@zudojs/api 0.1.2 → 1.0.1

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

@@ -1,27 +1,49 @@
-import { APIError, APIInternalError, APITimeoutError, APIValidationError, createAPIError, isAPIError, } from "../errors/index.js";
-import { DEFAULT_OPERATION_TIMEOUT, MAX_INTERCEPTORS } from "../constants.js";
+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 APIError instances.
  *
- * APIErrors pass through untouched. Other errors are wrapped in
- * APIInternalError (`expose: false`), preserving the original message and
- * error for logging via `cause` while keeping internals out of anything
- * a transport would serialize to a client.
+ * 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 (isAPIError(error)) {
         return error;
     }
-    if (error instanceof Error) {
-        const wrapped = new APIInternalError(error.message);
-        // The published @zudojs/errors 0.1.0 constructor doesn't accept
-        // `cause`; the field is a plain writable property on BaseError.
-        // Switch to `new APIInternalError(msg, { cause })` once this package
-        // depends on the next @zudojs/errors release.
-        wrapped.cause = error;
-        return wrapped;
+    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 new APIInternalError(`Unexpected non-error thrown in operation "${operationName}": ${String(error)}`);
+    return typeof value;
 }
 function isStandardSchema(value) {
     return (typeof value === "object" &&
@@ -29,41 +51,62 @@ function isStandardSchema(value) {
         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 when the operation's `input` is a Standard Schema.
+ * 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) {
         if (context.signal?.aborted) {
-            return { ok: false, error: abortedError(operation.name) };
+            return apiFailure(abortedError(operation.name));
         }
         let effectiveInput = input;
         if (isStandardSchema(operation.input)) {
             try {
                 const validation = await operation.input["~standard"].validate(input);
-                if (validation.issues) {
-                    return {
-                        ok: false,
-                        error: new APIValidationError(`Invalid input for operation "${operation.name}".`, validation.issues.map((issue) => issue.message)),
-                    };
+                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 = {
@@ -71,37 +114,79 @@ export class APIExecutor {
             input: effectiveInput,
             context,
         };
-        const executeHandler = async () => {
-            const result = await this.invokeHandler(operation, effectiveInput, context);
-            executionContext.result = result;
-            return result;
-        };
+        // 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 {
-            const result = await this.runPipeline(executionContext, executeHandler);
-            executionContext.result = result;
-            return result;
+            return await this.runPipeline(executionContext, executeHandler);
         }
         catch (error) {
-            return { ok: false, error: normalizeAPIError(error, operation.name) };
+            return apiFailure(normalizeAPIError(error, operation.name));
         }
     }
     /**
-     * Invokes the operation handler under its timeout and abort signal.
+     * 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 { ok: false, error: abortedError(operation.name) };
+            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);
         }
-        const timeoutMs = operation.timeout ??
-            operation.metadata?.timeout ??
-            DEFAULT_OPERATION_TIMEOUT;
+        let validation;
         try {
-            const output = await withDeadline(operation.handler(input, context), timeoutMs, operation.name, context.signal);
-            return { ok: true, data: output };
+            validation = await operation.output["~standard"].validate(output);
         }
         catch (error) {
-            return { ok: false, error: normalizeAPIError(error, operation.name) };
+            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);
+    }
+    /**
+     * Converts schema issues into the capped, redacted list carried on the
+     * client-facing `APIValidationError`.
+     */
+    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).
@@ -109,6 +194,11 @@ export class APIExecutor {
      * 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;
@@ -119,17 +209,54 @@ export class APIExecutor {
             }
             lastDispatched = index;
             if (index >= interceptors.length) {
-                return terminal();
+                const result = await terminal();
+                context.result = result;
+                return result;
             }
             const interceptor = interceptors[index];
-            return interceptor.intercept(context, () => dispatch(index + 1));
+            const result = await interceptor.intercept(context, () => dispatch(index + 1));
+            context.result = result;
+            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,
     });
@@ -138,12 +265,13 @@ function abortedError(operationName) {
  * 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) {
-    const useTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0;
-    if (!useTimeout && !signal) {
-        return promise;
-    }
     return new Promise((resolve, reject) => {
         let timer;
         const cleanup = () => {
@@ -155,14 +283,16 @@ function withDeadline(promise, timeoutMs, operationName, signal) {
             cleanup();
             reject(abortedError(operationName));
         };
-        if (useTimeout) {
-            timer = setTimeout(() => {
-                cleanup();
-                reject(new APITimeoutError(timeoutMs));
-            }, timeoutMs);
-        }
+        timer = setTimeout(() => {
+            cleanup();
+            reject(new APITimeoutError(timeoutMs));
+        }, timeoutMs);
         signal?.addEventListener("abort", onAbort, { once: true });
-        promise.then((value) => {
+        // `Promise.resolve` rather than `promise.then`: a hand-rolled operation
+        // whose handler returns synchronously is a legal JavaScript caller, and
+        // calling `.then` on its plain value failed with "promise.then is not a
+        // function" reported as an internal error of the operation.
+        Promise.resolve(promise).then((value) => {
             cleanup();
             resolve(value);
         }, (error) => {

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/interceptors/interceptor.type.d.ts

@@ -6,12 +6,24 @@ 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 operation result. Populated by the executor once the handler has
-     * run, so interceptor code after `await next()` can read it here as
-     * well as from `next()`'s return value.
+     * 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;
 }
@@ -24,24 +28,105 @@ export interface APIOperation<TInput = unknown, TOutput = unknown> {
      * 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;
     /**