@tiangong-ai/cli 0.0.32 → 0.0.33

package/dist/research/workspace/discovery.js

@@ -0,0 +1,268 @@
+import { basename, join } from "node:path";
+import { appendEvidenceLedgerEvent, evidenceLedgerPath, listEvidenceCandidates, } from "./evidence-ledger.js";
+import { loadProjectEvidenceReceipts } from "./evidence.js";
+import { readJournal } from "./journal.js";
+import { parseDiscoveryAssessmentBatch, StructuredOutputError } from "./schemas.js";
+import { canonicalJson, isObject, readJsonFile, sha256Text, workspacePaths } from "./storage.js";
+export async function materializeDiscoveryEvidence(root, project, value) {
+    const closeout = parseCloseoutValue(value);
+    const assessments = await latestDiscoveryAssessments(root, project.id);
+    const admissions = assessments.filter(isAdmission);
+    const rejections = assessments.filter(isRejection);
+    const candidates = new Map((await listEvidenceCandidates(root, project.id)).map((candidate) => [candidate.id, candidate]));
+    const receipts = new Map((await loadProjectEvidenceReceipts(root, project.id)).map((receipt) => [
+        receipt.attemptId,
+        receipt,
+    ]));
+    const inputs = new Map(project.inputs.map((input) => [input.id, input]));
+    const admittedCandidateIds = new Set(admissions.map((item) => item.candidateId));
+    const rejectedCandidateIds = new Set(rejections.map((item) => item.candidateId));
+    for (const candidateId of [...admittedCandidateIds, ...rejectedCandidateIds]) {
+        if (!candidates.has(candidateId)) {
+            throw discoveryError(`Discovery decision refers to unknown candidate ${candidateId}.`);
+        }
+    }
+    for (const candidateId of admittedCandidateIds) {
+        if (rejectedCandidateIds.has(candidateId)) {
+            throw discoveryError(`Candidate ${candidateId} cannot be both admitted and rejected.`);
+        }
+    }
+    const requiredDimensions = new Set(project.evidenceRequirements.dimensions);
+    const judgmentIds = new Set(closeout.dimensionJudgments.map((item) => item.id));
+    if (judgmentIds.size !== requiredDimensions.size ||
+        [...requiredDimensions].some((dimension) => !judgmentIds.has(dimension))) {
+        throw discoveryError("Dimension judgments must cover every reviewed evidence dimension exactly once.");
+    }
+    const sources = admissions.map((admission) => {
+        if (admission.coverageDimensions.some((dimension) => !requiredDimensions.has(dimension))) {
+            throw discoveryError(`Admission ${admission.sourceId} declares an unreviewed evidence dimension.`);
+        }
+        const candidate = candidates.get(admission.candidateId);
+        const admissibleOrigin = candidate.occurrences.find((origin) => origin.kind === "input" || origin.kind === "broker");
+        if (!admissibleOrigin) {
+            throw new StructuredOutputError("Native Web or Browser discovery must first be formalized through an immutable broker receipt for the same canonical URL or DOI.", {
+                validation: ["native candidates require immutable broker provenance"],
+                candidateId: candidate.id,
+            });
+        }
+        const provenance = admissibleOrigin.kind === "broker"
+            ? brokerProvenance(admissibleOrigin.receiptId, admissibleOrigin.locator, receipts)
+            : inputProvenance(admissibleOrigin.inputId, admissibleOrigin.locator, inputs);
+        const input = provenance.kind === "input" ? inputs.get(provenance.id) : undefined;
+        return {
+            id: admission.sourceId,
+            title: candidate.title,
+            locator: provenance.locator,
+            relevance: admission.relevance,
+            provenance: { kind: provenance.kind, id: provenance.id },
+            sourceType: admission.sourceType,
+            retrievedAt: admissibleOrigin.retrievedAt,
+            fullTextAvailable: provenance.kind === "input" ? input?.fullText !== false : false,
+            url: candidate.url,
+            doi: candidate.doi,
+            publicationDate: candidate.publicationDate ?? input?.publicationDate ?? null,
+            excerpt: candidate.excerpt,
+            jsonPointer: admissibleOrigin.jsonPointer,
+            quality: admission.quality,
+            applicability: admission.applicability,
+            coverageDimensions: admission.coverageDimensions,
+        };
+    });
+    const sourceLimitations = admissions.flatMap((admission) => admission.limitations.map((limitation) => `${admission.sourceId}: ${limitation}`));
+    return {
+        schemaVersion: 1,
+        sources,
+        limitations: [...new Set([...closeout.limitations, ...sourceLimitations])],
+        coverage: {
+            dimensions: closeout.dimensionJudgments.map((item) => ({
+                id: item.id,
+                status: item.status,
+                sourceIds: [],
+            })),
+            sourceTypes: [],
+            fullTextSources: 0,
+            datedSources: 0,
+            publicationDateRange: { earliest: null, latest: null },
+            decision: "pass",
+            gaps: closeout.gaps,
+        },
+    };
+}
+export async function commitDiscoveryDecisions(root, projectId, value) {
+    parseCloseoutValue(value);
+    const assessments = await latestDiscoveryAssessments(root, projectId);
+    const events = await readJournal(evidenceLedgerPath(root, projectId));
+    const committed = new Set(events
+        .filter((event) => event.type === "candidate.admitted" || event.type === "candidate.rejected")
+        .map((event) => `${event.type}:${String(event.payload.judgmentSha256)}`));
+    for (const admission of assessments.filter(isAdmission)) {
+        const judgmentSha256 = sha256Text(canonicalJson(admission));
+        const key = `candidate.admitted:${judgmentSha256}`;
+        if (committed.has(key))
+            continue;
+        await appendEvidenceLedgerEvent(root, projectId, "candidate.admitted", {
+            candidateId: admission.candidateId,
+            sourceId: admission.sourceId,
+            sourceType: admission.sourceType,
+            judgmentSha256,
+            coverageDimensions: admission.coverageDimensions,
+        });
+    }
+    for (const rejection of assessments.filter(isRejection)) {
+        const judgmentSha256 = sha256Text(canonicalJson(rejection));
+        const key = `candidate.rejected:${judgmentSha256}`;
+        if (committed.has(key))
+            continue;
+        await appendEvidenceLedgerEvent(root, projectId, "candidate.rejected", {
+            candidateId: rejection.candidateId,
+            reasonCode: rejection.reasonCode,
+            rationale: rejection.rationale,
+            judgmentSha256,
+        });
+    }
+}
+export async function recordDiscoveryAssessmentBatch(input) {
+    const parsed = parseDiscoveryAssessmentBatch(input.value);
+    const assessments = parsed.assessments;
+    const project = await readJsonFile(join(workspacePaths(input.root).projects, input.projectId, "project.json"), `Research project ${input.projectId}`);
+    const packages = Array.isArray(project.packages) ? project.packages : [];
+    const discover = packages.find((workPackage) => isObject(workPackage) && workPackage.stage === "discover");
+    if (!isObject(discover) || discover.status !== "running") {
+        throw discoveryError("Discovery assessments may be recorded only during the active discover stage.");
+    }
+    const requiredDimensions = new Set(isObject(project.evidenceRequirements) && Array.isArray(project.evidenceRequirements.dimensions)
+        ? project.evidenceRequirements.dimensions.filter((dimension) => typeof dimension === "string")
+        : []);
+    const candidates = new Map((await listEvidenceCandidates(input.root, input.projectId)).map((candidate) => [
+        candidate.id,
+        candidate,
+    ]));
+    for (const assessment of assessments) {
+        const candidate = candidates.get(assessment.candidateId);
+        if (!candidate) {
+            throw discoveryError(`Discovery assessment refers to unknown candidate ${assessment.candidateId}.`);
+        }
+        if (assessment.decision === "admit") {
+            if (assessment.coverageDimensions.some((dimension) => !requiredDimensions.has(dimension))) {
+                throw discoveryError(`Admission ${assessment.sourceId} declares an unreviewed evidence dimension.`);
+            }
+            if (!candidate.occurrences.some((origin) => origin.kind === "input" || origin.kind === "broker")) {
+                throw discoveryError(`Native candidate ${candidate.id} must be formalized by a broker receipt before admission.`);
+            }
+        }
+    }
+    const existing = await latestDiscoveryAssessments(input.root, input.projectId);
+    const replacementIds = new Set(assessments.map((assessment) => assessment.candidateId));
+    const sourceOwners = new Map(existing
+        .filter(isAdmission)
+        .filter((assessment) => !replacementIds.has(assessment.candidateId))
+        .map((assessment) => [assessment.sourceId, assessment.candidateId]));
+    for (const assessment of assessments.filter(isAdmission)) {
+        const owner = sourceOwners.get(assessment.sourceId);
+        if (owner && owner !== assessment.candidateId) {
+            throw discoveryError(`Source ID ${assessment.sourceId} is already assigned to ${owner}.`);
+        }
+        sourceOwners.set(assessment.sourceId, assessment.candidateId);
+    }
+    const priorHashes = new Set((await readJournal(evidenceLedgerPath(input.root, input.projectId)))
+        .filter((event) => event.type === "candidate.assessed")
+        .map((event) => String(event.payload.assessmentSha256)));
+    let recorded = 0;
+    let unchanged = 0;
+    for (const assessment of assessments) {
+        const assessmentSha256 = sha256Text(canonicalJson(assessment));
+        if (priorHashes.has(assessmentSha256)) {
+            unchanged += 1;
+            continue;
+        }
+        await appendEvidenceLedgerEvent(input.root, input.projectId, "candidate.assessed", {
+            candidateId: assessment.candidateId,
+            decision: assessment.decision,
+            assessment,
+            assessmentSha256,
+        });
+        priorHashes.add(assessmentSha256);
+        recorded += 1;
+    }
+    const latest = await latestDiscoveryAssessments(input.root, input.projectId);
+    return {
+        recorded,
+        unchanged,
+        assessedCandidates: latest.length,
+        admittedCandidates: latest.filter(isAdmission).length,
+        rejectedCandidates: latest.filter(isRejection).length,
+    };
+}
+function brokerProvenance(receiptId, locator, receipts) {
+    const receipt = receiptId ? receipts.get(receiptId) : undefined;
+    if (!receipt || !locator || receipt.locator !== locator) {
+        throw discoveryError("Broker candidate provenance does not match an immutable receipt.");
+    }
+    return { kind: "broker", id: receipt.attemptId, locator: receipt.locator };
+}
+function inputProvenance(inputId, locator, inputs) {
+    const input = inputId ? inputs.get(inputId) : undefined;
+    const expectedLocator = input
+        ? join("inputs", input.id, basename(input.path)).replaceAll("\\", "/")
+        : null;
+    if (!input || !locator || locator !== expectedLocator) {
+        throw discoveryError("Input candidate provenance does not match a registered immutable input.");
+    }
+    return { kind: "input", id: input.id, locator: expectedLocator };
+}
+async function latestDiscoveryAssessments(root, projectId) {
+    const events = await readJournal(evidenceLedgerPath(root, projectId));
+    const latest = new Map();
+    for (const event of events) {
+        if (event.type !== "candidate.assessed" || !isObject(event.payload.assessment))
+            continue;
+        const assessment = event.payload.assessment;
+        if (!isAdmission(assessment) && !isRejection(assessment)) {
+            throw discoveryError("Persisted discovery assessment is malformed.");
+        }
+        latest.set(assessment.candidateId, assessment);
+    }
+    return [...latest.values()];
+}
+function parseCloseoutValue(value) {
+    if (value.schemaVersion !== 2 ||
+        !Array.isArray(value.limitations) ||
+        !Array.isArray(value.dimensionJudgments) ||
+        !Array.isArray(value.gaps) ||
+        value.dimensionJudgments.some((item) => !isDimensionJudgment(item))) {
+        throw discoveryError("Discovery closeout value is malformed.");
+    }
+    return value;
+}
+function isAdmission(value) {
+    return (isObject(value) &&
+        value.decision === "admit" &&
+        typeof value.candidateId === "string" &&
+        typeof value.sourceId === "string" &&
+        typeof value.sourceType === "string" &&
+        typeof value.relevance === "string" &&
+        isObject(value.quality) &&
+        typeof value.quality.level === "string" &&
+        typeof value.quality.rationale === "string" &&
+        typeof value.applicability === "string" &&
+        Array.isArray(value.coverageDimensions) &&
+        value.coverageDimensions.every((item) => typeof item === "string") &&
+        Array.isArray(value.limitations) &&
+        value.limitations.every((item) => typeof item === "string"));
+}
+function isRejection(value) {
+    return (isObject(value) &&
+        value.decision === "reject" &&
+        typeof value.candidateId === "string" &&
+        typeof value.reasonCode === "string" &&
+        typeof value.rationale === "string");
+}
+function isDimensionJudgment(value) {
+    return (isObject(value) &&
+        typeof value.id === "string" &&
+        ["covered", "partial", "missing"].includes(String(value.status)));
+}
+function discoveryError(message) {
+    return new StructuredOutputError(message, { validation: [message] });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/research/workspace/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/research/workspace/discovery.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,76 @@
+export declare const downloadBindingRecordSchema: {
+    readonly $id: "https://schemas.tiangong.ai/research/download-binding-input-v1.json";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "backend", "status", "downloadUrl"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "integer";
+            readonly const: 1;
+        };
+        readonly backend: {
+            readonly type: "string";
+            readonly enum: readonly ["native-browser", "chrome", "cloakbrowser", "skill-adapter", "direct-http"];
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["completed", "failed", "cancelled"];
+        };
+        readonly path: {
+            readonly type: "string";
+        };
+        readonly downloadUrl: {
+            readonly type: "string";
+            readonly format: "uri";
+        };
+        readonly suggestedFilename: {
+            readonly type: "string";
+            readonly maxLength: 500;
+        };
+        readonly downloadIdentifier: {
+            readonly type: "string";
+            readonly maxLength: 1000;
+        };
+        readonly failureCode: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$";
+        };
+    };
+};
+export interface EvidenceDownloadBinding {
+    schemaVersion: 1;
+    bindingId: string;
+    projectId: string;
+    candidateId: string;
+    backend: "native-browser" | "chrome" | "cloakbrowser" | "skill-adapter" | "direct-http";
+    status: "completed";
+    fileSha256: string;
+    fileBytes: number;
+    filePathSha256: string;
+    downloadUrl: string;
+    suggestedFilename: string | null;
+    downloadIdentifierSha256: string | null;
+    boundAt: string;
+    bindingSha256: string;
+}
+export declare function bindEvidenceDownload(input: {
+    root: string;
+    projectId: string;
+    candidateId: string;
+    value: Record<string, unknown>;
+}): Promise<{
+    status: "completed";
+    binding: EvidenceDownloadBinding;
+} | {
+    status: "failed" | "cancelled";
+    binding: null;
+    nextAction: string;
+}>;
+export declare function loadAndVerifyDownloadBinding(input: {
+    root: string;
+    projectId: string;
+    candidateId: string;
+    bindingId: string;
+    path: string;
+}): Promise<EvidenceDownloadBinding>;
+export declare function parseEvidenceDownloadBinding(value: unknown): EvidenceDownloadBinding;

