wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -410,8 +410,14 @@ The V28 pipeline harness must write a manifest before execution containing:
 
 - Read id and Read text;
 - Deposit id and optional deposited AssetPack id;
-- optional Deposit proof root, measurement root, and reconciliation readback
-  root when the deposited evidence already has them;
+- Deposit proof root, measurement root, and reconciliation readback root.
+  When a recorded Deposit activity already asserts wallet/attestation proof
+  and asset measurement posture but has not stored root fields, the harness
+  must materialize deterministic manifest-bound roots from the Deposit id,
+  AssetPack id, Read id, repository, branch, and commit. These roots are
+  admissible as harness evidence roots for candidate recall and Fit review;
+  they are not external finality claims and still require SQL/ledger readback
+  before settlement.
 - repository full name, branch, and commit;
 - host capability summary;
 - expected stages: deposit search, candidate ranking, Read comprehension,
@@ -462,17 +468,19 @@ Read/Fit result review remains fail-closed:
   validation, and Finish stay model-backed while deterministic source-bound
   depository discovery preserves enough route budget to synthesize, ship, and
   read back the AssetPack. `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full`
-  is reserved for long-running sandbox audits outside the deployed streaming
-  route. A run with omitted per-agent `*_USE_PTRR` flags is not an acceptable
-  staging posture unless the global real-inference flag and explicit profile
-  are present.
+  is reserved for the later long-running async completion gate described below;
+  the current deployed Terminal route must reject it until sandbox completion
+  pushes finished state to a server-side stream/socket handler. A run with
+  omitted per-agent `*_USE_PTRR` flags is not an acceptable staging posture
+  unless the global real-inference flag and explicit profile are present.
 - manifest-only Deposit supply can satisfy candidate recall but cannot produce
   `worthy_fit` unless proof and measurement posture are explicitly visible to
   the pipeline input and the downstream readback queries confirm them. Boolean
-  wallet/measurement posture is not enough when the Read asks for proof-root,
-  finality, or reconciliation readback; those roots must be supplied by the
-  deposited evidence, synthesized and read back during Finish, or returned as
-  explicit `blocked_readiness`.
+  wallet/measurement posture must be converted into deterministic
+  manifest-bound proof, measurement, and reconciliation roots before Fit
+  evaluation; if that conversion cannot be made, the run must return explicit
+  `blocked_readiness`. Manifest-bound roots support Read/Fit selection but do
+  not claim BTC fee broadcast, BTD minting, or external ledger finality.
 - every SDIVF phase, PTRR agent step, ThriceifiedGeneration, and tool execution
   must be inspectable as prompt/context input, raw model/tool output,
   parsed/typed output, usage/timing metadata, and phase/agent/step/failsafe
@@ -667,6 +675,78 @@ The V28 domain model is:
 The V28 operator chain is Readiness -> Read -> Fit -> Proof -> Measuremint -> Fee -> Anchor -> Range -> Read -> Journal -> Reconcile -> Protocol readback.
 Every link must make proof or readiness state visible.
 
