From 722c2f0e4d5004213adb8d788710b3dddee589a5 Mon Sep 17 00:00:00 2001 From: SuPuHe Date: Mon, 7 Sep 2026 01:36:12 +0200 Subject: [PATCH 1/4] docs(plan): clarify Subgraph MCP recovery flow --- .agent/SPONSOR_REQUIREMENTS.md | 12 ++ .agent/TEST_MATRIX.md | 13 +- .../20260906T230709Z-plan-clarification.md | 89 ++++++++++++ .../20260907-subgraph-mcp-clarification.md | 57 ++++++++ .agents/skills/sponsor-qualification/SKILL.md | 18 ++- docs/DOMAIN_ARCHITECTURE.md | 48 ++++--- milestones/CONTRACTS.md | 57 +++++++- milestones/README.md | 4 +- .../coder-c/C01-recovery-evidence-strategy.md | 49 ++++--- .../coder-c/C02-reconciliation-engine.md | 44 ++++-- milestones/coder-c/C03-failure-injection.md | 19 ++- .../C04-recovery-matrix-integration.md | 27 ++-- milestones/coder-c/C05-frontend-recovery.md | 16 ++- milestones/coder-c/C06-qualification-demo.md | 30 ++-- milestones/coder-c/README.md | 22 +-- plan.md | 131 +++++++++++------- 16 files changed, 490 insertions(+), 146 deletions(-) create mode 100644 .agent/context/20260906T230709Z-plan-clarification.md create mode 100644 .agent/research/20260907-subgraph-mcp-clarification.md diff --git a/.agent/SPONSOR_REQUIREMENTS.md b/.agent/SPONSOR_REQUIREMENTS.md index 432c5d1..85c0cb0 100644 --- a/.agent/SPONSOR_REQUIREMENTS.md +++ b/.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 diff --git a/.agent/TEST_MATRIX.md b/.agent/TEST_MATRIX.md index 1b85e20..48072cd 100644 --- a/.agent/TEST_MATRIX.md +++ b/.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. diff --git a/.agent/context/20260906T230709Z-plan-clarification.md b/.agent/context/20260906T230709Z-plan-clarification.md new file mode 100644 index 0000000..1020da6 --- /dev/null +++ b/.agent/context/20260906T230709Z-plan-clarification.md @@ -0,0 +1,89 @@ +# 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: uncommitted +- PR: not created +- CI: not run; no pushed head + +## Review gates + +- Gate A: pending; user requested exactly one `npx free-pi-cli` consistency review +- Gate B: NOT RUN; no PR requested + +## Handoff/next steps + +1. Review the local diff and decide whether to request commit/push/PR. diff --git a/.agent/research/20260907-subgraph-mcp-clarification.md b/.agent/research/20260907-subgraph-mcp-clarification.md new file mode 100644 index 0000000..427c957 --- /dev/null +++ b/.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. diff --git a/.agents/skills/sponsor-qualification/SKILL.md b/.agents/skills/sponsor-qualification/SKILL.md index dcae10b..f7c7b55 100644 --- a/.agents/skills/sponsor-qualification/SKILL.md +++ b/.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. \ No newline at end of file +limitations. Never upgrade missing or mocked evidence into qualification. diff --git a/docs/DOMAIN_ARCHITECTURE.md b/docs/DOMAIN_ARCHITECTURE.md index 49b71e5..9419481 100644 --- a/docs/DOMAIN_ARCHITECTURE.md +++ b/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 diff --git a/milestones/CONTRACTS.md b/milestones/CONTRACTS.md index fa771bc..2237910 100644 --- a/milestones/CONTRACTS.md +++ b/milestones/CONTRACTS.md @@ -11,7 +11,8 @@ Change rule: expand-migrate-contract only - OneShot durable state grants submission ownership. - Privy authorizes and constrains the wallet action but is not the durable duplicate lock. - Arc receipt plus expected ERC-20 Transfer evidence establishes committed settlement. -- Direct Privy/Arc evidence resolves known transaction identities. The Graph is the selected v1 hashless candidate-discovery layer after C01; all indexed evidence remains non-authoritative. +- Direct Privy/Arc evidence resolves known transaction identities. The selected v1 hashless path queries the live OneShot/Arc Subgraph through Subgraph MCP and lets an LLM Recovery Agent recommend a bounded action after C01; all indexed/model evidence remains non-authoritative. +- Subgraph MCP and the LLM expose no signing, settlement, retry, Attempt-creation, or submission-ownership capability. - Any possibly submitted but unconfirmed outcome is `UNKNOWN`; reconciliation precedes another submission. ## 2. Canonical identifiers and money @@ -99,10 +100,42 @@ Results: ### IndexViewPort.lookup -The v1 implementation queries The Graph for candidate transfers and returns observations plus observed block/time, provider/deployment identity, chain-head comparison, lag, provider health details, retrieval time, and health classification: `FRESH`, `LAGGING`, `UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. +The v1 implementation obtains candidate transfers from a deployment-pinned +Subgraph MCP tool call and returns observations plus observed block/time, +provider/deployment/tool identity, chain-head comparison, lag, provider health +details, retrieval time, and health classification: `FRESH`, `LAGGING`, +`UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. The adapter validates tool +arguments, target deployment, result schema, `_meta`, size bounds, and untrusted +text. Credentials never enter prompts, tool results, fixtures, logs, or evidence. No IndexViewPort result grants settlement permission. +### RecoveryAdvisorPort.recommend + +Input is a bounded, sanitized recovery view containing durable-state summary, +authority labels, exact identity bindings, Arc/Privy observations, and validated +Subgraph MCP observations. The only accepted recommendations are: + +- `WAIT`: preserve `UNKNOWN` until fresher or authoritative evidence exists. +- `RECONCILE`: request another read-only evidence cycle. +- `ESCALATE`: request operator investigation with no financial effect. +- `RETURN_EXISTING_RESULT`: return candidate/evidence references for a result the deterministic core must independently prove already exists. + +The response includes a bounded reason, referenced evidence IDs, model +configuration identity, and decision ID. Unknown actions, free-form tool calls, +missing/fabricated references, malformed output, prompt/tool injection, or model +unavailability fail closed to `WAIT` plus a sanitized diagnostic. + +### Deterministic recovery safety core + +The safety core treats the recommendation as advisory and rechecks the current +state version and authoritative OneShot/Arc evidence. `RECONCILE` can enqueue +only a read-only lookup, `WAIT` maps to `HOLD_UNKNOWN`, `ESCALATE` maps to +`ESCALATE_UNKNOWN`, and `RETURN_EXISTING_RESULT` can produce +`MARK_COMMITTED`/an existing terminal response only when independently proven. +No mapping calls `SettlementPort`, creates an Attempt, or grants submission +ownership. + ## 6. Durable state machine | Current | Trigger | Next | Submission permission | @@ -154,12 +187,21 @@ The canonical fixture root is `packages/contracts/fixtures/v1/`. Every fixture h | `index/lagging.json` | `LAGGING`, no permission change | | `index/provider-error.json` | `UNHEALTHY`, no permission change | | `index/unavailable.json` | `UNAVAILABLE`, local authority still returned | +| `mcp/malformed.json` | rejected before agent input; fail-closed `WAIT` | +| `mcp/injected-content.json` | content remains untrusted evidence, never an instruction | +| `agent/wait.json` | `WAIT` -> `HOLD_UNKNOWN`, zero external submissions | +| `agent/reconcile.json` | `RECONCILE` -> read-only evidence cycle only | +| `agent/escalate.json` | `ESCALATE` -> operator escalation only | +| `agent/return-existing-result.json` | accepted only when authoritative evidence independently proves the result | +| `agent/unsupported-action.json` | rejected; fail-closed `WAIT`, zero external submissions | ## 9. Simulator behavior - Domain simulator exposes the HTTP seam and deterministic clock/IDs with an external-submission counter. - Settlement simulator consumes canonical requests and emits each SettlementPort/EvidencePort result family without network access. -- Recovery simulator consumes local state plus Privy/Arc and Graph candidate fixtures and emits deterministic commands and a labeled recovery view. +- Subgraph MCP simulator consumes pinned-deployment query fixtures and emits validated Graph candidates without network or credentials. +- Recovery-agent simulator consumes the labeled recovery view and emits every allowed/invalid recommendation deterministically. +- Recovery simulator passes recommendations through the deterministic safety core and emits commands and a labeled recovery view. - Simulators reject unknown fixture versions and schema drift. - Simulators never silently default an unknown enum to a successful or retryable result. @@ -169,14 +211,15 @@ The canonical fixture root is `packages/contracts/fixtures/v1/`. Every fixture h 2. Worker task plus durable state and external-submission counter. 3. Adapter ports plus official-response fixtures. 4. Reconciliation command plus durable transition and evidence record. -5. Graph candidate query plus deployment-specific freshness and ambiguity classification after C01. -6. Browser UI through frozen OpenAPI/mock server after Gate P4. +5. Subgraph MCP candidate query/tool result plus deployment-specific freshness and ambiguity classification after C01. +6. RecoveryAdvisorPort recommendation plus deterministic safety-core command and external-submission counter. +7. Browser UI through frozen OpenAPI/mock server after Gate P4. ## 11. Compatibility and ownership - A owns base schemas, OpenAPI, error codes, state vocabulary, and fixture validation tooling. - B owns provider-specific optional evidence fields and response-to-port classification fixtures. -- C owns index/recovery observation fields and reconciliation-decision fixtures. +- C owns index/MCP/recovery observation fields, recovery-agent recommendation fields, and reconciliation-decision fixtures. - Optional fields must not change existing result meaning. - Unknown enum values fail closed at boundaries. - A breaking change requires ADR, new fixture version, dual-form simulator support, independent consumer migration, and later removal. @@ -186,5 +229,5 @@ The canonical fixture root is `packages/contracts/fixtures/v1/`. Every fixture h - Every field has type, normalization, authority, and redaction rules. - Every terminal result has a durable transition and external-submission expectation. - Every lane can run a simulator with no credentials. -- No unresolved item can change settlement cardinality, monetary precision, Privy enforcement, Arc identity, or `UNKNOWN` semantics. +- No unresolved item can change settlement cardinality, monetary precision, Privy enforcement, Arc identity, `UNKNOWN` semantics, or the non-authoritative MCP/LLM boundary. - Human approval records the exact Git tree containing this contract pack. diff --git a/milestones/README.md b/milestones/README.md index 1b0a81a..b858e35 100644 --- a/milestones/README.md +++ b/milestones/README.md @@ -14,7 +14,7 @@ This directory turns `plan.md` into small, independently closable work packets f - [`coder-a/`](coder-a/README.md): domain, storage, API, worker, composition, intent/status UI, operations. - [`coder-b/`](coder-b/README.md): Privy, Arc, request/receipt safety, provider ambiguity, settlement UI, sponsor evidence. -- [`coder-c/`](coder-c/README.md): The Graph candidate discovery behind a provider-neutral port, reconciliation, failure injection, recovery UI, qualification. +- [`coder-c/`](coder-c/README.md): The Graph candidate discovery through Subgraph MCP, LLM Recovery Agent, deterministic reconciliation, failure injection, recovery UI, qualification. Each lane has six ordered packets. A packet depends only on the frozen contract pack and the preceding packet in the same directory. A real package from another coder is never required for packet closure; use the checked simulator until project Gate P4. @@ -89,4 +89,4 @@ For a required contract change: 4. Let each owner migrate independently. 5. Remove the old form only in a later, separately reviewed packet. -Never reinterpret `UNKNOWN`, monetary precision, settlement ownership, or external evidence authority through a compatibility shortcut. +Never reinterpret `UNKNOWN`, monetary precision, settlement ownership, or Graph/MCP/LLM authority through a compatibility shortcut. diff --git a/milestones/coder-c/C01-recovery-evidence-strategy.md b/milestones/coder-c/C01-recovery-evidence-strategy.md index 4e34efa..5ceaa16 100644 --- a/milestones/coder-c/C01-recovery-evidence-strategy.md +++ b/milestones/coder-c/C01-recovery-evidence-strategy.md @@ -8,9 +8,10 @@ Next: C02 immediately after closure ## Outcome A provider-neutral recovery evidence contract proves the known-identity -Privy/Arc baseline and validates The Graph as the selected hashless -candidate-discovery layer. Arc remains authoritative; a failed live Graph value -gate removes the Graph claim and selects the direct-recovery fallback. +Privy/Arc baseline and validates a live OneShot/Arc Subgraph queried through +Subgraph MCP as the selected hashless candidate-discovery layer for an LLM +Recovery Agent. Arc remains authoritative; a failed live MCP/Graph value gate +removes the Graph claim and selects the direct-recovery fallback. ## Small tasks @@ -26,36 +27,52 @@ gate removes the Graph claim and selects the direct-recovery fallback. - Compare The Graph with no-index, direct Arc event search, and enhanced RPC by lost-hash discovery, freshness, testnet/mainnet support, operational dependency, reuse, and sponsor leverage. -- Retain The Graph only if removing it breaks automatic hashless recovery or a - named recovery-agent decision instead of merely removing a dashboard query. +- Retain The Graph only if removing the live Subgraph MCP path breaks automatic + hashless recovery or a named LLM recovery-agent decision instead of merely + removing a dashboard query. -### C01.3 — Graph candidate and correlation contract +### C01.3 — Subgraph MCP candidate and correlation contract -- Define Graph observations, provider/deployment identity, observed-through - block/time, lag, health, retrieval time, candidate count, and contradiction. +- Pin the intended OneShot/Arc deployment and define MCP tool/query identity, + Graph observations, provider/deployment identity, observed-through block/time, + lag, health, retrieval time, candidate count, and contradiction. - Model tuple/window lookup and the preferred Arc Memo `memoId` correlation; distinguish empty or multiple candidates from authoritative non-payment. +- Validate MCP arguments/results, `_meta`, schema, size bounds, and untrusted + content; keep gateway/API credentials outside prompts, logs, and evidence. ### C01.4 — Fixtures and simulator -- Cover fresh, empty, lagging, unhealthy, unavailable, duplicate, out-of-order, - and contradictory results without selecting a vendor in domain code. +- Cover fresh, empty, lagging, unhealthy, unavailable, malformed/injected, + duplicate, out-of-order, and contradictory results without selecting a vendor + in domain code. - Add provider-specific mapping tests only after the decision record selects an implementation. +### C01.5 — Live MCP and AI-value spike + +- Query the intended live deployment through Subgraph MCP, not a direct + application GraphQL client, and capture a sanitized tool trace. +- Feed the live candidate/freshness result to an LLM Recovery Agent and prove it + materially affects candidate selection or explanation. +- Record `SELECT_SUBGRAPH_MCP` or `FALLBACK_DIRECT_RECOVERY`; the fallback keeps + safety but makes The Graph qualification `NOT VERIFIED`. + ## Acceptance evidence - Known-identity recovery remains safe with The Graph disabled; automatic hashless discovery is explicitly unavailable in that fallback. - No Graph result grants settlement permission. -- Live evidence shows whether The Graph finds the lost-hash candidate, how - freshness and multiple matches behave, and what capability removal loses. +- Live evidence shows whether Subgraph MCP finds the lost-hash candidate, how + freshness and multiple matches behave, how the LLM uses the result, and what + capability removal loses. - All fixtures run without network access or credentials. ## Handoff artifact -Publish `index-view-v1`, the baseline recovery evidence schema, removal/value -matrix, decision record, simulator fixtures, and package-local checks. +Publish `index-view-v1`, the baseline recovery evidence schema, MCP tool/query +schema, removal/value matrix, sanitized live MCP/agent trace, decision record, +simulator fixtures, and package-local checks. ## No-wait continuation @@ -63,5 +80,5 @@ Start C02 with the provider-neutral evidence contract and recorded decision. ## Non-goals -No settlement submission, database authority, mandatory third-party indexer, -sponsor claim, or production UI. \ No newline at end of file +No settlement submission, database authority, MCP/LLM financial authority, +sponsor claim from mocked evidence, or production UI. diff --git a/milestones/coder-c/C02-reconciliation-engine.md b/milestones/coder-c/C02-reconciliation-engine.md index 1d85c56..f78d49c 100644 --- a/milestones/coder-c/C02-reconciliation-engine.md +++ b/milestones/coder-c/C02-reconciliation-engine.md @@ -1,4 +1,4 @@ -# C02 — Deterministic Reconciliation Engine +# C02 — LLM Recovery Agent and Deterministic Reconciliation Owner: Coder C Branch: `milestone/c02-reconciliation-engine` @@ -7,7 +7,11 @@ Next: C03 immediately after closure ## Outcome -A pure decision engine combines authoritative local/Arc evidence, provider lookup, and non-authoritative Graph candidate observations to emit safe reconciliation commands and a provenance-labeled recovery view. It can never submit payment. +An LLM Recovery Agent consumes sanitized Subgraph MCP candidate observations and +recommends exactly one of `WAIT`, `RECONCILE`, `ESCALATE`, or +`RETURN_EXISTING_RESULT`. A deterministic safety core combines authoritative +local/Arc evidence with that advisory output to emit safe reconciliation +commands and a provenance-labeled recovery view. It can never submit payment. ## Small tasks @@ -16,40 +20,51 @@ A pure decision engine combines authoritative local/Arc evidence, provider looku - Define source, authority class, request binding, retrieval time, block/finality/freshness, sanitized reason, and digest. - Reject evidence that cannot bind to the exact intent/request/transaction identity. -### C02.2 — Precedence table +### C02.2 — Evidence precedence and agent input - Make durable committed record and exact verified Arc receipt authoritative. -- Use Privy status and direct Arc evidence to resolve the original activity; use The Graph only to locate, corroborate, or explain. +- Use Privy status and direct Arc evidence to resolve the original activity; use Subgraph MCP/LLM only to locate, select, corroborate, or explain candidates. - Encode contradictory, stale, missing, and unavailable combinations explicitly. +- Build a bounded, sanitized input that labels MCP content as untrusted data and excludes secrets/raw provider bodies. -### C02.3 — Reconciliation commands +### C02.3 — LLM recommendation contract -- Emit `MARK_COMMITTED`, `MARK_FAILED_SAFE`, `HOLD_UNKNOWN`, or `ESCALATE_UNKNOWN` with expected state version. -- Require exact verified success for commit and authoritative matching final failure/no-effect proof for failed-safe. -- Never emit a submit/retry command. +- Accept only structured `WAIT`, `RECONCILE`, `ESCALATE`, or + `RETURN_EXISTING_RESULT` with bounded reason and evidence/candidate references. +- Reject unknown actions, extra tool calls, fabricated/missing bindings, + free-form commands, and prompt/tool injection. +- Publish a deterministic agent simulator so C02 closes without model credentials. -### C02.4 — Recovery view +### C02.4 — Safety-core commands and recovery view +- Map `WAIT` to `HOLD_UNKNOWN`, `RECONCILE` to read-only lookup, and `ESCALATE` to `ESCALATE_UNKNOWN`. +- Permit `RETURN_EXISTING_RESULT` to become `MARK_COMMITTED`/a terminal response only after exact current Arc/durable proof; otherwise hold or escalate. +- Never emit submit/retry, create submission ownership, or call `SettlementPort`. - Separate authoritative state from provider/Arc/indexed observations. -- Include observed-through block/time, lag, health, and contradiction warnings. +- Include MCP deployment/tool identity, observed-through block/time, lag, health, + agent recommendation, core disposition, and contradiction warnings. - Sanitize raw payloads and bound collection sizes. ### C02.5 — Idempotency tests -- Repeat decisions, reorder/duplicate observations, change retrieval time, and replay webhooks/provider events. +- Repeat recommendations, reorder/duplicate observations, change retrieval time, and replay MCP/provider events. - Prove deterministic semantic command and zero external submissions. ## Acceptance evidence - Verified matching success resolves `UNKNOWN -> COMMITTED`. - Matching final revert/no-effect proof may resolve `UNKNOWN -> FAILED_SAFE`. -- Pending, not found, unavailable, empty/lagging/unhealthy Graph candidates, mismatch, or contradiction remains `UNKNOWN`. +- Pending, not found, unavailable, empty/lagging/unhealthy Graph/MCP candidates, + mismatch, contradiction, model failure, or invalid output remains `UNKNOWN`. +- Each allowed recommendation is exercised; none can bypass Arc/durable proof or create a settlement right. - Every decision explains authority and provenance without leaking raw sensitive data. - Package imports no A/B implementation and contains no SettlementPort call. ## Handoff artifact -Publish `reconciliation-v1`, complete decision matrix, command schema, evidence/recovery fixtures, pure simulator, and verification command. +Publish `reconciliation-v1`, RecoveryAdvisorPort schema, four-action/invalid-output +matrix, deterministic agent and safety-core simulators, command schema, +evidence/recovery fixtures, and verification command. ## No-wait continuation @@ -57,4 +72,5 @@ Start C03 using the local state and provider simulators from the frozen pack. ## Non-goals -No direct database mutation, queue ownership, settlement submission, live external-index requirement, or frontend. +No direct database mutation, queue ownership, settlement submission, live +external-index/model requirement, or frontend. diff --git a/milestones/coder-c/C03-failure-injection.md b/milestones/coder-c/C03-failure-injection.md index ca76416..46f624d 100644 --- a/milestones/coder-c/C03-failure-injection.md +++ b/milestones/coder-c/C03-failure-injection.md @@ -7,7 +7,10 @@ Next: C04 immediately after closure ## Outcome -A deterministic chaos harness proves that crashes, lost responses, duplicate/out-of-order evidence, Graph degradation, and provider/RPC contradictions cannot turn uncertainty into settlement permission. +A deterministic chaos harness proves that crashes, lost responses, +duplicate/out-of-order evidence, Graph/Subgraph MCP degradation, hostile tool +content, invalid LLM output, and provider/RPC contradictions cannot turn +uncertainty into settlement permission. ## Small tasks @@ -17,10 +20,12 @@ A deterministic chaos harness proves that crashes, lost responses, duplicate/out - Model process kill, timeout, disconnect, response loss, delayed evidence, and restart between durable transitions. - Make each scenario deterministic and seed-recorded. -### C03.2 — Graph degradation suite +### C03.2 — Graph and Subgraph MCP degradation suite - Delay/empty results, trail chain head, set provider health errors, omit freshness metadata, fail query, return duplicates/out-of-order events, and switch deployment identity. -- Assert health labels and no permission change. +- Add MCP timeout, wrong tool/deployment, schema drift, truncated/oversized or + malformed result, duplicated delivery, and injected instruction text. +- Assert health/provenance labels and no permission change. ### C03.3 — Provider/RPC contradiction suite @@ -32,8 +37,11 @@ A deterministic chaos harness proves that crashes, lost responses, duplicate/out - Persist synthetic evidence feed, restart the harness, replay/reorder it, and compare decisions. - Prove semantic idempotency and stable audit chronology. -### C03.5 — UNKNOWN aging and escalation +### C03.5 — Agent failure, UNKNOWN aging, and escalation +- Inject model timeout, malformed JSON, unsupported action, fabricated evidence + reference, and nondeterministic prose; assert fail-closed `WAIT`/hold and zero + settlement calls. - Add configurable age buckets, alerts, operator context, and escalation outcomes. - Ensure runbook language never instructs “just retry” or treats lease expiry as permission. @@ -41,7 +49,8 @@ A deterministic chaos harness proves that crashes, lost responses, duplicate/out - Every `.agent/TEST_MATRIX.md` case involving ambiguity/evidence has a deterministic scenario. - Crash/lost response after possible submission remains `UNKNOWN` until authoritative resolution. -- Empty, delayed, unhealthy, contradictory, or unavailable sources never unlock payment. +- Empty, delayed, unhealthy, contradictory, malformed, injected, or unavailable + sources and invalid agent output never unlock payment. - Repeated/reordered evidence causes zero settlement calls and stable commands. - Harness runs with no network or credentials. diff --git a/milestones/coder-c/C04-recovery-matrix-integration.md b/milestones/coder-c/C04-recovery-matrix-integration.md index 5c5dfea..bf98241 100644 --- a/milestones/coder-c/C04-recovery-matrix-integration.md +++ b/milestones/coder-c/C04-recovery-matrix-integration.md @@ -7,48 +7,57 @@ Next: hold C05 until project Gate P4 ## Outcome -The recovery service composes frozen local-state, provider/Arc, and Graph simulators, persists sanitized evidence through its command seam, and produces the complete pre-live safety matrix. +The recovery service composes frozen local-state, provider/Arc, Subgraph MCP, +and LLM simulators, persists sanitized evidence/decisions through its command +seam, and produces the complete pre-live safety matrix. ## Small tasks ### C04.1 — Service boundary -- Implement reconciliation job/command handler around the pure engine. +- Implement the reconciliation job/command handler around RecoveryAdvisorPort and the deterministic safety core. - Consume state snapshots and emit versioned commands; never write A tables or call settlement. - Add retry-safe reads and duplicate event handling. ### C04.2 — Evidence persistence contract -- Emit append-only observation records with provenance, retrieval time, block/freshness, authority, reason, and digest. +- Emit append-only observation/decision records with MCP/model provenance, + retrieval time, block/freshness, authority, reason, evidence references, and digest. - Redact provider bodies and secrets before crossing the boundary. -### C04.3 — Simulator composition +### C04.3 — MCP and agent simulator composition -- Host A local-state and B evidence simulators behind frozen ports. +- Host A local-state, B evidence, Subgraph MCP, and recovery-agent simulators behind frozen ports. - Verify contract version mismatch and unknown result fail closed. - Run all combinations without importing internal implementation paths. ### C04.4 — Matrix report - Generate a sanitized table containing scenario, stable intent, starting/final state, evidence sources, decision, and external-submission count. -- Cover normal, duplicate, concurrency, crash, lost response, Graph delay/error, denial, restart, downstream failure, and two-agent cases at the recovery seam. +- Cover normal, all four recommendations, invalid model output, duplicate, + concurrency, crash, lost response, Graph/MCP delay/error/malformed/injection, + denial, restart, downstream failure, and two-agent cases at the recovery seam. ### C04.5 — Gate P4 replacement guide - Document exact simulator-to-reviewed-package replacement points. -- Define checks, lag thresholds, expected package versions, and safe-disable behavior for a Graph deployment; keep the no-index baseline runnable. +- Define deployment/MCP target checks, lag thresholds, model configuration, + expected package versions, credential boundaries, and safe-disable behavior; + keep the no-index baseline runnable. ## Acceptance evidence - Package-local lint/type/test/build and full fixture matrix pass. - Reconciliation retries are idempotent and zero-submit by construction. - Recovery view always distinguishes authority and observation freshness. -- Contract mismatch, missing freshness metadata, raw provider payload, and unknown enum fail closed. +- Contract mismatch, missing freshness metadata, wrong MCP deployment/tool, raw + provider payload, prompt injection, and unknown agent enum fail closed. - Packet closes with simulators; live gaps are explicit Gate P4 items. ## Handoff artifact -Publish recovery service package, evidence command pack, matrix report, simulator lock, live replacement guide, and Graph decision and deployment checklist. +Publish recovery service package, MCP/agent evidence-command pack, matrix report, +simulator lock, live replacement guide, and Graph deployment/MCP checklist. ## No-wait continuation diff --git a/milestones/coder-c/C05-frontend-recovery.md b/milestones/coder-c/C05-frontend-recovery.md index f590340..0eab615 100644 --- a/milestones/coder-c/C05-frontend-recovery.md +++ b/milestones/coder-c/C05-frontend-recovery.md @@ -11,7 +11,10 @@ Do not write production UI before P4 freezes recovery-view semantics. Build agai ## Outcome -An independently composable recovery slice shows authoritative state, attempts, reconciliation, provider/Arc evidence, and Graph observations with clear provenance and no retry shortcut. +An independently composable recovery slice shows authoritative state, attempts, +reconciliation, provider/Arc evidence, Subgraph MCP observations, the advisory +LLM recommendation, and deterministic core disposition with clear provenance +and no retry shortcut. ## Small tasks @@ -25,9 +28,12 @@ An independently composable recovery slice shows authoritative state, attempts, - Label local, Privy, Arc, and The Graph source plus authority class. - Show verified transaction binding and contradiction warnings without raw sensitive payloads. -### C05.3 — Graph freshness and candidate state +### C05.3 — Subgraph MCP, agent, and candidate state -- When enabled, display provider/deployment identity, observed-through block/time, chain-head lag, health errors, and unavailable state; hide the section cleanly when the C01 fallback disables Graph. +- When enabled, display Subgraph MCP as the retrieval path, tool/provider/deployment + identity, observed-through block/time, chain-head lag, health errors, and + unavailable state; hide it cleanly when C01 selects the fallback. +- Display the LLM recommendation separately from deterministic core disposition and authoritative result. - Empty result reads “not observed through block N,” never “not paid.” ### C05.4 — UNKNOWN experience @@ -37,7 +43,9 @@ An independently composable recovery slice shows authoritative state, attempts, ### C05.5 — Component tests -- Cover fresh, empty, lagging, unhealthy, unavailable, contradictory, pending, committed, failed-safe, and aged-UNKNOWN fixtures. +- Cover all four recommendations, invalid output, fresh, empty, lagging, + unhealthy, unavailable, contradictory, pending, committed, failed-safe, and + aged-UNKNOWN fixtures. - Test malicious evidence strings, accessibility, keyboard, responsive layout, lint, type, and build. ## Acceptance evidence diff --git a/milestones/coder-c/C06-qualification-demo.md b/milestones/coder-c/C06-qualification-demo.md index d585350..38512c2 100644 --- a/milestones/coder-c/C06-qualification-demo.md +++ b/milestones/coder-c/C06-qualification-demo.md @@ -7,9 +7,10 @@ Project convergence: Gate P6 ## Outcome -A repeatable recovery demo proves The Graph can discover a candidate after the -transaction hash is lost, Arc can verify the exact final transfer, and OneShot -can resolve or safely hold `UNKNOWN` without a second payment. +A repeatable recovery demo proves an LLM Recovery Agent can use live OneShot/Arc +Subgraph data obtained through Subgraph MCP to discover/select a candidate after +the transaction hash is lost, while Arc and the deterministic OneShot safety +core verify or safely hold `UNKNOWN` without a second payment. ## Small tasks @@ -20,12 +21,16 @@ can resolve or safely hold `UNKNOWN` without a second payment. the chain receives the real payment while the durable intent records only `UNKNOWN`; do not delete a hash that OneShot already persisted. - Query the original Privy request; deliberately exercise the branch where no transaction hash is recovered. -- Query live The Graph data for candidate transfers and record sanitized deployment, observed block, lag, health, and candidate count. +- Through Subgraph MCP, query the pinned live OneShot/Arc deployment for + candidates and record a sanitized tool trace with deployment, observed block, + lag, health, and candidate count. +- Show the LLM materially using that tool result to emit one allowed recommendation with evidence references. - Verify the selected candidate through exact Arc Testnet receipt/log evidence. ### C06.2 — Recovery story -- Show The Graph discovering the candidate, Arc proving it, and OneShot deciding the durable transition. +- Show Subgraph MCP returning candidates, the LLM selecting/explaining them, + Arc proving the exact transfer, and the deterministic core deciding the durable transition. - Show the operator view before recovery with no transaction hash, then after recovery with the discovered hash, exact transfer evidence, and unchanged Business Intent identity. @@ -33,7 +38,9 @@ can resolve or safely hold `UNKNOWN` without a second payment. ### C06.3 — Graph removal and degradation story -- Run recovery with The Graph disabled, then delayed, empty, unhealthy, unavailable, missing freshness metadata, and returning multiple/contradictory candidates. +- Run recovery with The Graph disabled, then delayed, empty, unhealthy, + unavailable, missing freshness metadata, malformed/injected MCP output, + multiple/contradictory candidates, and invalid model output. - Show safe hold/escalation and accurate observed-through language. ### C06.4 — Audit and repeatability @@ -43,20 +50,25 @@ can resolve or safely hold `UNKNOWN` without a second payment. ### C06.5 — Sponsor qualification -- Run `sponsor-qualification` against actual code, tests, live demo, network, deployment, and known limitations. +- Run `sponsor-qualification` against actual code, tests, live Subgraph MCP trace, + meaningful LLM decision, deterministic safety proof, network, deployment, and limitations. - Report Privy, Arc, and The Graph individually as `QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`; target the Graph AI Tooling or AI Use Case track only. - Never treat plans, mocks, variables, labels, or dependency declarations as proof. ## Acceptance evidence -- Live The Graph data demonstrably enables hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup. +- Live The Graph data obtained through Subgraph MCP demonstrably enables + hashless discovery and meaningful LLM recovery automation beyond direct known-hash lookup. +- The agent exposes only four advisory actions, and the deterministic core independently enforces the final domain action. - OneShot remains authoritative and Graph degradation never unlocks settlement. - Demo is repeatable and evidence is sanitized. - Qualification verdicts cite concrete code, test, and live evidence or honestly remain `NOT VERIFIED`. ## Handoff artifact -Publish recovery evidence index, Graph deployment/health/value snapshot, degraded-state matrix, demo steps, qualification report, and limitations. +Publish recovery evidence index, sanitized Subgraph MCP tool trace, agent/core +decision trace, Graph deployment/health/value snapshot, degraded-state matrix, +demo steps, qualification report, and limitations. ## No-wait continuation diff --git a/milestones/coder-c/README.md b/milestones/coder-c/README.md index 6677c12..b6ef661 100644 --- a/milestones/coder-c/README.md +++ b/milestones/coder-c/README.md @@ -1,18 +1,20 @@ # Coder C Lane — Reconciliation and Recovery Evidence -Mission: implement The Graph as the hashless candidate-discovery path behind a -provider-neutral contract, reconcile ambiguous settlement evidence without -submitting payments, build failure-injection proof, render recovery UI, and -assemble qualification evidence. +Mission: implement the live OneShot/Arc Subgraph through Subgraph MCP as the +hashless candidate-discovery path, let an LLM Recovery Agent emit a bounded +four-action recommendation, enforce it through deterministic zero-submit +reconciliation, build failure-injection proof, render recovery UI, and assemble +qualification evidence. Stay inside C-owned paths. The reconciliation package emits frozen commands; it never writes A’s tables directly and never calls SettlementPort. ## Technology focus -Provider-neutral evidence contracts, `viem` read models, Vitest, deterministic -failure injection, React/Vite recovery components, and a GraphQL/Subgraph -adapter admitted only after C01 proves live discovery and safe degradation. +Provider-neutral evidence contracts, Subgraph MCP, structured LLM output, +`viem` read models, Vitest, deterministic failure injection, React/Vite recovery +components, and a Subgraph adapter admitted only after C01 proves live discovery +and safe degradation. ## Sequence @@ -23,6 +25,6 @@ adapter admitted only after C01 proves live discovery and safe degradation. 5. [C05 — Frontend recovery](C05-frontend-recovery.md), held until project Gate P4 6. [C06 — Qualification demo](C06-qualification-demo.md) -C01–C04 close against frozen local, Privy, Arc, and Graph fixtures. -A/B implementations and live Graph evidence are project-gate inputs, -not reasons to stop local progress. \ No newline at end of file +C01–C04 close against frozen local, Privy, Arc, Graph/MCP, and agent fixtures. +A/B implementations, live Graph evidence, and external model access are +project-gate inputs, not reasons to stop local progress. diff --git a/plan.md b/plan.md index e4016e1..ee6e736 100644 --- a/plan.md +++ b/plan.md @@ -3,7 +3,7 @@ Status: working testnet MVP and mainnet-readiness roadmap Team: exactly three coders Implementation base: the human-approved commit containing this plan -Research basis: `.agent/research/20260906-integration-decisions.md` +Research basis: `.agent/research/20260906-integration-decisions.md` and `.agent/research/20260907-subgraph-mcp-clarification.md` Detailed work packets: [`milestones/README.md`](milestones/README.md) Domain architecture: [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md) @@ -37,10 +37,14 @@ Business Intent contract. Transfer before recording `COMMITTED`. 6. A timeout, crash, or lost response becomes durable `UNKNOWN`. Reconciliation first asks Privy for the original transaction identity. When the hash is - missing, The Graph searches live indexed transfers for candidates; Arc then + missing, an LLM Recovery Agent queries the live OneShot/Arc Subgraph through + Subgraph MCP and uses the indexed data to select/explain candidates. It emits + only `WAIT`, `RECONCILE`, `ESCALATE`, or `RETURN_EXISTING_RESULT`. +7. The deterministic OneShot safety core validates the recommendation, and Arc verifies each candidate receipt and exact Transfer. No candidate, multiple - candidates, stale data, or contradiction leaves the intent `UNKNOWN`. -7. Repeated HTTP requests, queue deliveries, processes, or agents return the + candidates, stale/malformed data, invalid model output, or contradiction + leaves the intent `UNKNOWN`; the LLM never receives settlement permission. +8. Repeated HTTP requests, queue deliveries, processes, or agents return the same Business Intent and cannot create a second committed settlement. ## Sponsor and product configuration @@ -49,7 +53,10 @@ The primary product configuration is **Privy + Arc + The Graph**: - Privy authorizes and constrains the corporate wallet action. - The Graph discovers candidate transfers when a successful submission lost its - transaction hash or provider response. + transaction hash or provider response. The production path reaches the live + OneShot/Arc Subgraph through Subgraph MCP, not a direct application GraphQL client. +- The LLM Recovery Agent uses MCP results for meaningful candidate selection and + explanation, then emits one of four advisory recovery actions. - Arc verifies the candidate receipt and exact USDC `Transfer`. - OneShot and PostgreSQL alone decide the durable state transition. @@ -59,23 +66,25 @@ prove its live data, freshness, and candidate-selection behavior before the sponsor claim is made. The Graph submission targets the AI Tooling or AI Use Case track. One custom -Subgraph does not satisfy the Composable/Standardized track. The recovery agent -uses live Graph data to choose and explain candidates; deterministic Arc checks -and the OneShot state machine retain all financial authority. +Subgraph does not satisfy the Composable/Standardized track. One live Subgraph +is sufficient for the selected AI track. The recovery agent uses live Graph data +obtained through Subgraph MCP to choose and explain candidates; deterministic +Arc checks and the OneShot state machine retain all financial authority. ```mermaid flowchart LR Unknown[UNKNOWN after lost response] --> Provider{Privy returns original hash} Provider -->|yes| Verify[Verify on Arc] - Provider -->|no| Discover[The Graph searches wallet, recipient, amount, and block window] - Discover --> Candidates{Candidate set} - Candidates -->|one bindable candidate| Verify - Candidates -->|none, many, stale, or contradictory| Hold[Remain UNKNOWN and escalate] + Provider -->|no| Subgraph[Live OneShot Arc Subgraph] + Subgraph --> MCP[Subgraph MCP] + MCP --> RecoveryAgent[LLM Recovery Agent] + RecoveryAgent -->|RETURN_EXISTING_RESULT with candidate refs| Verify + RecoveryAgent -->|WAIT / RECONCILE / ESCALATE| Hold[Remain UNKNOWN or run read-only recovery] Verify -->|exact final Transfer| Commit[COMMITTED] Verify -->|not safely resolved| Hold ``` -The Graph discovers candidates, not truth. Arc RPC can also scan logs without a +The Graph and the LLM discover candidates, not truth. Arc RPC can also scan logs without a hash, so Graph is not mathematically indispensable; it is the selected product dependency for fast, structured, automatic recovery. Empty, lagging, unhealthy, or multiple candidate results keep the intent `UNKNOWN`. @@ -109,11 +118,13 @@ flowchart LR Worker -->|authorized transfer request| Privy Privy -->|ERC-20 USDC transaction| Arc[Arc] Arc -->|one settlement| SupplierWallet[Supplier wallet] - Arc --> History[The Graph candidate index] + Arc --> History[Live OneShot Arc Subgraph] DB --> Recovery[Recovery service and view] Recovery -->|provider lookup| Privy Recovery -->|receipt and log lookup| Arc - Recovery -->|candidate query and freshness| History + History --> MCP[Subgraph MCP] + MCP -->|validated live candidates and freshness| RecoveryAgent[LLM Recovery Agent] + RecoveryAgent -->|four-action recommendation| Recovery Recovery --> Agent Recovery --> Company ``` @@ -161,11 +172,11 @@ This plan optimizes for five properties: - A valid intent can produce one real ERC-20 USDC transfer on Arc Testnet and persist a verified receipt and Transfer identity. - A timeout, disconnect, lost response, or crash after possible submission produces durable `UNKNOWN`; a new payment is forbidden until authoritative reconciliation resolves it. - Ten sequential retries, ten parallel workers, restart recovery, queue redelivery, and two agent instances never produce more than one committed settlement. -- Privy/direct Arc lookup resolves known transaction identities. The Graph enables automatic hashless candidate discovery; its absence, delay, multiple matches, or contradiction never authorizes payment. +- Privy/direct Arc lookup resolves known transaction identities. The LLM Recovery Agent queries The Graph through Subgraph MCP for automatic hashless candidate discovery; absence, delay, malformed/injected output, multiple matches, contradiction, or invalid model output never authorizes payment. - Money remains a canonical integer string at JSON boundaries and `bigint` internally, using six-decimal ERC-20 USDC atomic units. - The demo proves working Privy and Arc integrations with sanitized testnet evidence and no exposed secrets. - A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while official Arc Mainnet values remain disabled until published and human-approved. -- The Graph sponsor claim is retained only when live evidence proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup. +- The Graph sponsor claim is retained only when a sanitized live Subgraph MCP trace proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. ## 4. Scope @@ -175,7 +186,8 @@ This plan optimizes for five properties: - Privy execution-wallet authorization and fail-closed wallet policy. - Arc Testnet ERC-20 USDC request construction, submission, receipt verification, and explorer evidence. - Durable reconciliation using OneShot state, Privy identifiers/status, and direct Arc RPC receipts/logs. -- Provider-neutral candidate-index port, The Graph deployment/health contract, and freshness/multiple-candidate classification. +- Provider-neutral candidate-index port, deployment-pinned Subgraph MCP adapter, The Graph deployment/health contract, and freshness/multiple-candidate classification. +- LLM Recovery Agent with structured four-action output and a deterministic, fail-closed OneShot safety core. - Contract simulators, failure injection, concurrency and restart testing, structured logs, metrics, and operator runbooks. - Minimal operator/user frontend after backend acceptance. - Arc Mainnet configuration seam, deployment manifest, readiness probe, safe-disable and rollback runbooks, with real-value execution disabled until official values and explicit human authorization exist. @@ -183,7 +195,7 @@ This plan optimizes for five properties: ### Excluded - Actual mainnet value transfer before Arc publishes official production access/addresses and a human authorizes the operation; additional chains/assets, swaps, bridges, fiat rails, automatic transaction replacement, and unrestricted payment overrides. -- Any external indexer as duplicate lock, durable intent store, or proof that another settlement is safe. +- Any external indexer, Subgraph MCP, or LLM as duplicate lock, durable intent store, settlement authority, or proof that another settlement is safe. - General workflow automation, arbitrary supplier/ERP integrations, native mobile clients, production compliance certification, or multi-region HA. - UI polish that is not necessary to demonstrate the invariant and sponsor requirements. @@ -228,13 +240,13 @@ activate real-value execution. | EVM encoding and RPC | `viem` for typed addresses, calldata, chain access, receipt reads, and log verification | | Authorization | Privy Node SDK, execution wallet, scoped wallet policy, persisted idempotency key, and reference identity | | Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are enabled for live proof; the Arc Mainnet profile is structurally complete but disabled until official chain/token values are published, pinned, verified, and human-approved | -| Hashless discovery | `IndexViewPort` is provider-neutral; The Graph is the selected v1 adapter for live candidate discovery. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | +| Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; a deployment-pinned Subgraph MCP adapter is the selected v1 path to the live OneShot/Arc Subgraph. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | | Money | Canonical integer strings at JSON boundaries and `bigint` internally; no JavaScript monetary floats | | Frontend | React and Vite, generated OpenAPI client, exact integer amount formatting, and no direct settlement capability | | Testing | Vitest for unit/contract tests, Testcontainers for PostgreSQL integration, Playwright for browser flows, deterministic failure simulators, and Graph adapter/degradation tests | | Local and CI | Docker Compose for reproducible local services and GitHub Actions for install, lint, type, test, build, migration, contract, and policy checks | | Submission jobs | One queue attempt; the task persists `COMMITTED`, `FAILED_SAFE`, or `UNKNOWN` before returning | -| Recovery authority | PostgreSQL state and verified Arc evidence are authoritative; Privy may locate the original request; The Graph supplies freshness-labeled candidates and never grants settlement permission | +| Recovery authority | PostgreSQL state and verified Arc evidence are authoritative; Privy may locate the original request; Subgraph MCP supplies freshness-labeled Graph candidates to the LLM; the deterministic core constrains every recommendation and neither MCP nor the model grants settlement permission | Exact dependency versions are pinned only after A01/B01 compatibility spikes. The exact v1 contracts, state table, fixture catalog, redaction rules, and change @@ -254,27 +266,50 @@ flowchart TB Outbox --> RecoveryWorker[Reconciliation worker] Worker --> Domain RecoveryWorker --> Reconciliation[packages/reconciliation] - Reconciliation --> Command[Versioned reconciliation command] + Reconciliation --> SafetyCore[Deterministic recovery safety core] + SafetyCore --> Command[Versioned reconciliation command] Command --> Domain Domain --> AuthPort[AuthorizationPort] Domain --> SettlementPort[SettlementPort] Reconciliation --> EvidencePort[EvidencePort] Reconciliation --> IndexPort[IndexViewPort] + Reconciliation --> AdvisorPort[RecoveryAdvisorPort] AuthPort --> PrivyAdapter[packages/privy-adapter] SettlementPort --> ArcAdapter[packages/arc-adapter] EvidencePort --> PrivyAdapter EvidencePort --> ArcAdapter - IndexPort -.-> HistoryAdapter[packages/history-adapter] + IndexPort -.-> MCPAdapter[packages/subgraph-mcp-adapter] + AdvisorPort --> RecoveryAgent[packages/recovery-agent] PrivyAdapter --> Privy[Privy wallet and policy] ArcAdapter --> Arc[Arc USDC and RPC] - HistoryAdapter --> GraphIndex[The Graph candidate index] + RecoveryAgent --> MCPAdapter + MCPAdapter --> MCP[Subgraph MCP] + MCP --> GraphIndex[Live OneShot Arc Subgraph] GraphIndex -.-> Arc ``` -OneShot decides whether settlement may be attempted. Privy constrains authorized wallet actions. Arc provides final settlement evidence. Direct Privy/Arc lookup resolves known transaction identities. The Graph is the selected automatic discovery path when that identity is lost; it proposes candidates but grants no settlement right. Detailed entity, state, sequence, and ownership diagrams live in [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md). +The selected recovery path is explicit: + +```text +The Graph Subgraph + ↓ +Subgraph MCP + ↓ +LLM Recovery Agent + ↓ +WAIT / RECONCILE / ESCALATE / RETURN_EXISTING_RESULT + ↓ +deterministic OneShot safety core +``` + +`WAIT` preserves uncertainty. `RECONCILE` requests another read-only evidence +cycle. `ESCALATE` requests operator attention. `RETURN_EXISTING_RESULT` supplies +candidate references that the core must independently verify using current +OneShot/Arc evidence. None is a submit or retry command. Detailed entity, state, +sequence, and ownership diagrams live in [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md). ## 7. Team topology and exclusive ownership @@ -311,7 +346,8 @@ Coder B never changes domain tables or state meanings directly. Owns: - `packages/reconciliation` -- optional `packages/history-adapter` after the C01 decision +- `packages/recovery-agent` +- `packages/subgraph-mcp-adapter` after the C01 live-value decision - `packages/testkit-failures` - `subgraph/` after The Graph passes the C01 live discovery and qualification gate - recovery-view schemas and queries @@ -403,8 +439,8 @@ silently changes a contract. | [B04](milestones/coder-b/B04-ambiguity-integration.md) | B | B03 | Conservative outcomes and production adapter pack | | [B05](milestones/coder-b/B05-frontend-settlement-details.md) | B | B04 + project Gate P4 | Authorization/settlement UI slice against fixtures | | [B06](milestones/coder-b/B06-sponsor-evidence.md) | B | B05 | Privy/Arc sanitized evidence bundle | -| [C01](milestones/coder-c/C01-recovery-evidence-strategy.md) | C | Frozen contract pack | Recovery evidence contract and indexer value decision | -| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | C01 | Deterministic reconciliation and evidence contract | +| [C01](milestones/coder-c/C01-recovery-evidence-strategy.md) | C | Frozen contract pack | Recovery evidence contract and live Subgraph MCP value decision | +| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | C01 | LLM recommendations plus deterministic reconciliation contract | | [C03](milestones/coder-c/C03-failure-injection.md) | C | C02 | Cross-source chaos and restart harness | | [C04](milestones/coder-c/C04-recovery-matrix-integration.md) | C | C03 | Recovery matrix and simulator integration pack | | [C05](milestones/coder-c/C05-frontend-recovery.md) | C | C04 + project Gate P4 | Recovery timeline UI slice against fixtures | @@ -478,7 +514,7 @@ This is the frontend unlock gate. - One real allowed Arc Testnet payment commits exactly once through Privy. - Wrong-scope and above-cap cases produce zero settlement. - A lost-response scenario reaches `UNKNOWN` and reconciles to the original transaction without a duplicate. -- The lost-hash scenario uses live The Graph data to discover candidates, direct Arc evidence to verify the bound transaction, and no second submission; stale, empty, multiple, or contradictory candidates remain `UNKNOWN`. +- The lost-hash scenario queries live The Graph data through Subgraph MCP, shows the LLM selecting/explaining candidates, uses direct Arc evidence to verify the bound transaction, and makes no second submission; stale, empty, malformed, injected, multiple, contradictory, or invalid-model results remain `UNKNOWN`. - OpenAPI and recovery-view semantics are frozen for frontend. ### P5 — frontend acceptance @@ -508,7 +544,7 @@ This is the frontend unlock gate. | Crash before submission | A | Worker kill point | P4 zero external settlement | | Crash after possible submission | B | Adapter fault fixture | P4 durable `UNKNOWN` | | Lost payment response | B | Proxy/fixture | P4 original transaction reconciled | -| Graph delay/absence/multiple candidates | C | Provider-neutral Graph simulator | P4 remain `UNKNOWN`; no submission grant | +| Graph/MCP delay, absence, malformed data, multiple candidates, or invalid LLM output | C | Provider-neutral MCP/agent simulator | P4 remain `UNKNOWN`; no submission grant | | Privy denial/above cap | B | Policy fixture/live-ready harness | P4 zero settlement | | Service restart | A | Process orchestration | P4 evidence durability | | Downstream failure after payment | A | Supplier fake | P4 original receipt retained | @@ -522,7 +558,7 @@ After P4, the three frontend packets remain independent: - A05 owns application shell, create/replay/conflict, and authoritative status. - B05 owns policy, authorization, transaction, and explorer details. -- C05 owns recovery timeline, evidence provenance, Graph freshness/candidate state, and escalation. +- C05 owns recovery timeline, evidence provenance, Subgraph MCP/agent trace, Graph freshness/candidate state, and escalation. Each slice is built against the frozen mock server. Final composition is a project gate, not a packet closure requirement. @@ -537,7 +573,7 @@ Each slice is built against the frozen mock server. Final composition is a proje ## 16. Human-only external configuration -Coder B produces a repeatable setup guide or wizard, but a human performs Privy application/wallet/key-quorum/policy creation, Arc Testnet funding, any selected index-provider credential entry, Mainnet profile activation, and CI-secret configuration. +Coder B produces a repeatable setup guide or wizard, while Coder C documents Graph deployment and Subgraph MCP/model configuration. A human performs Privy application/wallet/key-quorum/policy creation, Arc Testnet funding, every gateway/model credential entry, Mainnet profile activation, and CI-secret configuration. - Secret input is hidden and written only to ignored runtime files or approved secret stores. - Public network, contract, deployment, and policy identifiers are separated from secrets. @@ -547,7 +583,7 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy ## 17. Observability and operations -- Correlation fields: Business Intent ID, Attempt ID, settlement version, Privy reference/transaction ID, Arc transaction hash, active network profile, and Graph deployment/observed block. +- Correlation fields: Business Intent ID, Attempt ID, settlement version, Privy reference/transaction ID, Arc transaction hash, active network profile, Graph deployment/observed block, MCP request/tool identity, and recovery-agent decision identity. - Never log signatures, credentials, private keys, raw authorization bodies, or private wallet material. - Metrics: intent states, oldest/count `UNKNOWN`, transition conflicts, queue lag, reconciliation outcomes, policy denials, provider/RPC errors, Graph lag/health/candidate count, duplicate and conflict counts. - Safe disable stops new submission ownership while preserving status, evidence ingestion, and reconciliation reads. @@ -562,7 +598,8 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy | ERC-20/native precision confusion | Six-decimal ERC-20 is the only settlement amount; native balance is gas only | B/C | | Lost response after broadcast | Persist identity first, enter `UNKNOWN`, reconcile, forbid another payment | All | | Pending/evicted Arc transaction | Hold `UNKNOWN`; no automatic replacement in v1 | B/C | -| Graph lag/error/empty/multiple result | Surface freshness and candidate ambiguity; never infer non-payment | C | +| Graph/MCP lag, error, empty/malformed/multiple result | Surface provenance, freshness, and candidate ambiguity; never infer non-payment | C | +| Prompt injection or unsupported LLM action | Treat tool content as untrusted data; validate the four-action structured output and fail closed | C | | Queue redelivery | Domain CAS/constraints plus single-attempt submission task | A | | Shared-file conflicts | Exclusive path ownership and A-only root composition | A | | Credentials unavailable | Offline contract packs and simulators remain sufficient for packet closure | B | @@ -596,12 +633,12 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy | B04 | Conservative handling of provider ambiguity | Fault taxonomy and lookup contract suite | | B05 | Safe authorization/transaction UI | Fixture-driven component and redaction tests | | B06 | Verifiable Privy/Arc sponsor evidence | Policy denial and real transfer evidence bundle | -| C01 | Minimal recovery evidence strategy with an explicit indexer decision | Removal/value matrix and provider-neutral contract tests | -| C02 | Deterministic zero-submit reconciliation | Complete evidence/decision matrix | +| C01 | Minimal recovery evidence strategy with an explicit Subgraph MCP decision | Removal/value matrix, live MCP spike, and provider-neutral contract tests | +| C02 | Meaningful AI recovery within deterministic zero-submit reconciliation | Four-action recommendation matrix and safety-core tests | | C03 | Safety under loss, lag, contradiction, and restart | Seeded failure-injection suite | | C04 | Recovery service ready for real adapter replacement | Simulator composition and matrix report | | C05 | Accurate recovery/evidence UI | Degraded-evidence component tests | -| C06 | Verifiable recovery and conditional-index evidence | Live recovery, degraded demo, qualification report | +| C06 | Verifiable Subgraph MCP/AI recovery evidence | Live MCP/agent/core trace, degraded demo, qualification report | Every success criterion in Section 3 has at least two independent proof surfaces: a producer packet and a later project-gate verification. Packet closure establishes the producer proof; it never claims final integrated behavior by itself. @@ -622,7 +659,7 @@ Purpose: default mode for every coder packet. Purpose: compose reviewed packages with PostgreSQL and local services before external effects. - Uses real PostgreSQL and Graphile Worker. -- Replaces Privy, Arc, and The Graph network access with simulators. +- Replaces Privy, Arc, The Graph/Subgraph MCP, and LLM network access with deterministic simulators. - Runs migrations, API/worker orchestration, concurrency, restart, failure, and recovery suites. - Remains the fallback when external providers are unavailable. @@ -630,7 +667,7 @@ Purpose: compose reviewed packages with PostgreSQL and local services before ext Purpose: Gate P4 and P6 live proof. -- Requires human-approved Privy/Arc and any selected index-provider configuration in ignored/approved secret stores. +- Requires human-approved Privy/Arc, Graph/Subgraph MCP, and LLM configuration in ignored/approved secret stores. - Checks Arc chain/token/policy/deployment identities before running. - Limits settlement to an approved recipient and cap. - Produces sanitized public identifiers and result tables only. @@ -641,7 +678,7 @@ Purpose: Gate P4 and P6 live proof. Purpose: independently close A05/B05/C05. - Uses the P4-frozen OpenAPI and sanitized response fixtures. -- Simulates every authoritative, provider, Arc, and Graph state. +- Simulates every authoritative, provider, Arc, Graph/MCP, and recovery-agent state. - Contains no provider credentials or direct settlement capability. - Must behave identically to production UI for state labeling and disabled actions. @@ -652,15 +689,15 @@ P4 is deliberately procedural so convergence does not turn into open-ended share 1. Record exact reviewed A04, B04, and C04 package versions and tree SHAs. 2. Coder A creates the single composition branch from the approved integration base. 3. Replace the settlement simulator with B04’s public package entry point; run contract compatibility before any live call. -4. Replace the recovery/evidence simulators with C04 public entry points; run command/evidence compatibility. +4. Replace the recovery/evidence, Subgraph MCP, and LLM simulators with C04 public entry points; run tool/evidence/recommendation/command compatibility. 5. Run offline root checks first. A contract mismatch stops composition and opens one owner-specific compatibility ticket. 6. Run empty and upgrade migrations, API/worker boot, readiness, and safe-disable checks. 7. Run the complete local failure matrix with real packages but simulated external services. -8. A human enables testnet evidence mode and confirms network, token, wallet, policy, recipient, cap, funding, and the Graph deployment. -9. Execute one allowed intent, discard the returned transaction hash at the fault boundary, discover it through live The Graph data, and bind durable identity, Privy identity, Arc receipt/Transfer, and Graph freshness. +8. A human enables testnet evidence mode and confirms network, token, wallet, policy, recipient, cap, funding, Graph deployment, MCP target, and LLM configuration. +9. Execute one allowed intent, discard the returned transaction hash at the fault boundary, query live The Graph data through Subgraph MCP, show the LLM candidate recommendation, and bind durable identity, Privy identity, Arc receipt/Transfer, Graph freshness, and deterministic-core disposition. 10. Execute wrong-scope and above-cap denials; confirm zero settlements. 11. Inject a lost local response after possible broadcast; confirm durable `UNKNOWN`, zero replacement transaction, and reconciliation to original evidence. -12. Simulate empty, lagging, unhealthy, unavailable, multiple, and contradictory Graph candidates; confirm `UNKNOWN` and no permission change. +12. Simulate empty, lagging, unhealthy, unavailable, malformed/injected, multiple, and contradictory MCP candidates plus invalid LLM output; confirm `UNKNOWN` and no permission change. 13. Publish a sanitized Gate P4 manifest and freeze OpenAPI/recovery-view semantics. P4 failures never produce ad hoc edits by multiple coders on the composition branch. The owning coder fixes their package in a focused branch, republishes a reviewed version, and A updates only the version slot. @@ -671,7 +708,7 @@ P4 failures never produce ad hoc edits by multiple coders on the composition bra - A owns root package manager files, shared compiler/lint/test configuration, OpenAPI, migrations, API, worker, contracts, and domain/storage packages. - B owns only provider/chain adapter packages, provider fixtures, and human provider setup docs. -- C owns only reconciliation/failure packages, recovery docs, and the Graph adapter/Subgraph after C01. +- C owns only reconciliation/recovery-agent/Subgraph-MCP/failure packages, recovery docs, and the Subgraph after C01. - Frontend composition reserves one shell/route registry editor; B/C expose components through documented entry points instead of editing the registry concurrently. ### Commit controls @@ -700,7 +737,7 @@ Continue asynchronously with a documented conservative assumption for ordinary i - when `UNKNOWN` may transition to `FAILED_SAFE`; - Privy policy scope or bypass availability; - Arc network/token identity; -- the non-authoritative role of any external indexer; +- the non-authoritative role of any external indexer, Subgraph MCP, or LLM, or the four-action allowlist; - use of non-testnet funds or irreversible external configuration; - public API breaking compatibility after P4. @@ -725,7 +762,7 @@ Never cut: - denial/zero-settlement proof; - concurrency, restart, and lost-response tests; - exact Arc receipt/Transfer verification; -- Graph freshness/candidate labeling and non-authority; +- Graph freshness/candidate labeling, live Subgraph MCP use, meaningful LLM reasoning, and deterministic non-authority; - secret/redaction checks; - independent review and human merge controls. From d8cb5d3e6015d500ca74c4137681f9b1894953c2 Mon Sep 17 00:00:00 2001 From: selezenart Date: Mon, 7 Sep 2026 01:59:33 +0200 Subject: [PATCH 2/4] docs(plan): map sponsor claims and Arc qualification Add an explicit sponsor claim mapping across the three partner slots, naming each claimed track and recording why the Composable/Standardized Graph and Circle Agent Stack tracks are deliberately not claimed. Add section 5b covering Arc qualification: every Arc requirement mapped to an owner and artifact, the four-screen minimum qualifying frontend marked non-cuttable, an early OpenAPI freeze so frontend slices can start against the mock ahead of live proof, and the deliberate thin Circle tool surface. State the mainnet-readiness position against Arc public mainnet opening 16 September 2026 on chain 5042, after the submission deadline. The build targets deployment-ready, with MAINNET_READINESS.md as the single reviewer-facing artifact and real-value execution disabled pending explicit human authorization. Extend section 18 risks and the Gate P6 checklist to cover the new claims. --- .../20260906T230709Z-plan-clarification.md | 23 ++- plan.md | 141 +++++++++++++++++- 2 files changed, 153 insertions(+), 11 deletions(-) diff --git a/.agent/context/20260906T230709Z-plan-clarification.md b/.agent/context/20260906T230709Z-plan-clarification.md index 1020da6..ccbf09f 100644 --- a/.agent/context/20260906T230709Z-plan-clarification.md +++ b/.agent/context/20260906T230709Z-plan-clarification.md @@ -75,15 +75,26 @@ deterministic safety core. Repository: https://github.com/SWOFART/OneShot/. - Branch: `plan-clarification` - Base: `origin/develop` at `d256e5360247ba5c0dfd1901470a0ad8c7a46068` -- Commit: uncommitted -- PR: not created -- CI: not run; no pushed head +- 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: pending; user requested exactly one `npx free-pi-cli` consistency review -- Gate B: NOT RUN; no PR requested +- 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. Review the local diff and decide whether to request commit/push/PR. +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. diff --git a/plan.md b/plan.md index ee6e736..8b05174 100644 --- a/plan.md +++ b/plan.md @@ -71,6 +71,31 @@ is sufficient for the selected AI track. The recovery agent uses live Graph data obtained through Subgraph MCP to choose and explain candidates; deterministic Arc checks and the OneShot state machine retain all financial authority. +### Sponsor claim mapping + +Three partner slots. A partner with several tracks counts as one slot and the +project is eligible for all of that partner's tracks. The submission text must +name each claimed track explicitly. + +| Slot | Claimed track | Basis in this plan | +| --- | --- | --- | +| The Graph | AI Tooling or AI Use Case (From Scratch) | Live OneShot/Arc Subgraph read through Subgraph MCP; the LLM recovery agent performs candidate selection and explanation | +| Privy | Best B2B financial product | Corporate execution wallet, scoped policy, and a real accounts-payable workflow | +| Privy | Best financial flow | The committed USDC transfer is a completed financial flow through a Privy wallet action | +| Arc | Launch on Arc Testnet & Push to Mainnet | Primary Arc claim: working testnet product plus the disabled Mainnet profile, deployment manifest, readiness probe, and rollback runbooks | +| Arc | Best DeFi / Onchain Finance Application | Secondary Arc claim: conditional, multi-step USDC settlement on Arc with programmable authorization | + +Not claimed, and the reason: + +- **Composable or Standardized Graph Products.** One custom Subgraph does not + compose two Graph products and does not build on a standardized schema. The + track text states this does not qualify. +- **Best Agentic Economy Application with Circle Agent Stack.** Wallet + authorization and payment execution run through Privy, not the Circle Agent + Stack, and the calling agent executes an approved obligation rather than + making autonomous spending decisions. Claiming this track would misrepresent + the build. + ```mermaid flowchart LR Unknown[UNKNOWN after lost response] --> Provider{Privy returns original hash} @@ -163,7 +188,7 @@ This plan optimizes for five properties: 3. Low merge contention: each coder owns disjoint directories and shared files have a single editor. 4. Verifiable handoffs: ports, OpenAPI, schemas, fixtures, and simulators are versioned artifacts. 5. Late frontend: UI work consumes a stable backend contract instead of driving it. -6. Network promotion: testnet proves behavior; mainnet readiness proves the same boundaries can be configured safely when Arc publishes official production values. +6. Network promotion: testnet proves behavior; mainnet readiness proves the same boundaries can be configured safely on Arc public mainnet, which opens 16 September 2026 on chain `5042`. ## 3. Product success criteria @@ -174,8 +199,10 @@ This plan optimizes for five properties: - Ten sequential retries, ten parallel workers, restart recovery, queue redelivery, and two agent instances never produce more than one committed settlement. - Privy/direct Arc lookup resolves known transaction identities. The LLM Recovery Agent queries The Graph through Subgraph MCP for automatic hashless candidate discovery; absence, delay, malformed/injected output, multiple matches, contradiction, or invalid model output never authorizes payment. - Money remains a canonical integer string at JSON boundaries and `bigint` internally, using six-decimal ERC-20 USDC atomic units. +- The public repository contains the architecture diagram, setup and operator documentation, and no secrets in history. +- The submission text names each claimed partner track explicitly and states the Arc mainnet-readiness position. - The demo proves working Privy and Arc integrations with sanitized testnet evidence and no exposed secrets. -- A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while official Arc Mainnet values remain disabled until published and human-approved. +- A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while the Arc Mainnet profile stays disabled pending explicit human authorization. Arc public mainnet opens 16 September 2026, after the submission deadline. - The Graph sponsor claim is retained only when a sanitized live Subgraph MCP trace proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. ## 4. Scope @@ -190,7 +217,7 @@ This plan optimizes for five properties: - LLM Recovery Agent with structured four-action output and a deterministic, fail-closed OneShot safety core. - Contract simulators, failure injection, concurrency and restart testing, structured logs, metrics, and operator runbooks. - Minimal operator/user frontend after backend acceptance. -- Arc Mainnet configuration seam, deployment manifest, readiness probe, safe-disable and rollback runbooks, with real-value execution disabled until official values and explicit human authorization exist. +- Arc Mainnet configuration seam, deployment manifest, readiness probe, safe-disable and rollback runbooks, and the reviewer-facing `MAINNET_READINESS.md`, with real-value execution disabled until values are pinned, verified, and explicitly human-authorized. ### Excluded @@ -217,7 +244,7 @@ P0-P6 delivers testnet functionality and mainnet readiness. Actual production ac flowchart LR Local[Local and simulator proof] --> Testnet[Working Arc Testnet product] Testnet --> Ready[Disabled Arc Mainnet profile and deployment evidence] - Ready --> Values{Official Arc Mainnet values available} + Ready --> Values{Arc public mainnet live, values pinned and verified} Values -->|no| Hold[Remain testnet-only] Values -->|yes| Human{Human security and launch approval} Human -->|no| Hold @@ -239,7 +266,7 @@ activate real-value execution. | Work delivery | Graphile Worker over the same PostgreSQL database; at-least-once delivery is assumed | | EVM encoding and RPC | `viem` for typed addresses, calldata, chain access, receipt reads, and log verification | | Authorization | Privy Node SDK, execution wallet, scoped wallet policy, persisted idempotency key, and reference identity | -| Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are enabled for live proof; the Arc Mainnet profile is structurally complete but disabled until official chain/token values are published, pinned, verified, and human-approved | +| Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are enabled for live proof; the Arc Mainnet profile (chain `5042`, public launch 16 September 2026) is structurally complete but disabled until its values are pinned, verified, and human-approved | | Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; a deployment-pinned Subgraph MCP adapter is the selected v1 path to the live OneShot/Arc Subgraph. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | | Money | Canonical integer strings at JSON boundaries and `bigint` internally; no JavaScript monetary floats | | Frontend | React and Vite, generated OpenAPI client, exact integer amount formatting, and no direct settlement capability | @@ -252,6 +279,98 @@ Exact dependency versions are pinned only after A01/B01 compatibility spikes. The exact v1 contracts, state table, fixture catalog, redaction rules, and change protocol are frozen in [`milestones/CONTRACTS.md`](milestones/CONTRACTS.md). +## 5b. Arc qualification and evidence + +Both claimed Arc tracks share one requirement set. This section maps each +requirement to an owner and a concrete artifact so nothing is discovered late. + +| Arc requirement | Satisfied by | Owner | Artifact | +| --- | --- | --- | --- | +| Working backend | API, worker, PostgreSQL authority, Privy and Arc adapters | A/B | Gate P4 composition | +| Working frontend | A05, B05, C05 slices on React and Vite against the frozen OpenAPI | A/B/C | Gate P5 | +| Architecture diagram | Diagrams exported from this plan into the public repository README | A | `README.md` | +| Video demonstration and presentation | Scripted demo covering the invariant and Circle tool usage | B | Submission video, 2-4 minutes | +| Detailed documentation | README, setup guide, operator and recovery runbooks | A/B | Public repository | +| Public repository link | Public GitHub repository, secret-scanned history | A | Repository URL | +| Explicit bounty naming | Submission text names both claimed Arc tracks | B | Submission form | +| Mainnet deployment-readiness by 30 September | Disabled Mainnet profile, deployment manifest, readiness probe, rollback runbook | A/B | `MAINNET_READINESS.md` in the public repository | + +### Minimum Arc-qualifying frontend + +Arc requires a working frontend on every track, so the interface is a +qualification requirement and not optional polish. The minimum qualifying set +is: + +1. Create or reuse a Business Intent. +2. Read authoritative intent status. +3. View a committed settlement with its Arc explorer link. +4. View an `UNKNOWN` intent with its recovery timeline and evidence provenance. + +Anything beyond these four is cuttable. These four are not. + +### Early contract freeze for frontend start + +A05, B05, and C05 build against the frozen mock server and need no live +services. The real frontend blocker is therefore the OpenAPI freeze inside Gate +P4, not the live settlement proof. Freeze and publish the OpenAPI and +recovery-view semantics as soon as A04 stabilises them, ahead of live testnet +evidence, so frontend work can start while B is still obtaining live proof. + +Gate P4 remains the composition and live-proof gate. This rule changes only when +the contract is published, never what P4 must prove. + +### Circle developer-tool surface + +The project uses Arc and USDC directly. It does not use App Kits, Circle +Wallets, Circle Contracts, CCTP, Gateway, StableFX, Paymaster, or Nanopayments, +because wallet control and authorization run through Privy by design. + +The DeFi track lists App Kits only "where relevant", so this is permitted. It +is nevertheless a deliberate decision and must be defended in one sentence in +the submission: OneShot's contribution is settlement cardinality on Arc, and +adding a second wallet or payment product would duplicate the authorization +boundary that Privy already provides. + +Adding a Circle product solely to widen the logo surface is rejected. + +### Network constants + +Arc Testnet chain and token identities are pinned only after B01 verifies them +against official Arc documentation. Chain `eip155:5042002` and the USDC +interface address recorded in section 5 are treated as unverified inputs until +that check passes and is recorded in the B01 handoff. + +### Mainnet-readiness statement + +Arc public mainnet launches on 16 September 2026, chain ID `5042`, the day the +hackathon ends. The submission deadline is 13 September, so no team can be +deployed at submission time. The 30 September date is a post-launch window in +which reviewers verify the claim, not a deadline met inside the event. + +The Mainnet track accepts either state: deployed, or deployment-ready. This +build targets deployment-ready and treats actual deployment as an optional +upgrade the team may take after 16 September. + +Because verification happens after the event, readiness evidence must live in +the public repository rather than only in the submission form. +`MAINNET_READINESS.md` is the single reviewer-facing artifact and contains: + +- the pinned Arc mainnet chain, RPC, explorer, and USDC identities, or an + explicit note that a value awaits publication at launch; +- the deployment manifest and the exact commands that perform deployment; +- readiness-probe output showing every check passing against the disabled + profile; +- the rollback and safe-disable procedure; +- the current status line: `DEPLOYMENT-READY` or `DEPLOYED` with its evidence. + +Real-value execution stays disabled until a human authorizes activation. If the +team deploys after 16 September, only the status line and its evidence change; +no domain or contract work is required. + +The submission text states the readiness position plainly and points to this +file. + + ## 6. Architecture ```mermaid @@ -604,6 +723,11 @@ Coder B produces a repeatable setup guide or wizard, while Coder C documents Gra | Shared-file conflicts | Exclusive path ownership and A-only root composition | A | | Credentials unavailable | Offline contract packs and simulators remain sufficient for packet closure | B | | Scope pressure | Cut webhooks, rolling policy support, visual polish, and optional telemetry before safety | All | +| P4 slips and the frontend never ships | Publish the OpenAPI freeze early so frontend slices start against the mock; cut to the four minimum screens rather than dropping the interface | A | +| Arc network constants wrong or changed | B01 verifies chain, RPC, explorer, and USDC identities against official Arc docs before pinning; readiness probe re-checks them | B | +| Arc mainnet launches 16 September, after submission | Ship deployment-readiness evidence in `MAINNET_READINESS.md`; optional post-launch deployment changes only the status line | A/B | +| Readiness evidence not reachable after the event | Keep the reviewer-facing artifact in the public repository, not only in the submission form | A | +| Thin Circle tool surface questioned | Record the deliberate decision in section 5b and defend it in the submission rather than adding unused Circle products | B | ## 19. Definition of done for every packet @@ -755,6 +879,10 @@ If time is constrained, cut in this order: 4. Visual animation, theming, and secondary responsive polish; retain accessible core flows. 5. Arc Memo correlation if Privy cannot constrain the forwarded call; retain The Graph tuple/window discovery and strict authorization. +Sponsor-required scope is not on this list. A working frontend is an Arc +qualification requirement on every claimed Arc track. Cut inside the interface +down to the four minimum screens in section 5b, never the interface itself. + Never cut: - durable constraints and atomic submission ownership; @@ -804,6 +932,9 @@ Before Gate P6 can pass, confirm: - UI has no direct/bypass/force-pay action and labels authority/freshness correctly. - Demo/reset instructions require no unsafe database surgery or external-history rewrite. - Evidence, repository, logs, screenshots, fixtures, source maps, and reviews contain no secrets. +- Claimed partner tracks match the sponsor claim mapping in section 5. Composable/Standardized and Circle Agent Stack remain unclaimed. +- Every Arc requirement row in section 5b has a delivered artifact, including the README architecture diagram and the explicit track naming in the submission. +- Public README and submission text contain no statement that undermines a claimed dependency; justifications cite measured numbers. - Privy and Arc claims use the qualification standard. The Graph claim requires live hashless discovery plus meaningful recovery-agent automation; otherwise it is `NOT VERIFIED` and removed from the submission. - Mandatory FreePi gates and required CI apply to the exact candidate tree/head. - A human performs the final review and merge. From d6758ddd4d6626193b2b97bed72b7db883d97e10 Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Mon, 7 Sep 2026 03:21:25 +0200 Subject: [PATCH 3/4] fix(plan): resolve review blockers on Mermaid, Arc chain ID, and Graph requirements --- .agent/SPONSOR_REQUIREMENTS.md | 28 ++++++++------ .../20260906T230709Z-plan-clarification.md | 3 +- .../20260907-subgraph-mcp-clarification.md | 3 +- .agents/skills/sponsor-qualification/SKILL.md | 18 +++++---- docs/DOMAIN_ARCHITECTURE.md | 2 +- milestones/CONTRACTS.md | 10 +++-- .../coder-c/C01-recovery-evidence-strategy.md | 10 ++--- plan.md | 37 ++++++++++--------- 8 files changed, 61 insertions(+), 50 deletions(-) diff --git a/.agent/SPONSOR_REQUIREMENTS.md b/.agent/SPONSOR_REQUIREMENTS.md index 85c0cb0..285bb3d 100644 --- a/.agent/SPONSOR_REQUIREMENTS.md +++ b/.agent/SPONSOR_REQUIREMENTS.md @@ -31,24 +31,28 @@ The Graph is load-bearing for automatic recovery when a successful submission lost its transaction hash. It discovers candidates; Arc verifies them; OneShot 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. +- Target the AI Tooling or AI Use Case track (which permits Subgraphs, Subgraph MCP, + or Substreams). The recovery agent must use live Graph data for meaningful + candidate selection, explanation, and automation. +- `IndexViewPort` remains provider-neutral: direct GraphQL against the live + OneShot/Arc Subgraph is the minimal implementation path; Subgraph MCP is an + optional adapter chosen by OneShot, not a sponsor-mandated constraint. Mocks, + static fixtures, dependencies, or configuration entries alone are insufficient + without live Graph data and demonstrable AI impact. +- The LLM Recovery Agent must use the live Graph candidate observations (via direct + GraphQL or the Subgraph MCP adapter) to select `WAIT`, `RECONCILE`, `ESCALATE`, + or `RETURN_EXISTING_RESULT`. A sanitized trace must bind the retrieval 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. +- Malformed/injected indexer/MCP content and invalid model output also preserve + `UNKNOWN`. Neither The Graph indexers, Subgraph MCP, nor the LLM have signing, + settlement, retry, Attempt-creation, or submission-ownership capability. - Include a public repository, clear README, and a two-to-four-minute demo. ## Claim standard diff --git a/.agent/context/20260906T230709Z-plan-clarification.md b/.agent/context/20260906T230709Z-plan-clarification.md index ccbf09f..283d73e 100644 --- a/.agent/context/20260906T230709Z-plan-clarification.md +++ b/.agent/context/20260906T230709Z-plan-clarification.md @@ -86,7 +86,8 @@ deterministic safety core. Repository: https://github.com/SWOFART/OneShot/. 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. + planning and contract specification change (which adds RecoveryAdvisorPort, + specifies recovery fixtures, and updates CONTRACTS.md without altering runtime code). - Gate B: NOT RUN. Waived by the same explicit user decision. Equivalent local evidence was captured instead: the full `agent-policy` workflow diff --git a/.agent/research/20260907-subgraph-mcp-clarification.md b/.agent/research/20260907-subgraph-mcp-clarification.md index 427c957..ef2fc16 100644 --- a/.agent/research/20260907-subgraph-mcp-clarification.md +++ b/.agent/research/20260907-subgraph-mcp-clarification.md @@ -46,7 +46,8 @@ Attempt, acquire submission ownership, or call `SettlementPort`. 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; +1. the intended live OneShot/Arc deployment was queried (via direct GraphQL as + minimal baseline path or Subgraph MCP as optional adapter); 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; diff --git a/.agents/skills/sponsor-qualification/SKILL.md b/.agents/skills/sponsor-qualification/SKILL.md index f7c7b55..36b2628 100644 --- a/.agents/skills/sponsor-qualification/SKILL.md +++ b/.agents/skills/sponsor-qualification/SKILL.md @@ -14,16 +14,18 @@ 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 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, +- The Graph: prove a pinned live OneShot/Arc Subgraph is queried (via direct + GraphQL as minimal path or optional Subgraph MCP adapter) and that the LLM + Recovery Agent materially uses the live data for hashless candidate + selection/explanation beyond direct known-hash lookup. +- Bind a sanitized retrieval 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. + `RETURN_EXISTING_RESULT`, and the deterministic-core disposition. Mocks, + static fixtures, unused dependencies, variables, and prompt text alone + without live Graph data and demonstrable AI impact 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. + multiple, or contradictory index/MCP results and invalid model output cannot unlock + another settlement. Indexer/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 diff --git a/docs/DOMAIN_ARCHITECTURE.md b/docs/DOMAIN_ARCHITECTURE.md index 9419481..dbed5d5 100644 --- a/docs/DOMAIN_ARCHITECTURE.md +++ b/docs/DOMAIN_ARCHITECTURE.md @@ -198,7 +198,7 @@ sequenceDiagram Reconciler->>Arc: Verify receipt, Memo when used, and Transfer end end - Note over Agent,Reconciler: Graph/MCP/LLM discover candidates; Arc proves; deterministic core decides + 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 diff --git a/milestones/CONTRACTS.md b/milestones/CONTRACTS.md index 2237910..20a47f8 100644 --- a/milestones/CONTRACTS.md +++ b/milestones/CONTRACTS.md @@ -100,11 +100,13 @@ Results: ### IndexViewPort.lookup -The v1 implementation obtains candidate transfers from a deployment-pinned -Subgraph MCP tool call and returns observations plus observed block/time, -provider/deployment/tool identity, chain-head comparison, lag, provider health +The v1 implementation defines `IndexViewPort` as provider-neutral: direct GraphQL +querying of the live OneShot/Arc Subgraph is the minimal baseline path, and a +deployment-pinned Subgraph MCP tool call is supported as an optional adapter. +Both return candidate transfer observations plus observed block/time, +provider/deployment identity, chain-head comparison, lag, provider health details, retrieval time, and health classification: `FRESH`, `LAGGING`, -`UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. The adapter validates tool +`UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. The adapter validates query/tool arguments, target deployment, result schema, `_meta`, size bounds, and untrusted text. Credentials never enter prompts, tool results, fixtures, logs, or evidence. diff --git a/milestones/coder-c/C01-recovery-evidence-strategy.md b/milestones/coder-c/C01-recovery-evidence-strategy.md index 5ceaa16..34fc4f7 100644 --- a/milestones/coder-c/C01-recovery-evidence-strategy.md +++ b/milestones/coder-c/C01-recovery-evidence-strategy.md @@ -49,14 +49,14 @@ removes the Graph claim and selects the direct-recovery fallback. - Add provider-specific mapping tests only after the decision record selects an implementation. -### C01.5 — Live MCP and AI-value spike +### C01.5 — Live Graph and AI-value spike -- Query the intended live deployment through Subgraph MCP, not a direct - application GraphQL client, and capture a sanitized tool trace. +- Query the intended live deployment through direct GraphQL (minimal path) or + Subgraph MCP (optional adapter), and capture a sanitized retrieval trace. - Feed the live candidate/freshness result to an LLM Recovery Agent and prove it materially affects candidate selection or explanation. -- Record `SELECT_SUBGRAPH_MCP` or `FALLBACK_DIRECT_RECOVERY`; the fallback keeps - safety but makes The Graph qualification `NOT VERIFIED`. +- Record `SELECT_SUBGRAPH_MCP` or `FALLBACK_DIRECT_RECOVERY`; direct GraphQL + remains the minimal baseline path. ## Acceptance evidence diff --git a/plan.md b/plan.md index 8b05174..101fe1b 100644 --- a/plan.md +++ b/plan.md @@ -53,10 +53,11 @@ The primary product configuration is **Privy + Arc + The Graph**: - Privy authorizes and constrains the corporate wallet action. - The Graph discovers candidate transfers when a successful submission lost its - transaction hash or provider response. The production path reaches the live - OneShot/Arc Subgraph through Subgraph MCP, not a direct application GraphQL client. -- The LLM Recovery Agent uses MCP results for meaningful candidate selection and - explanation, then emits one of four advisory recovery actions. + transaction hash or provider response. `IndexViewPort` remains provider-neutral: + direct GraphQL against the live OneShot/Arc Subgraph is the minimal path, with + a Subgraph MCP adapter available as an optional agent integration. +- The LLM Recovery Agent uses live Graph candidate results for meaningful candidate + selection and explanation, then emits one of four advisory recovery actions. - Arc verifies the candidate receipt and exact USDC `Transfer`. - OneShot and PostgreSQL alone decide the durable state transition. @@ -68,8 +69,8 @@ sponsor claim is made. The Graph submission targets the AI Tooling or AI Use Case track. One custom Subgraph does not satisfy the Composable/Standardized track. One live Subgraph is sufficient for the selected AI track. The recovery agent uses live Graph data -obtained through Subgraph MCP to choose and explain candidates; deterministic -Arc checks and the OneShot state machine retain all financial authority. +(obtained directly or via optional Subgraph MCP) to choose and explain candidates; +deterministic Arc checks and the OneShot state machine retain all financial authority. ### Sponsor claim mapping @@ -188,7 +189,7 @@ This plan optimizes for five properties: 3. Low merge contention: each coder owns disjoint directories and shared files have a single editor. 4. Verifiable handoffs: ports, OpenAPI, schemas, fixtures, and simulators are versioned artifacts. 5. Late frontend: UI work consumes a stable backend contract instead of driving it. -6. Network promotion: testnet proves behavior; mainnet readiness proves the same boundaries can be configured safely on Arc public mainnet, which opens 16 September 2026 on chain `5042`. +6. Network promotion: Arc Testnet proves behavior; Mainnet remains disabled until official network parameters are published, pinned, verified, and human-approved. ## 3. Product success criteria @@ -202,8 +203,8 @@ This plan optimizes for five properties: - The public repository contains the architecture diagram, setup and operator documentation, and no secrets in history. - The submission text names each claimed partner track explicitly and states the Arc mainnet-readiness position. - The demo proves working Privy and Arc integrations with sanitized testnet evidence and no exposed secrets. -- A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while the Arc Mainnet profile stays disabled pending explicit human authorization. Arc public mainnet opens 16 September 2026, after the submission deadline. -- The Graph sponsor claim is retained only when a sanitized live Subgraph MCP trace proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. +- A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while Arc Mainnet is unavailable or its official parameters have not been pinned and explicitly human-approved. +- The Graph sponsor claim is retained only when a sanitized live Graph trace (via direct GraphQL or optional Subgraph MCP adapter) proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. ## 4. Scope @@ -266,8 +267,8 @@ activate real-value execution. | Work delivery | Graphile Worker over the same PostgreSQL database; at-least-once delivery is assumed | | EVM encoding and RPC | `viem` for typed addresses, calldata, chain access, receipt reads, and log verification | | Authorization | Privy Node SDK, execution wallet, scoped wallet policy, persisted idempotency key, and reference identity | -| Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are enabled for live proof; the Arc Mainnet profile (chain `5042`, public launch 16 September 2026) is structurally complete but disabled until its values are pinned, verified, and human-approved | -| Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; a deployment-pinned Subgraph MCP adapter is the selected v1 path to the live OneShot/Arc Subgraph. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | +| Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are the only enabled live profile; the Arc Mainnet profile contains no guessed network values and remains disabled until official parameters are published, pinned, verified, and human-approved | +| Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; direct GraphQL is the minimal implementation path to the live OneShot/Arc Subgraph, with a deployment-pinned Subgraph MCP adapter as an optional integration path. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | | Money | Canonical integer strings at JSON boundaries and `bigint` internally; no JavaScript monetary floats | | Frontend | React and Vite, generated OpenAPI client, exact integer amount formatting, and no direct settlement capability | | Testing | Vitest for unit/contract tests, Testcontainers for PostgreSQL integration, Playwright for browser flows, deterministic failure simulators, and Graph adapter/degradation tests | @@ -342,14 +343,14 @@ that check passes and is recorded in the B01 handoff. ### Mainnet-readiness statement -Arc public mainnet launches on 16 September 2026, chain ID `5042`, the day the -hackathon ends. The submission deadline is 13 September, so no team can be -deployed at submission time. The 30 September date is a post-launch window in -which reviewers verify the claim, not a deadline met inside the event. +Arc public mainnet is not available at planning time. Only Arc Testnet has +published network parameters and can be deployed and exercised by the team. +OneShot therefore claims a working Testnet integration and Mainnet readiness, +not a Mainnet deployment. -The Mainnet track accepts either state: deployed, or deployment-ready. This -build targets deployment-ready and treats actual deployment as an optional -upgrade the team may take after 16 September. +The Mainnet profile contains no guessed chain ID, RPC, explorer, token, or +contract values. It remains disabled until Arc publishes official parameters, +B01 pins and verifies them, and a human explicitly authorizes activation. Because verification happens after the event, readiness evidence must live in the public repository rather than only in the submission form. From 7a7571ad1324d478a3b952b9ecf10e1d8803af86 Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Mon, 7 Sep 2026 14:43:35 +0200 Subject: [PATCH 4/4] fix(plan): restore Subgraph MCP path Restore the MCP-only Graph recovery path selected before d6758dd while retaining the Mermaid and Arc Testnet corrections. --- .agent/SPONSOR_REQUIREMENTS.md | 28 ++++++++----------- .../20260906T230709Z-plan-clarification.md | 3 +- .../20260907-subgraph-mcp-clarification.md | 3 +- .agents/skills/sponsor-qualification/SKILL.md | 18 ++++++------ milestones/CONTRACTS.md | 10 +++---- .../coder-c/C01-recovery-evidence-strategy.md | 10 +++---- plan.md | 17 ++++++----- 7 files changed, 39 insertions(+), 50 deletions(-) diff --git a/.agent/SPONSOR_REQUIREMENTS.md b/.agent/SPONSOR_REQUIREMENTS.md index 285bb3d..85c0cb0 100644 --- a/.agent/SPONSOR_REQUIREMENTS.md +++ b/.agent/SPONSOR_REQUIREMENTS.md @@ -31,28 +31,24 @@ The Graph is load-bearing for automatic recovery when a successful submission lost its transaction hash. It discovers candidates; Arc verifies them; OneShot decides. C01 must prove this with live data before any qualification claim. -- Target the AI Tooling or AI Use Case track (which permits Subgraphs, Subgraph MCP, - or Substreams). The recovery agent must use live Graph data for meaningful - candidate selection, explanation, and automation. -- `IndexViewPort` remains provider-neutral: direct GraphQL against the live - OneShot/Arc Subgraph is the minimal implementation path; Subgraph MCP is an - optional adapter chosen by OneShot, not a sponsor-mandated constraint. Mocks, - static fixtures, dependencies, or configuration entries alone are insufficient - without live Graph data and demonstrable AI impact. -- The LLM Recovery Agent must use the live Graph candidate observations (via direct - GraphQL or the Subgraph MCP adapter) to select `WAIT`, `RECONCILE`, `ESCALATE`, - or `RETURN_EXISTING_RESULT`. A sanitized trace must bind the retrieval call, - deployment/query/result, `_meta` health, referenced evidence, model - recommendation, and deterministic-core disposition. +- 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 indexer/MCP content and invalid model output also preserve - `UNKNOWN`. Neither The Graph indexers, Subgraph MCP, nor the LLM have signing, - settlement, retry, Attempt-creation, or submission-ownership capability. +- 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 diff --git a/.agent/context/20260906T230709Z-plan-clarification.md b/.agent/context/20260906T230709Z-plan-clarification.md index 283d73e..ccbf09f 100644 --- a/.agent/context/20260906T230709Z-plan-clarification.md +++ b/.agent/context/20260906T230709Z-plan-clarification.md @@ -86,8 +86,7 @@ deterministic safety core. Repository: https://github.com/SWOFART/OneShot/. 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 - planning and contract specification change (which adds RecoveryAdvisorPort, - specifies recovery fixtures, and updates CONTRACTS.md without altering runtime code). + 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 diff --git a/.agent/research/20260907-subgraph-mcp-clarification.md b/.agent/research/20260907-subgraph-mcp-clarification.md index ef2fc16..427c957 100644 --- a/.agent/research/20260907-subgraph-mcp-clarification.md +++ b/.agent/research/20260907-subgraph-mcp-clarification.md @@ -46,8 +46,7 @@ Attempt, acquire submission ownership, or call `SettlementPort`. The Graph remains `NOT VERIFIED` until a sanitized demo trace proves all of: -1. the intended live OneShot/Arc deployment was queried (via direct GraphQL as - minimal baseline path or Subgraph MCP as optional adapter); +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; diff --git a/.agents/skills/sponsor-qualification/SKILL.md b/.agents/skills/sponsor-qualification/SKILL.md index 36b2628..f7c7b55 100644 --- a/.agents/skills/sponsor-qualification/SKILL.md +++ b/.agents/skills/sponsor-qualification/SKILL.md @@ -14,18 +14,16 @@ 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 a pinned live OneShot/Arc Subgraph is queried (via direct - GraphQL as minimal path or optional Subgraph MCP adapter) and that the LLM - Recovery Agent materially uses the live data for hashless candidate - selection/explanation beyond direct known-hash lookup. -- Bind a sanitized retrieval trace to deployment/query/result, `_meta` health, +- 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. Mocks, - static fixtures, unused dependencies, variables, and prompt text alone - without live Graph data and demonstrable AI impact are insufficient. + `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 index/MCP results and invalid model output cannot unlock - another settlement. Indexer/MCP/model code exposes no settlement or retry capability. + 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 diff --git a/milestones/CONTRACTS.md b/milestones/CONTRACTS.md index 20a47f8..2237910 100644 --- a/milestones/CONTRACTS.md +++ b/milestones/CONTRACTS.md @@ -100,13 +100,11 @@ Results: ### IndexViewPort.lookup -The v1 implementation defines `IndexViewPort` as provider-neutral: direct GraphQL -querying of the live OneShot/Arc Subgraph is the minimal baseline path, and a -deployment-pinned Subgraph MCP tool call is supported as an optional adapter. -Both return candidate transfer observations plus observed block/time, -provider/deployment identity, chain-head comparison, lag, provider health +The v1 implementation obtains candidate transfers from a deployment-pinned +Subgraph MCP tool call and returns observations plus observed block/time, +provider/deployment/tool identity, chain-head comparison, lag, provider health details, retrieval time, and health classification: `FRESH`, `LAGGING`, -`UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. The adapter validates query/tool +`UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. The adapter validates tool arguments, target deployment, result schema, `_meta`, size bounds, and untrusted text. Credentials never enter prompts, tool results, fixtures, logs, or evidence. diff --git a/milestones/coder-c/C01-recovery-evidence-strategy.md b/milestones/coder-c/C01-recovery-evidence-strategy.md index 34fc4f7..5ceaa16 100644 --- a/milestones/coder-c/C01-recovery-evidence-strategy.md +++ b/milestones/coder-c/C01-recovery-evidence-strategy.md @@ -49,14 +49,14 @@ removes the Graph claim and selects the direct-recovery fallback. - Add provider-specific mapping tests only after the decision record selects an implementation. -### C01.5 — Live Graph and AI-value spike +### C01.5 — Live MCP and AI-value spike -- Query the intended live deployment through direct GraphQL (minimal path) or - Subgraph MCP (optional adapter), and capture a sanitized retrieval trace. +- Query the intended live deployment through Subgraph MCP, not a direct + application GraphQL client, and capture a sanitized tool trace. - Feed the live candidate/freshness result to an LLM Recovery Agent and prove it materially affects candidate selection or explanation. -- Record `SELECT_SUBGRAPH_MCP` or `FALLBACK_DIRECT_RECOVERY`; direct GraphQL - remains the minimal baseline path. +- Record `SELECT_SUBGRAPH_MCP` or `FALLBACK_DIRECT_RECOVERY`; the fallback keeps + safety but makes The Graph qualification `NOT VERIFIED`. ## Acceptance evidence diff --git a/plan.md b/plan.md index 101fe1b..a86f812 100644 --- a/plan.md +++ b/plan.md @@ -53,11 +53,10 @@ The primary product configuration is **Privy + Arc + The Graph**: - Privy authorizes and constrains the corporate wallet action. - The Graph discovers candidate transfers when a successful submission lost its - transaction hash or provider response. `IndexViewPort` remains provider-neutral: - direct GraphQL against the live OneShot/Arc Subgraph is the minimal path, with - a Subgraph MCP adapter available as an optional agent integration. -- The LLM Recovery Agent uses live Graph candidate results for meaningful candidate - selection and explanation, then emits one of four advisory recovery actions. + transaction hash or provider response. The production path reaches the live + OneShot/Arc Subgraph through Subgraph MCP, not a direct application GraphQL client. +- The LLM Recovery Agent uses MCP results for meaningful candidate selection and + explanation, then emits one of four advisory recovery actions. - Arc verifies the candidate receipt and exact USDC `Transfer`. - OneShot and PostgreSQL alone decide the durable state transition. @@ -69,8 +68,8 @@ sponsor claim is made. The Graph submission targets the AI Tooling or AI Use Case track. One custom Subgraph does not satisfy the Composable/Standardized track. One live Subgraph is sufficient for the selected AI track. The recovery agent uses live Graph data -(obtained directly or via optional Subgraph MCP) to choose and explain candidates; -deterministic Arc checks and the OneShot state machine retain all financial authority. +obtained through Subgraph MCP to choose and explain candidates; deterministic +Arc checks and the OneShot state machine retain all financial authority. ### Sponsor claim mapping @@ -204,7 +203,7 @@ This plan optimizes for five properties: - The submission text names each claimed partner track explicitly and states the Arc mainnet-readiness position. - The demo proves working Privy and Arc integrations with sanitized testnet evidence and no exposed secrets. - A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while Arc Mainnet is unavailable or its official parameters have not been pinned and explicitly human-approved. -- The Graph sponsor claim is retained only when a sanitized live Graph trace (via direct GraphQL or optional Subgraph MCP adapter) proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. +- The Graph sponsor claim is retained only when a sanitized live Subgraph MCP trace proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup, followed by deterministic OneShot/Arc validation. ## 4. Scope @@ -268,7 +267,7 @@ activate real-value execution. | EVM encoding and RPC | `viem` for typed addresses, calldata, chain access, receipt reads, and log verification | | Authorization | Privy Node SDK, execution wallet, scoped wallet policy, persisted idempotency key, and reference identity | | Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are the only enabled live profile; the Arc Mainnet profile contains no guessed network values and remains disabled until official parameters are published, pinned, verified, and human-approved | -| Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; direct GraphQL is the minimal implementation path to the live OneShot/Arc Subgraph, with a deployment-pinned Subgraph MCP adapter as an optional integration path. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | +| Hashless discovery and AI recovery | `IndexViewPort` is provider-neutral; a deployment-pinned Subgraph MCP adapter is the selected v1 path to the live OneShot/Arc Subgraph. The LLM Recovery Agent emits only four advisory actions. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | | Money | Canonical integer strings at JSON boundaries and `bigint` internally; no JavaScript monetary floats | | Frontend | React and Vite, generated OpenAPI client, exact integer amount formatting, and no direct settlement capability | | Testing | Vitest for unit/contract tests, Testcontainers for PostgreSQL integration, Playwright for browser flows, deterministic failure simulators, and Graph adapter/degradation tests |