Merge pull request #140 from engineeredsoftware/v39/gate-5-read-fits-finding-runtime-ranking-replay

V39 Gate 5: ReadFitsFinding Runtime Replay

Author: geraldarthurdavis

.bitcode/v39-read-fits-finding-runtime.json

@@ -193,6 +193,9 @@ jobs:
               if [ -f scripts/check-v39-gate4-read-need-review-resynthesis.mjs ]; then
                 node scripts/check-v39-gate4-read-need-review-resynthesis.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
               fi
+              if [ -f scripts/check-v39-gate5-read-fits-finding-runtime.mjs ]; then
+                node scripts/check-v39-gate5-read-fits-finding-runtime.mjs --skip-branch-check --skip-package-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -322,6 +322,9 @@ jobs:
               if [ -f scripts/check-v39-gate4-read-need-review-resynthesis.mjs ]; then
                 node scripts/check-v39-gate4-read-need-review-resynthesis.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
               fi
+              if [ -f scripts/check-v39-gate5-read-fits-finding-runtime.mjs ]; then
+                node scripts/check-v39-gate5-read-fits-finding-runtime.mjs --skip-branch-check --skip-package-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -134,6 +134,16 @@ blockers; only `acceptReadNeed` may produce Finding Fits admission.
 Gate 5 makes `ReadFitsFindingSynthesis` search the whole available Depository for many candidate deposits.
 It must execute inference-derived query planning, lexical/symbolic/path/metadata/measurement/vector/provider channels, threshold ranking, verification, selected-fit provenance, replay receipts, and repair paths over the accepted Need.
 The active vector policy remains OpenAI `text-embedding-3-small`, 1536 dimensions, cosine similarity, and `match_deliverable_vectors` until a tested migration is specified.
+The implementation basis is `ReadFitsFindingRuntime`, exported from
+`packages/pipelines/asset-pack/src/read-fits-finding-runtime.ts`. It wraps
+the depository search result with `ReadFitsFindingReplayReceipt`,
+`ReadFitsFindingStorageRecord`, `ReadFitsFindingTelemetryReceipt`, and
+`ReadFitsFindingRepairPosture` projections so an accepted Need can replay the
+source-safe query plan, ranking root, selected-fit provenance root, embedding
+policy, and candidate counts without exposing protected source or unpaid
+AssetPack source. The generated source-safe proof artifact is
+`.bitcode/v39-read-fits-finding-runtime.json`, checked by
+`pnpm run check:v39-gate5`.
 
 ### Gate 6: AssetPack Preview, Quote, And Disclosure Boundary
 
@@ -248,8 +258,8 @@ Current canonical objects and emitted artifacts: query receipts, search channel
 Current algorithms and derivation rules: inference-derived queries search lexical, symbolic, path, metadata, measurement, embedding/vector, and provider-specific channels before ranking.
 Current invariants and fail-closed conditions: no-survivor asset pack and unsupported vector policy fail closed.
 Current proof obligations: Selection-and-materialization, Verification-decisions, and Disclosure-boundary proofs.
-Current source-bearing implementation basis: `depository-search.ts`, `embedding-config.ts`, and depository-search tools.
-Current validating commands and parity basis: V39 Gate 7 checks and later Gate 8 handoff checks.
+Current source-bearing implementation basis: `depository-search.ts`, `read-fits-finding-runtime.ts`, `embedding-config.ts`, and depository-search tools.
+Current validating commands and parity basis: V39 Gate 5 checks, Gate 7 checks, and later Gate 8 handoff checks.
 Current accepted boundaries: source-safe preview before settlement, full source only after paid rights transfer.
 
 ### Selection and materialization

BITCODE_SPEC_V39.md

@@ -145,7 +145,16 @@ Closure acceptance:
 
 Closure implementation:
 
-- Pending Gate 5 work must define runtime search artifacts, active embedding policy checks, and many-candidate replay evidence.
+- Gate 5 defines package-backed `ReadFitsFindingRuntime` source,
+  deterministic `.bitcode/v39-read-fits-finding-runtime.json`, package tests
+  for many-fit search, blocked admission, storage projection, replay, and
+  source-safe summaries, and protocol tests for the generated proof artifact.
+  Runtime payloads include `ReadFitsFindingReplayReceipt`,
+  `ReadFitsFindingStorageRecord`, `ReadFitsFindingTelemetryReceipt`, and
+  `ReadFitsFindingRepairPosture`. The runtime binds accepted-Need admission,
+  source-safe query plan, ranking evidence, selected-fit provenance, active
+  embedding policy, and repair posture without exposing protected source or
+  unpaid AssetPack source.
 
 ### Gate 6: AssetPack Preview, Quote, And Disclosure Boundary
 

