@classytic/arc 2.10.3 → 2.10.8

package/dist/{index-Cl0uoKd5.d.mts → index-BGbpGVyM.d.mts}

@@ -1,1383 +1,1732 @@
-import { r as RequestScope } from "./types-BD85MlEK.mjs";
-import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-Lo1VUDpt.mjs";
-import { n as DomainEvent } from "./EventTransport-CUw5NNWe.mjs";
+import { r as RequestScope } from "./types-tgR4Pt8F.mjs";
+import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-C8Y0XLAu.mjs";
+import { n as DomainEvent } from "./EventTransport-CfVEGaEl.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 import * as _$_classytic_repo_core_repository0 from "@classytic/repo-core/repository";
 import { MinimalRepo, QueryOptions, StandardRepo } from "@classytic/repo-core/repository";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 
-//#region src/types/base.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.
-     *
-     * 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.
-     */
-    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.
- * 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;
-interface UserOrganization {
-  userId: string;
-  organizationId: string;
-  [key: string]: unknown;
-}
-interface JWTPayload {
-  sub: string;
-  [key: string]: unknown;
-}
-/**
- * Standard API response envelope — `{ success, data?, error?, message?, meta? }`.
- * Used by Arc's default response shape.
- */
-interface ApiResponse<T = unknown> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-  meta?: Record<string, unknown>;
-}
-/**
- * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
- * instead of `(req as any).user`.
- *
- * @example
- * ```typescript
- * import type { ArcRequest } from '@classytic/arc';
- *
- * handler: async (req: ArcRequest, reply) => {
- *   req.user?.id;                    // typed
- *   req.scope.organizationId;        // typed (when member)
- *   req.signal;                      // AbortSignal (Fastify 5)
- * }
- * ```
- */
-type ArcRequest = FastifyRequest & {
-  scope: RequestScope;
-  user: Record<string, unknown> | undefined;
-  signal: AbortSignal;
-};
+//#region src/adapters/interface.d.ts
 /**
- * Wrap data in Arc's standard `{ success: true, data }` envelope.
+ * Arc's structural repository contract: the repo-core minimum plus any
+ * standard-repo methods a given kit implements. All optional methods are
+ * feature-detected at call sites — arc never assumes capabilities it
+ * hasn't probed.
  *
- * @example
- * ```typescript
- * handler: async (req, reply) => {
- *   const data = await getResults();
- *   return envelope(data);  // → { success: true, data }
- * }
+ * ```ts
+ * const adapter: DataAdapter<Product> = {
+ *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
+ *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
+ *   name: 'products',
+ * };
+ * defineResource({ adapter, ... });
  * ```
  */
-declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
-  success: true;
-  data: T;
-  [key: string]: unknown;
-};
-//#endregion
-//#region src/hooks/HookSystem.d.ts
-type HookPhase = "before" | "around" | "after";
-type HookOperation = "create" | "update" | "delete" | "restore" | "read" | "list";
-interface HookContext<T = AnyRecord> {
-  resource: string;
-  operation: HookOperation;
-  phase: HookPhase;
-  data?: T;
-  result?: T | T[];
-  user?: UserBase;
-  context?: RequestContext;
-  meta?: AnyRecord;
+type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
+interface DataAdapter<TDoc = unknown> {
+  /**
+   * Repository implementing CRUD operations. Accepts the typed
+   * `StandardRepo<TDoc>` (repo-core's standard contract) or the structural
+   * `RepositoryLike` (minimum + optionals). Arc feature-detects optional
+   * methods at runtime — kits only declare what they support.
+   */
+  repository: StandardRepo<TDoc> | RepositoryLike<TDoc>;
+  /** Adapter identifier for introspection */
+  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
+  /** Human-readable name */
+  readonly name: string;
+  /**
+   * Generate OpenAPI schemas for CRUD operations. Each adapter produces
+   * schemas appropriate to its ORM/database (mongoose kits use mongokit's
+   * `buildCrudSchemasFromModel`; SQL kits introspect columns).
+   *
+   * @param options - Schema generation options (field rules, populate hints)
+   * @param context - Resource-level context (idField for params schema, name for logs).
+   *                  Adapters should honor `context.idField` when producing the params
+   *                  schema (e.g., skip the ObjectId pattern when idField is a custom
+   *                  string field).
+   */
+  generateSchemas?(options?: RouteSchemaOptions, context?: AdapterSchemaContext): 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$1> | ValidationResult$1;
+  /** Health check for database connection. */
+  healthCheck?(): Promise<boolean>;
+  /**
+   * Custom filter matching for in-memory policy enforcement. Falls back
+   * to arc's built-in shallow matcher when omitted. Override for SQL
+   * adapters, non-Mongo operators, or kits that compile Filter IR.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close / cleanup resources. */
+  close?(): Promise<void>;
 }
-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.
+ * Context passed to `adapter.generateSchemas()` so adapters shape output
+ * to match resource-level configuration. All fields optional — adapters
+ * that ignore this still work; arc applies safety-net normalization.
  */
-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 AdapterSchemaContext {
+  /** The idField configured on the resource. Defaults to "_id". */
+  idField?: string;
+  /** Resource name (for error messages / logging). */
+  resourceName?: 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;
-  };
+interface SchemaMetadata {
+  name: string;
+  fields: Record<string, FieldMetadata>;
+  indexes?: Array<{
+    fields: string[];
+    unique?: boolean;
+    sparse?: boolean;
+  }>;
+  relations?: Record<string, RelationMetadata>;
 }
-declare class HookSystem {
-  private hooks;
-  private logger;
-  private warn;
-  constructor(options?: HookSystemOptions);
+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$1 {
+  valid: boolean;
+  errors?: Array<{
+    field: string;
+    message: string;
+    code?: string;
+  }>;
+}
+type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
+//#endregion
+//#region src/core/AccessControl.d.ts
+/** Denial reason codes returned by `fetchDetailed()`. */
+type FetchDenialReason = "NOT_FOUND" | "POLICY_FILTERED" | "ORG_SCOPE_DENIED";
+/** Result of a detailed fetch with access control. */
+interface FetchResult<TDoc> {
+  /** The document, or null if denied. */
+  doc: TDoc | null;
+  /** Null when the doc was found. A string code when denied. */
+  reason: FetchDenialReason | null;
+}
+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;
   /**
-   * Generate hook key
+   * 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.
    */
-  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;
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+}
+/** Minimal repository interface for access-controlled fetch operations */
+interface AccessControlRepository {
+  getById(id: string, options?: QueryOptions): Promise<unknown>;
+  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
+}
+declare class AccessControl {
+  private readonly tenantField;
+  private readonly idField;
+  private readonly _adapterMatchesFilter?;
   /**
-   * Register after hook
+   * One-shot latch for the "adapter didn't supply matchesFilter, in-memory
+   * policy-filter re-check is skipped" warning. The primary fetch path
+   * (`getOne(compoundFilter)`) already applied filters at the DB layer;
+   * this warn only fires when `validateItemAccess` runs and the adapter
+   * hasn't provided a native matcher for the post-hoc re-check.
    */
-  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  private _warnedNoMatcher;
+  constructor(config: AccessControlConfig);
   /**
-   * Register around hook — wraps the core operation.
-   * Call `next()` inside the handler to proceed.
+   * Build filter for single-item operations (get/update/delete)
+   * Combines ID filter with policy/org filters for proper security enforcement
    */
-  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
+  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
   /**
-   * Execute around hooks as a nested middleware chain.
-   * Each around hook receives `next()` to call the next hook or the core operation.
+   * Check if a post-fetch item matches the request's `_policyFilters`.
+   *
+   * **When this runs:** only on paths where the primary fetch path did NOT
+   * apply policy filters at the DB layer — notably `validateItemAccess`
+   * (used by `getBySlug` and cache revalidation). The main `fetchDetailed`
+   * path builds a compound filter (`buildIdFilter`) and passes it to
+   * `repository.getOne(compoundFilter)`, so the DB has already enforced
+   * the filter and an in-memory re-check would be redundant.
+   *
+   * **Evaluation order (fail-closed):**
+   * 1. No `_policyFilters` set → `true` (nothing to enforce).
+   * 2. Adapter supplied `matchesFilter` → delegate to it verbatim. Adapters
+   *    are expected to handle every filter shape the host emits
+   *    (mongokit/sqlitekit evaluate at the DB layer; Prisma/custom engines
+   *    can wrap their own predicate engine).
+   * 3. No adapter matcher → fall back to `simpleEqualityMatcher` — arc's
+   *    built-in flat-key equality helper. This is defense-in-depth for the
+   *    common case: arc's own permission helpers emit flat filters
+   *    (`{userId: …}`, `{organizationId: …}`), which this matcher evaluates
+   *    correctly. Operator-shaped filters (`$in`, `$ne`, `$regex`, `$and`,
+   *    `$or`) are **rejected** (the matcher returns `false`) — fail-closed
+   *    rather than fail-open. A one-shot warn flags the gap so adapter
+   *    authors can wire a richer matcher.
+   *
+   * Arc deliberately does NOT ship a full MongoDB-syntax matcher:
+   * re-implementing Mongo in JS was dead code for mongokit users (the DB
+   * did it) and silently wrong for non-Mongo adapters. The flat-equality
+   * fallback is small (~20 LOC), correct in both dialects, and closes the
+   * previous `getBySlug`-style policy-bypass path.
    */
-  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<T | undefined>;
+  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
   /**
-   * Execute hooks for a given context
+   * Emit a one-shot warn when policy filters contain operators (`$in`,
+   * `$ne`, `$regex`, etc.) and no `DataAdapter.matchesFilter` is wired —
+   * arc's flat-equality fallback fail-closes on operators, so the host
+   * sees 404s on docs that should match. Latched on `_warnedNoMatcher`
+   * so subsequent requests stay quiet.
    */
-  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
+  private _warnNoMatcher;
   /**
-   * Execute before hooks
+   * 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.
    */
-  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<T>;
+  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
+  /** Check ownership for update/delete (ownedByUser preset) */
+  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
   /**
-   * Execute after hooks
-   * Errors in after hooks are logged but don't fail the request
+   * 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)
    */
-  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<void>;
+  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
   /**
-   * 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.
+   * Same as `fetchWithAccessControl` but returns a structured result with
+   * a denial reason so callers can distinguish "doc doesn't exist" from
+   * "doc exists but was filtered by policy/org scope" from "repo threw".
+   *
+   * Codes:
+   * - `null`               — doc was found, no denial
+   * - `'NOT_FOUND'`        — doc genuinely doesn't exist in the DB
+   * - `'POLICY_FILTERED'`  — doc exists but the request's policy filters exclude it
+   * - `'ORG_SCOPE_DENIED'` — doc exists but the caller's org context doesn't match
+   * - `'REPO_ERROR'`       — the repository threw a "not found" error (mongokit style)
    */
-  private topologicalSort;
+  fetchDetailed<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<FetchResult<TDoc>>;
   /**
-   * Get all registered hooks
+   * 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.
    */
-  getAll(): HookRegistration[];
+  validateItemAccess(item: AnyRecord | null, req: IRequestContext): boolean;
+  /** Extract typed Arc internal metadata from request */
+  private _meta;
+}
+//#endregion
+//#region src/core/BodySanitizer.d.ts
+/**
+ * Policy for handling fields the caller lacks write permission for.
+ *
+ * - `'reject'` (default, secure): throw 403 listing the denied fields so
+ *   misconfigurations and attacks surface instead of silently disappearing.
+ * - `'strip'` (legacy): silently drop the field and continue. Preserved for
+ *   apps that relied on the pre-2.9 behaviour — new code should not use it.
+ */
+type FieldWriteDenialPolicy = "reject" | "strip";
+interface BodySanitizerConfig {
+  /** Schema options for field sanitization */
+  schemaOptions: RouteSchemaOptions;
   /**
-   * Get hooks for a specific resource
+   * What to do when a request contains fields the caller can't write.
+   * Default: `'reject'` — surface the misconfiguration as a 403.
    */
-  getForResource(resource: string): HookRegistration[];
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
+}
+declare class BodySanitizer {
+  private schemaOptions;
+  private onFieldWriteDenied;
+  constructor(config: BodySanitizerConfig);
   /**
-   * Get hooks matching filter criteria.
-   * Useful for debugging and testing specific hook combinations.
+   * Strip readonly and system-managed fields from request body.
+   * Prevents clients from overwriting _id, timestamps, __v, etc.
    *
-   * @example
-   * ```typescript
-   * // Find all before-create hooks for products (including wildcards)
-   * const hooks = hookSystem.getRegistered({
-   *   resource: 'product',
-   *   operation: 'create',
-   *   phase: 'before',
-   * });
-   * ```
+   * Also applies field-level write permissions when the request has
+   * field permission metadata.
    */
-  getRegistered(filter?: {
-    resource?: string;
-    operation?: HookOperation;
-    phase?: HookPhase;
-  }): HookRegistration[];
+  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;
   /**
-   * Get a structured summary of all registered hooks for debugging.
-   *
-   * @example
-   * ```typescript
-   * const info = hookSystem.inspect();
-   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
-   * ```
+   * Default sort applied when the request doesn't specify one.
+   *   - `string` — e.g. `'-createdAt'` (Mongo convention: leading `-` = DESC).
+   *   - `false` — disable the default; resolved query has no `sort` clause.
+   *     Use for SQL kits without a `createdAt` column.
+   * Defaults to `'-createdAt'` for back-compat with mongokit consumers.
    */
-  inspect(): {
-    total: number;
-    resources: Record<string, HookRegistration[]>;
-    summary: Array<{
-      name?: string;
-      key: string;
-      priority: number;
-      dependsOn?: string[];
-    }>;
-  };
+  defaultSort?: string | false;
+  /** 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;
+  /** `undefined` means "no default sort" (caller passed `false`). */
+  private defaultSort;
+  private schemaOptions;
+  private tenantField;
+  constructor(config?: QueryResolverConfig);
   /**
-   * Check if any hooks exist for a specific resource/operation/phase combination.
+   * Resolve a request into parsed query options -- ONE parse per request.
+   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
    */
-  has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
+  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
   /**
-   * Clear all hooks
+   * 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.
    */
-  clear(): void;
+  private sanitizeSelectAny;
+  /** Sanitize populate fields */
+  private sanitizePopulate;
+  /** Sanitize advanced populate options against allowedPopulate */
+  private sanitizePopulateOptions;
   /**
-   * Clear hooks for a specific resource
+   * Sanitize lookup/join options.
+   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
+   * Validates lookup structure to prevent injection.
    */
-  clearResource(resource: string): void;
+  private sanitizeLookups;
+  /** Get blocked fields from schema options */
+  private getBlockedFields;
 }
+//#endregion
+//#region src/core/BaseController.d.ts
 /**
- * Create a new isolated HookSystem instance
- *
- * Use this for:
- * - Test isolation (parallel test suites)
- * - Multiple app instances with independent hooks
+ * Union of every return shape repo-core's `MinimalRepo.getAll()` is
+ * contractually allowed to produce. Keeping arc's list surface in sync
+ * with that contract (v2.10.6) — previously arc narrowed to
+ * `OffsetPaginationResult<TDoc>` and treated bare arrays as
+ * "non-conforming," which drifted from repo-core's published shape.
  *
- * @example
- * const hooks = createHookSystem();
- * await app.register(arcCorePlugin, { hookSystem: hooks });
+ * - `OffsetPaginationResult<TDoc>` — when the query uses offset pagination
+ *   (`page` parameter).
+ * - `KeysetPaginationResult<TDoc>` — when the query uses keyset/cursor
+ *   pagination (`sort` + optional `after`).
+ * - `TDoc[]` — raw array when neither drives pagination; valid per
+ *   repo-core's `MinimalRepo.getAll` docstring.
  *
- * @example With custom logger
- * const hooks = createHookSystem({ logger: fastify.log });
+ * Arc passes the kit's response verbatim; callers / consumers should
+ * narrow on shape (`Array.isArray(result)` → bare array, presence of
+ * `page`/`total` → offset, presence of `nextCursor` → keyset).
  */
-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/types/query.d.ts
-/**
- * Request-shaped context object passed to controller methods. Apps and
- * adapters extend it freely via the index signature.
- */
-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, populate/lookup, 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>;
+type ListResult<TDoc> = OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[];
+interface BaseControllerOptions {
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
   /**
-   * Advanced populate options (Mongoose-compatible). When set, takes
-   * precedence over simple `populate`.
+   * Query parser instance.
+   * Default: Arc built-in query parser (adapter-agnostic).
+   * Swap in MongoKit QueryParser, pgkit parser, etc.
    */
-  populateOptions?: PopulateOption[];
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
   /**
-   * Lookup/join options (database-agnostic). MongoKit maps these to
-   * `$lookup`; future SQL adapters would map to JOINs.
+   * Default sort applied when the request doesn't specify one.
    *
-   * @example
-   * URL: ?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug
+   *   - `string` (default: `'-createdAt'`) — sort descending on the field.
+   *     Uses the Mongo convention `-fieldName` for DESC; matches the
+   *     mongokit / mongokit-sort parser. Applied only if the resource's
+   *     schema actually has the column.
+   *   - `false` — disable the default sort. Requests that pass no `sort`
+   *     get whatever order the adapter returns (PK order on most kits).
+   *     **Use this for SQL/Drizzle resources that don't declare a
+   *     `createdAt` column** — the default would otherwise compile to
+   *     `ORDER BY "createdAt" DESC` against a missing column.
+   *
+   * The `-createdAt` default is kept for back-compat with existing
+   * mongokit users; going forward, set this explicitly per resource.
    */
-  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>;
-  [key: string]: unknown;
-}
-/**
- * Database-agnostic lookup/join option. Parsed from URL:
- * `?lookup[alias][from]=...&lookup[alias][localField]=...&lookup[alias][foreignField]=...`
- */
-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 */
-  select?: string | Record<string, 0 | 1>;
-}
-/**
- * Mongoose-compatible populate option for advanced field selection.
- *
- * @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. The index signature lets custom
- * parsers (MongoKit, PrismaKit) add fields without breaking Arc's types.
- */
-interface ParsedQuery {
-  filters?: Record<string, unknown>;
-  limit?: number;
-  sort?: string | Record<string, 1 | -1>;
-  populate?: string | string[] | Record<string, unknown>;
-  populateOptions?: PopulateOption[];
-  lookups?: LookupOption[];
-  search?: string;
-  page?: number;
-  after?: string;
-  select?: string | string[] | Record<string, 0 | 1>;
-  [key: string]: unknown;
-}
-/**
- * Query Parser interface. Implement to create custom query parsers.
- *
- * @example MongoKit
- * ```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. */
-  getQuerySchema?(): {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
+  defaultSort?: string | false;
+  /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
+  resourceName?: string;
   /**
-   * Optional: Allowed filter fields whitelist. MCP auto-derives
-   * `filterableFields` from this if `schemaOptions.filterableFields`
-   * is not explicitly configured.
+   * 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.
    */
-  allowedFilterFields?: readonly string[];
+  tenantField?: string | false;
   /**
-   * Optional: Allowed filter operators whitelist. Used by MCP to enrich
-   * list-tool descriptions. Values are human-readable keys: 'eq', 'ne',
-   * 'gt', 'gte', 'lt', 'lte', 'in', 'nin', etc.
+   * Primary key field name (default: '_id').
+   *
+   * If not set, the controller auto-derives it from the repository's own
+   * `idField` property (e.g. MongoKit's `Repository({ idField: 'id' })`),
+   * so you only need to configure it in one place.
+   *
+   * Set explicitly to override the repo's setting (e.g. `'_id'` to opt out
+   * of native pass-through and force the slug-translation path).
+   *
+   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
    */
-  allowedOperators?: readonly string[];
+  idField?: string;
   /**
-   * Optional: Allowed sort fields whitelist. Used by MCP to describe
-   * available sort options in list-tool descriptions.
+   * 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.
    */
-  allowedSortFields?: readonly string[];
-}
-/** Ownership-check config used by `ownedByUser` preset / middleware. */
-interface OwnershipCheck {
-  field: string;
-  userField?: string;
-}
-/** Service-layer context — passed to repository / service calls. */
-interface ServiceContext {
-  user?: unknown;
-  requestId?: string;
-  /** Field projection for responses */
-  select?: string[] | Record<string, 0 | 1>;
-  /** Relations to populate */
-  populate?: string | string[];
-  /** Return plain objects */
-  lean?: boolean;
+  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;
+  };
+  /**
+   * Policy for requests that include fields the caller can't write.
+   *
+   * - `'reject'` (default): 403 with the denied field names. Surfaces
+   *   misconfigurations and attempts to set protected fields instead of
+   *   silently dropping them.
+   * - `'strip'`: legacy silent-drop behaviour. Only opt in when migrating
+   *   code that relied on the pre-2.9 permissive default.
+   */
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
-//#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/adapters/interface.d.ts
-/**
- * Arc's structural repository contract: the repo-core minimum plus any
- * standard-repo methods a given kit implements. All optional methods are
- * feature-detected at call sites — arc never assumes capabilities it
- * hasn't probed.
+ * Framework-agnostic base controller implementing IController.
  *
- * ```ts
- * const adapter: DataAdapter<Product> = {
- *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
- *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
- *   name: 'products',
- * };
- * defineResource({ adapter, ... });
- * ```
+ * 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)
  */
