docs(plan): map sponsor claims and Arc qualification

.agent/SPONSOR_REQUIREMENTS.md

@@ -33,10 +33,22 @@ decides. C01 must prove this with live data before any qualification claim.
 
 - Target the AI Tooling or AI Use Case track. The recovery agent must use live
   Graph data for meaningful candidate selection, explanation, and automation.
+- The production/demo path must query the pinned live OneShot/Arc Subgraph
+  through Subgraph MCP. A direct application GraphQL client, mocked MCP result,
+  dependency, or configuration entry alone is insufficient.
+- The LLM Recovery Agent must use the live MCP result to select `WAIT`,
+  `RECONCILE`, `ESCALATE`, or `RETURN_EXISTING_RESULT`. A sanitized trace must
+  bind the tool call, deployment/query/result, `_meta` health, referenced
+  evidence, model recommendation, and deterministic-core disposition.
 - Do not target Composable/Standardized with one custom Subgraph; that track
   requires two Graph products or meaningful standardized-schema work.
+- One live Subgraph is sufficient for the selected AI track; do not add a second
+  Subgraph merely to satisfy a requirement that belongs to another track.
 - Empty, delayed, multiple, or contradictory candidates preserve `UNKNOWN` and
   cannot unlock another settlement.
+- Malformed/injected MCP content and invalid model output also preserve
+  `UNKNOWN`. Subgraph MCP and the LLM have no signing, settlement, retry,
+  Attempt-creation, or submission-ownership capability.
 - Include a public repository, clear README, and a two-to-four-minute demo.
 
 ## Claim standard

.agent/TEST_MATRIX.md

@@ -1,7 +1,8 @@
 # OneShot Test Matrix
 
 Select every applicable case for changes to intents, retries, workers, queues,
-payments, settlements, reconciliation, Privy, Arc, or The Graph discovery. Prefer tests at
+payments, settlements, reconciliation, Privy, Arc, The Graph discovery,
+Subgraph MCP, or the LLM Recovery Agent. Prefer tests at
 the public domain boundary plus focused adapter tests. A test must assert durable
 state and external settlement count, not only an HTTP response.
 
@@ -15,7 +16,11 @@ state and external settlement count, not only an HTTP response.
 | Crash before submission | Kill process before any external submission | 0 settlements; retry is allowed from durable state |
 | Crash after submission | Kill process after possible submission but before local confirmation | Enter `UNKNOWN`; reconcile; no blind retry |
 | Lost payment response | Payment succeeds but HTTP response is lost | Exactly 1 committed settlement after reconciliation |
-| Graph delay, absence, or ambiguity | The Graph returns nothing, lags, is unavailable, or returns multiple candidates | Remain `UNKNOWN`; no duplicate settlement; absence is not non-payment proof |
+| Graph delay, absence, or ambiguity | The live Subgraph returns nothing, lags, is unavailable, or returns multiple candidates through Subgraph MCP | Remain `UNKNOWN`; no duplicate settlement; absence is not non-payment proof |
+| Subgraph MCP boundary failure | MCP times out or returns wrong deployment/tool, malformed/oversized data, schema drift, or injected instructions | Fail closed to `WAIT`/hold; 0 new settlements; sanitized diagnostic |
+| LLM recovery action matrix | Agent returns `WAIT`, `RECONCILE`, `ESCALATE`, and `RETURN_EXISTING_RESULT` | Core maps only to frozen safe commands; 0 settlement calls |
+| Invalid LLM output | Model times out, emits malformed JSON, unsupported action, or fabricated evidence reference | Reject output; remain `UNKNOWN`; 0 new settlements |
+| Existing-result challenge | Agent recommends `RETURN_EXISTING_RESULT` with and without independently authoritative Arc/durable proof | Return/commit only independently proven existing result; otherwise hold/escalate; never submit |
 | Privy denial | Policy denies or amount exceeds permission | 0 settlements and explicit authorization failure |
 | Service restart | Restart after durable intent creation or in-flight work | Intent and settlement state survive; invariant holds |
 | Downstream failure after payment | Supplier/API step fails after settlement | Payment result remains durable; no replacement payment |