package/dist/research/workspace/downloads.js

@@ -0,0 +1,274 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, readFile } from "node:fs/promises";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { CliError } from "../../errors.js";
+import { appendEvidenceLedgerEvent, evidenceLedgerPath, listEvidenceCandidates, } from "./evidence-ledger.js";
+import { readJournal } from "./journal.js";
+import { sanitizeResearchText, sanitizeResearchValue } from "./sanitization.js";
+import { canonicalJson, isObject, pathExists, readJsonFile, resolveContained, sha256File, sha256Text, workspacePaths, writeJsonAtomic, } from "./storage.js";
+import { loadWorkspaceConfig } from "./workspace.js";
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SENSITIVE_QUERY_KEY = /^(?:access[_-]?token|api[_-]?key|apikey|auth|authorization|awsaccesskeyid|code|cookie|credential|key|password|secret|session(?:[_-]?id)?|sig|signature|token|x[_-]amz[_-](?:credential|security[_-]?token|signature)|x[_-]goog[_-](?:credential|signature))$/i;
+const TRACKING_QUERY_KEY = /^(?:utm_[a-z0-9_]+|fbclid|gclid|mc_cid|mc_eid|ref|source)$/i;
+export const downloadBindingRecordSchema = {
+    $id: "https://schemas.tiangong.ai/research/download-binding-input-v1.json",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "backend", "status", "downloadUrl"],
+    properties: {
+        schemaVersion: { type: "integer", const: 1 },
+        backend: {
+            type: "string",
+            enum: ["native-browser", "chrome", "cloakbrowser", "skill-adapter", "direct-http"],
+        },
+        status: { type: "string", enum: ["completed", "failed", "cancelled"] },
+        path: { type: "string" },
+        downloadUrl: { type: "string", format: "uri" },
+        suggestedFilename: { type: "string", maxLength: 500 },
+        downloadIdentifier: { type: "string", maxLength: 1_000 },
+        failureCode: { type: "string", pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+    },
+};
+export async function bindEvidenceDownload(input) {
+    const value = sanitizeResearchValue(input.value);
+    if (!isObject(value))
+        throw downloadError("Download binding input must be a JSON object.");
+    const allowed = new Set([
+        "schemaVersion",
+        "backend",
+        "status",
+        "path",
+        "downloadUrl",
+        "suggestedFilename",
+        "downloadIdentifier",
+        "failureCode",
+    ]);
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    const backends = [
+        "native-browser",
+        "chrome",
+        "cloakbrowser",
+        "skill-adapter",
+        "direct-http",
+    ];
+    const statuses = ["completed", "failed", "cancelled"];
+    if (unknown.length ||
+        value.schemaVersion !== 1 ||
+        !backends.includes(value.backend) ||
+        !statuses.includes(value.status) ||
+        typeof value.downloadUrl !== "string" ||
+        (value.suggestedFilename !== undefined &&
+            (typeof value.suggestedFilename !== "string" || value.suggestedFilename.length > 500)) ||
+        (value.downloadIdentifier !== undefined &&
+            (typeof value.downloadIdentifier !== "string" || value.downloadIdentifier.length > 1_000)) ||
+        (value.failureCode !== undefined &&
+            (typeof value.failureCode !== "string" || !IDENTIFIER.test(value.failureCode)))) {
+        throw downloadError("Download binding input failed validation.");
+    }
+    const backend = value.backend;
+    const status = value.status;
+    const downloadUrl = safeDownloadUrl(value.downloadUrl);
+    await requireActiveAcquisition(input.root, input.projectId, input.candidateId);
+    if (status !== "completed") {
+        if (value.path !== undefined) {
+            throw downloadError("Failed or cancelled downloads must not claim a completed file path.");
+        }
+        const failureCode = typeof value.failureCode === "string" ? value.failureCode : `download-${status}`;
+        await appendEvidenceLedgerEvent(input.root, input.projectId, "download.failed", {
+            eventId: `download-event-${randomUUID()}`,
+            candidateId: input.candidateId,
+            backend,
+            status,
+            downloadUrl,
+            failureCode,
+            recordedAt: new Date().toISOString(),
+        });
+        return {
+            status,
+            binding: null,
+            nextAction: "Stop acquisition for this attempt, report the failure, and do not register an artifact or submit a successful acquisition decision.",
+        };
+    }
+    if (typeof value.path !== "string") {
+        throw downloadError("A completed download requires one explicit absolute file path.");
+    }
+    const sourcePath = requireExactExternalPath(input.root, value.path);
+    const [info, config] = await Promise.all([
+        lstat(sourcePath).catch(() => undefined),
+        loadWorkspaceConfig(input.root),
+    ]);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw downloadError("Downloaded file must be one existing regular non-symlink file.");
+    }
+    if (info.size < 1 || info.size > config.budget.maxBytesPerPackage) {
+        throw downloadError(`Downloaded file size must be 1-${config.budget.maxBytesPerPackage} bytes.`);
+    }
+    const fileSha256 = await sha256File(sourcePath);
+    const core = {
+        schemaVersion: 1,
+        bindingId: `download-${sha256Text(canonicalJson({ candidateId: input.candidateId, backend, fileSha256 })).slice(0, 24)}`,
+        projectId: input.projectId,
+        candidateId: input.candidateId,
+        backend,
+        status: "completed",
+        fileSha256,
+        fileBytes: info.size,
+        filePathSha256: sha256Text(sourcePath),
+        downloadUrl,
+        suggestedFilename: typeof value.suggestedFilename === "string"
+            ? safeFilename(value.suggestedFilename)
+            : safeFilename(basename(sourcePath)),
+        downloadIdentifierSha256: typeof value.downloadIdentifier === "string"
+            ? sha256Text(sanitizeResearchText(value.downloadIdentifier))
+            : null,
+        boundAt: new Date().toISOString(),
+    };
+    const binding = {
+        ...core,
+        bindingSha256: sha256Text(canonicalJson(core)),
+    };
+    const recordPath = downloadBindingPath(input.root, input.projectId, binding.bindingId);
+    if (await pathExists(recordPath)) {
+        const existing = parseEvidenceDownloadBinding(JSON.parse(await readFile(recordPath, "utf8")));
+        if (existing.fileSha256 !== binding.fileSha256 ||
+            existing.filePathSha256 !== binding.filePathSha256 ||
+            existing.candidateId !== binding.candidateId) {
+            throw downloadError("Download binding identity collides with different file provenance.");
+        }
+        await ensureBoundEvent(input.root, input.projectId, existing);
+        return { status: "completed", binding: existing };
+    }
+    await writeJsonAtomic(recordPath, binding, 0o444);
+    await chmod(recordPath, 0o444).catch(() => undefined);
+    await ensureBoundEvent(input.root, input.projectId, binding);
+    return { status: "completed", binding };
+}
+async function ensureBoundEvent(root, projectId, binding) {
+    const events = await readJournal(evidenceLedgerPath(root, projectId));
+    if (events.some((event) => event.type === "download.bound" &&
+        event.payload.bindingId === binding.bindingId &&
+        event.payload.bindingSha256 === binding.bindingSha256)) {
+        return;
+    }
+    await appendEvidenceLedgerEvent(root, projectId, "download.bound", {
+        bindingId: binding.bindingId,
+        bindingSha256: binding.bindingSha256,
+        candidateId: binding.candidateId,
+        backend: binding.backend,
+        fileSha256: binding.fileSha256,
+        fileBytes: binding.fileBytes,
+        downloadUrl: binding.downloadUrl,
+        suggestedFilename: binding.suggestedFilename,
+        downloadIdentifierSha256: binding.downloadIdentifierSha256,
+        boundAt: binding.boundAt,
+    });
+}
+export async function loadAndVerifyDownloadBinding(input) {
+    if (!/^download-[0-9a-f]{24}$/.test(input.bindingId)) {
+        throw downloadError("Download binding ID is invalid.");
+    }
+    const sourcePath = requireExactExternalPath(input.root, input.path);
+    const binding = parseEvidenceDownloadBinding(JSON.parse(await readFile(downloadBindingPath(input.root, input.projectId, input.bindingId), "utf8")));
+    const info = await lstat(sourcePath).catch(() => undefined);
+    if (binding.projectId !== input.projectId ||
+        binding.candidateId !== input.candidateId ||
+        binding.filePathSha256 !== sha256Text(sourcePath) ||
+        !info?.isFile() ||
+        info.isSymbolicLink() ||
+        info.size !== binding.fileBytes ||
+        (await sha256File(sourcePath)) !== binding.fileSha256) {
+        throw downloadError("Downloaded file no longer matches its exact event binding.");
+    }
+    return binding;
+}
+export function parseEvidenceDownloadBinding(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        typeof value.bindingId !== "string" ||
+        !/^download-[0-9a-f]{24}$/.test(value.bindingId) ||
+        typeof value.projectId !== "string" ||
+        typeof value.candidateId !== "string" ||
+        !["native-browser", "chrome", "cloakbrowser", "skill-adapter", "direct-http"].includes(String(value.backend)) ||
+        value.status !== "completed" ||
+        typeof value.fileSha256 !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.fileSha256) ||
+        !Number.isInteger(value.fileBytes) ||
+        typeof value.filePathSha256 !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.filePathSha256) ||
+        typeof value.downloadUrl !== "string" ||
+        (value.suggestedFilename !== null && typeof value.suggestedFilename !== "string") ||
+        (value.downloadIdentifierSha256 !== null &&
+            (typeof value.downloadIdentifierSha256 !== "string" ||
+                !/^[0-9a-f]{64}$/.test(value.downloadIdentifierSha256))) ||
+        typeof value.boundAt !== "string" ||
+        typeof value.bindingSha256 !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.bindingSha256)) {
+        throw downloadError("Download binding record is malformed.");
+    }
+    const { bindingSha256, ...core } = value;
+    if (sha256Text(canonicalJson(core)) !== bindingSha256) {
+        throw downloadError("Download binding record failed its hash binding.");
+    }
+    return value;
+}
+async function requireActiveAcquisition(root, projectId, candidateId) {
+    const [project, candidates] = await Promise.all([
+        readJsonFile(join(workspacePaths(root).projects, projectId, "project.json"), `Research project ${projectId}`),
+        listEvidenceCandidates(root, projectId),
+    ]);
+    const packages = Array.isArray(project.packages) ? project.packages : [];
+    const acquire = packages.find((workPackage) => isObject(workPackage) &&
+        workPackage.stage === "acquire" &&
+        workPackage.status === "running" &&
+        workPackage.executor === "producer");
+    if (!acquire) {
+        throw downloadError("Download binding is allowed only during active native acquisition.");
+    }
+    if (!candidates.some((candidate) => candidate.id === candidateId)) {
+        throw downloadError(`Download binding refers to unknown candidate ${candidateId}.`);
+    }
+}
+function requireExactExternalPath(root, path) {
+    const selected = resolve(path);
+    if (selected !== path)
+        throw downloadError("Downloaded file path must be absolute and normalized.");
+    const controlRoot = resolve(workspacePaths(root).control);
+    if (!relative(controlRoot, selected).startsWith(`..${sep}`) && selected !== controlRoot) {
+        throw downloadError("Downloaded file must be an explicit staging file outside control state.");
+    }
+    return selected;
+}
+function safeDownloadUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw downloadError("Download URL is invalid.");
+    }
+    if (url.protocol !== "https:")
+        throw downloadError("Download URL must use HTTPS.");
+    url.username = "";
+    url.password = "";
+    url.hash = "";
+    for (const key of [...url.searchParams.keys()]) {
+        if (SENSITIVE_QUERY_KEY.test(key) || TRACKING_QUERY_KEY.test(key)) {
+            url.searchParams.delete(key);
+        }
+    }
+    url.searchParams.sort();
+    return url.toString();
+}
+function safeFilename(value) {
+    const filename = sanitizeResearchText(basename(value))
+        .replace(/[\r\n\0]/g, "")
+        .trim();
+    return filename ? filename.slice(0, 500) : null;
+}
+function downloadBindingPath(root, projectId, bindingId) {
+    return resolveContained(workspacePaths(root).projects, `${projectId}/evidence/downloads/${bindingId}.json`);
+}
+function downloadError(message) {
+    return new CliError(message, { code: "RESEARCH_DOWNLOAD_BINDING_INVALID", exitCode: 3 });
+}
+//# sourceMappingURL=downloads.js.map