-type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
-interface DataAdapter<TDoc = unknown> {
+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;
+  /** `undefined` means "no default sort" (caller passed `false`). */
+  protected defaultSort: string | undefined;
+  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);
   /**
-   * Repository implementing CRUD operations. Accepts the typed
-   * `StandardRepo<TDoc>` (repo-core's standard contract) or the structural
-   * `RepositoryLike` (minimum + optionals). Arc feature-detects optional
-   * methods at runtime — kits only declare what they support.
+   * 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`.
    */
-  repository: StandardRepo<TDoc> | RepositoryLike<TDoc>;
-  /** Adapter identifier for introspection */
-  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
-  /** Human-readable name */
-  readonly name: string;
+  protected getTenantField(): string | undefined;
   /**
-   * Generate OpenAPI schemas for CRUD operations. Each adapter produces
-   * schemas appropriate to its ORM/database (mongoose kits use mongokit's
-   * `buildCrudSchemasFromModel`; SQL kits introspect columns).
+   * Build top-level tenant options to thread into the repository call.
    *
-   * @param options - Schema generation options (field rules, populate hints)
-   * @param context - Resource-level context (idField for params schema, name for logs).
-   *                  Adapters should honor `context.idField` when producing the params
-   *                  schema (e.g., skip the ObjectId pattern when idField is a custom
-   *                  string field).
+   * **Why this exists:** repo plugins (e.g. `@classytic/mongokit`'s
+   * `multiTenantPlugin`) read tenant scope from the TOP of the repository
+   * operation context — `context.organizationId`, not `context.data.organizationId`
+   * or `context.context.organizationId`. Without this stamping, a tenant-scoped
+   * repository throws `Missing 'organizationId' in context for '<op>'` even
+   * though arc already injected the tenant into the request body.
+   *
+   * **What this returns:**
+   * - `{ [tenantField]: orgId }` when the resource is tenant-scoped and the
+   *   caller's scope carries an org ID (member, service key bound to an org,
+   *   elevated admin impersonating an org).
+   * - `{}` otherwise — platform-universal resources (`tenantField: false`),
+   *   public/anonymous reads, elevated admins without an org target.
+   *
+   * **Call sites:** every `this.repository.*` CRUD entry — `create`, `update`,
+   * `delete`, `getAll` (via list), plus merged into `QueryOptions` for the
+   * access-controlled read path (`accessControl.fetchDetailed` → `getById`/`getOne`).
+   *
+   * **Name of the field:** uses the instance's own `tenantField` configuration
+   * (default `organizationId`). Matches mongokit's `multiTenantPlugin` default
+   * `contextKey` so host apps don't need to override either side.
+   *
+   * Multi-field tenancy (via `multiTenantPreset({ tenantFields: [...] })`)
+   * resolves additional fields at middleware time and stashes them on
+   * `_tenantFields` — {@link tenantRepoOptions} merges those in too.
    */
-  generateSchemas?(options?: RouteSchemaOptions, context?: AdapterSchemaContext): 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$1> | ValidationResult$1;
-  /** Health check for database connection. */
-  healthCheck?(): Promise<boolean>;
+  private tenantRepoOptions;
+  /** Extract typed Arc internal metadata from request */
+  private meta;
+  /** Get hook system from request context (instance-scoped) */
+  private getHooks;
   /**
-   * Custom filter matching for in-memory policy enforcement. Falls back
-   * to arc's built-in shallow matcher when omitted. Override for SQL
-   * adapters, non-Mongo operators, or kits that compile Filter IR.
+   * Resolve the repository primary key for mutation calls (update/delete/restore).
+   *
+   * When the resource declares a custom `idField` (e.g. `slug`, `jobId`, UUID),
+   * the default behavior is to translate the route id → the fetched doc's `_id`
+   * because most Mongo repositories key their mutation methods off `_id`.
+   *
+   * Exception: if the repository itself exposes a matching `idField` property
+   * (e.g. MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
+   * repository already knows how to look up by that field — so we pass the
+   * route id through unchanged and skip the translation.
+   *
+   * This makes `defineResource({ idField: 'id' })` work end-to-end with repos
+   * that natively support custom primary keys, without breaking the slug-style
+   * aliasing that Arc 2.6.3 introduced for repos keyed on `_id`.
    */
