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

package/src/agent-groups-perf.test.ts

@@ -0,0 +1,190 @@
+// Agent 分组的性能守卫(RFC-038 §8):visibleAgents() 每个请求多做一次「组授权 → 组成员」展开,
+// 这里量它的额外开销,并用 EXPLAIN QUERY PLAN 钉住展开查询走索引(不是全表扫)。
+//
+// 场景:NET 里 300 个节点;50 个组,每组 6 个节点(合起来覆盖全部 300 个)。
+//   baseline —— bob 直接授权这 300 个节点(没有组);
+//   groups   —— alice 授权这 50 个组(没有直接授权),可见集合与 bob 完全相同。
+// 两人看到的 Agent 一样多,差值就是「按组展开」本身的代价(交替量 15 轮,取每轮差值的中位数)。团队要求 ≈2 ms 以内(本机实测 −0.5~+1.9 ms);
+// 断言放宽到 max(5 ms, 基线的 15%)—— CI 容器比本机慢时两边一起变慢,绝对差也跟着放大。数字打印出来。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+import { visibleAgents } from "./agent-access.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-groups-perf-"));
+let BASE = "";
+let hub: any = null;
+const PW = "GroupPerfPassw0rd!x";
+let NET = "";
+let adminToken = "";
+let adminId = "";
+let alice = { token: "", id: "" };
+let bob = { token: "", id: "" };
+const NODES = 300;
+const GROUPS = 50;
+const PER_GROUP = NODES / GROUPS;
+const BOUND_MS = 5;
+const bound = (base: number) => Math.max(BOUND_MS, base * 0.15);
+// CI 容器里一次 visibleAgents() 约 65 ms(本机约 28 ms):原来 40 次 × 两边再加预热,顶破了 bun 默认的 5 s 单测超时(#2131 CI 实测)。
+// 15 次取中位数足够稳;性能用例另给显式超时。
+const WARMUP = 3;
+const ITER = 15;
+const PERF_TIMEOUT_MS = 60_000;
+
+const json = (token: string) => ({ Authorization: `Bearer ${token}`, "Content-Type": "application/json" });
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: json(token), body: payload === undefined ? undefined : JSON.stringify(payload) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+const median = (xs: number[]) => { const s = [...xs].sort((a, b) => a - b); return s[Math.floor(s.length / 2)]; };
+/**
+ * 交替计时:每一轮先量 A 再量 B,取「B − A」的中位数(再附上两边各自的中位数给人看)。
+ * 不能 A 连量 N 次再 B 连量 N 次:test638 在同一台机器上并发跑两份 aggregate,负载随时间变,
+ * 两段分开量时差值被负载漂移主导(--cpus=1 实测差出 26–33 ms,真实差值 < 1 ms)。
+ */
+function pairedDelta(a: () => void, b: () => void, n: number): { a: number; b: number; delta: number } {
+  for (let i = 0; i < WARMUP; i++) { a(); b(); }
+  const as: number[] = [], bs: number[] = [], ds: number[] = [];
+  for (let i = 0; i < n; i++) {
+    let t = performance.now(); a(); const ta = performance.now() - t;
+    t = performance.now(); b(); const tb = performance.now() - t;
+    as.push(ta); bs.push(tb); ds.push(tb - ta);
+  }
+  return { a: median(as), b: median(bs), delta: median(ds) };
+}
+async function pairedDeltaAsync(a: () => Promise<void>, b: () => Promise<void>, n: number): Promise<{ a: number; b: number; delta: number }> {
+  for (let i = 0; i < WARMUP; i++) { await a(); await b(); }
+  const as: number[] = [], bs: number[] = [], ds: number[] = [];
+  for (let i = 0; i < n; i++) {
+    let t = performance.now(); await a(); const ta = performance.now() - t;
+    t = performance.now(); await b(); const tb = performance.now() - t;
+    as.push(ta); bs.push(tb); ds.push(tb - ta);
+  }
+  return { a: median(as), b: median(bs), delta: median(ds) };
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const admin = register(`perf_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminId = admin.user!.user_id;
+  NET = admin.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  db.transaction(() => {
+    for (let i = 0; i < NODES; i++) {
+      const node = `node_perf_${i}`;
+      const alias = `perf-agent-${i}`;
+      db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, updated_at) VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'))`, [node, alias, NET, adminId]);
+      db.run(`INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`, [`resume_${node}`, alias, node, NET]);
+    }
+  });
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+
+  const mk = async (username: string) => {
+    const r = await send(adminToken, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  alice = await mk(`perf_alice_${Date.now()}`);
+  bob = await mk(`perf_bob_${Date.now()}`);
+
+  const groupIds: string[] = [];
+  for (let g = 0; g < GROUPS; g++) {
+    const nodeIds = Array.from({ length: PER_GROUP }, (_, k) => `node_perf_${g * PER_GROUP + k}`);
+    const r = await send(adminToken, "POST", `/api/networks/${NET}/agent-groups`, { name: `perf-group-${g}`, node_ids: nodeIds });
+    expect(r.status).toBe(200);
+    groupIds.push(r.body.group.group_id);
+  }
+  expect((await send(adminToken, "PUT", `/api/networks/${NET}/members/${alice.id}/agent-grants`, { group_grants: groupIds })).status).toBe(200);
+  expect((await send(adminToken, "PUT", `/api/networks/${NET}/members/${bob.id}/agent-grants`, { grants: Array.from({ length: NODES }, (_, i) => `node_perf_${i}`) })).status).toBe(200);
+}, 60_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("Agent 分组:性能守卫(50 组 × 300 节点)", () => {
+  test("两人可见集合相同(比较才公平)", () => {
+    const a = visibleAgents(alice.id, NET);
+    const b = visibleAgents(bob.id, NET);
+    expect(a.nodeIds.length).toBe(NODES);
+    expect([...a.nodeIds].sort()).toEqual([...b.nodeIds].sort());
+  });
+
+  test(`visibleAgents():组展开的额外开销 ≤ max(${BOUND_MS} ms, 基线 15%)(目标 ≈2 ms)`, () => {
+    const r = pairedDelta(() => { visibleAgents(bob.id, NET); }, () => { visibleAgents(alice.id, NET); }, ITER);
+    console.log(`[perf] visibleAgents median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    expect(r.delta).toBeLessThanOrEqual(bound(r.a));
+  }, PERF_TIMEOUT_MS);
+
+  // #2133:visibleAgents() 以前每个授权节点查一次 alias(300 条 ≈ 28–43 ms)。这两条钉住它不再回到 N+1:
+  // 查询条数(直接授权 1 + 组授权 1 + alias 1)是主判据,不受机器负载影响;绝对上限只兜底 ——
+  // 本机实测 ≈2.6–3.7 ms(负载 ~5),15 ms 给 test638 那种 --cpus=1 双份并发留足余量,仍远低于 N+1 的 28 ms。
+  const ABS_MS = 15;
+  test(`visibleAgents() at 300 grants stays under ${ABS_MS} ms (direct and via groups)`, () => {
+    const t = pairedDelta(() => { visibleAgents(bob.id, NET); }, () => { visibleAgents(alice.id, NET); }, 40);
+    console.log(`[perf] visibleAgents absolute: direct-300=${t.a.toFixed(2)}ms groups-50x6=${t.b.toFixed(2)}ms bound=${ABS_MS}ms`);
+    expect(t.a).toBeLessThan(ABS_MS);
+    expect(t.b).toBeLessThan(ABS_MS);
+  });
+
+  test("visibleAgents() makes a fixed number of queries, not one per granted node (#2133)", () => {
+    for (const who of [bob, alice]) {
+      let queries = 0;
+      const all = db.all.bind(db), get = db.get.bind(db);
+      (db as any).all = (...a: any[]) => { queries++; return (all as any)(...a); };
+      (db as any).get = (...a: any[]) => { queries++; return (get as any)(...a); };
+      try { visibleAgents(who.id, NET); } finally { (db as any).all = all; (db as any).get = get; }
+      console.log(`[perf] visibleAgents queries (${who === bob ? "direct-300" : "groups-50x6"}): ${queries}`);
+      expect(queries).toBeLessThanOrEqual(3);
+    }
+  });
+
+  test(`受限成员 GET /api/status:组授权比等量直接授权多出 ≤ max(${BOUND_MS} ms, 基线 15%)`, async () => {
+    const hit = async (token: string) => {
+      const r = await fetch(`${BASE}/api/status?network_id=${NET}`, { headers: json(token) });
+      const body = await r.json() as any;
+      if ((body.sessions ?? []).length !== NODES) throw new Error(`expected ${NODES} sessions, got ${(body.sessions ?? []).length}`);
+    };
+    const r = await pairedDeltaAsync(() => hit(bob.token), () => hit(alice.token), ITER);
+    console.log(`[perf] GET /api/status median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    expect(r.delta).toBeLessThanOrEqual(bound(r.a));
+  }, PERF_TIMEOUT_MS);
+
+  test("EXPLAIN QUERY PLAN:组展开走索引,不全表扫描", () => {
+    const plan = db.all<{ detail: string }>(
+      `EXPLAIN QUERY PLAN
+       SELECT m.node_id, g.can_message
+         FROM network_member_group_grants g
+         JOIN agent_groups ag ON ag.group_id = g.group_id AND ag.network_id = g.network_id
+         JOIN agent_group_members m ON m.group_id = g.group_id
+         JOIN nodes n ON n.node_id = m.node_id AND n.network_id = g.network_id
+        WHERE g.network_id = ?1 AND g.user_id = ?2`,
+      NET, alice.id,
+    ).map((r) => r.detail);
+    console.log(`[perf] plan:\n  ${plan.join("\n  ")}`);
+    // 四张表都是 SEARCH(按主键 / 索引定位),没有一张是 SCAN。
+    expect(plan.length).toBeGreaterThanOrEqual(4);
+    expect(plan.filter((d) => /^SCAN\b/.test(d))).toEqual([]);
+    expect(plan.every((d) => /^SEARCH\b/.test(d) && /(PRIMARY KEY|INDEX)/.test(d))).toBe(true);
+  });
+
+  test("EXPLAIN QUERY PLAN:按组找被授权成员(改组成员时断流用)走 group_id 索引", () => {
+    const plan = db.all<{ detail: string }>(
+      "EXPLAIN QUERY PLAN SELECT user_id FROM network_member_group_grants WHERE group_id = ?1", "x",
+    ).map((r) => r.detail);
+    console.log(`[perf] plan (usersGrantedGroup): ${plan.join(" | ")}`);
+    expect(plan.some((d) => /SEARCH .*idx_group_grants_group/.test(d))).toBe(true);
+  });
+});

package/src/auth.ts

@@ -438,12 +438,15 @@ export function deleteNetwork(userId: string, networkId: string): { ok: boolean;
   // Check if any sessions/tasks still reference this network
   const sessions = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions WHERE network_id = ?1", networkId);
   if (sessions && sessions.cnt > 0) return { ok: false, error: `network has ${sessions.cnt} active session(s) — stop them first` };
-  db.run("DELETE FROM networks WHERE network_id = ?1 AND owner_id = ?2", [networkId, userId]);
-  // PR #519 codex catch: leaving membership rows behind made deleted
-  // networks count toward getUserNetworkIds — a stale row could flip a
-  // single-network user to "ambiguous" or auto-resolve writes INTO the
-  // deleted network. Remove memberships with the network.
-  db.run("DELETE FROM network_members WHERE network_id = ?1", [networkId]);
+  db.transaction(() => {
+    db.run("DELETE FROM networks WHERE network_id = ?1 AND owner_id = ?2", [networkId, userId]);
+    // PR #519 codex catch: leaving membership rows behind made deleted
+    // networks count toward getUserNetworkIds — a stale row could flip a
+    // single-network user to "ambiguous" or auto-resolve writes INTO the
+    // deleted network. Remove memberships with the network.
+    db.run("DELETE FROM network_members WHERE network_id = ?1", [networkId]);
+    deleteNetworkAgentGroups(networkId); // #2144
+  });
   return { ok: true };
 }
 
@@ -582,7 +585,8 @@ export function getNetworkMembers(networkId: string) {
   return db.all<any>(
     `SELECT nm.user_id, nm.role, nm.joined_at, nm.invited_by, u.username, u.display_name,
             CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.agent_access = 'all' THEN 'all' ELSE 'granted' END AS agent_access,
-            (SELECT COUNT(*) FROM network_member_agent_grants g WHERE g.network_id = nm.network_id AND g.user_id = nm.user_id) AS agent_grant_count
+            (SELECT COUNT(*) FROM network_member_agent_grants g WHERE g.network_id = nm.network_id AND g.user_id = nm.user_id) AS agent_grant_count,
+            (SELECT COUNT(*) FROM network_member_group_grants gg WHERE gg.network_id = nm.network_id AND gg.user_id = nm.user_id) AS agent_group_count
      FROM network_members nm JOIN users u ON nm.user_id = u.user_id
      WHERE nm.network_id = ?1 ORDER BY nm.joined_at`,
     networkId);
@@ -793,3 +797,90 @@ export function listUsersWithMemberships() {
   }
   return users.map((u) => ({ ...u, networks: byUser.get(u.user_id) ?? [] }));
 }
+
+// Hub 管理员删**别人的**网络(清理旧测试账号留下的个人网络)。只删空网络:
+// 下面每张表里有一行就拒(409),并把计数原样回给调用方。表是按 schema 里所有带
+// network_id 的表逐个分类的,不是凭记忆 —— 新加一张带 network_id 的表要在这里归一类。
+//   阻断:真实内容,或会在删后重新长出节点的在途请求。
+//   清理:只描述「这个网络」本身的元数据/历史,网络没了它们就悬空。
+//   保留:audit_log(删除记录本身要留下)。
+const NETWORK_CONTENT_CHECKS: Array<[label: string, sql: string]> = [
+  ["nodes", "SELECT COUNT(*) AS cnt FROM nodes WHERE network_id = ?1"],
+  ["sessions", "SELECT COUNT(*) AS cnt FROM sessions WHERE network_id = ?1"],
+  ["tasks", "SELECT COUNT(*) AS cnt FROM tasks WHERE network_id = ?1"],
+  ["inbox", "SELECT COUNT(*) AS cnt FROM inbox WHERE network_id = ?1"],
+  ["user_inbox", "SELECT COUNT(*) AS cnt FROM user_inbox WHERE network_id = ?1"],
+  ["requirements", "SELECT COUNT(*) AS cnt FROM requirements WHERE network_id = ?1"],
+  ["requirement_projects", "SELECT COUNT(*) AS cnt FROM requirement_projects WHERE network_id = ?1"],
+  ["scheduled_tasks", "SELECT COUNT(*) AS cnt FROM scheduled_tasks WHERE network_id = ?1"],
+  ["providers", "SELECT COUNT(*) AS cnt FROM providers WHERE network_id = ?1"],
+  ["network_secrets", "SELECT COUNT(*) AS cnt FROM network_secrets WHERE network_id = ?1"],
+  ["skillhub_skills", "SELECT COUNT(*) AS cnt FROM skillhub_skills WHERE network_id = ?1"],
+  ["side_chats", "SELECT COUNT(*) AS cnt FROM side_chats WHERE network_id = ?1"],
+  // #2144 —— 组是管理员手工建的配置,和 requirements 一样算内容:有组就拒,别替人删掉。
+  ["agent_groups", "SELECT COUNT(*) AS cnt FROM agent_groups WHERE network_id = ?1"],
+  ["pending_node_create_requests", "SELECT COUNT(*) AS cnt FROM node_create_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
+  ["pending_node_start_requests", "SELECT COUNT(*) AS cnt FROM node_start_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
+];
+const NETWORK_CLEANUP_TABLES = [
+  "network_members", "network_member_agent_grants", "network_invites", "api_tokens",
+  "node_create_requests", "node_start_requests", "node_stop_requests", "node_rules_requests",
+  "node_config_updates", "rename_txn", "probe_results", "agent_telemetry", "completions",
+  "task_events", "task_terminal_events", "scheduled_task_runs", "external_schedule_edits",
+];
+
+function tableExists(name: string): boolean {
+  return db.dialect === "postgres"
+    ? !!db.get("SELECT 1 AS x FROM information_schema.tables WHERE table_name = ?1", name)
+    : !!db.get("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?1", name);
+}
+
+export function countNetworkContents(networkId: string): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const [label, sql] of NETWORK_CONTENT_CHECKS) {
+    const table = sql.match(/FROM (\w+)/)![1];
+    // 按需建表的模块(requirements / side-thread)在没用过的库上可能还没有这张表 —— 那就是 0 行。
+    if (!tableExists(table)) continue;
+    const cnt = db.get<{ cnt: number }>(sql, networkId)?.cnt ?? 0;
+    if (cnt > 0) counts[label] = cnt;
+  }
+  return counts;
+}
+
+export type AdminDeleteNetworkResult =
+  | { ok: true; owner_id: string; network_name: string; cleaned: Record<string, number> }
+  | { ok: false; status: number; error: string; counts?: Record<string, number> };
+
+// extraCounts:库外的内容(上传文件的索引在磁盘上),由调用方数好传进来,和库内计数一起判。
+export function adminDeleteEmptyNetwork(networkId: string, extraCounts: Record<string, number> = {}): AdminDeleteNetworkResult {
+  if (networkId === "default") return { ok: false, status: 409, error: "the default network cannot be deleted" };
+  return db.transaction((): AdminDeleteNetworkResult => {
+    const net = db.get<{ owner_id: string; network_name: string }>("SELECT owner_id, network_name FROM networks WHERE network_id = ?1", networkId);
+    if (!net) return { ok: false, status: 404, error: "network not found" };
+    const counts = { ...countNetworkContents(networkId) };
+    for (const [k, v] of Object.entries(extraCounts)) if (v > 0) counts[k] = v;
+    if (Object.keys(counts).length > 0) {
+      const summary = Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(", ");
+      return { ok: false, status: 409, error: `network is not empty (${summary}); only empty networks can be deleted by a hub admin`, counts };
+    }
+    const cleaned: Record<string, number> = {};
+    for (const table of NETWORK_CLEANUP_TABLES) {
+      if (!tableExists(table)) continue;
+      const changes = db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [networkId]).changes;
+      if (changes > 0) cleaned[table] = changes;
+    }
+    for (const [table, changes] of Object.entries(deleteNetworkAgentGroups(networkId))) if (changes > 0) cleaned[table] = changes;
+    db.run("DELETE FROM networks WHERE network_id = ?1", [networkId]);
+    return { ok: true, owner_id: net.owner_id, network_name: net.network_name, cleaned };
+  });
+}
+
+// #2144 —— Agent 分组(#2131)的三张表跟着网络一起删。agent_group_members 没有 network_id 列,
+// 只能按该网络的 group_id 删,所以必须在删 agent_groups 之前删它。owner 删网络与管理员删空网络共用。
+export function deleteNetworkAgentGroups(networkId: string): Record<string, number> {
+  return {
+    network_member_group_grants: db.run("DELETE FROM network_member_group_grants WHERE network_id = ?1", [networkId]).changes,
+    agent_group_members: db.run("DELETE FROM agent_group_members WHERE group_id IN (SELECT group_id FROM agent_groups WHERE network_id = ?1)", [networkId]).changes,
+    agent_groups: db.run("DELETE FROM agent_groups WHERE network_id = ?1", [networkId]).changes,
+  };
+}

package/src/db-adapter-guard.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   assertSafeTestDatabaseEnv,
+  redactPgUrl,
   resolveDatabaseTarget,
 } from "./db-adapter";
 
