V48 (impl-only): Close settle dual-write and prefs dual-read

Host evidence, completion schema, and mocks emit settleDelivery with
historical shippables dual-write. Header props use settleDelivery.
Template prefs dual-read delivery_templates and shippable_templates.
Migrate measure needinesses and tests to MeasurementKindCategory while
keeping measurement aliases for remaining consumers. Typecheck green;
focused tests pass.

Author: geraldarthurdavis

apps/uapi/components/bitcode/pipeline/ExecutionsCompleteHeaderContent/ExecutionsCompleteHeaderContent.tsx

@@ -78,6 +78,8 @@ export type RepoSnapshot = { org: string; repo: string; branch: string; commit:
 
 export type HeaderAssetPackCompletion = {
   summary?: string | null;
+  settleDelivery?: HeaderSettleDelivery;
+  /** Historical dual-write of settleDelivery. */
   shippables?: HeaderSettleDelivery;
   assetPackSynthesisArtifacts?: HeaderSettleDelivery;
   writtenAssets?: HeaderSettleDelivery;
@@ -105,13 +107,13 @@ const formatWrittenAssetType = (type?: string | null) => {
 };
 
 export function CompleteHeaderContent({
-  shippables,
+  settleDelivery,
   processingStats,
   repoSnapshot,
   postprocessed,
   executionType,
 }: {
-  shippables?: HeaderSettleDelivery;
+  settleDelivery?: HeaderSettleDelivery;
   processingStats?: HeaderProcessingStats;
   repoSnapshot?: RepoSnapshot;
   postprocessed?: any;
@@ -123,7 +125,7 @@ export function CompleteHeaderContent({
   // - processingStats and repoSnapshot are sourced from server-computed asset_pack_completion objects
   //   emitted by both pipelines. The UI renders only server-provided values.
   const [showFileDetails, setShowFileDetails] = React.useState(false);
-  const settleDeliverySurface = shippables || {};
+  const settleDeliverySurface = settleDelivery || {};
   const tldr: React.ReactNode[] = [];
   if (settleDeliverySurface?.pullRequest) {
     const pr = settleDeliverySurface.pullRequest;
@@ -347,7 +349,7 @@ export function getHeaderSettleDelivery(
 ): HeaderSettleDelivery | null {
   // Prefer settleDelivery; dual-read historical shippables.
   return (
-    (assetPackCompletion as any)?.settleDelivery ||
+    assetPackCompletion?.settleDelivery ||
     assetPackCompletion?.shippables ||
     assetPackCompletion?.deliveryMechanism ||
     null

apps/uapi/components/bitcode/pipeline/ExecutionsPageHeader/ExecutionsPageHeader.tsx

@@ -242,7 +242,7 @@ interface ExecutionPageHeaderProps {
   templates?: DeliveryTemplateSets;
   onTemplateSelect?: (templateId: string, templateCategory: keyof DeliveryTemplateSets) => void;
   /** Settle delivery (buyer PR after rights). Bitcode-owned meaning lives in AssetPack evidence first. */
-  shippables?: {
+  settleDelivery?: {
     pullRequest?: DeliveryMechanismSurface | null; // Singular PR delivery mechanism.
     fileChanges?: FileChanges | null;
     summary?: string | null;
@@ -339,7 +339,7 @@ const childVariants = {
  */
 export default function ExecutionsPageHeader({
   executionStatus: mode,
-  shippables,
+  settleDelivery,
   processingStats,
   repoSnapshot,
   onSelectDeliveryTemplateDefinitionOfNeed,
@@ -491,7 +491,7 @@ export default function ExecutionsPageHeader({
     };
   }, [entranceSpeedFactor]);
 
-  const effectiveSettleDelivery = shippables ?? {};
+  const effectiveSettleDelivery = settleDelivery ?? {};
   const effectiveMode = mode;
   const iterationConfidence = typeof processingStats?.confidence === 'number' ? processingStats?.confidence : undefined;
   const awaitingInstruction = processingStats?.awaitingInstruction ?? (typeof iterationConfidence === 'number' ? iterationConfidence < INSTRUCTION_WAIT_THRESHOLD : false);
@@ -806,7 +806,7 @@ export default function ExecutionsPageHeader({
 
           {effectiveMode === "executed" && effectiveSettleDelivery && (renderDocInsideHeader !== false) && (
             <CompleteHeaderContent
-              shippables={effectiveSettleDelivery as any}
+              settleDelivery={effectiveSettleDelivery as any}
               processingStats={processingStats as any}
               repoSnapshot={repoSnapshot as any}
               executionType={executionType}

apps/uapi/hooks/useTemplatePreferences.ts

@@ -2,11 +2,13 @@ import { useCallback, useEffect, useState } from 'react';
 
 interface UserTemplatePreferencesApiResponse {
   shippable_templates?: Record<string, string[]>;
+  delivery_templates?: Record<string, string[]>;
   evidence_document_templates?: Record<string, string[]>;
 }
 
 export interface UserTemplatePreferences {
   shippable_templates: Record<string, string[]>;
+  delivery_templates: Record<string, string[]>;
   evidence_document_templates: Record<string, string[]>;
 }
 
@@ -22,7 +24,8 @@ interface UseTemplatePreferencesHook {
 
 /**
  * Client-side hook that fetches the current user's saved template
- * preferences (Shippable & Evidence Document) from `/api/auxillaries/template-preferences`.
+ * preferences (delivery templates & evidence documents) from
+ * `/api/auxillaries/template-preferences`.
  *
  * It automatically fetches once on mount but also returns a `reload`
  * function should the caller read to refresh the data (e.g. after a
@@ -41,6 +44,7 @@ export const useTemplatePreferences = (): UseTemplatePreferencesHook => {
       if (res.status === 401 || res.status === 404) {
         setPreferences({
           shippable_templates: {},
+        delivery_templates: {},
           evidence_document_templates: {},
         });
         return;
@@ -61,12 +65,14 @@ export const useTemplatePreferences = (): UseTemplatePreferencesHook => {
       const data = (await res.json()) as UserTemplatePreferencesApiResponse;
 
       setPreferences({
-        shippable_templates: data.shippable_templates ?? {},
+        shippable_templates: data.delivery_templates ?? data.shippable_templates ?? {},
+        delivery_templates: data.delivery_templates ?? data.shippable_templates ?? {},
         evidence_document_templates: data.evidence_document_templates ?? {},
       });
     } catch (err) {
       setPreferences({
         shippable_templates: {},
+        delivery_templates: {},
         evidence_document_templates: {},
       });
       setError(err instanceof Error ? err.message : String(err));

apps/uapi/mocking/engines/StreamingPipelineEngine.ts

@@ -654,7 +654,8 @@ export class StreamingPipelineEngine {
         paths: ['src/mock.ts', 'README.md']
       }
     };
-    const shippables = {
+    // Settle delivery surface; dual-write historical shippables for reread.
+    const settleDelivery = {
       pullRequest: {
         url: 'https://github.com/mock/repo/pull/123',
         number: 123,
@@ -667,14 +668,15 @@ export class StreamingPipelineEngine {
     return {
       summary: writtenAssets.summary,
       display: 'Mock Asset Pack',
-      shippables,
+      settleDelivery,
+      shippables: settleDelivery,
       assetPackSynthesisArtifacts: {
-        ...shippables,
+        ...settleDelivery,
         proofEvidence: ['mock AssetPack evidence captured for reread'],
         reviewNotes: ['mock Read-satisfaction artifacts synthesized'],
       },
       writtenAssets,
-      deliveryMechanism: shippables,
+      deliveryMechanism: settleDelivery,
       semanticKind: 'asset-pack-written-asset',
       read: 'Mock retained corridor read',
       writtenAssetType: 'code-change',

apps/uapi/mocking/generators/MockDataGenerators.ts

@@ -477,7 +477,8 @@ class CompletionDataGenerator extends BaseDataGenerator {
         paths: ['src/main.ts', 'README.md', 'package.json'].slice(0, Math.floor(Math.random() * 3) + 1)
       } : null
     };
-    const shippables = {
+    // Settle delivery surface (buyer PR after rights); dual-write historical key.
+    const settleDelivery = {
       pullRequest: hasPR ? {
         url: 'https://github.com/mock/repo/pull/123',
         number: 123,
@@ -491,14 +492,15 @@ class CompletionDataGenerator extends BaseDataGenerator {
     return {
       summary: writtenAssets.summary || this.generateRealisticText(25),
       display: 'Mock Asset Pack',
-      shippables,
+      settleDelivery,
+      shippables: settleDelivery,
       assetPackSynthesisArtifacts: {
-        ...shippables,
+        ...settleDelivery,
         proofEvidence: ['mock AssetPack evidence captured for reread'],
         reviewNotes: ['mock Read-satisfaction artifacts synthesized'],
       },
       writtenAssets,
-      deliveryMechanism: shippables,
+      deliveryMechanism: settleDelivery,
       semanticKind: 'asset-pack-written-asset',
       read: this.generateRealisticText(10),
       writtenAssetType: this.pickRandom(['code-change', 'code-change-review', 'design-document']),

packages/agent-generics/src/__tests__/measure-agent.test.ts

@@ -1,8 +1,8 @@
 // @ts-nocheck
 import {
   factoryMeasureAgent,
-  factoryMeasureAgentAbsolutes,
-  MeasureAgentOutputSchema,
+  factoryAbsolutesMeasureAgent,
+  MeasurementOutputSchema,
   MeasurementReadingSchema,
 } from '../index';
 
@@ -27,8 +27,8 @@ describe('measure-agent base hierarchy', () => {
     expect(agent.measurementSpecs[0].measurementKind).toBe('function-count');
   });
 
-  it('factoryMeasureAgentAbsolutes bases measure-agent with the absolute category', () => {
-    const agent = factoryMeasureAgentAbsolutes({
+  it('factoryAbsolutesMeasureAgent bases measure-agent with the absolute category', () => {
+    const agent = factoryAbsolutesMeasureAgent({
       name: 'test-measure-absolutes',
       subject: 'a synthesized source-safe AssetPack patch',
       measurements: SIZES,
@@ -41,7 +41,7 @@ describe('measure-agent base hierarchy', () => {
 
   it('rejects an empty measurement catalog', () => {
     expect(() =>
-      factoryMeasureAgentAbsolutes({
+      factoryAbsolutesMeasureAgent({
         name: 'empty',
         subject: 'nothing',
         measurements: [],
@@ -50,7 +50,7 @@ describe('measure-agent base hierarchy', () => {
   });
 
   it('output schema accepts readings (magnitude optional) and rejects out-of-range volume', () => {
-    const ok = MeasureAgentOutputSchema.safeParse({
+    const ok = MeasurementOutputSchema.safeParse({
       measurements: [
         { measurementKind: 'function-count', magnitude: 12, volume: 0.6, rationale: 'twelve functions' },
         { measurementKind: 'correctness-estimate', volume: 0.8, rationale: 'coherent' },

packages/agent-generics/src/index.ts

@@ -103,6 +103,7 @@ export {
   MeasurementReadingSchema,
   MeasurementOutputSchema,
   MeasureAgentOutputSchema,
+  type MeasurementKindCategory,
   type MeasurementCategory,
   type MeasurementSpec,
   type MeasurementReading,

packages/api/src/routes/auxillaries-contract.ts

@@ -884,6 +884,7 @@ export function buildAuxillariesPreferencePosture(input: {
   const modelRecord = asRecord(toAuxillariesJsonSafe(input.modelPreferences ?? null));
   const templateRecord = asRecord(toAuxillariesJsonSafe(input.templatePreferences ?? null));
   const shippableTemplates =
+    asRecord(templateRecord?.delivery_templates) ??
     asRecord(templateRecord?.shippable_templates) ??
     asRecord(templateRecord?.deliverable_templates);
   const evidenceDocumentTemplates =

packages/api/src/routes/auxillaries.ts

@@ -18,6 +18,7 @@ import {
 
 const EMPTY_TEMPLATE_PREFERENCES = {
   shippable_templates: {},
+  delivery_templates: {},
   evidence_document_templates: {},
   auto_save_templates: false,
 };
@@ -361,6 +362,7 @@ export function buildGetAuxillaryDataRoute(options: AuxillaryRouteBuilderOptions
     const templatePreferences = templatePreferencesResult.data
       ? {
           shippable_templates: templatePreferencesResult.data.deliverable_templates || {},
+          delivery_templates: templatePreferencesResult.data.deliverable_templates || {},
           evidence_document_templates: templatePreferencesResult.data.ai_document_templates || {},
           auto_save_templates: Boolean(templatePreferencesResult.data.auto_save_templates),
         }
@@ -546,6 +548,7 @@ export function buildGetAuxillaryTemplatePreferencesRoute(options: AuxillaryRout
 
     return createJsonResponse({
       shippable_templates: data.deliverable_templates || {},
+      delivery_templates: data.deliverable_templates || {},
       evidence_document_templates: data.ai_document_templates || {},
     });
   });
@@ -574,34 +577,25 @@ export function buildPostAuxillaryTemplatePreferencesRoute(options: AuxillaryRou
       return createJsonResponse({ error: 'Invalid JSON' }, 400);
     }
 
-    const payload =
-      body && typeof body === 'object'
-        ? {
-            shippable_templates:
-              typeof (body as Record<string, unknown>).shippable_templates === 'object' &&
-              (body as Record<string, unknown>).shippable_templates !== null
-                ? (body as Record<string, unknown>).shippable_templates
-                : null,
-            evidence_document_templates:
-              typeof (body as Record<string, unknown>).evidence_document_templates === 'object' &&
-              (body as Record<string, unknown>).evidence_document_templates !== null
-                ? (body as Record<string, unknown>).evidence_document_templates
-                : null,
-          }
-        : {
-            shippable_templates: null,
-            evidence_document_templates: null,
-          };
-
-    if (!payload.shippable_templates || !payload.evidence_document_templates) {
+    const asObject = (value: unknown) =>
+      typeof value === 'object' && value !== null ? value : null;
+    const bodyRecord =
+      body && typeof body === 'object' ? (body as Record<string, unknown>) : null;
+    // Prefer delivery_templates; dual-read historical shippable_templates.
+    const deliveryTemplates =
+      asObject(bodyRecord?.delivery_templates) ||
+      asObject(bodyRecord?.shippable_templates);
+    const evidenceDocumentTemplates = asObject(bodyRecord?.evidence_document_templates);
+
+    if (!deliveryTemplates || !evidenceDocumentTemplates) {
       return createJsonResponse({ error: 'Invalid template preferences format' }, 400);
     }
 
     const { error: upsertError } = await supabaseAdmin.from('user_template_preferences').upsert(
       {
         user_id: user.id,
-        deliverable_templates: payload.shippable_templates,
-        ai_document_templates: payload.evidence_document_templates,
+        deliverable_templates: deliveryTemplates,
+        ai_document_templates: evidenceDocumentTemplates,
         updated_at: new Date().toISOString(),
       },
       { onConflict: 'user_id' },

packages/asset-packs-pipelines/domain/src/agents/finish/asset-pack-completion-agent.ts

@@ -52,12 +52,17 @@ const DeliveryMechanismSchema = z.object({
     .optional(),
 });
 
+const SettleDeliverySurfaceSchema = z.object({
+  pullRequest: ShippableSchema.nullable().optional(),
+  fileChanges: FileChangesSchema.nullable().optional(),
+  summary: z.string().nullable().optional(),
+});
+
 export const AssetPackCompletionOutputSchema = z.object({
-  shippables: z.object({
-    pullRequest: ShippableSchema.nullable().optional(),
-    fileChanges: FileChangesSchema.nullable().optional(),
-    summary: z.string().nullable().optional(),
-  }),
+  /** Canonical settle delivery surface (buyer PR after rights). */
+  settleDelivery: SettleDeliverySurfaceSchema.optional(),
+  /** Historical dual-write of settleDelivery for reread clients. */
+  shippables: SettleDeliverySurfaceSchema,
   assetPackSynthesisArtifacts: AssetPackSynthesisArtifactsSchema.optional(),
   writtenAssets: WrittenAssetsSchema.optional(),
   deliveryMechanism: DeliveryMechanismSchema.optional(),
@@ -256,8 +261,9 @@ const AssetPackCompletionAgent = factoryAgentWithSingleStep<any, AssetPackComple
       readiness: deliveryReadiness,
     };
 
-    // Validate and finalize output (schema still names shippables; dual-store settleDelivery).
+    // Validate and finalize output — dual-write settleDelivery + shippables.
     const validated = AssetPackCompletionOutputSchema.parse({
+      settleDelivery: shippables,
       shippables,
       assetPackSynthesisArtifacts,
       writtenAssets,