@classytic/arc 2.16.0 → 2.17.0

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { Kt as AnyRecord, S as QueryParserInterface, Zt as UserLike, b as ParsedQuery, et as OpenApiSchemas, st as ResourceConfig } from "../index-CkW0flkU.mjs";
-import { n as ErrorMapper } from "../errorHandler-mHuyWzZE.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-C1lX_jlm.mjs";
+import { Kt as AnyRecord, S as QueryParserInterface, Zt as UserLike, b as ParsedQuery, et as OpenApiSchemas, st as ResourceConfig } from "../index-C1JSBan-.mjs";
+import { n as ErrorMapper } from "../errorHandler-DuqTqeqn.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-4ZloYFvm.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
@@ -1144,7 +1144,8 @@ declare function simpleEqualityMatcher(item: unknown, filters: Record<string, un
  * State Machine Utility
  *
  * Pure utility for validating state transitions in workflow systems.
- * Zero dependencies, framework-agnostic.
+ * Zero runtime dependencies — usable from any layer of arc (controllers,
+ * hooks, pipeline steps, tests).
  *
  * @example
  * const orderState = createStateMachine('Order', {
@@ -1254,6 +1255,83 @@ declare function createStateMachine(name: string, transitions?: TransitionConfig
   trackHistory?: boolean;
 }): StateMachine;
 //#endregion
+//#region src/utils/streaming.d.ts
+/**
+ * Canonical SSE headers for AI-SDK-style UI message streams.
+ *
+ * `x-vercel-ai-ui-message-stream: v1` is the marker the Vercel AI SDK
+ * client uses to detect the v1 UI message stream protocol (vs the older
+ * data stream protocol). Surfaced as a constant so hosts don't memorise it.
+ */
+declare const UI_MESSAGE_STREAM_HEADERS: {
+  readonly "content-type": "text/event-stream";
+  readonly "cache-control": "no-cache";
+  readonly connection: "keep-alive";
+  readonly "x-accel-buffering": "no";
+  readonly "x-vercel-ai-ui-message-stream": "v1";
+};
+interface PipeUIMessageStreamOptions {
+  /**
+   * Headers to send before the first chunk. Defaults to
+   * {@link UI_MESSAGE_STREAM_HEADERS}. Pass a fully-replaced bag when
+   * you need a different protocol marker; merge manually otherwise —
+   * the helper does not deep-merge to keep behaviour predictable.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Abort signal — when fired, the helper cancels the source stream and
+   * ends the reply early. `request.raw` `close` is wired automatically
+   * when {@link pipeUIMessageStreamToReply} sees `reply.request`, so most
+   * hosts never pass this directly.
+   */
+  signal?: AbortSignal;
+  /**
+   * Custom chunk serialiser. Default: `JSON.stringify(chunk)`. Override
+   * when chunks are already strings (rare — most AI SDK transforms emit
+   * objects) or when you need pretty-print / type-prefix shenanigans.
+   */
+  serialize?: (chunk: unknown) => string;
+}
+/**
+ * Pipe a Web `ReadableStream` of JSON-serialisable chunks (typically
+ * `UIMessageChunk` from the Vercel AI SDK) into a Fastify reply as an
+ * SSE event stream.
+ *
+ * - Sets {@link UI_MESSAGE_STREAM_HEADERS} (or the caller's override)
+ *   before the first chunk.
+ * - Writes each chunk as `data: ${JSON.stringify(chunk)}\n\n`.
+ * - Cancels the source and closes the reply when the client disconnects.
+ * - Resolves once the stream is fully written.
+ *
+ * @example
+ * ```ts
+ * import { pipeUIMessageStreamToReply } from '@classytic/arc/utils';
+ * import { streamText, convertToUIMessageStream } from 'ai';
+ *
+ * defineResource({
+ *   name: 'chat',
+ *   routes: [{
+ *     method: 'POST', path: '/', streamResponse: true,
+ *     handler: async (req, reply) => {
+ *       const result = streamText({ model, messages: req.body.messages });
+ *       await pipeUIMessageStreamToReply(reply, result.toUIMessageStream());
+ *     },
+ *   }],
+ * });
+ * ```
+ */
+declare function pipeUIMessageStreamToReply(reply: FastifyReply, stream: ReadableStream<unknown>, options?: PipeUIMessageStreamOptions): Promise<void>;
+/**
+ * Heuristic — does this value look like a Web `ReadableStream`?
+ *
+ * Used by `createCrudRouter` to auto-pipe `streamResponse: true` handlers
+ * that return a UI message stream instead of writing to `reply.raw`
+ * directly. Cross-realm safe (no `instanceof`) — checks the duck shape
+ * the Streams spec mandates: `getReader`, `cancel`, and the `locked`
+ * getter.
+ */
+declare function isReadableStream(value: unknown): value is ReadableStream<unknown>;
+//#endregion
 //#region src/utils/typeGuards.d.ts
 interface EventsDecorator {
   publish: <T>(type: string, payload: T, meta?: Record<string, unknown>) => Promise<void>;
@@ -1283,4 +1361,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
  */
 declare function getUserId(user: UserLike | null | undefined): string | undefined;
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/utils/index.mjs

@@ -1,5 +1,5 @@
 import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-j4aJm1Wg.mjs";
-import { A as assertValidConfig, C as withCompensation, D as CircuitState, E as CircuitBreakerRegistry, M as validateResourceConfig, N as simpleEqualityMatcher, O as createCircuitBreaker, S as defineCompensation, T as CircuitBreakerError, _ as ArcQueryParser, a as bareListResponse, b as defineGuard, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as formatValidationErrors, k as createCircuitBreakerRegistry, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as CircuitBreaker, x as defineErrorMapper, y as handleRaw } from "../utils-DC5ycPfr.mjs";
+import { A as CircuitState, C as defineGuard, D as CircuitBreaker, E as withCompensation, F as validateResourceConfig, I as simpleEqualityMatcher, M as createCircuitBreakerRegistry, N as assertValidConfig, O as CircuitBreakerError, P as formatValidationErrors, S as handleRaw, T as defineCompensation, _ as paginationSchema, a as createStateMachine, b as ArcQueryParser, c as bareListResponse, d as errorDetailSchema, f as getDefaultCrudSchemas, g as offsetListResponse, h as listResponse, i as pipeUIMessageStreamToReply, j as createCircuitBreaker, k as CircuitBreakerRegistry, l as deleteResponse, m as keysetListResponse, n as UI_MESSAGE_STREAM_HEADERS, o as scheduleBackground, p as getListQueryParams, r as isReadableStream, s as aggregateListResponse, t as getUserId, u as errorContractSchema, v as queryParams, w as defineErrorMapper, x as createQueryParser, y as responses } from "../utils-CvD3glpM.mjs";
 import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-De34B1ZG.mjs";
 import { t as hasEvents } from "../typeGuards-BzkXkvVv.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/{utils-DC5ycPfr.mjs → utils-CvD3glpM.mjs}

@@ -1,7 +1,7 @@
 import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-TrJVIJl0.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-j4aJm1Wg.mjs";
-import { r as getAvailablePresets } from "./presets-C9BE6WaZ.mjs";
+import { r as getAvailablePresets } from "./presets-BYbPobbF.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
 //#region src/utils/simpleEqualityMatcher.ts
 /**
@@ -142,7 +142,10 @@ function validateResourceConfig(config, options = {}) {
 			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
 		});
 	}
-	if (config.routes) validateRoutes(config.routes, errors);
+	if (config.routes) {
+		validateRoutes(config.routes, errors);
+		validateRouteCrudCollisions(config, errors);
+	}
 	return {
 		valid: errors.length === 0,
 		errors,
@@ -210,6 +213,71 @@ function validatePresetOptions(preset, warnings) {
 		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
 	});
 }
+/**
+* Detect collisions between user-declared `routes:` entries and the
+* auto-CRUD route table that `createCrudRouter` will register.
+*
+* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
+* `create` boots fine through `defineResource()` and only blows up at
+* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
+* That error doesn't mention `disabledRoutes` and doesn't distinguish
+* "you collided with auto-CRUD" from "you collided with yourself" — so
+* the consumer has to grep arc's source to discover the fix.
+*
+* We surface the fix in the error message, naming the conflicting op
+* and the literal line to add.
+*
+* Honored config:
+*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
+*   - `disabledRoutes: ['create']` → that op's path is free for custom use
+*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
+*/
+function validateRouteCrudCollisions(config, errors) {
+	if (config.disableDefaultRoutes) return;
+	if (!config.routes || config.routes.length === 0) return;
+	const updateMethod = config.updateMethod ?? "PATCH";
+	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const crudTable = [
+		{
+			op: "list",
+			method: "GET",
+			path: "/"
+		},
+		{
+			op: "get",
+			method: "GET",
+			path: "/:id"
+		},
+		{
+			op: "create",
+			method: "POST",
+			path: "/"
+		},
+		...updateMethods.map((m) => ({
+			op: "update",
+			method: m,
+			path: "/:id"
+		})),
+		{
+			op: "delete",
+			method: "DELETE",
+			path: "/:id"
+		}
+	];
+	for (const [i, route] of config.routes.entries()) {
+		if (!route.method || !route.path) continue;
+		for (const crud of crudTable) {
+			if (disabled.has(crud.op)) continue;
+			if (route.method !== crud.method || route.path !== crud.path) continue;
+			errors.push({
+				field: `routes[${i}]`,
+				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
+				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
+			});
+		}
+	}
+}
 function validateRoutes(routes, errors) {
 	const validMethods = [
 		"GET",
@@ -1602,6 +1670,103 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
+//#region src/utils/streaming.ts
+/**
+* Canonical SSE headers for AI-SDK-style UI message streams.
+*
+* `x-vercel-ai-ui-message-stream: v1` is the marker the Vercel AI SDK
+* client uses to detect the v1 UI message stream protocol (vs the older
+* data stream protocol). Surfaced as a constant so hosts don't memorise it.
+*/
+const UI_MESSAGE_STREAM_HEADERS = {
+	"content-type": "text/event-stream",
+	"cache-control": "no-cache",
+	connection: "keep-alive",
+	"x-accel-buffering": "no",
+	"x-vercel-ai-ui-message-stream": "v1"
+};
+/**
+* Pipe a Web `ReadableStream` of JSON-serialisable chunks (typically
+* `UIMessageChunk` from the Vercel AI SDK) into a Fastify reply as an
+* SSE event stream.
+*
+* - Sets {@link UI_MESSAGE_STREAM_HEADERS} (or the caller's override)
+*   before the first chunk.
+* - Writes each chunk as `data: ${JSON.stringify(chunk)}\n\n`.
+* - Cancels the source and closes the reply when the client disconnects.
+* - Resolves once the stream is fully written.
+*
+* @example
+* ```ts
+* import { pipeUIMessageStreamToReply } from '@classytic/arc/utils';
+* import { streamText, convertToUIMessageStream } from 'ai';
+*
+* defineResource({
+*   name: 'chat',
+*   routes: [{
+*     method: 'POST', path: '/', streamResponse: true,
+*     handler: async (req, reply) => {
+*       const result = streamText({ model, messages: req.body.messages });
+*       await pipeUIMessageStreamToReply(reply, result.toUIMessageStream());
+*     },
+*   }],
+* });
+* ```
+*/
+async function pipeUIMessageStreamToReply(reply, stream, options = {}) {
+	const serialize = options.serialize ?? defaultSerialize;
+	const raw = reply.raw;
+	if (!raw.headersSent) {
+		const headers = options.headers ?? UI_MESSAGE_STREAM_HEADERS;
+		for (const [key, value] of Object.entries(headers)) raw.setHeader(key, value);
+		raw.statusCode = reply.statusCode;
+		raw.flushHeaders?.();
+	}
+	const reader = stream.getReader();
+	const onAbort = () => {
+		reader.cancel().catch(() => {});
+	};
+	reply.request.raw.once("close", onAbort);
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			if (!raw.write(`data: ${serialize(value)}\n\n`)) await once(raw, "drain");
+		}
+	} catch (err) {
+		if (!raw.writableEnded) raw.write(`event: error\ndata: ${JSON.stringify({ message: String(err) })}\n\n`);
+		throw err;
+	} finally {
+		reply.request.raw.removeListener("close", onAbort);
+		options.signal?.removeEventListener("abort", onAbort);
+		if (!raw.writableEnded) raw.end();
+		reader.releaseLock?.();
+	}
+}
+function defaultSerialize(chunk) {
+	return typeof chunk === "string" ? chunk : JSON.stringify(chunk);
+}
+function once(emitter, event) {
+	return new Promise((resolve) => {
+		emitter.once(event, () => resolve());
+	});
+}
+/**
+* Heuristic — does this value look like a Web `ReadableStream`?
+*
+* Used by `createCrudRouter` to auto-pipe `streamResponse: true` handlers
+* that return a UI message stream instead of writing to `reply.raw`
+* directly. Cross-realm safe (no `instanceof`) — checks the duck shape
+* the Streams spec mandates: `getReader`, `cancel`, and the `locked`
+* getter.
+*/
+function isReadableStream(value) {
+	if (value === null || typeof value !== "object") return false;
+	const obj = value;
+	return typeof obj.getReader === "function" && typeof obj.cancel === "function" && typeof obj.locked === "boolean";
+}
+//#endregion
 //#region src/utils/userHelpers.ts
 /**
 * Extract a user ID from a user object. Accepts `id` or `_id` — returns
@@ -1620,4 +1785,4 @@ function getUserId(user) {
 	return id ? String(id) : void 0;
 }
 //#endregion
-export { assertValidConfig as A, withCompensation as C, CircuitState as D, CircuitBreakerRegistry as E, validateResourceConfig as M, simpleEqualityMatcher as N, createCircuitBreaker as O, defineCompensation as S, CircuitBreakerError as T, ArcQueryParser as _, bareListResponse as a, defineGuard as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, formatValidationErrors as j, createCircuitBreakerRegistry as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, CircuitBreaker as w, defineErrorMapper as x, handleRaw as y };
+export { CircuitState as A, defineGuard as C, CircuitBreaker as D, withCompensation as E, validateResourceConfig as F, simpleEqualityMatcher as I, createCircuitBreakerRegistry as M, assertValidConfig as N, CircuitBreakerError as O, formatValidationErrors as P, handleRaw as S, defineCompensation as T, paginationSchema as _, createStateMachine as a, ArcQueryParser as b, bareListResponse as c, errorDetailSchema$1 as d, getDefaultCrudSchemas as f, offsetListResponse as g, listResponse as h, pipeUIMessageStreamToReply as i, createCircuitBreaker as j, CircuitBreakerRegistry as k, deleteResponse as l, keysetListResponse as m, UI_MESSAGE_STREAM_HEADERS as n, scheduleBackground as o, getListQueryParams as p, isReadableStream as r, aggregateListResponse as s, getUserId as t, errorContractSchema$1 as u, queryParams as v, defineErrorMapper as w, createQueryParser as x, responses as y };

package/dist/{validate-By96rH0r.mjs → validate-DFIP2VrM.mjs}

@@ -11,6 +11,13 @@ var ArcAggregationConfigError = class extends Error {
 	name = "ArcAggregationConfigError";
 };
 /**
+* Framework cap on URL-driven aggregation limits when the host opts
+* in to `defaultLimit` without explicit `maxLimit`. Set to the same
+* order of magnitude as a "large dashboard page" — bigger than every
+* realistic grouped tile, smaller than "we returned the whole table."
+*/
+const AGG_FRAMEWORK_MAX_LIMIT = 1e3;
+/**
 * Validate + normalize all aggregations on a resource. Throws on first
 * misconfig with the offending aggregation name in the message — hosts
 * see exactly which entry needs fixing.
@@ -53,6 +60,8 @@ function validateAggregations(resourceName, aggregations, schemaOptions) {
 			bucketAliases
 		});
 		if (config.topN) validateTopNConfig(resourceName, name, config.topN, groupBy, measures, bucketAliases);
+		validateLimitConfig(resourceName, name, config);
+		const limitPolicy = resolveLimitPolicy(config);
 		out.push({
 			name,
 			base: config,
@@ -65,13 +74,47 @@ function validateAggregations(resourceName, aggregations, schemaOptions) {
 				having: config.having,
 				sort: config.sort,
 				limit: config.limit,
-				topN: config.topN
+				topN: config.topN,
+				...limitPolicy ? { limitPolicy } : {}
 			}
 		});
 	}
 	return out;
 }
 /**
+* Validate `limit` / `defaultLimit` / `maxLimit` triad. Throws on
+* misconfig at boot — boundary value, hosts see exactly what to fix.
+*/
+function validateLimitConfig(resourceName, aggName, config) {
+	const hasStatic = config.limit !== void 0;
+	const hasDynamic = config.defaultLimit !== void 0;
+	if (hasStatic && hasDynamic) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" sets both \`limit\` (static cap) and \`defaultLimit\` (URL-driven cap). Pick one — static \`limit\` ignores the URL; \`defaultLimit\` reads \`?limit=N\` and caps it at \`maxLimit\`.`);
+	if (config.maxLimit !== void 0 && !hasDynamic) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" sets \`maxLimit\` without \`defaultLimit\`. \`maxLimit\` only applies to URL-driven limits — set \`defaultLimit\` or remove \`maxLimit\`.`);
+	if (hasStatic) {
+		if (!Number.isInteger(config.limit) || config.limit <= 0) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" \`limit\` must be a positive integer — got ${String(config.limit)}.`);
+	}
+	if (hasDynamic) {
+		if (!Number.isInteger(config.defaultLimit) || config.defaultLimit <= 0) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" \`defaultLimit\` must be a positive integer — got ${String(config.defaultLimit)}.`);
+		if (config.maxLimit !== void 0) {
+			if (!Number.isInteger(config.maxLimit) || config.maxLimit <= 0) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" \`maxLimit\` must be a positive integer — got ${String(config.maxLimit)}.`);
+			if (config.maxLimit < config.defaultLimit) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggName}" \`maxLimit\` (${config.maxLimit}) is less than \`defaultLimit\` (${config.defaultLimit}). The ceiling must be ≥ the default.`);
+		}
+	}
+}
+/**
+* Resolve the URL-driven limit policy into a concrete `{ default, max }`
+* pair. Returns `undefined` when the host uses the static `limit` form
+* (or no limit at all) — the request handler reads the absence to know
+* "do not parse `?limit=N` from the URL."
+*/
+function resolveLimitPolicy(config) {
+	if (config.defaultLimit === void 0) return void 0;
+	return {
+		defaultLimit: config.defaultLimit,
+		maxLimit: config.maxLimit ?? AGG_FRAMEWORK_MAX_LIMIT
+	};
+}
+/**
 * Adapter feature-detect for `aggregate()`. Called at boot when the
 * repository instance is available. Returns `true` when the kit ships
 * `aggregate`; `false` when missing.
@@ -83,14 +126,33 @@ function adapterSupportsAggregate(repo) {
 	if (!repo || typeof repo !== "object") return false;
 	return typeof repo.aggregate === "function";
 }
+/**
+* Resolve the effective per-request `limit` — three cases:
+*
+*   1. Host declared static `limit` → URL `?limit` ignored, static wins.
+*   2. Host declared `defaultLimit` → parse `?limit=N`, cap at
+*      `maxLimit`, fall back to default on absent / invalid input.
+*   3. Host declared neither → returns `undefined` (no limit applied,
+*      preserves pre-2.16.1 behavior).
+*/
+function resolveAggRequestLimit(normalized, query) {
+	const policy = normalized.compiled.limitPolicy;
+	if (!policy) return normalized.compiled.limit;
+	const raw = query["limit"];
+	if (raw === void 0 || raw === "") return policy.defaultLimit;
+	const parsed = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return policy.defaultLimit;
+	return Math.min(Math.floor(parsed), policy.maxLimit);
+}
 /** Compile to canonical `AggRequest` for `repo.aggregate()` at request time. */
-function compileAggRequest(normalized, callerFilter, tenantOptions) {
+function compileAggRequest(normalized, callerFilter, tenantOptions, query) {
 	const filter = {
 		...normalized.compiled.filter ?? {},
 		...callerFilter
 	};
 	const executionHints = buildExecutionHints(normalized.base);
 	const cache = buildCacheOptions(normalized.base);
+	const limit = query ? resolveAggRequestLimit(normalized, query) : normalized.compiled.limit;
 	return {
 		measures: normalized.compiled.measures,
 		...Object.keys(filter).length > 0 ? { filter } : {},
@@ -99,7 +161,7 @@ function compileAggRequest(normalized, callerFilter, tenantOptions) {
 		...normalized.compiled.dateBuckets ? { dateBuckets: normalized.compiled.dateBuckets } : {},
 		...normalized.compiled.having ? { having: normalized.compiled.having } : {},
 		...normalized.compiled.sort ? { sort: normalized.compiled.sort } : {},
-		...normalized.compiled.limit !== void 0 ? { limit: normalized.compiled.limit } : {},
+		...limit !== void 0 ? { limit } : {},
 		...normalized.compiled.topN ? { topN: normalized.compiled.topN } : {},
 		...executionHints ? { executionHints } : {},
 		...cache ? { cache } : {}

package/dist/{versioning-ZwX9tmbS.d.mts → versioning-5H4930tj.d.mts}

@@ -1,4 +1,4 @@
-import { n as DomainEvent } from "./EventTransport-C-2oAHtw.mjs";
+import { n as DomainEvent } from "./EventTransport-B1GFiYUy.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/plugins/health.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -231,7 +231,7 @@
     "push": "classytic-push",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
     "release": "npm run push -- main && npm run release:tag && npm publish",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:main && npm run smoke"
   },
   "engines": {
     "node": ">=22"
@@ -352,7 +352,7 @@
     "@classytic/mongokit": "^3.14.0",
     "@classytic/primitives": "^0.6.0",
     "@classytic/repo-core": "^0.5.0",
-    "@classytic/sqlitekit": "^0.4.0",
+    "@classytic/sqlitekit": "^0.5.0",
     "@classytic/streamline": "^2.3.3",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",

package/skills/arc/SKILL.md

@@ -134,6 +134,23 @@ export default defineResource({
 
 **Auto-generated:** `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Presets add their own routes (see table below).
 
+**Resource shorthands:**
+
+```typescript
+// "fetch-all" reference data — read-only crud (list+get), defaultLimit/maxLimit=1000,
+// cache { staleTime: 300, gcTime: 600 }. Explicit narrow flags still win.
+defineResource({ name: 'currency', adapter, referenceData: true });
+
+// Service resource — no adapter, no auto-CRUD, no validation, no registry entry.
+// Equivalent to disableDefaultRoutes + skipValidation + skipRegistry.
+defineResource({ name: 'health', customRoutesOnly: true, routes: [...] });
+
+// Resource-level pagination knobs (no custom queryParser needed):
+defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
+```
+
+400s on `?limit=` violations include the cap: `message: "Query parameter 'limit' must be <= 500 (got 800) (cap is 500)"` + `meta: { field: 'limit', cap: 500 }`.
+
 ## fieldRules
 
 | Flag | Effect |
@@ -533,12 +550,37 @@ await app.register(mcpPlugin, {
 
 **Per-resource opt-out:** `defineResource({ mcp: false })` — exclude a resource from MCP tool generation entirely. Useful for internal-admin or write-heavy resources where you don't want LLMs poking.
 
-**Auth modes** — `false` | `getAuth()` (Better Auth OAuth 2.1) | custom function returning `{ userId, organizationId, roles }` (human) or `{ clientId, organizationId, scopes }` (service). `PermissionResult.filters` flow into MCP tools exactly like REST.
+**Auth modes** — `false` | `getAuth()` (Better Auth OAuth 2.1) | `createMcpAuthFromBetterAuthApiKey(getAuth(), { orgFromMetadata: true })` (BA API-key plugin — handles `referenceId`/`userId` fallback + `metadata.organizationId` extraction) | custom function returning `{ userId, organizationId, roles }` (human) or `{ clientId, organizationId, scopes }` (service). `PermissionResult.filters` flow into MCP tools exactly like REST.
+
+**Tool-name collisions** — preset vs user (e.g. `softDelete` route vs `actions.restore`) auto-namespace to `softdelete_restore_<resource>`; every other collision shape throws `ArcError('arc.mcp.tool_name_collision')` naming both sources.
 
 **Custom tools** — co-locate with resources (`order.mcp.ts`), wire via `extraTools`. **AI SDK bridge** — expose AI SDK `tool()` defs via `buildMcpToolsFromBridges([...])`.
 
 Connect Claude CLI: `claude mcp add --transport http my-api http://localhost:3000/mcp`. Full recipes → [references/mcp.md](references/mcp.md).
 
+### AI SDK streaming → Fastify
+
+`streamResponse: true` routes that return a Web `ReadableStream` (Vercel AI SDK's `result.toUIMessageStream()`, `fetch().body`) auto-pipe through `pipeUIMessageStreamToReply()` — no `JsonToSseTransformStream` boilerplate.
+
+```typescript
+import { streamText } from 'ai';
+
+defineResource({
+  name: 'chat',
+  customRoutesOnly: true,
+  routes: [{
+    method: 'POST', path: '/', streamResponse: true, raw: true,
+    permissions: requireAuth(),
+    handler: async (req) => {
+      const result = streamText({ model, messages: req.body.messages });
+      return result.toUIMessageStream();  // arc pipes it for you
+    },
+  }],
+});
+```
+
+For manual control: `import { pipeUIMessageStreamToReply, UI_MESSAGE_STREAM_HEADERS } from '@classytic/arc/utils'`. Client disconnect cancels the source stream (no zombie LLM spend).
+
 ## Tenant cleanup (GDPR / SOX / HIPAA)
 
 Per-resource strategy + one auth-lifecycle wire-up:

package/skills/arc/references/api-reference.md

@@ -167,6 +167,8 @@ import {
 import {
   createStateMachine, CircuitBreaker, withCompensation, defineGuard,
   retry, queryParser,
+  // AI SDK / OpenAI streams → Fastify reply (no JsonToSseTransformStream boilerplate)
+  pipeUIMessageStreamToReply, UI_MESSAGE_STREAM_HEADERS, isReadableStream,
 } from '@classytic/arc/utils';
 import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
 import { Type, ArcListResponse } from '@classytic/arc/schemas';

package/skills/arc/references/mcp.md

@@ -168,7 +168,27 @@ Arc → auth.api.getMcpSession({ headers }) → { userId, organizationId }
 Arc → BaseController scopes by org automatically
 ```
 
-### 3. Custom Auth Function (API key, gateway, static org)
+### 3. Better Auth API Key (machine clients, no OAuth dance)
+
+Hosts using Better Auth's `apiKey()` plugin should NOT hand-wire `verifyApiKey` — the helper handles the `referenceId` vs `userId` fallback, `metadata.organizationId` extraction, disabled / expired guards, and fail-closed exception handling.
+
+```typescript
+import { createMcpAuthFromBetterAuthApiKey } from '@classytic/arc/mcp';
+import { getAuth } from './auth.config.js';
+
+await app.register(mcpPlugin, {
+  resources,
+  auth: createMcpAuthFromBetterAuthApiKey(getAuth(), {
+    orgFromMetadata: true,              // reads key.metadata.organizationId (default)
+    // metadataOrgField: 'tenantId',    // if you stored it under a different key
+    // permissionScope: 'mcp',          // permissions[scope] → result.scopes (default 'mcp')
+  }),
+});
+```
+
+Header precedence: `Authorization: Bearer <key>` first, then `x-api-key`. Keys with neither `userId` nor `referenceId` are treated as service principals (`clientId = key.id`) — `RequestScope.kind` becomes `"service"`.
+
+### 4. Custom Auth Function (API key, gateway, static org)
 
 Pass an `McpAuthResolver` — a function that receives headers and returns identity:
 
@@ -242,6 +262,15 @@ auth resolver returns { userId: 'alice', organizationId: 'org-a' }
 
 Works with any `tenantField` (`organizationId`, `workspaceId`, `teamId`). Resources with `tenantField: false` are visible to all authenticated users.
 
+## Tool-Name Collisions
+
+`createMcpServer()` resolves duplicate tool names BEFORE the MCP SDK sees them — the SDK's native `Tool already registered` error gave zero source attribution.
+
+- **Preset vs user** → auto-namespace. `softDelete`'s `restore_post` becomes `softdelete_restore_post` when the user defines `actions.restore`; the user's tool keeps the canonical name.
+- **User vs user / preset vs preset / 3-way+** → typed throw: `ArcError('arc.mcp.tool_name_collision')` naming both `source` strings (`crud:post:list`, `action:post:approve`, `route:post:GET /export`, `preset:softDelete:post:restore`).
+
+`resolveToolCollisions(tools)` is exported from `@classytic/arc/mcp` for test harnesses that want to exercise collision behaviour without booting a server.
+
 ## Level 2 — Custom Tools
 
 ```typescript