@classytic/arc 2.32.0 → 2.34.0

package/dist/{index-CpzxqePp.d.mts → index-BcR2bFZQ.d.mts}

@@ -1,18 +1,436 @@
 
-import { a as QueryCacheConfig } from "./QueryCache-DFA-QrU9.mjs";
 import { P as ArcHeaders, i as RequestScope } from "./types-ChuShpCP.mjs";
-import { a as UserBase, l as AnyRecord, r as PermissionCheck } from "./types-B7XeLEgK.mjs";
+import { d as UserBase, l as PermissionCheck, t as AnyRecord } from "./base-Csjc2oF-.mjs";
+import { a as QueryCacheConfig } from "./QueryCache-DFA-QrU9.mjs";
 import "./elevation-BXCfVcNG.mjs";
 import { n as FieldPermissionMap } from "./fields-I_EeRWND.mjs";
 import { n as EncryptionDirective } from "./types-ByHn9rEO.mjs";
-import { n as DomainEvent } from "./EventTransport-2uVV34WU.mjs";
+import { n as DomainEvent } from "./EventTransport-BEVP50ka.mjs";
 import { Filter } from "@classytic/repo-core/filter";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
+import { AggDateBucket, AggMeasure, AggTopN, QueryOptions, StandardRepo, TenantPurgeStrategy, TransactionHandle } from "@classytic/repo-core/repository";
 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/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 `rawHandler`.
