feat(reconciliation): recovery matrix and simulator composition (C04)

[kapustazh]

Summary

Implements Milestone C04: Reconciliation recovery service, source simulator composition behind public ports, pre-live 36-scenario recovery matrix runner with zero external submissions, append-only persistence seam, and Gate P4 replacement guidance.

Scope and acceptance criteria

• The change is limited to the stated milestone or issue (C04).
• Acceptance criteria are listed and satisfied:
  • C04.1: Recovery service boundary & versioned evidence-command seam (RecoveryService, RecoveryJob, RecoveryCommandPack, append-only APPEND_RECOVERY_RECORD, atomic event-ID dedupe, fail-closed on schema/contract version mismatch).
  • C04.2: Source simulator composition behind public ports (SimulatorLocalRecoveryStatePort, SimulatorKnownIdentityEvidencePort, SimulatorSubgraphMcpRecoveryPort, RecoveryAgentSimulator, InMemoryRecoveryCommandStore, createRecoverySimulatorComposition).
  • C04.3: Pre-live recovery matrix execution with zero external submissions (36 scenarios: normal success, 4 advisor actions, duplicate delivery, 10 concurrent recovery workers, crash before submission, lost response after submission, service restart, full MCP degradation catalog, 3 contradiction scenarios, model failure/prose/timeout catalog; all 36 pass with externalSubmissionCount: 0).
  • C04.4: Public-port replacement guidance and simulator lock (GATE_P4_RECOVERY_REPLACEMENT.md, C04_SIMULATOR_LOCK.md, SUBGRAPH_MCP_CHECKLIST.md, documented EvidencePort envelope gap, COMPOSITION_MANIFEST.md, GATE_P4_CHECKLIST.md).
• No unrelated cleanup is included.

Product and security invariants

• Tenant isolation remains fail-closed.
• Sponsor authorization, auditability, and daily caps remain enforced where applicable.
• Recipients cannot modify sponsor controls or access sponsor-only data.
• No secret, token, production identifier, or personal data is committed or pasted into review prompts.
• Any non-applicable invariant is explained below.

Invariant notes:

• Structural zero-submit / zero-payment: RecoveryService has no payment submission mechanism; settlementPermission is strictly NEVER; MARK_COMMITTED commands require authoritative, bound Arc final proofs from the evidence port.
• Deduplication & idempotency: Atomic event-ID deduplication is enforced before reads and verified upon append. Concurrency testing proves 10 parallel recovery workers converge to exactly 1 command pack.
• Reconcile UNKNOWN without blind retry: Incomplete, missing, degraded, or contradictory inputs produce HOLD_UNKNOWN, ESCALATE_UNKNOWN, or READ_ONLY_LOOKUP with zero external submissions.
• Secrets and privacy boundary: Raw provider bodies and unvalidated metadata are rejected at the persistence boundary via key-based scanning and text sanitization.

Validation

Commands and results:

pnpm test (packages/reconciliation): PASS (4 test suites, 66 tests)
pnpm test (root full suite): PASS (35 test suites, 504 tests)
pnpm typecheck (tsc -b): PASS (0 errors)
pnpm lint: PASS (0 errors)
pnpm --filter @oneshot/contracts validate:fixtures: PASS (9 valid fixtures)
pnpm --filter @oneshot/reconciliation build: PASS
runRecoveryMatrix(): PASS (36/36 scenarios passed, all externalSubmissionCount: 0)
git diff --cached --check: PASS (clean)
markdownlint: PASS (88 files inspected, 0 errors)

Independent review evidence

Gate A — exact candidate tree before push

• Base commit SHA: 4295bd9c909d39bd750eed8d756ec4b0abe77958
• Candidate tree SHA: 45302a06def4d8afd0c3d008f94980009034723d
• Candidate commit SHA (if already committed but unpushed): 6f332f8628b1b09b8ead10f40423f462190e85ba
• Reviewer tool: free-pi-cli
• Reviewer model: glm-5.3-flash
• Verdict: VERDICT: PASS
• Findings or residual risks:
  • Blocking findings: None.
  • Non-blocking:
    1. packages/reconciliation/src/service.ts:496-506: On MCP_BOUNDARY_REJECTED sanitized index view flows to advisor input; safe today due to structural NON_AUTHORITATIVE_CANDIDATE_DISCOVERY, but guard/comment recommended for future hardening.
    2. packages/reconciliation/src/service-simulator.ts:52-66: InMemoryRecoveryCommandStore enforces atomic event-ID dedupe, while durable state-version CAS (expectedStateVersion) is delegated to the A-owned consumer per Gate P4 replacement guide.
    3. packages/reconciliation/src/recovery-matrix.ts:120-134: Ten-concurrent-workers row reports concurrentResults[0] in row display; vitest integration tests already assert exactly 1 PROCESSED across all 10 workers.
• The reviewed tree equals the committed tree (45302a06def4d8afd0c3d008f94980009034723d).

Gate B — exact remote PR head

• Pull request URL/number: feat(reconciliation): recovery matrix and simulator composition (C04) #29 (feat(reconciliation): recovery matrix and simulator composition (C04) #29)
• Remote head commit SHA: 6f332f8628b1b09b8ead10f40423f462190e85ba
• Remote head tree SHA: 45302a06def4d8afd0c3d008f94980009034723d
• Reviewer tool: free-pi-cli
• Reviewer model: glm-5.3-flash
• Verdict: VERDICT: PASS
• Findings or residual risks:
  • Blocking findings: None.
  • Non-blocking:
    1. packages/reconciliation/docs/C04_RECOVERY_MATRIX_REPORT.md: Prettier column padding alignment in committed markdown vs unpadded raw generator table; identical content.
    2. packages/reconciliation/src/recovery-matrix.ts:119-134: Ten-concurrent-workers row renders concurrentResults[0]; convergence proven by vitest suite.
    3. packages/reconciliation/src/service.ts:497-506: On MCP_BOUNDARY_REJECTED sanitized empty index view feeds advisor; safe today, explicit guard recommended at Gate P4.
    4. packages/reconciliation/src/service-simulator.ts:52-66: InMemoryRecoveryCommandStore dedupe is in-memory; durable expectedStateVersion CAS is delegated to Gate P4 consumer.
• Gate B reviewed the current remote head and matches Gate A's approved tree, or a fresh Gate A was run for the changed tree.
• Agent policy / repository-policy and all applicable CI checks pass:
  • repository-policy: PASS (run 34170405800)
  • ESLint and TypeScript: PASS (run 34170405836)
  • Markdown and Mermaid: PASS (run 34170405836)
  • Workers Builds (oneshot): PASS

Risk and rollback

• Residual risks:
  • Durable persistence atomicity and expectedStateVersion CAS remain in-memory until the real persistence adapter is connected at Gate P4.
  • EvidencePort in live B-lane does not currently return a full proof envelope; live replacement at Gate P4 requires B-side envelope enrichment as documented in GATE_P4_RECOVERY_REPLACEMENT.md.
  • All live external effects (Privy, Arc, Subgraph MCP, model) remain unproven by design under the C04 simulator lock; unlocking is gated on Gate P4 proofs.
• Rollback or recovery plan:
  • Purely additive recovery package additions and documentation. Can be cleanly reverted via git revert 6f332f8628b1b09b8ead10f40423f462190e85ba without breaking existing lane A or B functionality.

Human merge

• A human owner has reviewed the evidence and will perform the merge.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	oneshot	6f332f8	Sep 07 2026, 11:33 PM