Files Changed: enforce mutation registry, contexts, and resource identity

[jeonghun-jj-lee]

Files Changed: enforce mutation registry, contexts, and resource identity

Important

Problem - No shared gate prevents a new file-mutating route from bypassing session provenance. Existing permissions classify paths lexically and do not carry root ownership, origin, endpoint identity, replay semantics, or a safe opaque-action alternative.
Approach - Introduce a versioned mutator registry, physical resource-identity service, and server-owned mutation contexts. Known local writers require a valid context; opaque actions use an endpoint-free uncertainty context only.
Scope - in: registry classes, context lifecycle, canonical resource identity, safe traversal, idempotency, replay, revocation, and opaque contexts. out: adoption by individual tools and UI surfaces.
Assumptions - Root lineage and bounded ledger storage are available from earlier slices.

Acceptance Criteria

• The registry classifies every supported route as ledger-backed, opaque-with-unknown-receipt, or explicitly out of scope.
• Raw session-visible storage adapters reject callers without a registered route and valid context.
• A context binds authenticated initiating panel, session, root, origin, exact operation, canonical source and destination identities, expiry, and idempotency semantics.
• Missing, expired, revoked, wrong-owner, wrong-endpoint, or invalid replayed contexts deny before filesystem access.
• An exact idempotent retry returns the original operation-group result without a second mutation.
• Resource identity safely handles existing targets, nonexistent leaves, aliases, symlinks, and provider capability limits; unsupported safe traversal denies known local mutation.
• An opaque context cannot authorize a known local write and emits only an operation-level Unknown Mutation Receipt with no resource identity or patch evidence.
• Capability discovery is distinct from context validation and can select legacy display only for unsupported protocol versions.

Testing Decisions

• Add table-driven context validation, replay, revocation, alias, symlink-race, and opaque-context coverage.
• Add a registry completeness test that rejects unregistered storage routes.

Key Decisions

• Authorization follows physical resource identity, not a lexical path string.
• Protocol discovery and mutation execution have separate fallback rules.

Constraints & Invariants

• Context capabilities never enter browser state, transcripts, logs, telemetry, sharing, or errors.
• A denied context must not create an evidence artifact or mutate storage.

Prior Art

• Parent Files Changed: full session-lineage mutation ledger #972
• Existing external directory permissions and reservation capabilities

Deliberation Resolution

• MutationContext is a discriminated union. A local context binds one or two canonical endpoints; an opaque context binds no local endpoint and can create only an Unknown Mutation Receipt. Endpoint requirements apply only to local contexts.
• operation_id is session-root-bound and independent of a context capability. A valid request with a new ID executes; the same ID plus identical normalized request returns the committed group result; the same ID plus a different request denies as replay. Expired, revoked, or wrong-owner contexts always deny before storage work.
• The normalized request consists of route ID, operation kind, canonical endpoint identities, declared resource kinds, root ID, and origin. Idempotent results remain available until root retention ends. safe_resolve returns a stable provider identity from a no-follow parent traversal, and no_follow_write verifies that identity again at write time; providers unable to guarantee both deny local mutation.
• A nonexistent endpoint is represented by the canonical identity of its nearest existing parent, normalized leaf name, and requested resource kind. A one-endpoint operation sets destination absent; a move sets both endpoints.
• The registry is a versioned generated manifest of all session-visible writer entry points. Static checks forbid direct use of protected storage adapters outside a registered adapter, and runtime checks require the matching route ID.
• A provider exposes safe_resolve and no_follow_write capability flags. A local context may execute only when both required flags are true; tests use a provider that returns false to prove denial before mutation.

Source

Part of #972. Blocked by #1075 and #1076.