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

package/dsh-memory-local/restore.mjs

@@ -0,0 +1,259 @@
+/**
+ * restore.mjs —— 把 web profile 的 `dsh-memory` 实体原子还原成**上游官方原物**（一键回滚）。
+ *
+ * 还原源 = deploy.mjs 首次替换时归档的 `_archive\g24-s2a-memory-deploy-*\official-entity\`
+ * （该目录不存在就不动手：没有还原源时回滚等于破坏）。
+ *
+ * 流程（可回滚的原子交换）：
+ *   1) 找含上游原物的备份目录（最新一个）
+ *   2) 把当前实体快照到 `_archive\g24-s2a-memory-prerestore-<stamp>\entity-before-restore\`
+ *      —— 还原本身也可被审视/再回滚
+ *   3) 上游原物拷进 `<target>.restore-tmp-<stamp>`，逐文件核 sha（与 OFFICIAL-ENTITY.json 对齐）
+ *   4) 交换：target → `<target>.restore-old-<stamp>`、tmp → target，然后删掉 old
+ *   5) 复核还原后 sha，打印「重新部署」命令
+ *
+ * 退出码：0 = 成功（含 --dry-run / --self-test 通过） / 1 = 还原失败 / 2 = 用法错误（含未知参数 / 缺 --allow-production） / 3 = 无还原源。
+ *
+ * 🔒 生产闸：`--target` 落在生产树（`$DSH_HOME` 与可选 `DSH_PROD_ROOTS`，realpath + 逻辑双比）内时，
+ *    **真还原**必须显式 `--allow-production`（否则 rc=2）；`--dry-run` 是只读档，不受闸门限制。
+ *
+ * 用法：
+ *   node restore.mjs --target <DSH_HOME> [--profile web] [--dry-run] [--list] [--allow-production]
+ *   node restore.mjs --self-test              # 沙箱夹具演练（不碰任何真实 home）
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { parseArgs, describeUnknown, EXIT } from '../lib/deploy-guard.mjs'
+// R-060 隔离闸（2026-10-16 接入）：把本文件原来"只比是否等于默认 home"的精确字符串比较，换成共享件
+// 「realpath + 逻辑路径双比」的生产树判定（`tools\lib\production-guard.mjs`）。
+import { gateProductionWrite, refuseLine } from './lib/prod-gate.mjs'
+
+const KNOWN_ARGS = [
+  '--dry-run', '--list', '--self-test', '--allow-production',
+  { flag: '--target', takesValue: true },
+  { flag: '--profile', takesValue: true, alias: '--p' },
+  { flag: '--archive', takesValue: true },
+]
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
+const stamp = () => {
+  const d = new Date()
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+const listTree = (root) => {
+  const out = []
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) walk(full)
+      else if (e.isFile()) out.push(path.relative(root, full).replaceAll('\\', '/'))
+    }
+  }
+  if (fs.existsSync(root)) walk(root)
+  return out.sort()
+}
+
+/** 找含上游原物的备份目录（最新优先）。 */
+function findSnapshot(archiveRoot) {
+  if (!fs.existsSync(archiveRoot)) return []
+  return fs.readdirSync(archiveRoot)
+    .filter((n) => n.startsWith('g24-s2a-memory-deploy-'))
+    .map((n) => path.join(archiveRoot, n))
+    .filter((d) => fs.existsSync(path.join(d, 'official-entity', 'package.json')))
+    .sort()
+}
+
+/** 校验一份实体目录与 OFFICIAL-ENTITY.json 的逐文件 sha 是否一致。 */
+function verifyAgainstManifest(entityDir, manifestFile) {
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'))
+  const bad = []
+  for (const f of manifest.files) {
+    const full = path.join(entityDir, f.file)
+    if (!fs.existsSync(full)) { bad.push(`${f.file}: missing`); continue }
+    const got = sha256(fs.readFileSync(full))
+    if (got !== f.sha256) bad.push(`${f.file}: sha ${got.slice(0, 12)} != ${f.sha256.slice(0, 12)}`)
+  }
+  return { manifest, bad }
+}
+
+/** 核心还原（供正常路径与 self-test 共用）。 */
+function restoreEntity({ target, backupDir, archiveRoot, dry }) {
+  const officialDir = path.join(backupDir, 'official-entity')
+  const manifestFile = path.join(backupDir, 'OFFICIAL-ENTITY.json')
+  const out = { target, backupDir, actions: [], ok: false }
+
+  const verified = verifyAgainstManifest(officialDir, manifestFile)
+  if (verified.bad.length) throw new Error(`备份原物自身校验失败：${verified.bad.join('; ')}`)
+  out.manifestFiles = verified.manifest.files.length
+
+  const tag = stamp()
+  const preDir = path.join(archiveRoot, `g24-s2a-memory-prerestore-${tag}`)
+  const tmpDir = `${target}.restore-tmp-${tag}`
+  const oldDir = `${target}.restore-old-${tag}`
+  out.actions.push(`snapshot current entity -> ${path.join(preDir, 'entity-before-restore')}`)
+  out.actions.push(`stage upstream entity -> ${tmpDir}`)
+  out.actions.push(`swap: ${target} -> ${oldDir}, then ${tmpDir} -> ${target}`)
+  out.preRestoreDir = preDir
+  if (dry) return out
+
+  // 2) 快照当前实体（还原也可被再回滚）
+  fs.mkdirSync(preDir, { recursive: true })
+  if (fs.existsSync(target)) fs.cpSync(target, path.join(preDir, 'entity-before-restore'), { recursive: true })
+  fs.writeFileSync(path.join(preDir, 'RESTORE-INFO.json'), `${JSON.stringify({
+    restoredAt: new Date().toISOString(), restoredFrom: backupDir, target,
+  }, null, 2)}\n`, 'utf8')
+
+  // 3) stage + 核 sha
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+  fs.cpSync(officialDir, tmpDir, { recursive: true })
+  const staged = verifyAgainstManifest(tmpDir, manifestFile)
+  if (staged.bad.length) { fs.rmSync(tmpDir, { recursive: true, force: true }); throw new Error(`stage 校验失败：${staged.bad.join('; ')}`) }
+
+  // 4) 交换
+  if (fs.existsSync(target)) fs.renameSync(target, oldDir)
+  fs.renameSync(tmpDir, target)
+  fs.rmSync(oldDir, { recursive: true, force: true })
+
+  // 5) 复核
+  const after = verifyAgainstManifest(target, manifestFile)
+  if (after.bad.length) throw new Error(`还原后复核失败：${after.bad.join('; ')}`)
+  out.ok = true
+  out.restoredFiles = after.manifest.files.length
+  return out
+}
+
+// ── --self-test：沙箱夹具演练（不碰真实 home / 真实 _archive） ─────────────────
+if (process.argv.includes('--self-test')) {
+  const pa = parseArgs(process.argv.slice(2), KNOWN_ARGS)
+  if (!pa.ok) { console.error(`[restore] ${describeUnknown(pa.unknown, KNOWN_ARGS)}`); process.exit(EXIT.USAGE) }
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'g24-s2a-restore-selftest-'))
+  const archiveRoot = path.join(sandbox, 'archive')
+  const target = path.join(sandbox, 'home', 'profiles', 'web', 'node_modules', 'dsh-memory')
+  const failures = []
+  const check = (name, ok, detail = '') => { console.log(`${ok ? 'PASS' : 'FAIL'} ${name}${detail ? ` — ${detail}` : ''}`); if (!ok) failures.push(name) }
+  try {
+    // 夹具：一份「官方原物」备份目录 + 一份「fork 实体」当前态
+    const backupDir = path.join(archiveRoot, 'g24-s2a-memory-deploy-20260921-000000')
+    const officialDir = path.join(backupDir, 'official-entity')
+    fs.mkdirSync(path.join(officialDir, 'lib'), { recursive: true })
+    fs.writeFileSync(path.join(officialDir, 'lib', 'index.js'), 'export const marker = "UPSTREAM";\n', 'utf8')
+    fs.writeFileSync(path.join(officialDir, 'package.json'), `${JSON.stringify({ name: 'dsh-memory', version: '0.1.0' }, null, 2)}\n`, 'utf8')
+    const files = listTree(officialDir).map((f) => ({
+      file: f, bytes: fs.statSync(path.join(officialDir, f)).size, sha256: sha256(fs.readFileSync(path.join(officialDir, f))),
+    }))
+    fs.writeFileSync(path.join(backupDir, 'OFFICIAL-ENTITY.json'), `${JSON.stringify({ files }, null, 2)}\n`, 'utf8')
+
+    fs.mkdirSync(path.join(target, 'lib'), { recursive: true })
+    fs.writeFileSync(path.join(target, 'lib', 'index.js'), 'export const marker = "FORK";\n', 'utf8')
+    fs.writeFileSync(path.join(target, 'package.json'), `${JSON.stringify({ name: 'dsh-memory', version: '0.1.0', fork: { name: 'dsh-memory-local' } }, null, 2)}\n`, 'utf8')
+
+    // ① 无还原源时拒绝
+    const emptyArchive = path.join(sandbox, 'empty-archive')
+    fs.mkdirSync(emptyArchive, { recursive: true })
+    check('no snapshot -> findSnapshot returns []', findSnapshot(emptyArchive).length === 0)
+    check('snapshot discovered', findSnapshot(archiveRoot).length === 1, JSON.stringify(findSnapshot(archiveRoot)))
+
+    // ② dry-run 不动盘
+    const dryRun = restoreEntity({ target, backupDir, archiveRoot, dry: true })
+    check('dry-run reports actions', dryRun.actions.length === 3 && dryRun.ok === false)
+    check('dry-run leaves the fork entity untouched',
+      fs.readFileSync(path.join(target, 'lib', 'index.js'), 'utf8').includes('FORK'))
+
+    // ③ 真还原
+    const real = restoreEntity({ target, backupDir, archiveRoot, dry: false })
+    check('restore ok', real.ok === true && real.restoredFiles === 2, JSON.stringify(real.restoredFiles))
+    check('entity is upstream again',
+      fs.readFileSync(path.join(target, 'lib', 'index.js'), 'utf8').includes('UPSTREAM'))
+    check('fork package.json (with fork section) is gone',
+      JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8')).fork === undefined)
+    check('pre-restore snapshot captured the fork entity',
+      fs.readFileSync(path.join(real.preRestoreDir, 'entity-before-restore', 'lib', 'index.js'), 'utf8').includes('FORK'))
+    check('no leftover swap dirs',
+      !fs.existsSync(`${target}.restore-old-`) && fs.readdirSync(path.dirname(target)).every((n) => !n.includes('.restore-tmp-') && !n.includes('.restore-old-')),
+      JSON.stringify(fs.readdirSync(path.dirname(target))))
+
+    // ④ 幂等：再还原一次仍然成功（还原上游原物到上游原物）
+    const again = restoreEntity({ target, backupDir, archiveRoot, dry: false })
+    check('second restore is idempotent', again.ok === true)
+    check('entity still upstream', fs.readFileSync(path.join(target, 'lib', 'index.js'), 'utf8').includes('UPSTREAM'))
+  } catch (error) {
+    check('self-test ran without throwing', false, error instanceof Error ? error.message : String(error))
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true })
+  }
+  console.log(failures.length === 0 ? '\nrestore self-test: ALL CHECKS PASS' : `\nrestore self-test: ${failures.length} CHECK(S) FAILED`)
+  process.exit(failures.length === 0 ? EXIT.OK : EXIT.GATE)
+}
+
+// ── 正常路径 ─────────────────────────────────────────────────────────────────
+const pa = parseArgs(process.argv.slice(2), KNOWN_ARGS)
+if (!pa.ok) {
+  console.error(`[restore] ${describeUnknown(pa.unknown, KNOWN_ARGS)}`)
+  process.exit(EXIT.USAGE)
+}
+const dry = !!pa.flags['--dry-run']
+const archiveRoot = pa.values['--archive'] ?? process.env.DSH_ARCHIVE ?? path.join(process.cwd(), '_archive')
+const profileName = pa.values['--profile'] ?? 'web'
+const snapshots = findSnapshot(archiveRoot)
+
+if (pa.flags['--list']) {
+  console.log(snapshots.length === 0 ? `no upstream snapshots under ${archiveRoot}` : snapshots.join('\n'))
+  process.exit(snapshots.length === 0 ? 3 : EXIT.OK)
+}
+
+const rawTarget = pa.values['--target']
+if (!rawTarget) {
+  console.error('[restore] 缺少 --target <DSH_HOME>：本脚本没有默认目标（写死生产路径是明令禁止的）')
+  process.exit(EXIT.USAGE)
+}
+const home = path.resolve(rawTarget)
+const target = path.join(home, 'profiles', profileName, 'node_modules', 'dsh-memory')
+
+// ── 生产闸（R-060 · 2026-10-16 接入）──────────────────────────────────────────
+// 旧判据 = `home.toLowerCase() === path.resolve(defaultHome).toLowerCase()`：两个洞
+//   ① 只比"**等于**"默认 home ⇒ `--target <生产树内的子目录>` 一律放行（2026-10-16 实测：真把上游原物写进了
+//      `~\.dsh\<子目录>\profiles\...`，无人拦）；
+//   ② 只比**逻辑**字符串、不走 realpath ⇒ junction 跨面可绕（R-060 取证⑦ V7 卡形态）。
+// 新判据 = 「realpath + 逻辑路径双比」前缀判定：目标落在生产树（`$DSH_HOME`）内 ⇒
+//   真还原必须显式 `--allow-production`（否则 rc=2）；**dry-run 是第一道门** ⇒ 只读档不设闸（旧实现连
+//   `--dry-run` 打生产也拒 —— 那是误拦，本次一并修掉：只读档零写入，闸门不该拦计划）。
+const gate = gateProductionWrite({
+  targets: [{ path: home, label: '--target' }],
+  allowProduction: pa.flags['--allow-production'] === true,
+  dryRun: dry,
+  op: '还原',
+  reason: `dsh-memory-local restore --target ${home}${dry ? '（只读 dry-run）' : '（真还原）'}`,
+})
+if (!gate.ok) {
+  console.error(refuseLine(gate))
+  process.exit(gate.exitCode)   // 2（缺放行 = 用法错；与生态既有 --allow-production 口径一致）
+}
+
+if (snapshots.length === 0) {
+  console.error(`[restore] 在 ${archiveRoot} 下找不到含上游原物的 g24-s2a-memory-deploy-* 备份 —— 无还原源，拒绝动手。`)
+  process.exit(3)
+}
+const backupDir = snapshots.at(-1)
+
+console.log(`target   : ${target}`)
+console.log(`restore  : ${backupDir}\\official-entity`)
+console.log(`archive  : ${archiveRoot}`)
+if (!fs.existsSync(target)) console.log('[restore] 注意：目标实体当前不存在（将直接铺上游原物）')
+
+try {
+  const res = restoreEntity({ target, backupDir, archiveRoot, dry })
+  for (const a of res.actions) console.log(`  ${dry ? 'would ' : ''}${a}`)
+  if (dry) { console.log('\n[restore] dry-run：未改任何文件'); process.exit(EXIT.OK) }
+  console.log(`\n[restore] 已还原上游原物：${res.restoredFiles} 个文件（逐文件 sha 复核通过）`)
+  console.log(`[restore] 还原前实体快照：${res.preRestoreDir}\\entity-before-restore`)
+  console.log('[restore] 未重启任何 DSH。重新装上 fork：')
+  console.log(`  node ${path.join(path.dirname(fileURLToPath(import.meta.url)), 'deploy.mjs')} --target ${home}`)
+  process.exit(EXIT.OK)
+} catch (error) {
+  console.error(`[restore] FAIL ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(EXIT.GATE)
+}

package/dsh-memory-local/rollback-injector-fix.mjs

@@ -0,0 +1,166 @@
+/**
+ * rollback-injector-fix.mjs —— 冲刺600-M1《注入去重修复》的**一键回滚入口**。
+ *
+ * 回滚语义（本卡专属）：把生产实体 `dsh-memory` 的 `lib/injector.mjs`
+ * 从「修复后」退回「改动前」——**只动这一个文件**，不碰实体其余 13 个文件、不碰库、不碰 wiring。
+ *
+ * 锚（改动前后逐字节固定）：
+ *   BEFORE（改动前）: fadbec42e2311b7cc2f09109a5ca3ef34e761760a409a28a84704d179c538f9c  14,939 B
+ *   AFTER （改动后）: fceb32b48aa6a057ee8d1652e91522d6aab3daa60d7f1a10e784cd49d75b71ea  16,368 B
+ *
+ * 安全口径：
+ *   · **默认 dry-run**（只打印将要做的事 + 逐条校验，不写任何文件）；`--apply` 才真写。
+ *   · 写前把关：目标当前 sha 必须 == AFTER（否则说明实体已不是本卡交付的那一份 ⇒ fail-closed 拒绝，
+ *     避免把别人的改动误盖）。
+ *   · 写前把「当前实体」备份到 `<回滚点>\rollback-runs\<stamp>\`（本动作自身也可被回看）。
+ *   · 写后复核 sha == BEFORE，不等即报错（不回滚一半）。
+ *   · 目标 home = 本机默认 `~/.dsh`（生产）时必须显式 `--allow-production`。
+ *   · 默认写完后走 **P0 闸门** 请求重启（`request-restart.mjs`）；`--no-restart` 跳过。
+ *     ⚠️ 只请求、不裸杀进程；无守护鱼时本脚本**不碰** dsh。
+ *
+ * 用法：
+ *   node rollback-injector-fix.mjs --target <DSH_HOME> [--point <回滚点目录>] [--apply] [--no-restart] [--allow-production]
+ *   node rollback-injector-fix.mjs --status --target <DSH_HOME>      # 只读：当前实体是改动前/后/其它
+ *
+ * 退出码：0 = 成功（含 dry-run 通过 / 无需回滚） · 1 = 门禁失败 · 2 = 用法错误 · 3 = 重启请求失败
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+
+const BEFORE = { sha: 'fadbec42e2311b7cc2f09109a5ca3ef34e761760a409a28a84704d179c538f9c', bytes: 14939, label: '改动前（0.1.5 之前的老取事件面写法）' }
+const AFTER = { sha: 'fceb32b48aa6a057ee8d1652e91522d6aab3daa60d7f1a10e784cd49d75b71ea', bytes: 16368, label: '改动后（M1 修复：新面优先 + 老线回落）' }
+const ARCHIVE = process.env.DSH_ARCHIVE || path.join(process.cwd(), '_archive')
+const RESTART_CLI = process.env.DSH_RESTART_CLI || path.join(process.cwd(), 'tools', 'request-restart.mjs')
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
+const say = (s) => process.stdout.write(`${s}\n`)
+
+// ── 参数 ──────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const flag = (n) => argv.includes(`--${n}`)
+const valu = (n) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] ? argv[i + 1] : null }
+const USAGE = 'node rollback-injector-fix.mjs --target <DSH_HOME> [--point <dir>] [--apply] [--no-restart] [--allow-production] | --status'
+const known = new Set(['--apply', '--dry-run', '--no-restart', '--allow-production', '--status', '--help', '--target', '--point', '--reason'])
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i]
+  if (!a.startsWith('--')) continue
+  if (!known.has(a)) { say(`[rollback-m1] 未知参数 ${a}\n用法：${USAGE}`); process.exit(2) }
+  if ((a === '--target' || a === '--point' || a === '--reason') && !argv[i + 1]) { say(`[rollback-m1] ${a} 缺值\n用法：${USAGE}`); process.exit(2) }
+  if (a === '--target' || a === '--point' || a === '--reason') i += 1
+}
+if (flag('help') || argv.length === 0) { say(`用法：${USAGE}`); process.exit(argv.length === 0 ? 2 : 0) }
+
+const rawTarget = valu('target')
+if (!rawTarget) { say(`[rollback-m1] --target <DSH_HOME> 必填（没有默认目标）\n用法：${USAGE}`); process.exit(2) }
+const home = path.resolve(rawTarget)
+if (!fs.existsSync(home)) { say(`[rollback-m1] --target 不存在：${home}`); process.exit(2) }
+const defaultHome = path.join(os.homedir(), '.dsh')
+const isProduction = home.toLowerCase() === path.resolve(defaultHome).toLowerCase()
+if (isProduction && !flag('allow-production')) {
+  say(`[rollback-m1] 目标 ${home} 是本机默认 home（= 生产）；确认要动生产请显式追加 --allow-production。`)
+  process.exit(2)
+}
+const apply = flag('apply')
+const doRestart = !flag('no-restart')
+const statusOnly = flag('status')
+
+const targetFile = path.join(home, 'profiles', 'web', 'node_modules', 'dsh-memory', 'lib', 'injector.mjs')
+
+// ── 回滚点定位（before 快照） ──────────────────────────────────────────────────
+function findPoint() {
+  const explicit = valu('point')
+  if (explicit) {
+    const p = path.resolve(explicit)
+    const f = path.join(p, 'before', 'prod-entity', 'lib', 'injector.mjs')
+    return fs.existsSync(f) ? { dir: p, file: f } : null
+  }
+  if (!fs.existsSync(ARCHIVE)) return null
+  const dirs = fs.readdirSync(ARCHIVE)
+    .filter((n) => n.startsWith('m1-injector-fix-'))
+    .map((n) => path.join(ARCHIVE, n))
+    .sort()
+    .reverse()
+  for (const dir of dirs) {
+    const f = path.join(dir, 'before', 'prod-entity', 'lib', 'injector.mjs')
+    if (!fs.existsSync(f)) continue
+    if (sha256(fs.readFileSync(f)) === BEFORE.sha) return { dir, file: f }
+  }
+  return null
+}
+
+const point = findPoint()
+const currentBytes = fs.existsSync(targetFile) ? fs.readFileSync(targetFile) : null
+const currentSha = currentBytes ? sha256(currentBytes) : null
+const state = currentSha === AFTER.sha ? 'AFTER' : currentSha === BEFORE.sha ? 'BEFORE' : currentSha ? 'OTHER' : 'ABSENT'
+
+say('[rollback-m1] 冲刺600-M1 注入去重修复 · 一键回滚')
+say(`  target      : ${targetFile}`)
+say(`  home        : ${home}${isProduction ? '  ⚠ PRODUCTION HOME' : '  [non-default home]'}`)
+say(`  mode        : ${statusOnly ? 'status(只读)' : apply ? 'APPLY(真写)' : 'DRY-RUN(默认，不写)'}`)
+say(`  当前实体     : ${currentSha ? `${currentSha}  ${currentBytes.length} B` : '(文件不存在)'}`)
+say(`  状态         : ${state}  ${state === 'AFTER' ? '（= 本卡改动后，可回滚）' : state === 'BEFORE' ? '（= 改动前，已回滚/无需回滚）' : state === 'OTHER' ? '（⚠ 既不是改动前也不是改动后 ⇒ 拒绝覆盖，请人工确认）' : ''}`)
+say(`  回滚点       : ${point ? point.dir : '(未找到含 before/prod-entity/lib/injector.mjs 且 sha 命中改动前锚的回滚点)'}`)
+say(`  改动前锚     : ${BEFORE.sha}  ${BEFORE.bytes} B  ${BEFORE.label}`)
+say(`  改动后锚     : ${AFTER.sha}  ${AFTER.bytes} B  ${AFTER.label}`)
+if (point) {
+  const src = fs.readFileSync(point.file)
+  say(`  回滚源复核   : ${sha256(src)} ${src.length} B  ${sha256(src) === BEFORE.sha && src.length === BEFORE.bytes ? '✅ 与改动前锚逐字节相同' : '❌ 不一致（回滚源被污染 ⇒ 拒绝）'}`)
+}
+
+if (statusOnly) {
+  say(`[rollback-m1] status 结束（只读，零写入）。`)
+  process.exit(0)
+}
+
+// ── 门禁 ─────────────────────────────────────────────────────────────────────
+if (state === 'ABSENT') { say('[rollback-m1] 目标文件不存在 ⇒ 无法回滚（实体可能未部署）。'); process.exit(1) }
+if (state === 'BEFORE') { say('[rollback-m1] 当前已是改动前版本 ⇒ 无需回滚（零写入）。'); process.exit(0) }
+if (state === 'OTHER') { say('[rollback-m1] 目标 sha 既不是改动前也不是改动后 ⇒ fail-closed 拒绝覆盖（请人工确认后再动）。'); process.exit(1) }
+if (!point) { say('[rollback-m1] 找不到可信回滚点 ⇒ fail-closed 中止（零写入）。'); process.exit(1) }
+const srcBuf = fs.readFileSync(point.file)
+if (sha256(srcBuf) !== BEFORE.sha || srcBuf.length !== BEFORE.bytes) {
+  say('[rollback-m1] 回滚源与改动前锚不一致 ⇒ fail-closed 中止（零写入）。')
+  process.exit(1)
+}
+
+if (!apply) {
+  say('[rollback-m1] DRY-RUN 结论：门禁全过，可安全回滚。实际执行请追加 --apply。')
+  say(`  [dry-run] 将把 ${point.file} 覆盖到 ${targetFile}（${BEFORE.bytes} B）`)
+  say(`  [dry-run] 覆盖前会先把当前实体备份到 ${path.join(point.dir, 'rollback-runs', '<stamp>')}`)
+  say(`  [dry-run] 覆盖后会复核 sha == ${BEFORE.sha}`)
+  say(`  [dry-run] ${doRestart ? '随后走 P0 闸门请求重启' : '--no-restart：不请求重启'}`)
+  process.exit(0)
+}
+
+// ── 真回滚 ───────────────────────────────────────────────────────────────────
+const stamp = (() => { const d = new Date(); const p = (n) => String(n).padStart(2, '0'); return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}-${String(d.getMilliseconds()).padStart(3, '0')}` })()
+const runDir = path.join(point.dir, 'rollback-runs', stamp)
+fs.mkdirSync(runDir, { recursive: true })
+fs.writeFileSync(path.join(runDir, 'injector.before-rollback.mjs'), currentBytes)
+fs.writeFileSync(path.join(runDir, 'MANIFEST.json'), `${JSON.stringify({
+  at: new Date().toISOString(), target: targetFile, home, productionHome: isProduction,
+  before: { sha256: currentSha, bytes: currentBytes.length },
+  after: { sha256: BEFORE.sha, bytes: BEFORE.bytes },
+  source: point.file, note: '此次回滚动作自身的留痕：before = 回滚前实体，after = 回滚后应等于改动前锚。',
+}, null, 2)}\n`, 'utf8')
+say(`[rollback-m1] 回滚前实体已备份：${path.join(runDir, 'injector.before-rollback.mjs')}（sha ${currentSha}）`)
+
+fs.writeFileSync(targetFile, srcBuf)
+const afterSha = sha256(fs.readFileSync(targetFile))
+say(`[rollback-m1] 已覆盖：${targetFile}`)
+say(`[rollback-m1] 复核 sha = ${afterSha}  ${afterSha === BEFORE.sha ? '✅ 与改动前锚相同' : '❌ 不一致'}`)
+if (afterSha !== BEFORE.sha) { say('[rollback-m1] 回滚后复核失败 —— 请人工检查（备份与回滚源都在回滚点里）。'); process.exit(1) }
+
+if (!doRestart) { say('[rollback-m1] --no-restart：回滚完成，未请求重启（改动要生效需自行走 P0 闸门重启）。'); process.exit(0) }
+
+// ── P0 闸门重启 ──────────────────────────────────────────────────────────────
+if (!fs.existsSync(RESTART_CLI)) { say(`[rollback-m1] 找不到重启闸门：${RESTART_CLI} ⇒ 未请求重启（回滚已生效于文件，等下次重启）。`); process.exit(3) }
+const reason = valu('reason') ?? `冲刺600-M1 回滚：dsh-memory 的 lib/injector.mjs 已退回改动前（${AFTER.sha.slice(0, 8)}→${BEFORE.sha.slice(0, 8)}）`
+const r = spawnSync(process.execPath, [RESTART_CLI, '--reason', reason], { encoding: 'utf8', windowsHide: true })
+say(`[rollback-m1] 重启闸门输出：\n${(r.stdout ?? '').trim()}`)
+if (r.status !== 0) { say(`[rollback-m1] 重启请求失败（rc=${r.status}）：${(r.stderr ?? '').trim().slice(0, 300)}`); process.exit(3) }
+say('[rollback-m1] 回滚完成 + 已走 P0 闸门请求重启。')
+process.exit(0)

