V39 Gate 4: Close ReadNeed review runtime

Adds the package-owned ReadNeedReviewResynthesisRuntime, rejected-Need posture, accepted-Need-only Finding Fits admission, source-safe storage and telemetry projections, route action coverage, deterministic V39 Gate 4 artifact/checker, docs/spec updates, and workflow wiring.

Validation: pnpm run check:v39-gate4; focused asset-pack ReadNeed Jest; focused UAPI read-review Jest; pnpm --filter @bitcode/protocol test; package/protocol/uapi type checks; V39/V38 spec-family and canon-posture checks; git diff --check.

Author: geraldarthurdavis

.bitcode/v39-read-need-review-resynthesis.json

@@ -190,6 +190,9 @@ jobs:
               if [ -f scripts/check-v39-gate3-enterprise-reading-ux-state.mjs ]; then
                 node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs --skip-branch-check --skip-uapi-tests
               fi
+              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
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -319,6 +319,9 @@ jobs:
               if [ -f scripts/check-v39-gate3-enterprise-reading-ux-state.mjs ]; then
                 node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs --skip-branch-check --skip-uapi-tests
               fi
+              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
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -394,7 +397,7 @@ jobs:
           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 --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-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 src/__tests__/read-need-review-resynthesis.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 --dir packages/protocol exec node --test --test-force-exit test/conversation-rehearsal.test.js
@@ -457,6 +460,7 @@ jobs:
             tests/auxillariesExternalsPane.test.tsx \
             tests/profileStep.test.tsx \
             tests/api/readReviewRoute.test.ts \
+            tests/api/readReviewProtocolParity.test.ts \
             tests/api/pipelineHarnessRoute.test.ts \
             tests/terminalPipelineHarnessClient.test.ts \
             tests/terminalEnterpriseReadingUxState.test.ts \

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

@@ -120,6 +120,14 @@ artifact is `.bitcode/v39-enterprise-reading-ux-state.json`, checked by
 Gate 4 makes `ReadNeedComprehensionSynthesis` a real review loop.
 It must persist Read Requests, synthesized Needs, feedback, resynthesis attempts, Need measurements, accepted-Need admission, rejected-Need posture, and telemetry receipts.
 Finding Fits remains blocked until a reviewed Need is accepted.
+The implementation basis is `ReadNeedReviewResynthesisRuntime`, exported from
+`packages/pipelines/asset-pack/src/read-need-review-resynthesis.ts`. It projects
+source-safe storage records for `read_request`, `synthesized_need`, `feedback`,
+`resynthesis_attempt`, `need_measurement`, `accepted_need_admission`,
+`rejected_need_posture`, and `telemetry_receipt`. The generated source-safe
+proof artifact is `.bitcode/v39-read-need-review-resynthesis.json`, checked by
+`pnpm run check:v39-gate4`. Rejected or unaccepted Needs must emit Finding Fits
+blockers; only `acceptReadNeed` may produce Finding Fits admission.
 
 ### Gate 5: ReadFitsFinding Runtime, Ranking, And Replay
 

BITCODE_SPEC_V39.md

@@ -128,7 +128,12 @@ Closure acceptance:
 
 Closure implementation:
 
-- Pending Gate 4 work must define package-backed source, deterministic artifact, pipeline tests, route tests, and accepted-Need admission tests.
+- Gate 4 defines package-backed `ReadNeedReviewResynthesisRuntime` source,
+  deterministic `.bitcode/v39-read-need-review-resynthesis.json`, pipeline
+  runtime tests, route tests for `synthesize_read_need`,
+  `resynthesize_read_need`, `accept_read_need`, and `reject_read_need`, and
+  accepted-Need admission tests. Route payloads include `readNeedReviewRuntime`,
+  `storageProjection`, `runtimeSummary`, and Finding Fits admission readback.
 
 ### Gate 5: ReadFitsFinding Runtime, Ranking, And Replay
 

BITCODE_SPEC_V39_DELTA.md

@@ -201,6 +201,12 @@ state tests, component tests, and the maintained opt-in browser proof workflow.
 ## Gate 4 implementation notes
 
 Gate 4 closes `ReadNeedComprehensionSynthesis` as a review, feedback, and resynthesis loop. Finding Fits remains blocked until a reviewed Need is accepted.
+The implementation centers on `ReadNeedReviewResynthesisRuntime`: it persists
+Read Requests, synthesized Needs, feedback history, resynthesis attempts, Need
+measurements, accepted-Need admission, rejected-Need posture, and source-safe
+telemetry receipts as PipelineExecution-compatible storage projections. The
+rejected-Need posture is explicit so operator feedback can drive resynthesis
+without accidentally admitting Finding Fits.
 
 ## Gate 5 implementation notes
 

BITCODE_SPEC_V39_NOTES.md

@@ -72,7 +72,7 @@ No `_legacy/` source is active source truth.
 | Settlement and delivery scope | Gate 1 | BTD receipts, source-to-shares compensation, ledger/database/storage synchronization, pull-request delivery | drafted | Gate plan keeps source-bearing AssetPack delivery blocked until settlement unlock. |
 | 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 | `ReadNeedComprehensionSynthesis`, Need storage, feedback, resynthesis, accepted-Need admission | pending | Finding Fits remains blocked until a reviewed Need is accepted. |
