@classytic/arc 2.28.0 → 2.31.0

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

@@ -1,10 +1,12 @@
-import { a as QueryCacheConfig } from "./QueryCache-DOMT_iq7.mjs";
-import { P as ArcHeaders, i as RequestScope } from "./types-DjC-KUCz.mjs";
-import { c as AnyRecord, i as UserBase, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
-import "./elevation-C9s5hFP_.mjs";
-import { n as FieldPermissionMap } from "./fields-D3lhgzhD.mjs";
-import { n as EncryptionDirective } from "./types-Cc91nXuA.mjs";
-import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
+
+import { 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 "./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 { Filter } from "@classytic/repo-core/filter";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 import { DataAdapter, RepositoryLike } from "@classytic/repo-core/adapter";
@@ -188,6 +190,22 @@ interface ControllerConfigurableOptions {
  */
 interface BaseControllerOptions extends ControllerConstructionOptions, ControllerConfigurableOptions {}
 //#endregion
+//#region src/scope/projection.d.ts
+/**
+ * Lightweight projection of `RequestScope` — just the fields tenant-aware
+ * hooks and controllers usually read. Full discriminated-union access is
+ * still available through the underlying `RequestScope` for advanced
+ * branching on `scope.kind`.
+ */
+interface RequestScopeProjection$1 {
+  /** 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[];
+}
+//#endregion
 //#region src/hooks/HookSystem.d.ts
 type HookPhase = "before" | "around" | "after";
 type HookOperation = "create" | "update" | "delete" | "restore" | "read" | "list";
@@ -200,6 +218,18 @@ interface HookContext<T = AnyRecord> {
   user?: UserBase;
   context?: RequestContext;
   meta?: AnyRecord;
+  /**
+   * Tenant/user projection of the validated `RequestScope` — the same shape
+   * `ResourceHookContext.scope` and `IRequestContext.scope` expose, from the
+   * same helper, so every surface reads identity identically.
+   *
+   * THIS is the identity source in a global hook. `ctx.user` comes from the
+   * auth adapter and is not scope-validated; the canonical `updatedBy` hook is
+   * `ctx.scope?.userId`, not `ctx.user?.id`. `undefined` on public/unscoped
+   * routes. Branch on `scope.kind` via `ctx.context._scope` when you need the
+   * full discriminated union.
+   */
+  scope?: RequestScopeProjection$1;
 }
 type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
 /**
@@ -230,14 +260,8 @@ declare class HookSystem {
   private logger;
   private warn;
   constructor(options?: HookSystemOptions);
-  /**
-   * Generate hook key
-   */
   private getKey;
-  /**
-   * Register a hook
-   * Supports both object parameter and positional arguments
-   */
+  /** Supports both the object-parameter and positional argument forms. */
   register<T = AnyRecord>(resourceOrOptions: string | {
     name?: string;
     resource: string;
@@ -247,13 +271,7 @@ declare class HookSystem {
     priority?: number;
     dependsOn?: string[];
   }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
-  /**
-   * Register before hook
-   */
   before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
-  /**
-   * Register after hook
-   */
   after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
   /**
    * Register around hook — wraps the core operation.
@@ -269,22 +287,13 @@ declare class HookSystem {
     context?: RequestContext;
     meta?: AnyRecord;
   }): Promise<T | undefined>;
-  /**
-   * Execute hooks for a given context
-   */
   execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
-  /**
-   * Execute before hooks
-   */
   executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
     user?: UserBase;
     context?: RequestContext;
     meta?: AnyRecord;
   }): Promise<T>;
-  /**
-   * Execute after hooks
-   * Errors in after hooks are logged but don't fail the request
-   */
+  /** Errors in after hooks are logged but never fail the request. */
   executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
     user?: UserBase;
     context?: RequestContext;
@@ -297,13 +306,7 @@ declare class HookSystem {
    * Hooks without names or dependencies pass through in their original order.
    */
   private topologicalSort;
-  /**
-   * Get all registered hooks
-   */
   getAll(): HookRegistration[];
-  /**
-   * Get hooks for a specific resource
-   */
   getForResource(resource: string): HookRegistration[];
   /**
    * Get hooks matching filter criteria.
@@ -347,13 +350,7 @@ declare class HookSystem {
    * Check if any hooks exist for a specific resource/operation/phase combination.
    */
   has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
-  /**
-   * Clear all hooks
-   */
   clear(): void;
-  /**
-   * Clear hooks for a specific resource
-   */
   clearResource(resource: string): void;
 }
 /**
@@ -464,7 +461,7 @@ interface AccessControlConfig {
 /** Minimal repository interface for access-controlled fetch operations */
 interface AccessControlRepository {
   getById(id: string, options?: QueryOptions): Promise<unknown>;
-  getOne?: (filter: AnyRecord, options?: QueryOptions) => Promise<unknown>;
+  getOne?: (filter: AnyRecord | Filter, options?: QueryOptions) => Promise<unknown>;
 }
 declare class AccessControl {
   private readonly tenantField;
@@ -483,7 +480,7 @@ declare class AccessControl {
    * Build filter for single-item operations (get/update/delete)
    * Combines ID filter with policy/org filters for proper security enforcement
    */
-  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
+  buildIdFilter(id: string, req: IRequestContext): AnyRecord | Filter;
   /**
    * Check if a post-fetch item matches the request's `_policyFilters`.
    *
@@ -657,7 +654,7 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
   /**
    * Composable access control (ID filtering, policy checks, org scope, ownership).
    *
-   * Not `readonly` since 2.15.0 — `configure()` rebuilds it when the host
+   * Not `readonly` — `configure()` rebuilds it when the host
    * supplies tenant/idField/matchesFilter post-construction. Same model as
    * `queryResolver` after `setQueryParser` shipped in 2.10.9.
    */
@@ -665,7 +662,7 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
   /**
    * Composable body sanitization (field permissions, system fields).
    *
-   * Not `readonly` since 2.15.0 — `configure()` rebuilds it when the host
+   * Not `readonly` — `configure()` rebuilds it when the host
    * supplies schemaOptions/onFieldWriteDenied post-construction.
    */
   bodySanitizer: BodySanitizer;
@@ -854,9 +851,9 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    */
   private scheduleCacheRefresh;
   /** Cached `list()` flow with SWR semantics. Returns null when cache is disabled. */
-  protected withListCache(req: IRequestContext, options: ParsedQuery): Promise<IControllerResponse<ListResult<TDoc>> | null>;
+  protected withListCache(req: IRequestContext, options: ControllerQueryOptions): Promise<IControllerResponse<ListResult<TDoc>> | null>;
   /** Cached `get()` flow with SWR semantics. Returns null when cache is disabled. */
-  protected withGetCache(req: IRequestContext, id: string, options: ParsedQuery): Promise<IControllerResponse<TDoc> | null>;
+  protected withGetCache(req: IRequestContext, id: string, options: ControllerQueryOptions): Promise<IControllerResponse<TDoc> | null>;
   list(req: IRequestContext): Promise<IControllerResponse<ListResult<TDoc>>>;
   /**
    * Resource-dispatch verbs router. Returns `null` when the request is
@@ -897,10 +894,10 @@ declare class BaseCrudController<TDoc = AnyRecord, TRepository extends Repositor
    */
   protected isFieldExposedForRead(field: string): boolean;
   /** Execute list query through hooks (extracted for cache revalidation) */
-  protected executeListQuery(options: ParsedQuery, req: IRequestContext): Promise<ListResult<TDoc>>;
+  protected executeListQuery(options: ControllerQueryOptions, req: IRequestContext): Promise<ListResult<TDoc>>;
   get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
   /** Execute get query through hooks (extracted for cache revalidation) */
-  protected executeGetQuery(id: string, options: ParsedQuery, req: IRequestContext): Promise<{
+  protected executeGetQuery(id: string, options: ControllerQueryOptions, req: IRequestContext): Promise<{
     doc: TDoc | null;
     reason: FetchDenialReason | null;
   }>;
@@ -1242,11 +1239,27 @@ interface AuthPluginOptions {
   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 `raw: true`.
+ * without switching to `rawHandler`.
  */
 interface ServerAccessor {
   /** Event bus — publish domain events from any handler */
@@ -1325,11 +1338,9 @@ interface ServerAccessor {
 /**
  * First-class projection of `request._scope` for controller handlers.
  *
- * **v2.10.6:** previously, pulling tenant/user/role info from inside a
- * controller override meant digging through `req.metadata._scope` and
- * calling `getOrgId(scope)` / `getUserId(user)` manually. This projection
- * lifts the two fields most hosts need directly onto `req` so cross-kit
- * controller code reads:
+ * 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) {
@@ -1402,7 +1413,7 @@ interface IRequestContext<TBody = unknown, TParams extends Record<string, string
   metadata?: TMetadata;
   /**
    * Fastify server accessor — publish events, log, and audit
-   * from any handler without switching to `raw: true`.
+   * from any handler without switching to `rawHandler`.
    *
    * @example
    * ```typescript
@@ -1437,7 +1448,7 @@ interface IControllerResponse<T = unknown> {
  * Controller handler — Arc's standard pattern.
  *
  * Receives a request context object, returns IControllerResponse.
- * Use with `raw: false` in routes.
+ * Use with `handler` in routes.
  *
  * **Generic parameters:**
  * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
@@ -1474,7 +1485,6 @@ interface IControllerResponse<T = unknown> {
  *   path: '/products',
  *   handler: createProduct,
  *   permissions: requireAuth(),
- *   raw: false,  // Arc wraps this into Fastify handler
  * }]
  * ```
  */
@@ -1483,7 +1493,7 @@ type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Rec
  * Fastify native handler
  *
  * Standard Fastify request/reply pattern.
- * Use with `raw: true` in routes.
+ * Use with `rawHandler` in routes.
  *
  * @example
  * ```typescript
@@ -1496,12 +1506,31 @@ type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Rec
  * routes: [{
  *   method: 'GET',
  *   path: '/files/:id/download',
- *   handler: downloadFile,
+ *   rawHandler: downloadFile,
  *   permissions: requireAuth(),
- *   raw: true,  // Use as-is, no wrapping
  * }]
  * ```
  */
+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
@@ -1530,11 +1559,11 @@ interface IController<TDoc = unknown> {
  * Flexible controller interface — accepts controllers with any handler style,
  * including class instances with extra methods / private fields.
  *
- * **v2.10.6:** the previous `[key: string]: unknown` index signature made
- * real class instances fail structural assignment (`new ScrapController()`
- * needed a `as unknown as ControllerLike` cast, because class instances
- * don't have an index signature). Dropped — arc only invokes the CRUD
- * methods at runtime, so the rest of the shape is the caller's concern.
+ * 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
@@ -1580,7 +1609,7 @@ interface RouteMcpConfig {
  *
  * - `handler: 'string'` → controller method → full Arc pipeline + MCP tool
  * - `handler: function` → inline handler → full Arc pipeline + MCP tool
- * - `raw: true` → raw Fastify handler → no pipeline, no MCP by default
+ * - `rawHandler` → raw Fastify handler → no pipeline, no MCP by default
  */
 interface RouteDefinition {
   readonly method: RouteMethod;
@@ -1589,14 +1618,14 @@ interface RouteDefinition {
   /**
    * Route handler.
    * - String: controller method name (Arc pipeline) — runtime lookup, no TS coverage on typos.
-   * - Function without `raw: true`: receives IRequestContext, returns IControllerResponse (Arc pipeline)
-   * - Function with `raw: true`: raw Fastify handler `(request, reply)`
+   * - Function: receives IRequestContext, returns IControllerResponse (Arc pipeline)
+   * - For a raw Fastify handler `(request, reply)`, use {@link rawHandler}
    *
    * Prefer `controllerMethod` (2.16) over the string form when you want the
    * compiler to catch typos. `handler` stays optional when `controllerMethod`
    * is set — exactly one of the two must be declared.
    */
-  readonly handler?: string | ControllerHandler | RouteHandlerMethod | ((request: never, reply: never) => unknown);
+  readonly handler?: string | ControllerHandler;
   /**
    * Typed function-reference handler (2.16). Receives the live controller
    * instance and returns the method to invoke — TypeScript catches typos
@@ -1608,11 +1637,15 @@ interface RouteDefinition {
    * handlers go through), so there's no per-request lookup overhead.
    * The returned method is bound to the controller before dispatch.
    *
+   * PIPELINE-ONLY: the referenced method is invoked as a `ControllerHandler`
+   * (one `IRequestContext`), because the router derives "is this raw?" from
+   * {@link rawHandler} alone and this field is mutually exclusive with it.
+   * There is no flag that could make a `controllerMethod` route raw. For a
+   * Fastify-native controller method, put its NAME in `rawHandler` — the
+   * lookup is the same, and the field states the calling convention.
+   *
    * Mutually exclusive with `handler` — passing both throws at boot
-   * with a clear "pick one" message. The runtime contract on what the
-   * returned function accepts mirrors the `handler` rules: a plain
-   * `ControllerHandler` for pipeline routes, a raw Fastify handler when
-   * the route is `raw: true`.
+   * with a clear "pick one" message.
    *
    * Typed loosely (`(controller: unknown) => …`) at the type-system
    * boundary because `RouteDefinition` is not generic over the
@@ -1636,14 +1669,33 @@ interface RouteDefinition {
    * });
    * ```
    */
-  readonly controllerMethod?: (controller: unknown) => ControllerHandler | RouteHandlerMethod;
+  readonly controllerMethod?: (controller: unknown) => ControllerHandler;
   /** Permission check — REQUIRED */
   readonly permissions: PermissionCheck;
   /**
-   * Raw mode — bypasses Arc pipeline. Handler receives raw Fastify
-   * request/reply. Default: false.
-   */
-  readonly raw?: boolean;
+   * Fastify-native handler — receives `(request, reply)` and owns the response.
+   * Bypasses arc's pipeline entirely: no `IControllerResponse` shaping, no
+   * field-write sanitization.
+   *
+   * Mutually exclusive with {@link handler}. The FIELD carries the intent, so
+   * there is no flag to forget: the previous `raw: boolean` let a Fastify-shaped
+   * function sit in `handler` without it (silently run through the pipeline) or
+   * a pipeline handler sit there with it (silently unwrapped), and neither
+   * mismatch was a type error.
+   *
+   * Splitting the two also restores inference. One field carrying both shapes
+   * meant a union of several function types, which has no single contextual
+   * signature — so an inline `handler: async (req) => …` reported TS7006 and
+   * every author annotated `req` by hand. Fastify types its own
+   * `RouteOptions.handler` as ONE function type for exactly this reason; see
+   * {@link RawRouteHandler} for why arc declares its own rather than reusing
+   * `RouteHandlerMethod` directly.
+   *
+   * Accepts a controller-method NAME as well, same as {@link handler} — the
+   * lookup is identical and only the calling convention differs, so a
+   * Fastify-native controller method stays reachable by name.
+   */
+  readonly rawHandler?: string | RawRouteHandler;
   /** Logical operation name (pipeline keys, MCP tool naming). */
   readonly operation?: string;
   /** OpenAPI summary */
@@ -1675,7 +1727,8 @@ interface RouteDefinition {
    */
   readonly tenantScope?: boolean;
   /**
-   * SSE streaming mode. Two handler shapes work:
+   * SSE streaming mode. Requires {@link rawHandler} — the handler is invoked
+   * with `(request, reply)` and owns the response. Two shapes work:
    *
    * - Write to `reply.raw` directly (NDJSON, custom SSE — historical contract).
    * - Return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`,
@@ -1706,7 +1759,7 @@ interface RouteDefinition {
    * `onFieldWriteDenied: 'reject' | 'strip'` setting governs how denials
    * are surfaced.
    *
-   * `raw: true` routes ALWAYS bypass this — they've opted out of the
+   * `rawHandler` routes ALWAYS bypass this — they've opted out of the
    * pipeline entirely.
    */
   readonly fieldWrite?: boolean;
@@ -1729,6 +1782,22 @@ interface RouteDefinition {
    * it to a dedicated `routes:` entry, or rely on the resource-level limit.
    */
   readonly rateLimit?: RateLimitConfig | false;
+  /**
+   * Per-route CORS override, forwarded to `@fastify/cors` as
+   * `routeOptions.config.cors`. `undefined` inherits the app policy; `false`
+   * disables CORS for this route; an object replaces the app policy for it.
+   *
+   * Needed because one app-wide policy cannot serve both an API and a public
+   * asset: an API wants `credentials: true` with a pinned origin list, a public
+   * asset wants `origin: "*"`, and `*` + credentials is forbidden by the spec
+   * (arc throws at boot on that pair).
+   *
+   * ```ts
+   * { method: "GET", path: "/manifest.json", permissions: allowPublic(),
+   *   cors: { origin: "*", credentials: false }, handler }
+   * ```
+   */
+  readonly cors?: RouteCorsConfig;
   /**
    * Fastify route schema. Each slot (`body`, `querystring`, `params`,
    * `headers`, `response[status]`) accepts a plain JSON Schema object
@@ -2318,12 +2387,9 @@ interface ResourceExtensions {
  * Hook context passed to resource-level hook handlers. Mirrors
  * HookSystem's HookContext but with a simpler API for inline use.
  *
- * **v2.10.8:** `context` and a first-class `scope` projection are now
- * forwarded from the internal `HookContext`. Before this release, inline
- * `config.hooks` handlers had no way to reach the caller's tenant or
- * user info — they had to bypass the documented API and push directly
- * into `resource._pendingHooks` to get the raw internal shape. Now the
- * documented DX is complete:
+ * `context` and a first-class `scope` projection are forwarded from the
+ * internal `HookContext`, so an inline handler reaches the caller's tenant
+ * and user through the documented API:
  *
  * ```ts
  * hooks: {
@@ -2358,7 +2424,7 @@ interface ResourceHookContext {
    * First-class projection of request scope — `{ organizationId?, userId?, orgRoles? }`.
    * Populated for every scoped request so multi-tenant hooks don't have to
    * drill into `context._scope.organizationId` themselves. Matches the
-   * identically-named field on `IRequestContext` (v2.10.6) so the same
+   * identically-named field on `IRequestContext` so the same
    * read pattern works in controllers and hooks.
    */
   scope?: {
@@ -2670,6 +2736,16 @@ interface PresetResult {
   /** Preset routes — merged into the resource's `routes` array. */
   routes?: RouteDefinition[] | ((permissions: ResourcePermissions) => RouteDefinition[]);
   middlewares?: MiddlewareConfig;
+  /**
+   * Permission gates the preset contributes as SECURE DEFAULTS. Merged per-op
+   * into the resource's `permissions`, but ONLY for operations the host has not
+   * explicitly gated — the host's own permission always wins. Lets a preset make
+   * authorization part of the permission/introspection model (required auth at
+   * `onRequest`, MCP parity) instead of relying on middleware alone. Example:
+   * `ownedByUser` injects `requireAuth()` on update/delete so an ownership
+   * resource is never public-by-omission.
+   */
+  permissions?: Partial<ResourcePermissions>;
   schemaOptions?: RouteSchemaOptions;
   controllerOptions?: Record<string, unknown>;
   hooks?: PresetHook[];
@@ -2828,7 +2904,7 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * object, primitive) is supported via auto-envelope (2.17+) but the
    * explicit envelope is the canonical contract — declared `fields:`
    * permissions, custom `status`, `meta`, and `headers` only work when
-   * you return the envelope. Set `raw: true` on a route to opt out of
+   * you return the envelope. Declare a route's function via `rawHandler` to opt out of
    * arc's pipeline entirely (custom streaming, SSE, manual `reply.send()`).
    *
    * **Path collisions with auto-CRUD are detected at `defineResource()` time.**
@@ -2843,7 +2919,7 @@ interface ResourceConfig<TDoc = AnyRecord> {
    * ```typescript
    * routes: [
    *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
-   *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
+   *   { method: 'POST', path: '/webhook', rawHandler: webhookFn, permissions: auth() },
    * ]
    * ```
    *
@@ -3035,6 +3111,18 @@ interface ResourceConfig<TDoc = AnyRecord> {
   skipValidation?: boolean;
   /** Don't register in introspection */
   skipRegistry?: boolean;
+  /**
+   * Fail-closed permission invariant. When `true`, any enabled CRUD WRITE
+   * (create/update/delete) that mounts WITHOUT a permission gate is a FATAL
+   * define-time error — `defineResource()` throws instead of shipping an
+   * unauthenticated write with only a warning. Reads that are ungated stay a
+   * non-fatal `info` hint (public catalogs are legitimate).
+   *
+   * Off by default (public-by-omission still only warns) so existing hosts are
+   * not broken. Opt in per-resource here, or app-wide via the
+   * `ARC_STRICT_PERMISSIONS=true` env — the recommended production posture.
+   */
+  strictPermissions?: boolean;
   /**
    * Default `limit` value when the request omits `?limit=`. Default 20.
    * Surfaced at the resource level (rather than only via a custom
@@ -3238,16 +3326,19 @@ interface ResourceConfig<TDoc = AnyRecord> {
  * "this resource will never work" failures.
  */
 /**
- * One non-fatal diagnostic produced during resource validation.
+ * One diagnostic produced during resource validation.
  *
- * - `severity`: log level the host logger uses (`warn` for misconfigurations
- *   the host should clean up, `info` for deprecation hints).
+ * - `severity`: `error` is FATAL — `defineResource()` throws at define-time,
+ *   the resource never boots (used by strict security invariants like ungated
+ *   CRUD under `strictPermissions`). `warn` flags a misconfiguration the host
+ *   should clean up; `info` is a deprecation hint. `warn`/`info` are non-fatal
+ *   and flushed through the host logger on first mount.
  * - `code`: stable identifier for the diagnostic — hosts and tests can match
  *   on this without parsing the human-readable message.
  * - `message`: pre-formatted line, resource name already interpolated.
  */
 interface ResourceDiagnostic {
-  severity: "warn" | "info";
+  severity: "error" | "warn" | "info";
   code: string;
   message: string;
 }
@@ -3787,6 +3878,7 @@ interface ArcInternalMetadata extends RequestContext {
   _ownershipCheck?: {
     field: string;
     userId: string;
+    missingOwner?: "deny" | "allow";
   };
   /** Arc instance references (hooks, field permissions, etc.) */
   arc?: {
@@ -3819,7 +3911,13 @@ interface ControllerQueryOptions {
    */
   lookups?: LookupOption[];
   select?: string | string[] | Record<string, 0 | 1>;
-  filters?: Record<string, unknown>;
+  /**
+   * Resolved row filter. Flat equality filters are a plain record; filters
+   * carrying `$`-operators (`$or`/`$and`/`$gte`) are normalized to the portable
+   * repo-core `Filter` IR at the repository boundary (see `toRepositoryFilter`)
+   * so every kit compiles them. Repositories accept both (`FilterInput`).
+   */
+  filters?: Record<string, unknown> | Filter;
   search?: string;
   lean?: boolean;
   after?: string;
@@ -3875,6 +3973,14 @@ interface PopulateOption {
  * parsers (MongoKit, PrismaKit) add fields without breaking Arc's types.
  */
 interface ParsedQuery {
+  /**
+   * Row filter — a plain record in the parser's operator dialect. This is the
+   * PARSER contract: a `QueryParser` (arc built-in, MongoKit, PrismaKit) emits a
+   * record, never repo-core `Filter` IR. IR appears only AFTER security
+   * composition, on `ControllerQueryOptions.filters` (via `toRepositoryFilter`).
+   * Keeping this record-only means `QueryResolver` never has to guess whether a
+   * parsed filter is an IR node it must not blindly spread tenant/policy onto.
+   */
   filters?: Record<string, unknown>;
   limit?: number;
   sort?: string | Record<string, 1 | -1>;
@@ -4189,4 +4295,4 @@ interface ValidateOptions {
   strict?: boolean;
 }
 //#endregion
-export { OpenApiSchemas as $, SlugExt as $t, RequestIdOptions as A, ControllerConfigurableOptions as An, RouteDefinition as At, defineResource as B, RouteHandler as Bt, RequestContext as C, defineHook as Cn, PipelineStep as Ct, HealthCheck as D, ArcListResult as Dn, ActionEntry as Dt, GracefulShutdownOptions as E, ArcGetResult as En, ActionDefinition as Et, FastifyWithDecorators as F, ControllerLike as Ft, OnTenantDeleteConfig as G, AuthenticatorContext as Gt, CrudController as H, AuthHelpers as Ht, MiddlewareHandler as I, FastifyHandler as It, PresetHook as J, BaseController as Jt, ResolvedTenantPurge as K, JwtContext as Kt, RequestWithExtras as L, IController as Lt, EventsDecorator as M, ListResult as Mn, RouteMethod as Mt, FastifyRequestExtras as N, BodySanitizer as Nn, RateLimitConfig as Nt, HealthOptions as O, ArcUpdateResult as On, ActionHandlerFn as Ot, FastifyWithAuth as P, BodySanitizerConfig as Pn, ControllerHandler as Pt, MiddlewareConfig as Q, TreeMixin as Qt, RegisterOptions as R, IControllerResponse as Rt, QueryParserInterface as S, createHookSystem as Sn, PipelineContext as St, CrudRouterOptions as T, ArcDeleteResult as Tn, ResourceCacheConfig as Tt, ResourceConfig as U, AuthPluginOptions as Ut, ResourceDefinition as V, ServerAccessor as Vt, ResourcePermissions as W, Authenticator as Wt, CrudRouteKey as X, SoftDeleteMixin as Xt, PresetResult as Y, SoftDeleteExt as Yt, CrudSchemas as Z, TreeExt as Zt, ControllerQueryOptions as _, afterDelete as _n, Guard as _t, InferAdapterDoc as a, QueryResolverConfig as an, ResourceExtensions as at, ParsedQuery as b, beforeDelete as bn, OperationFilter as bt, TypedController as c, DefineHookOptions as cn, AggMeasureShorthand as ct, PaginationResult as d, HookOperation as dn, AggregationDateRangeRequirement as dt, SlugMixin as en, RouteSchemaOptions as et, IntrospectionData as f, HookPhase as fn, AggregationIndexHint as ft, ArcInternalMetadata as g, afterCreate as gn, AggregationsMap as gt, ResourceMetadata as h, HookSystemOptions as hn, AggregationRateLimit as ht, ValidationResult as i, QueryResolver as in, ResourceHooks as it, ArcDecorator as j, ControllerConstructionOptions as jn, RouteMcpConfig as jt, IntrospectionPluginOptions as k, BaseControllerOptions as kn, ActionsMap as kt, TypedRepository as l, HookContext as ln, AggregationCacheConfig as lt, RegistryStats as m, HookSystem as mn, AggregationMaterializedResult as mt, ConfigError as n, BulkMixin as nn, FieldRule$1 as nt, InferDocType as o, AccessControl as on, EventDefinition as ot, RegistryEntry as p, HookRegistration as pn, AggregationMaterializedContext as pt, PresetFunction as q, TokenPair as qt, ValidateOptions as r, BaseCrudController as rn, ResourceHookContext as rt, InferResourceDoc as s, AccessControlConfig as sn, AggMeasureInput as st, RouteHandlerMethod$1 as t, BulkExt as tn, ArcFieldRule as tt, TypedResourceConfig as u, HookHandler as un, AggregationConfig as ut, LookupOption as v, afterUpdate as vn, Interceptor as vt, ServiceContext as w, ArcCreateResult as wn, Transform as wt, PopulateOption as x, beforeUpdate as xn, PipelineConfig as xt, OwnershipCheck as y, beforeCreate as yn, NextFunction as yt, ResourceRegistry as z, IRequestContext as zt };
+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 };