@classytic/arc 2.20.0 → 2.22.0

package/dist/{index-_--GyzcO.d.mts → index-DbtgCOCj.d.mts}

@@ -1,14 +1,16 @@
-import { a as QueryCacheConfig } from "./QueryCache-TRfXau3W.mjs";
-import { i as RequestScope } from "./types-LNebCoJx.mjs";
-import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-C7ahdGYf.mjs";
-import { n as DomainEvent } from "./EventTransport-IEn7Tn-Q.mjs";
+import { a as QueryCacheConfig } from "./QueryCache-Z1B38koh.mjs";
+import { i as RequestScope } from "./types-DH0GupI7.mjs";
+import { i as UserBase, t as PermissionCheck } from "./types-Csxga7d3.mjs";
+import "./elevation-C9s5hFP_.mjs";
+import { n as FieldPermissionMap } from "./fields-D3lhgzhD.mjs";
+import { n as EncryptionDirective } from "./types-Cc91nXuA.mjs";
+import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 import { DataAdapter, RepositoryLike } from "@classytic/repo-core/adapter";
 import { AggDateBucket, AggMeasure, AggTopN, QueryOptions, StandardRepo, TenantPurgeStrategy } from "@classytic/repo-core/repository";
 import { LookupSpec } from "@classytic/repo-core/lookup";
 import { FieldRule, SchemaBuilderOptions } from "@classytic/repo-core/schema";
-
 //#region src/core/BodySanitizer.d.ts
 /**
  * Policy for handling fields the caller lacks write permission for.
@@ -1082,7 +1084,8 @@ type ObjectId = string | {
  * The actual user structure is defined by your app's auth system.
  */
 type UserLike = UserBase & {
-  /** User email (optional) */email?: string;
+  /** User email (optional) */
+  email?: string;
 };
 interface UserOrganization {
   userId: string;
@@ -1229,11 +1232,17 @@ interface AuthPluginOptions {
    * utilities are available in the authenticator context.
    */
   jwt?: {
-    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
-    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
-    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
-    refreshExpiresIn?: string; /** Additional `@fastify/jwt` sign options */
-    sign?: Record<string, unknown>; /** Additional `@fastify/jwt` verify options */
+    /** JWT secret (required for JWT features) */
+    secret: string;
+    /** Access token expiry (default: '15m') */
+    expiresIn?: string;
+    /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string;
+    /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string;
+    /** Additional `@fastify/jwt` sign options */
+    sign?: Record<string, unknown>;
+    /** Additional `@fastify/jwt` verify options */
     verify?: Record<string, unknown>;
   };
   /**
@@ -1297,733 +1306,586 @@ interface AuthPluginOptions {
   strictTokenType?: boolean;
 }
 //#endregion
-//#region src/pipeline/types.d.ts
-/**
- * Pipeline context passed to guards, transforms, and interceptors.
- * Extends IRequestContext with pipeline-specific metadata.
- */
-interface PipelineContext extends IRequestContext {
-  /** Resource name being accessed */
-  resource: string;
-  /** CRUD operation being performed */
-  operation: "list" | "get" | "create" | "update" | "delete" | string;
-}
-/**
- * Which operations a pipeline step applies to.
- * If omitted, applies to ALL operations.
- */
-type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
-/**
- * Guard — boolean check that short-circuits on failure.
- * Return true to proceed, throw to deny.
- */
-interface Guard {
-  readonly _type: "guard";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext): boolean | Promise<boolean>;
-}
-/**
- * Transform — modifies request data before the handler.
- * Returns modified context (or mutates in place).
- */
-interface Transform {
-  readonly _type: "transform";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext): PipelineContext | undefined | Promise<PipelineContext | undefined>;
-}
-/**
- * Next function passed to interceptors — calls the handler (or next interceptor).
- */
-type NextFunction = () => Promise<IControllerResponse<unknown>>;
+//#region src/types/handlers.d.ts
 /**
- * Intercept — wraps handler execution (before + after pattern).
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `raw: true`.
  */
-interface Interceptor {
-  readonly _type: "interceptor";
-  readonly name: string;
-  readonly operations?: OperationFilter;
-  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
+interface ServerAccessor {
+  /** Event bus — publish domain events from any handler */
+  events?: {
+    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
+  };
+  /** Audit logger — log custom audit entries */
+  audit?: {
+    create: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+  };
+  /** Logger — structured logging */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+  /** QueryCache — stale-while-revalidate data cache */
+  queryCache?: {
+    get: <T>(key: string) => Promise<{
+      data: T;
+      status: "fresh" | "stale" | "miss";
+    }>;
+    set: <T>(key: string, data: T, config: {
+      staleTime?: number;
+      gcTime?: number;
+      tags?: string[];
+    }) => Promise<void>;
+    getResourceVersion: (resource: string) => Promise<number>;
+    bumpResourceVersion: (resource: string) => Promise<void>;
+  };
 }
-type PipelineStep = Guard | Transform | Interceptor;
-/**
- * Pipeline configuration — can be a flat array or per-operation map.
- */
-type PipelineConfig = PipelineStep[] | {
-  list?: PipelineStep[];
-  get?: PipelineStep[];
-  create?: PipelineStep[];
-  update?: PipelineStep[];
-  delete?: PipelineStep[];
-  [operation: string]: PipelineStep[] | undefined;
-};
-//#endregion
-//#region src/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'`.
+ * Request context passed to controller handlers.
  *
- * Compiles to the canonical `AggMeasure` IR at boot. Hosts who want
- * the full IR can pass an `AggMeasure` object directly.
+ * **Generic parameters** (all default to safe permissive types so existing code keeps working):
+ * - `TBody`     — request body shape (default: `unknown`)
+ * - `TParams`   — route param shape (default: `Record<string, string>`)
+ * - `TQuery`    — query string shape (default: `Record<string, unknown>`)
+ * - `TUser`     — authenticated user shape (default: `UserBase`)
+ * - `TMetadata` — internal metadata shape (default: `Record<string, unknown>`;
+ *   override with `ArcInternalMetadata` or your own augmentation when you
+ *   need typed access to `_scope`, `_policyFilters`, custom hook context, etc.)
  *
- * **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).
+ * @example
+ * ```typescript
+ * // Untyped (default) — req.body is `unknown`, must be narrowed
+ * async create(req: IRequestContext) {
+ *   const data = req.body as Partial<Product>;
+ *   return { success: true, data: await productRepo.create(data) };
+ * }
+ *
+ * // Typed body — req.body is `CreateProductInput`, narrowing not needed
+ * async create(req: IRequestContext<CreateProductInput>) {
+ *   return { success: true, data: await productRepo.create(req.body) };
+ * }
+ *
+ * // Fully typed — body, route params, query, and metadata
+ * async update(
+ *   req: IRequestContext<
+ *     Partial<Product>,
+ *     { id: string },
+ *     { fields?: string },
+ *     ArcInternalMetadata
+ *   >,
+ * ) {
+ *   const fields = req.query.fields?.split(',');
+ *   const orgId = req.metadata?._scope ? getOrgId(req.metadata._scope) : undefined;
+ *   return { success: true, data: await productRepo.update(req.params.id, req.body) };
+ * }
+ * ```
  */
