Merge pull request #113 from engineeredsoftware/v37/gate-3-conversation-stream-ui-event-contracts

V37 Gate 3: Conversation Stream UI And Event Contracts

Author: geraldarthurdavis

.bitcode/v37-conversation-stream-event-contract.json

@@ -112,6 +112,9 @@ jobs:
               if [ -f scripts/check-v37-gate2-conversation-session-route-history-contracts.mjs ]; then
                 node scripts/check-v37-gate2-conversation-session-route-history-contracts.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate3-conversation-stream-event-contracts.mjs ]; then
+                node scripts/check-v37-gate3-conversation-stream-event-contracts.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -21,6 +21,7 @@ jobs:
   gate-quality:
     name: Gate Quality
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     steps:
       - name: Checkout repository
@@ -240,6 +241,9 @@ jobs:
               if [ -f scripts/check-v37-gate2-conversation-session-route-history-contracts.mjs ]; then
                 node scripts/check-v37-gate2-conversation-session-route-history-contracts.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate3-conversation-stream-event-contracts.mjs ]; then
+                node scripts/check-v37-gate3-conversation-stream-event-contracts.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -263,7 +267,6 @@ jobs:
 
       - name: Test gate packages
         run: |
-          pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runInBand --forceExit
           pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runTestsByPath __tests__/btc-fee-operation.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runTestsByPath __tests__/btd.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runTestsByPath __tests__/v32-ledger-btd-settlement-failure-states.test.ts --runInBand --forceExit
@@ -311,10 +314,9 @@ jobs:
           pnpm --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/chatgpt-action-contract.test.ts src/__tests__/tools.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-harness.test.ts --runInBand --forceExit
           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 --passWithNoTests --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/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/conversations/__tests__/stream-events.test.ts --runInBand --forceExit
           pnpm --filter @bitcode/protocol test
 
       - name: Test staged Reading route and Terminal harness contracts
@@ -329,6 +331,8 @@ jobs:
             tests/api/vcsRoutes.test.ts \
             tests/api/conversationSessionRouteHistory.test.ts \
             tests/api/conversationSessionRouteHistoryContract.test.ts \
+            tests/api/conversationStreamEventContract.test.ts \
+            tests/conversationStreamPipelineLog.test.tsx \
             tests/auxillariesExternalsPane.test.tsx \
             tests/profileStep.test.tsx \
             tests/api/readReviewRoute.test.ts \

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

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 2 closes ConversationSession route-local history contracts over active V36 Exchange canon
+- V37 state: draft implementation; Gate 3 closes ConversationStreamEvent stream UI and event contracts 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`, and `.bitcode/v37-conversation-session-route-history.json`
-- Source parity state: V37 source parity includes Gate 1 spec family, roadmap, docs, workflow, and checker posture plus Gate 2 package-owned ConversationSession route-history 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`, and `.bitcode/v37-conversation-stream-event-contract.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, and Gate 3 package-owned ConversationStreamEvent stream UI/event 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`
@@ -31,7 +31,7 @@ V37 adds Website Conversations product contracts over inherited V36 canon:
 
 - `ConversationSession`: route-local conversation identity, route-local history, user/account posture, source context, policy decision, stream state, and proof-rooted history references.
 - `ConversationMessage`: user, assistant, system, tool, and handoff message records with source-safe disclosure classification, redaction posture, retry state, and telemetry event ids.
-- `ConversationStreamEvent`: readable streaming rows for model deltas, tool calls, retrieval summaries, proof roots, error states, and completion decisions.
+- `ConversationStreamEvent`: readable streaming rows for model deltas, tool calls, retrieval summaries, proof roots, retry states, completion decisions, and error rows.
 - `ConversationWritingWorkspace`: fullscreen writing mode for drafting Read Requests, Need feedback, AssetPack review notes, and Terminal handoff summaries without source leakage.
 - `ConversationSourceSelector`: repository, branch, commit, deposit, BTD range, AssetPack preview, and document 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.
@@ -81,6 +81,32 @@ source, or any claim that route-local Conversations are global ledger truth.
 package tests, route tests, docs, workflow wiring, source safety, proof roots,
 event ids, route ids, history operations, and persistence boundaries.
 
