@sleep2agi/commhub-server 0.9.0-preview.76 → 0.9.0-preview.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.76",
+  "version": "0.9.0-preview.78",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/mcp-route-label-http.test.ts

@@ -0,0 +1,120 @@
+// POST /mcp in /api/stats/routes carries the JSON-RPC method and, for tools/call, the tool name
+// ("POST /mcp tools/call report_status"). Production showed POST /mcp as the biggest route (15 req/s,
+// ~13% of a core) with no way to tell which tool. This suite pins, over real HTTP:
+//   - the labels (tools/call <name>, tools/list, batch) and that MCP responses are unchanged in kind;
+//   - arguments never reach the stats (a marker in arguments / a hostile tool name never shows up);
+//   - odd bodies still get the transport's own answers (invalid JSON → -32700, oversized → parsed by
+//     the transport itself) and are labelled "?";
+//   - unauthenticated /mcp stays plain "POST /mcp" (the body is never read before auth).
+
+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-mcp-route-label-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "McpRouteLabelPassw0rd!";
+const MARKER = "zz-argument-marker-7f3a";
+let BASE = "";
+let hub: any = null;
+let admin = "";
+
+const MCP_HEADERS = { "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" };
+async function mcpRaw(token: string, body: string): Promise<{ status: number; text: string }> {
+  const res = await fetch(`${BASE}/mcp`, { method: "POST", headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...MCP_HEADERS }, body });
+  return { status: res.status, text: await res.text() };
+}
+function rpc(text: string): any {
+  const lines = text.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(text);
+}
+async function routes(): Promise<{ text: string; keys: string[]; rows: any[] }> {
+  const res = await fetch(`${BASE}/api/stats/routes?minutes=5`, { headers: { Authorization: `Bearer ${admin}` } });
+  const text = await res.text();
+  const rows = JSON.parse(text).routes as any[];
+  return { text, keys: rows.map(r => r.route), rows };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`mrl_admin_${Date.now()}`, PW);
+  admin = a.token!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [a.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}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("POST /mcp route label", () => {
+  test("tools/call is labelled with the tool name and still answers normally", async () => {
+    const r = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "get_all_status", arguments: { note: MARKER } } }));
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result).toBeDefined();
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/call get_all_status");
+  });
+
+  test("tools/list and a batch get their own labels", async () => {
+    const list = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }));
+    expect(list.status).toBe(200);
+    expect(rpc(list.text).result.tools.length).toBeGreaterThan(10);
+    await mcpRaw(admin, JSON.stringify([{ jsonrpc: "2.0", id: 3, method: "tools/list" }]));
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/list");
+    expect(keys).toContain("POST /mcp batch");
+  });
+
+  test("arguments and hostile tool names never reach the stats", async () => {
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: `x ${MARKER}`, arguments: { a: MARKER } } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "n".repeat(500), arguments: {} } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 6, method: `tools/${MARKER} with spaces` }));
+    const { text, keys } = await routes();
+    expect(text).not.toContain(MARKER);
+    expect(text).not.toContain("n".repeat(65));
+    expect(keys).toContain("POST /mcp tools/call ?");
+    expect(keys).toContain("POST /mcp ?");
+    for (const k of keys) expect(k.length).toBeLessThan(200);
+  });
+
+  test("invalid JSON still gets the transport's parse error, labelled ?", async () => {
+    const r = await mcpRaw(admin, `{"jsonrpc":"2.0","method":"tools/list",`);
+    expect(r.status).toBe(400);
+    expect(rpc(r.text).error.code).toBe(-32700);
+    expect(rpc(r.text).error.message).toBe("Parse error: Invalid JSON");
+    const notRpc = await mcpRaw(admin, "null");
+    expect(notRpc.status).toBe(400);
+    expect(rpc(notRpc.text).error.code).toBe(-32700);
+  });
+
+  test("a body over the label limit is left to the transport and still works, labelled ?", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const padded = JSON.stringify({ jsonrpc: "2.0", id: 7, method: "tools/list" }).replace("{", "{" + " ".repeat(1024 * 1024 + 10));
+    const r = await mcpRaw(admin, padded);
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result.tools.length).toBeGreaterThan(10);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp ?");
+    expect(keys).not.toContain("POST /mcp tools/list");
+  });
+
+  test("unauthenticated /mcp is refused as before and not labelled", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const r = await mcpRaw("", JSON.stringify({ jsonrpc: "2.0", id: 8, method: "tools/list" }));
+    expect(r.status).toBe(401);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp");
+    expect(keys.filter(k => k.startsWith("POST /mcp "))).toEqual([]);
+  });
+});

