@classytic/arc 2.10.3 → 2.11.0

package/dist/index-DsJ1MNfC.d.mts

@@ -0,0 +1,1179 @@
+import { $ as OpenApiSchemas, Pt as AnyRecord, S as QueryParserInterface, at as ResourceConfig, b as ParsedQuery, zt as UserLike } from "./index-Cm0vUrr_.mjs";
+import { n as ErrorMapper } from "./errorHandler-Co3lnVmJ.mjs";
+import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
+
+//#region src/utils/errors.d.ts
+/**
+ * Error Classes
+ *
+ * Standard error types for the Arc framework.
+ */
+interface ErrorDetails {
+  code?: string;
+  statusCode?: number;
+  details?: Record<string, unknown>;
+  cause?: Error;
+  requestId?: string;
+}
+/**
+ * Base Arc Error
+ *
+ * All Arc errors extend this class and produce a consistent error envelope:
+ * {
+ *   success: false,
+ *   error: "Human-readable message",
+ *   code: "MACHINE_CODE",
+ *   requestId: "uuid",     // For tracing
+ *   timestamp: "ISO date", // When error occurred
+ *   details: { ... }       // Additional context
+ * }
+ */
+declare class ArcError extends Error {
+  name: string;
+  readonly code: string;
+  readonly statusCode: number;
+  readonly details?: Record<string, unknown>;
+  readonly cause?: Error;
+  readonly timestamp: string;
+  requestId?: string;
+  constructor(message: string, options?: ErrorDetails);
+  /**
+   * Set request ID (typically from request context)
+   */
+  withRequestId(requestId: string): this;
+  /**
+   * Convert to JSON response.
+   * Includes cause chain when present for debugging visibility.
+   */
+  toJSON(): Record<string, unknown>;
+}
+/**
+ * Not Found Error - 404
+ */
+declare class NotFoundError extends ArcError {
+  constructor(resource: string, identifier?: string);
+}
+/**
+ * Validation Error - 400
+ */
+declare class ValidationError extends ArcError {
+  readonly errors: Array<{
+    field: string;
+    message: string;
+  }>;
+  constructor(message: string, errors?: Array<{
+    field: string;
+    message: string;
+  }>);
+}
+/**
+ * Unauthorized Error - 401
+ */
+declare class UnauthorizedError extends ArcError {
+  constructor(message?: string);
+}
+/**
+ * Forbidden Error - 403
+ */
+declare class ForbiddenError extends ArcError {
+  constructor(message?: string);
+}
+/**
+ * Conflict Error - 409
+ */
+declare class ConflictError extends ArcError {
+  constructor(message: string, field?: string);
+}
+/**
+ * Organization Required Error - 403
+ */
+declare class OrgRequiredError extends ArcError {
+  readonly organizations?: Array<{
+    id: string;
+    roles?: string[];
+  }>;
+  constructor(message: string, organizations?: Array<{
+    id: string;
+    roles?: string[];
+  }>);
+}
+/**
+ * Organization Access Denied Error - 403
+ */
+declare class OrgAccessDeniedError extends ArcError {
+  constructor(orgId?: string);
+}
+/**
+ * Rate Limit Error - 429
+ */
+declare class RateLimitError extends ArcError {
+  readonly retryAfter?: number;
+  constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Service Unavailable Error - 503
+ */
+declare class ServiceUnavailableError extends ArcError {
+  constructor(message?: string);
+}
+/**
+ * Create error from status code
+ */
+declare function createError(statusCode: number, message: string, details?: Record<string, unknown>): ArcError;
+/**
+ * Create a domain-specific error with automatic HTTP status mapping.
+ *
+ * Eliminates manual `if (err.code === 'X') return status` boilerplate.
+ * Arc's error handler automatically maps `statusCode` to HTTP response.
+ *
+ * @example
+ * ```typescript
+ * import { createDomainError } from '@classytic/arc';
+ *
+ * throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
+ * throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+ * throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
+ * ```
+ */
+declare function createDomainError(code: string, message: string, statusCode?: number, details?: Record<string, unknown>): ArcError;
+/**
+ * Check if error is an Arc error
+ */
+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/envelope.d.ts
+/**
+ * Standard response envelope helper.
+ *
+ * Wraps a handler return value in arc's `{ success: true, data, ...meta }`
+ * shape. Pure utility — no types module coupling, no runtime dependencies.
+ *
+ * @example
+ * ```ts
+ * import { envelope } from '@classytic/arc';
+ *
+ * handler: async (req, reply) => {
+ *   const results = await search(req.query.q);
+ *   return envelope(results, { took: performance.now() - t0 });
+ * }
+ * ```
+ */
+/**
+ * Wrap data in arc's standard `{ success: true, data }` envelope, with
+ * optional top-level meta keys merged in.
+ */
+declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
+  success: true;
+  data: T;
+  [key: string]: unknown;
+};
+//#endregion
+//#region src/utils/handleRaw.d.ts
+/**
+ * Wrap a raw Fastify handler with Arc's response envelope and error handling.
+ *
+ * @param handler - Async function that receives `(request, reply)` and returns data.
+ *   The return value is sent as `{ success: true, data }`. If it returns
+ *   `undefined` or `null`, `{ success: true }` is sent (no `data` field).
+ * @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 {
+  type: string;
+  properties?: Record<string, JsonSchema | AnyRecord>;
+  required?: string[];
+  items?: JsonSchema | AnyRecord;
+  additionalProperties?: boolean | JsonSchema;
+  description?: string;
+  example?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * Base success response schema
+ */
+declare const successResponseSchema: JsonSchema;
+/**
+ * Error response schema
+ */
+declare const errorResponseSchema: JsonSchema;
+/**
+ * Pagination schema - matches MongoKit/Arc runtime format
+ *
+ * Runtime format (flat fields):
+ * { page, limit, total, pages, hasNext, hasPrev }
+ */
+declare const paginationSchema: JsonSchema;
+/**
+ * Wrap a data schema in a success response
+ */
+declare function wrapResponse(dataSchema: JsonSchema): JsonSchema;
+/**
+ * Create a list response schema with pagination - matches MongoKit/Arc runtime format
+ *
+ * Runtime format:
+ * { success, docs: [...], page, limit, total, pages, hasNext, hasPrev }
+ *
+ * Note: Uses 'docs' array (not 'data') with flat pagination fields
+ */
+declare function listResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a single item response schema
+ *
+ * Runtime format: { success, data: {...} }
+ */
+declare function itemResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a create/update response schema
+ */
+declare function mutationResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a delete response schema
+ *
+ * Runtime format: { success, data: { message, id?, soft? } }
+ */
+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: JsonSchema;
+      };
+    };
+  };
+  400: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+            details: {
+              type: string;
+              properties: {
+                errors: {
+                  type: string;
+                  items: {
+                    type: string;
+                    properties: {
+                      field: {
+                        type: string;
+                      };
+                      message: {
+                        type: string;
+                      };
+                    };
+                  };
+                };
+              };
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  401: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  403: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  404: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  409: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  500: {
+    description: string;
+    content: {
+      "application/json": {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+};
+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/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 { ValidationResult as $, handleRaw as A, CompensationStep as B, queryParams as C, ArcQueryParser as D, wrapResponse as E, defineErrorMapper as F, CircuitBreakerOptions as G, withCompensation as H, CompensationDefinition as I, CircuitState as J, CircuitBreakerRegistry as K, CompensationError as L, Guard as M, GuardConfig as N, ArcQueryParserOptions as O, defineGuard as P, ValidateOptions as Q, CompensationHooks as R, paginationSchema as S, successResponseSchema as T, CircuitBreaker as U, defineCompensation as V, CircuitBreakerError as W, createCircuitBreakerRegistry as X, createCircuitBreaker as Y, ConfigError as Z, getDefaultCrudSchemas as _, TransitionConfig as a, ErrorDetails as at, listResponse as b, JsonSchemaTarget as c, OrgAccessDeniedError as ct, isJsonSchema as d, ServiceUnavailableError as dt, assertValidConfig as et, isZodSchema as f, UnauthorizedError as ft, errorResponseSchema as g, isArcError as gt, deleteResponse as h, createError as ht, StateMachine as i, ConflictError as it, envelope as j, createQueryParser as k, convertOpenApiSchemas as l, OrgRequiredError as lt, JsonSchema as m, createDomainError as mt, EventsDecorator as n, validateResourceConfig as nt, createStateMachine as o, ForbiddenError as ot, toJsonSchema as p, ValidationError as pt, CircuitBreakerStats as q, hasEvents as r, ArcError as rt, simpleEqualityMatcher as s, NotFoundError as st, getUserId as t, formatValidationErrors as tt, convertRouteSchema as u, RateLimitError as ut, getListQueryParams as v, responses as w, mutationResponse as x, itemResponse as y, CompensationResult as z };