+## V37 Gate 3 ConversationStreamEvent stream UI canon
+
+Gate 3 implements `ConversationStreamEvent` as the package-owned stream event
+contract for Website Conversations. `ConversationStreamEvent` owns model
+deltas, tool calls, retrieval summaries, proof roots, retry states, completion
+decisions, and error rows. It emits
+`.bitcode/v37-conversation-stream-event-contract.json` with
+`source-safe-conversation-stream-event-metadata`, deterministic row roots,
+deterministic detail roots, event kind ids, required telemetry fields, source
+evidence roots, and source-safe disclosure limits.
+
+Conversation stream events are carried on the unversioned conversation SSE
+routes as metadata attached to legacy-compatible rows. The stream UI uses the
+shared rich execution log surface: collapsed rows show readable stream status,
+and expanded accordions show event ids, proof roots, redaction posture,
+prompt-disclosure posture, result-disclosure posture, fail-closed states, and
+source-safe expanded metadata. Raw protected prompts, protected source,
+provider tokens, private wallet material, raw provider responses, settlement
+private payloads, unpaid AssetPack source, and global ledger authority claims
+are never valid stream UI payloads.
+
+`check:v37-gate3` validates package source, generated artifact freshness,
+package tests, route/UI tests, telemetry binding, docs, workflow wiring,
+source safety, event kind coverage, proof roots, disclosure posture, and
+fail-closed states.
+
 ## 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 and Gate 2 ConversationSession contract set
+- V37 state: draft implementation; this delta records the V36-to-V37 Website Conversations opening through Gate 3 ConversationStreamEvent stream UI/event 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`, and `.bitcode/v37-conversation-session-route-history.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
+- 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`, and `.bitcode/v37-conversation-stream-event-contract.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
 - Spec companion: `BITCODE_SPEC_V37.md`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Parity companion: `BITCODE_SPEC_V37_PARITY_MATRIX.md`
@@ -92,6 +92,12 @@ Closure acceptance:
 - telemetry carries event ids, proof roots, redaction posture, prompt/result disclosure posture, and fail-closed states;
 - `pnpm run check:v37-gate3` validates stream contracts, route tests, UI tests, telemetry binding, source-safety, and workflow wiring.
 
+Gate 3 closure adds package-backed `ConversationStreamEvent` source,
+`.bitcode/v37-conversation-stream-event-contract.json`,
+`source-safe-conversation-stream-event-metadata`, route-attached SSE event
+metadata, rich execution log collapsed/expanded UI binding, package tests,
+route tests, UI tests, workflow wiring, and `check:v37-gate3`.
+
 ### Gate 4: Fullscreen Writing Mode And Composer Workspace
 
 Gate 4 defines the writing workspace.

BITCODE_SPEC_V37_DELTA.md

@@ -55,6 +55,22 @@ Gate 2 adds `.bitcode/v37-conversation-session-route-history.json`, `buildConver
 The required operations are create, restore, branch, retry, redact, and stream.
 Restore, branch, retry, and redaction preserve route-local history and proof roots without exposing protected source, raw protected prompts, protected model responses with source, wallet private material, provider tokens, secrets, settlement private payloads, unpaid AssetPack source, or any global ledger authority claim.
 
+## Gate 3 implementation notes
+
+ConversationStreamEvent stream contracts are source-safe SSE metadata
+contracts, not a transcript of raw model or tool payloads. Gate 3 adds
+`.bitcode/v37-conversation-stream-event-contract.json`,
+`buildConversationStreamEventContract`, the route-facing stream event adapter,
+package tests, route tests, UI tests, and `check:v37-gate3`.
+The required event rows are model deltas, tool calls, retrieval summaries,
+proof roots, retry states, completion decisions, and error rows.
+The shared execution log is the canonical stream UI: collapsed rows show a
+readable status, expanded rows show source-safe metadata, and the header can
+surface event id, proof root, redaction posture, prompt/result disclosure
+posture, and fail-closed state.
+Gate 3 keeps gate-quality CI greenable by bounding the workflow runtime and
+running maintained targeted package tests inside the gate job.
+
 ## V37 gate plan
 
 - Gate 1: V37 Conversations Roadmap And Spec Opening

BITCODE_SPEC_V37_NOTES.md

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; V37 parity includes Website Conversations spec family, roadmap, docs, workflow, checker posture, and Gate 2 ConversationSession route-history contracts
+- V37 state: draft implementation; V37 parity includes Website Conversations spec family, roadmap, docs, workflow, checker posture, Gate 2 ConversationSession route-history contracts, and Gate 3 ConversationStreamEvent stream UI/event 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`, and `.bitcode/v37-conversation-session-route-history.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
+- 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`, and `.bitcode/v37-conversation-stream-event-contract.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
 - Spec companion: `BITCODE_SPEC_V37.md`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V37_DELTA.md`
@@ -23,7 +23,7 @@ Every V37 gate must name package-owned conversation objects, source-safe payload
 
 ## Audit basis
 
-Gate 1 and Gate 2 audit basis:
+Gate 1, Gate 2, and Gate 3 audit basis:
 
 - `BITCODE_SPEC.txt`
 - `BITCODE_SPEC_V36.md`