-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`.
+ * First-class projection of `request._scope` for controller handlers.
  *
- * 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.
+ * **v2.10.6:** previously, pulling tenant/user/role info from inside a
+ * controller override meant digging through `req.metadata._scope` and
+ * calling `getOrgId(scope)` / `getUserId(user)` manually. This projection
+ * lifts the two fields most hosts need directly onto `req` so cross-kit
+ * controller code reads:
+ *
+ * ```ts
+ * async create(req: IRequestContext) {
+ *   const flowCtx = { organizationId: req.scope?.organizationId, actorId: req.scope?.userId };
+ * }
+ * ```
+ *
+ * Full scope shape (discriminated union of `member` / `service` / `elevated` / `public`)
+ * still lives on `req.metadata._scope` for code that needs to branch on
+ * `scope.kind` — this projection just surfaces the two keys every
+ * tenant-scoped resource reaches for.
  */
-interface 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;
+interface RequestScopeProjection {
+  /** Tenant the caller is scoped to (org member, service key bound to an org, or elevated admin's target org). */
+  organizationId?: string;
+  /** Caller's user id when authenticated — undefined for public / service-only scopes. */
+  userId?: string;
+  /** Org-level roles (e.g. `['admin', 'warehouse-manager']`) — separate from global `user.roles`. */
+  orgRoles?: string[];
+}
+interface IRequestContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>, TUser extends UserBase = UserBase, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+  /** Route parameters (e.g., { id: '123' }) */
+  params: TParams;
+  /** Query string parameters */
+  query: TQuery;
+  /** Request body */
+  body: TBody;
+  /** Authenticated user or null */
+  user: TUser | null;
+  /** Request headers */
+  headers: Record<string, string | undefined>;
+  /** Organization ID (for multi-tenant apps) */
+  organizationId?: string;
+  /** Team ID (for team-scoped resources) */
+  teamId?: string;
   /**
-   * 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).
+   * First-class tenant/user scope projection — lifted from `metadata._scope`
+   * so controller overrides don't have to dig through Arc internals.
+   * See {@link RequestScopeProjection}. `undefined` for routes that run
+   * without auth / scope resolution.
    */
-  swr?: boolean;
+  scope?: RequestScopeProjection;
   /**
-   * 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).
+   * Organization/auth context from middleware.
+   * Contains orgRoles, orgScope, organizationId, and any custom fields
+   * set by the auth adapter or org-scope plugin.
+   *
+   * @example
+   * ```typescript
+   * async create(req: IRequestContext) {
+   *   const roles = req.context?.orgRoles ?? [];
+   *   if (roles.includes('manager')) { ... }
+   * }
+   * ```
    */
-  tags?: readonly string[];
+  context?: RequestContext;
+  /**
+   * Internal metadata (includes context + Arc internals like `_policyFilters`,
+   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
+   * built-in fields, or supply your own interface to layer custom fields.
+   */
+  metadata?: TMetadata;
+  /**
+   * Fastify server accessor — publish events, log, and audit
+   * from any handler without switching to `raw: true`.
+   *
+   * @example
+   * ```typescript
+   * async reschedule(req: IRequestContext) {
+   *   const result = await repo.reschedule(req.params.id, req.body);
+   *   await req.server?.events?.publish('interview.rescheduled', { data: result });
+   *   return { data: result };
+   * }
+   * ```
+   */
+  server?: ServerAccessor;
 }
 /**
- * Per-aggregation rate limit. Layers on top of any global rate limit
- * via `@fastify/rate-limit` route-level config.
+ * 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 AggregationRateLimit {
-  /** Max requests per window. */
-  max: number;
-  /** Window in milliseconds. */
-  windowMs: number;
+interface IControllerResponse<T = unknown> {
+  /** Response payload — emitted directly to the wire (no envelope wrap). */
+  data: T;
+  /** HTTP status code. Defaults to 200. */
+  status?: number;
+  /** 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>;
 }
 /**
- * Required date-range narrowing. Caller MUST send a bounded range on
- * this field, and the range MUST NOT exceed `maxRangeDays`.
+ * Controller handler — Arc's standard pattern.
  *
- * Prevents "all-time" scans on billion-row collections — the single
- * biggest performance footgun for live aggregation endpoints.
+ * Receives a request context object, returns IControllerResponse.
+ * Use with `raw: false` in routes.
+ *
+ * **Generic parameters:**
+ * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
+ * - `TBody`     — shape of `req.body` (default: `unknown`)
+ * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
+ * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
+ *
+ * Backward-compatible: `ControllerHandler<Product>` still works (only the
+ * response data is typed); add more generics as needed when you want
+ * type-safe access to the request body, params, or query string.
+ *
+ * @example
+ * ```typescript
+ * // Untyped req — body is unknown, must be narrowed
+ * const createProduct: ControllerHandler<Product> = async (req) => {
+ *   const product = await productRepo.create(req.body as Partial<Product>);
+ *   return { data: product, status: 201 };
+ * };
+ *
+ * // Fully typed — body, params, query, and response all inferred
+ * const updateProduct: ControllerHandler<
+ *   Product,
+ *   Partial<Product>,
+ *   { id: string },
+ *   { upsert?: string }
+ * > = async (req) => {
+ *   const upsert = req.query.upsert === "true";
+ *   const product = await productRepo.update(req.params.id, req.body, { upsert });
+ *   return { data: product };
+ * };
+ *
+ * routes: [{
+ *   method: 'POST',
+ *   path: '/products',
+ *   handler: createProduct,
+ *   permissions: requireAuth(),
+ *   raw: false,  // Arc wraps this into Fastify handler
+ * }]
+ * ```
  */
-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;
-}
+type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
 /**
- * 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.
+ * Fastify native handler
  *
- * 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.
+ * Standard Fastify request/reply pattern.
+ * Use with `raw: true` in routes.
+ *
+ * @example
+ * ```typescript
+ * const downloadFile: FastifyHandler = async (request, reply) => {
+ *   const file = await getFile(request.params.id);
+ *   reply.header('Content-Type', file.mimeType);
+ *   return reply.send(file.buffer);
+ * };
+ *
+ * routes: [{
+ *   method: 'GET',
+ *   path: '/files/:id/download',
+ *   handler: downloadFile,
+ *   permissions: requireAuth(),
+ *   raw: true,  // Use as-is, no wrapping
+ * }]
+ * ```
  */
-interface AggregationIndexHint {
-  /** Leading-key columns the host expects the planner to use. */
-  leadingKeys: readonly string[];
+type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
+/**
+ * Union type for route handlers
+ */
+type RouteHandler = ControllerHandler | FastifyHandler;
+/**
+ * Controller interface for CRUD operations (strict).
+ *
+ * `list`'s return type aligns with repo-core's `MinimalRepo.getAll()`
+ * contract — the kit MAY return an offset envelope, a keyset envelope,
+ * or a raw array. Arc's `BaseController` forwards the kit's response
+ * verbatim; consumers narrow on shape
+ * (`Array.isArray(data)` → bare array, presence of `total` → offset,
+ * presence of `nextCursor` → keyset).
+ */
+interface IController<TDoc = unknown> {
+  list(req: IRequestContext): Promise<IControllerResponse<unknown>>;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+  }>>;
 }
 /**
- * Runtime context passed to the `materialized` hook.
+ * Flexible controller interface — accepts controllers with any handler style,
+ * including class instances with extra methods / private fields.
  *
- * 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).
+ * **v2.10.6:** the previous `[key: string]: unknown` index signature made
+ * real class instances fail structural assignment (`new ScrapController()`
+ * needed a `as unknown as ControllerLike` cast, because class instances
+ * don't have an index signature). Dropped — arc only invokes the CRUD
+ * methods at runtime, so the rest of the shape is the caller's concern.
+ *
+ * The five CRUD slots stay optional so partial controllers (e.g. read-only)
+ * assign too. Additional domain methods on the controller are allowed by
+ * construction (they're just not part of this contract).
  */
-interface 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>;
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
 }
-/** Materialized hook return shape — same envelope as `AggResult`. */
-interface AggregationMaterializedResult<TRow = AnyRecord> {
-  rows: readonly TRow[];
+//#endregion
+//#region src/types/resource/rate-limit.d.ts
+/**
+ * Resource-level rate-limit shape — shared by `ResourceConfig.rateLimit`
+ * and per-route `RouteDefinition.rateLimit` overrides.
+ */
+interface RateLimitConfig {
+  /** Maximum number of requests allowed within the time window */
+  max: number;
+  /** Time window for rate limiting (e.g., '1 minute', '15 seconds') */
+  timeWindow: string;
+}
+//#endregion
+//#region src/types/resource/routes.d.ts
+/** HTTP methods for custom routes. */
+type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** MCP tool configuration for a route or action. */
+interface RouteMcpConfig {
+  /** Override auto-generated tool description */
+  readonly description?: string;
+  /** MCP tool annotations */
+  readonly annotations?: {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+  };
 }
 /**
- * Single named aggregation declaration. Composes into `AggRequest` at
- * request time, with safety knobs layered on at the arc-handler level.
+ * Route definition — single custom-route shape (user-facing + internal).
+ *
+ * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
+ * - `handler: function` → inline handler → full Arc pipeline + MCP tool
+ * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
  */
-interface 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;
+interface RouteDefinition {
+  readonly method: RouteMethod;
+  /** Path relative to resource prefix */
+  readonly path: string;
   /**
-   * Cross-table joins. Each `LookupSpec` reuses the IR
-   * `@classytic/repo-core/lookup` defines for `lookupPopulate()`.
-   * Same compile path the kit already ships.
+   * Route handler.
+   * - String: controller method name (Arc pipeline) — runtime lookup, no TS coverage on typos.
+   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
+   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
    *
-   * **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.
+   * Prefer `controllerMethod` (2.16) over the string form when you want the
+   * compiler to catch typos. `handler` stays optional when `controllerMethod`
+   * is set — exactly one of the two must be declared.
    */
-  groupBy?: string | readonly string[];
+  readonly handler?: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
   /**
-   * 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.).
+   * Typed function-reference handler (2.16). Receives the live controller
+   * instance and returns the method to invoke — TypeScript catches typos
+   * and surfaces autocomplete on the controller's method names. Prefer
+   * this over the string `handler` form for any host that uses a typed
+   * controller subclass.
    *
-   * 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.
+   * Resolved ONCE at route-registration time (the same path string
+   * handlers go through), so there's no per-request lookup overhead.
+   * The returned method is bound to the controller before dispatch.
    *
-   * Aliases must NOT collide with a `groupBy` field name or measure
-   * alias — boot validation throws on collision.
+   * Mutually exclusive with `handler` — passing both throws at boot
+   * with a clear "pick one" message. The runtime contract on what the
+   * returned function accepts mirrors the `handler` rules: a plain
+   * `ControllerHandler` for pipeline routes, a raw Fastify handler when
+   * the route is `raw: true`.
    *
-   * @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']),
-   * }),
-   * ```
+   * Typed loosely (`(controller: unknown) => …`) at the type-system
+   * boundary because `RouteDefinition` is not generic over the
+   * controller shape — host code annotates the parameter to opt in:
    *
-   * @example "15-minute traffic buckets (custom-bin form)"
+   * @example
    * ```ts
-   * traffic: defineAggregation({
-   *   dateBuckets: {
-   *     slot: { field: 'ts', interval: { every: 15, unit: 'minute' } },
-   *   },
-   *   measures: { hits: 'count' },
-   *   permissions: allowPublic(),
-   * }),
+   * class PostController extends BaseController<Post> {
+   *   async getStats(ctx: IRequestContext) { … }
+   * }
+   *
+   * defineResource({
+   *   controller: new PostController(repo),
+   *   routes: [{
+   *     method: 'GET',
+   *     path: '/stats',
+   *     controllerMethod: (c: PostController) => c.getStats,
+   *     //                       ^^^^^^^^^^^^^^ TS catches typos here
+   *     permissions: requireAuth(),
+   *   }],
+   * });
    * ```
    */
-  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>;
+  readonly controllerMethod?: (controller: unknown) => ControllerHandler | RouteHandlerMethod;
+  /** Permission check — REQUIRED */
+  readonly permissions: PermissionCheck;
   /**
-   * Static hard cap on result rows. Always applied at the IR level
-   * (LIMIT / `$limit`), regardless of URL params. Use when the
-   * aggregation has a fixed-size shape ("top 10 categories"). Mutually
-   * exclusive with `defaultLimit` / `maxLimit` — pick the static form
-   * OR the URL-driven form, not both.
+   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
+   * request/reply. Default: false.
    */
-  limit?: number;
+  readonly raw?: boolean;
+  /** Logical operation name (pipeline keys, MCP tool naming). */
+  readonly operation?: string;
+  /** OpenAPI summary */
+  readonly summary?: string;
+  /** OpenAPI description */
+  readonly description?: string;
+  /** OpenAPI tags */
+  readonly tags?: string[];
+  /** Route-level middleware */
+  readonly preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
+  /** Pre-auth handlers (run before authentication) */
+  readonly preAuth?: RouteHandlerMethod[];
   /**
-   * URL-driven row limit — applied when the caller passes `?limit=N`.
-   * When set, the auto-route reads `query.limit`, parses it as a
-   * positive integer, caps it at `maxLimit` (or the framework default
-   * if `maxLimit` is unset), and writes the result into `AggRequest.limit`.
-   * When the caller omits `?limit`, this default applies.
+   * Opt this custom route into the multiTenant preset's tenant scoping.
    *
-   * **DoS defense.** Auto-generated `/aggregations/:name` routes today
-   * have no upper bound on response size. A `groupBy: 'userId'` on a
-   * 10M-user table without `defaultLimit` returns a 10M-row JSON. Setting
-   * `defaultLimit: 100, maxLimit: 1000` bounds the response shape while
-   * letting power users request up to 1000 rows when they need them.
+   * When `true` AND the resource declares `multiTenantPreset` (or
+   * `flexibleMultiTenantPreset`), arc prepends the preset's tenant
+   * filter + injection middleware to this route's chain — the same
+   * pair `update` gets. The handler can then read the resolved tenant
+   * via `getOrgId(req.scope)` / `req._tenantFields` (or, for write
+   * routes, off `req.body` after injection) without re-implementing
+   * the scope read + header fallback + 400 boilerplate.
    *
-   * Mutually exclusive with the static `limit` — boot error if both set.
-   * Setting `defaultLimit` without `maxLimit` uses the framework
-   * default cap (`AGG_FRAMEWORK_MAX_LIMIT = 1000`) — explicit is better.
+   * Throws at boot if set when no multiTenant preset is wired — the
+   * misconfiguration would otherwise be silently insecure (read routes
+   * returning every tenant's rows).
+   *
+   * @default false
    */
-  defaultLimit?: number;
+  readonly tenantScope?: boolean;
   /**
-   * Hard ceiling for URL-driven `?limit=N`. Only meaningful when
-   * `defaultLimit` is set; ignored otherwise. Defaults to
-   * `AGG_FRAMEWORK_MAX_LIMIT` (1000) when omitted but `defaultLimit` is
-   * present. Boot validation: must be ≥ `defaultLimit`.
+   * SSE streaming mode. Two handler shapes work:
+   *
+   * - Write to `reply.raw` directly (NDJSON, custom SSE — historical contract).
+   * - Return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`,
+   *   `fetch().body`, etc.). 2.17.1+ auto-pipes these through
+   *   `pipeUIMessageStreamToReply()` so each chunk is JSON-encoded into
+   *   an SSE `data:` frame and client-disconnect cancels the source.
+   *   Pre-2.17.1 this crashed with `chunk must be a string or Buffer`.
    */
