@classytic/arc 2.11.4 → 2.14.0

package/dist/{index-CXXRbnf8.d.mts → index-BtW7qYwa.d.mts}

@@ -1,198 +1,15 @@
 import { a as QueryCacheConfig } from "./QueryCache-D41bfdBB.mjs";
-import { r as RequestScope } from "./types-DDyTPc6y.mjs";
-import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-BRjxOAFp.mjs";
-import { n as DomainEvent } from "./EventTransport-CYNUXdCJ.mjs";
-import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
+import { i as RequestScope } from "./types-CTYvcwHe.mjs";
+import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-COhcH3fk.mjs";
+import { n as DomainEvent } from "./EventTransport-CT_52aWU.mjs";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
-import { MinimalRepo, QueryOptions, StandardRepo } from "@classytic/repo-core/repository";
+import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
+import * as _$_classytic_repo_core_adapter0 from "@classytic/repo-core/adapter";
+import { DataAdapter, RepositoryLike } from "@classytic/repo-core/adapter";
+import { AggDateBucket, AggMeasure, AggTopN, QueryOptions, StandardRepo } from "@classytic/repo-core/repository";
+import { LookupSpec } from "@classytic/repo-core/lookup";
 import { FieldRule, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 
-//#region src/adapters/interface.d.ts
-/**
- * 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> = {
- *   repository: myRepo,      // any MinimalRepo<Product> — kit-agnostic
- *   type: 'drizzle',         // or 'mongoose' | 'prisma' | 'custom'
- *   name: 'products',
- * };
- * defineResource({ adapter, ... });
- * ```
- */
-type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
-/**
- * Permissive structural input accepted at every adapter factory boundary.
- *
- * Wider than `RepositoryLike<TDoc>` on `getAll`'s `params`/`options` —
- * uses method-shorthand syntax with `unknown` so kit-native repositories
- * (mongokit's `Repository<TDoc>`, sqlitekit, prismakit) plug in directly,
- * without `as RepositoryLike<TDoc>` casts on the host.
- *
- * **Why this exists.** repo-core 0.2 widened `MinimalRepo['getAll']`'s
- * `params.filters` to a `Filter | Record<string, unknown>` IR union, but
- * concrete kit `Repository` classes still type `filters` as the narrower
- * `Record<string, unknown>`. Under `strictFunctionTypes` the kit's narrower
- * function-property `getAll` is no longer assignable to the IR-aware one,
- * which forced every host adapter glue file to write
- * `repository as unknown as RepositoryLike<TDoc>`.
- *
- * Adapter factories accept this permissive shape, then call
- * `asRepositoryLike()` once to widen for arc internals (audit, outbox,
- * idempotency stores still see the strict `RepositoryLike` view). The
- * documented escape hatch lives in arc, not at every host call site.
- */
-interface AdapterRepositoryInput<TDoc = unknown> {
-  readonly idField?: string;
-  getAll(params?: unknown, options?: unknown): Promise<unknown>;
-  getById(id: string, options?: unknown): Promise<TDoc | null>;
-  create(data: Partial<TDoc>, options?: unknown): Promise<TDoc>;
-  update(id: string, data: Partial<TDoc>, options?: unknown): Promise<TDoc | null>;
-  delete(id: string, options?: unknown): Promise<{
-    success: boolean;
-    message: string;
-    id?: string;
-    soft?: boolean;
-    count?: number;
-  }>;
-}
-/**
- * Widen a permissive `AdapterRepositoryInput<TDoc>` to arc's strict
- * `RepositoryLike<TDoc>` view. Single-source escape hatch for the
- * filter-IR drift documented on `AdapterRepositoryInput`.
- *
- * Arc internals (audit / outbox / idempotency, BaseController) still see
- * the IR-aware `RepositoryLike`; only the call paths arc exercises are
- * shared between the two views, and those use the narrower
- * `Record<string, unknown>` filter shape both sides agree on.
- */
-declare function asRepositoryLike<TDoc = unknown>(input: AdapterRepositoryInput<TDoc>): RepositoryLike<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>;
-}
-/**
- * Context passed to `adapter.generateSchemas()` so adapters shape output
- * to match resource-level configuration. All fields optional — adapters
- * that ignore this still work; arc applies safety-net normalization.
- */
-interface AdapterSchemaContext {
-  /** The idField configured on the resource. Defaults to "_id". */
-  idField?: string;
-  /** Resource name (for error messages / logging). */
-  resourceName?: string;
-}
-interface SchemaMetadata {
-  name: string;
-  fields: Record<string, FieldMetadata>;
-  indexes?: Array<{
-    fields: string[];
-    unique?: boolean;
-    sparse?: boolean;
-  }>;
-  relations?: Record<string, RelationMetadata>;
-}
-interface FieldMetadata {
-  type: "string" | "number" | "boolean" | "date" | "object" | "array" | "objectId" | "enum";
-  required?: boolean;
-  unique?: boolean;
-  default?: unknown;
-  enum?: Array<string | number>;
-  min?: number;
-  max?: number;
-  minLength?: number;
-  maxLength?: number;
-  pattern?: string;
-  description?: string;
-  ref?: string;
-  array?: boolean;
-}
-interface RelationMetadata {
-  type: "one-to-one" | "one-to-many" | "many-to-many";
-  target: string;
-  foreignKey?: string;
-  through?: string;
-}
-interface ValidationResult$1 {
-  valid: boolean;
-  errors?: Array<{
-    field: string;
-    message: string;
-    code?: string;
-  }>;
-}
-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";
@@ -605,6 +422,67 @@ declare class BodySanitizer {
   sanitize(body: AnyRecord, _operation: "create" | "update", req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
 }
 //#endregion
+//#region src/core/controllerTypes.d.ts
+/**
+ * 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.
+ */
+type ListResult<TDoc> = OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[];
+/**
+ * Discrete cache states reported via the `x-cache` response header.
+ *
+ * - `'HIT'`   — fresh cache entry served, no upstream call made.
+ * - `'STALE'` — stale entry served, upstream refresh scheduled in the background.
+ * - `'MISS'`  — no cache entry; upstream call ran and the result was cached.
+ *
+ * Exported as a literal union so test code and downstream clients can
+ * import + narrow without restating the literal triple.
+ */
+type CacheStatus = "HIT" | "STALE" | "MISS";
+/**
+ * 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"]>;
+//#endregion
 //#region src/core/QueryResolver.d.ts
 interface QueryResolverConfig {
   /** Query parser instance (default: Arc built-in parser) */
@@ -635,6 +513,13 @@ declare class QueryResolver {
   private schemaOptions;
   private tenantField;
   constructor(config?: QueryResolverConfig);
+  /**
+   * Swap the underlying parser. Mutates in place so the resolver instance
+   * stays referentially stable (hosts capturing a `queryResolver` ref via
+   * `defineResource({ controller })` keep that ref valid). Single source of
+   * truth — pairs with `BaseCrudController.setQueryParser()`.
+   */
+  setParser(parser: QueryParserInterface): void;
   /**
    * Resolve a request into parsed query options -- ONE parse per request.
    * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
@@ -661,54 +546,6 @@ declare class QueryResolver {
 }
 //#endregion
 //#region src/core/BaseCrudController.d.ts
-/**
- * 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.
- */
-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;
@@ -724,8 +561,8 @@ interface BaseControllerOptions {
   defaultLimit?: number;
   /**
    * 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
+   *   - `string` (default: `'-createdAt'`) — Mongo `-field` DESC convention.
+   *   - `false` — disable the default sort entirely (SQL/Drizzle resources
    *     without a `createdAt` column).
    */
   defaultSort?: string | false;
@@ -777,8 +614,6 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
   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;
@@ -789,7 +624,7 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
   /**
    * Composable query resolution (parsing, pagination, sort, select/populate).
    *
-   * Not `readonly` — `setQueryParser()` rebuilds this resolver to swap in a
+   * 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`.
@@ -803,18 +638,15 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
   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.
+   * Swap the controller's query parser. Mutates the existing `QueryResolver`
+   * in place via `QueryResolver.setParser()` — the resolver instance stays
+   * referentially stable, and there is no second copy of `defaultSort` /
+   * `tenantField` / `schemaOptions` for the swap to drift away from.
    *
    * 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.
+   * forwarded the parser only to auto-constructed controllers. `defineResource`
+   * calls this via duck-typing when both `controller` and `queryParser` are
+   * supplied; controllers that don't implement it are left untouched.
    */
   setQueryParser(queryParser: QueryParserInterface): void;
   /**
@@ -823,17 +655,39 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    */
   protected getTenantField(): string | undefined;
   /**
-   * Build top-level tenant options to thread into the repository call.
+   * Build the canonical repo-options bag from the Fastify request.
+   *
+   * Forwards the cross-kit canonical set (see repo-core's
+   * `STANDARD_REPO_OPTION_KEYS`) into every CRUD repo call so kit
+   * plugins (multi-tenant, audit, audit-trail, observability) get
+   * what they need without per-resource wiring:
+   *
+   * - **Tenant scope** — `[tenantField]: orgId` from `RequestScope`.
+   *   Plugin-scoped repos (mongokit's `multiTenantPlugin`) read tenant
+   *   scope from the TOP of the options bag, not `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.
+   *   Multi-field tenancy from `_tenantFields` (populated by
+   *   `multiTenantPreset`) is merged in.
    *
-   * 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.
+   * - **Audit attribution** — `userId` + `user` from the authenticated
+   *   actor. Mongokit's audit-log / audit-trail plugins read these
+   *   into the `who` column; sqlitekit's audit plugin reads the same
+   *   names. No host-side forwarding needed.
    *
-   * Returns `{ [tenantField]: orgId }` for tenant-scoped + org-carrying
-   * requests, `{}` otherwise. Merges multi-field tenancy from
-   * `_tenantFields` (populated by `multiTenantPreset`).
+   * - **Trace correlation** — `requestId` from Fastify's request id
+   *   for stitching logs / events / downstream calls.
+   *
+   * - **`session` is intentionally NOT auto-set.** Sessions are tied
+   *   to explicit transaction scopes the controller doesn't manage;
+   *   pass `session` inline at the call site when running inside a
+   *   `withTransaction` helper.
+   *
+   * Method kept named `tenantRepoOptions` for back-compat with hosts
+   * that spread `...this.tenantRepoOptions(req)` (10+ call sites in
+   * arc, plus host overrides). The bag has always grown over time —
+   * hosts that don't want audit forwarding never read those keys.
    */
   protected tenantRepoOptions(req: IRequestContext): AnyRecord;
   /** Extract typed Arc internal metadata from request */
@@ -844,21 +698,40 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    * 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`
+   * 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.
+   * 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.
+   * Read-side preflight for mutable-target operations (`update`, `delete`).
+   *
+   * Bundles the four steps that every mutation must do before touching the
+   * repo: (1) extract `:id`, (2) fetch under access control + tenant scope,
+   * (3) verify ownership, (4) translate the route id to the repo's primary
+   * key. Returning `{id, existing, repoId}` keeps the call sites a single
+   * line and makes drift between `update` and `delete` structurally
+   * impossible — there is one preflight, one denial-reason mapping, one
+   * ownership check.
+   *
+   * Pass `extraFetchOptions` for callers (e.g. soft-delete restore) that
+   * need to widen the fetch (`{ includeDeleted: true }`).
    */
-  protected notFoundResponse(reason?: FetchDenialReason | null): IControllerResponse<never>;
+  protected loadMutableTarget(req: IRequestContext, extraFetchOptions?: AnyRecord): Promise<{
+    id: string;
+    existing: TDoc;
+    repoId: string;
+  }>;
+  /**
+   * Centralized 404 thrower. Maps the denial reason from `fetchDetailed()`
+   * into a `NotFoundError` so consumers can distinguish "doc doesn't
+   * exist" from "doc filtered by policy/org scope" via the error
+   * `details.code` set by the global error handler.
+   */
+  protected throwNotFound(reason?: FetchDenialReason | null): never;
   /** Resolve cache config for a specific operation, merging per-op overrides */
   protected resolveCacheConfig(operation: "list" | "byId"): QueryCacheConfig | null;
   /**
@@ -870,7 +743,86 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
     userId?: string;
     orgId?: string;
   };
+  /** Shared `x-cache` response envelope builder. */
+  protected cacheResponse<T>(data: T, cacheStatus: CacheStatus): IControllerResponse<T>;
+  /** Required route-id helper shared by get/update/delete. Throws on missing id. */
+  protected requireIdParam(req: IRequestContext): string;
+  /**
+   * Normalizes `repo.exists()` return shapes across adapters. Per
+   * StandardRepo's contract, `exists` may return `boolean`, `{ _id }`,
+   * or `null` — every truthy non-null shape collapses to `true`.
+   */
+  protected isExistsTruthy(result: unknown): boolean;
+  /**
+   * Run `executeBefore` then `executeAround` (or just the executor if no
+   * hooks are wired). Returns the around-phase result directly. Throws an
+   * `ArcError` (status 400, code `BEFORE_<OP>_HOOK_ERROR`) when the
+   * before-hook fails — the global error handler emits the canonical
+   * `ErrorContract` shape.
+   *
+   * The caller runs `executeAfter` separately via `runAfterHook` — typically
+   * after success-checking the result (delete checks `isDeleteSuccess`,
+   * update checks `if (!item)`).
+   *
+   * **Knobs:**
+   *   - `meta` — passed verbatim into `executeBefore` / `executeAround` opts.
+   *   - `pipeProcessedData` (default `true`) — whether `executeBefore`'s
+   *     return value flows into `executeAround` as the data parameter.
+   *     Set `false` for delete (current behaviour: discards before's
+   *     return, passes original input to around).
+   */
+  protected runHookedOpUntilResult<TInput, TResult>(req: IRequestContext, args: {
+    op: "create" | "update" | "delete";
+    input: TInput;
+    meta?: Record<string, unknown>;
+    pipeProcessedData?: boolean;
+  }, executor: (processed: TInput) => Promise<TResult>): Promise<TResult>;
+  /**
+   * Run `executeAfter` for the given op + data. No-op when hooks aren't
+   * wired or `resourceName` isn't set. Caller passes the data shape it
+   * wants downstream after-handlers to receive — typically the result for
+   * create/update, the original input (`existing`) for delete.
+   */
+  protected runAfterHook(req: IRequestContext, op: "create" | "update" | "delete", data: AnyRecord, meta?: Record<string, unknown>): Promise<void>;
+  /** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
+  protected withListCache(req: IRequestContext, options: ParsedQuery): Promise<IControllerResponse<ListResult<TDoc>> | null>;
+  /** Cached `get()` flow with SWR semantics. Returns null when cache is disabled. */
+  protected withGetCache(req: IRequestContext, id: string, options: ParsedQuery): Promise<IControllerResponse<TDoc> | null>;
   list(req: IRequestContext): Promise<IControllerResponse<ListResult<TDoc>>>;
+  /**
+   * Resource-dispatch verbs router. Returns `null` when the request is
+   * a regular list query, otherwise returns the dispatch promise.
+   *
+   * Verbs (mutually exclusive — first match wins):
+   *   - `?_count=true` → `{ count: number }` via `repo.count()`
+   *   - `?_distinct=field` → `unknown[]` via `repo.distinct(field)`
+   *   - `?_exists=true` → `{ exists: boolean }` via `repo.exists()`
+   *
+   * All verbs share the resolved filter (parsed query + policy filters
+   * + tenant scope). Adapters that don't ship the underlying repo
+   * method get a `501` so failures surface loudly instead of falling
+   * back to a full table scan.
+   */
+  protected dispatchResourceVerb(req: IRequestContext): Promise<IControllerResponse<unknown>> | null;
+  /** Resolve filter + tenant/audit options for a dispatch verb. */
+  private resolveDispatchScope;
+  /** `?_count=true` → `repo.count(filter)` */
+  protected dispatchCount(req: IRequestContext): Promise<IControllerResponse<{
+    count: number;
+  }>>;
+  /** `?_distinct=field` → `repo.distinct(field, filter)` */
+  protected dispatchDistinct(req: IRequestContext, field: string): Promise<IControllerResponse<unknown[]>>;
+  /** `?_exists=true` → `repo.exists(filter)` */
+  protected dispatchExists(req: IRequestContext): Promise<IControllerResponse<{
+    exists: boolean;
+  }>>;
+  /**
+   * True when `field` is safe to expose via `_distinct`. Mirrors the
+   * `select` allowlist — fields marked `hidden` or `systemManaged` in
+   * `schemaOptions.fieldRules` are NOT exposed (would leak password
+   * hashes, internal flags, etc).
+   */
+  protected isFieldExposedForRead(field: string): boolean;
   /** Execute list query through hooks (extracted for cache revalidation) */
   protected executeListQuery(options: ParsedQuery, req: IRequestContext): Promise<ListResult<TDoc>>;
   get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
@@ -999,7 +951,7 @@ declare function SoftDeleteMixin<TBase extends Constructor<BaseCrudController>>(
  *
  * 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>> {
+interface BaseController<TDoc extends AnyRecord = AnyRecord, _TRepository extends RepositoryLike = RepositoryLike<TDoc>> {
   readonly accessControl: AccessControl;
   readonly bodySanitizer: BodySanitizer;
   queryResolver: QueryResolver;
@@ -1034,8 +986,8 @@ declare const BaseController_base: (new (repository: any, options?: BaseControll
  * 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];
+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
@@ -1355,6 +1307,283 @@ type PipelineConfig = PipelineStep[] | {
   [operation: string]: PipelineStep[] | undefined;
 };
 //#endregion
+//#region src/core/aggregation/types.d.ts
+/**
+ * Sugar for measures: `'count'` / `'count:field'` / `'sum:price'` /
+ * `'avg:rating'` / `'min:created'` / `'max:updated'` /
+ * `'countDistinct:userId'` / `'percentile:latency:0.95'`.
+ *
+ * Compiles to the canonical `AggMeasure` IR at boot. Hosts who want
+ * the full IR can pass an `AggMeasure` object directly.
+ *
+ * **Percentile.** `'percentile:<field>:<p>'` where `p` is a numeric
+ * literal in `[0, 1]` (e.g. `'percentile:latency:0.95'` for P95).
+ * Mongokit (≥3.13) compiles to `$percentile`; sqlitekit throws
+ * `UnsupportedOperationError` (no native percentile in SQLite).
+ */
+type AggMeasureShorthand = "count" | `count:${string}` | `countDistinct:${string}` | `sum:${string}` | `avg:${string}` | `min:${string}` | `max:${string}` | `percentile:${string}:${number}`;
+/** Either canonical IR or shorthand string — both compile to `AggMeasure`. */
+type AggMeasureInput = AggMeasure | AggMeasureShorthand;
+/**
+ * Cache config for an aggregation. Translates directly to the kit-side
+ * `CacheOptions` (TanStack-shaped) which the unified
+ * `@classytic/repo-core/cache` plugin reads from `req.cache`.
+ *
+ * Caching only fires when the kit's repo has the `cachePlugin` wired —
+ * arc declares the policy; the kit handles SWR + tag invalidation +
+ * version-bump on writes. Hosts without the plugin installed silently
+ * fall through to a non-cached call.
+ */
+interface AggregationCacheConfig {
+  /** Seconds the entry is fresh — no revalidation while inside this window. */
+  staleTime?: number;
+  /** Seconds the entry stays in cache past stale before eviction. Default: 60. */
+  gcTime?: number;
+  /**
+   * Stale-while-revalidate. When stale entries serve immediately and a
+   * background refresh updates the cache. Default: `true` for
+   * aggregations (dashboards almost always benefit from stale-serve).
+   */
+  swr?: boolean;
+  /**
+   * Group invalidation tags. Pass to `repo.cache?.invalidateByTags(tags)`
+   * after a write to clear matching entries. The model name is
+   * auto-tagged by the plugin — you only declare cross-cutting tags
+   * (e.g. `'pricing'` to invalidate every aggregation that depends on
+   * pricing across multiple resources).
+   */
+  tags?: readonly string[];
+}
+/**
+ * Per-aggregation rate limit. Layers on top of any global rate limit
+ * via `@fastify/rate-limit` route-level config.
+ */
+interface AggregationRateLimit {
+  /** Max requests per window. */
+  max: number;
+  /** Window in milliseconds. */
+  windowMs: number;
+}
+/**
+ * Required date-range narrowing. Caller MUST send a bounded range on
+ * this field, and the range MUST NOT exceed `maxRangeDays`.
+ *
+ * Prevents "all-time" scans on billion-row collections — the single
+ * biggest performance footgun for live aggregation endpoints.
+ */
+interface AggregationDateRangeRequirement {
+  /** Field whose range the caller must narrow (e.g. `'createdAt'`). */
+  field: string;
+  /**
+   * Cap on the queryable range. A request asking for >N days is
+   * rejected 400. Omit for "any range, but bounded" (lower + upper
+   * required, no cap).
+   */
+  maxRangeDays?: number;
+}
+/**
+ * Boot-time index hint. Arc warns when the kit's schema doesn't have
+ * an index whose leading keys match — flags the misconfig before
+ * traffic hits the DB.
+ *
+ * Documented intent, NOT runtime-enforced. Kits with their own index
+ * introspection (mongokit reads Mongoose schema, sqlitekit reads
+ * Drizzle indexes) can act on the hint; kits without introspection
+ * silently accept it.
+ */
+interface AggregationIndexHint {
+  /** Leading-key columns the host expects the planner to use. */
+  leadingKeys: readonly string[];
+}
+/**
+ * Runtime context passed to the `materialized` hook.
+ *
+ * The hook returns pre-computed data instead of running the live
+ * aggregation. Hosts use this for ultra-frequent dashboards backed by
+ * rollup tables maintained out-of-band (cron / CDC).
+ */
+interface AggregationMaterializedContext {
+  /** Compiled filter (host base + tenant + caller). */
+  filter: AnyRecord;
+  /** Tenant id when the resource is tenant-scoped. */
+  orgId?: string;
+  /** Authenticated user id, when present. */
+  userId?: string;
+  /** Fastify request id for tracing. */
+  requestId?: string;
+  /** Raw URL query params (post-validation). */
+  query: Record<string, unknown>;
+}
+/** Materialized hook return shape — same envelope as `AggResult`. */
+interface AggregationMaterializedResult<TRow = AnyRecord> {
+  rows: readonly TRow[];
+}
+/**
+ * Single named aggregation declaration. Composes into `AggRequest` at
+ * request time, with safety knobs layered on at the arc-handler level.
+ */
+interface AggregationConfig {
+  /**
+   * Pre-aggregate filter on the BASE rows (before lookups). Always
+   * ANDed with auto-injected tenant scope + caller URL-narrowing
+   * filters. Use for host-defined invariants (e.g. `archived: false`).
+   */
+  filter?: AnyRecord;
+  /**
+   * Cross-table joins. Each `LookupSpec` reuses the IR
+   * `@classytic/repo-core/lookup` defines for `lookupPopulate()`.
+   * Same compile path the kit already ships.
+   *
+   * **Kit support is incremental.** A kit's `aggregate()` may not yet
+   * compile lookups — boot validation against the adapter version
+   * surfaces this loud, so hosts pin the kit major they need.
+   */
+  lookups?: readonly LookupSpec[];
+  /**
+   * Group key(s). Dotted paths into joined aliases supported when
+   * `lookups` is set: `'category.parent'` groups by the joined
+   * `category` row's `parent` field.
+   */
+  groupBy?: string | readonly string[];
+  /**
+   * Time-bucket group keys for time-series aggregations. Each entry
+   * promotes a date column into a synthetic group key bucketed at
+   * the chosen interval. The map key becomes a column on the output
+   * row holding the canonical ISO-shaped bucket label
+   * (`'2026-04'` for month, `'2026-W15'` for ISO week, etc.).
+   *
+   * Bucketed keys participate in grouping the same way `groupBy`
+   * columns do — `sort: { month: 1 }`, `having`, pagination, and
+   * `topN.partitionBy` all treat them as first-class.
+   *
+   * Aliases must NOT collide with a `groupBy` field name or measure
+   * alias — boot validation throws on collision.
+   *
+   * @example "Daily revenue for the last quarter"
+   * ```ts
+   * dailyRevenue: defineAggregation({
+   *   dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+   *   measures: { revenue: 'sum:totalPrice' },
+   *   sort: { day: 1 },
+   *   permissions: requireRoles(['admin']),
+   * }),
+   * ```
+   *
+   * @example "15-minute traffic buckets (custom-bin form)"
+   * ```ts
+   * traffic: defineAggregation({
+   *   dateBuckets: {
+   *     slot: { field: 'ts', interval: { every: 15, unit: 'minute' } },
+   *   },
+   *   measures: { hits: 'count' },
+   *   permissions: allowPublic(),
+   * }),
+   * ```
+   */
+  dateBuckets?: Record<string, AggDateBucket>;
+  /** Named aggregations. At least one entry required. */
+  measures: Record<string, AggMeasureInput>;
+  /**
+   * Post-aggregate filter referencing measure aliases.
+   * Example: `{ revenue: { gt: 1000 } }` → `HAVING revenue > 1000`.
+   */
+  having?: AnyRecord;
+  /** Order grouped rows by groupBy field, measure alias, or joined-alias path. */
+  sort?: Record<string, 1 | -1>;
+  /** Hard cap on result rows. Applied at the IR level (LIMIT / `$limit`). */
+  limit?: number;
+  /**
+   * Top-N-per-group filter. Keeps only the top `limit` rows per
+   * partition, ranked by `sortBy`. The classic "top 3 products per
+   * category" / "top 5 customers per region" dashboard primitive.
+   *
+   * Composes with `having` / `sort` — applies AFTER group + measures +
+   * having, so `partitionBy` and `sortBy` may reference groupBy fields,
+   * dateBucket aliases, or measure aliases. The top-level `sort` orders
+   * the final row set across partitions.
+   *
+   * **Per-kit support.** Mongokit compiles to `$setWindowFields` (Mongo 5+,
+   * runs in-engine — scales). Sqlitekit post-processes in JS (fine for
+   * typical dashboards; prefer mongokit for >100k groups). See
+   * `AggTopN` for full semantics.
+   */
+  topN?: AggTopN;
+  /**
+   * Permission check. **REQUIRED.** Aggregations are read-shape but
+   * different from list (different threat model — measures may expose
+   * cardinality info even when individual rows are hidden). Boot error
+   * if missing.
+   */
+  permissions: PermissionCheck;
+  /**
+   * DB-level execution cap (ms). Mongokit threads to `maxTimeMS`;
+   * sqlitekit threads to per-statement timeout where supported.
+   * Default: kit's default (typically none).
+   */
+  timeout?: number;
+  /**
+   * Reject 422 if the result row count exceeds this cap. Better than
+   * silent truncation — caller knows the dashboard is incomplete.
+   * Default: no cap (use `limit` for truncation semantics).
+   */
+  maxGroups?: number;
+  /**
+   * Caller MUST provide filters on these fields (else 400 at request).
+   * Use to require a tenant-side narrowing the host can't infer
+   * (segment id, customer id, etc.).
+   */
+  requireFilters?: readonly string[];
+  /**
+   * Caller MUST send a bounded date range on this field. Prevents
+   * all-time scans on billion-row collections.
+   */
+  requireDateRange?: AggregationDateRangeRequirement;
+  /**
+   * Documented index expectation. Arc warns at boot when the kit
+   * exposes index introspection and no matching index exists. NOT
+   * runtime-enforced — purely a misconfig signal.
+   */
+  indexHint?: AggregationIndexHint;
+  /**
+   * Per-aggregation cache. Tenant-scoped keys; invalidates with the
+   * resource's cache namespace + any explicit `tags`.
+   */
+  cache?: AggregationCacheConfig;
+  /**
+   * Per-route rate limit. Wired to `@fastify/rate-limit` when the
+   * plugin is registered.
+   */
+  rateLimit?: AggregationRateLimit;
+  /**
+   * Pre-computed read replacement. When set, arc skips
+   * `repo.aggregate()` and calls this function instead. Same wire
+   * shape, same permissions, different data source.
+   *
+   * Use for homepage-counter dashboards backed by host-managed rollup
+   * tables (cron / CDC). The hook receives the compiled context
+   * (filter + scope) so the host can route the lookup to the right
+   * pre-aggregated bucket.
+   */
+  materialized?: (ctx: AggregationMaterializedContext) => Promise<AggregationMaterializedResult>;
+  /** Optional summary rendered in OpenAPI + MCP tool description. */
+  summary?: string;
+  /** Optional longer description for OpenAPI / MCP. */
+  description?: string;
+  /**
+   * MCP tool generation control. Mirrors `actions[name].mcp` semantics.
+   *
+   *   - `undefined` (default) — generate an MCP tool for this aggregation
+   *   - `false` — skip MCP tool generation (REST route still works)
+   *   - `{ description?, annotations? }` — generate with overrides
+   */
+  mcp?: boolean | {
+    readonly description?: string;
+    readonly annotations?: Record<string, unknown>;
+  };
+}
+/** Map of name → declaration. Keys become URL segments under `/aggregations/<name>`. */
+type AggregationsMap = Record<string, AggregationConfig>;
+//#endregion
 //#region src/types/handlers.d.ts
 /**
  * Minimal server accessor — exposes safe, read-only server decorators.
@@ -1514,30 +1743,29 @@ interface IRequestContext<TBody = unknown, TParams extends Record<string, string
    * 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 };
+   *   return { data: result };
    * }
    * ```
    */
   server?: ServerAccessor;
 }
 /**
- * Standard response from controller handlers
+ * Controller response shape — the success-path return from any handler.
+ *
+ * Errors throw `ArcError` (or any `HttpError`-shaped class); the global
+ * error handler catches them and emits an `ErrorContract`. There is no
+ * `success` discriminator on the response — HTTP status is the wire
+ * discriminator (2xx = data, 4xx/5xx = ErrorContract).
  */
 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) */
+  /** Response payload — emitted directly to the wire (no envelope wrap). */
+  data: T;
+  /** HTTP status code. Defaults to 200. */
   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) */
