@sleep2agi/commhub-server 0.9.0-preview.70 → 0.9.0-preview.72

package/src/db-adapter.ts

@@ -2,13 +2,15 @@
  * Database Adapter — supports SQLite and PostgreSQL
  *
  * SQLite adapter: wraps bun:sqlite (sync)
- * PostgreSQL adapter: wraps pg Pool (async, bridged to sync interface via blocking)
+ * PostgreSQL adapter: one Bun.SQL connection in a worker thread, bridged to the
+ *   sync interface with Atomics.wait (pg-worker.ts)
  *
  * Key design: callers write SQLite-style SQL. PgAdapter auto-translates:
  *   - ?1, ?2  →  $1, $2
- *   - datetime('now')  →  NOW()
- *   - datetime('now', '+N seconds')  →  NOW() + INTERVAL 'N seconds'
- *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  SERIAL PRIMARY KEY
+ *   - datetime('now'[, offset])  →  to_char(... AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')
+ *     (timestamps stay TEXT on both backends, RFC-039 §4.1)
+ *   - BLOB  →  BYTEA
+ *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  BIGSERIAL PRIMARY KEY; INTEGER  →  BIGINT
  *   - ON CONFLICT(col) DO UPDATE SET  →  ON CONFLICT(col) DO UPDATE SET  (same syntax)
  */
 
@@ -39,14 +41,32 @@ export interface DbAdapter {
 
   /** Dialect identifier */
   readonly dialect: "sqlite" | "postgres";
+
+  /** True when transaction() is all-or-nothing on one connection. */
+  readonly atomicTransactions: boolean;
+
+  /**
+   * Why features that need atomic transactions (scheduler, runtime evidence,
+   * side-thread command outbox) must stay off on this adapter, or null when
+   * they may run. Gates refuse on anything but null, so an adapter that does
+   * not implement this also refuses.
+   */
+  readonly transactionalFeaturesRefusal: string | null;
 }
 
+/** RFC-039: opt-in for PostgreSQL features whose PG tests do not exist yet (S4). */
+export const PG_EXPERIMENTAL_ENV = "COMMHUB_PG_EXPERIMENTAL";
+
 // ════════════════════════════════════════════
 //  SQLite Adapter (bun:sqlite, sync)
 // ════════════════════════════════════════════
 
 export class SQLiteAdapter implements DbAdapter {
   readonly dialect = "sqlite" as const;
+  readonly atomicTransactions = true;
+  get transactionalFeaturesRefusal(): string | null {
+    return this.atomicTransactions ? null : "transactions on this adapter are not atomic";
+  }
   constructor(private readonly rawDb: Database) {}
 
   run(sql: string, params?: any[]): QueryResult {
@@ -78,6 +98,15 @@ export class SQLiteAdapter implements DbAdapter {
 //  PostgreSQL Adapter (pg Pool, sync bridge)
 // ════════════════════════════════════════════
 
+/**
+ * PostgreSQL expression for SQLite's `datetime(...)` text: UTC, `YYYY-MM-DD HH:MM:SS`.
+ * Timestamps stay TEXT on both backends (RFC-039 §4.1), so a column written by
+ * `datetime('now')` compares, sorts and serialises the same way on each.
+ */
+function pgUtcText(expr: string): string {
+  return `to_char((${expr}) AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')`;
+}
+
 /**
  * Translate SQLite-style SQL to PostgreSQL.
  * Called on every query — must be fast (simple regex, no parsing).
@@ -85,18 +114,20 @@ export class SQLiteAdapter implements DbAdapter {
 export function sqliteToPostgres(sql: string): string {
   let s = sql;
   // ── datetime translations (before ?N→$N to handle datetime('now', ?N)) ──
-  // datetime('now', ?N) → NOW() + $N::INTERVAL  (param contains "+3600 seconds")
+  // datetime('now', ?N) → UTC text of NOW() + $N  (param contains "+3600 seconds").
+  // The CAST gives PG a type for a parameter it could not otherwise infer.
   s = s.replace(/datetime\s*\(\s*'now'\s*,\s*\?(\d+)\s*\)/gi, (_, n) => {
-    return `NOW() + $${n}::INTERVAL`;
+    return pgUtcText(`NOW() + CAST($${n} AS TEXT)::INTERVAL`);
   });
-  // datetime('now', '+N seconds') → NOW() + INTERVAL 'N seconds'
+  // datetime('now', '+N seconds') → UTC text of NOW() + INTERVAL 'N seconds'
   s = s.replace(/datetime\s*\(\s*'now'\s*,\s*'([^']+)'\s*\)/gi, (_, offset) => {
-    return `NOW() + INTERVAL '${offset.replace(/^\+/, "")}'`;
+    return pgUtcText(`NOW() + INTERVAL '${offset.replace(/^\+/, "")}'`);
   });
-  // datetime('now') → NOW()
-  s = s.replace(/datetime\s*\(\s*'now'\s*\)/gi, "NOW()");
-  // TEXT NOT NULL DEFAULT (datetime('now')) → TIMESTAMP NOT NULL DEFAULT NOW()
-  s = s.replace(/TEXT\s+NOT\s+NULL\s+DEFAULT\s+\(NOW\(\)\)/gi, "TIMESTAMP NOT NULL DEFAULT NOW()");
+  // datetime('now') → UTC text of NOW()
+  s = s.replace(/datetime\s*\(\s*'now'\s*\)/gi, pgUtcText("NOW()"));
+  // strftime('%Y-%m-%d %H:%M:%f', 'now') → the same text with milliseconds
+  s = s.replace(/strftime\s*\(\s*'%Y-%m-%d %H:%M:%f'\s*,\s*'now'\s*\)/gi,
+    "to_char(NOW() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.MS')");
   // ── Parameter placeholders ──
   // ?1, ?2 → $1, $2  (positional params)
   s = s.replace(/\?(\d+)/g, (_, n) => `$${n}`);
@@ -104,78 +135,168 @@ export function sqliteToPostgres(sql: string): string {
   let idx = 0;
   s = s.replace(/\?(?!\d)/g, () => `$${++idx}`);
   // ── DDL translations ──
-  // INTEGER PRIMARY KEY AUTOINCREMENT → SERIAL PRIMARY KEY
-  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "SERIAL PRIMARY KEY");
+  // INTEGER PRIMARY KEY AUTOINCREMENT → BIGSERIAL PRIMARY KEY
+  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "BIGSERIAL PRIMARY KEY");
+  // INTEGER → BIGINT: SQLite integers are 64-bit, and the Hub stores epoch
+  // milliseconds in INTEGER columns (a 32-bit PG integer overflows).
+  s = s.replace(/\bINTEGER\b/gi, "BIGINT");
+  // BLOB → BYTEA
+  s = s.replace(/\bBLOB\b/gi, "BYTEA");
   return s;
 }
 
 /**
- * PostgreSQL adapter using a synchronous subprocess bridge.
+ * Split a multi-statement script on top-level `;`.
+ *
+ * A bare `split(";")` cut through SQL comments (db.ts has `;` inside `--`
+ * comments) and through plpgsql `$$ … $$` bodies, so the Hub died on its
+ * first schema block on PostgreSQL. This skips `--` and `/* *\/` comments
+ * (dropping them) and keeps quoted strings, quoted identifiers and
+ * dollar-quoted bodies intact.
+ */
+export function splitSqlStatements(sql: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const c = sql[i];
+    if (c === "-" && sql[i + 1] === "-") {
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && sql[i + 1] === "*") {
+      const close = sql.indexOf("*/", i + 2);
+      i = close < 0 ? n : close + 2;
+      cur += " ";
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      while (j < n) {
+        if (sql[j] === c) {
+          if (sql[j + 1] === c) { j += 2; continue; }
+          break;
+        }
+        j++;
+      }
+      cur += sql.slice(i, j + 1);
+      i = j + 1;
+      continue;
+    }
+    if (c === "$") {
+      const tag = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+      if (tag) {
+        const close = sql.indexOf(tag[0], i + tag[0].length);
+        const stop = close < 0 ? n : close + tag[0].length;
+        cur += sql.slice(i, stop);
+        i = stop;
+        continue;
+      }
+    }
+    if (c === ";") {
+      if (cur.trim()) out.push(cur.trim());
+      cur = "";
+      i++;
+      continue;
+    }
+    cur += c;
+    i++;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/**
+ * PostgreSQL adapter: synchronous facade over one long-lived worker thread
+ * (RFC-039 S2b).
+ *
+ * The worker (pg-worker.ts) holds a single reserved Bun.SQL connection. Each
+ * call posts one request and blocks on Atomics.wait until the worker answers,
+ * so the DbAdapter interface stays synchronous — the same contract bun:sqlite
+ * gives the rest of the Hub, including "nothing else runs while a transaction
+ * is open". Because every statement uses the same backend connection,
+ * BEGIN/COMMIT/ROLLBACK are real transactions.
  *
- * TODO(P0-4): this is not transaction-safe. querySync currently starts a
- * fresh `node -e` process for every statement, so BEGIN/COMMIT/ROLLBACK do
- * not share one backend connection. PostgreSQL support is demoted behind
- * SQLite for now; before advertising it as production-ready, replace this
- * bridge with a long-lived worker or make DbAdapter async and use pg directly.
+ * SQLite semantics kept on purpose:
+ *   - a failed statement inside a transaction does not poison the transaction
+ *     (each statement inside one runs under a savepoint);
+ *   - nested transaction() calls become savepoints;
+ *   - booleans bind as 1/0 and undefined as NULL.
  */
 export class PgAdapter implements DbAdapter {
   readonly dialect = "postgres" as const;
-  private connString: string;
+  readonly atomicTransactions = true;
+  /** Closed by default on PG even with real transactions: explicit opt-in only. */
+  get transactionalFeaturesRefusal(): string | null {
+    if (!this.atomicTransactions) return "transactions on this adapter are not atomic";
+    if (process.env[PG_EXPERIMENTAL_ENV] === "1") return null;
+    return `PostgreSQL support is experimental; set ${PG_EXPERIMENTAL_ENV}=1 to enable this feature on it (RFC-039)`;
+  }
+  private readonly port: MessagePort;
+  private readonly flag: Int32Array;
+  private readonly worker: import("node:worker_threads").Worker;
+  private readonly waitMs: number;
+  private txDepth = 0;
 
   constructor(connectionString: string) {
-    this.connString = connectionString;
-    // Validate pg is available
-    try { require("pg"); } catch (e) {
-      throw new Error(
-        "PostgreSQL support requires 'pg' package. Install with: bun add pg\n" +
-        `  Original error: ${(e as Error).message}`
-      );
-    }
+    const { Worker, MessageChannel } = require("node:worker_threads") as typeof import("node:worker_threads");
+    const statementTimeoutMs = Number(process.env.COMMHUB_PG_STATEMENT_TIMEOUT_MS || 30_000);
+    // The main thread waits a little longer than PG itself will run a statement.
+    this.waitMs = statementTimeoutMs > 0 ? statementTimeoutMs + 5_000 : 300_000;
+    const { port1, port2 } = new MessageChannel();
+    this.port = port1 as unknown as MessagePort;
+    this.flag = new Int32Array(new SharedArrayBuffer(4));
+    this.worker = new Worker(new URL("./pg-worker.ts", import.meta.url), {
+      workerData: { port: port2, flag: this.flag, url: connectionString, statementTimeoutMs },
+      transferList: [port2 as any],
+    });
+    this.worker.unref();
+    (port1 as any).unref?.();
     // Test connection on startup
-    const test = this.querySync("SELECT 1 as ok");
+    const test = this.request("SELECT 1 as ok");
     if (!test.rows?.[0]?.ok) throw new Error("PostgreSQL connection test failed");
     console.log("[commhub] PostgreSQL connection verified");
   }
 
-  private querySync(sql: string, params?: any[]): { rows: any[]; rowCount: number } {
-    const pgSql = sqliteToPostgres(sql);
-    // Single-query subprocess with pg Pool (connection string from env)
-    const script = `
-      const{Pool}=require('pg');
-      const p=new Pool({connectionString:${JSON.stringify(this.connString)},max:1});
-      const q=${JSON.stringify(pgSql)};
-      const v=${JSON.stringify(params || [])};
-      p.query(q,v).then(r=>{
-        process.stdout.write(JSON.stringify({rows:r.rows,rowCount:r.rowCount||0}));
-        p.end();
-      }).catch(e=>{
-        process.stderr.write(e.message);
-        p.end();
-        process.exit(1);
-      });
-    `;
-    const proc = Bun.spawnSync(["node", "--no-warnings", "-e", script], {
-      stdout: "pipe", stderr: "pipe",
-    });
-    if (proc.exitCode !== 0) {
-      throw new Error(`PG: ${proc.stderr.toString().trim() || "query failed"}`);
+  /** Send one already-translated statement to the worker and block for the answer. */
+  private request(pgSql: string, params?: any[]): { rows: any[]; count: number } {
+    const { receiveMessageOnPort } = require("node:worker_threads") as typeof import("node:worker_threads");
+    const bound = (params ?? []).map(v => v === undefined ? null : typeof v === "boolean" ? (v ? 1 : 0) : v);
+    Atomics.store(this.flag, 0, 0);
+    (this.port as any).postMessage({ sql: pgSql, params: bound, guard: this.txDepth > 0 });
+    if (Atomics.wait(this.flag, 0, 0, this.waitMs) === "timed-out") {
+      throw new Error(`PG: no answer from the database worker within ${this.waitMs}ms`);
     }
-    return JSON.parse(proc.stdout.toString().trim());
+    const reply = receiveMessageOnPort(this.port as any)?.message as any;
+    if (!reply) throw new Error("PG: database worker signalled without a reply");
+    if (!reply.ok) throw new Error(`PG: ${reply.error}`);
+    return reply;
+  }
+
+  private querySync(sql: string, params?: any[]): { rows: any[]; count: number } {
+    return this.request(sqliteToPostgres(sql), params);
   }
 
   run(sql: string, params?: any[]): QueryResult {
     if (sql.trim().toUpperCase().startsWith("PRAGMA")) return { changes: 0 };
     const result = this.querySync(sql, params);
-    return { changes: result.rowCount };
+    return { changes: result.count };
+  }
+
+  /** bun:sqlite also accepts get(sql, [a, b]); a lone array argument is the parameter list. */
+  private static bindArgs(params: any[]): any[] | undefined {
+    if (params.length === 1 && Array.isArray(params[0])) return params[0];
+    return params.length > 0 ? params : undefined;
   }
 
   get<T = any>(sql: string, ...params: any[]): T | null {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows?.[0] as T) ?? null;
   }
 
   all<T = any>(sql: string, ...params: any[]): T[] {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows as T[]) ?? [];
   }
 
@@ -183,9 +304,9 @@ export class PgAdapter implements DbAdapter {
     if (sql.trim().toUpperCase().startsWith("PRAGMA")) return;
     const pgSql = sqliteToPostgres(sql);
     // Split multi-statement DDL (CREATE TABLE; CREATE INDEX; ...)
-    const stmts = pgSql.split(";").map(s => s.trim()).filter(s => s.length > 0);
+    const stmts = splitSqlStatements(pgSql);
     for (const stmt of stmts) {
-      try { this.querySync(stmt); } catch (e: any) {
+      try { this.request(stmt); } catch (e: any) {
         // Ignore "already exists" errors for CREATE TABLE/INDEX IF NOT EXISTS
         if (!/already exists/.test(e.message)) throw e;
       }
@@ -193,19 +314,32 @@ export class PgAdapter implements DbAdapter {
   }
 
   transaction<T>(fn: () => T): T {
-    // Not atomic for PostgreSQL until P0-4 is implemented; see class TODO.
-    this.querySync("BEGIN");
+    const depth = this.txDepth;
+    const savepoint = `anet_tx_${depth}`;
+    // Control statements run unguarded: they are what the guard is made of.
+    this.txDepth = 0;
+    try { this.request(depth === 0 ? "BEGIN" : `SAVEPOINT ${savepoint}`); } finally { this.txDepth = depth; }
+    this.txDepth = depth + 1;
+    let result: T;
     try {
-      const result = fn();
-      this.querySync("COMMIT");
-      return result;
+      result = fn();
     } catch (e) {
-      try { this.querySync("ROLLBACK"); } catch {}
+      this.txDepth = 0;
+      try {
+        if (depth === 0) this.request("ROLLBACK");
+        else { this.request(`ROLLBACK TO SAVEPOINT ${savepoint}`); this.request(`RELEASE SAVEPOINT ${savepoint}`); }
+      } catch {}
+      this.txDepth = depth;
       throw e;
     }
+    this.txDepth = 0;
+    try { this.request(depth === 0 ? "COMMIT" : `RELEASE SAVEPOINT ${savepoint}`); } finally { this.txDepth = depth; }
+    return result;
   }
 
-  close(): void {}
+  close(): void {
+    this.worker.terminate();
+  }
 }
 
 // ════════════════════════════════════════════
@@ -251,7 +385,54 @@ export function assertSafeTestDatabaseEnv(env: NodeJS.ProcessEnv = process.env):
  * explicit COMMHUB_DB (or a reviewed PostgreSQL DATABASE_URL), so forgetting
  * one fails before mkdir/open/write instead of touching the live Hub.
  */
+/**
+ * RFC-039 §9 — the one reviewed way a `bun test` process may use PostgreSQL.
+ *
+ * The inherited-DATABASE_URL guard stays absolute. A test that means to run
+ * on PostgreSQL names a *different* variable, COMMHUB_TEST_PG_URL, which is
+ * honoured only under NODE_ENV=test and only for a literal loopback host and
+ * a database called `anet_…_test`, so it cannot reach a real Hub database by
+ * accident. Error messages never carry credentials.
+ */
+export const TEST_PG_URL_ENV = "COMMHUB_TEST_PG_URL";
+const TEST_PG_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const TEST_PG_DB_RE = /^anet_[a-z0-9_]*_test$/;
+const TEST_PG_QUERY_KEYS = new Set(["connect_timeout", "sslmode", "application_name"]);
+
+/** A PostgreSQL URL with user and password replaced, safe to print. */
+export function redactPgUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    if (u.username || u.password) { u.username = "***"; u.password = ""; }
+    return u.toString();
+  } catch {
+    return "<unparseable URL>";
+  }
+}
+
+export function validateTestPgUrl(raw: string): string {
+  const refuse = (why: string) => new Error(
+    `[commhub] REFUSING ${TEST_PG_URL_ENV}=${redactPgUrl(raw)}: ${why}.\n` +
+    "  It is test-only: postgres(ql)://<user>:<password>@127.0.0.1|localhost|[::1][:port]/anet_<name>_test",
+  );
+  let u: URL;
+  try { u = new URL(raw); } catch { throw refuse("not a URL"); }
+  if (u.protocol !== "postgres:" && u.protocol !== "postgresql:") throw refuse("scheme must be postgres:// or postgresql://");
+  if (!TEST_PG_HOSTS.has(u.hostname)) throw refuse("host must be literally 127.0.0.1, localhost or ::1");
+  const dbName = decodeURIComponent(u.pathname.replace(/^\//, ""));
+  if (!TEST_PG_DB_RE.test(dbName)) throw refuse("database name must match /^anet_[a-z0-9_]*_test$/");
+  for (const key of u.searchParams.keys()) {
+    if (!TEST_PG_QUERY_KEYS.has(key)) throw refuse(`query parameter "${key}" is not allowed`);
+  }
+  return raw;
+}
+
 function resolveDatabaseTargetAfterGuard(env: NodeJS.ProcessEnv): DbTarget {
+  const testPgUrl = env[TEST_PG_URL_ENV];
+  if (env.NODE_ENV === "test" && testPgUrl) {
+    return { kind: "postgres", url: validateTestPgUrl(testPgUrl) };
+  }
+
   const dbUrl = env.DATABASE_URL;
   if (dbUrl && (dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://"))) {
     return { kind: "postgres", url: dbUrl };

package/src/db.ts

@@ -983,7 +983,7 @@ try { db.exec("ALTER TABLE requirements ADD COLUMN client_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE requirements ADD COLUMN issues_json TEXT"); } catch {}
 try { db.exec("ALTER TABLE requirements ADD COLUMN tags_json TEXT NOT NULL DEFAULT '[]'"); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
 db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_client ON requirements(network_id, client_id) WHERE client_id IS NOT NULL AND client_id != ''");
-for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT", "external_ref TEXT", "external_url TEXT", "archived INTEGER NOT NULL DEFAULT 0", "created_by_json TEXT", "updated_by_json TEXT", "parent_id TEXT"]) {
+for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT", "external_ref TEXT", "external_url TEXT", "archived INTEGER NOT NULL DEFAULT 0", "created_by_json TEXT", "updated_by_json TEXT", "parent_id TEXT", "start_on TEXT"]) {
   try { db.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
 }
 
@@ -1068,6 +1068,43 @@ db.exec(`
   CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_grants_alias ON network_member_agent_grants(network_id, user_id, alias) WHERE alias IS NOT NULL;
 `);
 
+// ── Agent 分组(RFC-038 §8):管理员自由定义的组,授权可以给到组,组成员动态生效 ──
+// 组授权单独一张表(不给 network_member_agent_grants 加列):那张表的 CHECK 改不了,
+// 而且旧 app 的 PUT 是整体替换 —— 同表的话,旧 app 一保存就把组授权清掉。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS agent_groups (
+    group_id     TEXT PRIMARY KEY,
+    network_id   TEXT NOT NULL,
+    name         TEXT NOT NULL,
+    description  TEXT,
+    created_by   TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at   TEXT
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_groups_name ON agent_groups(network_id, name);
+
+  CREATE TABLE IF NOT EXISTS agent_group_members (
+    group_id   TEXT NOT NULL,
+    node_id    TEXT NOT NULL,
+    added_by   TEXT,
+    added_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (group_id, node_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS network_member_group_grants (
+    network_id   TEXT NOT NULL,
+    user_id      TEXT NOT NULL,
+    group_id     TEXT NOT NULL,
+    can_message  INTEGER NOT NULL DEFAULT 1,
+    created_by   TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (network_id, user_id, group_id)
+  );
+  -- 改组成员 / 删组时按组找被授权成员(usersGrantedGroup、granted_user_count):主键以 network_id 开头用不上。
+  -- 展开查询本身走各表主键,见 agent-groups-perf.test.ts 的 EXPLAIN QUERY PLAN。
+  CREATE INDEX IF NOT EXISTS idx_group_grants_group ON network_member_group_grants(group_id);
+`);
+
 // ── #84: node rename — rename_txn table (RFC-010 §4) ──
 // Single isolated table holding the rename 2PC transaction state. It doubles
 // as the alias_rename_log (RFC §4 risk #5): the audit log of completed renames
@@ -1475,7 +1512,7 @@ if (db.dialect === "sqlite") {
       IF NEW.status IN ('replied', 'failed', 'cancelled', 'expired')
          AND (TG_OP = 'INSERT' OR OLD.status NOT IN ('replied', 'failed', 'cancelled', 'expired')) THEN
         INSERT INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
-        VALUES (NEW.task_id, NEW.network_id, NEW.from_node_id, COALESCE(NEW.completed_at, NOW()))
+        VALUES (NEW.task_id, NEW.network_id, NEW.from_node_id, COALESCE(NEW.completed_at, datetime('now')))
         ON CONFLICT (task_id) DO NOTHING;
       END IF;
       RETURN NEW;
@@ -1970,7 +2007,7 @@ export function syncScheduledRunForTask(taskId: string, expectedNetworkId?: stri
     `SELECT task_id, network_id, status, completed_at
        FROM tasks
       WHERE task_id = ?1
-        AND (?2 IS NULL OR network_id = ?2)`,
+        AND (CAST(?2 AS TEXT) IS NULL OR network_id = ?2)`,
     taskId,
     expectedNetworkId ?? null,
   );
@@ -2036,3 +2073,9 @@ export function logTaskEvent(taskId: string, fromStatus: string | null, toStatus
     );
   } catch {}
 }
+
+// RFC-039 F3: queries break created_at ties with SQLite's implicit rowid
+// (insertion order). PostgreSQL has none, so give these tables a real one.
+if (db.dialect === "postgres") {
+  for (const table of ["nodes", "user_inbox"]) db.exec(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS rowid BIGSERIAL`);
+}

package/src/pg-worker.ts

@@ -0,0 +1,87 @@
+/**
+ * PostgreSQL worker for PgAdapter (RFC-039 S2b).
+ *
+ * Holds ONE reserved Bun.SQL connection for the life of the Hub, so BEGIN /
+ * statements / COMMIT all run on the same backend and transactions are real.
+ * The main thread posts one request at a time and blocks on `flag` with
+ * Atomics.wait; this worker answers on `port` and then notifies, which keeps
+ * DbAdapter synchronous exactly like bun:sqlite.
+ *
+ * Request:  { sql, params?, guard? }   guard=true wraps the statement in a
+ *           savepoint so a failed statement inside a transaction behaves like
+ *           SQLite (the statement fails, the transaction survives).
+ * Response: { ok: true, rows, count } | { ok: false, error, code }
+ */
+import { workerData } from "node:worker_threads";
+import { SQL } from "bun";
+
+type Request = { sql: string; params?: unknown[]; guard?: boolean };
+
+const { port, flag, url, statementTimeoutMs } = workerData as {
+  port: MessagePort;
+  flag: Int32Array;
+  url: string;
+  statementTimeoutMs: number;
+};
+
+// bigint:true makes int8 arrive as BigInt, so it can be told apart from a
+// TEXT column that happens to hold digits; normalise() turns it into a number.
+// libpq's `connect_timeout` (seconds) in the URL is honoured, default 10 s,
+// so an endpoint that accepts TCP but never speaks PostgreSQL fails the
+// startup check instead of hanging the Hub.
+const connectTimeout = Number(new URL(url).searchParams.get("connect_timeout") || 10);
+const sql = new SQL(url, { max: 1, bigint: true, connectionTimeout: connectTimeout > 0 ? connectTimeout : 10 });
+let conn: any = null;
+
+async function connection() {
+  if (!conn) {
+    conn = await sql.reserve();
+    await conn.unsafe("SET TIME ZONE 'UTC'");
+    await conn.unsafe(`SET statement_timeout = ${Math.max(0, Math.floor(statementTimeoutMs))}`);
+  }
+  return conn;
+}
+
+function normalise(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : value.toString();
+  }
+  return value;
+}
+
+async function handle(req: Request) {
+  const c = await connection();
+  if (req.guard) await c.unsafe("SAVEPOINT anet_stmt");
+  let result: any;
+  try {
+    result = await c.unsafe(req.sql, req.params ?? []);
+  } catch (e) {
+    if (req.guard) {
+      await c.unsafe("ROLLBACK TO SAVEPOINT anet_stmt");
+      await c.unsafe("RELEASE SAVEPOINT anet_stmt");
+    }
+    throw e;
+  }
+  if (req.guard) await c.unsafe("RELEASE SAVEPOINT anet_stmt");
+  const rows = [...result].map((row: Record<string, unknown>) => {
+    for (const k of Object.keys(row)) row[k] = normalise(row[k]);
+    return row;
+  });
+  return { ok: true, rows, count: typeof result.count === "number" ? result.count : rows.length };
+}
+
+port.on("message", async (req: Request) => {
+  let out: unknown;
+  try {
+    out = await handle(req);
+  } catch (e: any) {
+    // A dropped connection is not retried: a retry inside a transaction would
+    // replay half of it. Forget it so the next request reconnects.
+    if (String(e?.code ?? "").startsWith("ERR_POSTGRES_CONNECTION")) conn = null;
+    out = { ok: false, error: String(e?.message ?? e), code: e?.errno ?? e?.code ?? null };
+  }
+  port.postMessage(out);
+  Atomics.store(flag, 0, 1);
+  Atomics.notify(flag, 0);
+});