BITCODE_SPEC_V39_DELTA.md

@@ -211,6 +211,14 @@ without accidentally admitting Finding Fits.
 ## Gate 5 implementation notes
 
 Gate 5 closes `ReadFitsFindingSynthesis` as a runtime many-candidate search pipeline with replayable query, ranking, threshold, and selected-fit provenance receipts across lexical, symbolic, path, metadata, measurement, vector, and provider-specific channels.
+The package-owned runtime is `ReadFitsFindingRuntime`. It persists
+source-safe storage records for accepted-Need admission, query plan, search
+channels, candidate ranking, selected-fit provenance, fit result, telemetry,
+repair posture, and source-safe replay receipt. The source-safe replay receipt
+verifies query-plan, query, ranking, selected-fit provenance, embedding policy,
+and candidate-count roots so an operator can diagnose blocked or no-worthy
+Finding Fits runs without raw source, raw provider responses, credentials,
+wallet private material, settlement payloads, or unpaid AssetPack source.
 
 ## Gate 6 implementation notes
 

BITCODE_SPEC_V39_NOTES.md

@@ -73,7 +73,7 @@ No `_legacy/` source is active source truth.
 | Depository supply indexing | Gate 2 | `packages/pipelines/asset-pack/src/depository-supply-index.ts`, `.bitcode/v39-depository-supply-indexing.json`, `packages/pipelines/asset-pack/src/__tests__/depository-supply-index.test.ts`, `packages/protocol/test/v39-depository-supply-indexing.test.js` | implemented | Deposited source becomes measurable, indexable, rights-aware, searchable, and repairable through source-safe `DepositorySupplyIndex` records. |
 | Enterprise Reading UX state machine | Gate 3 | `uapi/app/terminal/terminal-enterprise-reading-ux-state.ts`, `TerminalDepositReadWorkbench.tsx`, Conversation handoff, Terminal route query, `.bitcode/v39-enterprise-reading-ux-state.json`, focused UAPI tests, opt-in browser proof workflow | implemented | The five-step enterprise Reading UX is implemented with low-detail defaults, expandable source-safe detail, route-state handoff, rich execution stream integration, and source-safe disclosure proof. |
 | ReadNeed review and resynthesis | Gate 4 | `packages/pipelines/asset-pack/src/read-need-review-resynthesis.ts`, `.bitcode/v39-read-need-review-resynthesis.json`, package tests, route tests, protocol tests | implemented | Finding Fits remains blocked until a reviewed Need is accepted; rejected Needs preserve feedback and stay blocked. |
-| ReadFitsFinding runtime and replay | Gate 5 | `ReadFitsFindingSynthesis`, search tools, embeddings, ranking, selected-fit provenance, replay receipts | pending | Finding Fits searches the whole available Depository for many above-threshold candidates. |
+| ReadFitsFinding runtime and replay | Gate 5 | `packages/pipelines/asset-pack/src/read-fits-finding-runtime.ts`, `depository-search.ts`, `.bitcode/v39-read-fits-finding-runtime.json`, package tests, protocol tests | implemented | Finding Fits searches the whole available Depository for many above-threshold candidates and persists source-safe replay, storage, telemetry, and repair receipts. |
 | AssetPack preview and quote boundary | Gate 6 | AssetPack preview tests, quote tests, disclosure leak scans, proof roots | pending | Preview is commercially sufficient without exposing source-bearing AssetPack content. |
 | Settlement, BTD rights, and delivery | Gate 7 | BTC settlement receipt, BTD rights transfer, source-to-shares, ledger/database/storage, PR delivery | pending | Payment unlocks rights and delivery; repair paths are auditable. |
 | Operational telemetry and repair | Gate 8 | stream events, operator readback, runbook hooks, proof roots, repair commands | pending | Reading is observable and repairable end to end. |
@@ -95,7 +95,7 @@ No `_legacy/` source is active source truth.
 | Depository supply indexing | Deposits become measurable, embedded, indexable, rights-aware, searchable, and repairable | implemented |
 | Enterprise Reading UX | Terminal implements request read, review Need, request Finding Fits, review preview, buy and settle | implemented |
 | ReadNeed runtime | `ReadNeedComprehensionSynthesis` persists reviewable Needs, feedback, resynthesis, measurements, accepted-Need admission, and rejected-Need posture | implemented |
