V37 Gate 8: Conversation telemetry proof hooks

Adds package-owned ConversationTelemetryProofHooks canon source and generated artifact. Wires source-safe conversation telemetry proof hooks into API stream rows, the Conversations telemetry proof panel, dashboard/runbook docs, and Gate 8 workflow checks. Extends protocol, API, UI, documentation, and checker coverage for source-safe telemetry proof posture.

Author: geraldarthurdavis

.bitcode/v37-conversation-telemetry-proof-hooks.json

@@ -127,6 +127,9 @@ jobs:
               if [ -f scripts/check-v37-gate7-conversation-persistence-privacy-redaction.mjs ]; then
                 node scripts/check-v37-gate7-conversation-persistence-privacy-redaction.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate8-conversation-telemetry-proof-hooks.mjs ]; then
+                node scripts/check-v37-gate8-conversation-telemetry-proof-hooks.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

.github/workflows/bitcode-canon-quality.yml

@@ -256,6 +256,9 @@ jobs:
               if [ -f scripts/check-v37-gate7-conversation-persistence-privacy-redaction.mjs ]; then
                 node scripts/check-v37-gate7-conversation-persistence-privacy-redaction.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate8-conversation-telemetry-proof-hooks.mjs ]; then
+                node scripts/check-v37-gate8-conversation-telemetry-proof-hooks.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -328,7 +331,8 @@ jobs:
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --runTestsByPath src/__tests__/distributed-execution-runtime-receipt.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/reading-pipeline-observability.test.ts src/__tests__/reading-pipeline-contract.test.ts src/__tests__/v32-reading-pipeline-proof-coverage.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-disclosure.test.ts src/__tests__/postprocess.test.ts src/__tests__/read-need.test.ts --runInBand --forceExit
-          pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/conversations/__tests__/stream-events.test.ts src/conversations/__tests__/privacy.test.ts --runInBand --forceExit
+          pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/conversations/__tests__/stream-events.test.ts src/conversations/__tests__/privacy.test.ts src/conversations/__tests__/telemetry.test.ts --runInBand --forceExit
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/conversation-telemetry-proof-hooks.test.js
           pnpm --filter @bitcode/protocol test
 
       - name: Test staged Reading route and Terminal harness contracts
@@ -348,6 +352,8 @@ jobs:
             tests/conversationTerminalHandoff.test.tsx \
             tests/api/conversationPersistencePrivacyRedaction.test.ts \
             tests/conversationPersistencePrivacyPanel.test.tsx \
+            tests/api/conversationTelemetryProofHooks.test.ts \
+            tests/conversationTelemetryProofPanel.test.tsx \
             tests/conversationSourceSelector.test.tsx \
             tests/conversationWritingWorkspace.test.tsx \
             tests/auxillariesExternalsPane.test.tsx \

.github/workflows/bitcode-gate-quality.yml

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 7 closes ConversationPersistencePrivacyRedaction durable storage privacy over active V36 Exchange canon
+- V37 state: draft implementation; Gate 8 closes ConversationTelemetryProofHooks dashboards, runbooks, and source-safe telemetry proof over active V36 Exchange canon
 - Current canonical/latest target: `V36`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, `.bitcode/v37-conversation-terminal-handoff.json`, and `.bitcode/v37-conversation-persistence-privacy-redaction.json`
