Merge pull request #115 from engineeredsoftware/v37/gate-5-source-selectors-context-policy

V37 Gate 5: Source Selectors And Context Policy

Author: geraldarthurdavis

.bitcode/v37-conversation-source-selector.json

@@ -118,6 +118,9 @@ jobs:
               if [ -f scripts/check-v37-gate4-conversation-writing-workspace.mjs ]; then
                 node scripts/check-v37-gate4-conversation-writing-workspace.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate5-conversation-source-selector.mjs ]; then
+                node scripts/check-v37-gate5-conversation-source-selector.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -247,6 +247,9 @@ jobs:
               if [ -f scripts/check-v37-gate4-conversation-writing-workspace.mjs ]; then
                 node scripts/check-v37-gate4-conversation-writing-workspace.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate5-conversation-source-selector.mjs ]; then
+                node scripts/check-v37-gate5-conversation-source-selector.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -336,6 +339,7 @@ jobs:
             tests/api/conversationSessionRouteHistoryContract.test.ts \
             tests/api/conversationStreamEventContract.test.ts \
             tests/conversationStreamPipelineLog.test.tsx \
+            tests/conversationSourceSelector.test.tsx \
             tests/conversationWritingWorkspace.test.tsx \
             tests/auxillariesExternalsPane.test.tsx \
             tests/profileStep.test.tsx \

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

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 4 closes ConversationWritingWorkspace fullscreen writing mode and composer workspace over active V36 Exchange canon
+- V37 state: draft implementation; Gate 5 closes ConversationSourceSelector source selection and context policy 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`, and `.bitcode/v37-conversation-writing-workspace.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, and Gate 4 package-owned ConversationWritingWorkspace fullscreen writing 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`, and `.bitcode/v37-conversation-source-selector.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, and Gate 5 package-owned ConversationSourceSelector source/context policy 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`
@@ -33,7 +33,7 @@ V37 adds Website Conversations product contracts over inherited V36 canon:
 - `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, 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.
+- `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.
 
 V37 does not replace the V28 ChatGPT App, V33 interface contracts, V35 telemetry/docs, or V36 Exchange law.
@@ -132,6 +132,32 @@ package tests, UI tests, docs, workflow wiring, source safety, mode/action
 coverage, route-local draft keys, keyboard behavior, responsive fullscreen
 layout, recovery states, proof roots, and source-safe handoff summaries.
 
+## V37 Gate 5 ConversationSourceSelector context-policy canon
+
+Gate 5 implements `ConversationSourceSelector` as the package-owned source
+selection and context-policy contract for Website Conversations. It owns
+repository, branch, commit, deposit, BTD range, AssetPack preview, document,
+and prior conversation selectors. It emits
+`.bitcode/v37-conversation-source-selector.json` with
+`source-safe-conversation-source-selector-metadata`, deterministic row roots,
+deterministic detail roots, selector kind ids, governance ids, preview states,
+required field ids, proof roots, event ids, source evidence roots, and
+source-safe disclosure limits.
+
+Conversation source selection is route-local context metadata. It can select
+source-safe references, preview allowed/denied/retry posture, and explain the
+account, organization, wallet, rights, settlement, disclosure, and policy
+dimensions that govern the selector. It does not reveal protected repository
+source, unpaid AssetPack source, private BTD material, provider tokens, wallet
+private material, settlement private payloads, raw protected prompts, raw
+protected model responses, or global ledger authority claims. Full AssetPack
+or BTD source visibility remains governed by rights transfer and settlement.
+
+`check:v37-gate5` validates package source, generated artifact freshness,
+package tests, UI tests, docs, workflow wiring, selector kind coverage,
+governance coverage, allowed/denied/retry preview states, rights and
+settlement posture, proof roots, event ids, and source-safe preview metadata.
+
 ## Inherited V36 Exchange canon
 
 The promoted V36 sections below remain inherited canonical law for Exchange.
@@ -809,13 +835,15 @@ V36 inherits operator quality, visual/accessibility/performance posture, project
 | `.bitcode/v37-conversation-session-route-history.json` | Gate 2 | source-safe | ConversationSession route-local history contracts |
 | `.bitcode/v37-conversation-stream-event-contract.json` | Gate 3 | source-safe | ConversationStreamEvent stream UI/event contracts |
 | `.bitcode/v37-conversation-writing-workspace.json` | Gate 4 | source-safe | ConversationWritingWorkspace fullscreen composer contracts |
+| `.bitcode/v37-conversation-source-selector.json` | Gate 5 | source-safe | ConversationSourceSelector source/context policy contracts |
 
 ### V37 specifying generated artifacts
 
 Gate 1 requires `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, and `.bitcode/v37-canon-posture-drift-report.json` readiness.
 Gate 2 adds `.bitcode/v37-conversation-session-route-history.json` from the package-owned ConversationSession route-history builder with package tests, route tests, workflow checks, and source-safety checks.
 Gate 3 adds `.bitcode/v37-conversation-stream-event-contract.json` from the package-owned ConversationStreamEvent builder with package tests, route/UI tests, workflow checks, and source-safety checks.
 Gate 4 adds `.bitcode/v37-conversation-writing-workspace.json` from the package-owned ConversationWritingWorkspace builder with package tests, fullscreen workspace UI tests, workflow checks, and source-safety checks.
