@classytic/arc 2.16.1 → 2.17.1

package/dist/{createApp-DdPBtmzp.mjs → createApp-CzCEEsEm.mjs}

@@ -337,7 +337,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-Dci0AYLT.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-6mfTLBC-.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -347,7 +347,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-DNPzqaTT.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-wQejMBT3.mjs").then((n) => n.r);
 	const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 	await fastify.register(errorHandlerPlugin, errorOpts);
 	trackPlugin("arc-error-handler", errorOpts);

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-DBDgy6Hw.mjs";
+import { p as RegistryEntry } from "../index-C1JSBan-.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-ClykOQqa.mjs";
 import { FastifyPluginAsync } from "fastify";
 

package/dist/docs/index.mjs

@@ -1,5 +1,5 @@
-import { t as getUserRoles } from "../types-D57iXYb8.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-BRnd3pT7.mjs";
+import { t as getUserRoles } from "../types-DV9WDfeg.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-DKDs9NfD.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{elevation-Dci0AYLT.mjs → elevation-6mfTLBC-.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
 import fp from "fastify-plugin";
 //#region src/scope/elevation.ts
 var elevation_exports = /* @__PURE__ */ __exportAll({

package/dist/{errorHandler-DNPzqaTT.mjs → errorHandler-wQejMBT3.mjs}

@@ -39,13 +39,48 @@ function fastifyValidationDetails(error) {
 	return (error.validation ?? []).map((v) => {
 		const missingProperty = v.params?.missingProperty;
 		const path = v.instancePath?.replace(/^\//, "") || (typeof missingProperty === "string" ? missingProperty : void 0);
+		const meta = {};
+		if (v.keyword === "maximum" || v.keyword === "minimum" || v.keyword === "exclusiveMaximum" || v.keyword === "exclusiveMinimum") {
+			const bound = v.params?.limit;
+			if (typeof bound === "number") meta.bound = bound;
+		}
+		if (v.keyword === "enum") {
+			const allowed = v.params?.allowedValues;
+			if (Array.isArray(allowed)) meta.allowedValues = allowed;
+		}
 		return {
 			...path ? { path } : {},
 			code: v.keyword ?? "invalid",
-			message: v.message || "Invalid value"
+			message: v.message || "Invalid value",
+			...Object.keys(meta).length > 0 ? { meta } : {}
 		};
 	});
 }
+/**
+* Hoist a context-aware message + machine-readable `meta` for the
+* common pagination-cap miss (`?limit=200` against a maxLimit=100
+* resource). Pre-2.17.0 the wire envelope carried "Validation failed"
+* + a detail with the AJV string; hosts had to grep the detail's
+* message to surface the cap. Now the top-level message is
+* "limit must be <= 100 (got 200)" AND `meta.cap` / `meta.received`
+* are stamped on the contract for programmatic callers.
+*/
+function describePaginationCap(error, details) {
+	if (!Array.isArray(error.validation) || error.validation.length === 0) return null;
+	const v = error.validation.find((entry) => (entry.instancePath === "/limit" || entry.instancePath === "/page") && (entry.keyword === "maximum" || entry.keyword === "minimum"));
+	if (!v) return null;
+	const field = v.instancePath === "/limit" ? "limit" : "page";
+	const bound = v.params?.limit;
+	if (typeof bound !== "number") return null;
+	const detail = details.find((d) => d.path === field);
+	return {
+		message: detail?.message ? `Query parameter '${field}' ${detail.message} (cap is ${bound})` : `Query parameter '${field}' violates bound ${bound}`,
+		meta: {
+			field,
+			cap: bound
+		}
+	};
+}
 /** Map Mongoose `ValidationError.errors` → canonical `ErrorDetail[]`. */
 function mongooseValidationDetails(errors) {
 	return Object.entries(errors).map(([field, e]) => ({
@@ -116,13 +151,19 @@ function classify(error, ctx) {
 	const fastifyErr = error;
 	if (Array.isArray(fastifyErr.validation)) {
 		const arcInternalCode = typeof fastifyErr.code === "string" && fastifyErr.code.startsWith("arc.") ? fastifyErr.code : void 0;
-		const message = arcInternalCode ? error.message || "Validation failed" : "Validation failed";
+		const details = fastifyValidationDetails(fastifyErr);
+		const paginationCap = arcInternalCode ? null : describePaginationCap(fastifyErr, details);
+		const message = paginationCap?.message ?? (arcInternalCode ? error.message || "Validation failed" : "Validation failed");
+		const mergedMeta = {
+			...fastifyErr.meta ?? {},
+			...paginationCap?.meta ?? {}
+		};
 		return {
 			code: arcInternalCode ?? "arc.validation_error",
 			message,
 			status: typeof fastifyErr.statusCode === "number" ? fastifyErr.statusCode : 400,
-			details: fastifyValidationDetails(fastifyErr),
-			...fastifyErr.meta ? { meta: fastifyErr.meta } : {}
+			details,
+			...Object.keys(mergedMeta).length > 0 ? { meta: mergedMeta } : {}
 		};
 	}
 	if (typeof fastifyErr.statusCode === "number") return {

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.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 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-Dw--SyTq.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

package/dist/factory/index.mjs

@@ -1,5 +1,5 @@
 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-DdPBtmzp.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
 /**

package/dist/{fastify-augmentation-CJm0vh-l.d.mts → fastify-augmentation-7LIR0nDv.d.mts}

@@ -1,4 +1,4 @@
-import { An as HookSystem, z as ResourceRegistry } from "./index-DBDgy6Hw.mjs";
+import { An as HookSystem, z as ResourceRegistry } from "./index-C1JSBan-.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-ClykOQqa.mjs";
 import { FastifyPluginAsync } from "fastify";
 

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-DBDgy6Hw.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.mjs

@@ -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/{index-DBDgy6Hw.d.mts → index-C1JSBan-.d.mts}

@@ -2458,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
@@ -2941,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.
    *
@@ -3084,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` /
@@ -3121,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
@@ -3176,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
@@ -3445,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";
   /**

package/dist/{index-CC_pgZjY.d.mts → index-CruZir1o.d.mts}

@@ -1,4 +1,4 @@
-import { C as RequestContext, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, bt as IRequestContext, ft as RouteMcpConfig, mt as RouteSchemaOptions, q as CrudController, st as ResourceConfig, vt as IController, yt as IControllerResponse } from "./index-DBDgy6Hw.mjs";
+import { C as RequestContext, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, bt as IRequestContext, ft as RouteMcpConfig, mt as RouteSchemaOptions, q as CrudController, st as ResourceConfig, vt as IController, yt as IControllerResponse } from "./index-C1JSBan-.mjs";
 import { i as RequestScope } from "./types-CfapW2t8.mjs";
 import { c as PermissionCheck } from "./fields-DqZLp5d6.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { $t as BaseController, A as RequestIdOptions, At as AggregationRateLimit, B as defineResource, C as RequestContext, Ct as AggMeasureShorthand, D as HealthCheck, Dt as AggregationIndexHint, E as GracefulShutdownOptions, Et as AggregationDateRangeRequirement, F as FastifyWithDecorators, J as CrudRouteKey, Jt as ArcRequest, Kt as AnyRecord, L as RequestWithExtras, N as FastifyRequestExtras, O as HealthOptions, Ot as AggregationMaterializedContext, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, St as AggMeasureInput, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, Vt as AuthPluginOptions, X as EventDefinition, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, _n as ArcListResult, a as InferAdapterDoc, an as SlugMixin, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, d as PaginationResult, dn as ControllerConstructionOptions, en as SoftDeleteExt, f as IntrospectionData, g as ArcInternalMetadata, gn as ArcGetResult, gt as ControllerLike, h as ResourceMetadata, hn as ArcDeleteResult, i as ValidationResult, in as SlugExt, it as RateLimitConfig, jt as AggregationsMap, k as IntrospectionPluginOptions, kt as AggregationMaterializedResult, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, mn as ArcCreateResult, mt as RouteSchemaOptions, n as ConfigError, nn as TreeExt, o as InferDocType, on as BulkExt, p as RegistryEntry, q as CrudController, qt as ApiResponse, r as ValidateOptions, rn as TreeMixin, rt as PresetResult, s as InferResourceDoc, sn as BulkMixin, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteMixin, tt as PresetFunction, u as TypedResourceConfig, un as ControllerConfigurableOptions, vn as ArcUpdateResult, vt as IController, w as ServiceContext, wt as AggregationCacheConfig, xt as RouteHandler, y as OwnershipCheck, yn as ListResult, yt as IControllerResponse } from "./index-DBDgy6Hw.mjs";
+import { $t as BaseController, A as RequestIdOptions, At as AggregationRateLimit, B as defineResource, C as RequestContext, Ct as AggMeasureShorthand, D as HealthCheck, Dt as AggregationIndexHint, E as GracefulShutdownOptions, Et as AggregationDateRangeRequirement, F as FastifyWithDecorators, J as CrudRouteKey, Jt as ArcRequest, Kt as AnyRecord, L as RequestWithExtras, N as FastifyRequestExtras, O as HealthOptions, Ot as AggregationMaterializedContext, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, St as AggMeasureInput, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, Vt as AuthPluginOptions, X as EventDefinition, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, _n as ArcListResult, a as InferAdapterDoc, an as SlugMixin, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, d as PaginationResult, dn as ControllerConstructionOptions, en as SoftDeleteExt, f as IntrospectionData, g as ArcInternalMetadata, gn as ArcGetResult, gt as ControllerLike, h as ResourceMetadata, hn as ArcDeleteResult, i as ValidationResult, in as SlugExt, it as RateLimitConfig, jt as AggregationsMap, k as IntrospectionPluginOptions, kt as AggregationMaterializedResult, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, mn as ArcCreateResult, mt as RouteSchemaOptions, n as ConfigError, nn as TreeExt, o as InferDocType, on as BulkExt, p as RegistryEntry, q as CrudController, qt as ApiResponse, r as ValidateOptions, rn as TreeMixin, rt as PresetResult, s as InferResourceDoc, sn as BulkMixin, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteMixin, tt as PresetFunction, u as TypedResourceConfig, un as ControllerConfigurableOptions, vn as ArcUpdateResult, vt as IController, w as ServiceContext, wt as AggregationCacheConfig, xt as RouteHandler, y as OwnershipCheck, yn as ListResult, yt as IControllerResponse } from "./index-C1JSBan-.mjs";
 import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, t as FieldPermission, u as PermissionResult } from "./fields-DqZLp5d6.mjs";
-import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-CC_pgZjY.mjs";
+import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-CruZir1o.mjs";
 import { A as requireRoles, C as allOf, E as denyAll, M as when, O as requireAuth, S as createOrgPermissions, T as anyOf, a as presets_d_exports, c as readOnly, d as requireOrgRole, f as requireScopeContext, i as ownerWithAdminBypass, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "./index-3L-adFJO.mjs";
 import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-4ZloYFvm.mjs";
 

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-TrJVIJl0.mjs";
 import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-j4aJm1Wg.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-Vk8I7C0x.mjs";
-import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf, T as denyAll, _ as requireOrgMembership, a as presets_exports, b as requireServiceScope, c as readOnly, d as applyFieldWritePermissions, f as fields, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, m as createDynamicPermissionMatrix, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as applyFieldReadPermissions, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "./permissions-CTxMrreC.mjs";
-import { v as getControllerScope } from "./routerShared-ClV4cCaa.mjs";
-import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-wKeGXn38.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-CgHomZ4d.mjs";
+import { C as requireAuth, D as when, M as applyFieldWritePermissions, N as fields, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyFieldReadPermissions, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "./permissions-B1Qy55fg.mjs";
+import { x as getControllerScope } from "./routerShared-nCyJGOKX.mjs";
+import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-D8tpQ4ZL.mjs";
 //#region src/index.ts
-const version = "2.16.1";
+const version = "2.17.1";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAction, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
 import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-BJ0w-3Dt.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-BD0BCdf6.mjs";
+import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-CoMjNmkF.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/jobs.d.mts

@@ -39,6 +39,14 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
   deadLetterQueue?: string;
   /** Repeat schedule — cron or interval. Requires explicit timezone for cron. */
   repeat?: JobRepeatOptions;
+  /**
+   * Arc-level semaphore: max simultaneous handler executions for this job type.
+   * Jobs that dequeue while all slots are full are held (state stays `active`)
+   * and appear as `throttled: true` in `GET /jobs/:id/status`.
+   * Distinct from BullMQ `concurrency` — use this when the constraint is a
+   * downstream resource (AI model rate limit, DB connection pool, external API).
+   */
+  maxConcurrent?: number;
 }
 interface JobMeta {
   jobId: string;
@@ -59,6 +67,27 @@ interface JobDispatchOptions {
   /** One-shot repeat override at dispatch time. Usually prefer `JobDefinition.repeat`. */
   repeat?: JobRepeatOptions;
 }
+/** Point-in-time snapshot of a single job. */
+interface JobStatus {
+  id: string;
+  /** Registered job name (= queue name). */
+  name: string;
+  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown";
+  /** Progress reported by the handler via BullMQ `job.updateProgress()`. */
+  progress: number | Record<string, unknown>;
+  /** True when the job is dequeued by a worker but blocked on a `maxConcurrent` semaphore slot. */
+  throttled?: boolean;
+  /** Unix ms when the job was enqueued. */
+  timestamp?: number;
+  /** Unix ms when processing started. */
+  processedOn?: number;
+  /** Unix ms when the job finished (completed or failed). */
+  finishedOn?: number;
+  /** Failure message when `state === 'failed'`. */
+  failedReason?: string;
+  /** Handler return value when `state === 'completed'` (only present if removeOnComplete hasn't cleared the job). */
+  returnValue?: unknown;
+}
 interface JobsPluginOptions {
   /** Redis connection options (passed to BullMQ) */
   connection: {
@@ -91,6 +120,12 @@ interface JobDispatcher {
   }>;
   getQueue(name: string): unknown | null;
   getStats(): Promise<Record<string, QueueStats>>;
+  /**
+   * Fetch a point-in-time status snapshot for a job by its ID.
+   * Searches across all registered queues.
+   * Returns `null` if the job doesn't exist or has been removed by retention policy.
+   */
+  getStatus(jobId: string): Promise<JobStatus | null>;
   close(): Promise<void>;
 }
 interface QueueStats {
@@ -122,4 +157,4 @@ declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDe
  */
 declare const jobsPlugin: FastifyPluginAsync<JobsPluginOptions>;
 //#endregion
-export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };
+export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobStatus, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };