dsh-x-core 0.1.22 → 0.1.25

package/compat/session-events.mjs

@@ -1,122 +1,122 @@
-/**
- * 会话事件词汇兼容补丁。
- *
- * 问题：第三方插件会往会话日志里写自己的事件类型（如 `filesnap/point`）。dsh 的读取器
- * 遇到不认识的事件类型会**拒绝读取整份日志**——除非该事件写入时带了 `ignorable`
- * 标记，而 dsh 的 `Session.append` 目前不提供这个开关（插件只能靠"把自己塞进 dsh 已知
- * 集合"绕过，卸载即失效）。filesnap 作者在源码注释里明确写过这个代价：
- * "uninstalling the plugin strands those sessions"。
- *
- * 本补丁让 dsh 重新认识这些**纯日志性质**的事件类型，从而读出那些会话。
- * 事件本身仍原样保留在日志里（不删改任何数据），只是不再让读取器拒绝整份日志。
- *
- * 覆盖四层校验（都靠 KNOWN_SESSION_EVENT_TYPES 判"认不认识"）：
- *   1. dsh-session 的 KNOWN_SESSION_EVENT_TYPES —— 事件词汇表；
- *   2. v0 历史格式的冻结词汇表 RELEASED_V0_EVENT_DISPOSITIONS —— 旧日志迁移用；
- *   3. 该格式的语义校验 switch —— 未知类型会落到 default 抛错；
- *   4. dsh-session-persistence 的 validateStoredEvents —— 迁移完成后落库前再查一次词汇表
- *      （这一层查的是迁移后的 seq，旧日志经过打包行折叠会重新编号）。
- *
- * 除了事件词汇表，这里还兜一个 dsh 的健壮性缺口（见 appBootStackPatch 的注释）。
- *
- * 安全：只在源码结构匹配时替换，dsh 升级导致代码变化即自动跳过（不改坏任何东西）。
- */
-const SESSION_TYPES = ['filesnap/point', 'filesnap/rewound', 'filesnap/redone']
-const TARGETS = ['dsh-session/lib/index.js', 'dsh-app-boot/lib/index.js', 'dsh-session-format-v0-to-v1/lib/index.js']
-
-/** 带载荷字段的类型 —— 字段声明为可选，避免键校验把它们当多余字段拒绝。 */
-const PAYLOAD_KEYS = {
-  'filesnap/point': ['turn', 'point', 'manifest', 'reused', 'hashed', 'dropped'],
-  'filesnap/rewound': [],
-  'filesnap/redone': [],
-}
-
-function knownSetPatch(source) {
-  const anchor = 'const KNOWN_SESSION_EVENT_TYPES = new Set(['
-  if (!source.includes(anchor)) return null
-  const injected = SESSION_TYPES.map((type) => JSON.stringify(type)).join(',')
-  return source.replace(anchor, `${anchor}${injected},`)
-}
-
-function dispositionsPatch(source) {
-  const anchor = 'const RELEASED_V0_EVENT_DISPOSITIONS = Object.freeze({'
-  if (!source.includes(anchor)) return null
-  const entries = SESSION_TYPES
-    .map((type) => `${JSON.stringify(type)}: defineReleasedPayloadDisposition([],${JSON.stringify(PAYLOAD_KEYS[type] ?? [])},[])`)
-    .join(',')
-  return source.replace(anchor, `${anchor}${entries},`)
-}
-
-function semanticsPatch(source) {
-  const anchor = 'default: throw new SessionFormatError(`released payload validator is missing event'
-  if (!source.includes(anchor)) return null
-  const cases = SESSION_TYPES.map((type) => `case ${JSON.stringify(type)}:`).join(' ')
-  // 这些是纯日志事件：没有需要校验的语义，直接放行
-  return source.replace(anchor, `${cases} return;\n\t\t${anchor}`)
-}
-
-/**
- * dsh-app-boot 改写错误 stack 的两处要能容错。
- *
- * 注册过任意 ESM loader 钩子时（我们的 perf/ 与 compat/ 就是），Node 22.19 会把解析错误
- * 的 stack 变成只读的自有属性（实测 `writable: false`）。而 app-boot 为了把报错里的
- * importer 路径还原成真实调用方，会执行 `error.stack = ...` —— 这一写直接抛
- * `TypeError: Cannot assign to read only property 'stack'`，把原来的错误码
- * （`ERR_PACKAGE_PATH_NOT_EXPORTED` 之类）顶掉。dsh 0.1.7 新增的插件元数据读取
- * （`readPluginMeta` 会探测 `<包>/locale/en.json`）正好走这条路，于是「设置 → 内置插件」
- * 大面积报错（issue #24：188 条里 179 条带 meta.error）。
- *
- * 这里只把赋值本身包进 try/catch：写得进去行为不变；写不进去就放弃改写 stack，
- * 保住原始错误码。dsh 升级改掉这两行就会自动跳过。
- */
-export function appBootStackPatch(source) {
-  const assignments = [
-    'if (stack !== void 0) error.stack = stack.replace(originalMessage, message);',
-    'if (stack !== void 0) error.stack = stack.replace(originalMessage, error.message);',
-  ]
-  let out = source
-  let patched = 0
-  for (const line of assignments) {
-    if (!out.includes(line)) continue
-    const guarded = line.replace(
-      /^if \(stack !== void 0\) (error\.stack = .*);$/,
-      'if (stack !== void 0) { try { $1; } catch { /* stack 只读（注册过 ESM 钩子时 Node 会这样）：放弃改写，保留原始错误码 */ } }',
-    )
-    if (guarded === line) continue
-    out = out.replace(line, guarded)
-    patched += 1
-  }
-  return patched ? out : null
-}
-
-export function load(url, context, nextLoad) {
-  const result = nextLoad(url, context)
-  // 绝大多数模块不需要补丁，先筛路径，避免把每份源码额外解码成字符串。
-  if (!TARGETS.some((target) => url.includes(target))) return result
-  if (result.format !== 'module' || result.source === undefined) return result
-
-  let source = Buffer.isBuffer(result.source) ? result.source.toString('utf8') : String(result.source)
-  const before = source.length
-  const applied = []
-
-  if (url.includes('dsh-session/lib/index.js')) {
-    const next = knownSetPatch(source)
-    if (next !== null) { source = next; applied.push('事件词汇表') }
-  }
-  if (url.includes('dsh-app-boot/lib/index.js')) {
-    const next = appBootStackPatch(source)
-    if (next !== null) { source = next; applied.push('错误 stack 安全写') }
-  }
-  if (url.includes('dsh-session-format-v0-to-v1/lib/index.js')) {
-    const a = dispositionsPatch(source)
-    if (a !== null) { source = a; applied.push('v0 词汇表') }
-    const b = semanticsPatch(source)
-    if (b !== null) { source = b; applied.push('v0 语义校验') }
-  }
-
-  if (process.env.DSH_PERF_DEBUG === '1' && applied.length) {
-    console.error(`[compat] 会话事件兼容: ${applied.join(' + ')}`)
-  }
-  if (source.length === before) return result
-  return { ...result, source }
-}
+/**
+ * 会话事件词汇兼容补丁。
+ *
+ * 问题：第三方插件会往会话日志里写自己的事件类型（如 `filesnap/point`）。dsh 的读取器
+ * 遇到不认识的事件类型会**拒绝读取整份日志**——除非该事件写入时带了 `ignorable`
+ * 标记，而 dsh 的 `Session.append` 目前不提供这个开关（插件只能靠"把自己塞进 dsh 已知
+ * 集合"绕过，卸载即失效）。filesnap 作者在源码注释里明确写过这个代价：
+ * "uninstalling the plugin strands those sessions"。
+ *
+ * 本补丁让 dsh 重新认识这些**纯日志性质**的事件类型，从而读出那些会话。
+ * 事件本身仍原样保留在日志里（不删改任何数据），只是不再让读取器拒绝整份日志。
+ *
+ * 覆盖四层校验（都靠 KNOWN_SESSION_EVENT_TYPES 判"认不认识"）：
+ *   1. dsh-session 的 KNOWN_SESSION_EVENT_TYPES —— 事件词汇表；
+ *   2. v0 历史格式的冻结词汇表 RELEASED_V0_EVENT_DISPOSITIONS —— 旧日志迁移用；
+ *   3. 该格式的语义校验 switch —— 未知类型会落到 default 抛错；
+ *   4. dsh-session-persistence 的 validateStoredEvents —— 迁移完成后落库前再查一次词汇表
+ *      （这一层查的是迁移后的 seq，旧日志经过打包行折叠会重新编号）。
+ *
+ * 除了事件词汇表，这里还兜一个 dsh 的健壮性缺口（见 appBootStackPatch 的注释）。
+ *
+ * 安全：只在源码结构匹配时替换，dsh 升级导致代码变化即自动跳过（不改坏任何东西）。
+ */
+const SESSION_TYPES = ['filesnap/point', 'filesnap/rewound', 'filesnap/redone']
+const TARGETS = ['dsh-session/lib/index.js', 'dsh-app-boot/lib/index.js', 'dsh-session-format-v0-to-v1/lib/index.js']
+
+/** 带载荷字段的类型 —— 字段声明为可选，避免键校验把它们当多余字段拒绝。 */
+const PAYLOAD_KEYS = {
+  'filesnap/point': ['turn', 'point', 'manifest', 'reused', 'hashed', 'dropped'],
+  'filesnap/rewound': [],
+  'filesnap/redone': [],
+}
+
+function knownSetPatch(source) {
+  const anchor = 'const KNOWN_SESSION_EVENT_TYPES = new Set(['
+  if (!source.includes(anchor)) return null
+  const injected = SESSION_TYPES.map((type) => JSON.stringify(type)).join(',')
+  return source.replace(anchor, `${anchor}${injected},`)
+}
+
+function dispositionsPatch(source) {
+  const anchor = 'const RELEASED_V0_EVENT_DISPOSITIONS = Object.freeze({'
+  if (!source.includes(anchor)) return null
+  const entries = SESSION_TYPES
+    .map((type) => `${JSON.stringify(type)}: defineReleasedPayloadDisposition([],${JSON.stringify(PAYLOAD_KEYS[type] ?? [])},[])`)
+    .join(',')
+  return source.replace(anchor, `${anchor}${entries},`)
+}
+
+function semanticsPatch(source) {
+  const anchor = 'default: throw new SessionFormatError(`released payload validator is missing event'
+  if (!source.includes(anchor)) return null
+  const cases = SESSION_TYPES.map((type) => `case ${JSON.stringify(type)}:`).join(' ')
+  // 这些是纯日志事件：没有需要校验的语义，直接放行
+  return source.replace(anchor, `${cases} return;\n\t\t${anchor}`)
+}
+
+/**
+ * dsh-app-boot 改写错误 stack 的两处要能容错。
+ *
+ * 注册过任意 ESM loader 钩子时（我们的 perf/ 与 compat/ 就是），Node 22.19 会把解析错误
+ * 的 stack 变成只读的自有属性（实测 `writable: false`）。而 app-boot 为了把报错里的
+ * importer 路径还原成真实调用方，会执行 `error.stack = ...` —— 这一写直接抛
+ * `TypeError: Cannot assign to read only property 'stack'`，把原来的错误码
+ * （`ERR_PACKAGE_PATH_NOT_EXPORTED` 之类）顶掉。dsh 0.1.7 新增的插件元数据读取
+ * （`readPluginMeta` 会探测 `<包>/locale/en.json`）正好走这条路，于是「设置 → 内置插件」
+ * 大面积报错（issue #24：188 条里 179 条带 meta.error）。
+ *
+ * 这里只把赋值本身包进 try/catch：写得进去行为不变；写不进去就放弃改写 stack，
+ * 保住原始错误码。dsh 升级改掉这两行就会自动跳过。
+ */
+export function appBootStackPatch(source) {
+  const assignments = [
+    'if (stack !== void 0) error.stack = stack.replace(originalMessage, message);',
+    'if (stack !== void 0) error.stack = stack.replace(originalMessage, error.message);',
+  ]
+  let out = source
+  let patched = 0
+  for (const line of assignments) {
+    if (!out.includes(line)) continue
+    const guarded = line.replace(
+      /^if \(stack !== void 0\) (error\.stack = .*);$/,
+      'if (stack !== void 0) { try { $1; } catch { /* stack 只读（注册过 ESM 钩子时 Node 会这样）：放弃改写，保留原始错误码 */ } }',
+    )
+    if (guarded === line) continue
+    out = out.replace(line, guarded)
+    patched += 1
+  }
+  return patched ? out : null
+}
+
+export function load(url, context, nextLoad) {
+  const result = nextLoad(url, context)
+  // 绝大多数模块不需要补丁，先筛路径，避免把每份源码额外解码成字符串。
+  if (!TARGETS.some((target) => url.includes(target))) return result
+  if (result.format !== 'module' || result.source === undefined) return result
+
+  let source = Buffer.isBuffer(result.source) ? result.source.toString('utf8') : String(result.source)
+  const before = source.length
+  const applied = []
+
+  if (url.includes('dsh-session/lib/index.js')) {
+    const next = knownSetPatch(source)
+    if (next !== null) { source = next; applied.push('事件词汇表') }
+  }
+  if (url.includes('dsh-app-boot/lib/index.js')) {
+    const next = appBootStackPatch(source)
+    if (next !== null) { source = next; applied.push('错误 stack 安全写') }
+  }
+  if (url.includes('dsh-session-format-v0-to-v1/lib/index.js')) {
+    const a = dispositionsPatch(source)
+    if (a !== null) { source = a; applied.push('v0 词汇表') }
+    const b = semanticsPatch(source)
+    if (b !== null) { source = b; applied.push('v0 语义校验') }
+  }
+
+  if (process.env.DSH_PERF_DEBUG === '1' && applied.length) {
+    console.error(`[compat] 会话事件兼容: ${applied.join(' + ')}`)
+  }
+  if (source.length === before) return result
+  return { ...result, source }
+}

