wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V27_PARITY_MATRIX.md

@@ -28,7 +28,7 @@ Fresh audit inputs:
 - `BITCODE_SPEC_V27_DELTA.md`
 - `BITCODE_SPEC_V27_NOTES.md`
 - `BITCODE_SPEC_V27_PARITY_MATRIX.md`
-- `protocol-demonstration/V26_APPLICATION_SYSTEMS.md`
+- `protocol-demonstration/V26_TERMINAL_SYSTEMS.md`
 - `protocol-demonstration/V26_PROOF_SURFACES.md`
 - `packages/btd/src/constants.ts`
 - `packages/btd/src/index.ts`

BITCODE_SPEC_V28_NOTES.md

@@ -129,6 +129,12 @@ The same pass also reclassified active `orbitals` naming as legacy residue when
 Redirect-only `/orbitals/*` compatibility can remain documented as compatibility until it is removed, and old stylesheet class names can remain temporarily only where they are inert styling carriers.
 Active product language and touched implementation should converge on Auxillaries.
 
+V28 also owns the first hard separation between the standalone protocol demonstration and commercial Bitcode runtime source.
+The demonstration remains a sibling reference implementation and proof witness, not a workspace package that commercial UAPI can import.
+Commercial source must import formal protocol primitives from `packages/protocol` / `@bitcode/protocol`, and the UAPI Terminal witness must read formal protocol package assets rather than `protocol-demonstration/public`.
+The standalone `protocol-demonstration` runtime must not import UAPI or commercial packages; proof tests may continue to read commercial source as audit material only when the read is explicitly a parity/proof source-read, not a runtime dependency.
+V28 closes this as a boundary baseline; V29 must continue commercializing freshly ported protocol internals into cleaner packages and narrower APIs.
+
 ## Promotion Review Basis
 
 The V28 handoff is grounded in:
@@ -163,6 +169,7 @@ They are V28 inputs because V27 closed the protocol law and minimum crypto-comme
 | External VCS providers beyond GitHub remain incomplete or not started | V27 does not require broad third-party provider completion, and V28 is MVP QA | Keep V28 provider UX honest about GitHub-only readiness and hand off broader provider readiness to the later product version that owns the affected surface |
 | Auxillaries still mixes old orbital-era shell styles with the active contained tabs-left experience | V27 closed protocol law, not full commercial application visual QA | Remove or strictly contain conflicting `orbital-*` layout/background classes from active Auxillaries auth/profile/readiness paths, preserve only reusable aesthetic pieces that do not control commercial layout, and prove with desktop/mobile screenshots |
 | V26 proof generator and older promotion scripts still contain version-specific historical logic | V27 accepted generated-equivalent proof artifacts rather than fully modernizing promotion automation | Decide whether V28 should update proof generation for V28+ families or leave older promotion scripts as historical tooling |
+| Some formal protocol package internals are freshly ported from the standalone demonstration | V28 needs a commercial import boundary before it can finish all deeper package refactors | Keep commercial UAPI imports on `@bitcode/protocol`, keep `protocol-demonstration` out of the workspace build graph, and defer narrower package extraction/commercialization to V29 Terminal depth unless it blocks V28 MVP QA |
 
 ## V28 Gate Sketch
 
@@ -178,6 +185,7 @@ The minimum useful V28 gate plan is commercial-application-MVP-first:
    - QA primary active routes and navigation.
    - Remove Auxillaries old orbital shell conflicts from active contained tabs-left paths.
    - Harden Exchange MVP activity/search/detail/range-acquisition readiness.
+   - Separate commercial runtime imports from the standalone protocol demonstration and remove the demonstration from the workspace build graph.
    - Capture desktop/mobile visual proof for sign-in, create-account, signed-in profile, Exchange, Terminal, and BTD range disclosure.
 
 3. **Gate 3: Terminal Wallet, BTC Fee, And Need-Fit-Measuremint Workflow**
@@ -218,7 +226,9 @@ Before V28 implementation closes, rerun at minimum:
 - `rg -n 'gap blocking|partial blocking|not started|not promoted|not generated yet' BITCODE_SPEC_V28*`
 - `pnpm -C packages/api build`
 - `pnpm -C packages/orm build`
