wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -457,10 +457,15 @@ Read/Fit result review remains fail-closed:
   AssetPack range projection, or finality readback is unavailable.
 - staging-testnet 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.
+  AssetPack pipeline. Deployed route-streaming runs should use
+  `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded`: setup, synthesis,
+  validation, and Finish stay model-backed while deterministic source-bound
+  depository discovery preserves enough route budget to synthesize, ship, and
+  read back the AssetPack. `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full`
+  is reserved for long-running sandbox audits outside the deployed streaming
+  route. A run with omitted per-agent `*_USE_PTRR` flags is not an acceptable
+  staging posture unless the global real-inference flag and explicit profile
+  are 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. Boolean

BITCODE_V28_QA.md

@@ -712,6 +712,7 @@ BITCODE_QA_VERBOSE=true
 
 BITCODE_ENABLE_PIPELINE_HARNESS_API=1
 BITCODE_ASSET_PACK_REAL_INFERENCE=1
+BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded
 BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS=600000
 OPENAI_API_KEY=<OpenAI key for non-mocked Terminal/protocol synthesis>
 BITCODE_LLM_PROVIDER=openai
@@ -721,7 +722,7 @@ SENTRY_DSN=<optional V28 alert sink; absence must remain readable blocked readin
 
 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.
+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 deployed streaming posture is the global real-inference flag, `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded`, and a real server-side model credential. Use `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` only for long-running sandbox audits outside the deployed route.
 
 ## Live Deployment Pass: First-Run Onboarding To Terminal Readiness
 
@@ -1183,7 +1184,8 @@ keys by name:
 BITCODE_PIPELINE_STREAM_TO_DATABASE=1 \
 BITCODE_PIPELINE_STRUCTURED_DB=1 \
 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
+BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded \
+BITCODE_SANDBOX_ENV_KEYS=SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY,OPENAI_API_KEY,BITCODE_ASSET_PACK_REAL_INFERENCE,BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE,BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS
 ```
 
 These Supabase values must be real staging credentials. Placeholder hosts such
@@ -1195,6 +1197,8 @@ 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`.
+When no profile is configured, the deployed route injects
+`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded`.
 
 ```bash
 curl -N "$BITCODE_UAPI_URL/api/pipeline-harness/asset-pack" \
@@ -1321,9 +1325,13 @@ Observed staging-testnet harness evidence on 2026-05-17:
   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.
+  `BITCODE_ASSET_PACK_REAL_INFERENCE=1`. On the deployed streaming route,
+  `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` is now the required
+  profile: setup, synthesis, validation, and Finish produce model-generation
+  telemetry while deterministic source-bound discovery preserves budget for a
+  complete AssetPack run. Full discovery PTRR remains available through
+  `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` for long-running sandbox
+  audits outside the deployed route.
 - 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
@@ -1374,6 +1382,32 @@ Follow-up local Vercel Sandbox overlay evidence on 2026-05-17:
   reconciliation readback roots, or explicit blocked-readiness, before such a
   candidate can become `worthy_fit`.
 
+Second local overlay evidence on 2026-05-17:
+
+- Vercel Sandbox run `sbx_XO602gYd3F57rYSyc8NzkPsXIDb7` exported artifacts to
+  `.bitcode/pipeline-harness-runs/2026-05-17T20-34-37-584Z-sbx_XO602gYd3F57rYSyc8NzkPsXIDb7/`.
+- The run found and ranked the deposited repository candidate with real
+  OpenAI-backed setup and discovery telemetry, 3565 stream lines, prompt/context
+  input, raw responses, parsed output, usage, phase, agent, step, failsafe, and
+  generation correlation.
+- The run failed closed with `PipelineHarnessTimeoutError` after the configured
+  1200000 ms harness budget while still in discovery
+  (`asset-pack-plan-implementation-agent`). It did not reach synthesis,
+  validation, Finish, shipping, or ledger settlement.
+- The root cause is not a source crash; it is a runtime-shape mismatch between
+  the deployed streaming route budget and full PTRR discovery. V28 now separates
+  route-streaming real inference (`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded`)
+  from full PTRR audits (`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full`) so
+  staging can complete the value-producing Read/Fit -> AssetPack -> Finish path
+  inside the Vercel Function window.
+- The run also exposed agent-visible tool registry drift: a risk-admission
+  generation requested `lexical-depository-search`, but the PTRR tool executor
+  reported `Tool not found: lexical-depository-search`. The deterministic
+  depository search had already run before setup agents, so the search result
+  was present as pipeline context; V28 still needs agent-visible depository
+  search/readback tool registration or prompt tightening before full PTRR audits
+  can be considered clean.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

packages/pipeline-hosts/README.md

@@ -78,9 +78,12 @@ 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 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_REAL_INFERENCE=1`. On the deployed streaming route,
+`BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded` is the expected profile:
+setup, synthesis, validation, and finish stay model-backed, while deterministic
+source-bound discovery evidence preserves enough budget to ship and read back
+the AssetPack. Set `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=full` only for
+long-running sandbox audits outside the deployed route. 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.
@@ -132,6 +135,7 @@ BITCODE_SANDBOX_SOURCE_REVISION=31bbc0c5227b6b3aed5d107fd8507d35ec22970a \
 BITCODE_SANDBOX_DEPOSIT_HAS_PROOF=1 \
 BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT=1 \
 BITCODE_ASSET_PACK_REAL_INFERENCE=1 \
+BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded \
 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

@@ -29,6 +29,7 @@ const TRUSTED_SANDBOX_ENV_KEYS = [
   'BITCODE_LLM_PROVIDER',
   'BITCODE_LLM_MODEL',
   'BITCODE_ASSET_PACK_REAL_INFERENCE',
+  'BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE',
   'BITCODE_ASSET_PACK_SETUP_PLAN_USE_PTRR',
   'BITCODE_ASSET_PACK_COMPREHEND_READ_USE_PTRR',
   'BITCODE_ASSET_PACK_DANGER_WALL_USE_PTRR',

packages/pipelines/asset-pack/package.json

@@ -24,6 +24,7 @@
     "@bitcode/generic-agents-file-pick": "workspace:*",
     "@bitcode/generic-agents-read-comprehension": "workspace:*",
     "@bitcode/generic-agents-danger-wall": "workspace:*",
+    "@bitcode/generic-tools-editing": "workspace:*",
     "@bitcode/llm-generics": "workspace:*",
     "@bitcode/logger": "workspace:*",
     "@bitcode/prompts": "workspace:*",

packages/pipelines/asset-pack/src/__tests__/bounded-structured-inference.test.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { runBoundedStructuredInference } from '../bounded-structured-inference';
+
+const ResultSchema = z.object({
+  summary: z.string(),
+  accepted: z.boolean(),
+});
+
+function makeExecution(llm?: any) {
+  const stores: Array<{ namespace: string; key: string; value: unknown }> = [];
+  const execution: any = {
+    id: 'root',
+    store(namespace: string, key: string, value: unknown) {
+      stores.push({ namespace, key, value });
+    },
+    getRoot() {
+      return execution;
+    },
+    child(id: string) {
+      return {
+        ...execution,
+        id,
+        parent: execution,
+      };
+    },
+  };
+
+  if (llm) {
+    execution.llms = {
+      getDefaultLLM: jest.fn(() => llm),
+    };
+  }
+
+  return { execution, stores };
+}
+
+function resetInferenceEnv() {
+  delete process.env.BITCODE_ASSET_PACK_REAL_INFERENCE;
+  delete process.env.BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE;
+  delete process.env.OPENAI_API_KEY;
+  delete process.env.BITCODE_LLM_PROVIDER;
+  delete process.env.BITCODE_LLM_MODEL;
+}
+
+describe('runBoundedStructuredInference', () => {
+  beforeEach(resetInferenceEnv);
+  afterEach(resetInferenceEnv);
+
+  it('keeps deterministic fallback available when real inference is not required', async () => {
+    const { execution, stores } = makeExecution();
+
+    const result = await runBoundedStructuredInference({
+      agentName: 'test-agent',
+      phase: 'setup',
+      step: 'bounded',
+      systemPrompt: 'Return JSON.',
+      userPrompt: 'Return a result.',
+      schema: ResultSchema,
+      fallback: () => ({ summary: 'fallback', accepted: false }),
+      execution,
+    });
+
+    expect(result).toEqual({ summary: 'fallback', accepted: false });
+    expect(stores).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          namespace: 'bounded-inference',
+          key: 'status',
+          value: 'fallback-no-llm',
+        }),
+      ])
+    );
+  });
+
+  it('blocks real inference when no LLM can be resolved', async () => {
+    process.env.BITCODE_ASSET_PACK_REAL_INFERENCE = '1';
+    process.env.BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE = 'bounded';
+    const { execution, stores } = makeExecution();
+
+    await expect(
+      runBoundedStructuredInference({
+        agentName: 'test-agent',
+        phase: 'setup',
+        step: 'bounded',
+        systemPrompt: 'Return JSON.',
+        userPrompt: 'Return a result.',
+        schema: ResultSchema,
+        fallback: () => ({ summary: 'fallback', accepted: false }),
+        execution,
+      })
+    ).rejects.toThrow(/no configured LLM/i);
+
+    expect(stores).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          namespace: 'bounded-inference',
+          key: 'status',
+          value: 'blocked-no-llm',
+        }),
+      ])
+    );
+  });
+
+  it('uses the execution LLM for real bounded inference and stores parsed output telemetry', async () => {
+    process.env.BITCODE_ASSET_PACK_REAL_INFERENCE = '1';
+    process.env.BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE = 'bounded';
+    const llm = jest.fn(async () => ({
+      content: JSON.stringify({ summary: 'model result', accepted: true }),
+      usage: { inputTokens: 12, outputTokens: 8, totalTokens: 20 },
+      metadata: { provider: 'test-provider', model: 'test-model' },
+    }));
+    const { execution, stores } = makeExecution(llm);
+
+    const result = await runBoundedStructuredInference({
+      agentName: 'test-agent',
+      phase: 'setup',
+      step: 'bounded',
+      systemPrompt: 'Return JSON.',
+      userPrompt: 'Return a result.',
+      schema: ResultSchema,
+      fallback: () => ({ summary: 'fallback', accepted: false }),
+      execution,
+    });
+
+    expect(result).toEqual({ summary: 'model result', accepted: true });
+    expect(llm).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({
+          responseFormat: 'json',
+        }),
+      })
+    );
+    expect(stores).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          namespace: 'bounded-inference',
+          key: 'status',
+          value: 'success',
+        }),
+        expect.objectContaining({
+          namespace: 'llm',
+          key: 'parsedOutput',
+        }),
+      ])
+    );
+  });
+});