-  maxLimit?: number;
+  readonly streamResponse?: boolean;
   /**
-   * 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.
+   * INTERNAL — marker stamped by built-in presets (softDelete, tree, …)
+   * onto routes they emit. Read by the MCP collision detector
+   * (`createMcpServer.resolveToolCollisions`) to attribute the route
+   * source ("preset:softDelete vs user `actions.restore`") and to
+   * auto-namespace the preset side when a user-authored tool legitimately
+   * shadows it. Not part of the public surface — hosts must not set this.
    *
-   * **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.
+   * @internal
    */
-  topN?: AggTopN;
+  readonly _presetSource?: string;
   /**
-   * 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.
+   * Apply the resource's `fields` (field-level write permissions) to this
+   * custom route's request body.
+   *
+   * Default: `true` for body-bearing methods (POST/PUT/PATCH), `false`
+   * otherwise. Set to `false` to opt out — handler accepts the body as
+   * supplied with no field-write filtering. The resource-level
+   * `onFieldWriteDenied: 'reject' | 'strip'` setting governs how denials
+   * are surfaced.
+   *
+   * `raw: true` routes ALWAYS bypass this — they've opted out of the
+   * pipeline entirely.
    */
-  permissions: PermissionCheck;
+  readonly fieldWrite?: boolean;
   /**
-   * DB-level execution cap (ms). Mongokit threads to `maxTimeMS`;
-   * sqlitekit threads to per-statement timeout where supported.
-   * Default: kit's default (typically none).
+   * Per-route rate limit. A custom route is its own Fastify route, so this
+   * overrides the resource-level `rateLimit` for THIS endpoint only:
+   *
+   *   - omitted                → inherit the resource-level limit (or app default)
+   *   - `false`                → disable rate limiting on this route
+   *   - `{ max, timeWindow }`  → apply this specific limit
+   *
+   * Requires `@fastify/rate-limit` registered (arc's factory wires it by
+   * default). Use for an expensive `/export` or an auth-sensitive `/reset`
+   * that needs a tighter cap than the resource's read-heavy CRUD, or `false`
+   * on an internal health/webhook route that must not be throttled.
+   *
+   * Note: this is per-route because each custom route is a distinct endpoint.
+   * `actions` share ONE `POST /:id/action` mount by design, so a per-ACTION
+   * limit can't be expressed here — throttle a specific action by promoting
+   * it to a dedicated `routes:` entry, or rely on the resource-level limit.
    */
-  timeout?: number;
+  readonly rateLimit?: RateLimitConfig | false;
   /**
-   * 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).
+   * Fastify route schema. Each slot (`body`, `querystring`, `params`,
+   * `headers`, `response[status]`) accepts a plain JSON Schema object
+   * **or** a Zod v4 schema — Arc auto-converts via `convertRouteSchema`.
    */
-  maxGroups?: number;
+  readonly schema?: {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<number | string, unknown>;
+    [key: string]: unknown;
+  };
   /**
-   * 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.).
+   * MCP tool generation:
+   * - omitted/true: auto-generate (non-raw routes only)
+   * - false: skip MCP
+   * - object: explicit config
    */
-  requireFilters?: readonly string[];
+  readonly mcp?: boolean | RouteMcpConfig;
   /**
-   * Caller MUST send a bounded date range on this field. Prevents
-   * all-time scans on billion-row collections.
+   * MCP handler for raw routes — parallel entry point for MCP without
+   * changing the HTTP handler.
    */
-  requireDateRange?: AggregationDateRangeRequirement;
+  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }>;
+}
+//#endregion
+//#region src/types/resource/actions.d.ts
+/**
+ * Action handler function for state transitions. Receives the resource
+ * ID, action-specific data, and the request.
+ */
+type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
+/**
+ * Full action configuration with handler, permissions, and schema.
+ *
+ * Rate limiting is intentionally NOT per-action: every action shares one
+ * `POST /:id/action` (or `POST /action`) mount, so Fastify's per-route limit
+ * can't distinguish them. Actions inherit the resource-level `rateLimit`; to
+ * throttle a specific operation, promote it to a `routes:` entry (which
+ * supports `RouteDefinition.rateLimit`).
+ */
+interface ActionDefinition {
+  readonly handler: ActionHandlerFn;
+  /** Per-action permission (overrides resource-level `actionPermissions`) */
+  readonly permissions?: PermissionCheck;
   /**
-   * 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.
+   * JSON Schema or Zod v4 schema for action-specific body fields.
+   *
+   * Typed `unknown` (not `Record<string, unknown>`) so Zod class instances
+   * — `ZodObject<...>` carries no string index signature — assign without
+   * a cast. Same convention as `RouteDefinition.schema.body` / `customSchemas`.
+   * Runtime feature-detects via `convertRouteSchema` / `toJsonSchema`.
    */
-  indexHint?: AggregationIndexHint;
+  readonly schema?: unknown;
+  /** Description for OpenAPI docs and MCP tool */
+  readonly description?: string;
   /**
-   * Per-aggregation cache. Tenant-scoped keys; invalidates with the
-   * resource's cache namespace + any explicit `tags`.
+   * Whether this action needs an entity id from the URL.
+   *
+   * - `true` (default) — mounts under `POST /<prefix>/:id/action`. The `id`
+   *   path param is required; handler receives it as the first argument.
+   *   Use for actions that operate on an existing entity: `approve`,
+   *   `dispatch`, `cancel`, `archive`.
+   * - `false` — mounts under `POST /<prefix>/action` (no `:id` segment).
+   *   Handler receives an empty-string first argument. Use for
+   *   collection-level actions that create / search / bulk-mutate:
+   *   `propose` (creates a new entity), `search` (returns rows), `bulk`.
+   *
+   * 2.15.5: previously every action had to live under `:id/action`, forcing
+   * `propose`-style actions to swallow a meaningless URL parameter and
+   * making the auto-generated MCP tool advertise an `id` field agents
+   * had no value for. Setting `id: false` mounts the action at the
+   * resource root and drops `id` from the MCP tool's input shape.
    */
-  cache?: AggregationCacheConfig;
+  readonly id?: boolean;
   /**
-   * Per-route rate limit. Wired to `@fastify/rate-limit` when the
-   * plugin is registered.
+   * MCP tool generation:
+   * - omitted/true: auto-generate
+   * - false: skip
+   * - object: explicit config
    */
-  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.
- * Allows controller handlers to publish events, log, and audit
- * without switching to `raw: true`.
- */
-interface ServerAccessor {
-  /** Event bus — publish domain events from any handler */
-  events?: {
-    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
-  };
-  /** Audit logger — log custom audit entries */
-  audit?: {
-    create: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
-    update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
-    delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
-    custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
-  };
-  /** Logger — structured logging */
-  log?: {
-    info: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-    debug: (...args: unknown[]) => void;
-  };
-  /** QueryCache — stale-while-revalidate data cache */
-  queryCache?: {
-    get: <T>(key: string) => Promise<{
-      data: T;
-      status: "fresh" | "stale" | "miss";
-    }>;
-    set: <T>(key: string, data: T, config: {
-      staleTime?: number;
-      gcTime?: number;
-      tags?: string[];
-    }) => Promise<void>;
-    getResourceVersion: (resource: string) => Promise<number>;
-    bumpResourceVersion: (resource: string) => Promise<void>;
-  };
-}
-/**
- * Request context passed to controller handlers.
- *
- * **Generic parameters** (all default to safe permissive types so existing code keeps working):
- * - `TBody`     — request body shape (default: `unknown`)
- * - `TParams`   — route param shape (default: `Record<string, string>`)
- * - `TQuery`    — query string shape (default: `Record<string, unknown>`)
- * - `TUser`     — authenticated user shape (default: `UserBase`)
- * - `TMetadata` — internal metadata shape (default: `Record<string, unknown>`;
- *   override with `ArcInternalMetadata` or your own augmentation when you
- *   need typed access to `_scope`, `_policyFilters`, custom hook context, etc.)
- *
- * @example
- * ```typescript
- * // Untyped (default) — req.body is `unknown`, must be narrowed
- * async create(req: IRequestContext) {
- *   const data = req.body as Partial<Product>;
- *   return { success: true, data: await productRepo.create(data) };
- * }
- *
- * // Typed body — req.body is `CreateProductInput`, narrowing not needed
- * async create(req: IRequestContext<CreateProductInput>) {
- *   return { success: true, data: await productRepo.create(req.body) };
- * }
- *
- * // Fully typed — body, route params, query, and metadata
- * async update(
- *   req: IRequestContext<
- *     Partial<Product>,
- *     { id: string },
- *     { fields?: string },
- *     ArcInternalMetadata
- *   >,
- * ) {
- *   const fields = req.query.fields?.split(',');
- *   const orgId = req.metadata?._scope ? getOrgId(req.metadata._scope) : undefined;
- *   return { success: true, data: await productRepo.update(req.params.id, req.body) };
- * }
- * ```
- */
-/**
- * First-class projection of `request._scope` for controller handlers.
- *
- * **v2.10.6:** previously, pulling tenant/user/role info from inside a
- * controller override meant digging through `req.metadata._scope` and
- * calling `getOrgId(scope)` / `getUserId(user)` manually. This projection
- * lifts the two fields most hosts need directly onto `req` so cross-kit
- * controller code reads:
- *
- * ```ts
- * async create(req: IRequestContext) {
- *   const flowCtx = { organizationId: req.scope?.organizationId, actorId: req.scope?.userId };
- * }
- * ```
- *
- * Full scope shape (discriminated union of `member` / `service` / `elevated` / `public`)
- * still lives on `req.metadata._scope` for code that needs to branch on
- * `scope.kind` — this projection just surfaces the two keys every
- * tenant-scoped resource reaches for.
- */
-interface RequestScopeProjection {
-  /** Tenant the caller is scoped to (org member, service key bound to an org, or elevated admin's target org). */
-  organizationId?: string;
-  /** Caller's user id when authenticated — undefined for public / service-only scopes. */
-  userId?: string;
-  /** Org-level roles (e.g. `['admin', 'warehouse-manager']`) — separate from global `user.roles`. */
-  orgRoles?: string[];
-}
-interface IRequestContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>, TUser extends UserBase = UserBase, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
-  /** Route parameters (e.g., { id: '123' }) */
-  params: TParams;
-  /** Query string parameters */
-  query: TQuery;
-  /** Request body */
-  body: TBody;
-  /** Authenticated user or null */
-  user: TUser | null;
-  /** Request headers */
-  headers: Record<string, string | undefined>;
-  /** Organization ID (for multi-tenant apps) */
-  organizationId?: string;
-  /** Team ID (for team-scoped resources) */
-  teamId?: string;
-  /**
-   * First-class tenant/user scope projection — lifted from `metadata._scope`
-   * so controller overrides don't have to dig through Arc internals.
-   * See {@link RequestScopeProjection}. `undefined` for routes that run
-   * without auth / scope resolution.
-   */
-  scope?: RequestScopeProjection;
-  /**
-   * Organization/auth context from middleware.
-   * Contains orgRoles, orgScope, organizationId, and any custom fields
-   * set by the auth adapter or org-scope plugin.
-   *
-   * @example
-   * ```typescript
-   * async create(req: IRequestContext) {
-   *   const roles = req.context?.orgRoles ?? [];
-   *   if (roles.includes('manager')) { ... }
-   * }
-   * ```
-   */
-  context?: RequestContext;
-  /**
-   * Internal metadata (includes context + Arc internals like `_policyFilters`,
-   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
-   * built-in fields, or supply your own interface to layer custom fields.
-   */
-  metadata?: TMetadata;
-  /**
-   * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `raw: true`.
-   *
-   * @example
-   * ```typescript
-   * async reschedule(req: IRequestContext) {
-   *   const result = await repo.reschedule(req.params.id, req.body);
-   *   await req.server?.events?.publish('interview.rescheduled', { data: result });
-   *   return { data: result };
-   * }
-   * ```
-   */
-  server?: ServerAccessor;
-}
-/**
- * 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> {
-  /** Response payload — emitted directly to the wire (no envelope wrap). */
-  data: T;
-  /** HTTP status code. Defaults to 200. */
-  status?: number;
-  /** 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.
- *
- * Receives a request context object, returns IControllerResponse.
- * Use with `raw: false` in routes.
- *
- * **Generic parameters:**
- * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
- * - `TBody`     — shape of `req.body` (default: `unknown`)
- * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
- * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
- *
- * Backward-compatible: `ControllerHandler<Product>` still works (only the
- * response data is typed); add more generics as needed when you want
- * type-safe access to the request body, params, or query string.
- *
- * @example
- * ```typescript
- * // Untyped req — body is unknown, must be narrowed
- * const createProduct: ControllerHandler<Product> = async (req) => {
- *   const product = await productRepo.create(req.body as Partial<Product>);
- *   return { data: product, status: 201 };
- * };
- *
- * // Fully typed — body, params, query, and response all inferred
- * const updateProduct: ControllerHandler<
- *   Product,
- *   Partial<Product>,
- *   { id: string },
- *   { upsert?: string }
- * > = async (req) => {
- *   const upsert = req.query.upsert === "true";
- *   const product = await productRepo.update(req.params.id, req.body, { upsert });
- *   return { data: product };
- * };
- *
- * routes: [{
- *   method: 'POST',
- *   path: '/products',
- *   handler: createProduct,
- *   permissions: requireAuth(),
- *   raw: false,  // Arc wraps this into Fastify handler
- * }]
- * ```
- */
-type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
-/**
- * Fastify native handler
- *
- * Standard Fastify request/reply pattern.
- * Use with `raw: true` in routes.
- *
- * @example
- * ```typescript
- * const downloadFile: FastifyHandler = async (request, reply) => {
- *   const file = await getFile(request.params.id);
- *   reply.header('Content-Type', file.mimeType);
- *   return reply.send(file.buffer);
- * };
- *
- * routes: [{
- *   method: 'GET',
- *   path: '/files/:id/download',
- *   handler: downloadFile,
- *   permissions: requireAuth(),
- *   raw: true,  // Use as-is, no wrapping
- * }]
- * ```
- */
-type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
-/**
- * Union type for route handlers
- */
-type RouteHandler = ControllerHandler | FastifyHandler;
-/**
- * Controller interface for CRUD operations (strict).
- *
- * `list`'s return type aligns with repo-core's `MinimalRepo.getAll()`
- * contract — the kit MAY return an offset envelope, a keyset envelope,
- * or a raw array. Arc's `BaseController` forwards the kit's response
- * verbatim; consumers narrow on shape
- * (`Array.isArray(data)` → bare array, presence of `total` → offset,
- * presence of `nextCursor` → keyset).
- */
-interface IController<TDoc = unknown> {
-  list(req: IRequestContext): Promise<IControllerResponse<unknown>>;
-  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  delete(req: IRequestContext): Promise<IControllerResponse<{
-    message: string;
-  }>>;
-}
-/**
- * Flexible controller interface — accepts controllers with any handler style,
- * including class instances with extra methods / private fields.
- *
- * **v2.10.6:** the previous `[key: string]: unknown` index signature made
- * real class instances fail structural assignment (`new ScrapController()`
- * needed a `as unknown as ControllerLike` cast, because class instances
- * don't have an index signature). Dropped — arc only invokes the CRUD
- * methods at runtime, so the rest of the shape is the caller's concern.
- *
- * The five CRUD slots stay optional so partial controllers (e.g. read-only)
- * assign too. Additional domain methods on the controller are allowed by
- * construction (they're just not part of this contract).
- */
-interface ControllerLike {
-  list?: unknown;
-  get?: unknown;
-  create?: unknown;
-  update?: unknown;
-  delete?: unknown;
+  readonly mcp?: boolean | RouteMcpConfig;
 }
