wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -318,6 +318,47 @@ 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
+
+The first commercially meaningful 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
+commit-generic.
+
+The required Read is not "does anything exist?".
+It is:
+
+> Read the deposited repository revision and determine whether it contains
+> a worthy, proof-bearing path for Bitcode Terminal's wallet/GitHub readiness,
+> Deposit, Read/Fit, AssetPack evidence, settlement/finality readback, and
+> Supabase/ledger reconciliation flow. If the evidence is worthy, synthesize
+> the minimal AssetPack; if not, return explicit no-worthy-fit or blocked
+> readiness evidence.
+
+Acceptance criteria:
+
+- the Read cannot run until a Deposit row exists for the selected repository
+  with repository, branch, commit, signer, and wallet authorization posture;
+- the Read and Fit rows must carry the same repository, branch, and commit as
+  the deposited source revision;
+- candidate recall must prefer source and proof surfaces that explain the
+  product-critical path, including Terminal Deposit/Read components, execution
+  history persistence, repository source selection, wallet/GitHub readiness,
+  QA SQL, and BTD/ledger proof readback;
+- the Fit result must expose ranking quality, rejection reasons, proof roots,
+  dedupe/materialization roots where available, and finality/readiness status;
+- AssetPack synthesis must be protocol-specified and deterministic; 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;
+- negative controls must return no-worthy-fit or clarification, not a decorative
+  AssetPack, when the Read is unrelated to ENGI's deposited source or too broad
+  to measure;
+- 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.
+
 ### Gate 4: Terminal AssetPack Range Detail
 
 Purpose:

BITCODE_SPEC_V28_NOTES.md

@@ -82,6 +82,40 @@ Terminal Deposit/Read QA now starts from a real deployed staging-testnet prerequ
 
 The first Terminal prerequisite pass also exposed a profile round-trip drift: later Profile writes could preserve wallet address/provider/status while dropping `network`, `authAddress`, `paymentAddress`, `proofKind`, and `addressType` from `settings.bitcodeProfile.walletBinding`. V28 treats `user_connections` as the active provider connection record, but the profile projection must retain the same non-secret wallet metadata for UI/readiness parity. The profile contract and profile write path now preserve those fields, and `v28_qa_01b_backfill_profile_wallet_projection_from_connection` repairs existing staging rows from the active wallet connection before Terminal write QA continues.
 
+## May 15 Single-Deposit Reading/Fit QA Focus
+
+The first successful staging Deposit placed a live repository revision into the
+Bitcode data-space. That makes the next QA step commercially sharper: Reading
+must prove whether Bitcode can discover, rank, synthesize, and explain a worthy
+Fit from the only available deposited source, not from protocol-demo fixtures or
+broad mock state.
+
+The active QA fixture currently uses ENGI because that is the deposited source
+available in staging. That fixture must not become a commercial Terminal
+special case. Product logic must remain generic across user, provider,
+repository, branch, commit, and deposited source.
+
+The active QA scenario is therefore single-deposit:
+
+- data-space: the latest deposited repository revision row, currently exercised
+  with the `engineeredsoftware/ENGI` fixture, with repository, branch, commit,
+  signer, wallet authorization, and asset candidate evidence;
+- Read: determine whether the deposited repository contains a complete
+  Terminal-backed path from wallet/GitHub readiness through Deposit, Read/Fit,
+  AssetPack evidence, proof/finality readback, and Supabase/ledger
+  reconciliation;
+- expected positive outcome: a minimal, proof-bearing AssetPack fit that cites
+  exact deposited source revision evidence and names any settlement/finality
+  blockers honestly;
+- expected negative outcome: no-worthy-fit or clarification when the Read is
+  unrelated to ENGI's deposited source or too broad to measure.
+
+Saved query `v28_qa_terminal_06_read_fit_quality_after_read` is the QA readback
+for this focus. It is intentionally stricter than the generic activity query:
+it checks Deposit before Read, Read before Fit, repository/branch/commit
+alignment, frontier/mock leakage, and visibility of proof or measurement
+posture in the execution rows.
+
 ## May 15 Terminal Terminology Closure
 
 V28 now retires user-facing Deposit/Depositing and Read/Reading language in favor of Deposit/Depositing and Read/Reading.

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -116,6 +116,7 @@ It links manual screenshots, console logs, server logs, Supabase SQL checks, and
 | Terminal terminology parity | `BITCODE_SPEC_V28.md` terminology contract, `uapi/app/terminal/terminal-workspace-copy.ts`, `uapi/app/terminal/TerminalDepositComposer.tsx`, `uapi/app/terminal/TerminalReadScenarioPanel.tsx`, `uapi/components/base/bitcode/layout/bitcode-public-copy.ts`, Terminal/public-shell/docs tests, `supabase/migrations/20260515143000_v28_deposit_read_data_contract.sql` | closed for UI, docs, tests, API, ORM, demonstration, and data-contract carriers | Active V28 UI, docs, QA prose, OpenAPI, test-visible assertions, BTD journal kinds, ORM types, Supabase queries, and live schema use Deposit/Depositing and Read/Reading. The migration applied to staging renames range linkage to `read_id` and journal writes to `read_submission`; source audit has no exact retired Terminal-domain vocabulary outside excluded legacy/build artifacts. |
 | PSQL/Supabase data reality | `supabase/migrations/001_v26_production.sql`, `002_v27_btd_crypto_registry.sql`, `003_user_connections_provider_scope.sql`, `20260514173000_enable_pipeline_runs_rls.sql`, `20260514175000_enable_pipeline_runtime_rls.sql`, `20260515143000_v28_deposit_read_data_contract.sql`, `packages/orm/src/data-health/*`, `packages/orm/scripts/run-data-health.ts`, `packages/orm/scripts/check-schema-types.ts`, `supabase/DATA_HEALTH.md`, `supabase/queries/*` | data-contract naming closed; Terminal Deposit/Read write evidence pending | Staging database has all required auth/profile/connection/repository/BTD registry/journal/telemetry tables, RLS posture does not hide required user-scoped reads, generated schema types cover canonical public tables, automated data-health checks pass, and QA SQL queries match Terminal/Wallet/Externals UI state. Current baseline: migration `20260515143000` is applied locally and remotely, `btd_asset_pack_ranges` exposes `read_id`, journal kind constraints accept `read_submission`, `pnpm db:data-health:daily` passes against staging, wallet/GitHub SQL evidence is green, and the Terminal-specific saved queries gate Deposit/Read/Fit write-read parity. |
 | Fit-finding | `uapi/app/terminal/TerminalDepositReadWorkbench.tsx`, `TerminalReadScenarioPanel.tsx`, `terminal-deposit-read-workbench.ts`, `terminal-read-scenarios.ts`, `packages/protocol/src/canonical/*`, `protocol-demonstration/src/*` reference witness | partial | Terminal simplest Read produces or reads Fit candidates, review decision, qualities, rejection/block reasons, source roots, proof/dedupe roots, and visible readiness state without relying on demonstration runtime imports. |
