|
| 1 | +# Bitcode Spec V35 Delta |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +- Version: `V35` |
| 6 | +- V35 state: active draft target opened; this delta records planned V34-to-V35 telemetry and documentation depth |
| 7 | +- Current canonical/latest target: `V34` |
| 8 | +- Prior canonical anchor: `BITCODE_SPEC_V34.md` |
| 9 | +- Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md` |
| 10 | +- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion |
| 11 | +- Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates |
| 12 | +- Spec companion: `BITCODE_SPEC_V35.md` |
| 13 | +- Notes companion: `BITCODE_SPEC_V35_NOTES.md` |
| 14 | +- Parity companion: `BITCODE_SPEC_V35_PARITY_MATRIX.md` |
| 15 | +- Generated proof appendix: `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion |
| 16 | +- Scope: V35 draft delta for telemetry and documentation depth over promoted V34 deployment canon |
| 17 | + |
| 18 | +## Why V35 exists |
| 19 | + |
| 20 | +V34 promoted deployment depth: host capability, environment lanes, distributed execution receipts, storage posture, secret rotation, migration approvals, observers, repair jobs, rollback/upgrade playbooks, rehearsal, and promotion readiness. |
| 21 | +That made Bitcode operator-deployable. |
| 22 | + |
| 23 | +V35 exists because a deployable commercial Bitcode system must also be understandable, monitorable, supportable, documentable, and testnet-rollout ready. |
| 24 | +Telemetry cannot be dashboard folklore, and documentation cannot be stale narrative. |
| 25 | +Internal codebase docs, public `/docs`, telemetry taxonomy, dashboards, alert runbooks, incident response, operator escalation, documentation QA, onboarding, and rollout guides must become source-safe, proof-rooted protocol reality. |
| 26 | + |
| 27 | +## Accepted V35 decisions |
| 28 | + |
| 29 | +- V34 remains active canon during V35 drafting. |
| 30 | +- V35 gate branches are opened from `version/v35` and merged back only when their gate acceptance criteria are closed. |
| 31 | +- V35 owns telemetry and documentation depth: `TelemetryTaxonomyCatalog`, `DocumentationSurfaceCatalog`, `DocsQaAlignmentReport`, `OperatorRunbookCatalog`, `TestnetRolloutReadinessGuide`, and `DocumentationTelemetryPromotionReadinessReport`. |
| 32 | +- V35 telemetry and documentation contracts must be package-owned before they are exposed by route handlers, dashboards, runbooks, MCP tools, ChatGPT App actions, public docs, internal docs, or UI status surfaces. |
| 33 | +- Public docs disclose guidance, measurements, proof posture, fee/right boundaries, and source-safe previews; they must not disclose protected source, secrets, wallet private material, or unpaid AssetPack contents. |
| 34 | +- Telemetry events require redaction posture, source-safety class, correlation ids, proof roots, dashboard/runbook links, and storage targets. |
| 35 | +- Documentation QA must fail closed when code, SPEC, public docs, internal docs, generated proofs, generated artifacts, telemetry events, or deployment receipts drift. |
| 36 | + |
| 37 | +## Explicitly deferred |
| 38 | + |
| 39 | +- V36 owns deeper Exchange market behavior. |
| 40 | +- V37 owns deeper website Conversations product behavior. |
| 41 | +- Production-mainnet value-bearing launch remains explicitly blocked until a future promoted canon admits it. |
| 42 | +- Bridge chain-of-record implementation remains out of V35. |
| 43 | +- V35 does not reopen BTD supply law, Reading pipeline product law, or V34 interface contract law. |
| 44 | + |
| 45 | +## Pre-Implementation Sequence |
| 46 | + |
| 47 | +1. Open `version/v35` from promoted `main`. |
| 48 | +2. Open `v35/gate-1-telemetry-docs-roadmap-opening` from `version/v35`. |
| 49 | +3. Create the V35 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V34`. |
| 50 | +4. Refresh `SPECIFICATIONS_ROADMAP.md` so V34 is active canon, V35 is draft target, and V36-V37 scopes remain coherent. |
| 51 | +5. Retarget gate-quality and canon-quality workflow posture checks to V34 active / V35 draft. |
| 52 | +6. Add `check:v35-gate1` and a V35 Gate 1 checker. |
| 53 | +7. Define V35 gates, acceptance criteria, carryforward parity rows, and post-V35 roadmap responsibilities. |
| 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/v35`. |
| 56 | + |
| 57 | +## Commit-Body Direction |
| 58 | + |
| 59 | +V35 gate commit bodies should describe the closed gate, specification changes, implementation surfaces, tests, proof commands, and accepted boundaries. |
| 60 | +The eventual V35 promotion commit body must name all closed V35 gates, generated telemetry/documentation proof artifacts, docs QA evidence, telemetry taxonomy evidence, public/internal documentation evidence, dashboard/runbook evidence, rollout guide evidence, rehearsal proof, and the `BITCODE_SPEC.txt` pointer change from `V34` to `V35`. |
| 61 | +It must explicitly defer V36 Exchange depth, V37 Conversations depth, bridge chain-of-record implementation, and value-bearing mainnet launch. |
| 62 | + |
| 63 | +## Gate Delta |
| 64 | + |
| 65 | +### Gate 1: V35 Telemetry Documentation Roadmap And Spec Opening |
| 66 | + |
| 67 | +Gate 1 opens V35 correctly: |
| 68 | + |
| 69 | +- V35 SPEC, DELTA, NOTES, and PARITY files exist. |
| 70 | +- `BITCODE_SPEC.txt` remains `V34`. |
| 71 | +- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V34 active / V35 draft posture. |
| 72 | +- `check:v35-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, telemetry/documentation vocabulary, and promotion boundaries. |
| 73 | +- The V35 gate list is explicit before telemetry/documentation implementation begins. |
| 74 | + |
| 75 | +### Gate 2: Documentation Surface Catalog |
| 76 | + |
| 77 | +Gate 2 inventories internal and public documentation truth. |
| 78 | + |
| 79 | +Closure acceptance: |
| 80 | + |
| 81 | +- internal codebase docs, public `/docs`, package docs, route docs, generated artifact docs, API/interface docs, and owner/freshness posture are enumerated; |
| 82 | +- every docs surface names audience, owner, disclosure class, source roots, generated artifacts, spec links, test coverage, and freshness checks; |
| 83 | +- source-bearing material, secrets, wallet private material, and unpaid AssetPack contents remain blocked from public docs. |
| 84 | + |
| 85 | +### Gate 3: Telemetry Taxonomy Event Schema And Redaction |
| 86 | + |
| 87 | +Gate 3 defines source-safe event law. |
| 88 | + |
| 89 | +Closure acceptance: |
| 90 | + |
| 91 | +- pipeline, execution, PTRR agent, ThricifiedGeneration, tool, ledger, wallet, storage, interface, deployment, observer, repair, docs QA, and promotion events are cataloged; |
| 92 | +- every event names redaction posture, source-safety class, correlation ids, proof root, storage target, dashboard panel, alert threshold, and runbook link; |
| 93 | +- event payloads fail closed on secrets, protected source, raw unpaid AssetPack source, and wallet private material. |
| 94 | + |
| 95 | +### Gate 4: Public Docs Usage Guides |
| 96 | + |
| 97 | +Gate 4 makes enterprise-facing docs a maintained product surface. |
| 98 | + |
| 99 | +Closure acceptance: |
| 100 | + |
| 101 | +- public `/docs` pages exist or are explicitly cataloged for Terminal, Protocol, Auxillaries, MCP API, ChatGPT App, BTD, AssetPack ranges, Reads, fees, proof posture, and deferred Exchange/Conversations boundaries; |
| 102 | +- every public page derives from package/SPEC truth and names disclosure limits; |
| 103 | +- protected source, raw protected prompts, secrets, wallet private material, and unpaid AssetPack contents remain blocked. |
| 104 | + |
| 105 | +### Gate 5: Dashboards Alerts Runbooks Incident Escalation |
| 106 | + |
| 107 | +Gate 5 turns telemetry into operator action. |
| 108 | + |
| 109 | +Closure acceptance: |
| 110 | + |
| 111 | +- `OperatorRunbookCatalog` rows bind telemetry events to dashboard panels, alert thresholds, incident classes, escalation paths, safe commands, forbidden data, and post-incident docs updates; |
| 112 | +- dashboard and alert definitions derive from `TelemetryTaxonomyCatalog`; |
| 113 | +- incident evidence is source-safe and proof-rooted. |
| 114 | + |
| 115 | +### Gate 6: Documentation QA Alignment Proofs |
| 116 | + |
| 117 | +Gate 6 prevents stale documentation. |
| 118 | + |
| 119 | +Closure acceptance: |
| 120 | + |
| 121 | +- `DocsQaAlignmentReport` checks code, SPEC, DELTA, NOTES, PARITY, generated proof, generated artifacts, public docs, internal docs, route docs, and interface docs; |
| 122 | +- stale tokens, missing source roots, missing generated artifacts, and unsupported disclosure claims fail closed; |
| 123 | +- package scripts and workflows run the docs QA checks. |
| 124 | + |
| 125 | +### Gate 7: Developer Operator Testnet Rollout Guides |
| 126 | + |
| 127 | +Gate 7 prepares actual users and operators. |
| 128 | + |
| 129 | +Closure acceptance: |
| 130 | + |
| 131 | +- `TestnetRolloutReadinessGuide` covers contributor onboarding, local development, operator use, enterprise reader flows, depositor flows, interface consumers, environment lanes, wallet/settlement caveats, known blockers, and rehearsal evidence; |
| 132 | +- guides distinguish local, staging-testnet, public testnet, mainnet-ready dry run, and blocked value-bearing mainnet posture; |
| 133 | +- guide examples are source-safe and reproducible. |
| 134 | + |
| 135 | +### Gate 8: Telemetry Documentation Interface Integration |
| 136 | + |
| 137 | +Gate 8 wires the contracts into active surfaces. |
| 138 | + |
| 139 | +Closure acceptance: |
| 140 | + |
| 141 | +- Terminal, Auxillaries, API, MCP API, ChatGPT App, package READMEs, internal docs, and public docs consume package-owned documentation and telemetry contracts; |
| 142 | +- interface payloads expose event ids, proof roots, docs links, runbook links, and redaction posture where useful; |
| 143 | +- interface integration never exposes protected source, secrets, wallet private material, or unpaid AssetPack contents. |
| 144 | + |
| 145 | +### Gate 9: Local Staging Telemetry Documentation Rehearsal |
| 146 | + |
| 147 | +Gate 9 proves the docs and telemetry can be followed. |
| 148 | + |
| 149 | +Closure acceptance: |
| 150 | + |
| 151 | +- local and staging-testnet rehearsals exercise documentation discovery, telemetry event emission, dashboard/runbook lookup, docs QA, incident drill, and source-safe proof-root review; |
| 152 | +- rehearsal logs/screenshots are source-safe; |
| 153 | +- value-bearing mainnet remains blocked. |
| 154 | + |
| 155 | +### Gate 10: V35 Promotion Readiness |
| 156 | + |
| 157 | +Gate 10 owns final generated proof, promotion workflow support, source-safe `.bitcode/v35-documentation-telemetry-promotion-readiness-report.json`, and V35 closure. |
| 158 | + |
| 159 | +Closure acceptance: |
| 160 | + |
| 161 | +- V35 promotion checks validate all documentation/telemetry artifacts, catalogs, docs QA reports, dashboard/runbook bindings, rollout guides, interface integration evidence, rehearsal proof, and generated proof appendix support; |
| 162 | +- promotion scripts support V35 command planning, dry-run, generated proof output, and derived promotion commit body generation; |
| 163 | +- promotion rewrites runtime posture to active V35 / draft V36 only after validations pass. |
| 164 | + |
| 165 | +## Delta completion condition |
| 166 | + |
| 167 | +This delta is complete for Gate 10 when `version/v35` contains the Gate 10 `DocumentationTelemetryPromotionReadinessReport`, source-safe generated artifacts, focused tests, package exports, workflow wiring, promotion script support, generated proof support, and local/staging telemetry-documentation rehearsal evidence. |
0 commit comments