-- `pnpm -C protocol-demonstration test:v27-crypto`
+- `npm --prefix protocol-demonstration run test:v27-crypto`
+- `node --test --test-force-exit protocol-demonstration/test/v28-boundary-separation.test.js`
+- `pnpm -C uapi exec jest --runInBand tests/protocolCommercialBoundary.test.ts`
 - Commercial application and Terminal-specific Jest/Playwright coverage once added
 - `pnpm -C uapi build`
 - `git diff --check`

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -115,6 +115,7 @@ Audit query classes:
 | Exchange BTD widget landing stays at top-level Exchange entry | `uapi/app/exchange/ExchangePageClient.tsx`, `uapi/tests/exchangePageClient.test.tsx`, `protocol-demonstration/test/v28-commercial-mvp-qa.test.js` | closed for current micro-interface | Gate 2 |
 | Auxillaries old orbital shell conflicts removed from active contained tabs-left experience | May 7 manual QA reports no active old orbital shell collision and selectable panes; `BITCODE_V28_QA.md` records remaining V28 polish for visible `lane ready` / `lane active` prose, hierarchy, legibility, spacing, and border cleanup | partial; old orbital conflict appears closed, Auxillaries shell polish remains pending | Gate 2 |
 | Active Auxillaries naming avoids `orbitals` residue | `uapi/config/featureFlags.ts`, `uapi/lib/mock-review-mode.ts`, `uapi/app/terminal/TerminalOpenAuxillariesButton.tsx`, `uapi/components/base/bitcode/layout/user-menu.tsx`, and related tests now use Auxillaries naming; redirect-only `/orbitals/*` compatibility and inert stylesheet carriers remain bounded as compatibility/styling until separately removed | partial; active touched names closed, remaining CSS/compatibility carriers tracked for later cleanup | Gate 2 |
+| Standalone demonstration and commercial protocol source are separated | `packages/protocol` is the formal commercial protocol package; `uapi/package.json` depends on `@bitcode/protocol`; `pnpm-workspace.yaml` no longer includes `protocol-demonstration`; `uapi/tests/protocolCommercialBoundary.test.ts` and `protocol-demonstration/test/v28-boundary-separation.test.js` lock no commercial imports from the standalone demonstration and no demonstration runtime imports from commercial packages/UAPI | closed for V28 boundary baseline; V29 owns deeper commercialization of freshly ported package internals | Gate 2 |
 | Terminal big-picture operator orientation | `/terminal`, `uapi/app/terminal/TerminalTransactionWorkspace.tsx`, `uapi/app/terminal/TerminalMvpMap.tsx`, `uapi/components/base/bitcode/execution/BitcodeTransactionsOverview.tsx`, and `uapi/tests/e2e/commercial-mvp.terminal.spec.ts` now frame Terminal as recent/scoped Give/Need activity plus selected result, not Exchange master-detail; bare `/terminal` no longer auto-mutates during public nav while explicit route context remains addressable, and the old Terminal route redirects without becoming a canonical product route | partial; architectural correction, route-stability fixes, and known digest action no-ops implemented, next manual QA must judge digestibility | Gate 2 / Gate 3 |
 | Source names remain implicitly versioned to active canon | `AGENTS.md`, `uapi/app/terminal/demonstration-witness-scoped-styles/route.ts`, `uapi/app/terminal/demonstration-witness-styles/route.ts`, `uapi/app/terminal/demonstration-witness-scoped-styles/route.ts`, `uapi/app/terminal/demonstration-witness-styles/route.ts`, `uapi/app/terminal/demonstration-witness-theme-overrides.ts`, and `uapi/tests/demonstrationWitnessScopedStylesRoute.test.ts` replace explicit gate-named stylesheet route/source carriers with precise unversioned demonstration-witness names | closed for touched active UAPI demonstration witness stylesheet source | Gate 2 |
 | Exchange MVP activity/search/detail/range-acquisition readiness | `uapi/app/exchange/ExchangePageClient.tsx`, `uapi/app/terminal/TerminalTransactionWorkspace.tsx`, `uapi/app/terminal/TerminalTransactionDetailSurface.tsx`, `/btd/[assetPackId]`, and `uapi/tests/e2e/commercial-mvp.btd-exchange.spec.ts` now bind Exchange to a master table/search/filter pane plus named selected detail pane with table facts, non-column facts, payload, proof, AssetPack, and history paths | closed for V28 Exchange master-detail MVP; V30 owns deeper market mechanics | Gate 2 |

BITCODE_SPEC_V29_NOTES.md

@@ -44,12 +44,17 @@ V29 owns deeper Terminal:
 - V29 should improve Terminal copy, hierarchy, explanatory precision, and operator sequencing around Give, Need, Fit, proof, AssetPack, BTC fee posture, BTD range/read-right posture, and selected activity detail.
 - This is not a V28 blocker unless specific wording prevents a user from completing basic V28 MVP navigation or materially misstates Bitcode law.
 - May 7, 2026 follow-up QA clarified that Exchange, not Terminal, owns the master-detail product pattern. V28 must fix that MVP architecture and any obvious dead/ambiguous click targets; V29 should then deepen Terminal-specific sequencing, density management, task progression, and richer Give/Need result reading without reintroducing Exchange master-detail language.