+| Single-deposit commercial Read/Fit QA | `BITCODE_SPEC_V28.md` single-deposit commercial Reading QA, `BITCODE_V28_QA.md` Pass 2B, `supabase/queries/v28_qa_terminal_06_read_fit_quality_after_read.sql`, `uapi/tests/terminalActivityHistory.test.ts` | opened as the next critical V28 QA gate | Against the current single deposited repository revision, Terminal must prove Deposit before Read, Read before Fit, repository/branch/commit alignment, no `frontier/*` or mock leakage, worthy-fit AssetPack synthesis or explicit no-worthy-fit/blocker result, and honest settlement/finality readback. The current fixture is ENGI, but implementation must remain source-generic. |
 | AssetPack synthesis and deterministic pipeline configuration | `internal-docs/ASSETPACK_EXECUTION.md`, `packages/protocol/src/canonical/run-artifacts.js`, `packages/btd/src/semantic-volume.ts`, `measuremint.ts`, `range.ts`, `receipts.ts`, `replay.ts`, `uapi/app/api/btd/mint-draft/route.ts`, Terminal AssetPack components | partial with blocker | Staging Read/Fit path creates or reads AssetPack evidence, semantic volume, measuremint/range or zero-cell receipt, and access-policy hash using protocol-specified model/pipeline configuration. Any broad user model-selection UI that can affect ledgerized synthesis must be removed or scoped to non-ledgerized conversation UX. |
 | Ledgerized journal and ledger anchors | `packages/btd/src/terminal-journal.ts`, `ledger-anchor.ts`, `reconciliation.ts`, `uapi/app/api/btd/terminal-journal/route.ts`, `asset-pack-ledger-anchor/route.ts`, `ledger-database-reconciliation/route.ts`, `supabase/migrations/002_v27_btd_crypto_registry.sql` | partial | Terminal shows journal rows for Read/Fit/AssetPack/BTC fee/anchor/reconciliation events, ledger anchor or blocked-readiness state is explicit, and SQL evidence in `btd_terminal_journal_entries`, `btd_asset_pack_ledger_anchors`, and reconciliation repair tables matches the UI. |
 | BTC fee and testnet ledger path | `packages/btd/src/bitcoin-fees.ts`, `bitcoin-provider.ts`, `uapi/app/api/btd/btc-fee-transaction/route.ts`, wallet client code | partial | Testnet path prepares fee state, uses wallet-controlled signing/PSBT or named blocked-readiness receipt, records no server custody, and writes/readbacks `btc_fee_transactions` where a fee receipt is produced. |

