wip v28

Author: geraldarthurdavis

.env.example

@@ -11,6 +11,9 @@ BITCODE_DEBUG_STOP_AFTER_PLAN=false
 BITCODE_EXECUTION_DEBUG=false
 BITCODE_LLM_MODEL=<default Bitcode LLM model>
 BITCODE_LLM_PROVIDER=<default Bitcode LLM provider>
+BITCODE_ASSET_PACK_REAL_INFERENCE=false
+BITCODE_ENABLE_PIPELINE_HARNESS_API=false
+BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000
 BITCODE_LOG_FULL_PROMPTS=false
 BITCODE_LOG_FULL_PROMPTS_CORRELATION_IDS=
 BITCODE_LOG_FULL_TRACES=false

BITCODE_SPEC_V28.md

@@ -360,7 +360,9 @@ Acceptance criteria:
   rows are re-embedded and the matching function/schema still agree;
 - the Fit result must expose ranking quality, rejection reasons, proof roots,
   dedupe/materialization roots where available, and finality/readiness status;
-- AssetPack synthesis must be protocol-specified and deterministic; if source
+- AssetPack synthesis must be protocol-specified and reproducibly evidenced;
+  deterministic bring-up branches are regression scaffolds, while
+  staging-testnet commercial QA must run model-backed PTRR inference. If source
   materialization, settlement, BTC fee broadcast, ledger anchor, or BTD range
   issuance is not live, the result must state that blocker rather than imply
   delivery or minting;
@@ -385,8 +387,8 @@ 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;
+- stable documented runtimes `node26`, `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
@@ -441,6 +443,12 @@ Read/Fit result review remains fail-closed:
 - `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.
+- staging-testnet commercial Read/Fit QA must run model-backed inference.
+  `BITCODE_ASSET_PACK_REAL_INFERENCE=1` is the deployment-level switch for the
+  AssetPack pipeline; it forces every PTRR-capable setup, discovery, synthesis,
+  validation, and Finish agent off deterministic bring-up branches. A run with
+  any omitted per-agent `*_USE_PTRR` flag is not an acceptable staging posture
+  unless the global real-inference flag is present.
 - manifest-only Deposit supply can satisfy candidate recall but cannot produce
   `worthy_fit` unless proof and measurement posture are explicitly visible to
   the pipeline input and the downstream readback queries confirm them.
@@ -463,6 +471,10 @@ Read/Fit result review remains fail-closed:
   from credential posture, with OpenAI accepted when `OPENAI_API_KEY` is the
   only model credential present. A provider pin without a matching forwarded
   credential is not an admissible reason to require that provider.
+- the deployed staging trigger may use Vercel's automatic Sandbox OIDC, but it
+  still needs a server-side model credential such as `OPENAI_API_KEY`, real
+  Supabase admin/service-role credentials for telemetry persistence, and a
+  runtime budget that is shorter than the enclosing Vercel Function window.
 
 ### Gate 4: Terminal AssetPack Range Detail
 

BITCODE_V28_QA.md

@@ -710,12 +710,18 @@ NEXT_PUBLIC_MCP_UPGRADES=true
 NEXT_PUBLIC_BITCODE_QA_VERBOSE=true
 BITCODE_QA_VERBOSE=true
 
-OPENAI_API_KEY=<OpenAI key for non-mocked Terminal/protocol synthesis if enabled>
+BITCODE_ENABLE_PIPELINE_HARNESS_API=1
+BITCODE_ASSET_PACK_REAL_INFERENCE=1
+BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000
+OPENAI_API_KEY=<OpenAI key for non-mocked Terminal/protocol synthesis>
+BITCODE_LLM_PROVIDER=openai
+BITCODE_LLM_MODEL=<optional pinned OpenAI generation model>
 SENTRY_DSN=<optional V28 alert sink; absence must remain readable blocked readiness>
 ```
 
 Do not set mock flags true on this deployment.
 Do not point the Supabase custom provider token/userinfo URLs at localhost; Supabase cloud must be able to call the deployed Bitcode origin.
+Do not deploy staging-testnet Read/Fit QA with `BITCODE_ASSET_PACK_REAL_INFERENCE` unset or false. Per-agent `*_USE_PTRR` flags are only diagnostic overrides; the staging posture is the global real-inference flag plus a real server-side model credential.
 
 ## Live Deployment Pass: First-Run Onboarding To Terminal Readiness
 
@@ -1145,8 +1151,10 @@ evidence must remain QA-only, must report
 and must not be used for source-revision settlement, ledger finality, or a
 commercial `worthy_fit` claim.
 If the heavyweight pipeline exceeds the staging function window, set
-`BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` below that window; the expected result
-is a `PipelineHarnessTimeoutError` artifact with the last execution and stream
+`BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` below that window. The deployed
+streaming route declares an 800 second ceiling, so staging should start with
+`BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000`; the expected timeout result is
+a `PipelineHarnessTimeoutError` artifact with the last execution and stream
 events, not a missing artifact.
 
 Omit `BITCODE_SANDBOX_DEPOSIT_HAS_PROOF` and
@@ -1160,7 +1168,8 @@ 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
+BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
+BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY,BITCODE_ASSET_PACK_REAL_INFERENCE,BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS
 ```
 
 These Supabase values must be real staging credentials. Placeholder hosts such
