agentworkshop 0.7.27 → 0.7.34

package/scripts/test-log-flooding.mjs

@@ -0,0 +1,160 @@
+/**
+ * 回归测试 —— 日志同指纹限流(server/services/workshop/logger.ts)。
+ *
+ * P0 背景:daq/drivers.ts 的 OPC UA securityMode=None 告警原先每次建连写一行,
+ * 实测约 7 行/秒把生产日志灌到 18MB,且归一化后 100% 是同一句,真实错误被淹没。
+ * 覆盖:同指纹洪水折叠 + 抑制摘要、异指纹不误伤、窗口关闭自动结算、指纹表有界、
+ * 输出可注入 sink 且既有 debug/info/warn/error 语义不变(生产 stdout/stderr 行为不变)。
+ *
+ * 运行:node scripts/test-log-flooding.mjs(退出码非 0 = 有失败)
+ * 注:logger.ts 经 ./settings 使用 '@/' 别名,纯 node 运行需注册省略扩展名/别名解析钩子
+ * (与 scripts/_audit/run.mjs 同一机制;本沙箱内 tsx 会因 spawn 被拒而不可用)。
+ */
+import { register } from 'node:module'
+
+register(new URL('./_audit/ts-resolve-hook.mjs', import.meta.url).href)
+
+// 级别固定 debug:限流断言只关心"是否输出",不受运行环境 log.level(默认 info)影响
+process.env.AW_LOG_LEVEL = 'debug'
+
+const { createLogger, THROTTLE_MAX_FINGERPRINTS, THROTTLE_WINDOW_MS } = await import('../server/services/workshop/logger.ts')
+
+let pass = 0
+let fail = 0
+function check(name, ok, detail = '') {
+  if (ok) {
+    pass += 1
+    console.log('  PASS  ' + name)
+    return
+  }
+  fail += 1
+  console.log('  FAIL  ' + name + (detail ? '  — ' + detail : ''))
+}
+
+/** 自有 sink(需求 4):out ← 非 error/warn,err ← error/warn */
+function mkSink() {
+  const out = []
+  const err = []
+  return { out, err, sink: { out: line => out.push(line), err: line => err.push(line) } }
+}
+
+const all = s => [...s.out, ...s.err].map(line => JSON.parse(line))
+const text = s => all(s).map(line => String(line.msg))
+const count = s => s.out.length + s.err.length
+
+console.log('\n━━━ 1. 同指纹洪水:1000 条 → 窗口内 1 行 + 抑制摘要 ━━━')
+{
+  const s = mkSink()
+  const log = createLogger('flood.same', s.sink)
+  for (let i = 0; i < 1000; i++) {
+    log.warnThrottled(`[daq-opcua] WARN:节点 endpoint=opc.tcp://10.0.0.${i}:4840 使用 securityMode=None,耗时 ${i} ms`)
+  }
+  check('窗口内只输出首条', count(s) === 1, 'lines=' + count(s))
+  log.flushThrottled(true)
+  const lines = all(s)
+  const summary = text(s).find(m => m.includes('被抑制'))
+  check('总输出 ≤ 5 行', lines.length <= 5, 'lines=' + lines.length)
+  check('窗口关闭补一条抑制摘要', Boolean(summary), text(s).join(' | '))
+  check('摘要报告剩余 999 条', Boolean(summary && summary.includes('被抑制 999 条')), String(summary))
+  check('摘要带 scope 且为 [log-throttle] 标记', Boolean(summary && summary.startsWith('[log-throttle]') && summary.includes('scope=flood.same')), String(summary))
+  check('摘要与业务消息同流(warn → err)', s.err.some(line => line.includes('被抑制')))
+  log.flushThrottled(true)
+  check('无新增抑制时不重复补摘要', count(s) === lines.length, 'lines=' + count(s))
+  const first = lines.find(line => String(line.msg).startsWith('[daq-opcua] WARN:节点 endpoint='))
+  check('首条为 warn 级且消息文本未被改写',
+    Boolean(first && first.level === 'warn' && first.msg.startsWith('[daq-opcua] WARN:节点 endpoint=opc.tcp://10.0.0.0:4840')),
+    first ? first.msg : '首条缺失')
+  check('行结构不变(t/level/scope/msg)', Boolean(first && typeof first.t === 'string' && first.scope === 'flood.same'))
+}
+
+console.log('\n━━━ 2. 不同 scope / 明显不同文本:不得被抑制 ━━━')
+{
+  const s = mkSink()
+  const a = createLogger('flood.scope-a', s.sink)
+  const b = createLogger('flood.scope-b', s.sink)
+  const distinct = ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+  for (const word of distinct) a.warnThrottled('同文本不同作用域 ' + word)
+  for (const word of distinct) b.warnThrottled('同文本不同作用域 ' + word)
+  check('不同 scope 的同文本 10 条全部输出', count(s) === 10, 'lines=' + count(s))
+  check('无抑制摘要', !text(s).some(m => m.includes('被抑制')))
+  const c = createLogger('flood.scope-c', s.sink)
+  for (const word of distinct) c.warnThrottled('不同文本 ' + word)
+  check('同 scope 不同文本不被折叠', count(s) === 15, 'lines=' + count(s))
+  c.warnThrottled('不同文本 alpha')
+  check('同 scope 同文本重复才折叠', count(s) === 15, 'lines=' + count(s))
+  const d = createLogger('flood.scope-d', s.sink)
+  d.warnThrottled('数字变化 poll 1234 ms')
+  d.warnThrottled('数字变化 poll 5678 ms')
+  check('数字串归一化后同指纹(第二条折叠)', count(s) === 16, 'lines=' + count(s))
+  d.warnThrottled('ISO 2026-09-11T03:12:22.466Z 同文案')
+  d.warnThrottled('ISO 2027-01-02T04:00:00.000Z 同文案')
+  check('ISO 时间戳归一化后同指纹(第二条折叠)', count(s) === 17, 'lines=' + count(s))
+}
+
+console.log('\n━━━ 3. 窗口关闭自动结算:摘要 + 新窗口首条全量 ━━━')
+{
+  const s = mkSink()
+  const log = createLogger('flood.window', s.sink)
+  for (let i = 0; i < 5; i++) log.warnThrottled('窗口测试 poll ' + i + ' ms')
+  check('窗口内 1 行', count(s) === 1, 'lines=' + count(s))
+  const realNow = Date.now
+  Date.now = () => realNow() + THROTTLE_WINDOW_MS + 1000
+  try {
+    log.warnThrottled('窗口测试 poll 9999 ms')
+  }
+  finally {
+    Date.now = realNow
+  }
+  const lines = all(s)
+  const summary = text(s).find(m => m.includes('被抑制'))
+  check('窗口关闭后共 3 行(首条 + 摘要 + 新首条)', lines.length === 3, 'lines=' + lines.length)
+  check('自动摘要报告 4 条', Boolean(summary && summary.includes('被抑制 4 条')), String(summary))
+  check('新窗口首条全量输出', text(s).some(m => m === '窗口测试 poll 9999 ms'))
+  check('已结算窗口计数=1', log.throttleStats().windows === 1, 'windows=' + log.throttleStats().windows)
+  check('已结算指纹不再占表', log.throttleStats().size === 1, 'size=' + log.throttleStats().size)
+}
+
+console.log('\n━━━ 4. 指纹表有界:5000 个不同指纹不得越界 ━━━')
+{
+  const s = mkSink()
+  const log = createLogger('flood.bounded', s.sink)
+  let maxSeen = 0
+  let over = 0
+  for (let i = 0; i < 5000; i++) {
+    // 无数字文本:确保 5000 条归为 5000 个不同指纹
+    log.warnThrottled('指纹 ' + String.fromCharCode(0x4e00 + i))
+    const size = log.throttleStats().size
+    if (size > maxSeen) maxSeen = size
+    if (size > THROTTLE_MAX_FINGERPRINTS) over += 1
+  }
+  const st = log.throttleStats()
+  check('表大小恒 ≤ 上限', over === 0 && maxSeen <= THROTTLE_MAX_FINGERPRINTS, `max=${maxSeen} cap=${THROTTLE_MAX_FINGERPRINTS}`)
+  check('表顶到上限(容量被用满)', st.size === THROTTLE_MAX_FINGERPRINTS, 'size=' + st.size)
+  check('发生过逐出(不是整体 clear)', st.evictions > 0, 'evictions=' + st.evictions)
+  check('5000 个不同指纹均全量输出(未误折叠)', count(s) === 5000, 'lines=' + count(s))
+}
+
+console.log('\n━━━ 5. 既有 debug/info/warn/error 语义不变 ━━━')
+{
+  const s = mkSink()
+  const log = createLogger('flood.base', s.sink)
+  log.debug('debug')
+  log.info('info')
+  log.warn('warn')
+  log.error('error')
+  const lines = all(s)
+  check('四法各输出一次(不经限流)', lines.length === 4, 'lines=' + lines.length)
+  check('debug/info → out,warn/error → err', s.out.length === 2 && s.err.length === 2, `out=${s.out.length} err=${s.err.length}`)
+  log.warn('warn')
+  check('基础 warn 重复不折叠', count(s) === 5, 'lines=' + count(s))
+  check('基础四法不写限流表', log.throttleStats().size === 0, 'size=' + log.throttleStats().size)
+  const warnLine = all(s).find(line => line.level === 'warn')
+  check('scope/msg 原样落盘', Boolean(warnLine && warnLine.scope === 'flood.base' && warnLine.msg === 'warn'))
+  const extra = createLogger('flood.api', mkSink().sink)
+  check('限流 API 为显式 opt-in 方法',
+    typeof extra.rateLimited === 'function' && typeof extra.warnThrottled === 'function'
+    && typeof extra.flushThrottled === 'function' && typeof extra.throttleStats === 'function')
+}
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-lru.mjs