+  /** Custom response headers (e.g. X-Total-Count, Link, ETag). */
   headers?: Record<string, string>;
+  /** Top-level metadata merged into list-shaped responses (e.g. `{ took }`). */
+  meta?: Record<string, unknown>;
 }
 /**
  * Controller handler — Arc's standard pattern.
@@ -1560,7 +1788,7 @@ interface IControllerResponse<T = unknown> {
  * // 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 };
+ *   return { data: product, status: 201 };
  * };
  *
  * // Fully typed — body, params, query, and response all inferred
@@ -1572,7 +1800,7 @@ interface IControllerResponse<T = unknown> {
  * > = async (req) => {
  *   const upsert = req.query.upsert === "true";
  *   const product = await productRepo.update(req.params.id, req.body, { upsert });
- *   return { success: true, data: product };
+ *   return { data: product };
  * };
  *
  * routes: [{
@@ -2116,9 +2344,9 @@ interface ResourceHookContext {
  * ```
  */
 interface ResourceHooks {
-  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | undefined> | AnyRecord | undefined;
   afterCreate?: (ctx: ResourceHookContext) => Promise<void> | void;
-  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | void> | AnyRecord | void;
+  beforeUpdate?: (ctx: ResourceHookContext) => Promise<AnyRecord | undefined> | AnyRecord | undefined;
   afterUpdate?: (ctx: ResourceHookContext) => Promise<void> | void;
   beforeDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
   afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
@@ -2270,6 +2498,31 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * Only applies when `actions` is defined.
    */
   actionPermissions?: PermissionCheck;
+  /**
+   * Declarative aggregations (v2.13) — generate `GET /:resource/aggregations/:name`
+   * routes from the portable `AggRequest` IR. Each entry pins permissions,
+   * filters, lookups, measures, sort, limit, plus big-data safety knobs
+   * (timeout, maxGroups, requireDateRange, indexHint, materialized).
+   *
+   * @example
+   * ```ts
+   * defineResource({
+   *   name: 'order',
+   *   aggregations: {
+   *     revenueByStatus: defineAggregation({
+   *       groupBy: 'status',
+   *       measures: { count: 'count', revenue: 'sum:totalPrice' },
+   *       permissions: requireRoles(['admin']),
+   *       requireDateRange: { field: 'createdAt', maxRangeDays: 90 },
+   *       timeout: 5000,
+   *       maxGroups: 1000,
+   *       cache: { staleTime: 60 },
+   *     }),
+   *   },
+   * });
+   * ```
+   */
+  aggregations?: AggregationsMap;
   disableCrud?: boolean;
   disableDefaultRoutes?: boolean;
   /** Specific routes to disable */
@@ -2360,31 +2613,13 @@ interface ResourceConfig<TDoc = AnyRecord> {
   };
 }
 //#endregion
