pi-background-tasks 0.7.7 → 1.0.3

package/src/core/fusion/orchestrator.ts

@@ -1,4 +1,5 @@
 import { randomBytes as nodeRandomBytes } from 'node:crypto';
+import { canonicalJson } from '../attested-pi-run.js';
 import { parseJsonText } from '../common.js';
 import { FUSION_BUDGET_POLICY, FusionBudget, assertChildOutputWithinContract } from './budget.js';
 import {
@@ -9,14 +10,13 @@ import {
 import {
   boundedEvaluationErrors,
   formatEvaluationErrors,
+  parseFusionValidationCandidateReport,
+  renderValidatedFusionValidationReport,
   validateFusionEvaluation,
+  validateFusionFindingAccounting,
 } from './evaluation.js';
 import { FusionChildRunError, runPiChild, type RunPiChildOptions } from './pi-child.js';
 import {
-  FUSION_CANDIDATE_SYSTEM_PROMPT,
-  FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
-  FUSION_EVALUATOR_SYSTEM_PROMPT,
-  FUSION_MERGER_SYSTEM_PROMPT,
   buildBlindEvaluationInput,
   buildCandidatePrompt,
   buildEvaluationPrompt,
@@ -26,11 +26,20 @@ import {
   type AnonymousFusionCandidate,
 } from './prompts.js';
 import {
+  assertWorkflowCapability,
+  fusionWorkflowProfile,
+  type FusionWorkflowProfile,
+} from './workflows.js';
+import { buildFusionSourcePolicy, sourcePolicyCanonicalBytes } from './source-policy.js';
+import {
+  FUSION_INPUT_SCHEMA_VERSION,
+  FUSION_NO_TOOLS_CAPABILITY,
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
   addFusionUsage,
   createEmptyFusionUsage,
   type FusionCalibrationViolation,
+  type FusionCapability,
   type FusionCanonicalInputV3,
   type FusionCandidateId,
   type FusionContextOmissionLedgerV2,
@@ -43,6 +52,7 @@ import {
   type FusionSource,
   type FusionStage,
   type FusionUsage,
+  type FusionValidationFindingRecord,
   type ResolvedFusionModel,
   type ResolvedFusionModels,
 } from './types.js';
@@ -59,9 +69,12 @@ export interface FusionWorkflowInput {
   sessionId?: string | undefined;
   canonicalInput: FusionCanonicalInputV3;
   canonicalInputSerialized: string;
-  contextLedger: FusionContextOmissionLedgerV2;
+  contextLedger?: FusionContextOmissionLedgerV2 | undefined;
   config: FusionModelConfigV1;
   models: ResolvedFusionModels;
+  candidateCapability?: FusionCapability | undefined;
+  /** Mandatory v5 workflow profile. */
+  profile?: FusionWorkflowProfile | undefined;
   signal?: AbortSignal | undefined;
   onProgress?: FusionProgressSink | undefined;
 }
@@ -94,6 +107,33 @@ function errorText(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const allowedSet = new Set(allowed);
+  return Object.keys(value).every((key) => allowedSet.has(key));
+}
+
+function isStrictCleanCanonicalInput(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (!hasOnlyKeys(value, ['schema_version', 'workflow', 'cwd', 'request', 'context'])) return false;
+  const request = value['request'];
+  if (!isRecord(request)) return false;
+  if (!hasOnlyKeys(request, ['source', 'authority', 'text', 'sha256'])) return false;
+  const context = value['context'];
+  if (!isRecord(context)) return false;
+  if (!hasOnlyKeys(context, ['kind', 'policy_id', 'declared_sources'])) return false;
+  if (context['kind'] !== 'clean_task') return false;
+  const declaredSources = context['declared_sources'];
+  if (!Array.isArray(declaredSources)) return false;
+  for (const source of declaredSources) {
+    if (!isRecord(source) || !hasOnlyKeys(source, ['url', 'canonical_url', 'purpose', 'sha256'])) return false;
+  }
+  return true;
+}
+
 function asFusionError(error: unknown, artifactDir: string, messageOverride?: string): FusionError {
   if (error instanceof FusionError) {
     const details: FusionErrorDetails = {
@@ -179,25 +219,34 @@ function childOptions(
   model: ResolvedFusionModel,
   stage: FusionStage,
   attempt: number,
+  capability: FusionCapability,
   systemPrompt: string,
   userPrompt: string,
   signal: AbortSignal,
   slot?: CandidateSlot,
+  toolCallLogPath?: string,
+  sourcePolicy?: { path: string; sha256: string },
 ): RunPiChildOptions {
   const out: RunPiChildOptions = {
     stage,
     attempt,
     cwd: input.cwd,
     model,
+    capability,
     systemPrompt,
     userPrompt,
     signal,
   };
   if (slot !== undefined) out.slot = slot;
+  if (toolCallLogPath !== undefined) out.toolCallLogPath = toolCallLogPath;
+  if (sourcePolicy !== undefined) out.sourcePolicy = sourcePolicy;
   return out;
 }
 
-function parseEvaluationAttempt(text: string): {
+function parseEvaluationAttempt(
+  text: string,
+  expectedValidationFindings: readonly FusionValidationFindingRecord[] | undefined,
+): {
   evaluation: FusionEvaluationV1 | undefined;
   errors: readonly string[];
 } {
@@ -211,8 +260,21 @@ function parseEvaluationAttempt(text: string): {
     };
   }
   const result = validateFusionEvaluation(parsed);
-  if (result.ok) return { evaluation: result.value, errors: [] };
-  return { evaluation: undefined, errors: result.errors };
+  if (!result.ok) return { evaluation: undefined, errors: result.errors };
+  if (
+    expectedValidationFindings === undefined &&
+    result.value.validation_accounting !== undefined
+  ) {
+    return {
+      evaluation: undefined,
+      errors: ['evaluation.validation_accounting is permitted only for fusion_validate'],
+    };
+  }
+  if (expectedValidationFindings !== undefined) {
+    const accountingErrors = validateEvaluationAccountsForSourceFindings(result.value, expectedValidationFindings);
+    if (accountingErrors.length > 0) return { evaluation: undefined, errors: accountingErrors };
+  }
+  return { evaluation: result.value, errors: [] };
 }
 
 function randomIndex(limit: number, randomBytes: FusionRandomBytes): number {
@@ -308,6 +370,63 @@ function anonymousCandidates(
   };
 }
 
+interface ValidationSourceData {
+  findings: readonly FusionValidationFindingRecord[];
+  verified: readonly string[];
+  limitations: readonly string[];
+}
+
+function validationSourceData(candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate]): ValidationSourceData {
+  const findings: FusionValidationFindingRecord[] = [];
+  const verified: string[] = [];
+  const limitations: string[] = [];
+  for (const candidate of candidates) {
+    const report = parseFusionValidationCandidateReport(candidate.response, candidate.candidate_id);
+    findings.push(...report.findings);
+    verified.push(...report.verified);
+    limitations.push(...report.limitations);
+  }
+  return { findings, verified, limitations };
+}
+
+function validateEvaluationAccountsForSourceFindings(
+  evaluation: FusionEvaluationV1,
+  sourceFindings: readonly FusionValidationFindingRecord[],
+): readonly string[] {
+  const errors: string[] = [];
+  const accounting = evaluation.validation_accounting;
+  if (accounting === undefined) {
+    return ['validation evaluator output must include validation_accounting'];
+  }
+  const expected = sourceFindings.map((finding) => canonicalJson(finding)).sort();
+  const actual = accounting.findings.map((finding) => canonicalJson(finding)).sort();
+  if (expected.length !== actual.length || expected.some((value, index) => value !== actual[index])) {
+    errors.push('validation evaluator validation_accounting.findings must exactly equal host-assigned source findings');
+  }
+  errors.push(...validateFusionFindingAccounting(accounting));
+  return errors;
+}
+
+
+function resolveRunProfile(input: FusionWorkflowInput): FusionWorkflowProfile {
+  if (input.profile !== undefined) return fusionWorkflowProfile(input.profile.id);
+  const workflow = input.canonicalInput.workflow;
+  const contextKind = input.canonicalInput.context?.kind;
+  if (workflow !== undefined && workflow !== 'reason') {
+    throw new FusionError(`fusion workflow profile is required for ${workflow} runs`, {
+      code: 'orchestration_failed',
+      childCreated: false,
+    });
+  }
+  if (contextKind === 'clean_task') {
+    throw new FusionError('fusion workflow profile is required for clean-task runs', {
+      code: 'orchestration_failed',
+      childCreated: false,
+    });
+  }
+  return fusionWorkflowProfile('reason');
+}
+
 export class FusionOrchestrator {
   private readonly childRunner: FusionChildRunner;
   private readonly randomBytes: FusionRandomBytes;
@@ -324,26 +443,95 @@ export class FusionOrchestrator {
   }
 
   async run(input: FusionWorkflowInput): Promise<FusionRunResult> {
+    if (input.canonicalInput.schema_version !== FUSION_INPUT_SCHEMA_VERSION) {
+      throw new FusionError('fusion orchestrator accepts only v5 canonical input', {
+        code: 'orchestration_failed',
+        childCreated: false,
+      });
+    }
+    const profile = resolveRunProfile(input);
+    const inputWorkflow = input.canonicalInput.workflow ?? profile.id;
+    const inputContextKind = input.canonicalInput.context?.kind ?? 'session_projection';
+    if (inputWorkflow !== profile.id || inputContextKind !== profile.contextKind) {
+      throw new FusionError(
+        `fusion workflow profile ${profile.id} is incompatible with canonical input workflow=${String(inputWorkflow)} context=${String(inputContextKind)}`,
+        { code: 'orchestration_failed', childCreated: false },
+      );
+    }
+    if (profile.contextKind === 'clean_task' && !isStrictCleanCanonicalInput(input.canonicalInput)) {
+      throw new FusionError('clean-task fusion input must not carry parent context fields and must match the strict clean canonical shape', {
+        code: 'orchestration_failed',
+        childCreated: false,
+      });
+    }
+    const candidateCapability = assertWorkflowCapability(profile, input.candidateCapability);
     const storeOptions: CreateFusionArtifactStoreOptions = {
       cwd: input.cwd,
+      profile,
       source: input.source,
       config: input.config,
       models: input.models,
+      capabilities: {
+        candidate: candidateCapability,
+        evaluation: FUSION_NO_TOOLS_CAPABILITY,
+        merge: FUSION_NO_TOOLS_CAPABILITY,
+      },
     };
     if (input.sessionId !== undefined) storeOptions.sessionId = input.sessionId;
     if (this.now !== undefined) storeOptions.now = this.now;
+    let serializedParsed: unknown;
+    try {
+      serializedParsed = parseJsonText(input.canonicalInputSerialized);
+    } catch (error) {
+      throw new FusionError(`fusion canonical input artifact is not valid JSON: ${errorText(error)}`, {
+        code: 'orchestration_failed',
+        childCreated: false,
+      });
+    }
+    if (canonicalJson(serializedParsed) !== canonicalJson(input.canonicalInput)) {
+      throw new FusionError('fusion canonical input serialized bytes do not match canonical input object', {
+        code: 'orchestration_failed',
+        childCreated: false,
+      });
+    }
     const store = await this.createArtifactStore(storeOptions);
     input.onProgress?.({ type: 'state', state: 'initializing' });
     const usage = createEmptyFusionUsage();
     const calibrationWarnings: FusionCalibrationViolation[] = [];
     try {
       await store.writeCanonicalInput(input.canonicalInputSerialized);
-      await store.writeContextLedger(input.contextLedger);
+      if (inputContextKind === 'session_projection') {
+        if (input.contextLedger === undefined) {
+          throw new FusionError('session-projection fusion input requires an omission ledger artifact', {
+            code: 'orchestration_failed',
+            childCreated: false,
+          });
+        }
+        await store.writeContextLedger(input.contextLedger);
+      } else if (input.contextLedger !== undefined) {
+        throw new FusionError('clean-task fusion input must not carry a parent omission ledger', {
+          code: 'orchestration_failed',
+          childCreated: false,
+        });
+      }
+      if (profile.id === 'research') {
+        const cleanContext = input.canonicalInput.context;
+        if (cleanContext?.kind !== 'clean_task') {
+          throw new FusionError('research workflow requires a clean-task canonical input', {
+            code: 'orchestration_failed',
+            childCreated: false,
+          });
+        }
+        const policy = buildFusionSourcePolicy(input.cwd, cleanContext.declared_sources);
+        await store.writeSourcePolicy(sourcePolicyCanonicalBytes(policy));
+      }
       // Deterministic size accounting for the whole workflow, performed before
       // a single child process exists. A rejection here launches zero children.
       const budget = new FusionBudget(
         input.models,
-        input.canonicalInput.conversation_projection.policy.id,
+        input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1',
+        candidateCapability,
+        profile,
       );
       const budgetPlan = budget.plan(input.canonicalInput);
       await store.writeBudgetPlan(budgetPlan);
@@ -363,13 +551,20 @@ export class FusionOrchestrator {
         usage,
         budget,
         calibrationWarnings,
+        profile,
+        candidateCapability,
       );
       await store.transition('candidates_complete');
       input.onProgress?.({ type: 'state', state: 'candidates_complete' });
 
       const shuffled = anonymousCandidates(candidateResults, shuffledSlots(this.randomBytes));
+      const validationData = profile.id === 'validate' ? validationSourceData(shuffled.candidates) : undefined;
       await store.setAnonymousMap(shuffled.map);
-      const blindInput = buildBlindEvaluationInput(input.canonicalInput, shuffled.candidates);
+      const blindInput = buildBlindEvaluationInput(
+        input.canonicalInput,
+        shuffled.candidates,
+        validationData?.findings,
+      );
       await store.writeBlindCandidates(buildEvaluationPrompt(blindInput));
 
       await store.transition('evaluating');
@@ -381,6 +576,8 @@ export class FusionOrchestrator {
         blindInput,
         budget,
         calibrationWarnings,
+        profile,
+        validationData?.findings,
       );
       await store.writeEvaluationJson(evaluation);
       await store.transition('evaluation_complete');
@@ -390,7 +587,7 @@ export class FusionOrchestrator {
       input.onProgress?.({ type: 'state', state: 'merging' });
       const mergeInput = buildMergeInput(input.canonicalInput, shuffled.candidates, evaluation);
       const mergePrompt = buildMergePrompt(mergeInput);
-      budget.assertStagePrompt('merge', FUSION_MERGER_SYSTEM_PROMPT, mergePrompt);
+      budget.assertStagePrompt('merge', profile.mergerSystemPrompt, mergePrompt);
       input.onProgress?.({ type: 'merge_started' });
       const merged = await this.runChildWithRetry(
         input,
@@ -398,9 +595,11 @@ export class FusionOrchestrator {
         usage,
         input.models.merger,
         'merge',
-        FUSION_MERGER_SYSTEM_PROMPT,
+        profile.mergerSystemPrompt,
         mergePrompt,
         input.signal ?? new AbortController().signal,
+        // Stage policy, not caller input: evaluator and merger are always reasoning-only.
+        FUSION_NO_TOOLS_CAPABILITY,
         undefined,
         'md',
       );
@@ -412,23 +611,38 @@ export class FusionOrchestrator {
         budget,
         calibrationWarnings,
         'merge',
-        FUSION_MERGER_SYSTEM_PROMPT,
+        profile.mergerSystemPrompt,
         mergePrompt,
         merged,
       );
       assertChildOutputWithinContract('merge', merged.text);
-      await store.writeMerged(merged.text);
+      let finalMergedText = merged.text;
+      if (profile.id === 'validate') {
+        const accounting = evaluation.validation_accounting;
+        if (accounting === undefined) {
+          throw new FusionError('fusion_validate evaluation completed without validation accounting', {
+            code: 'evaluation_invalid',
+            stage: 'merge',
+          });
+        }
+        finalMergedText = renderValidatedFusionValidationReport(accounting, validationData);
+      }
+      if (finalMergedText !== merged.text) assertChildOutputWithinContract('merge', finalMergedText);
+      await store.writeMerged(finalMergedText);
       await store.setUsage(usage);
       await store.transition('completed');
       input.onProgress?.({ type: 'completed', runId: store.runId, artifactDir: store.artifactDir });
       return {
-        mergedText: merged.text,
+        mergedText: finalMergedText,
         details: {
           schema_version: FUSION_RESULT_SCHEMA_VERSION,
           run_id: store.runId,
+          workflow: profile.id,
           source: input.source,
           status: 'completed',
           artifact_dir: store.artifactDir,
+          context: { kind: inputContextKind, policy_id: input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1' },
+          tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
           models: store.snapshot().models,
           evaluator_attempts: store
             .snapshot()
@@ -480,14 +694,17 @@ export class FusionOrchestrator {
     usage: FusionUsage,
     budget: FusionBudget,
     calibrationWarnings: FusionCalibrationViolation[],
+    profile: FusionWorkflowProfile,
+    candidateCapability: FusionCapability,
   ): Promise<readonly CandidateResult[]> {
     const controller = new AbortController();
     const abortListener = () => controller.abort();
     input.signal?.addEventListener('abort', abortListener, { once: true });
     if (input.signal?.aborted) controller.abort();
+    const systemPrompt = profile.candidateSystemPrompt(candidateCapability);
     const prompt = buildCandidatePrompt(input.canonicalInput);
     for (const slot of [1, 2, 3] as const) {
-      budget.assertStagePrompt('candidate', FUSION_CANDIDATE_SYSTEM_PROMPT, prompt, slot);
+      budget.assertStagePrompt('candidate', systemPrompt, prompt, slot);
     }
     let primaryError: unknown;
     let completed = 0;
@@ -507,9 +724,10 @@ export class FusionOrchestrator {
           usage,
           model,
           'candidate',
-          FUSION_CANDIDATE_SYSTEM_PROMPT,
+          systemPrompt,
           prompt,
           controller.signal,
+          candidateCapability,
           slot,
           'md',
         ).then(async (result) => {
@@ -520,7 +738,7 @@ export class FusionOrchestrator {
             budget,
             calibrationWarnings,
             'candidate',
-            FUSION_CANDIDATE_SYSTEM_PROMPT,
+            systemPrompt,
             prompt,
             result,
             slot,
@@ -562,9 +780,11 @@ export class FusionOrchestrator {
     blindInput: Parameters<typeof buildEvaluationPrompt>[0],
     budget: FusionBudget,
     calibrationWarnings: FusionCalibrationViolation[],
+    profile: FusionWorkflowProfile,
+    expectedValidationFindings: readonly FusionValidationFindingRecord[] | undefined,
   ): Promise<FusionEvaluationV1> {
     const firstPrompt = buildEvaluationPrompt(blindInput);
-    budget.assertStagePrompt('evaluation', FUSION_EVALUATOR_SYSTEM_PROMPT, firstPrompt);
+    budget.assertStagePrompt('evaluation', profile.evaluatorSystemPrompt, firstPrompt);
     const first = await this.runEvaluationAttempt(
       input,
       store,
@@ -574,6 +794,8 @@ export class FusionOrchestrator {
       firstPrompt,
       1,
       false,
+      profile,
+      expectedValidationFindings,
     );
     if (first.evaluation !== undefined) return first.evaluation;
     const errors = boundedEvaluationErrors(first.errors);
@@ -586,7 +808,7 @@ export class FusionOrchestrator {
     });
     budget.assertStagePrompt(
       'evaluation_repair',
-      FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+      profile.evaluationRepairSystemPrompt,
       repairPrompt,
     );
     const second = await this.runEvaluationAttempt(
@@ -598,6 +820,8 @@ export class FusionOrchestrator {
       repairPrompt,
       2,
       true,
+      profile,
+      expectedValidationFindings,
     );
     if (second.evaluation !== undefined) return second.evaluation;
     throw new FusionError(
@@ -619,11 +843,13 @@ export class FusionOrchestrator {
     prompt: string,
     attempt: 1 | 2,
     repair: boolean,
+    profile: FusionWorkflowProfile,
+    expectedValidationFindings: readonly FusionValidationFindingRecord[] | undefined,
   ): Promise<EvaluationAttemptResult> {
     input.onProgress?.({ type: 'evaluation_started', attempt, repair });
     const systemPrompt = repair
-      ? FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT
-      : FUSION_EVALUATOR_SYSTEM_PROMPT;
+      ? profile.evaluationRepairSystemPrompt
+      : profile.evaluatorSystemPrompt;
     const result = await this.runChildWithRetry(
       input,
       store,
@@ -633,6 +859,8 @@ export class FusionOrchestrator {
       systemPrompt,
       prompt,
       input.signal ?? new AbortController().signal,
+      // Stage policy, not caller input: evaluator and merger are always reasoning-only.
+      FUSION_NO_TOOLS_CAPABILITY,
       undefined,
       'txt',
       attempt,
@@ -652,7 +880,7 @@ export class FusionOrchestrator {
     await store.setUsage(usage);
     // Bound the evaluator output before it can be embedded in a repair prompt.
     assertChildOutputWithinContract('evaluation', result.text);
-    const parsed = parseEvaluationAttempt(result.text);
+    const parsed = parseEvaluationAttempt(result.text, expectedValidationFindings);
     return { result, evaluation: parsed.evaluation, errors: parsed.errors };
   }
 
@@ -700,6 +928,7 @@ export class FusionOrchestrator {
     systemPrompt: string,
     userPrompt: string,
     signal: AbortSignal,
+    capability: FusionCapability,
     slot: CandidateSlot | undefined,
     responseKind: 'md' | 'txt',
     fixedAttempt?: 1 | 2,
@@ -709,9 +938,29 @@ export class FusionOrchestrator {
       if (stage === 'candidate' && slot !== undefined) {
         input.onProgress?.({ type: 'candidate_started', slot, attempt: logicalAttempt });
       }
+      const toolCallLogPath =
+        capability !== 'reason'
+          ? store.childToolCallLogPath(stage, slot, logicalAttempt)
+          : undefined;
+      const sourcePolicy =
+        capability === 'research'
+          ? store.sourcePolicyLaunchReference()
+          : undefined;
       try {
         return await this.childRunner(
-          childOptions(input, model, stage, logicalAttempt, systemPrompt, userPrompt, signal, slot),
+          childOptions(
+            input,
+            model,
+            stage,
+            logicalAttempt,
+            capability,
+            systemPrompt,
+            userPrompt,
+            signal,
+            slot,
+            toolCallLogPath,
+            sourcePolicy,
+          ),
         );
       } catch (error) {
         if (!signal.aborted && retryableSpawn(error, launchTry) && launchTry === 1) continue;