@classytic/arc 2.10.8 → 2.11.0

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

@@ -1,17 +1,49 @@
+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/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.
+ * Arc's structural repository contract.
+ *
+ * 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:
+ *
+ *   - `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> = {
@@ -25,12 +57,13 @@ import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-
 type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
 interface DataAdapter<TDoc = unknown> {
   /**
-   * Repository implementing CRUD operations. Accepts the typed
-   * `StandardRepo<TDoc>` (repo-core's standard contract) or the structural
-   * `RepositoryLike` (minimum + optionals). Arc feature-detects optional
+   * 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: StandardRepo<TDoc> | RepositoryLike<TDoc>;
+  repository: RepositoryLike<TDoc>;
   /** Adapter identifier for introspection */
   readonly type: "mongoose" | "prisma" | "drizzle" | "typeorm" | "custom";
   /** Human-readable name */
@@ -114,6 +147,257 @@ interface ValidationResult$1 {
 }
 type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
 //#endregion
+//#region src/hooks/HookSystem.d.ts
+type HookPhase = "before" | "around" | "after";
+type HookOperation = "create" | "update" | "delete" | "restore" | "read" | "list";
+interface HookContext<T = AnyRecord> {
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  data?: T;
+  result?: T | T[];
+  user?: UserBase;
+  context?: RequestContext;
+  meta?: AnyRecord;
+}
+type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
+/**
+ * Around hook handler — wraps the core operation.
+ * Call `next()` to proceed to the next around hook or the actual operation.
+ */
+type AroundHookHandler<T = AnyRecord> = (ctx: HookContext<T>, next: () => Promise<T | undefined>) => T | undefined | Promise<T | undefined>;
+interface HookRegistration {
+  /** Hook name for dependency resolution and debugging */
+  name?: string;
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  handler: HookHandler;
+  priority: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+interface HookSystemOptions {
+  /** Custom logger for error/warning reporting. Defaults to console */
+  logger?: {
+    error: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+  };
+}
+declare class HookSystem {
+  private hooks;
+  private logger;
+  private warn;
+  constructor(options?: HookSystemOptions);
+  /**
+   * Generate hook key
+   */
+  private getKey;
+  /**
+   * Register a hook
+   * Supports both object parameter and positional arguments
+   */
+  register<T = AnyRecord>(resourceOrOptions: string | {
+    name?: string;
+    resource: string;
+    operation: HookOperation;
+    phase: HookPhase;
+    handler: HookHandler<T>;
+    priority?: number;
+    dependsOn?: string[];
+  }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register before hook
+   */
+  before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register after hook
+   */
+  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register around hook — wraps the core operation.
+   * Call `next()` inside the handler to proceed.
+   */
+  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
+  /**
+   * Execute around hooks as a nested middleware chain.
+   * Each around hook receives `next()` to call the next hook or the core operation.
+   */
+  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T | undefined>;
+  /**
+   * Execute hooks for a given context
+   */
+  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
+  /**
+   * Execute before hooks
+   */
+  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T>;
+  /**
+   * Execute after hooks
+   * Errors in after hooks are logged but don't fail the request
+   */
+  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<void>;
+  /**
+   * Topological sort with Kahn's algorithm.
+   * Hooks with `dependsOn` are ordered after their dependencies.
+   * Within the same dependency level, priority ordering is preserved.
+   * Hooks without names or dependencies pass through in their original order.
+   */
+  private topologicalSort;
+  /**
+   * Get all registered hooks
+   */
+  getAll(): HookRegistration[];
+  /**
+   * Get hooks for a specific resource
+   */
+  getForResource(resource: string): HookRegistration[];
+  /**
+   * Get hooks matching filter criteria.
+   * Useful for debugging and testing specific hook combinations.
+   *
+   * @example
+   * ```typescript
+   * // Find all before-create hooks for products (including wildcards)
+   * const hooks = hookSystem.getRegistered({
+   *   resource: 'product',
+   *   operation: 'create',
+   *   phase: 'before',
+   * });
+   * ```
+   */
+  getRegistered(filter?: {
+    resource?: string;
+    operation?: HookOperation;
+    phase?: HookPhase;
+  }): HookRegistration[];
+  /**
+   * Get a structured summary of all registered hooks for debugging.
+   *
+   * @example
+   * ```typescript
+   * const info = hookSystem.inspect();
+   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
+   * ```
+   */
+  inspect(): {
+    total: number;
+    resources: Record<string, HookRegistration[]>;
+    summary: Array<{
+      name?: string;
+      key: string;
+      priority: number;
+      dependsOn?: string[];
+    }>;
+  };
+  /**
+   * Check if any hooks exist for a specific resource/operation/phase combination.
+   */
+  has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
+  /**
+   * Clear all hooks
+   */
+  clear(): void;
+  /**
+   * Clear hooks for a specific resource
+   */
+  clearResource(resource: string): void;
+}
+/**
+ * Create a new isolated HookSystem instance
+ *
+ * Use this for:
+ * - Test isolation (parallel test suites)
+ * - Multiple app instances with independent hooks
+ *
+ * @example
+ * const hooks = createHookSystem();
+ * await app.register(arcCorePlugin, { hookSystem: hooks });
+ *
+ * @example With custom logger
+ * const hooks = createHookSystem({ logger: fastify.log });
+ */
+declare function createHookSystem(options?: HookSystemOptions): HookSystem;
+interface DefineHookOptions<T = AnyRecord> {
+  /** Unique hook name (required for dependency resolution) */
+  name: string;
+  /** Target resource */
+  resource: string;
+  /** CRUD operation */
+  operation: HookOperation;
+  /** before or after */
+  phase: HookPhase;
+  /** Hook handler */
+  handler: HookHandler<T>;
+  /** Priority (lower = earlier, default: 10) */
+  priority?: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+/**
+ * Define a named hook with optional dependencies.
+ * Returns a registration object — call `register(hookSystem)` to activate.
+ *
+ * @example
+ * ```typescript
+ * const generateSlug = defineHook({
+ *   name: 'generateSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   handler: (ctx) => ({ ...ctx.data, slug: slugify(ctx.data.name) }),
+ * });
+ *
+ * const validateUniqueSlug = defineHook({
+ *   name: 'validateUniqueSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   dependsOn: ['generateSlug'],
+ *   handler: async (ctx) => { // check uniqueness },
+ * });
+ *
+ * // Register on a hook system
+ * generateSlug.register(hooks);
+ * validateUniqueSlug.register(hooks);
+ * ```
+ */
+declare function defineHook<T = AnyRecord>(options: DefineHookOptions<T>): DefineHookOptions<T> & {
+  register: (hooks: HookSystem) => () => void;
+};
+/**
+ * Create a before-create hook registration for a given hook system
+ */
+declare function beforeCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-create hook registration for a given hook system
+ */
+declare function afterCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-update hook registration for a given hook system
+ */
+declare function beforeUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-update hook registration for a given hook system
+ */
+declare function afterUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-delete hook registration for a given hook system
+ */
+declare function beforeDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-delete hook registration for a given hook system
+ */
+declare function afterDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+//#endregion
 //#region src/core/AccessControl.d.ts
 /** Denial reason codes returned by `fetchDetailed()`. */
 type FetchDenialReason = "NOT_FOUND" | "POLICY_FILTERED" | "ORG_SCOPE_DENIED";
@@ -330,26 +614,55 @@ declare class QueryResolver {
   private getBlockedFields;
 }
 //#endregion
-//#region src/core/BaseController.d.ts
+//#region src/core/BaseCrudController.d.ts
 /**
  * Union of every return shape repo-core's `MinimalRepo.getAll()` is
- * contractually allowed to produce. Keeping arc's list surface in sync
- * with that contract (v2.10.6) — previously arc narrowed to
- * `OffsetPaginationResult<TDoc>` and treated bare arrays as
- * "non-conforming," which drifted from repo-core's published shape.
- *
- * - `OffsetPaginationResult<TDoc>` — when the query uses offset pagination
- *   (`page` parameter).
- * - `KeysetPaginationResult<TDoc>` — when the query uses keyset/cursor
- *   pagination (`sort` + optional `after`).
- * - `TDoc[]` — raw array when neither drives pagination; valid per
- *   repo-core's `MinimalRepo.getAll` docstring.
- *
- * Arc passes the kit's response verbatim; callers / consumers should
- * narrow on shape (`Array.isArray(result)` → bare array, presence of
- * `page`/`total` → offset, presence of `nextCursor` → keyset).
+ * 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.
  */
 type ListResult<TDoc> = OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[];
+/**
+ * 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 ArcControllerLike = {
+  list: (...args: any[]) => unknown;
+  get: (...args: any[]) => unknown;
+  create: (...args: any[]) => unknown;
+  update: (...args: any[]) => unknown;
+  delete: (...args: any[]) => unknown;
+};
+/**
+ * Return type of the controller's `list` method.
+ *
+ * @example
+ * ```ts
+ * 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 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;
@@ -365,19 +678,9 @@ interface BaseControllerOptions {
   defaultLimit?: number;
   /**
    * Default sort applied when the request doesn't specify one.
-   *
-   *   - `string` (default: `'-createdAt'`) — sort descending on the field.
-   *     Uses the Mongo convention `-fieldName` for DESC; matches the
-   *     mongokit / mongokit-sort parser. Applied only if the resource's
-   *     schema actually has the column.
-   *   - `false` — disable the default sort. Requests that pass no `sort`
-   *     get whatever order the adapter returns (PK order on most kits).
-   *     **Use this for SQL/Drizzle resources that don't declare a
-   *     `createdAt` column** — the default would otherwise compile to
-   *     `ORDER BY "createdAt" DESC` against a missing column.
-   *
-   * The `-createdAt` default is kept for back-compat with existing
-   * mongokit users; going forward, set this explicitly per resource.
+   *   - `string` (default: `'-createdAt'`) — Mongo `-field` DESC convention.
+   *   - `false` — disable the default sort entirely (SQL/Drizzle resources
+   *     without a `createdAt` column).
    */
   defaultSort?: string | false;
   /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
@@ -389,22 +692,13 @@ interface BaseControllerOptions {
    */
   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).
+   * 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.).
-   * Falls back to built-in MongoDB-style matching if not provided.
    */
   matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
   /** Cache configuration for the resource */
@@ -416,26 +710,22 @@ interface BaseControllerOptions {
   };
   /**
    * 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.
+   * - `'reject'` (default): 403 with denied field names.
+   * - `'strip'`: legacy silent-drop.
    */
   onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
 /**
- * Framework-agnostic base controller implementing IController.
+ * Framework-agnostic CRUD 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.
+ * 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)
+ * @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> {
+declare class BaseCrudController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
   protected repository: TRepository;
   protected schemaOptions: RouteSchemaOptions;
   protected queryParser: QueryParserInterface;
@@ -450,95 +740,226 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
   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?;
+  /**
+   * 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);
   /**
-   * Get the tenant field name if multi-tenant scoping is enabled.
-   * Returns `undefined` when `tenantField` is `false` (platform-universal mode).
+   * 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.
    *
-   * Use this in subclass overrides instead of accessing `this.tenantField` directly
-   * to avoid TypeScript indexing errors with `string | false`.
+   * 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.
    *
-   * **Why this exists:** repo plugins (e.g. `@classytic/mongokit`'s
-   * `multiTenantPlugin`) read tenant scope from the TOP of the repository
-   * operation context — `context.organizationId`, not `context.data.organizationId`
-   * or `context.context.organizationId`. Without this stamping, a tenant-scoped
-   * repository throws `Missing 'organizationId' in context for '<op>'` even
-   * though arc already injected the tenant into the request body.
-   *
-   * **What this returns:**
-   * - `{ [tenantField]: orgId }` when the resource is tenant-scoped and the
-   *   caller's scope carries an org ID (member, service key bound to an org,
-   *   elevated admin impersonating an org).
-   * - `{}` otherwise — platform-universal resources (`tenantField: false`),
-   *   public/anonymous reads, elevated admins without an org target.
+   * 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.
    *
-   * **Call sites:** every `this.repository.*` CRUD entry — `create`, `update`,
-   * `delete`, `getAll` (via list), plus merged into `QueryOptions` for the
-   * access-controlled read path (`accessControl.fetchDetailed` → `getById`/`getOne`).
-   *
-   * **Name of the field:** uses the instance's own `tenantField` configuration
-   * (default `organizationId`). Matches mongokit's `multiTenantPlugin` default
-   * `contextKey` so host apps don't need to override either side.
-   *
-   * Multi-field tenancy (via `multiTenantPreset({ tenantFields: [...] })`)
-   * resolves additional fields at middleware time and stashes them on
-   * `_tenantFields` — {@link tenantRepoOptions} merges those in too.
+   * Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
+   * requests, `{}` otherwise. Merges multi-field tenancy from
+   * `_tenantFields` (populated by `multiTenantPreset`).
    */
-  private tenantRepoOptions;
+  protected tenantRepoOptions(req: IRequestContext): AnyRecord;
   /** Extract typed Arc internal metadata from request */
-  private meta;
+  protected meta(req: IRequestContext): ArcInternalMetadata | undefined;
   /** Get hook system from request context (instance-scoped) */
-  private getHooks;
+  protected getHooks(req: IRequestContext): HookSystem | null;
   /**
-   * 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`.
+   * Resolve the repository primary key for mutation calls.
    *
-   * 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.
+   * 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`.
    *
-   * 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`.
+   * 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.
    */
-  private resolveRepoId;
+  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
-   * 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.
+   * distinguish "doc doesn't exist" from "doc filtered by policy/org scope"
+   * without parsing error strings.
    */
-  private notFoundResponse;
+  protected notFoundResponse(reason?: FetchDenialReason | null): IControllerResponse<never>;
   /** Resolve cache config for a specific operation, merging per-op overrides */
-  private resolveCacheConfig;
+  protected resolveCacheConfig(operation: "list" | "byId"): QueryCacheConfig | null;
   /**
    * 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.
+   * Only includes orgId when the resource uses tenant-scoped data (tenantField is set).
+   * Universal resources (tenantField: false) get shared cache keys.
    */
-  private cacheScope;
+  protected cacheScope(req: IRequestContext): {
+    userId?: string;
+    orgId?: string;
+  };
   list(req: IRequestContext): Promise<IControllerResponse<ListResult<TDoc>>>;
   /** Execute list query through hooks (extracted for cache revalidation) */
-  private executeListQuery;
+  protected executeListQuery(options: ParsedQuery, req: IRequestContext): Promise<ListResult<TDoc>>;
   get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
   /** Execute get query through hooks (extracted for cache revalidation) */
-  private executeGetQuery;
+  protected executeGetQuery(id: string, options: ParsedQuery, req: IRequestContext): Promise<{
+    doc: TDoc | null;
+    reason: FetchDenialReason | null;
+  }>;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+    id?: string;
+    soft?: boolean;
+  }>>;
+}
+//#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;
+  }>>;
+}
+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>>;
+}
+declare function SlugMixin<TBase extends Constructor$2<BaseCrudController>>(Base: TBase): TBase & Constructor$2<SlugExt>;
+//#endregion
+//#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
+/**
+ * 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 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<{
@@ -546,72 +967,30 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
     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[]>>;
+  getBySlug(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;
   }>>;
 }
+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);
+/**
+ * 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.
+ */
+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" {
@@ -655,8 +1034,6 @@ type ObjectId = string | {
 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;
@@ -697,22 +1074,6 @@ type ArcRequest = FastifyRequest & {
   user: Record<string, unknown> | undefined;
   signal: AbortSignal;
 };
-/**
- * Wrap data in Arc's standard `{ success: true, data }` envelope.
- *
- * @example
- * ```typescript
- * handler: async (req, reply) => {
- *   const data = await getResults();
- *   return envelope(data);  // → { success: true, data }
- * }
- * ```
- */
-declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
-  success: true;
-  data: T;
-  [key: string]: unknown;
-};
 //#endregion
 //#region src/types/auth.d.ts
 /**
@@ -1285,60 +1646,138 @@ interface RateLimitConfig {
   /** Time window for rate limiting (e.g., '1 minute', '15 seconds') */
   timeWindow: string;
 }
