akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/signal/openapi/openapi.ts

@@ -1,9 +1,8 @@
-import { type Cls, FIELD_META, getNonArrayModel, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
-import { type ConstantCls, type ConstantField, ConstantRegistry, type ConstantType } from "akanjs/constant";
 import { FetchClient } from "akanjs/fetch";
-import type { SerializedArg, SerializedEndpoint, SerializedReturns, SerializedSignal } from "../types";
+import { Msg } from "../mcp";
+import { type JsonSchema, JsonSchemaBuilder } from "../schema";
+import type { SerializedArg, SerializedEndpoint, SerializedSignal } from "../types";
 
-type OpenApiSchema = Record<string, unknown>;
 type OpenApiParameter = Record<string, unknown>;
 type OpenApiOperation = Record<string, unknown>;
 type OpenApiPathItem = Record<string, OpenApiOperation>;
@@ -28,16 +27,29 @@ export interface OpenApiDocument {
   servers?: { url: string; description?: string }[];
   paths: Record<string, OpenApiPathItem>;
   components: {
-    schemas: Record<string, OpenApiSchema>;
-    securitySchemes?: Record<string, OpenApiSchema>;
+    schemas: Record<string, JsonSchema>;
+    securitySchemes?: Record<string, JsonSchema>;
   };
 }
 
+/**
+ * Every endpoint type this app answers over HTTP, which is what an API contract has to list.
+ *
+ * `prompt` is a plain `GET` mounted whether or not the app enabled MCP, so leaving it out described an app that
+ * serves fewer routes than it does — and left this document disagreeing with the API explorer, which shows the
+ * same route. The websocket types (`pubsub`, `message`) have no HTTP surface to describe and are absent for that
+ * reason rather than by omission.
+ */
 const httpMethods = {
   query: "get",
   mutation: "post",
+  prompt: "get",
 } as const;
 
+const schema = new JsonSchemaBuilder();
+/** Not a model, so it is handed to `referencedSchemas` beside them — and travels only if a prompt route cites it. */
+const promptMessageSchemaName = "PromptMessage";
+
 export const createOpenApiDocument = (
   serializedSignal: Record<string, SerializedSignal>,
   options: OpenApiDocumentOptions = {},
@@ -71,7 +83,10 @@ export const createOpenApiDocument = (
     ...(options.servers?.length ? { servers: options.servers } : {}),
     paths,
     components: {
-      schemas: createReferencedComponentSchemas(paths),
+      schemas: schema.referencedSchemas(paths, {
+        ...schema.allModelSchemas(),
+        [promptMessageSchemaName]: Msg.schema,
+      }),
       ...(hasProtectedOperation
         ? {
             securitySchemes: {
@@ -95,7 +110,7 @@ const collectRestEndpoints = (refName: string, signal: SerializedSignal): [strin
       )
     : [];
   return [...baseEndpointEntries, ...sliceEndpointEntries, ...Object.entries(signal.endpoint)].filter(
-    ([, endpoint]) => endpoint.type === "query" || endpoint.type === "mutation",
+    ([, endpoint]) => endpoint.type in httpMethods,
   );
 };
 
@@ -143,7 +158,7 @@ const createParameter = (
   name: arg.name,
   in: location,
   required: location === "path",
-  schema: createArgSchema(arg),
+  schema: schema.arg(arg),
   ...(arg.example !== undefined ? { example: arg.example } : {}),
   ...(options.resolveDescription?.(`${refName}.signal.${endpointKey}.arg.${arg.name}.desc`)
     ? { description: options.resolveDescription(`${refName}.signal.${endpointKey}.arg.${arg.name}.desc`) }
@@ -152,12 +167,12 @@ const createParameter = (
 
 const createRequestBody = (bodyArgs: SerializedArg[], uploadArgs: SerializedArg[]) => {
   const required = [...bodyArgs, ...uploadArgs].filter((arg) => !arg.nullable).map((arg) => arg.name);
-  const schema = {
+  const bodySchema = {
     type: "object",
     properties: Object.fromEntries(
       [...bodyArgs, ...uploadArgs].map((arg) => [
         arg.name,
-        uploadArgs.includes(arg) ? createUploadSchema(arg) : createArgSchema(arg),
+        uploadArgs.includes(arg) ? schema.upload(arg) : schema.arg(arg),
       ]),
     ),
     ...(required.length ? { required } : {}),
@@ -166,7 +181,7 @@ const createRequestBody = (bodyArgs: SerializedArg[], uploadArgs: SerializedArg[
     required: required.length > 0,
     content: {
       [uploadArgs.length ? "multipart/form-data" : "application/json"]: {
-        schema,
+        schema: bodySchema,
       },
     },
   };
@@ -181,168 +196,14 @@ const createResponseContent = (endpoint: SerializedEndpoint) =>
       }
     : {
         "application/json": {
-          schema: createReturnSchema(endpoint.returns),
+
+          schema:
+            endpoint.type === "prompt"
+              ? { type: "array", items: { $ref: `#/components/schemas/${promptMessageSchemaName}` } }
+              : schema.returns(endpoint.returns),
         },
       };
 
-const createReturnSchema = (returns: SerializedReturns): OpenApiSchema =>
-  withNullable(
-    withArrayDepth(createRefSchema(returns.refName, returns.modelType), returns.arrDepth ?? 0),
-    !!returns.nullable,
-  );
-
-const createArgSchema = (arg: SerializedArg): OpenApiSchema => {
-  const schema = arg.enum ? createEnumSchema(arg.enum) : createRefSchema(arg.refName, arg.modelType);
-  return withNullable(withArrayDepth(schema, arg.arrDepth ?? 0), !!arg.nullable);
-};
-
-const createUploadSchema = (arg: SerializedArg): OpenApiSchema => {
-  const fileSchema = { type: "string", format: "binary" };
-  return withNullable(withArrayDepth(fileSchema, arg.arrDepth ?? 0), !!arg.nullable);
-};
-
-const createRefSchema = (refName: string, modelType?: ConstantType): OpenApiSchema => {
-  if (!modelType) return createPrimitiveSchema(refName);
-  const modelRef = ConstantRegistry.getModelRef(refName, modelType);
-  return { $ref: `#/components/schemas/${ConstantRegistry.getModelName(modelRef as Cls)}` };
-};
-
-const createComponentSchemas = (): Record<string, OpenApiSchema> => {
-  const schemas: Record<string, OpenApiSchema> = {};
-  for (const [, database] of ConstantRegistry.database.entries()) {
-    [database.input, database.object, database.full, database.light, database.insight].forEach((modelRef) => {
-      schemas[ConstantRegistry.getModelName(modelRef)] = createModelSchema(modelRef);
-    });
-  }
-  for (const [, scalar] of ConstantRegistry.scalar.entries()) {
-    schemas[ConstantRegistry.getModelName(scalar.model)] = createModelSchema(scalar.model);
-  }
-  return schemas;
-};
-
-const createReferencedComponentSchemas = (paths: Record<string, OpenApiPathItem>): Record<string, OpenApiSchema> => {
-  const allSchemas = createComponentSchemas();
-  const referencedNames = collectSchemaRefNames(paths);
-  const pending = [...referencedNames];
-  for (let idx = 0; idx < pending.length; idx++) {
-    const schemaName = pending[idx];
-    if (!schemaName) continue;
-    const schema = allSchemas[schemaName];
-    if (!schema) continue;
-    for (const nestedName of collectSchemaRefNames(schema)) {
-      if (referencedNames.has(nestedName)) continue;
-      referencedNames.add(nestedName);
-      pending.push(nestedName);
-    }
-  }
-  return Object.fromEntries(
-    [...referencedNames]
-      .sort((a, b) => a.localeCompare(b))
-      .flatMap((name) => (allSchemas[name] ? ([[name, allSchemas[name]]] as const) : [])),
-  );
-};
-
-const collectSchemaRefNames = (value: unknown): Set<string> => {
-  const refs = new Set<string>();
-  const visit = (current: unknown) => {
-    if (!current || typeof current !== "object") return;
-    if (Array.isArray(current)) {
-      current.forEach(visit);
-      return;
-    }
-    const record = current as Record<string, unknown>;
-    if (typeof record.$ref === "string") {
-      const match = record.$ref.match(/^#\/components\/schemas\/(.+)$/);
-      if (match?.[1]) refs.add(match[1]);
-    }
-    Object.values(record).forEach(visit);
-  };
-  visit(value);
-  return refs;
-};
-
-const createModelSchema = (modelRef: ConstantCls): OpenApiSchema => {
-  const fields = (modelRef as { [FIELD_META]?: Record<string, ConstantField> })[FIELD_META] ?? {};
-  const properties: Record<string, OpenApiSchema> = {};
-  const required: string[] = [];
-  for (const [key, field] of Object.entries(fields)) {
-    const props = field.getProps();
-    properties[key] = createFieldSchema(field);
-    if (!props.nullable) required.push(key);
-  }
-  return {
-    type: "object",
-    properties,
-    ...(required.length ? { required } : {}),
-    additionalProperties: false,
-  };
-};
-
-const createFieldSchema = (field: ConstantField): OpenApiSchema => {
-  const props = field.getProps();
-  const schema = props.enum ? createInlineEnumSchema([...props.enum.values]) : createFieldRefSchema(props);
-  return withNullable(withArrayDepth(schema, props.arrDepth), props.nullable);
-};
-
-const createFieldRefSchema = (props: ReturnType<ConstantField["getProps"]>): OpenApiSchema => {
-  if (props.isMap) {
-    const [valueRef, valueArrDepth] = getNonArrayModel(props.of as Cls | Cls[]);
-    return {
-      type: "object",
-      additionalProperties: withArrayDepth(createModelRefSchema(valueRef as Cls), valueArrDepth),
-    };
-  }
-  return createModelRefSchema(props.modelRef as Cls);
-};
-
-const createModelRefSchema = (modelRef: Cls): OpenApiSchema => {
-  if (PrimitiveRegistry.has(modelRef))
-    return createPrimitiveSchema(PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar));
-  return { $ref: `#/components/schemas/${ConstantRegistry.getModelName(modelRef)}` };
-};
-
-const createPrimitiveSchema = (refName: string): OpenApiSchema => {
-  switch (refName) {
-    case "Boolean":
-      return { type: "boolean" };
-    case "Date":
-      return { type: "string", format: "date-time" };
-    case "Float":
-      return { type: "number" };
-    case "ID":
-      return { type: "string", pattern: "^[0-9a-fA-F]{24}$" };
-    case "Int":
-      return { type: "integer" };
-    case "Upload":
-      return { type: "string", format: "binary" };
-    case "Any":
-      return {};
-    case "String":
-    default:
-      return { type: "string" };
-  }
-};
-
-const createEnumSchema = (refName: string): OpenApiSchema => {
-  const enumRef = ConstantRegistry.enum.get(refName);
-  if (!enumRef) return { type: "string", "x-akan-enum": refName };
-  return createInlineEnumSchema([...enumRef.values]);
-};
-
-const createInlineEnumSchema = (values: unknown[]): OpenApiSchema => ({
-  type: values.every((value) => typeof value === "number") ? "number" : "string",
-  enum: values,
-});
-
-const withArrayDepth = (schema: OpenApiSchema, arrDepth: number): OpenApiSchema => {
-  let current = schema;
-  for (let idx = 0; idx < arrDepth; idx++) current = { type: "array", items: current };
-  return current;
-};
-
-const withNullable = (schema: OpenApiSchema, nullable: boolean): OpenApiSchema =>
-  nullable ? { anyOf: [schema, { type: "null" }] } : schema;
-
 const getProtectedGuards = (guards?: string[]) =>
   (guards ?? []).filter((guard) => guard !== "None" && guard !== "Public");
 

package/signal/schema/JsonSchemaBuilder.ts

@@ -0,0 +1,211 @@
+import { type Cls, FIELD_META, getNonArrayModel, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { type ConstantCls, type ConstantField, ConstantRegistry, type ConstantType } from "akanjs/constant";
+import type { SerializedArg, SerializedReturns } from "../types";
+
+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`.
+   */
+  refPrefix?: string;
+}
+
+export interface JsonSchemaModelOptions {
+  /**
+   * Drops `hidden` and `secret` fields. `SignalContext.resolveReturn` strips both 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 both.
+   */
+  readable?: 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 class JsonSchemaBuilder {
+  readonly #refPrefix: string;
+  constructor({ refPrefix = "#/components/schemas/" }: JsonSchemaBuilderOptions = {}) {
+    this.#refPrefix = refPrefix;
+  }
+
+  arg(arg: SerializedArg): JsonSchema {
+    const schema = arg.enum ? this.#enum(arg.enum) : this.#ref(arg.refName, arg.modelType);
+    return JsonSchemaBuilder.#nullable(JsonSchemaBuilder.#arrayed(schema, arg.arrDepth ?? 0), !!arg.nullable);
+  }
+
+  upload(arg: SerializedArg): JsonSchema {
+    const fileSchema = { type: "string", format: "binary" };
+    return JsonSchemaBuilder.#nullable(JsonSchemaBuilder.#arrayed(fileSchema, arg.arrDepth ?? 0), !!arg.nullable);
+  }
+
+  returns(returns: SerializedReturns): JsonSchema {
+    return JsonSchemaBuilder.#nullable(
+      JsonSchemaBuilder.#arrayed(this.#ref(returns.refName, returns.modelType), returns.arrDepth ?? 0),
+      !!returns.nullable,
+    );
+  }
+
+  model(modelRef: ConstantCls, { readable = false }: JsonSchemaModelOptions = {}): JsonSchema {
+    const fields = (modelRef as { [FIELD_META]?: Record<string, ConstantField> })[FIELD_META] ?? {};
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+    for (const [key, field] of Object.entries(fields)) {
+      const props = field.getProps();
+      if (readable && (props.fieldType === "hidden" || props.fieldType === "secret")) continue;
+      properties[key] = this.#field(field);
+      if (!props.nullable) required.push(key);
+    }
+    return {
+      type: "object",
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    };
+  }
+
+  /** Every registered model, keyed by schema name. Callers narrow this with `referencedSchemas`. */
+  allModelSchemas(options: JsonSchemaModelOptions = {}): Record<string, JsonSchema> {
+    const schemas: Record<string, JsonSchema> = {};
+    for (const [, database] of ConstantRegistry.database.entries()) {
+      [database.input, database.object, database.full, database.light, database.insight].forEach((modelRef) => {
+        schemas[ConstantRegistry.getModelName(modelRef)] = this.model(modelRef, options);
+      });
+    }
+    for (const [, scalar] of ConstantRegistry.scalar.entries()) {
+      schemas[ConstantRegistry.getModelName(scalar.model)] = this.model(scalar.model, options);
+    }
+    return schemas;
+  }
+
+  /**
+   * 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.
+   */
+  referencedSchemas(seed: unknown, allSchemas: Record<string, JsonSchema> = this.allModelSchemas()) {
+    const referencedNames = this.collectRefNames(seed);
+    const pending = [...referencedNames];
+    for (let idx = 0; idx < pending.length; idx++) {
+      const schemaName = pending[idx];
+      if (!schemaName) continue;
+      const schema = allSchemas[schemaName];
+      if (!schema) continue;
+      for (const nestedName of this.collectRefNames(schema)) {
+        if (referencedNames.has(nestedName)) continue;
+        referencedNames.add(nestedName);
+        pending.push(nestedName);
+      }
+    }
+    return Object.fromEntries(
+      [...referencedNames]
+        .sort((a, b) => a.localeCompare(b))
+        .flatMap((name) => (allSchemas[name] ? ([[name, allSchemas[name]]] as const) : [])),
+    );
+  }
+
+  collectRefNames(value: unknown): Set<string> {
+    const refs = new Set<string>();
+    const visit = (current: unknown) => {
+      if (!current || typeof current !== "object") return;
+      if (Array.isArray(current)) {
+        current.forEach(visit);
+        return;
+      }
+      const record = current as Record<string, unknown>;
+      if (typeof record.$ref === "string") {
+        const name = this.#refName(record.$ref);
+        if (name) refs.add(name);
+      }
+      Object.values(record).forEach(visit);
+    };
+    visit(value);
+    return refs;
+  }
+
+  #refName(ref: string): string | undefined {
+    if (!ref.startsWith(this.#refPrefix)) return undefined;
+    const name = ref.slice(this.#refPrefix.length);
+    return name.length ? name : undefined;
+  }
+
+  #ref(refName: string, modelType?: ConstantType): JsonSchema {
+    if (!modelType) return JsonSchemaBuilder.primitive(refName);
+    const modelRef = ConstantRegistry.getModelRef(refName, modelType);
+    return { $ref: `${this.#refPrefix}${ConstantRegistry.getModelName(modelRef as Cls)}` };
+  }
+
+  #modelRef(modelRef: Cls): JsonSchema {
+    if (PrimitiveRegistry.has(modelRef))
+      return JsonSchemaBuilder.primitive(PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar));
+    return { $ref: `${this.#refPrefix}${ConstantRegistry.getModelName(modelRef)}` };
+  }
+
+  #field(field: ConstantField): JsonSchema {
+    const props = field.getProps();
+    const schema = props.enum ? JsonSchemaBuilder.#inlineEnum([...props.enum.values]) : this.#fieldRef(props);
+    return JsonSchemaBuilder.#nullable(JsonSchemaBuilder.#arrayed(schema, props.arrDepth), props.nullable);
+  }
+
+  #fieldRef(props: ReturnType<ConstantField["getProps"]>): JsonSchema {
+    if (props.isMap) {
+      const [valueRef, valueArrDepth] = getNonArrayModel(props.of as Cls | Cls[]);
+      return {
+        type: "object",
+        additionalProperties: JsonSchemaBuilder.#arrayed(this.#modelRef(valueRef as Cls), valueArrDepth),
+      };
+    }
+    return this.#modelRef(props.modelRef as Cls);
+  }
+
+  #enum(refName: string): JsonSchema {
+    const enumRef = ConstantRegistry.enum.get(refName);
+    if (!enumRef) return { type: "string", "x-akan-enum": refName };
+    return JsonSchemaBuilder.#inlineEnum([...enumRef.values]);
+  }
+
+  static primitive(refName: string): JsonSchema {
+    switch (refName) {
+      case "Boolean":
+        return { type: "boolean" };
+      case "Date":
+        return { type: "string", format: "date-time" };
+      case "Float":
+        return { type: "number" };
+      case "ID":
+        return { type: "string", pattern: "^[0-9a-fA-F]{24}$" };
+      case "Int":
+        return { type: "integer" };
+      case "Upload":
+        return { type: "string", format: "binary" };
+      case "Any":
+        return {};
+      default:
+        return { type: "string" };
+    }
+  }
+
+  static #inlineEnum(values: unknown[]): JsonSchema {
+    return {
+      type: values.every((value) => typeof value === "number") ? "number" : "string",
+      enum: values,
+    };
+  }
+
+  static #arrayed(schema: JsonSchema, arrDepth: number): JsonSchema {
+    let current = schema;
+    for (let idx = 0; idx < arrDepth; idx++) current = { type: "array", items: current };
+    return current;
+  }
+
+  static #nullable(schema: JsonSchema, nullable: boolean): JsonSchema {
+    return nullable ? { anyOf: [schema, { type: "null" }] } : schema;
+  }
+}

package/signal/schema/index.ts

@@ -0,0 +1 @@
+export * from "./JsonSchemaBuilder";

package/signal/signalContext.ts

@@ -16,18 +16,24 @@ import {
 } from "akanjs/constant";
 import type { Adaptor, AdaptorCls, DatabaseService, InjectRegistry, LiveRegistry } from "akanjs/service";
 import type { Internal, InternalCls, InternalInfo, MiddlewareCls } from ".";
-import type { EndpointInfo } from "./endpointInfo";
+import type { EndpointInfo, EndpointType } from "./endpointInfo";
 import { Exception } from "./exception";
+import type { Guard, GuardCls } from "./guard";
+
+import { Msg } from "./mcp/Msg";
 import { isTraceEnabled, runWithTrace, SignalTrace, traceSpan } from "./trace";
 
 export type SignalTransportType = "http" | "websocket";
 
+const httpEndpointTypes = new Set<EndpointType>(["query", "mutation", "prompt"]);
+
 interface WebSocketRequest {
   ws: Bun.ServerWebSocket<unknown>;
   data: unknown[];
   eventType: WebSocketEventType;
 }
 type RuntimeRecord = Record<string, unknown>;
+type MiddlewareHandler = (context: SignalContext, next: () => Promise<unknown>) => PromiseOrObject<unknown>;
 
 interface ExceptionLike {
   statusCode: number;
@@ -70,6 +76,7 @@ export class SignalContext<
       env,
       live,
       middleware,
+      ctx,
     }: {
       endpointInfo: EndpointInfo;
       adaptor: Adaptor;
@@ -77,12 +84,19 @@ 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.
+       */
+      ctx?: Ctx;
     },
   ) {
     this.key = key;
-    this.transport = endpointInfo.type === "query" || endpointInfo.type === "mutation" ? "http" : "websocket";
+    this.transport = httpEndpointTypes.has(endpointInfo.type) ? "http" : "websocket";
     this.endpointInfo = endpointInfo;
-    if (this.transport === "http") this.ctx = new HttpExecutionContext(reqOrWsReq as Bun.BunRequest) as Ctx;
+    if (ctx) this.ctx = ctx;
+    else if (this.transport === "http") this.ctx = new HttpExecutionContext(reqOrWsReq as Bun.BunRequest) as Ctx;
     else this.ctx = new WebSocketExecutionContext(reqOrWsReq as WebSocketRequest) as Ctx;
     this.adaptor = adaptor;
     this.#registry = registry;
@@ -114,13 +128,25 @@ export class SignalContext<
     }
     return this;
   }
+  /**
+   * Guards read everything from the context they are handed and are already required to be side-effect free and
+   * safe to re-run — `SignalResolver.revalidateWsRooms` re-runs them outside of any request — so one instance per
+   * class serves every call instead of one per guard per request.
+   */
+  static #guards = new WeakMap<GuardCls, Guard>();
+  static #getGuard(GuardCls: GuardCls): Guard {
+    const cached = SignalContext.#guards.get(GuardCls);
+    if (cached) return cached;
+    const guard = new GuardCls();
+    SignalContext.#guards.set(GuardCls, guard);
+    return guard;
+  }
   async #checkGuards() {
     const guards = this.endpointInfo.signalOption.guards ?? [];
     if (guards.length === 0) return;
     await Promise.all(
       guards.map(async (GuardCls) => {
-        const guard = new GuardCls();
-        const canPass = await guard.canPass(this);
+        const canPass = await SignalContext.#getGuard(GuardCls).canPass(this);
         if (!canPass) throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
       }),
     );
@@ -138,6 +164,32 @@ export class SignalContext<
       return false;
     }
   }
