@tiangong-ai/cli 0.0.31 → 0.0.33

package/dist/research/workspace/projects.d.ts

@@ -5,7 +5,9 @@ export declare function loadProject(root: string, projectId: string): Promise<Pr
 export declare function listProjects(root: string): Promise<ProjectState[]>;
 export declare function saveProject(root: string, project: ProjectState): Promise<void>;
 export declare function retryProjectPackage(root: string, projectId: string, packageId?: string): Promise<ProjectState>;
-export declare function forkProject(root: string, sourceProjectId: string, targetProjectId: string, resumeThrough?: "discover" | "analyze" | "synthesize"): Promise<ProjectState>;
+export declare function forkProject(root: string, sourceProjectId: string, targetProjectId: string, resumeThrough?: "discover" | "acquire" | "analyze" | "synthesize"): Promise<ProjectState>;
+export declare function setProjectDisposition(root: string, projectId: string, disposition: "archived" | "abandoned", reason: string): Promise<ProjectState>;
+export declare function createProjectAddendum(root: string, sourceProjectId: string, targetProjectId: string): Promise<ProjectState>;
 export declare function refreshProject(project: ProjectState): ProjectState;
 export declare function nextReadyPackage(project: ProjectState): WorkPackage | undefined;
 export declare function packageById(project: ProjectState, packageId: string): WorkPackage;

package/dist/research/workspace/projects.js

@@ -5,9 +5,12 @@ import { CliError } from "../../errors.js";
 import { RESEARCH_CONTROL_DIRECTORY } from "./constants.js";
 import { appendJournalEvent } from "./journal.js";
 import { cloneProjectEvidenceReceipts } from "./evidence.js";
+import { appendEvidenceLedgerEvent, cloneEvidenceLedger, registerProjectInputCandidates, } from "./evidence-ledger.js";
+import { cloneProjectArtifactRecords } from "./artifacts.js";
+import { freezeEvidenceSnapshot, loadCurrentEvidenceSnapshot, loadImmutableEvidenceSnapshotChain, } from "./acquisition.js";
 import { projectInputsFromPlan, reverifyProjectInputPlan } from "./input-plan.js";
 import { evaluateProjectPreflight } from "./preflight.js";
