diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8a97d3164..0bf9c1e17 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: `V38 Gate N: Concise Topical Title`. -Use the version and promotion prefix for version promotion PRs: `V38 Canonical Promotion: Concise Topical Title`. +Use the version and gate prefix for gate PRs: `V39 Gate N: Concise Topical Title`. +Use the version and promotion prefix for version promotion PRs: `V39 Canonical Promotion: Concise Topical Title`. ## Closure diff --git a/.github/workflows/bitcode-canon-quality.yml b/.github/workflows/bitcode-canon-quality.yml index 5d8b87819..61ca12369 100644 --- a/.github/workflows/bitcode-canon-quality.yml +++ b/.github/workflows/bitcode-canon-quality.yml @@ -181,6 +181,10 @@ jobs: node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V38 --draft-target V39 node scripts/check-bitcode-spec-family.mjs --version V38 --mode promoted --current-target V38 node scripts/check-v38-gate11-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests + if [ -f BITCODE_SPEC_V39.md ]; then + node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38 + node scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs --skip-branch-check + fi else echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2 exit 1 @@ -296,7 +300,15 @@ jobs: node scripts/check-bitcode-spec-family.mjs --version V38 --mode draft --current-target V37 fi ;; + spec:\ V39*|spec:\ v39*) + POINTER="$(cat BITCODE_SPEC.txt)" + if [ "$POINTER" = "V39" ]; then + node scripts/check-bitcode-spec-family.mjs --version V39 --mode promoted --current-target V39 + else + node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38 + fi + ;; *) - echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38 spec change." + echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38/V39 spec change." ;; esac diff --git a/.github/workflows/bitcode-gate-quality.yml b/.github/workflows/bitcode-gate-quality.yml index 2ec6d65e7..49f15421a 100644 --- a/.github/workflows/bitcode-gate-quality.yml +++ b/.github/workflows/bitcode-gate-quality.yml @@ -310,6 +310,10 @@ jobs: node scripts/check-bitcode-canonical-inputs.mjs --current-target V38 node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V38 --draft-target V39 node scripts/check-v38-gate11-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests + if [ -f BITCODE_SPEC_V39.md ]; then + node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38 + node scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs --skip-branch-check + fi else echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2 exit 1 diff --git a/BITCODE_SPEC_V39.md b/BITCODE_SPEC_V39.md new file mode 100644 index 000000000..7f5b2b268 --- /dev/null +++ b/BITCODE_SPEC_V39.md @@ -0,0 +1,549 @@ +# Bitcode Spec V39 + +## Status + +- Version: `V39` +- V39 state: draft opened; V39 is the commercial Reading readiness target over promoted V38 inference correctness canon +- Current canonical/latest target: `V38` +- Draft proof-source commit: unbound until V39 promotion +- Prior canonical anchor: `BITCODE_SPEC_V38.md` +- Prior generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md` +- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V38` +- Generated structured artifact inventory: draft opening requires `.bitcode/v39-spec-family-report.json` and `.bitcode/v39-canonical-input-report.json`; later V39 gates must add package-backed source-safe artifacts for depository supply indexing, enterprise Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime, AssetPack preview/quote boundaries, settlement/delivery rights receipts, operational telemetry/rehearsal, and promotion readiness +- Source parity state: V39 source-side parity is opened but not closed; Gate 1 owns spec/roadmap/workflow posture and later gates must close runtime implementation, source-safe generated artifacts, tests, proofs, and local/staging rehearsal before promotion +- Notes companion: `BITCODE_SPEC_V39_NOTES.md` +- Delta companion: `BITCODE_SPEC_V39_DELTA.md` +- Parity companion: `BITCODE_SPEC_V39_PARITY_MATRIX.md` +- Generated proof appendix: `BITCODE_SPEC_V39_PROVEN.md` only after V39 promotion +- Scope: V39 draft system specification for commercial Reading readiness: deposited source indexing, enterprise Read Request UX, reviewable ReadNeed synthesis and resynthesis, many-fit depository search, source-safe AssetPack preview and deterministic quote, settlement, BTD rights transfer, post-settlement delivery, synchronized ledger/database/storage, operational telemetry, local/staging rehearsal, and promotion readiness +- Last fully realized canonical target preserved in source: `V38` + +## Version executive summary + +V39 is the commercial Reading readiness version. +It follows V38 by preserving the inference stack V38 made exact and applying it to the complete enterprise buyer path: request a read, review or resynthesize Bitcode's Need comprehension, request Finding Fits, review a source-safe AssetPack preview and deterministic BTC quote, settle, receive BTD rights, and receive the full AssetPack only after settlement unlock. + +V39 must turn the source-safe pipeline surfaces promoted through V28-V38 into a reliable product flow. +Deposits must be indexed and searchable as Depository supply. +`ReadNeedComprehensionSynthesis` must store reviewable Needs and resynthesis history. +`ReadFitsFindingSynthesis` must search many candidate deposits above threshold, rank and verify them, preserve selected-fit provenance, and feed synthesis without leaking unpaid source. +AssetPack preview must expose only measurements, fit reasons, quality posture, proof roots, pricing posture, and non-source metadata before settlement. +Settlement must produce auditable BTC, BTD rights-transfer, source-to-shares compensation, ledger/database/storage, delivery, and repair receipts. +Terminal and Conversation surfaces must present the flow as a clear five-step enterprise Reading experience while keeping expandable source-safe detail for operators. + +## V39 commercial Reading law + +V39 uses the existing primitive names precisely: + +- `PipelineExecution` owns phase ordering, phase inputs, phase outputs, ancestry state, phase receipts, and pipeline telemetry. +- PTRR agents own `Plan`, `Try`, `Refine`, and `Retry` steps plus agent-level prompt registry composition. +- PTRR steps own their prompt registries, selected tools, Failsafe usage, typed step outputs, step receipts, and step telemetry. +- `FailsafeGenerationSequence` owns context preparation, large input handling, large output handling, stitch or summarization loops, and repair orchestration around the final typed inference chain. +- `ThricifiedGeneration` owns the lowest-level Reason, Judge, and StructuredOutput inference calls. +- `ToolExecution` owns callable tool input, execution, output, errors, and receipts. +- `DocCodeToolPrompt` and `formatUsableTools` own doc-comment-backed tool definitions that are injected into final prompts when tools are available to a step. + +Tools are step-owned capabilities. +They are not hidden children of `ThricifiedGeneration`, but tool documentation must still be available to the final prompt material consumed by `ThricifiedGeneration`. +Every inference envelope must preserve template identity, prompt part identity, interpolated prompt, context bindings, selected tools, raw response presence, parsed typed result, schema verdict, retry or repair state, disclosure tier, proof root, and execution ancestry root at the permitted telemetry tier. + +The enterprise Reading product path has five user-visible stages: + +1. Request Read: capture repository/deposit anchors, enterprise intent, constraints, disclosure posture, and target outcome. +2. Review Synthesized Need: run `ReadNeedComprehensionSynthesis`, show a reviewable Need, and allow feedback-driven resynthesis without admitting Finding Fits until accepted. +3. Request Finding Fits: run `ReadFitsFindingSynthesis` against the Depository using accepted Need measurements, query plans, tools, embeddings, and ranking thresholds. +4. Review Synthesized AssetPack Preview: show only source-safe measurements, fit reasons, proof roots, quality posture, pricing quote, selected-fit provenance, and delivery posture. +5. Buy AssetPack And Settle: observe BTC payment, transfer BTD rights, unlock source-bearing delivery, create or repair the pull request, and synchronize ledger/database/storage receipts. + +## V39 Reading pipeline focus + +`ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` are the primary Reading pipelines under V39. +They must be audited from phase to agent to step to Failsafe substep to Thricified generation to tool to typed output. +The audit must count every inference point separately, name the prompts and PromptParts used by that point, define input context, define output schemas, define failure or repair behavior, and identify where the result is stored and streamed. + +`ReadNeedComprehensionSynthesis` must synthesize an enterprise user's Read Request into a reviewable Need that says exactly what should be read, what must not be over-inferred, which repository/deposit constraints apply, and what measurements drive fit-finding. + +`ReadFitsFindingSynthesis` must discover many possible fits, not one fit. +It must gather above-threshold deposits from the Depository, rank and verify those candidates, preserve found-fit provenance, and hand the selected fits into AssetPack synthesis. +Before settlement, the Reader may see only source-safe measurements, fit reasons, quality posture, pricing posture, proof roots, and preview metadata. +After settlement, delivery may cross the visibility boundary and provide the full AssetPack source as governed by BTD rights transfer and ledger/database synchronization. + +## V39 gate plan + +### Gate 1: Commercial Reading Roadmap And Spec Opening + +Gate 1 opens V39 correctly: + +- V39 SPEC, DELTA, NOTES, and PARITY files exist over active V38. +- `BITCODE_SPEC.txt` remains `V38`. +- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V38 active / V39 draft posture. +- `check:v39-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, inference vocabulary, depository-search vocabulary, and promotion boundaries. +- The V39 gate list is explicit before inference implementation begins. + +### Gate 2: Depository Supply Indexing And Searchable Deposit Lifecycle + +Gate 2 closes Depository supply reality for Reading. +It must make deposited source materials measurable, indexable, vector-searchable, metadata-searchable, rights-aware, and repairable as the source set that Finding Fits can search. +The gate is closed by package-backed source, deterministic source-safe artifact generation, deposit lifecycle tests, embedding/vector policy tests, Supabase/storage projection readback, and a checker that proves no protected source or credentials enter public artifacts. + +### Gate 3: Enterprise Reading UX State Machine + +Gate 3 implements the five-step enterprise Reading path in Terminal and connected Conversation handoffs. +The UX must default to clear low-detail guidance while preserving expandable source-safe operational detail for every step, pipeline run, quote, settlement, and delivery state. +The gate is closed by route state contracts, component tests, browser proof, stream-log integration, and source-safe disclosure tests. + +### Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime + +Gate 4 makes `ReadNeedComprehensionSynthesis` a real review loop. +It must persist Read Requests, synthesized Needs, feedback, resynthesis attempts, Need measurements, accepted-Need admission, rejected-Need posture, and telemetry receipts. +Finding Fits remains blocked until a reviewed Need is accepted. + +### Gate 5: ReadFitsFinding Runtime, Ranking, And Replay + +Gate 5 makes `ReadFitsFindingSynthesis` search the whole available Depository for many candidate deposits. +It must execute inference-derived query planning, lexical/symbolic/path/metadata/measurement/vector/provider channels, threshold ranking, verification, selected-fit provenance, replay receipts, and repair paths over the accepted Need. +The active vector policy remains OpenAI `text-embedding-3-small`, 1536 dimensions, cosine similarity, and `match_deliverable_vectors` until a tested migration is specified. + +### Gate 6: AssetPack Preview, Quote, And Disclosure Boundary + +Gate 6 makes source-safe AssetPack preview commercially usable without leaking source. +It must synthesize a preview from selected fits, expose fit measurements, quality reasons, proof roots, deterministic BTC quote, selected-fit provenance, delivery posture, and settlement instructions while withholding source-bearing AssetPack content until paid. + +### Gate 7: Settlement, BTD Rights Transfer, And Delivery + +Gate 7 closes the paid boundary. +It must observe BTC settlement, bind finality, mint or transfer the relevant BTD rights, allocate source-to-shares compensation to contributors, unlock source-bearing AssetPack delivery, create or repair the pull request, and synchronize ledger/database/object-storage receipts. + +### Gate 8: Operational Telemetry, Repair, And Operator Readback + +Gate 8 makes the Reading product observable and repairable. +It must stream source-safe phase, agent, step, Failsafe, ThricifiedGeneration, tool, storage, ledger, wallet, delivery, and UI events into the rich execution log and operator readback surfaces with proof roots and runbook hooks. + +### Gate 9: Interface And Conversation Product Parity + +Gate 9 brings Conversation, MCP/API, ChatGPT App, and package-facing interfaces into the same Reading contract without creating parallel authority. +Every interface must respect accepted-Need gating, source-safe preview, settlement unlock, BTD rights, and delivery boundaries. + +### Gate 10: Local And Staging Commercial Reading Rehearsal + +Gate 10 proves V39 locally and in staging-testnet. +It must run the five-step Reading flow with real non-mocked inference where credentials are available, Depository search, source-safe preview, telemetry streaming/readback, ledger/database/storage synchronization, PR delivery posture, and blocked production-mainnet value-bearing admission. + +### Gate 11: V39 Promotion Readiness + +Gate 11 closes V39 with promotion readiness. +It must generate V39 proof support, validate every V39 artifact, update promotion workflows, preserve V38 active / V39 draft to V39 active / draft V40 posture, and block promotion if Depository supply, Reading UX, Need review, Finding Fits, preview/quote, settlement/delivery, telemetry/repair, interface parity, local/staging rehearsal, or source-safety evidence is incomplete. + +## V39 non-goals + +- V39 does not change BTD supply law, Bitcoin settlement law, Exchange law, or production-mainnet admission unless a later promoted canon explicitly does so. +- V39 does not introduce versioned routes, versioned API paths, or versioned source identifiers. +- V39 does not allow protected source, raw protected prompts, raw provider responses, unpaid AssetPack source, credentials, private wallet material, or private settlement payloads to appear in public telemetry. +- V39 does not replace the existing prompt, registry, execution, agent, tool, and pipeline primitives with a parallel abstraction stack. + +## Canonical Bitcode executive summary + +Bitcode is the commercial Protocol implementation for depositing, measuring, finding, synthesizing, settling, delivering, and proving technical intelligence as BTD and AssetPack activity. +V39 does not replace V38 canon; it deepens the inference machinery that lets Bitcode understand Read Requests, synthesize Needs, find many fits across the Depository, synthesize source-safe AssetPack previews, and deliver full AssetPacks only after settlement and rights transfer. + +## source-of-truth hierarchy + +The source-of-truth hierarchy for V39 is: + +1. `BITCODE_SPEC.txt` points to active V38 until V39 promotion. +2. `BITCODE_SPEC_V38.md` and `BITCODE_SPEC_V38_PROVEN.md` remain active canon. +3. `BITCODE_SPEC_V39.md`, `BITCODE_SPEC_V39_DELTA.md`, `BITCODE_SPEC_V39_NOTES.md`, and `BITCODE_SPEC_V39_PARITY_MATRIX.md` are the draft target family during V39 gates. +4. Package source, tests, scripts, workflows, generated `.bitcode/*` artifacts, local/staging rehearsal evidence, and promotion checks must converge before V39 promotion. + +## full-system, re-implementation, and audit rule + +V39 work must preserve full-system auditability. +No implementation may bypass package-owned primitives for executions, pipelines, PTRR agents, prompt registries, tools, telemetry, BTD, ledger/database synchronization, object storage, or source-safe disclosure. +Any re-implementation must prove parity against the active primitive and may not fork an easier parallel path. + +## totality and precision enforcement rule + +V39 gates must make every inference edge total enough to audit: inputs, prompts, PromptParts, interpolation bindings, tools, outputs, raw provider responses, parsed typed results, schema verdicts, repairs, failures, storage destinations, streaming destinations, proof roots, and disclosure tiers must be precise before promotion. + +## system goals, non-goals, and design principles + +Goals: commercial inference correctness, reliable Reading intelligence, benchmarkable prompt materials, source-safe telemetry, depository-wide fit-finding, and settlement-traceable AssetPack synthesis. +Non-goals: value-bearing mainnet admission, BTD supply changes, bridge chain-of-record implementation, versioned routes, or provider-specific shortcuts without tests. +Design principles: reuse primitives, preserve typed receipts, fail closed, expose only permitted disclosure tiers, and make every prompt and search decision auditable. + +## system architecture and layer boundaries + +The V39 architecture boundary is `PipelineExecution -> PTRR agent -> PTRR step -> FailsafeGenerationSequence -> ThricifiedGeneration -> provider call`. +`ToolExecution` remains step-owned. +Prompt registry and PromptPart composition must flow downward from phase, agent, step, Failsafe, tool documentation, and generation prompt materials into the final provider call. +Ledger, wallet, object storage, GitHub delivery, and settlement operations remain outside inference authority and are invoked only through their existing package or route boundaries. + +## canonical domain model + +The V39 domain model carries the existing Bitcode objects: deposits, Reads, Read Requests, Needs, candidate fit deposits, AssetPacks, BTD ranges, preview measurements, settlement receipts, delivery receipts, proof roots, execution receipts, prompt receipts, tool receipts, telemetry events, and repair cases. +V39 adds no new chain-of-record object; it makes inference and fit-finding receipts precise enough to support the existing Protocol model. + +## whole Bitcode operator chain + +The whole operator chain is deposit source, measure deposited material, request a Read, synthesize a Need, review or resynthesize the Need, find many fitting deposits, synthesize a source-safe AssetPack preview, calculate deterministic settlement posture, settle in BTC when admitted, transfer BTD read rights, deliver the full AssetPack, journal database/ledger/object-storage projections, emit telemetry, and preserve proof roots for repair. + +## canonical subsystem surfaces + +### Depositing and asset supply + +Current canonical objects and emitted artifacts: deposits, deposited source metadata, BTD range identity, source-safe proofs, and inherited `.bitcode/asset-pack.lock.json` style artifact roots. +Current algorithms and derivation rules: source measurement, source-to-shares accounting, deposit admissibility, and proof-root derivation remain inherited from V38 and prior canon. +Current invariants and fail-closed conditions: deposits cannot expose secrets or protected source beyond permitted tiers, and invalid deposit fails closed. +Current proof obligations: source measurement, disclosure boundary, static analysis, and proof contract evidence remain required. +Current source-bearing implementation basis: package source and route contracts outside `_legacy/`. +Current validating commands and parity basis: active V38 promoted checks plus V39 gate checks. +Current accepted boundaries: V39 only changes inference/search surfaces that consume deposits. + +### Reading and prompt/inference ownership + +Current canonical objects and emitted artifacts: Read Request, synthesized Need, prompt registry receipts, PromptPart benchmark fixtures, Failsafe receipts, ThricifiedGeneration receipts, and typed Need outputs. +Current algorithms and derivation rules: PTRR steps compose prompts and delegate to Failsafe and Thricified chains. +Current invariants and fail-closed conditions: prompt contract incompleteness and parsed-envelope inadmissibility fail closed. +Current proof obligations: Inference-synthesis and Prompt-completeness evidence must cover every active inference point. +Current source-bearing implementation basis: `packages/agent-generics`, `packages/prompts`, and `packages/pipelines/asset-pack`. +Current validating commands and parity basis: V39 Gate 2 through Gate 6 checks. +Current accepted boundaries: inference may understand and measure; it may not settle, mint, or deliver protected source. + +### Fit, recall, ranking, and verification + +Current canonical objects and emitted artifacts: query receipts, search channel receipts, candidate deposits, ranking roots, threshold verdicts, selected-fit provenance, and verification evidence. +Current algorithms and derivation rules: inference-derived queries search lexical, symbolic, path, metadata, measurement, embedding/vector, and provider-specific channels before ranking. +Current invariants and fail-closed conditions: no-survivor asset pack and unsupported vector policy fail closed. +Current proof obligations: Selection-and-materialization, Verification-decisions, and Disclosure-boundary proofs. +Current source-bearing implementation basis: `depository-search.ts`, `embedding-config.ts`, and depository-search tools. +Current validating commands and parity basis: V39 Gate 7 checks and later Gate 8 handoff checks. +Current accepted boundaries: source-safe preview before settlement, full source only after paid rights transfer. + +### Selection and materialization + +Current canonical objects and emitted artifacts: AssetPack preview, AssetPack synthesis receipt, delivery PR receipt, `assetPackEvidence`, selected-source material, verification report, and proof bundle. +Current algorithms and derivation rules: selected fits are synthesized into an AssetPack only after source-safe preview posture and settlement/delivery boundaries are respected. +Current invariants and fail-closed conditions: unpaid AssetPack source cannot cross the Reader visibility boundary. +Current proof obligations: Selection-and-materialization and Settlement-source-to-shares proof evidence. +Current source-bearing implementation basis: Reading pipeline packages, GitHub delivery surfaces, BTD packages, and ledger/database projectors. +Current validating commands and parity basis: V39 Gate 8 through Gate 10 checks. +Current accepted boundaries: V39 can harden handoff and telemetry, not bypass payment. + +### Identity, authorization, and sensitive flow + +Current canonical objects and emitted artifacts: organization roles, account principals, wallet posture, policy decisions, signing authority boundaries, and sensitive-flow redaction receipts. +Current algorithms and derivation rules: policy checks gate source, wallet, settlement, delivery, and visibility transitions. +Current invariants and fail-closed conditions: authorization denial and private material exposure fail closed. +Current proof obligations: Authorization-and-sensitive-flow, Disclosure-boundary, and Static-code-analysis proofs. +Current source-bearing implementation basis: API packages, UAPI route boundaries, BTD packages, and V38 privacy redaction. +Current validating commands and parity basis: V39 Gate 5, Gate 8, and Gate 10 checks. +Current accepted boundaries: inference telemetry must never become an authorization bypass. + +### Disclosure and projection + +Current canonical objects and emitted artifacts: public, buyer, reviewer, internal, operator-only, and source-safe telemetry projections. +Current algorithms and derivation rules: each telemetry row is assigned a disclosure tier before storage, streaming, docs, or UI display. +Current invariants and fail-closed conditions: public projection overexposure fails closed. +Current proof obligations: Disclosure-boundary and Proof-contract evidence. +Current source-bearing implementation basis: V35 telemetry law, V38 stream UI, and V39 inference telemetry contracts. +Current validating commands and parity basis: V39 Gate 5 and Gate 9 checks. +Current accepted boundaries: raw protected prompts and raw provider responses are not public payloads. + +### Settlement and exact accounting + +Current canonical objects and emitted artifacts: BTC fee quote, measurement volume, settlement receipt, ledger root, database projection root, BTD right transfer, contributor compensation route, and repair receipt. +Current algorithms and derivation rules: deterministic measurement weight times measurement volume informs pricing posture, and settlement finality governs delivery. +Current invariants and fail-closed conditions: settlement conservation drift, underpayment, stale quote, and projection mismatch fail closed. +Current proof obligations: Settlement-source-to-shares and Proof-contract evidence. +Current source-bearing implementation basis: BTD packages, Exchange settlement canon, Reading pipeline handoff, and repair jobs. +Current validating commands and parity basis: V39 Gate 8, Gate 10, and Gate 11 checks. +Current accepted boundaries: V39 does not change BTC law; it preserves inference-to-settlement traceability. + +### Proof contract, witnesses, and replay + +Current canonical objects and emitted artifacts: generated proof appendix, spec-family reports, canonical-input reports, canon-posture drift reports, benchmark reports, inference receipts, tool receipts, telemetry roots, and rehearsal evidence. +Current algorithms and derivation rules: proof roots derive from deterministic artifacts and replayable command evidence. +Current invariants and fail-closed conditions: stale promoted status truth and missing generated proof evidence fail closed. +Current proof obligations: all nine proof families. +Current source-bearing implementation basis: `packages/protocol`, scripts, workflows, tests, and generated `.bitcode/*` artifacts. +Current validating commands and parity basis: V39 Gate 1 through Gate 11 checks. +Current accepted boundaries: generated proof cannot serialize credentials, protected source, unpaid AssetPack source, or private wallet material. + +## proof-family canon + +The V39 proof-family canon inherits all nine proof families and adds inference-focused closure criteria. + +### Inference-synthesis + +proofArtifactPath: `.bitcode/v39-inference-surface-inventory.json` and `.bitcode/v39-ptrr-failsafe-thricified-stack.json` +members: pipeline phases, PTRR agents, Plan/Try/Refine/Retry steps, Failsafe chains, ThricifiedGeneration calls, provider calls +theoremIds: commercial-reading-totality, typed-output-admissibility +replayStepIds: run V39 Gate 2 and Gate 3 checks +witnessArtifactPaths: prompt receipts, generation receipts, telemetry receipts +current member closure criteria: every inference point is counted and typed +current member verdict shape: passed, failed, or repair-required with proof root +current theorem-by-theorem closure reading: stack composition and typed output are replayable +current theorem-to-replay grouping: inventory, execution stack, telemetry +minimum artifact/replay binding set: source paths, prompt ids, schema ids, telemetry ids +current proof-object fields: proofRoot, phaseId, agentId, stepId, generationId, schemaVerdict +generated-artifact and test bindings: V39 Gate 2 and Gate 3 artifacts and tests +fail-closed conditions: missing prompt, missing schema, invalid typed output + +### Prompt-completeness + +proofArtifactPath: `.bitcode/v39-prompt-benchmark-report.json` +members: PromptParts, Prompts, templates, interpolation bindings, tool documentation +theoremIds: prompt-registry-totality, prompt-benchmark-coverage +replayStepIds: run V39 Gate 4 checks +witnessArtifactPaths: benchmark fixtures and reports +current member closure criteria: active prompts and PromptParts are benchmarkable +current member verdict shape: benchmark pass, benchmark fail, or missing fixture +current theorem-by-theorem closure reading: every active prompt has identity and expected qualities +current theorem-to-replay grouping: prompt inventory and benchmark suite +minimum artifact/replay binding set: prompt id, prompt part id, fixture id, result root +current proof-object fields: promptId, promptPartIds, fixtureRoot, qualityVerdict +generated-artifact and test bindings: V39 Gate 4 artifacts and tests +fail-closed conditions: missing prompt identity or unbound interpolation + +### Static-code-analysis + +proofArtifactPath: `.bitcode/v39-static-inference-boundary-report.json` +members: imports, source casing, route versioning, secret scans, raw prompt boundaries +theoremIds: source-boundary-conformance, no-versioned-route-drift +replayStepIds: run gate-quality static checks +witnessArtifactPaths: workflow logs and scan reports +current member closure criteria: no unsupported imports or versioned API routes +current member verdict shape: passed or failed with source location +current theorem-by-theorem closure reading: static code matches active source discipline +current theorem-to-replay grouping: casing, imports, route scan, redaction scan +minimum artifact/replay binding set: file path, scanner id, verdict +current proof-object fields: scannerId, filePath, verdict, evidenceRoot +generated-artifact and test bindings: gate-quality workflow +fail-closed conditions: versioned route, secret leak, unsupported import + +### Verification-decisions + +proofArtifactPath: `.bitcode/v39-verification-decision-report.json` +members: search verification, Need adequacy, fit quality, AssetPack preview quality +theoremIds: verification-is-typed, no-unverified-fit-selection +replayStepIds: run V39 Gate 6 through Gate 8 checks +witnessArtifactPaths: verification reports and selected-fit roots +current member closure criteria: verification decisions are typed and proof-rooted +current member verdict shape: accepted, rejected, blocked, or repair-required +current theorem-by-theorem closure reading: no fit or preview is accepted without evidence +current theorem-to-replay grouping: Need verification, fit verification, preview verification +minimum artifact/replay binding set: decision id, input root, output root, proof root +current proof-object fields: decisionId, state, reason, proofRoot +generated-artifact and test bindings: V39 Gate 6 through Gate 8 tests +fail-closed conditions: unsupported evidence, below-threshold fit, unverifiable preview + +### Selection-and-materialization + +proofArtifactPath: `.bitcode/v39-read-fits-finding-search-embeddings.json`; `.bitcode/v39-assetpack-synthesis-economic-traceability.json` +members: candidate deposits, selected fits, AssetPack synthesis handoff, PR delivery +theoremIds: selected-fits-traceable, materialization-source-safe +replayStepIds: run V39 Gate 7 and Gate 8 checks +witnessArtifactPaths: selected-source material, verification report, AssetPack evidence +current member closure criteria: selected fit provenance survives synthesis handoff +current member verdict shape: selected, rejected, or blocked +current theorem-by-theorem closure reading: materialization follows from verified fits +current theorem-to-replay grouping: search, rank, select, synthesize +minimum artifact/replay binding set: fit id, deposit id, ranking root, synthesis root +current proof-object fields: fitId, depositRef, rankingRoot, synthesisRoot +generated-artifact and test bindings: V39 Gate 7 and Gate 8 artifacts +fail-closed conditions: no-survivor asset pack, untraceable fit, unpaid source exposure + +### Authorization-and-sensitive-flow + +proofArtifactPath: `.bitcode/v39-sensitive-flow-report.json` +members: source visibility, prompt visibility, wallet material, settlement payloads, credentials +theoremIds: sensitive-flow-redacted, authority-boundary-preserved +replayStepIds: run V39 Gate 5, Gate 8, and Gate 9 checks +witnessArtifactPaths: telemetry disclosure reports and redaction receipts +current member closure criteria: protected payloads are blocked or assigned permitted tiers +current member verdict shape: allowed, denied, redacted, or blocked +current theorem-by-theorem closure reading: authority and visibility do not leak through inference +current theorem-to-replay grouping: telemetry, prompt disclosure, delivery boundary +minimum artifact/replay binding set: payload class, visibility tier, redaction verdict +current proof-object fields: payloadClass, tier, verdict, proofRoot +generated-artifact and test bindings: V39 Gate 5 and Gate 9 tests +fail-closed conditions: authorization denial, credential exposure, private wallet exposure + +### Settlement-source-to-shares + +proofArtifactPath: `.bitcode/v39-assetpack-synthesis-economic-traceability.json` +members: measurement volume, BTC price posture, fit contributor route, ledger/database roots +theoremIds: settlement-traceable-to-fits, compensation-conserved +replayStepIds: run V39 Gate 8 and Gate 10 checks +witnessArtifactPaths: settlement receipts and compensation route roots +current member closure criteria: fits remain traceable into settlement and compensation +current member verdict shape: conserved, blocked, or repair-required +current theorem-by-theorem closure reading: source-to-shares and fees remain exact +current theorem-to-replay grouping: fit provenance, pricing, settlement, rights transfer +minimum artifact/replay binding set: fit ids, fee quote, settlement root, compensation root +current proof-object fields: fitIds, btcAmount, ledgerRoot, databaseRoot +generated-artifact and test bindings: V39 Gate 8 and Gate 10 artifacts +fail-closed conditions: settlement conservation drift, projection mismatch, stale quote + +### Disclosure-boundary + +proofArtifactPath: `.bitcode/v39-disclosure-boundary-report.json` +members: source-safe preview, public telemetry, buyer telemetry, reviewer telemetry, operator telemetry +theoremIds: preview-does-not-leak-source, telemetry-tier-correct +replayStepIds: run V39 Gate 5 through Gate 10 checks +witnessArtifactPaths: stream events, telemetry roots, redaction receipts +current member closure criteria: every disclosure has a tier and forbidden payload list +current member verdict shape: source-safe, redacted, blocked, or failed +current theorem-by-theorem closure reading: source-safe previews remain non-source until settlement +current theorem-to-replay grouping: prompt disclosure, result disclosure, preview disclosure +minimum artifact/replay binding set: event id, tier, payload class, redaction root +current proof-object fields: eventId, tier, payloadClass, verdict +generated-artifact and test bindings: V39 Gate 5 and Gate 9 checks +fail-closed conditions: public projection overexposure, unpaid AssetPack source leakage + +### Proof-contract + +proofArtifactPath: `BITCODE_SPEC_V39_PROVEN.md` +members: spec family, generated artifacts, checks, workflows, promotion evidence +theoremIds: promotion-proof-complete, generated-appendix-current +replayStepIds: run V39 Gate 11 promotion readiness checks +witnessArtifactPaths: V39 generated proof appendix and `.bitcode/v39-*` artifacts +current member closure criteria: every closed gate has generated, tested, source-safe proof +current member verdict shape: promoted, draft, blocked, or stale +current theorem-by-theorem closure reading: promotion is accepted only with complete proof +current theorem-to-replay grouping: gate checks, generated proof, promotion workflow +minimum artifact/replay binding set: artifact root, command, commit, verdict +current proof-object fields: artifactRoot, command, commit, verdict +generated-artifact and test bindings: V39 Gate 11 and promotion workflow +fail-closed conditions: stale promoted status truth, missing proof, unsafe generated payload + +## generated canon + +Generated canon for V39 includes source-safe `.bitcode/v39-*` artifacts, generated reports, benchmark reports, rehearsal evidence, and the eventual `BITCODE_SPEC_V39_PROVEN.md`. +Generated artifacts must be reproducible, deterministic where possible, and blocked when source-safe payload rules fail. +Inherited V19 reproducible-canon artifacts remain the baseline for deterministic generated proof. +Inherited V20 operator-quality artifacts remain the baseline for operator-visible quality. +Exact generated-artifact inventory matrix includes `.bitcode/v39-spec-family-report.json`, `.bitcode/v39-canonical-input-report.json`, `.bitcode/v39-canon-posture-drift-report.json`, `.bitcode/v39-inference-surface-inventory.json`, `.bitcode/v39-ptrr-failsafe-thricified-stack.json`, `.bitcode/v39-prompt-benchmark-report.json`, `.bitcode/v39-disclosure-boundary-report.json`, and later `.bitcode/v39-*` gate artifacts. +V39 specifying generated artifacts include inference inventory, prompt benchmark, telemetry disclosure, depository search, AssetPack handoff, rehearsal, and promotion readiness reports. +Shared generated-artifact fields: version, currentTarget, artifactRoot, sourceRoots, proofRoots, disclosureTier, generatedAt, and command. +Artifact-specific generated payload fields: prompt ids, PromptPart ids, phase ids, agent ids, step ids, Failsafe ids, ThricifiedGeneration ids, tool ids, fit ids, ranking roots, and settlement roots. +Artifact confidentiality and disclosability taxonomy: public, source-safe, buyer-visible, reviewer-visible, operator-only, and forbidden. + +## validation canon + +Validation canon includes `pnpm run check:v39-gate1`, `pnpm run check:v39-gate2`, `pnpm run check:v39-gate3`, `pnpm run check:v39-gate4`, `pnpm run check:v39-gate5`, later V39 gate checks, `node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38`, `node scripts/check-bitcode-canonical-inputs.mjs --current-target V38`, `node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V38 --draft-target V39`, package tests, route tests, UI tests, prompt benchmark checks, telemetry redaction checks, and local/staging rehearsal checks. + +## promotion canon + +Promotion canon requires all V39 gates to close, V39 proof support to exist, a V39 promotion workflow to pass, and the promotion commit to change only accepted canon artifacts and the `BITCODE_SPEC.txt` pointer from V38 to V39. +The V39 promotion readiness canon is `.bitcode/v39-promotion-readiness-report.json`, `BITCODE_SPEC_V39_PROVEN.md`, `v39-canon-promotion.yml`, `check:v39-gate11`, `node scripts/promote-bitcode-canon.mjs --version V39 --commit HEAD --dry-run`, and the V39 active / draft V40 posture checks. + +## appendices and canonical supporting material + +The appendices below are canonical supporting material for V39 gate work. + +## Appendix A. Canonical type and surface catalog + +Canonical types include `PipelineExecution`, PTRR agent config, Plan/Try/Refine/Retry step receipts, Failsafe receipts, ThricifiedGeneration receipts, ToolExecution receipts, PromptPart, Prompt, prompt template, interpolation binding, Need, fit candidate, selected fit, AssetPack preview, settlement receipt, and telemetry event. + +## Appendix B. Proof family closure catalog + +The proof family closure catalog is the nine proof-family canon above. +Each family must close with proofArtifactPath, members, theoremIds, replayStepIds, witnessArtifactPaths, current member closure criteria, current member verdict shape, current theorem-by-theorem closure reading, current theorem-to-replay grouping, minimum artifact/replay binding set, current proof-object fields, generated-artifact and test bindings, and fail-closed conditions. + +### Exact proof-family inventory matrix + +| proofFamily | proofArtifactPath | memberIds | theoremIds | replayStepIds | witnessArtifactPaths | Current source basis | +| --- | --- | --- | --- | --- | --- | --- | +| Inference-synthesis | `.bitcode/v39-read-need-review-resynthesis.json`; `.bitcode/v39-read-fits-finding-runtime.json` | phases, agents, steps, failsafes, generations | commercial-reading-totality | v39-gate4, v39-gate5 | prompt receipts, generation receipts | `packages/agent-generics`, `packages/pipelines/asset-pack` | +| Prompt-completeness | `.bitcode/v39-read-need-review-resynthesis.json`; `.bitcode/v39-read-fits-finding-runtime.json` | PromptParts, Prompts | prompt-registry-totality | v39-gate4, v39-gate5 | benchmark fixtures | `packages/prompts` | +| Static-code-analysis | `.bitcode/v39-static-inference-boundary-report.json` | imports, routes, scans | source-boundary-conformance | gate-quality | workflow logs | scripts and workflows | +| Verification-decisions | `.bitcode/v39-read-need-review-resynthesis.json`; `.bitcode/v39-assetpack-preview-quote-boundary.json` | Need, fits, previews | verification-is-typed | v39-gate4, v39-gate6 | verification reports | Reading pipeline packages | +| Selection-and-materialization | `.bitcode/v39-read-fits-finding-runtime.json`; `.bitcode/v39-settlement-rights-delivery.json` | candidates, selected fits, AssetPack handoff | selected-fits-traceable | v39-gate5, v39-gate7 | selected-source material | depository search and synthesis packages | +| Authorization-and-sensitive-flow | `.bitcode/v39-sensitive-flow-report.json` | visibility tiers, redaction | sensitive-flow-redacted | v39-gate5, v39-gate9 | redaction receipts | API and UI redaction paths | +| Settlement-source-to-shares | `.bitcode/v39-settlement-rights-delivery.json` | fees, contributors, rights | settlement-traceable-to-fits | v39-gate7, v39-gate10 | settlement receipts | BTD and Reading packages | +| Disclosure-boundary | `.bitcode/v39-assetpack-preview-quote-boundary.json`; `.bitcode/v39-operational-telemetry-repair.json` | prompt, result, preview tiers | preview-does-not-leak-source | v39-gate6, v39-gate8 | telemetry events | V35/V38/V39 telemetry surfaces | +| Proof-contract | `BITCODE_SPEC_V39_PROVEN.md` | spec, artifacts, workflows | promotion-proof-complete | v39-gate11 | generated proof appendix | `packages/protocol` | + +## Appendix C. Generated artifact contract catalog + +### Inherited V19 reproducible-canon artifacts + +Inherited V19 reproducible-canon artifacts remain the baseline for deterministic generated proof. + +### Inherited V20 operator-quality artifacts + +Inherited V20 operator-quality artifacts remain the baseline for operator-visible quality. + +### Exact generated-artifact inventory matrix + +Exact generated-artifact inventory matrix includes `.bitcode/v39-spec-family-report.json`, `.bitcode/v39-canonical-input-report.json`, `.bitcode/v39-canon-posture-drift-report.json`, `.bitcode/v39-depository-supply-indexing.json`, `.bitcode/v39-enterprise-reading-ux-state.json`, `.bitcode/v39-read-need-review-resynthesis.json`, `.bitcode/v39-read-fits-finding-runtime.json`, `.bitcode/v39-assetpack-preview-quote-boundary.json`, `.bitcode/v39-settlement-rights-delivery.json`, `.bitcode/v39-operational-telemetry-repair.json`, `.bitcode/v39-interface-conversation-parity.json`, `.bitcode/v39-local-staging-commercial-reading-rehearsal.json`, and `.bitcode/v39-promotion-readiness-report.json`. + +### V39 specifying generated artifacts + +V39 specifying generated artifacts include Depository supply indexing, enterprise Reading UX state, ReadNeed review and resynthesis, ReadFitsFinding runtime and replay, AssetPack preview and quote boundary, settlement rights delivery, operational telemetry repair, interface Conversation parity, local and staging commercial Reading rehearsal, and promotion readiness reports. + +### Shared generated-artifact fields + +Shared generated-artifact fields: version, currentTarget, artifactRoot, sourceRoots, proofRoots, disclosureTier, generatedAt, and command. + +### Artifact-specific generated payload fields + +Artifact-specific generated payload fields: prompt ids, PromptPart ids, phase ids, agent ids, step ids, Failsafe ids, ThricifiedGeneration ids, tool ids, fit ids, ranking roots, and settlement roots. + +### Artifact confidentiality and disclosability taxonomy + +Artifact confidentiality and disclosability taxonomy: public, source-safe, buyer-visible, reviewer-visible, operator-only, and forbidden. + +### Minimum generated appendix rendered contents + +The generated appendix must include 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 generated proof evidence is stale, missing, or unsafe. + +### Canonical regeneration and fail-closed posture + +Canonical regeneration and fail-closed posture require V39 scripts to regenerate artifacts deterministically and fail closed on missing source roots, missing prompt ids, missing schema verdicts, unsafe telemetry payloads, stale proof-source commit, or mismatched canonical pointer. + +## Appendix D. Validation and checking gate catalog + +V39 validation begins with `check:v39-gate1` and expands through Gate 11. +Gate checks must be scriptable, workflow-wired, source-safe, and specific enough to identify the missing source or artifact. + +## Appendix E. Current canonical source map + +Current source map roots include `packages/agent-generics`, `packages/prompts`, `packages/tools-generics`, `packages/pipelines/asset-pack`, `packages/protocol`, `packages/api`, `uapi`, `.github/workflows`, `scripts`, and `protocol-demonstration` as a standalone minimal witness. + +## Appendix F. Subsystem totality and derivability matrix + +Subsystem totality coverage includes repo supply and depositing, reading and measured demand, prompt/inference/evaluator ownership, deposit-to-read fit, recall and ranking, verification decisions, selection and materialization, branch artifacts and assetPackEvidence, identity, authority, signing, and policy, sensitive data and confidentiality flows, projection, disclosure, and redaction, proof families, members, theorems, witnesses, and replay, settlement, source-to-shares, journals, and exact accounting, telemetry, persistence, state, and failure semantics, host/runtime capability truth, operator experience and pedagogy, validation and test stack, generated artifacts and canonical promotion. + +## Appendix G. Canonical file-family and promotion contract catalog + +The V39 file family is `BITCODE_SPEC_V39.md`, `BITCODE_SPEC_V39_DELTA.md`, `BITCODE_SPEC_V39_NOTES.md`, `BITCODE_SPEC_V39_PARITY_MATRIX.md`, and eventually `BITCODE_SPEC_V39_PROVEN.md`. +Promotion may update `BITCODE_SPEC.txt` only after all gates close and promotion validation succeeds. + +## Appendix H. Operator surface and quality contract catalog + +Operator surfaces include Terminal, Conversations, API, MCP API, ChatGPT App, Auxillaries, Exchange, generated proof reports, dashboards, runbooks, and local/staging rehearsal surfaces. +V39 operator quality requires collapsed readable state and expanded source-safe detail for the full Reading product path, including pipeline telemetry, preview/quote posture, settlement, rights, delivery, and repair. + +## Appendix I. Scenario, workflow, and cross-product contract catalog + +Scenario and workflow coverage includes 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 workflows. + +## Appendix J. Fail-closed contract and error posture matrix + +Fail-closed conditions include 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. + +## Appendix K. Source-bearing AssetPack and artifact contract catalog + +Source-bearing AssetPack and artifact contracts include `.bitcode/asset-pack.lock.json`, `.bitcode/selected-source-material.json`, `.bitcode/verification-report.json`, `.bitcode/source-to-shares.json`, `.bitcode/projection-policy.json`, `.bitcode/system-proof-bundle.json`, and `BITCODE_SPEC_V39_PROVEN.md`. +V39 may expose only source-safe preview metadata before settlement. + +## accepted boundaries and reopen conditions + +Accepted boundaries: V39 can harden inference, prompt benchmarking, search, telemetry, and traceability; V39 cannot change BTD supply law, route versioning discipline, mainnet admission, or settlement finality law without explicit later promotion. +Reopen conditions: evidence of prompt leakage, inference bypassing primitives, untraceable fit selection, unsafe telemetry, broken depository search, or stale generated proof. + +## completion condition + +V39 is complete only when every V39 gate is implemented, specified, tested, documented, generated, workflow-wired, source-safe, locally/staging rehearsed where applicable, and promotion-ready with `BITCODE_SPEC_V39_PROVEN.md` support. diff --git a/BITCODE_SPEC_V39_DELTA.md b/BITCODE_SPEC_V39_DELTA.md new file mode 100644 index 000000000..eaef5b4be --- /dev/null +++ b/BITCODE_SPEC_V39_DELTA.md @@ -0,0 +1,194 @@ +# Bitcode Spec V39 Delta + +## Status + +- Version: `V39` +- V39 state: draft opened; this delta records the planned V38-to-V39 commercial Reading readiness closure set +- Current canonical/latest target: `V38` +- Draft proof-source commit: unbound until V39 promotion +- Prior canonical anchor: `BITCODE_SPEC_V38.md` +- Prior generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md` +- Generated structured artifact inventory: draft opening requires `.bitcode/v39-spec-family-report.json` and `.bitcode/v39-canonical-input-report.json`; later V39 gates must add package-backed source-safe artifacts for Depository indexing, Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime, AssetPack preview/quote, settlement/delivery rights, telemetry/repair, interface parity, rehearsal, and promotion readiness +- Source parity state: V39 delta opens parity requirements; implementation parity remains pending until each V39 gate closes with source, artifacts, tests, workflow checks, and source-safe documentation +- Spec companion: `BITCODE_SPEC_V39.md` +- Notes companion: `BITCODE_SPEC_V39_NOTES.md` +- Parity companion: `BITCODE_SPEC_V39_PARITY_MATRIX.md` +- Generated proof appendix: `BITCODE_SPEC_V39_PROVEN.md` only after V39 promotion +- Scope: V39 draft delta for commercial Reading readiness over promoted V38 inference correctness canon + +## Why V39 exists + +V38 promoted inference correctness. +It made pipeline execution, PTRR agents, FailsafeGenerationSequence, ThricifiedGeneration, prompt benchmarking, source-safe inference telemetry, and Reading fit-search primitives exact enough to use as production-grade infrastructure. + +V39 exists because Bitcode now needs the full enterprise Reading path to become commercially reliable. +V39 closes product runtime gaps across Depository supply indexing, Read Request capture, reviewable ReadNeed synthesis and resynthesis, Finding Fits across many candidate deposits, source-safe AssetPack preview, deterministic BTC quote, BTD rights transfer, post-settlement delivery, ledger/database/storage synchronization, repair, and interface parity. + +## Accepted V39 decisions + +- V38 remains active canon during V39 drafting. +- V39 gate branches are opened from `version/v39` and merged back only when their gate acceptance criteria are closed. +- V39 owns commercial Reading readiness across Terminal, Conversation, MCP/API, ChatGPT App, package contracts, Depository, ledger, database, storage, wallet, and delivery surfaces. +- V38 inference law remains binding: PTRR agent steps use `FailsafeGenerationSequence` above `ThricifiedGeneration`, tools are step-owned, prompt registry composition is preserved, and telemetry disclosure tiers govern all inference evidence. +- `ReadNeedComprehensionSynthesis` must become a persisted review/resynthesis loop whose accepted Need gates Finding Fits. +- `ReadFitsFindingSynthesis` must discover many candidate deposits above threshold before AssetPack synthesis and settlement handoff. +- Fit-finding must preserve the active OpenAI embedding policy (`text-embedding-3-small`, 1536 dimensions, cosine `match_deliverable_vectors`) unless a replacement is explicitly specified, tested, and migrated. +- Source-bearing AssetPack delivery is forbidden before settlement unlock and BTD rights transfer. + +## Explicitly deferred + +- Production-mainnet value-bearing launch remains blocked. +- Bridge chain-of-record implementation remains deferred. +- V39 does not reopen BTD supply law, Exchange law, or Bitcoin settlement law except for inference and fit-finding traceability needed by AssetPack preview and post-settlement delivery. +- New LlamaIndex, Pinecone, or provider-specific search channels may be specified only after boundaries, credentials, storage, telemetry, and tests are explicit. + +## Pre-Implementation Sequence + +1. Open `version/v39` from promoted `main`. +2. Open `v39/gate-1-commercial-reading-roadmap-opening` from `version/v39`. +3. Create the V39 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V38`. +4. Refresh `SPECIFICATIONS_ROADMAP.md` so V38 is active canon, V39 is draft target, and post-V39 work remains coherent. +5. Retarget gate-quality and canon-quality workflow posture checks to V38 active / V39 draft. +6. Add `check:v39-gate1` and a V39 Gate 1 checker. +7. Define V39 gates, acceptance criteria, carryforward parity rows, and promotion boundaries. +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/v39`. + +## Commit-Body Direction + +V39 gate commit bodies should describe the closed gate, product surface, pipeline/runtime changes, generated proof artifacts, tests, telemetry/disclosure boundaries, and accepted deferrals. +The eventual V39 promotion commit body must name all closed V39 gates, generated commercial Reading proof artifacts, Depository indexing evidence, ReadNeed and ReadFitsFinding runtime evidence, AssetPack preview/quote evidence, settlement/delivery evidence, telemetry/repair evidence, local/staging rehearsal proof, promotion workflow evidence, and the `BITCODE_SPEC.txt` pointer change from `V38` to `V39`. + +## Gate Delta + +### Gate 1: V39 Commercial Reading Roadmap And Spec Opening + +Gate 1 opens V39 correctly: + +- V39 SPEC, DELTA, NOTES, and PARITY files exist. +- `BITCODE_SPEC.txt` remains `V38`. +- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V38 active / V39 draft posture. +- `check:v39-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, inference vocabulary, depository-search vocabulary, and promotion boundaries. +- The V39 gate list is explicit before inference implementation begins. + +### Gate 2: Depository Supply Indexing And Searchable Deposit Lifecycle + +Closure acceptance: + +- deposited source materials are measurable, indexable, vector-searchable, metadata-searchable, rights-aware, and repairable; +- deposit lifecycle receipts bind repository/deposit anchors, measurement roots, embedding roots, ownership boundaries, and source-safe telemetry; +- `pnpm run check:v39-gate2` validates package-backed source, generated artifact freshness, tests, and workflow wiring without exposing protected source or credentials. + +Closure implementation: + +- Pending Gate 2 work must define its package-owned canonical source and deterministic artifact path before implementation begins. +- The artifact must use a source-safe disclosure posture and include repair/replay acceptance criteria. + +### Gate 3: Enterprise Reading UX State Machine + +Closure acceptance: + +- Terminal implements the five-step enterprise Reading flow: request read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, buy and settle; +- each step has clear low-detail default UI and expandable source-safe detail; +- `pnpm run check:v39-gate3` validates state contracts, component tests, browser proof, and disclosure boundaries. + +Closure implementation: + +- Pending Gate 3 work must define route contracts, UI tests, and generated UX-state proof artifact. + +### Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime + +Closure acceptance: + +- `ReadNeedComprehensionSynthesis` persists Read Requests, synthesized Needs, feedback, resynthesis attempts, Need measurements, accepted-Need admission, rejected-Need posture, and source-safe telemetry receipts; +- Finding Fits remains blocked until a reviewed Need is accepted; +- `pnpm run check:v39-gate4` validates pipeline contracts, storage, telemetry, UI, tests, artifact freshness, and workflow wiring. + +Closure implementation: + +- Pending Gate 4 work must define package-backed source, deterministic artifact, pipeline tests, route tests, and accepted-Need admission tests. + +### Gate 5: ReadFitsFinding Runtime, Ranking, And Replay + +Closure acceptance: + +- Finding Fits uses inference-derived queries and depository search tools across lexical, symbolic, path, metadata, measurement, embedding/vector, and provider-specific channels; +- candidate deposits above threshold are ranked, verified, replayable, and traceable into selected-fit provenance; +- `pnpm run check:v39-gate5` validates search tools, embeddings, ranking, thresholding, replay receipts, tests, and generated evidence. + +Closure implementation: + +- Pending Gate 5 work must define runtime search artifacts, active embedding policy checks, and many-candidate replay evidence. + +### Gate 6: AssetPack Preview, Quote, And Disclosure Boundary + +Closure acceptance: + +- source-safe AssetPack preview exposes measurements, fit reasons, selected-fit provenance, proof roots, quality posture, deterministic BTC quote, and delivery posture; +- source-bearing AssetPack content remains blocked until settlement unlock; +- `pnpm run check:v39-gate6` validates quote determinism, preview disclosure, leak scanning, tests, and generated evidence. + +Closure implementation: + +- Pending Gate 6 work must define preview/quote artifacts, disclosure tests, and deterministic quote source. + +### Gate 7: Settlement, BTD Rights Transfer, And Delivery + +Closure acceptance: + +- BTC settlement observation, finality, BTD rights transfer, source-to-shares compensation, post-settlement delivery, and repair paths are auditable; +- ledger, database, and object-storage projections remain synchronized or repairable; +- `pnpm run check:v39-gate7` validates settlement, rights, delivery, repair, and synchronization evidence. + +Closure implementation: + +- Pending Gate 7 work must define settlement/delivery artifacts, receipt tests, and PR delivery repair evidence. + +### Gate 8: Operational Telemetry, Repair, And Operator Readback + +Closure acceptance: + +- Reading telemetry streams source-safe phase, agent, step, Failsafe, ThricifiedGeneration, tool, storage, ledger, wallet, delivery, and UI events; +- operator readback binds proof roots, runbook hooks, repair commands, and failure posture; +- `pnpm run check:v39-gate8` validates telemetry contracts, UI readback, repair proof, and source-safe disclosure. + +Closure implementation: + +- Pending Gate 8 work must define telemetry/repair artifacts and route or component tests. + +### Gate 9: Interface And Conversation Product Parity + +Closure acceptance: + +- Conversation, MCP/API, ChatGPT App, and package-facing interfaces obey the same Reading authority as Terminal; +- no interface bypasses accepted-Need gating, source-safe preview, settlement unlock, BTD rights, or delivery boundaries; +- `pnpm run check:v39-gate9` validates interface contract tests, Conversation handoff tests, and no-bypass posture. + +Closure implementation: + +- Pending Gate 9 work must define interface parity artifacts and consumer contract tests. + +### Gate 10: Local And Staging Commercial Reading Rehearsal + +Closure acceptance: + +- local and staging-testnet rehearsals run the five-step Reading flow with real non-mocked inference where credentials are available; +- rehearsals cover Depository search, source-safe preview, telemetry streaming/readback, ledger/database/storage synchronization, PR delivery posture, and blocked production-mainnet value-bearing admission; +- `pnpm run check:v39-gate10` validates rehearsal evidence and workflow wiring. + +Closure implementation: + +- Pending Gate 10 work must define local/staging artifacts, credential gates, and source-safe rehearsal evidence. + +### Gate 11: V39 Promotion Readiness + +Closure acceptance: + +- all V39 gates are closed; +- V39 generated proof appendix support exists; +- promotion workflow validates V39 and commits only the canonical pointer and generated promotion artifacts; +- `pnpm run check:v39-gate11` validates promotion readiness, source-safety, generated artifacts, and V39 draft posture preparation. + +Closure implementation: + +- Pending Gate 11 work must define the package-backed commercial Reading promotion readiness report, V39 promotion workflow, promotion command support, generated proof appendix support, active V39 / draft V40 post-promotion posture, and blocked value-bearing mainnet evidence. diff --git a/BITCODE_SPEC_V39_NOTES.md b/BITCODE_SPEC_V39_NOTES.md new file mode 100644 index 000000000..c54bc94de --- /dev/null +++ b/BITCODE_SPEC_V39_NOTES.md @@ -0,0 +1,236 @@ +# Bitcode Spec V39 Notes + +## Status + +- Version: `V39` +- V39 state: draft opened; V39 notes record planned commercial Reading readiness work over promoted V38 inference correctness +- Current canonical/latest target: `V38` +- Draft proof-source commit: unbound until V39 promotion +- Current active draft target: `V39` +- Prior canonical anchor: `BITCODE_SPEC_V38.md` +- Prior generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md` +- Generated structured artifact inventory: draft opening requires `.bitcode/v39-spec-family-report.json` and `.bitcode/v39-canonical-input-report.json`; later V39 gates must add package-backed source-safe artifacts for Depository indexing, Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime, AssetPack preview/quote, settlement/delivery rights, telemetry/repair, interface parity, rehearsal, and promotion readiness +- Source parity state: V39 source-side parity is opened but not closed; each gate must close implementation, generated proof, tests, documentation, and source-safe telemetry before V39 promotion +- Spec companion: `BITCODE_SPEC_V39.md` +- Delta companion: `BITCODE_SPEC_V39_DELTA.md` +- Parity companion: `BITCODE_SPEC_V39_PARITY_MATRIX.md` +- Scope: V39 draft notes for commercial Reading readiness over promoted V38 inference correctness canon +- Last fully realized canonical target preserved in source: `V38` + +This NOTES file does not promote V39. It is binding draft guidance while V39 gates are in flight. + +## Notes companion rule + +This file is the V39 notes companion. +Requirements are binding for V39 gate work while `BITCODE_SPEC.txt` remains `V38`. + +## Simplified-spec reading rule + +Read `BITCODE_SPEC.txt` first. +If it points to `V38`, V38 is active canon and V39 is the active draft target only when this V39 SPEC family exists on a V39 branch. +Read `BITCODE_SPEC_V39.md`, this NOTES companion, the V39 DELTA, and the V39 PARITY matrix together before implementing inference work. + +## Concise current-system reading + +V38 is active canon and inference correctness is promoted. +V39 is the draft target that focuses on commercial Reading readiness across deposited source supply, the five-step enterprise Reading UX, ReadNeed review/resynthesis, ReadFitsFinding many-candidate depository search, source-safe AssetPack preview, deterministic quote, settlement, BTD rights transfer, post-settlement delivery, and operational telemetry/repair. + +## Deferred from V38 + +V38 promoted the inference stack and its source-safe telemetry/disclosure law. +V39 should use that stack to close the commercial Reading product path end to +end, fully using Bitcode's existing pipeline, agent, prompt, execution, tool, +telemetry, registry, ledger, database, storage, wallet, and delivery primitives +without weakening any runtime boundary. + +Source anchors already exist and must be audited before V39 implementation: + +- `packages/agent-generics/src/steps/failsafe-sequence.ts` defines + `FailsafeGenerationSequence` as prepare-concise-context, chunk-then-sum, and + stitch-until-complete wrappers over `ThricifiedGeneration`. +- `packages/agent-generics/src/steps/thricified-generation.ts` defines + `ThricifiedGeneration` as the strict Reason, Judge, StructuredOutput chain. +- `packages/agent-generics/src/agents/factories.ts` requires + `factoryAgentWithPTRR` callers to provide an agent prompt plus complete + Plan, Try, Refine, and Retry step prompt registries. +- `packages/tools-generics/src/Tool.ts`, + `packages/tools-generics/src/doc-code-tool/DocCodeToolPrompt.ts`, and + `packages/tools-generics/src/doc-code-tool/formatUsableTools.ts` define the + doc-comment-backed tool prompt path that inference prompts must consume. +- `packages/pipelines/asset-pack/src/reading-pipeline-contract.ts`, + `packages/pipelines/asset-pack/src/read-need.ts`, + `packages/pipelines/asset-pack/src/depository-search.ts`, and + `packages/pipelines/asset-pack/src/tools/*DepositorySearchTool*` define the + current `ReadNeedComprehensionSynthesis` and + `ReadFitsFindingSynthesis` contracts, tools, search result shape, and + source-safe preview boundary. + +Thricification remains the lowest-level inference call chain. It is the final +place where phase, agent, step, substep, tool-documentation, and generation +prompt registries are resolved, composed, interpolated, and constrained to the +typed output. Failsafe chains may prepare context, chunk large inputs, summarize +or stitch large outputs, retry repairable typed-output failures, and organize +execution ancestry state around those calls, but inside PTRR agents they must +delegate final reason, judge-reasoning, and structured typed response +production to `ThricifiedGeneration`. + +Tools remain step-owned capability executions, not hidden children of +`ThricifiedGeneration`. Tool definitions must still be represented in final +prompts through the doc-comment `DocCodeToolPrompt` path, composed and +interpolated at the lowest inference point with the same source-safe telemetry +discipline as all other prompt material. + +## Candidate V39 workstreams + +- Make Depository supply operational for Reading: deposited source materials + must be measured, embedded, indexed, rights-aware, searchable, repairable, + and source-safe in all generated artifacts and logs. +- Implement the five-step enterprise Reading UX: request read, review + synthesized Need, request Finding Fits, review source-safe AssetPack preview, + buy AssetPack and settle. +- Make `ReadNeedComprehensionSynthesis` a persisted review loop with feedback + and resynthesis. Accepted Need is the only admission path into Finding Fits. +- Make `ReadFitsFindingSynthesis` a runtime search pipeline over the whole + available Depository, gathering many above-threshold candidate deposits before + selected-fit provenance is handed into AssetPack synthesis. +- Make source-safe AssetPack preview commercially sufficient without IP leakage: + show measurements, fit reasons, selected-fit provenance, quality posture, + proof roots, deterministic BTC quote, and delivery posture while withholding + source-bearing AssetPack content until settlement unlock. +- Make settlement, BTD rights transfer, contributor compensation, post-settlement + delivery, ledger/database/object-storage synchronization, repair, and replay + auditable as one paid boundary. +- Preserve V38 inference law throughout every Reading runtime surface. Pipeline + phases, PTRR agents, FailsafeGenerationSequence, ThricifiedGeneration, + DocCodeToolPrompt, prompt benchmarking, disclosure tiers, and telemetry roots + remain binding infrastructure, not optional implementation detail. +- Audit every inference point used by the Reading product. The audit must count + base primitives and specific implementations separately: phase prompts, PTRR + agent prompts, step prompts, Failsafe substep prompts, ThricifiedGeneration + prompts, tool prompt definitions, prompt templates, interpolation bindings, + expected context fields, raw outputs, parsed typed outputs, and repair/failure + surfaces. +- Specify the exact execution stack for pipeline agents without overlapping + names: PipelineExecution owns phases; PTRR agents own Plan, Try, Refine, and + Retry steps; FailsafeGenerationSequence owns context preparation, large input + handling, large output handling, and repair orchestration; ThricifiedGeneration + owns Reason, Judge, and StructuredOutput inference calls; ToolExecution owns + callable tools and tool input/output receipts. +- Require all PTRR agent steps to use practical FailsafeGenerationSequence + layers above ThricifiedGeneration unless a source-backed exception is + specified, tested, and justified. The default Reading stack should be + PipelineExecution -> PTRR agent -> PTRR step -> FailsafeGenerationSequence -> + ThricifiedGeneration -> provider call. +- Finish prompt and PromptPart benchmarking so semantically divided + PromptParts and complete Prompts are both benchmarkable. V39 Gate 1 should + inventory existing `benchmarks:` doc-comment metadata, the + `packages/prompts/src/benchmarking/*` runner, and all Reading and + conversation prompt surfaces, then define initial benchmark suites for every + prompt part and prompt used by active inference. +- Complete prompt registry composition and interpolation rules from phase + prompts through agent prompts, step prompts, substep prompts, final generation + prompts, and tool documentation. The final inference call must expose the + unrendered template identity, interpolated prompt, context bindings, selected + tools, raw response, parsed output, and schema verdict to telemetry at the + proper disclosure tier. +- Integrate this inference work with prior telemetry. Execution ancestry + state-stack data must be written, read, prepared by Failsafe layers, + interpolated into prompts, maintained through retries, and streamed as + source-safe phase, agent, step, Failsafe, ThricifiedGeneration, tool, input, + output, and typed-result events. +- Complete `ReadFitsFindingSynthesis` depository-search internals as the + coupled second focus of V39. Fit-finding queries are inference-derived and + must search throughout the Bitcode Depository using lexical, symbolic, path, + metadata, measurement, embedding/vector, and provider-specific channels where + appropriate. +- Harden the depository-search tool and primitive utility stack around source + embeddings, measurement embeddings, metadata embeddings, query synthesis, + ranking, verification, and AssetPack synthesis handoff. Existing OpenAI + embedding policy (`text-embedding-3-small`, 1536 dimensions, cosine + `match_deliverable_vectors`) is an active source anchor, and V39 may specify + additional LlamaIndex, Pinecone, or provider-backed channels only when their + boundaries, storage, credentials, telemetry, and tests are explicit. +- Preserve the economic carry-through from found fits to AssetPack settlement: + selected fit deposits must remain traceable into source-safe preview, + post-settlement delivery, contributor compensation, exact ledger/database + synchronization, and proof receipts. +- Clarify how Bitcoin, GitHub, compute, storage, and build/process boundaries + are represented in long-running inference and pipeline telemetry. +- Confirm that source-safe telemetry exposes prompt templates, interpolated + prompts, raw provider responses, parsed typed results, repair attempts, and + failed-output evidence only at their permitted disclosure tier. + +The V39 acceptance posture is commercial Reading readiness: Bitcode's ability +to maximize inference intelligence must become a reliable enterprise experience +for depositing, finding, buying, rights-transferring, and delivering precise +technical intelligence without leaking protected source before settlement. + +## Gate 1 implementation notes + +Gate 1 turns the loose post-V38 notes committed on `main` plus the promoted V38 posture into the formal V39 SPEC, DELTA, NOTES, and PARITY family. +The opening must preserve every relevant V38 instruction while grounding V39 in existing source anchors: `FailsafeGenerationSequence`, `ThricifiedGeneration`, PTRR agent factories, tool doc-comment prompt definitions, Reading pipeline contracts, depository-search tools, embedding policy, ledger/database/storage receipts, delivery boundaries, and source-safe telemetry boundaries. +Gate 1 adds `check:v39-gate1`, workflow posture updates, README and package documentation posture updates, and roadmap truth for V38 active / V39 draft. + +## Gate 2 implementation notes + +Gate 2 closes Depository supply indexing and searchable deposit lifecycle. The artifact must prove deposited source can be measured, embedded, indexed, rights-aware, and searched without exposing protected source or credentials. + +## Gate 3 implementation notes + +Gate 3 closes the enterprise Reading UX state machine. Terminal and Conversation handoff must expose the five-step Reading path with low-detail guidance by default and expandable source-safe pipeline detail. + +## Gate 4 implementation notes + +Gate 4 closes `ReadNeedComprehensionSynthesis` as a review, feedback, and resynthesis loop. Finding Fits remains blocked until a reviewed Need is accepted. + +## Gate 5 implementation notes + +Gate 5 closes `ReadFitsFindingSynthesis` as a runtime many-candidate search pipeline with replayable query, ranking, threshold, and selected-fit provenance receipts across lexical, symbolic, path, metadata, measurement, vector, and provider-specific channels. + +## Gate 6 implementation notes + +Gate 6 closes the source-safe AssetPack preview and deterministic BTC quote boundary. Preview can show measurements, fit reasons, quality posture, proof roots, quote, and delivery posture, but not source-bearing AssetPack content. + +## Gate 7 implementation notes + +Gate 7 closes settlement, BTD rights transfer, contributor compensation, and post-settlement delivery. Source-bearing delivery is unlocked only after settlement finality and rights transfer are auditable. + +## Gate 8 implementation notes + +Gate 8 closes operational telemetry, repair, and operator readback for Reading. Every pipeline, storage, ledger, wallet, delivery, and UI event must be source-safe, proof-rooted, and tied to repair/runbook posture. + +## Gate 9 implementation notes + +Gate 9 closes interface and Conversation product parity. Conversation, MCP/API, ChatGPT App, and package consumers may assist the flow but cannot bypass accepted-Need gating, preview disclosure, settlement, rights, or delivery law. + +## Gate 10 implementation notes + +Gate 10 closes local and staging commercial Reading rehearsal with real non-mocked inference where credentials are available, Depository search, source-safe preview, telemetry readback, ledger/database/storage synchronization, delivery posture, and blocked production-mainnet value-bearing admission. + +## Gate 11 implementation notes + +Gate 11 closes V39 by binding every commercial Reading gate artifact, V39 proof appendix generation, workflow posture, promotion command support, and post-promotion runtime posture into one source-safe promotion-readiness contract. After promotion, runtime posture must become active V39 / draft V40 and `BITCODE_SPEC.txt` may point to V39 only through the V39 promotion workflow. + +## V39 gate plan + +- Gate 1: V39 Commercial Reading Roadmap And Spec Opening +- Gate 2: Depository Supply Indexing And Searchable Deposit Lifecycle +- Gate 3: Enterprise Reading UX State Machine +- Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime +- Gate 5: ReadFitsFinding Runtime, Ranking, And Replay +- Gate 6: AssetPack Preview, Quote, And Disclosure Boundary +- Gate 7: Settlement, BTD Rights Transfer, And Delivery +- Gate 8: Operational Telemetry, Repair, And Operator Readback +- Gate 9: Interface And Conversation Product Parity +- Gate 10: Local And Staging Commercial Reading Rehearsal +- Gate 11: V39 Promotion Readiness + +## Non-goals during V39 opening + +- No new production route, API version, source package name, or UI label should + carry V39 in source code during the notes-only opening. +- No Bitcoin, GitHub, compute, storage, wallet, ledger, delivery, or + build/process runtime boundary may be weakened while commercial Reading is + being made product-ready. +- No later V39 gate may begin until Gate 1 creates the full draft family, + updates the roadmap, and wires `check:v39-gate1`. diff --git a/BITCODE_SPEC_V39_PARITY_MATRIX.md b/BITCODE_SPEC_V39_PARITY_MATRIX.md new file mode 100644 index 000000000..69f5b4d7e --- /dev/null +++ b/BITCODE_SPEC_V39_PARITY_MATRIX.md @@ -0,0 +1,137 @@ +# Bitcode Spec V39 Parity Matrix + +## Status + +- Version: `V39` +- V39 state: draft opened; V39 parity truth defines commercial Reading readiness work over promoted V38 inference correctness +- Current canonical/latest target: `V38` +- Draft proof-source commit: unbound until V39 promotion +- Prior canonical anchor: `BITCODE_SPEC_V38.md` +- Prior generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md` +- Generated structured artifact inventory: draft opening requires `.bitcode/v39-spec-family-report.json` and `.bitcode/v39-canonical-input-report.json`; later V39 gates must add package-backed source-safe artifacts for Depository indexing, Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime, AssetPack preview/quote, settlement/delivery rights, telemetry/repair, interface parity, rehearsal, and promotion readiness +- Source parity state: V39 parity is open; Gate 1 closes roadmap/spec/workflow posture and later gates must close implementation parity before promotion +- Spec companion: `BITCODE_SPEC_V39.md` +- Notes companion: `BITCODE_SPEC_V39_NOTES.md` +- Delta companion: `BITCODE_SPEC_V39_DELTA.md` +- Generated proof appendix: `BITCODE_SPEC_V39_PROVEN.md` only after V39 promotion +- Scope: V39 draft parity ledger for commercial Reading readiness over promoted V38 inference correctness canon +- Last fully realized canonical target preserved in source: `V38` + +## Purpose + +The V39 parity matrix prevents commercial Reading from becoming a partial demo, hidden pipeline run, one-off search path, unpriced preview, or settlement/delivery boundary that cannot be audited. +Every V39 gate must name the product stage it closes, primitive stack it uses, source evidence, generated artifacts, tests, prompt identities, disclosure tiers, depository-search channels, typed outputs, quote/settlement/delivery receipts, proof roots, and fail-closed repair posture. + +## Audit basis + +Gate 1 audit basis: + +- `BITCODE_SPEC.txt` +- `BITCODE_SPEC_V38.md` +- `BITCODE_SPEC_V38_PROVEN.md` +- `BITCODE_SPEC_V39.md` +- `BITCODE_SPEC_V39_DELTA.md` +- `BITCODE_SPEC_V39_NOTES.md` +- `BITCODE_SPEC_V39_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` +- `packages/agent-generics/src/steps/failsafe-sequence.ts` +- `packages/agent-generics/src/steps/thricified-generation.ts` +- `packages/agent-generics/src/agents/factories.ts` +- `packages/tools-generics/src/Tool.ts` +- `packages/tools-generics/src/doc-code-tool/DocCodeToolPrompt.ts` +- `packages/tools-generics/src/doc-code-tool/formatUsableTools.ts` +- `packages/pipelines/asset-pack/src/reading-pipeline-contract.ts` +- `packages/pipelines/asset-pack/src/read-need.ts` +- `packages/pipelines/asset-pack/src/depository-search.ts` +- `packages/pipelines/asset-pack/src/tools/AssetPackLexicalDepositorySearchTool.ts` +- `scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs` +- later V39 gate-specific generated artifacts, package sources, tests, and checker scripts as added by their gates + +No `_legacy/` source is active source truth. + +## V39 implementation matrix + +| Area | Gate | Source evidence | Judgment | Closure requirement | +| --- | --- | --- | --- | --- | +| Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V39.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v39/gate-1-commercial-reading-roadmap-opening` | drafted | V39 family validates in draft mode over active V38 and `check:v39-gate1` passes. | +| Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V38 active, V39 draft, and coherent post-V39 responsibility. | +| Commercial Reading vocabulary | Gate 1 | five-step Reading UX, `ReadNeedComprehensionSynthesis`, `ReadFitsFindingSynthesis`, AssetPack preview, BTC quote, BTD rights transfer, delivery | drafted | Spec family names the product stages without replacing primitive names. | +| Inference vocabulary | Gate 1 | `PipelineExecution`, PTRR Plan/Try/Refine/Retry, `FailsafeGenerationSequence`, `ThricifiedGeneration`, `ToolExecution`, `DocCodeToolPrompt` | drafted | V38 inference law remains binding on V39 product implementation. | +| Depository search scope | Gate 1 | depository-search source and tools, embedding policy, fit ranking expectations | drafted | Gate plan requires many-candidate Finding Fits across lexical, symbolic, path, metadata, measurement, vector, and provider channels. | +| Settlement and delivery scope | Gate 1 | BTD receipts, source-to-shares compensation, ledger/database/storage synchronization, pull-request delivery | drafted | Gate plan keeps source-bearing AssetPack delivery blocked until settlement unlock. | +| Depository supply indexing | Gate 2 | package source, generated artifact, deposit lifecycle tests, embedding/search projection tests | pending | Deposited source becomes measurable, indexable, rights-aware, searchable, and repairable. | +| Enterprise Reading UX state machine | Gate 3 | Terminal route state, Conversation handoff, rich execution log, browser proof | pending | The five-step enterprise Reading UX is implemented with low-detail defaults and expandable source-safe detail. | +| ReadNeed review and resynthesis | Gate 4 | `ReadNeedComprehensionSynthesis`, Need storage, feedback, resynthesis, accepted-Need admission | pending | Finding Fits remains blocked until a reviewed Need is accepted. | +| ReadFitsFinding runtime and replay | Gate 5 | `ReadFitsFindingSynthesis`, search tools, embeddings, ranking, selected-fit provenance, replay receipts | pending | Finding Fits searches the whole available Depository for many above-threshold candidates. | +| AssetPack preview and quote boundary | Gate 6 | AssetPack preview tests, quote tests, disclosure leak scans, proof roots | pending | Preview is commercially sufficient without exposing source-bearing AssetPack content. | +| Settlement, BTD rights, and delivery | Gate 7 | BTC settlement receipt, BTD rights transfer, source-to-shares, ledger/database/storage, PR delivery | pending | Payment unlocks rights and delivery; repair paths are auditable. | +| Operational telemetry and repair | Gate 8 | stream events, operator readback, runbook hooks, proof roots, repair commands | pending | Reading is observable and repairable end to end. | +| Interface and Conversation parity | Gate 9 | Conversation, MCP/API, ChatGPT App, package contract tests | pending | Interfaces follow Terminal authority and cannot bypass gating, preview, settlement, rights, or delivery boundaries. | +| Local and staging rehearsal | Gate 10 | local/staging lanes, real-inference gates, depository search, preview, settlement/delivery posture | pending | The full Reading flow rehearses in local and staging-testnet with production-mainnet value-bearing admission blocked. | +| Promotion readiness | Gate 11 | V39 promotion report, generated proof appendix, promotion workflow, command dry-run | pending | V39 promotes only after all commercial Reading gates and source-safety evidence close. | + +## V39 implementation checklist + +| Area | Required V39 result | Judgment | +| --- | --- | --- | +| Active canon pointer | `BITCODE_SPEC.txt` remains `V38` during V39 gate work | drafted | +| Gate branch pattern | V39 work happens on `version/v39` or `v39/gate-N-*` branches | drafted | +| Spec-family shape | V39 SPEC, DELTA, NOTES, and PARITY satisfy the full spec-family checker | drafted | +| Gate 1 script | `pnpm run check:v39-gate1` fails closed on stale posture, missing roadmap truth, missing commercial Reading scope, missing source anchors, or missing workflow wiring | drafted | +| Gate-quality workflow | Gate workflow validates V38 active / V39 draft posture and the V39 Gate 1 checker | drafted | +| Canon-quality workflow | Canon workflow validates promoted V38 canon, V39 draft family when present, and V38/V39 posture | drafted | +| Package docs | README, protocol package README, demonstration README, and PR template state V38 active / V39 draft workflow | drafted | +| Depository supply indexing | Deposits become measurable, embedded, indexable, rights-aware, searchable, and repairable | pending | +| Enterprise Reading UX | Terminal implements request read, review Need, request Finding Fits, review preview, buy and settle | pending | +| ReadNeed runtime | `ReadNeedComprehensionSynthesis` persists reviewable Needs, feedback, resynthesis, measurements, and accepted-Need admission | pending | +| ReadFitsFinding runtime | `ReadFitsFindingSynthesis` searches many above-threshold deposits with replayable query, ranking, threshold, and selected-fit provenance receipts | pending | +| Preview and quote | AssetPack preview is source-safe and quote is deterministic before settlement | pending | +| Settlement and delivery | BTC settlement, BTD rights transfer, source-to-shares compensation, ledger/database/storage sync, and delivery are auditable | pending | +| Telemetry and repair | Reading emits source-safe rich stream events and operator readback with proof roots and repair posture | pending | +| Interface parity | Conversation, MCP/API, ChatGPT App, and package consumers cannot bypass Terminal Reading authority | pending | +| Local/staging rehearsal | Full Reading flow rehearses locally and in staging-testnet with mainnet value-bearing admission blocked | pending | +| Promotion readiness | V39 promotes only after every commercial Reading gate and source-safety proof closes | pending | +| Inference stack vocabulary | V39 spec family names `PipelineExecution`, PTRR agents, Plan, Try, Refine, Retry, `FailsafeGenerationSequence`, `ThricifiedGeneration`, `ToolExecution`, `DocCodeToolPrompt`, and provider call boundaries | pending | +| Reading vocabulary | V39 spec family names `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` | pending | +| Depository search vocabulary | V39 spec family names lexical, symbolic, path, metadata, measurement, embedding/vector, provider-specific channels, candidate deposits, ranking, thresholds, and selected-fit provenance | pending | +| Embedding policy | V39 spec family preserves `text-embedding-3-small`, 1536 dimensions, cosine `match_deliverable_vectors` until a tested migration exists | pending | +| Disclosure boundary | V39 telemetry exposes prompt and inference evidence only by disclosure tier and blocks protected source, credentials, unpaid AssetPack source, wallet private material, and private settlement payloads | pending | + +## Gate 1 Parity + +| Requirement | Source evidence | Current V39 judgment | +| --- | --- | --- | +| V39 draft family exists | `BITCODE_SPEC_V39.md`, `BITCODE_SPEC_V39_DELTA.md`, `BITCODE_SPEC_V39_NOTES.md`, `BITCODE_SPEC_V39_PARITY_MATRIX.md` | drafted | +| Active pointer remains V38 | `BITCODE_SPEC.txt` | drafted | +| Branch posture is correct | `version/v39`, `v39/gate-1-commercial-reading-roadmap-opening` | drafted | +| Loose V39 notes are retained | `BITCODE_SPEC_V39_NOTES.md` | drafted | +| Failsafe above Thricified is specified | `packages/agent-generics/src/steps/failsafe-sequence.ts`, `packages/agent-generics/src/steps/thricified-generation.ts`, V39 SPEC/NOTES | drafted | +| PTRR agent naming is precise | `packages/agent-generics/src/agents/factories.ts`, V39 SPEC/DELTA | drafted | +| Tool prompt definitions are included | `packages/tools-generics/src/doc-code-tool/DocCodeToolPrompt.ts`, `packages/tools-generics/src/doc-code-tool/formatUsableTools.ts`, V39 SPEC/NOTES | drafted | +| Reading pipeline scope is exact | `packages/pipelines/asset-pack/src/reading-pipeline-contract.ts`, `packages/pipelines/asset-pack/src/read-need.ts`, V39 SPEC/DELTA | drafted | +| Finding Fits is plural and depository-wide | `packages/pipelines/asset-pack/src/depository-search.ts`, V39 SPEC/DELTA | drafted | +| Gate checker is wired | `scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs`, `package.json`, workflows | drafted | + +## Later Gate Parity + +Later V39 gates must add gate-specific parity sections when their implementation begins. Gate 1 intentionally does not claim closure for Depository indexing, enterprise Reading UX, Need review, Finding Fits runtime, preview/quote, settlement/delivery, telemetry/repair, interface parity, rehearsal, or promotion readiness. + +## accepted boundaries and reopen conditions + +V39 Gate 1 accepts only draft-family, roadmap, workflow, branch, and documentation posture closure. +Later gate scope is intentionally pending and must be reopened into gate-specific parity sections before implementation starts. + +## completion condition + +V39 Gate 1 is complete when `check:v39-gate1`, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-1-*` branch. diff --git a/README.md b/README.md index 33f57d2ff..4226e37eb 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 `V37`; V38 is the active draft target for inference stack and -fit-finding correctness after the promoted Website Conversations canon. +resolves to `V38`; V39 is the active draft target for commercial Reading +readiness after the promoted inference correctness canon. ## Current Product Posture @@ -99,8 +99,8 @@ AssetPack source, or wallet private material. Promotion hardening also keeps Conversation persistence and telemetry redaction on bounded private-key PEM scanning with closed/unclosed PEM tests so static security findings block promotion instead of being waived. -V38 Gate 1 opens the inference stack draft family and `check:v38-gate1` over -active V37. V38 focuses on commercial inference correctness: PTRR agents, +V38 Gate 1 opened the inference stack draft family and `check:v38-gate1` over +active V37. V38 promoted commercial inference correctness: PTRR agents, Plan/Try/Refine/Retry steps, `FailsafeGenerationSequence`, `ThricifiedGeneration`, prompt registry composition, prompt and PromptPart benchmarking, tool doc-comment prompts, source-safe inference telemetry, @@ -242,6 +242,13 @@ AssetPack source, credentials, wallet private material, or private settlement payloads. Use `pnpm run generate:v38-promotion-readiness`, `pnpm run check:v38-promotion-readiness`, and `pnpm run check:v38-gate11` before closing the gate. +V39 Gate 1 opens the commercial Reading readiness draft family and +`check:v39-gate1` over active V38. V39 focuses on Depository supply indexing, +the five-step enterprise Reading UX, ReadNeed review/resynthesis, +ReadFitsFinding runtime and replay, source-safe AssetPack preview and +deterministic BTC quote, settlement, BTD rights transfer, post-settlement +delivery, ledger/database/storage synchronization, telemetry/repair, interface +parity, local/staging rehearsal, and promotion readiness. V36 Gate 2 anchors market-wide activity through the package-owned `ExchangeActivityBook` and the source-safe generated artifact `.bitcode/v36-exchange-activity-book.json`, including listing, bid, ask, @@ -372,10 +379,10 @@ verified signatures. Use a version branch and gate-numbered branches: -1. Create one base branch per draft target, such as `version/v38`. +1. Create one base branch per draft target, such as `version/v39`. 2. Create scoped gate branches from the version branch. Prefix every gate branch - with the gate number, for example `v38/gate-1-inference-stack-roadmap-opening` - or `v38/gate-7-read-fits-finding-search`. + with the gate number, for example `v39/gate-1-commercial-reading-roadmap-opening` + or `v39/gate-5-read-fits-finding-runtime-replay`. 3. Group related work into clear commits with quality commit messages whose titles and bodies describe the proof, implementation, or documentation change. @@ -384,7 +391,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 `V38 Gate 7: ReadFitsFindingSynthesis Depository Search`. + title, for example `V39 Gate 5: ReadFitsFinding Runtime And Replay`. 6. Open the version branch back into `main` only after all gates close and the version is formally promoted as canon. @@ -394,11 +401,14 @@ 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 V38, `v38-canon-promotion.yml` must validate the +run the version promotion workflow. For V38, `v38-canon-promotion.yml` validates the inference stack, Reading pipeline, depository-search, prompt benchmark, telemetry, and rehearsal posture, generate `BITCODE_SPEC_V38_PROVEN.md`, and commit promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from `V37` to `V38` on the version branch. +For V39, Gate 1 opens `version/v39` and the gate-quality posture through +`pnpm run check:v39-gate1` before later gates add generated commercial Reading +artifacts and the V39 promotion workflow. V38 Gates 1 through 11 are wired through `pnpm run check:v38-gate1`, `pnpm run check:v38-gate2`, `pnpm run check:v38-gate3`, `pnpm run check:v38-gate4`, `pnpm run check:v38-gate5`, diff --git a/SPECIFICATIONS_ROADMAP.md b/SPECIFICATIONS_ROADMAP.md index a48965dc4..f36800ff7 100644 --- a/SPECIFICATIONS_ROADMAP.md +++ b/SPECIFICATIONS_ROADMAP.md @@ -2,13 +2,13 @@ ## Status -- Current active canonical pointer: `BITCODE_SPEC.txt` -> `V37` -- Current active canon: `BITCODE_SPEC_V37.md` -- Current draft target: `BITCODE_SPEC_V38.md`. -- Current working gate: V38 Gate 11 Promotion Readiness. -- Next queued gate after V38 Gate 10 closure: V38 Gate 11 Promotion Readiness. -- Latest closed version: V37 Website Conversations, which promoted conversation sessions, route-local history, stream UI/event contracts, fullscreen writing, source selectors, Terminal handoff, persistence/privacy/redaction, telemetry/proof hooks, local/staging rehearsal, and V37 promotion readiness. -- Recent V37 closure anchor: V37 Gate 10 Promotion Readiness generated V37 proof support, promoted `BITCODE_SPEC.txt` to `V37`, prepared V37 active / V38 draft runtime posture, and closed Website Conversations canon. +- Current active canonical pointer: `BITCODE_SPEC.txt` -> `V38` +- Current active canon: `BITCODE_SPEC_V38.md` +- Current draft target: `BITCODE_SPEC_V39.md`. +- Current working gate: V39 Gate 1 Commercial Reading Roadmap And Spec Opening. +- Next queued gate after V39 Gate 1 closure: V39 Gate 2 Depository Supply Indexing And Searchable Deposit Lifecycle. +- Latest closed version: V38 Inference Correctness, which promoted pipeline execution call-stack law, PTRR/Failsafe/Thricified parity, prompt and PromptPart benchmarking, source-safe inference telemetry, ReadNeedComprehensionSynthesis hardening, ReadFitsFindingSynthesis search and embeddings, AssetPack economic traceability, local/staging inference rehearsal, and V38 promotion readiness. +- Recent V38 closure anchor: V38 Gate 11 Promotion Readiness generated V38 proof support, promoted `BITCODE_SPEC.txt` to `V38`, prepared V38 active / V39 draft runtime posture, and closed inference correctness canon. - V34 Gate 2 closure anchor: deployment-depth now owns package-backed `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract` source, deterministic `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json`, and visible `value-bearing-mainnet` blocking through `blocked_future_canon_required`. - V34 Gate 3 closure anchor: deployment-depth now owns package-backed `DistributedExecutionRuntimeReceipt` source, deterministic `.bitcode/v34-distributed-execution-runtime-receipts.json`, `request_response_not_required` long-running work posture, and source-safe roots for pipeline, PTRR agent, ThricifiedGeneration, tool, ledger, wallet, proof, object-storage, and repair work. - V34 Gate 4 closure anchor: deployment-depth now owns package-backed `DeploymentStoragePosture` source, deterministic `.bitcode/v34-deployment-storage-posture.json`, ledger/database/object-storage drift repair fixtures, retention/encryption/backup/rollback/audit posture, and source-bearing AssetPack storage remains locked before settlement. @@ -60,6 +60,7 @@ - V38 Gate 9 closure anchor: Inference correctness depth now owns package-backed `V38ConversationToolPromptInferenceParity` source, deterministic `.bitcode/v38-conversation-tool-prompt-inference-parity.json`, `source-safe-conversation-tool-prompt-inference-parity-metadata`, protocol test, Conversation stream/telemetry tests, Terminal execution-log UI test, ChatGPT App tool prompt/admission tests, generator/checker scripts, workflow wiring, 8 parity rows, 34 passed source predicates, quick-response Conversation PTRR repair, prompt registry and typed schema parity, source-safe telemetry/disclosure posture, DocCodeToolPrompt formatting, ToolPromptRegistry hierarchy, ChatGPT App doc-code prompt carriers, interface no-bypass posture, and protected source/raw prompt/raw provider response/unpaid AssetPack source/credential/private wallet/private settlement payloads kept private or blocked. - V38 Gate 10 closure anchor: Inference correctness depth now owns package-backed `V38LocalStagingInferenceDepositorySearchRehearsal` source, deterministic `.bitcode/v38-local-staging-inference-depository-search-rehearsal.json`, `source-safe-local-staging-inference-depository-search-rehearsal-metadata`, protocol test, Vercel Sandbox harness tests, Reading depository-search tests, route preflight/harness tests, Terminal stream UI tests, generator/checker scripts, workflow wiring, 8 rehearsal rows, 2 lanes, local sandbox opt-in, staging-testnet bounded real-inference preflight, Supabase readback validation, ReadNeedComprehensionSynthesis and ReadFitsFindingSynthesis rehearsal, many-fit search, source-safe AssetPack preview, telemetry streaming/readback, ledger/database posture, blocked production-mainnet value-bearing admission, and protected source/raw prompt/raw provider response/live log payload/unpaid AssetPack source/credential/private wallet/private settlement payloads kept private or blocked. - V38 Gate 11 closure anchor: Inference correctness depth now owns package-backed `V38InferencePromotionReadinessReport` source, deterministic `.bitcode/v38-promotion-readiness-report.json`, `source-safe-inference-promotion-readiness-metadata`, source-safe coverage for all V38 inference artifacts, `BITCODE_SPEC_V38_PROVEN.md` generation support, promotion command dry-run support, `v38-canon-promotion.yml`, active V38 / draft V39 posture preparation, package tests, workflow wiring, and `check:v38-gate11`. +- V39 Gate 1 opening anchor: Commercial Reading readiness opens over promoted V38 with V39 SPEC, DELTA, NOTES, and PARITY files, `check:v39-gate1`, V38 active / V39 draft posture, and an eleven-gate plan for Depository supply indexing, enterprise Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime and replay, AssetPack preview/quote disclosure, settlement/BTD rights/delivery, operational telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness. - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work. This roadmap is not an active system specification. @@ -71,9 +72,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_V37.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. -- Promoted Bitcode history: `BITCODE_SPEC_V26.md` through `BITCODE_SPEC_V36.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. -- Draft and future Bitcode specifications: `BITCODE_SPEC_V38.md`, with companion `DELTA`, `NOTES`, and `PARITY_MATRIX` files while V38 gates are in flight, and later notes files. +- Active Bitcode specifications: `BITCODE_SPEC_V38.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. +- Promoted Bitcode history: `BITCODE_SPEC_V26.md` through `BITCODE_SPEC_V37.md`, with companion `DELTA`, `NOTES`, `PARITY_MATRIX`, and `PROVEN` files. +- Draft and future Bitcode specifications: `BITCODE_SPEC_V39.md`, with companion `DELTA`, `NOTES`, and `PARITY_MATRIX` files while V39 gates are in flight, and later notes files. - Specification discipline references: `BITCODE_SPECIFYING.md` and `BITCODE_SPEC_TEMPLATEGUIDE.md`. ## Roadmap @@ -116,8 +117,9 @@ They are referenced here for specification history only; active implementation w | V34 | `BITCODE_SPEC_V34.md` | promoted historical Bitcode canon | 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.md` | promoted historical Bitcode canon | 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.md` | promoted historical Bitcode canon | 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, pricing/liquidity/wrapper analysis, dispute/repair/revenue-route operations, Exchange UX, local/staging rehearsal, and Exchange-specific tests/proofs. | -| V37 | `BITCODE_SPEC_V37.md` | active canon | Website Conversations after V36: website conversation interface, stream UI/event contracts, fullscreen writing mode, conversation-to-Terminal handoff, source selectors, route-local chat history, persistence/privacy/redaction, telemetry/proof/docs, and any conversational UX not covered by the V28 ChatGPT App MVP. | -| V38 | `BITCODE_SPEC_V38.md` | active draft target | Inference correctness after V37: pipeline execution call stack, PTRR agents, FailsafeGenerationSequence over ThricifiedGeneration, prompt registry composition, PromptPart and Prompt benchmarking, Reading pipeline inference, ReadFitsFindingSynthesis depository search and embeddings, source-safe inference telemetry, local/staging rehearsal, and promotion readiness. | +| V37 | `BITCODE_SPEC_V37.md` | promoted historical Bitcode canon | Website Conversations after V36: website conversation interface, stream UI/event contracts, fullscreen writing mode, conversation-to-Terminal handoff, source selectors, route-local chat history, persistence/privacy/redaction, telemetry/proof/docs, and any conversational UX not covered by the V28 ChatGPT App MVP. | +| V38 | `BITCODE_SPEC_V38.md` | active canon | Inference correctness after V37: pipeline execution call stack, PTRR agents, FailsafeGenerationSequence over ThricifiedGeneration, prompt registry composition, PromptPart and Prompt benchmarking, Reading pipeline inference, ReadFitsFindingSynthesis depository search and embeddings, source-safe inference telemetry, local/staging rehearsal, and promotion readiness. | +| V39 | `BITCODE_SPEC_V39.md` | active draft target | Commercial Reading readiness after V38: Depository supply indexing, enterprise five-step Reading UX, ReadNeed review/resynthesis, ReadFitsFinding many-candidate runtime and replay, source-safe AssetPack preview and deterministic BTC quote, settlement, BTD rights transfer, post-settlement delivery, ledger/database/storage synchronization, operational telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness. | ## Current Planning Spine @@ -133,12 +135,13 @@ They are referenced here for specification history only; active implementation w 10. V35 promoted telemetry and documentation as the prelude to full commercial application testnet rollout. 11. V36 promoted deferred Exchange after the Protocol/Terminal/Auxillaries/interface/deployment/documentation spine matured. 12. V37 promoted website Conversations after Exchange depth was specified and implemented. -13. V38 is the current draft target and returns to inference correctness, Reading pipeline search, and source-safe telemetry after Conversations are promoted. +13. V38 promoted inference correctness, Reading pipeline search, prompt benchmarking, source-safe inference telemetry, and the practical PTRR/Failsafe/Thricified call stack. +14. V39 is the current draft target and turns that inference foundation into commercial Reading readiness: Depository supply indexing, enterprise Reading UX, accepted-Need-gated Finding Fits, AssetPack preview/quote, settlement, rights transfer, delivery, telemetry/repair, interface parity, and local/staging rehearsal. ## Boundary Rules - 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. -- V38+ work must build on V37 active canon and V27 `$BTD` law unless a future promoted spec explicitly supersedes it. +- V39+ work must build on V38 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 04b4d3336..2ab811c29 100644 --- a/package.json +++ b/package.json @@ -214,6 +214,7 @@ "check:v36-gate10": "node scripts/check-v36-gate10-promotion-readiness.mjs", "check:v37-gate1": "node scripts/check-v37-gate1-conversations-roadmap-opening.mjs", "check:v38-gate1": "node scripts/check-v38-gate1-inference-stack-roadmap-opening.mjs", + "check:v39-gate1": "node scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs", "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs", "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check", "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs", diff --git a/packages/protocol/README.md b/packages/protocol/README.md index 0e81d52ea..fc2774606 100644 --- a/packages/protocol/README.md +++ b/packages/protocol/README.md @@ -53,10 +53,17 @@ Current exported commercial helpers include: This is the `V38` active, `V39` draft after V38 promotion posture accepted by V38 canonical promotion. -V38 Gate 1 treats this package as promotion-critical runtime posture and opens -the inference stack specification family for active V37 / draft V38 work. +V39 Gate 1 treats this package as promotion-critical runtime posture and opens +the commercial Reading readiness specification family for active V38 / draft +V39 work. `packages/protocol/src/canon-posture.js` and `packages/protocol/data/state.json` must remain aligned to `V38` active, `V39` draft after promotion. +V39 Gate 1 is wired through `check:v39-gate1` and documents the exact +Depository supply, five-step enterprise Reading UX, ReadNeed review, +ReadFitsFinding runtime, AssetPack preview, deterministic BTC quote, BTD rights +transfer, post-settlement delivery, ledger/database/storage synchronization, +operational telemetry/repair, interface parity, and local/staging rehearsal +scope that later V39 gates must implement. V38 Gate 1 is wired through `check:v38-gate1` and documents the exact PipelineExecution, PTRR agent, Plan/Try/Refine/Retry, FailsafeGenerationSequence, ThricifiedGeneration, ToolExecution, DocCodeToolPrompt, Reading pipeline, diff --git a/packages/protocol/data/state.json b/packages/protocol/data/state.json index 34f3746f8..9316795bf 100644 --- a/packages/protocol/data/state.json +++ b/packages/protocol/data/state.json @@ -12,7 +12,7 @@ "draftSpecPath": "BITCODE_SPEC_V39.md", "draftDeltaPath": "BITCODE_SPEC_V39_DELTA.md", "draftParityPath": "BITCODE_SPEC_V39_PARITY_MATRIX.md", - "inheritedCanonSurfaceLabel": "V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37", + "inheritedCanonSurfaceLabel": "V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37/V38", "heroEyebrow": "Bitcode transactions and activity", "heroLede": "Set the active scenario, select supply, and follow the flow from deposit through settlement.", "heroTip": "Use the guide and lower runtime surfaces when you read exact replay, proof, or settlement detail." diff --git a/packages/protocol/src/canon-posture.js b/packages/protocol/src/canon-posture.js index acbabb6a7..10c7c047e 100644 --- a/packages/protocol/src/canon-posture.js +++ b/packages/protocol/src/canon-posture.js @@ -48,7 +48,7 @@ export function buildCanonPosture() { draftSpecPath: DRAFT_SPEC_PATH, draftDeltaPath: DRAFT_DELTA_PATH, draftParityPath: DRAFT_PARITY_PATH, - inheritedCanonSurfaceLabel: 'V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37', + inheritedCanonSurfaceLabel: 'V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37/V38', heroEyebrow: `${CURRENT_PROJECT_LABEL} transactions and activity`, heroLede: 'Set the active scenario, select supply, and follow the flow from deposit through settlement.', heroTip: 'Use the guide and lower runtime surfaces when you read exact replay, proof, or settlement detail.' diff --git a/packages/protocol/test/protocol-package-boundary.test.js b/packages/protocol/test/protocol-package-boundary.test.js index 9956a287a..b59b0d70f 100644 --- a/packages/protocol/test/protocol-package-boundary.test.js +++ b/packages/protocol/test/protocol-package-boundary.test.js @@ -57,6 +57,7 @@ test('@bitcode/protocol commercial formalization exports package-native canon he V35: { activeCanon: 'V35', draftTarget: 'V36' }, V36: { activeCanon: 'V36', draftTarget: 'V37' }, V37: { activeCanon: 'V37', draftTarget: 'V38' }, + V38: { activeCanon: 'V38', draftTarget: 'V39' }, }; const expectedPosture = expectedPostureByPointer[pointer]; diff --git a/protocol-demonstration/README.md b/protocol-demonstration/README.md index d62f3b671..e6e41ddeb 100644 --- a/protocol-demonstration/README.md +++ b/protocol-demonstration/README.md @@ -4,8 +4,9 @@ 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 `V38`; V39 is the next draft target after this promotion. This demo is governed by the active V38 canonical -spec and `BITCODE_SPEC_V38_PROVEN.md` as the current generated appendix. +resolves to `V38`; V39 is the active draft target for commercial Reading +readiness. This demo is governed by the active V38 canonical spec and +`BITCODE_SPEC_V38_PROVEN.md` as the current generated appendix. `BITCODE_SPEC.txt -> V38`. V35 telemetry/documentation work may compare against demonstration facts, but the demonstration remains self-contained and does not import commercial runtime diff --git a/protocol-demonstration/src/canon-posture.js b/protocol-demonstration/src/canon-posture.js index acbabb6a7..10c7c047e 100644 --- a/protocol-demonstration/src/canon-posture.js +++ b/protocol-demonstration/src/canon-posture.js @@ -48,7 +48,7 @@ export function buildCanonPosture() { draftSpecPath: DRAFT_SPEC_PATH, draftDeltaPath: DRAFT_DELTA_PATH, draftParityPath: DRAFT_PARITY_PATH, - inheritedCanonSurfaceLabel: 'V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37', + inheritedCanonSurfaceLabel: 'V16/V17/V18/V19/V20/V21/V22/V23/V24/V25/V26/V27/V28/V29/V30/V31/V32/V33/V34/V35/V36/V37/V38', heroEyebrow: `${CURRENT_PROJECT_LABEL} transactions and activity`, heroLede: 'Set the active scenario, select supply, and follow the flow from deposit through settlement.', heroTip: 'Use the guide and lower runtime surfaces when you read exact replay, proof, or settlement detail.' diff --git a/protocol-demonstration/test/v21-specifying.test.js b/protocol-demonstration/test/v21-specifying.test.js index d32ad4c0c..eaaf6f21e 100644 --- a/protocol-demonstration/test/v21-specifying.test.js +++ b/protocol-demonstration/test/v21-specifying.test.js @@ -25,6 +25,7 @@ function expectedActiveCanonicalInputArtifactCount(version) { V35: 0, V36: 0, V37: 0, + V38: 0, }; if (Object.hasOwn(expectedCountsByVersion, version)) { return expectedCountsByVersion[version]; diff --git a/scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs b/scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs new file mode 100644 index 000000000..b0fbc25f2 --- /dev/null +++ b/scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs @@ -0,0 +1,291 @@ +#!/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}.*$`, 'imu').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-v39-gate1-commercial-reading-roadmap-opening.mjs [--skip-branch-check] [--repo-root ]', + '', + 'Checks V39 Gate 1 spec family, roadmap, branch, workflow, docs, and active/draft commercial-reading 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 === 'V38', + `BITCODE_SPEC.txt must remain V38 during V39 gate work. Observed ${pointer || 'empty'}.`, + ); + + if (!args.skipBranchCheck) { + const branch = git(root, ['branch', '--show-current']); + assertCheck( + failures, + branch === 'version/v39' || /^v39\/gate-\d+-[a-z0-9][a-z0-9-]*$/u.test(branch), + `V39 work must occur on version/v39 or v39/gate-N-* branches. Observed ${branch || 'detached HEAD'}.`, + ); + } + + const requiredFiles = [ + 'BITCODE_SPEC_V39.md', + 'BITCODE_SPEC_V39_DELTA.md', + 'BITCODE_SPEC_V39_NOTES.md', + 'BITCODE_SPEC_V39_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', + 'packages/agent-generics/src/steps/failsafe-sequence.ts', + 'packages/agent-generics/src/steps/thricified-generation.ts', + 'packages/agent-generics/src/agents/factories.ts', + 'packages/tools-generics/src/Tool.ts', + 'packages/tools-generics/src/doc-code-tool/DocCodeToolPrompt.ts', + 'packages/tools-generics/src/doc-code-tool/formatUsableTools.ts', + 'packages/pipelines/asset-pack/src/reading-pipeline-contract.ts', + 'packages/pipelines/asset-pack/src/read-need.ts', + 'packages/pipelines/asset-pack/src/depository-search.ts', + 'packages/pipelines/asset-pack/src/tools/AssetPackLexicalDepositorySearchTool.ts', + ]; + + for (const relativePath of requiredFiles) { + assertCheck(failures, fileExists(root, relativePath), `Missing required V39 Gate 1 file: ${relativePath}`); + } + + const spec = read(root, 'BITCODE_SPEC_V39.md'); + const delta = read(root, 'BITCODE_SPEC_V39_DELTA.md'); + const notes = read(root, 'BITCODE_SPEC_V39_NOTES.md'); + const parity = read(root, 'BITCODE_SPEC_V39_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'); + const failsafeSource = read(root, 'packages/agent-generics/src/steps/failsafe-sequence.ts'); + const thricifiedSource = read(root, 'packages/agent-generics/src/steps/thricified-generation.ts'); + const agentFactorySource = read(root, 'packages/agent-generics/src/agents/factories.ts'); + const toolPromptSource = read(root, 'packages/tools-generics/src/doc-code-tool/DocCodeToolPrompt.ts'); + const usableToolsSource = read(root, 'packages/tools-generics/src/doc-code-tool/formatUsableTools.ts'); + const readingContractSource = read(root, 'packages/pipelines/asset-pack/src/reading-pipeline-contract.ts'); + const embeddingConfigSource = read(root, 'packages/pipelines/asset-pack/src/embedding-config.ts'); + const searchSource = read(root, 'packages/pipelines/asset-pack/src/depository-search.ts'); + + for (const [label, content] of [ + ['V39 SPEC', spec], + ['V39 DELTA', delta], + ['V39 NOTES', notes], + ['V39 PARITY', parity], + ]) { + assertCheck( + failures, + content.includes('Current canonical/latest target: `V38`'), + `${label} must declare V38 as current canonical/latest target.`, + ); + } + + for (const phrase of [ + 'five-step enterprise Reading', + 'Depository supply', + 'ReadNeed review', + 'Finding Fits', + 'AssetPack preview', + 'deterministic BTC quote', + 'BTD rights transfer', + 'post-settlement delivery', + 'commercial Reading', + 'PipelineExecution', + 'PTRR', + 'Plan', + 'Try', + 'Refine', + 'Retry', + 'FailsafeGenerationSequence', + 'ThricifiedGeneration', + 'ToolExecution', + 'DocCodeToolPrompt', + 'ReadNeedComprehensionSynthesis', + 'ReadFitsFindingSynthesis', + 'PromptPart', + 'prompt benchmarking', + 'source-safe telemetry', + 'text-embedding-3-small', + '1536 dimensions', + 'match_deliverable_vectors', + 'lexical', + 'symbolic', + 'metadata', + 'measurement', + 'embedding/vector', + 'candidate deposits', + 'selected-fit provenance', + 'protected source', + 'unpaid AssetPack', + ]) { + assertCheck(failures, spec.includes(phrase), `V39 SPEC must name ${phrase}.`); + } + + for (const gate of [ + 'Gate 1: V39 Commercial Reading Roadmap And Spec Opening', + 'Gate 2: Depository Supply Indexing And Searchable Deposit Lifecycle', + 'Gate 3: Enterprise Reading UX State Machine', + 'Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime', + 'Gate 5: ReadFitsFinding Runtime, Ranking, And Replay', + 'Gate 6: AssetPack Preview, Quote, And Disclosure Boundary', + 'Gate 7: Settlement, BTD Rights Transfer, And Delivery', + 'Gate 8: Operational Telemetry, Repair, And Operator Readback', + 'Gate 9: Interface And Conversation Product Parity', + 'Gate 10: Local And Staging Commercial Reading Rehearsal', + 'Gate 11: V39 Promotion Readiness', + ]) { + assertCheck(failures, delta.includes(gate) || notes.includes(gate) || spec.includes(gate), `V39 gate plan is missing ${gate}.`); + } + + assertCheck(failures, hasSection(notes, 'Notes companion rule'), 'V39 NOTES must include Notes companion rule.'); + assertCheck(failures, hasSection(notes, 'Simplified-spec reading rule'), 'V39 NOTES must include Simplified-spec reading rule.'); + assertCheck(failures, notes.includes('Candidate V39 workstreams'), 'V39 NOTES must carry the V39 workstreams.'); + assertCheck(failures, notes.includes('loose post-V38 notes committed on `main`'), 'V39 NOTES must preserve the loose main-note origin.'); + + assertCheck(failures, parity.includes('## V39 implementation matrix'), 'V39 PARITY must include the V39 implementation matrix.'); + assertCheck(failures, parity.includes('## V39 implementation checklist'), 'V39 PARITY must include the V39 implementation checklist.'); + assertCheck(failures, parity.includes('## Gate 1 Parity'), 'V39 PARITY must include Gate 1 parity.'); + assertCheck(failures, parity.includes('v39/gate-1-commercial-reading-roadmap-opening'), 'V39 PARITY must name the Gate 1 branch.'); + assertCheck(failures, parity.includes('Commercial Reading vocabulary'), 'V39 PARITY must include Commercial Reading vocabulary row.'); + + assertCheck(failures, roadmap.includes('Current active canonical pointer: `BITCODE_SPEC.txt` -> `V38`'), 'Roadmap must state V38 as active pointer.'); + assertCheck(failures, roadmap.includes('Current draft target: `BITCODE_SPEC_V39.md`'), 'Roadmap must state V39 as active draft target.'); + assertCheck(failures, roadmap.includes('| V38 | `BITCODE_SPEC_V38.md` | active canon |'), 'Roadmap must mark V38 active canon.'); + assertCheck(failures, roadmap.includes('| V39 | `BITCODE_SPEC_V39.md` | active draft target |'), 'Roadmap must mark V39 active draft target.'); + assertCheck(failures, roadmap.includes('V39 Gate 1 opening anchor'), 'Roadmap must include V39 Gate 1 opening anchor.'); + + assertCheck(failures, packageJson.includes('"check:v39-gate1"'), 'package.json must expose check:v39-gate1.'); + assertCheck(failures, gateWorkflow.includes('check-v39-gate1-commercial-reading-roadmap-opening.mjs'), 'Gate workflow must run the V39 Gate 1 checker.'); + assertCheck(failures, gateWorkflow.includes('--version V39 --mode draft --current-target V38'), 'Gate workflow must validate V39 draft spec over V38.'); + assertCheck(failures, gateWorkflow.includes('--active-canon V38 --draft-target V39'), 'Gate workflow must validate V38/V39 canon posture.'); + assertCheck(failures, canonWorkflow.includes('--version V39 --mode draft --current-target V38'), 'Canon workflow must validate V39 draft family.'); + assertCheck(failures, canonWorkflow.includes('--active-canon V38 --draft-target V39'), 'Canon workflow must validate V38/V39 canon posture.'); + assertCheck(failures, canonWorkflow.includes('spec:\\ V39*|spec:\\ v39*'), 'Canon workflow must enforce V39 spec-title conformance.'); + + assertCheck(failures, readme.includes('resolves to `V38`; V39 is the active draft target'), 'README must state V38 active / V39 draft posture.'); + assertCheck(failures, readme.includes('version/v39'), 'README must document the version/v39 branch workflow.'); + assertCheck(failures, readme.includes('v39/gate-1-commercial-reading-roadmap-opening'), 'README must document a V39 gate branch example.'); + assertCheck(failures, prTemplate.includes('V39 Gate N:'), 'PR template must show V39 gate title format.'); + assertCheck(failures, protocolReadme.includes('V38` active, `V39` draft'), 'Protocol README must state V38/V39 posture.'); + assertCheck(failures, protocolReadme.includes('check:v39-gate1'), 'Protocol README must mention check:v39-gate1.'); + assertCheck(failures, demoReadme.includes('resolves to `V38`; V39 is the active draft target'), 'Demonstration README must state V38/V39 posture.'); + + for (const [label, content] of [ + ['commercial protocol package', packagePosture], + ['standalone demonstration', demoPosture], + ['protocol state projection', postureState], + ]) { + assertCheck(failures, content.includes("ACTIVE_CANON_VERSION = 'V38'") || content.includes('"activeCanonVersion": "V38"'), `${label} must keep V38 active.`); + assertCheck(failures, content.includes("DRAFT_TARGET_VERSION = 'V39'") || content.includes('"draftTargetVersion": "V39"'), `${label} must declare V39 draft target.`); + } + + assertCheck(failures, failsafeSource.includes('ThricifiedGeneration'), 'Failsafe source must delegate to ThricifiedGeneration.'); + assertCheck(failures, thricifiedSource.includes('Reason') && thricifiedSource.includes('Judge'), 'Thricified source must preserve Reason and Judge stages.'); + assertCheck(failures, agentFactorySource.includes('factoryAgentWithPTRR'), 'Agent factory source must expose factoryAgentWithPTRR.'); + assertCheck(failures, toolPromptSource.includes('DocCodeToolPrompt'), 'Tool prompt source must expose DocCodeToolPrompt.'); + assertCheck(failures, usableToolsSource.includes('formatToolsWithDocCodeToolsIntoUsableTools'), 'Tool formatting source must expose usable tool formatting.'); + assertCheck(failures, readingContractSource.includes('ReadNeedComprehensionSynthesis'), 'Reading contract must name ReadNeedComprehensionSynthesis.'); + assertCheck(failures, readingContractSource.includes('ReadFitsFindingSynthesis'), 'Reading contract must name ReadFitsFindingSynthesis.'); + assertCheck(failures, embeddingConfigSource.includes('text-embedding-3-small'), 'Embedding config source must preserve OpenAI embedding policy.'); + assertCheck(failures, embeddingConfigSource.includes('match_deliverable_vectors'), 'Embedding config source must preserve vector match function name.'); + assertCheck(failures, searchSource.includes('buildAssetPackEmbeddingPolicy'), 'Depository search source must consume the embedding policy.'); + + 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('V39 Gate 1 commercial Reading roadmap opening check failed:\n'); + for (const failure of failures) process.stderr.write(`- ${failure}\n`); + process.exitCode = 1; + return; + } + + process.stdout.write(`V39 Gate 1 commercial Reading 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; +}