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

package/signal/signalContext.ts

@@ -19,10 +19,10 @@ import {
 import type { Adaptor, AdaptorCls, DatabaseService, InjectRegistry, LiveRegistry } from "akanjs/service";
 import type { Internal, InternalCls, InternalInfo, MiddlewareCls } from ".";
 import { CrossSiteGuard } from "./CrossSiteGuard";
-import type { EndpointInfo, EndpointType } from "./endpointInfo";
+import { EndpointCache } from "./endpointCache";
+import type { ArgInfo, EndpointInfo, EndpointType } from "./endpointInfo";
 import { Exception, isExceptionLike } from "./exception";
 import { type GuardCls, guardOf } from "./guard";
-
 import { SignalFailure } from "./SignalFailure";
 import { getCurrentTrace, runTraced, SignalTrace, type TraceOrigin, traceSpan } from "./trace";
 
@@ -33,6 +33,9 @@ export type HttpPeerResolver = (req: Request) => { address: string; port: number
 
 const httpEndpointTypes = new Set<EndpointType>(["query", "mutation"]);
 
+const deserializeArg = (arg: ArgInfo, value: unknown) =>
+  deserialize(arg.argRef, arg.arrDepth, value, { key: arg.name, nullable: arg.option?.nullable, enum: arg.enum });
+
 interface WebSocketRequest {
   ws: Bun.ServerWebSocket<unknown>;
   data: unknown[];
@@ -40,10 +43,7 @@ interface WebSocketRequest {
 }
 type RuntimeRecord = Record<string, unknown>;
 type MiddlewareHandler = (context: SignalContext, next: () => Promise<unknown>) => PromiseOrObject<unknown>;
-/**
- * Every relation subtree one response has resolved, by model class and then document id. Request-scoped: the
- * outermost `resolveReturn` starts it and every recursion threads it down, so nothing survives the response.
- */
+/** Request-scoped: the outermost `resolveReturn` starts one and every recursion threads it down. */
 type ResolveCache = Map<ConstantFieldTypeInput, Map<string, Promise<unknown>>>;
 
 export class SignalContext<
@@ -55,11 +55,7 @@ export class SignalContext<
   ctx: Ctx;
   endpointInfo: EndpointInfo;
   adaptor: Adaptor;
-  /**
-   * Which surface the call came in on. The transport for a plain request, `mcp` for one an agent made through the
-   * MCP endpoint. Held on the context rather than read off the trace: `SignalTrace.create` may answer `null`, and a
-   * guard that asked the trace whether a model is driving the call would fail open exactly there.
-   */
+  /** `mcp` for a call through the MCP endpoint. Held here, not on the trace: a null trace would let a guard fail open. */
   readonly origin: TraceOrigin;
   args: unknown[] = [];
   internalArgs: unknown[] = [];
@@ -88,13 +84,9 @@ export class SignalContext<
       env: Env;
       live: LiveRegistry;
       middleware: Map<string, MiddlewareCls>;
-      /**
-       * Runs the endpoint against a caller-built context instead of one derived from the request. MCP needs it:
-       * its arguments arrive as one named object rather than in a URL, but every guard, middleware and
-       * internalArg reads the request through this context, so the transport has to stay the same one.
-       */
+      /** A caller-built context: MCP's arguments arrive as one named object, not in a URL. */
       ctx?: Ctx;
-      /** Who is calling, for the log record; defaults to the transport, and MCP names itself. */
+      /** Defaults to the transport. */
       origin?: TraceOrigin;
     },
   ) {
@@ -110,7 +102,7 @@ export class SignalContext<
     this.#env = env;
     this.#live = live;
     this.#middleware = middleware;
-
+    
     this.trace = getCurrentTrace() ?? SignalTrace.create(key, endpointInfo.type, origin ?? this.transport);
     if (this.trace && this.transport === "http")
       this.trace.applyDebugHeader((reqOrWsReq as { headers?: Headers }).headers?.get?.("x-akan-debug"));
@@ -134,31 +126,19 @@ export class SignalContext<
       const httpCtx = this.getHttpContext();
       CrossSiteGuard.assertOrigin(httpCtx.req, httpCtx.url, this.key);
     }
-    if (this.trace) {
-      const start = performance.now();
-      this.args = await this.ctx.getArgs(this.endpointInfo);
-      this.trace.recordSpan("argParse", performance.now() - start);
-    } else {
-      this.args = await this.ctx.getArgs(this.endpointInfo);
-    }
+    const start = this.trace ? performance.now() : 0;
+    this.args = await this.ctx.getArgs(this.endpointInfo);
+    this.trace?.recordSpan("argParse", performance.now() - start);
     return this;
   }
