@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/src/runtime/provision.js

@@ -0,0 +1,237 @@
+// 运行时取件编排：三档来源依次尝试（issue #131 / PR-C / PR-C 追加下载档）
+//
+// 为什么单独一层：面板按钮需要一段「能被单测覆盖、又不必把绝对路径交给免鉴权端点」的
+// 逻辑。这里只做三件事——推源、收编、给结论；路由那侧只管鉴权与搬运。
+//
+// 为什么源不让用户输入：既有用户的 transformers 就装在 <profile>/node_modules 里，
+// 而插件自身也在那儿（<profile>/node_modules/@modusensus/dsh-mneme/）。所以从插件
+// 自己的位置往上三级就能推出源目录，面板不必传参，也不把「从任意目录收编」变成
+// 一个对外能力。
+//
+// 为什么 ok 要同时看结构和闭包缺口：describePayload 只点三个必需包，不看闭包计划里的
+// 必需依赖缺口。只认结构的话，「缺传递依赖、入口一 import 就炸」的收编会被面板显示成
+// 成功——这与 CLI 的退出码用的是同一条判据，两边必须一致。
+//
+// 同步实现：adoptRuntime 全是同步 fs 调用。收编 3203 个文件实测约 1–3 秒（同卷硬链接），
+// 跨卷回退成复制时会明显更久。这是用户点按钮才触发的显式动作，短暂占用事件循环可接受；
+// 将来若成为常态路径，再考虑挪进 worker。
+//
+// @module dsh-mneme/runtime/provision
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { adoptRuntime } from "./adopt.js";
+import { downloadRuntime } from "./download.js";
+import { defaultRuntimeDir, describePayload, detectLibc } from "./layout.js";
+
+/**
+ * 从插件自身位置推出宿主 node_modules。
+ *
+ * `<profile>/node_modules/@modusensus/dsh-mneme/lib/<file>` 往上是
+ * `lib` → `dsh-mneme` → `@modusensus` → `node_modules`，所以 dirname 四次。
+ * 调用方传自己的 `import.meta.url`，src/ 与 lib/ 这两种同深度布局都成立。
+ *
+ * 用 dirname 而不是 `new URL("../../..")`：后者会得到带尾部路径分隔符的目录 URL，
+ * fileURLToPath 之后是 `...\node_modules\`，与别处 `join()` 出来的字符串不相等 ——
+ * 这个值要参与比较与拼接，形态得是干净的那种。
+ *
+ * 为什么这个推导对两种 linker 都成立：
+ * - hoisted：插件在 `<profile>/node_modules/@modusensus/dsh-mneme/`，上三级就是 profile 的
+ *   node_modules，依赖都平铺在那儿；
+ * - isolated：Node 默认解析 symlink 后的真实路径，插件实际位于
+ *   `<profile>/node_modules/.pnpm/<pkg>/node_modules/@modusensus/dsh-mneme/`，上三级正好是
+ *   那个虚拟 store 的 node_modules —— 而 pnpm 正是把该包的依赖放在它的同级。
+ * 两种情况都指向「装着这个插件依赖的那个 node_modules」，这正是要收编的东西。
+ * @param {string} fromModuleUrl - 调用方自己的 import.meta.url。
+ * @returns {string} 宿主 node_modules 目录。
+ */
+export function hostModulesDir(fromModuleUrl) {
+  const file = fileURLToPath(fromModuleUrl);
+  return dirname(dirname(dirname(dirname(file))));
+}
+
+/**
+ * 收编本 profile 已有的运行时，给出面板可直接显示、脚本也能直接 gate 的结论。
+ * @param {object} opts - 选项。
+ * @param {string} opts.hostModulesDir - 源 node_modules。
+ * @param {string} [opts.runtimeDir] - 运行时根目录；空 = 默认位置。
+ * @param {boolean} [opts.overwrite] - 目标已存在时是否覆盖（用来修一份坏掉的 payload）。
+ * @returns {{ok: boolean, status: string, reason?: string, payloadId?: string, version?: string,
+ *   packages?: number, files?: number, bytes?: number, materialize?: string,
+ *   missing?: string[], gaps?: string[], reasons?: string[]}}
+ */
+export function adoptHostRuntime({ hostModulesDir: from, runtimeDir = "", overwrite = false }) {
+  const result = adoptRuntime({
+    fromModulesDir: from,
+    // 空串必须变成 undefined：adoptRuntime 的默认值只在「未传」时才生效，
+    // 传空串会得到一个相对路径。
+    runtimeDir: runtimeDir || undefined,
+    overwrite
+  });
+
+  // 失败路径不带 payloadDir（入口包解析不到就是这条）—— 先拦掉，别拿 undefined 当路径。
+  if (result.ok === false) {
+    return { ok: false, status: "failed", reason: result.reason };
+  }
+
+  const structural = describePayload(result.payloadDir);
+  const gaps = result.plan.gaps.map((gap) => gap.name);
+  const healthy = structural.ok && gaps.length === 0;
+  // 不健康时**也必须**带 reason：调用方（面板 / 工具 / provisionRuntime）会把它拼进给用户看的
+  // 那句话里，缺了就会显示成「收编失败：undefined」——评审指出的正是这个。
+  const why = [
+    ...structural.missing.map((item) => `缺 ${item}`),
+    ...gaps.map((gap) => `缺依赖 ${gap}`),
+    ...structural.reasons
+  ];
+
+  return {
+    ok: healthy,
+    status: healthy ? "adopted" : "incomplete",
+    ...(healthy ? {} : { reason: `收编结果不完整：${why.join("；") || "结构与闭包检查未通过"}` }),
+    payloadId: result.payloadId,
+    version: result.version,
+    packages: result.plan.packages.length,
+    files: result.totals.files,
+    bytes: result.totals.bytes,
+    materialize: result.manifest.materialize.mode,
+    missing: structural.missing,
+    gaps,
+    // reasons 里可能带绝对路径，但它只回给已鉴权的调用方（面板 / 本机 CLI）；
+    // 免鉴权的 /semantic 走 publicRuntimeStatus 投影，不经过这里。
+    reasons: structural.reasons
+  };
+}
+
+/**
+ * 读随包发布的 runtime-manifest.json。
+ *
+ * 路径：`src/runtime/` 与 `lib/runtime/` 往上两级都是包根，两种布局同深度，所以同一个相对路径
+ * 都成立。清单必须写进 package.json 的 files —— 否则装好的插件里根本没有它（这条真踩过）。
+ * 读不到返回 null：调用方据此给出「没有可下载的清单」这种可读原因，而不是抛栈。
+ * @param {string} [fromModuleUrl] - 调用方自己的 import.meta.url（测试可注入）。
+ * @returns {object|null} 清单内容。
+ */
+export function loadRuntimeManifest(fromModuleUrl = import.meta.url) {
+  try {
+    return JSON.parse(readFileSync(new URL("../../runtime-manifest.json", fromModuleUrl), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 依次尝试三档来源，给出一个统一形状的结论（面板 / CLI / agent 共用）：
+ *   ① 收编本机 node_modules（零网络）② 本地 .tgz 目录 ③ registry（可换镜像）
+ *
+ * 为什么三档都试、而不是先替调用方判断「本机有没有源」：那两种探测都是文件系统判断，
+ * 交给各自的实现更准，而且失败原因本身就是给人看的那句话 —— 判断逻辑重复一遍只会两边漂移。
+ *
+ * 两种来源都失败时，reason 里**两条原因都给**：用户和 agent 都需要知道「为什么收编不行」与
+ * 「为什么下载不行」，只给一条就会被迫去猜另一半。
+ * @param {object} opts - 选项。
+ * @returns {Promise<object>} {ok, strategy, ...}；strategy ∈ adopt | download | none。
+ */
+async function provisionOnce({
+  hostModulesDir: from,
+  runtimeDir = "",
+  localTarballDir = "",
+  mirror = "",
+  overwrite = false,
+  manifest,
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+  fetchImpl,
+  onProgress
+}) {
+  const adopted = adoptHostRuntime({ hostModulesDir: from, runtimeDir, overwrite });
+  if (adopted.ok) return { ...adopted, strategy: "adopt" };
+
+  const loaded = manifest === undefined ? loadRuntimeManifest() : manifest;
+  if (loaded === null || loaded === undefined) {
+    return {
+      ok: false,
+      strategy: "none",
+      status: "failed",
+      reason: `没有可用的 runtime-manifest.json，无法下载；收编也失败：${adopted.reason}`,
+      adoptReason: adopted.reason
+    };
+  }
+
+  const downloaded = await downloadRuntime({
+    manifest: loaded,
+    // 空串要变成 undefined：downloadRuntime 的默认值只在「未传」时生效，传空串会得到相对路径。
+    runtimeDir: runtimeDir || undefined,
+    localTarballDir,
+    mirror,
+    // 收编留下的是「不完整」的那份（缺件 / 缺依赖），它已经不可用：下载这一档必须覆盖它，
+    // 否则会因「目标已存在」失败 —— 用户拿到两份坏消息，却没有任何出路。
+    overwrite: overwrite || adopted.status === "incomplete",
+    platform,
+    arch,
+    libc,
+    ...(fetchImpl === undefined ? {} : { fetchImpl }),
+    ...(onProgress === undefined ? {} : { onProgress })
+  });
+
+  if (downloaded.ok) {
+    // 归一化：收编那一档直接给 packages / files / bytes，而下载档给的是 totals —— 不统一的话
+    // 面板与 agent 工具会读到 undefined（评审判断得对，这条是真 bug）。
+    const totals = downloaded.totals ?? {};
+    return {
+      ...downloaded,
+      strategy: "download",
+      adoptReason: adopted.reason,
+      packages: totals.packages ?? 0,
+      files: totals.files ?? 0,
+      bytes: totals.bytes ?? 0
+    };
+  }
+
+  return {
+    ok: false,
+    strategy: "none",
+    status: "failed",
+    reason: `收编失败：${adopted.reason}；下载失败：${downloaded.reason}`,
+    adoptReason: adopted.reason,
+    downloadReason: downloaded.reason
+  };
+}
+
+/**
+ * 同一运行时目录同时只允许一次取件。
+ *
+ * 面板按钮与 agent 工具可能并发调用（用户也可能连点两下），而取件是直接往**最终目录**写：
+ * 两路并发会互相覆盖成半份 payload。与其让第二次白跑一遍 200MB，不如把它接到正在进行的那次上 ——
+ * 结果一致，而且不会把目录写坏。
+ */
+const IN_FLIGHT = new Map();
+
+/**
+ * 取件真正会写入的那个运行时根目录 —— 绝对且归一化，用作串行化的键。
+ *
+ * 为什么不能直接拿 `options.runtimeDir` 当键：三档实现都是「空串 = 默认位置」，所以
+ * `""`、`~/.dsh/mneme/runtime`、`./runtime`、`D:\x\runtime` 与 `d:\x\runtime`
+ * 可能指向同一个目录，却得到四个不同的键 —— 同一个目录仍会被两路并发写（评审指出）。
+ * 键与写入位置必须一一对应，否则这把锁就只是看起来有用。
+ *
+ * win32 文件系统不区分大小写，键也跟着不区分；POSIX 保持原样（那边大小写是两回事）。
+ * @param {object} [options] - provisionRuntime 的选项。
+ * @returns {string} 归一化后的绝对路径。
+ */
+function runtimeLockKey(options) {
+  const given = String(options?.runtimeDir ?? "").trim();
+  const dir = resolve(given === "" ? defaultRuntimeDir() : given);
+  return process.platform === "win32" ? dir.toLowerCase() : dir;
+}
+
+export async function provisionRuntime(options) {
+  const key = runtimeLockKey(options);
+  const running = IN_FLIGHT.get(key);
+  if (running !== undefined) return running;
+  const task = provisionOnce(options).finally(() => IN_FLIGHT.delete(key));
+  IN_FLIGHT.set(key, task);
+  return task;
+}
+

package/src/runtime/tarball.js

@@ -0,0 +1,130 @@
+// 极简 USTAR 读取 + sha512 校验（issue #131 / PR-C）
+//
+// 为什么自己写而不是加依赖：插件里多一个 tar 依赖，就多一份要跟着上游走的供应链与体积
+// 成本；而这里只需要读「npm registry 产出的 .tgz」这一种固定格式（gzip + ustar/pax），
+// node:zlib 加一个一两百行的读取器就够，而且行为完全可审计。
+//
+// 只做下载通道必需的事：逐个条目回调（不把整棵解压树同时留在内存里）、跳过目录与不认识的
+// 类型、支持 ustar 的 prefix 长路径与 pax 的 path 覆盖（npm 的深层路径两者都会用到）。
+//
+// @module dsh-mneme/runtime/tarball
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+
+const BLOCK = 512;
+/** npm tarball 把所有内容放在统一的 `package/` 前缀下。 */
+const PACKAGE_PREFIX = "package/";
+
+/** 读 ustar 头里的字符串字段：到 NUL 截断，去掉尾随空白。 */
+function readString(buffer, start, length) {
+  const nul = buffer.indexOf(0, start);
+  const end = nul === -1 || nul > start + length ? start + length : nul;
+  return buffer.subarray(start, end).toString("utf8").trim();
+}
+
+/**
+ * 读数字字段。ustar 用八进制 + NUL/空格填充；GNU 对超大值改用 base-256（首字节最高位为 1）。
+ * 两者都认，否则遇到大文件会把它读成 0 字节而静默截断。
+ */
+function readNumber(buffer, start, length) {
+  if ((buffer[start] & 0x80) !== 0) {
+    let value = 0;
+    for (let i = start + 1; i < start + length; i++) value = value * 256 + buffer[i];
+    return value;
+  }
+  const text = readString(buffer, start, length);
+  if (text === "") return 0;
+  const value = parseInt(text, 8);
+  return Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+/** pax 扩展头（typeflag 'x'）的载荷是一串 `长度 key=value\n`，只需要 path。 */
+function paxPath(data) {
+  const text = data.toString("utf8");
+  const match = /^\d+ path=(.*)$/m.exec(text);
+  return match ? match[1] : null;
+}
+
+/**
+ * 遍历一个未压缩的 tar 归档。
+ * @param {Buffer} buffer - tar 字节。
+ * @param {(entry: {path: string, data: Buffer}) => void} onFile - 每个普通文件回调一次。
+ * @returns {{files: number, bytes: number, skipped: string[]}} 统计；skipped 是跳过的类型。
+ */
+export function walkTar(buffer, onFile) {
+  const stats = { files: 0, bytes: 0, skipped: [] };
+  let offset = 0;
+  let pendingPath = null;
+
+  while (offset + BLOCK <= buffer.length) {
+    const header = buffer.subarray(offset, offset + BLOCK);
+    // 全零块 = 归档结束（正常收尾，不是错误）。
+    if (header.every((byte) => byte === 0)) break;
+
+    const name = readString(header, 0, 100);
+    const size = readNumber(header, 124, 12);
+    const typeflag = String.fromCharCode(header[156] || 0x30);
+    const prefix = readString(header, 345, 155);
+    offset += BLOCK;
+
+    const data = buffer.subarray(offset, offset + size);
+    offset += Math.ceil(size / BLOCK) * BLOCK;
+
+    // pax 扩展头：只取 path 覆盖下一条目，自身不是文件。
+    if (typeflag === "x") {
+      pendingPath = paxPath(data) ?? pendingPath;
+      continue;
+    }
+    if (typeflag === "g") continue; // 全局 pax 头，本用途不需要
+
+    const full = pendingPath ?? (prefix ? `${prefix}/${name}` : name);
+    pendingPath = null;
+
+    if (typeflag === "5") continue; // 目录：由文件自身的路径隐式创建
+    if (typeflag !== "0" && typeflag !== "\0" && typeflag !== "") {
+      // 符号链接、硬链接、设备节点等：registry 产物里不该出现，如实记下而不是假装搬过来了。
+      stats.skipped.push(`${full} (typeflag=${typeflag})`);
+      continue;
+    }
+
+    onFile({ path: full.replace(/^\.\//, ""), data });
+    stats.files++;
+    stats.bytes += data.length;
+  }
+
+  return stats;
+}
+
+/**
+ * 遍历一个 .tgz（registry 的产物形态）。
+ * @param {Buffer} gzipped - gzip 字节。
+ * @param {(entry: {path: string, data: Buffer}) => void} onFile - 每个普通文件回调一次。
+ * @returns {{files: number, bytes: number, skipped: string[]}}
+ */
+export function walkTgz(gzipped, onFile) {
+  return walkTar(gunzipSync(gzipped), onFile);
+}
+
+/** 去掉 npm tarball 统一的 `package/` 前缀，得到包内相对路径。 */
+export function stripPackagePrefix(path) {
+  return path.startsWith(PACKAGE_PREFIX) ? path.slice(PACKAGE_PREFIX.length) : path;
+}
+
+/** sha512（base64）。与 npm `integrity` 字段的载荷同形。 */
+export function sha512Base64(buffer) {
+  return createHash("sha512").update(buffer).digest("base64");
+}
+
+/**
+ * 校验一条 npm integrity 字符串（形如 `sha512-<base64>`）。
+ * 只认 sha512：这是 lockfile 里给我们的那一种，其它算法一律当不匹配 —— 校验失败必须是失败，
+ * 不能因为「不认识的算法」而放行。
+ * @param {Buffer} buffer - 待校验的字节。
+ * @param {string} integrity - npm integrity 字符串。
+ * @returns {boolean} 是否匹配。
+ */
+export function verifyIntegrity(buffer, integrity) {
+  const expected = String(integrity ?? "").trim();
+  if (!expected.startsWith("sha512-")) return false;
+  return sha512Base64(buffer) === expected.slice("sha512-".length);
+}

package/src/runtime/verify.js

@@ -0,0 +1,191 @@
+// 运行时验证三件套（issue #131 / PR-A）
+//
+// 为什么要分三层，而不是「能 import 就算通过」：
+//
+//   结构   —— 入口在不在、版本对不对、平台子树对不对、闭包有没有缺口。
+//              便宜、确定，能立刻发现「解压到一半」。
+//   功能   —— 真的 import 入口并跑一次推理。这是唯一能证明「这份运行时在这个
+//              环境里真的算得出来」的一层；结构全对但原生二进制与本机 ABI 不
+//              匹配时，只有它能发现。
+//   完整性 —— 只对「有原始产物可比对」的来源做（下载的 tarball、本地 tarball）。
+//              收编来的目录没有原始 tarball，如实标 unverified，不假装验过。
+//
+// 功能验证复用 src/local-embedder.js 的 engineFactory 思路：真正干活的是注入进来
+// 的 engine，默认实现才去 import 真实运行时。这样测试不需要网络、不需要模型，
+// 也能把「返回了非归一化向量」「只返回一行」这类问题钉住。
+//
+// 默认 engine 会强制 env.allowRemoteModels = false：验证过程绝不能偷偷下载模型，
+// 否则「验证」本身就成了一个新的网络依赖点。
+//
+// @module dsh-mneme/runtime/verify
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+import { TRANSFORMERS_ENTRY, describePayload } from "./layout.js";
+
+/** 默认探针文本：中英各一条，避免只覆盖单字节语种。 */
+export const DEFAULT_PROBE_TEXTS = ["猫咪喜欢晒太阳", "the quick brown fox"];
+/** 默认模型，与 src/config.js 的 localEmbedModel 默认值一致。 */
+export const DEFAULT_PROBE_MODEL = "Xenova/bge-small-zh-v1.5";
+/** L2 归一化的容忍度（我们显式请求了 normalize: true）。 */
+const NORM_TOLERANCE = 0.01;
+/** 判定「退化向量」的余弦上限：两条毫不相干的文本不该几乎同向。 */
+const DEGENERATE_COS = 0.999;
+
+/**
+ * 默认 engine：真的去 import 运行时并建一个 feature-extraction 管道。
+ *
+ * 返回一个 `embed(texts) => number[][]`。之所以不返回 transformers 的 tensor，
+ * 是为了把「Tensor 形状怎么读」这种细节留在实现里，验证逻辑只看数字。
+ * @param {string} entryUrl - 入口文件的 file URL。
+ * @param {{cacheDir?: string, model?: string, dtype?: string, device?: string}} opts - 选项。
+ * @returns {Promise<(texts: string[]) => Promise<number[][]>>} 嵌入函数。
+ */
+export async function defaultEngine(entryUrl, { cacheDir, model = DEFAULT_PROBE_MODEL, dtype = "q8", device = "cpu" } = {}) {
+  const mod = await import(entryUrl);
+  const { env, pipeline } = mod;
+  if (cacheDir) {
+    try {
+      env.cacheDir = cacheDir;
+    } catch {
+      /* 老版本可能没有这个字段：忽略，交给下面 pipeline 自己找缓存 */
+    }
+  }
+  // 验证不允许触网：缓存命中就本地加载，命中不了就明确失败。
+  try {
+    env.allowRemoteModels = false;
+  } catch {
+    /* 同上 */
+  }
+  const extractor = await pipeline("feature-extraction", model, { dtype, device, cache_dir: cacheDir });
+  return async (texts) => {
+    const tensor = await extractor(texts, { pooling: "mean", normalize: true });
+    const dims = Array.from(tensor.dims ?? []);
+    const width = dims[dims.length - 1] || 0;
+    // 宽度为 0 时下面的 `i += width` 会原地打转 —— 那是**死循环**，会把调用方（乃至 DSH 主进程）
+    // 挂住。宁可明确失败：调用方按契约把失败变成 {ok:false, reason}，而不是永远等不到结果。
+    if (!Number.isInteger(width) || width <= 0) {
+      throw new Error(`推理输出的维度不可用：dims=${JSON.stringify(dims)}`);
+    }
+    const rows = [];
+    for (let i = 0; i < tensor.data.length; i += width) {
+      rows.push(Array.from(tensor.data.subarray(i, i + width)));
+    }
+    return rows;
+  };
+}
+
+/** 向量模长。 */
+function norm(row) {
+  let sum = 0;
+  for (const value of row) sum += value * value;
+  return Math.sqrt(sum);
+}
+
+/** 两行向量的余弦。 */
+function cosine(a, b) {
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}
+
+/**
+ * 跑功能验证：真的 import 并嵌入探针文本，然后检查结果的形状与数值性质。
+ *
+ * 任何失败都返回结果对象，不抛异常——验证本身必须是 fail-safe 的，
+ * 否则一条坏运行时会把调用方（面板、状态接口）也带崩。
+ * @param {string} dir - payload 目录。
+ * @param {object} [opts] - 选项。
+ * @returns {Promise<{ok: boolean, reason: string|null, dim: number|null, rows: number, elapsedMs: number}>}
+ */
+export async function verifyFunctional(dir, {
+  engine = defaultEngine,
+  probeTexts = DEFAULT_PROBE_TEXTS,
+  cacheDir,
+  model,
+  dtype,
+  device
+} = {}) {
+  const startedAt = Date.now();
+  const fail = (reason) => ({ ok: false, reason, dim: null, rows: 0, elapsedMs: Date.now() - startedAt });
+
+  const entry = join(dir, TRANSFORMERS_ENTRY);
+  let embed;
+  try {
+    embed = await engine(pathToFileURL(entry).href, { cacheDir, model, dtype, device });
+  } catch (error) {
+    return fail(`加载运行时失败：${error?.message ?? error}`);
+  }
+
+  let rows;
+  try {
+    rows = await embed(probeTexts);
+  } catch (error) {
+    return fail(`推理失败：${error?.message ?? error}`);
+  }
+
+  if (!Array.isArray(rows) || rows.length !== probeTexts.length) {
+    return fail(`返回行数不符：期望 ${probeTexts.length}，实际 ${Array.isArray(rows) ? rows.length : typeof rows}`);
+  }
+  // 先逐行确认「是数组」且「全是有限数」。这一步不能省：non-finite（NaN/Infinity）会让
+  // 下面所有比较恒为 false —— `Math.abs(NaN - 1) > tol` 是 false，`Math.abs(NaN) > 阈值`
+  // 也是 false —— 于是一份坏掉的运行时会被判成「验证通过」。这是本模块最危险的失败模式
+  // （假通过），比抛异常糟得多。行不是数组时同样要先拦住，否则 .length 直接抛，
+  // 违背「任何失败都返回结果对象，不抛异常」的契约。
+  for (let i = 0; i < rows.length; i++) {
+    if (!Array.isArray(rows[i])) return fail(`第 ${i} 行不是数组（${typeof rows[i]}）`);
+    if (rows[i].some((v) => !Number.isFinite(v))) return fail(`第 ${i} 行含有非有限数值`);
+  }
+  const dim = rows[0].length;
+  if (dim === 0) return fail("返回了空向量");
+  if (rows.some((row) => row.length !== dim)) return fail("各行维度不一致");
+
+  for (let i = 0; i < rows.length; i++) {
+    const length = norm(rows[i]);
+    if (Math.abs(length - 1) > NORM_TOLERANCE) {
+      return fail(`第 ${i} 行不是 L2 归一化向量（模长 ${length.toFixed(4)}）`);
+    }
+  }
+  if (rows.length >= 2 && Math.abs(cosine(rows[0], rows[1])) > DEGENERATE_COS) {
+    return fail(`嵌入退化：两条不相干文本的余弦为 ${cosine(rows[0], rows[1]).toFixed(4)}`);
+  }
+
+  return { ok: true, reason: null, dim, rows: rows.length, elapsedMs: Date.now() - startedAt };
+}
+
+/**
+ * 三层验证，任何一层失败都如实记录；结构不过就不再做功能验证（省掉一次无谓的加载）。
+ * @param {string} dir - payload 目录。
+ * @param {object} [opts] - 选项。
+ * @param {{status: string, detail?: string}} [opts.integrity] - 调用方算好的完整性结论
+ *   （下载/本地 tarball 路径在解包前比对过 sha512，把结果传进来；收编路径没有可比对
+ *   的原始产物，默认 unverified）。
+ * @returns {Promise<object>} 三件套结果 + 总判定。
+ */
+export async function verifyPayload(dir, {
+  platform = process.platform,
+  engine,
+  probeTexts,
+  cacheDir,
+  model,
+  dtype,
+  device,
+  integrity
+} = {}) {
+  const structural = describePayload(dir, { platform });
+  const integrityResult = integrity
+    ? { ok: integrity.status === "sha512-matched", status: integrity.status, detail: integrity.detail ?? null }
+    : { ok: true, status: "unverified", detail: "该来源没有可比对的原始产物（收编）；如需强校验请用 --strict 走 tarball 通道" };
+
+  const functional = structural.ok
+    ? await verifyFunctional(dir, { engine, probeTexts, cacheDir, model, dtype, device })
+    : { ok: false, reason: "结构检查未通过，跳过功能验证", dim: null, rows: 0, elapsedMs: 0 };
+
+  return {
+    dir,
+    version: structural.version,
+    ok: structural.ok && functional.ok && integrityResult.ok,
+    structural,
+    functional,
+    integrity: integrityResult
+  };
+}

package/src/scope.js

@@ -0,0 +1,83 @@
+// v0.8.0 A1（issue #17）：写入端 scope 解析。
+//
+// 身份模型（issue #17 的核心约定）：session 只是「载体」，记忆挂在持久化身份
+// 标签上——agent_scope = session header 的 agentPreset（跨会话稳定的 agent 模板
+// 身份），workspace_scope = 会话工作目录（registry 反查的 canonical path 优先，
+// header.cwd 兜底）。session_id 永不作为作用域键。
+//
+// 硬约束：解析失败绝不阻塞写入——任何一步取不到就落 NULL（读侧 NULL = 未标注
+// = 全局可见），任何异常都被吞掉（registry 故障 warn 一次后降级）。
+//
+// scopeEnabled 关闭时 resolveWriteScope 返回 null，调用方一个字段都不该标注，
+// 写入与去重行为和 A1 之前逐字节一致。
+
+/**
+ * @param {object} deps
+ * @param {object} [deps.ctx] 宿主上下文（可能带 workspaceRegistry；旧版 dsh 没有）
+ * @param {object} [deps.config] 已解析配置（读 scopeEnabled）
+ * @param {object} [deps.logger]
+ * @returns {(exec: object) => {agent_scope: string|null, workspace_scope: string|null}|null}
+ */
+export function createScopeResolver({ ctx, config, logger } = {}) {
+  let warned = false;
+  const warnOnce = (msg) => {
+    if (warned) return;
+    warned = true;
+    try {
+      logger?.warn?.(msg);
+    } catch {
+      // logger 自身故障同样不能影响写入路径
+    }
+  };
+
+  return function resolveWriteScope(exec) {
+    if (config?.scopeEnabled !== true) return null;
+
+    let session = null;
+    try {
+      session = exec?.agent?.session ?? null;
+    } catch {
+      session = null;
+    }
+
+    // 持久化 header（issue #17 的身份契约）：session.header 是创建时冻结的
+    // SessionHeader（含 agentPreset/cwd）。⚠️ 不能先读 requestHeader()——那返回
+    // EpochHeader（请求级模型路由头，首个请求后即为真值），会把 session.header
+    // 遮蔽掉，agentPreset/cwd 双双取空（本地 web 复验 2026-09-13 实测踩中）。
+    // 仅当宿主没有 .header 属性时才降级尝试 requestHeader().config（旧形状）。
+    let header = null;
+    try {
+      header = session?.header ?? session?.requestHeader?.()?.config ?? null;
+    } catch {
+      header = null;
+    }
+
+    let agentScope = null;
+    const preset = header?.agentPreset;
+    if (typeof preset === "string" && preset.trim()) agentScope = preset.trim();
+
+    // workspace：registry 反查优先（成员资格 = id 命中 + header canonical cwd
+    // 校验过，path 已 realpath 归一），失败回退 header.cwd，再失败留 NULL。
+    let workspaceScope = null;
+    try {
+      const list = ctx?.workspaceRegistry?.list?.();
+      const sessionId = session?.id;
+      if (Array.isArray(list) && sessionId != null) {
+        const hit = list.find(
+          (ws) => Array.isArray(ws?.sessionIds) && ws.sessionIds.includes(sessionId)
+        );
+        if (typeof hit?.path === "string" && hit.path.trim()) workspaceScope = hit.path.trim();
+      }
+    } catch (e) {
+      warnOnce(
+        `[dsh-mneme] workspaceRegistry lookup failed, falling back to session header cwd: ${String(e)}`
+      );
+    }
+    if (!workspaceScope) {
+      const cwd = header?.cwd;
+      if (typeof cwd === "string" && cwd.trim()) workspaceScope = cwd.trim();
+    }
+
+    return { agent_scope: agentScope, workspace_scope: workspaceScope };
+  };
+}