+ */
+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.
+ *
+ * Lifts the two fields most hosts need directly onto `req`, so a controller
+ * override never digs through `req.metadata._scope` and calls
+ * `getOrgId(scope)` / `getUserId(user)` by hand:
+ *
+ * ```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$1 {
+  /** 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 — `ArcHeaders` (`string | string[] | undefined` per
+   * name), the HONEST type: on the HTTP path this is Fastify's headers
+   * object passed through, and repeated headers arrive as `string[]` at
+   * runtime (2.24 widening — the previous `Record<string, string |
+   * undefined>` lied about that). Read via `getHeader(ctx.headers, name)`
+   * from `@classytic/arc/utils` for array-safe, duplicate-deterministic
+   * access, or `requireSingleHeaderValue` for security-sensitive headers.
+   */
+  headers: ArcHeaders;
+  /** 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$1;
+  /**
+   * 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 `rawHandler`.
+   *
+   * @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 `handler` 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(),
+ * }]
+ * ```
+ */
+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 `rawHandler` 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',
+ *   rawHandler: downloadFile,
+ *   permissions: requireAuth(),
+ * }]
+ * ```
+ */
+type RawRouteHandler = {
+  /**
+   * Fastify-native route handler — the type behind `RouteDefinition.rawHandler`.
+   *
+   * Declared with METHOD syntax and read back through an indexed access, which
+   * buys two properties a plain arrow alias can't have at once:
+   *
+   * - **Bivariant parameters.** `strictFunctionTypes` exempts method
+   *   declarations, so a handler annotated `FastifyRequest<{ Body: CreateBody }>`
+   *   assigns without a cast. Fastify's own `RouteHandlerMethod` is an arrow
+   *   alias, so it rejects those — hosts used to write `as any`.
+   * - **One call signature.** TypeScript contextually types parameters only
+   *   when a single constituent is callable, so inline
+   *   `rawHandler: async (request, reply) => …` infers instead of reporting
+   *   TS7006.
+   *
+   * The runtime always passes the real `(request, reply)` pair.
+   */
+  handler(this: FastifyInstance, request: FastifyRequest, reply: FastifyReply): unknown;
+}["handler"];
+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.
+ *
+ * Deliberately NO index signature: one would make real class instances fail
+ * structural assignment (`new ScrapController()` would need an
+ * `as unknown as ControllerLike` cast, because class instances don't have
+ * one). 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;
+}
+//#endregion
+//#region src/types/resource/writes.d.ts
+/**
+ * What every write verb receives besides its data.
+ *
+ * `create` gets exactly this shape; `update` / `delete` get the
+ * {@link MutationWriteContext} extension, which adds the loaded target.
+ */
+interface WriteContext<TDoc = AnyRecord> {
+  /**
+   * The arc request context. Resolve identity from `ctx.req.scope` via
+   * `getUserId` / `getOrgId` — never from headers, and never from `req.user`.
+   */
+  req: IRequestContext;
+  /**
+   * The repository arc would have called. Passed so a verb can COMPOSE with
+   * the default rather than replace it wholesale (validate, then delegate).
+   * Typed as the repo-core contract; a verb owning a richer kit repository
+   * usually closes over it directly instead of downcasting this one.
+   */
+  repository: RepositoryLike<TDoc>;
+  /**
+   * Present ONLY under `transactional: true`: repo-core's canonical
+   * `TransactionHandle` for the transaction this write runs in — imported,
+   * never restated, so a field added to the contract reaches write verbs
+   * instead of being silently dropped at this boundary.
+   * `uow.session` is the raw driver handle — the join point for work OUTSIDE
+   * the repository, canonically an outbox row:
+   * `outbox.store(event, { session: ctx.uow.session })` commits the event
+   * atomically with the business write. Connection-bound backends (SQLite)
+   * provide an empty handle; their tx-bound `ctx.repository` is the only
+   * join point.
+   */
+  uow?: TransactionHandle;
+}
+/**
+ * Context for `update` and `delete` verbs — operations with a mutable target.
+ *
+ * Both fields are REQUIRED, not optional: arc's `loadMutableTarget` preflight
+ * (access control, tenant scope, ownership) THROWS before the verb when the
+ * target cannot be produced, so by the time a verb runs the target exists.
+ * Typing them optional would push a defensive null-check into every command
+ * for a case that cannot occur.
+ */
+interface MutationWriteContext<TDoc = AnyRecord> extends WriteContext<TDoc> {
+  /**
+   * The REPOSITORY PRIMARY KEY — identical to the verb's own `id` argument.
+   *
+   * This is what `repository.update(id, …)` / `.delete(id, …)` would have
+   * received, which repo-core types as "update by primary key". It is NOT
+   * necessarily the value in the URL: a resource declaring `idField: 'slug'`
+   * routes on the slug while its repository keys off `_id`, and arc translates
+   * between them (`resolveMutationRepoId`) before either the repository or a
+   * verb is called. Handing a verb the raw route param would give a domain
+   * command a value its own repository cannot resolve.
+   *
+   * The route param is still reachable — `ctx.req.params.id`.
+   */
+  id: string;
+  /**
+   * The document as arc loaded it to run its permission and tenant checks.
+   * Handed over rather than re-fetched by the verb on purpose: a second read
+   * can observe a different document than the one the request was authorised
+   * against.
+   */
+  existing: TDoc;
+}
+/**
+ * Per-slot write commands. Every field is optional and independent: declare
+ * `update` alone and `create` / `delete` keep calling the repository.
+ *
+ * **Return contract, and it differs from the repository's on purpose.**
+ * A repository signals "not found" by returning `null`; a domain command
+ * signals failure by THROWING a typed error. So when a verb is declared:
+ *
+ *   - `create` — must return the created document. A nullish return is a
+ *     CONTRACT VIOLATION and arc throws (a 201 carrying `undefined` data and
+ *     after-hooks fed a non-document would be worse than the loud failure).
+ *   - `update` — returning the updated document is preferred (it becomes the
+ *     response directly). A `void` return is also success — arc issues ONE
+ *     repository re-read to answer the request, so a void-returning command
+ *     costs one extra read per update. It is never translated into a 404.
+ *   - `delete` — `undefined` is success. `deleteDraft()` returns `void`, and
+ *     treating that as a miss would answer 404 for a delete that happened.
+ */
+interface ResourceWrites<TDoc = AnyRecord> {
+  create?(data: Partial<TDoc>, ctx: WriteContext<TDoc>): Promise<TDoc>;
+  update?(id: string, data: Partial<TDoc>, ctx: MutationWriteContext<TDoc>): Promise<TDoc | null | undefined>;
+  delete?(id: string, ctx: MutationWriteContext<TDoc>): Promise<unknown>;
+}
+/**
+ * The three slots a write verb may be declared for. Kept in lockstep with the
+ * runtime list (`MUTATION_OPERATIONS` in `constants.ts`) by a `satisfies`
+ * check at its use sites — drift is a compile error, not a runtime surprise.
+ */
+type WriteVerbKey = "create" | "update" | "delete";
+//#endregion
 //#region src/core/BodySanitizer.d.ts
 /**
  * Policy for handling fields the caller lacks write permission for.
@@ -31,10 +449,25 @@ interface BodySanitizerConfig {
    * Default: `'reject'` — surface the misconfiguration as a 403.
    */
   onFieldWriteDenied?: FieldWriteDenialPolicy;
+  /**
+   * What to do when an update body carries an `immutable` /
+   * `immutableAfterCreate` field. Default: `'strip'` — today's behaviour.
+   *
+   * `'reject'` throws a 403 instead of returning 200 with the field silently
+   * unchanged (observed live: `PATCH {"type":"rent"}` → 200, `"type":"purchase"`).
+   *
+   * NOT folded into {@link onFieldWriteDenied}, which defaults to `'reject'`:
+   * a full-object PATCH echoing an immutable field back UNCHANGED is legitimate,
+   * and the sanitizer has no stored document to distinguish it from a real
+   * change. Sharing that default would break those callers. Opt in per resource,
+   * or fleet-wide via `ARC_STRICT_IMMUTABLE_WRITES`.
+   */
+  onImmutableWrite?: FieldWriteDenialPolicy;
 }
 declare class BodySanitizer {
   private schemaOptions;
   private onFieldWriteDenied;
+  private onImmutableWrite;
   constructor(config: BodySanitizerConfig);
   /**
    * Strip readonly and system-managed fields from request body.
@@ -182,6 +615,25 @@ interface ControllerConfigurableOptions {
    * - `'strip'`: legacy silent-drop.
    */
   onFieldWriteDenied?: FieldWriteDenialPolicy;
+  /** Immutable-write policy — see `onImmutableWrite` on the resource config. */
+  onImmutableWrite?: FieldWriteDenialPolicy;
+  /**
+   * Domain commands bound to the create / update / delete slots. When a slot
+   * declares one, the controller runs its full pipeline and calls the verb
+   * instead of `repository.<op>` — see `ResourceWrites`.
+   *
+   * Configurable rather than construction-only so a HOST-SUPPLIED controller
+   * receives it through `configure()` too. A custom controller that keeps
+   * `BaseCrudController`'s write methods is the common case, and it must not
+   * silently lose the resource's verbs just because it was hand-constructed.
+   */
+  writes?: ResourceWrites;
+  /**
+   * Transactional write envelope — see `ResourceConfig.transactional`.
+   * Configurable so a host-supplied controller receives it through
+   * `configure()` like `writes`.
+   */
+  transactional?: boolean;
 }
 /**
  * Full constructor options — union of construction-only + configurable.
@@ -197,13 +649,17 @@ interface BaseControllerOptions extends ControllerConstructionOptions, Controlle
  * still available through the underlying `RequestScope` for advanced
  * branching on `scope.kind`.
  */
-interface RequestScopeProjection$1 {
+interface RequestScopeProjection {
   /** Tenant the caller is scoped to (member, pinned elevated admin, service key bound to an 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[];
+  /** Active team for member scopes. */
+  teamId?: string;
+  /** Host-defined project / branch / region / workspace dimensions. */
+  context?: Readonly<Record<string, string>>;
 }
 //#endregion
 //#region src/hooks/HookSystem.d.ts
@@ -229,7 +685,7 @@ interface HookContext<T = AnyRecord> {
    * routes. Branch on `scope.kind` via `ctx.context._scope` when you need the
    * full discriminated union.
    */
-  scope?: RequestScopeProjection$1;
+  scope?: RequestScopeProjection;
 }
 type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
 /**
@@ -588,9 +1044,12 @@ interface QueryResolverConfig {
 declare class QueryResolver {
   private queryParser;
   private maxLimit;
+  /** Set only when the HOST passed one — it outranks any parser's cap, at any time. */
+  private readonly explicitMaxLimit;
   private defaultLimit;
   /** `undefined` means "no default sort" (caller passed `false`). */
   private defaultSort;
+  private readonly explicitDefaultSort;
   private schemaOptions;
   private tenantField;
   constructor(config?: QueryResolverConfig);
@@ -601,6 +1060,22 @@ declare class QueryResolver {
    * truth — pairs with `BaseCrudController.setQueryParser()`.
    */
   setParser(parser: QueryParserInterface): void;
+  /**
+   * The default sort, but only when the parser permits the field.
+   *
+   * A resource declaring `allowedSortFields` has stated exactly what may be
+   * sorted on. Arc then applied its OWN default of `-createdAt` on top, and
+   * mongokit 3.31 REJECTS a sort outside the allowlist rather than dropping it —
+   * so every list call on such a resource answered 400, `Blocked sort field not
+   * in allowlist: createdAt`. REST and MCP alike; the endpoint was unusable, and
+   * nothing the caller sent could avoid it.
+   *
+   * A general default must never outrank a specific declaration, so the
+   * FRAMEWORK default withdraws. A HOST-declared `defaultSort` is left alone —
+   * that contradiction is its author's to resolve, and `defineResource` reports
+   * it as a boot diagnostic instead of arc silently picking a winner.
+   */
+  private permittedDefaultSort;
   /**
    * Resolve a request into parsed query options -- ONE parse per request.
    * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
@@ -690,6 +1165,16 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    */
   protected _defaultSort?: string | false;
   protected _onFieldWriteDenied?: FieldWriteDenialPolicy;
+  protected _onImmutableWrite?: FieldWriteDenialPolicy;
+  /**
+   * Domain commands bound to the write slots (`ResourceWrites`). Consulted at
+   * the PERSISTENCE step only — everything upstream of it (sanitizer, tenant
+   * injection, actor stamp, hook sandwich) runs exactly as it does without
+   * one, which is the entire point of the seam.
+   */
+  protected _writes?: ResourceWrites;
+  /** Transactional write envelope — see `ResourceConfig.transactional`. */
+  protected _transactional: boolean;
   constructor(repository: TRepository, options?: BaseControllerOptions);
   /**
    * Swap the controller's query parser. Mutates the existing `QueryResolver`
@@ -823,6 +1308,35 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
     meta?: Record<string, unknown>;
     pipeProcessedData?: boolean;
   }, executor: (processed: TInput) => Promise<TResult>): Promise<TResult>;
+  /**
+   * Run a write's PERSISTENCE step, transactionally when the resource asked.
+   *
+   * Plain mode hands `fn` the live repository. Transactional mode runs it
+   * through repo-core's `retryingTransaction`: the callback receives the
+   * TX-BOUND repository (so declared verbs and repository calls join the same
+   * transaction), transient conflicts re-run `fn` with jittered bounded
+   * backoff, everything else — including `VersionConflictError` — surfaces
+   * once. Hooks stay OUTSIDE: before/around ran already and must not re-run;
+   * after-hooks run post-commit, which they already do by running after this.
+   */
+  protected runWritePersistence<T>(fn: (repo: TRepository, uow?: TransactionHandle) => Promise<T>): Promise<T>;
+  /** Assemble the `WriteContext` a `create` verb receives. */
+  protected writeContext(req: IRequestContext, repo?: TRepository, uow?: TransactionHandle): WriteContext;
+  /**
+   * Assemble the `MutationWriteContext` an `update` / `delete` verb receives.
+   *
+   * `existing` is the document arc ALREADY loaded to run its permission and
+   * tenant checks — `loadMutableTarget` throws before any verb runs when it
+   * cannot produce one, which is why the context types it required. Handing
+   * it over rather than letting the verb re-fetch is deliberate: a second
+   * read can observe a different document than the one the request was
+   * authorised against.
+   *
+   * `id` is the REPOSITORY PRIMARY KEY (`repoId`), never the raw route param —
+   * see the note on `MutationWriteContext.id`. Callers pass `resolveRepoId`'s
+   * output.
+   */
+  protected mutationWriteContext(req: IRequestContext, id: string, existing: unknown, repo?: TRepository, uow?: TransactionHandle): MutationWriteContext;
   /**
    * Run `executeAfter` for the given op + data. No-op when hooks aren't
    * wired or `resourceName` isn't set. Caller passes the data shape it
@@ -1186,396 +1700,74 @@ interface AuthPluginOptions {
   /**
    * Custom auth failure handler. Customize the 401 response when
    * authentication fails.
-   */
-  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
-  /**
-   * Expose detailed auth error messages in 401 responses. When `false`
-   * (default), returns generic "Authentication required". Decoupled from
-   * log level — set explicitly per environment.
-   */
-  exposeAuthErrors?: boolean;
-  /** Property name to store user on request (default: 'user') */
-  userProperty?: string;
-  /**
-   * Custom token extractor for the built-in JWT auth path. Defaults to
-   * extracting Bearer token from Authorization header. Use when tokens
-   * are in HttpOnly cookies, custom headers, or query params.
-   *
-   * @example
-   * ```typescript
-   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
-   * ```
-   */
-  tokenExtractor?: (request: FastifyRequest) => string | null;
-  /**
-   * Token revocation check — called after JWT verification succeeds.
-   * Return `true` to reject the token (revoked), `false` to allow.
-   *
-   * **Fail-closed**: if the check throws, the token is treated as revoked.
-   *
-   * @example
-   * ```typescript
-   * isRevoked: async (decoded) => {
-   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
-   * },
-   * ```
-   */
-  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
-  /**
-   * Enforce strict JWT `type` claim validation (default: `true`).
-   *
-   * When enabled, `authenticate` requires `decoded.type === "access"`.
-   * Tokens with a missing or unexpected `type` claim are rejected —
-   * defence in depth for apps that reuse the JWT secret to sign other
-   * token kinds (invite links, one-time verification codes).
-   *
-   * Arc's own `issueTokens` always sets `type: "access"` or
-   * `type: "refresh"`, so this default is safe for Arc-generated tokens.
-   *
-   * Set to `false` ONLY when you must accept tokens signed without a
-   * `type` claim (e.g. a legacy issuer you don't control). In that mode
-   * Arc still rejects tokens explicitly marked `type: "refresh"`.
-   */
-  strictTokenType?: boolean;
-}
-//#endregion
-//#region src/core/middlewares/rateLimit.d.ts
-/**
- * Per-route CORS override, read by `@fastify/cors` off `routeOptions.config.cors`.
- *
- * The app-wide policy cannot serve both an API and public assets: an API wants
- * `credentials: true` with a pinned origin list, while a public asset wants
- * `origin: "*"` — and `*` with credentials is forbidden by the CORS spec (arc
- * throws at boot on that combination). Per-route is the granularity that
- * resolves it. `false` disables CORS for the route entirely.
- *
- * Arc does not interpret the value; `@fastify/cors` owns the semantics. Typed
- * loosely on purpose so a host is never blocked by arc lagging the plugin's
- * option surface.
- */
-type RouteCorsConfig = Record<string, unknown> | false;
-//#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 `rawHandler`.
- */
-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.
- *
- * Lifts the two fields most hosts need directly onto `req`, so a controller
- * override never digs through `req.metadata._scope` and calls
- * `getOrgId(scope)` / `getUserId(user)` by hand:
- *
- * ```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 — `ArcHeaders` (`string | string[] | undefined` per
-   * name), the HONEST type: on the HTTP path this is Fastify's headers
-   * object passed through, and repeated headers arrive as `string[]` at
-   * runtime (2.24 widening — the previous `Record<string, string |
-   * undefined>` lied about that). Read via `getHeader(ctx.headers, name)`
-   * from `@classytic/arc/utils` for array-safe, duplicate-deterministic
-   * access, or `requireSingleHeaderValue` for security-sensitive headers.
-   */
-  headers: ArcHeaders;
-  /** Organization ID (for multi-tenant apps) */
-  organizationId?: string;
-  /** Team ID (for team-scoped resources) */
-  teamId?: string;
+   */
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
   /**
-   * 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.
+   * Expose detailed auth error messages in 401 responses. When `false`
+   * (default), returns generic "Authentication required". Decoupled from
+   * log level — set explicitly per environment.
    */
