@classytic/arc 2.11.4 → 2.14.0

package/dist/{createActionRouter-CIKOcNA7.mjs → createActionRouter-CBxLLbn3.mjs}

@@ -1,6 +1,7 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.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-BqLRb5l7.mjs";
-import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-Dy2p4MxS.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-DrOa-26E.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-lYhC2gE5.mjs";
 //#region src/core/createActionRouter.ts
 var createActionRouter_exports = /* @__PURE__ */ __exportAll({
 	buildActionBodySchema: () => buildActionBodySchema,
@@ -69,23 +70,13 @@ function createActionRouter(fastify, config) {
 			const { action, ...data } = req.body;
 			const { id } = req.params;
 			const handler = wrappedHandlers.get(action);
-			if (!handler) return sendControllerResponse(reply, {
-				success: false,
-				status: 400,
-				error: `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`,
-				meta: { validActions: actionEnum }
-			}, req);
+			if (!handler) throw createError(400, `Invalid action '${action}'. Valid actions: ${actionEnum.join(", ")}`, { validActions: actionEnum });
 			try {
 				return sendControllerResponse(reply, await handler(id, data, req), req);
 			} catch (error) {
 				if (onError) {
 					const { statusCode, error: errorMsg, code } = onError(error, action, id);
-					return sendControllerResponse(reply, {
-						success: false,
-						status: statusCode,
-						error: errorMsg,
-						...code ? { meta: { code } } : {}
-					}, req);
+					throw createError(statusCode, errorMsg, code ? { code } : void 0);
 				}
 				const err = error;
 				const statusCode = err.statusCode || err.status || 500;
@@ -95,12 +86,8 @@ function createActionRouter(fastify, config) {
 					action,
 					id
 				}, "Action handler error");
-				return sendControllerResponse(reply, {
-					success: false,
-					status: statusCode,
-					error: err.message || `Failed to execute '${action}' action`,
-					meta: { code: errorCode }
-				}, req);
+				if (error?.name === "ArcError" || error instanceof Error === false) throw error;
+				throw createError(statusCode, err.message || `Failed to execute '${action}' action`, { code: errorCode });
 			}
 		}
 	});

package/dist/createAggregationRouter-CRIBv4sC.mjs

