agl 40.6.0 → 41.0.0

package/ts/classes.controller.ts

@@ -87,6 +87,7 @@ import {
 } from './functions.canonicaldirectory.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { controllerFailureJournal } from './classes.failurejournal.js';
+import { ControllerEventDelivery } from './classes.controllereventdelivery.js';
 import {
   controllerPackageName,
   controllerBuiltinCommands,
@@ -929,6 +930,9 @@ const maxSessionArchiveReconciliationReads = 3;
 const maxLatestOpenCodeToolExecutions = 512;
 const maxLatestOpenCodeMessageUpdates = 512;
 const maxPendingFlexControllerEvents = 512;
+/** Events and serialized bytes one browser may have waiting before its queue collapses into a resync. */
+const maxPendingControllerEventsPerViewer = 512;
+const maxPendingControllerEventBytesPerViewer = 16 * 1024 * 1024;
 const maxLatestFlexToolExecutions = 512;
 const maxLatestFlexToolExecutionBytes = 8 * 1024 * 1024;
 const maxLatestFlexMessageUpdateBytes = 16 * 1024 * 1024;
@@ -1352,6 +1356,12 @@ interface ILatestTextUpdate {
   bytes?: number;
 }
 
+/** A live Flex reasoning snapshot with the accounting its deltas extend. */
+type TLatestFlexReasoningUpdate = ILatestReasoningUpdate & IFlexLiveTextAccounting;
+
+/** A live Flex text snapshot with the accounting its deltas extend. */
+type TLatestFlexTextUpdate = ILatestTextUpdate & IFlexLiveTextAccounting;
+
 type TControllerMessageDelta = IControllerReasoningDelta | IControllerTextDelta;
 
 interface IControllerTextDeltaFragment {
@@ -1389,6 +1399,67 @@ const controllerTextAfterAppendUtf8Bytes = (
   return Number.isSafeInteger(result) && result >= 0 ? result : undefined;
 };
 
+const isHighSurrogate = (codeArg: number): boolean => codeArg >= 0xD800 && codeArg <= 0xDBFF;
+const isLowSurrogate = (codeArg: number): boolean => codeArg >= 0xDC00 && codeArg <= 0xDFFF;
+
+/** The UTF-8 bytes `JSON.stringify` writes for a string's content (without its quotes), counted without serializing. */
+const controllerJsonStringContentBytes = (valueArg: string): number => {
+  let bytes = 0;
+  for (let index = 0; index < valueArg.length; index += 1) {
+    const code = valueArg.charCodeAt(index);
+    if (
+      code === 0x22 || code === 0x5C
+      || code === 0x08 || code === 0x09 || code === 0x0A || code === 0x0C || code === 0x0D
+    ) bytes += 2;
+    else if (code < 0x20) bytes += 6;
+    else if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (isHighSurrogate(code)) {
+      if (index + 1 < valueArg.length && isLowSurrogate(valueArg.charCodeAt(index + 1))) {
+        bytes += 4;
+        index += 1;
+      } else bytes += 6;
+    } else if (isLowSurrogate(code)) bytes += 6;
+    else bytes += 3;
+  }
+  return bytes;
+};
+
+/**
+ * What a live Flex snapshot's text costs, kept beside the text so a delta is accounted by its own length: the
+ * cumulative text is never encoded, serialized or even read again on the append path.
+ */
+interface IFlexLiveTextAccounting {
+  textUtf8Bytes: number;
+  /** `JSON.stringify(text)` bytes without the quotes. */
+  textJsonBytes: number;
+  textEndsWithHighSurrogate: boolean;
+}
+
+const flexLiveTextAccounting = (textArg: string): IFlexLiveTextAccounting => ({
+  textUtf8Bytes: Buffer.byteLength(textArg, 'utf8'),
+  textJsonBytes: controllerJsonStringContentBytes(textArg),
+  textEndsWithHighSurrogate: textArg.length > 0 && isHighSurrogate(textArg.charCodeAt(textArg.length - 1)),
+});
+
+const flexLiveTextAccountingAfterAppend = (
+  accountingArg: IFlexLiveTextAccounting,
+  deltaArg: string,
+): IFlexLiveTextAccounting | undefined => {
+  if (deltaArg.length === 0) return accountingArg;
+  // A surrogate pair split across the append: two lone halves (3 + 3 UTF-8 bytes, `\uXXXX` + `\uXXXX` in JSON)
+  // become one pair (4 bytes in both).
+  const joinsPair = accountingArg.textEndsWithHighSurrogate && isLowSurrogate(deltaArg.charCodeAt(0));
+  const textUtf8Bytes = accountingArg.textUtf8Bytes + Buffer.byteLength(deltaArg, 'utf8') - (joinsPair ? 2 : 0);
+  const textJsonBytes = accountingArg.textJsonBytes + controllerJsonStringContentBytes(deltaArg) - (joinsPair ? 8 : 0);
+  if (!Number.isSafeInteger(textUtf8Bytes) || !Number.isSafeInteger(textJsonBytes)) return undefined;
+  return {
+    textUtf8Bytes,
+    textJsonBytes,
+    textEndsWithHighSurrogate: isHighSurrogate(deltaArg.charCodeAt(deltaArg.length - 1)),
+  };
+};
+
 const fragmentControllerTextDelta = (valueArg: string): IControllerTextDeltaFragment[] => {
   const fragments: IControllerTextDeltaFragment[] = [];
   let delta = '';
@@ -3031,8 +3102,8 @@ export class OpenCodeController {
   private readonly latestOpenCodeReasoningUpdates = new Map<string, ILatestReasoningUpdate>();
   private readonly latestOpenCodeTextUpdates = new Map<string, ILatestTextUpdate>();
   private readonly latestFlexToolExecutions = new Map<string, ILatestToolExecution>();
-  private readonly latestFlexReasoningUpdates = new Map<string, ILatestReasoningUpdate>();
-  private readonly latestFlexTextUpdates = new Map<string, ILatestTextUpdate>();
+  private readonly latestFlexReasoningUpdates = new Map<string, TLatestFlexReasoningUpdate>();
+  private readonly latestFlexTextUpdates = new Map<string, TLatestFlexTextUpdate>();
   private readonly pendingFlexControllerEvents = new Map<string, IControllerEvent>();
   private readonly pendingFlexAutoAcceptSweeps = new Map<string, IFlexAutoAcceptSweep>();
   private openCodeControllerEventDrainTask?: Promise<void>;
@@ -3049,6 +3120,7 @@ export class OpenCodeController {
   private pendingFlexToolEventBytes = 0;
   private pendingFlexMessageEventBytes = 0;
   private flexControllerEventDrainTask?: Promise<void>;
+  private controllerEventDelivery?: ControllerEventDelivery;
   private flexAutoAcceptDrainTask?: Promise<void>;
   /** Sweeps whose auto-accept failed, queued again when the retry timer fires. */
   private readonly failedFlexAutoAcceptSweeps = new Map<string, IFlexAutoAcceptSweep>();
@@ -13230,6 +13302,7 @@ export class OpenCodeController {
       ...(this.openCodeControllerEventDrainTask ? [this.openCodeControllerEventDrainTask] : []),
       ...(this.flexControllerEventDrainTask ? [this.flexControllerEventDrainTask] : []),
     ]);
+    await this.controllerEventDelivery?.stop();
 
     if (this.flexProjectionReader) {
       await stopPart(async () => {
@@ -16757,7 +16830,7 @@ export class OpenCodeController {
         return { owner, ...(configuration.boardPump ? { configuration: configuration.boardPump } : {}) };
       },
       tickets: async () => (await this.ticketStore.execute('list', {}, undefined)).tickets,
-      ticket: (ticketKeyArg) => this.ticketStore.execute('get', { ticketId: ticketKeyArg }, undefined),
+      history: (ticketKeyArg) => this.ticketStore.history(ticketKeyArg),
       workers: (ownerArg) => this.requireFleetWorkers().views(ownerArg),
       steer: (sessionIdArg, ticketKeyArg, textArg) => this.requireFleetWorkers().notify(sessionIdArg, ticketKeyArg, textArg),
       publish: (eventArg, ownerArg) => this.requireFleetWorkers().events.publish(eventArg, ownerArg),
@@ -17631,6 +17704,7 @@ export class OpenCodeController {
         driver: {
           instructions: service.instructions(await this.readDriverConfiguration()),
           notes: state.scratchpad.text,
+          notesRevision: state.scratchpad.revision,
         },
       };
     }
@@ -23851,7 +23925,8 @@ export class OpenCodeController {
         let cursor: string | undefined;
         for (let pages = 0; ; pages++) {
           if (pages >= 1000) throw new Error('Flex delivery transcript exceeded its inspection limit.');
-          const page = await supervisorArg.request('message.page', {
+          // Metadata pages: identity and state only, so a full scan never moves the transcript's text.
+          const page = await supervisorArg.request('message.metadata.page', {
             ...payload, limit: 50, includeUndone: true, ...(cursor === undefined ? {} : { before: cursor }),
           }, signal);
           for (const message of page.messages) {
@@ -29188,7 +29263,7 @@ export class OpenCodeController {
 
   private setLatestFlexReasoningUpdate(
     keyArg: string,
-    entryArg: ILatestReasoningUpdate,
+    entryArg: TLatestFlexReasoningUpdate,
     bytesArg: number,
   ): void {
     this.deleteLatestFlexReasoningUpdate(keyArg);
@@ -29198,7 +29273,7 @@ export class OpenCodeController {
 
   private setLatestFlexTextUpdate(
     keyArg: string,
-    entryArg: ILatestTextUpdate,
+    entryArg: TLatestFlexTextUpdate,
     bytesArg: number,
   ): void {
     this.deleteLatestFlexTextUpdate(keyArg);
@@ -29721,7 +29796,7 @@ export class OpenCodeController {
       {
         projectId: eventArg.scopeId,
         update,
-        textUtf8Bytes: Buffer.byteLength(update.text, 'utf8'),
+        ...flexLiveTextAccounting(update.text),
       },
       eventBytes,
     );
@@ -29788,7 +29863,7 @@ export class OpenCodeController {
       {
         projectId: eventArg.scopeId,
         update,
-        textUtf8Bytes: Buffer.byteLength(update.text, 'utf8'),
+        ...flexLiveTextAccounting(update.text),
       },
       eventBytes,
     );
@@ -29836,13 +29911,11 @@ export class OpenCodeController {
       this.advanceFlexMessageStreamEpoch(true);
       return;
     }
-    const textUtf8Bytes = controllerTextAfterAppendUtf8Bytes(
-      previous.text,
-      entry.textUtf8Bytes,
-      eventArg.delta,
-    );
+    const accounting = flexLiveTextAccountingAfterAppend(entry, eventArg.delta);
+    const textUtf8Bytes = accounting?.textUtf8Bytes;
     if (
-      textUtf8Bytes === undefined
+      accounting === undefined
+      || textUtf8Bytes === undefined
       || textUtf8Bytes <= entry.textUtf8Bytes
       || textUtf8Bytes !== eventArg.textUtf8Bytes
     ) {
@@ -29851,9 +29924,11 @@ export class OpenCodeController {
     }
 
     const revision = this.flexMessageStreamRevision + 1;
+    // Measured with empty text first: the snapshot's size is that frame plus the text's tracked JSON bytes, so
+    // the growing text is serialized only when a snapshot is served.
     const update = {
       ...previous,
-      text: `${previous.text}${eventArg.delta}`,
+      text: '',
       sourceUpdatedAt,
       revision,
       streamEpoch: this.flexMessageStreamEpoch,
@@ -29915,7 +29990,7 @@ export class OpenCodeController {
           timestamp: sourceUpdatedAt,
         };
     const eventBytes = Buffer.byteLength(JSON.stringify(controllerEvent), 'utf8');
-    const snapshotBytes = Buffer.byteLength(JSON.stringify(snapshotEvent), 'utf8');
+    const snapshotBytes = Buffer.byteLength(JSON.stringify(snapshotEvent), 'utf8') + accounting.textJsonBytes;
     if (
       eventBytes > controllerMaxLiveMessageEventBytes
       || snapshotBytes > controllerMaxLiveMessageEventBytes
@@ -29926,6 +30001,7 @@ export class OpenCodeController {
       return;
     }
 
+    update.text = `${previous.text}${eventArg.delta}`;
     this.flexMessageStreamRevision = revision;
     if (eventArg.partType === 'reasoning') {
       this.setLatestFlexReasoningUpdate(
@@ -29933,7 +30009,7 @@ export class OpenCodeController {
         {
           projectId: eventArg.scopeId,
           update: update as IControllerReasoningUpdate,
-          textUtf8Bytes,
+          ...accounting,
         },
         snapshotBytes,
       );
@@ -29943,7 +30019,7 @@ export class OpenCodeController {
         {
           projectId: eventArg.scopeId,
           update: update as IControllerTextUpdate,
-          textUtf8Bytes,
+          ...accounting,
         },
         snapshotBytes,
       );
@@ -30634,7 +30710,7 @@ export class OpenCodeController {
         {
           projectId: eventArg.projectId,
           update,
-          textUtf8Bytes: Buffer.byteLength(update.text, 'utf8'),
+          ...flexLiveTextAccounting(update.text),
         },
         Buffer.byteLength(JSON.stringify(event), 'utf8'),
       );
@@ -30662,7 +30738,7 @@ export class OpenCodeController {
         {
           projectId: eventArg.projectId,
           update,
-          textUtf8Bytes: Buffer.byteLength(update.text, 'utf8'),
+          ...flexLiveTextAccounting(update.text),
         },
         Buffer.byteLength(JSON.stringify(event), 'utf8'),
       );
@@ -35074,20 +35150,44 @@ export class OpenCodeController {
     ));
   }
 
+  /** Every browser's own ordered event queue (`ControllerEventDelivery`), created with the first event. */
+  private controllerEventDeliveryQueues(): ControllerEventDelivery {
+    this.controllerEventDelivery ??= new ControllerEventDelivery({
+      viewers: async () => {
+        const typedSocket = this.typedServer?.typedsocket;
+        if (!typedSocket) return [];
+        const targets = await this.controllerEventViewers();
+        return targets.map((targetArg) => ({
+          peerId: targetArg.peer.id,
+          send: async (eventArg: IControllerEvent) => {
+            await typedSocket.createTypedRequest<IReq_ControllerEvent>(
+              'controller.event',
+              targetArg,
+              { timeoutMs: 2_000 },
+            ).fire(eventArg, { timeoutMs: 2_000, maxRetries: 0 });
+          },
+        }));
+      },
+      eventKey: (eventArg) => this.controllerEventKey(eventArg),
+      mergeDelta: mergeControllerMessageDeltaEvents,
+      limits: {
+        events: maxPendingControllerEventsPerViewer,
+        bytes: maxPendingControllerEventBytesPerViewer,
+        mergedDeltaBytes: controllerMaxLiveMessageEventBytes,
+      },
+    });
+    return this.controllerEventDelivery;
+  }
+
+  /**
+   * The driver and the session feed see every event once, in order, before any browser; each browser then gets it
+   * through its own queue, so one that acknowledges slowly delays only itself. Resolves once every browser's queue
+   * holds the event, never on an acknowledgement.
+   */
   private async pushControllerEvent(eventArg: IControllerEvent): Promise<void> {
     this.driverService?.observe(eventArg);
     this.sessionFeed?.observe(eventArg);
-    const typedSocket = this.typedServer?.typedsocket;
-    if (!typedSocket) return;
-    const targets = await this.controllerEventViewers();
-    await Promise.allSettled(targets.map(async (targetArg) => {
-      const request = typedSocket.createTypedRequest<IReq_ControllerEvent>(
-        'controller.event',
-        targetArg,
-        { timeoutMs: 2_000 },
-      );
-      await request.fire(eventArg, { timeoutMs: 2_000, maxRetries: 0 });
-    }));
+    await this.controllerEventDeliveryQueues().push(eventArg);
   }
 
   private runUpgradePreparationAdmission<T>(operationArg: () => Promise<T>): Promise<T> {

package/ts/classes.controllereventdelivery.ts

@@ -0,0 +1,289 @@
+import type { IControllerEvent } from '../ts_interfaces/interfaces.js';
+
+/** One authenticated browser connection that receives controller events. */
+export interface IControllerEventViewer {
+  peerId: string;
+  /** Sends one event; resolves on the browser's acknowledgement, rejects on its timeout or a closed connection. */
+  send(eventArg: IControllerEvent): Promise<void>;
+}
+
+export interface IControllerEventDeliveryLimits {
+  /** Events one viewer may have waiting before its queue collapses into a resync. */
+  events: number;
+  /** Serialized bytes one viewer may have waiting before its queue collapses into a resync. */
+  bytes: number;
+  /** The largest live message delta a merge in a viewer's queue may produce. */
+  mergedDeltaBytes: number;
+}
+
+export interface IControllerEventDeliveryOptions {
+  /** The connections that receive events now; read once per batch of pushed events. */
+  viewers(): Promise<IControllerEventViewer[]>;
+  /** Events with one key carry the same state, so in a collapsed queue the newest replaces the older ones. */
+  eventKey(eventArg: IControllerEvent): string;
+  /** Merges a contiguous live message delta into the delta queued just before it, or refuses with `undefined`. */
+  mergeDelta(previousArg: IControllerEvent, eventArg: IControllerEvent): IControllerEvent | undefined;
+  limits: IControllerEventDeliveryLimits;
+}
+
+interface IQueuedControllerEvent {
+  event: IControllerEvent;
+  /** `JSON.stringify(event)` bytes; for a merged delta the sum of its parts, never less than its size. */
+  bytes: number;
+}
+
+interface IViewerQueue {
+  viewer: IControllerEventViewer;
+  /** Waiting events in send order. Normal keys are a sequence; a collapsed queue keys by state. */
+  events: Map<string, IQueuedControllerEvent>;
+  /** The key of the newest waiting event while the queue is not collapsed: where a delta may merge. */
+  tailKey?: string;
+  bytes: number;
+  /** Set when the queue overflowed and until it drains: events then replace older ones of their state. */
+  collapsed: boolean;
+  sending?: Promise<void>;
+  removed: boolean;
+  /** How many times this queue collapsed. */
+  collapses: number;
+}
+
+interface IPendingFanOut {
+  item: IQueuedControllerEvent;
+  delivered: () => void;
+}
+
+const isLiveEvent = (eventArg: IControllerEvent): boolean => Boolean(
+  eventArg.toolExecution
+  || eventArg.reasoningUpdate
+  || eventArg.reasoningDelta
+  || eventArg.textUpdate
+  || eventArg.textDelta,
+);
+
+/** The live stream content in one event, which only a delta's own successor or a re-read can replace. */
+const isMessageDelta = (eventArg: IControllerEvent): boolean => Boolean(eventArg.reasoningDelta || eventArg.textDelta);
+
+/**
+ * Delivers controller events to every viewer through its own bounded, ordered queue, so a viewer that acknowledges
+ * slowly or never delays only itself. Each viewer has at most one event in flight and receives events in push order.
+ *
+ * A viewer whose queue passes its limits is resynchronized alone, with the existing Flex queue's collapse rules:
+ * the queue keeps the newest event of each state key (statuses, barriers, feed and ticket revisions, settings),
+ * drops live tool, reasoning and text content, and ends with `sessions.changed` for each harness whose live content
+ * it dropped, which makes the browser re-read the conversations and the open session (live snapshots included).
+ * The viewer's own revision checks catch any delta that no longer fits. Should a collapsed queue still hold more
+ * than its event limit, each session's states fold into their harness's `sessions.changed` too, so what remains is
+ * one event per harness and per project or global state. The queue stays collapsed until it drains.
+ */
+export class ControllerEventDelivery {
+  private readonly queues = new Map<string, IViewerQueue>();
+  private readonly fanOutQueue: IPendingFanOut[] = [];
+  private fanOutTask?: Promise<void>;
+  private sequence = 0;
+  private generation = 0;
+
+  constructor(private readonly options: IControllerEventDeliveryOptions) {}
+
+  /**
+   * Queues one event for every current viewer, in push order. Resolves once each viewer's queue holds it; it never
+   * waits for an acknowledgement.
+   */
+  public push(eventArg: IControllerEvent): Promise<void> {
+    const item: IQueuedControllerEvent = {
+      event: eventArg,
+      bytes: Buffer.byteLength(JSON.stringify(eventArg), 'utf8'),
+    };
+    return new Promise<void>((resolve) => {
+      this.fanOutQueue.push({ item, delivered: resolve });
+      this.startFanOut();
+    });
+  }
+
+  /** The events waiting for one viewer, in send order (the one in flight excluded). */
+  public waiting(peerIdArg: string): IControllerEvent[] {
+    return [...(this.queues.get(peerIdArg)?.events.values() ?? [])].map((itemArg) => itemArg.event);
+  }
+
+  /** How many times the queue of a connected viewer collapsed into a resync. */
+  public collapseCount(peerIdArg: string): number {
+    return this.queues.get(peerIdArg)?.collapses ?? 0;
+  }
+
+  /** Drops every waiting event and waits for the sends in flight; later pushes start fresh queues. */
+  public async stop(): Promise<void> {
+    this.generation += 1;
+    const sending: Promise<void>[] = [];
+    for (const queue of this.queues.values()) {
+      queue.removed = true;
+      queue.events.clear();
+      queue.bytes = 0;
+      if (queue.sending) sending.push(queue.sending);
+    }
+    this.queues.clear();
+    if (this.fanOutTask) sending.push(this.fanOutTask);
+    await Promise.allSettled(sending);
+  }
+
+  private startFanOut(): void {
+    if (this.fanOutTask) return;
+    const task = this.fanOut().finally(() => {
+      if (this.fanOutTask === task) this.fanOutTask = undefined;
+      if (this.fanOutQueue.length > 0) this.startFanOut();
+    });
+    this.fanOutTask = task;
+  }
+
+  private async fanOut(): Promise<void> {
+    while (this.fanOutQueue.length > 0) {
+      const batch = this.fanOutQueue.splice(0);
+      const generation = this.generation;
+      let viewers: IControllerEventViewer[] = [];
+      try {
+        viewers = await this.options.viewers();
+      } catch {
+        // No viewer can be named now; the events reach none, as a push without connections.
+      }
+      if (generation === this.generation) {
+        const current = new Set(viewers.map((viewerArg) => viewerArg.peerId));
+        for (const [peerId, queue] of this.queues) {
+          if (current.has(peerId)) continue;
+          queue.removed = true;
+          queue.events.clear();
+          queue.bytes = 0;
+          this.queues.delete(peerId);
+        }
+        for (const viewer of viewers) {
+          let queue = this.queues.get(viewer.peerId);
+          if (!queue) {
+            queue = { viewer, events: new Map(), bytes: 0, collapsed: false, removed: false, collapses: 0 };
+            this.queues.set(viewer.peerId, queue);
+          }
+          queue.viewer = viewer;
+          for (const pending of batch) this.enqueue(queue, pending.item);
+          this.startSending(queue);
+        }
+      }
+      for (const pending of batch) pending.delivered();
+    }
+  }
+
+  private enqueue(queueArg: IViewerQueue, itemArg: IQueuedControllerEvent): void {
+    if (queueArg.collapsed) {
+      this.absorb(queueArg, itemArg);
+      return;
+    }
+    if (isMessageDelta(itemArg.event) && queueArg.tailKey !== undefined) {
+      const tailKey = queueArg.tailKey;
+      const tail = queueArg.events.get(tailKey);
+      if (
+        tail !== undefined
+        && isMessageDelta(tail.event)
+        && tail.bytes + itemArg.bytes <= this.options.limits.mergedDeltaBytes
+      ) {
+        const merged = this.options.mergeDelta(tail.event, itemArg.event);
+        if (merged) {
+          queueArg.events.set(tailKey, { event: merged, bytes: tail.bytes + itemArg.bytes });
+          queueArg.bytes += itemArg.bytes;
+          if (queueArg.bytes > this.options.limits.bytes) this.collapse(queueArg);
+          return;
+        }
+      }
+    }
+    if (
+      queueArg.events.size + 1 > this.options.limits.events
+      || queueArg.bytes + itemArg.bytes > this.options.limits.bytes
+    ) {
+      this.collapse(queueArg);
+      this.absorb(queueArg, itemArg);
+      return;
+    }
+    this.sequence += 1;
+    queueArg.tailKey = `#${this.sequence}`;
+    queueArg.events.set(queueArg.tailKey, itemArg);
+    queueArg.bytes += itemArg.bytes;
+  }
+
+  private collapse(queueArg: IViewerQueue): void {
+    const dropped = [...queueArg.events.values()];
+    queueArg.events.clear();
+    queueArg.tailKey = undefined;
+    queueArg.bytes = 0;
+    queueArg.collapsed = true;
+    queueArg.collapses += 1;
+    for (const item of dropped) this.absorb(queueArg, item);
+  }
+
+  /** Adds an event to a collapsed queue: the newest of its state, or a resync of its harness for live content. */
+  private absorb(queueArg: IViewerQueue, itemArg: IQueuedControllerEvent): void {
+    if (isLiveEvent(itemArg.event)) {
+      this.resyncHarness(queueArg, itemArg.event);
+    } else {
+      this.place(queueArg, `state\0${this.options.eventKey(itemArg.event)}`, itemArg);
+    }
+    if (queueArg.events.size > this.options.limits.events) this.foldSessions(queueArg);
+  }
+
+  /**
+   * A collapsed queue that still holds more states than its limit keeps only what is not about one session: each
+   * session's states become their harness's `sessions.changed`, whose re-read covers the open session and the list.
+   */
+  private foldSessions(queueArg: IViewerQueue): void {
+    for (const [key, item] of [...queueArg.events]) {
+      if (!key.startsWith('state\0') || item.event.sessionId === undefined) continue;
+      queueArg.events.delete(key);
+      queueArg.bytes -= item.bytes;
+      this.resyncHarness(queueArg, item.event);
+    }
+  }
+
+  private resyncHarness(queueArg: IViewerQueue, eventArg: IControllerEvent): void {
+    const harnessId = eventArg.harnessId;
+    const event: IControllerEvent = {
+      type: 'sessions.changed',
+      ...(harnessId === undefined ? {} : { harnessId }),
+      timestamp: eventArg.timestamp,
+    };
+    this.place(
+      queueArg,
+      `resync\0${harnessId ?? ''}`,
+      { event, bytes: Buffer.byteLength(JSON.stringify(event), 'utf8') },
+    );
+  }
+
+  /** Puts an event last under its key, replacing an older one with that key. */
+  private place(queueArg: IViewerQueue, keyArg: string, itemArg: IQueuedControllerEvent): void {
+    const replaced = queueArg.events.get(keyArg);
+    if (replaced) {
+      queueArg.events.delete(keyArg);
+      queueArg.bytes -= replaced.bytes;
+    }
+    queueArg.events.set(keyArg, itemArg);
+    queueArg.bytes += itemArg.bytes;
+  }
+
+  private startSending(queueArg: IViewerQueue): void {
+    if (queueArg.sending || queueArg.events.size === 0) return;
+    const task = this.send(queueArg).finally(() => {
+      if (queueArg.sending === task) queueArg.sending = undefined;
+      if (!queueArg.removed && queueArg.events.size > 0) this.startSending(queueArg);
+    });
+    queueArg.sending = task;
+  }
+
+  private async send(queueArg: IViewerQueue): Promise<void> {
+    while (!queueArg.removed) {
+      const next = queueArg.events.entries().next().value as [string, IQueuedControllerEvent] | undefined;
+      if (!next) return;
+      queueArg.events.delete(next[0]);
+      queueArg.bytes -= next[1].bytes;
+      if (queueArg.tailKey === next[0]) queueArg.tailKey = undefined;
+      if (queueArg.events.size === 0) queueArg.collapsed = false;
+      try {
+        await queueArg.viewer.send(next[1].event);
+      } catch {
+        // As before: a viewer that does not acknowledge in time misses nothing it already received, and a closed
+        // connection leaves the viewer set at the next push.
+      }
+    }
+  }
+}

package/ts/classes.flexmodels.public.ts

@@ -727,6 +727,16 @@ export class FlexPublicHeadModel extends plugins.nosqldb.SmartDataDbDoc<
   name: 'flex_public_session_scope_purge',
   key: { controllerId: 1, scopeId: 1, id: 1 },
 })
+/**
+ * One session's records in a scope: a reader finds the record a publication lists for a session
+ * among that session's versions, never among every session's records. Created by the startup
+ * init of the models (`initFlexPublicModels`, the projection reader's `init`), outside any
+ * transaction. An older AGL leaves the index it does not declare alone.
+ */
+@plugins.nosqldb.compoundIndex({
+  name: 'flex_public_session_lookup',
+  key: { controllerId: 1, scopeId: 1, 'session.sessionId': 1 },
+})
 @plugins.nosqldb.managed({ collectionName: flexPublicSessionsCollectionName })
 export class FlexPublicSessionRecordModel extends plugins.nosqldb.SmartDataDbDoc<
   FlexPublicSessionRecordModel,

package/ts/classes.flexprojectionreader.ts

@@ -414,9 +414,7 @@ export class FlexProjectionReader {
     signalArg?: AbortSignal,
   ): Promise<TFlexSession> {
     const selection = await this.selectCandidate(scopeIdArg, undefined, signalArg);
-    const records = await this.loadSessionRecords(selection, signalArg);
-    const record = records.find((entry) => entry.session.sessionId === sessionIdArg);
-    if (!record) throw new FlexProjectionNotFoundError();
+    const record = await this.loadSessionRecord(selection, sessionIdArg, signalArg);
     return JSON.parse(JSON.stringify(record.session)) as TFlexSession;
   }
 
@@ -627,6 +625,35 @@ export class FlexProjectionReader {
     }).sort(compareNewestSession);
   }
 
+  /**
+   * The record the selected publication lists for one session: looked up through the session
+   * index among the records the publication lists, so it reads that session's records only, and
+   * proven against its manifest.
+   */
+  private async loadSessionRecord(
+    selectionArg: IFlexCandidateSelection,
+    sessionIdArg: string,
+    signalArg?: AbortSignal,
+  ): Promise<IFlexPublicSessionRecordDocument> {
+    const sessionRecords = selectionArg.manifest.sessionRecords;
+    const models = await this.models.publicSessions.getOffsetPage({
+      controllerId: this.controllerId,
+      scopeId: selectionArg.head.storageKey,
+      'session.sessionId': sessionIdArg,
+      id: { $in: sessionRecords.map((record) => record.id) },
+    }, this.pageOptions(2, signalArg));
+    // A publication lists one record per session.
+    if (models.length > 1) throw new FlexProjectionFormatError();
+    const [model] = models;
+    if (!model) throw new FlexProjectionNotFoundError();
+    const document = projectSessionRecord(model);
+    assertFlexPublicSessionRecordDocument(document);
+    const manifest = sessionRecords.find((record) => record.id === document.id);
+    if (!manifest || document.session.sessionId !== sessionIdArg) throw new FlexProjectionFormatError();
+    verifyRecordManifest(document, manifest);
+    return document;
+  }
+
   /**
    * The transcript the selected publication names for a session, proven by its id; a session
    * without messages has none.