V29 Gate 8: Formalize protocol package boundary

Move gate-critical canon helpers behind the @bitcode/protocol package index, retarget root canonical scripts away from direct protocol-demonstration source imports, and correct package-local repo-root defaults for spec and proof helpers.

Document the Gate 8 package-native boundary in the V29 spec family and protocol README, add a fail-closed Gate 8 checker, expand protocol package tests, and wire CI to run protocol package checks plus the UAPI commercial boundary test.

Validation: pnpm --filter @bitcode/protocol typecheck; pnpm --filter @bitcode/protocol test; pnpm run check:v29-gate8; node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28; node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28; node scripts/check-bitcode-canonical-inputs.mjs --current-target V28; node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29; node scripts/run-bitcode-spec-quality.mjs --mode basic; pnpm --dir uapi exec jest --runTestsByPath tests/protocolCommercialBoundary.test.ts --runInBand; git diff --check.

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -69,6 +69,7 @@ jobs:
           node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
           node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
           node scripts/check-v29-gate7-organization-permission-authority.mjs --skip-branch-check
+          node scripts/check-v29-gate8-demonstration-origin-formalization.mjs --skip-branch-check
 
       - name: Validate source casing and imports
         run: |
@@ -83,6 +84,7 @@ jobs:
           pnpm --dir packages/chatgptapp exec tsc --noEmit --pretty false
           pnpm --filter @bitcode/pipeline-asset-pack typecheck
           pnpm --filter @bitcode/pipeline-hosts typecheck
+          pnpm --filter @bitcode/protocol typecheck
 
       - name: Test gate packages
         run: |
@@ -97,6 +99,7 @@ jobs:
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/reading-pipeline-observability.test.ts src/__tests__/reading-pipeline-contract.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-disclosure.test.ts src/__tests__/postprocess.test.ts src/__tests__/read-need.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --filter @bitcode/protocol test
 
       - name: Test staged Reading route and Terminal harness contracts
         run: |
@@ -110,6 +113,7 @@ jobs:
             tests/terminalWalletBtcOperation.test.ts \
             tests/terminalJournalReconciliation.test.ts \
             tests/terminalOrganizationAuthority.test.ts \
+            tests/protocolCommercialBoundary.test.ts \
             tests/terminalTransactionDetailCards.test.tsx \
             tests/terminalTransactionDetailSnapshot.test.ts \
             tests/pipelineExecutionLogHeader.test.tsx \

BITCODE_SPEC_V29.md

@@ -147,6 +147,27 @@ Layer boundaries:
 - Ledger records and journals are source-of-truth for settlement/finality; Supabase/PostgreSQL projections must not contradict them.
 - Source-safe previews may expose measurements, roots, score bands, policy ids, fee quote roots, and settlement posture; they may not expose protected source before payment.
 
+## V29 demonstration-origin commercial formalization canon
+
+V29 Gate 8 makes demonstration-origin canonical helpers package-native commercial APIs.
+The formal package boundary is `packages/protocol` exposed as `@bitcode/protocol`.
+Commercial scripts, workflows, API surfaces, Terminal code, and package tests must import canonical posture, spec-family checks, canon-drift checks, canonical-input checks, and proof generation from `packages/protocol/src/index.js` or from the package export.
+They must not import `protocol-demonstration/src/*` runtime modules.
+
+`protocol-demonstration/` remains valuable, but it is a standalone minimal witness, not a commercial runtime dependency.
+It may be executed by its own test and proof workflows.
+It may be cited as historical evidence by generated proof inventories.
+It must not be the imported implementation source for gate checks, promotion scripts, commercial APIs, or Terminal runtime code.
+
+The commercial protocol package owns the active/draft posture while V29 is in flight:
+
+- `ACTIVE_CANON_VERSION = 'V28'`;
+- `DRAFT_TARGET_VERSION = 'V29'`;
+- spec-family, canonical-input, canon-posture-drift, and proven-generation helpers are exported through the package index;
+- package tests and Gate 8 checks fail closed on direct demonstration-source imports.
+
+This formalization preserves the demonstration boundary while allowing V29 promotion and later gates to operate from package-owned commercial source.
+
 ## V29 canonical domain model
 
 The V29 domain model extends V28 operationally:

BITCODE_SPEC_V29_DELTA.md

@@ -169,6 +169,16 @@ Closure acceptance:
 
 Gate 8 owns cleanup of freshly ported demonstration-origin internals into package-native APIs, no demonstration runtime imports, durable package tests, and updated internal/public documentation.
 
+Closure acceptance:
+
+- `@bitcode/protocol` exports active/draft canon posture, spec-family checks, canonical-input checks, canon-posture-drift checks, and canonical proven-generation helpers through the package index and type declarations.
+- Root scripts for spec quality, spec-family validation, canonical-input validation, canon-posture drift, pre-commit posture, and proven generation import those helpers from the protocol package instead of `protocol-demonstration/src/*`.
+- Commercial/runtime source scans fail closed on direct imports from standalone demonstration source.
+- The protocol package records active V28 / draft V29 posture while V29 is being developed.
+- Protocol package tests prove exported helpers, posture, provenance-helper availability, repository-revision deposit behavior, and direct demonstration-source import boundaries.
+- Gate-quality CI runs the Gate 8 checker, protocol package typecheck/test, and the UAPI commercial protocol boundary test.
+- V29 SPEC, DELTA, NOTES, PARITY, protocol package README, package scripts, and gate-quality workflow name the Gate 8 formalization boundary.
+
 ### Gate 9: Terminal UX Quality And Browser Proof
 
 Gate 9 owns accessibility, responsive layout, copy/prose clarity, empty/loading/blocked/failed states, Playwright coverage, and visual/browser verification for the complete Terminal transaction cockpit.

BITCODE_SPEC_V29_NOTES.md

@@ -188,6 +188,27 @@ Gate 7 completion condition:
 - Focused BTD, API, MCP, ChatGPT App, pipeline-hosts, and UAPI tests cover the authority primitive and interface surfaces.
 - Spec, delta, notes, parity, Terminal README, package scripts, and gate-quality workflow name the Gate 7 closure surface.
 
+## Gate 8 working notes
+
+Gate 8 is a commercial-source boundary cleanup gate.
+Earlier versions intentionally kept some proof and canon helpers close to the standalone demonstration so the minimal witness could remain easy to audit.
+V29 keeps that witness, but the commercial repository now needs package-native imports for every helper used by scripts, workflows, Terminal, APIs, and promotion checks.
+
+Accepted Gate 8 posture:
+
+- `@bitcode/protocol` is the package boundary for canonical posture, spec-family, canonical-input, canon-posture-drift, and proven-generation helpers.
+- `protocol-demonstration/` remains executable as a standalone minimal witness and may remain cited in proof inventories.
+- Commercial/runtime code and root scripts must not import from `protocol-demonstration/src/*`.
+- The protocol package posture must say active V28 and draft V29 until promotion.
+- The protocol package tests own the durable import-boundary scan so future gates cannot silently regress into demonstration runtime imports.
+- Gate-quality CI must run protocol package typecheck/test, the Gate 8 checker, and the UAPI commercial protocol boundary test.
+
+Gate 8 completion condition:
+
+- `pnpm run check:v29-gate8` passes.
+- Protocol package tests pass.
+- The spec family, package README, root scripts, and CI all name and enforce the package-native boundary.
+
 ## Later-version boundaries
 
 - V30 remains reserved for Protocol/BTD hardening that is not necessary to close Terminal transaction depth.

BITCODE_SPEC_V29_PARITY_MATRIX.md