BITCODE_V28_QA.md

@@ -817,7 +817,7 @@ Deposit path:
 1. Hard refresh `/terminal` and wait for top chrome wallet state and Terminal sync to settle.
 2. In the top Terminal activity area, confirm there is no visible red or amber `Failed to fetch execution history` error. Empty activity is acceptable; a 500/error banner is not.
 3. In `Repository supply`, confirm `Connection posture` says GitHub is connected, `Mode` is `live connection`, and `Inventory source` is `stored protocol inventory` or `live provider inventory`.
-4. In the repository selector, choose `engineeredsoftware/ENGI` for the first pass unless intentionally testing another `engineeredsoftware/*` repository.
+4. In the repository selector, choose the repository intended for this Deposit. The current walkthrough fixture uses `engineeredsoftware/ENGI`, but the Terminal flow must not special-case that repository.
 5. In `Deposit-side supply`, confirm the auth/session label and inventory cards use `engineeredsoftware/*`. If any `frontier/*`, `gh_inst_bitcode_001`, or other protocol-demo repository appears in the live staging lane, stop and classify as a V28 blocker.
 6. In `Deposit-side supply`, use the search box only to filter connected repositories. Search must not replace live inventory with protocol demo artifacts. Select/confirm one repository card; the selected card should match the `Repository supply` selector.
 7. Click `Record deposit selection`. Confirm the UI reports that selected deposit-side supply was recorded.
@@ -884,6 +884,124 @@ 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
+
+Purpose:
+Validate Bitcode's most commercially 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.
+The current walkthrough fixture is `engineeredsoftware/ENGI` because that is the
+repository already deposited, but Terminal code and operator flow must remain
+fully generic across repository owner, repository, branch, commit, signer, and
+source type.
+
+Starting condition:
+
+- Pass 2A Deposit submission has succeeded.
+- Query `v28_qa_terminal_02_activity_after_write` shows a completed
+  `agentic-execution:asset-pack` from `terminal-deposit-composer`.
+- Query `v28_qa_terminal_04_deposit_repository_alignment` shows the recent
+  deposit activity is for the selected deposited repository, with `source_branch` and
+  `source_commit` present, `wallet_authorization_signed='true'`, and
+  `frontier_reference_detected=false`.
+- Query `v28_qa_terminal_03_btd_ledger_after_terminal` still shows no claimed
+  mint/anchor/finality without matching projection rows.
+
+Commercial Read scenario:
+
+Use this as the first manual Read frame, whether entered directly or selected
+from the closest Terminal scenario:
+
+```text
+Read the deposited repository revision and determine whether it contains a
+complete, non-mock Terminal path from Bitcoin wallet identity and GitHub source
+scope through Deposit, Read/Fit, AssetPack evidence, proof/finality readback,
+and Supabase/ledger reconciliation. If there is a worthy fit, synthesize the
+minimal proof-bearing AssetPack. If there is not, return explicit no-worthy-fit
+or blocked-readiness evidence.
+```
+
+Positive-control expectation:
+
+- Candidate recall should point at deposited source surfaces that actually
+  explain the path, not generic product copy. Expected evidence families include
+  Terminal Deposit/Read components, repository/branch/commit source selection,
+  execution-history persistence, wallet/GitHub readiness, saved QA SQL, BTD
+  ledger readback, and proof/finality/admission primitives.
+- The Fit result must name why the selected ENGI evidence is decisive or why it
+  is insufficient. A decorative Fit summary with no source/proof linkage is a
+  failure.
+- The result must produce one of two honest outcomes:
+  - `worthy_fit`: a minimal AssetPack candidate with source revision, evidence
+    roots, proof/dedupe/materialization posture, and settlement/finality state;
+  - `no_worthy_fit` or `blocked_readiness`: explicit reasons such as source
+    materialization unavailable, no live branch materialization, missing ledger
+    anchor, no accepted Read review, or no settlement proof.
+
+Negative controls:
+
+1. Run or simulate a Read unrelated to the deposited ENGI source, such as
+   "Find a Solana wallet settlement AssetPack." Expected: no-worthy-fit or
+   clarification, not an ENGI AssetPack.
+2. Run or simulate an overly broad Read, such as "Make Bitcode better."
+   Expected: clarification or blocked measurement, not a confident Fit.
+3. Run or simulate a Read that would require unavailable source material outside
+   the deposited ENGI revision. Expected: no-worthy-fit or source-scope blocker.
+
+Manual steps:
+
+1. Hard refresh `/terminal`.
+2. Confirm the Activity area shows the successful ENGI Deposit row and no
+   execution-history error.
+3. Confirm the repository selector still shows the deposited repository, the
+   selected branch, and the selected commit from the successful Deposit.
+4. In the Read area, select or express the commercial Read scenario above.
+5. Record the Read posture. Capture the `/api/executions/history` request and
+   response; expected status is `201`.
+6. Accept the Read for fit search. Capture `/api/read-review`; expected response
+   has `fitSearchAdmission.admitted=true`. If it remains blocked, the blocker
+   must name the Read-review requirement or measurement deficiency.
+7. Record Fit posture. Capture the `/api/executions/history` request and
+   response; expected status is `201`.
+8. If a branch, AssetPack, BTC fee, ledger anchor, or settlement control becomes
+   enabled, inspect the preview first. Only click it if the preview names source
+   revision, proof/finality posture, wallet authorization, and expected database
+   readback.
+9. Run saved query `v28_qa_terminal_06_read_fit_quality_after_read`.
+10. Rerun `v28_qa_terminal_02_activity_after_write` and
+    `v28_qa_terminal_03_btd_ledger_after_terminal`.
+11. Paste screenshots, Network payload summaries, Vercel logs for the same
+    timestamps, and all three query outputs.
+
+Pass criteria:
+
+- `v28_qa_terminal_06_read_fit_quality_after_read` reports
+  `critical_read_gate_state='critical_read_fit_sequence_ready_for_result_review'`
+  for the positive-control run.
+- The observed repository matches the latest deposited repository.
+- Branch and commit are present on Deposit, Read, and Fit activity.
+- Deposit precedes Read, and Read precedes Fit.
+- No `frontier/*` repository or mock repository appears in staging-testnet
+  activity.
+- Fit evidence is source-bound and quality-explained, not just a summary.
+- Settlement, finality, BTC fee, BTD range, or ledger anchor claims appear only
+  when query 03 shows matching projection rows; otherwise the Terminal result
+  labels the exact blocked-readiness state.
+
+Commercial blockers:
+
+- Read/Fit runs against a repository other than the deposited repository revision.
+- Read/Fit produces a "fit" without source evidence, proof posture, rejection
+  reasons, or explicit blocker.
+- Negative controls produce a confident AssetPack instead of no-worthy-fit or
+  clarification.
+- Fit search proceeds before Read review/admission.
+- Terminal claims delivery, settlement, mint, anchor, or finality that SQL
+  readback cannot verify.
+- Any staging-testnet Read/Fit row contains `frontier/*`, mock provider, or
+  protocol-demo source as if it were live deposited ENGI source.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

