akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/service/agent.service.ts

@@ -2,6 +2,7 @@ import { Err } from "akanjs/dictionary";
 import type {
   AgentWireAttachment,
   AgentWireMessage,
+  AgentWireReference,
   LlmAccepts,
   LlmTurnRequest,
 } from "./predefinedAdaptor/llm.adaptor";
@@ -13,32 +14,27 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
   llm: plug(LlmAdaptorRole),
 })) {
   async runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void) {
-
     const names = ToolNames.of(request);
     const prepared = names.encode(
-      AgentService.instructed(AgentService.readable(AgentService.explained(request), this.llm.accepts)),
+      AgentService.instructed(
+        AgentService.readable(AgentService.referenced(AgentService.explained(request)), this.llm.accepts),
+      ),
     );
     const answer = await this.llm.chat(prepared, onDelta);
     if (!answer) throw new Err("agent.error.llmUnavailable");
-    return { text: answer.text ?? "", toolCalls: names.decode(answer.toolCalls ?? []), stop: answer.stop };
+    return {
+      text: answer.text ?? "",
+      toolCalls: names.decode(answer.toolCalls ?? []),
+      stop: answer.stop,
+      ...(answer.usage ? { usage: answer.usage } : {}),
+      ...(answer.model ? { model: answer.model } : {}),
+      ...(this.llm.limits ? { limits: this.llm.limits } : {}),
+    };
   }
 
   /**
-   * The framework's half of the system prompt, ahead of whatever the app said so the app's text stays the more
-   * specific one. Composed here rather than in an adaptor for the reason `explained` is: every adaptor would
-   * otherwise have to remember it, and forgetting is silent.
-   *
-   * The last two sentences are the load-bearing ones, and both were measured against the provider rather than
-   * guessed at (8 runs a cell, one screen, tools stubbed):
-   *
-   * - Batching. One call per turn costs a full model round trip and a resend of the whole transcript per call, and
-   *   the turn cap then parks the run on a question halfway through. Asking for it took "approve these eight" from
-   *   1.5 turns with three runs in eight that did nothing at all, to one turn in eight runs out of eight.
-   * - Not re-reading. A model that has just written something goes back to look at what it did, one read per turn,
-   *   which is where a chain of ten calls actually comes from — the change report it was already handed says the
-   *   same thing. Saying so took "read the screen, then approve what is pending" from 3.0 turns to 2.0, its floor,
-   *   in every run. It is scoped to confirmation on purpose: the read a fresh route needs after `navigate` is
-   *   acquisition, and it survived the sentence in every run of that scenario.
+   * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
+   * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
    */
   static readonly preamble = [
     "You are an in-page assistant. Use the published tools to read and drive the screen the user is looking at.",
@@ -51,12 +47,7 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...request, instructions: [AgentService.preamble, request.instructions].filter(Boolean).join("\n\n") };
   }
 
-  /**
-   * Folds a failed turn into the message text. `error` is a field only this wire has, so a provider mapping reads
-   * `text` and drops it — leaving the model an assistant turn that says nothing, with no hint that the attempt
-   * failed, and every reason to make the same one again. Done here rather than per adaptor because every adaptor
-   * would otherwise have to remember, and forgetting is silent.
-   */
+  /** Provider mappings read `text` and drop `error`, so a failed turn is folded into its text or retried blind. */
   static explained(request: LlmTurnRequest): LlmTurnRequest {
     if (!request.messages.some((message) => message.error)) return request;
     return { ...request, messages: request.messages.map((message) => AgentService.explainedMessage(message)) };
@@ -68,13 +59,50 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...rest, text: [message.text, `[The turn failed: ${error}]`].filter(Boolean).join("\n\n") };
   }
 
