wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -318,9 +318,9 @@ Acceptance criteria:
 - access policy id/hash is shown before mint or licensed-read commitment.
 - ledgerized synthesis uses protocol-specified models and configuration; Terminal must not expose user-driven model selection for Fit, AssetPack, measurement, measuremint, proof, journal, or settlement behavior.
 
-#### Single-deposit commercial Reading QA
+#### Single-deposit Reading QA
 
-The first commercially meaningful V28 Read/Fit QA scenario runs against the
+The first value-producing V28 Read/Fit QA scenario runs against the
 smallest real Bitcode data-space: one deposited repository revision.
 The current staging fixture happens to use `engineeredsoftware/ENGI`, but
 Terminal implementation must remain repository-, owner-, branch-, and
@@ -351,6 +351,12 @@ Acceptance criteria:
   root, selected candidate ids, rejected/blocker reasons, proof/measurement
   posture, embedding policy, and result state under the execution evidence
   tree;
+- Fit evidence must include a compact selection trace for operator review:
+  selected, blocked, and ranked candidates; source binding; use tier; score
+  channels; selected unit hashes; proof/measurement evidence; provider recall;
+  blockers; warnings; and rejection reasons. The full depository search result
+  can retain candidate payloads, but the Fit result must expose this bounded
+  trace directly for Terminal, SQL, and harness summaries.
 - vector recall for deposited AssetPack evidence uses OpenAI
   `text-embedding-3-small` by default with `encoding_format='float'` and
   `dimensions=1536`, matching Supabase `deliverable_vectors.embedding
@@ -362,7 +368,7 @@ Acceptance criteria:
   dedupe/materialization roots where available, and finality/readiness status;
 - AssetPack synthesis must be protocol-specified and reproducibly evidenced;
   deterministic bring-up branches are regression scaffolds, while
-  staging-testnet commercial QA must run model-backed PTRR inference. If source
+  staging-testnet QA must run model-backed PTRR inference. If source
   materialization, settlement, BTC fee broadcast, ledger anchor, or BTD range
   issuance is not live, the result must state that blocker rather than imply
   delivery or minting;
@@ -372,6 +378,10 @@ Acceptance criteria:
 - SQL readback must show Deposit before Read, Read before Fit, no
   `frontier/*` or mock repository leakage, and no ledger/database drift for any
   finality that Terminal claims.
+- Ledger settlement evidence must carry neutral protocol fields:
+  `settlementAdmissible`, `ownershipBoundary`, `btcFee`, and `readback`.
+  Depositor ownership, reader fee/license posture, and server-custody state
+  must be explicit even when settlement is blocked.
 
 #### Pipeline host runtime environment for Read/Fit QA
 
@@ -425,11 +435,11 @@ The harness has two admissible modes:
   installs workspace dependencies, builds the manifest Deposit into searchable
   depository supply, invokes the AssetPack pipeline entrypoint, exports
   evidence and telemetry artifacts, and relies on SQL readback before any
-  commercial result is accepted.
+  result is accepted.
 
 If a local source overlay is used to debug the harness before deployment, the
-run must report `sourceOverlay.commercialAdmissibility` as
-`qa-only-not-source-revision-evidence` and fail closed for commercial
+run must report `sourceOverlay.admissibility` as
+`qa-only-not-source-revision-evidence` and fail closed for
 settlement review even when the pipeline output itself contains a worthy
 classification. The same implementation must exist at the deposited source
 revision before that result can become source-bound evidence.
@@ -443,7 +453,7 @@ Read/Fit result review remains fail-closed:
 - `blocked_readiness` is mandatory when source materialization, model/tool
   credentials, telemetry persistence, BTC fee, ledger anchor, settlement,
   AssetPack range projection, or finality readback is unavailable.
-- staging-testnet commercial Read/Fit QA must run model-backed inference.
+- staging-testnet Read/Fit QA must run model-backed inference.
   `BITCODE_ASSET_PACK_REAL_INFERENCE=1` is the deployment-level switch for the
   AssetPack pipeline; it forces every PTRR-capable setup, discovery, synthesis,
   validation, and Finish agent off deterministic bring-up branches. A run with
@@ -613,10 +623,10 @@ V28 keeps these layer boundaries:
 - `/terminal` plus `uapi/app/terminal`: Terminal route surface.
 - `uapi/app/terminal`: Terminal implementation module retained as an internal component boundary while the prior generic workspace route remains absent.
 - `uapi/app/btd/[assetPackId]`: AssetPack range disclosure surface.
-- MCP API and ChatGPT App: V28 MVP commercial interface surfaces over registry-derived policy and proof truth.
+- MCP API and ChatGPT App: V28 MVP interface surfaces over registry-derived policy and proof truth.
 - `protocol-demonstration`: minimal deterministic protocol witness. It may
-  contain a local source-bound fit-finding loop for demonstration E2E proof, but
-  it must not import commercial packages or be imported by commercial runtime
+  contain a local source-bound fit-finding loop for E2E proof, but
+  it must not import workspace packages or be imported by product runtime
   code.
 
 ## canonical domain model

BITCODE_V28_QA.md

@@ -321,8 +321,8 @@ Implemented after Pass 2, pending next manual QA confirmation:
 | Terminal transaction search keeps the typed value stable while URL-backed filter state updates. | Focused Terminal activity-search E2E passes; full commercial MVP E2E passes. |
 | Retired generic workspace route/import/runtime compatibility artifacts are absent from commercial source scans. | Source scans show no active retired route, generic workspace subtree, or retired-shell runtime names outside explicit historical spec notes and framework error patterns. |
 | Protocol-demonstration client-entry, public mount globals, UAPI demonstration witness mocks, and demonstration state title use demonstration vocabulary rather than retired shell vocabulary. | Runtime/API scans show no retired shell names across active demonstration entrypoints. |
-| Standalone demonstration is not a commercial runtime dependency. | `@bitcode/protocol` is the commercial dependency, UAPI source/tests no longer import `@bitcode/protocol-demonstration`, Terminal witness routes read `packages/protocol/public`, `protocol-demonstration` is outside `pnpm-workspace.yaml`, and bidirectional boundary tests are added. |
-| Embedded demonstration witness no longer overwrites the commercial `/terminal` document title. | Dual-lane Playwright smoke found `/terminal` rendering with the browser title `Bitcode Demonstration`; the protocol witness bundle now skips `document.title` updates when mounted under the commercial witness host attribute, while standalone demonstration can keep its own title. |
+| Standalone demonstration is not a product runtime dependency. | `@bitcode/protocol` is the product dependency, UAPI source/tests no longer import `@bitcode/protocol-demonstration`, Terminal witness routes read `packages/protocol/public`, `protocol-demonstration` is outside `pnpm-workspace.yaml`, and bidirectional boundary tests are added. |
+| Embedded demonstration witness no longer overwrites the `/terminal` document title. | Dual-lane Playwright smoke found `/terminal` rendering with the browser title `Bitcode Demonstration`; the protocol witness bundle now skips `document.title` updates when mounted under the product witness host attribute, while standalone demonstration can keep its own title. |
 
 ### 2026-05-08 Pass 3A Setup: Dual Environment Lanes
 
@@ -890,10 +890,10 @@ V28 blockers:
 - GitHub access tokens or wallet signatures appear unredacted in browser-visible UI, query output intended for routine QA, or client telemetry.
 - A broad model selector can alter ledgerized Terminal/Fit/AssetPack synthesis.
 
-### Pass 2B: Single-Deposit Commercial Read/Fit QA
+### Pass 2B: Single-Deposit Read/Fit QA
 
 Purpose:
-Validate Bitcode's most commercially critical flow against the smallest real
+Validate Bitcode's most value-critical flow against the smallest real
 data-space now available in staging: a single deposited repository revision.
 This pass asks whether Reading can find a worthy Fit, synthesize the right
 AssetPack posture, and fail closed when evidence is not strong enough.
@@ -904,7 +904,7 @@ source type.
 
 First-run execution boundary:
 
-- A recorded Fit posture is not yet a commercial worthy Fit unless the deployed
+- A recorded Fit posture is not yet a worthy Fit unless the deployed
   pipeline has actually executed and written its evidence.
 - The AssetPack pipeline must now emit depository search evidence in execution
   storage: `depository/search.result`, `depository/search.candidateRanking`,
@@ -937,7 +937,7 @@ First-run execution boundary:
   `blocked_readiness`: Deposit, Read admission, source binding, and Fit posture
   are reviewable, but AssetPack range, ledger anchor, BTC fee, settlement, and
   finality readback must not be claimed.
-- `worthy_fit` and `no_worthy_fit` become commercially admissible only when the
+- `worthy_fit` and `no_worthy_fit` become admissible only when the
   result is derived from pipeline execution evidence rather than local posture
   rows alone.
 
@@ -953,7 +953,7 @@ Starting condition:
 - Query `v28_qa_terminal_03_btd_ledger_after_terminal` still shows no claimed
   mint/anchor/finality without matching projection rows.
 
-Commercial Read scenario:
+Read scenario:
 
 Use this as the first manual Read frame, whether entered directly or selected
 from the closest Terminal scenario:
@@ -1029,11 +1029,15 @@ Manual steps:
     `selectedCandidateAssetIds` are present in the pipeline output or execution
     storage summary. Also verify `embeddingPolicy.model`,
     `embeddingPolicy.dimensions`, and `embeddingPolicy.vectorStore.rpc`.
+    Inspect `fitResult.selectionTrace` for selected and blocked candidates,
+    source binding, use tier, score channels, selected unit hashes,
+    proof/measurement evidence, provider recall, blockers, warnings, and
+    rejection reasons.
 11. Run saved query `v28_qa_terminal_07_pipeline_harness_after_fit`. It must
     show at least one recent pipeline run or deliverable pipeline run, event
     telemetry, phase trace rows, agent-step rows, and generation/tool rows
     before a `worthy_fit` or `no_worthy_fit` classification can graduate from
-    posture into commercial result review.
+    posture into result review.
 12. Rerun `v28_qa_terminal_02_activity_after_write` and
     `v28_qa_terminal_03_btd_ledger_after_terminal`.
 13. Paste screenshots, Network payload summaries, Vercel logs for the same
@@ -1053,6 +1057,9 @@ Pass criteria:
 - No `frontier/*` repository or mock repository appears in staging-testnet
   activity.
 - Fit evidence is source-bound and quality-explained, not just a summary.
+- Fit evidence includes a compact selection trace with candidate source
+  binding, use tier, score channels, selected unit hashes, proof/measurement
+  evidence, provider recall, blockers, warnings, and rejection reasons.
 - Real `worthy_fit` or `no_worthy_fit` classification is backed by deployed
   pipeline execution rows, events, logs, depository search evidence, candidate
   ranking roots, embedding policy, and result evidence.
@@ -1066,7 +1073,7 @@ Pass criteria:
   when query 03 shows matching projection rows; otherwise the Terminal result
   labels the exact blocked-readiness state.
 
-Commercial blockers:
+Blockers:
 
 - Read/Fit runs against a repository other than the deposited repository revision.
 - Read/Fit produces a "fit" without source evidence, proof posture, rejection
@@ -1087,10 +1094,10 @@ Commercial blockers:
 
 Purpose:
 Prove that the Read/Fit path can run inside the first lightweight deployment
-host before QA treats a Fit result as commercially meaningful. This pass checks
+host before QA treats a Fit result as meaningful. This pass checks
 the harness itself: sandbox creation, command execution, manifest binding,
 artifact export, telemetry, database persistence, and cleanup.
-It also checks the first commercial finding layer: manifest Deposit supply is
+It also checks the first finding layer: manifest Deposit supply is
 converted into depository search input, candidates are ranked, and the pipeline
 stores query/ranking roots before any result state is reviewed.
 
@@ -1147,9 +1154,9 @@ Before promotion, operators may add `BITCODE_SANDBOX_APPLY_LOCAL_PATCH=1` to
 overlay the current worktree on the cloned source revision. This is only for
 debugging the harness and pipeline implementation before deployment. Overlay
 evidence must remain QA-only, must report
-`sourceOverlay.commercialAdmissibility='qa-only-not-source-revision-evidence'`,
+`sourceOverlay.admissibility='qa-only-not-source-revision-evidence'`,
 and must not be used for source-revision settlement, ledger finality, or a
-commercial `worthy_fit` claim.
+`worthy_fit` claim.
 If the heavyweight pipeline exceeds the staging function window, set
 `BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` below that window. The deployed
 streaming route declares an 800 second ceiling, so staging should start with
@@ -1250,15 +1257,19 @@ Pass criteria:
   blocked-readiness.
 - Generation/tool rows appear before any model/tool-mediated Fit quality claim
   can be accepted.
-- For the staging-testnet commercial pass, generation rows must be non-zero
+- For the staging-testnet pass, generation rows must be non-zero
   because `BITCODE_ASSET_PACK_REAL_INFERENCE=1` is required. A completed run
   with zero generation rows is only deterministic bring-up evidence.
 - Parsed/cast generation output is stored when a ThriceifiedGeneration parser
   runs, so operators can compare raw model text with typed Fit/search evidence.
 - Query 03 still shows no AssetPack range, BTC fee, ledger anchor, settlement,
   or finality claim without matching projection rows.
+- If `ledgerSettlement` is present in evidence, it uses
+  `settlementAdmissible`, `ownershipBoundary`, `btcFee`, and `readback`.
+  Depositor ownership, reader fee/license posture, and server custody are
+  explicit even when settlement is blocked.
 
-Commercial blockers:
+Blockers:
 
 - The harness cannot create a sandbox or authenticate with Vercel.
 - The harness runs but cannot export evidence artifacts before sandbox stop.

packages/pipeline-hosts/README.md

@@ -30,7 +30,7 @@ manifest and runner, executes Node, writes `evidence.json` and
 dependencies, builds a manifest depository asset from the pinned Deposit and
 source revision, and runs the AssetPack pipeline runner in the sandbox. It still
 requires SQL readback before any `worthy_fit`, settlement, range, BTC fee, or
-ledger finality claim is commercially admissible. If the operator has already
+ledger finality claim is admissible. If the operator has already
 verified proof and measurement posture for the manifest Deposit, set
 `BITCODE_SANDBOX_DEPOSIT_HAS_PROOF=1` and
 `BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT=1`; otherwise the pipeline should
@@ -69,15 +69,15 @@ trusted command environment. For local Vercel Sandbox creation, either pull
 token tuple `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. Deployed
 Vercel code should use automatic OIDC rather than storing a Vercel token when
 possible.
-Staging-testnet commercial Read/Fit QA must also set
+Staging-testnet Read/Fit QA must also set
 `BITCODE_ASSET_PACK_REAL_INFERENCE=1`. That single flag forces every
 PTRR-capable AssetPack setup, discovery, synthesis, validation, and finish
 agent off the deterministic bring-up path. 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.
 `BITCODE_LLM_PROVIDER` and `BITCODE_LLM_MODEL` may pin the generation model.
-When they are absent, the commercial runtime chooses OpenAI if `OPENAI_API_KEY`
+When they are absent, the runtime chooses OpenAI if `OPENAI_API_KEY`
 is the only model credential present. A provider pin is forwarded only when the
 matching provider credential is also forwarded; stale pins without credentials
 are stripped so staging does not silently require an unavailable model service.
@@ -132,7 +132,7 @@ When validating local harness changes before the pinned source revision has been
 promoted, add `BITCODE_SANDBOX_APPLY_LOCAL_PATCH=1`. The runner uploads
 `git diff --binary $BITCODE_SANDBOX_SOURCE_REVISION` as a source overlay and
 applies it before dependency installation. Overlay runs are QA-only: evidence records
-`sourceOverlay.commercialAdmissibility=qa-only-not-source-revision-evidence`,
+`sourceOverlay.admissibility=qa-only-not-source-revision-evidence`,
 and the harness must not be used as settlement or source-revision finality
 evidence until the same changes exist at the deposited revision.
 
@@ -166,7 +166,7 @@ psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 \
   -f supabase/queries/v28_qa_terminal_07_pipeline_harness_after_fit.sql
 ```
 
-The harness is not commercially reviewable until this query reports pipeline
+The harness is not reviewable until this query reports pipeline
 run/event/phase/agent/generation/tool visibility rather than a blocker state.
 
 Only pass secrets through `BITCODE_SANDBOX_ENV_KEYS` when the sandbox code path

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

@@ -102,7 +102,7 @@ describe('asset-pack sandbox harness plan', () => {
     expect(plan.sourceOverlay).toEqual({
       path: '.bitcode/pipeline-harness/source-overlay.patch',
       patchRoot: '/vercel/sandbox',
-      commercialAdmissibility: 'qa-only-not-source-revision-evidence',
+      admissibility: 'qa-only-not-source-revision-evidence',
     });
     expect(plan.files.map((file) => file.path)).toContain(
       '.bitcode/pipeline-harness/source-overlay.patch'
@@ -142,5 +142,8 @@ describe('asset-pack sandbox harness plan', () => {
     expect(source).toContain('artifact-streaming-enabled');
     expect(source).toContain('execution: execution ? summarizeExecution(execution) : null');
     expect(source).toContain('PipelineHarnessTimeoutError');
+    expect(source).toContain('settlementOwnershipBoundary');
+    expect(source).toContain('depositor owns minted BTD range');
+    expect(source).toContain('reader pays BTC fee');
   });
 });