@zudojs/api 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/api
 
-Higher-level API layer — operation definitions, execution context, interceptors, policies, and a transport-agnostic executor. Sits above `@zudojs/http` and `@zudojs/cqrs`.
+Higher-level API layer — operation definitions, execution context, interceptors, and a transport-agnostic executor. Sits above `@zudojs/http` and `@zudojs/cqrs`.
 
 ## When to use
 
@@ -20,36 +20,160 @@ npm install @zudojs/api
 
 ```typescript
 import {
+  // operations
   defineOperation,
-  APIExecutor,
+  resolveOperationTimeout,
   APIOperationRegistry,
+  // execution
+  APIExecutor,
   createNoopInterceptor,
   normalizeAPIError,
+  // context
+  createAPIContext,
+  createContextKey,
+  normalizeRequestId,
+  isValidRequestId,
+  RequestIdContextKey,
+  CorrelationIdContextKey,
+  TenantIdContextKey,
+  UserIdContextKey,
+  StartTimeContextKey,
+  // results
+  apiSuccess,
+  apiFailure,
+  isApiSuccess,
+  isApiFailure,
+  // constants
+  DEFAULT_OPERATION_TIMEOUT,
+  MAX_OPERATION_TIMEOUT,
+  MAX_INTERCEPTORS,
+  MAX_VALIDATION_ISSUES,
   type APIContext,
   type APIContextKey,
+  type APIExecutionContext,
+  type APIExecutorOptions,
   type APIHandler,
   type APIInterceptor,
-  type OperationDefinition,
+  type APIOperation,
+  type APIOperationMetadata,
+  type APIResult,
+  type DefineOperationOptions,
   type APIErrorOptions,
 } from "@zudojs/api";
 ```
 
+Every API error class from `@zudojs/errors` (`APIError`, `APIValidationError`, `APIInternalError`, `APIOperationNotFoundError`, …) plus `createAPIError`, `isAPIError` and `ErrorCode` are re-exported for convenience.
+
 ## Usage
 
 ```typescript
-import { defineOperation, APIOperationRegistry } from "@zudojs/api";
+import {
+  APIExecutor,
+  APIOperationRegistry,
+  createAPIContext,
+  defineOperation,
+  normalizeRequestId,
+} from "@zudojs/api";
 
-const getUser = defineOperation({
-  name: "GetUser",
-  input: { id: "string" },
-  handler: async ({ input, context }) => db.findUser(input.id),
+// 1. Define the operation. The handler is positional: (input, context).
+const getUser = defineOperation<{ id: string }, { id: string; name: string }>({
+  name: "users.get",
+  input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
+  output: UserSchema, // validated too — see "Output validation"
+  timeout: 5_000,
+  metadata: { tags: ["Users"] },
+  handler: async (input, context) => db.findUser(input.id, context.signal),
 });
 
+// 2. Register it.
 const registry = new APIOperationRegistry();
 registry.register(getUser);
-const result = await registry.dispatch("GetUser", { id: "u_1" }, ctx);
+registry.freeze();
+
+// 3. Execute it. The registry looks operations up; the executor runs them.
+const executor = new APIExecutor();
+const context = createAPIContext(
+  normalizeRequestId(request.headers["x-request-id"]),
+  { locale: "en" },
+);
+
+const result = await executor.execute(
+  registry.require("users.get"), // throws APIOperationNotFoundError (404)
+  { id: "u_1" },
+  context,
+);
+
+if (result.ok) {
+  respond(200, result.data);
+} else {
+  respond(result.error.statusCode, {
+    message: result.error.expose ? result.error.message : "Internal error",
+  });
+}
+```
+
+Results are frozen `{ ok: true, data }` / `{ ok: false, error }` objects — `execute` never throws for an operation failure.
+
+## Input validation
+
+When `operation.input` is a Standard Schema, the executor validates the input before the handler runs and passes the schema's *transformed* value to the handler. Failures return an `APIValidationError` (422).
+
+Schema issue messages routinely interpolate the value that failed, so by default the executor does **not** copy them into the client-facing error: each issue becomes `"<path>: invalid"` (e.g. `"user.email: invalid"`), naming where validation failed without echoing what was submitted. The list is capped at `MAX_VALIDATION_ISSUES` entries with a trailing `"… and N more issue(s) omitted."` marker.
+
+```typescript
+// Opt in to raw messages only when every schema in the process is known
+// to produce value-free messages.
+new APIExecutor({ exposeValidationMessages: true, maxValidationIssues: 10 });
+```
+
+## Output validation
+
+When `operation.output` is a Standard Schema, the handler's return value is validated too, and the validated (possibly stripped or transformed) value becomes `result.data`. A mismatch is a server bug, so it fails with an `APIInternalError` (500, `expose: false`) naming only the failing paths.
+
+## Timeouts
+
+Every operation has a deadline. `timeout` must be a positive, finite integer of at most `MAX_OPERATION_TIMEOUT` milliseconds; `defineOperation` rejects `0`, negatives, `NaN` and non-integers rather than silently running unbounded. Precedence is `timeout` → `metadata.timeout` → `DEFAULT_OPERATION_TIMEOUT`, resolved by `resolveOperationTimeout`.
+
+The handler itself is not cancellable — pass `context.signal` into anything that supports it. An execution cancelled through the signal fails with `ErrorCode.OPERATION_CANCELLED`; branch on that code rather than on the (nginx-convention) 499 status.
+
+## Interceptors
+
+```typescript
+const timing: APIInterceptor = {
+  async intercept(context, next) {
+    context.input = sanitize(context.input); // reaches the handler
+    const started = Date.now();
+    const result = await next();
+    // context.result === result, including when a downstream interceptor
+    // short-circuits without calling next().
+    log(context.operation.name, Date.now() - started, result.ok);
+    return result;
+  },
+};
+
+new APIExecutor([timing]); // or new APIExecutor({ interceptors: [timing] })
 ```
 
