akanjs 3.0.0-beta.9 → 3.0.0

package/types/signal/mcp/McpUriTemplate.d.ts

@@ -2,30 +2,12 @@ export interface McpResourceTarget {
     endpointKey: string;
     args: Record<string, string | string[]>;
 }
-/**
- * Two-way map between an `akan://` resource URI and the endpoint that answers it.
- *
- * Parsing is done by hand rather than through `URL`: `akan:` is a non-special scheme, and how a runtime
- * normalizes the authority of one (case, percent-decoding) is exactly where a camelCase refName like
- * `agentSession` would quietly stop matching its model.
- */
 export declare class McpUriTemplate {
     #private;
     static readonly scheme = "akan";
     static model(refName: string): string;
-    /**
-     * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
-     * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list
-     * would be one a slice could also be called, and the two would publish the same uri with only one of them
-     * readable. `list` in the *second* segment is already reserved against a model id, so there is nothing to
-     * collide with here.
-     */
+    /** The root list is the bare `…/list`: any third-segment token could also be an author's slice key. */
     static list(refName: string, sliceKey: string, argNames: string[]): string;
-    /**
-     * The uri a template names for one call's arguments — the inverse of `parse`, so what a page fetched can be
-     * attached under the address an agent may read it back from. A list argument repeats its key; an absent
-     * optional one is left out.
-     */
     static expand(template: string, args: Record<string, unknown>): string;
     static parse(uri: string): McpResourceTarget | null;
 }

package/types/signal/mcp/Msg.d.ts

@@ -1,20 +1,11 @@
 import { type MaskModel } from "akanjs/constant";
 import type { JsonSchema } from "../schema.d.ts";
 export type PromptRole = "user" | "assistant";