package/compat/worker-events.cjs

@@ -1,66 +1,66 @@
-/**
- * 会话事件词汇兼容补丁 —— worker 线程版（CommonJS）。
- *
- * dsh 在校验会话日志时会起一个 Worker Thread 跑 `worker.cjs`，那里有一份**内联的**
- * 事件词汇表副本，且校验用的就是它。主线程的 ESM 加载钩子够不到那个文件，所以
- * 需要这个 CJS 补丁：通过 NODE_OPTIONS=--require 注入，对 worker 同样生效
- * （worker 的 `execArgv: []` 只清空命令行参数，不影响 NODE_OPTIONS）。
- *
- * 做法：拦截 fs 读取，在 worker.cjs 的源码里把那几个纯日志事件类型补进词汇表。
- * 只改内存中的字符串，不动磁盘上的任何文件；匹配不到就原样返回（dsh 升级后自动失效）。
- *
- * 覆盖 worker.cjs 里的两处：
- *   1. KNOWN_SESSION_EVENT_TYPES —— "这个事件类型认不认识"；
- *   2. 词汇表之外的等价集合（若结构不同则跳过）。
- */
-'use strict'
-
-const SESSION_TYPES = ['filesnap/point', 'filesnap/rewound', 'filesnap/redone']
-const KNOWN_ANCHOR = 'const KNOWN_SESSION_EVENT_TYPES = new Set(['
-
-/** 只处理 dsh 的会话持久化 worker。 */
-function isTargetWorker(filename) {
-  return typeof filename === 'string' &&
-    filename.includes('dsh-session-persistence-jsonl') &&
-    filename.endsWith('worker.cjs')
-}
-
-/** 给源码里的词汇表注入事件类型；已注入过或结构不符则返回 null。 */
-function injectTypes(source) {
-  if (source.includes(SESSION_TYPES[0])) return null
-  const anchor = source.indexOf(KNOWN_ANCHOR)
-  if (anchor < 0) return null
-  const injected = SESSION_TYPES.map((type) => JSON.stringify(type)).join(',')
-  return source.slice(0, anchor + KNOWN_ANCHOR.length) + injected + ',' + source.slice(anchor + KNOWN_ANCHOR.length)
-}
-
-// 在 fs 层拦截：worker.cjs 这类打包文件由 Node 自己读取，不经过 require 的编译钩子
-let patched = null
-const fs = require('node:fs')
-
-function wrapRead(original, needsEncoding) {
-  return function patchedRead(file, ...rest) {
-    const result = original.call(this, file, ...rest)
-    try {
-      if (!isTargetWorker(typeof file === 'string' ? file : file?.toString?.())) return result
-      let text = typeof result === 'string' ? result : null
-      if (text === null && Buffer.isBuffer(result)) text = result.toString('utf8')
-      if (text === null) return result
-      const next = injectTypes(text)
-      if (next === null) return result
-      if (patched === null) {
-        patched = true
-        if (process.env.DSH_PERF_DEBUG === '1') {
-          console.error('[compat] worker 会话事件词汇已补丁')
-        }
-      }
-      return needsEncoding ? next : Buffer.from(next, 'utf8')
-    } catch {
-      // 任何意外都退回原始结果，绝不干扰读取
-      return result
-    }
-  }
-}
-
-fs.readFileSync = wrapRead(fs.readFileSync, true)
-fs.readFile = wrapRead(fs.readFile, false)
+/**
+ * 会话事件词汇兼容补丁 —— worker 线程版（CommonJS）。
+ *
+ * dsh 在校验会话日志时会起一个 Worker Thread 跑 `worker.cjs`，那里有一份**内联的**
+ * 事件词汇表副本，且校验用的就是它。主线程的 ESM 加载钩子够不到那个文件，所以
+ * 需要这个 CJS 补丁：通过 NODE_OPTIONS=--require 注入，对 worker 同样生效
+ * （worker 的 `execArgv: []` 只清空命令行参数，不影响 NODE_OPTIONS）。
+ *
+ * 做法：拦截 fs 读取，在 worker.cjs 的源码里把那几个纯日志事件类型补进词汇表。
+ * 只改内存中的字符串，不动磁盘上的任何文件；匹配不到就原样返回（dsh 升级后自动失效）。
+ *
+ * 覆盖 worker.cjs 里的两处：
+ *   1. KNOWN_SESSION_EVENT_TYPES —— "这个事件类型认不认识"；
+ *   2. 词汇表之外的等价集合（若结构不同则跳过）。
+ */
+'use strict'
+
+const SESSION_TYPES = ['filesnap/point', 'filesnap/rewound', 'filesnap/redone']
+const KNOWN_ANCHOR = 'const KNOWN_SESSION_EVENT_TYPES = new Set(['
+
+/** 只处理 dsh 的会话持久化 worker。 */
+function isTargetWorker(filename) {
+  return typeof filename === 'string' &&
+    filename.includes('dsh-session-persistence-jsonl') &&
+    filename.endsWith('worker.cjs')
+}
+
+/** 给源码里的词汇表注入事件类型；已注入过或结构不符则返回 null。 */
+function injectTypes(source) {
+  if (source.includes(SESSION_TYPES[0])) return null
+  const anchor = source.indexOf(KNOWN_ANCHOR)
+  if (anchor < 0) return null
+  const injected = SESSION_TYPES.map((type) => JSON.stringify(type)).join(',')
+  return source.slice(0, anchor + KNOWN_ANCHOR.length) + injected + ',' + source.slice(anchor + KNOWN_ANCHOR.length)
+}
+
+// 在 fs 层拦截：worker.cjs 这类打包文件由 Node 自己读取，不经过 require 的编译钩子
+let patched = null
+const fs = require('node:fs')
+
+function wrapRead(original, needsEncoding) {
+  return function patchedRead(file, ...rest) {
+    const result = original.call(this, file, ...rest)
+    try {
+      if (!isTargetWorker(typeof file === 'string' ? file : file?.toString?.())) return result
+      let text = typeof result === 'string' ? result : null
+      if (text === null && Buffer.isBuffer(result)) text = result.toString('utf8')
+      if (text === null) return result
+      const next = injectTypes(text)
+      if (next === null) return result
+      if (patched === null) {
+        patched = true
+        if (process.env.DSH_PERF_DEBUG === '1') {
+          console.error('[compat] worker 会话事件词汇已补丁')
+        }
+      }
+      return needsEncoding ? next : Buffer.from(next, 'utf8')
+    } catch {
+      // 任何意外都退回原始结果，绝不干扰读取
+      return result
+    }
+  }
+}
+
+fs.readFileSync = wrapRead(fs.readFileSync, true)
+fs.readFile = wrapRead(fs.readFile, false)