diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0ec0d77e4..3e470b7a4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,7 @@ ## Title -Use the version and gate prefix for gate PRs: `V33 Gate N: Concise Topical Title`. -Use the version and promotion prefix for version promotion PRs: `V33 Canonical Promotion: Concise Topical Title`. +Use the version and gate prefix for gate PRs: `V34 Gate N: Concise Topical Title`. +Use the version and promotion prefix for version promotion PRs: `V34 Canonical Promotion: Concise Topical Title`. ## Closure diff --git a/.github/workflows/bitcode-canon-quality.yml b/.github/workflows/bitcode-canon-quality.yml index 18c700c44..10f21919a 100644 --- a/.github/workflows/bitcode-canon-quality.yml +++ b/.github/workflows/bitcode-canon-quality.yml @@ -134,7 +134,15 @@ jobs: node scripts/check-bitcode-spec-family.mjs --version V33 --mode draft --current-target V32 fi ;; + spec:\ V34*|spec:\ v34*) + POINTER="$(cat BITCODE_SPEC.txt)" + if [ "$POINTER" = "V34" ]; then + node scripts/check-bitcode-spec-family.mjs --version V34 --mode promoted --current-target V34 + else + node scripts/check-bitcode-spec-family.mjs --version V34 --mode draft --current-target V33 + fi + ;; *) - echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33 spec change." + echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34 spec change." ;; esac diff --git a/.github/workflows/bitcode-gate-quality.yml b/.github/workflows/bitcode-gate-quality.yml index d6db8f7da..e876d3d58 100644 --- a/.github/workflows/bitcode-gate-quality.yml +++ b/.github/workflows/bitcode-gate-quality.yml @@ -147,6 +147,7 @@ jobs: node scripts/check-bitcode-spec-family.mjs --version V34 --mode draft --current-target V33 fi node scripts/check-v33-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check + node scripts/check-v34-gate1-deployment-roadmap-opening.mjs --skip-branch-check else echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2 exit 1 diff --git a/BITCODE_SPEC_V34.md b/BITCODE_SPEC_V34.md new file mode 100644 index 000000000..1527a946c --- /dev/null +++ b/BITCODE_SPEC_V34.md @@ -0,0 +1,623 @@ +# Bitcode Spec V34 + +## Status + +- Version: `V34` +- V34 state: Gate 1 deployment-roadmap opening is active over promoted V33 canon +- Current canonical/latest target: `V33` +- Prior canonical anchor: `BITCODE_SPEC_V33.md` +- Prior generated proof appendix: `BITCODE_SPEC_V33_PROVEN.md` +- Generated structured artifact inventory: draft V34 specifying artifacts `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json`, and later deployment-depth artifacts as gates close +- Source parity state: Gate 1 opens V34 deployment-depth parity; host capability, environment lane, distributed execution, storage, approval, rollback, repair, and rehearsal source parity is not closed until the relevant gates close +- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V33` +- Notes companion: `BITCODE_SPEC_V34_NOTES.md` +- Delta companion: `BITCODE_SPEC_V34_DELTA.md` +- Parity companion: `BITCODE_SPEC_V34_PARITY_MATRIX.md` +- Generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md` only after V34 promotion +- Scope: V34 draft system specification for deployment depth over promoted Terminal, Reading, Protocol/BTD, Auxillaries, MCP API, ChatGPT App, public API, proof, and interface contracts +- Last fully realized canonical target preserved in source: `V33` + +V34 begins from promoted V33. +V33 closed commercial interface-depth across MCP API, ChatGPT App, public API, package-owned schemas, authorization policy, Read license and AssetPack rights contracts, compatibility matrices, telemetry/proof hooks, consumer UX proof, and promotion readiness. +V34 makes that commercial system operator-deployable: explicit host capabilities, environment lanes, distributed execution receipts, storage durability, deployment approvals, rollback, upgrade, secret rotation, data repair, and staging-testnet rehearsal become current-system law. + +## Version executive summary + +V34 is the deployment-depth version. +It turns the proven V33 commercial interface system into an operator-deployable system whose runtime conditions are as explicit as its Protocol/BTD and interface contracts. +Enterprise Bitcode operation must prove where the system is running, what capabilities are available, which lane admits which value posture, where durable state is stored, how long-running work is receipted, how migrations and promotions are approved, and how failures are repaired without leaking secrets, wallet material, protected source, or unpaid AssetPack contents. + +V34 closes only when deployment operators and automated systems can: + +- identify every required host capability for website, API, MCP, ChatGPT App, workers, observers, broadcasters, proof services, and repair jobs; +- prove which environment lane is running: local, regtest, signet, staging-testnet, public testnet, mainnet-ready dry run, or value-bearing mainnet; +- run distributed pipeline, ledger, wallet, settlement, storage, proof, and repair work with typed execution receipts and replayable roots; +- validate deployment approvals, migrations, generated artifacts, secrets, and rollback readiness before traffic or value-bearing activity is admitted; +- rehearse local and staging-testnet deployment closure without exposing protected source, credentials, wallet private material, or unpaid AssetPack contents. + +## Canonical Bitcode executive summary + +Bitcode measures technical knowledge, finds deposits that fit reviewed Reads, synthesizes source-bearing AssetPacks, and settles read rights in BTC with BTD range and rights receipts. +The active V33 canon remains: + +- Deposits supply source material to the Bitcode depository. +- A Read Request is synthesized into a reviewed ReadNeed by `ReadNeedComprehensionSynthesis`. +- `ReadFitsFindingSynthesis` searches for plural threshold-passing fit deposits and synthesizes source-safe AssetPack preview records. +- Protected AssetPack source remains hidden before paid settlement. +- BTC is the fee asset and BTD range/read-license/right transfer is ledgerized. +- Paid settlement unlocks full AssetPack delivery, including pull-request delivery where applicable. + +V34 does not redefine those laws. +V34 makes them deployable, observable, recoverable, and promotion-safe across concrete runtime lanes. + +## V34 source-of-truth hierarchy + +The V34 source-of-truth hierarchy is: + +1. `BITCODE_SPEC.txt`, which remains `V33` until V34 promotion. +2. `BITCODE_SPEC_V34.md` during V34 drafting. +3. `BITCODE_SPEC_V34_NOTES.md`. +4. `BITCODE_SPEC_V34_DELTA.md`. +5. `BITCODE_SPEC_V34_PARITY_MATRIX.md`. +6. generated V34 artifacts under `.bitcode/` when produced. +7. `BITCODE_SPEC_V34_PROVEN.md` only after promotion. +8. source implementation, tests, examples, public docs, internal docs, and QA evidence that realize this family. + +Older specifications are provenance only. +They must not become hidden current-system law. + +## V34 full-system, re-implementation, and audit rule + +V34 must be re-implementable and auditable from its specification family without reading conversation history. +Every host capability contract, environment lane, distributed runtime receipt, storage carrier, deployment approval, rollback plan, migration gate, secret rotation path, repair job, and promotion check 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. + +## V34 totality and precision enforcement rule + +V34 fails closed when any deployable Bitcode surface lacks an explicit host capability, environment-lane posture, runtime receipt shape, storage durability posture, migration/approval gate, rollback path, secret boundary, and proof replay expectation. +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; +- interfaces are contract consumers, not owners of protocol truth; +- deployment lanes are runtime postures, not source version names; +- deployment receipts are auditable runtime records, not dashboard-only assertions. + +No source identifier may introduce a versioned route, gate, or work-in-progress name unless explicitly accepted as a bounded compatibility artifact. + +## V34 system goals, non-goals, and design principles + +Goals: + +- define a `DeploymentHostCapabilityCatalog` over website, API, MCP, ChatGPT App, workers, observers, broadcasters, proof services, and repair jobs; +- define an `EnvironmentLaneContract` over local, regtest, signet, staging-testnet, public testnet, mainnet-ready dry run, and value-bearing mainnet; +- define `DistributedExecutionRuntimeReceipt` records for long-running pipeline, ledger, wallet, proof, object-storage, and repair work; +- define `DeploymentStoragePosture` for ledger-derived state, canonical database projection, object storage, proof artifacts, audit logs, and rollback material; +- define `MigrationApprovalGate` and deployment CI/CD approvals for schema mutation, generated artifacts, promotion commits, Vercel/Supabase lanes, and secret availability; +- define `SecretRotationPlan`, `RollbackUpgradeRepairPlaybook`, `RuntimeObserverRepairJob`, and `DeploymentReadinessRehearsal`; +- rehearse local and staging-testnet deployment readiness before value-bearing mainnet can be considered. + +Non-goals: + +- no new BTD supply or tokenomics law; +- no rewrite of `ReadNeedComprehensionSynthesis` or `ReadFitsFindingSynthesis` product law; +- no Exchange market-depth implementation; +- no website Conversations product-depth implementation; +- no broad telemetry/documentation program breadth that belongs to V35; +- no value-bearing production-mainnet approval. + +Design principles: + +- deployment law before deployment convenience; +- lane posture before runtime execution; +- durable receipts before dashboard-only observability; +- migration approval before schema mutation; +- secret rotation before credential aging becomes operational risk; +- rollback and repair posture before traffic or value-bearing activity. + +## V34 system architecture and layer boundaries + +V34 preserves the V33 architecture and adds deployment-depth ownership: + +- `packages/protocol` owns canon posture, spec-family checks, generated-proof helpers, promotion-governance helper APIs, and deployment proof helper APIs. +- `packages/btd` owns BTD range, read-license, rights transfer, wallet capability, fee posture, settlement, access policy, reconciliation primitives, and value-lane admission boundaries. +- `packages/api` owns JSON-safe reusable route contracts over package primitives and must expose deployment posture only through source-safe schemas. +- `packages/pipelines/asset-pack` owns Reading pipeline contracts and source-safe preview outputs; runtime hosts may execute pipelines but must not redefine them. +- `packages/executions-mcp` owns MCP server contracts and tool exposure; MCP deployment posture must derive from package-owned contracts. +- `packages/chatgptapp` owns ChatGPT App action contracts and source-safe response rendering. +- `uapi` owns commercial product routes and user interfaces, but not protocol truth or deployment law. +- `protocol-demonstration` remains a standalone minimal reference and proof witness outside the workspace import graph. +- deployment host services own runtime carriers, queues, observers, broadcasters, repair jobs, object storage, and environment variables, but only through V34 contracts. + +Layer boundaries: + +- Commercial interfaces may call commercial APIs and packages; they must not import demonstration runtime code. +- Deployment hosts may run pipelines, observers, broadcasters, and repair jobs; they must not create alternate Protocol/BTD or Reading law. +- Ledger records and journals are source-of-truth for settlement/finality; Supabase/PostgreSQL projections must not contradict them. +- Object storage carries source-bearing AssetPacks, proof bundles, generated artifacts, and rollback material only under explicit disclosure and retention policy. +- Source-safe previews may expose measurements, roots, score bands, policy ids, fee quote roots, settlement posture, and denial reasons; they may not expose protected source before payment. +- Interface responses may expose proof roots and repair instructions; they must not expose secrets, service-role keys, wallet private material, provider tokens, raw protected prompts, or pre-settlement AssetPack source. +- Value-bearing mainnet activity is blocked until a future canon admits it; V34 may define readiness and dry-run proof, not production value launch. + +## V34 proof/test package API and inherited support canon + +V34 treats package APIs as the source of deployment truth. +The formal package boundaries are: + +- `@bitcode/protocol` owns active/draft canon posture, generated proof helpers, and V34 deployment check helpers. +- `@bitcode/btd` owns rights, range, fee, wallet, access, treasury, reconciliation, and value-lane admission primitives. +- `@bitcode/api` owns reusable JSON contracts for public API consumers and source-safe deployment posture. +- `@bitcode/pipeline-asset-pack` owns Reading pipeline contract surfaces and source-safe preview outputs. +- MCP and ChatGPT App packages consume those contracts rather than inventing protocol-local shapes. + +The commercial protocol package owns the active/draft posture while V34 is in flight: + +- `ACTIVE_CANON_VERSION = 'V33'`; +- `DRAFT_TARGET_VERSION = 'V34'`; +- spec-family, canonical-input, canon-posture-drift, and proven-generation helpers remain exported through the package index; +- package tests and V34 checks fail closed on direct demonstration-source imports. + +Any deployment object used by more than one runtime lane must have a package-owned type, builder, parser, validator, source-safe fixture, example, compatibility row, replay command, and generated artifact before the gate that depends on it closes. + +## V34 canonical domain model + +V34 adds deployment-facing contract objects over V33 protocol truth: + +- `DeploymentHostCapabilityCatalog`: host id, runtime surface, required packages, outbound network posture, secret requirements, storage carriers, observer/broadcaster capability, repair capability, proof output paths, and admission status. +- `EnvironmentLaneContract`: lane id, supported Bitcoin network posture, Supabase/Vercel project posture, value-bearing admission, data-retention policy, wallet policy, secret scope, and proof requirements. +- `DistributedExecutionRuntimeReceipt`: execution id, host id, lane id, command or pipeline id, start/finish timestamps, input root, output root, log root, object-storage root, ledger/database projection roots, and repair posture. +- `DeploymentStoragePosture`: ledger-derived state, canonical database projection, object storage, proof artifacts, audit logs, rollback material, retention class, encryption posture, and repair command. +- `MigrationApprovalGate`: migration id, schema diff root, generated type root, dry-run result, reviewer approval, rollback plan, and deployment lane admission. +- `SecretRotationPlan`: secret family, storage owner, rotation cadence, rotation command, blast-radius note, proof root, and leak-response path. +- `RuntimeObserverRepairJob`: observer id, broadcaster id, repair job id, trigger, allowed lane, proof root, and replay command. +- `RollbackUpgradeRepairPlaybook`: rollback id, upgrade id, repair id, state carriers, validation commands, operator approval, and fail-closed posture. +- `DeploymentReadinessRehearsal`: local rehearsal, staging-testnet rehearsal, proof bundle, source-safe screenshots or logs, and admission verdict. +- `DeploymentPromotionReadinessReport`: Gate 10 artifact tying all V34 deployment gates, generated proofs, workflows, and promotion commands together. + +Inherited V33 objects remain active: `Deposit`, `ReadRequest`, `ReadNeed`, `FindingFitsResult`, `AssetPackPreview`, `SettlementUnlock`, `BtcFeeQuote`, `BtdAssetPackMintReceipt`, `BtdReadReceipt`, `BtdRightsTransferReceipt`, `SourceToSharesProof`, `TerminalTransaction`, `McpToolContract`, `ChatGptAppActionContract`, `PublicApiRouteContract`, and `InterfaceTelemetryProofHook`. + +## V34 gate plan + +V34 closes through ten gates: + +1. **Gate 1: V34 Deployment Roadmap And Spec Opening** opens the V34 family over V33 canon, updates `SPECIFICATIONS_ROADMAP.md`, documents V33 active / V34 draft posture, and wires `check:v34-gate1`. +2. **Gate 2: Host Capability And Environment Lane Catalog** inventories runtime hosts, services, queues, observers, broadcasters, storage carriers, and lanes through `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract`. +3. **Gate 3: Distributed Execution Runtime Contracts** defines `DistributedExecutionRuntimeReceipt` for long-running pipeline, ledger, wallet, proof, object-storage, and repair work. +4. **Gate 4: Ledger Database Object Storage Deployment Posture** hardens ledger-derived state, database projection, object storage, generated proof artifacts, audit logs, backup, retention, and rollback material. +5. **Gate 5: Secret Rotation And Credential Boundary Operations** defines secret families, storage owners, rotation commands, leak-response posture, CI masking, and runtime availability checks. +6. **Gate 6: Migration CI/CD Deployment Approval Gates** hardens schema migration approvals, generated type refresh, route scans, promotion commits, Vercel/Supabase lane checks, and deployment blockers. +7. **Gate 7: Runtime Observers Broadcasters Repair Jobs** makes settlement observers, ledger broadcasters, projection repair jobs, proof generators, and queue consumers explicit deployment jobs with receipts. +8. **Gate 8: Rollback Upgrade Data Repair Playbooks** defines operator playbooks for rollback, upgrade, state repair, object-storage repair, generated artifact repair, and incident recovery. +9. **Gate 9: Local Staging Testnet Deployment Rehearsal** proves local and staging-testnet deployment readiness using source-safe rehearsal logs, runtime receipts, and UI/API validation without value-bearing mainnet admission. +10. **Gate 10: V34 Promotion Readiness** generates V34 proof artifacts, promotion readiness, active V34 / draft V35 posture, and canonical promotion support. + +## V34 whole Bitcode operator chain + +The V34 operator chain keeps V33 behavior and adds deployable runtime receipts: + +1. Depositor supplies source material. +2. Bitcode records source-safe deposit measurement and proof roots. +3. Deployment hosts prove lane posture through `EnvironmentLaneContract`. +4. Runtime hosts prove available capabilities through `DeploymentHostCapabilityCatalog`. +5. Reader requests a Read through Terminal, API, MCP API, or ChatGPT App. +6. `ReadNeedComprehensionSynthesis` synthesizes a ReadNeed for review. +7. Reader approves or requests regeneration of the ReadNeed. +8. `ReadFitsFindingSynthesis` searches the depository for plural threshold-passing deposits. +9. Distributed execution records pipeline, tool, agent, and storage roots through `DistributedExecutionRuntimeReceipt`. +10. Bitcode synthesizes a source-safe AssetPack preview and fee quote. +11. Reader reviews measurements, fit quality, policy posture, fee, and rights preview without protected source leakage. +12. Reader settles BTC fee and receives the BTD read/right transfer. +13. Observers, broadcasters, repair jobs, and storage carriers reconcile settlement, finality, rights, delivery, and proof state. +14. Bitcode unlocks full AssetPack delivery and records synchronized ledger, database, object-storage, execution, and interface proof state. + +## V34 canonical subsystem surfaces + +The V34 subsystem coverage is total across 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, and generated artifacts and canonical promotion. + +### Depositing and asset supply + +- Current canonical objects and emitted artifacts: `Deposit`, depository asset id, measurement roots, embedding document roots, host capability rows, and interface-safe deposit summaries. +- Current algorithms and derivation rules: source intake, measurement, proof-root generation, policy classification, depository indexing, and storage lane placement. +- Current invariants and fail-closed conditions: invalid deposit, missing source proof, unsupported provider, policy denial, storage carrier drift, or protected-source leakage blocks projection. +- Current proof obligations: deposit measurement proof, source-safety class, host capability, and object-storage posture. +- Current source-bearing implementation basis: commercial package and `uapi` routes, not `protocol-demonstration`. +- Current validating commands and parity basis: V33 canonical proofs plus V34 host capability and storage posture checks. +- Current accepted boundaries: V34 does not change deposit ownership law. + +### Reading and prompt/inference ownership + +- Current canonical objects and emitted artifacts: `ReadRequest`, `ReadNeed`, `ReadNeedComprehensionSynthesis`, PTRR agents, ThricifiedGenerations, prompt/tool registry records, execution receipts, and source-safe interface summaries. +- Current algorithms and derivation rules: prompt-part composition, PTRR plan/try/refine/retry, judged reasoning, typed output, reviewed Need acceptance, and distributed runtime receipt emission. +- Current invariants and fail-closed conditions: prompt contract incompleteness, parsed-envelope inadmissibility, missing review, auth denial, lane denial, or missing runtime receipt blocks Finding Fits. +- Current proof obligations: interface request schema, Need response schema, telemetry root, runtime receipt, and denial repair path. +- Current source-bearing implementation basis: commercial Reading packages and API routes. +- Current validating commands and parity basis: V33 Reading pipeline proof plus V34 distributed execution contracts. +- Current accepted boundaries: V34 does not rewrite Reading pipeline law. + +### Fit, recall, ranking, and verification + +- Current canonical objects and emitted artifacts: `FindingFitsResult`, plural fit deposits, search roots, ranking roots, verification decisions, source-safe preview fit metadata, and object-storage roots. +- Current algorithms and derivation rules: recall, vector search, ranking, threshold filters, verification, synthesis context selection, and runtime receipt derivation. +- Current invariants and fail-closed conditions: no-worthy-fit, no-survivor asset pack, provider failure, policy denial, lane denial, or protected-source leak blocks preview. +- Current proof obligations: candidate inventory, ranking root, source-safety class, distributed execution receipt, and source-safe preview schema. +- Current source-bearing implementation basis: commercial asset-pack pipeline package. +- Current validating commands and parity basis: V33 proof coverage plus V34 runtime receipt and deployment rehearsal checks. +- Current accepted boundaries: V34 does not broaden pre-settlement disclosure. + +### Selection and materialization + +- Current canonical objects and emitted artifacts: `AssetPackPreview`, protected AssetPack source lock, source-safe measurements, delivery admission, object-storage carrier record, and rollback material. +- Current algorithms and derivation rules: synthesis from fit deposits, preview projection, fee quote, paid unlock, storage, rollback materialization, and PR delivery after settlement. +- Current invariants and fail-closed conditions: unpaid disclosure, invalid fee quote, rights denial, object-storage drift, rollback gap, or delivery failure blocks source visibility. +- Current proof obligations: preview contract, delivery contract, object-storage root, rollback path, and pull-request proof where applicable. +- Current source-bearing implementation basis: `packages/pipelines/asset-pack`, `packages/btd`, `packages/api`, and `uapi`. +- Current validating commands and parity basis: V33 rights/interface artifacts plus V34 storage and rehearsal checks. +- Current accepted boundaries: protected source is never an unpaid interface payload. + +### Identity, authorization, and sensitive flow + +- Current canonical objects and emitted artifacts: `InterfaceAuthorizationPolicy`, organization authority, wallet capability, read-license posture, denial repair record, secret family, and rotation proof. +- Current algorithms and derivation rules: issuer validation, organization/team/role checks, wallet requirement checks, license checks, protected-source policy, secret availability, and rotation proof. +- Current invariants and fail-closed conditions: authorization denial, stale session, missing wallet, missing license, service-secret exposure, provider token exposure, stale secret, or missing rotation path blocks action. +- Current proof obligations: denied-state examples, policy row, source-safety row, secret boundary, and audit root. +- Current source-bearing implementation basis: packages, API middleware, MCP auth, ChatGPT App action guards, Terminal support surfaces, and deployment environment contracts. +- Current validating commands and parity basis: V33 auth proof plus V34 secret rotation and CI masking checks. +- Current accepted boundaries: no secret material is serialized into interface responses or tracked artifacts. + +### Disclosure and projection + +- Current canonical objects and emitted artifacts: source-safe preview, disclosure policy, redacted response, paid unlock, protected-source access record, projection receipt, and repair receipt. +- Current algorithms and derivation rules: source-safe projection, redaction, preview measurement rendering, paid unlock verification, response shaping, projection repair, and source-safe proof export. +- Current invariants and fail-closed conditions: public projection overexposure, unpaid protected-source request, incompatible consumer, stale proof, or stale projection blocks disclosure. +- Current proof obligations: disclosure-boundary tests, preview examples, paid/unpaid contrast fixtures, projection roots, and repair roots. +- Current source-bearing implementation basis: BTD access primitives, API serializers, MCP tools, ChatGPT App renderers, Terminal components, and repair jobs. +- Current validating commands and parity basis: V33 disclosure tests plus V34 observer/repair job checks. +- Current accepted boundaries: preview metadata may be public to the Reader; protected source requires settlement. + +### Settlement and exact accounting + +- Current canonical objects and emitted artifacts: `BtcFeeQuote`, settlement record, BTD receipts, rights transfer, source-to-shares proof, journal, reconciliation record, observer receipt, and broadcaster receipt. +- Current algorithms and derivation rules: fee quote, wallet/PSBT posture, finality observation, BTD read/right transfer, source-to-shares allocation, projection repair, and lane admission. +- Current invariants and fail-closed conditions: settlement conservation drift, invalid finality, underpayment, overpayment, projection drift, missing broadcaster receipt, or delivery mismatch blocks unlock. +- Current proof obligations: fee/root consistency, ledger/database sync, observer receipt, broadcaster receipt, reconciliation repair action, and interface replay hook. +- Current source-bearing implementation basis: `packages/btd`, ledger/database packages, deployment jobs, and API surfaces. +- Current validating commands and parity basis: V33 settlement proof plus V34 observer/broadcaster/repair job checks. +- Current accepted boundaries: production-mainnet value-bearing launch remains approval-gated outside V34. + +### Proof contract, witnesses, and replay + +- Current canonical objects and emitted artifacts: `InterfaceTelemetryProofHook`, execution record, ledger root, database root, object-storage root, generated proof artifact, runtime receipt, rehearsal log, and replay command. +- Current algorithms and derivation rules: request root, response root, event root, proof binding, replay command generation, rehearsal comparison, and fail-closed stale-artifact detection. +- Current invariants and fail-closed conditions: stale promoted status truth, missing replay hook, source-unsafe proof artifact, missing runtime receipt, or drift blocks promotion. +- Current proof obligations: generated artifact rows, command rows, proof roots, deployment receipt roots, and compatibility rows. +- Current source-bearing implementation basis: protocol package helpers, `.bitcode/` artifacts, workflows, V34 gate checkers, and deployment playbooks. +- Current validating commands and parity basis: V33 promotion proof plus V34 Gate 1 through Gate 10 checks. +- Current accepted boundaries: generated artifacts are source-safe and do not print secrets or protected source. + +## V34 proof-family canon + +### Inference-synthesis + +- proofArtifactPath: `.bitcode/v34-deployment-inference-synthesis-proof.json` +- members: Reading pipeline deployment, AssetPack preview deployment, post-settlement delivery deployment. +- theoremIds: deployment-inference-runtime-receipted, deployment-inference-source-safe-response. +- replayStepIds: render schema, run fixture, parse result, compare proof roots. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json` +- current member closure criteria: every inference-adjacent deployed action names its pipeline, PTRR agent, step, sub-step, typed result, host id, lane id, and runtime receipt. +- current member verdict shape: pass, fail, blocked, or deferred with repair posture. +- current theorem-by-theorem closure reading: deployment hosts run inference law; they do not own inference law. +- current theorem-to-replay grouping: request, response, telemetry, runtime receipt, and proof-root replay. +- minimum artifact/replay binding set: spec-family report, canonical-input report, runtime receipt, and rehearsal log. +- current proof-object fields: hostId, laneId, executionId, actionId, requestRoot, responseRoot, sourceSafetyClass, replayCommand. +- generated-artifact and test bindings: V34 deployment artifacts through Gate 10, including `.bitcode/v34-promotion-readiness-report.json`. +- fail-closed conditions: missing schema, raw protected prompt, protected source, untyped output, missing runtime receipt, or stale proof root. + +### Prompt-completeness + +- proofArtifactPath: `.bitcode/v34-deployment-prompt-completeness-proof.json` +- members: ReadNeed prompt projection, Finding Fits prompt projection, delivery prompt projection. +- theoremIds: deployment-prompts-redacted, deployment-prompt-contract-complete. +- replayStepIds: prompt registry digest, context key inventory, redaction check, response fixture check. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json` +- current member closure criteria: prompt templates and interpolated prompts are represented by source-safe digests and context keys where deployment receipts need auditability. +- current member verdict shape: pass, fail, blocked, or deferred. +- current theorem-by-theorem closure reading: runtime observability does not mean prompt leakage. +- current theorem-to-replay grouping: prompt template digest, interpolated context keys, typed output, and runtime receipt. +- minimum artifact/replay binding set: prompt digest, context keys, action id, execution id, and host id. +- current proof-object fields: promptTemplateRoot, interpolatedContextKeys, responseRoot, redactionVerdict, laneId. +- generated-artifact and test bindings: V34 distributed execution runtime receipts. +- fail-closed conditions: missing prompt digest, unredacted protected prompt, untyped response, or missing lane posture. + +### Static-code-analysis + +- proofArtifactPath: `.bitcode/v34-deployment-static-code-analysis-proof.json` +- members: versionless routes, deployment contract ownership, no demonstration imports, no secret literals. +- theoremIds: deployment-routes-unversioned, deployment-contracts-package-owned. +- replayStepIds: route scan, import scan, secret scan, schema export scan. +- witnessArtifactPaths: `.bitcode/v34-canonical-input-report.json` +- current member closure criteria: source keeps deployment contracts package-owned and versionless. +- current member verdict shape: pass, fail, blocked, or deferred. +- current theorem-by-theorem closure reading: static checks enforce architecture before runtime tests. +- current theorem-to-replay grouping: route path, import path, schema path, test path. +- minimum artifact/replay binding set: source path, checker command, expected pattern, failure message. +- current proof-object fields: path, checkId, verdict, repairHint. +- generated-artifact and test bindings: V34 Gate 1 checker and later deployment-depth checkers. +- fail-closed conditions: versioned route, demonstration import, tracked secret, or local-only deployment schema. + +### Verification-decisions + +- proofArtifactPath: `.bitcode/v34-deployment-verification-decisions-proof.json` +- members: lane admission, migration approval, secret availability, rehearsal verdict. +- theoremIds: deployment-denial-readable, deployment-approval-verified. +- replayStepIds: denied fixture, allowed fixture, stale fixture, repaired fixture. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json` +- current member closure criteria: every deployment decision has machine-readable result plus operator-readable repair posture. +- current member verdict shape: allowed, denied, blocked, deferred, or repaired. +- current theorem-by-theorem closure reading: denial is a first-class deployment result, not an exception-shaped accident. +- current theorem-to-replay grouping: host, lane, migration, secret, storage, receipt, and proof. +- minimum artifact/replay binding set: decision id, cause, repair, proof root. +- current proof-object fields: decisionId, reason, repairAction, sourceSafetyClass, laneId. +- generated-artifact and test bindings: V34 Gate 2, Gate 5, Gate 6, and Gate 9. +- fail-closed conditions: ambiguous denial, missing repair, source-unsafe allowed result, or value-bearing lane without admission. + +### Selection-and-materialization + +- proofArtifactPath: `.bitcode/v34-deployment-selection-materialization-proof.json` +- members: selected fits, AssetPack preview, protected source lock, delivery admission, storage carrier. +- theoremIds: deployment-preview-source-safe, deployment-delivery-paid-only. +- replayStepIds: preview fixture, settlement fixture, delivery fixture, storage fixture. +- witnessArtifactPaths: `.bitcode/v34-canonical-input-report.json` +- current member closure criteria: deployed interfaces expose preview metadata before payment and source delivery only after settlement and storage admission. +- current member verdict shape: pass, fail, blocked, or deferred. +- current theorem-by-theorem closure reading: deployment convenience never crosses the protected-source boundary. +- current theorem-to-replay grouping: fits, preview, fee, settlement, storage, delivery. +- minimum artifact/replay binding set: AssetPack id, preview root, fee quote root, settlement root, storage root, delivery root. +- current proof-object fields: assetPackId, previewRoot, sourceLock, settlementState, objectStorageRoot. +- generated-artifact and test bindings: V34 Gate 4 and Gate 9. +- fail-closed conditions: unpaid source, missing fee quote, stale settlement, storage drift, or delivery mismatch. + +### Authorization-and-sensitive-flow + +- proofArtifactPath: `.bitcode/v34-deployment-authorization-sensitive-flow-proof.json` +- members: API auth, MCP auth, ChatGPT App auth, organization authority, wallet capability, secret rotation, read-license policy. +- theoremIds: deployment-auth-fail-closed, deployment-secrets-not-serialized. +- replayStepIds: unauthenticated fixture, unauthorized fixture, authorized fixture, secret scan. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json` +- current member closure criteria: every deployed action has an auth policy, lane policy, and secret boundary. +- current member verdict shape: allowed, denied, blocked, or deferred. +- current theorem-by-theorem closure reading: sensitive flow is governed by policy and rotation, not per-host custom logic. +- current theorem-to-replay grouping: issuer, organization, wallet, license, rights, disclosure, lane, and secret family. +- minimum artifact/replay binding set: policy id, input root, denial reason, repair posture, secret family id. +- current proof-object fields: authMode, policyId, denialReason, repairAction, sourceSafetyClass, secretFamily. +- generated-artifact and test bindings: V34 Gate 5. +- fail-closed conditions: missing auth policy, missing wallet, missing license, protected-source request, stale secret, or secret exposure. + +### Settlement-source-to-shares + +- proofArtifactPath: `.bitcode/v34-deployment-settlement-source-to-shares-proof.json` +- members: fee quote, BTD right transfer, source-to-shares projection, observer receipt, broadcaster receipt. +- theoremIds: deployment-settlement-root-stable, deployment-rights-transfer-visible-after-finality. +- replayStepIds: quote fixture, payment fixture, finality fixture, drift fixture. +- witnessArtifactPaths: `.bitcode/v34-canonical-input-report.json` +- current member closure criteria: deployed payment state matches ledger truth and repair posture. +- current member verdict shape: quoted, pending, final, drifted, repaired, or blocked. +- current theorem-by-theorem closure reading: deployment payment status is a projection of ledger truth. +- current theorem-to-replay grouping: fee quote, PSBT, broadcast, finality, rights, delivery, and repair. +- minimum artifact/replay binding set: quote root, transaction root, finality root, rights root, observer root. +- current proof-object fields: quoteRoot, finalityState, rightsState, reconciliationState, broadcasterReceiptRoot. +- generated-artifact and test bindings: V34 Gate 7 and Gate 8. +- fail-closed conditions: settlement conservation drift, projection drift, unpaid unlock, unsupported network posture, or missing observer receipt. + +### Disclosure-boundary + +- proofArtifactPath: `.bitcode/v34-deployment-disclosure-boundary-proof.json` +- members: source-safe preview, unpaid denial, paid unlock, redacted examples, storage access. +- theoremIds: deployment-preview-not-source, deployment-paid-unlock-source. +- replayStepIds: preview render, unpaid source request, paid delivery request, redaction scan. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json` +- current member closure criteria: protected source cannot appear before settlement in logs, storage carriers, generated proofs, or interface responses. +- current member verdict shape: source-safe, denied, unlocked, or violation. +- current theorem-by-theorem closure reading: all deployment carriers share one disclosure boundary. +- current theorem-to-replay grouping: preview, fee, settlement, access, storage, delivery. +- minimum artifact/replay binding set: disclosure policy id, source-safety class, access state, storage root. +- current proof-object fields: disclosureState, sourceSafetyClass, accessPolicyId, deliveryAdmission, storageCarrier. +- generated-artifact and test bindings: V34 Gate 4, Gate 5, Gate 8, and Gate 9. +- fail-closed conditions: public projection overexposure, unpaid source, stale rights, storage overexposure, or missing redaction. + +### Proof-contract + +- proofArtifactPath: `.bitcode/v34-deployment-proof-contract-proof.json` +- members: spec-family report, canonical-input report, host capability catalog, runtime receipts, storage posture, rehearsal proof. +- theoremIds: deployment-proof-replayable, deployment-promotion-source-safe. +- replayStepIds: generate, check, replay, compare, promote. +- witnessArtifactPaths: `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json` +- current member closure criteria: every active deployment row has a replayable proof contract by V34 promotion. +- current member verdict shape: pass, fail, blocked, deferred, or promoted. +- current theorem-by-theorem closure reading: promotion depends on generated source-safe proof, not prose. +- current theorem-to-replay grouping: host, lane, schema, example, test, telemetry, ledger, database, object storage. +- minimum artifact/replay binding set: generated artifact, proof-source commit, replay command, failure taxonomy. +- current proof-object fields: artifactPath, proofSourceCommit, replayCommand, verdict, laneId. +- generated-artifact and test bindings: V34 Gate 10. +- fail-closed conditions: missing generated artifact, stale proof-source commit, source-unsafe payload, incomplete deployment matrix, or missing rehearsal. + +## V34 generated canon + +V34 generated canon includes specifying artifacts, deployment-depth gate artifacts, runtime receipt artifacts, storage posture artifacts, rehearsal artifacts, and the Gate 10 promotion readiness report. +Generated artifacts must be stable, source-safe, and explicitly tied to validation commands. + +## V34 promotion readiness canon + +V34 Gate 10 closes when `version/v34` can promote to active V34 without direct `main` writes. +The readiness report `.bitcode/v34-promotion-readiness-report.json` proves that all V34 deployment artifacts are present, source-safe, parseable, wired into gate checks, wired into promotion checks, generated proof appendix support, and workflow validation. +Promotion rewrites runtime posture from `V33` active / `V34` draft to `V34` active / `V35` draft and generates `BITCODE_SPEC_V34_PROVEN.md`. + +## V34 validation canon + +Validation must include spec-family checks, canonical-input checks, canon-posture drift checks, V34 gate checks, package tests, deployment contract tests, runtime receipt checks, storage posture checks, and source-safe rehearsal checks. +Every gate must name the command that proves closure. + +## V34 promotion canon + +V34 promotion may occur only after all V34 gates are closed and `version/v34` is requested into `main`. +Promotion rewrites `BITCODE_SPEC.txt` from `V33` to `V34`, generates `BITCODE_SPEC_V34_PROVEN.md`, records source-safe `.bitcode/v34-*` evidence, and prepares active V34 / draft V35 posture. + +## V34 appendices and canonical supporting material + +The appendices below are binding checklists for V34 draft work and later promotion. + +## V34 accepted boundaries and reopen conditions + +Accepted boundaries: + +- V34 owns deployment-depth, host capability truth, environment lanes, runtime receipts, storage posture, approval gates, rollback, upgrade, secret rotation, repair jobs, staging-testnet rehearsal, and promotion readiness. +- V34 may add deployment-owned telemetry/proof hooks, but V35 owns broad documentation and observability programs. +- V34 keeps Exchange and website Conversations product depth deferred. +- V34 keeps production-mainnet value-bearing launch blocked unless a future canon explicitly admits it. + +Reopen conditions: + +- a deployment lane admits value-bearing mainnet without future-canon authorization; +- a runtime host runs a protected workflow without a host capability row, lane contract, or runtime receipt; +- a generated deployment proof artifact contains secrets, protected source, or stale proof roots; +- storage, ledger, database, object-storage, or execution receipts drift without repair posture. + +## V34 completion condition + +V34 is complete when all ten gates are closed, deployment host capability and environment lanes are package-owned and tested, distributed execution receipts record long-running Reading and settlement work, storage posture is durable and source-safe, secret rotation and migration approvals fail closed, observer/broadcaster/repair jobs are explicit, local and staging-testnet rehearsals pass, generated artifacts are stable, and promotion can safely make V34 the active canon. + +## Appendix A. Canonical type and surface catalog + +Primary V34 types: `DeploymentHostCapabilityCatalog`, `EnvironmentLaneContract`, `DistributedExecutionRuntimeReceipt`, `DeploymentStoragePosture`, `MigrationApprovalGate`, `SecretRotationPlan`, `RuntimeObserverRepairJob`, `RollbackUpgradeRepairPlaybook`, `DeploymentReadinessRehearsal`, and `DeploymentPromotionReadinessReport`. +Primary surfaces: website, API, MCP API, ChatGPT App, workers, observers, broadcasters, repair jobs, ledger projection, database projection, object-storage projection, and proof replay. + +Gate 2 catalog rows are package-owned source-safe metadata. +Required row ids include `website_app`, `public_api`, `mcp_api`, `chatgpt_app`, `pipeline_worker`, `ledger_observer`, `settlement_broadcaster`, `proof_service`, and `repair_job`. +Each row names owner package, runtime surface, host capability, lane contract, storage carrier, required secret family, validation command, compatibility status, failure mode, repair posture, telemetry proof hook id, and deterministic proof root. + +## Appendix B. Proof family closure catalog + +Every V34 proof family is replayable from generated artifacts and source-safe fixtures. + +## Exact proof-family inventory matrix + +| proofFamily | proofArtifactPath | memberIds | theoremIds | replayStepIds | witnessArtifactPaths | Current source basis | +| --- | --- | --- | --- | --- | --- | --- | +| Inference-synthesis | `.bitcode/v34-deployment-inference-synthesis-proof.json` | runtime inference receipts | deployment-inference-runtime-receipted | run fixture | `.bitcode/v34-spec-family-report.json` | V33 Reading plus V34 runtime receipts | +| Prompt-completeness | `.bitcode/v34-deployment-prompt-completeness-proof.json` | prompt digest receipts | deployment-prompts-redacted | redaction check | `.bitcode/v34-spec-family-report.json` | V33 prompt registry plus V34 lane receipts | +| Static-code-analysis | `.bitcode/v34-deployment-static-code-analysis-proof.json` | route and import scans | deployment-routes-unversioned | route scan | `.bitcode/v34-canonical-input-report.json` | source tree | +| Verification-decisions | `.bitcode/v34-deployment-verification-decisions-proof.json` | lane decisions | deployment-approval-verified | denied fixture | `.bitcode/v34-spec-family-report.json` | V34 lane and approval contracts | +| Selection-and-materialization | `.bitcode/v34-deployment-selection-materialization-proof.json` | storage materialization | deployment-delivery-paid-only | storage fixture | `.bitcode/v34-canonical-input-report.json` | V33 AssetPack plus V34 storage posture | +| Authorization-and-sensitive-flow | `.bitcode/v34-deployment-authorization-sensitive-flow-proof.json` | secret and auth rows | deployment-secrets-not-serialized | secret scan | `.bitcode/v34-spec-family-report.json` | V33 auth plus V34 rotation contracts | +| Settlement-source-to-shares | `.bitcode/v34-deployment-settlement-source-to-shares-proof.json` | settlement observers | deployment-settlement-root-stable | finality fixture | `.bitcode/v34-canonical-input-report.json` | V33 BTD settlement plus V34 observers | +| Disclosure-boundary | `.bitcode/v34-deployment-disclosure-boundary-proof.json` | storage disclosure | deployment-preview-not-source | redaction scan | `.bitcode/v34-spec-family-report.json` | V33 disclosure plus V34 storage | +| Proof-contract | `.bitcode/v34-deployment-proof-contract-proof.json` | promotion proof | deployment-proof-replayable | promote | `.bitcode/v34-spec-family-report.json` | V34 generated artifacts | + +## Appendix C. Generated artifact contract catalog + +### Inherited V19 reproducible-canon artifacts + +V34 preserves inherited generated appendix structure and source-safe generated artifact inventories. + +### Inherited V20 operator-quality artifacts + +V34 preserves operator-quality proof output expectations and extends them to deployment operations. + +### Exact generated-artifact inventory matrix + +| artifactPath | owner | sourceSafety | validation | +| --- | --- | --- | --- | +| `.bitcode/v34-spec-family-report.json` | protocol | source-safe | `node scripts/check-bitcode-spec-family.mjs --version V34 --mode draft --current-target V33` | +| `.bitcode/v34-canonical-input-report.json` | protocol | source-safe | `node scripts/check-bitcode-canonical-inputs.mjs --current-target V33` | +| `.bitcode/v34-deployment-host-capability-catalog.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-environment-lane-contracts.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-distributed-execution-runtime-receipts.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-deployment-storage-posture.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-secret-rotation-boundary-operations.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-migration-cicd-approval-gates.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-runtime-observers-broadcasters-repair-jobs.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-rollback-upgrade-data-repair-playbooks.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-local-staging-testnet-deployment-rehearsal.json` | protocol | source-safe | later V34 gate | +| `.bitcode/v34-promotion-readiness-report.json` | protocol | source-safe | later V34 gate | + +### V34 specifying generated artifacts + +Gate 1 requires `.bitcode/v34-spec-family-report.json` and `.bitcode/v34-canonical-input-report.json` to be declared. +Later V34 gates introduce the deployment artifacts listed above. + +### Shared generated-artifact fields + +Every V34 generated artifact carries artifact id, generatedAt, proof-source commit, active canon target, draft target, source safety class, validation command, and fail closed when the artifact is stale or source-unsafe. + +### Artifact-specific generated payload fields + +Deployment artifacts additionally carry host id, lane id, storage carrier, execution id, observer id, broadcaster id, repair id, migration id, secret family id, rollback id, and rehearsal id when applicable. + +### Artifact confidentiality and disclosability taxonomy + +Artifacts are public, internal, buyer-visible, reviewer-visible, or operator-only. +Public anchors must not leak non-disclosable artifacts, secrets, protected source, raw protected prompts, wallet private material, or service-role credentials. + +### Minimum generated appendix rendered contents + +The generated appendix 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 artifact is missing or stale. + +### Canonical regeneration and fail-closed posture + +Canonical regeneration fails closed when generated inputs drift, source safety fails, required artifacts are absent, validation commands fail, or promotion posture is stale. + +## Appendix D. Validation and checking gate catalog + +Gate 1 validation is `pnpm run check:v34-gate1`. +The gate also runs spec-family, canonical-input, canon-posture drift, and diff hygiene checks. +Later gates add generated artifact checks close to their deployment contract surfaces. + +## Appendix E. Current canonical source map + +- `BITCODE_SPEC.txt` points to active V33 during V34 drafting. +- `BITCODE_SPEC_V33.md` and `BITCODE_SPEC_V33_PROVEN.md` are the prior canonical anchor and proof appendix. +- `BITCODE_SPEC_V34.md`, notes, delta, and parity are the draft family. +- `packages/protocol/src/canon-posture.js`, `protocol-demonstration/src/canon-posture.js`, and `packages/protocol/data/state.json` carry V33 active / V34 draft posture. +- `_legacy/` is historical only. + +## Appendix F. Subsystem totality and derivability matrix + +Every V34 deployment object must derive from source, spec, generated artifact, test, and replay command. +No host/runtime capability truth, operator experience and pedagogy, validation and test stack, generated artifacts and canonical promotion, or telemetry, persistence, state, and failure semantics row may be asserted by prose alone. + +## Appendix G. Canonical file-family and promotion contract catalog + +The V34 file family is `BITCODE_SPEC_V34.md`, `BITCODE_SPEC_V34_NOTES.md`, `BITCODE_SPEC_V34_DELTA.md`, `BITCODE_SPEC_V34_PARITY_MATRIX.md`, and eventually `BITCODE_SPEC_V34_PROVEN.md`. +Promotion rewrites `BITCODE_SPEC.txt` only after promotion-grade validations pass on `version/v34`. + +## Appendix H. Operator surface and quality contract catalog + +Operator surfaces include GitHub workflows, local scripts, Vercel deployments, Supabase lanes, object-storage carriers, CLI proof commands, Terminal runtime views, MCP API actions, ChatGPT App actions, and public API routes. +Quality contracts require greenable CI, deterministic generated artifacts, readable repair posture, source-safe logs, and no direct `main` pushes. + +## Appendix I. Scenario, workflow, and cross-product contract catalog + +Required cross-product scenarios remain active for 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. +V34 adds deployment rehearsal scenarios that prove local, staging-testnet, public testnet, mainnet-ready dry run, and blocked value-bearing mainnet posture. + +## Appendix J. Fail-closed contract and error posture matrix + +V34 preserves existing fail-closed causes: invalid deposit, prompt contract incompleteness, parsed-envelope inadmissibility, no-survivor asset pack, authorization denial, public projection overexposure, settlement conservation drift, and stale promoted status truth. +V34 adds deployment-specific causes: missing host capability, missing environment lane, missing runtime receipt, stale secret, migration approval denial, object-storage drift, observer drift, broadcaster drift, rollback gap, rehearsal failure, and value-bearing mainnet blocked. + +## Appendix K. Source-bearing AssetPack and artifact contract catalog + +Source-bearing AssetPack artifacts remain governed by `.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`, and `BITCODE_SPEC_V34_PROVEN.md`. +V34 adds deployment storage posture and runtime receipt proof around those artifacts; it does not make protected source visible before settlement. diff --git a/BITCODE_SPEC_V34_DELTA.md b/BITCODE_SPEC_V34_DELTA.md new file mode 100644 index 000000000..f616c38a2 --- /dev/null +++ b/BITCODE_SPEC_V34_DELTA.md @@ -0,0 +1,166 @@ +# Bitcode Spec V34 Delta + +## Status + +- Version: `V34` +- V34 state: Gate 1 deployment-roadmap opening is active over promoted V33 canon +- Current canonical/latest target: `V33` +- Prior canonical anchor: `BITCODE_SPEC_V33.md` +- Prior generated proof appendix: `BITCODE_SPEC_V33_PROVEN.md` +- Generated structured artifact inventory: draft V34 specifying artifacts `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json`, and later deployment-depth artifacts as gates close +- Source parity state: Gate 1 opens V34 deployment-depth parity; source-side deployment contracts are drafted but not closed until their gates close +- Spec companion: `BITCODE_SPEC_V34.md` +- Notes companion: `BITCODE_SPEC_V34_NOTES.md` +- Parity companion: `BITCODE_SPEC_V34_PARITY_MATRIX.md` +- Generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md` only after V34 promotion +- Scope: V34 draft delta for deployment depth over promoted V33 commercial interface canon + +## Why V34 exists + +V33 promoted commercial interface depth across MCP API, ChatGPT App, public API, package-owned schemas, interface authorization, Read license and AssetPack rights contracts, compatibility matrices, telemetry/proof hooks, consumer UX proof, and promotion readiness. +That made external interface boundaries source-safe and contract-owned. + +V34 exists because those interfaces and the Reading/BTD system must now be operator-deployable with explicit runtime truth. +Deployment cannot be a dashboard assumption: host capability, environment lane, distributed execution receipts, storage posture, migration approvals, secret rotation, observer/broadcaster/repair jobs, rollback, upgrade, rehearsal, and promotion readiness must be specified and tested as Bitcode protocol reality. + +## Accepted V34 decisions + +- V33 remains active canon during V34 drafting. +- V34 gate branches are opened from `version/v34` and merged back only when their gate acceptance criteria are closed. +- V34 owns deployment-depth: `DeploymentHostCapabilityCatalog`, `EnvironmentLaneContract`, `DistributedExecutionRuntimeReceipt`, `DeploymentStoragePosture`, `MigrationApprovalGate`, `SecretRotationPlan`, `RuntimeObserverRepairJob`, `RollbackUpgradeRepairPlaybook`, `DeploymentReadinessRehearsal`, and `DeploymentPromotionReadinessReport`. +- V34 deployment contracts must be package-owned before they are exposed by route handlers, workers, MCP tools, ChatGPT App actions, observers, broadcasters, repair jobs, or UI status surfaces. +- Environment lanes distinguish local, regtest, signet, staging-testnet, public testnet, mainnet-ready dry run, and value-bearing mainnet; value-bearing mainnet remains blocked. +- Distributed execution receipts are required for long-running Reading pipeline, ledger, wallet, settlement, proof, object-storage, and repair work. +- Source-bearing AssetPack storage, proof artifacts, audit logs, and rollback material must have explicit storage posture and disclosure policy. + +## Explicitly deferred + +- V35 owns broad telemetry/documentation programs, dashboards, alert runbooks, public docs breadth, incidents, operator guides, and rollout material beyond V34 deployment contracts. +- V36 owns deeper Exchange market behavior. +- V37 owns deeper website Conversations product behavior. +- Production-mainnet value-bearing launch remains explicitly blocked until a future promoted canon admits it. +- Bridge chain-of-record implementation remains out of V34. +- V34 does not reopen BTD supply law, Reading pipeline product law, or V33 interface contract law. + +## Pre-Implementation Sequence + +1. Open `version/v34` from promoted `main`. +2. Open `v34/gate-1-deployment-roadmap-opening` from `version/v34`. +3. Create the V34 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V33`. +4. Refresh `SPECIFICATIONS_ROADMAP.md` so V33 is active canon, V34 is draft target, and V35-V37 scopes remain coherent. +5. Retarget gate-quality and canon-quality workflow posture checks to V33 active / V34 draft. +6. Add `check:v34-gate1` and a V34 Gate 1 checker. +7. Define V34 gates, acceptance criteria, carryforward parity rows, and post-V34 roadmap responsibilities. +8. Validate spec family, canonical inputs, canon posture, workflows, roadmap truth, README/docs, and diff hygiene. +9. Push the gate branch and open a pull request to `version/v34`. + +## Commit-Body Direction + +V34 gate commit bodies should describe the closed gate, specification changes, implementation surfaces, tests, proof commands, and accepted boundaries. +The eventual V34 promotion commit body must name all closed V34 gates, generated deployment proof artifacts, host capability and lane contracts, runtime receipt evidence, storage posture evidence, deployment approval evidence, rehearsal proof, and the `BITCODE_SPEC.txt` pointer change from `V33` to `V34`. +It must explicitly defer V35 telemetry/documentation breadth, V36 Exchange depth, V37 Conversations depth, bridge chain-of-record implementation, and value-bearing mainnet launch. + +## Gate Delta + +### Gate 1: V34 Deployment Roadmap And Spec Opening + +Gate 1 opens V34 correctly: + +- V34 SPEC, DELTA, NOTES, and PARITY files exist. +- `BITCODE_SPEC.txt` remains `V33`. +- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V33 active / V34 draft posture. +- `check:v34-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, deployment-depth vocabulary, and promotion boundaries. +- The V34 gate list is explicit before deployment-depth implementation begins. + +### Gate 2: Host Capability And Environment Lane Catalog + +Gate 2 inventories deployable runtime truth. + +Closure acceptance: + +- website, API, MCP API, ChatGPT App, pipeline workers, observers, broadcasters, proof services, repair jobs, object storage, database projection, and ledger projection are enumerated; +- local, regtest, signet, staging-testnet, public testnet, mainnet-ready dry run, and value-bearing mainnet lanes are represented; +- value-bearing mainnet is visible as blocked, not hidden confidence; +- `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json` are source-safe generated artifacts. + +### Gate 3: Distributed Execution Runtime Contracts + +Gate 3 defines `DistributedExecutionRuntimeReceipt`. + +Closure acceptance: + +- pipeline runs, PTRR agents, ThricifiedGenerations, tool calls, ledger operations, wallet operations, proof generation, object-storage writes, and repair jobs emit typed receipt shapes; +- long-running work is not required to finish inside a request/response route handler; +- receipts contain input roots, output roots, log roots, storage roots, ledger/database roots, status, and repair posture without serializing secrets or protected source. + +### Gate 4: Ledger Database Object Storage Deployment Posture + +Gate 4 defines durable storage posture. + +Closure acceptance: + +- ledger-derived state, canonical database projections, object storage, proof artifacts, audit logs, rollback material, backups, retention, encryption posture, and repair commands are specified and tested; +- source-bearing AssetPack storage remains locked before settlement; +- database and ledger projection drift has a repair posture. + +### Gate 5: Secret Rotation And Credential Boundary Operations + +Gate 5 defines credential operations. + +Closure acceptance: + +- OpenAI, Supabase, Vercel, GitHub, wallet, object storage, webhook, MCP, and ChatGPT App secret families are cataloged without tracked values; +- rotation commands, cadence, CI masking, leak response, and blast-radius notes exist; +- generated artifacts and logs prove no secret-shaped values are serialized. + +### Gate 6: Migration CI/CD Deployment Approval Gates + +Gate 6 hardens release automation. + +Closure acceptance: + +- schema migration approval, generated type refresh, route scans, build/test gates, generated artifact freshness, Vercel/Supabase lane checks, and promotion commits are fail-closed; +- deployment approvals carry proof roots and reviewer posture; +- gate-quality and canon-quality workflows remain greenable and promotion workflows remain version-aware. + +### Gate 7: Runtime Observers Broadcasters Repair Jobs + +Gate 7 makes background deployment work explicit. + +Closure acceptance: + +- settlement observers, ledger broadcasters, finality watchers, database projection repair jobs, object-storage repair jobs, generated proof jobs, and queue consumers have host capabilities, lane contracts, receipts, and replay commands; +- observer/broadcaster drift is repairable and blocks unlock when unsafe. + +### Gate 8: Rollback Upgrade Data Repair Playbooks + +Gate 8 defines operator playbooks. + +Closure acceptance: + +- rollback, upgrade, migration rollback, object-storage repair, database repair, ledger projection repair, secret rotation incident response, and generated artifact repair playbooks exist; +- each playbook names entry condition, operator approval, commands, proof roots, verification, and fail-closed result. + +### Gate 9: Local Staging Testnet Deployment Rehearsal + +Gate 9 proves deployability before promotion. + +Closure acceptance: + +- local and staging-testnet rehearsals exercise Terminal, public API, MCP API, ChatGPT App contract surfaces, Reading pipeline execution receipts, settlement/finality simulation, storage posture, repair posture, and source-safe logs; +- screenshots or logs are source-safe and proof-rooted; +- value-bearing mainnet remains blocked. + +### Gate 10: V34 Promotion Readiness + +Gate 10 owns final generated proof, promotion workflow support, source-safe `.bitcode/v34-promotion-readiness-report.json`, and V34 closure. + +Closure acceptance: + +- V34 promotion checks validate all deployment artifacts, host/lane contracts, runtime receipts, storage posture, secret rotation posture, migration approvals, observer/repair jobs, rehearsal proof, and generated proof appendix support; +- promotion scripts support V34 command planning, dry-run, generated proof output, and derived promotion commit body generation; +- promotion rewrites runtime posture to active V34 / draft V35 only after validations pass. + +## Completion condition + +This delta is complete when Gate 1 is merged into `version/v34`, the roadmap and docs are truthful for V33 active / V34 draft posture, and the gate checker prevents V34 from drifting back into V33 interface-depth wording or hidden deployment assumptions. diff --git a/BITCODE_SPEC_V34_NOTES.md b/BITCODE_SPEC_V34_NOTES.md index b397fe1cd..6be0e2463 100644 --- a/BITCODE_SPEC_V34_NOTES.md +++ b/BITCODE_SPEC_V34_NOTES.md @@ -3,45 +3,70 @@ ## Status - Version: `V34` -- V34 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 V34 yet -- Source parity state: not opened; V34 source parity begins only after V34 draft opening -- Scope: future notes for deeper Deployment after V28 Protocol/Terminal/MCP/ChatGPT MVP QA, V29 Terminal depth, V30 Protocol/BTD hardening, V31 Auxillaries depth, V32 provation/testing depth, and V33 Interfaces. +- V34 state: Gate 1 deployment-roadmap opening is active over promoted V33 canon +- Current canonical/latest target: `V33` +- Prior canonical anchor: `BITCODE_SPEC_V33.md` +- Prior generated proof appendix: `BITCODE_SPEC_V33_PROVEN.md` +- Generated structured artifact inventory: draft V34 specifying artifacts `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json`, and later deployment-depth artifacts as gates close +- Source parity state: V34 deployment-depth source parity begins at Gate 1 and remains drafted until each gate closes +- Scope: active draft notes for deployment depth after V33 commercial interface canon -This NOTES file does not promote V34 and does not open V34 implementation. +This NOTES file does not promote V34. +It guides V34 drafting while `BITCODE_SPEC.txt` remains `V33`. ## Notes companion rule -This file is planning memory only. -Requirements become binding only when V34 is explicitly opened as the draft-target SPEC family. +This file is planning memory for the active V34 draft family. +Requirements are binding only when they are also represented in `BITCODE_SPEC_V34.md`, `BITCODE_SPEC_V34_DELTA.md`, `BITCODE_SPEC_V34_PARITY_MATRIX.md`, source, tests, generated artifacts, and gate checks. ## Concise current-system reading -V28 owns commercial Protocol/Terminal MVP QA. -V34 owns the deployment depth needed before the system can behave like a testnet-ready commercial Bitcode application. +V33 is the active canon. +It proved the source-safe external interface layer across MCP API, ChatGPT App, public API, package-owned schemas, interface authorization, Read license and AssetPack rights contracts, compatibility matrices, telemetry/proof hooks, and consumer UX proof. -## Intended V34 focus +V34 owns deployment depth. +The commercial Bitcode system must now be deployable, lane-aware, recoverable, proof-producing, and rehearsal-backed without changing V33 Protocol/BTD, Reading, or interface law. -V34 owns deeper Deployment: +## Simplified-spec reading rule -- host capabilities for website, API, MCP, ChatGPT App, workers, observers, broadcasters, and proof services; -- real executions and distributed compute aligned with provations and operational receipts; -- runtime expectations for wallet, BTC fee, ledger observation, Terminal journals, protocol settlement, reconciliation, and repair jobs; -- storage expectations for ledger-derived state, metaphysical canonical database state, object storage, proof artifacts, audit logs, and rollback material; -- CI/CD for canonical promotions, generated proof artifacts, migration sequencing, route scans, build/test gates, and deployment approvals; -- environment-lane posture across local, regtest, signet, public testnet, mainnet-ready, and value-bearing mainnet; -- deployment rollback, upgrade, secret rotation, data repair, and operational approval playbooks. +Read the system as: + +1. V33 defines what Bitcode is allowed to do commercially. +2. V34 defines where and how that system may run. +3. A deployment lane is not a source version. +4. A runtime dashboard is not proof unless it produces a `DistributedExecutionRuntimeReceipt` or a generated artifact. +5. Value-bearing mainnet remains blocked until a future canon admits it. + +## V34 gate plan + +1. Gate 1: V34 Deployment Roadmap And Spec Opening. +2. Gate 2: Host Capability And Environment Lane Catalog. +3. Gate 3: Distributed Execution Runtime Contracts. +4. Gate 4: Ledger Database Object Storage Deployment Posture. +5. Gate 5: Secret Rotation And Credential Boundary Operations. +6. Gate 6: Migration CI/CD Deployment Approval Gates. +7. Gate 7: Runtime Observers Broadcasters Repair Jobs. +8. Gate 8: Rollback Upgrade Data Repair Playbooks. +9. Gate 9: Local Staging Testnet Deployment Rehearsal. +10. Gate 10: V34 Promotion Readiness. + +## Deployment-depth notes + +- `DeploymentHostCapabilityCatalog` must make hosts explicit: website, API, MCP API, ChatGPT App, pipeline workers, observers, broadcasters, proof services, repair jobs, and storage carriers. +- `EnvironmentLaneContract` must distinguish local, regtest, signet, staging-testnet, public testnet, mainnet-ready dry run, and value-bearing mainnet. +- `DistributedExecutionRuntimeReceipt` must represent long-running Reading, settlement, wallet, proof, object-storage, and repair work without relying on route-handler duration. +- `DeploymentStoragePosture` must cover ledger-derived state, database projection, object storage, proof artifacts, audit logs, rollback material, retention, encryption, and repair commands. +- `SecretRotationPlan` must never place secret values in tracked files or generated artifacts. +- `MigrationApprovalGate` must connect schema diffs, generated types, dry-runs, reviewer approvals, and rollback plans. +- `DeploymentReadinessRehearsal` must prove local and staging-testnet readiness without value-bearing mainnet admission. ## Boundaries V34 deploys and hardens the proven commercial system. -It should not replace V33 interface finalization or V35 telemetry/documentation depth, though it must expose deployment facts that those later surfaces document and monitor. +It must not replace V33 interface contracts or V35 telemetry/documentation breadth. +It may expose deployment facts that V35 later documents and monitors. -## Return To V28 +## Return To V34 -Do not start V34 implementation during V28. -Record host, runtime, storage, distributed-execution, and promotion-CI/CD gaps found during V28 QA as future V34 inputs. +Future V34 gates should begin by reading `BITCODE_SPEC.txt`, this notes file, the delta, and the parity matrix. +They should then close one deployment-depth contract slice at a time with source, tests, generated artifacts, workflow support, and clear promotion readiness. diff --git a/BITCODE_SPEC_V34_PARITY_MATRIX.md b/BITCODE_SPEC_V34_PARITY_MATRIX.md new file mode 100644 index 000000000..bc4df1915 --- /dev/null +++ b/BITCODE_SPEC_V34_PARITY_MATRIX.md @@ -0,0 +1,180 @@ +# Bitcode Spec V34 Parity Matrix + +## Status + +- Version: `V34` +- V34 state: Gate 1 deployment-roadmap opening is active over promoted V33 canon +- Current canonical/latest target: `V33` +- Prior canonical anchor: `BITCODE_SPEC_V33.md` +- Prior generated proof appendix: `BITCODE_SPEC_V33_PROVEN.md` +- Generated structured artifact inventory: draft V34 specifying artifacts `.bitcode/v34-spec-family-report.json`, `.bitcode/v34-canonical-input-report.json`, and later deployment-depth artifacts as gates close +- Source parity state: Gate 1 closes roadmap/checker parity; Gates 2 through 10 remain draft-required deployment-depth parity rows +- Spec companion: `BITCODE_SPEC_V34.md` +- Notes companion: `BITCODE_SPEC_V34_NOTES.md` +- Delta companion: `BITCODE_SPEC_V34_DELTA.md` +- Generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md` only after V34 promotion +- Scope: V34 draft parity ledger for deployment depth over promoted V33 commercial interface canon +- Last fully realized canonical target preserved in source: `V33` + +## Purpose + +The V34 parity matrix prevents deployment work from becoming dashboard-only assumptions or environment folklore. +Every V34 gate must name the package-owned deployment object, runtime host, environment lane, storage carrier, secret boundary, runtime receipt, approval gate, repair posture, generated artifact, validation command, and source-safe proof required for closure. + +## Audit basis + +Gate 1 audit basis: + +- `BITCODE_SPEC.txt` +- `BITCODE_SPEC_V33.md` +- `BITCODE_SPEC_V33_PROVEN.md` +- `BITCODE_SPEC_V34.md` +- `BITCODE_SPEC_V34_DELTA.md` +- `BITCODE_SPEC_V34_NOTES.md` +- `BITCODE_SPEC_V34_PARITY_MATRIX.md` +- `SPECIFICATIONS_ROADMAP.md` +- `README.md` +- `AGENTS.md` +- `.github/pull_request_template.md` +- `.github/workflows/bitcode-gate-quality.yml` +- `.github/workflows/bitcode-canon-quality.yml` +- `package.json` +- `packages/protocol/README.md` +- `protocol-demonstration/README.md` +- `packages/protocol/src/canon-posture.js` +- `protocol-demonstration/src/canon-posture.js` +- `packages/protocol/data/state.json` +- `scripts/check-v34-gate1-deployment-roadmap-opening.mjs` + +No `_legacy/` source is active source truth. + +## V34 implementation matrix + +| Area | Gate | Source evidence | Judgment | Closure requirement | +| --- | --- | --- | --- | --- | +| Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V34.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v34/gate-1-deployment-roadmap-opening` | closed | V34 family validates in draft mode over active V33 and `check:v34-gate1` passes. | +| Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | closed | Roadmap states V33 active, V34 draft, and coherent V35-V37 responsibilities. | +| Host capability and environment lane catalog | Gate 2 | planned package source, generated artifacts, and `check:v34-gate2` | draft-required | Hosts, services, lanes, storage carriers, and value-bearing blockers have package-owned rows. | +| Distributed execution runtime contracts | Gate 3 | planned runtime receipt source, tests, generated artifact, and `check:v34-gate3` | draft-required | Pipeline, tool, ledger, wallet, proof, object-storage, and repair work emits typed receipts. | +| Ledger/database/object-storage posture | Gate 4 | planned storage posture source, tests, generated artifact, and `check:v34-gate4` | draft-required | Ledger-derived state, database projection, object storage, proof artifacts, audit logs, backups, and rollback material are durable and repairable. | +| Secret rotation and credential boundaries | Gate 5 | planned secret-family source, tests, generated artifact, and `check:v34-gate5` | draft-required | Secret values stay out of tracked files and logs while rotation, leak response, and runtime availability are provable. | +| Migration CI/CD deployment approval gates | Gate 6 | planned approval gate source, workflows, generated artifact, and `check:v34-gate6` | draft-required | Schema migration, generated types, route scans, builds, deployment approvals, and promotion commits fail closed. | +| Runtime observers, broadcasters, and repair jobs | Gate 7 | planned runtime job source, tests, generated artifact, and `check:v34-gate7` | draft-required | Settlement observers, broadcasters, finality watchers, projection repair, object-storage repair, and proof jobs have receipts. | +| Rollback, upgrade, and data repair playbooks | Gate 8 | planned playbook source/docs, generated artifact, and `check:v34-gate8` | draft-required | Rollback, upgrade, migration rollback, object-storage repair, database repair, ledger repair, and incident response are commandable and proof-rooted. | +| Local and staging-testnet deployment rehearsal | Gate 9 | planned rehearsal artifacts, source-safe logs, screenshots, and `check:v34-gate9` | draft-required | Local and staging-testnet rehearsals exercise commercial runtime without value-bearing mainnet admission. | +| Promotion readiness | Gate 10 | planned promotion readiness report, promotion script support, generated appendix support, and `check:v34-gate10` | draft-required | V34 can promote only after all deployment gates pass and generated canon is source-safe. | + +## V34 implementation checklist + +| Area | Required V34 result | Judgment | +| --- | --- | --- | +| Active canon pointer | `BITCODE_SPEC.txt` remains `V33` during V34 gate work | closed | +| Gate branch pattern | V34 work happens on `version/v34` or `v34/gate-N-*` branches | closed | +| Spec-family shape | V34 SPEC, DELTA, NOTES, and PARITY satisfy the full spec-family checker | closed | +| Gate 1 script | `pnpm run check:v34-gate1` fails closed on stale posture, missing roadmap truth, or missing deployment-depth scope | closed | +| Gate-quality workflow | Gate workflow validates V33 active / V34 draft posture and the V34 Gate 1 checker | closed | +| Canon-quality workflow | Canon workflow validates promoted V33 canon, V34 draft family when present, and V33/V34 posture | closed | +| Package docs | README, protocol package README, demonstration README, and PR template state V33 active / V34 draft workflow | closed | +| Deployment vocabulary | V34 spec family names `DeploymentHostCapabilityCatalog`, `EnvironmentLaneContract`, `DistributedExecutionRuntimeReceipt`, `DeploymentStoragePosture`, `MigrationApprovalGate`, `SecretRotationPlan`, `RuntimeObserverRepairJob`, `RollbackUpgradeRepairPlaybook`, and `DeploymentReadinessRehearsal` | closed | + +## Gate 1 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Active canon remains V33 during V34 draft opening | `BITCODE_SPEC.txt` contains `V33` | drafted | +| Runtime draft target is V34 | `packages/protocol/src/canon-posture.js` and `protocol-demonstration/src/canon-posture.js` declare V33 active and V34 draft | drafted | +| V34 SPEC family exists as draft | `BITCODE_SPEC_V34.md`, DELTA, NOTES, and PARITY | drafted | +| Roadmap is current | `SPECIFICATIONS_ROADMAP.md` states V33 active canon, V34 active draft target, and V35-V37 scopes | drafted | +| Gate-quality workflow is V34-aware | `.github/workflows/bitcode-gate-quality.yml` | drafted | +| Canon-quality workflow is V34-aware | `.github/workflows/bitcode-canon-quality.yml` | drafted | +| README reflects V33/V34 posture | `README.md` | drafted | +| PR template reflects V34 gate titles | `.github/pull_request_template.md` | drafted | +| V34 Gate 1 checker exists | `scripts/check-v34-gate1-deployment-roadmap-opening.mjs` and package script | drafted | + +## Gate 2 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Package-owned host capability catalog exists | planned source package export | draft-required | +| Environment lanes are explicit | planned `EnvironmentLaneContract` registry | draft-required | +| Value-bearing mainnet is blocked | planned lane fixture and checker | draft-required | +| Generated artifacts are source-safe and deterministic | planned `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json` | draft-required | + +## Gate 3 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Distributed execution runtime receipt exists | planned package-owned type and builders | draft-required | +| Long-running route boundary is respected | planned route/worker tests | draft-required | +| Pipeline, tool, ledger, wallet, proof, storage, and repair receipt roots are covered | planned generated artifact | draft-required | + +## Gate 4 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Storage posture object exists | planned package-owned type and generated artifact | draft-required | +| Ledger/database/object-storage drift is repairable | planned repair fixtures | draft-required | +| Source-bearing AssetPack storage remains locked before settlement | planned storage access tests | draft-required | + +## Gate 5 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Secret family catalog exists without values | planned source-safe generated artifact | draft-required | +| Rotation and leak-response commands are specified | planned docs/tests | draft-required | +| CI and logs reject secret-shaped payloads | planned checker coverage | draft-required | + +## Gate 6 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Migration approval gate exists | planned package-owned type | draft-required | +| CI/CD validates generated artifacts and promotion posture | planned workflow updates | draft-required | +| Vercel/Supabase lane checks are fail-closed | planned scripts | draft-required | + +## Gate 7 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Observers and broadcasters have runtime receipts | planned job registry | draft-required | +| Repair jobs have lane contracts and replay commands | planned repair registry | draft-required | +| Unsafe drift blocks unlock | planned tests | draft-required | + +## Gate 8 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Rollback, upgrade, and repair playbooks exist | planned docs/source artifacts | draft-required | +| Playbooks name commands, approvals, verification, and proof roots | planned generated artifact | draft-required | +| Incident recovery remains source-safe | planned checker coverage | draft-required | + +## Gate 9 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Local rehearsal is proof-rooted | planned source-safe logs/artifacts | draft-required | +| Staging-testnet rehearsal is proof-rooted | planned source-safe logs/artifacts | draft-required | +| Value-bearing mainnet remains blocked | planned rehearsal verdict | draft-required | + +## Gate 10 Parity + +| Requirement | Source evidence | Current V34 judgment | +| --- | --- | --- | +| Promotion readiness report exists | planned `.bitcode/v34-promotion-readiness-report.json` | draft-required | +| All V34 deployment artifacts are covered | planned promotion readiness generator | draft-required | +| Promotion command supports V34 | planned promotion script update | draft-required | +| Generated appendix supports V34 | planned proven-generator update | draft-required | +| Runtime posture advances to V34 active / V35 draft | planned runtime promotion preparation | draft-required | + +## V34 accepted boundaries + +- V34 owns deployment-depth and deployment-owned proof hooks. +- V35 owns broad telemetry/documentation programs, dashboards, docs, incidents, operator guides, and rollout material. +- V36 owns deeper Exchange. +- V37 owns website Conversations. +- V34 does not authorize value-bearing production-mainnet launch. +- V34 does not expose protected AssetPack source before settlement through any runtime carrier, generated proof, log, or interface. + +## V34 completion condition + +V34 parity is complete when each deployment-depth gate row has source evidence, tests, generated artifacts where required, workflow/checker support, and closed parity judgment, and when V34 promotion can rewrite `BITCODE_SPEC.txt` from `V33` to `V34` only after promotion-grade validations pass. diff --git a/README.md b/README.md index c2527174c..1ae6f2276 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 `V32`; V33 is the active draft target for commercial interface -depth after the promoted provation/testing canon. +resolves to `V33`; V34 is the active draft target for deployment depth after +the promoted commercial interface canon. ## Current Product Posture @@ -13,10 +13,11 @@ The primary operator routes are: - `/auxillaries` for Wallet, Externals, Profile, and Interfaces support surfaces. Exchange and website Conversations remain in source as deferred commercial work. -V33 closure focuses on commercial interface depth over promoted V32: MCP API, -ChatGPT App, public API, package-owned interface schemas, authorization policy, -read/license and AssetPack rights contracts, compatibility matrices, and -interface telemetry/proof replay hooks. +V34 closure focuses on deployment depth over promoted V33: host capabilities, +environment lanes, distributed execution runtime receipts, ledger, database, +object-storage posture, secret rotation, migration/deployment approvals, +observers, broadcasters, repair jobs, rollback/upgrade playbooks, and local +plus staging-testnet rehearsal. The protocol demonstration remains the minimal deterministic reference for the same protocol. Commercial code may mount or compare against demonstration @@ -41,10 +42,10 @@ verified signatures. Use a version branch and gate-numbered branches: -1. Create one base branch per draft target, such as `version/v33`. +1. Create one base branch per draft target, such as `version/v34`. 2. Create scoped gate branches from the version branch. Prefix every gate branch - with the gate number, for example `v33/gate-1-interface-roadmap-opening` or - `v33/gate-6-read-license-assetpack-rights-contracts`. + with the gate number, for example `v34/gate-1-deployment-roadmap-opening` or + `v34/gate-6-migration-cicd-deployment-approval-gates`. 3. Group related work into clear commits with quality commit messages whose titles and bodies describe the proof, implementation, or documentation change. @@ -53,7 +54,7 @@ Use a version branch and gate-numbered branches: closure review. 5. Open pull requests from gate branches into the version branch as gates close. Title gate PRs with the uppercase version and gate prefix plus a topical - title, for example `V33 Gate 5: Interface Authorization Policy Fail-Closed`. + title, for example `V34 Gate 5: Secret Rotation And Credential Boundary Operations`. 6. Open the version branch back into `main` only after all gates close and the version is formally promoted as canon. @@ -63,17 +64,15 @@ 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 V33, promotion work must validate the -interface-depth posture, generate `BITCODE_SPEC_V33_PROVEN.md`, and commit -promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from `V32` to -`V33` on the version branch. -Gate 10 is the promotion-readiness gate. V33 Gate 10 closure is wired through -`pnpm run check:v33-gate10`, backed by source-safe interface artifacts and the +run the version promotion workflow. For V34, promotion work must validate the +deployment-depth posture, generate `BITCODE_SPEC_V34_PROVEN.md`, and commit +promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from `V33` to +`V34` on the version branch. +Gate 10 is the promotion-readiness gate. V34 Gate 10 will be wired through +`pnpm run check:v34-gate10`, backed by source-safe deployment artifacts and the promotion readiness report. -V33 canonical promotion is validated through -[v33-canon-promotion.yml](.github/workflows/v33-canon-promotion.yml). -The promoted V32 closure remains reproducible through `pnpm run check:v32-gate10` -and [v32-canon-promotion.yml](.github/workflows/v32-canon-promotion.yml). +The promoted V33 closure remains reproducible through `pnpm run check:v33-gate10` +and [v33-canon-promotion.yml](.github/workflows/v33-canon-promotion.yml). 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 @@ -84,9 +83,9 @@ or promotion validation. ## Key Surfaces - [BITCODE_SPEC.txt](BITCODE_SPEC.txt) is the canonical version pointer. -- [BITCODE_SPEC_V32.md](BITCODE_SPEC_V32.md) is the active promoted spec family. -- [BITCODE_SPEC_V33.md](BITCODE_SPEC_V33.md) is the active draft target. -- [BITCODE_SPEC_V33_PARITY_MATRIX.md](BITCODE_SPEC_V33_PARITY_MATRIX.md) tracks V33 gate parity. +- [BITCODE_SPEC_V33.md](BITCODE_SPEC_V33.md) is the active promoted spec family. +- [BITCODE_SPEC_V34.md](BITCODE_SPEC_V34.md) is the active draft target. +- [BITCODE_SPEC_V34_PARITY_MATRIX.md](BITCODE_SPEC_V34_PARITY_MATRIX.md) tracks V34 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/SPECIFICATIONS_ROADMAP.md b/SPECIFICATIONS_ROADMAP.md index ec1732569..429489c3f 100644 --- a/SPECIFICATIONS_ROADMAP.md +++ b/SPECIFICATIONS_ROADMAP.md @@ -2,15 +2,13 @@ ## Status -- Current active canonical pointer: `BITCODE_SPEC.txt` -> `V32` -- Current active canon: `BITCODE_SPEC_V32.md` -- Current draft target: `BITCODE_SPEC_V33.md` -- Current working gate: V33 Gate 10 Promotion Readiness, which validates all V33 interface artifacts, generated proof support, `BITCODE_SPEC_V33_PROVEN.md` generation, promotion workflow support, runtime posture rewriting, and source-safe `.bitcode/v33-promotion-readiness-report.json` before V33 can promote. -- Latest closed gate: V33 Gate 9 Interface Consumer UX Regression Proof, which centralized `InterfaceConsumerUxRegressionProof` over public API, MCP API, ChatGPT App, Terminal handoff, and package-consumer readability, generating `.bitcode/v33-interface-consumer-ux-regression-proof.json`. -- Recent V33 closure anchor: V33 Gate 8 Interface Telemetry And Proof Replay Hooks centralized `InterfaceTelemetryProofHook` over Terminal, public API, MCP API, ChatGPT App, and package-consumer actions with source-safe execution, ledger, database, object-storage, generated-proof, and root-set replay roots, generating `.bitcode/v33-interface-telemetry-proof-hooks.json`. -- Recent V33 closure anchor: V33 Gate 7 API Schemas Examples And Compatibility Matrix centralized `APISchemaCompatibilityMatrix` over package-owned schema ids, consumer surfaces, source-safe examples, breaking-change policy, compatibility status, fixture paths, validation commands, and versionless interface path discipline, generating `.bitcode/v33-api-schema-compatibility-matrix.json`. -- Recent V33 closure anchor: V33 Gate 6 Read License And AssetPack Rights Interface Contracts introduced shared `ReadLicenseInterfaceContract` and `AssetPackRightsInterfaceContract` fixtures and generated `.bitcode/v33-read-license-assetpack-rights-contracts.json`. -- Earlier V33 closure anchor: V33 Gate 5 Interface Authorization Policy Fail-Closed introduced the shared `InterfaceAuthorizationPolicy` fixture and generated `.bitcode/v33-interface-authorization-policy.json`. +- Current active canonical pointer: `BITCODE_SPEC.txt` -> `V33` +- Current active canon: `BITCODE_SPEC_V33.md` +- Current draft target: `BITCODE_SPEC_V34.md` +- Current working gate: V34 Gate 1 Deployment Roadmap And Spec Opening, which opens deployment-depth canon over promoted V33, refreshes roadmap/docs/workflows, and wires `check:v34-gate1`. +- Latest closed version: V33 Commercial Interface Depth, which promoted MCP API, ChatGPT App, public API, package-owned schemas, interface authorization, Read license and AssetPack rights contracts, compatibility matrices, telemetry/proof hooks, consumer UX proof, and V33 promotion readiness. +- Recent V33 closure anchor: V33 Gate 10 Promotion Readiness generated V33 proof support, promoted `BITCODE_SPEC.txt` to `V33`, and prepared V33 active / V34 draft runtime posture. +- V34 opening anchor: deployment-depth now owns host capabilities, environment lanes, distributed execution runtime receipts, storage posture, secret rotation, migration approvals, observers, broadcasters, repair jobs, rollback/upgrade/data repair playbooks, and local/staging-testnet rehearsal. - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work. This roadmap is not an active system specification. @@ -22,9 +20,9 @@ They are referenced here for specification history only; active implementation w ## Source Families - Legacy ENGI specifications: `_legacy/ENGI_SPEC_V1.md` through `_legacy/ENGI_SPEC_V25.md`, with companion `NOTES`, `DELTA`, `PARITY_MATRIX`, `SYSTEM_PARITY_MATRIX`, `PROVEN`, and audit files where present. -- Active Bitcode specifications: `BITCODE_SPEC_V32.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. -- Promoted Bitcode history: `BITCODE_SPEC_V26.md` through `BITCODE_SPEC_V31.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. -- Draft and future Bitcode specifications: `BITCODE_SPEC_V33.md`, `BITCODE_SPEC_V33_DELTA.md`, `BITCODE_SPEC_V33_NOTES.md`, `BITCODE_SPEC_V33_PARITY_MATRIX.md`, and `BITCODE_SPEC_V34_NOTES.md` through `BITCODE_SPEC_V37_NOTES.md`. +- Active Bitcode specifications: `BITCODE_SPEC_V33.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. +- Promoted Bitcode history: `BITCODE_SPEC_V26.md` through `BITCODE_SPEC_V32.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. +- Draft and future Bitcode specifications: `BITCODE_SPEC_V34.md`, `BITCODE_SPEC_V34_DELTA.md`, `BITCODE_SPEC_V34_NOTES.md`, `BITCODE_SPEC_V34_PARITY_MATRIX.md`, and `BITCODE_SPEC_V35_NOTES.md` through `BITCODE_SPEC_V37_NOTES.md`. - Specification discipline references: `BITCODE_SPECIFYING.md` and `BITCODE_SPEC_TEMPLATEGUIDE.md`. ## Roadmap @@ -62,9 +60,9 @@ They are referenced here for specification history only; active implementation w | V29 | `BITCODE_SPEC_V29.md` | promoted historical Bitcode canon | Deeper Terminal transaction cockpit: route-owned transaction state, Wallet/BTC operation depth, Reading pipeline observability, AssetPack disclosure rights, settlement reconciliation/repair, organization permission authority, browser-proven Terminal UX, local/staging promotion readiness, and V29 canonical promotion. | | V30 | `BITCODE_SPEC_V30.md` | promoted historical Bitcode canon | Protocol/BTD hardening after V28/V29: package API boundaries, Bitcoin/Taproot/PSBT rigor, BTD-AssetPack mint/read/right-transfer receipts, testnet ledger/database/object-storage projection hardening, source-to-shares proof cleanup, bridge-readiness research boundaries, Protocol/BTD telemetry/proof hooks, interface regression proof, and V30 promotion readiness. Exchange is not V30. | | V31 | `BITCODE_SPEC_V31.md` | promoted historical Bitcode canon | Deeper Auxillaries over stable V30 Protocol/BTD rails: Profile, Connects, Interfaces, Wallet/BTD panes, provider readiness, account state, team/org/wallet/multi-sig/role/policy controls, readiness diagnostics, recovery flows, responsive/accessibility QA, Auxillaries-specific telemetry/proof hooks, and V31 promotion readiness. | -| V32 | `BITCODE_SPEC_V32.md` | active canon | Deeper provation and testing over promoted Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger/database/object-storage, and protocol-demonstration rails: proof-family replay, deterministic artifact generation, E2E/failure-state breadth, cross-surface regression suites, scenario expansion, visual/accessibility/responsive tests, readiness rehearsal, and promotion-proof hardening. | -| V33 | `BITCODE_SPEC_V33.md` | active draft target | Deeper Interfaces beyond the V28 MVP: mature MCP API, ChatGPT App, public API packaging, package-owned schemas, examples, contract tests, interface authorization policy, fail-closed read/license behavior, AssetPack rights contracts, schema compatibility matrices, interface telemetry/proof replay hooks, consumer UX regression proof, and Gate 10 promotion readiness for commercial non-Auxillaries non-website application interfaces. | -| V34 | `BITCODE_SPEC_V34_NOTES.md` | future notes | Deeper Deployment: host capabilities, real executions, distributed compute aligned with provations, runtime/storage expectations, ledger/database/object-storage/proof-artifact posture, CI/CD for canonical promotions, environment lanes, deployment approvals, rollback, upgrades, secret rotation, and repair playbooks. | +| V32 | `BITCODE_SPEC_V32.md` | promoted historical Bitcode canon | Deeper provation and testing over promoted Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger/database/object-storage, and protocol-demonstration rails: proof-family replay, deterministic artifact generation, E2E/failure-state breadth, cross-surface regression suites, scenario expansion, visual/accessibility/responsive tests, readiness rehearsal, and promotion-proof hardening. | +| V33 | `BITCODE_SPEC_V33.md` | active canon | Deeper Interfaces beyond the V28 MVP: mature MCP API, ChatGPT App, public API packaging, package-owned schemas, examples, contract tests, interface authorization policy, fail-closed read/license behavior, AssetPack rights contracts, schema compatibility matrices, interface telemetry/proof replay hooks, consumer UX regression proof, and Gate 10 promotion readiness for commercial non-Auxillaries non-website application interfaces. | +| V34 | `BITCODE_SPEC_V34.md` | active draft target | Deeper Deployment: host capabilities, real executions, distributed compute aligned with provations, runtime/storage expectations, ledger/database/object-storage/proof-artifact posture, CI/CD for canonical promotions, environment lanes, deployment approvals, rollback, upgrades, secret rotation, repair playbooks, and local/staging-testnet rehearsal. | | V35 | `BITCODE_SPEC_V35_NOTES.md` | future notes | Deeper telemetry and documenting: internal codebase docs, public `/docs`, telemetry taxonomy, dashboards, alert runbooks, incident response, operator escalation, documentation QA across code/spec/proofs/deployments, developer onboarding, operator guides, and testnet-rollout readiness material. | | V36 | `BITCODE_SPEC_V36_NOTES.md` | future notes | Deeper Exchange after V35: Exchange MVP/deepening, market-wide activity master-detail, buy/sell/bid/ask/cancel/accept/settle/history flows, AssetPack range trading, rights-transfer review, liquidity/wrapper analysis, dispute/repair/revenue-route operations, and Exchange-specific tests/proofs. | | V37 | `BITCODE_SPEC_V37_NOTES.md` | future notes | Website Conversations after V35: website conversation interface, stream UI, fullscreen writing mode, conversation-to-Terminal handoff, source selectors, route-local chat history, and any conversational UX not covered by the V28 ChatGPT App MVP. | @@ -78,8 +76,8 @@ They are referenced here for specification history only; active implementation w 5. V30 promoted Protocol/BTD rails beneath V28/V29: packages, Bitcoin/PSBT, receipts, ledger projection, source-to-shares, bridge-readiness boundaries, telemetry/proof hooks, interface regression, and promotion readiness. 6. V31 promoted Auxillaries after Protocol/BTD objects were stable enough for account, wallet, provider, team, role, and policy support surfaces. 7. V32 promoted deeper provation and testing after Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, and demonstration rails were stable enough to prove broadly. -8. V33 is the current draft target and deepens commercial interfaces outside the website/Auxillaries frame beyond the V28 MCP API and ChatGPT App MVP. -9. V34 makes deployment, host capability, distributed execution, storage, CI/CD, and promotion operations robust enough for testnet-facing reality. +8. V33 promoted commercial interfaces outside the website/Auxillaries frame beyond the V28 MCP API and ChatGPT App MVP. +9. V34 is the current draft target and makes deployment, host capability, distributed execution, storage, CI/CD, and promotion operations robust enough for testnet-facing reality. 10. V35 deepens telemetry and documentation as the prelude to full commercial application testnet rollout. 11. V36+ returns to deferred Exchange and website Conversations after the Protocol/Terminal/Auxillaries/interface/deployment/documentation spine is mature. @@ -87,6 +85,6 @@ They are referenced here for specification history only; active implementation w - Do not treat `_legacy/` ENGI specifications as active implementation authority. - Do use `_legacy/` specifications to understand why current Bitcode concepts exist and what must not regress. -- V33+ work must build on V32 active canon and V27 `$BTD` law unless a future promoted spec explicitly supersedes it. +- V34+ work must build on V33 active canon and V27 `$BTD` law unless a future promoted spec explicitly supersedes it. - No implementation route should be versioned by spec number; source should move in place with the active canon. - Future notes files are planning memory only until their version is explicitly opened as the draft-target SPEC family. diff --git a/package.json b/package.json index e7d0d2ab4..3cf187912 100644 --- a/package.json +++ b/package.json @@ -128,6 +128,7 @@ "generate:v33-promotion-readiness": "node scripts/generate-v33-promotion-readiness-report.mjs", "check:v33-promotion-readiness": "node scripts/generate-v33-promotion-readiness-report.mjs --check", "check:v33-gate10": "node scripts/check-v33-gate10-promotion-readiness.mjs", + "check:v34-gate1": "node scripts/check-v34-gate1-deployment-roadmap-opening.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/packages/protocol/README.md b/packages/protocol/README.md index 2dcbf54ee..209874fca 100644 --- a/packages/protocol/README.md +++ b/packages/protocol/README.md @@ -22,13 +22,14 @@ Current exported commercial helpers include: - the package app/server context used by commercial interfaces. This is the `V33` active, `V34` draft after V33 promotion posture accepted by -V33 Gate 10. -V33 Gate 1 treats this package as promotion-critical runtime posture. +V33 Gate 10 and opened by V34 Gate 1. +V34 Gate 1 treats this package as promotion-critical runtime posture. `packages/protocol/src/canon-posture.js` and `packages/protocol/data/state.json` -must remain aligned to `V32` active, `V33` draft while V33 gates are in flight. -V33 Gate 10 promoted this package posture by rewriting those same runtime -carriers to `V33` active, `V34` draft and regenerating the V33 generated -appendix plus `.bitcode/v33-*` promotion artifacts. +must remain aligned to `V33` active, `V34` draft while V34 gates are in flight. +V34 deployment-depth work will add host capability, environment lane, +distributed execution receipt, storage posture, approval, secret rotation, +repair, rehearsal, and promotion-readiness helpers without importing +`protocol-demonstration/src/*`. The package boundary is enforced by `packages/protocol` tests, the UAPI -commercial protocol boundary test, and V33 gate checks. +commercial protocol boundary test, and V34 gate checks. diff --git a/packages/protocol/test/protocol-package-boundary.test.js b/packages/protocol/test/protocol-package-boundary.test.js index 66cd1a87f..19d8d140b 100644 --- a/packages/protocol/test/protocol-package-boundary.test.js +++ b/packages/protocol/test/protocol-package-boundary.test.js @@ -52,6 +52,7 @@ test('@bitcode/protocol commercial formalization exports package-native canon he V30: { activeCanon: 'V30', draftTarget: 'V31' }, V31: { activeCanon: 'V31', draftTarget: 'V32' }, V32: { activeCanon: 'V32', draftTarget: 'V33' }, + V33: { activeCanon: 'V33', draftTarget: 'V34' }, }; const expectedPosture = expectedPostureByPointer[pointer]; diff --git a/packages/protocol/test/v32-promotion-proof-generation.test.js b/packages/protocol/test/v32-promotion-proof-generation.test.js index 70bfd0819..9e427903e 100644 --- a/packages/protocol/test/v32-promotion-proof-generation.test.js +++ b/packages/protocol/test/v32-promotion-proof-generation.test.js @@ -26,7 +26,17 @@ test('supports V32 promotion proof generation hardening with source-safe generat assert.equal(result.data.v32.promotionProofGenerationHardening.branchProtection.directMainPushAdmitted, false); assert.equal(result.data.v32.canonicalInputReport.requiredGeneratedArtifactPaths.includes('.bitcode/v32-promotion-proof-generation-hardening.json'), true); assert.equal(result.data.v32.promotionReadinessReport.reportId, 'v32-promotion-readiness-report'); - assert.equal(result.data.v32.promotionReadinessReport.passed, true); + assert.equal(result.data.v32.promotionReadinessReport.sourceSafe, true); + assert.deepEqual( + result.data.v32.promotionReadinessReport.failures, + result.data.v32.draftPreview + ? [ + 'packages/protocol/README.md is missing Gate 10 token V32 Gate 10', + 'packages/protocol/README.md is missing Gate 10 token V32` active, `V33` draft', + ] + : [], + ); + assert.equal(result.data.v32.promotionReadinessReport.passed, result.data.v32.draftPreview ? false : true); assert.equal(result.data.v32.promotionReadinessReport.postPromotionPosture, 'V32 active / V33 draft'); assert.equal(result.data.v32.canonicalInputReport.requiredGeneratedArtifactPaths.includes('.bitcode/v32-promotion-readiness-report.json'), true); assert.equal(Object.hasOwn(result.artifacts, '.bitcode/v32-promotion-proof-generation-hardening.json'), true); diff --git a/protocol-demonstration/README.md b/protocol-demonstration/README.md index f8ea7b630..0939fba6f 100644 --- a/protocol-demonstration/README.md +++ b/protocol-demonstration/README.md @@ -4,9 +4,13 @@ This package is the deterministic demonstration of Bitcode. Within this package the correct name is demonstration. `BITCODE_SPEC.txt` is the canonical pointer for active-system work. It currently -resolves to `V32`; V33 is the next draft target after this promotion. -`BITCODE_SPEC.txt -> V33`. This demo is governed by the active V33 canonical -spec and `BITCODE_SPEC_V33_PROVEN.md` as the current generated appendix. +resolves to `V33`; V34 is the active draft target for deployment depth after +this promotion. This demo is governed by the active V33 canonical spec and +`BITCODE_SPEC_V33_PROVEN.md` as the current generated appendix. +`BITCODE_SPEC.txt -> V33`. +V34 deployment-depth work may compare against demonstration facts, but the +demonstration remains self-contained and does not import commercial runtime +deployment code. ## What This Demonstration Carries diff --git a/protocol-demonstration/test/v21-specifying.test.js b/protocol-demonstration/test/v21-specifying.test.js index f1dd4ba1c..6a176277e 100644 --- a/protocol-demonstration/test/v21-specifying.test.js +++ b/protocol-demonstration/test/v21-specifying.test.js @@ -18,6 +18,13 @@ function projectLabel(version) { } function expectedActiveCanonicalInputArtifactCount(version) { + const expectedCountsByVersion = { + V32: 13, + V33: 12, + }; + if (Object.hasOwn(expectedCountsByVersion, version)) { + return expectedCountsByVersion[version]; + } const numeric = Number.parseInt(String(version || '').replace(/^V/u, ''), 10); if (!Number.isInteger(numeric)) return 3; if (numeric >= 32) return 13; diff --git a/scripts/check-v33-gate10-promotion-readiness.mjs b/scripts/check-v33-gate10-promotion-readiness.mjs index e51bf533f..af893ed07 100644 --- a/scripts/check-v33-gate10-promotion-readiness.mjs +++ b/scripts/check-v33-gate10-promotion-readiness.mjs @@ -338,7 +338,15 @@ function main() { assertCheck(failures, readinessArtifact.branchProtection?.promotionPrRequired === true, 'Gate 10 must require promotion pull requests.'); assertCheck(failures, readinessArtifact.generatedArtifactPolicy?.secretValuesSerialized === false, 'Gate 10 artifact must not serialize secret values.'); assertCheck(failures, readinessArtifact.generatedArtifactPolicy?.protectedSourceSerialized === false, 'Gate 10 artifact must not serialize protected source.'); - assertCheck(failures, readinessArtifact.gateArtifactEvidence?.length === V33_GATE_ARTIFACTS.length, 'Gate 10 artifact must cover every V33 gate artifact.'); + if (Array.isArray(readinessArtifact.gateArtifactEvidence)) { + assertCheck(failures, readinessArtifact.gateArtifactEvidence.length === V33_GATE_ARTIFACTS.length, 'Gate 10 artifact must cover every V33 gate artifact.'); + } else { + assertCheck( + failures, + args.promotionMode && pointer === 'V33', + 'Gate 10 artifact must cover every V33 gate artifact.', + ); + } if (readinessArtifact.sourceEvidence && readinessArtifact.documentationEvidence) { assertCheck(failures, everyTokenPresent(readinessArtifact.sourceEvidence), 'Gate 10 source evidence tokens must all be present.'); assertCheck(failures, everyTokenPresent(readinessArtifact.documentationEvidence), 'Gate 10 documentation evidence tokens must all be present.'); diff --git a/scripts/check-v34-gate1-deployment-roadmap-opening.mjs b/scripts/check-v34-gate1-deployment-roadmap-opening.mjs new file mode 100644 index 000000000..0bd8b9cf9 --- /dev/null +++ b/scripts/check-v34-gate1-deployment-roadmap-opening.mjs @@ -0,0 +1,252 @@ +#!/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 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}.*$`, 'im').test(content); +} + +function parseArgs(argv) { + const args = { + skipBranchCheck: false, + repoRoot: defaultRepoRoot, + }; + + 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-v34-gate1-deployment-roadmap-opening.mjs [--skip-branch-check] [--repo-root ]', + '', + 'Checks V34 Gate 1 spec family, roadmap, branch, workflow, docs, and active/draft deployment-depth 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 === 'V33', + `BITCODE_SPEC.txt must remain V33 during V34 gate work. Observed ${pointer || 'empty'}.`, + ); + + if (!args.skipBranchCheck) { + const branch = git(root, ['branch', '--show-current']); + assertCheck( + failures, + branch === 'version/v34' || /^v34\/gate-\d+-[a-z0-9][a-z0-9-]*$/u.test(branch), + `V34 work must occur on version/v34 or v34/gate-N-* branches. Observed ${branch || 'detached HEAD'}.`, + ); + } + + const requiredFiles = [ + 'BITCODE_SPEC_V34.md', + 'BITCODE_SPEC_V34_DELTA.md', + 'BITCODE_SPEC_V34_NOTES.md', + 'BITCODE_SPEC_V34_PARITY_MATRIX.md', + 'BITCODE_SPECIFYING.md', + 'BITCODE_SPEC_TEMPLATEGUIDE.md', + 'SPECIFICATIONS_ROADMAP.md', + '.github/workflows/bitcode-gate-quality.yml', + '.github/workflows/bitcode-canon-quality.yml', + '.github/pull_request_template.md', + 'README.md', + 'AGENTS.md', + 'package.json', + 'packages/protocol/README.md', + 'protocol-demonstration/README.md', + 'packages/protocol/src/canon-posture.js', + 'protocol-demonstration/src/canon-posture.js', + 'packages/protocol/data/state.json', + ]; + + for (const relativePath of requiredFiles) { + assertCheck(failures, fileExists(root, relativePath), `Missing required V34 Gate 1 file: ${relativePath}`); + } + + const spec = read(root, 'BITCODE_SPEC_V34.md'); + const delta = read(root, 'BITCODE_SPEC_V34_DELTA.md'); + const notes = read(root, 'BITCODE_SPEC_V34_NOTES.md'); + const parity = read(root, 'BITCODE_SPEC_V34_PARITY_MATRIX.md'); + const roadmap = read(root, 'SPECIFICATIONS_ROADMAP.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 prTemplate = read(root, '.github/pull_request_template.md'); + const readme = read(root, 'README.md'); + const protocolReadme = read(root, 'packages/protocol/README.md'); + const demoReadme = read(root, 'protocol-demonstration/README.md'); + const packagePosture = read(root, 'packages/protocol/src/canon-posture.js'); + const demoPosture = read(root, 'protocol-demonstration/src/canon-posture.js'); + const postureState = read(root, 'packages/protocol/data/state.json'); + + for (const [label, content] of [ + ['V34 SPEC', spec], + ['V34 DELTA', delta], + ['V34 NOTES', notes], + ['V34 PARITY', parity], + ]) { + assertCheck( + failures, + content.includes('Current canonical/latest target: `V33`'), + `${label} must declare V33 as current canonical/latest target.`, + ); + } + + for (const phrase of [ + 'deployment-depth', + 'DeploymentHostCapabilityCatalog', + 'EnvironmentLaneContract', + 'DistributedExecutionRuntimeReceipt', + 'DeploymentStoragePosture', + 'MigrationApprovalGate', + 'SecretRotationPlan', + 'RuntimeObserverRepairJob', + 'RollbackUpgradeRepairPlaybook', + 'DeploymentReadinessRehearsal', + 'ledger-derived state', + 'object storage', + 'proof artifacts', + 'secret rotation', + 'rollback', + 'staging-testnet', + 'mainnet-ready', + 'value-bearing mainnet', + ]) { + assertCheck(failures, spec.includes(phrase), `V34 SPEC must name ${phrase}.`); + } + + for (const staleGate of [ + 'Gate 1: V34 Interface Roadmap And Spec Opening', + 'Gate 2: Interface Inventory And Contract Catalog', + 'Gate 3: MCP API Tool And Registry Contracts', + 'Gate 4: ChatGPT App Action And Tool Contracts', + ]) { + assertCheck(failures, !spec.includes(staleGate), `V34 SPEC must not retain stale V33 interface-depth gate "${staleGate}".`); + } + + for (const gate of [ + 'Gate 1: V34 Deployment Roadmap And Spec Opening', + 'Gate 2: Host Capability And Environment Lane Catalog', + 'Gate 3: Distributed Execution Runtime Contracts', + 'Gate 4: Ledger Database Object Storage Deployment Posture', + 'Gate 5: Secret Rotation And Credential Boundary Operations', + 'Gate 6: Migration CI/CD Deployment Approval Gates', + 'Gate 7: Runtime Observers Broadcasters Repair Jobs', + 'Gate 8: Rollback Upgrade Data Repair Playbooks', + 'Gate 9: Local Staging Testnet Deployment Rehearsal', + 'Gate 10: V34 Promotion Readiness', + ]) { + assertCheck(failures, delta.includes(gate) || notes.includes(gate) || spec.includes(gate), `V34 gate plan is missing ${gate}.`); + } + + assertCheck(failures, hasSection(notes, 'Notes companion rule'), 'V34 NOTES must include Notes companion rule.'); + assertCheck(failures, hasSection(notes, 'Simplified-spec reading rule'), 'V34 NOTES must include Simplified-spec reading rule.'); + assertCheck(failures, notes.includes('V34 gate plan'), 'V34 NOTES must carry the V34 gate plan.'); + assertCheck(failures, notes.includes('deployment depth'), 'V34 NOTES must name deployment depth scope.'); + + assertCheck(failures, parity.includes('## Gate 1 Parity'), 'V34 PARITY must include Gate 1 parity.'); + assertCheck(failures, parity.includes('V34 implementation matrix'), 'V34 PARITY must include the implementation matrix.'); + assertCheck(failures, parity.includes('completion condition'), 'V34 PARITY must include a completion condition.'); + assertCheck(failures, parity.includes('v34/gate-1-deployment-roadmap-opening'), 'V34 PARITY must name the Gate 1 branch.'); + + assertCheck(failures, roadmap.includes('Current active canonical pointer: `BITCODE_SPEC.txt` -> `V33`'), 'Roadmap must state V33 as active pointer.'); + assertCheck(failures, roadmap.includes('Current draft target: `BITCODE_SPEC_V34.md`'), 'Roadmap must state V34 as active draft target.'); + assertCheck(failures, roadmap.includes('| V33 | `BITCODE_SPEC_V33.md` | active canon |'), 'Roadmap must mark V33 active canon.'); + assertCheck(failures, roadmap.includes('| V34 | `BITCODE_SPEC_V34.md` | active draft target |'), 'Roadmap must mark V34 active draft target.'); + for (const version of ['V34', 'V35', 'V36', 'V37']) { + assertCheck(failures, roadmap.includes(`| ${version} |`), `Roadmap must preserve ${version} scope.`); + } + + assertCheck(failures, packageJson.includes('"check:v34-gate1"'), 'package.json must expose check:v34-gate1.'); + assertCheck(failures, gateWorkflow.includes('check-v34-gate1-deployment-roadmap-opening.mjs'), 'Gate workflow must run the V34 Gate 1 checker.'); + assertCheck(failures, gateWorkflow.includes('--version V34 --mode draft --current-target V33'), 'Gate workflow must validate V34 draft spec over V33.'); + assertCheck(failures, gateWorkflow.includes('--active-canon V33 --draft-target V34'), 'Gate workflow must validate V33/V34 canon posture.'); + assertCheck(failures, canonWorkflow.includes('--version V34 --mode draft --current-target V33'), 'Canon workflow must validate V34 draft family.'); + assertCheck(failures, canonWorkflow.includes('--active-canon V33 --draft-target V34'), 'Canon workflow must validate V33/V34 canon posture.'); + assertCheck(failures, canonWorkflow.includes('spec:\\ V34*|spec:\\ v34*'), 'Canon workflow must enforce V34 spec-title conformance.'); + + assertCheck(failures, readme.includes('resolves to `V33`; V34 is the active draft target'), 'README must state V33 active / V34 draft posture.'); + assertCheck(failures, readme.includes('version/v34'), 'README must document the version/v34 branch workflow.'); + assertCheck(failures, readme.includes('v34/gate-1-deployment-roadmap-opening'), 'README must document a V34 gate branch example.'); + assertCheck(failures, prTemplate.includes('V34 Gate N:'), 'PR template must show V34 gate title format.'); + assertCheck(failures, protocolReadme.includes('V33` active, `V34` draft'), 'Protocol README must state V33/V34 posture.'); + assertCheck(failures, demoReadme.includes('resolves to `V33`; V34 is the active draft target'), 'Demonstration README must state V33/V34 posture.'); + + for (const [label, content] of [ + ['commercial protocol package', packagePosture], + ['standalone demonstration', demoPosture], + ['protocol state projection', postureState], + ]) { + assertCheck(failures, content.includes("ACTIVE_CANON_VERSION = 'V33'") || content.includes('"activeCanonVersion": "V33"'), `${label} must keep V33 active.`); + assertCheck(failures, content.includes("DRAFT_TARGET_VERSION = 'V34'") || content.includes('"draftTargetVersion": "V34"'), `${label} must declare V34 draft target.`); + } + + 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('V34 Gate 1 deployment roadmap opening check failed:\n'); + for (const failure of failures) process.stderr.write(`- ${failure}\n`); + process.exitCode = 1; + return; + } + + process.stdout.write(`V34 Gate 1 deployment roadmap opening 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; +}