Files Changed: adopt engine-owned mutation routes

[jeonghun-jj-lee]

Files Changed: adopt engine-owned mutation routes

Important

Problem - Built-in editing tools and direct server file routes use incompatible metadata and lifecycle paths. Some emit diffs, some emit only file lists, and some can mutate without a session-bound provenance record.
Approach - Route engine-owned writes, edits, patches, moves, deletes, implicit parent creation, formatting effects, and direct file APIs through the mutation gate. Shell, MCP, and custom routes emit declared receipts or explicit unknown-operation receipts.
Scope - in: engine tools and server file routes, multi-resource groups, formatter effects, recursive partial outcomes, and opaque tool handling. out: extension, plugin, runner, and UI adoption.
Assumptions - The registry, context, ledger, evidence, and privacy slices are available.

Acceptance Criteria

• Every engine-owned file mutation uses a registered context and operation group.
• Multi-file patches, moves, deletes, and formatter side effects publish one receipt per declared resource with partial outcomes where physical work is non-atomic.
• Newly created implicit parent directories are declared and receipted before creation.
• Recursive operations preflight their resource budget and either complete with full accounting or deny before mutation.
• Direct server file APIs cannot mutate session-visible storage without a valid context.
• Shell, MCP, and custom routes with declared resources produce ordinary receipts; otherwise they produce a dedicated unknown-operation receipt.
• Existing tool output can remain readable without serving as ownership authority.

Testing Decisions

• Extend tool and server-route tests for context validation, group lifecycle, moves, deletes, formatting, parent creation, recursive budgets, and opaque fallback.
• Add integration cases proving a preflight denial or pre-write failure leaves no applied resource receipt, while an execution-time failure preserves declared resource receipts with explicit partial statuses.

Key Decisions

• Tool metadata becomes presentation detail; the ledger is ownership authority.
• Physical non-atomicity is represented as explicit partial outcomes rather than hidden rollback assumptions.

Constraints & Invariants

• No known local engine mutator silently falls back to untracked behavior.
• No opaque operation fabricates a resource diff.

Prior Art

• Parent Files Changed: full session-lineage mutation ledger #972
• Existing write, edit, patch, shell, and direct-file pathways

Deliberation Resolution

• Every requested action creates an operation group. A preflight denial or failure before the first physical write produces a group with no applied resource receipt; an execution-time failure preserves intent receipts and marks each affected resource applied, failed, or not_started within a partial group.
• A denial before resource declaration has no resource receipt. A pre-write failure after declaration retains only not_started intent receipts and no applied resource receipt.
• This slice consumes the generated mutator registry and resource-identity contract from Files Changed: enforce mutation registry, contexts, and resource identity #1077. Moves have source and destination identities, implicit parents are declared before creation, and formatter effects are added as declared resources before commit.
• Recursive preflight snapshots the enumerated resource set and budget reservation. A concurrent enumeration change or post-preflight failure yields explicit partial outcomes; a preflight budget overflow denies before mutation.
• Full accounting includes every declared resource with an applied, failed, or not_started execution status; it does not imply that all declared resources completed successfully.
• A declared-resource opaque tool must submit a complete normalized endpoint set and then uses local receipt semantics. An undeclared or incomplete opaque declaration produces one Unknown Mutation Receipt and cannot produce a resource diff.

Source

Part of #972. Blocked by #1077 and #1078.