@classytic/arc 2.16.0 → 2.17.0

package/dist/events/transports/redis-stream-entry.mjs

@@ -1,4 +1,37 @@
+import sjson from "secure-json-parse";
 //#region src/events/transports/redis-stream.ts
+/**
+* Redis Stream Event Transport — Durable Event Delivery
+*
+* Uses Redis Streams (`XADD`/`XREADGROUP`) for persistent, at-least-once event
+* delivery across multiple service instances. Unlike Pub/Sub, events are stored
+* in Redis and survive crashes/restarts.
+*
+* **Delivery guarantee:** at-least-once. Failed messages are left unacked and
+* reclaimed after `claimTimeoutMs`, which can result in duplicate handler
+* execution. Consumers must be idempotent (e.g. use `event.meta.id` as a
+* deduplication key) to achieve effectively-once processing.
+*
+* Key features:
+* - Consumer groups: each event delivered to exactly one consumer per group
+* - Crash recovery: pending entries are auto-claimed after `claimTimeoutMs`
+* - Dead letter stream: events exceeding `maxRetries` are moved to a DLQ
+* - Backpressure: configurable block time and batch size
+*
+* @example
+* ```typescript
+* import { RedisStreamTransport } from '@classytic/arc/events';
+* import Redis from 'ioredis';
+*
+* const transport = new RedisStreamTransport(new Redis(), {
+*   stream: 'arc-events',
+*   group: 'api-service',
+*   consumer: 'worker-1',
+* });
+*
+* await app.register(eventPlugin, { transport });
+* ```
+*/
 var RedisStreamTransport = class {
 	name = "redis-stream";
 	redis;
@@ -350,7 +383,7 @@ function parseStreamFields(fields) {
 	}
 	if (!eventType || !rawData) return null;
 	try {
-		const parsed = JSON.parse(rawData, (key, value) => {
+		const parsed = sjson.parse(rawData, (key, value) => {
 			if (key === "timestamp" && typeof value === "string") return new Date(value);
 			return value;
 		});

package/dist/events/transports/redis.d.mts

@@ -1,4 +1,4 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-C-2oAHtw.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-B1GFiYUy.mjs";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {

package/dist/events/transports/redis.mjs

@@ -1,5 +1,21 @@
+import sjson from "secure-json-parse";
 //#region src/events/transports/redis.ts
 /**
+* Redis Event Transport
+*
+* Uses Redis Pub/Sub for cross-process event delivery.
+* Optional dependency — only imported when explicitly used.
+*
+* @example
+* import { RedisEventTransport } from '@classytic/arc/events/redis';
+* import Redis from 'ioredis';
+*
+* const redis = new Redis();
+* const transport = new RedisEventTransport(redis, { channel: 'arc-events' });
+*
+* await app.register(eventPlugin, { transport });
+*/
+/**
 * DomainEvent contains a `Date` in `meta.timestamp`.  We serialize it as an
 * ISO string and revive it on the other end so subscribers always receive a
 * proper Date object.
@@ -11,7 +27,7 @@ function serialize(event) {
 	});
 }
 function deserialize(raw) {
-	return JSON.parse(raw, (key, value) => {
+	return sjson.parse(raw, (key, value) => {
 		if (key === "timestamp" && typeof value === "string") return new Date(value);
 		return value;
 	});

package/dist/factory/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-D-fYtKjb.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, f as LoadResourcesOptions, h as loadResources, i as CustomAuthenticatorOption, l as UnderPressureOptions, m as ResourceModule, n as BetterAuthOption, o as JwtAuthOption, p as ResourceLike, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-BRmS8TNa.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts
@@ -95,4 +95,4 @@ declare const edgePreset: Partial<CreateAppOptions>;
  */
 declare function getPreset(name: "production" | "development" | "testing" | "edge"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, developmentPreset, edgePreset, getPreset, loadResources, productionPreset, testingPreset, toFetchHandler };
+export { ArcFactory, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };

package/dist/factory/index.mjs

@@ -1,5 +1,6 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-DNccuhyI.mjs";
-import { t as loadResources } from "../loadResources-ChQEj8ih.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-BOXzPhKU.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-CzCEEsEm.mjs";
+import { t as loadResources } from "../loadResources-fol6JuvW.mjs";
 //#region src/factory/edge.ts
 /**
 * Convert a Fastify app into a Web Standards fetch handler.
@@ -46,4 +47,4 @@ function toFetchHandler(app, options = {}) {
 	};
 }
 //#endregion
-export { ArcFactory, createApp, developmentPreset, edgePreset, getPreset, loadResources, productionPreset, testingPreset, toFetchHandler };
+export { ArcFactory, createApp, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };

package/dist/fastify-augmentation-7LIR0nDv.d.mts

@@ -0,0 +1,42 @@
+import { An as HookSystem, z as ResourceRegistry } from "./index-C1JSBan-.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-ClykOQqa.mjs";
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/core/arcCorePlugin.d.ts
+interface ArcCorePluginOptions {
+  /** Enable event emission for CRUD operations (requires eventPlugin) */
+  emitEvents?: boolean;
+  /** Hook system instance (for testing/custom setup) */
+  hookSystem?: HookSystem;
+  /** Resource registry instance (for testing/custom setup) */
+  registry?: ResourceRegistry;
+}
+interface PluginMeta {
+  name: string;
+  version?: string;
+  options?: Record<string, unknown>;
+  registeredAt: string;
+}
+interface ArcCore {
+  /** Instance-scoped hook system */
+  hooks: HookSystem;
+  /** Instance-scoped resource registry */
+  registry: ResourceRegistry;
+  /** Whether event emission is enabled */
+  emitEvents: boolean;
+  /** External OpenAPI paths contributed by auth adapters or third-party integrations */
+  externalOpenApiPaths: ExternalOpenApiPaths[];
+  /** Registered plugins for introspection */
+  plugins: Map<string, PluginMeta>;
+}
+declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
+declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;
+//#endregion
+//#region src/types/fastify-augmentation.d.ts
+declare module "fastify" {
+  interface FastifyInstance {
+    arc?: ArcCore;
+  }
+}
+//#endregion
+export { arcCorePlugin as a, _default as i, ArcCorePluginOptions as n, PluginMeta as r, ArcCore as t };

package/dist/{fields-Anj0xdih.d.mts → fields-DqZLp5d6.d.mts}

@@ -1,4 +1,4 @@
-import { i as RequestScope } from "./types-DVfpSfx2.mjs";
+import { i as RequestScope } from "./types-CfapW2t8.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/types.d.ts

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { An as HookSystem, Dn as HookOperation, En as HookHandler, Fn as beforeCreate, In as beforeDelete, Ln as beforeUpdate, Mn as afterCreate, Nn as afterDelete, On as HookPhase, Pn as afterUpdate, Rn as createHookSystem, Tn as HookContext, jn as HookSystemOptions, kn as HookRegistration, wn as DefineHookOptions, zn as defineHook } from "../index-CkW0flkU.mjs";
+import { An as HookSystem, Dn as HookOperation, En as HookHandler, Fn as beforeCreate, In as beforeDelete, Ln as beforeUpdate, Mn as afterCreate, Nn as afterDelete, On as HookPhase, Pn as afterUpdate, Rn as createHookSystem, Tn as HookContext, jn as HookSystemOptions, kn as HookRegistration, wn as DefineHookOptions, zn as defineHook } from "../index-C1JSBan-.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,5 +1,5 @@
-import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-NwJ_qPlY.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-Cyzrz6SX.mjs";
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-DoE6UoC2.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-cpqVb85w.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 

package/dist/idempotency/index.mjs

@@ -1,4 +1,4 @@
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-B0sunfZZ.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-5JgaxieH.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
@@ -266,6 +266,12 @@ var MemoryIdempotencyStore = class {
 */
 const HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
 const HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
+/**
+* Cap recursion depth in body fingerprinting. Real APIs almost never exceed
+* ~10 levels; the cap is generous so well-formed payloads are unaffected,
+* yet low enough to stop a `{"a":{"a":{...thousands deep...}}}` stack bomb.
+*/
+const MAX_FINGERPRINT_DEPTH = 32;
 const idempotencyPlugin = async (fastify, opts = {}) => {
 	const { enabled = false, headerName = "idempotency-key", ttlMs = 864e5, lockTimeoutMs = 3e4, methods = [
 		"POST",
@@ -298,14 +304,24 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		return true;
 	}
 	/**
-	* Normalize body for consistent hashing (sort keys recursively)
+	* Normalize body for consistent hashing (sort keys recursively).
+	*
+	* Recursion is bounded by `MAX_FINGERPRINT_DEPTH` to defeat a deep-nesting
+	* DoS: an attacker who sends a 1 MB JSON body of nested `{"a":{"a":...}}`
+	* would otherwise blow the call stack inside this hot path. The cap
+	* exceeds any sensible API shape (real bodies are <10 levels deep) while
+	* still being well under V8's default stack budget. At the limit we
+	* substitute a sentinel string so the hash still differs from siblings
+	* but recursion stops — the request is fingerprinted as if everything
+	* beyond the cap were `"<truncated>"`.
 	*/
-	function normalizeBody(obj) {
+	function normalizeBody(obj, depth = 0) {
 		if (obj === null || typeof obj !== "object") return obj;
-		if (Array.isArray(obj)) return obj.map(normalizeBody);
+		if (depth >= MAX_FINGERPRINT_DEPTH) return "<truncated>";
+		if (Array.isArray(obj)) return obj.map((item) => normalizeBody(item, depth + 1));
 		const sorted = {};
 		const keys = Object.keys(obj).sort();
-		for (const key of keys) sorted[key] = normalizeBody(obj[key]);
+		for (const key of keys) sorted[key] = normalizeBody(obj[key], depth + 1);
 		return sorted;
 	}
 	/**

package/dist/idempotency/redis.d.mts

@@ -1,2 +1,2 @@
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-Cyzrz6SX.mjs";
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-cpqVb85w.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/{index-3oIimXQn.d.mts → index-3L-adFJO.d.mts}

@@ -1,6 +1,6 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-CH0OQudo.mjs";
-import { i as RequestScope, n as Mandate } from "./types-DVfpSfx2.mjs";
-import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-Anj0xdih.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-BVkZsvEe.mjs";
+import { i as RequestScope, n as Mandate } from "./types-CfapW2t8.mjs";
+import { c as PermissionCheck, l as PermissionContext, u as PermissionResult } from "./fields-DqZLp5d6.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/permissions/agent.d.ts

package/dist/{index-CkW0flkU.d.mts → index-C1JSBan-.d.mts}

@@ -1,7 +1,7 @@
-import { a as QueryCacheConfig } from "./QueryCache-SvmT_9ti.mjs";
-import { i as RequestScope } from "./types-DVfpSfx2.mjs";
-import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-Anj0xdih.mjs";
-import { n as DomainEvent } from "./EventTransport-C-2oAHtw.mjs";
+import { a as QueryCacheConfig } from "./QueryCache-8YmAQ-zW.mjs";
+import { i as RequestScope } from "./types-CfapW2t8.mjs";
+import { c as PermissionCheck, d as UserBase, n as FieldPermissionMap } from "./fields-DqZLp5d6.mjs";
+import { n as DomainEvent } from "./EventTransport-B1GFiYUy.mjs";
 import { KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 import * as _$_classytic_repo_core_adapter0 from "@classytic/repo-core/adapter";
@@ -1569,8 +1569,39 @@ interface AggregationConfig {
   having?: AnyRecord;
   /** Order grouped rows by groupBy field, measure alias, or joined-alias path. */
   sort?: Record<string, 1 | -1>;
-  /** Hard cap on result rows. Applied at the IR level (LIMIT / `$limit`). */
+  /**
+   * Static hard cap on result rows. Always applied at the IR level
+   * (LIMIT / `$limit`), regardless of URL params. Use when the
+   * aggregation has a fixed-size shape ("top 10 categories"). Mutually
+   * exclusive with `defaultLimit` / `maxLimit` — pick the static form
+   * OR the URL-driven form, not both.
+   */
   limit?: number;
+  /**
+   * URL-driven row limit — applied when the caller passes `?limit=N`.
+   * When set, the auto-route reads `query.limit`, parses it as a
+   * positive integer, caps it at `maxLimit` (or the framework default
+   * if `maxLimit` is unset), and writes the result into `AggRequest.limit`.
+   * When the caller omits `?limit`, this default applies.
+   *
+   * **DoS defense.** Auto-generated `/aggregations/:name` routes today
+   * have no upper bound on response size. A `groupBy: 'userId'` on a
+   * 10M-user table without `defaultLimit` returns a 10M-row JSON. Setting
+   * `defaultLimit: 100, maxLimit: 1000` bounds the response shape while
+   * letting power users request up to 1000 rows when they need them.
+   *
+   * Mutually exclusive with the static `limit` — boot error if both set.
+   * Setting `defaultLimit` without `maxLimit` uses the framework
+   * default cap (`AGG_FRAMEWORK_MAX_LIMIT = 1000`) — explicit is better.
+   */
+  defaultLimit?: number;
+  /**
+   * Hard ceiling for URL-driven `?limit=N`. Only meaningful when
+   * `defaultLimit` is set; ignored otherwise. Defaults to
+   * `AGG_FRAMEWORK_MAX_LIMIT` (1000) when omitted but `defaultLimit` is
+   * present. Boot validation: must be ≥ `defaultLimit`.
+   */
+  maxLimit?: number;
   /**
    * Top-N-per-group filter. Keeps only the top `limit` rows per
    * partition, ranked by `sortBy`. The classic "top 3 products per
@@ -2427,8 +2458,42 @@ interface RouteDefinition {
    * @default false
    */
   readonly tenantScope?: boolean;
-  /** SSE streaming mode */
+  /**
+   * SSE streaming mode. Two handler shapes work:
+   *
+   * - Write to `reply.raw` directly (NDJSON, custom SSE — historical contract).
+   * - Return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`,
+   *   `fetch().body`, etc.). 2.17.1+ auto-pipes these through
+   *   `pipeUIMessageStreamToReply()` so each chunk is JSON-encoded into
+   *   an SSE `data:` frame and client-disconnect cancels the source.
+   *   Pre-2.17.1 this crashed with `chunk must be a string or Buffer`.
+   */
   readonly streamResponse?: boolean;
+  /**
+   * INTERNAL — marker stamped by built-in presets (softDelete, tree, …)
+   * onto routes they emit. Read by the MCP collision detector
+   * (`createMcpServer.resolveToolCollisions`) to attribute the route
+   * source ("preset:softDelete vs user `actions.restore`") and to
+   * auto-namespace the preset side when a user-authored tool legitimately
+   * shadows it. Not part of the public surface — hosts must not set this.
+   *
+   * @internal
+   */
+  readonly _presetSource?: string;
+  /**
+   * Apply the resource's `fields` (field-level write permissions) to this
+   * custom route's request body.
+   *
+   * Default: `true` for body-bearing methods (POST/PUT/PATCH), `false`
+   * otherwise. Set to `false` to opt out — handler accepts the body as
+   * supplied with no field-write filtering. The resource-level
+   * `onFieldWriteDenied: 'reject' | 'strip'` setting governs how denials
+   * are surfaced.
+   *
+   * `raw: true` routes ALWAYS bypass this — they've opted out of the
+   * pipeline entirely.
+   */
+  readonly fieldWrite?: boolean;
   /**
    * Fastify route schema. Each slot (`body`, `querystring`, `params`,
    * `headers`, `response[status]`) accepts a plain JSON Schema object
@@ -2707,13 +2772,37 @@ interface ResourceConfig<TDoc = AnyRecord> {
   /**
    * Custom routes beyond CRUD. Presets also merge their routes here.
    *
-   * @example
+   * **Route handlers return `IControllerResponse<T>` shape** —
+   * `{ data, status?, meta?, headers? }`. Returning a bare value (array,
+   * 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
+   * arc's pipeline entirely (custom streaming, SSE, manual `reply.send()`).
+   *
+   * **Path collisions with auto-CRUD are detected at `defineResource()` time.**
+   * If you declare a route that shares method+path with an auto-CRUD op
+   * (e.g. `POST /` collides with `create`), validation throws with the
+   * exact `disabledRoutes` line to add. Use one of:
+   *   - `disabledRoutes: ['create']` — suppress the auto-CRUD op
+   *   - `crud: { list: true, get: true }` — opt-in allow-list (preferred)
+   *   - `disableDefaultRoutes: true` — turn off all auto-CRUD on this resource
+   *
+   * @example Custom route alongside default CRUD:
    * ```typescript
    * routes: [
    *   { method: 'GET', path: '/stats', handler: 'getStats', permissions: auth() },
    *   { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: auth() },
    * ]
    * ```
+   *
+   * @example Custom POST replacing the auto-CRUD `create`:
+   * ```typescript
+   * disabledRoutes: ['create'],
+   * routes: [
+   *   { method: 'POST', path: '/', handler: customCreate, permissions: requireAuth() },
+   * ]
+   * ```
    */
   routes?: RouteDefinition[];
   /**
@@ -2886,6 +2975,86 @@ interface ResourceConfig<TDoc = AnyRecord> {
   skipValidation?: boolean;
   /** Don't register in introspection */
   skipRegistry?: boolean;
+  /**
+   * Default `limit` value when the request omits `?limit=`. Default 20.
+   * Surfaced at the resource level (rather than only via a custom
+   * `queryParser`) so hosts can declare it inline next to the resource
+   * shape. Threads into both the auto-built controller's QueryResolver
+   * AND the OpenAPI listQuery schema.
+   *
+   * For "fetch all" reference data, prefer the `referenceData: true`
+   * shorthand below — it pins this AND `maxLimit` AND aggressive cache
+   * defaults in one declaration.
+   */
+  defaultLimit?: number;
+  /**
+   * URL-driven `limit` ceiling. Default 100. Requests with
+   * `?limit=N` above this cap fail validation with a 400 that names
+   * the cap (`Query parameter 'limit' must be <= 100 (got N)`,
+   * `meta.cap: 100` on the wire envelope) — 2.17.0+ surfaces the cap
+   * value programmatically so callers can self-correct.
+   */
+  maxLimit?: number;
+  /**
+   * Mark this resource as **reference data** — small, mostly-static rows
+   * (currencies, countries, plans, credentials, pipeline stages) that
+   * callers want to fetch all of at once and cache aggressively.
+   *
+   * Sets the following defaults (each only when the corresponding
+   * narrower flag is not explicitly set, so this stays composable):
+   *
+   *   - `crud: { list: true, get: true }` — read-only surface (reference
+   *     data is rarely mutated through the public API; mutate via
+   *     migrations / admin tools).
+   *   - `defaultLimit: 1000` — one request returns everything by default.
+   *   - `maxLimit: 1000` — same cap so explicit `?limit=` requests
+   *     don't have to know the resource is reference data.
+   *   - `cache: { staleTime: 300, gcTime: 600 }` — 5 min fresh / 10 min
+   *     GC window so reference data isn't refetched on every request
+   *     (values are seconds per `ResourceCacheConfig`). No-op without
+   *     `queryCachePlugin` — same contract as the manual `cache` field;
+   *     a first-mount diagnostic fires when the plugin is missing.
+   *
+   * Pre-2.17.0 hosts achieved this by sprinkling `defaultLimit: 1000` +
+   * a custom queryParser + a `cache:` block across every reference
+   * resource. The shorthand collapses that to one flag.
+   *
+   * @example
+   * ```ts
+   * defineResource({
+   *   name: 'credential-type',
+   *   adapter,
+   *   referenceData: true,
+   * });
+   * ```
+   */
+  referenceData?: boolean;
+  /**
+   * Shorthand for the "service resource" pattern — a resource that ships
+   * ONLY custom routes (no auto-CRUD, no adapter, no validation, no
+   * introspection registry entry). Setting `customRoutesOnly: true`
+   * is equivalent to the three-flag combo:
+   *
+   * ```ts
+   * { disableDefaultRoutes: true, skipValidation: true, skipRegistry: true }
+   * ```
+   *
+   * Each of those flags stays public — power users that need to opt OUT
+   * of one (e.g. `customRoutesOnly: true` + `skipRegistry: false` because
+   * a custom-routes-only resource still wants OpenAPI docs) can pass the
+   * narrow flag explicitly; explicit settings always win over the
+   * shorthand. The shorthand only fills in flags that were not set.
+   *
+   * @example
+   * ```ts
+   * defineResource({
+   *   name: 'health',
+   *   customRoutesOnly: true,
+   *   routes: [{ method: 'GET', path: '/ping', handler: () => ({ ok: true }) }],
+   * });
+   * ```
+   */
+  customRoutesOnly?: boolean;
   /**
    * Per-resource MCP opt-out.
    *
@@ -3029,7 +3198,16 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
   readonly updateMethod?: "PUT" | "PATCH" | "both";
   readonly pipe?: PipelineConfig;
   readonly fields?: FieldPermissionMap;
+  /**
+   * Policy for field-write denials — `'reject'` (default, secure) raises 403
+   * listing the denied fields; `'strip'` silently drops them. Honored by
+   * both `BodySanitizer` (auto-CRUD) and `buildFieldWritePreHandler`
+   * (custom routes) so the policy is consistent across all body-bearing
+   * routes for the resource.
+   */
+  readonly onFieldWriteDenied?: "reject" | "strip";
   readonly cache?: ResourceCacheConfig;
+  readonly referenceData: boolean;
   /**
    * Per-resource MCP opt-out. `false` keeps the resource out of every
    * `mcpPlugin` registration regardless of the plugin's `expose` /
@@ -3066,8 +3244,34 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
    * `buildResourcePlugin` so the host's configured logger owns the
    * output — the framework never speaks to `console.*` from `src/`
    * outside of the CLI.
+   *
+   * Prefer the public {@link warnings} getter for programmatic access
+   * (CI fail-on-warnings, lint integrations) — it returns a frozen
+   * snapshot so callers can't accidentally mutate the diagnostic list.
    */
   _diagnostics?: ResourceDiagnostic[];
+  /**
+   * Public view of {@link _diagnostics} for programmatic consumption.
+   *
+   * Returns the collected define-time diagnostics for this resource.
+   * Empty when the resource validated cleanly. Useful for CI gates that
+   * want to fail the build on any non-fatal warning:
+   *
+   * @example
+   * ```ts
+   * import { orderResource } from './resources/order.resource.js';
+   * if (orderResource.warnings.length > 0) {
+   *   for (const w of orderResource.warnings) console.error(w.message);
+   *   process.exit(1);
+   * }
+   * ```
+   *
+   * **Scope.** Covers define-time only — diagnostics emitted at
+   * first-mount (e.g. `cache.invalidateOn` without `queryCachePlugin`)
+   * surface through `fastify.log.warn` instead and are not collected
+   * here; they require a Fastify instance to detect.
+   */
+  get warnings(): readonly ResourceDiagnostic[];
   /**
    * Per-host idempotency guard used by `buildResourcePlugin` to
    * skip duplicate shared-state writes when the same resource is
@@ -3121,6 +3325,26 @@ declare class ResourceDefinition<TDoc = AnyRecord> {
  * `BaseController<TDoc extends AnyRecord>` actually requires it.
  * One internal boundary cast replaces N host-side casts.
  */
+/**
+ * Narrow overload: when the host passes an `actions: { ... }` literal, the
+ * returned `ResourceDefinition.actions` is typed as the exact captured map
+ * (not the wide `ActionsMap | undefined`). Without this overload, hosts that
+ * wrote `defineResource({ actions: { send: ..., receive: ... } })` saw
+ * `resource.actions` typed `ActionsMap | undefined` and got
+ * "'resource.actions' is possibly 'undefined'" on every `resource.actions.send`
+ * call. TS infers `TActions` from the object literal at the call site —
+ * no explicit generic needed.
+ */
+declare function defineResource<TDoc, TActions extends ActionsMap>(config: ResourceConfig<TDoc> & {
+  actions: TActions;
+}): ResourceDefinition<TDoc> & {
+  readonly actions: TActions;
+};
+/**
+ * Wide overload: no `actions` declared. `ResourceDefinition<TDoc>.actions`
+ * stays `ActionsMap | undefined` exactly as in pre-2.17.1 — no
+ * back-compat breakage for hosts that never touched actions.
+ */
 declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
 //#endregion
 //#region src/registry/ResourceRegistry.d.ts
@@ -3390,6 +3614,13 @@ interface CrudRouterOptions {
   schemaOptions?: RouteSchemaOptions;
   /** Field-level permissions (visibility, writability per role) */
   fields?: FieldPermissionMap;
+  /**
+   * Policy for handling fields the caller lacks write permission for.
+   * Auto-CRUD reads this via `BodySanitizer`; custom routes' field-write
+   * preHandler honors the same setting. Default: `'reject'` — silent
+   * stripping hides misconfigurations and real attacks.
+   */
+  onFieldWriteDenied?: "reject" | "strip";
   /** HTTP method for update routes. Default: 'PATCH' */
   updateMethod?: "PUT" | "PATCH" | "both";
   /**
@@ -3713,7 +3944,24 @@ interface RegistryEntry extends ResourceMetadata {
       field: string;
       maxRangeDays?: number;
     }; /** Whether the aggregation requires named filters — surfaced in docs. */
-    readonly requireFilters?: readonly string[]; /** MCP tool generation flag — `false` to skip, object for overrides. */
+    readonly requireFilters?: readonly string[];
+    /**
+     * Static result-row cap (no URL override). Mutually exclusive with
+     * `defaultLimit` / `maxLimit`. Surfaced so OpenAPI docs can mention
+     * the fixed cap in the description.
+     */
+    readonly limit?: number;
+    /**
+     * URL-driven default limit (caller may pass `?limit=N`). When set,
+     * OpenAPI docs render `?limit` as a query parameter with this
+     * default and `maxLimit` as the maximum.
+     */
+    readonly defaultLimit?: number;
+    /**
+     * URL-driven limit ceiling (only meaningful with `defaultLimit`).
+     * OpenAPI docs render this as the `maximum` constraint on `?limit`.
+     */
+    readonly maxLimit?: number; /** MCP tool generation flag — `false` to skip, object for overrides. */
     readonly mcp?: boolean | {
       readonly description?: string;
       readonly annotations?: Record<string, unknown>;