@zudojs/api 0.1.0 → 1.0.0

package/dist/api/executor/executor.core.js

@@ -1,62 +1,300 @@
+import { apiFailure, apiSuccess } from "../result/apiResult.type.js";
+import { resolveOperationTimeout } from "../operation/operation.type.js";
+import { APIError, APIInternalError, APITimeoutError, APIValidationError, createAPIError, ErrorCode, isAPIError, } from "../errors/index.js";
+import { MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, } from "../constants.js";
 /**
- * Error normalizer for converting unknown errors into Error instances.
+ * Error normalizer for converting unknown errors into APIError instances.
+ *
+ * APIErrors pass through untouched. Everything else is wrapped in an
+ * `APIInternalError` (`expose: false`) carrying a generic message; the
+ * original error is preserved on `cause` for logging.
+ *
+ * The wrapper's own message is deliberately *not* a copy of the original.
+ * `BaseError.toJSON()` in `@zudojs/errors` 0.1.0 emits `message`, `stack`
+ * and the serialized `cause` regardless of `expose`, so a transport doing
+ * `res.json(result.error)` would otherwise ship the raw driver message
+ * (connection strings, constraint names, file paths, tokens) to a client.
  */
 export function normalizeAPIError(error, operationName) {
-    if (error instanceof Error) {
+    if (isAPIError(error)) {
         return error;
     }
-    return new Error(`Unexpected non-error thrown in operation "${operationName}": ${String(error)}`);
+    const where = operationName !== undefined && operationName !== ""
+        ? `operation "${operationName}"`
+        : "an API operation";
+    const wrapped = error instanceof Error
+        ? new APIInternalError(`An unexpected internal error occurred in ${where}.`)
+        : new APIInternalError(`A non-error value (${describeValueType(error)}) was thrown in ${where}.`);
+    // `APIInternalError`'s subclass constructor forwards only
+    // `{ endpoint, method }`, so `cause` cannot be passed through it.
+    // `APIError` / `createAPIError` *do* accept `cause`, but constructing
+    // through them would lose the `APIInternalError` class identity that
+    // consumers match on. `cause` is a declared writable class field on
+    // `BaseError`, so assigning it after construction is equivalent for
+    // `toJSON()` and for `error.cause` reads; only the native `[[cause]]`
+    // slot differs.
+    wrapped.cause = error;
+    return wrapped;
+}
+function describeValueType(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    return typeof value;
+}
+function isStandardSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value["~standard"]
+            ?.validate === "function");
+}
+/**
+ * A schema result counts as a failure only when it carries at least one
+ * issue. Some adapters always populate `issues` and return an empty array
+ * on success; treating that as a failure produces a 422 with an empty
+ * issue list and no way to learn what was wrong.
+ */
+function hasIssues(result) {
+    return Array.isArray(result.issues) && result.issues.length > 0;
 }
 /**
  * Executes an API operation through its interceptor pipeline.
+ *
+ * Enforces the operation timeout, honors the context AbortSignal, and
+ * validates input and output when the operation's `input` / `output` is a
+ * Standard Schema.
  */
 export class APIExecutor {
     interceptors;
-    constructor(interceptors = []) {
+    exposeValidationMessages;
+    maxValidationIssues;
+    constructor(optionsOrInterceptors = {}) {
+        const options = Array.isArray(optionsOrInterceptors)
+            ? { interceptors: optionsOrInterceptors }
+            : optionsOrInterceptors;
+        const interceptors = options.interceptors ?? [];
+        if (interceptors.length > MAX_INTERCEPTORS) {
+            throw new RangeError(`Interceptor pipeline exceeds MAX_INTERCEPTORS (${MAX_INTERCEPTORS}).`);
+        }
+        const maxValidationIssues = options.maxValidationIssues ?? MAX_VALIDATION_ISSUES;
+        if (!Number.isInteger(maxValidationIssues) ||
+            maxValidationIssues < 1 ||
+            maxValidationIssues > MAX_VALIDATION_ISSUES) {
+            throw new RangeError(`maxValidationIssues must be an integer between 1 and ${MAX_VALIDATION_ISSUES}, received ${String(maxValidationIssues)}.`);
+        }
         this.interceptors = Object.freeze([...interceptors]);
+        this.exposeValidationMessages = options.exposeValidationMessages === true;
+        this.maxValidationIssues = maxValidationIssues;
     }
     /**
      * Executes an operation with the given input and context.
      */
     async execute(operation, input, context) {
-        const executionContext = {
-            operation,
-            input,
-            context,
-        };
-        const executeNext = async () => {
+        if (context.signal?.aborted) {
+            return apiFailure(abortedError(operation.name));
+        }
+        let effectiveInput = input;
+        if (isStandardSchema(operation.input)) {
             try {
-                const output = await operation.handler(input, context);
-                return { ok: true, data: output };
+                const validation = await operation.input["~standard"].validate(input);
+                if (hasIssues(validation)) {
+                    return apiFailure(new APIValidationError(`Invalid input for operation "${operation.name}".`, this.clientIssues(validation.issues)));
+                }
+                effectiveInput = validation.value;
             }
             catch (error) {
-                return {
-                    ok: false,
-                    error: normalizeAPIError(error, operation.name),
-                };
+                return apiFailure(normalizeAPIError(error, operation.name));
             }
+        }
+        const executionContext = {
+            operation,
+            input: effectiveInput,
+            context,
         };
-        return this.runPipeline(executionContext, executeNext);
+        // Reads `executionContext.input` at call time, so an interceptor that
+        // replaces the input before calling `next()` actually changes what the
+        // handler receives.
+        const executeHandler = () => this.invokeHandler(operation, executionContext.input, context);
+        try {
+            return await this.runPipeline(executionContext, executeHandler);
+        }
+        catch (error) {
+            return apiFailure(normalizeAPIError(error, operation.name));
+        }
+    }
+    /**
+     * Invokes the operation handler under its timeout and abort signal, and
+     * validates the handler's output when `operation.output` is a Standard
+     * Schema.
+     */
+    async invokeHandler(operation, input, context) {
+        if (context.signal?.aborted) {
+            return apiFailure(abortedError(operation.name));
+        }
+        const timeoutMs = resolveOperationTimeout(operation);
+        let output;
+        try {
+            output = await withDeadline(operation.handler(input, context), timeoutMs, operation.name, context.signal);
+        }
+        catch (error) {
+            return apiFailure(normalizeAPIError(error, operation.name));
+        }
+        return this.validateOutput(operation, output);
+    }
+    /**
+     * Validates handler output against `operation.output`.
+     *
+     * A response that does not match its declared schema is a server bug,
+     * not a client mistake, so failures surface as an `APIInternalError`
+     * (500, `expose: false`) naming only the failing paths — never the
+     * offending values, which are exactly the fields (password hashes,
+     * internal audit columns) that should not reach a client.
+     */
+    async validateOutput(operation, output) {
+        if (!isStandardSchema(operation.output)) {
+            return apiSuccess(output);
+        }
+        let validation;
+        try {
+            validation = await operation.output["~standard"].validate(output);
+        }
+        catch (error) {
+            return apiFailure(normalizeAPIError(error, operation.name));
+        }
+        if (hasIssues(validation)) {
+            const paths = validation.issues
+                .slice(0, this.maxValidationIssues)
+                .map(formatIssuePath)
+                .join(", ");
+            return apiFailure(new APIInternalError(`Invalid output for operation "${operation.name}" at: ${paths}.`));
+        }
+        return apiSuccess(validation.value);
     }
     /**
-     * Runs the interceptor pipeline.
+     * Converts schema issues into the capped, redacted list carried on the
+     * client-facing `APIValidationError`.
      */
-    async runPipeline(context, next) {
+    clientIssues(issues) {
+        const limit = this.maxValidationIssues;
+        const shown = issues.slice(0, limit).map((issue) => this.exposeValidationMessages
+            ? truncate(issue.message, MAX_VALIDATION_ISSUE_LENGTH)
+            : `${formatIssuePath(issue)}: invalid`);
+        const omitted = issues.length - shown.length;
+        if (omitted > 0) {
+            shown.push(`… and ${omitted} more issue(s) omitted.`);
+        }
+        return shown;
+    }
+    /**
+     * Runs the interceptor pipeline (Koa-style dispatch).
+     *
+     * Each interceptor's `next()` may be awaited at most once; a second
+     * call rejects instead of silently re-executing the handler while
+     * bypassing downstream interceptors.
+     *
+     * `context.result` is assigned as each level resolves, so an
+     * interceptor reading it after `await next()` sees exactly what the
+     * level below returned — including when a downstream interceptor
+     * short-circuits without calling `next()`.
+     */
+    runPipeline(context, terminal) {
         const interceptors = this.interceptors;
-        let index = 0;
-        const runNext = async () => {
+        let lastDispatched = -1;
+        const dispatch = async (index) => {
+            if (index <= lastDispatched) {
+                throw new APIInternalError("next() called multiple times in interceptor pipeline.");
+            }
+            lastDispatched = index;
             if (index >= interceptors.length) {
-                return next();
+                const result = await terminal();
+                context.result = result;
+                return result;
             }
             const interceptor = interceptors[index];
-            index += 1;
-            if (!interceptor) {
-                return next();
-            }
-            return interceptor.intercept(context, runNext);
+            const result = await interceptor.intercept(context, () => dispatch(index + 1));
+            context.result = result;
+            return result;
         };
-        const result = await runNext();
-        return result;
+        return dispatch(0);
     }
 }
+// ─── Internal helpers ─────────────────────────────────────────────────────
+function truncate(value, max) {
+    const text = typeof value === "string" ? value : String(value);
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Renders a Standard Schema issue path as a dotted string. Path segments
+ * are field names, never submitted values, so they are safe to expose.
+ */
+function formatIssuePath(issue) {
+    const path = issue.path;
+    if (path === undefined || path.length === 0) {
+        return "(root)";
+    }
+    return path
+        .map((segment) => {
+        const key = typeof segment === "object" && segment !== null && "key" in segment
+            ? segment.key
+            : segment;
+        return truncate(String(key), 64);
+    })
+        .join(".");
+}
+/**
+ * Error for an execution cancelled by the caller's `AbortSignal`.
+ *
+ * Carries `ErrorCode.OPERATION_CANCELLED` — branch on that, not on the
+ * status code. `statusCode` is 499, an nginx convention ("Client Closed
+ * Request") rather than an IANA status; this package is
+ * transport-agnostic, so each adapter should map the *code* onto whatever
+ * its protocol calls "cancelled" (gRPC `CANCELLED`, a dropped queue
+ * message, a non-zero CLI exit) rather than passing 499 to the wire.
+ */
+function abortedError(operationName) {
+    return createAPIError(`Operation "${operationName}" was aborted.`, {
+        code: ErrorCode.OPERATION_CANCELLED,
+        statusCode: 499,
+        expose: true,
+    });
+}
+/**
+ * Awaits a handler promise, rejecting when the timeout elapses or the
+ * abort signal fires. The handler itself keeps running (promises are not
+ * cancellable), but the caller stops waiting and resources are released.
+ *
+ * `timeoutMs` is always a positive integer here — `defineOperation`
+ * rejects anything else and `resolveOperationTimeout` substitutes the
+ * default for hand-rolled operations — so the deadline can never be
+ * silently disabled.
+ */
+function withDeadline(promise, timeoutMs, operationName, signal) {
+    return new Promise((resolve, reject) => {
+        let timer;
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(abortedError(operationName));
+        };
+        timer = setTimeout(() => {
+            cleanup();
+            reject(new APITimeoutError(timeoutMs));
+        }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
 //# sourceMappingURL=executor.core.js.map

package/dist/api/executor/index.d.ts

@@ -1,3 +1,4 @@
 export { APIExecutor } from "./executor.core.js";
 export { normalizeAPIError } from "./executor.core.js";
+export type { APIExecutorOptions } from "./executor.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/handler/handler.type.d.ts

@@ -2,8 +2,11 @@ import type { APIContext } from "../context/context.type.js";
 /**
  * Handler for an API operation.
  *
- * Receives validated input and the execution context,
- * and returns the operation output.
+ * Receives the operation input and the execution context, and returns
+ * the operation output. Input is validated by the executor only when the
+ * operation's `input` is a Standard Schema (https://standardschema.dev,
+ * implemented by Zod, Valibot, ArkType, …); otherwise it is passed
+ * through as-is and the handler must validate it itself.
  */
 export type APIHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: APIContext) => Promise<TOutput>;
 //# sourceMappingURL=handler.type.d.ts.map

package/dist/api/interceptors/interceptor.type.d.ts

@@ -6,8 +6,25 @@ import type { APIOperation } from "../operation/operation.type.js";
  */
 export interface APIExecutionContext<TInput = unknown, TOutput = unknown> {
     readonly operation: APIOperation<TInput, TOutput>;
-    readonly input: TInput;
+    /**
+     * The input the handler will receive.
+     *
+     * Writable on purpose: an interceptor may replace it before calling
+     * `next()` (to sanitize, scope to a tenant, or apply a default) and the
+     * handler receives the replacement. The executor reads this field at
+     * handler-invocation time, so a replacement made by any interceptor in
+     * the chain takes effect.
+     */
+    input: TInput;
     readonly context: APIContext;
+    /**
+     * The result produced by the level below this one.
+     *
+     * The executor assigns it as each pipeline level resolves, so after
+     * `await next()` this holds exactly what `next()` returned — including
+     * when a downstream interceptor short-circuits without running the
+     * handler. It is `undefined` before `next()` has resolved.
+     */
     readonly result?: APIResult<TOutput>;
 }
 /**

package/dist/api/operation/operation.type.d.ts

@@ -7,6 +7,10 @@ export interface APIOperationMetadata {
     readonly tags?: readonly string[];
     readonly deprecated?: boolean;
     readonly version?: string;
+    /**
+     * Operation timeout in milliseconds. Superseded by
+     * {@link APIOperation.timeout} when both are present.
+     */
     readonly timeout?: number;
     readonly idempotent?: boolean;
 }
@@ -18,25 +22,111 @@ export interface APIOperationMetadata {
  */
 export interface APIOperation<TInput = unknown, TOutput = unknown> {
     readonly name: string;
+    /**
+     * Input schema. When this is a Standard Schema
+     * (https://standardschema.dev), the executor validates input against it
+     * before invoking the handler; other values are documentation-only.
+     */
     readonly input?: unknown;
+    /**
+     * Output schema. When this is a Standard Schema
+     * (https://standardschema.dev), the executor validates the handler's
+     * return value against it and returns the validated (possibly
+     * transformed) value as the result data; a handler returning the wrong
+     * shape fails with an `APIInternalError` (`expose: false`) rather than
+     * leaking through to the transport. Other values are
+     * documentation-only.
+     */
     readonly output?: unknown;
     readonly handler: APIHandler<TInput, TOutput>;
     readonly metadata?: APIOperationMetadata;
+    /**
+     * Operation timeout in milliseconds. Must be a positive, finite integer
+     * no greater than {@link MAX_OPERATION_TIMEOUT}. There is no way to
+     * disable the deadline: `0` and negative values are rejected by
+     * {@link defineOperation} rather than silently running unbounded.
+     */
     readonly timeout?: number;
 }
+/**
+ * An operation of any input/output type.
+ *
+ * `APIOperation<unknown, unknown>` is *not* a supertype of a typed
+ * operation — a handler taking `{ id: string }` cannot be called with an
+ * `unknown` input — so APIs that merely store or catalogue operations
+ * (the registry) accept this instead.
+ */
+export type AnyAPIOperation = APIOperation<never, unknown>;
 /**
  * Options for defining an API operation.
  */
 export interface DefineOperationOptions<TInput = unknown, TOutput = unknown> {
     readonly name: string;
+    /** @see {@link APIOperation.input} */
     readonly input?: unknown;
+    /** @see {@link APIOperation.output} */
     readonly output?: unknown;
     readonly handler: APIHandler<TInput, TOutput>;
     readonly metadata?: APIOperationMetadata;
+    /** @see {@link APIOperation.timeout} */
     readonly timeout?: number;
 }
+/**
+ * Validates an operation timeout.
+ *
+ * @throws {TypeError} if the value is not a number.
+ * @throws {RangeError} if the value is not a positive, finite integer of
+ * at most {@link MAX_OPERATION_TIMEOUT} milliseconds.
+ */
+export declare function assertValidTimeout(timeout: unknown, label: string): number;
+/**
+ * Resolves the effective timeout for an operation.
+ *
+ * This is the single owner of the precedence rule
+ * (`timeout` > `metadata.timeout` > {@link DEFAULT_OPERATION_TIMEOUT});
+ * `defineOperation` and the executor both go through it.
+ *
+ * Unusable values are skipped rather than disabling the deadline: the
+ * first usable candidate wins, and {@link DEFAULT_OPERATION_TIMEOUT}
+ * applies when none is. `defineOperation` rejects unusable values
+ * outright, so that fallback only applies to hand-rolled `APIOperation`
+ * objects.
+ */
+export declare function resolveOperationTimeout(source: {
+    readonly timeout?: number;
+    readonly metadata?: {
+        readonly timeout?: number;
+    };
+}): number;
+/**
+ * Validates the identity-bearing fields of an operation.
+ *
+ * Called by `defineOperation` and re-checked by
+ * `APIOperationRegistry.register`, since `APIOperation` is a bare
+ * interface that callers can satisfy without `defineOperation`.
+ *
+ * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {RangeError} if `name` is empty, over-long, or contains
+ * characters outside `[A-Za-z0-9._:/-]`.
+ */
+export declare function assertValidOperationShape(operation: {
+    readonly name?: unknown;
+    readonly handler?: unknown;
+}): void;
+/**
+ * Deeply freezes an operation's metadata so a registered operation cannot
+ * be rewritten process-wide through `metadata.tags` or `metadata.timeout`.
+ */
+export declare function freezeOperationMetadata(metadata: APIOperationMetadata | undefined): APIOperationMetadata | undefined;
 /**
  * Creates a new API operation definition.
+ *
+ * Validates the definition eagerly — a bad name, a missing handler, or an
+ * unusable timeout fails here, at startup, rather than on the first
+ * request that reaches the operation.
+ *
+ * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
  */
 export declare function defineOperation<TInput = unknown, TOutput = unknown>(options: DefineOperationOptions<TInput, TOutput>): APIOperation<TInput, TOutput>;
 //# sourceMappingURL=operation.type.d.ts.map

package/dist/api/operation/operation.type.js

@@ -1,11 +1,123 @@
-import { DEFAULT_OPERATION_TIMEOUT } from "../constants.js";
+import { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_NAME_LENGTH, MAX_OPERATION_TIMEOUT, } from "../constants.js";
+const OPERATION_NAME_PATTERN = /^[A-Za-z0-9._:/-]+$/;
+/**
+ * Validates an operation timeout.
+ *
+ * @throws {TypeError} if the value is not a number.
+ * @throws {RangeError} if the value is not a positive, finite integer of
+ * at most {@link MAX_OPERATION_TIMEOUT} milliseconds.
+ */
+export function assertValidTimeout(timeout, label) {
+    if (typeof timeout !== "number") {
+        throw new TypeError(`${label} must be a number, received ${typeof timeout}.`);
+    }
+    if (!Number.isFinite(timeout) || !Number.isInteger(timeout)) {
+        throw new RangeError(`${label} must be a finite integer number of milliseconds, received ${String(timeout)}.`);
+    }
+    if (timeout <= 0) {
+        throw new RangeError(`${label} must be greater than 0 ms, received ${timeout}. The deadline cannot be disabled.`);
+    }
+    if (timeout > MAX_OPERATION_TIMEOUT) {
+        throw new RangeError(`${label} must be at most ${MAX_OPERATION_TIMEOUT} ms, received ${timeout}.`);
+    }
+    return timeout;
+}
+function isUsableTimeout(timeout) {
+    return (typeof timeout === "number" &&
+        Number.isInteger(timeout) &&
+        timeout > 0 &&
+        timeout <= MAX_OPERATION_TIMEOUT);
+}
+/**
+ * Resolves the effective timeout for an operation.
+ *
+ * This is the single owner of the precedence rule
+ * (`timeout` > `metadata.timeout` > {@link DEFAULT_OPERATION_TIMEOUT});
+ * `defineOperation` and the executor both go through it.
+ *
+ * Unusable values are skipped rather than disabling the deadline: the
+ * first usable candidate wins, and {@link DEFAULT_OPERATION_TIMEOUT}
+ * applies when none is. `defineOperation` rejects unusable values
+ * outright, so that fallback only applies to hand-rolled `APIOperation`
+ * objects.
+ */
+export function resolveOperationTimeout(source) {
+    for (const candidate of [source.timeout, source.metadata?.timeout]) {
+        if (isUsableTimeout(candidate)) {
+            return candidate;
+        }
+    }
+    return DEFAULT_OPERATION_TIMEOUT;
+}
+/**
+ * Validates the identity-bearing fields of an operation.
+ *
+ * Called by `defineOperation` and re-checked by
+ * `APIOperationRegistry.register`, since `APIOperation` is a bare
+ * interface that callers can satisfy without `defineOperation`.
+ *
+ * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {RangeError} if `name` is empty, over-long, or contains
+ * characters outside `[A-Za-z0-9._:/-]`.
+ */
+export function assertValidOperationShape(operation) {
+    const { name, handler } = operation;
+    if (typeof name !== "string") {
+        throw new TypeError(`Operation name must be a string, received ${typeof name}.`);
+    }
+    if (name.length === 0) {
+        throw new RangeError("Operation name must not be empty.");
+    }
+    if (name.length > MAX_OPERATION_NAME_LENGTH) {
+        throw new RangeError(`Operation name must be at most ${MAX_OPERATION_NAME_LENGTH} characters, received ${name.length}.`);
+    }
+    if (!OPERATION_NAME_PATTERN.test(name)) {
+        throw new RangeError(`Operation name "${name}" contains characters outside ${OPERATION_NAME_PATTERN.source}.`);
+    }
+    if (typeof handler !== "function") {
+        throw new TypeError(`Operation "${name}" must have a handler function, received ${typeof handler}.`);
+    }
+}
+/**
+ * Deeply freezes an operation's metadata so a registered operation cannot
+ * be rewritten process-wide through `metadata.tags` or `metadata.timeout`.
+ */
+export function freezeOperationMetadata(metadata) {
+    if (metadata === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(metadata.tags)) {
+        Object.freeze(metadata.tags);
+    }
+    return Object.freeze(metadata);
+}
 /**
  * Creates a new API operation definition.
+ *
+ * Validates the definition eagerly — a bad name, a missing handler, or an
+ * unusable timeout fails here, at startup, rather than on the first
+ * request that reaches the operation.
+ *
+ * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
  */
 export function defineOperation(options) {
+    assertValidOperationShape(options);
+    if (options.timeout !== undefined) {
+        assertValidTimeout(options.timeout, "Operation timeout");
+    }
+    if (options.metadata?.timeout !== undefined) {
+        assertValidTimeout(options.metadata.timeout, "Operation metadata.timeout");
+    }
+    // Explicit field list rather than `...options`: an operation carries
+    // exactly the contract fields, never arbitrary extra properties.
     const operation = {
-        ...options,
-        timeout: options.timeout ?? options.metadata?.timeout ?? DEFAULT_OPERATION_TIMEOUT,
+        name: options.name,
+        input: options.input,
+        output: options.output,
+        handler: options.handler,
+        metadata: freezeOperationMetadata(options.metadata),
+        timeout: resolveOperationTimeout(options),
     };
     return Object.freeze(operation);
 }

package/dist/api/registry/operationRegistry.core.d.ts

@@ -1,8 +1,11 @@
-import type { APIOperation } from "../operation/operation.type.js";
+import type { AnyAPIOperation, APIOperation } from "../operation/operation.type.js";
 /**
  * Registry for API operations.
  *
  * Enforces uniqueness and provides O(1) lookup by operation name.
+ *
+ * Every failure leaving this class is an `APIError`, so a transport can
+ * map it by `statusCode` / `code` without special-casing the registry.
  */
 export declare class APIOperationRegistry {
     private readonly operations;
@@ -10,9 +13,15 @@ export declare class APIOperationRegistry {
     /**
      * Registers an operation.
      *
+     * The operation and its metadata are frozen on registration, so a
+     * registered operation cannot be rewritten through `metadata.tags` or
+     * `metadata.timeout` after the fact.
+     *
      * @throws {APIDuplicateOperationError} if an operation with the same name is already registered.
+     * @throws {APIError} if the registry is frozen.
+     * @throws {TypeError | RangeError} if the operation's name or handler is invalid.
      */
-    register(operation: APIOperation): void;
+    register(operation: AnyAPIOperation): void;
     /**
      * Retrieves an operation by name.
      */
@@ -23,6 +32,8 @@ export declare class APIOperationRegistry {
     has(name: string): boolean;
     /**
      * Retrieves an operation by name or throws.
+     *
+     * @throws {APIOperationNotFoundError} (404) if no operation is registered under `name`.
      */
     require(name: string): APIOperation;
     /**
@@ -35,6 +46,8 @@ export declare class APIOperationRegistry {
     findByTag(tag: string): readonly APIOperation[];
     /**
      * Unregisters an operation.
+     *
+     * @throws {APIError} if the registry is frozen.
      */
     unregister(name: string): boolean;
     /**