-interface RouteSchemaOptions {
+/**
+ * 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 {
+  /**
+   * When `true`, bypass the `systemManaged` / `readonly` / `immutable`
+   * strip in `BodySanitizer` for callers whose request scope is
+   * `elevated`. Lets platform admins stamp the value from the request
+   * body — needed for cross-tenant admin writes where the tenant field
+   * is the only way to pick a target org.
+   *
+   * Auto-set by `defineResource` on the configured `tenantField`. Hosts
+   * can set it manually on other fields (e.g. `createdBy`) if they want
+   * elevation-only override semantics for those too.
+   *
+   * Has no effect when `isElevated(scope)` is false — member and
+   * service callers continue to have the field stripped.
+   */
+  preserveForElevated?: boolean;
+  hidden?: boolean;
+  /** 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).
+   *
+   * 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.
+   */
+  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[];
   /**
-   * Fields allowed for filtering in list operations. MCP auto-derives
-   * from `QueryParser.allowedFilterFields` when not set explicitly.
-   */
-  filterableFields?: string[];
-  fieldRules?: Record<string, {
-    systemManaged?: boolean;
-    /**
-     * When `true`, bypass the `systemManaged` / `readonly` / `immutable`
-     * strip in `BodySanitizer` for callers whose request scope is
-     * `elevated`. Lets platform admins stamp the value from the request
-     * body — needed for cross-tenant admin writes where the tenant field
-     * is the only way to pick a target org.
-     *
-     * Auto-set by `defineResource` on the configured `tenantField`. Hosts
-     * can set it manually on other fields (e.g. `createdBy`) if they want
-     * elevation-only override semantics for those too.
-     *
-     * Has no effect when `isElevated(scope)` is false — member and
-     * service callers continue to have the field stripped.
-     */
-    preserveForElevated?: boolean;
-    hidden?: boolean;
-    immutable?: boolean;
-    immutableAfterCreate?: boolean;
-    optional?: boolean; /** String minimum length — auto-maps to OpenAPI `minLength` and MCP tool schema */
-    minLength?: number; /** String maximum length — auto-maps to OpenAPI `maxLength` and MCP tool schema */
-    maxLength?: number; /** Number minimum — auto-maps to OpenAPI `minimum` and MCP tool schema */
-    min?: number; /** Number maximum — auto-maps to OpenAPI `maximum` and MCP tool schema */
-    max?: number; /** Regex pattern — auto-maps to OpenAPI `pattern` and MCP tool schema */
-    pattern?: string; /** Allowed values — auto-maps to OpenAPI `enum` and MCP tool schema */
-    enum?: ReadonlyArray<string | number>; /** Human-readable description — auto-maps to OpenAPI `description` */
-    description?: string;
-    [key: string]: unknown;
-  }>;
-  /** Query parameter schema for OpenAPI */
-  query?: Record<string, unknown>;
+   * Fields allowed for filtering in list operations. MCP auto-derives
+   * from `QueryParser.allowedFilterFields` when not set explicitly.
+   *
+   * 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.
+   */
+  filterableFields?: string[];
   /**
-   * 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.
+   * 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`).
+   *
+   * 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`.
    */
-  strictAdditionalProperties?: boolean;
+  fieldRules?: Record<string, ArcFieldRule>;
 }
