@classytic/arc 2.15.3 → 2.16.0

package/dist/createActionRouter-DUpN3Dd1.mjs

@@ -0,0 +1,288 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import "./constants-TrJVIJl0.mjs";
+import { f as createError } from "./errors-j4aJm1Wg.mjs";
+import { a as buildAuthMiddlewareForPermissions, c as buildPreHandlerChain, f as resolveRouterPluginMw, l as buildRateLimitConfig, n as buildActionPipelineHandler, p as selectPluginMw, r as buildArcDecorator, t as buildActionPermissionMw, u as resolvePipelineSteps, y as sendControllerResponse } from "./routerShared-CZV5aabX.mjs";
+import { n as schemaIRToJsonSchemaBranch, t as normalizeSchemaIR } from "./schemaIR-Ctc89DSn.mjs";
+//#region src/core/createActionRouter.ts
+var createActionRouter_exports = /* @__PURE__ */ __exportAll({
+	buildActionBodySchema: () => buildActionBodySchema,
+	createActionRouter: () => createActionRouter
+});
+/**
+* Register the unified action endpoint: `POST /:id/action`.
+*
+* Shares every lifecycle primitive with the CRUD router — the preHandler
+* chain, the arc decorator, idempotency, rate-limit, and the response
+* shaper. The only thing that stays local is the dynamic permission check
+* (keyed by `body.action` at request time).
+*/
+function createActionRouter(fastify, config) {
+	const { tag, resourceName = tag ?? "action", actions, actionPermissions = {}, actionSchemas = {}, globalAuth, onError, fields: fieldPermissions, schemaOptions, idField = "_id", permissions: resourcePermissions, routeGuards = [], pipeline, rateLimit, idLessActionNames = [] } = config;
+	const allActionNames = Object.keys(actions);
+	if (allActionNames.length === 0) {
+		fastify.log.warn("[createActionRouter] No actions defined, skipping route creation");
+		return;
+	}
+	const idLessSet = new Set(idLessActionNames);
+	const idBoundActionNames = allActionNames.filter((name) => !idLessSet.has(name));
+	const idLessActions = allActionNames.filter((name) => idLessSet.has(name));
+	for (const name of idLessActionNames) if (!Object.hasOwn(actions, name)) throw new Error(`[Arc/Actions] Resource '${resourceName}': idLess action '${name}' is not declared in the actions map. Valid actions: ${allActionNames.join(", ")}.`);
+	const arcDecorator = buildArcDecorator({
+		resourceName,
+		schemaOptions,
+		permissions: resourcePermissions,
+		hooks: fastify.arc?.hooks,
+		events: fastify.events,
+		fields: fieldPermissions,
+		idField
+	});
+	const pluginMw = resolveRouterPluginMw(fastify, false);
+	const wrappedHandlers = /* @__PURE__ */ new Map();
+	for (const [name, handler] of Object.entries(actions)) {
+		const steps = resolvePipelineSteps(pipeline, name);
+		wrappedHandlers.set(name, buildActionPipelineHandler(handler, steps, name, resourceName));
+	}
+	const rateLimitConfig = buildRateLimitConfig(rateLimit);
+	/**
+	* Register one action mount point. Called once per mount (id-bound and/or
+	* id-less). Each mount has its OWN AJV `oneOf` body schema filtered to
+	* just `actionSubset` so the mount-point boundary is also a contract
+	* boundary: hitting `POST /<prefix>/action` with an id-bound action name
+	* fails at AJV (the discriminator enum excludes it) — and the
+	* formatter's "wrong mount" message points the caller at the right URL.
+	*/
+	const registerActionRoute = (mountOpts) => {
+		const { urlPath, actionSubset, hasId } = mountOpts;
+		if (actionSubset.length === 0) return;
+		const subsetSet = new Set(actionSubset);
+		const authMw = buildAuthMiddlewareForPermissions(fastify, actionSubset.map((name) => actionPermissions[name] ?? globalAuth));
+		const subsetPermissions = {};
+		for (const name of actionSubset) {
+			const perm = actionPermissions[name];
+			if (perm) subsetPermissions[name] = perm;
+		}
+		const permissionMw = buildActionPermissionMw(actionSubset, subsetPermissions, globalAuth, resourceName);
+		const subsetSchemas = {};
+		for (const name of actionSubset) if (actionSchemas[name]) subsetSchemas[name] = actionSchemas[name];
+		const bodySchema = buildActionBodySchema(actionSubset, subsetSchemas);
+		const routeSchema = {
+			tags: tag ? [tag] : void 0,
+			summary: `Perform action (${actionSubset.join("/")})`,
+			description: buildActionDescription(Object.fromEntries(actionSubset.map((name) => [name, actions[name]])), subsetPermissions),
+			body: bodySchema
+		};
+		if (hasId) routeSchema.params = {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				description: "Resource ID"
+			} },
+			required: ["id"]
+		};
+		const actionValidationFormatter = async (req, _reply) => {
+			const validationError = req.validationError;
+			if (!validationError) return;
+			const body = req.body;
+			const submitted = typeof body?.action === "string" ? body.action : void 0;
+			if (!submitted || !subsetSet.has(submitted)) {
+				const wrongMount = submitted && allActionNames.includes(submitted) ? submitted : void 0;
+				const otherMount = hasId ? "/action" : "/:id/action";
+				throw createError(400, wrongMount ? `Action '${wrongMount}' on '${resourceName}' is mounted at 'POST ${otherMount}', not 'POST ${urlPath}'` : submitted ? `Unknown action '${submitted}' on '${resourceName}'. Valid at 'POST ${urlPath}': ${actionSubset.join(", ")}` : `Missing 'action' field on '${resourceName}'. Valid at 'POST ${urlPath}': ${actionSubset.join(", ")}`, {
+					code: "arc.invalid_action",
+					validActions: actionSubset,
+					mount: urlPath,
+					...submitted ? { submitted } : {},
+					...wrongMount ? { mountedAt: otherMount } : {}
+				});
+			}
+			const branchPath = `/oneOf/${actionSubset.indexOf(submitted)}/`;
+			const ajvErrors = validationError.validation ?? [];
+			const scoped = ajvErrors.filter((e) => e.keyword !== "oneOf" && (e.schemaPath?.includes(branchPath) || !e.schemaPath?.includes("/oneOf/")));
+			const useErrors = scoped.length > 0 ? scoped : ajvErrors;
+			const scopedError = /* @__PURE__ */ new Error(`Validation failed for action '${submitted}' on '${resourceName}'`);
+			scopedError.statusCode = 400;
+			scopedError.code = "arc.validation_error";
+			scopedError.validation = useErrors;
+			scopedError.validationContext = "body";
+			scopedError.meta = { action: submitted };
+			throw scopedError;
+		};
+		const preHandler = [actionValidationFormatter, ...buildPreHandlerChain({
+			arcDecorator,
+			authMw,
+			permissionMw,
+			pluginMw: selectPluginMw("POST", pluginMw),
+			routeGuards
+		})];
+		fastify.route({
+			method: "POST",
+			url: urlPath,
+			schema: routeSchema,
+			attachValidation: true,
+			preHandler: preHandler.length > 0 ? preHandler : void 0,
+			...rateLimitConfig ? { config: rateLimitConfig } : {},
+			handler: async (req, reply) => {
+				const { action, ...data } = req.body;
+				const id = hasId ? req.params.id : "";
+				if (hasId) {
+					const reqWithExtras = req;
+					reqWithExtras.arc = {
+						...reqWithExtras.arc ?? {},
+						entityId: id
+					};
+				}
+				const handler = wrappedHandlers.get(action);
+				if (!handler) throw createError(400, `Invalid action '${action}'. Valid actions: ${actionSubset.join(", ")}`, { validActions: actionSubset });
+				try {
+					return sendControllerResponse(reply, await handler(id, data, req), req);
+				} catch (error) {
+					if (onError) {
+						const { statusCode, error: errorMsg, code } = onError(error, action, id);
+						throw createError(statusCode, errorMsg, code ? { code } : void 0);
+					}
+					const err = error;
+					const statusCode = err.statusCode || err.status || 500;
+					const errorCode = err.code || "ACTION_FAILED";
+					if (statusCode >= 500) req.log.error({
+						err: error,
+						action,
+						id
+					}, "Action handler error");
+					if (error?.name === "ArcError" || error instanceof Error === false) throw error;
+					throw createError(statusCode, err.message || `Failed to execute '${action}' action`, { code: errorCode });
+				}
+			}
+		});
+		fastify.log.debug({
+			actions: actionSubset,
+			mount: urlPath,
+			tag,
+			resourceName
+		}, "[createActionRouter] Registered action endpoint");
+	};
+	registerActionRoute({
+		urlPath: "/:id/action",
+		actionSubset: idBoundActionNames,
+		hasId: true
+	});
+	registerActionRoute({
+		urlPath: "/action",
+		actionSubset: idLessActions,
+		hasId: false
+	});
+}
+/**
+* Build a discriminated body schema for the unified action endpoint.
+*
+* Produces a schema of the form:
+* ```json
+* {
+*   "type": "object",
+*   "required": ["action"],
+*   "properties": {
+*     "action": { "type": "string", "enum": ["dispatch", "approve"] },
+*     "carrier": { "type": "string" }
+*   },
+*   "oneOf": [
+*     {
+*       "properties": {
+*         "action": { "const": "dispatch" },
+*         "carrier": { "type": "string" }       // ← every branch lists the union
+*       },
+*       "required": ["action", "carrier"]
+*     },
+*     {
+*       "properties": {
+*         "action": { "const": "approve" },
+*         "carrier": { "type": "string" }       // ← even though approve doesn't use it
+*       },
+*       "required": ["action"]
+*     }
+*   ]
+* }
+* ```
+*
+* **Why every branch carries the full property union.** AJV's
+* `removeAdditional: 'all'` (Fastify's framework default) interacts badly
+* with `oneOf`: when a branch's `properties` lacks a field, AJV strips it
+* from the body during that branch's evaluation — *even if a different
+* branch would have allowed it*. The strip mutates the body before
+* `oneOf` finishes discriminating, so by the time the matching branch
+* wins, the body has already lost fields. Concretely: `actions: { verify:
+* {}, hold: { schema: z.object({ amount, reason }.optional()) } }` +
+* `POST { action: 'hold', amount: 1, reason }` lands at the handler as
+* `{ action: 'hold' }`. Empirically reproduced and locked at
+* [tests/core/action-discriminator-strip.test.ts](../../tests/core/action-discriminator-strip.test.ts).
+*
+* Listing every action's properties on every branch makes per-branch
+* removeAdditional walks see every caller field as "in this branch's
+* properties," so nothing gets stripped during oneOf evaluation. The
+* `required` array stays per-action, so the handler still gets called
+* only when the matching branch's required-field contract is satisfied.
+* Per-branch `additionalProperties: false` (Zod v4 default) carries
+* through but, under host removeAdditional: 'all', it can no longer
+* reject sibling-action fields — those become silently stripped at top
+* level instead. That's the host's opt-in to stripping; arc's job is to
+* stop accidentally losing the action's *own* declared fields.
+*
+* Under arc's own `createApp` (`removeAdditional: false`), strict-mode
+* rejection still functions normally — see
+* [tests/core/action-strict-schema-parity.test.ts](../../tests/core/action-strict-schema-parity.test.ts).
+*
+* Exported so OpenAPI generation and MCP tool generation can reuse the same
+* schema shape (single source of truth).
+*/
+function buildActionBodySchema(actionEnum, actionSchemas = {}) {
+	const unionProperties = {};
+	const irs = [];
+	for (const actionName of actionEnum) {
+		const ir = normalizeSchemaIR(actionSchemas[actionName]);
+		irs.push({
+			name: actionName,
+			ir
+		});
+		for (const [key, val] of Object.entries(ir.properties)) unionProperties[key] = val;
+	}
+	const branches = [];
+	for (const { name, ir } of irs) branches.push(schemaIRToJsonSchemaBranch({
+		...ir,
+		properties: {
+			...unionProperties,
+			...ir.properties
+		}
+	}, {
+		properties: { action: {
+			type: "string",
+			const: name
+		} },
+		required: ["action"]
+	}));
+	return {
+		type: "object",
+		required: ["action"],
+		properties: {
+			action: {
+				type: "string",
+				enum: [...actionEnum]
+			},
+			...unionProperties
+		},
+		oneOf: branches
+	};
+}
+/**
+* Build OpenAPI description for an action mount from the action map + the
+* permission map for THAT mount's subset. Used by both `/:id/action` and
+* `/action` to render an "Available actions" list with role hints.
+*/
+function buildActionDescription(actions, actionPermissions) {
+	const lines = ["Unified action endpoint for state transitions.\n\n**Available actions:**"];
+	for (const action of Object.keys(actions)) {
+		const roles = actionPermissions[action]?._roles;
+		const roleStr = roles?.length ? ` (requires: ${roles.join(" or ")})` : "";
+		lines.push(`- \`${action}\`${roleStr}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { createActionRouter_exports as n, buildActionBodySchema as t };

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

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

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

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE } from "./types-C_s5moIu.mjs";
+import { n as PUBLIC_SCOPE } from "./types-Bi0r0vjG.mjs";
 import Fastify from "fastify";
 import qs from "qs";
 //#region src/factory/presets.ts
@@ -202,7 +202,7 @@ async function registerArcCore(fastify, config, trackPlugin) {
 	await fastify.register(arcCorePlugin, { emitEvents: config.arcPlugins?.emitEvents !== false });
 	trackPlugin("arc-core");
 	if (config.arcPlugins?.events !== false) {
-		const { default: eventPlugin } = await import("./eventPlugin-CaKTYkYM.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-C2cGqtRO.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -239,15 +239,15 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-graceful-shutdown");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-SM8gghN6.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-TeHE8G-v.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-m1XsgAIJ.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-B4XMSSe7.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = config.stores?.queryCache ?? new (await (import("./memory-UBydS5ku.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-QOLe11D5.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
@@ -256,19 +256,19 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 	}
 	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
 	else {
-		const { default: ssePlugin } = await import("./sse-Bz-5ZeTt.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("./sse-BY6sTy4P.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-Qnvwc-LQ.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-TuOmguhi.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-BUrT5aP4.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-B6mimogM.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -337,7 +337,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-DgoeTyfX.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-Dci0AYLT.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -347,7 +347,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-Bk-AGhkU.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-DpoXQHZ9.mjs").then((n) => n.r);
 	const errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 	await fastify.register(errorHandlerPlugin, errorOpts);
 	trackPlugin("arc-error-handler", errorOpts);
@@ -448,7 +448,7 @@ async function registerResources(fastify, config) {
 	let discoveryPath;
 	let discoveryYieldedZero = false;
 	if (resolvedResources === void 0 && config.resourceDir) {
-		const { loadResources } = await import("./loadResources-DBMQg_Aj.mjs").then((n) => n.n);
+		const { loadResources } = await import("./loadResources-ChQEj8ih.mjs").then((n) => n.n);
 		const { resolve, dirname } = await import("node:path");
 		const { fileURLToPath } = await import("node:url");
 		const rawDir = config.resourceDir;
@@ -575,7 +575,6 @@ const PLUGIN_REGISTRY = {
 		optional: true
 	}
 };
-/** Load a plugin from the registry with helpful error messages. */
 async function loadPlugin(name, logger) {
 	const entry = PLUGIN_REGISTRY[name];
 	if (!entry) throw new Error(`Unknown plugin: ${name}`);
@@ -828,7 +827,10 @@ async function createApp(options) {
 		pluginTimeout: config.pluginTimeout ?? 1e4,
 		...config.bodyLimit !== void 0 ? { bodyLimit: config.bodyLimit } : {},
 		allowErrorHandlerOverride: true,
-		routerOptions: { querystringParser: (str) => qs.parse(str) },
+		routerOptions: {
+			querystringParser: (str) => qs.parse(str),
+			maxParamLength: config.maxParamLength ?? 400
+		},
 		ajv: { customOptions: {
 			coerceTypes: true,
 			useDefaults: true,
@@ -872,7 +874,7 @@ async function createApp(options) {
 	await registerErrorHandler(fastify, config, trackPlugin);
 	await registerResources(fastify, config);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-CK-FNO8E.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-C-gD32oF.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
 	if (config.serializeBigInt) {

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

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

package/dist/docs/index.d.mts

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

package/dist/docs/index.mjs

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

package/dist/{errorHandler-Bk-AGhkU.mjs → errorHandler-DpoXQHZ9.mjs}

@@ -114,25 +114,28 @@ function classify(error, ctx) {
 	}
 	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 (Array.isArray(fastifyErr.validation)) {
+		const arcInternalCode = typeof fastifyErr.code === "string" && fastifyErr.code.startsWith("arc.") ? fastifyErr.code : void 0;
+		const message = arcInternalCode ? error.message || "Validation failed" : "Validation failed";
+		return {
+			code: arcInternalCode ?? "arc.validation_error",
+			message,
+			status: typeof fastifyErr.statusCode === "number" ? fastifyErr.statusCode : 400,
+			details: fastifyValidationDetails(fastifyErr),
+			...fastifyErr.meta ? { meta: fastifyErr.meta } : {}
+		};
+	}
 	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
-		};
-	}
+	const namedMapping = error.name ? ctx.errorMap[error.name] : void 0;
+	if (namedMapping) return {
+		code: namedMapping.code,
+		message: namedMapping.message ?? error.message,
+		status: namedMapping.statusCode
+	};
 	if (error.name === "ValidationError" && "errors" in error) {
 		const errs = error.errors;
 		return {

package/dist/errors-C1lX_jlm.d.mts

@@ -0,0 +1,91 @@
+import { HttpError } from "@classytic/repo-core/errors";
+
+//#region src/utils/errors.d.ts
+interface ErrorOptions {
+  code?: string;
+  statusCode?: number;
+  details?: Record<string, unknown>;
+  cause?: Error;
+}
+/**
+ * Base Arc Error. Implements the canonical `HttpError` contract — `status`
+ * mirrors `statusCode` and `meta` mirrors `details`, so consumers reading
+ * either name see the same value without adapter glue.
+ */
+declare class ArcError extends Error implements HttpError {
+  name: string;
+  readonly code: string;
+  readonly statusCode: number;
+  readonly details?: Record<string, unknown>;
+  readonly cause?: Error;
+  constructor(message: string, options?: ErrorOptions);
+  /** `HttpError.status` mirror — repo-core's `toErrorContract` reads this. */
+  get status(): number;
+  /** `HttpError.meta` mirror — `details` under the canonical name. */
+  get meta(): Record<string, unknown> | undefined;
+}
+declare class NotFoundError extends ArcError {
+  constructor(resource: string, identifier?: string);
+}
+declare class ValidationError extends ArcError {
+  readonly errors: ReadonlyArray<{
+    field: string;
+    message: string;
+  }>;
+  constructor(message: string, errors?: Array<{
+    field: string;
+    message: string;
+  }>);
+}
+declare class UnauthorizedError extends ArcError {
+  constructor(message?: string);
+}
+declare class ForbiddenError extends ArcError {
+  constructor(message?: string);
+}
+declare class ConflictError extends ArcError {
+  constructor(message: string, field?: string);
+}
+declare class OrgRequiredError extends ArcError {
+  readonly organizations?: ReadonlyArray<{
+    id: string;
+    roles?: string[];
+  }>;
+  constructor(message: string, organizations?: Array<{
+    id: string;
+    roles?: string[];
+  }>);
+}
+declare class OrgAccessDeniedError extends ArcError {
+  constructor(orgId?: string);
+}
+declare class RateLimitError extends ArcError {
+  readonly retryAfter?: number;
+  constructor(message?: string, retryAfter?: number);
+}
+declare class ServiceUnavailableError extends ArcError {
+  constructor(message?: string);
+}
+/**
+ * Quick `ArcError` constructor when the bundled subclasses don't fit.
+ *
+ * If `details.code` is a string, it's lifted to the top-level `error.code`
+ * (the canonical wire slot for business signals — `'ORG_CONTEXT_REQUIRED'`,
+ * `'ALL_FIELDS_STRIPPED'`, etc). The same code stays in `details` so
+ * in-process consumers reading `error.details.code` still work. Without
+ * this lift, business codes get buried in `details` and the wire envelope
+ * carries only the status-derived `arc.forbidden` / `arc.bad_request`
+ * fallback — `repo-core`'s `toErrorContract` doesn't surface free-form
+ * `details` objects (its `details[]` array is reserved for validation /
+ * duplicate-key items).
+ */
+declare function createError(statusCode: number, message: string, details?: Record<string, unknown>): ArcError;
+/**
+ * Domain-error escape hatch. Use a hierarchical code that scopes the error
+ * to your package (`'commerce.cart.locked'`, `'payment.gateway.timeout'`).
+ */
+declare function createDomainError(code: string, message: string, statusCode?: number, details?: Record<string, unknown>): ArcError;
+/** Type guard. */
+declare function isArcError(error: unknown): error is ArcError;
+//#endregion
+export { NotFoundError as a, RateLimitError as c, ValidationError as d, createDomainError as f, ForbiddenError as i, ServiceUnavailableError as l, isArcError as m, ConflictError as n, OrgAccessDeniedError as o, createError as p, ErrorOptions as r, OrgRequiredError as s, ArcError as t, UnauthorizedError as u };

package/dist/{eventPlugin-CaKTYkYM.mjs → eventPlugin-C2cGqtRO.mjs}

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

package/dist/{eventPlugin-qXpqTebY.d.mts → eventPlugin-CtHC_av1.d.mts}

@@ -1,4 +1,4 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-CT_52aWU.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "./EventTransport-C-2oAHtw.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/events/defineEvent.d.ts

package/dist/events/index.d.mts

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

package/dist/events/index.mjs

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

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

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

package/dist/events/transports/redis.d.mts

@@ -1,4 +1,4 @@
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-CT_52aWU.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-C-2oAHtw.mjs";
 
 //#region src/events/transports/redis.d.ts
 interface RedisLike {

package/dist/factory/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-DrBaUwyV.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as ResourceLike, f as ResourceModule, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, p as loadResources, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as LoadResourcesOptions } from "../types-D-fYtKjb.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts

package/dist/factory/index.mjs

@@ -1,5 +1,5 @@
-import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-PFegs47-.mjs";
-import { t as loadResources } from "../loadResources-DBMQg_Aj.mjs";
+import { a as edgePreset, c as testingPreset, i as developmentPreset, n as createApp, o as getPreset, s as productionPreset, t as ArcFactory } from "../createApp-DNccuhyI.mjs";
+import { t as loadResources } from "../loadResources-ChQEj8ih.mjs";
 //#region src/factory/edge.ts
 /**
 * Convert a Fastify app into a Web Standards fetch handler.