-- Source parity state: V37 source parity includes Gate 1 spec family, roadmap, docs, workflow, and checker posture, Gate 2 package-owned ConversationSession route-history contracts, Gate 3 package-owned ConversationStreamEvent stream UI/event contracts, Gate 4 package-owned ConversationWritingWorkspace fullscreen writing contracts, Gate 5 package-owned ConversationSourceSelector source/context policy contracts, Gate 6 package-owned ConversationTerminalHandoff transaction handoff contracts, and Gate 7 package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, `.bitcode/v37-conversation-terminal-handoff.json`, `.bitcode/v37-conversation-persistence-privacy-redaction.json`, and `.bitcode/v37-conversation-telemetry-proof-hooks.json`
+- Source parity state: V37 source parity includes Gate 1 spec family, roadmap, docs, workflow, and checker posture, Gate 2 package-owned ConversationSession route-history contracts, Gate 3 package-owned ConversationStreamEvent stream UI/event contracts, Gate 4 package-owned ConversationWritingWorkspace fullscreen writing contracts, Gate 5 package-owned ConversationSourceSelector source/context policy contracts, Gate 6 package-owned ConversationTerminalHandoff transaction handoff contracts, Gate 7 package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts, and Gate 8 package-owned ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V36`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V37_DELTA.md`
@@ -36,6 +36,7 @@ V37 adds Website Conversations product contracts over inherited V36 canon:
 - `ConversationSourceSelector`: repository, branch, commit, deposit, BTD range, AssetPack preview, document, and prior conversation source selectors governed by policy, rights, and disclosure posture.
 - `ConversationTerminalHandoff`: source-safe handoff from conversation context into `/terminal` transactions for Depositing, Reading, Finding Fits, Exchange, settlement, and delivery workflows.
 - `ConversationPersistencePrivacyRedaction`: durable conversation storage, visibility tier separation, export, delete, retention, replay, and incident repair posture for source-safe persisted history.
+- `ConversationTelemetryProofHooks`: source-safe telemetry families, dashboard panels, runbook ids, correlation ids, proof roots, redaction posture, and visibility tiers for sessions, messages, streams, tools, selectors, handoffs, retries, errors, and completions.
 
 V37 does not replace the V28 ChatGPT App, V33 interface contracts, V35 telemetry/docs, or V36 Exchange law.
 It turns the website conversation surface into a route-owned user experience that consumes those contracts and emits proof-rooted source-safe telemetry.
@@ -227,6 +228,40 @@ workflow wiring, visibility tier coverage, retention posture coverage, export
 posture, delete posture, replay posture, incident repair posture, proof roots,
 event ids, and source-safe persisted metadata.
 
+## V37 Gate 8 ConversationTelemetryProofHooks canon
+
+Gate 8 implements `ConversationTelemetryProofHooks` as the package-owned
+telemetry, dashboard, runbook, and documentation contract for Website
+Conversations. It owns source-safe event families for sessions, messages,
+streams, tools, source selectors, Terminal handoffs, retries, errors, and
+completions. It emits
+`.bitcode/v37-conversation-telemetry-proof-hooks.json` with
+`source-safe-conversation-telemetry-proof-hooks-metadata`, deterministic row
+roots, hook roots, dashboard panel ids, runbook ids, required telemetry field
+ids, proof root fields, source evidence roots, replay expectations, and
+source-safe disclosure boundaries.
+
+Conversation telemetry proof hooks may expose only event ids, conversation
+ids, message ids, run ids, source selector refs, Terminal transaction refs,
+state enums, counts, proof roots, dashboard panel ids, runbook ids, and
+redacted error classes. They must not expose secret values, provider tokens,
+wallet private material, protected source payloads, raw protected prompts,
+raw provider responses with protected source, unpaid AssetPack source,
+settlement private payloads, private payment credentials, operator private
+notes, ledger write authority, or wallet signing authority.
+
+Gate 8 binds conversation stream rows to source-safe telemetry proof hooks in
+the API and gives the fullscreen Conversations UI a telemetry proof panel
+that previews dashboard/runbook posture without source leakage. Public docs
+explain route-local history, streaming, source selection, Terminal handoff,
+privacy, retries, and telemetry proof hooks. Internal docs define the
+dashboard panels and runbook ids operators use to debug failure and quality
+posture without protected payloads. `check:v37-gate8` validates package
+source, generated artifact freshness, package tests, API tests, UI tests,
+public docs, internal runbooks, workflow wiring, dashboard coverage, runbook
+coverage, event family coverage, proof roots, telemetry roots, source
+evidence roots, and source-safe telemetry metadata.
+
 ## Inherited V36 Exchange canon
 
 The promoted V36 sections below remain inherited canonical law for Exchange.