-interface FieldRule {
+interface FieldRule$1 {
   field: string;
   required?: boolean;
   readonly?: boolean;
@@ -1834,263 +2273,29 @@ interface ResourceConfig<TDoc = AnyRecord> {
   };
 }
 //#endregion
-//#region src/hooks/HookSystem.d.ts
-type HookPhase = "before" | "around" | "after";
-type HookOperation = "create" | "update" | "delete" | "restore" | "read" | "list";
-interface HookContext<T = AnyRecord> {
-  resource: string;
-  operation: HookOperation;
-  phase: HookPhase;
-  data?: T;
-  result?: T | T[];
-  user?: UserBase;
-  context?: RequestContext;
-  meta?: AnyRecord;
-}
-type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
-/**
- * Around hook handler — wraps the core operation.
- * Call `next()` to proceed to the next around hook or the actual operation.
- */
-type AroundHookHandler<T = AnyRecord> = (ctx: HookContext<T>, next: () => Promise<T | undefined>) => T | undefined | Promise<T | undefined>;
-interface HookRegistration {
-  /** Hook name for dependency resolution and debugging */
-  name?: string;
-  resource: string;
-  operation: HookOperation;
-  phase: HookPhase;
-  handler: HookHandler;
-  priority: number;
-  /** Names of hooks that must execute before this one */
-  dependsOn?: string[];
-}
-interface HookSystemOptions {
-  /** Custom logger for error/warning reporting. Defaults to console */
-  logger?: {
-    error: (message: string, ...args: unknown[]) => void;
-    warn?: (message: string, ...args: unknown[]) => void;
-  };
-}
-declare class HookSystem {
-  private hooks;
-  private logger;
-  private warn;
-  constructor(options?: HookSystemOptions);
-  /**
-   * Generate hook key
-   */
-  private getKey;
-  /**
-   * Register a hook
-   * Supports both object parameter and positional arguments
-   */
-  register<T = AnyRecord>(resourceOrOptions: string | {
-    name?: string;
-    resource: string;
-    operation: HookOperation;
-    phase: HookPhase;
-    handler: HookHandler<T>;
-    priority?: number;
-    dependsOn?: string[];
-  }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
-  /**
-   * Register before hook
-   */
-  before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
-  /**
-   * Register after hook
-   */
-  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
-  /**
-   * Register around hook — wraps the core operation.
-   * Call `next()` inside the handler to proceed.
-   */
-  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
-  /**
-   * Execute around hooks as a nested middleware chain.
-   * Each around hook receives `next()` to call the next hook or the core operation.
-   */
-  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<T | undefined>;
-  /**
-   * Execute hooks for a given context
-   */
-  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
-  /**
-   * Execute before hooks
-   */
-  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<T>;
-  /**
-   * Execute after hooks
-   * Errors in after hooks are logged but don't fail the request
-   */
-  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-  }): Promise<void>;
-  /**
-   * Topological sort with Kahn's algorithm.
-   * Hooks with `dependsOn` are ordered after their dependencies.
-   * Within the same dependency level, priority ordering is preserved.
-   * Hooks without names or dependencies pass through in their original order.
-   */
-  private topologicalSort;
-  /**
-   * Get all registered hooks
-   */
-  getAll(): HookRegistration[];
-  /**
-   * Get hooks for a specific resource
-   */
-  getForResource(resource: string): HookRegistration[];
-  /**
-   * Get hooks matching filter criteria.
-   * Useful for debugging and testing specific hook combinations.
-   *
-   * @example
-   * ```typescript
-   * // Find all before-create hooks for products (including wildcards)
-   * const hooks = hookSystem.getRegistered({
-   *   resource: 'product',
-   *   operation: 'create',
-   *   phase: 'before',
-   * });
-   * ```
-   */
-  getRegistered(filter?: {
-    resource?: string;
-    operation?: HookOperation;
-    phase?: HookPhase;
-  }): HookRegistration[];
-  /**
-   * Get a structured summary of all registered hooks for debugging.
-   *
-   * @example
-   * ```typescript
-   * const info = hookSystem.inspect();
-   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
-   * ```
-   */
-  inspect(): {
-    total: number;
-    resources: Record<string, HookRegistration[]>;
-    summary: Array<{
-      name?: string;
-      key: string;
-      priority: number;
-      dependsOn?: string[];
-    }>;
-  };
-  /**
-   * Check if any hooks exist for a specific resource/operation/phase combination.
-   */
-  has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
-  /**
-   * Clear all hooks
-   */
-  clear(): void;
-  /**
-   * Clear hooks for a specific resource
-   */
-  clearResource(resource: string): void;
-}
-/**
- * Create a new isolated HookSystem instance
- *
- * Use this for:
- * - Test isolation (parallel test suites)
- * - Multiple app instances with independent hooks
- *
- * @example
- * const hooks = createHookSystem();
- * await app.register(arcCorePlugin, { hookSystem: hooks });
- *
- * @example With custom logger
- * const hooks = createHookSystem({ logger: fastify.log });
- */
-declare function createHookSystem(options?: HookSystemOptions): HookSystem;
-interface DefineHookOptions<T = AnyRecord> {
-  /** Unique hook name (required for dependency resolution) */
-  name: string;
-  /** Target resource */
-  resource: string;
-  /** CRUD operation */
-  operation: HookOperation;
-  /** before or after */
-  phase: HookPhase;
-  /** Hook handler */
-  handler: HookHandler<T>;
-  /** Priority (lower = earlier, default: 10) */
-  priority?: number;
-  /** Names of hooks that must execute before this one */
-  dependsOn?: string[];
-}
+//#region src/core/defineResource.d.ts
 /**
- * Define a named hook with optional dependencies.
- * Returns a registration object — call `register(hookSystem)` to activate.
+ * Define a resource with database adapter.
  *
- * @example
- * ```typescript
- * const generateSlug = defineHook({
- *   name: 'generateSlug',
- *   resource: 'product', operation: 'create', phase: 'before',
- *   handler: (ctx) => ({ ...ctx.data, slug: slugify(ctx.data.name) }),
- * });
+ * This is the MAIN entry point for creating Arc resources — the adapter
+ * provides both repository and schema metadata.
  *
- * const validateUniqueSlug = defineHook({
- *   name: 'validateUniqueSlug',
- *   resource: 'product', operation: 'create', phase: 'before',
- *   dependsOn: ['generateSlug'],
- *   handler: async (ctx) => { // check uniqueness },
- * });
+ * Staged into seven named phases so future refactors touch one phase at a
+ * time instead of threading changes through a 450-line function:
  *
- * // Register on a hook system
- * generateSlug.register(hooks);
- * validateUniqueSlug.register(hooks);
- * ```
- */
-declare function defineHook<T = AnyRecord>(options: DefineHookOptions<T>): DefineHookOptions<T> & {
-  register: (hooks: HookSystem) => () => void;
-};
-/**
- * Create a before-create hook registration for a given hook system
- */
-declare function beforeCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Create an after-create hook registration for a given hook system
- */
-declare function afterCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Create a before-update hook registration for a given hook system
- */
-declare function beforeUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Create an after-update hook registration for a given hook system
- */
-declare function afterUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Create a before-delete hook registration for a given hook system
- */
-declare function beforeDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Create an after-delete hook registration for a given hook system
- */
-declare function afterDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
-//#endregion
-//#region src/core/defineResource.d.ts
-/**
- * Define a resource with database adapter
+ *   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> {
@@ -2147,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;
   /**
@@ -2705,4 +2910,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { beforeCreate as $, ObjectId as $t, RequestIdOptions as A, FastifyHandler as At, ResourceDefinition as B, PipelineContext as Bt, RequestContext as C, ResourcePermissions as Ct, HealthCheck as D, RouteSchemaOptions as Dt, GracefulShutdownOptions as E, RouteMethod as Et, FastifyWithDecorators as F, Guard as Ft, HookOperation as G, Authenticator as Gt, DefineHookOptions as H, Transform as Ht, MiddlewareHandler as I, Interceptor as It, HookSystem as J, TokenPair as Jt, HookPhase as K, AuthenticatorContext as Kt, RequestWithExtras as L, NextFunction as Lt, EventsDecorator as M, IControllerResponse as Mt, FastifyRequestExtras as N, IRequestContext as Nt, HealthOptions as O, ControllerHandler as Ot, FastifyWithAuth as P, RouteHandler as Pt, afterUpdate as Q, JWTPayload as Qt, RegisterOptions as R, OperationFilter as Rt, QueryParserInterface as S, ResourceHooks as St, CrudRouterOptions as T, RouteMcpConfig as Tt, HookContext as U, AuthHelpers as Ut, defineResource as V, PipelineStep as Vt, HookHandler as W, AuthPluginOptions as Wt, afterCreate as X, ApiResponse as Xt, HookSystemOptions as Y, AnyRecord as Yt, afterDelete as Z, ArcRequest as Zt, ControllerQueryOptions as _, RepositoryLike as _n, PresetResult as _t, InferAdapterDoc as a, BaseControllerOptions as an, ActionEntry as at, ParsedQuery as b, ResourceConfig as bt, TypedController as c, BodySanitizer as cn, CrudController as ct, PaginationResult as d, AccessControlConfig as dn, EventDefinition as dt, UserLike as en, beforeDelete as et, IntrospectionData as f, AdapterFactory as fn, FieldRule as ft, ArcInternalMetadata as g, RelationMetadata as gn, PresetHook as gt, ResourceMetadata as h, FieldMetadata as hn, PresetFunction as ht, ValidationResult as i, BaseController as in, ActionDefinition as it, ArcDecorator as j, IController as jt, IntrospectionPluginOptions as k, ControllerLike as kt, TypedRepository as l, BodySanitizerConfig as ln, CrudRouteKey as lt, RegistryStats as m, DataAdapter as mn, OpenApiSchemas as mt, ConfigError as n, envelope as nn, createHookSystem as nt, InferDocType as o, QueryResolver as on, ActionHandlerFn as ot, RegistryEntry as p, AdapterSchemaContext as pn, MiddlewareConfig as pt, HookRegistration as q, JwtContext as qt, ValidateOptions as r, getUserId as rn, defineHook as rt, InferResourceDoc as s, QueryResolverConfig as sn, ActionsMap as st, RouteHandlerMethod$1 as t, UserOrganization as tn, beforeUpdate as tt, TypedResourceConfig as u, AccessControl as un, CrudSchemas as ut, LookupOption as v, SchemaMetadata as vn, RateLimitConfig as vt, ServiceContext as w, RouteDefinition as wt, PopulateOption as x, ResourceHookContext as xt, OwnershipCheck as y, ValidationResult$1 as yn, ResourceCacheConfig as yt, ResourceRegistry as z, PipelineConfig as zt };
+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 };