@classytic/arc 2.8.5 → 2.10.3

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

@@ -1,8 +1,112 @@
 import { r as RequestScope } from "./types-BD85MlEK.mjs";
-import { n as FieldPermissionMap } from "./fields-DpZQa_Q3.mjs";
-import { i as UserBase, t as PermissionCheck } from "./types-DZi1aYhm.mjs";
+import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-Lo1VUDpt.mjs";
+import { n as DomainEvent } from "./EventTransport-CUw5NNWe.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;
+};
+/**
+ * Wrap data in Arc's standard `{ success: true, data }` envelope.
+ *
+ * @example
+ * ```typescript
+ * handler: async (req, reply) => {
+ *   const data = await getResults();
+ *   return envelope(data);  // → { success: true, data }
+ * }
+ * ```
+ */
+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";
@@ -254,6 +358,183 @@ declare function beforeDelete<T = AnyRecord>(hooks: HookSystem, resource: string
  */
 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>;
+  /**
+   * Advanced populate options (Mongoose-compatible). When set, takes
+   * precedence over simple `populate`.
+   */
+  populateOptions?: PopulateOption[];
+  /**
+   * 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
+   */
+  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[];
+  };
+  /**
+   * Optional: Allowed filter fields whitelist. MCP auto-derives
+   * `filterableFields` from this if `schemaOptions.filterableFields`
+   * is not explicitly configured.
+   */
+  allowedFilterFields?: readonly string[];
+  /**
+   * Optional: Allowed filter operators whitelist. Used by MCP to enrich
+   * list-tool descriptions. Values are human-readable keys: 'eq', 'ne',
+   * 'gt', 'gte', 'lt', 'lte', 'in', 'nin', etc.
+   */
+  allowedOperators?: readonly string[];
+  /**
+   * Optional: Allowed sort fields whitelist. Used by MCP to describe
+   * available sort options in list-tool descriptions.
+   */
+  allowedSortFields?: readonly string[];
+}
+/** 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/pipeline/types.d.ts
 /**
  * Pipeline context passed to guards, transforms, and interceptors.
@@ -316,1701 +597,735 @@ type PipelineConfig = PipelineStep[] | {
   [operation: string]: PipelineStep[] | undefined;
 };
 //#endregion
-//#region src/types/repository.d.ts
+//#region src/adapters/interface.d.ts
 /**
- * Repository Interface — Database-Agnostic CRUD Contract
- *
- * This is the canonical contract every arc-compatible repository follows.
- * It is intentionally structural: any object matching the shape works,
- * including the reference implementation at `@classytic/mongokit` and any
- * future `prismakit` / `pgkit` / `sqlitekit` that mirrors it.
- *
- * ## Design
- *
- * The interface is tiered so a minimal adapter can ship with five methods
- * while a mature one (mongokit 3.6+) can opt into the full surface without
- * type assertions:
- *
- * 1. **Required** — `getAll`, `getById`, `create`, `update`, `delete`.
- *    Every resource needs these; arc's BaseController assumes they exist.
- *
- * 2. **Recommended** — `getOne` / `getByQuery`. Used by AccessControl to
- *    enforce compound filters (idField + org scope + policy). Without them,
- *    arc falls back to `getById` + post-fetch checks, which is slower and
- *    produces wrong 404s on custom idFields.
- *
- * 3. **Optional capabilities** — batch ops, soft delete, aggregation,
- *    transactions, etc. Declared as optional so kits implement only what
- *    their underlying DB supports. arc feature-detects at runtime.
- *
- * All options/results are named types so custom kits can import and
- * implement them directly:
- *
- * ```ts
- * import type {
- *   CrudRepository,
- *   DeleteOptions,
- *   DeleteResult,
- *   PaginationResult,
- *   UpdateManyResult,
- *   BulkWriteOperation,
- *   BulkWriteResult,
- * } from '@classytic/arc';
- *
- * class PgRepository<TDoc> implements CrudRepository<TDoc> { … }
- * ```
+ * 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 Reference implementation
  * ```ts
- * import type { CrudRepository } from '@classytic/arc';
- * const userRepo: CrudRepository<UserDocument> = new Repository(UserModel);
+ * const adapter: DataAdapter<Product> = {
+ *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
+ *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
+ *   name: 'products',
+ * };
+ * defineResource({ adapter, ... });
  * ```
- *
- * ## Contract gotchas (learned from mongokit 3.6 integration)
- *
- * If you build a custom kit that implements this contract, these are the
- * behaviors arc's tests specifically verify. Align your kit here and
- * arc's `BaseController` + presets will work out of the box:
- *
- * 1. **`getById` / `getOne` miss semantics** — MAY return `null` or throw a
- *    404-style error whose message contains "not found". Arc handles both.
- *    Pick one and document it in your kit.
- *
- * 2. **`deleteMany` with soft-delete** — if your kit intercepts
- *    `deleteMany` and rewrites it to `updateMany`, the returned
- *    `deletedCount` may be `0` even when N docs were soft-deleted. The
- *    authoritative count comes from a follow-up query. Consumers shouldn't
- *    rely on `deletedCount` reflecting soft-delete work unless your kit
- *    promises it.
- *
- * 3. **Lifecycle hooks are shared with plugins** — never use
- *    `removeAllListeners(event)` to clean up test hooks. That silently
- *    removes soft-delete, cascade, multi-tenant, and audit plugin
- *    listeners too, which then makes subsequent operations misbehave
- *    (e.g. a soft-delete becomes a hard delete). Always use
- *    `.off(event, fn)` with the specific handler reference you registered.
- *
- * 4. **Hard-delete mode** — `delete(id, { mode: 'hard' })` and
- *    `deleteMany(q, { mode: 'hard' })` MUST bypass soft-delete
- *    interception while still running policy / multi-tenant / cascade /
- *    audit hooks. Kits without soft-delete should accept and ignore the
- *    flag.
- *
- * 5. **Keyset pagination auto-detection** — `getAll({ sort, limit })`
- *    without `page` SHOULD return a `KeysetPaginatedResult` with
- *    `method: "keyset"`. Kits that only offer offset pagination can return
- *    the legacy offset shape; arc's types still satisfy.
- *
- * 6. **`idField` identity** — kits that key on anything other than `"_id"`
- *    MUST set `readonly idField` on the repository so arc's BaseController
- *    passes route params straight through to `update`/`delete`/`restore`
- *    without translating them.
- *
- * 7. **`before:restore` / `after:restore` hooks** — if you implement
- *    `restore`, fire these hooks symmetrically with `before:delete` /
- *    `after:delete` so hosts can wire cascade-restore flows.
- *
- * See `tests/core/repository-contract-mongokit.test.ts` for a runnable
- * reference against mongokit 3.6. Copy it, swap in your kit's repository,
- * and make it pass — if everything's green, arc will work against your
- * kit.
- */
-/**
- * Opaque transaction session. Adapters bind this to their own type
- * (Mongoose `ClientSession`, Prisma transaction client, `pg.Client`, …).
  */
-type RepositorySession = unknown;
-/**
- * Query options for read operations. Extended ad-hoc by adapters via the
- * index signature — kit authors should namespace custom flags (e.g.
- * `__pgHint`) to avoid collisions.
- */
-interface QueryOptions {
-  /** Transaction session — adapter-specific concrete type */
-  session?: RepositorySession;
-  /** Return plain objects instead of driver documents */
-  lean?: boolean;
-  /** Include soft-deleted docs in reads (honored by soft-delete plugin) */
-  includeDeleted?: boolean;
-  /** Forwarded to policy/tenant hooks */
-  user?: Record<string, unknown>;
-  /** Arc request-scoped metadata (orgId, roles, requestId, …) */
-  context?: Record<string, unknown>;
+type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
+interface DataAdapter<TDoc = unknown> {
   /**
-   * Adapter-specific escape hatch — `select`, `populate`, `populateOptions`,
-   * `readPreference`, `maxTimeMS`, and every kit's driver-specific flags
-   * flow through here. Arc intentionally does NOT type these concretely
-   * because each kit's DB shapes them differently: mongoose uses
-   * `PopulateOptions[]`, prisma uses `{ include: {...} }`, pgkit uses SQL
-   * JOIN hints, etc. Typing them as (say) `string | Record<string, unknown>`
-   * would REJECT the narrower shapes real kits actually expose, breaking
-   * structural assignability of `Repository<T> → CrudRepository<T>`.
+   * 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.
    */
-  [key: string]: unknown;
-}
-/**
- * Options for write operations (create/update). Superset of QueryOptions
- * so callers can pass a single options object.
- */
-interface WriteOptions extends QueryOptions {
-  /** Upsert on update/replace operations */
-  upsert?: boolean;
-}
-/**
- * Options for delete operations.
- *
- * `mode: 'hard'` opts out of the soft-delete interception when the adapter
- * has a soft-delete plugin wired. Policy, cascade, audit, and cache hooks
- * still fire — only the soft-delete rewrite is bypassed. Use for GDPR
- * erasure or admin purge paths.
- */
-interface DeleteOptions extends QueryOptions {
+  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>;
   /**
-   * Force physical deletion even when soft-delete is active, or force soft
-   * when the default would be hard. Adapters without soft-delete support
-   * MUST ignore this flag (it is a hint, not a contract).
+   * 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.
    */
-  mode?: "hard" | "soft";
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close / cleanup resources. */
+  close?(): Promise<void>;
 }
 /**
- * Result of a single delete operation.
- *
- * Matches mongokit's shape. Adapters without soft-delete awareness can omit
- * `soft` and `count`. Arc's BaseController uses the `success` flag to decide
- * whether to return 200 or 404.
+ * 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 DeleteResult {
-  success: boolean;
-  message: string;
-  /** Primary key of the removed doc (string form) */
-  id?: string;
-  /** True when a soft-delete plugin intercepted the operation */
-  soft?: boolean;
-  /** For batch-variant implementations that return the delete count inline */
-  count?: number;
+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;
+    message: string;
+    code?: string;
+  }>;
 }
+type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
+//#endregion
+//#region src/types/handlers.d.ts
 /**
- * Result of a batch delete (`deleteMany`) — distinct from single `delete`
- * because MongoDB's driver returns a different shape for batch operations.
- *
- * **Soft-delete gotcha** — when a soft-delete plugin intercepts
- * `deleteMany` by rewriting it to `updateMany` internally (mongokit 3.6
- * does this in `before:deleteMany`), the `deletedCount` returned here may
- * be `0` because the underlying `Model.deleteMany` was never called. The
- * affected-row count lives inside the hook's `updateMany` result and is
- * not surfaced to the caller. Consumers that need the exact soft-deleted
- * count should run a follow-up query (`repo.count({ deletedAt: { $ne:
- * null }, ...filter })`). 3rd-party kits with soft-delete should document
- * which convention they follow.
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `raw: true`.
  */
