wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28_NOTES.md

@@ -76,6 +76,10 @@ Live staging OAuth also exposed two callback hardening requirements. First, the
 
 The same clean-deploy pass removed Auxillaries as a standalone page destination. Supabase and GitHub callbacks, retained `/auxillaries/*` compatibility paths, and retained `/orbitals/*` paths must land on `/terminal?auxillary-open-to=<pane>` so Auxillaries opens as the global overlay and never renders the retired late-Engi workspace page or left-sidebar navigation. The left execution sidebar and disabled AssetPacks tab are not part of the V28 website application surface; retained sidebar components may remain for future repurposing but must not be mounted by the active layout.
 
+May 14 GitHub App onboarding then closed the second live prerequisite. The first staging callback failed because Vercel received an unsupported private-key representation; the GitHub JWT helper now accepts PEM with real newlines, escaped-newline PEM, base64-encoded PEM, or a single-line PEM with markers, and rejects local `.pem` file paths as deployment misconfiguration. The follow-up pass connected installation `132358627` for `engineeredsoftware`, persisted the provider-scoped `user_connections.provider='github'` row, and backfilled `public.vcs_repositories` from live GitHub inventory when the connection payload carried an empty repository array. For V28 Terminal QA, `public.vcs_repositories` is the authoritative GitHub source inventory projection; `connection_data.repositories=[]` is not a blocker once `vcs_repositories` contains the installed repositories.
+
+Terminal Give/Need QA now starts from a real deployed staging-testnet prerequisite state: Leather wallet-authenticated Supabase user, Bitcode wallet binding projection, GitHub App installation, and repository inventory containing `engineeredsoftware/ENGI`. The next acceptance step is write/read parity for Terminal Need, Give, Fit, and branch/settlement posture. Saved Supabase queries `v28_qa_terminal_01_prerequisites_wallet_github_repo`, `v28_qa_terminal_02_activity_after_write`, and `v28_qa_terminal_03_btd_ledger_after_terminal` are the current operator evidence set for this phase.
+
 ### Deterministic Model Boundary
 
 V28 must remove the idea that a user can choose ledgerized Bitcode synthesis models.

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -111,9 +111,9 @@ It links manual screenshots, console logs, server logs, Supabase SQL checks, and
 
 | Parity area | Source evidence | Current V28 judgment | Closure evidence required |
 | --- | --- | --- | --- |
