@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/agent-run-store.js

@@ -9,10 +9,28 @@
  * a user actually reopens stay complete while history stops growing unbounded.
  */
 import Database from 'better-sqlite3';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { normalizeProviderEgressReceiptV1 } from '@duckcodeailabs/dql-core';
 const DEFAULT_MAX_RUNS = 300;
 const DEFAULT_FULL_PAYLOAD_RUNS = 50;
+const EVIDENCE_CANDIDATE_ROLES = new Set([
+    'metric',
+    'entity_key',
+    'entity_label',
+    'categorical_dimension',
+    'time_dimension',
+    'member',
+    'relationship',
+    'context',
+]);
+const ANALYTICAL_TASK_OUTCOME_STATUSES = new Set([
+    'completed', 'partial', 'gap', 'blocked', 'dependency_blocked',
+]);
+const ANALYTICAL_TASK_OUTCOME_TRUST_STATES = new Set([
+    'certified', 'governed', 'review_required', 'blocked', 'not_applicable',
+]);
 export function resolveAgentRunRetention(env = process.env) {
     const configured = Number(env.DQL_AGENT_RUN_RETENTION);
     if (!Number.isFinite(configured) || configured <= 0)
@@ -48,6 +66,7 @@ export class SqliteAgentRunStore {
             this.migrateLegacyJson(options.legacyJsonPath);
     }
     save(run) {
+        const persistedRun = normalizeRunProviderEgressReceipts(run);
         const now = new Date().toISOString();
         this.db.prepare(`
       INSERT INTO agent_runs (id, question, route, status, started_at, completed_at, compacted, payload_json, updated_at)
@@ -61,12 +80,13 @@ export class SqliteAgentRunStore {
         compacted = 0,
         payload_json = excluded.payload_json,
         updated_at = excluded.updated_at
-    `).run(run.id, run.question, run.route, run.status ?? null, run.startedAt, run.completedAt ?? null, JSON.stringify(run), now);
+    `).run(persistedRun.id, persistedRun.question, persistedRun.route, persistedRun.status ?? null, persistedRun.startedAt, persistedRun.completedAt ?? null, JSON.stringify(persistedRun), now);
         this.enforceRetention();
         this.compactOldRuns();
     }
     saveProgress(progress) {
-        const updatedAt = progress.lifecycle.updatedAt;
+        const persistedProgress = sanitizeProgressRoleCoverage(progress);
+        const updatedAt = persistedProgress.lifecycle.updatedAt;
         this.db.prepare(`
       INSERT INTO agent_runs (id, question, route, status, started_at, completed_at, compacted, payload_json, updated_at)
       VALUES (?, ?, ?, NULL, ?, NULL, 0, ?, ?)
@@ -80,7 +100,7 @@ export class SqliteAgentRunStore {
         payload_json = excluded.payload_json,
         updated_at = excluded.updated_at
       WHERE agent_runs.completed_at IS NULL
-    `).run(progress.id, progress.question, progress.route ?? 'blocked', progress.lifecycle.startedAt, JSON.stringify(progress), updatedAt);
+    `).run(persistedProgress.id, persistedProgress.question, persistedProgress.route ?? 'blocked', persistedProgress.lifecycle.startedAt, JSON.stringify(persistedProgress), updatedAt);
     }
     get(id) {
         const row = this.db.prepare('SELECT payload_json FROM agent_runs WHERE id = ?').get(id);
@@ -125,12 +145,16 @@ export class SqliteAgentRunStore {
                 const userCancelled = progress.lifecycle.state === 'cancelling'
                     || progress.events.some((event) => event.type === 'run.cancelled');
                 const route = progress.route ?? (userCancelled ? 'cancelled' : 'blocked');
+                const retainedArtifacts = retainedInterruptedArtifacts(progress, userCancelled);
+                const retainedIndependentResult = retainedArtifacts.some((artifact) => artifact.trustState !== 'blocked');
                 const failure = {
                     code: userCancelled ? 'RUN_CANCELLED' : 'RUN_INTERRUPTED',
                     phase: progress.lifecycle.phase,
                     message: userCancelled
                         ? 'Stopped by user.'
-                        : 'The local DQL runtime restarted before this agent run completed. No result was accepted.',
+                        : retainedIndependentResult
+                            ? 'The local DQL runtime restarted before this agent run completed. Completed independent task results remain available for inspection.'
+                            : 'The local DQL runtime restarted before this agent run completed. No result was accepted.',
                     recoverable: !userCancelled,
                     safeActions: userCancelled ? [] : ['retry_same_request'],
                 };
@@ -141,16 +165,24 @@ export class SqliteAgentRunStore {
                     route,
                     plan: progress.plan,
                     steps: progress.steps,
-                    artifacts: progress.artifacts,
+                    artifacts: retainedArtifacts,
                     evaluations: progress.evaluations,
                     failure,
                 };
+                const runtimeReceipt = interruptedRuntimeReceiptV5(progress, userCancelled, route);
+                const runtimeReceiptV6 = runtimeReceipt
+                    ? interruptedRuntimeReceiptV6(progress, userCancelled, runtimeReceipt)
+                    : undefined;
                 const diagnosticArtifact = {
                     id: `${progress.id}:diagnostic`,
                     kind: 'answer',
                     title: userCancelled ? 'Cancelled agent run' : 'Interrupted agent run',
                     trustState: 'blocked',
-                    payload: { diagnosticReceipt: receipt },
+                    payload: {
+                        diagnosticReceipt: receipt,
+                        ...(runtimeReceipt ? { diagnosticReceiptV5: runtimeReceipt } : {}),
+                        ...(runtimeReceiptV6 ? { diagnosticReceiptV6: runtimeReceiptV6 } : {}),
+                    },
                 };
                 const run = {
                     id: progress.id,
@@ -167,8 +199,8 @@ export class SqliteAgentRunStore {
                     steps: progress.steps,
                     summary: failure.message,
                     artifacts: userCancelled
-                        ? progress.artifacts
-                        : [...progress.artifacts.filter((artifact) => artifact.trustState === 'blocked'), diagnosticArtifact],
+                        ? retainedArtifacts
+                        : [...retainedArtifacts, diagnosticArtifact],
                     evaluations: [
                         ...progress.evaluations,
                         userCancelled
@@ -207,6 +239,16 @@ export class SqliteAgentRunStore {
                     repairAttempts: 0,
                     escalationAttempts: 0,
                     diagnosticReceipt: receipt,
+                    ...(runtimeReceipt ? { diagnosticReceiptV5: runtimeReceipt } : {}),
+                    ...(runtimeReceiptV6 ? { diagnosticReceiptV6: runtimeReceiptV6 } : {}),
+                    ...(progress.askAnalystState ? { askAnalystState: progress.askAnalystState } : {}),
+                    ...(progress.analyticalTaskOutcomes?.length
+                        ? { analyticalTaskOutcomes: progress.analyticalTaskOutcomes }
+                        : {}),
+                    ...(progress.analyticalTaskOutcomeSummary
+                        ? { analyticalTaskOutcomeSummary: progress.analyticalTaskOutcomeSummary }
+                        : {}),
+                    ...(progress.traceReference ? { traceReference: progress.traceReference } : {}),
                     lifecycle: {
                         ...progress.lifecycle,
                         state: 'terminal',
@@ -259,7 +301,9 @@ export class SqliteAgentRunStore {
             return;
         try {
             const parsed = JSON.parse(readFileSync(legacyJsonPath, 'utf-8'));
-            const runs = Array.isArray(parsed.runs) ? parsed.runs.filter(isAgentRunRecord) : [];
+            const runs = Array.isArray(parsed.runs)
+                ? parsed.runs.filter(isAgentRunRecord).map(normalizeRunProviderEgressReceipts)
+                : [];
             const insert = this.db.prepare(`
         INSERT OR IGNORE INTO agent_runs (id, question, route, status, started_at, completed_at, compacted, payload_json, updated_at)
         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)
@@ -285,27 +329,563 @@ export class SqliteAgentRunStore {
         }
     }
 }
+/**
+ * Restart recovery retains the typed continuation state for a deliberate retry,
+ * but its diagnostic artifact/export receipt must remain content-free. Never
+ * copy the question, filter values, member values, answer, SQL, or rows here.
+ */
+function interruptedRuntimeReceiptV5(progress, cancelled, route) {
+    const state = progress.askAnalystState;
+    if (!state)
+        return undefined;
+    const diagnosticState = interruptedDiagnosticState(state);
+    const summaryInput = {
+        version: 2,
+        runtimeMode: state.mode,
+        whatHappened: cancelled
+            ? 'The Ask runtime was cancelled before its final result was accepted.'
+            : 'The Ask runtime was interrupted before its final result was accepted.',
+        why: cancelled
+            ? 'The local run was cancelled before finalization.'
+            : 'The local DQL runtime restarted before finalization.',
+        impact: 'No executable data answer was accepted for this run.',
+        nextAction: cancelled ? 'none' : 'retry_same_plan',
+        ...(state.resolvedPlan?.compiler ? { selectedCompiler: state.resolvedPlan.compiler } : {}),
+        programTaskCount: state.program.taskIds.length,
+        admittedCandidateCount: state.workspace.admittedCandidateIds.length,
+        toolCallCount: state.toolCalls,
+        executionAttempts: state.executionAttempts,
+    };
+    return {
+        version: 5,
+        runId: progress.id,
+        state: diagnosticState,
+        summary: {
+            ...summaryInput,
+            summaryFingerprint: `sha256:${createHash('sha256').update(JSON.stringify(summaryInput)).digest('hex')}`,
+        },
+        businessAnswer: {
+            version: 1,
+            mode: 'deterministic_fallback',
+            trustState: cancelled ? 'not_applicable' : 'blocked',
+            factIds: [],
+            limitationCount: 1,
+        },
+        finalStopReason: cancelled ? 'cancelled' : 'blocked',
+    };
+}
+/**
+ * Restart recovery has no live trace collector, so V6 is projected only from
+ * the persisted V2 state and its content-free V5 envelope. Do not infer a
+ * connection or SQL attempt from elapsed time/prose: an interrupted execution
+ * count is retained separately and the connection boundary remains skipped
+ * unless a terminal run receipt recorded it before restart.
+ */
+function interruptedRuntimeReceiptV6(progress, cancelled, receipt) {
+    const state = progress.askAnalystState;
+    const planning = state.version === 2 || state.version === 3
+        ? state.planningReceipt
+        : undefined;
+    const plannerTool = state.workspace.tools.find((tool) => tool.kind === 'provider_meaning');
+    const recoveryTool = state.workspace.tools.find((tool) => tool.kind === 'candidate_extension');
+    const planFrozen = state.resolvedPlan?.planFrozen === true;
+    const verification = planning?.verification ?? {
+        version: 1,
+        status: state.phase === 'clarify' ? 'ambiguous' : state.phase === 'blocked' ? 'invalid' : 'valid',
+        missingRoles: [],
+        candidateIds: [],
+        reasonCode: state.phase === 'clarify'
+            ? 'persisted_clarification_state'
+            : state.phase === 'blocked'
+                ? 'persisted_blocked_state'
+                : 'persisted_program_state',
+    };
+    // A durable failed provider tool is a planner attempt too. This restores a
+    // truthful concise V6 restart story for V2 checkpoints saved between
+    // dispatch and planning-receipt finalization.
+    const plannerAttempted = plannerTool?.status === 'completed' || plannerTool?.status === 'failed';
+    const plannerCalls = Math.max(planning?.plannerCalls ?? 0, plannerAttempted ? Math.max(1, state.planningContinuations) : 0);
+    const revisionCalls = planning?.revisionCalls
+        ?? (recoveryTool?.status === 'completed' && plannerCalls > 1 ? 1 : 0);
+    const planningMode = planning?.mode
+        ?? (plannerCalls === 0
+            ? 'deterministic_binding'
+            : revisionCalls > 0 ? 'targeted_revision' : 'initial_planner');
+    const executionAttempts = state.executionAttempts;
+    return {
+        ...receipt,
+        version: 6,
+        planning: {
+            version: 1,
+            mode: planningMode,
+            plannerCalls,
+            revisionCalls,
+            verification,
+        },
+        // V2 stores count-only admission coverage, so reload can retain the
+        // meaningful "required versus admitted" story without exposing labels,
+        // prompts, or result values. Older V1 states remain content-free.
+        roleCoverage: state.workspace.version === 2
+            ? (state.workspace.roleCoverage ?? [])
+                .filter((entry) => Number.isFinite(entry.candidateCount) && entry.candidateCount >= 0)
+                .map((entry) => ({
+                role: entry.role,
+                candidateCount: entry.candidateCount,
+                ...(entry.state === 'alternatives' || entry.state === 'proven' ? { state: entry.state } : {}),
+            }))
+            : [],
+        cascade: {
+            attempts: [],
+            ...(state.resolvedPlan?.selectedTier ? { selectedTier: state.resolvedPlan.selectedTier } : {}),
+            ...(state.resolvedPlan?.compiler && state.resolvedPlan.compiler !== 'none'
+                ? { stopReason: `persisted_${state.resolvedPlan.compiler}_plan` }
+                : {}),
+            planFrozen,
+        },
+        connection: { attempted: false },
+        execution: { attempts: executionAttempts },
+        facts: { factCount: 0 },
+        safeNextAction: receipt.summary.nextAction,
+        story: [
+            { stage: 'retrieval', status: state.workspace.snapshotId ? 'completed' : 'skipped', reasonCode: state.workspace.snapshotId ? 'persisted_snapshot' : 'snapshot_not_retained' },
+            {
+                stage: 'role_coverage',
+                status: state.workspace.version === 2 && (state.workspace.roleCoverage?.length ?? 0) > 0
+                    ? 'completed'
+                    : 'skipped',
+                reasonCode: state.workspace.version === 2 && (state.workspace.roleCoverage?.length ?? 0) > 0
+                    ? 'persisted_role_admission_coverage'
+                    : 'content_free_restart_projection',
+            },
+            {
+                stage: 'planner',
+                status: plannerTool?.status === 'failed' ? 'blocked' : plannerCalls > 0 ? 'completed' : 'skipped',
+                reasonCode: plannerTool?.reasonCode ?? planningMode,
+            },
+            { stage: 'verification', status: verification.status === 'valid' ? 'completed' : 'blocked', reasonCode: verification.reasonCode },
+            { stage: 'targeted_recovery', status: recoveryTool?.status === 'completed' ? 'completed' : 'skipped', reasonCode: recoveryTool?.reasonCode ?? 'not_required' },
+            { stage: 'cascade', status: planFrozen ? 'completed' : state.phase === 'blocked' ? 'blocked' : 'skipped', reasonCode: state.resolvedPlan?.compiler ?? 'no_persisted_compiler' },
+            { stage: 'freeze', status: planFrozen ? 'completed' : 'skipped', reasonCode: planFrozen ? 'persisted_plan_frozen' : 'no_persisted_plan' },
+            { stage: 'connection', status: 'skipped', reasonCode: 'connection_boundary_not_retained_on_restart' },
+            { stage: 'execution', status: executionAttempts > 0 ? 'blocked' : 'skipped', reasonCode: executionAttempts > 0 ? 'interrupted_after_execution_attempt' : 'execution_not_attempted' },
+            { stage: 'facts', status: 'skipped', reasonCode: cancelled ? 'run_cancelled_before_final_facts' : 'run_interrupted_before_final_facts' },
+        ],
+    };
+}
+function interruptedDiagnosticState(state) {
+    return {
+        version: 1,
+        mode: state.mode,
+        phase: state.phase,
+        questionFingerprint: state.frame.questionFingerprint,
+        kind: state.frame.kind,
+        requirementCounts: {
+            measures: state.frame.requirements.measures.length,
+            dimensions: state.frame.requirements.dimensions.length,
+            entityTerms: state.frame.requirements.entityTerms.length + state.frame.requirements.entityDisplayTerms.length,
+            members: state.frame.requirements.memberTerms.length,
+            filters: state.program.filters.length,
+        },
+        mission: {
+            mode: state.mission.mode,
+            taskCount: state.mission.tasks.length,
+            deferredTaskCount: state.mission.deferredTasks?.length ?? 0,
+            hypothesisCount: state.mission.hypotheses.length,
+        },
+        workspace: {
+            ...(state.workspace.snapshotId ? { snapshotId: state.workspace.snapshotId } : {}),
+            ...(state.workspace.sourceFingerprint ? { sourceFingerprint: state.workspace.sourceFingerprint } : {}),
+            admittedCandidateCount: state.workspace.admittedCandidateIds.length,
+            excludedCandidateCount: state.workspace.excludedCandidates.length,
+            sourceCoverage: state.workspace.sourceCoverage.map((coverage) => ({
+                source: coverage.source,
+                status: coverage.status,
+                candidateCount: coverage.candidateIds.length,
+            })),
+            tools: state.workspace.tools.map((tool) => ({
+                id: tool.id,
+                kind: tool.kind,
+                status: tool.status,
+                reasonCode: tool.reasonCode,
+            })),
+        },
+        program: {
+            id: state.program.id,
+            taskCount: state.program.taskIds.length,
+            candidateCount: state.program.candidateIds.length,
+            requiredRoles: state.program.requiredRoles,
+            outputAssertionCount: state.program.outputs.assertions.length,
+        },
+        ...(state.resolvedPlan ? { resolvedPlan: state.resolvedPlan } : {}),
+        counters: {
+            planningContinuations: state.planningContinuations,
+            toolCalls: state.toolCalls,
+            executionAttempts: state.executionAttempts,
+            repairAttempts: state.repairAttempts,
+        },
+    };
+}
 export function defaultAgentRunSqlitePath(projectRoot) {
     return join(projectRoot, '.dql', 'local', 'agent-runs.sqlite');
 }
 function parseRun(payload) {
     try {
         const value = JSON.parse(payload);
-        return isAgentRunRecord(value) ? value : undefined;
+        return isAgentRunRecord(value) ? normalizeRunProviderEgressReceipts(value) : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Durable run JSON is local and therefore untrusted on import/read. Keep an
+ * invalid provider receipt from advertising historical row egress through the
+ * primary run field, diagnostic receipt, or its diagnostic artifact payload.
+ */
+function normalizeRunProviderEgressReceipts(run) {
+    const normalizeReceiptList = (value) => Array.isArray(value)
+        ? value.flatMap((receipt) => {
+            const normalized = normalizeProviderEgressReceiptV1(receipt);
+            return normalized ? [normalized] : [];
+        })
+        : undefined;
+    const normalizeReceiptContainer = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        const record = value;
+        const providerEgressReceipts = normalizeReceiptList(record.providerEgressReceipts);
+        return providerEgressReceipts === undefined
+            ? value
+            : { ...record, providerEgressReceipts };
+    };
+    const rootReceipts = normalizeReceiptList(run.providerEgressReceipts);
+    const diagnosticReceipt = normalizeReceiptContainer(run.diagnosticReceipt);
+    const artifacts = run.artifacts.map((artifact) => {
+        if (!artifact.payload || typeof artifact.payload !== 'object' || Array.isArray(artifact.payload))
+            return artifact;
+        const payload = artifact.payload;
+        const normalizedDiagnosticReceipt = normalizeReceiptContainer(payload.diagnosticReceipt);
+        return normalizedDiagnosticReceipt === payload.diagnosticReceipt
+            ? artifact
+            : { ...artifact, payload: { ...payload, diagnosticReceipt: normalizedDiagnosticReceipt } };
+    });
+    const askAnalystState = sanitizeAskAnalystStateRoleCoverage(run.askAnalystState);
+    const taskReceipts = sanitizeTaskOutcomeReceipts({
+        outcomes: run.analyticalTaskOutcomes,
+        summary: run.analyticalTaskOutcomeSummary,
+        steps: run.steps,
+    });
+    // Do not spread untrusted V3 receipts back onto the returned object. Older
+    // V1/V2 runs simply omit the additive fields; malformed V3 JSON is stripped
+    // or reduced to a blocked receipt before the notebook/API can render it.
+    const { analyticalTaskOutcomes: _rawTaskOutcomes, analyticalTaskOutcomeSummary: _rawTaskOutcomeSummary, ...durableRun } = run;
+    return {
+        ...durableRun,
+        ...(rootReceipts === undefined ? {} : { providerEgressReceipts: rootReceipts }),
+        ...(diagnosticReceipt === run.diagnosticReceipt
+            ? {}
+            : { diagnosticReceipt: diagnosticReceipt }),
+        artifacts,
+        ...(askAnalystState === run.askAnalystState ? {} : { askAnalystState }),
+        ...(taskReceipts.outcomes ? { analyticalTaskOutcomes: taskReceipts.outcomes } : {}),
+        ...(taskReceipts.summary ? { analyticalTaskOutcomeSummary: taskReceipts.summary } : {}),
+    };
+}
 function parseProgress(payload) {
     try {
         const value = JSON.parse(payload);
-        return isAgentRunProgressRecord(value) ? value : undefined;
+        return isAgentRunProgressRecord(value) ? sanitizeProgressRoleCoverage(value) : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * V2 role coverage is an observability summary, not a payload lane. Persist
+ * only the typed count tuples so an injected label, raw query fragment, or
+ * result value cannot survive a restart through the Ask state or diagnostic
+ * projection. The rest of the local continuation state remains intact.
+ */
+function sanitizeAskAnalystStateRoleCoverage(state) {
+    if (!state || (state.version !== 2 && state.version !== 3) || !Array.isArray(state.workspace.roleCoverage))
+        return state;
+    const roleCoverage = state.workspace.roleCoverage.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return [];
+        const record = entry;
+        if (typeof record.role !== 'string'
+            || !EVIDENCE_CANDIDATE_ROLES.has(record.role)
+            || !Number.isFinite(record.candidateCount)
+            || Number(record.candidateCount) < 0)
+            return [];
+        const coverageState = record.state === 'alternatives' || record.state === 'proven'
+            ? record.state
+            : undefined;
+        return [{
+                role: record.role,
+                candidateCount: Math.floor(Number(record.candidateCount)),
+                ...(coverageState ? { state: coverageState } : {}),
+            }];
+    });
+    return {
+        ...state,
+        workspace: {
+            ...state.workspace,
+            roleCoverage,
+        },
+    };
+}
+function sanitizeProgressRoleCoverage(progress) {
+    const askAnalystState = sanitizeAskAnalystStateRoleCoverage(progress.askAnalystState);
+    const taskReceipts = sanitizeTaskOutcomeReceipts({
+        outcomes: progress.analyticalTaskOutcomes,
+        summary: progress.analyticalTaskOutcomeSummary,
+        steps: progress.steps,
+    });
+    const { analyticalTaskOutcomes: _rawTaskOutcomes, analyticalTaskOutcomeSummary: _rawTaskOutcomeSummary, ...durableProgress } = progress;
+    return {
+        ...durableProgress,
+        ...(askAnalystState === progress.askAnalystState ? {} : { askAnalystState }),
+        ...(taskReceipts.outcomes ? { analyticalTaskOutcomes: taskReceipts.outcomes } : {}),
+        ...(taskReceipts.summary ? { analyticalTaskOutcomeSummary: taskReceipts.summary } : {}),
+    };
+}
+function isDurableString(value) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= 1_000;
+}
+function durableStringList(value, maxItems = 32) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter(isDurableString).map((item) => item.trim()))].slice(0, maxItems);
+}
+function durableRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function taskReceiptTrustForArtifact(value) {
+    if (value === 'grounded')
+        return 'governed';
+    return ANALYTICAL_TASK_OUTCOME_TRUST_STATES.has(value)
+        ? value
+        : undefined;
+}
+function canonicalTaskResultProofForArtifact(value) {
+    const artifact = durableRecord(value);
+    const trustState = taskReceiptTrustForArtifact(artifact?.trustState);
+    if (!artifact || artifact.kind !== 'answer' || !trustState || trustState === 'blocked')
+        return undefined;
+    const payload = durableRecord(artifact.payload);
+    const result = durableRecord(payload?.result);
+    const fingerprint = result?.resultFingerprint;
+    if (!result || !isDurableString(fingerprint)
+        || !Array.isArray(result.columns) || result.columns.length === 0
+        || !Array.isArray(result.rows))
+        return undefined;
+    return { resultFingerprint: fingerprint, trustState };
+}
+function canonicalTaskResultProofsByTask(steps) {
+    const byTask = new Map();
+    if (!Array.isArray(steps))
+        return byTask;
+    for (const rawStep of steps) {
+        const step = durableRecord(rawStep);
+        const taskId = step?.askAnalystTaskId;
+        if (!step || !isDurableString(taskId) || !Array.isArray(step.artifacts))
+            continue;
+        const proofs = step.artifacts
+            .map(canonicalTaskResultProofForArtifact)
+            .filter((proof) => Boolean(proof));
+        if (proofs.length > 0) {
+            const byFingerprint = new Map();
+            for (const proof of proofs) {
+                const existing = byFingerprint.get(proof.resultFingerprint);
+                byFingerprint.set(proof.resultFingerprint, existing
+                    ? leastTrustedTaskReceiptState([existing, proof.trustState])
+                    : proof.trustState);
+            }
+            byTask.set(taskId, byFingerprint);
+        }
+    }
+    return byTask;
+}
+function sanitizeTaskOutcomeFailure(value) {
+    const failure = durableRecord(value);
+    if (!failure || !isDurableString(failure.code) || !isDurableString(failure.message))
+        return undefined;
+    if (failure.phase !== 'planning' && failure.phase !== 'execution' && failure.phase !== 'dependency')
+        return undefined;
+    return { version: 1, code: failure.code, message: failure.message, phase: failure.phase };
+}
+function sanitizeTaskOutcomeGap(value) {
+    const gap = durableRecord(value);
+    const allowedCodes = new Set([
+        'MISSING_MEASURE', 'MISSING_DIMENSION', 'MISSING_ATTRIBUTE', 'MISSING_RELATIONSHIP',
+        'MISSING_RUNTIME_CAPABILITY', 'RESULT_CONTRACT_MISMATCH', 'PROVIDER_UNAVAILABLE',
+        'EXECUTION_FAILED', 'AMBIGUOUS_MEANING', 'POLICY_BLOCKED',
+    ]);
+    const allowedPhases = new Set([
+        'retrieval', 'meaning', 'planning', 'compilation', 'execution', 'presentation',
+    ]);
+    const allowedRoutes = new Set([
+        'certified', 'semantic', 'governed_relational', 'generated', 'research',
+    ]);
+    if (!gap || !allowedCodes.has(gap.code)
+        || !allowedPhases.has(gap.phase)
+        || !isDurableString(gap.message) || typeof gap.recoverable !== 'boolean'
+        || typeof gap.planFrozen !== 'boolean')
+        return undefined;
+    const attemptedRoutes = Array.isArray(gap.attemptedRoutes)
+        ? gap.attemptedRoutes.filter((route) => typeof route === 'string' && allowedRoutes.has(route))
+        : [];
+    return {
+        version: 1,
+        code: gap.code,
+        phase: gap.phase,
+        message: gap.message,
+        searchedSources: durableStringList(gap.searchedSources),
+        attemptedRoutes,
+        missing: durableStringList(gap.missing),
+        recoverable: gap.recoverable,
+        planFrozen: gap.planFrozen,
+        nextActions: durableStringList(gap.nextActions),
+    };
+}
+function leastTrustedTaskReceiptState(states) {
+    if (states.length === 0)
+        return 'blocked';
+    const score = {
+        certified: 4, governed: 3, review_required: 2, not_applicable: 1, blocked: 0,
+    };
+    return states.reduce((least, candidate) => score[candidate] < score[least] ? candidate : least);
+}
+/**
+ * Read local V3 task receipts as untrusted JSON. Successful status is valid
+ * only when the same task step contains a canonical immutable result artifact
+ * with the advertised fingerprint. This also keeps V1/V2 records readable:
+ * absent additive fields remain absent.
+ */
+function sanitizeTaskOutcomeReceipts(input) {
+    const rawSummary = durableRecord(input.summary);
+    const rawOutcomes = Array.isArray(input.outcomes) ? input.outcomes : undefined;
+    if (!rawOutcomes && !rawSummary)
+        return {};
+    const canonicalByTask = canonicalTaskResultProofsByTask(input.steps);
+    const outcomes = [];
+    const seenTaskIds = new Set();
+    for (const rawOutcome of rawOutcomes ?? []) {
+        const outcome = durableRecord(rawOutcome);
+        const taskId = outcome?.taskId;
+        const status = outcome?.status;
+        if (!outcome || !isDurableString(taskId)
+            || !ANALYTICAL_TASK_OUTCOME_STATUSES.has(status)
+            || seenTaskIds.has(taskId))
+            continue;
+        seenTaskIds.add(taskId);
+        const persistedTrustState = ANALYTICAL_TASK_OUTCOME_TRUST_STATES.has(outcome.trustState)
+            ? outcome.trustState
+            : undefined;
+        const requestedSuccess = status === 'completed' || status === 'partial';
+        const resultFingerprint = isDurableString(outcome.resultFingerprint) ? outcome.resultFingerprint : undefined;
+        const canonicalTrustState = resultFingerprint
+            ? canonicalByTask.get(taskId)?.get(resultFingerprint)
+            : undefined;
+        const canonicalResult = Boolean(canonicalTrustState);
+        if (requestedSuccess && !canonicalResult) {
+            outcomes.push({
+                version: 1,
+                taskId,
+                status: 'blocked',
+                trustState: 'blocked',
+                summary: 'This persisted task result has no matching immutable canonical artifact.',
+                failure: {
+                    version: 1,
+                    code: 'TASK_RESULT_ARTIFACT_UNVERIFIED',
+                    message: 'This persisted task result has no matching immutable canonical artifact.',
+                    phase: 'execution',
+                },
+            });
+            continue;
+        }
+        const trustState = canonicalTrustState
+            ? persistedTrustState
+                ? leastTrustedTaskReceiptState([persistedTrustState, canonicalTrustState])
+                : canonicalTrustState
+            : persistedTrustState ?? 'blocked';
+        outcomes.push({
+            version: 1,
+            taskId,
+            status: status,
+            trustState,
+            ...(isDurableString(outcome.summary) ? { summary: outcome.summary } : {}),
+            ...(canonicalResult && resultFingerprint ? { resultFingerprint } : {}),
+            ...(sanitizeTaskOutcomeGap(outcome.gap) ? { gap: sanitizeTaskOutcomeGap(outcome.gap) } : {}),
+            ...(sanitizeTaskOutcomeFailure(outcome.failure) ? { failure: sanitizeTaskOutcomeFailure(outcome.failure) } : {}),
+            ...(status === 'dependency_blocked' ? { dependencyTaskIds: durableStringList(outcome.dependencyTaskIds) } : {}),
+        });
+    }
+    const requestedTaskCount = typeof rawSummary?.taskCount === 'number' && Number.isFinite(rawSummary.taskCount)
+        ? Math.max(0, Math.min(100, Math.floor(rawSummary.taskCount)))
+        : 0;
+    // Preserve an execution-pending compiler checkpoint only when it makes no
+    // success claim. It becomes execution-final after the first child step.
+    const mayKeepEmptySummary = outcomes.length === 0
+        && requestedTaskCount > 0
+        && durableStringList(rawSummary?.successfulTaskIds).length === 0;
+    if (outcomes.length === 0 && !mayKeepEmptySummary)
+        return {};
+    const successfulTaskIds = outcomes
+        .filter((outcome) => outcome.status === 'completed' || outcome.status === 'partial')
+        .map((outcome) => outcome.taskId);
+    const failedTaskIds = outcomes
+        .filter((outcome) => outcome.status !== 'completed' && outcome.status !== 'partial' && outcome.status !== 'dependency_blocked')
+        .map((outcome) => outcome.taskId);
+    const dependencyBlockedTaskIds = outcomes
+        .filter((outcome) => outcome.status === 'dependency_blocked')
+        .map((outcome) => outcome.taskId);
+    const taskCount = Math.max(requestedTaskCount, outcomes.length);
+    const summary = {
+        version: 1,
+        status: successfulTaskIds.length === 0
+            ? 'blocked'
+            : failedTaskIds.length > 0 || dependencyBlockedTaskIds.length > 0 || successfulTaskIds.length < taskCount
+                ? 'partial'
+                : 'completed',
+        trustState: leastTrustedTaskReceiptState(outcomes
+            .filter((outcome) => outcome.status === 'completed' || outcome.status === 'partial')
+            .map((outcome) => outcome.trustState ?? 'blocked')),
+        taskCount,
+        successfulTaskIds,
+        failedTaskIds,
+        dependencyBlockedTaskIds,
+    };
+    return {
+        ...(outcomes.length > 0 ? { outcomes } : {}),
+        summary,
+    };
+}
+/**
+ * A restart never turns an in-flight Ask into a completed parent answer, but
+ * it must not erase a completed independent child whose canonical result was
+ * checkpointed before the interruption. Keep only blocked diagnostics plus
+ * artifact/result pairs proved by the V3 task receipt.
+ */
+function retainedInterruptedArtifacts(progress, userCancelled) {
+    if (userCancelled)
+        return progress.artifacts;
+    const retainedIds = new Set(progress.artifacts
+        .filter((artifact) => artifact.trustState === 'blocked')
+        .map((artifact) => artifact.id));
+    for (const outcome of progress.analyticalTaskOutcomes ?? []) {
+        if ((outcome.status !== 'completed' && outcome.status !== 'partial') || !outcome.resultFingerprint)
+            continue;
+        const step = progress.steps.find((candidate) => candidate.askAnalystTaskId === outcome.taskId);
+        const artifact = step?.artifacts.find((candidate) => canonicalTaskResultProofForArtifact(candidate)?.resultFingerprint === outcome.resultFingerprint);
+        if (artifact)
+            retainedIds.add(artifact.id);
+    }
+    return progress.artifacts.filter((artifact) => retainedIds.has(artifact.id));
+}
 function isAgentRunRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;