ai-maestro 1.0.0

package/src/orchestration/consolidator.mjs

@@ -0,0 +1,772 @@
+const SCHEMA_VERSION = 1;
+
+const RUN_STATUSES = Object.freeze([
+  'completed',
+  'completed_with_warnings',
+  'failed',
+  'blocked',
+  'needs_human'
+]);
+
+const CONSOLIDATION_STATUSES = Object.freeze([
+  'accepted',
+  'accepted_with_warnings',
+  'rejected',
+  'inconclusive',
+  'needs_human'
+]);
+
+const COMPLETENESS_VALUES = Object.freeze(['complete', 'partial', 'invalid']);
+const NEXT_ACTIONS = Object.freeze(['complete', 'verify', 'fallback', 'fix', 'ask_human', 'block']);
+const EVIDENCE_TYPES = Object.freeze([
+  'run-status',
+  'syntax-validation',
+  'workspace-diff',
+  'test-result',
+  'host-validation',
+  'failure-classification',
+  'verifier-result',
+  'diagnostics',
+  'other'
+]);
+
+const TASK_STATUSES = Object.freeze([
+  'pending',
+  'in_progress',
+  'completed',
+  'completed_with_warnings',
+  'failed',
+  'blocked',
+  'needs_human',
+  'archived'
+]);
+
+export function consolidateResults(input) {
+  assertConsolidationInput(input);
+
+  const taskId = String(input.task.id);
+  const subtasks = normalizeSubtasks(input.subtasks || []);
+  const subtaskResults = normalizeSubtaskResults(input.subtaskResults || []);
+  const rawTaskWarnings = input.warnings || [];
+  const taskWarnings = normalizeStringArray(rawTaskWarnings);
+  const provenance = normalizeEvidenceArray(input.provenance || [], {
+    inputErrors: [],
+    owner: 'input.provenance'
+  });
+  const fallbackResults = [...(input.fallbackResults || [])];
+  const classification = isPlainObject(input.classification) ? input.classification : {};
+  const verifierResult = input.verifierResult ?? null;
+
+  const inputErrors = collectInputErrors(input, subtasks, rawTaskWarnings, provenance.inputErrors);
+  const invalidReferences = collectReferenceErrors(taskId, subtasks, subtaskResults);
+  const resultBySubtask = firstResultBySubtask(subtaskResults);
+  const declaredSubtaskIds = subtasks.length > 0 ? subtasks.map(subtask => subtask.id) : parentSubtaskIds(taskId, subtaskResults);
+  const subtaskById = new Map(subtasks.map(subtask => [subtask.id, subtask]));
+  const allEvidence = [];
+
+  for (const entry of provenance.entries) {
+    allEvidence.push({
+      rawSubtaskId: taskId,
+      rawRunId: null,
+      originSequence: entry.sequence,
+      type: entry.type,
+      sourceId: entry.sourceId,
+      field: entry.field,
+      value: cloneData(entry.value)
+    });
+  }
+
+  fallbackResults.forEach((value, index) => {
+    allEvidence.push({
+      rawSubtaskId: taskId,
+      rawRunId: null,
+      originSequence: provenance.entries.length + index,
+      type: 'diagnostics',
+      sourceId: `fallback:${index}`,
+      field: 'fallbackResults',
+      value: cloneData(value)
+    });
+  });
+
+  const preliminarySubtasks = declaredSubtaskIds.map(subtaskId => {
+    const subtask = subtaskById.get(subtaskId) || null;
+    const result = resultBySubtask.get(subtaskId) || null;
+    return buildSubtaskConsolidation({
+      taskId,
+      subtaskId,
+      subtask,
+      result,
+      allEvidence,
+      invalidReferences,
+      inputErrors
+    });
+  });
+
+  const evidence = buildEvidenceEntries(allEvidence);
+  const evidenceRefsBySubtask = groupEvidenceRefsBySubtask(evidence);
+  const internalPerSubtask = preliminarySubtasks
+    .map(item => ({
+      ...item,
+      evidenceRefs: evidenceRefsBySubtask.get(item.subtaskId) || []
+    }))
+    .sort((a, b) => compareStrings(a.subtaskId, b.subtaskId));
+  const perSubtask = internalPerSubtask.map(({ verificationRequired, ...item }) => item);
+
+  const missingEvidence = collectMissingEvidence({
+    taskId,
+    classification,
+    verifierResult,
+    perSubtask: internalPerSubtask,
+    evidence
+  });
+  const warnings = uniqueSorted([
+    ...taskWarnings,
+    ...perSubtask.flatMap(item => item.warnings)
+  ]);
+  const codeFailures = uniqueSorted(perSubtask.flatMap(item => item.isCodeFailure ? item.failures : []));
+  const infrastructureFailures = uniqueSorted(perSubtask.flatMap(item => item.infrastructureFailure ? item.failures : []));
+  const failures = uniqueSorted([...codeFailures, ...infrastructureFailures]);
+  const conflicts = uniqueSorted(perSubtask
+    .filter(item => item.observedState === 'contradictory')
+    .map(item => `Subtask ${item.subtaskId} has conflicting execution signals`));
+  const inconsistencies = uniqueSorted([
+    ...perSubtask
+      .filter(item => item.observedState === 'contradictory')
+      .map(item => `Subtask ${item.subtaskId} contradicts runStatus ${String(item.runStatus)}`),
+    ...invalidReferences
+  ]);
+  const remainingIssues = uniqueSorted([
+    ...failures,
+    ...missingEvidence.map(item => `${item.subtaskId}: ${item.reason}`),
+    ...invalidReferences,
+    ...inputErrors
+  ]);
+  const consolidationCompleteness = decideCompleteness(inputErrors, invalidReferences, perSubtask);
+  const { status, recommendedNextAction } = decideStatus({
+    inputErrors,
+    perSubtask: internalPerSubtask,
+    warnings,
+    classification,
+    verifierResult
+  });
+
+  const verifierInputHints = {
+    requiresIndependentCheck: status !== 'accepted' || warnings.length > 0 || missingEvidence.length > 0,
+    criticalWithoutVerifier: classification.risk === 'critical' && verifierResult === null
+  };
+
+  const result = {
+    schemaVersion: SCHEMA_VERSION,
+    taskId,
+    status,
+    consolidationCompleteness,
+    perSubtask,
+    evidence,
+    missingEvidence,
+    warnings,
+    failures,
+    codeFailures,
+    infrastructureFailures,
+    conflicts,
+    inconsistencies,
+    invalidReferences,
+    remainingIssues,
+    recommendedNextAction,
+    verifierInputHints,
+    summary: '',
+    inputErrors
+  };
+  return { ...result, summary: summarizeConsolidation(result) };
+}
+
+export function validateConsolidation(result) {
+  const errors = [];
+  const warnings = [];
+  try {
+    if (!isPlainObject(result)) {
+      return { isValid: false, errors: ['result must be an object'], warnings };
+    }
+    if (result.schemaVersion !== SCHEMA_VERSION) {
+      errors.push('schemaVersion must be 1');
+    }
+    if (typeof result.taskId !== 'string' || result.taskId.length === 0) {
+      errors.push('taskId must be a non-empty string');
+    }
+    if (!CONSOLIDATION_STATUSES.includes(result.status)) {
+      errors.push('status is not a recognized consolidation status');
+    }
+    if (!COMPLETENESS_VALUES.includes(result.consolidationCompleteness)) {
+      errors.push('consolidationCompleteness is not recognized');
+    }
+    for (const field of [
+      'perSubtask',
+      'evidence',
+      'missingEvidence',
+      'warnings',
+      'failures',
+      'codeFailures',
+      'infrastructureFailures',
+      'conflicts',
+      'inconsistencies',
+      'invalidReferences',
+      'remainingIssues',
+      'inputErrors'
+    ]) {
+      if (!Array.isArray(result[field])) {
+        errors.push(`${field} must be an array`);
+      }
+    }
+    if (!NEXT_ACTIONS.includes(result.recommendedNextAction)) {
+      errors.push('recommendedNextAction is not recognized');
+    }
+    if (!isPlainObject(result.verifierInputHints)) {
+      errors.push('verifierInputHints must be an object');
+    }
+    if (typeof result.summary !== 'string' || result.summary.length === 0) {
+      warnings.push('summary is missing or empty');
+    }
+    if (Array.isArray(result.failures) && Array.isArray(result.codeFailures) && Array.isArray(result.infrastructureFailures)) {
+      const expectedFailures = uniqueSorted([...result.codeFailures, ...result.infrastructureFailures]);
+      if (!arrayEqual(result.failures, expectedFailures)) {
+        errors.push('failures must be the union of codeFailures and infrastructureFailures');
+      }
+    }
+  } catch (error) {
+    errors.push(`validation failed: ${error && error.message ? error.message : String(error)}`);
+  }
+  return { isValid: errors.length === 0, errors, warnings };
+}
+
+export function summarizeConsolidation(result) {
+  try {
+    if (!isPlainObject(result)) {
+      return 'Consolidation result summary unavailable: result is not an object';
+    }
+    if (!CONSOLIDATION_STATUSES.includes(result.status)) {
+      return 'Consolidation result summary unavailable: unknown status';
+    }
+    if (!COMPLETENESS_VALUES.includes(result.consolidationCompleteness)) {
+      return 'Consolidation result summary unavailable: unknown completeness';
+    }
+    const perSubtask = Array.isArray(result.perSubtask) ? result.perSubtask : [];
+    const issueCount = countArray(result.failures) + countArray(result.missingEvidence) +
+      countArray(result.invalidReferences) + countArray(result.inputErrors) + countArray(result.conflicts);
+    return `Consolidation ${result.status}: ${perSubtask.length} subtask(s), completeness ${result.consolidationCompleteness}, ${issueCount} issue(s).`;
+  } catch (error) {
+    return `Consolidation result summary unavailable: ${error && error.message ? error.message : 'unknown error'}`;
+  }
+}
+
+function assertConsolidationInput(input) {
+  if (!isPlainObject(input)) {
+    throw new TypeError('input must be an object');
+  }
+  if (!isPlainObject(input.task) || input.task.id === undefined || input.task.id === null) {
+    throw new TypeError('input.task must be an object with id');
+  }
+  for (const field of ['subtasks', 'subtaskResults', 'acceptanceCriteria', 'warnings', 'provenance', 'fallbackResults']) {
+    if (input[field] !== undefined && !Array.isArray(input[field])) {
+      throw new TypeError(`input.${field} must be an array`);
+    }
+  }
+  const subtaskResults = input.subtaskResults || [];
+  subtaskResults.forEach((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new TypeError(`input.subtaskResults[${index}] must be an object`);
+    }
+    if (!isNonBlankString(item.subtaskId)) {
+      throw new TypeError(`input.subtaskResults[${index}].subtaskId must be a non-empty string`);
+    }
+  });
+}
+
+function collectInputErrors(input, subtasks, taskWarnings, provenanceErrors) {
+  const errors = [];
+  if (typeof input.task.description !== 'string' || input.task.description.length === 0) {
+    errors.push('task.description must be a non-empty string');
+  }
+  if (typeof input.task.status !== 'string' || !TASK_STATUSES.includes(input.task.status)) {
+    errors.push(`task.status is invalid: ${String(input.task.status)}`);
+  }
+  if (hasDuplicate(subtasks.map(subtask => subtask.id))) {
+    errors.push('subtasks contains duplicate id');
+  }
+  addArrayItemTypeErrors(errors, input.acceptanceCriteria || [], 'acceptanceCriteria', 'string');
+  addArrayItemTypeErrors(errors, taskWarnings, 'warnings', 'string');
+  errors.push(...provenanceErrors);
+  (input.subtaskResults || []).forEach((item, index) => {
+    if (item.evidence !== undefined && !Array.isArray(item.evidence)) {
+      errors.push(`subtaskResults[${index}].evidence must be an array`);
+    }
+    if (item.warnings !== undefined && !Array.isArray(item.warnings)) {
+      errors.push(`subtaskResults[${index}].warnings must be an array`);
+    }
+  });
+  return uniqueSorted(errors);
+}
+
+function normalizeSubtasks(subtasks) {
+  return [...subtasks]
+    .filter(isPlainObject)
+    .map((subtask, index) => ({
+      raw: subtask,
+      id: typeof subtask.id === 'string' ? subtask.id : String(subtask.id ?? `missing-id-${index}`),
+      verificationRequired: subtask.verificationRequired === true,
+      noChangeExpected: subtask.noChangeExpected === true || (isPlainObject(subtask.requires) && subtask.requires.noChangeExpected === true)
+    }))
+    .sort((a, b) => compareStrings(a.id, b.id) || compareStrings(canonicalStringify(a.raw), canonicalStringify(b.raw)));
+}
+
+function normalizeSubtaskResults(results) {
+  return [...results]
+    .map((result, index) => ({ ...result, originalIndex: index }))
+    .sort((a, b) => compareStrings(a.subtaskId, b.subtaskId) ||
+      compareNullableStrings(a.runId, b.runId) ||
+      compareNullableStrings(a.runStatus, b.runStatus) ||
+      compareNullableStrings(a.noExecutionReason, b.noExecutionReason) ||
+      compareStrings(canonicalStringify(a), canonicalStringify(b)));
+}
+
+function normalizeStringArray(values) {
+  return values.filter(value => typeof value === 'string');
+}
+
+function normalizeEvidenceArray(values, { inputErrors, owner }) {
+  const entries = [];
+  values.forEach((item, index) => {
+    if (!isPlainObject(item)) {
+      inputErrors.push(`${owner}[${index}] must be an object`);
+      return;
+    }
+    if (!EVIDENCE_TYPES.includes(item.type)) {
+      inputErrors.push(`${owner}[${index}].type is invalid`);
+      return;
+    }
+    if (!isNonBlankString(item.sourceId)) {
+      inputErrors.push(`${owner}[${index}].sourceId must be a non-empty string`);
+      return;
+    }
+    entries.push({
+      sequence: index,
+      type: item.type,
+      sourceId: item.sourceId,
+      field: typeof item.field === 'string' ? item.field : null,
+      value: cloneData(item.value)
+    });
+  });
+  return { entries, inputErrors };
+}
+
+function collectReferenceErrors(taskId, subtasks, results) {
+  const errors = [];
+  const subtaskIds = new Set(subtasks.map(subtask => subtask.id));
+  const resultSubtaskIds = results.map(result => result.subtaskId);
+  for (const id of duplicateValues(resultSubtaskIds)) {
+    errors.push(`duplicate subtaskResult subtaskId: ${id}`);
+  }
+  const runOwners = new Map();
+  for (const result of results) {
+    if (isNonBlankString(result.runId)) {
+      const owner = runOwners.get(result.runId);
+      if (owner && owner !== result.subtaskId) {
+        errors.push(`duplicate runId ${result.runId} for subtasks ${owner} and ${result.subtaskId}`);
+      }
+      runOwners.set(result.runId, result.subtaskId);
+    }
+    if (subtasks.length > 0) {
+      if (!subtaskIds.has(result.subtaskId)) {
+        errors.push(`orphan subtaskResult reference: ${result.subtaskId}`);
+      }
+    } else if (result.subtaskId !== taskId) {
+      errors.push(`orphan subtaskResult reference: ${result.subtaskId}`);
+    }
+    const validity = validateRunAssociation(result);
+    if (!validity.valid) {
+      errors.push(`invalid run association for ${result.subtaskId}: ${validity.reason}`);
+    }
+  }
+  return uniqueSorted(errors);
+}
+
+function firstResultBySubtask(results) {
+  const map = new Map();
+  for (const result of results) {
+    if (!map.has(result.subtaskId)) {
+      map.set(result.subtaskId, result);
+    }
+  }
+  return map;
+}
+
+function parentSubtaskIds(taskId, results) {
+  return results.some(result => result.subtaskId === taskId) ? [taskId] : [];
+}
+
+function buildSubtaskConsolidation({ taskId, subtaskId, subtask, result, allEvidence, invalidReferences, inputErrors }) {
+  if (!result) {
+    return {
+      subtaskId,
+      runId: null,
+      runStatus: null,
+      noExecutionReason: 'result_missing',
+      observedState: 'missing',
+      isCodeFailure: false,
+      infrastructureFailure: false,
+      warnings: [],
+      failures: [],
+      evidenceRefs: [],
+      missingEvidence: ['Subtask result is missing'],
+      verificationRequired: subtask ? subtask.verificationRequired : true
+    };
+  }
+
+  const evidenceErrors = [];
+  const evidence = normalizeEvidenceArray(result.evidence || [], {
+    inputErrors: evidenceErrors,
+    owner: `subtaskResults[${result.originalIndex}].evidence`
+  });
+  inputErrors.push(...evidenceErrors);
+  for (const entry of evidence.entries) {
+    allEvidence.push({
+      rawSubtaskId: result.subtaskId || taskId,
+      rawRunId: normalizeRunId(result.runId),
+      originSequence: entry.sequence,
+      type: entry.type,
+      sourceId: entry.sourceId,
+      field: entry.field,
+      value: entry.value
+    });
+  }
+
+  const validity = validateRunAssociation(result);
+  const observedState = validity.valid
+    ? observeState(result, evidence.entries, subtask)
+    : 'invalid';
+  const infrastructureFailure = observedState === 'failed' && result.infrastructureFailure === true;
+  const isCodeFailure = observedState === 'failed' && result.infrastructureFailure !== true;
+  const warnings = normalizeStringArray(result.warnings || []);
+  if (result.runStatus === 'completed_with_warnings') {
+    warnings.push(`Subtask ${subtaskId} completed with warnings`);
+  }
+  const failures = [];
+  if (isCodeFailure) {
+    failures.push(`Subtask ${subtaskId} failed`);
+  }
+  if (infrastructureFailure) {
+    failures.push(`Subtask ${subtaskId} failed due to infrastructure`);
+  }
+  const missingEvidence = [];
+  for (const entry of evidence.entries) {
+    if (entry.type === 'test-result' && isPlainObject(entry.value) && entry.value.ran === false) {
+      missingEvidence.push('Tests were not executed');
+    }
+  }
+  if (observedState === 'invalid' && !invalidReferences.some(ref => ref.includes(subtaskId))) {
+    invalidReferences.push(`invalid run association for ${subtaskId}: ${validity.reason}`);
+  }
+  return {
+    subtaskId,
+    runId: normalizeRunId(result.runId),
+    runStatus: result.runStatus ?? null,
+    noExecutionReason: result.noExecutionReason ?? null,
+    observedState,
+    isCodeFailure,
+    infrastructureFailure,
+    warnings: uniqueSorted(warnings),
+    failures: uniqueSorted(failures),
+    evidenceRefs: [],
+    missingEvidence: uniqueSorted(missingEvidence),
+    verificationRequired: subtask ? subtask.verificationRequired : true
+  };
+}
+
+function validateRunAssociation(result) {
+  const runId = result.runId;
+  const runStatus = result.runStatus;
+  const reason = result.noExecutionReason;
+  const evidence = Array.isArray(result.evidence) ? result.evidence : [];
+  if (typeof runId === 'string' && runId.trim().length === 0) {
+    return { valid: false, reason: 'runId must be a non-empty string or null' };
+  }
+  if (isNonBlankString(runId)) {
+    if (runStatus === 'completed' || runStatus === 'completed_with_warnings' || runStatus === 'failed') {
+      return reason === undefined
+        ? { valid: true, reason: null }
+        : { valid: false, reason: 'executed result must not include noExecutionReason' };
+    }
+    if (runStatus === null || runStatus === undefined) {
+      return { valid: false, reason: 'runId present without runStatus' };
+    }
+    if (runStatus === 'blocked' || runStatus === 'needs_human') {
+      return { valid: false, reason: 'blocked or needs_human with runId is not allowed' };
+    }
+    return { valid: false, reason: `unknown runStatus ${String(runStatus)}` };
+  }
+  if (runId === null) {
+    if (evidence.some(evidenceDeclaresExecution)) {
+      return { valid: false, reason: 'runId null is incompatible with evidence that declares execution' };
+    }
+    if (runStatus === 'blocked' && reason === 'blocked_before_execution') {
+      return { valid: true, reason: null };
+    }
+    if (runStatus === 'needs_human' && reason === 'needs_human_before_execution') {
+      return { valid: true, reason: null };
+    }
+    if (runStatus === null && (reason === 'not_executed' || reason === 'result_missing')) {
+      return { valid: true, reason: null };
+    }
+    if (runStatus === 'completed' || runStatus === 'completed_with_warnings' || runStatus === 'failed') {
+      return { valid: false, reason: 'execution status requires non-empty runId' };
+    }
+    if ((runStatus === 'blocked' || runStatus === 'needs_human') && reason === undefined) {
+      return { valid: false, reason: 'noExecutionReason is required before execution' };
+    }
+    return { valid: false, reason: `invalid no-execution combination ${String(runStatus)}/${String(reason)}` };
+  }
+  return { valid: false, reason: 'runId key must be a non-empty string or null' };
+}
+
+function evidenceDeclaresExecution(item) {
+  if (!isPlainObject(item)) {
+    return false;
+  }
+  if (item.type === 'workspace-diff' || item.type === 'host-validation' || item.type === 'syntax-validation') {
+    return true;
+  }
+  if (item.type === 'test-result' && isPlainObject(item.value) && item.value.ran === true) {
+    return true;
+  }
+  if (item.type === 'failure-classification' && isPlainObject(item.value)) {
+    return item.value.category === 'syntax_failure' ||
+      item.value.category === 'test_failure' ||
+      item.value.category === 'unknown_failure' ||
+      item.value.infrastructureFailure === true;
+  }
+  return false;
+}
+
+function observeState(result, evidence, subtask) {
+  if (result.runId === null) {
+    if (result.runStatus === 'blocked' || result.runStatus === 'needs_human') {
+      return result.runStatus;
+    }
+    return 'missing';
+  }
+  if (hasContradiction(result, evidence, subtask)) {
+    return 'contradictory';
+  }
+  return result.runStatus;
+}
+
+function hasContradiction(result, evidence, subtask) {
+  if (result.runStatus !== 'completed' && result.runStatus !== 'completed_with_warnings') {
+    return false;
+  }
+  const noChangeExpected = result.noChangeExpected === true ||
+    result.expectedNoChange === true ||
+    (subtask && subtask.noChangeExpected === true);
+  return evidence.some(entry => {
+    if (!isPlainObject(entry.value)) {
+      return false;
+    }
+    if (entry.type === 'syntax-validation' && entry.value.syntaxValidationFailed === true) {
+      return true;
+    }
+    if (entry.type === 'workspace-diff' && entry.value.workspaceChanged === false && !noChangeExpected) {
+      return true;
+    }
+    if (entry.type === 'test-result' && entry.value.ran === true && entry.value.passed === false) {
+      return true;
+    }
+    if (entry.type === 'host-validation' && entry.value.result === 'failed') {
+      return true;
+    }
+    return false;
+  });
+}
+
+function buildEvidenceEntries(rawEvidence) {
+  return [...rawEvidence]
+    .sort((a, b) => compareStrings(a.rawSubtaskId, b.rawSubtaskId) ||
+      compareNullableStrings(a.rawRunId, b.rawRunId) ||
+      a.originSequence - b.originSequence ||
+      compareStrings(a.type, b.type) ||
+      compareStrings(a.sourceId, b.sourceId))
+    .map((entry, index) => ({
+      id: `${entry.rawSubtaskId}:${entry.rawRunId ?? 'none'}:${index}`,
+      subtaskId: entry.rawSubtaskId,
+      runId: entry.rawRunId,
+      sequence: entry.originSequence,
+      type: entry.type,
+      sourceId: entry.sourceId,
+      field: entry.field ?? null,
+      value: entry.value
+    }));
+}
+
+function groupEvidenceRefsBySubtask(evidence) {
+  const grouped = new Map();
+  for (const entry of evidence) {
+    const current = grouped.get(entry.subtaskId) || [];
+    current.push(entry.id);
+    grouped.set(entry.subtaskId, current);
+  }
+  return grouped;
+}
+
+function collectMissingEvidence({ taskId, classification, verifierResult, perSubtask }) {
+  const entries = [];
+  if (classification.risk === 'critical' && verifierResult === null) {
+    entries.push({
+      subtaskId: taskId,
+      kind: 'verifier-result',
+      reason: 'Critical task requires verifier result'
+    });
+  }
+  for (const item of perSubtask) {
+    if (item.observedState === 'missing') {
+      entries.push({
+        subtaskId: item.subtaskId,
+        kind: 'subtask-result',
+        reason: 'Subtask result is missing'
+      });
+    }
+    for (const reason of item.missingEvidence) {
+      entries.push({
+        subtaskId: item.subtaskId,
+        kind: 'evidence',
+        reason
+      });
+    }
+  }
+  return entries.sort((a, b) => compareStrings(a.subtaskId, b.subtaskId) ||
+    compareStrings(a.kind, b.kind) ||
+    compareStrings(a.reason, b.reason));
+}
+
+function decideCompleteness(inputErrors, invalidReferences, perSubtask) {
+  if (inputErrors.length > 0) {
+    return 'invalid';
+  }
+  if (invalidReferences.length > 0 || perSubtask.some(item => ['missing', 'contradictory', 'invalid'].includes(item.observedState))) {
+    return 'partial';
+  }
+  return 'complete';
+}
+
+function decideStatus({ inputErrors, perSubtask, warnings, classification, verifierResult }) {
+  if (inputErrors.length > 0) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.some(item => item.observedState === 'invalid')) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.some(item => item.observedState === 'needs_human') ||
+      (classification.risk === 'critical' && verifierResult === null)) {
+    return { status: 'needs_human', recommendedNextAction: 'ask_human' };
+  }
+  if (perSubtask.some(item => item.observedState === 'blocked')) {
+    return { status: 'needs_human', recommendedNextAction: 'ask_human' };
+  }
+  if (perSubtask.some(item => item.observedState === 'missing' && item.verificationRequired !== false)) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.some(item => item.observedState === 'contradictory')) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.some(item => item.isCodeFailure)) {
+    return { status: 'rejected', recommendedNextAction: 'fix' };
+  }
+  if (perSubtask.some(item => item.infrastructureFailure)) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.some(item => item.observedState === 'missing')) {
+    return { status: 'accepted_with_warnings', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.length === 0) {
+    return { status: 'inconclusive', recommendedNextAction: 'verify' };
+  }
+  if (perSubtask.every(item => item.observedState === 'completed' || item.observedState === 'completed_with_warnings')) {
+    if (warnings.length > 0 || perSubtask.some(item => item.observedState === 'completed_with_warnings')) {
+      return { status: 'accepted_with_warnings', recommendedNextAction: 'verify' };
+    }
+    return { status: 'accepted', recommendedNextAction: 'complete' };
+  }
+  return { status: 'inconclusive', recommendedNextAction: 'verify' };
+}
+
+function addArrayItemTypeErrors(errors, values, field, type) {
+  values.forEach((value, index) => {
+    if (typeof value !== type) {
+      errors.push(`${field}[${index}] must be a ${type}`);
+    }
+  });
+}
+
+function normalizeRunId(runId) {
+  return isNonBlankString(runId) ? runId : null;
+}
+
+function hasDuplicate(values) {
+  return duplicateValues(values).length > 0;
+}
+
+function duplicateValues(values) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      duplicates.add(value);
+    }
+    seen.add(value);
+  }
+  return [...duplicates].sort(compareStrings);
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(value => typeof value === 'string'))].sort(compareStrings);
+}
+
+function arrayEqual(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function countArray(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonBlankString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function cloneData(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneData);
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).map(key => [key, cloneData(value[key])]));
+  }
+  return value;
+}
+
+function compareStrings(a, b) {
+  return String(a).localeCompare(String(b));
+}
+
+function compareNullableStrings(a, b) {
+  return String(a ?? '').localeCompare(String(b ?? ''));
+}
+
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalStringify).join(',')}]`;
+  }
+  if (isPlainObject(value)) {
+    return `{${Object.keys(value).sort(compareStrings).map(key => `${key}:${canonicalStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}