agentworkshop 0.7.24 → 0.7.33

package/scripts/_audit/awhome/commands/README.md

@@ -0,0 +1,3 @@
+# 自定义指令目录
+
+导出 { meta, run } 的 .mjs 文件放入本目录即自动注册。

package/scripts/_audit/awhome/commands/hello.mjs

@@ -0,0 +1,12 @@
+// scratch audit command (registration target experiment)
+export const meta = {
+  name: 'hello-audit',
+  group: 'audit',
+  summary: 'hello from audit scratch',
+  needsProject: false,
+}
+
+export async function run() {
+  console.log('hello-audit ok')
+  return 0
+}

package/scripts/_audit/dcw-controller-e2e.ts

@@ -0,0 +1,99 @@
+/**
+ * 审计实验 5 —— 端到端:真实 DcwController + mock 驱动,验证
+ *  ① 正常写:硬件写入 + 账本锚 + 写历史(正对照)
+ *  ② PATCH decimals=101(无校验)→ 后续写「已落硬件但记账抛错」→ 无账本锚/无写历史/500
+ *  ③ 不存在节点 id 的语义(服务层 404)
+ *
+ * cwd 已切到 scripts/_audit/.tmp:所有仓库文件写到临时目录,绝不碰 server/data/*。
+ * 运行:node --experimental-transform-types scripts/_audit/run.mjs scripts/_audit/dcw-controller-e2e.ts
+ */
+import { mkdirSync, rmSync } from 'node:fs'
+
+// 清空本次实验的隔离数据目录(run.mjs 已把 AW_DATA_DIR 指向 scripts/_audit/.tmp/audit-data;
+// 同目录其它实验残留的 20000 锚账本会污染断言,故先清空)
+const ISOLATED = new URL('./.tmp/audit-data/', import.meta.url)
+rmSync(ISOLATED, { recursive: true, force: true })
+mkdirSync(ISOLATED, { recursive: true })
+// 清空上次实验留下的临时库(benchmark 会写出 10MB+ 的 dcw-rollback.json)
+rmSync(new URL('./.tmp/server/', import.meta.url), { recursive: true, force: true })
+mkdirSync(new URL('./.tmp/server/data/', import.meta.url), { recursive: true })
+process.chdir(new URL('./.tmp/', import.meta.url).pathname.replace(/^\//, ''))
+
+const { getDcwController } = await import('../../server/services/workshop/dcw/dcw-controller')
+const { getRecipeRollBackRepo } = await import('../../server/services/workshop/dcw/recipe-rollback.repo')
+const { getDcwRecipeRepo } = await import('../../server/services/workshop/dcw/dcw-recipe.repo')
+
+let failures = 0
+function check(name: string, cond: boolean, extra = ''): void {
+  if (cond) {
+    console.log(`  PASS  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+  else {
+    failures++
+    console.log(`  FAIL  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+}
+
+const mockPlc = (globalThis as { __dcwMockPlc?: Map<string, number> }).__dcwMockPlc!
+const plcValue = (): number | undefined => mockPlc.get('default')
+
+const ctrl = getDcwController()
+const ledger = getRecipeRollBackRepo()
+const writes = getDcwRecipeRepo()
+
+const node = ctrl.create({ templateRef: 'temp-sp', driver: 'mock', min: 150, max: 200, decimals: 1, enabled: true })
+console.log(`  节点 ${node.id} 创建(mock 驱动,min150 max200 decimals1)`)
+
+console.log('\n=== ① 正对照:正常写 ===')
+{
+  const anchorsBefore = ledger.stats().anchors
+  const out = await ctrl.write(node.id, 160, null, { source: 'manual', actor: 'audit' })
+  check('写入返回 ok', out.ok === true, out.message)
+  check('mock PLC 记录写入值 160(硬件已写)', plcValue() === 160, `plc=${plcValue()}`)
+  check('账本新增 1 条锚', ledger.stats().anchors === anchorsBefore + 1, `anchors=${ledger.stats().anchors}`)
+  check('写历史新增 1 条', writes.historyList(5).length === 1, `n=${writes.historyList(5).length}`)
+  check('节点 value=160', node.value === 160, `value=${node.value}`)
+}
+
+console.log('\n=== ② PATCH decimals=101(接口无任何范围校验)→ 再写 ===')
+{
+  const patched = ctrl.patch(node.id, { decimals: 101 })
+  check('PATCH decimals=101 被接受(无校验)', patched.decimals === 101, `decimals=${patched.decimals}`)
+
+  const anchorsBefore = ledger.stats().anchors
+  const historyBefore = writes.historyList(50).length
+  let err: unknown
+  try {
+    await ctrl.write(node.id, 170, null, { source: 'manual', actor: 'audit' })
+  }
+  catch (e) {
+    err = e
+  }
+  console.log(`  写 170 抛错: ${(err as Error)?.name}: ${(err as Error)?.message}`)
+  check('写入抛出异常(调用方得到 500 而非 ACK)', err != null, String((err as Error)?.name))
+  check('异常来自 toFixed 的 RangeError 语义', /toFixed|digits|RangeError/i.test(`${(err as Error)?.name} ${(err as Error)?.message}`), `${(err as Error)?.name}`)
+  check('mock PLC 已记录 170(硬件写入已发生)', plcValue() === 170, `plc=${plcValue()}`)
+  check('账本未新增锚(这次硬件变更无法回退)', ledger.stats().anchors === anchorsBefore, `anchors=${ledger.stats().anchors}`)
+  check('写历史未新增条目(审计缺失)', writes.historyList(50).length === historyBefore, `n=${writes.historyList(50).length}`)
+  check('节点 state=error 且 value 仍是旧值 160', node.state === 'error' && node.value === 160, `state=${node.state} value=${node.value}`)
+
+  const stable = ledger.lastStableAnchor(node.id)
+  console.log(`  账本最新稳定锚={prev:${stable?.prevValue}, new:${stable?.newValue}};硬件实际=${plcValue()};节点显示=${node.value}`)
+  check('硬件(170)≠ 账本(160):账本与硬件已漂移', plcValue() !== stable?.newValue)
+}
+
+console.log('\n=== ③ 不存在节点 id 的服务层语义 ===')
+{
+  let e404: unknown
+  try {
+    await ctrl.write('dw-nonexistent', 160, null, { source: 'manual', actor: 'audit' })
+  }
+  catch (e) {
+    e404 = e
+  }
+  const status = (e404 as { status?: number })?.status
+  check('不存在节点 → AppError 404(控制器层)', status === 404, `status=${status}`)
+}
+
+console.log(`\nresult: ${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/_audit/dcw-flush-cost.ts

@@ -0,0 +1,43 @@
+/**
+ * 审计实验 4 —— DCW 落盘放大成本(只读:仅读真实 data/*.json,写入 scripts/_audit/.tmp)。
+ *
+ * 运行:node --experimental-transform-types scripts/_audit/run.mjs scripts/_audit/dcw-flush-cost.ts
+ */
+import { mkdirSync, readFileSync, statSync } from 'node:fs'
+import { saveJsonFileAtomic } from '../../server/services/workshop/json-store.mjs'
+
+const TMP = new URL('./.tmp/', import.meta.url).pathname.replace(/^\//, '')
+mkdirSync(TMP, { recursive: true })
+
+const rows = (f: string): unknown => JSON.parse(readFileSync(`server/data/${f}`, 'utf-8'))
+
+const nodes = rows('dcws.json') as Array<Record<string, unknown>>
+const writes = rows('dcw-writes.json') as Array<Record<string, unknown>>
+
+function bench(label: string, data: unknown, target: string, iters: number): void {
+  const t0 = performance.now()
+  for (let i = 0; i < iters; i++) saveJsonFileAtomic(target, data)
+  const dt = performance.now() - t0
+  const size = statSync(target).size
+  // JSON.stringify 单独计量(纯 CPU,事件循环阻塞部分)
+  const t1 = performance.now()
+  for (let i = 0; i < iters; i++) JSON.stringify(data, null, 2)
+  const ds = performance.now() - t1
+  console.log(
+    `  ${label}: flushNow 全量落盘 per-op=${(dt / iters).toFixed(1)}ms`
+    + ` (其中 JSON.stringify(pretty) ${(ds / iters).toFixed(1)}ms), 文件=${(size / 1024).toFixed(1)}KB,`
+    + ` iters=${iters}`,
+  )
+  console.log(`    记录数=${Array.isArray(data) ? data.length : Object.keys(data as object).length}`)
+}
+
+console.log('=== 真实数据规模下的落盘成本(与生产 server/data/*.json 同形) ===')
+bench('dcws.json(节点快照;每次写值/读值后防抖落盘 dcw-controller.ts:179,235)', nodes, `${TMP}/dcws.json`, 20)
+bench('dcw-writes.json(写历史;每次下发后防抖落盘 dcw-controller.ts:193)', writes, `${TMP}/dcw-writes.json`, 20)
+
+const readInt = nodes.map(n => Number(n.readIntervalMs)).filter(v => Number.isFinite(v) && v > 0)
+const perSec = readInt.reduce((a, v) => a + (1000 / v), 0)
+console.log('\n=== 生产规模推算 ===')
+console.log(`  配置了周期读的节点=${readInt.length},合计周期读频率=${perSec.toFixed(1)} 次/秒`)
+console.log(`  每次周期读 executeRead 尾部调用 repo.flushDebounced()(dcw-controller.ts:235)`)
+console.log(`  防抖窗 1.5s(dcw-node.repo.ts:60-66)→ 稳态下 dcws.json 全量重写≈每 1.5s 一次`)

package/scripts/_audit/dcw-rollback-ledger.ts

@@ -0,0 +1,153 @@
+/**
+ * 审计实验 2 —— RecipeRollBackRepo 账本算法/落盘成本(只读审计)。
+ *
+ * 关键:cwd 切到 scripts/_audit/.tmp,使 repo 的 DATA_DIR 指向临时目录,
+ * **绝不触碰 server/data/dcw-rollback.json**(真实数据文件)。
+ *
+ * 运行:node --experimental-transform-types scripts/_audit/run.mjs scripts/_audit/dcw-rollback-ledger.ts
+ */
+import { mkdirSync } from 'node:fs'
+
+const TMP = new URL('./.tmp/', import.meta.url)
+mkdirSync(new URL('server/data/', TMP), { recursive: true })
+process.chdir(new URL('.tmp/', new URL('.', import.meta.url)).pathname.replace(/^\//, ''))
+
+const { RecipeRollBackRepo } = await import('../../server/services/workshop/dcw/recipe-rollback.repo')
+
+const CAP_ANCHORS = 20000
+const CAP_RECORDS = 2000
+
+function anchorOf(i: number, nodeId = `n-${i % 50}`) {
+  return {
+    lineId: 'ln-audit',
+    nodeId,
+    prevValue: i,
+    newValue: i + 1,
+    source: 'manual' as const,
+    actor: 'user',
+    recipeRunId: null,
+  }
+}
+
+/** 贴近真实形状的 windowAgg(实测 server/data/dcw-rollback.json:平均记录 1267 B) */
+function aggOf(nodeId: string) {
+  return {
+    at: new Date().toISOString(),
+    fromMs: Date.now() - 600_000,
+    toMs: Date.now(),
+    channels: Array.from({ length: 8 }, (_, k) => ({
+      daqNodeId: `dq-${k}`,
+      ch: `CH${k}`,
+      unit: 'C',
+      latest: 123.45,
+      avg: 121.11,
+      min: 100.5,
+      max: 140.25,
+      cnt: 120,
+      breaches: 0,
+      nodeIdFallback: nodeId,
+    })),
+  }
+}
+
+function ms(fn: () => void): number {
+  const t0 = performance.now()
+  fn()
+  return performance.now() - t0
+}
+function report(label: string, totalMs: number, iters: number): void {
+  console.log(`  ${label}: total=${totalMs.toFixed(1)}ms  per-op=${(totalMs / iters).toFixed(3)}ms  (iters=${iters})`)
+}
+
+console.log('=== A. anchors 到达上限后的每次 appendAnchor 成本 ===')
+{
+  const repo = new RecipeRollBackRepo()
+  for (let i = 0; i < CAP_ANCHORS; i++) repo.appendAnchor(anchorOf(i))
+  console.log(`  填充后 anchors=${repo.stats().anchors}(cap=${CAP_ANCHORS})`)
+  const iters = 200
+  const t = ms(() => {
+    for (let i = 0; i < iters; i++) repo.appendAnchor(anchorOf(CAP_ANCHORS + i))
+  }, iters)
+  report('appendAnchor(在上限稳态,每次触发 splice+new Set)', t, iters)
+  console.log(`  追加后 anchors=${repo.stats().anchors}(仍为 cap,说明每写都触发淘汰路径)`)
+
+  console.log('\n=== B. 查询方法成本(20000 锚 / 50 节点) ===')
+  const nodeId = 'n-0'
+  let t1 = ms(() => { for (let i = 0; i < 1000; i++) repo.lastStableAnchor(nodeId) }, 1000)
+  report('lastStableAnchor (O(1) 索引)', t1, 1000)
+  t1 = ms(() => { for (let i = 0; i < 1000; i++) repo.lastRollbackAnchor(nodeId) }, 1000)
+  report('lastRollbackAnchor (节点子序列倒扫)', t1, 1000)
+  t1 = ms(() => { for (let i = 0; i < 200; i++) repo.anchorById('anc-nonexistent') }, 200)
+  report('anchorById (全量 find,未命中=最坏)', t1, 200)
+  t1 = ms(() => { for (let i = 0; i < 200; i++) repo.listAnchors({ lineId: 'ln-nope', limit: 100 }) }, 200)
+  report('listAnchors({lineId}) 无命中 → 全量 20000 倒扫', t1, 200)
+  t1 = ms(() => { for (let i = 0; i < 200; i++) repo.listAnchors({ nodeId, limit: 30 }) }, 200)
+  report('listAnchors({nodeId, limit:30}) 走索引', t1, 200)
+}
+
+console.log('\n=== C. records(2000 上限)+ open 索引 ===')
+{
+  const repo = new RecipeRollBackRepo()
+  for (let i = 0; i < CAP_RECORDS; i++) {
+    repo.insertRecord({
+      lineId: 'ln-audit',
+      nodeId: `n-${i % 50}`,
+      nodeName: `node-${i % 50}`,
+      recipeId: null,
+      hypothesis: 'h',
+      params: [{ nodeId: `n-${i % 50}`, templateRef: 'cw-temp', from: i, to: i + 1 }],
+      setAt: new Date().toISOString(),
+      status: 'open',
+      judge: null,
+      anchorId: `anc-${i}`,
+      policy: 'auto_rollback',
+    })
+  }
+  console.log(`  records=${repo.stats().records} open=${repo.stats().open}(每节点仅索引最后一条)`)
+  const t = ms(() => { for (let i = 0; i < 200; i++) repo.listOpenRecords() }, 200)
+  report('listOpenRecords (O(open))', t, 200)
+  const t2 = ms(() => { for (let i = 0; i < 200; i++) repo.chainRollbackCount('n-0') }, 200)
+  report('chainRollbackCount (全量 2000 filter)', t2, 200)
+  const t3 = ms(() => { for (let i = 0; i < 2000; i++) repo.byId('opt-nonexistent') }, 2000)
+  report('byId (全量 find,未命中=最坏)', t3, 2000)
+}
+
+console.log('\n=== D. 同节点第二条 open 记录 → 索引可见性 ===')
+{
+  const repo = new RecipeRollBackRepo()
+  const r1 = repo.insertRecord({ nodeId: 'n-x', status: 'open', policy: 'auto_rollback', setAt: new Date().toISOString(), params: [], lineId: 'l' } as never)
+  const r2 = repo.insertRecord({ nodeId: 'n-x', status: 'open', policy: 'auto_rollback', setAt: new Date().toISOString(), params: [], lineId: 'l' } as never)
+  const open = repo.listOpenRecords()
+  const listed = repo.listRecords({ nodeId: 'n-x', status: 'open', limit: 50 })
+  console.log(`  insertRecord #1=${r1.id} #2=${r2.id}`)
+  console.log(`  listOpenRecords() 返回 ${open.length} 条;listRecords(status=open) 返回 ${listed.length} 条`)
+  console.log(`  → 未被索引的 open 记录是否可达:${open.some(r => r.id === r1.id) ? '可达' : '不可达(永不被 sweep 评估)'}`)
+}
+
+console.log('\n=== E. flushNow(全量序列化)成本 ===')
+{
+  const repo = new RecipeRollBackRepo()
+  for (let i = 0; i < CAP_ANCHORS; i++) repo.appendAnchor(anchorOf(i))
+  for (let i = 0; i < CAP_RECORDS; i++) {
+    repo.insertRecord({
+      lineId: 'ln-audit',
+      nodeId: `n-${i % 50}`,
+      nodeName: `node-${i % 50}`,
+      recipeId: null,
+      hypothesis: 'h',
+      params: [{ nodeId: `n-${i % 50}`, templateRef: 'cw-temp', from: i, to: i + 1 }],
+      setAt: new Date().toISOString(),
+      status: 'closed-line-stop',
+      judge: null,
+      anchorId: `anc-${i}`,
+      policy: 'auto_rollback',
+      windowAgg: aggOf(`n-${i % 50}`),
+    } as never)
+  }
+  const iters = 20
+  const t = ms(() => { for (let i = 0; i < iters; i++) repo.flushNow() }, iters)
+  report(`flushNow(anchors=${CAP_ANCHORS} + records=${CAP_RECORDS} 含聚合)`, t, iters)
+  const { statSync } = await import('node:fs')
+  const size = statSync(process.cwd() + '/server/data/dcw-rollback.json').size
+  console.log(`  落盘文件大小=${(size / 1024 / 1024).toFixed(2)} MB(每次 agent/rollback 写后同步全量重写)`)
+}

package/scripts/_audit/dcw-unrecorded-write.ts

@@ -0,0 +1,171 @@
+/**
+ * 审计实验 3 —— 「写入落到硬件但未入账」链路(只读审计;全部走本地假 PLC,不触真实数据)。
+ *
+ * 组成:
+ *  A) 假 Modbus TCP PLC(FC16 写 / FC03 读;可切换「回读返回陈旧值」和「永不响应」)
+ *  B) 真实 modbus-tcp 写驱动(server/services/workshop/dcw/drivers.ts)
+ *  C) 真实 RecipeRollBackRepo(账本;cwd 已切到 scripts/_audit/.tmp,绝不碰 server/data/*)
+ *  D) 忠实复刻 dcw-controller.ts:536 的入册闸门 `if (outcome.ok !== false)`
+ *
+ * 运行:node --experimental-transform-types scripts/_audit/run.mjs scripts/_audit/dcw-unrecorded-write.ts
+ */
+import { mkdirSync } from 'node:fs'
+import net from 'node:net'
+
+const TMP_DIR = new URL('./.tmp/server/data/', import.meta.url)
+mkdirSync(TMP_DIR, { recursive: true })
+process.chdir(new URL('./.tmp/', import.meta.url).pathname.replace(/^\//, ''))
+
+const { modbusTcpDcwDriver } = await import('../../server/services/workshop/dcw/drivers')
+const { RecipeRollBackRepo } = await import('../../server/services/workshop/dcw/recipe-rollback.repo')
+const { writeTolerance } = await import('../../server/services/workshop/dcw/dcw-runtime')
+
+let failures = 0
+function check(name: string, cond: boolean, extra = ''): void {
+  if (cond) {
+    console.log(`  PASS  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+  else {
+    failures++
+    console.log(`  FAIL  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+}
+
+interface FakePlc {
+  port: number
+  registers: Map<number, number>
+  writeCount: number
+  mode: 'stale-readback' | 'hang'
+  close: () => void
+}
+
+function startFakePlc(opts: { staleReadback?: number, mode?: 'stale-readback' | 'hang' }): Promise<FakePlc> {
+  const registers = new Map<number, number>()
+  const state = { writeCount: 0, mode: opts.mode ?? 'stale-readback' as 'stale-readback' | 'hang' }
+  const server = net.createServer((sock) => {
+    let buf = Buffer.alloc(0)
+    sock.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk])
+      while (buf.length >= 6) {
+        const len = buf.readUInt16BE(4)
+        const total = 6 + len
+        if (buf.length < total) break
+        const unitId = buf.readUInt8(6)
+        const pdu = buf.subarray(7, total)
+        const fc = pdu.readUInt8(0)
+        const tid = buf.readUInt16BE(0)
+        if (state.mode === 'hang') {
+          buf = buf.subarray(total)
+          continue // 收到即吞:模拟半开链路(不响应)
+        }
+        let resp: Buffer
+        if (fc === 0x10) { // write multiple registers
+          const addr = pdu.readUInt16BE(1)
+          const qty = pdu.readUInt16BE(3)
+          for (let i = 0; i < qty; i++) registers.set(addr + i, pdu.readUInt16BE(6 + i * 2))
+          state.writeCount++
+          resp = Buffer.from([0x10, pdu[1]!, pdu[2]!, pdu[3]!, pdu[4]!])
+        }
+        else if (fc === 0x03) { // read holding registers
+          const addr = pdu.readUInt16BE(1)
+          const qty = pdu.readUInt16BE(3)
+          const data: number[] = []
+          for (let i = 0; i < qty; i++) {
+            // 关键:回读一律返回「陈旧值」——模拟 PLC 尚未生效/慢一拍
+            data.push(opts.staleReadback != null ? opts.staleReadback : (registers.get(addr + i) ?? 0))
+          }
+          resp = Buffer.from([0x03, data.length * 2, ...data.flatMap(v => [v >> 8 & 0xFF, v & 0xFF])])
+        }
+        else {
+          resp = Buffer.from([fc | 0x80, 0x01])
+        }
+        const head = Buffer.alloc(6)
+        head.writeUInt16BE(tid, 0)
+        head.writeUInt16BE(0, 2)
+        head.writeUInt16BE(resp.length + 1, 4)
+        sock.write(Buffer.concat([head, Buffer.from([unitId]), resp]))
+        buf = buf.subarray(total)
+      }
+    })
+    sock.on('error', () => {})
+  })
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: (server.address() as net.AddressInfo).port,
+        registers,
+        get writeCount() { return state.writeCount },
+        mode: state.mode,
+        close: () => server.close(),
+      } as FakePlc)
+    })
+  })
+}
+
+const nodeLike = { decimals: 2, min: 0, max: 100 } as never
+
+console.log('\n=== A. 回读陈旧值:写已落到寄存器,但 ACK 判定失败(ok=false) ===')
+{
+  const plc = await startFakePlc({ staleReadback: 5 })
+  const cfg = { host: '127.0.0.1', port: plc.port, unitId: 1, register: 0, dataType: 'int16', byteOrder: 'big' }
+  const res = await modbusTcpDcwDriver.write({
+    eng: 20,
+    tolerance: writeTolerance(nodeLike),
+    domain: { min: 0, max: 100 },
+    driverConfig: cfg,
+  })
+  console.log(`  驱动返回: ok=${res.ok} raw=${res.raw} readback=${res.readback} message=${res.message}`)
+  check('硬件寄存器已收到写入值 20', plc.registers.get(0) === 20, `reg0=${plc.registers.get(0)}`)
+  check('驱动判定为 ACK 失败(ok=false)', res.ok === false)
+  check('失败原因 = 回读偏差超容差', /回读偏差超容差/.test(res.message), res.message)
+  check('readback 为陈旧值 5', res.readback === 5)
+
+  // 账本语义复刻:dcw-controller.ts:536「仅成功写记锚」→ ok=false 时 afterWrite 不被调用
+  const repo = new RecipeRollBackRepo()
+  const seeded = repo.appendAnchor({ lineId: 'ln', nodeId: 'dw-1', prevValue: 5, newValue: 10, source: 'manual', actor: 'user', recipeRunId: null })
+  const outcome = res
+  let ledgerAppends = 0
+  if (outcome.ok !== false) { // ← 与 dcw-controller.ts:532-536 同构
+    repo.appendAnchor({ lineId: 'ln', nodeId: 'dw-1', prevValue: 10, newValue: 20, source: 'manual', actor: 'user', recipeRunId: null })
+    ledgerAppends++
+  }
+  check('ok=false 时账本未入册(闸门同构复刻)', ledgerAppends === 0)
+  const stable = repo.lastStableAnchor('dw-1')
+  console.log(`  账本最新稳定锚 = {prev:${stable?.prevValue}, new:${stable?.newValue}};硬件寄存器 = ${plc.registers.get(0)}`)
+  check('入册锚不是本次写入(20 不在册)', stable?.newValue === 10, `new=${stable?.newValue}`)
+  check('硬件实际值(20)≠ 入册锚 newValue(10):账本与硬件漂移', plc.registers.get(0) !== stable?.newValue)
+  check('seeded 锚的 prevValue=5 仍是回退目标:回退将跳过真实的上一设定值 10', stable?.prevValue === 5)
+  plc.close()
+}
+
+console.log('\n=== B. 同理:另一个方向的漂移(node.value = 陈旧回读值 → 保写心跳将重下发陈旧值) ===')
+{
+  const plc = await startFakePlc({ staleReadback: 5 })
+  const cfg = { host: '127.0.0.1', port: plc.port, unitId: 1, register: 0, dataType: 'int16', byteOrder: 'big' }
+  const res = await modbusTcpDcwDriver.write({ eng: 20, tolerance: writeTolerance(nodeLike), domain: { min: 0, max: 100 }, driverConfig: cfg })
+  // dcw-controller.ts:176 等价:node.applyWriteResult(outcome.readback ?? eng, ok, ...)
+  const DcwNodeMod = await import('../../server/services/workshop/dcw/dcw-node')
+  const node = DcwNodeMod.DcwNode.fromRow({ id: 'dw-1', templateRef: 'cw-temp', min: 0, max: 100, decimals: 2, holdIntervalMs: 1000, driver: 'modbus-tcp', driverConfig: cfg })
+  node.value = 10
+  node.applyWriteResult(res.readback ?? 20, res.ok, res.message, new Date().toISOString())
+  console.log(`  写入 20 / 回读 ${res.readback} → node.value=${node.value}(state=${node.state})`)
+  check('node.value 被写成陈旧回读值 5(既非设定值 20 也非真实上一设定 10)', node.value === 5, `value=${node.value}`)
+  plc.close()
+}
+
+console.log('\n=== C. 写超时(假 PLC 收到即吞):是否 bounded、是否误判 ===')
+{
+  const plc = await startFakePlc({ mode: 'hang' })
+  const cfg = { host: '127.0.0.1', port: plc.port, unitId: 1, register: 0, dataType: 'int16', byteOrder: 'big' }
+  const t0 = Date.now()
+  const res = await modbusTcpDcwDriver.write({ eng: 30, tolerance: writeTolerance(nodeLike), domain: { min: 0, max: 100 }, driverConfig: cfg })
+  const dt = Date.now() - t0
+  console.log(`  返回: ok=${res.ok} message=${res.message} elapsed=${dt}ms`)
+  check('写有硬超时(<=4s 返回,实测 withModbusConn 3s)', dt < 4000, `${dt}ms`)
+  check('超时映射为 ACK 失败(ok=false)', res.ok === false)
+  check('超时时 readback=null(账本/节点值无法判定硬件真实状态)', res.readback === null, `readback=${res.readback}`)
+  plc.close()
+}
+
+console.log(`\nresult: ${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/_audit/dcw-write-mutex.ts

@@ -0,0 +1,157 @@
+/**
+ * 审计实验 1 —— DCW 单节点写在飞互斥 + 周期读互斥(只读:不碰任何源码/数据文件)。
+ *
+ * 驱动真实 DcwNodeRuntime(dcw-runtime.ts),host 全部打桩,统计同一节点的
+ * 并发在飞写/读数;断言心跳重下发(tick)与手动 write() 共享同一 writing 闸门。
+ *
+ * 运行:node --experimental-transform-types scripts/_audit/run.mjs scripts/_audit/dcw-write-mutex.ts
+ */
+import { DcwNode } from '../../server/services/workshop/dcw/dcw-node'
+import { DcwNodeRuntime } from '../../server/services/workshop/dcw/dcw-runtime'
+
+let failures = 0
+function check(name: string, cond: boolean, extra = ''): void {
+  if (cond) {
+    console.log(`  PASS  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+  else {
+    failures++
+    console.log(`  FAIL  ${name}${extra ? ` (${extra})` : ''}`)
+  }
+}
+
+const statusOf = (e: unknown): string => {
+  const s = (e as { status?: number }).status
+  return s ? String(s) : `no-status:${(e as Error)?.message ?? String(e)}`
+}
+
+interface Stats {
+  writeCalls: number
+  readCalls: number
+  inFlightWrites: number
+  maxInFlightWrites: number
+  inFlightReads: number
+  maxInFlightReads: number
+  writeEng: number[]
+  concurrentReadPairs: number
+}
+
+function makeNode(): DcwNode {
+  return DcwNode.fromRow({
+    id: 'n-audit-1',
+    templateRef: 'cw-temp',
+    name: 'audit-node',
+    driver: 'mock',
+    min: 0,
+    max: 200,
+    decimals: 2,
+    holdIntervalMs: 10,
+    readIntervalMs: 1000,
+    enabled: true,
+    lineId: 'ln-audit',
+  })
+}
+
+function makeHarness(opts: { writeDelayMs: number, readDelayMs: number }) {
+  const stats: Stats = {
+    writeCalls: 0,
+    readCalls: 0,
+    inFlightWrites: 0,
+    maxInFlightWrites: 0,
+    inFlightReads: 0,
+    maxInFlightReads: 0,
+    writeEng: [],
+    concurrentReadPairs: 0,
+  }
+  const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+  const host = {
+    running: () => true,
+    defaults: () => ({ holdIntervalMs: 10, readIntervalMs: 1000 }),
+    async executeWrite(node: DcwNode, eng: number) {
+      stats.writeCalls++
+      stats.writeEng.push(eng)
+      stats.inFlightWrites++
+      stats.maxInFlightWrites = Math.max(stats.maxInFlightWrites, stats.inFlightWrites)
+      await sleep(opts.writeDelayMs)
+      stats.inFlightWrites--
+      node.applyWriteResult(eng, true, 'stub ok', new Date().toISOString())
+      return { ok: true, message: 'stub ok', raw: eng, readback: eng }
+    },
+    async executeRead() {
+      stats.readCalls++
+      stats.inFlightReads++
+      stats.maxInFlightReads = Math.max(stats.maxInFlightReads, stats.inFlightReads)
+      if (stats.inFlightReads > 1)
+        stats.concurrentReadPairs++
+      await sleep(opts.readDelayMs)
+      stats.inFlightReads--
+      return { ok: true, value: 1, raw: 1, message: 'stub read', at: new Date().toISOString() }
+    },
+  }
+  return { host, stats }
+}
+
+async function main(): Promise<void> {
+  // ---------- 场景 A:手动写在飞时,保写心跳必须跳过本拍(不得并发) ----------
+  console.log('\n[A] manual write in flight -> tick keep-alive must skip')
+  {
+    const node = makeNode()
+    const { host, stats } = makeHarness({ writeDelayMs: 120, readDelayMs: 0 })
+    const rt = new DcwNodeRuntime(node, host as never)
+    const p = rt.write(50)
+    let tickAt = 1_000_000
+    for (let i = 0; i < 20; i++) {
+      tickAt += 50 // 远超 holdIntervalMs=10,心跳到点
+      rt.tick(tickAt)
+    }
+    const concurrentSecondWrite = await rt.write(60).then(() => 'resolved', e => `rejected:${statusOf(e)}`)
+    const outcome = await p
+    check('manual write ok', outcome.ok === true)
+    check('heartbeat skipped while manual write in flight (executeWrite called once)', stats.writeCalls === 1, `calls=${stats.writeCalls}`)
+    check('max concurrent in-flight writes == 1', stats.maxInFlightWrites === 1, `max=${stats.maxInFlightWrites}`)
+    check('second concurrent manual write rejected with 409', concurrentSecondWrite === 'rejected:409', concurrentSecondWrite)
+  }
+
+  // ---------- 场景 B:手动写结束后,心跳按节奏重下发且仍与手动写互斥 ----------
+  console.log('\n[B] heartbeat re-write shares the same gate')
+  {
+    const node = makeNode()
+    const { host, stats } = makeHarness({ writeDelayMs: 60, readDelayMs: 0 })
+    const rt = new DcwNodeRuntime(node, host as never)
+    await rt.write(80)
+    const callsAfterManual = stats.writeCalls
+    const t = 2_000_100
+    rt.tick(t) // 到点 -> 心跳下发 node.value
+    rt.tick(t) // 同一拍再次 tick:心跳在飞,必须跳过
+    await new Promise(r => setTimeout(r, 5))
+    const second = await rt.write(90).then(() => 'resolved', e => `rejected:${statusOf(e)}`)
+    await new Promise(r => setTimeout(r, 150))
+    check('heartbeat issued at least one write', stats.writeCalls > callsAfterManual, `calls=${stats.writeCalls}`)
+    check('heartbeat wrote current setpoint 80', stats.writeEng.includes(80), JSON.stringify(stats.writeEng))
+    check('manual write during heartbeat in flight rejected with 409', second === 'rejected:409', second)
+    check('max concurrent in-flight writes == 1 (whole scenario)', stats.maxInFlightWrites === 1, `max=${stats.maxInFlightWrites}`)
+  }
+
+  // ---------- 场景 C:周期读的在飞互斥(readNow 与 tick 读) ----------
+  console.log('\n[C] readNow() while periodic read in flight')
+  {
+    const node = makeNode()
+    const { host, stats } = makeHarness({ writeDelayMs: 0, readDelayMs: 120 })
+    const rt = new DcwNodeRuntime(node, host as never)
+    rt.tick(3_000_000) // 触发周期读(不 await)
+    await new Promise(r => setTimeout(r, 10)) // 让周期读进入在飞
+    const res = await rt.readNow().then(() => 'resolved', e => `rejected:${statusOf(e)}`)
+    await new Promise(r => setTimeout(r, 250))
+    check('periodic read started', stats.readCalls >= 1, `readCalls=${stats.readCalls}`)
+    check(
+      'readNow() rejected (expect rejected:409) while periodic read in flight',
+      res === 'rejected:409',
+      `actual=${res}; concurrent read pairs=${stats.concurrentReadPairs}, maxInFlightReads=${stats.maxInFlightReads}`,
+    )
+  }
+
+  console.log(`\nresult: ${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+void main()

package/scripts/_audit/diag-cwd.ts

@@ -0,0 +1,20 @@
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+
+const target = new URL('./.tmp/server/', import.meta.url)
+console.log('[diag] entry file url =', import.meta.url)
+console.log('[diag] rm target =', target.href)
+console.log('[diag] before rm exists =', existsSync(target))
+rmSync(target, { recursive: true, force: true })
+console.log('[diag] after rm exists =', existsSync(target))
+mkdirSync(new URL('./.tmp/server/data/', import.meta.url), { recursive: true })
+
+const chdirTo = new URL('./.tmp/', import.meta.url).pathname.replace(/^\//, '')
+console.log('[diag] chdir target =', chdirTo)
+process.chdir(chdirTo)
+console.log('[diag] cwd =', process.cwd())
+console.log('[diag] cwd contents =', readdirSync(process.cwd()))
+
+const mod = await import('../../server/services/workshop/dcw/recipe-rollback.repo')
+const repo = new mod.RecipeRollBackRepo()
+console.log('[diag] ledger stats =', JSON.stringify(repo.stats()))
+console.log('[diag] data dir contents =', readdirSync(new URL('./.tmp/server/data/', import.meta.url)))