-| BTC/D identity and wallet-backed session | `uapi/app/api/wallet/_shared.ts`, `uapi/app/api/wallet/authenticate/route.ts`, `uapi/app/api/wallet/oauth/authorization-code/route.ts`, `uapi/app/api/wallet/oauth/token/route.ts`, `uapi/app/api/wallet/oauth/userinfo/route.ts`, `uapi/lib/bitcoin-wallet-client.ts`, `uapi/lib/bitcode-wallet-local.ts`, `packages/btd/src/wallet.ts`, `packages/btd/src/bitcoin-provider.ts`, `supabase/migrations/003_user_connections_provider_scope.sql`, `uapi/tests/bitcoinWalletClient.test.ts` | partial | Live staging-testnet wallet connect with Xverse or Leather, signed challenge proof, top-chrome identity hydration, Wallet pane provider/address/balance readout, Supabase auth/session projection, sign-out clearing, and SQL evidence in `auth.users`, `user_connections`, and `user_profiles`. Leather parity additionally requires documented `getAddresses`, `open`, `signMessage`, hex `signPsbt`, and `sendTransfer` request shapes to stay covered by tests before Terminal BTC fee usage depends on them. |
-| GitHub App and repository source scope | `uapi/app/api/vcs/_shared.ts`, `uapi/app/api/vcs/[provider]/callback/route.ts`, `uapi/app/api/vcs/[provider]/setup/route.ts`, `uapi/app/api/vcs/[provider]/repositories/route.ts`, `packages/api/src/vcs/github-service.ts`, Auxillaries Externals pane, `supabase/migrations/001_v26_production.sql` `user_connections` and `vcs_repositories` | partial | GitHub App install/callback returns to Externals, installation/user state is stored under provider-scoped connection data, repositories appear for Give/Need source scope, and SQL evidence confirms `user_connections.provider='github'` plus `vcs_repositories` rows. |
-| 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`, `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/*` | baseline pass; first-run QA evidence still 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: `pnpm db:data-health:daily` passes 24/24 against staging, live data-health/schema E2E passes with `.env.local` loading, and direct advisory-style SQL returns zero public tables with policies/browser grants while RLS is disabled. |
+| BTC/D identity and wallet-backed session | `uapi/app/api/wallet/_shared.ts`, `uapi/app/api/wallet/authenticate/route.ts`, `uapi/app/api/wallet/oauth/authorization-code/route.ts`, `uapi/app/api/wallet/oauth/token/route.ts`, `uapi/app/api/wallet/oauth/userinfo/route.ts`, `uapi/lib/bitcoin-wallet-client.ts`, `uapi/lib/bitcode-wallet-local.ts`, `packages/btd/src/wallet.ts`, `packages/btd/src/bitcoin-provider.ts`, `supabase/migrations/003_user_connections_provider_scope.sql`, `uapi/tests/bitcoinWalletClient.test.ts` | staging prerequisite pass for Leather; BTC fee signing still pending | May 14 live staging SQL confirmed `auth.users`, `auth.identities`, `user_profiles.settings.bitcodeProfile.walletBinding`, and `user_connections.provider='leather'` for the same wallet-backed user. Xverse/manual-provider parity and Terminal BTC fee signing remain closure evidence before BTC fee usage depends on them. |
+| GitHub App and repository source scope | `uapi/app/api/vcs/_shared.ts`, `uapi/app/api/vcs/[provider]/callback/route.ts`, `uapi/app/api/vcs/[provider]/setup/route.ts`, `uapi/app/api/vcs/[provider]/repositories/route.ts`, `packages/api/src/vcs/github-service.ts`, Auxillaries Externals pane, `supabase/migrations/001_v26_production.sql` `user_connections` and `vcs_repositories` | staging prerequisite pass | May 14 live staging SQL confirmed GitHub installation `132358627`, account `engineeredsoftware`, provider-scoped connection data, and `public.vcs_repositories` rows including `engineeredsoftware/ENGI`. Terminal Give/Need must now prove that repository inventory is used as live source scope. |
+| 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`, `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/*` | baseline pass; Terminal Give/Need 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: `pnpm db:data-health:daily` passes against staging, live data-health/schema E2E passes with `.env.local` loading, wallet/GitHub SQL evidence is green, and the Terminal-specific saved queries now gate Need/Give/Fit write-read parity. |
 | Fit-finding | `uapi/app/terminal/TerminalGiveNeedWorkbench.tsx`, `TerminalNeedScenarioPanel.tsx`, `terminal-give-need-workbench.ts`, `terminal-need-scenarios.ts`, `packages/protocol/src/canonical/*`, `protocol-demonstration/src/*` reference witness | partial | Terminal simplest Need 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. |
 | 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 Need/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 Need/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. |

BITCODE_V28_QA.md

@@ -567,9 +567,9 @@ Deferred to V29 from this pass:
 
 ## Current QA Queue
 
-1. Natural progression 1A in Mock lane, then Testnet-readiness lane.
-2. Natural progression 1B in Mock lane, then Testnet-readiness lane.
-3. Natural progression 1C in Mock lane, then Testnet-readiness lane.
+1. Live staging-testnet Pass 2A: Terminal Give/Need/Fit write-read parity after Wallet and GitHub prerequisites.
+2. Live staging-testnet branch/settlement blocked-readiness or branch-write proof from the Terminal command deck.
+3. Mock-lane regression parity for the same Terminal Give/Need/Fit actions after live behavior is clarified.
 4. MCP API and ChatGPT App MVP readiness in Mock lane, then Testnet-readiness lane.
 5. Docs sequence 00-04 in Mock lane, then Testnet-readiness lane where the route depends on live/provider state.
 
@@ -800,6 +800,70 @@ Paste back after each subpass:
 - Supabase SQL results from the required wallet/GitHub/Terminal queries;
 - a short note naming each issue as V28 blocker, V28 polish, or deferred version focus.
 
+### Pass 2A: Terminal Give/Need MVP Write-Read QA
+
+Run this pass from `https://www.bitcode.exchange/terminal` after Pass 1A and 1B are green.
+The current live staging baseline is the Leather-authenticated wallet plus GitHub App installation on `engineeredsoftware`, with `engineeredsoftware/ENGI` present in `public.vcs_repositories`.
+
+Before touching Terminal controls, run saved query `v28_qa_terminal_01_prerequisites_wallet_github_repo`.
+The row for the current user should report `terminal_prerequisite_state='ready_for_terminal_give_need'`.
+If it reports `warning:ENGI_repo_not_in_inventory`, continue only if another connected repository is intentionally selected in the UI and paste that repository name with the SQL result.
+If it reports any `blocker:*`, stop and repair that prerequisite before Terminal write QA.
+
+Need path:
+
+1. Hard refresh `/terminal` and wait for top chrome wallet state and Terminal sync to settle.
+2. Confirm the repository/source context is live GitHub inventory, not mock data. Prefer `engineeredsoftware/ENGI` for the first pass.
+3. Confirm no model picker can affect ledgerized Need/Fit/AssetPack synthesis.
+4. In `Give + need chain`, inspect the `need` card and capture the summary, scenario, parser, closure criteria count, target kinds count, and repository row.
+5. Click `Record need posture`.
+6. Confirm the UI reports that need-measurement posture was recorded.
+7. In Network, capture the `/api/executions/history` request and response. Expected status is `201`.
+8. Run `v28_qa_terminal_02_activity_after_write` and confirm an `executions_recent` row with `type='agentic-execution:need-measurement'`, `context_summary.source='terminal-need-scenario-panel'`, and the same scenario/repository shown in the UI.
+
+Give path:
+
+1. In `Give + need chain`, inspect the `give` card and capture selected source entries, artifact kinds, repository row, and profile row.
+2. Click `Record give posture`.
+3. Confirm the UI reports that give-side share posture was recorded.
+4. In Network, capture the `/api/executions/history` request and response. Expected status is `201`.
+5. Run `v28_qa_terminal_02_activity_after_write` and confirm an `executions_recent` row with `type='agentic-execution:asset-pack'`, `context_summary.source='terminal-give-need-workbench'`, `context_summary.workbench='give'`, and a non-empty `output_summary.give`.
+
+Fit and closure path:
+
+1. Inspect `Asset-pack fit and settlement intent`.
+2. Click `Record fit posture`.
+3. Confirm the UI reports that fit and settlement posture was recorded.
+4. Run `v28_qa_terminal_02_activity_after_write` and confirm an `executions_recent` row with `type='agentic-execution:proof-refresh'`, `context_summary.workbench='fit'`, and a non-empty `output_summary.fit`.
+5. In `Flow controls`, inspect `Transaction readiness`.
+6. If `Make Bitcode branch` is enabled, click it once and capture `/api/make-bitcode-branch` plus the follow-up `/api/executions/history` write. Then run `v28_qa_terminal_02_activity_after_write` and `v28_qa_terminal_03_btd_ledger_after_terminal`.
+7. If `Make Bitcode branch` is disabled, capture the disabled tooltip/readiness text. This is acceptable for V28 only when it names the exact missing capability and the Need/Give/Fit posture rows above still persisted and reread correctly.
+
+BTD/ledger readback:
+
+1. Run `v28_qa_terminal_03_btd_ledger_after_terminal` after any fit, branch, BTC fee, mint, or ledger action.
+2. For early V28 posture-only writes, empty `recent_measuremint_receipts`, `recent_asset_pack_ranges`, `recent_btc_fee_transactions`, and `recent_ledger_anchors` rows are acceptable if `consistency_summary` reports zero missing journals, zero missing anchors, and zero blocking repairs.
+3. If Terminal claims an AssetPack mint, BTC fee, ledger anchor, settlement, or reconciliation happened, the matching row must appear in the corresponding BTD section of query 03.
+
+Pass criteria:
+
+- Wallet/Auth/Profile/GitHub/repository prerequisites are ready in query 01.
+- Need, Give, and Fit record actions write user-scoped rows and reread in query 02.
+- The Terminal activity UI shows those rows after refresh or activity reload.
+- Branch/settlement either progresses with explicit network and SQL evidence or fails closed with a precise blocker.
+- No Terminal control routes through Exchange or website Conversations.
+- No user-facing model selection can change ledgerized Need/Fit/AssetPack synthesis.
+- Query 03 shows no ledger/database drift for any BTD state that Terminal claims.
+
+V28 blockers:
+
+- `/api/executions/history` returns 500 or query 02 reports `public.executions` missing after a Terminal write is expected to persist.
+- Terminal shows mock repository, mock wallet, or mock GitHub state in the deployed staging-testnet lane.
+- A recorded Need/Give/Fit row is not tied to the authenticated wallet user.
+- Terminal claims mint/settlement/anchor/finality without matching BTD projection rows.
+- 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.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:
@@ -1025,6 +1089,25 @@ order by updated_at desc
 limit 10;
 ```
 
+Terminal Give/Need prerequisite consolidation:
+
+Saved query name: `v28_qa_terminal_01_prerequisites_wallet_github_repo`
+
+Use `supabase/queries/v28_qa_terminal_01_prerequisites_wallet_github_repo.sql`.
+This is the preferred single-row readiness query before Terminal Give/Need QA. `v28_qa_05_vcs_repositories_recent` remains the direct repository inventory check, and `v28_qa_05b_github_connection_repository_payload` is only a fallback inspection when repository rows are unexpectedly absent.
+
+Terminal activity write/readback:
+
+Saved query name: `v28_qa_terminal_02_activity_after_write`
+
+Use `supabase/queries/v28_qa_terminal_02_activity_after_write.sql` after every `Record need posture`, `Record give posture`, `Record fit posture`, or `Make Bitcode branch` action. This query reports optional runtime tables as missing instead of hard-erroring, so a missing `public.executions` or `public.execution_events` row becomes explicit QA evidence.
+
+BTD and ledger projection readback:
+
+Saved query name: `v28_qa_terminal_03_btd_ledger_after_terminal`
+
+Use `supabase/queries/v28_qa_terminal_03_btd_ledger_after_terminal.sql` after any Terminal action that claims Fit closure, AssetPack minting, BTC fee payment, ledger anchoring, settlement, or reconciliation.
+
 ### Top Chrome Wallet Readiness
 
 Expected V28 behavior:

supabase/DATA_HEALTH.md

@@ -114,6 +114,18 @@ reusable checks:
   staging-only reset for early QA. It preserves schema/migrations, deletes
   Supabase Auth users, truncates Bitcode-owned public projection data, and
   reseeds `public.btd_supply_state`.
+- `v28_qa_terminal_01_prerequisites_wallet_github_repo`:
+  `supabase/queries/v28_qa_terminal_01_prerequisites_wallet_github_repo.sql`
+  confirms Supabase Auth, wallet binding, GitHub installation, and repository
+  inventory before Terminal Give/Need QA.
+- `v28_qa_terminal_02_activity_after_write`:
+  `supabase/queries/v28_qa_terminal_02_activity_after_write.sql` checks
+  Terminal activity, execution events, pipeline rows, stream logs, and errors
+  after each Terminal write action.
+- `v28_qa_terminal_03_btd_ledger_after_terminal`:
+  `supabase/queries/v28_qa_terminal_03_btd_ledger_after_terminal.sql` checks
+  BTD measuremint, ranges, BTC fee receipts, Terminal journal, ledger anchors,
+  reconciliation repairs, and crypto telemetry after Terminal closure actions.
 
 The script runner is authoritative for pass/fail automation. The saved queries
 are for operator inspection and QA narration.