@@ -55,7 +55,7 @@ No `_legacy/` source is active source truth.
 | AssetPack disclosure rights | Gate 5 | `asset-pack-disclosure.ts`, AssetPack postprocess, sandbox harness, BTD access tests, Terminal disclosure review UI, Gate 5 checker | drafted | Source-safe preview and paid unlock are proven without protected-source leakage. |
 | Settlement reconciliation repair | Gate 6 | BTD journal/reconciliation, Supabase readback, sandbox harness settlement evidence, Terminal repair UI, Gate 6 checker | drafted | Ledger, database, and metaphysical state drift is classified, proof-rooted, repair-actioned, and visible. |
 | Organization permission authority | Gate 7 | `packages/btd/src/authority.ts`, BTD/API/MCP/ChatGPT App tests, sandbox harness authority evidence, Terminal Authority section, Gate 7 checker | drafted | Registry-derived roles, holdings, read-license authority, settlement, confirmation, and interface admission govern actions. |
-| Commercial formalization | Gate 8 | packages/protocol, package tests, import scans, docs | pending | Demonstration-origin commercial internals are package-native and no runtime demo imports remain. |
+| Commercial formalization | Gate 8 | `packages/protocol/src/index.js`, `packages/protocol/src/canon-posture.js`, root scripts, protocol package tests, import scans, docs, Gate 8 checker | drafted | Demonstration-origin commercial internals are package-native and no direct demonstration-source imports remain in commercial/runtime sources. |
 | Terminal UX quality | Gate 9 | Playwright/Jest/a11y/responsive/browser QA | pending | Complete transaction cockpit is usable by default and inspectable in detail. |
 | Promotion readiness | Gate 10 | promotion workflow, `.bitcode/v29-*`, `BITCODE_SPEC_V29_PROVEN.md` | pending | `version/v29` can promote to `main` only after all V29 checks pass. |
 
@@ -72,7 +72,8 @@ No `_legacy/` source is active source truth.
 | Gate 4 Reading observability | `pnpm run check:v29-gate4` proves contract-aware Reading stream telemetry and Terminal rendering | drafted |
 | Gate 5 AssetPack disclosure | `pnpm run check:v29-gate5` proves source-safe disclosure review, leakage detection, Terminal preview rendering, and PR title enforcement | drafted |
 | Gate 7 organization authority | `pnpm run check:v29-gate7` proves shared org/interface authority across BTD, API, MCP, ChatGPT App, harness, and Terminal | drafted |
-| Product implementation gates | Gates 8-9 close remaining Terminal transaction depth with tests and docs | pending |
+| Gate 8 commercial formalization | `pnpm run check:v29-gate8` proves package-native protocol exports, V28/V29 posture, script import cleanup, docs, tests, and CI wiring | drafted |
+| Product implementation gates | Gate 9 closes remaining Terminal transaction UX quality with browser proof | pending |
 | Promotion gate | Gate 10 closes generated proof and promotion automation | pending |
 
 ## Gate 1 Parity
@@ -242,3 +243,32 @@ Gate 7 completion condition:
 - Gate-quality CI invokes the Gate 7 checker and focused tests.
 - Gate 7 does not add broad enterprise RBAC administration beyond Terminal transaction authority; later versions may deepen team policy authoring.
 - Gate 7 does not reveal protected source before settlement and does not add versioned API routes or source identifiers.
+
+## Gate 8 Parity
+
+Gate 8 closes the demonstration-origin commercial formalization slice by moving gate-critical helpers behind the protocol package boundary.
+
+Accepted surfaces:
+
+- `packages/protocol/src/index.js` exports canonical posture, spec-family validation, canonical-input validation, canon-posture-drift validation, generated artifact builders, and canonical proven-generation helpers.
+- `packages/protocol/src/index.d.ts` declares the same package-native API surface for consumers that type-check against the protocol package.
+- `packages/protocol/src/canon-posture.js` declares active V28 and draft V29 while V29 gates are in progress.
+- Root scripts for spec-family checks, canonical-input checks, canon-posture drift, spec quality, pre-commit posture, and proven generation import through the protocol package source boundary.
+- `packages/protocol/test/protocol-package-boundary.test.js` proves package exports, posture, provenance-helper availability, repository-revision deposit behavior, and direct demonstration-source import boundaries.
+- `uapi/tests/protocolCommercialBoundary.test.ts` remains the commercial application boundary scan proving UAPI depends on `@bitcode/protocol` and not the standalone demonstration package.
+- `.github/workflows/bitcode-gate-quality.yml` runs the Gate 8 checker, protocol package typecheck/test, and the commercial protocol boundary test.
+
+Accepted boundaries:
+
+- Gate 8 does not delete the standalone protocol demonstration.
+- Gate 8 does not forbid generated proof inventories or historical documentation from citing `protocol-demonstration/` as evidence.
+- Gate 8 forbids direct imports from standalone demonstration source in commercial/runtime source and root scripts.
+- Gate 8 does not promote `BITCODE_SPEC.txt` to V29.
+- Gate 8 does not add versioned API routes or source identifiers.
+
+Gate 8 completion condition:
+
+- `pnpm run check:v29-gate8` passes.
+- Focused protocol package typecheck/test and the UAPI commercial protocol boundary test pass.
+- V29 SPEC, DELTA, NOTES, PARITY, protocol package README, package scripts, and gate-quality workflow name the formalized package-native boundary.
+- Root scripts use protocol package exports for canonical helpers and do not directly import `protocol-demonstration/src/*`.

