wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -359,6 +359,69 @@ Acceptance criteria:
   `frontier/*` or mock repository leakage, and no ledger/database drift for any
   finality that Terminal claims.
 
+#### Pipeline host runtime environment for Read/Fit QA
+
+V28 now admits a lightweight deployment harness because the first commercial
+Read/Fit result cannot be reviewed from local posture rows alone.
+The harness is not the full V34 distributed deployment program; it is the
+minimum real host contract needed to prove that AssetPack pipeline execution,
+agent/prompt/tool context, artifact export, and telemetry readback are running
+before Terminal may classify a Read as `worthy_fit` or `no_worthy_fit`.
+
+The V28 QA host is Vercel Sandbox.
+The active host capability contract is:
+
+- isolated Firecracker microVM execution on Amazon Linux 2023;
+- default working directory `/vercel/sandbox`;
+- stable documented runtimes `node24`, `node22`, and `python3.13`, with
+  `node24` as the default Bitcode harness runtime;
+- `vercel-sandbox` user with sudo available for setup;
+- ephemeral filesystem, requiring evidence export before sandbox stop;
+- command execution, command log collection, file upload/download, exposed
+  ports when explicitly requested, snapshots, and egress network policies;
+- authentication through Vercel OIDC tokens from a linked project or through
+  explicit access-token variables for non-Vercel environments.
+
+The V28 pipeline harness must write a manifest before execution containing:
+
+- Read id and Read text;
+- Deposit id and optional deposited AssetPack id;
+- repository full name, branch, and commit;
+- host capability summary;
+- expected stages: deposit search, candidate ranking, Read comprehension,
+  AssetPack synthesis, validation, Finish, and telemetry readback;
+- expected SQL evidence surfaces: `executions`, `execution_events`,
+  `pipeline_runs`, `run_jobs`, `stream_logs`, `phase_executions`,
+  `deliverable_pipeline_runs`, `deliverable_pipeline_phase_delegations`,
+  `deliverable_pipeline_agent_steps`, `deliverable_pipeline_generations`, and
+  `deliverable_pipeline_tool_executions`;
+- admissible result states `worthy_fit`, `no_worthy_fit`, and
+  `blocked_readiness`;
+- redacted command-environment names only, never secret values.
+
+The harness has two admissible modes:
+
+- `host_smoke`: proves Vercel Sandbox creation, command execution, artifact
+  export, and stop/cleanup. This mode always produces `blocked_readiness`
+  because it does not invoke the AssetPack pipeline.
+- `asset_pack_pipeline`: clones or mounts the selected repository revision,
+  installs workspace dependencies, invokes the AssetPack pipeline entrypoint,
+  exports evidence and telemetry artifacts, and relies on SQL readback before
+  any commercial result is accepted.
+
+Read/Fit result review remains fail-closed:
+
+- `worthy_fit` requires source-bound pipeline output plus event, phase, agent,
+  generation/tool, proof/readiness, and ledger/database readback evidence.
+- `no_worthy_fit` requires source-bound rejection reasons from the pipeline,
+  not absence of UI posture alone.
+- `blocked_readiness` is mandatory when source materialization, model/tool
+  credentials, telemetry persistence, BTC fee, ledger anchor, settlement,
+  AssetPack range projection, or finality readback is unavailable.
+- secrets for wallets, GitHub, model providers, Supabase service roles, or
+  other systems may be passed into a sandbox only by explicit allowlist or
+  brokered network policy; routine QA artifacts must show only redacted names.
+
 ### Gate 4: Terminal AssetPack Range Detail
 
 Purpose:

BITCODE_V28_QA.md

@@ -896,6 +896,18 @@ repository already deposited, but Terminal code and operator flow must remain
 fully generic across repository owner, repository, branch, commit, signer, and
 source type.
 
