@classytic/arc 2.16.1 → 2.17.1

package/dist/testing/index.mjs

@@ -1036,7 +1036,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-DdPBtmzp.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-CzCEEsEm.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as OnTenantDeleteConfig, A as RequestIdOptions, Bt as AuthHelpers, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as TokenPair, H as ActionDefinition, Ht as Authenticator, I as MiddlewareHandler, J as CrudRouteKey, Jt as ArcRequest, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as AuthenticatorContext, Vt as AuthPluginOptions, W as ActionHandlerFn, Wt as JwtContext, X as EventDefinition, Xt as ObjectId, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, Zt as UserLike, _ as ControllerQueryOptions, _t as FastifyHandler, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, ct as ResourceHookContext, d as PaginationResult, dt as RouteDefinition, et as OpenApiSchemas, f as IntrospectionData, ft as RouteMcpConfig, g as ArcInternalMetadata, gt as ControllerLike, h as ResourceMetadata, ht as ControllerHandler, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHooks, m as RegistryStats, mt as RouteSchemaOptions, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMethod, q as CrudController, qt as ApiResponse, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourcePermissions, v as LookupOption, vt as IController, w as ServiceContext, x as PopulateOption, xt as RouteHandler, y as OwnershipCheck, yt as IControllerResponse } from "../index-DBDgy6Hw.mjs";
+import { $ as OnTenantDeleteConfig, A as RequestIdOptions, Bt as AuthHelpers, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, G as ActionsMap, Gt as TokenPair, H as ActionDefinition, Ht as Authenticator, I as MiddlewareHandler, J as CrudRouteKey, Jt as ArcRequest, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, M as EventsDecorator, N as FastifyRequestExtras, O as HealthOptions, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, Ut as AuthenticatorContext, Vt as AuthPluginOptions, W as ActionHandlerFn, Wt as JwtContext, X as EventDefinition, Xt as ObjectId, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, Zt as UserLike, _ as ControllerQueryOptions, _t as FastifyHandler, a as InferAdapterDoc, at as ResolvedTenantPurge, b as ParsedQuery, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, ct as ResourceHookContext, d as PaginationResult, dt as RouteDefinition, et as OpenApiSchemas, f as IntrospectionData, ft as RouteMcpConfig, g as ArcInternalMetadata, gt as ControllerLike, h as ResourceMetadata, ht as ControllerHandler, i as ValidationResult, it as RateLimitConfig, j as ArcDecorator, k as IntrospectionPluginOptions, l as TypedRepository, lt as ResourceHooks, m as RegistryStats, mt as RouteSchemaOptions, n as ConfigError, nt as PresetHook, o as InferDocType, ot as ResourceCacheConfig, p as RegistryEntry, pt as RouteMethod, q as CrudController, qt as ApiResponse, r as ValidateOptions, rt as PresetResult, s as InferResourceDoc, st as ResourceConfig, t as RouteHandlerMethod, tt as PresetFunction, u as TypedResourceConfig, ut as ResourcePermissions, v as LookupOption, vt as IController, w as ServiceContext, x as PopulateOption, xt as RouteHandler, y as OwnershipCheck, yt as IControllerResponse } from "../index-C1JSBan-.mjs";
 import { i as RequestScope } from "../types-CfapW2t8.mjs";
 import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-DqZLp5d6.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-DvwtjDwu.mjs";

package/dist/{types-Dw--SyTq.d.mts → types-BRmS8TNa.d.mts}

@@ -1,5 +1,5 @@
 import { r as CacheStore } from "./interface-BVkZsvEe.mjs";
-import { Ht as Authenticator } from "./index-DBDgy6Hw.mjs";
+import { Ht as Authenticator } from "./index-C1JSBan-.mjs";
 import { n as ElevationOptions } from "./elevation-DvwtjDwu.mjs";
 import { a as EventTransport } from "./EventTransport-B1GFiYUy.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-ClykOQqa.mjs";

