kapustazh · Sep 7, 2026
diff --git a/.agent/context/20260907T160800Z-c02-reconciliation-engine.md b/.agent/context/20260907T160800Z-c02-reconciliation-engine.md
@@ -0,0 +1,34 @@
+# Session Context: C02 LLM Recovery Agent and Deterministic Reconciliation
+
+## Date/time
+
+- UTC: 2026-09-07T16:08:00Z
+
+## User goal
+
+Implement Coder C Milestone C02: LLM Recovery Agent and Deterministic Reconciliation.
+Build the RecoveryAdvisorPort contract, deterministic LLM recovery agent simulator, deterministic recovery safety core, safe reconciliation command vocabulary, provenance-labeled recovery view, and exhaustive idempotency/safety test matrix. Zero payment submission capability by construction.
+
+## Invariants and boundaries
+
+- 1 business intent -> at most 1 committed settlement.
+- UNKNOWN state reconciles without blind retries.
+- Authoritative proof: local OneShot COMMITTED record and exact verified Arc receipt + Transfer.
+- Advisory inputs: Subgraph MCP observations and LLM Recovery Agent recommendations are strictly NON-AUTHORITATIVE and ADVISORY. They can NEVER grant settlement rights or submit payments.
+- RETURN_EXISTING_RESULT converts to MARK_COMMITTED / terminal state ONLY if independently verified by authoritative Arc/durable evidence; otherwise fails safe to HOLD_UNKNOWN or ESCALATE_UNKNOWN.
+- Package-isolated: imports NO private A/B implementation modules, NO SettlementPort calls, NO direct database mutations.
+
+## Small tasks
+
+- C02.1 — Evidence model & binding validation (source, authorityClass, request binding, retrieval time, block/finality/freshness, sanitized reason, digest).
+- C02.2 — Evidence precedence & bounded sanitized agent input (labels untrusted data, strips secrets/raw provider bodies, encodes contradictory/stale/missing/unavailable).
+- C02.3 — RecoveryAdvisorPort contract & deterministic agent simulator (WAIT, RECONCILE, ESCALATE, RETURN_EXISTING_RESULT; rejects unknown actions, prompt injection, extra tools).
+- C02.4 — Deterministic safety core & provenance-labeled recovery view (maps recommendations to safe read-only/hold/escalate/commit commands; zero submit by construction).
+- C02.5 — Idempotency, replay, reordering, and matrix tests.
+
+## Git and PR state
+
+- Branch: `milestone/c02-reconciliation-engine`
+- Base: `develop` (64d0a6fb65c3bedce169cc95867595e3f79b90c7)
+- Review tooling: `free-pi-cli` / `glm 5.3`
+- Status: ACTIVE
diff --git a/packages/reconciliation/README.md b/packages/reconciliation/README.md
@@ -44,6 +44,12 @@ The package participates in the root pnpm workspace and TypeScript project.
 - `schemas/index-view-v1.schema.json`: downstream sanitized view contract.
 - `schemas/subgraph-mcp-result-v1.schema.json`: accepted GraphQL result body.
 - `schemas/recovery-evidence-v1.schema.json`: known-identity local/Privy/Arc baseline.