+- V28 introduces a formal `@bitcode/protocol` package and removes direct commercial imports from the standalone `protocol-demonstration`, but some package internals are intentionally fresh ports for parity. V29 must continue commercializing those demonstration-origin internals into formal packages, narrower APIs, durable package tests, and Terminal-owned protocol adapters.
+- The standalone `protocol-demonstration` should remain a sibling reference guide and proof witness outside the workspace build graph. V29 should use it to reveal commercial implementation gaps, not as runtime code imported by commercial UAPI, Terminal, Exchange, Auxillaries, MCP, ChatGPT App, or package consumers.
 
 ## Boundaries
 
 V29 deepens Terminal only after V28 establishes commercial MVP coherence.
 It must not absorb V30 Exchange depth, V31 Auxillaries depth, V32 provation/testing depth, V33 interface finalization, V34 deployment depth, or V35 telemetry/documentation depth except for narrow Terminal-owned hooks.
 
+V29 must also avoid reopening V28's demonstration/commercial boundary.
+Any Terminal feature that currently depends on freshly ported demonstration-origin modules should be formalized in-place inside commercial packages or replaced with package-native primitives, while the standalone demonstration stays a reference implementation.
+
 ## Return To V28
 
 Do not start V29 implementation during V28.

BITCODE_V26_QA.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This guide records human QA for the V26 commercial promotion. It focuses on the website application and the commercial implementation of the Bitcode demonstration protocol.
+This guide records human QA for the V26 commercial promotion. It focuses on the website product and the commercial implementation of the Bitcode demonstration protocol.
 
 Use this document to collect observations the repository cannot infer locally: browser behavior, wallet/provider account state, live API responses, database rows, network failures, and whether the commercial UI actually teaches Bitcode rather than old Engi or generic agentic SWE concepts.
 
@@ -32,7 +32,7 @@ Record this once per QA pass.
 Use the dev-server URL reported by the agent. For testnet validation, prefer:
 
 ```text
-/application?environmentMode=testnet&bitcodeDebug=1
+/terminal?environmentMode=testnet&bitcodeDebug=1
 ```
 
 If the server falls back to a different port, keep the same path and query string.
@@ -46,23 +46,23 @@ Every issue should connect to at least one of these questions.
 | Spec alignment | Does the product behave like a commercial extension of `protocol-demonstration/`, not a separate product or old Engi flow? |
 | Inference | Do prompts, contexts, model/provider calls, and completion payloads use Need, AssetPack evidence, Finish, Shippables, BTC fees, and non-fungible `$BTD` precisely? |
 | AssetPack pipeline | Are `assetPackSynthesisArtifacts` / `writtenAssets` evidence-only, while `shippables` / `deliveryMechanism` represent GitHub pull-request delivery only? |
-| Terminal | Can a user express a Need, anchor repository context, inspect activity, reread evidence, and understand closure without leaving `/application`? |
+| Terminal | Can a user express a Need, anchor repository context, inspect activity, reread evidence, and understand closure without leaving `/terminal`? |
 | Exchange | Are existing V26 Exchange surfaces minimum viable and scoped, without pretending V27/V28 tokenomics, Terminal, or market depth is complete? |
 | Wallet and balances | Does the top-right balance distinguish BTC fee liquidity from non-fungible `$BTD` share/read-right holdings? |
 | Providers | Do GitHub, wallet, MCP, ChatGPT App, and API surfaces fail closed when authorization or repository context is missing? |
 | Storage | Do database rows preserve Bitcode fields and avoid resurrecting old deliverable/product vocabulary except as physical retained table identifiers? |
 | Proof | Do visible proof/status/readiness claims match actual route, database, network, and UI behavior? |
 
-## Website Application QA
+## Website Product QA
 
-Start at `/application?environmentMode=testnet&bitcodeDebug=1`.
+Start at `/terminal?environmentMode=testnet&bitcodeDebug=1`.
 
 1. Load the page signed out.
    - Record load time, visible route, console errors, and whether any old Engi, generic developer-platform, or deprecated "deliverables" language is visible.
-   - Confirm `/application` is the primary product surface and not a marketing wrapper around a demo.
+   - Confirm `/terminal` is the primary product surface and not a marketing wrapper around a demo.
 
 2. Sign in.
-   - Record provider used and whether the app lands back on `/application`.
+   - Record provider used and whether the app lands back on `/terminal`.
    - Confirm auth, Profile, Connects, Interfaces, and `$BTD` surfaces use Bitcode naming.
 
 3. Inspect the top-right balance widget.
