wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -410,6 +410,8 @@ The V28 pipeline harness must write a manifest before execution containing:
 
 - Read id and Read text;
 - Deposit id and optional deposited AssetPack id;
+- optional Deposit proof root, measurement root, and reconciliation readback
+  root when the deposited evidence already has them;
 - repository full name, branch, and commit;
 - host capability summary;
 - expected stages: deposit search, candidate ranking, Read comprehension,
@@ -461,7 +463,11 @@ Read/Fit result review remains fail-closed:
   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.
+  the pipeline input and the downstream readback queries confirm them. Boolean
+  wallet/measurement posture is not enough when the Read asks for proof-root,
+  finality, or reconciliation readback; those roots must be supplied by the
+  deposited evidence, synthesized and read back during Finish, or returned as
+  explicit `blocked_readiness`.
 - every SDIVF phase, PTRR agent step, ThriceifiedGeneration, and tool execution
   must be inspectable as prompt/context input, raw model/tool output,
   parsed/typed output, usage/timing metadata, and phase/agent/step/failsafe

BITCODE_V28_QA.md

@@ -1209,7 +1209,10 @@ curl -N "$BITCODE_UAPI_URL/api/pipeline-harness/asset-pack" \
     "depositId": "3f68d845-d910-41ef-835a-89cf0103ac0a",
     "depositAssetId": "asset_repository-revision-deposit-engineeredsoftware-engi_aece31322e",
     "depositHasWalletOrAttestationProof": true,
