Merge pull request #211 from engineeredsoftware/v45/gate-8-proof-readback-operational-boundaries

V45 Gate 8: Proof Readback Authority

Author: geraldarthurdavis

BITCODE_SPEC_V45_NOTES.md

@@ -548,6 +548,76 @@ entitlement, explicit non-final language for preview/quote/payment
 observation, authoritative readback for final settlement and rights transfer,
 and repository delivery visibility only for the entitled Reader boundary.
 
+## V45 protocol atom 7: proof readback and operational authority
+
+Audit classification: V44 establishes generated specification proof,
+ledgerized journaling, telemetry, database/storage synchronization, workflow
+checks, and source-safe repair posture. The remaining gap is evidence
+authority: which operational artifacts can advance protocol state, which are
+only observability, and what happens when proof, ledger, database, storage,
+telemetry, provider, or delivery evidence disagrees.
+
+Protocol-law statement:
+
+Bitcode state advances only by proof-backed readback. No UI row, conversation
+message, streamed telemetry item, route response, external provider event, or
+workflow log can alone advance AssetPack lifecycle, BTD rights, BTC settlement,
+source unlock, delivery, or contributor compensation. The advancing artifact
+must be paired with the required proof root and read back from the appropriate
+ledger, database, storage, wallet, provider, or repository boundary.
+
+Canonical evidence authority is:
+
+| Evidence class | Protocol authority | Limit |
+| --- | --- | --- |
+| canonical specification and generated proof appendix | defines protocol law, required proof families, and promotion-grade validation posture | not a live transaction, wallet, source, or delivery receipt |
+| execution/workflow receipt | proves a pipeline, PTRR agent, tool, route, workflow, or validation step ran with typed inputs/outputs and status | not economic finality and not source entitlement unless joined to settlement and rights readback |
+| ledger journal | records protocol-economic state transitions, BTD/BTC journals, repair states, and auditable event ordering | cannot override Bitcoin finality, protected storage, or repository delivery evidence |
+| database projection | serves queryable application state, interface read models, and reconciliation indexes | cannot be treated as final when it diverges from ledger, storage, wallet, or delivery roots |
+| object storage and protected-source roots | prove content custody, source-safe preview objects, source-bearing withheld pack objects, and delivery payload roots | cannot disclose source without entitlement, rights transfer, and delivery authority |
+| telemetry stream | makes running phases, agents, tools, prompts, outputs, timings, and errors observable | observability only; telemetry is not settlement, rights transfer, or source unlock |
+| wallet/provider receipt | supplies quote, PSBT, broadcast, observation, txid, block/finality, or network evidence | provider observation is not final settlement until reconciled with quote, wallet authority, and finality policy |
+| repository delivery receipt | proves pull request, branch, commit, patch, or delivery artifact reached the entitled repository boundary | not public source permission and not contributor compensation by itself |
+
+Canonical readback requirements are:
+
+| State advancement | Required readback before advancement |
+| --- | --- |
+| Depository admission | depositor approval root, source-safety proof, policy eligibility, protected-source storage root, Depository index root, ledger/database projection |
+| reviewed Need acceptance | Read Request root, Need synthesis receipt, user review/approval root, database read model, telemetry summary root |
+| Finding Fits selection | search receipt, candidate provenance roots, measurement/ranking roots, source-safe Fit set root, depository readback |
+| Need-Fit AssetPack synthesis | selected Fit set root, synthesis execution receipt, source-bearing withheld storage root, source-safe preview root, measurement/BTD posture root |
+| BTC quote issuance | reviewed Need root, selected Fit set root, Need-Fit AssetPack root, BTD volume/range roots, deterministic quote root, wallet/network policy root |
+| BTC payment observation | accepted quote root, wallet authority root, provider observation, txid/network/amount readback, mismatch classification if any |
+| BTC settlement finalization | payment observation, configured finality receipt, quote/payment conservation, ledger/database/storage agreement, repair-free settlement receipt |
+| BTD rights transfer | finalized settlement root, BTD range/rights receipt, entitled Reader boundary, ledger/database readback |
+| source unlock and repository delivery | rights transfer root, protected-source object readback, delivery payload root, repository PR/commit receipt, entitled repository boundary |
+| contributor compensation | finalized settlement root, source-to-shares allocation root, contributor roots, compensation statement, ledger/database reconciliation |
+
+Operational repair law:
+
+- If any required readback is missing, stale, contradictory, or outside the
+  allowed actor/network/source boundary, the state must remain in or return to
+  a source-safe repair state.
+- Repair state may expose failure class, blocker, retry command, proof root
+  identifiers, and operator-safe telemetry, but not unpaid source, secrets,
+  wallet private material, raw provider payloads, raw prompts, or raw model
+  responses.
+- Computation hosts, sandbox executions, workflow runners, browser proofs, and
+  API routes may produce receipts, but they do not own protocol truth. They
+  must write/read through the canonical proof, ledger, database, storage,
+  wallet, and repository boundaries.
+- If evidence classes conflict, Bitcode must prefer the stricter
+  source-safety and economic-finality posture until reconciliation proves the
+  correct state.
+
+Acceptance for this atom: later V45 formal specification and implementation
+work may split the readback tables, but it must preserve proof-backed readback
+as the only state advancement mechanism, telemetry as observability rather
+than authority, Bitcoin finality as payment truth, storage and repository roots
+as delivery truth, database projections as reconciled read models, and
+fail-closed repair for every evidence mismatch.
+
 ## Non-goals during V45 opening
 
 - Do not implement V45 gate behavior before the V45 intent discussion is