@@ -53,6 +53,19 @@ Gate 1 and Gate 2 audit basis:
 - `uapi/app/conversations/conversation-session-route-history.ts`
 - `uapi/tests/api/conversationSessionRouteHistory.test.ts`
 - `uapi/tests/api/conversationSessionRouteHistoryContract.test.ts`
+- `packages/protocol/src/canonical/conversation-stream-event-contract.js`
+- `packages/protocol/test/conversation-stream-event-contract.test.js`
+- `packages/api/src/conversations/stream-events.ts`
+- `packages/api/src/conversations/__tests__/stream-events.test.ts`
+- `scripts/generate-v37-conversation-stream-event-contract.mjs`
+- `scripts/check-v37-gate3-conversation-stream-event-contracts.mjs`
+- `.bitcode/v37-conversation-stream-event-contract.json`
+- `uapi/hooks/useConversationStream.ts`
+- `uapi/app/conversations/components/hooks/usePipelineState.ts`
+- `uapi/components/base/bitcode/execution/pipeline-execution-log.tsx`
+- `uapi/components/base/bitcode/execution/pipeline-execution-log-header.tsx`
+- `uapi/tests/api/conversationStreamEventContract.test.ts`
+- `uapi/tests/conversationStreamPipelineLog.test.tsx`
 
 No `_legacy/` source is active source truth.
 
@@ -63,7 +76,7 @@ No `_legacy/` source is active source truth.
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V37.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v37/gate-1-conversations-roadmap-opening` | drafted | V37 family validates in draft mode over active V36 and `check:v37-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V36 active, V37 draft, and coherent post-V37 responsibility. |
 | Conversation session and route history | Gate 2 | `ConversationSession`, `.bitcode/v37-conversation-session-route-history.json`, package source, route contracts, tests, and `check:v37-gate2` | closed | Route-local identity, route-local history, restore, branch, retry, redaction, stream, and proof roots are typed and source-safe. |
-| Conversation stream events | Gate 3 | future `ConversationStreamEvent`, stream UI tests, telemetry hooks, and `check:v37-gate3` | pending | Model deltas, tool calls, retrieval summaries, completion decisions, retry/error states, proof roots, and expanded metadata are source-safe. |
+| Conversation stream events | Gate 3 | `ConversationStreamEvent`, `.bitcode/v37-conversation-stream-event-contract.json`, route-attached SSE metadata, stream UI tests, telemetry hooks, and `check:v37-gate3` | closed | Model deltas, tool calls, retrieval summaries, completion decisions, retry/error states, proof roots, collapsed readable status, expanded metadata, and disclosure posture are source-safe. |
 | Writing workspace | Gate 4 | future `ConversationWritingWorkspace`, fullscreen route tests, accessibility proof, and `check:v37-gate4` | pending | Read Request, Need feedback, AssetPack review notes, and Terminal handoff writing flows are accessible, restorable, and source-safe. |
 | Source selectors | Gate 5 | future `ConversationSourceSelector`, policy tests, rights checks, and `check:v37-gate5` | pending | Repository, branch, commit, deposit, BTD range, AssetPack preview, document, and prior conversation selectors are policy-gated. |
 | Terminal handoff | Gate 6 | future `ConversationTerminalHandoff`, Terminal integration tests, and `check:v37-gate6` | pending | Conversations can hand source-safe transaction intent to Terminal without becoming a parallel ledger/wallet authority. |
@@ -85,6 +98,8 @@ No `_legacy/` source is active source truth.
 | Package docs | README, protocol package README, demonstration README, and PR template state V36 active / V37 draft workflow | drafted |
 | Conversations vocabulary | V37 spec family names `ConversationSession`, `ConversationMessage`, `ConversationStreamEvent`, `ConversationWritingWorkspace`, `ConversationSourceSelector`, and `ConversationTerminalHandoff` | drafted |
 | ConversationSession route-history artifact | `ConversationSession` source emits `.bitcode/v37-conversation-session-route-history.json` and `check:v37-gate2` validates it | closed |
+| ConversationStreamEvent artifact | `ConversationStreamEvent` source emits `.bitcode/v37-conversation-stream-event-contract.json` and `check:v37-gate3` validates it | closed |
+| ConversationStreamEvent event coverage | `source-safe-conversation-stream-event-metadata` covers model deltas, tool calls, retrieval summaries, proof roots, retry states, completion decisions, and error rows | closed |
 | Disclosure boundary | Conversations expose source-safe stream, selector, proof, handoff, and policy metadata, not protected source, secrets, wallet private material, or unpaid AssetPack contents | drafted |
 | Terminal handoff boundary | Terminal remains the transaction cockpit and ledger/wallet authority; Conversations prepare and hand off source-safe intent | drafted |
 | Privacy posture | Conversation persistence, export, delete, retention, replay, and repair paths preserve disclosure classes and redaction policy | drafted |