+At most `MAX_INTERCEPTORS` interceptors per executor, and each `next()` may be awaited once.
+
+## Context
+
+`APIContext` carries the request id, an optional `AbortSignal`, caller state, and typed key/value slots. Keys carry their own identity, so two keys created with the same name never collide:
+
+```typescript
+const FeatureFlagsKey = createContextKey<readonly string[]>("featureFlags");
+
+context.set(FeatureFlagsKey, ["beta"]);
+context.get(FeatureFlagsKey); // readonly string[] | undefined
+context.metadata; // read-only snapshot keyed by key name
+```
+
+`createAPIContext` requires a safe request id (non-empty, ≤128 chars, `[A-Za-z0-9._:-]`) and throws otherwise. Run client-supplied header values through `normalizeRequestId` first — it replaces anything unsafe with a generated UUID, so a request id can never inject a log line or split a response header. `requestId` cannot be reassigned through `RequestIdContextKey`.
+
+## Errors
+
+`normalizeAPIError(error, operationName?)` converts anything thrown into an `APIError`. Non-API errors become an `APIInternalError` with a generic message and the original on `cause` — the internal message is deliberately not copied onto the wrapper, because `BaseError.toJSON()` serializes `message`, `stack` and `cause` regardless of `expose`.
+
 ## License
 
 MIT

package/dist/api/constants.d.ts

@@ -5,14 +5,44 @@
  */
 /**
  * Default timeout for API operations (30 seconds).
+ *
+ * Applied by {@link defineOperation} when no explicit timeout is given, and
+ * by the executor as a fail-safe for hand-rolled operation objects.
  */
 export declare const DEFAULT_OPERATION_TIMEOUT = 30000;
+/**
+ * Maximum timeout accepted for a single operation (1 hour).
+ *
+ * Enforced by `defineOperation`. A larger value is almost always a unit
+ * mistake (seconds vs milliseconds) rather than an intentional deadline.
+ */
+export declare const MAX_OPERATION_TIMEOUT = 3600000;
 /**
  * Maximum number of interceptors allowed in a pipeline.
+ * Enforced by the APIExecutor constructor.
  */
 export declare const MAX_INTERCEPTORS = 32;
 /**
- * Maximum number of policies allowed on a single operation.
+ * Maximum number of validation issues carried on an `APIValidationError`
+ * produced by the executor.
+ *
+ * Schema libraries emit one issue per failing element, so an array input
+ * can produce an unbounded number of issues. The executor truncates the
+ * list at this many entries and appends a single marker entry recording
+ * how many were dropped.
+ */
+export declare const MAX_VALIDATION_ISSUES = 20;
+/**
+ * Maximum length of a single validation issue string produced by the
+ * executor. Longer strings are truncated with an ellipsis.
+ */
+export declare const MAX_VALIDATION_ISSUE_LENGTH = 200;
+/**
+ * Maximum length of an operation name accepted by `defineOperation`.
+ */
+export declare const MAX_OPERATION_NAME_LENGTH = 128;
+/**
+ * Maximum length of a request id accepted by `createAPIContext`.
  */