@@ -1169,6 +1178,9 @@ sandbox can execute but every stream-event insert fails with transport errors.
 
 On Vercel staging/preview, prefer the deployed streaming trigger because it
 uses Vercel automatic OIDC instead of a local Vercel token:
+the deployed route preflight-fails when `BITCODE_ASSET_PACK_REAL_INFERENCE` is
+unset, when `OPENAI_API_KEY` is missing, or when
+`BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` exceeds `600000`.
 
 ```bash
 curl -N "$BITCODE_UAPI_URL/api/pipeline-harness/asset-pack" \
@@ -1238,6 +1250,9 @@ Pass criteria:
   blocked-readiness.
 - Generation/tool rows appear before any model/tool-mediated Fit quality claim
   can be accepted.
+- For the staging-testnet commercial pass, generation rows must be non-zero
+  because `BITCODE_ASSET_PACK_REAL_INFERENCE=1` is required. A completed run
+  with zero generation rows is only deterministic bring-up evidence.
 - Parsed/cast generation output is stored when a ThriceifiedGeneration parser
   runs, so operators can compare raw model text with typed Fit/search evidence.
 - Query 03 still shows no AssetPack range, BTC fee, ledger anchor, settlement,
@@ -1276,12 +1291,13 @@ Observed staging-testnet harness evidence on 2026-05-17:
   `deliverable_pipeline_runs.status='completed'`, 603 deliverable pipeline
   events, 12 completed phase rows, 40 completed agent-step rows, and no running
   phase or agent rows for the run.
-- The default harness path uses deterministic setup/discovery/synthesis/
-  validation/finish agents unless a phase-specific `*_USE_PTRR=1` flag is set;
-  therefore this observed run had zero generation rows and zero tool execution
-  rows. A model/tool-mediated commercial Fit claim still requires generation
-  and tool rows with prompt, raw response, parsed/cast output, provider/model,
-  usage, and phase/agent/step correlation.
+- The default harness path previously used deterministic setup/discovery/
+  synthesis/validation/finish branches unless a phase-specific `*_USE_PTRR=1`
+  flag was set; therefore this observed run had zero generation rows and zero
+  tool execution rows. The V28 staging posture is now
+  `BITCODE_ASSET_PACK_REAL_INFERENCE=1`, which forces every PTRR-capable
+  AssetPack branch to produce model-generation telemetry or fail with explicit
+  blocked-readiness evidence.
 - Ledger readback correctly showed zero BTD range, BTC fee, journal, anchor, and
   crypto telemetry rows, and `btd_supply_state.total_minted=0`, because source
   overlay QA evidence cannot mint BTD, claim BTC fee settlement, or anchor

packages/pipeline-hosts/README.md

@@ -9,8 +9,8 @@ leaving enough telemetry for SQL readback.
 
 - Firecracker microVM isolation on Amazon Linux 2023.
 - Default working directory: `/vercel/sandbox`.
-- Default runtime: `node24`; documented runtime options are `node24`,
-  `node22`, and `python3.13`.
+- Default runtime: `node24`; documented runtime options are `node26`,
+  `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.
@@ -69,13 +69,28 @@ trusted command environment. For local Vercel Sandbox creation, either pull
 token tuple `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. Deployed
 Vercel code should use automatic OIDC rather than storing a Vercel token when
 possible.
+Staging-testnet commercial Read/Fit QA must also set
+`BITCODE_ASSET_PACK_REAL_INFERENCE=1`. That single flag forces every
+PTRR-capable AssetPack setup, discovery, synthesis, validation, and finish
+agent off the deterministic bring-up path. The phase-specific
+`BITCODE_ASSET_PACK_*_USE_PTRR=1` flags remain available for local bisection,
+but they are not sufficient as a staging posture because a missed flag silently
+turns part of the run back into deterministic evidence.
 `BITCODE_LLM_PROVIDER` and `BITCODE_LLM_MODEL` may pin the generation model.
 When they are absent, the commercial runtime chooses OpenAI if `OPENAI_API_KEY`
 is the only model credential present. A provider pin is forwarded only when the
 matching provider credential is also forwarded; stale pins without credentials
 are stripped so staging does not silently require an unavailable model service.
 Database streaming requires a real Supabase URL and service-role key; placeholder
 `.env.local` values fail preflight before a sandbox is created.
+The deployed streaming route declares an 800 second Vercel Function window; keep
+`BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS` at or below `600000` there so the
+route still has time to collect and stream the blocked-readiness artifact if the
+sandbox budget expires. Local CLI harness runs can use a larger sandbox budget
+when the calling process is not the limiting host. On deployed/runtime
+production, the route preflight-fails without
+`BITCODE_ASSET_PACK_REAL_INFERENCE=1`, without `OPENAI_API_KEY`, or with a
+larger harness runtime budget.
 
 ## Live QA
 
@@ -108,6 +123,8 @@ BITCODE_SANDBOX_SOURCE_COMMIT=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
 BITCODE_SANDBOX_SOURCE_REVISION=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
 BITCODE_SANDBOX_DEPOSIT_HAS_PROOF=1 \
 BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT=1 \
+BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
+BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000 \
 pnpm -C packages/pipeline-hosts run qa:asset-pack:sandbox
 ```
 