@@ -83,3 +84,65 @@ describe("#435 inherited DATABASE_URL guard", () => {
     }
   });
 });
+
+describe("RFC-039 §9 COMMHUB_TEST_PG_URL (test-only PostgreSQL)", () => {
+  const TEST = { ...BASE_ENV, NODE_ENV: "test" };
+  const ok = (url: string) => expect(resolveDatabaseTarget({ ...TEST, COMMHUB_TEST_PG_URL: url })).toEqual({ kind: "postgres", url });
+  const refused = (url: string, why: RegExp) => {
+    let message = "";
+    try { resolveDatabaseTarget({ ...TEST, COMMHUB_TEST_PG_URL: url }); } catch (e: any) { message = String(e?.message ?? e); }
+    expect(message).toMatch(/REFUSING COMMHUB_TEST_PG_URL/);
+    expect(message).toMatch(why);
+    // Credentials never reach an error message.
+    expect(message).not.toContain("s3cret");
+    expect(message).not.toContain("tester");
+  };
+
+  test("loopback host + anet_*_test database is accepted under NODE_ENV=test", () => {
+    ok("postgres://tester:s3cret@127.0.0.1:5432/anet_sched_test");
+    ok("postgresql://tester:s3cret@localhost/anet_side_thread_test");
+    ok("postgres://tester:s3cret@[::1]:6543/anet_x_test?connect_timeout=2&sslmode=disable");
+  });
+
+  test("ignored outside NODE_ENV=test", () => {
+    expect(resolveDatabaseTarget({ ...BASE_ENV, NODE_ENV: "production", COMMHUB_DB: "/tmp/i.db", COMMHUB_TEST_PG_URL: "postgres://tester:s3cret@127.0.0.1/anet_x_test" }))
+      .toEqual({ kind: "sqlite", path: "/tmp/i.db" });
+  });
+
+  test("inherited DATABASE_URL still refuses even when COMMHUB_TEST_PG_URL is set", () => {
+    expect(() => resolveDatabaseTarget({
+      ...TEST,
+      DATABASE_URL: "postgres://user:pw@prod.example:5432/commhub",
+      COMMHUB_TEST_PG_URL: "postgres://tester:s3cret@127.0.0.1/anet_x_test",
+    })).toThrow(/REFUSING to honor inherited DATABASE_URL/);
+  });
+
+  test("refuses a value that is not a URL or not postgres", () => {
+    refused("not a url", /not a URL/);
+    refused("mysql://tester:s3cret@127.0.0.1/anet_x_test", /scheme/);
+  });
+
+  test("refuses every host that is not literally loopback", () => {
+    for (const host of ["10.0.0.5", "db.internal", "localhost.evil.example", "127.0.0.2", "127.0.0.1,evil.example", "LOCALHOST", "%2Ftmp"]) {
+      refused(`postgres://tester:s3cret@${host}/anet_x_test`, /host must be/);
+    }
+  });
+
+  test("refuses database names outside /^anet_[a-z0-9_]*_test$/", () => {
+    for (const name of ["commhub", "anet_x", "anet_x_test2", "ANET_X_TEST", "anet-x_test", "anet_x_test/extra", ""]) {
+      refused(`postgres://tester:s3cret@127.0.0.1/${name}`, /database name/);
+    }
+  });
+
+  test("refuses connection-steering query parameters", () => {
+    refused("postgres://tester:s3cret@127.0.0.1/anet_x_test?host=db.internal", /"host" is not allowed/);
+    refused("postgres://tester:s3cret@127.0.0.1/anet_x_test?options=-csearch_path%3Dprod", /"options" is not allowed/);
+  });
+
+  test("redactPgUrl drops user and password", () => {
+    const out = redactPgUrl("postgres://tester:s3cret@127.0.0.1:5432/anet_x_test");
+    expect(out).not.toContain("tester");
+    expect(out).not.toContain("s3cret");
+    expect(out).toContain("127.0.0.1:5432/anet_x_test");
+  });
+});

