@classytic/arc 2.16.0 → 2.17.0

package/dist/{core-DBJ_j6rX.mjs → core-DYJvu7aI.mjs}

@@ -1,11 +1,11 @@
 import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-TrJVIJl0.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { A as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-DC5ycPfr.mjs";
-import { t as BaseController } from "./BaseController-DlCCTIxJ.mjs";
-import { t as applyPresets } from "./presets-C9BE6WaZ.mjs";
+import { N as assertValidConfig, f as getDefaultCrudSchemas, i as pipeUIMessageStreamToReply, r as isReadableStream } from "./utils-CvD3glpM.mjs";
+import { t as BaseController } from "./BaseController-Dmeh4Y_y.mjs";
+import { t as applyPresets } from "./presets-BYbPobbF.mjs";
 import { n as convertRouteSchema, t as convertOpenApiSchemas } from "./schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "./typeGuards-BzkXkvVv.mjs";
-import { b as buildRequestScopeProjection, c as buildPreHandlerChain, d as resolveRoutePreHandlers, f as resolveRouterPluginMw, g as createRequestContext, h as createFastifyHandler, i as buildAuthMiddleware, l as buildRateLimitConfig, m as createCrudHandlers, o as buildCrudPermissionMw, p as selectPluginMw, r as buildArcDecorator, s as buildPipelineHandler, u as resolvePipelineSteps } from "./routerShared-CZV5aabX.mjs";
+import { C as buildRequestScopeProjection, _ as createCrudHandlers, c as buildPipelineHandler, d as methodCarriesBody, f as resolvePipelineSteps, g as tryRegisterRoute, h as selectPluginMw, i as buildAuthMiddleware, l as buildPreHandlerChain, m as resolveRouterPluginMw, o as buildCrudPermissionMw, p as resolveRoutePreHandlers, r as buildArcDecorator, s as buildFieldWritePreHandler, u as buildRateLimitConfig, v as createFastifyHandler, y as createRequestContext } from "./routerShared-nCyJGOKX.mjs";
 import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
 import { t as resolveActionPermission } from "./actionPermissions-Bjmvn7Eb.mjs";
 //#region src/core/aggregation/defineAggregation.ts
@@ -60,7 +60,7 @@ function defineAggregation(config) {
 * `wrapHandler` is derived inline from `!route.raw`.
 */
 function createCustomRoutes(fastify, routes, controller, options) {
-	const { tag, resourceName, arcDecorator, rateLimitConfig, pluginMw, pipeline, routeGuards, tenantScopeMw } = options;
+	const { tag, resourceName, arcDecorator, rateLimitConfig, pluginMw, pipeline, routeGuards, tenantScopeMw, fieldPermissions, onFieldWriteDenied } = options;
 	for (const route of routes) {
 		const routeWithRefs = route;
 		const hasHandler = route.handler !== void 0;
@@ -103,6 +103,10 @@ function createCustomRoutes(fastify, routes, controller, options) {
 			if (!tenantScopeMw || tenantScopeMw.length === 0) throw new Error(`Route ${route.method} ${route.path}: \`tenantScope: true\` requires a multi-tenant preset. Add \`multiTenantPreset()\` (or \`flexibleMultiTenantPreset()\`) to the resource's \`presets\`, or remove the \`tenantScope\` flag from this route.`);
 			customPreHandlers.unshift(...tenantScopeMw);
 		}
+		if (route.raw !== true && route.fieldWrite !== false && methodCarriesBody(route.method)) {
+			const fieldWriteMw = buildFieldWritePreHandler(fieldPermissions, onFieldWriteDenied);
+			if (fieldWriteMw) customPreHandlers.push(fieldWriteMw);
+		}
 		const preHandler = buildPreHandlerChain({
 			preAuth: route.preAuth ?? [],
 			arcDecorator,
@@ -113,7 +117,7 @@ function createCustomRoutes(fastify, routes, controller, options) {
 			customMws: customPreHandlers
 		});
 		const isStream = route.streamResponse === true;
-		fastify.route({
+		tryRegisterRoute(fastify, {
 			method: route.method,
 			url: route.path,
 			schema,
@@ -122,9 +126,14 @@ function createCustomRoutes(fastify, routes, controller, options) {
 				reply.raw.setHeader("Content-Type", "text/event-stream");
 				reply.raw.setHeader("Cache-Control", "no-cache");
 				reply.raw.setHeader("Connection", "keep-alive");
-				return handler(request, reply);
+				const result = await handler(request, reply);
+				if (isReadableStream(result)) await pipeUIMessageStreamToReply(reply, result);
+				return result;
 			} : handler,
 			...rateLimitConfig ? { config: rateLimitConfig } : {}
+		}, {
+			resourceName,
+			op: opName
 		});
 	}
 }
@@ -138,7 +147,7 @@ function createCustomRoutes(fastify, routes, controller, options) {
 * @param options    - Router configuration
 */
 function createCrudRouter(fastify, controller, options = {}) {
-	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, routeGuards = [], routes: customRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, updateMethod = DEFAULT_UPDATE_METHOD, idField } = options;
+	const { tag = "Resource", schemas = {}, permissions = {}, middlewares = {}, routeGuards = [], routes: customRoutes = [], disableDefaultRoutes = false, disabledRoutes = [], resourceName = "unknown", schemaOptions, rateLimit, pipe: pipeline, fields: fieldPermissions, onFieldWriteDenied, updateMethod = DEFAULT_UPDATE_METHOD, idField } = options;
 	const rateLimitConfig = buildRateLimitConfig(rateLimit);
 	const resourceHasQueryCache = fastify.hasDecorator("queryCache") && controller && typeof controller._cacheConfig !== "undefined" && controller._cacheConfig !== void 0;
 	const pluginMw = resolveRouterPluginMw(fastify, Boolean(resourceHasQueryCache));
@@ -229,7 +238,7 @@ function createCrudRouter(fastify, controller, options = {}) {
 			const methodsToRegister = spec.op === "update" ? updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod] : [spec.method];
 			for (const method of methodsToRegister) {
 				const summary = spec.op === "update" ? `${method === "PUT" ? "Replace" : "Update"} ${tag}` : spec.summary;
-				fastify.route({
+				tryRegisterRoute(fastify, {
 					method,
 					url: spec.url,
 					schema: buildSchema({
@@ -240,6 +249,9 @@ function createCrudRouter(fastify, controller, options = {}) {
 					preHandler: preHandler.length > 0 ? preHandler : void 0,
 					handler: handlers[spec.op],
 					...rateLimitConfig ? { config: rateLimitConfig } : {}
+				}, {
+					resourceName,
+					op: spec.op
 				});
 			}
 		}
@@ -252,7 +264,9 @@ function createCrudRouter(fastify, controller, options = {}) {
 		pluginMw,
 		pipeline,
 		routeGuards,
-		tenantScopeMw
+		tenantScopeMw,
+		fieldPermissions,
+		onFieldWriteDenied
 	});
 }
 function buildCrudHandlers(ctrl, pipeline, resourceName) {
@@ -442,11 +456,14 @@ function buildBaseController(resolvedConfig, adapter, repository) {
 		const limitProp = qp.getQuerySchema()?.properties?.limit;
 		if (limitProp?.maximum) maxLimitFromParser = limitProp.maximum;
 	}
+	const resourceConfigMaxLimit = resolvedConfig.maxLimit;
+	const resourceConfigDefaultLimit = resolvedConfig.defaultLimit;
 	return new BaseController(repository, {
 		resourceName: resolvedConfig.name,
 		schemaOptions: resolvedConfig.schemaOptions,
 		queryParser: qp,
-		maxLimit: maxLimitFromParser,
+		maxLimit: resourceConfigMaxLimit ?? maxLimitFromParser,
+		...resourceConfigDefaultLimit !== void 0 ? { defaultLimit: resourceConfigDefaultLimit } : {},
 		tenantField: resolvedConfig.tenantField,
 		idField: resolvedConfig.idField,
 		...resolvedConfig.defaultSort !== void 0 ? { defaultSort: resolvedConfig.defaultSort } : {},
@@ -1033,10 +1050,21 @@ function buildResourcePlugin(resource) {
 			handler: hook.handler,
 			priority: hook.priority
 		});
-		if (isFirstMount && resource.cache?.invalidateOn && fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
+		if (isFirstMount && resource.cache?.invalidateOn) if (fastify.registerCacheInvalidationRule) for (const [pattern, tags] of Object.entries(resource.cache.invalidateOn)) fastify.registerCacheInvalidationRule({
 			pattern,
 			tags
 		});
+		else fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`cache.invalidateOn\` but \`queryCachePlugin\` is not registered. Cache-invalidation rules are silently ignored. Either register the plugin (\`await fastify.register(queryCachePlugin, ...)\`) or remove the \`cache.invalidateOn\` config to clean up the resource definition.`);
+		if (isFirstMount && resource.audit) {
+			if (!(fastify.hasDecorator("audit") && typeof fastify.audit?.create === "function" && fastify.audit?._noop !== true)) fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares \`audit: ${JSON.stringify(resource.audit)}\` but \`auditPlugin\` is not registered (or is registered with a noop logger). Audit events for this resource will NOT be recorded. Either register \`auditPlugin\` (\`await fastify.register(auditPlugin, { store: ... })\`) or remove the \`audit\` flag from the resource definition.`);
+		}
+		if (isFirstMount && resource.events && Object.keys(resource.events).length > 0) {
+			const eventsDecor = fastify.events;
+			if (!(eventsDecor != null && typeof eventsDecor.publish === "function")) {
+				const eventNames = Object.keys(resource.events).join(", ");
+				fastify.log?.warn?.(`[Arc] Resource '${resource.name}' declares events (${eventNames}) but \`eventPlugin\` is not registered. The events will silently NOT be emitted on CRUD mutations. Either register the plugin (\`await fastify.register(eventPlugin, { transport: ... })\`) or remove the \`events\` declaration from the resource.`);
+			}
+		}
 		await fastify.register(async (instance) => {
 			const typedInstance = instance;
 			let schemas = buildGeneratedCrudSchemas(resource._registryMeta?.openApiSchemas, resource.customSchemas);
@@ -1061,10 +1089,11 @@ function buildResourcePlugin(resource) {
 				updateMethod: resource.updateMethod,
 				pipe: resource.pipe,
 				fields: resource.fields,
+				onFieldWriteDenied: resource.onFieldWriteDenied,
 				idField: resource.idField
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-DUpN3Dd1.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-BHUMb1-y.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1078,7 +1107,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-Dq-TUCuY.mjs"), import("./validate-By96rH0r.mjs").then((n) => n.i)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-BYVvhfc5.mjs"), import("./validate-DFIP2VrM.mjs").then((n) => n.i)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1142,7 +1171,16 @@ var ResourceDefinition = class {
 	updateMethod;
 	pipe;
 	fields;
+	/**
+	* 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.
+	*/
+	onFieldWriteDenied;
 	cache;
+	referenceData;
 	/**
 	* Per-resource MCP opt-out. `false` keeps the resource out of every
 	* `mcpPlugin` registration regardless of the plugin's `expose` /
@@ -1174,9 +1212,37 @@ var ResourceDefinition = class {
 	* `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;
 	/**
+	* 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() {
+		return this._diagnostics ?? [];
+	}
+	/**
 	* Per-host idempotency guard used by `buildResourcePlugin` to
 	* skip duplicate shared-state writes when the same resource is
 	* mounted at multiple prefixes (`/v1`, `/v2`). See the plugin
@@ -1209,8 +1275,10 @@ var ResourceDefinition = class {
 		this.updateMethod = config.updateMethod;
 		this.pipe = config.pipe;
 		this.fields = config.fields;
+		this.onFieldWriteDenied = config.onFieldWriteDenied;
 		this.cache = config.cache;
 		this.mcp = config.mcp !== false;
+		this.referenceData = config.referenceData === true;
 		this.tenantField = config.tenantField;
 		this.onTenantDelete = config.onTenantDelete;
 		this.resolvedTenantPurge = resolveTenantPurge({
@@ -1364,6 +1432,7 @@ function resolveOpenApiSchemas(resolvedConfig) {
 		openApiSchemas = stripSystemManagedFromBodyRequired(openApiSchemas, resolvedConfig.schemaOptions);
 		openApiSchemas = cleanLegacyObjectIdParams(openApiSchemas, resolvedConfig.idField);
 		openApiSchemas = layerQueryParserListQuery(openApiSchemas, resolvedConfig.queryParser);
+		openApiSchemas = applyResourcePaginationCaps(openApiSchemas, resolvedConfig);
 		openApiSchemas = mergeUserOpenApiOverrides(openApiSchemas, resolvedConfig.openApiSchemas);
 		if (openApiSchemas) openApiSchemas = convertOpenApiSchemas(openApiSchemas);
 		return {
@@ -1435,6 +1504,45 @@ function layerQueryParserListQuery(openApiSchemas, queryParser) {
 	};
 }
 /**
+* Apply resource-level `defaultLimit` / `maxLimit` (2.17.0) onto the
+* listQuery schema. Resource-level caps win over both the framework
+* default and the parser-derived value because they're the most-explicit
+* declaration — a host that wrote `defaultLimit: 1000` on the resource
+* means "this resource specifically returns up to 1000", regardless of
+* what the parser's default would have been. The `referenceData: true`
+* shorthand lifts both to 1000 so reference-data resources don't need
+* a custom queryParser just to get the caps right.
+*
+* Bootstraps a minimal listQuery slot when none exists (no queryParser
+* registered, no adapter-generated schema) so the AJV layer still gets
+* a `maximum:` and surfaces the cap in the 400 envelope via
+* `errorHandler.describePaginationCap()` instead of producing the
+* generic "Bad Request" we ate pre-2.17.0.
+*/
+function applyResourcePaginationCaps(openApiSchemas, resolvedConfig) {
+	const cfg = resolvedConfig;
+	if (cfg.defaultLimit === void 0 && cfg.maxLimit === void 0) return openApiSchemas;
+	const existing = openApiSchemas?.listQuery;
+	const existingProps = existing?.properties ?? {};
+	const patchedLimit = { ...existingProps.limit ?? {
+		type: "integer",
+		minimum: 1
+	} };
+	if (cfg.maxLimit !== void 0) patchedLimit.maximum = cfg.maxLimit;
+	if (cfg.defaultLimit !== void 0) patchedLimit.default = cfg.defaultLimit;
+	return {
+		...openApiSchemas,
+		listQuery: {
+			type: "object",
+			...existing ?? {},
+			properties: {
+				...existingProps,
+				limit: patchedLimit
+			}
+		}
+	};
+}
+/**
 * Apply per-resource `openApiSchemas` overrides on top of the kit's
 * generated schemas. Shallow merge by slot — users who want field-level
 * surgery should compose at the schema-options layer before this point.
@@ -1547,24 +1655,8 @@ function validateActionsShape(config) {
 }
 //#endregion
 //#region src/core/defineResource.ts
-/**
-* `TDoc` is **unconstrained** at this layer. The previous `TDoc
-* extends AnyRecord` bound leaked out of `BaseController`'s
-* mixin-composition requirement into every host's adapter boundary:
-* Mongoose's `HydratedDocument<T>`, Prisma's generated row types,
-* and any domain interface without an explicit index signature all
-* failed to satisfy `Record<string, unknown>` even though at runtime
-* they ARE string-keyed objects. Hosts were forced to cast at every
-* adapter (`as RepositoryLike<Record<string, unknown>>`) — a type
-* escape with no runtime purpose, since arc's pipeline only reads
-* known envelope fields.
-*
-* The cast moved inside `resolveOrAutoCreateController` where
-* `BaseController<TDoc extends AnyRecord>` actually requires it.
-* One internal boundary cast replaces N host-side casts.
-*/
 function defineResource(config) {
-	const normalisedConfig = resolveCrudAllowList(config);
+	const normalisedConfig = resolveCrudAllowList(expandCustomRoutesOnly(expandReferenceData(config)));
 	let diagnostics = [];
 	if (!normalisedConfig.skipValidation) diagnostics = validateDefineResourceConfig(normalisedConfig);
 	const repository = normalisedConfig.adapter?.repository;
@@ -1606,6 +1698,57 @@ function defineResource(config) {
 * doesn't false-positive "Data adapter required when CRUD routes are
 * enabled" on a host that explicitly opted CRUD out.
 */
+/**
+* Expand the `referenceData: true` shorthand. Reference data is the
+* recurring "small static catalogue" shape (currencies, plans,
+* pipeline stages, credential types) where callers want "fetch all"
+* semantics and aggressive caching — pre-2.17.0 hosts hand-wired
+* `crud` + `defaultLimit` + `maxLimit` + `cache` on every such
+* resource. The shorthand pins canonical defaults; explicit narrow
+* settings always win so a host can opt INTO mutations
+* (`referenceData: true, crud: { list: true, get: true, create: true }`)
+* or override the cache window without giving up the read-only +
+* fetch-all defaults.
+*/
+function expandReferenceData(config) {
+	if (config.referenceData !== true) return config;
+	return {
+		...config,
+		crud: config.crud ?? {
+			list: true,
+			get: true
+		},
+		defaultLimit: config.defaultLimit ?? 1e3,
+		maxLimit: config.maxLimit ?? 1e3,
+		cache: config.cache ?? {
+			staleTime: 300,
+			gcTime: 600
+		}
+	};
+}
+/**
+* Expand the `customRoutesOnly: true` shorthand into its three primitive
+* flags. The shorthand exists because hosts wiring a "service resource"
+* (custom routes only, no adapter, no auto-CRUD) had to remember to set
+* `disableDefaultRoutes` + `skipValidation` + `skipRegistry` in lockstep —
+* forgetting any one of them produced confusing errors ("controller
+* required when CRUD routes are enabled" for a resource that ships none).
+*
+* Explicit narrow settings always win — the shorthand only fills in
+* flags that were not set so power users can opt back into a specific
+* primitive (`customRoutesOnly: true, skipRegistry: false` keeps OpenAPI
+* docs while still skipping CRUD + validation).
+*/
+function expandCustomRoutesOnly(config) {
+	if (config.customRoutesOnly !== true) return config;
+	return {
+		...config,
+		customRoutesOnly: void 0,
+		disableDefaultRoutes: config.disableDefaultRoutes ?? true,
+		skipValidation: config.skipValidation ?? true,
+		skipRegistry: config.skipRegistry ?? true
+	};
+}
 function resolveCrudAllowList(config) {
 	const { crud, disabledRoutes: legacyDisabled, disableDefaultRoutes: legacyDisableAll } = config;
 	if (crud === void 0) return config;

package/dist/{createActionRouter-DUpN3Dd1.mjs → createActionRouter-BHUMb1-y.mjs}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import "./constants-TrJVIJl0.mjs";
 import { f as createError } from "./errors-j4aJm1Wg.mjs";
-import { a as buildAuthMiddlewareForPermissions, c as buildPreHandlerChain, f as resolveRouterPluginMw, l as buildRateLimitConfig, n as buildActionPipelineHandler, p as selectPluginMw, r as buildArcDecorator, t as buildActionPermissionMw, u as resolvePipelineSteps, y as sendControllerResponse } from "./routerShared-CZV5aabX.mjs";
-import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-Ctc89DSn.mjs";
+import { S as sendControllerResponse, a as buildAuthMiddlewareForPermissions, f as resolvePipelineSteps, g as tryRegisterRoute, h as selectPluginMw, l as buildPreHandlerChain, m as resolveRouterPluginMw, n as buildActionPipelineHandler, r as buildArcDecorator, t as buildActionPermissionMw, u as buildRateLimitConfig } from "./routerShared-nCyJGOKX.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-DAOvBWgT.mjs";
 //#region src/core/createActionRouter.ts
 var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 	buildActionBodySchema: () => buildActionBodySchema,
@@ -114,7 +114,7 @@ function createActionRouter(fastify, config) {
 			pluginMw: selectPluginMw("POST", pluginMw),
 			routeGuards
 		})];
-		fastify.route({
+		tryRegisterRoute(fastify, {
 			method: "POST",
 			url: urlPath,
 			schema: routeSchema,
@@ -152,6 +152,9 @@ function createActionRouter(fastify, config) {
 					throw createError(statusCode, err.message || `Failed to execute '${action}' action`, { code: errorCode });
 				}
 			}
+		}, {
+			resourceName,
+			op: `action${urlPath}`
 		});
 		fastify.log.debug({
 			actions: actionSubset,

package/dist/{createAggregationRouter-Dq-TUCuY.mjs → createAggregationRouter-BYVvhfc5.mjs}

@@ -1,7 +1,7 @@
 import { f as createError, l as UnauthorizedError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
-import { c as buildPreHandlerChain, f as resolveRouterPluginMw, i as buildAuthMiddleware, l as buildRateLimitConfig, p as selectPluginMw, r as buildArcDecorator } from "./routerShared-CZV5aabX.mjs";
-import { r as validateAggregations } from "./validate-By96rH0r.mjs";
-import { t as buildAggregationHandler } from "./buildHandler-BZX6zzDM.mjs";
+import { h as selectPluginMw, i as buildAuthMiddleware, l as buildPreHandlerChain, m as resolveRouterPluginMw, r as buildArcDecorator, u as buildRateLimitConfig } from "./routerShared-nCyJGOKX.mjs";
+import { r as validateAggregations } from "./validate-DFIP2VrM.mjs";
+import { t as buildAggregationHandler } from "./buildHandler-C_SkBNF3.mjs";
 //#region src/core/aggregation/createAggregationRouter.ts
 /**
 * Register one Fastify route per aggregation. No-op when the map is

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

@@ -202,7 +202,7 @@ async function registerArcCore(fastify, config, trackPlugin) {
 	await fastify.register(arcCorePlugin, { emitEvents: config.arcPlugins?.emitEvents !== false });
 	trackPlugin("arc-core");
 	if (config.arcPlugins?.events !== false) {
-		const { default: eventPlugin } = await import("./eventPlugin-C2cGqtRO.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-CnJCUyM0.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -239,7 +239,7 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-graceful-shutdown");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-TeHE8G-v.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-8MfrrUYU.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.caching === true ? {} : config.arcPlugins.caching;
 		await fastify.register(cachingPlugin, opts);
 		trackPlugin("arc-caching", opts);
@@ -256,19 +256,19 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 	}
 	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
 	else {
-		const { default: ssePlugin } = await import("./sse-BY6sTy4P.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("./sse-jh5OqFjR.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.sse === true ? {} : config.arcPlugins.sse;
 		await fastify.register(ssePlugin, opts);
 		trackPlugin("arc-sse", opts);
 	}
 	if (config.arcPlugins?.metrics) {
-		const { default: metricsPlugin } = await import("./metrics-TuOmguhi.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-B-PU4-Yu.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.metrics === true ? {} : config.arcPlugins.metrics;
 		await fastify.register(metricsPlugin, opts);
 		trackPlugin("arc-metrics", opts);
 	}
 	if (config.arcPlugins?.versioning) {
-		const { default: versioningPlugin } = await import("./versioning-B6mimogM.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-CuIwUQZ2.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -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-DpoXQHZ9.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);
@@ -448,7 +448,7 @@ async function registerResources(fastify, config) {
 	let discoveryPath;
 	let discoveryYieldedZero = false;
 	if (resolvedResources === void 0 && config.resourceDir) {
-		const { loadResources } = await import("./loadResources-ChQEj8ih.mjs").then((n) => n.n);
+		const { loadResources } = await import("./loadResources-fol6JuvW.mjs").then((n) => n.n);
 		const { resolve, dirname } = await import("node:path");
 		const { fileURLToPath } = await import("node:url");
 		const rawDir = config.resourceDir;
@@ -874,7 +874,7 @@ async function createApp(options) {
 	await registerErrorHandler(fastify, config, trackPlugin);
 	await registerResources(fastify, config);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-C-gD32oF.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-boS5Rx26.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
 	if (config.serializeBigInt) {

package/dist/{defineEvent-DRwY0fYm.mjs → defineEvent-NPKUJRt8.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { n as createEvent } from "./EventTransport-Hxvv5QQz.mjs";
+import { n as createEvent } from "./EventTransport-ClEDfiMS.mjs";
 //#region src/events/defineEvent.ts
 /**
 * defineEvent — Typed Event Definitions with Optional Schema Validation

package/dist/docs/index.d.mts

@@ -1,5 +1,5 @@
-import { p as RegistryEntry } from "../index-CkW0flkU.mjs";
-import { t as ExternalOpenApiPaths } from "../externalPaths-DFg-2KTp.mjs";
+import { p as RegistryEntry } from "../index-C1JSBan-.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-ClykOQqa.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/docs/openapi/types.d.ts

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-34T9yNwd.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-DpoXQHZ9.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/{eventPlugin-C2cGqtRO.mjs → eventPlugin-CnJCUyM0.mjs}

@@ -2,7 +2,7 @@ import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { d as createDomainError } from "./errors-j4aJm1Wg.mjs";
 import { t as requestContext } from "./requestContext-SSaaTgW8.mjs";
-import { n as createEvent, t as MemoryEventTransport } from "./EventTransport-Hxvv5QQz.mjs";
+import { n as createEvent, t as MemoryEventTransport } from "./EventTransport-ClEDfiMS.mjs";
 import fp from "fastify-plugin";
 //#region src/events/retry.ts
 /**

package/dist/{eventPlugin-CtHC_av1.d.mts → eventPlugin-DjEx_J3j.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";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/events/defineEvent.d.ts

package/dist/events/index.d.mts

@@ -1,7 +1,7 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-C-2oAHtw.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-CtHC_av1.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions, t as DeadLetteredEvent } from "../EventTransport-B1GFiYUy.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-DjEx_J3j.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-DT-YjzrB.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-BuiAS3aE.mjs";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 
 //#region src/events/eventTypes.d.ts

package/dist/events/index.mjs

@@ -1,7 +1,7 @@
-import { t as MemoryEventTransport } from "../EventTransport-Hxvv5QQz.mjs";
-import { n as defineEvent, t as createEventRegistry } from "../defineEvent-DRwY0fYm.mjs";
-import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-C2cGqtRO.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-B0sunfZZ.mjs";
+import { t as MemoryEventTransport } from "../EventTransport-ClEDfiMS.mjs";
+import { n as defineEvent, t as createEventRegistry } from "../defineEvent-NPKUJRt8.mjs";
+import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-CnJCUyM0.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-5JgaxieH.mjs";
 import { and, anyOf, eq, lte, ne, or } from "@classytic/repo-core/filter";
 import { update } from "@classytic/repo-core/update";
 //#region src/events/eventTypes.ts
@@ -716,7 +716,7 @@ function wrapWithSchema(definition, handler, options = {}) {
 		if (validate && definition.schema) result = validate(definition.schema, event.payload);
 		else if (registry) result = registry.validate(definition.name, event.payload, eventVersion);
 		else if (definition.schema) {
-			const { createEventRegistry } = await import("../defineEvent-DRwY0fYm.mjs").then((n) => n.r);
+			const { createEventRegistry } = await import("../defineEvent-NPKUJRt8.mjs").then((n) => n.r);
 			const adhoc = createEventRegistry();
 			adhoc.register(definition);
 			result = adhoc.validate(definition.name, event.payload);

package/dist/events/transports/redis-stream-entry.d.mts

@@ -1,2 +1,2 @@
-import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-DT-YjzrB.mjs";
+import { n as RedisStreamTransport, r as RedisStreamTransportOptions, t as RedisStreamLike } from "../../redis-stream-BuiAS3aE.mjs";
 export { type RedisStreamLike, RedisStreamTransport, type RedisStreamTransportOptions };