@jjh32456/dsh-longlive 1.6.8 → 1.8.0

package/scripts/surgery-run.cmd

@@ -16,7 +16,7 @@ exit /b 0
 
 :usage
 echo Usage:
-echo   surgery-run.cmd -SessionPath "C:\...\session.v4.jsonl.zstd" -AppPath "<app folder>\DeepSeek Harness.exe" -Confirm TRUNCATE-VISIBLE [options]
+echo   surgery-run.cmd -SessionPath "<session-file>" -AppPath "<app folder>\DeepSeek Harness.exe" -Confirm TRUNCATE-VISIBLE [options]
 echo.
 echo Options:
 echo   -KeepTurns N            default 12

package/scripts/unattended-surgery.ps1

@@ -75,7 +75,7 @@
   powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass `
     -File scripts\unattended-surgery.ps1 `
     -SessionPath "%USERPROFILE%\.dsh\sessions\scope\abc\session.v4.jsonl.zstd" `
-    -AppPath "C:\Program Files\DSH\DSH.exe" -Confirm TRUNCATE-VISIBLE
+    -AppPath "<path-to-DSH-host.exe>" -Confirm TRUNCATE-VISIBLE
 #>
 [CmdletBinding()]
 param(
@@ -576,8 +576,11 @@ if ($RestartDelaySeconds -lt 0 -or $RestartDelaySeconds -gt 86400) {
 if (-not $DryRun -and $Confirm -ne 'TRUNCATE-VISIBLE') {
   Write-StderrAndExit "Refusing to cut: pass -Confirm TRUNCATE-VISIBLE (or use -DryRun)." 2
 }
+if (-not $DryRun -and -not $AppPath -and $env:DSH_APP_PATH) {
+  $AppPath = $env:DSH_APP_PATH
+}
 if (-not $DryRun -and -not $AppPath) {
-  Write-StderrAndExit "Refusing to cut: pass -AppPath <DSH host exe> so the host can be restarted." 2
+  Write-StderrAndExit "Refusing to cut: pass -AppPath <dsh host exe> or set DSH_APP_PATH so the host can be restarted." 2
 }
 if ($AppPath) {
   if (-not (Test-Path -LiteralPath $AppPath -PathType Leaf)) {

package/scripts/verify-card-anchors.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// scripts/verify-card-anchors.mjs — 1.8.0 AutoCard anchor liveness check.
+//
+//   node scripts/verify-card-anchors.mjs [--memory-root <dir>] [--sessions-root <dir>]
+//        [--all | --sample N] [--json] [--out <file>]
+//
+// Reads `.longlive/index/cards.jsonl`, loads the original L0 session for every
+// card anchor, recomputes turnDigest, and labels each card live / stale / missing.
+// Exit 1 when any card is not live (unless --allow-stale for inspection runs).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseSession } from '../src/codec.js';
+import { discoverSessionLogs, extractTurns } from '../src/memory/event-index.js';
+import { readAutoCards, cardsPathOf } from '../src/memory/auto-cards.js';
+
+function dshHome() {
+  const raw = process.env.DSH_HOME;
+  return typeof raw === 'string' && raw.trim() !== '' ? path.resolve(raw.trim()) : path.join(os.homedir(), '.dsh');
+}
+
+function defaultMemoryRoot() {
+  for (const envName of ['DSH_LONGLIVE_MEMORY_ROOT', 'DSH_MEM']) {
+    const value = process.env[envName];
+    if (typeof value === 'string' && value.trim() !== '') return path.resolve(value.trim());
+  }
+  return path.join(dshHome(), 'longlive-memory');
+}
+
+function parseArgs(argv) {
+  const out = { memoryRoot: '', sessionsRoot: '', sample: 0, json: false, out: '', allowStale: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const match = /^--([a-z-]+)(?:=(.*))?$/.exec(arg);
+    if (!match) continue;
+    const [, key, inline] = match;
+    const value = inline !== undefined ? inline : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : '');
+    if (key === 'memory-root') out.memoryRoot = value;
+    else if (key === 'sessions-root') out.sessionsRoot = value;
+    else if (key === 'sample') out.sample = Number.parseInt(value, 10) || 0;
+    else if (key === 'json') out.json = true;
+    else if (key === 'out') out.out = value;
+    else if (key === 'allow-stale') out.allowStale = true;
+  }
+  return out;
+}
+
+/** Discover session files without parsing them (avoid loading 900MB at once). */
+function sessionFiles(sessionsRoot) {
+  const files = new Map();
+  for (const item of discoverSessionLogs([sessionsRoot])) files.set(item.sessionId, item.file);
+  return files;
+}
+
+export function verifyCards({ memoryRoot, sessionsRoot } = {}) {
+  const root = path.resolve(String(memoryRoot ?? ''));
+  const cards = readAutoCards(root);
+  const files = sessionFiles(path.resolve(String(sessionsRoot ?? '')));
+  const items = [];
+  const bySession = new Map();
+  for (const card of cards) {
+    const ids = [card.sessionId, card.anchor?.sessionId].filter(Boolean);
+    const sessionId = ids[0];
+    if (!bySession.has(sessionId)) bySession.set(sessionId, []);
+    bySession.get(sessionId).push(card);
+  }
+  for (const [sessionId, group] of bySession) {
+    let parsed = null;
+    const file = files.get(sessionId);
+    if (file) {
+      try { parsed = parseSession(fs.readFileSync(file)); } catch { parsed = null; }
+    }
+    // Use the same per-turn extraction as the index builder; turnWindowOf would
+    // include preamble events differently and produce false stale digests.
+    const records = new Map();
+    if (parsed) {
+      try {
+        for (const record of extractTurns(parsed.header, parsed.events, parsed.frames, parsed.texts)) {
+          records.set(record.turn, record);
+        }
+      } catch { /* unreadable session => missing below */ }
+    }
+    for (const card of group) {
+      const record = records.get(card.turn);
+      if (!record) {
+        items.push({
+          cardId: card.cardId, eventId: card.eventId, sessionId: card.sessionId, turn: card.turn,
+          status: 'missing', code: parsed ? 'E_TURN_MISSING' : 'E_SESSION_MISSING',
+          expectedDigest: card.anchor.digest, actualDigest: null,
+        });
+        continue;
+      }
+      const anchor = card.anchor;
+      const sameWindow = anchor.seqStart === record.seqStart && anchor.seqEnd === record.seqEnd;
+      const live = sameWindow && anchor.digest === record.digest;
+      items.push({
+        cardId: card.cardId, eventId: card.eventId, sessionId: card.sessionId, turn: card.turn,
+        status: live ? 'live' : 'stale',
+        code: live ? 'OK' : (sameWindow ? 'E_TURN_DIGEST_MISMATCH' : 'E_TURN_WINDOW_MISMATCH'),
+        expectedDigest: anchor.digest,
+        actualDigest: record.digest,
+      });
+    }
+  }
+  const counts = { total: items.length, live: 0, stale: 0, missing: 0 };
+  for (const item of items) counts[item.status] = (counts[item.status] ?? 0) + 1;
+  return { schema: 'card-anchors/v1', memoryRoot: root, cardsFile: cardsPathOf(root), sessions: files.size, counts, items };
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
+if (isMain) {
+  const args = parseArgs(process.argv.slice(2));
+  const memoryRoot = args.memoryRoot !== '' ? args.memoryRoot : defaultMemoryRoot();
+  const sessionsRoot = args.sessionsRoot !== '' ? args.sessionsRoot : path.join(dshHome(), 'sessions');
+  const report = verifyCards({ memoryRoot, sessionsRoot });
+  let items = report.items;
+  if (args.sample > 0 && items.length > args.sample) {
+    items = [...items].sort((a, b) => a.cardId.localeCompare(b.cardId)).slice(0, args.sample);
+  }
+  const output = { ...report, items, sampled: args.sample > 0 && args.sample < report.items.length };
+  const body = args.json || args.out !== '';
+  if (body) {
+    const text = JSON.stringify(output, null, 2);
+    if (args.json) console.log(text);
+    if (args.out !== '') {
+      fs.mkdirSync(path.dirname(path.resolve(args.out)), { recursive: true });
+      fs.writeFileSync(path.resolve(args.out), `${text}\n`, 'utf8');
+    }
+  } else {
+    console.log(`[verify-card-anchors] total=${output.counts.total} live=${output.counts.live} stale=${output.counts.stale} missing=${output.counts.missing}`);
+    for (const item of items.filter((x) => x.status !== 'live').slice(0, 20)) {
+      console.log(`  ${item.status} ${item.cardId} ${item.sessionId}#${item.turn} ${item.code}`);
+    }
+  }
+  if ((output.counts.stale > 0 || output.counts.missing > 0) && !args.allowStale) process.exitCode = 1;
+}