-export declare const MAX_POLICIES = 16;
+export declare const MAX_REQUEST_ID_LENGTH = 128;
 //# sourceMappingURL=constants.d.ts.map

package/dist/api/constants.js

@@ -5,14 +5,44 @@
  */
 /**
  * Default timeout for API operations (30 seconds).
+ *
+ * Applied by {@link defineOperation} when no explicit timeout is given, and
+ * by the executor as a fail-safe for hand-rolled operation objects.
  */
 export const DEFAULT_OPERATION_TIMEOUT = 30_000;
+/**
+ * Maximum timeout accepted for a single operation (1 hour).
+ *
+ * Enforced by `defineOperation`. A larger value is almost always a unit
+ * mistake (seconds vs milliseconds) rather than an intentional deadline.
+ */
+export const MAX_OPERATION_TIMEOUT = 3_600_000;
 /**
  * Maximum number of interceptors allowed in a pipeline.
+ * Enforced by the APIExecutor constructor.
  */
 export const MAX_INTERCEPTORS = 32;
 /**
- * Maximum number of policies allowed on a single operation.
+ * Maximum number of validation issues carried on an `APIValidationError`
+ * produced by the executor.
+ *
+ * Schema libraries emit one issue per failing element, so an array input
+ * can produce an unbounded number of issues. The executor truncates the
+ * list at this many entries and appends a single marker entry recording
+ * how many were dropped.
+ */
+export const MAX_VALIDATION_ISSUES = 20;
+/**
+ * Maximum length of a single validation issue string produced by the
+ * executor. Longer strings are truncated with an ellipsis.
+ */
+export const MAX_VALIDATION_ISSUE_LENGTH = 200;
+/**
+ * Maximum length of an operation name accepted by `defineOperation`.
+ */
+export const MAX_OPERATION_NAME_LENGTH = 128;
+/**
+ * Maximum length of a request id accepted by `createAPIContext`.
  */
-export const MAX_POLICIES = 16;
+export const MAX_REQUEST_ID_LENGTH = 128;
 //# sourceMappingURL=constants.js.map

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

@@ -10,11 +10,49 @@ export interface APIContext<TState = unknown> {
     readonly signal?: AbortSignal;
     readonly state: TState;
     get<T>(key: APIContextKey<T>): T | undefined;
+    /**
+     * Stores a value under a typed key.
+     *
+     * @throws {TypeError} for {@link RequestIdContextKey}, which is fixed at
+     * construction so `get(RequestIdContextKey)` can never disagree with
+     * `context.requestId`.
+     */
     set<T>(key: APIContextKey<T>, value: T): void;
+    /**
+     * Read-only snapshot of the context values, keyed by context key name.
+     *
+     * This is a genuine read-only façade, not the context's backing store:
+     * it has no mutating methods at all, so casting it to `Map` and calling
+     * `set`/`delete`/`clear` throws rather than mutating the context.
+     */
     readonly metadata: ReadonlyMap<string, unknown>;
 }
+/**
+ * Determines whether a value is usable as a request id.
+ *
+ * A valid request id is a non-empty string of at most
+ * {@link MAX_REQUEST_ID_LENGTH} characters drawn from `[A-Za-z0-9._:-]`.
+ * The charset excludes CR/LF and other control characters, so a request id
+ * is always safe to place in a log line or a response header.
+ */
+export declare function isValidRequestId(value: unknown): value is string;
+/**
+ * Normalizes an untrusted request id.
+ *
+ * Transports typically populate the request id from an inbound
+ * `X-Request-Id` / `X-Correlation-Id` header, i.e. straight from the
+ * network. Pass that value through this function before handing it to
+ * {@link createAPIContext}: valid ids are returned unchanged, anything
+ * else (missing, empty, over-long, or containing characters that would
+ * allow log injection or response splitting) is replaced by a freshly
+ * generated UUID.
+ */
+export declare function normalizeRequestId(value: unknown): string;
 /**
  * Creates a new API context.
+ *
+ * @throws {TypeError} if `requestId` is not a valid request id. Use
+ * {@link normalizeRequestId} for client-supplied values.
  */
 export declare function createAPIContext<TState = unknown>(requestId: string, state: TState, signal?: AbortSignal): APIContext<TState>;
 export type { APIContextKey };

package/dist/api/context/context.type.js

