pi-background-tasks 1.0.7 → 2.1.1

package/src/core/fusion/artifacts.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { chmod, mkdir } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { canonicalJson, sha256Buffer } from '../attested-pi-run.js';
@@ -6,6 +6,7 @@ import { sanitizePathSegment } from '../common.js';
 import { replaceFileDurable } from '../durable-fs.js';
 import {
   EMPTY_FUSION_USAGE,
+  FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
   FUSION_MANIFEST_SCHEMA_VERSION,
   FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
   FusionError,
@@ -16,9 +17,12 @@ import {
   type FusionBudgetPlanV1,
   type FusionCalibrationViolation,
   type FusionCandidateId,
+  type FusionCandidateOutputRecovery,
   type FusionCapability,
   type FusionContextOmissionLedgerV2,
   type FusionChildRunResult,
+  type FusionCommittedResultV1,
+  type FusionResultDetails,
   type FusionModelConfigV1,
   type FusionSource,
   type FusionStage,
@@ -29,6 +33,10 @@ import {
   type ResolvedFusionModels,
 } from './types.js';
 import { fusionWorkflowProfile, type FusionWorkflowProfile } from './workflows.js';
+import {
+  FUSION_CANDIDATE_MAX_OUTPUT_BYTES,
+  fusionJsonRenderedTextBytes,
+} from './output-contract.js';
 
 /**
  * Run ids are prefixed by workflow so an artifact directory is self-describing.
@@ -57,8 +65,17 @@ interface MutableFusionArtifactManifest {
     evaluation: FusionCapability;
     merge: FusionCapability;
   };
-  context: { kind: import('./types.js').FusionContextKind; policy_id: string; ledger_artifact?: string; source_policy_artifact?: string };
-  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
+  context: {
+    kind: import('./types.js').FusionContextKind;
+    policy_id: string;
+    ledger_artifact?: string;
+    source_policy_artifact?: string;
+  };
+  tool_policy: {
+    candidate_tools: readonly string[];
+    evaluation_tools: readonly [];
+    merge_tools: readonly [];
+  };
   usage: FusionUsage;
   attempts: FusionAttemptArtifactRecord[];
   artifacts: Record<string, FusionArtifactRef>;
@@ -123,7 +140,9 @@ export interface RecordFusionFailedAttemptInput {
   stderr: Buffer;
   error: string;
   status: 'failed' | 'cancelled';
+  childCreated: boolean;
   responseKind: 'md' | 'txt';
+  outputRecovery?: FusionCandidateOutputRecovery;
   provider?: string;
   model?: string;
   qualifiedId?: string;
@@ -206,7 +225,11 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     models: manifest.models,
     capabilities: manifest.capabilities,
     context: { ...manifest.context },
-    tool_policy: { candidate_tools: [...manifest.tool_policy.candidate_tools], evaluation_tools: [], merge_tools: [] },
+    tool_policy: {
+      candidate_tools: [...manifest.tool_policy.candidate_tools],
+      evaluation_tools: [],
+      merge_tools: [],
+    },
     usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
@@ -234,6 +257,59 @@ function calibrationViolationName(prefix: string): string {
   return `${prefix}.calibration-violation.json`;
 }
 
+function oversizedResponseName(prefix: string, kind: 'md' | 'txt'): string {
+  return `${prefix}.response.oversized.${kind}`;
+}
+
+function validateOutputRecovery(
+  recovery: FusionCandidateOutputRecovery,
+  replacementText?: string,
+): void {
+  if (recovery.limit_bytes !== FUSION_CANDIDATE_MAX_OUTPUT_BYTES) {
+    throw errorForArtifact('fusion output recovery limit mismatches the candidate contract');
+  }
+  const originalBytes = Buffer.from(recovery.original_text, 'utf8');
+  if (createHash('sha256').update(originalBytes).digest('hex') !== recovery.original_text_sha256) {
+    throw errorForArtifact('fusion output recovery original text hash mismatch');
+  }
+  if (
+    fusionJsonRenderedTextBytes(recovery.original_text) !== recovery.original_json_rendered_bytes
+  ) {
+    throw errorForArtifact('fusion output recovery original JSON-rendered byte count mismatch');
+  }
+  if (recovery.original_json_rendered_bytes <= recovery.limit_bytes) {
+    throw errorForArtifact('fusion output recovery original did not exceed the candidate contract');
+  }
+  if (replacementText !== undefined) {
+    const replacementBytes = fusionJsonRenderedTextBytes(replacementText);
+    if (replacementBytes !== recovery.replacement_json_rendered_bytes) {
+      throw errorForArtifact(
+        'fusion output recovery replacement JSON-rendered byte count mismatch',
+      );
+    }
+    if (recovery.status === 'completed' && replacementBytes > recovery.limit_bytes) {
+      throw errorForArtifact('completed fusion output recovery replacement exceeds the contract');
+    }
+  }
+}
+
+function outputRecoveryRecord(
+  recovery: FusionCandidateOutputRecovery,
+  path: string,
+): NonNullable<FusionAttemptArtifactRecord['output_recovery']> {
+  return {
+    kind: recovery.kind,
+    status: recovery.status,
+    limit_bytes: recovery.limit_bytes,
+    original_response_path: path,
+    original_record_index: recovery.original_record_index,
+    replacement_record_index: recovery.replacement_record_index,
+    original_json_rendered_bytes: recovery.original_json_rendered_bytes,
+    replacement_json_rendered_bytes: recovery.replacement_json_rendered_bytes,
+    original_text_sha256: recovery.original_text_sha256,
+  };
+}
+
 function artifactRefSha256Hex(value: string): string {
   const hex = value.startsWith('sha256:') ? value.slice('sha256:'.length) : value;
   if (!/^[0-9a-f]{64}$/u.test(hex)) {
@@ -295,8 +371,18 @@ export class FusionArtifactStore {
         evaluation: 'reason',
         merge: 'reason',
       },
-      context: { kind: profile.contextKind, policy_id: profile.contextKind === 'session_projection' ? 'fusion-session-projection-v1' : 'fusion-clean-task-v1' },
-      tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
+      context: {
+        kind: profile.contextKind,
+        policy_id:
+          profile.contextKind === 'session_projection'
+            ? 'fusion-session-projection-v1'
+            : 'fusion-clean-task-v1',
+      },
+      tool_policy: {
+        candidate_tools: profile.candidateTools,
+        evaluation_tools: [],
+        merge_tools: [],
+      },
       usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
@@ -327,6 +413,12 @@ export class FusionArtifactStore {
     return this.artifactPath(`${attemptPrefix(stage, slot, attempt)}.tool-calls.jsonl`);
   }
 
+  childOutputRecoveryPath(slot: 1 | 2 | 3, attempt: number, responseKind: 'md' | 'txt'): string {
+    return this.artifactPath(
+      oversizedResponseName(attemptPrefix('candidate', slot, attempt), responseKind),
+    );
+  }
+
   snapshot(): FusionArtifactManifest {
     return publicManifest(this.manifest);
   }
@@ -339,11 +431,18 @@ export class FusionArtifactStore {
           childCreated: false,
         });
       }
-      if (to === 'completed' && manifest.artifacts['merged.md'] === undefined) {
-        throw new FusionError('fusion cannot complete before merged.md is durable', {
-          code: 'state_transition_invalid',
-          childCreated: false,
-        });
+      if (
+        to === 'completed' &&
+        (manifest.artifacts['merged.md'] === undefined ||
+          manifest.artifacts['result.json'] === undefined)
+      ) {
+        throw new FusionError(
+          'fusion cannot complete before merged.md and result.json are durable',
+          {
+            code: 'state_transition_invalid',
+            childCreated: false,
+          },
+        );
       }
       manifest.state = to;
     });
@@ -403,8 +502,21 @@ export class FusionArtifactStore {
     await this.writeArtifact('evaluation.json', canonicalJson(value));
   }
 
-  async writeMerged(text: string): Promise<void> {
-    await this.writeArtifact('merged.md', text);
+  async writeMerged(text: string): Promise<FusionArtifactRef> {
+    return this.writeArtifact('merged.md', text);
+  }
+
+  async writeCommittedResult(
+    merged: FusionArtifactRef,
+    details: FusionResultDetails,
+  ): Promise<FusionArtifactRef> {
+    const value: FusionCommittedResultV1 = {
+      schema_version: FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
+      run_id: this.runId,
+      merged,
+      details,
+    };
+    return this.writeArtifact('result.json', `${canonicalJson(value)}\n`);
   }
 
   async writeError(state: Exclude<FusionTerminalState, 'completed'>, error: string): Promise<void> {
@@ -436,11 +548,22 @@ export class FusionArtifactStore {
       input.result.toolCallTrace === undefined
         ? undefined
         : await this.writeArtifact(`${prefix}.tool-calls.jsonl`, input.result.toolCallTrace.bytes);
+    if (input.result.outputRecovery !== undefined) {
+      validateOutputRecovery(input.result.outputRecovery, input.result.text);
+    }
+    const outputRecoveryRef =
+      input.result.outputRecovery === undefined
+        ? undefined
+        : await this.writeArtifact(
+            oversizedResponseName(prefix, input.responseKind),
+            input.result.outputRecovery.original_text,
+          );
     await this.updateManifest((manifest) => {
       const record: FusionAttemptArtifactRecord = {
         stage: input.result.stage,
         attempt: input.result.attempt,
         status: 'completed',
+        child_created: true,
         prompt_path: promptRef.path,
         events_path: eventsRef.path,
         stderr_path: stderrRef.path,
@@ -454,6 +577,12 @@ export class FusionArtifactStore {
         record.tool_calls_path = toolCallsRef.path;
         record.tool_calls = { ...input.result.toolCallTrace.summary };
       }
+      if (outputRecoveryRef !== undefined && input.result.outputRecovery !== undefined) {
+        record.output_recovery = outputRecoveryRecord(
+          input.result.outputRecovery,
+          outputRecoveryRef.path,
+        );
+      }
       if (input.result.slot !== undefined) record.slot = input.result.slot;
       manifest.attempts.push(record);
     });
@@ -466,20 +595,26 @@ export class FusionArtifactStore {
     violation: FusionCalibrationViolation;
   }): Promise<FusionArtifactRef> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
-    return this.writeArtifact(calibrationViolationName(prefix), `${canonicalJson(input.violation)}\n`);
+    return this.writeArtifact(
+      calibrationViolationName(prefix),
+      `${canonicalJson(input.violation)}\n`,
+    );
   }
 
   async recordValidationCandidateContractEvent(
     input: RecordValidationCandidateContractEventInput,
   ): Promise<FusionArtifactRef> {
     const name = `candidate-${String(input.slot)}.output-contract-${input.status}.json`;
-    return this.writeArtifact(name, `${canonicalJson({
-      schema_version: FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
-      ...input.detail,
-      candidate_id: input.candidateId,
-      slot: input.slot,
-      status: input.status,
-    })}\n`);
+    return this.writeArtifact(
+      name,
+      `${canonicalJson({
+        schema_version: FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
+        ...input.detail,
+        candidate_id: input.candidateId,
+        slot: input.slot,
+        status: input.status,
+      })}\n`,
+    );
   }
 
   async recordFailedAttempt(input: RecordFusionFailedAttemptInput): Promise<void> {
@@ -496,11 +631,20 @@ export class FusionArtifactStore {
             `${prefix}.response.partial.${input.responseKind}`,
             input.partialResponse,
           );
+    if (input.outputRecovery !== undefined) validateOutputRecovery(input.outputRecovery);
+    const outputRecoveryRef =
+      input.outputRecovery === undefined
+        ? undefined
+        : await this.writeArtifact(
+            oversizedResponseName(prefix, input.responseKind),
+            input.outputRecovery.original_text,
+          );
     await this.updateManifest((manifest) => {
       const record: FusionAttemptArtifactRecord = {
         stage: input.stage,
         attempt: input.attempt,
         status: input.status,
+        child_created: input.childCreated,
         prompt_path: promptRef.path,
         events_path: eventsRef.path,
         stderr_path: stderrRef.path,
@@ -508,6 +652,9 @@ export class FusionArtifactStore {
         error: input.error,
       };
       if (partialResponseRef !== undefined) record.partial_response_path = partialResponseRef.path;
+      if (outputRecoveryRef !== undefined && input.outputRecovery !== undefined) {
+        record.output_recovery = outputRecoveryRecord(input.outputRecovery, outputRecoveryRef.path);
+      }
       if (input.provider !== undefined) record.provider = input.provider;
       if (input.model !== undefined) record.model = input.model;
       if (input.qualifiedId !== undefined) record.qualifiedId = input.qualifiedId;

package/src/core/fusion/budget.ts

@@ -23,6 +23,20 @@ import {
   type AnonymousFusionCandidate,
 } from './prompts.js';
 import { FUSION_REASON_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
+import {
+  FUSION_CANDIDATE_MAX_OUTPUT_BYTES,
+  FUSION_DIAGNOSTICS_MAX_BYTES,
+  FUSION_EVALUATION_MAX_OUTPUT_BYTES,
+  FUSION_MERGE_MAX_OUTPUT_BYTES,
+} from './output-contract.js';
+export {
+  FUSION_CANDIDATE_MAX_OUTPUT_BYTES,
+  FUSION_DIAGNOSTICS_MAX_BYTES,
+  FUSION_EVALUATION_MAX_OUTPUT_BYTES,
+  FUSION_MERGE_MAX_OUTPUT_BYTES,
+  assertChildOutputWithinContract,
+  fusionOutputContractBytes,
+} from './output-contract.js';
 import {
   FUSION_BUDGET_PLAN_SCHEMA_VERSION,
   FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION,
@@ -54,11 +68,6 @@ import {
 
 export const FUSION_CALIBRATED_BYTES_PER_TOKEN = TOKEN_BUDGET_FAMILY_CALIBRATIONS;
 
-export const FUSION_CANDIDATE_MAX_OUTPUT_BYTES = 48 * 1024;
-export const FUSION_EVALUATION_MAX_OUTPUT_BYTES = 64 * 1024;
-export const FUSION_MERGE_MAX_OUTPUT_BYTES = 64 * 1024;
-export const FUSION_DIAGNOSTICS_MAX_BYTES = 8 * 1024;
-
 const FUSION_OUTPUT_RESERVE_RATE_X100 = 200;
 export const FUSION_UTILIZATION_WARNING_THRESHOLD_BASIS_POINTS = 8000;
 const BASIS_POINTS_DENOMINATOR = 10_000;
@@ -243,22 +252,6 @@ export function fusionTokenUpperBound(utf8Bytes: number): number {
   }).tokens;
 }
 
-export function fusionOutputContractBytes(stage: FusionStage): number {
-  if (stage === 'candidate') return FUSION_CANDIDATE_MAX_OUTPUT_BYTES;
-  if (stage === 'evaluation') return FUSION_EVALUATION_MAX_OUTPUT_BYTES;
-  return FUSION_MERGE_MAX_OUTPUT_BYTES;
-}
-
-export function assertChildOutputWithinContract(stage: FusionStage, text: string): void {
-  const bytes = Buffer.byteLength(JSON.stringify(text), 'utf8');
-  const allowed = fusionOutputContractBytes(stage);
-  if (bytes <= allowed) return;
-  throw new FusionError(
-    `fusion ${stage} response is ${String(bytes)} JSON-rendered bytes, exceeding the ${String(allowed)}-byte output contract for that stage; the response is preserved in the run artifacts and is not forwarded or truncated`,
-    { code: 'child_output_cap', stage, childCreated: true },
-  );
-}
-
 function utf8Bytes(value: string): number {
   return Buffer.byteLength(value, 'utf8');
 }
@@ -563,6 +556,13 @@ function entryLabel(entry: FusionStageBudgetPlanEntry): string {
   return `${entry.budget_stage}${slot}${conditional}`;
 }
 
+function blockingChildLabel(entry: FusionStageBudgetPlanEntry): string {
+  if (entry.budget_stage === 'candidate') return `candidate-${String(entry.slot ?? 1)}`;
+  if (entry.budget_stage === 'evaluation_repair') return 'evaluator-repair';
+  if (entry.budget_stage === 'evaluation') return 'evaluator';
+  return 'merger';
+}
+
 function formatTable(entries: readonly FusionStageBudgetPlanEntry[]): string {
   const lines = entries.map(
     (entry) =>
@@ -983,10 +983,10 @@ export class FusionBudget {
           ? ' Dominant byte class is dense ASCII/low-whitespace content; the whitespace gate is a heuristic token-density proxy, not a bound.'
           : ` Dominant byte class is ${dominantByteClass}.`;
     const message =
-      `Fusion prompt budget exceeded by ${checkText} before child creation. Primary blocking stage: ${entryLabel(primary)} on route ${primary.route.qualified_id}. ` +
+      `Fusion prompt budget exceeded by ${checkText} before ${blockingChildLabel(primary)} child creation. Primary blocking stage: ${entryLabel(primary)} on route ${primary.route.qualified_id}. ` +
       `Forecast ${String(primary.input_utf8_bytes)} UTF-8 bytes (<= ${String(primary.input_only_input_tokens_upper_bound)} input tokens) against ${String(primary.allowed_input_tokens)} allowed input tokens, over by ${String(Math.max(0, tokensOver))} tokens. ` +
       `Estimator: ${rateText}.${routeWarning}${dominantText} ` +
-      `No child was created. Nothing was clipped, dropped, or substituted. Artifact directory: ${artifactDir}.\n` +
+      `The ${blockingChildLabel(primary)} child was not created. Nothing was clipped, dropped, or substituted. Artifact directory: ${artifactDir}.\n` +
       `Per-stage forecast table:\n${formatTable(plan.stages)}\n` +
       `Primary blocker byte composition: ${compositionText}.\n` +
       `Additional blockers: ${additional.length === 0 ? 'none' : additional}.\n` +

package/src/core/fusion/child-protocol.ts

@@ -1,14 +1,19 @@
 import { createHash } from 'node:crypto';
 import type { Usage } from '@earendil-works/pi-ai';
 import type { FusionClaudeCacheObservation } from './claude-cache.js';
+import {
+  FUSION_CANDIDATE_MAX_OUTPUT_BYTES,
+  fusionJsonRenderedTextBytes,
+} from './output-contract.js';
 
 export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-child-result.v3' as const;
+  'pi-background-tasks.fusion-child-result.v4' as const;
 export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
 export const FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION =
-  'pi-background-tasks.fusion-child-settlement.v2' as const;
+  'pi-background-tasks.fusion-child-settlement.v3' as const;
 export const FUSION_CHILD_SETTLEMENT_PREFIX = '\u001ePI_FUSION_CHILD_SETTLEMENT ';
 export const FUSION_TOOL_CALL_LOG_PATH_ENV = 'PI_FUSION_TOOL_CALL_LOG_PATH';
+export const FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH_ENV = 'PI_FUSION_CANDIDATE_OUTPUT_RECOVERY_PATH';
 export const FUSION_RESEARCH_ENABLED_ENV = 'PI_FUSION_RESEARCH_ENABLED';
 export const FUSION_SOURCE_POLICY_PATH_ENV = 'PI_FUSION_SOURCE_POLICY_PATH';
 export const FUSION_SOURCE_POLICY_SHA256_ENV = 'PI_FUSION_SOURCE_POLICY_SHA256';
@@ -63,6 +68,14 @@ export interface FusionChildTextBlockMetadata {
 
 export type FusionChildResultUsageMetadata = Usage;
 
+export type FusionChildOutputRecoveryRole = 'none' | 'oversized_original' | 'replacement';
+
+export interface FusionChildOutputContractMetadata {
+  json_rendered_bytes: number;
+  candidate_limit_bytes: number | null;
+  recovery_role: FusionChildOutputRecoveryRole;
+}
+
 export interface FusionChildResultMetadata {
   schema_version: typeof FUSION_CHILD_RESULT_SCHEMA_VERSION;
   provider: string;
@@ -72,6 +85,7 @@ export interface FusionChildResultMetadata {
   text_sha256: string;
   usage: FusionChildResultUsageMetadata;
   cache_observation: FusionClaudeCacheObservation;
+  output_contract: FusionChildOutputContractMetadata;
 }
 
 export type FusionChildSettlementFailureReason =
@@ -79,7 +93,8 @@ export type FusionChildSettlementFailureReason =
   | 'final_not_stop'
   | 'invalid_non_final'
   | 'runtime_guard'
-  | 'cache_observation';
+  | 'cache_observation'
+  | 'output_recovery';
 
 export interface FusionChildSettlementRecord {
   schema_version: typeof FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION;
@@ -89,6 +104,7 @@ export interface FusionChildSettlementRecord {
   final_record_index: number | null;
   final_text_sha256: string | null;
   recovered_error_ordinals: number[];
+  recovered_output_cap_ordinals: number[];
   failure_reason: FusionChildSettlementFailureReason | null;
 }
 
@@ -126,7 +142,60 @@ export function isRecoverableFusionChildErrorRecord(record: FusionChildResultMet
     record.stop_reason === 'error' &&
     record.text_blocks.length === 0 &&
     record.text_sha256 === protocolSha256(Buffer.alloc(0)) &&
-    hasZeroUsage(record)
+    hasZeroUsage(record) &&
+    record.output_contract.recovery_role === 'none'
+  );
+}
+
+function isOversizedOriginal(record: FusionChildResultMetadata): boolean {
+  const output = record.output_contract;
+  return (
+    output.recovery_role === 'oversized_original' &&
+    output.candidate_limit_bytes === FUSION_CANDIDATE_MAX_OUTPUT_BYTES &&
+    output.json_rendered_bytes > FUSION_CANDIDATE_MAX_OUTPUT_BYTES &&
+    record.stop_reason === 'stop'
+  );
+}
+
+function outputRecoveryProtocolInvalid(records: readonly FusionChildResultMetadata[]): boolean {
+  const originals = records.flatMap((record, ordinal) =>
+    record.output_contract.recovery_role === 'oversized_original' ? [ordinal] : [],
+  );
+  const replacements = records.flatMap((record, ordinal) =>
+    record.output_contract.recovery_role === 'replacement' ? [ordinal] : [],
+  );
+  for (const record of records) {
+    const output = record.output_contract;
+    if (
+      output.candidate_limit_bytes !== null &&
+      output.candidate_limit_bytes !== FUSION_CANDIDATE_MAX_OUTPUT_BYTES
+    ) {
+      return true;
+    }
+    if (output.recovery_role !== 'none' && output.candidate_limit_bytes === null) return true;
+    if (output.recovery_role === 'oversized_original' && !isOversizedOriginal(record)) return true;
+  }
+  if (originals.length === 0 && replacements.length === 0) return false;
+  if (originals.length !== 1 || replacements.length !== 1) return true;
+  const original = originals[0];
+  const replacement = replacements[0];
+  return (
+    original === undefined ||
+    replacement === undefined ||
+    original !== records.length - 2 ||
+    replacement !== records.length - 1
+  );
+}
+
+function finalCandidateOutputExceedsContract(
+  records: readonly FusionChildResultMetadata[],
+): boolean {
+  const final = records.at(-1);
+  if (final === undefined) return false;
+  const output = final.output_contract;
+  return (
+    output.candidate_limit_bytes === FUSION_CANDIDATE_MAX_OUTPUT_BYTES &&
+    output.json_rendered_bytes > FUSION_CANDIDATE_MAX_OUTPUT_BYTES
   );
 }
 
@@ -134,24 +203,36 @@ export function buildFusionChildSettlement(
   records: readonly FusionChildResultMetadata[],
   runtimeGuardFailed = false,
   cacheObservationFailed = false,
+  outputRecoveryFailed = false,
 ): FusionChildSettlementRecord {
   const finalRecordIndex = records.length === 0 ? null : records.length - 1;
   const final = records.at(-1);
   const recoveredErrorOrdinals = records.flatMap((record, ordinal) =>
     ordinal < records.length - 1 && isRecoverableFusionChildErrorRecord(record) ? [ordinal] : [],
   );
+  const recoveredOutputCapOrdinals = records.flatMap((record, ordinal) =>
+    ordinal < records.length - 1 && isOversizedOriginal(record) ? [ordinal] : [],
+  );
+  const invalidRecovery = outputRecoveryProtocolInvalid(records);
   const invalidNonFinal = records.some(
     (record, ordinal) =>
       ordinal < records.length - 1 &&
       record.stop_reason !== 'toolUse' &&
-      !isRecoverableFusionChildErrorRecord(record),
+      !isRecoverableFusionChildErrorRecord(record) &&
+      !isOversizedOriginal(record),
   );
   let failureReason: FusionChildSettlementFailureReason | null = null;
   if (runtimeGuardFailed) failureReason = 'runtime_guard';
   else if (cacheObservationFailed) failureReason = 'cache_observation';
   else if (final === undefined) failureReason = 'no_records';
   else if (final.stop_reason !== 'stop') failureReason = 'final_not_stop';
-  else if (invalidNonFinal) failureReason = 'invalid_non_final';
+  else if (
+    outputRecoveryFailed ||
+    invalidRecovery ||
+    finalCandidateOutputExceedsContract(records)
+  ) {
+    failureReason = 'output_recovery';
+  } else if (invalidNonFinal) failureReason = 'invalid_non_final';
   return {
     schema_version: FUSION_CHILD_SETTLEMENT_SCHEMA_VERSION,
     status: failureReason === null ? 'complete' : 'failed',
@@ -160,6 +241,7 @@ export function buildFusionChildSettlement(
     final_record_index: finalRecordIndex,
     final_text_sha256: final?.text_sha256 ?? null,
     recovered_error_ordinals: recoveredErrorOrdinals,
+    recovered_output_cap_ordinals: recoveredOutputCapOrdinals,
     failure_reason: failureReason,
   };
 }
@@ -173,15 +255,33 @@ export function buildFusionChildResultMetadata(
     usage: Usage;
   },
   cacheObservation: FusionClaudeCacheObservation,
+  outputContract: {
+    candidateLimitBytes: number | null;
+    recoveryRole: FusionChildOutputRecoveryRole;
+  } = { candidateLimitBytes: null, recoveryRole: 'none' },
 ): FusionChildResultMetadata {
+  if (
+    outputContract.candidateLimitBytes !== null &&
+    outputContract.candidateLimitBytes !== FUSION_CANDIDATE_MAX_OUTPUT_BYTES
+  ) {
+    throw new Error('fusion child candidate output limit does not match the shared contract');
+  }
+  if (outputContract.recoveryRole !== 'none' && outputContract.candidateLimitBytes === null) {
+    throw new Error('fusion child output recovery role requires the candidate output contract');
+  }
   const textBlocks = message.content.flatMap((part) =>
     part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
   );
+  const text = textBlocks.join('');
   const usage: FusionChildResultUsageMetadata = {
     input: message.usage.input,
     output: message.usage.output,
     cacheRead: message.usage.cacheRead,
     cacheWrite: message.usage.cacheWrite,
+    ...(message.usage.cacheWrite1h === undefined
+      ? {}
+      : { cacheWrite1h: message.usage.cacheWrite1h }),
+    ...(message.usage.reasoning === undefined ? {} : { reasoning: message.usage.reasoning }),
     totalTokens: message.usage.totalTokens,
     cost: {
       input: message.usage.cost.input,
@@ -196,12 +296,17 @@ export function buildFusionChildResultMetadata(
     provider: message.provider,
     model: message.model,
     stop_reason: message.stopReason,
-    text_blocks: textBlocks.map((text) => ({
-      utf8_bytes: Buffer.byteLength(text, 'utf8'),
-      sha256: protocolSha256(text),
+    text_blocks: textBlocks.map((blockText) => ({
+      utf8_bytes: Buffer.byteLength(blockText, 'utf8'),
+      sha256: protocolSha256(blockText),
     })),
-    text_sha256: protocolSha256(textBlocks.join('')),
+    text_sha256: protocolSha256(text),
     usage,
     cache_observation: cacheObservation,
+    output_contract: {
+      json_rendered_bytes: fusionJsonRenderedTextBytes(text),
+      candidate_limit_bytes: outputContract.candidateLimitBytes,
+      recovery_role: outputContract.recoveryRole,
+    },
   };
 }

package/src/core/fusion/claude-cache.ts

@@ -5,6 +5,7 @@ export const FUSION_CLAUDE_CACHE_OBSERVATION_SCHEMA_VERSION =
 export const FUSION_CLAUDE_CACHE_RETENTION_ENV = 'PI_CACHE_RETENTION';
 export const FUSION_CLAUDE_CACHE_DEFAULT_RETENTION = 'long' as const;
 export const FUSION_CLAUDE_CACHE_BREAKPOINT_LIMIT = 4;
+export const FUSION_CLAUDE_PROMPT_CACHING_SCOPE_BETA = 'prompt-caching-scope-2026-01-05' as const;
 
 export type FusionClaudeCacheRetention = 'none' | 'short' | 'long';
 export type FusionClaudeCachePolicySource =
@@ -63,6 +64,26 @@ export function resolveFusionClaudeCachePolicy(env: Readonly<NodeJS.ProcessEnv>
   };
 }
 
+export function applyFusionClaudePromptCachingScopeHeader(
+  headers: Record<string, string | null>,
+): boolean {
+  const matchingKey = Object.keys(headers).find((key) => key.toLowerCase() === 'anthropic-beta');
+  const existing = matchingKey === undefined ? undefined : headers[matchingKey];
+  const values =
+    typeof existing === 'string'
+      ? existing
+          .split(',')
+          .map((value) => value.trim())
+          .filter((value) => value.length > 0)
+      : [];
+  if (!values.includes(FUSION_CLAUDE_PROMPT_CACHING_SCOPE_BETA)) {
+    values.push(FUSION_CLAUDE_PROMPT_CACHING_SCOPE_BETA);
+  }
+  const targetKey = matchingKey ?? 'anthropic-beta';
+  headers[targetKey] = values.join(',');
+  return true;
+}
+
 function validateCacheControl(value: unknown): JsonObject {
   if (!isRecord(value)) {
     throw new Error('Fusion Claude cache_control must be an object');