package/src/actions/audit.js

@@ -0,0 +1,125 @@
+// src/actions/audit.js — HMAC 链式审计（M2-G / §12.4 / §12.7）
+//
+// 一行一个 JSON：
+//   {seq,ts,actorId,action,target,beforeHash,afterHash,prevHash,hmac}
+// - seq 严格 +1（从 1 起），prevHash 链接上一行 hmac（首行 GENESIS）；
+// - hmac = HMAC-SHA256(auditKey, 规范化前 8 字段)，auditKey **仅宿主内存**；
+// - 逆序/断链/篡改 → E_AUDIT_BROKEN（校验失败，绝不静默）；
+// - actorId 只记哈希前缀，正文不记（隐私）。
+// 审计 key 不落盘：跨重启延续审计链需要独立服务账号 + OS 凭据库（§13 第二层，1.6.9 不做）。
+
+import path from 'node:path';
+
+import { GENESIS_HASH, actionsDir, appendJsonl, hmacHexFor, readJsonl, sha256Hex, stableStringify } from './fs.js';
+
+export const AUDIT_SCHEMA = 'audit/v1';
+export const AUDIT_FILE = 'actions.log';
+
+export class AuditError extends Error {
+  constructor(code, message, details = undefined) {
+    super(message);
+    this.name = 'AuditError';
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+const AUDIT_FILE_NAME = AUDIT_FILE;
+
+export function auditFilePath(memoryRoot) {
+  return path.join(actionsDir(memoryRoot), AUDIT_FILE_NAME);
+}
+
+/** Canonical string of the 8 signed fields (order fixed; target stringified stably). */
+export function canonicalAuditBody(entry) {
+  return [
+    String(entry.seq),
+    String(entry.ts),
+    String(entry.actorId),
+    String(entry.action),
+    stableStringify(entry.target ?? null),
+    String(entry.beforeHash ?? ''),
+    String(entry.afterHash ?? ''),
+    String(entry.prevHash ?? ''),
+  ].join('\n');
+}
+
+/** Host-only actor identity: hashed prefix only, never the raw id. */
+export function hashActorId(raw) {
+  return `host:${sha256Hex(String(raw ?? 'host')).slice(0, 8)}`;
+}
+
+const hmacFor = hmacHexFor;
+
+/**
+ * Create the audit chain writer/verifier.
+ *
+ * @param {object} options
+ * @param {string} options.memoryRoot
+ * @param {Buffer|string} options.auditKey host-memory key (32B Buffer preferred)
+ * @param {() => Date} [options.now]
+ * @returns {{append:Function, readAll:Function, verify:Function, latest:Function, file:string}}
+ */
+export function createAuditLog(options = {}) {
+  const memoryRoot = String(options.memoryRoot ?? '');
+  const auditKey = options.auditKey;
+  const now = typeof options.now === 'function' ? options.now : () => new Date();
+  const file = auditFilePath(memoryRoot);
+
+  function readAll() {
+    const read = readJsonl(file);
+    return { rows: Array.isArray(read.rows) ? read.rows : [], bad: read.bad ?? 0, exists: read.exists === true };
+  }
+
+  function verify(rows = readAll().rows) {
+    let prevHash = GENESIS_HASH;
+    let prevSeq = 0;
+    for (let index = 0; index < rows.length; index += 1) {
+      const entry = rows[index];
+      if (entry === null || typeof entry !== 'object') {
+        return { ok: false, code: 'E_AUDIT_BROKEN', at: index, reason: 'not-an-object' };
+      }
+      if (entry.seq !== prevSeq + 1) {
+        return { ok: false, code: 'E_AUDIT_BROKEN', at: index, reason: `seq ${entry.seq} != ${prevSeq + 1}` };
+      }
+      if (entry.prevHash !== undefined && entry.prevHash !== prevHash) {
+        return { ok: false, code: 'E_AUDIT_BROKEN', at: index, reason: 'prevHash mismatch' };
+      }
+      const expected = hmacFor(auditKey, canonicalAuditBody(entry));
+      if (entry.hmac !== expected) {
+        return { ok: false, code: 'E_AUDIT_BROKEN', at: index, reason: 'hmac mismatch' };
+      }
+      prevHash = entry.hmac;
+      prevSeq = entry.seq;
+    }
+    return { ok: true, rows: rows.length, lastSeq: prevSeq, lastHash: prevHash };
+  }
+
+  function append({ actorId = 'host', action, target = null, beforeHash = '', afterHash = '' } = {}) {
+    const current = readAll();
+    const checked = verify(current.rows);
+    if (!checked.ok) throw new AuditError('E_AUDIT_BROKEN', '审计链已损坏：拒绝继续追加。', checked);
+    const seq = (current.rows.length > 0 ? current.rows[current.rows.length - 1].seq : 0) + 1;
+    const prevHash = current.rows.length > 0 ? current.rows[current.rows.length - 1].hmac : GENESIS_HASH;
+    const entry = {
+      seq,
+      ts: now().toISOString(),
+      actorId: String(actorId),
+      action: String(action),
+      target,
+      beforeHash: String(beforeHash ?? ''),
+      afterHash: String(afterHash ?? ''),
+      prevHash,
+    };
+    entry.hmac = hmacFor(auditKey, canonicalAuditBody(entry));
+    const written = appendJsonl(file, entry);
+    return { ok: true, seq, entry, file, offset: written.offset };
+  }
+
+  function latest() {
+    const { rows } = readAll();
+    return rows.length > 0 ? rows[rows.length - 1] : null;
+  }
+
+  return { file, readAll, verify, append, latest };
+}

package/src/actions/evidence.js

@@ -0,0 +1,122 @@
+// src/actions/evidence.js — evidence 私有写路径 + HMAC 验签（N38 三写 probe 的靶子）
+//
+// evidence 包只由宿主写：写盘前用**仅宿主内存**的 auditKey 签名，原子写
+// `<memoryRoot>/.longlive/evidence/latest.json`，并把 `packageSha256` 一起落盘供复核。
+// 模型/子脑没有 token、没有 auditKey：
+//   - 走动作门 → 401 `E_NO_CAP`（见 panel-auth.js）；
+//   - 伪造证据（自己拼 JSON + 假签名）→ 验签失败 `E_HMAC_INVALID`，不落盘、不覆盖真证据。
+// 本模块不读取任何凭据文件，也不把 key 写进返回值。
+
+import path from 'node:path';
+
+import { hmacHexFor, readJsonFile, sha256Hex, stableStringify, writeJsonAtomic } from './fs.js';
+
+export const EVIDENCE_SCHEMA = 'evidence-package/v1';
+export const EVIDENCE_DIR = 'evidence';
+export const EVIDENCE_FILE = 'latest.json';
+
+export class EvidenceError extends Error {
+  constructor(code, message, status = 403, details = undefined) {
+    super(message);
+    this.name = 'EvidenceError';
+    this.code = code;
+    this.status = status;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function evidenceFilePath(memoryRoot) {
+  return path.join(String(memoryRoot ?? ''), '.longlive', EVIDENCE_DIR, EVIDENCE_FILE);
+}
+
+function canonicalEvidencePayload(pkg) {
+  return stableStringify(pkg ?? null);
+}
+
+/**
+ * Create the host-side evidence writer.
+ *
+ * @param {object} options
+ * @param {string} options.memoryRoot
+ * @param {Buffer|string} options.auditKey host-memory signing key (never serialized)
+ * @param {() => Date} [options.now]
+ */
+export function createEvidenceWriter(options = {}) {
+  const memoryRoot = String(options.memoryRoot ?? '');
+  const auditKey = options.auditKey;
+  const now = typeof options.now === 'function' ? options.now : () => new Date();
+  const file = evidenceFilePath(memoryRoot);
+
+  if (!auditKey) throw new EvidenceError('E_NO_CAP', '缺少宿主签名 key：evidence 只允许宿主进程写。', 401);
+
+  function sign(pkg) {
+    return hmacHexFor(auditKey, canonicalEvidencePayload(pkg));
+  }
+
+  function persist(pkg, signature, source) {
+    const packageSha256 = sha256Hex(canonicalEvidencePayload(pkg));
+    const record = {
+      schemaVersion: EVIDENCE_SCHEMA,
+      package: pkg,
+      packageSha256,
+      signature,
+      signatureSource: source,
+      writtenAt: now().toISOString(),
+    };
+    writeJsonAtomic(file, record);
+    return {
+      ok: true,
+      path: file,
+      packageSha256,
+      fileSha256: sha256Hex(JSON.stringify(record)),
+    };
+  }
+
+  /** Host path: sign with the in-memory key, then write (N38 host probe). */
+  function writeHost(pkg) {
+    if (pkg === null || typeof pkg !== 'object') {
+      throw new EvidenceError('E_EVIDENCE_INVALID', 'evidence 包必须是对象。', 422);
+    }
+    return persist(pkg, sign(pkg), 'host');
+  }
+
+  /**
+   * Any caller may submit a package + signature, but only a host-signed one
+   * verifies. A forged signature fails closed with `E_HMAC_INVALID`.
+   */
+  function submitSigned({ pkg, signature } = {}) {
+    if (pkg === null || typeof pkg !== 'object') {
+      throw new EvidenceError('E_EVIDENCE_INVALID', 'evidence 包必须是对象。', 422);
+    }
+    if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature)) {
+      throw new EvidenceError('E_HMAC_INVALID', 'evidence 签名缺失或格式非法：拒绝写入。', 403);
+    }
+    const expected = sign(pkg);
+    if (signature.toLowerCase() !== expected) {
+      throw new EvidenceError('E_HMAC_INVALID', 'evidence 验签失败：拒绝写入（真证据未被覆盖）。', 403);
+    }
+    return persist(pkg, expected, 'host');
+  }
+
+  /** Re-read + re-verify the on-disk evidence (used by probe/action returns). */
+  function readLatest() {
+    const read = readJsonFile(file);
+    if (!read.ok) return { ok: false, present: false, code: read.code };
+    const record = read.value;
+    const packageSha256 = record?.package === undefined ? null : sha256Hex(canonicalEvidencePayload(record.package));
+    const signatureValid = typeof record?.signature === 'string'
+      && record.signature === sign(record.package);
+    return {
+      ok: signatureValid && packageSha256 === record.packageSha256,
+      present: true,
+      schemaVersion: record?.schemaVersion ?? null,
+      package: record?.package ?? null,
+      packageSha256,
+      recordedSha256: record?.packageSha256 ?? null,
+      signatureValid,
+      writtenAt: record?.writtenAt ?? null,
+    };
+  }
+
+  return { file, writeHost, submitSigned, readLatest, signPackage: sign };
+}

package/src/actions/fs.js

@@ -0,0 +1,162 @@
+// src/actions/fs.js — 动作层私有文件原语（1.6.9 Gate-1）
+//
+// 动作/审计/证据只写宿主私有目录：`<memoryRoot>/.longlive/{actions,evidence,distill,protected.json,...}`。
+// 全部写入走 tmp + fsync + 读回校验 + rename；读取对坏行只计数不抛错。
+// 不依赖任何第三方包，不联网。
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ACTIONS_DIR = 'actions';
+export const GENESIS_HASH = '0'.repeat(64);
+
+export function sha256Hex(value) {
+  return crypto.createHash('sha256').update(typeof value === 'string' ? value : Buffer.from(value)).digest('hex');
+}
+
+/** HMAC-SHA256 hex. Used by the audit chain and the evidence signature. */
+export function hmacHexFor(key, text) {
+  return crypto.createHmac('sha256', key).update(String(text), 'utf8').digest('hex');
+}
+
+export function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/** Atomic JSON write (tmp + fsync + read-back + rename). */
+export function writeJsonAtomic(file, value) {
+  const dir = path.dirname(file);
+  ensureDir(dir);
+  const text = `${JSON.stringify(value, null, 2)}\n`;
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeFileSync(fd, text, 'utf8');
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      /* best effort on some filesystems */
+    }
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
+    }
+  }
+  const readBack = fs.readFileSync(tmp, 'utf8');
+  if (readBack !== text) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* ignore */
+    }
+    throw new Error('E_WRITE_READBACK');
+  }
+  fs.renameSync(tmp, file);
+  return { file, bytes: Buffer.byteLength(text, 'utf8') };
+}
+
+export function readJsonFile(file) {
+  try {
+    return { ok: true, value: JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch (error) {
+    return { ok: false, code: error?.code === 'ENOENT' ? 'ENOENT' : (error?.code ?? 'E_READ') };
+  }
+}
+
+/** Append one JSON line, fsynced. Returns the byte offset before the append. */
+export function appendJsonl(file, value) {
+  ensureDir(path.dirname(file));
+  const text = `${JSON.stringify(value)}\n`;
+  const before = fs.existsSync(file) ? fs.statSync(file).size : 0;
+  const fd = fs.openSync(file, 'a');
+  try {
+    fs.writeFileSync(fd, text, 'utf8');
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      /* best effort */
+    }
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
+    }
+  }
+  return { file, bytes: Buffer.byteLength(text, 'utf8'), offset: before };
+}
+
+/** Read JSONL defensively: `{rows, bad, exists}`; never throws on bad lines. */
+export function readJsonl(file) {
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return { rows: [], bad: 0, exists: false, code: error?.code === 'ENOENT' ? 'ENOENT' : (error?.code ?? 'E_READ') };
+  }
+  const rows = [];
+  let bad = 0;
+  for (const line of text.replace(/^\uFEFF/, '').split(/\r?\n/)) {
+    if (line.trim() === '') continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      bad += 1;
+    }
+  }
+  return { rows, bad, exists: true };
+}
+
+/** Atomic JSONL rewrite (tmp + read-back + rename). */
+export function writeJsonlAtomic(file, rows) {
+  const dir = path.dirname(file);
+  ensureDir(dir);
+  const text = Array.isArray(rows) && rows.length > 0 ? `${rows.map((row) => JSON.stringify(row)).join('\n')}\n` : '';
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeFileSync(fd, text, 'utf8');
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      /* best effort */
+    }
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* ignore */
+    }
+  }
+  const readBack = fs.readFileSync(tmp, 'utf8');
+  if (readBack !== text) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* ignore */
+    }
+    throw new Error('E_WRITE_READBACK');
+  }
+  fs.renameSync(tmp, file);
+  return { file, bytes: Buffer.byteLength(text, 'utf8') };
+}
+
+export function newId(prefix) {
+  const stamp = new Date().toISOString().replace(/[-:TZ.]/g, '').slice(0, 14);
+  return `${prefix}_${stamp}_${crypto.randomBytes(3).toString('hex')}`;
+}
+
+/** Directory of this memory root's private action state. */
+export function actionsDir(memoryRoot) {
+  return path.join(String(memoryRoot ?? ''), '.longlive', ACTIONS_DIR);
+}