-/**
- * What a client may do with a block when it cannot keep all of them.
- *
- * `priority` is the field that matters here: a prompt this server assembles is often mostly context — a document
- * embedded beside the one line asking for something — and a client with a full window drops blocks by this number
- * rather than by position. Leaving it off means every block is equally droppable, so the instruction can go and
- * the attachment stay.
- */
 export interface PromptAnnotations {
-    /** Who the block is for. A note meant only for the model is `["assistant"]`, so a UI need not render it. */
     audience?: PromptRole[];
-    /** 0 is "drop this first", 1 is "this is the point of the prompt". Anything outside the range is refused. */
+    /** 0 = drop first, 1 = the point of the prompt; omitted = as droppable as any block; outside 0..1 throws. */
     priority?: number;
-    /** ISO 8601. Lets a client tell a re-fetched resource from the copy it already holds. */
+    /** ISO 8601. */
     lastModified?: string;
 }
 export interface PromptTextContent {
@@ -51,93 +42,45 @@ export interface PromptMessage {
     role: PromptRole;
     content: PromptContent;
 }
-/** What a `prompt()` exec may return. A bare string is the 80% case and is wrapped into one user message. */
+/** A bare string is wrapped into one user message. */
 export type PromptResult = string | PromptMessage[];
-/** Enough of the `File` model to link or inline it, structural so the framework does not depend on the lib. */
+/** Structural, so the framework does not depend on the lib's `File` model. */
 export interface PromptFileSource {
     url: string;
     filename?: string;
     mimetype?: string;
 }
-/**
- * A model class, named by the caller so an attachment can be masked by what it *is* rather than by what it still
- * carries at runtime. The same model any other audience masks by — see `mask` in `akanjs/constant`.
- */
 export type PromptModel = MaskModel;
 /**
- * Builds the messages a `prompt()` endpoint returns.
- *
- * Named `Msg` rather than `msg` because `akanjs/dictionary` already exports a `msg` for toasts.
- *
- * Every attachment builder carries the `user` role. Content the server assembles is context handed *to* the
- * model, which is what the user role means; an assistant-role attachment would be the server putting words in the
- * model's mouth. That is only meaningful for few-shot text, which `Msg.assistant` covers.
+ * Named `Msg` because `akanjs/dictionary` already exports a `msg`. Attachments carry the `user` role: an
+ * assistant-role attachment would put the server's words in the model's mouth.
  */
 export declare class Msg {
     #private;
-    /**
-     * What every `prompt()` route answers with, as JSON Schema, for the app's OpenAPI document.
-     *
-     * A prompt declares `Any` on the wire, so the generated response schema was `{}` — a documented `GET` whose body
-     * the document could not describe, which is half of the agreement the HTTP route was mounted for. The shape is
-     * fixed by the protocol rather than by the endpoint, so it is written once, here: the block types and the fields
-     * each must carry come off `contentFields`, so a type added to one cannot describe itself out of the other.
-     */
+    /** JSON Schema of a prompt message for the OpenAPI document, since a prompt declares `Any` on the wire. */
     static readonly schema: JsonSchema;
     static user(text: string, annotations?: PromptAnnotations): PromptMessage;
     static assistant(text: string, annotations?: PromptAnnotations): PromptMessage;
     /**
-     * Embeds the value itself. The payload travels in the prompt, so prefer `link` for anything large.
-     *
-     * Name the model it is an instance of and the `hidden`/`secret` fields are stripped before it goes out:
-     * `Msg.resource(uri, order, { model: cnst.Order })`. A payload you assembled yourself needs no model and is
-     * embedded as given — but one that still carries a document's secret fields is refused rather than sent, so
-     * the rule is the same either way: a document travels masked, or it does not travel.
+     * Naming the `model` strips its `hidden`/`secret` fields; an unnamed payload that still carries populated ones
+     * throws rather than being sent.
      */
     static resource(uri: string, value: unknown, { model, ...annotations }?: {
         model?: PromptModel;
     } & PromptAnnotations): PromptMessage;
     /**
-     * Strips what a model marks `hidden` or `secret`, by the model the caller names rather than by the one the
-     * value happens to still carry.
-     *
-     * That distinction is the whole fix. A check that reads the class off the value can only mask what arrives as an
-     * instance, so a `{ ...doc }` spread, a `toJSON()`, or a round-trip through `JSON.stringify` reached the wire
-     * with the metadata already gone and nothing could be done about it. A named model is metadata the value cannot
-     * lose, so a hydrated document and a plain object copied out of one mask identically.
-     *
-     * This is the field half of `resolveReturn` and deliberately not the whole of it. That one also loads every
-     * relation it walks past, which is right for a query's return value and wrong for an attachment, where it would
-     * turn embedding one document into a fan of queries nobody asked for. So a populated relation is masked in
-     * place and one that is still an id is left as an id.
-     *
-     * Public because a payload can be an assembly of several documents — `{ order, customer }` names no single
-     * model, so each piece is masked on its way in.
-     *
-     * Returns `unknown` rather than the argument's type, because what comes back is missing fields that type still
-     * promises. The value's only destination is a JSON payload, so nothing downstream wanted the type anyway.
+     * Masks by the named model rather than the value's class, which a spread or a JSON round-trip loses. Unlike
+     * `resolveReturn` it loads no relation: a populated one is masked in place, an id stays an id.
      */
     static mask(model: PromptModel, value: unknown): unknown;
-    /**
-     * Points at something without paying for it. The client decides whether to fetch, and skips what it already
-     * holds — so a prompt that references twenty documents costs twenty URIs rather than twenty payloads.
-     */
     static link(source: string | PromptFileSource, { name, description, ...annotations }?: {
         name?: string;
         description?: string;
     } & PromptAnnotations): PromptMessage;
     static image(data: string, mimeType: string, annotations?: PromptAnnotations): PromptMessage;
     static audio(data: string, mimeType: string, annotations?: PromptAnnotations): PromptMessage;
-    /**
-     * Inlines a file as base64, costing roughly 1.33× its bytes in the prompt. Worth it only when the client
-     * cannot fetch the URL itself — a public asset is cheaper as `Msg.link`. Fetched as this process, so a file
-     * behind a caller-scoped signed URL needs its bytes passed to `Msg.image` instead.
-     */
+    /** Fetched as this process, so a file behind a caller-scoped signed URL needs its bytes passed to `Msg.image`. */
     static imageOf(file: PromptFileSource, annotations?: PromptAnnotations): Promise<PromptMessage>;
-    /**
-     * The one runtime check on a prompt's return value. `prompt()` carries `Any` on the wire so the signal
-     * pipeline hands the value back untouched — nothing upstream would notice a malformed message, and the client
-     * would receive it as a valid prompt.
-     */
+    /** The only runtime check on a prompt's value: `prompt()` carries `Any`, so nothing upstream inspects it. */
     static normalize(value: unknown): PromptMessage[];
 }

package/types/signal/mcp/mcpProtocol.d.ts

@@ -1,17 +1,3 @@
-/**
- * Wire vocabulary for the MCP revisions this server answers.
- *
- * `2026-07-28` made the protocol stateless — no `initialize`, no session id, no server-opened stream — which is
- * what makes a single `POST /mcp` route sufficient. Everything before it is the *legacy* era, still what shipping
- * clients speak (measured: Claude Code 2.1.226 negotiates `2025-11-25`), and supporting it costs almost nothing
- * here because a legacy server *may* decline to issue `Mcp-Session-Id`: without one the client sends no session
- * header and never asks to resume a stream, so both eras run over the same stateless handler.
- *
- * `2025-06-18` is listed for the same reason. The surface this server actually implements — POST-only Streamable
- * HTTP, no sessions, no server-initiated requests — is wire-identical between the two legacy revisions, and a
- * client that proposes a version the server does not list is told to disconnect. Naming only the one revision that
- * was measured turned "we tested against this" into "we refuse everything else".
- */
 export declare const MCP_MODERN_VERSION = "2026-07-28";
 export declare const MCP_LEGACY_VERSION = "2025-11-25";
 export declare const MCP_LEGACY_PRIOR_VERSION = "2025-06-18";
@@ -24,14 +10,6 @@ export declare const MCP_META_PROTOCOL_VERSION = "io.modelcontextprotocol/protoc
 export declare const MCP_META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
 export declare const MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
 export declare const MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
-/**
- * `-32020`..`-32099` is reserved by the spec, so nothing outside this table may be minted in that band.
- * `-32002` (resource not found) is retired in the modern revision; unknown resources are `invalidParams`.
- *
- * The band also defines `-32021 missingRequiredClientCapability`, which is absent because this server requires
- * none: it never samples, elicits, or reads roots. It belongs here the day one of those appears, not before — a
- * constant nothing emits reads as a check someone forgot to write.
- */
 export declare const McpErrorCode: {
     readonly parse: -32700;
     readonly invalidRequest: -32600;
@@ -83,10 +61,7 @@ export interface McpPromptArgument {
     description?: string;
     required?: boolean;
 }
-/**
- * A prompt is user-controlled — the client offers it as a slash command and the model never invokes it — so its
- * `title` and `description` are read by a person, not inferred from a schema the way a tool's are.
- */
+/** User-controlled: a client offers it as a slash command, so a person reads its `title` and `description`. */
 export interface McpPrompt {
     name: string;
     title?: string;

package/types/signal/mcp/pagePrompt.d.ts

@@ -1,13 +1,11 @@
 import type { McpPromptArgument } from "./mcpProtocol.d.ts";
-/** One `page().prompt(name, description)` as the catalogue lists it, with the route it was declared on. */
 export interface PagePromptEntry {
     name: string;
     description: string;
     arguments: McpPromptArgument[];
-    /** The matched route pattern (`/:lang/project/:projectId`), which is also what names the screen to a model. */
+    /** The matched route pattern, e.g. `/:lang/project/:projectId`. */
     pattern: string;
 }
-/** One `fetch.*` query the page made while its body ran, with the answer it received. */
 export interface PagePromptRecord {
     key: string;
     args: Record<string, unknown>;
@@ -35,15 +33,11 @@ export interface PagePromptRunInput {
     name: string;
     /** `prompts/get` sends a flat string map; the page's own declaration types each value. */
     arguments: Record<string, string>;
-    /** The caller's request headers the page run should carry — the bearer token above all. */
     headers: [string, string][];
-    /** The locale segment the synthetic URL starts with; the route needs one whether or not the page reads it. */
+    /** The synthetic URL's locale segment, which the route needs whether or not the page reads it. */
     language?: string;
 }
-/**
- * Where page prompts come from. Pages live in the RSC worker, a process apart from the one that serves `/mcp`,
- * so the MCP router speaks to them through this rather than by importing route modules of its own.
- */
+/** Pages live in the RSC worker, a process apart from the one serving `/mcp`, so the router reaches them through this. */
 export interface PagePromptSource {
     list(): Promise<PagePromptEntry[]>;
     run(input: PagePromptRunInput): Promise<PagePromptRun>;

package/types/signal/middleware.d.ts

@@ -21,39 +21,12 @@ declare const Logging_base: {
 export declare class Logging extends Logging_base {
     use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }
-declare const Cache_base: {
-    new (): {
-        use(env: BackendEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-    };
-    refName: string;
-};
-/**
- * Serves an endpoint's own answer back for as long as its declared `cache` allows, and stands aside for every
- * endpoint that declared none — this is registered by default, so a TTL of its own would put a stale window on
- * every call in the app.
- *
- * A cached answer is **shared**, which is why only a `query` taking no internal argument can carry one: internal
- * arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers per caller
- * and one entry would be one caller's answer handed to the next. Guards are re-run on every hit regardless —
- * shared is not public, and `next()`, which is what runs them, is exactly what a hit skips.
- */
-export declare class Cache extends Cache_base {
-    #private;
-    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-}
 declare const Timeout_base: {
     new (): {
         use(env: BackendEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
     };
     refName: string;
 };
-/**
- * Bounds an endpoint that declared a `timeout`, and nothing else — this is registered by default, so a default
- * of its own would put a deadline on every endpoint in the app that nobody asked for.
- *
- * XXX losing the race does not cancel the work: `next()` keeps running with nobody holding its result, so a
- * handler that writes is still going to write. The deadline answers the caller; it does not undo the call.
- */
 export declare class Timeout extends Timeout_base {
     use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }

package/types/signal/schema/JsonSchemaBuilder.d.ts

@@ -2,71 +2,43 @@ import { type ConstantCls } from "akanjs/constant";
 import type { SerializedArg, SerializedReturns } from "../types.d.ts";
 export type JsonSchema = Record<string, unknown>;
 export interface JsonSchemaBuilderOptions {
-    /**
-     * Where a model `$ref` points. OpenAPI collects every model under `components/schemas`, while MCP requires each
-     * tool schema to resolve on its own and so embeds its models in a per-schema `$defs`.
-     */
+    /** Default `#/components/schemas/` (OpenAPI); MCP embeds each tool's models in a per-schema `$defs`. */
     refPrefix?: string;
-    /**
-     * How a nullable schema is spelled. `anyOf` with a null branch is the OpenAPI habit and the default; `type` merges
-     * `"null"` into a schema that has one plain `type` (and lists `null` in its `enum`, which would otherwise still
-     * refuse it) — the shorter form a listing that is re-sent to every agent is paid for by the byte.
-     */
+    /** `anyOf` (default) adds a null branch; `type` merges `"null"` into a plain `type` (and its `enum`), shorter. */
     nullable?: "anyOf" | "type";
+    /** `wire` (default) is the HTTP body shape; `agent` uses a primitive's `agent.schema` when it declares one. */
+    face?: JsonSchemaFace;
 }
+export type JsonSchemaFace = "wire" | "agent";
 export type JsonSchemaRelations = "inline" | "id" | "named";
 export interface JsonSchemaModelOptions {
     /**
-     * Drops `hidden`, `secret`, and `visual` fields. `SignalContext.resolveReturn` strips the first two from every
-     * response, so naming them describes a value the caller can never read — and on a model like `user` the names
-     * are themselves the leak: `password`, `accountId`, `phone` published as readable properties of the model. This
-     * is the one place a field the framework blocks on every value path is still visible, so it is scoped to schemas
-     * that describe a *response*. A request body is a different shape and legitimately carries all three.
-     *
-     * `visual` is dropped here because it is dropped from the payload an AI caller receives, and a schema that
-     * promises a field the value omits is worse than one that never named it: a non-optional visual field would be
-     * listed `required` and a validating client would refuse the whole result.
+     * Response schemas only: drops `hidden`/`secret` (stripped from every response, and on `user` the names alone
+     * leak) and `visual` (stripped for AI callers, so listing it `required` would make a client refuse the result).
      */
     readable?: boolean;
     /**
-     * How a field holding another database model is described. `inline` follows the `$ref`, which is right where
-     * schemas share a component section. `id` is what a request body carries: `serialize` sends a relation as its id,
-     * so a schema showing the whole related object asks the caller for a shape the server never reads. `named` is for
-     * a response: the nested document becomes `{ type: "object" }` carrying its model name, so the returned model
-     * keeps every field of its own and stops dragging its relations' closures into each copy. An embedded scalar has
-     * no tool of its own and stays inline under either.
+     * A database-model field: `inline` (default) follows the `$ref`, `id` is what a request body carries, `named` is
+     * `{ type: "object" }` with the model name. An embedded scalar always stays inline.
      */
     relations?: JsonSchemaRelations;
-    /**
-     * Whether an id carries the 24-hex `pattern`. Kept on a top-level argument, where it is read once; dropped inside
-     * a per-tool `$defs`, where it would repeat on every id field of every copy.
-     */
+    /** Whether an id carries the 24-hex `pattern` (default `true`). */
     idPattern?: boolean;
 }
-/**
- * Turns serialized signal metadata and Akan constants into JSON Schema (2020-12 by default, which is also what
- * OpenAPI 3.1 uses). One builder per output dialect target — `new` it at the call site, it holds no shared state.
- */
 export declare class JsonSchemaBuilder {
     #private;
-    constructor({ refPrefix, nullable }?: JsonSchemaBuilderOptions);
+    constructor({ refPrefix, nullable, face, }?: JsonSchemaBuilderOptions);
     arg(arg: SerializedArg): JsonSchema;
     upload(arg: SerializedArg): JsonSchema;
     returns(returns: SerializedReturns): JsonSchema;
     model(modelRef: ConstantCls, options?: JsonSchemaModelOptions): JsonSchema;
-    /** Every registered model, keyed by schema name. Callers narrow this with `referencedSchemas`. */
     allModelSchemas(options?: JsonSchemaModelOptions): Record<string, JsonSchema>;
-    /**
-     * The models `seed` references, plus everything those transitively reference, sorted by name.
-     *
-     * `allSchemas` is derived from the registry, so a caller that narrows many seeds against the same registry —
-     * MCP builds one per tool schema and one per output schema — passes its own copy rather than rebuilding every
-     * registered model each time. Holding it here instead would make this builder stateful, and the one in
-     * `openapi.ts` lives at module scope for the life of the process.
-     */
+    /** The transitive closure of the models `seed` references, sorted by name. Pass `allSchemas` when narrowing often. */
     referencedSchemas(seed: unknown, allSchemas?: Record<string, JsonSchema>): {
         [k: string]: JsonSchema;
     };
     collectRefNames(value: unknown): Set<string>;
-    static primitive(refName: string, { idPattern }?: Pick<JsonSchemaModelOptions, "idPattern">): JsonSchema;
+    static primitive(refName: string, { idPattern, face }?: Pick<JsonSchemaModelOptions, "idPattern"> & {
+        face?: JsonSchemaFace;
+    }): JsonSchema;
 }

package/types/signal/serializer/fetch.serializer.d.ts

@@ -6,12 +6,7 @@ export declare class FetchSerializer {
     static logger: Logger;
     static serializeDatabaseSignal(sliceCls: SliceCls, endpointCls: EndpointCls): SerializedSignal;
     static serializeServiceSignal(endpointCls: EndpointCls): SerializedSignal;
-    /**
-     * A container that never finished initializing has empty registries rather than none, so a caller reaching a
-     * devtools or MCP route before boot completed gets an empty catalogue. Destructuring the registry used to
-     * throw before the loop, which surfaced as `Cannot destructure property 'endpointCls' from null` on a route
-     * whose honest answer is "nothing is registered yet".
-     */
+    /** A container that has not finished booting answers an empty catalogue rather than throwing. */
     static serializeRegistry(live: LiveRegistry | null | undefined): {
         signal: {
             [key: string]: SerializedSignal;

package/types/signal/serverSignal.d.ts

@@ -34,6 +34,5 @@ export type ServerSignalClsStatics = {
 export type ServerSignalMethods<EnpCls, IntCls> = EndpointServerSignalMethods<EnpCls> & InternalServerSignalMethods<IntCls>;
 export type TypedServerSignalCls<EnpCls, IntCls> = AdaptorCls<ServerSignalMethods<EnpCls, IntCls> & ServerSignal> & ServerSignalClsStatics;
 export type ServerSignalCls<EnpCls = unknown, IntCls = unknown> = AdaptorCls<ServerSignalMethods<EnpCls, IntCls> & ServerSignal> & ServerSignalClsStatics;
-/** Composes endpoint and internal classes into a server-side signal class. */
 export declare const serverSignal: <EnpCls, IntCls>(endpointRef: EnpCls, internalRef: IntCls) => ServerSignalCls<EnpCls, IntCls>;
 export {};

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,52 +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>;
-    /**
-     * The endpoint's guards, for a middleware that answers a call without executing it — a cache hit skips
-     * `next()`, and `next()` is what would otherwise run them. Side-effect free, like the guards themselves.
-     */
-    checkGuards(): Promise<void>;
-    /**
-     * 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/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>;
@@ -102,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 }: {
@@ -113,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,8 +65,7 @@ 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 [] ? {
+type RootSliceInfoObj<SrvModule extends ServiceModel, _Input, _Full, _Light, _Insight, _Filter extends FilterInstance, _QueryKey extends string> = {
     [""]: SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SrvMap<SrvModule>, [
         "queryKey",
         "args"
@@ -83,5 +77,6 @@ export declare function slice<SrvModule extends ServiceModel, BuildSlice extends
         _QueryKey | undefined,
         unknown[] | undefined
     ]>;
-} : ExtendSliceInfoObj<SrvModule, LibSlices>>>;
+};
+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, LibSlices extends [] ? Assign<ReturnType<BuildSlice>, RootSliceInfoObj<SrvModule, _Input, _Full, _Light, _Insight, _Filter, _QueryKey>> : Assign<ExtendSliceInfoObj<SrvModule, LibSlices>, Assign<ReturnType<BuildSlice>, RootSliceInfoObj<SrvModule, _Input, _Full, _Light, _Insight, _Filter, _QueryKey>>>>;
 export {};