@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/member-presence-http.test.ts

@@ -0,0 +1,210 @@
+// 人员列表的在线状态 —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// GET /api/networks/:id/humans 给每个人加 online / last_seen_at(判据 = 此刻有没有活着的用户流
+// /events/users/me);用户流上推 member_presence。两个方向都测:
+//   看得到:普通成员、受限成员、viewer;连上 → online=true,断开 → online=false + last_seen_at。
+//   看不到:非成员 403;节点令牌只拿身份字段(含头像),无在线状态;别的网络的人收不到推送;自己收不到自己的。
+
+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, hashToken, generateNetworkToken, generateId } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-member-presence-"));
+let BASE = "";
+let hub: any = null;
+
+const PW = "PresenceTestPassw0rd!x";
+let ownerToken = "";
+let NET = "";
+const users: Record<string, { token: string; userId: string }> = {};
+let nodeToken = "";
+
+const auth = (token: string) => ({ Authorization: `Bearer ${token}` });
+
+async function get(token: string, path: string): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token) });
+  const text = await res.text();
+  let body: any = text;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+async function post(token: string, path: string, payload: unknown): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${BASE}${path}`, { method: "POST", headers: { ...auth(token), "Content-Type": "application/json" }, body: JSON.stringify(payload) });
+  const text = await res.text();
+  let body: any = text;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+async function login(username: string): Promise<{ token: string; userId: string }> {
+  const r = await post("", "/api/auth/login", { username, password: PW });
+  expect(r.status).toBe(200);
+  return { token: r.body.token, userId: r.body.user.user_id };
+}
+
+/** 一条用户流:收集 data: 帧,close() 模拟 app 退出。 */
+async function openUserStream(token: string, networkId: string) {
+  const ctrl = new AbortController();
+  const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(networkId)}`, { headers: auth(token), signal: ctrl.signal });
+  expect(res.status).toBe(200);
+  const events: any[] = [];
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  void (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value);
+        let i: number;
+        while ((i = buf.indexOf("\n\n")) >= 0) {
+          const frame = buf.slice(0, i);
+          buf = buf.slice(i + 2);
+          for (const line of frame.split("\n")) if (line.startsWith("data: ")) events.push(JSON.parse(line.slice(6)));
+        }
+      }
+    } catch { /* aborted */ }
+  })();
+  await waitFor(() => events.some((e) => e.type === "connected"));
+  return { events, close: () => ctrl.abort(), presence: () => events.filter((e) => e.type === "member_presence") };
+}
+
+async function waitFor(cond: () => boolean | Promise<boolean>, ms = 3000): Promise<void> {
+  const until = Date.now() + ms;
+  while (Date.now() < until) {
+    if (await cond()) return;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  throw new Error("waitFor timed out");
+}
+
+const humanOf = async (token: string, userId: string) =>
+  (await get(token, `/api/networks/${NET}/humans`)).body.humans.find((h: any) => h.user_id === userId);
+
+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 owner = register(`pres_owner_${Date.now()}`, PW, undefined, "Owner");
+  expect(owner.ok).toBe(true);
+  ownerToken = owner.token!;
+  NET = owner.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [owner.user!.user_id]);
+  users.owner = { token: ownerToken, userId: owner.user!.user_id };
+
+  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}`;
+
+  // 受限成员(默认 agent_access=granted)、viewer、普通成员;外人自己一个网络。
+  for (const [name, role] of [["pres_alpha", "member"], ["pres_beta", "member"], ["pres_gamma", "viewer"]] as const) {
+    const r = await post(ownerToken, "/api/admin/users", { username: name, password: PW, network_id: NET, role });
+    expect(r.status).toBe(200);
+    users[name] = await login(name);
+  }
+  const outsider = register(`pres_out_${Date.now()}`, PW);
+  expect(outsider.ok).toBe(true);
+  users.outsider = { token: outsider.token!, userId: outsider.user!.user_id };
+  users.outsider_net = { token: outsider.token!, userId: outsider.network_id! };
+
+  nodeToken = generateNetworkToken();
+  db.run("INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, 'pres-node', 'network')",
+    [generateId("tok"), hashToken(nodeToken), users.owner.userId, NET]);
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/networks/:id/humans — online / last_seen_at", () => {
+  test("never connected since hub start → online=false, last_seen_at=null (unknown, not 'long ago')", async () => {
+    const r = await get(users.pres_alpha.token, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(200);
+    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["avatar_url", "display_name", "last_seen_at", "online", "user_id", "username"]);
+    expect(r.body.humans.every((h: any) => h.avatar_url === null)).toBe(true);
+    const beta = r.body.humans.find((h: any) => h.user_id === users.pres_beta.userId);
+    expect(beta.online).toBe(false);
+    expect(beta.last_seen_at).toBeNull();
+  });
+
+  test("user stream open → online for member, restricted member and viewer; closed → offline with last_seen_at", async () => {
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const before = Date.now();
+    const beta = await openUserStream(users.pres_beta.token, NET);
+
+    for (const viewer of ["pres_alpha", "pres_gamma", "owner"]) {
+      const h = await humanOf(users[viewer].token, users.pres_beta.userId);
+      expect(h.online).toBe(true);
+      expect(Date.parse(h.last_seen_at)).toBeGreaterThanOrEqual(before - 1000);
+    }
+    // 推送:alpha 收到 beta 上线;beta 收不到自己的。
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online === true));
+    const up = watcher.presence().find((e) => e.member_user_id === users.pres_beta.userId)!;
+    expect(up.network_id).toBe(NET);
+    expect(up.user_id).toBe(users.pres_alpha.userId); // 收件人
+    expect(beta.presence().filter((e) => e.member_user_id === users.pres_beta.userId)).toEqual([]);
+
+    beta.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+    const off = await humanOf(users.pres_gamma.token, users.pres_beta.userId);
+    expect(off.online).toBe(false);
+    expect(Date.parse(off.last_seen_at)).toBeGreaterThanOrEqual(before - 1000);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online === false));
+    const down = watcher.presence().find((e) => e.member_user_id === users.pres_beta.userId && e.online === false)!;
+    expect(typeof down.last_seen_at).toBe("string");
+    watcher.close();
+  });
+
+  test("two streams for one user: closing one keeps them online, no offline event", async () => {
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const a = await openUserStream(users.pres_beta.token, NET);
+    const b = await openUserStream(users.pres_beta.token, NET);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online));
+    a.close();
+    await new Promise((r) => setTimeout(r, 200));
+    expect((await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online).toBe(true);
+    expect(watcher.presence().filter((e) => e.member_user_id === users.pres_beta.userId && !e.online)).toEqual([]);
+    b.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+    watcher.close();
+  });
+});
+
+describe("who must NOT see presence", () => {
+  test("non-member → 403, no humans at all", async () => {
+    const r = await get(users.outsider.token, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(403);
+    expect(r.body.humans).toBeUndefined();
+  });
+
+  test("node token → identity fields including avatar, no online / last_seen_at", async () => {
+    const beta = await openUserStream(users.pres_beta.token, NET);
+    const r = await get(nodeToken, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(200);
+    for (const h of r.body.humans) {
+      expect(Object.keys(h).sort()).toEqual(["avatar_url", "display_name", "user_id", "username"]);
+      expect(h.avatar_url).toBeNull();
+    }
+    // 节点令牌也不能订阅用户流(既有行为,这里钉住:不能借它收 member_presence)。
+    expect((await fetch(`${BASE}/events/users/me?network_id=${NET}`, { headers: auth(nodeToken) })).status).toBe(403);
+    beta.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+  });
+
+  test("a user connected in another network gets no member_presence about this network's people", async () => {
+    const outsiderStream = await openUserStream(users.outsider.token, users.outsider_net.userId);
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const beta = await openUserStream(users.pres_beta.token, NET);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online));
+    beta.close();
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && !e.online));
+    expect(outsiderStream.presence()).toEqual([]);
+    watcher.close();
+    outsiderStream.close();
+  });
+});

package/src/messages-ack-by-agent-http.test.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, test } 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";
+
+// #1909 —— POST /api/messages/ack 的 `{ agent }` 形态:把调用者收到的、来自该 agent 的
+// 两张表(user_inbox + inbox reply/task/message)全部标已读。角标分母 unread_by_agent
+// 数的是全集,按 id 只能 ack 拉到的那一页 ⇒ 老行永远清不掉,这一形态补上。
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-ack-by-agent-http-"));
+let server: any;
+let base = "";
+let tokenA = "";
+let tokenB = "";
+let userA = "";
+let userB = "";
+let userIdA = "";
+let userIdB = "";
+let netA = "";
+let netB = "";
+
+const AGENT = "ack-agent-x";
+const OTHER = "ack-agent-y";
+
+function seed() {
+  const ui = (id: string, net: string, uid: string, from: string) =>
+    db.run(
+      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, content) VALUES (?1, ?2, ?3, ?4, 'agent_message', 'x')`,
+      [id, net, uid, from],
+    );
+  const ib = (id: string, net: string, to: string, from: string, type: string) =>
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, content, from_session, network_id) VALUES (?1, ?2, ?3, 'x', ?4, ?5)`,
+      [id, to, type, from, net],
+    );
+  ui("ui_a_x_1", netA, userIdA, AGENT);
+  ui("ui_a_x_2", netA, userIdA, AGENT);
+  ui("ui_a_y_1", netA, userIdA, OTHER);
+  ui("ui_b_x_1", netB, userIdB, AGENT);
+  ib("ib_a_x_reply", netA, userA, AGENT, "reply");
+  ib("ib_a_x_task", netA, userA, AGENT, "task");
+  ib("ib_a_x_status", netA, userA, AGENT, "status"); // 不在 reply/task/message 内,不该被 ack
+  ib("ib_a_y_reply", netA, userA, OTHER, "reply");
+  ib("ib_b_x_reply", netB, userB, AGENT, "reply");
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  const stamp = `${Date.now()}_${process.pid}`;
+  userA = `ack_agent_a_${stamp}`;
+  userB = `ack_agent_b_${stamp}`;
+  const a = register(userA, "AckAgent123!", undefined, "seed");
+  const b = register(userB, "AckAgent123!", undefined, "seed");
+  expect(a.ok).toBe(true);
+  expect(b.ok).toBe(true);
+  tokenA = a.token!; netA = a.network_id!;
+  tokenB = b.token!; netB = b.network_id!;
+  userIdA = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [userA])!.user_id;
+  userIdB = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [userB])!.user_id;
+  seed();
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+async function ack(token: string, body: unknown): Promise<{ status: number; body: any }> {
+  const response = await fetch(`${base}/api/messages/ack`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+const uiAcked = (id: string) => db.get<{ acked: number }>("SELECT acked FROM user_inbox WHERE message_id = ?1", [id])!.acked;
+const ibAcked = (id: string) => db.get<{ acked: number }>("SELECT acked FROM inbox WHERE id = ?1", [id])!.acked;
+
+async function unreadByAgent(token: string): Promise<Record<string, number>> {
+  const response = await fetch(`${base}/api/messages?scope=user&limit=5`, { headers: { Authorization: `Bearer ${token}` } });
+  expect(response.status).toBe(200);
+  return ((await response.json()) as any).unread_by_agent ?? {};
+}
+
+describe("POST /api/messages/ack { agent } (#1909)", () => {
+  test("missing everything → message_id_required; agent + ids → ambiguous_ack", async () => {
+    const none = await ack(tokenA, {});
+    expect(none.status).toBe(400);
+    expect(none.body.error).toBe("message_id_required");
+    const both = await ack(tokenA, { agent: AGENT, message_ids: ["ui_a_x_1"] });
+    expect(both.status).toBe(400);
+    expect(both.body.error).toBe("ambiguous_ack");
+    // 拒绝的那次不能有副作用
+    expect(uiAcked("ui_a_x_1")).toBe(0);
+  });
+
+  test("unread_by_agent counts the seeded rows before ack", async () => {
+    const by = await unreadByAgent(tokenA);
+    expect(by[AGENT]).toBe(4); // 2 user_inbox + reply + task (status 不计)
+    expect(by[OTHER]).toBe(2);
+  });
+
+  test("agent form acks both tables, only that agent, only the caller", async () => {
+    const r = await ack(tokenA, { agent: `  ${AGENT}  ` });
+    expect(r.status).toBe(200);
+    expect(r.body).toMatchObject({ ok: true, scope: "agent", agent: AGENT, acked: 4, acked_user_inbox: 2, acked_inbox: 2 });
+    expect(uiAcked("ui_a_x_1")).toBe(1);
+    expect(uiAcked("ui_a_x_2")).toBe(1);
+    expect(ibAcked("ib_a_x_reply")).toBe(1);
+    expect(ibAcked("ib_a_x_task")).toBe(1);
+    // 不该动的:别的 agent、非 reply/task/message 类型、别的用户
+    expect(uiAcked("ui_a_y_1")).toBe(0);
+    expect(ibAcked("ib_a_x_status")).toBe(0);
+    expect(ibAcked("ib_a_y_reply")).toBe(0);
+    expect(uiAcked("ui_b_x_1")).toBe(0);
+    expect(ibAcked("ib_b_x_reply")).toBe(0);
+    const by = await unreadByAgent(tokenA);
+    expect(by[AGENT] ?? 0).toBe(0);
+    expect(by[OTHER]).toBe(2);
+    expect((await unreadByAgent(tokenB))[AGENT]).toBe(2);
+  });
+
+  test("agent form is idempotent: second call changes 0 rows", async () => {
+    const r = await ack(tokenA, { agent: AGENT });
+    expect(r.status).toBe(200);
+    expect(r.body.acked).toBe(0);
+  });
+
+  test("id form still works and now reports scope ids", async () => {
+    const r = await ack(tokenA, { message_ids: ["ui_a_y_1", "ib_a_y_reply", "ui_b_x_1"] });
+    expect(r.status).toBe(200);
+    expect(r.body).toMatchObject({ ok: true, scope: "ids", acked: 2, acked_user_inbox: 1, acked_inbox: 1 });
+    expect(uiAcked("ui_a_y_1")).toBe(1);
+    expect(ibAcked("ib_a_y_reply")).toBe(1);
+    expect(uiAcked("ui_b_x_1")).toBe(0); // 别人的 id 匹配不到
+  });
+});

package/src/migrate-sqlite-to-pg.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MigrateRefused, migrateSqliteToPg } from "./migrate-sqlite-to-pg";
+
+// Only the refusals that happen before any connection is attempted; the full
+// copy runs against a real PostgreSQL in test2123 (migrate-stage.sh).
+const home = mkdtempSync(join(tmpdir(), "anet-migrate-home-"));
+const commhub = join(home, ".commhub");
+mkdirSync(commhub);
+writeFileSync(join(commhub, "commhub.db"), "");
+const elsewhere = join(home, "copies");
+mkdirSync(elsewhere);
+symlinkSync(join(commhub, "commhub.db"), join(elsewhere, "link.db"));
+const PG = "postgres://user:s3cret@127.0.0.1:1/anet_never_test";
+
+afterAll(() => rmSync(home, { recursive: true, force: true }));
+
+async function refusal(opts: Parameters<typeof migrateSqliteToPg>[0]): Promise<string> {
+  try {
+    await migrateSqliteToPg({ ...opts, home, log: () => {} });
+  } catch (e) {
+    expect(e).toBeInstanceOf(MigrateRefused);
+    return String((e as Error).message);
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("RFC-039 S5 migrate-to-pg refusals", () => {
+  test("target must be a postgres URL", async () => {
+    expect(await refusal({ from: join(elsewhere, "x.db"), to: "mysql://h/db" })).toContain("--to must be a postgres");
+  });
+
+  test("missing source", async () => {
+    expect(await refusal({ from: join(elsewhere, "missing.db"), to: PG })).toContain("does not exist");
+  });
+
+  test("the live Hub directory ~/.commhub is refused, also through a symlink", async () => {
+    for (const from of [join(commhub, "commhub.db"), join(elsewhere, "link.db")]) {
+      const message = await refusal({ from, to: PG });
+      expect(message).toContain("live Hub's directory");
+      expect(message).toContain("--i-know-this-is-a-copy");
+      expect(message).not.toContain("s3cret");
+    }
+  });
+});

package/src/migrate-sqlite-to-pg.ts

@@ -0,0 +1,263 @@
+/**
+ * RFC-039 S5 — offline copy of a Hub's SQLite database into an EMPTY
+ * PostgreSQL database.
+ *
+ *   commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>
+ *                                [--dry-run] [--i-know-this-is-a-copy]
+ *
+ * Contract:
+ *   - offline: no running process may have the source (or its -wal/-shm)
+ *     open (checked through /proc on Linux). A stopped Hub normally leaves a
+ *     -wal behind — that is expected, and its contents are included: the
+ *     source is opened read-only and read through a `VACUUM INTO` snapshot in
+ *     a private temp dir.
+ *   - never the live Hub's database: a source whose real path is under
+ *     ~/.commhub is refused unless --i-know-this-is-a-copy is given.
+ *   - empty target only: the target's `public` schema must hold no tables,
+ *     views, sequences or functions. The schema is then built by the Hub's
+ *     own module graph (no second copy of the DDL).
+ *   - one transaction: every table is copied and verified — row counts plus
+ *     a SHA-256 over canonicalised rows — before COMMIT; any mismatch or
+ *     error rolls everything back.
+ *   - --dry-run does all of the above, rolls back, and drops what it created,
+ *     leaving the target as it found it.
+ *   - the target URL is printed with credentials removed.
+ */
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { PgAdapter, redactPgUrl, type DbAdapter } from "./db-adapter.js";
+
+export type MigrateOptions = {
+  from: string;
+  to: string;
+  dryRun?: boolean;
+  allowCommhubCopy?: boolean;
+  home?: string;
+  log?: (line: string) => void;
+};
+
+export type TableReport = { table: string; rows: number; sha256: string };
+export type MigrateReport = { ok: true; dryRun: boolean; tables: TableReport[] };
+
+class DryRunRollback extends Error {}
+
+/** Refusals are thrown as MigrateRefused so the CLI can print them without a stack. */
+export class MigrateRefused extends Error {}
+
+function refuse(message: string): never {
+  throw new MigrateRefused(`[migrate-to-pg] REFUSING: ${message}`);
+}
+
+const quoteIdent = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+/** One canonical text per value, identical for bun:sqlite and PgAdapter output. */
+function canonical(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "bigint") return `i:${value.toString()}`;
+  if (typeof value === "number") return Number.isInteger(value) ? `i:${value}` : `f:${value}`;
+  if (value instanceof Uint8Array) return `b:${Buffer.from(value).toString("hex")}`;
+  if (typeof value === "string" && /^-?\d+$/.test(value) && value.length > 15) return `i:${value}`; // unsafe int8 comes back as text
+  return `s:${String(value)}`;
+}
+
+/** Order-independent digest: hash each row, sort the row hashes, hash the list. */
+function tableDigest(rows: Iterable<Record<string, unknown>>, cols: string[]): { rows: number; sha256: string } {
+  const rowHashes: string[] = [];
+  for (const row of rows) {
+    rowHashes.push(createHash("sha256").update(JSON.stringify(cols.map((c) => canonical(row[c])))).digest("hex"));
+  }
+  rowHashes.sort();
+  return { rows: rowHashes.length, sha256: createHash("sha256").update(rowHashes.join("\n")).digest("hex") };
+}
+
+function bindValue(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : value.toString();
+  }
+  return value;
+}
+
+function checkSource(from: string, home: string, allowCommhubCopy: boolean): string {
+  const abs = resolve(from);
+  if (!existsSync(abs)) refuse(`source ${abs} does not exist`);
+  const real = realpathSync(abs);
+  if (!statSync(real).isFile()) refuse(`source ${real} is not a file`);
+  const commhubDir = join(home, ".commhub");
+  const guarded = existsSync(commhubDir) ? realpathSync(commhubDir) : resolve(commhubDir);
+  if ((real === guarded || real.startsWith(guarded + sep)) && !allowCommhubCopy) {
+    refuse(`source ${real} is under ${guarded}, the live Hub's directory. Stop the Hub, copy the database elsewhere, ` +
+      "and migrate the copy — or pass --i-know-this-is-a-copy if this file already is one");
+  }
+  const holders = processesHolding([real, `${real}-wal`, `${real}-shm`]);
+  if (holders === null) {
+    console.warn("[migrate-to-pg] cannot inspect open files on this platform — make sure the Hub using this database is stopped");
+  } else if (holders.length) {
+    refuse(`${real} is open in running process(es) ${holders.join(", ")} — stop the Hub first`);
+  }
+  return real;
+}
+
+/** PIDs (other than ours) with any of `paths` open; null where /proc is unavailable. */
+function processesHolding(paths: string[]): number[] | null {
+  if (!existsSync("/proc/self/fd")) return null;
+  const wanted = new Set(paths);
+  const holders: number[] = [];
+  for (const entry of readdirSync("/proc")) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid === process.pid) continue;
+    let fds: string[];
+    try { fds = readdirSync(`/proc/${pid}/fd`); } catch { continue; } // gone, or another user's
+    for (const fd of fds) {
+      let target = "";
+      try { target = readlinkSync(`/proc/${pid}/fd/${fd}`); } catch { continue; }
+      if (wanted.has(target.replace(/ \(deleted\)$/, ""))) { holders.push(pid); break; }
+    }
+  }
+  return holders;
+}
+
+function publicObjectCount(pg: PgAdapter): number {
+  const row = pg.get<{ n: number }>(
+    `SELECT (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.sequences WHERE sequence_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.routines WHERE routine_schema = 'public') AS n`,
+  );
+  return Number(row?.n ?? 0);
+}
+
+function dropEverythingInPublic(pg: DbAdapter) {
+  // Only ever called on a target that was verified empty before we started,
+  // so everything here was created by this run.
+  pg.exec(`DO $$ DECLARE r record; BEGIN
+    FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'public' LOOP
+      EXECUTE 'DROP FUNCTION IF EXISTS ' || r.sig || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT sequencename FROM pg_sequences WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP SEQUENCE IF EXISTS public.' || quote_ident(r.sequencename) || ' CASCADE';
+    END LOOP;
+  END $$`);
+}
+
+export async function migrateSqliteToPg(opts: MigrateOptions): Promise<MigrateReport> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const home = opts.home ?? process.env.HOME ?? "";
+  if (!/^postgres(ql)?:\/\//.test(opts.to)) refuse("--to must be a postgres:// or postgresql:// URL");
+  const source = checkSource(opts.from, home, !!opts.allowCommhubCopy);
+  log(`[migrate-to-pg] source ${source}`);
+  log(`[migrate-to-pg] target ${redactPgUrl(opts.to)}${opts.dryRun ? " (dry run)" : ""}`);
+
+  // Empty-target check on a connection of our own, before the schema exists.
+  const probe = new PgAdapter(opts.to);
+  const existing = publicObjectCount(probe);
+  probe.close();
+  if (existing > 0) refuse(`target schema "public" is not empty (${existing} tables/sequences/functions). Migrate only into a new, empty database`);
+
+  // Snapshot the source: a consistent read that cannot touch the original.
+  const snapDir = mkdtempSync(join(tmpdir(), "anet-migrate-"));
+  const snapshot = join(snapDir, "snapshot.db");
+  try {
+    const original = new Database(source, { readonly: true });
+    original.exec(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`);
+    original.close();
+    const src = new Database(snapshot, { readonly: true, safeIntegers: true });
+
+    // Build the target schema exactly as the Hub does: import its module graph
+    // with DATABASE_URL pointing at the target.
+    delete process.env.COMMHUB_DB;
+    process.env.DATABASE_URL = opts.to;
+    await import("./server.js");
+    const { db } = await import("./db.js");
+    if (db.dialect !== "postgres") throw new Error("schema build did not select PostgreSQL");
+
+    const tables = (src.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[])
+      .map((r) => r.name);
+    const report: TableReport[] = [];
+
+    try {
+      db.transaction(() => {
+        for (const table of tables) {
+          const srcCols = (src.query(`PRAGMA table_info(${quoteIdent(table)})`).all() as { name: string }[]).map((c) => c.name);
+          const tgtCols = new Set(db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1", table,
+          ).map((c) => c.column_name));
+          const srcCount = Number((src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get() as { n: bigint | number }).n);
+          if (tgtCols.size === 0) {
+            if (srcCount > 0) throw new Error(`table ${table} (${srcCount} rows) does not exist in the Hub's PostgreSQL schema`);
+            log(`[migrate-to-pg] skip ${table}: not in the PostgreSQL schema, and empty in the source`);
+            continue;
+          }
+          const missing = srcCols.filter((c) => !tgtCols.has(c));
+          if (missing.length && srcCount > 0) throw new Error(`table ${table}: column(s) ${missing.join(", ")} do not exist in PostgreSQL`);
+          const cols = srcCols.filter((c) => tgtCols.has(c));
+          // SQLite's implicit rowid carries insertion order; PostgreSQL keeps it
+          // in a real `rowid` column on the tables that sort by it (RFC-039 F3).
+          const copyRowid = tgtCols.has("rowid") && !srcCols.includes("rowid");
+          const selectCols = [...(copyRowid ? ["rowid AS rowid"] : []), ...cols.map(quoteIdent)].join(", ");
+          const insertCols = [...(copyRowid ? ["rowid"] : []), ...cols];
+
+          // Triggers are off only while this table is being filled. Re-enabled
+          // in `finally` so no path — including a failed batch — leaves them
+          // off; a rollback also restores them (DDL is transactional in PG).
+          db.exec(`ALTER TABLE ${quoteIdent(table)} DISABLE TRIGGER USER`);
+          try {
+            db.run(`DELETE FROM ${quoteIdent(table)}`); // rows the schema bootstrap seeded; the source is authoritative
+            const perBatch = Math.max(1, Math.floor(30000 / insertCols.length));
+            const stmt = src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)} ORDER BY rowid LIMIT ?1 OFFSET ?2`);
+            for (let offset = 0; offset < srcCount; offset += perBatch) {
+              const rows = stmt.all(perBatch, offset) as Record<string, unknown>[];
+              if (!rows.length) break;
+              const params: unknown[] = [];
+              const tuples = rows.map((row) => `(${insertCols.map((c) => { params.push(bindValue(row[c])); return `?${params.length}`; }).join(", ")})`);
+              db.run(`INSERT INTO ${quoteIdent(table)} (${insertCols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}`, params);
+            }
+          } finally {
+            db.exec(`ALTER TABLE ${quoteIdent(table)} ENABLE TRIGGER USER`);
+          }
+
+          // Sequences behind BIGSERIAL columns continue after the copied ids.
+          for (const seq of db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1 AND column_default LIKE 'nextval(%'", table,
+          )) {
+            db.get(`SELECT setval(pg_get_serial_sequence(?1, ?2), COALESCE((SELECT MAX(${quoteIdent(seq.column_name)}) FROM ${quoteIdent(table)}), 0) + 1, false)`,
+              table, seq.column_name);
+          }
+
+          // Verify before COMMIT.
+          const hashCols = copyRowid ? ["rowid", ...cols] : cols;
+          const srcDigest = tableDigest(src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)}`).all() as Record<string, unknown>[], hashCols);
+          const tgtDigest = tableDigest(db.all(`SELECT ${hashCols.map(quoteIdent).join(", ")} FROM ${quoteIdent(table)}`), hashCols);
+          if (srcDigest.rows !== tgtDigest.rows || srcDigest.sha256 !== tgtDigest.sha256) {
+            throw new Error(`verification failed for ${table}: source ${srcDigest.rows} rows ${srcDigest.sha256.slice(0, 12)}, ` +
+              `target ${tgtDigest.rows} rows ${tgtDigest.sha256.slice(0, 12)}`);
+          }
+          report.push({ table, rows: srcDigest.rows, sha256: srcDigest.sha256 });
+          log(`[migrate-to-pg] ${table}: ${srcDigest.rows} rows, sha256 ${srcDigest.sha256.slice(0, 16)} ✓`);
+        }
+        if (opts.dryRun) throw new DryRunRollback("dry run");
+      });
+    } catch (e) {
+      const rows = report.reduce((n, t) => n + t.rows, 0);
+      dropEverythingInPublic(db);
+      src.close();
+      if (!(e instanceof DryRunRollback)) {
+        const verify = e instanceof Error && e.message.startsWith("verification failed") ? "MISMATCH" : "NOT-REACHED";
+        log(`[migrate-to-pg] SUMMARY result=FAILED tables_verified=${report.length}/${tables.length} rows=${rows} verify=${verify} — rolled back, target left empty`);
+        throw e;
+      }
+      log(`[migrate-to-pg] SUMMARY result=DRY-RUN tables=${report.length} rows=${rows} verify=OK — rolled back, target left empty`);
+      return { ok: true, dryRun: true, tables: report };
+    }
+    src.close();
+    log(`[migrate-to-pg] SUMMARY result=COMMITTED tables=${report.length} rows=${report.reduce((n, t) => n + t.rows, 0)} verify=OK`);
+    return { ok: true, dryRun: false, tables: report };
+  } finally {
+    rmSync(snapDir, { recursive: true, force: true });
+  }
+}