@classytic/arc 2.16.1 → 2.17.0

package/README.md

@@ -122,12 +122,31 @@ export default defineResource({
   actions: {
     approve: { handler: approveOrder, permissions: requireRoles(['admin']) },
   },
-  // mcp: false,    // opt out of MCP tool generation for this resource (2.16)
+  // mcp: false,    // opt out of MCP tool generation for this resource
 });
 ```
 
 Auto-generates: `GET /products`, `GET /products/:id`, `POST /products`, `PATCH /products/:id`, `DELETE /products/:id` + softDelete adds `GET /products/deleted`, `POST /products/:id/restore` + slugLookup adds `GET /products/by-slug/:slug` + custom routes + `POST /products/:id/action`.
 
+### Resource shorthands
+
+```typescript
+// Reference data — read-only list+get, fetch-all limits (1000), 5min/10min cache.
+defineResource({ name: 'currency', adapter, referenceData: true });
+
+// Service resource — custom routes only, no adapter, no auto-CRUD, no registry entry.
+defineResource({
+  name: 'health',
+  customRoutesOnly: true,
+  routes: [{ method: 'GET', path: '/ping', permissions: allowPublic(), handler: () => ({ ok: true }) }],
+});
+
+// Tune pagination caps inline (no custom queryParser needed).
+defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
+```
+
+`?limit=` violations respond 400 with a cap-aware envelope: `message: "Query parameter 'limit' must be <= 500 (got 800) (cap is 500)"` plus `meta: { field: 'limit', cap: 500 }` so callers can self-correct without scraping the message.
+
 ---
 
 ## Permissions
@@ -243,7 +262,8 @@ Tree-shake by importing only the subpath you need:
 | `@classytic/arc/plugins` | Health, request-id, versioning, tracing, response-cache |
 | `@classytic/arc/integrations/jobs` | BullMQ job dispatcher |
 | `@classytic/arc/integrations/websocket` | WebSocket integration |
-| `@classytic/arc/mcp` | Model Context Protocol tools |
+| `@classytic/arc/mcp` | Model Context Protocol tools + `createMcpAuthFromBetterAuthApiKey` (Better Auth API-key resolver), `resolveToolCollisions` |
+| `@classytic/arc/utils` | `pipeUIMessageStreamToReply`, `UI_MESSAGE_STREAM_HEADERS` (Vercel AI SDK → Fastify reply); errors, query parser, circuit breaker |
 | `@classytic/arc/testing` | `createTestApp`, `expectArc`, `TestAuthProvider`, `createTestFixtures` |
 | `@classytic/arc/types` | Type-only barrel (zero runtime cost) |
 

package/dist/{BaseController-Vk8I7C0x.mjs → BaseController-Dmeh4Y_y.mjs}

@@ -1,10 +1,9 @@
-import { h as SYSTEM_FIELDS, o as DEFAULT_TENANT_FIELD } from "./constants-TrJVIJl0.mjs";
+import { o as DEFAULT_TENANT_FIELD } from "./constants-TrJVIJl0.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { d as createDomainError, f as createError, i as NotFoundError, r as ForbiddenError } from "./errors-j4aJm1Wg.mjs";
-import { b as isElevated, c as getOrgId, n as PUBLIC_SCOPE, x as isMember } from "./types-Bi0r0vjG.mjs";
-import { N as simpleEqualityMatcher, _ as ArcQueryParser, r as scheduleBackground, t as getUserId } from "./utils-DPXZnZUx.mjs";
-import { d as applyFieldWritePermissions, p as resolveEffectiveRoles } from "./permissions-CTxMrreC.mjs";
-import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { b as isElevated, c as getOrgId } from "./types-Bi0r0vjG.mjs";
+import { I as simpleEqualityMatcher, b as ArcQueryParser, o as scheduleBackground, t as getUserId } from "./utils-CvD3glpM.mjs";
+import { w as BodySanitizer } from "./routerShared-nCyJGOKX.mjs";
 import { t as buildQueryKey } from "./keys-DopsCuyQ.mjs";
 //#region src/core/AccessControl.ts
 const log = arcLog("access-control");
@@ -241,47 +240,6 @@ var AccessControl = class {
 		return req.metadata;
 	}
 };
-var BodySanitizer = class {
-	schemaOptions;
-	onFieldWriteDenied;
-	constructor(config) {
-		this.schemaOptions = config.schemaOptions;
-		this.onFieldWriteDenied = config.onFieldWriteDenied ?? "reject";
-	}
-	/**
-	* Strip readonly and system-managed fields from request body.
-	* Prevents clients from overwriting _id, timestamps, __v, etc.
-	*
-	* Also applies field-level write permissions when the request has
-	* field permission metadata.
-	*/
-	sanitize(body, _operation, req, meta) {
-		let sanitized = { ...body };
-		for (const field of SYSTEM_FIELDS) delete sanitized[field];
-		const scopeForRules = req ? (meta ?? req.metadata)?._scope ?? PUBLIC_SCOPE : void 0;
-		const scopeIsElevated = scopeForRules ? isElevated(scopeForRules) : false;
-		const fieldRules = this.schemaOptions.fieldRules ?? {};
-		for (const [field, rules] of Object.entries(fieldRules)) {
-			const bypass = Boolean(rules.preserveForElevated) && scopeIsElevated;
-			if ((rules.systemManaged || rules.readonly) && !bypass) delete sanitized[field];
-			if (_operation === "update" && (rules.immutable || rules.immutableAfterCreate) && !bypass) delete sanitized[field];
-		}
-		if (req) {
-			const arcContext = meta ?? req.metadata;
-			const scope = arcContext?._scope ?? PUBLIC_SCOPE;
-			if (!isElevated(scope)) {
-				const fieldPerms = arcContext?.arc?.fields;
-				if (fieldPerms) {
-					const effectiveRoles = resolveEffectiveRoles(getUserRoles(req.user), isMember(scope) ? scope.orgRoles : []);
-					const { body: filtered, deniedFields } = applyFieldWritePermissions(sanitized, fieldPerms, effectiveRoles);
-					if (deniedFields.length > 0 && this.onFieldWriteDenied === "reject") throw new ForbiddenError(`Not permitted to write field${deniedFields.length === 1 ? "" : "s"}: ${deniedFields.join(", ")}`);
-					sanitized = filtered;
-				}
-			}
-		}
-		return sanitized;
-	}
-};
 //#endregion
 //#region src/core/fieldRulePredicates.ts
 /**
@@ -1531,4 +1489,4 @@ function TreeMixin(Base) {
 */
 var BaseController = class extends SoftDeleteMixin(TreeMixin(SlugMixin(BulkMixin(BaseCrudController)))) {};
 //#endregion
-export { BulkMixin as a, collectReadBlockedFields as c, AccessControl as d, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, BodySanitizer as u };
+export { BulkMixin as a, collectReadBlockedFields as c, SlugMixin as i, isFieldReadable as l, TreeMixin as n, BaseCrudController as o, SoftDeleteMixin as r, QueryResolver as s, BaseController as t, AccessControl as u };

package/dist/audit/index.mjs

@@ -351,7 +351,8 @@ function createNoopLogger() {
 		restore: noop,
 		custom: noop,
 		query: async () => [],
-		purge: async () => 0
+		purge: async () => 0,
+		_noop: true
 	};
 }
 var auditPlugin_default = fp(auditPlugin, {

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { Bt as AuthHelpers, Vt as AuthPluginOptions } from "../index-DBDgy6Hw.mjs";
+import { Bt as AuthHelpers, Vt as AuthPluginOptions } from "../index-C1JSBan-.mjs";
 import { c as PermissionCheck } from "../fields-DqZLp5d6.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-ClykOQqa.mjs";
 import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-DlmaHUAl.mjs";

package/dist/auth/index.mjs

@@ -1,6 +1,6 @@
 import { d as createDomainError, l as UnauthorizedError, p as isArcError, t as ArcError } from "../errors-j4aJm1Wg.mjs";
-import { _ as requireOrgMembership, v as requireOrgRole, x as requireTeamMembership } from "../permissions-CTxMrreC.mjs";
-import { n as normalizeRoles, t as getUserRoles } from "../types-D57iXYb8.mjs";
+import { _ as requireTeamMembership, m as requireOrgRole, p as requireOrgMembership } from "../permissions-B1Qy55fg.mjs";
+import { n as normalizeRoles, t as getUserRoles } from "../types-DV9WDfeg.mjs";
 import { n as extractBetterAuthOpenApi } from "../betterAuthOpenApi-ClWxaceA.mjs";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import fp from "fastify-plugin";

package/dist/auth/redis-session.mjs

@@ -1,5 +1,31 @@
+import sjson from "secure-json-parse";
 //#region src/auth/redis-session.ts
 /**
+* Redis Session Store for Arc
+*
+* Implements the SessionStore interface using Redis for distributed session storage.
+* Use this in multi-instance/clustered deployments where MemorySessionStore won't work.
+*
+* This is a SEPARATE subpath import — only loaded when explicitly used:
+*   import { RedisSessionStore } from '@classytic/arc/auth/redis';
+*
+* @example
+* ```typescript
+* import { createSessionManager } from '@classytic/arc/auth';
+* import { RedisSessionStore } from '@classytic/arc/auth/redis';
+* import Redis from 'ioredis';
+*
+* const redis = new Redis(process.env.REDIS_URL);
+*
+* const sessions = createSessionManager({
+*   store: new RedisSessionStore({ redis }),
+*   secret: process.env.SESSION_SECRET!,
+* });
+*
+* await fastify.register(sessions.plugin);
+* ```
+*/
+/**
 * Redis-backed session store for distributed deployments.
 *
 * Uses two key patterns:
@@ -22,7 +48,7 @@ var RedisSessionStore = class {
 		if (!raw) return null;
 		let session;
 		try {
-			session = JSON.parse(raw);
+			session = sjson.parse(raw);
 		} catch {
 			await this.delete(sessionId);
 			return null;
@@ -46,7 +72,7 @@ var RedisSessionStore = class {
 	async delete(sessionId) {
 		const raw = await this.redis.get(this.prefix + sessionId);
 		if (raw) try {
-			const session = JSON.parse(raw);
+			const session = sjson.parse(raw);
 			await this.redis.srem(this.userPrefix + session.userId, sessionId);
 		} catch {}
 		await this.redis.del(this.prefix + sessionId);

package/dist/cli/commands/describe.d.mts

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition, it as RateLimitConfig, mt as RouteSchemaOptions } from "../../index-DBDgy6Hw.mjs";
+import { V as ResourceDefinition, it as RateLimitConfig, mt as RouteSchemaOptions } from "../../index-C1JSBan-.mjs";
 
 //#region src/cli/commands/describe.d.ts
 interface DescribedResource {

package/dist/cli/commands/docs.mjs

@@ -1,4 +1,4 @@
-import { t as buildOpenApiSpec } from "../../openapi-BRnd3pT7.mjs";
+import { t as buildOpenApiSpec } from "../../openapi-DKDs9NfD.mjs";
 import { t as loadResourcesFromEntry } from "../../loadResourcesFromEntry-DCjYMgfC.mjs";
 import { dirname, resolve } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";

package/dist/core/index.d.mts

@@ -1,3 +1,3 @@
-import { $t as BaseController, At as AggregationRateLimit, B as defineResource, Cn as AccessControlConfig, Ct as AggMeasureShorthand, Dt as AggregationIndexHint, Et as AggregationDateRangeRequirement, Ot as AggregationMaterializedContext, Sn as AccessControl, St as AggMeasureInput, Tt as AggregationConfig, V as ResourceDefinition, an as SlugMixin, bn as BodySanitizer, cn as BaseControllerOptions, dn as ControllerConstructionOptions, en as SoftDeleteExt, fn as QueryResolver, in as SlugExt, jt as AggregationsMap, kt as AggregationMaterializedResult, ln as BaseCrudController, nn as TreeExt, on as BulkExt, pn as QueryResolverConfig, rn as TreeMixin, sn as BulkMixin, tn as SoftDeleteMixin, un as ControllerConfigurableOptions, wt as AggregationCacheConfig, xn as BodySanitizerConfig, yn as ListResult } from "../index-DBDgy6Hw.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, a as createRequestContext, b as DEFAULT_ID_FIELD, c as sendControllerResponse, d as getEntityQuery, f as defineResourceVariants, g as createPermissionMiddleware, h as createCrudRouter, i as createFastifyHandler, j as MAX_REGEX_LENGTH, k as HookPhase, l as getEntityId, m as defineAction, n as isFieldReadable, o as getControllerContext, p as DefineActionConfig, r as createCrudHandlers, s as getControllerScope, t as collectReadBlockedFields, u as getEntityIdField, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "../index-CC_pgZjY.mjs";
+import { $t as BaseController, At as AggregationRateLimit, B as defineResource, Cn as AccessControlConfig, Ct as AggMeasureShorthand, Dt as AggregationIndexHint, Et as AggregationDateRangeRequirement, Ot as AggregationMaterializedContext, Sn as AccessControl, St as AggMeasureInput, Tt as AggregationConfig, V as ResourceDefinition, an as SlugMixin, bn as BodySanitizer, cn as BaseControllerOptions, dn as ControllerConstructionOptions, en as SoftDeleteExt, fn as QueryResolver, in as SlugExt, jt as AggregationsMap, kt as AggregationMaterializedResult, ln as BaseCrudController, nn as TreeExt, on as BulkExt, pn as QueryResolverConfig, rn as TreeMixin, sn as BulkMixin, tn as SoftDeleteMixin, un as ControllerConfigurableOptions, wt as AggregationCacheConfig, xn as BodySanitizerConfig, yn as ListResult } from "../index-C1JSBan-.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, a as createRequestContext, b as DEFAULT_ID_FIELD, c as sendControllerResponse, d as getEntityQuery, f as defineResourceVariants, g as createPermissionMiddleware, h as createCrudRouter, i as createFastifyHandler, j as MAX_REGEX_LENGTH, k as HookPhase, l as getEntityId, m as defineAction, n as isFieldReadable, o as getControllerContext, p as DefineActionConfig, r as createCrudHandlers, s as getControllerScope, t as collectReadBlockedFields, u as getEntityIdField, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "../index-CruZir1o.mjs";
 export { AccessControl, AccessControlConfig, AggMeasureInput, AggMeasureShorthand, AggregationCacheConfig, AggregationConfig, AggregationDateRangeRequirement, AggregationIndexHint, AggregationMaterializedContext, AggregationMaterializedResult, AggregationRateLimit, AggregationsMap, BaseController, BaseControllerOptions, BaseCrudController, BodySanitizer, BodySanitizerConfig, BulkExt, BulkMixin, CRUD_OPERATIONS, ControllerConfigurableOptions, ControllerConstructionOptions, CrudOperation, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, DefineActionConfig, HOOK_OPERATIONS, HOOK_PHASES, HookOperation, HookPhase, ListResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MutationOperation, QueryResolver, QueryResolverConfig, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugExt, SlugMixin, SoftDeleteExt, SoftDeleteMixin, TreeExt, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAction, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 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 { a as BulkMixin, c as collectReadBlockedFields, d as AccessControl, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as BodySanitizer } from "../BaseController-Vk8I7C0x.mjs";
-import { _ as getControllerContext, g as createRequestContext, h as createFastifyHandler, m as createCrudHandlers, v as getControllerScope, y as sendControllerResponse } from "../routerShared-ClV4cCaa.mjs";
-import { a as defineResource, c as createCrudRouter, i as defineResourceVariants, l as createPermissionMiddleware, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as defineAction, t as getEntityId, u as defineAggregation } from "../core-wKeGXn38.mjs";
+import { a as BulkMixin, c as collectReadBlockedFields, i as SlugMixin, l as isFieldReadable, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, s as QueryResolver, t as BaseController, u as AccessControl } from "../BaseController-Dmeh4Y_y.mjs";
+import { S as sendControllerResponse, _ as createCrudHandlers, b as getControllerContext, v as createFastifyHandler, w as BodySanitizer, x as getControllerScope, y as createRequestContext } from "../routerShared-nCyJGOKX.mjs";
+import { a as defineResource, c as createCrudRouter, i as defineResourceVariants, l as createPermissionMiddleware, n as getEntityIdField, o as ResourceDefinition, r as getEntityQuery, s as defineAction, t as getEntityId, u as defineAggregation } from "../core-DYJvu7aI.mjs";
 export { AccessControl, BaseController, BaseCrudController, BodySanitizer, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, QueryResolver, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, collectReadBlockedFields, createCrudHandlers, createCrudRouter, createFastifyHandler, createPermissionMiddleware, createRequestContext, defineAction, defineAggregation, defineResource, defineResourceVariants, getControllerContext, getControllerScope, getEntityId, getEntityIdField, getEntityQuery, isFieldReadable, sendControllerResponse };

package/dist/{core-wKeGXn38.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-DPXZnZUx.mjs";
-import { t as BaseController } from "./BaseController-Vk8I7C0x.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-ClV4cCaa.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-eiOFtnC3.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-C4unhBnV.mjs"), import("./validate-DFIP2VrM.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-eiOFtnC3.mjs → createActionRouter-BHUMb1-y.mjs}

@@ -1,7 +1,7 @@
 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-ClV4cCaa.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({
@@ -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-C4unhBnV.mjs → createAggregationRouter-BYVvhfc5.mjs}

@@ -1,5 +1,5 @@
 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-ClV4cCaa.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