@classytic/arc 2.10.3 → 2.11.0

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

@@ -1,111 +1,151 @@
-import { r as RequestScope } from "./types-BD85MlEK.mjs";
-import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-Lo1VUDpt.mjs";
-import { n as DomainEvent } from "./EventTransport-CUw5NNWe.mjs";
+import { a as QueryCacheConfig } from "./QueryCache-DOBNHBE0.mjs";
+import { r as RequestScope } from "./types-tgR4Pt8F.mjs";
+import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-C8Y0XLAu.mjs";
+import { n as DomainEvent } from "./EventTransport-CfVEGaEl.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
-import * as _$_classytic_repo_core_repository0 from "@classytic/repo-core/repository";
-import { MinimalRepo, QueryOptions, StandardRepo } from "@classytic/repo-core/repository";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
+import { MinimalRepo, QueryOptions, StandardRepo } from "@classytic/repo-core/repository";
+import { FieldRule, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 
-//#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>;
-}
+//#region src/adapters/interface.d.ts
 /**
- * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
- * instead of `(req as any).user`.
+ * Arc's structural repository contract.
  *
- * @example
- * ```typescript
- * import type { ArcRequest } from '@classytic/arc';
+ * Defined as `MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>` — the
+ * repo-core 5-method floor (required) plus every other `StandardRepo`
+ * method (optional). This compound is the single shape arc accepts
+ * across its entire API surface:
  *
- * handler: async (req: ArcRequest, reply) => {
- *   req.user?.id;                    // typed
- *   req.scope.organizationId;        // typed (when member)
- *   req.signal;                      // AbortSignal (Fastify 5)
- * }
+ *   - `defineResource({ adapter: { repository, ... } })`
+ *   - `auditPlugin({ repository })`, `idempotencyPlugin({ repository })`
+ *   - `new EventOutbox({ repository, transport })`
+ *
+ * **Why compound and not `StandardRepo` alone:** forcing every kit to
+ * implement the full `StandardRepo` surface would break kits with
+ * partial capabilities (sqlitekit has no aggregation, prismakit has no
+ * native atomic CAS the same way). Feature-detection at the arc layer
+ * lets each kit declare only what it implements; arc's audit / outbox /
+ * idempotency plugins check `typeof repo.method === 'function'` at
+ * construction and throw with the list of missing primitives if a
+ * required subset isn't covered. See the store-backing contract matrix
+ * in the file header.
+ *
+ * **Why compound and not `MinimalRepo` alone:** arc's internal plugins
+ * still need the `StandardRepo` type info at call sites where they use
+ * optionals like `findOneAndUpdate` / `deleteMany`. Without the
+ * `Partial<StandardRepo>` half, every access would require
+ * `as StandardRepo` casts and the feature-detect pattern would be
+ * runtime-only with no type-level backing.
+ *
+ * **Hosts importing repo-core directly.** `MinimalRepo` and
+ * `StandardRepo` are repo-core's contract — hosts that want to reference
+ * them by name should `import type { MinimalRepo, StandardRepo } from
+ * '@classytic/repo-core/repository'` rather than go through arc. Arc
+ * doesn't re-export them from its root barrel on purpose: creating a
+ * second source of truth would force arc to either drift from repo-core
+ * or force-sync every time the contract iterates.
+ *
+ * ```ts
+ * const adapter: DataAdapter<Product> = {
+ *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
+ *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
+ *   name: 'products',
+ * };
+ * defineResource({ adapter, ... });
  * ```
  */
-type ArcRequest = FastifyRequest & {
-  scope: RequestScope;
-  user: Record<string, unknown> | undefined;
-  signal: AbortSignal;
-};
+type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
+interface DataAdapter<TDoc = unknown> {
+  /**
+   * Repository implementing CRUD operations. Any value that satisfies
+   * `RepositoryLike<TDoc>` — which includes `StandardRepo<TDoc>` (all
+   * methods implemented), `MinimalRepo<TDoc>` (5-method floor), or
+   * anything in between a kit declares. Arc feature-detects optional
+   * methods at runtime — kits only declare what they support.
+   */
+  repository: RepositoryLike<TDoc>;
+  /** Adapter identifier for introspection */
+  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
+  /** Human-readable name */
+  readonly name: string;
+  /**
+   * Generate OpenAPI schemas for CRUD operations. Each adapter produces
+   * schemas appropriate to its ORM/database (mongoose kits use mongokit's
+   * `buildCrudSchemasFromModel`; SQL kits introspect columns).
+   *
+   * @param options - Schema generation options (field rules, populate hints)
+   * @param context - Resource-level context (idField for params schema, name for logs).
+   *                  Adapters should honor `context.idField` when producing the params
+   *                  schema (e.g., skip the ObjectId pattern when idField is a custom
+   *                  string field).
+   */
+  generateSchemas?(options?: RouteSchemaOptions, context?: AdapterSchemaContext): OpenApiSchemas | Record<string, unknown> | null;
+  /** Extract schema metadata for OpenAPI/introspection. */
+  getSchemaMetadata?(): SchemaMetadata | null;
+  /** Validate data against schema before persistence. */
+  validate?(data: unknown): Promise<ValidationResult$1> | ValidationResult$1;
+  /** Health check for database connection. */
+  healthCheck?(): Promise<boolean>;
+  /**
+   * Custom filter matching for in-memory policy enforcement. Falls back
+   * to arc's built-in shallow matcher when omitted. Override for SQL
+   * adapters, non-Mongo operators, or kits that compile Filter IR.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close / cleanup resources. */
+  close?(): Promise<void>;
+}
 /**
- * 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 }
- * }
- * ```
+ * 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.
  */
-declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
-  success: true;
-  data: T;
-  [key: string]: unknown;
-};
+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/hooks/HookSystem.d.ts
 type HookPhase = "before" | "around" | "after";
@@ -358,1052 +398,1818 @@ 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;
-  };
+//#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;
 }
-/**
- * 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>;
+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;
   /**
-   * Advanced populate options (Mongoose-compatible). When set, takes
-   * precedence over simple `populate`.
+   * 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.
    */
-  populateOptions?: PopulateOption[];
+  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?;
   /**
-   * Lookup/join options (database-agnostic). MongoKit maps these to
-   * `$lookup`; future SQL adapters would map to JOINs.
+   * One-shot latch for the "adapter didn't supply matchesFilter, in-memory
+   * policy-filter re-check is skipped" warning. The primary fetch path
+   * (`getOne(compoundFilter)`) already applied filters at the DB layer;
+   * this warn only fires when `validateItemAccess` runs and the adapter
+   * hasn't provided a native matcher for the post-hoc re-check.
+   */
+  private _warnedNoMatcher;
+  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 a post-fetch item matches the request's `_policyFilters`.
    *
-   * @example
-   * URL: ?lookup[category][from]=categories&lookup[category][localField]=categorySlug&lookup[category][foreignField]=slug
+   * **When this runs:** only on paths where the primary fetch path did NOT
+   * apply policy filters at the DB layer — notably `validateItemAccess`
+   * (used by `getBySlug` and cache revalidation). The main `fetchDetailed`
+   * path builds a compound filter (`buildIdFilter`) and passes it to
+   * `repository.getOne(compoundFilter)`, so the DB has already enforced
+   * the filter and an in-memory re-check would be redundant.
+   *
+   * **Evaluation order (fail-closed):**
+   * 1. No `_policyFilters` set → `true` (nothing to enforce).
+   * 2. Adapter supplied `matchesFilter` → delegate to it verbatim. Adapters
+   *    are expected to handle every filter shape the host emits
+   *    (mongokit/sqlitekit evaluate at the DB layer; Prisma/custom engines
+   *    can wrap their own predicate engine).
+   * 3. No adapter matcher → fall back to `simpleEqualityMatcher` — arc's
+   *    built-in flat-key equality helper. This is defense-in-depth for the
+   *    common case: arc's own permission helpers emit flat filters
+   *    (`{userId: …}`, `{organizationId: …}`), which this matcher evaluates
+   *    correctly. Operator-shaped filters (`$in`, `$ne`, `$regex`, `$and`,
+   *    `$or`) are **rejected** (the matcher returns `false`) — fail-closed
+   *    rather than fail-open. A one-shot warn flags the gap so adapter
+   *    authors can wire a richer matcher.
+   *
+   * Arc deliberately does NOT ship a full MongoDB-syntax matcher:
+   * re-implementing Mongo in JS was dead code for mongokit users (the DB
+   * did it) and silently wrong for non-Mongo adapters. The flat-equality
+   * fallback is small (~20 LOC), correct in both dialects, and closes the
+   * previous `getBySlug`-style policy-bypass path.
    */
-  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>;
+  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
+  /**
+   * Emit a one-shot warn when policy filters contain operators (`$in`,
+   * `$ne`, `$regex`, etc.) and no `DataAdapter.matchesFilter` is wired —
+   * arc's flat-equality fallback fail-closes on operators, so the host
+   * sees 404s on docs that should match. Latched on `_warnedNoMatcher`
+   * so subsequent requests stay quiet.
+   */
+  private _warnNoMatcher;
+  /**
+   * 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;
 }
+//#endregion
+//#region src/core/BodySanitizer.d.ts
 /**
- * Mongoose-compatible populate option for advanced field selection.
+ * Policy for handling fields the caller lacks write permission for.
  *
- * @example
- * ```typescript
- * // URL: ?populate[author][select]=name,email
- * // Generates: { path: 'author', select: 'name email' }
- * ```
+ * - `'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.
  */