@@ -1,25 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { MAX_REQUEST_ID_LENGTH } from "../constants.js";
 import { RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, createContextKey, } from "./contextKey.type.js";
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
+/**
+ * Determines whether a value is usable as a request id.
+ *
+ * A valid request id is a non-empty string of at most
+ * {@link MAX_REQUEST_ID_LENGTH} characters drawn from `[A-Za-z0-9._:-]`.
+ * The charset excludes CR/LF and other control characters, so a request id
+ * is always safe to place in a log line or a response header.
+ */
+export function isValidRequestId(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_REQUEST_ID_LENGTH &&
+        REQUEST_ID_PATTERN.test(value));
+}
+/**
+ * Normalizes an untrusted request id.
+ *
+ * Transports typically populate the request id from an inbound
+ * `X-Request-Id` / `X-Correlation-Id` header, i.e. straight from the
+ * network. Pass that value through this function before handing it to
+ * {@link createAPIContext}: valid ids are returned unchanged, anything
+ * else (missing, empty, over-long, or containing characters that would
+ * allow log injection or response splitting) is replaced by a freshly
+ * generated UUID.
+ */
+export function normalizeRequestId(value) {
+    return isValidRequestId(value) ? value : randomUUID();
+}
 /**
  * Creates a new API context.
+ *
+ * @throws {TypeError} if `requestId` is not a valid request id. Use
+ * {@link normalizeRequestId} for client-supplied values.
  */
 export function createAPIContext(requestId, state, signal) {
-    const metadata = new Map();
-    metadata.set(RequestIdContextKey.name, requestId);
+    if (!isValidRequestId(requestId)) {
+        throw new TypeError(`Invalid requestId: expected a non-empty string of at most ${MAX_REQUEST_ID_LENGTH} characters matching ${REQUEST_ID_PATTERN.source}. Use normalizeRequestId() for client-supplied values.`);
+    }
+    // Values are stored under the key's unique `id` symbol, so keys sharing
+    // a `name` never share a slot.
+    const store = new Map();
+    const names = new Map();
+    const remember = (key) => {
+        names.set(key.id, key.name);
+    };
+    remember(RequestIdContextKey);
+    store.set(RequestIdContextKey.id, requestId);
+    let view;
     const context = {
         requestId,
         signal,
         state,
         get(key) {
-            return metadata.get(key.name);
+            return store.get(key.id);
         },
         set(key, value) {
-            metadata.set(key.name, value);
+            if (key.id === RequestIdContextKey.id) {
+                throw new TypeError("requestId is fixed at context creation and cannot be reassigned.");
+            }
+            remember(key);
+            store.set(key.id, value);
+            view = undefined;
         },
         get metadata() {
-            return new Map(metadata);
+            if (view === undefined) {
+                const snapshot = new Map();
+                for (const [id, value] of store) {
+                    snapshot.set(names.get(id) ?? id.toString(), value);
+                }
+                view = createReadonlyMapView(snapshot);
+            }
+            return view;
         },
     };
     return Object.freeze(context);
 }
+/**
+ * Wraps a private map in a frozen object exposing only the read half of
+ * the `ReadonlyMap` interface. The wrapped map is unreachable from the
+ * returned value, so there is no cast that recovers mutation rights.
+ */
+function createReadonlyMapView(source) {
+    const view = {
+        get size() {
+            return source.size;
+        },
+        get: (key) => source.get(key),
+        has: (key) => source.has(key),
+        keys: () => source.keys(),
+        values: () => source.values(),
+        entries: () => source.entries(),
+        forEach: (callback, thisArg) => {
+            for (const [key, value] of source) {
+                callback.call(thisArg, value, key, view);
+            }
+        },
+        [Symbol.iterator]: () => source[Symbol.iterator](),
+    };
+    return Object.freeze(view);
+}
 export { RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, createContextKey, };
 //# sourceMappingURL=context.type.js.map

package/dist/api/context/contextKey.type.d.ts

@@ -8,13 +8,26 @@
  */
 /**
  * A typed key for storing and retrieving values from the API context.
+ *
+ * Keys carry a unique `id` symbol, so two keys created with the same
+ * `name` are distinct slots: a third-party key can never collide with —
+ * or be read as the wrong type through — a key owned by someone else.
+ * `name` is retained for debugging and for the context's `metadata` view.
+ *
+ * Keys must be created with {@link createContextKey}; the `id` symbol is
+ * the identity the context stores values under.
  */
 export interface APIContextKey<T> {
     readonly name: string;
+    /** Unique identity for this key. Two keys never share an id. */
+    readonly id: symbol;
+    /** Phantom type carrier. Never populated at runtime. */
     readonly type: T;
 }
 /**
  * Creates a typed context key.
+ *
+ * @throws {TypeError} if `name` is not a non-empty string.
  */
 export declare function createContextKey<T>(name: string): APIContextKey<T>;
 /**

package/dist/api/context/contextKey.type.js

@@ -8,10 +8,16 @@
  */
 /**
  * Creates a typed context key.
+ *
+ * @throws {TypeError} if `name` is not a non-empty string.
  */
 export function createContextKey(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("Context key name must be a non-empty string.");
+    }
     return Object.freeze({
         name,
+        id: Symbol(name),
         type: undefined,
     });
 }

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