@@ -0,0 +1,114 @@
+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-DrOa-26E.mjs";
+import { r as validateAggregations, t as buildAggregationHandler } from "./buildHandler-olo-gt94.mjs";
+//#region src/core/aggregation/createAggregationRouter.ts
+/**
+* Register one Fastify route per aggregation. No-op when the map is
+* empty — same convention `createActionRouter` follows.
+*/
+function createAggregationRouter(fastify, config) {
+	const { tag, resourceName, aggregations, fields: fieldPermissions, schemaOptions, permissions: resourcePermissions, routeGuards = [], repository, buildOptions } = config;
+	if (!aggregations || Object.keys(aggregations).length === 0) return;
+	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
+	const arcDecorator = buildArcDecorator({
+		resourceName,
+		schemaOptions,
+		permissions: resourcePermissions,
+		hooks: fastify.arc?.hooks,
+		events: fastify.events,
+		fields: fieldPermissions
+	});
+	for (const aggregation of normalized) registerOne(fastify, aggregation, {
+		tag,
+		arcDecorator,
+		routeGuards,
+		repository,
+		buildOptions
+	});
+	fastify.log?.debug?.({
+		aggregations: normalized.map((a) => a.name),
+		resourceName
+	}, `[createAggregationRouter] registered ${normalized.length} aggregation route(s)`);
+}
+function registerOne(fastify, normalized, ctx) {
+	const { tag, arcDecorator, routeGuards, repository, buildOptions } = ctx;
+	const { name } = normalized;
+	const config = normalized.base;
+	const authMw = buildAuthMiddleware(fastify, config.permissions);
+	const permissionFn = config.permissions;
+	const permissionMw = async (req, _reply) => {
+		const raw = await permissionFn(buildPermissionContextLite(req, normalized.name));
+		if (!normalizePermissionGranted(raw)) {
+			const status = req.user ? 403 : 401;
+			const reason = normalizePermissionReason(raw);
+			if (status === 401) throw new UnauthorizedError(reason ?? "Authentication required to access this aggregation.");
+			throw new ForbiddenError(reason ?? "You do not have permission to access this aggregation.");
+		}
+	};
+	const preHandler = buildPreHandlerChain({
+		arcDecorator,
+		authMw,
+		permissionMw,
+		pluginMw: selectPluginMw("GET", resolveRouterPluginMw(fastify, false)),
+		routeGuards
+	});
+	const rateLimitConfig = buildRateLimitConfig(config.rateLimit ? {
+		max: config.rateLimit.max,
+		timeWindow: `${config.rateLimit.windowMs}ms`
+	} : void 0);
+	const handler = buildAggregationHandler(normalized, {
+		repo: repository,
+		buildOptions
+	});
+	const routeSchema = {
+		tags: tag ? [tag] : void 0,
+		summary: config.summary ?? `Aggregation: ${name}`,
+		description: config.description ?? "Portable aggregation generated by arc. Filters from query string compose with the declaration's base filter + tenant scope."
+	};
+	fastify.route({
+		method: "GET",
+		url: `/aggregations/${name}`,
+		schema: routeSchema,
+		preHandler: preHandler.length > 0 ? preHandler : void 0,
+		...rateLimitConfig ? { config: rateLimitConfig } : {},
+		handler: async (req, reply) => {
+			try {
+				return await handler(req, reply);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				req.log.error({
+					err,
+					aggregation: name
+				}, "Aggregation handler error");
+				throw createError(500, `Aggregation "${name}" failed: ${message}`);
+			}
+		}
+	});
+}
+/**
+* Minimal `PermissionContext` for aggregation routes. Aggregations are
+* read-shape so the action is `'list'` and `data` / `resourceId` stay
+* undefined unless the URL includes them (none do today — `:name` is
+* the only path param).
+*/
+function buildPermissionContextLite(req, aggregationName) {
+	const reqWithExtras = req;
+	return {
+		user: reqWithExtras.user ?? null,
+		request: req,
+		resource: reqWithExtras.arc?.resource ?? "aggregation",
+		action: `aggregation:${aggregationName}`
+	};
+}
+/** PermissionCheck returns `boolean | PermissionResult`. Pull `granted`. */
+function normalizePermissionGranted(raw) {
+	if (typeof raw === "boolean") return raw;
+	return raw.granted;
+}
+/** Pull `reason` when the check returned a structured `PermissionResult`. */
+function normalizePermissionReason(raw) {
+	if (typeof raw === "boolean") return void 0;
+	return raw.reason;
+}
+//#endregion
+export { createAggregationRouter };

package/dist/{createApp-C9bRrqlX.mjs → createApp-XX2-N0Yd.mjs}

@@ -1,5 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { n as PUBLIC_SCOPE } from "./types-AOD8fxIw.mjs";
+import { arcLog } from "./logger/index.mjs";
+import { n as PUBLIC_SCOPE } from "./types-C_s5moIu.mjs";
 import Fastify from "fastify";
 import qs from "qs";
 //#region src/factory/presets.ts