-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;
+type FieldWriteDenialPolicy = "reject" | "strip";
+interface BodySanitizerConfig {
+  /** Schema options for field sanitization */
+  schemaOptions: RouteSchemaOptions;
+  /**
+   * What to do when a request contains fields the caller can't write.
+   * Default: `'reject'` — surface the misconfiguration as a 403.
+   */
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
-/**
- * Parsed query result from QueryParser. The index signature lets custom
- * parsers (MongoKit, PrismaKit) add fields without breaking Arc's types.
- */
-interface ParsedQuery {
-  filters?: Record<string, unknown>;
-  limit?: number;
-  sort?: string | Record<string, 1 | -1>;
-  populate?: string | string[] | Record<string, unknown>;
-  populateOptions?: PopulateOption[];
-  lookups?: LookupOption[];
-  search?: string;
-  page?: number;
-  after?: string;
-  select?: string | string[] | Record<string, 0 | 1>;
-  [key: string]: unknown;
+declare class BodySanitizer {
+  private schemaOptions;
+  private onFieldWriteDenied;
+  constructor(config: BodySanitizerConfig);
+  /**
+   * Strip readonly and system-managed fields from request body.
+   * Prevents clients from overwriting _id, timestamps, __v, etc.
+   *
+   * Also applies field-level write permissions when the request has
+   * field permission metadata.
+   */
+  sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
 }
-/**
- * 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[];
-  };
+//#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;
   /**
-   * Optional: Allowed filter fields whitelist. MCP auto-derives
-   * `filterableFields` from this if `schemaOptions.filterableFields`
-   * is not explicitly configured.
+   * Default sort applied when the request doesn't specify one.
+   *   - `string` — e.g. `'-createdAt'` (Mongo convention: leading `-` = DESC).
+   *   - `false` — disable the default; resolved query has no `sort` clause.
+   *     Use for SQL kits without a `createdAt` column.
+   * Defaults to `'-createdAt'` for back-compat with mongokit consumers.
    */
-  allowedFilterFields?: readonly string[];
+  defaultSort?: string | false;
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
+  /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable. */
+  tenantField?: string | false;
+}
+declare class QueryResolver {
+  private queryParser;
+  private maxLimit;
+  private defaultLimit;
+  /** `undefined` means "no default sort" (caller passed `false`). */
+  private defaultSort;
+  private schemaOptions;
+  private tenantField;
+  constructor(config?: QueryResolverConfig);
   /**
-   * 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.
+   * Resolve a request into parsed query options -- ONE parse per request.
+   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
    */
-  allowedOperators?: readonly string[];
+  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
   /**
-   * Optional: Allowed sort fields whitelist. Used by MCP to describe
-   * available sort options in list-tool descriptions.
+   * 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.
    */
-  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;
+  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/pipeline/types.d.ts
+//#region src/core/BaseCrudController.d.ts
 /**
- * Pipeline context passed to guards, transforms, and interceptors.
- * Extends IRequestContext with pipeline-specific metadata.
+ * Union of every return shape repo-core's `MinimalRepo.getAll()` is
+ * contractually allowed to produce. See repo-core's `MinimalRepo.getAll`
+ * docstring for the three-way split:
+ *
+ * - `OffsetPaginationResult<TDoc>` — `page` param drives pagination.
+ * - `KeysetPaginationResult<TDoc>` — `sort` + optional `after` drives pagination.
+ * - `TDoc[]` — raw array when neither drives pagination.
+ *
+ * Arc passes the kit's response verbatim; consumers narrow on shape.
  */
-interface PipelineContext extends IRequestContext {
-  /** Resource name being accessed */
-  resource: string;
-  /** CRUD operation being performed */
-  operation: "list" | "get" | "create" | "update" | "delete" | string;
-}
+type ListResult<TDoc> = OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[];
 /**
- * Which operations a pipeline step applies to.
- * If omitted, applies to ALL operations.
+ * Controller-shape surface that the `Arc*Result` utilities read return
+ * types from. Internal — exported so the utility types can reference
+ * the minimal shape without a circular dependency on the full
+ * `BaseCrudController` / `BaseController` declarations.
  */
-type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
+type ArcControllerLike = {
+  list: (...args: any[]) => unknown;
+  get: (...args: any[]) => unknown;
+  create: (...args: any[]) => unknown;
+  update: (...args: any[]) => unknown;
+  delete: (...args: any[]) => unknown;
+};
 /**
- * Guard — boolean check that short-circuits on failure.
- * Return true to proceed, throw to deny.
- */
-interface Guard {
-  readonly _type: "guard";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext): boolean | Promise<boolean>;
-}
-/**
- * Transform — modifies request data before the handler.
- * Returns modified context (or mutates in place).
- */
-interface Transform {
-  readonly _type: "transform";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext): PipelineContext | undefined | Promise<PipelineContext | undefined>;
-}
-/**
- * Next function passed to interceptors — calls the handler (or next interceptor).
- */
-type NextFunction = () => Promise<IControllerResponse<unknown>>;
-/**
- * Intercept — wraps handler execution (before + after pattern).
- */
-interface Interceptor {
-  readonly _type: "interceptor";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
-}
-type PipelineStep = Guard | Transform | Interceptor;
-/**
- * Pipeline configuration — can be a flat array or per-operation map.
- */
-type PipelineConfig = PipelineStep[] | {
-  list?: PipelineStep[];
-  get?: PipelineStep[];
-  create?: PipelineStep[];
-  update?: PipelineStep[];
-  delete?: PipelineStep[];
-  [operation: string]: PipelineStep[] | undefined;
-};
-//#endregion
-//#region src/adapters/interface.d.ts
-/**
- * Arc's structural repository contract: the repo-core minimum plus any
- * standard-repo methods a given kit implements. All optional methods are
- * feature-detected at call sites — arc never assumes capabilities it
- * hasn't probed.
+ * Return type of the controller's `list` method.
  *
+ * @example
  * ```ts
- * const adapter: DataAdapter<Product> = {
- *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
- *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
- *   name: 'products',
- * };
- * defineResource({ adapter, ... });
+ * class ProductController extends BaseController<Product> {
+ *   async list(ctx: IRequestContext): ArcListResult<this> {
+ *     // return shape inferred from BaseController.list — no need to
+ *     // restate `Promise<IControllerResponse<ListResult<Product>>>`
+ *     return super.list(ctx);
+ *   }
+ * }
  * ```
  */
-type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
-interface DataAdapter<TDoc = unknown> {
+type ArcListResult<TCtrl extends ArcControllerLike> = ReturnType<TCtrl["list"]>;
+/** Return type of the controller's `get` method. See {@link ArcListResult}. */
+type ArcGetResult<TCtrl extends ArcControllerLike> = ReturnType<TCtrl["get"]>;
+/** Return type of the controller's `create` method. See {@link ArcListResult}. */
+type ArcCreateResult<TCtrl extends ArcControllerLike> = ReturnType<TCtrl["create"]>;
+/** Return type of the controller's `update` method. See {@link ArcListResult}. */
+type ArcUpdateResult<TCtrl extends ArcControllerLike> = ReturnType<TCtrl["update"]>;
+/** Return type of the controller's `delete` method. See {@link ArcListResult}. */
+type ArcDeleteResult<TCtrl extends ArcControllerLike> = ReturnType<TCtrl["delete"]>;
+interface BaseControllerOptions {
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
   /**
-   * 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.
+   * Query parser instance.
+   * Default: Arc built-in query parser (adapter-agnostic).
+   * Swap in MongoKit QueryParser, pgkit parser, etc.
    */
-  repository: StandardRepo<TDoc> | RepositoryLike<TDoc>;
-  /** Adapter identifier for introspection */
-  readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
-  /** Human-readable name */
-  readonly name: string;
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
   /**
-   * 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).
+   * Default sort applied when the request doesn't specify one.
+   *   - `string` (default: `'-createdAt'`) — Mongo `-field` DESC convention.
+   *   - `false` — disable the default sort entirely (SQL/Drizzle resources
+   *     without a `createdAt` column).
    */
-  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>;
+  defaultSort?: string | false;
+  /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
+  resourceName?: string;
   /**
-   * 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.
+   * 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'). Auto-derives from the repo's
+   * own `idField` when unset.
+   */
+  idField?: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
    */
   matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
-  /** Close / cleanup resources. */
-  close?(): Promise<void>;
+  /** Cache configuration for the resource */
+  cache?: ResourceCacheConfig;
+  /** Internal preset fields map (slug, tree, etc.) */
+  presetFields?: {
+    slugField?: string;
+    parentField?: string;
+  };
+  /**
+   * Policy for requests that include fields the caller can't write.
+   * - `'reject'` (default): 403 with denied field names.
+   * - `'strip'`: legacy silent-drop.
+   */
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
 /**
- * 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.
+ * Framework-agnostic CRUD controller implementing IController.
+ *
+ * Composes AccessControl, BodySanitizer, and QueryResolver. All shared
+ * state and helpers are `protected` so the preset mixins (SoftDelete,
+ * Tree, Slug, Bulk) can extend cleanly.
+ *
+ * @template TDoc - The document type.
+ * @template TRepository - The repository type (defaults to RepositoryLike).
  */
-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;
+declare class BaseCrudController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
+  protected repository: TRepository;
+  protected schemaOptions: RouteSchemaOptions;
+  protected queryParser: QueryParserInterface;
+  protected maxLimit: number;
+  protected defaultLimit: number;
+  /** `undefined` means "no default sort" (caller passed `false`). */
+  protected defaultSort: string | undefined;
+  protected resourceName?: string;
+  protected tenantField: string | false;
+  protected idField: string;
+  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
+  readonly accessControl: AccessControl;
+  /** Composable body sanitization (field permissions, system fields) */
+  readonly bodySanitizer: BodySanitizer;
+  /**
+   * Composable query resolution (parsing, pagination, sort, select/populate).
+   *
+   * Not `readonly` — `setQueryParser()` rebuilds this resolver to swap in a
+   * different parser (e.g. mongokit's `QueryParser`). `defineResource` calls
+   * it automatically when a resource supplies both `controller` and
+   * `queryParser`.
+   */
+  queryResolver: QueryResolver;
+  protected _matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  protected _presetFields: {
+    slugField?: string;
+    parentField?: string;
+  };
+  protected _cacheConfig?: ResourceCacheConfig;
+  constructor(repository: TRepository, options?: BaseControllerOptions);
+  /**
+   * Swap the controller's query parser. Rebuilds the internal `QueryResolver`
+   * with the new parser while preserving every other config.
+   *
+   * Closes the v2.10.9 gap where `defineResource({ controller, queryParser })`
+   * forwarded the parser only to auto-constructed controllers; user-supplied
+   * controllers kept their default `ArcQueryParser`. `defineResource` calls
+   * this via duck-typing when both `controller` and `queryParser` are
+   * supplied — controllers that don't implement `setQueryParser` are left
+   * untouched.
+   *
+   * Idempotent + safe to call repeatedly. Does NOT touch `maxLimit` or
+   * `defaultLimit` — those are construction-time decisions.
+   */
+  setQueryParser(queryParser: QueryParserInterface): void;
+  /**
+   * Get the tenant field name if multi-tenant scoping is enabled.
+   * Returns `undefined` when `tenantField` is `false`.
+   */
+  protected getTenantField(): string | undefined;
+  /**
+   * Build top-level tenant options to thread into the repository call.
+   *
+   * Plugin-scoped repos (mongokit's `multiTenantPlugin`) read tenant scope
+   * from the TOP of the operation context — `context.organizationId`, not
+   * `context.data.organizationId`. Without this stamping, a tenant-scoped
+   * repo throws "Missing 'organizationId' in context" even when arc has
+   * injected the tenant into the request body.
+   *
+   * Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
+   * requests, `{}` otherwise. Merges multi-field tenancy from
+   * `_tenantFields` (populated by `multiTenantPreset`).
+   */
+  protected tenantRepoOptions(req: IRequestContext): AnyRecord;
+  /** Extract typed Arc internal metadata from request */
+  protected meta(req: IRequestContext): ArcInternalMetadata | undefined;
+  /** Get hook system from request context (instance-scoped) */
+  protected getHooks(req: IRequestContext): HookSystem | null;
+  /**
+   * Resolve the repository primary key for mutation calls.
+   *
+   * When the resource declares a custom `idField` (slug, jobId, UUID), the
+   * default behavior is to translate the route id → the fetched doc's `_id`
+   * because most Mongo repositories key mutation methods off `_id`.
+   *
+   * Exception: if the repo exposes a matching `idField` property (e.g.
+   * MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
+   * repo handles lookup itself — pass the route id through unchanged.
+   */
+  protected resolveRepoId(id: string, existing: AnyRecord | null): string;
+  /**
+   * Centralized 404 response builder. Maps the denial reason from
+   * `fetchDetailed()` into a structured `details.code` so consumers can
+   * distinguish "doc doesn't exist" from "doc filtered by policy/org scope"
+   * without parsing error strings.
+   */
+  protected notFoundResponse(reason?: FetchDenialReason | null): IControllerResponse<never>;
+  /** Resolve cache config for a specific operation, merging per-op overrides */
+  protected resolveCacheConfig(operation: "list" | "byId"): QueryCacheConfig | null;
+  /**
+   * Extract user/org IDs from request for cache key scoping.
+   * Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
+   * Universal resources (tenantField: false) get shared cache keys.
+   */
+  protected cacheScope(req: IRequestContext): {
+    userId?: string;
+    orgId?: string;
+  };
+  list(req: IRequestContext): Promise<IControllerResponse<ListResult<TDoc>>>;
+  /** Execute list query through hooks (extracted for cache revalidation) */
+  protected executeListQuery(options: ParsedQuery, req: IRequestContext): Promise<ListResult<TDoc>>;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  /** Execute get query through hooks (extracted for cache revalidation) */
+  protected executeGetQuery(id: string, options: ParsedQuery, req: IRequestContext): Promise<{
+    doc: TDoc | null;
+    reason: FetchDenialReason | null;
   }>;
-  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;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+    id?: string;
+    soft?: boolean;
+  }>>;
 }
-interface RelationMetadata {
-  type: "one-to-one" | "one-to-many" | "many-to-many";
-  target: string;
-  foreignKey?: string;
-  through?: string;
+//#endregion
+//#region src/core/mixins/bulk.d.ts
+type Constructor$3<T> = new (...args: any[]) => T;
+/** Public surface contributed by BulkMixin. */
+interface BulkExt {
+  bulkCreate(req: IRequestContext): Promise<IControllerResponse<AnyRecord[]>>;
+  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>>;
+  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
+    deletedCount: number;
+  }>>;
 }