-  scope?: RequestScopeProjection;
+  exposeAuthErrors?: boolean;
+  /** Property name to store user on request (default: 'user') */
+  userProperty?: string;
   /**
-   * Organization/auth context from middleware.
-   * Contains orgRoles, orgScope, organizationId, and any custom fields
-   * set by the auth adapter or org-scope plugin.
+   * Custom token extractor for the built-in JWT auth path. Defaults to
+   * extracting Bearer token from Authorization header. Use when tokens
+   * are in HttpOnly cookies, custom headers, or query params.
    *
    * @example
    * ```typescript
-   * async create(req: IRequestContext) {
-   *   const roles = req.context?.orgRoles ?? [];
-   *   if (roles.includes('manager')) { ... }
-   * }
+   * tokenExtractor: (request) => request.cookies?.['auth-token'] ?? null,
    * ```
    */
-  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;
+  tokenExtractor?: (request: FastifyRequest) => string | null;
   /**
-   * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `rawHandler`.
+   * Token revocation check — called after JWT verification succeeds.
+   * Return `true` to reject the token (revoked), `false` to allow.
+   *
+   * **Fail-closed**: if the check throws, the token is treated as revoked.
    *
    * @example
    * ```typescript
-   * 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 };
-   * }
+   * isRevoked: async (decoded) => {
+   *   return await redis.sismember('revoked-tokens', decoded.jti ?? decoded.id);
+   * },
    * ```
    */
