Merge pull request #208 from engineeredsoftware/v45/gate-5-btc-settlement-state-machine

V45 Gate 5: BTC Settlement State Machine

Author: geraldarthurdavis

BITCODE_SPEC_V45_NOTES.md

@@ -335,6 +335,90 @@ deterministic fixed-point measurement weighting, measuremint/range conservation,
 zero-cell tail posture, BTC-before-rights law, and source-to-shares as
 post-settlement contributor allocation rather than BTD size.
 
+## V45 protocol atom 4: BTC settlement state machine
+
+Audit classification: V44 correctly names estimates, quotes, observed payment,
+final settlement, contributor allocation, delivery, and repair as distinct
+economic labels. The implementation already separates BTC fee quotes, PSBT
+handoff, broadcast observation, finality receipts, settlement unlock,
+source-to-shares, and compensation statements. V45 must make BTC settlement
+law explicit so that a quote, a broadcast transaction, an observed payment,
+confirmed finality, BTD rights transfer, source delivery, refund/escalation,
+and contributor compensation cannot be collapsed by an interface, pipeline,
+or operator.
+
+Protocol-law statement:
+
+BTC is Bitcode settlement money and payment truth. A BTC quote is a
+source-safe procurement offer bound to a reviewed Need, selected Fit set,
+synthesized Need-Fit AssetPack, BTD scalar-volume/range, deterministic
+share-to-fee policy, wallet authority, network, expiry, and proof roots. A BTC
+payment is not final merely because a transaction is prepared, signed,
+broadcast, visible in mempool, or observed by a provider. Source unlock,
+rights-bearing BTD transfer, delivery, and contributor compensation require
+confirmed BTC finality, quote/payment conservation, ledger/database/storage
+readback, and repair-free settlement receipts.
+
+The canonical BTC settlement state machine is:
+
+| State | Meaning | Required inputs | Output posture |
+| --- | --- | --- | --- |
+| `btc-not-quoteable` | No reviewed Need-Fit quote can exist yet. | reviewed Need missing, selected Fit set missing, BTD quote posture missing, wallet authority missing, or policy blocker | no BTC quote claim |
+| `btc-quote-issued` | Deterministic sats quote is created for the Reader. | quote root, BTD scalar-volume/range roots, deterministic share-to-fee policy root, network, expiry, budget policy | source-safe offer only; no payment |
+| `btc-quote-accepted` | Reader and organization authority accept the quote before expiry. | accepted quote root, buyer authorization root, wallet authority root, budget approval root when required | PSBT preparation admitted |
+| `btc-quote-inactive` | Quote is expired, superseded, failed, revoked, or mismatched. | inactive quote root and reason | payment against this quote cannot unlock rights |
+| `btc-wallet-ready` | Reader wallet can sign without server custody. | wallet signer session, network match, PSBT signing capability, no-server-custody proof | PSBT handoff may proceed |
+| `btc-psbt-prepared` | Settlement transaction is prepared but unsigned. | accepted quote, wallet-ready proof, terminal journal root, PSBT root | no payment observation |
+| `btc-psbt-signed` | Reader has signed the transaction. | prepared PSBT root, wallet authorization proof, signed PSBT root | broadcast admitted; no finality |
+| `btc-broadcast-submitted` | Signed transaction has been submitted to the Bitcoin network. | signed transaction root, txid, network root, provider observation root | observed payment pending finality |
+| `btc-payment-observed` | Debit, credit, txid, amount, payer, payee, and network are observed. | payment observation root, expected sats, observed debit sats, observed credit sats, txid | source remains locked; finality pending |
+| `btc-payment-mismatch-repair-required` | Observed payment does not conserve the accepted quote or violates wallet/network policy. | mismatch proof root, repair blocker root | repair, replacement, refund, or escalation only |
+| `btc-finality-confirmed` | Bitcoin finality satisfies the configured confirmation/finality policy. | finality receipt, confirmations, txid, block/reorg readback, quote/payment conservation root | settlement can authorize BTD rights transfer |
+| `btc-replaced-reorged-or-failed` | Transaction was replaced, reorged out, failed, or became non-final. | replacement, reorg, or failure root | source remains locked; repair or refund/escalation required |
+| `btc-settlement-finalized` | Quote, payment, finality, ledger, database, object storage, and source-safe readback agree. | finality root, ledger/database/storage reconciliation root, terminal journal root, settlement unlock root | BTD rights transfer and delivery unlock may proceed |
+| `btc-contributor-compensation-routable` | Final settlement is available to source-to-shares allocation and contributor statements. | finalized settlement root, BTD range slices, source-to-shares proof, contributor roots | compensation statements and treasury routes may be issued |
+| `btc-refund-or-escalation-required` | A payment or quote cannot be accepted as final settlement, and value movement or operator review is required. | refund/escalation case root, payment evidence, policy reason | no rights, no source unlock, no contributor compensation |
+| `btc-settlement-repair-required` | Any quote, wallet, PSBT, broadcast, observation, finality, readback, unlock, or compensation proof is missing or stale. | repair blocker root | fail-closed repair only |
+
+Settlement law:
+
+- A quote is not an estimate. It must be denominated in BTC sats, bind the
+  BTD scalar-volume/range and deterministic share-to-fee policy, name its
+  network and expiry, and carry a source-safe quote root.
+- A quote must be accepted before PSBT preparation. Expired, superseded,
+  failed, revoked, wrong-network, wrong-wallet, or mismatched quotes cannot
+  unlock rights even if a payment is later observed.
+- Bitcode must never take server custody of wallet private material. The
+  Reader signs through a wallet session that proves network, capability,
+  authorization, and no-server-custody posture.
+- Prepared, signed, broadcast, and observed states are not final settlement.
+  They cannot transfer BTD rights, unlock source, deliver a pull request, or
+  allocate contributor compensation.
+- Payment observation must conserve the accepted quote: expected sats,
+  observed debit sats, observed credit sats, payer, payee, network, txid, and
+  quote root must reconcile. Drift enters repair, refund, or escalation.
+- BTC finality requires the configured confirmation/finality policy and must
+  fail closed on replacement, reorg, failure, stale provider readback, or
+  missing ledger/database/object-storage reconciliation.
+- Refund or escalation is a repair path, not a successful purchase path. It
+  does not transfer BTD rights, disclose source, satisfy contributor
+  compensation, or convert an inactive quote into final settlement.
+- Contributor compensation is routable only after final settlement and must be
+  derived from source-to-shares, BTD range slices, contributor roots, and the
+  settled BTC payment. Estimated depositor earning ranges remain non-final.
+- Product surfaces may show quote, observed payment, finality, repair,
+  refund/escalation, and compensation states, but they must not expose private
+  settlement payloads, wallet private material, unpaid AssetPack source, raw
+  protected source, raw prompts, or raw provider responses.
+
+Acceptance for this atom: later V45 specification may refine confirmation
+thresholds, wallet-provider adapters, refund mechanisms, and compensation
+route mechanics, but it must preserve BTC as settlement money, quote as
+source-safe deterministic procurement offer, observed payment as non-final,
+confirmed finality as prerequisite to BTD rights transfer, source unlock only
+after settlement readback, refund/escalation as fail-closed repair, and
+contributor compensation as post-finality source-to-shares allocation.
+
 ## Non-goals during V45 opening
 
 - Do not implement V45 gate behavior before the V45 intent discussion is