@@ -27,6 +32,10 @@ state and external settlement count, not only an HTTP response.
 - Monetary values use integer atomic units or `bigint` end to end.
 - State transitions are atomic under real concurrency, not only mocked sequence.
 - External submission identifiers and reconciliation evidence survive restart.
+- Subgraph MCP evidence records pinned deployment, tool/query identity, `_meta`
+  freshness, and retrieval identity without credentials.
+- Agent recommendation, deterministic core disposition, and external-submission
+  count are asserted separately.
 - Logs and test fixtures contain no real secrets or wallet material.
 - Tests use testnet or isolated fakes; never create unauthorized mainnet effects.
 

.agent/context/20260906T230709Z-plan-clarification.md

@@ -0,0 +1,100 @@
+# Session Context: Subgraph MCP plan clarification
+
+## Date/time
+
+- UTC: 2026-09-06T23:07:09Z
+
+## User goal
+
+Clarify the product plan and independently closable C-lane milestones so The
+Graph qualification path explicitly uses a live OneShot/Arc Subgraph through
+Subgraph MCP, with meaningful LLM recovery reasoning behind a deterministic
+OneShot safety boundary.
+
+## Original prompt/request
+
+Create `plan-clarification` from the new repository's `develop`; update the plan,
+The Graph milestones, and sponsor-qualification skill around the flow Subgraph
+-> Subgraph MCP -> LLM Recovery Agent -> four allowed recommendations ->
+deterministic safety core. Repository: https://github.com/SWOFART/OneShot/.
+
+## Assumptions
+
+- This work targets The Graph's AI application eligibility path, not the separate
+  composable/standardized-products path; one live Subgraph is therefore planned.
+- The LLM is advisory. Existing authoritative state and Arc-evidence semantics
+  remain unchanged.
+- No push or PR is included because the user did not request either in this turn.
+- `develop` advanced during review preparation; the branch was fast-forwarded
+  and the clarification was rebuilt on the newer hashless-recovery plan instead
+  of restoring its deleted C01 milestone.
+
+## Plan
+
+1. Inspect current `develop` planning contracts and official The Graph sources.
+2. Update the plan, C-lane packets, architecture, and sponsor qualification rules.
+3. Run focused consistency and repository validation without external credentials.
+
+## Key decisions
+
+- Preserve develop's provider-neutral hashless-recovery design while selecting
+  a deployment-pinned Subgraph MCP adapter to feed the LLM Recovery Agent.
+- Freeze four advisory actions: `WAIT`, `RECONCILE`, `ESCALATE`, and
+  `RETURN_EXISTING_RESULT`; reject any submit/retry capability.
+- Keep OneShot durable state and verified Arc evidence authoritative. Direct LLM
+  state mutation and Graph-based retry permission were rejected as unsafe.
+
+## Files/components touched
+
+- `plan.md`, `docs/DOMAIN_ARCHITECTURE.md`: explicit MCP/LLM/core architecture.
+- `milestones/CONTRACTS.md`, `milestones/README.md`, `milestones/coder-c/*`: frozen ports, fixtures, packet tasks, tests, demo evidence.
+- `.agent/TEST_MATRIX.md`: MCP failure, four-action, invalid-output, and existing-result cases.
+- `.agent/SPONSOR_REQUIREMENTS.md`, `.agents/skills/sponsor-qualification/SKILL.md`: qualification standard.
+- `.agent/research/20260907-subgraph-mcp-clarification.md`: primary-source decision record.
+
+## Commands/checks
+
+- `git fetch origin develop` - develop advanced from `4336e04` to `d256e5360247ba5c0dfd1901470a0ad8c7a46068` during review preparation.
+- Fast-forward plus deliberate conflict resolution - preserved the new
+  `C01-recovery-evidence-strategy.md`; did not resurrect deleted
+  `C01-subgraph-index-health.md`.
+- Final `git diff --check`, branch-base equality, task sizing, stale terminology,
+  context, permissions, and secret-scope checks - pending after reconstruction.
+
+## External-doc findings
+
+- The Graph Subgraph MCP introduction - MCP exposes schema/query tools and returns structured Subgraph results to a client LLM.
+- The Graph AI overview - models can retrieve live blockchain data through Subgraph MCP.
+- The Graph hackathon resources, accessed 2026-09-07 - AI apps may use live Subgraph data through MCP; multiple products are a separate track.
+
+## Unresolved questions
+
+- None.
+
+## Git and PR state
+
+- Branch: `plan-clarification`
+- Base: `origin/develop` at `d256e5360247ba5c0dfd1901470a0ad8c7a46068`
+- Commit: `722c2f0` pushed; sponsor-claim/Arc-qualification plan edits committed this session
+- PR: opened against `develop`
+- CI: `Agent policy / repository-policy` runs on the pushed head
+
+## Review gates
+
+- Gate A: NOT RUN. `npx free-pi-cli` cannot start in this environment: the
+  registry resolves `free-pi-cli` to a `0.0.1` placeholder release that ships no
+  executable, and a pinned `free-pi-cli@0.2.19` install was denied by the local
+  sandbox. The user was informed of the fail-closed rule in
+  `.agent/IMPLEMENTATION_LOOP.md` and explicitly waived both gates for this
+  documentation-only change.
+- Gate B: NOT RUN. Waived by the same explicit user decision.
+
+Equivalent local evidence was captured instead: the full `agent-policy` workflow
+was reproduced locally against the candidate tree and passed, and
+`git diff --cached --check` reported no whitespace errors.
+
+## Handoff/next steps
+
+1. Human owner reviews the PR directly; no FreePi verdict backs this tree.
+2. Restore the normal Gate A/Gate B loop for the next change once a working
+   `free-pi-cli` distribution is available.

