relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/falkor/demo.js

@@ -0,0 +1,221 @@
+// Shared helper for seeding the isolated 5-agent demo sandbox (`demo_<projectId>`)
+// and rebuilding a real workspace graph (`<projectId>`) from real transcripts & history.
+const path = require("path");
+const schema = require("./schema");
+const cursor = require("./cursor");
+const { projectHistory, projectPeer } = require("./project");
+const { writeProjection } = require("./write");
+const { ingestHistory, ingestPeer } = require("./ingest");
+const coord = require("./coord");
+const central = require("./central");
+const analytics = require("./analytics");
+const intents = require("./intents");
+const { loadRegistry, loadMemory } = require("../store");
+
+const WS = process.platform === "win32" ? "C:\\demo\\relay-app" : "/workspace/relay-app";
+const wsFile = (...parts) => path.join(WS, ...parts);
+
+const S_CLAUDE = "52b29a54-d8fb-4091-ab60-463ac73c9d6c";
+const S_CURSOR = "3e62675d-9b0f-4d99-b17d-c1d875fe98dc";
+const S_CODEX = "019e1fdf-e54d-70e2-ae26-d0d7103a404f";
+const S_COPILOT = "fcc51653-804f-4e4f-9330-347a42abd57c";
+const S_ANTI = "46d9adf1-1b25-4cf7-bd41-da8309d19f08";
+
+function demoGraphId(projectId) {
+  const base = String(projectId || "sandbox").replace(/^demo_/, "");
+  return `demo_${base}`;
+}
+
+function buildDemoHistory(now = Date.now()) {
+  const m = (minsAgo) => now - minsAgo * 60_000;
+  return [
+    // Session 1: Claude Code (@alice) switching login flow to JWT tokens
+    { id: "d01", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(25), role: "user", kind: "message", text: "switch the login flow to short-lived JWT tokens with refresh rotation" },
+    { id: "d02", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(24.5), role: "assistant", kind: "message", text: "I'll update src/auth.ts to issue 15-minute access JWTs and rotate refresh tokens in src/session.ts." },
+    { id: "d03", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(24), role: "tool", kind: "code_edit", text: "Edit auth.ts", file: "auth.ts", path: wsFile("src", "auth.ts"), diff: "--- a/src/auth.ts\n+++ b/src/auth.ts\n@@ -10,4 +10,8 @@\n-export function loginWithCookie(user) {\n+export function issueJwtPair(user) {\n+  return signJwt(user, { expiresIn: '15m' });\n" },
+    { id: "d04", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(23), role: "tool", kind: "code_edit", text: "Edit session.ts", file: "session.ts", path: wsFile("src", "session.ts"), diff: "--- a/src/session.ts\n+++ b/src/session.ts\n@@ -1,3 +1,6 @@\n+export function rotateRefreshToken(token) {\n+  return revokeAndMint(token);\n+}\n" },
+    { id: "d05", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(22), role: "user", kind: "message", text: "continue" },
+    { id: "d06", agent: "Claude Code", ownerLogin: "alice", sessionId: S_CLAUDE, ts: m(21.5), role: "tool", kind: "code_edit", text: "Edit middleware.ts", file: "middleware.ts", path: wsFile("src", "middleware.ts"), diff: "--- a/src/middleware.ts\n+++ b/src/middleware.ts\n@@ -4,2 +4,5 @@\n+export function verifyBearerJwt(req, res, next) {\n+  req.user = verifyJwt(req.headers.authorization);\n+}\n" },
+
+    // Session 2: Codex (@alice) hardening rate limits on auth & api routes
+    { id: "d07", agent: "Codex", ownerLogin: "alice", sessionId: S_CODEX, ts: m(18), role: "user", kind: "message", text: "add sliding-window rate limiting to login and token refresh endpoints" },
+    { id: "d08", agent: "Codex", ownerLogin: "alice", sessionId: S_CODEX, ts: m(17.5), role: "assistant", kind: "message", text: "Applying rate limiter middleware to src/routes.ts and src/auth.ts." },
+    { id: "d09", agent: "Codex", ownerLogin: "alice", sessionId: S_CODEX, ts: m(17), role: "tool", kind: "code_edit", text: "apply_patch auth.ts", file: "auth.ts", path: wsFile("src", "auth.ts"), diff: "+import { rateLimit } from './rateLimit';\n+export const authLimiter = rateLimit({ windowMs: 60000, max: 10 });\n" },
+    { id: "d10", agent: "Codex", ownerLogin: "alice", sessionId: S_CODEX, ts: m(16.8), role: "tool", kind: "code_edit", text: "apply_patch routes.ts", file: "routes.ts", path: wsFile("src", "routes.ts"), diff: "+app.post('/api/token/refresh', authLimiter, rotateRefreshToken);\n" },
+
+    // Session 3: Antigravity (@alice) updating UI auth client
+    { id: "d11", agent: "Antigravity", ownerLogin: "alice", sessionId: S_ANTI, ts: m(12), role: "user", kind: "message", text: "wire automatic silent JWT refresh into the frontend API client" },
+    { id: "d12", agent: "Antigravity", ownerLogin: "alice", sessionId: S_ANTI, ts: m(11.5), role: "assistant", kind: "message", text: "Updating src/client.ts and src/auth.ts types to retry 401 responses after refreshing the access token." },
+    { id: "d13", agent: "Antigravity", ownerLogin: "alice", sessionId: S_ANTI, ts: m(11), role: "tool", kind: "code_edit", text: "replace_file_content client.ts", file: "client.ts", path: wsFile("src", "client.ts"), diff: "+if (res.status === 401) await refreshAccessToken();\n" },
+    { id: "d14", agent: "Antigravity", ownerLogin: "alice", sessionId: S_ANTI, ts: m(10.5), role: "tool", kind: "code_edit", text: "replace_file_content auth.ts", file: "auth.ts", path: wsFile("src", "auth.ts"), diff: "+export type TokenPair = { accessToken: string; refreshToken: string; expiresIn: number };\n" },
+  ];
+}
+
+function buildPeerSnapshot(now = Date.now()) {
+  const m = (minsAgo) => now - minsAgo * 60_000;
+  return {
+    login: "bob",
+    chats: [
+      {
+        id: `chat_cursor_${S_CURSOR}`,
+        agent: "Cursor",
+        ownerLogin: "bob",
+        sessionId: S_CURSOR,
+        messages: [
+          { role: "user", kind: "message", text: "add logout revocation endpoint and clear refresh token store", ts: m(20) },
+          { role: "assistant", kind: "message", text: "Adding token revocation in src/auth.ts and src/session.ts.", ts: m(19.5) },
+          { role: "tool", kind: "code_edit", text: "StrReplace auth.ts", file: "auth.ts", ts: m(19) },
+          { role: "tool", kind: "code_edit", text: "StrReplace session.ts", file: "session.ts", ts: m(18.5) },
+        ],
+      },
+      {
+        id: `chat_copilot_${S_COPILOT}`,
+        agent: "Copilot",
+        ownerLogin: "bob",
+        sessionId: S_COPILOT,
+        messages: [
+          { role: "user", kind: "message", text: "add integration tests for JWT expiry and refresh rotation", ts: m(8) },
+          { role: "assistant", kind: "message", text: "Creating tests/auth.test.ts and exporting verify helpers from src/auth.ts.", ts: m(7.5) },
+          { role: "tool", kind: "code_edit", text: "replace_string_in_file auth.ts", file: "auth.ts", ts: m(7) },
+          { role: "tool", kind: "code_edit", text: "create_file auth.test.ts", file: "auth.test.ts", ts: m(6.5) },
+        ],
+      },
+    ],
+    edits: [
+      { id: "e_bob01", agent: "Cursor", ownerLogin: "bob", file: "src/auth.ts", ts: m(19), diff: "+export async function revokeSession(jti: string) { await denylist.add(jti); }\n" },
+      { id: "e_bob02", agent: "Cursor", ownerLogin: "bob", file: "src/session.ts", ts: m(18.5), diff: "+export const denylist = new Set<string>();\n" },
+      { id: "e_bob03", agent: "Copilot", ownerLogin: "bob", file: "src/auth.ts", ts: m(7), diff: "+export { verifyJwt } from './jwt';\n" },
+      { id: "e_bob04", agent: "Copilot", ownerLogin: "bob", file: "tests/auth.test.ts", ts: m(6.5), diff: "+test('rotates refresh token and rejects replay', async () => {});\n" },
+    ],
+  };
+}
+
+/**
+ * Seeds the isolated demo graph (`demo_<projectId>`) without touching the real workspace graph.
+ * Note: does NOT pollute the live `intents` cache for real workspace sessions unless `updateIntents` is set.
+ */
+async function seedDemoGraph(falkor, projectId, opts = {}) {
+  const targetId = opts.rawTarget ? String(projectId || "demo_sandbox") : demoGraphId(projectId);
+  const { client } = falkor.state;
+  const now = Date.now();
+  await client.deleteGraph(targetId).catch(() => undefined);
+  schema.forget(targetId);
+  await falkor.ensureProject(targetId);
+
+  const localProj = projectHistory(buildDemoHistory(now), { workspacePath: WS, storeText: true });
+  await writeProjection(client, targetId, localProj);
+
+  const peerProj = projectPeer(buildPeerSnapshot(now), { login: "bob", trustRowOwners: false, storeText: true });
+  await writeProjection(client, targetId, peerProj);
+
+  if (opts.updateIntents) {
+    for (const i of localProj.intents.values()) intents.remember(i);
+    for (const i of peerProj.intents.values()) intents.remember(i);
+  }
+
+  coord.configure(falkor);
+  coord.recordHeld(targetId, `Claude Code:ALICE-DESK:${S_CLAUDE}`, "src/auth.ts", now - 2 * 60_000);
+  coord.recordContention(targetId, {
+    kind: "claim_blocked",
+    file: "src/auth.ts",
+    wanter: `Cursor:BOB-LAPTOP:${S_CURSOR}`,
+    holder: `Claude Code:ALICE-DESK:${S_CLAUDE}`,
+    reason: `File \`src/auth.ts\` is locked by Claude Code. They're working on: "switch the login flow to short-lived JWT tokens with refresh rotation" (2 min ago).`,
+    ts: now - 20 * 60_000,
+    holderIntentText: "switch the login flow to short-lived JWT tokens with refresh rotation",
+  });
+  await coord.flushAll();
+
+  central.configure(falkor);
+  const decisions = [
+    central.toRow({
+      event_id: 101,
+      kind: "decision",
+      decision_id: "jwt-refresh-rotation",
+      content: "Use 15-minute stateless JWT access tokens paired with single-use rotating refresh tokens in src/auth.ts and src/session.ts.",
+      status: "accepted",
+      user: "alice",
+      agent_label: "Claude Code",
+      files: ["src/auth.ts", "src/session.ts", "src/middleware.ts"],
+      ts: new Date(now - 21 * 60_000).toISOString(),
+    }),
+    central.toRow({
+      event_id: 102,
+      kind: "decision",
+      decision_id: "auth-rate-limit",
+      content: "Enforce 10 req/min sliding-window rate limit on /api/token/refresh and login routes.",
+      status: "accepted",
+      user: "alice",
+      agent_label: "Codex",
+      files: ["src/auth.ts", "src/routes.ts"],
+      ts: new Date(now - 16 * 60_000).toISOString(),
+    }),
+  ].filter(Boolean);
+  await central.writeRows(targetId, decisions);
+
+  analytics.configure(falkor);
+  const summary = await analytics.run(targetId, { full: true });
+  falkor.notify?.(projectId, { demo: true, summary });
+  return { targetId, summary };
+}
+
+/**
+ * Drops and rebuilds a real workspace graph from its local `memory.json` + roomPeers + central JSONL.
+ */
+async function rebuildProjectGraph(falkor, projectId, opts = {}) {
+  const projects = loadRegistry().projects || [];
+  const project = projects.find((p) => p.id === projectId || p.name === projectId);
+  if (!project) throw Object.assign(new Error(`Unknown project "${projectId}"`), { status: 404 });
+  const { client } = falkor.state;
+  if (!opts.keep) {
+    await client.deleteGraph(project.id);
+    schema.forget(project.id);
+    cursor.reset(project.id);
+  }
+  await falkor.ensureProject(project.id);
+  const memory = loadMemory(project.id);
+  const history = memory.history || [];
+  const t = Date.now();
+  const result = await ingestHistory(project.id, history, project.path, { full: true });
+  const peers = Object.entries(memory.roomPeers || {});
+  for (const [key, snapshot] of peers) {
+    await ingestPeer(project.id, { snapshot, login: snapshot.login || key, trustRowOwners: key === "host" });
+  }
+  // Re-ingest Central JSONL decisions/tasks if present
+  try {
+    central.configure(falkor);
+    const { eventsPath } = require("../centralStore");
+    const fs = require("fs");
+    const centralId = project.centralProjectId || project.id;
+    const file = eventsPath(centralId);
+    if (fs.existsSync(file)) {
+      const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+      const rows = lines
+        .map((l) => {
+          try {
+            return central.toRow(JSON.parse(l));
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean);
+      if (rows.length) await central.writeRows(project.id, rows);
+    }
+  } catch {
+    /* optional central events */
+  }
+  analytics.configure(falkor);
+  const stats = await analytics.run(project.id, { full: true });
+  falkor.notify?.(project.id, { rebuilt: true, stats });
+  return {
+    projectId: project.id,
+    path: project.path,
+    events: history.length,
+    peers: peers.length,
+    ingest: result,
+    analytics: stats,
+    ms: Date.now() - t,
+  };
+}
+
+module.exports = { demoGraphId, buildDemoHistory, buildPeerSnapshot, seedDemoGraph, rebuildProjectGraph };

package/backend/lib/falkor/fixtures.js

@@ -0,0 +1,85 @@
+// Synthetic events shaped like real unifyEvent output (no user data).
+const path = require("path");
+
+// A native absolute workspace, so path handling is exercised the way it runs on each OS.
+const WS = process.platform === "win32" ? "C:\\Users\\dev\\demo" : "/home/dev/demo";
+const wsPath = (...parts) => path.join(WS, ...parts);
+// Agents sometimes report Windows paths with forward slashes; on POSIX this is the same path.
+const slashed = (p) => p.split(path.sep).join("/");
+const CLAUDE_SID = "52b29a54-d8fb-4091-ab60-463ac73c9d6c";
+const CURSOR_SID = "3e62675d-9b0f-4d99-b17d-c1d875fe98dc";
+
+let n = 0;
+function ev(fields) {
+  n += 1;
+  return {
+    id: `ev${String(n).padStart(4, "0")}`,
+    ownerLogin: "alice",
+    role: "assistant",
+    kind: "message",
+    text: "",
+    file: null,
+    path: null,
+    diff: "",
+    ...fields,
+  };
+}
+
+function demoHistory() {
+  n = 0;
+  return [
+    ev({ agent: "Claude Code", sessionId: CLAUDE_SID, ts: 1000, role: "user", text: "switch the login flow to JWT tokens" }),
+    ev({ agent: "Cursor", sessionId: CURSOR_SID, ts: 1500.685, role: "user", text: "make the navbar sticky" }),
+    ev({ agent: "Claude Code", sessionId: CLAUDE_SID, ts: 2000, role: "assistant", kind: "thinking", text: "hmm, issuer first" }),
+    ev({ agent: "Claude Code", sessionId: CLAUDE_SID, ts: 2100, role: "assistant", text: "I'll update the token issuer first." }),
+    ev({
+      agent: "Claude Code",
+      sessionId: CLAUDE_SID,
+      ts: 3000,
+      role: "tool",
+      kind: "code_edit",
+      text: "Edit auth.ts",
+      file: "auth.ts",
+      path: slashed(wsPath("src", "Auth.ts")),
+      diff: "--- a/auth.ts\n+++ b/auth.ts\n@@ -1,2 +1,3 @@\n-old\n+new\n+newer\n",
+    }),
+    ev({
+      agent: "Cursor",
+      sessionId: CURSOR_SID,
+      ts: 3500.685,
+      role: "tool",
+      kind: "code_edit",
+      text: "Write navbar.css",
+      file: "navbar.css",
+      path: wsPath("styles", "navbar.css"),
+      diff: "+.nav{position:sticky}\n",
+    }),
+    ev({ agent: "Claude Code", sessionId: CLAUDE_SID, ts: 4000, role: "user", text: "also add refresh tokens, api_key=supersecretvalue123" }),
+    ev({
+      agent: "Claude Code",
+      sessionId: CLAUDE_SID,
+      ts: 5000,
+      role: "tool",
+      kind: "code_edit",
+      text: "Edit auth.ts",
+      file: "auth.ts",
+      path: wsPath("src", "auth.ts"),
+      diff: "+refresh\n",
+    }),
+    ev({
+      agent: "Claude Code",
+      sessionId: CLAUDE_SID,
+      ts: 5100,
+      role: "tool",
+      kind: "code_edit",
+      text: "Write notes.md",
+      file: "notes.md",
+      path: path.join(path.dirname(WS), "other-repo", "notes.md"),
+      diff: "+x\n",
+    }),
+    ev({ agent: "Antigravity", sessionId: "session", ts: 6000, role: "user", text: "what files do you see" }),
+    ev({ agent: "Codex", sessionId: "codex-1", ts: 7000, role: "tool", kind: "code_edit", text: "apply_patch", file: null, path: null, diff: "" }),
+  ];
+}
+
+module.exports = { demoHistory, WS, wsPath, CLAUDE_SID, CURSOR_SID };

package/backend/lib/falkor/index.js

@@ -0,0 +1,146 @@
+const { readConfig, loadFileConfig, saveFileConfig, configPath, validUrl } = require("./config");
+const { FalkorClient } = require("./client");
+const schema = require("./schema");
+
+const state = {
+  cfg: null,
+  client: null,
+  deps: {},
+  projects: new Map(),
+  started: false,
+};
+
+function projectStats(projectId) {
+  if (!state.projects.has(projectId)) {
+    state.projects.set(projectId, {
+      schemaVersion: null,
+      needsRebuild: false,
+      lastIngestAt: null,
+      lastIngestCount: 0,
+      bufferDrops: 0,
+      droppedRows: 0,
+      pendingLinks: 0,
+      lastError: null,
+    });
+  }
+  return state.projects.get(projectId);
+}
+
+function enabled() {
+  return Boolean(state.started && state.cfg?.enabled);
+}
+
+async function ensureProject(projectId) {
+  const info = await schema.ensure(state.client, projectId);
+  const stats = projectStats(projectId);
+  stats.schemaVersion = info.schemaVersion;
+  stats.needsRebuild = info.needsRebuild;
+  return info;
+}
+
+/** After any write: refresh the UI and let the analytics job know there's new structure. */
+function notify(projectId, payload = {}) {
+  try {
+    // Not "graph": that event name already carries the dependency graph to the dashboard.
+    state.deps.sse?.emit?.("memory-graph", { workspaceId: projectId, at: Date.now(), ...payload });
+  } catch {
+    /* UI refresh is best-effort */
+  }
+  require("./bus").emit("graph-written", { projectId });
+}
+
+function maskUrl(url) {
+  return url ? url.replace(/\/\/[^@/]*@/, "//***@") : null;
+}
+
+function health() {
+  return {
+    enabled: Boolean(state.cfg?.enabled),
+    running: state.started,
+    url: maskUrl(state.cfg?.url),
+    source: state.cfg?.source || null,
+    configFile: configPath(),
+    storeText: state.cfg?.storeText ?? null,
+    breaker: state.client ? state.client.status() : null,
+    projects: Object.fromEntries(state.projects),
+  };
+}
+
+/** Starts the client and every module once; used at boot and by a runtime enable. */
+function startGraph() {
+  if (state.started) return;
+  state.client = new FalkorClient(state.cfg);
+  state.started = true;
+  for (const name of MODULES) {
+    try {
+      require(name).start(module.exports);
+    } catch (err) {
+      console.warn(`[relay-falkor] ${name} failed to start: ${err.message || err}`);
+    }
+  }
+  state.client
+    .connection()
+    .then(() => console.log(`[relay-falkor] connected ${maskUrl(state.cfg.url)}`))
+    .catch((err) => console.warn(`[relay-falkor] not reachable yet (${err.message || err}); relay continues without it`));
+}
+
+/**
+ * Turns the graph on in a running relay serve (`relay graph enable`, Mission Control's
+ * Enable button). Saves the URL so the next start remembers it.
+ */
+async function enableAtRuntime(url) {
+  const target = String(url || "").trim() || "falkor://127.0.0.1:6379";
+  if (!validUrl(target)) throw Object.assign(new Error("URL must look like falkor://host:port"), { status: 400 });
+  const saved = { ...(loadFileConfig() || {}), url: target };
+  delete saved.disabled;
+  saveFileConfig(saved);
+  if (state.started) return { ...health(), note: "already running; restart relay serve to switch databases" };
+  state.cfg = readConfig();
+  if (!state.cfg.enabled) throw Object.assign(new Error("RELAY_FALKOR_DISABLED is set in this process"), { status: 409 });
+  startGraph();
+  try {
+    await state.client.connection();
+  } catch (err) {
+    return { ...health(), warning: `saved, but FalkorDB is not reachable yet: ${err.message || err}` };
+  }
+  return health();
+}
+
+function registerRoutes(app) {
+  app.get("/api/graph/health", (_req, res) => res.json(health()));
+  app.post("/api/graph/enable", async (req, res) => {
+    // Writes this machine's config: never through the room tunnel.
+    if (require("../roomAuth").isRemoteRequest(req)) return res.status(403).json({ ok: false, reason: "local requests only" });
+    try {
+      res.json({ ok: true, ...(await enableAtRuntime(req.body?.url)) });
+    } catch (err) {
+      res.status(err.status || 500).json({ ok: false, reason: String(err.message || err) });
+    }
+  });
+  // Registered even when disabled here: a room guest without FalkorDB still reads the host's graph.
+  require("./routes").register(app, module.exports);
+}
+
+/**
+ * Wires the memory graph into relay serve. Never throws: a broken or absent
+ * FalkorDB must leave every existing relay behavior untouched.
+ */
+function init(app, deps = {}) {
+  try {
+    state.cfg = readConfig();
+    state.deps = deps;
+    registerRoutes(app);
+    if (!state.cfg.enabled) {
+      console.log("[relay-falkor] memory graph off (run `relay graph enable`, or set RELAY_FALKOR_URL)");
+      return health();
+    }
+    startGraph();
+  } catch (err) {
+    console.warn(`[relay-falkor] init failed: ${err.message || err}`);
+  }
+  return health();
+}
+
+const MODULES = ["./ingest", "./coord", "./central", "./analytics"];
+
+module.exports = { init, state, enabled, ensureProject, projectStats, health, notify, enableAtRuntime };

package/backend/lib/falkor/ingest.js

@@ -0,0 +1,233 @@
+const { bus } = require("./bus");
+const cursor = require("./cursor");
+const intents = require("./intents");
+const { projectHistory, projectPatches, projectPeer } = require("./project");
+const { writeProjection } = require("./write");
+
+const DEBOUNCE_MS = 2000;
+const pending = new Map();
+const running = new Map();
+let api = null;
+
+function log(projectId, msg) {
+  console.log(`[relay-falkor] ${projectId}: ${msg}`);
+}
+
+// The cursor says what we sent; the graph's Meta.lastIngestAt says what it kept. RDB
+// snapshots can lose the last few seconds, and a FalkorDB can be wiped or swapped,
+// so a cursor newer than the graph means re-send everything (MERGE keeps it idempotent).
+const SNAPSHOT_GRACE_MS = 5000;
+const reconciled = new Set();
+
+function cursorFor(projectId, info, opts) {
+  const cur = cursor.load(projectId);
+  if (opts.full) return { ...cur, seen: [] };
+  if (!reconciled.has(projectId)) {
+    reconciled.add(projectId);
+    if (cur.seen.length && cur.updatedAt > (info?.lastIngestAt || 0) + SNAPSHOT_GRACE_MS) {
+      log(projectId, "graph is behind the ingest cursor (lost snapshot or new database); re-sending history");
+      return { ...cur, seen: [] };
+    }
+  }
+  return cur;
+}
+
+/** Projects + writes everything in `history` the cursor hasn't confirmed yet. */
+async function ingestHistory(projectId, history, workspacePath, opts = {}) {
+  const { client, state } = api;
+  const stats = api.projectStats(projectId);
+  const info = await api.ensureProject(projectId);
+  const cur = cursorFor(projectId, info, opts);
+  const seen = cursor.seenSet(cur);
+  const projection = projectHistory(history, {
+    workspacePath,
+    isNew: (id) => !seen.has(id),
+    storeText: state.cfg.storeText,
+  });
+  for (const info of projection.intents.values()) intents.remember(info);
+  if (!projection.sessions.length && !projection.turns.length && !projection.edits.length) return { skipped: true };
+
+  const t = Date.now();
+  const result = await writeProjection(client, projectId, projection);
+  // Stamp the graph before the cursor, so the cursor can never look older than what the graph holds.
+  await client.write(projectId, "MERGE (m:Meta {key:'meta'}) SET m.lastIngestAt = $now RETURN 1", { now: Date.now() });
+  cursor.commit(projectId, cur, (history || []).map((e) => e.id).filter(Boolean));
+  stats.lastIngestAt = Date.now();
+  stats.lastIngestCount = result.turnsCreated + result.editsCreated;
+  stats.droppedRows += projection.dropped;
+  stats.lastError = null;
+  log(projectId, `+${result.turnsCreated} turns, +${result.editsCreated} edits, ${result.sessions} sessions (${Date.now() - t}ms)`);
+  api.notify?.(projectId, result);
+  return result;
+}
+
+function schedule(projectId, payload) {
+  try {
+    const projected = projectHistory(payload.history, {
+      workspacePath: payload.workspacePath,
+      isNew: () => false,
+      storeText: false,
+    });
+    for (const info of projected.intents.values()) intents.remember(info);
+  } catch {
+    /* best-effort immediate intent cache update */
+  }
+  const entry = pending.get(projectId) || {};
+  entry.payload = payload;
+  clearTimeout(entry.timer);
+  entry.timer = setTimeout(() => flush(projectId), DEBOUNCE_MS);
+  if (entry.timer.unref) entry.timer.unref();
+  pending.set(projectId, entry);
+}
+
+async function flush(projectId) {
+  const entry = pending.get(projectId);
+  if (!entry) return;
+  if (running.get(projectId)) {
+    schedule(projectId, entry.payload);
+    return;
+  }
+  pending.delete(projectId);
+  if (!api.client.available()) return;
+  running.set(projectId, true);
+  try {
+    const { history, workspacePath } = entry.payload;
+    await ingestHistory(projectId, history, workspacePath);
+  } catch (err) {
+    // Replayable: the cursor wasn't committed, so the next sync re-sends these events.
+    api.projectStats(projectId).lastError = String(err.message || err);
+    if (!err.breaker) log(projectId, `ingest failed: ${err.message || err}`);
+  } finally {
+    running.delete(projectId);
+  }
+}
+
+// ---- patches: not replayable from history, so failed batches go back into a bounded buffer
+const PATCH_BUFFER_MAX = 2000;
+const patchQueues = new Map();
+
+function queuePatch(projectId, patch) {
+  const q = patchQueues.get(projectId) || { items: [], timer: null };
+  q.items.push(patch);
+  if (q.items.length > PATCH_BUFFER_MAX) {
+    q.items.splice(0, q.items.length - PATCH_BUFFER_MAX);
+    api.projectStats(projectId).bufferDrops += 1;
+  }
+  if (!q.timer) {
+    q.timer = setTimeout(() => flushPatches(projectId), 1000);
+    if (q.timer.unref) q.timer.unref();
+  }
+  patchQueues.set(projectId, q);
+}
+
+async function flushPatches(projectId) {
+  const q = patchQueues.get(projectId);
+  if (!q) return;
+  q.timer = null;
+  const items = q.items.splice(0);
+  if (!items.length) return;
+  const retry = () => {
+    q.items.unshift(...items);
+    q.timer = setTimeout(() => flushPatches(projectId), api.state.cfg.breakerCooldownMs);
+    if (q.timer.unref) q.timer.unref();
+  };
+  if (!api.client.available()) return retry();
+  try {
+    await api.ensureProject(projectId);
+    const result = await writeProjection(api.client, projectId, projectPatches(items, { storeText: api.state.cfg.storeText }));
+    if (result.editsCreated) log(projectId, `+${result.editsCreated} patch edits`);
+    api.notify?.(projectId, result);
+  } catch (err) {
+    api.projectStats(projectId).lastError = String(err.message || err);
+    retry();
+  }
+}
+
+// ---- room peers: debounced per (project, peer); content-addressed keys make re-pushes no-ops
+const peerSeen = new Map();
+const PEER_SEEN_MAX = 20000;
+
+function seenFor(projectId) {
+  if (!peerSeen.has(projectId)) peerSeen.set(projectId, new Set());
+  return peerSeen.get(projectId);
+}
+
+async function ingestPeer(projectId, { snapshot, login, trustRowOwners }) {
+  await api.ensureProject(projectId);
+  const seen = seenFor(projectId);
+  const projection = projectPeer(snapshot, {
+    login,
+    trustRowOwners,
+    isNew: (id) => !seen.has(id),
+    storeText: api.state.cfg.storeText,
+  });
+  for (const info of projection.intents.values()) intents.remember(info);
+  if (!projection.turns.length && !projection.edits.length) return { skipped: true };
+  const result = await writeProjection(api.client, projectId, projection);
+  for (const t of projection.turns) seen.add(`peer_${t.turnKey}`);
+  for (const e of projection.edits) seen.add(String(e.editKey).replace(/^e_/, ""));
+  for (const e of projection.edits) seen.add(e.editKey);
+  if (seen.size > PEER_SEEN_MAX) peerSeen.set(projectId, new Set([...seen].slice(-PEER_SEEN_MAX / 2)));
+  log(projectId, `peer ${login}: +${result.turnsCreated} turns, +${result.editsCreated} edits`);
+  api.notify?.(projectId, { peer: login, ...result });
+  return result;
+}
+
+const peerTimers = new Map();
+function schedulePeer(projectId, payload) {
+  try {
+    const projected = projectPeer(payload.snapshot, {
+      login: payload.login,
+      trustRowOwners: payload.trustRowOwners,
+      isNew: () => false,
+      storeText: false,
+    });
+    for (const info of projected.intents.values()) intents.remember(info);
+  } catch {
+    /* best-effort immediate intent cache update */
+  }
+  const key = `${projectId}|${payload.login}`;
+  const entry = peerTimers.get(key) || {};
+  entry.payload = payload;
+  clearTimeout(entry.timer);
+  entry.timer = setTimeout(async () => {
+    peerTimers.delete(key);
+    if (!api.client.available()) return;
+    try {
+      await ingestPeer(projectId, entry.payload);
+    } catch (err) {
+      api.projectStats(projectId).lastError = String(err.message || err);
+    }
+  }, DEBOUNCE_MS);
+  if (entry.timer.unref) entry.timer.unref();
+  peerTimers.set(key, entry);
+}
+
+function start(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+  bus.on("history", ({ project, workspacePath, memory }) => {
+    if (!project?.id || !Array.isArray(memory?.history)) return;
+    schedule(project.id, { history: memory.history, workspacePath: workspacePath || project.path });
+  });
+  bus.on("patch", ({ projectId, patch }) => {
+    if (projectId && patch) queuePatch(projectId, patch);
+  });
+  bus.on("peer", ({ projectId, key, login, snapshot }) => {
+    if (!projectId || !snapshot) return;
+    // A guest's "host" bucket aggregates several people, so its row owners are meaningful;
+    // a single peer's push is forced to that peer's authenticated login.
+    const trustRowOwners = key === "host";
+    schedulePeer(projectId, { snapshot, login: login || key, trustRowOwners });
+  });
+}
+
+function configure(falkor) {
+  api = { ...falkor, client: falkor.state.client, state: falkor.state };
+}
+
+/** Forget per-process state, as a restart would. */
+function _resetForTests() {
+  reconciled.clear();
+}
+
+module.exports = { start, configure, ingestHistory, ingestPeer, flush, flushPatches, _resetForTests };