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

package/dist/capabilities/session/bridge-ledger.js

@@ -0,0 +1,224 @@
+/**
+ * 桥作业账本(批次 A「桥作业账本化」,2026-10-01):extension-bridge 易失控制状态
+ * (队列/在飞/节律/客户端注册)的 SQLite 持久面,独立 db 文件
+ * `<stateRoot>/gotry-state/bridge.db`——**绝不触碰** state-ledger.ts 与内核清单钉住文件
+ * (ts/data/kernel-manifest.json);桥账本与产品状态账本物理分库,互不迁移。
+ *
+ * 修掉的真缺陷:
+ *   ① gotry-backend 重启丢在飞作业——claimed 作业随进程蒸发,回包到了也无人认领;
+ *     账本 + recoverOnBoot(见 extension-bridge.createBridgeJobQueue)让重启后
+ *     queued 重排、claimed 未超时复活、claimed 已超时结算 unresolved 并记节律冷却。
+ *   ② 未知 jobId 回包 200 静默丢弃——扩展真跑了的作业结果无痕消失;
+ *     现在 404 {ok:false,error:'unknown-job'} 且孤儿回包落 bridge_jobs(status='unresolved',
+ *     result_json 保留)供对账。
+ *
+ * 批次 B(2026-10-01,事件上行端点):bridge_events 表——扩展 workspace 事件
+ * (活动上下文,非权威事实)经 POST /v1/session/bridge/events 上行落账;
+ * idem_key 部分唯一索引(WHERE NOT NULL)让重试幂等:同 key 重发不重复落行。
+ *
+ * 红线继承:本账本只存**控制状态**(job 元数据/回包/节律/客户端能力清单/事件流水),
+ * 协议面不存在 cookie 值字段(extension-tests §38 红线断言),账本亦零凭据落库。
+ *
+ * 引擎:better-sqlite3(既有依赖,零新增);WAL + busy_timeout,同仓 readFileSync
+ * 风格的同步 API。时间戳一律 epoch 毫秒(INTEGER),与 timeout_at 比较同单位。
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+/** 站点节律冷却(毫秒):与 capabilities/session-search.ts 的 MIN_INTERVAL_MS 同口径 30s;导出仅测试/文档锚点 */
+export const BRIDGE_SITE_COOLDOWN_MS = 30_000;
+/** stateRoot 可相对可绝对(与 state-ledger.stateDirOf 同款解析) */
+function stateDirOf(stateRoot) {
+    const root = isAbsolute(stateRoot) ? stateRoot : join(process.cwd(), stateRoot);
+    return join(root, 'gotry-state');
+}
+export function bridgeLedgerDbPath(stateRoot) {
+    return join(stateDirOf(stateRoot), 'bridge.db');
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS bridge_jobs (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  site TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('queued','claimed','resolved','unresolved','void')),
+  claimed_by_client TEXT,
+  claimed_origin TEXT,
+  claimed_at INTEGER,
+  timeout_at INTEGER,
+  result_json TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS bridge_jobs_status ON bridge_jobs(status);
+
+CREATE TABLE IF NOT EXISTS bridge_clients (
+  client_id TEXT PRIMARY KEY,
+  origin TEXT NOT NULL,
+  capabilities_json TEXT NOT NULL DEFAULT '[]',
+  last_seen_at INTEGER NOT NULL,
+  login_sites_json TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS bridge_pacing (
+  site TEXT PRIMARY KEY,
+  last_hit_at INTEGER NOT NULL,
+  cooldown_until INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS bridge_events (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  client_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  site TEXT,
+  subject TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  idem_key TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS bridge_events_idem_key
+  ON bridge_events(idem_key) WHERE idem_key IS NOT NULL;
+`;
+/**
+ * SQLite 落地的桥作业账本(实现 extension-bridge.BridgeJobStore 契约)。
+ * 所有写方法单语句/单事务同步提交;调用方(extension-bridge)负责失败兜底
+ * (write-before-submit 的 INSERT 失败 = 提交失败,fail-closed 不入队)。
+ */
+export class BridgeLedgerStore {
+    dbPath;
+    db;
+    now;
+    constructor(dbPath, opts = {}) {
+        this.dbPath = dbPath;
+        this.now = opts.now ?? Date.now;
+        mkdirSync(dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.exec(SCHEMA);
+    }
+    /** write-before-submit:入队前先落 queued(提交失败 = 调用方不得派发) */
+    insertQueuedJob(job, timeoutAt) {
+        const ts = this.now();
+        this.db.prepare(`INSERT INTO bridge_jobs (id, kind, site, payload_json, status, timeout_at, attempts, created_at, updated_at)
+       VALUES (@id, @kind, @site, @payload, 'queued', @timeoutAt, 0, @ts, @ts)`).run({ id: job.jobId, kind: job.kind, site: job.site, payload: JSON.stringify(job), timeoutAt, ts });
+    }
+    /** 领取(/jobs 派发与 dispatchToParked 两处):claimed + 领取者 + attempts 递增 */
+    markClaimed(jobId, claim) {
+        const ts = this.now();
+        this.db.prepare(`UPDATE bridge_jobs
+       SET status='claimed', claimed_by_client=@client, claimed_origin=@origin, claimed_at=@ts, attempts=attempts+1, updated_at=@ts
+       WHERE id=@id`).run({ id: jobId, client: claim.clientId ?? null, origin: claim.origin, ts });
+    }
+    markResolved(jobId, result) {
+        this.db.prepare(`UPDATE bridge_jobs SET status='resolved', result_json=@result, updated_at=@ts WHERE id=@id`).run({ id: jobId, result: JSON.stringify(result), ts: this.now() });
+    }
+    markUnresolved(jobId, note) {
+        const result = note ? JSON.stringify({ ok: false, reason: note.reason }) : null;
+        this.db.prepare(`UPDATE bridge_jobs SET status='unresolved', result_json=@result, updated_at=@ts WHERE id=@id`).run({ id: jobId, result, ts: this.now() });
+    }
+    markVoid(jobId) {
+        this.db.prepare(`UPDATE bridge_jobs SET status='void', updated_at=@ts WHERE id=@id`).run({ id: jobId, ts: this.now() });
+    }
+    /**
+     * 孤儿回包落库(对账面):未知 jobId 的回包内容以 status='unresolved' 保留。
+     *  - 无行(纯未知/探测回包):插 kind 取回包自报(缺省 'orphan'),site='unknown';
+     *  - 已 resolved:迟到回包不覆盖已决结果(幂等,首次裁决为准);
+     *  - unresolved/void:补 result_json——作废/超时后扩展其实跑完了,留证供对账。
+     */
+    recordOrphanResult(jobId, result) {
+        const existing = this.getJob(jobId);
+        const ts = this.now();
+        const resultJson = JSON.stringify(result);
+        if (!existing) {
+            this.db.prepare(`INSERT INTO bridge_jobs (id, kind, site, payload_json, status, result_json, attempts, created_at, updated_at)
+         VALUES (@id, @kind, 'unknown', '{}', 'unresolved', @result, 0, @ts, @ts)`).run({ id: jobId, kind: result.kind ?? 'orphan', result: resultJson, ts });
+            return;
+        }
+        if (existing.status === 'resolved')
+            return;
+        this.db.prepare(`UPDATE bridge_jobs SET status='unresolved', result_json=@result, updated_at=@ts WHERE id=@id`).run({ id: jobId, result: resultJson, ts });
+    }
+    /** bridge_clients upsert:/jobs 轮询体(clientId + capabilities)到达即刷新,login_sites 保序合并 */
+    upsertClient(clientId, origin, capabilities) {
+        const ts = this.now();
+        this.db.prepare(`INSERT INTO bridge_clients (client_id, origin, capabilities_json, last_seen_at, login_sites_json)
+       VALUES (@clientId, @origin, @caps, @ts, '[]')
+       ON CONFLICT(client_id) DO UPDATE SET
+         origin=excluded.origin, capabilities_json=excluded.capabilities_json, last_seen_at=excluded.last_seen_at`).run({ clientId, origin, caps: JSON.stringify([...capabilities]), ts });
+    }
+    /** cookie-names 命中票据名(名字级)→ 该客户端在该站点持有登录态 */
+    recordClientLoginSite(clientId, site) {
+        const row = this.db.prepare(`SELECT login_sites_json FROM bridge_clients WHERE client_id=?`).get(clientId);
+        if (!row)
+            return;
+        let sites;
+        try {
+            sites = JSON.parse(row.login_sites_json);
+        }
+        catch {
+            sites = [];
+        }
+        const merged = new Set(Array.isArray(sites) ? sites.filter((s) => typeof s === 'string') : []);
+        merged.add(site);
+        this.db.prepare(`UPDATE bridge_clients SET login_sites_json=@sites WHERE client_id=@clientId`).run({ clientId, sites: JSON.stringify([...merged]) });
+    }
+    /** 站点导航类作业提交/领取:记命中时刻并把冷却推到 now+30s(不回退既有冷却) */
+    noteSiteHit(site) {
+        const ts = this.now();
+        this.db.prepare(`INSERT INTO bridge_pacing (site, last_hit_at, cooldown_until) VALUES (@site, @ts, @until)
+       ON CONFLICT(site) DO UPDATE SET last_hit_at=excluded.last_hit_at, cooldown_until=MAX(cooldown_until, excluded.cooldown_until)`).run({ site, ts, until: ts + BRIDGE_SITE_COOLDOWN_MS });
+    }
+    /** 超时结算冷却:claimed 超时的导航作业——站点可能已被打,只推冷却,不虚构 last_hit_at */
+    applyCooldown(site) {
+        const ts = this.now();
+        this.db.prepare(`INSERT INTO bridge_pacing (site, last_hit_at, cooldown_until) VALUES (@site, @ts, @until)
+       ON CONFLICT(site) DO UPDATE SET cooldown_until=MAX(cooldown_until, excluded.cooldown_until)`).run({ site, ts, until: ts + BRIDGE_SITE_COOLDOWN_MS });
+    }
+    pacingOf(site) {
+        const row = this.db.prepare(`SELECT last_hit_at, cooldown_until FROM bridge_pacing WHERE site=?`).get(site);
+        return row ? { lastHitAt: row.last_hit_at, cooldownUntil: row.cooldown_until } : null;
+    }
+    /**
+     * 事件上行落账(批次 B):seq 由 AUTOINCREMENT 分配,ts 取服务端落账时刻
+     * (clientTs 是扩展侧时钟,仅参与形状校验不入列——服务端时钟才是账本唯一时间轴)。
+     * 幂等:idem_key 非空且已存在 → 不重复落行,返回 false(由调用方计入 rejected);
+     * idem_key 为 NULL 的行不参与去重,多行共存(部分唯一索引)。
+     * 同进程同步 API,check-then-insert 对本连接原子。
+     */
+    insertEvent(ev) {
+        if (ev.idem_key !== null) {
+            const dup = this.db.prepare(`SELECT 1 FROM bridge_events WHERE idem_key=?`).get(ev.idem_key);
+            if (dup)
+                return false;
+        }
+        this.db.prepare(`INSERT INTO bridge_events (ts, client_id, kind, site, subject, payload_json, idem_key)
+       VALUES (@ts, @clientId, @kind, @site, @subject, @payload, @idem)`).run({ ts: this.now(), clientId: ev.client_id, kind: ev.kind, site: ev.site, subject: ev.subject, payload: ev.payload_json, idem: ev.idem_key });
+        return true;
+    }
+    /** 事件流水读面(测试/对账):按 seq 升序 */
+    listEvents() {
+        return this.db.prepare(`SELECT seq, ts, client_id, kind, site, subject, payload_json, idem_key FROM bridge_events ORDER BY seq`).all();
+    }
+    listPendingJobs() {
+        return this.db.prepare(`SELECT id, kind, site, payload_json, status, claimed_by_client, claimed_origin, timeout_at, attempts
+       FROM bridge_jobs WHERE status IN ('queued','claimed')`).all();
+    }
+    getJob(jobId) {
+        return this.db.prepare(`SELECT * FROM bridge_jobs WHERE id=?`).get(jobId) ?? null;
+    }
+    getClient(clientId) {
+        return this.db.prepare(`SELECT * FROM bridge_clients WHERE client_id=?`).get(clientId) ?? null;
+    }
+    listPacing() {
+        return this.db.prepare(`SELECT site, last_hit_at, cooldown_until FROM bridge_pacing ORDER BY site`).all();
+    }
+    close() {
+        this.db.close();
+    }
+}
+/** 打开(或创建)桥作业账本;stateRoot 目录自动落位 */
+export function openBridgeLedgerStore(stateRoot, opts = {}) {
+    return new BridgeLedgerStore(bridgeLedgerDbPath(stateRoot), opts);
+}