-| ReadFitsFinding runtime | `ReadFitsFindingSynthesis` searches many above-threshold deposits with replayable query, ranking, threshold, and selected-fit provenance receipts | pending |
+| ReadFitsFinding runtime | `ReadFitsFindingSynthesis` searches many above-threshold deposits with replayable query, ranking, threshold, and selected-fit provenance receipts | implemented |
 | Preview and quote | AssetPack preview is source-safe and quote is deterministic before settlement | pending |
 | Settlement and delivery | BTC settlement, BTD rights transfer, source-to-shares compensation, ledger/database/storage sync, and delivery are auditable | pending |
 | Telemetry and repair | Reading emits source-safe rich stream events and operator readback with proof roots and repair posture | pending |
@@ -165,16 +165,29 @@ No `_legacy/` source is active source truth.
 
 ## Later Gate Parity
 
-Later V39 gates must add gate-specific parity sections when their implementation begins. Gates 1 through 4 intentionally do not claim closure for Finding Fits runtime, preview/quote, settlement/delivery, telemetry/repair, interface parity, rehearsal, or promotion readiness.
+Later V39 gates must add gate-specific parity sections when their implementation begins. Gates 1 through 5 intentionally do not claim closure for preview/quote, settlement/delivery, telemetry/repair, interface parity, rehearsal, or promotion readiness.
 
 ## accepted boundaries and reopen conditions
 
 V39 Gate 1 accepts only draft-family, roadmap, workflow, branch, and documentation posture closure.
 V39 Gate 2 accepts only Depository supply indexing, source-safe search document, vector projection, storage readback posture, rights boundary, repair posture, and Finding Fits handoff closure.
 V39 Gate 3 accepts only enterprise Reading UX state, source-safe route handoff/readback, low-detail/expandable Terminal rendering, rich stream-log integration, opt-in browser proof wiring, and generated UX proof artifact closure.
 V39 Gate 4 accepts only ReadNeed review runtime storage projection, feedback/resynthesis lineage, accepted-Need admission, rejected-Need posture, source-safe telemetry receipts, route actions, and generated review proof artifact closure.
+V39 Gate 5 accepts only ReadFitsFinding runtime storage projection, many-candidate depository search, source-safe query/ranking/provenance evidence, replay receipts, repair posture, active embedding policy, and generated runtime proof artifact closure.
 Later gate scope is intentionally pending and must be reopened into gate-specific parity sections before implementation starts.
 
+## Gate 5 Parity
+
+V39 Gate 5 is implemented when `ReadFitsFindingRuntime` wraps the accepted-Need
+depository search with source-safe runtime, storage, telemetry, replay, and
+repair records. The parity source is
+`packages/pipelines/asset-pack/src/read-fits-finding-runtime.ts`; it must not
+expose protected source, raw protected prompts, raw provider responses,
+credentials, wallet private material, settlement private payloads, or unpaid
+AssetPack source. The generated proof artifact is
+`.bitcode/v39-read-fits-finding-runtime.json` and the gate check is
+`pnpm run check:v39-gate5`.
+
 ## completion condition
 
-V39 Gate 4 is complete when `check:v39-gate4`, focused ReadNeed package and route tests, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-4-*` branch.
+V39 Gate 5 is complete when `check:v39-gate5`, focused ReadFitsFinding package tests, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-5-*` branch.

BITCODE_SPEC_V39_PARITY_MATRIX.md

@@ -275,6 +275,14 @@ PipelineExecution-compatible storage records. Finding Fits remains blocked
 until an accepted Need is present. Use
 `pnpm run generate:v39-read-need-review-resynthesis` and
 `pnpm run check:v39-gate4` before closing the gate.
+V39 Gate 5 adds the package-owned `ReadFitsFindingRuntime` and source-safe
+generated artifact `.bitcode/v39-read-fits-finding-runtime.json`.
+ReadFitsFindingSynthesis now projects accepted-Need admission, source-safe
+query plans, seven search channels, many-candidate ranking, selected-fit
+provenance, active embedding policy, replay receipts, repair posture, and
+telemetry receipts into PipelineExecution-compatible storage records. Use
+`pnpm run generate:v39-read-fits-finding-runtime` and
+`pnpm run check:v39-gate5` before closing the gate.
 V36 Gate 2 anchors market-wide activity through the package-owned
 `ExchangeActivityBook` and the source-safe generated artifact
 `.bitcode/v36-exchange-activity-book.json`, including listing, bid, ask,
@@ -437,7 +445,10 @@ For V39, Gate 1 opens `version/v39` and the gate-quality posture through
 artifacts and the V39 promotion workflow.
 V39 Gate 2 is wired through `pnpm run check:v39-gate2`; V39 Gate 3 is wired
 through `pnpm run check:v39-gate3` and its generated
