@citeark/agent 0.3.20

package/src/assets/readiness.mjs

@@ -0,0 +1,130 @@
+export function createAssetReadiness(plan, {
+  state = "planned",
+  manifest = null,
+  admission = null,
+  preparationMode = null,
+  cacheHit = false,
+  message = null,
+} = {}) {
+  const records = new Map((Array.isArray(manifest?.assets) ? manifest.assets : [])
+    .map((record) => [record?.assetId, record]));
+  const assets = (Array.isArray(plan?.assets) ? plan.assets : []).slice(0, 32).map((asset) => {
+    const record = records.get(asset.id);
+    return {
+      id: asset.id,
+      kind: asset.kind,
+      identity: String(asset.identity ?? asset.id).slice(0, 240),
+      required: asset.required === true,
+      action: asset.decision?.action ?? "unknown",
+      status: record?.status ?? assetStatus(state, asset),
+      expectedDownloadBytes: asset.expectedDownloadBytes,
+      preparedBytes: record?.totalBytes ?? null,
+      sourceClass: asset.sourceLocators?.[0]?.sourceClass ?? asset.sourceLocators?.[0]?.source ?? null,
+    };
+  });
+  const admissionSummary = admission?.summary ?? admission;
+  const admittedCount = number(
+    admissionSummary?.admittedCount ?? admissionSummary?.admittedTargetCount,
+  );
+  const retryableCount = number(
+    admissionSummary?.transportRetryableAssetCount
+      ?? admissionSummary?.retryableCount
+      ?? admissionSummary?.retryableTargetCount,
+  );
+  const unavailableCount = number(
+    admissionSummary?.transportUnavailableAssetCount
+      ?? admissionSummary?.terminalCount
+      ?? admissionSummary?.blockedCount
+      ?? admissionSummary?.blockedTargetCount,
+  );
+  const reachableCount = number(
+    admissionSummary?.transportReachableAssetCount ?? admittedCount,
+  );
+  const transportStatus = unavailableCount > 0
+    ? "unavailable"
+    : retryableCount > 0
+      ? "retrying"
+      : new Set(["planned", "preparing"]).has(state) && !admissionSummary
+        ? "checking"
+        : "ready";
+  const scientificCompleteness = plan?.scientificCompleteness ?? {
+    status: "undetermined",
+    missingKinds: [],
+    missingRequirements: [],
+    invalidBindings: [],
+    summary: { total: 0, required: 0, covered: 0, notRequired: 0, missing: 0 },
+  };
+  const preparationStatus = state === "prepared"
+    ? "prepared"
+    : state === "blocked"
+      ? "blocked"
+      : state === "failed"
+        ? "failed"
+      : state === "preparing"
+          ? "preparing"
+          : state === "deferred"
+            ? "deferred"
+            : "pending";
+  const staticBlockedCount = number(admissionSummary?.blockedTargetCount);
+  const handoffAllowed = admissionSummary
+    ? staticBlockedCount === 0 && admittedCount > 0
+    : true;
+  const cacheUsable = preparationStatus === "prepared";
+  return {
+    schemaVersion: "0.1",
+    kind: "citeark.asset-readiness",
+    state,
+    transport: {
+      status: transportStatus,
+      reachable: reachableCount,
+      retryable: retryableCount,
+      unavailable: unavailableCount,
+      // Compatibility alias for existing public projections.
+      blocked: unavailableCount,
+    },
+    scientificCompleteness: {
+      status: scientificCompleteness.status,
+      missingKinds: scientificCompleteness.missingKinds ?? [],
+      missingRequirements: scientificCompleteness.missingRequirements ?? [],
+      invalidBindings: scientificCompleteness.invalidBindings ?? [],
+      summary: scientificCompleteness.summary,
+      requirements: (scientificCompleteness.items ?? []).map((item) => ({
+        kind: item.kind,
+        required: item.required,
+        status: item.status,
+        reason: item.reason,
+      })),
+    },
+    preparation: {
+      status: preparationStatus,
+      mode: cacheHit ? "cache" : preparationMode,
+      cacheHit,
+      completed: assets.filter((asset) => new Set(["prepared", "stream_ready", "metadata_verified"]).has(asset.status)).length,
+      total: assets.length,
+      assets,
+    },
+    agentHandoff: {
+      allowed: handoffAllowed,
+      cacheUsable,
+      fallbackRequired: handoffAllowed && !cacheUsable,
+      mode: cacheUsable ? "prepared_cache" : "autonomous_agent",
+    },
+    // "Ready" means the complete reproduction Agent may be started. It does
+    // not claim that optional prefetching or scientific validation succeeded.
+    reproductionReady: handoffAllowed,
+    ...(message ? { message: String(message).slice(0, 500) } : {}),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function assetStatus(state, asset) {
+  if (state === "preparing") return "preparing";
+  if (state === "deferred") return "deferred";
+  if (state === "blocked" || state === "failed") return state;
+  if (asset?.decision?.action === "blocked") return "deferred";
+  return "pending";
+}
+
+function number(value) {
+  return Number.isSafeInteger(Number(value)) && Number(value) >= 0 ? Number(value) : 0;
+}

package/src/assets/reproduction-admission.mjs

@@ -0,0 +1,355 @@
+import { lookup } from "node:dns/promises";
+
+import { assetTransportCompatibilityIssues } from "./source-grounding.mjs";
+import { automaticAdmissionByExperiment } from "../research/automatic-admission.mjs";
+import { probePublicAssetUrl } from "./public-asset-probe.mjs";
+
+export { probePublicAssetUrl } from "./public-asset-probe.mjs";
+
+const DEFAULT_OBSERVATION_TTL_MS = 30 * 60_000;
+const DEFAULT_EXTERNAL_RETRIES = 2;
+
+export class ReproductionAdmissionProbeError extends Error {
+  constructor(message, admission, {
+    externalRetryCount = 0,
+    maxExternalRetries = DEFAULT_EXTERNAL_RETRIES,
+  } = {}) {
+    super(message);
+    this.name = "ReproductionAdmissionProbeError";
+    this.externalRetryCount = nonNegativeInteger(externalRetryCount);
+    this.maxExternalRetries = nonNegativeInteger(maxExternalRetries);
+    this.retryable = this.externalRetryCount < this.maxExternalRetries;
+    this.failureCategory = "admission";
+    this.failureCode = "admission.public_asset_probe_transient";
+    this.recoveryAction = this.retryable
+      ? "平台将在不消耗科研目标尝试额度的情况下重新探测公开资产"
+      : "公开资产在多轮平台探测后仍不可达；保留完整探测记录并停止自动重试";
+    this.admission = admission;
+  }
+}
+
+/**
+ * Split the static automatic-run decision from public transport observation.
+ *
+ * A target is admitted when its immutable Research Plan is eligible for an
+ * automatic run. Link probes only describe whether the optional prefetcher can
+ * save work before the autonomous reproduction Agent starts. A transient,
+ * unavailable, gated, or structurally surprising transport is handed to that
+ * Agent as an observation; it never becomes a scientific or execution verdict.
+ */
+export async function assessAutomaticReproductionAdmission({
+  research,
+  targets,
+  datasetRegistry,
+  fetchImpl = fetch,
+  resolveHost = lookup,
+  timeoutMs = 12_000,
+  previousAdmission,
+  explicitlySelectedExperimentIds = [],
+  observationTtlMs = DEFAULT_OBSERVATION_TTL_MS,
+  probeMaxAttempts = 3,
+  retryBaseDelayMs,
+  retryMaxDelayMs,
+  sleepImpl,
+  randomImpl,
+  observe,
+  now = () => new Date(),
+}) {
+  const experiments = new Map(
+    (Array.isArray(research?.experiments) ? research.experiments : [])
+      .map((experiment) => [experiment.id, experiment]),
+  );
+  const staticAdmissions = automaticAdmissionByExperiment(research);
+  const explicitlySelected = new Set(explicitlySelectedExperimentIds);
+  const registry = datasetRegistryMap(datasetRegistry);
+  const observations = new Map();
+  const cachedObservations = reusableObservations(previousAdmission, {
+    now: now(),
+    observationTtlMs,
+  });
+  const admittedTargets = [];
+  const blockedTargets = [];
+  const transportReports = [];
+
+  for (const target of Array.isArray(targets) ? targets : []) {
+    const experiment = experiments.get(target.experimentId);
+    const staticAdmission = staticAdmissions.get(target.experimentId);
+    const remainingReasons = (staticAdmission?.reasons ?? []).filter(
+      (reason) => !(
+        explicitlySelected.has(target.experimentId)
+        && isExplicitSelectionReason(reason.code)
+      ),
+    );
+    if (!experiment || (!staticAdmission?.automatic && remainingReasons.length > 0)) {
+      blockedTargets.push({
+        ...target,
+        state: "blocked",
+        reasonCode: "admission.static_ineligible",
+        reasons: remainingReasons.length ? remainingReasons : [{
+          code: "admission.experiment_missing",
+          message: "Research Plan 缺少目标实验",
+        }],
+      });
+      continue;
+    }
+
+    const assetResults = [];
+    for (const asset of staticAdmission.publicAssetsToProbe) {
+      const urls = publicAssetUrls(asset, registry);
+      const probes = [];
+      for (const url of urls) {
+        const key = String(url);
+        let observation = observations.get(key);
+        if (!observation) {
+          const cached = cachedObservations.get(key);
+          if (cached) {
+            observation = { ...cached, reused: true };
+            emitCachedObservation(observe, observation);
+          } else {
+            observation = await probePublicAssetUrl(key, {
+              fetchImpl,
+              resolveHost,
+              timeoutMs,
+              maxAttempts: probeMaxAttempts,
+              ...(retryBaseDelayMs === undefined ? {} : { retryBaseDelayMs }),
+              ...(retryMaxDelayMs === undefined ? {} : { retryMaxDelayMs }),
+              ...(sleepImpl === undefined ? {} : { sleepImpl }),
+              ...(randomImpl === undefined ? {} : { randomImpl }),
+              observe,
+              now,
+            });
+          }
+          observations.set(key, observation);
+        }
+        const preparationIssues = observation.status === "reachable"
+          ? [
+              ...assetTransportCompatibilityIssues(asset, key),
+              ...assetInventoryPreparationHints(asset, observation),
+            ]
+          : [];
+        probes.push({
+          ...observation,
+          ...(preparationIssues.length ? { preparationIssues } : {}),
+        });
+        if (observation.status === "reachable") break;
+      }
+      const reachable = probes.some((probe) => probe.status === "reachable");
+      const retryable = probes.some((probe) => probe.status === "retryable");
+      const preparationIssues = [...new Set(
+        probes.flatMap((probe) => probe.preparationIssues ?? []),
+      )];
+      assetResults.push({
+        assetId: asset.id,
+        identity: asset.identity,
+        status: reachable ? "reachable" : retryable ? "retryable" : "unavailable",
+        ...(preparationIssues.length ? {
+          preparationIssues,
+        } : {}),
+        probes,
+      });
+    }
+    const transportStatus = assetResults.some((asset) => asset.status === "unavailable")
+      ? "unavailable"
+      : assetResults.some((asset) => asset.status === "retryable")
+        ? "retryable"
+        : "reachable";
+    transportReports.push({
+      ...target,
+      status: transportStatus,
+      assets: assetResults,
+      handoff: transportStatus === "reachable"
+        ? "prefetch_candidate"
+        : "reproduction_agent_fallback",
+    });
+    admittedTargets.push(target);
+  }
+
+  const observationValues = [...observations.values()];
+  const transportAssetResults = transportReports.flatMap((report) => report.assets);
+  return {
+    schemaVersion: "0.1",
+    policy: "static-eligibility-plus-transport-observation/v2",
+    admittedTargets,
+    blockedTargets,
+    // Backward-compatible field: transport failures no longer schedule a new
+    // Processing Worker, so there are no retryable admission targets.
+    retryableTargets: [],
+    transportReports,
+    observations: observationValues,
+    summary: {
+      targetCount: Array.isArray(targets) ? targets.length : 0,
+      admittedTargetCount: admittedTargets.length,
+      blockedTargetCount: blockedTargets.length,
+      retryableTargetCount: 0,
+      transportReachableTargetCount: transportReports.filter(
+        (report) => report.status === "reachable",
+      ).length,
+      transportRetryableTargetCount: transportReports.filter(
+        (report) => report.status === "retryable",
+      ).length,
+      transportUnavailableTargetCount: transportReports.filter(
+        (report) => report.status === "unavailable",
+      ).length,
+      transportReachableAssetCount: transportAssetResults.filter(
+        (asset) => asset.status === "reachable",
+      ).length,
+      transportRetryableAssetCount: transportAssetResults.filter(
+        (asset) => asset.status === "retryable",
+      ).length,
+      transportUnavailableAssetCount: transportAssetResults.filter(
+        (asset) => asset.status === "unavailable",
+      ).length,
+      preparationIssueCount: transportAssetResults.reduce(
+        (sum, asset) => sum + (asset.preparationIssues?.length ?? 0),
+        0,
+      ),
+      probedUrlCount: observationValues.length,
+      requestAttemptCount: observationValues.reduce(
+        (sum, item) => sum + nonNegativeInteger(item?.attemptCount),
+        0,
+      ),
+      reusedObservationCount: observationValues.filter((item) => item?.reused === true).length,
+    },
+    assessedAt: now().toISOString(),
+  };
+}
+
+function isExplicitSelectionReason(code) {
+  return code === "admission.proxy_requires_selection"
+    || code === "admission.cross_hardware_requires_selection";
+}
+
+export function assertNoTransientAdmissionFailures(admission, options = {}) {
+  // Kept as a compatibility shim for callers outside the main pipeline.
+  // Public transport observations are advisory and must never create another
+  // Worker or consume a scientific target attempt.
+  void options;
+  return admission;
+}
+
+function reusableObservations(previousAdmission, { now, observationTtlMs }) {
+  const cutoff = now.getTime() - Math.max(0, Number(observationTtlMs) || 0);
+  return new Map(
+    (Array.isArray(previousAdmission?.observations) ? previousAdmission.observations : [])
+      .filter((observation) => observation?.status === "reachable")
+      .filter((observation) => {
+        const observedAt = Date.parse(observation?.observedAt ?? "");
+        return Number.isFinite(observedAt) && observedAt >= cutoff;
+      })
+      .filter((observation) => typeof observation?.url === "string")
+      .map((observation) => [observation.url, observation]),
+  );
+}
+
+function emitCachedObservation(observe, observation) {
+  if (typeof observe !== "function") return;
+  try {
+    observe({
+      schemaVersion: "1.0",
+      kind: "decision",
+      component: "public_asset_probe",
+      operation: "reuse_recent_success",
+      outcome: { status: "succeeded", retryable: false },
+      details: {
+        url: observation.url,
+        observedAt: observation.observedAt,
+        cachePolicy: "same-processing-job/30m",
+      },
+    });
+  } catch {
+    // Logging failure cannot invalidate a still-fresh successful observation.
+  }
+}
+
+function publicAssetUrls(asset, registry) {
+  const urls = Array.isArray(asset?.sourceUrls) ? [...asset.sourceUrls] : [];
+  const registryUrl = registry.get(asset?.registryDatasetId)?.candidateTransport?.url;
+  if (typeof registryUrl === "string" && !urls.includes(registryUrl)) urls.push(registryUrl);
+  return urls;
+}
+
+export function assetInventoryPreparationHints(asset, observation) {
+  const inventory = observation?.inventory;
+  if (inventory?.provider !== "hugging-face") return [];
+  const issues = [];
+  const acquisition = asset?.acquisition ?? {};
+  const files = Array.isArray(inventory.files) ? inventory.files : [];
+  const requiredPaths = Array.isArray(acquisition.requiredPaths)
+    ? acquisition.requiredPaths.filter((value) => typeof value === "string" && value)
+    : [];
+  const literalPaths = requiredPaths.filter((pattern) => !/[?*\[]/.test(pattern));
+  const patternPaths = requiredPaths.filter((pattern) => /[?*\[]/.test(pattern));
+
+  for (const requiredPath of literalPaths) {
+    if (!files.some((file) => file?.path === requiredPath)) {
+      issues.push(`Hugging Face 文件清单缺少必需路径 ${requiredPath}`);
+    }
+  }
+  if (
+    patternPaths.length
+    && !files.some((file) => patternPaths.some((pattern) => globMatches(pattern, file?.path)))
+  ) {
+    issues.push(`Hugging Face 文件清单没有匹配任何必需模式：${patternPaths.join(", ")}`);
+  }
+
+  const declaredRevision = typeof acquisition.revision === "string"
+    ? acquisition.revision.trim()
+    : "";
+  if (
+    /^[0-9a-f]{7,64}$/i.test(declaredRevision)
+    && typeof inventory.revision === "string"
+    && !inventory.revision.toLowerCase().startsWith(declaredRevision.toLowerCase())
+  ) {
+    issues.push(`Hugging Face revision 与计划不一致：声明 ${declaredRevision}，实际 ${inventory.revision}`);
+  }
+
+  const maximumDownloadBytes = Number(acquisition.maximumDownloadBytes);
+  const plannedBytes = plannedInventoryBytes(acquisition.mode, files, inventory.totalBytes, requiredPaths);
+  if (
+    Number.isSafeInteger(maximumDownloadBytes)
+    && maximumDownloadBytes > 0
+    && Number.isSafeInteger(plannedBytes)
+    && plannedBytes > maximumDownloadBytes
+  ) {
+    issues.push(`公开资产预计下载 ${plannedBytes} bytes，超过计划上限 ${maximumDownloadBytes} bytes`);
+  }
+  return issues;
+}
+
+// Compatibility export for older integrations. These are preparation hints,
+// not automatic-admission failures.
+export const assetInventoryCompatibilityIssues = assetInventoryPreparationHints;
+
+function plannedInventoryBytes(mode, files, totalBytes, requiredPaths) {
+  if (mode === "metadata") return 0;
+  if (mode === "selective" && requiredPaths.length) {
+    const matched = files.filter((file) =>
+      requiredPaths.some((pattern) => globMatches(pattern, file?.path)));
+    if (matched.some((file) => !Number.isSafeInteger(file?.bytes))) return null;
+    return matched.reduce((sum, file) => sum + file.bytes, 0);
+  }
+  return Number.isSafeInteger(totalBytes) ? totalBytes : null;
+}
+
+function globMatches(pattern, value) {
+  if (typeof value !== "string") return false;
+  const source = [...String(pattern)].map((character) => {
+    if (character === "*") return ".*";
+    if (character === "?") return ".";
+    return character.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${source}$`).test(value);
+}
+
+function datasetRegistryMap(value) {
+  return new Map(
+    (Array.isArray(value?.datasets) ? value.datasets : [])
+      .filter((dataset) => typeof dataset?.id === "string")
+      .map((dataset) => [dataset.id, dataset]),
+  );
+}
+
+function nonNegativeInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number >= 0 ? number : 0;
+}

package/src/assets/requirements.mjs

@@ -0,0 +1,152 @@
+export const ASSET_REQUIREMENT_KINDS = Object.freeze([
+  "author_code",
+  "model",
+  "tokenizer",
+  "training_data",
+  "evaluation_data",
+  "evaluator",
+  "configuration",
+  "dependencies",
+]);
+
+const REQUIREMENT_KIND_SET = new Set(ASSET_REQUIREMENT_KINDS);
+const UNDETERMINED_REASON = "Research Compiler did not determine this material requirement.";
+
+export function normalizeAssetRequirements(value, { fillMissing = false } = {}) {
+  const normalized = [];
+  const seen = new Set();
+  for (const candidate of Array.isArray(value) ? value : []) {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+    if (!REQUIREMENT_KIND_SET.has(candidate.kind) || seen.has(candidate.kind)) continue;
+    seen.add(candidate.kind);
+    normalized.push({
+      kind: candidate.kind,
+      required: candidate.required === true,
+      reason: text(candidate.reason) ?? "Research Compiler did not record why this material is or is not required.",
+      assetIds: stringList(candidate.assetIds),
+      checkIds: stringList(candidate.checkIds),
+      repository: candidate.repository === true,
+    });
+  }
+  if (fillMissing) {
+    for (const kind of ASSET_REQUIREMENT_KINDS) {
+      if (seen.has(kind)) continue;
+      normalized.push({
+        kind,
+        required: true,
+        reason: UNDETERMINED_REASON,
+        assetIds: [],
+        checkIds: [],
+        repository: false,
+      });
+    }
+  }
+  return normalized.sort(
+    (left, right) => ASSET_REQUIREMENT_KINDS.indexOf(left.kind)
+      - ASSET_REQUIREMENT_KINDS.indexOf(right.kind),
+  );
+}
+
+export function evaluateAssetRequirementCoverage({ requirements, assets, checks }) {
+  const raw = Array.isArray(requirements) ? requirements : [];
+  const normalized = normalizeAssetRequirements(raw);
+  const counts = new Map();
+  for (const candidate of raw) {
+    if (!REQUIREMENT_KIND_SET.has(candidate?.kind)) continue;
+    counts.set(candidate.kind, (counts.get(candidate.kind) ?? 0) + 1);
+  }
+  const missingKinds = ASSET_REQUIREMENT_KINDS.filter((kind) => !counts.has(kind));
+  const duplicateKinds = ASSET_REQUIREMENT_KINDS.filter((kind) => (counts.get(kind) ?? 0) > 1);
+  const assetIds = new Set((Array.isArray(assets) ? assets : [])
+    .filter((asset) => asset?.required === true)
+    .map((asset) => asset.id));
+  const checkIds = new Set((Array.isArray(checks) ? checks : []).map((check) => check?.id));
+  const items = normalized.map((requirement) => {
+    // Host-filled placeholders describe unknown requirements, not missing assets.
+    // Keep the conservative required flag for older consumers, but do not turn
+    // an absent compiler declaration into evidence that a material is needed.
+    const undetermined = requirement.reason === UNDETERMINED_REASON
+      && !requirement.repository && !requirement.assetIds.length && !requirement.checkIds.length;
+    const matchedAssetIds = requirement.assetIds.filter((id) => assetIds.has(id));
+    const matchedCheckIds = requirement.checkIds.filter((id) => checkIds.has(id));
+    const invalidAssetIds = requirement.assetIds.filter((id) => !assetIds.has(id));
+    const invalidCheckIds = requirement.checkIds.filter((id) => !checkIds.has(id));
+    const covered = !requirement.required
+      || requirement.repository
+      || matchedAssetIds.length > 0
+      || matchedCheckIds.length > 0;
+    return {
+      ...requirement,
+      status: undetermined ? "undetermined" : requirement.required ? covered ? "covered" : "missing" : "not_required",
+      matchedAssetIds,
+      matchedCheckIds,
+      invalidAssetIds,
+      invalidCheckIds,
+    };
+  });
+  const missingRequirements = items
+    .filter((item) => item.status === "missing")
+    .map((item) => item.kind);
+  const invalidBindings = items.flatMap((item) => [
+    ...item.invalidAssetIds.map((id) => `${item.kind}:asset:${id}`),
+    ...item.invalidCheckIds.map((id) => `${item.kind}:check:${id}`),
+  ]);
+  const undeterminedKinds = items.filter((item) => item.status === "undetermined").map((item) => item.kind);
+  const status = missingKinds.length || duplicateKinds.length || undeterminedKinds.length
+    ? "undetermined"
+    : missingRequirements.length || invalidBindings.length
+      ? "incomplete"
+      : "complete";
+  return {
+    schemaVersion: "0.1",
+    status,
+    items,
+    missingKinds,
+    duplicateKinds,
+    undeterminedKinds,
+    missingRequirements,
+    invalidBindings,
+    summary: {
+      total: ASSET_REQUIREMENT_KINDS.length,
+      required: items.filter((item) => item.required).length,
+      covered: items.filter((item) => item.status === "covered").length,
+      notRequired: items.filter((item) => item.status === "not_required").length,
+      missing: missingRequirements.length,
+      undetermined: undeterminedKinds.length + missingKinds.length,
+    },
+  };
+}
+
+export function assetRequirementCoverageFailures(coverage) {
+  if (coverage?.status === "complete") return [];
+  if (coverage?.status === "undetermined") {
+    const detail = [
+      ...(coverage.missingKinds ?? []).map((kind) => `缺少 ${kind}`),
+      ...(coverage.duplicateKinds ?? []).map((kind) => `${kind} 重复`),
+      ...(coverage.undeterminedKinds ?? []).map((kind) => `${kind} 待工作区核实`),
+    ];
+    return [{
+      assetId: null,
+      reasonCode: "asset.requirements_undetermined",
+      message: `科研资料需求清单无法判定：${detail.join("；") || "缺少完整需求声明"}。`,
+    }];
+  }
+  return [{
+    assetId: null,
+    reasonCode: "asset.requirements_incomplete",
+    message: `科研资料尚未闭合：${[
+      ...(coverage?.missingRequirements ?? []),
+      ...(coverage?.invalidBindings ?? []),
+    ].join("；") || "存在未满足需求"}。`,
+  }];
+}
+
+function stringList(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map(text)
+    .filter(Boolean))];
+}
+
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}