@haikit/server 0.17.0 → 0.19.0

package/src/runtime.ts

@@ -10,12 +10,17 @@ import {
   type ModelAdapter,
   type Notify,
   type Progress,
+  type SendSignal,
+  type Signal,
   type StoreAdapter,
   type Tool,
   type ToolCtx,
   type ToolReturn,
+  type Update,
+  type UpdateOptions,
   type WireEvent,
 } from "@haikit/core";
+import { Broadcast } from "./signals.js";
 
 export interface HaiConfig {
   model: ModelAdapter;
@@ -65,6 +70,27 @@ export interface HaiConfig {
    * browser still shows it at once.
    */
   maxWakes?: { count: number; perMs: number };
+  /**
+   * Set when app code revises surfaces with `hai.update`, which refuses
+   * without it. The browser then opens the events stream, which is how a
+   * revision reaches it, and the events route starts the turns an update sent
+   * with `wake` asks for.
+   */
+  updates?: boolean;
+  /**
+   * The signals this app sends with `hai.signal`: short-lived broadcasts to
+   * every open browser. A signal not listed here is refused. With any listed,
+   * the browser opens the events stream, which is how a signal reaches it.
+   */
+  signals?: Signal<any>[];
+  /**
+   * How presence is counted (`hai.onPresence`). `graceMs`: how long a
+   * conversation whose events stream closed still counts, so a browser that
+   * reconnects doesn't flicker the count; default 5 s. `heartbeatMs`: how
+   * often servers sharing a store tell each other their counts; a server not
+   * heard from for three beats stops counting; default 10 s.
+   */
+  presence?: { graceMs?: number; heartbeatMs?: number };
 }
 
 /**
@@ -111,9 +137,40 @@ interface Hop {
    * so two renders at once cannot both ask; the handle is known once it shows,
    * and `settled` resolves when its render has shown it or failed.
    */
-  asking: { handle: string | null; settled: Promise<void> } | null;
+  asking: {
+    handle: string | null;
+    settled: Promise<void>;
+    /** The digest it was asked under, and its latest, once a later call in the reply has revised it. */
+    question?: string;
+    digest?: string;
+  } | null;
+}
+
+/** A `hai.update` write, and every call it answers. */
+interface UpdateJob {
+  props: unknown;
+  model: string | undefined;
+  wake: boolean;
+  timeoutMs: number;
+  waiters: { resolve: (written: { handle: string }) => void; reject: (err: unknown) => void }[];
+}
+
+/** The `hai.update` calls for one surface: the next to write, once the one writing is done. */
+interface UpdateQueue {
+  next: UpdateJob | null;
 }
 
+/** The longest delay a Node timer keeps; past it, one fires after about a millisecond. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** How long `hai.update` waits for a turn to let the conversation go, by default. */
+const UPDATE_TIMEOUT_MS = 30_000;
+/** How many conversations `hai.update` remembers its surfaces' handles for. */
+const UPDATE_NAMES_KEPT = 10_000;
+/** The first wait before `hai.update` tries a busy conversation again, and the longest. */
+const UPDATE_RETRY_MS = 100;
+const UPDATE_RETRY_MAX_MS = 2_000;
+
 /** An elicit surface a tool call showed, and the digest its answer goes out under. */
 interface Question {
   handle: string;
@@ -130,6 +187,18 @@ export class Hai {
   private readonly queryUi: Tool;
   /** Handles each conversation has a revision of in flight, so two calls can't revise one at once. */
   private readonly revising = new WeakMap<Conversation, Set<string>>();
+  private readonly signals = new Map<string, Signal<any>>();
+  /** Signals sent, streams open, and presence, here and on the other servers. */
+  private readonly broadcast: Broadcast;
+  /** `hai.update` calls by conversation and surface: one writing, and the newest waiting behind it. */
+  private readonly updating = new Map<string, UpdateQueue>();
+  /**
+   * The surfaces `hai.update` has revised, by conversation: each one's first
+   * handle and its latest, both mapped to the first, so calls naming either
+   * share a queue. Kept for the most recent conversations only; one let go of
+   * costs coalescing, never correctness, since every write revises the latest.
+   */
+  private readonly surfaceNames = new Map<string, Map<string, string>>();
   /** What the model gets as its system prompt: the app's, then the scope. */
   readonly system: string;
   private seq = 0;
@@ -157,6 +226,25 @@ export class Hai {
       );
     }
     this.maxWakes = { count, perMs };
+    for (const s of config.signals ?? []) {
+      if (this.signals.has(s.name)) throw new Error(`two signals are named "${s.name}"`);
+      this.signals.set(s.name, s);
+    }
+    const { graceMs = 5_000, heartbeatMs = 10_000 } = config.presence ?? {};
+    for (const [name, ms] of [["graceMs", graceMs], ["heartbeatMs", heartbeatMs]] as const) {
+      // Past the longest timer Node keeps, it fires after about a millisecond:
+      // a grace would end at once, and a heartbeat would spin.
+      // Whole milliseconds, as timers count them: a fractional one would be
+      // scheduled shorter than the staleness arithmetic assumes.
+      if (typeof ms !== "number" || !Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_MS) {
+        throw new RangeError(
+          `presence.${name} must be a whole number of milliseconds, from 1 to ${MAX_TIMER_MS} (got ${String(ms)})`,
+        );
+      }
+    }
+    this.broadcast = new Broadcast(config.store, graceMs, heartbeatMs);
+    // hear the other servers' signals from now, so a stream that opens later gets their latest
+    if (this.signals.size) this.broadcast.start();
     // query_ui is DERIVED, never authored. It cannot drift from the surfaces
     // that actually exist, and it always exists.
     const queryUi = this.buildQueryUiTool();
@@ -171,14 +259,29 @@ export class Hai {
     }
   }
 