+Gate 5 adds `.bitcode/v37-conversation-source-selector.json` from the package-owned ConversationSourceSelector builder with package tests, source selector UI tests, workflow checks, and source-safety checks.
 Later V37 gates add Conversations generated artifacts only when their package-owned builders, route checks, stream tests, telemetry checks, and source-safety tests exist.
 
 ### Shared generated-artifact fields

BITCODE_SPEC_V37.md

@@ -128,6 +128,15 @@ Closure acceptance:
 - selector previews are source-safe and explain denial/retry states;
 - `pnpm run check:v37-gate5` validates selector contracts, rights checks, route tests, UI tests, docs, telemetry, and workflow wiring.
 
+Gate 5 closure adds package-backed `ConversationSourceSelector` source,
+`.bitcode/v37-conversation-source-selector.json`,
+`source-safe-conversation-source-selector-metadata`, repository, branch,
+commit, deposit, BTD range, AssetPack preview, document, and prior
+conversation selector kinds, account, organization, wallet, rights,
+settlement, disclosure, and policy governance dimensions, allowed, denied, and
+retry-required preview states, source-safe selector UI binding, package tests,
+UI tests, workflow wiring, and `check:v37-gate5`.
+
 ### Gate 6: Conversation To Terminal Transaction Handoff
 
 Gate 6 connects conversation intent to Terminal execution.

BITCODE_SPEC_V37_DELTA.md

@@ -86,6 +86,23 @@ messages are redacted source-safe metadata only and must not expose protected
 source, provider tokens, private wallet material, unpaid AssetPack source,
 settlement private payloads, or global ledger authority claims.
 
+## Gate 5 implementation notes
+
+ConversationSourceSelector contracts are source-safe context-policy
+contracts, not source disclosure or rights transfer. Gate 5 adds
+`.bitcode/v37-conversation-source-selector.json`,
+`buildConversationSourceSelector`, the route-facing source selector helper,
+the source selector component, package tests, UI tests, and
+`check:v37-gate5`.
+The required selector kinds are repository, branch, commit, deposit, BTD
+range, AssetPack preview, document, and prior conversation. The required
+governance dimensions are account, organization, wallet, rights, settlement,
+disclosure, and policy. The preview states are allowed, denied, and
+retry-required, and every preview is source-safe metadata only. Full protected
+source, unpaid AssetPack source, private BTD material, wallet private material,
+provider tokens, protected prompts/responses, settlement private payloads, and
+global ledger authority claims remain outside Conversations.
+
 ## V37 gate plan
 
 - Gate 1: V37 Conversations Roadmap And Spec Opening

BITCODE_SPEC_V37_NOTES.md

