@classytic/arc 2.2.5 → 2.4.1

package/dist/interface-DGmPxakH.d.mts

@@ -0,0 +1,2213 @@
+import { s as RequestScope } from "./elevation-Ca_yveIO.mjs";
+import { n as FieldPermissionMap } from "./fields-DFwdaWCq.mjs";
+import { i as UserBase, t as PermissionCheck } from "./types-BNUccdcf.mjs";
+import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
+
+//#region src/hooks/HookSystem.d.ts
+type HookPhase = "before" | "around" | "after";
+type HookOperation = "create" | "update" | "delete" | "read" | "list";
+interface HookContext<T = AnyRecord> {
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  data?: T;
+  result?: T | T[];
+  user?: UserBase;
+  context?: RequestContext;
+  meta?: AnyRecord;
+}
+type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
+/**
+ * Around hook handler — wraps the core operation.
+ * Call `next()` to proceed to the next around hook or the actual operation.
+ */
+type AroundHookHandler<T = AnyRecord> = (ctx: HookContext<T>, next: () => Promise<T | undefined>) => T | undefined | Promise<T | undefined>;
+interface HookRegistration {
+  /** Hook name for dependency resolution and debugging */
+  name?: string;
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  handler: HookHandler;
+  priority: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+interface HookSystemOptions {
+  /** Custom logger for error/warning reporting. Defaults to console */
+  logger?: {
+    error: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+  };
+}
+declare class HookSystem {
+  private hooks;
+  private logger;
+  private warn;
+  constructor(options?: HookSystemOptions);
+  /**
+   * Generate hook key
+   */
+  private getKey;
+  /**
+   * Register a hook
+   * Supports both object parameter and positional arguments
+   */
+  register<T = AnyRecord>(resourceOrOptions: string | {
+    name?: string;
+    resource: string;
+    operation: HookOperation;
+    phase: HookPhase;
+    handler: HookHandler<T>;
+    priority?: number;
+    dependsOn?: string[];
+  }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register before hook
+   */
+  before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register after hook
+   */
+  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register around hook — wraps the core operation.
+   * Call `next()` inside the handler to proceed.
+   */
+  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
+  /**
+   * Execute around hooks as a nested middleware chain.
+   * Each around hook receives `next()` to call the next hook or the core operation.
+   */
+  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T | undefined>;
+  /**
+   * Execute hooks for a given context
+   */
+  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
+  /**
+   * Execute before hooks
+   */
+  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T>;
+  /**
+   * Execute after hooks
+   * Errors in after hooks are logged but don't fail the request
+   */
+  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<void>;
+  /**
+   * Topological sort with Kahn's algorithm.
+   * Hooks with `dependsOn` are ordered after their dependencies.
+   * Within the same dependency level, priority ordering is preserved.
+   * Hooks without names or dependencies pass through in their original order.
+   */
+  private topologicalSort;
+  /**
+   * Get all registered hooks
+   */
+  getAll(): HookRegistration[];
+  /**
+   * Get hooks for a specific resource
+   */
+  getForResource(resource: string): HookRegistration[];
+  /**
+   * Get hooks matching filter criteria.
+   * Useful for debugging and testing specific hook combinations.
+   *
+   * @example
+   * ```typescript
+   * // Find all before-create hooks for products (including wildcards)
+   * const hooks = hookSystem.getRegistered({
+   *   resource: 'product',
+   *   operation: 'create',
+   *   phase: 'before',
+   * });
+   * ```
+   */
+  getRegistered(filter?: {
+    resource?: string;
+    operation?: HookOperation;
+    phase?: HookPhase;
+  }): HookRegistration[];
+  /**
+   * Get a structured summary of all registered hooks for debugging.
+   *
+   * @example
+   * ```typescript
+   * const info = hookSystem.inspect();
+   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
+   * ```
+   */
+  inspect(): {
+    total: number;
+    resources: Record<string, HookRegistration[]>;
+    summary: Array<{
+      name?: string;
+      key: string;
+      priority: number;
+      dependsOn?: string[];
+    }>;
+  };
+  /**
+   * Check if any hooks exist for a specific resource/operation/phase combination.
+   */
+  has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
+  /**
+   * Clear all hooks
+   */
+  clear(): void;
+  /**
+   * Clear hooks for a specific resource
+   */
+  clearResource(resource: string): void;
+}
+/**
+ * Create a new isolated HookSystem instance
+ *
+ * Use this for:
+ * - Test isolation (parallel test suites)
+ * - Multiple app instances with independent hooks
+ *
+ * @example
+ * const hooks = createHookSystem();
+ * await app.register(arcCorePlugin, { hookSystem: hooks });
+ *
+ * @example With custom logger
+ * const hooks = createHookSystem({ logger: fastify.log });
+ */
+declare function createHookSystem(options?: HookSystemOptions): HookSystem;
+interface DefineHookOptions<T = AnyRecord> {
+  /** Unique hook name (required for dependency resolution) */
+  name: string;
+  /** Target resource */
+  resource: string;
+  /** CRUD operation */
+  operation: HookOperation;
+  /** before or after */
+  phase: HookPhase;
+  /** Hook handler */
+  handler: HookHandler<T>;
+  /** Priority (lower = earlier, default: 10) */
+  priority?: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+/**
+ * Define a named hook with optional dependencies.
+ * Returns a registration object — call `register(hookSystem)` to activate.
+ *
+ * @example
+ * ```typescript
+ * const generateSlug = defineHook({
+ *   name: 'generateSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   handler: (ctx) => ({ ...ctx.data, slug: slugify(ctx.data.name) }),
+ * });
+ *
+ * const validateUniqueSlug = defineHook({
+ *   name: 'validateUniqueSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   dependsOn: ['generateSlug'],
+ *   handler: async (ctx) => { // check uniqueness },
+ * });
+ *
+ * // Register on a hook system
+ * generateSlug.register(hooks);
+ * validateUniqueSlug.register(hooks);
+ * ```
+ */
+declare function defineHook<T = AnyRecord>(options: DefineHookOptions<T>): DefineHookOptions<T> & {
+  register: (hooks: HookSystem) => () => void;
+};
+/**
+ * Create a before-create hook registration for a given hook system
+ */
+declare function beforeCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-create hook registration for a given hook system
+ */
+declare function afterCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-update hook registration for a given hook system
+ */
+declare function beforeUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-update hook registration for a given hook system
+ */
+declare function afterUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-delete hook registration for a given hook system
+ */
+declare function beforeDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-delete hook registration for a given hook system
+ */
+declare function afterDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+//#endregion
+//#region src/pipeline/types.d.ts
+/**
+ * Pipeline context passed to guards, transforms, and interceptors.
+ * Extends IRequestContext with pipeline-specific metadata.
+ */
+interface PipelineContext extends IRequestContext {
+  /** Resource name being accessed */
+  resource: string;
+  /** CRUD operation being performed */
+  operation: "list" | "get" | "create" | "update" | "delete" | string;
+}
+/**
+ * Which operations a pipeline step applies to.
+ * If omitted, applies to ALL operations.
+ */
+type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
+/**
+ * Guard — boolean check that short-circuits on failure.
+ * Return true to proceed, throw to deny.
+ */
+interface Guard {
+  readonly _type: "guard";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): boolean | Promise<boolean>;
+}
+/**
+ * Transform — modifies request data before the handler.
+ * Returns modified context (or mutates in place).
+ */
+interface Transform {
+  readonly _type: "transform";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): PipelineContext | undefined | Promise<PipelineContext | undefined>;
+}
+/**
+ * Next function passed to interceptors — calls the handler (or next interceptor).
+ */
+type NextFunction = () => Promise<IControllerResponse<unknown>>;
+/**
+ * Intercept — wraps handler execution (before + after pattern).
+ */
+interface Interceptor {
+  readonly _type: "interceptor";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
+}
+type PipelineStep = Guard | Transform | Interceptor;
+/**
+ * Pipeline configuration — can be a flat array or per-operation map.
+ */
+type PipelineConfig = PipelineStep[] | {
+  list?: PipelineStep[];
+  get?: PipelineStep[];
+  create?: PipelineStep[];
+  update?: PipelineStep[];
+  delete?: PipelineStep[];
+  [operation: string]: PipelineStep[] | undefined;
+};
+//#endregion
+//#region src/types/repository.d.ts
+/**
+ * Repository Interface - Database-Agnostic CRUD Operations
+ *
+ * This is the standard interface that all repositories must implement.
+ * MongoKit Repository already implements this interface.
+ *
+ * @example
+ * ```typescript
+ * import type { CrudRepository } from '@classytic/arc';
+ *
+ * // Your repository automatically satisfies this interface
+ * const userRepo: CrudRepository<UserDocument> = new Repository(UserModel);
+ * ```
+ */
+/**
+ * Query options for read operations
+ */
+interface QueryOptions {
+  /** Transaction session — adapters handle the actual type (e.g., Mongoose ClientSession) */
+  session?: unknown;
+  /** Field selection - include or exclude fields */
+  select?: string | string[] | Record<string, 0 | 1>;
+  /** Relations to populate - string, array, or Mongoose populate options */
+  populate?: string | string[] | Record<string, unknown>;
+  /** Return plain JS objects instead of Mongoose documents */
+  lean?: boolean;
+  /** Allow additional adapter-specific options */
+  [key: string]: unknown;
+}
+/**
+ * Pagination parameters for list operations
+ */
+interface PaginationParams<TDoc = unknown> {
+  /** Filter criteria */
+  filters?: Partial<TDoc> & Record<string, unknown>;
+  /** Sort specification - string ("-createdAt") or object ({ createdAt: -1 }) */
+  sort?: string | Record<string, 1 | -1>;
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Items per page */
+  limit?: number;
+  /** Allow additional options (select, populate, etc.) */
+  [key: string]: unknown;
+}
+/**
+ * Paginated result from list operations
+ */
+interface PaginatedResult<TDoc> {
+  /** Documents for current page */
+  docs: TDoc[];
+  /** Current page number */
+  page: number;
+  /** Items per page */
+  limit: number;
+  /** Total document count */
+  total: number;
+  /** Total page count */
+  pages: number;
+  /** Has next page */
+  hasNext: boolean;
+  /** Has previous page */
+  hasPrev: boolean;
+}
+/**
+ * Standard CRUD Repository Interface
+ *
+ * Defines the contract for data access operations.
+ * All database adapters (MongoKit, Prisma, etc.) implement this interface.
+ *
+ * @typeParam TDoc - The document/entity type
+ */
+interface CrudRepository<TDoc> {
+  /**
+   * Get paginated list of documents
+   */
+  getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginatedResult<TDoc>>;
+  /**
+   * Get single document by ID
+   */
+  getById(id: string, options?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * Create new document
+   */
+  create(data: Partial<TDoc>, options?: {
+    session?: unknown;
+    [key: string]: unknown;
+  }): Promise<TDoc>;
+  /**
+   * Update document by ID
+   */
+  update(id: string, data: Partial<TDoc>, options?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * Delete document by ID
+   */
+  delete(id: string, options?: {
+    session?: unknown;
+    [key: string]: unknown;
+  }): Promise<{
+    success: boolean;
+    message: string;
+  }>;
+  /** Allow custom methods (getBySlug, getTree, restore, etc.) */
+  [key: string]: unknown;
+}
+/**
+ * Extract document type from a repository
+ *
+ * @example
+ * ```typescript
+ * type UserDoc = InferDoc<typeof userRepository>;
+ * // UserDoc is now the document type of userRepository
+ * ```
+ */
+type InferDoc<R> = R extends CrudRepository<infer T> ? T : never;
+//#endregion
+//#region src/core/defineResource.d.ts
+/**
+ * Define a resource with database adapter
+ *
+ * This is the MAIN entry point for creating Arc resources.
+ * The adapter provides both repository and schema metadata.
+ */
+declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
+interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
+  _appliedPresets?: string[];
+  _controllerOptions?: {
+    slugField?: string;
+    parentField?: string;
+    [key: string]: unknown;
+  };
+  _pendingHooks?: Array<{
+    operation: "create" | "update" | "delete" | "read" | "list";
+    phase: "before" | "after";
+    handler: (ctx: AnyRecord) => unknown;
+    priority: number;
+  }>;
+}
+declare class ResourceDefinition<TDoc = AnyRecord> {
+  readonly name: string;
+  readonly displayName: string;
+  readonly tag: string;
+  readonly prefix: string;
+  readonly adapter?: DataAdapter<TDoc>;
+  readonly controller?: IController<TDoc>;
+  readonly schemaOptions: RouteSchemaOptions;
+  readonly customSchemas: CrudSchemas;
+  readonly permissions: ResourcePermissions;
+  readonly additionalRoutes: AdditionalRoute[];
+  readonly middlewares: MiddlewareConfig;
+  readonly disableDefaultRoutes: boolean;
+  readonly disabledRoutes: CrudRouteKey[];
+  readonly events: Record<string, EventDefinition>;
+  readonly rateLimit?: RateLimitConfig | false;
+  readonly updateMethod?: "PUT" | "PATCH" | "both";
+  readonly pipe?: PipelineConfig;
+  readonly fields?: FieldPermissionMap;
+  readonly cache?: ResourceCacheConfig;
+  readonly tenantField?: string | false;
+  readonly idField?: string;
+  readonly queryParser?: QueryParserInterface;
+  readonly _appliedPresets: string[];
+  _pendingHooks: Array<{
+    operation: "create" | "update" | "delete" | "read" | "list";
+    phase: "before" | "after";
+    handler: (ctx: AnyRecord) => unknown;
+    priority: number;
+  }>;
+  _registryMeta?: RegisterOptions;
+  constructor(config: ResolvedResourceConfig<TDoc>);
+  /** Get repository from adapter (if available) */
+  get repository(): RepositoryLike | CrudRepository<TDoc> | undefined;
+  _validateControllerMethods(): void;
+  toPlugin(): FastifyPluginAsync;
+  /**
+   * Get event definitions for registry
+   */
+  getEvents(): Array<{
+    name: string;
+    module: string;
+    schema?: AnyRecord;
+    description?: string;
+  }>;
+  /**
+   * Get resource metadata
+   */
+  getMetadata(): ResourceMetadata;
+}
+//#endregion
+//#region src/registry/ResourceRegistry.d.ts
+interface RegisterOptions {
+  module?: string;
+  /** Pre-generated OpenAPI schemas */
+  openApiSchemas?: OpenApiSchemas;
+}
+declare class ResourceRegistry {
+  private _resources;
+  private _frozen;
+  constructor();
+  /**
+   * Register a resource
+   */
+  register(resource: ResourceDefinition<unknown>, options?: RegisterOptions): this;
+  /**
+   * Get resource by name
+   */
+  get(name: string): RegistryEntry | undefined;
+  /**
+   * Get all resources
+   */
+  getAll(): RegistryEntry[];
+  /**
+   * Get resources by module
+   */
+  getByModule(moduleName: string): RegistryEntry[];
+  /**
+   * Get resources by preset
+   */
+  getByPreset(presetName: string): RegistryEntry[];
+  /**
+   * Check if resource exists
+   */
+  has(name: string): boolean;
+  /**
+   * Get registry statistics
+   */
+  getStats(): RegistryStats;
+  /**
+   * Get full introspection data
+   */
+  getIntrospection(): IntrospectionData;
+  /**
+   * Freeze registry (prevent further registrations)
+   */
+  freeze(): void;
+  /**
+   * Check if frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Unfreeze registry (allow new registrations)
+   */
+  unfreeze(): void;
+  /**
+   * Reset registry — clear all resources and unfreeze
+   */
+  reset(): void;
+  /** @internal Alias for unfreeze() */
+  _unfreeze(): void;
+  /** @internal Alias for reset() */
+  _clear(): void;
+  /**
+   * Group by key
+   */
+  private _groupBy;
+}
+//#endregion
+//#region src/types/handlers.d.ts
+/**
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `wrapHandler: false`.
+ */
+interface ServerAccessor {
+  /** Event bus — publish domain events from any handler */
+  events?: {
+    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
+  };
+  /** Audit logger — log custom audit entries */
+  audit?: {
+    create: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+  };
+  /** Logger — structured logging */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+  /** QueryCache — stale-while-revalidate data cache */
+  queryCache?: {
+    get: <T>(key: string) => Promise<{
+      data: T;
+      status: 'fresh' | 'stale' | 'miss';
+    }>;
+    set: <T>(key: string, data: T, config: {
+      staleTime?: number;
+      gcTime?: number;
+      tags?: string[];
+    }) => Promise<void>;
+    getResourceVersion: (resource: string) => Promise<number>;
+    bumpResourceVersion: (resource: string) => Promise<void>;
+  };
+}
+/**
+ * Request context passed to controller handlers
+ */
+interface IRequestContext {
+  /** Route parameters (e.g., { id: '123' }) */
+  params: Record<string, string>;
+  /** Query string parameters */
+  query: Record<string, unknown>;
+  /** Request body */
+  body: unknown;
+  /** Authenticated user or null */
+  user: UserBase | null;
+  /** Request headers */
+  headers: Record<string, string | undefined>;
+  /** Organization ID (for multi-tenant apps) */
+  organizationId?: string;
+  /** Team ID (for team-scoped resources) */
+  teamId?: string;
+  /**
+   * Organization/auth context from middleware.
+   * Contains orgRoles, orgScope, organizationId, and any custom fields
+   * set by the auth adapter or org-scope plugin.
+   *
+   * @example
+   * ```typescript
+   * async create(req: IRequestContext) {
+   *   const roles = req.context?.orgRoles ?? [];
+   *   if (roles.includes('manager')) { ... }
+   * }
+   * ```
+   */
+  context?: RequestContext;
+  /** Internal metadata (includes context + Arc internals like _policyFilters, log) */
+  metadata?: Record<string, unknown>;
+  /**
+   * Fastify server accessor — publish events, log, and audit
+   * from any handler without switching to `wrapHandler: false`.
+   *
+   * @example
+   * ```typescript
+   * async reschedule(req: IRequestContext) {
+   *   const result = await repo.reschedule(req.params.id, req.body);
+   *   await req.server?.events?.publish('interview.rescheduled', { data: result });
+   *   return { success: true, data: result };
+   * }
+   * ```
+   */
+  server?: ServerAccessor;
+}
+/**
+ * Standard response from controller handlers
+ */
+interface IControllerResponse<T = unknown> {
+  /** Operation success status */
+  success: boolean;
+  /** Response data */
+  data?: T;
+  /** Error message (when success is false) */
+  error?: string;
+  /** HTTP status code (default: 200 for success, 400 for error) */
+  status?: number;
+  /** Additional metadata */
+  meta?: Record<string, unknown>;
+  /** Error details (for debugging) */
+  details?: Record<string, unknown>;
+  /** Custom response headers (e.g., X-Total-Count, Link, ETag) */
+  headers?: Record<string, string>;
+}
+/**
+ * Controller handler - Arc's standard pattern
+ *
+ * Receives a request context object, returns IControllerResponse.
+ * Use with `wrapHandler: true` in additionalRoutes.
+ *
+ * @example
+ * ```typescript
+ * const createProduct: ControllerHandler<Product> = async (req) => {
+ *   const product = await productRepo.create(req.body);
+ *   return { success: true, data: product, status: 201 };
+ * };
+ *
+ * additionalRoutes: [{
+ *   method: 'POST',
+ *   path: '/products',
+ *   handler: createProduct,
+ *   permissions: requireAuth(),
+ *   wrapHandler: true,  // Arc wraps this into Fastify handler
+ * }]
+ * ```
+ */
+type ControllerHandler<T = unknown> = (req: IRequestContext) => Promise<IControllerResponse<T>>;
+/**
+ * Fastify native handler
+ *
+ * Standard Fastify request/reply pattern.
+ * Use with `wrapHandler: false` in additionalRoutes.
+ *
+ * @example
+ * ```typescript
+ * const downloadFile: FastifyHandler = async (request, reply) => {
+ *   const file = await getFile(request.params.id);
+ *   reply.header('Content-Type', file.mimeType);
+ *   return reply.send(file.buffer);
+ * };
+ *
+ * additionalRoutes: [{
+ *   method: 'GET',
+ *   path: '/files/:id/download',
+ *   handler: downloadFile,
+ *   permissions: requireAuth(),
+ *   wrapHandler: false,  // Use as-is, no wrapping
+ * }]
+ * ```
+ */
+type FastifyHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
+/**
+ * Union type for route handlers
+ */
+type RouteHandler = ControllerHandler | FastifyHandler;
+/**
+ * Controller interface for CRUD operations (strict)
+ */
+interface IController<TDoc = unknown> {
+  list(req: IRequestContext): Promise<IControllerResponse<{
+    docs: TDoc[];
+    total: number;
+  }>>;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+  }>>;
+}
+/**
+ * Flexible controller interface - accepts controllers with any handler style
+ * Use this when your controller uses Fastify native handlers
+ */
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/core/AccessControl.d.ts
+interface AccessControlConfig {
+  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable org filtering. */
+  tenantField: string | false;
+  /** Primary key field name (default: '_id') */
+  idField: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
+   * Falls back to built-in MongoDB-style matching if not provided.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+}
+/** Minimal repository interface for access-controlled fetch operations */
+interface AccessControlRepository {
+  getById(id: string, options?: unknown): Promise<unknown>;
+  getOne?: (filter: AnyRecord, options?: unknown) => Promise<unknown>;
+}
+declare class AccessControl {
+  private readonly tenantField;
+  private readonly idField;
+  private readonly _adapterMatchesFilter?;
+  /** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
+   *  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
+  private static readonly DANGEROUS_REGEX;
+  /** Forbidden paths that could lead to prototype pollution */
+  private static readonly FORBIDDEN_PATHS;
+  constructor(config: AccessControlConfig);
+  /**
+   * Build filter for single-item operations (get/update/delete)
+   * Combines ID filter with policy/org filters for proper security enforcement
+   */
+  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
+  /**
+   * Check if item matches policy filters (for get/update/delete operations)
+   * Validates that fetched item satisfies all policy constraints
+   *
+   * Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
+   * otherwise falls back to built-in MongoDB-style matching.
+   */
+  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
+  /**
+   * Check org/tenant scope for a document — uses configurable tenantField.
+   *
+   * SECURITY: When org scope is active (orgId present), documents that are
+   * missing the tenant field are DENIED by default. This prevents legacy or
+   * unscoped records from leaking across tenants.
+   */
+  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
+  /** Check ownership for update/delete (ownedByUser preset) */
+  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
+  /**
+   * Fetch a single document with full access control enforcement.
+   * Combines compound DB filter (ID + org + policy) with post-hoc fallback.
+   *
+   * Takes repository as a parameter to avoid coupling.
+   *
+   * Replaces the duplicated pattern in get/update/delete:
+   *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
+   */
+  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: unknown): Promise<TDoc | null>;
+  /**
+   * Post-fetch access control validation for items fetched by non-ID queries
+   * (e.g., getBySlug, restore). Applies org scope, policy filters, and
+   * ownership checks — the same guarantees as fetchWithAccessControl.
+   */
+  validateItemAccess(item: AnyRecord | null, req: IRequestContext): boolean;
+  /** Extract typed Arc internal metadata from request */
+  private _meta;
+  /**
+   * Check if a value matches a MongoDB query operator
+   */
+  private matchesOperator;
+  /**
+   * Check if item matches a single filter condition
+   * Supports nested paths (e.g., "owner.id", "metadata.status")
+   */
+  private matchesFilter;
+  /**
+   * Built-in MongoDB-style policy filter matching.
+   * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+   */
+  private defaultMatchesPolicyFilters;
+  /**
+   * Get nested value from object using dot notation (e.g., "owner.id")
+   * Security: Validates path against forbidden patterns to prevent prototype pollution
+   */
+  private getNestedValue;
+  /**
+   * Create a safe RegExp from a string, guarding against ReDoS.
+   * Returns null if the pattern is invalid or dangerous.
+   */
+  private static safeRegex;
+}
+//#endregion
+//#region src/core/BodySanitizer.d.ts
+interface BodySanitizerConfig {
+  /** Schema options for field sanitization */
+  schemaOptions: RouteSchemaOptions;
+}
+declare class BodySanitizer {
+  private schemaOptions;
+  constructor(config: BodySanitizerConfig);
+  /**
+   * Strip readonly and system-managed fields from request body.
+   * Prevents clients from overwriting _id, timestamps, __v, etc.
+   *
+   * Also applies field-level write permissions when the request has
+   * field permission metadata.
+   */
+  sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
+}
+//#endregion
+//#region src/core/QueryResolver.d.ts
+interface QueryResolverConfig {
+  /** Query parser instance (default: Arc built-in parser) */
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
+  /** Default sort field (default: '-createdAt') */
+  defaultSort?: string;
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
+  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable. */
+  tenantField?: string | false;
+}
+declare class QueryResolver {
+  private queryParser;
+  private maxLimit;
+  private defaultLimit;
+  private defaultSort;
+  private schemaOptions;
+  private tenantField;
+  constructor(config?: QueryResolverConfig);
+  /**
+   * Resolve a request into parsed query options -- ONE parse per request.
+   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
+   */
+  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
+  /**
+   * Sanitize select — preserves the input format (string, array, or object).
+   * This is critical for db-agnostic support: MongoKit returns object projections,
+   * Mongoose uses space-separated strings, SQL adapters may use arrays.
+   */
+  private sanitizeSelectAny;
+  /** Sanitize populate fields */
+  private sanitizePopulate;
+  /** Sanitize advanced populate options against allowedPopulate */
+  private sanitizePopulateOptions;
+  /**
+   * Sanitize lookup/join options.
+   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
+   * Validates lookup structure to prevent injection.
+   */
+  private sanitizeLookups;
+  /** Get blocked fields from schema options */
+  private getBlockedFields;
+}
+//#endregion
+//#region src/core/BaseController.d.ts
+interface BaseControllerOptions {
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
+  /**
+   * Query parser instance.
+   * Default: Arc built-in query parser (adapter-agnostic).
+   * Swap in MongoKit QueryParser, pgkit parser, etc.
+   */
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
+  /** Default sort field (default: '-createdAt') */
+  defaultSort?: string;
+  /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
+  resourceName?: string;
+  /**
+   * Field name used for multi-tenant scoping (default: 'organizationId').
+   * Override to match your schema: 'workspaceId', 'tenantId', 'teamId', etc.
+   * Set to `false` to disable org filtering for platform-universal resources.
+   */
+  tenantField?: string | false;
+  /**
+   * Primary key field name (default: '_id').
+   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
+   */
+  idField?: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
+   * Falls back to built-in MongoDB-style matching if not provided.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Cache configuration for the resource */
+  cache?: ResourceCacheConfig;
+  /** Internal preset fields map (slug, tree, etc.) */
+  presetFields?: {
+    slugField?: string;
+    parentField?: string;
+  };
+}
+/**
+ * Framework-agnostic base controller implementing IController.
+ *
+ * Composes AccessControl, BodySanitizer, and QueryResolver for clean
+ * separation of concerns. CRUD methods delegate directly to these
+ * composed classes — no intermediate wrapper methods.
+ *
+ * @template TDoc - The document type
+ * @template TRepository - The repository type (defaults to RepositoryLike)
+ */
+declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
+  protected repository: TRepository;
+  protected schemaOptions: RouteSchemaOptions;
+  protected queryParser: QueryParserInterface;
+  protected maxLimit: number;
+  protected defaultLimit: number;
+  protected defaultSort: string;
+  protected resourceName?: string;
+  protected tenantField: string | false;
+  protected idField: string;
+  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
+  readonly accessControl: AccessControl;
+  /** Composable body sanitization (field permissions, system fields) */
+  readonly bodySanitizer: BodySanitizer;
+  /** Composable query resolution (parsing, pagination, sort, select/populate) */
+  readonly queryResolver: QueryResolver;
+  private _matchesFilter?;
+  private _presetFields;
+  private _cacheConfig?;
+  constructor(repository: TRepository, options?: BaseControllerOptions);
+  /**
+   * Get the tenant field name if multi-tenant scoping is enabled.
+   * Returns `undefined` when `tenantField` is `false` (platform-universal mode).
+   *
+   * Use this in subclass overrides instead of accessing `this.tenantField` directly
+   * to avoid TypeScript indexing errors with `string | false`.
+   */
+  protected getTenantField(): string | undefined;
+  /** Extract typed Arc internal metadata from request */
+  private meta;
+  /** Get hook system from request context (instance-scoped) */
+  private getHooks;
+  /** Resolve cache config for a specific operation, merging per-op overrides */
+  private resolveCacheConfig;
+  /**
+   * Extract user/org IDs from request for cache key scoping.
+   * Only includes orgId when this resource uses tenant-scoped data (tenantField is set).
+   * Universal resources (tenantField: false) get shared cache keys to avoid fragmentation.
+   */
+  private cacheScope;
+  list(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  /** Execute list query through hooks (extracted for cache revalidation) */
+  private executeListQuery;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  /** Execute get query through hooks (extracted for cache revalidation) */
+  private executeGetQuery;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+    id?: string;
+    soft?: boolean;
+  }>>;
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  bulkCreate(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>>;
+  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
+    deletedCount: number;
+  }>>;
+}
+//#endregion
+//#region src/types/index.d.ts
+declare module 'fastify' {
+  interface FastifyRequest {
+    /** Request scope — set by auth adapter, read by permissions/presets/guards */
+    scope: RequestScope;
+    /**
+     * Current user — set by auth adapter (Better Auth, JWT, custom).
+     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
+     * Guard with `if (request.user)` on routes that allow anonymous access.
+     *
+     * Note: kept as required (not `user?`) because `@fastify/jwt` declares it
+     * as required — declaration merges must have identical modifiers.
+     * The `| undefined` in the type achieves the same DX: TypeScript will
+     * flag unguarded access like `request.user.id` as possibly undefined.
+     */
+    user: Record<string, unknown> | undefined;
+    /** Policy-injected query filters (e.g. ownership, org-scoping) */
+    _policyFilters?: Record<string, unknown>;
+    /** Field mask — fields to include/exclude in responses */
+    fieldMask?: {
+      include?: string[];
+      exclude?: string[];
+    };
+    /** Arbitrary policy metadata for downstream consumers */
+    policyMetadata?: Record<string, unknown>;
+    /** Document loaded by policy middleware for ownership checks */
+    document?: unknown;
+    /** Ownership check context (field name + user field) */
+    _ownershipCheck?: Record<string, unknown>;
+  }
+}
+type AnyRecord = Record<string, unknown>;
+/** MongoDB ObjectId — accepts string or any object with a `toString()` (e.g. mongoose ObjectId). */
+type ObjectId = string | {
+  toString(): string;
+};
+/**
+ * Flexible user type that accepts any object with id/ID properties.
+ * Use this instead of `any` when dealing with user objects.
+ * Re-exports UserBase from permissions module for convenience.
+ * The actual user structure is defined by your app's auth system.
+ */
+type UserLike = UserBase & {
+  /** User email (optional) */email?: string;
+};
+/**
+ * Extract user ID from a user object (supports both id and _id)
+ */
+declare function getUserId(user: UserLike | null | undefined): string | undefined;
+type CrudController<TDoc> = IController<TDoc>;
+interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+  meta?: Record<string, unknown>;
+}
+interface UserOrganization {
+  userId: string;
+  organizationId: string;
+  [key: string]: unknown;
+}
+interface JWTPayload {
+  sub: string;
+  [key: string]: unknown;
+}
+interface RequestContext {
+  operation?: string;
+  user?: unknown;
+  filters?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * Internal metadata shape injected by Arc's Fastify adapter.
+ * Extends RequestContext with known internal fields so controllers
+ * can access them without `as AnyRecord` casts.
+ */
+interface ArcInternalMetadata extends RequestContext {
+  /** Policy filters from permission middleware */
+  _policyFilters?: Record<string, unknown>;
+  /** Request scope from scope resolution */
+  _scope?: RequestScope;
+  /** Ownership check config from ownedByUser preset */
+  _ownershipCheck?: {
+    field: string;
+    userId: string;
+  };
+  /** Arc instance references (hooks, field permissions, etc.) */
+  arc?: {
+    hooks?: HookSystem;
+    fields?: FieldPermissionMap;
+    [key: string]: unknown;
+  };
+}
+/**
+ * Controller-level query options - parsed from request query string
+ * Includes pagination, filtering, and context data
+ */
+interface ControllerQueryOptions {
+  page?: number;
+  limit?: number;
+  sort?: string | Record<string, 1 | -1>;
+  /** Simple populate (comma-separated string or array) */
+  populate?: string | string[] | Record<string, unknown>;
+  /**
+   * Advanced populate options (Mongoose-compatible)
+   * When set, takes precedence over simple `populate`
+   */
+  populateOptions?: PopulateOption[];
+  /**
+   * Lookup/join options (database-agnostic).
+   * MongoKit maps these to $lookup aggregation pipeline stages.
+   * Future adapters (PrismaKit, PgKit) would map to SQL JOINs.
+   *
+   * @example
+   * URL: ?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug
+   */
+  lookups?: LookupOption[];
+  select?: string | string[] | Record<string, 0 | 1>;
+  filters?: Record<string, unknown>;
+  search?: string;
+  lean?: boolean;
+  after?: string;
+  user?: unknown;
+  context?: Record<string, unknown>;
+  /** Allow additional options */
+  [key: string]: unknown;
+}
+/**
+ * Database-agnostic lookup/join option.
+ * Parsed from URL: ?lookup[alias][from]=collection&lookup[alias][localField]=field&lookup[alias][foreignField]=field
+ *
+ * MongoKit maps this to MongoDB $lookup aggregation.
+ * Future adapters would map to SQL JOINs or Prisma includes.
+ */
+interface LookupOption {
+  /** Source collection/table to join from */
+  from: string;
+  /** Local field to match on */
+  localField: string;
+  /** Foreign field to match on */
+  foreignField: string;
+  /** Alias for the joined data (defaults to the lookup key) */
+  as?: string;
+  /** Return a single object instead of array (default: false) */
+  single?: boolean;
+  /** Field selection on the joined collection (comma-separated) */
+  select?: string;
+}
+/**
+ * Mongoose-compatible populate option for advanced field selection
+ * Used when you need to select specific fields from populated documents
+ *
+ * @example
+ * ```typescript
+ * // URL: ?populate[author][select]=name,email
+ * // Generates: { path: 'author', select: 'name email' }
+ * ```
+ */
+interface PopulateOption {
+  /** Field path to populate */
+  path: string;
+  /** Fields to select (space-separated) */
+  select?: string;
+  /** Filter conditions for populated documents */
+  match?: Record<string, unknown>;
+  /** Query options (limit, sort, skip) */
+  options?: {
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+    skip?: number;
+  };
+  /** Nested populate configuration */
+  populate?: PopulateOption;
+}
+/**
+ * Parsed query result from QueryParser
+ * Includes pagination, sorting, filtering, etc.
+ *
+ * The index signature allows custom query parsers (like MongoKit's QueryParser)
+ * to add additional fields without breaking Arc's type system.
+ */
+interface ParsedQuery {
+  filters?: Record<string, unknown>;
+  limit?: number;
+  sort?: string | Record<string, 1 | -1>;
+  /** Simple populate (comma-separated string or array) */
+  populate?: string | string[] | Record<string, unknown>;
+  /**
+   * Advanced populate options (Mongoose-compatible)
+   * When set, takes precedence over simple `populate`
+   * @example [{ path: 'author', select: 'name email' }]
+   */
+  populateOptions?: PopulateOption[];
+  /**
+   * Lookup/join options from MongoKit QueryParser or custom parsers.
+   * Maps to $lookup in MongoDB, JOINs in SQL adapters.
+   */
+  lookups?: LookupOption[];
+  search?: string;
+  page?: number;
+  after?: string;
+  select?: string | string[] | Record<string, 0 | 1>;
+  /** Allow additional fields from custom query parsers */
+  [key: string]: unknown;
+}
+/**
+ * Query Parser Interface
+ * Implement this to create custom query parsers
+ *
+ * @example MongoKit QueryParser
+ * ```typescript
+ * import { QueryParser } from '@classytic/mongokit';
+ * const queryParser = new QueryParser();
+ * ```
+ */
+interface QueryParserInterface {
+  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+  /**
+   * Optional: Export OpenAPI schema for query parameters
+   * Use this to document query parameters in OpenAPI/Swagger
+   */
+  getQuerySchema?(): {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  /**
+   * Optional: Allowed filter fields whitelist.
+   * When set, MCP auto-derives `filterableFields` from this
+   * if `schemaOptions.filterableFields` is not explicitly configured.
+   */
+  allowedFilterFields?: readonly string[];
+  /**
+   * Optional: Allowed filter operators whitelist.
+   * Used by MCP to enrich list tool descriptions with available operators.
+   * Values are human-readable keys: 'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', etc.
+   */
+  allowedOperators?: readonly string[];
+  /**
+   * Optional: Allowed sort fields whitelist.
+   * Used by MCP to describe available sort options in list tool descriptions.
+   */
+  allowedSortFields?: readonly string[];
+}
+interface FastifyRequestExtras {
+  user?: Record<string, unknown>;
+}
+interface RequestWithExtras extends FastifyRequest {
+  /**
+   * Arc metadata - set by createCrudRouter
+   * Contains resource configuration and schema options
+   */
+  arc?: {
+    resourceName?: string;
+    schemaOptions?: RouteSchemaOptions;
+    permissions?: ResourcePermissions;
+  };
+  context?: Record<string, unknown>;
+  _policyFilters?: Record<string, unknown>;
+  fieldMask?: {
+    include?: string[];
+    exclude?: string[];
+  };
+  _ownershipCheck?: Record<string, unknown>;
+}
+type FastifyWithAuth = FastifyInstance & {
+  authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+};
+/**
+ * Arc core decorator interface
+ * Added by arcCorePlugin to provide instance-scoped hooks and registry
+ */
+interface ArcDecorator {
+  /** Instance-scoped hook system */
+  hooks: HookSystem;
+  /** Instance-scoped resource registry */
+  registry: ResourceRegistry;
+  /** Whether event emission is enabled */
+  emitEvents: boolean;
+}
+/**
+ * Events decorator interface
+ * Added by eventPlugin to provide event pub/sub
+ */
+interface EventsDecorator {
+  /** Publish an event */
+  publish: <T>(type: string, payload: T, meta?: Partial<{
+    id: string;
+    timestamp: Date;
+  }>) => Promise<void>;
+  /** Subscribe to events */
+  subscribe: (pattern: string, handler: (event: unknown) => void | Promise<void>) => Promise<() => void>;
+  /** Get transport name */
+  transportName: string;
+}
+/**
+ * Fastify instance with Arc decorators
+ * Arc adds these decorators via plugins/presets
+ */
+type FastifyWithDecorators = FastifyInstance & {
+  arc?: ArcDecorator;
+  events?: EventsDecorator;
+  authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  organizationScoped?: (options?: {
+    required?: boolean;
+  }) => RouteHandlerMethod;
+  [key: string]: unknown;
+};
+interface OwnershipCheck {
+  field: string;
+  userField?: string;
+}
+/**
+ * Per-resource rate limit configuration.
+ *
+ * Applied to all routes of the resource when `@fastify/rate-limit` is registered
+ * on the Fastify instance. Set to `false` to explicitly disable rate limiting
+ * for a resource even when a global rate limit is configured.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'product',
+ *   rateLimit: { max: 100, timeWindow: '1 minute' },
+ * });
+ * ```
+ */
+/**
+ * Per-resource cache configuration for QueryCache.
+ * Enables stale-while-revalidate, auto-invalidation on mutations,
+ * and cross-resource tag-based invalidation.
+ */
+interface ResourceCacheConfig {
+  /** Seconds data is "fresh" (no revalidation). Default: 0 */
+  staleTime?: number;
+  /** Seconds stale data stays cached (SWR window). Default: 60 */
+  gcTime?: number;
+  /** Per-operation overrides */
+  list?: {
+    staleTime?: number;
+    gcTime?: number;
+  };
+  byId?: {
+    staleTime?: number;
+    gcTime?: number;
+  };
+  /** Tags for cross-resource invalidation grouping */
+  tags?: string[];
+  /**
+   * Cross-resource invalidation: event pattern → tag targets.
+   * When matched event fires, all caches with those tags are invalidated.
+   * @example { 'category.*': ['catalog'] }
+   */
+  invalidateOn?: Record<string, string[]>;
+  /** Disable caching for this resource */
+  disabled?: boolean;
+}
+interface RateLimitConfig {
+  /** Maximum number of requests allowed within the time window */
+  max: number;
+  /** Time window for rate limiting (e.g., '1 minute', '15 seconds', '1 hour') */
+  timeWindow: string;
+}
+interface ResourceConfig<TDoc = AnyRecord> {
+  name: string;
+  displayName?: string;
+  tag?: string;
+  prefix?: string;
+  adapter?: DataAdapter<TDoc>;
+  /** Controller instance - accepts any object with CRUD methods */
+  controller?: IController<TDoc> | ControllerLike;
+  queryParser?: unknown;
+  permissions?: ResourcePermissions;
+  schemaOptions?: RouteSchemaOptions;
+  openApiSchemas?: OpenApiSchemas;
+  customSchemas?: Partial<CrudSchemas>;
+  presets?: Array<string | PresetResult | {
+    name: string;
+    [key: string]: unknown;
+  }>;
+  hooks?: ResourceHooks;
+  /**
+   * Functional pipeline — guards, transforms, and interceptors.
+   * Can be a flat array (all operations) or per-operation map.
+   *
+   * @example
+   * ```typescript
+   * import { pipe, guard, transform, intercept } from '@classytic/arc';
+   *
+   * resource('product', {
+   *   pipe: pipe(isActive, slugify, timing),
+   *   // OR per-operation:
+   *   pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
+   * });
+   * ```
+   */
+  pipe?: PipelineConfig;
+  /**
+   * Field-level permissions — control visibility and writability per role.
+   *
+   * @example
+   * ```typescript
+   * import { fields } from '@classytic/arc';
+   * fields: {
+   *   salary: fields.visibleTo(['admin', 'hr']),
+   *   password: fields.hidden(),
+   * }
+   * ```
+   */
+  fields?: FieldPermissionMap;
+  middlewares?: MiddlewareConfig;
+  additionalRoutes?: AdditionalRoute[];
+  disableCrud?: boolean;
+  disableDefaultRoutes?: boolean;
+  disabledRoutes?: CrudRouteKey[];
+  /**
+   * Field name used for multi-tenant scoping (default: 'organizationId').
+   * Override to match your schema: 'workspaceId', 'tenantId', 'teamId', etc.
+   * Takes effect when org context is present (via multiTenant preset).
+   */
+  tenantField?: string | false;
+  /**
+   * Primary key field name (default: '_id').
+   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
+   */
+  idField?: string;
+  module?: string;
+  events?: Record<string, EventDefinition>;
+  skipValidation?: boolean;
+  skipRegistry?: boolean;
+  _appliedPresets?: string[];
+  /** HTTP method for update routes. Default: 'PATCH' */
+  updateMethod?: 'PUT' | 'PATCH' | 'both';
+  /**
+   * Per-resource rate limiting.
+   * Requires `@fastify/rate-limit` to be registered on the Fastify instance.
+   * Set to `false` to disable rate limiting for this resource.
+   */
+  rateLimit?: RateLimitConfig | false;
+  /**
+   * QueryCache configuration for this resource.
+   * Enables stale-while-revalidate and auto-invalidation.
+   * Requires `queryCachePlugin` to be registered.
+   */
+  cache?: ResourceCacheConfig;
+}
+/**
+ * Resource-level permissions
+ * ONLY PermissionCheck functions allowed - no string arrays
+ */
+interface ResourcePermissions {
+  list?: PermissionCheck;
+  get?: PermissionCheck;
+  create?: PermissionCheck;
+  update?: PermissionCheck;
+  delete?: PermissionCheck;
+}
+interface ResourceHooks {
+  beforeCreate?: (data: AnyRecord) => Promise<AnyRecord> | AnyRecord;
+  afterCreate?: (doc: AnyRecord) => Promise<void> | void;
+  beforeUpdate?: (id: string, data: AnyRecord) => Promise<AnyRecord> | AnyRecord;
+  afterUpdate?: (doc: AnyRecord) => Promise<void> | void;
+  beforeDelete?: (id: string) => Promise<void> | void;
+  afterDelete?: (id: string) => Promise<void> | void;
+}
+/**
+ * Additional route definition for custom endpoints
+ */
+interface AdditionalRoute {
+  /** HTTP method */
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Route path (relative to resource prefix) */
+  path: string;
+  /**
+   * Handler - string (controller method name) or function
+   * Function can be Fastify handler or (request, reply) => Promise<unknown>
+   */
+  handler: string | RouteHandlerMethod | ((request: FastifyRequest<any>, reply: FastifyReply) => unknown);
+  /** Permission check - REQUIRED */
+  permissions: PermissionCheck;
+  /**
+   * Handler type - REQUIRED, no auto-detection
+   * true = ControllerHandler (receives context object)
+   * false = FastifyHandler (receives request, reply)
+   */
+  wrapHandler: boolean;
+  /**
+   * Logical operation name for pipeline keys and permission actions.
+   * Defaults to handler name (string handlers) or method+path slug.
+   * Prevents collisions when multiple routes share the same HTTP method.
+   *
+   * @example
+   * operation: 'listDeleted'  // Used as pipeline key and permission action
+   * operation: 'restore'
+   */
+  operation?: string;
+  /** OpenAPI summary */
+  summary?: string;
+  /** OpenAPI description */
+  description?: string;
+  /** OpenAPI tags */
+  tags?: string[];
+  /**
+   * Custom route-level middleware
+   * Can be an array of handlers or a function that receives fastify and returns handlers
+   * @example
+   * // Direct array
+   * preHandler: [myMiddleware]
+   * // Function that receives fastify (for accessing decorators)
+   * preHandler: (fastify) => [fastify.customerContext({ required: true })]
+   */
+  preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
+  /** Fastify route schema */
+  schema?: Record<string, unknown>;
+  /**
+   * MCP handler for routes with `wrapHandler: false`.
+   * When set, this route becomes an MCP tool without needing `wrapHandler: true`.
+   * The HTTP handler stays a plain Fastify handler; MCP gets a parallel entry point.
+   *
+   * @example
+   * ```typescript
+   * additionalRoutes: [{
+   *   method: 'GET',
+   *   path: '/stats',
+   *   handler: (req, reply) => reply.send(getStats()),
+   *   wrapHandler: false,
+   *   permissions: isAuthenticated,
+   *   mcpHandler: async (input) => ({
+   *     content: [{ type: 'text', text: JSON.stringify(await getStats()) }],
+   *   }),
+   * }]
+   * ```
+   */
+  mcpHandler?: (input: Record<string, unknown>) => Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
+}
+interface RouteSchemaOptions {
+  hiddenFields?: string[];
+  readonlyFields?: string[];
+  requiredFields?: string[];
+  optionalFields?: string[];
+  excludeFields?: string[];
+  /**
+   * Fields allowed for filtering in list operations.
+   * Used by MCP tool generation to build the list tool's input schema.
+   * If not set and using a QueryParser with `allowedFilterFields`, MCP auto-derives from it.
+   */
+  filterableFields?: string[];
+  fieldRules?: Record<string, {
+    systemManaged?: boolean;
+    immutable?: boolean;
+    immutableAfterCreate?: boolean;
+    optional?: boolean;
+    [key: string]: unknown;
+  }>;
+  query?: Record<string, unknown>;
+}
+interface FieldRule {
+  field: string;
+  required?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
+}
+/**
+ * CRUD Route Schemas (Fastify Native Format)
+ *
+ * @example
+ * {
+ *   list: {
+ *     querystring: { type: 'object', properties: { page: { type: 'number' } } },
+ *     response: { 200: { type: 'object', properties: { docs: { type: 'array' } } } }
+ *   },
+ *   create: {
+ *     body: { type: 'object', properties: { name: { type: 'string' } } },
+ *     response: { 201: { type: 'object' } }
+ *   }
+ * }
+ */
+interface CrudSchemas {
+  /** GET / - List all resources */
+  list?: {
+    querystring?: Record<string, unknown>;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** GET /:id - Get single resource */
+  get?: {
+    params?: Record<string, unknown>;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** POST / - Create resource */
+  create?: {
+    body?: Record<string, unknown>;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** PATCH /:id - Update resource */
+  update?: {
+    params?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** DELETE /:id - Delete resource */
+  delete?: {
+    params?: Record<string, unknown>;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface OpenApiSchemas {
+  entity?: unknown;
+  createBody?: unknown;
+  updateBody?: unknown;
+  params?: unknown;
+  listQuery?: unknown;
+  /**
+   * Explicit response schema for OpenAPI documentation.
+   * If provided, this will be used as-is for the response schema.
+   * If not provided, response schema is auto-generated from createBody.
+   *
+   * Note: This is for OpenAPI docs only - does NOT affect Fastify serialization.
+   *
+   * @example
+   * response: {
+   *   type: 'object',
+   *   properties: {
+   *     _id: { type: 'string' },
+   *     name: { type: 'string' },
+   *     email: { type: 'string' },
+   *     // Exclude password, include virtuals
+   *     fullName: { type: 'string' },
+   *   }
+   * }
+   */
+  response?: unknown;
+  [key: string]: unknown;
+}
+/** Handler for middleware functions */
+type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
+type CrudRouteKey = 'list' | 'get' | 'create' | 'update' | 'delete';
+interface MiddlewareConfig {
+  list?: MiddlewareHandler[];
+  get?: MiddlewareHandler[];
+  create?: MiddlewareHandler[];
+  update?: MiddlewareHandler[];
+  delete?: MiddlewareHandler[];
+  [key: string]: MiddlewareHandler[] | undefined;
+}
+/**
+ * JWT utilities provided to authenticator
+ * Arc provides these helpers, app uses them as needed
+ */
+interface JwtContext {
+  /** Verify a JWT token and return decoded payload */
+  verify: <T = Record<string, unknown>>(token: string) => T;
+  /** Sign a payload and return JWT token */
+  sign: (payload: Record<string, unknown>, options?: {
+    expiresIn?: string;
+  }) => string;
+  /** Decode without verification (for inspection) */
+  decode: <T = Record<string, unknown>>(token: string) => T | null;
+}
+/**
+ * Context passed to app's authenticator function
+ */
+interface AuthenticatorContext {
+  /** JWT utilities (available if jwt.secret provided) */
+  jwt: JwtContext | null;
+  /** Fastify instance for advanced use cases */
+  fastify: FastifyInstance;
+}
+/**
+ * App-provided authenticator function
+ *
+ * Arc calls this for every non-public route.
+ * App has FULL control over authentication logic.
+ *
+ * @example
+ * ```typescript
+ * // Simple JWT auth
+ * authenticate: async (request, { jwt }) => {
+ *   const token = request.headers.authorization?.split(' ')[1];
+ *   if (!token || !jwt) return null;
+ *   const decoded = jwt.verify(token);
+ *   return userRepo.findById(decoded.id);
+ * }
+ *
+ * // Multi-strategy (JWT + API Key)
+ * authenticate: async (request, { jwt }) => {
+ *   const apiKey = request.headers['x-api-key'];
+ *   if (apiKey) {
+ *     const result = await apiKeyService.verify(apiKey);
+ *     if (result) return { _id: result.userId, isApiKey: true };
+ *   }
+ *   const token = request.headers.authorization?.split(' ')[1];
+ *   if (token && jwt) {
+ *     const decoded = jwt.verify(token);
+ *     return userRepo.findById(decoded.id);
+ *   }
+ *   return null;
+ * }
+ * ```
+ */
+type Authenticator = (request: FastifyRequest, context: AuthenticatorContext) => Promise<unknown | null> | unknown | null;
+/**
+ * Token pair returned by issueTokens helper
+ */
+interface TokenPair {
+  /** Access token (JWT) */
+  accessToken: string;
+  /** Refresh token (JWT with longer expiry) */
+  refreshToken?: string;
+  /** Access token expiry in seconds */
+  expiresIn: number;
+  /** Refresh token expiry in seconds */
+  refreshExpiresIn?: number;
+  /** Token type (always 'Bearer') */
+  tokenType: 'Bearer';
+}
+/**
+ * Auth helpers available on fastify.auth
+ *
+ * @example
+ * ```typescript
+ * // In login handler
+ * const user = await userRepo.findByEmail(email);
+ * if (!user || !await bcrypt.compare(password, user.password)) {
+ *   return reply.code(401).send({ error: 'Invalid credentials' });
+ * }
+ *
+ * const tokens = fastify.auth.issueTokens({
+ *   id: user._id,
+ *   email: user.email,
+ *   role: user.role,
+ * });
+ *
+ * return { success: true, ...tokens, user };
+ * ```
+ */
+interface AuthHelpers {
+  /** JWT utilities (if configured) */
+  jwt: JwtContext | null;
+  /**
+   * Issue access + refresh tokens for a user
+   * App calls this after validating credentials
+   */
+  issueTokens: (payload: Record<string, unknown>, options?: {
+    expiresIn?: string;
+    refreshExpiresIn?: string;
+  }) => TokenPair;
+  /**
+   * Verify a refresh token and return decoded payload
+   */
+  verifyRefreshToken: <T = Record<string, unknown>>(token: string) => T;
+}
+interface ServiceContext {
+  user?: unknown;
+  requestId?: string;
+  select?: string[] | Record<string, 0 | 1>;
+  populate?: string | string[];
+  lean?: boolean;
+}
+interface PresetHook {
+  operation: 'create' | 'update' | 'delete' | 'read' | 'list';
+  phase: 'before' | 'after';
+  handler: (ctx: AnyRecord) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
+  priority?: number;
+}
+interface PresetResult {
+  name: string;
+  additionalRoutes?: AdditionalRoute[] | ((permissions: ResourcePermissions) => AdditionalRoute[]);
+  middlewares?: MiddlewareConfig;
+  schemaOptions?: RouteSchemaOptions;
+  controllerOptions?: Record<string, unknown>;
+  hooks?: PresetHook[];
+}
+type PresetFunction = (config: ResourceConfig) => PresetResult;
+interface GracefulShutdownOptions {
+  timeout?: number;
+  onShutdown?: () => Promise<void> | void;
+  signals?: NodeJS.Signals[];
+  logEvents?: boolean;
+}
+interface RequestIdOptions {
+  headerName?: string;
+  generator?: () => string;
+}
+interface HealthOptions {
+  path?: string;
+  check?: () => Promise<unknown>;
+}
+interface HealthCheck {
+  healthy: boolean;
+  timestamp: string;
+  [key: string]: unknown;
+}
+/**
+ * Auth Plugin Options - Clean, Minimal Configuration
+ *
+ * Arc provides JWT infrastructure and calls your authenticator.
+ * You control ALL authentication logic.
+ *
+ * @example
+ * ```typescript
+ * // Minimal: just JWT (uses default jwtVerify)
+ * auth: {
+ *   jwt: { secret: process.env.JWT_SECRET },
+ * }
+ *
+ * // With custom authenticator (recommended)
+ * auth: {
+ *   jwt: { secret: process.env.JWT_SECRET },
+ *   authenticate: async (request, { jwt }) => {
+ *     const token = request.headers.authorization?.split(' ')[1];
+ *     if (!token) return null;
+ *     const decoded = jwt.verify(token);
+ *     return userRepo.findById(decoded.id);
+ *   },
+ * }
+ *
+ * // Multi-strategy (JWT + API Key)
+ * auth: {
+ *   jwt: { secret: process.env.JWT_SECRET },
+ *   authenticate: async (request, { jwt }) => {
+ *     // Try API key first (faster)
+ *     const apiKey = request.headers['x-api-key'];
+ *     if (apiKey) {
+ *       const result = await apiKeyService.verify(apiKey);
+ *       if (result) return { _id: result.userId, isApiKey: true };
+ *     }
+ *     // Try JWT
+ *     const token = request.headers.authorization?.split(' ')[1];
+ *     if (token) {
+ *       const decoded = jwt.verify(token);
+ *       return userRepo.findById(decoded.id);
+ *     }
+ *     return null;
+ *   },
+ *   onFailure: (request, reply) => {
+ *     reply.code(401).send({
+ *       success: false,
+ *       error: 'Authentication required',
+ *       message: 'Use Bearer token or X-API-Key header',
+ *     });
+ *   },
+ * }
+ * ```
+ */
+interface AuthPluginOptions {
+  /**
+   * JWT configuration (optional but recommended)
+   * If provided, jwt utilities are available in authenticator context
+   */
+  jwt?: {
+    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
+    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string; /** Additional @fastify/jwt sign options */
+    sign?: Record<string, unknown>; /** Additional @fastify/jwt verify options */
+    verify?: Record<string, unknown>;
+  };
+  /**
+   * Custom authenticator function (recommended)
+   *
+   * Arc calls this for non-public routes.
+   * Return user object to authenticate, null/undefined to reject.
+   *
+   * If not provided and jwt.secret is set, uses default jwtVerify.
+   */
+  authenticate?: Authenticator;
+  /**
+   * Custom auth failure handler
+   * Customize the 401 response when authentication fails
+   */
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  /**
+   * Expose detailed auth error messages in 401 responses.
+   * When false (default), returns generic "Authentication required".
+   * When true, includes the actual error message for debugging.
+   * Decoupled from log level — set explicitly per environment.
+   */
+  exposeAuthErrors?: boolean;
+  /**
+   * Property name to store user on request (default: 'user')
+   */
+  userProperty?: string;
+  /**
+   * Custom token extractor for the built-in JWT auth path.
+   * When not provided, defaults to extracting Bearer token from Authorization header.
+   * Use this when tokens are in HttpOnly cookies, custom headers, or query params.
+   *
+   * @example
+   * ```typescript
+   * // Extract from HttpOnly cookie
+   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
+   *
+   * // Extract from custom header
+   * tokenExtractor: (request) => request.headers['x-api-token'] as string ?? null,
+   * ```
+   */
+  tokenExtractor?: (request: FastifyRequest) => string | null;
+  /**
+   * Token revocation check — called after JWT verification succeeds.
+   * Return `true` to reject the token (revoked), `false` to allow.
+   *
+   * Arc provides this primitive — implement your own store (Redis set,
+   * DB lookup, Better Auth session check, etc.)
+   *
+   * **Fail-closed**: if the check throws, the token is treated as revoked.
+   *
+   * @example
+   * ```typescript
+   * // Redis-backed revocation
+   * isRevoked: async (decoded) => {
+   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
+   * },
+   *
+   * // DB-backed revocation
+   * isRevoked: async (decoded) => {
+   *   const user = await db.user.findById(decoded.id);
+   *   return !user || user.bannedAt != null;
+   * },
+   * ```
+   */
+  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
+}
+interface IntrospectionPluginOptions {
+  path?: string;
+  prefix?: string;
+  enabled?: boolean;
+  authRoles?: string[];
+}
+interface CrudRouterOptions {
+  /** Route prefix */
+  prefix?: string;
+  /** Permission checks for CRUD operations */
+  permissions?: ResourcePermissions;
+  /** OpenAPI tag for grouping routes */
+  tag?: string;
+  /** JSON schemas for CRUD operations */
+  schemas?: Partial<CrudSchemas>;
+  /** Middlewares for each CRUD operation */
+  middlewares?: MiddlewareConfig;
+  /** Additional custom routes (from presets or user-defined) */
+  additionalRoutes?: AdditionalRoute[];
+  /** Disable all default CRUD routes */
+  disableDefaultRoutes?: boolean;
+  /** Disable specific CRUD routes */
+  disabledRoutes?: CrudRouteKey[];
+  /** Functional pipeline (guard/transform/intercept) */
+  pipe?: PipelineConfig;
+  /** Resource name for lifecycle hooks */
+  resourceName?: string;
+  /** Schema generation options */
+  schemaOptions?: RouteSchemaOptions;
+  /** Field-level permissions (visibility, writability per role) */
+  fields?: FieldPermissionMap;
+  /** HTTP method for update routes. Default: 'PATCH' */
+  updateMethod?: 'PUT' | 'PATCH' | 'both';
+  /**
+   * Per-resource rate limiting.
+   * Requires `@fastify/rate-limit` to be registered on the Fastify instance.
+   * Set to `false` to disable rate limiting for this resource.
+   */
+  rateLimit?: RateLimitConfig | false;
+}
+interface ResourceMetadata {
+  name: string;
+  displayName?: string;
+  tag?: string;
+  prefix: string;
+  module?: string;
+  permissions?: ResourcePermissions;
+  presets: string[];
+  additionalRoutes?: AdditionalRoute[];
+  routes: Array<{
+    method: string;
+    path: string;
+    handler?: string;
+    operation?: string;
+    summary?: string;
+  }>;
+  events?: string[];
+}
+interface RegistryEntry extends ResourceMetadata {
+  plugin: unknown;
+  adapter?: {
+    type: string;
+    name: string;
+  } | null;
+  events?: string[];
+  disableDefaultRoutes?: boolean;
+  openApiSchemas?: OpenApiSchemas;
+  registeredAt?: string;
+  /** Field-level permissions metadata (for OpenAPI docs) */
+  fieldPermissions?: Record<string, {
+    type: string;
+    roles?: readonly string[];
+    redactValue?: unknown;
+  }>;
+  /** Pipeline step names (for OpenAPI docs) */
+  pipelineSteps?: Array<{
+    type: string;
+    name: string;
+    operations?: string[];
+  }>;
+  /** Update HTTP method(s) used for this resource */
+  updateMethod?: 'PUT' | 'PATCH' | 'both';
+  /** Routes disabled for this resource */
+  disabledRoutes?: string[];
+  /** Rate limit config */
+  rateLimit?: RateLimitConfig | false;
+}
+interface RegistryStats {
+  total?: number;
+  totalResources: number;
+  byTag?: Record<string, number>;
+  byModule?: Record<string, number>;
+  presetUsage?: Record<string, number>;
+  totalRoutes?: number;
+  totalEvents?: number;
+}
+interface IntrospectionData {
+  resources: ResourceMetadata[];
+  stats: RegistryStats;
+  generatedAt?: string;
+}
+interface EventDefinition {
+  name: string;
+  /** Optional handler — events are published via fastify.events.publish(), not invoked through resource definitions */
+  handler?: (data: unknown) => Promise<void> | void;
+  schema?: Record<string, unknown>;
+  description?: string;
+}
+interface ConfigError {
+  field: string;
+  message: string;
+  code?: string;
+}
+interface ValidationResult$1 {
+  valid: boolean;
+  errors: ConfigError[];
+}
+interface ValidateOptions {
+  strict?: boolean;
+}
+/**
+ * Infer document type from DataAdapter or ResourceConfig
+ */
+type InferDocType<T> = T extends DataAdapter<infer D> ? D : T extends ResourceConfig<infer D> ? D : never;
+/**
+ * Infer document type from a DataAdapter.
+ * Falls back to `unknown` (not `never`) — safe for generic constraints.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
+ * type ProductDoc = InferAdapterDoc<typeof adapter>;
+ * // ProductDoc = the document type inferred from the adapter
+ * ```
+ */
+type InferAdapterDoc<A> = A extends DataAdapter<infer D> ? D : unknown;
+type InferResourceDoc<T> = T extends ResourceConfig<infer D> ? D : never;
+type TypedResourceConfig<TDoc> = ResourceConfig<TDoc>;
+type TypedController<TDoc> = IController<TDoc>;
+type TypedRepository<TDoc> = CrudRepository<TDoc>;
+//#endregion
+//#region src/adapters/interface.d.ts
+/**
+ * Minimal repository interface for flexible adapter compatibility.
+ * Any repository with these method signatures is accepted — no `as any` needed.
+ *
+ * CrudRepository<TDoc> and MongoKit Repository both satisfy this interface.
+ */
+interface RepositoryLike {
+  getAll(params?: unknown): Promise<unknown>;
+  getById(id: string, options?: unknown): Promise<unknown>;
+  create(data: unknown, options?: unknown): Promise<unknown>;
+  update(id: string, data: unknown, options?: unknown): Promise<unknown>;
+  delete(id: string, options?: unknown): Promise<unknown>;
+  [key: string]: unknown;
+}
+interface DataAdapter<TDoc = unknown> {
+  /**
+   * Repository implementing CRUD operations
+   * Accepts CrudRepository, MongoKit Repository, or any compatible object
+   */
+  repository: CrudRepository<TDoc> | RepositoryLike;
+  /** Adapter identifier for introspection */
+  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
+  /** Human-readable name */
+  readonly name: string;
+  /**
+   * Generate OpenAPI schemas for CRUD operations
+   *
+   * This method allows each adapter to generate schemas specific to its ORM/database.
+   * For example, Mongoose adapter can use mongokit to generate schemas from Mongoose models.
+   *
+   * @param options - Schema generation options (field rules, populate settings, etc.)
+   * @returns OpenAPI schemas for CRUD operations or null if not supported
+   */
+  generateSchemas?(options?: RouteSchemaOptions): OpenApiSchemas | Record<string, unknown> | null;
+  /** Extract schema metadata for OpenAPI/introspection */
+  getSchemaMetadata?(): SchemaMetadata | null;
+  /** Validate data against schema before persistence */
+  validate?(data: unknown): Promise<ValidationResult> | ValidationResult;
+  /** Health check for database connection */
+  healthCheck?(): Promise<boolean>;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Falls back to built-in MongoDB-style matching if not provided.
+   * Override this for SQL adapters or non-MongoDB query operators.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close/cleanup resources */
+  close?(): Promise<void>;
+}
+interface SchemaMetadata {
+  name: string;
+  fields: Record<string, FieldMetadata>;
+  indexes?: Array<{
+    fields: string[];
+    unique?: boolean;
+    sparse?: boolean;
+  }>;
+  relations?: Record<string, RelationMetadata>;
+}
+interface FieldMetadata {
+  type: "string" | "number" | "boolean" | "date" | "object" | "array" | "objectId" | "enum";
+  required?: boolean;
+  unique?: boolean;
+  default?: unknown;
+  enum?: Array<string | number>;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  description?: string;
+  ref?: string;
+  array?: boolean;
+}
+interface RelationMetadata {
+  type: "one-to-one" | "one-to-many" | "many-to-many";
+  target: string;
+  foreignKey?: string;
+  through?: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors?: Array<{
+    field: string;
+    message: string;
+    code?: string;
+  }>;
+}
+type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
+//#endregion
+export { RegistryStats as $, HookContext as $t, HealthCheck as A, FastifyHandler as At, MiddlewareConfig as B, InferDoc as Bt, EventDefinition as C, QueryResolverConfig as Ct, FastifyWithDecorators as D, AccessControlConfig as Dt, FastifyWithAuth as E, AccessControl as Et, IntrospectionData as F, RegisterOptions as Ft, ParsedQuery as G, Interceptor as Gt, ObjectId as H, PaginationParams as Ht, IntrospectionPluginOptions as I, ResourceRegistry as It, PresetHook as J, PipelineConfig as Jt, PopulateOption as K, NextFunction as Kt, JWTPayload as L, ResourceDefinition as Lt, InferAdapterDoc as M, IControllerResponse as Mt, InferDocType as N, IRequestContext as Nt, FieldRule as O, ControllerHandler as Ot, InferResourceDoc as P, RouteHandler as Pt, RegistryEntry as Q, DefineHookOptions as Qt, JwtContext as R, defineResource as Rt, CrudSchemas as S, QueryResolver as St, FastifyRequestExtras as T, BodySanitizerConfig as Tt, OpenApiSchemas as U, QueryOptions as Ut, MiddlewareHandler as V, PaginatedResult as Vt, OwnershipCheck as W, Guard as Wt, QueryParserInterface as X, PipelineStep as Xt, PresetResult as Y, PipelineContext as Yt, RateLimitConfig as Z, Transform as Zt, ConfigError as _, ValidateOptions as _t, RepositoryLike as a, HookSystemOptions as an, ResourceHooks as at, CrudRouteKey as b, BaseController as bt, AdditionalRoute as c, afterUpdate as cn, RouteHandlerMethod$1 as ct, ArcDecorator as d, beforeUpdate as dn, TokenPair as dt, HookHandler as en, RequestContext as et, ArcInternalMetadata as f, createHookSystem as fn, TypedController as ft, AuthenticatorContext as g, UserOrganization as gt, Authenticator as h, UserLike as ht, RelationMetadata as i, HookSystem as in, ResourceConfig as it, HealthOptions as j, IController as jt, GracefulShutdownOptions as k, ControllerLike as kt, AnyRecord as l, beforeCreate as ln, RouteSchemaOptions as lt, AuthPluginOptions as m, TypedResourceConfig as mt, DataAdapter as n, HookPhase as nn, RequestWithExtras as nt, SchemaMetadata as o, afterCreate as on, ResourceMetadata as ot, AuthHelpers as p, defineHook as pn, TypedRepository as pt, PresetFunction as q, OperationFilter as qt, FieldMetadata as r, HookRegistration as rn, ResourceCacheConfig as rt, ValidationResult as s, afterDelete as sn, ResourcePermissions as st, AdapterFactory as t, HookOperation as tn, RequestIdOptions as tt, ApiResponse as u, beforeDelete as un, ServiceContext as ut, ControllerQueryOptions as v, ValidationResult$1 as vt, EventsDecorator as w, BodySanitizer as wt, CrudRouterOptions as x, BaseControllerOptions as xt, CrudController as y, getUserId as yt, LookupOption as z, CrudRepository as zt };