+/** Action config: bare handler function OR full ActionDefinition. */
+type ActionEntry = ActionHandlerFn | ActionDefinition;
+/** Actions configuration map. */
+type ActionsMap = Record<string, ActionEntry>;
 //#endregion
-//#region src/types/resource.d.ts
-/** Standard controller type alias for CRUD operations. */
-type CrudController<TDoc> = IController<TDoc>;
-/**
- * Tenant-cleanup declaration on a resource — compliance-grade strategy
- * for what happens to this resource's rows when the owning organization
- * is deleted. Surfaces in arc's org-delete cascade runner and in
- * registry introspection (audit scripts ask "what happens to this
- * resource on org delete?").
- *
- * Strategy variants:
- *   - `hard` — permanent removal (GDPR right-to-be-forgotten).
- *   - `soft` — recoverable; pair with TTL for eventual hard-purge.
- *   - `anonymize` — keep the row (legal retention) but clear PII
- *     (HIPAA / PCI / SOX-compatible).
- *   - `skip` — explicit opt-out with mandatory `reason`.
- *
- * See {@link ResourceConfig.onTenantDelete} for the full decision tree.
- */
-interface OnTenantDeleteConfig {
-  /**
-   * What to do with rows whose `tenantField` matches the deleted org.
-   * Discriminated union from `@classytic/repo-core/repository` — every
-   * kit's `purgeByField` consumes the same shape.
-   */
-  strategy: TenantPurgeStrategy;
-  /**
-   * Resources are processed in ascending `priority` order. Use to land
-   * leaf data (logs, events) before aggregate references. Default `100`.
-   */
-  priority?: number;
-  /**
-   * Rows per chunk for the underlying `purgeByField` call — bounds
-   * lock contention + replication-log pressure on very large tenants.
-   * Default kit-specific (~1000).
-   */
-  batchSize?: number;
-}
+//#region src/types/resource/cache.d.ts
 /**
- * Resolved tenant-purge declaration — what arc actually runs when
- * `cascadeDeleteForOrganization` fires. Computed once at boot from the
- * resource's `onTenantDelete` declaration.
- *
- * Exposed via `ResourceDefinition.resolvedTenantPurge` and
- * `getCascadingResourcesWithMetadata(registry)` so audit tooling can
- * answer "is this resource really going to hard-delete?" without
- * reading the source.
- */
-interface ResolvedTenantPurge {
-  readonly strategy: TenantPurgeStrategy;
-  readonly priority: number;
-  readonly batchSize?: number;
-  /**
-   * Where the strategy came from — `'declared'` (host wrote
-   * `onTenantDelete` explicitly) or `'disabled'` (no declaration —
-   * runner skips this resource).
-   */
-  readonly source: "declared" | "disabled";
-}
+ * Per-resource QueryCache configuration — stale-while-revalidate
+ * windows, per-operation overrides, and tag-based cross-resource
+ * invalidation.
+ */
 /**
  * Per-resource cache configuration for QueryCache. Enables
  * stale-while-revalidate, auto-invalidation on mutations, and
@@ -2053,531 +1915,461 @@ interface ResourceCacheConfig {
   /** Disable caching for this resource */
   disabled?: boolean;
 }
-interface RateLimitConfig {
-  /** Maximum number of requests allowed within the time window */
-  max: number;
-  /** Time window for rate limiting (e.g., '1 minute', '15 seconds') */
-  timeWindow: string;
+//#endregion
+//#region src/pipeline/types.d.ts
+/**
+ * Pipeline context passed to guards, transforms, and interceptors.
+ * Extends IRequestContext with pipeline-specific metadata.
+ */
+interface PipelineContext extends IRequestContext {
+  /** Resource name being accessed */
+  resource: string;
+  /** CRUD operation being performed */
+  operation: "list" | "get" | "create" | "update" | "delete" | string;
 }
 /**
- * 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.
+ * Which operations a pipeline step applies to.
+ * If omitted, applies to ALL operations.
  */
-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;
-  /**
-   * Aggregation visibility override. By default, only `hidden: true`
-   * blocks a field from `groupBy` / `measures.field` / `sort` / `dateBuckets`
-   * — that's the genuine cardinality-leak guard (the value is omitted from
-   * list/get responses, so exposing it via aggregation would reveal data
-   * the client can't otherwise see).
-   *
-   * `systemManaged: true` does **not** block aggregation — it's a write
-   * rule, not a visibility rule. Server-stamped fields like `createdAt`,
-   * `status`, or plugin-generated handles are visible in every list
-   * response and should aggregate freely.
-   *
-   * Use this flag to override the default:
-   *
-   * - `aggregable: false` — explicit deny, even on visible fields. Useful
-   *   when a value is exposed per-row but the cardinality across rows is
-   *   itself sensitive (e.g. `email` is visible in `get/:id` to admins
-   *   but you don't want a public-readable agg of email distributions).
-   * - `aggregable: true` — escape hatch on `hidden` fields. Lets you
-   *   aggregate a hidden column when you're sure cardinality leakage
-   *   isn't a concern (e.g. `internalScore` hidden from list, but a
-   *   committee-only `byScore` agg is fine).
-   *
-   * Defaults to `undefined` (use the `hidden`-only rule).
-   */
-  aggregable?: 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;
+type OperationFilter = Array<"list" | "get" | "create" | "update" | "delete" | string>;
+/**
+ * Guard — boolean check that short-circuits on failure.
+ * Return true to proceed, throw to deny.
+ */
+interface Guard {
+  readonly _type: "guard";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): boolean | Promise<boolean>;
 }
 /**
- * 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.
+ * Transform — modifies request data before the handler.
+ * Returns modified context (or mutates in place).
+ */
+interface Transform {
+  readonly _type: "transform";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): PipelineContext | undefined | Promise<PipelineContext | undefined>;
+}
+/**
+ * Next function passed to interceptors — calls the handler (or next interceptor).
+ */
+type NextFunction = () => Promise<IControllerResponse<unknown>>;
+/**
+ * Intercept — wraps handler execution (before + after pattern).
+ */
+interface Interceptor {
+  readonly _type: "interceptor";
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
+}
+type PipelineStep = Guard | Transform | Interceptor;
+/**
+ * Pipeline configuration — can be a flat array or per-operation map.
+ */
+type PipelineConfig = PipelineStep[] | {
+  list?: PipelineStep[];
+  get?: PipelineStep[];
+  create?: PipelineStep[];
+  update?: PipelineStep[];
+  delete?: PipelineStep[];
+  [operation: string]: PipelineStep[] | undefined;
+};
+//#endregion
+//#region src/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'`.
  *
- * 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
+ * Compiles to the canonical `AggMeasure` IR at boot. Hosts who want
+ * the full IR can pass an `AggMeasure` object directly.
  *