-  /**
-   * In declaration order, not in parallel. Every guard has to pass either way, so the only thing concurrency
-   * bought was that a call refused by two of them named whichever lost the race — a log line that changed
-   * between identical requests. Sequential also stops at the first refusal instead of running the rest.
-   */
+  
   async #checkGuards() {
     for (const GuardCls of this.endpointInfo.signalOption.guards ?? []) {
       if (!(await guardOf(GuardCls).canPass(this)))
         throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
     }
   }
-  /**
-   * Re-checks this context's guards outside of a request, for a websocket room that is already
-   * subscribed. Only global middlewares run: they carry the account resolution this depends on,
-   * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
-   */
+  /** Re-checks the guards of a subscribed room outside a request; only global middlewares (account resolution) run. */
   async authorize(): Promise<boolean> {
     try {
       await this.#withMiddleware(async () => await this.#checkGuards(), { endpointMiddlewares: false })();
@@ -168,18 +148,14 @@ export class SignalContext<
     }
   }
   /**
-   * Evaluates only the guards marked `static scope = "account"` — the ones that read the caller and nothing
-   * else — so a catalogue can hide entries the caller certainly cannot use.
-   *
-   * **Never an access gate.** An endpoint whose guards are all resource-scoped passes here and is stopped later
-   * by `#checkGuards` with the arguments those guards need. Erring visible is deliberate: a resource guard fails
-   * closed with no arguments, so evaluating one here would delete every legitimate entry from the listing.
+   * Evaluates only `scope = "account"` guards, to hide listing entries. Never an access gate: a resource guard fails
+   * closed without arguments, so it is left to `#checkGuards` at call time.
    */
   async canListForAccount(): Promise<boolean> {
     const guards = (this.endpointInfo.signalOption.guards ?? []).filter((GuardCls) => GuardCls.scope === "account");
     if (guards.length === 0) return true;
     try {
-
+      
       await this.#withMiddleware(
         async () => {
           for (const GuardCls of guards) {
@@ -194,11 +170,7 @@ export class SignalContext<
       return false;
     }
   }
-  /**
-   * An account guard has no arguments here, so one that throws anything but a refusal reached for them anyway —
-   * a resource guard mismarked. The entry stays hidden (fail-closed), but the guard is named once per endpoint,
-   * because otherwise the only trace is a tool that is missing for everyone.
-   */
+  
   async #canListWith(GuardCls: GuardCls): Promise<boolean> {
     try {
       return await guardOf(GuardCls).canPass(this);
@@ -236,21 +208,12 @@ export class SignalContext<
     }
     return next;
   }
-  /**
-   * `use(env)` takes no context, so the instance and the handler it returns are a function of `(class, env)` and
-   * hold for the life of the process. Building both per request cost an instance, a handler and a closure on every
-   * call for every registered middleware — and `Logging` is registered by default.
-   */
   static #httpPeer: HttpPeerResolver | null = null;
-  /**
-   * Lets the http branch of `getClientIp` reach the socket the way the websocket branch already reaches
-   * `ws.remoteAddress`. Registered by whichever `Bun.serve` is listening, because only the server can answer
-   * `requestIP`. Behind the federation gateway this never fires — the gateway always writes `x-real-ip` —
-   * so it is the answer for a process nothing is proxying.
-   */
+  /** Registered by the listening `Bun.serve`, the only thing that can answer `requestIP`; unused behind the gateway. */
   static setHttpPeerResolver(resolve: HttpPeerResolver | null) {
     SignalContext.#httpPeer = resolve;
   }
+  
   static #middlewareHandlers = new WeakMap<MiddlewareCls, WeakMap<object, Promise<MiddlewareHandler>>>();
   static #getMiddlewareHandler(MiddlewareCls: MiddlewareCls, env: BackendEnv): Promise<MiddlewareHandler> {
     const byEnv =
@@ -258,7 +221,7 @@ export class SignalContext<
     SignalContext.#middlewareHandlers.set(MiddlewareCls, byEnv);
     const cached = byEnv.get(env);
     if (cached) return cached;
-
+    
     const handler = Promise.resolve(new MiddlewareCls().use(env) as PromiseOrObject<MiddlewareHandler>).catch(
       (error: unknown) => {
         byEnv.delete(env);
@@ -291,46 +254,44 @@ export class SignalContext<
           }),
         );
       }