-`.bitcode/v39-enterprise-reading-ux-state.json` artifact.
+`.bitcode/v39-enterprise-reading-ux-state.json` artifact. V39 Gate 4 is wired
+through `pnpm run check:v39-gate4`; V39 Gate 5 is wired through
+`pnpm run check:v39-gate5` and its generated
+`.bitcode/v39-read-fits-finding-runtime.json` artifact.
 V38 Gates 1 through 11 are wired through `pnpm run check:v38-gate1`,
 `pnpm run check:v38-gate2`, `pnpm run check:v38-gate3`,
 `pnpm run check:v38-gate4`, `pnpm run check:v38-gate5`,

README.md

@@ -5,8 +5,8 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V38`
 - Current active canon: `BITCODE_SPEC_V38.md`
 - Current draft target: `BITCODE_SPEC_V39.md`.
-- Current working gate: V39 Gate 4 ReadNeed Review, Resynthesis, And Admission Runtime.
-- Next queued gate after V39 Gate 4 closure: V39 Gate 5 ReadFitsFinding Runtime, Ranking, And Replay.
+- Current working gate: V39 Gate 5 ReadFitsFinding Runtime, Ranking, And Replay.
+- Next queued gate after V39 Gate 5 closure: V39 Gate 6 AssetPack Preview, Quote, And Disclosure Boundary.
 - Latest closed version: V38 Inference Correctness, which promoted pipeline execution call-stack law, PTRR/Failsafe/Thricified parity, prompt and PromptPart benchmarking, source-safe inference telemetry, ReadNeedComprehensionSynthesis hardening, ReadFitsFindingSynthesis search and embeddings, AssetPack economic traceability, local/staging inference rehearsal, and V38 promotion readiness.
 - Recent V38 closure anchor: V38 Gate 11 Promotion Readiness generated V38 proof support, promoted `BITCODE_SPEC.txt` to `V38`, prepared V38 active / V39 draft runtime posture, and closed inference correctness canon.
 - V34 Gate 2 closure anchor: deployment-depth now owns package-backed `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract` source, deterministic `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json`, and visible `value-bearing-mainnet` blocking through `blocked_future_canon_required`.
@@ -64,6 +64,7 @@
 - V39 Gate 2 closure anchor: Commercial Reading readiness now owns package-backed `DepositorySupplyIndex` source, deterministic `.bitcode/v39-depository-supply-indexing.json`, source-safe Depository supply records, lexical/metadata/measurement/vector search documents, active OpenAI embedding/vector projection, Supabase storage readback posture, depositor/Reader settlement boundary, repair actions, Finding Fits handoff, package tests, protocol tests, workflow wiring, and `check:v39-gate2`.
 - V39 Gate 3 closure anchor: Commercial Reading readiness now owns package-backed `TerminalEnterpriseReadingUxState` source, deterministic `.bitcode/v39-enterprise-reading-ux-state.json`, five-step Reading state, source-safe `readingStage` Conversation handoff and Terminal readback, low-detail defaults, expandable source-safe detail, rich execution stream integration, component/route tests, opt-in browser proof workflow wiring, and `check:v39-gate3`.
 - V39 Gate 4 closure anchor: Commercial Reading readiness now owns package-backed `ReadNeedReviewResynthesisRuntime` source, deterministic `.bitcode/v39-read-need-review-resynthesis.json`, Read Request persistence, synthesized Need storage, feedback/resynthesis lineage, Need measurement storage, accepted-Need admission, rejected-Need posture, source-safe telemetry receipts, route/runtime storage projection tests, workflow wiring, and `check:v39-gate4`.
+- V39 Gate 5 closure anchor: Commercial Reading readiness now owns package-backed `ReadFitsFindingRuntime` source, deterministic `.bitcode/v39-read-fits-finding-runtime.json`, accepted-Need-only Finding Fits admission, source-safe query plans, seven search channels, many-candidate ranking, selected-fit provenance roots, active OpenAI embedding policy, replay receipts, repair posture, package tests, protocol tests, workflow wiring, and `check:v39-gate5`.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

SPECIFICATIONS_ROADMAP.md

@@ -224,6 +224,9 @@
     "generate:v39-read-need-review-resynthesis": "node scripts/generate-v39-read-need-review-resynthesis.mjs",
     "check:v39-read-need-review-resynthesis": "node scripts/generate-v39-read-need-review-resynthesis.mjs --check",
     "check:v39-gate4": "node scripts/check-v39-gate4-read-need-review-resynthesis.mjs",
+    "generate:v39-read-fits-finding-runtime": "node scripts/generate-v39-read-fits-finding-runtime.mjs",
+    "check:v39-read-fits-finding-runtime": "node scripts/generate-v39-read-fits-finding-runtime.mjs --check",
+    "check:v39-gate5": "node scripts/check-v39-gate5-read-fits-finding-runtime.mjs",
     "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs",
     "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check",
     "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs",