From a6e37bf76b692ada1ef09886195d1addca6d3e0e Mon Sep 17 00:00:00 2001 From: Garrett Maring Date: Wed, 20 May 2026 12:47:41 -0300 Subject: [PATCH] Open V29 objectives and gate plan Creates the V29 draft SPEC, DELTA, NOTES, and PARITY family over the promoted V28 canon while preserving BITCODE_SPEC.txt -> V28. Retargets gate/canon quality posture to V28 active and V29 draft, adds check:v29-gate1, and keeps spec-quality/pre-commit expectations aligned with promoted V28 canonical inputs. --- .github/workflows/bitcode-canon-quality.yml | 17 +- .github/workflows/bitcode-gate-quality.yml | 17 +- BITCODE_SPEC_V29.md | 633 ++++++++++++++++++ BITCODE_SPEC_V29_DELTA.md | 118 ++++ BITCODE_SPEC_V29_NOTES.md | 116 ++-- BITCODE_SPEC_V29_PARITY_MATRIX.md | 94 +++ README.md | 42 +- package.json | 1 + .../test/v21-specifying.test.js | 2 +- scripts/check-bitcode-pre-commit.mjs | 4 +- .../check-v29-gate1-objectives-and-gating.mjs | 177 +++++ 11 files changed, 1138 insertions(+), 83 deletions(-) create mode 100644 BITCODE_SPEC_V29.md create mode 100644 BITCODE_SPEC_V29_DELTA.md create mode 100644 BITCODE_SPEC_V29_PARITY_MATRIX.md create mode 100644 scripts/check-v29-gate1-objectives-and-gating.mjs diff --git a/.github/workflows/bitcode-canon-quality.yml b/.github/workflows/bitcode-canon-quality.yml index 920e72e6e..f8e889e6c 100644 --- a/.github/workflows/bitcode-canon-quality.yml +++ b/.github/workflows/bitcode-canon-quality.yml @@ -20,11 +20,12 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Validate active canon and V28 draft posture + - name: Validate active canon and V29 draft posture run: | - node scripts/check-bitcode-canonical-inputs.mjs --current-target V27 - node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V27 --draft-target V28 - node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27 + node scripts/check-bitcode-canonical-inputs.mjs --current-target V28 + node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29 + node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28 + node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28 bitcode-demonstration-mvp: name: Bitcode Demonstration MVP @@ -53,13 +54,13 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Run V28 strict draft conformance for spec-title changes + - name: Run V29 strict draft conformance for spec-title changes run: | case "$SPEC_TITLE" in - spec:\ V28*|spec:\ v28*) - node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27 + spec:\ V29*|spec:\ v29*) + node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28 ;; *) - echo "Skipping strict spec-title conformance; title is not a V28 spec change." + echo "Skipping strict spec-title conformance; title is not a V29 spec change." ;; esac diff --git a/.github/workflows/bitcode-gate-quality.yml b/.github/workflows/bitcode-gate-quality.yml index 992ad80fd..f5c2d03d7 100644 --- a/.github/workflows/bitcode-gate-quality.yml +++ b/.github/workflows/bitcode-gate-quality.yml @@ -40,17 +40,12 @@ jobs: - name: Validate draft canon posture run: | - test "$(cat BITCODE_SPEC.txt)" = "V27" - node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27 - node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V27 --draft-target V28 - node scripts/check-bitcode-canonical-inputs.mjs --current-target V27 - node scripts/check-v28-metadevelopment-readiness.mjs --skip-branch-check - node scripts/check-v28-gate9-depository-evidence.mjs - node scripts/check-v28-gate10-read-need-comprehension.mjs - node scripts/check-v28-gate11-read-fits-finding-preview.mjs - node scripts/check-v28-gate12-settlement-rights-delivery.mjs - node scripts/check-v28-gate13-product-closure-promotion-readiness.mjs - node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run + test "$(cat BITCODE_SPEC.txt)" = "V28" + node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28 + node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28 + node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29 + node scripts/check-bitcode-canonical-inputs.mjs --current-target V28 + node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check - name: Validate source casing and imports run: | diff --git a/BITCODE_SPEC_V29.md b/BITCODE_SPEC_V29.md new file mode 100644 index 000000000..f7f02f795 --- /dev/null +++ b/BITCODE_SPEC_V29.md @@ -0,0 +1,633 @@ +# Bitcode Spec V29 + +## Status + +- Version: `V29` +- V29 state: draft target opened; V29 owns deeper Terminal transaction operation after V28 promotion and must not alter the active V28 canon pointer until promotion +- Current canonical/latest target: `V28` +- Prior canonical anchor: `BITCODE_SPEC_V28.md` +- Prior generated proof appendix: `BITCODE_SPEC_V28_PROVEN.md` +- Generated structured artifact inventory: draft `.bitcode/v29-spec-family-report.json`, draft `.bitcode/v29-canonical-input-report.json`, future `.bitcode/v29-canon-posture-drift-report.json`, V29 gate-quality evidence, and no `BITCODE_SPEC_V29_PROVEN.md` until promotion +- Source parity state: V29 Gate 1 opens the draft specification and quality gates; product-source parity begins from V28 Terminal, Reading, AssetPack, settlement, ledger, and workflow implementation truth +- State: draft target opened +- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V28` +- Draft target source: `protocol-demonstration/src/canon-posture.js` declares `DRAFT_TARGET_VERSION = 'V29'` +- Primary scope: deeper Terminal workflows and transaction operation over the promoted V28 commercial Reading, Finding Fits, AssetPack, settlement, delivery, and promotion baseline +- Prior active canon: `BITCODE_SPEC_V28.md` +- Notes companion: `BITCODE_SPEC_V29_NOTES.md` +- Delta companion: `BITCODE_SPEC_V29_DELTA.md` +- Parity companion: `BITCODE_SPEC_V29_PARITY_MATRIX.md` +- Generated proof appendix: none until V29 promotion +- Scope: V29 canonical system specification for Terminal transaction depth, operator recovery, wallet/BTC settlement operation, AssetPack disclosure and rights review, ledger/database reconciliation, organization permission decisions, and promotion-ready workflow proof over V28 + +V29 begins from promoted V28. +V28 made Depositing, Read Request, Read-Need Comprehension, Finding Fits, AssetPack synthesis, source-safe preview, settlement posture, delivery, and promotion governance coherent enough for canon. +V29 deepens the Terminal as the primary operator surface for that system. + +## Version executive summary + +V29 is a Terminal-depth version. +It does not create a new protocol supply law, a new `$BTD` denomination, or a versioned implementation route family. +It turns V28's promoted commercial Reading system into a more complete enterprise operator experience: + +- transaction state is navigable, recoverable, and explainable; +- wallet, signer session, BTC fee, PSBT, broadcast, replacement, reorg, blocked-readiness, and recovery states are ordinary Terminal states; +- Read Request, synthesized Need, Finding Fits, source-safe AssetPack preview, settlement, rights transfer, and pull-request delivery are presented as one coherent journey; +- proof roots, telemetry, prompt/inference/tool traces, ledger state, database projection, metaphysical state, reconciliation drift, and repair actions are visible at controlled levels of detail; +- organization holdings, roles, read-license usage, and registry-derived permission decisions are first-class Terminal facts; +- V28's demonstration-origin commercial internals continue being formalized into packages and narrow APIs without importing demonstration runtime code. + +V29 closes only when the Terminal can be used as a commercial transaction cockpit for the V28 Read/Fit/AssetPack system and when every V29 gate is specified, implemented, tested, documented, and promotion-ready. + +## Canonical Bitcode executive summary + +Bitcode is a protocol and commercial implementation for measuring technical knowledge, exchanging source-bearing AssetPacks, and settling rights through proof-backed Reading. +The active V28 canon remains: + +- a Deposit supplies source material to the Bitcode depository; +- a Read Request is synthesized into a reviewed Need before any Finding Fits run; +- `ReadNeedComprehensionSynthesis` uses PTRR agents and ThricifiedGenerations to synthesize a precise Need; +- `ReadFitsFindingSynthesis` searches the depository for all threshold-passing fit deposits, uses those fits as synthesis context, and produces a source-safe AssetPack preview; +- protected AssetPack source remains hidden before settlement; +- BTC is the fee asset; +- BTD range/read-license/right transfer and delivery are ledgerized; +- paid settlement unlocks the full AssetPack as a pull request against the Reader's repository. + +V29 does not redefine those laws. +V29 makes their operation deeper, more recoverable, more legible, and more completely validated in Terminal. + +## V29 source-of-truth hierarchy + +The V29 source-of-truth hierarchy is: + +1. `BITCODE_SPEC.txt`, which remains `V28` until V29 promotion. +2. `BITCODE_SPEC_V29.md` during V29 drafting. +3. `BITCODE_SPEC_V29_NOTES.md`. +4. `BITCODE_SPEC_V29_DELTA.md`. +5. `BITCODE_SPEC_V29_PARITY_MATRIX.md`. +6. generated V29 artifacts under `.bitcode/` when produced. +7. `BITCODE_SPEC_V29_PROVEN.md` only after promotion. +8. source implementation, tests, internal docs, public docs, and QA evidence that realize this file family. + +Older specifications are provenance only. +They must not be used as hidden current-system law. + +## V29 full-system, re-implementation, and audit rule + +V29 must be re-implementable and auditable from its specification family without reading conversation history. +Every Terminal state, pipeline admission boundary, proof root, ledger/database projection, disclosure rule, fee/right transfer state, and promotion gate must identify: + +- canonical object; +- required inputs; +- outputs and stored artifacts; +- deterministic, inferred, external, or policy-derived fields; +- proof obligations; +- failure and repair posture; +- implementation and validation surfaces. + +## V29 totality and precision enforcement rule + +V29 fails closed when a Terminal feature only displays a happy-path summary while hiding missing proof, ledger, database, wallet, or delivery state. +Each gate must preserve exact abstraction names: + +- executions are the base runtime records; +- pipelines compose phase-wise behavior; +- agents are PTRR agents; +- PTRR steps are the four formal agent steps; +- sub-steps are ThricifiedGenerations; +- pipeline inference points are ThricifiedGenerations; +- tools are registry-backed tool calls; +- prompts are prompt-part and prompt-template registry compositions. + +No source identifier may introduce a versioned route, gate, or work-in-progress name unless explicitly accepted as a bounded compatibility artifact. + +## V29 system goals, non-goals, and design principles + +Goals: + +- make Terminal the complete enterprise operator path for Reading transactions; +- deepen recovery, evidence, prompt/telemetry visibility, and ledger/database synchronization; +- preserve the V28 five-step Reading UX while adding transaction detail without overwhelming the default operator path; +- make BTC settlement and BTD rights transfer readable and repairable; +- make organization permissions and license usage registry-derived; +- keep local and staging validation realistic enough to reveal operational defects before promotion. + +Non-goals: + +- no Exchange market-depth implementation; +- no website Conversations product-depth implementation; +- no new `$BTD` supply law; +- no value-bearing mainnet approval; +- no broad provider completion beyond Terminal-owned hooks; +- no direct runtime dependency on `protocol-demonstration/`. + +Design principles: + +- low-detail by default, complete detail on expansion; +- no protected source leakage before settlement; +- typed events over raw JSON as the operator contract; +- ledger truth and database projection remain synchronized but distinct; +- failures must name the blocking primitive and the repair path. + +## V29 system architecture and layer boundaries + +V29 preserves the V28 architecture: + +- `packages/*` own protocol, BTD, pipeline, agent, prompt, tool, storage, and interface primitives; +- `packages/pipelines/asset-pack` owns Reading pipelines and AssetPack synthesis logic; +- `packages/pipeline-hosts` owns Vercel Sandbox and host-lane execution harnesses; +- `packages/btd` owns BTD range, measuremint, BTC fee, wallet, access, ledger, reconciliation, and terminal-journal primitives; +- `uapi` owns commercial API routes and Terminal UI; +- `protocol-demonstration` remains a standalone minimal reference and proof witness outside the workspace import graph. + +Layer boundaries: + +- Terminal may call commercial APIs and packages; it must not import demonstration runtime code. +- API routes may orchestrate pipelines; pipeline packages must remain reusable outside a single route. +- Ledger records and journals are source-of-truth for settlement/finality; Supabase/PostgreSQL projections must not contradict them. +- Source-safe previews may expose measurements, roots, score bands, policy ids, fee quote roots, and settlement posture; they may not expose protected source before payment. + +## V29 canonical domain model + +The V29 domain model extends V28 operationally: + +- `Deposit`: source supply with repository, branch, commit, depositor boundary, depository asset id, measurement, embedding document, and proof roots. +- `ReadRequest`: Reader-authored request with repository target, constraints, non-goals, desired artifact kinds, and context. +- `ReadNeed`: reviewed synthesis of the request, including requirements, exclusions, proof expectations, pricing vector, feedback lineage, and acceptance root. +- `FindingFitsResult`: all threshold-passing fit deposits, search roots, ranking roots, blockers, no-worthy-fit posture, and selected synthesis context. +- `AssetPackPreview`: source-safe measurements, quality score, disclosure policy, access policy, fee quote, range projection, and protected-source lock. +- `SettlementUnlock`: BTC fee proof, BTD range/read-license/right transfer, paid disclosure decision, delivery admission, and reconciliation state. +- `TerminalTransaction`: URL-addressable activity combining execution, pipeline, agent, tool, prompt, ledger, database, delivery, and proof state. + +## V29 whole Bitcode operator chain + +The V29 Terminal operator chain is: + +```text +Readiness + -> Deposit or select deposited source + -> Request Read + -> Synthesize and review Need + -> Request Finding Fits + -> Review source-safe AssetPack preview + -> Prepare BTC fee and settlement + -> Wallet signs or blocks explicitly + -> Ledger/database/right-transfer reconciliation + -> Paid delivery as pull request + -> Terminal journal, proof, and repair follow-through +``` + +Each transition must be observable as an execution, pipeline, PTRR agent, PTRR step, ThricifiedGeneration, tool call, ledger journal row, database projection, or repair receipt where applicable. + +## V29 canonical subsystem surfaces + +### Depositing and asset supply + +- Current canonical objects and emitted artifacts: Deposit, depository asset, repository snapshot, source measurement, embedding document, source proof root, ownership boundary, deposit journal row. +- Current algorithms and derivation rules: repository inventory binds source branch/commit; deposit admission creates searchable lexical/vector evidence; depositor ownership stays separate from later Reader rights. +- Current invariants and fail-closed conditions: invalid deposit, missing repository commit, unavailable source material, or absent depositor boundary blocks Finding Fits. +- Current proof obligations: source measurement root, embedding policy root, repository snapshot root, and depositor boundary proof. +- Current source-bearing implementation basis: `uapi/app/terminal`, commercial API routes, `packages/pipelines/asset-pack`, `packages/btd`, Supabase migrations, and readback scripts. +- Current validating commands and parity basis: V29 gate checks, V28 readback verifier until replaced, package tests, UAPI tests, and staging-testnet SQL/readback evidence. +- Current accepted boundaries: broader provider families remain staged unless Terminal requires a narrow GitHub-adjacent hook. + +### Reading and prompt/inference ownership + +- Current canonical objects and emitted artifacts: ReadRequest, ReadNeed, prompt registry ids, PTRR agent ids, PTRR step ids, ThricifiedGeneration ids, raw output posture, parsed typed output, and acceptance root. +- Current algorithms and derivation rules: the Reader's request is not admitted to Finding Fits until `ReadNeedComprehensionSynthesis` synthesizes a Need and the user accepts it. +- Current invariants and fail-closed conditions: prompt contract incompleteness, parsed-envelope inadmissibility, missing Need review, or feedback lineage mismatch blocks Finding Fits. +- Current proof obligations: prompt template, interpolated prompt, input context, output schema, raw response posture, parsed output, usage, model identity, and acceptance root. +- Current source-bearing implementation basis: Reading pipeline contracts, bounded structured inference, read-review API route, Terminal Read UX, and tests. +- Current validating commands and parity basis: pipeline contract tests, route tests, prompt rendering/audit checks, local live OpenAI validation, and V29 gate checks. +- Current accepted boundaries: full-profile async push completion can deepen in V29 gates but cannot bypass source-safe preview or settlement boundaries. + +### Fit, recall, ranking, and verification + +- Current canonical objects and emitted artifacts: FindingFits query root, lexical search result, vector search result, fit deposit list, candidate score, ranking root, blocker list, and verification decision. +- Current algorithms and derivation rules: `ReadFitsFindingSynthesis` discovery searches the depository for all fits above threshold, ranks them, and uses fit deposits as contextual knowledge for AssetPack synthesis. +- Current invariants and fail-closed conditions: no-survivor asset pack, no-worthy-fit, mock/frontier source leakage, missing embedding policy, or missing candidate source root blocks implementation. +- Current proof obligations: search provider/tool ids, vector embedding policy, threshold, source roots, ranking roots, and selected-context root. +- Current source-bearing implementation basis: depository search tools, embedding configuration, AssetPack pipeline agents, and pipeline host harnesses. +- Current validating commands and parity basis: depository search tests, embedding tests, tool telemetry tests, staging readback, and Terminal stream tests. +- Current accepted boundaries: non-GitHub deposit providers are future unless required for a specific Terminal-owned repair. + +### Selection and materialization + +- Current canonical objects and emitted artifacts: AssetPack synthesis output, source-safe preview, delivery plan, branch artifact, pull-request delivery, branch artifacts and assetPackEvidence. +- Current algorithms and derivation rules: implementation uses discovered fit deposits as context; protected source is written only behind the paid unlock boundary; delivery materializes as a pull request after settlement. +- Current invariants and fail-closed conditions: unpaid preview cannot expose protected source; delivery cannot proceed without settlement unlock; branch identity must match ReadRequest repository context. +- Current proof obligations: synthesis prompt/output, preview policy, fee quote root, settlement unlock, delivery branch, PR id/url, and assetPackEvidence. +- Current source-bearing implementation basis: AssetPack pipeline postprocess, GitHub/VCS routes, pipeline host runner, Terminal delivery readback, and BTD package primitives. +- Current validating commands and parity basis: synthesis tests, source-leakage tests, route tests, PR delivery mocks/live checks, and V29 gate checks. +- Current accepted boundaries: full mainnet value delivery remains approval-gated. + +### Identity, authorization, and sensitive flow + +- Current canonical objects and emitted artifacts: wallet identity, signer session, GitHub connection, organization role, read-license, access-policy decision, permission proof. +- Current algorithms and derivation rules: registry-derived permissions decide whether an operator can read, pay, unlock, deliver, repair, or administer a transaction. +- Current invariants and fail-closed conditions: authorization denial, stale signer session, missing org role, or sensitive data projection mismatch blocks action. +- Current proof obligations: wallet signature proof, provider installation proof, role/license readback, policy id/hash, and denial reason. +- Current source-bearing implementation basis: wallet API, VCS API, BTD access primitives, Terminal permission UI, MCP/ChatGPT action gates. +- Current validating commands and parity basis: wallet tests, access tests, API route tests, Terminal permission tests, and staging auth readback. +- Current accepted boundaries: broad enterprise RBAC depth can expand inside V29 only when tied to Terminal transaction operation. + +### Disclosure and projection + +- Current canonical objects and emitted artifacts: disclosure policy, projection policy, redaction decision, preview metadata, owner-read/licensed-read/denied state. +- Current algorithms and derivation rules: source-safe preview reveals measurements and rights posture, not protected AssetPack source; paid unlock changes the disclosability boundary. +- Current invariants and fail-closed conditions: public projection overexposure, missing projection policy, or unpaid source access blocks display and delivery. +- Current proof obligations: disclosure boundary proof, projection policy hash, redaction decision, and access readback. +- Current source-bearing implementation basis: BTD access/projection primitives, Terminal preview components, API route serializers, and tests. +- Current validating commands and parity basis: disclosure tests, UI tests, readback queries, and source leakage scans. +- Current accepted boundaries: public docs may summarize posture but must not expose private source. + +### Settlement and exact accounting + +- Current canonical objects and emitted artifacts: BTC fee quote, PSBT, payment observation, settlement unlock, BTD range, source-to-shares, journal entry, ledger anchor, reconciliation report. +- Current algorithms and derivation rules: Share-to-Fee pricing is deterministic from measurement weights and measurement volume; BTC fee payment gates protected-source unlock and read-license/right transfer. +- Current invariants and fail-closed conditions: settlement conservation drift, missing payment proof, stale fee quote, reorg, replacement, broadcast failure, or custody ambiguity blocks finality. +- Current proof obligations: quote root, PSBT state, txid or blocked-readiness receipt, ledger anchor, source-to-shares report, and reconciliation result. +- Current source-bearing implementation basis: `packages/btd` fee/range/journal/reconciliation primitives, UAPI settlement routes, Terminal payment UI, and Supabase projections. +- Current validating commands and parity basis: BTD tests, settlement route tests, staging ledger/database readback, and V29 gate checks. +- Current accepted boundaries: value-bearing mainnet stays outside V29 unless separately approved. + +### Proof contract, witnesses, and replay + +- Current canonical objects and emitted artifacts: proof family, member, theorem, witness artifact, replay step, generated proof appendix, validation report. +- Current algorithms and derivation rules: every promoted V29 claim needs a generated or executable witness, and every failure must preserve enough context for replay. +- Current invariants and fail-closed conditions: stale promoted status truth, missing witness, inconsistent proof root, or ungreen promotion validation blocks promotion. +- Current proof obligations: proof-family report, canonical input report, canon-posture drift report, promotion dry-run, generated appendix, and gate closure checks. +- Current source-bearing implementation basis: spec-family checker, canonical-input checker, promotion scripts, gate-quality workflows, and protocol-demonstration proof runtime. +- Current validating commands and parity basis: `check:spec-family`, V29 gate scripts, canon-posture drift checks, demonstration tests, package tests, and promotion workflow. +- Current accepted boundaries: V29 promotion automation may be hardened across gates but must be complete before `version/v29` merges to `main`. + +## V29 proof-family canon + +### Exact proof-family inventory matrix + +| proofFamily | proofArtifactPath | memberIds | theoremIds | replayStepIds | witnessArtifactPaths | Current source basis | +| --- | --- | --- | --- | --- | --- | --- | +| Inference-synthesis | `.bitcode/v29-inference-synthesis-proof.json` | prompt, model, parsed-output | prompt-complete, typed-output | render, infer, parse, persist | pipeline telemetry, route tests | Reading pipeline contracts | +| Prompt-completeness | `.bitcode/v29-prompt-completeness-proof.json` | prompt parts, templates, interpolations | no-hidden-prompt, context-bound | compose, render, record | prompt render outputs | prompt registry and tests | +| Static-code-analysis | `.bitcode/v29-static-code-analysis-proof.json` | source scans, route scans, import scans | no-versioned-routes, no-demo-import | scan, report | lint/typecheck outputs | scripts and CI | +| Verification-decisions | `.bitcode/v29-verification-decisions-proof.json` | Fit verification, preview verification | threshold, blocker, no-worthy-fit | search, rank, decide | depository search reports | asset-pack pipeline | +| Selection-and-materialization | `.bitcode/v29-selection-and-materialization-proof.json` | selected fits, delivery branch | paid-before-source, pr-delivery | synthesize, settle, deliver | AssetPack evidence, PR receipt | pipeline host and VCS routes | +| Authorization-and-sensitive-flow | `.bitcode/v29-authorization-and-sensitive-flow-proof.json` | wallet, org, license, policy | authorized-action, redaction | sign, authorize, project | wallet/access readbacks | BTD and UAPI | +| Settlement-source-to-shares | `.bitcode/v29-settlement-source-to-shares-proof.json` | fee, range, license, source shares | conservation, right-transfer | quote, pay, mint, reconcile | source-to-shares, fee receipt | BTD settlement primitives | +| Disclosure-boundary | `.bitcode/v29-disclosure-boundary-proof.json` | preview, paid unlock, denied state | no-prepay-source, paid-source | preview, unlock, read | projection-policy, leakage scans | access/projection code | +| Proof-contract | `.bitcode/v29-proof-contract.json` | families, theorems, witnesses | complete-family, replayable | generate, validate, promote | spec/proven artifacts | spec-family tools | + +### Inference-synthesis + +- proofArtifactPath: `.bitcode/v29-inference-synthesis-proof.json` +- members: Reading Need synthesis, Finding Fits discovery, AssetPack synthesis, preview validation, settlement unlock inference. +- theoremIds: prompt-complete, typed-output, model-bound, telemetry-persisted. +- replayStepIds: render prompts, call model or mock, parse type, persist execution telemetry. +- witnessArtifactPaths: pipeline telemetry rows, prompt render artifacts, route test reports, staging readback. +- current member closure criteria: each inference point is a ThricifiedGeneration under a PTRR agent step with a schema-bound output. +- current member verdict shape: pass, fail, blocked, or accepted-boundary with evidence path. +- current theorem-by-theorem closure reading: no theorem is closed without prompt, input, raw output posture, parsed output, model id, and usage state. +- current theorem-to-replay grouping: prompt composition, model call, parse, persist, and UI projection. +- minimum artifact/replay binding set: execution id, pipeline id, phase id, PTRR agent id, PTRR step id, ThricifiedGeneration id, prompt id, model id, output schema id. +- current proof-object fields: proofFamily, memberId, theoremId, replayStepId, evidencePath, verdict, blocker. +- generated-artifact and test bindings: `.bitcode/v29-spec-family-report.json`, pipeline tests, route tests, and Terminal stream tests. +- fail-closed conditions: missing prompt, missing typed parse, hidden model id, or missing telemetry blocks promotion. + +### Prompt-completeness + +- proofArtifactPath: `.bitcode/v29-prompt-completeness-proof.json` +- members: prompt part registry, prompt template registry, agent prompt registry, step prompt registry, sub-step prompt composition. +- theoremIds: every inference has a prompt template; every interpolated prompt is recorded; every schema is named. +- replayStepIds: collect prompt parts, compose prompt, interpolate context, record prompt payload. +- witnessArtifactPaths: rendered prompt files, telemetry rows, prompt tests. +- current member closure criteria: no inference occurs without a registered prompt path. +- current member verdict shape: pass, fail, blocked, accepted-boundary. +- current theorem-by-theorem closure reading: prompt completeness is required before parsed-envelope admissibility. +- current theorem-to-replay grouping: registry lookup, composition, interpolation, telemetry projection. +- minimum artifact/replay binding set: prompt ids, prompt part ids, context root, template text, interpolated text. +- current proof-object fields: promptId, templateId, contextRoot, inferenceId, schemaId, verdict. +- generated-artifact and test bindings: prompt inventory, prompt rendering tests, pipeline contract tests. +- fail-closed conditions: prompt contract incompleteness blocks the step. + +### Static-code-analysis + +- proofArtifactPath: `.bitcode/v29-static-code-analysis-proof.json` +- members: route version scan, import boundary scan, source casing scan, lint, typecheck. +- theoremIds: no versioned active source, no demonstration runtime import, no casing drift. +- replayStepIds: scan files, compare rules, emit report. +- witnessArtifactPaths: CI logs, local command output, `.bitcode` reports. +- current member closure criteria: all required scans pass or name accepted compatibility exceptions. +- current member verdict shape: pass, fail, blocked. +- current theorem-by-theorem closure reading: source shape must match active canon posture. +- current theorem-to-replay grouping: route scan, import scan, lint/typecheck. +- minimum artifact/replay binding set: command, exit code, checked paths, violations. +- current proof-object fields: ruleId, path, result, evidence, blocker. +- generated-artifact and test bindings: gate-quality workflow and local gate scripts. +- fail-closed conditions: active versioned route, stale draft posture, or direct demo import blocks closure. + +### Verification-decisions + +- proofArtifactPath: `.bitcode/v29-verification-decisions-proof.json` +- members: candidate fit verification, preview verification, settlement readiness verification. +- theoremIds: threshold-admitted, no-worthy-fit-is-honest, blocked-readiness-is-explained. +- replayStepIds: search, rank, verify, decide. +- witnessArtifactPaths: search result rows, ranking roots, verification reports. +- current member closure criteria: every Fit decision has candidates, thresholds, roots, and reasons. +- current member verdict shape: worthy_fit, no_worthy_fit, blocked_readiness. +- current theorem-by-theorem closure reading: the decision must be derivable from stored candidates and Need measurements. +- current theorem-to-replay grouping: recall, ranking, scoring, verifier judgment. +- minimum artifact/replay binding set: Need id, deposit ids, scores, threshold, ranking root, verifier output. +- current proof-object fields: decision, candidates, roots, reasons, output schema. +- generated-artifact and test bindings: depository-search tests, staging readback, Terminal preview tests. +- fail-closed conditions: fabricated candidate, missing source root, or absent blocker reason. + +### Selection-and-materialization + +- proofArtifactPath: `.bitcode/v29-selection-and-materialization-proof.json` +- members: selected deposits, AssetPack synthesis, branch artifact, delivery PR. +- theoremIds: context-bound-synthesis, paid-before-source, delivery-target-matches-read. +- replayStepIds: select, synthesize, preview, unlock, deliver. +- witnessArtifactPaths: assetPackEvidence, delivery receipts, PR metadata. +- current member closure criteria: materialized source is never visible to Reader before paid unlock. +- current member verdict shape: preview_locked, unlock_ready, delivered, blocked. +- current theorem-by-theorem closure reading: selection and delivery must read back from settlement and source roots. +- current theorem-to-replay grouping: fit selection, synthesis, settlement unlock, VCS branch, PR creation. +- minimum artifact/replay binding set: fitDepositAssetIds, sourceRoot, settlementUnlockId, branch, pullRequest. +- current proof-object fields: selectedIds, previewPolicy, unlockDecision, deliveryReceipt, blocker. +- generated-artifact and test bindings: pipeline host tests, VCS tests, readback verifier. +- fail-closed conditions: unpaid source exposure, mismatched target repo, missing PR receipt. + +### Authorization-and-sensitive-flow + +- proofArtifactPath: `.bitcode/v29-authorization-and-sensitive-flow-proof.json` +- members: wallet identity, signer session, provider connection, org role, read-license, policy decision. +- theoremIds: action-authorized, secret-not-projected, redaction-applied. +- replayStepIds: authenticate, authorize, project, redact. +- witnessArtifactPaths: wallet proof, connection rows, policy readback, redaction logs. +- current member closure criteria: sensitive data is only shown to authorized principals and only at the admitted boundary. +- current member verdict shape: authorized, denied, blocked, redacted. +- current theorem-by-theorem closure reading: an action cannot execute from UI intent alone. +- current theorem-to-replay grouping: identity proof, role/license lookup, policy decision, projection. +- minimum artifact/replay binding set: principal id, role/license ids, policy id/hash, decision. +- current proof-object fields: principal, policy, decision, reason, projectedFields. +- generated-artifact and test bindings: wallet/access tests, API tests, Terminal permission tests. +- fail-closed conditions: authorization denial or projection mismatch blocks action. + +### Settlement-source-to-shares + +- proofArtifactPath: `.bitcode/v29-settlement-source-to-shares-proof.json` +- members: fee quote, payment observation, BTD range, source-to-shares, read-license, journal. +- theoremIds: fee-conservation, range-conservation, license-transfer. +- replayStepIds: quote, prepare PSBT, observe payment, mint/transfer, reconcile. +- witnessArtifactPaths: `.bitcode/source-to-shares.json`, fee receipt, journal rows, ledger anchors. +- current member closure criteria: settlement must conserve BTC fee, BTD range, source shares, and right transfer. +- current member verdict shape: prepared, signed, broadcast, confirmed, blocked, reconciled. +- current theorem-by-theorem closure reading: no paid source unlock without fee and right-transfer readback. +- current theorem-to-replay grouping: quote root, payment path, ledger observation, BTD state, reconciliation. +- minimum artifact/replay binding set: fee quote root, txid or blocked receipt, range id, license id, journal id. +- current proof-object fields: quote, payment, range, license, reconciliation, blocker. +- generated-artifact and test bindings: BTD tests, settlement route tests, staging readback. +- fail-closed conditions: settlement conservation drift, stale quote, or chain reorg. + +### Disclosure-boundary + +- proofArtifactPath: `.bitcode/v29-disclosure-boundary-proof.json` +- members: preview, projection policy, redaction, paid unlock, denied state. +- theoremIds: no-prepay-source, paid-reader-source, denied-state-no-source. +- replayStepIds: project preview, redact source, evaluate unlock, read source. +- witnessArtifactPaths: `.bitcode/projection-policy.json`, preview payloads, leakage scan reports. +- current member closure criteria: source-bearing content crosses visibility boundary only after paid unlock. +- current member verdict shape: preview, locked, unlocked, denied, blocked. +- current theorem-by-theorem closure reading: disclosure posture must be explainable from policy, payment, and license state. +- current theorem-to-replay grouping: preview, settlement, license, projection. +- minimum artifact/replay binding set: preview id, projection policy hash, settlement unlock id, license id. +- current proof-object fields: visibility, policy, redactions, unlock, blocker. +- generated-artifact and test bindings: disclosure tests, UI tests, source leakage scans. +- fail-closed conditions: public projection overexposure or unpaid protected-source access. + +### Proof-contract + +- proofArtifactPath: `.bitcode/v29-proof-contract.json` +- members: spec-family report, canonical input report, canon-posture drift report, promotion proof appendix. +- theoremIds: complete-family, valid-draft, valid-promotion. +- replayStepIds: validate family, validate inputs, validate posture, generate proven, promote. +- witnessArtifactPaths: `.bitcode/v29-spec-family-report.json`, `.bitcode/v29-canonical-input-report.json`, `BITCODE_SPEC_V29_PROVEN.md`. +- current member closure criteria: promotion cannot run unless all gate checks and generated proof inputs are green. +- current member verdict shape: draft-valid, promotion-ready, promoted, blocked. +- current theorem-by-theorem closure reading: generated canon must match the hand-authored spec family and source posture. +- current theorem-to-replay grouping: check, generate, dry-run promote, commit promote. +- minimum artifact/replay binding set: spec family files, generated reports, proof-source commit, promotion command. +- current proof-object fields: version, report, currentTarget, pointer, promotionCommit, verdict. +- generated-artifact and test bindings: spec-family checker, canonical-input checker, promotion workflow. +- fail-closed conditions: stale promoted status truth, missing generated appendix, or failed gate check. + +## V29 generated canon + +### Inherited V19 reproducible-canon artifacts + +V29 continues the reproducible-canon requirement: generated reports must be deterministic, path-addressable, and promotion-bound. + +### Inherited V20 operator-quality artifacts + +V29 continues operator-quality proof: Terminal workflow claims must be backed by UI, accessibility, responsive, error-state, and browser evidence where applicable. + +### Exact generated-artifact inventory matrix + +| artifact | required in draft | required at promotion | purpose | +| --- | --- | --- | --- | +| `.bitcode/v29-spec-family-report.json` | yes | yes | validates the hand-authored V29 family shape | +| `.bitcode/v29-canonical-input-report.json` | yes | yes | records canonical input closure for active V28 plus V29 draft | +| `.bitcode/v29-canon-posture-drift-report.json` | gate-dependent | yes | proves runtime/docs active/draft posture | +| `BITCODE_SPEC_V29_PROVEN.md` | no | yes | generated proof appendix for promoted V29 | + +### V29 specifying generated artifacts + +The minimum V29 generated set is `.bitcode/v29-spec-family-report.json`, `.bitcode/v29-canonical-input-report.json`, future `.bitcode/v29-canon-posture-drift-report.json`, and `BITCODE_SPEC_V29_PROVEN.md`. + +### Shared generated-artifact fields + +Every generated artifact must include artifact id, schema id, version, current target, source commit, command, generated timestamp, verdict, inputs, and blockers. + +### Artifact-specific generated payload fields + +Spec-family reports include required file lists and section counts. +Canonical-input reports include active pointer, family paths, generated artifact paths, and proof appendix posture. +Canon-posture reports include active canon, draft target, runtime carrier paths, and drift failures. +Promotion reports include proof-source commit and promotion command. + +### Artifact confidentiality and disclosability taxonomy + +Generated artifacts are internal by default, reviewer-visible when they contain no secrets, public only when explicitly projected, buyer-visible only after paid unlock, and never allowed to leak protected source or secrets. + +### Minimum generated appendix rendered contents + +`BITCODE_SPEC_V29_PROVEN.md` must render aggregate proof verdict, exact proof-family inventory, exact per-family member inventory, exact per-family theorem inventory, exact replay-step inventories and theorem bindings, witness artifact inventories, generated artifact inventories, scenario and run coverage matrices, proof-source commit, and fail closed when any required proof input is absent. + +### Canonical regeneration and fail-closed posture + +Generated canon must be regenerable from repository state. +Promotion must fail closed when any required report, witness, test, proof family, or source posture is stale. + +## V29 validation canon + +V29 validation is layered: + +- spec-family and canonical-input checks for the V29 draft; +- canon-posture drift checks for V28 active and V29 draft; +- V29 gate-specific scripts; +- package lint, typecheck, and Jest suites; +- UAPI route/component tests; +- Terminal browser, accessibility, responsive, and error-state checks; +- local non-mocked OpenAI/Supabase/Vercel Sandbox validation for gates that touch live pipeline behavior; +- staging-testnet readback where ledger/database synchronization or delivery is claimed. + +## V29 promotion canon + +V29 promotes only through `version/v29` into `main`. +Promotion must: + +1. pass every V29 gate check; +2. pass active V28 and draft V29 posture checks before promotion; +3. generate `.bitcode/v29-*` canonical reports; +4. generate `BITCODE_SPEC_V29_PROVEN.md`; +5. update runtime posture carriers from active V28/draft V29 to active V29/next draft; +6. commit `BITCODE_SPEC.txt` changing from `V28` to `V29`; +7. keep main protected by pull request and verified-signature rules. + +## V29 appendices and canonical supporting material + +The appendices below are binding draft structure for V29. +They name the proof, artifact, validation, source, workflow, and fail-closed surfaces that every later gate must keep synchronized. + +## Appendix A. Canonical type and surface catalog + +Canonical V29 type families: + +- Reading: ReadRequest, ReadNeed, FindingFitsResult, AssetPackPreview, SettlementUnlock. +- Pipeline: execution, pipeline, phase, PTRR agent, PTRR step, ThricifiedGeneration, tool call, prompt record, parsed output. +- Terminal: TerminalTransaction, journal row, stream row, detail accordion, repair action. +- BTD: range, source-to-shares, access policy, read-license, BTC fee quote, payment observation, ledger anchor, reconciliation report. +- Delivery: branch artifact, AssetPack evidence, pull request, delivery repair receipt. + +## Appendix B. Proof family closure catalog + +Each proof family named in the proof-family canon must have members, theorems, replay steps, witness artifacts, generated artifacts, and fail-closed conditions before V29 promotion. + +## Appendix C. Generated artifact contract catalog + +The V29 generated-artifact contract is exactly the generated canon section above plus Appendix K source-bearing artifact constraints. + +## Appendix D. Validation and checking gate catalog + +Gate validation starts with `pnpm run check:v29-gate1`. +Later gates must add focused scripts before claiming implementation closure. +Promotion validation must run all V29 gate scripts, source scans, package tests, UAPI tests, demonstration proof checks, generated report checks, and diff hygiene. + +## Appendix E. Current canonical source map + +Source map: + +- `BITCODE_SPEC.txt`: active canon pointer, still `V28` during V29 drafting. +- `BITCODE_SPEC_V29.md`, `_DELTA`, `_NOTES`, `_PARITY_MATRIX`: draft target family. +- `protocol-demonstration/src/canon-posture.js`: active/draft runtime posture carrier. +- `packages/pipelines/asset-pack`: Reading pipeline and AssetPack synthesis source. +- `packages/pipeline-hosts`: sandbox/harness execution source. +- `packages/btd`: BTD, BTC, rights, journal, and reconciliation primitives. +- `uapi/app/terminal`: Terminal operator surface. +- `.github/workflows`: gate and promotion automation. + +## Appendix F. Subsystem totality and derivability matrix + +V29 must cover repo supply and depositing; reading and measured demand; prompt/inference/evaluator ownership; deposit-to-read fit; recall and ranking; verification decisions; selection and materialization; branch artifacts and assetPackEvidence; identity, authority, signing, and policy; sensitive data and confidentiality flows; projection, disclosure, and redaction; proof families, members, theorems, witnesses, and replay; settlement, source-to-shares, journals, and exact accounting; telemetry, persistence, state, and failure semantics; host/runtime capability truth; operator experience and pedagogy; validation and test stack; generated artifacts and canonical promotion. + +The subsystem sections in the canonical subsystem surfaces chapter are the active derivability matrix rows for V29. + +## Appendix G. Canonical file-family and promotion contract catalog + +V29 file family: + +- `BITCODE_SPEC_V29.md` +- `BITCODE_SPEC_V29_DELTA.md` +- `BITCODE_SPEC_V29_NOTES.md` +- `BITCODE_SPEC_V29_PARITY_MATRIX.md` +- future `BITCODE_SPEC_V29_PROVEN.md` +- `.bitcode/v29-spec-family-report.json` +- `.bitcode/v29-canonical-input-report.json` +- future `.bitcode/v29-canon-posture-drift-report.json` + +## Appendix H. Operator surface and quality contract catalog + +Terminal quality must include: + +- URL-addressable transaction state; +- guided low-detail default path; +- expandable complete detail; +- readable live stream rows for pipeline, agent, tool, prompt, ledger, and delivery activity; +- keyboard and screen-reader usable controls; +- responsive layout; +- explicit empty, loading, blocked, failed, repaired, paid, and delivered states. + +## Appendix I. Scenario, workflow, and cross-product contract catalog + +V29 cross-product scenarios include auth-issuer-rollback, privacy-boundary-proof-export, polyglot-gateway-benchmark-remediation, auth-many-asset-normalization, Targeted deposit, Normalization deposit, patch, context, public, buyer, reviewer, internal, Openly writable, Measurably readable, Provable, and Valuable. + +These names are scenario/workflow coverage labels, not new product brands. + +## Appendix J. Fail-closed contract and error posture matrix + +Fail-closed states: + +- invalid deposit blocks Finding Fits; +- prompt contract incompleteness blocks inference; +- parsed-envelope inadmissibility blocks typed pipeline output; +- no-survivor asset pack blocks preview and settlement; +- authorization denial blocks protected action; +- public projection overexposure blocks display; +- settlement conservation drift blocks unlock and delivery; +- stale promoted status truth blocks promotion. + +Every fail-closed state must carry a readable Terminal blocker and a repair or retry posture when repair is allowed. + +## Appendix K. Source-bearing AssetPack and artifact contract catalog + +Source-bearing AssetPack artifacts include: + +- `.bitcode/asset-pack.lock.json` +- `.bitcode/selected-source-material.json` +- `.bitcode/verification-report.json` +- `.bitcode/source-to-shares.json` +- `.bitcode/projection-policy.json` +- `.bitcode/system-proof-bundle.json` +- `BITCODE_SPEC_V29_PROVEN.md` + +Before settlement, the Reader may see only source-safe preview metadata. +After settlement, the Reader may receive the full AssetPack source according to the paid read-license/right transfer and delivery policy. + +## V29 accepted boundaries and reopen conditions + +Accepted boundaries: + +- V29 remains Terminal-depth, not Exchange depth. +- V29 may deepen MCP/ChatGPT only where Terminal transaction authority requires shared permission truth. +- V29 may harden demonstration-origin commercial internals but must keep the demonstration standalone. +- V29 may use staging-testnet and local live validation; value-bearing mainnet remains separately approved. +- V29 promotion automation may be implemented across gates, but it must be complete before promotion. + +Reopen conditions: + +- V28 promoted law is found inconsistent with source behavior. +- Terminal exposes protected source before settlement. +- ledger/database projection contradicts settlement truth. +- organization permission decisions cannot be derived from registry/access policy state. +- gate workflow cannot fail closed for stale active/draft posture. + +## V29 completion condition + +V29 is complete only when: + +- all gates in the V29 parity matrix are closed; +- the Terminal supports the deep transaction workflows specified here; +- live or bounded-real validation proves the claimed Reading/settlement/delivery paths; +- promotion workflows can promote only `version/v29`; +- generated V29 proof artifacts and `BITCODE_SPEC_V29_PROVEN.md` are produced; +- `BITCODE_SPEC.txt` changes from `V28` to `V29` only in the formal promotion commit. diff --git a/BITCODE_SPEC_V29_DELTA.md b/BITCODE_SPEC_V29_DELTA.md new file mode 100644 index 000000000..a8be71610 --- /dev/null +++ b/BITCODE_SPEC_V29_DELTA.md @@ -0,0 +1,118 @@ +# Bitcode Spec V29 Delta + +## Status + +- Version: `V29` +- V29 state: draft target opened; this delta records V29's planned Terminal-depth changes over promoted V28 +- Current canonical/latest target: `V28` +- Prior canonical anchor: `BITCODE_SPEC_V28.md` +- Prior generated proof appendix: `BITCODE_SPEC_V28_PROVEN.md` +- Generated structured artifact inventory: draft `.bitcode/v29-spec-family-report.json`, draft `.bitcode/v29-canonical-input-report.json`, future `.bitcode/v29-canon-posture-drift-report.json`, and no `BITCODE_SPEC_V29_PROVEN.md` until promotion +- Source parity state: V29 delta truth is opened in documentation and gate-quality scripts; product implementation begins only through V29 gate branches +- State: draft target delta opened +- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V28` +- Scope: V29 delta for deeper Terminal transaction operation after V28 commercial Reading, AssetPack, settlement, delivery, and promotion closure +- Spec companion: `BITCODE_SPEC_V29.md` +- Notes companion: `BITCODE_SPEC_V29_NOTES.md` +- Parity companion: `BITCODE_SPEC_V29_PARITY_MATRIX.md` +- Generated proof appendix: none until V29 promotion + +## Why V29 exists + +V28 canonically promoted the first commercial Bitcode Protocol and Terminal MVP: + +- Depositing creates source-bound depository evidence. +- Read Request to Read-Need comprehension is formalized. +- Finding Fits searches the depository and synthesizes source-safe AssetPack previews. +- Settlement, read-license/right transfer, and PR delivery are specified and implemented at MVP depth. +- Gate, branch, commit, CI, and promotion governance are formalized. + +V29 exists because the Terminal now needs enterprise operational depth. +The product must not merely complete the happy path; it must make every transaction state navigable, recoverable, provable, and comprehensible. + +## Accepted V29 decisions + +- V28 remains active canon during V29 drafting. +- V29 owns deeper Terminal workflows and transaction operation. +- V29 gate branches are opened from `version/v29` and merged back only when their gate acceptance criteria are closed. +- V29 preserves the V28 five-step Reading UX: request Read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, buy/settle. +- V29 deepens wallet, signer-session, BTC fee, PSBT, broadcast, replacement, reorg, blocked-readiness, and failure recovery in Terminal. +- V29 deepens AssetPack range detail, owner-read, licensed-read, denied-state, source-safe preview, paid unlock, and access-policy review. +- V29 deepens Terminal journal diffing, ledger/database/metaphysical separation, reconciliation repair, and proof-root surfacing. +- V29 deepens organization holdings, roles, read-license usage, and registry-derived permission decisions. +- V29 continues formalizing demonstration-origin commercial internals into packages and narrow APIs without importing `protocol-demonstration/` runtime code. +- V29 workflows and scripts must be retargeted to active V28 and draft V29. + +## Explicitly deferred + +- Exchange product/market depth remains beyond V29. +- Website Conversations product depth remains beyond V29. +- New `$BTD` supply law remains out of scope. +- Value-bearing mainnet launch remains separately approval-gated. +- Full provider-family completion remains out of scope unless a Terminal transaction gate requires a narrow hook. +- V30 remains the home for Protocol/BTD hardening discovered during V28/V29 when the hardening is not required to complete Terminal transaction depth. +- V31+ scopes remain future unless explicitly reopened by a later spec. + +## Pre-Implementation Sequence + +1. Open `version/v29` from promoted `main`. +2. Open `v29/gate-1-objectives-and-gating` from `version/v29`. +3. Create the V29 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V28`. +4. Retarget gate-quality and canon-quality workflow posture checks from V27/V28 to V28/V29. +5. Add a V29 Gate 1 checker and package script. +6. Define V29 gates, acceptance criteria, and carryforward parity rows. +7. Validate spec family, canonical inputs, canon posture, workflows, and diff hygiene. +8. Push the gate branch and open a pull request to `version/v29`. + +## Commit-Body Direction + +V29 gate commit bodies should describe the closed gate, the spec-family changes, the implementation surfaces, the validation commands, and any accepted boundaries. +The eventual V29 promotion commit body must name the Terminal transaction-depth surfaces, list all closed V29 gates, cite generated proof artifacts, state that `BITCODE_SPEC.txt` advances from `V28` to `V29`, and explicitly defer Exchange/Conversations/value-bearing-mainnet work. + +## Gate Delta + +### Gate 1: V29 Objectives And Gating + +Gate 1 opens V29 correctly: + +- V29 SPEC, DELTA, NOTES, and PARITY files exist. +- `BITCODE_SPEC.txt` remains `V28`. +- README and workflows describe V28 active / V29 draft posture. +- `check:v29-gate1` validates branch naming, spec family, notes, parity, workflow posture, and promotion boundaries. +- The V29 gate list is explicit before product implementation begins. + +### Gate 2: Terminal Transaction Read Models And Navigation + +Gate 2 owns URL-addressable transaction state, Terminal state machine, detail panes, execution-to-transaction read models, low-detail defaults, expandable detail, and no raw-JSON dependency for ordinary operators. + +### Gate 3: Wallet Signer Session And BTC Fee Operations + +Gate 3 owns wallet connection depth, signer-session recovery, BTC fee quote lifecycle, PSBT handoff, broadcast/finality/replacement/reorg/failure states, blocked-readiness receipts, and no server-custody posture. + +### Gate 4: Reading Transaction Recovery And Pipeline Observability + +Gate 4 owns deep Terminal visibility over `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis`, including execution, phase, PTRR agent, PTRR step, ThricifiedGeneration, prompt, tool, output, and typed parse telemetry. + +### Gate 5: AssetPack Disclosure Rights And Preview Depth + +Gate 5 owns AssetPack range detail, owner-read/licensed-read/denied-state flows, source-safe preview, disclosure policy review, paid unlock state, and protected-source leakage tests. + +### Gate 6: Settlement Reconciliation And Repair + +Gate 6 owns ledger/database/metaphysical separation, journal diffing, reconciliation repair actions, proof-root surfacing, settlement conservation drift handling, and delivery recovery. + +### Gate 7: Organization Permissions And Interface Authority + +Gate 7 owns organization holdings, roles, read-license usage, registry-derived permission decisions, MCP/ChatGPT action authority alignment, and Terminal permission explainers. + +### Gate 8: Demonstration-Origin Commercial Formalization + +Gate 8 owns cleanup of freshly ported demonstration-origin internals into package-native APIs, no demonstration runtime imports, durable package tests, and updated internal/public documentation. + +### Gate 9: Terminal UX Quality And Browser Proof + +Gate 9 owns accessibility, responsive layout, copy/prose clarity, empty/loading/blocked/failed states, Playwright coverage, and visual/browser verification for the complete Terminal transaction cockpit. + +### Gate 10: Local And Staging Promotion Readiness + +Gate 10 owns non-mocked local validation, staging-testnet readback, generated proof artifacts, V29 promotion workflow support, promotion dry-run, and final version branch readiness. diff --git a/BITCODE_SPEC_V29_NOTES.md b/BITCODE_SPEC_V29_NOTES.md index 858dc18d8..57c79f90d 100644 --- a/BITCODE_SPEC_V29_NOTES.md +++ b/BITCODE_SPEC_V29_NOTES.md @@ -3,59 +3,95 @@ ## Status - Version: `V29` -- V29 state: future notes scaffold only -- Current canonical/latest target: `V27` -- Current active draft target: `V28` -- Prior canonical anchor: `BITCODE_SPEC_V27.md` -- Prior generated proof appendix: `BITCODE_SPEC_V27_PROVEN.md` -- Generated structured artifact inventory: none for V29 yet -- Source parity state: not opened; V29 source parity begins only after V29 draft opening -- Scope: future notes for deeper Terminal work after V28 commercial Protocol/Terminal MVP QA. - -This NOTES file does not promote V29 and does not open V29 implementation. -It preserves roadmap intent so V28 can remain focused on commercial Protocol/Terminal MVP QA, bugfixing, audit, and hardening. +- V29 state: draft target opened; V29 notes now track active V28 canon and V29 Terminal-depth gate planning +- Current canonical/latest target: `V28` +- Prior canonical anchor: `BITCODE_SPEC_V28.md` +- Prior generated proof appendix: `BITCODE_SPEC_V28_PROVEN.md` +- Generated structured artifact inventory: draft `.bitcode/v29-spec-family-report.json`, draft `.bitcode/v29-canonical-input-report.json`, future `.bitcode/v29-canon-posture-drift-report.json`, and no `BITCODE_SPEC_V29_PROVEN.md` until promotion +- Source parity state: notes opened from V28 handoff; source implementation begins gate-by-gate after Gate 1 +- Scope: V29 notes for deeper Terminal workflow, transaction operation, evidence readability, wallet/BTC operation, settlement repair, organization permission, and promotion-readiness work. ## Notes companion rule -This file is planning memory only. -Requirements become binding only when V29 is explicitly opened as the draft-target SPEC family. +This file is a required companion to `BITCODE_SPEC_V29.md`. +It may carry planning detail, QA observations, and simplified reading, but it must not override the main V29 SPEC. +Binding V29 requirements must be reflected in SPEC, DELTA, and PARITY before a gate closes. ## Concise current-system reading -V27 is active canon. -V28 is current draft target and owns commercial Protocol implementation, Terminal MVP QA, MCP API/ChatGPT App MVP, BTD/testnet/ledgerization, and demonstration-to-commercial boundary cleanup. -V29 is expected to deepen Terminal after the Terminal/Protocol shell, Auxillaries active shell, BTD disclosure, MCP/ChatGPT MVP, and route QA are stable. +V28 is active canon. +V29 is the current draft target and owns deeper Terminal transaction operation over the promoted V28 commercial Reading system. -## Intended V29 focus +The V28 system already defines: -V29 owns deeper Terminal: +- source Depositing into the Bitcode depository; +- Read Request to reviewed Read-Need comprehension; +- Finding Fits over fit deposits in the depository; +- source-safe AssetPack preview before settlement; +- BTC fee posture, BTD range/read-license/right transfer, and delivery; +- ledger/database reconciliation, telemetry, and promotion governance at MVP depth. -- full Read submission, measurement, review, Fit, proof, dedupe, measuremint, and settlement workflows; -- wallet connection, signer-session recovery, BTC fee preparation, PSBT handoff, broadcast, replacement, reorg, and failure recovery depth; -- AssetPack range detail, owner-read, licensed-read, denied-state, and access-policy review as ordinary operator workflows; -- Terminal journal diffing, reconciliation repair, ledger/database/metaphysical state separation, and proof-root surfacing; -- organization holdings, team roles, read-license usage, and registry-derived Terminal permission decisions; -- Terminal-specific route, UI, accessibility, responsive, error-state, and Playwright coverage. -- Terminal prose, labels, explainers, and read/write guidance refined for clearer commercial comprehension while preserving V27 technical law. +V29's job is to make those flows operationally excellent in Terminal: recoverable, navigable, typed, inspectable, accessible, and promotion-proven. -## Inputs deferred from V28 QA +## Simplified-spec reading rule -- May 7, 2026 V28 manual QA accepted Terminal as the primary operator surface at MVP level but identified prose clarity as a Terminal-focused improvement. -- V29 should improve Terminal copy, hierarchy, explanatory precision, and operator sequencing around Deposit, Read, Fit, proof, AssetPack, BTC fee posture, BTD range/read-right posture, and selected activity detail. -- This is not a V28 blocker unless specific wording prevents a user from completing basic V28 MVP navigation or materially misstates Bitcode law. -- May 7, 2026 follow-up QA clarified that Terminal should not present itself as a market-wide master-detail product surface. V28 must fix that MVP architecture and any obvious dead/ambiguous click targets; V29 should then deepen Terminal-specific sequencing, density management, task progression, and richer Deposit/Read result reading without reintroducing Exchange-style market language. -- V28 introduces a formal `@bitcode/protocol` package and removes direct commercial imports from the standalone `protocol-demonstration`, but some package internals are intentionally fresh ports for parity. V29 must continue commercializing those demonstration-origin internals into formal packages, narrower APIs, durable package tests, and Terminal-owned protocol adapters. -- The standalone `protocol-demonstration` should remain a sibling reference guide and proof witness outside the workspace build graph. V29 should use it to reveal commercial implementation gaps, not as runtime code imported by commercial UAPI, Terminal, Auxillaries, MCP, ChatGPT App, or package consumers. +For a simplified reading of V29: -## Boundaries +1. V28 is the current law. +2. V29 does not change the law of BTD supply, BTC fee asset, or source-safe paid unlock. +3. V29 improves how a commercial operator uses Terminal to carry a transaction from readiness through paid delivery and repair. +4. If a Terminal state is important for money, source visibility, rights, proof, or delivery, it must be visible, typed, and recoverable. +5. `BITCODE_SPEC.txt` must remain `V28` until the V29 promotion workflow commits the canonical pointer change. -V29 deepens Terminal only after V28 establishes commercial Protocol/Terminal MVP coherence. -It must not absorb V30 Protocol/BTD hardening, V31 Auxillaries depth, V32 provation/testing depth, V33 interface finalization, V34 deployment depth, V35 telemetry/documentation depth, or V36+ Exchange/Conversations depth except for narrow Terminal-owned hooks. +## V29 gate plan -V29 must also avoid reopening V28's demonstration/commercial boundary. -Any Terminal feature that currently depends on freshly ported demonstration-origin modules should be formalized in-place inside commercial packages or replaced with package-native primitives, while the standalone demonstration stays a reference implementation. +1. **Gate 1: V29 Objectives And Gating** + - Open the V29 spec family. + - Retarget workflows and branch/readme posture to active V28 / draft V29. + - Add a Gate 1 checker and define all V29 gates. -## Return To V28 +2. **Gate 2: Terminal Transaction Read Models And Navigation** + - Build URL-addressable Terminal transaction state, typed read models, default-low-detail navigation, and expandable detail panes. -Do not start V29 implementation during V28. -Record Terminal gaps found during V28 QA as future V29 inputs unless they block V28 commercial Protocol/Terminal MVP usability. +3. **Gate 3: Wallet Signer Session And BTC Fee Operations** + - Deepen signer-session recovery, BTC fee quote, PSBT handoff, broadcast, replacement, reorg, failure, and blocked-readiness states. + +4. **Gate 4: Reading Transaction Recovery And Pipeline Observability** + - Make `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` execution telemetry fully readable in Terminal at execution, phase, PTRR agent, PTRR step, ThricifiedGeneration, prompt, tool, raw output, and parsed output levels. + +5. **Gate 5: AssetPack Disclosure Rights And Preview Depth** + - Deepen source-safe preview, AssetPack range detail, owner-read/licensed-read/denied state, disclosure policy review, paid unlock, and source-leakage tests. + +6. **Gate 6: Settlement Reconciliation And Repair** + - Make ledger/database/metaphysical separation, journal diffing, reconciliation repair, proof roots, and delivery recovery ordinary Terminal workflows. + +7. **Gate 7: Organization Permissions And Interface Authority** + - Deepen org holdings, roles, read-license usage, registry-derived permission decisions, and MCP/ChatGPT action authority parity. + +8. **Gate 8: Demonstration-Origin Commercial Formalization** + - Continue moving freshly ported internals into package-native APIs and durable tests while preserving the standalone demonstration boundary. + +9. **Gate 9: Terminal UX Quality And Browser Proof** + - Close accessibility, responsive, copy, loading/empty/error/blocked states, browser checks, and Playwright coverage for the complete Terminal cockpit. + +10. **Gate 10: Local And Staging Promotion Readiness** + - Run non-mocked local validation, staging-testnet readback, generated proof artifacts, promotion dry-run, and `version/v29` promotion readiness. + +## Gate 1 closure notes + +Gate 1 is complete only when the V29 family exists, validates, and is wired to CI. +It intentionally does not claim Terminal product closure. + +Gate 1 accepted evidence: + +- `BITCODE_SPEC_V29.md`, DELTA, NOTES, and PARITY exist. +- `BITCODE_SPEC.txt` remains `V28`. +- workflows and README describe V28 active / V29 draft posture. +- `pnpm run check:v29-gate1` validates branch, posture, workflow, docs, and spec-family shape. + +## Later-version boundaries + +- V30 remains reserved for Protocol/BTD hardening that is not necessary to close Terminal transaction depth. +- V31+ scopes remain future unless a later spec family reopens them. +- Exchange and website Conversations remain outside V29 product depth. +- Value-bearing mainnet remains separately approved. diff --git a/BITCODE_SPEC_V29_PARITY_MATRIX.md b/BITCODE_SPEC_V29_PARITY_MATRIX.md new file mode 100644 index 000000000..69a3958e4 --- /dev/null +++ b/BITCODE_SPEC_V29_PARITY_MATRIX.md @@ -0,0 +1,94 @@ +# Bitcode Spec V29 Parity Matrix + +## Status + +- Version: `V29` +- V29 state: draft target opened; parity now tracks V29 gates over active V28 canon +- Current canonical/latest target: `V28` +- Prior canonical anchor: `BITCODE_SPEC_V28.md` +- Prior generated proof appendix: `BITCODE_SPEC_V28_PROVEN.md` +- Generated structured artifact inventory: draft `.bitcode/v29-spec-family-report.json`, draft `.bitcode/v29-canonical-input-report.json`, future `.bitcode/v29-canon-posture-drift-report.json`, and no `BITCODE_SPEC_V29_PROVEN.md` until promotion +- Source parity state: Gate 1 parity is documentation/workflow/checker closure; product-source rows start as pending V29 gate work +- State: draft target parity matrix opened +- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V28` +- Scope: V29 parity ledger for Terminal transaction depth, wallet/BTC operations, Reading pipeline observability, AssetPack disclosure, settlement repair, organization permissions, UX quality, and promotion readiness +- Spec companion: `BITCODE_SPEC_V29.md` +- Notes companion: `BITCODE_SPEC_V29_NOTES.md` +- Delta companion: `BITCODE_SPEC_V29_DELTA.md` +- Generated proof appendix: none until V29 promotion + +## Purpose + +The V29 parity matrix prevents Terminal-depth work from becoming vague product polish. +Each gate must name source surfaces, tests, proof evidence, documentation, and accepted boundaries before it closes. + +## Audit basis + +Gate 1 audit basis: + +- `BITCODE_SPEC.txt` +- `BITCODE_SPEC_V28.md` +- `BITCODE_SPEC_V28_DELTA.md` +- `BITCODE_SPEC_V28_NOTES.md` +- `BITCODE_SPEC_V28_PARITY_MATRIX.md` +- `BITCODE_SPEC_V28_PROVEN.md` +- `BITCODE_SPEC_V29_NOTES.md` +- `README.md` +- `AGENTS.md` +- `.github/workflows/bitcode-gate-quality.yml` +- `.github/workflows/bitcode-canon-quality.yml` +- `package.json` +- `protocol-demonstration/src/canon-posture.js` +- Terminal, Reading pipeline, BTD, pipeline-host, UAPI, and workflow surfaces named by V28 promotion. + +No `_legacy/` source is active source truth. + +## V29 implementation matrix + +| Area | Gate | Source evidence | Judgment | Closure requirement | +| --- | --- | --- | --- | --- | +| Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V29.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v29/gate-1-objectives-and-gating` | drafted | V29 family validates in draft mode over active V28 and `check:v29-gate1` passes. | +| Workflow retargeting | Gate 1 | `.github/workflows/bitcode-gate-quality.yml`, `.github/workflows/bitcode-canon-quality.yml` | drafted | CI checks V28 active / V29 draft posture instead of stale V27/V28 posture. | +| Terminal transaction read models | Gate 2 | `uapi/app/terminal`, API execution routes, read-model adapters | pending | Terminal transaction state is URL-addressable, recoverable, and typed. | +| Wallet signer/BTC operations | Gate 3 | `packages/btd`, wallet API, BTC fee route, Terminal wallet UI | pending | Signer session, PSBT, broadcast/finality/reorg/replacement/failure states are ordinary Terminal states. | +| Reading pipeline observability | Gate 4 | `packages/pipelines/asset-pack`, `packages/pipeline-hosts`, Terminal stream components | pending | Pipeline/phase/PTRR/ThricifiedGeneration/tool/prompt telemetry is complete and readable. | +| AssetPack disclosure rights | Gate 5 | BTD access primitives, AssetPack preview UI, disclosure policy tests | pending | Source-safe preview and paid unlock are proven without source leakage. | +| Settlement reconciliation repair | Gate 6 | BTD journal/reconciliation, Supabase readback, Terminal repair UI | pending | Ledger, database, and metaphysical state drift is visible and repairable. | +| Organization permission authority | Gate 7 | access policy, org holdings, MCP/ChatGPT gates, Terminal permission UI | pending | Registry-derived roles, holdings, and read-license authority govern actions. | +| Commercial formalization | Gate 8 | packages/protocol, package tests, import scans, docs | pending | Demonstration-origin commercial internals are package-native and no runtime demo imports remain. | +| Terminal UX quality | Gate 9 | Playwright/Jest/a11y/responsive/browser QA | pending | Complete transaction cockpit is usable by default and inspectable in detail. | +| Promotion readiness | Gate 10 | promotion workflow, `.bitcode/v29-*`, `BITCODE_SPEC_V29_PROVEN.md` | pending | `version/v29` can promote to `main` only after all V29 checks pass. | + +## V29 implementation checklist + +| Area | Required V29 result | Judgment | +| --- | --- | --- | +| Active canon pointer | `BITCODE_SPEC.txt` remains `V28` during V29 gate work | drafted | +| Gate branch pattern | V29 work happens on `version/v29` or `v29/gate-N-*` branches | drafted | +| Spec-family shape | V29 SPEC, DELTA, NOTES, and PARITY satisfy the full spec-family checker | drafted | +| Gate 1 script | `pnpm run check:v29-gate1` fails closed on stale posture or missing gates | drafted | +| Product implementation gates | Gates 2-9 close Terminal transaction depth with tests and docs | pending | +| Promotion gate | Gate 10 closes generated proof and promotion automation | pending | + +## Gate 1 Parity + +| Requirement | Source evidence | Current V29 judgment | +| --- | --- | --- | +| Active canon remains V28 during V29 draft opening | `BITCODE_SPEC.txt` contains `V28` | drafted | +| Runtime draft target is V29 | `protocol-demonstration/src/canon-posture.js` declares V28 active and V29 draft | drafted | +| V29 SPEC family exists as draft | `BITCODE_SPEC_V29.md`, DELTA, NOTES, and PARITY | drafted | +| Gate-quality workflow is V29-aware | `.github/workflows/bitcode-gate-quality.yml` | drafted | +| Canon-quality workflow is V29-aware | `.github/workflows/bitcode-canon-quality.yml` | drafted | +| README reflects V28/V29 posture | `README.md` | drafted | +| V29 Gate 1 checker exists | `scripts/check-v29-gate1-objectives-and-gating.mjs` and package script | drafted | + +## accepted boundaries + +- Gate 1 does not implement Terminal product depth. +- Gate 1 does not create `BITCODE_SPEC_V29_PROVEN.md`. +- Gate 1 does not promote `BITCODE_SPEC.txt` to V29. +- Gate 1 may retarget workflows to active V28 / draft V29 so later gates are greenable. + +## completion condition + +Gate 1 is complete when the V29 draft family validates, `check:v29-gate1` passes, workflow posture is V29-aware, README/docs reflect V29 initiation, and the gate branch is committed and pushed for review into `version/v29`. diff --git a/README.md b/README.md index 50889834b..cede61449 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Bitcode Repository `BITCODE_SPEC.txt` is the canonical pointer for active-system work. It currently -resolves to `V27`; V28 is the active draft target for commercial MVP QA, -hardening, and surface cleanup. +resolves to `V28`; V29 is the active draft target for deeper Terminal +transaction workflows and operator recovery. ## Current Product Posture @@ -12,9 +12,10 @@ The primary operator routes are: - `/terminal` for depositing, reading, transaction work, and protocol follow-through. - `/auxillaries` for Wallet, Externals, Profile, and Interfaces support surfaces. -Exchange and website Conversations remain in source as deferred commercial work, -but V28 closure focuses on Terminal, Auxillaries, wallet/BTC testnet, MCP API, -and ChatGPT App MVP behavior. +Exchange and website Conversations remain in source as deferred commercial work. +V29 closure focuses on Terminal transaction depth over the promoted V28 Reading, +Finding Fits, AssetPack preview, BTC settlement, rights transfer, and delivery +canon. The protocol demonstration remains the minimal deterministic reference for the same protocol. Commercial code may mount or compare against demonstration @@ -39,10 +40,10 @@ verified signatures. Use a version branch and gate-numbered branches: -1. Create one base branch per draft target, such as `version/v28`. +1. Create one base branch per draft target, such as `version/v29`. 2. Create scoped gate branches from the version branch. Prefix every gate branch - with the gate number, for example `v28/gate-3-read-fit-workflow` or - `v28/gate-8-promotion-proof`. + with the gate number, for example `v29/gate-1-objectives-and-gating` or + `v29/gate-6-settlement-reconciliation-repair`. 3. Group related work into clear commits with quality commit messages whose titles and bodies describe the proof, implementation, or documentation change. @@ -54,16 +55,15 @@ Use a version branch and gate-numbered branches: version is formally promoted as canon. Gate pull requests into `version/**` run the Bitcode gate-quality workflow: -draft-canon checks, casing/import checks, relevant package typechecks and Jest -suites, protocol-demonstration QA, and diff hygiene. The repository-wide canon -quality workflow stays green during draft work by checking active/draft posture -and MVP demonstration proof, while full promoted-suite closure is reserved for -the version promotion workflow. Version pull requests into `main` run the -version promotion workflow. For V28, that workflow validates the promotion proof -posture and, only after promotion validations pass, executes the canonical -promotion script, generates `BITCODE_SPEC_V28_PROVEN.md`, and commits the -promotion artifacts plus `BITCODE_SPEC.txt` pointer change from `V27` to `V28` -on the version branch. +active/draft canon checks, casing/import checks, relevant package typechecks and +Jest suites, protocol-demonstration QA, and diff hygiene. The repository-wide +canon quality workflow stays green during draft work by checking active/draft +posture and promoted-spec proof posture, while full promoted-suite closure is +reserved for the version promotion workflow. Version pull requests into `main` +run the version promotion workflow. For V29, promotion work must validate the +Terminal-depth proof posture, generate `BITCODE_SPEC_V29_PROVEN.md`, and commit +promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from `V28` to +`V29` on the version branch. The application CI workflow uses the root pnpm workspace install, runs uapi lint/typecheck/build plus mocked Jest coverage, and keeps heavier legacy scans explicitly opt-in until their catalogs are refurbished: set @@ -74,9 +74,9 @@ or promotion validation. ## Key Surfaces - [BITCODE_SPEC.txt](BITCODE_SPEC.txt) is the canonical version pointer. -- [BITCODE_SPEC_V27.md](BITCODE_SPEC_V27.md) is the active promoted spec family. -- [BITCODE_SPEC_V28.md](BITCODE_SPEC_V28.md) is the active draft target. -- [BITCODE_V28_QA.md](BITCODE_V28_QA.md) tracks commercial MVP QA. +- [BITCODE_SPEC_V28.md](BITCODE_SPEC_V28.md) is the active promoted spec family. +- [BITCODE_SPEC_V29.md](BITCODE_SPEC_V29.md) is the active draft target. +- [BITCODE_SPEC_V29_PARITY_MATRIX.md](BITCODE_SPEC_V29_PARITY_MATRIX.md) tracks V29 gate parity. - [uapi/README.md](uapi/README.md) documents the commercial website/API surface. - [uapi/app/terminal/README.md](uapi/app/terminal/README.md) documents Terminal. - [uapi/app/exchange/README.md](uapi/app/exchange/README.md) documents Exchange. diff --git a/package.json b/package.json index 4420fd808..f02eb3ef2 100644 --- a/package.json +++ b/package.json @@ -44,6 +44,7 @@ "check:v28-gate11": "node scripts/check-v28-gate11-read-fits-finding-preview.mjs", "check:v28-gate12": "node scripts/check-v28-gate12-settlement-rights-delivery.mjs", "check:v28-gate13": "node scripts/check-v28-gate13-product-closure-promotion-readiness.mjs", + "check:v29-gate1": "node scripts/check-v29-gate1-objectives-and-gating.mjs", "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic", "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title", "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24", diff --git a/protocol-demonstration/test/v21-specifying.test.js b/protocol-demonstration/test/v21-specifying.test.js index a9018bf0b..61c1a8876 100644 --- a/protocol-demonstration/test/v21-specifying.test.js +++ b/protocol-demonstration/test/v21-specifying.test.js @@ -20,7 +20,7 @@ function projectLabel(version) { function expectedActiveCanonicalInputArtifactCount(version) { const numeric = Number.parseInt(String(version || '').replace(/^V/u, ''), 10); if (!Number.isInteger(numeric)) return 3; - if (numeric === 27) return 0; + if (numeric === 27 || numeric === 28) return 0; if (numeric >= 26) return 22; if (numeric >= 22) return 3; if (numeric === 21) return 2; diff --git a/scripts/check-bitcode-pre-commit.mjs b/scripts/check-bitcode-pre-commit.mjs index 45196b945..3bf0fe841 100644 --- a/scripts/check-bitcode-pre-commit.mjs +++ b/scripts/check-bitcode-pre-commit.mjs @@ -16,9 +16,9 @@ const SPEC_RELEVANT_PATHS = [ /^BITCODE_SPEC\.txt$/u, /^packages\/protocol-demonstration\/src\/canonical\/v21-specifying\.js$/u, /^package\.json$/u, - /^scripts\/(?:check-bitcode-|check-v28-metadevelopment-readiness|prepare-bitcode-spec-family-promotion|prepare-bitcode-runtime-canon-promotion|promote-bitcode-canon|run-bitcode-spec-quality|setup-bitcode-git-hooks)/u, + /^scripts\/(?:check-bitcode-|check-v28-metadevelopment-readiness|check-v29-gate1-objectives-and-gating|prepare-bitcode-spec-family-promotion|prepare-bitcode-runtime-canon-promotion|promote-bitcode-canon|run-bitcode-spec-quality|setup-bitcode-git-hooks)/u, /^\.githooks\/(?:pre-commit|commit-msg)$/u, - /^\.github\/workflows\/(?:bitcode-canon-quality|bitcode-gate-quality|v28-canon-promotion)\.yml$/u + /^\.github\/workflows\/(?:bitcode-canon-quality|bitcode-gate-quality|v28-canon-promotion|v29-canon-promotion)\.yml$/u ]; function projectLabel(version) { diff --git a/scripts/check-v29-gate1-objectives-and-gating.mjs b/scripts/check-v29-gate1-objectives-and-gating.mjs new file mode 100644 index 000000000..cf8ce67b5 --- /dev/null +++ b/scripts/check-v29-gate1-objectives-and-gating.mjs @@ -0,0 +1,177 @@ +#!/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 repoRoot = path.resolve(__dirname, '..'); + +function read(root, relativePath) { + return readFileSync(path.join(root, relativePath), 'utf8'); +} + +function fileExists(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 hasSection(content, sectionHeading) { + const escaped = sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + return new RegExp(`^#{2,6}\\s+${escaped}\\s*$`, 'm').test(content); +} + +function parseArgs(argv) { + const args = { + skipBranchCheck: false, + repoRoot + }; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + if (arg === '--skip-branch-check') args.skipBranchCheck = true; + else if (arg === '--repo-root') args.repoRoot = path.resolve(argv[++index]); + 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-v29-gate1-objectives-and-gating.mjs [--skip-branch-check] [--repo-root ]', + '', + 'Checks V29 Gate 1 draft-family, branch, workflow, docs, and posture readiness.' + ].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 === 'V28', + `BITCODE_SPEC.txt must remain V28 during V29 gate work. Observed ${pointer || 'empty'}.` + ); + + if (!args.skipBranchCheck) { + const branch = git(root, ['branch', '--show-current']); + assertCheck( + failures, + branch === 'version/v29' || /^v29\/gate-\d+-[a-z0-9][a-z0-9-]*$/u.test(branch), + `V29 work must occur on version/v29 or gate-prefixed branches. Observed ${branch || 'detached HEAD'}.` + ); + } + + const requiredFiles = [ + 'BITCODE_SPEC_V29.md', + 'BITCODE_SPEC_V29_DELTA.md', + 'BITCODE_SPEC_V29_NOTES.md', + 'BITCODE_SPEC_V29_PARITY_MATRIX.md', + 'BITCODE_SPECIFYING.md', + 'BITCODE_SPEC_TEMPLATEGUIDE.md', + '.github/workflows/bitcode-gate-quality.yml', + '.github/workflows/bitcode-canon-quality.yml', + 'README.md', + 'AGENTS.md' + ]; + + for (const relativePath of requiredFiles) { + assertCheck(failures, fileExists(root, relativePath), `Missing required V29 Gate 1 file: ${relativePath}`); + } + + const spec = read(root, 'BITCODE_SPEC_V29.md'); + const delta = read(root, 'BITCODE_SPEC_V29_DELTA.md'); + const notes = read(root, 'BITCODE_SPEC_V29_NOTES.md'); + const parity = read(root, 'BITCODE_SPEC_V29_PARITY_MATRIX.md'); + const packageJson = read(root, 'package.json'); + const gateWorkflow = read(root, '.github/workflows/bitcode-gate-quality.yml'); + const canonWorkflow = read(root, '.github/workflows/bitcode-canon-quality.yml'); + const readme = read(root, 'README.md'); + const agents = read(root, 'AGENTS.md'); + const posture = read(root, 'protocol-demonstration/src/canon-posture.js'); + + assertCheck(failures, spec.includes('Current canonical/latest target: `V28`'), 'V29 SPEC must declare V28 as current canonical/latest target.'); + assertCheck(failures, delta.includes('Current canonical/latest target: `V28`'), 'V29 DELTA must declare V28 as current canonical/latest target.'); + assertCheck(failures, notes.includes('Current canonical/latest target: `V28`'), 'V29 NOTES must declare V28 as current canonical/latest target.'); + assertCheck(failures, parity.includes('Current canonical/latest target: `V28`'), 'V29 PARITY must declare V28 as current canonical/latest target.'); + assertCheck(failures, posture.includes("ACTIVE_CANON_VERSION = 'V28'"), 'Runtime canon posture must keep V28 active.'); + assertCheck(failures, posture.includes("DRAFT_TARGET_VERSION = 'V29'"), 'Runtime canon posture must declare V29 as draft target.'); + + for (const gate of [ + 'Gate 1: V29 Objectives And Gating', + 'Gate 2: Terminal Transaction Read Models And Navigation', + 'Gate 3: Wallet Signer Session And BTC Fee Operations', + 'Gate 4: Reading Transaction Recovery And Pipeline Observability', + 'Gate 5: AssetPack Disclosure Rights And Preview Depth', + 'Gate 6: Settlement Reconciliation And Repair', + 'Gate 7: Organization Permissions And Interface Authority', + 'Gate 8: Demonstration-Origin Commercial Formalization', + 'Gate 9: Terminal UX Quality And Browser Proof', + 'Gate 10: Local And Staging Promotion Readiness' + ]) { + assertCheck(failures, hasSection(delta, gate) || notes.includes(gate), `V29 gate plan is missing ${gate}.`); + } + + assertCheck(failures, hasSection(notes, 'Simplified-spec reading rule'), 'V29 NOTES must carry the simplified-spec reading rule.'); + assertCheck(failures, hasSection(parity, 'V29 implementation matrix'), 'V29 PARITY must carry an implementation matrix.'); + assertCheck(failures, hasSection(parity, 'V29 implementation checklist'), 'V29 PARITY must carry an implementation checklist.'); + assertCheck(failures, parity.includes('| Draft family and branch posture | Gate 1 |'), 'V29 PARITY must name Gate 1 draft-family posture.'); + + assertCheck(failures, packageJson.includes('"check:v29-gate1"'), 'package.json must expose check:v29-gate1.'); + assertCheck(failures, gateWorkflow.includes('check-v29-gate1-objectives-and-gating.mjs'), 'Gate workflow must run the V29 Gate 1 checker.'); + assertCheck(failures, gateWorkflow.includes('--version V29 --mode draft --current-target V28'), 'Gate workflow must validate V29 draft spec over V28.'); + assertCheck(failures, gateWorkflow.includes('--active-canon V28 --draft-target V29'), 'Gate workflow must validate V28/V29 canon posture.'); + assertCheck(failures, canonWorkflow.includes('--active-canon V28 --draft-target V29'), 'Canon quality workflow must validate V28/V29 canon posture.'); + assertCheck(failures, canonWorkflow.includes('--version V29 --mode draft --current-target V28'), 'Canon quality workflow must validate V29 draft family.'); + + assertCheck(failures, readme.includes('resolves to `V28`; V29 is the active draft target'), 'README must state V28 active / V29 draft posture.'); + assertCheck(failures, readme.includes('version/v29'), 'README must document the version/v29 branch workflow.'); + assertCheck(failures, readme.includes('v29/gate-1-objectives-and-gating'), 'README must document a V29 gate branch example.'); + assertCheck(failures, agents.includes('version/v29') || agents.includes('such as `version/v28`'), 'AGENTS.md must document version base branch usage.'); + assertCheck(failures, /gate branches must be prefixed with the gate number/i.test(agents), 'AGENTS.md must retain gate-number branch discipline.'); + + const routeScan = execFileSync('find', ['uapi/app/api', '-path', '*v[0-9]*', '-print'], { + cwd: root, + encoding: 'utf8' + }).trim(); + assertCheck(failures, routeScan.length === 0, `UAPI API routes must remain unversioned. Found:\n${routeScan}`); + + if (failures.length > 0) { + process.stderr.write('V29 Gate 1 objectives and gating check failed:\n'); + for (const failure of failures) process.stderr.write(`- ${failure}\n`); + process.exitCode = 1; + return; + } + + process.stdout.write(`V29 Gate 1 objectives and gating ok pointer=${pointer}\n`); +} + +try { + main(); +} catch (error) { + const detail = error instanceof Error ? error.message : String(error); + process.stderr.write(`${detail}\n`); + process.exitCode = 1; +}