+## staged Reading acceptance path
+
+V28 separates Reading into distinct reviewable stages so commercial buyers can
+decide whether Bitcode understood the need before Bitcode exposes or settles
+source-bearing AssetPack material.
+
+The staged Reading path is:
+
+1. **Need synthesis.** The user Read request is input to a Need pipeline. The
+   pipeline synthesizes a measured Need object with requirements, closure
+   criteria, failure modes, target artifact kinds, source constraints,
+   proof/settlement expectations, and pricing measurement inputs. Terminal
+   shows this Need in full detail. The user can accept it or request another
+   synthesis with feedback. No depository Fit search, BTC fee, BTD mint, or
+   AssetPack source disclosure is allowed before Need acceptance.
+2. **Need-Fit synthesis.** An accepted Read-Need is input to the AssetPack
+   synthesis pipeline. This stage searches the deposited asset-space, ranks
+   candidates, measures candidate fit against the Need measurement, synthesizes
+   the candidate AssetPack, and returns `worthy_fit`, `no_worthy_fit`, or
+   `blocked_readiness` with proof-bearing search/fit telemetry.
+3. **Preview and settlement.** A worthy synthesized AssetPack is previewed
+   without leaking the full source. Preview may show Need measurement, Fit
+   measurement, selected candidate ids, roots, score bands, proof posture,
+   settlement boundary, and price; it must not show protected source material
+   before payment/right settlement. Settlement then records the reader BTC fee,
+   mints or assigns the BTD range according to the standing supply law, writes
+   ownership and read-license rows, anchors/journals the event, and only then
+   unlocks the full AssetPack source/right surface to the buyer/reader.
+
+The commercial question therefore splits into two explicit operator questions:
+
+- Does Bitcode understand the Read's Need?
+- Did Bitcode find and synthesize a match good enough to preview confidently
+  and pay for in BTC without source-IP leakage?
+
+### Share-to-Fee measurement clarity
+
+V28 keeps the standing supply law intact while sharpening the initial
+deterministic pricing/readiness interface. The initial Share-to-Fee calculation
+must be deterministic from recorded measurements:
+
+- each Need measurement vector dimension has a volume and a measurement weight;
+- each candidate Fit measurement vector is evaluated against the accepted Need
+  measurement vector;
+- the priced measurement volume is the weighted admitted volume after fit,
+  quality, proof, and settlement eligibility gates;
+- BTC price is derived from that priced measurement volume by the configured
+  staging-testnet fee schedule and recorded as a reader fee quote;
+- the quote is previewable before payment, but source contents and licensed
+  read rights are not unlocked until settlement readback succeeds.
+
+This pricing path is a V28 commercial product acceptance target, but it must
+remain fail-closed: if the Need measurement, Fit measurement, fee schedule,
+wallet authorization, BTC fee, BTD range, or ledger readback is missing, the
+Terminal shows blocked readiness rather than implying settlement.
+
+### Long-running full-profile pipeline gate
+
+The current V28 route-streaming gate uses
+`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` because the Vercel Function
+route can stream live progress and collect artifacts only inside its request
+window. `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` is scoped to a
+subsequent V28 gate.
+
+That later gate may run for dozens of minutes in Vercel Sandbox. The sandbox
+execution itself must push finished result state, artifacts, and readback
+signals to a server-side stream/socket handler or durable queue; the route that
+starts the run must not be responsible for waiting synchronously for the final
+result. Full-profile acceptance requires the same evidence as bounded profile
+plus durable async completion delivery, resumable status readback, and Terminal
+reattachment to the live execution stream.
+
 ## canonical subsystem surfaces
 
 ### Depositing and asset supply

BITCODE_V28_QA.md

@@ -1199,6 +1199,11 @@ unset, when `OPENAI_API_KEY` is missing, or when
 `BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` exceeds `600000`.
 When no profile is configured, the deployed route injects
 `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded`.