@@ -201,7 +202,7 @@ async function registerArcCore(fastify, config, trackPlugin) {
 	await fastify.register(arcCorePlugin, { emitEvents: config.arcPlugins?.emitEvents !== false });
 	trackPlugin("arc-core");
 	if (config.arcPlugins?.events !== false) {
-		const { default: eventPlugin } = await import("./eventPlugin-Cts2-Tfj.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-CaKTYkYM.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -237,15 +238,15 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-graceful-shutdown");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-CheW3m-S.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-SM8gghN6.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.caching === true ? {} : config.arcPlugins.caching;
 		await fastify.register(cachingPlugin, opts);
 		trackPlugin("arc-caching", opts);
 	}
 	if (config.arcPlugins?.queryCache) {
-		const { queryCachePlugin } = await import("./queryCachePlugin-Bq6bO6vc.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-m1XsgAIJ.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = config.stores?.queryCache ?? new (await (import("./memory-DikHSvWa.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-UBydS5ku.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
@@ -254,19 +255,19 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 	}
 	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
 	else {
-		const { default: ssePlugin } = await import("./sse-V7aXc3bW.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("./sse-Bz-5ZeTt.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.sse === true ? {} : config.arcPlugins.sse;
 		await fastify.register(ssePlugin, opts);
 		trackPlugin("arc-sse", opts);
 	}
 	if (config.arcPlugins?.metrics) {
-		const { default: metricsPlugin } = await import("./metrics-Csh4nsvv.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-Qnvwc-LQ.mjs").then((n) => n.r);
 		const opts = config.arcPlugins.metrics === true ? {} : config.arcPlugins.metrics;
 		await fastify.register(metricsPlugin, opts);
 		trackPlugin("arc-metrics", opts);
 	}
 	if (config.arcPlugins?.versioning) {
-		const { default: versioningPlugin } = await import("./versioning-CGPjkqAg.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-BUrT5aP4.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -335,7 +336,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-DOFoxoDs.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-DgoeTyfX.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -345,7 +346,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-BQm8ZxTK.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-Bk-AGhkU.mjs").then((n) => n.r);
 	const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 	await fastify.register(errorHandlerPlugin, errorOpts);
 	trackPlugin("arc-error-handler", errorOpts);
@@ -399,7 +400,7 @@ async function registerOne(parent, resource) {
 }
 /**
 * Execute the full resource lifecycle:
-* 1. plugins()                   — infra (DB, docs, webhooks)
+* 1. plugins()                   — infra (DB, data, webhooks)
 * 2. bootstrap[]                 — domain init (singletons, event handlers)
 * 3. resources factory (if any)  — resolved AFTER bootstrap, so engine-backed
 *                                  adapters can `await ensureEngine()` and pass
@@ -445,7 +446,7 @@ async function registerResources(fastify, config) {
 	let discoveryPath;
 	let discoveryYieldedZero = false;
 	if (resolvedResources === void 0 && config.resourceDir) {
-		const { loadResources } = await import("./loadResources-CPpkyKfM.mjs").then((n) => n.n);
+		const { loadResources } = await import("./loadResources-DBMQg_Aj.mjs").then((n) => n.n);
 		const { resolve, dirname } = await import("node:path");
 		const { fileURLToPath } = await import("node:url");
 		const rawDir = config.resourceDir;
@@ -745,7 +746,7 @@ function validateDistributedRuntime(options) {
 * 4. Arc core (fastify.arc, events)
 * 5. Arc plugins (requestId, health, caching, SSE, metrics, versioning)
 * 6. Auth (scope decoration, auth strategy, elevation, error handler)
-* 7. plugins()        — user infra (DB, docs, webhooks)
+* 7. plugins()        — user infra (DB, data, webhooks)
 * 8. bootstrap[]      — domain init (singletons, event handlers)
 * 9. resources[]      — auto-discovered routes (prefix + skipGlobalPrefix)
 * 10. afterResources() — post-registration wiring
@@ -810,17 +811,22 @@ async function createApp(options) {
 	await registerErrorHandler(fastify, config, trackPlugin);
 	await registerResources(fastify, config);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-ByllIXXV.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-CK-FNO8E.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
-	if (config.serializeBigInt) fastify.addHook("preSerialization", async (_request, _reply, payload) => {
-		if (payload === null || payload === void 0) return payload;
-		try {
-			return JSON.parse(JSON.stringify(payload, (_key, value) => typeof value === "bigint" ? Number(value) : value));
-		} catch {
-			return payload;
-		}
-	});
+	if (config.serializeBigInt) {
+		const mode = config.serializeBigInt === "string" ? "string" : "number";
+		if (config.serializeBigInt === true) arcLog("createApp").warn("serializeBigInt: true is a back-compat alias for 'number' (lossy above Number.MAX_SAFE_INTEGER = 9007199254740991). For IDs / money / counters / ledger values use serializeBigInt: 'string' (lossless). The boolean form will be removed in a future major.");
+		else if (mode === "number") arcLog("createApp").warn("serializeBigInt: 'number' loses precision above Number.MAX_SAFE_INTEGER (9007199254740991). Use 'string' instead unless you've audited that no bigint payload field can exceed the safe range.");
+		fastify.addHook("preSerialization", async (_request, _reply, payload) => {
+			if (payload === null || payload === void 0) return payload;
+			try {
+				return JSON.parse(JSON.stringify(payload, (_key, value) => typeof value === "bigint" ? mode === "string" ? value.toString() : Number(value) : value));
+			} catch {
+				return payload;
+			}
+		});
+	}
 	const authMode = config.auth === false ? "none" : config.auth ? config.auth.type : "none";
 	fastify.log.info({
 		preset: config.preset ?? "custom",

package/dist/{defineEvent-D1Ky9M1D.mjs → defineEvent-D5h7EvAx.mjs}

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

package/dist/docs/index.d.mts

@@ -1,8 +1,14 @@
-import { p as RegistryEntry } from "../index-CXXRbnf8.mjs";
+import { p as RegistryEntry } from "../index-BtW7qYwa.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BD5nw6St.mjs";
 import { FastifyPluginAsync } from "fastify";
 
-//#region src/docs/openapi.d.ts
+//#region src/docs/openapi/types.d.ts
+/**
+ * OpenAPI 3.0 type primitives used by arc's spec emitter.
+ *
+ * Internal to `src/docs/openapi/*` — public exports are surfaced via
+ * `src/docs/index.ts` (which re-exports `OpenApiSpec` only).
+ */
 interface OpenApiOptions {
   /** API title */
   title?: string;
@@ -23,6 +29,13 @@ interface OpenApiOptions {
   /** Custom OpenAPI extensions */
   extensions?: Record<string, unknown>;
 }
+interface OpenApiBuildOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  serverUrl?: string;
+  apiPrefix?: string;
+}
 interface OpenApiSpec {
   openapi: string;
   info: {
@@ -45,13 +58,6 @@ interface OpenApiSpec {
   }>;
   security?: Array<Record<string, string[]>>;
 }
-interface OpenApiBuildOptions {
-  title?: string;
-  version?: string;
-  description?: string;
-  serverUrl?: string;
-  apiPrefix?: string;
-}
 interface PathItem {
   get?: Operation;
   post?: Operation;
@@ -101,7 +107,7 @@ interface Response {
   }>;
 }
 interface SchemaObject {
-  type?: string;
+  type?: string | string[];
   format?: string;
   properties?: Record<string, SchemaObject>;
   items?: SchemaObject;
@@ -110,12 +116,17 @@ interface SchemaObject {
   description?: string;
   example?: unknown;
   additionalProperties?: boolean | SchemaObject;
-  enum?: string[];
+  enum?: (string | number | boolean | null)[];
   minimum?: number;
   maximum?: number;
   minLength?: number;
   maxLength?: number;
   pattern?: string;
+  oneOf?: SchemaObject[];
+  anyOf?: SchemaObject[];
+  allOf?: SchemaObject[];
+  default?: unknown;
+  nullable?: boolean;
 }
 interface SecurityScheme {
   type: string;
@@ -124,6 +135,8 @@ interface SecurityScheme {
   in?: string;
   name?: string;
 }
+//#endregion
+//#region src/docs/openapi/index.d.ts
 declare const openApiPlugin: FastifyPluginAsync<OpenApiOptions>;
 /**
  * Build OpenAPI spec from registry resources.

package/dist/docs/index.mjs

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

package/dist/{elevation-DOFoxoDs.mjs → elevation-DgoeTyfX.mjs}

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

package/dist/errorHandler-Bk-AGhkU.mjs

@@ -0,0 +1,174 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { m as statusToArcCode, p as isArcError } from "./errors-j4aJm1Wg.mjs";
+import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+import fp from "fastify-plugin";
+//#region src/plugins/errorHandler.ts
+var errorHandler_exports = /* @__PURE__ */ __exportAll({
+	defaultIsDuplicateKeyError: () => defaultIsDuplicateKeyError,
+	errorHandlerPlugin: () => errorHandlerPlugin
+});
+/**
+* Default duplicate-key detector. Strict driver-code matching only — never
+* message strings (false positives mask real WriteConflict / NotWritable
+* errors as 409s). Long-tail drivers compose: see jsdoc on
+* {@link ErrorHandlerOptions.isDuplicateKeyError}.
+*/
+function defaultIsDuplicateKeyError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	if (e.code === 11e3 || e.codeName === "DuplicateKey") return true;
+	if (e.code === "P2002") return true;
+	if (e.code === "23505") return true;
+	if (e.code === "ER_DUP_ENTRY" || e.errno === 1062) return true;
+	if (e.code === "SQLITE_CONSTRAINT_UNIQUE" || e.code === "SQLITE_CONSTRAINT_PRIMARYKEY") return true;
+	return false;
+}
+function extractDuplicateFields(err) {
+	if (!err || typeof err !== "object") return null;
+	const e = err;
+	if (e.keyValue && typeof e.keyValue === "object") return Object.keys(e.keyValue);
+	if (e.meta?.target) {
+		if (Array.isArray(e.meta.target)) return e.meta.target.map(String);
+		if (typeof e.meta.target === "string") return [e.meta.target];
+	}
+	if (typeof e.constraint === "string") return [e.constraint];
+	return null;
+}
+/** Map Fastify schema-validation errors → canonical `ErrorDetail[]`. */
+function fastifyValidationDetails(error) {
+	return (error.validation ?? []).map((v) => {
+		const missingProperty = v.params?.missingProperty;
+		const path = v.instancePath?.replace(/^\//, "") || (typeof missingProperty === "string" ? missingProperty : void 0);
+		return {
+			...path ? { path } : {},
+			code: v.keyword ?? "invalid",
+			message: v.message || "Invalid value"
+		};
+	});
+}
+/** Map Mongoose `ValidationError.errors` → canonical `ErrorDetail[]`. */
+function mongooseValidationDetails(errors) {
+	return Object.entries(errors).map(([field, e]) => ({
+		path: e.path || field,
+		code: "validation_error",
+		message: e.message
+	}));
+}
+async function errorHandlerPluginFn(fastify, options = {}) {
+	const isProduction = process.env.NODE_ENV === "production";
+	const { includeStack = !isProduction, onError, errorMap = {}, errorMappers = [], isDuplicateKeyError = defaultIsDuplicateKeyError } = options;
+	fastify.setErrorHandler(async (error, request, reply) => {
+		if (onError) try {
+			await onError(error, request);
+		} catch (callbackError) {
+			request.log.error({ err: callbackError }, "Error in onError callback");
+		}
+		const correlationId = request.id;
+		const contract = classify(error, {
+			errorMappers,
+			errorMap,
+			isDuplicateKeyError
+		});
+		const meta = { ...contract.meta ?? {} };
+		if (includeStack && error.stack) meta.stack = error.stack;
+		const wire = {
+			...contract,
+			...correlationId ? { correlationId } : {},
+			...Object.keys(meta).length > 0 ? { meta } : {}
+		};
+		const status = wire.status ?? 500;
+		if (status >= 500) request.log.error({
+			err: error,
+			status
+		}, "Server error");
+		else if (status >= 400) request.log.warn({
+			err: error,
+			status
+		}, "Client error");
+		if (isArcError(error) && error.cause) request.log.error({ cause: error.cause }, "Error cause chain");
+		return reply.status(status).send(wire);
+	});
+}
+/**
+* Single-pass error → `ErrorContract` classifier. Dispatch order is fixed:
+*
+*   1. Class-based mappers (`instanceof`) — user-registered domain errors
+*   2. `ArcError` / any `HttpError`-shaped throw — flows through `toErrorContract`
+*   3. Fastify schema-validation errors — `error.validation` array
+*   4. Fastify-style errors with a numeric `statusCode`
+*   5. Name-keyed `errorMap` entries
+*   6. Mongoose `ValidationError` / `CastError`
+*   7. Driver-specific duplicate-key classifier
+*   8. Fallback: `arc.internal_error` 500
+*/
+function classify(error, ctx) {
+	for (const mapper of ctx.errorMappers) if (error instanceof mapper.type) {
+		const mapped = mapper.toResponse(error);
+		return {
+			code: mapped.code ?? statusToArcCode(mapped.status),
+			message: mapped.message ?? error.message,
+			status: mapped.status,
+			...mapped.details ? { details: mapped.details } : {},
+			...mapped.meta ? { meta: mapped.meta } : {}
+		};
+	}
+	if (isArcError(error) || isHttpError(error)) return toErrorContract(error);
+	const fastifyErr = error;
+	if (Array.isArray(fastifyErr.validation)) return {
+		code: "arc.validation_error",
+		message: "Validation failed",
+		status: 400,
+		details: fastifyValidationDetails(fastifyErr)
+	};
+	if (typeof fastifyErr.statusCode === "number") return {
+		code: statusToArcCode(fastifyErr.statusCode),
+		message: error.message || "Error",
+		status: fastifyErr.statusCode
+	};
+	if (error.name && ctx.errorMap[error.name]) {
+		const m = ctx.errorMap[error.name];
+		return {
+			code: m.code,
+			message: m.message ?? error.message,
+			status: m.statusCode
+		};
+	}
+	if (error.name === "ValidationError" && "errors" in error) {
+		const errs = error.errors;
+		return {
+			code: "arc.validation_error",
+			message: error.message || "Validation failed",
+			status: 400,
+			details: mongooseValidationDetails(errs)
+		};
+	}
+	if (error.name === "CastError") return {
+		code: "arc.invalid_id",
+		message: "Invalid identifier format",
+		status: 400
+	};
+	if (ctx.isDuplicateKeyError(error)) {
+		const fields = extractDuplicateFields(error);
+		return {
+			code: "arc.conflict",
+			message: "Resource already exists",
+			status: 409,
+			...fields && fields.length > 0 ? { details: fields.map((f) => ({
+				path: f,
+				code: "duplicate_key",
+				message: `Duplicate value for "${f}"`
+			})) } : {}
+		};
+	}
+	return {
+		code: "arc.internal_error",
+		message: error.message || "Internal Server Error",
+		status: 500
+	};
+}
+const errorHandlerPlugin = fp(errorHandlerPluginFn, {
+	name: "arc-error-handler",
+	fastify: "5.x"
+});
+//#endregion
+export { errorHandlerPlugin as n, errorHandler_exports as r, defaultIsDuplicateKeyError as t };

package/dist/errorHandler-DFr45ZG4.d.mts

@@ -0,0 +1,45 @@
+import { ErrorDetail } from "@classytic/repo-core/errors";
+import { FastifyInstance, FastifyRequest } from "fastify";
+
+//#region src/plugins/errorHandler.d.ts
+/**
+ * Class-based error mapper — `instanceof` check converts a thrown class
+ * to a partial `ErrorContract`. Highest-priority dispatch in the handler.
+ */
+interface ErrorMapper<T extends Error = Error> {
+  type: abstract new (...args: any[]) => T;
+  toResponse: (error: T) => {
+    status: number;
+    code?: string;
+    message?: string;
+    details?: ReadonlyArray<ErrorDetail>;
+    meta?: Record<string, unknown>;
+  };
+}
+interface ErrorHandlerOptions {
+  /** Include `meta.stack` on the wire (defaults to `NODE_ENV !== 'production'`). */
+  includeStack?: boolean;
+  /** Custom callback fired for every error — log to Sentry / Datadog / etc. */
+  onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;
+  /** Map by `error.name` string. Lower priority than `errorMappers`. */
+  errorMap?: Record<string, {
+    statusCode: number;
+    code: string;
+    message?: string;
+  }>;
+  /** Map by `instanceof`. Highest priority — checked first. */
+  errorMappers?: ErrorMapper[];
+  /** Driver-aware duplicate-key classifier. Override to add long-tail drivers. */
+  isDuplicateKeyError?: (err: unknown) => boolean;
+}
+/**
+ * Default duplicate-key detector. Strict driver-code matching only — never
+ * message strings (false positives mask real WriteConflict / NotWritable
+ * errors as 409s). Long-tail drivers compose: see jsdoc on
+ * {@link ErrorHandlerOptions.isDuplicateKeyError}.
+ */
+declare function defaultIsDuplicateKeyError(err: unknown): boolean;
+declare function errorHandlerPluginFn(fastify: FastifyInstance, options?: ErrorHandlerOptions): Promise<void>;
+declare const errorHandlerPlugin: typeof errorHandlerPluginFn;
+//#endregion
+export { errorHandlerPlugin as i, ErrorMapper as n, defaultIsDuplicateKeyError as r, ErrorHandlerOptions as t };