@@ -146,7 +146,7 @@ If you inspect Supabase or local database state, collect row ids and field names
 | generated assets | AssetPack evidence and file-change metadata |
 | vector storage | AssetPack evidence embeddings; retained physical table names are acceptable only as storage identifiers |
 | user BTD tables | `$BTD` holdings/read-rights, not fungible credit spend |
-| notifications/email rows | AssetPack completion, measured `$BTD`, BTC fee posture, `/application?transactionId=...` links |
+| notifications/email rows | AssetPack completion, measured `$BTD`, BTC fee posture, `/terminal?transactionId=...` links |
 
 Flag any current API/UI field named `deliverables`, `finalWorkSummary`, `credits` as product denomination, `$ENGI`, or `ENGI`.
 
@@ -199,7 +199,7 @@ Blocking / high / medium / low
 
 | Area | Pass / fail | Blocking issue ids |
 | --- | --- | --- |
-| Website application | | |
+| Website product | | |
 | Need review | | |
 | AssetPack run | | |
 | Finish PR delivery | | |

BITCODE_V28_QA.md

@@ -103,15 +103,22 @@ Implemented after Pass 2, pending next manual QA confirmation:
 | Direct `/conversations` fullscreen exit returns deterministically to `/terminal`. | Focused Conversations E2E passes; full commercial MVP E2E passes. |
 | Bare Terminal route no longer auto-mutates its URL during load, while explicit route context and user selections still remain URL-addressable. | Public stitched navigation route spec passes 5-repeat focused verification and the full commercial MVP suite. |
 | 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. |
-| Active `/application` route/import/runtime compatibility artifacts are absent from commercial source scans. | Source scans show no active `/application`, `app/application`, or application 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 application shell vocabulary. | Runtime/API scans show no application-shell names across active demonstration entrypoints. |
+| 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. |
 
 Automated verification after this implementation pass:
 
-- `pnpm -C uapi exec tsc --noEmit --pretty false`: pass.
+- `pnpm -C uapi exec tsc --noEmit --pretty false`: pass after the formal protocol package split.
 - `pnpm -C uapi run test:e2e:commercial-mvp`: 50 passed after Conversations streaming, Conversations exit, and Terminal transaction-search stabilization.
-- `pnpm -C protocol-demonstration test:integration`: 58 passed after demonstration title/posture cleanup.
-- `pnpm -C protocol-demonstration test:v28-commercial-mvp-qa`: 6 passed after demonstration title/posture cleanup.
+- `npm --prefix protocol-demonstration run test:integration`: 58 passed after standalone demonstration/package-boundary cleanup.
+- `npm --prefix protocol-demonstration run test:v27-crypto`: 9 passed after standalone demonstration/package-boundary cleanup.
+- `npm --prefix protocol-demonstration run test:v28-commercial-mvp-qa`: 8 passed after adding the boundary-separation checks.
+- `pnpm -C uapi exec jest --runInBand tests/demonstrationWitnessMount.test.tsx tests/demonstrationWitnessScopedStylesRoute.test.ts tests/terminalPreservedShellSurface.test.tsx tests/terminalShellBridge.test.tsx tests/marketingLandingPage.test.tsx tests/api/needReviewProtocolParity.test.ts tests/api/bitcodeAppContextOptions.test.ts tests/protocolCommercialBoundary.test.ts`: 18 passed after the formal protocol package split.
+- `node --test --test-force-exit protocol-demonstration/test/v28-boundary-separation.test.js`: 2 passed after the formal package split.
+- `pnpm -C packages/protocol test`: 1 passed after the formal package split.
+- `pnpm -C packages/protocol run typecheck`: pass after adding the formal package typecheck config.
+- `pnpm -C uapi exec jest --runInBand tests/protocolCommercialBoundary.test.ts`: 3 passed after the formal package split.
 
 Deferred to V29 from this pass:
 

internal-docs/BITCODE_EXECUTIONS.md

@@ -48,4 +48,4 @@ Operators should be able to:
 - Replace output-object-first labels with AssetPack or written-asset labels.
 - Replace pre-Finish labels with Finish and delivery-mechanism labels.
 - Keep computer-use hidden unless the server admits it internally for Need measurement.
-- Ensure all execution UI reads from the same Exchange activity model as `/application`.
+- Ensure all execution UI reads from the same Exchange activity model as `/terminal`.

internal-docs/BITCODE_FRONTEND_ARCHITECTURE.md

@@ -5,7 +5,7 @@ Status: non-canonical internal note.
 ## Product Surfaces
 
 V26 frontend architecture is organized around:
-- Bitcode Terminal at `/application`,
+- Bitcode Terminal at `/terminal`,
 - Bitcode Exchange activity, Transactions, and history surfaces,
 - conversations as rich input overlays,
 - auxillaries for identity/readiness,