-  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 `handler` 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(),
- * }]
- * ```
- */
-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 `rawHandler` 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',
- *   rawHandler: downloadFile,
- *   permissions: requireAuth(),
- * }]
- * ```
- */
-type RawRouteHandler = {
+  isRevoked?: (decoded: Record<string, unknown>) => boolean | Promise<boolean>;
   /**
-   * Fastify-native route handler — the type behind `RouteDefinition.rawHandler`.
+   * Enforce strict JWT `type` claim validation (default: `true`).
    *
-   * Declared with METHOD syntax and read back through an indexed access, which
-   * buys two properties a plain arrow alias can't have at once:
+   * When enabled, `authenticate` requires `decoded.type === "access"`.
+   * Tokens with a missing or unexpected `type` claim are rejected —
+   * defence in depth for apps that reuse the JWT secret to sign other
+   * token kinds (invite links, one-time verification codes).
    *
-   * - **Bivariant parameters.** `strictFunctionTypes` exempts method
-   *   declarations, so a handler annotated `FastifyRequest<{ Body: CreateBody }>`
-   *   assigns without a cast. Fastify's own `RouteHandlerMethod` is an arrow
-   *   alias, so it rejects those — hosts used to write `as any`.
-   * - **One call signature.** TypeScript contextually types parameters only
-   *   when a single constituent is callable, so inline
-   *   `rawHandler: async (request, reply) => …` infers instead of reporting
-   *   TS7006.
+   * Arc's own `issueTokens` always sets `type: "access"` or
+   * `type: "refresh"`, so this default is safe for Arc-generated tokens.
    *
-   * The runtime always passes the real `(request, reply)` pair.
+   * Set to `false` ONLY when you must accept tokens signed without a
+   * `type` claim (e.g. a legacy issuer you don't control). In that mode
+   * Arc still rejects tokens explicitly marked `type: "refresh"`.
    */
-  handler(this: FastifyInstance, request: FastifyRequest, reply: FastifyReply): unknown;
-}["handler"];
-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;
-  }>>;
+  strictTokenType?: boolean;
 }