+| 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. |
 | 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. |
@@ -94,7 +94,7 @@ No `_legacy/` source is active source truth.
 | Package docs | README, protocol package README, demonstration README, and PR template state V38 active / V39 draft workflow | drafted |
 | 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, and accepted-Need admission | pending |
+| 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 |
 | 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 |
@@ -149,17 +149,32 @@ No `_legacy/` source is active source truth.
 | Proof artifact and checker exist | `.bitcode/v39-enterprise-reading-ux-state.json`, `packages/protocol/src/canonical/v39-enterprise-reading-ux-state.js`, `packages/protocol/test/v39-enterprise-reading-ux-state.test.js`, `scripts/check-v39-gate3-enterprise-reading-ux-state.mjs` | implemented |
 | Browser proof remains wired as opt-in gate-quality evidence | `.github/workflows/bitcode-gate-quality.yml`, `uapi/tests/terminalUxBrowserProof.test.tsx`, `uapi/tests/e2e/commercial-mvp.terminal-ux.spec.ts` | implemented |
 
+## Gate 4 Parity
+
+| Requirement | Source evidence | Current V39 judgment |
+| --- | --- | --- |
+| ReadNeed review runtime exists | `packages/pipelines/asset-pack/src/read-need-review-resynthesis.ts`, `packages/pipelines/asset-pack/src/__tests__/read-need-review-resynthesis.test.ts` | implemented |
+| Read Requests and synthesized Needs persist as source-safe storage projections | `ReadNeedReviewStorageRecord`, `read_request`, `synthesized_need`, `need_measurement` records | implemented |
+| Feedback and resynthesis lineage are preserved | `resynthesis_attempt` record, `previousNeedId`, `feedbackHistory`, route resynthesis tests | implemented |
+| Accepted Need is the only Finding Fits admission path | `acceptReadNeed`, `admitReadFitsFinding`, `accepted_need_admission`, route acceptance tests | implemented |
+| Rejected Needs block Finding Fits and retain feedback | `rejectReadNeed`, `rejected_need_posture`, route rejection tests | implemented |
+| Telemetry receipts count the ReadNeed pipeline stack | `ReadNeedReviewTelemetryReceipt`, 4 phases, 16 PTRR steps, 48 ThricifiedGeneration ids | implemented |
+| Read review route exposes all review actions | `uapi/app/api/read-review/route.ts`, `uapi/tests/api/readReviewRoute.test.ts` | implemented |
+| Proof artifact and checker exist | `.bitcode/v39-read-need-review-resynthesis.json`, `packages/protocol/src/canonical/v39-read-need-review-resynthesis.js`, `packages/protocol/test/v39-read-need-review-resynthesis.test.js`, `scripts/check-v39-gate4-read-need-review-resynthesis.mjs` | implemented |
+| Workflow wiring includes Gate 4 source-safe proof | `.github/workflows/bitcode-gate-quality.yml`, `.github/workflows/bitcode-canon-quality.yml` | implemented |
+
 ## Later Gate Parity
 
-Later V39 gates must add gate-specific parity sections when their implementation begins. Gates 1 through 3 intentionally do not claim closure for Need review, 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 4 intentionally do not claim closure for Finding Fits runtime, 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.
 Later gate scope is intentionally pending and must be reopened into gate-specific parity sections before implementation starts.
 
 ## completion condition
 
-V39 Gate 3 is complete when `check:v39-gate3`, focused Terminal/Conversation/UAPI tests, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-3-*` branch.
+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.

BITCODE_SPEC_V39_PARITY_MATRIX.md

@@ -266,6 +266,15 @@ only source-safe `readingStage` intent, Terminal parses it as posture, and the
 rich execution stream remains the live Reading pipeline log. Use
 `pnpm run generate:v39-enterprise-reading-ux-state` and
 `pnpm run check:v39-gate3` before closing the gate.
+V39 Gate 4 adds the package-owned `ReadNeedReviewResynthesisRuntime` and
+source-safe generated artifact `.bitcode/v39-read-need-review-resynthesis.json`.
+ReadNeedComprehensionSynthesis now projects Read Requests, synthesized Needs,
+feedback history, resynthesis attempts, Need measurements, accepted-Need
+admission, rejected-Need posture, and source-safe telemetry receipts into
+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.
 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,

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 3 Enterprise Reading UX State Machine.
-- Next queued gate after V39 Gate 3 closure: V39 Gate 4 ReadNeed Review, Resynthesis, And Admission Runtime.
+- 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.
 - 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`.
@@ -63,6 +63,7 @@
 - V39 Gate 1 opening anchor: Commercial Reading readiness opens over promoted V38 with V39 SPEC, DELTA, NOTES, and PARITY files, `check:v39-gate1`, V38 active / V39 draft posture, and an eleven-gate plan for Depository supply indexing, enterprise Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime and replay, AssetPack preview/quote disclosure, settlement/BTD rights/delivery, operational telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness.
 - 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`.
 - 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

@@ -221,6 +221,9 @@
     "generate:v39-enterprise-reading-ux-state": "node scripts/generate-v39-enterprise-reading-ux-state.mjs",
     "check:v39-enterprise-reading-ux-state": "node scripts/generate-v39-enterprise-reading-ux-state.mjs --check",
     "check:v39-gate3": "node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs",
+    "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: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",