akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/service/predefinedAdaptor/sql/RawDocumentTable.ts

@@ -0,0 +1,200 @@
+import {
+  type AkanSqlClient,
+  type QueryLeafOps,
+  REF_NAME_RE,
+  RESERVED_RE,
+  type SqlDialect,
+  type SqlFrag,
+  type SqliteDocumentRow,
+  type TransferRow,
+} from "./types";
+import { assertStorableJson, BASE_COLUMN_LEAF, decodeDateValue, isPlainObject, jsonStr, quoteIdent } from "./values";
+
+export interface RawFilterOperators {
+  $ne?: unknown;
+  $in?: unknown[];
+  $nin?: unknown[];
+  $exists?: boolean;
+  $gt?: unknown;
+  $gte?: unknown;
+  $lt?: unknown;
+  $lte?: unknown;
+}
+
+/** Dot paths into `_doc`, or a base column, each to a value or to `RawFilterOperators` over it. */
+export type RawFilter = Record<string, unknown>;
+
+export interface RawFindOptions {
+  /** Only rows whose id sorts after this one: rows come in id order, so a page resumes where the last one ended. */
+  after?: string;
+  limit?: number;
+  /** Removed rows are read too unless this is `false`. */
+  withRemoved?: boolean;
+  /** Holds the rows read until the transaction ends; SQLite's one writer already does. */
+  lock?: boolean;
+}
+
+/**
+ * A table read and written as stored rows, beneath its model: a field the model no longer declares, or a table no model
+ * owns any more, stays reachable. Writes run no hook and derive nothing.
+ */
+export class RawDocumentTable {
+  static readonly #baseColumns = new Set(["id", "createdAt", "updatedAt", "removedAt"]);
+  static readonly #columns = `"id", "createdAt", "updatedAt", "removedAt", "_doc"`;
+  readonly name: string;
+  readonly #connection: () => AkanSqlClient;
+  readonly #dialect: SqlDialect;
+  #exists: boolean | undefined;
+
+  constructor(name: string, connection: () => AkanSqlClient, dialect: SqlDialect) {
+    if (!REF_NAME_RE.test(name) || RESERVED_RE.test(name)) throw new Error(`"${name}" names no model table`);
+    this.name = name;
+    this.#connection = connection;
+    this.#dialect = dialect;
+  }
+
+  async exists() {
+    if (this.#exists) return true;
+    const isPostgres = this.#dialect.name === "postgres";
+    const row = await this.#connection()
+      .prepare(
+        isPostgres
+          ? `SELECT to_regclass(?) IS NOT NULL AS "found"`
+          : `SELECT COUNT(*) AS "found" FROM sqlite_master WHERE "type" = 'table' AND "name" = ?`,
+      )
+      .get<{ found: unknown }>(isPostgres ? quoteIdent(this.name) : this.name);
+    this.#exists = !!Number(row?.found ?? 0);
+    return this.#exists;
+  }
+
+  async find(filter?: RawFilter, options: RawFindOptions = {}) {
+    if (!(await this.exists())) return [];
+    const where = this.#where(filter, options);
+    const limit = options.limit === undefined ? "" : ` LIMIT ${Math.max(0, Math.trunc(options.limit))}`;
+    const rows = await this.#connection()
+      .prepare(
+        `SELECT ${RawDocumentTable.#columns} FROM ${quoteIdent(this.name)} WHERE ${where.sql} ORDER BY "id"${limit}${this.#forUpdate(options.lock)}`,
+      )
+      .all<SqliteDocumentRow>(...where.params);
+    return rows.map(RawDocumentTable.#toRow);
+  }
+
+  async count(filter?: RawFilter, options: Omit<RawFindOptions, "limit"> = {}) {
+    if (!(await this.exists())) return 0;
+    const where = this.#where(filter, options);
+    const row = await this.#connection()
+      .prepare(`SELECT COUNT(*) AS "count" FROM ${quoteIdent(this.name)} WHERE ${where.sql}`)
+      .get<{ count: unknown }>(...where.params);
+    return Number(row?.count ?? 0);
+  }
+
+  async get(id: string, { lock = false }: Pick<RawFindOptions, "lock"> = {}) {
+    if (!(await this.exists())) return null;
+    const row = await this.#connection()
+      .prepare(
+        `SELECT ${RawDocumentTable.#columns} FROM ${quoteIdent(this.name)} WHERE "id" = ?${this.#forUpdate(lock)}`,
+      )
+      .get<SqliteDocumentRow>(id);
+    return row ? RawDocumentTable.#toRow(row) : null;
+  }
+
+  async insert(row: TransferRow) {
+    await this.#assertExists();
+    await this.#connection()
+      .prepare(
+        `INSERT INTO ${quoteIdent(this.name)} (${RawDocumentTable.#columns}) VALUES (?, ?, ?, ?, ${this.#dialect.docValuePlaceholder()})`,
+      )
+      .run(row.id, row.createdAt, row.updatedAt, row.removedAt, this.#json(row._doc));
+  }
+
+  async write(id: string, { _doc, removedAt }: Pick<TransferRow, "_doc" | "removedAt">) {
+    await this.#assertExists();
+    const result = await this.#connection()
+      .prepare(
+        `UPDATE ${quoteIdent(this.name)} SET "_doc" = ${this.#dialect.docValuePlaceholder()}, "removedAt" = ? WHERE "id" = ?`,
+      )
+      .run(this.#json(_doc), removedAt, id);
+    return this.#dialect.affectedRows(result) > 0;
+  }
+
+  async delete(id: string) {
+    await this.#assertExists();
+    const result = await this.#connection()
+      .prepare(`DELETE FROM ${quoteIdent(this.name)} WHERE "id" = ?`)
+      .run(id);
+    return this.#dialect.affectedRows(result) > 0;
+  }
+
+  #forUpdate(lock = false) {
+    return lock && this.#dialect.name === "postgres" ? " FOR UPDATE" : "";
+  }
+
+  async #assertExists() {
+    if (!(await this.exists())) throw new Error(`Table "${this.name}" does not exist`);
+  }
+
+  #json(doc: Record<string, unknown>) {
+    return assertStorableJson(jsonStr(doc), this.name);
+  }
+
+  #where(filter: RawFilter = {}, { after, withRemoved = true }: RawFindOptions): SqlFrag {
+    const parts = Object.entries(filter).flatMap(([path, value]) => this.#leaves(path, value));
+    if (after !== undefined) parts.push({ sql: `"id" > ?`, params: [after] });
+    if (!withRemoved) parts.push({ sql: `"removedAt" IS NULL`, params: [] });
+    if (!parts.length) return { sql: "1 = 1", params: [] };
+    return { sql: parts.map((part) => `(${part.sql})`).join(" AND "), params: parts.flatMap((part) => part.params) };
+  }
+
+  #leaves(path: string, value: unknown): SqlFrag[] {
+    RawDocumentTable.#assertPath(path);
+    if (value === undefined) throw new Error(`Filter value for "${path}" is undefined`);
+    const leaf: QueryLeafOps = RawDocumentTable.#baseColumns.has(path) ? BASE_COLUMN_LEAF : this.#dialect;
+    if (!isPlainObject(value)) {
+      if (Array.isArray(value))
+        throw new Error(`Filter "${path}" compares an array; match it with $in or by its items`);
+      return [leaf.eq(path, value)];
+    }
+    const operators = Object.entries(value);
+    if (!operators.length || operators.some(([key]) => !key.startsWith("$")))
+      throw new Error(`Filter "${path}" compares an object; match its leaves by their own paths`);
+    return operators.map(([operator, operand]) => {
+      switch (operator) {
+        case "$ne":
+          return leaf.ne(path, operand);
+        case "$in":
+        case "$nin": {
+          if (!Array.isArray(operand)) throw new Error(`Filter "${path}" ${operator} takes an array`);
+          if (!operand.length) return { sql: operator === "$in" ? "0 = 1" : "1 = 1", params: [] };
+          return operator === "$in" ? leaf.inList(path, operand) : leaf.notInList(path, operand);
+        }
+        case "$exists":
+          return operand ? leaf.exists(path) : leaf.missing(path);
+        case "$gt":
+        case "$gte":
+        case "$lt":
+        case "$lte":
+          return leaf.compare(path, operator.slice(1) as "gt" | "gte" | "lt" | "lte", operand);
+        default:
+          throw new Error(`Unknown filter operator "${operator}" on "${path}"`);
+      }
+    });
+  }
+
+  static #assertPath(path: string) {
+    const segments = path.split(".");
+    
+    if (segments.some((segment) => !/^[\w$-]+$/.test(segment) || /^-?\d+$/.test(segment)))
+      throw new Error(`Filter path "${path}" must be dot-separated names, without array indexes`);
+  }
+
+  static #toRow(row: SqliteDocumentRow): TransferRow {
+    const epoch = (value: unknown) => decodeDateValue(value)?.valueOf() ?? null;
+    return {
+      id: row.id,
+      createdAt: epoch(row.createdAt) ?? 0,
+      updatedAt: epoch(row.updatedAt) ?? 0,
+      removedAt: epoch(row.removedAt),
+      _doc: (typeof row._doc === "string" ? JSON.parse(row._doc) : row._doc) as Record<string, unknown>,
+    };
+  }
+}

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -586,11 +586,11 @@ export class SqlDocumentStore {
         const values = Array.isArray(doc[key]) ? doc[key] : [doc[key]];
         const fieldEnum = props.enum as { has: (value: unknown) => boolean } | undefined;
         const invalidValue = fieldEnum ? values.find((value: unknown) => !fieldEnum.has(value)) : undefined;
-        if (invalidValue !== undefined) throw new Error(`Invalid enum value for ${key}: ${invalidValue}`);
+        if (invalidValue !== undefined) throw SqlDocumentStore.#invalidField(key, this.table);
       }
       const validate = props.validate as ((value: unknown, doc: MutableDocumentRecord) => boolean) | undefined;
       if (validate && doc[key] !== undefined && doc[key] !== null && !validate(doc[key], doc)) {
-        throw new Error(`Invalid field value: ${key}`);
+        throw SqlDocumentStore.#invalidField(key, this.table);
       }
     }
     return { ...data, ...doc };
