wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -53,6 +53,49 @@ V28 answers that by specifying:
 - honest provider readiness where GitHub is the implemented VCS provider and broader provider rollout is later external-connection work;
 - V28 promotion proof after implementation, tests, builds, and route scans close.
 
+## Real-Deployed Staging-Testnet MVP Target
+
+V28 closure is now judged primarily by one real staging-testnet operator path with mocks disabled.
+Mock mode remains a deterministic regression harness, but manual acceptance must prove that the deployed staging-testnet application is honest and minimally usable from first onboarding through Terminal Give and Need results.
+
+The V28 staging-testnet target path is:
+
+1. Open `/terminal` with Exchange and website Conversations disabled and with public mock flags off.
+2. Open the Wallet auxillary pane and connect a Bitcoin-capable browser wallet on the configured testnet lane.
+3. Capture a signed Bitcoin identity proof, bind payment/auth address facts, and project the wallet session into Supabase through Bitcode's custom Bitcoin-auth boundary.
+4. Return to top chrome and verify that wallet identity, BTC fee posture, and BTD posture replace anonymous `Connect Wallet` state only after wallet status is known.
+5. Open Externals and install or connect the GitHub App so repository inventory and source scope are available for Give and Need.
+6. Keep Profile limited to optional email/contact/admin posture; email may improve notifications, but it is not the primary identity primitive.
+7. In Terminal, perform the simplest Need path: select or express a Need, produce Fit-finding evidence, show review/proof/dedupe roots, and read the Fit result without leaving Terminal.
+8. Synthesize the resulting AssetPack through protocol-specified model and pipeline configuration, not user-selected ledgerized synthesis preferences.
+9. Emit or simulate the BTC fee/testnet ledger path with user-controlled signing, explicit blocked-readiness receipts when broadcast is unavailable, and no server custody.
+10. Record synthetic measurement, measuremint result, AssetPack range or zero-cell receipt, access-policy hash, ledger anchor or ledger-observed placeholder, Terminal journal entry, and database projection.
+11. Reconcile ledger/journal/database state and expose any drift as a blocking or repairable Terminal read.
+12. Perform the simplest Give path against a GitHub repository/source scope and read earning, settlement, or blocked-readiness state from the same Terminal/protocol readback grammar.
+
+V28 does not require value-bearing mainnet behavior.
+Regtest, signet, public testnet, and staging-testnet readiness may be used, but value-bearing mainnet requires a separate approval root.
+Ledgers and ledgerized journals remain source-of-truth for cryptographic finality; Supabase/PostgreSQL is the ledger-derived and Bitcode-canonical data realm for private/metaphysical facts, projections, readiness, and UI read models.
+
+MCP API and ChatGPT App MVP entrypoints must read from the same wallet, GitHub, Terminal journal, AssetPack, access-policy, and proof state.
+They may trigger admitted actions only through the same fail-closed Protocol boundary that Terminal uses.
+
+## Deterministic Model Posture
+
+User-driven model selection is not allowed for ledgerized Bitcode synthesis.
+Fit-finding, AssetPack synthesis, semantic measurement, measureminting, proof admission, ledgerized journaling, and settlement must use protocol-specified model identities, model versions, prompts, thresholds, toolchains, and receipt-bound configuration.
+
+This rule exists because user-selected model preferences would break replay, parity, and settlement determinism.
+Changing a ledgerized model or pipeline configuration is a protocol/specification event with receipt/proof impact, not a per-user setting.
+
+Allowed exception:
+
+- non-ledgerized conversational interfaces may expose user model selection for draft conversation UX;
+- any output that becomes Fit evidence, AssetPack material, measurement, proof, journal, or settlement input must pass through the protocol-specified ledgerized path and record the model/configuration roots used.
+
+Active source or UI that presents broad "apply model to all" behavior for Terminal, Protocol, Fit, AssetPack, or BTD synthesis is V28 legacy residue.
+It must be removed, hidden behind a conversation-only boundary, or made explicitly non-ledgerized before V28 promotion.
+
 ## Commercial Application MVP QA Scope
 
 The screenshot QA finding from May 6, 2026 shows that Auxillaries still mixes the older orbital visual shell with the newer contained tabs-left approach.
