@pi-unipi/background-tasks 2.16.0 → 2.17.0

package/src/fusion/result-package.ts

@@ -1,959 +0,0 @@
-import { lstat, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { canonicalJson, sha256Buffer } from '../attested-pi-run.js';
-import { parseJsonText, type JsonObject } from '../types.js';
-import {
-  FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
-  FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
-  FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES,
-  FUSION_FAILURE_SUMMARY_MAX_BYTES,
-  assertFusionArtifactBasename,
-  buildFusionRunProgress,
-} from './artifacts.js';
-import {
-  FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
-  FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
-  FUSION_LEGACY_MANIFEST_SCHEMA_VERSION,
-  FUSION_MANIFEST_SCHEMA_VERSION,
-  FUSION_RESULT_SCHEMA_VERSION,
-  FusionError,
-  type FusionArtifactRef,
-  type FusionFailureAttemptMetadata,
-  type FusionFailureEvidenceArtifact,
-  type FusionFailureList,
-  type FusionFailureResultView,
-  type FusionFailureSummaryV1,
-  type FusionResultDetails,
-  type FusionRunResult,
-  type FusionUsage,
-  type FusionWorkflowId,
-  type FusionRunProgress,
-  type FusionSource,
-  type FusionStage,
-} from './types.js';
-
-const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
-
-function isRecord(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function fail(message: string, artifactDir: string): never {
-  throw new FusionError(`fusion committed result invalid: ${message}`, {
-    code: 'artifact_error',
-    childCreated: true,
-    artifactDir,
-  });
-}
-
-function assertOnlyKeys(
-  value: JsonObject,
-  allowed: readonly string[],
-  label: string,
-  artifactDir: string,
-): void {
-  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unexpected.length > 0)
-    fail(`${label} contains unexpected keys: ${unexpected.join(', ')}`, artifactDir);
-}
-
-function artifactRef(value: unknown, label: string, artifactDir: string): FusionArtifactRef {
-  if (!isRecord(value)) fail(`${label} must be an object`, artifactDir);
-  assertOnlyKeys(value, ['path', 'byte_length', 'sha256'], label, artifactDir);
-  const path = value['path'];
-  const byteLength = value['byte_length'];
-  const sha256 = value['sha256'];
-  if (typeof path !== 'string') fail(`${label}.path is invalid`, artifactDir);
-  try {
-    assertFusionArtifactBasename(path);
-  } catch {
-    fail(`${label}.path is invalid`, artifactDir);
-  }
-  if (!Number.isSafeInteger(byteLength) || Number(byteLength) < 0) {
-    fail(`${label}.byte_length is invalid`, artifactDir);
-  }
-  if (typeof sha256 !== 'string' || !SHA256_PATTERN.test(sha256)) {
-    fail(`${label}.sha256 is invalid`, artifactDir);
-  }
-  return { path, byte_length: Number(byteLength), sha256 };
-}
-
-function usage(value: unknown, artifactDir: string): FusionUsage {
-  if (!isRecord(value)) fail('details.usage must be an object', artifactDir);
-  assertOnlyKeys(
-    value,
-    [
-      'input',
-      'output',
-      'cacheRead',
-      'cacheWrite',
-      'cacheWrite1h',
-      'reasoning',
-      'totalTokens',
-      'cost',
-    ],
-    'details.usage',
-    artifactDir,
-  );
-  const cost = value['cost'];
-  if (!isRecord(cost)) fail('details.usage.cost must be an object', artifactDir);
-  assertOnlyKeys(
-    cost,
-    ['input', 'output', 'cacheRead', 'cacheWrite', 'total'],
-    'details.usage.cost',
-    artifactDir,
-  );
-  const finiteNonnegative = (entry: unknown, label: string): number => {
-    if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0)
-      fail(`${label} is invalid`, artifactDir);
-    return entry;
-  };
-  const output = finiteNonnegative(value['output'], 'details.usage.output');
-  const cacheWrite = finiteNonnegative(value['cacheWrite'], 'details.usage.cacheWrite');
-  const cacheWrite1h =
-    value['cacheWrite1h'] === undefined
-      ? undefined
-      : finiteNonnegative(value['cacheWrite1h'], 'details.usage.cacheWrite1h');
-  const reasoning =
-    value['reasoning'] === undefined
-      ? undefined
-      : finiteNonnegative(value['reasoning'], 'details.usage.reasoning');
-  if (cacheWrite1h !== undefined && cacheWrite1h > cacheWrite) {
-    fail('details.usage.cacheWrite1h must not exceed cacheWrite', artifactDir);
-  }
-  if (reasoning !== undefined && reasoning > output) {
-    fail('details.usage.reasoning must not exceed output', artifactDir);
-  }
-  return {
-    input: finiteNonnegative(value['input'], 'details.usage.input'),
-    output,
-    cacheRead: finiteNonnegative(value['cacheRead'], 'details.usage.cacheRead'),
-    cacheWrite,
-    ...(cacheWrite1h === undefined ? {} : { cacheWrite1h }),
-    ...(reasoning === undefined ? {} : { reasoning }),
-    totalTokens: finiteNonnegative(value['totalTokens'], 'details.usage.totalTokens'),
-    cost: {
-      input: finiteNonnegative(cost['input'], 'details.usage.cost.input'),
-      output: finiteNonnegative(cost['output'], 'details.usage.cost.output'),
-      cacheRead: finiteNonnegative(cost['cacheRead'], 'details.usage.cost.cacheRead'),
-      cacheWrite: finiteNonnegative(cost['cacheWrite'], 'details.usage.cost.cacheWrite'),
-      total: finiteNonnegative(cost['total'], 'details.usage.cost.total'),
-    },
-  };
-}
-
-function resultDetails(
-  value: unknown,
-  expected: { runId: string; workflow: FusionWorkflowId; artifactDir: string },
-): FusionResultDetails {
-  if (!isRecord(value)) fail('details must be an object', expected.artifactDir);
-  assertOnlyKeys(
-    value,
-    [
-      'schema_version',
-      'run_id',
-      'workflow',
-      'source',
-      'status',
-      'context',
-      'tool_policy',
-      'artifact_dir',
-      'models',
-      'evaluator_attempts',
-      'usage',
-      'budget',
-    ],
-    'details',
-    expected.artifactDir,
-  );
-  if (value['schema_version'] !== FUSION_RESULT_SCHEMA_VERSION)
-    fail('details schema version mismatch', expected.artifactDir);
-  if (value['run_id'] !== expected.runId) fail('details run id mismatch', expected.artifactDir);
-  if (value['workflow'] !== expected.workflow)
-    fail('details workflow mismatch', expected.artifactDir);
-  if (value['source'] !== 'command' && value['source'] !== 'tool')
-    fail('details source is invalid', expected.artifactDir);
-  if (value['status'] !== 'completed')
-    fail('details status is not completed', expected.artifactDir);
-  if (value['artifact_dir'] !== expected.artifactDir)
-    fail('details artifact directory mismatch', expected.artifactDir);
-  const context = value['context'];
-  const toolPolicy = value['tool_policy'];
-  const models = value['models'];
-  const budget = value['budget'];
-  if (!isRecord(context) || !isRecord(toolPolicy) || !isRecord(models) || !isRecord(budget)) {
-    fail('details nested contract is malformed', expected.artifactDir);
-  }
-  assertOnlyKeys(context, ['kind', 'policy_id'], 'details.context', expected.artifactDir);
-  if (
-    (context['kind'] !== 'session_projection' && context['kind'] !== 'clean_task') ||
-    typeof context['policy_id'] !== 'string'
-  ) {
-    fail('details.context is invalid', expected.artifactDir);
-  }
-  assertOnlyKeys(
-    toolPolicy,
-    ['candidate_tools', 'evaluation_tools', 'merge_tools'],
-    'details.tool_policy',
-    expected.artifactDir,
-  );
-  const stringArray = (entry: unknown): entry is string[] =>
-    Array.isArray(entry) && entry.every((item) => typeof item === 'string');
-  if (
-    !stringArray(toolPolicy['candidate_tools']) ||
-    !Array.isArray(toolPolicy['evaluation_tools']) ||
-    toolPolicy['evaluation_tools'].length !== 0 ||
-    !Array.isArray(toolPolicy['merge_tools']) ||
-    toolPolicy['merge_tools'].length !== 0
-  ) {
-    fail('details.tool_policy is invalid', expected.artifactDir);
-  }
-  assertOnlyKeys(
-    models,
-    ['candidates', 'evaluator', 'merger', 'thinking_level'],
-    'details.models',
-    expected.artifactDir,
-  );
-  if (
-    !stringArray(models['candidates']) ||
-    models['candidates'].length !== 3 ||
-    typeof models['evaluator'] !== 'string' ||
-    typeof models['merger'] !== 'string' ||
-    typeof models['thinking_level'] !== 'string'
-  ) {
-    fail('details.models is invalid', expected.artifactDir);
-  }
-  assertOnlyKeys(
-    budget,
-    [
-      'policy_id',
-      'calibration_version',
-      'route_table',
-      'rate_sources',
-      'unknown_provider_warnings',
-      'calibration_warnings',
-    ],
-    'details.budget',
-    expected.artifactDir,
-  );
-  if (
-    typeof budget['policy_id'] !== 'string' ||
-    typeof budget['calibration_version'] !== 'string' ||
-    !Array.isArray(budget['route_table']) ||
-    !Array.isArray(budget['rate_sources']) ||
-    !stringArray(budget['unknown_provider_warnings']) ||
-    !Array.isArray(budget['calibration_warnings'])
-  ) {
-    fail('details.budget is invalid', expected.artifactDir);
-  }
-  if (
-    !Number.isSafeInteger(value['evaluator_attempts']) ||
-    ![1, 2].includes(Number(value['evaluator_attempts']))
-  ) {
-    fail('details evaluator_attempts is invalid', expected.artifactDir);
-  }
-  const checkedUsage = usage(value['usage'], expected.artifactDir);
-  const candidates = models['candidates'];
-  if (!stringArray(candidates) || candidates.length !== 3)
-    fail('details.models candidates are invalid', expected.artifactDir);
-  const candidate1 = candidates[0];
-  const candidate2 = candidates[1];
-  const candidate3 = candidates[2];
-  if (candidate1 === undefined || candidate2 === undefined || candidate3 === undefined) {
-    fail('details.models candidates are incomplete', expected.artifactDir);
-  }
-  const source = value['source'];
-  const contextKind = context['kind'];
-  return {
-    schema_version: FUSION_RESULT_SCHEMA_VERSION,
-    run_id: expected.runId,
-    workflow: expected.workflow,
-    source,
-    status: 'completed',
-    context: { kind: contextKind, policy_id: context['policy_id'] },
-    tool_policy: {
-      candidate_tools: [...toolPolicy['candidate_tools']],
-      evaluation_tools: [],
-      merge_tools: [],
-    },
-    artifact_dir: expected.artifactDir,
-    models: {
-      candidates: [candidate1, candidate2, candidate3],
-      evaluator: models['evaluator'],
-      merger: models['merger'],
-      thinking_level: models['thinking_level'],
-    },
-    evaluator_attempts: Number(value['evaluator_attempts']),
-    usage: checkedUsage,
-    budget: {
-      policy_id: budget['policy_id'],
-      calibration_version: budget['calibration_version'],
-      route_table: budget['route_table'] as FusionResultDetails['budget']['route_table'],
-      rate_sources: budget['rate_sources'] as FusionResultDetails['budget']['rate_sources'],
-      unknown_provider_warnings: [...budget['unknown_provider_warnings']],
-      calibration_warnings: budget[
-        'calibration_warnings'
-      ] as FusionResultDetails['budget']['calibration_warnings'],
-    },
-  };
-}
-
-function sameRef(left: FusionArtifactRef, right: FusionArtifactRef): boolean {
-  return (
-    left.path === right.path &&
-    left.byte_length === right.byte_length &&
-    left.sha256 === right.sha256
-  );
-}
-
-async function readUtf8(
-  path: string,
-  label: string,
-  artifactDir: string,
-): Promise<{ bytes: Buffer; text: string }> {
-  let bytes: Buffer;
-  try {
-    bytes = await readFile(path);
-  } catch (error) {
-    fail(
-      `${label} is unreadable: ${error instanceof Error ? error.message : String(error)}`,
-      artifactDir,
-    );
-  }
-  let text: string;
-  try {
-    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-  } catch {
-    fail(`${label} is not well-formed UTF-8`, artifactDir);
-  }
-  return { bytes, text };
-}
-
-/** Failure retrieval has an additional bounded, no-symlink evidence-file policy. */
-async function readFailureUtf8(
-  path: string,
-  label: string,
-  artifactDir: string,
-  maxBytes: number,
-): Promise<{ bytes: Buffer; text: string }> {
-  try {
-    const metadata = await lstat(path);
-    if (!metadata.isFile() || metadata.isSymbolicLink()) {
-      fail(`${label} is not a regular artifact file`, artifactDir);
-    }
-    if (metadata.size > maxBytes) fail(`${label} exceeds its bounded artifact size`, artifactDir);
-  } catch (error) {
-    if (error instanceof FusionError) throw error;
-    fail(
-      `${label} is unreadable: ${error instanceof Error ? error.message : String(error)}`,
-      artifactDir,
-    );
-  }
-  const file = await readUtf8(path, label, artifactDir);
-  if (file.bytes.length > maxBytes) fail(`${label} exceeds its bounded artifact size`, artifactDir);
-  return file;
-}
-
-export interface ReadFusionCommittedResultOptions {
-  artifactDirAbs: string;
-  artifactDir: string;
-  runId: string;
-  workflow: FusionWorkflowId;
-}
-
-/** Verify the manifest-bound Fusion commit before returning merged bytes. */
-export async function readFusionCommittedResult(
-  options: ReadFusionCommittedResultOptions,
-): Promise<FusionRunResult> {
-  const manifestFile = await readUtf8(
-    join(options.artifactDirAbs, 'manifest.json'),
-    'manifest.json',
-    options.artifactDir,
-  );
-  let manifestValue: unknown;
-  try {
-    manifestValue = parseJsonText(manifestFile.text);
-  } catch (error) {
-    fail(
-      `manifest.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-      options.artifactDir,
-    );
-  }
-  if (!isRecord(manifestValue)) fail('manifest.json must be an object', options.artifactDir);
-  if (manifestValue['schema_version'] !== FUSION_MANIFEST_SCHEMA_VERSION)
-    fail('manifest schema version mismatch', options.artifactDir);
-  if (manifestValue['run_id'] !== options.runId || manifestValue['workflow'] !== options.workflow)
-    fail('manifest identity mismatch', options.artifactDir);
-  if (manifestValue['state'] !== 'completed')
-    fail('manifest is not committed', options.artifactDir);
-  const artifacts = manifestValue['artifacts'];
-  if (!isRecord(artifacts)) fail('manifest artifacts map is invalid', options.artifactDir);
-  const manifestMerged = artifactRef(
-    artifacts['merged.md'],
-    'manifest artifacts merged.md',
-    options.artifactDir,
-  );
-  const manifestResult = artifactRef(
-    artifacts['result.json'],
-    'manifest artifacts result.json',
-    options.artifactDir,
-  );
-  if (manifestMerged.path !== 'merged.md' || manifestResult.path !== 'result.json')
-    fail('manifest fixed artifact paths are invalid', options.artifactDir);
-
-  const resultFile = await readUtf8(
-    join(options.artifactDirAbs, 'result.json'),
-    'result.json',
-    options.artifactDir,
-  );
-  if (
-    resultFile.bytes.length !== manifestResult.byte_length ||
-    sha256Buffer(resultFile.bytes) !== manifestResult.sha256
-  ) {
-    fail('result.json does not match its manifest hash and length', options.artifactDir);
-  }
-  let resultValue: unknown;
-  try {
-    resultValue = parseJsonText(resultFile.text);
-  } catch (error) {
-    fail(
-      `result.json is invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-      options.artifactDir,
-    );
-  }
-  if (!isRecord(resultValue)) fail('result.json must be an object', options.artifactDir);
-  assertOnlyKeys(
-    resultValue,
-    ['schema_version', 'run_id', 'merged', 'details'],
-    'result.json',
-    options.artifactDir,
-  );
-  if (
-    resultValue['schema_version'] !== FUSION_COMMITTED_RESULT_SCHEMA_VERSION ||
-    resultValue['run_id'] !== options.runId
-  ) {
-    fail('result.json identity mismatch', options.artifactDir);
-  }
-  const committedMerged = artifactRef(
-    resultValue['merged'],
-    'result.json merged',
-    options.artifactDir,
-  );
-  if (!sameRef(committedMerged, manifestMerged))
-    fail('result.json merged reference does not match manifest', options.artifactDir);
-  const details = resultDetails(resultValue['details'], options);
-
-  const mergedFile = await readUtf8(
-    join(options.artifactDirAbs, 'merged.md'),
-    'merged.md',
-    options.artifactDir,
-  );
-  if (
-    mergedFile.bytes.length !== committedMerged.byte_length ||
-    sha256Buffer(mergedFile.bytes) !== committedMerged.sha256
-  ) {
-    fail('merged.md does not match its committed hash and length', options.artifactDir);
-  }
-  return { mergedText: mergedFile.text, details };
-}
-
-// The public tool adds a small task envelope and text receipt around this view.
-// Keep the verified details below 8 KiB even after that model-visible envelope.
-const FAILURE_VIEW_MAX_BYTES = 6 * 1024;
-const FAILURE_CODES = new Set([
-  'config_invalid', 'config_conflict', 'model_unavailable', 'context_capture_failed',
-  'context_policy_unsupported_block', 'prompt_budget_exceeded_forecast',
-  'prompt_budget_exceeded_measured', 'model_capacity_unknown', 'child_spawn_failed',
-  'child_stdin_failed', 'child_event_invalid', 'child_exit_failed',
-  'child_runtime_limit_exceeded', 'child_runtime_payload_invalid',
-  'child_cache_policy_invalid', 'child_timeout', 'child_output_cap', 'child_cancelled',
-  'evaluation_invalid', 'artifact_error', 'state_transition_invalid', 'orchestration_failed',
-]);
-const FAILURE_REMEDIATION_IDS = new Set([
-  'inspect_manifest_bound_evidence', 'inspect_terminal_error', 'split_or_reduce_work',
-  'retry_same_route_after_operator_review',
-]);
-const FAILURE_CLASSIFICATIONS = new Set([
-  'complete_stage_output', 'partial_stage_output', 'oversized_original',
-  'empty_rejected_output', 'evidence_only',
-]);
-
-interface TrustedFailureManifest {
-  schemaVersion: string;
-  source: FusionSource;
-  state: 'failed' | 'cancelled';
-  usage: FusionUsage;
-  artifacts: Readonly<Record<string, FusionArtifactRef>>;
-  attempts: readonly FusionFailureAttemptMetadata[];
-  classifications: Readonly<Record<string, FusionFailureEvidenceArtifact['classification']>>;
-  error?: string | undefined;
-}
-
-function failureUnavailable(
-  state: 'failed' | 'cancelled',
-  status: 'unavailable' | 'integrity_failed',
-): FusionFailureResultView {
-  return {
-    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
-    summary_status: status,
-    terminal_state: state,
-    answer: { present: false, reason: 'run_did_not_commit' },
-    summary_unavailable_reason: status === 'unavailable' ? 'manifest_untrusted' : 'summary_integrity_failed',
-  };
-}
-
-function failureString(value: unknown, label: string): string {
-  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
-  return value;
-}
-
-function failureInteger(value: unknown, label: string): number {
-  if (!Number.isSafeInteger(value) || Number(value) < 0)
-    throw new Error(`${label} must be a nonnegative integer`);
-  return Number(value);
-}
-
-function compareFailureText(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
-
-function failureStage(value: unknown, label: string): FusionStage {
-  if (value === 'candidate' || value === 'evaluation' || value === 'merge') return value;
-  throw new Error(`${label} is invalid`);
-}
-
-function failureUsage(value: unknown, artifactDir: string): FusionUsage {
-  return usage(value, artifactDir);
-}
-
-function failureRef(value: unknown, label: string, artifactDir: string): FusionArtifactRef {
-  return artifactRef(value, label, artifactDir);
-}
-
-function sameFailureRef(left: FusionArtifactRef, right: FusionArtifactRef): boolean {
-  return left.path === right.path && left.byte_length === right.byte_length && left.sha256 === right.sha256;
-}
-
-function trustedFailureManifest(
-  value: unknown,
-  options: ReadFusionCommittedResultOptions,
-): TrustedFailureManifest {
-  if (!isRecord(value)) throw new Error('manifest must be an object');
-  const schemaVersion = value['schema_version'];
-  if (schemaVersion !== FUSION_MANIFEST_SCHEMA_VERSION && schemaVersion !== FUSION_LEGACY_MANIFEST_SCHEMA_VERSION)
-    throw new Error('manifest schema version mismatch');
-  if (value['run_id'] !== options.runId || value['workflow'] !== options.workflow)
-    throw new Error('manifest identity mismatch');
-  const state = value['state'];
-  if (state !== 'failed' && state !== 'cancelled') throw new Error('manifest is not failed or cancelled');
-  const source = value['source'];
-  if (source !== 'command' && source !== 'tool') throw new Error('manifest source is invalid');
-  const artifactsValue = value['artifacts'];
-  if (!isRecord(artifactsValue)) throw new Error('manifest artifacts are invalid');
-  const artifacts: Record<string, FusionArtifactRef> = {};
-  for (const [name, ref] of Object.entries(artifactsValue)) {
-    assertFusionArtifactBasename(name);
-    const checked = failureRef(ref, `manifest artifact ${name}`, options.artifactDir);
-    if (checked.path !== name) throw new Error('manifest artifact key/ref divergence');
-    artifacts[name] = checked;
-  }
-  const attemptsValue = value['attempts'];
-  if (!Array.isArray(attemptsValue)) throw new Error('manifest attempts are invalid');
-  const attempts: FusionFailureAttemptMetadata[] = [];
-  const classifications: Record<string, FusionFailureEvidenceArtifact['classification']> = {};
-  const attemptArtifact = (entry: unknown, label: string): string | undefined => {
-    if (entry === undefined) return undefined;
-    const name = failureString(entry, label);
-    assertFusionArtifactBasename(name);
-    if (artifacts[name] === undefined) throw new Error(`${label} is not manifest-bound`);
-    return name;
-  };
-  for (const attemptValue of attemptsValue) {
-    if (!isRecord(attemptValue)) throw new Error('manifest attempt is invalid');
-    const metadata = failureAttempt({
-      stage: attemptValue['stage'], slot: attemptValue['slot'], attempt: attemptValue['attempt'],
-      status: attemptValue['status'], child_created: attemptValue['child_created'],
-    });
-    attempts.push(metadata);
-    const response = attemptArtifact(attemptValue['response_path'], 'manifest response_path');
-    if (response !== undefined) {
-      const responseRef = artifacts[response];
-      if (responseRef === undefined) throw new Error('manifest response_path is not manifest-bound');
-      classifications[response] =
-        responseRef.byte_length === 0 && metadata.status !== 'completed'
-          ? 'empty_rejected_output'
-          : 'complete_stage_output';
-    }
-    const partial = attemptArtifact(
-      attemptValue['partial_response_path'],
-      'manifest partial_response_path',
-    );
-    if (partial !== undefined) classifications[partial] = 'partial_stage_output';
-    const recovery = attemptValue['output_recovery'];
-    if (recovery !== undefined) {
-      if (!isRecord(recovery)) throw new Error('manifest output_recovery is invalid');
-      const original = attemptArtifact(
-        recovery['original_response_path'],
-        'manifest output_recovery.original_response_path',
-      );
-      if (original === undefined) throw new Error('manifest output recovery has no original response');
-      classifications[original] = 'oversized_original';
-    }
-  }
-  attempts.sort((left, right) =>
-    compareFailureText(left.stage, right.stage) ||
-    (left.slot ?? 0) - (right.slot ?? 0) ||
-    left.attempt - right.attempt,
-  );
-  const manifestUsage = failureUsage(value['usage'], options.artifactDir);
-  const error = value['error'];
-  if (error !== undefined && typeof error !== 'string') throw new Error('manifest error is invalid');
-  return { schemaVersion, source, state, usage: manifestUsage, artifacts, attempts, classifications, ...(error === undefined ? {} : { error }) };
-}
-
-function failureMessage(value: unknown): FusionFailureSummaryV1['failure']['message'] {
-  if (!isRecord(value)) throw new Error('failure message is invalid');
-  assertOnlyKeys(value, ['byte_length', 'sha256', 'inline_message', 'omission_reason'], 'failure message', 'failure-summary.json');
-  const byteLength = failureInteger(value['byte_length'], 'failure message byte_length');
-  const sha256 = failureString(value['sha256'], 'failure message sha256');
-  if (!SHA256_PATTERN.test(sha256)) throw new Error('failure message sha256 is invalid');
-  const inline = value['inline_message'];
-  const omission = value['omission_reason'];
-  if ((inline === undefined) === (omission === undefined)) throw new Error('failure message must have exactly one representation');
-  if (inline !== undefined) {
-    if (
-      typeof inline !== 'string' ||
-      byteLength > FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES ||
-      Buffer.byteLength(inline, 'utf8') !== byteLength ||
-      sha256Buffer(Buffer.from(inline, 'utf8')) !== sha256
-    ) {
-      throw new Error('failure inline message does not match its metadata');
-    }
-    return { byte_length: byteLength, sha256, inline_message: inline };
-  }
-  if (omission !== 'exceeds_inline_message_bytes_cap')
-    throw new Error('failure message omission reason is invalid');
-  return { byte_length: byteLength, sha256, omission_reason: omission };
-}
-
-function failureList<T>(
-  value: unknown,
-  label: string,
-  cap: number,
-  parseEntry: (entry: unknown) => T,
-): FusionFailureList<T> {
-  if (!isRecord(value)) throw new Error(`${label} is invalid`);
-  assertOnlyKeys(value, ['listed', 'omitted_count'], label, 'failure-summary.json');
-  if (!Array.isArray(value['listed']) || value['listed'].length > cap)
-    throw new Error(`${label}.listed is invalid`);
-  return {
-    listed: value['listed'].map(parseEntry),
-    omitted_count: failureInteger(value['omitted_count'], `${label}.omitted_count`),
-  };
-}
-
-function failureAttempt(value: unknown): FusionFailureAttemptMetadata {
-  if (!isRecord(value)) throw new Error('failure attempt is invalid');
-  assertOnlyKeys(value, ['stage', 'slot', 'attempt', 'status', 'child_created'], 'failure attempt', 'failure-summary.json');
-  const stage = failureStage(value['stage'], 'failure attempt stage');
-  const slot = value['slot'];
-  if (slot !== undefined && slot !== 1 && slot !== 2 && slot !== 3)
-    throw new Error('failure attempt slot is invalid');
-  if ((stage === 'candidate') !== (slot !== undefined))
-    throw new Error('failure attempt stage/slot is inconsistent');
-  const status = value['status'];
-  if (status !== 'completed' && status !== 'failed' && status !== 'cancelled') throw new Error('failure attempt status is invalid');
-  if (typeof value['child_created'] !== 'boolean') throw new Error('failure attempt child_created is invalid');
-  const attempt = failureInteger(value['attempt'], 'failure attempt number');
-  if (attempt === 0) throw new Error('failure attempt number must be positive');
-  return { stage, ...(slot === undefined ? {} : { slot }), attempt, status, child_created: value['child_created'] };
-}
-
-function failureEvidence(
-  value: unknown,
-  manifest: TrustedFailureManifest,
-  artifactDir: string,
-): FusionFailureEvidenceArtifact {
-  if (!isRecord(value)) throw new Error('failure evidence row is invalid');
-  assertOnlyKeys(value, ['name', 'classification', 'ref'], 'failure evidence row', artifactDir);
-  const name = failureString(value['name'], 'failure evidence name');
-  assertFusionArtifactBasename(name);
-  const classification = value['classification'];
-  if (typeof classification !== 'string' || !FAILURE_CLASSIFICATIONS.has(classification))
-    throw new Error('failure evidence classification is invalid');
-  const ref = failureRef(value['ref'], 'failure evidence ref', artifactDir);
-  const manifestRef = manifest.artifacts[name];
-  if (manifestRef === undefined || !sameFailureRef(ref, manifestRef))
-    throw new Error('failure evidence ref diverges from manifest');
-  const expectedClassification = manifest.classifications[name] ?? 'evidence_only';
-  if (classification !== expectedClassification) throw new Error('failure evidence classification diverges from manifest');
-  return { name, classification: expectedClassification, ref };
-}
-
-function failureProgress(value: unknown, manifest: TrustedFailureManifest, artifactDir: string): FusionRunProgress {
-  if (!isRecord(value)) throw new Error('failure progress is invalid');
-  assertOnlyKeys(value, ['manifest_state', 'candidates', 'evaluation', 'merge', 'usage_so_far'], 'failure progress', artifactDir);
-  if (value['manifest_state'] !== manifest.state) throw new Error('failure progress state diverges from manifest');
-  const stage = (entry: unknown, label: string, candidates: boolean): FusionRunProgress['candidates'] => {
-    if (!isRecord(entry)) throw new Error(`${label} is invalid`);
-    assertOnlyKeys(entry, ['status', 'attempts_recorded', 'children_created', 'children_completed', 'children_failed', 'children_cancelled', 'not_started_slots'], label, artifactDir);
-    const status = entry['status'];
-    if (status !== 'not_started' && status !== 'incomplete' && status !== 'completed') throw new Error(`${label}.status is invalid`);
-    const notStarted = entry['not_started_slots'];
-    if (candidates ? !Number.isSafeInteger(notStarted) || Number(notStarted) < 0 || Number(notStarted) > 3 : notStarted !== undefined)
-      throw new Error(`${label}.not_started_slots is invalid`);
-    return {
-      status,
-      attempts_recorded: failureInteger(entry['attempts_recorded'], `${label}.attempts_recorded`),
-      children_created: failureInteger(entry['children_created'], `${label}.children_created`),
-      children_completed: failureInteger(entry['children_completed'], `${label}.children_completed`),
-      children_failed: failureInteger(entry['children_failed'], `${label}.children_failed`),
-      children_cancelled: failureInteger(entry['children_cancelled'], `${label}.children_cancelled`),
-      ...(candidates ? { not_started_slots: Number(notStarted) } : {}),
-    };
-  };
-  const usageSoFar = failureUsage(value['usage_so_far'], artifactDir);
-  if (canonicalJson(usageSoFar) !== canonicalJson(manifest.usage)) throw new Error('failure progress usage diverges from manifest');
-  return { manifest_state: manifest.state, candidates: stage(value['candidates'], 'failure candidates', true), evaluation: stage(value['evaluation'], 'failure evaluation', false), merge: stage(value['merge'], 'failure merge', false), usage_so_far: usageSoFar };
-}
-
-function parseFailureSummary(
-  value: unknown,
-  manifest: TrustedFailureManifest,
-  options: ReadFusionCommittedResultOptions,
-): FusionFailureSummaryV1 {
-  if (!isRecord(value)) throw new Error('failure summary must be an object');
-  assertOnlyKeys(value, ['schema_version', 'run_id', 'workflow', 'source', 'terminal_state', 'created_at', 'answer', 'failure', 'progress', 'usage_so_far', 'attempts', 'evidence_artifacts', 'remediation_ids'], 'failure summary', options.artifactDir);
-  if (value['schema_version'] !== FUSION_FAILURE_SUMMARY_SCHEMA_VERSION || value['run_id'] !== options.runId || value['workflow'] !== options.workflow || value['source'] !== manifest.source || value['terminal_state'] !== manifest.state || typeof value['created_at'] !== 'string')
-    throw new Error('failure summary identity is invalid');
-  const answer = value['answer'];
-  if (!isRecord(answer) || answer['present'] !== false || answer['reason'] !== 'run_did_not_commit') throw new Error('failure summary answer assertion is invalid');
-  const failure = value['failure'];
-  if (!isRecord(failure)) throw new Error('failure summary failure metadata is invalid');
-  assertOnlyKeys(failure, ['code', 'stage', 'slot', 'attempt', 'child_created', 'message'], 'failure metadata', options.artifactDir);
-  const code = failure['code'];
-  if (code !== null && (typeof code !== 'string' || !FAILURE_CODES.has(code))) throw new Error('failure code is invalid');
-  const stageValue = failure['stage'];
-  const stage = stageValue === undefined ? undefined : failureStage(stageValue, 'failure stage');
-  const slot = failure['slot'];
-  if (slot !== undefined && slot !== 1 && slot !== 2 && slot !== 3) throw new Error('failure slot is invalid');
-  if (failure['attempt'] !== undefined) failureInteger(failure['attempt'], 'failure attempt');
-  if (typeof failure['child_created'] !== 'boolean') throw new Error('failure child_created is invalid');
-  const progress = failureProgress(value['progress'], manifest, options.artifactDir);
-  const expectedProgress = buildFusionRunProgress(manifest);
-  if (canonicalJson(progress) !== canonicalJson(expectedProgress))
-    throw new Error('failure progress diverges from durable attempts');
-  const usageSoFar = failureUsage(value['usage_so_far'], options.artifactDir);
-  if (canonicalJson(usageSoFar) !== canonicalJson(manifest.usage))
-    throw new Error('summary usage diverges from manifest');
-  const attempts = failureList(
-    value['attempts'],
-    'failure attempts',
-    FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
-    failureAttempt,
-  );
-  const expectedAttempts = manifest.attempts;
-  const expectedAttemptListedCount = Math.min(
-    expectedAttempts.length,
-    FUSION_FAILURE_SUMMARY_ATTEMPT_CAP,
-  );
-  if (
-    attempts.listed.length !== expectedAttemptListedCount ||
-    attempts.omitted_count !== expectedAttempts.length - expectedAttemptListedCount ||
-    canonicalJson(attempts.listed) !==
-      canonicalJson(
-        expectedAttempts.filter((_attempt, index) => index < expectedAttemptListedCount),
-      )
-  ) {
-    throw new Error('failure attempt metadata diverges from manifest');
-  }
-  const evidence = failureList(
-    value['evidence_artifacts'],
-    'failure evidence artifacts',
-    FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
-    (entry) => failureEvidence(entry, manifest, options.artifactDir),
-  );
-  const expectedEvidence = Object.entries(manifest.artifacts)
-    .filter(([name]) => name !== 'failure-summary.json')
-    .map(([name, ref]) => ({ name, classification: manifest.classifications[name] ?? 'evidence_only', ref }))
-    .sort((left, right) => compareFailureText(left.name, right.name));
-  const expectedEvidenceListedCount = Math.min(
-    expectedEvidence.length,
-    FUSION_FAILURE_SUMMARY_EVIDENCE_CAP,
-  );
-  if (
-    evidence.listed.length !== expectedEvidenceListedCount ||
-    evidence.omitted_count !== expectedEvidence.length - expectedEvidenceListedCount ||
-    canonicalJson(evidence.listed) !==
-      canonicalJson(
-        expectedEvidence.filter((_evidence, index) => index < expectedEvidenceListedCount),
-      )
-  ) {
-    throw new Error('failure evidence metadata diverges from manifest');
-  }
-  const remediationIds = value['remediation_ids'];
-  const expectedRemediationIds = [
-    'inspect_manifest_bound_evidence',
-    'inspect_terminal_error',
-    'split_or_reduce_work',
-    'retry_same_route_after_operator_review',
-  ];
-  if (
-    !Array.isArray(remediationIds) ||
-    !remediationIds.every((id) => typeof id === 'string' && FAILURE_REMEDIATION_IDS.has(id)) ||
-    canonicalJson(remediationIds) !== canonicalJson(expectedRemediationIds)
-  ) {
-    throw new Error('failure remediation ids are invalid');
-  }
-  const terminalMessage = failureMessage(failure['message']);
-  if (manifest.error === undefined) throw new Error('manifest terminal error is unavailable');
-  const manifestErrorBytes = Buffer.from(manifest.error, 'utf8');
-  const expectedMessage = {
-    byte_length: manifestErrorBytes.length,
-    sha256: sha256Buffer(manifestErrorBytes),
-    ...(manifestErrorBytes.length <= FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES
-      ? { inline_message: manifest.error }
-      : { omission_reason: 'exceeds_inline_message_bytes_cap' as const }),
-  };
-  if (canonicalJson(terminalMessage) !== canonicalJson(expectedMessage))
-    throw new Error('failure message diverges from manifest terminal error');
-  return {
-    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION, run_id: options.runId, workflow: options.workflow,
-    source: manifest.source, terminal_state: manifest.state, created_at: value['created_at'],
-    answer: { present: false, reason: 'run_did_not_commit' },
-    failure: { code: code as FusionFailureSummaryV1['failure']['code'], ...(stage === undefined ? {} : { stage }), ...(slot === undefined ? {} : { slot }), ...(failure['attempt'] === undefined ? {} : { attempt: Number(failure['attempt']) }), child_created: failure['child_created'], message: terminalMessage },
-    progress, usage_so_far: usageSoFar, attempts, evidence_artifacts: evidence,
-    remediation_ids: [...remediationIds] as FusionFailureSummaryV1['remediation_ids'],
-  };
-}
-
-interface FailureViewSource {
-  terminal_state: Exclude<FusionFailureResultView['terminal_state'], 'completed'>;
-  failure?: FusionFailureResultView['failure'] | undefined;
-  progress: FusionRunProgress;
-  usage_so_far: FusionUsage;
-  attempts: FusionFailureList<FusionFailureAttemptMetadata>;
-  evidence_artifacts: FusionFailureList<FusionFailureEvidenceArtifact>;
-  remediation_ids: FusionFailureSummaryV1['remediation_ids'];
-}
-
-function boundedFailureView(
-  source: FailureViewSource,
-  status: FusionFailureResultView['summary_status'],
-  summaryRef?: FusionArtifactRef,
-): FusionFailureResultView {
-  const attempts = { listed: [...source.attempts.listed], omitted_count: source.attempts.omitted_count };
-  const evidence = { listed: [...source.evidence_artifacts.listed], omitted_count: source.evidence_artifacts.omitted_count };
-  const failure = source.failure;
-  const view: FusionFailureResultView = {
-    schema_version: FUSION_FAILURE_SUMMARY_SCHEMA_VERSION,
-    summary_status: status,
-    terminal_state: source.terminal_state,
-    answer: { present: false, reason: 'run_did_not_commit' },
-    ...(failure === undefined
-      ? {}
-      : { failure: { ...failure, message: { ...failure.message } } }),
-    progress: source.progress,
-    usage_so_far: source.usage_so_far,
-    attempts,
-    evidence_artifacts: evidence,
-    remediation_ids: source.remediation_ids,
-    ...(summaryRef === undefined ? {} : { failure_summary_ref: summaryRef }),
-  };
-  const fits = (): boolean => Buffer.byteLength(canonicalJson(view), 'utf8') <= FAILURE_VIEW_MAX_BYTES;
-  if (!fits() && view.failure?.message.inline_message !== undefined) {
-    const message = view.failure.message;
-    view.failure = {
-      ...view.failure,
-      message: {
-        byte_length: message.byte_length,
-        sha256: message.sha256,
-        omission_reason: 'result_view_byte_budget',
-      },
-    };
-  }
-  while (!fits() && evidence.listed.length > 0) { evidence.listed.pop(); evidence.omitted_count += 1; }
-  while (!fits() && attempts.listed.length > 0) { attempts.listed.pop(); attempts.omitted_count += 1; }
-  if (!fits()) throw new Error('failure result view exceeds its byte budget without a safe whole-section omission');
-  return view;
-}
-
-function legacyFailureSource(
-  manifest: TrustedFailureManifest,
-): FailureViewSource {
-  const message =
-    manifest.error === undefined
-      ? undefined
-      : (() => {
-          const bytes = Buffer.from(manifest.error, 'utf8');
-          return bytes.length <= FUSION_FAILURE_SUMMARY_INLINE_MESSAGE_BYTES
-            ? {
-                byte_length: bytes.length,
-                sha256: sha256Buffer(bytes),
-                inline_message: manifest.error,
-              }
-            : {
-                byte_length: bytes.length,
-                sha256: sha256Buffer(bytes),
-                omission_reason: 'exceeds_inline_message_bytes_cap' as const,
-              };
-        })();
-  const evidence = Object.entries(manifest.artifacts)
-    .map(([name, ref]) => ({
-      name,
-      classification: manifest.classifications[name] ?? 'evidence_only',
-      ref: { ...ref },
-    }))
-    .sort((left, right) => compareFailureText(left.name, right.name));
-  const attempts = manifest.attempts;
-  return {
-    terminal_state: manifest.state,
-    ...(message === undefined ? {} : { failure: { message } }),
-    progress: buildFusionRunProgress(manifest),
-    usage_so_far: manifest.usage,
-    attempts: {
-      listed: attempts.filter((_attempt, index) => index < FUSION_FAILURE_SUMMARY_ATTEMPT_CAP),
-      omitted_count: attempts.length - Math.min(attempts.length, FUSION_FAILURE_SUMMARY_ATTEMPT_CAP),
-    },
-    evidence_artifacts: {
-      listed: evidence.filter((_evidence, index) => index < FUSION_FAILURE_SUMMARY_EVIDENCE_CAP),
-      omitted_count: evidence.length - Math.min(evidence.length, FUSION_FAILURE_SUMMARY_EVIDENCE_CAP),
-    },
-    remediation_ids: ['inspect_manifest_bound_evidence', 'inspect_terminal_error'],
-  };
-}
-
-/** Read only terminal failure metadata; it never reads stage-output bodies. */
-export async function readFusionFailureResult(
-  options: ReadFusionCommittedResultOptions,
-): Promise<FusionFailureResultView> {
-  let manifest: TrustedFailureManifest;
-  try {
-    const file = await readUtf8(join(options.artifactDirAbs, 'manifest.json'), 'manifest.json', options.artifactDir);
-    manifest = trustedFailureManifest(parseJsonText(file.text), options);
-  } catch {
-    return failureUnavailable('failed', 'unavailable');
-  }
-  const summaryRef = manifest.artifacts['failure-summary.json'];
-  if (summaryRef === undefined) {
-    return boundedFailureView(legacyFailureSource(manifest), 'legacy_manifest_only');
-  }
-  if (manifest.schemaVersion !== FUSION_MANIFEST_SCHEMA_VERSION || summaryRef.path !== 'failure-summary.json')
-    return failureUnavailable(manifest.state, 'integrity_failed');
-  try {
-    if (summaryRef.byte_length > FUSION_FAILURE_SUMMARY_MAX_BYTES)
-      throw new Error('failure summary exceeds its bounded artifact size');
-    const file = await readFailureUtf8(
-      join(options.artifactDirAbs, summaryRef.path),
-      'failure-summary.json',
-      options.artifactDir,
-      FUSION_FAILURE_SUMMARY_MAX_BYTES,
-    );
-    if (file.bytes.length !== summaryRef.byte_length || sha256Buffer(file.bytes) !== summaryRef.sha256)
-      throw new Error('failure summary hash/length mismatch');
-    const summary = parseFailureSummary(parseJsonText(file.text), manifest, options);
-    return boundedFailureView(summary, 'verified', summaryRef);
-  } catch {
-    return failureUnavailable(manifest.state, 'integrity_failed');
-  }
-}