Shadow Sweep (plan → commit)

A Shadow Sweep plan is created from metadata, hashes, manifests and provider revision identifiers (Gmail historyId, Drive changes tokens, Graph delta links, Dropbox cursors, ETags). It never mutates provider state, and it never copies payloads to preview.

Contents

Field	Meaning
objects[]	selected assets with expectedVersion, expectedSizeBytes, expectedSha256, actions and preservationElected
excluded[]	objects the planner refused (low confidence, policy exclusion, protected by rule, unsupported capability, over grant limit, recent, shared)
sourceMarkers[]	provider-native concurrency markers at planning time
projection	bytes to preserve/remove/transfer, projected reclaim, projected post-action quota per source
destination	for restore/migrate: destination, metadata/permission mapping, known lossiness
policy	Action Authorization evaluation summary and required approvals
meter	rating preview against the current rate card and the standing envelope
hash	SHA-256 over the material fields: objects, actions, destination, intent, actor, estimated price
expiresAt	plans expire (default 60 minutes)

Lifecycle

draft → validated → authorized → committing → committed → executed | partially_executed, or stale | expired | rejected | cancelled.

Optimistic concurrency

POST /v1/plans/{id}/validate re-reads current object versions. Any object that is missing, changed version, changed size or hash, or already trashed marks the plan stale. Source-level marker drift alone (new mail arriving) is not material.

Authorization records planHashAtAuthorization. POST /v1/plans/{id}/commit verifies, in order: plan state is authorized; current hash equals both the plan hash and the hash at authorization; not expired; not stale; action decision is allow; commercial authorization exists when the plan is billable. Any failure returns a 409 (plan_stale, plan_expired, plan_hash_mismatch, plan_state_conflict) or 403 (action_denied, step_up_required) or 402 (commercial_authorization_required).

If a material field changes after authorization (the price, the objects), the hash changes and commit fails with plan_hash_mismatch: re-authorize.

AI and plans

AI may propose selections or explain a plan (sweep_explain_plan in MCP). It cannot bypass validation, policy, authorization or the commit gate.