-interface ValidationResult$1 {
-  valid: boolean;
-  errors?: Array<{
-    field: string;
-    message: string;
-    code?: string;
-  }>;
+declare function BulkMixin<TBase extends Constructor$3<BaseCrudController>>(Base: TBase): TBase & Constructor$3<BulkExt>;
+//#endregion
+//#region src/core/mixins/slug.d.ts
+type Constructor$2<T> = new (...args: any[]) => T;
+/** Public surface contributed by SlugMixin. */
+interface SlugExt {
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<AnyRecord>>;
 }
-type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
+declare function SlugMixin<TBase extends Constructor$2<BaseCrudController>>(Base: TBase): TBase & Constructor$2<SlugExt>;
 //#endregion
-//#region src/types/handlers.d.ts
+//#region src/core/mixins/tree.d.ts
+type Constructor$1<T> = new (...args: any[]) => T;
+/** Public surface contributed by TreeMixin. */
+interface TreeExt {
+  getTree(req: IRequestContext): Promise<IControllerResponse<AnyRecord[]>>;
+  getChildren(req: IRequestContext): Promise<IControllerResponse<AnyRecord[]>>;
+}
+declare function TreeMixin<TBase extends Constructor$1<BaseCrudController>>(Base: TBase): TBase & Constructor$1<TreeExt>;
+//#endregion
+//#region src/core/mixins/softDelete.d.ts
+type Constructor<T> = new (...args: any[]) => T;
+/** Public surface contributed by SoftDeleteMixin. */
+interface SoftDeleteExt {
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginationResult<AnyRecord>>>;
+  restore(req: IRequestContext): Promise<IControllerResponse<AnyRecord>>;
+}
+declare function SoftDeleteMixin<TBase extends Constructor<BaseCrudController>>(Base: TBase): TBase & Constructor<SoftDeleteExt>;
+//#endregion
+//#region src/core/BaseController.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`.
+ * Fully-composed controller shape: all CRUD methods + every preset method
+ * (SoftDelete / Tree / Slug / Bulk) typed over the caller-supplied `TDoc`.
+ *
+ * **Inheritance summary** (what hover-docs should show when you reach for
+ * a method):
+ *
+ *   `BaseController<TDoc>`
+ *     └─ composes: `BaseCrudController` → `BulkMixin` → `SlugMixin` → `TreeMixin` → `SoftDeleteMixin`
+ *
+ *   - From `BaseCrudController`: `list`, `get`, `create`, `update`, `delete`
+ *   - From `BulkMixin`: `bulkCreate`, `bulkUpdate`, `bulkDelete`
+ *   - From `SlugMixin`: `getBySlug`
+ *   - From `TreeMixin`: `getTree`, `getChildren`
+ *   - From `SoftDeleteMixin`: `getDeleted`, `restore`
+ *
+ *   Hosts that only need CRUD extend `BaseCrudController` directly for a
+ *   smaller surface. Hosts that want specific mixins compose them by hand
+ *   (e.g. `class X extends SoftDeleteMixin(BaseCrudController<Doc>)`).
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * ADR — why declaration merging + why `TDoc` carries `extends AnyRecord`
+ * ──────────────────────────────────────────────────────────────────────────
+ * The natural reflex is:
+ *
+ *   class BaseController<TDoc> extends SoftDelete(Tree(Slug(Bulk(BaseCrud<TDoc>)))) {}
+ *
+ * TypeScript rejects this. Mixin factories can't receive a generic type
+ * parameter from the derived class (TS4.0 added limited support, but
+ * chained mixins over 4 levels deep still break because each factory
+ * would need its own TDoc binding — TS can't infer a shared `TDoc` across
+ * the chain without losing the base `extends Constructor<Base>` constraint).
+ *
+ * The composed runtime pins `BaseCrudController` to `AnyRecord` at the
+ * mixin-chain base; the TYPE surface hosts interact with threads `TDoc` so
+ * `new BaseController<Product>().list(req)` returns
+ * `Promise<IControllerResponse<ListResult<Product>>>` and not
+ * `ListResult<AnyRecord>`. Declaration merging bridges the two.
+ *
+ * **Why `TDoc extends AnyRecord` IS load-bearing:** the derived class
+ * inherits the mixin-composed base which is pinned to `AnyRecord`.
+ * Inherited methods return `ListResult<AnyRecord>` and the derived
+ * interface returns `ListResult<TDoc>`. For TS's "derived is assignable
+ * to base" check to pass, `TDoc` must be assignable to `AnyRecord` —
+ * which requires the `extends AnyRecord` bound. Dropping the bound fails
+ * with `Type 'TDoc[]' is not assignable to type 'AnyRecord[]'` at the
+ * class declaration. Hosts therefore need one of:
+ *   (a) `class X extends BaseController { ... }` — drop the generic,
+ *       lose return-type narrowing for `list` / `get` / etc.
+ *   (b) `interface IUser extends AnyRecord { ... }` — add an index
+ *       signature to the domain interface (preferred when you own it).
+ *   (c) Use the utility types (`ArcListResult<typeof this>`,
+ *       `ArcCreateResult<typeof this>`) when overriding methods — they
+ *       read the return type from the class, sidestepping the bound
+ *       for method bodies even when `TDoc` is unbound elsewhere.
+ *
+ * **Why `TRepository` defaults to `RepositoryLike<TDoc>`:** keeps
+ * diagnostics symmetric. With the older `RepositoryLike = RepositoryLike<unknown>`
+ * default, error messages mixed `AnyRecord` and `unknown` in the same
+ * signature, which confused the reader about where the mismatch was.
+ *
+ * **Cost this pays:** every method that participates in the `TDoc`
+ * narrowing is redeclared on the interface. Adding a new method to a
+ * mixin means updating this interface too. The alternative (losing
+ * host-side generics OR rewriting mixins as a non-generic union) is
+ * strictly worse.
+ *
+ * Spec reference: https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-classes-with-other-types
  */
-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>;
-  };
+interface BaseController<TDoc extends AnyRecord = AnyRecord, TRepository extends RepositoryLike = RepositoryLike<TDoc>> {
+  readonly accessControl: AccessControl;
+  readonly bodySanitizer: BodySanitizer;
+  queryResolver: QueryResolver;
+  setQueryParser(queryParser: QueryParserInterface): void;
+  list(req: IRequestContext): Promise<IControllerResponse<ListResult<TDoc>>>;
+  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;
+    id?: string;
+    soft?: boolean;
+  }>>;
+  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[]>>;
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  bulkCreate(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
+    matchedCount: number;
+    modifiedCount: number;
+  }>>;
+  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
+    deletedCount: number;
+  }>>;
 }
+declare const BaseController_base: (new (repository: any, options?: BaseControllerOptions) => BaseCrudController<AnyRecord, any>) & (new (...args: any[]) => BulkExt) & (new (...args: any[]) => SlugExt) & (new (...args: any[]) => TreeExt) & (new (...args: any[]) => SoftDeleteExt);
 /**
- * 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) };
- * }
- * ```
+ * Fully-composed controller: `BaseCrudController` + SoftDelete + Tree +
+ * Slug + Bulk. Drop-in replacement for the pre-2.11 god class. The
+ * companion interface above gives every method full generic precision
+ * on `TDoc` via declaration merging.
  */
-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;
+declare class BaseController<TDoc extends AnyRecord = AnyRecord, TRepository extends RepositoryLike = RepositoryLike<TDoc>> extends BaseController_base {
+  readonly _phantom?: [TDoc, TRepository];
 }
+//#endregion
+//#region src/types/base.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    /** Request scope — set by auth adapter, read by permissions/presets/guards */
+    scope: RequestScope;
+    /**
+     * Current user — set by auth adapter (Better Auth, JWT, custom).
+     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
+     * Guard with `if (request.user)` on routes that allow anonymous access.
+     *
+     * Kept as required (not `user?`) because `@fastify/jwt` declares it
+     * as required — declaration merges must have identical modifiers.
+     * The `| undefined` in the type achieves the same DX.
+     */
+    user: Record<string, unknown> | undefined;
+    /** Policy-injected query filters (e.g. ownership, org-scoping) */
+    _policyFilters?: Record<string, unknown>;
+    /** Field mask — fields to include/exclude in responses */
+    fieldMask?: {
+      include?: string[];
+      exclude?: string[];
+    };
+    /** Arbitrary policy metadata for downstream consumers */
+    policyMetadata?: Record<string, unknown>;
+    /** Document loaded by policy middleware for ownership checks */
+    document?: unknown;
+    /** Ownership check context (field name + user field) */
+    _ownershipCheck?: Record<string, unknown>;
+  }
+}
+type AnyRecord = Record<string, unknown>;
+/** MongoDB ObjectId — accepts string or any object with a `toString()` (e.g. mongoose ObjectId). */
+type ObjectId = string | {
+  toString(): string;
+};
 /**
- * Standard response from controller handlers
+ * Flexible user type that accepts any object with id/_id properties.
+ * The actual user structure is defined by your app's auth system.
  */
-interface IControllerResponse<T = unknown> {
-  /** Operation success status */
+type UserLike = UserBase & {
+  /** User email (optional) */email?: string;
+};
+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;
-  /** Response data */
   data?: T;
-  /** Error message (when success is false) */
   error?: string;
-  /** HTTP status code (default: 200 for success, 400 for error) */
-  status?: number;
-  /** Additional metadata */
+  message?: string;
   meta?: Record<string, unknown>;
-  /** Error details (for debugging) */
-  details?: Record<string, unknown>;
-  /** Custom response headers (e.g., X-Total-Count, Link, ETag) */
-  headers?: Record<string, string>;
 }
 /**
- * Controller handler — Arc's standard pattern.
- *
- * Receives a request context object, returns IControllerResponse.
- * Use with `raw: false` in routes.
- *
- * **Generic parameters:**
- * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
- * - `TBody`     — shape of `req.body` (default: `unknown`)
- * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
- * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
- *
- * Backward-compatible: `ControllerHandler<Product>` still works (only the
- * response data is typed); add more generics as needed when you want
- * type-safe access to the request body, params, or query string.
+ * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * instead of `(req as any).user`.
  *
  * @example
  * ```typescript
- * // Untyped req — body is unknown, must be narrowed
- * const createProduct: ControllerHandler<Product> = async (req) => {
- *   const product = await productRepo.create(req.body as Partial<Product>);
- *   return { success: true, data: product, status: 201 };
- * };
- *
- * // 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 };
- * };
+ * import type { ArcRequest } from '@classytic/arc';
  *
- * routes: [{
- *   method: 'POST',
- *   path: '/products',
- *   handler: createProduct,
- *   permissions: requireAuth(),
- *   raw: false,  // Arc wraps this into Fastify handler
- * }]
+ * handler: async (req: ArcRequest, reply) => {
+ *   req.user?.id;                    // typed
+ *   req.scope.organizationId;        // typed (when member)
+ *   req.signal;                      // AbortSignal (Fastify 5)
+ * }
  * ```
  */
-type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
+type ArcRequest = FastifyRequest & {
+  scope: RequestScope;
+  user: Record<string, unknown> | undefined;
+  signal: AbortSignal;
+};
+//#endregion
+//#region src/types/auth.d.ts
 /**
- * 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
+ * JWT utilities provided to authenticator. Arc provides the helpers;
+ * apps use them as needed.
  */
-type RouteHandler = ControllerHandler | FastifyHandler;
+interface JwtContext {
+  /** Verify a JWT token and return decoded payload */
+  verify: <T = Record<string, unknown>>(token: string) => T;
+  /** Sign a payload and return JWT token */
+  sign: (payload: Record<string, unknown>, options?: {
+    expiresIn?: string;
+  }) => string;
+  /** Decode without verification (for inspection) */
+  decode: <T = Record<string, unknown>>(token: string) => T | null;
+}
+/** Context passed to app's authenticator function. */
+interface AuthenticatorContext {
+  /** JWT utilities (available if `jwt.secret` provided) */
+  jwt: JwtContext | null;
+  /** Fastify instance for advanced use cases */
+  fastify: FastifyInstance;
+}
 /**
- * Controller interface for CRUD operations (strict)
+ * App-provided authenticator function. Arc calls this for every
+ * non-public route. The app has full control over authentication logic.
+ *
+ * Return a user object to authenticate, `null`/`undefined` to reject.
+ *
+ * @example
+ * ```typescript
+ * authenticate: async (request, { jwt }) => {
+ *   const token = request.headers.authorization?.split(' ')[1];
+ *   if (!token || !jwt) return null;
+ *   const decoded = jwt.verify(token);
+ *   return userRepo.findById(decoded.id);
+ * }
+ * ```
  */
-interface IController<TDoc = unknown> {
-  list(req: IRequestContext): Promise<IControllerResponse<{
-    docs: TDoc[];
-    total: number;
-  }>>;
-  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  delete(req: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-  }>>;
+type Authenticator = (request: FastifyRequest, context: AuthenticatorContext) => Promise<unknown | null> | unknown | null;
+/** Token pair returned by `issueTokens` helper. */
+interface TokenPair {
+  /** Access token (JWT) */
+  accessToken: string;
+  /** Refresh token (JWT with longer expiry) */
+  refreshToken?: string;
+  /** Access token expiry in seconds */
+  expiresIn: number;
+  /** Refresh token expiry in seconds */
+  refreshExpiresIn?: number;
+  /** Token type (always 'Bearer') */
+  tokenType: "Bearer";
 }
 /**
- * Flexible controller interface - accepts controllers with any handler style
- * Use this when your controller uses Fastify native handlers
+ * Auth helpers exposed on `fastify.auth`.
+ *
+ * @example
+ * ```typescript
+ * const tokens = fastify.auth.issueTokens({
+ *   id: user._id,
+ *   email: user.email,
+ *   role: user.role,
+ * });
+ * return { success: true, ...tokens, user };
+ * ```
  */
-interface ControllerLike {
-  list?: unknown;
-  get?: unknown;
-  create?: unknown;
-  update?: unknown;
-  delete?: unknown;
-  [key: string]: unknown;
+interface AuthHelpers {
+  /** JWT utilities (if configured) */
+  jwt: JwtContext | null;
+  /**
+   * Issue access + refresh tokens for a user. App calls this after
+   * validating credentials.
+   */
+  issueTokens: (payload: Record<string, unknown>, options?: {
+    expiresIn?: string;
+    refreshExpiresIn?: string;
+  }) => TokenPair;
+  /** Verify a refresh token and return decoded payload. */
+  verifyRefreshToken: <T = Record<string, unknown>>(token: string) => T;
 }
-//#endregion
-//#region src/types/resource.d.ts
-/** Standard controller type alias for CRUD operations. */
-type CrudController<TDoc> = IController<TDoc>;
 /**
- * Per-resource cache configuration for QueryCache. Enables
- * stale-while-revalidate, auto-invalidation on mutations, and
- * cross-resource tag-based invalidation.
+ * Auth plugin options — clean, minimal configuration.
+ *
+ * Arc provides JWT infrastructure and calls your authenticator. You
+ * control all authentication logic.
+ *
+ * @example
+ * ```typescript
+ * auth: {
+ *   jwt: { secret: process.env.JWT_SECRET },
+ *   authenticate: async (request, { jwt }) => {
+ *     const token = request.headers.authorization?.split(' ')[1];
+ *     if (!token) return null;
+ *     const decoded = jwt.verify(token);
+ *     return userRepo.findById(decoded.id);
+ *   },
+ * }
+ * ```
  */
-interface ResourceCacheConfig {
-  /** Seconds data is "fresh" (no revalidation). Default: 0 */
-  staleTime?: number;
-  /** Seconds stale data stays cached (SWR window). Default: 60 */
-  gcTime?: number;
-  /** Per-operation overrides */
-  list?: {
-    staleTime?: number;
-    gcTime?: number;
-  };
-  byId?: {
-    staleTime?: number;
-    gcTime?: number;
+interface AuthPluginOptions {
+  /**
+   * JWT configuration (optional but recommended). If provided, JWT
+   * utilities are available in the authenticator context.
+   */
+  jwt?: {
+    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
+    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string; /** Additional `@fastify/jwt` sign options */
+    sign?: Record<string, unknown>; /** Additional `@fastify/jwt` verify options */
+    verify?: Record<string, unknown>;
   };
-  /** Tags for cross-resource invalidation grouping */
-  tags?: string[];
   /**
-   * Cross-resource invalidation: event pattern → tag targets.
-   * @example { 'category.*': ['catalog'] }
+   * Custom authenticator function. Arc calls this for non-public routes.
+   * If not provided and `jwt.secret` is set, uses default `jwtVerify`.
    */
-  invalidateOn?: Record<string, string[]>;
-  /** Disable caching for this resource */
-  disabled?: boolean;
-}
-interface RateLimitConfig {
-  /** Maximum number of requests allowed within the time window */
-  max: number;
-  /** Time window for rate limiting (e.g., '1 minute', '15 seconds') */
-  timeWindow: string;
-}
-interface RouteSchemaOptions {
-  hiddenFields?: string[];
-  readonlyFields?: string[];
-  requiredFields?: string[];
-  optionalFields?: string[];
-  excludeFields?: string[];
+  authenticate?: Authenticator;
   /**
-   * Fields allowed for filtering in list operations. MCP auto-derives
-   * from `QueryParser.allowedFilterFields` when not set explicitly.
+   * Custom auth failure handler. Customize the 401 response when
+   * authentication fails.
    */
-  filterableFields?: string[];
-  fieldRules?: Record<string, {
-    systemManaged?: boolean;
-    hidden?: boolean;
-    immutable?: boolean;
-    immutableAfterCreate?: boolean;
-    optional?: boolean; /** String minimum length — auto-maps to OpenAPI `minLength` and MCP tool schema */
-    minLength?: number; /** String maximum length — auto-maps to OpenAPI `maxLength` and MCP tool schema */
-    maxLength?: number; /** Number minimum — auto-maps to OpenAPI `minimum` and MCP tool schema */
-    min?: number; /** Number maximum — auto-maps to OpenAPI `maximum` and MCP tool schema */
-    max?: number; /** Regex pattern — auto-maps to OpenAPI `pattern` and MCP tool schema */
-    pattern?: string; /** Allowed values — auto-maps to OpenAPI `enum` and MCP tool schema */
-    enum?: ReadonlyArray<string | number>; /** Human-readable description — auto-maps to OpenAPI `description` */
-    description?: string;
-    [key: string]: unknown;
-  }>;
-  /** Query parameter schema for OpenAPI */
-  query?: Record<string, unknown>;
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  /**
+   * 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>;
   /**
-   * 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.
+   * 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"`.
    */
-  strictAdditionalProperties?: boolean;
+  strictTokenType?: boolean;
 }
-interface FieldRule {
-  field: string;
-  required?: boolean;
-  readonly?: boolean;
-  hidden?: boolean;
+//#endregion
+//#region src/pipeline/types.d.ts
+/**
+ * Pipeline context passed to guards, transforms, and interceptors.
+ * Extends IRequestContext with pipeline-specific metadata.
+ */
+interface PipelineContext extends IRequestContext {
+  /** Resource name being accessed */
+  resource: string;
+  /** CRUD operation being performed */
+  operation: "list" | "get" | "create" | "update" | "delete" | string;
 }
 /**
- * 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.
+ * Which operations a pipeline step applies to.
+ * If omitted, applies to ALL operations.
  */
-interface CrudSchemas {
-  /** GET / — list */
-  list?: {
-    querystring?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** GET /:id — get one */
-  get?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** POST / — create */
-  create?: {
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** PATCH /:id — update */
-  update?: {
-    params?: unknown;
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** DELETE /:id — delete */
-  delete?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
+type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
+/**
+ * Guard — boolean check that short-circuits on failure.
+ * Return true to proceed, throw to deny.
+ */
+interface Guard {
+  readonly _type: "guard";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): boolean | Promise<boolean>;
 }
-interface OpenApiSchemas {
-  entity?: unknown;
-  createBody?: unknown;
-  updateBody?: unknown;
-  params?: unknown;
-  listQuery?: unknown;
-  /**
-   * Explicit response schema for OpenAPI documentation. Auto-generated
-   * from `createBody` if omitted. Does NOT affect Fastify serialization.
-   */
-  response?: unknown;
-  [key: string]: unknown;
+/**
+ * Transform — modifies request data before the handler.
+ * Returns modified context (or mutates in place).
+ */
+interface Transform {
+  readonly _type: "transform";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): PipelineContext | undefined | Promise<PipelineContext | undefined>;
 }
-type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
-interface MiddlewareConfig {
-  list?: MiddlewareHandler[];
-  get?: MiddlewareHandler[];
-  create?: MiddlewareHandler[];
-  update?: MiddlewareHandler[];
-  delete?: MiddlewareHandler[];
-  [key: string]: MiddlewareHandler[] | undefined;
+/**
+ * Next function passed to interceptors — calls the handler (or next interceptor).
+ */
+type NextFunction = () => Promise<IControllerResponse<unknown>>;
+/**
+ * Intercept — wraps handler execution (before + after pattern).
+ */
+interface Interceptor {
+  readonly _type: "interceptor";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
 }
-/** 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;
+type PipelineStep = Guard | Transform | Interceptor;
+/**
+ * Pipeline configuration — can be a flat array or per-operation map.
+ */
+type PipelineConfig = PipelineStep[] | {
+  list?: PipelineStep[];
+  get?: PipelineStep[];
+  create?: PipelineStep[];
+  update?: PipelineStep[];
+  delete?: PipelineStep[];
+  [operation: string]: PipelineStep[] | undefined;
+};
+//#endregion
+//#region src/types/handlers.d.ts
+/**
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `raw: true`.
+ */
+interface ServerAccessor {
+  /** Event bus — publish domain events from any handler */
+  events?: {
+    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
+  };
+  /** Audit logger — log custom audit entries */
+  audit?: {
+    create: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+  };
+  /** Logger — structured logging */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+  /** QueryCache — stale-while-revalidate data cache */
+  queryCache?: {
+    get: <T>(key: string) => Promise<{
+      data: T;
+      status: "fresh" | "stale" | "miss";
+    }>;
+    set: <T>(key: string, data: T, config: {
+      staleTime?: number;
+      gcTime?: number;
+      tags?: string[];
+    }) => Promise<void>;
+    getResourceVersion: (resource: string) => Promise<number>;
+    bumpResourceVersion: (resource: string) => Promise<void>;
   };
 }
 /**
- * Route definition — single custom-route shape (user-facing + internal).
+ * Request context passed to controller handlers.
  *
- * - `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
+ * **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 RouteDefinition {
-  readonly method: RouteMethod;
-  /** Path relative to resource prefix */
-  readonly path: string;
+/**
+ * First-class projection of `request._scope` for controller handlers.
+ *
+ * **v2.10.6:** previously, pulling tenant/user/role info from inside a
+ * controller override meant digging through `req.metadata._scope` and
+ * calling `getOrgId(scope)` / `getUserId(user)` manually. This projection
+ * lifts the two fields most hosts need directly onto `req` so cross-kit
+ * controller code reads:
+ *
+ * ```ts
+ * async create(req: IRequestContext) {
+ *   const flowCtx = { organizationId: req.scope?.organizationId, actorId: req.scope?.userId };
+ * }
+ * ```
+ *
+ * Full scope shape (discriminated union of `member` / `service` / `elevated` / `public`)
+ * still lives on `req.metadata._scope` for code that needs to branch on
+ * `scope.kind` — this projection just surfaces the two keys every
+ * tenant-scoped resource reaches for.
+ */
+interface RequestScopeProjection {
+  /** Tenant the caller is scoped to (org member, service key bound to an org, or elevated admin's target org). */
+  organizationId?: string;
+  /** Caller's user id when authenticated — undefined for public / service-only scopes. */
+  userId?: string;
+  /** Org-level roles (e.g. `['admin', 'warehouse-manager']`) — separate from global `user.roles`. */
+  orgRoles?: string[];
+}
+interface 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;
   /**
-   * 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)`
+   * First-class tenant/user scope projection — lifted from `metadata._scope`
+   * so controller overrides don't have to dig through Arc internals.
+   * See {@link RequestScopeProjection}. `undefined` for routes that run
+   * without auth / scope resolution.
    */
-  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
-  /** Permission check — REQUIRED */
-  readonly permissions: PermissionCheck;
+  scope?: RequestScopeProjection;
   /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
-   * request/reply. Default: false.
+   * 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')) { ... }
+   * }
+   * ```
    */
-  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;
+  context?: RequestContext;
   /**
-   * Fastify route schema. Each slot (`body`, `querystring`, `params`,
-   * `headers`, `response[status]`) accepts a plain JSON Schema object
-   * **or** a Zod v4 schema — Arc auto-converts via `convertRouteSchema`.
-   */
-  readonly schema?: {
-    body?: unknown;
-    querystring?: unknown;
-    params?: unknown;
-    headers?: unknown;
-    response?: Record<number | string, unknown>;
-    [key: string]: unknown;
-  };
-  /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate (non-raw routes only)
-   * - false: skip MCP
-   * - object: explicit config
+   * 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.
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  metadata?: TMetadata;
   /**
-   * MCP handler for raw routes — parallel entry point for MCP without
-   * changing the HTTP handler.
+   * 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 };
+   * }
+   * ```
    */
-  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
-    content: Array<{
-      type: string;
-      text: string;
-    }>;
-    isError?: boolean;
-  }>;
+  server?: ServerAccessor;
 }
 /**
- * Action handler function for state transitions. Receives the resource
- * ID, action-specific data, and the request.
+ * Standard response from controller handlers
  */
-type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
-/** Full action configuration with handler, permissions, and schema. */
-interface ActionDefinition {
-  readonly handler: ActionHandlerFn;
-  /** Per-action permission (overrides resource-level `actionPermissions`) */
-  readonly permissions?: PermissionCheck;
-  /**
-   * JSON Schema or Zod v4 schema for action-specific body fields.
-   * Per-field values are typed `unknown` so Zod class instances assign
-   * without casts.
-   */
-  readonly schema?: Record<string, unknown>;
-  /** Description for OpenAPI docs and MCP tool */
-  readonly description?: string;
-  /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate
-   * - false: skip
-   * - object: explicit config
-   */
-  readonly mcp?: boolean | RouteMcpConfig;
+interface 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>;
 }
-/** Action config: bare handler function OR full ActionDefinition. */
-type ActionEntry = ActionHandlerFn | ActionDefinition;
-/** Actions configuration map. */
-type ActionsMap = Record<string, ActionEntry>;
 /**
- * Hook context passed to resource-level hook handlers. Mirrors
- * HookSystem's HookContext but with a simpler API for inline use.
+ * 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
+ * }]
+ * ```
  */
-interface ResourceHookContext {
-  /** The document data (create/update body, or existing doc for delete) */
-  data: AnyRecord;
-  /** Authenticated user or null */
-  user?: UserBase;
-  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
-  meta?: AnyRecord;
-}
+type 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>>;
 /**
- * Inline lifecycle hooks on a resource definition. Wired into the
- * HookSystem automatically — same pipeline as presets and app-level hooks.
+ * Fastify native handler
+ *
+ * Standard Fastify request/reply pattern.
+ * Use with `raw: true` in routes.
  *
  * @example
  * ```typescript
- * defineResource({
- *   name: 'chat',
- *   hooks: {
- *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
- *     beforeDelete: async (ctx) => {
- *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
- *     },
- *   },
- * });
+ * 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
+ * }]
  * ```
  */
-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;
+type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
+/**
+ * Union type for route handlers
+ */
+type RouteHandler = ControllerHandler | FastifyHandler;
+/**
+ * Controller interface for CRUD operations (strict).
+ *
+ * `list`'s return type aligns with repo-core's `MinimalRepo.getAll()`
+ * contract — the kit MAY return an offset envelope, a keyset envelope,
+ * or a raw array. Arc's `BaseController` forwards the kit's response
+ * verbatim; consumers narrow on shape
+ * (`Array.isArray(data)` → bare array, presence of `total` → offset,
+ * presence of `nextCursor` → keyset).
+ */
+interface IController<TDoc = unknown> {
+  list(req: IRequestContext): Promise<IControllerResponse<unknown>>;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+  }>>;
 }
-interface PresetHook {
-  operation: "create" | "update" | "delete" | "read" | "list";
-  phase: "before" | "after";
-  handler: (ctx: AnyRecord) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
-  priority?: number;
+/**
+ * Flexible controller interface — accepts controllers with any handler style,
+ * including class instances with extra methods / private fields.
+ *
+ * **v2.10.6:** the previous `[key: string]: unknown` index signature made
+ * real class instances fail structural assignment (`new ScrapController()`
+ * needed a `as unknown as ControllerLike` cast, because class instances
+ * don't have an index signature). Dropped — arc only invokes the CRUD
+ * methods at runtime, so the rest of the shape is the caller's concern.
+ *
+ * The five CRUD slots stay optional so partial controllers (e.g. read-only)
+ * assign too. Additional domain methods on the controller are allowed by
+ * construction (they're just not part of this contract).
+ */
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
 }
-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[];
+//#endregion
+//#region src/types/resource.d.ts
+/** Standard controller type alias for CRUD operations. */
+type CrudController<TDoc> = IController<TDoc>;
+/**
+ * Per-resource cache configuration for QueryCache. Enables
+ * stale-while-revalidate, auto-invalidation on mutations, and
+ * cross-resource tag-based invalidation.
+ */
+interface ResourceCacheConfig {
+  /** Seconds data is "fresh" (no revalidation). Default: 0 */
+  staleTime?: number;
+  /** Seconds stale data stays cached (SWR window). Default: 60 */
+  gcTime?: number;
+  /** Per-operation overrides */
+  list?: {
+    staleTime?: number;
+    gcTime?: number;
+  };
+  byId?: {
+    staleTime?: number;
+    gcTime?: number;
+  };
+  /** Tags for cross-resource invalidation grouping */
+  tags?: string[];
+  /**
+   * Cross-resource invalidation: event pattern → tag targets.
+   * @example { 'category.*': ['catalog'] }
+   */
+  invalidateOn?: Record<string, string[]>;
+  /** Disable caching for this resource */
+  disabled?: boolean;
 }
-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;
+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;
 }
-/** 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;
+/**
+ * Per-field rule — arc's extension of repo-core's 4-field `FieldRule` floor
+ * (`immutable`, `immutableAfterCreate`, `systemManaged`, `optional`) with
+ * the constraint / UI / security bits arc layers on top.
+ *
+ * Kept structurally compatible with `@classytic/repo-core/schema`'s
+ * `FieldRule` so arc's `fieldRules: Record<string, ArcFieldRule>` flows
+ * into mongokit's / sqlitekit's `buildCrudSchemasFromModel(..., options)`
+ * without a cast. See `RouteSchemaOptions` JSDoc for the full rationale.
+ */
+interface ArcFieldRule extends FieldRule {
   /**
-   * 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`.
+   * When `true`, bypass the `systemManaged` / `readonly` / `immutable`
+   * strip in `BodySanitizer` for callers whose request scope is
+   * `elevated`. Lets platform admins stamp the value from the request
+   * body — needed for cross-tenant admin writes where the tenant field
+   * is the only way to pick a target org.
    *
-   * @example
-   * ```typescript
-   * defineResource({ name: 'webhook', prefix: '/webhooks', skipGlobalPrefix: true })
-   * ```
+   * Auto-set by `defineResource` on the configured `tenantField`. Hosts
+   * can set it manually on other fields (e.g. `createdBy`) if they want
+   * elevation-only override semantics for those too.
+   *
+   * Has no effect when `isElevated(scope)` is false — member and
+   * service callers continue to have the field stripped.
    */
-  skipGlobalPrefix?: boolean;
-  /** Optional for service-pattern resources */
-  adapter?: DataAdapter<TDoc>;
-  /** Controller instance — accepts any object with CRUD methods. */
-  controller?: IController<TDoc> | ControllerLike;
-  queryParser?: unknown;
-  permissions?: ResourcePermissions;
-  schemaOptions?: RouteSchemaOptions;
-  openApiSchemas?: OpenApiSchemas;
-  /** Custom JSON schemas (override Arc-generated). */
-  customSchemas?: Partial<CrudSchemas>;
-  /** Preset names, objects, or PresetResult values. */
-  presets?: Array<string | PresetResult | {
-    name: string;
-    [key: string]: unknown;
-  }>;
-  hooks?: ResourceHooks;
-  /**
-   * Functional pipeline — guards, transforms, interceptors. Flat array
-   * (all operations) or per-operation map.
+  preserveForElevated?: boolean;
+  hidden?: 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>;
+  /**
+   * When `true`, widen the JSON Schema `type` of this field to also
+   * accept `null`. Mirrors Zod's `.nullable()` at the arc config layer
+   * for kit-generated schemas that don't carry the flag end-to-end
+   * (e.g. Zod → Mongoose → mongokit drops `.nullable()` because
+   * Mongoose has no first-class nullable marker unless `default: null`
+   * is also set).
    *
-   * @example
-   * ```typescript
-   * pipe: pipe(isActive, slugify, timing),
-   * pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
-   * ```
+   * Applied post-kit by `mergeFieldRuleConstraints`: if the adapter
+   * emitted `{ type: 'string', enum: [...] }` for a field arc should
+   * accept null for, the merge widens it to
+   * `{ type: ['string', 'null'], enum: [...] }` — draft-7 tuple form
+   * AJV 8 validates natively.
+   *
+   * No-op when the property already declares `type: [...,'null']` or
+   * an `anyOf: [..., { type: 'null' }]` branch — arc never fights the
+   * kit's own output.
    */
-  pipe?: PipelineConfig;
+  nullable?: boolean;
+  /** Human-readable description — auto-maps to OpenAPI `description` */
+  description?: string;
+  [key: string]: unknown;
+}
+/**
+ * Schema-shaping options for a resource.
+ *
+ * Extends `@classytic/repo-core/schema`'s `SchemaBuilderOptions` so every
+ * kit-generator callback typed against the repo-core contract
+ * (mongokit's `buildCrudSchemasFromModel`, sqlitekit's
+ * `buildCrudSchemasFromTable`, prismakit's equivalent) accepts arc's
+ * options bag directly — no `as SchemaBuilderOptions` / `Parameters<...>[1]`
+ * cast at the host wiring site.
+ *
+ * Inherited from `SchemaBuilderOptions`:
+ *   - `strictAdditionalProperties` — emit `additionalProperties: false`
+ *   - `dateAs` — `'date'` vs `'datetime'` ISO rendering
+ *   - `softRequiredFields` — stay in `properties`, drop from `required[]`
+ *   - `create: { omitFields, requiredOverrides, optionalOverrides, schemaOverrides }`
+ *   - `update: { omitFields, requireAtLeastOne }`
+ *   - `query: { filterableFields }` (kit-native filter declaration)
+ *   - `openApiExtensions` — emit `x-*` vendor keywords for docgen
+ *
+ * Arc adds:
+ *   - `fieldRules` with the richer `ArcFieldRule` per-entry shape
+ *     (preserveForElevated, minLength/maxLength/min/max/pattern, enum,
+ *     nullable, description) — arc's extensions are applied post-kit by
+ *     `mergeFieldRuleConstraints`; the kit only sees the repo-core floor.
+ *   - `hiddenFields` / `readonlyFields` / `requiredFields` / `optionalFields`
+ *     / `excludeFields` — arc-only convenience lists that predate fieldRules.
+ *     Keep using them if they're already in place; new code should prefer
+ *     `fieldRules` for per-field control.
+ *   - `filterableFields: string[]` — top-level list arc's MCP layer auto-
+ *     derives from `QueryParser.allowedFilterFields`. Distinct from the
+ *     inherited `query.filterableFields: Record<...>` which feeds the kit's
+ *     list-query schema; nothing stops a resource from using both.
+ *
+ * **Why extend rather than duplicate**: mongokit's
+ * `buildCrudSchemasFromModel(model, options: SchemaBuilderOptions)` is the
+ * canonical callback shape. Before the extension, hosts wrote
+ * `Parameters<typeof buildCrudSchemasFromModel>[1]` or
+ * `as SchemaBuilderOptions` at every wiring site — a defensive cast with
+ * no runtime effect. Extension locks the structural relationship at the
+ * type layer so the cast is compile-verified gone.
+ */
+interface RouteSchemaOptions extends SchemaBuilderOptions {
+  hiddenFields?: string[];
+  readonlyFields?: string[];
+  requiredFields?: string[];
+  optionalFields?: string[];
+  excludeFields?: string[];
   /**
-   * Field-level permissions — control visibility and writability per role.
+   * Fields allowed for filtering in list operations. MCP auto-derives
+   * from `QueryParser.allowedFilterFields` when not set explicitly.
    *
-   * @example
-   * ```typescript
-   * fields: {
-   *   salary: fields.visibleTo(['admin', 'hr']),
-   *   password: fields.hidden(),
-   * }
-   * ```
+   * Distinct from the inherited `query.filterableFields: Record<...>`
+   * from `SchemaBuilderOptions` — that entry feeds the kit's list-query
+   * JSON Schema; this one is arc's MCP-auto-derivation list.
    */
-  fields?: FieldPermissionMap;
+  filterableFields?: string[];
   /**
-   * Policy for requests that include fields the caller can't write.
+   * Per-field rules. Richer than repo-core's `FieldRules` — arc adds
+   * `preserveForElevated`, constraint hints (`minLength`, `enum`,
+   * `nullable`, etc.), and `description` on top of the four-flag floor
+   * (`immutable`, `immutableAfterCreate`, `systemManaged`, `optional`).
    *
-   * - `'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.
+   * Structurally compatible: `Record<string, ArcFieldRule>` is assignable
+   * to repo-core's `Record<string, FieldRule>` since `ArcFieldRule extends
+   * FieldRule`. Kits see only the floor; arc's extensions are applied
+   * post-kit by `mergeFieldRuleConstraints`.
    */
-  onFieldWriteDenied?: "reject" | "strip";
-  middlewares?: MiddlewareConfig;
+  fieldRules?: Record<string, ArcFieldRule>;
+}
+interface FieldRule$1 {
+  field: string;
+  required?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
+}
+/**
+ * CRUD route schemas (Fastify native format). Each slot accepts a plain
+ * JSON Schema object **or** a Zod v4 schema — Arc's `convertRouteSchema`
+ * feature-detects at runtime. Slot values are typed `unknown` so
+ * class-based Zod schemas assign without casts.
+ */
+interface CrudSchemas {
+  /** GET / — list */
+  list?: {
+    querystring?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** GET /:id — get one */
+  get?: {
+    params?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** POST / — create */
+  create?: {
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** PATCH /:id — update */
+  update?: {
+    params?: unknown;
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** DELETE /:id — delete */
+  delete?: {
+    params?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface OpenApiSchemas {
+  entity?: unknown;
+  createBody?: unknown;
+  updateBody?: unknown;
+  params?: unknown;
+  listQuery?: unknown;
   /**
-   * PreHandler guards auto-applied to **every** route on this resource
-   * (CRUD + custom + preset). Runs after auth/permissions, before
-   * per-route `preHandler`. Use for mode gates, tenant checks, feature
-   * flags — anything that applies to every endpoint.
+   * Explicit response schema for OpenAPI documentation. Auto-generated
+   * from `createBody` if omitted. Does NOT affect Fastify serialization.
    */
-  routeGuards?: RouteHandlerMethod[];
+  response?: unknown;
+  [key: string]: unknown;
+}
+type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
+interface MiddlewareConfig {
+  list?: MiddlewareHandler[];
+  get?: MiddlewareHandler[];
+  create?: MiddlewareHandler[];
+  update?: MiddlewareHandler[];
+  delete?: MiddlewareHandler[];
+  [key: string]: MiddlewareHandler[] | undefined;
+}
+/** HTTP methods for custom routes. */
+type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** MCP tool configuration for a route or action. */
+interface RouteMcpConfig {
+  /** Override auto-generated tool description */
+  readonly description?: string;
+  /** MCP tool annotations */
+  readonly annotations?: {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+  };
+}
+/**
+ * Route definition — single custom-route shape (user-facing + internal).
+ *
+ * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
+ * - `handler: function` → inline handler → full Arc pipeline + MCP tool
+ * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
+ */
+interface RouteDefinition {
+  readonly method: RouteMethod;
+  /** Path relative to resource prefix */
+  readonly path: string;
   /**
-   * Custom routes beyond CRUD. Presets also merge their routes here.
-   *
-   * @example
-   * ```typescript
-   * routes: [
-   *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
-   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
-   * ]
-   * ```
+   * 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)`
    */
-  routes?: RouteDefinition[];
+  readonly handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
+  /** Permission check — REQUIRED */
+  readonly permissions: PermissionCheck;
   /**
-   * State-transition actions → unified `POST /:id/action` endpoint.
-   * Each action can be a bare handler or full config with permissions
-   * + schema.
-   *
-   * @example
-   * ```typescript
-   * actions: {
-   *   approve: async (id, data, req) => service.approve(id, req.user._id),
-   *   cancel: {
-   *     handler: async (id, data, req) => service.cancel(id, data.reason, req.user._id),
-   *     permissions: roles('admin'),
-   *     schema: { reason: { type: 'string' } },
-   *   },
-   * },
-   * actionPermissions: auth(),
-   * ```
+   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
+   * request/reply. Default: false.
    */
-  actions?: ActionsMap;
+  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;
   /**
-   * Fallback permission for actions without per-action permissions.
-   * Only applies when `actions` is defined.
+   * 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`.
    */
-  actionPermissions?: PermissionCheck;
-  disableCrud?: boolean;
-  disableDefaultRoutes?: boolean;
-  /** Specific routes to disable */
-  disabledRoutes?: CrudRouteKey[];
+  readonly schema?: {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<number | string, unknown>;
+    [key: string]: unknown;
+  };
   /**
-   * Field name used for multi-tenant scoping (default: 'organizationId').
-   * Override to match your schema: 'workspaceId', 'tenantId', etc.
+   * MCP tool generation:
+   * - omitted/true: auto-generate (non-raw routes only)
+   * - false: skip MCP
+   * - object: explicit config
+   */
+  readonly mcp?: boolean | RouteMcpConfig;
+  /**
+   * MCP handler for raw routes — parallel entry point for MCP without
+   * changing the HTTP handler.
+   */
+  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
+}
+/**
+ * Action handler function for state transitions. Receives the resource
+ * ID, action-specific data, and the request.
+ */
+type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
+/** Full action configuration with handler, permissions, and schema. */
+interface ActionDefinition {
+  readonly handler: ActionHandlerFn;
+  /** Per-action permission (overrides resource-level `actionPermissions`) */
+  readonly permissions?: PermissionCheck;
+  /**
+   * JSON Schema or Zod v4 schema for action-specific body fields.
+   * Per-field values are typed `unknown` so Zod class instances assign
+   * without casts.
+   */
+  readonly schema?: Record<string, unknown>;
+  /** Description for OpenAPI docs and MCP tool */
+  readonly description?: string;
+  /**
+   * MCP tool generation:
+   * - omitted/true: auto-generate
+   * - false: skip
+   * - object: explicit config
+   */
+  readonly mcp?: boolean | RouteMcpConfig;
+}
+/** Action config: bare handler function OR full ActionDefinition. */
+type ActionEntry = ActionHandlerFn | ActionDefinition;
+/** Actions configuration map. */
+type ActionsMap = Record<string, ActionEntry>;
+/**
+ * Hook context passed to resource-level hook handlers. Mirrors
+ * HookSystem's HookContext but with a simpler API for inline use.
+ *
+ * **v2.10.8:** `context` and a first-class `scope` projection are now
+ * forwarded from the internal `HookContext`. Before this release, inline
+ * `config.hooks` handlers had no way to reach the caller's tenant or
+ * user info — they had to bypass the documented API and push directly
+ * into `resource._pendingHooks` to get the raw internal shape. Now the
+ * documented DX is complete:
+ *
+ * ```ts
+ * hooks: {
+ *   afterCreate: (ctx) => {
+ *     auditLog.write({
+ *       org: ctx.scope?.organizationId,
+ *       actor: ctx.scope?.userId,
+ *       id: ctx.data._id,
+ *     });
+ *   },
+ * }
+ * ```
+ *
+ * The `scope` projection matches `IRequestContext.scope` (2.10.6) so
+ * hosts read tenant/user the same way across controllers and hooks.
+ * Use `context._scope` directly for advanced cases that need to
+ * discriminate on `scope.kind` or reach auth-adapter-specific fields.
+ */
+interface ResourceHookContext {
+  /** The document data (create/update body, or existing doc for delete / after-result) */
+  data: AnyRecord;
+  /** Authenticated user or null */
+  user?: UserBase;
+  /**
+   * Full typed request context — includes `_scope`, `_policyFilters`,
+   * `arc` metadata. Use `ctx.scope` for the common tenant/user projection;
+   * reach for `ctx.context` when you need `_scope.kind` branching or
+   * custom fields set by your auth adapter.
+   */
+  context?: AnyRecord;
+  /**
+   * First-class projection of request scope — `{ organizationId?, userId?, orgRoles? }`.
+   * Populated for every scoped request so multi-tenant hooks don't have to
+   * drill into `context._scope.organizationId` themselves. Matches the
+   * identically-named field on `IRequestContext` (v2.10.6) so the same
+   * read pattern works in controllers and hooks.
+   */
+  scope?: {
+    organizationId?: string;
+    userId?: string;
+    orgRoles?: string[];
+  };
+  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
+  meta?: AnyRecord;
+}
+/**
+ * Inline lifecycle hooks on a resource definition. Wired into the
+ * HookSystem automatically — same pipeline as presets and app-level hooks.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'chat',
+ *   hooks: {
+ *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
+ *     beforeDelete: async (ctx) => {
+ *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface ResourceHooks {
+  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | void;
+  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  afterUpdate?: (ctx: ResourceHookContext) => Promise<void> | void;
+  beforeDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+  afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
+}
+interface PresetHook {
+  operation: "create" | "update" | "delete" | "read" | "list";
+  phase: "before" | "after";
+  handler: (ctx: AnyRecord) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
+  priority?: number;
+}
+interface PresetResult {
+  name: string;
+  /** Preset routes — merged into the resource's `routes` array. */
+  routes?: RouteDefinition[] | ((permissions: ResourcePermissions) => RouteDefinition[]);
+  middlewares?: MiddlewareConfig;
+  schemaOptions?: RouteSchemaOptions;
+  controllerOptions?: Record<string, unknown>;
+  hooks?: PresetHook[];
+}
+type PresetFunction = (config: ResourceConfig) => PresetResult;
+interface EventDefinition {
+  name: string;
+  /** Optional handler — events are published via `fastify.events.publish()`. */
+  handler?: (data: unknown) => Promise<void> | void;
+  /** JSON schema for event payload */
+  schema?: Record<string, unknown>;
+  description?: string;
+}
+/** Resource-level permissions — only `PermissionCheck` functions allowed. */
+interface ResourcePermissions {
+  list?: PermissionCheck;
+  get?: PermissionCheck;
+  create?: PermissionCheck;
+  update?: PermissionCheck;
+  delete?: PermissionCheck;
+}
+interface ResourceConfig<TDoc = AnyRecord> {
+  name: string;
+  displayName?: string;
+  tag?: string;
+  /** Defaults to `/${name}s` if not provided. */
+  prefix?: string;
+  /**
+   * Skip the global `resourcePrefix` from `createApp()`. The resource
+   * registers at its own `prefix` (or `/${name}s`) directly on root.
+   * Useful for webhooks, health, admin routes that shouldn't be under
+   * `/api/v1`.
+   *
+   * @example
+   * ```typescript
+   * defineResource({ name: 'webhook', prefix: '/webhooks', skipGlobalPrefix: true })
+   * ```
+   */
+  skipGlobalPrefix?: boolean;
+  /** Optional for service-pattern resources */
+  adapter?: DataAdapter<TDoc>;
+  /** Controller instance — accepts any object with CRUD methods. */
+  controller?: IController<TDoc> | ControllerLike;
+  queryParser?: unknown;
+  permissions?: ResourcePermissions;
+  schemaOptions?: RouteSchemaOptions;
+  openApiSchemas?: OpenApiSchemas;
+  /** Custom JSON schemas (override Arc-generated). */
+  customSchemas?: Partial<CrudSchemas>;
+  /** Preset names, objects, or PresetResult values. */
+  presets?: Array<string | PresetResult | {
+    name: string;
+    [key: string]: unknown;
+  }>;
+  hooks?: ResourceHooks;
+  /**
+   * Functional pipeline — guards, transforms, interceptors. Flat array
+   * (all operations) or per-operation map.
+   *
+   * @example
+   * ```typescript
+   * pipe: pipe(isActive, slugify, timing),
+   * pipe: { create: pipe(isActive, slugify), list: pipe(timing) },
+   * ```
+   */
+  pipe?: PipelineConfig;
+  /**
+   * Field-level permissions — control visibility and writability per role.
+   *
+   * @example
+   * ```typescript
+   * fields: {
+   *   salary: fields.visibleTo(['admin', 'hr']),
+   *   password: fields.hidden(),
+   * }
+   * ```
+   */
+  fields?: FieldPermissionMap;
+  /**
+   * Policy for requests that include fields the caller can't write.
+   *
+   * - `'reject'` (default, secure): 403 with the denied field names.
+   *   Surfaces misconfigurations and write-side permission violations
+   *   instead of silently dropping them.
+   * - `'strip'`: legacy silent-drop behaviour — only opt in when migrating
+   *   pre-2.9 code that relied on the permissive default.
+   */
+  onFieldWriteDenied?: "reject" | "strip";
+  middlewares?: MiddlewareConfig;
+  /**
+   * PreHandler guards auto-applied to **every** route on this resource
+   * (CRUD + custom + preset). Runs after auth/permissions, before
+   * per-route `preHandler`. Use for mode gates, tenant checks, feature
+   * flags — anything that applies to every endpoint.
+   */
+  routeGuards?: RouteHandlerMethod[];
+  /**
+   * Custom routes beyond CRUD. Presets also merge their routes here.
+   *
+   * @example
+   * ```typescript
+   * routes: [
+   *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
+   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
+   * ]
+   * ```
+   */
+  routes?: RouteDefinition[];
+  /**
+   * State-transition actions → unified `POST /:id/action` endpoint.
+   * Each action can be a bare handler or full config with permissions
+   * + schema.
+   *
+   * @example
+   * ```typescript
+   * actions: {
+   *   approve: async (id, data, req) => service.approve(id, req.user._id),
+   *   cancel: {
+   *     handler: async (id, data, req) => service.cancel(id, data.reason, req.user._id),
+   *     permissions: roles('admin'),
+   *     schema: { reason: { type: 'string' } },
+   *   },
+   * },
+   * actionPermissions: auth(),
+   * ```
+   */
+  actions?: ActionsMap;
+  /**
+   * Fallback permission for actions without per-action permissions.
+   * Only applies when `actions` is defined.
+   */
+  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', etc.
    */
   tenantField?: string | false;
+  /**
+   * Default sort applied to `list` responses when the request doesn't
+   * specify one. Arc's built-in default is `-createdAt` (Mongo convention).
+   *
+   *   - `string` — override (e.g. `'-created_at'`, `'-id'`).
+   *   - `false` — disable the default entirely. The adapter returns rows
+   *     in its native order (primary-key order on most kits). **Use this
+   *     for SQL/Drizzle resources that don't declare a `createdAt`
+   *     column** — without it, the framework default would compile to
+   *     `ORDER BY "createdAt" DESC` against a missing column.
+   *
+   * @example
+   * ```ts
+   * defineResource({ name: 'metric', defaultSort: '-recordedAt' });
+   * defineResource({ name: 'tag', defaultSort: false }); // no default sort
+   * ```
+   */
+  defaultSort?: string | false;
   /**
    * Primary key field name (default: '_id').
    *
@@ -1469,10 +2275,27 @@ interface ResourceConfig<TDoc = AnyRecord> {
 //#endregion
 //#region src/core/defineResource.d.ts
 /**
- * Define a resource with database adapter
+ * Define a resource with database adapter.
+ *
+ * This is the MAIN entry point for creating Arc resources — the adapter
+ * provides both repository and schema metadata.
+ *
+ * Staged into seven named phases so future refactors touch one phase at a
+ * time instead of threading changes through a 450-line function:
+ *
+ *   1. validate                  — fail-fast structural checks
+ *   2. resolveIdField            — auto-derive `idField` from repository
+ *   3. applyPresetsAndAutoInject — clone + apply presets + tenant-field rules
+ *   4. resolveController         — reuse user controller or auto-create BaseController
+ *   5. buildResource             — construct ResourceDefinition + validate methods
+ *   6. wireHooks                 — push preset + inline `config.hooks` onto _pendingHooks
+ *   7. resolveOpenApiSchemas     — adapter schemas → parser listQuery → user override
  *
- * This is the MAIN entry point for creating Arc resources.
- * The adapter provides both repository and schema metadata.
+ * Each phase has a single responsibility; `resolvedConfig` is the canonical
+ * post-preset, post-auto-inject config that every later phase reads. Raw
+ * `config` is only consulted for things presets don't touch (adapter,
+ * skipRegistry, skipValidation, hooks — which are wired separately from
+ * preset hooks).
  */
 declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
 interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
@@ -1529,7 +2352,7 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   _registryMeta?: RegisterOptions;
   constructor(config: ResolvedResourceConfig<TDoc>);
   /** Get repository from adapter (if available) */
-  get repository(): _$_classytic_repo_core_repository0.StandardRepo<TDoc> | RepositoryLike<TDoc> | undefined;
+  get repository(): RepositoryLike<TDoc> | undefined;
   _validateControllerMethods(): void;
   toPlugin(): FastifyPluginAsync;
   /**
@@ -1682,178 +2505,6 @@ type FastifyWithDecorators = FastifyInstance & {
 /** Handler signature for middleware functions. */
 type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
 //#endregion
-//#region src/types/auth.d.ts
-/**
- * JWT utilities provided to authenticator. Arc provides the helpers;
- * apps use them as needed.
- */
-interface JwtContext {
-  /** Verify a JWT token and return decoded payload */
-  verify: <T = Record<string, unknown>>(token: string) => T;
-  /** Sign a payload and return JWT token */
-  sign: (payload: Record<string, unknown>, options?: {
-    expiresIn?: string;
-  }) => string;
-  /** Decode without verification (for inspection) */
-  decode: <T = Record<string, unknown>>(token: string) => T | null;
-}
-/** Context passed to app's authenticator function. */
-interface AuthenticatorContext {
-  /** JWT utilities (available if `jwt.secret` provided) */
-  jwt: JwtContext | null;
-  /** Fastify instance for advanced use cases */
-  fastify: FastifyInstance;
-}
-/**
- * App-provided authenticator function. Arc calls this for every
- * non-public route. The app has full control over authentication logic.
- *
- * Return a user object to authenticate, `null`/`undefined` to reject.
- *
- * @example
- * ```typescript
- * authenticate: async (request, { jwt }) => {
- *   const token = request.headers.authorization?.split(' ')[1];
- *   if (!token || !jwt) return null;
- *   const decoded = jwt.verify(token);
- *   return userRepo.findById(decoded.id);
- * }
- * ```
- */
-type Authenticator = (request: FastifyRequest, context: AuthenticatorContext) => Promise<unknown | null> | unknown | null;
-/** Token pair returned by `issueTokens` helper. */
-interface TokenPair {
-  /** Access token (JWT) */
-  accessToken: string;
-  /** Refresh token (JWT with longer expiry) */
-  refreshToken?: string;
-  /** Access token expiry in seconds */
-  expiresIn: number;
-  /** Refresh token expiry in seconds */
-  refreshExpiresIn?: number;
-  /** Token type (always 'Bearer') */
-  tokenType: "Bearer";
-}
-/**
- * Auth helpers exposed on `fastify.auth`.
- *
- * @example
- * ```typescript
- * const tokens = fastify.auth.issueTokens({
- *   id: user._id,
- *   email: user.email,
- *   role: user.role,
- * });
- * return { success: true, ...tokens, user };
- * ```
- */
-interface AuthHelpers {
-  /** JWT utilities (if configured) */
-  jwt: JwtContext | null;
-  /**
-   * Issue access + refresh tokens for a user. App calls this after
-   * validating credentials.
-   */
-  issueTokens: (payload: Record<string, unknown>, options?: {
-    expiresIn?: string;
-    refreshExpiresIn?: string;
-  }) => TokenPair;
-  /** Verify a refresh token and return decoded payload. */
-  verifyRefreshToken: <T = Record<string, unknown>>(token: string) => T;
-}
-/**
- * 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;
-}
-//#endregion
 //#region src/types/plugins.d.ts
 interface GracefulShutdownOptions {
   timeout?: number;
@@ -1916,68 +2567,245 @@ interface CrudRouterOptions {
   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[];
+//#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;
 }
-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")[];
+/**
+ * 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/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
@@ -2015,23 +2843,26 @@ interface IntrospectionData {
   generatedAt?: string;
 }
 //#endregion
-//#region src/types/validation.d.ts
+//#region src/types/repository.d.ts
 /**
- * Validation result types — produced by `validateResourceConfig` and
- * consumed by `assertValidConfig` / `formatValidationErrors`.
+ * Discriminated union of pagination result shapes. Narrow on `method`.
+ *
+ * repo-core ships the individual shapes (`OffsetPaginationResult` /
+ * `KeysetPaginationResult`) but no combined union — arc needs one for the
+ * BaseController's `list` / `getDeleted` return signatures, where either
+ * shape is valid depending on the caller's pagination params.
+ *
+ * @example
+ * ```ts
+ * const result = await repo.getAll(params);
+ * if (result.method === 'keyset') {
+ *   result.next;     // keyset cursor
+ * } else {
+ *   result.page;     // offset number
+ * }
+ * ```
  */
-interface ConfigError {
-  field: string;
-  message: string;
-  code?: string;
-}
-interface ValidationResult {
-  valid: boolean;
-  errors: ConfigError[];
-}
-interface ValidateOptions {
-  strict?: boolean;
-}
+type PaginationResult<TDoc, TExtra extends Record<string, unknown> = Record<string, never>> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra>;
 //#endregion
 //#region src/types/utility.d.ts
 /**
@@ -2061,441 +2892,22 @@ type TypedResourceConfig<TDoc> = ResourceConfig<TDoc>;
 type TypedController<TDoc> = IController<TDoc>;
 type TypedRepository<TDoc> = StandardRepo<TDoc>;
 //#endregion
-//#region src/types/repository.d.ts
+//#region src/types/validation.d.ts
 /**
- * Discriminated union of pagination result shapes. Narrow on `method`.
- *
- * repo-core ships the individual shapes (`OffsetPaginationResult` /
- * `KeysetPaginationResult`) but no combined union — arc needs one for the
- * BaseController's `list` / `getDeleted` return signatures, where either
- * shape is valid depending on the caller's pagination params.
- *
- * @example
- * ```ts
- * const result = await repo.getAll(params);
- * if (result.method === 'keyset') {
- *   result.next;     // keyset cursor
- * } else {
- *   result.page;     // offset number
- * }
- * ```
- */
-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;
-  /**
-   * 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
-/**
- * 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.
+ * Validation result types — produced by `validateResourceConfig` and
+ * consumed by `assertValidConfig` / `formatValidationErrors`.
  */
-type FieldWriteDenialPolicy = "reject" | "strip";
-interface BodySanitizerConfig {
-  /** Schema options for field sanitization */
-  schemaOptions: RouteSchemaOptions;
-  /**
-   * What to do when a request contains fields the caller can't write.
-   * Default: `'reject'` — surface the misconfiguration as a 403.
-   */
-  onFieldWriteDenied?: FieldWriteDenialPolicy;
-}
-declare class BodySanitizer {
-  private schemaOptions;
-  private onFieldWriteDenied;
-  constructor(config: BodySanitizerConfig);
-  /**
-   * Strip readonly and system-managed fields from request body.
-   * Prevents clients from overwriting _id, timestamps, __v, etc.
-   *
-   * Also applies field-level write permissions when the request has
-   * field permission metadata.
-   */
-  sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
-}
-//#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;
+interface ConfigError {
+  field: string;
+  message: string;
+  code?: string;
 }
-//#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;
-  };
-  /**
-   * Policy for requests that include fields the caller can't write.
-   *
-   * - `'reject'` (default): 403 with the denied field names. Surfaces
-   *   misconfigurations and attempts to set protected fields instead of
-   *   silently dropping them.
-   * - `'strip'`: legacy silent-drop behaviour. Only opt in when migrating
-   *   code that relied on the pre-2.9 permissive default.
-   */
-  onFieldWriteDenied?: FieldWriteDenialPolicy;
+interface ValidationResult {
+  valid: boolean;
+  errors: ConfigError[];
 }
-/**
- * Framework-agnostic base controller implementing IController.
- *
- * Composes AccessControl, BodySanitizer, and QueryResolver for clean
- * separation of concerns. CRUD methods delegate directly to these
- * composed classes — no intermediate wrapper methods.
- *
- * @template TDoc - The document type
- * @template TRepository - The repository type (defaults to RepositoryLike)
- */
-declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
-  protected repository: TRepository;
-  protected schemaOptions: RouteSchemaOptions;
-  protected queryParser: QueryParserInterface;
-  protected maxLimit: number;
-  protected defaultLimit: number;
-  protected defaultSort: string;
-  protected resourceName?: string;
-  protected tenantField: string | false;
-  protected idField: string;
-  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
-  readonly accessControl: AccessControl;
-  /** Composable body sanitization (field permissions, system fields) */
-  readonly bodySanitizer: BodySanitizer;
-  /** Composable query resolution (parsing, pagination, sort, select/populate) */
-  readonly queryResolver: QueryResolver;
-  private _matchesFilter?;
-  private _presetFields;
-  private _cacheConfig?;
-  constructor(repository: TRepository, options?: BaseControllerOptions);
-  /**
-   * Get the tenant field name if multi-tenant scoping is enabled.
-   * Returns `undefined` when `tenantField` is `false` (platform-universal mode).
-   *
-   * Use this in subclass overrides instead of accessing `this.tenantField` directly
-   * to avoid TypeScript indexing errors with `string | false`.
-   */
-  protected getTenantField(): string | undefined;
-  /** Extract typed Arc internal metadata from request */
-  private meta;
-  /** Get hook system from request context (instance-scoped) */
-  private getHooks;
-  /**
-   * Resolve the repository primary key for mutation calls (update/delete/restore).
-   *
-   * When the resource declares a custom `idField` (e.g. `slug`, `jobId`, UUID),
-   * the default behavior is to translate the route id → the fetched doc's `_id`
-   * because most Mongo repositories key their mutation methods off `_id`.
-   *
-   * Exception: if the repository itself exposes a matching `idField` property
-   * (e.g. MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
-   * repository already knows how to look up by that field — so we pass the
-   * route id through unchanged and skip the translation.
-   *
-   * This makes `defineResource({ idField: 'id' })` work end-to-end with repos
-   * that natively support custom primary keys, without breaking the slug-style
-   * aliasing that Arc 2.6.3 introduced for repos keyed on `_id`.
-   */
-  private resolveRepoId;
-  /**
-   * Centralized 404 response builder. Maps the denial reason from
-   * `fetchDetailed()` into a structured `details.code` so consumers can
-   * programmatically distinguish "doc doesn't exist" from "doc filtered
-   * by policy/org scope" without parsing error strings.
-   *
-   * Error messages are intentionally vague in the `error` field (don't
-   * leak whether the doc exists) — the detail is in `details.code` only.
-   */
-  private notFoundResponse;
-  /** Resolve cache config for a specific operation, merging per-op overrides */
-  private resolveCacheConfig;
-  /**
-   * Extract user/org IDs from request for cache key scoping.
-   * Only includes orgId when this resource uses tenant-scoped data (tenantField is set).
-   * Universal resources (tenantField: false) get shared cache keys to avoid fragmentation.
-   */
-  private cacheScope;
-  list(req: IRequestContext): Promise<IControllerResponse<OffsetPaginationResult<TDoc>>>;
-  /** Execute list query through hooks (extracted for cache revalidation) */
-  private executeListQuery;
-  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  /** Execute get query through hooks (extracted for cache revalidation) */
-  private executeGetQuery;
-  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  delete(req: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-    id?: string;
-    soft?: boolean;
-  }>>;
-  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginationResult<TDoc>>>;
-  restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
-  getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
-  bulkCreate(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
-  /**
-   * Build a tenant-scoped filter for bulk update/delete.
-   *
-   * Mirrors `AccessControl.buildIdFilter` semantics for single-doc ops:
-   *   - Always merge `_policyFilters` (from permission middleware)
-   *   - When `tenantField` is set AND a `member` scope is present, add the
-   *     org filter so cross-tenant data can't be touched.
-   *   - When the scope is `elevated` (platform admin), no org filter is
-   *     applied — admins can bulk-update across orgs intentionally.
-   *   - When the scope is `public` on a tenant-scoped resource, deny.
-   *   - When NO scope is present at all (e.g., direct controller calls in
-   *     unit tests, or app routes without auth middleware), the controller
-   *     stays lenient — it's the middleware layer's job to fail-close.
-   *     Apps that want fail-close on bulk routes should run the multi-tenant
-   *     preset middleware (or equivalent) ahead of these handlers.
-   *
-   * Returns the merged filter, or `null` when access must be denied.
-   */
-  private buildBulkFilter;
-  /**
-   * Sanitize a bulk update data payload through the same write-permission
-   * pipeline as single-doc update(). Handles both shapes:
-   *
-   *   - Flat:           `{ name: 'x', status: 'y' }`
-   *   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 }, $unset: { tag: '' } }`
-   *
-   * For each operand, runs `bodySanitizer.sanitize('update', ...)` so that
-   * system fields, systemManaged/readonly/immutable rules, AND field-level
-   * write permissions are enforced. Without this, a tenant-scoped user could
-   * pass `{ $set: { organizationId: 'org-b' } }` to move records across orgs.
-   *
-   * Returns the sanitized payload along with the list of stripped fields for
-   * audit/error reporting.
-   */
-  private sanitizeBulkUpdateData;
-  bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
-    matchedCount: number;
-    modifiedCount: number;
-  }>>;
-  /**
-   * Bulk delete by `filter` or `ids`.
-   *
-   * Body shape (one of):
-   *   - `{ filter: { status: 'archived' } }`     — delete by query filter
-   *   - `{ ids: ['id1', 'id2', 'id3'] }`         — delete specific docs by id
-   *
-   * The `ids` form translates to `{ [idField]: { $in: ids } }` using the
-   * resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
-   * UUID, etc.). Tenant scope and policy filters are merged in either way,
-   * so cross-tenant deletes are blocked at the controller layer.
-   *
-   * Both forms perform a single `repo.deleteMany()` DB call — no per-doc
-   * fetch loop. Per-doc lifecycle hooks (`before:delete`/`after:delete`) do
-   * NOT fire for bulk operations; use the single-doc `delete()` if you need
-   * them, or subscribe to the bulk lifecycle event from the events plugin.
-   */
-  bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
-    deletedCount: number;
-  }>>;
+interface ValidateOptions {
+  strict?: boolean;
 }
 //#endregion
-export { CrudSchemas as $, HookPhase as $t, AuthHelpers as A, SchemaMetadata as At, FastifyWithDecorators as B, ArcInternalMetadata as Bt, ResourceMetadata as C, RouteHandler as Ct, HealthOptions as D, FieldMetadata as Dt, HealthCheck as E, DataAdapter as Et, TokenPair as F, OperationFilter as Ft, ResourceDefinition as G, PopulateOption as Gt, RequestWithExtras as H, LookupOption as Ht, ArcDecorator as I, PipelineConfig as It, ActionEntry as J, ServiceContext as Jt, defineResource as K, QueryParserInterface as Kt, EventsDecorator as L, PipelineContext as Lt, Authenticator as M, Guard as Mt, AuthenticatorContext as N, Interceptor as Nt, IntrospectionPluginOptions as O, RelationMetadata as Ot, JwtContext as P, NextFunction as Pt, CrudRouteKey as Q, HookOperation as Qt, FastifyRequestExtras as R, PipelineStep as Rt, RegistryStats as S, IRequestContext as St, GracefulShutdownOptions as T, AdapterSchemaContext as Tt, RegisterOptions as U, OwnershipCheck as Ut, MiddlewareHandler as V, ControllerQueryOptions as Vt, ResourceRegistry as W, ParsedQuery as Wt, ActionsMap as X, HookContext as Xt, ActionHandlerFn as Y, DefineHookOptions as Yt, CrudController as Z, HookHandler as Zt, ConfigError as _, UserOrganization as _n, ControllerHandler as _t, QueryResolverConfig as a, afterUpdate as an, PresetHook as at, IntrospectionData as b, IController as bt, AccessControl as c, beforeUpdate as cn, ResourceCacheConfig as ct, InferAdapterDoc as d, AnyRecord as dn, ResourceHooks as dt, HookRegistration as en, EventDefinition as et, InferDocType as f, ApiResponse as fn, ResourcePermissions as ft, TypedResourceConfig as g, UserLike as gn, RouteSchemaOptions as gt, TypedRepository as h, ObjectId as hn, RouteMethod as ht, QueryResolver as i, afterDelete as in, PresetFunction as it, AuthPluginOptions as j, ValidationResult$1 as jt, RequestIdOptions as k, RepositoryLike as kt, AccessControlConfig as l, createHookSystem as ln, ResourceConfig as lt, TypedController as m, JWTPayload as mn, RouteMcpConfig as mt, BaseController as n, HookSystemOptions as nn, MiddlewareConfig as nt, BodySanitizer as o, beforeCreate as on, PresetResult as ot, InferResourceDoc as p, ArcRequest as pn, RouteDefinition as pt, ActionDefinition as q, RequestContext as qt, BaseControllerOptions as r, afterCreate as rn, OpenApiSchemas as rt, BodySanitizerConfig as s, beforeDelete as sn, RateLimitConfig as st, RouteHandlerMethod$1 as t, HookSystem as tn, FieldRule as tt, PaginationResult as u, defineHook as un, ResourceHookContext as ut, ValidateOptions as v, envelope as vn, ControllerLike as vt, CrudRouterOptions as w, AdapterFactory as wt, RegistryEntry as x, IControllerResponse as xt, ValidationResult as y, getUserId as yn, FastifyHandler as yt, FastifyWithAuth as z, Transform as zt };
+export { OpenApiSchemas as $, ArcListResult as $t, RequestIdOptions as A, RelationMetadata as An, Authenticator as At, ResourceDefinition as B, UserOrganization as Bt, RequestContext as C, beforeUpdate as Cn, OperationFilter as Ct, HealthCheck as D, AdapterSchemaContext as Dn, Transform as Dt, GracefulShutdownOptions as E, AdapterFactory as En, PipelineStep as Et, FastifyWithDecorators as F, ApiResponse as Ft, ActionsMap as G, TreeMixin as Gt, ActionDefinition as H, SoftDeleteExt as Ht, MiddlewareHandler as I, ArcRequest as It, CrudRouteKey as J, BulkExt as Jt, ArcFieldRule as K, SlugExt as Kt, RequestWithExtras as L, JWTPayload as Lt, EventsDecorator as M, SchemaMetadata as Mn, JwtContext as Mt, FastifyRequestExtras as N, ValidationResult$1 as Nn, TokenPair as Nt, HealthOptions as O, DataAdapter as On, AuthHelpers as Ot, FastifyWithAuth as P, AnyRecord as Pt, MiddlewareConfig as Q, ArcGetResult as Qt, RegisterOptions as R, ObjectId as Rt, QueryParserInterface as S, beforeDelete as Sn, NextFunction as St, CrudRouterOptions as T, defineHook as Tn, PipelineContext as Tt, ActionEntry as U, SoftDeleteMixin as Ut, defineResource as V, BaseController as Vt, ActionHandlerFn as W, TreeExt as Wt, EventDefinition as X, ArcCreateResult as Xt, CrudSchemas as Y, BulkMixin as Yt, FieldRule$1 as Z, ArcDeleteResult as Zt, ControllerQueryOptions as _, HookSystemOptions as _n, IControllerResponse as _t, InferAdapterDoc as a, QueryResolverConfig as an, ResourceConfig as at, ParsedQuery as b, afterUpdate as bn, Guard as bt, TypedController as c, AccessControl as cn, ResourcePermissions as ct, PaginationResult as d, HookContext as dn, RouteMethod as dt, ArcUpdateResult as en, PresetFunction as et, IntrospectionData as f, HookHandler as fn, RouteSchemaOptions as ft, ArcInternalMetadata as g, HookSystem as gn, IController as gt, ResourceMetadata as h, HookRegistration as hn, FastifyHandler as ht, ValidationResult as i, QueryResolver as in, ResourceCacheConfig as it, ArcDecorator as j, RepositoryLike as jn, AuthenticatorContext as jt, IntrospectionPluginOptions as k, FieldMetadata as kn, AuthPluginOptions as kt, TypedRepository as l, AccessControlConfig as ln, RouteDefinition as lt, RegistryStats as m, HookPhase as mn, ControllerLike as mt, ConfigError as n, BaseCrudController as nn, PresetResult as nt, InferDocType as o, BodySanitizer as on, ResourceHookContext as ot, RegistryEntry as p, HookOperation as pn, ControllerHandler as pt, CrudController as q, SlugMixin as qt, ValidateOptions as r, ListResult as rn, RateLimitConfig as rt, InferResourceDoc as s, BodySanitizerConfig as sn, ResourceHooks as st, RouteHandlerMethod$1 as t, BaseControllerOptions as tn, PresetHook as tt, TypedResourceConfig as u, DefineHookOptions as un, RouteMcpConfig as ut, LookupOption as v, afterCreate as vn, IRequestContext as vt, ServiceContext as w, createHookSystem as wn, PipelineConfig as wt, PopulateOption as x, beforeCreate as xn, Interceptor as xt, OwnershipCheck as y, afterDelete as yn, RouteHandler as yt, ResourceRegistry as z, UserLike as zt };