-interface DeleteManyResult {
-  /** Driver-reported acknowledgement */
-  acknowledged?: boolean;
-  /**
-   * Number of documents removed. May be 0 when soft-delete intercepts;
-   * see the "Soft-delete gotcha" note above.
-   */
-  deletedCount: number;
-  /** True when a soft-delete plugin intercepted and did `updateMany` instead */
-  soft?: boolean;
-}
-/** Result of a bulk update operation. Matches MongoDB driver shape. */
-interface UpdateManyResult {
-  acknowledged?: boolean;
-  matchedCount: number;
-  modifiedCount: number;
-  upsertedCount?: number;
-  upsertedId?: unknown;
-}
-/** Shape of a single operation passed to `bulkWrite`. */
-type BulkWriteOperation<TDoc = unknown> = {
-  insertOne: {
-    document: Partial<TDoc>;
-  };
-} | {
-  updateOne: {
-    filter: Record<string, unknown>;
-    update: Record<string, unknown>;
-    upsert?: boolean;
-  };
-} | {
-  updateMany: {
-    filter: Record<string, unknown>;
-    update: Record<string, unknown>;
-    upsert?: boolean;
+interface ServerAccessor {
+  /** Event bus — publish domain events from any handler */
+  events?: {
+    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
   };
-} | {
-  deleteOne: {
-    filter: Record<string, unknown>;
+  /** 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>;
   };
-} | {
-  deleteMany: {
-    filter: Record<string, unknown>;
+  /** Logger — structured logging */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
   };
-} | {
-  replaceOne: {
-    filter: Record<string, unknown>;
-    replacement: Partial<TDoc>;
-    upsert?: boolean;
+  /** 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>;
   };
-};
-/** Result of a heterogeneous bulk write. */
-interface BulkWriteResult {
-  ok?: number;
-  insertedCount?: number;
-  matchedCount?: number;
-  modifiedCount?: number;
-  deletedCount?: number;
-  upsertedCount?: number;
-  insertedIds?: Record<number, unknown>;
-  upsertedIds?: Record<number, unknown>;
-}
-/**
- * Pagination parameters for list operations.
- *
- * Supports three modes, auto-detected by the adapter:
- * - **Offset** — pass `page` + `limit`.
- * - **Keyset** — pass `sort` + `limit` (+ optional `after` cursor). Required
- *   for infinite scroll on large collections; O(1) per page.
- * - **Raw** — pass neither; adapter returns all matching docs.
- */
-interface PaginationParams<TDoc = unknown> {
-  /** Filter criteria */
-  filters?: Partial<TDoc> & Record<string, unknown>;
-  /** Sort spec — string (`"-createdAt"`) or object (`{ createdAt: -1 }`) */
-  sort?: string | Record<string, 1 | -1>;
-  /** Page number (1-indexed) — triggers offset pagination */
-  page?: number;
-  /** Items per page */
-  limit?: number;
-  /** Opaque cursor from a prior `next` field — triggers keyset pagination */
-  after?: string;
-  /** Allow additional options (select, populate, search, …) */
-  [key: string]: unknown;
 }
 /**
- * Offset-based paginated result (the default shape when `page` is provided).
+ * Request context passed to controller handlers.
  *
- * `method` is optional so legacy adapters returning the bare `{ docs, page,
- * limit, total, pages, hasNext, hasPrev }` shape still satisfy the type.
- */
-interface OffsetPaginatedResult<TDoc> {
-  /** Discriminator — omitted or `"offset"` */
-  method?: "offset";
-  docs: TDoc[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-}
-/**
- * Keyset-based paginated result (returned when `sort` is provided without
- * `page`). Ideal for infinite scroll — no `count()` query, O(1) per page.
- */
-interface KeysetPaginatedResult<TDoc> {
-  /** Discriminator — always `"keyset"` */
-  method: "keyset";
-  docs: TDoc[];
-  limit: number;
-  hasMore: boolean;
-  /** Opaque cursor token for the next page, or `null` at the end */
-  next: string | null;
-}
-/**
- * Discriminated union of all pagination result shapes.
- * Consumers narrow on the `method` discriminator.
+ * **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
- * ```ts
- * const result = await repo.getAll(params);
- * if (result.method === "keyset") {
- *   // result.next, result.hasMore
- * } else {
- *   // result.page, result.total, result.pages
+ * ```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) };
  * }
- * ```
- */
-type PaginationResult<TDoc> = OffsetPaginatedResult<TDoc> | KeysetPaginatedResult<TDoc>;
-/**
- * Legacy alias. Existing code typed as `PaginatedResult<TDoc>` continues
- * to work unchanged — it resolves to the offset shape, which is the most
- * common. New code should prefer `PaginationResult<TDoc>` for the full
- * discriminated union.
- */
-type PaginatedResult<TDoc> = OffsetPaginatedResult<TDoc>;
-/**
- * Standard CRUD Repository Interface
- *
- * The canonical contract arc consumes. Tiered so minimal adapters only
- * implement the required five methods; richer kits declare the optional
- * capabilities they support.
  *
- * Every optional method is feature-detected at runtime by arc's
- * BaseController and presets — implement only what your DB can express.
+ * // Typed body — req.body is `CreateProductInput`, narrowing not needed
+ * async create(req: IRequestContext<CreateProductInput>) {
+ *   return { success: true, data: await productRepo.create(req.body) };
+ * }
  *
- * @typeParam TDoc - The document/entity type
+ * // 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 CrudRepository<TDoc> {
+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;
   /**
-   * Native primary key field. Defaults to `"_id"` (Mongo convention).
+   * Organization/auth context from middleware.
+   * Contains orgRoles, orgScope, organizationId, and any custom fields
+   * set by the auth adapter or org-scope plugin.
    *
-   * Set to match `defineResource({ idField })` for kits that key on a
-   * custom field (e.g. `"id"`, `"uuid"`, `"slug"`). Arc's BaseController
-   * reads this to decide whether to pass route params straight through
-   * to `update`/`delete`/`restore` or to translate them via a fetched
-   * doc's `_id` first.
+   * @example
+   * ```typescript
+   * async create(req: IRequestContext) {
+   *   const roles = req.context?.orgRoles ?? [];
+   *   if (roles.includes('manager')) { ... }
+   * }
+   * ```
    */
-  readonly idField?: string;
+  context?: RequestContext;
   /**
-   * List documents with pagination. Adapter auto-selects offset vs keyset
-   * mode based on the presence of `page` or `after` in `params`.
-   *
-   * Return shapes (all valid under the contract):
-   * - `OffsetPaginatedResult<TDoc>` — when `page` is given
-   * - `KeysetPaginatedResult<TDoc>` — when `sort` + optional `after` are given
-   * - `TDoc[]` — raw array, when neither `page` nor `sort` drives pagination
-   *
-   * Arc's BaseController narrows the union before returning to clients.
+   * 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.
    */
-  getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginationResult<TDoc> | TDoc[]>;
+  metadata?: TMetadata;
   /**
-   * Fetch a single document by its primary key.
-   *
-   * **Miss semantics — kits may EITHER return `null` OR throw a 404-style
-   * error.** Arc's `BaseController` handles both: `AccessControl.fetchWith­
-   * AccessControl` catches errors whose message contains "not found" and
-   * converts them to null. 3rd-party kit authors: pick one convention and
-   * document it. mongokit 3.6 throws by default; pass
-   * `{ throwOnNotFound: false }` to get null. A SQL kit that returns null
-   * directly is equally valid.
-   */
-  getById(id: string, options?: QueryOptions): Promise<TDoc | null>;
-  /** Insert a single document. */
-  create(data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc>;
-  /** Update a document by primary key. Returns the updated doc or null. */
-  update(id: string, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
-  /**
-   * Delete a document by primary key. Pass `{ mode: 'hard' }` to bypass
-   * soft-delete interception.
-   */
-  delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
-  /**
-   * Find a single doc by a compound filter. Used by arc's AccessControl to
-   * combine `idField + orgId + policy` in one query. Without it, arc falls
-   * back to `getById` + post-fetch scope checks (slower; 404s on custom
-   * idFields if the doc lives outside the user's scope).
+   * Fastify server accessor — publish events, log, and audit
+   * from any handler without switching to `raw: true`.
    *
-   * Miss semantics match `getById` — kits may return null or throw. Arc
-   * handles both. See the note on `getById` above.
-   */
-  getOne?(filter: Record<string, unknown>, options?: QueryOptions): Promise<TDoc | null>;
-  /** Alias many kits expose alongside `getOne`. Arc checks both. */
-  getByQuery?(filter: Record<string, unknown>, options?: QueryOptions): Promise<TDoc | null>;
-  /** Count matching documents. Respects soft-delete when applicable. */
-  count?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<number>;
-  /**
-   * Cheap existence check. Kits may return `boolean` or `{ _id }` — arc
-   * coerces to boolean at the call site.
-   */
-  exists?(filter: Record<string, unknown>, options?: QueryOptions): Promise<boolean | {
-    _id: unknown;
-  } | null>;
-  /** Return the distinct values of a field matching the filter. */
-  distinct?<T = unknown>(field: string, filter?: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
-  /** Return all matching docs as a raw array (no pagination metadata). */
-  findAll?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<TDoc[]>;
-  /**
-   * Atomic "find or create" — return the doc matching the filter, or
-   * insert `data` and return it if none exists. MAY return `null` when
-   * neither path produces a document (e.g. race loss + validation error
-   * handling — mongokit returns null in this window).
-   */
-  getOrCreate?(filter: Record<string, unknown>, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
-  /** Insert multiple documents in one call. */
-  createMany?(items: Array<Partial<TDoc>>, options?: WriteOptions): Promise<TDoc[]>;
-  /**
-   * Update all documents matching `filter`. Should reject empty filters
-   * to prevent accidental mass updates (mongokit does this).
-   */
-  updateMany?(filter: Record<string, unknown>, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
-  /**
-   * Delete all documents matching `filter`. Soft-deletes when a soft-delete
-   * plugin is wired; pass `{ mode: 'hard' }` to force physical removal.
+   * @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 };
+   * }
+   * ```
    */
-  deleteMany?(filter: Record<string, unknown>, options?: DeleteOptions): Promise<DeleteManyResult>;
-  /**
-   * Heterogeneous bulk write (insertOne / updateOne / deleteMany / …).
-   *
-   * Structurally typed as `unknown` because each kit uses its own operation
-   * shape — mongoose uses `AnyBulkWriteOperation[]`, prisma builds these
-   * from its client-extension API, pgkit uses SQL primitives. Arc does
-   * not call `bulkWrite` internally, so the exact shape is kit-specific.
-   * See `BulkWriteOperation<TDoc>` (exported from arc) for a reference
-   * shape you can use when implementing your own kit; mongokit-compatible
-   * callers should import its own operation types.
-   */
-  bulkWrite?: unknown;
-  /** Restore a soft-deleted document. Should fire `before:restore` hooks. */
-  restore?(id: string, options?: QueryOptions): Promise<TDoc | null>;
-  /** Paginated list of soft-deleted documents. */
-  getDeleted?(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginationResult<TDoc> | TDoc[]>;
-  /**
-   * Run an aggregation pipeline.
-   *
-   * Structurally typed as `unknown` because each kit uses a different
-   * stage type (mongoose's `PipelineStage`, prisma's client-extension
-   * builders, pgkit's query-builder primitives, …). Arc does not call
-   * `aggregate` internally — it's a capability consumers use directly on
-   * the repo. Cast or re-declare at the call site using your kit's types.
-   */
-  aggregate?: unknown;
-  /**
-   * Paginated aggregation. Same kit-specificity reasoning as `aggregate`
-   * — structurally `unknown`, type-safe at the call site.
-   */
-  aggregatePaginate?: unknown;
-  /**
-   * Run `callback` inside a transaction. Adapters should auto-retry on
-   * transient transaction errors and expose a `session` the callback can
-   * forward to subsequent repo calls.
-   */
-  withTransaction?<T>(callback: (session: RepositorySession) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
-  /** slugLookup preset — fetch by a business slug. */
-  getBySlug?(slug: string, options?: QueryOptions): Promise<TDoc | null>;
-  /** tree preset — return the full hierarchy. */
-  getTree?(options?: QueryOptions): Promise<TDoc[]>;
-  /** tree preset — return direct children of a node. */
-  getChildren?(parentId: string, options?: QueryOptions): Promise<TDoc[]>;
-  [key: string]: unknown;
+  server?: ServerAccessor;
 }
 /**
- * Extract document type from a repository.
- *
- * @example
- * ```ts
- * type UserDoc = InferDoc<typeof userRepository>;
- * ```
+ * Standard response from controller handlers
  */
-type InferDoc<R> = R extends CrudRepository<infer T> ? T : never;
-//#endregion
-//#region src/core/defineResource.d.ts
+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>;
+}
 /**
- * Define a resource with database adapter
+ * Controller handler — Arc's standard pattern.
  *
- * This is the MAIN entry point for creating Arc resources.
- * The adapter provides both repository and schema metadata.
- */
-declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
-interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
-  _appliedPresets?: string[];
-  _controllerOptions?: {
-    slugField?: string;
-    parentField?: string;
-    [key: string]: unknown;
-  };
-  _pendingHooks?: Array<{
-    operation: "create" | "update" | "delete" | "read" | "list";
-    phase: "before" | "after";
-    handler: (ctx: AnyRecord) => unknown;
-    priority: number;
-  }>;
-}
-declare class ResourceDefinition<TDoc = AnyRecord> {
-  readonly name: string;
-  readonly displayName: string;
-  readonly tag: string;
-  readonly prefix: string;
-  readonly adapter?: DataAdapter<TDoc>;
-  readonly controller?: IController<TDoc>;
-  readonly schemaOptions: RouteSchemaOptions;
-  readonly customSchemas: CrudSchemas;
-  readonly permissions: ResourcePermissions;
-  readonly additionalRoutes: AdditionalRoute[];
-  /**
-   * Original v2.8 `routes` declaration — retained for downstream consumers
-   * (OpenAPI, MCP, registry, CLI introspect). Preserves fields dropped during
-   * normalization to `additionalRoutes` (notably `mcp`, `description`,
-   * `annotations`). Undefined when the resource was defined with the legacy
-   * `additionalRoutes` shape.
-   *
-   * Added in 2.8.1 — the source-of-truth fix for "canonical resource manifest".
-   */
-  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(): RepositoryLike | CrudRepository<TDoc> | undefined;
-  _validateControllerMethods(): void;
-  toPlugin(): FastifyPluginAsync;
-  /**
-   * Get event definitions for registry
-   */
-  getEvents(): Array<{
-    name: string;
-    module: string;
-    schema?: AnyRecord;
-    description?: string;
-  }>;
-  /**
-   * Get resource metadata
-   */
-  getMetadata(): ResourceMetadata;
-}
-//#endregion
-//#region src/registry/ResourceRegistry.d.ts
-interface RegisterOptions {
-  module?: string;
-  /** Pre-generated OpenAPI schemas */
-  openApiSchemas?: OpenApiSchemas;
-}
-declare class ResourceRegistry {
-  private _resources;
-  private _frozen;
-  constructor();
-  /**
-   * Register a resource
-   */
-  register(resource: ResourceDefinition<unknown>, options?: RegisterOptions): this;
-  /**
-   * Get resource by name
-   */
-  get(name: string): RegistryEntry | undefined;
-  /**
-   * Get all resources
-   */
-  getAll(): RegistryEntry[];
-  /**
-   * Get resources by module
-   */
-  getByModule(moduleName: string): RegistryEntry[];
-  /**
-   * Get resources by preset
-   */
-  getByPreset(presetName: string): RegistryEntry[];
-  /**
-   * Check if resource exists
-   */
-  has(name: string): boolean;
-  /**
-   * Get registry statistics
-   */
-  getStats(): RegistryStats;
-  /**
-   * Get full introspection data
-   */
-  getIntrospection(): IntrospectionData;
-  /**
-   * Freeze registry (prevent further registrations)
-   */
-  freeze(): void;
-  /**
-   * Check if frozen
-   */
-  isFrozen(): boolean;
-  /**
-   * Unfreeze registry (allow new registrations)
-   */
-  unfreeze(): void;
-  /**
-   * Reset registry — clear all resources and unfreeze
-   */
-  reset(): void;
-  /** @internal Alias for unfreeze() */
-  _unfreeze(): void;
-  /** @internal Alias for reset() */
-  _clear(): void;
-  /**
-   * Group by key
-   */
-  private _groupBy;
-}
-//#endregion
-//#region src/types/handlers.d.ts
-/**
- * Minimal server accessor — exposes safe, read-only server decorators.
- * Allows controller handlers to publish events, log, and audit
- * without switching to `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;
-  /**
-   * Organization/auth context from middleware.
-   * Contains orgRoles, orgScope, organizationId, and any custom fields
-   * set by the auth adapter or org-scope plugin.
-   *
-   * @example
-   * ```typescript
-   * async create(req: IRequestContext) {
-   *   const roles = req.context?.orgRoles ?? [];
-   *   if (roles.includes('manager')) { ... }
-   * }
-   * ```
-   */
-  context?: RequestContext;
-  /**
-   * Internal metadata (includes context + Arc internals like `_policyFilters`,
-   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
-   * built-in fields, or supply your own interface to layer custom fields.
-   */
-  metadata?: TMetadata;
-  /**
-   * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `raw: true`.
-   *
-   * @example
-   * ```typescript
-   * async reschedule(req: IRequestContext) {
-   *   const result = await repo.reschedule(req.params.id, req.body);
-   *   await req.server?.events?.publish('interview.rescheduled', { data: result });
-   *   return { success: true, data: result };
-   * }
-   * ```
-   */
-  server?: ServerAccessor;
-}
-/**
- * Standard response from controller handlers
- */
-interface IControllerResponse<T = unknown> {
-  /** Operation success status */
-  success: boolean;
-  /** Response data */
-  data?: T;
-  /** Error message (when success is false) */
-  error?: string;
-  /** HTTP status code (default: 200 for success, 400 for error) */
-  status?: number;
-  /** Additional metadata */
-  meta?: Record<string, unknown>;
-  /** Error details (for debugging) */
-  details?: Record<string, unknown>;
-  /** Custom response headers (e.g., X-Total-Count, Link, ETag) */
-  headers?: Record<string, string>;
-}
-/**
- * Controller handler — Arc's standard pattern.
- *
- * Receives a request context object, returns IControllerResponse.
- * Use with `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)
- */
-interface IController<TDoc = unknown> {
-  list(req: IRequestContext): Promise<IControllerResponse<{
-    docs: TDoc[];
-    total: number;
-  }>>;
-  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  delete(req: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-  }>>;
-}
-/**
- * Flexible controller interface - accepts controllers with any handler style
- * Use this when your controller uses Fastify native handlers
- */
-interface ControllerLike {
-  list?: unknown;
-  get?: unknown;
-  create?: unknown;
-  update?: unknown;
-  delete?: unknown;
-  [key: string]: unknown;
-}
-//#endregion
-//#region src/core/AccessControl.d.ts
-interface AccessControlConfig {
-  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable org filtering. */
-  tenantField: string | false;
-  /** Primary key field name (default: '_id') */
-  idField: string;
-  /**
-   * Custom filter matching for policy enforcement.
-   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
-   * Falls back to built-in MongoDB-style matching if not provided.
-   */
-  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
-}
-/** Minimal repository interface for access-controlled fetch operations */
-interface AccessControlRepository {
-  getById(id: string, options?: QueryOptions): Promise<unknown>;
-  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
-}
-declare class AccessControl {
-  private readonly tenantField;
-  private readonly idField;
-  private readonly _adapterMatchesFilter?;
-  /** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
-   *  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
-  private static readonly DANGEROUS_REGEX;
-  /** Forbidden paths that could lead to prototype pollution */
-  private static readonly FORBIDDEN_PATHS;
-  constructor(config: AccessControlConfig);
-  /**
-   * Build filter for single-item operations (get/update/delete)
-   * Combines ID filter with policy/org filters for proper security enforcement
-   */
-  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
-  /**
-   * Check if item matches policy filters (for get/update/delete operations)
-   * Validates that fetched item satisfies all policy constraints
-   *
-   * Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
-   * otherwise falls back to built-in MongoDB-style matching.
-   */
-  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
-  /**
-   * Check org/tenant scope for a document — uses configurable tenantField.
-   *
-   * SECURITY: When org scope is active (orgId present), documents that are
-   * missing the tenant field are DENIED by default. This prevents legacy or
-   * unscoped records from leaking across tenants.
-   */
-  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
-  /** Check ownership for update/delete (ownedByUser preset) */
-  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
-  /**
-   * Fetch a single document with full access control enforcement.
-   * Combines compound DB filter (ID + org + policy) with post-hoc fallback.
-   *
-   * Takes repository as a parameter to avoid coupling.
-   *
-   * Replaces the duplicated pattern in get/update/delete:
-   *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
-   */
-  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
-  /**
-   * Post-fetch access control validation for items fetched by non-ID queries
-   * (e.g., getBySlug, restore). Applies org scope, policy filters, and
-   * ownership checks — the same guarantees as fetchWithAccessControl.
-   */
-  validateItemAccess(item: AnyRecord | null, req: IRequestContext): boolean;
-  /** Extract typed Arc internal metadata from request */
-  private _meta;
-  /**
-   * Check if a value matches a MongoDB query operator
-   */
-  private matchesOperator;
-  /**
-   * Check if item matches a single filter condition
-   * Supports nested paths (e.g., "owner.id", "metadata.status")
-   */
-  private matchesFilter;
-  /**
-   * Built-in MongoDB-style policy filter matching.
-   * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
-   */
-  private defaultMatchesPolicyFilters;
-  /**
-   * Get nested value from object using dot notation (e.g., "owner.id")
-   * Security: Validates path against forbidden patterns to prevent prototype pollution
-   */
-  private getNestedValue;
-  /**
-   * Create a safe RegExp from a string, guarding against ReDoS.
-   * Returns null if the pattern is invalid or dangerous.
-   */
-  private static safeRegex;
-}
-//#endregion
-//#region src/core/BodySanitizer.d.ts
-interface BodySanitizerConfig {
-  /** Schema options for field sanitization */
-  schemaOptions: RouteSchemaOptions;
-}
-declare class BodySanitizer {
-  private schemaOptions;
-  constructor(config: BodySanitizerConfig);
-  /**
-   * Strip readonly and system-managed fields from request body.
-   * Prevents clients from overwriting _id, timestamps, __v, etc.
-   *
-   * Also applies field-level write permissions when the request has
-   * field permission metadata.
-   */
-  sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
-}
-//#endregion
-//#region src/core/QueryResolver.d.ts
-interface QueryResolverConfig {
-  /** Query parser instance (default: Arc built-in parser) */
-  queryParser?: QueryParserInterface;
-  /** Maximum limit for pagination (default: 100) */
-  maxLimit?: number;
-  /** Default limit for pagination (default: 20) */
-  defaultLimit?: number;
-  /** Default sort field (default: '-createdAt') */
-  defaultSort?: string;
-  /** Schema options for field sanitization */
-  schemaOptions?: RouteSchemaOptions;
-  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable. */
-  tenantField?: string | false;
-}
-declare class QueryResolver {
-  private queryParser;
-  private maxLimit;
-  private defaultLimit;
-  private defaultSort;
-  private schemaOptions;
-  private tenantField;
-  constructor(config?: QueryResolverConfig);
-  /**
-   * Resolve a request into parsed query options -- ONE parse per request.
-   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
-   */
-  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
-  /**
-   * Sanitize select — preserves the input format (string, array, or object).
-   * This is critical for db-agnostic support: MongoKit returns object projections,
-   * Mongoose uses space-separated strings, SQL adapters may use arrays.
-   */
-  private sanitizeSelectAny;
-  /** Sanitize populate fields */
-  private sanitizePopulate;
-  /** Sanitize advanced populate options against allowedPopulate */
-  private sanitizePopulateOptions;
-  /**
-   * Sanitize lookup/join options.
-   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
-   * Validates lookup structure to prevent injection.
-   */
-  private sanitizeLookups;
-  /** Get blocked fields from schema options */
-  private getBlockedFields;
-}
-//#endregion
-//#region src/core/BaseController.d.ts
-interface BaseControllerOptions {
-  /** Schema options for field sanitization */
-  schemaOptions?: RouteSchemaOptions;
-  /**
-   * Query parser instance.
-   * Default: Arc built-in query parser (adapter-agnostic).
-   * Swap in MongoKit QueryParser, pgkit parser, etc.
-   */
-  queryParser?: QueryParserInterface;
-  /** Maximum limit for pagination (default: 100) */
-  maxLimit?: number;
-  /** Default limit for pagination (default: 20) */
-  defaultLimit?: number;
-  /** Default sort field (default: '-createdAt') */
-  defaultSort?: string;
-  /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
-  resourceName?: string;
-  /**
-   * Field name used for multi-tenant scoping (default: 'organizationId').
-   * Override to match your schema: 'workspaceId', 'tenantId', 'teamId', etc.
-   * Set to `false` to disable org filtering for platform-universal resources.
-   */
-  tenantField?: string | false;
-  /**
-   * Primary key field name (default: '_id').
-   *
-   * 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;
-  };
-}
-/**
- * Framework-agnostic base controller implementing IController.
- *
- * Composes AccessControl, BodySanitizer, and QueryResolver for clean
- * separation of concerns. CRUD methods delegate directly to these
- * composed classes — no intermediate wrapper methods.
+ * Receives a request context object, returns IControllerResponse.
+ * Use with `raw: false` in routes.
  *
- * @template TDoc - The document type
- * @template TRepository - The repository type (defaults to RepositoryLike)
- */
-declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
-  protected repository: TRepository;
-  protected schemaOptions: RouteSchemaOptions;
-  protected queryParser: QueryParserInterface;
-  protected maxLimit: number;
-  protected defaultLimit: number;
-  protected defaultSort: string;
-  protected resourceName?: string;
-  protected tenantField: string | false;
-  protected idField: string;
-  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
-  readonly accessControl: AccessControl;
-  /** Composable body sanitization (field permissions, system fields) */
-  readonly bodySanitizer: BodySanitizer;
-  /** Composable query resolution (parsing, pagination, sort, select/populate) */
-  readonly queryResolver: QueryResolver;
-  private _matchesFilter?;
-  private _presetFields;
-  private _cacheConfig?;
-  constructor(repository: TRepository, options?: BaseControllerOptions);
-  /**
-   * Get the tenant field name if multi-tenant scoping is enabled.
-   * Returns `undefined` when `tenantField` is `false` (platform-universal mode).
-   *
-   * Use this in subclass overrides instead of accessing `this.tenantField` directly
-   * to avoid TypeScript indexing errors with `string | false`.
-   */
-  protected getTenantField(): string | undefined;
-  /** Extract typed Arc internal metadata from request */
-  private meta;
-  /** Get hook system from request context (instance-scoped) */
-  private getHooks;
-  /**
-   * Resolve 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;
-  /** Resolve cache config for a specific operation, merging per-op overrides */
-  private resolveCacheConfig;
-  /**
-   * Extract user/org IDs from request for cache key scoping.
-   * Only includes orgId when this resource uses tenant-scoped data (tenantField is set).
-   * Universal resources (tenantField: false) get shared cache keys to avoid fragmentation.
-   */
-  private cacheScope;
-  list(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
-  /** Execute list query through hooks (extracted for cache revalidation) */
-  private executeListQuery;
-  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  /** Execute get query through hooks (extracted for cache revalidation) */
-  private executeGetQuery;
-  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  delete(req: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-    id?: string;
-    soft?: boolean;
-  }>>;
-  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  getDeleted(req: IRequestContext): Promise<IControllerResponse<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;
-  }>>;
-}
-//#endregion
-//#region src/types/index.d.ts
-declare module 'fastify' {
-  interface FastifyRequest {
-    /** Request scope — set by auth adapter, read by permissions/presets/guards */
-    scope: RequestScope;
-    /**
-     * Current user — set by auth adapter (Better Auth, JWT, custom).
-     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
-     * Guard with `if (request.user)` on routes that allow anonymous access.
-     *
-     * Note: kept as required (not `user?`) because `@fastify/jwt` declares it
-     * as required — declaration merges must have identical modifiers.
-     * The `| undefined` in the type achieves the same DX: TypeScript will
-     * flag unguarded access like `request.user.id` as possibly undefined.
-     */
-    user: Record<string, unknown> | undefined;
-    /** Policy-injected query filters (e.g. ownership, org-scoping) */
-    _policyFilters?: Record<string, unknown>;
-    /** Field mask — fields to include/exclude in responses */
-    fieldMask?: {
-      include?: string[];
-      exclude?: string[];
-    };
-    /** Arbitrary policy metadata for downstream consumers */
-    policyMetadata?: Record<string, unknown>;
-    /** Document loaded by policy middleware for ownership checks */
-    document?: unknown;
-    /** Ownership check context (field name + user field) */
-    _ownershipCheck?: Record<string, unknown>;
-  }
-}
-/**
- * Typed Fastify request with Arc decorations.
+ * **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>`)
  *
- * Use this in `raw: true` handlers instead of `(req as any).user`.
+ * 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
- * import type { ArcRequest } from '@classytic/arc';
+ * // 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 };
+ * };
  *
- * handler: async (req: ArcRequest, reply: FastifyReply) => {
- *   req.user?.id;                    // typed
- *   req.scope.organizationId;        // typed (when member)
- *   req.signal;                      // AbortSignal (Fastify 5)
- * }
+ * // 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 ArcRequest = FastifyRequest & {
-  scope: RequestScope;
-  user: Record<string, unknown> | undefined;
-  signal: AbortSignal;
-};
+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>>;
 /**
- * Response envelope helper — wraps data in Arc's standard `{ success, data }` format.
+ * Fastify native handler
+ *
+ * Standard Fastify request/reply pattern.
+ * Use with `raw: true` in routes.
  *
  * @example
  * ```typescript
- * import { envelope } from '@classytic/arc';
+ * const downloadFile: FastifyHandler = async (request, reply) => {
+ *   const file = await getFile(request.params.id);
+ *   reply.header('Content-Type', file.mimeType);
+ *   return reply.send(file.buffer);
+ * };
  *
- * handler: async (req, reply) => {
- *   const data = await getResults();
- *   return envelope(data);
- *   // → { success: true, data }
- * }
+ * routes: [{
+ *   method: 'GET',
+ *   path: '/files/:id/download',
+ *   handler: downloadFile,
+ *   permissions: requireAuth(),
+ *   raw: true,  // Use as-is, no wrapping
+ * }]
  * ```
  */
-declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
-  success: true;
-  data: T;
-  [key: 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;
-};
+type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
 /**
- * Flexible user type that accepts any object with id/ID properties.
- * Use this instead of `any` when dealing with user objects.
- * Re-exports UserBase from permissions module for convenience.
- * The actual user structure is defined by your app's auth system.
+ * Union type for route handlers
  */
-type UserLike = UserBase & {
-  /** User email (optional) */email?: string;
-};
+type RouteHandler = ControllerHandler | FastifyHandler;
 /**
- * Extract user ID from a user object (supports both id and _id)
+ * Controller interface for CRUD operations (strict)
  */
-declare function getUserId(user: UserLike | null | undefined): string | undefined;
-type CrudController<TDoc> = IController<TDoc>;
-interface ApiResponse<T = unknown> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-  meta?: Record<string, unknown>;
-}
-interface UserOrganization {
-  userId: string;
-  organizationId: string;
-  [key: string]: unknown;
-}
-interface JWTPayload {
-  sub: string;
-  [key: string]: unknown;
+interface 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;
+  }>>;
 }
-interface RequestContext {
-  operation?: string;
-  user?: unknown;
-  filters?: Record<string, unknown>;
+/**
+ * Flexible controller interface - accepts controllers with any handler style
+ * Use this when your controller uses Fastify native handlers
+ */
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
   [key: string]: unknown;
 }
+//#endregion
+//#region src/types/resource.d.ts
+/** Standard controller type alias for CRUD operations. */
+type CrudController<TDoc> = IController<TDoc>;
 /**
- * Internal metadata shape injected by Arc's Fastify adapter.
- * Extends RequestContext with known internal fields so controllers
- * can access them without `as AnyRecord` casts.
+ * Per-resource cache configuration for QueryCache. Enables
+ * stale-while-revalidate, auto-invalidation on mutations, and
+ * cross-resource tag-based invalidation.
  */
-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;
+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;
   };
-  /** Arc instance references (hooks, field permissions, etc.) */
-  arc?: {
-    hooks?: HookSystem;
-    fields?: FieldPermissionMap;
-    [key: string]: unknown;
+  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;
 }
-/**
- * Controller-level query options - parsed from request query string
- * Includes pagination, filtering, and context data
- */
-interface ControllerQueryOptions {
-  page?: number;
-  limit?: number;
-  sort?: string | Record<string, 1 | -1>;
-  /** Simple populate (comma-separated string or array) */
-  populate?: string | string[] | Record<string, unknown>;
+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[];
   /**
-   * Advanced populate options (Mongoose-compatible)
-   * When set, takes precedence over simple `populate`
+   * Fields allowed for filtering in list operations. MCP auto-derives
+   * from `QueryParser.allowedFilterFields` when not set explicitly.
    */
-  populateOptions?: PopulateOption[];
+  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>;
   /**
-   * Lookup/join options (database-agnostic).
-   * MongoKit maps these to $lookup aggregation pipeline stages.
-   * Future adapters (PrismaKit, PgKit) would map to SQL JOINs.
-   *
-   * @example
-   * URL: ?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug
+   * 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.
    */
-  lookups?: LookupOption[];
-  select?: string | string[] | Record<string, 0 | 1>;
-  filters?: Record<string, unknown>;
-  search?: string;
-  lean?: boolean;
-  after?: string;
-  user?: unknown;
-  context?: Record<string, unknown>;
-  /** Allow additional options */
-  [key: string]: unknown;
+  strictAdditionalProperties?: boolean;
 }
-/**
- * Database-agnostic lookup/join option.
- * Parsed from URL: ?lookup[alias][from]=collection&lookup[alias][localField]=field&lookup[alias][foreignField]=field
- *
- * MongoKit maps this to MongoDB $lookup aggregation.
- * Future adapters would map to SQL JOINs or Prisma includes.
- */
-interface LookupOption {
-  /** Source collection/table to join from */
-  from: string;
-  /** Local field to match on */
-  localField: string;
-  /** Foreign field to match on */
-  foreignField: string;
-  /** Alias for the joined data (defaults to the lookup key) */
-  as?: string;
-  /** Return a single object instead of array (default: false) */
-  single?: boolean;
-  /** Field selection on the joined collection (comma-separated string or projection object) */
-  select?: string | Record<string, 0 | 1>;
+interface FieldRule {
+  field: string;
+  required?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
 }
 /**
- * Mongoose-compatible populate option for advanced field selection
- * Used when you need to select specific fields from populated documents
- *
- * @example
- * ```typescript
- * // URL: ?populate[author][select]=name,email
- * // Generates: { path: 'author', select: 'name email' }
- * ```
+ * 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 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;
+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;
   };
-  /** Nested populate configuration */
-  populate?: PopulateOption;
+  /** 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;
 }
-/**
- * Parsed query result from QueryParser
- * Includes pagination, sorting, filtering, etc.
- *
- * The index signature allows custom query parsers (like MongoKit's QueryParser)
- * to add additional fields without breaking Arc's type system.
- */
-interface ParsedQuery {
-  filters?: Record<string, unknown>;
-  limit?: number;
-  sort?: string | Record<string, 1 | -1>;
-  /** Simple populate (comma-separated string or array) */
-  populate?: string | string[] | Record<string, unknown>;
-  /**
-   * Advanced populate options (Mongoose-compatible)
-   * When set, takes precedence over simple `populate`
-   * @example [{ path: 'author', select: 'name email' }]
-   */
-  populateOptions?: PopulateOption[];
+interface OpenApiSchemas {
+  entity?: unknown;
+  createBody?: unknown;
+  updateBody?: unknown;
+  params?: unknown;
+  listQuery?: unknown;
   /**
-   * Lookup/join options from MongoKit QueryParser or custom parsers.
-   * Maps to $lookup in MongoDB, JOINs in SQL adapters.
+   * Explicit response schema for OpenAPI documentation. Auto-generated
+   * from `createBody` if omitted. Does NOT affect Fastify serialization.
    */
-  lookups?: LookupOption[];
-  search?: string;
-  page?: number;
-  after?: string;
-  select?: string | string[] | Record<string, 0 | 1>;
-  /** Allow additional fields from custom query parsers */
+  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;
+  };
+}
 /**
- * Query Parser Interface
- * Implement this to create custom query parsers
+ * Route definition — single custom-route shape (user-facing + internal).
  *
- * @example MongoKit QueryParser
- * ```typescript
- * import { QueryParser } from '@classytic/mongokit';
- * const queryParser = new QueryParser();
- * ```
+ * - `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 QueryParserInterface {
-  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+interface RouteDefinition {
+  readonly method: RouteMethod;
+  /** Path relative to resource prefix */
+  readonly path: string;
   /**
-   * Optional: Export OpenAPI schema for query parameters
-   * Use this to document query parameters in OpenAPI/Swagger
+   * 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)`
    */
-  getQuerySchema?(): {
-    type: 'object';
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
+  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
+  /** Permission check — REQUIRED */
+  readonly permissions: PermissionCheck;
   /**
-   * Optional: Allowed filter fields whitelist.
-   * When set, MCP auto-derives `filterableFields` from this
-   * if `schemaOptions.filterableFields` is not explicitly configured.
+   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
+   * request/reply. Default: false.
    */
-  allowedFilterFields?: readonly string[];
+  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;
   /**
-   * Optional: Allowed filter operators whitelist.
-   * Used by MCP to enrich list tool descriptions with available operators.
-   * Values are human-readable keys: 'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', etc.
+   * 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`.
    */
-  allowedOperators?: readonly string[];
+  readonly schema?: {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<number | string, unknown>;
+    [key: string]: unknown;
+  };
   /**
-   * Optional: Allowed sort fields whitelist.
-   * Used by MCP to describe available sort options in list tool descriptions.
+   * MCP tool generation:
+   * - omitted/true: auto-generate (non-raw routes only)
+   * - false: skip MCP
+   * - object: explicit config
    */
-  allowedSortFields?: readonly string[];
-}
-interface FastifyRequestExtras {
-  user?: Record<string, unknown>;
-}
-interface RequestWithExtras extends FastifyRequest {
+  readonly mcp?: boolean | RouteMcpConfig;
   /**
-   * Arc metadata - set by createCrudRouter
-   * Contains resource configuration and schema options
+   * MCP handler for raw routes — parallel entry point for MCP without
+   * changing the HTTP handler.
    */
-  arc?: {
-    resourceName?: string;
-    schemaOptions?: RouteSchemaOptions;
-    permissions?: ResourcePermissions;
-  };
-  context?: Record<string, unknown>;
-  _policyFilters?: Record<string, unknown>;
-  fieldMask?: {
-    include?: string[];
-    exclude?: string[];
-  };
-  _ownershipCheck?: Record<string, unknown>;
-}
-type FastifyWithAuth = FastifyInstance & {
-  authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-};
-/**
- * Arc core decorator interface
- * Added by arcCorePlugin to provide instance-scoped hooks and registry
- */
-interface ArcDecorator {
-  /** Instance-scoped hook system */
-  hooks: HookSystem;
-  /** Instance-scoped resource registry */
-  registry: ResourceRegistry;
-  /** Whether event emission is enabled */
-  emitEvents: boolean;
+  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
 }
 /**
- * Events decorator interface
- * Added by eventPlugin to provide event pub/sub
+ * Action handler function for state transitions. Receives the resource
+ * ID, action-specific data, and the request.
  */
-interface EventsDecorator {
-  /** Publish an event */
-  publish: <T>(type: string, payload: T, meta?: Partial<{
-    id: string;
-    timestamp: Date;
-  }>) => Promise<void>;
-  /** Subscribe to events */
-  subscribe: (pattern: string, handler: (event: unknown) => void | Promise<void>) => Promise<() => void>;
-  /** Get transport name */
-  transportName: string;
+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>;
 /**
- * Fastify instance with Arc decorators
- * Arc adds these decorators via plugins/presets
+ * Hook context passed to resource-level hook handlers. Mirrors
+ * HookSystem's HookContext but with a simpler API for inline use.
  */
-type FastifyWithDecorators = FastifyInstance & {
-  arc?: ArcDecorator;
-  events?: EventsDecorator;
-  authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  organizationScoped?: (options?: {
-    required?: boolean;
-  }) => RouteHandlerMethod;
-  [key: string]: unknown;
-};
-interface OwnershipCheck {
-  field: string;
-  userField?: string;
+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;
 }
 /**
- * Per-resource rate limit configuration.
- *
- * Applied to all routes of the resource when `@fastify/rate-limit` is registered
- * on the Fastify instance. Set to `false` to explicitly disable rate limiting
- * for a resource even when a global rate limit is configured.
+ * Inline lifecycle hooks on a resource definition. Wired into the
+ * HookSystem automatically — same pipeline as presets and app-level hooks.
  *
  * @example
  * ```typescript
  * defineResource({
- *   name: 'product',
- *   rateLimit: { max: 100, timeWindow: '1 minute' },
+ *   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');
+ *     },
+ *   },
  * });
  * ```
  */
-/**
- * Per-resource cache configuration for QueryCache.
- * Enables stale-while-revalidate, auto-invalidation on mutations,
- * and cross-resource tag-based invalidation.
- */
-interface ResourceCacheConfig {
-  /** Seconds data is "fresh" (no revalidation). Default: 0 */
-  staleTime?: number;
-  /** Seconds stale data stays cached (SWR window). Default: 60 */
-  gcTime?: number;
-  /** Per-operation overrides */
-  list?: {
-    staleTime?: number;
-    gcTime?: number;
-  };
-  byId?: {
-    staleTime?: number;
-    gcTime?: number;
-  };
-  /** Tags for cross-resource invalidation grouping */
-  tags?: string[];
-  /**
-   * Cross-resource invalidation: event pattern → tag targets.
-   * When matched event fires, all caches with those tags are invalidated.
-   * @example { 'category.*': ['catalog'] }
-   */
-  invalidateOn?: Record<string, string[]>;
-  /** Disable caching for this resource */
-  disabled?: boolean;
+interface 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 RateLimitConfig {
-  /** Maximum number of requests allowed within the time window */
-  max: number;
-  /** Time window for rate limiting (e.g., '1 minute', '15 seconds', '1 hour') */
-  timeWindow: string;
+interface 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`.
+   * 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 })
-   * // Registers at /webhooks even when createApp({ resourcePrefix: '/api/v1' })
    * ```
    */
   skipGlobalPrefix?: boolean;
+  /** Optional for service-pattern resources */
   adapter?: DataAdapter<TDoc>;
-  /** Controller instance - accepts any object with CRUD methods */
+  /** 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, and interceptors.
-   * Can be a flat array (all operations) or per-operation map.
+   * Functional pipeline — guards, transforms, interceptors. Flat array
+   * (all operations) or per-operation map.
    *
    * @example
    * ```typescript
-   * import { pipe, guard, transform, intercept } from '@classytic/arc';
-   *
-   * resource('product', {
-   *   pipe: pipe(isActive, slugify, timing),
-   *   // OR per-operation:
-   *   pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
-   * });
+   * pipe: pipe(isActive, slugify, timing),
+   * pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
    * ```
    */
   pipe?: PipelineConfig;
@@ -2019,7 +1334,6 @@ interface ResourceConfig<TDoc = AnyRecord> {
    *
    * @example
    * ```typescript
-   * import { fields } from '@classytic/arc';
    * fields: {
    *   salary: fields.visibleTo(['admin', 'hr']),
    *   password: fields.hidden(),
@@ -2027,23 +1341,22 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * ```
    */
   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 `routes` + preset routes). Runs after auth/permissions,
-   * before per-route `preHandler`. Use for mode gates, tenant checks,
-   * feature flags — anything that applies to every endpoint.
-   *
-   * @example
-   * ```typescript
-   * defineResource({
-   *   routeGuards: [requireFlowMode('standard')],
-   *   routes: [
-   *     { method: 'GET', path: '/', raw: true, handler: listHandler },
-   *     // guard runs automatically — no per-route boilerplate
-   *   ],
-   * });
-   * ```
+   * (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[];
   /**
@@ -2059,8 +1372,9 @@ interface ResourceConfig<TDoc = AnyRecord> {
    */
   routes?: RouteDefinition[];
   /**
-   * State-transition actions → unified POST /:id/action endpoint.
-   * Each action can be a bare handler or full config with permissions + schema.
+   * State-transition actions → unified `POST /:id/action` endpoint.
+   * Each action can be a bare handler or full config with permissions
+   * + schema.
    *
    * @example
    * ```typescript
@@ -2083,72 +1397,59 @@ interface ResourceConfig<TDoc = AnyRecord> {
   actionPermissions?: PermissionCheck;
   disableCrud?: boolean;
   disableDefaultRoutes?: boolean;
+  /** Specific routes to disable */
   disabledRoutes?: CrudRouteKey[];
   /**
    * Field name used for multi-tenant scoping (default: 'organizationId').
-   * Override to match your schema: 'workspaceId', 'tenantId', 'teamId', etc.
-   * Takes effect when org context is present (via multiTenant preset).
+   * Override to match your schema: 'workspaceId', 'tenantId', etc.
    */
   tenantField?: string | false;
   /**
    * Primary key field name (default: '_id').
    *
-   * Type-narrowed to `keyof TDoc` when `defineResource<TDoc>` is called with
-   * a typed document interface — gives autocomplete for valid field names —
-   * while still accepting any string when TDoc is `unknown` / `AnyRecord` so
-   * adapters with dynamic shapes still work.
+   * Type-narrowed to `keyof TDoc` when `defineResource<TDoc>` is called
+   * with a typed document interface — autocomplete for valid field names
+   * — while still accepting any string when TDoc is `unknown` /
+   * `AnyRecord` so adapters with dynamic shapes still work.
    *
    * @example
    * ```ts
    * defineResource<IJob>({ idField: 'jobId' })  // ← autocompletes from IJob fields
    * defineResource({ idField: 'sku' })          // ← any string allowed
    * ```
-   *
-   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases) or
-   * resources keyed by a business identifier (slug, sku, orderNumber).
    */
   idField?: (keyof TDoc & string) | (string & {});
+  /** For grouping in registry */
   module?: string;
+  /** Domain events */
   events?: Record<string, EventDefinition>;
+  /** Skip schema validation */
   skipValidation?: boolean;
+  /** Don't register in introspection */
   skipRegistry?: boolean;
+  /** Internal: track applied presets */
   _appliedPresets?: string[];
-  /**
-   * Called during plugin registration with the scoped Fastify instance.
-   * Use for wiring singletons, reading decorators, or setting up resource-specific
-   * services that need access to the Fastify instance.
-   *
-   * @example
-   * ```typescript
-   * defineResource({
-   *   name: 'notification',
-   *   onRegister: (fastify) => {
-   *     setSseManager(fastify.sseManager);
-   *   },
-   * })
-   * ```
-   */
-  onRegister?: (fastify: FastifyInstance) => void | Promise<void>;
   /** HTTP method for update routes. Default: 'PATCH' */
-  updateMethod?: 'PUT' | 'PATCH' | 'both';
+  updateMethod?: "PUT" | "PATCH" | "both";
   /**
-   * Per-resource rate limiting.
-   * Requires `@fastify/rate-limit` to be registered on the Fastify instance.
-   * Set to `false` to disable rate limiting for this resource.
+   * Per-resource rate limiting. Requires `@fastify/rate-limit` to be
+   * registered. Set to `false` to disable for this resource.
    */
   rateLimit?: RateLimitConfig | false;
   /**
-   * QueryCache configuration for this resource.
-   * Enables stale-while-revalidate and auto-invalidation.
-   * Requires `queryCachePlugin` to be registered.
+   * QueryCache configuration for this resource. Enables
+   * stale-while-revalidate and auto-invalidation. Requires
+   * `queryCachePlugin` to be registered.
    */
   cache?: ResourceCacheConfig;
   /**
    * Per-resource audit opt-in. When `auditPlugin` is registered with
-   * `autoAudit: { perResource: true }`, only resources with this flag are audited.
+   * `autoAudit: { perResource: true }`, only resources with this flag
+   * are audited.
    *
-   * The cleanest pattern for apps where most resources don't need auditing —
-   * no growing exclude lists, no centralized allowlist to maintain.
+   * The cleanest pattern for apps where most resources don't need
+   * auditing — no growing exclude lists, no centralized allowlist to
+   * maintain.
    *
    * - `true`: Audit create/update/delete on this resource
    * - `{ operations: ['delete'] }`: Audit only specific operations
@@ -2156,15 +1457,8 @@ interface ResourceConfig<TDoc = AnyRecord> {
    *
    * @example
    * ```ts
-   * // app.ts
-   * await fastify.register(auditPlugin, {
-   *   autoAudit: { perResource: true },
-   * });
-   *
-   * // order.resource.ts
+   * await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
    * defineResource({ name: 'order', audit: true });
-   *
-   * // payment.resource.ts
    * defineResource({ name: 'payment', audit: { operations: ['delete'] } });
    * ```
    */
@@ -2172,450 +1466,226 @@ interface ResourceConfig<TDoc = AnyRecord> {
     operations?: ("create" | "update" | "delete")[];
   };
 }
+//#endregion
+//#region src/core/defineResource.d.ts
 /**
- * Resource-level permissions
- * ONLY PermissionCheck functions allowed - no string arrays
- */
-interface ResourcePermissions {
-  list?: PermissionCheck;
-  get?: PermissionCheck;
-  create?: PermissionCheck;
-  update?: PermissionCheck;
-  delete?: PermissionCheck;
-}
-/**
- * Hook context passed to resource-level hook handlers.
- * Mirrors HookSystem's HookContext but with a simpler API for inline use.
- */
-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;
-}
-/**
- * Inline lifecycle hooks on a resource definition.
- * These are wired into the HookSystem automatically — same pipeline as presets and app-level hooks.
+ * Define a resource with database adapter
  *
- * @example
- * ```typescript
- * defineResource({
- *   name: 'chat',
- *   hooks: {
- *     afterCreate: async (ctx) => {
- *       analytics.track('chat.created', { chatId: ctx.data._id, userId: ctx.user?.id });
- *     },
- *     beforeDelete: async (ctx) => {
- *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
- *     },
- *     afterDelete: async (ctx) => {
- *       await notificationService.send('chat.deleted', { id: ctx.meta?.id });
- *     },
- *   },
- * });
- * ```
+ * This is the MAIN entry point for creating Arc resources.
+ * The adapter provides both repository and schema metadata.
  */
-interface ResourceHooks {
-  /** Runs before create — can modify data by returning a new object */
-  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
-  /** Runs after create — receives the created document */
-  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | void;
-  /** Runs before update — ctx.meta.id has the resource ID, ctx.meta.existing has the current doc */
-  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
-  /** Runs after update — receives the updated document */
-  afterUpdate?: (ctx: ResourceHookContext) => Promise<void> | void;
-  /** Runs before delete — ctx.data is the existing doc, ctx.meta.id has the resource ID */
-  beforeDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
-  /** Runs after delete — ctx.data is the deleted doc, ctx.meta.id has the resource ID */
-  afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+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;
+  }>;
 }
-/**
- * Additional route definition for custom endpoints
- */
-interface AdditionalRoute {
-  /** HTTP method */
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  /** Route path (relative to resource prefix) */
-  path: 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;
   /**
-   * Handler - string (controller method name) or function.
-   *
-   * When `wrapHandler: true`:
-   * - `string` — calls controller method by name (e.g., `'approve'`)
-   * - `ControllerHandler` — receives `IRequestContext`, returns `IControllerResponse`
-   *
-   * When `wrapHandler: false`:
-   * - Fastify handler `(request, reply) => unknown`
+   * Get event definitions for registry
    */
-  handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<any>, reply: FastifyReply) => unknown);
-  /** Permission check - REQUIRED */
-  permissions: PermissionCheck;
+  getEvents(): Array<{
+    name: string;
+    module: string;
+    schema?: AnyRecord;
+    description?: string;
+  }>;
   /**
-   * Handler type - REQUIRED, no auto-detection
-   * true = ControllerHandler (receives context object)
-   * false = FastifyHandler (receives request, reply)
+   * Get resource metadata
    */
-  wrapHandler: boolean;
+  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();
   /**
-   * Logical operation name for pipeline keys and permission actions.
-   * Defaults to handler name (string handlers) or method+path slug.
-   * Prevents collisions when multiple routes share the same HTTP method.
-   *
-   * @example
-   * operation: 'listDeleted'  // Used as pipeline key and permission action
-   * operation: 'restore'
+   * Register a resource
    */
-  operation?: string;
-  /** OpenAPI summary */
-  summary?: string;
-  /** OpenAPI description */
-  description?: string;
-  /** OpenAPI tags */
-  tags?: string[];
+  register(resource: ResourceDefinition<unknown>, options?: RegisterOptions): this;
   /**
-   * Custom route-level middleware
-   * Can be an array of handlers or a function that receives fastify and returns handlers
-   * @example
-   * // Direct array
-   * preHandler: [myMiddleware]
-   * // Function that receives fastify (for accessing decorators)
-   * preHandler: (fastify) => [fastify.customerContext({ required: true })]
+   * Get resource by name
    */
-  preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
+  get(name: string): RegistryEntry | undefined;
   /**
-   * Pre-auth handlers — run BEFORE authentication middleware.
-   * Use for promoting query params to headers (e.g., EventSource ?token= → Authorization).
-   *
-   * @example
-   * ```typescript
-   * preAuth: [(req) => {
-   *   const token = (req.query as Record<string, string>)?.token;
-   *   if (token) req.headers.authorization = `Bearer ${token}`;
-   * }]
-   * ```
+   * Get all resources
    */
-  preAuth?: RouteHandlerMethod[];
+  getAll(): RegistryEntry[];
   /**
-   * Streaming response mode — designed for SSE and AI streaming routes.
-   * When `true`:
-   * - Forces `wrapHandler: false` (no `{ success, data }` wrapper)
-   * - Sets SSE headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`
-   * - `request.signal` (Fastify 5 built-in) is available for abort-on-disconnect
-   *
-   * @example
-   * ```typescript
-   * {
-   *   method: 'POST',
-   *   path: '/stream',
-   *   streamResponse: true,
-   *   permissions: requireAuth(),
-   *   handler: async (request, reply) => {
-   *     const { stream } = await generateStream({ abortSignal: request.signal });
-   *     return reply.send(stream);
-   *   },
-   * }
-   * ```
+   * Get resources by module
    */
-  streamResponse?: boolean;
-  /** Fastify route schema */
-  schema?: Record<string, unknown>;
+  getByModule(moduleName: string): RegistryEntry[];
   /**
-   * MCP handler for routes with `wrapHandler: false`.
-   * When set, this route becomes an MCP tool without needing `wrapHandler: true`.
-   * The HTTP handler stays a plain Fastify handler; MCP gets a parallel entry point.
-   *
-   * @example
-   * ```typescript
-   * additionalRoutes: [{
-   *   method: 'GET',
-   *   path: '/stats',
-   *   handler: (req, reply) => reply.send(getStats()),
-   *   wrapHandler: false,
-   *   permissions: isAuthenticated,
-   *   mcpHandler: async (input) => ({
-   *     content: [{ type: 'text', text: JSON.stringify(await getStats()) }],
-   *   }),
-   * }]
-   * ```
+   * Get resources by preset
    */
-  mcpHandler?: (input: Record<string, unknown>) => Promise<{
-    content: Array<{
-      type: string;
-      text: string;
-    }>;
-    isError?: boolean;
-  }>;
+  getByPreset(presetName: string): RegistryEntry[];
   /**
-   * MCP tool generation config preserved from v2.8 `routes`.
-   * - `false`: skip MCP tool generation for this route
-   * - `true` / omitted: auto-generate when the route goes through Arc's pipeline
-   * - object: explicit description/annotations overrides
-   *
-   * Added in 2.8.1 — previously dropped during `routes → additionalRoutes`
-   * normalization, breaking MCP opt-out and per-route annotations.
-   */
-  mcp?: boolean | {
-    readonly description?: string;
-    readonly annotations?: {
-      readonly readOnlyHint?: boolean;
-      readonly destructiveHint?: boolean;
-      readonly idempotentHint?: boolean;
-      readonly openWorldHint?: boolean;
-    };
-  };
-}
-/** 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 — replaces additionalRoutes.
- *
- * - `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;
+   * Check if resource exists
+   */
+  has(name: string): boolean;
   /**
-   * Route handler.
-   * - String: controller method name (goes through Arc pipeline)
-   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (goes through Arc pipeline)
-   * - Function with `raw: true`: raw Fastify handler (request, reply)
+   * Get registry statistics
    */
-  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
-  /** Permission check — REQUIRED */
-  readonly permissions: PermissionCheck;
+  getStats(): RegistryStats;
   /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify request/reply.
-   * Default: false (handler goes through Arc pipeline).
+   * Get full introspection data
    */
-  readonly raw?: boolean;
-  /** Logical operation name (for pipeline keys, MCP tool naming). Defaults to handler name or method+path slug. */
-  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;
+  getIntrospection(): IntrospectionData;
   /**
-   * 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` at registration time. Slot values
-   * are typed `unknown` so class-based Zod schemas assign without casts.
+   * Freeze registry (prevent further registrations)
    */
-  readonly schema?: {
-    body?: unknown;
-    querystring?: unknown;
-    params?: unknown;
-    headers?: unknown;
-    response?: Record<number | string, unknown>;
-    [key: string]: unknown;
-  };
+  freeze(): void;
   /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate (non-raw routes only)
-   * - false: skip MCP
-   * - object: explicit config
+   * Check if frozen
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  isFrozen(): boolean;
   /**
-   * MCP handler for raw routes — parallel entry point for MCP without changing HTTP handler.
+   * Unfreeze registry (allow new registrations)
    */
-  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 context.
- */
-type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
-/**
- * Full action configuration with handler, permissions, and schema.
- */
-interface ActionDefinition {
-  /** Action handler */
-  readonly handler: ActionHandlerFn;
-  /** Per-action permission check (overrides resource-level actionPermissions) */
-  readonly permissions?: PermissionCheck;
+  unfreeze(): void;
   /**
-   * JSON Schema or Zod v4 schema for action-specific body fields.
-   * Per-field values are typed `unknown` so Zod class instances assign without casts.
+   * Reset registry — clear all resources and unfreeze
    */
-  readonly schema?: Record<string, unknown>;
-  /** Description for OpenAPI docs and MCP tool */
-  readonly description?: string;
+  reset(): void;
+  /** @internal Alias for unfreeze() */
+  _unfreeze(): void;
+  /** @internal Alias for reset() */
+  _clear(): void;
   /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate
-   * - false: skip
-   * - object: explicit config
+   * Group by key
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  private _groupBy;
 }
-/** Action config: bare handler function OR full ActionDefinition */
-type ActionEntry = ActionHandlerFn | ActionDefinition;
-/** Actions configuration map */
-type ActionsMap = Record<string, ActionEntry>;
-interface RouteSchemaOptions {
-  hiddenFields?: string[];
-  readonlyFields?: string[];
-  requiredFields?: string[];
-  optionalFields?: string[];
-  excludeFields?: string[];
+//#endregion
+//#region src/types/fastify.d.ts
+interface FastifyRequestExtras {
+  user?: Record<string, unknown>;
+}
+interface RequestWithExtras extends FastifyRequest {
   /**
-   * Fields allowed for filtering in list operations.
-   * Used by MCP tool generation to build the list tool's input schema.
-   * If not set and using a QueryParser with `allowedFilterFields`, MCP auto-derives from it.
+   * Arc metadata — set by createCrudRouter. Contains resource configuration
+   * and schema options.
    */
-  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?: Record<string, unknown>;
-}
-interface FieldRule {
-  field: string;
-  required?: boolean;
-  readonly?: boolean;
-  hidden?: boolean;
+  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>;
+};
 /**
- * CRUD Route Schemas (Fastify Native Format)
- *
- * Each slot accepts either a plain JSON Schema object **or** a Zod v4 schema —
- * arc's `convertRouteSchema` feature-detects at runtime. The slot values are
- * typed `unknown` (not `Record<string, unknown>`) so class-based Zod schemas
- * assign cleanly without `as unknown as Record<string, unknown>` casts.
- *
- * @example
- * ```ts
- * {
- *   list: {
- *     querystring: { type: 'object', properties: { page: { type: 'number' } } },
- *     response: { 200: z.object({ docs: z.array(EntitySchema) }) }
- *   },
- *   create: {
- *     body: z.object({ name: z.string(), size: z.number().int().positive() }),
- *     response: { 201: EntitySchema }
- *   }
- * }
- * ```
+ * Arc core decorator — added by `arcCorePlugin`. Provides instance-scoped
+ * hooks and resource registry.
  */
-interface CrudSchemas {
-  /** GET / - List all resources */
-  list?: {
-    /** Plain JSON Schema or Zod schema (auto-converted). */querystring?: unknown; /** Map of HTTP status code → JSON Schema or Zod schema. */
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** GET /:id - Get single resource */
-  get?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** POST / - Create resource */
-  create?: {
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** PATCH /:id - Update resource */
-  update?: {
-    params?: unknown;
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** DELETE /:id - Delete resource */
-  delete?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
+interface ArcDecorator {
+  hooks: HookSystem;
+  registry: ResourceRegistry;
+  /** Whether event emission is enabled */
+  emitEvents: boolean;
 }
-interface OpenApiSchemas {
-  entity?: unknown;
-  createBody?: unknown;
-  updateBody?: unknown;
-  params?: unknown;
-  listQuery?: unknown;
+/** 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>;
   /**
-   * Explicit response schema for OpenAPI documentation.
-   * If provided, this will be used as-is for the response schema.
-   * If not provided, response schema is auto-generated from createBody.
-   *
-   * Note: This is for OpenAPI docs only - does NOT affect Fastify serialization.
-   *
-   * @example
-   * response: {
-   *   type: 'object',
-   *   properties: {
-   *     _id: { type: 'string' },
-   *     name: { type: 'string' },
-   *     email: { type: 'string' },
-   *     // Exclude password, include virtuals
-   *     fullName: { type: 'string' },
-   *   }
-   * }
+   * 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.
    */
-  response?: unknown;
-  [key: string]: unknown;
+  subscribe: <T = unknown>(pattern: string, handler: (event: DomainEvent<T>) => void | Promise<void>) => Promise<() => void>;
+  transportName: string;
 }
-/** Handler for middleware functions */
+/**
+ * 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>;
-type CrudRouteKey = 'list' | 'get' | 'create' | 'update' | 'delete';
-interface MiddlewareConfig {
-  list?: MiddlewareHandler[];
-  get?: MiddlewareHandler[];
-  create?: MiddlewareHandler[];
-  update?: MiddlewareHandler[];
-  delete?: MiddlewareHandler[];
-  [key: string]: MiddlewareHandler[] | undefined;
-}
+//#endregion
+//#region src/types/auth.d.ts
 /**
- * JWT utilities provided to authenticator
- * Arc provides these helpers, app uses them as needed
+ * JWT utilities provided to authenticator. Arc provides the helpers;
+ * apps use them as needed.
  */
 interface JwtContext {
   /** Verify a JWT token and return decoded payload */
@@ -2627,51 +1697,31 @@ interface JwtContext {
   /** Decode without verification (for inspection) */
   decode: <T = Record<string, unknown>>(token: string) => T | null;
 }
-/**
- * Context passed to app's authenticator function
- */
+/** Context passed to app's authenticator function. */
 interface AuthenticatorContext {
-  /** JWT utilities (available if jwt.secret provided) */
+  /** JWT utilities (available if `jwt.secret` provided) */
   jwt: JwtContext | null;
   /** Fastify instance for advanced use cases */
   fastify: FastifyInstance;
 }
 /**
- * App-provided authenticator function
+ * App-provided authenticator function. Arc calls this for every
+ * non-public route. The app has full control over authentication logic.
  *
- * Arc calls this for every non-public route.
- * App has FULL control over authentication logic.
+ * Return a user object to authenticate, `null`/`undefined` to reject.
  *
  * @example
  * ```typescript
- * // Simple JWT auth
  * authenticate: async (request, { jwt }) => {
  *   const token = request.headers.authorization?.split(' ')[1];
  *   if (!token || !jwt) return null;
  *   const decoded = jwt.verify(token);
  *   return userRepo.findById(decoded.id);
  * }
- *
- * // Multi-strategy (JWT + API Key)
- * authenticate: async (request, { jwt }) => {
- *   const apiKey = request.headers['x-api-key'];
- *   if (apiKey) {
- *     const result = await apiKeyService.verify(apiKey);
- *     if (result) return { _id: result.userId, isApiKey: true };
- *   }
- *   const token = request.headers.authorization?.split(' ')[1];
- *   if (token && jwt) {
- *     const decoded = jwt.verify(token);
- *     return userRepo.findById(decoded.id);
- *   }
- *   return null;
- * }
  * ```
  */
 type Authenticator = (request: FastifyRequest, context: AuthenticatorContext) => Promise<unknown | null> | unknown | null;
-/**
- * Token pair returned by issueTokens helper
- */
+/** Token pair returned by `issueTokens` helper. */
 interface TokenPair {
   /** Access token (JWT) */
   accessToken: string;
@@ -2682,25 +1732,18 @@ interface TokenPair {
   /** Refresh token expiry in seconds */
   refreshExpiresIn?: number;
   /** Token type (always 'Bearer') */
-  tokenType: 'Bearer';
+  tokenType: "Bearer";
 }
 /**
- * Auth helpers available on fastify.auth
+ * Auth helpers exposed on `fastify.auth`.
  *
  * @example
  * ```typescript
- * // In login handler
- * const user = await userRepo.findByEmail(email);
- * if (!user || !await bcrypt.compare(password, user.password)) {
- *   return reply.code(401).send({ error: 'Invalid credentials' });
- * }
- *
  * const tokens = fastify.auth.issueTokens({
  *   id: user._id,
  *   email: user.email,
  *   role: user.role,
  * });
- *
  * return { success: true, ...tokens, user };
  * ```
  */
@@ -2708,41 +1751,110 @@ interface AuthHelpers {
   /** JWT utilities (if configured) */
   jwt: JwtContext | null;
   /**
-   * Issue access + refresh tokens for a user
-   * App calls this after validating credentials
+   * 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
-   */
+  /** Verify a refresh token and return decoded payload. */
   verifyRefreshToken: <T = Record<string, unknown>>(token: string) => T;
 }
-interface ServiceContext {
-  user?: unknown;
-  requestId?: string;
-  select?: string[] | Record<string, 0 | 1>;
-  populate?: string | string[];
-  lean?: boolean;
-}
-interface PresetHook {
-  operation: 'create' | 'update' | 'delete' | 'read' | 'list';
-  phase: 'before' | 'after';
-  handler: (ctx: AnyRecord) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
-  priority?: number;
-}
-interface PresetResult {
-  name: string;
-  /** Preset routes — merged into the resource's `routes` array. */
-  routes?: RouteDefinition[] | ((permissions: ResourcePermissions) => RouteDefinition[]);
-  middlewares?: MiddlewareConfig;
-  schemaOptions?: RouteSchemaOptions;
-  controllerOptions?: Record<string, unknown>;
-  hooks?: PresetHook[];
+/**
+ * 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 {
+  /**
+   * 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>;
+  };
+  /**
+   * Custom authenticator function. Arc calls this for non-public routes.
+   * If not provided and `jwt.secret` is set, uses default `jwtVerify`.
+   */
+  authenticate?: Authenticator;
+  /**
+   * Custom auth failure handler. Customize the 401 response when
+   * authentication fails.
+   */
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  /**
+   * Expose detailed auth error messages in 401 responses. When `false`
+   * (default), returns generic "Authentication required". Decoupled from
+   * log level — set explicitly per environment.
+   */
+  exposeAuthErrors?: boolean;
+  /** Property name to store user on request (default: 'user') */
+  userProperty?: string;
+  /**
+   * Custom token extractor for the built-in JWT auth path. 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,
+   * ```
+   */
+  tokenExtractor?: (request: FastifyRequest) => string | null;
+  /**
+   * 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);
+   * },
+   * ```
+   */
+  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;
 }
-type PresetFunction = (config: ResourceConfig) => PresetResult;
+//#endregion
+//#region src/types/plugins.d.ts
 interface GracefulShutdownOptions {
   timeout?: number;
   onShutdown?: () => Promise<void> | void;
@@ -2762,488 +1874,628 @@ interface HealthCheck {
   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;
+}
+//#endregion
+//#region src/types/utility.d.ts
 /**
- * Auth Plugin Options - Clean, Minimal Configuration
+ * Infer document type from a `DataAdapter` or `ResourceConfig`. Smart
+ * inference that works with multiple sources.
  *
- * Arc provides JWT infrastructure and calls your authenticator.
- * You control ALL authentication logic.
+ * @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
- * // Minimal: just JWT (uses default jwtVerify)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- * }
+ * 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/repository.d.ts
+/**
+ * Discriminated union of pagination result shapes. Narrow on `method`.
  *
- * // With custom authenticator (recommended)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- *   authenticate: async (request, { jwt }) => {
- *     const token = request.headers.authorization?.split(' ')[1];
- *     if (!token) return null;
- *     const decoded = jwt.verify(token);
- *     return userRepo.findById(decoded.id);
- *   },
- * }
+ * 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.
  *
- * // Multi-strategy (JWT + API Key)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- *   authenticate: async (request, { jwt }) => {
- *     // Try API key first (faster)
- *     const apiKey = request.headers['x-api-key'];
- *     if (apiKey) {
- *       const result = await apiKeyService.verify(apiKey);
- *       if (result) return { _id: result.userId, isApiKey: true };
- *     }
- *     // Try JWT
- *     const token = request.headers.authorization?.split(' ')[1];
- *     if (token) {
- *       const decoded = jwt.verify(token);
- *       return userRepo.findById(decoded.id);
- *     }
- *     return null;
- *   },
- *   onFailure: (request, reply) => {
- *     reply.code(401).send({
- *       success: false,
- *       error: 'Authentication required',
- *       message: 'Use Bearer token or X-API-Key header',
- *     });
- *   },
+ * @example
+ * ```ts
+ * const result = await repo.getAll(params);
+ * if (result.method === 'keyset') {
+ *   result.next;     // keyset cursor
+ * } else {
+ *   result.page;     // offset number
  * }
  * ```
  */
-interface AuthPluginOptions {
+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;
+}
+interface AccessControlConfig {
+  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable org filtering. */
+  tenantField: string | false;
+  /** Primary key field name (default: '_id') */
+  idField: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
+   * Falls back to built-in MongoDB-style matching if not provided.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+}
+/** Minimal repository interface for access-controlled fetch operations */
+interface AccessControlRepository {
+  getById(id: string, options?: QueryOptions): Promise<unknown>;
+  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
+}
+declare class AccessControl {
+  private readonly tenantField;
+  private readonly idField;
+  private readonly _adapterMatchesFilter?;
+  /** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
+   *  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
+  private static readonly DANGEROUS_REGEX;
+  /** Forbidden paths that could lead to prototype pollution */
+  private static readonly FORBIDDEN_PATHS;
+  constructor(config: AccessControlConfig);
+  /**
+   * Build filter for single-item operations (get/update/delete)
+   * Combines ID filter with policy/org filters for proper security enforcement
+   */
+  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
+  /**
+   * Check if item matches policy filters (for get/update/delete operations)
+   * Validates that fetched item satisfies all policy constraints
+   *
+   * Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
+   * otherwise falls back to built-in MongoDB-style matching.
+   */
+  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
+  /**
+   * Check org/tenant scope for a document — uses configurable tenantField.
+   *
+   * SECURITY: When org scope is active (orgId present), documents that are
+   * missing the tenant field are DENIED by default. This prevents legacy or
+   * unscoped records from leaking across tenants.
+   */
+  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
+  /** Check ownership for update/delete (ownedByUser preset) */
+  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
+  /**
+   * Fetch a single document with full access control enforcement.
+   * Combines compound DB filter (ID + org + policy) with post-hoc fallback.
+   *
+   * Takes repository as a parameter to avoid coupling.
+   *
+   * Replaces the duplicated pattern in get/update/delete:
+   *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
+   */
+  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * 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)
+   */
+  fetchDetailed<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<FetchResult<TDoc>>;
+  /**
+   * Post-fetch access control validation for items fetched by non-ID queries
+   * (e.g., getBySlug, restore). Applies org scope, policy filters, and
+   * ownership checks — the same guarantees as fetchWithAccessControl.
+   */
+  validateItemAccess(item: AnyRecord | null, req: IRequestContext): boolean;
+  /** Extract typed Arc internal metadata from request */
+  private _meta;
   /**
-   * JWT configuration (optional but recommended)
-   * If provided, jwt utilities are available in authenticator context
+   * Check if a value matches a MongoDB query operator
    */
-  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>;
-  };
+  private matchesOperator;
   /**
-   * Custom authenticator function (recommended)
-   *
-   * Arc calls this for non-public routes.
-   * Return user object to authenticate, null/undefined to reject.
-   *
-   * If not provided and jwt.secret is set, uses default jwtVerify.
+   * Check if item matches a single filter condition
+   * Supports nested paths (e.g., "owner.id", "metadata.status")
    */
-  authenticate?: Authenticator;
+  private matchesFilter;
   /**
-   * Custom auth failure handler
-   * Customize the 401 response when authentication fails
+   * Built-in MongoDB-style policy filter matching.
+   * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
    */
-  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  private defaultMatchesPolicyFilters;
   /**
-   * Expose detailed auth error messages in 401 responses.
-   * When false (default), returns generic "Authentication required".
-   * When true, includes the actual error message for debugging.
-   * Decoupled from log level — set explicitly per environment.
+   * Get nested value from object using dot notation (e.g., "owner.id")
+   * Security: Validates path against forbidden patterns to prevent prototype pollution
    */
-  exposeAuthErrors?: boolean;
+  private getNestedValue;
   /**
-   * Property name to store user on request (default: 'user')
+   * Create a safe RegExp from a string, guarding against ReDoS.
+   * Returns null if the pattern is invalid or dangerous.
    */
-  userProperty?: string;
+  private static safeRegex;
+}
+//#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;
   /**
-   * Custom token extractor for the built-in JWT auth path.
-   * When not provided, defaults to extracting Bearer token from Authorization header.
-   * Use this when tokens are in HttpOnly cookies, custom headers, or query params.
-   *
-   * @example
-   * ```typescript
-   * // Extract from HttpOnly cookie
-   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
-   *
-   * // Extract from custom header
-   * tokenExtractor: (request) => request.headers['x-api-token'] as string ?? null,
-   * ```
+   * What to do when a request contains fields the caller can't write.
+   * Default: `'reject'` — surface the misconfiguration as a 403.
    */
-  tokenExtractor?: (request: FastifyRequest) => string | null;
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
+}
+declare class BodySanitizer {
+  private schemaOptions;
+  private onFieldWriteDenied;
+  constructor(config: BodySanitizerConfig);
   /**
-   * Token revocation check — called after JWT verification succeeds.
-   * Return `true` to reject the token (revoked), `false` to allow.
-   *
-   * Arc provides this primitive — implement your own store (Redis set,
-   * DB lookup, Better Auth session check, etc.)
-   *
-   * **Fail-closed**: if the check throws, the token is treated as revoked.
-   *
-   * @example
-   * ```typescript
-   * // Redis-backed revocation
-   * isRevoked: async (decoded) => {
-   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
-   * },
+   * Strip readonly and system-managed fields from request body.
+   * Prevents clients from overwriting _id, timestamps, __v, etc.
    *
-   * // DB-backed revocation
-   * isRevoked: async (decoded) => {
-   *   const user = await db.user.findById(decoded.id);
-   *   return !user || user.bannedAt != null;
-   * },
-   * ```
+   * Also applies field-level write permissions when the request has
+   * field permission metadata.
    */
-  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
-}
-interface IntrospectionPluginOptions {
-  path?: string;
-  prefix?: string;
-  enabled?: boolean;
-  authRoles?: string[];
+  sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
 }
-interface CrudRouterOptions {
-  /** Route prefix */
-  prefix?: string;
-  /** Permission checks for CRUD operations */
-  permissions?: ResourcePermissions;
-  /** OpenAPI tag for grouping routes */
-  tag?: string;
-  /** JSON schemas for CRUD operations */
-  schemas?: Partial<CrudSchemas>;
-  /** Middlewares for each CRUD operation */
-  middlewares?: MiddlewareConfig;
-  /** Additional custom routes (from presets or user-defined) */
-  additionalRoutes?: AdditionalRoute[];
-  /** Disable all default CRUD routes */
-  disableDefaultRoutes?: boolean;
-  /** Disable specific CRUD routes */
-  disabledRoutes?: CrudRouteKey[];
-  /** Functional pipeline (guard/transform/intercept) */
-  pipe?: PipelineConfig;
-  /** Resource name for lifecycle hooks */
-  resourceName?: string;
-  /** Schema generation options */
+//#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-level permissions (visibility, writability per role) */
-  fields?: FieldPermissionMap;
-  /** HTTP method for update routes. Default: 'PATCH' */
-  updateMethod?: 'PUT' | 'PATCH' | 'both';
+  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable. */
+  tenantField?: string | false;
+}
+declare class QueryResolver {
+  private queryParser;
+  private maxLimit;
+  private defaultLimit;
+  private defaultSort;
+  private schemaOptions;
+  private tenantField;
+  constructor(config?: QueryResolverConfig);
   /**
-   * Per-resource rate limiting.
-   * Requires `@fastify/rate-limit` to be registered on the Fastify instance.
-   * Set to `false` to disable rate limiting for this resource.
+   * Resolve a request into parsed query options -- ONE parse per request.
+   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
    */
-  rateLimit?: RateLimitConfig | false;
-  /** PreHandler guards applied to every route (CRUD + custom + preset). */
-  routeGuards?: RouteHandlerMethod[];
-}
-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[];
+  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
+  /**
+   * Sanitize select — preserves the input format (string, array, or object).
+   * This is critical for db-agnostic support: MongoKit returns object projections,
+   * Mongoose uses space-separated strings, SQL adapters may use arrays.
+   */
+  private sanitizeSelectAny;
+  /** Sanitize populate fields */
+  private sanitizePopulate;
+  /** Sanitize advanced populate options against allowedPopulate */
+  private sanitizePopulateOptions;
+  /**
+   * Sanitize lookup/join options.
+   * If schemaOptions.query.allowedLookups is set, only those collections are allowed.
+   * Validates lookup structure to prevent injection.
+   */
+  private sanitizeLookups;
+  /** Get blocked fields from schema options */
+  private getBlockedFields;
 }
-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")[];
-  };
+//#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;
   /**
-   * v2.8 declarative actions metadata — populated from `ResourceConfig.actions`.
+   * 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.
    *
-   * Consumed by OpenAPI generation (renders `POST /:id/action` with a
-   * discriminated body schema) and MCP tool generation.
+   * Set explicitly to override the repo's setting (e.g. `'_id'` to opt out
+   * of native pass-through and force the slug-translation path).
    *
-   * Added in 2.8.1.
+   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
    */
-  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>;
-    };
-  }>;
+  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;
+  };
   /**
-   * 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`.
+   * Policy for requests that include fields the caller can't write.
    *
-   * Added in 2.8.1 — previously not surfaced to downstream consumers,
-   * causing OpenAPI to mark action endpoints as public when runtime required auth.
+   * - `'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.
    */
-  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;
-}
-interface EventDefinition {
-  name: string;
-  /** Optional handler — events are published via fastify.events.publish(), not invoked through resource definitions */
-  handler?: (data: unknown) => Promise<void> | void;
-  schema?: Record<string, unknown>;
-  description?: string;
-}
-interface ConfigError {
-  field: string;
-  message: string;
-  code?: string;
-}
-interface ValidationResult$1 {
-  valid: boolean;
-  errors: ConfigError[];
-}
-interface ValidateOptions {
-  strict?: boolean;
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
 /**
- * Infer document type from DataAdapter or ResourceConfig
- */
-type InferDocType<T> = T extends DataAdapter<infer D> ? D : T extends ResourceConfig<infer D> ? D : never;
-/**
- * Infer document type from a DataAdapter.
- * Falls back to `unknown` (not `never`) — safe for generic constraints.
- *
- * @example
- * ```typescript
- * const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
- * type ProductDoc = InferAdapterDoc<typeof adapter>;
- * // ProductDoc = the document type inferred from the adapter
- * ```
- */
-type InferAdapterDoc<A> = A extends DataAdapter<infer D> ? D : unknown;
-type InferResourceDoc<T> = T extends ResourceConfig<infer D> ? D : never;
-type TypedResourceConfig<TDoc> = ResourceConfig<TDoc>;
-type TypedController<TDoc> = IController<TDoc>;
-type TypedRepository<TDoc> = CrudRepository<TDoc>;
-//#endregion
-//#region src/adapters/interface.d.ts
-/**
- * Minimal structural repository shape for flexible adapter compatibility.
- *
- * `RepositoryLike` is the **loose** variant of `CrudRepository<TDoc>` — it
- * uses `unknown` for document payloads so any object with the right method
- * names satisfies it without type assertions. Prefer `CrudRepository<TDoc>`
- * for kits you own; use `RepositoryLike` when wrapping third-party repos.
- *
- * Both interfaces declare the same tiered capabilities:
+ * Framework-agnostic base controller implementing IController.
  *
- * - **Required** — `getAll`, `getById`, `create`, `update`, `delete`
- * - **Recommended** — `getOne` / `getByQuery` (used by AccessControl for
- *   compound filters like `idField + orgId + policy`)
- * - **Optional** — feature-detected at runtime by presets and the
- *   BaseController. Declare only what your DB supports.
+ * Composes AccessControl, BodySanitizer, and QueryResolver for clean
+ * separation of concerns. CRUD methods delegate directly to these
+ * composed classes — no intermediate wrapper methods.
  *
- * See [CrudRepository](../types/repository.ts) for full prose-level docs
- * on each method and the design rationale behind the tiering.
+ * @template TDoc - The document type
+ * @template TRepository - The repository type (defaults to RepositoryLike)
  */
-interface RepositoryLike {
+declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
+  protected repository: TRepository;
+  protected schemaOptions: RouteSchemaOptions;
+  protected queryParser: QueryParserInterface;
+  protected maxLimit: number;
+  protected defaultLimit: number;
+  protected defaultSort: string;
+  protected resourceName?: string;
+  protected tenantField: string | false;
+  protected idField: string;
+  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
+  readonly accessControl: AccessControl;
+  /** Composable body sanitization (field permissions, system fields) */
+  readonly bodySanitizer: BodySanitizer;
+  /** Composable query resolution (parsing, pagination, sort, select/populate) */
+  readonly queryResolver: QueryResolver;
+  private _matchesFilter?;
+  private _presetFields;
+  private _cacheConfig?;
+  constructor(repository: TRepository, options?: BaseControllerOptions);
+  /**
+   * Get the tenant field name if multi-tenant scoping is enabled.
+   * Returns `undefined` when `tenantField` is `false` (platform-universal mode).
+   *
+   * Use this in subclass overrides instead of accessing `this.tenantField` directly
+   * to avoid TypeScript indexing errors with `string | false`.
+   */
+  protected getTenantField(): string | undefined;
+  /** Extract typed Arc internal metadata from request */
+  private meta;
+  /** Get hook system from request context (instance-scoped) */
+  private getHooks;
   /**
-   * The repository's native primary key field. When set, arc's BaseController
-   * passes route params through to `update()`/`delete()`/`restore()` calls
-   * unchanged instead of translating them to `_id`.
+   * 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`.
    *
-   * Match this to your `defineResource({ idField })` for repositories that
-   * natively look up by a custom field (e.g. mongokit's
-   * `new Repository(Model, [], {}, { idField: 'id' })`). Without it, arc
-   * will try to translate route ids → fetched doc's `_id`, which 404s on
-   * repos that don't key on `_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.
    *
-   * Defaults to `'_id'` (Mongo). Kits that always use `_id` may omit it.
+   * 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`.
    */
-  readonly idField?: string;
-  getAll(params?: PaginationParams, options?: QueryOptions): Promise<unknown>;
-  getById(id: string, options?: QueryOptions): Promise<unknown>;
-  create(data: unknown, options?: WriteOptions): Promise<unknown>;
-  update(id: string, data: unknown, options?: WriteOptions): Promise<unknown>;
-  /**
-   * Delete by primary key. Pass `{ mode: 'hard' }` to bypass soft-delete
-   * interception (required by arc's hard-delete flow — `?hard=true` on
-   * the DELETE route forwards this option).
-   */
-  delete(id: string, options?: DeleteOptions): Promise<unknown>;
-  /**
-   * Find a single doc by compound filter. Used by AccessControl for
-   * `idField + org + policy` scoping. Without this, arc falls back to
-   * `getById` + post-fetch security checks (slower, and 404s on custom
-   * idFields that live outside the user's scope).
-   */
-  getOne?(filter: Record<string, unknown>, options?: QueryOptions): Promise<unknown>;
-  /** Alias many kits expose alongside `getOne`. Arc checks both. */
-  getByQuery?(filter: Record<string, unknown>, options?: QueryOptions): Promise<unknown>;
-  count?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<number>;
-  exists?(filter: Record<string, unknown>, options?: QueryOptions): Promise<boolean | {
-    _id: unknown;
-  } | null>;
-  distinct?<T = unknown>(field: string, filter?: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
-  findAll?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<unknown[]>;
-  getOrCreate?(filter: Record<string, unknown>, data: unknown, options?: WriteOptions): Promise<unknown>;
-  createMany?(items: unknown[], options?: WriteOptions): Promise<unknown[]>;
-  updateMany?(filter: Record<string, unknown>, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
-  deleteMany?(filter: Record<string, unknown>, options?: DeleteOptions): Promise<DeleteManyResult>;
-  bulkWrite?: unknown;
-  restore?(id: string, options?: QueryOptions): Promise<unknown>;
-  getDeleted?(params?: PaginationParams, options?: QueryOptions): Promise<PaginationResult<unknown> | unknown[]>;
-  aggregate?: unknown;
-  aggregatePaginate?: unknown;
-  withTransaction?<T>(callback: (session: RepositorySession) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
-  getBySlug?(slug: string, options?: QueryOptions): Promise<unknown>;
-  getTree?(options?: QueryOptions): Promise<unknown>;
-  getChildren?(parentId: string, options?: QueryOptions): Promise<unknown>;
-  [key: string]: unknown;
-}
-interface DataAdapter<TDoc = unknown> {
+  private resolveRepoId;
   /**
-   * Repository implementing CRUD operations. Accepts the typed
-   * `CrudRepository<TDoc>` or the loose `RepositoryLike` — arc checks
-   * capabilities at runtime via feature detection.
+   * 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.
    */
-  repository: CrudRepository<TDoc> | RepositoryLike;
-  /** Adapter identifier for introspection */
-  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
-  /** Human-readable name */
-  readonly name: string;
+  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[]>>;
   /**
-   * Generate OpenAPI schemas for CRUD operations
+   * Build a tenant-scoped filter for bulk update/delete.
    *
-   * This method allows each adapter to generate schemas specific to its ORM/database.
-   * For example, Mongoose adapter can use mongokit to generate schemas from Mongoose models.
+   * 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.
    *
-   * @param options - Schema generation options (field rules, populate settings, etc.)
-   * @param context - Resource-level context: idField (for params schema), resourceName.
-   *                  Adapters should honor `context.idField` when producing the params
-   *                  schema — e.g. skip the ObjectId pattern when idField is a custom
-   *                  string field. Backwards compatible: legacy adapters ignoring the
-   *                  context still work because Arc strips the mismatched pattern as
-   *                  a safety net.
-   * @returns OpenAPI schemas for CRUD operations or null if not supported
+   * Returns the merged filter, or `null` when access must be denied.
    */
-  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> | ValidationResult;
-  /** Health check for database connection */
-  healthCheck?(): Promise<boolean>;
+  private buildBulkFilter;
   /**
-   * Custom filter matching for policy enforcement.
-   * Falls back to built-in MongoDB-style matching if not provided.
-   * Override this for SQL adapters or non-MongoDB query operators.
+   * 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.
    */
-  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
-  /** Close/cleanup resources */
-  close?(): Promise<void>;
-}
-/**
- * Context passed to `adapter.generateSchemas()` so adapters can shape the
- * output to match resource-level configuration (idField overrides, etc).
- * All fields are optional — adapters are free to ignore this argument, in
- * which case Arc applies safety-net normalization to the generated schemas.
- */
-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 {
-  valid: boolean;
-  errors?: Array<{
-    field: string;
-    message: string;
-    code?: string;
-  }>;
+  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 AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
 //#endregion
-export { PresetFunction as $, DeleteOptions as $t, EventsDecorator as A, beforeCreate as An, BaseController as At, InferResourceDoc as B, FastifyHandler as Bt, ConfigError as C, HookPhase as Cn, TypedResourceConfig as Ct, CrudRouterOptions as D, afterCreate as Dn, ValidationResult$1 as Dt, CrudRouteKey as E, HookSystemOptions as En, ValidateOptions as Et, GracefulShutdownOptions as F, BodySanitizerConfig as Ft, LookupOption as G, RegisterOptions as Gt, IntrospectionPluginOptions as H, IControllerResponse as Ht, HealthCheck as I, AccessControl as It, ObjectId as J, defineResource as Jt, MiddlewareConfig as K, ResourceRegistry as Kt, HealthOptions as L, AccessControlConfig as Lt, FastifyWithAuth as M, beforeUpdate as Mn, QueryResolver as Mt, FastifyWithDecorators as N, createHookSystem as Nn, QueryResolverConfig as Nt, CrudSchemas as O, afterDelete as On, envelope as Ot, FieldRule as P, defineHook as Pn, BodySanitizer as Pt, PopulateOption as Q, DeleteManyResult as Qt, InferAdapterDoc as R, ControllerHandler as Rt, AuthenticatorContext as S, HookOperation as Sn, TypedRepository as St, CrudController as T, HookSystem as Tn, UserOrganization as Tt, JWTPayload as U, IRequestContext as Ut, IntrospectionData as V, IController as Vt, JwtContext as W, RouteHandler as Wt, OwnershipCheck as X, BulkWriteResult as Xt, OpenApiSchemas as Y, BulkWriteOperation as Yt, ParsedQuery as Z, CrudRepository as Zt, ArcInternalMetadata as _, PipelineStep as _n, RouteMcpConfig as _t, RelationMetadata as a, PaginationParams as an, RegistryStats as at, AuthPluginOptions as b, HookContext as bn, TokenPair as bt, ValidationResult as c, RepositorySession as cn, RequestWithExtras as ct, ActionHandlerFn as d, Guard as dn, ResourceHookContext as dt, DeleteResult as en, PresetHook as et, ActionsMap as f, Interceptor as fn, ResourceHooks as ft, ArcDecorator as g, PipelineContext as gn, RouteHandlerMethod$1 as gt, ApiResponse as h, PipelineConfig as hn, RouteDefinition as ht, FieldMetadata as i, PaginatedResult as in, RegistryEntry as it, FastifyRequestExtras as j, beforeDelete as jn, BaseControllerOptions as jt, EventDefinition as k, afterUpdate as kn, getUserId as kt, ActionDefinition as l, UpdateManyResult as ln, ResourceCacheConfig as lt, AnyRecord as m, OperationFilter as mn, ResourcePermissions as mt, AdapterSchemaContext as n, KeysetPaginatedResult as nn, QueryParserInterface as nt, RepositoryLike as o, PaginationResult as on, RequestContext as ot, AdditionalRoute as p, NextFunction as pn, ResourceMetadata as pt, MiddlewareHandler as q, ResourceDefinition as qt, DataAdapter as r, OffsetPaginatedResult as rn, RateLimitConfig as rt, SchemaMetadata as s, QueryOptions as sn, RequestIdOptions as st, AdapterFactory as t, InferDoc as tn, PresetResult as tt, ActionEntry as u, WriteOptions as un, ResourceConfig as ut, ArcRequest as v, Transform as vn, RouteSchemaOptions as vt, ControllerQueryOptions as w, HookRegistration as wn, UserLike as wt, Authenticator as x, HookHandler as xn, TypedController as xt, AuthHelpers as y, DefineHookOptions as yn, ServiceContext as yt, InferDocType as z, ControllerLike as zt };
+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 };