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

package/types/signal/signalContext.d.ts

@@ -16,10 +16,7 @@ interface WebSocketRequest {
     eventType: WebSocketEventType;
 }
 type RuntimeRecord = Record<string, 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 declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketExecutionContext = HttpExecutionContext | WebSocketExecutionContext, Env extends BackendEnv = BackendEnv> {
     #private;
@@ -28,11 +25,7 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     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[];
@@ -44,47 +37,27 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
         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;
     });
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
     init(): Promise<this>;
-    /**
-     * 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. */
     authorize(): Promise<boolean>;
     /**
-     * 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.
      */
     canListForAccount(): Promise<boolean>;
-    /**
-     * 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): void;
     exec(): Promise<unknown>;
     /** Whether `run` already logged this failure, so a transport's catch does not log it a second time. */
     static wasReported(error: unknown): boolean;
-    /**
-     * 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 run<T>(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, origin: TraceOrigin, fn: () => Promise<T>, { trace }?: {
         trace?: boolean;
     }): Promise<T>;
@@ -97,7 +70,6 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
         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>;
     static loadNested(value: unknown, service: DatabaseService, { arrDepth, nullable }: {
@@ -108,38 +80,19 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getWebSocketContext<Appended = unknown>(): WebSocketExecutionContext<Appended>;
     get<T = unknown>(key: string): T | 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;
     /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
     getClientPort(): number | null;
     getRoomId(key: string): string;
     /**
-     * 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): string;
-    /**
-     * 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. */
     resolveInternalArgs(): Promise<unknown[]>;
     getEnv(): Env;
     getArg<T = unknown>(argName: string): T | undefined;

package/types/signal/signalRegistry.d.ts

@@ -26,7 +26,6 @@ export declare class ServiceSignal<IntlCls extends InternalCls = InternalCls, En
     serializedSignal: SerializedSignal;
     constructor(internal: IntlCls, endpoint: EndpCls, server: SrvrCls);
 }