+//#endregion
+//#region src/core/middlewares/rateLimit.d.ts
 /**
- * Flexible controller interface — accepts controllers with any handler style,
- * including class instances with extra methods / private fields.
+ * Per-route CORS override, read by `@fastify/cors` off `routeOptions.config.cors`.
  *
- * Deliberately NO index signature: one would make real class instances fail
- * structural assignment (`new ScrapController()` would need an
- * `as unknown as ControllerLike` cast, because class instances don't have
- * one). Arc only invokes the CRUD methods at runtime, so the rest of the
- * shape is the caller's concern.
+ * The app-wide policy cannot serve both an API and public assets: an API wants
+ * `credentials: true` with a pinned origin list, while a public asset wants
+ * `origin: "*"` — and `*` with credentials is forbidden by the CORS spec (arc
+ * throws at boot on that combination). Per-route is the granularity that
+ * resolves it. `false` disables CORS for the route entirely.
  *
- * 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).
+ * Arc does not interpret the value; `@fastify/cors` owns the semantics. Typed
+ * loosely on purpose so a host is never blocked by arc lagging the plugin's
+ * option surface.
  */
-interface ControllerLike {
-  list?: unknown;
-  get?: unknown;
-  create?: unknown;
-  update?: unknown;
-  delete?: unknown;
-}
+type RouteCorsConfig = Record<string, unknown> | false;
 //#endregion
 //#region src/types/resource/rate-limit.d.ts
 /**
@@ -1672,6 +1864,41 @@ interface RouteDefinition {
   readonly controllerMethod?: (controller: unknown) => ControllerHandler;
   /** Permission check — REQUIRED */
   readonly permissions: PermissionCheck;