packages/pipeline-hosts/src/dev/run-asset-pack-sandbox-harness.ts

@@ -28,6 +28,16 @@ const TRUSTED_SANDBOX_ENV_KEYS = [
   'BITCODE_PIPELINE_BTC_NETWORK',
   'BITCODE_LLM_PROVIDER',
   'BITCODE_LLM_MODEL',
+  'BITCODE_ASSET_PACK_REAL_INFERENCE',
+  'BITCODE_ASSET_PACK_SETUP_PLAN_USE_PTRR',
+  'BITCODE_ASSET_PACK_COMPREHEND_READ_USE_PTRR',
+  'BITCODE_ASSET_PACK_DANGER_WALL_USE_PTRR',
+  'BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR',
+  'BITCODE_ASSET_PACK_SYNTHESIS_USE_PTRR',
+  'BITCODE_ASSET_PACK_VALIDATION_USE_PTRR',
+  'BITCODE_ASSET_PACK_READY_TO_INSTRUCT_USE_PTRR',
+  'BITCODE_ASSET_PACK_VALIDATION_READY_TO_FINISH_USE_PTRR',
+  'BITCODE_ASSET_PACK_FINISH_DELIVER_USE_PTRR',
   'BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS',
 ] as const;
 

packages/pipelines/asset-pack/src/__tests__/runtime-inference-policy.test.ts

@@ -0,0 +1,36 @@
+import {
+  isAssetPackRealInferenceEnabled,
+  shouldUseAssetPackPtrr,
+  shouldUseAssetPackPtrrForAgent,
+} from '../runtime-inference-policy';
+
+describe('AssetPack runtime inference policy', () => {
+  it('keeps deterministic branches disabled by default', () => {
+    const env = {} as NodeJS.ProcessEnv;
+
+    expect(isAssetPackRealInferenceEnabled(env)).toBe(false);
+    expect(shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_SYNTHESIS_USE_PTRR', env)).toBe(false);
+    expect(shouldUseAssetPackPtrrForAgent('BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR', 'plan-implementation', env)).toBe(false);
+  });
+
+  it('enables all PTRR-capable branches through the commercial real-inference flag', () => {
+    const env = { BITCODE_ASSET_PACK_REAL_INFERENCE: '1' } as NodeJS.ProcessEnv;
+
+    expect(isAssetPackRealInferenceEnabled(env)).toBe(true);
+    expect(shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_SYNTHESIS_USE_PTRR', env)).toBe(true);
+    expect(shouldUseAssetPackPtrrForAgent('BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR', 'plan-implementation', env)).toBe(true);
+  });
+
+  it('keeps existing phase and per-agent PTRR flags for targeted diagnosis', () => {
+    expect(
+      shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_READY_TO_INSTRUCT_USE_PTRR', {
+        BITCODE_ASSET_PACK_READY_TO_INSTRUCT_USE_PTRR: 'true',
+      } as NodeJS.ProcessEnv)
+    ).toBe(true);
+    expect(
+      shouldUseAssetPackPtrrForAgent('BITCODE_ASSET_PACK_VALIDATION_USE_PTRR', 'last', {
+        BITCODE_ASSET_PACK_VALIDATION_LAST_USE_PTRR: 'yes',
+      } as NodeJS.ProcessEnv)
+    ).toBe(true);
+  });
+});

packages/pipelines/asset-pack/src/agents/discovery-agents.ts

@@ -2,8 +2,8 @@
  * Discovery Phase Agents for the AssetPack Pipeline
  * 
  * Discovery agents default to deterministic, source-bound structured evidence
- * for live Read/Fit pipeline reliability. The heavyweight PTRR variants remain
- * available with BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR=1.
+ * for bounded local regression reliability. Staging/commercial runs should set
+ * BITCODE_ASSET_PACK_REAL_INFERENCE=1 to force the heavyweight PTRR variants.
  */
 
 import { factoryAgentWithPTRR } from '@bitcode/agent-generics';