-  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
-  /** Close / cleanup resources. */
-  close?(): Promise<void>;
-}
-/**
- * Context passed to `adapter.generateSchemas()` so adapters shape output
- * to match resource-level configuration. All fields optional — adapters
- * that ignore this still work; arc applies safety-net normalization.
- */
-interface AdapterSchemaContext {
-  /** The idField configured on the resource. Defaults to "_id". */
-  idField?: string;
-  /** Resource name (for error messages / logging). */
-  resourceName?: string;
-}
-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$1 {
-  valid: boolean;
-  errors?: Array<{
-    field: string;
+  private resolveRepoId;
+  /**
+   * Centralized 404 response builder. Maps the denial reason from
+   * `fetchDetailed()` into a structured `details.code` so consumers can
+   * programmatically distinguish "doc doesn't exist" from "doc filtered
+   * by policy/org scope" without parsing error strings.
+   *
+   * Error messages are intentionally vague in the `error` field (don't
+   * leak whether the doc exists) — the detail is in `details.code` only.
+   */
+  private notFoundResponse;
+  /** 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<ListResult<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;
-    code?: string;
-  }>;
-}
-type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
-//#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 `raw: true`.
- */
-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.
- *
- * **Generic parameters** (all default to safe permissive types so existing code keeps working):
- * - `TBody`     — request body shape (default: `unknown`)
- * - `TParams`   — route param shape (default: `Record<string, string>`)
- * - `TQuery`    — query string shape (default: `Record<string, unknown>`)
- * - `TUser`     — authenticated user shape (default: `UserBase`)
- * - `TMetadata` — internal metadata shape (default: `Record<string, unknown>`;
- *   override with `ArcInternalMetadata` or your own augmentation when you
- *   need typed access to `_scope`, `_policyFilters`, custom hook context, etc.)
- *
- * @example
- * ```typescript
- * // Untyped (default) — req.body is `unknown`, must be narrowed
- * async create(req: IRequestContext) {
- *   const data = req.body as Partial<Product>;
- *   return { success: true, data: await productRepo.create(data) };
- * }
- *
- * // Typed body — req.body is `CreateProductInput`, narrowing not needed
- * async create(req: IRequestContext<CreateProductInput>) {
- *   return { success: true, data: await productRepo.create(req.body) };
- * }
- *
- * // Fully typed — body, route params, query, and metadata
- * async update(
- *   req: IRequestContext<
- *     Partial<Product>,
- *     { id: string },
- *     { fields?: string },
- *     ArcInternalMetadata
- *   >,
- * ) {
- *   const fields = req.query.fields?.split(',');
- *   const orgId = req.metadata?._scope ? getOrgId(req.metadata._scope) : undefined;
- *   return { success: true, data: await productRepo.update(req.params.id, req.body) };
- * }
- * ```
- */
-interface IRequestContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>, TUser extends UserBase = UserBase, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
-  /** Route parameters (e.g., { id: '123' }) */
-  params: TParams;
-  /** Query string parameters */
-  query: TQuery;
-  /** Request body */
-  body: TBody;
-  /** Authenticated user or null */
-  user: TUser | null;
-  /** Request headers */
-  headers: Record<string, string | undefined>;
-  /** Organization ID (for multi-tenant apps) */
-  organizationId?: string;
-  /** Team ID (for team-scoped resources) */
-  teamId?: string;
+    id?: string;
+    soft?: boolean;
+  }>>;
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginationResult<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[]>>;
   /**
-   * Organization/auth context from middleware.
-   * Contains orgRoles, orgScope, organizationId, and any custom fields
-   * set by the auth adapter or org-scope plugin.
+   * Build a tenant-scoped filter for bulk update/delete.
    *
-   * @example
-   * ```typescript
-   * async create(req: IRequestContext) {
-   *   const roles = req.context?.orgRoles ?? [];
-   *   if (roles.includes('manager')) { ... }
-   * }
-   * ```
+   * Mirrors `AccessControl.buildIdFilter` semantics for single-doc ops:
+   *   - Always merge `_policyFilters` (from permission middleware)
+   *   - When `tenantField` is set AND a `member` scope is present, add the
+   *     org filter so cross-tenant data can't be touched.
+   *   - When the scope is `elevated` (platform admin), no org filter is
+   *     applied — admins can bulk-update across orgs intentionally.
+   *   - When the scope is `public` on a tenant-scoped resource, deny.
+   *   - When NO scope is present at all (e.g., direct controller calls in
+   *     unit tests, or app routes without auth middleware), the controller
+   *     stays lenient — it's the middleware layer's job to fail-close.
+   *     Apps that want fail-close on bulk routes should run the multi-tenant
+   *     preset middleware (or equivalent) ahead of these handlers.
+   *
+   * Returns the merged filter, or `null` when access must be denied.
    */
-  context?: RequestContext;
+  private buildBulkFilter;
   /**
-   * Internal metadata (includes context + Arc internals like `_policyFilters`,
-   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
-   * built-in fields, or supply your own interface to layer custom fields.
+   * Sanitize a bulk update data payload through the same write-permission
+   * pipeline as single-doc update(). Handles both shapes:
+   *
+   *   - Flat:           `{ name: 'x', status: 'y' }`
+   *   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 }, $unset: { tag: '' } }`
+   *
+   * For each operand, runs `bodySanitizer.sanitize('update', ...)` so that
+   * system fields, systemManaged/readonly/immutable rules, AND field-level
+   * write permissions are enforced. Without this, a tenant-scoped user could
+   * pass `{ $set: { organizationId: 'org-b' } }` to move records across orgs.
+   *
+   * Returns the sanitized payload along with the list of stripped fields for
+   * audit/error reporting.
    */
-  metadata?: TMetadata;
+  private sanitizeBulkUpdateData;
+  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>>;
   /**
-   * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `raw: true`.
+   * Bulk delete by `filter` or `ids`.
    *
-   * @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 };
-   * }
-   * ```
+   * Body shape (one of):
+   *   - `{ filter: { status: 'archived' } }`     — delete by query filter
+   *   - `{ ids: ['id1', 'id2', 'id3'] }`         — delete specific docs by id
+   *
+   * The `ids` form translates to `{ [idField]: { $in: ids } }` using the
+   * resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
+   * UUID, etc.). Tenant scope and policy filters are merged in either way,
+   * so cross-tenant deletes are blocked at the controller layer.
+   *
+   * Both forms perform a single `repo.deleteMany()` DB call — no per-doc
+   * fetch loop. Per-doc lifecycle hooks (`before:delete`/`after:delete`) do
+   * NOT fire for bulk operations; use the single-doc `delete()` if you need
+   * them, or subscribe to the bulk lifecycle event from the events plugin.
    */
-  server?: ServerAccessor;
+  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
+    deletedCount: number;
+  }>>;
+}
+//#endregion
+//#region src/types/base.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.
+     *
+     * 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.
+     */
+    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.
+ * 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;
+interface UserOrganization {
+  userId: string;
+  organizationId: string;
+  [key: string]: unknown;
+}
+interface JWTPayload {
+  sub: string;
+  [key: string]: unknown;
 }
 /**
- * Standard response from controller handlers
+ * Standard API response envelope — `{ success, data?, error?, message?, meta? }`.
+ * Used by Arc's default response shape.
  */
-interface IControllerResponse<T = unknown> {
-  /** Operation success status */
+interface ApiResponse<T = unknown> {
   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 */
+  message?: string;
   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 `raw: false` in routes.
- *
- * **Generic parameters:**
- * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
- * - `TBody`     — shape of `req.body` (default: `unknown`)
- * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
- * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
- *
- * Backward-compatible: `ControllerHandler<Product>` still works (only the
- * response data is typed); add more generics as needed when you want
- * type-safe access to the request body, params, or query string.
+ * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * instead of `(req as any).user`.
  *
  * @example
  * ```typescript
- * // Untyped req — body is unknown, must be narrowed
- * const createProduct: ControllerHandler<Product> = async (req) => {
- *   const product = await productRepo.create(req.body as Partial<Product>);
- *   return { success: true, data: product, status: 201 };
- * };
+ * import type { ArcRequest } from '@classytic/arc';
  *
- * // Fully typed — body, params, query, and response all inferred
- * const updateProduct: ControllerHandler<
- *   Product,
- *   Partial<Product>,
- *   { id: string },
- *   { upsert?: string }
- * > = async (req) => {
- *   const upsert = req.query.upsert === "true";
- *   const product = await productRepo.update(req.params.id, req.body, { upsert });
- *   return { success: true, data: product };
- * };
- *
- * routes: [{
- *   method: 'POST',
- *   path: '/products',
- *   handler: createProduct,
- *   permissions: requireAuth(),
- *   raw: false,  // Arc wraps this into Fastify handler
- * }]
+ * handler: async (req: ArcRequest, reply) => {
+ *   req.user?.id;                    // typed
+ *   req.scope.organizationId;        // typed (when member)
+ *   req.signal;                      // AbortSignal (Fastify 5)
+ * }
  * ```
  */
-type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
+type ArcRequest = FastifyRequest & {
+  scope: RequestScope;
+  user: Record<string, unknown> | undefined;
+  signal: AbortSignal;
+};
 /**
- * Fastify native handler
- *
- * Standard Fastify request/reply pattern.
- * Use with `raw: true` in routes.
+ * Wrap data in Arc's standard `{ success: true, data }` envelope.
  *
  * @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);
- * };
- *
- * routes: [{
- *   method: 'GET',
- *   path: '/files/:id/download',
- *   handler: downloadFile,
- *   permissions: requireAuth(),
- *   raw: true,  // Use as-is, no wrapping
- * }]
+ * handler: async (req, reply) => {
+ *   const data = await getResults();
+ *   return envelope(data);  // → { success: true, data }
+ * }
  * ```
  */
-type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
+declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
+  success: true;
+  data: T;
+  [key: string]: unknown;
+};
+//#endregion
+//#region src/types/auth.d.ts
 /**
- * Union type for route handlers
+ * JWT utilities provided to authenticator. Arc provides the helpers;
+ * apps use them as needed.
  */
-type RouteHandler = ControllerHandler | FastifyHandler;
+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;
+}
 /**
- * Controller interface for CRUD operations (strict)
+ * App-provided authenticator function. Arc calls this for every
+ * non-public route. The app has full control over authentication logic.
+ *
+ * Return a user object to authenticate, `null`/`undefined` to reject.
+ *
+ * @example
+ * ```typescript
+ * 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);
+ * }
+ * ```
  */
-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;
-  }>>;
+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";
 }
 /**
- * Flexible controller interface - accepts controllers with any handler style
- * Use this when your controller uses Fastify native handlers
+ * Auth helpers exposed on `fastify.auth`.
+ *
+ * @example
+ * ```typescript
+ * const tokens = fastify.auth.issueTokens({
+ *   id: user._id,
+ *   email: user.email,
+ *   role: user.role,
+ * });
+ * return { success: true, ...tokens, user };
+ * ```
  */
-interface ControllerLike {
-  list?: unknown;
-  get?: unknown;
-  create?: unknown;
-  update?: unknown;
-  delete?: unknown;
-  [key: string]: unknown;
+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;
 }
-//#endregion
-//#region src/types/resource.d.ts
-/** Standard controller type alias for CRUD operations. */
-type CrudController<TDoc> = IController<TDoc>;
 /**
- * Per-resource cache configuration for QueryCache. Enables
- * stale-while-revalidate, auto-invalidation on mutations, and
- * cross-resource tag-based invalidation.
+ * Auth plugin options — clean, minimal configuration.
+ *
+ * Arc provides JWT infrastructure and calls your authenticator. You
+ * control all authentication logic.
+ *
+ * @example
+ * ```typescript
+ * 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);
+ *   },
+ * }
+ * ```
  */
