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

package/ts/src/state-ledger.ts

@@ -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'
@@ -77,6 +87,108 @@ function isUniqueViolation(e: unknown): boolean {
   return e instanceof Error && (e as { code?: string }).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: ReadonlySet<string> = new Set([
+  'SQLITE_BUSY',
+  'SQLITE_BUSY_TIMEOUT',
+  'SQLITE_BUSY_SNAPSHOT',
+  'SQLITE_BUSY_RECOVERY',
+  'SQLITE_PROTOCOL',
+])
+
+function sqliteCodeOf(e: unknown): string | undefined {
+  const code = (e as { code?: unknown } | null | undefined)?.code
+  return typeof code === 'string' ? code : undefined
+}
+
+function isContention(e: unknown): boolean {
+  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_* 撞名。 */
+  readonly code = 'GOTRY_LEDGER_BUSY'
+  readonly op: string
+  readonly attempts: number
+  readonly sqliteCode: string | undefined
+
+  constructor(op: string, attempts: number, cause: unknown) {
+    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: number): void {
+  if (ms <= 0) return
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/** 指数退避 + pid 抖动:N 个进程同时冷启动时不会同节奏再撞第二次。 */
+function backoffMs(attempt: number): number {
+  return Math.min(5 * 2 ** attempt, 160) + (process.pid % 11)
+}
+
+/**
+ * 有界重试争用码,耗尽即抛 LedgerBusyError。
+ *
+ * 只对「整体提交或整体回滚」的单元使用:事务函数回滚后守门纯函数会重新读当前
+ * 状态再算一遍,所以重跑是幂等的(事件另有 idem_key UNIQUE 兜底)。
+ */
+function withContentionRetry<T>(op: string, fn: () => T, opts: { retries?: number; budgetMs?: number } = {}): T {
+  const retries = opts.retries ?? CONTENTION_RETRIES
+  const deadline = opts.budgetMs === undefined ? undefined : Date.now() + opts.budgetMs
+  let lastError: unknown
+  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,
@@ -262,6 +374,50 @@ 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 忽略)时不自行重试:重试归最外层事务所有,否则会在一个已经
+   * 注定回滚的事务里空转。
+   */
+  private runWrite<T>(op: string, fn: () => T): T {
+    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: ProfilePatch, actor = 'tool:gotry_motivation_save'): {
     saved: boolean
@@ -270,7 +426,8 @@ export class StateLedger {
     // 事件边界 ISO:事件行的 ts 就是 homeCityPreference.updated_at 的源头,
     // fold 路径会读同一字段回放——rebuildProjections 必须能复现该值。
     const ts = new Date().toISOString()
-    const run = this.db.transaction((): { saved: boolean; profile: MergedProfile & { updated_at?: string } } => {
+    // 读改写(readMotivation → mergeProfile → 写投影):第一条语句是 SELECT → IMMEDIATE。
+    return this.runWrite('appendMotivationPatch', (): { saved: boolean; profile: MergedProfile & { updated_at?: string } } => {
       const current = this.readMotivation()
       const merged = mergeProfile(current, patch, ts)
       if (!merged) {
@@ -285,7 +442,6 @@ export class StateLedger {
       ).run(this.tenant, JSON.stringify(doc))
       return { saved: true, profile: doc }
     })
-    return run()
   }
 
   /** 愿望入池/同名幂等更新(红线:conditions 必填非空) */
@@ -301,7 +457,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((): { added: boolean; wish_id: string; total: number } => {
+    // 读改写(readWishPool → 同名判定 → 写事件+投影):第一条语句是 SELECT → IMMEDIATE。
+    // 这是 D15-2 演练里实际失败的那条路径。
+    return this.runWrite('appendWish', (): { added: boolean; wish_id: string; total: number } => {
       const pool = this.readWishPool()
       const existing = pool.find(w => String(w.name ?? '') === name)
       if (existing) {
@@ -330,13 +488,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: Omit<MemoryUtilityEvent, 'schema' | 'event_id'>, actor = 'tool:gotry_wish_pool_list'): { appended: boolean; events: MemoryUtilityEvent[] } {
     const full = gateUtilityEvent([], ev).events[0]
     if (!full) return { appended: false, events: this.readUtilityEvents() }
+    // 非读改写:事务内只有一条 INSERT,写锁在第一条语句就拿到,不存在快照升级。
+    // 维持 DEFERRED(与修复前逐字节同义),争用只会落到 busy_timeout 等待上。
     const run = this.db.transaction((): boolean => {
       return this.insertEvent({ actor, kind: 'memory_utility.event', subjectId: full.wish_id, payload: { event: full }, idemKey: `mu:${full.event_id}` }) !== null
     })
@@ -345,7 +504,9 @@ export class StateLedger {
 
   /** 时间线行程(守门 = appendTrip:必填/绝对日期/重叠冲突即停;幂等键 = trip_id) */
   appendTripEvent(ev: Omit<TimelineEvent, 'schema' | 'trip_id' | 'ts'>, actor = 'tool:gotry_trip_log'): { appended: boolean; tripId?: string; reason?: string; total: number } {
-    const run = this.db.transaction((): { appended: boolean; tripId?: string; reason?: string; total: number } => {
+    // 读改写(readTrips → 重叠冲突判定 → 写事件):第一条语句是 SELECT → IMMEDIATE。
+    // 重叠判定必须看见提交后的全量行程,否则两个进程可以各写一条互相重叠的行程。
+    return this.runWrite('appendTripEvent', (): { appended: boolean; tripId?: string; reason?: string; total: number } => {
       const existing = this.readTrips()
       const gate = gateTrip(existing, ev)
       if (!gate.appended) return { appended: false, tripId: gate.tripId, reason: gate.reason, total: existing.length }
@@ -353,12 +514,13 @@ 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: { label: string; constraints: CompanionConstraints; evidence: string }, actor = 'tool:gotry_companion_save'): { appended: boolean; companionId: string; reason?: string; total: number } {
-    const run = this.db.transaction((): { appended: boolean; companionId: string; reason?: string; total: number } => {
+    // 读改写(readCompanions → upsertCompanion → DELETE+INSERT 整组投影):
+    // 第一条语句是 SELECT → IMMEDIATE。replaceItems 整组重写,丢更新的代价最大。
+    return this.runWrite('appendCompanion', (): { appended: boolean; companionId: string; reason?: string; total: number } => {
       const profiles = this.readCompanions()
       const res = upsertCompanion(profiles, patch)
       if (!res.appended) return { appended: false, companionId: res.companionId, reason: res.reason, total: profiles.length }
@@ -366,7 +528,6 @@ 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()
   }
 
   /**
@@ -382,7 +543,9 @@ export class StateLedger {
     recorded: boolean
     trip?: { appended: boolean; tripId?: string; reason?: string }
   } {
-    const run = this.db.transaction((): { recorded: boolean; trip?: { appended: boolean; tripId?: string; reason?: string } } => {
+    // 读改写:行程分支里 readTrips → gateTrip → 写事件;且 full 为空时整个事务
+    // 以 SELECT 开头。两个写同一事务提交的原子性正是本方法的存在理由 → IMMEDIATE。
+    return this.runWrite('confirmOutcome', (): { recorded: boolean; trip?: { appended: boolean; tripId?: string; reason?: string } } => {
       const now = new Date().toISOString()
       const full = gateUtilityEvent([], {
         wish_id: input.wishId, kind: 'verified_outcome', ts: now,
@@ -403,7 +566,6 @@ export class StateLedger {
       }
       return { recorded, trip }
     })
-    return run()
   }
 
   // ---- 投影维护 ---------------------------------------------------------------
@@ -442,6 +604,8 @@ export class StateLedger {
    * 与写路径共用同一套纯函数 → 直读投影与 fold 结果一致(账本/投影永不分叉的可验证性)。
    */
   rebuildProjections(toSeq?: number): { events: number; wishes: number; companions: number } {
+    // DELETE 开头 → 写锁即刻到手,维持 DEFERRED(审计表见 runWrite 上方);
+    // 且本方法常被 forgetSubject/importLegacyInto 嵌套调用,嵌套层不该自己重试。
     const run = this.db.transaction((): { events: number; wishes: number; companions: number } => {
       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)
@@ -517,6 +681,7 @@ export class StateLedger {
 
   createWorkflowRun(input: { id: string; goal: string; ticket: unknown; state: unknown }, actor = 'system:async-request'): void {
     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)
@@ -561,6 +726,7 @@ export class StateLedger {
     terminalOutcome?: unknown,
     actor = 'system:async-collect',
   ): void {
+    // UPDATE ... WHERE status = 'pending' 开头(CAS 式状态推进)→ 维持 DEFERRED。
     const run = this.db.transaction(() => {
       const update = this.db.prepare(
         `UPDATE workflow_runs SET status = ?, deliverable = ?, updated = ?
@@ -611,6 +777,7 @@ export class StateLedger {
   /** 登记一笔待确认外部写(幂等键去重:同一确认不可能登记两次)。L2 = 只登记不执行。 */
   requestPendingWrite(input: { idemKey: string; seam: string; payload: unknown }, actor = 'system:writegate'): { created: boolean; status: string } {
     const ts = new Date().toISOString()
+    // INSERT ... ON CONFLICT DO NOTHING 开头 → 维持 DEFERRED。
     const run = this.db.transaction((): { created: boolean; status: string } => {
       const info = this.db.prepare(
         `INSERT INTO pending_writes (tenant_id, idem_key, seam, payload, status, created, updated)
@@ -628,6 +795,7 @@ export class StateLedger {
 
   /** L3:具名 seam 确认——pending → confirmed,携 receipt(外部世界回执) */
   confirmPendingWrite(idemKey: string, receipt: string, actor = 'system:writegate'): { ok: boolean; status: string } {
+    // UPDATE ... WHERE status = 'pending' 开头(CAS)→ 维持 DEFERRED。
     const run = this.db.transaction((): { ok: boolean; status: string } => {
       const info = this.db.prepare(
         `UPDATE pending_writes SET status = 'confirmed', receipt = ?, updated = ? WHERE idem_key = ? AND status = 'pending' AND tenant_id = ?`,
@@ -644,6 +812,7 @@ export class StateLedger {
 
   /** saga 补偿:pending/confirmed → compensated(SagaLLM 式补偿语义) */
   compensatePendingWrite(idemKey: string, note: string, actor = 'system:writegate'): { ok: boolean; status: string } {
+    // UPDATE ... WHERE status != 'compensated' 开头(CAS)→ 维持 DEFERRED。
     const run = this.db.transaction((): { ok: boolean; status: string } => {
       const info = this.db.prepare(
         `UPDATE pending_writes SET status = 'compensated', receipt = COALESCE(receipt, ?), updated = ? WHERE idem_key = ? AND status != 'compensated' AND tenant_id = ?`,
@@ -672,6 +841,7 @@ export class StateLedger {
 
   /** 物理删除某主体的全部事件并重建投影;删除本身留一行审计事件(红线 6「可删除」)。 */
   forgetSubject(subjects: Array<{ kinds: string[]; subjectId: string }>, actor = 'system:state-cli'): { deleted: number } {
+    // DELETE events 开头 → 维持 DEFERRED(审计表见 runWrite 上方)。
     const run = this.db.transaction((): { deleted: number } => {
       let deleted = 0
       for (const s of subjects) {
@@ -698,25 +868,51 @@ export class StateLedger {
 
 const openLedgers = new Map<string, StateLedger>()
 
-export function openDb(stateRoot: string, tenant = 'local'): StateLedger {
-  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 }) as number
-  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() as Array<{ name: string }>).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: Database.Database): void {
+  const currentMode = (): string => 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: Database.Database): boolean {
+  // 快路径: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((): boolean => {
+    // 版本探测搬进事务:与建表同处一个写锁下,不再有两个进程各读到 0 的 TOCTOU。
+    const version = db.pragma('user_version', { simple: true }) as number
+    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() as Array<{ name: string }>).some(c => c.name === 'tenant_id')
+      isV1 = hasEventsTable && !eventsHasTenant
       if (isV1) {
         // v1 → v2:events 加 tenant_id,回填 'local';投影/工单/pending_writes 强制重建(旧表无 tenant_id)
         db.exec(`
@@ -731,7 +927,7 @@ export function openDb(stateRoot: string, tenant = 'local'): StateLedger {
         `)
       } else {
         // v2 幂等:检查 workflow_runs 是否缺 tenant_id(修一次跑坏的迁移)
-        const wrHasTenant = (db.prepare("PRAGMA table_info(workflow_runs)").all() as Array<{ name: string }>).some(c => c.name === 'tenant_id')
+        const wrHasTenant = (db.prepare('PRAGMA table_info(workflow_runs)').all() as Array<{ name: string }>).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;
@@ -744,16 +940,68 @@ export function openDb(stateRoot: string, tenant = 'local'): StateLedger {
       }
       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)
     }
-  } 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')
+    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'] as const
+
+/**
+ * 纯读探测:user_version 已是 2、SCHEMA 全部对象在位、kv 旗标已等于目标值
+ * → 慢路径(exec SCHEMA + kv upsert)可证明是空操作,于是整段写锁都省掉。
+ * 任何一项不满足(新库,或别的进程正在建而本连接还看不到)→ false,走慢路径。
+ */
+function schemaAlreadyCurrent(db: Database.Database): boolean {
+  try {
+    if ((db.pragma('user_version', { simple: true }) as number) < 2) return false
+    const present = new Set(
+      (db.prepare("SELECT name FROM sqlite_master WHERE type IN ('table', 'index')").all() as Array<{ name: string }>).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() as { v: string } | undefined
+    return row?.v === SCHEMA_VERSION
+  } catch {
+    return false
+  }
+}
+
+export function openDb(stateRoot: string, tenant = 'local'): StateLedger {
+  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
+  }
+  // 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)
@@ -802,7 +1050,13 @@ export function ensureLedger(stateRoot: string, tenant = 'local'): StateLedger {
 
 function importLegacyInto(ledger: StateLedger, dir: string): MigrationReport['imported'] {
   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() as { v: string } | undefined
     if (flag) return
     const readJsonSafe = (p: string): unknown | null => {
@@ -854,7 +1108,7 @@ function importLegacyInto(ledger: StateLedger, dir: string): MigrationReport['im
     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
 }
 

package/ts/src/unified.ts

@@ -117,6 +117,13 @@ function routeHint(id: string): string | undefined {
   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 逐行对齐
 
@@ -485,8 +492,20 @@ function releaseZ3(resource: { release?: () => void } | null | undefined): void
   if (typeof resource?.release === 'function') resource.release()
 }
 
-/** 航班链形态求解:按 Option 选择,锚点命名约束,core 剥竖线(D-2 修复) */
-export async function solveUnified(spec: JourneySpecTS): Promise<{
+/**
+ * Issue #620:求解器自身失败的显式类别。**不是 unsat_core**——判定缺席,不是「不可行」。
+ * 机器 token 只住在 `code` 里,不得渲染进任何用户面「冲突」文案。
+ */
+export type SolverErrorInfo = {
+  /** `solver_input_not_integer` = spec 里有非整数进不了 Z3 整数编码(确定性,可定位到字段);
+   *  `solver_runtime_error` = z3-solver / WASM 运行时异常(含真正的内存/竞态形态)。 */
+  code: 'solver_input_not_integer' | 'solver_runtime_error'
+  message: string
+}
+
+export interface UnifiedSolveResult {
+  /** `solver_error` 存在时,`feasible: false` 只表示「没有产出可行解」,
+   *  **不表示「不可行」**——那一轮根本没有判定。读者必须先看 `solver_error`。 */
   feasible: boolean
   money_cny?: number
   legs?: Array<LegReport & { leg: string; d2d_min?: number }>
@@ -495,27 +514,76 @@ export async function solveUnified(spec: JourneySpecTS): Promise<{
   suggestions?: Array<{ relax: string; money_cny: number }>
   work_window_exclusions?: Array<{ segment: string; option: string; reason: string }>
   skeleton_notes?: string[]
-}> {
-  // WASM 防护:如果 z3-solver 加载或求解触发 memory access 错误,不让异常穿透到进程层把 dsh 杀掉。
-  // 候选形态走 solveChoiceSegment 不经过这里——这里是显式航班链路径,用户量较少。
+  solver_error?: SolverErrorInfo
+}
+
+/** Issue #620:进 Z3 前的输入类型闸。`Int.val(NaN|Infinity|小数)` 在 WASM 里是
+ *  `Assertion failed`,不是一个可解释的判定——所以在构造 AST 之前抛可定位的类型化错误。 */
+export class SolverInputError extends Error {
+  readonly code = 'solver_input_not_integer' as const
+  constructor(message: string) {
+    super(message)
+    this.name = 'SolverInputError'
+  }
+}
+
+/** 把所有将要变成 `Int.val(...)` 的数验成有限整数;违例逐项点名(段/候选/字段)。 */
+function assertZ3IntegerInputs(spec: JourneySpecTS, wakeFloorMin: number): void {
+  const bad: string[] = []
+  const check = (where: string, value: unknown): void => {
+    // 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: JourneySpecTS): Promise<UnifiedSolveResult> {
+  // 求解器失败防护: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 as Error).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: SolverErrorInfo['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: JourneySpecTS): Promise<{
-  feasible: boolean
-  money_cny?: number
-  legs?: Array<LegReport & { leg: string; d2d_min?: number }>
-  red_flags?: string[]
-  unsat_core?: string[]
-  suggestions?: Array<{ relax: string; money_cny: number }>
-  work_window_exclusions?: Array<{ segment: string; option: string; reason: string }>
-  skeleton_notes?: string[]
-}> {
+async function solveUnifiedInner(spec: JourneySpecTS): Promise<UnifiedSolveResult> {
   // M-1:求解前的工作窗口确定性预过滤(与 py 对齐),排除理由入记录
   // 骨架层(§7-1):三值语义标注——枢纽间否定只降权不排除(骨架滞后会错杀 EK329)
   const skeletonNotes: string[] = []
@@ -541,11 +609,16 @@ async function solveUnifiedInner(spec: JourneySpecTS): Promise<{
     }
   }
 
+  // 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: Record<string, any[]> = {}
   const assertions: Record<string, any> = {}