-//#region src/core/defineResource.d.ts
+//#region src/core/defineResource/ResourceDefinition.d.ts
 /**
- * Define a resource with database adapter.
- *
- * This is the MAIN entry point for creating Arc resources — the adapter
- * provides both repository and schema metadata.
- *
- * 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
- *
- * 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).
+ * Constructor input shape — `ResourceConfig` plus the metadata
+ * Phases 3-6 stamp on it. Defined locally because the class
+ * constructor is the only consumer; no other code path needs this
+ * type.
  */
-declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
 interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
   _appliedPresets?: string[];
   _controllerOptions?: {
@@ -2404,6 +2639,7 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   readonly displayName: string;
   readonly tag: string;
   readonly prefix: string;
+  readonly skipGlobalPrefix: boolean;
   readonly adapter?: DataAdapter<TDoc>;
   readonly controller?: IController<TDoc>;
   readonly schemaOptions: RouteSchemaOptions;
@@ -2413,9 +2649,10 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   readonly middlewares: MiddlewareConfig;
   readonly routeGuards?: RouteHandlerMethod$1[];
   readonly disableDefaultRoutes: boolean;
-  readonly disabledRoutes: CrudRouteKey[];
+  readonly disabledRoutes: readonly CrudRouteKey[];
   readonly actions?: ActionsMap;
   readonly actionPermissions?: PermissionCheck;
+  readonly aggregations?: AggregationsMap;
   readonly events: Record<string, EventDefinition>;
   readonly rateLimit?: RateLimitConfig | false;
   readonly audit?: boolean | {
@@ -2425,7 +2662,6 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   readonly pipe?: PipelineConfig;
   readonly fields?: FieldPermissionMap;
   readonly cache?: ResourceCacheConfig;
-  readonly skipGlobalPrefix: boolean;
   readonly tenantField?: string | false;
   readonly idField?: string;
   readonly queryParser?: QueryParserInterface;
@@ -2437,32 +2673,78 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
     priority: number;
   }>;
   _registryMeta?: RegisterOptions;
+  /**
+   * Per-host idempotency guard used by `buildResourcePlugin` to
+   * skip duplicate shared-state writes when the same resource is
+   * mounted at multiple prefixes (`/v1`, `/v2`). See the plugin
+   * file for the full rationale; surfaced here as `readonly` so
+   * the helper can consult it without a class-method indirection.
+   */
+  readonly _sharedStateRegisteredOn: WeakSet<object>;
   constructor(config: ResolvedResourceConfig<TDoc>);
-  /** Get repository from adapter (if available) */
-  get repository(): RepositoryLike<TDoc> | undefined;
+  /** Repository accessor — pulled off the adapter when one is wired. */
+  get repository(): _$_classytic_repo_core_adapter0.RepositoryLike<TDoc> | undefined;
+  /**
+   * Validate that the wired controller implements every method
+   * needed by enabled CRUD routes + every string-handler custom
+   * route. Runs at the end of `defineResource()` (skippable via
+   * `skipValidation: true`) so misconfigured resources fail at
+   * boot, not on first request.
+   */
   _validateControllerMethods(): void;
-  toPlugin(): FastifyPluginAsync;
   /**
-   * Get event definitions for registry
+   * Build the Fastify plugin that materialises this resource into
+   * routes, hooks, registry entries, and cache invalidation rules.
+   * One-line delegate — the implementation lives in `./plugin.ts`.
    */
+  toPlugin(): FastifyPluginAsync;
+  /** Event definitions for registry consumption. */
   getEvents(): Array<{
     name: string;
     module: string;
     schema?: unknown;
     description?: string;
   }>;
-  /**
-   * Get resource metadata
-   */
+  /** Resource metadata — shape consumed by registry / introspection. */
   getMetadata(): ResourceMetadata;
 }
 //#endregion