+  /**
+   * PUBLISH this route's gate in the permission matrix, under this key.
+   *
+   * ## Why a route needs to opt in, when CRUD and actions do not
+   *
+   * `introspectRegistry` walks `permissions`, `actions` and `aggregations` —
+   * each of which has a stable NAME to key by. A route has only a method and a
+   * path, and a path is not an identity: `/recompute` becoming
+   * `/classification/recompute` would silently break every client gating on it.
+   * So routes were skipped, and the consequence was not a missing feature but an
+   * invisible one — a resource whose gates live entirely on `routes[]` publishes
+   * NOTHING, is absent from the matrix, and every `can()` against it returns
+   * `false`. A UI that gates on it hides the feature from everyone including
+   * admins, which reads as "my permissions are broken" rather than "this key was
+   * never published".
+   *
+   * Declaring `capability` gives the gate the stable name it was missing. The key
+   * is BARE, sitting alongside `list` / `get` / `create` — a consumer asks
+   * `can('sku-classification', 'recompute')` and does not need to know whether
+   * the verb is implemented as a route, an action or a CRUD slot.
+   *
+   * Omit it for routes nothing needs to gate a UI on (a health check, a public
+   * manifest). The route is still ENFORCED either way — this only controls
+   * whether clients can SEE the decision in advance.
+   *
+   * Collides with a CRUD slot, an `action:`, an `agg:` or another route on the
+   * same resource ⇒ `defineResource()` THROWS at boot. A silent overwrite would
+   * let one gate answer for a different verb, and `introspectRegistry` refuses
+   * the same collision as a backstop for hand-built registry entries.
+   *
+   * @example
+   * { method: 'POST', path: '/recompute', capability: 'recompute',
+   *   permissions: requireRoles(['admin']) }
+   */
+  readonly capability?: string;
   /**
    * Fastify-native handler — receives `(request, reply)` and owns the response.
    * Bypasses arc's pipeline entirely: no `IControllerResponse` shaping, no
@@ -1811,6 +2038,35 @@ interface RouteDefinition {
     response?: Record<number | string, unknown>;
     [key: string]: unknown;
   };
+  /**
+   * Fastify route CONFIG — `reply.routeOptions.config` at request time.
+   *
+   * Fastify's own first-class route option (Reference/Routes.md § Config), passed
+   * straight through. Arc adds no semantics: it is the documented seam every Fastify
+   * plugin uses to take per-route options, and arc forwarding it is what makes those
+   * plugins reachable from a `defineResource` route at all.
+   *
+   * ## Why this is not optional polish
+   *
+   * Arc REGISTERS `fastify-raw-body` with `global: false` (see `registerSecurity`),
+   * which means a route opts in with `config: { rawBody: true }`. Without this field
+   * that opt-in had nowhere to live, so the plugin arc itself installs was
+   * unreachable from any resource — and a route that wrote it got no error, just a
+   * silently absent `request.rawBody`.
+   *
+   * The cost of that was found end-to-end, not by review: every HMAC-signed webhook
+   * verified its signature against a body it never received, so a real provider
+   * callback 401'd in production while every unit test passed.
+   *
+   * @example
+   * // Signature verification needs the exact transmitted bytes.
+   * { method: 'POST', path: '/webhooks', config: { rawBody: true }, rawHandler }
+   *
+   * @example
+   * // Anything a plugin reads per-route — rate-limit overrides, feature flags.
+   * { method: 'GET', path: '/report', config: { rateLimit: { max: 5 } } }
+   */
+  readonly config?: Record<string, unknown>;
   /**
    * MCP tool generation:
    * - omitted/true: auto-generate (non-raw routes only)
@@ -2843,6 +3099,44 @@ interface ResourceConfig<TDoc = AnyRecord> {
   adapter?: DataAdapter<TDoc>;
   /** Controller instance — accepts any object with CRUD methods. */
   controller?: IController<TDoc> | ControllerLike;
+  /**
+   * Bind a CRUD write slot to a DOMAIN COMMAND, keeping arc's request
+   * pipeline. Arc still sanitizes against the resource's field rules, injects
+   * the tenant field, stamps the actor and runs the hook sandwich — then calls
+   * your verb where it would have called `repository.create/update/delete`.
+   *
+   * Reach for this whenever the kernel behind the resource owns a GUARDED
+   * write (a verb that refuses once a document is posted / closed / locked).
+   * Overriding the controller method instead silently drops the pipeline —
+   * see `ResourceWrites` for the two-way trap this closes.
+   *
+   * @example
+   * ```typescript
+   * writes: {
+   *   create: (data, ctx) => engine.invoices.createDraft(data, resolveCtx(ctx.req)),
+   *   update: (id, data, ctx) => engine.invoices.updateDraft(id, data, resolveCtx(ctx.req)),
+   *   delete: (id, ctx) => engine.invoices.deleteDraft(id, resolveCtx(ctx.req)),
+   * }
+   * ```
+   */
+  writes?: ResourceWrites<TDoc>;
+  /**
+   * Run every CRUD write (and its declared verb) inside a repository
+   * transaction with TRANSIENT-conflict retry (repo-core
+   * `retryingTransaction`): begin → persistence/verb → commit, re-run on the
+   * kit-classified conflicts only, jittered bounded backoff.
+   *
+   * Contract: before/around hooks run ONCE (outside the retry); the
+   * persistence step may re-run, which is safe by construction when side
+   * effects go through the tx-bound repository (they roll back) or an outbox
+   * row; after-hooks run once, post-commit. A `VersionConflictError`
+   * (`ifVersion` CAS) is NOT transient and surfaces as 409.
+   *
+   * Boot-fatal when the adapter's repository has no `withTransaction`
+   * (capability `transactions: false`) — a requested transactional envelope
+   * that silently degrades is the defect, not a mode.
+   */
+  transactional?: boolean;
   queryParser?: unknown;
   permissions?: ResourcePermissions;
   schemaOptions?: RouteSchemaOptions;