packages/pipelines/asset-pack/src/__tests__/depository-search-tool.test.ts

@@ -0,0 +1,80 @@
+import { executionContext } from '@bitcode/generic-tools-editing/execution-context';
+import { lexicalDepositorySearchTool } from '../tools/AssetPackLexicalDepositorySearchTool';
+
+describe('lexical depository search tool', () => {
+  it('reads back the authoritative depository search result from execution context', async () => {
+    const storedResult = {
+      schema: 'bitcode.asset-pack.depository-search',
+      resultState: 'worthy_fit',
+      resultReasons: ['Selected 1 proof-bearing AssetPack candidate for this Read.'],
+      read: {
+        prompt: 'Read deposited source evidence.',
+        targetArtifactKinds: [],
+        closureCriteria: [],
+        failureModes: [],
+      },
+      thresholds: {
+        reviewScore: 0.75,
+        worthyScore: 0.85,
+        semanticScore: 0.35,
+        maxSelectedCandidates: 3,
+      },
+      searchedAssetCount: 1,
+      selectedCandidateAssetIds: ['asset-1'],
+      selectedCandidates: [
+        {
+          assetId: 'asset-1',
+          title: 'Deposited source asset',
+          useTier: 'settlement-eligible',
+          selectedUnits: [],
+          ranking: {
+            finalScore: 0.91,
+            semanticScore: 0.9,
+          },
+          verification: {
+            blockers: [],
+            warnings: [],
+          },
+          recall: {
+            matchedTerms: ['deposit', 'read'],
+          },
+        },
+      ],
+      rejectedCandidates: [],
+      blockedCandidates: [],
+      candidateRanking: [],
+      embeddingPolicy: {
+        provider: 'openai',
+        model: 'text-embedding-3-small',
+      },
+      queryRoot: 'sha256:query',
+      rankingRoot: 'sha256:ranking',
+      createdAt: '2026-05-17T00:00:00.000Z',
+    };
+    const execution = {
+      findUp: jest.fn((namespace: string, key: string) => {
+        if (namespace === 'depository/search' && key === 'result') return storedResult;
+        return undefined;
+      }),
+    };
+
+    const output = await executionContext.run(execution as any, () =>
+      lexicalDepositorySearchTool.execute({ repositoryFullName: 'engineeredsoftware/ENGI' }),
+    );
+
+    expect(output).toMatchObject({
+      schema: 'bitcode.asset-pack.lexical-depository-search-tool-result',
+      readbackSource: 'execution-store',
+      resultState: 'worthy_fit',
+      selectedCandidateAssetIds: ['asset-1'],
+      searchedAssetCount: 1,
+      queryRoot: 'sha256:query',
+      rankingRoot: 'sha256:ranking',
+      fitResult: {
+        schema: 'bitcode.asset-pack.fit-result',
+        resultState: 'worthy_fit',
+        selectedCandidateAssetIds: ['asset-1'],
+      },
+    });
+  });
+});