dsh-plugin-compat-check 0.1.2 → 0.1.4

package/kernel/lib/owned-process.mjs

@@ -0,0 +1,287 @@
+/** Owned process-group lifecycle. No argv, environment or global process listing
+ * is retained; ps is a bounded failure diagnostic, filtered to this group. */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { privateDiagnostic } from "../plugin/lib/host-resources.js";
+export function failureDiagnostic(error) {
+  return error?.diagnostics?.length
+    ? error.diagnostics
+    : error?.diagnostic
+      ? [error.diagnostic]
+      : [];
+}
+export function publishDiagnostic(diagnostic, privateDetails) {
+  const dir = process.env.DSC_EXECUTION_DIAGNOSTICS;
+  if (dir) {
+    const redact = (value) =>
+      String(value)
+        .slice(-8192)
+        .replace(/https?:\/\/[^\s"'<>]+/gi, "<url>")
+        .replace(
+          /(authorization\s*[:=]\s*)(?:Bearer\s+)?[^\s,;]+/gi,
+          "$1[redacted]",
+        )
+        .replace(
+          /((?:api[_-]?key|access[_-]?token|password)\s*[:=]\s*)[^\s,;]+/gi,
+          "$1[redacted]",
+        );
+    const data = {
+      ...diagnostic,
+      ...(privateDetails
+        ? {
+            privateDetails: Object.fromEntries(
+              Object.entries(privateDetails).map(([key, value]) => [
+                key,
+                redact(value),
+              ]),
+            ),
+          }
+        : {}),
+    };
+    const written = privateDiagnostic(
+      path.join(dir, `${diagnostic.component}-${randomUUID()}.json`),
+      data,
+    );
+    diagnostic.persistence = { requested: true, written };
+  }
+  return diagnostic;
+}
+export function groupSnapshot(pgid) {
+  if (process.platform === "win32")
+    return { available: false, reason: "unsupported-platform" };
+  const args =
+    process.platform === "darwin"
+      ? ["-g", String(pgid), "-o", "pid=,ppid=,pgid=,uid=,stat="]
+      : ["-axo", "pid=,ppid=,pgid=,uid=,stat="];
+  const r = spawnSync("/bin/ps", args, {
+    encoding: "utf8",
+    timeout: 1000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  if (
+    process.platform === "darwin" &&
+    r.status === 1 &&
+    !r.error &&
+    !r.stdout.trim() &&
+    !r.stderr.trim()
+  )
+    return { available: true, members: [], truncated: false };
+  if (r.status !== 0 || r.error)
+    return { available: false, reason: r.error?.code || "ps-failed" };
+  const lines = r.stdout.trim().split("\n");
+  const members = [];
+  for (const line of lines) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+    if (!m) return { available: false, reason: "invalid-ps-output" };
+    if (Number(m[3]) === pgid)
+      members.push({
+        pid: Number(m[1]),
+        ppid: Number(m[2]),
+        pgid: Number(m[3]),
+        uid: Number(m[4]),
+        state: m[5],
+      });
+  }
+  return {
+    available: true,
+    members: members.slice(0, 64),
+    truncated: members.length > 64,
+  };
+}
+const stopping = new WeakMap();
+export function stopOwnedChild(child) {
+  if (!child?.pid)
+    return Promise.resolve({ stopped: true, status: "not-started" });
+  if (stopping.has(child)) return stopping.get(child);
+  const pending = (async () => {
+    if (!Number.isSafeInteger(child.pid) || child.pid <= 1)
+      throw new Error("Invalid owned child pid");
+    const done = () => child.exitCode !== null || child.signalCode !== null;
+    let exitListener;
+    const exited = done()
+      ? Promise.resolve()
+      : new Promise((resolve) => {
+          exitListener = resolve;
+          child.once("exit", resolve);
+        });
+    const signals = [];
+    let phase = "SIGTERM";
+    const state = () => ({
+      schemaVersion: 1,
+      kind: "plugin-compat-check/execution-diagnostic",
+      component: "owned-process",
+      phase,
+      pid: child.pid,
+      pgid: process.platform === "win32" ? null : child.pid,
+      parentPid: process.pid,
+      uid: process.getuid?.() ?? null,
+      leaderExited: done(),
+      exitCode: child.exitCode,
+      signalCode: child.signalCode,
+      signals,
+    });
+    const waitExit = async () => {
+      let timer;
+      try {
+        await Promise.race([
+          exited,
+          new Promise((resolve) => {
+            timer = setTimeout(resolve, 2000);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    const signal = async (sig) => {
+      phase = sig;
+      try {
+        if (process.platform !== "win32") process.kill(-child.pid, sig);
+        else if (!done()) child.kill(sig);
+        signals.push({ signal: sig, result: "sent" });
+      } catch (error) {
+        signals.push({ signal: sig, result: error.code || "error" });
+        if (error.code === "ESRCH") return;
+        let group = groupSnapshot(child.pid);
+        if (
+          process.platform === "darwin" &&
+          error.code === "EPERM" &&
+          !done() &&
+          group.available &&
+          !group.truncated &&
+          group.members.every((m) => m.uid === process.getuid?.()) &&
+          (sig === "SIGKILL" ||
+            group.members.every(
+              (m) => m.state.startsWith("Z") || m.state.includes("E"),
+            ))
+        ) {
+          await waitExit();
+          group = groupSnapshot(child.pid);
+        }
+        // Darwin filters zombies out of killpg and can return EPERM when only
+        // zombies remain. Never infer this from EPERM alone or a failed ps.
+        const zombieOnly =
+          process.platform === "darwin" &&
+          error.code === "EPERM" &&
+          group.available &&
+          (done() ||
+            group.members.some(
+              (m) => m.pid === child.pid && m.state.startsWith("Z"),
+            )) &&
+          !group.truncated &&
+          (group.members.length > 0 || done()) &&
+          group.members.every(
+            (m) => m.uid === process.getuid?.() && m.state.startsWith("Z"),
+          );
+        if (zombieOnly) {
+          signals[signals.length - 1].result = group.members.length
+            ? "verified-zombie-only"
+            : "verified-exited-group";
+          signals[signals.length - 1].group = group;
+          return;
+        }
+        const failure = new Error(
+          `Owned process cleanup failed: ${sig} ${error.code || "error"}`,
+          { cause: error },
+        );
+        failure.code = "OWNED_PROCESS_CLEANUP_FAILED";
+        failure.diagnostic = publishDiagnostic({
+          ...state(),
+          code: failure.code,
+          signalError: {
+            code: error.code || null,
+            syscall: error.syscall || null,
+            stack: String(error.stack || "")
+              .split("\n")
+              .slice(1, 10)
+              .map((line) =>
+                line
+                  .replace(/\((?:file:\/\/)?\/.*\/([^/]+:\d+:\d+)\)/g, "($1)")
+                  .replace(/at (?:file:\/\/)?\/.*\/([^/]+:\d+:\d+)/g, "at $1"),
+              ),
+          },
+          group,
+        });
+        throw failure;
+      }
+    };
+    try {
+      await signal("SIGTERM");
+      await new Promise((r) => setTimeout(r, 100));
+      await signal("SIGKILL");
+      phase = "exit";
+      let timer;
+      try {
+        await Promise.race([
+          exited,
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () =>
+                reject(
+                  Object.assign(
+                    new Error("Owned process did not exit after SIGKILL"),
+                    {
+                      code: "OWNED_PROCESS_EXIT_TIMEOUT",
+                      diagnostic: publishDiagnostic({
+                        ...state(),
+                        code: "OWNED_PROCESS_EXIT_TIMEOUT",
+                        group: groupSnapshot(child.pid),
+                      }),
+                    },
+                  ),
+                ),
+              2000,
+            );
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+      return {
+        stopped: true,
+        status: signals.some((s) => s.result === "verified-zombie-only")
+          ? "zombie-only"
+          : "stopped",
+        ...state(),
+      };
+    } catch (error) {
+      child.unref?.();
+      throw error;
+    } finally {
+      if (exitListener) child.off("exit", exitListener);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    }
+  })();
+  stopping.set(child, pending);
+  return pending;
+}
+
+/** Attempt each owned cleanup even when another resource fails. */
+export async function cleanupOwned(tasks) {
+  const settled = await Promise.allSettled(
+    tasks.map((task) => Promise.resolve().then(task)),
+  );
+  const failures = settled
+    .filter((r) => r.status === "rejected")
+    .map((r) => r.reason);
+  if (failures.length) {
+    const error = new AggregateError(failures, "Owned resource cleanup failed");
+    error.code = "OWNED_RESOURCE_CLEANUP_FAILED";
+    error.diagnostics = failures.flatMap(failureDiagnostic);
+    throw error;
+  }
+}
+export function combineFailure(primary, cleanup) {
+  if (!primary) return cleanup;
+  const error = new Error(primary.message + "; " + cleanup.message, {
+    cause: primary,
+  });
+  error.code = primary.code || "EXECUTION_FAILED";
+  error.diagnostics = [
+    ...failureDiagnostic(primary),
+    ...failureDiagnostic(cleanup),
+  ];
+  return error;
+}

package/kernel/lib/profile-compatibility.mjs

@@ -0,0 +1,69 @@
+/** Read independent profile grants without importing or changing target plugins. */
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+
+const exact = (value) => {
+  const parsed = typeof value === "string" ? semver.parse(value) : null;
+  return (
+    parsed !== null &&
+    value ===
+      parsed.version + (parsed.build.length ? "+" + parsed.build.join(".") : "")
+  );
+};
+export function readProfileCompatibility(nodeModules) {
+  const file = path.join(path.dirname(nodeModules), "compatibility.json");
+  const unavailable = (note) => ({
+    file,
+    exemptions: undefined,
+    notes: [note],
+  });
+  let fd;
+  try {
+    fd = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0),
+    );
+    if (!fs.fstatSync(fd).isFile())
+      return unavailable("compatibility.json 不是普通文件，精确豁免未观测");
+    const buffer = Buffer.alloc(65537),
+      length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    if (length > 65536)
+      return unavailable(
+        "compatibility.json 超过64KiB读取预算，精确豁免未观测",
+      );
+    const value = JSON.parse(buffer.subarray(0, length).toString("utf8"));
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+      return unavailable(
+        "compatibility.json 必须为精确版本豁免对象，记录未采用",
+      );
+    const exemptions = Object.create(null),
+      notes = [];
+    for (const [key, versions] of Object.entries(value)) {
+      const i = key.lastIndexOf("@");
+      if (
+        i <= 0 ||
+        !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(
+          key.slice(0, i),
+        ) ||
+        !exact(key.slice(i + 1)) ||
+        !Array.isArray(versions) ||
+        !versions.every(exact)
+      ) {
+        notes.push("compatibility.json 含无效的精确版本豁免记录，已忽略");
+        continue;
+      }
+      Object.defineProperty(exemptions, key, {
+        value: versions,
+        enumerable: true,
+      });
+    }
+    return { file, exemptions, notes };
+  } catch (error) {
+    return error.code === "ENOENT"
+      ? { file, exemptions: {}, notes: [] }
+      : unavailable("compatibility.json 不可读或JSON无效，精确豁免未观测");
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}

package/kernel/lib/verdict.mjs

@@ -99,8 +99,8 @@ export function methodRule(rules, service, method, side = "host") {
     return null;
   return rule;
 }
-export function declarationOf(p, version) {
-  return declaredSupport(p, version);
+export function declarationOf(p, version, options) {
+  return declaredSupport(p, version, options);
 }
 export function buildVerdicts({
   report,
@@ -110,6 +110,8 @@ export function buildVerdicts({
   dshVersion = null,
   entryStates = [],
   observationTarget = {},
+  compatibilityExemptions,
+  compatibilityNotes = [],
 }) {
   const observation = normalizeObservation(hostSurface, {
     dshVersion,
@@ -146,6 +148,7 @@ export function buildVerdicts({
     const resolved = Object.create(null);
     const limitations = [
       ...observation.notes,
+      ...compatibilityNotes,
       ...(p.diagnostics || []).map((d) => `${d.kind}: ${d.file ?? ""}`),
     ];
     let verified = 0;
@@ -331,7 +334,14 @@ export function buildVerdicts({
             method: null,
             location: location(hostDeps[0] || hostSites[0]),
             severity: "degraded",
-            impact: "该依赖没有足够运行时或目录证据，不能确认可用或缺失",
+            evidence: {
+              status: observed.status,
+              hardInject: hard,
+              inHostCatalog: false,
+            },
+            impact: hard
+              ? "插件必需inject的激活前提尚未确认；需同profile服务观测，不能推断已缺失或已挂起"
+              : "该依赖没有足够运行时或目录证据，不能确认可用或缺失",
             basis: "未采样不等于不存在；仅列出待核实依赖",
             ruleSource: "default",
             ruleRef: null,
@@ -422,14 +432,32 @@ export function buildVerdicts({
           (s) => methods.includes(s.method) || protectedCall(s),
         ).length;
     }
-    const declaration = declarationOf(p, dshVersion);
+    const declaration = declarationOf(p, dshVersion, {
+      exemptions: compatibilityExemptions,
+    });
     const rejectedPeers =
+      declaration?.rejected ??
       declaration?.raw?.peers?.filter(
         (r) => r.source === "peerDependencies" && !r.compatible,
-      ) || [];
-    if (rejectedPeers.length) {
+      ) ??
+      [];
+    const modern = declaration?.policy === "engines-first";
+    if (modern && rejectedPeers.length && declaration.exempted === true)
+      limitations.push(
+        "声明范围未满足，但存在此插件与目标DSH的精确版本豁免；加载许可不证明API或业务兼容",
+      );
+    if (
+      (rejectedPeers.length || declaration?.invalid) &&
+      declaration?.exempted !== true
+    ) {
       limitations.push(
-        "官方 peer 范围不匹配；未读取 exact-version 豁免，不能断言实际加载失败",
+        modern
+          ? declaration.invalid
+            ? declaration.invalid
+            : "声明范围不匹配；精确版本豁免" +
+              (declaration.exempted === null ? "未观测" : "未授予") +
+              "，未实测加载结果"
+          : "官方 peer 范围不匹配；未读取 exact-version 豁免，不能断言实际加载失败",
       );
       add({
         category: CATEGORY.DECLARED_INCOMPATIBLE,
@@ -439,18 +467,31 @@ export function buildVerdicts({
         method: null,
         location: null,
         severity: "degraded",
-        impact:
-          "官方 peer 声明不支持当前 DSH；请确认版本范围与精确版本豁免，API 存在不等于完整兼容",
-        basis: rejectedPeers
-          .map((r) => `${r.name}: ${r.range}，当前 ${dshVersion}`)
-          .join("; "),
+        impact: modern
+          ? "按目标DSH声明规则未获放行；须核对精确豁免及实际加载，API存在不等于完整兼容"
+          : "官方 peer 声明不支持当前 DSH；请确认版本范围与精确版本豁免，API 存在不等于完整兼容",
+        basis:
+          declaration.invalid ||
+          rejectedPeers
+            .map((r) => `${r.name}: ${r.range}，当前 ${dshVersion}`)
+            .join("; "),
         evidence: {
           runtimeVersion: dshVersion,
           peers: rejectedPeers,
-          exemption: "unobserved",
+          exemption: modern
+            ? declaration.exempted === null
+              ? "unobserved"
+              : "not-granted"
+            : "unobserved",
+          policy: declaration.policy ?? "legacy-peers",
+          invalid: declaration.invalid ?? null,
         },
         ruleSource: "declaration",
-        ruleRef: "package.peerDependencies",
+        ruleRef: declaration.invalid
+          ? "package.declaration"
+          : rejectedPeers.some((r) => r.source === "engines.dsh")
+            ? "package.engines.dsh"
+            : "package.peerDependencies",
       });
     }
     if (declaration?.claimsCompatible && findings.length) {

package/kernel/lib/version.mjs

@@ -29,7 +29,7 @@
  */
 
 /** 语义化版本。改动它会同时影响三个入口的 `--version` 与报告 JSON 的 `toolVersion`。 */
-export const TOOL_VERSION = '0.1.2';
+export const TOOL_VERSION = '0.1.4';
 
 /** 人类可读的一行，给 `--version` 用 */
 export function versionLine() {

package/kernel/rules/README.md

@@ -1,18 +1,18 @@
 # 严重度规则表与维护
 
-适用于0.1.2，判定算法与0.1.1一致。当前契约见 [Plan现行契约](../docs/Plan.md)，验证见 [自动统计](../docs/current-state.json)。本页后半保留2026-10-11旧提取器的规则依据；其中表格不是当前覆盖率，也不是当前运行时真值。
+适用于0.1.4；公开版本以registry和Plan发布记录为准。当前契约见 [Plan](../docs/Plan.md)，验证见 [自动统计](../docs/current-state.json)。后半保留2026-10-11旧提取器的依据，历史表不是当前覆盖率或运行时真值。
 
 ## 文件与运行时消费者
 
 | 文件 | 用途 |
 |---|---|
 | severity.json | 方法严重度/影响文案；引擎读取services下的方法规则，并与代码内默认档合用 |
-| dsh-api-catalog.json | 指定DSH版本生成的宿主/客户端契约目录；不证明当次运行时提供某方法 |
+| dsh-api-catalog.json / dsh-api-catalog-0.2.1-rc.2.json | 原0.2.0-rc.2（host91/client8）与新rc.2（host98/client8）契约快照；DSH≥0.2.1-rc.2选新目录，其余/未知选旧目录，CLI显式覆盖优先；未来版本未认证 |
 | usage-inventory.json | 带日期/版本/profile及完整性标记的AST库存快照；由coverage显式刷新，不保证与后续提取器重扫同数 |
 
 严重度由 `lib/verdict.mjs` 的确定性逻辑、缺失证据、方法规则及默认档共同决定，不由LLM决定。方法规则的severity/impact参与判定与输出，layer控制端别：方法自身优先、服务layer回退。summary/basis/evidence/knownGoneIn/needsReview等用于解释与维护；knownExtractionArtifacts是历史反例登记，不是自动过滤黑名单。
 
-0.2.1-rc.1宿主改为优先按engines.dsh判断；本版尚未同步该逻辑，已复现声明误报与漏报，规则/API目录也未更新为新版。新版接入验证不代表这些判定已适配，实施顺序见Plan后续。
+0.1.3按DSH目标分流声明：从0.2.1-rc.1起自有engines.dsh优先，缺失才回退全部官方peer；旧目标保留旧行为。非法/空范围、预发布和peer workspace别名均有回归；engines中的workspace不获放行。独立compatibility.json仅按插件/运行时精确版本豁免，非法字段不能靠豁免绕过；无效记录忽略并保留覆盖限制。
 
 ## 当前证据与严重度
 
@@ -21,15 +21,21 @@
 | 可映射loader条目FAILED/PENDING | fatal，影响依据measured；禁用、LOADING、无法映射不冒充同一事实 |
 | 宿主硬依赖且明确absent | 可判fatal；仅catalog缺项不冒充运行时缺失 |
 | 非硬依赖服务明确absent，或有足够方法证据 | 按规则/默认档给feature-dead或degraded；用户影响通常是inferred |
-| 官方peer范围冲突 | declared-incompatible，degraded及推断影响；不是实测加载失败；当前内核沿用0.2.0-rc.2，将engines.dsh作建议处理 |
+| 官方声明冲突或非法字段 | declared-incompatible，degraded及推断影响；不冒充实测加载失败；有效精确豁免可消除范围冲突，但保留限制且不证明业务成功 |
 | 未采样、读取失败、访问器未知、源码不完整 | 保留覆盖限制；不以省略键认定不存在 |
 
 方法规则中的degraded应有具体降级/回退依据；peer声明冲突的degraded是引擎针对声明风险的独立默认，不代表观察到回退。方法缺失但没有语义规则时会明确“影响面未知”。声明provide只是候选提供方，不证明已激活，不能遮住完整的present方法观测。
 
 宿主、客户端及shared调用点必须分开。客户端方法不能拿宿主probe判缺失；同名服务也不保证同一语义。对源码归属不确定的Context/别名保留suspected。certainty与impactBasis分别表达证据强度和影响是否实测。
 
+0.1.4补强：必需inject未观测保持degraded/suspected，仅提示激活前提未确认；同profile明确absent才推断激活障碍，optional/scoped依赖与方法缺失分别处理，不借业务答案调严重度。`--observe-services`另记服务预测身份/摘要，不覆盖静态FN，也不改变生产certainty或impactBasis。
+
+仓库独立业务队列将手审的功能调用区间内API风险与真实市场操作、侧栏HTTP/编辑器及有限模型回复结果对照，保持业务、loader标签及预测隔离；不把整个插件的其它发现挪给本功能。正常/自然失败与HTTP503/控件缺失故障组分别计分，限定样本不能改变生产报告中的certainty或impactBasis，也不是新增严重度规则的充分证据。复现见[Plan](../docs/Plan.md#52-日常检查与真实集成)。
+
 ## 如何更新
 
+ASAR读取器已修正数据起点为8+headerSize，并校验头长、边界、完整读取、UTF-8/JSON及归档SHA256。2026-10-18与Electron原生ASAR读取逐字节及首尾交叉校验后生成独立rc.2目录，旧目录未改。新host增加8项、移除invariants；subagents移除start/startContinuable/drainContinuableChildren/drainContinuableDescendants，增加startActivation/drainChildren/drainDescendants/waitForChildren；其它方法差异和源摘要见current-state。client方法集合未变。旧方法规则保留其原调用语义；不把新方法当同义重命名，也不只凭目录变化新增严重度，未知影响继续回退。
+
 先读调用点和目标版本的真实描述符/官方源码，再修改规则，添加行为回归并审查快照差异。原needsReview已在2026-10-15逐条复核，决定与证据保留于severity.json的needsReview.reviewed/evidence及 [Plan](../docs/Plan.md)。
 
 `tools/coverage.mjs` 从AST调用点按host/client/shared分端计数，规则命中与默认影响、类别发现分列。**knownExtractionArtifacts只保留历史反例，不过滤现在的真实调用**；纯客户端规则不用于宿主同名方法。probe须为现代格式并绑定本目标/版本/时间，不能借别的profile的面。写库存要求显式或观测到的合法semver版本，非法版本退出3且不覆盖旧文件。
@@ -183,7 +189,7 @@ node tools/coverage.mjs --probe <报告> --write             # 顺带刷新 rule
 
 ### F. 提取器已正确处理，无需规则（1 个）
 
-`betterSidebar` —— 它是插件自己 `ctx.provide()` 出来的服务，**提取器已正确记入 `providedServices`**（同类的还有 dshmarket 的 `market`），因此不会产生假缺口。`pet` / `agentTeams` / `companionQq` / `betterLocale` 这些**没有**被 `ctx.provide()` 捕获的（见 `docs/Plan.md` §2.1 的提供方证据约束），就落进了上面 A 组。
+`betterSidebar` —— 它是插件自己 `ctx.provide()` 出来的服务，**提取器已正确记入 `providedServices`**（同类的还有 dshmarket 的 `market`），因此不会产生假缺口。`pet` / `agentTeams` / `companionQq` / `betterLocale` 这些**没有**被 `ctx.provide()` 捕获的（见 `docs/Plan.md` §2.2 的提供方证据约束），就落进了上面 A 组。
 
 ## 历史补充：已知提取误报