@@ -0,0 +1,78 @@
+/** 回归测试 —— 有界 LRU(shared/lru.mjs)。运行: node scripts/test-lru.mjs */
+import { LruMap } from '../shared/lru.mjs'
+
+let pass = 0, fail = 0
+const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+
+console.log('\n━━━ 1. 容量与逐出 ━━━')
+{
+  const l = new LruMap(3)
+  l.set('a', 1); l.set('b', 2); l.set('c', 3)
+  check('未超限 size=3', l.size === 3)
+  l.set('d', 4)
+  check('超限后 size 仍为 3', l.size === 3, 'size=' + l.size)
+  check('最旧的 a 被逐出', !l.has('a'))
+  check('最新的 d 在', l.has('d'))
+  check('逐出计数=1', l.evictions === 1)
+}
+
+console.log('\n━━━ 2. 访问提升(LRU 语义核心) ━━━')
+{
+  const l = new LruMap(3)
+  l.set('a', 1); l.set('b', 2); l.set('c', 3)
+  l.get('a')            // a 变最新
+  l.set('d', 4)         // 应逐出 b(而非 a)
+  check('被访问过的 a 存活', l.has('a'))
+  check('未访问的 b 被逐出', !l.has('b'))
+  check('新写入的 d 在', l.has('d'))
+}
+
+console.log('\n━━━ 3. getOrSet 单入口 ━━━')
+{
+  const l = new LruMap(2)
+  let computed = 0
+  const v1 = l.getOrSet('k', () => { computed++; return 'V' })
+  const v2 = l.getOrSet('k', () => { computed++; return 'V' })
+  check('值正确', v1 === 'V' && v2 === 'V')
+  check('只计算一次(二次命中缓存)', computed === 1, 'computed=' + computed)
+  check('命中数=1', l.hits === 1, 'hits=' + l.hits)
+}
+
+console.log('\n━━━ 4. 无界增长已被消除(对比旧写法) ━━━')
+{
+  const l = new LruMap(100)
+  for (let i = 0; i < 100000; i++) l.set('k' + i, i)
+  check('插入 10 万后 size 恒为 100', l.size === 100, 'size=' + l.size)
+  check('逐出总数 = 99900', l.evictions === 99900, 'evictions=' + l.evictions)
+  check('最后写入的仍在', l.get('k99999') === 99999)
+}
+
+console.log('\n━━━ 5. 对比 clear() 抖动:LRU 不应造成全量穿透 ━━━')
+{
+  const l = new LruMap(500)
+  for (let i = 0; i < 500; i++) l.set('k' + i, i)
+  // 旧实现:第 501 次写入触发 clear(),之后 500 个条目全部回源
+  l.set('k500', 500)   // 触发一次逐出:k0 出局
+  let survived = 0
+  for (let i = 0; i < 500; i++) if (l.has('k' + i)) survived++
+  // 500 条候选中恰好逐出 1 条 → 存活 499(旧 clear() 实现此处存活 0)
+  check('仅逐出 1 条,其余 499 条仍在(旧 clear() 会剩 0)', survived === 499, 'survived=' + survived)
+}
+
+console.log('\n━━━ 6. 边界与回调 ━━━')
+{
+  let evictedKeys = []
+  const l = new LruMap(2, (k) => evictedKeys.push(k))
+  l.set('a', 1); l.set('b', 2); l.set('c', 3)
+  check('onEvict 收到逐出键', evictedKeys.join(',') === 'a', evictedKeys.join(','))
+  check('delete 可用', l.delete('b') === true && !l.has('b'))
+  check('clear 后为空', (l.clear(), l.size === 0))
+  let threw = false
+  try { new LruMap(0) } catch { threw = true }
+  check('max<1 抛错', threw)
+  const s = l.stats()
+  check('stats 形状正确', typeof s.hitRate === 'number' && s.max === 2)
+}
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-memory-month-query.mjs