@@ -2888,6 +3182,18 @@ interface ResourceConfig<TDoc = AnyRecord> {
    *   pre-2.9 code that relied on the permissive default.
    */
   onFieldWriteDenied?: "reject" | "strip";
+  /**
+   * What to do when an UPDATE body carries an `immutable` /
+   * `immutableAfterCreate` field. Default `'strip'`.
+   *
+   * `'reject'` answers 403 instead of 200-with-the-field-unchanged. Kept
+   * separate from `onFieldWriteDenied` (which defaults to `'reject'`) because a
+   * full-object PATCH echoing an immutable field back UNCHANGED is legitimate,
+   * and the sanitizer has no stored document to tell that from a real change.
+   * Hosts sending partial patches should turn it on; `ARC_STRICT_IMMUTABLE_WRITES`
+   * sets it fleet-wide.
+   */
+  onImmutableWrite?: "reject" | "strip";
   middlewares?: MiddlewareConfig;
   /**
    * PreHandler guards auto-applied to **every** route on this resource
@@ -3444,6 +3750,22 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
    * snapshot so callers can't accidentally mutate the diagnostic list.
    */
   _diagnostics?: ResourceDiagnostic[];
+  /**
+   * Boot-time assertions that CANNOT be settled at define time because
+   * they read state a connection establishes.
+   *
+   * `defineResource()` frequently runs at module-import time — before
+   * `beforeBoot()` opens the database. A repository's capability
+   * descriptor is therefore not yet authoritative then: mongokit
+   * deliberately reports `transactions: false` for an unresolved topology
+   * (fail-closed), so asserting at define time would reject a correctly
+   * configured app for the crime of importing its resources early.
+   *
+   * `buildResourcePlugin` runs these on first mount — lifecycle slot 5,
+   * after `beforeBoot` (0) and module resolution (0.5) — where the same
+   * fail-closed rule finally means what it says.
+   */
+  _deferredChecks?: Array<() => void>;
   /**
    * Public view of {@link _diagnostics} for programmatic consumption.
    *
@@ -4016,6 +4338,13 @@ interface QueryParserInterface {
    * is not explicitly configured.
    */
   allowedFilterFields?: readonly string[];
+  /**
+   * Optional: the parser's own page-size cap.
+   *
+   * A parser that declares one has ANSWERED the question, and `QueryResolver` must
+   * defer to it rather than applying its own default on top — see the note there.
+   */
+  maxLimit?: number;
   /**
    * Optional: Allowed filter operators whitelist. Used by MCP to enrich
    * list-tool descriptions. Values are human-readable keys: 'eq', 'ne',
@@ -4062,6 +4391,11 @@ interface ResourceMetadata {
     summary?: string;
     description?: string;
     permissions?: PermissionCheck;
+    /**
+     * Matrix key this route's gate is published under. Absent ⇒ enforced but not
+     * advertised — see `capability` on `RouteDefinition`.
+     */
+    capability?: string;
     raw?: boolean;
     schema?: unknown;
   }>;