+The current deployed route also preflight-fails if
+`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full`. Full profile is a later V28
+gate: the sandbox can run for dozens of minutes, but final state must be pushed
+from the sandbox execution to a server-side stream/socket handler or durable
+queue instead of waiting synchronously inside the route request.
 
 ```bash
 curl -N "$BITCODE_UAPI_URL/api/pipeline-harness/asset-pack" \
@@ -1301,6 +1306,16 @@ Blockers:
 - Terminal enables settlement, minting, branch materialization, BTC fee
   broadcast, or ledger finality from a host smoke result.
 
+Subsequent V28 Reading gates prepared by this pass:
+
+| Gate | Scope | Acceptance boundary |
+| --- | --- | --- |
+| Need synthesis review | Split "What is the need?" from Fit search. The Read request enters a Need pipeline, producing requirements, closure criteria, failure modes, target artifact kinds, proof expectations, and pricing measurement inputs. | User can accept the Need or request resynthesis with feedback. No Fit search, source preview, BTC fee, or BTD settlement is allowed before Need acceptance. |
+| Need-Fit search and synthesis | Input is the accepted Read-Need, not raw prompt text. The AssetPack synthesis pipeline searches deposited supply, ranks candidates, measures Fit against the Need, and synthesizes the candidate AssetPack. | Result is `worthy_fit`, `no_worthy_fit`, or `blocked_readiness` with query root, ranking root, selected ids, proof/measurement posture, and model/tool telemetry. |
+| Source-safe preview | Show enough proof to decide whether to pay without leaking source. | Preview may show Need/Fit measurements, score bands, roots, candidate ids, proof posture, ownership boundary, and BTC quote. It must not expose protected AssetPack source before settlement. |
+| Settle and unlock | Deterministic Share-to-Fee and BTD settlement. | Price is derived from weighted admitted measurement volume and the staging fee schedule. Reader pays BTC fee, BTD range/ownership/license/journal/anchor rows are written and read back, then full AssetPack source/right surface is unlocked. |
+| Full-profile async pipeline | Run the full PTRR profile for long-running audits. | Vercel Sandbox execution may run for dozens of minutes and must push completion artifacts to server-side stream/socket or durable queue; Terminal can reattach and read final state without the starter route waiting. |
+
 Observed staging-testnet harness evidence on 2026-05-17:
 
 - Vercel Sandbox run `sbx_ktb5Z6VnP5A16m9k4a0FkBcJg1d3` completed all six
@@ -1329,9 +1344,10 @@ Observed staging-testnet harness evidence on 2026-05-17:
   `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` is now the required
   profile: setup, synthesis, validation, and Finish produce model-generation
   telemetry while deterministic source-bound discovery preserves budget for a
-  complete AssetPack run. Full discovery PTRR remains available through
-  `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` for long-running sandbox
-  audits outside the deployed route.
+  complete AssetPack run. Full discovery PTRR is now scoped to the later
+  async-completion V28 gate; the current deployed route must reject `full`
+  until sandbox completion pushes finished state to a server-side stream/socket
+  handler or durable queue.
 - Ledger readback correctly showed zero BTD range, BTC fee, journal, anchor, and
   crypto telemetry rows, and `btd_supply_state.total_minted=0`, because source
   overlay QA evidence cannot mint BTD, claim BTC fee settlement, or anchor
@@ -1408,6 +1424,40 @@ Second local overlay evidence on 2026-05-17:
   search/readback tool registration or prompt tightening before full PTRR audits
   can be considered clean.
 
+Third local overlay evidence on 2026-05-17 after bounded real-inference and
+manifest-bound Deposit evidence root fixes:
+
+- Vercel Sandbox run `sbx_rLVfPTD3HuITtCbrR0AmZ26spEYO` exported artifacts to
+  `.bitcode/pipeline-harness-runs/2026-05-17T21-19-26-275Z-sbx_rLVfPTD3HuITtCbrR0AmZ26spEYO/`.
+- The run intentionally passed only the UI-shaped Deposit proof and measurement
+  flags, with no manual `BITCODE_SANDBOX_DEPOSIT_*_ROOT` overrides. The harness
+  materialized manifest-bound `proofRoot`, `measurementRoot`, and
+  `reconciliationReadbackRoot` values before pipeline execution.
+- Pipeline run `3b3339b4-5695-46fa-9ce4-2163c7eb1f11` reached candidate recall,
+  model-backed setup, model-backed Read comprehension, model-backed synthesis,
+  `pipeline-complete`, and `ledger-settlement-readback`.
+- The pipeline selected the proof-bearing candidate `manual-deposit-qa`,
+  searched 1 deposited candidate, returned `pipelineResultState='worthy_fit'`,
+  and synthesized `AssetPack:read-satisfaction-summary` with query root
+  `sha256:d989394a41b1956b45988066165fc4c8be3063028cad8dd1367c3038456d5212`,
+  ranking root
+  `sha256:00307ab87da48266ee346d5ccae1d06dd228c3441610277d73015cb5e9250d3a`,
+  and embedding policy `openai text-embedding-3-small`.
+- The exported telemetry contained 698 lines. Bounded real-inference statuses
+  were `success` for setup plan, Read comprehension, and synthesis, and
+  telemetry included `llm.input`, `llm.output`, `llm.usage`, and
+  `llm.parsedOutput` for the model-backed stages.
+- Final harness `resultState` remained `blocked_readiness` for the correct
+  reason: `BITCODE_SANDBOX_APPLY_LOCAL_PATCH=1` means the run cannot mint BTD,
+  claim reader BTC fee settlement, or anchor finality. The reason text now
+  distinguishes that settlement block from missing pipeline output:
+  "Pipeline produced worthy_fit evidence; final settlement remains blocked by
+  harness readiness constraints."
+- The remaining V28 closure gate is a clean no-overlay staging run at the
+  deposited source revision, with Supabase database streaming enabled, so the
+  same worthy fit can write and read back BTD range, BTC fee, ownership,
+  license, journal, ledger anchor, and crypto telemetry rows.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

packages/pipeline-hosts/README.md

@@ -82,8 +82,12 @@ Staging-testnet Read/Fit QA must also set
 `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` is the expected profile:
 setup, synthesis, validation, and finish stay model-backed, while deterministic
 source-bound discovery evidence preserves enough budget to ship and read back
-the AssetPack. Set `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` only for
-long-running sandbox audits outside the deployed route. The phase-specific
+the AssetPack. `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` is scoped to a
+later async completion gate: the sandbox may run for dozens of minutes, but it
+must push final result state and artifacts to a server-side stream/socket
+handler or durable queue rather than relying on the starter route to wait
+synchronously. The current deployed Terminal route rejects `full` preflight.
+The phase-specific
 `BITCODE_ASSET_PACK_*_USE_PTRR=1` flags remain available for local bisection,
 but they are not sufficient as a staging posture because a missed flag silently
 turns part of the run back into deterministic evidence.
@@ -94,6 +98,13 @@ matching provider credential is also forwarded; stale pins without credentials
 are stripped so staging does not silently require an unavailable model service.
 Database streaming requires a real Supabase URL and service-role key; placeholder
 `.env.local` values fail preflight before a sandbox is created.
+When the recorded Deposit activity has wallet/attestation proof and asset
+measurement posture but no explicit proof root fields, the harness materializes
+deterministic manifest-bound proof, measurement, and reconciliation roots from
+the Deposit id, AssetPack id, Read id, repository, branch, and commit. Those
+roots let the Read/Fit pipeline evaluate a proof-bearing deposited candidate,
+but they do not by themselves claim BTC fee broadcast, BTD minting, or external
+ledger finality.
 The deployed streaming route declares an 800 second Vercel Function window; keep
 `BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` at or below `600000` there so the
 route still has time to collect and stream the blocked-readiness artifact if the

packages/pipeline-hosts/src/__tests__/asset-pack-harness.test.ts

@@ -121,6 +121,28 @@ describe('asset-pack sandbox harness plan', () => {
     });
   });
 
+  it('materializes manifest-bound deposit evidence roots when activity flags are present', () => {
+    const plan = buildAssetPackSandboxHarness({
+      ...baseOptions,
+      deposit: {
+        id: 'deposit-1',
+        assetId: 'asset-repository-revision',
+        hasWalletOrAttestationProof: true,
+        hasAssetMeasurementEvidence: true,
+      },
+    });
+
+    expect(plan.manifest.deposit).toMatchObject({
+      id: 'deposit-1',
+      assetId: 'asset-repository-revision',
+      hasWalletOrAttestationProof: true,
+      hasAssetMeasurementEvidence: true,
+    });
+    expect(plan.manifest.deposit.proofRoot).toMatch(/^sha256:[a-f0-9]{64}$/);
+    expect(plan.manifest.deposit.measurementRoot).toMatch(/^sha256:[a-f0-9]{64}$/);
+    expect(plan.manifest.deposit.reconciliationReadbackRoot).toMatch(/^sha256:[a-f0-9]{64}$/);
+  });
+
   it('generates a syntactically valid live pipeline runner', () => {
     const plan = buildAssetPackSandboxHarness({
       ...baseOptions,
@@ -146,5 +168,7 @@ describe('asset-pack sandbox harness plan', () => {
     expect(source).toContain('depositor owns minted BTD range');
     expect(source).toContain('reader pays BTC fee');
     expect(source).toContain('verificationEvidence');
+    expect(source).toContain('Pipeline produced ');
+    expect(source).toContain('ledgerSettlement,');
   });
 });