@@ -0,0 +1,62 @@
+/**
+ * 回归测试 —— 记忆反思查询下推(P1-3)
+ * 断言:listByAgentKindMonth / countByAgentKindMonth 与「全量拉取 + JS filter」结果完全一致,
+ * 且跨月/跨年边界正确。
+ * 运行: npx tsx scripts/test-memory-month-query.mjs
+ */
+import { DatabaseSync } from 'node:sqlite'
+import { readFileSync } from 'node:fs'
+import { createMemoryRepo } from '../server/services/workshop/db/memory.repo.ts'
+
+let pass = 0, fail = 0
+const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+
+// 用真实 schema 建库:保证测试与生产表结构(索引/触发器/唯一约束)完全一致
+const db = new DatabaseSync(':memory:')
+const schemaSql = readFileSync(new URL('../server/services/workshop/db/schema.sql', import.meta.url), 'utf8')
+db.exec(schemaSql)
+
+const repo = createMemoryRepo(db)
+const AGENT = 'a1'
+// 直接写主表以便精确控制 created_at(upsert 不接受时间覆盖)
+// 先建 channel(FK 约束),再插记忆行
+db.prepare(`INSERT INTO channels (id, name, created_at, updated_at) VALUES ('c1','t',?,?)`)
+  .run(new Date().toISOString(), new Date().toISOString())
+const ins = db.prepare(
+  `INSERT INTO agent_memories (id, channel_id, agent_id, kind, title, title_fts, content, importance, dedup_key, access_count, created_at)
+   VALUES (?, 'c1', ?, ?, ?, ?, ?, 1, ?, 0, ?)`,
+)
+for (const [id, kind, at] of [
+  ['m1', 'episodic-task', '2026-09-01T00:00:00.000Z'],
+  ['m2', 'episodic-task', '2026-09-15T12:00:00.000Z'],
+  ['m3', 'episodic-task', '2026-09-30T23:59:59.000Z'],
+  ['m4', 'episodic-task', '2026-10-01T00:00:00.000Z'],   // 下月首刻,必须排除
+  ['m5', 'episodic-session', '2026-09-10T00:00:00.000Z'], // 不同 kind,必须排除
+  ['m6', 'episodic-task', '2025-12-31T23:00:00.000Z'],    // 去年 12 月
+  ['m7', 'episodic-task', '2026-01-01T00:00:00.000Z'],
+]) {
+  ins.run(id, AGENT, kind, id, id, id, id, at)
+}
+// 另一 agent 的行不得串入
+ins.run('other1', 'a2', 'episodic-task', 'o', 'o', 'o', 'o', '2026-09-05T00:00:00.000Z')
+
+console.log('\n━━━ 1. 与全量 JS filter 语义一致 ━━━')
+const all = repo.listByAgentWithRowid(AGENT, 1_000_000)
+for (const month of ['2026-09', '2026-10', '2025-12', '2026-01', '2027-01']) {
+  const expect = all.filter(r => r.kind === 'episodic-task' && r.createdAt.slice(0, 7) === month).map(r => r.id).sort()
+  const got = repo.listByAgentKindMonth(AGENT, 'episodic-task', month).map(r => r.id).sort()
+  check(`${month}: 行集一致 [${expect.join(',')}]`, JSON.stringify(expect) === JSON.stringify(got), `got [${got.join(',')}]`)
+  check(`${month}: 计数一致 (${expect.length})`, repo.countByAgentKindMonth(AGENT, 'episodic-task', month) === expect.length)
+}
+
+console.log('\n━━━ 2. 边界正确性 ━━━')
+const sep = repo.listByAgentKindMonth(AGENT, 'episodic-task', '2026-09').map(r => r.id)
+check('9 月含首日 m1', sep.includes('m1'))
+check('9 月含末日 23:59:59 的 m3', sep.includes('m3'))
+check('9 月不含 10-01T00:00:00 的 m4', !sep.includes('m4'))
+check('9 月不含 session 类 m5', !sep.includes('m5'))
+check('9 月共 3 条', sep.length === 3, 'len=' + sep.length)
+check('12 月跨年查询正确', repo.listByAgentKindMonth(AGENT, 'episodic-task', '2025-12').map(r => r.id).join(',') === 'm6')
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-plugin-hardening.mjs