- * 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.
+ * **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`.
  *
- * **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.
+ * 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 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.
-   *
-   * 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[];
-  /**
-   * 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`.
-   */
-  fieldRules?: Record<string, ArcFieldRule>;
-  /**
-   * Query-time security whitelists + the kit's `filterableFields`.
-   *
-   * Extends repo-core's `SchemaBuilderOptions['query']` with arc-specific
-   * runtime features that `QueryResolver` reads at request time:
-   *
-   * - **`allowedPopulate`** — populate-path whitelist consumed by
-   *   `QueryResolver.sanitizePopulate` / `sanitizeAdvancedPopulate`.
-   *   When set, only paths in the list pass through; everything else is
-   *   stripped silently. Shrinks the auto-wired `?populate=` attack surface.
-   *
-   * - **`allowedLookups`** — lookup-collection whitelist consumed by
-   *   `QueryResolver.sanitizeLookups`. When set, only the listed
-   *   collections may be `$lookup`'d into the pipeline.
-   *
-   * Both are pre-2.11.2 runtime features — the type was missing them, so
-   * hosts wrote `as Record<string, unknown>` at every call site. Arc's own
-   * `QueryResolver` had to cast its own input via `as AnyRecord` for the
-   * same reason. Adding the type dropped both casts.
+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).
    */
-  query?: SchemaBuilderOptions["query"] & {
-    /**
-     * Populate-path whitelist. When set, `QueryResolver.sanitizePopulate`
-     * strips any `?populate=<path>` not in this list. Omit to allow all
-     * paths the kit recognizes.
-     */
-    allowedPopulate?: string[];
-    /**
-     * Lookup-collection whitelist for `QueryResolver.sanitizeLookups`.
-     * When set, only the listed collections may be `$lookup`'d. Omit to
-     * disable the whitelist (kit-level rules still apply).
-     */
-    allowedLookups?: string[];
-  };
-}
-interface FieldRule$1 {
-  field: string;
-  required?: boolean;
-  readonly?: boolean;
-  hidden?: boolean;
+  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[];
 }
 /**
- * CRUD route schemas (Fastify native format). Each slot accepts a plain
- * JSON Schema object **or** a Zod v4 schema — Arc's `convertRouteSchema`
- * feature-detects at runtime. Slot values are typed `unknown` so
- * class-based Zod schemas assign without casts.
+ * Per-aggregation rate limit. Layers on top of any global rate limit
+ * via `@fastify/rate-limit` route-level config.
  */