-  /** Whether this app sends notices, so the browser should open the events stream. */
+  /**
+   * Whether this app sends notices, `hai.update`'s included: what the
+   * conversation's history may have unread, and the events stream may have to
+   * deliver.
+   */
   get sendsNotices(): boolean {
-    return this.notices.size > 0;
+    return this.notices.size > 0 || this.config.updates === true;
   }
 
-  /** Whether any of its notices are `wake` notices, which the events route starts turns for. */
+  /**
+   * Whether the browser should open the events stream: for notices, or for
+   * signals, which travel on it too.
+   */
+  get streamsEvents(): boolean {
+    return this.sendsNotices || this.signals.size > 0;
+  }
+
+  /**
+   * Whether any of its notices may be `wake` notices, which the events route
+   * starts turns for: a registered one, or an update sent with `wake`.
+   */
   get wakes(): boolean {
-    return [...this.notices.values()].some((n) => n.notice.kind === "wake");
+    return this.config.updates === true || [...this.notices.values()].some((n) => n.notice.kind === "wake");
   }
 
   /**
@@ -225,6 +328,282 @@ export class Hai {
     return { seq: record.seq };
   };
 
+  /**
+   * Send a signal to every open events stream, on this server and, through a
+   * store with `publish` and `subscribe`, on the others. Not stored, not
+   * numbered, never in the model's context or the transcript: the browser
+   * hands it to the app's handler for it. Each signal's latest payload is
+   * kept, and a stream that opens later is sent it first.
+   *
+   * Throws for a signal not listed in `signals`, or a payload that fails its
+   * schema.
+   */
+  readonly signal: SendSignal = (signal, payload) => {
+    const name = signal?.name;
+    if (this.signals.get(name) !== signal) {
+      throw new Error(`signal "${name}" is not registered: list it in createHai({ signals })`);
+    }
+    this.broadcast.send({ type: "signal", name, version: signal.version, payload: signal.payload.parse(payload) });
+  };
+
+  /**
+   * How many conversations have an events stream open, on every server
+   * sharing the store: a tab with the app open, as near as the server can
+   * tell. `listener` hears the count now and whenever it changes. A stream
+   * that closes still counts for `presence.graceMs`, so a reconnect doesn't
+   * flicker it. Returns a function that stops listening.
+   *
+   * Each server counts its own and the totals are summed, so a conversation
+   * counts once per server it has a stream on: one that reconnects to another
+   * server counts on both until the grace runs out, and one with streams on
+   * two servers at once counts twice. (The client opens one stream per
+   * conversation, so the second doesn't happen with it.)
+   *
+   * Only the number leaves a server: no conversation ids, and nothing the
+   * model sees. An app with no notices, updates or signals opens no events
+   * stream, so counts nothing.
+   */
+  onPresence(listener: (count: number) => void): () => void {
+    return this.broadcast.onPresence(listener);
+  }
+
+  /**
+   * An events stream opened for `conversationId`: it hears every signal from
+   * now on, starting with each one's latest payload, and counts toward
+   * presence. The events route calls this; call it too if you serve the
+   * stream yourself, and call what it returns when the stream closes.
+   */
+  streamOpened(conversationId: string, emit: Emit): () => void {
+    return this.broadcast.opened(conversationId, emit);
+  }
+
+  /**
+   * Revise a surface from outside any turn: a webhook, a job, a price feed.
+   * The revision is stored and attached as `ctx.update` does, under the
+   * conversation's lease, so a click can never act on props the server doesn't
+   * hold. Then an *update notice* tells both sides: the events stream sends
+   * the browser the revision, which it swaps into the component on screen,
+   * and the model hears which handle replaced which, with the new digest, in
+   * the next user message (or at once, with `wake`).
+   *
+   * `handle` may be any handle the surface has had: the revision replaces the
+   * latest. It throws if that one was answered, if the conversation is out of
+   * date, and, after waiting `timeoutMs` for a turn to let the conversation
+   * go, with `ConversationBusy`. A question waiting on the surface waits on
+   * the revision.
+   *
+   * One write per surface is in flight at a time. A call made meanwhile
+   * replaces any still waiting behind it, and every call it replaced resolves
+   * to the handle it writes; a wake any of them asked for still wakes.
+   */
+  readonly update: Update = (conversationId, surface, handle, props, options = {}) => {
+    const impl = surface as AnySurfaceImpl;
+    const name = impl?.surface?.name;
+    if (this.surfaces.get(name) !== impl) {
+      return Promise.reject(new Error(`surface "${name}" is not registered: list it in createHai({ surfaces })`));
+    }
+    // Required even when notices open the events stream: it is also what has
+    // the events route start the turn an update sent with `wake` asks for.
+    if (this.config.updates !== true) {
+      return Promise.reject(new Error("hai.update is off: set createHai({ updates: true })"));
+    }
+    const { timeoutMs = UPDATE_TIMEOUT_MS, model, wake } = options as UpdateOptions;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      return Promise.reject(new RangeError(`timeoutMs must be a finite number of milliseconds, zero or more (got ${String(timeoutMs)})`));
+    }
+    if (model !== undefined && typeof model !== "string") return Promise.reject(new TypeError("model must be a string"));
+    let parsed: unknown;
+    try {
+      // Validated before anything waits: props may come from outside this process.
+      parsed = impl.surface.props.parse(props);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+
+    return new Promise((resolve, reject) => {
+      // the surface's first handle, when it is one `hai.update` has revised here
+      const first = this.surfaceNames.get(conversationId)?.get(handle) ?? handle;
+      const key = `${conversationId}\u0000${first}`;
+      const waiter = { resolve, reject };
+      const queue = this.updating.get(key);
+      if (queue) {
+        const behind = queue.next;
+        queue.next = {
+          props: parsed,
+          model,
+          wake: wake === true || behind?.wake === true,
+          timeoutMs,
+          waiters: [...(behind?.waiters ?? []), waiter],
+        };
+        return;
+      }
+      const fresh: UpdateQueue = { next: { props: parsed, model, wake: wake === true, timeoutMs, waiters: [waiter] } };
+      this.updating.set(key, fresh);
+      void (async () => {
+        for (let job = fresh.next; job; job = fresh.next) {
+          fresh.next = null;
+          try {
+            const { replaced, ...written } = await this.revise(conversationId, impl, handle, job);
+            this.name(conversationId, first, replaced, written.handle);
+            for (const w of job.waiters) w.resolve(written);
+          } catch (err) {
+            for (const w of job.waiters) w.reject(err);
+          }
+        }
+        this.updating.delete(key);
+      })();
+    });
+  };
+
+  /** Record that `first`'s surface went from `replaced` to `latest`, for the next call's queue. */
+  private name(conversationId: string, first: string, replaced: string, latest: string) {
+    const names = this.surfaceNames.get(conversationId) ?? new Map<string, string>();
+    // only the first and the latest are kept: what a caller is likely to hold
+    if (replaced !== first) names.delete(replaced);
+    names.set(first, first).set(latest, first);
+    // most recently revised last, so the oldest conversation goes first
+    this.surfaceNames.delete(conversationId);
+    this.surfaceNames.set(conversationId, names);
+    if (this.surfaceNames.size > UPDATE_NAMES_KEPT) this.surfaceNames.delete(this.surfaceNames.keys().next().value!);
+  }
+
+  /**
+   * Append the update notice this conversation owes, if any, before anything
+   * else is done with it: a revision whose own attempt to append it failed.
+   * One a holder appended before its save failed is not appended again.
+   */
+  private async announce(conversation: Conversation): Promise<void> {
+    const owed = conversation.announcing;
+    if (!owed) return;
+    // The model hasn't taken it in either way: that commits with clearing this.
+    const unread = (await this.config.store.getNotices(conversation.id, conversation.noticedThrough ?? 0)) ?? [];
+    if (!unread.some((n) => n.handle === owed.handle && n.replaces === owed.replaces)) await this.config.store.putNotice(owed);
+    conversation.announcing = null;
+  }
+
+  /** One `hai.update` write: take the lease, revise, let the conversation go. */
+  private async revise(
+    conversationId: string,
+    impl: AnySurfaceImpl,
+    handle: string,
+    job: UpdateJob,
+  ): Promise<{ handle: string; replaced: string }> {
+    const { store } = this.config;
+    // Loading an unknown id would start a new conversation, so make sure it
+    // exists first, with the cheapest read there is.
+    if ((await store.getNotices(conversationId, Number.MAX_SAFE_INTEGER, 1)) === null) {
+      throw new Error(`no conversation ${conversationId}`);
+    }
+    // A turn in progress lands first: wait for it, backing off, up to the timeout.
+    const deadline = Date.now() + job.timeoutMs;
+    let conversation: Conversation | null = null;
+    for (let wait = UPDATE_RETRY_MS; !conversation; wait = Math.min(wait * 2, UPDATE_RETRY_MAX_MS)) {
+      try {
+        conversation = await store.loadConversation(conversationId);
+      } catch (err) {
+        const left = deadline - Date.now();
+        if (!isConversationBusy(err) || left <= 0) throw err;
+        await new Promise((r) => setTimeout(r, Math.min(wait, left)));
+        // not another try once the timeout has passed, even if the turn has gone
+        if (Date.now() >= deadline) throw err;
+      }
+    }
+
+    let failure: unknown = null;
+    let written: { handle: string; replaced: string } | null = null;
+    try {
+      // one an earlier update still owes goes first, in order
+      await this.announce(conversation);
+      written = await this.reviseHeld(conversation, impl, handle, job);
+    } catch (err) {
+      failure = err;
+    }
+    // As a route does at the end of a request: let the conversation go, with
+    // the token kept so the save can prove this is still the rightful holder.
+    conversation.leaseUntil = null;
+    if (!isStaleLease(failure)) {
+      try {
+        await store.saveConversation(conversation);
+      } catch (err) {
+        failure ??= err;
+      }
+    }
+    if (failure) throw failure;
+    return written!;
+  }
+
+  private async reviseHeld(
+    conversation: Conversation,
+    impl: AnySurfaceImpl,
+    handle: string,
+    job: UpdateJob,
+  ): Promise<{ handle: string; replaced: string }> {
+    const { store } = this.config;
+    if (!conversation.handles.includes(handle)) throw new Error(`no surface ${handle} in conversation ${conversation.id}`);
+    // the surface as it is now: updates queued one behind another each revise the last
+    const current = currentHandle(conversation, handle);
+    if (conversation.frozen.includes(current)) throw new Error(`${current} was answered, so it can't be revised`);
+    const record = await store.getPayload(current, conversation.id);
+    if (!record) throw new Error(`no surface ${current} in conversation ${conversation.id}`);
+    if (record.component !== impl.surface.name) throw new Error(`${current} is a ${record.component}, not a ${impl.surface.name}`);
+    // After the reads, right before the write, as for `ctx.update`: a revision
+    // must not bring an out-of-date conversation back by superseding the
+    // surface that closed it.
+    if (await this.refuseIfExpired(conversation, () => {})) {
+      throw new Error("this conversation is out of date; nothing more can be revised in it");
+    }
+
+    const next = await store.putPayload(
+      {
+        conversationId: conversation.id,
+        component: impl.surface.name,
+        version: impl.surface.version,
+        props: job.props,
+        mode: record.mode,
+        staleAfterMs: windowOf(impl),
+      },
+      conversation.leaseToken,
+    );
+    const digest = impl.impl.digest(job.props, { handle: next });
+    // …and once more as it takes effect: the write and the digest take a while too
+    const window = strictest(record.staleAfterMs, windowOf(impl));
+    if (window !== "never" && !(Number.isFinite(record.createdAt) && window !== undefined && record.createdAt + window > Date.now())) {
+      throw new Error("this conversation went out of date while the revision was made; it was not applied");
+    }
+
+    conversation.handles.push(next);
+    (conversation.superseded ??= {})[current] = next;
+    // A question waiting on the surface waits on its revision. Its digest stays
+    // as the model was shown it: the update's text rides in the same message as
+    // the answer, after it, saying what changed.
+    if (conversation.pending?.handle === current) conversation.pending = { ...conversation.pending, handle: next };
+    // The notice it owes commits with it, in one fenced save, so the revision
+    // and its notice can't come apart. Saved before the notice is appended,
+    // which proves the lease is still held: a notice for a revision the history
+    // lost would show the browser a surface every click on is refused.
+    const notice = {
+      conversationId: conversation.id,
+      name: impl.surface.name,
+      version: impl.surface.version,
+      payload: null,
+      model: `${job.model ? `${job.model} ` : ""}${current} was replaced by ${next}; its earlier digest is out of date. Now: ${digest}`,
+      handle: next,
+      replaces: current,
+      ...(job.wake ? { kind: "wake" as const } : {}),
+    };
+    conversation.announcing = notice;
+    await store.saveConversation(conversation);
+    try {
+      await store.putNotice(notice);
+    } catch (err) {
+      // Still owed, and appended by whoever holds the conversation next, before
+      // anything else: the model hears of the revision before it runs again.
+      throw new Error(`${next} is saved, but its update notice could not be stored yet: it goes out with the conversation's next request (${(err as Error).message})`);
+    }
+    conversation.announcing = null;
+    return { handle: next, replaced: current };
+  }
+
   /**
    * Start a turn for the `wake` notices this conversation hasn't taken in, if
    * it can take one now. The events route calls this, and streams the turn
@@ -279,6 +658,7 @@ export class Hai {
   }
 
   private async wakeTurn(conversation: Conversation, emit: Emit): Promise<WakeOutcome> {
+    await this.announce(conversation);
     // a load of an unknown id starts a new conversation, which has not begun either
     if (!conversation.messages.length || conversation.status === "awaiting") return "idle";
     if (await this.refuseIfExpired(conversation, () => {})) return "idle";
@@ -373,11 +753,13 @@ export class Hai {
     conversation: Conversation,
   ): Promise<{ blocks: TextBlock[]; through: number; wake: number }> {
     const through = conversation.noticedThrough ?? 0;
-    if (!this.notices.size) return { blocks: [], through, wake: 0 };
+    if (!this.sendsNotices) return { blocks: [], through, wake: 0 };
     const fresh = (await this.config.store.getNotices(conversation.id, through)) ?? [];
     return {
       blocks: fresh.flatMap((n) =>
-        n.model === null ? [] : [{ type: "text" as const, text: `[App notification: ${n.name}] ${n.model}` }],
+        n.model === null
+          ? []
+          : [{ type: "text" as const, text: n.replaces === undefined ? `[App notification: ${n.name}] ${n.model}` : `[UI update] ${n.model}` }],
       ),
       through: fresh.at(-1)?.seq ?? through,
       // the newest unread wake notice, or 0
@@ -474,6 +856,7 @@ export class Hai {
   // ─────────────────────────────────────────────────── public API
 
   async send(conversation: Conversation, text: string, emit: Emit): Promise<void> {
+    await this.announce(conversation);
     if (await this.refuseIfExpired(conversation, emit)) return;
 
     // The first message is the one that starts the conversation.
@@ -523,6 +906,7 @@ export class Hai {
    */
   async start(conversation: Conversation, emit: Emit): Promise<void> {
     if (!this.config.init || conversation.messages.length > 0) return;
+    await this.announce(conversation);
     const unread = await this.unreadNotices(conversation);
     if (await this.runInit(conversation, withText(unread.blocks, STARTED), emit, unread.through)) return; // parked on its surface
     conversation.status = "idle";
@@ -619,6 +1003,7 @@ export class Hai {
     input: { handle: string; action: string; value: unknown },
     emit: Emit,
   ): Promise<void> {
+    await this.announce(conversation);
     if (await this.refuseIfExpired(conversation, emit)) return;
 
     // The payload row carries a conversation id, but that alone is not enough.
@@ -757,8 +1142,9 @@ export class Hai {
    */
   private async refuseIfExpired(conversation: Conversation, emit: Emit): Promise<boolean> {
     if (!conversation.handles.length) return false;
-    const now = Date.now();
     const records = await this.config.store.getPayloads(conversation.handles, conversation.id);
+    // after the read, so a window that ran out while it was in flight counts
+    const now = Date.now();
 
     // the surface that went out of date first is the one that closed it
     let first: { expiredAt: number; age: number; window: number | undefined } | null = null;
@@ -866,8 +1252,18 @@ export class Hai {
         // Hold the resolved siblings too — the API is all-or-nothing per batch.
         conversation.status = "awaiting";
         // At the question's latest revision: a later call in this reply may
-        // have revised it.
-        conversation.pending = { ...parked, handle: currentHandle(conversation, parked.handle), results };
+        // have revised it, and then its answer goes out under the revision's
+        // digest, not the original's.
+        // Only the question's part is replaced: anything the asking call said
+        // after it rides along as before.
+        const handle = currentHandle(conversation, parked.handle);
+        const asking = hop.asking;
+        let digest = parked.digest;
+        if (handle !== parked.handle && asking?.handle === handle && asking.digest !== undefined) {
+          const asked = asking.question;
+          digest = asked !== undefined && parked.digest.startsWith(asked) ? asking.digest + parked.digest.slice(asked.length) : asking.digest;
+        }
+        conversation.pending = { ...parked, handle, digest, results };
         emit({ type: "status", status: "awaiting" });
         await this.emitContext(conversation, emit);
         return;
@@ -916,6 +1312,9 @@ export class Hai {
       surfaceMode: "display" | "elicit",
       // the handle this revises in place, for `update`
       replaces?: string,
+      // last word before the surface is attached and sent: throwing leaves the
+      // stored payload unreferenced, inert as an overtaken turn's
+      beforeAttach?: () => void,
     ) => {
       // Validate before storing: props may originate outside this process.
       const parsed = impl.surface.props.parse(props);
@@ -941,6 +1340,7 @@ export class Hai {
 
       // The split, in two lines. Digest -> model. Payload -> browser.
       const digest = impl.impl.digest(parsed, { handle });
+      beforeAttach?.();
       // Recorded only once the digest is in hand. A surface that fails here is
       // never shown, and a handle in the history counts toward its freshness,
       // so it could otherwise close the conversation over something unseen.
@@ -1000,6 +1400,7 @@ export class Hai {
       try {
         const ret = await show(impl, props, "elicit");
         claim.handle = ret.handle;
+        claim.question = ret.model;
         asked = { handle: ret.handle, digest: ret.model };
         return ret;
       } catch (err) {
@@ -1028,11 +1429,33 @@ export class Hai {
         if (record.component !== impl.surface.name) {
           throw new Error(`${handle} is a ${record.component}, not a ${impl.surface.name}`);
         }
-        const ret = await show(impl, props, record.mode, handle);
+        // Freshness again, last, right before the write: a long turn can
+        // outlast a window that was open when it began, and so can the reads
+        // above. A revision must not bring an out-of-date conversation back
+        // by superseding the surface that closed it.
+        if (await this.refuseIfExpired(conversation, () => {})) {
+          throw new Error("this conversation is out of date; nothing more can be revised in it");
+        }
+        // …and once more as it takes effect: the write and the digest above can
+        // take a while too, and the browser closes the conversation at the old
+        // surface's deadline whether or not a revision is on its way.
+        const window = strictest(record.staleAfterMs, windowOf(impl));
+        const stillFresh = () => {
+          if (window === "never") return;
+          if (!(Number.isFinite(record.createdAt) && window !== undefined && record.createdAt + window > Date.now())) {
+            throw new Error("this conversation went out of date while the revision was made; it was not applied");
+          }
+        };
+        const ret = await show(impl, props, record.mode, handle, stillFresh);
         (conversation.superseded ??= {})[handle] = ret.handle!;
-        // a question waiting on the old surface waits on the new one
-        if (asked?.handle === handle) asked = { handle: ret.handle!, digest: ret.model };
-        if (hop.asking?.handle === handle) hop.asking.handle = ret.handle!;
+        // a question waiting on the old surface waits on the new one; when this
+        // call asked it, its result starts with the revision's digest now, so
+        // that is the part a later call's revision replaces
+        const mine = asked?.handle === handle;
+        if (mine) asked = { handle: ret.handle!, digest: ret.model };
+        if (hop.asking?.handle === handle) {
+          Object.assign(hop.asking, { handle: ret.handle!, digest: ret.model }, mine ? { question: ret.model } : {});
+        }
         return ret;
       } finally {
         revising.delete(handle);