supabase/queries/v28_qa_terminal_01_prerequisites_wallet_github_repo.sql

@@ -82,7 +82,6 @@ repo_inventory AS (
   SELECT
     r.user_id,
     count(*)::bigint AS github_repository_count,
-    count(*) FILTER (WHERE r.repo_full_name = 'engineeredsoftware/ENGI')::bigint AS engi_repository_rows,
     max(r.updated_at) AS repository_inventory_updated_at,
     coalesce(
       jsonb_agg(
@@ -134,14 +133,16 @@ SELECT
     ELSE 'github_installation_token_fresh'
   END AS github_token_freshness,
   coalesce(r.github_repository_count, 0) AS github_repository_count,
-  coalesce(r.engi_repository_rows, 0) AS engi_repository_rows,
+  CASE
+    WHEN coalesce(r.github_repository_count, 0) > 0 THEN 'github_repository_inventory_available'
+    ELSE 'github_repository_inventory_missing'
+  END AS github_repository_inventory_state,
   CASE
     WHEN p.user_id IS NULL THEN 'blocker:missing_user_profile'
     WHEN nullif(trim(coalesce(p.wallet_address, '')), '') IS NULL THEN 'blocker:missing_profile_wallet_binding'
     WHEN w.user_id IS NULL THEN 'blocker:missing_wallet_connection'
     WHEN g.user_id IS NULL THEN 'blocker:missing_github_connection'
     WHEN coalesce(r.github_repository_count, 0) = 0 THEN 'blocker:missing_vcs_repository_inventory'
-    WHEN coalesce(r.engi_repository_rows, 0) = 0 THEN 'warning:ENGI_repo_not_in_inventory'
     ELSE 'ready_for_terminal_deposit_read'
   END AS terminal_prerequisite_state,
   CASE

supabase/queries/v28_qa_terminal_04_deposit_repository_alignment.sql

@@ -31,7 +31,7 @@ BEGIN
             'private', r.repo_private,
             'updated_at', r.updated_at
           )
-          ORDER BY (r.repo_full_name = 'engineeredsoftware/ENGI') DESC, r.repo_full_name
+          ORDER BY r.repo_full_name
         ) FILTER (WHERE r.repo_full_name IS NOT NULL) AS repositories
       FROM public.vcs_repositories r
       JOIN latest_user u ON u.user_id = r.user_id