@@ -0,0 +1,45 @@
+/**
+ * 回归测试 —— 插件宿主加固(P0-2 路径包含判定 + P0-1 回滚所需的路由卸下能力)
+ * 运行: node scripts/test-plugin-hardening.mjs
+ * 退出码: 0 全通过 / 1 有失败
+ *
+ * 说明:半注册回滚(P0-1)的端到端验证需要 Nitro 运行时(host.mjs 依赖 @/ 别名),
+ * 由 scripts/test-plugin-live.mjs 打真实服务器完成。
+ */
+import { isPathInside, createRouteTable } from '../sdk/context.mjs'
+
+let pass = 0, fail = 0
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  PASS  ${name}`) }
+  else { fail++; console.log(`  FAIL  ${name}${detail ? '  — ' + detail : ''}`) }
+}
+
+console.log('\n━━━ 1. 路径包含判定(P0-2) ━━━')
+{
+  const d = 'C:/repo/server/plugins-builtin/rag-bridge'
+  check('目录内文件 → 允许', isPathInside(d, d + '/client.mjs') === true)
+  check('目录自身 → 允许', isPathInside(d, d) === true)
+  check('同前缀兄弟目录 → 拒绝(旧 startsWith 实现会放行)', isPathInside(d, 'C:/repo/server/plugins-builtin/rag-bridge-evil/x.mjs') === false)
+  check('../ 逃逸到仓库根 → 拒绝', isPathInside(d, 'C:/repo/.env') === false)
+  check('../ 逃逸到上级 → 拒绝', isPathInside(d, 'C:/repo/server/plugins-builtin/other.mjs') === false)
+  check('含 .. 的相对写法仍判定为内', isPathInside(d, d + '/sub/../client.mjs') === true)
+}
+
+console.log('\n━━━ 2. 路由表按插件卸下(P0-1 回滚所需) ━━━')
+{
+  const t = createRouteTable()
+  t.register('alpha', 'GET', '/a', () => 1)
+  t.register('alpha', 'POST', '/b', () => 2)
+  t.register('beta', 'GET', '/c', () => 3)
+  check('注册后 size=3', t.size === 3, 'size=' + t.size)
+  check('byPlugin(alpha) 2 条', t.byPlugin('alpha').length === 2)
+  const removed = t.unregisterPlugin('alpha')
+  check('unregisterPlugin 返回 2', removed === 2, 'removed=' + removed)
+  check('alpha 路由已清空', t.byPlugin('alpha').length === 0)
+  check('beta 路由不受影响', t.byPlugin('beta').length === 1)
+  check('resolve(alpha) 为 null', t.resolve('alpha', 'GET', '/a') === null)
+  check('unregisterPlugin 幂等(再调返回 0)', t.unregisterPlugin('alpha') === 0)
+}
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-rollback-index.mjs

@@ -0,0 +1,79 @@
+/**
+ * 回归 + 性能测试 —— DCW 回滚账本索引化(P1-8/P1-9)
+ * 验证:索引版与原「逆序全扫」版**结果完全一致**,且热路径显著更快。
+ * 运行: node scripts/test-rollback-index.mjs
+ */
+import { RecipeRollBackRepo } from '../server/services/workshop/dcw/recipe-rollback.repo.ts'
+
+let pass = 0, fail = 0
+const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+
+// ---- 参照实现:旧版线性全扫语义 ----
+const ref = {
+  lastAnchorOf: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) if (anchors[i].nodeId === nodeId) return anchors[i]; return undefined },
+  lastStableAnchor: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId === nodeId && a.prevValue != null && a.prevValue !== a.newValue) return a } return undefined },
+  lastStableBefore: (anchors, nodeId, atMs) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId !== nodeId || a.prevValue == null || a.prevValue === a.newValue) continue; if (Date.parse(a.at) <= atMs) return a } return undefined },
+  lastRollbackAnchor: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId === nodeId && a.source === 'rollback') return a } return undefined },
+}
+
+const repo = new RecipeRollBackRepo()
+const NODES = ['n-a', 'n-b', 'n-c']
+const N = 3000
+const t0 = Date.now()
+for (let i = 0; i < N; i++) {
+  const nodeId = NODES[i % NODES.length]
+  const prev = i % 7 === 0 ? null : i - 1          // 制造 prevValue==null 的锚
+  const same = i % 11 === 0                        // 制造 prevValue==newValue 的锚
+  repo.appendAnchor({
+    nodeId,
+    prevValue: prev,
+    newValue: same ? prev : i,
+    source: i % 13 === 0 ? 'rollback' : 'agent',
+    lineId: 'line-1',
+    at: new Date(Date.parse('2026-01-01T00:00:00Z') + i * 1000).toISOString(),
+  })
+}
+console.log(`\n写入 ${N} 锚耗时 ${Date.now() - t0}ms`)
+
+console.log('\n━━━ 1. 索引版与线性扫描语义一致 ━━━')
+const all = repo.listAnchors({ limit: N + 10 })   // 正序取回全部(倒序后再 reverse)
+const anchorsAsc = [...all].reverse()
+for (const nodeId of NODES) {
+  const a1 = repo.lastAnchorOf(nodeId), a2 = ref.lastAnchorOf(anchorsAsc, nodeId)
+  check(`lastAnchorOf(${nodeId}) 一致`, a1?.id === a2?.id, `${a1?.id} vs ${a2?.id}`)
+  const s1 = repo.lastStableAnchor(nodeId), s2 = ref.lastStableAnchor(anchorsAsc, nodeId)
+  check(`lastStableAnchor(${nodeId}) 一致`, s1?.id === s2?.id, `${s1?.id} vs ${s2?.id}`)
+  const r1 = repo.lastRollbackAnchor(nodeId), r2 = ref.lastRollbackAnchor(anchorsAsc, nodeId)
+  check(`lastRollbackAnchor(${nodeId}) 一致`, r1?.id === r2?.id, `${r1?.id} vs ${r2?.id}`)
+  // 取该节点锚中位时刻
+  const nodeAnchors = anchorsAsc.filter(a => a.nodeId === nodeId)
+  const midMs = Date.parse(nodeAnchors[Math.floor(nodeAnchors.length / 2)].at)
+  const b1 = repo.lastStableBefore(nodeId, midMs), b2 = ref.lastStableBefore(anchorsAsc, nodeId, midMs)
+  check(`lastStableBefore(${nodeId}, mid) 一致`, b1?.id === b2?.id, `${b1?.id} vs ${b2?.id}`)
+}
+
+console.log('\n━━━ 2. open 记录索引 ━━━')
+const rec = repo.insertRecord({ nodeId: 'n-a', status: 'open', policy: 'auto_rollback', setAt: new Date().toISOString(), params: [], lineId: 'line-1' })
+check('openRecordOf 命中', repo.openRecordOf('n-a')?.id === rec.id)
+check('listOpenRecords 含该条', repo.listOpenRecords().some(r => r.id === rec.id))
+repo.updateRecord(rec.id, { status: 'judged' })
+check('状态转 judged 后 openRecordOf 失效', repo.openRecordOf('n-a') === undefined)
+check('listOpenRecords 不含已关闭记录', !repo.listOpenRecords().some(r => r.id === rec.id))
+const rec2 = repo.insertRecord({ nodeId: 'n-b', status: 'open', policy: 'auto_rollback', setAt: new Date().toISOString(), params: [], lineId: 'line-1' })
+check('新 open 可再次命中', repo.openRecordOf('n-b')?.id === rec2.id)
+const s = repo.stats()
+check('stats.open 与索引一致', s.open === repo.listOpenRecords().length, `${s.open} vs ${repo.listOpenRecords().length}`)
+
+console.log('\n━━━ 3. 热路径性能(索引 vs 线性) ━━━')
+const ITER = 20000
+let t = Date.now()
+for (let i = 0; i < ITER; i++) repo.lastStableAnchor(NODES[i % 3])
+const indexedMs = Date.now() - t
+t = Date.now()
+for (let i = 0; i < ITER; i++) ref.lastStableAnchor(anchorsAsc, NODES[i % 3])
+const linearMs = Date.now() - t
+console.log(`  索引 ${indexedMs}ms  vs  线性 ${linearMs}ms  (${(linearMs / Math.max(indexedMs, 1)).toFixed(1)}x)`)
+check('索引版不慢于线性版', indexedMs <= linearMs, `${indexedMs} vs ${linearMs}`)
+
+console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-sdk-surface.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// ============================================================
+// test-sdk-surface.mjs — SDK 类型声明 / package.json 出口面 防漂移守卫
+// ------------------------------------------------------------
+// 断言三件事(任一失败 → exit 1):
+//   ① 类型声明里列出的生命周期事件集合 == sdk/lifecycle.mjs 运行时集合
+//      (LIFECYCLE_EVENTS 与 CLIENT_EVENTS 各自比对:
+//       sdk/index.d.mts 的 readonly 元组字面量 vs 运行时 Object.freeze 数组)
+//   ② sdk/client.d.mts 存在
+//   ③ package.json 每个 exports 条目的 types / default 目标文件都真实存在
+// 用法: node scripts/test-sdk-surface.mjs
+// ============================================================
+import { readFileSync, existsSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(HERE, '..')
+
+let failures = 0
+const pass = (msg) => console.log(`  ✔ ${msg}`)
+const fail = (msg) => { failures += 1; console.error(`  ✘ ${msg}`) }
+
+/** 从 .d.mts 源码抽取 `export declare const <NAME>: readonly [...]` 的字面量集合 */
+function extractTuple(file, name) {
+  const src = readFileSync(file, 'utf8')
+  // 允许跨行;匹配 declare const NAME: readonly [ ... ]
+  const re = new RegExp(`export declare const ${name}\\s*:\\s*readonly\\s*\\[([\\s\\S]*?)\\]`)
+  const m = src.match(re)
+  if (!m) return null
+  return m[1]
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(s => {
+      const q = s.match(/^'(.*)'$/) ?? s.match(/^"(.*)"$/)
+      return q ? q[1] : s
+    })
+}
+
+/** 集合并集比较(顺序无关,但重复也要能发现) */
+function sameSet(a, b) {
+  if (a.length !== b.length) return false
+  const sa = [...new Set(a)].sort()
+  const sb = [...new Set(b)].sort()
+  return sa.length === sb.length && sa.every((v, i) => v === sb[i])
+}
+
+const fmt = arr => JSON.stringify(arr)
+
+// ---------- ① 生命周期事件清单:类型 == 运行时 ----------
+console.log('\n[1/3] 生命周期事件清单(类型声明 vs 运行时)')
+const { LIFECYCLE_EVENTS, CLIENT_EVENTS } = await import('../sdk/lifecycle.mjs')
+const indexDts = join(ROOT, 'sdk', 'index.d.mts')
+
+for (const [name, runtime] of [['LIFECYCLE_EVENTS', [...LIFECYCLE_EVENTS]], ['CLIENT_EVENTS', [...CLIENT_EVENTS]]]) {
+  const declared = extractTuple(indexDts, name)
+  if (!declared) {
+    fail(`${name}: sdk/index.d.mts 未找到 'export declare const ' + name + ': readonly [...]' 声明`)
+    continue
+  }
+  if (sameSet(declared, runtime)) {
+    pass(`${name}: 类型声明与运行时一致(${runtime.length} 项)`)
+  }
+  else {
+    const missing = runtime.filter(e => !declared.includes(e))
+    const extra = declared.filter(e => !runtime.includes(e))
+    fail(`${name}: 类型声明与运行时漂移`)
+    if (missing.length) console.error(`      类型缺失(运行时独有): ${fmt(missing)}`)
+    if (extra.length) console.error(`      类型多余(已在运行时移除): ${fmt(extra)}`)
+    console.error(`      运行时 = ${fmt(runtime)}`)
+    console.error(`      类型声明 = ${fmt(declared)}`)
+  }
+}
+
+// 额外守卫:确保由 sdk/index.mjs 转出的运行时清单与 lifecycle.mjs 同源
+const indexMjs = await import('../sdk/index.mjs')
+if (sameSet([...indexMjs.LIFECYCLE_EVENTS], [...LIFECYCLE_EVENTS])) {
+  pass('sdk/index.mjs 转出的 LIFECYCLE_EVENTS 与 lifecycle.mjs 同源')
+}
+else {
+  fail('sdk/index.mjs 转出的 LIFECYCLE_EVENTS 与 lifecycle.mjs 不一致')
+}
+
+// ---------- ② sdk/client.d.mts 存在 ----------
+console.log('\n[2/3] sdk/client.d.mts 存在性')
+const clientDts = join(ROOT, 'sdk', 'client.d.mts')
+if (existsSync(clientDts) && statSync(clientDts).isFile()) {
+  pass('sdk/client.d.mts 存在')
+}
+else {
+  fail('sdk/client.d.mts 不存在(package.json exports["./sdk/client"].types 悬空)')
+}
+
+// 且必须真实描述 createClientContext(非空壳)
+if (existsSync(clientDts)) {
+  const src = readFileSync(clientDts, 'utf8')
+  const need = ['createClientContext', 'CLIENT_SDK_VERSION', 'export interface ClientContext']
+  for (const token of need) {
+    if (src.includes(token)) pass(`sdk/client.d.mts 声明了 ${token}`)
+    else fail(`sdk/client.d.mts 缺少声明: ${token}`)
+  }
+}
+
+// ---------- ③ package.json exports 目标文件全部存在 ----------
+console.log('\n[3/3] package.json exports 目标文件存在性')
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+const pkgName = pkg.name ?? '(anonymous)'
+
+function checkTarget(specifier, conditionName, target) {
+  // 字符串简写 与 { types, default } 两形态都支持
+  if (typeof target === 'string') {
+    checkFile(specifier, conditionName, target)
+    return
+  }
+  if (target && typeof target === 'object') {
+    for (const [cond, val] of Object.entries(target)) checkTarget(specifier, `${conditionName}.${cond}`, val)
+    return
+  }
+  fail(`exports["${specifier}"]${conditionName}: 目标不是字符串/对象`)
+}
+
+function checkFile(specifier, conditionName, rel) {
+  if (!rel.startsWith('./')) {
+    fail(`exports["${specifier}"]${conditionName} → "${rel}" 不是相对路径`)
+    return
+  }
+  const abs = join(ROOT, rel)
+  if (existsSync(abs) && statSync(abs).isFile()) {
+    pass(`exports["${specifier}"]${conditionName} → ${rel}`)
+  }
+  else {
+    fail(`exports["${specifier}"]${conditionName} → ${rel} 文件不存在`)
+  }
+}
+
+const exportsMap = pkg.exports ?? {}
+const specifiers = Object.keys(exportsMap)
+if (specifiers.length === 0) fail('package.json 未声明 exports')
+for (const spec of specifiers) checkTarget(spec, '', exportsMap[spec])
+
+// 额外守卫:两个 types 入口都应指向存在的 .d.mts
+for (const spec of ['.', './sdk', './sdk/client']) {
+  const t = exportsMap[spec]?.types
+  if (t && !t.endsWith('.d.mts')) fail(`exports["${spec}"].types 不是 .d.mts: ${t}`)
+}
+
+// ---------- 报告 ----------
+console.log('')
+if (failures === 0) {
+  console.log(`✅ SDK 出口面校验通过(${pkgName}@${pkg.version ?? '?'})`)
+  process.exit(0)
+}
+console.error(`❌ SDK 出口面校验失败:${failures} 项`)
+process.exit(1)