package.json

@@ -393,6 +393,7 @@
     "check:v45-gate5": "node scripts/check-v45-gate5-btc-settlement-state-machine.mjs",
     "check:v45-gate6": "node scripts/check-v45-gate6-spec-consolidation-sequencing.mjs",
     "check:v45-gate7": "node scripts/check-v45-gate7-interface-authority-disclosure-boundaries.mjs",
+    "check:v45-gate8": "node scripts/check-v45-gate8-proof-readback-operational-boundaries.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-gate8-proof-readback-operational-boundaries.mjs

@@ -0,0 +1,160 @@
+#!/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-gate8-proof-readback-operational-boundaries.mjs [--skip-branch-check] [--repo-root <path>]',
+      '',
+      'Checks the V45 proof readback and operational authority 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',
+    'BITCODE_SPEC.txt',
+    'package.json',
+    'scripts/check-v45-gate7-interface-authority-disclosure-boundaries.mjs',
+  ]) {
+    assertCheck(failures, exists(root, relativePath), `Missing required V45 Gate 8 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 7: proof readback and operational authority',
+    'The remaining gap is evidence authority',
+    'which operational artifacts can advance protocol state',
+    'Bitcode state advances only by proof-backed readback',
+    'No UI row, conversation message, streamed telemetry item, route response, external provider event, or workflow log can alone advance AssetPack lifecycle',
+    'The advancing artifact must be paired with the required proof root and read back from the appropriate ledger, database, storage, wallet, provider, or repository boundary',
+    'Canonical evidence authority is',
+    'canonical specification and generated proof appendix',
+    'execution/workflow receipt',
+    'ledger journal',
+    'database projection',
+    'object storage and protected-source roots',
+    'telemetry stream',
+    'observability only; telemetry is not settlement, rights transfer, or source unlock',
+    'wallet/provider receipt',
+    'provider observation is not final settlement',
+    'repository delivery receipt',
+    'not public source permission and not contributor compensation by itself',
+    'Canonical readback requirements are',
+    'Depository admission',
+    'reviewed Need acceptance',
+    'Finding Fits selection',
+    'Need-Fit AssetPack synthesis',
+    'BTC quote issuance',
+    'BTC payment observation',
+    'BTC settlement finalization',
+    'BTD rights transfer',
+    'source unlock and repository delivery',
+    'contributor compensation',
+    'Operational repair law',
+    'source-safe repair state',
+    'failure class, blocker, retry command, proof root identifiers, and operator-safe telemetry',
+    'Computation hosts, sandbox executions, workflow runners, browser proofs, and API routes may produce receipts',
+    'they do not own protocol truth',
+    'prefer the stricter source-safety and economic-finality posture',
+    'Acceptance for this atom',
+    'proof-backed readback as the only state advancement mechanism',
+    'telemetry as observability rather than authority',
+    'Bitcoin finality as payment truth',
+    'storage and repository roots as delivery truth',
+    'database projections as reconciled read models',
+    'fail-closed repair for every evidence mismatch',
+  ]) {
+    assertCheck(failures, normalizedNotes.includes(phrase), `V45 Gate 8 notes must include phrase: ${phrase}`);
+  }
+
+  assertCheck(
+    failures,
+    packageJson.includes('"check:v45-gate8": "node scripts/check-v45-gate8-proof-readback-operational-boundaries.mjs"'),
+    'package.json must expose check:v45-gate8.',
+  );
+
+  if (failures.length > 0) {
+    process.stderr.write('V45 Gate 8 proof readback and operational authority check failed:\n');
+    for (const failure of failures) process.stderr.write(`- ${failure}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write('V45 Gate 8 proof readback and operational authority check passed.\n');
+}
+
+try {
+  main();
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${detail}\n`);
+  process.exitCode = 1;
+}