package.json

@@ -390,6 +390,7 @@
     "check:v45-gate2": "node scripts/check-v45-gate2-knowledge-commoditization-law.mjs",
     "check:v45-gate3": "node scripts/check-v45-gate3-assetpack-lifecycle-state-machine.mjs",
     "check:v45-gate4": "node scripts/check-v45-gate4-btd-scalar-volume-state-machine.mjs",
+    "check:v45-gate5": "node scripts/check-v45-gate5-btc-settlement-state-machine.mjs",
     "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs",
     "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check",
     "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs",

scripts/check-v45-gate5-btc-settlement-state-machine.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const defaultRepoRoot = path.resolve(__dirname, '..');
+
+function read(root, relativePath) {
+  return readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+function exists(root, relativePath) {
+  return existsSync(path.join(root, relativePath));
+}
+
+function git(root, args) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+function assertCheck(failures, condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function normalize(content) {
+  return content.replace(/\s+/gu, ' ').trim();
+}
+
+function parseArgs(argv) {
+  const args = { repoRoot: defaultRepoRoot, skipBranchCheck: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--repo-root') args.repoRoot = path.resolve(argv[++index]);
+    else if (arg === '--skip-branch-check') args.skipBranchCheck = true;
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else throw new Error(`Unknown argument ${arg}`);
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: node scripts/check-v45-gate5-btc-settlement-state-machine.mjs [--skip-branch-check] [--repo-root <path>]',
+      '',
+      'Checks the V45 BTC settlement state machine specification atom.',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const root = args.repoRoot;
+  const failures = [];
+  const pointer = read(root, 'BITCODE_SPEC.txt').trim();
+
+  assertCheck(failures, pointer === 'V44', `BITCODE_SPEC.txt must remain V44 during V45 atom work. Observed ${pointer || 'empty'}.`);
+
+  if (!args.skipBranchCheck) {
+    const branch = git(root, ['branch', '--show-current']);
+    assertCheck(
+      failures,
+      branch === 'version/v45' || /^v45\/gate-\d+-[a-z0-9][a-z0-9-]*$/u.test(branch),
+      `V45 work must occur on version/v45 or v45/gate-N-* branches. Observed ${branch || 'detached HEAD'}.`,
+    );
+  }
+
+  for (const relativePath of [
+    'BITCODE_SPEC_V45_NOTES.md',
+    'BITCODE_SPEC_V44.md',
+    'packages/btd/src/bitcoin-fees.ts',
+    'packages/btd/src/btc-fee-operation.ts',
+    'packages/btd/src/settlement.ts',
+    'packages/pipelines/asset-pack/src/asset-pack-settlement-rights-delivery.ts',
+    'packages/pipelines/asset-pack/src/btd-btc-compensation-statements.ts',
+    'package.json',
+    'scripts/check-v45-gate4-btd-scalar-volume-state-machine.mjs',
+  ]) {
+    assertCheck(failures, exists(root, relativePath), `Missing required V45 Gate 5 file: ${relativePath}`);
+  }
+
+  const notes = read(root, 'BITCODE_SPEC_V45_NOTES.md');
+  const normalizedNotes = normalize(notes);
+  const packageJson = read(root, 'package.json');
+
+  for (const phrase of [
+    'V45 protocol atom 4: BTC settlement state machine',
+    'V44 correctly names estimates, quotes, observed payment, final settlement, contributor allocation, delivery, and repair',
+    'separates BTC fee quotes, PSBT handoff, broadcast observation, finality receipts, settlement unlock, source-to-shares, and compensation statements',
+    'BTC is Bitcode settlement money and payment truth',
+    'A BTC quote is a source-safe procurement offer',
+    'bound to a reviewed Need, selected Fit set, synthesized Need-Fit AssetPack',
+    'BTD scalar-volume/range',
+    'A BTC payment is not final merely because a transaction is prepared, signed, broadcast, visible in mempool, or observed by a provider',
+    'confirmed BTC finality, quote/payment conservation, ledger/database/storage readback, and repair-free settlement receipts',
+    'btc-not-quoteable',
+    'btc-quote-issued',
+    'btc-quote-accepted',
+    'btc-quote-inactive',
+    'btc-wallet-ready',
+    'btc-psbt-prepared',
+    'btc-psbt-signed',
+    'btc-broadcast-submitted',
+    'btc-payment-observed',
+    'btc-payment-mismatch-repair-required',
+    'btc-finality-confirmed',
+    'btc-replaced-reorged-or-failed',
+    'btc-settlement-finalized',
+    'btc-contributor-compensation-routable',
+    'btc-refund-or-escalation-required',
+    'btc-settlement-repair-required',
+    'wrong-network, wrong-wallet, or mismatched quotes cannot unlock rights',
+    'never take server custody of wallet private material',
+    'Prepared, signed, broadcast, and observed states are not final settlement',
+    'Payment observation must conserve the accepted quote',
+    'BTC finality requires the configured confirmation/finality policy',
+    'Refund or escalation is a repair path, not a successful purchase path',
+    'Contributor compensation is routable only after final settlement',
+    'Estimated depositor earning ranges remain non-final',
+    'must not expose private settlement payloads, wallet private material, unpaid AssetPack source',
+    'Acceptance for this atom',
+    'BTC as settlement money',
+    'quote as source-safe deterministic procurement offer',
+    'observed payment as non-final',
+    'confirmed finality as prerequisite to BTD rights transfer',
+    'source unlock only after settlement readback',
+    'refund/escalation as fail-closed repair',
+    'contributor compensation as post-finality source-to-shares allocation',
+  ]) {
+    assertCheck(failures, normalizedNotes.includes(phrase), `V45 Gate 5 notes must include phrase: ${phrase}`);
+  }
+
+  assertCheck(
+    failures,
+    packageJson.includes('"check:v45-gate5": "node scripts/check-v45-gate5-btc-settlement-state-machine.mjs"'),
+    'package.json must expose check:v45-gate5.',
+  );
+
+  if (failures.length > 0) {
+    process.stderr.write('V45 Gate 5 BTC settlement state machine check failed:\n');
+    for (const failure of failures) process.stderr.write(`- ${failure}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write('V45 Gate 5 BTC settlement state machine check passed.\n');
+}
+
+try {
+  main();
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${detail}\n`);
+  process.exitCode = 1;
+}