@classytic/arc 2.8.0 → 2.8.1

package/dist/{interface-IJqN3pXK.d.mts → interface-CS6d7HiB.d.mts}

@@ -5,7 +5,7 @@ import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, Rout
 
 //#region src/hooks/HookSystem.d.ts
 type HookPhase = "before" | "around" | "after";
-type HookOperation = "create" | "update" | "delete" | "read" | "list";
+type HookOperation = "create" | "update" | "delete" | "restore" | "read" | "list";
 interface HookContext<T = AnyRecord> {
   resource: string;
   operation: HookOperation;
@@ -318,116 +318,479 @@ type PipelineConfig = PipelineStep[] | {
 //#endregion
 //#region src/types/repository.d.ts
 /**
- * Repository Interface - Database-Agnostic CRUD Operations
+ * Repository Interface — Database-Agnostic CRUD Contract
  *
- * This is the standard interface that all repositories must implement.
- * MongoKit Repository already implements this interface.
+ * This is the canonical contract every arc-compatible repository follows.
+ * It is intentionally structural: any object matching the shape works,
+ * including the reference implementation at `@classytic/mongokit` and any
+ * future `prismakit` / `pgkit` / `sqlitekit` that mirrors it.
  *
- * @example
- * ```typescript
- * import type { CrudRepository } from '@classytic/arc';
+ * ## Design
+ *
+ * The interface is tiered so a minimal adapter can ship with five methods
+ * while a mature one (mongokit 3.6+) can opt into the full surface without
+ * type assertions:
+ *
+ * 1. **Required** — `getAll`, `getById`, `create`, `update`, `delete`.
+ *    Every resource needs these; arc's BaseController assumes they exist.
+ *
+ * 2. **Recommended** — `getOne` / `getByQuery`. Used by AccessControl to
+ *    enforce compound filters (idField + org scope + policy). Without them,
+ *    arc falls back to `getById` + post-fetch checks, which is slower and
+ *    produces wrong 404s on custom idFields.
+ *
+ * 3. **Optional capabilities** — batch ops, soft delete, aggregation,
+ *    transactions, etc. Declared as optional so kits implement only what
+ *    their underlying DB supports. arc feature-detects at runtime.
+ *
+ * All options/results are named types so custom kits can import and
+ * implement them directly:
  *
- * // Your repository automatically satisfies this interface
+ * ```ts
+ * import type {
+ *   CrudRepository,
+ *   DeleteOptions,
+ *   DeleteResult,
+ *   PaginationResult,
+ *   UpdateManyResult,
+ *   BulkWriteOperation,
+ *   BulkWriteResult,
+ * } from '@classytic/arc';
+ *
+ * class PgRepository<TDoc> implements CrudRepository<TDoc> { … }
+ * ```
+ *
+ * @example Reference implementation
+ * ```ts
+ * import type { CrudRepository } from '@classytic/arc';
  * const userRepo: CrudRepository<UserDocument> = new Repository(UserModel);
  * ```
+ *
+ * ## Contract gotchas (learned from mongokit 3.6 integration)
+ *
+ * If you build a custom kit that implements this contract, these are the
+ * behaviors arc's tests specifically verify. Align your kit here and
+ * arc's `BaseController` + presets will work out of the box:
+ *
+ * 1. **`getById` / `getOne` miss semantics** — MAY return `null` or throw a
+ *    404-style error whose message contains "not found". Arc handles both.
+ *    Pick one and document it in your kit.
+ *
+ * 2. **`deleteMany` with soft-delete** — if your kit intercepts
+ *    `deleteMany` and rewrites it to `updateMany`, the returned
+ *    `deletedCount` may be `0` even when N docs were soft-deleted. The
+ *    authoritative count comes from a follow-up query. Consumers shouldn't
+ *    rely on `deletedCount` reflecting soft-delete work unless your kit
+ *    promises it.
+ *
+ * 3. **Lifecycle hooks are shared with plugins** — never use
+ *    `removeAllListeners(event)` to clean up test hooks. That silently
+ *    removes soft-delete, cascade, multi-tenant, and audit plugin
+ *    listeners too, which then makes subsequent operations misbehave
+ *    (e.g. a soft-delete becomes a hard delete). Always use
+ *    `.off(event, fn)` with the specific handler reference you registered.
+ *
+ * 4. **Hard-delete mode** — `delete(id, { mode: 'hard' })` and
+ *    `deleteMany(q, { mode: 'hard' })` MUST bypass soft-delete
+ *    interception while still running policy / multi-tenant / cascade /
+ *    audit hooks. Kits without soft-delete should accept and ignore the
+ *    flag.
+ *
+ * 5. **Keyset pagination auto-detection** — `getAll({ sort, limit })`
+ *    without `page` SHOULD return a `KeysetPaginatedResult` with
+ *    `method: "keyset"`. Kits that only offer offset pagination can return
+ *    the legacy offset shape; arc's types still satisfy.
+ *
+ * 6. **`idField` identity** — kits that key on anything other than `"_id"`
+ *    MUST set `readonly idField` on the repository so arc's BaseController
+ *    passes route params straight through to `update`/`delete`/`restore`
+ *    without translating them.
+ *
+ * 7. **`before:restore` / `after:restore` hooks** — if you implement
+ *    `restore`, fire these hooks symmetrically with `before:delete` /
+ *    `after:delete` so hosts can wire cascade-restore flows.
+ *
+ * See `tests/core/repository-contract-mongokit.test.ts` for a runnable
+ * reference against mongokit 3.6. Copy it, swap in your kit's repository,
+ * and make it pass — if everything's green, arc will work against your
+ * kit.
  */
 /**
- * Query options for read operations
+ * Opaque transaction session. Adapters bind this to their own type
+ * (Mongoose `ClientSession`, Prisma transaction client, `pg.Client`, …).
+ */
+type RepositorySession = unknown;
+/**
+ * Query options for read operations. Extended ad-hoc by adapters via the
+ * index signature — kit authors should namespace custom flags (e.g.
+ * `__pgHint`) to avoid collisions.
  */
 interface QueryOptions {
-  /** Transaction session — adapters handle the actual type (e.g., Mongoose ClientSession) */
-  session?: unknown;
-  /** Field selection - include or exclude fields */
-  select?: string | string[] | Record<string, 0 | 1>;
-  /** Relations to populate - string, array, or Mongoose populate options */
-  populate?: string | string[] | Record<string, unknown>;
-  /** Return plain JS objects instead of Mongoose documents */
+  /** Transaction session — adapter-specific concrete type */
+  session?: RepositorySession;
+  /** Return plain objects instead of driver documents */
   lean?: boolean;
-  /** Allow additional adapter-specific options */
+  /** Include soft-deleted docs in reads (honored by soft-delete plugin) */
+  includeDeleted?: boolean;
+  /** Forwarded to policy/tenant hooks */
+  user?: Record<string, unknown>;
+  /** Arc request-scoped metadata (orgId, roles, requestId, …) */
+  context?: Record<string, unknown>;
+  /**
+   * Adapter-specific escape hatch — `select`, `populate`, `populateOptions`,
+   * `readPreference`, `maxTimeMS`, and every kit's driver-specific flags
+   * flow through here. Arc intentionally does NOT type these concretely
+   * because each kit's DB shapes them differently: mongoose uses
+   * `PopulateOptions[]`, prisma uses `{ include: {...} }`, pgkit uses SQL
+   * JOIN hints, etc. Typing them as (say) `string | Record<string, unknown>`
+   * would REJECT the narrower shapes real kits actually expose, breaking
+   * structural assignability of `Repository<T> → CrudRepository<T>`.
+   */
   [key: string]: unknown;
 }
 /**
- * Pagination parameters for list operations
+ * Options for write operations (create/update). Superset of QueryOptions
+ * so callers can pass a single options object.
+ */
+interface WriteOptions extends QueryOptions {
+  /** Upsert on update/replace operations */
+  upsert?: boolean;
+}
+/**
+ * Options for delete operations.
+ *
+ * `mode: 'hard'` opts out of the soft-delete interception when the adapter
+ * has a soft-delete plugin wired. Policy, cascade, audit, and cache hooks
+ * still fire — only the soft-delete rewrite is bypassed. Use for GDPR
+ * erasure or admin purge paths.
+ */
+interface DeleteOptions extends QueryOptions {
+  /**
+   * Force physical deletion even when soft-delete is active, or force soft
+   * when the default would be hard. Adapters without soft-delete support
+   * MUST ignore this flag (it is a hint, not a contract).
+   */
+  mode?: "hard" | "soft";
+}
+/**
+ * Result of a single delete operation.
+ *
+ * Matches mongokit's shape. Adapters without soft-delete awareness can omit
+ * `soft` and `count`. Arc's BaseController uses the `success` flag to decide
+ * whether to return 200 or 404.
+ */
+interface DeleteResult {
+  success: boolean;
+  message: string;
+  /** Primary key of the removed doc (string form) */
+  id?: string;
+  /** True when a soft-delete plugin intercepted the operation */
+  soft?: boolean;
+  /** For batch-variant implementations that return the delete count inline */
+  count?: number;
+}
+/**
+ * Result of a batch delete (`deleteMany`) — distinct from single `delete`
+ * because MongoDB's driver returns a different shape for batch operations.
+ *
+ * **Soft-delete gotcha** — when a soft-delete plugin intercepts
+ * `deleteMany` by rewriting it to `updateMany` internally (mongokit 3.6
+ * does this in `before:deleteMany`), the `deletedCount` returned here may
+ * be `0` because the underlying `Model.deleteMany` was never called. The
+ * affected-row count lives inside the hook's `updateMany` result and is
+ * not surfaced to the caller. Consumers that need the exact soft-deleted
+ * count should run a follow-up query (`repo.count({ deletedAt: { $ne:
+ * null }, ...filter })`). 3rd-party kits with soft-delete should document
+ * which convention they follow.
+ */
+interface DeleteManyResult {
+  /** Driver-reported acknowledgement */
+  acknowledged?: boolean;
+  /**
+   * Number of documents removed. May be 0 when soft-delete intercepts;
+   * see the "Soft-delete gotcha" note above.
+   */
+  deletedCount: number;
+  /** True when a soft-delete plugin intercepted and did `updateMany` instead */
+  soft?: boolean;
+}
+/** Result of a bulk update operation. Matches MongoDB driver shape. */
+interface UpdateManyResult {
+  acknowledged?: boolean;
+  matchedCount: number;
+  modifiedCount: number;
+  upsertedCount?: number;
+  upsertedId?: unknown;
+}
+/** Shape of a single operation passed to `bulkWrite`. */
+type BulkWriteOperation<TDoc = unknown> = {
+  insertOne: {
+    document: Partial<TDoc>;
+  };
+} | {
+  updateOne: {
+    filter: Record<string, unknown>;
+    update: Record<string, unknown>;
+    upsert?: boolean;
+  };
+} | {
+  updateMany: {
+    filter: Record<string, unknown>;
+    update: Record<string, unknown>;
+    upsert?: boolean;
+  };
+} | {
+  deleteOne: {
+    filter: Record<string, unknown>;
+  };
+} | {
+  deleteMany: {
+    filter: Record<string, unknown>;
+  };
+} | {
+  replaceOne: {
+    filter: Record<string, unknown>;
+    replacement: Partial<TDoc>;
+    upsert?: boolean;
+  };
+};
+/** Result of a heterogeneous bulk write. */
+interface BulkWriteResult {
+  ok?: number;
+  insertedCount?: number;
+  matchedCount?: number;
+  modifiedCount?: number;
+  deletedCount?: number;
+  upsertedCount?: number;
+  insertedIds?: Record<number, unknown>;
+  upsertedIds?: Record<number, unknown>;
+}
+/**
+ * Pagination parameters for list operations.
+ *
+ * Supports three modes, auto-detected by the adapter:
+ * - **Offset** — pass `page` + `limit`.
+ * - **Keyset** — pass `sort` + `limit` (+ optional `after` cursor). Required
+ *   for infinite scroll on large collections; O(1) per page.
+ * - **Raw** — pass neither; adapter returns all matching docs.
  */
 interface PaginationParams<TDoc = unknown> {
   /** Filter criteria */
   filters?: Partial<TDoc> & Record<string, unknown>;
-  /** Sort specification - string ("-createdAt") or object ({ createdAt: -1 }) */
+  /** Sort spec — string (`"-createdAt"`) or object (`{ createdAt: -1 }`) */
   sort?: string | Record<string, 1 | -1>;
-  /** Page number (1-indexed) */
+  /** Page number (1-indexed) — triggers offset pagination */
   page?: number;
   /** Items per page */
   limit?: number;
-  /** Allow additional options (select, populate, etc.) */
+  /** Opaque cursor from a prior `next` field — triggers keyset pagination */
+  after?: string;
+  /** Allow additional options (select, populate, search, …) */
   [key: string]: unknown;
 }
 /**
- * Paginated result from list operations
+ * Offset-based paginated result (the default shape when `page` is provided).
+ *
+ * `method` is optional so legacy adapters returning the bare `{ docs, page,
+ * limit, total, pages, hasNext, hasPrev }` shape still satisfy the type.
  */
-interface PaginatedResult<TDoc> {
-  /** Documents for current page */
+interface OffsetPaginatedResult<TDoc> {
+  /** Discriminator — omitted or `"offset"` */
+  method?: "offset";
   docs: TDoc[];
-  /** Current page number */
   page: number;
-  /** Items per page */
   limit: number;
-  /** Total document count */
   total: number;
-  /** Total page count */
   pages: number;
-  /** Has next page */
   hasNext: boolean;
-  /** Has previous page */
   hasPrev: boolean;
 }
+/**
+ * Keyset-based paginated result (returned when `sort` is provided without
+ * `page`). Ideal for infinite scroll — no `count()` query, O(1) per page.
+ */
+interface KeysetPaginatedResult<TDoc> {
+  /** Discriminator — always `"keyset"` */
+  method: "keyset";
+  docs: TDoc[];
+  limit: number;
+  hasMore: boolean;
+  /** Opaque cursor token for the next page, or `null` at the end */
+  next: string | null;
+}
+/**
+ * Discriminated union of all pagination result shapes.
+ * Consumers narrow on the `method` discriminator.
+ *
+ * @example
+ * ```ts
+ * const result = await repo.getAll(params);
+ * if (result.method === "keyset") {
+ *   // result.next, result.hasMore
+ * } else {
+ *   // result.page, result.total, result.pages
+ * }
+ * ```
+ */
+type PaginationResult<TDoc> = OffsetPaginatedResult<TDoc> | KeysetPaginatedResult<TDoc>;
+/**
+ * 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>;
 /**
  * Standard CRUD Repository Interface
  *
- * Defines the contract for data access operations.
- * All database adapters (MongoKit, Prisma, etc.) implement this interface.
+ * The canonical contract arc consumes. Tiered so minimal adapters only
+ * implement the required five methods; richer kits declare the optional
+ * capabilities they support.
+ *
+ * Every optional method is feature-detected at runtime by arc's
+ * BaseController and presets — implement only what your DB can express.
  *
  * @typeParam TDoc - The document/entity type
  */
 interface CrudRepository<TDoc> {
   /**
-   * Get paginated list of documents
+   * Native primary key field. Defaults to `"_id"` (Mongo convention).
+   *
+   * Set to match `defineResource({ idField })` for kits that key on a
+   * custom field (e.g. `"id"`, `"uuid"`, `"slug"`). Arc's BaseController
+   * reads this to decide whether to pass route params straight through
+   * to `update`/`delete`/`restore` or to translate them via a fetched
+   * doc's `_id` first.
    */
-  getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginatedResult<TDoc>>;
+  readonly idField?: string;
   /**
-   * Get single document by ID
+   * List documents with pagination. Adapter auto-selects offset vs keyset
+   * mode based on the presence of `page` or `after` in `params`.
+   *
+   * Return shapes (all valid under the contract):
+   * - `OffsetPaginatedResult<TDoc>` — when `page` is given
+   * - `KeysetPaginatedResult<TDoc>` — when `sort` + optional `after` are given
+   * - `TDoc[]` — raw array, when neither `page` nor `sort` drives pagination
+   *
+   * Arc's BaseController narrows the union before returning to clients.
+   */
+  getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginationResult<TDoc> | TDoc[]>;
+  /**
+   * Fetch a single document by its primary key.
+   *
+   * **Miss semantics — kits may EITHER return `null` OR throw a 404-style
+   * error.** Arc's `BaseController` handles both: `AccessControl.fetchWith­
+   * AccessControl` catches errors whose message contains "not found" and
+   * converts them to null. 3rd-party kit authors: pick one convention and
+   * document it. mongokit 3.6 throws by default; pass
+   * `{ throwOnNotFound: false }` to get null. A SQL kit that returns null
+   * directly is equally valid.
    */
   getById(id: string, options?: QueryOptions): Promise<TDoc | null>;
+  /** Insert a single document. */
+  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>;
   /**
-   * Create new document
+   * Delete a document by primary key. Pass `{ mode: 'hard' }` to bypass
+   * soft-delete interception.
    */
-  create(data: Partial<TDoc>, options?: {
-    session?: unknown;
-    [key: string]: unknown;
-  }): Promise<TDoc>;
+  delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
   /**
-   * Update document by ID
+   * 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
+   * back to `getById` + post-fetch scope checks (slower; 404s on custom
+   * idFields if the doc lives outside the user's scope).
+   *
+   * Miss semantics match `getById` — kits may return null or throw. Arc
+   * handles both. See the note on `getById` above.
    */
-  update(id: string, data: Partial<TDoc>, options?: QueryOptions): Promise<TDoc | null>;
+  getOne?(filter: Record<string, unknown>, options?: QueryOptions): Promise<TDoc | null>;
+  /** Alias many kits expose alongside `getOne`. Arc checks both. */
+  getByQuery?(filter: Record<string, unknown>, options?: QueryOptions): Promise<TDoc | null>;
+  /** Count matching documents. Respects soft-delete when applicable. */
+  count?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<number>;
   /**
-   * Delete document by ID
+   * Cheap existence check. Kits may return `boolean` or `{ _id }` — arc
+   * coerces to boolean at the call site.
    */
-  delete(id: string, options?: {
-    session?: unknown;
-    [key: string]: unknown;
-  }): Promise<{
-    success: boolean;
-    message: string;
-  }>;
-  /** Allow custom methods (getBySlug, getTree, restore, etc.) */
+  exists?(filter: Record<string, unknown>, options?: QueryOptions): Promise<boolean | {
+    _id: unknown;
+  } | null>;
+  /** Return the distinct values of a field matching the filter. */
+  distinct?<T = unknown>(field: string, filter?: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
+  /** Return all matching docs as a raw array (no pagination metadata). */
+  findAll?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<TDoc[]>;
+  /**
+   * Atomic "find or create" — return the doc matching the filter, or
+   * insert `data` and return it if none exists. MAY return `null` when
+   * neither path produces a document (e.g. race loss + validation error
+   * handling — mongokit returns null in this window).
+   */
+  getOrCreate?(filter: Record<string, unknown>, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
+  /** Insert multiple documents in one call. */
+  createMany?(items: Array<Partial<TDoc>>, options?: WriteOptions): Promise<TDoc[]>;
+  /**
+   * Update all documents matching `filter`. Should reject empty filters
+   * to prevent accidental mass updates (mongokit does this).
+   */
+  updateMany?(filter: Record<string, unknown>, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
+  /**
+   * Delete all documents matching `filter`. Soft-deletes when a soft-delete
+   * plugin is wired; pass `{ mode: 'hard' }` to force physical removal.
+   */
+  deleteMany?(filter: Record<string, unknown>, options?: DeleteOptions): Promise<DeleteManyResult>;
+  /**
+   * Heterogeneous bulk write (insertOne / updateOne / deleteMany / …).
+   *
+   * Structurally typed as `unknown` because each kit uses its own operation
+   * shape — mongoose uses `AnyBulkWriteOperation[]`, prisma builds these
+   * from its client-extension API, pgkit uses SQL primitives. Arc does
+   * not call `bulkWrite` internally, so the exact shape is kit-specific.
+   * See `BulkWriteOperation<TDoc>` (exported from arc) for a reference
+   * shape you can use when implementing your own kit; mongokit-compatible
+   * callers should import its own operation types.
+   */
+  bulkWrite?: unknown;
+  /** Restore a soft-deleted document. Should fire `before:restore` hooks. */
+  restore?(id: string, options?: QueryOptions): Promise<TDoc | null>;
+  /** Paginated list of soft-deleted documents. */
+  getDeleted?(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginationResult<TDoc> | TDoc[]>;
+  /**
+   * Run an aggregation pipeline.
+   *
+   * Structurally typed as `unknown` because each kit uses a different
+   * stage type (mongoose's `PipelineStage`, prisma's client-extension
+   * builders, pgkit's query-builder primitives, …). Arc does not call
+   * `aggregate` internally — it's a capability consumers use directly on
+   * the repo. Cast or re-declare at the call site using your kit's types.
+   */
+  aggregate?: unknown;
+  /**
+   * Paginated aggregation. Same kit-specificity reasoning as `aggregate`
+   * — structurally `unknown`, type-safe at the call site.
+   */
+  aggregatePaginate?: unknown;
+  /**
+   * Run `callback` inside a transaction. Adapters should auto-retry on
+   * transient transaction errors and expose a `session` the callback can
+   * forward to subsequent repo calls.
+   */
+  withTransaction?<T>(callback: (session: RepositorySession) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  /** slugLookup preset — fetch by a business slug. */
+  getBySlug?(slug: string, options?: QueryOptions): Promise<TDoc | null>;
+  /** tree preset — return the full hierarchy. */
+  getTree?(options?: QueryOptions): Promise<TDoc[]>;
+  /** tree preset — return direct children of a node. */
+  getChildren?(parentId: string, options?: QueryOptions): Promise<TDoc[]>;
   [key: string]: unknown;
 }
 /**
- * Extract document type from a repository
+ * Extract document type from a repository.
  *
  * @example
- * ```typescript
+ * ```ts
  * type UserDoc = InferDoc<typeof userRepository>;
- * // UserDoc is now the document type of userRepository
  * ```
  */
 type InferDoc<R> = R extends CrudRepository<infer T> ? T : never;
@@ -465,6 +828,16 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   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 middlewares: MiddlewareConfig;
   readonly disableDefaultRoutes: boolean;
   readonly disabledRoutes: CrudRouteKey[];
@@ -845,8 +1218,8 @@ interface AccessControlConfig {
 }
 /** Minimal repository interface for access-controlled fetch operations */
 interface AccessControlRepository {
-  getById(id: string, options?: unknown): Promise<unknown>;
-  getOne?: (filter: AnyRecord, options?: unknown) => Promise<unknown>;
+  getById(id: string, options?: QueryOptions): Promise<unknown>;
+  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
 }
 declare class AccessControl {
   private readonly tenantField;
@@ -890,7 +1263,7 @@ declare class AccessControl {
    * Replaces the duplicated pattern in get/update/delete:
    *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
    */
-  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: unknown): Promise<TDoc | null>;
+  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: QueryOptions): Promise<TDoc | null>;
   /**
    * Post-fetch access control validation for items fetched by non-ID queries
    * (e.g., getBySlug, restore). Applies org scope, policy filters, and
@@ -1123,7 +1496,7 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
     soft?: boolean;
   }>>;
   getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginationResult<TDoc>>>;
   restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
   getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
   getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
@@ -1958,6 +2331,24 @@ interface AdditionalRoute {
     }>;
     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';
@@ -2075,9 +2466,17 @@ interface RouteSchemaOptions {
   filterableFields?: string[];
   fieldRules?: Record<string, {
     systemManaged?: boolean;
+    hidden?: boolean;
     immutable?: boolean;
     immutableAfterCreate?: boolean;
-    optional?: boolean;
+    optional?: boolean; /** String minimum length — auto-maps to OpenAPI `minLength` and MCP tool schema */
+    minLength?: number; /** String maximum length — auto-maps to OpenAPI `maxLength` and MCP tool schema */
+    maxLength?: number; /** Number minimum — auto-maps to OpenAPI `minimum` and MCP tool schema */
+    min?: number; /** Number maximum — auto-maps to OpenAPI `maximum` and MCP tool schema */
+    max?: number; /** Regex pattern — auto-maps to OpenAPI `pattern` and MCP tool schema */
+    pattern?: string; /** Allowed values — auto-maps to OpenAPI `enum` and MCP tool schema */
+    enum?: ReadonlyArray<string | number>; /** Human-readable description — auto-maps to OpenAPI `description` */
+    description?: string;
     [key: string]: unknown;
   }>;
   query?: Record<string, unknown>;
@@ -2544,6 +2943,33 @@ interface RegistryEntry extends ResourceMetadata {
   audit?: boolean | {
     operations?: ("create" | "update" | "delete")[];
   };
+  /**
+   * v2.8 declarative actions metadata — populated from `ResourceConfig.actions`.
+   *
+   * Consumed by OpenAPI generation (renders `POST /:id/action` with a
+   * discriminated body schema) and MCP tool generation.
+   *
+   * Added in 2.8.1.
+   */
+  actions?: Array<{
+    readonly name: string;
+    readonly description?: string; /** Raw per-action schema (JSON Schema, Zod v4, or legacy field map) */
+    readonly schema?: Record<string, unknown>; /** Per-action permission check (if different from resource-level `actionPermissions`) */
+    readonly permissions?: PermissionCheck; /** MCP tool generation flag — `false` to skip, object for overrides */
+    readonly mcp?: boolean | {
+      readonly description?: string;
+      readonly annotations?: Record<string, unknown>;
+    };
+  }>;
+  /**
+   * Resource-level fallback permission for actions without per-action
+   * permissions. Used by OpenAPI to determine auth requirements and by MCP
+   * as the fallback in `createActionToolHandler`.
+   *
+   * Added in 2.8.1 — previously not surfaced to downstream consumers,
+   * causing OpenAPI to mark action endpoints as public when runtime required auth.
+   */
+  actionPermissions?: PermissionCheck;
 }
 interface RegistryStats {
   total?: number;
@@ -2601,68 +3027,84 @@ type TypedRepository<TDoc> = CrudRepository<TDoc>;
 //#endregion
 //#region src/adapters/interface.d.ts
 /**
- * Minimal repository interface for flexible adapter compatibility.
- * Any repository with these method signatures is accepted — no `as any` needed.
+ * Minimal structural repository shape for flexible adapter compatibility.
  *
- * CrudRepository<TDoc> and MongoKit Repository both satisfy this interface.
- */
-/**
- * Minimal repository interface for flexible adapter compatibility.
- * Any repository with these method signatures is accepted.
+ * `RepositoryLike` is the **loose** variant of `CrudRepository<TDoc>` — it
+ * uses `unknown` for document payloads so any object with the right method
+ * names satisfies it without type assertions. Prefer `CrudRepository<TDoc>`
+ * for kits you own; use `RepositoryLike` when wrapping third-party repos.
  *
- * **Required** — core CRUD (every resource needs these):
- *   getAll, getById, create, update, delete
+ * Both interfaces declare the same tiered capabilities:
  *
- * **Recommended** — used by AccessControl for compound queries:
- *   getOne
+ * - **Required** — `getAll`, `getById`, `create`, `update`, `delete`
+ * - **Recommended** — `getOne` / `getByQuery` (used by AccessControl for
+ *   compound filters like `idField + orgId + policy`)
+ * - **Optional** — feature-detected at runtime by presets and the
+ *   BaseController. Declare only what your DB supports.
  *
- * **Optional** — enabled by presets, checked at runtime:
- *   getBySlug     — slugLookup preset
- *   getDeleted    — softDelete preset (list soft-deleted)
- *   restore       — softDelete preset (restore soft-deleted)
- *   getTree       — tree preset (hierarchical queries)
- *   getChildren   — tree preset (child nodes)
- *   createMany    — bulk preset (batch create)
- *   updateMany    — bulk preset (batch update by filter)
- *   deleteMany    — bulk preset (batch delete by filter)
+ * See [CrudRepository](../types/repository.ts) for full prose-level docs
+ * on each method and the design rationale behind the tiering.
  */
 interface RepositoryLike {
-  getAll(params?: unknown): Promise<unknown>;
-  getById(id: string, options?: unknown): Promise<unknown>;
-  create(data: unknown, options?: unknown): Promise<unknown>;
-  update(id: string, data: unknown, options?: unknown): Promise<unknown>;
-  delete(id: string, options?: unknown): Promise<unknown>;
-  /**
-   * The repository's native primary key field. When set, Arc's BaseController
-   * will pass route params through to `update()`/`delete()`/`restore()` calls
+  /**
+   * The repository's native primary key field. When set, arc's BaseController
+   * passes route params through to `update()`/`delete()`/`restore()` calls
    * unchanged instead of translating them to `_id`.
    *
-   * Set this to match your `defineResource({ idField })` for repositories that
-   * natively look up by a custom field (e.g. MongoKit's
-   * `new Repository(Model, [], {}, { idField: 'id' })`). Without it, Arc will
-   * try to translate route ids → fetched doc's `_id` which 404s on repos that
-   * don't key on `_id`.
+   * Match this to your `defineResource({ idField })` for repositories that
+   * natively look up by a custom field (e.g. mongokit's
+   * `new Repository(Model, [], {}, { idField: 'id' })`). Without it, arc
+   * will try to translate route ids → fetched doc's `_id`, which 404s on
+   * repos that don't key on `_id`.
    *
-   * Defaults to `'_id'` (Mongo). Repositories that always use `_id` may omit it.
+   * Defaults to `'_id'` (Mongo). Kits that always use `_id` may omit it.
    */
   readonly idField?: string;
-  /** Find single doc by compound filter — used by AccessControl for idField + org/policy scoping.
-   * Without this, Arc falls back to getById + post-fetch security checks. */
-  getOne?(filter: Record<string, unknown>, options?: unknown): Promise<unknown>;
-  getBySlug?(slug: string, options?: unknown): Promise<unknown>;
-  getDeleted?(options?: unknown): Promise<unknown>;
-  restore?(id: string): Promise<unknown>;
-  getTree?(options?: unknown): Promise<unknown>;
-  getChildren?(parentId: string, options?: unknown): Promise<unknown>;
-  createMany?(items: unknown[], options?: unknown): Promise<unknown>;
-  updateMany?(filter: Record<string, unknown>, data: unknown): Promise<unknown>;
-  deleteMany?(filter: Record<string, unknown>): Promise<unknown>;
+  getAll(params?: PaginationParams, options?: QueryOptions): Promise<unknown>;
+  getById(id: string, options?: QueryOptions): Promise<unknown>;
+  create(data: unknown, options?: WriteOptions): Promise<unknown>;
+  update(id: string, data: unknown, options?: WriteOptions): 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>;
+  /**
+   * Find a single doc by compound filter. Used by AccessControl for
+   * `idField + org + policy` scoping. Without this, arc falls back to
+   * `getById` + post-fetch security checks (slower, and 404s on custom
+   * idFields that live outside the user's scope).
+   */
+  getOne?(filter: Record<string, unknown>, options?: QueryOptions): Promise<unknown>;
+  /** Alias many kits expose alongside `getOne`. Arc checks both. */
+  getByQuery?(filter: Record<string, unknown>, options?: QueryOptions): Promise<unknown>;
+  count?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<number>;
+  exists?(filter: Record<string, unknown>, options?: QueryOptions): Promise<boolean | {
+    _id: unknown;
+  } | null>;
+  distinct?<T = unknown>(field: string, filter?: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
+  findAll?(filter?: Record<string, unknown>, options?: QueryOptions): Promise<unknown[]>;
+  getOrCreate?(filter: Record<string, unknown>, data: unknown, options?: WriteOptions): Promise<unknown>;
+  createMany?(items: unknown[], options?: WriteOptions): Promise<unknown[]>;
+  updateMany?(filter: Record<string, unknown>, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
+  deleteMany?(filter: Record<string, unknown>, options?: DeleteOptions): Promise<DeleteManyResult>;
+  bulkWrite?: unknown;
+  restore?(id: string, options?: QueryOptions): Promise<unknown>;
+  getDeleted?(params?: PaginationParams, options?: QueryOptions): Promise<PaginationResult<unknown> | unknown[]>;
+  aggregate?: unknown;
+  aggregatePaginate?: 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>;
   [key: string]: unknown;
 }
 interface DataAdapter<TDoc = unknown> {
   /**
-   * Repository implementing CRUD operations
-   * Accepts CrudRepository, MongoKit Repository, or any compatible object
+   * Repository implementing CRUD operations. Accepts the typed
+   * `CrudRepository<TDoc>` or the loose `RepositoryLike` — arc checks
+   * capabilities at runtime via feature detection.
    */
   repository: CrudRepository<TDoc> | RepositoryLike;
   /** Adapter identifier for introspection */
@@ -2753,4 +3195,4 @@ interface ValidationResult {
 }
 type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
 //#endregion
-export { PresetFunction as $, QueryOptions as $t, EventsDecorator as A, BaseController as At, InferResourceDoc as B, FastifyHandler as Bt, ConfigError as C, defineHook as Cn, TypedResourceConfig as Ct, CrudRouterOptions as D, ValidationResult$1 as Dt, CrudRouteKey as E, 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, QueryResolver as Mt, FastifyWithDecorators as N, QueryResolverConfig as Nt, CrudSchemas as O, envelope as Ot, FieldRule as P, BodySanitizer as Pt, PopulateOption as Q, PaginationParams as Qt, InferAdapterDoc as R, ControllerHandler as Rt, AuthenticatorContext as S, createHookSystem as Sn, TypedRepository as St, CrudController as T, UserOrganization as Tt, JWTPayload as U, IRequestContext as Ut, IntrospectionData as V, IController as Vt, JwtContext as W, RouteHandler as Wt, OwnershipCheck as X, InferDoc as Xt, OpenApiSchemas as Y, CrudRepository as Yt, ParsedQuery as Z, PaginatedResult as Zt, ArcInternalMetadata as _, afterDelete as _n, RouteMcpConfig as _t, RelationMetadata as a, PipelineContext as an, RegistryStats as at, AuthPluginOptions as b, beforeDelete as bn, TokenPair as bt, ValidationResult as c, DefineHookOptions as cn, RequestWithExtras as ct, ActionHandlerFn as d, HookOperation as dn, ResourceHookContext as dt, Guard as en, PresetHook as et, ActionsMap as f, HookPhase as fn, ResourceHooks as ft, ArcDecorator as g, afterCreate as gn, RouteHandlerMethod$1 as gt, ApiResponse as h, HookSystemOptions as hn, RouteDefinition as ht, FieldMetadata as i, PipelineConfig as in, RegistryEntry as it, FastifyRequestExtras as j, BaseControllerOptions as jt, EventDefinition as k, getUserId as kt, ActionDefinition as l, HookContext as ln, ResourceCacheConfig as lt, AnyRecord as m, HookSystem as mn, ResourcePermissions as mt, AdapterSchemaContext as n, NextFunction as nn, QueryParserInterface as nt, RepositoryLike as o, PipelineStep as on, RequestContext as ot, AdditionalRoute as p, HookRegistration as pn, ResourceMetadata as pt, MiddlewareHandler as q, ResourceDefinition as qt, DataAdapter as r, OperationFilter as rn, RateLimitConfig as rt, SchemaMetadata as s, Transform as sn, RequestIdOptions as st, AdapterFactory as t, Interceptor as tn, PresetResult as tt, ActionEntry as u, HookHandler as un, ResourceConfig as ut, ArcRequest as v, afterUpdate as vn, RouteSchemaOptions as vt, ControllerQueryOptions as w, UserLike as wt, Authenticator as x, beforeUpdate as xn, TypedController as xt, AuthHelpers as y, beforeCreate as yn, ServiceContext as yt, InferDocType as z, ControllerLike as zt };
+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 };