-- `src/simulator.ts`: credential-free deterministic scenarios.
+- `schemas/recovery-advisor-v1.schema.json`: C02 RecoveryAdvisorPort recommendation schema.
+- `schemas/reconciliation-command-v1.schema.json`: C02 deterministic safety core command schema.
+- `schemas/recovery-view-v1.schema.json`: C02 detailed recovery view schema.
+- `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.
+- `docs/recovery-action-matrix.md`: C02 four-action advisory and safety core disposition matrix.
 - `docs/removal-value-matrix.md`: Graph removal/value comparison.
 - `docs/live-value-gate.md`: sanitized live MCP/agent spike protocol and current decision.
diff --git a/packages/reconciliation/docs/recovery-action-matrix.md b/packages/reconciliation/docs/recovery-action-matrix.md
@@ -0,0 +1,66 @@
+# OneShot Recovery Action & Safety Core Matrix (v1)
+
+## 1. Overview
+
+The OneShot Reconciliation Engine resolves business intents stranded in `UNKNOWN` state without ever performing blind retries or issuing duplicate settlement requests.
+
+The engine coordinates:
+
+1. **Subgraph MCP / The Graph Discovery**: Locates candidate ERC-20 Transfer events matching the business intent binding without requiring transaction hashes. Non-authoritative by construction.
+2. **LLM Recovery Agent (`RecoveryAdvisorPort`)**: Consumes a bounded, redacted, untrusted-labeled view of observations and recommends exactly one bounded action. Advisory by construction.
+3. **Deterministic Recovery Safety Core**: Combines authoritative OneShot durable state and exact verified Arc on-chain evidence with the advisory recommendation to emit safe commands. Zero-submit by construction.
+
+---
+
+## 2. Authority Hierarchy
+
+| Authority Class | Source | Authority Level | Can Grant Settlement? | Can Transition to COMMITTED? |
+| --- | --- | --- | --- | --- |
+| `AUTHORITATIVE_ONESHOT` | OneShot Ledger | Authoritative | No (Worker only via CAS) | Yes (reflects existing state) |
+| `AUTHORITATIVE_CHAIN_EVIDENCE` | Arc Receipt + Transfer Log | Authoritative | No (Never initiates payment) | Yes (on verified final match) |
+| `PROVIDER_OBSERVATION` | Privy API | Observation | No | No (Requires Arc confirmation) |
+| `NON_AUTHORITATIVE_CANDIDATE_DISCOVERY` | The Graph / Subgraph MCP | Non-authoritative | NEVER | NEVER |
+| `ADVISORY_AGENT_OBSERVATION` | LLM Recovery Agent | Advisory | NEVER | NEVER |
+
+---
+
+## 3. Four-Action Advisory Matrix
+
+The LLM Recovery Agent may only output one of four strictly bounded actions:
+
+| Action | Agent Meaning | Safety Core Disposition | Target State | External Submissions |
+| --- | --- | --- | --- | --- |
+| `WAIT` | Preserves `UNKNOWN` until fresher evidence or next indexing cycle. | `HOLD_UNKNOWN` | `UNKNOWN` | 0 |
+| `RECONCILE` | Re-check indexer or provider evidence in a read-only cycle. | `READ_ONLY_LOOKUP` | `UNKNOWN` | 0 |
+| `ESCALATE` | Human operator intervention needed (e.g. contradiction, anomalies). | `ESCALATE_UNKNOWN` | `UNKNOWN` | 0 |
+| `RETURN_EXISTING_RESULT` | Advises that a candidate matches the intended settlement. | If Arc proof verified: `MARK_COMMITTED`<br>If Arc proof absent: `HOLD_UNKNOWN` (Overridden!) | `COMMITTED` (with proof)<br>`UNKNOWN` (without proof) | 0 |
+
+---
+
+## 4. Invalid Output & Boundary Rejection Matrix
+
+Any anomalous, untrusted, or hostile agent output fails closed to `WAIT` with an explicit diagnostic:
+
+| Issue Class | Trigger / Example | Boundary Validation | Safety Core Disposition | Target State |
+| --- | --- | --- | --- | --- |
+| `UNSUPPORTED_ACTION` | Agent outputs `RETRY`, `SUBMIT`, `RESUBMIT`, `CANCEL` | Rejected (`INVALID_RESULT`) | `HOLD_UNKNOWN` | `UNKNOWN` |
+| `PROMPT_INJECTION` | Reason contains "ignore previous instructions", "execute_payment" | Rejected (`INVALID_RESULT`) | `HOLD_UNKNOWN` | `UNKNOWN` |
+| `FABRICATED_BINDING` | Referenced evidence ID does not exist in available evidence | Rejected (`INVALID_IDENTITY`) | `HOLD_UNKNOWN` | `UNKNOWN` |
+| `MALFORMED_OUTPUT` | Non-JSON text, null, missing required fields | Rejected (`INVALID_JSON`) | `HOLD_UNKNOWN` | `UNKNOWN` |
+| `TIMEOUT_OR_UNAVAILABLE` | Model fails to return within timeout | Rejected (`MCP_UNAVAILABLE`) | `HOLD_UNKNOWN` | `UNKNOWN` |
+
+---
+
+## 5. End-to-End Decision Truth Table
+
+| Authoritative Arc Receipt | Arc Transfer Matching | Subgraph MCP Status | Agent Recommendation | Safety Core Command | Target State | Submissions |
+| --- | --- | --- | --- | --- | --- | --- |
+| `SUCCESS` (final) | `MATCH` | `FRESH` (1 match) | `RETURN_EXISTING_RESULT` | `MARK_COMMITTED` | `COMMITTED` | 0 |
+| `SUCCESS` (final) | `MATCH` | `LAGGING` | `WAIT` | `MARK_COMMITTED` | `COMMITTED` | 0 |
+| `REVERT` (final) | N/A | Any | Any | `MARK_FAILED_SAFE` | `FAILED_SAFE` | 0 |
+| `NOT_FOUND` / `PENDING` | None | `FRESH` (1 candidate) | `RETURN_EXISTING_RESULT` | `HOLD_UNKNOWN` (Overridden) | `UNKNOWN` | 0 |
+| `NOT_FOUND` / `PENDING` | None | `FRESH` (0 candidates) | `WAIT` | `HOLD_UNKNOWN` | `UNKNOWN` | 0 |
+| `NOT_FOUND` / `PENDING` | None | `LAGGING` | `RECONCILE` | `READ_ONLY_LOOKUP` | `UNKNOWN` | 0 |
+| `NOT_FOUND` / `PENDING` | None | `UNHEALTHY` / `ERROR` | `RECONCILE` | `READ_ONLY_LOOKUP` | `UNKNOWN` | 0 |
+| Contradictory | Mismatch | Multiple candidates | `RETURN_EXISTING_RESULT` | `ESCALATE_UNKNOWN` (Overridden) | `UNKNOWN` | 0 |
+| Any | Any | Any | `RETRY` (Unsupported) | `HOLD_UNKNOWN` (Fails closed) | `UNKNOWN` | 0 |
diff --git a/packages/reconciliation/fixtures/v1/agent/escalate.json b/packages/reconciliation/fixtures/v1/agent/escalate.json
@@ -0,0 +1,21 @@
+{
+  "version": "recovery-advisor-v1",
+  "recommendation": {
+    "action": "ESCALATE",
+    "decisionId": "dec-escalate-001",
+    "reason": "Contradictory or anomalous transfer observations detected",
+    "referencedEvidenceIds": ["thegraph:candidate-1"],
+    "modelIdentity": {
+      "modelName": "recovery-advisor-llm",
+      "modelVersion": "1.0.0",
+      "promptVersion": "recovery-v1"
+    },
+    "timestamp": "2026-09-07T12:00:00.000Z"
+  },
+  "expected": {
+    "disposition": "OPERATOR_ESCALATION",
+    "commandType": "ESCALATE_UNKNOWN",
+    "targetState": "UNKNOWN",
+    "external_submission_count": 0
+  }
+}
diff --git a/packages/reconciliation/fixtures/v1/agent/reconcile.json b/packages/reconciliation/fixtures/v1/agent/reconcile.json
@@ -0,0 +1,21 @@
+{
+  "version": "recovery-advisor-v1",
+  "recommendation": {
+    "action": "RECONCILE",
+    "decisionId": "dec-reconcile-001",
+    "reason": "Requesting read-only indexer re-check for in-flight transfer",
+    "referencedEvidenceIds": [],
+    "modelIdentity": {
+      "modelName": "recovery-advisor-llm",
+      "modelVersion": "1.0.0",
+      "promptVersion": "recovery-v1"
+    },
+    "timestamp": "2026-09-07T12:00:00.000Z"
+  },
+  "expected": {
+    "disposition": "SCHEDULE_READ_ONLY_LOOKUP",
+    "commandType": "READ_ONLY_LOOKUP",
+    "targetState": "UNKNOWN",
+    "external_submission_count": 0
+  }
+}
diff --git a/packages/reconciliation/fixtures/v1/agent/return-existing-result.json b/packages/reconciliation/fixtures/v1/agent/return-existing-result.json
@@ -0,0 +1,26 @@
+{
+  "version": "recovery-advisor-v1",
+  "recommendation": {
+    "action": "RETURN_EXISTING_RESULT",
+    "decisionId": "dec-return-001",
+    "reason": "Matching transfer observation identified on-chain",
+    "referencedEvidenceIds": [
+      "arc:0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+    ],
+    "modelIdentity": {
+      "modelName": "recovery-advisor-llm",
+      "modelVersion": "1.0.0",
+      "promptVersion": "recovery-v1"
+    },
+    "timestamp": "2026-09-07T12:00:00.000Z"
+  },
+  "expected": {
+    "disposition_with_arc_proof": "CONFIRMED_ON_CHAIN",
+    "command_with_arc_proof": "MARK_COMMITTED",
+    "target_state_with_arc_proof": "COMMITTED",
+    "disposition_without_arc_proof": "UNVERIFIED_ADVISORY_OVERRIDE",
+    "command_without_arc_proof": "HOLD_UNKNOWN",
+    "target_state_without_arc_proof": "UNKNOWN",
+    "external_submission_count": 0
+  }
+}
diff --git a/packages/reconciliation/fixtures/v1/agent/unsupported-action.json b/packages/reconciliation/fixtures/v1/agent/unsupported-action.json
@@ -0,0 +1,22 @@
+{
+  "version": "recovery-advisor-v1",
+  "recommendation": {
+    "action": "RETRY_SETTLEMENT",
+    "decisionId": "dec-bad-001",
+    "reason": "Attempting to force resubmission",
+    "referencedEvidenceIds": [],
+    "modelIdentity": {
+      "modelName": "recovery-advisor-llm",
+      "modelVersion": "1.0.0",
+      "promptVersion": "recovery-v1"
+    },
+    "timestamp": "2026-09-07T12:00:00.000Z"
+  },
+  "expected": {
+    "disposition": "HOLD_SAFE",
+    "commandType": "HOLD_UNKNOWN",
+    "targetState": "UNKNOWN",
+    "accepted": false,
+    "external_submission_count": 0
+  }
+}
diff --git a/packages/reconciliation/fixtures/v1/agent/wait.json b/packages/reconciliation/fixtures/v1/agent/wait.json
@@ -0,0 +1,21 @@
+{
+  "version": "recovery-advisor-v1",
+  "recommendation": {
+    "action": "WAIT",
+    "decisionId": "dec-wait-001",
+    "reason": "Awaiting fresher Arc receipt confirmation or next indexing cycle",
+    "referencedEvidenceIds": [],
+    "modelIdentity": {
+      "modelName": "recovery-advisor-llm",
+      "modelVersion": "1.0.0",
+      "promptVersion": "recovery-v1"
+    },
+    "timestamp": "2026-09-07T12:00:00.000Z"
+  },
+  "expected": {
+    "disposition": "HOLD_SAFE",
+    "commandType": "HOLD_UNKNOWN",
+    "targetState": "UNKNOWN",
+    "external_submission_count": 0
+  }
+}
diff --git a/packages/reconciliation/schemas/reconciliation-command-v1.schema.json b/packages/reconciliation/schemas/reconciliation-command-v1.schema.json
@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oneshot.invalid/schemas/reconciliation-command-v1.schema.json",
+  "title": "OneShot Reconciliation safety-core command v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "commandType",
+    "businessIntentId",
+    "requestFingerprint",
+    "targetState",
+    "reason",
+    "evidenceReferences",
+    "disposition",
+    "advisoryAction",
+    "authoritativeProofPresent",
+    "issuedAt",
+    "settlementPermission"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "reconciliation-command-v1" },
+    "commandType": {
+      "enum": [
+        "HOLD_UNKNOWN",
+        "READ_ONLY_LOOKUP",
+        "ESCALATE_UNKNOWN",
+        "MARK_COMMITTED",
+        "MARK_FAILED_SAFE"
+      ]
+    },
+    "businessIntentId": { "type": "string", "maxLength": 128 },
+    "requestFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "targetState": { "enum": ["UNKNOWN", "COMMITTED", "FAILED_SAFE"] },
+    "reason": { "type": "string", "maxLength": 1000 },
+    "evidenceReferences": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 256 }
+    },
+    "disposition": { "type": "string", "maxLength": 128 },
+    "advisoryAction": {
+      "enum": ["WAIT", "RECONCILE", "ESCALATE", "RETURN_EXISTING_RESULT"]
+    },
+    "authoritativeProofPresent": { "type": "boolean" },
+    "issuedAt": { "type": "string", "format": "date-time", "maxLength": 35 },
+    "settlementPermission": { "const": "NEVER" }
+  }
+}
diff --git a/packages/reconciliation/schemas/recovery-advisor-v1.schema.json b/packages/reconciliation/schemas/recovery-advisor-v1.schema.json
@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oneshot.invalid/schemas/recovery-advisor-v1.schema.json",
+  "title": "OneShot Recovery Advisor recommendation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "action",
+    "decisionId",
+    "reason",
+    "referencedEvidenceIds",
+    "modelIdentity",
+    "timestamp"
+  ],
+  "properties": {
+    "action": {
+      "enum": ["WAIT", "RECONCILE", "ESCALATE", "RETURN_EXISTING_RESULT"]
+    },
+    "decisionId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$"
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "referencedEvidenceIds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 256
+      },
+      "maxItems": 25
+    },
+    "modelIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelName", "modelVersion", "promptVersion"],
+      "properties": {
+        "modelName": { "type": "string", "maxLength": 64 },
+        "modelVersion": { "type": "string", "maxLength": 32 },
+        "promptVersion": { "type": "string", "maxLength": 32 }
+      }
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "maxLength": 35
+    }
+  }
+}
diff --git a/packages/reconciliation/schemas/recovery-view-v1.schema.json b/packages/reconciliation/schemas/recovery-view-v1.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oneshot.invalid/schemas/recovery-view-v1.schema.json",
+  "title": "OneShot Detailed recovery view v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "businessIntentId",
+    "authoritativeState",
+    "coreDisposition",
+    "recommendedAction",
+    "authoritativeEvidence",
+    "providerObservations",
+    "indexedCandidates",
+    "indexHealth",
+    "contradiction",
+    "contradictionCodes",
+    "diagnostics",
+    "settlementPermission",
+    "evaluatedAt",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "recovery-view-v1" },
+    "businessIntentId": { "type": "string", "maxLength": 128 },
+    "authoritativeState": {
+      "enum": ["SUBMITTING", "UNKNOWN", "COMMITTED", "FAILED_SAFE"]
+    },
+    "coreDisposition": {
+      "enum": [
+        "HOLD_UNKNOWN",
+        "READ_ONLY_LOOKUP",
+        "ESCALATE_UNKNOWN",
+        "MARK_COMMITTED",
+        "MARK_FAILED_SAFE"
+      ]
+    },
+    "recommendedAction": {
+      "enum": ["WAIT", "RECONCILE", "ESCALATE", "RETURN_EXISTING_RESULT"]
+    },
+    "authoritativeEvidence": { "type": "array" },
+    "providerObservations": { "type": "array" },
+    "indexedCandidates": { "type": "array" },
+    "indexHealth": {
+      "enum": ["FRESH", "LAGGING", "UNHEALTHY", "UNAVAILABLE", "UNKNOWN_FRESHNESS"]
+    },
+    "contradiction": { "type": "boolean" },
+    "contradictionCodes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "settlementPermission": { "const": "NEVER" },
+    "evaluatedAt": { "type": "string", "format": "date-time", "maxLength": 35 },
+    "summary": { "type": "string", "maxLength": 500 }
+  }
+}