sillyspec 3.27.12 → 3.28.0

package/.claude/worktrees/sillyspec-data-model-research/src/db.js

@@ -1,381 +0,0 @@
-import { openDatabase, applyPragmas, runTransaction } from './db-engine.js';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { dirname } from 'path';
-
-// DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
-// 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema（W4-H：高频读路径 gate/derive/status
-// 每次 new ProgressManager 都过 init，靠版本戳跳过建表省开销）。
-// node:sqlite（DatabaseSync）是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
-// _createSchema 内 DDL 直接落盘，无需额外 _save。
-const DB_SCHEMA_VERSION = 5;
-
-// SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）：WAL 单写者模型，并发写第二者在
-// busy_timeout=5000（init PRAGMA）后抛 SQLITE_BUSY。busy_timeout 已在引擎层处理大部分等待；
-// 此处常量给 transaction() 做超时后的应用层兜底重试。
-// 仅 SQLITE_BUSY 重试（其它异常直接上抛）；MAX_BUSY_RETRIES 有限次防死循环，达上限 fail-loud
-// 不静默吞错。BUSY_BACKOFF_MS 递增退避（50→100→200ms），总等待上限 350ms。
-// busy_timeout=5000 保持不变（design §7）：引擎层 5s 等待已覆盖大部分锁竞争，应用层 3 次退避
-// 足够消化极端并发超时尖刺，无需抬高 busy_timeout（过长会让单次写阻塞拖慢整体吞吐）。
-const MAX_BUSY_RETRIES = 3;
-const BUSY_BACKOFF_MS = [50, 100, 200];
-
-/**
- * 同步阻塞 sleep（node:sqlite 同步 API，BUSY 退避不能用 await）。
- * Atomics.wait 阻塞当前线程不占 CPU；SharedArrayBuffer 不可用的环境（受限 CSP / 旧 Node）
- * 退化为 busy-wait（退避时长 50-200ms 短，CPU 占用可接受）。仅在 transaction() 的 BUSY
- * 重试路径调用。
- */
-function _sleepSync(ms) {
-  try {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-  } catch {
-    const end = Date.now() + ms;
-    while (Date.now() < end) { /* busy-wait fallback */ }
-  }
-}
-
-export class DB {
-  constructor(dbPath) {
-    this.dbPath = dbPath;
-    this.db = null;
-  }
-
-  /**
-   * 同步初始化（node:sqlite DatabaseSync 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
-   *  - openDatabase(path) 同步打开/创建库文件（node:sqlite 原生绑定，非 WASM）
-   *  - PRAGMA：journal_mode=WAL 真生效（node:sqlite 直连原生 SQLite，WAL 落地；
-   *    sql.js 是纯内存库，WAL 对它无意义），busy_timeout=5000 让写锁竞争时自动等待，
-   *    foreign_keys=ON 启用外键级联，synchronous=NORMAL 在 WAL 下兼顾安全与性能
-   *  - schema 戳检查：内容匹配 DB_SCHEMA_VERSION 则跳过 _createSchema，省建表开销
-   *  - node:sqlite 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
-   *
-   * .bak 损坏回退由 _openWithFallback() 承担（task-04）：主库 → .bak → 全新/报错 逐级回退，
-   * 语义对齐原 sql.js 的 _loadDatabase。
-   */
-  init() {
-    // 1. 确保父目录存在
-    const dir = dirname(this.dbPath);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
-    // 2. 同步打开/创建数据库（主库 → .bak → 全新/报错 逐级回退，归 task-04）
-    this.db = this._openWithFallback();
-
-    // 3. 设置 PRAGMA（node:sqlite 走真 SQLite，journal_mode=WAL 真生效；经 applyPragmas 逐条 exec）
-    applyPragmas(this.db, [
-      ['journal_mode', 'WAL'],
-      ['busy_timeout', '5000'],
-      ['foreign_keys', 'ON'],
-      ['synchronous', 'NORMAL'],
-    ]);
-
-    // 4. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
-    //    schema 已最新则跳过建表，省 DDL 开销。node:sqlite 打开即持久化，
-    //    _createSchema 内 DDL 直接落盘，无需 _save。
-    //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），不在本层兜底。
-    const versionPath = `${this.dbPath}.schema-version`;
-    let schemaCurrent = false;
-    try {
-      schemaCurrent = existsSync(versionPath)
-        && readFileSync(versionPath, 'utf8').trim() === String(DB_SCHEMA_VERSION);
-    } catch { /* 戳读取失败保守重跑 schema */ }
-
-    if (!schemaCurrent) {
-      this._createSchema();
-      try { writeFileSync(versionPath, String(DB_SCHEMA_VERSION)); } catch { /* 戳写入失败不阻断，下次重跑 */ }
-    }
-  }
-
-  /**
-   * 打开数据库（主库 → .bak → 全新/报错 逐级回退）。
-   * 语义对齐原 sql.js 的 _loadDatabase，但 node:sqlite 绑定文件路径无 _save，
-   * .bak 回退时 copyFileSync 把 .bak 内容恢复到主库路径，统一用 dbPath。
-   *  - 主库存在且有内容且可打开：直接用。
-   *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 原因后 copy 回主库使用。
-   *  - 都不可用：主库不存在→建全新空库；主库曾存在(空/损坏)→fail-loud 抛错(不静默建空库吞进度)。
-   * node:sqlite 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
-   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——node:sqlite 视其为合法空库）。
-   * 注：node:sqlite 提交即持久化，不再写前备份主 .bak（sql.js 时代 _save/_atomicWriteSync 已随
-   * 2026-08-11 迁移移除）；此恢复分支是向后兼容兜底，仅对 sql.js 时代遗留的 .bak 生效，
-   * 全新 node:sqlite 项目不产生主 .bak）。
-   */
-  _openWithFallback() {
-    const bakPath = `${this.dbPath}.bak`;
-    // readValid: null=文件不存在；'empty'=存在但 0 字节；'ok'=有内容
-    const readValid = (p) => {
-      if (!existsSync(p)) return null;
-      return statSync(p).size === 0 ? 'empty' : 'ok';
-    };
-    // tryOpen: openDatabase(path) + prepare 探测双保险（防打开成功但内容非 SQLite）。
-    // 探测前先设 busy_timeout（2026-08-21 审查 BUG-7）：init() 的 applyPragmas 在 _openWithFallback
-    // 之后才跑，探测 SELECT 此前以 busy_timeout=0（SQLite 默认）执行——他者进程 CHECKPOINT 改写
-    // 主库时探测立即 SQLITE_BUSY，3 次重试总窗口仅 350ms，大 WAL 下 checkpoint 秒级 → 健康库
-    // 被误判"损坏"硬抛错。先设 busy_timeout 让探测自身等待锁，重试只剩消化瞬时抖动。
-    const tryOpen = (p) => {
-      let db;
-      try { db = openDatabase(p); }
-      catch { return null; }
-      try {
-        db.exec('PRAGMA busy_timeout = 5000');
-        db.prepare('SELECT count(*) FROM sqlite_master').get(); return db;
-      } catch { try { db.close(); } catch { /* 关闭失败忽略 */ } return null; }
-    };
-
-    // 1. 主库（0 字节=截断信号，必须走回退，故门禁要求 'ok' 有内容）
-    if (readValid(this.dbPath) === 'ok') {
-      const primaryDb = tryOpen(this.dbPath);
-      if (primaryDb) return primaryDb;
-      // 并发首开竞争（2026-08-12 db-concurrency flaky 根因实证）：多进程近乎同时
-      // new DB().init() 打开同一新建库时，tryOpen 的 prepare(SELECT count(*)) 可能撞上
-      // 他者进程的 CHECKPOINT 改写主库 → 瞬时失败返 null。此时主库存在且有内容，
-      // 非真损坏——有限重试消化锁竞争（复用 MAX_BUSY_RETRIES 退避，与 transaction 的
-      // SQLITE_BUSY 重试同基建）。真损坏重试也不会过，最终仍走 .bak 回退 / fail-loud，
-      // 防吞进度语义零回归。
-      for (let attempt = 0; attempt < MAX_BUSY_RETRIES; attempt++) {
-        _sleepSync(BUSY_BACKOFF_MS[attempt]);
-        const retryDb = tryOpen(this.dbPath);
-        if (retryDb) return retryDb;
-      }
-    }
-
-    // 2. .bak 回退（.bak 是恢复源：存在且能打开即用，含 0 字节空库；门禁只挡"不存在"，
-    //    避免 tryOpen 对不存在的路径触发 openDatabase 的副作用——会凭空创建文件）
-    if (readValid(bakPath) !== null) {
-      const bakDb = tryOpen(bakPath);
-      if (bakDb) {
-        const primaryRaw = readValid(this.dbPath);
-        const reason = primaryRaw === 'empty'
-          ? 'sillyspec.db 为空（可能被截断）'
-          : primaryRaw === null
-            ? 'sillyspec.db 不存在'
-            : 'sillyspec.db 损坏';
-        console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
-        bakDb.close();
-        // 覆盖前救援快照（2026-08-21 审查 BUG-7）：主库有内容但打不开（"损坏"）时，其中可能
-        // 含比 .bak 更新的数据——静默覆盖即静默丢。best-effort 留一份 .corrupt-<ts> 副本供人工恢复。
-        if (primaryRaw === 'ok') {
-          try { copyFileSync(this.dbPath, `${this.dbPath}.corrupt-${Date.now()}`); } catch { /* 救援失败不阻断恢复 */ }
-        }
-        // node:sqlite 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath。
-        // 体检 BUG-18：主库可能正被其他进程（daemon/另一 CLI）打开——Windows 覆盖他人
-        // 打开的文件抛 EPERM/EBUSY，短暂退避重试（持有者通常是瞬时句柄），仍失败 fail-loud
-        let copied = false;
-        let lastErr = null;
-        for (let attempt = 0; attempt < 5 && !copied; attempt++) {
-          try {
-            copyFileSync(bakPath, this.dbPath);
-            copied = true;
-          } catch (e) {
-            if (!['EPERM', 'EBUSY', 'EACCES'].includes(e.code)) throw e;
-            lastErr = e;
-            _sleepSync(50 * (attempt + 1));
-          }
-        }
-        if (!copied) throw lastErr;
-        return openDatabase(this.dbPath);
-      }
-    }
-
-    // 3. 都不可用
-    if (readValid(this.dbPath) === null) {
-      // 主库与备份都不存在 → 全新项目，建空库
-      return openDatabase(this.dbPath);
-    }
-    // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud（不静默建空库吞进度）
-    throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
-  }
-
-  /**
-   * 关闭数据库。node:sqlite 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
-   * 不需要 sql.js 时代的 _save() 整库 export 落盘。
-   */
-  close() {
-    if (this.db) {
-      try {
-        this.db.close();
-      } catch (err) {
-        // close 自身失败（如 WAL checkpoint 磁盘满）：仍置 null 防后续操作已损坏句柄，warn 留痕不吞
-        console.warn(`[db] close 失败（句柄已废弃）: ${err && err.message ? err.message : err}`);
-      } finally {
-        this.db = null;
-      }
-    }
-  }
-
-  /**
-   * 原生事务 + SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）。
-   *
-   * node:sqlite 无 .transaction()，runTransaction(fn)（db-engine）用 SAVEPOINT/RELEASE/
-   * ROLLBACK TO 手写事务：fn 抛错自动回滚且不吞错，嵌套调用自动形成 savepoint 栈
-   * （对齐旧引擎嵌套自动 SAVEPOINT 的兼容实现）。无需手动 BEGIN/COMMIT/ROLLBACK，
-   * 也无需 _save（node:sqlite 提交即持久化）。
-   *
-   * SQLITE_BUSY 重试：WAL 单写者模型，并发写第二者在 busy_timeout=5000 后抛 BUSY。此处对
-   * BUSY 加 MAX_BUSY_RETRIES 次递增退避（BUSY_BACKOFF_MS）；仅 BUSY 重试（其它异常直接上抛），
-   * 达上限 fail-loud 抛错不静默吞（防死循环）。BUSY 重试收敛在 DB 层 transaction 封装，
-   * 所有写者（progress.js _write / initChange / setStage 等）统一受益，不散落调用点。
-   */
-  transaction(fn) {
-    if (!this.db) throw new Error('DB not initialized');
-    let attempt = 0;
-    while (true) {
-      try {
-        return runTransaction(this.db, fn);
-      } catch (err) {
-        // 仅 SQLITE_BUSY 重试（node:sqlite err.errcode 为 5 / err.code 为 'ERR_SQLITE_ERROR'，message 含 'database is locked'）
-        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5 || err.errcode === 5
-          || (typeof err.message === 'string' && /database is locked|SQLITE_BUSY/i.test(err.message)));
-        if (!isBusy) throw err;
-        if (attempt >= MAX_BUSY_RETRIES) throw err; // 达上限 fail-loud（不静默吞，防死循环）
-        _sleepSync(BUSY_BACKOFF_MS[attempt]);
-        attempt++;
-      }
-    }
-  }
-
-  /** 获取底层 db 对象（node:sqlite DatabaseSync 实例，供 progress.js 直接使用） */
-  getDb() {
-    return this.db;
-  }
-
-  _createSchema() {
-    // node:sqlite：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
-    // sql.js 的 .run(sql) 在此换为 .exec(sql)。
-
-    // project 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS project (
-        id INTEGER PRIMARY KEY DEFAULT 1,
-        name TEXT NOT NULL,
-        schema_version INTEGER DEFAULT 5,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL
-      )
-    `);
-
-    // changes 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS changes (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT UNIQUE NOT NULL,
-        current_stage TEXT DEFAULT 'scan',
-        status TEXT DEFAULT 'active',
-        no_worktree INTEGER DEFAULT 0,
-        created_at TEXT NOT NULL,
-        last_active TEXT NOT NULL,
-        platform_change_id INTEGER,
-        platform_workspace_id INTEGER,
-        platform_last_sync TEXT,
-        platform_sync_enabled INTEGER DEFAULT 0
-      )
-    `);
-
-    // stages 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS stages (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
-        stage TEXT NOT NULL,
-        status TEXT DEFAULT 'pending',
-        started_at TEXT,
-        completed_at TEXT,
-        UNIQUE(change_id, stage)
-      )
-    `);
-
-    // steps 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS steps (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        stage_id INTEGER NOT NULL REFERENCES stages(id) ON DELETE CASCADE,
-        name TEXT NOT NULL,
-        status TEXT DEFAULT 'pending',
-        output TEXT,
-        completed_at TEXT,
-        ordering INTEGER NOT NULL DEFAULT 0
-      )
-    `);
-
-    // batch_progress 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS batch_progress (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
-        total INTEGER DEFAULT 0,
-        completed INTEGER DEFAULT 0,
-        failed INTEGER DEFAULT 0,
-        skipped INTEGER DEFAULT 0,
-        UNIQUE(change_id)
-      )
-    `);
-
-    // approvals 表
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS approvals (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        change_id INTEGER NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
-        status TEXT DEFAULT 'not_required',
-        requested_at TEXT,
-        approved_by TEXT,
-        approved_at TEXT,
-        rejection_reason TEXT,
-        UNIQUE(change_id)
-      )
-    `);
-
-    // 索引
-    this.db.exec('CREATE INDEX IF NOT EXISTS idx_changes_current_stage ON changes(current_stage)');
-    this.db.exec('CREATE INDEX IF NOT EXISTS idx_changes_status ON changes(status)');
-    this.db.exec('CREATE INDEX IF NOT EXISTS idx_stages_change ON stages(change_id)');
-    this.db.exec('CREATE INDEX IF NOT EXISTS idx_steps_stage ON steps(stage_id)');
-
-    // Migration: add isolation columns to changes table (idempotent)
-    this._migrateAddColumn('changes', 'isolation_status', 'TEXT');
-    this._migrateAddColumn('changes', 'isolation_mode', 'TEXT');
-    this._migrateAddColumn('changes', 'isolation_reason', 'TEXT');
-
-    // Migration: add waiting support columns to steps table (idempotent)
-    this._migrateAddColumn('steps', 'wait_reason', 'TEXT');
-    this._migrateAddColumn('steps', 'wait_options', 'TEXT');
-    this._migrateAddColumn('steps', 'wait_answer', 'TEXT');
-    this._migrateAddColumn('steps', 'waited_at', 'TEXT');
-    // repeatableWait support
-    this._migrateAddColumn('steps', 'wait_answers', 'TEXT'); // JSON array
-    this._migrateAddColumn('steps', 'wait_round', 'INTEGER');
-    this._migrateAddColumn('steps', 'max_wait_rounds', 'INTEGER');
-
-    // Revision v1 support
-    this._migrateAddColumn('stages', 'revision', 'INTEGER DEFAULT 0');
-    this._migrateAddColumn('stages', 'reopened_from_step', 'TEXT');
-    this._migrateAddColumn('stages', 'reopened_at', 'TEXT');
-    this._migrateAddColumn('stages', 'stale_reason', 'TEXT');
-
-    // Platform sync support（2026-08-10-platform-progress-sync §8 / D-012）：
-    // changes 表加 base_ts（last_synced_platform_ts）与本地脏度（last_local_modified_ts）两列，
-    // 为 serializeForSync()/import() 序列化与 base_ts 乐观锁冲突检测提供数据载体。
-    // NULL 语义（gap8）：last_local_modified_ts NULL=本地无脏度（pull 不判冲突直接 import）；
-    // last_synced_platform_ts NULL=首次同步（base_ts NULL 平台接受首次 push）。
-    this._migrateAddColumn('changes', 'last_synced_platform_ts', 'TEXT');
-    this._migrateAddColumn('changes', 'last_local_modified_ts', 'TEXT');
-
-    // changes 表加 title（人类可读中文标题）+ quicklog_id（关联 QUICKLOG ql-ID）两列：
-    // 让 quick-<hex> 这种机器 hash sessionId 命名的 change 行可读，DB↔QUICKLOG 可对账。
-    // quick 启动时回填（stage.js：title 从任务描述提取、quicklog_id 用分配的 qlId），
-    // --done 时从 step3「需求：」刷新 title（agent 可改）。完整流程 change 的 name 本身
-    // 已语义化，title/quicklog_id 留空。不纳入平台同步脏度（本地展示用元信息）。
-    this._migrateAddColumn('changes', 'title', 'TEXT');
-    this._migrateAddColumn('changes', 'quicklog_id', 'TEXT');
-  }
-
-  /**
-   * 幂等地给表添加列（列已存在则跳过）。
-   * node:sqlite：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
-   * @private
-   */
-  _migrateAddColumn(table, column, type) {
-    try {
-      this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
-    } catch {
-      // 列已存在，静默跳过
-    }
-  }
-}