package/src/db-adapter-translate.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { PG_EXPERIMENTAL_ENV, PgAdapter, SQLiteAdapter, splitSqlStatements, sqliteToPostgres } from "./db-adapter";
+
+const UTC_NOW = "to_char((NOW()) AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')";
+
+describe("RFC-039 S2a sqliteToPostgres", () => {
+  test("datetime('now') stays SQLite-format UTC text", () => {
+    expect(sqliteToPostgres("SELECT datetime('now')")).toBe(`SELECT ${UTC_NOW}`);
+  });
+
+  test("DEFAULT (datetime('now')) keeps the column TEXT", () => {
+    const out = sqliteToPostgres("created_at TEXT NOT NULL DEFAULT (datetime('now'))");
+    expect(out).toBe(`created_at TEXT NOT NULL DEFAULT (${UTC_NOW})`);
+    expect(out).not.toContain("TIMESTAMP");
+  });
+
+  test("strftime with milliseconds keeps SQLite's %f shape", () => {
+    expect(sqliteToPostgres("VALUES (strftime('%Y-%m-%d %H:%M:%f', 'now'))")).toBe(
+      "VALUES (to_char(NOW() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.MS'))",
+    );
+  });
+
+  test("literal offset", () => {
+    expect(sqliteToPostgres("x < datetime('now', '+14 days')")).toBe(
+      "x < to_char((NOW() + INTERVAL '14 days') AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')",
+    );
+  });
+
+  test("parameter offset is cast so PG can infer its type", () => {
+    expect(sqliteToPostgres("x < datetime('now', ?2)")).toBe(
+      "x < to_char((NOW() + CAST($2 AS TEXT)::INTERVAL) AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')",
+    );
+  });
+
+  test("INTEGER → BIGINT (epoch-ms columns), identifiers containing integer untouched", () => {
+    expect(sqliteToPostgres("created_at INTEGER NOT NULL, integer_ref TEXT")).toBe("created_at BIGINT NOT NULL, integer_ref TEXT");
+    expect(sqliteToPostgres("CAST(x AS INTEGER)")).toBe("CAST(x AS BIGINT)");
+  });
+
+  test("BLOB → BYTEA, identifiers containing blob untouched", () => {
+    expect(sqliteToPostgres("iv BLOB NOT NULL, blob_ref TEXT")).toBe("iv BYTEA NOT NULL, blob_ref TEXT");
+  });
+
+  test("placeholders and AUTOINCREMENT unchanged in behaviour", () => {
+    expect(sqliteToPostgres("SELECT * FROM t WHERE a = ?1 AND b = ?2")).toBe("SELECT * FROM t WHERE a = $1 AND b = $2");
+    expect(sqliteToPostgres("a = ? AND b = ?")).toBe("a = $1 AND b = $2");
+    expect(sqliteToPostgres("id INTEGER PRIMARY KEY AUTOINCREMENT")).toBe("id BIGSERIAL PRIMARY KEY");
+  });
+});
+
+describe("RFC-039 S2a splitSqlStatements", () => {
+  test("a `;` inside a -- comment does not split (db.ts first schema block)", () => {
+    expect(splitSqlStatements("CREATE TABLE a (x TEXT);\n-- note; more words\nCREATE TABLE b (y TEXT);")).toEqual([
+      "CREATE TABLE a (x TEXT)",
+      "CREATE TABLE b (y TEXT)",
+    ]);
+  });
+
+  test("block comments are dropped", () => {
+    expect(splitSqlStatements("SELECT 1 /* a; b */ ; SELECT 2")).toEqual(["SELECT 1", "SELECT 2"]);
+  });
+
+  test("quoted strings and identifiers keep their `;` and doubled quotes", () => {
+    expect(splitSqlStatements(`INSERT INTO t VALUES ('a;b', 'it''s;'); SELECT "c;d" FROM t`)).toEqual([
+      `INSERT INTO t VALUES ('a;b', 'it''s;')`,
+      `SELECT "c;d" FROM t`,
+    ]);
+  });
+
+  test("a plpgsql $$ body stays one statement", () => {
+    const fn = "CREATE FUNCTION f() RETURNS trigger AS $$\nBEGIN\n  INSERT INTO t VALUES (1);\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql";
+    expect(splitSqlStatements(`${fn};\nDROP TRIGGER IF EXISTS x ON t;`)).toEqual([fn, "DROP TRIGGER IF EXISTS x ON t"]);
+  });
+
+  test("tagged dollar quotes; $1 placeholders are not dollar quotes", () => {
+    expect(splitSqlStatements("SELECT $body$a;b$body$; UPDATE t SET a = $1 WHERE b = $2")).toEqual([
+      "SELECT $body$a;b$body$",
+      "UPDATE t SET a = $1 WHERE b = $2",
+    ]);
+  });
+
+  test("empty statements are dropped", () => {
+    expect(splitSqlStatements(" ; ;\n SELECT 1 ;; ")).toEqual(["SELECT 1"]);
+  });
+});
+
+describe("RFC-039 transactional feature gates", () => {
+  // A PgAdapter without its constructor: no worker, no connection.
+  function pgWith(atomic: boolean) {
+    const pg = Object.create(PgAdapter.prototype);
+    Object.defineProperty(pg, "atomicTransactions", { value: atomic });
+    return pg as PgAdapter;
+  }
+  function withFlag<T>(value: string | undefined, fn: () => T): T {
+    const saved = process.env[PG_EXPERIMENTAL_ENV];
+    if (value === undefined) delete process.env[PG_EXPERIMENTAL_ENV];
+    else process.env[PG_EXPERIMENTAL_ENV] = value;
+    try { return fn(); } finally {
+      if (saved === undefined) delete process.env[PG_EXPERIMENTAL_ENV];
+      else process.env[PG_EXPERIMENTAL_ENV] = saved;
+    }
+  }
+
+  test("SQLite: open, flag irrelevant", () => {
+    const sqlite = new SQLiteAdapter(new Database(":memory:"));
+    expect(withFlag(undefined, () => sqlite.transactionalFeaturesRefusal)).toBeNull();
+    expect(withFlag("1", () => sqlite.transactionalFeaturesRefusal)).toBeNull();
+    sqlite.close();
+  });
+
+  test("PostgreSQL with real transactions: closed by default, message names the variable", () => {
+    const refusal = withFlag(undefined, () => pgWith(true).transactionalFeaturesRefusal);
+    expect(refusal).toContain(`${PG_EXPERIMENTAL_ENV}=1`);
+    expect(refusal).toContain("experimental");
+    expect(withFlag("true", () => pgWith(true).transactionalFeaturesRefusal)).not.toBeNull();
+  });
+
+  test("PostgreSQL: opens only with atomic transactions AND the opt-in", () => {
+    expect(withFlag("1", () => pgWith(true).transactionalFeaturesRefusal)).toBeNull();
+    expect(withFlag("1", () => pgWith(false).transactionalFeaturesRefusal)).toContain("not atomic");
+  });
+});