BITCODE_SPEC_V37.md

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; this delta records the V36-to-V37 Website Conversations opening through Gate 6 ConversationTerminalHandoff transaction handoff contracts
+- V37 state: draft implementation; this delta records the V36-to-V37 Website Conversations opening through Gate 8 ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts
 - Current canonical/latest target: `V36`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, and `.bitcode/v37-conversation-terminal-handoff.json`
-- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent contracts and stream UI binding; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, `.bitcode/v37-conversation-terminal-handoff.json`, `.bitcode/v37-conversation-persistence-privacy-redaction.json`, and `.bitcode/v37-conversation-telemetry-proof-hooks.json`
+- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent contracts and stream UI binding; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts; Gate 7 adds package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts; Gate 8 adds package-owned ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts
 - Spec companion: `BITCODE_SPEC_V37.md`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Parity companion: `BITCODE_SPEC_V37_PARITY_MATRIX.md`
@@ -180,6 +180,15 @@ Closure acceptance:
 
 Gate 8 binds Conversations to telemetry, proof, dashboards, and public/internal docs.
 
+Gate 8 closure adds package-backed `ConversationTelemetryProofHooks` source,
+`.bitcode/v37-conversation-telemetry-proof-hooks.json`,
+`source-safe-conversation-telemetry-proof-hooks-metadata`, session/message/
+stream/tool/source selector/Terminal handoff/retry/error/completion event
+families, source-safe dashboard panels, runbook ids, proof roots, telemetry
+roots, API stream proof hook metadata, fullscreen telemetry proof preview UI,
+public conversation docs, internal operator runbook docs, package tests, API
+tests, UI tests, workflow wiring, and `check:v37-gate8`.
+
 Closure acceptance:
 
 - conversation event families bind sessions, messages, streams, tools, source selectors, handoffs, retries, errors, and completions to source-safe telemetry;

BITCODE_SPEC_V37_DELTA.md

@@ -3,13 +3,13 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 6 closes ConversationTerminalHandoff transaction handoff over active V36 Exchange canon
+- V37 state: draft implementation; Gate 8 closes ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs posture over active V36 Exchange canon
 - Current canonical/latest target: `V36`
 - Current active draft target: `V37`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, and `.bitcode/v37-conversation-terminal-handoff.json`
-- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent stream contracts; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, `.bitcode/v37-conversation-terminal-handoff.json`, `.bitcode/v37-conversation-persistence-privacy-redaction.json`, and `.bitcode/v37-conversation-telemetry-proof-hooks.json`
+- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent stream contracts; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts; Gate 7 adds package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts; Gate 8 adds package-owned ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts
 - Scope: draft notes for website Conversations work after V36 Exchange depth and after the V28 ChatGPT App MVP proved the interface path.
 
 This NOTES file does not promote V37. It is binding draft guidance while V37 gates are in flight.
@@ -136,6 +136,19 @@ retention never escalates visibility, replay uses prompt template ids and
 parsed result shapes, and incident repair operates over proof roots and
 redaction verdicts.
 
+Gate 8 adds `ConversationTelemetryProofHooks` so conversation sessions,
+messages, streams, tools, source selectors, Terminal handoffs, retries,
+errors, and completions have source-safe dashboard/runbook telemetry. The
+package source emits `.bitcode/v37-conversation-telemetry-proof-hooks.json`,
+the API attaches telemetry proof hooks to conversation stream execution rows,
+and the UI exposes a fullscreen telemetry proof panel. Telemetry proof hooks
+may expose event ids, conversation ids, message ids, run ids, source selector
+refs, Terminal transaction refs, state enums, counts, proof roots, dashboard
+panel ids, runbook ids, and redacted error classes only. Protected prompts,
+protected model responses, protected source payloads, provider tokens, wallet
+private material, settlement private payloads, unpaid AssetPack source,
+ledger write authority, and wallet signing authority remain forbidden.
+
 ## V37 gate plan
 
 - Gate 1: V37 Conversations Roadmap And Spec Opening