-/** Registry for database and service signals used by routing and fetch serialization. */
 export declare class SignalRegistry {
     #private;
     static registerDatabase<RefName extends string, IntlCls extends InternalCls, EndpCls extends EndpointCls, SlceCls extends SliceCls, SrvrCls extends ServerSignalCls>(refName: RefName, internal: SignalWithBase<RefName, IntlCls>, endpoint: SignalWithBase<RefName, EndpCls>, slice: SignalWithBase<RefName, SlceCls>, server: SrvrCls): DatabaseSignal<IntlCls, EndpCls, SlceCls, SrvrCls>;

package/types/signal/slice.d.ts

@@ -31,7 +31,7 @@ export type SliceCls<SrvModule extends ServiceModel = ServiceModel, SliceInfoObj
     removeGuards: GuardCls[];
     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;
@@ -48,13 +48,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 | {
         root?: boolean;
@@ -70,7 +65,6 @@ type RootSliceQueryKey<Filter extends FilterInstance> = Extract<keyof Filter["qu
 type ExtendSliceInfoObj<SrvModule extends ServiceModel, LibSlices extends SliceCls[], _Input = CnstInput<SrvModule>, _Full = CnstFull<SrvModule>, _Light = CnstLight<SrvModule>, _Insight = CnstInsight<SrvModule>, _Filter extends FilterInstance = DbFilter<SrvModule>, _Merged = MergeAllKeyOfObjects<LibSlices, typeof SLICE_META>> = {
     [K in keyof _Merged]: _Merged[K] extends SliceInfo ? SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SliceInfoSrvs<_Merged[K]>, SliceInfoArgNames<_Merged[K]>, SliceInfoArgs<_Merged[K]>, SliceInfoInternalArgs<_Merged[K]>, SliceInfoServerArgs<_Merged[K]>> : never;
 };
-/** Builds database-backed slice APIs for list, insight, init, view, edit, create, update, and remove flows. */
 export declare function slice<SrvModule extends ServiceModel, BuildSlice extends SliceBuilder<SrvModule>, LibSlices extends SliceCls[], _Input = CnstInput<SrvModule>, _Full = CnstFull<SrvModule>, _Light = CnstLight<SrvModule>, _Insight = CnstInsight<SrvModule>, _Filter extends FilterInstance = DbFilter<SrvModule>, _QueryKey extends string = RootSliceQueryKey<_Filter>>(srv: SrvModule, option: RootSliceOption, sliceBuilder: BuildSlice, ...libSlices: LibSlices): SliceCls<SrvModule, Assign<ReturnType<BuildSlice>, LibSlices extends [] ? {
     [""]: SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SrvMap<SrvModule>, [
         "queryKey",

package/types/signal/sliceInfo.d.ts

@@ -5,42 +5,17 @@ import type { ServiceModel } from "akanjs/service";
 import { type ArgInfo, type EndpointArgProps, type InternalArgInfo, type InternalArgProps } from "./endpointInfo.d.ts";
 import type { InternalArgCls } from "./internalArg.d.ts";
 import type { CnstFull, CnstInput, CnstInsight, CnstLight, DbFilter, SignalOption, SrvMap, SrvRefName } from "./types.d.ts";
-/**
- * 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[];
 }
 export interface ResolvedLiveSliceOption {
@@ -68,10 +43,10 @@ export declare class SliceInfo<RefName extends string = string, Input = any, Ful
     execFn: ((...args: [...ServerArgs, ...InternalArgs]) => QueryOf<DocumentModel<Full>>) | null;
     constructor(refName: RefName, input: Cls<Input>, full: Cls<Full>, light: Cls<Light>, insight: Cls<Insight>, filter: FilterCls<Filter>, signalOption?: SignalOption);
     param<ArgName extends string, Arg extends ParamFieldType, _ClientArg = FieldToValue<Arg>, _ServerArg = DocumentModel<_ClientArg>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...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, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)]>;
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined]>;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], 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]>): this;
     exec(query: (this: {
         [K in keyof Srvs as K extends string ? Uncapitalize<K> : never]: Srvs[K];

package/types/signal/trace.d.ts

@@ -1,7 +1,5 @@
 import { type LogAttrs, type LogFlightRecorder } from "akanjs/common";
-/** Whether full request tracing (`AKAN_TRACE=1`) is enabled. Cached after first read. */
 export declare const isTraceEnabled: () => boolean;
-/** Override the trace flag at runtime (tests / harness control). */
 export declare const setTraceEnabled: (enabled: boolean) => void;
 export declare const isLogContextEnabled: () => boolean;
 export declare const setLogContextEnabled: (enabled: boolean) => void;
@@ -14,11 +12,6 @@ export declare const setFlightRecorderEnabled: (enabled: boolean) => void;
 /** `AKAN_LOG_FLIGHT_MS`: a call at least this long is "slow" for both the recorder and the `slow` canonical mode. */
 export declare const getFlightThresholdMs: () => number;
 export declare const setFlightThresholdMs: (ms: number) => void;
-/**
- * `x-akan-debug` lowers one request's log floor to `trace`. Honoured in `local` unconditionally, and elsewhere only
- * when the header carries the value of `AKAN_LOG_DEBUG_HEADER`: a client that can lower a server's log level is a
- * log-volume vector, so outside development it has to prove it was told the secret.
- */
 export declare const isDebugHeaderAllowed: () => boolean;
 export interface SpanRecord {
     name: string;
@@ -27,7 +20,6 @@ export interface SpanRecord {
 export type TraceMode = "context" | "full";
 export type TraceOrigin = "http" | "websocket" | "mcp" | "internal" | "page";
 export type TraceOutcome = "ok" | "error";
-/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
 export declare class SignalTrace {
     #private;
     /** Total captured records the process holds at once (`AKAN_LOG_FLIGHT_MAX`); a call past it runs unrecorded. */
@@ -39,7 +31,6 @@ export declare class SignalTrace {
     readonly mode: TraceMode;
     readonly startedAt: number;
     readonly spans: SpanRecord[];
-    /** What the canonical line carries beyond timing — `userId` once the caller is known. */
     readonly attrs: LogAttrs;
     dbQueryCount: number;
     dbQueryMs: number;
@@ -56,11 +47,10 @@ export declare class SignalTrace {
         mode?: TraceMode;
         origin?: TraceOrigin;
     });
-    /** The trace a call runs under given what is switched on, or `null` when both modes are off. */
+    /** `null` when both modes are off. */
     static create(endpointKey: string, endpointType: string, origin: TraceOrigin): SignalTrace | null;
     static get activeFlights(): number;
     get endpoint(): string;
-    /** Attaches the ring unless the process is already holding its cap; a trace past the cap simply is not recorded. */
     startFlightRecorder(): boolean;
     /** Honours `x-akan-debug` for this call when the deployment allows it; anything else is ignored, not refused. */
     applyDebugHeader(value: string | null | undefined): boolean;
@@ -73,34 +63,17 @@ export declare class SignalTrace {
     finalize(): void;
 }
 export declare const getCurrentTrace: () => SignalTrace | undefined;
-/** Run `fn` with `trace` as the ambient request trace. */
 export declare const runWithTrace: <T>(trace: SignalTrace, fn: () => T) => T;
-/**
- * Run `fn` as the whole life of `trace`: a throw marks the outcome before it propagates, and the trace is
- * finalized after the caller's own catch has run — which is what lets an error log carry the traceId.
- */
+/** Finalizes `trace` after the caller's own catch has run, which is what lets an error log carry the traceId. */
 export declare const runTraced: <T>(trace: SignalTrace | null, fn: () => Promise<T>) => Promise<T>;
-/**
- * Time an async stage under the current trace. When tracing is off (or no trace is
- * active) this is a thin passthrough with no measurement overhead.
- */
 export declare const traceSpan: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
-/** Record a DB query duration against the current trace (no-op when untraced). */
 export declare const traceDbQuery: (durationMs: number) => void;
-/** Record a cache hit/miss against the current trace (no-op when untraced). */
 export declare const traceCache: (hit: boolean) => void;
-/** Record a DataLoader batch against the current trace (no-op when untraced). */
 export declare const traceDataLoaderBatch: (keyCount: number) => void;
-/**
- * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
- * bounded sample ring per span so percentiles stay representative of steady state
- * without unbounded memory growth.
- */
 declare class TraceAggregator {
     #private;
     ingest(trace: SignalTrace): void;
     reset(): void;
-    /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
     snapshot(): {
         enabled: boolean;
         endpoints: {
@@ -123,7 +96,6 @@ declare class TraceAggregator {
     };
 }
 export declare const traceAggregator: TraceAggregator;
-/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
 export declare const getTraceSnapshot: () => {
     enabled: boolean;
     endpoints: {

package/types/signal/types.d.ts

@@ -46,6 +46,8 @@ interface InitOption {
     serverMode?: "federation" | "batch" | "all";
     operationMode?: ("cloud" | "edge" | "local" | (string & {}))[];
     enabled?: boolean;
+    /** Instances booting together take turns and one that waited skips its own run; unset, every instance runs it. */
+    once?: boolean;
 }
 interface TimerOption {
     serverMode?: "federation" | "batch" | "all";
@@ -69,42 +71,32 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     default?: boolean;
     path?: string;
     serverMode?: "federation" | "batch" | "all";
+    /**
+     * Milliseconds; the server rejects with `base.error.gatewayTimeout` and the client sizes its request budget from
+     * it. Losing the race does not stop the handler, which runs to completion with nobody holding its result.
+     */
     timeout?: number;
     partial?: _Key[] | readonly _Key[];
+    /**
+     * Milliseconds to reuse the answer, keyed by endpoint and arguments; unset caches nothing. Only a `query` with no
+     * internal argument may carry one (those answer per caller), and the lookup runs after the guards.
+     */
     cache?: number;
     guards?: GuardCls[];
     middlewares?: MiddlewareCls[];
     prefix?: false | string;
     globalPrefix?: false;
-    /**
-     * HTTP verb for a `mutation`, `POST` unless named. Only a foreign wire protocol needs the others — a client
-     * that cannot be changed and sends `PATCH /rest/v1/<table>`. Every other endpoint type ignores it.
-     */
+    /** HTTP verb of a `mutation`, `POST` unless named; every other endpoint type ignores it. */
     method?: HttpMutationMethod;
-    /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
     fileUpload?: boolean;
-    /**
-     * Whether this endpoint belongs on an agent's shelf. `true` — the default — publishes it to MCP subject to the
-     * guard and shape rules; `false` keeps it out of the catalogue entirely.
-     *
-     * This is curation, not authorization: HTTP serves the endpoint exactly as before, and the guards are still the
-     * only thing deciding who may call it. Write it where an endpoint is perfectly guarded and still has no business
-     * on a shelf — a step of a UI-driven state machine (`requestPhoneCodeForSignin`), or a read a model would only
-     * ever call by mistake. Every catalogue entry carries the model schemas it mentions, so one endpoint dropped
-     * here is kilobytes off every `tools/list`.
-     */
+    /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
     mcp?: boolean;
     /**
-     * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
-     * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
-     * newer one exists. Name `"queue"` when the frames are a sequence a subscriber has to see in full, such as
-     * deltas against a base it already holds; the send buffer then grows with the slowest subscriber.
+     * A slow subscriber of a `pubsub(Binary)`: `"coalesce"` (default) keeps only the newest frame per room, `"queue"`
+     * delivers every frame and grows the send buffer with the slowest subscriber.
      */
     backpressure?: "coalesce" | "queue";
-    /**
-     * Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. It carries what
-     * the room needs to route a change — which model, and how the slice asked to be treated.
-     */
+    /** Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. */
     live?: LiveEndpointOption;
     scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
     scheduleCron?: string;
@@ -120,25 +112,13 @@ interface SerializedSignalOption {
     guards?: string[];
     method?: HttpMutationMethod;
     fileUpload?: boolean;
-    /**
-     * Only ever `false`, and only when something declared it: `true` is the default, so serializing it would ship a
-     * field per endpoint that says nothing. Resolved here rather than left to the reader because the browser API
-     * explorer has guard *names* and no classes, and a second implementation of the rule would eventually disagree
-     * with the catalogue.
-     */
+    /** Only ever `false`, when declared. Resolved here because the API explorer holds guard names, not classes. */
     mcp?: false;
-    /**
-     * Only ever `false`, and only when one of the guards declares `static agents = false`: a person-only act. Resolved
-     * here for the same reason `mcp` is — the reader holds guard names, not classes.
-     */
+    /** Only ever `false`, when a guard declares `static agents = false` (a person-only act). */
     agents?: false;
 }
 export interface SerializedSlice extends SerializedSignalOption {
-    /**
-     * Present when the slice declared `.live()`. `sort` is the allowlist of sort keys a subscriber may place a new
-     * row under itself; on any other sort an insertion refetches instead of guessing where the row goes. `pauseOn`
-     * names the arguments that switch the room off while they carry a value, and travels only when there are any.
-     */
+    /** `sort`: keys a subscriber may place a new row under itself (others refetch); `pauseOn` travels only when set. */
     live?: {
         sort: string[];
         pauseOn?: string[];
@@ -160,25 +140,22 @@ export interface SerializedArg {
     nullable?: boolean;
     example?: string | number | boolean | Date;
     enum?: string;
-    /** The values this arg accepts, when they are a fixed list the caller has to pick from. */
     oneOf?: (string | number)[];
-    /** For an id a filter declared against a model: the model it points at, so a UI can offer a picker. */
+    /** The model a filter's id argument points at, so a UI can offer a picker. */
     ref?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
     type: "query" | "mutation" | "pubsub" | "message";
     returns: SerializedReturns;
+    /** Milliseconds; the client sizes its request budget from it. */
+    timeout?: number;
 }
 export interface SerializedFilter {
-    /** Every filter query the model declares, by key, with the args each one takes. */
     filter: {
         [key: string]: SerializedArg[];
     };
     sortKeys: string[];
-    /**
-     * The field map behind each sort key, which a live subscriber needs to place a new row without asking the server
-     * where it goes. Only the keys a `.live({ sort })` allowlist names are ever compared against it.
-     */
+    /** The field map behind each sort key, which a live subscriber needs to place a new row itself. */
     sorts?: {
         [key: string]: {
             [path: string]: 1 | -1;
@@ -199,10 +176,7 @@ export interface SerializedSignal {
     createGuards?: string[];
     updateGuards?: string[];
     removeGuards?: string[];
-    /**
-     * Which generated CRUD verbs this model keeps off the agent shelf. Carried on the signal because the endpoints
-     * it names do not exist until `FetchClient.getBaseEndpoint` synthesizes them. Only the `false` keys travel.
-     */
+    /** Generated CRUD verbs kept off the agent shelf, carried here because `FetchClient.getBaseEndpoint` synthesizes them. */
     mcp?: SerializedSignalMcp;
     /** Which generated CRUD verbs a person-only guard protects, by the same verb map; only the `false` keys travel. */
     agents?: SerializedSignalMcp;
@@ -226,11 +200,8 @@ export type WebsocketMessageData = {
     data: object | object[];
 };
 /**
- * One document change, as one live room sees it.
- *
- * The verb is relative to the room and not to the database: a row edited out of a filter arrives as `leave` in the
- * list it left and `enter` in the one it joined, and a soft delete is a `leave` everywhere. `invalidate` carries no
- * document at all — it is what a room that cannot be routed in memory sends instead, and it means refetch.
+ * `op` is relative to the room, not the database: a row edited out of a filter is `leave` there and `enter` where it
+ * joined, a soft delete is `leave` everywhere, and `invalidate` (no document) means refetch.
  */
 export interface LiveEventPayload {
     op: "enter" | "update" | "leave" | "invalidate";
@@ -238,9 +209,8 @@ export interface LiveEventPayload {
     light?: object | null;
 }
 /**
- * `roomId` is the room the server actually joined; `requestRoomId` is the one the client built from the arguments
- * it sent. They differ only for a live room, whose id also carries the caller's resolved internal arguments so
- * that two subscribers of the same `inSelf` slice do not share one room. The client re-keys on the pair.
+ * `roomId` is the room the server joined, `requestRoomId` the one the client built; they differ only for a live room,
+ * whose id also carries the caller's internal arguments. The client re-keys on the pair.
  */
 export type WebsocketSubscribeAck = {
     type: "sub";

package/types/store/SliceRequest.d.ts

@@ -1,16 +1,6 @@
-/**
- * Which list request for one slice is the current one.
- *
- * Every paging action reads state, fires a fetch, and writes the answer back. Two of them in flight — a user
- * clicking page 2 then page 3 — race, and the *slower* response used to win: the list from one page landed under
- * the page number of another, and the spinner was cleared by whichever finished last. Nothing in the state could
- * say which request a response belonged to, so a ticket says it instead.
- *
- * One per slice rather than per action, because every one of them writes the same `<model>List`.
- */
+/** Which of a slice's in-flight list requests is current, so a slower, older response is dropped. */
 export declare class SliceRequest {
     #private;
-    /** Takes the next ticket and makes it the current one, so every earlier request is now stale. */
     claim(): number;
     isCurrent(ticket: number): boolean;
 }

package/types/store/action.d.ts

@@ -32,16 +32,12 @@ export interface NewOption {
     modal?: string;
     setDefault?: boolean;
     sliceName?: string;
-    /**
-     * The draft scope this form belongs to, already built by the shell that holds the raw seed. Absent means no
-     * draft: `new<Model>` merges its argument into `default<Model>`, whose date defaults would rotate the key on
-     * every open, so the scope cannot be derived from what arrives here.
-     */
+    /** Built by the shell from the raw seed (merged date defaults would rotate the key). Absent means no draft. */
     draftScope?: string;
 }
 export interface EditOption {
     modal?: string | null;
-    /** As `NewOption.draftScope`. For an edit the shell builds it from the record id. */
+    /** Built by the shell from the record id. Absent means no draft. */
     draftScope?: string;
 }
 type PartialOrNull<O> = {

package/types/store/actionTag.d.ts

@@ -3,19 +3,10 @@ export interface ActionOwner {
     refName: string;
 }
 export interface ActionTag {
-    /** The `st.do` key this function is. */
     action: string;
     /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
     state?: string;
 }
-/**
- * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
- *
- * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
- * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
- * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
- *
- * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
- */
+/** Tags a dispatcher (non-enumerable) so a control handed it by reference can emit `data-akan-*`. */
 export declare const tagAction: <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag) => T;
 export declare const actionTagOf: (value: unknown) => ActionTag | undefined;

package/types/store/agent/AgentBridge.d.ts

@@ -1,24 +1,10 @@
 import type { AgentRefusal } from "akanjs/signal";
 import type { StoreInstance } from "../storeInstance.d.ts";
-import type { SerializedStoreState } from "./types.d.ts";
-/**
- * What an in-page agent may read out of the store the user is looking at.
- *
- * Reads only. Driving the app is a component's declaration to make: `st.tool` binds a name and a schema to the
- * same handler the control on screen calls, so what an agent can do is what the screen offers the user and nothing
- * else. A store method that no component declared is not a lever this screen has — publishing one made the surface
- * the bundle rather than the screen, and gave the model levers whose effect it could not see.
- *
- * A key is readable while a mounted component subscribes it through `st.use` / `st.sel` / `st.ref`, and its value
- * is masked by the model that key declares. Masking is not optional even though the data mostly came from the
- * server already masked: `<model>Form` holds what the *user* typed, credentials included, and an in-page agent
- * ships what it reads to a remote model. The mask is by the declared model rather than by the value's class,
- * because `immerify` copies a form into a plain object and the class is gone by the time anyone can ask.
- */
+import { type SerializedStoreState } from "./StoreCatalogue.d.ts";
+/** Masked store reads for an in-page agent: `<model>Form` holds typed credentials, and reads ship to a remote model. */
 export declare class AgentBridge {
     #private;
     readonly refusals: AgentRefusal[];
-    /** The bridge for the app running in this process: the one store every `st.use` goes through. */
     static of(): AgentBridge;
     constructor(instance: StoreInstance);
     get state(): {
@@ -27,11 +13,6 @@ export declare class AgentBridge {
     subscribe(listener: () => void): () => void;
     /** The keys one view may read right now: subscribed by a mounted component and catalogued. */
     readableKeys(viewKey?: string): string[];
-    /**
-     * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
-     *
-     * The key itself has to be one the screen reads, not merely one its store owns: a component subscribing
-     * `userList` says the screen shows a user list, and says nothing about `userForm` sitting in the same store.
-     */
+    /** The masked value of a key a mounted component reads; throws for any other key. */
     read(key: string, viewKey?: string): unknown;
 }

package/types/store/agent/AgentContext.d.ts

@@ -1,13 +1,7 @@
 import type { ContextBlock, SurfaceView } from "../../vendor/use-agentic.d.ts";
 import type { StoreInstance } from "../storeInstance.d.ts";
 import type { AgentBridge } from "./AgentBridge.d.ts";
-/**
- * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
- * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
- * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
- * what happens to be in the store. Base-store plumbing is kept off the surface by `st.use.x({ agent: false })`
- * at each call site, and the route block carries the three of them that matter.
- */
+/** A turn's default context: route, on-screen scopes, and live keys (small primitives inline, the rest by name). */
 export declare class AgentContext {
     #private;
     static of(): AgentContext;

package/types/store/agent/AgentCursor.d.ts

@@ -0,0 +1,24 @@
+/** A plain DOM element, not a React one: it outlives route changes, exists once, and is created on first use. */
+export declare class AgentCursor {
+    #private;
+    static readonly className = "akan-agent-cursor";
+    /** Matches the transform transition in `akanjs/ui/styles.css`. */
+    static readonly travelMs = 320;
+    /** Pixels below which the pointer jumps instead of gliding. */
+    static readonly travelFrom = 200;
+    /** Pixels the pointer drifts off a pressed control while it waits. */
+    static readonly driftBy = 18;
+    /** Fade delay after the last call, for a host that reports no turn boundary (one that does calls `hold`). */
+    static readonly idleMs = 1400;
+    static readonly thinkingClass = "akan-agent-cursor-thinking";
+    static readonly scrollingClass = "akan-agent-cursor-scrolling";
+    /** Travels to the control once it has stopped moving, then presses it. Resolves when the press has landed. */
+    static press(target: HTMLElement): Promise<void>;
+    static scroll(way: "up" | "down"): void;
+    /** Keeps the pointer up for as long as the turn runs, instead of for `idleMs` after the last call. */
+    static hold(): void;
+    static release(): void;
+    /** Drifts clear of the last pressed control and shows the waiting spinner; a no-op before the first press. */
+    static think(): void;
+    static hide(): void;
+}