@mh-gg/relay-runtime 0.1.1-alpha.20260613T085325975Z

package/test/encryptedRoomRuntime.test.cjs

@@ -0,0 +1,729 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { createEncryptedRoomRuntime, parseStreamHeader } = require("../src/encryptedRoomRuntime.cjs");
+
+function hexId(prefix) {
+  return String(prefix).padStart(64, "0");
+}
+
+function makeEvent(id, overrides = {}) {
+  const eventId = hexId(id);
+  return {
+    id: eventId,
+    pubkey: overrides.pubkey || "pk_" + eventId.slice(0, 8),
+    created_at: Math.floor(Date.now() / 1000),
+    kind: 9000,
+    tags: [
+      ["scheme", "matterhorn.operation.v2"],
+      ["d", overrides.roomName || "room"],
+      ["stream", overrides.stream || "stream:general"],
+      ["hlc", overrides.hlc || `000000000000001:000000:${overrides.nodeId || "node"}`],
+      ["member", overrides.member || "alice"],
+      ["device", overrides.device || "d1"],
+      ["seq", String(overrides.seq ?? 0)],
+      ["plugin", overrides.plugin || "chat"],
+      ["type", overrides.type || "message.send"],
+      ["role", overrides.role || "member"],
+      ["epoch", overrides.epoch || "e1"],
+      ["op-id", overrides.opId || `op_${id}`],
+      ["payload-hash", overrides.payloadHash || `ph_${id}`]
+    ],
+    content: "encrypted"
+  };
+}
+
+test("parseStreamHeader extracts v2 header tags", () => {
+  const event = makeEvent("e1", { stream: "chat:messages", hlc: "000000000000010:000001:n1", member: "bob", seq: 5 });
+  const header = parseStreamHeader(event);
+  assert.equal(header.stream, "chat:messages");
+  assert.equal(header.hlc, "000000000000010:000001:n1");
+  assert.equal(header.writer, "bob");
+  assert.equal(header.seq, 5);
+  assert.equal(header.plugin, "chat");
+});
+
+test("parseStreamHeader rejects invalid HLC", () => {
+  const event = makeEvent("e1", { hlc: "not-an-hlc" });
+  assert.equal(parseStreamHeader(event), undefined);
+  assert.equal(parseStreamHeader({ id: "no-tags" }), undefined);
+  assert.equal(parseStreamHeader({ tags: [["hlc", "000000000000001:000000:n1"]] }), undefined);
+
+  const fallback = parseStreamHeader({
+    pubkey: "pubkey-fallback",
+    tags: [
+      ["stream", "s1"],
+      ["hlc", "000000000000001:000000:n1"],
+      ["seq", "-1"]
+    ]
+  });
+  assert.equal(fallback.writer, "pubkey-fallback");
+  assert.equal(fallback.seq, 0);
+});
+
+test("insert indexes events by stream", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const r1 = runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1" }));
+  const r2 = runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000002:000000:n1" }));
+  const r3 = runtime.insert(makeEvent("e3", { stream: "s2", hlc: "000000000000001:000000:n1" }));
+
+  assert.equal(r1.ok, true);
+  assert.equal(r1.inserted, true);
+  assert.equal(r2.ok, true);
+  assert.equal(r3.ok, true);
+  assert.deepEqual(runtime.listStreams(), ["s1", "s2"]);
+  assert.equal(runtime.streamEvents("s1").length, 2);
+  assert.equal(runtime.streamEvents("s2").length, 1);
+});
+
+test("insert deduplicates by event id", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const ev = makeEvent("e1");
+  assert.equal(runtime.insert(ev).inserted, true);
+  assert.equal(runtime.insert(ev).inserted, false);
+  assert.equal(runtime.stats.duplicates, 1);
+});
+
+test("insert deduplicates by (stream, hlc, writer, seq)", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1", member: "alice", seq: 0 }));
+  const r2 = runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000001:000000:n1", member: "alice", seq: 0 }));
+  assert.equal(r2.inserted, false);
+  assert.equal(r2.eventId, hexId("e1"));
+});
+
+test("rangeQuery returns events ordered by hlc", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000003:000000:n1" }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000001:000000:n1" }));
+  runtime.insert(makeEvent("e3", { stream: "s1", hlc: "000000000000002:000000:n1" }));
+
+  const result = runtime.rangeQuery("s1");
+  assert.deepEqual(result.events, [hexId("e2"), hexId("e3"), hexId("e1")]);
+});
+
+test("rangeQuery respects sinceHlc and untilHlc", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1" }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000002:000000:n1" }));
+  runtime.insert(makeEvent("e3", { stream: "s1", hlc: "000000000000003:000000:n1" }));
+
+  const r1 = runtime.rangeQuery("s1", { sinceHlc: "000000000000002:000000:n1" });
+  assert.deepEqual(r1.events, [hexId("e2"), hexId("e3")]);
+
+  const r2 = runtime.rangeQuery("s1", { untilHlc: "000000000000002:000000:n1" });
+  assert.deepEqual(r2.events, [hexId("e1"), hexId("e2")]);
+
+  const r3 = runtime.rangeQuery("s1", { sinceHlc: "000000000000002:000000:n1", untilHlc: "000000000000002:000000:n1" });
+  assert.deepEqual(r3.events, [hexId("e2")]);
+
+  const r4 = runtime.rangeQuery("s1", { beforeHlc: "999999999999999:000000:n1", limit: 2 });
+  assert.deepEqual(r4.events, [hexId("e2"), hexId("e3")]);
+
+  const r5 = runtime.rangeQuery("s1", { sinceHlc: "999999999999999:000000:n1" });
+  assert.deepEqual(r5.events, []);
+});
+
+test("headQuery returns latest events", () => {
+  const runtime = createEncryptedRoomRuntime();
+  for (let i = 1; i <= 5; i += 1) {
+    runtime.insert(makeEvent(`e${i}`, { stream: "s1", hlc: `00000000000000${i}:000000:n1` }));
+  }
+  const result = runtime.headQuery("s1", { limit: 2 });
+  assert.deepEqual(result.events, [hexId("e4"), hexId("e5")]);
+});
+
+test("latestHlc returns the newest HLC in a stream", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1" }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000003:000000:n1" }));
+  runtime.insert(makeEvent("e3", { stream: "s1", hlc: "000000000000002:000000:n1" }));
+  assert.equal(runtime.latestHlc("s1"), "000000000000003:000000:n1");
+  assert.equal(runtime.latestHlc("unknown"), undefined);
+});
+
+test("snapshot and restore round-trip", () => {
+  const runtime = createEncryptedRoomRuntime({ roomName: "room-a" });
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1" }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000002:000000:n1" }));
+
+  const snap = runtime.snapshot();
+  assert.equal(snap.roomName, "room-a");
+  assert.equal(snap.events.length, 2);
+
+  const restored = createEncryptedRoomRuntime();
+  const result = restored.restore(snap);
+  assert.equal(result.ok, true);
+  assert.equal(result.inserted, 2);
+  assert.deepEqual(restored.listStreams(), ["s1"]);
+  assert.deepEqual(restored.rangeQuery("s1").events, [hexId("e1"), hexId("e2")]);
+});
+
+test("eviction keeps maxEventsPerStream", () => {
+  const runtime = createEncryptedRoomRuntime({ maxEventsPerStream: 3 });
+  for (let i = 1; i <= 5; i += 1) {
+    runtime.insert(makeEvent(`e${i}`, { stream: "s1", hlc: `00000000000000${i}:000000:n1` }));
+  }
+  assert.equal(runtime.streamEvents("s1").length, 3);
+  assert.equal(runtime.stats.evictions, 2);
+  assert.deepEqual(runtime.rangeQuery("s1").events, [hexId("e3"), hexId("e4"), hexId("e5")]);
+});
+
+test("createNegentropySession returns a session scoped to stream", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1", created_at: 1000 }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000002:000000:n1", created_at: 1001 }));
+  runtime.insert(makeEvent("e3", { stream: "s2", hlc: "000000000000001:000000:n1", created_at: 1002 }));
+
+  const session = runtime.createNegentropySession("s1");
+  assert.ok(session.negentropy);
+  assert.equal(typeof session.negentropy.initiate(), "string");
+});
+
+test("large thread: latest 50 plus chunked scroll back", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const stream = "chat:messages:general";
+  const total = 600;
+  for (let i = 1; i <= total; i += 1) {
+    const physical = String(i).padStart(15, "0");
+    runtime.insert(makeEvent(`m${i}`, {
+      stream,
+      hlc: `${physical}:000000:n1`,
+      member: i % 3 === 0 ? "bob" : "alice",
+      seq: i - 1,
+      created_at: 1000 + i
+    }));
+  }
+
+  // 1. Client opens thread: fetch latest 50 messages.
+  const latest = runtime.headQuery(stream, { limit: 50 });
+  assert.equal(latest.events.length, 50);
+  assert.equal(latest.events[0], hexId("m551"));
+  assert.equal(latest.events[latest.events.length - 1], hexId("m600"));
+
+  // 2. Scroll up: fetch previous 50 messages (messages 501-550).
+  const oldestLoadedHlc = "000000000000551:000000:n1";
+  const chunk1 = runtime.rangeQuery(stream, { beforeHlc: oldestLoadedHlc, limit: 50 });
+  assert.equal(chunk1.events.length, 50);
+  assert.equal(chunk1.events[0], hexId("m501"));
+  assert.equal(chunk1.events[chunk1.events.length - 1], hexId("m550"));
+
+  // 3. Scroll up again: fetch next 50 older messages (messages 451-500).
+  const nextOldestHlc = "000000000000501:000000:n1";
+  const chunk2 = runtime.rangeQuery(stream, { beforeHlc: nextOldestHlc, limit: 50 });
+  assert.equal(chunk2.events.length, 50);
+  assert.equal(chunk2.events[0], hexId("m451"));
+  assert.equal(chunk2.events[chunk2.events.length - 1], hexId("m500"));
+
+  // 4. Jump to a specific historical range (messages 101-150, inclusive).
+  const range = runtime.rangeQuery(stream, {
+    sinceHlc: "000000000000101:000000:n1",
+    untilHlc: "000000000000150:000000:n1"
+  });
+  assert.equal(range.events.length, 50);
+  assert.equal(range.events[0], hexId("m101"));
+  assert.equal(range.events[range.events.length - 1], hexId("m150"));
+});
+
+test("large thread: query totals and pagination offsets", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const stream = "chat:messages:general";
+  const total = 600;
+  for (let i = 1; i <= total; i += 1) {
+    const physical = String(i).padStart(15, "0");
+    runtime.insert(makeEvent(`m${i}`, {
+      stream,
+      hlc: `${physical}:000000:n1`,
+      seq: i - 1
+    }));
+  }
+
+  const pageSize = 100;
+  const firstPage = runtime.rangeQuery(stream, { limit: pageSize, offset: 0 });
+  assert.equal(firstPage.total, 600);
+  assert.equal(firstPage.events.length, 100);
+  assert.equal(firstPage.events[0], hexId("m1"));
+
+  const secondPage = runtime.rangeQuery(stream, { limit: pageSize, offset: 100 });
+  assert.equal(secondPage.events.length, 100);
+  assert.equal(secondPage.events[0], hexId("m101"));
+
+  const lastPage = runtime.rangeQuery(stream, { limit: pageSize, offset: 500 });
+  assert.equal(lastPage.events.length, 100);
+  assert.equal(lastPage.events[0], hexId("m501"));
+  assert.equal(lastPage.events[lastPage.events.length - 1], hexId("m600"));
+});
+
+test("snapshot and restore preserves large thread queries without room secrets", () => {
+  const runtime = createEncryptedRoomRuntime({ roomName: "encrypted-room" });
+  const stream = "chat:messages:thread-a";
+  const total = 600;
+  for (let i = 1; i <= total; i += 1) {
+    const physical = String(i).padStart(15, "0");
+    runtime.insert(makeEvent(`m${i}`, {
+      stream,
+      hlc: `${physical}:000000:n1`,
+      member: i % 2 === 0 ? "bob" : "alice",
+      seq: i - 1,
+      created_at: 2000 + i
+    }));
+  }
+
+  // Snapshot the runtime state. This simulates relay shutdown persistence.
+  const snap = runtime.snapshot();
+  assert.equal(snap.events.length, 600);
+  assert.equal(snap.roomName, "encrypted-room");
+  // No room secret is ever part of the snapshot.
+  assert.equal(snap.roomSecret, undefined);
+  assert.equal(snap.epochKey, undefined);
+
+  // Create a fresh runtime and restore. This simulates relay restart.
+  const restored = createEncryptedRoomRuntime({ roomName: "encrypted-room" });
+  const restoreResult = restored.restore(snap);
+  assert.equal(restoreResult.ok, true);
+  assert.equal(restoreResult.inserted, 600);
+
+  // Latest query still works.
+  const latest = restored.headQuery(stream, { limit: 50 });
+  assert.equal(latest.events.length, 50);
+  assert.equal(latest.events[0], hexId("m551"));
+  assert.equal(latest.events[latest.events.length - 1], hexId("m600"));
+
+  // Chunked scroll back still works.
+  const chunk = restored.rangeQuery(stream, { beforeHlc: "000000000000551:000000:n1", limit: 50 });
+  assert.equal(chunk.events.length, 50);
+  assert.equal(chunk.events[0], hexId("m501"));
+  assert.equal(chunk.events[chunk.events.length - 1], hexId("m550"));
+
+  // Range jump still works.
+  const range = restored.rangeQuery(stream, {
+    sinceHlc: "000000000000101:000000:n1",
+    untilHlc: "000000000000150:000000:n1"
+  });
+  assert.equal(range.events.length, 50);
+  assert.equal(range.events[0], hexId("m101"));
+
+  // Stream metadata is preserved.
+  assert.deepEqual(restored.listStreams(), [stream]);
+  assert.equal(restored.latestHlc(stream), "000000000000600:000000:n1");
+});
+
+test("restore ignores duplicate events across restart", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const stream = "chat:messages:general";
+  runtime.insert(makeEvent("e1", { stream, hlc: "000000000000001:000000:n1" }));
+  runtime.insert(makeEvent("e2", { stream, hlc: "000000000000002:000000:n1" }));
+
+  const snap = runtime.snapshot();
+  const restored = createEncryptedRoomRuntime();
+  restored.restore(snap);
+
+  // Simulate the same events arriving again after restart (e.g. mesh replay).
+  const replay1 = restored.insert(makeEvent("e1", { stream, hlc: "000000000000001:000000:n1" }));
+  const replay2 = restored.insert(makeEvent("e2", { stream, hlc: "000000000000002:000000:n1" }));
+  assert.equal(replay1.inserted, false);
+  assert.equal(replay2.inserted, false);
+  assert.equal(restored.streamEvents(stream).length, 2);
+});
+
+test("restore with empty snapshot is a no-op", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const result = runtime.restore({ events: [] });
+  assert.equal(result.ok, true);
+  assert.equal(result.inserted, 0);
+  assert.deepEqual(runtime.listStreams(), []);
+});
+
+test("restore rejects invalid snapshot", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const result = runtime.restore({ notEvents: [] });
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "invalid-snapshot");
+});
+
+test("insert rejects missing event id and missing stream header", () => {
+  const runtime = createEncryptedRoomRuntime();
+  assert.equal(runtime.insert({ kind: 9001 }).ok, false);
+  assert.equal(runtime.insert({ id: "abc", kind: 9999 }).ok, false);
+});
+
+test("has and get expose stored events", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const ev = makeEvent("e1");
+  runtime.insert(ev);
+  assert.equal(runtime.has(hexId("e1")), true);
+  assert.equal(runtime.has("missing"), false);
+  assert.equal(runtime.get(hexId("e1"))?.id, hexId("e1"));
+  assert.equal(runtime.get("missing"), undefined);
+});
+
+test("streamWritersFor lists distinct writers", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", member: "alice" }));
+  runtime.insert(makeEvent("e2", { stream: "s1", member: "alice" }));
+  runtime.insert(makeEvent("e3", { stream: "s1", member: "bob" }));
+  assert.deepEqual(runtime.streamWritersFor("s1"), ["alice", "bob"]);
+  assert.deepEqual(runtime.streamWritersFor("unknown"), []);
+});
+
+test("deduplicates by (stream, hlc, writer, seq) across writers and seq", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeEvent("e1", { stream: "s1", hlc: "000000000000001:000000:n1", member: "alice", seq: 0 }));
+  runtime.insert(makeEvent("e2", { stream: "s1", hlc: "000000000000001:000000:n1", member: "bob", seq: 0 }));
+  runtime.insert(makeEvent("e3", { stream: "s1", hlc: "000000000000001:000000:n1", member: "alice", seq: 1 }));
+  assert.equal(runtime.streamEvents("s1").length, 3);
+
+  const dup = runtime.insert(makeEvent("e4", { stream: "s1", hlc: "000000000000001:000000:n1", member: "alice", seq: 0 }));
+  assert.equal(dup.inserted, false);
+  assert.equal(dup.eventId, hexId("e1"));
+});
+
+test("control-plane parse tolerates malformed events", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const bad = {
+    id: hexId("bad"),
+    pubkey: "pk",
+    created_at: 1000,
+    kind: 9010,
+    tags: [["protocol", "matterhorn-sdk"], ["version", "1"], ["d", "room"]],
+    content: "not-json"
+  };
+  const result = runtime.insert(bad);
+  assert.equal(result.ok, true);
+  assert.equal(result.inserted, true);
+  assert.equal(runtime.activeKeyEpoch(), undefined);
+});
+
+test("control-plane retirement without a successor leaves no active epoch", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeControlPlaneEvent("ke1", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    retiredAt: 2000,
+    historyVisibility: "retained-keyring"
+  }));
+  assert.equal(runtime.activeKeyEpoch(), undefined);
+});
+
+function makeControlPlaneEvent(id, kind, payload, overrides = {}) {
+  const eventId = hexId(id);
+  return {
+    id: eventId,
+    pubkey: overrides.pubkey || "pk_admin",
+    created_at: overrides.createdAt ?? 1000,
+    kind,
+    tags: [
+      ["protocol", "matterhorn-sdk"],
+      ["version", "1"],
+      ["d", overrides.roomName || "room"]
+    ],
+    content: JSON.stringify(payload)
+  };
+}
+
+test("folds room.key.epoch into active key epoch view", () => {
+  const runtime = createEncryptedRoomRuntime();
+  const epoch = makeControlPlaneEvent("ke1", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    createdByDevice: "dev-admin",
+    historyVisibility: "retained-keyring"
+  });
+
+  const result = runtime.insert(epoch);
+  assert.equal(result.ok, true);
+  assert.equal(result.inserted, true);
+
+  const active = runtime.activeKeyEpoch();
+  assert.ok(active);
+  assert.equal(active.id, "epoch_1");
+  assert.equal(active.index, 1);
+  assert.equal(active.historyVisibility, "retained-keyring");
+});
+
+test("retires previous active epoch when a new epoch is created", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeControlPlaneEvent("ke1", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    historyVisibility: "retained-keyring"
+  }));
+
+  runtime.insert(makeControlPlaneEvent("ke2", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_2",
+    index: 2,
+    createdAt: 2000,
+    createdBy: "admin",
+    historyVisibility: "active-epoch-only"
+  }));
+
+  runtime.insert(makeControlPlaneEvent("ke1r", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    retiredAt: 2000,
+    historyVisibility: "retained-keyring"
+  }));
+
+  const active = runtime.activeKeyEpoch();
+  assert.equal(active.id, "epoch_2");
+  assert.equal(active.historyVisibility, "active-epoch-only");
+
+  const epochs = runtime.listKeyEpochs();
+  assert.equal(epochs.length, 2);
+  const retired = epochs.find((e) => e.id === "epoch_1");
+  assert.equal(retired.retiredAt, 2000);
+});
+
+test("folds key epoch grants and room index key grants", () => {
+  const runtime = createEncryptedRoomRuntime();
+
+  runtime.insert(makeControlPlaneEvent("keg1", 9011, {
+    kind: "matterhorn.key-epoch-grant",
+    version: 1,
+    roomName: "room",
+    epochId: "epoch_1",
+    epochIndex: 1,
+    recipientMemberId: "alice",
+    recipientDeviceId: "dev-a",
+    recipientEncryptionKeyId: "rkx_alice",
+    createdAt: 1000,
+    wrap: { alg: "x25519+hkdf-sha256+aes-256-gcm", ephemeralPublicKey: "epk", iv: "iv" },
+    wrappedEpochKey: "cipher"
+  }));
+
+  runtime.insert(makeControlPlaneEvent("kig1", 9012, {
+    kind: "matterhorn.room-index-key-grant",
+    version: 1,
+    recipientMemberId: "alice",
+    recipientDeviceId: "dev-a",
+    recipientEncryptionKeyId: "rkx_alice",
+    createdAt: 1000,
+    wrap: { alg: "x25519+hkdf-sha256+aes-256-gcm", ephemeralPublicKey: "epk", iv: "iv" },
+    wrappedRoomIndexKey: "cipher"
+  }));
+
+  assert.deepEqual(runtime.listEpochGrantRecipients("epoch_1"), ["rkx_alice"]);
+  assert.deepEqual(runtime.listRoomIndexKeyGrantRecipients(), ["rkx_alice"]);
+});
+
+test("keyEpochForIngress returns active epoch when epochId is omitted", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeControlPlaneEvent("ke1", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    historyVisibility: "retained-keyring"
+  }));
+
+  assert.equal(runtime.keyEpochForIngress().id, "epoch_1");
+  assert.equal(runtime.keyEpochForIngress("epoch_1").id, "epoch_1");
+  assert.equal(runtime.keyEpochForIngress("missing"), undefined);
+});
+
+test("snapshot and restore preserves control-plane state", () => {
+  const runtime = createEncryptedRoomRuntime();
+  runtime.insert(makeControlPlaneEvent("ke1", 9010, {
+    kind: "room.key.epoch",
+    version: 1,
+    id: "epoch_1",
+    index: 1,
+    createdAt: 1000,
+    createdBy: "admin",
+    historyVisibility: "retained-keyring"
+  }));
+  runtime.insert(makeControlPlaneEvent("keg1", 9011, {
+    kind: "matterhorn.key-epoch-grant",
+    version: 1,
+    roomName: "room",
+    epochId: "epoch_1",
+    epochIndex: 1,
+    recipientMemberId: "alice",
+    recipientDeviceId: "dev-a",
+    recipientEncryptionKeyId: "rkx_alice",
+    createdAt: 1000,
+    wrap: { alg: "x25519+hkdf-sha256+aes-256-gcm", ephemeralPublicKey: "epk", iv: "iv" },
+    wrappedEpochKey: "cipher"
+  }));
+
+  const snap = runtime.snapshot();
+  const restored = createEncryptedRoomRuntime();
+  restored.restore(snap);
+
+  assert.equal(restored.activeKeyEpoch().id, "epoch_1");
+  assert.deepEqual(restored.listEpochGrantRecipients("epoch_1"), ["rkx_alice"]);
+});
+
+const {
+  createRoomIndexNgramEvents,
+  generatePartyIdentity,
+  roomIndexSearchQuery
+} = require("@mh-gg/event");
+
+function makeNgramIndexEvent(id, payload, overrides = {}) {
+  return {
+    id: hexId(id),
+    pubkey: overrides.pubkey || "pk_index",
+    created_at: overrides.createdAt ?? 1700000000,
+    kind: 9013,
+    tags: overrides.tags || [["d", payload.roomName || "room"]],
+    content: JSON.stringify(payload)
+  };
+}
+
+test("server-side n-gram search indexes opaque sidecar tokens", () => {
+  const roomName = "room";
+  const roomIndexKey = "22".repeat(32);
+  const identity = generatePartyIdentity(1700000000000);
+  const runtime = createEncryptedRoomRuntime({ roomName });
+  const target = makeEvent("e9", {
+    roomName,
+    stream: "chat:messages:general",
+    hlc: "000000000000009:000000:n1",
+    opId: "op_e9"
+  });
+
+  assert.equal(runtime.insert(target).inserted, true);
+  const indexEvents = createRoomIndexNgramEvents({
+    identity,
+    roomIndexKey,
+    roomName,
+    targetEventId: target.id,
+    targetOperationId: "op_e9",
+    targetHlc: "000000000000009:000000:n1",
+    stream: "chat:messages:general",
+    field: "body",
+    text: "Deploy launch codes in alpha channel",
+    createdAt: 1700000000000,
+    maxTokensPerEvent: 512
+  });
+  assert.equal(indexEvents[0].content.includes("launch"), false);
+  assert.equal(indexEvents[0].content.includes("codes"), false);
+  for (const event of indexEvents) assert.equal(runtime.insert(event).inserted, true);
+
+  const query = roomIndexSearchQuery({ roomIndexKey, roomName, text: "launch codes" });
+  const result = runtime.searchNgrams({ ...query, stream: "chat:messages:general" });
+  assert.deepEqual(result.events, [target.id]);
+  assert.equal(result.matches[0].targetOperationId, "op_e9");
+  assert.equal(result.matches[0].field, "body");
+
+  const miss = roomIndexSearchQuery({ roomIndexKey, roomName, text: "unrelated" });
+  assert.deepEqual(runtime.searchNgrams(miss).events, []);
+});
+
+test("server-side n-gram search covers modes, invalid tokens, and pruning", () => {
+  const runtime = createEncryptedRoomRuntime({ roomName: "room", maxEventsPerStream: 2 });
+  const targetA = makeEvent("a1", {
+    roomName: "room",
+    stream: "chat:messages:general",
+    hlc: "000000000000001:000000:n1",
+    opId: "op_a1"
+  });
+  const targetB = makeEvent("b1", {
+    roomName: "room",
+    stream: "chat:messages:general",
+    hlc: "000000000000002:000000:n1",
+    opId: "op_b1"
+  });
+  const tokenA = "abcdefghijklmnopqrstuvwxyz";
+  const tokenB = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+  runtime.insert(targetA);
+  runtime.insert(makeNgramIndexEvent("i1", {
+    kind: "matterhorn.room-index-ngram",
+    version: 1,
+    suite: "matterhorn.ngram.hmac-sha256.v1",
+    roomName: "room",
+    keyId: "key",
+    targetEventId: targetA.id,
+    targetOperationId: "op_a1",
+    targetHlc: "000000000000001:000000:n1",
+    stream: "chat:messages:general",
+    field: "body",
+    tokenCount: 2,
+    createdAt: 10,
+    tokens: [tokenA, tokenB, "bad"]
+  }));
+  runtime.insert(makeNgramIndexEvent("i1", {
+    kind: "matterhorn.room-index-ngram",
+    version: 1,
+    suite: "matterhorn.ngram.hmac-sha256.v1",
+    roomName: "room",
+    keyId: "key",
+    targetEventId: targetA.id,
+    tokens: [tokenA]
+  }));
+  runtime.insert(targetB);
+  runtime.insert(makeNgramIndexEvent("i2", {
+    kind: "matterhorn.room-index-ngram",
+    version: 1,
+    suite: "matterhorn.ngram.hmac-sha256.v1",
+    roomName: "room",
+    keyId: "key",
+    targetEventId: targetB.id,
+    targetHlc: "000000000000002:000000:n1",
+    stream: "chat:messages:general",
+    tokenCount: 1,
+    createdAt: 20,
+    tokens: [tokenA]
+  }));
+
+  assert.deepEqual(runtime.searchNgrams({ keyId: "key", tokens: ["bad"] }), { events: [], matches: [], total: 0, queryTokenCount: 0 });
+  const anyResult = runtime.searchNgrams({ keyId: "key", tokens: [tokenA, tokenB], mode: "any", order: "score", limit: 1 });
+  assert.equal(anyResult.events.length, 1);
+  assert.equal(anyResult.queryTokenCount, 2);
+
+  const thresholdResult = runtime.searchNgrams({ keyId: "key", tokens: [tokenA, tokenB], mode: "threshold", minScore: 0.75 });
+  assert.equal(thresholdResult.events.includes(targetA.id), true);
+  assert.equal(thresholdResult.events.includes(targetB.id), false);
+
+  assert.deepEqual(runtime.searchNgrams({ keyId: "key", tokens: [tokenA], stream: "other" }).events, []);
+
+  runtime.insert(makeEvent("c1", { roomName: "room", stream: "chat:messages:general", hlc: "000000000000003:000000:n1" }));
+  assert.equal(runtime.has(targetA.id), false);
+  assert.equal(runtime.searchNgrams({ keyId: "key", tokens: [tokenB] }).events.includes(targetA.id), false);
+});
+
+test("server-side n-gram index ignores malformed sidecars without leaking state", () => {
+  const runtime = createEncryptedRoomRuntime({ roomName: "room" });
+  const target = makeEvent("d1", { roomName: "room" });
+  runtime.insert(target);
+
+  const malformedPayloads = [
+    null,
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "bad", roomName: "room", keyId: "key", targetEventId: target.id, tokens: ["abcdefghijklmnopqrstuvwxyz"] },
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "matterhorn.ngram.hmac-sha256.v1", roomName: "other", keyId: "key", targetEventId: target.id, tokens: ["abcdefghijklmnopqrstuvwxyz"] },
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "matterhorn.ngram.hmac-sha256.v1", roomName: "room", keyId: "", targetEventId: target.id, tokens: ["abcdefghijklmnopqrstuvwxyz"] },
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "matterhorn.ngram.hmac-sha256.v1", roomName: "room", keyId: "key", targetEventId: "bad", tokens: ["abcdefghijklmnopqrstuvwxyz"] },
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "matterhorn.ngram.hmac-sha256.v1", roomName: "room", keyId: "key", targetEventId: target.id, tokens: [] },
+    { kind: "matterhorn.room-index-ngram", version: 1, suite: "matterhorn.ngram.hmac-sha256.v1", roomName: "room", keyId: "key", targetEventId: target.id, tokens: ["bad"] }
+  ];
+
+  for (const [index, payload] of malformedPayloads.entries()) {
+    const event = payload
+      ? makeNgramIndexEvent(`m${index}`, payload)
+      : { ...makeNgramIndexEvent(`m${index}`, {}, {}), content: "not-json" };
+    assert.equal(runtime.insert(event).ok, true);
+  }
+
+  assert.deepEqual(runtime.ngramIndexStats(), { targets: 0, indexEvents: 0, tokenPostingLists: 0, postings: 0 });
+});