@@ -221,12 +264,12 @@ Acceptance criteria:
 - sign-in, sign-up, signed-in, and signed-out Auxillaries states are responsive and not pushed offscreen.
 - Auxillaries portal entry, including unauthenticated `Connect Wallet`, opens the contained Auxillaries shell rather than the old onboarding/orbital shell.
 - mock and testnet-readiness Auxillaries entry render the same pane order and shell regardless of caller; V28 primary onboarding order is Bitcoin wallet identity first, GitHub repository connection second, optional email notifications third.
-- Bitcoin wallet authentication must use a Bitcoin-capable wallet provider, with Xverse/Sats Connect first, Leather direct-provider second, UniSat/OKX fallback, and manual Bitcoin-address staging only when no Bitcoin dapp provider is discoverable. When multiple providers are detected, Profile must expose provider-specific actions such as `Connect Xverse` and `Connect Leather` so a stalled Xverse prompt does not block Leather verification. The flow must obtain a Bitcode Bitcoin authentication proof when available, bind the Bitcoin address to the profile, preserve payment/auth address distinction, and persist wallet-provider connection posture without server custody of private keys.
+- Bitcoin wallet authentication must use a Bitcoin-capable wallet provider, with Xverse/Sats Connect first, Leather direct-provider second, UniSat/OKX fallback, and manual Bitcoin-address staging only when no Bitcoin dapp provider is discoverable. When multiple providers are detected, Wallet must expose provider-specific actions such as `Connect Xverse` and `Connect Leather` so a stalled Xverse prompt does not block Leather verification. The flow must obtain a Bitcode Bitcoin authentication proof when available, bind the Bitcoin address to the wallet identity/profile projection, preserve payment/auth address distinction, and persist wallet-provider connection posture without server custody of private keys.
 - non-mock/staging QA must fail clearly when the Bitcoin wallet provider is unavailable, the browser exposes only an Ethereum provider, Supabase session persistence is unavailable, signed proof capture fails, or the connection-storage migration has not been applied; local staging may preserve the wallet identity for QA continuity while backend persistence is repaired.
 - Auxillaries selector cards use centered pane names plus visual state indicators, not duplicate lane-title prose, and hover movement must not clip the first selector card.
 - Auxillaries profile panes must be scrollable on first render, including unauthenticated and non-mock contained portal entry.
 - Auxillaries settings panes auto-save edits; visible pane-level Save buttons are not part of the commercial MVP shell.
-- the `$BTD` auxillary shows BTD as the primary large balance, shows owned AssetPack count and BTC wallet liquidity as secondary stats, moves explanatory system copy into tooltips/accessibility labels, avoids long-identifier overflow, and includes a Protocol/Terminal activity table for BTD-relevant owned packs, Gives, Needs, proof closures, ledger anchors, synthetic measurements, and range-bearing activity.
+- the Wallet auxillary shows BTD as the primary large balance, shows owned AssetPack count and BTC wallet liquidity as secondary stats, moves explanatory system copy into tooltips/accessibility labels, avoids long-identifier overflow, and includes a Protocol/Terminal activity table for BTD-relevant owned packs, Gives, Needs, proof closures, ledger anchors, synthetic measurements, and range-bearing activity.
 - notification dropdowns remain legible and do not include redundant Auxillaries footer launchers when top chrome and profile menu already provide that entry.
 - route QA covers `/`, `/terminal`, `/auxillaries/*`, `/btd/[assetPackId]`, MCP API routes, ChatGPT App entrypoints, and protocol routes; Exchange and website Conversations are disabled or hidden for V28 QA, and the prior generic workspace route is verified absent from active source.
 - Exchange navigation is disabled for V28 and must not be required by any V28 acceptance criterion; any retained Exchange route/API behavior is treated as deferred compatibility or future work.
@@ -239,7 +282,7 @@ Acceptance criteria:
 - V28 verbose QA telemetry may log wallet detection, wallet signing, local/server persistence, user-data merge, nav identity state, and BTD wallet pane entry behind `NEXT_PUBLIC_BITCODE_QA_VERBOSE=true`, `NEXT_PUBLIC_BITCODE_VERBOSE=true`, `?bitcode_verbose=true`, or `localStorage.bitcode.qa.verbose=true`.
 - automated Playwright E2E coverage exists at commercial-product granularity for public home, Terminal, Auxillaries, BTD range disclosure, MCP API/ChatGPT App readiness, docs, route navigation, responsive route health, and key micro-interactions including URL-addressable Terminal activity filters, filter reset behavior, BTD data-share consent, and public docs article readability.
 - Playwright tests must check browser console/page-error cleanliness, framework-overlay absence, route readability, micro-interface interaction, and stitched user flows rather than only screenshot snapshots.