-    "depositHasAssetMeasurementEvidence": true
+    "depositHasAssetMeasurementEvidence": true,
+    "depositProofRoot": "sha256:<proof-root-when-known>",
+    "depositMeasurementRoot": "sha256:<measurement-root-when-known>",
+    "depositReconciliationReadbackRoot": "sha256:<readback-root-when-known>"
   }'
 ```
 
@@ -1353,6 +1356,24 @@ Later staging-testnet evidence on 2026-05-17 after the no-overlay deployment:
   future failures show the same phase/agent/step/generation metadata operators
   already use for persisted Bitcode activity.
 
+Follow-up local Vercel Sandbox overlay evidence on 2026-05-17:
+
+- Vercel Sandbox run `sbx_GLXzpbkAjP6sIceauReWGdp0GWTE` exported artifacts to
+  `.bitcode/pipeline-harness-runs/2026-05-17T20-08-16-548Z-sbx_GLXzpbkAjP6sIceauReWGdp0GWTE/`.
+- The run progressed past setup risk admission and into real model-backed
+  discovery, exporting 3237 telemetry lines with prompt/context, response,
+  usage, phase, agent, step, failsafe, and generation correlation.
+- The run failed closed with `resultState='blocked_readiness'` because
+  `applyResearchApproachSemanticMirrors` assumed `approach.phases` existed on
+  the top-level return value, while full PTRR returns envelope-shaped typed
+  output. The V28 fix is to normalize PTRR envelopes for discovery mirrors
+  before reading semantic aliases.
+- The run also exposed an overclaim risk: manifest-only Deposit evidence with
+  wallet/measurement booleans was being treated as enough for a Read requiring
+  proof/finality and reconciliation readback. V28 now requires proof-root and
+  reconciliation readback roots, or explicit blocked-readiness, before such a
+  candidate can become `worthy_fit`.
+
 ## 2026-05-13 Staging Deployment Readiness Gate
 
 Purpose:

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

@@ -145,5 +145,6 @@ describe('asset-pack sandbox harness plan', () => {
     expect(source).toContain('settlementOwnershipBoundary');
     expect(source).toContain('depositor owns minted BTD range');
     expect(source).toContain('reader pays BTC fee');
+    expect(source).toContain('verificationEvidence');
   });
 });

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

@@ -471,6 +471,11 @@ function buildManifestDepositoryAsset(manifest) {
   const assetId = manifest.deposit?.assetId || manifest.deposit?.id || 'manifest-deposit-reference';
   const source = manifest.sourceRevision || {};
   const repositoryFullName = source.repositoryFullName || '';
+  const verificationEvidence = {
+    proofRoot: manifest.deposit?.proofRoot || null,
+    measurementRoot: manifest.deposit?.measurementRoot || null,
+    reconciliationReadbackRoot: manifest.deposit?.reconciliationReadbackRoot || null,
+  };
   const text = [
     'Deposited repository revision',
     repositoryFullName,
@@ -504,6 +509,9 @@ function buildManifestDepositoryAsset(manifest) {
     },
     hasWalletOrAttestationProof: manifest.deposit?.hasWalletOrAttestationProof === true,
     hasAssetMeasurementEvidence: manifest.deposit?.hasAssetMeasurementEvidence === true,
+    verificationEvidence: Object.values(verificationEvidence).some(Boolean)
+      ? verificationEvidence
+      : null,
   };
 }
 

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

@@ -380,6 +380,10 @@ async function main(): Promise<void> {
       assetId: process.env.BITCODE_SANDBOX_DEPOSIT_ASSET_ID || null,
       hasWalletOrAttestationProof: process.env.BITCODE_SANDBOX_DEPOSIT_HAS_PROOF === '1',
       hasAssetMeasurementEvidence: process.env.BITCODE_SANDBOX_DEPOSIT_HAS_MEASUREMENT === '1',
+      proofRoot: process.env.BITCODE_SANDBOX_DEPOSIT_PROOF_ROOT || null,
+      measurementRoot: process.env.BITCODE_SANDBOX_DEPOSIT_MEASUREMENT_ROOT || null,
+      reconciliationReadbackRoot:
+        process.env.BITCODE_SANDBOX_DEPOSIT_RECONCILIATION_READBACK_ROOT || null,
     },
     sourceRevision: {
       repositoryFullName,

packages/pipeline-hosts/src/types.ts

@@ -82,6 +82,9 @@ export interface PipelineDepositReference {
   assetId?: string | null;
   hasWalletOrAttestationProof?: boolean;
   hasAssetMeasurementEvidence?: boolean;
+  proofRoot?: string | null;
+  measurementRoot?: string | null;
+  reconciliationReadbackRoot?: string | null;
 }
 
 export interface PipelineHarnessManifest {

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

@@ -116,6 +116,10 @@ describe('AssetPack depository search', () => {
           signingSurface: null,
           githubBoundary: null,
           attestations: [],
+          verificationEvidence: {
+            measurementRoot: 'sha256:test-measurement-root',
+            reconciliationReadbackRoot: 'sha256:test-reconciliation-readback-root',
+          },
           hasWalletOrAttestationProof: false,
         }),
       ],
@@ -134,6 +138,10 @@ describe('AssetPack depository search', () => {
         asset({
           assetMeasurement: null,
           measurementProvenance: [],
+          verificationEvidence: {
+            proofRoot: 'sha256:test-proof-root',
+            reconciliationReadbackRoot: 'sha256:test-reconciliation-readback-root',
+          },
           hasAssetMeasurementEvidence: false,
         }),
       ],

packages/pipelines/asset-pack/src/__tests__/discovery-semantic-mirrors.test.ts

@@ -51,6 +51,37 @@ describe('AssetPack discovery semantic mirrors', () => {
     expect(output.approach.phases[0].writtenAssets).toEqual(['draft pull request']);
   });
 
+  it('normalizes PTRR envelope research outputs before mirroring', () => {
+    const output = applyResearchApproachSemanticMirrors({
+      output: {
+        approach: {
+          methodology: 'parallel analysis',
+          phases: [
+            {
+              name: 'finish',
+              description: 'materialize the AssetPack evidence',
+              assetPackSynthesisArtifacts: ['source patch evidence'],
+            },
+          ],
+          tools: ['git'],
+          estimatedEffort: 'medium',
+        },
+        alternatives: [],
+        risks: [],
+        recommendation: 'finish with an AssetPack',
+      },
+    } as any);
+
+    expect(output.approach.phases[0].writtenAssets).toEqual(['source patch evidence']);
+  });
+
+  it('fails softly when PTRR research output omits approach phases', () => {
+    const output = applyResearchApproachSemanticMirrors({ output: { recommendation: 'continue' } } as any);
+
+    expect(output.approach.phases).toEqual([]);
+    expect(output.recommendation).toBe('continue');
+  });
+
   it('mirrors definition of read into read satisfaction criteria', () => {
     const output = applyPlanImplementationSemanticMirrors({
       implementationPlan: {
@@ -89,4 +120,25 @@ describe('AssetPack discovery semantic mirrors', () => {
 
     expect(output.readSatisfactionCriteria).toEqual(['asset pack accepted']);
   });
+
+  it('normalizes PTRR envelope plan outputs before mirroring', () => {
+    const output = applyPlanImplementationSemanticMirrors({
+      finalOutput: {
+        implementationPlan: {
+          overview: 'deliver the requested change',
+          milestones: [],
+          dependencies: [],
+        },
+        testingStrategy: {
+          approach: 'targeted regression',
+          testTypes: ['unit'],
+          coverage: 'focused',
+        },
+        validationCriteria: ['tests pass'],
+        definitionOfRead: ['asset pack accepted'],
+      },
+    } as any);
+
+    expect(output.readSatisfactionCriteria).toEqual(['asset pack accepted']);
+  });
 });

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

@@ -195,23 +195,67 @@ const ResearchApproachOutputSchema = z.object({
   recommendation: z.string()
 });
 
+function pickStructuredOutput<T>(rawOutput: T, expectedKeys: string[]): any {
+  const envelopeCandidates = [
+    (rawOutput as any)?.output,
+    (rawOutput as any)?.finalOutput,
+    (rawOutput as any)?.processedResult,
+    (rawOutput as any)?.result,
+  ].filter((candidate) => candidate && typeof candidate === 'object');
+  const candidates = [
+    rawOutput,
+    ...envelopeCandidates,
+  ];
+  const match = candidates.find((candidate) =>
+    candidate &&
+    typeof candidate === 'object' &&
+    expectedKeys.some((key) => Object.prototype.hasOwnProperty.call(candidate, key))
+  );
+  return match || envelopeCandidates[0] || rawOutput;
+}
+
+function normalizeResearchApproachOutput(
+  rawOutput: z.infer<typeof ResearchApproachOutputSchema>
+): z.infer<typeof ResearchApproachOutputSchema> {
+  const output = pickStructuredOutput(rawOutput, ['approach']);
+  const approach = output?.approach && typeof output.approach === 'object' ? output.approach : {};
+  return {
+    approach: {
+      methodology: typeof approach.methodology === 'string' ? approach.methodology : '',
+      phases: Array.isArray(approach.phases) ? approach.phases : [],
+      tools: Array.isArray(approach.tools) ? approach.tools : [],
+      estimatedEffort: typeof approach.estimatedEffort === 'string' ? approach.estimatedEffort : '',
+    },
+    alternatives: Array.isArray(output?.alternatives) ? output.alternatives : [],
+    risks: Array.isArray(output?.risks) ? output.risks : [],
+    recommendation: typeof output?.recommendation === 'string' ? output.recommendation : '',
+  };
+}
+
 export function applyResearchApproachSemanticMirrors(
-  output: z.infer<typeof ResearchApproachOutputSchema>
+  rawOutput: z.infer<typeof ResearchApproachOutputSchema>
 ): z.infer<typeof ResearchApproachOutputSchema> {
+  const output = normalizeResearchApproachOutput(rawOutput);
   return {
     ...output,
     approach: {
       ...output.approach,
-      phases: output.approach.phases.map((phase) => ({
-        ...phase,
-        writtenAssets:
-          phase.writtenAssets ??
-          phase.assetPackSynthesisArtifacts ??
-          phase.shippables,
-        assetPackSynthesisArtifacts:
-          phase.assetPackSynthesisArtifacts ??
-          phase.writtenAssets,
-      })),
+      phases: output.approach.phases.map((phase) => {
+        const normalizedPhase: any =
+          phase && typeof phase === 'object'
+            ? phase
+            : { name: String(phase || ''), description: '' };
+        return {
+          ...normalizedPhase,
+          writtenAssets:
+            normalizedPhase.writtenAssets ??
+            normalizedPhase.assetPackSynthesisArtifacts ??
+            normalizedPhase.shippables,
+          assetPackSynthesisArtifacts:
+            normalizedPhase.assetPackSynthesisArtifacts ??
+            normalizedPhase.writtenAssets,
+        };
+      }),
     },
   };
 }
@@ -327,9 +371,41 @@ const PlanImplementationOutputSchema = z.object({
   readSatisfactionCriteria: z.array(z.string()).optional()
 });
 
+function normalizePlanImplementationOutput(
+  rawOutput: z.infer<typeof PlanImplementationOutputSchema>
+): z.infer<typeof PlanImplementationOutputSchema> {
+  const output = pickStructuredOutput(rawOutput, ['implementationPlan']);
+  const implementationPlan =
+    output?.implementationPlan && typeof output.implementationPlan === 'object'
+      ? output.implementationPlan
+      : {};
+  const testingStrategy =
+    output?.testingStrategy && typeof output.testingStrategy === 'object'
+      ? output.testingStrategy
+      : {};
+  return {
+    implementationPlan: {
+      overview: typeof implementationPlan.overview === 'string' ? implementationPlan.overview : '',
+      milestones: Array.isArray(implementationPlan.milestones) ? implementationPlan.milestones : [],
+      dependencies: Array.isArray(implementationPlan.dependencies) ? implementationPlan.dependencies : [],
+    },
+    testingStrategy: {
+      approach: typeof testingStrategy.approach === 'string' ? testingStrategy.approach : '',
+      testTypes: Array.isArray(testingStrategy.testTypes) ? testingStrategy.testTypes : [],
+      coverage: typeof testingStrategy.coverage === 'string' ? testingStrategy.coverage : '',
+    },
+    validationCriteria: Array.isArray(output?.validationCriteria) ? output.validationCriteria : [],
+    definitionOfRead: Array.isArray(output?.definitionOfRead) ? output.definitionOfRead : undefined,
+    readSatisfactionCriteria: Array.isArray(output?.readSatisfactionCriteria)
+      ? output.readSatisfactionCriteria
+      : undefined,
+  };
+}
+
 export function applyPlanImplementationSemanticMirrors(
-  output: z.infer<typeof PlanImplementationOutputSchema>
+  rawOutput: z.infer<typeof PlanImplementationOutputSchema>
 ): z.infer<typeof PlanImplementationOutputSchema> {
+  const output = normalizePlanImplementationOutput(rawOutput);
   return {
     ...output,
     readSatisfactionCriteria: output.readSatisfactionCriteria ?? output.definitionOfRead,

uapi/app/api/pipeline-harness/asset-pack/route.ts

@@ -23,6 +23,9 @@ type AssetPackHarnessRequest = {
   depositAssetId?: string | null;
   depositHasWalletOrAttestationProof?: boolean;
   depositHasAssetMeasurementEvidence?: boolean;
+  depositProofRoot?: string | null;
+  depositMeasurementRoot?: string | null;
+  depositReconciliationReadbackRoot?: string | null;
   repositoryFullName?: string;
   sourceBranch?: string;
   sourceCommit?: string;
@@ -529,6 +532,9 @@ export async function POST(request: NextRequest): Promise<Response> {
               assetId: body.depositAssetId || null,
               hasWalletOrAttestationProof: body.depositHasWalletOrAttestationProof,
               hasAssetMeasurementEvidence: body.depositHasAssetMeasurementEvidence,
+              proofRoot: body.depositProofRoot || null,
+              measurementRoot: body.depositMeasurementRoot || null,
+              reconciliationReadbackRoot: body.depositReconciliationReadbackRoot || null,
             },
             sourceRevision: {
               repositoryFullName,