@@ -4295,4 +4629,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, TreeMixin as $t, RequestIdOptions as A, BaseControllerOptions as An, RouteDefinition as At, defineResource as B, RawRouteHandler as Bt, RequestContext as C, createHookSystem as Cn, PipelineStep as Ct, HealthCheck as D, ArcGetResult as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, ArcDeleteResult as En, ActionDefinition as Et, FastifyWithDecorators as F, BodySanitizerConfig as Fn, ControllerLike as Ft, OnTenantDeleteConfig as G, Authenticator as Gt, CrudController as H, ServerAccessor as Ht, MiddlewareHandler as I, FastifyHandler as It, PresetHook as J, TokenPair as Jt, ResolvedTenantPurge as K, AuthenticatorContext as Kt, RequestWithExtras as L, IController as Lt, EventsDecorator as M, ControllerConstructionOptions as Mn, RouteMethod as Mt, FastifyRequestExtras as N, ListResult as Nn, RateLimitConfig as Nt, HealthOptions as O, ArcListResult as On, ActionHandlerFn as Ot, FastifyWithAuth as P, BodySanitizer as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, TreeExt as Qt, RegisterOptions as R, IControllerResponse as Rt, QueryParserInterface as S, beforeUpdate as Sn, PipelineContext as St, CrudRouterOptions as T, ArcCreateResult as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, AuthHelpers as Ut, ResourceDefinition as V, RouteHandler as Vt, ResourcePermissions as W, AuthPluginOptions as Wt, CrudRouteKey as X, SoftDeleteExt as Xt, PresetResult as Y, BaseController as Yt, CrudSchemas as Z, SoftDeleteMixin as Zt, ControllerQueryOptions as _, afterCreate as _n, Guard as _t, InferAdapterDoc as a, QueryResolver as an, ResourceExtensions as at, ParsedQuery as b, beforeCreate as bn, OperationFilter as bt, TypedController as c, AccessControlConfig as cn, AggMeasureShorthand as ct, PaginationResult as d, HookHandler as dn, AggregationDateRangeRequirement as dt, SlugExt as en, RouteSchemaOptions as et, IntrospectionData as f, HookOperation as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, HookSystemOptions as gn, AggregationsMap as gt, ResourceMetadata as h, HookSystem as hn, AggregationRateLimit as ht, ValidationResult as i, BaseCrudController as in, ResourceHooks as it, ArcDecorator as j, ControllerConfigurableOptions as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, ArcUpdateResult as kn, ActionsMap as kt, TypedRepository as l, DefineHookOptions as ln, AggregationCacheConfig as lt, RegistryStats as m, HookRegistration as mn, AggregationMaterializedResult as mt, ConfigError as n, BulkExt as nn, FieldRule$1 as nt, InferDocType as o, QueryResolverConfig as on, EventDefinition as ot, RegistryEntry as p, HookPhase as pn, AggregationMaterializedContext as pt, PresetFunction as q, JwtContext as qt, ValidateOptions as r, BulkMixin as rn, ResourceHookContext as rt, InferResourceDoc as s, AccessControl as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, SlugMixin as tn, ArcFieldRule as tt, TypedResourceConfig as u, HookContext as un, AggregationConfig as ut, LookupOption as v, afterDelete as vn, Interceptor as vt, ServiceContext as w, defineHook as wn, Transform as wt, PopulateOption as x, beforeDelete as xn, PipelineConfig as xt, OwnershipCheck as y, afterUpdate as yn, NextFunction as yt, ResourceRegistry as z, IRequestContext as zt };
+export { OpenApiSchemas as $, AccessControlConfig as $t, RequestIdOptions as A, WriteVerbKey as An, RouteDefinition as At, defineResource as B, BaseController as Bt, RequestContext as C, ControllerConstructionOptions as Cn, PipelineStep as Ct, HealthCheck as D, MutationWriteContext as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, BodySanitizerConfig as En, ActionDefinition as Et, FastifyWithDecorators as F, IControllerResponse as Fn, AuthPluginOptions as Ft, OnTenantDeleteConfig as G, SlugExt as Gt, CrudController as H, SoftDeleteMixin as Ht, MiddlewareHandler as I, IRequestContext as In, Authenticator as It, PresetHook as J, BulkMixin as Jt, ResolvedTenantPurge as K, SlugMixin as Kt, RequestWithExtras as L, RawRouteHandler as Ln, AuthenticatorContext as Lt, EventsDecorator as M, ControllerLike as Mn, RouteMethod as Mt, FastifyRequestExtras as N, FastifyHandler as Nn, RateLimitConfig as Nt, HealthOptions as O, ResourceWrites as On, ActionHandlerFn as Ot, FastifyWithAuth as P, IController as Pn, AuthHelpers as Pt, MiddlewareConfig as Q, AccessControl as Qt, RegisterOptions as R, RouteHandler as Rn, JwtContext as Rt, QueryParserInterface as S, ControllerConfigurableOptions as Sn, PipelineContext as St, CrudRouterOptions as T, BodySanitizer as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, TreeExt as Ut, ResourceDefinition as V, SoftDeleteExt as Vt, ResourcePermissions as W, TreeMixin as Wt, CrudRouteKey as X, QueryResolver as Xt, PresetResult as Y, BaseCrudController as Yt, CrudSchemas as Z, QueryResolverConfig as Zt, ControllerQueryOptions as _, ArcDeleteResult as _n, Guard as _t, InferAdapterDoc as a, HookRegistration as an, ResourceExtensions as at, ParsedQuery as b, ArcUpdateResult as bn, OperationFilter as bt, TypedController as c, afterCreate as cn, AggMeasureShorthand as ct, PaginationResult as d, beforeCreate as dn, AggregationDateRangeRequirement as dt, DefineHookOptions as en, RouteSchemaOptions as et, IntrospectionData as f, beforeDelete as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, ArcCreateResult as gn, AggregationsMap as gt, ResourceMetadata as h, defineHook as hn, AggregationRateLimit as ht, ValidationResult as i, HookPhase as in, ResourceHooks as it, ArcDecorator as j, ControllerHandler as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, WriteContext as kn, ActionsMap as kt, TypedRepository as l, afterDelete as ln, AggregationCacheConfig as lt, RegistryStats as m, createHookSystem as mn, AggregationMaterializedResult as mt, ConfigError as n, HookHandler as nn, FieldRule$1 as nt, InferDocType as o, HookSystem as on, EventDefinition as ot, RegistryEntry as p, beforeUpdate as pn, AggregationMaterializedContext as pt, PresetFunction as q, BulkExt as qt, ValidateOptions as r, HookOperation as rn, ResourceHookContext as rt, InferResourceDoc as s, HookSystemOptions as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, HookContext as tn, ArcFieldRule as tt, TypedResourceConfig as u, afterUpdate as un, AggregationConfig as ut, LookupOption as v, ArcGetResult as vn, Interceptor as vt, ServiceContext as w, ListResult as wn, Transform as wt, PopulateOption as x, BaseControllerOptions as xn, PipelineConfig as xt, OwnershipCheck as y, ArcListResult as yn, NextFunction as yt, ResourceRegistry as z, ServerAccessor as zn, TokenPair as zt };