@classytic/arc 2.23.0 → 2.28.0

package/dist/{core-DQ6rDTyH.mjs → defineResource-2zvVVpxg.mjs}

@@ -1,19 +1,21 @@
 import { s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { r as ForbiddenError } from "./errors-DkO8Nk6-.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-bHblZ9YN.mjs";
-import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-BQ8KNvWC.mjs";
-import { a as selectPluginMw, c as buildRouteHooks, d as buildAuthMiddleware, i as resolveRouterPluginMw, l as resolveRoutePreHandlers, n as buildRateLimitConfig, p as buildArcDecorator, r as buildRouteConfig, s as buildCrudPermissionMw, t as tryRegisterRoute, u as routeHookOptions } from "./registerRoute-CWO6mdYe.mjs";
-import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-Tw4iXtlf.mjs";
-import { t as getUserRoles } from "./types-XTApa8b6.mjs";
-import { t as applyPresets } from "./presets-BOe4Ugkl.mjs";
-import { D as requireAuth } from "./permissions-tbxFHxjZ.mjs";
-import { N as assertValidConfig, l as getDefaultCrudSchemas } from "./utils-CZyeRXTh.mjs";
+import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CSyCxl2V.mjs";
+import { d as DEFAULT_FIELD_WRITE_DENIAL_POLICY, t as BaseController } from "./BaseController-B65zbz9m.mjs";
+import { a as buildRouteHooks, c as buildAuthMiddleware, i as selectPluginMw, n as buildRouteConfig, o as resolveRoutePreHandlers, r as resolveRouterPluginMw, s as routeHookOptions, t as buildRateLimitConfig, u as buildArcDecorator } from "./rateLimit-DrED-C4v.mjs";
+import { a as applyFieldWritePermissions, s as resolveEffectiveRoles } from "./applyPermissionResult-BnyVE9eD.mjs";
+import { r as buildCrudPermissionMw, t as tryRegisterRoute } from "./registerRoute-DTp18Ah_.mjs";
+import { c as getDefaultCrudSchemas } from "./utils-taUVD4p3.mjs";
 import { n as convertRouteSchema, r as ensureSchemaConverter, t as convertOpenApiSchemas } from "./schemaConverter-DJvodiHj.mjs";
 import { i as pipeUIMessageStreamToReply, r as isReadableStream } from "./streaming-BQcW6_Kq.mjs";
 import { t as hasEvents } from "./typeGuards-C9KXUly6.mjs";
-import { a as createCrudHandlers, d as buildRequestScopeProjection, i as resolvePipelineSteps, o as createFastifyHandler, r as buildPipelineHandler, s as createRequestContext, t as resolveActionPermission } from "./actionPermissions-lszoJle1.mjs";
+import { a as createFastifyHandler, i as createCrudHandlers, n as buildPipelineHandler, o as createRequestContext, r as resolvePipelineSteps, u as buildRequestScopeProjection } from "./pipeline-BGRnV-To.mjs";
+import { A as requireAuth } from "./permissions-BrtiBKGs.mjs";
+import { r as getAvailablePresets, t as applyPresets } from "./presets-DwFDVKP0.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CAphcmUG.mjs";
 //#region src/core/middlewares/fieldWrite.ts
 /**
 * Build a preHandler that enforces field-write permissions on the request body.
@@ -53,52 +55,6 @@ function methodCarriesBody(method) {
 	return m === "POST" || m === "PUT" || m === "PATCH";
 }
 //#endregion
-//#region src/core/aggregation/defineAggregation.ts
-/**
-* Declare a single resource aggregation. Exported configs flow into
-* `defineResource({ aggregations: { ... } })` either as named keys or
-* via auto-discovery patterns (loadAggregations — future).
-*
-* @example Inline
-* ```ts
-* defineResource({
-*   name: 'order',
-*   aggregations: {
-*     revenueByStatus: defineAggregation({
-*       groupBy: 'status',
-*       measures: { count: 'count', revenue: 'sum:totalPrice' },
-*       permissions: requireRoles(['admin']),
-*     }),
-*   },
-* });
-* ```
-*
-* @example Multi-file
-* ```ts
-* // orders/aggregations/revenue-by-status.ts
-* import { defineAggregation } from '@classytic/arc';
-*
-* export const revenueByStatus = defineAggregation({
-*   groupBy: 'status',
-*   measures: { count: 'count', revenue: 'sum:totalPrice' },
-*   permissions: requireRoles(['admin']),
-*   timeout: 5000,
-*   cache: { staleTime: 60 },
-* });
-*
-* // orders/order.resource.ts
-* import * as aggregations from './aggregations/index.js';
-*
-* defineResource({
-*   name: 'order',
-*   aggregations,                                  // 30+ entries flow in
-* });
-* ```
-*/
-function defineAggregation(config) {
-	return config;
-}
-//#endregion
 //#region src/core/createCrudRouter.ts
 /**
 * Mount custom routes (from presets or user-defined `routes`) on Fastify.
@@ -338,80 +294,6 @@ function createPermissionMiddleware(permission, resourceName, action) {
 	return buildCrudPermissionMw(permission, resourceName, action);
 }
 //#endregion
-//#region src/core/defineAction.ts
-/**
-* Build an `ActionDefinition` with a typed handler. The literal schema
-* type captured here flows into `data`, so `defineAction({ schema:
-* z.object({...}), handler })` produces fully-typed code with no
-* `as MyShape` cast.
-*
-* Behaviorally identical to a bare `ActionDefinition` object — same
-* validation path (AJV), same permission resolution, same MCP wiring.
-* The runtime shape is unchanged; only the type-level inference is new.
-*/
-function defineAction(config) {
-	return {
-		handler: config.handler,
-		permissions: config.permissions,
-		schema: config.schema,
-		description: config.description,
-		id: config.id,
-		mcp: config.mcp
-	};
-}
-//#endregion
-//#region src/core/defineResource/seams.ts
-/** Plain object test — literals only; class instances must replace, not merge. */
-function isPlainObject(value) {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
-/** Recursive plain-object merge; nested arrays REPLACE (they're value lists). */
-function mergePlain(base, next) {
-	const out = { ...base };
-	for (const [key, value] of Object.entries(next)) {
-		if (value === void 0) continue;
-		const existing = out[key];
-		out[key] = isPlainObject(existing) && isPlainObject(value) ? mergePlain(existing, value) : value;
-	}
-	return out;
-}
-/**
-* Canonical slot-aware merge of a base resource config with host seams.
-* Later seams win over earlier ones; `undefined` values never clobber.
-*
-* Merge semantics (value-driven — no per-slot registry to drift):
-*
-*   - **Top-level arrays CONCAT** — `routes`, `middlewares`, `presets`,
-*     `routeGuards`, `disabledRoutes`: additive collections, base first.
-*   - **Plain objects merge recursively** — `permissions`, `actions`,
-*     `schemaOptions` (incl. `fieldRules`), `aggregations`, `customSchemas`,
-*     `fields`, `cache`, `events`: per-key composition. Arrays NESTED inside
-*     them replace (they're value lists — enums, sort specs), not concat.
-*   - **Everything else last-wins** — class instances (`adapter`,
-*     `controller`, `queryParser`), functions, scalars.
-*
-* The single `as` at the return is the one documented erasure for the
-* {@link AdapterLike}-widened seam slots — inside the helper so no module
-* author ever writes one (mirrors mongokit's one-cast-at-the-boundary rule).
-*/
-function mergeResourceConfig(base, ...seams) {
-	const out = { ...base };
-	for (const seam of seams) {
-		if (!seam) continue;
-		for (const [key, value] of Object.entries(seam)) {
-			if (value === void 0) continue;
-			const existing = out[key];
-			if (Array.isArray(existing) && Array.isArray(value)) out[key] = [...existing, ...value];
-			else if (isPlainObject(existing) && isPlainObject(value)) out[key] = mergePlain(existing, value);
-			else if (Array.isArray(value)) out[key] = [...value];
-			else out[key] = value;
-		}
-	}
-	return out;
-}
-//#endregion
 //#region src/core/defineResource/controller.ts
 /**
 * Phase 4 — pick (or auto-create) the resource's controller.
@@ -1396,7 +1278,7 @@ function buildResourcePlugin(resource) {
 				extensions: resource.extensions
 			});
 			if (resource.actions && Object.keys(resource.actions).length > 0) {
-				const { createActionRouter } = await import("./createActionRouter-BuOv-m4Y.mjs").then((n) => n.n);
+				const { createActionRouter } = await import("./createActionRouter-C-N7z2EL.mjs").then((n) => n.n);
 				createActionRouter(typedInstance, {
 					...normalizeActionsToRouterConfig(resource.actions, resource.actionPermissions, resource.tag, resource.permissions, resource.name, typedInstance.log),
 					resourceName: resource.name,
@@ -1411,7 +1293,7 @@ function buildResourcePlugin(resource) {
 				});
 			}
 			if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
-				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-CgJv_BU_.mjs"), import("./validate-C2mGgSXg.mjs").then((n) => n.r)]);
+				const [{ createAggregationRouter }, { adapterSupportsAggregate, ArcAggregationConfigError }] = await Promise.all([import("./createAggregationRouter-wzwFa_dW.mjs"), import("./validate-Bk44F2yT.mjs").then((n) => n.r)]);
 				const repoForAgg = resource.controller?.repository ?? resource.repository;
 				if (!adapterSupportsAggregate(repoForAgg)) {
 					const undispatchable = Object.entries(resource.aggregations).filter(([, cfg]) => !cfg.materialized).map(([name]) => name);
@@ -1861,6 +1743,289 @@ function mergeUserOpenApiOverrides(openApiSchemas, userOverrides) {
 	};
 }
 //#endregion
+//#region src/core/validateResourceConfig.ts
+/**
+* Resource Configuration Validator
+*
+* Fail-fast validation at definition time.
+* Invalid configs throw immediately with clear, actionable errors.
+*
+* @example
+* const result = validateResourceConfig(config);
+* if (!result.valid) {
+*   console.error(formatValidationErrors(result.errors));
+* }
+*/
+/**
+* Validate a resource configuration
+*/
+function validateResourceConfig(config, options = {}) {
+	const errors = [];
+	const warnings = [];
+	if (!config.name) errors.push({
+		field: "name",
+		message: "Resource name is required",
+		suggestion: "Add a unique resource name (e.g., \"product\", \"user\")"
+	});
+	else if (!/^[a-z][a-z0-9-]*$/i.test(config.name)) errors.push({
+		field: "name",
+		message: `Invalid resource name "${config.name}"`,
+		suggestion: "Use alphanumeric characters and hyphens, starting with a letter"
+	});
+	const crudRoutes = CRUD_OPERATIONS;
+	const disabledRoutes = new Set(config.disabledRoutes ?? []);
+	const enabledCrudRoutes = crudRoutes.filter((route) => !disabledRoutes.has(route));
+	if (!config.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
+		if (!config.adapter) errors.push({
+			field: "adapter",
+			message: "Data adapter is required when CRUD routes are enabled",
+			suggestion: "Provide an adapter: createMongooseAdapter({ model, repository })"
+		});
+		else if (!config.adapter.repository) errors.push({
+			field: "adapter.repository",
+			message: "Adapter must provide a repository",
+			suggestion: "Ensure your adapter returns a valid StandardRepo (see @classytic/repo-core)"
+		});
+	} else if (!config.adapter && !config.routes?.length) warnings.push({
+		field: "config",
+		message: "Resource has no adapter and no routes",
+		suggestion: "Provide either adapter for CRUD or routes for custom logic"
+	});
+	if (config.controller && !options.skipControllerCheck && !config.disableDefaultRoutes) {
+		const ctrl = config.controller;
+		const requiredMethods = CRUD_OPERATIONS;
+		for (const method of requiredMethods) if (typeof ctrl[method] !== "function") errors.push({
+			field: `controller.${method}`,
+			message: `Missing required CRUD method "${method}"`,
+			suggestion: "Extend BaseController which implements IController interface"
+		});
+	}
+	if (config.controller && config.routes) validateRouteHandlers(config.controller, config.routes, errors);
+	if (config.permissions) validatePermissionKeys(config, options, errors, warnings);
+	if (config.presets && !options.allowUnknownPresets) validatePresets(config.presets, errors, warnings);
+	if (config.prefix) {
+		if (!config.prefix.startsWith("/")) errors.push({
+			field: "prefix",
+			message: `Prefix must start with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "/${config.prefix}"`
+		});
+		if (config.prefix.endsWith("/") && config.prefix !== "/") warnings.push({
+			field: "prefix",
+			message: `Prefix should not end with "/" (got "${config.prefix}")`,
+			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
+		});
+	}
+	if (config.routes) {
+		validateRoutes(config.routes, errors);
+		validateRouteCrudCollisions(config, errors);
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+function validateRouteHandlers(controller, routes, errors) {
+	const ctrl = controller;
+	for (const route of routes) if (typeof route.handler === "string") {
+		if (typeof ctrl[route.handler] !== "function") errors.push({
+			field: `routes[${route.method} ${route.path}]`,
+			message: `Handler "${route.handler}" not found on controller`,
+			suggestion: `Add method "${route.handler}" to controller or use a function handler`
+		});
+	}
+}
+function validatePermissionKeys(config, options, _errors, warnings) {
+	const validKeys = /* @__PURE__ */ new Set([...CRUD_OPERATIONS, ...options.additionalPermissionKeys ?? []]);
+	for (const route of config.routes ?? []) if (typeof route.handler === "string") validKeys.add(route.handler);
+	for (const preset of config.presets ?? []) {
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (presetName === "softDelete") {
+			validKeys.add("deleted");
+			validKeys.add("restore");
+		}
+		if (presetName === "slugLookup") validKeys.add("getBySlug");
+		if (presetName === "tree") {
+			validKeys.add("tree");
+			validKeys.add("children");
+			validKeys.add("getTree");
+			validKeys.add("getChildren");
+		}
+	}
+	for (const key of Object.keys(config.permissions ?? {})) if (!validKeys.has(key)) warnings.push({
+		field: `permissions.${key}`,
+		message: `Unknown permission key "${key}"`,
+		suggestion: `Valid keys: ${Array.from(validKeys).join(", ")}`
+	});
+}
+function validatePresets(presets, errors, warnings) {
+	const availablePresets = getAvailablePresets();
+	for (const preset of presets) {
+		if (typeof preset === "object" && ("middlewares" in preset || "routes" in preset)) continue;
+		const presetName = typeof preset === "string" ? preset : preset.name;
+		if (!availablePresets.includes(presetName)) errors.push({
+			field: "presets",
+			message: `Unknown preset "${presetName}"`,
+			suggestion: `Available presets: ${availablePresets.join(", ")}`
+		});
+		if (typeof preset === "object") validatePresetOptions(preset, warnings);
+	}
+}
+function validatePresetOptions(preset, warnings) {
+	const validOptions = {
+		slugLookup: ["slugField"],
+		tree: ["parentField"],
+		softDelete: ["deletedField"],
+		ownedByUser: ["ownerField"],
+		multiTenant: ["tenantField", "allowPublic"]
+	}[preset.name] ?? [];
+	const providedOptions = Object.keys(preset).filter((k) => k !== "name");
+	for (const opt of providedOptions) if (!validOptions.includes(opt)) warnings.push({
+		field: `presets[${preset.name}].${opt}`,
+		message: `Unknown option "${opt}" for preset "${preset.name}"`,
+		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
+	});
+}
+/**
+* Detect collisions between user-declared `routes:` entries and the
+* auto-CRUD route table that `createCrudRouter` will register.
+*
+* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
+* `create` boots fine through `defineResource()` and only blows up at
+* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
+* That error doesn't mention `disabledRoutes` and doesn't distinguish
+* "you collided with auto-CRUD" from "you collided with yourself" — so
+* the consumer has to grep arc's source to discover the fix.
+*
+* We surface the fix in the error message, naming the conflicting op
+* and the literal line to add.
+*
+* Honored config:
+*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
+*   - `disabledRoutes: ['create']` → that op's path is free for custom use
+*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
+*/
+function validateRouteCrudCollisions(config, errors) {
+	if (config.disableDefaultRoutes) return;
+	if (!config.routes || config.routes.length === 0) return;
+	const updateMethod = config.updateMethod ?? "PATCH";
+	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
+	const disabled = new Set(config.disabledRoutes ?? []);
+	const crudTable = [
+		{
+			op: "list",
+			method: "GET",
+			path: "/"
+		},
+		{
+			op: "get",
+			method: "GET",
+			path: "/:id"
+		},
+		{
+			op: "create",
+			method: "POST",
+			path: "/"
+		},
+		...updateMethods.map((m) => ({
+			op: "update",
+			method: m,
+			path: "/:id"
+		})),
+		{
+			op: "delete",
+			method: "DELETE",
+			path: "/:id"
+		}
+	];
+	for (const [i, route] of config.routes.entries()) {
+		if (!route.method || !route.path) continue;
+		for (const crud of crudTable) {
+			if (disabled.has(crud.op)) continue;
+			if (route.method !== crud.method || route.path !== crud.path) continue;
+			errors.push({
+				field: `routes[${i}]`,
+				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
+				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
+			});
+		}
+	}
+}
+function validateRoutes(routes, errors) {
+	const validMethods = [
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS",
+		"HEAD"
+	];
+	const seenRoutes = /* @__PURE__ */ new Set();
+	for (const [i, route] of routes.entries()) {
+		if (!validMethods.includes(route.method)) errors.push({
+			field: `routes[${i}].method`,
+			message: `Invalid HTTP method "${route.method}"`,
+			suggestion: `Valid methods: ${validMethods.join(", ")}`
+		});
+		if (!route.path) errors.push({
+			field: `routes[${i}].path`,
+			message: "Route path is required"
+		});
+		else if (!route.path.startsWith("/")) errors.push({
+			field: `routes[${i}].path`,
+			message: `Route path must start with "/" (got "${route.path}")`,
+			suggestion: `Change to "/${route.path}"`
+		});
+		const routeWithRefs = route;
+		if (!route.handler && typeof routeWithRefs.controllerMethod !== "function") errors.push({
+			field: `routes[${i}].handler`,
+			message: "Route must declare either `handler` (string / function) or `controllerMethod`",
+			suggestion: "Prefer `controllerMethod: (c: MyController) => c.method` for typed handler refs."
+		});
+		const routeKey = `${route.method} ${route.path}`;
+		if (seenRoutes.has(routeKey)) errors.push({
+			field: `routes[${i}]`,
+			message: `Duplicate route "${routeKey}"`
+		});
+		seenRoutes.add(routeKey);
+	}
+}
+/**
+* Format validation errors for display
+*/
+function formatValidationErrors(resourceName, result) {
+	const lines = [];
+	if (result.errors.length > 0) {
+		lines.push(`Resource "${resourceName}" validation failed:`);
+		lines.push("");
+		lines.push("ERRORS:");
+		for (const err of result.errors) {
+			lines.push(`  ✗ ${err.field}: ${err.message}`);
+			if (err.suggestion) lines.push(`    → ${err.suggestion}`);
+		}
+	}
+	if (result.warnings.length > 0) {
+		if (lines.length > 0) lines.push("");
+		lines.push("WARNINGS:");
+		for (const warn of result.warnings) {
+			lines.push(`  ⚠ ${warn.field}: ${warn.message}`);
+			if (warn.suggestion) lines.push(`    → ${warn.suggestion}`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Validate and throw if invalid
+*/
+function assertValidConfig(config, options) {
+	const result = validateResourceConfig(config, options);
+	if (!result.valid) {
+		const errorMsg = formatValidationErrors(config.name ?? "unknown", result);
+		throw new Error(errorMsg);
+	}
+}
+//#endregion
 //#region src/core/defineResource/validate.ts
 /**
 * CRUD op names — kept module-scope (vs allocated per `defineResource()`
@@ -2023,102 +2188,4 @@ function defineResource(config) {
 	return resource;
 }
 //#endregion
-//#region src/core/defineResourceVariants.ts
-/**
-* Define multiple resources from a shared base config and per-variant overrides.
-*
-* Each variant is independently passed through `defineResource()` — the
-* returned `ResourceDefinition`s are real, fully-registered resources.
-* Register each one's plugin in your app:
-*
-* ```typescript
-* await app.register(articlePublic.toPlugin());
-* await app.register(articleAdmin.toPlugin());
-* ```
-*
-* @param base    Shared config — adapter, queryParser, schemaOptions, hooks, etc.
-*                Must NOT include `name` or `prefix` (those are per-variant).
-* @param variants  Map of variant key → override. Each variant must declare
-*                  its own `name` and `prefix`. Other fields override the base.
-* @returns A record where each key from `variants` maps to a real
-*          `ResourceDefinition` ready for `.toPlugin()` registration.
-*/
-function defineResourceVariants(base, variants) {
-	const out = {};
-	for (const key of Object.keys(variants)) {
-		const override = variants[key];
-		out[key] = defineResource({
-			...base,
-			...override
-		});
-	}
-	return out;
-}
-//#endregion
-//#region src/core/entityHelpers.ts
-/**
-* Per-request entity helpers — read the resource binding (idField + the
-* URL `:id` value) off `req.arc`.
-*
-* Action handlers receive their `id` argument as the raw URL `:id` value.
-* When the resource declares a custom `idField` (`slug`, `reportId`, …)
-* that's NOT the document `_id`, a naive `Model.findById(id)` silently
-* returns null. The historical footgun was a `findById(id)` typo where
-* the handler author hadn't realised that `:id` resolves to the friendly
-* handle.
-*
-* `getEntityQuery(req)` produces the canonical filter shape so handlers
-* compose lookups with no resource-config recall:
-*
-* ```ts
-* actions: {
-*   archive: {
-*     handler: async (id, data, req) => {
-*       const doc = await Model.findOne(getEntityQuery(req));
-*       if (!doc) throw new NotFoundError("Order");
-*       // ...
-*     },
-*   },
-* }
-* ```
-*
-* The router populates `req.arc.idField` and `req.arc.entityId` before
-* invoking the handler — these helpers are zero-cost reads.
-*/
-/**
-* Read the resource's configured `idField` for the current request.
-* Falls back to the framework default (`_id`) when the route hasn't
-* bound an idField — keeps handlers safe to author without checking
-* the resource config.
-*/
-function getEntityIdField(req) {
-	return req.arc?.idField ?? "_id";
-}
-/**
-* Read the URL `:id` path param value as the resource handle.
-* Returns `undefined` when the route has no `:id` segment (collection
-* routes) — handlers that need the entity must be on row routes.
-*/
-function getEntityId(req) {
-	if (req.arc?.entityId !== void 0) return req.arc.entityId;
-	return req.params?.id;
-}
-/**
-* Compose a `findOne` filter that resolves the current request's
-* entity, regardless of whether the resource binds `_id` or a custom
-* field. Idiomatic shape for arc action handlers.
-*
-* ```ts
-* const doc = await Model.findOne(getEntityQuery(req));
-* ```
-*
-* Returns `{}` when the route has no entity context (collection routes
-* or tests bypassing the router) — caller decides what that means.
-*/
-function getEntityQuery(req) {
-	const id = getEntityId(req);
-	if (id === void 0) return {};
-	return { [getEntityIdField(req)]: id };
-}
-//#endregion
-export { defineResource as a, defineAction as c, defineAggregation as d, defineResourceVariants as i, createCrudRouter as l, getEntityIdField as n, ResourceDefinition as o, getEntityQuery as r, mergeResourceConfig as s, getEntityId as t, createPermissionMiddleware as u };
+export { ResourceDefinition as a, validateResourceConfig as i, assertValidConfig as n, createCrudRouter as o, formatValidationErrors as r, createPermissionMiddleware as s, defineResource as t };

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-BBsvQt7U.mjs";
+import { p as RegistryEntry } from "../index-DPRH0Cme.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.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-XTApa8b6.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-jSDx-VDv.mjs";
+import { n as getUserRoles } from "../userHelpers-Cg_y3fBz.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-BLV4OMXb.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/{elevation-COpYKt2h.mjs → elevation-CIz1GjGm.mjs}

@@ -1,6 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BvlQSDMB.mjs";
+import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
 import fp from "fastify-plugin";
 //#region src/scope/elevation.ts
 var elevation_exports = /* @__PURE__ */ __exportAll({
@@ -18,7 +19,7 @@ const elevationPlugin = async (fastify, opts = {}) => {
 	const authenticateWithElevation = async (request, reply) => {
 		await originalAuthenticate.call(fastify, request, reply);
 		if (reply.sent) return;
-		if (request.headers[scopeHeader] !== "platform") return;
+		if (requireSingleHeaderValue(request.headers, scopeHeader) !== "platform") return;
 		const user = request.user;
 		if (!user) {
 			log.debug("Elevation requested but no user after auth");
@@ -45,7 +46,7 @@ const elevationPlugin = async (fastify, opts = {}) => {
 			});
 			return;
 		}
-		const orgId = request.headers[orgHeader];
+		const orgId = requireSingleHeaderValue(request.headers, orgHeader);
 		const userId = String(user.id ?? user._id ?? "unknown");
 		request.scope = {
 			kind: "elevated",

package/dist/{eventPlugin-A6EbthXR.d.mts → eventPlugin-Bg3cP2_u.d.mts}

@@ -140,12 +140,41 @@ interface RetryOptions {
    */
   transport?: Pick<EventTransport, "deadLetter">;
   /**
-   * Callback when all retries are exhausted. The event is "dead".
-   * Use this to publish to a `$deadLetter` channel, log, alert, etc.
+   * DURABLE dead-letter persistence for exhausted events (custom store,
+   * `$deadLetter` publisher, ...). Treated exactly like
+   * {@link transport}.deadLetter: a failure follows {@link dlqFailureMode}
+   * — rethrow by default, so the transport redelivers instead of
+   * acknowledging an event that is neither processed nor persisted.
    *
-   * Fires in addition to {@link transport} routing if both are set.
+   * This is what `eventPlugin({ deadLetterQueue })` wires. Use
+   * {@link onDead} for metrics/alerts whose failure must NOT affect
+   * acknowledgement.
+   */
+  deadLetter?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  /**
+   * OBSERVABILITY callback when all retries are exhausted (metrics,
+   * alerting, logging). Fires in addition to {@link transport} /
+   * {@link deadLetter} routing. Failures are logged and swallowed — this
+   * callback can never affect whether the event is acknowledged; durable
+   * persistence belongs in {@link deadLetter}.
    */
   onDead?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
+  /**
+   * What to do when `transport.deadLetter()` ITSELF fails after retries are
+   * exhausted.
+   *
+   *  - `'rethrow'` (default) — the wrapper throws, so the transport treats
+   *    the handler as failed: an at-least-once transport (Redis Streams,
+   *    SQS) keeps the original message pending and redelivers it. The only
+   *    mode that cannot LOSE the event — returning normally would
+   *    acknowledge a message that was neither processed nor persisted.
+   *  - `'log-and-drop'` — log the DLQ failure and return normally,
+   *    acknowledging the message. Only correct when losing the event is
+   *    acceptable (metrics, notifications).
+   *
+   * @default 'rethrow'
+   */
+  dlqFailureMode?: "rethrow" | "log-and-drop";
   /**
    * Optional name for logging + written into `DeadLetteredEvent.handlerName`.
    */
@@ -246,6 +275,12 @@ interface EventPluginOptions {
    * Dead letter queue for events that exhaust all retries.
    * Requires `retry` to be enabled. If `retry` is set but no custom `store`,
    * failed events are published to the `$deadLetter` event type by default.
+   *
+   * The store is DURABLE persistence: if it throws, the wrapped handler
+   * rethrows (per `retry.dlqFailureMode`, default `'rethrow'`) so an
+   * at-least-once transport redelivers instead of acknowledging an event
+   * that was neither processed nor dead-lettered. Metrics/alerting belongs
+   * in `retry.onDead`, whose failures never affect acknowledgement.
    */
   deadLetterQueue?: {
     /** Custom store function. If omitted, publishes to '$deadLetter' event type. */