-      if (!this.trace) return await this.endpointInfo.execFn.call(this.adaptor, ...this.args, ...this.internalArgs);
-      return await traceSpan(
-        "handler",
-        async () => await this.endpointInfo.execFn?.call(this.adaptor, ...this.args, ...this.internalArgs),
-      );
+      const handle = async () => await this.endpointInfo.execFn?.call(this.adaptor, ...this.args, ...this.internalArgs);
+      return await EndpointCache.through(this, this.trace ? () => traceSpan("handler", handle) : handle);
     };
     const next = this.#withMiddleware(coreExec);
     const result = this.trace ? await traceSpan("execChain", () => next()) : await next();
-
+    
     if (this.endpointInfo.type === "pubsub") return result;
     if (result instanceof Response) return result;
+    const resolveOption = {
+      signalContext: this,
+      returnRef: this.endpointInfo.returns.returnRef,
+      arrDepth: this.endpointInfo.returns.arrDepth,
+      registry: this.#registry,
+      live: this.#live,
+    };
     if (!this.trace) {
-      const resolved = await SignalContext.resolveReturn(result, {
-        signalContext: this,
-        returnRef: this.endpointInfo.returns.returnRef,
-        arrDepth: this.endpointInfo.returns.arrDepth,
-        registry: this.#registry,
-        live: this.#live,
-      });
-      return this.ctx.makeResponse(resolved, this.endpointInfo);
+      const resolved = await SignalContext.resolveReturn(result, resolveOption);
+      return this.ctx.makeResponse(this.#settleUndefined(resolved), this.endpointInfo);
     }
-    const resolved = await traceSpan("resolveReturn", () =>
-      SignalContext.resolveReturn(result, {
-        signalContext: this,
-        returnRef: this.endpointInfo.returns.returnRef,
-        arrDepth: this.endpointInfo.returns.arrDepth,
-        registry: this.#registry,
-        live: this.#live,
-      }),
+    const resolved = await traceSpan("resolveReturn", () => SignalContext.resolveReturn(result, resolveOption));
+    return await traceSpan("serialize", async () =>
+      this.ctx.makeResponse(this.#settleUndefined(resolved), this.endpointInfo),
+    );
+  }
+
+  #settleUndefined(resolved: unknown) {
+    if (resolved !== undefined) return resolved;
+    const { nullable, returnRef } = this.endpointInfo.returns;
+    if (nullable || returnRef === Any) return null;
+    throw new Error(
+      `${this.endpointInfo.type} ${this.key} returned undefined, but its return is not nullable: return a value, or declare { nullable: true } and return null`,
     );
-    return await traceSpan("serialize", async () => this.ctx.makeResponse(resolved, this.endpointInfo));
   }
   /** Whether `run` already logged this failure, so a transport's catch does not log it a second time. */
   static wasReported(error: unknown) {
     return typeof error === "object" && error !== null && SignalContext.#reported.has(error);
   }
-  /**
-   * Runs `fn` as one traced call of `key`, so every log it writes — the 500 log included, which is why the
-   * catch is in here and not in the transport — carries the same traceId. Rethrows after logging.
-   */
+  /** The 500 log is written in here, not in the transport, so it carries the call's traceId; rethrows after. */
   static async run<T>(
     endpoint: Adaptor,
     endpointInfo: EndpointInfo,
@@ -392,7 +353,6 @@ export class SignalContext<
       arrDepth: number;
       registry: InjectRegistry;
       live: LiveRegistry;
-      /** Omitted by the outermost call, which starts an empty one; every recursion threads it down. */
       cache?: ResolveCache;
     },
   ): Promise<unknown> {
@@ -406,7 +366,7 @@ export class SignalContext<
       );
     const valueRecord = value as RuntimeRecord;
     const resolvedValue = {} as RuntimeRecord;