+//#region src/core/defineResource.d.ts
+/**
+ * `TDoc` is **unconstrained** at this layer. The previous `TDoc
+ * extends AnyRecord` bound leaked out of `BaseController`'s
+ * mixin-composition requirement into every host's adapter boundary:
+ * Mongoose's `HydratedDocument<T>`, Prisma's generated row types,
+ * and any domain interface without an explicit index signature all
+ * failed to satisfy `Record<string, unknown>` even though at runtime
+ * they ARE string-keyed objects. Hosts were forced to cast at every
+ * adapter (`as RepositoryLike<Record<string, unknown>>`) — a type
+ * escape with no runtime purpose, since arc's pipeline only reads
+ * known envelope fields.
+ *
+ * The cast moved inside `resolveOrAutoCreateController` where
+ * `BaseController<TDoc extends AnyRecord>` actually requires it.
+ * One internal boundary cast replaces N host-side casts.
+ */
+declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
+//#endregion
 //#region src/registry/ResourceRegistry.d.ts
 interface RegisterOptions {
   module?: string;
   /** Pre-generated OpenAPI schemas */
   openApiSchemas?: OpenApiSchemas;
 }
+/**
+ * One enumerated wire route. Matches `ResourceMetadata.routes[]`'s shape so
+ * it slots straight into `IntrospectionData` without re-mapping.
+ */
+interface RouteRow {
+  method: string;
+  path: string;
+  operation?: string;
+  handler?: string;
+  summary?: string;
+}
 declare class ResourceRegistry {
   private _resources;
   private _frozen;
@@ -2493,12 +2775,36 @@ declare class ResourceRegistry {
   has(name: string): boolean;
   /**
    * Get registry statistics
+   *
+   * `totalRoutes` is derived from `enumerateRoutes()` — single source of
+   * truth shared with `getIntrospection()` and consistent with what
+   * OpenAPI / Fastify actually mount. New route sources (e.g. v2.13
+   * aggregations) light up here automatically.
    */
   getStats(): RegistryStats;
   /**
    * Get full introspection data
+   *
+   * Routes come from `enumerateRoutes()` so consumers see the complete
+   * surface — CRUD + custom + actions + aggregations — and match what
+   * `getStats()` counts.
    */
   getIntrospection(): IntrospectionData;
+  /**
+   * Single source of truth for "what routes does this resource expose?".
+   *
+   * Enumerates every wire route the resource will mount on Fastify:
+   *   - default CRUD (respecting `disabledRoutes` + `updateMethod`)
+   *   - host-declared `customRoutes` (alias: `routes`)
+   *   - the unified `POST /:id/action` endpoint when `actions` is set
+   *   - one `GET /:resource/aggregations/:name` per declared aggregation
+   *
+   * Both `getStats()` and `getIntrospection()` consume this list, so a
+   * new route source (e.g. future webhook routes) only has to be added
+   * here — the count and the introspection contract update together.
+   * Mirrors the same set of paths emitted by `docs/openapi.ts`.
+   */
+  enumerateRoutes(r: RegistryEntry): RouteRow[];
   /**
    * Freeze registry (prevent further registrations)
    */
@@ -2870,13 +3176,13 @@ interface RegistryEntry extends ResourceMetadata {
   disableDefaultRoutes?: boolean;
   openApiSchemas?: OpenApiSchemas;
   registeredAt?: string;
-  /** Field-level permissions metadata (for OpenAPI docs) */
+  /** Field-level permissions metadata (for OpenAPI data) */
   fieldPermissions?: Record<string, {
     type: string;
     roles?: readonly string[];
     redactValue?: unknown;
   }>;
-  /** Pipeline step names (for OpenAPI docs) */
+  /** Pipeline step names (for OpenAPI data) */
   pipelineSteps?: Array<{
     type: string;
     name: string;
@@ -2914,6 +3220,34 @@ interface RegistryEntry extends ResourceMetadata {
    * MCP as the fallback in `createActionToolHandler`. Added in 2.8.1.
    */
   actionPermissions?: PermissionCheck;
+  /**
+   * Aggregation route metadata (v2.13). Mirrors the runtime config in
+   * a doc-friendly shape so OpenAPI emission and MCP tool generation
+   * read from one source.
+   *
+   * Each entry corresponds to a `GET /:resource/aggregations/:name`
+   * route. Response shape (rows array of objects keyed by groupBy +
+   * measure aliases) is derived at OpenAPI emission time from
+   * `groupBy` + `measures` + `lookups`.
+   */
+  aggregations?: Array<{
+    readonly name: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly permissions: PermissionCheck;
+    readonly groupBy?: string | readonly string[]; /** Measure aliases keyed to their op-tag (e.g. `'count'`, `'sum:price'`). */
+    readonly measures: Readonly<Record<string, string>>; /** Lookup alias names (`as` or `from`) — used by OpenAPI to know which dotted-path output keys nest. */
+    readonly lookupAliases: readonly string[]; /** Whether the aggregation requires a date range — surfaced in docs. */
+    readonly requireDateRange?: {
+      field: string;
+      maxRangeDays?: number;
+    }; /** Whether the aggregation requires named filters — surfaced in docs. */
+    readonly requireFilters?: readonly string[]; /** MCP tool generation flag — `false` to skip, object for overrides. */
+    readonly mcp?: boolean | {
+      readonly description?: string;
+      readonly annotations?: Record<string, unknown>;
+    };
+  }>;
 }
 interface RegistryStats {
   total?: number;
@@ -2997,4 +3331,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, ArcListResult as $t, RequestIdOptions as A, FieldMetadata as An, Authenticator as At, ResourceDefinition as B, UserOrganization as Bt, RequestContext as C, beforeUpdate as Cn, OperationFilter as Ct, HealthCheck as D, AdapterRepositoryInput as Dn, Transform as Dt, GracefulShutdownOptions as E, AdapterFactory as En, PipelineStep as Et, FastifyWithDecorators as F, asRepositoryLike as Fn, 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, RepositoryLike as Mn, JwtContext as Mt, FastifyRequestExtras as N, SchemaMetadata as Nn, TokenPair as Nt, HealthOptions as O, AdapterSchemaContext as On, AuthHelpers as Ot, FastifyWithAuth as P, ValidationResult$1 as Pn, 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, RelationMetadata as jn, AuthenticatorContext as jt, IntrospectionPluginOptions as k, DataAdapter 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 };
+export { OpenApiSchemas as $, SoftDeleteMixin as $t, RequestIdOptions as A, afterUpdate as An, Guard as At, defineResource as B, Authenticator as Bt, RequestContext as C, HookOperation as Cn, AggregationConfig as Ct, HealthCheck as D, HookSystemOptions as Dn, AggregationMaterializedResult as Dt, GracefulShutdownOptions as E, HookSystem as En, AggregationMaterializedContext as Et, FastifyWithDecorators as F, defineHook as Fn, PipelineContext as Ft, ActionsMap as G, ApiResponse as Gt, ActionDefinition as H, JwtContext as Ht, MiddlewareHandler as I, PipelineStep as It, CrudRouteKey as J, ObjectId as Jt, ArcFieldRule as K, ArcRequest as Kt, RequestWithExtras as L, Transform as Lt, EventsDecorator as M, beforeDelete as Mn, NextFunction as Mt, FastifyRequestExtras as N, beforeUpdate as Nn, OperationFilter as Nt, HealthOptions as O, afterCreate as On, AggregationRateLimit as Ot, FastifyWithAuth as P, createHookSystem as Pn, PipelineConfig as Pt, MiddlewareConfig as Q, SoftDeleteExt as Qt, RegisterOptions as R, AuthHelpers as Rt, QueryParserInterface as S, HookHandler as Sn, AggregationCacheConfig as St, CrudRouterOptions as T, HookRegistration as Tn, AggregationIndexHint as Tt, ActionEntry as U, TokenPair as Ut, ResourceDefinition as V, AuthenticatorContext as Vt, ActionHandlerFn as W, AnyRecord as Wt, EventDefinition as X, UserOrganization as Xt, CrudSchemas as Y, UserLike as Yt, FieldRule$1 as Z, BaseController as Zt, ControllerQueryOptions as _, BodySanitizerConfig as _n, IControllerResponse as _t, InferAdapterDoc as a, BulkMixin as an, ResourceConfig as at, ParsedQuery as b, DefineHookOptions as bn, AggMeasureInput as bt, TypedController as c, QueryResolver as cn, ResourcePermissions as ct, PaginationResult as d, ArcDeleteResult as dn, RouteMethod as dt, TreeExt as en, PresetFunction as et, IntrospectionData as f, ArcGetResult as fn, RouteSchemaOptions as ft, ArcInternalMetadata as g, BodySanitizer as gn, IController as gt, ResourceMetadata as h, ListResult as hn, FastifyHandler as ht, ValidationResult as i, BulkExt as in, ResourceCacheConfig as it, ArcDecorator as j, beforeCreate as jn, Interceptor as jt, IntrospectionPluginOptions as k, afterDelete as kn, AggregationsMap as kt, TypedRepository as l, QueryResolverConfig as ln, RouteDefinition as lt, RegistryStats as m, ArcUpdateResult as mn, ControllerLike as mt, ConfigError as n, SlugExt as nn, PresetResult as nt, InferDocType as o, BaseControllerOptions as on, ResourceHookContext as ot, RegistryEntry as p, ArcListResult as pn, ControllerHandler as pt, CrudController as q, JWTPayload as qt, ValidateOptions as r, SlugMixin as rn, RateLimitConfig as rt, InferResourceDoc as s, BaseCrudController as sn, ResourceHooks as st, RouteHandlerMethod$1 as t, TreeMixin as tn, PresetHook as tt, TypedResourceConfig as u, ArcCreateResult as un, RouteMcpConfig as ut, LookupOption as v, AccessControl as vn, IRequestContext as vt, ServiceContext as w, HookPhase as wn, AggregationDateRangeRequirement as wt, PopulateOption as x, HookContext as xn, AggMeasureShorthand as xt, OwnershipCheck as y, AccessControlConfig as yn, RouteHandler as yt, ResourceRegistry as z, AuthPluginOptions as zt };