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

package/src/db-adapter.ts

@@ -2,12 +2,14 @@
  * 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'
+ *   - 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  →  SERIAL PRIMARY KEY
  *   - 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,17 @@ 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()"));
   // ── Parameter placeholders ──
   // ?1, ?2 → $1, $2  (positional params)
   s = s.replace(/\?(\d+)/g, (_, n) => `$${n}`);
@@ -106,67 +134,148 @@ export function sqliteToPostgres(sql: string): string {
   // ── DDL translations ──
   // INTEGER PRIMARY KEY AUTOINCREMENT → SERIAL PRIMARY KEY
   s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "SERIAL PRIMARY KEY");
+  // 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 `;`.
  *
- * 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.
+ * 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.
+ *
+ * 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 };
   }
 
   get<T = any>(sql: string, ...params: any[]): T | null {
@@ -183,9 +292,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 +302,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();
+  }
 }
 
 // ════════════════════════════════════════════

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;

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);
+});

package/src/requirements-etag-http.test.ts

@@ -0,0 +1,91 @@
+// GET /api/requirements conditional requests: ETag on every list response, 304 with an empty body
+// when If-None-Match matches. The app polls the whole list every 15 s (production: 500 rows,
+// 708 KB / 163 KB gzip) and it is unchanged on almost every poll. Old clients never send
+// If-None-Match and keep getting the full 200.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-requirements-etag-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let ownerToken = "", network = "";
+
+const list = (token: string, headers: Record<string, string> = {}) =>
+  fetch(`${base}/api/requirements?network_id=${network}`, { headers: { Authorization: `Bearer ${token}`, ...headers } });
+
+beforeAll(async () => {
+  const { register } = await import("./auth.js");
+  const owner = register(`etag_owner_${Date.now()}`, "EtagOwnerPassw0rd!", undefined, "seed");
+  ownerToken = owner.token!; network = owner.network_id!;
+  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}`;
+  const created = await fetch(`${base}/api/requirements`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${ownerToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "etag card", network_id: network }),
+  });
+  expect(created.status).toBe(201);
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/requirements conditional requests", () => {
+  test("a plain GET is the same 200 JSON as before, plus ETag and private/no-cache", async () => {
+    const res = await list(ownerToken);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("application/json;charset=utf-8");
+    expect(res.headers.get("etag")).toMatch(/^W\/"[A-Za-z0-9_-]{27}"$/);
+    expect(res.headers.get("cache-control")).toBe("private, no-cache");
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(body.requirements.map((r: any) => r.name)).toEqual(["etag card"]);
+    expect(Array.isArray(body.capabilities)).toBe(true);
+  });
+
+  test("If-None-Match with the current ETag → 304, empty body, same ETag", async () => {
+    const etag = (await list(ownerToken)).headers.get("etag")!;
+    const res = await list(ownerToken, { "If-None-Match": etag });
+    expect(res.status).toBe(304);
+    expect(res.headers.get("etag")).toBe(etag);
+    expect(await res.text()).toBe("");
+    // strong/weak spelling and lists are accepted
+    expect((await list(ownerToken, { "If-None-Match": etag.replace(/^W\//, "") })).status).toBe(304);
+    expect((await list(ownerToken, { "If-None-Match": `W/"stale", ${etag}` })).status).toBe(304);
+  });
+
+  test("304 survives gzip negotiation (not compressed, still empty)", async () => {
+    const etag = (await list(ownerToken, { "Accept-Encoding": "gzip" })).headers.get("etag")!;
+    const res = await list(ownerToken, { "If-None-Match": etag, "Accept-Encoding": "gzip" });
+    expect(res.status).toBe(304);
+    expect(res.headers.get("content-encoding")).toBeNull();
+  });
+
+  test("any change to the list changes the ETag → full 200 again", async () => {
+    const before = await list(ownerToken);
+    const etag = before.headers.get("etag")!;
+    const id = ((await before.json()) as any).requirements[0].id;
+    const patched = await fetch(`${base}/api/requirements/${id}?network_id=${network}`, {
+      method: "PATCH",
+      headers: { Authorization: `Bearer ${ownerToken}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "etag card renamed" }),
+    });
+    expect(patched.status).toBe(200);
+    const res = await list(ownerToken, { "If-None-Match": etag });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("etag")).not.toBe(etag);
+    expect(((await res.json()) as any).requirements[0].name).toBe("etag card renamed");
+  });
+
+  test("a stale or foreign ETag never yields 304", async () => {
+    expect((await list(ownerToken, { "If-None-Match": 'W/"not-the-current-one"' })).status).toBe(200);
+    expect((await list(ownerToken, { "If-None-Match": "" })).status).toBe(200);
+  });
+});

package/src/requirements-http.test.ts

@@ -372,7 +372,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {