@classytic/arc 2.8.4 → 2.9.1

package/dist/{interface-BVuMfeVv.d.mts → interface-YrWsmKqE.d.mts}

@@ -1,6 +1,6 @@
-import { r as RequestScope } from "./types-C72d3NDn.mjs";
-import { n as FieldPermissionMap } from "./fields-DC4So2M2.mjs";
-import { i as UserBase, t as PermissionCheck } from "./types-CVC4HOKi.mjs";
+import { r as RequestScope } from "./types-BD85MlEK.mjs";
+import { n as FieldPermissionMap } from "./fields-BC7zcmI9.mjs";
+import { i as UserBase, t as PermissionCheck } from "./types-DZi1aYhm.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 
 //#region src/hooks/HookSystem.d.ts
@@ -472,6 +472,23 @@ interface DeleteOptions extends QueryOptions {
    */
   mode?: "hard" | "soft";
 }
+/**
+ * Options for the atomic `findOneAndUpdate` compare-and-set primitive.
+ *
+ * Kit-agnostic — every backend implements the core knobs (`sort`,
+ * `returnDocument`, `upsert`, `session`). The index signature lets kits
+ * thread through backend-specific options (mongoose `arrayFilters`,
+ * `collation`, `maxTimeMS`; prisma `select`, `include`; etc.) without arc
+ * having to know about them.
+ */
+interface FindOneAndUpdateOptions extends QueryOptions {
+  /** Sort spec disambiguating when filter matches multiple docs (FIFO claim). */
+  sort?: Record<string, unknown>;
+  /** Return doc state before or after the update. Default: 'after'. */
+  returnDocument?: "before" | "after";
+  /** Insert if no doc matches. Default: false. */
+  upsert?: boolean;
+}
 /**
  * Result of a single delete operation.
  *
@@ -593,10 +610,24 @@ interface PaginationParams<TDoc = unknown> {
  *
  * `method` is optional so legacy adapters returning the bare `{ docs, page,
  * limit, total, pages, hasNext, hasPrev }` shape still satisfy the type.
+ *
+ * ## Extending with kit-specific fields
+ *
+ * Kits are free to return extra metadata (query timing, region, index hit-rate,
+ * cursor version, …). Supply them via the `TExtra` generic and they appear
+ * at the top level alongside the standard fields — no wrapper object, no
+ * narrowing gymnastics:
+ *
+ * ```ts
+ * type ProductPage = OffsetPaginatedResult<Product, { tookMs: number; region: string }>;
+ * //   ^? { method?: "offset"; docs: Product[]; page: number; ...; tookMs: number; region: string }
+ * ```
+ *
+ * Default `TExtra = {}` preserves the standard shape for every caller that
+ * doesn't care about extras.
  */
-interface OffsetPaginatedResult<TDoc> {
-  /** Discriminator — omitted or `"offset"` */
-  method?: "offset";
+type OffsetPaginatedResult<TDoc, TExtra = {}> = {
+  /** Discriminator — omitted or `"offset"` */method?: "offset";
   docs: TDoc[];
   page: number;
   limit: number;
@@ -604,20 +635,29 @@ interface OffsetPaginatedResult<TDoc> {
   pages: number;
   hasNext: boolean;
   hasPrev: boolean;
-}
+  /**
+   * Optional performance warning surfaced by the underlying kit for deep
+   * offset pagination (e.g. mongokit emits one when `page * limit` exceeds
+   * its `deepPageThreshold`). Kits that don't produce warnings leave it
+   * absent.
+   */
+  warning?: string;
+} & TExtra;
 /**
  * Keyset-based paginated result (returned when `sort` is provided without
  * `page`). Ideal for infinite scroll — no `count()` query, O(1) per page.
+ *
+ * Cursor tokens are opaque by design; kits encode their own versioning
+ * (mongokit carries a `ver` field inside the token). Surface kit-specific
+ * extras (e.g. `cursor.version`, `queryPlan`) via the `TExtra` generic.
  */
-interface KeysetPaginatedResult<TDoc> {
-  /** Discriminator — always `"keyset"` */
-  method: "keyset";
+type KeysetPaginatedResult<TDoc, TExtra = {}> = {
+  /** Discriminator — always `"keyset"` */method: "keyset";
   docs: TDoc[];
   limit: number;
-  hasMore: boolean;
-  /** Opaque cursor token for the next page, or `null` at the end */
+  hasMore: boolean; /** Opaque cursor token for the next page, or `null` at the end */
   next: string | null;
-}
+} & TExtra;
 /**
  * Discriminated union of all pagination result shapes.
  * Consumers narrow on the `method` discriminator.
@@ -632,14 +672,14 @@ interface KeysetPaginatedResult<TDoc> {
  * }
  * ```
  */
-type PaginationResult<TDoc> = OffsetPaginatedResult<TDoc> | KeysetPaginatedResult<TDoc>;
+type PaginationResult<TDoc, TExtra = {}> = OffsetPaginatedResult<TDoc, TExtra> | KeysetPaginatedResult<TDoc, TExtra>;
 /**
  * Legacy alias. Existing code typed as `PaginatedResult<TDoc>` continues
  * to work unchanged — it resolves to the offset shape, which is the most
  * common. New code should prefer `PaginationResult<TDoc>` for the full
  * discriminated union.
  */
-type PaginatedResult<TDoc> = OffsetPaginatedResult<TDoc>;
+type PaginatedResult<TDoc, TExtra = {}> = OffsetPaginatedResult<TDoc, TExtra>;
 /**
  * Standard CRUD Repository Interface
  *
@@ -691,11 +731,47 @@ interface CrudRepository<TDoc> {
   create(data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc>;
   /** Update a document by primary key. Returns the updated doc or null. */
   update(id: string, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
+  /**
+   * Atomic compare-and-set — match one document and mutate it in a single
+   * round-trip. Returns the resulting document (post-update by default), or
+   * `null` when no match and `upsert` is false.
+   *
+   * **Why this is a first-class contract method (vs an optional capability):**
+   * arc's outbox, distributed-lock, and workflow-semaphore patterns all
+   * depend on compare-and-set semantics. Without an atomic primitive they
+   * either race or require a two-phase pattern that doesn't translate
+   * cleanly to every backend. Every kit targeting arc 2.10+ should
+   * implement this.
+   *
+   * Plugins wire into `before:findOneAndUpdate` / `after:findOneAndUpdate`
+   * and read the filter from `context.query` — the canonical field name.
+   *
+   * @example FIFO claim-lease for an outbox relay
+   * ```ts
+   * const claimed = await outboxRepo.findOneAndUpdate(
+   *   { status: 'pending', visibleAt: { $lte: new Date() } },
+   *   { $set: { status: 'processing', leasedBy: workerId, leaseExpiresAt } },
+   *   { sort: { createdAt: 1 }, returnDocument: 'after' },
+   * );
+   * ```
+   */
+  findOneAndUpdate?(filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
   /**
    * Delete a document by primary key. Pass `{ mode: 'hard' }` to bypass
    * soft-delete interception.
    */
   delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
+  /**
+   * Classify an error thrown by a write as a unique-index / duplicate-key
+   * violation. Used by arc's idempotency and outbox adapters to distinguish
+   * "this write already landed" from "transient DB error".
+   *
+   * Each backend signals this differently (MongoDB `code 11000`,
+   * Prisma `P2002`, Postgres `23505`, etc.) — classification lives in the
+   * kit that knows its driver. Arc falls back to a Mongo default if absent;
+   * non-mongo kits must implement to participate in idempotency semantics.
+   */
+  isDuplicateKeyError?(err: unknown): boolean;
   /**
    * Find a single doc by a compound filter. Used by arc's AccessControl to
    * combine `idField + orgId + policy` in one query. Without it, arc falls
@@ -771,6 +847,37 @@ interface CrudRepository<TDoc> {
    * — structurally `unknown`, type-safe at the call site.
    */
   aggregatePaginate?: unknown;
+  /**
+   * Fluent aggregation pipeline builder.
+   *
+   * Same `unknown` reasoning as `aggregate` — each kit returns its own
+   * builder class (mongokit returns `AggregationBuilder`, others may
+   * return SQL builders, Prisma chains, etc.). Cast at the call site:
+   *
+   * ```ts
+   * import type { AggregationBuilder } from '@classytic/mongokit';
+   * const pipeline = (repo.buildAggregation?.() as AggregationBuilder)
+   *   .match({ status: 'active' })
+   *   .group({ _id: '$category', count: { $sum: 1 } })
+   *   .build();
+   * ```
+   */
+  buildAggregation?(): unknown;
+  /**
+   * Fluent `$lookup` stage builder. Same kit-specific reasoning as
+   * `buildAggregation` — cast at the call site.
+   *
+   * ```ts
+   * import type { LookupBuilder } from '@classytic/mongokit';
+   * const stages = (repo.buildLookup?.('departments') as LookupBuilder)
+   *   .localField('deptSlug')
+   *   .foreignField('slug')
+   *   .as('department')
+   *   .single()
+   *   .build();
+   * ```
+   */
+  buildLookup?(from?: string): unknown;
   /**
    * Run `callback` inside a transaction. Adapters should auto-retry on
    * transient transaction errors and expose a `session` the callback can
@@ -827,17 +934,7 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   readonly schemaOptions: RouteSchemaOptions;
   readonly customSchemas: CrudSchemas;
   readonly permissions: ResourcePermissions;
-  readonly additionalRoutes: AdditionalRoute[];
-  /**
-   * Original v2.8 `routes` declaration — retained for downstream consumers
-   * (OpenAPI, MCP, registry, CLI introspect). Preserves fields dropped during
-   * normalization to `additionalRoutes` (notably `mcp`, `description`,
-   * `annotations`). Undefined when the resource was defined with the legacy
-   * `additionalRoutes` shape.
-   *
-   * Added in 2.8.1 — the source-of-truth fix for "canonical resource manifest".
-   */
-  readonly routes?: readonly RouteDefinition[];
+  readonly routes: readonly RouteDefinition[];
   readonly middlewares: MiddlewareConfig;
   readonly routeGuards?: RouteHandlerMethod$1[];
   readonly disableDefaultRoutes: boolean;
@@ -1205,6 +1302,15 @@ interface ControllerLike {
 }
 //#endregion
 //#region src/core/AccessControl.d.ts
+/** Denial reason codes returned by `fetchDetailed()`. */
+type FetchDenialReason = "NOT_FOUND" | "POLICY_FILTERED" | "ORG_SCOPE_DENIED";
+/** Result of a detailed fetch with access control. */
+interface FetchResult<TDoc> {
+  /** The document, or null if denied. */
+  doc: TDoc | null;
+  /** Null when the doc was found. A string code when denied. */
+  reason: FetchDenialReason | null;
+}
 interface AccessControlConfig {
   /** Field name used for multi-tenant scoping (default: 'organizationId'). Set to `false` to disable org filtering. */
   tenantField: string | false;
@@ -1265,6 +1371,19 @@ declare class AccessControl {
    *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
    */
   fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * Same as `fetchWithAccessControl` but returns a structured result with
+   * a denial reason so callers can distinguish "doc doesn't exist" from
+   * "doc exists but was filtered by policy/org scope" from "repo threw".
+   *
+   * Codes:
+   * - `null`               — doc was found, no denial
+   * - `'NOT_FOUND'`        — doc genuinely doesn't exist in the DB
+   * - `'POLICY_FILTERED'`  — doc exists but the request's policy filters exclude it
+   * - `'ORG_SCOPE_DENIED'` — doc exists but the caller's org context doesn't match
+   * - `'REPO_ERROR'`       — the repository threw a "not found" error (mongokit style)
+   */
+  fetchDetailed<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<FetchResult<TDoc>>;
   /**
    * Post-fetch access control validation for items fetched by non-ID queries
    * (e.g., getBySlug, restore). Applies org scope, policy filters, and
@@ -1300,12 +1419,27 @@ declare class AccessControl {
 }
 //#endregion
 //#region src/core/BodySanitizer.d.ts
+/**
+ * Policy for handling fields the caller lacks write permission for.
+ *
+ * - `'reject'` (default, secure): throw 403 listing the denied fields so
+ *   misconfigurations and attacks surface instead of silently disappearing.
+ * - `'strip'` (legacy): silently drop the field and continue. Preserved for
+ *   apps that relied on the pre-2.9 behaviour — new code should not use it.
+ */
+type FieldWriteDenialPolicy = "reject" | "strip";
 interface BodySanitizerConfig {
   /** Schema options for field sanitization */
   schemaOptions: RouteSchemaOptions;
+  /**
+   * What to do when a request contains fields the caller can't write.
+   * Default: `'reject'` — surface the misconfiguration as a 403.
+   */
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
 declare class BodySanitizer {
   private schemaOptions;
+  private onFieldWriteDenied;
   constructor(config: BodySanitizerConfig);
   /**
    * Strip readonly and system-managed fields from request body.
@@ -1415,6 +1549,16 @@ interface BaseControllerOptions {
     slugField?: string;
     parentField?: string;
   };
+  /**
+   * Policy for requests that include fields the caller can't write.
+   *
+   * - `'reject'` (default): 403 with the denied field names. Surfaces
+   *   misconfigurations and attempts to set protected fields instead of
+   *   silently dropping them.
+   * - `'strip'`: legacy silent-drop behaviour. Only opt in when migrating
+   *   code that relied on the pre-2.9 permissive default.
+   */
+  onFieldWriteDenied?: FieldWriteDenialPolicy;
 }
 /**
  * Framework-agnostic base controller implementing IController.
@@ -1475,6 +1619,16 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
    * aliasing that Arc 2.6.3 introduced for repos keyed on `_id`.
    */
   private resolveRepoId;
+  /**
+   * Centralized 404 response builder. Maps the denial reason from
+   * `fetchDetailed()` into a structured `details.code` so consumers can
+   * programmatically distinguish "doc doesn't exist" from "doc filtered
+   * by policy/org scope" without parsing error strings.
+   *
+   * Error messages are intentionally vague in the `error` field (don't
+   * leak whether the doc exists) — the detail is in `details.code` only.
+   */
+  private notFoundResponse;
   /** Resolve cache config for a specific operation, merging per-op overrides */
   private resolveCacheConfig;
   /**
@@ -2027,6 +2181,16 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * ```
    */
   fields?: FieldPermissionMap;
+  /**
+   * Policy for requests that include fields the caller can't write.
+   *
+   * - `'reject'` (default, secure): 403 with the denied field names. Surfaces
+   *   misconfigurations and write-side permission violations instead of
+   *   silently dropping them.
+   * - `'strip'`: legacy silent-drop behaviour — only opt in when migrating
+   *   code that relied on the pre-2.9 permissive default.
+   */
+  onFieldWriteDenied?: 'reject' | 'strip';
   middlewares?: MiddlewareConfig;
   /**
    * PreHandler guards auto-applied to **every** route on this resource
@@ -2113,22 +2277,6 @@ interface ResourceConfig<TDoc = AnyRecord> {
   skipValidation?: boolean;
   skipRegistry?: boolean;
   _appliedPresets?: string[];
-  /**
-   * Called during plugin registration with the scoped Fastify instance.
-   * Use for wiring singletons, reading decorators, or setting up resource-specific
-   * services that need access to the Fastify instance.
-   *
-   * @example
-   * ```typescript
-   * defineResource({
-   *   name: 'notification',
-   *   onRegister: (fastify) => {
-   *     setSseManager(fastify.sseManager);
-   *   },
-   * })
-   * ```
-   */
-  onRegister?: (fastify: FastifyInstance) => void | Promise<void>;
   /** HTTP method for update routes. Default: 'PATCH' */
   updateMethod?: 'PUT' | 'PATCH' | 'both';
   /**
@@ -2231,141 +2379,6 @@ interface ResourceHooks {
   /** Runs after delete — ctx.data is the deleted doc, ctx.meta.id has the resource ID */
   afterDelete?: (ctx: ResourceHookContext) => Promise<void> | void;
 }
-/**
- * Additional route definition for custom endpoints
- */
-interface AdditionalRoute {
-  /** HTTP method */
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  /** Route path (relative to resource prefix) */
-  path: string;
-  /**
-   * Handler - string (controller method name) or function.
-   *
-   * When `wrapHandler: true`:
-   * - `string` — calls controller method by name (e.g., `'approve'`)
-   * - `ControllerHandler` — receives `IRequestContext`, returns `IControllerResponse`
-   *
-   * When `wrapHandler: false`:
-   * - Fastify handler `(request, reply) => unknown`
-   */
-  handler: string | ControllerHandler | RouteHandlerMethod | ((request: FastifyRequest<any>, reply: FastifyReply) => unknown);
-  /** Permission check - REQUIRED */
-  permissions: PermissionCheck;
-  /**
-   * Handler type - REQUIRED, no auto-detection
-   * true = ControllerHandler (receives context object)
-   * false = FastifyHandler (receives request, reply)
-   */
-  wrapHandler: boolean;
-  /**
-   * Logical operation name for pipeline keys and permission actions.
-   * Defaults to handler name (string handlers) or method+path slug.
-   * Prevents collisions when multiple routes share the same HTTP method.
-   *
-   * @example
-   * operation: 'listDeleted'  // Used as pipeline key and permission action
-   * operation: 'restore'
-   */
-  operation?: string;
-  /** OpenAPI summary */
-  summary?: string;
-  /** OpenAPI description */
-  description?: string;
-  /** OpenAPI tags */
-  tags?: string[];
-  /**
-   * Custom route-level middleware
-   * Can be an array of handlers or a function that receives fastify and returns handlers
-   * @example
-   * // Direct array
-   * preHandler: [myMiddleware]
-   * // Function that receives fastify (for accessing decorators)
-   * preHandler: (fastify) => [fastify.customerContext({ required: true })]
-   */
-  preHandler?: RouteHandlerMethod[] | ((fastify: FastifyInstance) => RouteHandlerMethod[]);
-  /**
-   * Pre-auth handlers — run BEFORE authentication middleware.
-   * Use for promoting query params to headers (e.g., EventSource ?token= → Authorization).
-   *
-   * @example
-   * ```typescript
-   * preAuth: [(req) => {
-   *   const token = (req.query as Record<string, string>)?.token;
-   *   if (token) req.headers.authorization = `Bearer ${token}`;
-   * }]
-   * ```
-   */
-  preAuth?: RouteHandlerMethod[];
-  /**
-   * Streaming response mode — designed for SSE and AI streaming routes.
-   * When `true`:
-   * - Forces `wrapHandler: false` (no `{ success, data }` wrapper)
-   * - Sets SSE headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`
-   * - `request.signal` (Fastify 5 built-in) is available for abort-on-disconnect
-   *
-   * @example
-   * ```typescript
-   * {
-   *   method: 'POST',
-   *   path: '/stream',
-   *   streamResponse: true,
-   *   permissions: requireAuth(),
-   *   handler: async (request, reply) => {
-   *     const { stream } = await generateStream({ abortSignal: request.signal });
-   *     return reply.send(stream);
-   *   },
-   * }
-   * ```
-   */
-  streamResponse?: boolean;
-  /** Fastify route schema */
-  schema?: Record<string, unknown>;
-  /**
-   * MCP handler for routes with `wrapHandler: false`.
-   * When set, this route becomes an MCP tool without needing `wrapHandler: true`.
-   * The HTTP handler stays a plain Fastify handler; MCP gets a parallel entry point.
-   *
-   * @example
-   * ```typescript
-   * additionalRoutes: [{
-   *   method: 'GET',
-   *   path: '/stats',
-   *   handler: (req, reply) => reply.send(getStats()),
-   *   wrapHandler: false,
-   *   permissions: isAuthenticated,
-   *   mcpHandler: async (input) => ({
-   *     content: [{ type: 'text', text: JSON.stringify(await getStats()) }],
-   *   }),
-   * }]
-   * ```
-   */
-  mcpHandler?: (input: Record<string, unknown>) => Promise<{
-    content: Array<{
-      type: string;
-      text: string;
-    }>;
-    isError?: boolean;
-  }>;
-  /**
-   * MCP tool generation config preserved from v2.8 `routes`.
-   * - `false`: skip MCP tool generation for this route
-   * - `true` / omitted: auto-generate when the route goes through Arc's pipeline
-   * - object: explicit description/annotations overrides
-   *
-   * Added in 2.8.1 — previously dropped during `routes → additionalRoutes`
-   * normalization, breaking MCP opt-out and per-route annotations.
-   */
-  mcp?: boolean | {
-    readonly description?: string;
-    readonly annotations?: {
-      readonly readOnlyHint?: boolean;
-      readonly destructiveHint?: boolean;
-      readonly idempotentHint?: boolean;
-      readonly openWorldHint?: boolean;
-    };
-  };
-}
 /** HTTP methods for custom routes */
 type RouteMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /** MCP tool configuration for a route or action */
@@ -2381,7 +2394,7 @@ interface RouteMcpConfig {
   };
 }
 /**
- * Route definition — replaces additionalRoutes.
+ * Route definition — the 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
@@ -2419,8 +2432,20 @@ interface RouteDefinition {
   readonly preAuth?: RouteHandlerMethod[];
   /** SSE streaming mode */
   readonly streamResponse?: boolean;
-  /** Fastify route schema */
-  readonly schema?: Record<string, unknown>;
+  /**
+   * 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` at registration time. Slot values
+   * are typed `unknown` so class-based Zod schemas assign without casts.
+   */
+  readonly schema?: {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: Record<number | string, unknown>;
+    [key: string]: unknown;
+  };
   /**
    * MCP tool generation:
    * - omitted/true: auto-generate (non-raw routes only)
@@ -2452,8 +2477,11 @@ interface ActionDefinition {
   readonly handler: ActionHandlerFn;
   /** Per-action permission check (overrides resource-level actionPermissions) */
   readonly permissions?: PermissionCheck;
-  /** JSON Schema for action-specific body fields */
-  readonly schema?: Record<string, Record<string, unknown>>;
+  /**
+   * JSON Schema or Zod v4 schema for action-specific body fields.
+   * Per-field values are typed `unknown` so Zod class instances assign without casts.
+   */
+  readonly schema?: Record<string, unknown>;
   /** Description for OpenAPI docs and MCP tool */
   readonly description?: string;
   /**
@@ -2506,47 +2534,54 @@ interface FieldRule {
 /**
  * CRUD Route Schemas (Fastify Native Format)
  *
+ * Each slot accepts either a plain JSON Schema object **or** a Zod v4 schema —
+ * arc's `convertRouteSchema` feature-detects at runtime. The slot values are
+ * typed `unknown` (not `Record<string, unknown>`) so class-based Zod schemas
+ * assign cleanly without `as unknown as Record<string, unknown>` casts.
+ *
  * @example
+ * ```ts
  * {
  *   list: {
  *     querystring: { type: 'object', properties: { page: { type: 'number' } } },
- *     response: { 200: { type: 'object', properties: { docs: { type: 'array' } } } }
+ *     response: { 200: z.object({ docs: z.array(EntitySchema) }) }
  *   },
  *   create: {
- *     body: { type: 'object', properties: { name: { type: 'string' } } },
- *     response: { 201: { type: 'object' } }
+ *     body: z.object({ name: z.string(), size: z.number().int().positive() }),
+ *     response: { 201: EntitySchema }
  *   }
  * }
+ * ```
  */
 interface CrudSchemas {
   /** GET / - List all resources */
   list?: {
-    querystring?: Record<string, unknown>;
+    /** Plain JSON Schema or Zod schema (auto-converted). */querystring?: unknown; /** Map of HTTP status code → JSON Schema or Zod schema. */
     response?: Record<number, unknown>;
     [key: string]: unknown;
   };
   /** GET /:id - Get single resource */
   get?: {
-    params?: Record<string, unknown>;
+    params?: unknown;
     response?: Record<number, unknown>;
     [key: string]: unknown;
   };
   /** POST / - Create resource */
   create?: {
-    body?: Record<string, unknown>;
+    body?: unknown;
     response?: Record<number, unknown>;
     [key: string]: unknown;
   };
   /** PATCH /:id - Update resource */
   update?: {
-    params?: Record<string, unknown>;
-    body?: Record<string, unknown>;
+    params?: unknown;
+    body?: unknown;
     response?: Record<number, unknown>;
     [key: string]: unknown;
   };
   /** DELETE /:id - Delete resource */
   delete?: {
-    params?: Record<string, unknown>;
+    params?: unknown;
     response?: Record<number, unknown>;
     [key: string]: unknown;
   };
@@ -2869,6 +2904,23 @@ interface AuthPluginOptions {
    * ```
    */
   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, legacy tokens from a third-party
+   * issuer).
+   *
+   * Arc's own token issuance (`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;
 }
 interface IntrospectionPluginOptions {
   path?: string;
@@ -2887,8 +2939,8 @@ interface CrudRouterOptions {
   schemas?: Partial<CrudSchemas>;
   /** Middlewares for each CRUD operation */
   middlewares?: MiddlewareConfig;
-  /** Additional custom routes (from presets or user-defined) */
-  additionalRoutes?: AdditionalRoute[];
+  /** Custom routes (from presets or user-defined) */
+  routes?: readonly RouteDefinition[];
   /** Disable all default CRUD routes */
   disableDefaultRoutes?: boolean;
   /** Disable specific CRUD routes */
@@ -3073,6 +3125,29 @@ type TypedRepository<TDoc> = CrudRepository<TDoc>;
  *
  * See [CrudRepository](../types/repository.ts) for full prose-level docs
  * on each method and the design rationale behind the tiering.
+ *
+ * ## Store-backing contract (audit / outbox / idempotency)
+ *
+ * Arc's pluggable stores (audit log, event outbox, HTTP idempotency) all
+ * consume a `RepositoryLike` directly — no wrapper classes, no adapters to
+ * register. If you want to back one of these subsystems with any database,
+ * pass a repository satisfying the method subset below. `mongokit ≥3.8`
+ * implements every method; other kits must match the relevant subset.
+ *
+ * | Subsystem          | Required methods                                        |
+ * |--------------------|---------------------------------------------------------|
+ * | `auditPlugin`      | `create`, `findAll`                                     |
+ * | `idempotencyPlugin`| `getOne`, `deleteMany`, `findOneAndUpdate`              |
+ * | `EventOutbox`      | `create`, `getOne`, `findAll`, `deleteMany`, `findOneAndUpdate` |
+ *
+ * The outbox is the strictest — its atomic FIFO claim-lease loop depends
+ * on `findOneAndUpdate` returning the post-update doc. Kits without atomic
+ * CAS cannot back the outbox; use an in-memory / transport-native store
+ * (`MemoryOutboxStore`, Redis Streams, etc.) instead.
+ *
+ * Every store adapter throws at construction with the list of missing
+ * methods if the repository doesn't satisfy its subset, so misconfigurations
+ * fail fast rather than at first request.
  */
 interface RepositoryLike {
   /**
@@ -3093,12 +3168,50 @@ interface RepositoryLike {
   getById(id: string, options?: QueryOptions): Promise<unknown>;
   create(data: unknown, options?: WriteOptions): Promise<unknown>;
   update(id: string, data: unknown, options?: WriteOptions): Promise<unknown>;
+  /**
+   * Atomic compare-and-set — match one document and mutate it in a single
+   * round-trip. Returns the post-update document (or pre-update when
+   * `returnDocument: 'before'`), or `null` when no document matches and
+   * `upsert` is false.
+   *
+   * Used by the transactional outbox, distributed locks, and workflow
+   * semaphores. Kits without atomic CAS can omit this method — arc stores
+   * that require it throw a clear capability error at construction.
+   *
+   * Options follow mongokit's {@link https://github.com/classytic/mongokit | FindOneAndUpdateOptions}
+   * shape: `{ sort, returnDocument, upsert, session, ... }`. Plugins reading
+   * the hook context find the filter under `context.query` (the canonical
+   * field name across every method on this contract).
+   */
+  findOneAndUpdate?(filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: {
+    sort?: Record<string, unknown>;
+    returnDocument?: "before" | "after";
+    upsert?: boolean;
+    session?: RepositorySession;
+    [key: string]: unknown;
+  }): Promise<unknown>;
   /**
    * Delete by primary key. Pass `{ mode: 'hard' }` to bypass soft-delete
    * interception (required by arc's hard-delete flow — `?hard=true` on
    * the DELETE route forwards this option).
    */
   delete(id: string, options?: DeleteOptions): Promise<unknown>;
+  /**
+   * Classify an error thrown by `create` / `findOneAndUpdate` / `update` as
+   * a unique-index / duplicate-key violation.
+   *
+   * Arc's idempotency and outbox adapters need to distinguish "this write
+   * already landed (idempotent no-op)" from "transient DB error (retry)".
+   * Since every backend signals dup-key differently — MongoDB `code 11000`,
+   * Prisma `P2002`, Postgres `23505`, SQLite `UNIQUE constraint failed` —
+   * we put the classification back in the kit that knows its driver.
+   *
+   * If a kit omits this predicate, arc falls back to a conservative MongoDB
+   * check (`code === 11000 || codeName === "DuplicateKey"`), so mongokit
+   * ≤3.8 keeps working without changes. Non-mongo kits MUST implement it to
+   * participate in idempotency semantics.
+   */
+  isDuplicateKeyError?(err: unknown): boolean;
   /**
    * Find a single doc by compound filter. Used by AccessControl for
    * `idField + org + policy` scoping. Without this, arc falls back to
@@ -3123,10 +3236,27 @@ interface RepositoryLike {
   getDeleted?(params?: PaginationParams, options?: QueryOptions): Promise<PaginationResult<unknown> | unknown[]>;
   aggregate?: unknown;
   aggregatePaginate?: unknown;
+  /**
+   * Fluent aggregation builder. Mongokit returns `AggregationBuilder`;
+   * other kits may return their own builder class. Cast at the call site
+   * — arc never calls this internally. See [CrudRepository.buildAggregation](../types/repository.ts).
+   */
+  buildAggregation?(): unknown;
+  /**
+   * Fluent `$lookup` stage builder. Mongokit returns `LookupBuilder`;
+   * other kits may return nothing. Cast at the call site.
+   */
+  buildLookup?(from?: string): unknown;
   withTransaction?<T>(callback: (session: RepositorySession) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
   getBySlug?(slug: string, options?: QueryOptions): Promise<unknown>;
   getTree?(options?: QueryOptions): Promise<unknown>;
   getChildren?(parentId: string, options?: QueryOptions): Promise<unknown>;
+  /** Full-text / engine-backed search. Present when e.g. mongokit's `elasticSearchPlugin` is registered. */
+  search?(query: unknown, options?: unknown): Promise<unknown>;
+  /** Semantic / vector similarity search. Present when e.g. mongokit's `vectorPlugin` is registered. */
+  searchSimilar?(query: unknown, options?: unknown): Promise<unknown>;
+  /** Embed a text/media input into its vector representation. */
+  embed?(input: unknown): Promise<number[]>;
   [key: string]: unknown;
 }
 interface DataAdapter<TDoc = unknown> {
@@ -3224,4 +3354,4 @@ interface ValidationResult {
 }
 type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
 //#endregion
-export { PresetFunction as $, DeleteOptions as $t, EventsDecorator as A, beforeCreate as An, BaseController as At, InferResourceDoc as B, FastifyHandler as Bt, ConfigError as C, HookPhase as Cn, TypedResourceConfig as Ct, CrudRouterOptions as D, afterCreate as Dn, ValidationResult$1 as Dt, CrudRouteKey as E, HookSystemOptions as En, ValidateOptions as Et, GracefulShutdownOptions as F, BodySanitizerConfig as Ft, LookupOption as G, RegisterOptions as Gt, IntrospectionPluginOptions as H, IControllerResponse as Ht, HealthCheck as I, AccessControl as It, ObjectId as J, defineResource as Jt, MiddlewareConfig as K, ResourceRegistry as Kt, HealthOptions as L, AccessControlConfig as Lt, FastifyWithAuth as M, beforeUpdate as Mn, QueryResolver as Mt, FastifyWithDecorators as N, createHookSystem as Nn, QueryResolverConfig as Nt, CrudSchemas as O, afterDelete as On, envelope as Ot, FieldRule as P, defineHook as Pn, BodySanitizer as Pt, PopulateOption as Q, DeleteManyResult as Qt, InferAdapterDoc as R, ControllerHandler as Rt, AuthenticatorContext as S, HookOperation as Sn, TypedRepository as St, CrudController as T, HookSystem as Tn, UserOrganization as Tt, JWTPayload as U, IRequestContext as Ut, IntrospectionData as V, IController as Vt, JwtContext as W, RouteHandler as Wt, OwnershipCheck as X, BulkWriteResult as Xt, OpenApiSchemas as Y, BulkWriteOperation as Yt, ParsedQuery as Z, CrudRepository as Zt, ArcInternalMetadata as _, PipelineStep as _n, RouteMcpConfig as _t, RelationMetadata as a, PaginationParams as an, RegistryStats as at, AuthPluginOptions as b, HookContext as bn, TokenPair as bt, ValidationResult as c, RepositorySession as cn, RequestWithExtras as ct, ActionHandlerFn as d, Guard as dn, ResourceHookContext as dt, DeleteResult as en, PresetHook as et, ActionsMap as f, Interceptor as fn, ResourceHooks as ft, ArcDecorator as g, PipelineContext as gn, RouteHandlerMethod$1 as gt, ApiResponse as h, PipelineConfig as hn, RouteDefinition as ht, FieldMetadata as i, PaginatedResult as in, RegistryEntry as it, FastifyRequestExtras as j, beforeDelete as jn, BaseControllerOptions as jt, EventDefinition as k, afterUpdate as kn, getUserId as kt, ActionDefinition as l, UpdateManyResult as ln, ResourceCacheConfig as lt, AnyRecord as m, OperationFilter as mn, ResourcePermissions as mt, AdapterSchemaContext as n, KeysetPaginatedResult as nn, QueryParserInterface as nt, RepositoryLike as o, PaginationResult as on, RequestContext as ot, AdditionalRoute as p, NextFunction as pn, ResourceMetadata as pt, MiddlewareHandler as q, ResourceDefinition as qt, DataAdapter as r, OffsetPaginatedResult as rn, RateLimitConfig as rt, SchemaMetadata as s, QueryOptions as sn, RequestIdOptions as st, AdapterFactory as t, InferDoc as tn, PresetResult as tt, ActionEntry as u, WriteOptions as un, ResourceConfig as ut, ArcRequest as v, Transform as vn, RouteSchemaOptions as vt, ControllerQueryOptions as w, HookRegistration as wn, UserLike as wt, Authenticator as x, HookHandler as xn, TypedController as xt, AuthHelpers as y, DefineHookOptions as yn, ServiceContext as yt, InferDocType as z, ControllerLike as zt };
+export { PresetHook as $, DeleteResult as $t, FastifyRequestExtras as A, beforeCreate as An, BaseControllerOptions as At, IntrospectionData as B, IController as Bt, ControllerQueryOptions as C, HookPhase as Cn, UserLike as Ct, CrudSchemas as D, afterCreate as Dn, envelope as Dt, CrudRouterOptions as E, HookSystemOptions as En, ValidationResult$1 as Et, HealthCheck as F, AccessControl as Ft, MiddlewareConfig as G, ResourceRegistry as Gt, JWTPayload as H, IRequestContext as Ht, HealthOptions as I, AccessControlConfig as It, OpenApiSchemas as J, BulkWriteOperation as Jt, MiddlewareHandler as K, ResourceDefinition as Kt, InferAdapterDoc as L, ControllerHandler as Lt, FastifyWithDecorators as M, beforeUpdate as Mn, QueryResolverConfig as Mt, FieldRule as N, createHookSystem as Nn, BodySanitizer as Nt, EventDefinition as O, afterDelete as On, getUserId as Ot, GracefulShutdownOptions as P, defineHook as Pn, BodySanitizerConfig as Pt, PresetFunction as Q, DeleteOptions as Qt, InferDocType as R, ControllerLike as Rt, ConfigError as S, HookOperation as Sn, TypedResourceConfig as St, CrudRouteKey as T, HookSystem as Tn, ValidateOptions as Tt, JwtContext as U, RouteHandler as Ut, IntrospectionPluginOptions as V, IControllerResponse as Vt, LookupOption as W, RegisterOptions as Wt, ParsedQuery as X, CrudRepository as Xt, OwnershipCheck as Y, BulkWriteResult as Yt, PopulateOption as Z, DeleteManyResult as Zt, ArcRequest as _, PipelineStep as _n, RouteSchemaOptions as _t, RelationMetadata as a, PaginationParams as an, RequestContext as at, Authenticator as b, HookContext as bn, TypedController as bt, ValidationResult as c, RepositorySession as cn, ResourceCacheConfig as ct, ActionHandlerFn as d, Guard as dn, ResourceHooks as dt, FindOneAndUpdateOptions as en, PresetResult as et, ActionsMap as f, Interceptor as fn, ResourceMetadata as ft, ArcInternalMetadata as g, PipelineContext as gn, RouteMcpConfig as gt, ArcDecorator as h, PipelineConfig as hn, RouteHandlerMethod$1 as ht, FieldMetadata as i, PaginatedResult as in, RegistryStats as it, FastifyWithAuth as j, beforeDelete as jn, QueryResolver as jt, EventsDecorator as k, afterUpdate as kn, BaseController as kt, ActionDefinition as l, UpdateManyResult as ln, ResourceConfig as lt, ApiResponse as m, OperationFilter as mn, RouteDefinition as mt, AdapterSchemaContext as n, KeysetPaginatedResult as nn, RateLimitConfig as nt, RepositoryLike as o, PaginationResult as on, RequestIdOptions as ot, AnyRecord as p, NextFunction as pn, ResourcePermissions as pt, ObjectId as q, defineResource as qt, DataAdapter as r, OffsetPaginatedResult as rn, RegistryEntry as rt, SchemaMetadata as s, QueryOptions as sn, RequestWithExtras as st, AdapterFactory as t, InferDoc as tn, QueryParserInterface as tt, ActionEntry as u, WriteOptions as un, ResourceHookContext as ut, AuthHelpers as v, Transform as vn, ServiceContext as vt, CrudController as w, HookRegistration as wn, UserOrganization as wt, AuthenticatorContext as x, HookHandler as xn, TypedRepository as xt, AuthPluginOptions as y, DefineHookOptions as yn, TokenPair as yt, InferResourceDoc as z, FastifyHandler as zt };