@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/src/state-ledger.js

@@ -1,3 +1,33 @@
+/**
+ * 事务化状态账本(ADR-15,docs/rfc/transactional-state-rfc.md):
+ * 「文件即权威」→「单文件 SQLite 账本即权威」。
+ *
+ *   - events 表 = 唯一权威(append-only;语义幂等键物理化为 UNIQUE 索引)
+ *   - 投影表(projection_docs/items)= 日志的确定性 fold,可随时 DROP 重建
+ *   - 红线进事务:evidence/conditions 校验发生在写事务内,拒绝即回滚账本无痕
+ *   - 一次写 = 单事务{INSERT event; UPDATE 投影},跨文件分叉在物理上不可能
+ *   - 语义层零改造:mergeProfile/appendTrip/upsertCompanion/appendEvent 纯函数
+ *     原样复用为写路径守门与 fold 处理器(memory-design §1.6「账本化只换存储面」)
+ *
+ * 迁移纪律(D2 one-shot):旧 JSON/JSONL 文件在首次写时自动导入为 events
+ * (单事务 + 导入前快照到 gotry-state/pre-ledger-backup/);此后文件降级为
+ * 导出视图(state-cli export),永不再回流。读路径带文件回退(未迁移 root
+ * 仍可读旧文件),写路径必经账本——工具外无写入路径。
+ *
+ * 引擎:better-sqlite3(复用矩阵 open-source import 通道),WAL + NORMAL,
+ * 同步 API 与仓内 readFileSync 风格一致;busy_timeout 容忍跨进程
+ * (dsh 运行时 / async-collect / state-cli tick 并存)。
+ *
+ * 跨进程争用纪律(D-15 演练 D15-1/D15-2 的修复,issue #275 已于 2026-10-05
+ * 作为 deferred 关闭——触发出现时另开新 issue):
+ *   - busy_timeout 必须在任何可争用语句之前装好(含 journal_mode = WAL);
+ *   - 建表/迁移整段在 BEGIN IMMEDIATE 里做,版本探测与建表同处一个写锁;
+ *   - 读改写事务一律 BEGIN IMMEDIATE(先读后写的 DEFERRED 事务升级锁时,
+ *     SQLite 直接返回 SQLITE_BUSY_SNAPSHOT 且不调用 busy handler);
+ *   - 争用重试有界,耗尽后抛 LedgerBusyError(典型化),不再漏裸 SQLITE_BUSY*。
+ * 单写者产品形态(ADR-16 一个账本一个 owner)本来就不会走到这些竞态,
+ * 以上只改争用路径的行为,单进程行为逐字节不变。
+ */
 import Database from 'better-sqlite3';
 import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
@@ -6,13 +36,15 @@ import { mergeProfile } from './memory-capture.js';
 import { appendEvent as gateUtilityEvent, projectUtility } from './memory-utility.js';
 import { appendTrip as gateTrip } from './travel-timeline.js';
 import { upsertCompanion } from './companions.js';
-const SCHEMA_VERSION = '1';
+const SCHEMA_VERSION = '2';
+/** 稳定 wish 主键:名称语义派生(重放/同名幂等更新不再依赖墙钟;RFC §1.1 id 不稳定缺口的修复) */
 export function makeWishId(name) {
     return 'w-' + createHash('sha256').update(String(name).trim()).digest('hex').slice(0, 10);
 }
 function sha(s) {
     return createHash('sha256').update(s).digest('hex');
 }
+/** stateRoot 可相对可绝对(与 incident-log.resolveIncidentsPath 同款解析) */
 function stateDirOf(stateRoot) {
     const root = isAbsolute(stateRoot) ? stateRoot : join(process.cwd(), stateRoot);
     return join(root, 'gotry-state');
@@ -23,23 +55,115 @@ export function ledgerDbPath(stateRoot) {
 export function ledgerExists(stateRoot) {
     return existsSync(ledgerDbPath(stateRoot));
 }
-const LEGACY_FILES = [
-    'motivation-profile.json',
-    'wish-pool.json',
-    'memory-utility.jsonl',
-    'trips.jsonl',
-    'companions.json'
-];
+const LEGACY_FILES = ['motivation-profile.json', 'wish-pool.json', 'memory-utility.jsonl', 'trips.jsonl', 'companions.json'];
 function legacyFilesPresent(stateRoot) {
     const dir = stateDirOf(stateRoot);
-    return LEGACY_FILES.some((f)=>existsSync(join(dir, f)));
+    return LEGACY_FILES.some(f => existsSync(join(dir, f)));
 }
 function isUniqueViolation(e) {
     return e instanceof Error && e.code === 'SQLITE_CONSTRAINT_UNIQUE';
 }
+// ---- 跨进程争用:有界重试 + 典型化出口(D15-1/D15-2) --------------------------
+/** 写锁等待上限;跨进程(dsh 运行时 / async-collect / state-cli tick)共存的容忍面。 */
+const BUSY_TIMEOUT_MS = 5_000;
+/** 争用重试次数上限(首次尝试之外);退避总额 < 400ms,宁可早报错也不无限等。 */
+const CONTENTION_RETRIES = 5;
+/**
+ * 打开路径(WAL 切换 / 建表迁移)另按**墙钟**封顶:冷启动竞赛里失败往往是立即
+ * 抛出(busy handler 根本没被调用),次数上限会退化成「次数 × busy_timeout」那么长。
+ * 一次 open 最多争用 5s —— 正好等于 busy_timeout 的语义,然后给典型化错误。
+ */
+const OPEN_CONTENTION_BUDGET_MS = 5_000;
+const OPEN_CONTENTION_RETRIES = 20;
+/**
+ * SQLite 把「此刻拿不到锁」编码成这几个码:
+ *   SQLITE_BUSY / _TIMEOUT      写锁被别的连接占着(busy handler 已耗尽)
+ *   SQLITE_BUSY_SNAPSHOT        读快照过期、无法升级为写(DEFERRED 读改写的死法)
+ *   SQLITE_BUSY_RECOVERY        WAL 正在被别的连接恢复
+ *   SQLITE_PROTOCOL             WAL index(-shm)争用导致的锁协议重试
+ * 只有这几个码允许重试;其余码(约束冲突/IO 错误/逻辑错)一律原样抛出——
+ * 真错误不得被重试掩盖成「忙」。
+ */
+const CONTENTION_CODES = new Set([
+    'SQLITE_BUSY',
+    'SQLITE_BUSY_TIMEOUT',
+    'SQLITE_BUSY_SNAPSHOT',
+    'SQLITE_BUSY_RECOVERY',
+    'SQLITE_PROTOCOL',
+]);
+function sqliteCodeOf(e) {
+    const code = e?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function isContention(e) {
+    const code = sqliteCodeOf(e);
+    return code !== undefined && CONTENTION_CODES.has(code);
+}
+/**
+ * 典型化的账本争用错误:有界重试耗尽后的唯一出口。
+ *
+ * 修复前跨进程争用会把 better-sqlite3 的裸 SQLITE_BUSY / SQLITE_BUSY_SNAPSHOT
+ * 直接扔给调用方(D15-1/D15-2),调用方只能嗅探字符串码。现在调用方可以
+ * `instanceof LedgerBusyError` 判定「只是忙、可稍后再来」,底层码仍保留在
+ * `sqliteCode`/`cause` 里供诊断。
+ */
+export class LedgerBusyError extends Error {
+    /** 与 better-sqlite3 的 `code` 面同形,便于统一嗅探;永不与 SQLITE_* 撞名。 */
+    code = 'GOTRY_LEDGER_BUSY';
+    op;
+    attempts;
+    sqliteCode;
+    constructor(op, attempts, cause) {
+        super(`ledger busy: ${op} 在 ${attempts} 次尝试后仍未取得写锁(末次 SQLite 码 ${sqliteCodeOf(cause) ?? 'unknown'})`, { cause });
+        this.name = 'LedgerBusyError';
+        this.op = op;
+        this.attempts = attempts;
+        this.sqliteCode = sqliteCodeOf(cause);
+    }
+}
+/** 同步退避:better-sqlite3 全同步,不能 await;Atomics.wait 是仓内既有惯用法。 */
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** 指数退避 + pid 抖动:N 个进程同时冷启动时不会同节奏再撞第二次。 */
+function backoffMs(attempt) {
+    return Math.min(5 * 2 ** attempt, 160) + (process.pid % 11);
+}
+/**
+ * 有界重试争用码,耗尽即抛 LedgerBusyError。
+ *
+ * 只对「整体提交或整体回滚」的单元使用:事务函数回滚后守门纯函数会重新读当前
+ * 状态再算一遍,所以重跑是幂等的(事件另有 idem_key UNIQUE 兜底)。
+ */
+function withContentionRetry(op, fn, opts = {}) {
+    const retries = opts.retries ?? CONTENTION_RETRIES;
+    const deadline = opts.budgetMs === undefined ? undefined : Date.now() + opts.budgetMs;
+    let lastError;
+    let attempts = 0;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        attempts += 1;
+        try {
+            return fn();
+        }
+        catch (e) {
+            if (!isContention(e))
+                throw e;
+            lastError = e;
+            if (attempt >= retries)
+                break;
+            if (deadline !== undefined && Date.now() >= deadline)
+                break;
+            sleepSync(backoffMs(attempt));
+        }
+    }
+    throw new LedgerBusyError(op, attempts, lastError);
+}
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS events (
   seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
   ts TEXT NOT NULL,
   actor TEXT NOT NULL,
   kind TEXT NOT NULL,
@@ -48,48 +172,56 @@ CREATE TABLE IF NOT EXISTS events (
   idem_key TEXT,
   run_id TEXT
 );
-CREATE UNIQUE INDEX IF NOT EXISTS events_idem ON events(idem_key) WHERE idem_key IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS events_idem ON events(tenant_id, idem_key) WHERE idem_key IS NOT NULL;
 
 CREATE TABLE IF NOT EXISTS projection_docs (
-  subject TEXT PRIMARY KEY,
-  doc TEXT NOT NULL
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  subject TEXT NOT NULL,
+  doc TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, subject)
 );
 CREATE TABLE IF NOT EXISTS projection_items (
+  tenant_id TEXT NOT NULL DEFAULT 'local',
   subject TEXT NOT NULL,
   item_id TEXT NOT NULL,
   doc TEXT NOT NULL,
   ord INTEGER NOT NULL DEFAULT 0,
-  PRIMARY KEY (subject, item_id)
+  PRIMARY KEY (tenant_id, subject, item_id)
 );
 
 CREATE TABLE IF NOT EXISTS workflow_runs (
-  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  id TEXT NOT NULL,
   goal TEXT NOT NULL,
   status TEXT NOT NULL CHECK (status IN ('pending','settled','failed')),
   ticket_json TEXT NOT NULL,
   state_json TEXT NOT NULL,
   deliverable TEXT,
   created TEXT NOT NULL,
-  updated TEXT NOT NULL
+  updated TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, id)
 );
 CREATE TABLE IF NOT EXISTS workflow_steps (
+  tenant_id TEXT NOT NULL DEFAULT 'local',
   run_id TEXT NOT NULL,
   name TEXT NOT NULL,
   status TEXT NOT NULL CHECK (status IN ('intent','done','failed')),
   result TEXT,
   intent_ts TEXT NOT NULL,
   done_ts TEXT,
-  PRIMARY KEY (run_id, name)
+  PRIMARY KEY (tenant_id, run_id, name)
 );
 
 CREATE TABLE IF NOT EXISTS pending_writes (
-  idem_key TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL DEFAULT 'local',
+  idem_key TEXT NOT NULL,
   seam TEXT NOT NULL,
   payload TEXT NOT NULL,
   status TEXT NOT NULL CHECK (status IN ('pending','confirmed','compensated')),
   receipt TEXT,
   created TEXT NOT NULL,
-  updated TEXT NOT NULL
+  updated TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, idem_key)
 );
 
 CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL);