package/src/requirement-events-http.test.ts

@@ -0,0 +1,257 @@
+// 任务动态(#429)—— HTTP 集成测试(真实 Bun.serve,临时库;PG 梯子上用 COMMHUB_TEST_PG_URL 原样再跑一遍)。
+//   写路径    —— 新建 / PATCH 的每个字段 / 勾子任务 / 标签改名 / 删项目 / 删卡,各记字段级流水:谁、旧值 → 新值
+//   同一事务  —— 流水写不进去,那次改动也不生效
+//   可见范围  —— 与列表相同:scoped 成员只看到看得见的卡(删掉的按墓碑);Agent 受限成员看不见的节点被隐去
+//   翻页      —— limit / next_cursor / since / requirement_id;参数不合法 400;capability `events`
+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-requirement-events-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "EventsPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let restricted = { token: "", id: "" };
+let nodeToken = "";
+let NODE = "";
+
+type R = { status: number; body: any };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; seq: number };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const events = (t: string, qs = "") => send(t, "GET", `/api/requirements/events?network_id=${NET}${qs}`);
+const of = (list: any[], id: string) => list.filter(e => e.requirement_id === id);
+const user = (id: string) => ({ kind: "user", id });
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`ev_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.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}`;
+  const mk = async (username: string) => {
+    const r = await send(admin.token, "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 });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`ev_member_${stamp}`);
+  scoped = await mk(`ev_scoped_${stamp}`);
+  restricted = await mk(`ev_restricted_${stamp}`);
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  // 看全部任务,但一个 Agent 都没授权:所有节点对他隐去
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, restricted.id]);
+  NODE = `n_ev_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [NODE, "ev-node", "ev-node", NET]);
+  const ntok = createNetworkTokenForNode(admin.id, NET, "ev-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirement events", () => {
+  test("capability `events` is advertised", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("events");
+  });
+
+  test("create records one `created` event with the actor, title and seq", async () => {
+    const card = await create(member.token, { name: "动态示例一" });
+    const r = await events(admin.token, `&requirement_id=${card.id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.events.length).toBe(1);
+    const [e] = r.body.events;
+    expect(e).toMatchObject({ kind: "created", field: null, actor: user(member.id), title: "动态示例一", seq: card.seq, new: { title: "动态示例一", column: "pool" } });
+    expect(typeof e.id).toBe("string");
+    expect(Date.parse(e.at)).toBeGreaterThan(0);
+  });
+
+  test("a PATCH records one event per changed field, old → new; unchanged fields and no-op PATCHes record nothing", async () => {
+    const card = await create(admin.token, { name: "动态示例二", priority: "normal", tags: ["UI"] });
+    const r1 = await patch(member.token, card.id, {
+      column: "doing", priority: "high", due: "2026-10-03", name: "动态示例二(改)", tags: ["UI", "后端"],
+      agent_owner: { kind: "node", id: NODE }, participants: [user(admin.id)], assignee: "",
+    });
+    expect(r1.status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    const byField = Object.fromEntries(list.filter((e: any) => e.kind === "changed").map((e: any) => [e.field, e]));
+    expect(Object.keys(byField).sort()).toEqual(["agent_owner", "column", "due", "participants", "priority", "tags", "title"]);
+    expect(byField.column).toMatchObject({ old: "pool", new: "doing", actor: user(member.id) });
+    expect(byField.priority).toMatchObject({ old: "normal", new: "high" });
+    expect(byField.due).toMatchObject({ old: null, new: "2026-10-03" });
+    expect(byField.title).toMatchObject({ old: "动态示例二", new: "动态示例二(改)" });
+    expect(byField.tags).toMatchObject({ old: ["UI"], new: ["UI", "后端"] });
+    expect(byField.agent_owner).toMatchObject({ old: null, new: { kind: "node", id: NODE } });
+    expect(byField.participants).toMatchObject({ old: [], new: [user(admin.id)] });
+    // every event of that PATCH carries the card's title after the change
+    expect(new Set(list.filter((e: any) => e.kind === "changed").map((e: any) => e.title))).toEqual(new Set(["动态示例二(改)"]));
+    const before = list.length;
+    expect((await patch(member.token, card.id, { priority: "high", column: "doing" })).status).toBe(200);
+    expect(of((await events(admin.token)).body.events, card.id).length).toBe(before);
+    // archive / unarchive, description (length only, never the text), move to done
+    await patch(member.token, card.id, { description: "一段描述" });
+    await patch(member.token, card.id, { column: "done" });
+    await patch(member.token, card.id, { archived: true });
+    const later = of((await events(admin.token)).body.events, card.id).slice(0, 3);
+    expect(later.map((e: any) => e.field)).toEqual(["archived", "column", "description"]);
+    expect(later[0]).toMatchObject({ old: false, new: true });
+    expect(later[1]).toMatchObject({ old: "doing", new: "done" });
+    expect(later[2]).toMatchObject({ old: { chars: 0 }, new: { chars: 4 } });
+    expect(JSON.stringify(later[2])).not.toContain("一段描述");
+  });
+
+  test("checklist: ticking an item is `checklist_item` (repeat is a no-op); adding items is `checklist`", async () => {
+    const card = await create(admin.token, { name: "动态示例三", checklist: [{ id: "a", text: "第一项" }, { id: "b", text: "第二项" }] });
+    const tick = (done: boolean) => send(member.token, "PATCH", `/api/requirements/${card.id}/checklist/a?network_id=${NET}`, { done });
+    expect((await tick(true)).status).toBe(200);
+    expect((await tick(true)).status).toBe(200);
+    let list = of((await events(admin.token)).body.events, card.id);
+    const ticks = list.filter((e: any) => e.field === "checklist_item");
+    expect(ticks.length).toBe(1);
+    expect(ticks[0]).toMatchObject({ old: { id: "a", text: "第一项", done: false }, new: { id: "a", text: "第一项", done: true }, actor: user(member.id) });
+    // a PATCH that only flips one item's done is also `checklist_item`
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }] });
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }, { id: "c", text: "第三项" }] });
+    list = of((await events(admin.token)).body.events, card.id);
+    expect(list[0]).toMatchObject({ field: "checklist", old: { total: 2, done: 2 }, new: { total: 3, done: 2 } });
+    expect(list[1]).toMatchObject({ field: "checklist_item", new: { id: "b", done: true } });
+  });
+
+  test("the actor of a node token is the node", async () => {
+    const card = await create(admin.token, { name: "动态示例四" });
+    expect((await patch(nodeToken, card.id, { column: "doing" })).status).toBe(200);
+    const [e] = of((await events(nodeToken)).body.events, card.id);
+    expect(e).toMatchObject({ field: "column", actor: { kind: "node", id: NODE } });
+  });
+
+  test("tag rename, project delete and card delete each record per-card events", async () => {
+    const p = await send(admin.token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `动态项目-${Date.now()}` });
+    expect(p.status).toBe(201);
+    const card = await create(admin.token, { name: "动态示例五", tags: ["旧标签"], project_id: p.body.project.id });
+    expect((await send(admin.token, "POST", `/api/requirements/tags/ops?network_id=${NET}`, { op: "rename", from: "旧标签", to: "新标签" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${p.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${card.id}?network_id=${NET}`)).status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    expect(list.slice(0, 3).map((e: any) => [e.kind, e.field])).toEqual([["deleted", null], ["changed", "project"], ["changed", "tags"]]);
+    expect(list[0]).toMatchObject({ title: "动态示例五", seq: expect.any(Number), actor: user(admin.id) });
+    expect(list[1]).toMatchObject({ old: p.body.project.id, new: null });
+    expect(list[2]).toMatchObject({ old: ["旧标签"], new: ["新标签"] });
+  });
+
+  test("the write and its events are one transaction: no events table → the PATCH fails and the card is unchanged", async () => {
+    const { db } = await import("./db.js");
+    const card = await create(admin.token, { name: "动态示例六", priority: "low" });
+    db.exec("ALTER TABLE requirement_events RENAME TO requirement_events_away");
+    try {
+      const r = await patch(admin.token, card.id, { priority: "high" });
+      expect(r.status).toBeGreaterThanOrEqual(500);
+    } finally {
+      db.exec("ALTER TABLE requirement_events_away RENAME TO requirement_events");
+    }
+    const now = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(now.body.requirement.priority).toBe("low");
+  });
+
+  test("a scoped member sees events only for cards they can see — deleted ones by their tombstone", async () => {
+    const mine = await create(scoped.token, { name: "动态示例七(scoped 自己建的)" });
+    const theirs = await create(admin.token, { name: "动态示例八(scoped 看不见)" });
+    const joined = await create(admin.token, { name: "动态示例九(scoped 是参与人)", participants: [user(scoped.id)] });
+    await patch(admin.token, mine.id, { priority: "high" });
+    await patch(admin.token, theirs.id, { priority: "high" });
+    await send(admin.token, "DELETE", `/api/requirements/${joined.id}?network_id=${NET}`);
+    const seen = (await events(scoped.token, "&limit=500")).body.events;
+    expect(of(seen, mine.id).length).toBe(2);
+    expect(of(seen, theirs.id).length).toBe(0);
+    expect(of(seen, joined.id).map((e: any) => e.kind)).toEqual(["deleted", "created"]);
+    // a filter on a card they cannot see answers like a card with no events
+    expect((await events(scoped.token, `&requirement_id=${theirs.id}`)).body.events).toEqual([]);
+  });
+
+  test("an agent-restricted member: hidden nodes are masked, and an event that only differs by a hidden node is dropped", async () => {
+    const card = await create(admin.token, { name: "动态示例十" });
+    await patch(nodeToken, card.id, { priority: "high" });
+    await patch(admin.token, card.id, { agent_owner: { kind: "node", id: NODE } });
+    await patch(admin.token, card.id, { participants: [user(admin.id), { kind: "node", id: NODE }] });
+    const seen = of((await events(restricted.token)).body.events, card.id);
+    const all = of((await events(admin.token)).body.events, card.id);
+    expect(all.map((e: any) => e.field)).toEqual(["participants", "agent_owner", "priority", null]);
+    expect(seen.map((e: any) => e.field)).toEqual(["participants", "priority", null]);
+    expect(seen[0]).toMatchObject({ old: [], new: [user(admin.id)] });
+    expect(seen[1]).toMatchObject({ field: "priority", actor: null });
+    expect(JSON.stringify(seen)).not.toContain(NODE);
+  });
+
+  test("paging: newest first, limit + next_cursor without overlap; since; bad params 400", async () => {
+    const card = await create(admin.token, { name: "动态示例十一" });
+    for (const priority of ["high", "low", "lowest", "normal"]) await patch(admin.token, card.id, { priority });
+    const q = `&requirement_id=${card.id}`;
+    const p1 = await events(admin.token, `${q}&limit=2`);
+    expect(p1.body.events.length).toBe(2);
+    expect(p1.body.has_more).toBe(true);
+    expect(p1.body.events[0].new).toBe("normal");
+    const p2 = await events(admin.token, `${q}&limit=2&cursor=${p1.body.next_cursor}`);
+    const p3 = await events(admin.token, `${q}&limit=2&cursor=${p2.body.next_cursor}`);
+    const ids = [...p1.body.events, ...p2.body.events, ...p3.body.events].map((e: any) => e.id);
+    expect(new Set(ids).size).toBe(5);
+    expect(p3.body.has_more).toBe(false);
+    expect(p3.body.next_cursor).toBe(null);
+    expect(ids.map(Number)).toEqual([...ids.map(Number)].sort((a, b) => b - a));
+    // since = server_time of an earlier read → only what came after
+    const t = p1.body.server_time;
+    await patch(admin.token, card.id, { priority: "high" });
+    const after = await events(admin.token, `${q}&since=${encodeURIComponent(t)}`);
+    // since is inclusive (>=): an event written in the same millisecond as server_time comes back again,
+    // and clients dedupe by id. Only the events not already seen must be exactly the new one.
+    expect(after.body.events.every((e: any) => Date.parse(e.at) >= Date.parse(t))).toBe(true);
+    const seen = new Set(ids);
+    expect(after.body.events.filter((e: any) => !seen.has(e.id)).map((e: any) => e.new)).toEqual(["high"]);
+    for (const bad of ["&limit=0", "&limit=501", "&limit=x", "&since=nope", "&cursor=abc", "&cursor=0"]) {
+      expect((await events(admin.token, bad)).status).toBe(400);
+    }
+  });
+
+  test("migration is idempotent and leaves the rows alone", async () => {
+    const { db } = await import("./db.js");
+    const { ensureRequirementEvents } = await import("./requirement-events.js");
+    const n = Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n);
+    ensureRequirementEvents(db);
+    ensureRequirementEvents(db);
+    expect(Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n)).toBe(n);
+    expect(n).toBeGreaterThan(0);
+  });
+});

package/src/requirement-events.test.ts

@@ -0,0 +1,45 @@
+// diffRequirement 的边角(HTTP 层的写路径在 requirement-events-http.test.ts)。
+import { describe, expect, test } from "bun:test";
+import { diffRequirement, eventPublic, type EventCard } from "./requirement-events.js";
+
+const base: EventCard = {
+  requirement_id: "req_1", network_id: "net_1", seq: 7, title: "示例", column_name: "pool", priority: "normal", due_on: null, start_on: null,
+  assignee: null, owner_json: null, agent_owner_json: null, participants_json: "[]", tags_json: "[]", checklist_json: "[]", description: null,
+  project_id: null, parent_id: null, archived: 0,
+};
+const ck = (items: { id: string; text: string; done?: boolean }[]) => JSON.stringify(items.map(i => ({ done: false, ...i })));
+
+describe("diffRequirement", () => {
+  test("no change → no events; null vs empty string are the same", () => {
+    expect(diffRequirement(base, { ...base })).toEqual([]);
+    expect(diffRequirement(base, { ...base, due_on: "", assignee: "", description: "" })).toEqual([]);
+  });
+  test("created carries title and column only", () => {
+    expect(diffRequirement(null, base)).toEqual([{ kind: "created", field: null, old: null, new: { title: "示例", column: "pool" } }]);
+  });
+  test("checklist: reorder, rename, add or remove is one `checklist` event with counts", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二", done: true }]) };
+    for (const next of [ck([{ id: "b", text: "二", done: true }, { id: "a", text: "一" }]), ck([{ id: "a", text: "一改" }, { id: "b", text: "二", done: true }]), ck([{ id: "a", text: "一" }])]) {
+      const out = diffRequirement(a, { ...a, checklist_json: next });
+      expect(out.length).toBe(1);
+      expect(out[0].field).toBe("checklist");
+    }
+    expect(diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一" }]) })[0]).toMatchObject({ old: { total: 2, done: 1 }, new: { total: 1, done: 0 } });
+  });
+  test("checklist: two items ticked in one write are two `checklist_item` events", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二" }]) };
+    const out = diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一", done: true }, { id: "b", text: "二", done: true }]) });
+    expect(out.map(e => [e.field, (e.new as { id: string }).id])).toEqual([["checklist_item", "a"], ["checklist_item", "b"]]);
+  });
+  test("malformed stored JSON reads as empty rather than throwing", () => {
+    expect(() => diffRequirement({ ...base, tags_json: "{nope", participants_json: "x" }, base)).not.toThrow();
+  });
+  test("description records lengths, never text", () => {
+    const [e] = diffRequirement(base, { ...base, description: "secret text" });
+    expect(e).toEqual({ kind: "changed", field: "description", old: { chars: 0 }, new: { chars: 11 } });
+  });
+  test("eventPublic: bigint / string ids from PostgreSQL come out as strings, seq as a number", () => {
+    const row = { id: 12n as unknown as string, network_id: "n", requirement_id: "r", seq: "3", title: "t", actor_json: null, kind: "changed", field: "priority", old_json: "\"low\"", new_json: "\"high\"", created_at: "2026-10-01T00:00:00.000Z" };
+    expect(eventPublic(row)).toMatchObject({ id: "12", seq: 3, old: "low", new: "high", actor: null });
+  });
+});

package/src/requirement-events.ts

@@ -0,0 +1,143 @@
+// 任务动态(#429,Vincent 2026-09-30「任务有新的状态…这完成了,这是有这种动态」)。
+//
+// requirements 表只存「现在是什么」和「最后是谁改的」(updated_by_json),改之前是什么没有任何地方留着 ——
+// 「优先级 P2 → P0」「状态 需求池 → 进行中」画不出来。这里给每一次写入记字段级的流水:谁(用户 / 节点)、
+// 什么时候、哪个字段、旧值 → 新值。写入点在 requirements.ts 的各条写路径里,和那次 UPDATE 在同一个事务里。
+//
+// 表只加不改:旧 Hub(回滚之后)不认识这张表,也不会碰它;再升回来接着记(回滚期间的改动没有流水)。
+// 读:GET /api/requirements/events(requirements.ts,可见范围与列表相同),capability `events`。
+import type { DbAdapter } from "./db-adapter.js";
+
+/** 流水保留多久。更早的在写入时顺手清掉(每 PRUNE_EVERY 次写一次)。 */
+export const EVENTS_RETENTION_MS = 180 * 86_400_000;
+const PRUNE_EVERY = 500;
+
+/** IF NOT EXISTS:重复执行无副作用;SQLite / PostgreSQL 同一段(适配层把 AUTOINCREMENT 译成 BIGSERIAL)。 */
+export function ensureRequirementEvents(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_events (
+      id             INTEGER PRIMARY KEY AUTOINCREMENT,
+      network_id     TEXT NOT NULL,
+      requirement_id TEXT NOT NULL,
+      seq            INTEGER,
+      title          TEXT,
+      actor_json     TEXT,
+      kind           TEXT NOT NULL,
+      field          TEXT,
+      old_json       TEXT,
+      new_json       TEXT,
+      created_at     TEXT NOT NULL
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_network ON requirement_events(network_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_card ON requirement_events(requirement_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_created ON requirement_events(created_at)");
+}
+
+/** 流水要比较的列(requirements.ts 的 Row 的子集)。 */
+export type EventCard = {
+  requirement_id: string;
+  network_id: string;
+  seq: number | null;
+  title: string;
+  column_name: string;
+  priority: string;
+  due_on: string | null;
+  start_on: string | null;
+  assignee: string | null;
+  owner_json: string | null;
+  agent_owner_json: string | null;
+  participants_json: string | null;
+  tags_json: string | null;
+  checklist_json: string | null;
+  description: string | null;
+  project_id: string | null;
+  parent_id: string | null;
+  archived: number | null;
+};
+
+export type EventKind = "created" | "changed" | "deleted";
+/**
+ * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
+ * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
+ * description(只记字数,不存正文)/ project / parent / archived。
+ */
+export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
+
+const parse = (json: string | null | undefined): unknown => {
+  if (!json) return null;
+  try { return JSON.parse(json); } catch { return null; }
+};
+const list = (json: string | null | undefined): unknown[] => { const v = parse(json); return Array.isArray(v) ? v : []; };
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+type Item = { id: string; text: string; done: boolean };
+const items = (json: string | null | undefined): Item[] =>
+  list(json).filter((x): x is Item => !!x && typeof (x as Item).id === "string" && typeof (x as Item).text === "string").map(x => ({ id: x.id, text: x.text, done: !!x.done }));
+const counts = (xs: Item[]) => ({ total: xs.length, done: xs.filter(x => x.done).length });
+
+/** 一次写入前后的差异。before = null:新建(只记一条 created)。 */
+export function diffRequirement(before: EventCard | null, after: EventCard): EventDraft[] {
+  if (!before) return [{ kind: "created", field: null, old: null, new: { title: after.title, column: after.column_name } }];
+  const out: EventDraft[] = [];
+  const scalar = (field: string, a: unknown, b: unknown) => { if (!same(a, b)) out.push({ kind: "changed", field, old: a, new: b }); };
+  scalar("column", before.column_name, after.column_name);
+  scalar("title", before.title, after.title);
+  scalar("priority", before.priority, after.priority);
+  scalar("due", before.due_on || null, after.due_on || null);
+  scalar("start", before.start_on || null, after.start_on || null);
+  scalar("assignee", before.assignee || null, after.assignee || null);
+  scalar("owner", parse(before.owner_json), parse(after.owner_json));
+  scalar("agent_owner", parse(before.agent_owner_json), parse(after.agent_owner_json));
+  scalar("participants", list(before.participants_json), list(after.participants_json));
+  scalar("tags", list(before.tags_json), list(after.tags_json));
+  // 子任务:同一条(同 id、同文字)只是勾选变了 = 一条 checklist_item;条目增删 / 改字 / 换顺序 = 一条 checklist。
+  const a = items(before.checklist_json), b = items(after.checklist_json);
+  const shape = (xs: Item[]) => xs.map(x => `${x.id}\u0000${x.text}`).join("\u0001");
+  if (shape(a) === shape(b)) {
+    for (let i = 0; i < b.length; i++) if (a[i].done !== b[i].done) out.push({ kind: "changed", field: "checklist_item", old: a[i], new: b[i] });
+  } else {
+    out.push({ kind: "changed", field: "checklist", old: counts(a), new: counts(b) });
+  }
+  if ((before.description || "") !== (after.description || "")) {
+    out.push({ kind: "changed", field: "description", old: { chars: (before.description || "").length }, new: { chars: (after.description || "").length } });
+  }
+  scalar("project", before.project_id || null, after.project_id || null);
+  scalar("parent", before.parent_id || null, after.parent_id || null);
+  scalar("archived", !!before.archived, !!after.archived);
+  return out;
+}
+
+let writes = 0;
+
+/** 记下一张卡的一组流水(调用方负责放进同一个事务)。actorJson = updated_by_json 的那个值。 */
+export function recordRequirementEvents(database: DbAdapter, card: Pick<EventCard, "requirement_id" | "network_id" | "seq" | "title">, actorJson: string | null, drafts: readonly EventDraft[], at: string): void {
+  for (const d of drafts) {
+    database.run(
+      `INSERT INTO requirement_events (network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`,
+      [card.network_id, card.requirement_id, card.seq ?? null, card.title, actorJson && actorJson !== "null" ? actorJson : null, d.kind, d.field,
+        d.old === null || d.old === undefined ? null : JSON.stringify(d.old), d.new === null || d.new === undefined ? null : JSON.stringify(d.new), at],
+    );
+    writes++;
+  }
+  if (drafts.length && writes >= PRUNE_EVERY) {
+    writes = 0;
+    database.run("DELETE FROM requirement_events WHERE created_at < ?1", [new Date(Date.parse(at) - EVENTS_RETENTION_MS).toISOString()]);
+  }
+}
+
+export type EventRow = { id: number | string; network_id: string; requirement_id: string; seq: number | string | null; title: string | null; actor_json: string | null; kind: string; field: string | null; old_json: string | null; new_json: string | null; created_at: string };
+
+/** 对外的一条(id 转成字符串:PostgreSQL 的 BIGSERIAL 可能回成字符串或 bigint,客户端一律按字符串比较 / 翻页)。 */
+export const eventPublic = (row: EventRow) => ({
+  id: String(row.id),
+  requirement_id: row.requirement_id,
+  seq: row.seq == null ? null : Number(row.seq),
+  title: row.title,
+  actor: parse(row.actor_json),
+  kind: row.kind,
+  field: row.field,
+  old: parse(row.old_json),
+  new: parse(row.new_json),
+  at: row.created_at,
+});

package/src/requirements-http.test.ts

@@ -373,7 +373,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", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {