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

.agent/context/20260907T221016Z-c04-recovery-matrix-integration.md

@@ -0,0 +1,78 @@
+# Session Context: C04 recovery matrix and integration
+
+## Date/time
+
+- UTC: 2026-09-07T22:10:16Z
+
+## User goal
+
+Implement Coder C milestone C04 and review the finished candidate with fresh
+FreePi processes using GLM 5.3.
+
+## Original prompt/request
+
+"C04 план начинай делать. Делай ревью через free pi glm5-3"
+
+## Assumptions
+
+- C02/C03 merged through PR #22 and are the complete simulator baseline for C04.
+- C04 remains package-local and zero-submit; live adapter replacement stays at Gate P4.
+
+## Plan
+
+1. Add the versioned recovery service and append-only evidence-command seam.
+2. Compose local, known-identity, Subgraph MCP, and advisor simulators behind public ports.
+3. Execute the complete C04 recovery matrix and publish replacement guidance.
+4. Run package/root checks, FreePi Gate A, draft PR CI, and FreePi Gate B.
+
+## Key decisions
+
+- Preserve deterministic safety-core authority; model and index outputs stay advisory.
+- Make duplicate delivery converge through deterministic record and command identities.
+
+## Files/components touched
+
+- `docs/COMPOSITION_MANIFEST.md`: updated reconciliation port reference to `RecoveryService` with Subgraph MCP adapter.
+- `docs/GATE_P4_CHECKLIST.md`: references `GATE_P4_RECOVERY_REPLACEMENT.md` and `RecoveryCommandStorePort`.
+- `packages/reconciliation`: recovery service, simulators, full pre-live matrix, schemas, and integration tests.
+- `.agent/context/20260907T221016Z-c04-recovery-matrix-integration.md`: this session record.
+
+## Commands/checks
+
+- `git fetch origin develop` - PASS.
+- Current `develop` rebased with PR #27 at `4295bd9c909d39bd750eed8d756ec4b0abe77958`.
+- `pnpm format:check` - PASS (Prettier 3.9.6).
+- `pnpm lint` - PASS (ESLint 10.10.0, 0 issues).
+- `pnpm typecheck` - PASS (TypeScript 6.0.3, 0 issues).
+- `pnpm check:generated` - PASS (contracts current).
+- `pnpm validate:fixtures` - PASS (9 fixtures validated).
+- `pnpm test` - PASS (35 test files, 504 tests passing; 66 in reconciliation package).
+- `npx markdownlint-cli2` - PASS (88 markdown files, 0 issues).
+- `git diff --check` - PASS (no whitespace or merge marker issues).
+
+## External-doc findings
+
+- None; C04 is a frozen simulator and integration milestone.
+
+## Unresolved questions
+
+- None.
+
+## Git and PR state
+
+- Branch: `milestone/c04-recovery-matrix-integration`
+- Base: `origin/develop` at `4295bd9c909d39bd750eed8d756ec4b0abe77958`
+- Commit: uncommitted
+- PR: not created
+- CI: not applicable
+
+## Review gates
+
+- Gate A: NOT RUN
+- Gate B: NOT RUN
+
+## Handoff/next steps
+
+1. Stage candidate files and capture candidate tree SHA (`git write-tree`).
+2. Run FreePi Gate A pre-push review with `npx free-pi-cli` (GLM 5.3).
+3. Commit, push branch, open draft PR, verify CI, then run FreePi Gate B.

docs/COMPOSITION_MANIFEST.md

@@ -36,7 +36,7 @@ All ports conform to frozen definitions in `@oneshot/contracts`:
 
 - **Settlement**: `ArcSettlementAdapter` (`@oneshot/privy-adapter`, owned by Coder B)
 - **Authorization**: `PrivyAuthorizationAdapter` (`@oneshot/privy-adapter`, owned by Coder B)
-- **Reconciliation**: Subgraph MCP Recovery Engine (`@oneshot/reconciliation-subgraph`, owned by Coder C)
+- **Reconciliation**: `RecoveryService` with a Subgraph MCP adapter (`@oneshot/reconciliation`, owned by Coder C)
 
 ## Environment Configuration
 

docs/GATE_P4_CHECKLIST.md

@@ -42,7 +42,9 @@ readiness probing they build on. See
    - Verify contract version `1.0.0`.
 
 3. **Replace Recovery Engine**:
-   - Wire `SubgraphMcpRecoveryEngine` into `reconcile_intent` task in `createTaskList`.
+   - Follow `packages/reconciliation/docs/GATE_P4_RECOVERY_REPLACEMENT.md`.
+   - Inject `RecoveryService` into the `reconcile_intent` task in `createTaskList`.
+   - Keep A-owned persistence behind `RecoveryCommandStorePort`; the recovery package does not write A tables.
 
 4. **Freeze the frontend boundary**:
    - Revalidate the A01 OpenAPI v1 artifact against the composed backend.

packages/reconciliation/README.md

@@ -12,6 +12,11 @@ variable.
 This package cannot submit or retry a settlement. It imports no domain,
 storage, Privy, or Arc implementation and exposes no `SettlementPort`.
 
+C04 adds a recovery service around the frozen source ports and deterministic
+safety core. It emits versioned, append-only observation and decision commands
+through `RecoveryCommandStorePort`; an A-owned consumer remains responsible for
+durable writes and state-version checks.
+
 ## Boundary
 
 The parser accepts the public MCP `CallToolResult` shape used by
@@ -50,10 +55,18 @@ The package participates in the root pnpm workspace and TypeScript project.
 - `src/simulator.ts`: credential-free deterministic Subgraph MCP scenarios.
 - `src/agent-simulator.ts`: C02 credential-free deterministic RecoveryAdvisorPort simulator.
 - `src/safety-core.ts`: C02 deterministic recovery safety core.
+- `src/service.ts`: C04 recovery job handler and evidence-command persistence seam.
+- `src/service-simulator.ts`: C04 A/B/MCP/model simulator composition and atomic dedupe store.
+- `src/recovery-matrix.ts`: C04 complete sanitized pre-live matrix runner and Markdown renderer.
 - `docs/recovery-action-matrix.md`: C02 four-action advisory and safety core disposition matrix.
 - `schemas/chaos-timeline-v1.schema.json`: C03 chaos timeline scenario schema.
 - `src/chaos/`: C03 cross-source failure injection harness, timeline DSL, and scenario runner.
 - `docs/CHAOS_MATRIX_REPORT.md`: C03 chaos scenario catalog and execution report.
 - `docs/ESCALATION_RUNBOOK.md`: C03 operator escalation runbook (strict no-blind-retry policy).
 - `docs/removal-value-matrix.md`: Graph removal/value comparison.
 - `docs/live-value-gate.md`: sanitized live MCP/agent spike protocol and current decision.
+- `schemas/recovery-command-pack-v1.schema.json`: append-only C04 command pack contract.
+- `docs/C04_RECOVERY_MATRIX_REPORT.md`: generated service and chaos matrix report.
+- `docs/C04_SIMULATOR_LOCK.md`: exact simulator identities and unlock conditions.
+- `docs/GATE_P4_RECOVERY_REPLACEMENT.md`: public-port replacement map and known live gaps.
+- `docs/SUBGRAPH_MCP_CHECKLIST.md`: deployment, freshness, data-boundary, and disable checks.