-- the commercial-MVP Playwright runner executes serially against one deterministic mock-mode dev server, including mocked Auxillaries profile, model-preferences, data-share, notifications, Terminal activity, BTD mint/read state, and MCP/ChatGPT App readiness paths, so failures represent product regressions rather than local wallet/session availability.
+- the commercial-MVP Playwright runner executes serially against one deterministic mock-mode dev server, including mocked Auxillaries profile, non-ledgerized interface preferences, data-share, notifications, Terminal activity, BTD mint/read state, and MCP/ChatGPT App readiness paths, so failures represent product regressions rather than local wallet/session availability.
 - visual QA proves no framework overlay, blank page, major content overlap, or unreadable primary controls.
 
 ### Gate 3: Terminal Wallet, BTC Fee, And Need-Fit-Measuremint Workflow
@@ -259,6 +302,7 @@ Acceptance criteria:
 - semantic volume, cumulative measurement, measuremint target, residual credit, token count, zero-cell reason, and refit posture are visible.
 - source deposit, Need discovery, preliminary Fit, and uncommitted proof never imply minting.
 - 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.
 
 ### Gate 4: Terminal AssetPack Range Detail
 

BITCODE_SPEC_V28_NOTES.md

@@ -47,6 +47,36 @@ This means:
 - V28 keeps Terminal, Auxillaries readiness, BTD range disclosure, wallet/BTC/testnet, synthetic measurement, BTD-AssetPack minting, ledgerized journals, database projection, reconciliation, MCP API, and ChatGPT App MVP.
 - any retained Exchange or Conversations code is compatibility/future source and must not be a V28 promotion blocker unless it contaminates active Terminal/Protocol/MCP/ChatGPT behavior.
 
+## May 13 Staging-Testnet QA Recalibration
+
+V28 QA now resumes from the real deployed staging-testnet path, not from an isolated mock surface tour.
+Mock mode remains important for deterministic regression testing, but manual acceptance must primarily validate the live staging-testnet flow from first onboarding through Terminal transactions.
+
+The V28 natural path is:
+
+1. Wallet first: detect Xverse/Leather/other Bitcoin-capable providers, sign the Bitcode Bitcoin challenge, persist the wallet-backed session through Bitcode's custom Bitcoin-auth boundary, and reflect wallet identity in top chrome and the Wallet pane.
+2. Externals second: connect the GitHub App, capture installation/callback state, and read repository inventory needed by Give and Need.
+3. Profile third: collect optional email/contact/admin posture without treating email as the primary identity primitive.
+4. Need path: use Terminal to express or select the simplest Need, run Fit-finding, expose source/proof/dedupe roots, and read the Fit result.
+5. AssetPack path: synthesize the AssetPack with protocol-specified model and pipeline configuration, emit synthetic measurement, measuremint/range or zero-cell receipt, access policy, ledger anchor/readiness, and Terminal journal state.
+6. Give path: contribute source from the connected repository scope and read earning, settlement, or blocked-readiness state through the same Terminal/protocol readback grammar.
+7. Reconciliation path: query Supabase/PostgreSQL projections and compare them to Terminal journal, ledger anchor, wallet, GitHub, AssetPack, and telemetry state.
+
+This recalibration means the QA document, parity matrix, and implementation work should now classify every finding by the lowest-level source-of-truth it affects: wallet identity, GitHub/source scope, Fit-finding, AssetPack synthesis, ledgerized journal, PostgreSQL projection, pipeline runtime, telemetry/alerting, or legacy residue.
+
+### Deterministic Model Boundary
+
+V28 must remove the idea that a user can choose ledgerized Bitcode synthesis models.
+User model selection breaks replay and parity when the selected model can affect Fit-finding, AssetPack synthesis, semantic measurement, measureminting, proof admission, or journaled settlement.
+
+The allowed boundary is narrow:
+
+- conversation UX may offer user-facing model preferences only for draft, non-ledgerized conversation behavior;
+- ledgerized Terminal/Protocol behavior must use protocol-specified model identities, versions, prompts, thresholds, toolchains, and receipt-bound configuration;
+- any "apply to all" model control visible in active Auxillaries/Interfaces must be removed, disabled, or scoped to non-ledgerized conversation interfaces before V28 promotion.
+
+Current source audit flags `uapi/app/auxillaries/components/AuxillariesInterfacesPane.tsx` and `uapi/app/auxillaries/components/models/GlobalModelSelection.tsx` as likely V28 cleanup points because they still present broad user-driven model preference behavior.
+
 ## QA Scope Refinement
 
 Screenshots captured on May 6, 2026 show the active Auxillaries experience mixing the old orbital shell with the newer contained tabs-left approach.