@@ -5,6 +5,6 @@
  *
  * Re-exported from @zudojs/errors for convenience.
  */
-export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, } from "@zudojs/errors";
+export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, ErrorCode, } from "@zudojs/errors";
 export type { APIErrorOptions } from "@zudojs/errors";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/errors/index.js

@@ -5,5 +5,5 @@
  *
  * Re-exported from @zudojs/errors for convenience.
  */
-export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, } from "@zudojs/errors";
+export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, ErrorCode, } from "@zudojs/errors";
 //# sourceMappingURL=index.js.map

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

@@ -2,31 +2,101 @@ import type { APIContext } from "../context/context.type.js";
 import type { APIResult } from "../result/apiResult.type.js";
 import type { APIOperation } from "../operation/operation.type.js";
 import type { APIInterceptor } from "../interceptors/interceptor.type.js";
+import { APIError } from "../errors/index.js";
+export type { APIExecutionContext } from "../interceptors/interceptor.type.js";
 /**
- * Execution context passed through the interceptor pipeline.
+ * 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 interface APIExecutionContext<TInput = unknown, TOutput = unknown> {
-    readonly operation: APIOperation<TInput, TOutput>;
-    readonly input: TInput;
-    readonly context: APIContext;
-    readonly result?: APIResult<TOutput>;
-}
+export declare function normalizeAPIError(error: unknown, operationName?: string): APIError;
 /**
- * Error normalizer for converting unknown errors into Error instances.
+ * Options for {@link APIExecutor}.
  */
-export declare function normalizeAPIError(error: unknown, operationName?: string): Error;
+export interface APIExecutorOptions {
+    /** Interceptor pipeline, outermost first. */
+    readonly interceptors?: readonly APIInterceptor[];
+    /**
+     * Whether raw schema issue messages are copied into the client-facing
+     * `APIValidationError` (which is `expose: true`).
+     *
+     * Default `false`. Schema messages routinely interpolate the received
+     * value — Zod's built-in messages do for several checks, and most
+     * hand-written `message:` strings do — which would put submitted
+     * secrets straight into a 422 body. With the default, clients receive
+     * one entry per failing path (`"user.email: invalid"`) naming *where*
+     * validation failed but never echoing *what* was submitted.
+     *
+     * Set to `true` only when every schema in the process is known to
+     * produce value-free messages.
+     */
+    readonly exposeValidationMessages?: boolean;
+    /**
+     * Maximum number of validation issues carried on a single
+     * `APIValidationError`. Defaults to {@link MAX_VALIDATION_ISSUES}.
+     *
+     * A schema over a large array emits one issue per failing element, so
+     * an uncapped list is an amplification vector: the executor is the
+     * layer on the untrusted-input boundary and caps it here.
+     */
+    readonly maxValidationIssues?: number;
+}
 /**
  * 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 declare class APIExecutor {
     private readonly interceptors;
-    constructor(interceptors?: readonly APIInterceptor[]);
+    private readonly exposeValidationMessages;
+    private readonly maxValidationIssues;
+    constructor(optionsOrInterceptors?: readonly APIInterceptor[] | APIExecutorOptions);
     /**
      * Executes an operation with the given input and context.
      */
     execute<TInput = unknown, TOutput = unknown>(operation: APIOperation<TInput, TOutput>, input: TInput, context: APIContext): Promise<APIResult<TOutput>>;
     /**
-     * Runs the interceptor pipeline.
+     * Invokes the operation handler under its timeout and abort signal, and
+     * validates the handler's output when `operation.output` is a Standard
+     * Schema.
+     */
+    private invokeHandler;
+    /**
+     * 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.
+     */
+    private validateOutput;
+    /**
+     * Converts schema issues into the capped, redacted list carried on the
+     * client-facing `APIValidationError`.
+     */
+    private clientIssues;
+    /**
+     * 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()`.
      */
     private runPipeline;
 }