package/dist/{types-BD0BCdf6.d.mts → types-CoMjNmkF.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-DBDgy6Hw.mjs";
+import { V as ResourceDefinition } from "./index-C1JSBan-.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts
@@ -93,6 +93,17 @@ interface ToolDefinition<TSession = McpAuthResult> {
   outputSchema?: Record<string, z.ZodTypeAny>;
   annotations?: ToolAnnotations;
   handler: (input: Record<string, unknown>, ctx: ToolContext<TSession>) => Promise<CallToolResult>;
+  /**
+   * Origin label used by collision diagnostics — names BOTH the resource
+   * and the surface that produced this tool (`'crud:post:list'`,
+   * `'action:post:approve'`, `'route:post:GET /export'`,
+   * `'preset:softDelete:post:restore'`). When two tools share a name,
+   * `createMcpServer()` prints both labels so the host can see which
+   * surfaces collided without spelunking through the MCP SDK's stack
+   * trace. Optional — hand-written tools without a `source` simply
+   * appear as `'(unknown)'` in collision messages.
+   */
+  source?: string;
 }
 /** Output of definePrompt() — plain data, not yet registered */
 interface PromptDefinition {

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-import { Kt as AnyRecord, S as QueryParserInterface, Zt as UserLike, b as ParsedQuery, et as OpenApiSchemas, st as ResourceConfig } from "../index-DBDgy6Hw.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";
@@ -1255,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>;
@@ -1284,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-DPXZnZUx.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-BMQK8mRl.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-DPXZnZUx.mjs → utils-BMQK8mRl.mjs}

@@ -1,8 +1,9 @@
 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";
+import { Readable } from "node:stream";
 //#region src/utils/simpleEqualityMatcher.ts
 /**
 * `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
@@ -1670,6 +1671,114 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
+//#region src/utils/streaming.ts
+/**
+* Streaming helpers — adapters between Web `ReadableStream` producers
+* (Vercel AI SDK, OpenAI SDK, `fetch().body`, hand-built `TransformStream`s)
+* and Fastify's raw Node-stream reply.
+*
+* Why this exists: returning a `ReadableStream<UIMessageChunk>` from a
+* `streamResponse: true` arc route used to crash with
+* `chunk must be a string or Buffer` because Fastify cannot serialise
+* `UIMessageChunk` JSON objects directly. Every arc-ai host (sniffer,
+* spawn, downstream) reimplemented the same `JsonToSseTransformStream` +
+* SSE header boilerplate. `pipeUIMessageStreamToReply()` is that
+* boilerplate, owned once.
+*
+* arc stays peer-coupled to nothing: the helper accepts any
+* `ReadableStream<unknown>` and JSON-stringifies each chunk. It works
+* with `UIMessageChunk` from the AI SDK without importing it.
+*/
+/**
+* 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 headers = options.headers ?? UI_MESSAGE_STREAM_HEADERS;
+	for (const [key, value] of Object.entries(headers)) reply.header(key, value);
+	const reader = stream.getReader();
+	let cancelled = false;
+	const onAbort = () => {
+		cancelled = true;
+		reader.cancel().catch(() => {});
+	};
+	reply.request.raw.once("close", onAbort);
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	async function* sseFrames() {
+		try {
+			while (true) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				yield `data: ${serialize(value)}\n\n`;
+			}
+		} catch (err) {
+			if (!cancelled) yield `event: error\ndata: ${JSON.stringify({ message: String(err) })}\n\n`;
+		} finally {
+			reply.request.raw.removeListener("close", onAbort);
+			options.signal?.removeEventListener("abort", onAbort);
+			reader.releaseLock?.();
+		}
+	}
+	const nodeStream = Readable.from(sseFrames());
+	await reply.send(nodeStream);
+}
+function defaultSerialize(chunk) {
+	return typeof chunk === "string" ? chunk : JSON.stringify(chunk);
+}
+/**
+* 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
@@ -1688,4 +1797,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.16.1",
+  "version": "2.17.1",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {

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