@@ -868,6 +868,10 @@ export class SqlDocumentStore {
     );
   }
 
+  static #invalidField(key: string, table: string) {
+    return new Err.BadRequest("base.error.invalidField", { field: key }, { details: { model: table } });
+  }
+
   #assertImmutableUnchanged(prepared: DocumentRecord, originalData: DocumentRecord) {
     this.#immutableKeys ??= Object.entries(this.database.doc[FIELD_META] as unknown as FieldMap)
       .filter(([, fieldMeta]) => fieldMeta.getProps().immutable)

package/service/predefinedAdaptor/sql/SqliteInsightSession.ts

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { MigrationTables } from "./MigrationTables";
 import type { InsightSession } from "./types";
 import { quoteIdent } from "./values";
 
@@ -14,6 +15,8 @@ import { quoteIdent } from "./values";
 export class SqliteInsightSession implements InsightSession {
   
   static readonly #unnameable = ["sqlite_dbpage", "sqlite_stat3", "sqlite_stat4"];
+  
+  static readonly #ledger = [MigrationTables.run, MigrationTables.change];
   static readonly #documentColumn = "_doc";
 
   readonly #db: Database;
@@ -22,7 +25,7 @@ export class SqliteInsightSession implements InsightSession {
 
   private constructor(db: Database, source: string, cleanup: () => Promise<void>) {
     this.#db = db;
-    this.#hidden = [source, ...SqliteInsightSession.#unnameable];
+    this.#hidden = [source, ...SqliteInsightSession.#unnameable, ...SqliteInsightSession.#ledger];
     this.#cleanup = cleanup;
   }
 

package/service/predefinedAdaptor/sql/dialect/postgres.ts

@@ -177,7 +177,6 @@ export class PostgresDialect implements SqlDialect {
     const textAt = `(${this.docColumn()}) #>> ${p}`;
     const arr = `COALESCE(NULLIF(${jsonbAt}, 'null'::jsonb), '[]'::jsonb)`;
     const set = (next: string) => `${PostgresDialect.#setFunction}(${acc}, ${p}, ${next})`;
-    
     switch (op) {
       case "set":
         return { sql: set("?::text::jsonb"), params: [jsonStr(value)] };

package/service/predefinedAdaptor/sql/dialect/sqlite.ts

@@ -98,7 +98,6 @@ export class SqliteDialect implements SqlDialect {
     
     const cur = `json_extract(${this.docColumn()}, ${p})`;
     const arr = `COALESCE(${cur}, json('[]'))`;
-    
     switch (op) {
       case "set":
         return { sql: `json_set(${acc}, ${p}, json(?))`, params: [jsonStr(value)] };

package/service/predefinedAdaptor/sql/types.ts

@@ -115,6 +115,7 @@ export interface InsightSession {
 }
 
 export interface DatabaseAdaptor {
+  readonly dialect?: SqlDialect;
   getConnection(): AkanSqlClient;
   getStore(constant: ConstantModel, database: DatabaseModel, schema: DocumentSchema): DocumentStore;
   /** Every model table this process has opened a store for. */
@@ -144,7 +145,8 @@ export interface TransactionContext {
 }
 
 export const BASE_COLUMNS = baseDocumentColumns;
-export const RESERVED_RE = /^sqlite_|^_akan_meta$|^search_doc$|^search_fts$/i;
+export const RESERVED_RE =
+  /^sqlite_|^_akan_meta$|^_akan_migration_run$|^_akan_migration_change$|^search_doc$|^search_fts$/i;
 export const REF_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 export const toSafeRefName = (value: string) => value.replace(/[^A-Za-z0-9_]+/g, "_").replace(/_+/g, "_");
 export type DocumentRecord = Record<string, unknown>;

package/service/predefinedAdaptor/storage.adaptor.ts

@@ -1,4 +1,5 @@
 import { renameSync } from "node:fs";
+import { isAbsolute, parse, relative, resolve, sep } from "node:path";
 import { getApiPrefix, getEnv } from "akanjs/base";
 import { adapt } from "../adapt";
 
@@ -50,6 +51,13 @@ export interface StorageAdaptor {
   copyData(request: CopyRequest): Promise<string>;
   deleteData(url: string): Promise<boolean>;
   deleteDataByPath(path: string): Promise<boolean>;
+  /**
+   * Absolute path of a stored key on this machine's disk. `null` means the key is refused (rooted, NUL, or outside
+   * its root): reject the request, never fall back to `readData` for it. The method is absent on an adaptor that
+   * keeps no local files. Without `access`, a `private/` key resolves under the private root, so a caller serving
+   * an untrusted key passes `access: "public"`.
+   */
+  resolveLocalPath?(path: string, access?: "public" | "private"): string | null;
 }
 
 export interface BlobStorageOptions {
@@ -88,6 +96,17 @@ export class BlobStorage
   #resolveFilePath(path: string) {
     return path.startsWith("private/") ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
   }
+  resolveLocalPath(path: string, access?: "public" | "private") {
+    
+    if (path.includes("\0") || parse(path).root) return null;
+    const isPrivate = access ? access === "private" : path.startsWith("private/");
+    const base = resolve(isPrivate ? this.privateRoot : this.root);
+    const target = resolve(base, path);
+    
+    const within = relative(base, target);
+    if (!within || within === ".." || within.startsWith(`..${sep}`) || isAbsolute(within)) return null;
+    return target;
+  }
   async readData(path: string): Promise<ReadableStream> {
     const filePath = this.#resolveFilePath(path);
     return Bun.file(filePath).stream();

package/signal/endpointCache.ts

@@ -1,19 +1,25 @@
-import { type CacheAdaptor, CacheAdaptorRole } from "akanjs/service";
+import { type CacheAdaptor, CacheAdaptorRole, EndpointCacheKeys } from "akanjs/service";
 import dayjs from "dayjs";
+import type { EndpointInfo } from "./endpointInfo";
 import type { SignalContext } from "./signalContext";
 import { TaggedJson } from "./TaggedJson";
 import { traceCache } from "./trace";
 
 export class EndpointCache {
-  static #topic = "cache";
   static #refused = new Set<string>();
 
+  static declares(endpointInfo: EndpointInfo): boolean {
+    const ttl = endpointInfo.signalOption.cache;
+    return !!ttl && Number.isFinite(ttl) && ttl > 0;
+  }
+
   static async through(context: SignalContext, run: () => Promise<unknown>) {
     const ttl = context.endpointInfo.signalOption.cache;
-    if (!ttl || !Number.isFinite(ttl) || ttl <= 0) return await run();
+    if (!ttl || !EndpointCache.declares(context.endpointInfo)) return await run();
     if (!EndpointCache.#cacheable(context)) return await run();
     const cache = context.getAdaptor(CacheAdaptorRole) as unknown as CacheAdaptor;
-    const key = `${context.key}:${JSON.stringify(context.args)}`;
+    const key = await EndpointCache.#key(context, cache);
+    if (key === undefined) return await run();
     const cached = await EndpointCache.#read(context, cache, key);
     if (cached !== undefined) {
       traceCache(true);
@@ -36,15 +42,23 @@ export class EndpointCache {
     return false;
   }
   
+  static async #key(context: SignalContext, cache: CacheAdaptor) {
+    try {
+      return await EndpointCacheKeys.entryKey(cache, context.key, context.args);
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache read failed for ${context.key}: ${String(error)}`);
+      return undefined;
+    }
+  }
   static async #read(context: SignalContext, cache: CacheAdaptor, key: string) {
     try {
-      const cached = await cache.get<string>(EndpointCache.#topic, key);
+      const cached = await cache.get<string>(EndpointCacheKeys.topic, key);
       if (cached == null) return undefined;
       const { returnRef, arrDepth } = context.endpointInfo.returns;
       return TaggedJson.parse(cached, { ref: returnRef, arrDepth });
     } catch (error) {
       context.adaptor.logger.warn(`Cache read failed for ${context.key}: ${String(error)}`);
-      await cache.delete(EndpointCache.#topic, key).catch(() => undefined);
+      await cache.delete(EndpointCacheKeys.topic, key).catch(() => undefined);
       return undefined;
     }
   }
@@ -53,7 +67,9 @@ export class EndpointCache {
       const serialized = TaggedJson.stringify(result);
       
       if (serialized === undefined) return;
-      await cache.set(EndpointCache.#topic, key, serialized, { expireAt: dayjs().add(ttl, "millisecond") });
+      
+      const lifeMs = Math.min(ttl, EndpointCacheKeys.generationTtlMs);
+      await cache.set(EndpointCacheKeys.topic, key, serialized, { expireAt: dayjs().add(lifeMs, "millisecond") });
     } catch (error) {
       context.adaptor.logger.warn(`Cache write failed for ${context.key}: ${String(error)}`);
     }

package/signal/endpointErrorContract.ts

@@ -0,0 +1,37 @@
+import type { Adaptor } from "akanjs/service";
+
+import type { EndpointInfo } from "./endpointInfo";
+import type { EndpointErrors } from "./types";
+
+export class EndpointErrorContract {
+  static readonly #warned = new Set<string>();
+
+  /** Refuses a declaration no response could carry: a status outside 400–599, or a key that is not an error key. */
+  static assertDeclared(errors: EndpointErrors | undefined) {
+    if (!errors) return;
+    for (const [status, keys] of Object.entries(errors) as [string, EndpointErrors[number]][]) {
+      const code = Number(status);
+      if (!Number.isInteger(code) || code < 400 || code > 599)
+        throw new Error(`errors declares status ${status}: an error answers with a 400–599 status`);
+      for (const key of keys)
+        if (!/^[^.]+\.error\.[^.]+$/.test(key))
+          throw new Error(`errors declares "${key}" under ${status}: an error key reads <module>.error.<key>`);
+    }
+  }
+
+  static keysOf(errors: EndpointErrors | undefined): string[] {
+    return errors ? Object.values(errors).flat() : [];
+  }
+
+  static checkThrown(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, thrownKey: string) {
+    const { errors } = endpointInfo.signalOption;
+    if (!errors || process.env.NODE_ENV === "production" || thrownKey.startsWith("base.error.")) return;
+    if (EndpointErrorContract.keysOf(errors).includes(thrownKey)) return;
+    const warnedKey = `${key}\0${thrownKey}`;
+    if (EndpointErrorContract.#warned.has(warnedKey)) return;
+    EndpointErrorContract.#warned.add(warnedKey);
+    endpoint.logger.warn(
+      `"${key}" threw ${thrownKey}, which its \`errors\` declaration leaves out: OpenAPI and the MCP catalogue do not publish it.`,
+    );
+  }
+}

package/signal/endpointIdempotency.ts

@@ -25,15 +25,17 @@ export class EndpointIdempotency {
   static readonly #topic = "idempotency";
   static readonly #tag = "\u0000akan";
 
+  static applies(context: SignalContext): boolean {
+    return context.endpointInfo.type === "mutation" && context.transport === "http" && context.origin === "http";
+  }
+
   /** A Response when the call is kept or replayed; otherwise the handler's own result, which the caller answers. */
   static async through(
     context: SignalContext,
     run: () => Promise<unknown>,
     answer: (result: unknown) => Promise<unknown>,
   ) {
-    
-    if (context.endpointInfo.type !== "mutation" || context.transport !== "http" || context.origin !== "http")
-      return await run();
+    if (!EndpointIdempotency.applies(context)) return await run();
     const { req } = context.getHttpContext();
     const idempotencyKey = req.headers.get(EndpointIdempotency.header)?.trim();
     if (!idempotencyKey || idempotencyKey.length > 256) return await run();

package/signal/endpointInfo.ts

@@ -7,6 +7,7 @@ import {
   isEnum,
   type PromiseOrObject,
 } from "akanjs/base";
+import { trimSlashes } from "akanjs/common";
 import type {
   ConstantFieldType,
   ConstantFieldTypeInput,
@@ -18,6 +19,7 @@ import type {
   UploadableClientArg,
 } from "akanjs/constant";
 import type { ServiceModel } from "akanjs/service";
+import { EndpointErrorContract } from "./endpointErrorContract";
 import type { InternalArgCls } from "./internalArg";
 import type { ArgType, SignalOption, SrvMap } from "./types";
 
@@ -103,6 +105,7 @@ export class EndpointInfo<
   }
 
   constructor(type: ReqType, returnRef: Returns, signalOption: SignalOption<Returns, Nullable> = {}) {
+    EndpointErrorContract.assertDeclared(signalOption.errors);
     this.type = type;
     this.returns = EndpointInfo.getReturnInfo(returnRef, signalOption);
     this.signalOption = signalOption;
@@ -335,7 +338,7 @@ export class EndpointInfo<
     if (prefix === false || prefix === "") return "";
     const resolved = prefix ?? defaultPrefix;
     if (!resolved) return "";
-    const trimmed = resolved.trim().replace(/^\/+|\/+$/g, "");
+    const trimmed = trimSlashes(resolved.trim());
     return trimmed ? `/${trimmed}` : "";
   }
 }

package/signal/endpointRateLimit.ts

@@ -92,9 +92,13 @@ export class EndpointRateLimit {
   }
 
   /** `ip` runs before the request body is read; `account` after the middlewares resolved the caller. */
-  static async admit(context: SignalContext, phase: "ip" | "account") {
+  static admit(context: SignalContext, phase: "ip" | "account"): Promise<void> | undefined {
     const budget = EndpointRateLimit.budgetOf(context.key, context.endpointInfo);
-    if (!budget || budget.by !== phase) return;
+    if (!budget || budget.by !== phase) return undefined;
+    return EndpointRateLimit.#consume(context, phase, budget);
+  }
+
+  static async #consume(context: SignalContext, phase: "ip" | "account", budget: ResolvedBudget) {
     const caller =
       (phase === "account" ? EndpointRateLimit.#accountOf(context) : null) ?? EndpointRateLimit.#ipOf(context);
     const verdict = await EndpointRateLimit.#limiterOf(context).consume(`${context.key}:${caller}`, budget);

package/signal/exception.ts

@@ -60,7 +60,10 @@ export class Exception extends Error {
   };
 }
 
-/** Forwarded to the caller instead of generalized: an `Exception`, a dictionary `Err`, or a restored remote one. */
+/**
+ * Forwarded to the caller instead of generalized: an `Exception`, a dictionary `Err`, a `NoDocumentError`, or a restored
+ * remote one.
+ */
 export interface ExceptionLike {
   statusCode: number;
   toJSON: () => object;

package/signal/index.ts

@@ -6,6 +6,7 @@ export * from "./agentTurnStream";
 export * from "./base.signal";
 export { CrossSiteGuard, type CrossSiteOption } from "./CrossSiteGuard";
 export * from "./endpoint";
+export * from "./endpointErrorContract";
 export * from "./endpointInfo";
 export * from "./endpointRateLimit";
 export * from "./exception";

package/signal/mcp/McpDocument.ts

@@ -188,7 +188,7 @@ export class McpDocument {
     const outputSchema = this.#outputSchema(endpoint);
     return {
       name: key,
-      ...this.#catalogue.entryTexts(refName, key),
+      ...this.#withErrors(this.#catalogue.entryTexts(refName, key), endpoint),
       inputSchema: {
         type: "object",
         properties,
@@ -201,6 +201,21 @@ export class McpDocument {
     };
   }
 
+  #withErrors(texts: { title?: string; description?: string }, endpoint: SerializedEndpoint) {
+    const errors = Object.entries(endpoint.errors ?? {}) as [string, readonly string[]][];
+    if (!errors.length) return texts;
+    const listed = errors
+      .flatMap(([status, keys]) =>
+        keys.map((key) => {
+          const message = this.#options.resolveDescription?.(key);
+          return `${status} ${key}${message ? ` (${message})` : ""}`;
+        }),
+      )
+      .join(", ");
+    const line = `Errors it answers with on purpose: ${listed}.`;
+    return { ...texts, description: texts.description ? `${texts.description}\n${line}` : line };
+  }
+
   #outputSchema(endpoint: SerializedEndpoint) {
     if (this.#options.outputSchema === "none") return undefined;
 

package/signal/mcp/McpUriTemplate.ts

@@ -21,7 +21,7 @@ export class McpUriTemplate {
 
   static expand(template: string, args: Record<string, unknown>): string {
     const queryAt = template.indexOf("{?");
-    const path = (queryAt === -1 ? template : template.slice(0, queryAt)).replace(/\{([^}]+)\}/g, (_, name: string) =>
+    const path = (queryAt === -1 ? template : template.slice(0, queryAt)).replace(/\{([^{}]+)\}/g, (_, name: string) =>
       encodeURIComponent(String(args[name] ?? "")),
     );
     if (queryAt === -1) return path;