-  /**
-   * Replaces every attachment the provider cannot read with a note naming it, so no adaptor has to think about
-   * attachments it does not support and none can lose one quietly. The model has to be *told*, not merely spared:
-   * a file that vanishes on the way in is one it answers about from the filename, confidently and wrongly.
-   *
-   * The note rides in the message text because that is the one field every provider mapping already reads.
-   */
+  /** Mirrors the client's clip where nothing routes around it: a hand-built wire or an older client passes here too. */
+  static readonly referenceLimit = 20_000;
+
+  /** As text, the one field every provider mapping reads; the heading stays out of `preamble`: most turns lack one. */
+  static referenced(request: LlmTurnRequest): LlmTurnRequest {
+    if (!request.messages.some((message) => message.references?.length)) return request;
+    return { ...request, messages: request.messages.map((message) => AgentService.referencedMessage(message)) };
+  }
+
+  private static referencedMessage(message: AgentWireMessage): AgentWireMessage {
+    const { references = [], ...rest } = message;
+    if (!references.length) return message;
+    const block = [AgentService.referenceHeading, ...references.map(AgentService.referenceLine)].join("\n\n");
+    return { ...rest, text: [message.text, block].filter(Boolean).join("\n\n") };
+  }
+
+  /** Not free to shorten: both halves were observed working — a re-read with a tool, else a caveat. */
+  static readonly referenceHeading =
+    "[Referenced data: the user pointed at this while writing the message above, with the @[label](mention:…) " +
+    "tokens in it. Each value is what it was at the moment they sent the message, not what it is now — read it " +
+    "again with a tool before relying on it, and do not assume an edit you have made since is reflected here.]";
+
+  private static referenceLine(reference: AgentWireReference): string {
+    const at = `${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}`;
+    const head = `${at} (${reference.label}):`;
+    if (reference.value === undefined)
+      return `${head} [not read: ${reference.note ?? "the value was not carried into this conversation"}]`;
+    const text =
+      typeof reference.value === "string" ? reference.value : (JSON.stringify(reference.value, null, 2) ?? "null");
+    const body =
+      text.length <= AgentService.referenceLimit
+        ? text
+        : `${text.slice(0, AgentService.referenceLimit)}…\n[Clipped at ${AgentService.referenceLimit} characters.]`;
+    return `${head}\n${AgentService.fenced(body)}${reference.note ? `\n[${reference.note}]` : ""}`;
+  }
+
+  private static fenced(text: string): string {
+    const runs = text.match(/`+/g);
+    const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+    const fence = "`".repeat(Math.max(3, longest + 1));
+    return `${fence}\n${text}\n${fence}`;
+  }
+
+  /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
   static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest {
     if (!request.messages.some((message) => message.attachments?.length)) return request;
     const messages = request.messages.map((message) => AgentService.readableMessage(message, accepts ?? {}));
@@ -94,18 +122,21 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     };
   }
 
-  /** Extracted text is readable by every model there is; bytes and links need the provider to say so. */
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;
+    
+    if (typeof attachment.mimeType !== "string") return false;
     return attachment.mimeType.startsWith("image/") ? !!accepts.image : !!accepts.document;
   }
 
   private static note(attachment: AgentWireAttachment): string {
     const why =
-      attachment.data || attachment.url
-        ? "this model cannot read that type"
-        : "its content is no longer available, as a reloaded conversation keeps the name and not the bytes";
+      !attachment.data && !attachment.url
+        ? "its content is no longer available, as a reloaded conversation keeps the name and not the bytes"
+        : typeof attachment.mimeType === "string"
+          ? "this model cannot read that type"
+          : "it names no type it could be read as";
     return `[Attachment not read: ${attachment.name} (${attachment.mimeType}) — ${why}. Tell the user it was not read instead of guessing what it holds, and ask for the text if the answer needs it.]`;
   }
 }

package/service/injectInfo.ts