+  /**
+   * 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.
+   */
+  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) {
+            if (!(await SignalContext.#getGuard(GuardCls).canPass(this)))
+              throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
+          }
+        },
+        { endpointMiddlewares: false },
+      )();
+      return true;
+    } catch {
+      return false;
+    }
+  }
   #withMiddleware(
     coreExec: () => Promise<unknown>,
     { endpointMiddlewares = true }: { endpointMiddlewares?: boolean } = {},
@@ -151,12 +203,34 @@ export class SignalContext<
     for (let i = middlewares.length - 1; i >= 0; i--) {
       const MiddlewareCls = middlewares[i];
       if (!MiddlewareCls) continue;
-      const middleware = new MiddlewareCls();
       const currentNext = next;
-      next = async () => await (await middleware.use(this.getEnv()))(this, currentNext);
+      next = async () =>
+        await (await SignalContext.#getMiddlewareHandler(MiddlewareCls, this.getEnv()))(this, currentNext);
     }
     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 #middlewareHandlers = new WeakMap<MiddlewareCls, WeakMap<object, Promise<MiddlewareHandler>>>();
+  static #getMiddlewareHandler(MiddlewareCls: MiddlewareCls, env: BaseEnv): Promise<MiddlewareHandler> {
+    const byEnv =
+      SignalContext.#middlewareHandlers.get(MiddlewareCls) ?? new WeakMap<object, Promise<MiddlewareHandler>>();
+    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);
+        throw error;
+      },
+    );
+    byEnv.set(env, handler);
+    return handler;
+  }
   async exec() {
     if (!this.trace) return await this.#exec();
     return await runWithTrace(this.trace, async () => {
@@ -190,9 +264,11 @@ export class SignalContext<
       );
     };
     const next = this.#withMiddleware(coreExec);
-    const result = this.trace ? await traceSpan("execChain", () => next()) : await next();
+    const raw = this.trace ? await traceSpan("execChain", () => next()) : await next();
     if (this.endpointInfo.type === "pubsub") return;
-    if (result instanceof Response) return result;
+    if (raw instanceof Response) return raw;
+
+    const result = this.endpointInfo.type === "prompt" ? Msg.normalize(raw) : raw;
     if (!this.trace) {
       const resolved = await SignalContext.resolveReturn(result, {
         signalContext: this,