@ixo/oracle-runtime-workers 0.4.1 → 0.10.0

package/src/matrix/gateway-do.ts

@@ -28,6 +28,7 @@ import {
   withRateLimitRetry,
   type BotMessage,
   type MatrixBotOptions,
+  type StartResult,
 } from '@ixo/matrix-bot-workers-sdk';
 import { createClient, MatrixError, Preset, Visibility } from 'matrix-js-sdk';
 import {
@@ -42,6 +43,9 @@ import {
   type OutboxRow,
   type TurnResult,
   type UserOracleObject,
+  type MediaStream,
+  type SnapshotStream,
+  isInterruptedTurnError,
 } from '../do/contracts';
 import { decryptWithPin } from '../secrets/pin-cipher';
 import {
@@ -54,7 +58,21 @@ import {
   IngestPipeline,
   type InboundAttachment,
   type IngestTurn,
+  type InboundMessage,
 } from './ingest';
+import {
+  bumpInboxAttempts,
+  countInboxRows,
+  deleteInboxRows,
+  ensureInboxTable,
+  inboundOfRow,
+  insertInboxRow,
+  listInboxRows,
+  MAX_TURN_REPLAYS,
+  planInboxReplay,
+  replyTxnId,
+  updateInboxThread,
+} from './inbox-store';
 import {
   readRelatesTo,
   resolveReplyChainRoot,
@@ -192,6 +210,10 @@ function stateEventId(json: JsonString | null): string | undefined {
 // Durable Object
 // ---------------------------------------------------------------------------
 
+/** Posted when a room turn fails or is given up; the user resends. */
+const TURN_FAILED_NOTICE =
+  'Sorry — something went wrong while handling your message. Please try again.';
+
 export class MatrixGatewayDO
   extends MatrixBotDO<OracleWorkerEnv>
   implements MatrixGatewayObject
@@ -209,6 +231,10 @@ export class MatrixGatewayDO
   /** Memoised `getOracleSecretsKey` result (private JWK JSON). */
   private oracleSecretsKeyJson: string | null = null;
   private oracleSigningMnemonic: string | null = null;
+  private inboxTableReady = false;
+  /** Event ids of turns running in this instance (a graceful restart must not replay them). */
+  private readonly inFlightEvents = new Set<string>();
+  private inboxReplayRunning = false;
 
   // -------------------------------------------------------------------------
   // Configuration
@@ -298,26 +324,43 @@ export class MatrixGatewayDO
     const isText = message.msgtype === 'm.text';
     const isFile = FILE_MSGTYPES.has(message.msgtype);
     if (!isText && !isFile) return;
-    // Resolved before the offer so the pipeline's synchronous alias lookup
-    // (room alias → user DID) can answer from the memo.
-    await this.canonicalAliasOf(message.roomId);
-    const threadRootId = await this.threadRootFor(message, eventId);
-    const outcome = this.ingestPipeline().offer({
+    const inbound: InboundMessage = {
       eventId,
       roomId: message.roomId,
       sender: message.sender,
       ts: message.ts,
       body: isText ? message.body : '',
-      ...(threadRootId ? { threadRootId } : {}),
+      ...(message.threadRootId ? { threadRootId: message.threadRootId } : {}),
       ...(isFile
         ? { attachment: attachmentOf(content, eventId, message.body) }
         : {}),
-    });
-    if (outcome !== 'queued')
+    };
+    // Durable before anything waits on the network: the SDK has already
+    // marked the event processed, so from here on only this row brings the
+    // message back if the instance dies before its reply is in the outbox.
+    const sql = this.inboxSql();
+    insertInboxRow(sql, inbound, Date.now());
+    // Resolved before the offer so the pipeline's synchronous alias lookup
+    // (room alias → user DID) can answer from the memo.
+    await this.canonicalAliasOf(message.roomId);
+    const threadRootId = await this.threadRootFor(message, eventId);
+    if (threadRootId && threadRootId !== inbound.threadRootId) {
+      inbound.threadRootId = threadRootId;
+      updateInboxThread(sql, eventId, threadRootId);
+    }
+    this.offerInbound(inbound);
+  }
+
+  /** Feed a message into the ingest pipeline; a message it will not turn into a turn leaves the inbox at once. */
+  private offerInbound(inbound: InboundMessage): void {
+    const outcome = this.ingestPipeline().offer(inbound);
+    if (outcome !== 'queued') {
+      deleteInboxRows(this.inboxSql(), [inbound.eventId]);
       this.log(
         'debug',
-        `ingest dropped ${eventId} in ${message.roomId}: ${outcome}`,
+        `ingest dropped ${inbound.eventId} in ${inbound.roomId}: ${outcome}`,
       );
+    }
   }
 
   /**
@@ -378,6 +421,7 @@ export class MatrixGatewayDO
       'info',
       `turn ${requestId}: ${turn.userDid} in ${turn.roomId}${turn.threadId ? ` (thread ${turn.threadId})` : ''}`,
     );
+    for (const id of turn.eventIds) this.inFlightEvents.add(id);
     let typing: ReturnType<typeof setInterval> | null = null;
     try {
       await this.setTyping(turn.roomId, true, TYPING_TIMEOUT_MS);
@@ -387,29 +431,46 @@ export class MatrixGatewayDO
         );
       }, TYPING_REFRESH_MS);
       const result = await this.runTurn(turn, requestId);
-      if (result.text.trim()) {
-        await this.sendText(
-          turn.roomId,
-          result.text,
-          turn.threadId ? { threadId: turn.threadId } : undefined,
+      if (result.replayed)
+        this.log(
+          'info',
+          `turn ${requestId}: reply served from the user object's ledger (turn had already finished)`,
         );
+      if (result.text.trim()) {
+        // The transaction id is derived from the event id, so this reply is
+        // deduplicated by the homeserver if a previous incarnation already
+        // sent it before it died (see inbox-store.ts).
+        await this.sendText(turn.roomId, result.text, {
+          ...(turn.threadId ? { threadId: turn.threadId } : {}),
+          ...(turn.eventIds[0] ? { txnId: replyTxnId(turn.eventIds[0]) } : {}),
+        });
       } else {
         this.log('info', `turn ${requestId}: empty reply, nothing sent`);
       }
+      // The reply is in the durable outbox (or there is none): the turn
+      // has ended, the inbox row has done its job.
+      deleteInboxRows(this.inboxSql(), turn.eventIds);
     } catch (err) {
       // A turn aborted because a newer message on the same thread superseded
       // it is not a failure: the new turn answers, the old card says so.
       if (isAbortError(err)) {
         this.log('info', `turn ${requestId}: superseded by a newer message`);
+        deleteInboxRows(this.inboxSql(), turn.eventIds);
         return;
       }
-      this.log('error', `turn ${requestId} failed`, err);
-      try {
-        await this.sendNotice(
-          turn.roomId,
-          'Sorry — something went wrong while handling your message. Please try again.',
-          turn.threadId ? { threadId: turn.threadId } : undefined,
+      if (isInterruptedTurnError(err))
+        this.log(
+          'warn',
+          `turn ${requestId}: the user object lost this turn in a reset and will not re-run it; asking the user to retry`,
         );
+      else this.log('error', `turn ${requestId} failed`, err);
+      try {
+        await this.sendNotice(turn.roomId, TURN_FAILED_NOTICE, {
+          ...(turn.threadId ? { threadId: turn.threadId } : {}),
+          ...(turn.eventIds[0]
+            ? { txnId: `${replyTxnId(turn.eventIds[0])}-notice` }
+            : {}),
+        });
       } catch (noticeErr) {
         this.log(
           'error',
@@ -417,7 +478,10 @@ export class MatrixGatewayDO
           noticeErr,
         );
       }
+      // Told the user (or could not): either way this turn is over.
+      deleteInboxRows(this.inboxSql(), turn.eventIds);
     } finally {
+      for (const id of turn.eventIds) this.inFlightEvents.delete(id);
       if (typing) clearInterval(typing);
       await this.setTyping(turn.roomId, false).catch(() => undefined);
       // Close the card on every exit — reply posted, empty reply, thrown
@@ -460,6 +524,105 @@ export class MatrixGatewayDO
     });
   }
 
+  // -------------------------------------------------------------------------
+  // Turn inbox: room messages whose reply is not in the outbox yet
+  // -------------------------------------------------------------------------
+
+  private inboxSql(): SqlStorage {
+    const sql = this.ctx.storage.sql;
+    if (!this.inboxTableReady) {
+      ensureInboxTable(sql);
+      this.inboxTableReady = true;
+    }
+    return sql;
+  }
+
+  /**
+   * Every start of this instance — first request, keep-alive alarm, RPC —
+   * goes through here. A start that actually brought the bot up is the
+   * moment to re-dispatch the turns a previous incarnation left unfinished.
+   */
+  override async ensureStarted(): Promise<StartResult> {
+    const result = await super.ensureStarted();
+    if (result.started) this.scheduleInboxReplay();
+    return result;
+  }
+
+  private scheduleInboxReplay(): void {
+    if (this.inboxReplayRunning) return;
+    this.inboxReplayRunning = true;
+    void this.replayInbox()
+      .catch((err: unknown) => this.log('error', 'inbox replay failed', err))
+      .finally(() => {
+        this.inboxReplayRunning = false;
+      });
+  }
+
+  /**
+   * Re-dispatch the messages whose turn never ended. Each replay is charged
+   * to the row; a row that has used its replays gets the "try again" notice
+   * instead, so a message that kills the instance cannot loop. The user
+   * object decides what a replay means for it (`matrix-turn-ledger.ts`):
+   * stored reply, attach to the running turn, or refuse — never a second run.
+   */
+  private async replayInbox(): Promise<void> {
+    const sql = this.inboxSql();
+    const rows = listInboxRows(sql);
+    if (rows.length === 0) return;
+    const plan = planInboxReplay(rows, {
+      inFlight: this.inFlightEvents,
+      maxReplays: MAX_TURN_REPLAYS,
+    });
+    for (const row of plan.exhausted) {
+      this.log(
+        'warn',
+        `inbox: giving up on ${row.eventId} in ${row.roomId} after ${row.attempts} replays; notifying the user`,
+      );
+      try {
+        await this.sendNotice(row.roomId, TURN_FAILED_NOTICE, {
+          ...(row.threadRootId ? { threadId: row.threadRootId } : {}),
+          txnId: `${replyTxnId(row.eventId)}-notice`,
+        });
+      } catch (err) {
+        this.log(
+          'error',
+          `inbox: could not post the notice for ${row.eventId}`,
+          err,
+        );
+      }
+      deleteInboxRows(sql, [row.eventId]);
+    }
+    if (plan.replay.length > 0)
+      bumpInboxAttempts(
+        sql,
+        plan.replay.map((row) => row.eventId),
+      );
+    for (const row of plan.replay) {
+      try {
+        await this.canonicalAliasOf(row.roomId);
+      } catch (err) {
+        this.log('warn', `inbox: alias lookup failed for ${row.roomId}`, err);
+      }
+      this.offerInbound(inboundOfRow(row));
+    }
+    this.log(
+      'info',
+      `inbox replay: ${plan.replay.length} turn(s) re-dispatched, ${plan.exhausted.length} given up, ${plan.skipped.length} already running`,
+    );
+  }
+
+  /**
+   * Operator / testing aid behind `ORACLE_DEBUG_ROUTES`: reset this object
+   * the way an unplanned platform reset does — in-flight turns and the sync
+   * loop die, committed storage (outbox, inbox, crypto snapshot) survives,
+   * the next request or alarm boots a fresh instance. The RPC rejects.
+   */
+  async debugAbortObject(): Promise<void> {
+    // Worded like the platform's own reset so RPC callers classify it as
+    // transient (see `isTransientGatewayError`), exactly as in production.
+    this.ctx.abort('gateway reset requested by the debug route');
+  }
+
   override async stop(): Promise<void> {
     // A debounce buffer firing after the stop would send through
     // `startedClient()`, which restarts the bot.
@@ -724,11 +887,12 @@ export class MatrixGatewayDO
   // User snapshots (SQLite files as room media) and media downloads
   // -------------------------------------------------------------------------
 
-  async uploadUserSnapshot(
+  async uploadUserSnapshotStream(
     userDid: string,
     storageKey: string,
-    bytes: Uint8Array,
+    body: ReadableStream<Uint8Array>,
     filename: string,
+    size: number,
   ): Promise<{ eventId: string }> {
     const target = await this.resolveUserRoom(userDid);
     if (!target)
@@ -740,10 +904,13 @@ export class MatrixGatewayDO
       await this.getRoomStateEvent(roomId, MEDIA_STATE_TYPE, storageKey),
     );
     // `{"file":{…}}` (encrypted) or `{"url":"mxc://…"}`, per the room.
+    // Streamed: encrypted chunk by chunk in an E2EE room and sent with the
+    // exact length; the whole-buffer upload grew the crypto WASM heap for good.
     const source: unknown = JSON.parse(
-      await this.uploadFile(roomId, bytes, {
+      await this.uploadFileStream(roomId, body, {
         filename,
         mimetype: SNAPSHOT_MIMETYPE,
+        size,
       }),
     );
     const content = {
@@ -752,7 +919,7 @@ export class MatrixGatewayDO
       filename: storageKey,
       cid: storageKey,
       sender: this.cfg().userId,
-      info: { mimetype: SNAPSHOT_MIMETYPE, size: bytes.byteLength },
+      info: { mimetype: SNAPSHOT_MIMETYPE, size },
       ...(typeof source === 'object' && source !== null ? source : {}),
     };
     const eventId = await this.sendEvent(
@@ -786,43 +953,64 @@ export class MatrixGatewayDO
     }
     this.log(
       'info',
-      `uploaded snapshot ${storageKey} (${bytes.byteLength} bytes) for ${userDid} → ${eventId}`,
+      `uploaded snapshot ${storageKey} (${size} bytes) for ${userDid} → ${eventId}`,
     );
     return { eventId };
   }
 
-  async downloadUserSnapshot(
+  async downloadUserSnapshotStream(
     userDid: string,
     storageKey: string,
-  ): Promise<{ bytes: Uint8Array; eventId: string } | null> {
+  ): Promise<SnapshotStream | null> {
     const target = await this.resolveUserRoom(userDid);
     if (!target) return null;
     const eventId = stateEventId(
       await this.getRoomStateEvent(target.roomId, MEDIA_STATE_TYPE, storageKey),
     );
     if (!eventId) return null;
-    const file = await this.downloadFile(target.roomId, eventId);
-    return file ? { bytes: file.bytes, eventId } : null;
+    const media = await this.mediaStream(target.roomId, eventId);
+    return media ? { ...media, eventId } : null;
+  }
+
+  /**
+   * A media event as a stream, AS STORED — raw ciphertext plus the
+   * `EncryptedFile` fields in an E2EE room. Decryption happens in the calling
+   * object: the SDK's whole-buffer `downloadFile` decrypts in the crypto WASM
+   * and grows its heap for good, and a stream that fails its hash check on
+   * this side of the RPC would reach the caller as a bare disconnect.
+   */
+  private async mediaStream(
+    roomId: string,
+    eventId: string,
+  ): Promise<MediaStream | null> {
+    const media = await this.downloadFileStream(roomId, eventId, {
+      raw: true,
+    });
+    if (!media) return null;
+    return {
+      stream: media.stream,
+      ...(media.file ? { file: media.file } : {}),
+      ...(media.size !== undefined ? { size: media.size } : {}),
+      ...(media.mimetype ? { mimetype: media.mimetype } : {}),
+      ...(media.filename ? { filename: media.filename } : {}),
+    };
   }
 
   /**
-   * Bytes of a media message (`m.image` / `m.file` / …) for the attachments
-   * pipeline — decrypted when the event carries an encrypted `file`. Null
-   * when the event is unknown or redacted.
+   * A media message (`m.image` / `m.file` / …) for the attachments pipeline,
+   * as stored (see `mediaStream`). Null when the event is unknown or redacted.
    */
-  async downloadEventMedia(
+  async downloadEventMediaStream(
     roomId: string,
     eventId: string,
-  ): Promise<{
-    bytes: Uint8Array;
-    mimetype?: string;
-    filename?: string;
-  } | null> {
-    return this.downloadFile(roomId, eventId);
+  ): Promise<MediaStream | null> {
+    return this.mediaStream(roomId, eventId);
   }
 
-  /** Authenticated download of an `mxc://` URI (`/_matrix/client/v1/media/download`, legacy fallback on 404). */
-  async downloadMxcMedia(mxc: string): Promise<Uint8Array> {
+  /** Authenticated download of an `mxc://` URI as a stream (`/_matrix/client/v1/media/download`, legacy fallback on 404). */
+  async downloadMxcMediaStream(
+    mxc: string,
+  ): Promise<ReadableStream<Uint8Array>> {
     const client = await this.startedClient();
     const token = client.getAccessToken();
     const headers: Record<string, string> = token
@@ -855,7 +1043,9 @@ export class MatrixGatewayDO
       throw new Error(
         `MatrixGatewayDO: media download failed: ${res.status} ${res.statusText}`,
       );
-    return new Uint8Array(await res.arrayBuffer());
+    if (!res.body)
+      throw new Error('MatrixGatewayDO: media download has no body');
+    return res.body;
   }
 
   // -------------------------------------------------------------------------
@@ -973,6 +1163,7 @@ export class MatrixGatewayDO
       ...(await super.status()),
       turns: { inFlight: this.turnGate.inUse, waiting: this.turnGate.queued },
       ingestPending: this.ingest?.pendingCount ?? 0,
+      inbox: countInboxRows(this.inboxSql()),
     };
   }
 }

package/src/matrix/inbox-store.ts

@@ -0,0 +1,188 @@
+/**
+ * Durable inbox for room messages whose turn is still in flight.
+ *
+ * The bot SDK marks an inbound event processed before it is delivered, and
+ * the reply only reaches the durable outbox once the user object has finished
+ * the whole LLM turn. A gateway reset in between — a platform host drain, a
+ * deploy — used to lose the reply silently: the fresh instance saw the event
+ * as processed and never asked again. Every accepted message is therefore
+ * written here before anything waits on the network, deleted once its turn
+ * has ended (reply in the outbox, empty reply, superseded, error notice
+ * posted), and whatever is left is re-dispatched on the next start. The user
+ * object makes re-dispatch safe (`src/do/matrix-turn-ledger.ts`): an event
+ * it already answered returns the stored text, one still running attaches,
+ * and one interrupted mid-turn is refused — never run twice.
+ *
+ * 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 { matrixTxnId } from './txn-id';
+
+export interface InboxRow extends InboundMessage {
+  receivedAt: number;
+  /** Replays charged to this row (0 = never replayed). */
+  attempts: number;
+}
+
+/**
+ * Replays a message gets after the original dispatch. A row that has been
+ * replayed this many times when the next start finds it is given up: the
+ * user gets the "try again" notice instead of a fourth attempt.
+ */
+export const MAX_TURN_REPLAYS = 2;
+
+export function ensureInboxTable(sql: SqlStorage): void {
+  sql.exec(
+    `CREATE TABLE IF NOT EXISTS turn_inbox (
+      event_id TEXT PRIMARY KEY,
+      room_id TEXT NOT NULL,
+      sender TEXT NOT NULL,
+      ts INTEGER NOT NULL,
+      body TEXT NOT NULL,
+      thread_root_id TEXT,
+      attachment TEXT,
+      received_at INTEGER NOT NULL,
+      attempts INTEGER NOT NULL DEFAULT 0
+    ) WITHOUT ROWID`,
+  );
+}
+
+/** Record a message before its turn starts. A repeat of the same event id is a no-op. */
+export function insertInboxRow(
+  sql: SqlStorage,
+  msg: InboundMessage,
+  receivedAt: number,
+): void {
+  sql.exec(
+    `INSERT OR IGNORE INTO turn_inbox
+      (event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`,
+    msg.eventId,
+    msg.roomId,
+    msg.sender,
+    msg.ts,
+    msg.body,
+    msg.threadRootId ?? null,
+    msg.attachment ? JSON.stringify(msg.attachment) : null,
+    receivedAt,
+  );
+}
+
+/** A quote-reply's thread root, resolved after the row was written. */
+export function updateInboxThread(
+  sql: SqlStorage,
+  eventId: string,
+  threadRootId: string,
+): void {
+  sql.exec(
+    `UPDATE turn_inbox SET thread_root_id = ? WHERE event_id = ?`,
+    threadRootId,
+    eventId,
+  );
+}
+
+export function deleteInboxRows(sql: SqlStorage, eventIds: string[]): void {
+  for (const id of eventIds)
+    sql.exec(`DELETE FROM turn_inbox WHERE event_id = ?`, id);
+}
+
+export function bumpInboxAttempts(sql: SqlStorage, eventIds: string[]): void {
+  for (const id of eventIds)
+    sql.exec(
+      `UPDATE turn_inbox SET attempts = attempts + 1 WHERE event_id = ?`,
+      id,
+    );
+}
+
+export function countInboxRows(sql: SqlStorage): number {
+  const rows = sql
+    .exec<{ n: number }>(`SELECT COUNT(*) AS n FROM turn_inbox`)
+    .toArray();
+  return Number(rows[0]?.n ?? 0);
+}
+
+type InboxSqlRow = {
+  event_id: string;
+  room_id: string;
+  sender: string;
+  ts: number;
+  body: string;
+  thread_root_id: string | null;
+  attachment: string | null;
+  received_at: number;
+  attempts: number;
+} & Record<string, SqlStorageValue>;
+
+/** Every pending row, oldest first (the order the messages arrived in). */
+export function listInboxRows(sql: SqlStorage): InboxRow[] {
+  return sql
+    .exec<InboxSqlRow>(
+      `SELECT event_id, room_id, sender, ts, body, thread_root_id, attachment, received_at, attempts
+       FROM turn_inbox ORDER BY ts ASC, event_id ASC`,
+    )
+    .toArray()
+    .map((row) => ({
+      eventId: row.event_id,
+      roomId: row.room_id,
+      sender: row.sender,
+      ts: Number(row.ts),
+      body: row.body,
+      ...(row.thread_root_id ? { threadRootId: row.thread_root_id } : {}),
+      ...(row.attachment
+        ? { attachment: parseAttachment(row.attachment) }
+        : {}),
+      receivedAt: Number(row.received_at),
+      attempts: Number(row.attempts),
+    }));
+}
+
+function parseAttachment(json: string): InboundAttachment {
+  const parsed: unknown = JSON.parse(json);
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    typeof (parsed as { eventId?: unknown }).eventId !== 'string'
+  )
+    throw new Error('turn_inbox: malformed attachment column');
+  return parsed as InboundAttachment;
+}
+
+/** The message a row was made from — what goes back into the ingest pipeline. */
+export function inboundOfRow(row: InboxRow): InboundMessage {
+  const { receivedAt: _receivedAt, attempts: _attempts, ...msg } = row;
+  return msg;
+}
+
+export interface InboxReplayPlan {
+  /** Rows to feed back into the ingest pipeline, oldest first. */
+  replay: InboxRow[];
+  /** Rows that used up their replays: notify the user and drop. */
+  exhausted: InboxRow[];
+  /** Rows whose turn is running in this instance right now (a restart, not a reset): leave alone. */
+  skipped: InboxRow[];
+}
+
+export function planInboxReplay(
+  rows: InboxRow[],
+  opts: { inFlight: ReadonlySet<string>; maxReplays: number },
+): InboxReplayPlan {
+  const plan: InboxReplayPlan = { replay: [], exhausted: [], skipped: [] };
+  for (const row of rows) {
+    if (opts.inFlight.has(row.eventId)) plan.skipped.push(row);
+    else if (row.attempts >= opts.maxReplays) plan.exhausted.push(row);
+    else plan.replay.push(row);
+  }
+  return plan;
+}
+
+/**
+ * The transaction id of the reply to a room message. Derived from the event
+ * id, so a reply re-sent after a reset — by the replayed turn, or by the
+ * durable outbox — is deduplicated by the homeserver instead of appearing
+ * twice. Event ids are `$` + base64 (standard or url-safe); the id must not
+ * contain `/`, whitespace or control characters, and stays under 255 bytes.
+ */
+export function replyTxnId(eventId: string): string {
+  return matrixTxnId('reply', eventId);
+}

package/src/matrix/txn-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Transaction ids for Matrix sends that may be retried across a gateway
+ * restart. The homeserver deduplicates sends by transaction id per device,
+ * so a caller that re-sends with the same id after a lost response gets the
+ * original event back instead of a duplicate. Synapse accepts ids without
+ * whitespace, control characters or `/`, up to 255 bytes. The parts joined
+ * here (event ids, session ids, request ids, run ids) are ASCII; `/` and `+`
+ * of standard-base64 event ids are mapped so distinct ids stay distinct, and
+ * anything outside printable ASCII is dropped.
+ */
+export const MAX_TXN_ID_LENGTH = 255;
+
+export function matrixTxnId(prefix: string, ...parts: string[]): string {
+  let out = prefix;
+  for (const part of parts) {
+    out += '-';
+    for (const ch of part) {
+      const code = ch.charCodeAt(0);
+      if (ch === '/') out += '_';
+      else if (ch === '+') out += '-';
+      else if (code > 0x20 && code < 0x7f) out += ch;
+    }
+  }
+  return out.slice(0, MAX_TXN_ID_LENGTH);
+}
+
+/**
+ * A transaction id for a best-effort post whose retries all live in one
+ * in-memory loop (an audit entry, a prompt): fixed for the life of that loop,
+ * so a response lost after the homeserver accepted the event is deduplicated
+ * instead of posted twice, and fresh for every new post.
+ */
+export function retryTxnId(prefix: string): string {
+  return matrixTxnId(prefix, crypto.randomUUID());
+}