-import { ensureDirectory, fileRecord, fileSize, readJsonFile, sha256File, workspacePaths, writeJsonAtomic, } from "./storage.js";
+import { ensureDirectory, fileRecord, fileSize, isObject, readJsonFile, sha256File, workspacePaths, writeJsonAtomic, } from "./storage.js";
 import { loadWorkspaceConfig, withWorkspaceLock } from "./workspace.js";
 const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{2,63}$/;
 export async function initializeProject(root, projectId, question, evidenceRequirements, budgetConfirmed = false, inputPlan) {
@@ -81,6 +84,9 @@ export async function initializeProject(root, projectId, question, evidenceRequi
                 costUsd: 0,
                 wallSeconds: 0,
             },
+            lineage: initialLineage("primary"),
+            handoff: initialHandoffState(),
+            evidenceState: initialEvidenceState(),
         };
         await Promise.all([
             ensureDirectory(projectRoot),
@@ -88,6 +94,7 @@ export async function initializeProject(root, projectId, question, evidenceRequi
             ensureDirectory(join(projectRoot, "runs")),
         ]);
         await writeJsonAtomic(projectPath, project);
+        await registerProjectInputCandidates(root, projectId, project.inputs);
         await appendJournalEvent(paths.journal, "project.initialized", projectId, {
             projectId,
             questionSha256: await hashQuestion(normalizedQuestion),
@@ -136,12 +143,17 @@ export async function addProjectInput(root, projectId, inputPath, role) {
             path: canonicalInput,
             sha256,
             bytes: await fileSize(canonicalInput),
+            sourceType: "primary",
+            dimensions: [],
+            fullText: true,
+            publicationDate: null,
             addedAt: new Date().toISOString(),
         };
         project.inputs.push(input);
         project.inputs.sort((left, right) => left.id.localeCompare(right.id));
         project.updatedAt = new Date().toISOString();
         await saveProject(root, project);
+        await registerProjectInputCandidates(root, projectId, [input]);
         await appendJournalEvent(workspacePaths(root).journal, "project.input.added", projectId, {
             projectId,
             inputId: input.id,
@@ -176,6 +188,19 @@ export async function retryProjectPackage(root, projectId, packageId) {
     validateProjectId(projectId);
     return withWorkspaceLock(root, "project.retry", async () => {
         const project = await loadProject(root, projectId);
+        if (project.status === "archived" ||
+            project.status === "abandoned" ||
+            project.lineage.supersededBy) {
+            throw new CliError("Historical projects cannot be retried; continue from the authoritative project.", {
+                code: "RESEARCH_PROJECT_NOT_AUTHORITATIVE",
+                exitCode: 3,
+                details: {
+                    projectId,
+                    status: project.status,
+                    supersededBy: project.lineage.supersededBy,
+                },
+            });
+        }
         const selected = packageId
             ? packageById(project, packageId)
             : project.packages.find((item) => item.status === "failed" || item.status === "retry");
@@ -225,6 +250,18 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
     }
     return withWorkspaceLock(root, "project.fork", async () => {
         const source = await loadProject(root, sourceProjectId);
+        if (source.lineage.supersededBy) {
+            throw new CliError(`Project ${sourceProjectId} is historical; fork the authoritative project ${source.lineage.supersededBy}.`, { code: "RESEARCH_PROJECT_NOT_AUTHORITATIVE", exitCode: 3 });
+        }
+        if (source.status === "archived" || source.status === "abandoned") {
+            throw new CliError(`Project ${sourceProjectId} is ${source.status} and cannot be forked.`, {
+                code: "RESEARCH_PROJECT_NOT_AUTHORITATIVE",
+                exitCode: 3,
+            });
+        }
+        if (source.handoff.state !== "agent-actionable") {
+            throw new CliError(`Project ${sourceProjectId} has an unresolved ${source.handoff.state} handoff.`, { code: "RESEARCH_PROJECT_HANDOFF_REQUIRED", exitCode: 3 });
+        }
         const targetRoot = join(workspacePaths(root).projects, targetProjectId);
         if (await lstat(targetRoot).catch(() => undefined)) {
             throw new CliError(`Research project already exists: ${targetProjectId}`, {
@@ -235,7 +272,7 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
         const config = await loadWorkspaceConfig(root);
         const packages = defaultWorkPackages(config);
         const inheritedStages = resumeThrough
-            ? ["discover", "analyze", "synthesize"].slice(0, ["discover", "analyze", "synthesize"].indexOf(resumeThrough) + 1)
+            ? ["discover", "acquire", "analyze", "synthesize"].slice(0, ["discover", "acquire", "analyze", "synthesize"].indexOf(resumeThrough) + 1)
             : [];
         for (const stage of inheritedStages) {
             const sourcePackage = source.packages.find((item) => item.stage === stage);
@@ -266,6 +303,9 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
                 ...source.evidenceRequirements,
                 dimensions: [...source.evidenceRequirements.dimensions],
                 sourceTypes: [...source.evidenceRequirements.sourceTypes],
+                requiredCapabilityIds: [...(source.evidenceRequirements.requiredCapabilityIds ?? [])],
+                requiredCompanionIds: [...(source.evidenceRequirements.requiredCompanionIds ?? [])],
+                requiredDiscoveryScopes: [...(source.evidenceRequirements.requiredDiscoveryScopes ?? [])],
             },
             packages,
             usage: {
@@ -276,6 +316,13 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
                 costUsd: 0,
                 wallSeconds: 0,
             },
+            lineage: {
+                ...initialLineage("fork"),
+                derivedFrom: sourceProjectId,
+                supersedes: sourceProjectId,
+            },
+            handoff: initialHandoffState(),
+            evidenceState: initialEvidenceState(),
         };
         await Promise.all([
             ensureDirectory(targetRoot),
@@ -285,6 +332,7 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
         const inheritedOutputs = [];
         const stageOutput = {
             discover: "outputs/evidence.json",
+            acquire: "outputs/acquisition.json",
             analyze: "outputs/analysis.json",
             synthesize: "outputs/report.md",
         };
@@ -299,20 +347,223 @@ export async function forkProject(root, sourceProjectId, targetProjectId, resume
         }
         if (inheritedStages.includes("discover")) {
             await cloneProjectEvidenceReceipts(root, sourceProjectId, targetProjectId);
+            await cloneEvidenceLedger(root, sourceProjectId, targetProjectId);
+        }
+        if (inheritedStages.includes("acquire")) {
+            await cloneProjectArtifactRecords(root, sourceProjectId, targetProjectId);
         }
         refreshProject(project);
         await writeJsonAtomic(join(targetRoot, "project.json"), project);
+        if (inheritedStages.includes("acquire")) {
+            await freezeEvidenceSnapshot(root, project);
+            inheritedOutputs.push(await fileRecord(join(targetRoot, "outputs", "evidence-snapshot.json"), "outputs/evidence-snapshot.json"));
+            await saveProject(root, project);
+        }
+        source.lineage.supersededBy = targetProjectId;
+        source.evidenceState.staleReason = `Superseded by recovery fork ${targetProjectId}.`;
+        refreshProject(source);
+        await saveProject(root, source);
+        await appendEvidenceLedgerEvent(root, sourceProjectId, "project.superseded", {
+            sourceProjectId,
+            supersededBy: targetProjectId,
+            reason: "recovery-fork",
+        });
         await appendJournalEvent(workspacePaths(root).journal, "project.forked", targetProjectId, {
             sourceProjectId,
             targetProjectId,
             resumeThrough: resumeThrough ?? null,
             inheritedOutputs,
             inheritedUsage: false,
+            sourceSuperseded: true,
+        });
+        return project;
+    });
+}
+export async function setProjectDisposition(root, projectId, disposition, reason) {
+    validateProjectId(projectId);
+    const normalizedReason = reason.trim();
+    if (normalizedReason.length < 8 || normalizedReason.length > 500) {
+        throw new CliError("Project disposition reason must contain 8-500 characters.", {
+            code: "RESEARCH_PROJECT_DISPOSITION_INVALID",
+            exitCode: 2,
+        });
+    }
+    return withWorkspaceLock(root, `project.${disposition}`, async () => {
+        const project = refreshProject(await loadProject(root, projectId));
+        if (project.status === "running" ||
+            project.packages.some((item) => item.status === "running")) {
+            throw new CliError("Abort the active native stage before archiving or abandoning this project.", { code: "RESEARCH_PROJECT_DISPOSITION_INVALID", exitCode: 3 });
+        }
+        if (project.status === "archived" || project.status === "abandoned") {
+            if (project.status === disposition)
+                return project;
+            throw new CliError(`Project is already ${project.status}.`, {
+                code: "RESEARCH_PROJECT_DISPOSITION_INVALID",
+                exitCode: 3,
+            });
+        }
+        if (disposition === "archived" && project.status !== "complete" && project.status !== "stale") {
+            throw new CliError("Archive is for complete or superseded history; use abandon for unfinished work.", { code: "RESEARCH_PROJECT_DISPOSITION_INVALID", exitCode: 3 });
+        }
+        if (disposition === "abandoned" &&
+            (project.status === "complete" || project.status === "stale")) {
+            throw new CliError("Abandon is for unfinished work; archive complete or superseded history instead.", { code: "RESEARCH_PROJECT_DISPOSITION_INVALID", exitCode: 3 });
+        }
+        project.status = disposition;
+        project.updatedAt = new Date().toISOString();
+        await saveProject(root, project);
+        await appendJournalEvent(workspacePaths(root).journal, `project.${disposition}`, projectId, {
+            projectId,
+            disposition,
+            reason: normalizedReason,
+            supersededBy: project.lineage.supersededBy,
         });
         return project;
     });
 }
+export async function createProjectAddendum(root, sourceProjectId, targetProjectId) {
+    validateProjectId(sourceProjectId);
+    validateProjectId(targetProjectId);
+    if (sourceProjectId === targetProjectId) {
+        throw new CliError("Addendum target must use a different project ID.", {
+            code: "RESEARCH_PROJECT_ADDENDUM_INVALID",
+            exitCode: 2,
+        });
+    }
+    return withWorkspaceLock(root, "project.addendum", async () => {
+        const source = refreshProject(await loadProject(root, sourceProjectId));
+        if (source.status !== "complete" || source.packages.at(-1)?.stage !== "close") {
+            throw new CliError("An addendum requires a mechanically closed source project.", {
+                code: "RESEARCH_PROJECT_ADDENDUM_INVALID",
+                exitCode: 3,
+            });
+        }
+        if (source.lineage.supersededBy) {
+            throw new CliError(`Project ${sourceProjectId} is already superseded by ${source.lineage.supersededBy}.`, { code: "RESEARCH_PROJECT_ADDENDUM_INVALID", exitCode: 3 });
+        }
+        const snapshot = await loadCurrentEvidenceSnapshot(root, sourceProjectId);
+        const closurePath = join(workspacePaths(root).projects, sourceProjectId, "outputs", "closure.json");
+        const closure = await readJsonFile(closurePath, `Research closure ${sourceProjectId}`).catch(() => null);
+        const closureSnapshot = closure?.evidenceSnapshot &&
+            typeof closure.evidenceSnapshot === "object" &&
+            !Array.isArray(closure.evidenceSnapshot)
+            ? closure.evidenceSnapshot
+            : null;
+        if (closure?.projectId !== sourceProjectId ||
+            closure?.status !== "complete" ||
+            closureSnapshot?.snapshotId !== snapshot.snapshotId ||
+            closureSnapshot?.snapshotSha256 !== snapshot.snapshotSha256 ||
+            source.evidenceState.closureSnapshotId !== snapshot.snapshotId ||
+            source.evidenceState.currentSnapshotSha256 !== snapshot.snapshotSha256) {
+            throw new CliError("Source closure is not bound to its current evidence snapshot.", {
+                code: "RESEARCH_PROJECT_ADDENDUM_INVALID",
+                exitCode: 3,
+            });
+        }
+        const targetRoot = join(workspacePaths(root).projects, targetProjectId);
+        if (await lstat(targetRoot).catch(() => undefined)) {
+            throw new CliError(`Research project already exists: ${targetProjectId}`, {
+                code: "RESEARCH_PROJECT_EXISTS",
+                exitCode: 2,
+            });
+        }
+        const config = await loadWorkspaceConfig(root);
+        const now = new Date().toISOString();
+        const target = {
+            schemaVersion: 1,
+            id: targetProjectId,
+            question: source.question,
+            status: "ready",
+            createdAt: now,
+            updatedAt: now,
+            budgetConfirmedAt: source.budgetConfirmedAt,
+            inputs: source.inputs.map((input) => ({ ...input })),
+            evidenceRequirements: {
+                ...source.evidenceRequirements,
+                dimensions: [...source.evidenceRequirements.dimensions],
+                sourceTypes: [...source.evidenceRequirements.sourceTypes],
+                requiredCapabilityIds: [...(source.evidenceRequirements.requiredCapabilityIds ?? [])],
+                requiredCompanionIds: [...(source.evidenceRequirements.requiredCompanionIds ?? [])],
+                requiredDiscoveryScopes: [...(source.evidenceRequirements.requiredDiscoveryScopes ?? [])],
+            },
+            packages: defaultWorkPackages(config),
+            usage: {
+                tokens: 0,
+                inputTokens: 0,
+                cachedInputTokens: 0,
+                outputTokens: 0,
+                costUsd: 0,
+                wallSeconds: 0,
+            },
+            lineage: {
+                kind: "addendum",
+                derivedFrom: sourceProjectId,
+                supersedes: sourceProjectId,
+                supersededBy: null,
+                baseSnapshotId: snapshot.snapshotId,
+                baseSnapshotSha256: snapshot.snapshotSha256,
+            },
+            handoff: initialHandoffState(),
+            evidenceState: initialEvidenceState(),
+        };
+        await Promise.all([
+            ensureDirectory(targetRoot),
+            ensureDirectory(join(targetRoot, "outputs")),
+            ensureDirectory(join(targetRoot, "runs")),
+            ensureDirectory(join(targetRoot, "evidence", "snapshots")),
+        ]);
+        const inheritedOutputs = [];
+        for (const logicalPath of ["outputs/evidence.json", "outputs/acquisition.json"]) {
+            const sourcePath = join(workspacePaths(root).projects, sourceProjectId, logicalPath);
+            const destination = join(targetRoot, logicalPath);
+            await cp(sourcePath, destination, { errorOnExist: true, force: false });
+            inheritedOutputs.push(await fileRecord(destination, logicalPath));
+        }
+        const baseSnapshotLogicalPath = "outputs/base-evidence-snapshot.json";
+        const sourceSnapshotPath = join(workspacePaths(root).projects, sourceProjectId, "evidence", "snapshots", `${snapshot.snapshotSha256}.json`);
+        const snapshotChain = await loadImmutableEvidenceSnapshotChain(root, sourceProjectId, snapshot.snapshotSha256);
+        for (const chainSnapshot of snapshotChain) {
+            await cp(join(workspacePaths(root).projects, sourceProjectId, "evidence", "snapshots", `${chainSnapshot.snapshotSha256}.json`), join(targetRoot, "evidence", "snapshots", `${chainSnapshot.snapshotSha256}.json`), { errorOnExist: true, force: false });
+        }
+        await cp(sourceSnapshotPath, join(targetRoot, baseSnapshotLogicalPath), {
+            errorOnExist: true,
+            force: false,
+        });
+        inheritedOutputs.push(await fileRecord(join(targetRoot, baseSnapshotLogicalPath), baseSnapshotLogicalPath));
+        await cloneProjectEvidenceReceipts(root, sourceProjectId, targetProjectId);
+        await cloneEvidenceLedger(root, sourceProjectId, targetProjectId);
+        await cloneProjectArtifactRecords(root, sourceProjectId, targetProjectId);
+        await appendEvidenceLedgerEvent(root, targetProjectId, "addendum.created", {
+            sourceProjectId,
+            targetProjectId,
+            baseSnapshotId: snapshot.snapshotId,
+            baseSnapshotSha256: snapshot.snapshotSha256,
+        });
+        await writeJsonAtomic(join(targetRoot, "project.json"), target);
+        source.lineage.supersededBy = targetProjectId;
+        source.evidenceState.staleReason = `Superseded by evidence addendum ${targetProjectId}.`;
+        refreshProject(source);
+        await saveProject(root, source);
+        await appendEvidenceLedgerEvent(root, sourceProjectId, "project.superseded", {
+            sourceProjectId,
+            supersededBy: targetProjectId,
+            snapshotId: snapshot.snapshotId,
+            snapshotSha256: snapshot.snapshotSha256,
+        });
+        await appendJournalEvent(workspacePaths(root).journal, "project.addendum.created", targetProjectId, {
+            sourceProjectId,
+            targetProjectId,
+            baseSnapshotId: snapshot.snapshotId,
+            baseSnapshotSha256: snapshot.snapshotSha256,
+            inheritedOutputs,
+            originalClosurePreserved: true,
+        });
+        return target;
+    });
+}
 export function refreshProject(project) {
+    if (project.status === "archived" || project.status === "abandoned")
+        return project;
     const now = Date.now();
     for (const workPackage of project.packages) {
         if (workPackage.status !== "pending" && workPackage.status !== "retry")
@@ -326,7 +577,13 @@ export function refreshProject(project) {
         if (dependenciesComplete)
             workPackage.status = "ready";
     }
-    if (project.packages.some((item) => item.status === "failed"))
+    if (project.lineage.supersededBy || project.evidenceState.staleReason)
+        project.status = "stale";
+    else if (project.handoff.state === "user-action-required")
+        project.status = "waiting-user";
+    else if (project.handoff.state === "external-response-required")
+        project.status = "waiting-external";
+    else if (project.packages.some((item) => item.status === "failed"))
         project.status = "blocked";
     else if (project.packages.every((item) => item.status === "complete"))
         project.status = "complete";
@@ -339,6 +596,8 @@ export function refreshProject(project) {
 }
 export function nextReadyPackage(project) {
     refreshProject(project);
+    if (project.handoff.state !== "agent-actionable")
+        return undefined;
     return project.packages.find((workPackage) => workPackage.status === "ready");
 }
 export function packageById(project, packageId) {
@@ -355,7 +614,8 @@ function defaultWorkPackages(config) {
     const maxAttempts = config.budget.maxAttemptsPerPackage;
     return [
         workPackage("discover", "discover", "agent", "producer", [], ["outputs/evidence.json"], maxAttempts),
-        workPackage("analyze", "analyze", "agent", "producer", ["discover"], ["outputs/analysis.json"], maxAttempts),
+        workPackage("acquire", "acquire", "agent", "producer", ["discover"], ["outputs/acquisition.json"], maxAttempts),
+        workPackage("analyze", "analyze", "agent", "producer", ["acquire"], ["outputs/analysis.json"], maxAttempts),
         workPackage("synthesize", "synthesize", "agent", "producer", ["analyze"], ["outputs/report.md"], maxAttempts),
         workPackage("review", "review", "agent", "reviewer", ["synthesize"], ["outputs/review.json"], maxAttempts),
         workPackage("close", "close", "verify", "mechanical", ["review"], ["outputs/closure.json"], 1),
@@ -383,6 +643,17 @@ function validateProjectShape(project, expectedId) {
     if (project.schemaVersion !== 1 ||
         project.id !== expectedId ||
         !PROJECT_ID_PATTERN.test(project.id) ||
+        ![
+            "ready",
+            "running",
+            "blocked",
+            "complete",
+            "stale",
+            "waiting-user",
+            "waiting-external",
+            "archived",
+            "abandoned",
+        ].includes(project.status) ||
         typeof project.question !== "string" ||
         (project.budgetConfirmedAt !== null && typeof project.budgetConfirmedAt !== "string") ||
         !Array.isArray(project.inputs) ||
@@ -394,7 +665,10 @@ function validateProjectShape(project, expectedId) {
         typeof project.usage.cachedInputTokens !== "number" ||
         typeof project.usage.outputTokens !== "number" ||
         typeof project.usage.costUsd !== "number" ||
-        typeof project.usage.wallSeconds !== "number") {
+        typeof project.usage.wallSeconds !== "number" ||
+        !isProjectLineage(project.lineage) ||
+        !isProjectHandoff(project.handoff) ||
+        !isProjectEvidenceState(project.evidenceState)) {
         throw new CliError(`Research project state is invalid: ${expectedId}`, {
             code: "RESEARCH_PROJECT_INVALID",
             exitCode: 2,
@@ -412,12 +686,83 @@ function validateProjectShape(project, expectedId) {
         });
     }
 }
+function initialLineage(kind) {
+    return {
+        kind,
+        derivedFrom: null,
+        supersedes: null,
+        supersededBy: null,
+        baseSnapshotId: null,
+        baseSnapshotSha256: null,
+    };
+}
+function initialEvidenceState() {
+    return {
+        currentSnapshotId: null,
+        currentSnapshotSha256: null,
+        closureSnapshotId: null,
+        staleReason: null,
+    };
+}
+function initialHandoffState() {
+    return {
+        state: "agent-actionable",
+        reasonCode: null,
+        summary: null,
+        requestedActions: [],
+        evidenceGaps: [],
+        requestedAt: null,
+        resolvedAt: null,
+        resolutionNote: null,
+    };
+}
+function isProjectLineage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const lineage = value;
+    return (["primary", "fork", "addendum"].includes(String(lineage.kind)) &&
+        nullableString(lineage.derivedFrom) &&
+        nullableString(lineage.supersedes) &&
+        nullableString(lineage.supersededBy) &&
+        nullableString(lineage.baseSnapshotId) &&
+        nullableSha256(lineage.baseSnapshotSha256));
+}
+function isProjectEvidenceState(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const state = value;
+    return (nullableString(state.currentSnapshotId) &&
+        nullableSha256(state.currentSnapshotSha256) &&
+        nullableString(state.closureSnapshotId) &&
+        nullableString(state.staleReason));
+}
+function isProjectHandoff(value) {
+    if (!isObject(value))
+        return false;
+    return (["agent-actionable", "user-action-required", "external-response-required"].includes(String(value.state)) &&
+        nullableString(value.reasonCode) &&
+        nullableString(value.summary) &&
+        Array.isArray(value.requestedActions) &&
+        value.requestedActions.every((item) => typeof item === "string") &&
+        Array.isArray(value.evidenceGaps) &&
+        value.evidenceGaps.every((item) => typeof item === "string") &&
+        nullableString(value.requestedAt) &&
+        nullableString(value.resolvedAt) &&
+        nullableString(value.resolutionNote));
+}
+function nullableString(value) {
+    return value === null || typeof value === "string";
+}
+function nullableSha256(value) {
+    return value === null || (typeof value === "string" && /^[0-9a-f]{64}$/.test(value));
+}
 function defaultEvidenceRequirements(config) {
     return config.mode === "production-research"
         ? {
             dimensions: ["research-question"],
             sourceTypes: ["primary"],
             requiredCapabilityIds: [],
+            requiredCompanionIds: [],
             requiredDiscoveryScopes: [],
             minSources: 3,
             minFullTextSources: 1,
@@ -429,6 +774,7 @@ function defaultEvidenceRequirements(config) {
             dimensions: ["research-question"],
             sourceTypes: [],
             requiredCapabilityIds: [],
+            requiredCompanionIds: [],
             requiredDiscoveryScopes: [],
             minSources: 1,
             minFullTextSources: 0,
@@ -444,6 +790,9 @@ export function normalizeEvidenceRequirements(value) {
         requiredCapabilityIds: [
             ...new Set((value.requiredCapabilityIds ?? []).map(normalizeRequirementId)),
         ].sort(),
+        requiredCompanionIds: [
+            ...new Set((value.requiredCompanionIds ?? []).map(normalizeRequirementId)),
+        ].sort(),
         requiredDiscoveryScopes: [
             ...new Set((value.requiredDiscoveryScopes ?? []).map(normalizeRequirementId)),
         ].sort(),
@@ -473,6 +822,9 @@ function isEvidenceRequirements(value) {
         (value.requiredCapabilityIds === undefined ||
             (Array.isArray(value.requiredCapabilityIds) &&
                 value.requiredCapabilityIds.every(validRequirementId))) &&
+        (value.requiredCompanionIds === undefined ||
+            (Array.isArray(value.requiredCompanionIds) &&
+                value.requiredCompanionIds.every(validRequirementId))) &&
         (value.requiredDiscoveryScopes === undefined ||
             (Array.isArray(value.requiredDiscoveryScopes) &&
                 value.requiredDiscoveryScopes.every(validRequirementId))) &&