|
| 1 | +# Bitcode Spec V38 Delta |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +- Version: `V38` |
| 6 | +- V38 state: active draft opening over promoted V37 |
| 7 | +- Current canonical/latest target: `V37` |
| 8 | +- Prior canonical anchor: `BITCODE_SPEC_V37.md` |
| 9 | +- Prior generated proof appendix: `BITCODE_SPEC_V37_PROVEN.md` |
| 10 | +- Generated structured artifact inventory: draft `.bitcode/v38-spec-family-report.json`, `.bitcode/v38-canonical-input-report.json`, `.bitcode/v38-canon-posture-drift-report.json`, V38 gate-quality workflow evidence, and future V38 generated proof artifacts as gates close |
| 11 | +- Source parity state: V38 source-side inference stack, prompt benchmarking, Reading pipeline, depository-search, telemetry, rehearsal, workflow, and promotion surfaces are draft-required until their gates close |
| 12 | +- Spec companion: `BITCODE_SPEC_V38.md` |
| 13 | +- Notes companion: `BITCODE_SPEC_V38_NOTES.md` |
| 14 | +- Parity companion: `BITCODE_SPEC_V38_PARITY_MATRIX.md` |
| 15 | +- Generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md` only after V38 promotion |
| 16 | +- Scope: V38 delta for inference stack correctness, Reading inference, fit-finding depository search, prompt benchmarking, telemetry, and promotion readiness over promoted V37 Website Conversations canon |
| 17 | + |
| 18 | +## Why V38 exists |
| 19 | + |
| 20 | +V37 promoted Website Conversations. |
| 21 | +That made route-local conversation sessions, streaming UI, writing, source selection, Terminal handoff, persistence, privacy, telemetry, and rehearsal visible enough for enterprise product use. |
| 22 | + |
| 23 | +V38 exists because Bitcode now needs the inference stack beneath Reading, Conversations, tools, and depository search to become explicit, testable, benchmarkable, and commercially reliable. |
| 24 | +V38 closes implementation gaps in how PTRR agents, Failsafe chains, ThricifiedGeneration, prompt registries, PromptParts, tool prompts, telemetry, context ancestry, and Reading search/synthesis work together. |
| 25 | + |
| 26 | +## Accepted V38 decisions |
| 27 | + |
| 28 | +- V37 remains active canon during V38 drafting. |
| 29 | +- V38 gate branches are opened from `version/v38` and merged back only when their gate acceptance criteria are closed. |
| 30 | +- V38 owns inference correctness across Reading pipelines, Website Conversations, tool-definition prompts, and interface-specific inference entrypoints. |
| 31 | +- All practical PTRR agent steps should use `FailsafeGenerationSequence` above `ThricifiedGeneration`; any exception must be source-backed, specified, and tested. |
| 32 | +- `ThricifiedGeneration` remains the lowest-level Reason, Judge, StructuredOutput chain. |
| 33 | +- Tools are step-owned capabilities, and their doc-comment definitions must be injected into final prompt material through `DocCodeToolPrompt` and `formatUsableTools`. |
| 34 | +- Prompt registry composition, interpolation bindings, raw responses, parsed typed results, schema verdicts, retries, repairs, and execution ancestry roots must be telemetry-visible at permitted disclosure tiers. |
| 35 | +- `ReadFitsFindingSynthesis` must discover many candidate fits above threshold, not merely one candidate, before AssetPack synthesis and settlement handoff. |
| 36 | +- 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. |
| 37 | + |
| 38 | +## Explicitly deferred |
| 39 | + |
| 40 | +- Production-mainnet value-bearing launch remains blocked. |
| 41 | +- Bridge chain-of-record implementation remains deferred. |
| 42 | +- V38 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. |
| 43 | +- New LlamaIndex, Pinecone, or provider-specific search channels may be specified only after boundaries, credentials, storage, telemetry, and tests are explicit. |
| 44 | + |
| 45 | +## Pre-Implementation Sequence |
| 46 | + |
| 47 | +1. Open `version/v38` from promoted `main`. |
| 48 | +2. Open `v38/gate-1-inference-stack-roadmap-opening` from `version/v38`. |
| 49 | +3. Create the V38 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V37`. |
| 50 | +4. Refresh `SPECIFICATIONS_ROADMAP.md` so V37 is active canon, V38 is draft target, and post-V38 work remains coherent. |
| 51 | +5. Retarget gate-quality and canon-quality workflow posture checks to V37 active / V38 draft. |
| 52 | +6. Add `check:v38-gate1` and a V38 Gate 1 checker. |
| 53 | +7. Define V38 gates, acceptance criteria, carryforward parity rows, and promotion boundaries. |
| 54 | +8. Validate spec family, canonical inputs, canon posture, workflows, roadmap truth, README/docs, and diff hygiene. |
| 55 | +9. Push the gate branch and open a pull request to `version/v38`. |
| 56 | + |
| 57 | +## Commit-Body Direction |
| 58 | + |
| 59 | +V38 gate commit bodies should describe the closed gate, inference surfaces, prompt/promptpart changes, pipeline or tool changes, generated proof artifacts, tests, telemetry/disclosure boundaries, and accepted deferrals. |
| 60 | +The eventual V38 promotion commit body must name all closed V38 gates, generated inference proof artifacts, prompt benchmark reports, Reading pipeline evidence, depository-search evidence, source-safe telemetry evidence, local/staging rehearsal proof, promotion workflow evidence, and the `BITCODE_SPEC.txt` pointer change from `V37` to `V38`. |
| 61 | + |
| 62 | +## Gate Delta |
| 63 | + |
| 64 | +### Gate 1: V38 Inference Stack Roadmap And Spec Opening |
| 65 | + |
| 66 | +Gate 1 opens V38 correctly: |
| 67 | + |
| 68 | +- V38 SPEC, DELTA, NOTES, and PARITY files exist. |
| 69 | +- `BITCODE_SPEC.txt` remains `V37`. |
| 70 | +- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V37 active / V38 draft posture. |
| 71 | +- `check:v38-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, inference vocabulary, depository-search vocabulary, and promotion boundaries. |
| 72 | +- The V38 gate list is explicit before inference implementation begins. |
| 73 | + |
| 74 | +### Gate 2: Inference Surface Inventory And Prompt Registry Map |
| 75 | + |
| 76 | +Closure acceptance: |
| 77 | + |
| 78 | +- every active Reading, Conversation, tool-definition, and interface inference point is counted; |
| 79 | +- phase, PTRR agent, step, Failsafe, ThricifiedGeneration, tool, prompt, PromptPart, interpolation binding, context field, output schema, failure surface, storage target, and stream target inventories are package-backed and generated; |
| 80 | +- `pnpm run check:v38-gate2` validates inventory freshness, source coverage, prompt registry coverage, source-safety boundaries, and workflow wiring. |
| 81 | + |
| 82 | +### Gate 3: PTRR Failsafe And Thricified Execution Stack |
| 83 | + |
| 84 | +Closure acceptance: |
| 85 | + |
| 86 | +- practical PTRR steps use `FailsafeGenerationSequence` over `ThricifiedGeneration`; |
| 87 | +- Plan, Try, Refine, Retry steps preserve agent, step, Failsafe, generation, and provider-call ancestry; |
| 88 | +- exceptions are source-backed and tested; |
| 89 | +- `pnpm run check:v38-gate3` validates stack composition, typed output repair, and telemetry events. |
| 90 | + |
| 91 | +### Gate 4: PromptPart And Prompt Benchmarking |
| 92 | + |
| 93 | +Closure acceptance: |
| 94 | + |
| 95 | +- PromptParts and complete Prompts are benchmarkable; |
| 96 | +- active Reading, Conversation, and tool-definition prompts have initial benchmark suites; |
| 97 | +- benchmark artifacts preserve prompt identities, fixtures, typed-output quality expectations, and disclosure tiers; |
| 98 | +- `pnpm run check:v38-gate4` validates benchmark runner, fixtures, reports, and source-safe metadata. |
| 99 | + |
| 100 | +### Gate 5: Inference Telemetry And Disclosure Tiers |
| 101 | + |
| 102 | +Closure acceptance: |
| 103 | + |
| 104 | +- inference telemetry emits phase, agent, step, Failsafe, ThricifiedGeneration, tool, prompt template, interpolated prompt, raw response, parsed output, schema verdict, retry, repair, and failure events; |
| 105 | +- each event has disclosure-tier rules; |
| 106 | +- protected payloads remain blocked or redacted; |
| 107 | +- `pnpm run check:v38-gate5` validates event contracts, UI stream compatibility, API contracts, and redaction tests. |
| 108 | + |
| 109 | +### Gate 6: ReadNeedComprehensionSynthesis Inference Hardening |
| 110 | + |
| 111 | +Closure acceptance: |
| 112 | + |
| 113 | +- Read Request to Need synthesis uses the V38 inference stack; |
| 114 | +- synthesized Needs are reviewable, resynthesizable with feedback, measurement-backed, and bounded to the original request; |
| 115 | +- storage and telemetry are source-safe and typed; |
| 116 | +- `pnpm run check:v38-gate6` validates pipeline contracts, agents, prompts, outputs, tests, and docs. |
| 117 | + |
| 118 | +### Gate 7: ReadFitsFindingSynthesis Depository Search And Embeddings |
| 119 | + |
| 120 | +Closure acceptance: |
| 121 | + |
| 122 | +- Finding Fits uses inference-derived queries and depository search tools across lexical, symbolic, path, metadata, measurement, embedding/vector, and provider-specific channels; |
| 123 | +- candidate deposits above threshold are ranked, verified, and traceable; |
| 124 | +- embedding policy, vector dimensions, similarity metric, storage, credentials, and telemetry are explicit; |
| 125 | +- `pnpm run check:v38-gate7` validates search tools, embeddings, ranking, thresholding, tests, and generated evidence. |
| 126 | + |
| 127 | +### Gate 8: AssetPack Synthesis Handoff And Economic Traceability |
| 128 | + |
| 129 | +Closure acceptance: |
| 130 | + |
| 131 | +- selected fits remain traceable into AssetPack synthesis; |
| 132 | +- source-safe preview and post-settlement delivery preserve visibility boundaries; |
| 133 | +- contributor compensation, ledger/database synchronization, proof receipts, and repair paths are specified and tested; |
| 134 | +- `pnpm run check:v38-gate8` validates fit-to-AssetPack receipts, settlement traceability, source-safety, and repair posture. |
| 135 | + |
| 136 | +### Gate 9: Conversation And Tool-Prompt Inference Parity |
| 137 | + |
| 138 | +Closure acceptance: |
| 139 | + |
| 140 | +- Website Conversations and tool-definition prompts use V38 prompt registry, Failsafe, Thricified, tool prompt, telemetry, and disclosure posture; |
| 141 | +- interface-specific inference entrypoints do not bypass the stack; |
| 142 | +- `pnpm run check:v38-gate9` validates Conversation/tool parity, route contracts, UI surfaces, and prompt disclosure rules. |
| 143 | + |
| 144 | +### Gate 10: Local Staging Inference And Depository Search Rehearsal |
| 145 | + |
| 146 | +Closure acceptance: |
| 147 | + |
| 148 | +- local and staging-testnet rehearsals run Reading inference, depository search, source-safe AssetPack preview, telemetry streaming, and blocked mainnet posture; |
| 149 | +- real non-mocked inference is exercised where credentials are available; |
| 150 | +- logs/screenshots/proofs are source-safe; |
| 151 | +- `pnpm run check:v38-gate10` validates rehearsal evidence and workflow wiring. |
| 152 | + |
| 153 | +### Gate 11: V38 Promotion Readiness |
| 154 | + |
| 155 | +Closure acceptance: |
| 156 | + |
| 157 | +- all V38 gates are closed; |
| 158 | +- V38 generated proof appendix support exists; |
| 159 | +- promotion workflow validates V38 and commits only the canonical pointer and generated promotion artifacts; |
| 160 | +- `pnpm run check:v38-gate11` validates promotion readiness, source-safety, generated artifacts, and V39 draft posture preparation. |
0 commit comments