refactor(storage): own structured mutation commit effects

[Jurij89]

Summary

• Move structured-mutation graph-effect interpretation behind one pure Storage-owned effect snapshot.
• Capture the canonical touched graph set and structural no-op classification before the first await, so caller mutation cannot redirect cache invalidation after a backend commit.
• Keep execution in the existing Agent invalidation wrapper and apply effects only after successful potentially-mutating operations; structural no-ops and failures do not churn the Context Graph projection cache.
• Keep the existing structuredMutation capability and public helper exports intact; this adds no callback runner, capability protocol, wrapper layer, scheduler work, or background component.

Related Work

• Fixes refactor(storage): keep structured mutation effects behind storage ownership #2188
• Part of Reconnect-triggered background sync amplification can starve foreground catch-up #2052
• Stacked on security(storage): close leased raw SPARQL mutation routes #2187
• Depends on refactor(storage): migrate exact managed mutations #2185
• Execution plan: agent-docs/plans/2026-08-09-system-record-followup-refactors.md

Data Flow

sequenceDiagram
    participant A as Agent cache wrapper
    participant S as Pure Storage effect model
    participant B as Structured mutation backend
    A->>S: capture effects from mutation
    S-->>A: frozen scope and no-op classification
    A->>B: execute original mutation with original receiver/options
    alt commit succeeds and may mutate
        B-->>A: success
        A->>A: invalidate list and touched projections
    else structural no-op or failure
        B-->>A: no-op success or error
        A->>A: no cache effect
    end

Loading

Files Changed

Area	Change
packages/storage/src/bounded-structured-mutation.ts	Adds the pure immutable effect snapshot and its contract.
packages/storage/src/index.ts	Exports the Storage-owned snapshot while retaining existing public helpers.
packages/agent/src/dkg-agent-base.ts	Consumes the snapshot without decoding the mutation vocabulary and retains execution ownership.
packages/storage/test/bounded-structured-mutation.test.ts	Covers all six mutation kinds, structural no-op classification, immutability, and caller mutation after capture.
packages/agent/test/replace-subject-agent-wrapper.test.ts	Proves success-only invalidation, original graph scope, exact options forwarding, and bound receiver semantics.

Test Plan

• Dependency-aware Agent build, including Core, Storage, Query, Chain, Publisher, Random Sampling, Agent type tests, and package-root checks
• Storage and Agent builds after the review simplification
• bounded-structured-mutation.test.ts: 19 passed
• replace-subject-agent-wrapper.test.ts: 4 passed
• All six structured mutation variants capture the same target graph as before
• Structural no-op and failed mutation paths produce no cache invalidation
• Caller mutation after dispatch cannot redirect the captured effect
• Agent forwards the exact options object and invokes the inner method with its store receiver
• git diff --check; generated EVM deployment output restored before commit

[otReviewAgent]

Review Agent completed this review and found no issues.