feat(bsv): implement the upto payment scheme

[linzhm]

Description

Depends on #4. This is the TypeScript implementation preview for the proposed BSV upto specification, submitted to the BSV fork only. Please review the specification first; this Draft is not a simultaneous request for implementation approval.

Adds upto alongside the existing @x402/bsv exact scheme: the payer signs a reusable maximum authorization, the Resource Server supplies the actual amount through existing SettlementOverrides, and the recipient constructs and verifies the terminal transaction. Complete terminal Atomic BEEF returns through the existing settlement response so the payer can validate and internalize its outputs.

The usual case reserves fee headroom (E > M). Stream compatibility means applications can form increasing, fully signed conflicting candidates using unchanged payer cap signatures; only one selected terminal is settled. This adds no streaming scheme, endpoint, or extra x402 round trip.

Dependency and temporary base

Both this PR and #4 use feat/bsv-exact-scheme at df5fdb3c solely to show focused diffs. This PR contains no specification file; the dependency is explicit, not a Git-enforced stack.

Do not merge either PR into this branch while it carries the active upstream exact PR (number 2890). A BSV maintainer must first establish a separate integration base, or use an appropriate base after exact lands. Retarget and recheck the diffs, approve/merge #4 first, then reconcile this implementation with the approved specification. Opening this fork Draft does not claim completion of the upstream spec-first process.

Scope and review order

60 files, +11,911/−12: BSV implementation, unit/integration tests, README, changeset, and TypeScript E2E catalog/role registration. No core, HTTP, MCP, legacy, generic specification, existing exact source, or TypeScript workspace lockfile changes. E2E MCP exclusion files prevent unsupported BSV combinations; they do not add MCP support.

Within typescript/packages/mechanisms/bsv/, review:

1. src/upto/types.ts, internal/authorization.ts, and internal/source.ts: signed fields, BEEF validation, and joint-source ancestry conflicts.
2. internal/transaction.ts, internal/terminal.ts, and internal/outputs.ts: reusable cap signatures, recipient signatures, owner net amounts, fee/refund arithmetic, and full terminal validation.
3. server/, facilitator/, and client/: admission/amount binding, terminal selection before wallet effects, and payer receipt validation. Fresh verification is not response recovery; repeated facilitator settlement has the narrower replay contract in docs(specs): define the upto scheme for BSV #4.
4. test/integrations/ and e2e/BSV.md: opt-in dual-wallet and authenticated three-role setup.

The enforcement split remains subject to #4's review: cap signatures mechanically limit total exposure E, not service maximum M; control signatures require the recipient's completion authority but do not covenant allocation rules; cap signatures do not expire cryptographically. Persistent coordination and recipient-controlled settlement authentication remain deployment requirements, not guarantees supplied by the transport.

Tests

Validation recorded on 2026-09-05 against the unchanged uploaded file hashes:

• TypeScript workspace format/lint checks passed. pnpm test --force passed on Node 22.23.2 and 24.19.0: 57/57 tasks each, no cached tasks.
• BSV unit/HTTP tests: 304/304, including 121 existing exact tests; full signed candidates, multi-I/O, ancestry-conflict rejection, and terminal delivery covered.
• All seven package entry points passed CJS/ESM loading and declaration checks. Existing export mappings are unchanged.
• Offline E2E harness checks: 4/4. Server/facilitator E2E type checks pass. Auxiliary type checks still report three existing BSV exact-test errors and two existing E2E client v1 network-literal errors; these checks are not claimed green.
• Funded dual-wallet integration, live catalog E2E, and real remote authentication/miner observation: NOT RUN. Disabled integration collection is a skip, not live evidence.

Checklist

• docs(specs): define the upto scheme for BSV #4 approved/merged and implementation reconciled with it
• Safe integration base established and final diff rechecked
• Human author verification of payment/signature logic completed
• Local TypeScript workspace checks passed
• Contribution commit signed and GitHub verification confirmed valid
• @x402/bsv changeset included
• Funded dual-wallet and live catalog E2E passed

AI assistance

Significant AI assistance was used for implementation, tests, and review. This remains Draft; human verification and the unresolved specification/live-validation gates are not represented as complete. No reviewers or upstream changes are requested by opening this preview.