@@ -28,6 +28,7 @@ import {
   createAssetPackDiscoveryPhaseAssessComplexityAgentPrompt,
   AssetPackDiscoveryPhaseAssessComplexityAgentPromptSteps
 } from './prompts/assess-complexity-prompt';
+import { shouldUseAssetPackPtrrForAgent } from '../runtime-inference-policy';
 
 // ==================== UNDERSTAND REQUIREMENTS AGENT ====================
 
@@ -595,10 +596,7 @@ export async function AssetPackDiscoveryPhaseAssessComplexityAgent(
 }
 
 function shouldUseDiscoveryPtrr(agent: string): boolean {
-  return (
-    process?.env?.BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR === '1' ||
-    process?.env?.[`BITCODE_ASSET_PACK_DISCOVERY_${agent.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_USE_PTRR`] === '1'
-  );
+  return shouldUseAssetPackPtrrForAgent('BITCODE_ASSET_PACK_DISCOVERY_USE_PTRR', agent);
 }
 
 function resolveDiscoveryRead(input: any, execution: any): string {

packages/pipelines/asset-pack/src/agents/finish/deliver-asset-pack-to-destination-agent.ts

@@ -14,6 +14,7 @@ import {
   resolveDeliveryMechanismTemplateFromExecution,
   resolveWrittenAssetTypeFromExecution,
 } from '../../semantic-resolution';
+import { shouldUseAssetPackPtrr } from '../../runtime-inference-policy';
 
 const FinishDeliveryOutputSchema = z.object({
   status: z.enum(['delivered','partial']).default('delivered'),
@@ -69,7 +70,7 @@ export default async function deliverAssetPackToDestination(input: any, executio
   // Build tool plan via output.useTools using agent PTRR Try step instructions
   // when explicitly enabled. The default staging finish path records local
   // delivery evidence without claiming a third-party pull request.
-  const result = process?.env?.BITCODE_ASSET_PACK_FINISH_DELIVER_USE_PTRR === '1'
+  const result = shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_FINISH_DELIVER_USE_PTRR')
     ? await AssetPackFinishDeliverAgent(
     {
       writtenAssetType: dtype,

packages/pipelines/asset-pack/src/agents/implementation/asset-pack-synthesize-artifacts-agent.ts

@@ -16,6 +16,7 @@ import { PROMPTPART_SPECIFIC_AGENT_ASSETPACKSYNTHESIZEARTIFACTS_PTRRREFINE_PURPO
 import { PROMPTPART_SPECIFIC_AGENT_ASSETPACKSYNTHESIZEARTIFACTS_PTRRRETRY_PURPOSE } from '@bitcode/prompts/raw_promptparts/specific/promptpart_specific_agent_assetpacksynthesizeartifacts_ptrrretry_purpose';
 import { z } from 'zod';
 import { AssetPackWrittenAssetType } from '../../types/AssetPackWrittenAssetType';
+import { shouldUseAssetPackPtrr } from '../../runtime-inference-policy';
 
 const AssetPackSynthesisInputSchema = z.object({
   read: z.string().optional(),
@@ -101,7 +102,7 @@ export default async function assetPackSynthesizeArtifacts(input: any, execution
     execution?.get?.('pipeline', 'deliveryMechanismTemplate') ??
     execution?.findUp?.('pipeline', 'deliveryMechanismTemplate') ??
     storedPipelineInput?.deliveryMechanismTemplate;
-  const result = process?.env?.BITCODE_ASSET_PACK_SYNTHESIS_USE_PTRR === '1'
+  const result = shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_SYNTHESIS_USE_PTRR')
     ? await AssetPackSynthesizeArtifactsAgent(
     {
       ...input,

packages/pipelines/asset-pack/src/agents/setup/asset-pack-comprehend-read-agent.ts

@@ -8,6 +8,7 @@
  */
 
 import { bitcodeSetupReadComprehensionAgent } from '@bitcode/generic-agents-read-comprehension';
+import { shouldUseAssetPackPtrr } from '../../runtime-inference-policy';
 
 export const AssetPackComprehendReadAgent = bitcodeSetupReadComprehensionAgent;
 
@@ -27,7 +28,7 @@ export async function runComprehendReadAgent(input: any, execution: any) {
     phase: 'setup',
     beforeAgent: 'danger-wall'
   };
-  const out = process?.env?.BITCODE_ASSET_PACK_COMPREHEND_READ_USE_PTRR === '1'
+  const out = shouldUseAssetPackPtrr('BITCODE_ASSET_PACK_COMPREHEND_READ_USE_PTRR')
     ? await AssetPackComprehendReadAgent(agentInput, execution)
     : buildDeterministicReadComprehension(agentInput, execution);
   try {