diff --git a/docs/v2/INCREMENTAL_DEV_PLAN.md b/docs/v2/INCREMENTAL_DEV_PLAN.md new file mode 100644 index 0000000..a814411 --- /dev/null +++ b/docs/v2/INCREMENTAL_DEV_PLAN.md @@ -0,0 +1,188 @@ +# TORCH 2.0 × BitUnlock — Incremental Development Plan + +**Status:** Draft v0.1 +**Canonical for:** cross-repo sequencing of TORCH 2.0 and the BitUnlock changes it needs. +**Companions:** [`DEVELOPMENT_NETWORK_SPEC.md`](./DEVELOPMENT_NETWORK_SPEC.md) (product vision), [`V2_ARCHITECTURE_BRIDGE.md`](./V2_ARCHITECTURE_BRIDGE.md) (verified terrain), BitUnlock `docs/TORCH_INTEGRATION_PLAN.md` (BitUnlock-side engineering view). + +## 0. Governing rules + +1. **BitUnlock upgrades are allowed but must never break existing tenants** (Satisfied, BitRoad) or the published contract. Every BitUnlock change in this plan is additive: new tables via append-only migrations, new endpoints marked in OpenAPI, new behavior behind per-tenant capabilities that default **off**. Turning a capability off must restore exactly today's behavior. +2. **TORCH promotes BitUnlock's existing backlog; it does not invent parallel systems.** Everything TORCH needs from BitUnlock already exists as a designed item in BitUnlock's `docs/FUTURE_APPLICATION_PERMISSION_ROADMAP.md`. That document's promotion criteria (§17) require a second application class and an independently versioned reference consumer — TORCH is both. We activate items in TORCH-need order, not roadmap-tier order. +3. **TORCH work must not displace BitUnlock's own stabilization work.** BitUnlock's `docs/TODO.md` Priority 0–1 items (production reconciliation, backup/recovery, GA gates) and the owner action items proceed independently. No stage below requires pausing them; Stage 2+ BitUnlock items should land only after Priority 1 gates are green. +4. **Every increment is a safe stopping point.** If work halts after any increment, both products remain shippable and no tenant is broken. +5. **Custody rules from the spec bind every increment.** TORCH holds no compute principal in Stages 0–2. Any increment that would put a bearer credential under TORCH control (Stage 3) requires a durable-custody design pass first — the standing lesson from BitUnlock's Cashu post-mortem (`docs/CASHU_MICROPAYMENTS_PLAN.md` §8a). + +## 1. Stage map + +```text +Stage 0 Foundations TORCH docs/schemas; BitUnlock untouched (operator actions only) +Stage 1 Pilot (spec Phase A) TORCH campaign service + static products; BitUnlock code unchanged +Stage 2 Notifications+Sponsors Webhooks, payer/beneficiary; TORCH Build campaigns +Stage 3 Compute leases Allowance ledger, machine delegation; TORCH provider gateway +Stage 4 Scale economics Multi-payer funding, adjustments, subscriptions; Foundry +``` + +Each stage's BitUnlock items map to `FUTURE_APPLICATION_PERMISSION_ROADMAP.md` sections, cited as FR §n. + +--- + +## Stage 0 — Foundations (TORCH-only; BitUnlock operator/owner actions only) + +No BitUnlock code changes. TORCH work is docs + schemas + additive lock-protocol fields. + +### T0.1 Spec v0.2 +Fold the bridge's §4.5 corrections into `DEVELOPMENT_NETWORK_SPEC.md`: milestone-grained fees, pledges as TORCH-side signed events, poll-driven order tracking, refunds scoped to provider layer, Mode D deferred to Stage 4, Mode A-only compute for the pilot. +**Exit:** spec and bridge contain no contradictions. + +### T0.2 v2 object schemas +JSON Schemas under `docs/v2/schemas/`: `campaign`, `milestone`, `task-contract`, `pledge`, `evidence-bundle`, `stewardship-manifest` (the public `ai-contributions` manifest). Wire into CI beside the existing scheduler contract validators (`npm run validate:scheduler` pattern). +**Exit:** schemas validate in CI; example instances committed as fixtures. + +### T0.3 Additive lock-event fields +Optional `campaignId`, `milestoneId`, `taskContractHash`, `leaseId`, `actor` in lock content JSON plus the v2 d-tag grammar. 1.x events without these fields remain fully valid. +**Exit:** existing test suite green untouched; new round-trip tests for v2 fields; a 1.x-only scheduler run behaves identically. + +### T0.4 Evidence bundle v1 +Normalize `verify-run-artifacts.mjs` output + task-log into one signed JSON document conforming to the T0.2 schema; publish its hash as a Nostr event via the existing quorum publisher. +**Exit:** a normal scheduler run emits a verifiable signed bundle; verification CLI (`torch-lock verify-evidence`) validates signature + schema + hash. + +### T0.5 Durable actor identity +Two-key model from the bridge §6.1: locks stay ephemeral, but carry an `actor` npub with a signature over the lock's d-tag. Actor registry document format for maintainer/sponsor/verifier/worker roles. +**Exit:** attribution verifiable from relay data alone. + +### B0.1 (operator) TORCH tenant on staging +Allowlist a TORCH service pubkey on BitUnlock **staging**; create tenant, connect wallet, register a throwaway static product; run one fake order end to end. Stand up the sandbox Worker for TORCH CI use. +**Exit:** TORCH CI can exercise a full quote→pay→unlock against the sandbox. + +### B0.2 (owner) License decision +BitUnlock has no license ("all rights reserved"), and `@bitunlock/protocol`/`@bitunlock/sdk` are unpublished — TORCH must vendor them the way BitRoad does. Decide BitUnlock's license (or at minimum a vendoring grant for the two packages) **before** TORCH 2.0 code that imports them is published. +**Exit:** recorded decision; TORCH vendoring is legally clean. + +--- + +## Stage 1 — Pilot (spec Phase A; BitUnlock code unchanged) + +TORCH becomes a real BitUnlock tenant selling static products. Polling only. Mode A compute only (sponsor-created spend-limited provider keys that TORCH never touches). + +### T1.1 Campaign service skeleton +New service (recommended: Cloudflare Worker + D1, copying BitUnlock's NIP-98/idempotency/tenant-scoping patterns — same operator, same stack). Owns: campaigns, milestones, task contracts, pledge registry, evidence index, BitUnlock order polling. Publishes signal events to relays; repo-side scheduler talks to it over REST + NIP-98. +**Exit:** CRUD + state machine tested; poll loop reconciles sandbox orders. + +### T1.2 Coordination fee as static product +One BitUnlock static product per milestone coordination fee (json payload = signed milestone receipt); verification reserve as a second product; private report access via term-access entitlements verified **offline** with the vendored SDK. +**Exit:** paying the product on staging flips the milestone's funding state in the campaign service via polling; report endpoint honors entitlements. + +### T1.3 The pilot (spec §24) +One opted-in repo, one Stewardship campaign, sponsor-supplied limited OpenRouter key configured directly into the runner environment, TORCH-operated worker, one independent verifier, coordination fee paid through BitUnlock **production** (operator allowlists the TORCH tenant on prod), public cost/outcome summary. +**Exit criteria (from the spec):** maintainer accepts the result; compute stayed within the sponsor limit; TORCH held no principal; review cost the maintainer less than doing the coordination manually. Even a pilot where the operator plays all human roles counts for the machinery; a pilot with one external party counts for the product. + +**BitUnlock during Stage 1:** zero code changes. Operator actions: prod allowlist; optionally `single-recipient` + `accrual` billing for the TORCH tenant (existing, capability-gated, already exercised in production by the fee ledger). + +--- + +## Stage 2 — Notifications and sponsor flows (spec Phase B) + +First BitUnlock code changes. Both are FR Tier 1 items whose promotion criteria TORCH now satisfies. Land only after BitUnlock Priority 1 gates are green. + +### B2.1 Signed lifecycle events + webhooks (FR §4) +As specified in FR §4: common signed envelope; transports = signed HTTPS webhooks + encrypted Nostr events, with **polling preserved forever as fallback** (so no existing tenant must change). Event set for the first cut: `order.created`, `order.paid`, `entitlement.issued`, `entitlement.revoked`, `execution.completed`, `execution.failed`. +**Compat:** new tables (append-only migrations); per-tenant opt-in endpoint registration; no payload contains credentials or entitlement plaintext; OpenAPI routes added as new; conformance vectors extended, none modified. +**Tests:** delivery/retry/replay-window/dead-letter negative vectors; regression run of Satisfied + BitRoad flows with the capability off *and* on-but-unregistered. +**Exit:** TORCH campaign service consumes webhooks with polling fallback (T2.1); no behavior change for tenants that never register an endpoint. + +### B2.2 Payer/beneficiary separation (FR §6) +Mode 1 first (known beneficiary): sponsor pubkey pays; entitlement issues to a named beneficiary (maintainer, verifier, or the campaign service itself). Private claims (mode 2) deferred until entitlement recovery is stable, per BitUnlock's own sequencing note. +**Compat:** absent a `beneficiaryPubkey`, behavior is byte-identical to today (payer = beneficiary). Capability-gated per tenant; new schema fields optional. +**Exit:** a sponsor can fund a milestone product whose entitlement lands with the campaign or maintainer; negative vectors for wrong-beneficiary redemption. + +### T2.1 Webhook consumption + reconciliation +Campaign service prefers webhooks, reconciles by polling, and treats poll state as authoritative on conflict. + +### T2.2 Build-campaign machinery +Feature contracts (signed, versioned via the existing prompt-governance service), milestone DAG replacing roster round-robin for campaign work (1.x roster mode remains untouched for maintenance fleets), pledge lifecycle (signed pledge events → JIT settlement prompts when a milestone goes ready), sponsor/maintainer notification digests. +**Exit:** one small Build campaign (spec §24 example: bounded export feature) runs end to end on staging rails. + +--- + +## Stage 3 — Compute leases (spec Phase C; the custody-sensitive stage) + +Gate: written custody design for every bearer credential TORCH's gateway will hold, reviewed against the Cashu post-mortem criteria (durable custody first-class; fee economics per rail) **before** implementation. + +### B3.1 Generic usage/allowance ledger (FR §3) +An entitlement grants N units ("inference-sats", "tokens", "verifier-runs"); idempotent, concurrency-safe consumption API with signed usage receipts; rail-agnostic (Lightning-funded now, Cashu-fundable later if ever revisited). This is the BitUnlock-side representation of the spec's **compute lease**. +**Compat:** entirely new subsystem; existing entitlements gain nothing unless a product opts in. Capability-gated. +**Exit:** overspend impossible under concurrent consumption (adversarial test); TORCH can reconcile gateway metering against ledger receipts. + +### B3.2 Machine/service-account delegation (FR §8) +Worker-agent keys consume allowances under a grant bound to owner, machine pubkey, allowed operations, allowance, expiry, revocation. Independently revocable; never inherits billing or tenant admin. +**Compat:** additive; no existing auth path changes. + +### T3.1 Provider gateway +TORCH-side OpenAI-compatible proxy that meters tokens against a lease/allowance, kills at ceiling, reconciles usage, and handles credential injection/revocation for Mode B (ephemeral Routstr sessions). This is where the Stage 3 custody gate applies. + +### T3.2 Verification depth +Blind verifier assignment on independent leases; human-testing task flows; evidence-bundle cross-verification. + +### B3.3 (optional) TORCH execution schemas +Only if TORCH sells execution products: register TORCH input/output schemas in BitUnlock's validator registry and, if needed, a campaign-service adapter beside `routstr-adapter.ts`. Skip if static products + TORCH's own gateway cover the need — fewer moving parts in BitUnlock. + +--- + +## Stage 4 — Scale economics (spec Phases D/E; Foundry) + +Highest-complexity BitUnlock items; each needs the legal review the spec (§21) and FR Tier 3 both call for. + +### B4.1 Multi-payer funding / group unlocks (FR §13) +Many sponsors contribute toward one milestone target with defined partial-funding and target-failure behavior. This is the custody-minimized replacement for the spec's Mode F campaign reserve — contributions are tracked by BitUnlock as order-shaped facts, not pooled in a TORCH wallet. +**Gate:** legal/regulatory review first (FR §13 lists it; spec §21 requires it). + +### B4.2 Adjustment/credit artifacts (FR §11) +Signed refund/credit/compensation artifacts referencing original orders — gives the spec's "unused value returns" language an auditable form without moving BitUnlock into escrow. + +### B4.3 Subscription transformations (FR §5) +Maintainer subscriptions with upgrades/supersession, after manual renewal is proven. + +### B4.4 Third payment role (spec Mode D) +Only if Stages 1–3 prove per-milestone single-leg + accrual insufficient. This is the one item that is a true protocol version change (`PAYMENT_ROLES` is frozen); it stays last and may never be needed. + +### T4.x Foundry +Charters, exploration milestones, competing prototypes, graduation — pure TORCH-side product work on the machinery Stages 1–3 built. + +--- + +## 2. Cross-cutting compatibility discipline (every BitUnlock increment) + +Inherited from BitUnlock's `AGENTS.md` and existing practice; restated here as the plan's contract: + +- Append-only migrations; never edit a committed migration. +- Capability-gated, default-off; off = today's exact behavior. +- Clients must stay leg-count-agnostic (already mandated); nothing here changes leg semantics until B4.4, which is version-negotiated. +- OpenAPI updated in the same change; `documentation-truth` tests updated; conformance `test-vectors/` extended, never modified. +- Regression gate per increment: full `npm run check`, plus a named Satisfied execution-product run and a BitRoad conformance byte-diff, with the new capability off and on. +- Staging soak before prod; prod capability grants initially to the TORCH tenant only. +- Rollback story per increment = flip the capability off (data remains, behavior reverts). + +## 3. Sequencing summary + +| Order | Increment | Repo | Blocked by | +|---|---|---|---| +| 1 | T0.1 spec v0.2 | TORCH | — | +| 2 | T0.2 schemas | TORCH | T0.1 | +| 3 | T0.3 lock fields | TORCH | T0.2 | +| 4 | T0.4 evidence bundle | TORCH | T0.2 | +| 5 | T0.5 actor identity | TORCH | T0.3 | +| 6 | B0.1 staging tenant + sandbox | BitUnlock (operator) | — | +| 7 | B0.2 license decision | BitUnlock (owner) | — | +| 8 | T1.1 campaign service | TORCH | T0.2, B0.1 | +| 9 | T1.2 fee products + entitlement gating | TORCH | T1.1 | +| 10 | T1.3 **pilot** | both (operator) | T0.4, T1.2 | +| 11 | B2.1 webhooks | BitUnlock | BitUnlock P1 gates; pilot learnings | +| 12 | B2.2 payer/beneficiary | BitUnlock | B2.1 recommended, not required | +| 13 | T2.1–T2.2 Build campaigns | TORCH | T1.3, B2.1 | +| 14 | custody design pass | TORCH doc | — (gates Stage 3) | +| 15 | B3.1 allowance ledger | BitUnlock | B2.1 | +| 16 | B3.2 machine delegation | BitUnlock | B3.1 | +| 17 | T3.1 provider gateway | TORCH | 14, B3.1 | +| 18 | Stage 4 items | both | legal review; proven need | + +The pilot (row 10) is the go/no-go checkpoint: everything after it is justified only by what the pilot proves about demand and maintainer-attention economics.