@@ -1,4 +1,4 @@
-import { type BackendEnv, type Cls, INJECT_META, PrimitiveRegistry } from "akanjs/base";
+import { type BackendEnv, type Cls, dayjs, INJECT_META, PrimitiveRegistry } from "akanjs/base";
 import {
   type ConstantFieldTypeInput,
   ConstantRegistry,
@@ -17,7 +17,7 @@ import type {
 } from "akanjs/signal";
 import type { Adaptor, AdaptorCls, Service, ServiceCls } from ".";
 import { LiveSyncHub } from "./liveSyncHub";
-import type { CacheAdaptor, CacheSetOptions } from "./predefinedAdaptor";
+import type { CacheAdaptor, CacheSetOptions, CacheValue } from "./predefinedAdaptor";
 
 export type InjectType = "database" | "service" | "use" | "signal" | "plug" | "env" | "memory";
 
@@ -30,7 +30,7 @@ interface InjectBuilderOptions<ReturnType> {
   local?: boolean;
   default?: unknown;
   isMap?: boolean;
-  cacheOption?: CacheSetOptions;
+  ttl?: number;
   parentRefName: string;
 }
 
@@ -77,7 +77,6 @@ export interface LiveRegistry {
   internal: Map<string, Internal>;
   sliceCls: Map<string, SliceCls>;
   endpointCls: Map<string, EndpointCls>;
-  /** The process's one live-sync router. Rooms are registered on it at subscribe and read from it on every write. */
   syncHub: LiveSyncHub;
 }
 export const getDefaultLiveRegistry = (): LiveRegistry => ({
@@ -104,7 +103,8 @@ export class InjectInfo<
   readonly adaptor?: AdaptorCls;
   readonly default?: unknown;
   readonly isMap?: boolean;
-  readonly cacheOption?: CacheSetOptions;
+  /** How long a `memory` value lives by default, in milliseconds — a `set` that names its own `expireAt` wins. */
+  readonly ttl?: number;
   readonly parentRefName: string;
   constructor(type: Type, options: InjectBuilderOptions<ReturnType>) {
     this.type = type;
@@ -116,7 +116,7 @@ export class InjectInfo<
     this.set = options.set;
     this.default = options.default;
     this.isMap = options.isMap ?? false;
-    this.cacheOption = options.cacheOption;
+    this.ttl = options.ttl;
     this.parentRefName = options.parentRefName;
   }
   static async resolveInjection(
@@ -261,80 +261,87 @@ export class InjectInfo<
   ) {
     if (injectInfo.local) {
       Object.defineProperty(instance, propKey, {
-        value: injectInfo.default ?? null,
+        value: injectInfo.isMap ? new Map() : (injectInfo.default ?? null),
         writable: true,
         enumerable: true,
       });
-    } else if (injectInfo.isMap) {
-      const topic = `akan:memory:${injectInfo.parentRefName}`;
-      const getter = injectInfo.get as unknown as (value: unknown) => unknown;
-      const setter = injectInfo.set as unknown as (value: unknown) => string | number | Buffer;
-      const get = async (key: string) => {
-        const value = await cacheAdaptor.hget(topic, propKey, key);
-        return value === undefined || value === null ? undefined : getter(value);
-      };
-      const set = async (key: string, value: unknown, option?: CacheSetOptions) => {
-        const setValue = setter(value);
-        await cacheAdaptor.hset(topic, propKey, key, setValue, option ?? injectInfo.cacheOption);
-      };
-      Object.defineProperty(instance, propKey, {
-        value: {
-          get,
-          set,
-          delete: async (key: string) => {
-            await cacheAdaptor.hdelete(topic, propKey, key);
-          },
-          getOrInsert: async (key: string, value: unknown, option?: CacheSetOptions) => {
-            const existingValue = await get(key);
-            if (existingValue !== undefined) return existingValue;
-            await set(key, value, option);
-            return value;
-          },
-          getOrInsertComputed: async (
-            key: string,
-            compute: (key: string) => unknown | Promise<unknown>,
-            option?: CacheSetOptions,
-          ) => {
-            const existingValue = await get(key);
-            if (existingValue !== undefined) return existingValue;
-            const value = await compute(key);
-            await set(key, value, option);
-            return value;
-          },
-          keys: async () => await cacheAdaptor.hkeys(topic, propKey),
-          entries: async () => {
-            const entries = await cacheAdaptor.hentries(topic, propKey);
-            return entries.map(([key, value]) => [key, getter(value)]);
-          },
-          forEach: async (callback: (value: unknown, key: string) => void | Promise<void>) => {
-            for (const [key, value] of await cacheAdaptor.hentries(topic, propKey)) await callback(getter(value), key);
-          },
-          clear: async () => {
-            await cacheAdaptor.hclear(topic, propKey);
-          },
-        },
-      });
-    } else {
+      return;
+    }
+    
+    const topic = `akan:memory:${injectInfo.parentRefName}`;
+    const getter = injectInfo.get as unknown as (value: unknown) => unknown;
+    const setter = injectInfo.set as unknown as (value: unknown) => CacheValue;
+    const optionOf = (option?: CacheSetOptions): CacheSetOptions | undefined =>
+      option ?? (injectInfo.ttl ? { expireAt: dayjs().add(injectInfo.ttl, "millisecond") } : undefined);
+    if (!injectInfo.isMap) {
       Object.defineProperty(instance, propKey, {
         value: {
-          get: async () => {
-            const getter = injectInfo.get as unknown as (value: unknown) => unknown;
-            const value = await cacheAdaptor.get("akan:memory", propKey);
-            return value === null ? value : getter(value);
-          },
+          get: async () => getter((await cacheAdaptor.get(topic, propKey)) ?? undefined),
           set: async (value: unknown, option?: CacheSetOptions) => {
-            const setter = injectInfo.set as unknown as (value: unknown) => string | number | Buffer;
-            const setValue = setter(value);
-            await cacheAdaptor.set("akan:memory", propKey, setValue, option ?? injectInfo.cacheOption);
+            await cacheAdaptor.set(topic, propKey, setter(value), optionOf(option));
           },
           delete: async () => {
-            await cacheAdaptor.delete("akan:memory", propKey);
+            await cacheAdaptor.delete(topic, propKey);
           },
+          getDel: async () => getter((await cacheAdaptor.getDel(topic, propKey)) ?? undefined),
+          setIfAbsent: async (value: unknown, option?: CacheSetOptions) =>
+            await cacheAdaptor.setIfAbsent(topic, propKey, setter(value), optionOf(option)),
+          incr: async (by = 1, option?: CacheSetOptions) =>
+            await cacheAdaptor.incr(topic, propKey, by, optionOf(option)),
         },
         writable: false,
         enumerable: true,
       });
+      return;
     }
+    const readEntry = (value: unknown) => (value === undefined || value === null ? undefined : getter(value));
+    const get = async (key: string) => readEntry(await cacheAdaptor.hget(topic, propKey, key));
+    const set = async (key: string, value: unknown, option?: CacheSetOptions) => {
+      await cacheAdaptor.hset(topic, propKey, key, setter(value), optionOf(option));
+    };
+    
+    const insert = async (key: string, value: unknown, option?: CacheSetOptions) => {
+      if (await cacheAdaptor.hsetIfAbsent(topic, propKey, key, setter(value), optionOf(option))) return value;
+      const stored = await get(key);
+      return stored !== undefined ? stored : value;
+    };
+    Object.defineProperty(instance, propKey, {
+      value: {
+        get,
+        set,
+        delete: async (key: string) => {
+          await cacheAdaptor.hdelete(topic, propKey, key);
+        },
+        getDel: async (key: string) => readEntry(await cacheAdaptor.hgetDel(topic, propKey, key)),
+        setIfAbsent: async (key: string, value: unknown, option?: CacheSetOptions) =>
+          await cacheAdaptor.hsetIfAbsent(topic, propKey, key, setter(value), optionOf(option)),
+        incr: async (key: string, by = 1, option?: CacheSetOptions) =>
+          await cacheAdaptor.hincr(topic, propKey, key, by, optionOf(option)),
+        getOrInsert: async (key: string, value: unknown, option?: CacheSetOptions) => {
+          const existingValue = await get(key);
+          return existingValue !== undefined ? existingValue : await insert(key, value, option);
+        },
+        getOrInsertComputed: async (
+          key: string,
+          compute: (key: string) => unknown | Promise<unknown>,
+          option?: CacheSetOptions,
+        ) => {
+          const existingValue = await get(key);
+          return existingValue !== undefined ? existingValue : await insert(key, await compute(key), option);
+        },
+        keys: async () => await cacheAdaptor.hkeys(topic, propKey),
+        entries: async () => {
+          const entries = await cacheAdaptor.hentries(topic, propKey);
+          return entries.map(([key, value]) => [key, getter(value)]);
+        },
+        forEach: async (callback: (value: unknown, key: string) => void | Promise<void>) => {
+          for (const [key, value] of await cacheAdaptor.hentries(topic, propKey)) await callback(getter(value), key);
+        },
+        clear: async () => {
+          await cacheAdaptor.hclear(topic, propKey);
+        },
+      },
+    });
   }
 }
 
@@ -370,7 +377,9 @@ export const injectionBuilder = (parentRefName: string) => ({
     ValueRef extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
     MapValue = never,
     DefaultValue extends GetFieldValue<ValueRef, ExplicitType> = never,
-    GetFn extends (value: GetFieldValue<ValueRef, ExplicitType>) => unknown = never,
+    GetFn extends (
+      value: MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>,
+    ) => unknown = never,
     Local extends boolean = false,
   >(
     modelRef: ValueRef,
@@ -378,9 +387,13 @@ export const injectionBuilder = (parentRefName: string) => ({
       local?: Local;
       default?: DefaultValue;
       of?: MapValue;
-      expireAt?: CacheSetOptions["expireAt"];
+      /** Milliseconds each write lives unless the `set` call names its own `expireAt`. */
+      ttl?: number;
+      /** Turns the stored value — a Map's entry value — into what the code reads; `set` is its inverse. */
       get?: GetFn;
-      set?: (value: ReturnType<GetFn>) => GetFieldValue<ValueRef, ExplicitType>;
+      set?: (
+        value: ReturnType<GetFn>,
+      ) => MapConstructor extends ValueRef ? FieldToValue<MapValue> : GetFieldValue<ValueRef, ExplicitType>;
     } = {},
   ) => {
     if (opts.local && (!!opts.get || !!opts.set))
@@ -390,10 +403,12 @@ export const injectionBuilder = (parentRefName: string) => ({
     const isMap = modelRef === Map;
     if (isMap && !opts.of) throw new Error("of should be provided when modelRef is Map");
     const valueRef = (isMap ? opts.of : modelRef) as Cls;
-
+    
     const isStructured = Array.isArray(valueRef) || !PrimitiveRegistry.has(valueRef);
-    type FieldValue = never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>;
-    type MapFieldValue = never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>;
+    const read = opts.get as ((value: unknown) => unknown) | undefined;
+    const write = opts.set as ((value: unknown) => unknown) | undefined;
+    type FieldValue = [GetFn] extends [never] ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>;
+    type MapFieldValue = [GetFn] extends [never] ? FieldToValue<MapValue> : ReturnType<GetFn>;
     type IsNullable = DefaultValue extends never ? true : false;
     type UseValue = IsNullable extends true ? FieldValue | null : FieldValue;
     return new InjectInfo<
@@ -407,6 +422,12 @@ export const injectionBuilder = (parentRefName: string) => ({
               get: (key: string) => Promise<MapFieldValue | undefined>;
               set: (key: string, value: MapFieldValue, option?: CacheSetOptions) => Promise<void>;
               delete: (key: string) => Promise<void>;
+              /** Reads and removes the entry in one step: of two callers racing for it, one gets it. */
+              getDel: (key: string) => Promise<MapFieldValue | undefined>;
+              /** Writes only where no live entry is stored, and answers whether this call wrote. */
+              setIfAbsent: (key: string, value: MapFieldValue, option?: CacheSetOptions) => Promise<boolean>;
+              /** Adds to a numeric entry and answers the sum; an entry this call creates takes the expiry. */
+              incr: (key: string, by?: number, option?: CacheSetOptions) => Promise<number>;
               getOrInsert: (key: string, value: MapFieldValue, option?: CacheSetOptions) => Promise<MapFieldValue>;
               getOrInsertComputed: (
                 key: string,
@@ -422,6 +443,9 @@ export const injectionBuilder = (parentRefName: string) => ({
               get: () => Promise<UseValue>;
               set: (value: UseValue, option?: CacheSetOptions) => Promise<void>;
               delete: () => Promise<void>;
+              getDel: () => Promise<UseValue>;
+              setIfAbsent: (value: UseValue, option?: CacheSetOptions) => Promise<boolean>;
+              incr: (by?: number, option?: CacheSetOptions) => Promise<number>;
             },
       never,
       ValueRef
@@ -430,16 +454,23 @@ export const injectionBuilder = (parentRefName: string) => ({
       get: (serializedValue: never) => {
         const stored = serializedValue as unknown;
         
+        if (stored === undefined || stored === null) {
+          if (opts.default === undefined) return null;
+          return read ? read(opts.default) : opts.default;
+        }
+        
         const rawValue = isStructured && typeof stored === "string" ? JSON.parse(stored) : stored;
-        return ConstantRegistry.deserialize(valueRef, (rawValue as object | null) ?? opts.default, true) ?? null;
+        const value = ConstantRegistry.deserialize(valueRef, rawValue as object, true) ?? null;
+        return read && value !== null ? read(value) : value;
       },
       set: (value: never) => {
-        const serialized = ConstantRegistry.serialize(valueRef, value, true) ?? opts.default ?? null;
+        const plain = write ? write(value) : value;
+        const serialized = ConstantRegistry.serialize(valueRef, plain, true) ?? opts.default ?? null;
         return isStructured ? JSON.stringify(serialized) : serialized;
       },
       default: opts.default as unknown,
       isMap,
-      cacheOption: opts.expireAt ? { expireAt: opts.expireAt } : undefined,
+      ttl: opts.ttl,
       parentRefName,
     });
   },

package/service/ipcTypes.ts

@@ -1,4 +1,5 @@
 import type { LogRecord } from "akanjs/common";
+import type { LiveChange } from "./predefinedAdaptor/websocket.adaptor";
 
 export type AkanChildRole = "all" | "federation" | "batch";
 
@@ -9,6 +10,7 @@ export type AkanUpstream = { type: "unix"; socketPath: string } | { type: "tcp";
 export interface AkanJobOptions {
   delay?: number;
   attempts?: number;
+  /** Smaller runs sooner, and a job with none runs before every prioritized one — bullmq's reading. */
   priority?: number;
   backoff?: number | { type?: string; delay?: number };
   removeOnComplete?: boolean | number;
@@ -58,7 +60,7 @@ export interface AkanMetricsReport {
   rscWorkerRestartCount?: number;
   rscWorkerRecycleCount?: number;
   rscWorkerLastRecycleReason?: string;
-
+  
   rscWorkerReportedAt?: number;
   rscWorkerRssBytes?: number;
   rscWorkerHeapTotalBytes?: number;
@@ -149,6 +151,7 @@ export type AkanIpcMessage =
   | { type: "pubsub.unsubscribe"; roomId: string; socketId?: string; pid?: number }
   | { type: "pubsub.snapshot.request" }
   | { type: "pubsub.snapshot"; rooms: string[]; pid?: number }
+  | { type: "live.change"; change: LiveChange; origin?: string }
   | { type: "queue.enqueued"; queue: string; name: string; jobId: string }
   | { type: "queue.wake"; queue?: string; name?: string }
   | { type: "health.ping"; nonce: string; sentAt: number }

package/service/liveSyncHub.ts

@@ -40,26 +40,13 @@ interface LiveRoom {
   evaluator: DocumentQueryEvaluator;
   payload: "light" | "id";
   subscribers: number;
-  /**
-   * Top-level `<path> eq <value>` conditions this room's query requires, when it is a plain conjunction of them.
-   * A change whose document disagrees with one of these cannot belong to this room, and cannot have belonged to it
-   * before either, so the room is skipped without walking its tree at all.
-   */
+  /** The query's top-level `eq` conditions when it is a plain conjunction; a document disagreeing skips the room. */
   index: Map<string, unknown> | null;
 }
 
 /**
- * Routes a document change to the rooms it belongs to.
- *
- * A room is one live subscription's resolved query, kept from the moment the socket subscribed. When a document
- * changes, the same query is evaluated against the version before the write and the version after it, and the pair
- * of answers is the event: appearing is `enter`, disappearing is `leave`, and staying is `update`. That is why the
- * CRUD verb never reaches a subscriber — an edit that moves a row out of a filter has to arrive as a removal from
- * that list, and a create that lands in one has to arrive as an insertion, which the verb alone cannot say.
- *
- * Every read wraps the caller's query in `removedAt` being empty (`SqlDocumentStore.findForRead`), and that wrapper
- * is added by the store rather than carried in the descriptor a slice returns. It is applied here for the same
- * reason: without it a soft delete still satisfies the query and would be routed as an ordinary update.
+ * Evaluates each room's query before and after a write: appearing is `enter`, disappearing `leave`, staying `update`.
+ * `removedAt` is wrapped in here as the store does on every read, or a soft delete would route as an update.
  */
 export class LiveSyncHub {
   readonly #rooms = new Map<string, LiveRoom>();
@@ -106,7 +93,6 @@ export class LiveSyncHub {
     return room;
   }
 
-  /** Every room this process currently holds, for a recovery that has to tell all of them to resynchronize. */
   roomIds(): string[] {
     return [...this.#rooms.keys()];
   }
@@ -122,11 +108,7 @@ export class LiveSyncHub {
     if (forModel && !forModel.size) this.#roomsByModel.delete(room.refName);
   }
 
-  /**
-   * Which rooms this change belongs to and how it reads in each.
-   *
-   * `previous` is absent on a create, which is the same thing as having belonged to no room before.
-   */
+  /** `previous` is absent on a create — no room held the document before. */
   route(refName: string, next: Record<string, unknown>, previous?: Record<string, unknown>): LiveRoomTarget[] {
     const rooms = this.#roomsByModel.get(refName);
     if (!rooms?.size) return [];
@@ -149,7 +131,6 @@ export class LiveSyncHub {
     return targets;
   }
 
-  /** A cheap pre-filter: false only when the room's own equality conditions rule the document out outright. */
   static #mayMatch(room: LiveRoom, row: DocumentRowView): boolean {
     if (!room.index) return true;
     for (const [path, value] of room.index) {
@@ -159,17 +140,6 @@ export class LiveSyncHub {
     return true;
   }
 
-  /**
-   * The top-level equality conditions of a query, when it is nothing but those.
-   *
-   * Most slices are `{ org: <id> }` or `{ org: <id>, status: "open" }`, so a write on a document belonging to one
-   * organisation can skip every room belonging to another without evaluating anything. Anything less regular —
-   * a nested group, an operator, a dotted path — indexes nothing and evaluates in full.
-   *
-   * Two shapes are excluded because the stored value is not the operand even though it looks like it is: a base
-   * column, which the row holds encoded rather than as the caller wrote it, and an array field, where a bare value
-   * means membership. Indexing either would skip a room that does match.
-   */
   static #indexOf(query: DocumentQuery | undefined, fields: QueryFieldMap): Map<string, unknown> | null {
     if (!query || typeof query !== "object" || "kind" in query) return null;
     const index = new Map<string, unknown>();