@classytic/arc 2.15.4 → 2.16.0

package/dist/index-bRjYu21O.d.mts

@@ -1,1320 +0,0 @@
-import { $ as OpenApiSchemas, S as QueryParserInterface, Wt as AnyRecord, Yt as UserLike, at as ResourceConfig, b as ParsedQuery } from "./index-BswOSJCE.mjs";
-import { n as ErrorMapper } from "./errorHandler-DFr45ZG4.mjs";
-import { HttpError, errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
-import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
-
-//#region src/utils/errors.d.ts
-interface ErrorOptions {
-  code?: string;
-  statusCode?: number;
-  details?: Record<string, unknown>;
-  cause?: Error;
-}
-/**
- * Base Arc Error. Implements the canonical `HttpError` contract — `status`
- * mirrors `statusCode` and `meta` mirrors `details`, so consumers reading
- * either name see the same value without adapter glue.
- */
-declare class ArcError extends Error implements HttpError {
-  name: string;
-  readonly code: string;
-  readonly statusCode: number;
-  readonly details?: Record<string, unknown>;
-  readonly cause?: Error;
-  constructor(message: string, options?: ErrorOptions);
-  /** `HttpError.status` mirror — repo-core's `toErrorContract` reads this. */
-  get status(): number;
-  /** `HttpError.meta` mirror — `details` under the canonical name. */
-  get meta(): Record<string, unknown> | undefined;
-}
-declare class NotFoundError extends ArcError {
-  constructor(resource: string, identifier?: string);
-}
-declare class ValidationError extends ArcError {
-  readonly errors: ReadonlyArray<{
-    field: string;
-    message: string;
-  }>;
-  constructor(message: string, errors?: Array<{
-    field: string;
-    message: string;
-  }>);
-}
-declare class UnauthorizedError extends ArcError {
-  constructor(message?: string);
-}
-declare class ForbiddenError extends ArcError {
-  constructor(message?: string);
-}
-declare class ConflictError extends ArcError {
-  constructor(message: string, field?: string);
-}
-declare class OrgRequiredError extends ArcError {
-  readonly organizations?: ReadonlyArray<{
-    id: string;
-    roles?: string[];
-  }>;
-  constructor(message: string, organizations?: Array<{
-    id: string;
-    roles?: string[];
-  }>);
-}
-declare class OrgAccessDeniedError extends ArcError {
-  constructor(orgId?: string);
-}
-declare class RateLimitError extends ArcError {
-  readonly retryAfter?: number;
-  constructor(message?: string, retryAfter?: number);
-}
-declare class ServiceUnavailableError extends ArcError {
-  constructor(message?: string);
-}
-/**
- * Quick `ArcError` constructor when the bundled subclasses don't fit.
- *
- * If `details.code` is a string, it's lifted to the top-level `error.code`
- * (the canonical wire slot for business signals — `'ORG_CONTEXT_REQUIRED'`,
- * `'ALL_FIELDS_STRIPPED'`, etc). The same code stays in `details` so
- * in-process consumers reading `error.details.code` still work. Without
- * this lift, business codes get buried in `details` and the wire envelope
- * carries only the status-derived `arc.forbidden` / `arc.bad_request`
- * fallback — `repo-core`'s `toErrorContract` doesn't surface free-form
- * `details` objects (its `details[]` array is reserved for validation /
- * duplicate-key items).
- */
-declare function createError(statusCode: number, message: string, details?: Record<string, unknown>): ArcError;
-/**
- * Domain-error escape hatch. Use a hierarchical code that scopes the error
- * to your package (`'commerce.cart.locked'`, `'payment.gateway.timeout'`).
- */
-declare function createDomainError(code: string, message: string, statusCode?: number, details?: Record<string, unknown>): ArcError;
-/** Type guard. */
-declare function isArcError(error: unknown): error is ArcError;
-//#endregion
-//#region src/core/validateResourceConfig.d.ts
-interface ConfigError {
-  field: string;
-  message: string;
-  suggestion?: string;
-}
-interface ValidationResult {
-  valid: boolean;
-  errors: ConfigError[];
-  warnings: ConfigError[];
-}
-interface ValidateOptions {
-  /** Skip controller method validation (for testing) */
-  skipControllerCheck?: boolean;
-  /** Allow unknown preset names */
-  allowUnknownPresets?: boolean;
-  /** Custom valid permission keys beyond CRUD */
-  additionalPermissionKeys?: string[];
-}
-/**
- * Validate a resource configuration
- */
-declare function validateResourceConfig(config: ResourceConfig, options?: ValidateOptions): ValidationResult;
-/**
- * Format validation errors for display
- */
-declare function formatValidationErrors(resourceName: string, result: ValidationResult): string;
-/**
- * Validate and throw if invalid
- */
-declare function assertValidConfig(config: ResourceConfig, options?: ValidateOptions): void;
-//#endregion
-//#region src/utils/circuitBreaker.d.ts
-/**
- * Circuit Breaker Pattern
- *
- * Wraps external service calls with failure protection.
- * Prevents cascading failures by "opening" the circuit when
- * a service is failing, allowing it time to recover.
- *
- * States:
- * - CLOSED: Normal operation, requests pass through
- * - OPEN: Too many failures, all requests fail fast
- * - HALF_OPEN: Testing if service recovered, limited requests
- *
- * @example
- * import { CircuitBreaker } from '@classytic/arc/utils';
- *
- * const paymentBreaker = new CircuitBreaker(async (amount) => {
- *   return await stripe.charges.create({ amount });
- * }, {
- *   failureThreshold: 5,
- *   resetTimeout: 30000,
- *   timeout: 5000,
- * });
- *
- * try {
- *   const result = await paymentBreaker.call(100);
- * } catch (error) {
- *   // Handle failure or circuit open
- * }
- */
-declare const CircuitState: {
-  readonly CLOSED: "CLOSED";
-  readonly OPEN: "OPEN";
-  readonly HALF_OPEN: "HALF_OPEN";
-};
-type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
-interface CircuitBreakerOptions {
-  /**
-   * Number of failures before opening circuit
-   * @default 5
-   */
-  failureThreshold?: number;
-  /**
-   * Time in ms before attempting to close circuit
-   * @default 60000 (60 seconds)
-   */
-  resetTimeout?: number;
-  /**
-   * Request timeout in ms
-   * @default 10000 (10 seconds)
-   */
-  timeout?: number;
-  /**
-   * Number of successful requests in HALF_OPEN before closing
-   * @default 1
-   */
-  successThreshold?: number;
-  /**
-   * Fallback function when circuit is open.
-   * Receives the same arguments as the wrapped function.
-   */
-  fallback?: (...args: unknown[]) => Promise<unknown>;
-  /**
-   * Callback when state changes
-   */
-  onStateChange?: (from: CircuitState, to: CircuitState) => void;
-  /**
-   * Callback on error
-   */
-  onError?: (error: Error) => void;
-  /**
-   * Name for logging/monitoring
-   */
-  name?: string;
-}
-interface CircuitBreakerStats {
-  name?: string;
-  state: CircuitState;
-  failures: number;
-  successes: number;
-  totalCalls: number;
-  openedAt: number | null;
-  lastCallAt: number | null;
-}
-declare class CircuitBreakerError extends Error {
-  state: CircuitState;
-  constructor(message: string, state: CircuitState);
-}
-declare class CircuitBreaker<T extends (...args: any[]) => Promise<any>> {
-  private state;
-  private failures;
-  private successes;
-  private totalCalls;
-  private nextAttempt;
-  private lastCallAt;
-  private openedAt;
-  private readonly failureThreshold;
-  private readonly resetTimeout;
-  private readonly timeout;
-  private readonly successThreshold;
-  private readonly fallback?;
-  private readonly onStateChange?;
-  private readonly onError?;
-  private readonly name;
-  private readonly fn;
-  constructor(fn: T, options?: CircuitBreakerOptions);
-  /**
-   * Call the wrapped function with circuit breaker protection
-   */
-  call(...args: Parameters<T>): Promise<ReturnType<T>>;
-  /**
-   * Execute function with timeout
-   */
-  private executeWithTimeout;
-  /**
-   * Handle successful call
-   */
-  private onSuccess;
-  /**
-   * Handle failed call
-   */
-  private onFailure;
-  /**
-   * Change circuit state
-   */
-  private setState;
-  /**
-   * Manually open the circuit
-   */
-  open(): void;
-  /**
-   * Manually close the circuit
-   */
-  close(): void;
-  /**
-   * Get current statistics
-   */
-  getStats(): CircuitBreakerStats;
-  /**
-   * Get current state
-   */
-  getState(): CircuitState;
-  /**
-   * Check if circuit is open
-   */
-  isOpen(): boolean;
-  /**
-   * Check if circuit is closed
-   */
-  isClosed(): boolean;
-  /**
-   * Reset statistics
-   */
-  reset(): void;
-}
-/**
- * Create a circuit breaker with sensible defaults
- *
- * @example
- * const emailBreaker = createCircuitBreaker(
- *   async (to, subject, body) => sendEmail(to, subject, body),
- *   { name: 'email-service' }
- * );
- */
-declare function createCircuitBreaker<T extends (...args: any[]) => Promise<any>>(fn: T, options?: CircuitBreakerOptions): CircuitBreaker<T>;
-/**
- * Circuit breaker registry for managing multiple breakers
- */
-declare class CircuitBreakerRegistry {
-  private breakers;
-  /**
-   * Register a circuit breaker
-   */
-  register<T extends (...args: any[]) => Promise<any>>(name: string, fn: T, options?: Omit<CircuitBreakerOptions, "name">): CircuitBreaker<T>;
-  /**
-   * Get a circuit breaker by name
-   */
-  get(name: string): CircuitBreaker<any> | undefined;
-  /**
-   * Get all breakers
-   */
-  getAll(): Map<string, CircuitBreaker<any>>;
-  /**
-   * Get statistics for all breakers
-   */
-  getAllStats(): Record<string, CircuitBreakerStats>;
-  /**
-   * Reset all breakers
-   */
-  resetAll(): void;
-  /**
-   * Open all breakers
-   */
-  openAll(): void;
-  /**
-   * Close all breakers
-   */
-  closeAll(): void;
-}
-/**
- * Create a new CircuitBreakerRegistry instance.
- * Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
- */
-declare function createCircuitBreakerRegistry(): CircuitBreakerRegistry;
-//#endregion
-//#region src/utils/compensation.d.ts
-/**
- * Compensating Transaction — In-Process Rollback Primitive
- *
- * Runs steps in order. If any step fails, runs compensating actions
- * for already-completed steps in reverse. Zero dependencies.
- *
- * Type-safe: generic context type gives autocomplete across steps.
- * Discriminated union result: compiler enforces checking success before
- * accessing failedStep/error.
- *
- * For distributed sagas across services, use Temporal, Inngest, or Streamline.
- *
- * @example
- * ```typescript
- * interface CheckoutCtx {
- *   orderId: string;
- *   reservationId?: string;
- * }
- *
- * const result = await withCompensation<CheckoutCtx>('checkout', [
- *   {
- *     name: 'reserve',
- *     execute: async (ctx) => {
- *       const res = await inventoryService.reserve(ctx.orderId);
- *       ctx.reservationId = res.id;
- *       return res;
- *     },
- *     compensate: async (ctx) => {
- *       await inventoryService.release(ctx.reservationId!);
- *     },
- *   },
- *   { name: 'notify', execute: sendEmail, fireAndForget: true },
- * ], { orderId: 'ord-123' });
- *
- * if (result.success) {
- *   // result.results available, no failedStep
- * } else {
- *   // result.failedStep and result.error guaranteed
- * }
- * ```
- */
-/** Step definition with typed context and typed result */
-interface CompensationStep<TCtx = Record<string, unknown>, TResult = unknown> {
-  /** Step name — used in results, logs, and hooks */
-  readonly name: string;
-  /** Execute the step — return value stored in results[name] */
-  readonly execute: (ctx: TCtx) => Promise<TResult>;
-  /** Rollback on failure — receives context and this step's own result */
-  readonly compensate?: (ctx: TCtx, stepResult: TResult) => Promise<void>;
-  /** Fire-and-forget — don't await, don't block, swallow errors, skip in rollback */
-  readonly fireAndForget?: boolean;
-}
-/** Lifecycle hooks for observability — wire to Arc events, metrics, or logging */
-interface CompensationHooks {
-  readonly onStepComplete?: (stepName: string, result: unknown) => void;
-  readonly onStepFailed?: (stepName: string, error: Error) => void;
-  readonly onCompensate?: (stepName: string) => void;
-}
-/** Error from a compensation action that failed during rollback */
-interface CompensationError {
-  readonly step: string;
-  readonly error: string;
-}
-/** Discriminated union — success and failure are mutually exclusive */
-type CompensationResult = {
-  readonly success: true;
-  readonly completedSteps: readonly string[];
-  readonly results: Readonly<Record<string, unknown>>;
-} | {
-  readonly success: false;
-  readonly completedSteps: readonly string[];
-  readonly results: Readonly<Record<string, unknown>>;
-  readonly failedStep: string;
-  readonly error: string;
-  readonly compensationErrors?: readonly CompensationError[];
-};
-/**
- * Run steps in order with automatic compensation on failure.
- *
- * @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
- */
-declare function withCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(_name: string, steps: readonly CompensationStep<TCtx>[], initialContext?: TCtx, hooks?: CompensationHooks): Promise<CompensationResult>;
-interface CompensationDefinition<TCtx extends Record<string, unknown> = Record<string, unknown>> {
-  readonly name: string;
-  readonly execute: (initialContext?: TCtx, hooks?: CompensationHooks) => Promise<CompensationResult>;
-}
-declare function defineCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: readonly CompensationStep<TCtx>[]): CompensationDefinition<TCtx>;
-//#endregion
-//#region src/utils/defineErrorMapper.d.ts
-/**
- * Register an `ErrorMapper` with its domain-specific generic argument and
- * have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
- *
- * The returned mapper is identical at runtime — `type` and `toResponse` are
- * passed through untouched. Only the declared type widens from
- * `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
- *
- * Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
- * before invoking `toResponse`, so the widened callback signature is never
- * called with a non-`T` error at runtime. This helper codifies that invariant
- * in one place.
- */
-declare function defineErrorMapper<T extends Error>(mapper: ErrorMapper<T>): ErrorMapper;
-//#endregion
-//#region src/utils/defineGuard.d.ts
-interface GuardConfig<T> {
-  /** Unique name — used as the storage key on the request. */
-  readonly name: string;
-  /**
-   * Resolve the guard context from the request. Throw to abort the request
-   * (Fastify's error handler will produce the appropriate HTTP response).
-   * Return a value to stash it for `from()` extraction.
-   */
-  readonly resolve: (req: FastifyRequest, reply: FastifyReply) => T | Promise<T>;
-}
-interface Guard<T> {
-  /** Use in `routeGuards` or per-route `preHandler` arrays. */
-  readonly preHandler: RouteHandlerMethod;
-  /**
-   * Extract the resolved context from a request. Throws if the guard
-   * hasn't run yet (i.e. not in the preHandler chain).
-   */
-  from(req: FastifyRequest): T;
-  /** The guard name (for debugging). */
-  readonly name: string;
-}
-/**
- * Create a typed guard. See module JSDoc for usage.
- */
-declare function defineGuard<T>(config: GuardConfig<T>): Guard<T>;
-//#endregion
-//#region src/utils/handleRaw.d.ts
-/**
- * Wrap a raw Fastify handler with Arc's response shape and error handling.
- *
- * @param handler - Async function that receives `(request, reply)` and returns data.
- *   The return value is sent raw (no envelope). If it returns `undefined`,
- *   the response body is empty (HTTP status only).
- * @param statusCode - HTTP status code for successful responses (default: 200)
- */
-declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-//#endregion
-//#region src/utils/queryParser.d.ts
-interface ArcQueryParserOptions {
-  /** Maximum allowed limit value (default: 1000) */
-  maxLimit?: number;
-  /** Default limit for pagination (default: 20) */
-  defaultLimit?: number;
-  /** Maximum regex pattern length (default: 500) */
-  maxRegexLength?: number;
-  /** Maximum search query length (default: 200) */
-  maxSearchLength?: number;
-  /** Maximum filter nesting depth (default: 10) */
-  maxFilterDepth?: number;
-  /**
-   * Whitelist of fields that can be filtered on.
-   * When set, only these fields are accepted as filters — all others are silently dropped.
-   * Also used by MCP to auto-derive filterable fields in tool schemas.
-   */
-  allowedFilterFields?: string[];
-  /**
-   * Whitelist of fields that can be sorted on.
-   * When set, sort fields not in this list are silently dropped.
-   * Also used by MCP to describe available sort options.
-   */
-  allowedSortFields?: string[];
-  /**
-   * Whitelist of filter operators (e.g. ['eq', 'ne', 'gt', 'lt', 'in']).
-   * When set, only these operators are accepted — all others are dropped.
-   * Also used by MCP to enrich list tool descriptions.
-   */
-  allowedOperators?: string[];
-}
-/**
- * Arc's default query parser
- *
- * Converts URL query parameters to a structured query format:
- * - Pagination: ?page=1&limit=20
- * - Sorting: ?sort=-createdAt,name (- prefix = descending)
- * - Filtering: ?status=active&price[gte]=100&price[lte]=500
- * - Search: ?search=keyword
- * - Populate: ?populate=author,category
- * - Field selection: ?select=name,price,status
- * - Keyset pagination: ?after=cursor_value
- *
- * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
- */
-declare class ArcQueryParser implements QueryParserInterface {
-  private readonly maxLimit;
-  private readonly defaultLimit;
-  private readonly maxRegexLength;
-  private readonly maxSearchLength;
-  private readonly maxFilterDepth;
-  private readonly _allowedFilterFields?;
-  private readonly _allowedSortFields?;
-  private readonly _allowedOperators?;
-  /** Allowed filter fields (used by MCP for auto-derive) */
-  readonly allowedFilterFields?: readonly string[];
-  /** Allowed sort fields (used by MCP for sort descriptions) */
-  readonly allowedSortFields?: readonly string[];
-  /** Allowed operators (used by MCP for operator descriptions) */
-  readonly allowedOperators?: readonly string[];
-  /** Supported filter operators */
-  private readonly operators;
-  constructor(options?: ArcQueryParserOptions);
-  /**
-   * Parse URL query parameters into structured query options
-   */
-  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
-  private parseNumber;
-  private parseString;
-  /**
-   * Parse populate parameter — handles both simple string and bracket notation.
-   *
-   * Simple: ?populate=author,category → { populate: 'author,category' }
-   * Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
-   */
-  private parsePopulate;
-  private parseSort;
-  private parseSearch;
-  private parseSelect;
-  /**
-   * Check if a value exceeds the maximum nesting depth.
-   * Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
-   */
-  private exceedsDepth;
-  private parseFilters;
-  private parseFilterValue;
-  private coerceValue;
-  /**
-   * Generate OpenAPI-compatible JSON Schema for query parameters.
-   * Arc's defineResource() auto-detects this method and uses it
-   * to document list endpoint query parameters in OpenAPI/Swagger.
-   */
-  getQuerySchema(): {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-  private sanitizeRegex;
-}
-/**
- * Create a new ArcQueryParser instance
- */
-declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryParser;
-//#endregion
-//#region src/utils/responseSchemas.d.ts
-interface JsonSchema {
-  /**
-   * Optional because JSON Schema allows top-level combinator-only schemas
-   * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-   * `listResponse()`, which emits a `oneOf` of the four canonical list
-   * shapes with no top-level `type`.
-   */
-  type?: string | string[];
-  properties?: Record<string, JsonSchema | AnyRecord>;
-  required?: string[];
-  items?: JsonSchema | AnyRecord;
-  additionalProperties?: boolean | JsonSchema;
-  description?: string;
-  example?: unknown;
-  oneOf?: JsonSchema[];
-  anyOf?: JsonSchema[];
-  allOf?: JsonSchema[];
-  [key: string]: unknown;
-}
-/**
- * Pagination schema - matches MongoKit/Arc runtime format
- *
- * Runtime format (flat fields):
- * { page, limit, total, pages, hasNext, hasPrev }
- */
-declare const paginationSchema: JsonSchema;
-/**
- * List response schema — full union of every wire shape `toCanonicalList`
- * can emit. Hosts who know their endpoint only ever produces one variant
- * can pin to a narrower helper:
- *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
- *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
- *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
- *   - `bareListResponse(item)` — `{ data }`
- *
- * The default `listResponse(item)` is the union (`oneOf`) of all four so
- * Fastify validation accepts any canonical kit shape — pre-2.13 this only
- * modelled offset and rejected keyset/aggregate/bare lists at the
- * response-schema gate.
- */
-declare function listResponse(itemSchema: JsonSchema): JsonSchema;
-/** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
-declare function offsetListResponse(itemSchema: JsonSchema): JsonSchema;
-/** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
-declare function keysetListResponse(itemSchema: JsonSchema): JsonSchema;
-/** Aggregate variant — same shape as offset, discriminated by `method: 'aggregate'`. */
-declare function aggregateListResponse(itemSchema: JsonSchema): JsonSchema;
-/** Bare variant — `{ data }`, no `method` discriminant. */
-declare function bareListResponse(itemSchema: JsonSchema): JsonSchema;
-/** Delete response — flat shape mirroring the canonical delete envelope. */
-declare function deleteResponse(): JsonSchema;
-declare const responses: {
-  200: (schema: JsonSchema) => {
-    description: string;
-    content: {
-      "application/json": {
-        schema: JsonSchema;
-      };
-    };
-  };
-  201: (schema: JsonSchema) => {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          additionalProperties: boolean;
-          /**
-           * Optional because JSON Schema allows top-level combinator-only schemas
-           * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
-           * `listResponse()`, which emits a `oneOf` of the four canonical list
-           * shapes with no top-level `type`.
-           */
-          type?: string | string[];
-          properties?: Record<string, JsonSchema | AnyRecord>;
-          required?: string[];
-          items?: JsonSchema | AnyRecord;
-          description?: string;
-          example?: unknown;
-          oneOf?: JsonSchema[];
-          anyOf?: JsonSchema[];
-          allOf?: JsonSchema[];
-        };
-      };
-    };
-  };
-  400: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-  401: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-  403: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-  404: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-  409: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-  500: {
-    description: string;
-    content: {
-      "application/json": {
-        schema: {
-          readonly type: "object";
-          readonly properties: {
-            readonly code: {
-              readonly type: "string";
-              readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
-            };
-            readonly message: {
-              readonly type: "string";
-              readonly description: "Human-readable, safe-for-client message.";
-            };
-            readonly status: {
-              readonly type: "integer";
-              readonly description: "Suggested HTTP status code (hosts may override).";
-            };
-            readonly details: {
-              readonly type: "array";
-              readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
-              readonly items: {
-                readonly type: "object";
-                readonly properties: {
-                  readonly path: {
-                    readonly type: "string";
-                    readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
-                  };
-                  readonly code: {
-                    readonly type: "string";
-                  };
-                  readonly message: {
-                    readonly type: "string";
-                  };
-                  readonly meta: {
-                    readonly type: "object";
-                    readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
-                  };
-                };
-                readonly required: readonly ["code", "message"];
-              };
-            };
-            readonly correlationId: {
-              readonly type: "string";
-              readonly description: "Request id for support lookups.";
-            };
-            readonly meta: {
-              readonly type: "object";
-              readonly description: "Non-PII diagnostics (safe to log + return).";
-            };
-          };
-          readonly required: readonly ["code", "message"];
-        };
-      };
-    };
-  };
-};
-declare const queryParams: {
-  pagination: {
-    page: {
-      type: string;
-      minimum: number;
-      default: number;
-      description: string;
-    };
-    limit: {
-      type: string;
-      minimum: number;
-      maximum: number;
-      default: number;
-      description: string;
-    };
-  };
-  sorting: {
-    sort: {
-      type: string;
-      description: string;
-      example: string;
-    };
-  };
-  filtering: {
-    select: {
-      description: string;
-      example: string;
-    };
-    populate: {
-      description: string;
-      example: string;
-    };
-  };
-};
-/**
- * Get standard list query parameters schema
- */
-declare function getListQueryParams(): AnyRecord;
-/**
- * Get default response schemas for all CRUD operations.
- *
- * When routes have response schemas, Fastify compiles them with
- * fast-json-stringify for 2-3x faster serialization and prevents
- * accidental field disclosure.
- *
- * These defaults use `additionalProperties: true` so all fields pass through.
- * Override with specific schemas for full serialization performance + safety.
- *
- * Note: `example` properties are stripped from defaults so they work with
- * any Fastify instance (not just createApp which adds `keywords: ['example']`).
- */
-declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
-//#endregion
-//#region src/utils/runtime.d.ts
-/**
- * Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
- * available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
- */
-declare const scheduleBackground: (cb: () => void) => void;
-//#endregion
-//#region src/utils/schemaConverter.d.ts
-/**
- * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
- * - `draft-7`: Fastify/AJV validation (default)
- * - `draft-2020-12`: AJV 2020 (opt-in, requires ajv/dist/2020)
- * - `openapi-3.0`: OpenAPI 3.0 document generation
- * - `openapi-3.1`: OpenAPI 3.1 document generation
- */
-type JsonSchemaTarget = "draft-7" | "draft-2020-12" | "openapi-3.0" | "openapi-3.1";
-/**
- * Check if an object is already a plain JSON Schema.
- * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
- * `allOf`, `anyOf`, `oneOf`, `items`, `enum`) and does NOT have Zod markers.
- */
-declare function isJsonSchema(input: unknown): input is Record<string, unknown>;
-/**
- * Check if an object is a Zod schema (has `_zod` marker from Zod v4).
- */
-declare function isZodSchema(input: unknown): boolean;
-/**
- * Convert any schema input to JSON Schema.
- *
- * Detection order:
- * 1. `null`/`undefined` → `undefined`
- * 2. Already JSON Schema → pass through as-is (zero overhead)
- * 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
- * 4. Unrecognized object → return as-is (treat as opaque schema)
- *
- * @param input Schema (Zod, plain JSON Schema, or opaque object)
- * @param target Output target — defaults to `draft-7` for Fastify compatibility.
- *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
- */
-declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget): Record<string, unknown> | undefined;
-/**
- * Convert all schema fields in an OpenApiSchemas object.
- * JSON Schema values pass through unchanged. Only Zod schemas are converted.
- *
- * Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
- * generation, not Fastify route validation.
- */
-declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSchemaTarget): OpenApiSchemas;
-/**
- * Convert schema values in a Fastify route schema record.
- *
- * Handles `body`, `querystring`, `params`, `headers` (top-level conversion)
- * and `response` (iterates by status code — each value converted individually).
- *
- * JSON Schema values pass through unchanged. Only Zod schemas are converted.
- *
- * Used for both custom routes and customSchemas (CRUD overrides).
- *
- * Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
- * Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
- */
-declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
-//#endregion
-//#region src/utils/simpleEqualityMatcher.d.ts
-/**
- * `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
- * matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
- *
- * **What it does:** for each `[key, expected]` in the filter, compares
- * `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
- * match their string representation) and returns `true` only if every
- * filter entry matches. Array item values are matched implicitly (contains).
- *
- * **What it does NOT do:**
- * - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
- * - No `$and` / `$or`
- * - No dot-path traversal (`"owner.id"`)
- * - No schema-specific coercion
- *
- * **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
- * permission helpers and are shaped like `{ ownerId: "u1" }` or
- * `{ organizationId: "org_x" }` — flat equality. For that common shape,
- * this helper is a safe, tested, 15-line defense-in-depth matcher that
- * hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
- * into without arc shipping a full Mongo-syntax engine.
- *
- * **When to use:**
- * - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
- * - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
- * - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
- *
- * **When NOT to use:**
- * - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
- *   native matcher (mongokit's repo does the filter at the DB layer; for
- *   custom repos, wrap the kit's own predicate engine).
- * - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
- *   applied by `getOne(compoundFilter)` already covers this.
- *
- * @example
- * ```ts
- * import { simpleEqualityMatcher } from '@classytic/arc/utils';
- *
- * // On a custom adapter
- * const adapter: DataAdapter = {
- *   repository,
- *   type: 'custom',
- *   name: 'in-memory',
- *   matchesFilter: simpleEqualityMatcher,
- * };
- *
- * // Or directly on BaseController for ad-hoc controllers
- * new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
- * ```
- */
-declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
-//#endregion
-//#region src/utils/stateMachine.d.ts
-/**
- * State Machine Utility
- *
- * Pure utility for validating state transitions in workflow systems.
- * Zero dependencies, framework-agnostic.
- *
- * @example
- * const orderState = createStateMachine('Order', {
- *   approve: ['pending', 'draft'],
- *   cancel: ['pending', 'approved'],
- *   fulfill: ['approved'],
- * });
- *
- * // Check if transition is allowed
- * if (orderState.can('approve', currentStatus)) {
- *   // Perform approval
- * }
- *
- * // Assert transition (throws if invalid)
- * orderState.assert('approve', currentStatus, ValidationError);
- */
-interface StateMachine {
-  /**
-   * Synchronously check if action can be performed from current status.
-   * Only checks the transition map — does NOT evaluate guards.
-   * Use `canAsync()` when guards need to be evaluated.
-   */
-  can(action: string, status: string | null | undefined): boolean;
-  /**
-   * Asynchronously check if action can be performed, including guard evaluation.
-   * Falls back to simple transition check when no guard is defined.
-   */
-  canAsync(action: string, status: string | null | undefined, context?: Record<string, unknown>): Promise<boolean>;
-  /**
-   * Assert action can be performed, throw error if invalid
-   * @param action - Action to perform
-   * @param status - Current status
-   * @param errorFactory - Optional error constructor
-   * @param message - Optional custom error message
-   */
-  assert(action: string, status: string | null | undefined, errorFactory?: (msg: string) => Error, message?: string): void;
-  /**
-   * Get transition history
-   */
-  getHistory?(): TransitionHistoryEntry[];
-  /**
-   * Record a transition
-   */
-  recordTransition?(from: string, to: string, action: string, metadata?: Record<string, unknown>): void;
-  /**
-   * Clear history
-   */
-  clearHistory?(): void;
-  /**
-   * Get available actions for current status
-   */
-  getAvailableActions?(status: string): string[];
-}
-interface TransitionHistoryEntry {
-  from: string;
-  to: string;
-  action: string;
-  timestamp: Date;
-  metadata?: Record<string, unknown>;
-}
-/** Context passed to transition guards and actions */
-interface TransitionContext {
-  from: string;
-  to: string;
-  action: string;
-  data?: Record<string, unknown>;
-}
-type TransitionGuard = (context: TransitionContext) => boolean | Promise<boolean>;
-type TransitionAction = (context: TransitionContext) => void | Promise<void>;
-type TransitionConfig = Record<string, string[] | {
-  from: string[];
-  to?: string;
-  guard?: TransitionGuard;
-  before?: TransitionAction;
-  after?: TransitionAction;
-}>;
-/**
- * Create a state machine for validating transitions
- *
- * @param name - Name of the state machine (used in error messages)
- * @param transitions - Map of actions to allowed source statuses
- * @param options - Additional options (history, guards, actions)
- * @returns State machine with can() and assert() methods
- *
- * @example
- * // Basic usage
- * const transferState = createStateMachine('Transfer', {
- *   approve: ['draft'],
- *   dispatch: ['approved'],
- *   receive: ['dispatched', 'in_transit'],
- *   cancel: ['draft', 'approved'],
- * });
- *
- * @example
- * // With guards and actions
- * const orderState = createStateMachine('Order', {
- *   approve: {
- *     from: ['pending'],
- *     to: 'approved',
- *     guard: ({ data }) => data.paymentConfirmed,
- *     before: ({ from, to }) => console.log(`Approving order from ${from} to ${to}`),
- *     after: ({ data }) => sendApprovalEmail(data.customerId),
- *   },
- * }, { trackHistory: true });
- */
-declare function createStateMachine(name: string, transitions?: TransitionConfig, options?: {
-  trackHistory?: boolean;
-}): StateMachine;
-//#endregion
-//#region src/utils/typeGuards.d.ts
-interface EventsDecorator {
-  publish: <T>(type: string, payload: T, meta?: Record<string, unknown>) => Promise<void>;
-  subscribe: (pattern: string, handler: (event: {
-    type: string;
-    payload: unknown;
-    meta: Record<string, unknown>;
-  }) => Promise<void>) => Promise<() => void>;
-  transportName: string;
-}
-/** Check if fastify has the events plugin registered */
-declare function hasEvents(instance: FastifyInstance): instance is FastifyInstance & {
-  events: EventsDecorator;
-};
-//#endregion
-//#region src/utils/userHelpers.d.ts
-/**
- * Extract a user ID from a user object. Accepts `id` or `_id` — returns
- * `undefined` when neither is present. Used by arc's controllers to
- * populate `createdBy` / `updatedBy` fields and for cache scoping.
- *
- * @example
- * ```ts
- * import { getUserId } from '@classytic/arc/utils';
- * const uid = getUserId(request.user);
- * ```
- */
-declare function getUserId(user: UserLike | null | undefined): string | undefined;
-//#endregion
-export { ValidateOptions as $, ArcQueryParserOptions as A, CompensationResult as B, keysetListResponse as C, queryParams as D, paginationSchema as E, defineGuard as F, CircuitBreakerError as G, defineCompensation as H, defineErrorMapper as I, CircuitBreakerStats as J, CircuitBreakerOptions as K, CompensationDefinition as L, handleRaw as M, Guard as N, responses as O, GuardConfig as P, ConfigError as Q, CompensationError as R, getListQueryParams as S, offsetListResponse as T, withCompensation as U, CompensationStep as V, CircuitBreaker as W, createCircuitBreaker as X, CircuitState as Y, createCircuitBreakerRegistry as Z, bareListResponse as _, isArcError as _t, TransitionConfig as a, ConflictError as at, errorDetailSchema$1 as b, JsonSchemaTarget as c, NotFoundError as ct, isJsonSchema as d, RateLimitError as dt, ValidationResult as et, isZodSchema as f, ServiceUnavailableError as ft, aggregateListResponse as g, createError as gt, JsonSchema as h, createDomainError as ht, StateMachine as i, ArcError as it, createQueryParser as j, ArcQueryParser as k, convertOpenApiSchemas as l, OrgAccessDeniedError as lt, scheduleBackground as m, ValidationError as mt, EventsDecorator as n, formatValidationErrors as nt, createStateMachine as o, ErrorOptions as ot, toJsonSchema as p, UnauthorizedError as pt, CircuitBreakerRegistry as q, hasEvents as r, validateResourceConfig as rt, simpleEqualityMatcher as s, ForbiddenError as st, getUserId as t, assertValidConfig as tt, convertRouteSchema as u, OrgRequiredError as ut, deleteResponse as v, listResponse as w, getDefaultCrudSchemas as x, errorContractSchema$1 as y, CompensationHooks as z };