From 231ba5ed4cebc6b73864167f00ecd07a6df2ec79 Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Sun, 6 Sep 2026 22:14:40 +0200 Subject: [PATCH 1/3] docs(plan): clarify product roadmap --- .agent/PROJECT_CONTEXT.md | 13 ++ .../20260906T201351Z-product-roadmap.md | 65 ++++++ milestones/README.md | 12 +- .../coder-a/A01-foundation-contracts.md | 2 +- milestones/coder-a/A02-durable-intents.md | 2 +- milestones/coder-a/A03-atomic-worker.md | 2 +- .../A04-restart-operations-composition.md | 2 +- .../coder-a/A05-frontend-intent-status.md | 2 +- milestones/coder-a/A06-release-operations.md | 2 +- milestones/coder-a/README.md | 5 + .../coder-b/B01-sdk-network-compatibility.md | 2 +- .../coder-b/B02-request-policy-receipt.md | 2 +- .../coder-b/B03-live-settlement-harness.md | 2 +- .../coder-b/B04-ambiguity-integration.md | 2 +- .../B05-frontend-settlement-details.md | 2 +- milestones/coder-b/B06-sponsor-evidence.md | 2 +- milestones/coder-b/README.md | 5 + .../coder-c/C01-subgraph-index-health.md | 2 +- .../coder-c/C02-reconciliation-engine.md | 2 +- milestones/coder-c/C03-failure-injection.md | 2 +- .../C04-recovery-matrix-integration.md | 2 +- milestones/coder-c/C05-frontend-recovery.md | 2 +- milestones/coder-c/C06-qualification-demo.md | 2 +- milestones/coder-c/README.md | 6 + plan.md | 190 +++++++++++++----- 25 files changed, 262 insertions(+), 70 deletions(-) create mode 100644 .agent/context/20260906T201351Z-product-roadmap.md diff --git a/.agent/PROJECT_CONTEXT.md b/.agent/PROJECT_CONTEXT.md index 1189146..3267b67 100644 --- a/.agent/PROJECT_CONTEXT.md +++ b/.agent/PROJECT_CONTEXT.md @@ -14,6 +14,19 @@ The core cardinality is: This document defines ownership and vocabulary. It is not a product implementation plan. +## Primary production vertical + +The first user is a company that lets an autonomous agent purchase a paid API +operation or digital result in USDC. The company approves one business +obligation; retries, restarts, queue redelivery, parallel workers, and multiple +agent instances must all converge on the same Business Intent and at most one +committed settlement. + +The initial product exposes an agent API, execution worker, reconciliation +service, operator console, and audit/recovery timeline. Invoice payment, +procurement, subscriptions, and other agent-commerce workflows are later +verticals over the same durable intent contract. + ## System ownership - OneShot is authoritative for business-intent execution state, attempt state, diff --git a/.agent/context/20260906T201351Z-product-roadmap.md b/.agent/context/20260906T201351Z-product-roadmap.md new file mode 100644 index 0000000..e358e92 --- /dev/null +++ b/.agent/context/20260906T201351Z-product-roadmap.md @@ -0,0 +1,65 @@ +# Session Context: Product-First Production Roadmap + +## Date/time + +- UTC: 20260906T201351Z + +## User goal + +Rewrite the OneShot plan as a clearer production roadmap: begin with the global +product vision and final B2B paid-API-job concept, remove per-packet day counts, +retain approximate scheduling, name the technology stack, and improve the three +A/B/C work lanes. + +## Assumptions + +- The current delivery commitment is a production-quality testnet MVP. +- The approximate calendar range may be expressed in weeks while fixed daily + promises are removed. +- Packet estimates use S/M/L effort bands. +- Mainnet or real-funds production remains a separately approved post-MVP stage. + +## Key decisions + +- The primary vertical is an autonomous B2B agent purchasing a paid API job or + digital result in USDC. +- The root plan now starts with product vision, product flow, user surfaces, and + the roadmap estimation model. +- The expected production-MVP range is six to eight weeks with three active + coders, recalibrated after foundation and live compatibility evidence. +- The stack is explicit: Node.js, TypeScript, pnpm, Fastify, PostgreSQL, pg, + Graphile Worker, viem, Privy, Arc, The Graph, React/Vite, Vitest, + Testcontainers, Playwright, Matchstick, Docker Compose, and GitHub Actions. +- A/B/C lane READMEs now state their technology focus; all 18 packets use S/M/L + estimates instead of working-day forecasts. +- A post-MVP path covers pilot readiness, limited production rollout, and later + product expansion without expanding the P0-P6 implementation commitment. + +## Files/components touched + +- plan.md +- .agent/PROJECT_CONTEXT.md +- milestones/README.md +- milestones/coder-a/README.md, coder-b/README.md, coder-c/README.md +- All 18 A/B/C packet files for effort-label conversion +- This context record + +## Validation + +- All local Markdown links in plan.md and milestones/ resolve. +- Exactly 18 packet files exist and all 18 contain S/M/L effort headers. +- No day-based estimate or legacy Forecast: header remains in the roadmap. +- git diff --check passes. +- Gate A and Gate B were intentionally not run because the user explicitly + requested skipping the two-review procedure for the planning phase. + +## References + +- C:\dev\thoughts\hackathon_eth_online_2026\brainstorming\11_OneShot — Privy Arc Graph Direction.md +- C:\dev\deeptrace\PLAN.md + +## Git state and next step + +- Branch: codex/clarify-product-roadmap +- Base: develop at 5ef6a66313614e67b476f56c98f47c65344fb6ec +- Commit and push follow after final scoped-diff inspection. diff --git a/milestones/README.md b/milestones/README.md index 3a30f40..07cc02c 100644 --- a/milestones/README.md +++ b/milestones/README.md @@ -35,11 +35,21 @@ Use these states in the PR or project tracker: - Never depend on another coder’s active branch. - Never import another coder’s private implementation path. - Consume only frozen schemas, fixtures, simulators, or reviewed package exports. -- Preserve backward compatibility within a delivery wave. +- Preserve backward compatibility within a delivery phase. - Convert breaking proposals into additive versioned contracts. - A project integration failure creates a focused ticket for the owning lane; it does not reopen unrelated completed packets. - Status meetings and review availability do not gate coding. Record assumptions and continue fail-closed. +## Effort and scheduling + +- `S`: less than one focused week. +- `M`: roughly one focused week. +- `L`: roughly one to two focused weeks. + +These are comparison bands, not delivery promises. The root roadmap defines +phase order and the approximate six-to-eight-week product range. Packet closure +still depends on evidence, contracts, and review rather than elapsed time. + ## Small-task sizing Every numbered task inside a packet should fit one coherent commit, normally two to six focused hours. If a task cannot be reviewed independently, split it by observable behavior, not by internal layer. diff --git a/milestones/coder-a/A01-foundation-contracts.md b/milestones/coder-a/A01-foundation-contracts.md index 54e1a04..4e2cb94 100644 --- a/milestones/coder-a/A01-foundation-contracts.md +++ b/milestones/coder-a/A01-foundation-contracts.md @@ -1,7 +1,7 @@ # A01 — Foundation and Contract Runtime Owner: Coder A -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/a01-foundation-contracts` Depends on: frozen `milestones/CONTRACTS.md` only Next: A02 immediately after closure diff --git a/milestones/coder-a/A02-durable-intents.md b/milestones/coder-a/A02-durable-intents.md index 9d7b06a..d9efdfa 100644 --- a/milestones/coder-a/A02-durable-intents.md +++ b/milestones/coder-a/A02-durable-intents.md @@ -1,7 +1,7 @@ # A02 — Durable Intent Ledger and API Owner: Coder A -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/a02-durable-intents` Depends on: A01 only Next: A03 immediately after closure diff --git a/milestones/coder-a/A03-atomic-worker.md b/milestones/coder-a/A03-atomic-worker.md index 0e279dc..0a79912 100644 --- a/milestones/coder-a/A03-atomic-worker.md +++ b/milestones/coder-a/A03-atomic-worker.md @@ -1,7 +1,7 @@ # A03 — Atomic At-Most-Once Worker Owner: Coder A -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/a03-atomic-worker` Depends on: A02 only Next: A04 immediately after closure diff --git a/milestones/coder-a/A04-restart-operations-composition.md b/milestones/coder-a/A04-restart-operations-composition.md index edc06e0..9aaf5f1 100644 --- a/milestones/coder-a/A04-restart-operations-composition.md +++ b/milestones/coder-a/A04-restart-operations-composition.md @@ -1,7 +1,7 @@ # A04 — Restart Safety, Operations, and Simulator Composition Owner: Coder A -Forecast: 4 working days +Effort: L — roughly one to two focused weeks Branch: `milestone/a04-restart-operations-composition` Depends on: A03 only Next: hold A05 until project Gate P4; improve backend evidence while waiting diff --git a/milestones/coder-a/A05-frontend-intent-status.md b/milestones/coder-a/A05-frontend-intent-status.md index 48e9bbc..d835b5b 100644 --- a/milestones/coder-a/A05-frontend-intent-status.md +++ b/milestones/coder-a/A05-frontend-intent-status.md @@ -1,7 +1,7 @@ # A05 — Frontend Intent and Authoritative Status Owner: Coder A -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/a05-frontend-intent-status` Depends on: A04 and project Gate P4 Next: A06 immediately after closure diff --git a/milestones/coder-a/A06-release-operations.md b/milestones/coder-a/A06-release-operations.md index 718a45f..5f8bb25 100644 --- a/milestones/coder-a/A06-release-operations.md +++ b/milestones/coder-a/A06-release-operations.md @@ -1,7 +1,7 @@ # A06 — Operational Demo and Release Bundle Owner: Coder A -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/a06-release-operations` Depends on: A05 only Project convergence: Gate P6 diff --git a/milestones/coder-a/README.md b/milestones/coder-a/README.md index 1398dd7..f1084a6 100644 --- a/milestones/coder-a/README.md +++ b/milestones/coder-a/README.md @@ -4,6 +4,11 @@ Mission: build the authoritative intent ledger, API, worker, concurrency guarant Exclusive paths are listed in `plan.md`. Do not implement provider-specific logic; consume `AuthorizationPort`, `SettlementPort`, `EvidencePort`, and `IndexViewPort` through contracts and simulators. +## Technology focus + +Node.js, strict TypeScript, pnpm, Fastify, OpenAPI/JSON Schema, PostgreSQL, +`pg`, Graphile Worker, React/Vite, Vitest, Testcontainers, and Playwright. + ## Sequence 1. [A01 — Foundation and contracts](A01-foundation-contracts.md) diff --git a/milestones/coder-b/B01-sdk-network-compatibility.md b/milestones/coder-b/B01-sdk-network-compatibility.md index 568fe5b..22afc81 100644 --- a/milestones/coder-b/B01-sdk-network-compatibility.md +++ b/milestones/coder-b/B01-sdk-network-compatibility.md @@ -1,7 +1,7 @@ # B01 — SDK and Arc Network Compatibility Owner: Coder B -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/b01-sdk-network-compatibility` Depends on: frozen `milestones/CONTRACTS.md` only Next: B02 immediately after closure diff --git a/milestones/coder-b/B02-request-policy-receipt.md b/milestones/coder-b/B02-request-policy-receipt.md index 57b1e05..6db6c0c 100644 --- a/milestones/coder-b/B02-request-policy-receipt.md +++ b/milestones/coder-b/B02-request-policy-receipt.md @@ -1,7 +1,7 @@ # B02 — Canonical Request, Policy, and Receipt Verification Owner: Coder B -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/b02-request-policy-receipt` Depends on: B01 only Next: B03 immediately after closure diff --git a/milestones/coder-b/B03-live-settlement-harness.md b/milestones/coder-b/B03-live-settlement-harness.md index 9dc43b2..f6aa001 100644 --- a/milestones/coder-b/B03-live-settlement-harness.md +++ b/milestones/coder-b/B03-live-settlement-harness.md @@ -1,7 +1,7 @@ # B03 — Offline-Complete and Live-Ready Settlement Harness Owner: Coder B -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/b03-live-settlement-harness` Depends on: B02 only Next: B04 immediately after offline closure diff --git a/milestones/coder-b/B04-ambiguity-integration.md b/milestones/coder-b/B04-ambiguity-integration.md index 239557b..a8cf79c 100644 --- a/milestones/coder-b/B04-ambiguity-integration.md +++ b/milestones/coder-b/B04-ambiguity-integration.md @@ -1,7 +1,7 @@ # B04 — Provider Ambiguity and Production Adapter Pack Owner: Coder B -Forecast: 4 working days +Effort: L — roughly one to two focused weeks Branch: `milestone/b04-ambiguity-integration` Depends on: B03 only Next: hold B05 until project Gate P4 diff --git a/milestones/coder-b/B05-frontend-settlement-details.md b/milestones/coder-b/B05-frontend-settlement-details.md index e71e7d9..2437694 100644 --- a/milestones/coder-b/B05-frontend-settlement-details.md +++ b/milestones/coder-b/B05-frontend-settlement-details.md @@ -1,7 +1,7 @@ # B05 — Frontend Authorization and Settlement Details Owner: Coder B -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/b05-frontend-settlement-details` Depends on: B04 and project Gate P4 Next: B06 immediately after closure diff --git a/milestones/coder-b/B06-sponsor-evidence.md b/milestones/coder-b/B06-sponsor-evidence.md index 46b8acb..b13d1f2 100644 --- a/milestones/coder-b/B06-sponsor-evidence.md +++ b/milestones/coder-b/B06-sponsor-evidence.md @@ -1,7 +1,7 @@ # B06 — Privy and Arc Sponsor Evidence Owner: Coder B -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/b06-sponsor-evidence` Depends on: B05 only Project convergence: Gate P6 diff --git a/milestones/coder-b/README.md b/milestones/coder-b/README.md index 4b4d43d..16ee318 100644 --- a/milestones/coder-b/README.md +++ b/milestones/coder-b/README.md @@ -4,6 +4,11 @@ Mission: provide a conservative, policy-constrained Privy/Arc adapter with exact Stay inside B-owned packages and fixtures. Consume domain requests from the frozen contract pack; never redefine durable states or edit migrations. +## Technology focus + +Privy Node SDK, Privy execution-wallet policies, `viem`, Arc Testnet RPC and +ERC-20 USDC, React/Vite, Vitest, and sanitized provider fixtures. + ## Sequence 1. [B01 — SDK and network compatibility](B01-sdk-network-compatibility.md) diff --git a/milestones/coder-c/C01-subgraph-index-health.md b/milestones/coder-c/C01-subgraph-index-health.md index 4b6c7e5..182bfb2 100644 --- a/milestones/coder-c/C01-subgraph-index-health.md +++ b/milestones/coder-c/C01-subgraph-index-health.md @@ -1,7 +1,7 @@ # C01 — Subgraph Mapping and Index Health Owner: Coder C -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/c01-subgraph-index-health` Depends on: frozen `milestones/CONTRACTS.md` only Next: C02 immediately after closure diff --git a/milestones/coder-c/C02-reconciliation-engine.md b/milestones/coder-c/C02-reconciliation-engine.md index 51e4092..104b8bd 100644 --- a/milestones/coder-c/C02-reconciliation-engine.md +++ b/milestones/coder-c/C02-reconciliation-engine.md @@ -1,7 +1,7 @@ # C02 — Deterministic Reconciliation Engine Owner: Coder C -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/c02-reconciliation-engine` Depends on: C01 only Next: C03 immediately after closure diff --git a/milestones/coder-c/C03-failure-injection.md b/milestones/coder-c/C03-failure-injection.md index 3fdcf40..43fcc05 100644 --- a/milestones/coder-c/C03-failure-injection.md +++ b/milestones/coder-c/C03-failure-injection.md @@ -1,7 +1,7 @@ # C03 — Cross-Source Failure Injection Owner: Coder C -Forecast: 3 working days +Effort: M — roughly one focused week Branch: `milestone/c03-failure-injection` Depends on: C02 only Next: C04 immediately after closure diff --git a/milestones/coder-c/C04-recovery-matrix-integration.md b/milestones/coder-c/C04-recovery-matrix-integration.md index dca8fcb..11e8456 100644 --- a/milestones/coder-c/C04-recovery-matrix-integration.md +++ b/milestones/coder-c/C04-recovery-matrix-integration.md @@ -1,7 +1,7 @@ # C04 — Recovery Matrix and Simulator Integration Owner: Coder C -Forecast: 4 working days +Effort: L — roughly one to two focused weeks Branch: `milestone/c04-recovery-matrix-integration` Depends on: C03 only Next: hold C05 until project Gate P4 diff --git a/milestones/coder-c/C05-frontend-recovery.md b/milestones/coder-c/C05-frontend-recovery.md index 205e3f3..cd78336 100644 --- a/milestones/coder-c/C05-frontend-recovery.md +++ b/milestones/coder-c/C05-frontend-recovery.md @@ -1,7 +1,7 @@ # C05 — Frontend Recovery Timeline and Indexed History Owner: Coder C -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/c05-frontend-recovery` Depends on: C04 and project Gate P4 Next: C06 immediately after closure diff --git a/milestones/coder-c/C06-qualification-demo.md b/milestones/coder-c/C06-qualification-demo.md index 92446ab..3bb49e0 100644 --- a/milestones/coder-c/C06-qualification-demo.md +++ b/milestones/coder-c/C06-qualification-demo.md @@ -1,7 +1,7 @@ # C06 — The Graph, Recovery, and Qualification Bundle Owner: Coder C -Forecast: 2 working days +Effort: S — less than one focused week Branch: `milestone/c06-qualification-demo` Depends on: C05 only Project convergence: Gate P6 diff --git a/milestones/coder-c/README.md b/milestones/coder-c/README.md index 065bfe5..28b89d2 100644 --- a/milestones/coder-c/README.md +++ b/milestones/coder-c/README.md @@ -4,6 +4,12 @@ Mission: index Arc transfer observations, classify Graph health/freshness, recon Stay inside C-owned paths. The reconciliation package emits frozen commands; it never writes A’s tables directly and never calls SettlementPort. +## Technology focus + +The Graph Subgraph stack, `graph-cli`, AssemblyScript mappings, GraphQL, +Matchstick, `viem` read paths, Vitest, deterministic failure injection, and +React/Vite recovery components. + ## Sequence 1. [C01 — Subgraph and index health](C01-subgraph-index-health.md) diff --git a/plan.md b/plan.md index e82186c..dd7b060 100644 --- a/plan.md +++ b/plan.md @@ -1,13 +1,71 @@ # OneShot Product Delivery Plan -Status: implementation-ready planning baseline +Status: production MVP roadmap Team: exactly three coders -Planning horizon: 20 working days, recalibrated after Backend Wave 1 +Indicative delivery range: six to eight weeks with three active coders Implementation base: the human-approved commit containing this plan Research basis: `.agent/research/20260906-integration-decisions.md` Detailed work packets: [`milestones/README.md`](milestones/README.md) -## 1. Mission +## Global product vision + +OneShot is a payment control plane for autonomous business agents. It lets a +company approve one business obligation, allow an agent to execute it, and +retain one durable financial outcome even when requests, processes, workers, +or agent instances repeat. + +The primary product promise is: + +`One job. Many retries. One settlement.` + +The first production vertical is a B2B agent purchasing a paid API operation +or digital result in USDC. Invoice payment, procurement, subscriptions, and +other agent-commerce obligations are later verticals built on the same +Business Intent contract. + +## Primary product flow + +1. A company configures a Privy-controlled wallet, recipient policy, and + spending limit. +2. An agent creates one Business Intent for a paid API job with a stable + identity, recipient, amount, asset, network, and purpose. +3. OneShot validates and durably records the obligation before any external + effect. +4. A worker obtains atomic submission ownership and asks Privy to authorize the + exact Arc USDC transfer. +5. Arc settles the payment. OneShot verifies the receipt and expected ERC-20 + Transfer before recording `COMMITTED`. +6. A timeout, crash, or lost response becomes durable `UNKNOWN`. Reconciliation + looks up the original Privy and Arc activity; The Graph adds indexed history, + freshness, and recovery context. +7. Repeated HTTP requests, queue deliveries, processes, or agents return the + same Business Intent and cannot create a second committed settlement. + +## Product surfaces + +| Surface | User | Purpose | +| --- | --- | --- | +| Agent API and generated client | Autonomous agent or backend | Create/reuse a Business Intent and read its authoritative state | +| Operator console | Company operator | Inspect attempts, policy decisions, settlement evidence, and recovery state | +| Execution worker | OneShot service | Acquire submission ownership and execute the approved settlement | +| Reconciliation service | Agent and operator | Resolve ambiguous outcomes without blindly paying again | +| Audit and recovery timeline | Company and supplier | Explain what happened, which evidence is authoritative, and what action is safe | + +## Production roadmap model + +- The roadmap targets a production-quality testnet MVP, not a disposable demo. +- The overall six-to-eight-week range is approximate and is recalibrated after + the independent foundation phase and the first live Privy/Arc compatibility + proof. +- Work packets use `S`, `M`, and `L` effort bands instead of fixed + per-packet date promises: `S` is less than one focused week, `M` is roughly one focused week, + and `L` is roughly one to two focused weeks. +- A, B, and C progress independently inside frozen contracts. Product phases + advance when evidence gates pass, not when a date arrives. +- Frontend production work begins after backend convergence freezes the public + API and recovery semantics. + +## 1. Mission and v1 release Deliver a testnet application that accepts one approved Business Intent, safely survives retries, crashes, duplicate delivery, parallel workers, and ambiguous provider responses, and produces at most one committed ERC-20 USDC settlement on Arc Testnet through a Privy-controlled corporate wallet. The Graph supplies live indexed recovery and history evidence without becoming settlement authority. @@ -15,7 +73,7 @@ The release claim is: `1 Business Intent / N Attempts / <= 1 committed Settlement` -The delivery plan is backend-first. Frontend implementation is deliberately placed in Wave 5 and may start only after the backend contract-freeze gate has passed. +The delivery plan is backend-first. Frontend implementation is deliberately placed in Phase R5 and may start only after the backend contract-freeze gate has passed. ## 2. Planning objectives @@ -57,31 +115,54 @@ This plan optimizes for five properties: - 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. +### Post-MVP production path + +The current implementation commitment ends with a production-quality testnet +MVP. A real-funds release requires separate evidence and human approval: + +1. **Pilot readiness:** tenant authentication and authorization, retention and + deletion policy, backup/restore proof, load limits, incident response, + dependency and contract security review, and production Privy/Arc support. +2. **Limited production pilot:** allowlisted organizations, conservative + spending caps, safe-disable drills, operator escalation, SLO measurement, + and staged rollout with no automatic mainnet migration. +3. **Product expansion:** invoice and procurement connectors, subscriptions, + supplier APIs, additional settlement networks/assets, and higher-availability + deployment only after the core invariant remains proven in the pilot. + +These stages extend the roadmap without expanding the P0-P6 build commitment. + ## 5. Fixed technical baseline -| Area | Decision | +| Area | Technology and decision | | --- | --- | -| Runtime | Node.js LTS and strict TypeScript; A01 pins the workspace runtime, while B01 proves SDK compatibility independently and reports any mismatch at P2 | -| Workspace | `pnpm` workspace with package-local lint, type, test, and build commands | -| API | HTTP JSON, OpenAPI source of truth, generated-schema drift check | -| State | PostgreSQL with constraints, compare-and-set transitions, and transactional enqueueing | -| Queue | Graphile Worker; at-least-once delivery is assumed | -| Money | Integer strings at boundaries, `bigint` internally, no JavaScript monetary floats | +| Runtime | Current active Node.js LTS, pinned by A01, with strict TypeScript | +| Workspace | `pnpm` monorepo with package-local lint, type, test, and build commands | +| API and contracts | Fastify HTTP JSON API, JSON Schema, OpenAPI source of truth, and generated-client/schema drift checks | +| Authoritative state | PostgreSQL, explicit SQL migrations, `pg`, uniqueness constraints, compare-and-set transitions, and transactional outbox records | +| 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 | Arc Testnet `eip155:5042002`, ERC-20 USDC `0x3600000000000000000000000000000000000000`, six decimals | -| Authorization | Privy execution wallet with explicit fail-closed policy and persisted request identity | -| Submission jobs | One queue attempt; task persists `COMMITTED`, `FAILED_SAFE`, or `UNKNOWN` before returning | -| Recovery | OneShot and verified Arc evidence authoritative; The Graph is freshness-labeled observation only | -| Frontend | Begins after Gate P4; consumes frozen OpenAPI and mock server | - -The exact v1 contracts, state table, fixture catalog, redaction rules, and change protocol are frozen in [`milestones/CONTRACTS.md`](milestones/CONTRACTS.md). +| Indexing | The Graph custom Subgraph, `graph-cli`, AssemblyScript mappings, GraphQL client, `_meta` health data, and Matchstick mapping tests | +| 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, Matchstick for Subgraph mappings, and deterministic failure simulators | +| 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 | OneShot state and verified Arc evidence are authoritative; Privy helps locate activity; The Graph is freshness-labeled observation and history | + +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). ## 6. Architecture ```text -Caller / late frontend +Autonomous agent / operator console | v -HTTP API ----------> PostgreSQL authoritative ledger <--------- Worker +Fastify API -------> PostgreSQL authoritative ledger <--- Graphile Worker | | | | +-- transactional jobs/outbox -+ | @@ -184,42 +265,49 @@ Consumers validate against the pack, not against a producer’s active branch. - Questions default to a written assumption plus a fail-closed implementation. Only decisions that could weaken settlement cardinality, money representation, authorization, or `UNKNOWN` handling require synchronous escalation. - Daily status is informational and never an approval gate. -## 9. Delivery waves +## 9. Delivery phases and indicative schedule + +The three lanes run in parallel. The calendar ranges below describe likely +elapsed time with three active coders; they are planning estimates rather than +deadlines or permission to weaken acceptance evidence. -| Wave | Days | A | B | C | Project gate | -| --- | ---: | --- | --- | --- | --- | -| W0 | 0 | Read frozen pack; branch | Read frozen pack; branch | Read frozen pack; branch | P0 plan/contract approval | -| W1 | 1–4 | A01 | B01 | C01 | Independent toolchains runnable | -| W2 | 4–7 | A02 | B02 | C02 | Contract packs v1 emitted | -| W3 | 7–10 | A03 | B03 | C03 | Safety behavior proven independently | -| W4 | 10–14 | A04 | B04 | C04 | P4 backend convergence and live proof | -| W5 | 15–18 | A05 | B05 | C05 | P5 frontend acceptance | -| W6 | 18–20 | A06 | B06 | C06 | P6 release candidate | +| Phase | Approximate duration | Coder A | Coder B | Coder C | Exit evidence | +| --- | --- | --- | --- | --- | --- | +| R0 — product and contract freeze | Less than one week | Confirm domain/API contract | Confirm provider/chain contract | Confirm recovery/index contract | P0 approved scope and immutable v1 pack | +| R1 — independent foundations | About one week | A01 | B01 | C01 | P1 independent toolchains and compatibility findings | +| R2 — durable core and adapters | About one week | A02 | B02 | C02 | P2 compatible contract packs and simulators | +| R3 — safety under failure | About one week | A03 | B03 | C03 | P3 concurrency, ambiguity, and failure proofs | +| R4 — backend convergence | One to two weeks | A04 and composition owner | B04 and live settlement evidence | C04 and live index/recovery evidence | P4 integrated backend, one real settlement, lost-response recovery | +| R5 — product interface | About one week | A05 application shell | B05 policy/settlement slice | C05 recovery/history slice | P5 composed operator experience | +| R6 — hardening and release | About one week | A06 operations bundle | B06 Privy/Arc evidence | C06 Graph/recovery evidence | P6 repeatable release candidate | -Dates are forecasts, not permission to cut safety. Each coder may move to the next packet as soon as their current packet closes. +The expected production-MVP range is six to eight weeks because early phases +overlap across the three lanes. Provider access, SDK incompatibility, or failed +P4 evidence may extend the range. A completed packet immediately unlocks the +next same-owner packet; teams do not wait for ceremonial phase boundaries. ## 10. Work-packet inventory -| ID | Owner | Estimate | Own-track prerequisite | Independently verifiable output | +| ID | Owner | Effort | Own-track prerequisite | Independently verifiable output | | --- | --- | ---: | --- | --- | -| [A01](milestones/coder-a/A01-foundation-contracts.md) | A | 3 d | Frozen contract pack | Workspace, contracts package, OpenAPI, domain simulator | -| [A02](milestones/coder-a/A02-durable-intents.md) | A | 3 d | A01 | PostgreSQL intent/replay/conflict API | -| [A03](milestones/coder-a/A03-atomic-worker.md) | A | 3 d | A02 | Atomic worker and at-most-once fake-port proof | -| [A04](milestones/coder-a/A04-restart-operations-composition.md) | A | 4 d | A03 | Restart-safe orchestration and simulator composition | -| [A05](milestones/coder-a/A05-frontend-intent-status.md) | A | 2 d | A04 + project Gate P4 | Intent/status frontend slice against mock server | -| [A06](milestones/coder-a/A06-release-operations.md) | A | 2 d | A05 | Operational demo and release bundle | -| [B01](milestones/coder-b/B01-sdk-network-compatibility.md) | B | 3 d | Frozen contract pack | SDK/network compatibility and readiness package | -| [B02](milestones/coder-b/B02-request-policy-receipt.md) | B | 3 d | B01 | Canonical request, policy, and receipt verifier | -| [B03](milestones/coder-b/B03-live-settlement-harness.md) | B | 3 d | B02 | Offline-complete plus live-ready settlement harness | -| [B04](milestones/coder-b/B04-ambiguity-integration.md) | B | 4 d | B03 | Conservative outcomes and production adapter pack | -| [B05](milestones/coder-b/B05-frontend-settlement-details.md) | B | 2 d | B04 + project Gate P4 | Authorization/settlement UI slice against fixtures | -| [B06](milestones/coder-b/B06-sponsor-evidence.md) | B | 2 d | B05 | Privy/Arc sanitized evidence bundle | -| [C01](milestones/coder-c/C01-subgraph-index-health.md) | C | 3 d | Frozen contract pack | Subgraph mappings and Graph health client | -| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | 3 d | C01 | Deterministic reconciliation and evidence contract | -| [C03](milestones/coder-c/C03-failure-injection.md) | C | 3 d | C02 | Cross-source chaos and restart harness | -| [C04](milestones/coder-c/C04-recovery-matrix-integration.md) | C | 4 d | C03 | Recovery matrix and simulator integration pack | -| [C05](milestones/coder-c/C05-frontend-recovery.md) | C | 2 d | C04 + project Gate P4 | Recovery timeline UI slice against fixtures | -| [C06](milestones/coder-c/C06-qualification-demo.md) | C | 2 d | C05 | Graph/recovery qualification bundle | +| [A01](milestones/coder-a/A01-foundation-contracts.md) | A | M | Frozen contract pack | Workspace, contracts package, OpenAPI, domain simulator | +| [A02](milestones/coder-a/A02-durable-intents.md) | A | M | A01 | PostgreSQL intent/replay/conflict API | +| [A03](milestones/coder-a/A03-atomic-worker.md) | A | M | A02 | Atomic worker and at-most-once fake-port proof | +| [A04](milestones/coder-a/A04-restart-operations-composition.md) | A | L | A03 | Restart-safe orchestration and simulator composition | +| [A05](milestones/coder-a/A05-frontend-intent-status.md) | A | S | A04 + project Gate P4 | Intent/status frontend slice against mock server | +| [A06](milestones/coder-a/A06-release-operations.md) | A | S | A05 | Operational demo and release bundle | +| [B01](milestones/coder-b/B01-sdk-network-compatibility.md) | B | M | Frozen contract pack | SDK/network compatibility and readiness package | +| [B02](milestones/coder-b/B02-request-policy-receipt.md) | B | M | B01 | Canonical request, policy, and receipt verifier | +| [B03](milestones/coder-b/B03-live-settlement-harness.md) | B | M | B02 | Offline-complete plus live-ready settlement harness | +| [B04](milestones/coder-b/B04-ambiguity-integration.md) | B | L | B03 | Conservative outcomes and production adapter pack | +| [B05](milestones/coder-b/B05-frontend-settlement-details.md) | B | S | B04 + project Gate P4 | Authorization/settlement UI slice against fixtures | +| [B06](milestones/coder-b/B06-sponsor-evidence.md) | B | S | B05 | Privy/Arc sanitized evidence bundle | +| [C01](milestones/coder-c/C01-subgraph-index-health.md) | C | M | Frozen contract pack | Subgraph mappings and Graph health client | +| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | M | C01 | Deterministic reconciliation and evidence contract | +| [C03](milestones/coder-c/C03-failure-injection.md) | C | M | C02 | Cross-source chaos and restart harness | +| [C04](milestones/coder-c/C04-recovery-matrix-integration.md) | C | L | C03 | Recovery matrix and simulator integration pack | +| [C05](milestones/coder-c/C05-frontend-recovery.md) | C | S | C04 + project Gate P4 | Recovery timeline UI slice against fixtures | +| [C06](milestones/coder-c/C06-qualification-demo.md) | C | S | C05 | Graph/recovery qualification bundle | Each packet contains smaller, one-commit-sized tasks, exact acceptance criteria, tests, output artifacts, and a no-wait continuation instruction. @@ -484,7 +572,7 @@ P4 failures never produce ad hoc edits by multiple coders on the composition bra - Consumers pin a digest/version rather than a moving branch. - New optional fields have deterministic default handling that fails closed. - New enum variants are rejected until explicitly supported. -- Removal/deprecation never occurs in the same wave as introduction. +- Removal/deprecation never occurs in the same delivery phase as introduction. ## 24. Decision and escalation policy @@ -505,7 +593,7 @@ An escalation record contains the exact decision, safest default, affected contr ## 25. Schedule control and scope-cut order -The 20-day horizon is a forecast. Re-estimate at P1 and after any provider compatibility failure. Never change acceptance evidence silently to preserve dates. +The six-to-eight-week production-MVP range is a forecast. Re-estimate at P1 and after any provider compatibility failure. Never change acceptance evidence silently to preserve dates. If time is constrained, cut in this order: From f641d9747083c01810cfd0bc720159e0bdb8641c Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Sun, 6 Sep 2026 22:25:29 +0200 Subject: [PATCH 2/3] docs(plan): replace estimates with diagrams --- .../20260906T201351Z-product-roadmap.md | 68 +++-- docs/DOMAIN_ARCHITECTURE.md | 250 ++++++++++++++++++ milestones/README.md | 12 +- .../coder-a/A01-foundation-contracts.md | 1 - milestones/coder-a/A02-durable-intents.md | 1 - milestones/coder-a/A03-atomic-worker.md | 1 - .../A04-restart-operations-composition.md | 1 - .../coder-a/A05-frontend-intent-status.md | 1 - milestones/coder-a/A06-release-operations.md | 1 - .../coder-b/B01-sdk-network-compatibility.md | 1 - .../coder-b/B02-request-policy-receipt.md | 1 - .../coder-b/B03-live-settlement-harness.md | 1 - .../coder-b/B04-ambiguity-integration.md | 1 - .../B05-frontend-settlement-details.md | 1 - milestones/coder-b/B06-sponsor-evidence.md | 1 - .../coder-c/C01-subgraph-index-health.md | 1 - .../coder-c/C02-reconciliation-engine.md | 1 - milestones/coder-c/C03-failure-injection.md | 1 - .../C04-recovery-matrix-integration.md | 1 - milestones/coder-c/C05-frontend-recovery.md | 1 - milestones/coder-c/C06-qualification-demo.md | 1 - plan.md | 193 ++++++++------ 22 files changed, 401 insertions(+), 140 deletions(-) create mode 100644 docs/DOMAIN_ARCHITECTURE.md diff --git a/.agent/context/20260906T201351Z-product-roadmap.md b/.agent/context/20260906T201351Z-product-roadmap.md index e358e92..34440a9 100644 --- a/.agent/context/20260906T201351Z-product-roadmap.md +++ b/.agent/context/20260906T201351Z-product-roadmap.md @@ -6,60 +6,54 @@ ## User goal -Rewrite the OneShot plan as a clearer production roadmap: begin with the global -product vision and final B2B paid-API-job concept, remove per-packet day counts, -retain approximate scheduling, name the technology stack, and improve the three -A/B/C work lanes. - -## Assumptions - -- The current delivery commitment is a production-quality testnet MVP. -- The approximate calendar range may be expressed in weeks while fixed daily - promises are removed. -- Packet estimates use S/M/L effort bands. -- Mainnet or real-funds production remains a separately approved post-MVP stage. +Rewrite OneShot as a product-first roadmap based on the final B2B paid-API-job +concept. Name the technology stack, organize delivery only by dependencies and +evidence gates, and explain how every domain component and A/B/C lane +contributes to the complete product. ## Key decisions - The primary vertical is an autonomous B2B agent purchasing a paid API job or digital result in USDC. -- The root plan now starts with product vision, product flow, user surfaces, and - the roadmap estimation model. -- The expected production-MVP range is six to eight weeks with three active - coders, recalibrated after foundation and live compatibility evidence. -- The stack is explicit: Node.js, TypeScript, pnpm, Fastify, PostgreSQL, pg, - Graphile Worker, viem, Privy, Arc, The Graph, React/Vite, Vitest, +- The root plan starts with product vision, product flow, user surfaces, system + context, and the dependency-gated roadmap. +- The stack is explicit: Node.js, TypeScript, pnpm, Fastify, PostgreSQL, `pg`, + Graphile Worker, `viem`, Privy, Arc, The Graph, React/Vite, Vitest, Testcontainers, Playwright, Matchstick, Docker Compose, and GitHub Actions. -- A/B/C lane READMEs now state their technology focus; all 18 packets use S/M/L - estimates instead of working-day forecasts. -- A post-MVP path covers pilot readiness, limited production rollout, and later - product expansion without expanding the P0-P6 implementation commitment. +- A/B/C lane READMEs state their technology focus. Packet metadata contains + ownership and dependencies only. +- `docs/DOMAIN_ARCHITECTURE.md` explains system context, domain records, state + ownership, component responsibilities, success and recovery sequences, port + boundaries, and A/B/C convergence. +- Post-MVP pilot stages remain separate from the P0-P6 implementation contract. ## Files/components touched -- plan.md -- .agent/PROJECT_CONTEXT.md -- milestones/README.md -- milestones/coder-a/README.md, coder-b/README.md, coder-c/README.md -- All 18 A/B/C packet files for effort-label conversion +- `plan.md` +- `.agent/PROJECT_CONTEXT.md` +- `milestones/README.md` +- `milestones/coder-a/README.md`, `coder-b/README.md`, `coder-c/README.md` +- All 18 A/B/C packet files +- `docs/DOMAIN_ARCHITECTURE.md` - This context record ## Validation -- All local Markdown links in plan.md and milestones/ resolve. -- Exactly 18 packet files exist and all 18 contain S/M/L effort headers. -- No day-based estimate or legacy Forecast: header remains in the roadmap. -- git diff --check passes. +- All local Markdown links in `plan.md`, `milestones/`, and `docs/` resolve. +- Exactly 18 packet files remain. +- Packet headers contain no planning-size metadata. +- Mermaid fence pairs and required diagram types are checked structurally. +- `git diff --check` passes. - Gate A and Gate B were intentionally not run because the user explicitly requested skipping the two-review procedure for the planning phase. ## References -- C:\dev\thoughts\hackathon_eth_online_2026\brainstorming\11_OneShot — Privy Arc Graph Direction.md -- C:\dev\deeptrace\PLAN.md +- `C:\dev\thoughts\hackathon_eth_online_2026\brainstorming\11_OneShot — Privy Arc Graph Direction.md` +- `C:\dev\deeptrace\PLAN.md` -## Git state and next step +## Git state -- Branch: codex/clarify-product-roadmap -- Base: develop at 5ef6a66313614e67b476f56c98f47c65344fb6ec -- Commit and push follow after final scoped-diff inspection. +- Branch: `milestone/product-roadmap` +- Base: `develop` at `5ef6a66313614e67b476f56c98f47c65344fb6ec` +- Pull request: `https://github.com/SWOFART/OneShot/pull/7` diff --git a/docs/DOMAIN_ARCHITECTURE.md b/docs/DOMAIN_ARCHITECTURE.md new file mode 100644 index 0000000..2fb026d --- /dev/null +++ b/docs/DOMAIN_ARCHITECTURE.md @@ -0,0 +1,250 @@ +# OneShot Domain Architecture + +This document explains how each domain part contributes to the product promise: + +`1 Business Intent / N Attempts / <= 1 committed Settlement` + +## System context + +```mermaid +flowchart LR + Operator[Company operator] -->|configures policy| Privy[Privy] + Agent[Autonomous agent] -->|creates or reuses intent| API[OneShot API] + Agent -.->|requests business job| Supplier[Paid API or supplier] + API --> Domain[OneShot domain] + Domain --> Ledger[(Authoritative ledger)] + Ledger --> Worker[Execution worker] + Worker --> Privy + Privy --> Arc[Arc USDC settlement] + Arc --> SupplierWallet[Supplier wallet] + Arc --> Index[The Graph index] + Ledger --> Recovery[Recovery and audit view] + Index --> Recovery + Recovery --> Agent + Recovery --> Operator +``` + +The paid service and its result remain outside OneShot's trust boundary. +OneShot guarantees payment cardinality and evidence for an approved obligation; +it does not certify supplier quality or delivery. + +## Domain records and relationships + +```mermaid +classDiagram + class BusinessIntent { + +business_intent_id + +payload_fingerprint + +recipient + +amount_atomic + +asset + +network + +purpose + +state + +version + } + class Attempt { + +attempt_id + +stage + +sanitized_result + +created_at + } + class Settlement { + +settlement_id + +provider_reference + +transaction_hash + +receipt_status + +transfer_log_index + } + class OutboxJob { + +job_id + +job_type + +delivery_state + } + class EvidenceObservation { + +source + +authority_class + +retrieved_at + +block_number + +freshness + +digest + } + class ReconciliationDecision { + +command + +expected_version + +reason + } + + BusinessIntent "1" --> "0..*" Attempt : records execution tries + BusinessIntent "1" --> "0..1" Settlement : owns financial result + BusinessIntent "1" --> "0..*" OutboxJob : schedules work + BusinessIntent "1" --> "0..*" EvidenceObservation : collects evidence + BusinessIntent "1" --> "0..*" ReconciliationDecision : resolves uncertainty + Attempt "0..*" --> "0..1" Settlement : may produce +``` + +The Business Intent is the durable business identity. Attempts may repeat. +Settlement cardinality is enforced against the Business Intent, never against +an HTTP request, worker process, queue delivery, or agent session. + +## State ownership + +```mermaid +stateDiagram-v2 + [*] --> AUTHORIZING: valid new intent + AUTHORIZING --> REJECTED: Privy policy denies + AUTHORIZING --> READY: exact action authorized + READY --> SUBMITTING: atomic ownership acquired + SUBMITTING --> COMMITTED: final receipt and Transfer verified + SUBMITTING --> FAILED_SAFE: authoritative no-effect proof + SUBMITTING --> UNKNOWN: timeout, crash, or possible submission + UNKNOWN --> COMMITTED: original payment verified + UNKNOWN --> FAILED_SAFE: authoritative final no-effect proof + UNKNOWN --> UNKNOWN: pending, absent, stale, unhealthy, or contradictory evidence + REJECTED --> [*] + COMMITTED --> [*] +``` + +Only the domain and PostgreSQL transition rules own these states. Privy, Arc, +The Graph, queues, and UI components report facts or perform bounded actions; +none may reinterpret the state machine. + +## Component responsibilities + +| Part | Owns | Must never own | +| --- | --- | --- | +| Agent API | Validation, create/replay/conflict response, status reads | Direct settlement or retry permission | +| Contracts package | Shared schemas, ports, enums, money and identity rules | Provider implementation | +| Domain package | State transitions, submission ownership, result classification | Network calls or UI | +| PostgreSQL storage | Durable uniqueness, versions, attempts, settlement and evidence records | Business decisions outside domain commands | +| Transactional outbox | Atomic creation of work with domain state | Duplicate-payment prevention by itself | +| 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 Subgraph/client | Indexed transfer history, deployment identity, freshness and health | Proof that an absent payment never happened | +| Reconciliation engine | Combine bound evidence and emit versioned safe commands | Settlement submission | +| 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 | + +## Successful settlement sequence + +```mermaid +sequenceDiagram + participant Agent + participant API as OneShot API + participant DB as PostgreSQL + participant Worker + participant Privy + participant Arc + participant Graph as The Graph + + Agent->>API: POST Business Intent with stable ID + API->>DB: Insert intent and outbox job atomically + DB-->>API: New intent or identical replay + API-->>Agent: Authoritative intent state + Worker->>DB: Acquire AUTHORIZING/READY/SUBMITTING ownership + Worker->>Privy: Authorize exact wallet action + Privy->>Arc: Submit ERC-20 USDC transfer + Arc-->>Worker: Final receipt and logs + Worker->>Worker: Verify chain, token, recipient, amount, Transfer + Worker->>DB: Persist COMMITTED and settlement identity + Arc-->>Graph: Transfer event indexed independently + Agent->>API: GET intent status + API-->>Agent: One committed settlement with evidence +``` + +## Ambiguous submission and recovery + +```mermaid +sequenceDiagram + participant Worker + participant DB as PostgreSQL + participant Privy + participant Arc + participant Reconciler + participant Graph as The Graph + + Worker->>DB: Persist SUBMITTING and request identity + Worker->>Privy: Submit authorized transfer + Privy->>Arc: Broadcast transaction + Arc--xWorker: Success response is lost + Worker->>DB: Persist UNKNOWN + Reconciler->>DB: Load intent, request identity, and observations + Reconciler->>Privy: Lookup original provider request + Reconciler->>Arc: Lookup exact transaction receipt and Transfer + Reconciler->>Graph: Query indexed observation plus freshness + Note over Reconciler,Graph: Graph may locate or corroborate activity but cannot authorize a retry + Reconciler->>DB: MARK_COMMITTED when exact Arc success is verified + DB-->>Worker: Redelivery observes terminal state; no second submission +``` + +## Port and adapter boundary + +```mermaid +flowchart LR + Domain[Domain state machine] + Domain --> Auth[AuthorizationPort] + Domain --> Settle[SettlementPort] + Domain --> Evidence[EvidencePort] + Domain --> Index[IndexViewPort] + + Auth --> Privy[Privy adapter] + Settle --> ArcWrite[Arc write adapter] + Evidence --> PrivyRead[Privy lookup] + Evidence --> ArcRead[Arc receipt/log lookup] + Index --> GraphClient[Graph client] + + Privy --> External1[Privy service] + ArcWrite --> External2[Arc RPC] + PrivyRead --> External1 + ArcRead --> External2 + GraphClient --> External3[The Graph] +``` + +The domain consumes stable result families. Adapters translate external SDK, +RPC, and GraphQL behavior into those results. External response shapes never +leak into the state machine. + +## A/B/C ownership and convergence + +```mermaid +flowchart TB + Contracts[Frozen contracts, fixtures, and simulators] + + subgraph A[Coder A - authority and orchestration] + A1[Contracts and OpenAPI] + A2[PostgreSQL intent ledger] + A3[Atomic worker] + A4[Composition and operations] + A1 --> A2 --> A3 --> A4 + end + + subgraph B[Coder B - authorization and settlement] + B1[Privy/Arc compatibility] + B2[Request, policy, receipt] + B3[Live settlement harness] + B4[Ambiguity-safe adapters] + B1 --> B2 --> B3 --> B4 + end + + subgraph C[Coder C - evidence and recovery] + C1[Subgraph and health] + C2[Reconciliation engine] + C3[Failure injection] + C4[Recovery service] + C1 --> C2 --> C3 --> C4 + end + + Contracts --> A1 + Contracts --> B1 + Contracts --> C1 + A4 --> P4[P4 composition] + B4 --> P4 + C4 --> P4 + P4 --> UI[Composed product interface] + UI --> Release[Release evidence] +``` + +Each coder closes backend packets against frozen simulators. P4 is where exact +reviewed packages replace simulators. Integration failures return to the owning +lane instead of producing shared ad hoc edits. diff --git a/milestones/README.md b/milestones/README.md index 07cc02c..357aec1 100644 --- a/milestones/README.md +++ b/milestones/README.md @@ -40,19 +40,9 @@ Use these states in the PR or project tracker: - A project integration failure creates a focused ticket for the owning lane; it does not reopen unrelated completed packets. - Status meetings and review availability do not gate coding. Record assumptions and continue fail-closed. -## Effort and scheduling - -- `S`: less than one focused week. -- `M`: roughly one focused week. -- `L`: roughly one to two focused weeks. - -These are comparison bands, not delivery promises. The root roadmap defines -phase order and the approximate six-to-eight-week product range. Packet closure -still depends on evidence, contracts, and review rather than elapsed time. - ## Small-task sizing -Every numbered task inside a packet should fit one coherent commit, normally two to six focused hours. If a task cannot be reviewed independently, split it by observable behavior, not by internal layer. +Every numbered task inside a packet should produce one coherent, independently reviewable commit. If it cannot be reviewed independently, split it by observable behavior, not by internal layer. Good split: schema + migration, replay behavior, conflict behavior, concurrency proof. Bad split: “all database code,” “all tests,” or “finish integration.” diff --git a/milestones/coder-a/A01-foundation-contracts.md b/milestones/coder-a/A01-foundation-contracts.md index 4e2cb94..b681fd6 100644 --- a/milestones/coder-a/A01-foundation-contracts.md +++ b/milestones/coder-a/A01-foundation-contracts.md @@ -1,7 +1,6 @@ # A01 — Foundation and Contract Runtime Owner: Coder A -Effort: M — roughly one focused week Branch: `milestone/a01-foundation-contracts` Depends on: frozen `milestones/CONTRACTS.md` only Next: A02 immediately after closure diff --git a/milestones/coder-a/A02-durable-intents.md b/milestones/coder-a/A02-durable-intents.md index d9efdfa..9a8ee99 100644 --- a/milestones/coder-a/A02-durable-intents.md +++ b/milestones/coder-a/A02-durable-intents.md @@ -1,7 +1,6 @@ # A02 — Durable Intent Ledger and API Owner: Coder A -Effort: M — roughly one focused week Branch: `milestone/a02-durable-intents` Depends on: A01 only Next: A03 immediately after closure diff --git a/milestones/coder-a/A03-atomic-worker.md b/milestones/coder-a/A03-atomic-worker.md index 0a79912..c4a1c5a 100644 --- a/milestones/coder-a/A03-atomic-worker.md +++ b/milestones/coder-a/A03-atomic-worker.md @@ -1,7 +1,6 @@ # A03 — Atomic At-Most-Once Worker Owner: Coder A -Effort: M — roughly one focused week Branch: `milestone/a03-atomic-worker` Depends on: A02 only Next: A04 immediately after closure diff --git a/milestones/coder-a/A04-restart-operations-composition.md b/milestones/coder-a/A04-restart-operations-composition.md index 9aaf5f1..aa94d98 100644 --- a/milestones/coder-a/A04-restart-operations-composition.md +++ b/milestones/coder-a/A04-restart-operations-composition.md @@ -1,7 +1,6 @@ # A04 — Restart Safety, Operations, and Simulator Composition Owner: Coder A -Effort: L — roughly one to two focused weeks Branch: `milestone/a04-restart-operations-composition` Depends on: A03 only Next: hold A05 until project Gate P4; improve backend evidence while waiting diff --git a/milestones/coder-a/A05-frontend-intent-status.md b/milestones/coder-a/A05-frontend-intent-status.md index d835b5b..8f17d96 100644 --- a/milestones/coder-a/A05-frontend-intent-status.md +++ b/milestones/coder-a/A05-frontend-intent-status.md @@ -1,7 +1,6 @@ # A05 — Frontend Intent and Authoritative Status Owner: Coder A -Effort: S — less than one focused week Branch: `milestone/a05-frontend-intent-status` Depends on: A04 and project Gate P4 Next: A06 immediately after closure diff --git a/milestones/coder-a/A06-release-operations.md b/milestones/coder-a/A06-release-operations.md index 5f8bb25..16e68bd 100644 --- a/milestones/coder-a/A06-release-operations.md +++ b/milestones/coder-a/A06-release-operations.md @@ -1,7 +1,6 @@ # A06 — Operational Demo and Release Bundle Owner: Coder A -Effort: S — less than one focused week Branch: `milestone/a06-release-operations` Depends on: A05 only Project convergence: Gate P6 diff --git a/milestones/coder-b/B01-sdk-network-compatibility.md b/milestones/coder-b/B01-sdk-network-compatibility.md index 22afc81..6bcd564 100644 --- a/milestones/coder-b/B01-sdk-network-compatibility.md +++ b/milestones/coder-b/B01-sdk-network-compatibility.md @@ -1,7 +1,6 @@ # B01 — SDK and Arc Network Compatibility Owner: Coder B -Effort: M — roughly one focused week Branch: `milestone/b01-sdk-network-compatibility` Depends on: frozen `milestones/CONTRACTS.md` only Next: B02 immediately after closure diff --git a/milestones/coder-b/B02-request-policy-receipt.md b/milestones/coder-b/B02-request-policy-receipt.md index 6db6c0c..d799794 100644 --- a/milestones/coder-b/B02-request-policy-receipt.md +++ b/milestones/coder-b/B02-request-policy-receipt.md @@ -1,7 +1,6 @@ # B02 — Canonical Request, Policy, and Receipt Verification Owner: Coder B -Effort: M — roughly one focused week Branch: `milestone/b02-request-policy-receipt` Depends on: B01 only Next: B03 immediately after closure diff --git a/milestones/coder-b/B03-live-settlement-harness.md b/milestones/coder-b/B03-live-settlement-harness.md index f6aa001..2936cd3 100644 --- a/milestones/coder-b/B03-live-settlement-harness.md +++ b/milestones/coder-b/B03-live-settlement-harness.md @@ -1,7 +1,6 @@ # B03 — Offline-Complete and Live-Ready Settlement Harness Owner: Coder B -Effort: M — roughly one focused week Branch: `milestone/b03-live-settlement-harness` Depends on: B02 only Next: B04 immediately after offline closure diff --git a/milestones/coder-b/B04-ambiguity-integration.md b/milestones/coder-b/B04-ambiguity-integration.md index a8cf79c..5344ced 100644 --- a/milestones/coder-b/B04-ambiguity-integration.md +++ b/milestones/coder-b/B04-ambiguity-integration.md @@ -1,7 +1,6 @@ # B04 — Provider Ambiguity and Production Adapter Pack Owner: Coder B -Effort: L — roughly one to two focused weeks Branch: `milestone/b04-ambiguity-integration` Depends on: B03 only Next: hold B05 until project Gate P4 diff --git a/milestones/coder-b/B05-frontend-settlement-details.md b/milestones/coder-b/B05-frontend-settlement-details.md index 2437694..2780c9b 100644 --- a/milestones/coder-b/B05-frontend-settlement-details.md +++ b/milestones/coder-b/B05-frontend-settlement-details.md @@ -1,7 +1,6 @@ # B05 — Frontend Authorization and Settlement Details Owner: Coder B -Effort: S — less than one focused week Branch: `milestone/b05-frontend-settlement-details` Depends on: B04 and project Gate P4 Next: B06 immediately after closure diff --git a/milestones/coder-b/B06-sponsor-evidence.md b/milestones/coder-b/B06-sponsor-evidence.md index b13d1f2..13975e7 100644 --- a/milestones/coder-b/B06-sponsor-evidence.md +++ b/milestones/coder-b/B06-sponsor-evidence.md @@ -1,7 +1,6 @@ # B06 — Privy and Arc Sponsor Evidence Owner: Coder B -Effort: S — less than one focused week Branch: `milestone/b06-sponsor-evidence` Depends on: B05 only Project convergence: Gate P6 diff --git a/milestones/coder-c/C01-subgraph-index-health.md b/milestones/coder-c/C01-subgraph-index-health.md index 182bfb2..e38f359 100644 --- a/milestones/coder-c/C01-subgraph-index-health.md +++ b/milestones/coder-c/C01-subgraph-index-health.md @@ -1,7 +1,6 @@ # C01 — Subgraph Mapping and Index Health Owner: Coder C -Effort: M — roughly one focused week Branch: `milestone/c01-subgraph-index-health` Depends on: frozen `milestones/CONTRACTS.md` only Next: C02 immediately after closure diff --git a/milestones/coder-c/C02-reconciliation-engine.md b/milestones/coder-c/C02-reconciliation-engine.md index 104b8bd..baf68af 100644 --- a/milestones/coder-c/C02-reconciliation-engine.md +++ b/milestones/coder-c/C02-reconciliation-engine.md @@ -1,7 +1,6 @@ # C02 — Deterministic Reconciliation Engine Owner: Coder C -Effort: M — roughly one focused week Branch: `milestone/c02-reconciliation-engine` Depends on: C01 only Next: C03 immediately after closure diff --git a/milestones/coder-c/C03-failure-injection.md b/milestones/coder-c/C03-failure-injection.md index 43fcc05..57d403d 100644 --- a/milestones/coder-c/C03-failure-injection.md +++ b/milestones/coder-c/C03-failure-injection.md @@ -1,7 +1,6 @@ # C03 — Cross-Source Failure Injection Owner: Coder C -Effort: M — roughly one focused week Branch: `milestone/c03-failure-injection` Depends on: C02 only Next: C04 immediately after closure diff --git a/milestones/coder-c/C04-recovery-matrix-integration.md b/milestones/coder-c/C04-recovery-matrix-integration.md index 11e8456..017071a 100644 --- a/milestones/coder-c/C04-recovery-matrix-integration.md +++ b/milestones/coder-c/C04-recovery-matrix-integration.md @@ -1,7 +1,6 @@ # C04 — Recovery Matrix and Simulator Integration Owner: Coder C -Effort: L — roughly one to two focused weeks Branch: `milestone/c04-recovery-matrix-integration` Depends on: C03 only Next: hold C05 until project Gate P4 diff --git a/milestones/coder-c/C05-frontend-recovery.md b/milestones/coder-c/C05-frontend-recovery.md index cd78336..8bf8e1b 100644 --- a/milestones/coder-c/C05-frontend-recovery.md +++ b/milestones/coder-c/C05-frontend-recovery.md @@ -1,7 +1,6 @@ # C05 — Frontend Recovery Timeline and Indexed History Owner: Coder C -Effort: S — less than one focused week Branch: `milestone/c05-frontend-recovery` Depends on: C04 and project Gate P4 Next: C06 immediately after closure diff --git a/milestones/coder-c/C06-qualification-demo.md b/milestones/coder-c/C06-qualification-demo.md index 3bb49e0..29c5eca 100644 --- a/milestones/coder-c/C06-qualification-demo.md +++ b/milestones/coder-c/C06-qualification-demo.md @@ -1,7 +1,6 @@ # C06 — The Graph, Recovery, and Qualification Bundle Owner: Coder C -Effort: S — less than one focused week Branch: `milestone/c06-qualification-demo` Depends on: C05 only Project convergence: Gate P6 diff --git a/plan.md b/plan.md index dd7b060..d4be034 100644 --- a/plan.md +++ b/plan.md @@ -2,10 +2,10 @@ Status: production MVP roadmap Team: exactly three coders -Indicative delivery range: six to eight weeks with three active coders Implementation base: the human-approved commit containing this plan Research basis: `.agent/research/20260906-integration-decisions.md` Detailed work packets: [`milestones/README.md`](milestones/README.md) +Domain architecture: [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md) ## Global product vision @@ -51,17 +51,36 @@ Business Intent contract. | Reconciliation service | Agent and operator | Resolve ambiguous outcomes without blindly paying again | | Audit and recovery timeline | Company and supplier | Explain what happened, which evidence is authoritative, and what action is safe | +```mermaid +flowchart LR + Company[Company operator] -->|wallet policy and limits| Privy[Privy] + Agent[Autonomous agent] -->|stable business intent| API[OneShot API] + Agent -.->|requests paid work| SupplierAPI[Paid API or digital supplier] + API --> Core[OneShot domain] + Core --> DB[(PostgreSQL authority)] + DB --> Worker[Execution worker] + Worker -->|authorized transfer request| Privy + Privy -->|ERC-20 USDC transaction| Arc[Arc] + Arc -->|one settlement| SupplierWallet[Supplier wallet] + Arc --> Graph[The Graph index] + Graph --> Recovery[Recovery view] + DB --> Recovery + Recovery --> Agent + Recovery --> Company +``` + +OneShot controls payment cardinality. It does not guarantee the quality or +delivery of the supplier's API result; that remains a separate commercial +contract. + ## Production roadmap model - The roadmap targets a production-quality testnet MVP, not a disposable demo. -- The overall six-to-eight-week range is approximate and is recalibrated after - the independent foundation phase and the first live Privy/Arc compatibility - proof. -- Work packets use `S`, `M`, and `L` effort bands instead of fixed - per-packet date promises: `S` is less than one focused week, `M` is roughly one focused week, - and `L` is roughly one to two focused weeks. -- A, B, and C progress independently inside frozen contracts. Product phases - advance when evidence gates pass, not when a date arrives. +- Work is ordered by domain dependencies and evidence gates. +- A, B, and C progress independently inside frozen contracts and converge only + through reviewed package entry points, fixtures, and simulators. +- A phase advances when its exit evidence passes; a packet advances when its + local acceptance contract passes. - Frontend production work begins after backend convergence freezes the public API and recovery semantics. @@ -158,21 +177,35 @@ protocol are frozen in [`milestones/CONTRACTS.md`](milestones/CONTRACTS.md). ## 6. Architecture -```text -Autonomous agent / operator console - | - v -Fastify API -------> PostgreSQL authoritative ledger <--- Graphile Worker - | | | - | +-- transactional jobs/outbox -+ - | - +--> AuthorizationPort --> Privy policy/wallet - +--> SettlementPort ----> Arc ERC-20 USDC - +--> EvidencePort ------> Privy status + Arc RPC - +--> IndexViewPort -----> The Graph observation +```mermaid +flowchart TB + Clients[Agent API client and operator console] --> API[apps/api - Fastify] + API --> Domain[packages/domain] + Domain --> Contracts[packages/contracts] + Domain --> Storage[packages/storage-postgres] + Storage --> DB[(PostgreSQL)] + Storage --> Outbox[Transactional outbox] + Outbox --> Worker[apps/worker - Graphile Worker] + Worker --> Domain + + Domain --> AuthPort[AuthorizationPort] + Domain --> SettlementPort[SettlementPort] + Domain --> EvidencePort[EvidencePort] + Domain --> IndexPort[IndexViewPort] + + AuthPort --> PrivyAdapter[packages/privy-adapter] + SettlementPort --> ArcAdapter[packages/arc-adapter] + EvidencePort --> ArcAdapter + PrivyAdapter --> Privy[Privy wallet and policy] + ArcAdapter --> Arc[Arc USDC and RPC] + + IndexPort --> Reconciliation[packages/reconciliation] + Reconciliation --> GraphClient[packages/graph-client] + GraphClient --> Subgraph[The Graph Subgraph] + Subgraph --> Arc ``` -OneShot decides whether settlement may be attempted. Privy constrains authorized wallet actions. Arc provides final settlement evidence. The Graph explains indexed history and freshness but grants no settlement right. +OneShot decides whether settlement may be attempted. Privy constrains authorized wallet actions. Arc provides final settlement evidence. The Graph explains indexed history and freshness but grants no settlement right. Detailed entity, state, sequence, and ownership diagrams live in [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md). ## 7. Team topology and exclusive ownership @@ -265,66 +298,78 @@ Consumers validate against the pack, not against a producer’s active branch. - Questions default to a written assumption plus a fail-closed implementation. Only decisions that could weaken settlement cardinality, money representation, authorization, or `UNKNOWN` handling require synchronous escalation. - Daily status is informational and never an approval gate. -## 9. Delivery phases and indicative schedule +## 9. Delivery phases and dependency gates -The three lanes run in parallel. The calendar ranges below describe likely -elapsed time with three active coders; they are planning estimates rather than -deadlines or permission to weaken acceptance evidence. +The three lanes run in parallel. Phase order expresses dependency and product +readiness only. A lane may begin its next packet as soon as its own acceptance +contract passes. -| Phase | Approximate duration | Coder A | Coder B | Coder C | Exit evidence | +| Phase | Entry condition | Coder A | Coder B | Coder C | Exit evidence | | --- | --- | --- | --- | --- | --- | -| R0 — product and contract freeze | Less than one week | Confirm domain/API contract | Confirm provider/chain contract | Confirm recovery/index contract | P0 approved scope and immutable v1 pack | -| R1 — independent foundations | About one week | A01 | B01 | C01 | P1 independent toolchains and compatibility findings | -| R2 — durable core and adapters | About one week | A02 | B02 | C02 | P2 compatible contract packs and simulators | -| R3 — safety under failure | About one week | A03 | B03 | C03 | P3 concurrency, ambiguity, and failure proofs | -| R4 — backend convergence | One to two weeks | A04 and composition owner | B04 and live settlement evidence | C04 and live index/recovery evidence | P4 integrated backend, one real settlement, lost-response recovery | -| R5 — product interface | About one week | A05 application shell | B05 policy/settlement slice | C05 recovery/history slice | P5 composed operator experience | -| R6 — hardening and release | About one week | A06 operations bundle | B06 Privy/Arc evidence | C06 Graph/recovery evidence | P6 repeatable release candidate | - -The expected production-MVP range is six to eight weeks because early phases -overlap across the three lanes. Provider access, SDK incompatibility, or failed -P4 evidence may extend the range. A completed packet immediately unlocks the -next same-owner packet; teams do not wait for ceremonial phase boundaries. +| R0 — product and contract freeze | Product vertical selected | Confirm domain/API contract | Confirm provider/chain contract | Confirm recovery/index contract | P0 approved scope and immutable v1 pack | +| R1 — independent foundations | P0 | A01 | B01 | C01 | P1 runnable toolchains and recorded compatibility findings | +| R2 — durable core and adapters | Own R1 packet | A02 | B02 | C02 | P2 compatible contract packs and simulators | +| R3 — safety under failure | Own R2 packet | A03 | B03 | C03 | P3 concurrency, ambiguity, and failure proofs | +| R4 — backend convergence | A03/B03/C03 artifacts available | A04 and composition owner | B04 and live settlement evidence | C04 and live index/recovery evidence | P4 integrated backend, one real settlement, lost-response recovery | +| R5 — product interface | P4 | A05 application shell | B05 policy/settlement slice | C05 recovery/history slice | P5 composed operator experience | +| R6 — hardening and release | P5 | A06 operations bundle | B06 Privy/Arc evidence | C06 Graph/recovery evidence | P6 repeatable release candidate | + +Provider access, SDK incompatibility, or failed integration evidence opens an +owner-specific compatibility task. It never weakens the safety invariant or +silently changes a contract. ## 10. Work-packet inventory -| ID | Owner | Effort | Own-track prerequisite | Independently verifiable output | -| --- | --- | ---: | --- | --- | -| [A01](milestones/coder-a/A01-foundation-contracts.md) | A | M | Frozen contract pack | Workspace, contracts package, OpenAPI, domain simulator | -| [A02](milestones/coder-a/A02-durable-intents.md) | A | M | A01 | PostgreSQL intent/replay/conflict API | -| [A03](milestones/coder-a/A03-atomic-worker.md) | A | M | A02 | Atomic worker and at-most-once fake-port proof | -| [A04](milestones/coder-a/A04-restart-operations-composition.md) | A | L | A03 | Restart-safe orchestration and simulator composition | -| [A05](milestones/coder-a/A05-frontend-intent-status.md) | A | S | A04 + project Gate P4 | Intent/status frontend slice against mock server | -| [A06](milestones/coder-a/A06-release-operations.md) | A | S | A05 | Operational demo and release bundle | -| [B01](milestones/coder-b/B01-sdk-network-compatibility.md) | B | M | Frozen contract pack | SDK/network compatibility and readiness package | -| [B02](milestones/coder-b/B02-request-policy-receipt.md) | B | M | B01 | Canonical request, policy, and receipt verifier | -| [B03](milestones/coder-b/B03-live-settlement-harness.md) | B | M | B02 | Offline-complete plus live-ready settlement harness | -| [B04](milestones/coder-b/B04-ambiguity-integration.md) | B | L | B03 | Conservative outcomes and production adapter pack | -| [B05](milestones/coder-b/B05-frontend-settlement-details.md) | B | S | B04 + project Gate P4 | Authorization/settlement UI slice against fixtures | -| [B06](milestones/coder-b/B06-sponsor-evidence.md) | B | S | B05 | Privy/Arc sanitized evidence bundle | -| [C01](milestones/coder-c/C01-subgraph-index-health.md) | C | M | Frozen contract pack | Subgraph mappings and Graph health client | -| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | M | C01 | Deterministic reconciliation and evidence contract | -| [C03](milestones/coder-c/C03-failure-injection.md) | C | M | C02 | Cross-source chaos and restart harness | -| [C04](milestones/coder-c/C04-recovery-matrix-integration.md) | C | L | C03 | Recovery matrix and simulator integration pack | -| [C05](milestones/coder-c/C05-frontend-recovery.md) | C | S | C04 + project Gate P4 | Recovery timeline UI slice against fixtures | -| [C06](milestones/coder-c/C06-qualification-demo.md) | C | S | C05 | Graph/recovery qualification bundle | +| ID | Owner | Own-track prerequisite | Independently verifiable output | +| --- | --- | --- | --- | +| [A01](milestones/coder-a/A01-foundation-contracts.md) | A | Frozen contract pack | Workspace, contracts package, OpenAPI, domain simulator | +| [A02](milestones/coder-a/A02-durable-intents.md) | A | A01 | PostgreSQL intent/replay/conflict API | +| [A03](milestones/coder-a/A03-atomic-worker.md) | A | A02 | Atomic worker and at-most-once fake-port proof | +| [A04](milestones/coder-a/A04-restart-operations-composition.md) | A | A03 | Restart-safe orchestration and simulator composition | +| [A05](milestones/coder-a/A05-frontend-intent-status.md) | A | A04 + project Gate P4 | Intent/status frontend slice against mock server | +| [A06](milestones/coder-a/A06-release-operations.md) | A | A05 | Operational demo and release bundle | +| [B01](milestones/coder-b/B01-sdk-network-compatibility.md) | B | Frozen contract pack | SDK/network compatibility and readiness package | +| [B02](milestones/coder-b/B02-request-policy-receipt.md) | B | B01 | Canonical request, policy, and receipt verifier | +| [B03](milestones/coder-b/B03-live-settlement-harness.md) | B | B02 | Offline-complete plus live-ready settlement harness | +| [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-subgraph-index-health.md) | C | Frozen contract pack | Subgraph mappings and Graph health client | +| [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | C01 | Deterministic reconciliation and evidence 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 | +| [C06](milestones/coder-c/C06-qualification-demo.md) | C | C05 | Graph/recovery qualification bundle | Each packet contains smaller, one-commit-sized tasks, exact acceptance criteria, tests, output artifacts, and a no-wait continuation instruction. ## 11. Dependency graph -```text -Frozen v1 contract pack - |--------------------|--------------------| - v v v - A01 -> A02 -> A03 -> A04 A05 -> A06 - B01 -> B02 -> B03 -> B04 -- P4 backend -> B05 -> B06 - C01 -> C02 -> C03 -> C04 gate C05 -> C06 - | - real adapters replace simulators +```mermaid +flowchart LR + Contract[Frozen v1 contract pack] + + Contract --> A01 --> A02 --> A03 --> A04 + Contract --> B01 --> B02 --> B03 --> B04 + Contract --> C01 --> C02 --> C03 --> C04 + + A04 --> P4{P4 backend convergence} + B04 --> P4 + C04 --> P4 + + P4 --> A05 --> A06 + P4 --> B05 --> B06 + P4 --> C05 --> C06 + + A06 --> P6{P6 release candidate} + B06 --> P6 + C06 --> P6 ``` -The lane arrows are same-owner dependencies. Gate P4 is the only intentional convergence point before frontend. No backend work packet waits for P4 to close; A04/B04/C04 close against their own contract simulators. P4 only decides whether frontend may begin. +The lane arrows are same-owner dependencies. Gate P4 is the intentional +backend convergence point. A04/B04/C04 close against contract simulators; P4 +replaces them with exact reviewed package entry points and live testnet +evidence before frontend work begins. ## 12. Project gates @@ -340,7 +385,7 @@ Project gates coordinate the product but are not coder work-packet closure condi - A01, B01, and C01 each pass package-local checks without third-party credentials. - Every lane can continue using only committed fixtures and simulators. -- Forecast is recalibrated from actual SDK/tooling friction. +- SDK/tooling compatibility findings are recorded before contract-pack convergence. ### P2 — contract-pack compatibility @@ -451,7 +496,7 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy | 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 | -| Schedule pressure | Cut webhooks, rolling policy support, visual polish, and optional telemetry before safety | All | +| Scope pressure | Cut webhooks, rolling policy support, visual polish, and optional telemetry before safety | All | ## 19. Definition of done for every packet @@ -591,9 +636,9 @@ Continue asynchronously with a documented conservative assumption for ordinary i An escalation record contains the exact decision, safest default, affected contract/version, options, security impact, and owner. While it is unresolved, unaffected packets continue and the affected boundary fails closed. -## 25. Schedule control and scope-cut order +## 25. Scope control and cut order -The six-to-eight-week production-MVP range is a forecast. Re-estimate at P1 and after any provider compatibility failure. Never change acceptance evidence silently to preserve dates. +Never change acceptance evidence to accelerate delivery. When integration or provider assumptions fail, reduce optional scope or open an owner-specific compatibility task. If time is constrained, cut in this order: @@ -664,4 +709,4 @@ Before Gate P6 can pass, confirm: 4. Each coder closes and advances through their own lane without waiting for global milestone closure. 5. Run project gates asynchronously when all required artifacts happen to be available; failures create focused owner tickets and do not halt unaffected work. 6. Do not start A05, B05, or C05 until P4 passes. -7. Re-estimate after P1 using measured friction, preserving all safety criteria. +7. Record P1 integration friction and adjust optional scope while preserving all safety criteria. From 47d289fab6c09338cc0bcd117a501203ad7bedd8 Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Sun, 6 Sep 2026 22:38:27 +0200 Subject: [PATCH 3/3] docs(plan): fix recovery diagrams --- .../20260906T201351Z-product-roadmap.md | 2 +- docs/DOMAIN_ARCHITECTURE.md | 36 +++++++++++++------ plan.md | 22 +++++++----- 3 files changed, 40 insertions(+), 20 deletions(-) diff --git a/.agent/context/20260906T201351Z-product-roadmap.md b/.agent/context/20260906T201351Z-product-roadmap.md index 34440a9..6ec0d63 100644 --- a/.agent/context/20260906T201351Z-product-roadmap.md +++ b/.agent/context/20260906T201351Z-product-roadmap.md @@ -42,7 +42,7 @@ contributes to the complete product. - All local Markdown links in `plan.md`, `milestones/`, and `docs/` resolve. - Exactly 18 packet files remain. - Packet headers contain no planning-size metadata. -- Mermaid fence pairs and required diagram types are checked structurally. +- Mermaid CLI 11.17.0 rendered all 10 diagrams successfully. - `git diff --check` passes. - Gate A and Gate B were intentionally not run because the user explicitly requested skipping the two-review procedure for the planning phase. diff --git a/docs/DOMAIN_ARCHITECTURE.md b/docs/DOMAIN_ARCHITECTURE.md index 2fb026d..c26f095 100644 --- a/docs/DOMAIN_ARCHITECTURE.md +++ b/docs/DOMAIN_ARCHITECTURE.md @@ -18,8 +18,10 @@ flowchart LR Privy --> Arc[Arc USDC settlement] Arc --> SupplierWallet[Supplier wallet] Arc --> Index[The Graph index] - Ledger --> Recovery[Recovery and audit view] - Index --> Recovery + Ledger --> Recovery[Recovery service and audit view] + Recovery -->|provider lookup| Privy + Recovery -->|receipt and log lookup| Arc + Recovery -->|indexed history and freshness| Index Recovery --> Agent Recovery --> Operator ``` @@ -101,6 +103,7 @@ stateDiagram-v2 UNKNOWN --> COMMITTED: original payment verified UNKNOWN --> FAILED_SAFE: authoritative final no-effect proof UNKNOWN --> UNKNOWN: pending, absent, stale, unhealthy, or contradictory evidence + FAILED_SAFE --> AUTHORIZING: policy opens a new attempt REJECTED --> [*] COMMITTED --> [*] ``` @@ -142,11 +145,15 @@ sequenceDiagram API->>DB: Insert intent and outbox job atomically DB-->>API: New intent or identical replay API-->>Agent: Authoritative intent state - Worker->>DB: Acquire AUTHORIZING/READY/SUBMITTING ownership - Worker->>Privy: Authorize exact wallet action - Privy->>Arc: Submit ERC-20 USDC transfer + Worker->>DB: Claim AUTHORIZING attempt + Worker->>Privy: Evaluate exact wallet policy + Privy-->>Worker: AUTHORIZED + Worker->>DB: Persist AUTHORIZING to READY + Worker->>DB: Atomically persist SUBMITTING and request identity + Worker->>Privy: Submit the authorized transfer + Privy->>Arc: Broadcast ERC-20 USDC transaction Arc-->>Worker: Final receipt and logs - Worker->>Worker: Verify chain, token, recipient, amount, Transfer + Worker->>Worker: Verify chain, token, recipient, amount, and Transfer Worker->>DB: Persist COMMITTED and settlement identity Arc-->>Graph: Transfer event indexed independently Agent->>API: GET intent status @@ -174,8 +181,10 @@ sequenceDiagram Reconciler->>Arc: Lookup exact transaction receipt and Transfer Reconciler->>Graph: Query indexed observation plus freshness Note over Reconciler,Graph: Graph may locate or corroborate activity but cannot authorize a retry - Reconciler->>DB: MARK_COMMITTED when exact Arc success is verified - DB-->>Worker: Redelivery observes terminal state; no second submission + Reconciler->>Domain: Emit MARK_COMMITTED with expected version + Domain->>DB: Compare and set UNKNOWN to COMMITTED + Worker->>DB: Check the same intent after redelivery + DB-->>Worker: Terminal state means no second submission ``` ## Port and adapter boundary @@ -183,15 +192,20 @@ sequenceDiagram ```mermaid flowchart LR Domain[Domain state machine] + Reconciliation[Reconciliation engine] + Command[Versioned reconciliation command] + Domain --> Auth[AuthorizationPort] Domain --> Settle[SettlementPort] - Domain --> Evidence[EvidencePort] - Domain --> Index[IndexViewPort] + Reconciliation --> Evidence[EvidencePort] + Reconciliation --> Index[IndexViewPort] + Reconciliation --> Command + Command --> Domain Auth --> Privy[Privy adapter] Settle --> ArcWrite[Arc write adapter] Evidence --> PrivyRead[Privy lookup] - Evidence --> ArcRead[Arc receipt/log lookup] + Evidence --> ArcRead[Arc receipt and log lookup] Index --> GraphClient[Graph client] Privy --> External1[Privy service] diff --git a/plan.md b/plan.md index d4be034..a82d07d 100644 --- a/plan.md +++ b/plan.md @@ -63,8 +63,10 @@ flowchart LR Privy -->|ERC-20 USDC transaction| Arc[Arc] Arc -->|one settlement| SupplierWallet[Supplier wallet] Arc --> Graph[The Graph index] - Graph --> Recovery[Recovery view] - DB --> Recovery + DB --> Recovery[Recovery service and view] + Recovery -->|provider lookup| Privy + Recovery -->|receipt and log lookup| Arc + Recovery -->|indexed history and freshness| Graph Recovery --> Agent Recovery --> Company ``` @@ -185,22 +187,26 @@ flowchart TB Domain --> Storage[packages/storage-postgres] Storage --> DB[(PostgreSQL)] Storage --> Outbox[Transactional outbox] - Outbox --> Worker[apps/worker - Graphile Worker] + Outbox --> Worker[Settlement worker] + Outbox --> RecoveryWorker[Reconciliation worker] Worker --> Domain + RecoveryWorker --> Reconciliation[packages/reconciliation] + Reconciliation --> Command[Versioned reconciliation command] + Command --> Domain Domain --> AuthPort[AuthorizationPort] Domain --> SettlementPort[SettlementPort] - Domain --> EvidencePort[EvidencePort] - Domain --> IndexPort[IndexViewPort] + Reconciliation --> EvidencePort[EvidencePort] + Reconciliation --> IndexPort[IndexViewPort] AuthPort --> PrivyAdapter[packages/privy-adapter] SettlementPort --> ArcAdapter[packages/arc-adapter] + EvidencePort --> PrivyAdapter EvidencePort --> ArcAdapter + IndexPort --> GraphClient[packages/graph-client] + PrivyAdapter --> Privy[Privy wallet and policy] ArcAdapter --> Arc[Arc USDC and RPC] - - IndexPort --> Reconciliation[packages/reconciliation] - Reconciliation --> GraphClient[packages/graph-client] GraphClient --> Subgraph[The Graph Subgraph] Subgraph --> Arc ```