@@ -86,7 +86,7 @@ No `_legacy/` source is active source truth.
 | 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 | `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 | `ConversationWritingWorkspace`, `.bitcode/v37-conversation-writing-workspace.json`, fullscreen workspace UI tests, accessibility proof, and `check:v37-gate4` | closed | 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. |
+| Source selectors | Gate 5 | `ConversationSourceSelector`, `.bitcode/v37-conversation-source-selector.json`, policy tests, rights checks, source selector UI tests, and `check:v37-gate5` | closed | 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. |
 | Persistence privacy redaction | Gate 7 | future storage contracts, privacy tests, redaction tests, and `check:v37-gate7` | pending | Retention, export, delete, replay, incident repair, protected prompt/model response redaction, and disclosure classes are enforced. |
 | Telemetry proof hooks docs | Gate 8 | future telemetry taxonomy, docs, dashboards, runbooks, generated proof hooks, and `check:v37-gate8` | pending | Conversation sessions, messages, streams, tools, selectors, handoffs, retries, errors, and completions are observable and source-safe. |
@@ -110,6 +110,8 @@ No `_legacy/` source is active source truth.
 | 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 |
 | ConversationWritingWorkspace artifact | `ConversationWritingWorkspace` source emits `.bitcode/v37-conversation-writing-workspace.json` and `check:v37-gate4` validates it | closed |
 | ConversationWritingWorkspace coverage | `source-safe-conversation-writing-workspace-metadata` covers Read Request, Need feedback, AssetPack review note, Terminal handoff summary, save, restore, summarize, handoff, keyboard behavior, responsive layout, recovery state, proof roots, and event ids | closed |
+| ConversationSourceSelector artifact | `ConversationSourceSelector` source emits `.bitcode/v37-conversation-source-selector.json` and `check:v37-gate5` validates it | closed |
+| ConversationSourceSelector coverage | `source-safe-conversation-source-selector-metadata` covers repository, branch, commit, deposit, BTD range, AssetPack preview, document, prior conversation, account, organization, wallet, rights, settlement, disclosure, policy, allowed, denied, retry-required, proof roots, and event ids | 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 |
@@ -149,6 +151,19 @@ No `_legacy/` source is active source truth.
 | Emitted summaries are source-safe | `uapi/app/conversations/conversation-writing-workspace.ts` redacts source blocks, token-shaped values, secret fields, private keys, and JWT-shaped values before preview or handoff | closed |
 | Workspace UI is accessible and wired | `uapi/app/conversations/components/ConversationWritingWorkspace.tsx`, `uapi/app/conversations/components/ConversationsOverlay.tsx`, `uapi/tests/conversationWritingWorkspace.test.tsx`, `scripts/check-v37-gate4-conversation-writing-workspace.mjs`, `.github/workflows/bitcode-gate-quality.yml` | closed |
 
+## V37 Gate 5 Parity
+
+| Requirement | Source evidence | Current V37 judgment |
+| --- | --- | --- |
+| `ConversationSourceSelector` context policy is package-owned | `packages/protocol/src/canonical/conversation-source-selector.js`, `packages/protocol/src/index.js`, `packages/protocol/src/index.d.ts` | closed |
+| Generated source selector artifact exists | `.bitcode/v37-conversation-source-selector.json`, `scripts/generate-v37-conversation-source-selector.mjs`, `pnpm run check:v37-conversation-source-selector` | closed |
+| Required selector kinds are covered | repository, branch, commit, deposit, BTD range, AssetPack preview, document, and prior conversation | closed |
+| Governance dimensions are covered | account, organization, wallet, rights, settlement, disclosure, and policy posture | closed |
+| Preview states are explainable | allowed, denied, and retry-required previews include source-safe reason/retry metadata | closed |
+| Source selector UI is wired | `uapi/app/conversations/conversation-source-selector.ts`, `uapi/app/conversations/components/ConversationSourceSelector.tsx`, `uapi/app/conversations/components/ConversationsOverlay.tsx`, and `uapi/tests/conversationSourceSelector.test.tsx` | closed |
+| Selector previews are source-safe | protected source, unpaid AssetPack source, private BTD material, provider tokens, wallet private material, settlement private payloads, protected prompts/responses, and global ledger authority claims are forbidden | closed |
+| Workflow, package, and UI tests are wired | `packages/protocol/test/conversation-source-selector.test.js`, `scripts/check-v37-gate5-conversation-source-selector.mjs`, `.github/workflows/bitcode-gate-quality.yml`, and `.github/workflows/bitcode-canon-quality.yml` | closed |
+
 ## Inherited V36 implementation matrix
 
 | Area | Gate | Source evidence | Judgment | Closure requirement |

BITCODE_SPEC_V37_PARITY_MATRIX.md

@@ -207,9 +207,14 @@ Gate 10 is the promotion-readiness gate. V37 Gate 1 is wired through
 `pnpm run check:v37-conversation-session-route-history`; V37 Gate 3 is wired
 through `pnpm run check:v37-gate3`; and V37 Gate 4 is wired through
 `pnpm run check:v37-gate4` and
-`pnpm run check:v37-conversation-writing-workspace`. Later V37 gates add
-Conversations generated artifacts before `check:v37-gate10` and the V37
-promotion workflow exist.
+`pnpm run check:v37-conversation-writing-workspace`. V37 Gate 5 is wired
+through `pnpm run check:v37-gate5` and
+`pnpm run check:v37-conversation-source-selector`, covering source-safe
+repository, branch, commit, deposit, BTD range, AssetPack preview, document,
+and prior conversation selectors with account, organization, wallet, rights,
+settlement, disclosure, and policy posture. Later V37 gates add Conversations
+generated artifacts before `check:v37-gate10` and the V37 promotion workflow
+exist.
 The promoted V35 closure remains reproducible through `pnpm run check:v35-gate10`
 and [v35-canon-promotion.yml](.github/workflows/v35-canon-promotion.yml).
 The application CI workflow uses the root pnpm workspace install, runs uapi