@@ -75,15 +105,15 @@ V28 refinement:
 - use hover title context for the user's most recent BTD AssetPacks when known;
 - leave hover title absent when no recent AssetPack facts are known instead of showing explanatory copy;
 - use the hover action for the connected wallet label: show the wallet nickname when one exists and otherwise show a middle-truncated Bitcoin address;
-- click the widget into the `$BTD` wallet auxillary pane, leaving Exchange acquisition/trading entry to explicit Exchange navigation and `$BTD` pane activity-table links;
+- click the widget into the Wallet auxillary pane, leaving Exchange acquisition/trading deferred beyond V35 and any BTD-relevant activity visible through Terminal/Protocol activity readbacks;
 - keep the demonstration protocol aligned with a source-reading V28 MVP QA proof.
 
 Manual follow-up QA on May 6, 2026 passed after tightening the divider and icon spacing:
 
 - resting state reads `0.042 BTC | 1,200 BTD` visually with a styled divider rather than a literal pipe;
 - hover state reads wallet identity without layout shift;
 - hover title lists recent BTD AssetPacks and does not explain BTC/BTD ontology;
-- click opens the `$BTD` auxillary wallet pane without console errors.
+- click opens the Wallet auxillary pane without console errors.
 
 Follow-up Exchange landing QA previously revealed that the Exchange client was appending `transactionId=mock-run-branch-remediation` and scrolling to the lower `Finish-delivered Shippables` section after the widget click. That work is no longer V28 closure after the May 11 scope reduction. The V28 rule is now that the BTD widget opens the `$BTD` wallet auxillary pane and Exchange is disabled/hidden for V28 QA; deeper Exchange behavior moves beyond V35.
 
@@ -185,7 +215,7 @@ The following 1A resume exposed a second Auxillaries MVP shell slice.
 All portal entry into Auxillaries, including unauthenticated `Connect Wallet` from the non-mock top chrome, must use the contained Auxillaries shell rather than falling back into the old onboarding/orbital shell.
 The contained selector should not duplicate pane names with both lane labels and centered titles; the centered pane title plus top-right visual state indicator is the V28 pattern.
 Auxillaries edits are application settings and should auto-save; visible Save buttons belong to legacy/onboarding behavior and should be removed from the contained commercial panes.
-The `$BTD` pane must highlight BTD and BTC balances strongly, avoid long-address overflow, and include the shared Exchange activity-table grammar for BTD-relevant activity even when testnet-readiness has no ledger-derived events yet.
+The Wallet pane must highlight BTD and BTC balances strongly, avoid long-address overflow, and include the shared Terminal/Protocol activity-table grammar for BTD-relevant activity even when testnet-readiness has no ledger-derived events yet.
 The notification dropdown is part of prerequisite trust and must keep titles, timestamps, pills, messages, and actions legible without awkward line breaks.
 
 The next May 9 1A patch tightened this into implementation-level V28 expectations.
@@ -202,7 +232,7 @@ Email is no longer allowed to present as the primary Profile authentication path
 The Profile onboarding order is now:
 
 1. Bitcoin wallet authentication connects a Bitcoin-capable wallet provider, captures a Bitcode Bitcoin authentication proof when available, and establishes wallet identity for the staging profile. Xverse is preferred through Sats Connect provider discovery and `wallet_connect`; Leather is supported through `window.LeatherProvider.request('getAddresses')` plus `signMessage`; UniSat/OKX remain fallback providers; MetaMask BTC remains manual-staging-only until a documented Bitcoin dapp provider or Snap bridge is implemented.
-2. GitHub repository connection follows and is required for Give and Need, but Exchange viewing can proceed from wallet identity alone.
+2. GitHub repository connection follows and is required for Give and Need; V28 Terminal read-only orientation may proceed from wallet identity alone, but repository/source-scope actions must stay blocked until GitHub is connected.
 3. Email is optional and exists for notifications, Bitcode updates, and recovery/contact posture.
 
 Implementation must therefore keep wallet auth enabled and top-most in Wallet, avoid the Ethereum provider path for Bitcoin identity, persist wallet-provider binding only through the wallet-auth route when backend session state is available, keep Profile from accepting unverifiable provider-managed signer assertions, and surface staging prerequisites clearly.