-
+    
     const pending: Promise<void>[] = [];
     const assign = (key: string, resolved: Promise<unknown>) =>
       pending.push(
@@ -536,7 +496,7 @@ export class SignalContext<
     const refName = ConstantRegistry.getRefName(modelRef as ConstantCls);
     const service = live.service.get(refName) as unknown as DatabaseService;
     if (!service) throw new Error(`Service ${refName} is not registered`);
-
+    
     const resolved =
       value === null || value === undefined
         ? null
@@ -554,13 +514,7 @@ export class SignalContext<
     if (resolved === null && !nullable) throw new Error(`Document ${value} is not found`);
     return resolved;
   }
-  /**
-   * The resolved subtree for one document, computed once per response.
-   *
-   * A listing whose rows share a relation — twenty users with the same avatar — otherwise loads, `toJSON`s and
-   * walks that document once per row, and every copy is identical by construction. The promise is what is
-   * stored, not the value, so rows that ask together coalesce onto the first load instead of racing it.
-   */
+  
   static #resolveOnce(
     cache: ResolveCache,
     modelRef: ConstantFieldTypeInput,
@@ -586,27 +540,22 @@ export class SignalContext<
     }
     if (arrDepth > 0 && Array.isArray(value) && value.length === 0) return [];
     if (arrDepth === 0)
-      return await service.__load(String(value)).then((doc) => {
-        if (doc === null) {
-          if (nullable) return null;
-          else throw new Error(`Document ${value} is not found`);
-        } else return doc.toJSON();
-      });
+      return await service.__load(String(value)).then((doc) => SignalContext.#loadedJson(doc, value, nullable));
     if (arrDepth === 1)
-      return await service.__loadMany(value as string[]).then((docs) =>
-        docs.map((doc) => {
-          if (doc === null) {
-            if (nullable) return null;
-            else throw new Error(`Document ${value} is not found`);
-          } else return doc.toJSON();
-        }),
-      );
+      return await service
+        .__loadMany(value as string[])
+        .then((docs) => docs.map((doc) => SignalContext.#loadedJson(doc, value, nullable)));
     return await Promise.all(
       (value as unknown[]).map(
         async (v) => await SignalContext.loadNested(v, service, { arrDepth: arrDepth - 1, nullable }),
       ),
     );
   }
+  static #loadedJson(doc: { toJSON: () => unknown } | null, value: unknown, nullable: boolean) {
+    if (doc !== null) return doc.toJSON();
+    if (nullable) return null;
+    throw new Error(`Document ${value} is not found`);
+  }
   getHttpContext<Appended = unknown>() {
     if (this.transport !== "http") throw new Error("Transport is not http");
     return this.ctx as HttpExecutionContext<Appended>;
@@ -620,18 +569,13 @@ export class SignalContext<
     return this.getWebSocketContext<{ [key: string]: T }>().ws.data[key] ?? null;
   }
   /**
-   * The caller's IP, preferring what a proxy recorded over the socket peer. Behind the federation gateway the
-   * peer is the gateway itself for every request and for the whole life of every socket, so `remoteAddress`
-   * alone names the wrong machine — which is why nothing here reads it first. IPv4 arrives unwrapped from its
-   * `::ffff:` form, so it can be used as a destination as well as an identity.
-   *
-   * `null` means no proxy recorded one and the transport has no peer to fall back on — never a placeholder,
-   * because a loopback-looking address for an unknown caller is the failure this replaced.
+   * What a proxy recorded before the socket peer (behind the gateway every peer is the gateway), IPv4 unwrapped from
+   * `::ffff:`; `null`, never a placeholder, when neither is known.
    */
   getClientIp(): string | null {
     if (this.transport === "http") {
       const { req } = this.getHttpContext();
-
+      
       const peer = SignalContext.#httpPeer?.(req);
       return TrustedProxy.clientAddress(req.headers, peer === undefined ? undefined : (peer?.address ?? null));
     }
@@ -654,16 +598,8 @@ export class SignalContext<
     return `${key}${this.args.length ? "-" : ""}${this.args.join("-")}`;
   }
   /**
-   * A live room's id, which appends the caller's resolved internal arguments to the client-visible one.
-   *
-   * Without them every subscriber of an `inSelf` slice shares one room and receives each other's rows. It cannot
-   * be done for pubsub in general: an ordinary room's publisher computes the same id from the arguments it
-   * publishes with and has no access to a subscriber's `Self`, so widening the id there would put subscriber and
-   * publisher in different rooms. A live room's only publisher is the router, which holds this id already.
-   *
-   * The token is the argument's own id where it has one — that is what `Self` yields, and a room name never
-   * leaves the server — and a digest otherwise, so a credential handed in as an internal argument is not spelled
-   * out in a room name that gets logged.
+   * Appends the caller's internal arguments so subscribers of an `inSelf` slice do not share a room — only for live
+   * rooms, whose sole publisher holds this id. A non-id token is digested so no credential is spelled out in a log.
    */
   getLiveRoomId(key: string) {
     const base = this.getRoomId(key);
@@ -689,13 +625,7 @@ export class SignalContext<
     }
     return hash.toString(36);
   }
