@danceiny/gotry 0.2.0-rc.27 → 0.2.0-rc.28

package/dist/src/session-zones.js

@@ -65,17 +65,20 @@ export function isZoneEventKind(v) {
 }
 /**
  * 幂等键(设计 §2 钉死的 rev 写键:P4-2 落账本直接复用):
- * rev 写 `hotctx:<note_id>:<rev>` / `notebook:<entry_id>:<rev>`——同 rev 重放物理 no-op;
- * drop 键带 ts:同一事件重放仍去重,且不跨生命周期碰撞(drop→再捕获循环不误伤)。
+ * rev 写 `hotctx:<note_id>:<生代>:<rev>` / `notebook:<entry_id>:<生代>:<rev>`——
+ * 同 rev 重放物理 no-op;drop 键带 ts:同一事件重放仍去重。
+ * 生代 = 文档的 created_at(诞生时刻,修订沿用):note_id/entry_id 是语义派生的,
+ * drop 后重捕获会复用同一 id 与 rev 1,若键里没有生代,UNIQUE 索引会把「更正后
+ * 仍真」的重捕获物理吞掉——纯核允许的生命周期在账本上就断了(P4-2 物理化暴露)。
  */
 export function zoneIdemKey(ev) {
     switch (ev.kind) {
         case 'hotctx.note.captured':
         case 'hotctx.note.revised':
-            return `hotctx:${ev.note.note_id}:${ev.note.rev}`;
+            return `hotctx:${ev.note.note_id}:${ev.note.created_at}:${ev.note.rev}`;
         case 'notebook.entry.promoted':
         case 'notebook.entry.revised':
-            return `notebook:${ev.entry.entry_id}:${ev.entry.rev}`;
+            return `notebook:${ev.entry.entry_id}:${ev.entry.created_at}:${ev.entry.rev}`;
         case 'hotctx.note.dropped':
             return `hotctx:${ev.note_id}:drop:${ev.ts}`;
         case 'notebook.entry.dropped':

package/dist/src/state-ledger.js

@@ -17,6 +17,16 @@
  * 引擎: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';
@@ -53,6 +63,103 @@ function legacyFilesPresent(stateRoot) {
 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,
@@ -183,12 +290,56 @@ export class StateLedger {
     }
     // ---- 写:单事务{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, ts);
             if (!merged) {
@@ -201,7 +352,6 @@ export class StateLedger {
          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') {
@@ -211,7 +361,9 @@ 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);
             if (existing) {
@@ -240,13 +392,14 @@ export class StateLedger {
             this.insertItem('wish_pool', id, doc, seq ?? 0);
             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() };
+        // 非读改写:事务内只有一条 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;
         });
@@ -254,7 +407,9 @@ export class StateLedger {
     }
     /** 时间线行程(守门 = 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)
@@ -263,11 +418,12 @@ export class StateLedger {
             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)
@@ -276,14 +432,15 @@ export class StateLedger {
             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,
@@ -304,7 +461,6 @@ export class StateLedger {
             }
             return { recorded, trip };
         });
-        return run();
     }
     // ---- 投影维护 ---------------------------------------------------------------
     upsertItem(subject, itemId, doc) {
@@ -329,6 +485,8 @@ export class StateLedger {
      * 与写路径共用同一套纯函数 → 直读投影与 fold 结果一致(账本/投影永不分叉的可验证性)。
      */
     rebuildProjections(toSeq) {
+        // 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);
@@ -397,6 +555,7 @@ export class StateLedger {
     // ---- durable 工单(TS-3) -----------------------------------------------------
     createWorkflowRun(input, actor = 'system:async-request') {
         const ts = new Date().toISOString();
+        // 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, ?, ?)
@@ -422,6 +581,7 @@ export class StateLedger {
         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);
@@ -466,6 +626,7 @@ export class StateLedger {
     /** 登记一笔待确认外部写(幂等键去重:同一确认不可能登记两次)。L2 = 只登记不执行。 */
     requestPendingWrite(input, actor = 'system:writegate') {
         const ts = new Date().toISOString();
+        // 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);
@@ -480,6 +641,7 @@ export class StateLedger {
     }
     /** L3:具名 seam 确认——pending → confirmed,携 receipt(外部世界回执) */
     confirmPendingWrite(idemKey, receipt, actor = 'system:writegate') {
+        // 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) {
@@ -493,6 +655,7 @@ export class StateLedger {
     }
     /** saga 补偿:pending/confirmed → compensated(SagaLLM 式补偿语义) */
     compensatePendingWrite(idemKey, note, actor = 'system:writegate') {
+        // 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) {
@@ -515,6 +678,7 @@ export class StateLedger {
     // ---- forget(D5:物理硬删,审计只留一行) ---------------------------------------
     /** 物理删除某主体的全部事件并重建投影;删除本身留一行审计事件(红线 6「可删除」)。 */
     forgetSubject(subjects, actor = 'system:state-cli') {
+        // DELETE events 开头 → 维持 DEFERRED(审计表见 runWrite 上方)。
         const run = this.db.transaction(() => {
             let deleted = 0;
             for (const s of subjects) {
@@ -537,25 +701,53 @@ export class StateLedger {
 }
 // ---- 打开/迁移(one-shot D2;模块级缓存避免每次读开新句柄) ----------------------
 const openLedgers = new Map();
-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');
-    // schema v1→v2 迁移:v1 无 tenant_id 列(user_version 未设置过,实际为 0)
-    const version = db.pragma('user_version', { simple: true });
-    if (version < 2) {
-        // 检测是否真有 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');
-        const isV1 = hasEventsTable && !eventsHasTenant;
-        db.transaction(() => {
+/**
+ * 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(`
@@ -571,7 +763,7 @@ export function openDb(stateRoot, tenant = 'local') {
             }
             else {
                 // v2 幂等:检查 workflow_runs 是否缺 tenant_id(修一次跑坏的迁移)
-                const wrHasTenant = db.prepare("PRAGMA table_info(workflow_runs)").all().some(c => c.name === '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;
@@ -584,17 +776,72 @@ export function openDb(stateRoot, tenant = 'local') {
             }
             db.exec(SCHEMA);
             db.pragma('user_version = 2');
-            db.prepare('INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v').run('schema_version', SCHEMA_VERSION);
-        })();
-        // v1 升级后:旧单用户事件只可安全归入 local;即使调用者打开非 local 租户,也只重建 local 投影。
-        if (isV1) {
-            const ledger = new StateLedger(db, stateRoot, 'local');
-            ledger.rebuildProjections();
+            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;
+    });
+    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);
+    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;
     }
-    else {
-        db.exec(SCHEMA); // 幂等建表(IF NOT EXISTS)
-        db.prepare('INSERT INTO kv (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v').run('schema_version', '2');
+    // 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);
@@ -637,7 +884,13 @@ export function ensureLedger(stateRoot, tenant = 'local') {
 }
 function importLegacyInto(ledger, dir) {
     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;
@@ -705,7 +958,7 @@ function importLegacyInto(ledger, dir) {
         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 回退旧文件(只读,绝不反向写) ---------

package/dist/src/unified.js

@@ -21,6 +21,12 @@ const SEGMENT_ROUTES = {
 function routeHint(id) {
     return SEGMENT_ROUTES[id];
 }
+// Issue #620 注:数据包缺 buffer_min/origin_transfer_min/dest_transfer_min 时,
+// 这里的 `Number(undefined)` = NaN 会一路流到求解层。NaN **不在 parse 边界补 0**
+// (补零等于替用户编接驳时间,ADR-10 翻译不造数),也不在这里整包拒收
+// (data/yunnan-pack.json 的 yn0 真值按 meta.reconcil 仍待 founder 校准)。
+// 防线在 solveUnifiedInner 的 assertZ3IntegerInputs:进 Z3 之前逐字段点名,
+// 以显式 solver_error 返回,绝不冒充「不可行」。
 // ---- 适配器:旧候选用例(洱海形态:request + candidates)→ 单 choice 段 -------------
 // 与 py unified.py segments_from_candidate 逐行对齐
 export function segmentsFromCandidate(req, candidates) {
@@ -380,16 +386,70 @@ function releaseZ3(resource) {
     if (typeof resource?.release === 'function')
         resource.release();
 }
+/** Issue #620:进 Z3 前的输入类型闸。`Int.val(NaN|Infinity|小数)` 在 WASM 里是
+ *  `Assertion failed`,不是一个可解释的判定——所以在构造 AST 之前抛可定位的类型化错误。 */
+export class SolverInputError extends Error {
+    code = 'solver_input_not_integer';
+    constructor(message) {
+        super(message);
+        this.name = 'SolverInputError';
+    }
+}
+/** 把所有将要变成 `Int.val(...)` 的数验成有限整数;违例逐项点名(段/候选/字段)。 */
+function assertZ3IntegerInputs(spec, wakeFloorMin) {
+    const bad = [];
+    const check = (where, value) => {
+        // NaN/Infinity 经 JSON.stringify 会变成 "null",诊断信息就丢了——数值一律按原文印。
+        if (!Number.isInteger(value))
+            bad.push(`${where}=${typeof value === 'number' ? String(value) : JSON.stringify(value)}`);
+    };
+    check('wakeFloorMin', wakeFloorMin);
+    if (spec.budgetCny !== undefined)
+        check('budgetCny', spec.budgetCny);
+    for (const seg of spec.segments) {
+        if (seg.anchors?.arriveByMin !== undefined)
+            check(`${seg.id}.anchors.arriveByMin`, seg.anchors.arriveByMin);
+        if (seg.anchors?.departAfterMin !== undefined)
+            check(`${seg.id}.anchors.departAfterMin`, seg.anchors.departAfterMin);
+        // 段级 wake/arriveStay 编码只取 options[0].move 的接驳口径(见下方 o0)。
+        const o0 = seg.options[0]?.move;
+        if (o0) {
+            check(`${seg.id}.bufferMin`, o0.bufferMin);
+            check(`${seg.id}.originTransferMin`, o0.originTransferMin);
+            check(`${seg.id}.destTransferMin`, o0.destTransferMin);
+        }
+        for (const opt of seg.options) {
+            const svc = opt.move?.services[0];
+            if (!svc) {
+                bad.push(`${seg.id}/${opt.id}.services[0]=missing`);
+                continue;
+            }
+            check(`${seg.id}/${opt.id}.depMin`, svc.depMin);
+            check(`${seg.id}/${opt.id}.arrMin`, svc.arrMin);
+            check(`${seg.id}/${opt.id}.priceCny`, svc.priceCny);
+        }
+    }
+    if (bad.length > 0) {
+        throw new SolverInputError(`solveUnified: Z3 整数编码只接受有限整数,下列输入不是(issue #620):${bad.slice(0, 8).join('、')}`
+            + (bad.length > 8 ? `(共 ${bad.length} 处)` : ''));
+    }
+}
 /** 航班链形态求解:按 Option 选择,锚点命名约束,core 剥竖线(D-2 修复) */
 export async function solveUnified(spec) {
-    // WASM 防护:如果 z3-solver 加载或求解触发 memory access 错误,不让异常穿透到进程层把 dsh 杀掉。
-    // 候选形态走 solveChoiceSegment 不经过这里——这里是显式航班链路径,用户量较少。
+    // 求解器失败防护:z3-solver 加载/求解异常不让它穿透到进程层把 dsh 杀掉。
+    // 但也**不冒充判定**(issue #620):崩溃以 solver_error 显式返回,unsat_core 保持缺席,
+    // 否则「引擎故障」会被下游当成「你的行程不可行」,理由位置上还放着机器 token。
+    // 候选形态走 solveChoiceSegment 不经过这里——这里是显式航班链路径。
     try {
         return await solveUnifiedInner(spec);
     }
     catch (e) {
-        console.error('[gotry] solveUnified failed (likely wasm thread race):', e.message?.slice(0, 200));
-        return { feasible: false, unsat_core: ['wasm_runtime_error'], red_flags: ['WASM 求解器异常,建议下次用候选形态(枚举)重试'] };
+        const err = e instanceof Error ? e : new Error(String(e));
+        const code = err instanceof SolverInputError ? err.code : 'solver_runtime_error';
+        const message = (err.message ?? '').slice(0, 200);
+        // 措辞纪律:不再写「likely wasm thread race」——#620 证明它也可能是确定性的输入错误。
+        console.error(`[gotry] solveUnified aborted — ${code}(求解器失败,不是「不可行」判定):`, message);
+        return { feasible: false, solver_error: { code, message } };
     }
 }
 async function solveUnifiedInner(spec) {
@@ -418,11 +478,15 @@ async function solveUnifiedInner(spec) {
             return { feasible: false, unsat_core: [`${seg.id}:work_window`], work_window_exclusions: exclusions };
         }
     }
+    // Issue #620:类型闸在 Z3 会话之外先跑——非整数输入不许进 WASM(进去就是
+    // `Assertion failed`,还会污染共享实例)。抛 SolverInputError,由 solveUnified 归类。
+    const wakeFloorPre = spec.defaultWakeFloorMin ?? hhmmToMin('06:00');
+    assertZ3IntegerInputs(spec, wakeFloorPre);
     // Z3 会话进互斥门(骨架/预过滤等网络段留在门外):solveUnifiedInner 的判定段
     // 从 here 到 return 全部独占共享实例。
     return withZ3('unified.solveUnifiedInner', async (z3) => {
         const { Bool, If, Int, Solver, Sum } = z3;
-        const wakeFloor = spec.defaultWakeFloorMin ?? hhmmToMin('06:00');
+        const wakeFloor = wakeFloorPre;
         const allSels = {};
         const assertions = {};
         const svcOf = {};

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Stai Travel Bridge",
-  "version": "0.2.0.27",
+  "version": "0.2.0.28",
   "description": "Stai 连接获准的旅行检索与供应商门户：检索结果经本机或授权后端桥接；门户可触发一次性登录代填，扩展不持久保存凭据。",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnuzBX8rT8+RZKEUip5VRA0cY056pExy9PNdN9YCiuY3dgglRbcIBhjuFJoR6EX3/MaUv82vJVyItRVrowXLTwDk4WZof0vwFgKL0zBK304PC46pUaAKTSu1PgXeL1+j5KTAGz/9a9+RnPdbj7jND5rM/MOmBHNPVPpp1NlwxRGIgF9OxHSOfXORcH4Iyte1aJSFUJbFtNS/DaE5D+KjyupPLyIqVN/dCiKnNsTCEHQB9ngeli665PFp76hkccHQQZ4sVuMLS4zBPcazUsp1kcnW+xsQoUATkODTCY+Pzk3zUVF1QOESTjRCVnbNi8tkO43RMRs2q63gX/3inFivcEwIDAQAB",
   "permissions": [
@@ -56,5 +56,5 @@
       "run_at": "document_start"
     }
   ],
-  "version_name": "0.2.0-rc.27"
+  "version_name": "0.2.0-rc.28"
 }