@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/matrix/group-chat.ts

@@ -91,6 +91,11 @@ export const DEFAULT_REQUIRE_POWER_LEVEL = 0;
 export const COMPACT_BUFFER_THRESHOLD = 20;
 export const COMPACT_JIT_MIN = 5;
 export const COMPACT_JIT_TIMEOUT_MS = 3000;
+/** The oldest messages one summary covers at most; a longer buffer is compacted over several runs. */
+export const COMPACT_BATCH_MAX = 50;
+/** After a failed summary a room's automatic compaction waits this long, doubling per failure up to the max. */
+export const COMPACT_RETRY_MIN_MS = 60_000;
+export const COMPACT_RETRY_MAX_MS = 30 * 60_000;
 export const RECALL_DEFAULT_CHUNKS = 10;
 export const RECALL_MAX_CHUNKS = 30;
 export const PINNED_FACT_MAX_CHARS = 500;
@@ -508,13 +513,13 @@ export class GroupChatStore {
   }
 
   deletePinnedFact(roomId: string, factId: string): boolean {
-    const before = this.countFacts(roomId);
-    this.sql.exec(
-      `DELETE FROM group_pinned_facts WHERE room_id = ? AND id = ?`,
-      roomId,
-      factId,
+    return (
+      this.sql.exec(
+        `DELETE FROM group_pinned_facts WHERE room_id = ? AND id = ?`,
+        roomId,
+        factId,
+      ).rowsWritten > 0
     );
-    return this.countFacts(roomId) < before;
   }
 
   countFacts(roomId?: string): number {
@@ -568,21 +573,23 @@ export class GroupChatStore {
 
   /** Buffer a message for compaction; false when the event was already buffered (a replay). */
   bufferAppend(roomId: string, msg: ObservedMessage): boolean {
-    const before = this.bufferCount(roomId);
-    this.sql.exec(
-      `INSERT OR IGNORE INTO group_message_buffer
+    // An ignored duplicate writes nothing; an insert writes its row (and
+    // its index entries).
+    return (
+      this.sql.exec(
+        `INSERT OR IGNORE INTO group_message_buffer
         (event_id, room_id, thread_id, sender_did, sender_user_id, display_name, body, ts)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-      msg.eventId,
-      roomId,
-      msg.threadId,
-      msg.senderDid,
-      msg.senderMatrixUserId,
-      msg.senderDisplayName,
-      msg.body,
-      msg.timestamp,
+        msg.eventId,
+        roomId,
+        msg.threadId,
+        msg.senderDid,
+        msg.senderMatrixUserId,
+        msg.senderDisplayName,
+        msg.body,
+        msg.timestamp,
+      ).rowsWritten > 0
     );
-    return this.bufferCount(roomId) > before;
   }
 
   bufferCount(roomId?: string): number {
@@ -601,12 +608,13 @@ export class GroupChatStore {
     return Number(rows[0]?.n ?? 0);
   }
 
-  /** The room's buffered messages, oldest first. */
-  bufferRows(roomId: string): ObservedMessage[] {
+  /** The room's buffered messages, oldest first (at most `limit`). */
+  bufferRows(roomId: string, limit = COMPACT_BATCH_MAX): ObservedMessage[] {
     return this.sql
       .exec<BufferRow>(
-        `SELECT * FROM group_message_buffer WHERE room_id = ? ORDER BY ts ASC, rowid ASC`,
+        `SELECT * FROM group_message_buffer WHERE room_id = ? ORDER BY ts ASC, rowid ASC LIMIT ?`,
         roomId,
+        limit,
       )
       .toArray()
       .map(rowToObserved);
@@ -760,6 +768,11 @@ export class GroupChatService {
   >();
   private readonly activeThreads = new Map<string, number>();
   private readonly compacting = new Map<string, Promise<void>>();
+  /** Rooms whose last summary failed: no automatic compaction before `until`. */
+  private readonly compactBackoff = new Map<
+    string,
+    { until: number; delayMs: number }
+  >();
   private readonly now: () => number;
 
   constructor(
@@ -1013,7 +1026,10 @@ export class GroupChatService {
 
   observe(roomId: string, message: ObservedMessage): void {
     if (!this.store.bufferAppend(roomId, message)) return;
-    if (this.store.bufferCount(roomId) >= COMPACT_BUFFER_THRESHOLD)
+    if (
+      this.compactDue(roomId) &&
+      this.store.bufferCount(roomId) >= COMPACT_BUFFER_THRESHOLD
+    )
       this.deps.keepAlive(
         this.compact(roomId).catch((err: unknown) =>
           this.deps.log(
@@ -1027,6 +1043,7 @@ export class GroupChatService {
 
   /** Compact a buffer of ≥ 5 before the bot answers, bounded so the reply is not held up. */
   async compactJustInTime(roomId: string): Promise<void> {
+    if (!this.compactDue(roomId)) return;
     if (this.store.bufferCount(roomId) < COMPACT_JIT_MIN) return;
     const work = this.compact(roomId).catch((err: unknown) =>
       this.deps.log(
@@ -1053,19 +1070,45 @@ export class GroupChatService {
     return work;
   }
 
+  /**
+   * Whether automatic compaction (threshold, just in time) may run for the
+   * room: not while it backs off after a failed summary, so a model outage
+   * costs one summary call per back-off window, not one per message.
+   */
+  private compactDue(roomId: string): boolean {
+    const backoff = this.compactBackoff.get(roomId);
+    return !backoff || backoff.until <= this.now();
+  }
+
+  private noteCompactFailure(roomId: string): void {
+    const previous = this.compactBackoff.get(roomId)?.delayMs;
+    const delayMs = previous
+      ? Math.min(previous * 2, COMPACT_RETRY_MAX_MS)
+      : COMPACT_RETRY_MIN_MS;
+    this.compactBackoff.set(roomId, { until: this.now() + delayMs, delayMs });
+  }
+
   private async compactInner(roomId: string): Promise<void> {
     const drained = this.store.bufferRows(roomId);
     const first = drained[0];
     const last = drained[drained.length - 1];
     if (!first || !last) return;
-    const summary = await this.deps.summarize(drained);
+    let summary: string | null;
+    try {
+      summary = await this.deps.summarize(drained);
+    } catch (err) {
+      this.noteCompactFailure(roomId);
+      throw err;
+    }
     if (!summary) {
+      this.noteCompactFailure(roomId);
       this.deps.log(
         'warn',
         `[group-chat] summary unavailable; ${drained.length} messages stay buffered for ${roomId}`,
       );
       return;
     }
+    this.compactBackoff.delete(roomId);
     const chunk: ChannelMemoryChunk = {
       id: crypto.randomUUID(),
       roomId,

package/src/matrix/inbox-store.ts

@@ -16,7 +16,7 @@
  * Cost shape (SQLite-backed Durable Object storage bills rows written and
  * read): one row written on receipt, one delete when the turn ends.
  */
-import type { InboundAttachment, InboundMessage } from './ingest';
+import type { InboundAttachment, InboundMessage, OfferOutcome } from './ingest';
 import { matrixTxnId } from './txn-id';
 
 export interface InboxRow extends InboundMessage {
@@ -103,6 +103,21 @@ export function deleteInboxRows(sql: SqlStorage, eventIds: string[]): void {
     sql.exec(`DELETE FROM turn_inbox WHERE event_id = ?`, id);
 }
 
+/**
+ * The inbox row of a message after its offer: a queued message keeps it until
+ * its turn ends, an unverified one (the sender's homeserver could not be
+ * looked up) keeps it for the next replay, and a dropped one leaves at once.
+ */
+export function settleOfferedRow(
+  sql: SqlStorage,
+  eventId: string,
+  outcome: OfferOutcome,
+): 'kept' | 'deleted' {
+  if (outcome === 'queued' || outcome === 'unverified') return 'kept';
+  deleteInboxRows(sql, [eventId]);
+  return 'deleted';
+}
+
 export function bumpInboxAttempts(sql: SqlStorage, eventIds: string[]): void {
   for (const id of eventIds)
     sql.exec(

package/src/matrix/ingest.ts

@@ -75,6 +75,15 @@ export interface IngestTurn {
 export interface IngestDeps {
   /** The DID that forms the oracle half of the user↔oracle room alias. */
   oracleDid: string;
+  /**
+   * The Matrix server name the user's DID document registers, lowercased;
+   * null when it is not known. Synchronous like `canonicalAlias`: the gateway
+   * resolves it before the offer. A message whose attributed identity was
+   * minted on any other server is dropped (`'foreign'`); with no known server
+   * there is no verdict (`'unverified'`) and the gateway keeps the message
+   * for a later attempt.
+   */
+  userServerName(userDid: string): string | null;
   /**
    * The bot's Matrix user id. Its first occurrence in a message is rewritten
    * to `(USER MENTIONED YOU @AI_AGENT)` before the agent sees it, as the Node
@@ -129,25 +138,65 @@ export function userDidFromRoomAlias(
   return aliasPartToDid(local.slice(0, -suffix.length));
 }
 
+/** The server name of a Matrix user id or room alias (`@a:server` → `server`), lowercased; null without one. */
+export function serverNameOf(matrixId: string): string | null {
+  const colon = matrixId.indexOf(':');
+  if (colon === -1) return null;
+  const server = matrixId.slice(colon + 1).toLowerCase();
+  return server || null;
+}
+
+/** Whose turn a message is, and the server that identity was minted on. */
+export interface UserAttribution {
+  userDid: string;
+  /**
+   * The server the identity came from: the sender's for a DID-shaped sender,
+   * the alias's for a non-DID sender attributed to the room's owner. It must
+   * be the user's registered homeserver — anyone can register
+   * `@did-ixo-<someone>` on a server of their own, and a Matrix localpart
+   * says nothing about who controls the DID.
+   */
+  server: string | null;
+}
+
 /**
  * Who is the user for this message? The canonical alias names the room's
  * owner; the sender's localpart names the speaker. They agree in a 1:1
  * oracle room. When the speaker is DID-shaped but differs from the room
  * owner (a third member invited into the room), the SPEAKER wins — a turn
  * must never run inside another user's object. A non-DID sender in an
- * owner's room is attributed to the owner (legacy / non-DID accounts).
+ * owner's room is attributed to the owner (legacy / non-DID accounts), but
+ * only when the sender's account lives on the alias's own server: an
+ * account on any other server is someone else, whatever the room says.
+ *
+ * `alias` must be one the caller verified (the alias resolves to this very
+ * room on its homeserver — `room-alias.ts`): a room's canonical-alias state
+ * is written by its members and proves nothing on its own.
  */
+export function attributeUser(opts: {
+  alias: string | null;
+  sender: string;
+  oracleDid: string;
+}): UserAttribution | null {
+  const fromSender = matrixUserIdToDid(opts.sender);
+  if (fromSender) {
+    return { userDid: fromSender, server: serverNameOf(opts.sender) };
+  }
+  if (!opts.alias) return null;
+  const fromAlias = userDidFromRoomAlias(opts.alias, opts.oracleDid);
+  const aliasServer = serverNameOf(opts.alias);
+  if (!fromAlias || !aliasServer) return null;
+  if (serverNameOf(opts.sender) !== aliasServer) return null;
+  return { userDid: fromAlias, server: aliasServer };
+}
+
+/** The DID `attributeUser` names, without the server it came from. */
 export function resolveUserDid(opts: {
   alias: string | null;
   sender: string;
   oracleDid: string;
 }): string | null {
-  const fromSender = matrixUserIdToDid(opts.sender);
-  const fromAlias = opts.alias
-    ? userDidFromRoomAlias(opts.alias, opts.oracleDid)
-    : null;
-  if (fromSender && fromAlias && fromSender !== fromAlias) return fromSender;
-  return fromAlias ?? fromSender;
+  return attributeUser(opts)?.userDid ?? null;
 }
 
 /** The thread a message belongs to: its resolved root, else the message itself. */
@@ -157,6 +206,13 @@ export function threadRootIdOf(
   return msg.threadRootId ?? msg.eventId;
 }
 
+export type OfferOutcome =
+  | 'queued'
+  | 'unverified'
+  | 'empty'
+  | 'unmapped'
+  | 'foreign';
+
 export class IngestPipeline {
   private readonly pending = new Map<string, Pending>();
   private readonly debounceMs: number;
@@ -166,19 +222,28 @@ export class IngestPipeline {
   }
 
   /**
-   * Offer a decrypted message. Returns the reason it was dropped, or
-   * `'queued'` when it entered the debounce buffer.
+   * Offer a decrypted message. Returns the reason it was dropped, `'queued'`
+   * when it entered the debounce buffer, or `'unverified'` when the sender's
+   * registered homeserver is not known — neither queued nor dropped.
+   * `alias`: the room's verified alias as the caller just checked it (null
+   * for none); omitted, `canonicalAlias` is asked.
    */
-  offer(msg: InboundMessage): 'queued' | 'empty' | 'unmapped' {
+  offer(msg: InboundMessage, alias?: string | null): OfferOutcome {
     if (!msg.body.trim() && !msg.attachment) return 'empty';
-    const userDid = resolveUserDid({
-      alias: this.deps.canonicalAlias(msg.roomId),
+    const attribution = attributeUser({
+      alias: alias === undefined ? this.deps.canonicalAlias(msg.roomId) : alias,
       sender: msg.sender,
       oracleDid: this.deps.oracleDid,
     });
-    if (!userDid) return 'unmapped';
+    if (!attribution) return 'unmapped';
+    const { userDid } = attribution;
+    const registered = this.deps.userServerName(userDid);
+    if (!registered) return 'unverified';
+    if (attribution.server !== registered) return 'foreign';
 
-    const key = `${msg.roomId}|${threadRootIdOf(msg)}`;
+    // Per speaker as well as per thread: two members typing in one thread of
+    // a group room are two turns, each in its own user's object.
+    const key = `${msg.roomId}|${threadRootIdOf(msg)}|${userDid}`;
     const existing = this.pending.get(key);
     if (existing) {
       clearTimeout(existing.timer);

package/src/matrix/media-deadline.ts

@@ -0,0 +1,130 @@
+/**
+ * Deadlines for the gateway's media downloads. A homeserver that stops
+ * sending mid-body would otherwise keep the reading side — a user object
+ * assembling an attachment for a turn — waiting for as long as the
+ * connection stays open.
+ *
+ * The bound covers the whole transfer: opening the download and every byte
+ * of the body. When it passes (or the caller's own signal aborts), the
+ * source is cancelled and the stream handed out errors with the reason.
+ */
+
+export interface BoundedSignal {
+  signal: AbortSignal;
+  /** Stop the timer (the transfer finished or failed on its own). */
+  clear(): void;
+}
+
+/** Error a download fails with when its deadline passes. */
+export class MediaDownloadTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`media download timed out after ${timeoutMs} ms`);
+    this.name = 'MediaDownloadTimeoutError';
+  }
+}
+
+/**
+ * A signal that aborts after `timeoutMs`, or as soon as `signal` does. The
+ * timer is a plain timeout so it can be cleared the moment the transfer ends
+ * (a pending timer keeps a Durable Object resident).
+ */
+export function boundedSignal(
+  timeoutMs: number,
+  signal?: AbortSignal,
+): BoundedSignal {
+  const controller = new AbortController();
+  const onCallerAbort = (): void => controller.abort(signal?.reason);
+  const timer = setTimeout(
+    () => controller.abort(new MediaDownloadTimeoutError(timeoutMs)),
+    timeoutMs,
+  );
+  const clear = (): void => {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', onCallerAbort);
+  };
+  if (signal?.aborted) {
+    clear();
+    controller.abort(signal.reason);
+  } else signal?.addEventListener('abort', onCallerAbort, { once: true });
+  controller.signal.addEventListener('abort', clear, { once: true });
+  return { signal: controller.signal, clear };
+}
+
+/** The signal's reason as an Error (a `DOMException` reason already is one). */
+function abortReason(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+
+/**
+ * Settle with `work`, or reject with the signal's reason when it aborts
+ * first. A result that arrives after the abort is handed to `discard` so a
+ * stream opened too late is still released.
+ */
+export function raceSignal<T>(
+  work: Promise<T>,
+  signal: AbortSignal,
+  discard: (late: T) => void,
+): Promise<T> {
+  if (signal.aborted) {
+    void work.then(discard, () => undefined);
+    return Promise.reject(abortReason(signal));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      void work.then(discard, () => undefined);
+      reject(abortReason(signal));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    work.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        if (signal.aborted) discard(value);
+        else resolve(value);
+      },
+      (err: unknown) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+/**
+ * `source` behind the deadline: the returned stream carries the same bytes,
+ * and errors with the signal's reason (the source cancelled) when the bound
+ * passes before the last byte. The timer is cleared once the transfer ends
+ * either way, including when the reader cancels.
+ */
+export function streamWithDeadline(
+  source: ReadableStream<Uint8Array>,
+  bound: BoundedSignal,
+): ReadableStream<Uint8Array> {
+  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
+  const writer = writable.getWriter();
+  const reader = source.getReader();
+  const stop = (reason: unknown): void => {
+    void writer.abort(reason).catch(() => undefined);
+    void reader.cancel(reason).catch(() => undefined);
+  };
+  const onAbort = (): void => stop(bound.signal.reason);
+  if (bound.signal.aborted) onAbort();
+  else bound.signal.addEventListener('abort', onAbort, { once: true });
+  void (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done || bound.signal.aborted) break;
+        await writer.write(value);
+      }
+      if (!bound.signal.aborted) await writer.close();
+    } catch (err) {
+      // The reader went away (cancelled) or the source failed: end both.
+      stop(err);
+    } finally {
+      bound.signal.removeEventListener('abort', onAbort);
+      bound.clear();
+    }
+  })();
+  return readable;
+}

package/src/matrix/replay-format.ts

@@ -2,9 +2,11 @@
  * Room replay formatting — a port of `@ixo/matrix`'s `formatMsg`. The Node
  * runtime replays every HTTP/SSE turn into the user's oracle room as a thread
  * under the session's root event: the user message prefixed `**You:**`, the
- * reply prefixed with the oracle's name, both rendered to HTML with marked.
+ * reply prefixed with the oracle's name, both rendered to HTML with marked —
+ * with raw HTML escaped, as for every room reply (`reply-parts.ts`): the
+ * text may come from a model or a user and must not become room markup.
  */
-import { marked } from 'marked';
+import { renderRoomMarkdown } from './reply-parts';
 
 export interface FormatReplayParams {
   message: string;
@@ -29,6 +31,6 @@ export function formatReplay({
   const body = disablePrefix
     ? message
     : `**${isOracle ? oracleName : 'You'}:**\n${message}`;
-  const formattedBody = marked.parse(body, { gfm: true, async: false });
+  const formattedBody = renderRoomMarkdown(body);
   return { body, formattedBody };
 }

package/src/matrix/reply-parts.ts

@@ -0,0 +1,92 @@
+/**
+ * What the gateway posts in a Matrix room for one finished turn. Without a
+ * Reply Plan (chat style off, the default) it is the reply text as one
+ * plain `m.text`, exactly as before chat delivery existed. With a plan it is
+ * one `m.text` per part, in the thread, rendered to HTML with raw HTML from
+ * the model escaped. Each part has its own transaction id, so a replayed
+ * turn is deduplicated part by part.
+ */
+import { Marked } from 'marked';
+import type { TurnResult } from '../do/contracts';
+import { parseReplyPlan } from '../delivery/schema';
+import type { ReplyPart } from '../delivery/types';
+import { matrixTxnId } from './txn-id';
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** URL schemes a link or image in a room message may use. */
+const ALLOWED_URL = /^(?:https?|mailto|mxc):/i;
+
+/**
+ * Markdown → `formatted_body` for anything the oracle posts to a room. Raw
+ * HTML in the text (block or inline) is shown as text, never passed through
+ * as markup, and a link or image whose URL is not http(s), mailto or mxc
+ * (`javascript:`, `data:`, a relative path) is shown as its text. Returning
+ * `false` hands an allowed one to marked's own renderer.
+ */
+const safeMarkdown = new Marked({
+  gfm: true,
+  async: false,
+  renderer: {
+    html: ({ text }) => escapeHtml(text),
+    link({ href, tokens }) {
+      return ALLOWED_URL.test(href.trim())
+        ? false
+        : this.parser.parseInline(tokens);
+    },
+    image({ href, text }) {
+      return ALLOWED_URL.test(href.trim()) ? false : escapeHtml(text);
+    },
+  },
+});
+
+/** Markdown rendered to room HTML with raw HTML escaped. */
+export function renderRoomMarkdown(text: string): string {
+  return safeMarkdown.parse(text, { async: false });
+}
+
+export function replyPartContent(part: ReplyPart): {
+  body: string;
+  formattedBody: string;
+} {
+  if (part.kind === 'text')
+    return {
+      body: part.text,
+      formattedBody: renderRoomMarkdown(part.text),
+    };
+  const { title, url } = part.artifact;
+  return {
+    body: `${title}\n${url}`,
+    formattedBody: `<p><strong>${escapeHtml(title)}</strong><br><a href="${escapeHtml(url)}">Open document</a></p>`,
+  };
+}
+
+export function replyPartTxnId(eventId: string, partId: string): string {
+  return matrixTxnId('reply', eventId, partId);
+}
+
+/** One room message of a turn's reply; `partId` is set for a plan part. */
+export interface RoomReplyMessage {
+  body: string;
+  formattedBody?: string;
+  partId?: string;
+}
+
+/** The messages a finished room turn posts, in order; none for an empty reply. */
+export function roomReplyMessages(
+  result: Pick<TurnResult, 'text' | 'plan'>,
+): RoomReplyMessage[] {
+  const plan = parseReplyPlan(result.plan);
+  if (plan && plan.parts.length > 0)
+    return plan.parts.map((part) => ({
+      ...replyPartContent(part),
+      partId: part.partId,
+    }));
+  return result.text.trim() ? [{ body: result.text }] : [];
+}

package/src/matrix/room-alias.ts

@@ -0,0 +1,96 @@
+/**
+ * The user↔oracle alias a room really carries.
+ *
+ * A room's `m.room.canonical_alias` is ordinary room state: any member with
+ * the power to set it can write any alias there, and a homeserver does not
+ * check aliases that live on another server. A room created on a server of
+ * an attacker's own can therefore claim `#<victim>_<oracle>:<victim's
+ * server>`. What cannot be forged is the alias directory of the alias's own
+ * server, so an alias counts only when that server resolves it to the very
+ * same room. Anything else — no alias, an alias that resolves elsewhere or
+ * nowhere — is "no alias".
+ *
+ * Verdicts are memoised per room for a TTL and dropped when the room's alias
+ * state changes. A lookup that fails (homeserver error, rate limit) is not a
+ * verdict: it throws, nothing is memoised, and the caller retries later.
+ */
+
+export interface VerifiedRoomAliasDeps {
+  /**
+   * The room's canonical alias when it is one that matters (a user↔oracle
+   * alias of this oracle), null otherwise. Throws when the state cannot be read.
+   */
+  readCanonicalAlias(roomId: string): Promise<string | null>;
+  /** The room an alias points at in its server's directory; null when it points nowhere. Throws on any other failure. */
+  resolveAlias(alias: string): Promise<string | null>;
+  /** How long a verdict is served without asking again. */
+  ttlMs: number;
+  /** Upper bound on the rooms remembered at once (oldest dropped first). */
+  maxRooms?: number;
+  now?: () => number;
+}
+
+interface Verdict {
+  alias: string | null;
+  at: number;
+}
+
+const DEFAULT_MAX_ROOMS = 5_000;
+
+export class VerifiedRoomAliases {
+  private readonly verdicts = new Map<string, Verdict>();
+  /** Bumped by `invalidate`, so a lookup that started before a change is not memoised after it. */
+  private readonly generations = new Map<string, number>();
+  private readonly now: () => number;
+
+  constructor(private readonly deps: VerifiedRoomAliasDeps) {
+    this.now = deps.now ?? Date.now;
+  }
+
+  /** The memoised verified alias of a room; null when there is none or no fresh verdict. */
+  known(roomId: string): string | null {
+    return this.fresh(roomId)?.alias ?? null;
+  }
+
+  /** The room's verified alias (null = none). Throws when the homeserver could not be asked. */
+  async verify(roomId: string): Promise<string | null> {
+    const memo = this.fresh(roomId);
+    if (memo) return memo.alias;
+    const generation = this.generations.get(roomId) ?? 0;
+    const claimed = await this.deps.readCanonicalAlias(roomId);
+    const alias =
+      claimed !== null && (await this.deps.resolveAlias(claimed)) === roomId
+        ? claimed
+        : null;
+    if ((this.generations.get(roomId) ?? 0) === generation)
+      this.remember(roomId, alias);
+    return alias;
+  }
+
+  /** Forget the room's verdict (its alias state changed). */
+  invalidate(roomId: string): void {
+    this.verdicts.delete(roomId);
+    this.generations.set(roomId, (this.generations.get(roomId) ?? 0) + 1);
+  }
+
+  private fresh(roomId: string): Verdict | undefined {
+    const verdict = this.verdicts.get(roomId);
+    if (!verdict) return undefined;
+    if (this.now() - verdict.at >= this.deps.ttlMs) {
+      this.verdicts.delete(roomId);
+      return undefined;
+    }
+    return verdict;
+  }
+
+  private remember(roomId: string, alias: string | null): void {
+    this.verdicts.delete(roomId);
+    const max = this.deps.maxRooms ?? DEFAULT_MAX_ROOMS;
+    while (this.verdicts.size >= max) {
+      const oldest = this.verdicts.keys().next().value;
+      if (oldest === undefined) break;
+      this.verdicts.delete(oldest);
+    }
+    this.verdicts.set(roomId, { alias, at: this.now() });
+  }
+}