-interface CrudSchemas {
-  /** GET / — list */
-  list?: {
-    querystring?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** GET /:id — get one */
-  get?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** POST / — create */
-  create?: {
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** PATCH /:id — update */
-  update?: {
-    params?: unknown;
-    body?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  /** DELETE /:id — delete */
-  delete?: {
-    params?: unknown;
-    response?: Record<number, unknown>;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
+interface AggregationRateLimit {
+  /** Max requests per window. */
+  max: number;
+  /** Window in milliseconds. */
+  windowMs: number;
 }
-interface OpenApiSchemas {
-  entity?: unknown;
-  createBody?: unknown;
-  updateBody?: unknown;
-  params?: unknown;
-  listQuery?: unknown;
+/**
+ * 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;
   /**
-   * Explicit response schema for OpenAPI documentation. Auto-generated
-   * from `createBody` if omitted. Does NOT affect Fastify serialization.
+   * 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).
    */
-  response?: unknown;
-  [key: string]: unknown;
-}
-type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
-interface MiddlewareConfig {
-  list?: MiddlewareHandler[];
-  get?: MiddlewareHandler[];
-  create?: MiddlewareHandler[];
-  update?: MiddlewareHandler[];
-  delete?: MiddlewareHandler[];
-  [key: string]: MiddlewareHandler[] | undefined;
+  maxRangeDays?: number;
 }
-/** HTTP methods for custom routes. */
-type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-/** MCP tool configuration for a route or action. */
-interface RouteMcpConfig {
-  /** Override auto-generated tool description */
-  readonly description?: string;
-  /** MCP tool annotations */
-  readonly annotations?: {
-    readonly readOnlyHint?: boolean;
-    readonly destructiveHint?: boolean;
-    readonly idempotentHint?: boolean;
-    readonly openWorldHint?: boolean;
-  };
+/**
+ * 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[];
 }
 /**
- * Route definition — single custom-route shape (user-facing + internal).
+ * Runtime context passed to the `materialized` hook.
  *
- * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
- * - `handler: function` → inline handler → full Arc pipeline + MCP tool
- * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
+ * 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 RouteDefinition {
-  readonly method: RouteMethod;
-  /** Path relative to resource prefix */
-  readonly path: string;
+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 {
   /**
-   * Route handler.
-   * - String: controller method name (Arc pipeline) — runtime lookup, no TS coverage on typos.
-   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
-   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
-   *
-   * Prefer `controllerMethod` (2.16) over the string form when you want the
-   * compiler to catch typos. `handler` stays optional when `controllerMethod`
-   * is set — exactly one of the two must be declared.
+   * 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`).
    */
-  readonly handler?: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<Record<string, unknown>>, reply: FastifyReply) => unknown);
+  filter?: AnyRecord;
   /**
-   * Typed function-reference handler (2.16). Receives the live controller
-   * instance and returns the method to invoke — TypeScript catches typos
-   * and surfaces autocomplete on the controller's method names. Prefer
-   * this over the string `handler` form for any host that uses a typed
-   * controller subclass.
+   * Cross-table joins. Each `LookupSpec` reuses the IR
+   * `@classytic/repo-core/lookup` defines for `lookupPopulate()`.
+   * Same compile path the kit already ships.
    *
-   * Resolved ONCE at route-registration time (the same path string
-   * handlers go through), so there's no per-request lookup overhead.
-   * The returned method is bound to the controller before dispatch.
+   * **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.).
    *
-   * Mutually exclusive with `handler` — passing both throws at boot
-   * with a clear "pick one" message. The runtime contract on what the
-   * returned function accepts mirrors the `handler` rules: a plain
-   * `ControllerHandler` for pipeline routes, a raw Fastify handler when
-   * the route is `raw: true`.
+   * 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.
    *
-   * Typed loosely (`(controller: unknown) => …`) at the type-system
-   * boundary because `RouteDefinition` is not generic over the
-   * controller shape — host code annotates the parameter to opt in:
+   * Aliases must NOT collide with a `groupBy` field name or measure
+   * alias — boot validation throws on collision.
    *
-   * @example
+   * @example "Daily revenue for the last quarter"
    * ```ts
-   * class PostController extends BaseController<Post> {
-   *   async getStats(ctx: IRequestContext) { … }
-   * }
+   * dailyRevenue: defineAggregation({
+   *   dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
+   *   measures: { revenue: 'sum:totalPrice' },
+   *   sort: { day: 1 },
+   *   permissions: requireRoles(['admin']),
+   * }),
+   * ```
    *
-   * defineResource({
-   *   controller: new PostController(repo),
-   *   routes: [{
-   *     method: 'GET',
-   *     path: '/stats',
-   *     controllerMethod: (c: PostController) => c.getStats,
-   *     //                       ^^^^^^^^^^^^^^ TS catches typos here
-   *     permissions: requireAuth(),
-   *   }],
-   * });
+   * @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(),
+   * }),
    * ```
    */
-  readonly controllerMethod?: (controller: unknown) => ControllerHandler | RouteHandlerMethod;
-  /** Permission check — REQUIRED */
-  readonly permissions: PermissionCheck;
+  dateBuckets?: Record<string, AggDateBucket>;
+  /** Named aggregations. At least one entry required. */
+  measures: Record<string, AggMeasureInput>;
   /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
-   * request/reply. Default: false.
+   * Post-aggregate filter referencing measure aliases.
+   * Example: `{ revenue: { gt: 1000 } }` → `HAVING revenue > 1000`.
    */
-  readonly raw?: boolean;
-  /** Logical operation name (pipeline keys, MCP tool naming). */
-  readonly operation?: string;
-  /** OpenAPI summary */
-  readonly summary?: string;
-  /** OpenAPI description */
-  readonly description?: string;
-  /** OpenAPI tags */
-  readonly tags?: string[];
-  /** Route-level middleware */
-  readonly preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
-  /** Pre-auth handlers (run before authentication) */
-  readonly preAuth?: RouteHandlerMethod[];
+  having?: AnyRecord;
+  /** Order grouped rows by groupBy field, measure alias, or joined-alias path. */
+  sort?: Record<string, 1 | -1>;
   /**
-   * Opt this custom route into the multiTenant preset's tenant scoping.
-   *
-   * When `true` AND the resource declares `multiTenantPreset` (or
-   * `flexibleMultiTenantPreset`), arc prepends the preset's tenant
-   * filter + injection middleware to this route's chain — the same
-   * pair `update` gets. The handler can then read the resolved tenant
-   * via `getOrgId(req.scope)` / `req._tenantFields` (or, for write
-   * routes, off `req.body` after injection) without re-implementing
-   * the scope read + header fallback + 400 boilerplate.
-   *
-   * Throws at boot if set when no multiTenant preset is wired — the
-   * misconfiguration would otherwise be silently insecure (read routes
-   * returning every tenant's rows).
-   *
-   * @default false
+   * Static hard cap on result rows. Always applied at the IR level
+   * (LIMIT / `$limit`), regardless of URL params. Use when the
+   * aggregation has a fixed-size shape ("top 10 categories"). Mutually
+   * exclusive with `defaultLimit` / `maxLimit` — pick the static form
+   * OR the URL-driven form, not both.
    */
-  readonly tenantScope?: boolean;
+  limit?: number;
   /**
-   * SSE streaming mode. Two handler shapes work:
+   * URL-driven row limit — applied when the caller passes `?limit=N`.
+   * When set, the auto-route reads `query.limit`, parses it as a
+   * positive integer, caps it at `maxLimit` (or the framework default
+   * if `maxLimit` is unset), and writes the result into `AggRequest.limit`.
+   * When the caller omits `?limit`, this default applies.
    *
-   * - Write to `reply.raw` directly (NDJSON, custom SSE — historical contract).
-   * - Return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`,
-   *   `fetch().body`, etc.). 2.17.1+ auto-pipes these through
-   *   `pipeUIMessageStreamToReply()` so each chunk is JSON-encoded into
-   *   an SSE `data:` frame and client-disconnect cancels the source.
-   *   Pre-2.17.1 this crashed with `chunk must be a string or Buffer`.
+   * **DoS defense.** Auto-generated `/aggregations/:name` routes today
+   * have no upper bound on response size. A `groupBy: 'userId'` on a
+   * 10M-user table without `defaultLimit` returns a 10M-row JSON. Setting
+   * `defaultLimit: 100, maxLimit: 1000` bounds the response shape while
+   * letting power users request up to 1000 rows when they need them.
+   *
+   * Mutually exclusive with the static `limit` — boot error if both set.
+   * Setting `defaultLimit` without `maxLimit` uses the framework
+   * default cap (`AGG_FRAMEWORK_MAX_LIMIT = 1000`) — explicit is better.
    */
-  readonly streamResponse?: boolean;
+  defaultLimit?: number;
   /**
-   * INTERNAL — marker stamped by built-in presets (softDelete, tree, …)
-   * onto routes they emit. Read by the MCP collision detector
-   * (`createMcpServer.resolveToolCollisions`) to attribute the route
-   * source ("preset:softDelete vs user `actions.restore`") and to
-   * auto-namespace the preset side when a user-authored tool legitimately
-   * shadows it. Not part of the public surface — hosts must not set this.
-   *
-   * @internal
+   * Hard ceiling for URL-driven `?limit=N`. Only meaningful when
+   * `defaultLimit` is set; ignored otherwise. Defaults to
+   * `AGG_FRAMEWORK_MAX_LIMIT` (1000) when omitted but `defaultLimit` is
+   * present. Boot validation: must be ≥ `defaultLimit`.
    */
-  readonly _presetSource?: string;
+  maxLimit?: number;
   /**
-   * Apply the resource's `fields` (field-level write permissions) to this
-   * custom route's request body.
+   * 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.
    *
-   * Default: `true` for body-bearing methods (POST/PUT/PATCH), `false`
-   * otherwise. Set to `false` to opt out — handler accepts the body as
-   * supplied with no field-write filtering. The resource-level
-   * `onFieldWriteDenied: 'reject' | 'strip'` setting governs how denials
-   * are surfaced.
+   * 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.
    *
-   * `raw: true` routes ALWAYS bypass this — they've opted out of the
-   * pipeline entirely.
+   * **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.
    */
-  readonly fieldWrite?: boolean;
+  topN?: AggTopN;
   /**
-   * Per-route rate limit. A custom route is its own Fastify route, so this
-   * overrides the resource-level `rateLimit` for THIS endpoint only:
-   *
-   *   - omitted                → inherit the resource-level limit (or app default)
-   *   - `false`                → disable rate limiting on this route
-   *   - `{ max, timeWindow }`  → apply this specific limit
-   *
-   * Requires `@fastify/rate-limit` registered (arc's factory wires it by
-   * default). Use for an expensive `/export` or an auth-sensitive `/reset`
-   * that needs a tighter cap than the resource's read-heavy CRUD, or `false`
-   * on an internal health/webhook route that must not be throttled.
-   *
-   * Note: this is per-route because each custom route is a distinct endpoint.
-   * `actions` share ONE `POST /:id/action` mount by design, so a per-ACTION
-   * limit can't be expressed here — throttle a specific action by promoting
-   * it to a dedicated `routes:` entry, or rely on the resource-level limit.
+   * 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.
    */
-  readonly rateLimit?: RateLimitConfig | false;
+  permissions: PermissionCheck;
   /**
-   * Fastify route schema. Each slot (`body`, `querystring`, `params`,
-   * `headers`, `response[status]`) accepts a plain JSON Schema object
-   * **or** a Zod v4 schema — Arc auto-converts via `convertRouteSchema`.
+   * DB-level execution cap (ms). Mongokit threads to `maxTimeMS`;
+   * sqlitekit threads to per-statement timeout where supported.
+   * Default: kit's default (typically none).
    */
-  readonly schema?: {
-    body?: unknown;
-    querystring?: unknown;
-    params?: unknown;
-    headers?: unknown;
-    response?: Record<number | string, unknown>;
-    [key: string]: unknown;
-  };
+  timeout?: number;
   /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate (non-raw routes only)
-   * - false: skip MCP
-   * - object: explicit config
+   * 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).
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  maxGroups?: number;
   /**
-   * MCP handler for raw routes — parallel entry point for MCP without
-   * changing the HTTP handler.
+   * 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.).
    */
-  readonly mcpHandler?: (input: Record<string, unknown>) => Promise<{
-    content: Array<{
-      type: string;
-      text: string;
-    }>;
-    isError?: boolean;
-  }>;
+  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/resource/events.d.ts
 /**
- * Action handler function for state transitions. Receives the resource
- * ID, action-specific data, and the request.
+ * Domain-event declaration on a resource — name, optional handler, and
+ * payload schema for the `events:` block of a resource definition.
  */
-type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
+interface EventDefinition {
+  name: string;
+  /** Optional handler — events are published via `fastify.events.publish()`. */
+  handler?: (data: unknown) => Promise<void> | void;
+  /**
+   * JSON Schema or Zod v4 schema for event payload. Typed `unknown` so Zod
+   * class instances assign without a cast (same convention as
+   * `ActionDefinition.schema` and `RouteDefinition.schema`).
+   */
+  schema?: unknown;
+  description?: string;
+}
+//#endregion
+//#region src/types/resource/extensions.d.ts
 /**
- * Full action configuration with handler, permissions, and schema.
+ * `ResourceExtensions` — the typed plugin-extension namespace plugins
+ * augment via declaration merging (`declare module "@classytic/arc/types"`).
+ */
+/**
+ * Plugin extension namespace — arc's typed escape hatch for attaching
+ * declarative, per-resource config that **plugins** read at request time.
+ *
+ * **External** plugins augment it via TypeScript declaration merging
+ * (`declare module "@classytic/arc/types"`) to register their own typed
+ * slice — exactly the model Fastify uses for `FastifyInstance` decorators.
+ * The host gets full autocomplete + compile-time checking on the matching
+ * `extensions` block, and a typo (`extensions: { encyrption: … }`) is a
+ * type error rather than a silent no-op.
+ *
+ * **First-party** slices (arc's own subpath plugins) are declared inline
+ * below with type-only imports instead of `declare module`. Not a style
+ * choice: arc bundles its declarations, and a relative module augmentation
+ * (`declare module "../types/resource.js"`) survives bundling as an
+ * unresolvable specifier — the merge silently never happens for consumers,
+ * so the key would be a compile ERROR downstream while working inside this
+ * repo. Inline declaration is bundler-proof; the type-only import is erased
+ * at runtime, so the plugin stays fully opt-in.
+ *
+ * **The "React for backend" composition model.** `defineResource()` is the
+ * declarative component, `extensions` is its typed props bag, and plugins
+ * are the providers that consume those props at the framework boundary.
+ * Adding a cross-cutting capability becomes *additive* — a plugin ships a
+ * subpath + a one-line `declare module` augmentation, with no new
+ * first-class `ResourceConfig` field and no core release per feature.
+ *
+ * Arc threads the declared `extensions` onto every generated route's
+ * Fastify `config` (see `createCrudRouter`), so a plugin reads its slice
+ * at request time via `request.routeOptions.config.arcExtensions` without
+ * re-deriving which resource a route belongs to.
+ *
+ * @example An external plugin package registers its slice
+ * ```ts
+ * declare module "@classytic/arc/types" {
+ *   interface ResourceExtensions {
+ *     myPlugin?: import("my-arc-plugin").MyPluginDirective;
+ *   }
+ * }
+ * ```
  *
- * Rate limiting is intentionally NOT per-action: every action shares one
- * `POST /:id/action` (or `POST /action`) mount, so Fastify's per-route limit
- * can't distinguish them. Actions inherit the resource-level `rateLimit`; to
- * throttle a specific operation, promote it to a `routes:` entry (which
- * supports `RouteDefinition.rateLimit`).
+ * @example A host declares it on a resource
+ * ```ts
+ * defineResource({
+ *   name: "payment",
+ *   extensions: { encryption: { mode: "fields", fields: ["cardNumber", "cvv"] } },
+ * });
+ * ```
  */
-interface ActionDefinition {
-  readonly handler: ActionHandlerFn;
-  /** Per-action permission (overrides resource-level `actionPermissions`) */
-  readonly permissions?: PermissionCheck;
-  /**
-   * JSON Schema or Zod v4 schema for action-specific body fields.
-   *
-   * Typed `unknown` (not `Record<string, unknown>`) so Zod class instances
-   * — `ZodObject<...>` carries no string index signature — assign without
-   * a cast. Same convention as `RouteDefinition.schema.body` / `customSchemas`.
-   * Runtime feature-detects via `convertRouteSchema` / `toJsonSchema`.
-   */
-  readonly schema?: unknown;
-  /** Description for OpenAPI docs and MCP tool */
-  readonly description?: string;
-  /**
-   * Whether this action needs an entity id from the URL.
-   *
-   * - `true` (default) — mounts under `POST /<prefix>/:id/action`. The `id`
-   *   path param is required; handler receives it as the first argument.
-   *   Use for actions that operate on an existing entity: `approve`,
-   *   `dispatch`, `cancel`, `archive`.
-   * - `false` — mounts under `POST /<prefix>/action` (no `:id` segment).
-   *   Handler receives an empty-string first argument. Use for
-   *   collection-level actions that create / search / bulk-mutate:
-   *   `propose` (creates a new entity), `search` (returns rows), `bulk`.
-   *
-   * 2.15.5: previously every action had to live under `:id/action`, forcing
-   * `propose`-style actions to swallow a meaningless URL parameter and
-   * making the auto-generated MCP tool advertise an `id` field agents
-   * had no value for. Setting `id: false` mounts the action at the
-   * resource root and drops `id` from the MCP tool's input shape.
-   */
-  readonly id?: boolean;
+interface ResourceExtensions {
   /**
-   * MCP tool generation:
-   * - omitted/true: auto-generate
-   * - false: skip
-   * - object: explicit config
+   * Encrypt this resource's responses — full-body JWE or specific fields.
+   * Read at request time by `@classytic/arc/encryption`'s `encryptionPlugin`
+   * from `request.routeOptions.config.arcExtensions.encryption`; inert (and
+   * dependency-free — the import is type-only) unless that plugin is
+   * registered.
    */
-  readonly mcp?: boolean | RouteMcpConfig;
+  encryption?: EncryptionDirective;
 }
-/** Action config: bare handler function OR full ActionDefinition. */
-type ActionEntry = ActionHandlerFn | ActionDefinition;
-/** Actions configuration map. */
-type ActionsMap = Record<string, ActionEntry>;
+//#endregion
+//#region src/types/resource/hooks.d.ts
 /**
  * Hook context passed to resource-level hook handlers. Mirrors
  * HookSystem's HookContext but with a simpler API for inline use.
@@ -2612,52 +2404,317 @@ interface ResourceHookContext {
   /** Authenticated user or null */
   user?: UserBase;
   /**
-   * Full typed request context — includes `_scope`, `_policyFilters`,
-   * `arc` metadata. Use `ctx.scope` for the common tenant/user projection;
-   * reach for `ctx.context` when you need `_scope.kind` branching or
-   * custom fields set by your auth adapter.
+   * Full typed request context — includes `_scope`, `_policyFilters`,
+   * `arc` metadata. Use `ctx.scope` for the common tenant/user projection;
+   * reach for `ctx.context` when you need `_scope.kind` branching or
+   * custom fields set by your auth adapter.
+   */
+  context?: AnyRecord;
+  /**
+   * First-class projection of request scope — `{ organizationId?, userId?, orgRoles? }`.
+   * Populated for every scoped request so multi-tenant hooks don't have to
+   * drill into `context._scope.organizationId` themselves. Matches the
+   * identically-named field on `IRequestContext` (v2.10.6) so the same
+   * read pattern works in controllers and hooks.
+   */
+  scope?: {
+    organizationId?: string;
+    userId?: string;
+    orgRoles?: string[];
+  };
+  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
+  meta?: AnyRecord;
+}
+/**
+ * Inline lifecycle hooks on a resource definition. Wired into the
+ * HookSystem automatically — same pipeline as presets and app-level hooks.
+ *
+ * @example
+ * ```typescript
+ * defineResource({
+ *   name: 'chat',
+ *   hooks: {
+ *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
+ *     beforeDelete: async (ctx) => {
+ *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface ResourceHooks {
+  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | undefined> | AnyRecord | undefined;
+  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | 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;
+}
+//#endregion
+//#region src/types/resource/fields.d.ts
+/**
+ * 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;
+  /**
+   * Aggregation visibility override. By default, only `hidden: true`
+   * blocks a field from `groupBy` / `measures.field` / `sort` / `dateBuckets`
+   * — that's the genuine cardinality-leak guard (the value is omitted from
+   * list/get responses, so exposing it via aggregation would reveal data
+   * the client can't otherwise see).
+   *
+   * `systemManaged: true` does **not** block aggregation — it's a write
+   * rule, not a visibility rule. Server-stamped fields like `createdAt`,
+   * `status`, or plugin-generated handles are visible in every list
+   * response and should aggregate freely.
+   *
+   * Use this flag to override the default:
+   *
+   * - `aggregable: false` — explicit deny, even on visible fields. Useful
+   *   when a value is exposed per-row but the cardinality across rows is
+   *   itself sensitive (e.g. `email` is visible in `get/:id` to admins
+   *   but you don't want a public-readable agg of email distributions).
+   * - `aggregable: true` — escape hatch on `hidden` fields. Lets you
+   *   aggregate a hidden column when you're sure cardinality leakage
+   *   isn't a concern (e.g. `internalScore` hidden from list, but a
+   *   committee-only `byScore` agg is fine).
+   *
+   * Defaults to `undefined` (use the `hidden`-only rule).
+   */
+  aggregable?: 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;
+}
+interface FieldRule$1 {
+  field: string;
+  required?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
+}
+//#endregion
+//#region src/types/resource/schemas.d.ts
+/**
+ * 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.
+   *
+   * 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[];
+  /**
+   * 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`.
    */
-  context?: AnyRecord;
+  fieldRules?: Record<string, ArcFieldRule>;
   /**
-   * First-class projection of request scope — `{ organizationId?, userId?, orgRoles? }`.
-   * Populated for every scoped request so multi-tenant hooks don't have to
-   * drill into `context._scope.organizationId` themselves. Matches the
-   * identically-named field on `IRequestContext` (v2.10.6) so the same
-   * read pattern works in controllers and hooks.
+   * Query-time security whitelists + the kit's `filterableFields`.
+   *
+   * Extends repo-core's `SchemaBuilderOptions['query']` with arc-specific
+   * runtime features that `QueryResolver` reads at request time:
+   *
+   * - **`allowedPopulate`** — populate-path whitelist consumed by
+   *   `QueryResolver.sanitizePopulate` / `sanitizeAdvancedPopulate`.
+   *   When set, only paths in the list pass through; everything else is
+   *   stripped silently. Shrinks the auto-wired `?populate=` attack surface.
+   *
+   * - **`allowedLookups`** — lookup-collection whitelist consumed by
+   *   `QueryResolver.sanitizeLookups`. When set, only the listed
+   *   collections may be `$lookup`'d into the pipeline.
+   *
+   * Both are pre-2.11.2 runtime features — the type was missing them, so
+   * hosts wrote `as Record<string, unknown>` at every call site. Arc's own
+   * `QueryResolver` had to cast its own input via `as AnyRecord` for the
+   * same reason. Adding the type dropped both casts.
    */
-  scope?: {
-    organizationId?: string;
-    userId?: string;
-    orgRoles?: string[];
+  query?: SchemaBuilderOptions["query"] & {
+    /**
+     * Populate-path whitelist. When set, `QueryResolver.sanitizePopulate`
+     * strips any `?populate=<path>` not in this list. Omit to allow all
+     * paths the kit recognizes.
+     */
+    allowedPopulate?: string[];
+    /**
+     * Lookup-collection whitelist for `QueryResolver.sanitizeLookups`.
+     * When set, only the listed collections may be `$lookup`'d. Omit to
+     * disable the whitelist (kit-level rules still apply).
+     */
+    allowedLookups?: string[];
   };
-  /** Additional metadata (e.g. `{ id, existing }` for update/delete) */
-  meta?: AnyRecord;
 }
 /**
- * Inline lifecycle hooks on a resource definition. Wired into the
- * HookSystem automatically — same pipeline as presets and app-level hooks.
- *
- * @example
- * ```typescript
- * defineResource({
- *   name: 'chat',
- *   hooks: {
- *     afterCreate: async (ctx) => { analytics.track('chat.created', { id: ctx.data._id }); },
- *     beforeDelete: async (ctx) => {
- *       if (ctx.data.isProtected) throw new Error('Cannot delete protected chat');
- *     },
- *   },
- * });
- * ```
+ * CRUD route schemas (Fastify native format). Each slot accepts a plain
+ * JSON Schema object **or** a Zod v4 schema — Arc's `convertRouteSchema`
+ * feature-detects at runtime. Slot values are typed `unknown` so
+ * class-based Zod schemas assign without casts.
  */
-interface ResourceHooks {
-  beforeCreate?: (ctx: ResourceHookContext) => Promise<AnyRecord | undefined> | AnyRecord | undefined;
-  afterCreate?: (ctx: ResourceHookContext) => Promise<void> | 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;
+interface CrudSchemas {
+  /** GET / — list */
+  list?: {
+    querystring?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** GET /:id — get one */
+  get?: {
+    params?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** POST / — create */
+  create?: {
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** PATCH /:id — update */
+  update?: {
+    params?: unknown;
+    body?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  /** DELETE /:id — delete */
+  delete?: {
+    params?: unknown;
+    response?: Record<number, unknown>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface OpenApiSchemas {
+  entity?: unknown;
+  createBody?: unknown;
+  updateBody?: unknown;
+  params?: unknown;
+  listQuery?: unknown;
+  /**
+   * Explicit response schema for OpenAPI documentation. Auto-generated
+   * from `createBody` if omitted. Does NOT affect Fastify serialization.
+   */
+  response?: unknown;
+  [key: string]: unknown;
+}
+type CrudRouteKey = "list" | "get" | "create" | "update" | "delete";
+interface MiddlewareConfig {
+  list?: MiddlewareHandler[];
+  get?: MiddlewareHandler[];
+  create?: MiddlewareHandler[];
+  update?: MiddlewareHandler[];
+  delete?: MiddlewareHandler[];
+  [key: string]: MiddlewareHandler[] | undefined;
 }
+//#endregion
+//#region src/types/resource/presets.d.ts
 interface PresetHook {
   operation: "create" | "update" | "delete" | "read" | "list";
   phase: "before" | "after";
@@ -2674,18 +2731,68 @@ interface PresetResult {
   hooks?: PresetHook[];
 }
 type PresetFunction = (config: ResourceConfig) => PresetResult;
-interface EventDefinition {
-  name: string;
-  /** Optional handler — events are published via `fastify.events.publish()`. */
-  handler?: (data: unknown) => Promise<void> | void;
+//#endregion
+//#region src/types/resource/tenant.d.ts
+/**
+ * Tenant-cleanup declaration on a resource — compliance-grade strategy
+ * for what happens to this resource's rows when the owning organization
+ * is deleted. Surfaces in arc's org-delete cascade runner and in
+ * registry introspection (audit scripts ask "what happens to this
+ * resource on org delete?").
+ *
+ * Strategy variants:
+ *   - `hard` — permanent removal (GDPR right-to-be-forgotten).
+ *   - `soft` — recoverable; pair with TTL for eventual hard-purge.
+ *   - `anonymize` — keep the row (legal retention) but clear PII
+ *     (HIPAA / PCI / SOX-compatible).
+ *   - `skip` — explicit opt-out with mandatory `reason`.
+ *
+ * See {@link ResourceConfig.onTenantDelete} for the full decision tree.
+ */
+interface OnTenantDeleteConfig {
   /**
-   * JSON Schema or Zod v4 schema for event payload. Typed `unknown` so Zod
-   * class instances assign without a cast (same convention as
-   * `ActionDefinition.schema` and `RouteDefinition.schema`).
+   * What to do with rows whose `tenantField` matches the deleted org.
+   * Discriminated union from `@classytic/repo-core/repository` — every
+   * kit's `purgeByField` consumes the same shape.
    */
-  schema?: unknown;
-  description?: string;
+  strategy: TenantPurgeStrategy;
+  /**
+   * Resources are processed in ascending `priority` order. Use to land
+   * leaf data (logs, events) before aggregate references. Default `100`.
+   */
+  priority?: number;
+  /**
+   * Rows per chunk for the underlying `purgeByField` call — bounds
+   * lock contention + replication-log pressure on very large tenants.
+   * Default kit-specific (~1000).
+   */
+  batchSize?: number;
+}
+/**
+ * Resolved tenant-purge declaration — what arc actually runs when
+ * `cascadeDeleteForOrganization` fires. Computed once at boot from the
+ * resource's `onTenantDelete` declaration.
+ *
+ * Exposed via `ResourceDefinition.resolvedTenantPurge` and
+ * `getCascadingResourcesWithMetadata(registry)` so audit tooling can
+ * answer "is this resource really going to hard-delete?" without
+ * reading the source.
+ */
+interface ResolvedTenantPurge {
+  readonly strategy: TenantPurgeStrategy;
+  readonly priority: number;
+  readonly batchSize?: number;
+  /**
+   * Where the strategy came from — `'declared'` (host wrote
+   * `onTenantDelete` explicitly) or `'disabled'` (no declaration —
+   * runner skips this resource).
+   */
+  readonly source: "declared" | "disabled";
 }
+//#endregion
+//#region src/types/resource/config.d.ts
+/** Standard controller type alias for CRUD operations. */
+type CrudController<TDoc> = IController<TDoc>;
 /** Resource-level permissions — only `PermissionCheck` functions allowed. */
 interface ResourcePermissions {
   list?: PermissionCheck;
@@ -2694,48 +2801,6 @@ interface ResourcePermissions {
   update?: PermissionCheck;
   delete?: PermissionCheck;
 }
-/**
- * Plugin extension namespace — arc's typed escape hatch for attaching
- * declarative, per-resource config that **plugins** read at request time.
- *
- * This interface is intentionally **empty in core**. Each optional plugin
- * augments it via TypeScript declaration merging to register its own typed
- * slice — exactly the model Fastify uses for `FastifyInstance` decorators.
- * A host that never installs a plugin never sees its key; a host that does
- * gets full autocomplete + compile-time checking on the matching
- * `extensions` block, and a typo (`extensions: { encyrption: … }`) is a
- * type error rather than a silent no-op.
- *
- * **The "React for backend" composition model.** `defineResource()` is the
- * declarative component, `extensions` is its typed props bag, and plugins
- * are the providers that consume those props at the framework boundary.
- * Adding a cross-cutting capability becomes *additive* — a plugin ships a
- * subpath + a one-line `declare module` augmentation, with no new
- * first-class `ResourceConfig` field and no core release per feature.
- *
- * Arc threads the declared `extensions` onto every generated route's
- * Fastify `config` (see `createCrudRouter`), so a plugin reads its slice
- * at request time via `request.routeOptions.config.arcExtensions` without
- * re-deriving which resource a route belongs to.
- *
- * @example A plugin registers its slice (in `@classytic/arc/encryption`)
- * ```ts
- * declare module "@classytic/arc/types" {
- *   interface ResourceExtensions {
- *     encryption?: import("@classytic/arc/encryption").EncryptionDirective;
- *   }
- * }
- * ```
- *
- * @example A host declares it on a resource
- * ```ts
- * defineResource({
- *   name: "payment",
- *   extensions: { encryption: { mode: "fields", fields: ["cardNumber", "cvv"] } },
- * });
- * ```
- */
-interface ResourceExtensions {}
 interface ResourceConfig<TDoc = AnyRecord> {
   name: string;
   displayName?: string;
@@ -2935,7 +3000,7 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * });
    * ```
    */
-  crud?: false | { [K in CrudRouteKey]?: boolean };
+  crud?: false | { [K in CrudRouteKey]?: boolean; };
   /**
    * Field name used for multi-tenant scoping (default: 'organizationId').
    * Override to match your schema: 'workspaceId', 'tenantId', etc.
@@ -3166,6 +3231,28 @@ interface ResourceConfig<TDoc = AnyRecord> {
   audit?: boolean | {
     operations?: ("create" | "update" | "delete")[];
   };
+  /**
+   * Per-record change timeline (2.22) — `history: true` adds
+   * `GET /:prefix/:id/history`, serving this record's audit entries
+   * (who/when/what-changed, newest first, `?limit=&offset=`). Implies
+   * `audit: true` (the flag auto-enables it when unset) and requires
+   * `auditPlugin` to be registered — the route answers 503 with
+   * `history.audit_unavailable` otherwise.
+   *
+   * Change history exposes before/after snapshots, so the gate defaults
+   * STRICTER than reads: the resource's `update` permission, falling back
+   * to `get`, falling back to authenticated-only via the route's normal
+   * auth. Override with the object form:
+   *
+   * ```ts
+   * defineResource({ name: 'order', history: true });
+   * defineResource({ name: 'payment', history: { permissions: requireRoles(['auditor']), limit: 100 } });
+   * ```
+   */
+  history?: boolean | {
+    permissions?: PermissionCheck;
+    limit?: number;
+  };
   /**
    * Typed plugin-extension namespace — declarative per-resource config that
    * arc plugins read at request time. Empty by default; each installed
@@ -3626,7 +3713,8 @@ type FastifyWithDecorators = FastifyInstance & {
   arc?: ArcDecorator;
   events?: EventsDecorator;
   authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>; /** Organization-scoped filtering — from `multiTenant` preset */
+  optionalAuthenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  /** Organization-scoped filtering — from `multiTenant` preset */
   organizationScoped?: (options?: {
     required?: boolean;
   }) => RouteHandlerMethod;
@@ -3991,8 +4079,10 @@ interface RegistryEntry extends ResourceMetadata {
    */
   actions?: Array<{
     readonly name: string;
-    readonly description?: string; /** Raw per-action schema (JSON Schema, Zod v4, or legacy field map) */
-    readonly schema?: unknown; /** Per-action permission check (if different from resource-level `actionPermissions`) */
+    readonly description?: string;
+    /** Raw per-action schema (JSON Schema, Zod v4, or legacy field map) */
+    readonly schema?: unknown;
+    /** Per-action permission check (if different from resource-level `actionPermissions`) */
     readonly permissions?: PermissionCheck;
     /**
      * 2.15.5: mount point — `true` (default) for `POST /:id/action`,
@@ -4001,7 +4091,8 @@ interface RegistryEntry extends ResourceMetadata {
      * resource manifests so callers can pick the right URL without
      * reading the action definition itself.
      */
-    readonly id?: boolean; /** MCP tool generation flag — `false` to skip, object for overrides */
+    readonly id?: boolean;
+    /** MCP tool generation flag — `false` to skip, object for overrides */
     readonly mcp?: boolean | {
       readonly description?: string;
       readonly annotations?: Record<string, unknown>;
@@ -4028,13 +4119,17 @@ interface RegistryEntry extends ResourceMetadata {
     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 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. */
+    };
+    /** Whether the aggregation requires named filters — surfaced in docs. */
     readonly requireFilters?: readonly string[];
     /**
      * Static result-row cap (no URL override). Mutually exclusive with
@@ -4052,7 +4147,8 @@ interface RegistryEntry extends ResourceMetadata {
      * URL-driven limit ceiling (only meaningful with `defaultLimit`).
      * OpenAPI docs render this as the `maximum` constraint on `?limit`.
      */
-    readonly maxLimit?: number; /** MCP tool generation flag — `false` to skip, object for overrides. */
+    readonly maxLimit?: number;
+    /** MCP tool generation flag — `false` to skip, object for overrides. */
     readonly mcp?: boolean | {
       readonly description?: string;
       readonly annotations?: Record<string, unknown>;
@@ -4141,4 +4237,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OnTenantDeleteConfig as $, UserOrganization as $t, RequestIdOptions as A, ArcCreateResult as An, AggregationMaterializedResult as At, defineResource as B, BodySanitizerConfig as Bn, Transform as Bt, RequestContext as C, afterDelete as Cn, AggMeasureInput as Ct, HealthCheck as D, beforeUpdate as Dn, AggregationDateRangeRequirement as Dt, GracefulShutdownOptions as E, beforeDelete as En, AggregationConfig as Et, FastifyWithDecorators as F, BaseControllerOptions as Fn, NextFunction as Ft, ActionsMap as G, JwtContext as Gt, ActionDefinition as H, AuthPluginOptions as Ht, MiddlewareHandler as I, ControllerConfigurableOptions as In, OperationFilter as It, CrudRouteKey as J, ApiResponse as Jt, ArcFieldRule as K, TokenPair as Kt, RequestWithExtras as L, ControllerConstructionOptions as Ln, PipelineConfig as Lt, EventsDecorator as M, ArcGetResult as Mn, AggregationsMap as Mt, FastifyRequestExtras as N, ArcListResult as Nn, Guard as Nt, HealthOptions as O, createHookSystem as On, AggregationIndexHint as Ot, FastifyWithAuth as P, ArcUpdateResult as Pn, Interceptor as Pt, MiddlewareConfig as Q, UserLike as Qt, RegisterOptions as R, ListResult as Rn, PipelineContext as Rt, QueryParserInterface as S, afterCreate as Sn, RouteHandler as St, CrudRouterOptions as T, beforeCreate as Tn, AggregationCacheConfig as Tt, ActionEntry as U, Authenticator as Ut, ResourceDefinition as V, AuthHelpers as Vt, ActionHandlerFn as W, AuthenticatorContext as Wt, EventDefinition as X, JWTPayload as Xt, CrudSchemas as Y, ArcRequest as Yt, FieldRule$1 as Z, ObjectId as Zt, ControllerQueryOptions as _, HookOperation as _n, ControllerLike as _t, InferAdapterDoc as a, SlugExt as an, ResolvedTenantPurge as at, ParsedQuery as b, HookSystem as bn, IControllerResponse as bt, TypedController as c, BulkMixin as cn, ResourceExtensions as ct, PaginationResult as d, QueryResolverConfig as dn, ResourcePermissions as dt, BaseController as en, OpenApiSchemas as et, IntrospectionData as f, AccessControl as fn, RouteDefinition as ft, ArcInternalMetadata as g, HookHandler as gn, ControllerHandler as gt, ResourceMetadata as h, HookContext as hn, RouteSchemaOptions as ht, ValidationResult as i, TreeMixin as in, RateLimitConfig as it, ArcDecorator as j, ArcDeleteResult as jn, AggregationRateLimit as jt, IntrospectionPluginOptions as k, defineHook as kn, AggregationMaterializedContext as kt, TypedRepository as l, BaseCrudController as ln, ResourceHookContext as lt, RegistryStats as m, DefineHookOptions as mn, RouteMethod as mt, ConfigError as n, SoftDeleteMixin as nn, PresetHook as nt, InferDocType as o, SlugMixin as on, ResourceCacheConfig as ot, RegistryEntry as p, AccessControlConfig as pn, RouteMcpConfig as pt, CrudController as q, AnyRecord as qt, ValidateOptions as r, TreeExt as rn, PresetResult as rt, InferResourceDoc as s, BulkExt as sn, ResourceConfig as st, RouteHandlerMethod$1 as t, SoftDeleteExt as tn, PresetFunction as tt, TypedResourceConfig as u, QueryResolver as un, ResourceHooks as ut, LookupOption as v, HookPhase as vn, FastifyHandler as vt, ServiceContext as w, afterUpdate as wn, AggMeasureShorthand as wt, PopulateOption as x, HookSystemOptions as xn, IRequestContext as xt, OwnershipCheck as y, HookRegistration as yn, IController as yt, ResourceRegistry as z, BodySanitizer as zn, PipelineStep as zt };
+export { OpenApiSchemas as $, UserOrganization as $t, RequestIdOptions as A, ArcCreateResult as An, RouteDefinition as At, defineResource as B, BodySanitizerConfig as Bn, RouteHandler as Bt, RequestContext as C, afterDelete as Cn, PipelineStep as Ct, HealthCheck as D, beforeUpdate as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, beforeDelete as En, ActionDefinition as Et, FastifyWithDecorators as F, BaseControllerOptions as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, JwtContext as Gt, CrudController as H, AuthPluginOptions as Ht, MiddlewareHandler as I, ControllerConfigurableOptions as In, FastifyHandler as It, PresetHook as J, ApiResponse as Jt, ResolvedTenantPurge as K, TokenPair as Kt, RequestWithExtras as L, ControllerConstructionOptions as Ln, IController as Lt, EventsDecorator as M, ArcGetResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ArcListResult as Nn, RateLimitConfig as Nt, HealthOptions as O, createHookSystem as On, ActionHandlerFn as Ot, FastifyWithAuth as P, ArcUpdateResult as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, UserLike as Qt, RegisterOptions as R, ListResult as Rn, IControllerResponse as Rt, QueryParserInterface as S, afterCreate as Sn, PipelineContext as St, CrudRouterOptions as T, beforeCreate as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, Authenticator as Ut, ResourceDefinition as V, AuthHelpers as Vt, ResourcePermissions as W, AuthenticatorContext as Wt, CrudRouteKey as X, JWTPayload as Xt, PresetResult as Y, ArcRequest as Yt, CrudSchemas as Z, ObjectId as Zt, ControllerQueryOptions as _, HookOperation as _n, Guard as _t, InferAdapterDoc as a, SlugExt as an, ResourceExtensions as at, ParsedQuery as b, HookSystem as bn, OperationFilter as bt, TypedController as c, BulkMixin as cn, AggMeasureShorthand as ct, PaginationResult as d, QueryResolverConfig as dn, AggregationDateRangeRequirement as dt, BaseController as en, RouteSchemaOptions as et, IntrospectionData as f, AccessControl as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookHandler as gn, AggregationsMap as gt, ResourceMetadata as h, HookContext as hn, AggregationRateLimit as ht, ValidationResult as i, TreeMixin as in, ResourceHooks as it, ArcDecorator as j, ArcDeleteResult as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, defineHook as kn, ActionsMap as kt, TypedRepository as l, BaseCrudController as ln, AggregationCacheConfig as lt, RegistryStats as m, DefineHookOptions as mn, AggregationMaterializedResult as mt, ConfigError as n, SoftDeleteMixin as nn, FieldRule$1 as nt, InferDocType as o, SlugMixin as on, EventDefinition as ot, RegistryEntry as p, AccessControlConfig as pn, AggregationMaterializedContext as pt, PresetFunction as q, AnyRecord as qt, ValidateOptions as r, TreeExt as rn, ResourceHookContext as rt, InferResourceDoc as s, BulkExt as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, SoftDeleteExt as tn, ArcFieldRule as tt, TypedResourceConfig as u, QueryResolver as un, AggregationConfig as ut, LookupOption as v, HookPhase as vn, Interceptor as vt, ServiceContext as w, afterUpdate as wn, Transform as wt, PopulateOption as x, HookSystemOptions as xn, PipelineConfig as xt, OwnershipCheck as y, HookRegistration as yn, NextFunction as yt, ResourceRegistry as z, BodySanitizer as zn, IRequestContext as zt };