package.json

@@ -51,6 +51,7 @@
     "check:v29-gate5": "node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs",
     "check:v29-gate6": "node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs",
     "check:v29-gate7": "node scripts/check-v29-gate7-organization-permission-authority.mjs",
+    "check:v29-gate8": "node scripts/check-v29-gate8-demonstration-origin-formalization.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/protocol/README.md

@@ -2,12 +2,24 @@
 
 Formal Bitcode protocol package for commercial source.
 
-V28 starts the separation between the deterministic `protocol-demonstration`
-reference and commercial runtime imports. Commercial surfaces should import
-protocol state, API context, and protocol primitives from this package rather
-than importing the standalone demonstration package.
-
-Some implementation internals are still freshly ported from the demonstration
-and intentionally retain source proximity for parity. V29 must continue
-commercializing those internals into narrower packages and cleaner module
-boundaries.
+V29 Gate 8 makes this package the package-native boundary for canonical helpers
+that were originally ported from the standalone `protocol-demonstration`
+witness. Commercial scripts, API/runtime code, and workflow checks must import
+canon posture, spec-family checks, canonical-input checks, canon-drift checks,
+and proven-generation helpers from `@bitcode/protocol` or
+`packages/protocol/src/index.js`.
+
+They must not import `protocol-demonstration/src/*`. The demonstration remains
+a standalone minimal witness and may still be executed or cited by proof
+inventories, but it is not a commercial runtime implementation dependency.
+
+Current exported commercial helpers include:
+
+- active/draft canon posture (`V28` active, `V29` draft during V29 work);
+- spec-family and canonical-input validation helpers;
+- canon-posture drift reporting;
+- canonical proven-generation helpers;
+- the package app/server context used by commercial interfaces.
+
+The package boundary is enforced by `packages/protocol` tests, the UAPI
+commercial protocol boundary test, and `check:v29-gate8`.

packages/protocol/src/canon-posture.js

@@ -1,7 +1,7 @@
 // @ts-check
 
-export const ACTIVE_CANON_VERSION = 'V27';
-export const DRAFT_TARGET_VERSION = 'V28';
+export const ACTIVE_CANON_VERSION = 'V28';
+export const DRAFT_TARGET_VERSION = 'V29';
 export const CURRENT_CANON_OPERATOR_LABEL = `${ACTIVE_CANON_VERSION} active canon / ${DRAFT_TARGET_VERSION} system draft`;
 
 /**

packages/protocol/src/canonical/proven-generator.js

@@ -49,7 +49,7 @@ const COLLECTED_PROVEN_RUN_CACHE = new Map();
 const BASE_PROVEN_DATA_CACHE = new Map();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, '../../..');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
 
 /**
  * @param {string} version

packages/protocol/src/canonical/v21-specifying.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-export const DEFAULT_V21_SPECIFYING_REPO_ROOT = path.resolve(__dirname, '../../..');
+export const DEFAULT_V21_SPECIFYING_REPO_ROOT = path.resolve(__dirname, '../../../..');
 
 export const COMMON_REQUIRED_SPEC_SECTIONS = [
   'Status',