-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;
+interface AuthPluginOptions {
+  /**
+   * JWT configuration (optional but recommended). If provided, JWT
+   * utilities are available in the 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>;
   };
-  /** Tags for cross-resource invalidation grouping */
-  tags?: string[];
   /**
-   * Cross-resource invalidation: event pattern → tag targets.
-   * @example { 'category.*': ['catalog'] }
+   * Custom authenticator function. Arc calls this for non-public routes.
+   * If not provided and `jwt.secret` is set, uses default `jwtVerify`.
    */
-  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') */
-  timeWindow: string;
-}
-interface RouteSchemaOptions {
-  hiddenFields?: string[];
-  readonlyFields?: string[];
-  requiredFields?: string[];
-  optionalFields?: string[];
-  excludeFields?: string[];
+  authenticate?: Authenticator;
   /**
-   * Fields allowed for filtering in list operations. MCP auto-derives
-   * from `QueryParser.allowedFilterFields` when not set explicitly.
+   * Custom auth failure handler. Customize the 401 response when
+   * authentication fails.
    */
-  filterableFields?: string[];
-  fieldRules?: Record<string, {
-    systemManaged?: boolean;
-    hidden?: boolean;
-    immutable?: boolean;
-    immutableAfterCreate?: boolean;
-    optional?: boolean; /** String minimum length — auto-maps to OpenAPI `minLength` and MCP tool schema */
-    minLength?: number; /** String maximum length — auto-maps to OpenAPI `maxLength` and MCP tool schema */
-    maxLength?: number; /** Number minimum — auto-maps to OpenAPI `minimum` and MCP tool schema */
-    min?: number; /** Number maximum — auto-maps to OpenAPI `maximum` and MCP tool schema */
-    max?: number; /** Regex pattern — auto-maps to OpenAPI `pattern` and MCP tool schema */
-    pattern?: string; /** Allowed values — auto-maps to OpenAPI `enum` and MCP tool schema */
-    enum?: ReadonlyArray<string | number>; /** Human-readable description — auto-maps to OpenAPI `description` */
-    description?: string;
-    [key: string]: unknown;
-  }>;
-  /** Query parameter schema for OpenAPI */
-  query?: Record<string, unknown>;
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
   /**
-   * When `true`, emitted CRUD body schemas set `additionalProperties: false`
-   * so AJV rejects unknown fields on create / update. Honored by kit schema
-   * generators that receive this options bag (sqlitekit's
-   * `buildCrudSchemasFromTable`, pgkit's equivalent). Mongoose-based
-   * generators may ignore it — Mongoose schemas are inherently strict at
-   * the model level.
+   * Expose detailed auth error messages in 401 responses. When `false`
+   * (default), returns generic "Authentication required". Decoupled from
+   * log level — set explicitly per environment.
    */
-  strictAdditionalProperties?: boolean;
-}
-interface FieldRule {
-  field: string;
-  required?: boolean;
-  readonly?: boolean;
-  hidden?: boolean;
-}
-/**
- * CRUD route schemas (Fastify native format). Each slot accepts a plain
- * JSON Schema object **or** a Zod v4 schema — Arc's `convertRouteSchema`
- * feature-detects at runtime. Slot values are typed `unknown` so
- * class-based Zod schemas assign without casts.
- */
-interface CrudSchemas {
-  /** GET / — list */
-  list?: {
-    querystring?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** GET /:id — get one */
-  get?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** POST / — create */
-  create?: {
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** PATCH /:id — update */
-  update?: {
-    params?: unknown;
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** DELETE /:id — delete */
-  delete?: {
-    params?: 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. Auto-generated
-   * from `createBody` if omitted. Does NOT affect Fastify serialization.
-   */
-  response?: unknown;
-  [key: string]: unknown;
-}
-type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
-interface MiddlewareConfig {
-  list?: MiddlewareHandler[];
-  get?: MiddlewareHandler[];
-  create?: MiddlewareHandler[];
-  update?: MiddlewareHandler[];
-  delete?: MiddlewareHandler[];
-  [key: string]: MiddlewareHandler[] | undefined;
-}
-/** HTTP methods for custom routes. */
-type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-/** MCP tool configuration for a route or action. */
-interface RouteMcpConfig {
-  /** Override auto-generated tool description */
-  readonly description?: string;
-  /** MCP tool annotations */
-  readonly annotations?: {
-    readonly readOnlyHint?: boolean;
-    readonly destructiveHint?: boolean;
-    readonly idempotentHint?: boolean;
-    readonly openWorldHint?: boolean;
-  };
-}
-/**
- * Route definition — single custom-route shape (user-facing + internal).
- *
- * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
- * - `handler: function` → inline handler → full Arc pipeline + MCP tool
- * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
- */
-interface RouteDefinition {
-  readonly method: RouteMethod;
-  /** Path relative to resource prefix */
-  readonly path: string;
-  /**
-   * Route handler.
-   * - String: controller method name (Arc pipeline)
-   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
-   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
-   */
-  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
-  /** Permission check — REQUIRED */
-  readonly permissions: PermissionCheck;
-  /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
-   * request/reply. Default: false.
-   */
-  readonly raw?: boolean;
-  /** Logical operation name (pipeline keys, MCP tool naming). */
-  readonly operation?: string;
-  /** OpenAPI summary */
-  readonly summary?: string;
-  /** OpenAPI description */
-  readonly description?: string;
-  /** OpenAPI tags */
-  readonly tags?: string[];
-  /** Route-level middleware */
-  readonly preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
-  /** Pre-auth handlers (run before authentication) */
-  readonly preAuth?: RouteHandlerMethod[];
-  /** SSE streaming mode */
-  readonly streamResponse?: boolean;
+  exposeAuthErrors?: boolean;
+  /** Property name to store user on request (default: 'user') */
+  userProperty?: string;
   /**
-   * Fastify route schema. Each slot (`body`, `querystring`, `params`,
-   * `headers`, `response[status]`) accepts a plain JSON Schema object
-   * **or** a Zod v4 schema — Arc auto-converts via `convertRouteSchema`.
+   * Custom token extractor for the built-in JWT auth path. Defaults to
+   * extracting Bearer token from Authorization header. Use when tokens
+   * are in HttpOnly cookies, custom headers, or query params.
+   *
+   * @example
+   * ```typescript
+   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
+   * ```
    */
-  readonly schema?: {
-    body?: unknown;
-    querystring?: unknown;
-    params?: unknown;
-    headers?: unknown;
-    response?: Record<number | string, unknown>;
-    [key: string]: unknown;
-  };
+  tokenExtractor?: (request: FastifyRequest) => string | null;
   /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate (non-raw routes only)
-   * - false: skip MCP
-   * - object: explicit config
+   * Token revocation check — called after JWT verification succeeds.
+   * Return `true` to reject the token (revoked), `false` to allow.
+   *
+   * **Fail-closed**: if the check throws, the token is treated as revoked.
+   *
+   * @example
+   * ```typescript
+   * isRevoked: async (decoded) => {
+   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
+   * },
+   * ```
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
   /**
-   * MCP handler for raw routes — parallel entry point for MCP without
-   * changing the HTTP handler.
+   * Enforce strict JWT `type` claim validation (default: `true`).
+   *
+   * When enabled, `authenticate` requires `decoded.type === "access"`.
+   * Tokens with a missing or unexpected `type` claim are rejected —
+   * defence in depth for apps that reuse the JWT secret to sign other
+   * token kinds (invite links, one-time verification codes).
+   *
+   * Arc's own `issueTokens` always sets `type: "access"` or
+   * `type: "refresh"`, so this default is safe for Arc-generated tokens.
+   *
+   * Set to `false` ONLY when you must accept tokens signed without a
+   * `type` claim (e.g. a legacy issuer you don't control). In that mode
+   * Arc still rejects tokens explicitly marked `type: "refresh"`.
    */
-  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
-    content: Array<{
-      type: string;
-      text: string;
-    }>;
-    isError?: boolean;
-  }>;
+  strictTokenType?: boolean;
 }
+//#endregion
+//#region src/pipeline/types.d.ts
 /**
- * Action handler function for state transitions. Receives the resource
- * ID, action-specific data, and the request.
+ * Pipeline context passed to guards, transforms, and interceptors.
+ * Extends IRequestContext with pipeline-specific metadata.
  */
-type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
-/** Full action configuration with handler, permissions, and schema. */
-interface ActionDefinition {
-  readonly handler: ActionHandlerFn;
-  /** Per-action permission (overrides resource-level `actionPermissions`) */
-  readonly permissions?: PermissionCheck;
-  /**
-   * JSON Schema or Zod v4 schema for action-specific body fields.
-   * Per-field values are typed `unknown` so Zod class instances assign
-   * without casts.
-   */
-  readonly schema?: Record<string, unknown>;
-  /** Description for OpenAPI docs and MCP tool */
-  readonly description?: string;
-  /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate
-   * - false: skip
-   * - object: explicit config
-   */
-  readonly mcp?: boolean | RouteMcpConfig;
+interface PipelineContext extends IRequestContext {
+  /** Resource name being accessed */
+  resource: string;
+  /** CRUD operation being performed */
+  operation: "list" | "get" | "create" | "update" | "delete" | string;
 }
-/** Action config: bare handler function OR full ActionDefinition. */
-type ActionEntry = ActionHandlerFn | ActionDefinition;
-/** Actions configuration map. */
-type ActionsMap = Record<string, ActionEntry>;
 /**
- * Hook context passed to resource-level hook handlers. Mirrors
- * HookSystem's HookContext but with a simpler API for inline use.
+ * Which operations a pipeline step applies to.
+ * If omitted, applies to ALL operations.
  */
-interface ResourceHookContext {
-  /** The document data (create/update body, or existing doc for delete) */
-  data: AnyRecord;
-  /** Authenticated user or null */
-  user?: UserBase;
-  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
-  meta?: AnyRecord;
-}
+type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
 /**
- * Inline lifecycle hooks on a resource definition. Wired into the
- * HookSystem automatically — same pipeline as presets and app-level hooks.
- *
- * @example
- * ```typescript
- * defineResource({
- *   name: 'chat',
- *   hooks: {
- *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
- *     beforeDelete: async (ctx) => {
- *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
- *     },
- *   },
- * });
- * ```
+ * Guard — boolean check that short-circuits on failure.
+ * Return true to proceed, throw to deny.
  */
-interface ResourceHooks {
-  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
-  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | void;
-  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
-  afterUpdate?: (ctx: ResourceHookContext) => Promise<void> | void;
-  beforeDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
-  afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+interface Guard {
+  readonly _type: "guard";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): boolean | Promise<boolean>;
 }
-interface PresetHook {
-  operation: "create" | "update" | "delete" | "read" | "list";
-  phase: "before" | "after";
-  handler: (ctx: AnyRecord) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
-  priority?: number;
+/**
+ * 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>;
 }
-interface PresetResult {
-  name: string;
-  /** Preset routes — merged into the resource's `routes` array. */
-  routes?: RouteDefinition[] | ((permissions: ResourcePermissions) => RouteDefinition[]);
-  middlewares?: MiddlewareConfig;
-  schemaOptions?: RouteSchemaOptions;
-  controllerOptions?: Record<string, unknown>;
-  hooks?: PresetHook[];
+/**
+ * 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 PresetFunction = (config: ResourceConfig) => PresetResult;
-interface EventDefinition {
-  name: string;
-  /** Optional handler — events are published via `fastify.events.publish()`. */
-  handler?: (data: unknown) => Promise<void> | void;
-  /** JSON schema for event payload */
-  schema?: Record<string, unknown>;
-  description?: string;
+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/handlers.d.ts
+/**
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `raw: true`.
+ */
+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>;
+  };
 }
-/** Resource-level permissions — only `PermissionCheck` functions allowed. */
-interface ResourcePermissions {
-  list?: PermissionCheck;
-  get?: PermissionCheck;
-  create?: PermissionCheck;
-  update?: PermissionCheck;
-  delete?: PermissionCheck;
+/**
+ * Request context passed to controller handlers.
+ *
+ * **Generic parameters** (all default to safe permissive types so existing code keeps working):
+ * - `TBody`     — request body shape (default: `unknown`)
+ * - `TParams`   — route param shape (default: `Record<string, string>`)
+ * - `TQuery`    — query string shape (default: `Record<string, unknown>`)
+ * - `TUser`     — authenticated user shape (default: `UserBase`)
+ * - `TMetadata` — internal metadata shape (default: `Record<string, unknown>`;
+ *   override with `ArcInternalMetadata` or your own augmentation when you
+ *   need typed access to `_scope`, `_policyFilters`, custom hook context, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Untyped (default) — req.body is `unknown`, must be narrowed
+ * async create(req: IRequestContext) {
+ *   const data = req.body as Partial<Product>;
+ *   return { success: true, data: await productRepo.create(data) };
+ * }
+ *
+ * // Typed body — req.body is `CreateProductInput`, narrowing not needed
+ * async create(req: IRequestContext<CreateProductInput>) {
+ *   return { success: true, data: await productRepo.create(req.body) };
+ * }
+ *
+ * // Fully typed — body, route params, query, and metadata
+ * async update(
+ *   req: IRequestContext<
+ *     Partial<Product>,
+ *     { id: string },
+ *     { fields?: string },
+ *     ArcInternalMetadata
+ *   >,
+ * ) {
+ *   const fields = req.query.fields?.split(',');
+ *   const orgId = req.metadata?._scope ? getOrgId(req.metadata._scope) : undefined;
+ *   return { success: true, data: await productRepo.update(req.params.id, req.body) };
+ * }
+ * ```
+ */
+/**
+ * First-class projection of `request._scope` for controller handlers.
+ *
+ * **v2.10.6:** previously, pulling tenant/user/role info from inside a
+ * controller override meant digging through `req.metadata._scope` and
+ * calling `getOrgId(scope)` / `getUserId(user)` manually. This projection
+ * lifts the two fields most hosts need directly onto `req` so cross-kit
+ * controller code reads:
+ *
+ * ```ts
+ * async create(req: IRequestContext) {
+ *   const flowCtx = { organizationId: req.scope?.organizationId, actorId: req.scope?.userId };
+ * }
+ * ```
+ *
+ * Full scope shape (discriminated union of `member` / `service` / `elevated` / `public`)
+ * still lives on `req.metadata._scope` for code that needs to branch on
+ * `scope.kind` — this projection just surfaces the two keys every
+ * tenant-scoped resource reaches for.
+ */
+interface RequestScopeProjection {
+  /** Tenant the caller is scoped to (org member, service key bound to an org, or elevated admin's target org). */
+  organizationId?: string;
+  /** Caller's user id when authenticated — undefined for public / service-only scopes. */
+  userId?: string;
+  /** Org-level roles (e.g. `['admin', 'warehouse-manager']`) — separate from global `user.roles`. */
+  orgRoles?: string[];
 }
-interface ResourceConfig<TDoc = AnyRecord> {
-  name: string;
-  displayName?: string;
-  tag?: string;
-  /** Defaults to `/${name}s` if not provided. */
-  prefix?: string;
-  /**
-   * Skip the global `resourcePrefix` from `createApp()`. The resource
-   * registers at its own `prefix` (or `/${name}s`) directly on root.
-   * Useful for webhooks, health, admin routes that shouldn't be under
-   * `/api/v1`.
-   *
-   * @example
-   * ```typescript
-   * defineResource({ name: 'webhook', prefix: '/webhooks', skipGlobalPrefix: true })
-   * ```
-   */
-  skipGlobalPrefix?: boolean;
-  /** Optional for service-pattern resources */
-  adapter?: DataAdapter<TDoc>;
-  /** Controller instance — accepts any object with CRUD methods. */
-  controller?: IController<TDoc> | ControllerLike;
-  queryParser?: unknown;
-  permissions?: ResourcePermissions;
-  schemaOptions?: RouteSchemaOptions;
-  openApiSchemas?: OpenApiSchemas;
-  /** Custom JSON schemas (override Arc-generated). */
-  customSchemas?: Partial<CrudSchemas>;
-  /** Preset names, objects, or PresetResult values. */
-  presets?: Array<string | PresetResult | {
-    name: string;
-    [key: string]: unknown;
-  }>;
-  hooks?: ResourceHooks;
+interface IRequestContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>, TUser extends UserBase = UserBase, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+  /** Route parameters (e.g., { id: '123' }) */
+  params: TParams;
+  /** Query string parameters */
+  query: TQuery;
+  /** Request body */
+  body: TBody;
+  /** Authenticated user or null */
+  user: TUser | null;
+  /** Request headers */
+  headers: Record<string, string | undefined>;
+  /** Organization ID (for multi-tenant apps) */
+  organizationId?: string;
+  /** Team ID (for team-scoped resources) */
+  teamId?: string;
   /**
-   * Functional pipeline — guards, transforms, interceptors. Flat array
-   * (all operations) or per-operation map.
-   *
-   * @example
-   * ```typescript
-   * pipe: pipe(isActive, slugify, timing),
-   * pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
-   * ```
+   * First-class tenant/user scope projection — lifted from `metadata._scope`
+   * so controller overrides don't have to dig through Arc internals.
+   * See {@link RequestScopeProjection}. `undefined` for routes that run
+   * without auth / scope resolution.
    */
-  pipe?: PipelineConfig;
+  scope?: RequestScopeProjection;
   /**
-   * Field-level permissions — control visibility and writability per role.
+   * Organization/auth context from middleware.
+   * Contains orgRoles, orgScope, organizationId, and any custom fields
+   * set by the auth adapter or org-scope plugin.
    *
    * @example
    * ```typescript
-   * fields: {
-   *   salary: fields.visibleTo(['admin', 'hr']),
-   *   password: fields.hidden(),
+   * async create(req: IRequestContext) {
+   *   const roles = req.context?.orgRoles ?? [];
+   *   if (roles.includes('manager')) { ... }
    * }
    * ```
    */
-  fields?: FieldPermissionMap;
-  /**
-   * Policy for requests that include fields the caller can't write.
-   *
-   * - `'reject'` (default, secure): 403 with the denied field names.
-   *   Surfaces misconfigurations and write-side permission violations
-   *   instead of silently dropping them.
-   * - `'strip'`: legacy silent-drop behaviour — only opt in when migrating
-   *   pre-2.9 code that relied on the permissive default.
-   */
-  onFieldWriteDenied?: "reject" | "strip";
-  middlewares?: MiddlewareConfig;
+  context?: RequestContext;
   /**
-   * PreHandler guards auto-applied to **every** route on this resource
-   * (CRUD + custom + preset). Runs after auth/permissions, before
-   * per-route `preHandler`. Use for mode gates, tenant checks, feature
-   * flags — anything that applies to every endpoint.
+   * Internal metadata (includes context + Arc internals like `_policyFilters`,
+   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
+   * built-in fields, or supply your own interface to layer custom fields.
    */
-  routeGuards?: RouteHandlerMethod[];
+  metadata?: TMetadata;
   /**
-   * Custom routes beyond CRUD. Presets also merge their routes here.
+   * Fastify server accessor — publish events, log, and audit
+   * from any handler without switching to `raw: true`.
    *
    * @example
    * ```typescript
-   * routes: [
-   *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
-   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
-   * ]
+   * 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 };
+   * }
    * ```
    */
-  routes?: RouteDefinition[];
-  /**
-   * State-transition actions → unified `POST /:id/action` endpoint.
-   * Each action can be a bare handler or full config with permissions
-   * + schema.
-   *
-   * @example
-   * ```typescript
+  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 `raw: false` in routes.
+ *
+ * **Generic parameters:**
+ * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
+ * - `TBody`     — shape of `req.body` (default: `unknown`)
+ * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
+ * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
+ *
+ * Backward-compatible: `ControllerHandler<Product>` still works (only the
+ * response data is typed); add more generics as needed when you want
+ * type-safe access to the request body, params, or query string.
+ *
+ * @example
+ * ```typescript
+ * // Untyped req — body is unknown, must be narrowed
+ * const createProduct: ControllerHandler<Product> = async (req) => {
+ *   const product = await productRepo.create(req.body as Partial<Product>);
+ *   return { success: true, data: product, status: 201 };
+ * };
+ *
+ * // Fully typed — body, params, query, and response all inferred
+ * const updateProduct: ControllerHandler<
+ *   Product,
+ *   Partial<Product>,
+ *   { id: string },
+ *   { upsert?: string }
+ * > = async (req) => {
+ *   const upsert = req.query.upsert === "true";
+ *   const product = await productRepo.update(req.params.id, req.body, { upsert });
+ *   return { success: true, data: product };
+ * };
+ *
+ * routes: [{
+ *   method: 'POST',
+ *   path: '/products',
+ *   handler: createProduct,
+ *   permissions: requireAuth(),
+ *   raw: false,  // Arc wraps this into Fastify handler
+ * }]
+ * ```
+ */
+type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
+/**
+ * Fastify native handler
+ *
+ * Standard Fastify request/reply pattern.
+ * Use with `raw: true` in routes.
+ *
+ * @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);
+ * };
+ *
+ * routes: [{
+ *   method: 'GET',
+ *   path: '/files/:id/download',
+ *   handler: downloadFile,
+ *   permissions: requireAuth(),
+ *   raw: true,  // Use as-is, no wrapping
+ * }]
+ * ```
+ */
+type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
+/**
+ * Union type for route handlers
+ */
+type RouteHandler = ControllerHandler | FastifyHandler;
+/**
+ * Controller interface for CRUD operations (strict).
+ *
+ * `list`'s return type aligns with repo-core's `MinimalRepo.getAll()`
+ * contract — the kit MAY return an offset envelope, a keyset envelope,
+ * or a raw array. Arc's `BaseController` forwards the kit's response
+ * verbatim; consumers narrow on shape
+ * (`Array.isArray(data)` → bare array, presence of `total` → offset,
+ * presence of `nextCursor` → keyset).
+ */
+interface IController<TDoc = unknown> {
+  list(req: IRequestContext): Promise<IControllerResponse<unknown>>;
+  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,
+ * including class instances with extra methods / private fields.
+ *
+ * **v2.10.6:** the previous `[key: string]: unknown` index signature made
+ * real class instances fail structural assignment (`new ScrapController()`
+ * needed a `as unknown as ControllerLike` cast, because class instances
+ * don't have an index signature). Dropped — arc only invokes the CRUD
+ * methods at runtime, so the rest of the shape is the caller's concern.
+ *
+ * The five CRUD slots stay optional so partial controllers (e.g. read-only)
+ * assign too. Additional domain methods on the controller are allowed by
+ * construction (they're just not part of this contract).
+ */
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
+}
+//#endregion
+//#region src/types/resource.d.ts
+/** Standard controller type alias for CRUD operations. */
+type CrudController<TDoc> = IController<TDoc>;
+/**
+ * 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.
+   * @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') */
+  timeWindow: string;
+}
+interface RouteSchemaOptions {
+  hiddenFields?: string[];
+  readonlyFields?: string[];
+  requiredFields?: string[];
+  optionalFields?: string[];
+  excludeFields?: string[];
+  /**
+   * Fields allowed for filtering in list operations. MCP auto-derives
+   * from `QueryParser.allowedFilterFields` when not set explicitly.
+   */
+  filterableFields?: string[];
+  fieldRules?: Record<string, {
+    systemManaged?: boolean;
+    /**
+     * When `true`, bypass the `systemManaged` / `readonly` / `immutable`
+     * strip in `BodySanitizer` for callers whose request scope is
+     * `elevated`. Lets platform admins stamp the value from the request
+     * body — needed for cross-tenant admin writes where the tenant field
+     * is the only way to pick a target org.
+     *
+     * Auto-set by `defineResource` on the configured `tenantField`. Hosts
+     * can set it manually on other fields (e.g. `createdBy`) if they want
+     * elevation-only override semantics for those too.
+     *
+     * Has no effect when `isElevated(scope)` is false — member and
+     * service callers continue to have the field stripped.
+     */
+    preserveForElevated?: boolean;
+    hidden?: boolean;
+    immutable?: boolean;
+    immutableAfterCreate?: boolean;
+    optional?: boolean; /** String minimum length — auto-maps to OpenAPI `minLength` and MCP tool schema */
+    minLength?: number; /** String maximum length — auto-maps to OpenAPI `maxLength` and MCP tool schema */
+    maxLength?: number; /** Number minimum — auto-maps to OpenAPI `minimum` and MCP tool schema */
+    min?: number; /** Number maximum — auto-maps to OpenAPI `maximum` and MCP tool schema */
+    max?: number; /** Regex pattern — auto-maps to OpenAPI `pattern` and MCP tool schema */
+    pattern?: string; /** Allowed values — auto-maps to OpenAPI `enum` and MCP tool schema */
+    enum?: ReadonlyArray<string | number>; /** Human-readable description — auto-maps to OpenAPI `description` */
+    description?: string;
+    [key: string]: unknown;
+  }>;
+  /** Query parameter schema for OpenAPI */
+  query?: Record<string, unknown>;
+  /**
+   * When `true`, emitted CRUD body schemas set `additionalProperties: false`
+   * so AJV rejects unknown fields on create / update. Honored by kit schema
+   * generators that receive this options bag (sqlitekit's
+   * `buildCrudSchemasFromTable`, pgkit's equivalent). Mongoose-based
+   * generators may ignore it — Mongoose schemas are inherently strict at
+   * the model level.
+   */
+  strictAdditionalProperties?: boolean;
+}
+interface FieldRule {
+  field: string;
+  required?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
+}
+/**
+ * CRUD route schemas (Fastify native format). Each slot accepts a plain
+ * JSON Schema object **or** a Zod v4 schema — Arc's `convertRouteSchema`
+ * feature-detects at runtime. Slot values are typed `unknown` so
+ * class-based Zod schemas assign without casts.
+ */
+interface CrudSchemas {
+  /** GET / — list */
+  list?: {
+    querystring?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** GET /:id — get one */
+  get?: {
+    params?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** POST / — create */
+  create?: {
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** PATCH /:id — update */
+  update?: {
+    params?: unknown;
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** DELETE /:id — delete */
+  delete?: {
+    params?: 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. Auto-generated
+   * from `createBody` if omitted. Does NOT affect Fastify serialization.
+   */
+  response?: unknown;
+  [key: string]: unknown;
+}
+type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
+interface MiddlewareConfig {
+  list?: MiddlewareHandler[];
+  get?: MiddlewareHandler[];
+  create?: MiddlewareHandler[];
+  update?: MiddlewareHandler[];
+  delete?: MiddlewareHandler[];
+  [key: string]: MiddlewareHandler[] | undefined;
+}
+/** HTTP methods for custom routes. */
+type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** MCP tool configuration for a route or action. */
+interface RouteMcpConfig {
+  /** Override auto-generated tool description */
+  readonly description?: string;
+  /** MCP tool annotations */
+  readonly annotations?: {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+  };
+}
+/**
+ * Route definition — single custom-route shape (user-facing + internal).
+ *
+ * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
+ * - `handler: function` → inline handler → full Arc pipeline + MCP tool
+ * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
+ */
+interface RouteDefinition {
+  readonly method: RouteMethod;
+  /** Path relative to resource prefix */
+  readonly path: string;
+  /**
+   * Route handler.
+   * - String: controller method name (Arc pipeline)
+   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
+   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
+   */
+  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
+  /** Permission check — REQUIRED */
+  readonly permissions: PermissionCheck;
+  /**
+   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
+   * request/reply. Default: false.
+   */
+  readonly raw?: boolean;
+  /** Logical operation name (pipeline keys, MCP tool naming). */
+  readonly operation?: string;
+  /** OpenAPI summary */
+  readonly summary?: string;
+  /** OpenAPI description */
+  readonly description?: string;
+  /** OpenAPI tags */
+  readonly tags?: string[];
+  /** Route-level middleware */
+  readonly preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
+  /** Pre-auth handlers (run before authentication) */
+  readonly preAuth?: RouteHandlerMethod[];
+  /** SSE streaming mode */
+  readonly streamResponse?: boolean;
+  /**
+   * Fastify route schema. Each slot (`body`, `querystring`, `params`,
+   * `headers`, `response[status]`) accepts a plain JSON Schema object
+   * **or** a Zod v4 schema — Arc auto-converts via `convertRouteSchema`.
+   */
+  readonly schema?: {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<number | string, unknown>;
+    [key: string]: unknown;
+  };
+  /**
+   * MCP tool generation:
+   * - omitted/true: auto-generate (non-raw routes only)
+   * - false: skip MCP
+   * - object: explicit config
+   */
+  readonly mcp?: boolean | RouteMcpConfig;
+  /**
+   * MCP handler for raw routes — parallel entry point for MCP without
+   * changing the HTTP handler.
+   */
+  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
+}
+/**
+ * Action handler function for state transitions. Receives the resource
+ * ID, action-specific data, and the request.
+ */
+type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
+/** Full action configuration with handler, permissions, and schema. */
+interface ActionDefinition {
+  readonly handler: ActionHandlerFn;
+  /** Per-action permission (overrides resource-level `actionPermissions`) */
+  readonly permissions?: PermissionCheck;
+  /**
+   * JSON Schema or Zod v4 schema for action-specific body fields.
+   * Per-field values are typed `unknown` so Zod class instances assign
+   * without casts.
+   */
+  readonly schema?: Record<string, unknown>;
+  /** Description for OpenAPI docs and MCP tool */
+  readonly description?: string;
+  /**
+   * MCP tool generation:
+   * - omitted/true: auto-generate
+   * - false: skip
+   * - object: explicit config
+   */
+  readonly mcp?: boolean | RouteMcpConfig;
+}
+/** Action config: bare handler function OR full ActionDefinition. */
+type ActionEntry = ActionHandlerFn | ActionDefinition;
+/** Actions configuration map. */
+type ActionsMap = Record<string, ActionEntry>;
+/**
+ * Hook context passed to resource-level hook handlers. Mirrors
+ * HookSystem's HookContext but with a simpler API for inline use.
+ *
+ * **v2.10.8:** `context` and a first-class `scope` projection are now
+ * forwarded from the internal `HookContext`. Before this release, inline
+ * `config.hooks` handlers had no way to reach the caller's tenant or
+ * user info — they had to bypass the documented API and push directly
+ * into `resource._pendingHooks` to get the raw internal shape. Now the
+ * documented DX is complete:
+ *
+ * ```ts
+ * hooks: {
+ *   afterCreate: (ctx) => {
+ *     auditLog.write({
+ *       org: ctx.scope?.organizationId,
+ *       actor: ctx.scope?.userId,
+ *       id: ctx.data._id,
+ *     });
+ *   },
+ * }
+ * ```
+ *
+ * The `scope` projection matches `IRequestContext.scope` (2.10.6) so
+ * hosts read tenant/user the same way across controllers and hooks.
+ * Use `context._scope` directly for advanced cases that need to
+ * discriminate on `scope.kind` or reach auth-adapter-specific fields.
+ */
+interface ResourceHookContext {
+  /** The document data (create/update body, or existing doc for delete / after-result) */
+  data: AnyRecord;
+  /** Authenticated user or null */
+  user?: UserBase;
+  /**
+   * Full typed request context — includes `_scope`, `_policyFilters`,
+   * `arc` metadata. Use `ctx.scope` for the common tenant/user projection;
+   * reach for `ctx.context` when you need `_scope.kind` branching or
+   * custom fields set by your auth adapter.
+   */
+  context?: AnyRecord;
+  /**
+   * First-class projection of request scope — `{ organizationId?, userId?, orgRoles? }`.
+   * Populated for every scoped request so multi-tenant hooks don't have to
+   * drill into `context._scope.organizationId` themselves. Matches the
+   * identically-named field on `IRequestContext` (v2.10.6) so the same
+   * read pattern works in controllers and hooks.
+   */
+  scope?: {
+    organizationId?: string;
+    userId?: string;
+    orgRoles?: string[];
+  };
+  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
+  meta?: AnyRecord;
+}
+/**
+ * Inline lifecycle hooks on a resource definition. Wired into the
+ * HookSystem automatically — same pipeline as presets and app-level hooks.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'chat',
+ *   hooks: {
+ *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
+ *     beforeDelete: async (ctx) => {
+ *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface ResourceHooks {
+  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | void;
+  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  afterUpdate?: (ctx: ResourceHookContext) => Promise<void> | void;
+  beforeDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+  afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+}
+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;
+  /** Preset routes — merged into the resource's `routes` array. */
+  routes?: RouteDefinition[] | ((permissions: ResourcePermissions) => RouteDefinition[]);
+  middlewares?: MiddlewareConfig;
+  schemaOptions?: RouteSchemaOptions;
+  controllerOptions?: Record<string, unknown>;
+  hooks?: PresetHook[];
+}
+type PresetFunction = (config: ResourceConfig) => PresetResult;
+interface EventDefinition {
+  name: string;
+  /** Optional handler — events are published via `fastify.events.publish()`. */
+  handler?: (data: unknown) => Promise<void> | void;
+  /** JSON schema for event payload */
+  schema?: Record<string, unknown>;
+  description?: string;
+}
+/** Resource-level permissions — only `PermissionCheck` functions allowed. */
+interface ResourcePermissions {
+  list?: PermissionCheck;
+  get?: PermissionCheck;
+  create?: PermissionCheck;
+  update?: PermissionCheck;
+  delete?: PermissionCheck;
+}
+interface ResourceConfig<TDoc = AnyRecord> {
+  name: string;
+  displayName?: string;
+  tag?: string;
+  /** Defaults to `/${name}s` if not provided. */
+  prefix?: string;
+  /**
+   * Skip the global `resourcePrefix` from `createApp()`. The resource
+   * registers at its own `prefix` (or `/${name}s`) directly on root.
+   * Useful for webhooks, health, admin routes that shouldn't be under
+   * `/api/v1`.
+   *
+   * @example
+   * ```typescript
+   * defineResource({ name: 'webhook', prefix: '/webhooks', skipGlobalPrefix: true })
+   * ```
+   */
+  skipGlobalPrefix?: boolean;
+  /** Optional for service-pattern resources */
+  adapter?: DataAdapter<TDoc>;
+  /** Controller instance — accepts any object with CRUD methods. */
+  controller?: IController<TDoc> | ControllerLike;
+  queryParser?: unknown;
+  permissions?: ResourcePermissions;
+  schemaOptions?: RouteSchemaOptions;
+  openApiSchemas?: OpenApiSchemas;
+  /** Custom JSON schemas (override Arc-generated). */
+  customSchemas?: Partial<CrudSchemas>;
+  /** Preset names, objects, or PresetResult values. */
+  presets?: Array<string | PresetResult | {
+    name: string;
+    [key: string]: unknown;
+  }>;
+  hooks?: ResourceHooks;
+  /**
+   * Functional pipeline — guards, transforms, interceptors. Flat array
+   * (all operations) or per-operation map.
+   *
+   * @example
+   * ```typescript
+   * pipe: pipe(isActive, slugify, timing),
+   * pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
+   * ```
+   */
+  pipe?: PipelineConfig;
+  /**
+   * Field-level permissions — control visibility and writability per role.
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   salary: fields.visibleTo(['admin', 'hr']),
+   *   password: fields.hidden(),
+   * }
+   * ```
+   */
+  fields?: FieldPermissionMap;
+  /**
+   * Policy for requests that include fields the caller can't write.
+   *
+   * - `'reject'` (default, secure): 403 with the denied field names.
+   *   Surfaces misconfigurations and write-side permission violations
+   *   instead of silently dropping them.
+   * - `'strip'`: legacy silent-drop behaviour — only opt in when migrating
+   *   pre-2.9 code that relied on the permissive default.
+   */
+  onFieldWriteDenied?: "reject" | "strip";
+  middlewares?: MiddlewareConfig;
+  /**
+   * PreHandler guards auto-applied to **every** route on this resource
+   * (CRUD + custom + preset). Runs after auth/permissions, before
+   * per-route `preHandler`. Use for mode gates, tenant checks, feature
+   * flags — anything that applies to every endpoint.
+   */
+  routeGuards?: RouteHandlerMethod[];
+  /**
+   * Custom routes beyond CRUD. Presets also merge their routes here.
+   *
+   * @example
+   * ```typescript
+   * routes: [
+   *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
+   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
+   * ]
+   * ```
+   */
+  routes?: RouteDefinition[];
+  /**
+   * State-transition actions → unified `POST /:id/action` endpoint.
+   * Each action can be a bare handler or full config with permissions
+   * + schema.
+   *
+   * @example
+   * ```typescript
    * actions: {
    *   approve: async (id, data, req) => service.approve(id, req.user._id),
    *   cancel: {
@@ -1404,6 +1753,24 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * Override to match your schema: 'workspaceId', 'tenantId', etc.
    */
   tenantField?: string | false;
+  /**
+   * Default sort applied to `list` responses when the request doesn't
+   * specify one. Arc's built-in default is `-createdAt` (Mongo convention).
+   *
+   *   - `string` — override (e.g. `'-created_at'`, `'-id'`).
+   *   - `false` — disable the default entirely. The adapter returns rows
+   *     in its native order (primary-key order on most kits). **Use this
+   *     for SQL/Drizzle resources that don't declare a `createdAt`
+   *     column** — without it, the framework default would compile to
+   *     `ORDER BY "createdAt" DESC` against a missing column.
+   *
+   * @example
+   * ```ts
+   * defineResource({ name: 'metric', defaultSort: '-recordedAt' });
+   * defineResource({ name: 'tag', defaultSort: false }); // no default sort
+   * ```
+   */
+  defaultSort?: string | false;
   /**
    * Primary key field name (default: '_id').
    *
@@ -1467,1035 +1834,875 @@ interface ResourceConfig<TDoc = AnyRecord> {
   };
 }
 //#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 routes: readonly RouteDefinition[];
-  readonly middlewares: MiddlewareConfig;
-  readonly routeGuards?: RouteHandlerMethod$1[];
-  readonly disableDefaultRoutes: boolean;
-  readonly disabledRoutes: CrudRouteKey[];
-  readonly actions?: ActionsMap;
-  readonly actionPermissions?: PermissionCheck;
-  readonly events: Record<string, EventDefinition>;
-  readonly rateLimit?: RateLimitConfig | false;
-  readonly audit?: boolean | {
-    operations?: ("create" | "update" | "delete")[];
-  };
-  readonly updateMethod?: "PUT" | "PATCH" | "both";
-  readonly pipe?: PipelineConfig;
-  readonly fields?: FieldPermissionMap;
-  readonly cache?: ResourceCacheConfig;
-  readonly skipGlobalPrefix: boolean;
-  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(): _$_classytic_repo_core_repository0.StandardRepo<TDoc> | RepositoryLike<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;
+//#region src/hooks/HookSystem.d.ts
+type HookPhase = "before" | "around" | "after";
+type HookOperation = "create" | "update" | "delete" | "restore" | "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);
   /**
-   * Freeze registry (prevent further registrations)
+   * Generate hook key
    */
-  freeze(): void;
+  private getKey;
   /**
-   * Check if frozen
+   * Register a hook
+   * Supports both object parameter and positional arguments
    */
-  isFrozen(): boolean;
+  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;
   /**
-   * Unfreeze registry (allow new registrations)
+   * Register before hook
    */
-  unfreeze(): void;
+  before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
   /**
-   * Reset registry — clear all resources and unfreeze
+   * Register after hook
    */
-  reset(): void;
-  /** @internal Alias for unfreeze() */
-  _unfreeze(): void;
-  /** @internal Alias for reset() */
-  _clear(): void;
+  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
   /**
-   * Group by key
+   * Register around hook — wraps the core operation.
+   * Call `next()` inside the handler to proceed.
    */
-  private _groupBy;
-}
-//#endregion
-//#region src/types/fastify.d.ts
-interface FastifyRequestExtras {
-  user?: Record<string, unknown>;
-}
-interface RequestWithExtras extends FastifyRequest {
+  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
   /**
-   * Arc metadata — set by createCrudRouter. Contains resource configuration
-   * and schema options.
+   * Execute around hooks as a nested middleware chain.
+   * Each around hook receives `next()` to call the next hook or the core operation.
    */
-  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 — added by `arcCorePlugin`. Provides instance-scoped
- * hooks and resource registry.
- */
-interface ArcDecorator {
-  hooks: HookSystem;
-  registry: ResourceRegistry;
-  /** Whether event emission is enabled */
-  emitEvents: boolean;
-}
-/** Events decorator — added by `eventPlugin`. Provides event pub/sub. */
-interface EventsDecorator {
-  publish: <T>(type: string, payload: T, meta?: Partial<{
-    id: string;
-    timestamp: Date;
-  }>) => Promise<void>;
+  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T | undefined>;
   /**
-   * Subscribe to an event pattern. Handler receives the full
-   * `DomainEvent<T> = { type, payload, meta }` envelope — destructure
-   * `payload` if you only need the body, or read `meta.correlationId` /
-   * `meta.timestamp` for tracing. See CHANGELOG 2.10 for the migration
-   * note from 2.9.x's loose `unknown` type.
+   * Execute hooks for a given context
    */
-  subscribe: <T = unknown>(pattern: string, handler: (event: DomainEvent<T>) => void | Promise<void>) => Promise<() => void>;
-  transportName: string;
-}
-/**
- * Fastify instance with Arc decorators. Arc adds these via plugins/presets.
- */
-type FastifyWithDecorators = FastifyInstance & {
-  arc?: ArcDecorator;
-  events?: EventsDecorator;
-  authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>; /** Organization-scoped filtering — from `multiTenant` preset */
-  organizationScoped?: (options?: {
-    required?: boolean;
-  }) => RouteHandlerMethod;
-  [key: string]: unknown;
-};
-/** Handler signature for middleware functions. */
-type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
-//#endregion
-//#region src/types/auth.d.ts
-/**
- * JWT utilities provided to authenticator. Arc provides the helpers;
- * apps use 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. The app has full control over authentication logic.
- *
- * Return a user object to authenticate, `null`/`undefined` to reject.
- *
- * @example
- * ```typescript
- * 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);
- * }
- * ```
- */
-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 exposed on `fastify.auth`.
- *
- * @example
- * ```typescript
- * 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;
+  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
   /**
-   * Issue access + refresh tokens for a user. App calls this after
-   * validating credentials.
+   * Execute before hooks
    */
-  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;
-}
-/**
- * Auth plugin options — clean, minimal configuration.
- *
- * Arc provides JWT infrastructure and calls your authenticator. You
- * control all authentication logic.
- *
- * @example
- * ```typescript
- * 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);
- *   },
- * }
- * ```
- */
-interface AuthPluginOptions {
+  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T>;
   /**
-   * JWT configuration (optional but recommended). If provided, JWT
-   * utilities are available in the authenticator context.
+   * Execute after hooks
+   * Errors in after hooks are logged but don't fail the request
    */
-  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>;
-  };
+  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<void>;
   /**
-   * Custom authenticator function. Arc calls this for non-public routes.
-   * If not provided and `jwt.secret` is set, uses default `jwtVerify`.
+   * 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.
    */
-  authenticate?: Authenticator;
+  private topologicalSort;
   /**
-   * Custom auth failure handler. Customize the 401 response when
-   * authentication fails.
+   * Get all registered hooks
    */
-  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  getAll(): HookRegistration[];
   /**
-   * Expose detailed auth error messages in 401 responses. When `false`
-   * (default), returns generic "Authentication required". Decoupled from
-   * log level — set explicitly per environment.
+   * Get hooks for a specific resource
    */
-  exposeAuthErrors?: boolean;
-  /** Property name to store user on request (default: 'user') */
-  userProperty?: string;
+  getForResource(resource: string): HookRegistration[];
   /**
-   * Custom token extractor for the built-in JWT auth path. Defaults to
-   * extracting Bearer token from Authorization header. Use when tokens
-   * are in HttpOnly cookies, custom headers, or query params.
+   * Get hooks matching filter criteria.
+   * Useful for debugging and testing specific hook combinations.
    *
    * @example
    * ```typescript
-   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
+   * // Find all before-create hooks for products (including wildcards)
+   * const hooks = hookSystem.getRegistered({
+   *   resource: 'product',
+   *   operation: 'create',
+   *   phase: 'before',
+   * });
    * ```
    */
-  tokenExtractor?: (request: FastifyRequest) => string | null;
+  getRegistered(filter?: {
+    resource?: string;
+    operation?: HookOperation;
+    phase?: HookPhase;
+  }): HookRegistration[];
   /**
-   * Token revocation check — called after JWT verification succeeds.
-   * Return `true` to reject the token (revoked), `false` to allow.
-   *
-   * **Fail-closed**: if the check throws, the token is treated as revoked.
+   * Get a structured summary of all registered hooks for debugging.
    *
    * @example
    * ```typescript
-   * isRevoked: async (decoded) => {
-   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
-   * },
+   * const info = hookSystem.inspect();
+   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
    * ```
    */
-  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
-  /**
-   * Enforce strict JWT `type` claim validation (default: `true`).
-   *
-   * When enabled, `authenticate` requires `decoded.type === "access"`.
-   * Tokens with a missing or unexpected `type` claim are rejected —
-   * defence in depth for apps that reuse the JWT secret to sign other
-   * token kinds (invite links, one-time verification codes).
-   *
-   * Arc's own `issueTokens` always sets `type: "access"` or
-   * `type: "refresh"`, so this default is safe for Arc-generated tokens.
-   *
-   * Set to `false` ONLY when you must accept tokens signed without a
-   * `type` claim (e.g. a legacy issuer you don't control). In that mode
-   * Arc still rejects tokens explicitly marked `type: "refresh"`.
-   */
-  strictTokenType?: boolean;
-}
-//#endregion
-//#region src/types/plugins.d.ts
-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;
-}
-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;
-  /** Custom routes (from presets or user-defined) */
-  routes?: readonly RouteDefinition[];
-  /** 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. Set to `false` to disable for this resource.
-   */
-  rateLimit?: RateLimitConfig | false;
-  /** PreHandler guards applied to every route (CRUD + custom + preset). */
-  routeGuards?: RouteHandlerMethod[];
-}
-//#endregion
-//#region src/types/registry.d.ts
-interface ResourceMetadata {
-  name: string;
-  displayName?: string;
-  tag?: string;
-  prefix: string;
-  module?: string;
-  permissions?: ResourcePermissions;
-  presets: string[];
-  customRoutes?: Array<{
-    method: string;
-    path: string;
-    handler: string;
-    operation?: string;
-    summary?: string;
-    description?: string;
-    permissions?: PermissionCheck;
-    raw?: boolean;
-    schema?: Record<string, unknown>;
-  }>;
-  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;
-  /** Per-resource audit opt-in flag (read by `auditPlugin` perResource mode) */
-  audit?: boolean | {
-    operations?: ("create" | "update" | "delete")[];
-  };
-  /**
-   * v2.8 declarative actions metadata — populated from
-   * `ResourceConfig.actions`. Consumed by OpenAPI generation (renders
-   * `POST /:id/action` with a discriminated body schema) and MCP tool
-   * generation. Added in 2.8.1.
-   */
-  actions?: Array<{
-    readonly name: string;
-    readonly description?: string; /** Raw per-action schema (JSON Schema, Zod v4, or legacy field map) */
-    readonly schema?: Record<string, unknown>; /** Per-action permission check (if different from resource-level `actionPermissions`) */
-    readonly permissions?: PermissionCheck; /** MCP tool generation flag — `false` to skip, object for overrides */
-    readonly mcp?: boolean | {
-      readonly description?: string;
-      readonly annotations?: Record<string, unknown>;
-    };
-  }>;
-  /**
-   * Resource-level fallback permission for actions without per-action
-   * permissions. Used by OpenAPI to determine auth requirements and by
-   * MCP as the fallback in `createActionToolHandler`. Added in 2.8.1.
-   */
-  actionPermissions?: PermissionCheck;
-}
-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;
-}
-//#endregion
-//#region src/types/validation.d.ts
-/**
- * Validation result types — produced by `validateResourceConfig` and
- * consumed by `assertValidConfig` / `formatValidationErrors`.
- */
-interface ConfigError {
-  field: string;
-  message: string;
-  code?: string;
-}
-interface ValidationResult {
-  valid: boolean;
-  errors: ConfigError[];
-}
-interface ValidateOptions {
-  strict?: boolean;
+  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;
 }
-//#endregion
-//#region src/types/utility.d.ts
 /**
- * Infer document type from a `DataAdapter` or `ResourceConfig`. Smart
- * inference that works with multiple sources.
+ * Create a new isolated HookSystem instance
+ *
+ * Use this for:
+ * - Test isolation (parallel test suites)
+ * - Multiple app instances with independent hooks
  *
  * @example
- * ```typescript
- * type Doc1 = InferDocType<typeof adapter>;     // From DataAdapter
- * type Doc2 = InferDocType<typeof resource>;    // From ResourceConfig
- * ```
+ * const hooks = createHookSystem();
+ * await app.register(arcCorePlugin, { hookSystem: hooks });
+ *
+ * @example With custom logger
+ * const hooks = createHookSystem({ logger: fastify.log });
  */
-type InferDocType<T> = T extends DataAdapter<infer D> ? D : T extends ResourceConfig<infer D> ? D : never;
+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[];
+}
 /**
- * Infer document type from a `DataAdapter`. Falls back to `unknown`
- * (not `never`) — safe for generic constraints.
+ * Define a named hook with optional dependencies.
+ * Returns a registration object — call `register(hookSystem)` to activate.
  *
  * @example
  * ```typescript
- * const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
- * type ProductDoc = InferAdapterDoc<typeof adapter>;
+ * 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);
  * ```
  */
-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> = StandardRepo<TDoc>;
+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/types/repository.d.ts
+//#region src/core/defineResource.d.ts
 /**
- * Discriminated union of pagination result shapes. Narrow on `method`.
- *
- * repo-core ships the individual shapes (`OffsetPaginationResult` /
- * `KeysetPaginationResult`) but no combined union — arc needs one for the
- * BaseController's `list` / `getDeleted` return signatures, where either
- * shape is valid depending on the caller's pagination params.
+ * Define a resource with database adapter
  *
- * @example
- * ```ts
- * const result = await repo.getAll(params);
- * if (result.method === 'keyset') {
- *   result.next;     // keyset cursor
- * } else {
- *   result.page;     // offset number
- * }
- * ```
+ * This is the MAIN entry point for creating Arc resources.
+ * The adapter provides both repository and schema metadata.
  */
-type PaginationResult<TDoc, TExtra extends Record<string, unknown> = Record<string, never>> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra>;
-//#endregion
-//#region src/core/AccessControl.d.ts
-/** Denial reason codes returned by `fetchDetailed()`. */
-type FetchDenialReason = "NOT_FOUND" | "POLICY_FILTERED" | "ORG_SCOPE_DENIED";
-/** Result of a detailed fetch with access control. */
-interface FetchResult<TDoc> {
-  /** The document, or null if denied. */
-  doc: TDoc | null;
-  /** Null when the doc was found. A string code when denied. */
-  reason: FetchDenialReason | null;
+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;
+  }>;
 }
-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;
+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 routes: readonly RouteDefinition[];
+  readonly middlewares: MiddlewareConfig;
+  readonly routeGuards?: RouteHandlerMethod$1[];
+  readonly disableDefaultRoutes: boolean;
+  readonly disabledRoutes: CrudRouteKey[];
+  readonly actions?: ActionsMap;
+  readonly actionPermissions?: PermissionCheck;
+  readonly events: Record<string, EventDefinition>;
+  readonly rateLimit?: RateLimitConfig | false;
+  readonly audit?: boolean | {
+    operations?: ("create" | "update" | "delete")[];
+  };
+  readonly updateMethod?: "PUT" | "PATCH" | "both";
+  readonly pipe?: PipelineConfig;
+  readonly fields?: FieldPermissionMap;
+  readonly cache?: ResourceCacheConfig;
+  readonly skipGlobalPrefix: boolean;
+  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(): _$_classytic_repo_core_repository0.StandardRepo<TDoc> | RepositoryLike<TDoc> | undefined;
+  _validateControllerMethods(): void;
+  toPlugin(): FastifyPluginAsync;
   /**
-   * 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.
+   * Get event definitions for registry
    */
-  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  getEvents(): Array<{
+    name: string;
+    module: string;
+    schema?: AnyRecord;
+    description?: string;
+  }>;
+  /**
+   * Get resource metadata
+   */
+  getMetadata(): ResourceMetadata;
 }
-/** Minimal repository interface for access-controlled fetch operations */
-interface AccessControlRepository {
-  getById(id: string, options?: QueryOptions): Promise<unknown>;
-  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
+//#endregion
+//#region src/registry/ResourceRegistry.d.ts
+interface RegisterOptions {
+  module?: string;
+  /** Pre-generated OpenAPI schemas */
+  openApiSchemas?: OpenApiSchemas;
 }
-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);
+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;
   /**
-   * Build filter for single-item operations (get/update/delete)
-   * Combines ID filter with policy/org filters for proper security enforcement
+   * Get full introspection data
    */
-  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
+  getIntrospection(): IntrospectionData;
   /**
-   * 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.
+   * Freeze registry (prevent further registrations)
    */
-  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
+  freeze(): void;
   /**
-   * 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.
+   * Check if frozen
    */
-  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
-  /** Check ownership for update/delete (ownedByUser preset) */
-  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
+  isFrozen(): 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)
+   * Unfreeze registry (allow new registrations)
    */
-  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
+  unfreeze(): void;
   /**
-   * Same as `fetchWithAccessControl` but returns a structured result with
-   * a denial reason so callers can distinguish "doc doesn't exist" from
-   * "doc exists but was filtered by policy/org scope" from "repo threw".
-   *
-   * Codes:
-   * - `null`               — doc was found, no denial
-   * - `'NOT_FOUND'`        — doc genuinely doesn't exist in the DB
-   * - `'POLICY_FILTERED'`  — doc exists but the request's policy filters exclude it
-   * - `'ORG_SCOPE_DENIED'` — doc exists but the caller's org context doesn't match
-   * - `'REPO_ERROR'`       — the repository threw a "not found" error (mongokit style)
+   * Reset registry — clear all resources and unfreeze
    */
-  fetchDetailed<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<FetchResult<TDoc>>;
+  reset(): void;
+  /** @internal Alias for unfreeze() */
+  _unfreeze(): void;
+  /** @internal Alias for reset() */
+  _clear(): void;
   /**
-   * 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.
+   * Group by key
    */
-  validateItemAccess(item: AnyRecord | null, req: IRequestContext): boolean;
-  /** Extract typed Arc internal metadata from request */
-  private _meta;
+  private _groupBy;
+}
+//#endregion
+//#region src/types/fastify.d.ts
+interface FastifyRequestExtras {
+  user?: Record<string, unknown>;
+}
+interface RequestWithExtras extends FastifyRequest {
   /**
-   * Check if a value matches a MongoDB query operator
+   * Arc metadata — set by createCrudRouter. Contains resource configuration
+   * and schema options.
    */
-  private matchesOperator;
+  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 — added by `arcCorePlugin`. Provides instance-scoped
+ * hooks and resource registry.
+ */
+interface ArcDecorator {
+  hooks: HookSystem;
+  registry: ResourceRegistry;
+  /** Whether event emission is enabled */
+  emitEvents: boolean;
+}
+/** Events decorator — added by `eventPlugin`. Provides event pub/sub. */
+interface EventsDecorator {
+  publish: <T>(type: string, payload: T, meta?: Partial<{
+    id: string;
+    timestamp: Date;
+  }>) => Promise<void>;
   /**
-   * Check if item matches a single filter condition
-   * Supports nested paths (e.g., "owner.id", "metadata.status")
+   * Subscribe to an event pattern. Handler receives the full
+   * `DomainEvent<T> = { type, payload, meta }` envelope — destructure
+   * `payload` if you only need the body, or read `meta.correlationId` /
+   * `meta.timestamp` for tracing. See CHANGELOG 2.10 for the migration
+   * note from 2.9.x's loose `unknown` type.
    */
-  private matchesFilter;
+  subscribe: <T = unknown>(pattern: string, handler: (event: DomainEvent<T>) => void | Promise<void>) => Promise<() => void>;
+  transportName: string;
+}
+/**
+ * Fastify instance with Arc decorators. Arc adds these via plugins/presets.
+ */
+type FastifyWithDecorators = FastifyInstance & {
+  arc?: ArcDecorator;
+  events?: EventsDecorator;
+  authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>; /** Organization-scoped filtering — from `multiTenant` preset */
+  organizationScoped?: (options?: {
+    required?: boolean;
+  }) => RouteHandlerMethod;
+  [key: string]: unknown;
+};
+/** Handler signature for middleware functions. */
+type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
+//#endregion
+//#region src/types/plugins.d.ts
+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;
+}
+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;
+  /** Custom routes (from presets or user-defined) */
+  routes?: readonly RouteDefinition[];
+  /** 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";
   /**
-   * Built-in MongoDB-style policy filter matching.
-   * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+   * Per-resource rate limiting. Requires `@fastify/rate-limit` to be
+   * registered. Set to `false` to disable for this resource.
    */
-  private defaultMatchesPolicyFilters;
+  rateLimit?: RateLimitConfig | false;
+  /** PreHandler guards applied to every route (CRUD + custom + preset). */
+  routeGuards?: RouteHandlerMethod[];
+}
+//#endregion
+//#region src/types/query.d.ts
+/**
+ * Request-shaped context object passed to controller methods. Apps and
+ * adapters extend it freely via the index signature.
+ */
+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, populate/lookup, 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>;
   /**
-   * Get nested value from object using dot notation (e.g., "owner.id")
-   * Security: Validates path against forbidden patterns to prevent prototype pollution
+   * Advanced populate options (Mongoose-compatible). When set, takes
+   * precedence over simple `populate`.
    */
-  private getNestedValue;
+  populateOptions?: PopulateOption[];
   /**
-   * Create a safe RegExp from a string, guarding against ReDoS.
-   * Returns null if the pattern is invalid or dangerous.
+   * Lookup/join options (database-agnostic). MongoKit maps these to
+   * `$lookup`; future SQL adapters would map to JOINs.
+   *
+   * @example
+   * URL: ?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug
    */
-  private static safeRegex;
+  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>;
+  [key: string]: unknown;
+}
+/**
+ * Database-agnostic lookup/join option. Parsed from URL:
+ * `?lookup[alias][from]=...&lookup[alias][localField]=...&lookup[alias][foreignField]=...`
+ */
+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 */
+  select?: string | Record<string, 0 | 1>;
 }
-//#endregion
-//#region src/core/BodySanitizer.d.ts
 /**
- * Policy for handling fields the caller lacks write permission for.
+ * Mongoose-compatible populate option for advanced field selection.
  *
- * - `'reject'` (default, secure): throw 403 listing the denied fields so
- *   misconfigurations and attacks surface instead of silently disappearing.
- * - `'strip'` (legacy): silently drop the field and continue. Preserved for
- *   apps that relied on the pre-2.9 behaviour — new code should not use it.
+ * @example
+ * ```typescript
+ * // URL: ?populate[author][select]=name,email
+ * // Generates: { path: 'author', select: 'name email' }
+ * ```
  */
-type FieldWriteDenialPolicy = "reject" | "strip";
-interface BodySanitizerConfig {
-  /** Schema options for field sanitization */
-  schemaOptions: RouteSchemaOptions;
-  /**
-   * What to do when a request contains fields the caller can't write.
-   * Default: `'reject'` — surface the misconfiguration as a 403.
-   */
-  onFieldWriteDenied?: FieldWriteDenialPolicy;
-}
-declare class BodySanitizer {
-  private schemaOptions;
-  private onFieldWriteDenied;
-  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;
+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;
 }
-//#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;
+/**
+ * Parsed query result from QueryParser. The index signature lets custom
+ * parsers (MongoKit, PrismaKit) add fields without breaking Arc's types.
+ */
+interface ParsedQuery {
+  filters?: Record<string, unknown>;
+  limit?: number;
+  sort?: string | Record<string, 1 | -1>;
+  populate?: string | string[] | Record<string, unknown>;
+  populateOptions?: PopulateOption[];
+  lookups?: LookupOption[];
+  search?: string;
+  page?: number;
+  after?: string;
+  select?: string | string[] | Record<string, 0 | 1>;
+  [key: string]: unknown;
 }
-declare class QueryResolver {
-  private queryParser;
-  private maxLimit;
-  private defaultLimit;
-  private defaultSort;
-  private schemaOptions;
-  private tenantField;
-  constructor(config?: QueryResolverConfig);
+/**
+ * Query Parser interface. Implement to create custom query parsers.
+ *
+ * @example MongoKit
+ * ```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. */
+  getQuerySchema?(): {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
   /**
-   * Resolve a request into parsed query options -- ONE parse per request.
-   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
+   * Optional: Allowed filter fields whitelist. MCP auto-derives
+   * `filterableFields` from this if `schemaOptions.filterableFields`
+   * is not explicitly configured.
    */
-  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
+  allowedFilterFields?: readonly string[];
   /**
-   * 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.
+   * Optional: Allowed filter operators whitelist. Used by MCP to enrich
+   * list-tool descriptions. Values are human-readable keys: 'eq', 'ne',
+   * 'gt', 'gte', 'lt', 'lte', 'in', 'nin', etc.
    */
-  private sanitizeSelectAny;
-  /** Sanitize populate fields */
-  private sanitizePopulate;
-  /** Sanitize advanced populate options against allowedPopulate */
-  private sanitizePopulateOptions;
+  allowedOperators?: readonly string[];
   /**
-   * Sanitize lookup/join options.
-   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
-   * Validates lookup structure to prevent injection.
+   * Optional: Allowed sort fields whitelist. Used by MCP to describe
+   * available sort options in list-tool descriptions.
    */
-  private sanitizeLookups;
-  /** Get blocked fields from schema options */
-  private getBlockedFields;
+  allowedSortFields?: readonly string[];
+}
+/** Ownership-check config used by `ownedByUser` preset / middleware. */
+interface OwnershipCheck {
+  field: string;
+  userField?: string;
+}
+/** Service-layer context — passed to repository / service calls. */
+interface ServiceContext {
+  user?: unknown;
+  requestId?: string;
+  /** Field projection for responses */
+  select?: string[] | Record<string, 0 | 1>;
+  /** Relations to populate */
+  populate?: string | string[];
+  /** Return plain objects */
+  lean?: boolean;
 }
 //#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').
-   *
-   * If not set, the controller auto-derives it from the repository's own
-   * `idField` property (e.g. MongoKit's `Repository({ idField: 'id' })`),
-   * so you only need to configure it in one place.
-   *
-   * Set explicitly to override the repo's setting (e.g. `'_id'` to opt out
-   * of native pass-through and force the slug-translation path).
-   *
-   * 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;
+//#region src/types/registry.d.ts
+interface ResourceMetadata {
+  name: string;
+  displayName?: string;
+  tag?: string;
+  prefix: string;
+  module?: string;
+  permissions?: ResourcePermissions;
+  presets: string[];
+  customRoutes?: Array<{
+    method: string;
+    path: string;
+    handler: string;
+    operation?: string;
+    summary?: string;
+    description?: string;
+    permissions?: PermissionCheck;
+    raw?: boolean;
+    schema?: Record<string, unknown>;
+  }>;
+  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;
+  /** Per-resource audit opt-in flag (read by `auditPlugin` perResource mode) */
+  audit?: boolean | {
+    operations?: ("create" | "update" | "delete")[];
   };
   /**
-   * Policy for requests that include fields the caller can't write.
-   *
-   * - `'reject'` (default): 403 with the denied field names. Surfaces
-   *   misconfigurations and attempts to set protected fields instead of
-   *   silently dropping them.
-   * - `'strip'`: legacy silent-drop behaviour. Only opt in when migrating
-   *   code that relied on the pre-2.9 permissive default.
+   * v2.8 declarative actions metadata — populated from
+   * `ResourceConfig.actions`. Consumed by OpenAPI generation (renders
+   * `POST /:id/action` with a discriminated body schema) and MCP tool
+   * generation. Added in 2.8.1.
    */
-  onFieldWriteDenied?: FieldWriteDenialPolicy;
+  actions?: Array<{
+    readonly name: string;
+    readonly description?: string; /** Raw per-action schema (JSON Schema, Zod v4, or legacy field map) */
+    readonly schema?: Record<string, unknown>; /** Per-action permission check (if different from resource-level `actionPermissions`) */
+    readonly permissions?: PermissionCheck; /** MCP tool generation flag — `false` to skip, object for overrides */
+    readonly mcp?: boolean | {
+      readonly description?: string;
+      readonly annotations?: Record<string, unknown>;
+    };
+  }>;
+  /**
+   * Resource-level fallback permission for actions without per-action
+   * permissions. Used by OpenAPI to determine auth requirements and by
+   * MCP as the fallback in `createActionToolHandler`. Added in 2.8.1.
+   */
+  actionPermissions?: PermissionCheck;
+}
+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;
+}
+//#endregion
+//#region src/types/repository.d.ts
 /**
- * Framework-agnostic base controller implementing IController.
+ * Discriminated union of pagination result shapes. Narrow on `method`.
  *
- * Composes AccessControl, BodySanitizer, and QueryResolver for clean
- * separation of concerns. CRUD methods delegate directly to these
- * composed classes — no intermediate wrapper methods.
+ * repo-core ships the individual shapes (`OffsetPaginationResult` /
+ * `KeysetPaginationResult`) but no combined union — arc needs one for the
+ * BaseController's `list` / `getDeleted` return signatures, where either
+ * shape is valid depending on the caller's pagination params.
  *
- * @template TDoc - The document type
- * @template TRepository - The repository type (defaults to RepositoryLike)
+ * @example
+ * ```ts
+ * const result = await repo.getAll(params);
+ * if (result.method === 'keyset') {
+ *   result.next;     // keyset cursor
+ * } else {
+ *   result.page;     // offset number
+ * }
+ * ```
  */
-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 the repository primary key for mutation calls (update/delete/restore).
-   *
-   * When the resource declares a custom `idField` (e.g. `slug`, `jobId`, UUID),
-   * the default behavior is to translate the route id → the fetched doc's `_id`
-   * because most Mongo repositories key their mutation methods off `_id`.
-   *
-   * Exception: if the repository itself exposes a matching `idField` property
-   * (e.g. MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
-   * repository already knows how to look up by that field — so we pass the
-   * route id through unchanged and skip the translation.
-   *
-   * This makes `defineResource({ idField: 'id' })` work end-to-end with repos
-   * that natively support custom primary keys, without breaking the slug-style
-   * aliasing that Arc 2.6.3 introduced for repos keyed on `_id`.
-   */
-  private resolveRepoId;
-  /**
-   * Centralized 404 response builder. Maps the denial reason from
-   * `fetchDetailed()` into a structured `details.code` so consumers can
-   * programmatically distinguish "doc doesn't exist" from "doc filtered
-   * by policy/org scope" without parsing error strings.
-   *
-   * Error messages are intentionally vague in the `error` field (don't
-   * leak whether the doc exists) — the detail is in `details.code` only.
-   */
-  private notFoundResponse;
-  /** 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<OffsetPaginationResult<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<PaginationResult<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[]>>;
-  /**
-   * Build a tenant-scoped filter for bulk update/delete.
-   *
-   * Mirrors `AccessControl.buildIdFilter` semantics for single-doc ops:
-   *   - Always merge `_policyFilters` (from permission middleware)
-   *   - When `tenantField` is set AND a `member` scope is present, add the
-   *     org filter so cross-tenant data can't be touched.
-   *   - When the scope is `elevated` (platform admin), no org filter is
-   *     applied — admins can bulk-update across orgs intentionally.
-   *   - When the scope is `public` on a tenant-scoped resource, deny.
-   *   - When NO scope is present at all (e.g., direct controller calls in
-   *     unit tests, or app routes without auth middleware), the controller
-   *     stays lenient — it's the middleware layer's job to fail-close.
-   *     Apps that want fail-close on bulk routes should run the multi-tenant
-   *     preset middleware (or equivalent) ahead of these handlers.
-   *
-   * Returns the merged filter, or `null` when access must be denied.
-   */
-  private buildBulkFilter;
-  /**
-   * Sanitize a bulk update data payload through the same write-permission
-   * pipeline as single-doc update(). Handles both shapes:
-   *
-   *   - Flat:           `{ name: 'x', status: 'y' }`
-   *   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 }, $unset: { tag: '' } }`
-   *
-   * For each operand, runs `bodySanitizer.sanitize('update', ...)` so that
-   * system fields, systemManaged/readonly/immutable rules, AND field-level
-   * write permissions are enforced. Without this, a tenant-scoped user could
-   * pass `{ $set: { organizationId: 'org-b' } }` to move records across orgs.
-   *
-   * Returns the sanitized payload along with the list of stripped fields for
-   * audit/error reporting.
-   */
-  private sanitizeBulkUpdateData;
-  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
-    matchedCount: number;
-    modifiedCount: number;
-  }>>;
-  /**
-   * Bulk delete by `filter` or `ids`.
-   *
-   * Body shape (one of):
-   *   - `{ filter: { status: 'archived' } }`     — delete by query filter
-   *   - `{ ids: ['id1', 'id2', 'id3'] }`         — delete specific docs by id
-   *
-   * The `ids` form translates to `{ [idField]: { $in: ids } }` using the
-   * resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
-   * UUID, etc.). Tenant scope and policy filters are merged in either way,
-   * so cross-tenant deletes are blocked at the controller layer.
-   *
-   * Both forms perform a single `repo.deleteMany()` DB call — no per-doc
-   * fetch loop. Per-doc lifecycle hooks (`before:delete`/`after:delete`) do
-   * NOT fire for bulk operations; use the single-doc `delete()` if you need
-   * them, or subscribe to the bulk lifecycle event from the events plugin.
-   */
-  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
-    deletedCount: number;
-  }>>;
+type PaginationResult<TDoc, TExtra extends Record<string, unknown> = Record<string, never>> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra>;
+//#endregion
+//#region src/types/utility.d.ts
+/**
+ * Infer document type from a `DataAdapter` or `ResourceConfig`. Smart
+ * inference that works with multiple sources.
+ *
+ * @example
+ * ```typescript
+ * type Doc1 = InferDocType<typeof adapter>;     // From DataAdapter
+ * type Doc2 = InferDocType<typeof resource>;    // From 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>;
+ * ```
+ */
+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> = StandardRepo<TDoc>;
+//#endregion
+//#region src/types/validation.d.ts
+/**
+ * Validation result types — produced by `validateResourceConfig` and
+ * consumed by `assertValidConfig` / `formatValidationErrors`.
+ */
+interface ConfigError {
+  field: string;
+  message: string;
+  code?: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors: ConfigError[];
+}
+interface ValidateOptions {
+  strict?: boolean;
 }
 //#endregion
-export { CrudSchemas as $, HookPhase as $t, AuthHelpers as A, SchemaMetadata as At, FastifyWithDecorators as B, ArcInternalMetadata as Bt, ResourceMetadata as C, RouteHandler as Ct, HealthOptions as D, FieldMetadata as Dt, HealthCheck as E, DataAdapter as Et, TokenPair as F, OperationFilter as Ft, ResourceDefinition as G, PopulateOption as Gt, RequestWithExtras as H, LookupOption as Ht, ArcDecorator as I, PipelineConfig as It, ActionEntry as J, ServiceContext as Jt, defineResource as K, QueryParserInterface as Kt, EventsDecorator as L, PipelineContext as Lt, Authenticator as M, Guard as Mt, AuthenticatorContext as N, Interceptor as Nt, IntrospectionPluginOptions as O, RelationMetadata as Ot, JwtContext as P, NextFunction as Pt, CrudRouteKey as Q, HookOperation as Qt, FastifyRequestExtras as R, PipelineStep as Rt, RegistryStats as S, IRequestContext as St, GracefulShutdownOptions as T, AdapterSchemaContext as Tt, RegisterOptions as U, OwnershipCheck as Ut, MiddlewareHandler as V, ControllerQueryOptions as Vt, ResourceRegistry as W, ParsedQuery as Wt, ActionsMap as X, HookContext as Xt, ActionHandlerFn as Y, DefineHookOptions as Yt, CrudController as Z, HookHandler as Zt, ConfigError as _, UserOrganization as _n, ControllerHandler as _t, QueryResolverConfig as a, afterUpdate as an, PresetHook as at, IntrospectionData as b, IController as bt, AccessControl as c, beforeUpdate as cn, ResourceCacheConfig as ct, InferAdapterDoc as d, AnyRecord as dn, ResourceHooks as dt, HookRegistration as en, EventDefinition as et, InferDocType as f, ApiResponse as fn, ResourcePermissions as ft, TypedResourceConfig as g, UserLike as gn, RouteSchemaOptions as gt, TypedRepository as h, ObjectId as hn, RouteMethod as ht, QueryResolver as i, afterDelete as in, PresetFunction as it, AuthPluginOptions as j, ValidationResult$1 as jt, RequestIdOptions as k, RepositoryLike as kt, AccessControlConfig as l, createHookSystem as ln, ResourceConfig as lt, TypedController as m, JWTPayload as mn, RouteMcpConfig as mt, BaseController as n, HookSystemOptions as nn, MiddlewareConfig as nt, BodySanitizer as o, beforeCreate as on, PresetResult as ot, InferResourceDoc as p, ArcRequest as pn, RouteDefinition as pt, ActionDefinition as q, RequestContext as qt, BaseControllerOptions as r, afterCreate as rn, OpenApiSchemas as rt, BodySanitizerConfig as s, beforeDelete as sn, RateLimitConfig as st, RouteHandlerMethod$1 as t, HookSystem as tn, FieldRule as tt, PaginationResult as u, defineHook as un, ResourceHookContext as ut, ValidateOptions as v, envelope as vn, ControllerLike as vt, CrudRouterOptions as w, AdapterFactory as wt, RegistryEntry as x, IControllerResponse as xt, ValidationResult as y, getUserId as yn, FastifyHandler as yt, FastifyWithAuth as z, Transform as zt };
+export { beforeCreate as $, ObjectId as $t, RequestIdOptions as A, FastifyHandler as At, ResourceDefinition as B, PipelineContext as Bt, RequestContext as C, ResourcePermissions as Ct, HealthCheck as D, RouteSchemaOptions as Dt, GracefulShutdownOptions as E, RouteMethod as Et, FastifyWithDecorators as F, Guard as Ft, HookOperation as G, Authenticator as Gt, DefineHookOptions as H, Transform as Ht, MiddlewareHandler as I, Interceptor as It, HookSystem as J, TokenPair as Jt, HookPhase as K, AuthenticatorContext as Kt, RequestWithExtras as L, NextFunction as Lt, EventsDecorator as M, IControllerResponse as Mt, FastifyRequestExtras as N, IRequestContext as Nt, HealthOptions as O, ControllerHandler as Ot, FastifyWithAuth as P, RouteHandler as Pt, afterUpdate as Q, JWTPayload as Qt, RegisterOptions as R, OperationFilter as Rt, QueryParserInterface as S, ResourceHooks as St, CrudRouterOptions as T, RouteMcpConfig as Tt, HookContext as U, AuthHelpers as Ut, defineResource as V, PipelineStep as Vt, HookHandler as W, AuthPluginOptions as Wt, afterCreate as X, ApiResponse as Xt, HookSystemOptions as Y, AnyRecord as Yt, afterDelete as Z, ArcRequest as Zt, ControllerQueryOptions as _, RepositoryLike as _n, PresetResult as _t, InferAdapterDoc as a, BaseControllerOptions as an, ActionEntry as at, ParsedQuery as b, ResourceConfig as bt, TypedController as c, BodySanitizer as cn, CrudController as ct, PaginationResult as d, AccessControlConfig as dn, EventDefinition as dt, UserLike as en, beforeDelete as et, IntrospectionData as f, AdapterFactory as fn, FieldRule as ft, ArcInternalMetadata as g, RelationMetadata as gn, PresetHook as gt, ResourceMetadata as h, FieldMetadata as hn, PresetFunction as ht, ValidationResult as i, BaseController as in, ActionDefinition as it, ArcDecorator as j, IController as jt, IntrospectionPluginOptions as k, ControllerLike as kt, TypedRepository as l, BodySanitizerConfig as ln, CrudRouteKey as lt, RegistryStats as m, DataAdapter as mn, OpenApiSchemas as mt, ConfigError as n, envelope as nn, createHookSystem as nt, InferDocType as o, QueryResolver as on, ActionHandlerFn as ot, RegistryEntry as p, AdapterSchemaContext as pn, MiddlewareConfig as pt, HookRegistration as q, JwtContext as qt, ValidateOptions as r, getUserId as rn, defineHook as rt, InferResourceDoc as s, QueryResolverConfig as sn, ActionsMap as st, RouteHandlerMethod$1 as t, UserOrganization as tn, beforeUpdate as tt, TypedResourceConfig as u, AccessControl as un, CrudSchemas as ut, LookupOption as v, SchemaMetadata as vn, RateLimitConfig as vt, ServiceContext as w, RouteDefinition as wt, PopulateOption as x, ResourceHookContext as xt, OwnershipCheck as y, ValidationResult$1 as yn, ResourceCacheConfig as yt, ResourceRegistry as z, PipelineConfig as zt };