.agent/research/20260907-subgraph-mcp-clarification.md

@@ -0,0 +1,57 @@
+# The Graph Subgraph MCP Clarification
+
+Date: 2026-09-07
+Scope: primary-source clarification for OneShot's The Graph AI-track architecture and qualification evidence.
+
+## Primary-source findings
+
+- The Graph's Subgraph MCP is an open-source Model Context Protocol server that
+  exposes Subgraph data to MCP-compatible clients. Its tools can inspect a
+  schema, discover Subgraphs, and execute queries against a specific deployment
+  ([Subgraph MCP introduction](https://thegraph.com/docs/en/subgraphs/tooling/subgraph-mcp/introduction/)).
+- The MCP server is not an LLM. It translates MCP tool requests into Subgraph
+  queries and returns structured results for a client model to reason over
+  ([Subgraph MCP introduction](https://thegraph.com/docs/en/subgraphs/tooling/subgraph-mcp/introduction/)).
+- The Graph's AI overview describes Subgraph MCP as the bridge through which
+  models explore schemas, execute GraphQL queries, find Subgraphs, and retrieve
+  live blockchain data ([AI overview](https://thegraph.com/docs/en/ai-overview/)).
+- Current hackathon guidance lists AI applications that use The Graph as a live
+  data source, including agents querying Subgraphs through Subgraph MCP. The
+  catalog size does not impose a multiple-Subgraph minimum for this AI track;
+  composable/standardized products are a separate prize path
+  ([hackathon resources](https://thegraph.com/blog/hackathon-resources/)).
+
+## OneShot decision
+
+The production/demo recovery path is:
+
+```text
+live OneShot/Arc Subgraph
+        ↓
+Subgraph MCP
+        ↓
+LLM Recovery Agent
+        ↓
+WAIT / RECONCILE / ESCALATE / RETURN_EXISTING_RESULT
+        ↓
+deterministic OneShot safety core
+```
+
+The LLM recommendation is meaningful but advisory. The deterministic core
+rechecks the durable state version and authoritative Arc/OneShot evidence.
+Neither The Graph, Subgraph MCP, nor the LLM can sign, submit, retry, create an
+Attempt, acquire submission ownership, or call `SettlementPort`.
+
+## Qualification consequence
+
+The Graph remains `NOT VERIFIED` until a sanitized demo trace proves all of:
+
+1. the intended live OneShot/Arc deployment was queried through Subgraph MCP;
+2. the returned live indexed evidence and `_meta` health reached the LLM;
+3. the LLM selected one of the four frozen recommendations using referenced evidence;
+4. the deterministic core independently accepted, constrained, or rejected it;
+5. empty, delayed, malformed, injected, unavailable, or contradictory tool data
+   and invalid model output never create settlement permission.
+
+One live Subgraph is sufficient for this AI-track claim. OneShot must not claim
+the separate composable/multiple-products track without separate evidence.

.agents/skills/sponsor-qualification/SKILL.md

@@ -14,13 +14,21 @@ code, tests, and demo instructions. Review working evidence, not plans.
   path through scoped policy or spending permission. Login-only is insufficient.
 - Arc: prove a real USDC settlement on Arc Testnet and, for the Launch track,
   fail-closed mainnet-readiness artifacts without inventing unavailable values.
-- The Graph: prove live indexed data drives hashless candidate discovery and
-  meaningful recovery-agent automation beyond direct known-hash lookup. Arc
-  verifies candidates; empty, stale, multiple, or contradictory results cannot
-  unlock another settlement.
+- The Graph: prove a pinned live OneShot/Arc Subgraph is queried through
+  Subgraph MCP and that the LLM Recovery Agent materially uses the result for
+  hashless candidate selection/explanation beyond direct known-hash lookup.
+- Bind a sanitized MCP trace to deployment/query/result, `_meta` health,
+  evidence references, one of `WAIT`, `RECONCILE`, `ESCALATE`, or
+  `RETURN_EXISTING_RESULT`, and the deterministic-core disposition. Direct
+  GraphQL, mocks, dependencies, variables, and prompt text alone are insufficient.
+- Arc verifies candidates and OneShot decides. Empty, stale, malformed/injected,
+  multiple, or contradictory MCP results and invalid model output cannot unlock
+  another settlement. MCP/model code exposes no settlement or retry capability.
+- Do not require multiple Subgraphs for the selected AI track or award the
+  separate Composable/Standardized claim without its own proof.
 - Verify the demo preserves `1 intent / N attempts / <=1 settlement` and never
   exposes secrets.
 
 For each selected sponsor, report `QUALIFIED`, `NOT QUALIFIED`, or
 `NOT VERIFIED`, citing code, tests, live demo evidence, network, and known
-limitations. Never upgrade missing or mocked evidence into qualification.
+limitations. Never upgrade missing or mocked evidence into qualification.

docs/DOMAIN_ARCHITECTURE.md

@@ -17,11 +17,13 @@ flowchart LR
     Worker --> Privy
     Privy --> Arc[Arc USDC settlement]
     Arc --> SupplierWallet[Supplier wallet]
-    Arc --> Graph[The Graph candidate index]
+    Arc --> Graph[Live OneShot Arc Subgraph]
     Ledger --> Recovery[Recovery service and audit view]
     Recovery -->|provider lookup| Privy
     Recovery -->|receipt and log lookup| Arc
-    Recovery -->|candidate query and freshness| Graph
+    Graph --> MCP[Subgraph MCP]
+    MCP -->|validated candidates and freshness| RecoveryAgent[LLM Recovery Agent]
+    RecoveryAgent -->|four-action recommendation| Recovery
     Recovery --> Agent
     Recovery --> Operator
 ```
@@ -124,8 +126,10 @@ none may reinterpret the state machine.
 | Graphile Worker | Deliver execution and reconciliation jobs | Authority to pay because a job was redelivered |
 | Privy adapter | Wallet authorization, policy checks, provider request identity | Durable Business Intent authority |
 | Arc adapter | Transaction construction, submission, receipt and Transfer verification | Deciding whether another attempt is allowed |
-| The Graph candidate adapter | Indexed transfer discovery, deployment identity, freshness, and health after passing the C01 value gate | Proof that an absent payment never happened |
-| Reconciliation engine | Combine bound evidence and emit versioned safe commands | Settlement submission |
+| The Graph Subgraph | Indexed transfer discovery, deployment identity, freshness, and health after passing C01 | Proof that an absent payment never happened |
+| Subgraph MCP adapter | Pin deployment and validate MCP tool/query results before model use | Model behavior, settlement authority, or secret exposure |
+| LLM Recovery Agent | Recommend `WAIT`, `RECONCILE`, `ESCALATE`, or `RETURN_EXISTING_RESULT` from labeled evidence | Settlement submission or authoritative transition |
+| Deterministic recovery safety core | Recheck Arc/durable proof and map allowed recommendations to safe commands | Trusting Graph/MCP/model as financial authority |
 | Operator console | Explain state, evidence, policy and safe recovery actions | Force-pay or bypass controls |
 | Telemetry/runbooks | Reveal failures, lag, `UNKNOWN` age and safe-disable state | Secrets or mutation of financial truth |
 
@@ -168,8 +172,10 @@ sequenceDiagram
     participant DB as PostgreSQL
     participant Privy
     participant Arc
-    participant Graph as The Graph
-    participant Reconciler
+    participant Graph as OneShot Arc Subgraph
+    participant MCP as Subgraph MCP
+    participant Agent as LLM Recovery Agent
+    participant Reconciler as Deterministic safety core
     participant Domain
 
     Worker->>DB: Persist SUBMITTING and request identity
@@ -183,13 +189,16 @@ sequenceDiagram
     alt transaction hash recovered
         Reconciler->>Arc: Verify recovered receipt and Transfer
     else transaction hash missing
-        Reconciler->>Graph: Query memo ID or transfer tuple plus freshness
-        Graph-->>Reconciler: Zero, one, or multiple candidates
+        Agent->>MCP: Inspect/query pinned deployment
+        MCP->>Graph: Query memo ID or transfer tuple plus _meta
+        Graph-->>MCP: Zero, one, or multiple live candidates
+        MCP-->>Agent: Validated structured tool result
+        Agent-->>Reconciler: Four-action recommendation and evidence references
         loop each candidate
             Reconciler->>Arc: Verify receipt, Memo when used, and Transfer
         end
     end
-    Note over Reconciler,Graph: Graph discovers candidates, Arc proves, and Graph never authorizes a retry
+    Note over Agent,Reconciler: Graph/MCP/LLM discover candidates, Arc proves, deterministic core decides
     alt exactly one bindable final match
         Reconciler->>Domain: Emit MARK_COMMITTED with expected version
         Domain->>DB: Compare and set UNKNOWN to COMMITTED
@@ -212,25 +221,32 @@ flowchart LR
     Domain --> Settle[SettlementPort]
     Reconciliation --> Evidence[EvidencePort]
     Reconciliation --> Index[IndexViewPort]
-    Reconciliation --> Command
+    Reconciliation --> Advisor[RecoveryAdvisorPort]
+    Reconciliation --> SafetyCore[Deterministic safety core]
+    SafetyCore --> Command
     Command --> Domain
 
     Auth --> Privy[Privy adapter]
     Settle --> ArcWrite[Arc write adapter]
     Evidence --> PrivyRead[Privy lookup]
     Evidence --> ArcRead[Arc receipt and log lookup]
-    Index --> HistoryAdapter[The Graph adapter]
+    Index --> MCPAdapter[Subgraph MCP adapter]
+    Advisor --> RecoveryAgent[LLM Recovery Agent]
 
     Privy --> External1[Privy service]
     ArcWrite --> External2[Arc RPC]
     PrivyRead --> External1
     ArcRead --> External2
-    HistoryAdapter --> External3[The Graph live provider]
+    RecoveryAgent --> MCPAdapter
+    MCPAdapter --> MCP[Subgraph MCP]
+    MCP --> External3[Live OneShot Arc Subgraph]
 ```
 
 The domain consumes stable result families. Adapters translate external SDK,
-RPC, and Graph-query behavior into those results. External response shapes never
-leak into the state machine.
+RPC, MCP, Graph-query, and model behavior into those results. The safety core
+accepts only the frozen four-action recommendation contract and independently
+validates any result-returning command. External response shapes never leak
+into the state machine.
 
 ## A/B/C ownership and convergence
 
@@ -255,8 +271,8 @@ flowchart TB
     end
 
     subgraph C[Coder C - evidence and recovery]
-      C1[Graph discovery and evidence strategy]
-      C2[Reconciliation engine]
+      C1[Subgraph MCP discovery strategy]
+      C2[LLM agent and safety core]
       C3[Failure injection]
       C4[Recovery service]
       C1 --> C2 --> C3 --> C4