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

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mh-gg/relay-runtime",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Relay runtime helpers for matterhorn.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/relay-core": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/host-runtime": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/authority": "^0.1.1-alpha.20260603T124500153Z",
+    "@mh-gg/base": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-security": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-state": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/*.cjs test/*.test.cjs"
+  }
+}

package/src/encryptedRoomRuntime.cjs

@@ -0,0 +1,641 @@
+const { parseHlc } = require("@mh-gg/protocol");
+const { createStreamNegentropySession } = require("@mh-gg/relay-core");
+
+const ROOM_INDEX_NGRAM_KIND = 9013;
+const ROOM_INDEX_NGRAM_PAYLOAD_KIND = "matterhorn.room-index-ngram";
+const ROOM_INDEX_NGRAM_SUITE = "matterhorn.ngram.hmac-sha256.v1";
+
+function tagValue(tags, name) {
+  const tag = Array.isArray(tags) ? tags.find((item) => Array.isArray(item) && item[0] === name) : undefined;
+  return tag ? tag[1] : undefined;
+}
+
+function tagNumber(tags, name) {
+  const raw = tagValue(tags, name);
+  const value = Number(raw);
+  return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+function parseStreamHeader(nostrEvent) {
+  const tags = nostrEvent?.tags;
+  if (!Array.isArray(tags)) return undefined;
+  const stream = tagValue(tags, "stream");
+  const hlc = tagValue(tags, "hlc");
+  if (!stream || !hlc) return undefined;
+  const parsedHlc = parseHlc(hlc);
+  if (!parsedHlc) return undefined;
+  return {
+    stream,
+    hlc,
+    writer: tagValue(tags, "member") || nostrEvent?.pubkey || "",
+    device: tagValue(tags, "device") || "",
+    seq: tagNumber(tags, "seq") || 0,
+    opId: tagValue(tags, "op-id") || "",
+    plugin: tagValue(tags, "plugin") || "",
+    type: tagValue(tags, "type") || "",
+    action: tagValue(tags, "action") || "",
+    role: tagValue(tags, "role") || "",
+    epoch: tagValue(tags, "epoch") || ""
+  };
+}
+
+function compareIndexEntries(left, right) {
+  const hlcOrder = String(left.hlc).localeCompare(String(right.hlc));
+  if (hlcOrder !== 0) return hlcOrder;
+  const writerOrder = String(left.writer).localeCompare(String(right.writer));
+  if (writerOrder !== 0) return writerOrder;
+  const seqDiff = (left.seq || 0) - (right.seq || 0);
+  if (seqDiff !== 0) return seqDiff;
+  return String(left.eventId).localeCompare(String(right.eventId));
+}
+
+function binarySearchInsert(array, entry, compare) {
+  let low = 0;
+  let high = array.length;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    const cmp = compare(entry, array[mid]);
+    if (cmp === 0) return mid;
+    if (cmp > 0) low = mid + 1;
+    else high = mid;
+  }
+  array.splice(low, 0, entry);
+  return low;
+}
+
+function createEncryptedRoomRuntime(options = {}) {
+  const roomName = options.roomName;
+  const logger = options.logger || { debug() {}, info() {}, warn() {}, error() {} };
+  const maxEventsPerStream = Number.isInteger(options.maxEventsPerStream) && options.maxEventsPerStream > 0
+    ? options.maxEventsPerStream
+    : 10000;
+
+  const events = new Map(); // eventId (hex) -> nostrEvent
+  const streams = new Map(); // stream -> sorted entries[]
+  const streamWriters = new Map(); // stream -> Set(writer)
+  const stats = { inserts: 0, duplicates: 0, evictions: 0, ngramIndexEvents: 0, ngramPostings: 0 };
+
+  // Control-plane key state (visible to relays in plaintext tags/payload).
+  const keyEpochs = new Map(); // epochId -> { id, index, createdAt, retiredAt, createdBy, historyVisibility }
+  let activeEpochId = null;
+  const epochGrants = new Map(); // epochId -> Map(recipientKeyId -> grantEventId)
+  const roomIndexKeyGrants = new Map(); // recipientKeyId -> grantEventId
+  let controlPlaneCounter = 0;
+
+  // Opaque, client-generated n-gram search indexes. Relays see deterministic
+  // HMAC tokens and posting-list shape, never plaintext terms or roomIndexKey.
+  const ngramIndex = new Map(); // `${suite}:${keyId}:${token}` -> Set(targetEventId)
+  const ngramTargets = new Map(); // targetEventId -> metadata + tokenKeys
+  const ngramIndexEvents = new Map(); // indexEventId -> { targetEventId, tokenKeys }
+
+  function entryForEvent(eventId, nostrEvent) {
+    const header = parseStreamHeader(nostrEvent);
+    if (!header) return undefined;
+    return { eventId, ...header };
+  }
+
+  function parseControlPlanePayload(nostrEvent) {
+    try {
+      const kind = nostrEvent?.kind;
+      if (kind !== 9010 && kind !== 9011 && kind !== 9012 && kind !== ROOM_INDEX_NGRAM_KIND) return undefined;
+      const content = JSON.parse(nostrEvent?.content || "{}");
+      if (!content || typeof content !== "object") return undefined;
+      return content;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function foldKeyEpochEvent(nostrEvent) {
+    const payload = parseControlPlanePayload(nostrEvent);
+    if (!payload || payload.kind !== "room.key.epoch" || payload.version !== 1) return;
+    const previous = keyEpochs.get(payload.id);
+    const record = {
+      id: payload.id,
+      index: payload.index,
+      createdAt: payload.createdAt,
+      retiredAt: payload.retiredAt,
+      createdBy: payload.createdBy,
+      createdByDevice: payload.createdByDevice,
+      historyVisibility: payload.historyVisibility
+    };
+    keyEpochs.set(payload.id, record);
+    const active = activeEpochId ? keyEpochs.get(activeEpochId) : undefined;
+    if (!record.retiredAt && (!active || record.index > active.index)) {
+      activeEpochId = payload.id;
+    } else if (activeEpochId === payload.id && record.retiredAt) {
+      // Find next non-retired epoch by highest index
+      let next = null;
+      for (const epoch of keyEpochs.values()) {
+        if (!epoch.retiredAt && (!next || epoch.index > next.index)) next = epoch;
+      }
+      activeEpochId = next ? next.id : null;
+    }
+  }
+
+  function foldKeyEpochGrantEvent(nostrEvent) {
+    const payload = parseControlPlanePayload(nostrEvent);
+    if (!payload || payload.kind !== "matterhorn.key-epoch-grant" || payload.version !== 1) return;
+    let grants = epochGrants.get(payload.epochId);
+    if (!grants) {
+      grants = new Map();
+      epochGrants.set(payload.epochId, grants);
+    }
+    grants.set(payload.recipientEncryptionKeyId, nostrEvent.id);
+  }
+
+  function foldRoomIndexKeyGrantEvent(nostrEvent) {
+    const payload = parseControlPlanePayload(nostrEvent);
+    if (!payload || payload.kind !== "matterhorn.room-index-key-grant" || payload.version !== 1) return;
+    roomIndexKeyGrants.set(payload.recipientEncryptionKeyId, nostrEvent.id);
+  }
+
+
+
+  function validNgramToken(token) {
+    return typeof token === "string" && /^[A-Za-z0-9_-]{22,96}$/.test(token);
+  }
+
+  function ngramPostingKey(suite, keyId, token) {
+    return `${suite || ROOM_INDEX_NGRAM_SUITE}:${keyId || ""}:${token}`;
+  }
+
+  function eventStreamHeader(eventId) {
+    const event = events.get(eventId);
+    return event ? parseStreamHeader(event) : undefined;
+  }
+
+  function targetMetadata(payload) {
+    const fromEvent = eventStreamHeader(payload.targetEventId);
+    return {
+      targetEventId: payload.targetEventId,
+      targetOperationId: payload.targetOperationId || fromEvent?.opId || "",
+      stream: payload.stream || fromEvent?.stream || "",
+      hlc: payload.targetHlc || fromEvent?.hlc || "",
+      suite: payload.suite || ROOM_INDEX_NGRAM_SUITE,
+      keyId: payload.keyId || "",
+      field: payload.field || "",
+      tokenCount: Number.isInteger(payload.tokenCount) ? payload.tokenCount : 0,
+      tokenDigest: payload.tokenDigest || "",
+      indexedAt: Number.isInteger(payload.createdAt) ? payload.createdAt : 0
+    };
+  }
+
+  function ensureNgramTarget(targetEventId, payload) {
+    const next = targetMetadata(payload);
+    const current = ngramTargets.get(targetEventId);
+    if (!current) {
+      ngramTargets.set(targetEventId, { ...next, tokenKeys: new Set(), indexEventIds: new Set() });
+      return ngramTargets.get(targetEventId);
+    }
+    for (const [key, value] of Object.entries(next)) {
+      if (value !== "" && value !== 0) current[key] = value;
+    }
+    return current;
+  }
+
+  function foldRoomIndexNgramEvent(nostrEvent) {
+    const payload = parseControlPlanePayload(nostrEvent);
+    if (!payload || payload.kind !== ROOM_INDEX_NGRAM_PAYLOAD_KIND || payload.version !== 1) return;
+    if (payload.suite !== ROOM_INDEX_NGRAM_SUITE) return;
+    if (roomName && payload.roomName && payload.roomName !== roomName) return;
+    if (typeof payload.targetEventId !== "string" || !/^[0-9a-f]{64}$/i.test(payload.targetEventId)) return;
+    if (typeof payload.keyId !== "string" || !payload.keyId) return;
+    if (!Array.isArray(payload.tokens) || payload.tokens.length === 0) return;
+    if (ngramIndexEvents.has(nostrEvent.id)) return;
+
+    const target = ensureNgramTarget(payload.targetEventId, payload);
+    const tokenKeys = new Set();
+    for (const token of payload.tokens) {
+      if (!validNgramToken(token)) continue;
+      const key = ngramPostingKey(payload.suite, payload.keyId, token);
+      tokenKeys.add(key);
+      target.tokenKeys.add(key);
+      let postings = ngramIndex.get(key);
+      if (!postings) {
+        postings = new Set();
+        ngramIndex.set(key, postings);
+      }
+      const before = postings.size;
+      postings.add(payload.targetEventId);
+      if (postings.size !== before) stats.ngramPostings += 1;
+    }
+    if (tokenKeys.size === 0) {
+      if (target.tokenKeys.size === 0 && target.indexEventIds.size === 0) ngramTargets.delete(payload.targetEventId);
+      return;
+    }
+    target.indexEventIds.add(nostrEvent.id);
+    ngramIndexEvents.set(nostrEvent.id, { targetEventId: payload.targetEventId, tokenKeys });
+    stats.ngramIndexEvents += 1;
+  }
+
+  function currentNgramPostingCount() {
+    let total = 0;
+    for (const postings of ngramIndex.values()) total += postings.size;
+    return total;
+  }
+
+  function pruneNgramPostingKey(key) {
+    const postings = ngramIndex.get(key);
+    if (postings && postings.size === 0) ngramIndex.delete(key);
+  }
+
+  function removeNgramIndexEvent(indexEventId) {
+    const record = ngramIndexEvents.get(indexEventId);
+    if (!record) return;
+    const target = ngramTargets.get(record.targetEventId);
+    for (const key of record.tokenKeys) {
+      const postings = ngramIndex.get(key);
+      if (postings) {
+        postings.delete(record.targetEventId);
+        pruneNgramPostingKey(key);
+      }
+      target?.tokenKeys?.delete?.(key);
+    }
+    target?.indexEventIds?.delete?.(indexEventId);
+    ngramIndexEvents.delete(indexEventId);
+    if (target && target.indexEventIds.size === 0) ngramTargets.delete(record.targetEventId);
+  }
+
+  function removeNgramTarget(targetEventId) {
+    const target = ngramTargets.get(targetEventId);
+    if (!target) return;
+    for (const key of target.tokenKeys || []) {
+      const postings = ngramIndex.get(key);
+      if (postings) {
+        postings.delete(targetEventId);
+        pruneNgramPostingKey(key);
+      }
+    }
+    for (const indexEventId of target.indexEventIds || []) ngramIndexEvents.delete(indexEventId);
+    ngramTargets.delete(targetEventId);
+  }
+
+  function removeSecondaryIndexesForEvent(eventId) {
+    if (ngramIndexEvents.has(eventId)) removeNgramIndexEvent(eventId);
+    if (ngramTargets.has(eventId)) removeNgramTarget(eventId);
+  }
+
+  function foldControlPlaneEvent(nostrEvent) {
+    const kind = nostrEvent?.kind;
+    if (kind === 9010) foldKeyEpochEvent(nostrEvent);
+    else if (kind === 9011) foldKeyEpochGrantEvent(nostrEvent);
+    else if (kind === 9012) foldRoomIndexKeyGrantEvent(nostrEvent);
+    else if (kind === ROOM_INDEX_NGRAM_KIND) foldRoomIndexNgramEvent(nostrEvent);
+  }
+
+  function ensureStream(name) {
+    let list = streams.get(name);
+    if (!list) {
+      list = [];
+      streams.set(name, list);
+      streamWriters.set(name, new Set());
+    }
+    return list;
+  }
+
+  function insert(nostrEvent) {
+    const eventId = nostrEvent?.id;
+    if (!eventId || typeof eventId !== "string") {
+      return { ok: false, reason: "missing-event-id" };
+    }
+    if (events.has(eventId)) {
+      stats.duplicates += 1;
+      return { ok: true, inserted: false, eventId };
+    }
+
+    const kind = nostrEvent?.kind;
+    const isControlPlane = kind === 9010 || kind === 9011 || kind === 9012 || kind === ROOM_INDEX_NGRAM_KIND;
+
+    function controlPlaneHlc() {
+      // Use a stable, monotonic HLC for control-plane deduplication.
+      // For key-epoch events, embed the index so retirement updates supersede.
+      controlPlaneCounter += 1;
+      const payload = parseControlPlanePayload(nostrEvent);
+      const index = Number.isInteger(payload?.index) ? payload.index : 0;
+      return `${String(index).padStart(8, "0")}:${String(nostrEvent.created_at || 0).padStart(16, "0")}:${String(controlPlaneCounter).padStart(16, "0")}`;
+    }
+    const entry = isControlPlane ? { eventId, stream: `_ctl:${kind}`, hlc: controlPlaneHlc(), writer: nostrEvent.pubkey || "", device: "", seq: 0, opId: "", plugin: "", type: "", action: "", role: "", epoch: "" } : entryForEvent(eventId, nostrEvent);
+    if (!entry) {
+      return { ok: false, reason: "missing-stream-header" };
+    }
+    const list = ensureStream(entry.stream);
+    const writers = streamWriters.get(entry.stream);
+    if (writers) writers.add(entry.writer);
+
+    // Deduplicate by (stream, hlc, writer, seq) — keep first-seen eventId.
+    const existingIndex = list.findIndex((e) =>
+      e.hlc === entry.hlc && e.writer === entry.writer && e.seq === entry.seq
+    );
+    if (existingIndex >= 0) {
+      stats.duplicates += 1;
+      return { ok: true, inserted: false, eventId: list[existingIndex].eventId };
+    }
+
+    binarySearchInsert(list, entry, compareIndexEntries);
+    events.set(eventId, nostrEvent);
+    stats.inserts += 1;
+
+    foldControlPlaneEvent(nostrEvent);
+
+    if (list.length > maxEventsPerStream) {
+      const removed = list.shift();
+      if (removed) {
+        removeSecondaryIndexesForEvent(removed.eventId);
+        events.delete(removed.eventId);
+        stats.evictions += 1;
+      }
+    }
+
+    return { ok: true, inserted: true, eventId };
+  }
+
+  function has(eventId) {
+    return events.has(eventId);
+  }
+
+  function get(eventId) {
+    return events.get(eventId);
+  }
+
+  function listStreams() {
+    return Array.from(streams.keys()).sort();
+  }
+
+  function streamWritersFor(stream) {
+    return Array.from(streamWriters.get(stream) || new Set()).sort();
+  }
+
+  function queryOptions(options = {}) {
+    const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 1000;
+    const offset = Number.isInteger(options.offset) && options.offset >= 0 ? options.offset : 0;
+    return { limit, offset };
+  }
+
+  function rangeQuery(stream, options = {}) {
+    const list = streams.get(stream);
+    if (!list || list.length === 0) return { events: [] };
+    const { limit, offset } = queryOptions(options);
+    const sinceHlc = options.sinceHlc;
+    const untilHlc = options.untilHlc;
+    const beforeHlc = options.beforeHlc;
+
+    // beforeHlc is a convenience for "load more above" pagination: return the
+    // most recent `limit` events strictly before `beforeHlc`, ordered oldest-first.
+    if (typeof beforeHlc === "string" && beforeHlc.length > 0) {
+      const firstAtOrAfter = list.findIndex((e) => String(e.hlc).localeCompare(beforeHlc) >= 0);
+      const end = firstAtOrAfter < 0 ? list.length : firstAtOrAfter;
+      const start = Math.max(0, end - limit);
+      const slice = list.slice(start, end);
+      return { events: slice.map((e) => e.eventId), total: end };
+    }
+
+    let start = 0;
+    if (typeof sinceHlc === "string" && sinceHlc.length > 0) {
+      start = list.findIndex((e) => String(e.hlc).localeCompare(sinceHlc) >= 0);
+      if (start < 0) start = list.length;
+    }
+    let end = list.length;
+    if (typeof untilHlc === "string" && untilHlc.length > 0) {
+      const firstAfter = list.findIndex((e) => String(e.hlc).localeCompare(untilHlc) > 0);
+      end = firstAfter < 0 ? list.length : firstAfter;
+    }
+
+    const slice = list.slice(start, end).slice(offset, offset + limit);
+    return { events: slice.map((e) => e.eventId), total: end - start };
+  }
+
+  function headQuery(stream, options = {}) {
+    const list = streams.get(stream);
+    if (!list || list.length === 0) return { events: [] };
+    const { limit } = queryOptions(options);
+    return { events: list.slice(-limit).map((e) => e.eventId) };
+  }
+
+  function latestHlc(stream) {
+    const list = streams.get(stream);
+    if (!list || list.length === 0) return undefined;
+    return list[list.length - 1].hlc;
+  }
+
+  function streamEvents(stream) {
+    const list = streams.get(stream);
+    if (!list) return [];
+    return list.map((e) => events.get(e.eventId)).filter(Boolean);
+  }
+
+  function createNegentropySession(stream) {
+    const list = streams.get(stream);
+    const sessionEvents = list ? list.map((e) => events.get(e.eventId)).filter(Boolean) : [];
+    return createStreamNegentropySession(stream, sessionEvents);
+  }
+
+  function snapshot() {
+    return {
+      roomName,
+      events: Array.from(events.values()),
+      keyEpochs: Array.from(keyEpochs.entries()),
+      activeEpochId,
+      epochGrants: Array.from(epochGrants.entries()).map(([epochId, map]) => [epochId, Array.from(map.entries())]),
+      roomIndexKeyGrants: Array.from(roomIndexKeyGrants.entries()),
+      stats: { ...stats }
+    };
+  }
+
+  function restore(data) {
+    if (!data || !Array.isArray(data.events)) return { ok: false, reason: "invalid-snapshot" };
+    events.clear();
+    streams.clear();
+    streamWriters.clear();
+    keyEpochs.clear();
+    epochGrants.clear();
+    roomIndexKeyGrants.clear();
+    ngramIndex.clear();
+    ngramTargets.clear();
+    ngramIndexEvents.clear();
+    activeEpochId = null;
+    controlPlaneCounter = 0;
+    stats.inserts = 0;
+    stats.duplicates = 0;
+    stats.evictions = 0;
+    stats.ngramIndexEvents = 0;
+    stats.ngramPostings = 0;
+    let inserted = 0;
+    for (const event of data.events) {
+      const result = insert(event);
+      if (result.ok && result.inserted) inserted += 1;
+    }
+    if (Array.isArray(data.keyEpochs)) {
+      for (const [epochId, epoch] of data.keyEpochs) keyEpochs.set(epochId, epoch);
+    }
+    if (typeof data.activeEpochId === "string") activeEpochId = data.activeEpochId;
+    if (Array.isArray(data.epochGrants)) {
+      for (const [epochId, entries] of data.epochGrants) {
+        const map = new Map();
+        for (const [keyId, eventId] of entries) map.set(keyId, eventId);
+        epochGrants.set(epochId, map);
+      }
+    }
+    if (Array.isArray(data.roomIndexKeyGrants)) {
+      for (const [keyId, eventId] of data.roomIndexKeyGrants) roomIndexKeyGrants.set(keyId, eventId);
+    }
+    return { ok: true, inserted };
+  }
+
+
+
+  function targetForSearch(eventId) {
+    const target = ngramTargets.get(eventId);
+    if (target) {
+      const header = (!target.stream || !target.hlc) ? eventStreamHeader(eventId) : undefined;
+      return {
+        eventId,
+        stream: target.stream || header?.stream || "",
+        hlc: target.hlc || header?.hlc || "",
+        targetOperationId: target.targetOperationId || header?.opId || "",
+        field: target.field || "",
+        indexedAt: target.indexedAt || 0
+      };
+    }
+    const header = eventStreamHeader(eventId);
+    return { eventId, stream: header?.stream || "", hlc: header?.hlc || "", targetOperationId: header?.opId || "", field: "", indexedAt: 0 };
+  }
+
+  function compareSearchMatches(left, right, order) {
+    if (order === "score") {
+      const scoreDiff = (right.score || 0) - (left.score || 0);
+      if (scoreDiff !== 0) return scoreDiff;
+      const matchedDiff = (right.matchedTokens || 0) - (left.matchedTokens || 0);
+      if (matchedDiff !== 0) return matchedDiff;
+    }
+    const hlcOrder = String(right.hlc || "").localeCompare(String(left.hlc || ""));
+    if (hlcOrder !== 0) return hlcOrder;
+    const indexedDiff = (right.indexedAt || 0) - (left.indexedAt || 0);
+    if (indexedDiff !== 0) return indexedDiff;
+    return String(left.eventId).localeCompare(String(right.eventId));
+  }
+
+  function searchNgrams(options = {}) {
+    const rawTokens = Array.isArray(options.tokens) ? options.tokens.filter(validNgramToken) : [];
+    const tokens = Array.from(new Set(rawTokens));
+    if (tokens.length === 0) return { events: [], matches: [], total: 0, queryTokenCount: 0 };
+    const suite = options.suite || ROOM_INDEX_NGRAM_SUITE;
+    const keyId = typeof options.keyId === "string" ? options.keyId : "";
+    const stream = typeof options.stream === "string" && options.stream ? options.stream : undefined;
+    const mode = options.mode === "any" || options.mode === "threshold" ? options.mode : "all";
+    const order = options.order === "score" ? "score" : "newest";
+    const minScore = Number.isFinite(options.minScore) ? Math.max(0, Math.min(1, Number(options.minScore))) : (mode === "threshold" ? 0.5 : 0);
+    const limit = Number.isInteger(options.limit) && options.limit > 0 ? Math.min(options.limit, 1000) : 100;
+    const offset = Number.isInteger(options.offset) && options.offset >= 0 ? options.offset : 0;
+    const postingKeys = tokens.map((token) => ngramPostingKey(suite, keyId, token));
+    const matchesByEvent = new Map();
+
+    if (mode === "all") {
+      const postingSets = postingKeys
+        .map((key) => ngramIndex.get(key) || new Set())
+        .sort((left, right) => left.size - right.size);
+      if (postingSets.length === 0 || postingSets[0].size === 0) return { events: [], matches: [], total: 0, queryTokenCount: tokens.length };
+      const candidateIds = new Set(postingSets[0]);
+      for (const postings of postingSets.slice(1)) {
+        for (const eventId of Array.from(candidateIds)) {
+          if (!postings.has(eventId)) candidateIds.delete(eventId);
+        }
+        if (candidateIds.size === 0) break;
+      }
+      for (const eventId of candidateIds) matchesByEvent.set(eventId, tokens.length);
+    } else {
+      for (const key of postingKeys) {
+        const postings = ngramIndex.get(key);
+        if (!postings) continue;
+        for (const eventId of postings) matchesByEvent.set(eventId, (matchesByEvent.get(eventId) || 0) + 1);
+      }
+    }
+
+    const matches = [];
+    for (const [eventId, matchedTokens] of matchesByEvent) {
+      const target = targetForSearch(eventId);
+      if (stream && target.stream !== stream) continue;
+      const score = tokens.length === 0 ? 0 : matchedTokens / tokens.length;
+      if (mode !== "all" && score < minScore) continue;
+      matches.push({
+        eventId,
+        score,
+        matchedTokens,
+        queryTokenCount: tokens.length,
+        stream: target.stream,
+        hlc: target.hlc,
+        targetOperationId: target.targetOperationId,
+        field: target.field,
+        indexedAt: target.indexedAt
+      });
+    }
+
+    matches.sort((left, right) => compareSearchMatches(left, right, order));
+    const slice = matches.slice(offset, offset + limit);
+    return { events: slice.map((match) => match.eventId), matches: slice, total: matches.length, queryTokenCount: tokens.length };
+  }
+
+  function ngramIndexStats() {
+    return {
+      targets: ngramTargets.size,
+      indexEvents: ngramIndexEvents.size,
+      tokenPostingLists: ngramIndex.size,
+      postings: currentNgramPostingCount()
+    };
+  }
+
+  function activeKeyEpoch() {
+    if (!activeEpochId) return undefined;
+    const epoch = keyEpochs.get(activeEpochId);
+    if (!epoch) return undefined;
+    return { ...epoch };
+  }
+
+  function listKeyEpochs() {
+    return Array.from(keyEpochs.values()).sort((a, b) => a.index - b.index).map((e) => ({ ...e }));
+  }
+
+  function listEpochGrantRecipients(epochId) {
+    const grants = epochGrants.get(epochId);
+    if (!grants) return [];
+    return Array.from(grants.keys());
+  }
+
+  function listRoomIndexKeyGrantRecipients() {
+    return Array.from(roomIndexKeyGrants.keys());
+  }
+
+  function keyEpochForIngress(epochId) {
+    if (!epochId) return activeKeyEpoch();
+    const epoch = keyEpochs.get(epochId);
+    return epoch ? { ...epoch } : undefined;
+  }
+
+  return {
+    insert,
+    has,
+    get,
+    listStreams,
+    streamWritersFor,
+    rangeQuery,
+    headQuery,
+    latestHlc,
+    streamEvents,
+    searchNgrams,
+    ngramIndexStats,
+    createNegentropySession,
+    snapshot,
+    restore,
+    activeKeyEpoch,
+    listKeyEpochs,
+    listEpochGrantRecipients,
+    listRoomIndexKeyGrantRecipients,
+    keyEpochForIngress,
+    get stats() { return { ...stats }; }
+  };
+}
+
+module.exports = {
+  createEncryptedRoomRuntime,
+  parseStreamHeader
+};