-  /**
-   * Resolves the declared internal arguments without running guards or the handler.
-   *
-   * An unsubscribe has to name the same room the subscribe joined, and that id depends on these — but there is
-   * nothing to authorize about leaving a room, and re-running the handler to compute a name would issue the
-   * slice's query again for nothing.
-   */
+  /** Without guards or the handler: an unsubscribe needs the room id, and leaving a room authorizes nothing. */
   async resolveInternalArgs() {
     if (this.internalArgs.length || !this.endpointInfo.internalArgs.length) return this.internalArgs;
     this.internalArgs = await Promise.all(
@@ -767,26 +697,14 @@ export class HttpExecutionContext<Appended = unknown> {
     const args = endpointInfo.args.map((arg) => {
       switch (arg.type) {
         case "param":
-          return deserialize(arg.argRef, arg.arrDepth, this.params[arg.name], {
-            key: arg.name,
-            nullable: arg.option?.nullable,
-            enum: arg.enum,
-          });
+          return deserializeArg(arg, this.params[arg.name]);
         case "body":
           if (arg.argRef === Upload) return this.body[arg.name];
-          return deserialize(arg.argRef, arg.arrDepth, this.body[arg.name], {
-            key: arg.name,
-            nullable: arg.option?.nullable,
-            enum: arg.enum,
-          });
+          return deserializeArg(arg, this.body[arg.name]);
         case "search": {
           const raw = arg.arrDepth ? this.url.searchParams.getAll(arg.name) : this.url.searchParams.get(arg.name);
           const value = arg.argRef === Any ? HttpExecutionContext.#parseAny(arg.name, raw) : raw;
-          const result = deserialize(arg.argRef, arg.arrDepth, value, {
-            key: arg.name,
-            nullable: arg.option?.nullable,
-            enum: arg.enum,
-          });
+          const result = deserializeArg(arg, value);
           this.searchParams[arg.name] = result;
           return result;
         }
@@ -825,17 +743,8 @@ export class WebSocketExecutionContext<Appended = unknown> {
     const args = endpointInfo.args.map((arg, idx) => {
       switch (arg.type) {
         case "msg":
-          return deserialize(arg.argRef, arg.arrDepth, this.data[idx], {
-            key: arg.name,
-            nullable: arg.option?.nullable,
-            enum: arg.enum,
-          });
         case "room":
-          return deserialize(arg.argRef, arg.arrDepth, this.data[idx], {
-            key: arg.name,
-            nullable: arg.option?.nullable,
-            enum: arg.enum,
-          });
+          return deserializeArg(arg, this.data[idx]);
         default:
           return undefined;
       }
@@ -847,7 +756,7 @@ export class WebSocketExecutionContext<Appended = unknown> {
       nullable: endpointInfo.returns.nullable,
     }) as unknown as Response;
   }
-
+  
   on = (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => {
     if (event === "disconnect") this.onDisconnect.add(handler);
     else this.onUnsubscribe.add(handler);

package/signal/signalRegistry.ts

@@ -23,17 +23,14 @@ export class DatabaseSignal<
   SlceCls extends SliceCls = SliceCls,
   SrvrCls extends ServerSignalCls = ServerSignalCls,
 > {
-  internal: IntlCls;
-  endpoint: EndpCls;
-  slice: SlceCls;
-  server: SrvrCls;
   serializedSignal: SerializedSignal;
 
-  constructor(internal: IntlCls, endpoint: EndpCls, slice: SlceCls, server: SrvrCls) {
-    this.internal = internal;
-    this.endpoint = endpoint;
-    this.slice = slice;
-    this.server = server;
+  constructor(
+    public internal: IntlCls,
+    public endpoint: EndpCls,
+    public slice: SlceCls,
+    public server: SrvrCls,
+  ) {
     this.serializedSignal = FetchSerializer.serializeDatabaseSignal(slice, endpoint);
   }
 }
@@ -43,20 +40,17 @@ export class ServiceSignal<
   EndpCls extends EndpointCls = EndpointCls,
   SrvrCls extends ServerSignalCls = ServerSignalCls,
 > {
-  internal: IntlCls;
-  endpoint: EndpCls;
-  server: SrvrCls;
   serializedSignal: SerializedSignal;
 
-  constructor(internal: IntlCls, endpoint: EndpCls, server: SrvrCls) {
-    this.internal = internal;
-    this.endpoint = endpoint;
-    this.server = server;
+  constructor(
+    public internal: IntlCls,
+    public endpoint: EndpCls,
+    public server: SrvrCls,
+  ) {
     this.serializedSignal = FetchSerializer.serializeServiceSignal(endpoint);
   }
 }
 
-/** Registry for database and service signals used by routing and fetch serialization. */
 export class SignalRegistry {
   static readonly #database = new Map<string, DatabaseSignal<InternalCls, EndpointCls, SliceCls, ServerSignalCls>>();
   static readonly #service = new Map<string, ServiceSignal<InternalCls, EndpointCls, ServerSignalCls>>();

package/signal/slice.ts

@@ -41,7 +41,7 @@ export type SliceCls<
   mcp: ResolvedSliceMcp;
 };
 
-/** The generated verbs, resolved to a plain answer each. `root` is not here: it rides on the root slice itself. */
+/** `root` is absent: it rides on the root slice itself. */
 export interface ResolvedSliceMcp {
   get: boolean;
   create: boolean;
@@ -59,13 +59,8 @@ interface RootSliceOption {
     remove?: GuardCls | GuardCls[];
   };
   /**
-   * Which of the entries this call generates belong on an agent's shelf. Keyed exactly like `guards` above and
-   * scoped to exactly what `guards` governs — the root slice and the generated CRUD — so `false` here narrows the
-   * catalogue and nothing else. `create`/`update`/`remove` fall back to `cru` the same way their guards do, and
-   * the bare `false` is every key at once.
-   *
-   * A named slice and a custom endpoint declare their own `mcp` in their own signal option, exactly as they
-   * declare their own guards. This is curation, not authorization: HTTP is unchanged.
+   * Keyed like `guards`, for the root slice and generated CRUD only; `create`/`update`/`remove` fall back to `cru`
+   * and a bare boolean sets every key. Curation, not authorization: HTTP is unchanged.
    */
   mcp?:
     | boolean
@@ -102,7 +97,6 @@ type ExtendSliceInfoObj<
     : never;
 };
 
-/** Builds database-backed slice APIs for list, insight, init, view, edit, create, update, and remove flows. */
 export function slice<
   SrvModule extends ServiceModel,
   BuildSlice extends SliceBuilder<SrvModule>,
@@ -148,7 +142,7 @@ export function slice<
   const rootGuards = toGuards(option.guards?.root);
   const getGuards = toGuards(option.guards?.get);
   const cruGuards = toGuards(option.guards?.cru);
-
+  
   const createGuards = option.guards?.create ? toGuards(option.guards.create) : cruGuards;
   const updateGuards = option.guards?.update ? toGuards(option.guards.update) : cruGuards;
   const removeGuards = option.guards?.remove ? toGuards(option.guards.remove) : cruGuards;
@@ -177,7 +171,7 @@ export function slice<
     static mcp = mcp;
     static [SLICE_META] = Object.assign(
       {
-
+        
         [""]: init({ guards: rootGuards, ...(mcpOption?.root === false ? { mcp: false } : {}) })
           .search<"queryKey", string>("queryKey", String)
           .search<"args", unknown[]>("args", Any)
@@ -185,7 +179,7 @@ export function slice<
             try {
               return resolveFilterQuery(filterRef, queryKey, args);
             } catch (error) {
-
+              
               if (error instanceof FilterQueryError) throw new Exception.BadRequest(error.message);
               throw error;
             }

package/signal/sliceInfo.ts

@@ -23,42 +23,17 @@ import {
 import type { InternalArgCls } from "./internalArg";
 import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SignalOption, SrvMap, SrvRefName } from "./types";
 
-/**
- * What a slice declares when it opts into live sync. Nothing here is required — `.live()` on its own is the whole
- * opt-in, and every default below is the conservative reading.
- */
 export interface LiveSliceOption<ArgName extends string = string> {
   /**
-   * The sort keys a client may reproduce well enough to place a row itself. Anything else falls back to a refetch,
-   * because the client would otherwise have to guess where a new row goes.
-   *
-   * `latest` is `{ createdAt: -1 }` on a real column, which a client compares identically. A key that sorts on a
-   * field inside `_doc` is checked at boot and warned about: SQLite orders those by SQL value and Postgres by
-   * jsonb type, so the two servers do not even agree with each other.
+   * Keys a client may place a new row under itself (default `["latest"]`); any other sort refetches. A key on a
+   * `_doc` field is warned about at boot: SQLite orders it by SQL value and Postgres by jsonb type.
    */
   sort?: string[];
-  /**
-   * Downgrades this slice to invalidation only: subscribers are told their list moved and refetch, and no
-   * membership is evaluated. Required for a query holding `q.raw()`, `q.search()`, or `exists`/`missing` on a
-   * `_doc` field, none of which can be answered without the database.
-   */
+  /** Invalidation only: subscribers refetch. Required for `q.raw()`, `q.search()` or `exists`/`missing` on `_doc`. */
   fallback?: "invalidate";
   /** `light` sends the row and costs nothing to apply; `id` sends the id alone for a room where the row is bulky. */
   payload?: "light" | "id";
-  /**
-   * The arguments that switch live sync off for as long as they carry a value, named for this slice.
-   *
-   * A filter often builds a different query shape depending on what it was handed — `search ? q.search(text) : {}`
-   * is the common one — so the same slice is routable blank and unroutable with text in the box. Naming the
-   * argument makes that explicit: the client opens no room while it is filled and the window updates by
-   * refetching, which is what a slice with no `.live()` at all does. Clearing it opens the room again.
-   *
-   * Only a nullable argument can be named, which in practice means a `search`: a `param` is always present, so
-   * naming one would switch live off for good. That is refused at boot rather than left to be discovered.
-   *
-   * This is not `fallback`. `fallback: "invalidate"` keeps the room and gives up precision — every write on the
-   * model tells the room to refetch. `pauseOn` gives up the room and keeps precision everywhere else.
-   */
+  /** Nullable arguments that close the room while they carry a value (the list refetches); a `param` is refused. */
   pauseOn?: ArgName[];
 }
 
@@ -136,6 +111,7 @@ export class SliceInfo<
       [...ServerArgs, arg: _ServerArg]
     >;
   }
+  /** @deprecated Slices are GET queries, which carry no body: `fetch` never sends this argument. Use `.search`. */
   body<
     ArgName extends string,
     ExplicitType = unknown,
@@ -208,7 +184,6 @@ export class SliceInfo<
       ServerArgs
     >;
   }
-  /** Opts this slice into live sync. Declaring nothing at all is what keeps a slice out of it entirely. */
   live(option: LiveSliceOption<ArgNames[number]> = {}) {
     if (this.execFn) throw new Error("Query function is already set");
     if (this.liveOption) throw new Error("Live option is already set");