docs(v2): add TORCH x BitUnlock incremental development plan

Cross-repo staged plan: Stage 0 foundations (schemas, evidence bundles,
actor identity, staging tenant, license decision), Stage 1 pilot with
zero BitUnlock code changes, Stage 2 webhooks + payer/beneficiary,
Stage 3 allowance-ledger compute leases + machine delegation, Stage 4
multi-payer funding and protocol-level items. Every BitUnlock change is
additive, capability-gated, and maps to its existing future roadmap;
the pilot is the go/no-go checkpoint.

Co-Authored-By: Claude Fable 5 <[email protected]>

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.