@@ -97,101 +229,131 @@ CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v TEXT NOT NULL);
 export class StateLedger {
     db;
     stateRoot;
+    tenant;
     dbPath;
-    constructor(db, stateRoot){
+    constructor(db, stateRoot, tenant = 'local') {
         this.db = db;
         this.stateRoot = stateRoot;
+        this.tenant = tenant;
         this.dbPath = ledgerDbPath(stateRoot);
     }
+    // ---- 基础事件面 ------------------------------------------------------------
+    /** 事件插入(idem 命中 → 返回 null,不抛;红线校验异常向上抛 = 事务回滚) */
     insertEvent(ev) {
-        const stmt = this.db.prepare(`INSERT INTO events (ts, actor, kind, subject_id, payload, idem_key, run_id)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        const stmt = this.db.prepare(`INSERT INTO events (tenant_id, ts, actor, kind, subject_id, payload, idem_key, run_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
         try {
-            const info = stmt.run(ev.ts ?? new Date().toISOString(), ev.actor, ev.kind, ev.subjectId ?? '', JSON.stringify(ev.payload), ev.idemKey ?? null, ev.runId ?? null);
+            const info = stmt.run(this.tenant, ev.ts ?? new Date().toISOString(), ev.actor, ev.kind, ev.subjectId ?? '', JSON.stringify(ev.payload), ev.idemKey ?? null, ev.runId ?? null);
             return Number(info.lastInsertRowid);
-        } catch (e) {
-            if (isUniqueViolation(e)) return null;
+        }
+        catch (e) {
+            if (isUniqueViolation(e))
+                return null;
             throw e;
         }
     }
     readEvents(kind, limit = 100) {
-        const where = kind ? 'WHERE kind = ?' : '';
-        const rows = this.db.prepare(`SELECT seq, ts, actor, kind, subject_id, payload, idem_key, run_id
-       FROM events ${where} ORDER BY seq DESC LIMIT ?`).all(...kind ? [
-            kind,
-            limit
-        ] : [
-            limit
-        ]);
+        const rows = kind
+            ? this.db.prepare(`SELECT seq, tenant_id, ts, actor, kind, subject_id, payload, idem_key, run_id
+           FROM events WHERE tenant_id = ? AND kind = ? ORDER BY seq DESC LIMIT ?`).all(this.tenant, kind, limit)
+            : this.db.prepare(`SELECT seq, tenant_id, ts, actor, kind, subject_id, payload, idem_key, run_id
+           FROM events WHERE tenant_id = ? ORDER BY seq DESC LIMIT ?`).all(this.tenant, limit);
         return rows;
     }
     countEvents() {
-        return this.db.prepare('SELECT COUNT(*) AS n FROM events').get().n;
+        return this.db.prepare('SELECT COUNT(*) AS n FROM events WHERE tenant_id = ?').get(this.tenant).n;
     }
+    // ---- 读:投影与日志类事件 ----------------------------------------------------
     readMotivation() {
-        const row = this.db.prepare(`SELECT doc FROM projection_docs WHERE subject = 'motivation'`).get();
+        const row = this.db.prepare(`SELECT doc FROM projection_docs WHERE subject = 'motivation' AND tenant_id = ?`).get(this.tenant);
         return row ? JSON.parse(row.doc) : null;
     }
     readWishPool() {
-        const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'wish_pool' ORDER BY ord, rowid`).all();
-        return rows.map((r)=>JSON.parse(r.doc));
+        const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'wish_pool' AND tenant_id = ? ORDER BY ord, rowid`).all(this.tenant);
+        return rows.map(r => JSON.parse(r.doc));
     }
     readCompanions() {
-        const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'companions' ORDER BY ord, rowid`).all();
-        return rows.map((r)=>JSON.parse(r.doc));
+        const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'companions' AND tenant_id = ? ORDER BY ord, rowid`).all(this.tenant);
+        return rows.map(r => JSON.parse(r.doc));
     }
     readUtilityEvents() {
-        const rows = this.db.prepare(`SELECT payload FROM events WHERE kind = 'memory_utility.event' ORDER BY seq`).all();
-        return rows.map((r)=>JSON.parse(r.payload).event);
+        const rows = this.db.prepare(`SELECT payload FROM events WHERE kind = 'memory_utility.event' AND tenant_id = ? ORDER BY seq`).all(this.tenant);
+        return rows.map(r => JSON.parse(r.payload).event);
     }
     readTrips() {
-        const rows = this.db.prepare(`SELECT payload FROM events WHERE kind = 'trip.logged' ORDER BY seq`).all();
-        return rows.map((r)=>JSON.parse(r.payload).trip);
+        const rows = this.db.prepare(`SELECT payload FROM events WHERE kind = 'trip.logged' AND tenant_id = ? ORDER BY seq`).all(this.tenant);
+        return rows.map(r => JSON.parse(r.payload).trip);
     }
+    /** 效用投影(与文件版 projectUtility 同源同构) */
     projectUtilityNow() {
         return projectUtility(this.readUtilityEvents());
     }
+    // ---- 写:单事务{INSERT event; UPDATE 投影},守门纯函数原样复用 -----------------
+    // 红线进事务:evidence 缺失/conditions 空 → mergeProfile/校验拒绝 → 事务回滚,账本无痕。
+    /**
+     * 读改写事务的统一出口(D15-2 修复)。
+     *
+     * 为什么必须 BEGIN IMMEDIATE:DEFERRED 事务的第一条语句是 SELECT 时,SQLite 只
+     * 取读快照;等后面要写时若已有别的写者提交过,快照无法升级,SQLite **立即**返回
+     * SQLITE_BUSY_SNAPSHOT 并且**不调用 busy handler**(等待毫无意义,快照已过期)。
+     * 所以 busy_timeout 对这条路径完全无效——演练里 appendWish 需要调用方自己重试
+     * 6~9 次才做完 12 次尝试,就是这个原因。IMMEDIATE 开头就拿写锁,后来者改为在
+     * busy handler 里排队等待,SQLITE_BUSY_SNAPSHOT 在物理上不再可能出现。
+     *
+     * 重试是 IMMEDIATE 之外的第二道兜底(busy_timeout 真被耗尽时),整体回滚后重算,
+     * 幂等;耗尽 → LedgerBusyError。已在外层事务里(嵌套 = SAVEPOINT,模式被
+     * better-sqlite3 忽略)时不自行重试:重试归最外层事务所有,否则会在一个已经
+     * 注定回滚的事务里空转。
+     */
+    runWrite(op, fn) {
+        const run = this.db.transaction(fn);
+        if (this.db.inTransaction)
+            return run.immediate();
+        return withContentionRetry(`ledger.${op}`, () => run.immediate());
+    }
+    /**
+     * 全量事务审计(D15-2):判据只有一条——**事务的第一条语句是不是 SELECT**。
+     * 是 → 先读后写,会撞 SQLITE_BUSY_SNAPSHOT,必须走 runWrite(IMMEDIATE+有界重试);
+     * 不是(INSERT/UPDATE/DELETE 开头)→ 写锁在第一条语句就拿到,快照升级在物理上
+     * 不会发生,维持 DEFERRED 逐字节同义,不扩大改动面。
+     *
+     *   runWrite(IMMEDIATE)  appendMotivationPatch  readMotivation 开头
+     *                        appendWish             readWishPool 开头(演练实测失败点)
+     *                        appendTripEvent        readTrips 开头
+     *                        appendCompanion        readCompanions 开头
+     *                        confirmOutcome         full 为空时以 readTrips 开头
+     *                        importLegacyInto       SELECT kv.legacy_imported_v1 开头
+     *   维持 DEFERRED        appendUtilityEvent     单条 INSERT
+     *                        rebuildProjections     DELETE 投影开头(读在写锁之内)
+     *                        createWorkflowRun      INSERT workflow_runs 开头
+     *                        finishWorkflowRun      UPDATE workflow_runs 开头
+     *                        requestPendingWrite    INSERT pending_writes 开头
+     *                        confirmPendingWrite    UPDATE pending_writes 开头
+     *                        compensatePendingWrite UPDATE pending_writes 开头
+     *                        forgetSubject          DELETE events 开头
+     * openDb 的建表/迁移事务另见 ensureSchema(D15-1)。
+     */
+    /** 动机画像增量补丁(守门 = mergeProfile:追加不删史/幂等/权重变更须伴新证据) */
     appendMotivationPatch(patch, actor = 'tool:gotry_motivation_save') {
+        // 事件边界 ISO:事件行的 ts 就是 homeCityPreference.updated_at 的源头,
+        // fold 路径会读同一字段回放——rebuildProjections 必须能复现该值。
         const ts = new Date().toISOString();
-        const run = this.db.transaction(()=>{
+        // 读改写(readMotivation → mergeProfile → 写投影):第一条语句是 SELECT → IMMEDIATE。
+        return this.runWrite('appendMotivationPatch', () => {
             const current = this.readMotivation();
-            const merged = mergeProfile(current, patch);
+            const merged = mergeProfile(current, patch, ts);
             if (!merged) {
-                const unchanged = {
-                    ...current ?? {
-                        weights: {},
-                        evidence: [],
-                        hard: {}
-                    },
-                    updated_at: current?.updated_at ?? ts
-                };
-                return {
-                    saved: false,
-                    profile: unchanged
-                };
+                const unchanged = { ...(current ?? { weights: {}, evidence: [], hard: {} }), updated_at: current?.updated_at ?? ts };
+                return { saved: false, profile: unchanged };
             }
-            const doc = {
-                ...merged,
-                updated_at: ts
-            };
-            this.insertEvent({
-                actor,
-                kind: 'motivation.patch',
-                subjectId: 'motivation',
-                payload: {
-                    patch
-                },
-                ts
-            });
-            this.db.prepare(`INSERT INTO projection_docs (subject, doc) VALUES ('motivation', ?)
-         ON CONFLICT(subject) DO UPDATE SET doc = excluded.doc`).run(JSON.stringify(doc));
-            return {
-                saved: true,
-                profile: doc
-            };
+            const doc = { ...merged, updated_at: ts };
+            this.insertEvent({ actor, kind: 'motivation.patch', subjectId: 'motivation', payload: { patch }, ts });
+            this.db.prepare(`INSERT INTO projection_docs (tenant_id, subject, doc) VALUES (?, 'motivation', ?)
+         ON CONFLICT(tenant_id, subject) DO UPDATE SET doc = excluded.doc`).run(this.tenant, JSON.stringify(doc));
+            return { saved: true, profile: doc };
         });
-        return run();
     }
+    /** 愿望入池/同名幂等更新(红线:conditions 必填非空) */
     appendWish(entry, actor = 'tool:gotry_wish_pool_add') {
         const name = String(entry.name ?? '').trim();
         const conditions = entry.conditions;
@@ -199,9 +361,11 @@ export class StateLedger {
             throw new Error('wish pool entry requires name and conditions (fulfilment conditions are the whole point)');
         }
         const ts = new Date().toISOString();
-        const run = this.db.transaction(()=>{
+        // 读改写(readWishPool → 同名判定 → 写事件+投影):第一条语句是 SELECT → IMMEDIATE。
+        // 这是 D15-2 演练里实际失败的那条路径。
+        return this.runWrite('appendWish', () => {
             const pool = this.readWishPool();
-            const existing = pool.find((w)=>String(w.name ?? '') === name);
+            const existing = pool.find(w => String(w.name ?? '') === name);
             if (existing) {
                 const id = typeof existing.wish_id === 'string' && existing.wish_id ? existing.wish_id : makeWishId(name);
                 const next = {
@@ -209,32 +373,11 @@ export class StateLedger {
                     wish_id: id,
                     reason: entry.reason !== undefined ? entry.reason : existing.reason,
                     conditions,
-                    ...entry.muted !== undefined ? {
-                        muted: Boolean(entry.muted)
-                    } : {}
+                    ...(entry.muted !== undefined ? { muted: Boolean(entry.muted) } : {}),
                 };
-                this.insertEvent({
-                    actor,
-                    kind: 'wish.updated',
-                    subjectId: id,
-                    payload: {
-                        wish_id: id,
-                        patch: {
-                            reason: next.reason,
-                            conditions,
-                            ...entry.muted !== undefined ? {
-                                muted: Boolean(entry.muted)
-                            } : {}
-                        }
-                    },
-                    ts
-                });
+                this.insertEvent({ actor, kind: 'wish.updated', subjectId: id, payload: { wish_id: id, patch: { reason: next.reason, conditions, ...(entry.muted !== undefined ? { muted: Boolean(entry.muted) } : {}) } }, ts });
                 this.upsertItem('wish_pool', id, next);
-                return {
-                    added: false,
-                    wish_id: id,
-                    total: pool.length
-                };
+                return { added: false, wish_id: id, total: pool.length };
             }
             const id = makeWishId(name);
             const doc = {
@@ -242,607 +385,636 @@ export class StateLedger {
                 name,
                 reason: entry.reason ?? '',
                 conditions,
-                ...entry.muted !== undefined ? {
-                    muted: Boolean(entry.muted)
-                } : {},
-                added_at: ts
+                ...(entry.muted !== undefined ? { muted: Boolean(entry.muted) } : {}),
+                added_at: ts,
             };
-            const seq = this.insertEvent({
-                actor,
-                kind: 'wish.added',
-                subjectId: id,
-                payload: {
-                    wish: doc
-                },
-                ts
-            });
+            const seq = this.insertEvent({ actor, kind: 'wish.added', subjectId: id, payload: { wish: doc }, ts });
             this.insertItem('wish_pool', id, doc, seq ?? 0);
-            return {
-                added: true,
-                wish_id: id,
-                total: pool.length + 1
-            };
+            return { added: true, wish_id: id, total: pool.length + 1 };
         });
-        return run();
     }
+    /** 效用事件(幂等键 = 语义 event_id;verified 无归因自动降级 applied——纯函数同款纪律) */
     appendUtilityEvent(ev, actor = 'tool:gotry_wish_pool_list') {
         const full = gateUtilityEvent([], ev).events[0];
-        if (!full) return {
-            appended: false,
-            events: this.readUtilityEvents()
-        };
-        const run = this.db.transaction(()=>{
-            return this.insertEvent({
-                actor,
-                kind: 'memory_utility.event',
-                subjectId: full.wish_id,
-                payload: {
-                    event: full
-                },
-                idemKey: `mu:${full.event_id}`
-            }) !== null;
+        if (!full)
+            return { appended: false, events: this.readUtilityEvents() };
+        // 非读改写:事务内只有一条 INSERT,写锁在第一条语句就拿到,不存在快照升级。
+        // 维持 DEFERRED(与修复前逐字节同义),争用只会落到 busy_timeout 等待上。
+        const run = this.db.transaction(() => {
+            return this.insertEvent({ actor, kind: 'memory_utility.event', subjectId: full.wish_id, payload: { event: full }, idemKey: `mu:${full.event_id}` }) !== null;
         });
-        return {
-            appended: run(),
-            events: this.readUtilityEvents()
-        };
+        return { appended: run(), events: this.readUtilityEvents() };
     }
+    /** 时间线行程(守门 = appendTrip:必填/绝对日期/重叠冲突即停;幂等键 = trip_id) */
     appendTripEvent(ev, actor = 'tool:gotry_trip_log') {
-        const run = this.db.transaction(()=>{
+        // 读改写(readTrips → 重叠冲突判定 → 写事件):第一条语句是 SELECT → IMMEDIATE。
+        // 重叠判定必须看见提交后的全量行程,否则两个进程可以各写一条互相重叠的行程。
+        return this.runWrite('appendTripEvent', () => {
             const existing = this.readTrips();
             const gate = gateTrip(existing, ev);
-            if (!gate.appended) return {
-                appended: false,
-                tripId: gate.tripId,
-                reason: gate.reason,
-                total: existing.length
-            };
+            if (!gate.appended)
+                return { appended: false, tripId: gate.tripId, reason: gate.reason, total: existing.length };
             const full = gate.events[gate.events.length - 1];
-            this.insertEvent({
-                actor,
-                kind: 'trip.logged',
-                subjectId: full.trip_id,
-                payload: {
-                    trip: full
-                },
-                idemKey: `trip:${full.trip_id}`
-            });
-            return {
-                appended: true,
-                tripId: full.trip_id,
-                total: gate.events.length
-            };
+            this.insertEvent({ actor, kind: 'trip.logged', subjectId: full.trip_id, payload: { trip: full }, idemKey: `trip:${full.trip_id}` });
+            return { appended: true, tripId: full.trip_id, total: gate.events.length };
         });
-        return run();
     }
+    /** 同行人档案(守门 = upsertCompanion:负面清单拒收/追加不删史/幂等) */
     appendCompanion(patch, actor = 'tool:gotry_companion_save') {
-        const run = this.db.transaction(()=>{
+        // 读改写(readCompanions → upsertCompanion → DELETE+INSERT 整组投影):
+        // 第一条语句是 SELECT → IMMEDIATE。replaceItems 整组重写,丢更新的代价最大。
+        return this.runWrite('appendCompanion', () => {
             const profiles = this.readCompanions();
             const res = upsertCompanion(profiles, patch);
-            if (!res.appended) return {
-                appended: false,
-                companionId: res.companionId,
-                reason: res.reason,
-                total: profiles.length
-            };
-            this.insertEvent({
-                actor,
-                kind: 'companion.saved',
-                subjectId: res.companionId,
-                payload: {
-                    patch
-                }
-            });
-            this.replaceItems('companions', res.profiles.map((p)=>[
-                    p.companion_id,
-                    p
-                ]));
-            return {
-                appended: true,
-                companionId: res.companionId,
-                total: res.profiles.length
-            };
+            if (!res.appended)
+                return { appended: false, companionId: res.companionId, reason: res.reason, total: profiles.length };
+            this.insertEvent({ actor, kind: 'companion.saved', subjectId: res.companionId, payload: { patch } });
+            this.replaceItems('companions', res.profiles.map(p => [p.companion_id, p]));
+            return { appended: true, companionId: res.companionId, total: res.profiles.length };
         });
-        return run();
     }
+    /**
+     * 成行确认(原跨两文件写 → 单事务):verified_outcome 效用事件 + 可选时间线行程,
+     * 同事务提交,崩溃后要么全有要么全无(RFC §1.1 partial-writes 缺口的修复)。
+     */
     confirmOutcome(input, actor = 'tool:gotry_wish_pool_list') {
-        const run = this.db.transaction(()=>{
+        // 读改写:行程分支里 readTrips → gateTrip → 写事件;且 full 为空时整个事务
+        // 以 SELECT 开头。两个写同一事务提交的原子性正是本方法的存在理由 → IMMEDIATE。
+        return this.runWrite('confirmOutcome', () => {
             const now = new Date().toISOString();
             const full = gateUtilityEvent([], {
-                wish_id: input.wishId,
-                kind: 'verified_outcome',
-                ts: now,
-                ctx: 'gotry_wish_pool_list.confirm',
-                detail: input.detail,
-                attribution: input.attribution
+                wish_id: input.wishId, kind: 'verified_outcome', ts: now,
+                ctx: 'gotry_wish_pool_list.confirm', detail: input.detail, attribution: input.attribution,
             }).events[0];
-            const recorded = full ? this.insertEvent({
-                actor,
-                kind: 'memory_utility.event',
-                subjectId: full.wish_id,
-                payload: {
-                    event: full
-                },
-                idemKey: `mu:${full.event_id}`
-            }) !== null : false;
+            const recorded = full
+                ? this.insertEvent({ actor, kind: 'memory_utility.event', subjectId: full.wish_id, payload: { event: full }, idemKey: `mu:${full.event_id}` }) !== null
+                : false;
             let trip;
             if (input.trip) {
                 const existing = this.readTrips();
                 const gate = gateTrip(existing, input.trip);
                 if (gate.appended) {
                     const fullTrip = gate.events[gate.events.length - 1];
-                    this.insertEvent({
-                        actor,
-                        kind: 'trip.logged',
-                        subjectId: fullTrip.trip_id,
-                        payload: {
-                            trip: fullTrip
-                        },
-                        idemKey: `trip:${fullTrip.trip_id}`
-                    });
+                    this.insertEvent({ actor, kind: 'trip.logged', subjectId: fullTrip.trip_id, payload: { trip: fullTrip }, idemKey: `trip:${fullTrip.trip_id}` });
                 }
-                trip = {
-                    appended: gate.appended,
-                    tripId: gate.tripId,
-                    reason: gate.reason
-                };
+                trip = { appended: gate.appended, tripId: gate.tripId, reason: gate.reason };
             }
-            return {
-                recorded,
-                trip
-            };
+            return { recorded, trip };
         });
-        return run();
     }
+    // ---- 投影维护 ---------------------------------------------------------------
     upsertItem(subject, itemId, doc) {
-        const ord = this.db.prepare(`SELECT ord FROM projection_items WHERE subject = ? AND item_id = ?`).get(subject, itemId)?.ord ?? this.nextOrd(subject);
-        this.db.prepare(`INSERT INTO projection_items (subject, item_id, doc, ord) VALUES (?, ?, ?, ?)
-       ON CONFLICT(subject, item_id) DO UPDATE SET doc = excluded.doc`).run(subject, itemId, JSON.stringify(doc), ord);
+        const ord = this.db.prepare(`SELECT ord FROM projection_items WHERE subject = ? AND item_id = ? AND tenant_id = ?`).get(subject, itemId, this.tenant)?.ord ?? this.nextOrd(subject);
+        this.db.prepare(`INSERT INTO projection_items (tenant_id, subject, item_id, doc, ord) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(tenant_id, subject, item_id) DO UPDATE SET doc = excluded.doc`).run(this.tenant, subject, itemId, JSON.stringify(doc), ord);
     }
     insertItem(subject, itemId, doc, ord) {
-        this.db.prepare(`INSERT INTO projection_items (subject, item_id, doc, ord) VALUES (?, ?, ?, ?)
-       ON CONFLICT(subject, item_id) DO UPDATE SET doc = excluded.doc`).run(subject, itemId, JSON.stringify(doc), ord);
+        this.db.prepare(`INSERT INTO projection_items (tenant_id, subject, item_id, doc, ord) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(tenant_id, subject, item_id) DO UPDATE SET doc = excluded.doc`).run(this.tenant, subject, itemId, JSON.stringify(doc), ord);
     }
     replaceItems(subject, items) {
-        this.db.prepare('DELETE FROM projection_items WHERE subject = ?').run(subject);
-        const ins = this.db.prepare('INSERT INTO projection_items (subject, item_id, doc, ord) VALUES (?, ?, ?, ?)');
-        items.forEach(([id, doc], i)=>ins.run(subject, id, JSON.stringify(doc), i));
+        this.db.prepare('DELETE FROM projection_items WHERE subject = ? AND tenant_id = ?').run(subject, this.tenant);
+        const ins = this.db.prepare('INSERT INTO projection_items (tenant_id, subject, item_id, doc, ord) VALUES (?, ?, ?, ?, ?)');
+        items.forEach(([id, doc], i) => ins.run(this.tenant, subject, id, JSON.stringify(doc), i));
     }
     nextOrd(subject) {
-        return (this.db.prepare('SELECT COALESCE(MAX(ord), -1) AS m FROM projection_items WHERE subject = ?').get(subject).m ?? -1) + 1;
+        return (this.db.prepare('SELECT COALESCE(MAX(ord), -1) AS m FROM projection_items WHERE subject = ? AND tenant_id = ?').get(subject, this.tenant).m ?? -1) + 1;
     }
+    /**
+     * fold 重建:DROP 全部投影 → 重放 events(可截到 toSeq)→ 重建投影。
+     * 与写路径共用同一套纯函数 → 直读投影与 fold 结果一致(账本/投影永不分叉的可验证性)。
+     */
     rebuildProjections(toSeq) {
-        const run = this.db.transaction(()=>{
-            this.db.prepare('DELETE FROM projection_docs').run();
-            this.db.prepare('DELETE FROM projection_items').run();
-            const rows = (toSeq === undefined ? this.db.prepare('SELECT seq, ts, kind, subject_id, payload FROM events ORDER BY seq') : this.db.prepare('SELECT seq, ts, kind, subject_id, payload FROM events WHERE seq <= ? ORDER BY seq')).all(...toSeq === undefined ? [] : [
-                toSeq
-            ]);
-            for (const row of rows)this.foldEvent(row);
-            const wishes = this.db.prepare(`SELECT COUNT(*) AS n FROM projection_items WHERE subject = 'wish_pool'`).get().n;
-            const companions = this.db.prepare(`SELECT COUNT(*) AS n FROM projection_items WHERE subject = 'companions'`).get().n;
-            return {
-                events: rows.length,
-                wishes,
-                companions
-            };
+        // DELETE 开头 → 写锁即刻到手,维持 DEFERRED(审计表见 runWrite 上方);
+        // 且本方法常被 forgetSubject/importLegacyInto 嵌套调用,嵌套层不该自己重试。
+        const run = this.db.transaction(() => {
+            this.db.prepare('DELETE FROM projection_docs WHERE tenant_id = ?').run(this.tenant);
+            this.db.prepare('DELETE FROM projection_items WHERE tenant_id = ?').run(this.tenant);
+            const rows = (toSeq === undefined
+                ? this.db.prepare('SELECT seq, ts, kind, subject_id, payload FROM events WHERE tenant_id = ? ORDER BY seq')
+                : this.db.prepare('SELECT seq, ts, kind, subject_id, payload FROM events WHERE seq <= ? AND tenant_id = ? ORDER BY seq')).all(...(toSeq === undefined ? [this.tenant] : [toSeq, this.tenant]));
+            for (const row of rows)
+                this.foldEvent(row);
+            const wishes = this.db.prepare(`SELECT COUNT(*) AS n FROM projection_items WHERE subject = 'wish_pool' AND tenant_id = ?`).get(this.tenant).n;
+            const companions = this.db.prepare(`SELECT COUNT(*) AS n FROM projection_items WHERE subject = 'companions' AND tenant_id = ?`).get(this.tenant).n;
+            return { events: rows.length, wishes, companions };
         });
         return run();
     }
     foldEvent(row) {
         const p = JSON.parse(row.payload);
-        switch(row.kind){
-            case 'motivation.imported':
-                {
-                    const doc = p['profile'];
-                    this.db.prepare(`INSERT INTO projection_docs (subject, doc) VALUES ('motivation', ?)
-           ON CONFLICT(subject) DO UPDATE SET doc = excluded.doc`).run(JSON.stringify(doc));
-                    break;
-                }
-            case 'motivation.patch':
-                {
-                    const current = this.readMotivation();
-                    const merged = mergeProfile(current, p['patch']);
-                    if (merged) {
-                        const doc = {
-                            ...merged,
-                            updated_at: row.ts
-                        };
-                        this.db.prepare(`INSERT INTO projection_docs (subject, doc) VALUES ('motivation', ?)
-             ON CONFLICT(subject) DO UPDATE SET doc = excluded.doc`).run(JSON.stringify(doc));
-                    }
-                    break;
+        switch (row.kind) {
+            case 'motivation.imported': {
+                const doc = p['profile'];
+                this.db.prepare(`INSERT INTO projection_docs (tenant_id, subject, doc) VALUES (?, 'motivation', ?)
+           ON CONFLICT(tenant_id, subject) DO UPDATE SET doc = excluded.doc`).run(this.tenant, JSON.stringify(doc));
+                break;
+            }
+            case 'motivation.patch': {
+                const current = this.readMotivation();
+                // 重建路径:时间戳 = 事件行 row.ts(账本事实);不在 fold 里再读时钟
+                const merged = mergeProfile(current, p['patch'], row.ts);
+                if (merged) {
+                    const doc = { ...merged, updated_at: row.ts };
+                    this.db.prepare(`INSERT INTO projection_docs (tenant_id, subject, doc) VALUES (?, 'motivation', ?)
+             ON CONFLICT(tenant_id, subject) DO UPDATE SET doc = excluded.doc`).run(this.tenant, JSON.stringify(doc));
                 }
+                break;
+            }
             case 'wish.imported':
-            case 'wish.added':
-                {
-                    const wish = p['wish'] ?? p['profile'];
-                    this.insertItem('wish_pool', String(wish.wish_id ?? row.subject_id), wish, row.seq);
-                    break;
-                }
-            case 'wish.updated':
-                {
-                    const id = String(p['wish_id']);
-                    const patch = p['patch'] ?? {};
-                    const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'wish_pool' AND item_id = ?`).get(id);
-                    if (rows) {
-                        const doc = {
-                            ...JSON.parse(rows.doc),
-                            ...patch
-                        };
-                        this.upsertItem('wish_pool', id, doc);
-                    }
-                    break;
-                }
-            case 'companion.imported':
-                {
-                    const profile = p['profile'];
-                    this.insertItem('companions', profile.companion_id, profile, row.seq);
-                    break;
-                }
-            case 'companion.saved':
-                {
-                    const patch = p['patch'];
-                    const res = upsertCompanion(this.readCompanions(), patch);
-                    this.replaceItems('companions', res.profiles.map((c)=>[
-                            c.companion_id,
-                            c
-                        ]));
-                    break;
+            case 'wish.added': {
+                const wish = (p['wish'] ?? p['profile']);
+                this.insertItem('wish_pool', String(wish.wish_id ?? row.subject_id), wish, row.seq);
+                break;
+            }
+            case 'wish.updated': {
+                const id = String(p['wish_id']);
+                const patch = (p['patch'] ?? {});
+                const rows = this.db.prepare(`SELECT doc FROM projection_items WHERE subject = 'wish_pool' AND item_id = ? AND tenant_id = ?`).get(id, this.tenant);
+                if (rows) {
+                    const doc = { ...JSON.parse(rows.doc), ...patch };
+                    this.upsertItem('wish_pool', id, doc);
                 }
-            default:
                 break;
+            }
+            case 'companion.imported': {
+                const profile = p['profile'];
+                this.insertItem('companions', profile.companion_id, profile, row.seq);
+                break;
+            }
+            case 'companion.saved': {
+                const patch = p['patch'];
+                const res = upsertCompanion(this.readCompanions(), patch);
+                this.replaceItems('companions', res.profiles.map(c => [c.companion_id, c]));
+                break;
+            }
+            default:
+                break; // 日志类事件(memory_utility/trip/async/write/forget)无投影
         }
     }
+    // ---- durable 工单(TS-3) -----------------------------------------------------
     createWorkflowRun(input, actor = 'system:async-request') {
         const ts = new Date().toISOString();
-        const run = this.db.transaction(()=>{
-            this.db.prepare(`INSERT INTO workflow_runs (id, goal, status, ticket_json, state_json, deliverable, created, updated)
-         VALUES (?, ?, 'pending', ?, ?, NULL, ?, ?)
-         ON CONFLICT(id) DO UPDATE SET updated = excluded.updated`).run(input.id, input.goal, JSON.stringify(input.ticket), JSON.stringify(input.state), ts, ts);
-            this.insertEvent({
-                actor,
-                kind: 'async.run_created',
-                subjectId: input.id,
-                payload: {
-                    ticket: input.ticket
-                },
-                runId: input.id,
-                ts
-            });
+        // INSERT 开头 → 维持 DEFERRED(审计表见 runWrite 上方)。
+        const run = this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO workflow_runs (tenant_id, id, goal, status, ticket_json, state_json, deliverable, created, updated)
+         VALUES (?, ?, ?, 'pending', ?, ?, NULL, ?, ?)
+         ON CONFLICT(tenant_id, id) DO UPDATE SET updated = excluded.updated`).run(this.tenant, input.id, input.goal, JSON.stringify(input.ticket), JSON.stringify(input.state), ts, ts);
+            this.insertEvent({ actor, kind: 'async.run_created', subjectId: input.id, payload: { ticket: input.ticket }, runId: input.id, ts });
         });
         run();
     }
     getWorkflowRun(id) {
-        return this.db.prepare('SELECT * FROM workflow_runs WHERE id = ?').get(id);
+        return this.db.prepare('SELECT * FROM workflow_runs WHERE id = ? AND tenant_id = ?').get(id, this.tenant);
     }
     pendingWorkflowRuns() {
-        return this.db.prepare(`SELECT id, goal FROM workflow_runs WHERE status = 'pending' ORDER BY created`).all();
+        return this.db.prepare(`SELECT id, goal FROM workflow_runs WHERE status = 'pending' AND tenant_id = ? ORDER BY created`).all(this.tenant);
     }
     getWorkflowStep(runId, name) {
-        return this.db.prepare('SELECT status, result FROM workflow_steps WHERE run_id = ? AND name = ?').get(runId, name);
+        return this.db.prepare('SELECT status, result FROM workflow_steps WHERE run_id = ? AND name = ? AND tenant_id = ?').get(runId, name, this.tenant);
     }
     markStepIntent(runId, name) {
-        this.db.prepare(`INSERT INTO workflow_steps (run_id, name, status, intent_ts) VALUES (?, ?, 'intent', ?)
-       ON CONFLICT(run_id, name) DO NOTHING`).run(runId, name, new Date().toISOString());
+        this.db.prepare(`INSERT INTO workflow_steps (tenant_id, run_id, name, status, intent_ts) VALUES (?, ?, ?, 'intent', ?)
+       ON CONFLICT(tenant_id, run_id, name) DO NOTHING`).run(this.tenant, runId, name, new Date().toISOString());
     }
     markStepDone(runId, name, result) {
-        this.db.prepare(`UPDATE workflow_steps SET status = 'done', result = ?, done_ts = ? WHERE run_id = ? AND name = ?`).run(JSON.stringify(result), new Date().toISOString(), runId, name);
-    }
-    settleWorkflowRun(id, deliverable, actor = 'system:async-collect') {
-        const run = this.db.transaction(()=>{
-            this.db.prepare(`UPDATE workflow_runs SET status = 'settled', deliverable = ?, updated = ? WHERE id = ?`).run(deliverable, new Date().toISOString(), id);
+        this.db.prepare(`UPDATE workflow_steps SET status = 'done', result = ?, done_ts = ? WHERE run_id = ? AND name = ? AND tenant_id = ?`).run(JSON.stringify(result), new Date().toISOString(), runId, name, this.tenant);
+    }
+    finishWorkflowRun(id, status, eventKind, deliverable, terminalOutcome, actor = 'system:async-collect') {
+        // UPDATE ... WHERE status = 'pending' 开头(CAS 式状态推进)→ 维持 DEFERRED。
+        const run = this.db.transaction(() => {
+            const update = this.db.prepare(`UPDATE workflow_runs SET status = ?, deliverable = ?, updated = ?
+         WHERE id = ? AND tenant_id = ? AND status = 'pending'`).run(status, deliverable, new Date().toISOString(), id, this.tenant);
+            if (update.changes === 0) {
+                const existing = this.getWorkflowRun(id);
+                if (existing?.status === status)
+                    return;
+                throw new Error(`workflow ${id} cannot transition ${existing?.status ?? 'missing'} -> ${status}`);
+            }
             this.insertEvent({
                 actor,
-                kind: 'async.settled',
+                kind: eventKind,
                 subjectId: id,
-                payload: {
-                    bytes: deliverable.length
-                },
-                runId: id
+                payload: { bytes: deliverable.length, terminal_outcome: terminalOutcome },
+                idemKey: `async-terminal:${id}`,
+                runId: id,
             });
         });
         run();
     }
+    settleWorkflowRun(id, deliverable, terminalOutcome, actor = 'system:async-collect') {
+        this.finishWorkflowRun(id, 'settled', 'async.settled', deliverable, terminalOutcome, actor);
+    }
+    failWorkflowRun(id, deliverable, terminalOutcome, actor = 'system:async-collect') {
+        this.finishWorkflowRun(id, 'failed', 'async.failed', deliverable, terminalOutcome, actor);
+    }
+    getWorkflowTerminalOutcome(id) {
+        const row = this.db.prepare(`SELECT payload FROM events
+       WHERE tenant_id = ? AND run_id = ? AND kind IN ('async.settled', 'async.failed')
+       ORDER BY seq DESC LIMIT 1`).get(this.tenant, id);
+        if (!row)
+            return null;
+        try {
+            const payload = JSON.parse(row.payload);
+            return payload.terminal_outcome ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ---- WriteGate saga 基座(TS-4, RFC S4 L2/L3 物理预备) -----------------------
+    /** 登记一笔待确认外部写(幂等键去重:同一确认不可能登记两次)。L2 = 只登记不执行。 */
     requestPendingWrite(input, actor = 'system:writegate') {
         const ts = new Date().toISOString();
-        const run = this.db.transaction(()=>{
-            const info = this.db.prepare(`INSERT INTO pending_writes (idem_key, seam, payload, status, created, updated)
-         VALUES (?, ?, ?, 'pending', ?, ?) ON CONFLICT(idem_key) DO NOTHING`).run(input.idemKey, input.seam, JSON.stringify(input.payload ?? {}), ts, ts);
+        // INSERT ... ON CONFLICT DO NOTHING 开头 → 维持 DEFERRED。
+        const run = this.db.transaction(() => {
+            const info = this.db.prepare(`INSERT INTO pending_writes (tenant_id, idem_key, seam, payload, status, created, updated)
+         VALUES (?, ?, ?, ?, 'pending', ?, ?) ON CONFLICT(tenant_id, idem_key) DO NOTHING`).run(this.tenant, input.idemKey, input.seam, JSON.stringify(input.payload ?? {}), ts, ts);
             if (info.changes === 0) {
-                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ?').get(input.idemKey);
-                return {
-                    created: false,
-                    status: row.status
-                };
+                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ? AND tenant_id = ?').get(input.idemKey, this.tenant);
+                return { created: false, status: row.status };
             }
-            this.insertEvent({
-                actor,
-                kind: 'write.pending',
-                subjectId: input.idemKey,
-                payload: {
-                    seam: input.seam,
-                    payload: input.payload
-                },
-                idemKey: `pw:${sha(input.idemKey)}:pending`
-            });
-            return {
-                created: true,
-                status: 'pending'
-            };
+            this.insertEvent({ actor, kind: 'write.pending', subjectId: input.idemKey, payload: { seam: input.seam, payload: input.payload }, idemKey: `pw:${sha(input.idemKey)}:pending` });
+            return { created: true, status: 'pending' };
         });
         return run();
     }
+    /** L3:具名 seam 确认——pending → confirmed,携 receipt(外部世界回执) */
     confirmPendingWrite(idemKey, receipt, actor = 'system:writegate') {
-        const run = this.db.transaction(()=>{
-            const info = this.db.prepare(`UPDATE pending_writes SET status = 'confirmed', receipt = ?, updated = ? WHERE idem_key = ? AND status = 'pending'`).run(receipt, new Date().toISOString(), idemKey);
+        // UPDATE ... WHERE status = 'pending' 开头(CAS)→ 维持 DEFERRED。
+        const run = this.db.transaction(() => {
+            const info = this.db.prepare(`UPDATE pending_writes SET status = 'confirmed', receipt = ?, updated = ? WHERE idem_key = ? AND status = 'pending' AND tenant_id = ?`).run(receipt, new Date().toISOString(), idemKey, this.tenant);
             if (info.changes === 0) {
-                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ?').get(idemKey);
-                return {
-                    ok: false,
-                    status: row?.status ?? 'missing'
-                };
+                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ? AND tenant_id = ?').get(idemKey, this.tenant);
+                return { ok: false, status: row?.status ?? 'missing' };
             }
-            this.insertEvent({
-                actor,
-                kind: 'write.confirmed',
-                subjectId: idemKey,
-                payload: {
-                    receipt
-                }
-            });
-            return {
-                ok: true,
-                status: 'confirmed'
-            };
+            this.insertEvent({ actor, kind: 'write.confirmed', subjectId: idemKey, payload: { receipt } });
+            return { ok: true, status: 'confirmed' };
         });
         return run();
     }
+    /** saga 补偿:pending/confirmed → compensated(SagaLLM 式补偿语义) */
     compensatePendingWrite(idemKey, note, actor = 'system:writegate') {
-        const run = this.db.transaction(()=>{
-            const info = this.db.prepare(`UPDATE pending_writes SET status = 'compensated', receipt = COALESCE(receipt, ?), updated = ? WHERE idem_key = ? AND status != 'compensated'`).run(note, new Date().toISOString(), idemKey);
+        // UPDATE ... WHERE status != 'compensated' 开头(CAS)→ 维持 DEFERRED。
+        const run = this.db.transaction(() => {
+            const info = this.db.prepare(`UPDATE pending_writes SET status = 'compensated', receipt = COALESCE(receipt, ?), updated = ? WHERE idem_key = ? AND status != 'compensated' AND tenant_id = ?`).run(note, new Date().toISOString(), idemKey, this.tenant);
             if (info.changes === 0) {
-                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ?').get(idemKey);
-                return {
-                    ok: false,
-                    status: row?.status ?? 'missing'
-                };
+                const row = this.db.prepare('SELECT status FROM pending_writes WHERE idem_key = ? AND tenant_id = ?').get(idemKey, this.tenant);
+                return { ok: false, status: row?.status ?? 'missing' };
             }
-            this.insertEvent({
-                actor,
-                kind: 'write.compensated',
-                subjectId: idemKey,
-                payload: {
-                    note
-                }
-            });
-            return {
-                ok: true,
-                status: 'compensated'
-            };
+            this.insertEvent({ actor, kind: 'write.compensated', subjectId: idemKey, payload: { note } });
+            return { ok: true, status: 'compensated' };
         });
         return run();
     }
     listPendingWrites() {
-        return this.db.prepare('SELECT idem_key, seam, status, receipt, created FROM pending_writes ORDER BY created').all();
+        return this.db.prepare('SELECT idem_key, seam, status, receipt, created FROM pending_writes WHERE tenant_id = ? ORDER BY created').all(this.tenant);
     }
+    /** what-if 分叉:VACUUM INTO 副本,预演不触正本(LoopX「先只读投影后执行」的物理化) */
     forkWhatIf(destPath) {
         this.db.prepare('VACUUM INTO ?').run(destPath);
         return destPath;
     }
+    // ---- forget(D5:物理硬删,审计只留一行) ---------------------------------------
+    /** 物理删除某主体的全部事件并重建投影;删除本身留一行审计事件(红线 6「可删除」)。 */
     forgetSubject(subjects, actor = 'system:state-cli') {
-        const run = this.db.transaction(()=>{
+        // DELETE events 开头 → 维持 DEFERRED(审计表见 runWrite 上方)。
+        const run = this.db.transaction(() => {
             let deleted = 0;
-            for (const s of subjects){
-                const placeholders = s.kinds.map(()=>'?').join(',');
-                const info = this.db.prepare(`DELETE FROM events WHERE subject_id = ? AND kind IN (${placeholders})`).run(s.subjectId, ...s.kinds);
+            for (const s of subjects) {
+                const placeholders = s.kinds.map(() => '?').join(',');
+                const info = this.db.prepare('DELETE FROM events WHERE subject_id = ? AND tenant_id = ? AND kind IN (' + placeholders + ')').run(s.subjectId, this.tenant, ...s.kinds);
                 deleted += info.changes;
             }
-            this.insertEvent({
-                actor,
-                kind: 'forget.executed',
-                payload: {
-                    subjects
-                }
-            });
+            this.insertEvent({ actor, kind: 'forget.executed', payload: { subjects } });
             this.rebuildProjections();
-            return {
-                deleted
-            };
+            return { deleted };
         });
         return run();
     }
     close() {
         this.db.close();
+        for (const [key, value] of openLedgers)
+            if (value === this)
+                openLedgers.delete(key);
     }
 }
+// ---- 打开/迁移(one-shot D2;模块级缓存避免每次读开新句柄) ----------------------
 const openLedgers = new Map();
-function openDb(stateRoot) {
-    const path = ledgerDbPath(stateRoot);
-    const cached = openLedgers.get(path);
-    if (cached) return cached;
-    mkdirSync(join(path, '..'), {
-        recursive: true
+/**
+ * WAL 切换(D15-1 的第一个抛点)。
+ *
+ * 切成 WAL 要拿排他锁,而 `PRAGMA journal_mode` 并非在所有路径上都会走 busy
+ * handler,所以除了「busy_timeout 先装好」之外还要有界重试。每次失败先回看当前
+ * 模式:别的进程已经切成 wal 就直接收工——冷启动竞赛里这是最常见的结局。
+ *
+ * 不抛而仍未切成 wal(例如不支持 WAL 的文件系统)时保持修复前行为:照旧继续,
+ * 不编造「忙」。只有真的抛争用码且重试耗尽才给 LedgerBusyError。
+ */
+function ensureWalMode(db) {
+    const currentMode = () => String(db.pragma('journal_mode', { simple: true }) ?? '').toLowerCase();
+    if (currentMode() === 'wal')
+        return;
+    withContentionRetry('openDb journal_mode = WAL', () => {
+        if (currentMode() === 'wal')
+            return; // 竞赛里最常见的结局:别的进程已经切好了
+        db.pragma('journal_mode = WAL');
+    }, { retries: OPEN_CONTENTION_RETRIES, budgetMs: OPEN_CONTENTION_BUDGET_MS });
+}
+/**
+ * 建表/迁移(D15-1 的第二个抛点):整段进 BEGIN IMMEDIATE + 有界重试。
+ *
+ * 修复前版本探测在事务**外**,两个冷启动进程会各自读到 user_version = 0,再同时
+ * 进 DEFERRED 事务执行 `db.exec(SCHEMA)` —— 第一条 DDL 要升级成写,输的那个直接
+ * 抛裸 SQLITE_BUSY。现在版本探测与建表同处一个写锁下,后来者在 busy handler 里
+ * 排队,进去后重新读到 user_version = 2,于是只跑一遍幂等建表。
+ *
+ * 返回 isV1:v1→v2 升级后要重建投影,而那需要 StateLedger 实例,只能在事务外做。
+ */
+function ensureSchema(db) {
+    // 快路径:schema 已是 v2、kv 旗标在位、历史坏迁移已修 → 纯读探测,完全不取写锁。
+    // (修复前每次 open 都要写一次 kv schema_version,连只读调用方也在抢写锁,
+    //  冷启动竞赛因此更密;值本来就幂等,不写与写同义。)
+    if (schemaAlreadyCurrent(db))
+        return false;
+    const kvSchemaVersion = 'INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v';
+    const migrate = db.transaction(() => {
+        // 版本探测搬进事务:与建表同处一个写锁下,不再有两个进程各读到 0 的 TOCTOU。
+        const version = db.pragma('user_version', { simple: true });
+        let isV1 = false;
+        if (version < 2) {
+            // schema v1→v2 迁移:v1 无 tenant_id 列(user_version 未设置过,实际为 0)
+            // 检测是否真有 v1 数据(有 events 表但无 tenant_id 列)
+            const hasEventsTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='events'").get() !== undefined;
+            const eventsHasTenant = hasEventsTable && db.prepare('PRAGMA table_info(events)').all().some(c => c.name === 'tenant_id');
+            isV1 = hasEventsTable && !eventsHasTenant;
+            if (isV1) {
+                // v1 → v2:events 加 tenant_id,回填 'local';投影/工单/pending_writes 强制重建(旧表无 tenant_id)
+                db.exec(`
+          ALTER TABLE events ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'local';
+          DROP INDEX IF EXISTS events_idem;
+          CREATE UNIQUE INDEX events_idem ON events(tenant_id, idem_key) WHERE idem_key IS NOT NULL;
+          DROP TABLE IF EXISTS projection_docs;
+          DROP TABLE IF EXISTS projection_items;
+          DROP TABLE IF EXISTS workflow_runs;
+          DROP TABLE IF EXISTS workflow_steps;
+          DROP TABLE IF EXISTS pending_writes;
+        `);
+            }
+            else {
+                // v2 幂等:检查 workflow_runs 是否缺 tenant_id(修一次跑坏的迁移)
+                const wrHasTenant = db.prepare('PRAGMA table_info(workflow_runs)').all().some(c => c.name === 'tenant_id');
+                if (!wrHasTenant && db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='workflow_runs'").get()) {
+                    db.exec(`
+            DROP TABLE IF EXISTS workflow_runs;
+            DROP TABLE IF EXISTS workflow_steps;
+            DROP TABLE IF EXISTS pending_writes;
+            DROP TABLE IF EXISTS projection_docs;
+            DROP TABLE IF EXISTS projection_items;
+          `);
+                }
+            }
+            db.exec(SCHEMA);
+            db.pragma('user_version = 2');
+            db.prepare(kvSchemaVersion).run('schema_version', SCHEMA_VERSION);
+        }
+        else {
+            // 已是 v2:只做幂等建表(IF NOT EXISTS)。坏迁移修补只属于 version < 2 分支,
+            // 与修复前一致——user_version 已经是 2 时绝不去 DROP 任何可能有数据的表。
+            db.exec(SCHEMA);
+            db.prepare(kvSchemaVersion).run('schema_version', SCHEMA_VERSION);
+        }
+        return isV1;
     });
-    mkdirSync(dirname(path), {
-        recursive: true
+    return withContentionRetry('openDb schema ensure/migrate', () => migrate.immediate(), {
+        retries: OPEN_CONTENTION_RETRIES,
+        budgetMs: OPEN_CONTENTION_BUDGET_MS,
     });
+}
+/** 当前 SCHEMA 应当存在的全部对象;快路径据此判定「慢路径必然是空操作」。 */
+const SCHEMA_OBJECTS = ['events', 'events_idem', 'projection_docs', 'projection_items', 'workflow_runs', 'workflow_steps', 'pending_writes', 'kv'];
+/**
+ * 纯读探测:user_version 已是 2、SCHEMA 全部对象在位、kv 旗标已等于目标值
+ * → 慢路径(exec SCHEMA + kv upsert)可证明是空操作,于是整段写锁都省掉。
+ * 任何一项不满足(新库,或别的进程正在建而本连接还看不到)→ false,走慢路径。
+ */
+function schemaAlreadyCurrent(db) {
+    try {
+        if (db.pragma('user_version', { simple: true }) < 2)
+            return false;
+        const present = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type IN ('table', 'index')").all().map(r => r.name));
+        if (!SCHEMA_OBJECTS.every(name => present.has(name)))
+            return false;
+        const row = db.prepare(`SELECT v FROM kv WHERE k = 'schema_version'`).get();
+        return row?.v === SCHEMA_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+export function openDb(stateRoot, tenant = 'local') {
+    const path = ledgerDbPath(stateRoot);
+    const cacheKey = `${path}::${tenant}`;
+    const cached = openLedgers.get(cacheKey);
+    if (cached)
+        return cached;
+    mkdirSync(dirname(path), { recursive: true });
     const db = new Database(path);
-    db.pragma('journal_mode = WAL');
-    db.pragma('synchronous = NORMAL');
-    db.pragma('busy_timeout = 5000');
-    db.exec(SCHEMA);
-    db.prepare('INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v').run('schema_version', SCHEMA_VERSION);
-    const ledger = new StateLedger(db, stateRoot);
-    openLedgers.set(path, ledger);
+    let isV1 = false;
+    try {
+        // D15-1 顺序红线:busy_timeout 必须在任何可争用语句之前装好。修复前它排在
+        // `journal_mode = WAL` 之后,于是 WAL 切换的排他锁被持有时,其余连接还没有
+        // busy handler —— 冷启动并发打开直接抛裸 SQLITE_BUSY。顺序不可再调换。
+        db.pragma(`busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        ensureWalMode(db);
+        db.pragma('synchronous = NORMAL');
+        isV1 = ensureSchema(db);
+    }
+    catch (e) {
+        // 打开失败不留半开句柄(重试/上抛都不该泄漏 better-sqlite3 的文件描述符)。
+        try {
+            db.close();
+        }
+        catch { /* 句柄已废,关不掉不影响裁决 */ }
+        throw e;
+    }
+    // v1 升级后:旧单用户事件只可安全归入 local;即使调用者打开非 local 租户,也只重建 local 投影。
+    if (isV1) {
+        const ledger = new StateLedger(db, stateRoot, 'local');
+        ledger.rebuildProjections();
+    }
+    const ledger = new StateLedger(db, stateRoot, tenant);
+    openLedgers.set(cacheKey, ledger);
     return ledger;
 }
-export function openLedgerIfExists(stateRoot) {
-    if (!ledgerExists(stateRoot)) return null;
-    return openDb(stateRoot);
+/** 只读场景:账本不存在返回 null(调用方走文件回退) */
+export function openLedgerIfExists(stateRoot, tenant = 'local') {
+    if (!ledgerExists(stateRoot))
+        return null;
+    return openDb(stateRoot, tenant);
 }
-export function ensureLedger(stateRoot) {
-    if (ledgerExists(stateRoot)) return openDb(stateRoot);
+/**
+ * 确保账本可用(写路径必经):
+ *  - DB 已存在 → 直接用
+ *  - 无 DB 无旧文件 → 建空账本(fresh root,smoke/测试形态)
+ *  - 无 DB 有旧文件 → 快照 → 建账本 → 旧数据单事务导入为 events(one-shot;
+ *    导入幂等键 + kv 旗标双保险,并发 ensure 不重复导入)
+ */
+export function ensureLedger(stateRoot, tenant = 'local') {
+    if (ledgerExists(stateRoot))
+        return openDb(stateRoot, tenant);
     const dir = stateDirOf(stateRoot);
     const hasLegacy = legacyFilesPresent(stateRoot);
     let backupDir = null;
     if (hasLegacy) {
         backupDir = join(dir, 'pre-ledger-backup');
-        mkdirSync(backupDir, {
-            recursive: true
-        });
-        for (const f of LEGACY_FILES){
-            if (existsSync(join(dir, f))) copyFileSync(join(dir, f), join(backupDir, f));
+        mkdirSync(backupDir, { recursive: true });
+        for (const f of LEGACY_FILES) {
+            if (existsSync(join(dir, f)))
+                copyFileSync(join(dir, f), join(backupDir, f));
         }
     }
-    const ledger = openDb(stateRoot);
-    if (hasLegacy) importLegacyInto(ledger, dir);
-    return ledger;
+    if (hasLegacy) {
+        // 旧 JSON/JSONL 是单用户本地状态,没有可审计租户归属;迁移边界=只归入 local,绝不按调用 tenant 猜测或搬移。
+        const localLedger = openDb(stateRoot, 'local');
+        importLegacyInto(localLedger, dir);
+        return tenant === 'local' ? localLedger : openDb(stateRoot, tenant);
+    }
+    return openDb(stateRoot, tenant);
 }
 function importLegacyInto(ledger, dir) {
-    const imported = {
-        motivation: false,
-        wishes: 0,
-        utilityEvents: 0,
-        trips: 0,
-        companions: 0
-    };
-    const run = ledger.db.transaction(()=>{
+    const imported = { motivation: false, wishes: 0, utilityEvents: 0, trips: 0, companions: 0 };
+    // 读改写:以 SELECT kv.legacy_imported_v1 开头(旗标判定)→ IMMEDIATE + 有界重试。
+    // 「并发 ensure 不重复导入」靠的就是这个旗标,而 DEFERRED 事务下两个进程会同时
+    // 读到无旗标、再在写时一个拿锁一个抛 SQLITE_BUSY_SNAPSHOT —— 正是 D15-2 的形状。
+    const run = ledger.db.transaction(() => {
+        // 重试要幂等:计数器属于「本次事务的成果」,每次尝试重新归零,回滚过的那次
+        // 不得残留在报告里。
+        Object.assign(imported, { motivation: false, wishes: 0, utilityEvents: 0, trips: 0, companions: 0 });
         const flag = ledger.db.prepare(`SELECT v FROM kv WHERE k = 'legacy_imported_v1'`).get();
-        if (flag) return;
-        const readJsonSafe = (p)=>{
+        if (flag)
+            return;
+        const readJsonSafe = (p) => {
             try {
                 return JSON.parse(readFileSync(p, 'utf-8'));
-            } catch  {
+            }
+            catch {
                 return null;
             }
         };
+        // 动机画像:整档快照事件(fold 直接落投影)
         const profile = readJsonSafe(join(dir, 'motivation-profile.json'));
         if (profile) {
-            if (ledger.insertEvent({
-                actor: 'system:migrate',
-                kind: 'motivation.imported',
-                subjectId: 'motivation',
-                payload: {
-                    profile
-                },
-                idemKey: 'import:motivation'
-            }) !== null) imported.motivation = true;
+            if (ledger.insertEvent({ actor: 'system:migrate', kind: 'motivation.imported', subjectId: 'motivation', payload: { profile }, idemKey: 'import:motivation' }) !== null)
+                imported.motivation = true;
         }
+        // 愿望池:逐条导入(保留原 wish_id)
         const pool = readJsonSafe(join(dir, 'wish-pool.json'));
         if (Array.isArray(pool)) {
-            for (const w of pool){
+            for (const w of pool) {
                 const id = String(w['wish_id'] ?? makeWishId(String(w['name'] ?? '')));
-                const wish = {
-                    ...w,
-                    wish_id: id
-                };
-                if (ledger.insertEvent({
-                    actor: 'system:migrate',
-                    kind: 'wish.imported',
-                    subjectId: id,
-                    payload: {
-                        wish
-                    },
-                    idemKey: `import:wish:${id}`
-                }) !== null) imported.wishes++;
+                const wish = { ...w, wish_id: id };
+                if (ledger.insertEvent({ actor: 'system:migrate', kind: 'wish.imported', subjectId: id, payload: { wish }, idemKey: `import:wish:${id}` }) !== null)
+                    imported.wishes++;
             }
         }
+        // 效用流:逐行导入(语义 event_id 即幂等键)
         try {
             const lines = readFileSync(join(dir, 'memory-utility.jsonl'), 'utf-8').split('\n').filter(Boolean);
-            for (const line of lines){
+            for (const line of lines) {
                 try {
                     const ev = JSON.parse(line);
-                    if (ledger.insertEvent({
-                        actor: 'system:migrate',
-                        kind: 'memory_utility.event',
-                        subjectId: ev.wish_id,
-                        payload: {
-                            event: ev
-                        },
-                        idemKey: `mu:${ev.event_id}`
-                    }) !== null) imported.utilityEvents++;
-                } catch  {}
+                    if (ledger.insertEvent({ actor: 'system:migrate', kind: 'memory_utility.event', subjectId: ev.wish_id, payload: { event: ev }, idemKey: `mu:${ev.event_id}` }) !== null)
+                        imported.utilityEvents++;
+                }
+                catch { /* 脏行跳过:导入永不因单行失败而中断 */ }
             }
-        } catch  {}
+        }
+        catch { /* 文件不存在 */ }
+        // 时间线:逐行导入(trip_id 幂等)
         try {
             const lines = readFileSync(join(dir, 'trips.jsonl'), 'utf-8').split('\n').filter(Boolean);
-            for (const line of lines){
+            for (const line of lines) {
                 try {
                     const trip = JSON.parse(line);
-                    if (ledger.insertEvent({
-                        actor: 'system:migrate',
-                        kind: 'trip.logged',
-                        subjectId: trip.trip_id,
-                        payload: {
-                            trip
-                        },
-                        idemKey: `trip:${trip.trip_id}`
-                    }) !== null) imported.trips++;
-                } catch  {}
+                    if (ledger.insertEvent({ actor: 'system:migrate', kind: 'trip.logged', subjectId: trip.trip_id, payload: { trip }, idemKey: `trip:${trip.trip_id}` }) !== null)
+                        imported.trips++;
+                }
+                catch { /* 脏行跳过 */ }
             }
-        } catch  {}
+        }
+        catch { /* 文件不存在 */ }
+        // 同行人:逐条导入(保留 companion_id)
         const companions = readJsonSafe(join(dir, 'companions.json'));
         if (Array.isArray(companions)) {
-            for (const c of companions){
+            for (const c of companions) {
                 const id = String(c['companion_id'] ?? '');
-                if (!id) continue;
-                if (ledger.insertEvent({
-                    actor: 'system:migrate',
-                    kind: 'companion.imported',
-                    subjectId: id,
-                    payload: {
-                        profile: c
-                    },
-                    idemKey: `import:companion:${id}`
-                }) !== null) imported.companions++;
+                if (!id)
+                    continue;
+                if (ledger.insertEvent({ actor: 'system:migrate', kind: 'companion.imported', subjectId: id, payload: { profile: c }, idemKey: `import:companion:${id}` }) !== null)
+                    imported.companions++;
             }
         }
         ledger.rebuildProjections();
         ledger.db.prepare(`INSERT INTO kv (k, v) VALUES ('legacy_imported_v1', 'done') ON CONFLICT(k) DO UPDATE SET v = excluded.v`).run();
     });
-    run();
+    withContentionRetry('ensureLedger legacy import', () => run.immediate());
     return imported;
 }
+// ---- 读路径统一出口:账本优先,未迁移 root 回退旧文件(只读,绝不反向写) ---------
 function readLegacyJson(stateRoot, name, fallback) {
     try {
         return JSON.parse(readFileSync(join(stateDirOf(stateRoot), name), 'utf-8'));
-    } catch  {
+    }
+    catch {
         return fallback;
     }
 }
 function readLegacyJsonl(stateRoot, name) {
     try {
-        return readFileSync(join(stateDirOf(stateRoot), name), 'utf-8').split('\n').filter(Boolean).map((l)=>JSON.parse(l));
-    } catch  {
+        return readFileSync(join(stateDirOf(stateRoot), name), 'utf-8').split('\n').filter(Boolean).map(l => JSON.parse(l));
+    }
+    catch {
         return [];
     }
 }
-export function readMotivationWithFallback(stateRoot) {
-    const ledger = openLedgerIfExists(stateRoot);
-    if (ledger) return ledger.readMotivation();
+export function readMotivationWithFallback(stateRoot, tenant = 'local') {
+    const ledger = openLedgerIfExists(stateRoot, tenant);
+    if (ledger)
+        return ledger.readMotivation();
+    if (tenant !== 'local')
+        return null;
     return readLegacyJson(stateRoot, 'motivation-profile.json', null);
 }
-export function readWishPoolWithFallback(stateRoot) {
-    const ledger = openLedgerIfExists(stateRoot);
-    if (ledger) return ledger.readWishPool();
+export function readWishPoolWithFallback(stateRoot, tenant = 'local') {
+    const ledger = openLedgerIfExists(stateRoot, tenant);
+    if (ledger)
+        return ledger.readWishPool();
+    if (tenant !== 'local')
+        return [];
     return readLegacyJson(stateRoot, 'wish-pool.json', []);
 }
-export function readUtilityEventsWithFallback(stateRoot) {
-    const ledger = openLedgerIfExists(stateRoot);
-    if (ledger) return ledger.readUtilityEvents();
+export function readUtilityEventsWithFallback(stateRoot, tenant = 'local') {
+    const ledger = openLedgerIfExists(stateRoot, tenant);
+    if (ledger)
+        return ledger.readUtilityEvents();
+    if (tenant !== 'local')
+        return [];
     return readLegacyJsonl(stateRoot, 'memory-utility.jsonl');
 }
-export function readTripsWithFallback(stateRoot) {
-    const ledger = openLedgerIfExists(stateRoot);
-    if (ledger) return ledger.readTrips();
+export function readTripsWithFallback(stateRoot, tenant = 'local') {
+    const ledger = openLedgerIfExists(stateRoot, tenant);
+    if (ledger)
+        return ledger.readTrips();
+    if (tenant !== 'local')
+        return [];
     return readLegacyJsonl(stateRoot, 'trips.jsonl');
 }
-export function readCompanionsWithFallback(stateRoot) {
-    const ledger = openLedgerIfExists(stateRoot);
-    if (ledger) return ledger.readCompanions();
+export function readCompanionsWithFallback(stateRoot, tenant = 'local') {
+    const ledger = openLedgerIfExists(stateRoot, tenant);
+    if (ledger)
+        return ledger.readCompanions();
+    if (tenant !== 'local')
+        return [];
     return readLegacyJson(stateRoot, 'companions.json', []);
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/src/state-ledger.ts