dsh-plugin-compat-check 0.1.3 → 0.1.5

package/kernel/lib/functional-health-contract.mjs

@@ -0,0 +1,337 @@
+/** Pure declarations/results contract. Author declarations never imply execution or compatibility. */
+export const FUNCTIONAL_HEALTH_KIND = "plugin-compat-check/functional-health";
+export const FUNCTIONAL_HEALTH_LIMITS = Object.freeze({
+  checks: 32,
+  path: 256,
+  selector: 160,
+  responseBytes: 65536,
+  requestMs: 3000,
+  totalMs: 180000,
+});
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const keys = (v, allowed) =>
+  object(v) && Object.keys(v).every((k) => allowed.includes(k));
+const exactVersion = (v) =>
+  typeof v === "string" &&
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(
+    v,
+  );
+const digest = (v) => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
+const bounded = (v, n) =>
+  typeof v === "string" && v.length > 0 && v.length <= n;
+const artifactValid = (a) =>
+  keys(a, ["name", "version", "sha256"]) &&
+  typeof a.name === "string" &&
+  /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(a.name) &&
+  a.name.length <= 214 &&
+  exactVersion(a.version) &&
+  digest(a.sha256);
+export function validFunctionalPath(v) {
+  return (
+    bounded(v, FUNCTIONAL_HEALTH_LIMITS.path) &&
+    /^\/(?!\/)[A-Za-z0-9/_.,~-]*$/.test(v) &&
+    !v.split("/").some((p) => p === ".." || p === ".")
+  );
+}
+export function validateFunctionalManifest(value) {
+  const errors = [];
+  if (
+    !keys(value, ["schemaVersion", "artifact", "dshVersion", "checks"]) ||
+    value.schemaVersion !== 1 ||
+    !artifactValid(value.artifact) ||
+    !exactVersion(value.dshVersion)
+  )
+    errors.push("Invalid manifest schema or exact artifact/DSH identity");
+  if (
+    !Array.isArray(value?.checks) ||
+    value.checks.length < 1 ||
+    value.checks.length > FUNCTIONAL_HEALTH_LIMITS.checks
+  )
+    errors.push("Expected 1..32 bounded checks");
+  else {
+    const seen = new Set();
+    for (const c of value.checks) {
+      if (
+        !object(c) ||
+        !bounded(c.id, 64) ||
+        !/^[A-Za-z0-9_-]+$/.test(c.id) ||
+        seen.has(c.id) ||
+        !validFunctionalPath(c.path)
+      ) {
+        errors.push("Invalid check id/path or duplicate id");
+        continue;
+      }
+      seen.add(c.id);
+      if (c.type === "http") {
+        if (
+          !keys(c, ["id", "type", "path", "status", "json"]) ||
+          !Number.isInteger(c.status) ||
+          c.status < 200 ||
+          c.status > 599 ||
+          (c.status >= 300 && c.status < 400)
+        )
+          errors.push("Invalid HTTP check");
+        if (
+          c.json !== undefined &&
+          (!keys(c.json, ["pointer", "equals"]) ||
+            typeof c.json.pointer !== "string" ||
+            c.json.pointer.length > 256 ||
+            !/^(?:\/(?:[^~\u0000-\u001f]|~[01])*)*$/.test(c.json.pointer) ||
+            !Object.hasOwn(c.json, "equals") ||
+            ![null, "string", "boolean", "number"].includes(
+              c.json.equals === null ? null : typeof c.json.equals,
+            ) ||
+            (typeof c.json.equals === "string" && c.json.equals.length > 256) ||
+            (typeof c.json.equals === "number" &&
+              !Number.isFinite(c.json.equals)))
+        )
+          errors.push(
+            "JSON assertion must be a bounded JSON pointer and scalar value",
+          );
+      } else if (c.type === "dom") {
+        if (
+          !keys(c, [
+            "id",
+            "type",
+            "path",
+            "selector",
+            "minCount",
+            "maxCount",
+          ]) ||
+          !bounded(c.selector, FUNCTIONAL_HEALTH_LIMITS.selector) ||
+          !/^[A-Za-z0-9_#.*\[\]="'\- >]+$/.test(c.selector) ||
+          !Number.isInteger(c.minCount) ||
+          !Number.isInteger(c.maxCount) ||
+          c.minCount < 0 ||
+          c.maxCount < c.minCount ||
+          c.maxCount > 1000
+        )
+          errors.push("Invalid bounded DOM selector/count check");
+      } else errors.push("Only HTTP GET and DOM selector counts are supported");
+    }
+  }
+  return errors.length ? { valid: false, errors } : { valid: true, value };
+}
+
+/** Imported evidence is an offline assertion, not a signature or compatibility verdict. */
+export function validateFunctionalHealthResult(value, expectedIdentity = {}) {
+  const errors = [];
+  const iso = (v) =>
+    typeof v === "string" &&
+    Number.isFinite(Date.parse(v)) &&
+    new Date(v).toISOString() === v;
+  if (
+    !keys(value, [
+      "schemaVersion",
+      "kind",
+      "status",
+      "identity",
+      "startedAt",
+      "completedAt",
+      "checks",
+      "cleanup",
+      "limitations",
+      "error",
+      "declaration",
+    ]) ||
+    value.schemaVersion !== 1 ||
+    value.kind !== FUNCTIONAL_HEALTH_KIND ||
+    !["tested-pass", "tested-failed", "error"].includes(value.status)
+  )
+    errors.push("Invalid functional health result schema/status");
+  const declarationValidation = validateFunctionalManifest(value?.declaration);
+  if (!declarationValidation.valid)
+    errors.push("Missing or invalid executed declaration");
+  const id = value?.identity;
+  if (
+    declarationValidation.valid &&
+    (value.declaration.dshVersion !== id?.dshVersion ||
+      ["name", "version", "sha256"].some(
+        (k) => value.declaration.artifact[k] !== id?.artifact?.[k],
+      ))
+  )
+    errors.push("Executed declaration identity differs from result");
+  if (
+    !keys(id, ["artifact", "dshVersion", "manifestSha256"]) ||
+    !artifactValid(id.artifact) ||
+    !exactVersion(id.dshVersion) ||
+    !digest(id.manifestSha256)
+  )
+    errors.push("Invalid exact evidence identity");
+  if (
+    !iso(value?.startedAt) ||
+    !iso(value?.completedAt) ||
+    value.completedAt < value.startedAt ||
+    Date.parse(value.completedAt) - Date.parse(value.startedAt) >
+      FUNCTIONAL_HEALTH_LIMITS.totalMs + 30000
+  )
+    errors.push("Invalid bounded measurement times");
+  if (
+    !keys(value?.cleanup, ["stopped", "removed", "errors"]) ||
+    typeof value.cleanup.stopped !== "boolean" ||
+    typeof value.cleanup.removed !== "boolean" ||
+    (value.cleanup.errors !== undefined &&
+      (!Array.isArray(value.cleanup.errors) ||
+        value.cleanup.errors.length > 8 ||
+        value.cleanup.errors.some((x) => !bounded(x, 512))))
+  )
+    errors.push("Invalid cleanup evidence");
+  if (
+    !Array.isArray(value?.limitations) ||
+    value.limitations.length < 1 ||
+    value.limitations.length > 8 ||
+    value.limitations.some((x) => !bounded(x, 512)) ||
+    (value.error !== undefined && !bounded(value.error, 1024))
+  )
+    errors.push("Invalid limitations/error summary");
+  const seen = new Set();
+  if (!Array.isArray(value?.checks) || value.checks.length > 32)
+    errors.push("Invalid check evidence");
+  else
+    for (const c of value.checks) {
+      const e = c?.evidence;
+      if (
+        !keys(c, ["id", "type", "status", "evidence"]) ||
+        !bounded(c.id, 64) ||
+        !/^[A-Za-z0-9_-]+$/.test(c.id) ||
+        seen.has(c.id) ||
+        !["http", "dom"].includes(c.type) ||
+        !["pass", "failed", "error"].includes(c.status) ||
+        !keys(e, [
+          "httpStatus",
+          "responseBytes",
+          "jsonMatched",
+          "count",
+          "elapsedMs",
+          "error",
+        ]) ||
+        !Number.isFinite(e.elapsedMs) ||
+        e.elapsedMs < 0 ||
+        e.elapsedMs > FUNCTIONAL_HEALTH_LIMITS.totalMs
+      ) {
+        errors.push("Invalid check row");
+        continue;
+      }
+      seen.add(c.id);
+      if (c.status === "error") {
+        if (!bounded(e.error, 256)) errors.push("Missing check error");
+      } else if (c.type === "http") {
+        if (
+          !Number.isInteger(e.httpStatus) ||
+          e.httpStatus < 200 ||
+          e.httpStatus > 599 ||
+          !Number.isInteger(e.responseBytes) ||
+          e.responseBytes < 0 ||
+          e.responseBytes > 65536 ||
+          (e.jsonMatched !== undefined && typeof e.jsonMatched !== "boolean") ||
+          e.count !== undefined ||
+          e.error !== undefined
+        )
+          errors.push("Invalid HTTP evidence");
+      } else if (
+        !Number.isInteger(e.count) ||
+        e.count < 0 ||
+        e.httpStatus !== undefined ||
+        e.responseBytes !== undefined ||
+        e.jsonMatched !== undefined ||
+        e.error !== undefined
+      )
+        errors.push("Invalid DOM evidence");
+    }
+  if (errors.length) return { valid: false, errors };
+  if (declarationValidation.valid && Array.isArray(value?.checks)) {
+    const expected = value.declaration.checks;
+    if (
+      (value.status !== "error" && value.checks.length !== expected.length) ||
+      value.checks.length > expected.length
+    )
+      errors.push("Evidence must cover every declared check in order");
+    for (let i = 0; i < value.checks.length; i++) {
+      const row = value.checks[i],
+        check = expected[i];
+      if (!row || !check || row.id !== check.id || row.type !== check.type) {
+        errors.push("Evidence check identity/order differs from declaration");
+        continue;
+      }
+      if (row.status === "error") continue;
+      const e = row.evidence;
+      if (!object(e)) continue;
+      const passed =
+        check.type === "http"
+          ? e.httpStatus === check.status &&
+            (!check.json || e.jsonMatched === true)
+          : e.count >= check.minCount && e.count <= check.maxCount;
+      if (
+        row.status !== (passed ? "pass" : "failed") ||
+        (check.type === "http" &&
+          Boolean(check.json) !== (e.jsonMatched !== undefined))
+      )
+        errors.push("Evidence outcome conflicts with executed expectation");
+    }
+  }
+  if (
+    value?.status === "tested-pass" &&
+    (!value.checks?.length ||
+      value.checks.some((c) => c?.status !== "pass") ||
+      value.cleanup?.stopped !== true ||
+      value.cleanup?.removed !== true ||
+      value.cleanup?.errors?.length ||
+      value.error !== undefined)
+  )
+    errors.push("Pass conflicts with checks or cleanup");
+  if (
+    value?.status === "tested-failed" &&
+    (!value.checks?.some((c) => c?.status === "failed") ||
+      value.checks.some((c) => c?.status === "error") ||
+      value.cleanup?.stopped !== true ||
+      value.cleanup?.removed !== true ||
+      value.error !== undefined)
+  )
+    errors.push("Failed measurement conflicts with checks/cleanup");
+  if (value?.status === "error" && !bounded(value.error, 1024))
+    errors.push("Missing run error");
+  if (errors.length) return { valid: false, errors };
+  const staleReasons = [];
+  if (
+    !expectedIdentity.artifact ||
+    !["name", "version", "sha256"].every(
+      (k) => typeof expectedIdentity.artifact[k] === "string",
+    )
+  )
+    staleReasons.push("Current artifact identity unavailable");
+  else
+    for (const key of ["name", "version", "sha256"])
+      if (id.artifact[key] !== expectedIdentity.artifact[key])
+        staleReasons.push("Artifact " + key + " changed");
+  if (!expectedIdentity.dshVersion)
+    staleReasons.push("Current DSH version unavailable");
+  else if (id.dshVersion !== expectedIdentity.dshVersion)
+    staleReasons.push("DSH version changed");
+  if (!expectedIdentity.manifestSha256)
+    staleReasons.push("Current declaration identity unavailable");
+  else if (id.manifestSha256 !== expectedIdentity.manifestSha256)
+    staleReasons.push("Declaration changed");
+  return {
+    valid: true,
+    value,
+    current: staleReasons.length === 0,
+    staleReasons,
+  };
+}
+
+/** SHA256 identity rule: UTF-8 of JSON with recursively sorted object keys and preserved array order, no whitespace. */
+export function canonicalFunctionalManifest(value) {
+  const validation = validateFunctionalManifest(value);
+  if (!validation.valid) throw Error(validation.errors.join("; "));
+  const ordered = (v) =>
+    Array.isArray(v)
+      ? v.map(ordered)
+      : object(v)
+        ? Object.fromEntries(
+            Object.keys(v)
+              .sort()
+              .map((k) => [k, ordered(v[k])]),
+          )
+        : v;
+  return JSON.stringify(ordered(value));
+}

package/kernel/lib/issue-report.mjs

@@ -0,0 +1,217 @@
+/** Shared CLI/panel share view. Never serialize raw inputs, logs, evidence or baseline. */
+import { TOOL_VERSION } from "./version.mjs";
+import { nextSteps } from "./finding-guidance.mjs";
+
+function safe(value) {
+  const raw = String(value ?? "未提供");
+  // Hide the whole field: token-by-token replacement leaks the tail of a path
+  // containing spaces and can turn a multi-line log into apparently safe prose.
+  if (
+    /[\x00-\x1f\x7f\u202a-\u202e\u2066-\u2069]/.test(raw) ||
+    /(?:[a-z]:[\\/]|\\\\|~[\\/]|(?:^|[\s("'`=：:，；])\/|\.\.[\\/]|\/[^\s/]+\/)/i.test(
+      raw,
+    ) ||
+    /(?:https?|file):|Bearer\s|(?:token|password|passwd|secret|api[_-]?key|authorization)\s*[:=]|(?:sk-|ghp_|github_pat_|npm_)[a-z0-9_]+/i.test(
+      raw,
+    )
+  )
+    return "［说明包含路径、链接、凭据或控制字符，已隐藏；请在本机查看］";
+  return raw
+    .replace(
+      /[&<>@]/g,
+      (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "@": "&#64;" })[c],
+    )
+    .replace(/[\\`*_{}\[\]()#+.!|~-]/g, "\\$&");
+}
+
+// Keep public package identifiers and relative source positions useful. Invalid
+// metadata is omitted wholesale rather than partially echoing arbitrary input.
+function identity(value) {
+  return typeof value === "string" &&
+    /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(value)
+    ? "`" + value + "`"
+    : "未提供或已隐藏";
+}
+function version(value) {
+  return typeof value === "string" &&
+    /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?(?:\+[a-z0-9.-]+)?$/i.test(value)
+    ? "`" + value + "`"
+    : "未知或已隐藏";
+}
+function location(value) {
+  if (!value) return "源码位置未提供（声明或 loader 事实可无位置）";
+  const file = value.file;
+  if (
+    typeof file !== "string" ||
+    !/^(?:[a-z0-9_@.-]+\/)*[a-z0-9_@.-]+$/i.test(file) ||
+    file.split("/").some((p) => p === ".." || p === ".") ||
+    !Number.isSafeInteger(value.line) ||
+    value.line < 1
+  )
+    return "源码位置已隐藏（非安全的包内相对路径）";
+  return "`" + file + ":" + value.line + "`";
+}
+
+/** Render the canonical JSON body, without changing its verdict or exit code. */
+export function renderIssueReport(body, options = {}) {
+  const lines = [
+    "# DSH 插件兼容性故障报告",
+    "",
+    "- 工具版本: " + version(body.toolVersion ?? TOOL_VERSION),
+    "- DSH 目标版本: " + version(body.dshVersion),
+    "- 退出码: " + (body.ok ? body.exitCode : 3),
+    "",
+    "绝对路径、原始参数、日志、源码片段、原始探针/evidence 与基线均不导出；保留插件名、包内相对位置及分析说明。常见凭据会隐藏，但不能保证任意业务文本无敏感信息；请预览后再分享。",
+    "",
+  ];
+  if (!body.ok) {
+    lines.push(
+      "## 工具无法判定",
+      "",
+      "本次未产生可信插件结论。原始错误已省略，避免泄露路径、配置或日志；请在本机移除 --issue-report 排查。用法错误可先运行 --help。",
+      "",
+    );
+  } else {
+    const o = body.observation;
+    if (body.catalog) {
+      const c = body.catalog;
+      lines.push(
+        "- 参考目录: " +
+          version(c.referenceVersion) +
+          "；SHA-256: " +
+          (/^[a-f0-9]{64}$/.test(c.sha256) ? c.sha256 : "未提供"),
+        "- 目录认证范围: " +
+          (c.certifiedVersions?.map(version).join("、") || "无") +
+          "；仅内置目录与精确版本集成，不代表业务验收或运行时观测。",
+        ...(c.verified
+          ? []
+          : [
+              "- 目录警告: 目标版本或自定义目录未认证；当前结果不能证明目标版本已验收，请在实际宿主复核。",
+            ]),
+      );
+    } else lines.push("- API目录身份未提供，版本范围未认证；请重新体检。");
+    lines.push(
+      "- 证据模式: " + o.mode,
+      "- 观测绑定: " + o.bound + "；可用: " + o.usable,
+      "- 观测 DSH 版本: " + version(o.dshVersion),
+      "- 扫描完整: " +
+        body.extraction.scanComplete +
+        "；诊断数: " +
+        body.extraction.diagnostics.length,
+      "- 汇总: " +
+        ["ok", "partial", "broken", "unknown", "limited", "vacuousOk"]
+          .map((k) => k + "=" + body.summary[k])
+          .join(", "),
+      "",
+    );
+    for (const note of o.notes) lines.push("- 观测限制: " + safe(note));
+    for (const [name, p] of Object.entries(body.plugins)) {
+      lines.push(
+        "",
+        "## 插件 " + identity(name),
+        "",
+        "- 插件版本: " + version(p.version),
+        "- 结论: " + p.verdict + "；vacuous=" + p.vacuous,
+        "- coverage=" +
+          p.coverage.status +
+          "；verifiedCalls=" +
+          p.coverage.verifiedCalls,
+      );
+      for (const note of p.coverage.limitations)
+        lines.push("- 覆盖限制: " + safe(note));
+      if (!p.findings.length)
+        lines.push("- 未报告发现；不等于业务功能通过验收。");
+      for (const f of p.findings) {
+        lines.push(
+          "",
+          "- 发现: " +
+            safe(f.category) +
+            "；API: " +
+            identity([f.service, f.method].filter(Boolean).join(".")),
+          "  - severity=" +
+            f.severity +
+            "；certainty=" +
+            f.certainty +
+            "；impactBasis=" +
+            f.impactBasis,
+          "  - 位置: " + location(f.location),
+          "  - 影响: " + safe(f.impact),
+          "  - 依据: " + safe(f.basis),
+        );
+        for (const step of nextSteps(f))
+          lines.push("  - 下一步: " + safe(step));
+      }
+    }
+  }
+  const flags = [
+    "--nm <profile-or-node_modules>",
+    "--no-baseline",
+    "--issue-report",
+  ];
+  const runtimeEvidence =
+    body.observation?.usable === true ||
+    body.observation?.mode === "runtime" ||
+    body.hasRuntimeSurface === true ||
+    body.inputs?.hasRuntimeSurface === true;
+  const fileProbe =
+    options.probe || (body.inputs?.probe && !body.inputs?.probeBoot);
+  const explicitBoot =
+    !fileProbe && (options.probeBoot || body.inputs?.probeBoot);
+  const loaderFindings = Object.values(body.plugins || {}).some((plugin) =>
+    (plugin.findings || []).some(
+      (finding) => finding.category === "host-entry-inactive",
+    ),
+  );
+  if (fileProbe || (runtimeEvidence && !explicitBoot))
+    flags.push("--probe <probe-report.json>");
+  else if (explicitBoot) flags.push("--probe-boot");
+  if (options.dshVersion || body.dshVersion)
+    flags.push("--dsh-version <dsh-version>");
+  if (options.rules || body.inputs?.rules) flags.push("--rules <rules.json>");
+  if (options.catalog || body.inputs?.catalog)
+    flags.push("--catalog <catalog.json>");
+  lines.push("", "## 复核（在仓库根目录，先替换占位符）", "");
+  if (runtimeEvidence)
+    lines.push(
+      "本报告含运行时观测；仅静态扫描可能给出不同结论，不能复现这些运行时发现。",
+      "",
+    );
+  if (loaderFindings)
+    lines.push(
+      "本报告包含 loader 状态事实。FAILED/PENDING 必须回到原来的同一宿主刷新报告并核对条目身份、状态和时间；静态扫描或文件 probe 不能复现这些状态。",
+      "",
+    );
+  if (explicitBoot)
+    lines.push(
+      "原 CLI 显式请求了 --probe-boot；下面命令会安装依赖、启动并执行目标插件，临时 profile 不是 OS 沙箱。这是一次新宿主检查，不能复现原宿主的 loader 或业务事实。原有超时/留存参数未复制，必要时在本机补回；导出文本本身不启动宿主。",
+      "",
+    );
+  else if (fileProbe || runtimeEvidence)
+    lines.push(
+      "下面命令仅适用于已另行取得同一 profile、DSH 版本且采样时间有效的合格 probe 文件后；本报告未导出观测，也不会自动创建 probe 或启动宿主。文件 probe 只能补充其明确记录的服务结构，不能代替原宿主状态或业务验收。",
+      "",
+    );
+  else
+    lines.push(
+      "下面命令只用于复核文件、声明与目录；CLI 仍可能读取目标旁置的 probe-report.json，运行后须核对输出中的实际证据来源。",
+      "",
+    );
+  lines.push(
+    "```sh",
+    "node bin/compat-check.mjs " + flags.join(" "),
+    "```",
+    "",
+    "使用相同工具版本/源码提交、目标插件制品、规则与 API 目录；规则/目录占位符须替换为本报告对应的输入，自定义输入需自行保存并核对身份。命令不保证复现原观测时刻或相同结论，也不补齐未导出的观测。",
+    "",
+    "## 判读限制",
+    "",
+    "certain 表示当前证据足以支持该条发现，可来自明确静态事实或合格运行时观测；suspected 表示当前证据不足以确定该条发现。impactBasis=measured/inferred 分别表示影响有对应实测依据/影响由证据推断，确定发现不等于影响已实测。vacuous 表示本轮未发现冲突但没有已验证调用，仍可能存在服务依赖或客户端功能。catalogue 不是运行时观测，未观测不等于缺失；limited/vacuous 或客户端未验证均不能省略。声明放行、激活、调用核验或覆盖完整不证明业务成功。",
+    "",
+    "普通体检按目标版本选择已知目录：0.2.1-rc.2及以后用rc.2目录，其余/未知用旧目录；显式--catalog优先，未来版本未经认证。声明从0.2.1-rc.1起优先engines.dsh，否则回退官方peer；旧目标保留旧规则。精确豁免只表示声明获准，不证明业务成功；请以实际宿主复核。",
+    "",
+    "下一步是核实建议；本工具不会自动安装、升级或修改配置与源码。",
+    "",
+    "本报告只生成文本，不自动上传、创建 issue 或回复他人。",
+  );
+  return lines.join("\n");
+}

package/kernel/lib/observation.mjs

@@ -2,6 +2,7 @@ import path from "node:path";
 
 const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const samePath = (a, b) => path.resolve(a) === path.resolve(b);
+export const MAX_OBSERVATION_FUTURE_SKEW_MS = 5 * 60 * 1000;
 
 /** Legacy reports authorize only their explicit keys, never missing keys. */
 export function normalizeObservation(surface, target = {}) {
@@ -22,15 +23,24 @@ export function normalizeObservation(surface, target = {}) {
     notes.push("探针的 profile/DSH 版本与体检对象不匹配，忽略运行时证据");
     return { root, notes, bound, usable: false };
   }
-  if (
-    bound &&
-    target.maxAgeMs &&
-    (!surface.probedAt ||
-      !Number.isFinite(Date.parse(surface.probedAt)) ||
-      Date.now() - Date.parse(surface.probedAt) > target.maxAgeMs)
-  ) {
-    notes.push("探针采样时间缺失或已过期，忽略运行时证据");
-    return { root, notes, bound, usable: false };
+  if (bound) {
+    const sampledAt =
+      typeof surface.probedAt === "string" ? Date.parse(surface.probedAt) : NaN;
+    if (!Number.isFinite(sampledAt)) {
+      notes.push("探针采样时间缺失或无效，忽略运行时证据");
+      return { root, notes, bound, usable: false };
+    }
+    const ageMs = Date.now() - sampledAt;
+    if (ageMs < -MAX_OBSERVATION_FUTURE_SKEW_MS) {
+      notes.push(
+        "探针采样时间超出允许的未来时钟偏差（5 分钟），忽略运行时证据",
+      );
+      return { root, notes, bound, usable: false };
+    }
+    if (target.maxAgeMs && ageMs > target.maxAgeMs) {
+      notes.push("探针采样时间已过期，忽略运行时证据");
+      return { root, notes, bound, usable: false };
+    }
   }
   if (!bound)
     notes.push(