akanjs 3.0.0-beta.8 → 3.0.0

package/service/agent.service.ts

@@ -14,7 +14,6 @@ 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(
@@ -23,25 +22,19 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     );
     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.",
@@ -54,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)) };
@@ -71,24 +59,10 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...rest, text: [message.text, `[The turn failed: ${error}]`].filter(Boolean).join("\n\n") };
   }
 
-  /**
-   * The ceiling one reference's value may add to a turn, mirroring the client's own — the browser clips before it
-   * stages, and this is the same answer given again where nothing can route around it. `runTurn` is the only path
-   * to `chat()`, so a host that builds the wire itself, an older client, and a replayed transcript all pass here.
-   */
+  /** 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;
 
-  /**
-   * Folds what the user pointed at into the message they pointed with, as text.
-   *
-   * Text rather than a carrier of its own for the same reason the note in `readable` is text: it is the one field
-   * every provider mapping already reads, so Anthropic, the OpenAI dialect and DeepSeek need no change between
-   * them and none of them can drop a reference quietly.
-   *
-   * The heading rides once per message rather than once per reference, and lives here rather than in `preamble`
-   * because most conversations never carry one — a sentence about mention tokens in every turn of every app is
-   * paid by every app that has no references at all.
-   */
+  /** 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)) };
@@ -101,35 +75,12 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return { ...rest, text: [message.text, block].filter(Boolean).join("\n\n") };
   }
 
-  /**
-   * Not decoration, and not free to shorten. Both halves of the sentence were observed doing their job, against
-   * Anthropic, with the same referenced field and only the published tools changed:
-   *
-   * - With no tool on the screen to re-read with, the model opened its answer by saying so — that it could see
-   *   only the snapshot and the field might have been edited since. Unprompted, ahead of the answer.
-   * - With the screen's own tools passed (a state read and a write), it issued the read instead of answering,
-   *   and stopped the turn there.
-   *
-   * So it reads as an instruction rather than as framing: it re-reads where it can and says it cannot where it
-   * cannot, which is the pair a turn confidently quoting a stale value is bought against. Two scenarios against
-   * one provider, not the per-cell runs behind `preamble` — enough to keep the sentence, not enough to call it
-   * measured.
-   */
+  /** 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.]";
 
-  /**
-   * A string value is printed as itself rather than as JSON. It is the common case — one field of one document —
-   * and a quoted, escaped copy of a paragraph is harder for a model to read back and to quote from than the
-   * paragraph. It is also what a clipped value already is, so the cut JSON prints as the fragment it is.
-   *
-   * The pointer leads the line rather than riding the wire alone, and that is what the label cannot do. Pointed
-   * at a saved document while a *different* document of the same model sat open on the screen, the model
-   * compared the two ids, said the edit it could make would land on the wrong one, and stopped to ask — with no
-   * write call. Two references sharing a label are still two ids here, so keep the id ahead of the label.
-   */
   private static referenceLine(reference: AgentWireReference): string {
     const at = `${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}`;
     const head = `${at} (${reference.label}):`;
@@ -144,14 +95,6 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return `${head}\n${AgentService.fenced(body)}${reference.note ? `\n[${reference.note}]` : ""}`;
   }
 
-  /**
-   * Where a value ends. A multi-line one — the usual shape of the prose field somebody points at — otherwise runs
-   * straight into the next reference's heading, and the model reads one value that swallowed the next label.
-   *
-   * The fence grows past the longest backtick run inside the value, which is CommonMark's own answer to the same
-   * problem: a fixed fence is one that a value containing a fence breaks out of, and a value containing a fence is
-   * ordinary here, because the thing being pointed at is often something a person wrote.
-   */
   private static fenced(text: string): string {
     const runs = text.match(/`+/g);
     const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
@@ -159,13 +102,7 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     return `${fence}\n${text}\n${fence}`;
   }
 
-  /**
-   * 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.
-   */
+  /** 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 ?? {}));
@@ -185,11 +122,10 @@ 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;
   }

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;
@@ -141,6 +143,7 @@ export type AkanIpcMessage =
       /** Actual websocket upstream the child bound; may differ from the preferred port when it was in use. */
       wsUpstream?: Extract<AkanUpstream, { type: "tcp" }>;
       healthPath?: string;
+      crossSite?: { allowedOrigins: string[]; enabled: boolean };
     }
   | { type: "backend-ready"; pid: number }
   | { type: "pubsub.publish"; roomId: string; data: object | object[]; origin?: string }
@@ -149,6 +152,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 }
@@ -160,6 +164,9 @@ export type AkanIpcMessage =
   /** Hub → child: the lowest severity any subscriber wants; `null` tells the child to stop forwarding. */
   | { type: "log.level"; minSev: number | null }
   | { type: "shutdown"; signal?: string }
+  /** Desktop server → the shell that started it: the path behind a file picker grant (forServer). */
+  | { type: "file.resolve"; id: string; grant: string }
+  | { type: "file.resolved"; id: string; path?: string; mode?: "read" | "write" | "folder"; error?: string }
   | { type: "error"; message: string; stack?: string; pid?: number };
 
 export const sendAkanIpc = (message: AkanIpcMessage) => {

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>();