wip v28

Author: geraldarthurdavis

BITCODE_V28_QA.md

@@ -1256,6 +1256,40 @@ Commercial blockers:
 - Terminal enables settlement, minting, branch materialization, BTC fee
   broadcast, or ledger finality from a host smoke result.
 
+Observed staging-testnet harness evidence on 2026-05-17:
+
+- Vercel Sandbox run `sbx_ktb5Z6VnP5A16m9k4a0FkBcJg1d3` completed all six
+  host commands and exported artifacts to
+  `.bitcode/pipeline-harness-runs/2026-05-17T16-37-38-466Z-sbx_ktb5Z6VnP5A16m9k4a0FkBcJg1d3/`.
+- Pipeline run `d21240bd-ebc7-41ae-b082-06d7beb244a7` returned
+  `pipelineResultState='worthy_fit'` and final `resultState='blocked_readiness'`
+  because the run used `BITCODE_SANDBOX_APPLY_LOCAL_PATCH=1`.
+- The synthesized AssetPack evidence was source-bound to
+  `engineeredsoftware/ENGI@main@4ced69180958143254639a8a5af94c0991545a91`,
+  selected candidate `manual-deposit-qa`, query root
+  `sha256:1d58f3d0e16af0700a702b2b307c744145a9196ac63841345a20ff597f5a3ca3`,
+  ranking root
+  `sha256:c04599ac4782dadf3b63842381dd20c76f577401cc35d82fbee4a63797496aa1`,
+  and embedding policy `openai text-embedding-3-small`, 1536 dimensions,
+  `match_deliverable_vectors`, cosine.
+- Supabase readback showed `pipeline_runs.status='completed'`,
+  `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.
+- 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
+  finality.
+- The next promotion step is a clean source-revision run after these pipeline
+  harness changes are deployed in the deposited source revision. Only a clean
+  no-overlay run may write and read back ledger settlement rows.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

packages/pipeline-hosts/src/asset-pack-harness.ts

@@ -1390,6 +1390,7 @@ try {
         ...postprocessedOutput,
       }
     : rawOutput;
+  await pipelineStreamer.flushStructuredWrites?.();
   const pipelineResultState = normalizeResultState(
     output?.resultState || output?.fitResult?.resultState || output?.fit?.resultState
   );

packages/pipelines-generics/src/execution/PipelineExecutor.ts

@@ -13,6 +13,7 @@ import {
   ShortCircuitSignal 
 } from '@bitcode/execution-generics';
 import { Executor } from '@bitcode/execution-generics';
+import { resolveRegisteredAgent } from './resolve-agent';
 
 export interface PhaseConfig {
   phaseName: string;
@@ -54,10 +55,7 @@ export class PipelineExecutor {
    */
   async executeAgent(agentName: string, input: any): Promise<any> {
     // Get agent from registry
-    const agent = this.execution.agents.getAgent(agentName);
-    if (!agent) {
-      throw new Error(`Agent not found: ${agentName}`);
-    }
+    const agent = await resolveRegisteredAgent(agentName, this.execution.agents.getAgent(agentName) as any);
     const phase = String(this.execution.get('phase', 'current') || 'setup');
     const step = 'try';
     this.execution.store('agent', 'name', agentName);

packages/pipelines-generics/src/execution/__tests__/events.unit.test.ts

@@ -2,6 +2,7 @@
 // @ts-nocheck
 import { PipelineExecution } from '../PipelineExecution';
 import { PipelineExecutor } from '../PipelineExecutor';
+import { createAgentExecutor } from '../agent-executor';
 import { ExecutionStreamAdapter } from '@bitcode/execution-generics';
 import { Streamer } from '@bitcode/streams';
 
@@ -86,4 +87,28 @@ describe('PipelineExecutor event emission (unit)', () => {
       { explicit: true },
     ]);
   });
+
+  it('resolves lazy registered agents before executing through generic executors', async () => {
+    const exec = new PipelineExecution('pipeline:lazy-agent');
+    const phaseInput = { read: 'fit deposited source revision' };
+
+    (exec as any).agents.registerAgent('unit:lazy-executor', (() =>
+      Promise.resolve(async (input: any, execution: any) => {
+        execution.store('lazy-agent', 'executor-input', input);
+        return { ok: true, read: input.read };
+      })) as any);
+    (exec as any).agents.registerAgent('unit:lazy-phase', (() =>
+      Promise.resolve(async (input: any, execution: any) => {
+        execution.store('lazy-agent', 'phase-input', input);
+        return { ok: true, read: input.read };
+      })) as any);
+
+    const executorOutput = await createAgentExecutor('unit:lazy-executor')(phaseInput, exec);
+    const phaseOutput = await new PipelineExecutor(exec).executeAgent('unit:lazy-phase', phaseInput);
+
+    expect(executorOutput).toEqual({ ok: true, read: phaseInput.read });
+    expect(phaseOutput).toEqual({ ok: true, read: phaseInput.read });
+    expect(exec.get('lazy-agent', 'executor-input')).toBe(phaseInput);
+    expect(exec.get('lazy-agent', 'phase-input')).toBe(phaseInput);
+  });
 });

packages/pipelines-generics/src/execution/agent-executor.ts

@@ -7,12 +7,12 @@ import { Executor } from '@bitcode/execution-generics';
 import { PipelineExecution } from './PipelineExecution';
 import { log } from '@bitcode/logger';
 import { isExecutionDebugEnabled } from './debug';
+import { resolveRegisteredAgent } from './resolve-agent';
 
 export function createAgentExecutor(agentName: string): Executor<any, any> {
   return async (input: any, execution: any) => {
     const px = execution as PipelineExecution;
-    const agent = px.agents.getAgent(agentName);
-    if (!agent) throw new Error(`Agent not found: ${agentName}`);
+    const agent = await resolveRegisteredAgent(agentName, px.agents.getAgent(agentName) as any);
     const phase = String(px.get('phase', 'current') || 'setup');
     const step = 'try';
     px.store('agent', 'name', agentName);

packages/pipelines-generics/src/execution/resolve-agent.ts

@@ -0,0 +1,28 @@
+import type { ExecutionAgent } from './PipelineAgentRegistry';
+
+type RegisteredAgent = ExecutionAgent | (() => Promise<ExecutionAgent | { default?: ExecutionAgent }>);
+
+export async function resolveRegisteredAgent(
+  agentName: string,
+  registeredAgent: RegisteredAgent | undefined
+): Promise<ExecutionAgent> {
+  if (!registeredAgent) {
+    throw new Error(`Agent not found: ${agentName}`);
+  }
+
+  if (typeof registeredAgent !== 'function') {
+    throw new Error(`Registered agent is not executable: ${agentName}`);
+  }
+
+  if (registeredAgent.length === 0) {
+    const loaded = await (registeredAgent as () => Promise<ExecutionAgent | { default?: ExecutionAgent }>)();
+    if (typeof loaded === 'function') {
+      return loaded;
+    }
+    if (typeof loaded?.default === 'function') {
+      return loaded.default;
+    }
+  }
+
+  return registeredAgent as ExecutionAgent;
+}

packages/pipelines-generics/src/streaming/__tests__/forkable-execution.test.ts

@@ -102,7 +102,7 @@ describe('enablePipelineStreaming + Execution emits DB events (snapshot stream)'
     const userId = '22222222-2222-4222-8222-222222222222';
 
     const exec = new Execution(`exec-${runId}`);
-    enablePipelineStreaming(exec as any, {
+    const streamer = enablePipelineStreaming(exec as any, {
       runId,
       userId,
       supabase,
@@ -177,6 +177,7 @@ describe('enablePipelineStreaming + Execution emits DB events (snapshot stream)'
       phase: 'setup',
       data: { status: 'completed' },
     });
+    await (streamer as any).flushStructuredWrites?.();
 
     expect(supabase.tables.deliverable_pipeline_runs).toHaveLength(1);
     expect(supabase.tables.deliverable_pipeline_phase_delegations).toHaveLength(1);

packages/pipelines-generics/src/streaming/pipeline-stream-integration.ts

@@ -111,6 +111,7 @@ export function enablePipelineStreaming(
     const deliverableRunId = String(config.runId || '');
     const canPersistDeliverableHierarchy = uuidRe.test(deliverableRunId);
     let deliverableRunReady: Promise<boolean> | null = null;
+    let structuredWriteQueue: Promise<unknown> = Promise.resolve();
 
     const insertRow = async (table: string, row: any, returningId = false) => {
       const query = (supabase as any).from(table).insert(row);
@@ -222,7 +223,36 @@ export function enablePipelineStreaming(
       }, 'id', deliverableRunId).catch(() => {});
     };
 
-    streamer.subscribe(async (event: any) => {
+    const completeOpenHierarchyRows = async (now: string) => {
+      if (!(await ensureDeliverableRun())) return;
+      const { data: openPhases } = await (supabase as any)
+        .from('deliverable_pipeline_phase_delegations')
+        .select('id')
+        .eq('run_id', deliverableRunId)
+        .eq('status', 'running');
+      const openPhaseIds = Array.isArray(openPhases)
+        ? openPhases.map((row: any) => row?.id).filter(Boolean)
+        : [];
+      if (!openPhaseIds.length) return;
+      await (supabase as any)
+        .from('deliverable_pipeline_agent_steps')
+        .update({
+          completed_at: now,
+          status: 'completed',
+        })
+        .in('phase_delegation_id', openPhaseIds)
+        .eq('status', 'running');
+      await (supabase as any)
+        .from('deliverable_pipeline_phase_delegations')
+        .update({
+          completed_at: now,
+          status: 'completed',
+        })
+        .in('id', openPhaseIds)
+        .eq('status', 'running');
+    };
+
+    const persistStructuredEvent = async (event: any) => {
       try {
         const type = String(event?.type || '');
         const context = normalizeEventContext(event);
@@ -414,13 +444,21 @@ export function enablePipelineStreaming(
 
         // If Finish phase completes, mark run completed.
         if (type === 'phase-complete' && phaseName === 'finish') {
+          await completeOpenHierarchyRows(now);
           await markDeliverableRun('completed', event?.data ?? event);
           await updateRows('executions', { status: 'completed', completed_at: now }, 'id', config.runId).catch(() => {});
         }
       } catch (err) {
         console.error('Structured stream persistence error', err);
       }
+    };
+
+    streamer.subscribe((event: any) => {
+      structuredWriteQueue = structuredWriteQueue
+        .catch(() => {})
+        .then(() => persistStructuredEvent(event));
     });
+    (streamer as any).flushStructuredWrites = () => structuredWriteQueue.catch(() => {});
   }
 
   // Note: Cleanup should be handled by the pipeline implementation

packages/pipelines/asset-pack/src/__tests__/asset-pack-synthesize-artifacts-agent.test.ts

@@ -0,0 +1,39 @@
+// @ts-nocheck
+import assetPackSynthesizeArtifacts from '../agents/implementation/asset-pack-synthesize-artifacts-agent';
+import { Execution } from '@bitcode/execution-generics';
+
+describe('assetPackSynthesizeArtifacts', () => {
+  it('recovers Read, source revision, and fit evidence from execution context', async () => {
+    const root = new Execution('pipeline:asset-pack');
+    root.store('read', 'request', {
+      prompt: 'Read the deposited source revision for terminal closure.',
+    });
+    root.store('harness', 'sourceRevision', {
+      repositoryFullName: 'engineeredsoftware/ENGI',
+      branch: 'main',
+      commit: 'abc123',
+    });
+    root.store('fit', 'result', {
+      resultState: 'worthy_fit',
+      selectedCandidateAssetIds: ['deposit-1'],
+      queryRoot: 'sha256:query',
+      rankingRoot: 'sha256:ranking',
+      embeddingPolicy: { provider: 'openai', model: 'text-embedding-3-small' },
+    });
+
+    const phase = root.child('phase:implementation');
+    const result = await assetPackSynthesizeArtifacts({ overallComplexity: 'moderate' }, phase);
+
+    expect(result.assetPack.read).toBe('Read the deposited source revision for terminal closure.');
+    expect(result.assetPackSynthesisArtifacts.summary).toContain('engineeredsoftware/ENGI@main@abc123');
+    expect(result.assetPackSynthesisArtifacts.summary).toContain('worthy_fit with 1 selected candidate');
+    expect(result.assetPackSynthesisArtifacts.proofEvidence).toEqual(
+      expect.arrayContaining([
+        'Selected candidate assets: deposit-1',
+        'Query root: sha256:query',
+        'Ranking root: sha256:ranking',
+        'Embedding policy: openai text-embedding-3-small',
+      ])
+    );
+  });
+});

packages/pipelines/asset-pack/src/__tests__/postprocess.test.ts

@@ -85,6 +85,32 @@ describe('normalizeAssetPackOutput', () => {
     });
   });
 
+  it('preserves implementation artifacts when postprocess runs from a sibling execution node', () => {
+    const root = new Execution('pipeline:asset-pack');
+    const implementation = root.child('phase:implementation');
+    const finish = root.child('phase:finish');
+    implementation.store('implementation', 'assetPackSynthesisArtifacts', {
+      summary: 'Sibling implementation AssetPack artifacts are authoritative.',
+      fileChanges: { edited: 0, created: 1, deleted: 0 },
+      proofEvidence: ['sibling-implementation-read'],
+    });
+    finish.store('finish/asset_pack_completion', 'assetPackSynthesisArtifacts', {
+      summary: 'Finish wrapper should not override implementation artifacts.',
+      fileChanges: { edited: 0, created: 0, deleted: 0 },
+      proofEvidence: ['finish-wrapper'],
+    });
+
+    const normalized = normalizeAssetPackOutput({ success: true, summary: '' } as any, finish);
+    const result = buildAssetPackPostprocessedResult(finish, normalized);
+
+    expect(normalized.assetPackSynthesisArtifacts?.summary).toBe(
+      'Sibling implementation AssetPack artifacts are authoritative.'
+    );
+    expect(result.summary).toBe('Sibling implementation AssetPack artifacts are authoritative.');
+    expect(result.title).toBe('Sibling implementation AssetPack artifacts are authoritative.');
+    expect(result.assetPackSynthesisArtifacts?.proofEvidence).toEqual(['sibling-implementation-read']);
+  });
+
   it('uses pull-request delivery mechanisms as canonical shippable evidence for the written asset', () => {
     const exec = new Execution('pipeline:asset-pack');
     exec.store('execution', 'id', 'exec-2');