+First-run execution boundary:
+
+- A recorded Fit posture is not yet a commercial worthy Fit unless the deployed
+  pipeline has actually executed and written its evidence.
+- Until real pipeline execution exists, the honest positive-control result is
+  `blocked_readiness`: Deposit, Read admission, source binding, and Fit posture
+  are reviewable, but AssetPack range, ledger anchor, BTC fee, settlement, and
+  finality readback must not be claimed.
+- `worthy_fit` and `no_worthy_fit` become commercially admissible only when the
+  result is derived from pipeline execution evidence rather than local posture
+  rows alone.
+
 Starting condition:
 
 - Pass 2A Deposit submission has succeeded.
@@ -971,7 +983,9 @@ Manual steps:
    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`.
+9. Run saved query `v28_qa_terminal_06_read_fit_quality_after_read`. Before the
+   first deployed pipeline execution, expect `latest_fit_result_state` to be
+   `blocked_readiness`, not `worthy_fit`.
 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
@@ -982,12 +996,17 @@ 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.
+- Query 06 also reports `latest_fit_result_state` as one of `worthy_fit`,
+  `no_worthy_fit`, or `blocked_readiness`. Before deployed pipeline execution is
+  wired, the accepted result is `blocked_readiness`.
 - 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.
+- Real `worthy_fit` or `no_worthy_fit` classification is backed by deployed
+  pipeline execution rows, events, logs, and result evidence.
 - 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.
@@ -1005,6 +1024,105 @@ Commercial blockers:
 - Any staging-testnet Read/Fit row contains `frontier/*`, mock provider, or
   protocol-demo source as if it were live deposited source.
 
+### Pass 2C: Vercel Sandbox Pipeline Harness QA
+
+Purpose:
+Prove that the Read/Fit path can run inside the first lightweight deployment
+host before QA treats a Fit result as commercially meaningful. This pass checks
+the harness itself: sandbox creation, command execution, manifest binding,
+artifact export, telemetry, database persistence, and cleanup.
+
+Prerequisites:
+
+- Vercel project is linked and local OIDC credentials are current:
+  `vercel link && vercel env pull`.
+- `@vercel/sandbox` is installed in the workspace running the harness.
+- Pass 2B has produced a Deposit, Read, and Fit posture for the same repository,
+  branch, and commit.
+- No wallet, GitHub, Supabase, model, or provider secret is passed into the
+  sandbox unless it is explicitly named in `BITCODE_SANDBOX_ENV_KEYS` for this
+  run and the network policy is understood.
+
+Host smoke command:
+
+```bash
+BITCODE_RUN_VERCEL_SANDBOX_HARNESS=1 \
+BITCODE_SANDBOX_MODE=host_smoke \
+BITCODE_SANDBOX_REPOSITORY=engineeredsoftware/ENGI \
+BITCODE_SANDBOX_SOURCE_BRANCH=main \
+BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+pnpm run qa:pipeline-harness:sandbox
+```
+
+Expected host smoke result:
+
+- The script creates a Vercel Sandbox, runs `node --version`, writes a harness
+  manifest, writes `evidence.json` and `telemetry.jsonl`, reads both artifacts
+  back, and stops the sandbox unless `BITCODE_SANDBOX_LEAVE_RUNNING=1`.
+- The returned result state is `blocked_readiness`; this is correct because
+  host smoke proves only the host lifecycle.
+
+Repository pipeline command:
+
+```bash
+BITCODE_RUN_VERCEL_SANDBOX_HARNESS=1 \
+BITCODE_SANDBOX_MODE=asset_pack_pipeline \
+BITCODE_SANDBOX_SOURCE_GIT_URL=https://github.com/engineeredsoftware/ENGI.git \
+BITCODE_SANDBOX_SOURCE_BRANCH=main \
+BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+BITCODE_SANDBOX_SOURCE_REVISION=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+pnpm run qa:pipeline-harness:sandbox
+```
+
+If database streaming is intentionally being tested, pass only the required
+keys by name:
+
+```bash
+BITCODE_PIPELINE_STREAM_TO_DATABASE=1 \
+BITCODE_PIPELINE_STRUCTURED_DB=1 \
+BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY
+```
+
+After either harness run:
+
+1. Save the command JSON summary, sandbox id, command exit codes, and artifact
+   presence fields.
+2. Run saved query
+   `supabase/queries/v28_qa_terminal_07_pipeline_harness_after_fit.sql`.
+3. Rerun `v28_qa_terminal_06_read_fit_quality_after_read` and
+   `v28_qa_terminal_03_btd_ledger_after_terminal`.
+4. Capture Vercel Sandbox dashboard/log evidence for the same timestamps.
+
+Pass criteria:
+
+- Host smoke returns exported evidence and telemetry artifacts and stops the
+  sandbox cleanly.
+- The repository pipeline run either produces source-bound AssetPack pipeline
+  evidence or an explicit `blocked_readiness` error artifact.
+- Query 07 reports `pipeline_harness_ready_for_result_review`, or reports a
+  precise blocker/warning that Terminal also shows as blocked-readiness.
+- Query 07 shows recent pipeline runtime evidence in at least the base runtime
+  surfaces (`pipeline_runs` or `deliverable_pipeline_runs`) plus event/log
+  telemetry (`execution_events` or `stream_logs`).
+- Phase and agent-step telemetry appear before any result can be promoted past
+  blocked-readiness.
+- Generation/tool rows appear before any model/tool-mediated Fit quality claim
+  can be accepted.
+- Query 03 still shows no AssetPack range, BTC fee, ledger anchor, settlement,
+  or finality claim without matching projection rows.
+
+Commercial blockers:
+
+- The harness cannot create a sandbox or authenticate with Vercel.
+- The harness runs but cannot export evidence artifacts before sandbox stop.
+- A `worthy_fit` or `no_worthy_fit` result is claimed without query 07 runtime
+  evidence.
+- Provider tokens, wallet signatures, GitHub credentials, model keys, or
+  Supabase service-role secrets appear unredacted in command output, artifacts,
+  browser telemetry, or routine QA query rows.
+- Terminal enables settlement, minting, branch materialization, BTC fee
+  broadcast, or ledger finality from a host smoke result.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

package.json

@@ -47,7 +47,7 @@
     "audit:stories": "node scripts/audit_stories.js",
     "check:prompts": "node scripts/generate_prompt_inventory.js --ci",
     "lint": "eslint packages --ext .ts,.tsx",
-    "typecheck:core": "pnpm -C packages/execution-generics run typecheck && pnpm -C packages/pipelines-generics run typecheck && pnpm -C packages/agent-generics run typecheck && pnpm -C packages/streams run typecheck",
+    "typecheck:core": "pnpm -C packages/execution-generics run typecheck && pnpm -C packages/pipelines-generics run typecheck && pnpm -C packages/pipeline-hosts run typecheck && pnpm -C packages/agent-generics run typecheck && pnpm -C packages/streams run typecheck",
     "lint:core": "pnpm exec eslint packages/execution-generics packages/pipelines-generics packages/agent-generics/src packages/streams/src --ext .ts,.tsx",
     "lint:agents": "eslint packages/generic-agents packages/pipelines/asset-pack/src/agents --ext .ts",
     "prelint:agents": "pnpm run build:eslint-plugin",
@@ -73,6 +73,7 @@
     "db:squash": "bash scripts/db-squash.sh",
     "render:prompts": "pnpm -C packages/pipelines/asset-pack exec ts-node --transpile-only scripts/render-prompts.ts",
     "render:prompts:all": "pnpm -C packages/pipelines/asset-pack exec ts-node --transpile-only scripts/render-prompts.ts --scope=all",
+    "qa:pipeline-harness:sandbox": "pnpm -C packages/pipeline-hosts run qa:asset-pack:sandbox",
     "mcp:inspect": "pnpm exec mcp-inspector --stdio-command ./scripts/start-bitcode-mcp.sh"
   },
   "dependencies": {

packages/pipeline-hosts/README.md

@@ -0,0 +1,68 @@
+# `@bitcode/pipeline-hosts`
+
+This package owns host-runtime adapters for Bitcode pipeline QA. The first
+adapter is the Vercel Sandbox harness used to prove that Read/Fit and
+AssetPack pipeline work is running in an isolated host, emitting artifacts, and
+leaving enough telemetry for SQL readback.
+
+## Vercel Sandbox Host Capabilities
+
+- Firecracker microVM isolation on Amazon Linux 2023.
+- Default working directory: `/vercel/sandbox`.
+- Default runtime: `node24`; stable documented runtime options are `node24`,
+  `node22`, and `python3.13`.
+- The sandbox user is `vercel-sandbox` and can use `sudo`.
+- Filesystem state is ephemeral. Evidence must be exported before stop, then
+  persisted to Bitcode storage or database projections.
+- Command output, file upload/download, exposed ports, network policies, and
+  snapshots are part of the host contract.
+- Auth is through Vercel OIDC tokens from `vercel link && vercel env pull`, or
+  through access-token variables for non-Vercel hosts.
+
+## Harness Modes
+
+`host_smoke` verifies the host lifecycle only. It creates a sandbox, writes a
+manifest and runner, executes Node, writes `evidence.json` and
+`telemetry.jsonl`, exports them, then stops the sandbox. The result is always
+`blocked_readiness` because the AssetPack pipeline was not invoked.
+
+`asset_pack_pipeline` clones or mounts a repository source, installs workspace
+dependencies, and runs the AssetPack pipeline runner in the sandbox. It still
+requires SQL readback before any `worthy_fit`, settlement, range, BTC fee, or
+ledger finality claim is commercially admissible.
+
+## Live QA
+
+Link a Vercel project and pull local OIDC credentials:
+
+```bash
+vercel link
+vercel env pull
+```
+
+Run the low-cost host smoke:
+
+```bash
+BITCODE_RUN_VERCEL_SANDBOX_HARNESS=1 \
+BITCODE_SANDBOX_MODE=host_smoke \
+BITCODE_SANDBOX_REPOSITORY=engineeredsoftware/ENGI \
+BITCODE_SANDBOX_SOURCE_BRANCH=main \
+BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+pnpm -C packages/pipeline-hosts run qa:asset-pack:sandbox
+```
+
+Run the repository pipeline path after source access and credentials are ready:
+
+```bash
+BITCODE_RUN_VERCEL_SANDBOX_HARNESS=1 \
+BITCODE_SANDBOX_MODE=asset_pack_pipeline \
+BITCODE_SANDBOX_SOURCE_GIT_URL=https://github.com/engineeredsoftware/ENGI.git \
+BITCODE_SANDBOX_SOURCE_BRANCH=main \
+BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+BITCODE_SANDBOX_SOURCE_REVISION=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
+pnpm -C packages/pipeline-hosts run qa:asset-pack:sandbox
+```
+
+Only pass secrets through `BITCODE_SANDBOX_ENV_KEYS` when the sandbox code path
+is trusted and its network policy is understood. Prefer credential brokering or
+strict allowlists before running untrusted generated code.

packages/pipeline-hosts/jest.config.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  preset: 'ts-jest/presets/js-with-ts',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  roots: ['<rootDir>'],
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+  globals: {
+    'ts-jest': {
+      tsconfig: '<rootDir>/../../tsconfig.json',
+      diagnostics: false,
+    },
+  },
+};

packages/pipeline-hosts/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bitcode/pipeline-hosts",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Bitcode pipeline host adapters and Vercel Sandbox harnesses.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "pnpm exec jest --config jest.config.cjs --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "qa:asset-pack:sandbox": "ts-node --transpile-only src/dev/run-asset-pack-sandbox-harness.ts"
+  },
+  "dependencies": {
+    "@vercel/sandbox": "^1.10.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^25.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "10.9.2",
+    "typescript": "^5.0.0"
+  }
+}