@omg-dev/server 0.4.24

package/src/test/subscriptions.test.ts

@@ -0,0 +1,878 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test"
+import { defineSchema, collection, fields, schemaToSQL, type Schema } from "@omg-dev/schema"
+import { openDb, setDbInstance, markScoped, type VibesDb } from "../db.ts"
+import {
+  addSubClient,
+  removeSubClient,
+  handleSubMessage,
+  notifyCollectionChange,
+  notifyRowChange,
+  subClientCount,
+  subscriptionCount,
+  setSubscriptionSchema,
+  setSubscriptionRingCap,
+  setMaxSubsPerClient,
+  _resetSubscriptionState,
+  _currentSeq,
+  type SubClient,
+  type SubServerMessage,
+} from "../subscriptions.ts"
+
+// ── Fixture ──────────────────────────────────────────────────────────────────
+
+function makeSchema(): Schema {
+  return defineSchema({
+    collections: {
+      // global/public — exercises the unscoped (no _owner) subscription path
+      tasks: collection({
+        fields: {
+          title: fields.string(),
+          done: fields.boolean(),
+        },
+      }).scoped("global"),
+      // user-scoped — exercises _owner filtering
+      notes: collection({
+        fields: {
+          body: fields.string(),
+        },
+      }).scoped("user"),
+    },
+  })
+}
+
+let db: VibesDb
+let schema: Schema
+
+function makeClient(userId: string | null = null): SubClient & { sent: SubServerMessage[]; sentRaw: string[] } {
+  const sent: SubServerMessage[] = []
+  const sentRaw: string[] = []
+  return {
+    readyState: 1,
+    ctx: { userId },
+    sent,
+    sentRaw,
+    send(data: string) {
+      sentRaw.push(data)
+      sent.push(JSON.parse(data) as SubServerMessage)
+    },
+  }
+}
+
+beforeEach(() => {
+  _resetSubscriptionState()
+  schema = makeSchema()
+  db = openDb(":memory:")
+  setDbInstance(db)
+  // markScoped is normally invoked by registerScopes during migrate; do it
+  // here directly since this test bypasses the migrator.
+  markScoped("notes")
+  for (const sql of schemaToSQL(schema)) db.raw().exec(sql)
+  setSubscriptionSchema(schema)
+})
+
+afterEach(() => {
+  _resetSubscriptionState()
+  setSubscriptionSchema(null)
+  db.close()
+})
+
+// ── Registry lifecycle ───────────────────────────────────────────────────────
+
+describe("subscriptions — registry lifecycle", () => {
+  it("addSubClient / removeSubClient track client count", () => {
+    const c1 = makeClient(), c2 = makeClient()
+    expect(subClientCount()).toBe(0)
+    addSubClient(c1)
+    addSubClient(c2)
+    expect(subClientCount()).toBe(2)
+    removeSubClient(c1)
+    expect(subClientCount()).toBe(1)
+    removeSubClient(c2)
+    expect(subClientCount()).toBe(0)
+  })
+
+  it("addSubClient is idempotent for the same client instance", () => {
+    const c = makeClient()
+    addSubClient(c)
+    addSubClient(c)
+    expect(subClientCount()).toBe(1)
+  })
+
+  it("removeSubClient on unknown client is a no-op", () => {
+    removeSubClient(makeClient())
+    expect(subClientCount()).toBe(0)
+  })
+})
+
+// ── Sub / unsub / snapshot ───────────────────────────────────────────────────
+
+describe("subscriptions — sub / unsub", () => {
+  it("sub emits a snapshot frame with all rows on a global collection", async () => {
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "first", 0, "2026-01-01", "2026-01-01")
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t2", "second", 1, "2026-01-02", "2026-01-02")
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+
+    expect(c.sent).toHaveLength(1)
+    const msg = c.sent[0]
+    expect(msg.type).toBe("snapshot")
+    if (msg.type !== "snapshot") throw new Error("expected snapshot")
+    expect(msg.subId).toBe("a")
+    expect(msg.collection).toBe("tasks")
+    expect(msg.rows).toHaveLength(2)
+    expect(subscriptionCount("tasks")).toBe(1)
+  })
+
+  it("sub on a scoped collection filters by client.ctx.userId", async () => {
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n1", "alice's note", "alice", "2026-01-01", "2026-01-01")
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n2", "bob's note", "bob", "2026-01-02", "2026-01-02")
+
+    const alice = makeClient("alice")
+    addSubClient(alice)
+    await handleSubMessage(alice, JSON.stringify({ op: "sub", subId: "x", collection: "notes" }))
+
+    expect(alice.sent).toHaveLength(1)
+    const msg = alice.sent[0]
+    if (msg.type !== "snapshot") throw new Error("expected snapshot")
+    expect(msg.rows).toHaveLength(1)
+    expect(msg.rows[0].id).toBe("n1")
+    expect(msg.rows[0].body).toBe("alice's note")
+  })
+
+  it("sub on a scoped collection with no auth emits an error frame, not the rows", async () => {
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n1", "owned", "alice", "2026-01-01", "2026-01-01")
+
+    const anon = makeClient(null)
+    addSubClient(anon)
+    await handleSubMessage(anon, JSON.stringify({ op: "sub", subId: "x", collection: "notes" }))
+
+    expect(anon.sent).toHaveLength(1)
+    const msg = anon.sent[0]
+    expect(msg.type).toBe("error")
+    if (msg.type !== "error") throw new Error("expected error")
+    expect(msg.code).toBe("auth_required")
+    expect(msg.message).toContain("notes")
+  })
+
+  it("unsub removes the subscription so subsequent notifies are not delivered", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    c.sent.length = 0
+    await handleSubMessage(c, JSON.stringify({ op: "unsub", subId: "a" }))
+
+    expect(subscriptionCount("tasks")).toBe(0)
+    await notifyCollectionChange("tasks")
+    expect(c.sent).toHaveLength(0)
+  })
+
+  it("duplicate subId on the same client yields an error frame", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    c.sent.length = 0
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+
+    expect(c.sent).toHaveLength(1)
+    const msg = c.sent[0]
+    if (msg.type !== "error") throw new Error("expected error")
+    expect(msg.code).toBe("duplicate_subId")
+  })
+
+  it("bad json / missing op / unknown op all emit an error frame", async () => {
+    const c = makeClient()
+    addSubClient(c)
+
+    await handleSubMessage(c, "{not json")
+    await handleSubMessage(c, JSON.stringify({ subId: "a", collection: "tasks" }))
+    await handleSubMessage(c, JSON.stringify({ op: "garbage", subId: "a" }))
+
+    expect(c.sent).toHaveLength(3)
+    expect((c.sent[0] as { type: string; code: string }).code).toBe("bad_json")
+    expect((c.sent[1] as { type: string; code: string }).code).toBe("bad_shape")
+    expect((c.sent[2] as { type: string; code: string }).code).toBe("unknown_op")
+  })
+
+  it("sub before addSubClient yields client_not_registered", async () => {
+    const c = makeClient()
+    // intentionally NOT calling addSubClient
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    expect(c.sent).toHaveLength(1)
+    if (c.sent[0].type !== "error") throw new Error("expected error")
+    expect(c.sent[0].code).toBe("client_not_registered")
+  })
+})
+
+// ── Fan-out on write ─────────────────────────────────────────────────────────
+
+describe("subscriptions — notifyCollectionChange fan-out", () => {
+  it("re-sends the snapshot to every subscriber of the affected collection", async () => {
+    const c1 = makeClient(), c2 = makeClient(), unrelated = makeClient()
+    addSubClient(c1); addSubClient(c2); addSubClient(unrelated)
+    await handleSubMessage(c1, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(c2, JSON.stringify({ op: "sub", subId: "b", collection: "tasks" }))
+    await handleSubMessage(unrelated, JSON.stringify({ op: "sub", subId: "c", collection: "notes" }))
+    // Tank the initial snapshots so we can isolate the fan-out.
+    c1.sent.length = 0; c2.sent.length = 0; unrelated.sent.length = 0
+
+    // Note: scoped notes sub with userId=null errored on subscribe, so it's
+    // not actually in the registry. That's fine — the only thing we care
+    // about here is that a tasks-only notify doesn't reach an unrelated sub.
+    // Re-test that path explicitly with a valid scoped sub below.
+
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "x", 0, "2026-01-01", "2026-01-01")
+    await notifyCollectionChange("tasks")
+
+    expect(c1.sent).toHaveLength(1)
+    expect(c2.sent).toHaveLength(1)
+    expect((c1.sent[0] as { type: string }).type).toBe("snapshot")
+    expect((c2.sent[0] as { type: string }).type).toBe("snapshot")
+  })
+
+  it("does not deliver to clients subscribed only to other collections", async () => {
+    const tasksSub = makeClient()
+    const notesSub = makeClient("alice")
+    addSubClient(tasksSub); addSubClient(notesSub)
+    await handleSubMessage(tasksSub, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(notesSub, JSON.stringify({ op: "sub", subId: "b", collection: "notes" }))
+    tasksSub.sent.length = 0; notesSub.sent.length = 0
+
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "x", 0, "2026-01-01", "2026-01-01")
+    await notifyCollectionChange("tasks")
+
+    expect(tasksSub.sent).toHaveLength(1)
+    expect(notesSub.sent).toHaveLength(0)
+  })
+
+  it("evicts a client whose readyState is 3 (closed) at fan-out time", async () => {
+    const open = makeClient(), closed = makeClient()
+    addSubClient(open); addSubClient(closed)
+    await handleSubMessage(open, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(closed, JSON.stringify({ op: "sub", subId: "b", collection: "tasks" }))
+
+    closed.readyState = 3
+    await notifyCollectionChange("tasks")
+
+    // open still registered, closed evicted.
+    expect(subClientCount()).toBe(1)
+    expect(subscriptionCount("tasks")).toBe(1)
+  })
+
+  it("decodes booleans to true/false in the snapshot rows (REST-shape)", async () => {
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "open", 0, "2026-01-01", "2026-01-01")
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t2", "done", 1, "2026-01-02", "2026-01-02")
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+
+    const msg = c.sent[0]
+    if (msg.type !== "snapshot") throw new Error("expected snapshot")
+    const byId = new Map(msg.rows.map(r => [r.id, r]))
+    expect(byId.get("t1")?.done).toBe(false)
+    expect(byId.get("t2")?.done).toBe(true)
+  })
+
+  it("survives a send() that throws — evicts the client without crashing the fan-out", async () => {
+    const ok = makeClient()
+    const bad: SubClient & { sent: SubServerMessage[] } = {
+      readyState: 1,
+      ctx: { userId: null },
+      sent: [],
+      send() { throw new Error("socket exploded") },
+    } as SubClient & { sent: SubServerMessage[] }
+
+    addSubClient(ok); addSubClient(bad)
+    await handleSubMessage(ok, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(bad, JSON.stringify({ op: "sub", subId: "b", collection: "tasks" }))
+    ok.sent.length = 0
+
+    // The fan-out will try `bad` first or second; either way the iteration
+    // must keep going so `ok` still receives its snapshot.
+    await notifyCollectionChange("tasks")
+    expect(ok.sent).toHaveLength(1)
+    // bad has been evicted because send() threw.
+    expect(subClientCount()).toBe(1)
+  })
+})
+
+// ── Predicate filter (Phase 2) ───────────────────────────────────────────────
+
+describe("subscriptions — predicate filter", () => {
+  it("filters initial snapshot by a top-level eq predicate", async () => {
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "open one", 0, "2026-01-01", "2026-01-01")
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t2", "closed", 1, "2026-01-02", "2026-01-02")
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t3", "open two", 0, "2026-01-03", "2026-01-03")
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+    }))
+
+    const msg = c.sent[0]
+    if (msg.type !== "snapshot") throw new Error("expected snapshot, got " + JSON.stringify(msg))
+    const ids = msg.rows.map(r => r.id).sort()
+    expect(ids).toEqual(["t1", "t3"])
+  })
+
+  it("combines predicate with scope filter on user-scoped collections", async () => {
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n1", "alice high", "alice", "2026-01-01", "2026-01-01")
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n2", "alice low", "alice", "2026-01-02", "2026-01-02")
+    db.raw().prepare("INSERT INTO notes (id, body, _owner, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("n3", "bob high", "bob", "2026-01-03", "2026-01-03")
+
+    const alice = makeClient("alice")
+    addSubClient(alice)
+    await handleSubMessage(alice, JSON.stringify({
+      op: "sub", subId: "a", collection: "notes",
+      where: { op: "like", column: "body", pattern: "%high%" },
+    }))
+
+    const msg = alice.sent[0]
+    if (msg.type !== "snapshot") throw new Error("expected snapshot")
+    const ids = msg.rows.map(r => r.id)
+    // Only alice's "high" note — bob's row is excluded by _owner, alice's
+    // "low" row is excluded by the predicate.
+    expect(ids).toEqual(["n1"])
+  })
+
+  it("rejects a malformed predicate with bad_predicate, leaves no subscription", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "regex", column: "title", pattern: ".*" },
+    }))
+
+    const msg = c.sent[0]
+    if (msg.type !== "error") throw new Error("expected error")
+    expect(msg.code).toBe("bad_predicate")
+    expect(subscriptionCount("tasks")).toBe(0)
+  })
+
+  it("rejects a predicate referencing an unknown column", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "nonexistent", value: 1 },
+    }))
+
+    const msg = c.sent[0]
+    if (msg.type !== "error") throw new Error("expected error")
+    expect(msg.code).toBe("bad_predicate")
+    expect(msg.message).toContain("unknown column")
+  })
+
+  it("rejects an unknown collection (whitelist via schema)", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "DROP TABLE tasks",
+    }))
+
+    const msg = c.sent[0]
+    if (msg.type !== "error") throw new Error("expected error")
+    expect(msg.code).toBe("unknown_collection")
+  })
+
+  it("notifyCollectionChange (fallback path) still re-applies the predicate on the re-snapshot", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+    }))
+    c.sent.length = 0
+
+    // Insert a row that does NOT match the predicate.
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "finished", 1, "2026-01-01", "2026-01-01")
+    await notifyCollectionChange("tasks")
+
+    // Subscriber DOES get a re-snapshot (Phase 3 will narrow this), but its
+    // contents respect the predicate: row t1 (done=true) is filtered out.
+    expect(c.sent).toHaveLength(1)
+    if (c.sent[0].type !== "snapshot") throw new Error("expected snapshot")
+    expect(c.sent[0].rows).toEqual([])
+
+    // Now insert a matching row.
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t2", "open", 0, "2026-01-02", "2026-01-02")
+    await notifyCollectionChange("tasks")
+
+    if (c.sent[1].type !== "snapshot") throw new Error("expected snapshot")
+    expect(c.sent[1].rows.map(r => r.id)).toEqual(["t2"])
+  })
+})
+
+// ── Delta computation (Phase 3) ──────────────────────────────────────────────
+
+describe("subscriptions — notifyRowChange delta matrix", () => {
+  // Helpers — build encoded (storage-shape) rows since notifyRowChange
+  // takes raw rows the way auto-crud does.
+  const t = (id: string, title: string, done: 0 | 1): Record<string, unknown> => ({
+    id, title, done, created_at: "2026-01-01", updated_at: "2026-01-01",
+  })
+  const n = (id: string, body: string, owner: string): Record<string, unknown> => ({
+    id, body, _owner: owner, created_at: "2026-01-01", updated_at: "2026-01-01",
+  })
+
+  it("insert: emits an insert delta to subs whose predicate matches the new row", async () => {
+    const yes = makeClient(), no = makeClient()
+    addSubClient(yes); addSubClient(no)
+    await handleSubMessage(yes, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+    }))
+    await handleSubMessage(no, JSON.stringify({
+      op: "sub", subId: "b", collection: "tasks",
+      where: { op: "eq", column: "done", value: true },
+    }))
+    yes.sent.length = 0; no.sent.length = 0
+
+    await notifyRowChange("tasks", "insert", null, t("t1", "x", 0))
+
+    expect(yes.sent).toHaveLength(1)
+    expect(no.sent).toHaveLength(0)
+    const m = yes.sent[0]
+    if (m.type !== "delta") throw new Error("expected delta")
+    expect(m.op).toBe("insert")
+    if (m.op !== "insert") throw new Error("unreachable")
+    expect(m.row.id).toBe("t1")
+    expect(m.row.done).toBe(false) // decoded
+  })
+
+  it("subs with no predicate get every insert", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    c.sent.length = 0
+
+    await notifyRowChange("tasks", "insert", null, t("t1", "x", 0))
+    await notifyRowChange("tasks", "insert", null, t("t2", "y", 1))
+
+    expect(c.sent).toHaveLength(2)
+    const ids = c.sent.map(m => {
+      if (m.type !== "delta" || m.op !== "insert") throw new Error("bad")
+      return m.row.id
+    })
+    expect(ids).toEqual(["t1", "t2"])
+  })
+
+  it("update: matrix — out→in emits insert, in→in emits update, in→out emits delete, out→out is silent", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+    }))
+    c.sent.length = 0
+
+    // out (done=1) → in (done=0): insert
+    await notifyRowChange("tasks", "update", t("r1", "x", 1), t("r1", "x", 0))
+    // in (done=0) → in (done=0): update (other column changed)
+    await notifyRowChange("tasks", "update", t("r2", "old", 0), t("r2", "new", 0))
+    // in (done=0) → out (done=1): delete
+    await notifyRowChange("tasks", "update", t("r3", "x", 0), t("r3", "x", 1))
+    // out → out: silent
+    await notifyRowChange("tasks", "update", t("r4", "a", 1), t("r4", "b", 1))
+
+    expect(c.sent).toHaveLength(3)
+    const summarize = (m: SubServerMessage) => {
+      if (m.type !== "delta") throw new Error("expected delta")
+      if (m.op === "delete") return `delete ${m.id}`
+      return `${m.op} ${m.row.id}`
+    }
+    expect(c.sent.map(summarize)).toEqual([
+      "insert r1",
+      "update r2",
+      "delete r3",
+    ])
+  })
+
+  it("delete: emits delete delta with id only when the row was in the read set", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+    }))
+    c.sent.length = 0
+
+    // In-set row → delete delta.
+    await notifyRowChange("tasks", "delete", t("r1", "x", 0), null)
+    // Out-of-set row → no delta.
+    await notifyRowChange("tasks", "delete", t("r2", "x", 1), null)
+
+    expect(c.sent).toHaveLength(1)
+    const m = c.sent[0]
+    if (m.type !== "delta" || m.op !== "delete") throw new Error("expected delete delta")
+    expect(m.id).toBe("r1")
+  })
+
+  it("scope: deltas only reach subs whose ctx.userId matches the row's _owner", async () => {
+    const alice = makeClient("alice")
+    const bob = makeClient("bob")
+    addSubClient(alice); addSubClient(bob)
+    await handleSubMessage(alice, JSON.stringify({ op: "sub", subId: "a", collection: "notes" }))
+    await handleSubMessage(bob, JSON.stringify({ op: "sub", subId: "b", collection: "notes" }))
+    alice.sent.length = 0; bob.sent.length = 0
+
+    await notifyRowChange("notes", "insert", null, n("n1", "alice only", "alice"))
+
+    expect(alice.sent).toHaveLength(1)
+    expect(bob.sent).toHaveLength(0)
+  })
+
+  it("scope: anonymous client on a scoped collection never receives any delta", async () => {
+    const anon = makeClient(null)
+    addSubClient(anon)
+    // Anon sub on scoped collection errors during subscribe (auth_required),
+    // so the sub is NOT registered. notifyRowChange has nothing to send.
+    await handleSubMessage(anon, JSON.stringify({ op: "sub", subId: "a", collection: "notes" }))
+    expect(subscriptionCount("notes")).toBe(0)
+    anon.sent.length = 0
+
+    await notifyRowChange("notes", "insert", null, n("n1", "x", "alice"))
+    expect(anon.sent).toHaveLength(0)
+  })
+
+  it("scope: a delete from a different owner does NOT leak the row id to other subs", async () => {
+    const alice = makeClient("alice")
+    const bob = makeClient("bob")
+    addSubClient(alice); addSubClient(bob)
+    await handleSubMessage(alice, JSON.stringify({ op: "sub", subId: "a", collection: "notes" }))
+    await handleSubMessage(bob, JSON.stringify({ op: "sub", subId: "b", collection: "notes" }))
+    alice.sent.length = 0; bob.sent.length = 0
+
+    // Bob deletes one of his rows. Alice MUST NOT receive that delta —
+    // it would let her enumerate bob's row ids.
+    await notifyRowChange("notes", "delete", n("n1", "bob private", "bob"), null)
+
+    expect(bob.sent).toHaveLength(1)
+    expect(alice.sent).toHaveLength(0)
+  })
+
+  it("delta payload uses decoded shape (booleans as true/false)", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    c.sent.length = 0
+
+    await notifyRowChange("tasks", "insert", null, t("t1", "x", 1))
+    const m = c.sent[0]
+    if (m.type !== "delta" || m.op !== "insert") throw new Error("expected insert")
+    expect(m.row.done).toBe(true)
+  })
+
+  it("zero subs on a collection is a fast no-op", async () => {
+    // notifyRowChange should return Promise.resolve() without touching the
+    // DB when nobody's listening. We can't assert "no DB touched" directly
+    // but we can assert the promise resolves and no sends happen.
+    await notifyRowChange("tasks", "insert", null, t("t1", "x", 0))
+    // No assertions beyond "did not throw" — just exercising the early-out.
+    expect(subscriptionCount("tasks")).toBe(0)
+  })
+})
+
+// ── Sequence numbers + resume (Phase 4) ──────────────────────────────────────
+
+describe("subscriptions — seq tagging + resume", () => {
+  const t = (id: string, title: string, done: 0 | 1): Record<string, unknown> => ({
+    id, title, done, created_at: "2026-01-01", updated_at: "2026-01-01",
+  })
+
+  it("snapshot frames carry a seq equal to the current global counter", async () => {
+    db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+      .run("t1", "x", 0, "2026-01-01", "2026-01-01")
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    const m = c.sent[0]
+    if (m.type !== "snapshot") throw new Error("expected snapshot")
+    expect(m.seq).toBe(0) // no writes through notifyRowChange yet
+  })
+
+  it("delta frames carry strictly increasing seq across writes", async () => {
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    c.sent.length = 0
+
+    await notifyRowChange("tasks", "insert", null, t("r1", "a", 0))
+    await notifyRowChange("tasks", "insert", null, t("r2", "b", 0))
+    await notifyRowChange("tasks", "insert", null, t("r3", "c", 0))
+
+    expect(c.sent).toHaveLength(3)
+    const seqs = c.sent.map(m => {
+      if (m.type !== "delta") throw new Error("expected delta")
+      return m.seq
+    })
+    expect(seqs[1]).toBeGreaterThan(seqs[0])
+    expect(seqs[2]).toBeGreaterThan(seqs[1])
+  })
+
+  it("ring records writes even with zero subscribers, allowing later resume", async () => {
+    // No subs yet — but the ring should still capture the write.
+    await notifyRowChange("tasks", "insert", null, t("r1", "x", 0))
+    await notifyRowChange("tasks", "insert", null, t("r2", "y", 0))
+    const seqAfter = _currentSeq()
+    expect(seqAfter).toBe(2)
+
+    // Now a client subscribes with resumeFromSeq=0 — should replay both.
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks", resumeFromSeq: 0,
+    }))
+
+    // Two delta frames, then a resumed ack.
+    const types = c.sent.map(m => m.type)
+    expect(types).toEqual(["delta", "delta", "resumed"])
+    const ack = c.sent[2]
+    if (ack.type !== "resumed") throw new Error("expected resumed")
+    expect(ack.fromSeq).toBe(0)
+    expect(ack.replayed).toBe(2)
+    expect(ack.toSeq).toBe(seqAfter)
+  })
+
+  it("resume from current seq returns 'resumed' with 0 replayed (no-op catch-up)", async () => {
+    await notifyRowChange("tasks", "insert", null, t("r1", "x", 0))
+    const seqAfter = _currentSeq()
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks", resumeFromSeq: seqAfter,
+    }))
+
+    expect(c.sent).toHaveLength(1)
+    const m = c.sent[0]
+    if (m.type !== "resumed") throw new Error("expected resumed")
+    expect(m.replayed).toBe(0)
+  })
+
+  it("falls back to a fresh snapshot when resume gap exceeds the ring cap", async () => {
+    // Cap=2, four writes → ring holds seq=3,4. Resuming from seq=1 means
+    // we need events 2,3,4 but seq=2 has been evicted — must fall back.
+    setSubscriptionRingCap(2)
+    await notifyRowChange("tasks", "insert", null, t("r1", "a", 0))
+    await notifyRowChange("tasks", "insert", null, t("r2", "b", 0))
+    await notifyRowChange("tasks", "insert", null, t("r3", "c", 0))
+    await notifyRowChange("tasks", "insert", null, t("r4", "d", 0))
+
+    // Persist the rows to the DB so the snapshot fallback has something
+    // to return — notifyRowChange doesn't write through.
+    for (const id of ["r1", "r2", "r3", "r4"]) {
+      db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+        .run(id, id, 0, "2026-01-01", "2026-01-01")
+    }
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks", resumeFromSeq: 1,
+    }))
+
+    expect(c.sent).toHaveLength(1)
+    const m = c.sent[0]
+    expect(m.type).toBe("snapshot")
+    if (m.type !== "snapshot") throw new Error("expected snapshot")
+    expect(m.rows.map(r => r.id).sort()).toEqual(["r1", "r2", "r3", "r4"])
+  })
+
+  it("replay respects the sub's predicate (events outside the predicate are skipped)", async () => {
+    // Mix of done=true and done=false writes.
+    await notifyRowChange("tasks", "insert", null, t("r1", "x", 0))
+    await notifyRowChange("tasks", "insert", null, t("r2", "y", 1))
+    await notifyRowChange("tasks", "insert", null, t("r3", "z", 0))
+
+    const c = makeClient()
+    addSubClient(c)
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks",
+      where: { op: "eq", column: "done", value: false },
+      resumeFromSeq: 0,
+    }))
+
+    // Should replay r1 and r3 (done=false), skip r2.
+    const deltas = c.sent.filter(m => m.type === "delta")
+    expect(deltas).toHaveLength(2)
+    const ids = deltas.map(m => {
+      if (m.type !== "delta" || m.op !== "insert") throw new Error("bad")
+      return m.row.id
+    })
+    expect(ids).toEqual(["r1", "r3"])
+    const ack = c.sent.at(-1)
+    if (ack?.type !== "resumed") throw new Error("expected resumed ack")
+    expect(ack.replayed).toBe(2)
+  })
+
+  it("replay respects scope — cross-tenant ring entries are dropped", async () => {
+    const aliceRow = (id: string, body: string): Record<string, unknown> => ({
+      id, body, _owner: "alice", created_at: "2026-01-01", updated_at: "2026-01-01",
+    })
+    const bobRow = (id: string, body: string): Record<string, unknown> => ({
+      id, body, _owner: "bob", created_at: "2026-01-01", updated_at: "2026-01-01",
+    })
+
+    await notifyRowChange("notes", "insert", null, aliceRow("n1", "alice"))
+    await notifyRowChange("notes", "insert", null, bobRow("n2", "bob"))
+
+    const alice = makeClient("alice")
+    addSubClient(alice)
+    await handleSubMessage(alice, JSON.stringify({
+      op: "sub", subId: "a", collection: "notes", resumeFromSeq: 0,
+    }))
+
+    // Should replay n1 only (alice's row), then resumed.
+    const deltas = alice.sent.filter(m => m.type === "delta")
+    expect(deltas).toHaveLength(1)
+    if (deltas[0].type !== "delta" || deltas[0].op !== "insert") throw new Error("bad")
+    expect(deltas[0].row.id).toBe("n1")
+  })
+
+  it("ring respects RING_CAP — only the most recent N entries are kept", async () => {
+    setSubscriptionRingCap(3)
+    for (let i = 1; i <= 5; i++) {
+      await notifyRowChange("tasks", "insert", null, t(`r${i}`, "x", 0))
+    }
+    // Ring should now hold seqs 3, 4, 5 only.
+
+    const c = makeClient()
+    addSubClient(c)
+    // Resume from seq 2 — the entry with seq=3 is still in the ring,
+    // so the oldest entry (seq=3) is acceptable: ring is intact since
+    // resumeFromSeq=2 == 3-1.
+    await handleSubMessage(c, JSON.stringify({
+      op: "sub", subId: "a", collection: "tasks", resumeFromSeq: 2,
+    }))
+
+    const deltas = c.sent.filter(m => m.type === "delta")
+    const ids = deltas.map(m => {
+      if (m.type !== "delta" || m.op !== "insert") throw new Error("bad")
+      return m.row.id
+    })
+    expect(ids).toEqual(["r3", "r4", "r5"])
+
+    // Resuming from seq 1 — ring's oldest is 3, gap is too big.
+    for (const id of ["r1", "r2", "r3", "r4", "r5"]) {
+      db.raw().prepare("INSERT INTO tasks (id, title, done, created_at, updated_at) VALUES (?, ?, ?, ?, ?)")
+        .run(id, id, 0, `2026-01-${id.slice(1).padStart(2, "0")}`, "2026-01-01")
+    }
+    const c2 = makeClient()
+    addSubClient(c2)
+    await handleSubMessage(c2, JSON.stringify({
+      op: "sub", subId: "b", collection: "tasks", resumeFromSeq: 1,
+    }))
+    expect(c2.sent.at(0)?.type).toBe("snapshot")
+  })
+})
+
+// ── Hardening (Phase 6) ──────────────────────────────────────────────────────
+
+describe("subscriptions — quota + hardening", () => {
+  it("rejects subs past MAX_SUBS_PER_CLIENT with sub_limit_exceeded", async () => {
+    setMaxSubsPerClient(2)
+    const c = makeClient()
+    addSubClient(c)
+
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "b", collection: "tasks" }))
+    // Third is over cap.
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "c", collection: "tasks" }))
+
+    const errs = c.sent.filter(m => m.type === "error")
+    expect(errs).toHaveLength(1)
+    if (errs[0].type !== "error") throw new Error("expected error")
+    expect(errs[0].code).toBe("sub_limit_exceeded")
+    // Two snapshots, one error — no third snapshot.
+    expect(c.sent.filter(m => m.type === "snapshot")).toHaveLength(2)
+  })
+
+  it("freeing a sub via unsub re-opens a quota slot", async () => {
+    setMaxSubsPerClient(2)
+    const c = makeClient()
+    addSubClient(c)
+
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "a", collection: "tasks" }))
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "b", collection: "tasks" }))
+    await handleSubMessage(c, JSON.stringify({ op: "unsub", subId: "a" }))
+    // Slot freed; this should succeed.
+    await handleSubMessage(c, JSON.stringify({ op: "sub", subId: "c", collection: "tasks" }))
+
+    const errs = c.sent.filter(m => m.type === "error")
+    expect(errs).toHaveLength(0)
+  })
+
+  it("security regression: cross-tenant deltas never leak — full insert/update/delete cycle", async () => {
+    // Mirrors the security model in test/security.test.ts: every write on a
+    // user-scoped collection MUST only reach subs whose ctx.userId matches
+    // the row's _owner. This test fans out one of each kind and asserts
+    // the wrong tenant got zero deltas.
+    const alice = makeClient("alice"), bob = makeClient("bob"), anon = makeClient(null)
+    addSubClient(alice); addSubClient(bob); addSubClient(anon)
+    await handleSubMessage(alice, JSON.stringify({ op: "sub", subId: "a", collection: "notes" }))
+    await handleSubMessage(bob, JSON.stringify({ op: "sub", subId: "b", collection: "notes" }))
+    // Anon is rejected at sub time on a scoped collection — expected.
+    await handleSubMessage(anon, JSON.stringify({ op: "sub", subId: "x", collection: "notes" }))
+
+    alice.sent.length = 0; bob.sent.length = 0; anon.sent.length = 0
+
+    const aliceRow = (id: string, body: string): Record<string, unknown> => ({
+      id, body, _owner: "alice", created_at: "2026-01-01", updated_at: "2026-01-01",
+    })
+
+    // Insert alice's row.
+    await notifyRowChange("notes", "insert", null, aliceRow("n1", "hello"))
+    // Update alice's row.
+    await notifyRowChange("notes", "update", aliceRow("n1", "hello"), aliceRow("n1", "hello edited"))
+    // Delete alice's row.
+    await notifyRowChange("notes", "delete", aliceRow("n1", "hello edited"), null)
+
+    expect(alice.sent).toHaveLength(3)
+    expect(bob.sent).toHaveLength(0)
+    expect(anon.sent).toHaveLength(0)
+  })
+
+  it("security regression: predicate gating doesn't bypass scope gating", async () => {
+    // Sub with a predicate that's always-true. The predicate must NOT
+    // promote a cross-tenant row into the read set.
+    const alice = makeClient("alice"), bob = makeClient("bob")
+    addSubClient(alice); addSubClient(bob)
+    await handleSubMessage(alice, JSON.stringify({
+      op: "sub", subId: "a", collection: "notes",
+      where: { op: "isNotNull", column: "body" }, // always true for non-null bodies
+    }))
+    await handleSubMessage(bob, JSON.stringify({ op: "sub", subId: "b", collection: "notes" }))
+    alice.sent.length = 0; bob.sent.length = 0
+
+    // Bob's row appears — must reach bob but never alice.
+    await notifyRowChange("notes", "insert", null, {
+      id: "b1", body: "bob's", _owner: "bob",
+      created_at: "2026-01-01", updated_at: "2026-01-01",
+    })
+
+    expect(bob.sent).toHaveLength(1)
+    expect(alice.sent).toHaveLength(0)
+  })
+})