feat(reconciliation): add C01 recovery evidence contract

.agent/context/20260907T130620Z-c01-recovery-evidence-strategy.md

@@ -0,0 +1,77 @@
+# Session Context: C01 recovery evidence strategy
+
+## Date/time
+
+- UTC: 2026-09-07T13:06:20Z
+
+## User goal
+
+Implement the Coder C milestone sequence, starting with C01, so OneShot has a provider-neutral, fail-closed recovery evidence contract before any live Subgraph MCP adapter is admitted.
+
+## Original prompt/request
+
+Reply in English and keep responses concise. Work as Coder C on the milestones under `milestones/coder-c`, create a new branch from `develop`, begin coding, use existing `.agent/research` on Subgraph MCP, and perform additional Graph research when needed. Stop and ask if a material requirement is unclear.
+
+## Assumptions
+
+- C01 is the first implementation scope; later C milestones remain out of this branch.
+- Offline contract mode is sufficient for local implementation. Missing live deployment/model credentials must remain an explicit evidence gap and cannot be represented as sponsor qualification.
+- The Graph, Subgraph MCP, and any future model output remain non-authoritative and cannot grant settlement or retry permission.
+- C01 is integrated into Coder A's pnpm workspace scaffold now present on `develop`.
+
+## Plan
+
+1. Freeze `index-view-v1` provider-neutral evidence and MCP boundary schemas.
+2. Add strict runtime validation, deterministic fixtures, and simulator coverage for healthy and degraded observations.
+3. Publish the removal/value matrix, live-spike protocol, safe fallback decision, and package-local verification commands.
+4. Run format, lint, type, test, and build checks; inspect scope and record results.
+
+## Key decisions
+
+- Branch from the verified current `develop` SHA using the milestone-prescribed branch name.
+- Keep C01 in `packages/reconciliation`; do not create `packages/subgraph-mcp-adapter` or `subgraph/` until a live deployment passes the value gate.
+- Pin immutable deployment/query identity in the contract and reject unknown fields or missing `_meta` freshness instead of trusting generic MCP output.
+- Follow B01/B02's direct USDC transfer decision: production correlation is sender/token/recipient/amount plus a bounded block window; `memo_id` is unused.
+
+## Files/components touched
+
+- `.agent/context/20260907T130620Z-c01-recovery-evidence-strategy.md` - active C01 decisions and evidence.
+- `packages/reconciliation` - implemented standalone `index-view-v1`, known-identity evidence schema, strict MCP boundary, deterministic simulator, 24 tests, and live-value decision docs.
+
+## Commands/checks
+
+- `git fetch origin develop` - passed; branch rebased to `c3ab0ca5faba435f4ca8275f6e60c08e877b97b0`.
+- Required repository policy, implementation loop, security/sponsor rules, test matrix, Coder C milestones, and repo skills read before editing.
+- Official The Graph documentation checked on 2026-09-07 for immutable deployment query tools and `_meta` fields.
+- Package-local Prettier check - passed.
+- Package-local ESLint 10.0.1 strict typed lint - passed.
+- TypeScript 6.0.3 strict typecheck and build - passed on Node 24.19.0.
+- Vitest 5.0.0 - 24 tests passed; fresh/empty/lagging/unhealthy/unavailable/malformed/injected/duplicate/out-of-order/contradictory and identity-drift cases covered with zero settlement permission.
+
+## External-doc findings
+
+- The Graph Subgraph MCP introduction and `graphops/subgraph-mcp` README, checked 2026-09-07: use a deployment-pinned execute-query tool; the MCP server returns structured Subgraph results and is not an LLM.
+- The Graph GraphQL API docs, checked 2026-09-07: `_meta` exposes deployment, indexed block number/hash/timestamp, and `hasIndexingErrors`; C01 validates these as non-authoritative health/freshness evidence.
+- The Graph supported-network registry, checked 2026-09-07: Arc Testnet is supported under `arc-testnet` and chain ID `eip155:5042002`, so a live OneShot/Arc Subgraph is feasible.
+
+## Unresolved questions
+
+- The repository contains no immutable OneShot/Arc deployment ID, Subgraph MCP connection, model access, or deployment credentials. The user authorized a new deployment if needed, but credential entry remains a human setup dependency. Until those inputs exist, the production adapter remains unadmitted and the safe mode is `FALLBACK_DIRECT_RECOVERY`.
+
+## Git and PR state
+
+- Branch: `milestone/c01-recovery-evidence-strategy`
+- Base: `develop` at `c3ab0ca5faba435f4ca8275f6e60c08e877b97b0`
+- Commit: uncommitted
+- PR: not created
+- CI: not run
+
+## Review gates
+
+- Gate A: NOT RUN
+- Gate B: NOT RUN
+
+## Handoff/next steps
+
+1. Resolve the live deployment/configuration choice, then run the C01 live MCP/agent value gate or retain the explicit fallback.
+2. Stage the exact candidate, run Gate A, and continue the implementation loop only after the decision is reflected in code and evidence.

packages/reconciliation/README.md

@@ -0,0 +1,49 @@
+# `@oneshot/reconciliation`
+
+`index-view-v1` is C01's provider-neutral recovery evidence contract. It turns
+a deployment-pinned Subgraph MCP query result into a bounded, sanitized,
+non-authoritative candidate view.
+
+B01/B02 establish direct USDC ERC-20 `transfer` as the v1 settlement shape.
+The production lookup therefore uses sender/token/recipient/amount plus a
+bounded block window. `memo_id` is not sent by v1 settlement and is not a query
+variable.
+
+This package cannot submit or retry a settlement. It imports no domain,
+storage, Privy, or Arc implementation and exposes no `SettlementPort`.
+
+## Boundary
+
+The parser accepts the public MCP `CallToolResult` shape used by
+`execute_query_by_deployment_id`: exactly one text content block containing a
+GraphQL JSON response. It validates byte limits before parsing and then checks:
+
+- expected MCP server, tool, immutable deployment, query digest, and variables;
+- a strict OneShot candidate schema and bounded candidate count;
+- `_meta.deployment`, indexed block identity/time, and indexing-error state;
+- chain-head lag and exact intent/request/correlation bindings;
+- duplicate, out-of-order, mismatched, and contradictory observations.
+
+Invalid, oversized, unavailable, injected, stale, or contradictory input
+produces a fail-closed view. Empty data means only “not observed through block
+N.” No output grants permission to pay.
+
+## Verify
+
+From this directory:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+The package participates in the root pnpm workspace and TypeScript project.
+
+## Artifacts
+
+- `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.
+- `docs/removal-value-matrix.md`: Graph removal/value comparison.
+- `docs/live-value-gate.md`: sanitized live MCP/agent spike protocol and current decision.

packages/reconciliation/docs/live-value-gate.md

@@ -0,0 +1,41 @@
+# C01 live Subgraph MCP value gate
+
+## Current decision
+
+`FALLBACK_DIRECT_RECOVERY` (provisional until the live promotion protocol passes)
+
+No immutable OneShot/Arc Subgraph deployment, approved Gateway connection, or
+sanitized live model trace exists in the repository as of 2026-09-07. The
+production adapter and `subgraph/` are therefore not admitted. This is a safe
+capability fallback, not evidence that The Graph failed technically.
+
+Known-identity Privy/Arc recovery remains available. Automatic hashless
+discovery through Subgraph MCP is unavailable, and The Graph qualification is
+`NOT VERIFIED`.
+
+B01/B02 define v1 settlement as a direct USDC ERC-20 `transfer`. The live query
+must bind sender, token, recipient, amount, and a bounded block window. It must
+not rely on `memo_id`, because the approved settlement path does not emit one.
+
+## Promotion protocol
+
+Change the decision to `SELECT_SUBGRAPH_MCP` only when one sanitized trace binds:
+
+1. immutable deployment ID and `_meta.deployment` manifest CID;
+2. MCP server/version, `execute_query_by_deployment_id`, query digest, variables, call ID, and retrieval time;
+3. candidate data plus `_meta` indexed block/time, Arc RPC chain head, computed lag, health, and candidate count;
+4. an LLM recommendation that references only evidence/candidate IDs and uses one frozen action;
+5. deterministic-core disposition plus proof of zero new settlement calls;
+6. exact Arc receipt/Transfer verification for any returned existing result.
+
+Credentials, authorization headers, raw provider bodies, prompts containing
+secrets, and model chain-of-thought are never recorded. Empty, delayed,
+unhealthy, malformed, injected, multiple, or contradictory results preserve
+`UNKNOWN`.
+
+## Primary sources checked
+
+- The Graph Subgraph MCP introduction: the server exposes Subgraph data as MCP tools and is not an LLM.
+- `graphops/subgraph-mcp` main branch: the immutable tool is `execute_query_by_deployment_id`; it accepts `deployment_id`, `query`, and optional `variables`, and returns GraphQL JSON in one text content block.
+- The Graph GraphQL API: `_meta` exposes deployment, indexed block number/hash/timestamp, and `hasIndexingErrors`.
+- The Graph supported-network registry: Arc Testnet is supported as `arc-testnet` with CAIP-2 chain ID `eip155:5042002`.

packages/reconciliation/docs/removal-value-matrix.md

@@ -0,0 +1,26 @@
+# C01 indexer removal/value matrix
+
+Date checked: 2026-09-07
+
+| Path                                      | Lost-hash discovery                                                   | Freshness evidence                                                        | Arc Testnet         | Dependency                 | Reuse                                          | Sponsor leverage                             |
+| ----------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------- | -------------------------- | ---------------------------------------------- | -------------------------------------------- |
+| Known Privy/Arc identity                  | No hashless search; safest baseline when request/hash is known        | Direct provider/RPC state                                                 | Yes                 | Privy and Arc RPC          | High for known identity                        | None for The Graph                           |
+| Direct Arc log search                     | Hashless tuple/window scan                                            | RPC head plus searched range                                              | Yes                 | Arc RPC                    | Chain-specific scanner                         | None for The Graph                           |
+| Enhanced RPC/indexer                      | Provider-specific hashless search                                     | Provider-specific                                                         | Must be proven      | Extra vendor               | Medium                                         | None for The Graph                           |
+| OneShot/Arc Subgraph through Subgraph MCP | Structured transfer tuple/window candidates for an LLM recovery agent | `_meta` deployment, indexed block/time, indexing errors, and RPC head lag | Must be proven live | The Graph Gateway plus MCP | High for recovery views and agent explanations | Required live path for the selected AI track |
+
+## Value test
+
+Removing Subgraph MCP must remove automatic structured hashless candidate
+discovery used by the LLM. It must not remove known-identity recovery, Arc
+verification, the durable `UNKNOWN` hold, or any safety property.
+
+The Graph path is retained only after a sanitized live trace proves that loss
+of the transaction hash is recovered through the pinned MCP deployment and
+that the returned candidate/freshness data materially changes the LLM's
+selection or explanation. Otherwise OneShot uses direct recovery and reports
+The Graph as `NOT VERIFIED`.
+
+B01/B02 reject the memo-forwarding path because Privy cannot constrain the
+nested recipient and amount. C01 therefore evaluates only the direct USDC
+`Transfer` tuple/window path for v1; `memo_id` remains unused.

packages/reconciliation/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@oneshot/reconciliation",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Provider-neutral, zero-submit recovery evidence contracts for OneShot.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "typecheck": "tsc -b --pretty false",
+    "verify": "pnpm run format && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build"
+  }
+}