@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.1

package/dsh-memory-local/test/fixtures-s2b.mjs

@@ -0,0 +1,216 @@
+/**
+ * FORK-EDIT(2026-09-21): S2b 单测夹具 —— 临时目录里的记忆库/向量库（**绝不落生产路径**）。
+ *
+ * 口径（家规「测试不得写生产路径」）：一切路径来自 `fs.mkdtempSync(os.tmpdir())`，
+ * 由调用方显式传给被测模块（config.memoryDb / config.vectorsDb / config.logsDir）。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+// FORK-EDIT(2026-09-22): U3 adapter 接入 —— 夹具造注入事件用的事件名取自适配层唯一源（值恒等）。
+import { EV } from '../src/host-adapter.js';
+
+export const DIM = 512;
+
+/** 确定性 stub 向量（char n-gram 哈希 → dim 维 + L2 归一化）。仅供单测，无任何语义质量。 */
+export function stubVector(text, dim = DIM) {
+  const v = new Float32Array(dim);
+  const s = String(text ?? '').toLowerCase();
+  const grams = [];
+  for (let n = 1; n <= 3; n += 1) {
+    for (let i = 0; i + n <= s.length; i += 1) grams.push(s.slice(i, i + n));
+  }
+  for (const g of grams) {
+    const h = crypto.createHash('md5').update(g).digest();
+    const idx = ((h[0] << 8) | h[1]) % dim;
+    const sign = h[2] % 2 === 0 ? 1 : -1;
+    v[idx] += sign;
+  }
+  let norm = 0;
+  for (let i = 0; i < dim; i += 1) norm += v[i] * v[i];
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < dim; i += 1) v[i] /= norm;
+  return v;
+}
+
+const MEMORY_DDL = `
+  CREATE TABLE IF NOT EXISTS memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    text TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '',
+    pinned INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+    USING fts5(text, tags, content='memories', content_rowid='id');
+  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts (rowid, text, tags) VALUES (new.id, new.text, new.tags);
+  END;
+`;
+
+const VECTORS_DDL = `
+  CREATE TABLE IF NOT EXISTS vectors (
+    source TEXT NOT NULL, ref_id TEXT NOT NULL, model TEXT NOT NULL, dim INTEGER NOT NULL,
+    vec BLOB NOT NULL, text_hash TEXT NOT NULL, updated_at INTEGER NOT NULL,
+    PRIMARY KEY (source, ref_id)
+  );
+  CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);
+`;
+
+/**
+ * 造一个隔离环境（临时目录 + 两侧库 + 记忆条目）。
+ * @param {object} [opts]
+ * @param {Array<{text:string,tags?:string,pinned?:boolean,updated_at?:number}>} [opts.memories]
+ * @param {boolean} [opts.makeVectors] 是否建 vectors.db（false = 模拟"向量库不存在"）
+ * @param {boolean} [opts.makeMemory] 是否建 memory.db
+ * @param {boolean} [opts.writeAutonomy] 是否写 butler-autonomy.json
+ * @param {boolean} [opts.moduleEnabled] 模块位开关值
+ * @param {boolean} [opts.writeLogsDir] 是否预建 logs 目录
+ */
+export function makeTempEnv(opts = {}) {
+  const {
+    memories = [],
+    makeVectors = true,
+    makeMemory = true,
+    writeAutonomy = true,
+    moduleEnabled = true,
+    writeLogsDir = true,
+    modelId = 'stub-ngram',
+  } = opts;
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'g24-s2b-'));
+  const home = path.join(root, '.dsh');
+  const memoryDb = path.join(home, 'memory', 'memory.db');
+  const vectorsDb = path.join(home, 'memory-vectors', 'vectors.db');
+  const logsDir = path.join(home, 'logs');
+  fs.mkdirSync(path.dirname(memoryDb), { recursive: true });
+  if (writeLogsDir) fs.mkdirSync(logsDir, { recursive: true });
+
+  const inserted = [];
+  if (makeMemory) {
+    const db = new DatabaseSync(memoryDb);
+    db.exec(MEMORY_DDL);
+    const stmt = db.prepare(
+      'INSERT INTO memories (text, tags, pinned, created_at, updated_at) VALUES (?, ?, ?, ?, ?)',
+    );
+    memories.forEach((m, i) => {
+      const ts = m.updated_at ?? 1700000000000 + i * 86400000;
+      const r = stmt.run(String(m.text), String(m.tags ?? ''), m.pinned ? 1 : 0, ts, ts);
+      inserted.push({ id: Number(r.lastInsertRowid), text: String(m.text), tags: String(m.tags ?? ''), pinned: Boolean(m.pinned), updated_at: ts });
+    });
+    db.close();
+  }
+
+  if (makeVectors) {
+    fs.mkdirSync(path.dirname(vectorsDb), { recursive: true });
+    const vdb = new DatabaseSync(vectorsDb);
+    vdb.exec(VECTORS_DDL);
+    const ins = vdb.prepare(
+      'INSERT INTO vectors (source, ref_id, model, dim, vec, text_hash, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)',
+    );
+    for (const rec of inserted) {
+      const vec = stubVector(rec.text);
+      ins.run(
+        'memory',
+        String(rec.id),
+        modelId,
+        DIM,
+        Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength),
+        crypto.createHash('sha256').update(rec.text).digest('hex').slice(0, 16),
+        rec.updated_at,
+      );
+    }
+    vdb.prepare('INSERT INTO meta (k, v) VALUES (?, ?)').run('schemaVersion', '1');
+    vdb.prepare('INSERT INTO meta (k, v) VALUES (?, ?)').run('modelId', modelId);
+    vdb.prepare('INSERT INTO meta (k, v) VALUES (?, ?)').run('dim', String(DIM));
+    vdb.close();
+  }
+
+  if (writeAutonomy) {
+    fs.writeFileSync(
+      path.join(home, 'butler-autonomy.json'),
+      `${JSON.stringify({ schemaVersion: 1, modules: { 'memory-recall': { enabled: Boolean(moduleEnabled), since: '2026-09-21T00:00:00.000Z', by: 'test', why: 's2b unittest' } } }, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  return {
+    root,
+    home,
+    memoryDb,
+    vectorsDb,
+    logsDir,
+    inserted,
+    cleanup: () => {
+      try {
+        fs.rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/** 内存 logger（可注入；不落盘）。 */
+export function memoryLogger() {
+  const lines = [];
+  return {
+    log: (obj) => {
+      lines.push(obj);
+      return true;
+    },
+    sweep: () => {},
+    path: '(memory)',
+    stats: () => ({ written: lines.length, errors: 0 }),
+    lines,
+    find: (event) => lines.filter((l) => l.event === event),
+  };
+}
+
+/** 结构化 stub 桥（可注入；可控 ready / 延迟 / 报错）。 */
+export function stubBridge({ ready = true, delayMs = 0, throwOnEncode = null, dim = DIM } = {}) {
+  const calls = { probe: 0, encode: 0 };
+  return {
+    host: '127.0.0.1',
+    port: 8201,
+    kind: 'stub',
+    calls,
+    async probe() {
+      calls.probe += 1;
+      if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+      return ready
+        ? { ok: true, port: 8201, dim, model: 'stub-ngram', error: null }
+        : { ok: false, port: null, dim: 0, model: null, error: 'ECONNREFUSED' };
+    },
+    async health() {
+      return this.probe();
+    },
+    async encode(text) {
+      calls.encode += 1;
+      if (throwOnEncode) throw new Error(throwOnEncode);
+      if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+      return stubVector(String(text), dim);
+    },
+    stats: () => ({ encodeCalls: calls.encode }),
+  };
+}
+
+/** 假 agent（surface 可见性测试用）：nodes/events 结构照 dsh-session 形态。 */
+export function fakeAgent(events) {
+  const list = events || [];
+  return {
+    id: 'test-session',
+    session: {
+      events: list,
+      surface: { nodes: list.map((_, i) => i) },
+    },
+  };
+}
+
+/** 造一条"注入消息"事件（形态与插件注入一致）。 */
+export function injectionEvent(text, ids = [], seq = 0) {
+  return { seq, type: EV.USER_MESSAGE, data: { role: 'user', content: [{ type: 'text', text }], source: { kind: 'memory-recall', version: 1, items: ids } } };
+}

package/dsh-memory-local/test/probe-entity.mjs

@@ -0,0 +1,170 @@
+/**
+ * probe-entity.mjs <entityDir> —— 在**部署位置**加载 dsh-memory 实体，用 mock ctx 断言
+ * 「插件注册出什么」：三工具（memory_write / memory_search / memory_forget）+ memory:recall 段。
+ *
+ * 为什么需要它：`node --check` 只查语法、静态扫只查 import 形态，而「插件被 DSH 加载后到底
+ * 注册了什么」只有真 import 一次真 apply 才知道。它同时是 deploy.mjs 的门禁③ 与
+ * verify-after-restart.mjs 的核心断言（同一支探针，两处口径一致）。
+ *
+ * 副作用：只在一个临时 SQLite 文件上跑 write/search/forget，跑完删掉；不碰任何 DSH home。
+ * 输出：stdout 末行 `PROBE: {json}`；退出码 0 = 全部断言通过，1 = 有断言失败。
+ *
+ * 用法：node test/probe-entity.mjs <entityDir>
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+// FORK-EDIT(2026-09-22): U3 adapter 接入 —— 断言里的服务名取自适配层唯一源；
+// 由于两端同源，本断言变成**真可证伪**：适配层若把 SVC.tools 的值改错，这里立刻红。
+import { SVC } from '../src/host-adapter.js'
+
+const entityDir = process.argv[2]
+// 默认断言「这是 fork 实体」；--upstream 用于拿上游原物做对照（回归脚本会用到）。
+const mode = process.argv.includes('--upstream') ? 'upstream' : 'fork'
+if (!entityDir) {
+  console.error('usage: node test/probe-entity.mjs <entityDir>')
+  process.exit(2)
+}
+const entityAbs = path.resolve(entityDir)
+const entry = path.join(entityAbs, 'lib', 'index.js')
+const failures = []
+const check = (name, ok, detail = '') => {
+  if (!ok) failures.push(`${name}${detail ? ` — ${detail}` : ''}`)
+  return ok
+}
+
+const result = { entityDir: entityAbs, packageName: null, fork: null, tools: [], section: null, behavior: null }
+
+try {
+  const pkgFile = path.join(entityAbs, 'package.json')
+  if (fs.existsSync(pkgFile)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'))
+    result.packageName = pkg.name
+    result.packageVersion = pkg.version
+    result.fork = pkg.fork ?? null
+  }
+  check('lib/index.js exists', fs.existsSync(entry), entry)
+  if (mode === 'fork') {
+    check('package.json has a fork section', Boolean(result.fork), JSON.stringify(result.packageName))
+    check('fork section records the upstream base',
+      Boolean(result.fork?.base) && Boolean(result.fork?.baseSha256) && Boolean(result.fork?.libSha256),
+      JSON.stringify(result.fork))
+  } else {
+    check('entity is the untouched upstream package',
+      !result.fork && result.packageName === 'dsh-memory', JSON.stringify(result.packageName))
+  }
+
+  const mod = await import(pathToFileURL(entry).href)
+  check('module exports apply', typeof mod.apply === 'function')
+  check('module name === "memory"', mod.name === 'memory', String(mod.name))
+  check('inject includes tools + systemPrompt',
+    Array.isArray(mod.inject) && mod.inject.includes(SVC.tools) && mod.inject.includes(SVC.systemPrompt),
+    JSON.stringify(mod.inject))
+
+  // mock ctx：只实现插件真正用到的那几个面（tools.register / systemPrompt.section / effect / on）
+  // FORK-EDIT(2026-09-21 · S2b): 新增 `on`（`agent/pre-step` 监听）与 `memory_get` 断言。
+  const registered = []
+  const sections = []
+  const disposers = []
+  const listeners = []
+  const ctx = {
+    tools: { register: (tool) => { registered.push(tool); return () => {} } },
+    systemPrompt: { section: (section) => { sections.push(section); return () => {} } },
+    effect: (fn) => { const d = fn(); if (typeof d === 'function') disposers.push(d); return () => {} },
+    on: (event, handler, options) => { listeners.push({ event, handler, options }); return () => {} },
+  }
+
+  const dbFile = path.join(os.tmpdir(), `dsh-memory-probe-${process.pid}-${Date.now()}.db`)
+  // S2b：配置走插件自己的 schema（拿全量默认值），再把注入面全部指向临时目录
+  // ⇒ 探针不读也不写任何 DSH home（家规：测试不得落生产路径）。
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memory-probe-home-'))
+  const baseConfig = {
+    path: dbFile,
+    promptRecentCount: 10,
+    promptMaxChars: 2000,
+    maxTextChars: 2000,
+    searchLimitDefault: 10,
+    searchLimitMax: 50,
+    promptOrder: 50,
+  }
+  const config = typeof mod.Config === 'function'
+    ? mod.Config({
+        ...baseConfig,
+        recallEnabled: false, // 探针不跑注入链，只验注册面
+        recallHome: tmpHome,
+        recallMemoryDb: path.join(tmpHome, 'memory', 'memory.db'),
+        recallVectorsDb: path.join(tmpHome, 'memory-vectors', 'vectors.db'),
+      })
+    : baseConfig
+  result.configKeys = Object.keys(config).length
+  mod.apply(ctx, config)
+
+  result.tools = registered.map((t) => ({ name: t?.name, hasExecute: typeof t?.execute === 'function' }))
+  const names = result.tools.map((t) => t.name).sort()
+  // S2b：fork 版在官方三工具之外自注册 `memory_get`（指针指向的那扇门，方案 §3.4 关 B1）；
+  // `--upstream` 模式拿上游原物对照，仍是官方三工具、也没有 pre-step 监听。
+  const expectedTools = mode === 'fork'
+    ? ['memory_forget', 'memory_get', 'memory_search', 'memory_write']
+    : ['memory_forget', 'memory_search', 'memory_write']
+  check(`registers the expected tools (${mode})`,
+    JSON.stringify(names) === JSON.stringify(expectedTools),
+    JSON.stringify(names))
+  check('every tool has execute()', result.tools.every((t) => t.hasExecute))
+  if (mode === 'fork') {
+    check('registers the agent/pre-step recall listener',
+      listeners.some((l) => l.event === 'agent/pre-step' && typeof l.handler === 'function'),
+      JSON.stringify(listeners.map((l) => l.event)))
+    check('the pre-step listener is prepended',
+      listeners.some((l) => l.event === 'agent/pre-step' && l.options && l.options.prepend === true),
+      JSON.stringify(listeners.map((l) => l.options ?? null)))
+  }
+
+  check('registers the memory:recall prompt section', sections.length === 1 && sections[0]?.name === 'memory:recall',
+    JSON.stringify(sections.map((s) => s?.name)))
+  const section = sections[0]
+  check('recall section exposes text()', typeof section?.text === 'function')
+
+  // 行为冒烟：write → search → get → forget（在临时库上）
+  const tool = (n) => registered.find((t) => t?.name === n)
+  const written = await tool('memory_write').execute({ text: 'probe: dsh-memory-local entity smoke', tags: ['Probe', 'probe'], pinned: false })
+  const found = await tool('memory_search').execute({ query: 'probe dsh-memory-local' })
+  // S2b：只读展开（指针的落点）
+  const got = tool('memory_get')
+    ? await tool('memory_get').execute({ id: written.id }, { agent: { id: 'probe-session' } })
+    : null
+  const forgotten = await tool('memory_forget').execute({ id: written.id })
+  const sectionTextOnEmpty = sections[0].text()
+  result.behavior = {
+    writeId: written.id, writeTags: written.tags, writePinned: written.pinned,
+    searchHits: found.matches.length, searchFirstId: found.matches[0]?.id ?? null,
+    gotText: got ? String(got.text).slice(0, 40) : null,
+    gotFound: got ? String(got.text).length > 0 : null,
+    forgotten: forgotten.forgotten,
+    sectionAfterForget: sectionTextOnEmpty === '' ? 'empty' : 'non-empty',
+  }
+  check('memory_write returned an id + normalized tags', Number.isInteger(written.id) && written.tags === 'probe',
+    JSON.stringify(written))
+  check('memory_search finds the freshly written fact', found.matches.length === 1 && found.matches[0].id === written.id,
+    JSON.stringify(found.matches.map((m) => m.id)))
+  if (mode === 'fork') {
+    check('memory_get expands the same record (read-only)',
+      Boolean(got) && got.id === written.id && String(got.text).includes('entity smoke') && got.truncated === false,
+      JSON.stringify(got))
+    check('memory_get reports a missing id instead of throwing',
+      JSON.stringify(await tool('memory_get').execute({ id: 999999 })) !== null)
+  }
+  check('memory_forget deletes it', forgotten.forgotten === true, JSON.stringify(forgotten))
+  check('recall section renders empty after the delete', sectionTextOnEmpty === '', JSON.stringify(sectionTextOnEmpty.slice(0, 60)))
+
+  for (const d of disposers) { try { d() } catch { /* dispose best-effort */ } }
+  for (const f of [dbFile, `${dbFile}-journal`]) { try { fs.rmSync(f, { force: true }) } catch { /* ignore */ } }
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }) } catch { /* ignore */ }
+} catch (error) {
+  failures.push(`threw: ${error instanceof Error ? error.message : String(error)}`)
+}
+
+result.ok = failures.length === 0
+result.failures = failures
+console.log(`PROBE: ${JSON.stringify(result)}`)
+process.exit(result.ok ? 0 : 1)

package/dsh-memory-local/test/regression.mjs

@@ -0,0 +1,270 @@
+/**
+ * regression.mjs —— fork 回归：**同输入、同输出**地对照上游实体与 fork 实体。
+ *
+ * 对照对象（各跑一遍完全相同的操作序列，全部在各自的临时 SQLite 上）：
+ *   · 模块面   ：name / inject / 三工具的名字、描述、参数 schema、输出 render 文本
+ *   · 行为面   ：write（含 tags 归一化 / pinned）/ search（命中、空结果、非法 limit）/
+ *                forget（命中、不存在）/ memory:recall 段文本 / 各错误消息
+ *   · 汇总指纹 ：把两次运行的观测序列各算一个 sha256，不相等即 FAIL 并打印首个差异
+ *
+ * 这是「三个官方工具行为一致」的机器判据（不花 token、不碰任何 DSH home、只用临时库）。
+ *
+ * 用法：
+ *   node test/regression.mjs [--upstream <上游实体目录>] [--fork <fork实体或源码目录>]
+ * 默认：上游 = _archive 里 deploy 备份的 official-entity（其次本机生产 profile 实体，只读）；
+ *       fork = 本包（未部署时直接用源码 lib/）。
+ * 退出码：0 = 完全一致 / 1 = 存在差异 / 2 = 用法错误 / 3 = 找不到上游对照物。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const pkgRoot = path.join(here, '..')
+const args = process.argv.slice(2)
+const argValue = (flag) => {
+  const i = args.indexOf(flag)
+  return i >= 0 && args[i + 1] ? args[i + 1] : null
+}
+
+function findUpstream() {
+  const explicit = argValue('--upstream')
+  if (explicit) return explicit
+  const archive = process.env.DSH_ARCHIVE || path.join(process.cwd(), '_archive')
+  if (fs.existsSync(archive)) {
+    const snaps = fs.readdirSync(archive)
+      .filter((n) => n.startsWith('g24-s2a-memory-deploy-'))
+      .map((n) => path.join(archive, n, 'official-entity'))
+      .filter((d) => fs.existsSync(path.join(d, 'lib', 'index.js')))
+      .sort()
+    if (snaps.length) return snaps.at(-1)
+  }
+  const production = path.join(os.homedir(), '.dsh', 'profiles', 'web', 'node_modules', 'dsh-memory')
+  if (fs.existsSync(path.join(production, 'lib', 'index.js'))) return production
+  return null
+}
+
+/**
+ * fork 侧默认取**隔离实例里的部署实体** —— 插件只能在「部署位置」被加载：
+ * 它的 peer 依赖（@deepseek-ai/schemastery、@deepseek-ai/dsh-tools）由 profile 的闭包提供，
+ * 源码目录（tools/dsh-memory-local）没有 node_modules，直接 import 会 ERR_MODULE_NOT_FOUND。
+ */
+function findForkEntity() {
+  const explicit = argValue('--fork') ?? process.env.DSH_MEMORY_FORK_ENTITY ?? null
+  if (explicit) return explicit
+  const candidates = [
+    path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'profiles', 'web', 'node_modules', 'dsh-memory'),
+  ]
+  for (const c of candidates) {
+    const pkgFile = path.join(c, 'package.json')
+    if (!fs.existsSync(pkgFile)) continue
+    try {
+      if (JSON.parse(fs.readFileSync(pkgFile, 'utf8')).fork) return c
+    } catch { /* not a dsh entity */ }
+  }
+  return null
+}
+
+/**
+ * 从 dir 向上找第一个「能解析到宿主闭包」的目录（判据 = node_modules/@deepseek-ai/schemastery 存在）。
+ * 插件只能在这样的位置被 import —— 源码目录与 _archive 都不满足，profile 实体满足。
+ */
+function resolvableContext(dir) {
+  let cur = path.resolve(dir)
+  for (;;) {
+    if (fs.existsSync(path.join(cur, 'node_modules', '@deepseek-ai', 'schemastery'))) return cur
+    const parent = path.dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+}
+
+const forkDir = findForkEntity()
+const upstreamDir = findUpstream()
+if (!forkDir) {
+  console.error('[regression] 找不到 fork 部署实体：先把 fork 部署到隔离实例（deploy.mjs --target <DSH_HOME>），')
+  console.error('            或用 --fork <实体目录> / $DSH_MEMORY_FORK_ENTITY 显式指定部署位置。')
+  process.exit(2)
+}
+if (!upstreamDir) { console.error('[regression] 找不到上游对照实体：用 --upstream <dir> 显式指定'); process.exit(3) }
+
+const fixtureText = 'regression fixture: DSH 记忆引擎 fork 基线（tags 归一化 + 中文）'
+const pinnedText = 'pinned fixture: 每轮都要出现的事实'
+
+/** 用 mock ctx 加载一个实体，跑固定序列，返回可比较的观测对象。 */
+async function observe(label, dir) {
+  const obs = { label, dir, steps: [] }
+  const entry = path.join(dir, 'lib', 'index.js')
+  const mod = await import(pathToFileURL(entry).href)
+  obs.module = { name: mod.name, inject: mod.inject, hasApply: typeof mod.apply === 'function' }
+
+  const registered = []
+  const sections = []
+  const ctx = {
+    tools: { register: (t) => { registered.push(t); return () => {} } },
+    systemPrompt: { section: (s) => { sections.push(s); return () => {} } },
+    effect: (fn) => { const d = fn(); return () => { if (typeof d === 'function') d() } },
+    // FORK-EDIT(2026-09-21): S2b 起 fork 会注册 `agent/pre-step` 监听（指针注入）。
+    // 夹具给一个空监听口 —— 注入链本身由 s2b.test.mjs 覆盖，本对照只看三工具与段。
+    on: () => () => {},
+  }
+  const dbFile = path.join(os.tmpdir(), `dsh-memory-regression-${label}-${process.pid}-${Date.now()}.db`)
+  // FORK-EDIT(2026-09-21): S2b 起 fork 的 Config 多了 recall* 字段（指针注入，默认关）。
+  // 它们全部给默认值 ⇒ 两侧行为面不变；上游实体不认识这些键（schemastery 忽略），故可同一份夹具。
+  // `recallEnabled:false` = 注入链路不激活，对照的仍是「三工具 + memory:recall 段」本身。
+  const recallDefaults = {
+    recallEnabled: false, recallHome: '', recallMemoryDb: '', recallVectorsDb: '',
+    recallBridgeHost: '127.0.0.1', recallBridgePort: 8201, recallBridgePortScanMax: 10,
+    recallTimeoutMs: 300, recallEncodeTimeoutMs: 250, recallMaxItems: 8, recallMaxChars: 800,
+    recallMaxTokens: 600, recallMaxPerSession: 3, recallSummaryChars: 80, recallQueryMaxChars: 512,
+    recallVectorTopK: 20, recallFtsTopK: 20, recallRrfK: 60, recallResultTopK: 8, recallIndexTtlMs: 60000,
+  }
+  mod.apply(ctx, {
+    path: dbFile, promptRecentCount: 10, promptMaxChars: 2000, maxTextChars: 2000,
+    searchLimitDefault: 10, searchLimitMax: 50, promptOrder: 50,
+    ...recallDefaults,
+  })
+
+  const capture = async (step, fn) => {
+    try {
+      const value = await fn()
+      obs.steps.push({ step, ok: true, value })
+    } catch (error) {
+      obs.steps.push({ step, ok: false, error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  const tool = (n) => registered.find((t) => t?.name === n)
+  const describe = (t) => ({
+    name: t?.name,
+    description: t?.description,
+    parameters: t?.parameters,
+    outputSchema: t?.output?.schema,
+    hasRender: typeof t?.output?.render === 'function',
+    hasPresentCall: typeof t?.presentCall === 'function',
+  })
+  obs.toolShapes = registered.map(describe)
+  obs.sectionShapes = sections.map((s) => ({ name: s?.name, order: s?.order, hasText: typeof s?.text === 'function' }))
+
+  const render = (name, args, value) => tool(name).output.render(args, value)
+
+  await capture('write.fixture', () => tool('memory_write').execute({ text: fixtureText, tags: ['Reg', 'reg', '中文 标签'], pinned: false }))
+  await capture('write.pinned', () => tool('memory_write').execute({ text: pinnedText, tags: [], pinned: true }))
+  await capture('section.afterWrites', () => sections[0].text())
+  await capture('search.hit', async () => {
+    const value = await tool('memory_search').execute({ query: 'regression fixture' })
+    return { value, rendered: render('memory_search', { query: 'regression fixture' }, value) }
+  })
+  await capture('search.miss', async () => {
+    const value = await tool('memory_search').execute({ query: 'zzz-不存在的词-zzz' })
+    return { value, rendered: render('memory_search', { query: 'zzz-不存在的词-zzz' }, value) }
+  })
+  await capture('search.badLimit', () => tool('memory_search').execute({ query: 'fixture', limit: 0 }))
+  await capture('search.emptyQuery', () => tool('memory_search').execute({ query: '   ' }))
+  await capture('search.limitOverMax', () => tool('memory_search').execute({ query: 'fixture', limit: 999 }))
+  await capture('write.blank', () => tool('memory_write').execute({ text: '   ' }))
+  await capture('write.tooLong', () => tool('memory_write').execute({ text: 'x'.repeat(2001) }))
+  await capture('forget.missing', async () => {
+    const value = await tool('memory_forget').execute({ id: 999999 })
+    return { value, rendered: render('memory_forget', { id: 999999 }, value) }
+  })
+  await capture('forget.hit', async () => {
+    const value = await tool('memory_forget').execute({ id: 1 })
+    return { value, rendered: render('memory_forget', { id: 1 }, value) }
+  })
+  await capture('section.afterForget', () => sections[0].text())
+  await capture('write.render', () => render('memory_write', { text: fixtureText }, { id: 7, tags: 'reg', pinned: false }))
+
+  for (const f of [dbFile, `${dbFile}-journal`]) { try { fs.rmSync(f, { force: true }) } catch { /* ignore */ } }
+  obs.fingerprint = crypto.createHash('sha256').update(JSON.stringify(obs)).digest('hex')
+  return obs
+}
+
+// 上游对照物也必须落在「能解析到宿主闭包」的位置：_archive 里的备份原物不在任何 profile 的
+// node_modules 树内，直接 import 会 ERR_MODULE_NOT_FOUND（schemastery 由 profile 闭包提供）。
+// → 必要时把它铺进隔离 profile 的隐藏参考目录（跑完清理，--keep-ref 可保留）。
+const keepRef = args.includes('--keep-ref')
+const refRoot = path.join(path.dirname(path.resolve(forkDir)), '.g24-s2a-upstream-ref')
+let upstreamPath = path.resolve(upstreamDir)
+let cleanupRef = null
+if (resolvableContext(upstreamPath) === null) {
+  try { fs.rmSync(refRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+  fs.mkdirSync(refRoot, { recursive: true })
+  upstreamPath = path.join(refRoot, 'dsh-memory')
+  fs.cpSync(upstreamDir, upstreamPath, { recursive: true })
+  cleanupRef = keepRef ? null : refRoot
+  console.log(`[regression] 上游对照物已铺到可解析位置：${upstreamPath}${keepRef ? '（--keep-ref 保留）' : '（跑完清理）'}`)
+}
+
+let upstream
+let fork
+try {
+  upstream = await observe('upstream', upstreamPath)
+  fork = await observe('fork', path.resolve(forkDir))
+} finally {
+  if (cleanupRef) { try { fs.rmSync(cleanupRef, { recursive: true, force: true }) } catch { /* ignore */ } }
+}
+
+const failures = []
+function compare(label, a, b) {
+  const sa = JSON.stringify(a)
+  const sb = JSON.stringify(b)
+  if (sa !== sb) failures.push({ label, upstream: sa?.slice(0, 400), fork: sb?.slice(0, 400) })
+}
+/**
+ * FORK-EDIT(2026-09-21): 「工具集」对照的**显式白名单**（否则这道门永远红 = 等于失效）。
+ * 依据：方案 `docs\P2-记忆引擎升级-方案-20260916.md` §3.4 —— `memory_get` 是 fork 自注册的
+ * 「指针展开」工具（官方包不提供，属**有意新增**）；其余任何工具差异照旧判红。
+ * 只放宽"多出"这一个名字，且要求上游工具集是 fork 的**真子集**（少一个/改名/多一个都算差异）。
+ */
+const FORK_ONLY_TOOLS = ['memory_get']
+function compareToolShapes(a, b) {
+  const names = (list) => (Array.isArray(list) ? list.map((t) => t?.name) : [])
+  const up = names(a)
+  const fk = names(b)
+  const extra = fk.filter((n) => !up.includes(n))
+  const missing = up.filter((n) => !fk.includes(n))
+  const unexpectedExtra = extra.filter((n) => !FORK_ONLY_TOOLS.includes(n))
+  const byName = (list) => Object.fromEntries((list ?? []).map((t) => [t?.name, t]))
+  const upMap = byName(a)
+  const fkMap = byName(b)
+  const shapeDiffs = up.filter((n) => JSON.stringify(upMap[n]) !== JSON.stringify(fkMap[n])).map((n) => n)
+  if (missing.length === 0 && unexpectedExtra.length === 0 && shapeDiffs.length === 0) {
+    if (extra.length > 0) console.log(`[regression] 白名单放行 fork 独有工具：${extra.join(', ')}（依据：方案 §3.4 / S2b 交付报告）`)
+    return
+  }
+  failures.push({
+    label: `tool shapes（缺=${JSON.stringify(missing)} 越界多出=${JSON.stringify(unexpectedExtra)} 形状变化=${JSON.stringify(shapeDiffs)}）`,
+    upstream: JSON.stringify(a)?.slice(0, 400),
+    fork: JSON.stringify(b)?.slice(0, 400),
+  })
+}
+compare('module shape', upstream.module, fork.module)
+compareToolShapes(upstream.toolShapes, fork.toolShapes)
+compare('section shapes', upstream.sectionShapes, fork.sectionShapes)
+compare('step count', upstream.steps.length, fork.steps.length)
+for (let i = 0; i < Math.max(upstream.steps.length, fork.steps.length); i++) {
+  compare(`step[${i}] ${upstream.steps[i]?.step ?? fork.steps[i]?.step ?? '?'}`, upstream.steps[i], fork.steps[i])
+}
+
+console.log(`upstream : ${upstream.dir}`)
+console.log(`fork     : ${fork.dir}`)
+console.log(`upstream fingerprint : ${upstream.fingerprint}`)
+console.log(`fork     fingerprint : ${fork.fingerprint}`)
+console.log(`steps compared       : ${upstream.steps.length}`)
+for (const s of upstream.steps) {
+  console.log(`  ${s.ok ? 'ok  ' : 'err '} ${s.step.padEnd(20)} ${JSON.stringify(s.ok ? s.value : s.error).slice(0, 120)}`)
+}
+if (failures.length === 0) {
+  console.log('\nregression: IDENTICAL — 上下游实体在同一序列上逐步骤一致（含工具描述、参数 schema、错误消息、段落文本、render 文本）')
+  process.exit(0)
+}
+console.log(`\nregression: ${failures.length} DIFFERENCE(S)`)
+for (const f of failures) {
+  console.log(`  ✗ ${f.label}`)
+  console.log(`      upstream: ${f.upstream}`)
+  console.log(`      fork    : ${f.fork}`)
+}
+process.exit(1)