package/dsh-memory-local/src/bridge.mjs

@@ -0,0 +1,108 @@
+/**
+ * FORK-EDIT(2026-09-21): 回环编码桥客户端（方案 §3.1 编码通道契约 / §3.4 fail-open）
+ *
+ * 契约（S1 已实测，见 S1 交付 §3.7）：
+ *   · 桥只绑 127.0.0.1，端口从 8201 起、被占则 +1 顺延（serve.mjs，最多 10 次）
+ *   · GET  /health → { ready, modelLoading, model, dim, port, ... }
+ *   · POST /encode {"texts":[…]} → { vectors: [[…]], model, dim }
+ *
+ * 本模块的铁律：
+ *   ① 桥不在 / 未就绪 / 超时 / 任何异常 ⇒ 抛错，由调用方 fail-open（绝不阻塞对话）；
+ *   ② **超时不排队**（方案 §3.4：发出即设 250 ms 超时并放弃，桥侧不做补偿）——
+ *      单飞守卫：上一发未回则本轮直接跳过，不堆叠请求；
+ *   ③ 只允许回环地址（非 127.0.0.1 / localhost / ::1 一律拒，绝不给桥改绑非回环的机会）；
+ *   ④ 探活结果（含**失败**）按 TTL 缓存 ⇒ 桥不在时不会每轮都连打 10 个端口。
+ */
+const LOOPBACK = /^(127\.0\.0\.1|localhost|::1)$/;
+
+export function createBridgeClient({
+  host = '127.0.0.1',
+  port = 8201,
+  portScanMax = 10,
+  encodeTimeoutMs = 250,
+  healthTimeoutMs = 120,
+  healthTtlMs = 10000,
+} = {}) {
+  if (!LOOPBACK.test(String(host))) {
+    throw new Error(`编码桥只允许回环地址（方案 §3.1），收到 host=${host}`);
+  }
+
+  let cache = null; // { ok, port, dim, model, at, error }
+  let inFlight = false;
+  let encodeCalls = 0;
+
+  const fetchJson = async (url, init, ms) => {
+    const res = await fetch(url, { ...init, signal: AbortSignal.timeout(ms) });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  };
+
+  /** 探活：从 port 起顺延，找第一个 ready 的桥；成功与失败都缓存 TTL。 */
+  const probe = async (force = false) => {
+    const now = Date.now();
+    if (!force && cache && now - cache.at < healthTtlMs) return cache;
+    let lastErr = 'unknown';
+    for (let p = port; p <= port + portScanMax; p += 1) {
+      try {
+        const h = await fetchJson(`http://${host}:${p}/health`, {}, healthTimeoutMs);
+        cache = {
+          ok: Boolean(h && h.ready),
+          port: p,
+          dim: Number(h && h.dim) || 0,
+          model: (h && h.model) || null,
+          modelLoading: Boolean(h && h.modelLoading),
+          at: Date.now(),
+          error: h && h.ready ? null : 'model-not-ready',
+        };
+        return cache;
+      } catch (e) {
+        lastErr = String(e && e.message ? e.message : e);
+      }
+    }
+    cache = { ok: false, port: null, dim: 0, model: null, at: Date.now(), error: lastErr };
+    return cache;
+  };
+
+  const encode = async (text) => {
+    const h = await probe();
+    if (!h || !h.ok) throw new Error(`编码桥不可用：${(h && h.error) || 'not ready'}`);
+    if (inFlight) throw new Error('编码桥上一发未返回（超时不排队，本轮跳过）');
+    inFlight = true;
+    try {
+      encodeCalls += 1;
+      const out = await fetchJson(
+        `http://${host}:${h.port}/encode`,
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ texts: [String(text ?? '')] }),
+        },
+        encodeTimeoutMs,
+      );
+      const vec = out && out.vectors && out.vectors[0];
+      if (!vec) throw new Error('编码桥返回空向量');
+      return Float32Array.from(vec);
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  return {
+    kind: 'bridge',
+    host,
+    port,
+    describe: () => ({ kind: 'bridge', host, port, encodeTimeoutMs, healthTtlMs, encodeCalls }),
+    probe,
+    health: () => probe(),
+    stats: () => ({ encodeCalls, inFlight }),
+    get dim() {
+      return cache ? cache.dim : 0;
+    },
+    get modelId() {
+      return cache ? cache.model : null;
+    },
+    encode,
+    // 桥一次一条（召回只需 1 条查询向量）
+    encodeBatch: async (texts) => Promise.all(texts.map((t) => encode(t))),
+  };
+}