@classytic/arc 2.19.0 → 2.20.0

package/dist/{createApp--703hQE1.mjs → createApp-D6uwzCKu.mjs}

@@ -245,7 +245,7 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-caching", opts);
 	}
 	if (config.arcPlugins?.queryCache) {
-		const { queryCachePlugin } = await import("./queryCachePlugin-emHb0CuX.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-DzqLN904.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
 		const store = config.stores?.queryCache ?? new (await (import("./memory-CLXA2VeJ.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
@@ -384,6 +384,134 @@ function createOptionalAuthenticate(authenticate) {
 	};
 }
 //#endregion
+//#region src/factory/module.ts
+/**
+* Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+* (this is where a dynamic `import()` fires); a promise (or plain module) is
+* awaited. Called once per module at the start of the bootstrap phase.
+*/
+async function resolveModule(input) {
+	const resolved = typeof input === "function" ? await input() : await input;
+	if (!resolved || typeof resolved !== "object" || typeof resolved.name !== "string") throw new Error("[arc] a `modules` entry resolved to something that is not an ArcModule (expected an object with a string `name`). Check dynamic-import thunks return `createXModule(deps)` (or the module object), not the namespace.");
+	return resolved;
+}
+/**
+* Order modules for composition by their `dependsOn` edges — a STABLE
+* topological sort. Called once at the start of the bootstrap phase; every
+* subsequent phase (bootstrap, resources, afterResources, and reverse-order
+* onClose) iterates the returned list, so a module's declared dependencies are
+* always composed before it.
+*
+* "Stable" = modules with no edge between them keep their original list order,
+* so declaring `dependsOn` on one module never silently reorders an unrelated
+* one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+* returned unchanged.
+*
+* Fail-fast — throws (never reorders past a broken contract) on:
+*   - duplicate module names (the name is the graph key)
+*   - a `dependsOn` name not present in the composed set
+*   - a self-reference (`dependsOn` includes the module's own name)
+*   - a dependency cycle (reports the concrete `a → b → … → a` path)
+*/
+function orderModules(modules) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const m of modules) {
+		if (byName.has(m.name)) throw new Error(`[arc] Duplicate module name "${m.name}" — composed twice; check your modules array.`);
+		byName.set(m.name, m);
+	}
+	for (const m of modules) for (const dep of m.dependsOn ?? []) {
+		if (dep === m.name) throw new Error(`[arc] module "${m.name}" dependsOn itself — remove the self-reference.`);
+		if (!byName.has(dep)) throw new Error(`[arc] module "${m.name}" dependsOn "${dep}", which is not composed. Add the "${dep}" module to createApp({ modules }) (before this one is fine — arc orders them), or drop the dependency. Composed modules: ${[...byName.keys()].join(", ") || "(none)"}.`);
+	}
+	if (modules.every((m) => !m.dependsOn || m.dependsOn.length === 0)) return [...modules];
+	const originalIndex = /* @__PURE__ */ new Map();
+	let nextIndex = 0;
+	for (const m of modules) originalIndex.set(m.name, nextIndex++);
+	const pendingDeps = new Map(modules.map((m) => [m.name, (m.dependsOn ?? []).length]));
+	const dependents = /* @__PURE__ */ new Map();
+	for (const m of modules) for (const dep of m.dependsOn ?? []) {
+		const list = dependents.get(dep);
+		if (list) list.push(m.name);
+		else dependents.set(dep, [m.name]);
+	}
+	const ordered = [];
+	const remaining = new Set(modules.map((m) => m.name));
+	while (remaining.size > 0) {
+		let pick;
+		let pickIndex = Number.POSITIVE_INFINITY;
+		for (const name of remaining) {
+			if (pendingDeps.get(name) !== 0) continue;
+			const index = originalIndex.get(name) ?? Number.POSITIVE_INFINITY;
+			if (index < pickIndex) {
+				pick = name;
+				pickIndex = index;
+			}
+		}
+		if (pick === void 0) throw new Error(describeModuleCycle(remaining, byName));
+		const picked = byName.get(pick);
+		if (!picked) throw new Error(`[arc] internal: ordered module "${pick}" is missing from the index`);
+		ordered.push(picked);
+		remaining.delete(pick);
+		for (const dependent of dependents.get(pick) ?? []) pendingDeps.set(dependent, (pendingDeps.get(dependent) ?? 1) - 1);
+	}
+	return ordered;
+}
+/** Walk the still-unordered subgraph for one concrete cycle path. */
+function describeModuleCycle(remaining, byName) {
+	const stack = [];
+	const onStack = /* @__PURE__ */ new Set();
+	const done = /* @__PURE__ */ new Set();
+	let cycle = null;
+	const walk = (name) => {
+		if (cycle) return;
+		stack.push(name);
+		onStack.add(name);
+		for (const dep of byName.get(name)?.dependsOn ?? []) {
+			if (!remaining.has(dep)) continue;
+			if (onStack.has(dep)) {
+				cycle = [...stack.slice(stack.indexOf(dep)), dep];
+				return;
+			}
+			if (!done.has(dep)) walk(dep);
+			if (cycle) return;
+		}
+		onStack.delete(name);
+		stack.pop();
+		done.add(name);
+	};
+	for (const name of remaining) {
+		if (!done.has(name)) walk(name);
+		if (cycle) break;
+	}
+	return `[arc] module dependency cycle: ${cycle ? cycle.join(" → ") : [...remaining].join(", ")}. Modules cannot dependsOn each other circularly — break it with a shared module both point at, or wire the softer direction through an event/port instead of a hard dependsOn.`;
+}
+/**
+* Identity helper for authoring a typed module — mirrors `defineResource`.
+* Gives inference + a single obvious construction site; does no work.
+*
+* `TExports` is inferred from the `bootstrap` return value, so a module
+* author gets a typed public export for free:
+*
+* ```ts
+* export const accountingModule = (deps: Deps) =>
+*   defineModule({
+*     name: "accounting",
+*     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+*   });
+* ```
+*/
+function defineModule(module) {
+	return module;
+}
+function getModuleExports(fastify, name) {
+	const modules = fastify.arc?.modules;
+	if (!modules || !Object.hasOwn(modules, name)) {
+		const available = modules ? Object.keys(modules) : [];
+		throw new Error(`[arc] no public export recorded for module "${name}".\nA module's export is its bootstrap() return value; it is readable only AFTER that module's bootstrap ran (dependsOn / list order = init order).\nModules with recorded exports: ${available.length ? available.join(", ") : "(none)"}.`);
+	}
+	return modules[name];
+}
+//#endregion
 //#region src/factory/registerResources.ts
 function isResourcesFactory(value) {
 	return typeof value === "function";
@@ -401,15 +529,29 @@ async function registerOne(parent, resource) {
 	}
 }
 /**
-* Execute the full resource lifecycle:
-* 1. plugins()                   — infra (DB, data, webhooks)
-* 2. bootstrap[]                 — domain init (singletons, event handlers)
-* 3. resources factory (if any)  — resolved AFTER bootstrap, so engine-backed
+* Execute the full resource lifecycle. The module graph is resolved + ordered
+* by `dependsOn` (stable topological sort) once, up FRONT — before any
+* side-effecting plugin — so a bad graph fails fast with no half-initialised
+* infra. Every phase below iterates that order; each module phase runs BEFORE
+* its app-level counterpart:
+*
+* 1.  resolve + orderModules     — validate the graph (dup names, missing/self
+*                                  deps, cycles fail fast) BEFORE side effects
+* 2.  plugins()                  — app infra (DB, data, webhooks)
+* 3.  module.plugins             — module infra, dependsOn order, before bootstraps
+* 4a. module.bootstrap           — engine init (return value → arc.modules[name])
+* 4b. bootstrap[]                — app-level domain init
+* 5.  resources factory (if any) — resolved AFTER bootstrap, so engine-backed
 *                                  adapters can `await ensureEngine()` and pass
 *                                  live models/repos into `defineResource(...)`
-* 4. resources[]                 — register each (split by prefix)
-* 5. afterResources()            — post-registration wiring
-* 6. onReady/onClose             — lifecycle hooks
+* 5b. module resources           — RESOLVED after the app factory, but PREPENDED
+*                                  so they REGISTER before app resources (two
+*                                  orderings, both intentional — see §5b)
+* 6.  module.afterResources → afterResources()  — post-registration wiring
+* 7.  onReady                    — lifecycle hook
+* 7b. onClose                    — module.onClose (reverse composition order)
+*                                  THEN app onClose, in ONE hook so module
+*                                  teardown runs before shared infra closes.
 */
 async function registerResources(fastify, config) {
 	if (config.preset === "production") {
@@ -422,10 +564,37 @@ async function registerResources(fastify, config) {
 			strictResourceDir: true
 		};
 	}
+	const modules = orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
 	if (config.plugins) {
 		await config.plugins(fastify);
 		fastify.log.debug("Custom plugins registered");
 	}
+	for (const m of modules) {
+		if (!m.plugins) continue;
+		try {
+			await m.plugins(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" plugins() threw: ${msg}`, { cause: err });
+		}
+	}
+	for (const m of modules) {
+		if (!m.bootstrap) continue;
+		let exported;
+		try {
+			exported = await m.bootstrap(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" bootstrap threw: ${msg}`, { cause: err });
+		}
+		if (exported !== void 0) {
+			const arc = fastify.arc;
+			if (!arc) throw new Error(`[arc] module "${m.name}" returned a public export but fastify.arc is not decorated — arcCorePlugin must register first.`);
+			if (!arc.modules) arc.modules = Object.create(null);
+			arc.modules[m.name] = exported;
+		}
+	}
+	if (modules.length) fastify.log.debug(`${modules.length} module(s) composed (in dependency order): ${modules.map((m) => m.name).join(" → ")}`);
 	if (config.bootstrap?.length) {
 		for (const init of config.bootstrap) await init(fastify);
 		fastify.log.debug(`${config.bootstrap.length} bootstrap function(s) executed`);
@@ -462,6 +631,20 @@ async function registerResources(fastify, config) {
 		}
 		resolvedResources = discovered;
 	}
+	if (modules.length) {
+		const moduleResources = [];
+		for (const m of modules) {
+			if (!m.resources) continue;
+			try {
+				const rs = typeof m.resources === "function" ? await m.resources(fastify) : m.resources;
+				moduleResources.push(...rs);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`[arc] module "${m.name}" resources factory threw: ${msg}. Check the module's bootstrap ran and its adapters received booted engines.`, { cause: err });
+			}
+		}
+		if (moduleResources.length) resolvedResources = [...moduleResources, ...resolvedResources ?? []];
+	}
 	if (resolvedResources && resolvedResources.length > 0) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const resource of resolvedResources) if (resource.name) {
@@ -490,6 +673,15 @@ async function registerResources(fastify, config) {
 		const hints = discoveryYieldedZero ? ` but yielded 0 resources. Check the path, file naming (*.resource.{ts,js,mts,mjs}), and runtime layout (src/ vs dist/). Use \`strictResourceDir: true\` to fail boot.` : "";
 		fastify.log.warn(`0 resources registered${prefix}${scanned}${hints}`);
 	}
+	for (const m of modules) {
+		if (!m.afterResources) continue;
+		try {
+			await m.afterResources(fastify);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`[arc] module "${m.name}" afterResources() threw: ${msg}`, { cause: err });
+		}
+	}
 	if (config.afterResources) {
 		await config.afterResources(fastify);
 		fastify.log.debug("afterResources hook executed");
@@ -500,12 +692,12 @@ async function registerResources(fastify, config) {
 			await onReady(fastify);
 		});
 	}
-	if (config.onClose) {
-		const onClose = config.onClose;
-		fastify.addHook("onClose", async () => {
-			await onClose(fastify);
-		});
-	}
+	const closers = modules.filter((m) => m.onClose).reverse();
+	const appOnClose = config.onClose;
+	if (closers.length || appOnClose) fastify.addHook("onClose", async () => {
+		for (const m of closers) await m.onClose?.(fastify);
+		if (appOnClose) await appOnClose(fastify);
+	});
 }
 //#endregion
 //#region src/factory/registerSecurity.ts
@@ -522,7 +714,8 @@ function buildRateLimitOpts(input) {
 	};
 	const matchesPath = compilePathMatcher(skipPaths);
 	const combined = async (req, key) => {
-		if (matchesPath((req.url ?? "").split("?", 1)[0] ?? "")) return true;
+		const path = (req.url ?? "").split("?", 1)[0] ?? "";
+		if (matchesPath(path)) return true;
 		if (typeof allowList === "function") return await allowList(req, key);
 		if (Array.isArray(allowList)) return allowList.includes(key);
 		return false;
@@ -711,7 +904,7 @@ var createApp_exports = /* @__PURE__ */ __exportAll({
 	createApp: () => createApp,
 	resolveLoggerConfig: () => resolveLoggerConfig
 });
-const MEMORY_STORE_NAMES = new Set(["memory", "memory-cache"]);
+const MEMORY_STORE_NAMES = /* @__PURE__ */ new Set(["memory", "memory-cache"]);
 /**
 * Default redact paths layered into Fastify's pino logger when the host
 * doesn't supply a `logger.redact` of their own. Covers the common token /
@@ -947,4 +1140,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { edgePreset as a, testingPreset as c, developmentPreset as i, createApp as n, getPreset as o, createApp_exports as r, productionPreset as s, ArcFactory as t };
+export { getModuleExports as a, developmentPreset as c, productionPreset as d, testingPreset as f, defineModule as i, edgePreset as l, createApp as n, orderModules as o, createApp_exports as r, resolveModule as s, ArcFactory as t, getPreset as u };

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { p as RegistryEntry } from "../index-CUTG2Cuo.mjs";
+import { p as RegistryEntry } from "../index-_--GyzcO.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-BE6wFpYv.mjs";
 import { FastifyPluginAsync } from "fastify";
 

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-DZ-5a5Op.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-Dq6RbEGK.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {

package/dist/events/index.mjs

@@ -417,12 +417,13 @@ function repositoryAsOutboxStore(repository) {
 		},
 		async getPending(limit) {
 			const now = /* @__PURE__ */ new Date();
-			return unwrapDocs(await r.getAll({
+			const result = await r.getAll({
 				filters: claimableFilter(now),
 				sort: { createdAt: 1 },
 				page: 1,
 				limit
-			})).map((d) => d.event).filter(isWellFormed);
+			});
+			return unwrapDocs(result).map((d) => d.event).filter(isWellFormed);
 		},
 		async claimPending(options) {
 			const limit = options?.limit ?? DEFAULT_CLAIM_LIMIT;
@@ -493,12 +494,13 @@ function repositoryAsOutboxStore(repository) {
 			}
 		},
 		async getDeadLettered(limit) {
-			return unwrapDocs(await r.getAll({
+			const result = await r.getAll({
 				filters: eq("status", "dead_letter"),
 				sort: { [idField]: 1 },
 				page: 1,
 				limit
-			})).filter((d) => isWellFormed(d.event)).map((d) => ({
+			});
+			return unwrapDocs(result).filter((d) => isWellFormed(d.event)).map((d) => ({
 				event: d.event,
 				error: {
 					message: d.lastError?.message ?? "unknown",
@@ -513,13 +515,14 @@ function repositoryAsOutboxStore(repository) {
 			const cutoff = new Date(Date.now() - olderThanMs);
 			let totalDeleted = 0;
 			for (;;) {
-				const batch = unwrapDocs(await r.getAll({
+				const result = await r.getAll({
 					filters: and(eq("status", "delivered"), lte("deliveredAt", cutoff)),
 					sort: { deliveredAt: 1 },
 					page: 1,
 					limit: DEFAULT_PURGE_BATCH,
 					select: idField
-				}));
+				});
+				const batch = unwrapDocs(result);
 				if (batch.length === 0) break;
 				const ids = batch.map((d) => d[idField]);
 				const res = await r.deleteMany(anyOf(idField, ids));

package/dist/factory/index.d.mts

@@ -1,4 +1,5 @@
-import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, f as LoadResourcesOptions, h as loadResources, i as CustomAuthenticatorOption, l as UnderPressureOptions, m as ResourceModule, n as BetterAuthOption, o as JwtAuthOption, p as ResourceLike, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-9_wtNPsI.mjs";
+import { a as getModuleExports, c as LoadResourcesOptions, d as loadResources, i as defineModule, l as ResourceLike, n as ArcModuleInput, o as orderModules, r as ArcModuleRegistry, s as resolveModule, t as ArcModule, u as ResourceModule } from "../module-JYH9V0I8.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, d as preloadResourcesAsync, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption, u as preloadResources } from "../types-BHMKlMBU.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 
 //#region src/factory/createApp.d.ts
@@ -95,4 +96,4 @@ declare const edgePreset: Partial<CreateAppOptions>;
  */
 declare function getPreset(name: "production" | "development" | "testing" | "edge"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };
+export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type MultipartOptions, type RawBodyOptions, type ResourceLike, type ResourceModule, type UnderPressureOptions, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/factory/index.mjs

@@ -1,5 +1,5 @@
 import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-CHw3_oA_.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--703hQE1.mjs";
+import { a as getModuleExports, c as developmentPreset, d as productionPreset, f as testingPreset, i as defineModule, l as edgePreset, n as createApp, o as orderModules, s as resolveModule, t as ArcFactory, u as getPreset } from "../createApp-D6uwzCKu.mjs";
 import { t as loadResources } from "../loadResources-B8UmpITt.mjs";
 //#region src/factory/edge.ts
 /**
@@ -47,4 +47,4 @@ function toFetchHandler(app, options = {}) {
 	};
 }
 //#endregion
-export { ArcFactory, createApp, developmentPreset, edgePreset, getPreset, loadResources, preloadResources, preloadResourcesAsync, productionPreset, testingPreset, toFetchHandler };
+export { ArcFactory, createApp, defineModule, developmentPreset, edgePreset, getModuleExports, getPreset, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveModule, testingPreset, toFetchHandler };

package/dist/{fastify-augmentation-D-5_yQJi.d.mts → fastify-augmentation-CCQJEDgh.d.mts}

@@ -1,5 +1,6 @@
-import { bn as HookSystem, z as ResourceRegistry } from "./index-CUTG2Cuo.mjs";
+import { bn as HookSystem, z as ResourceRegistry } from "./index-_--GyzcO.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
+import { r as ArcModuleRegistry } from "./module-JYH9V0I8.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/core/arcCorePlugin.d.ts
@@ -28,6 +29,16 @@ interface ArcCore {
   externalOpenApiPaths: ExternalOpenApiPaths[];
   /** Registered plugins for introspection */
   plugins: Map<string, PluginMeta>;
+  /**
+   * Module public exports — `bootstrap()` return values keyed by module name
+   * (see `src/factory/module.ts`). Read via `getModuleExports(fastify, name)`:
+   * augment `ArcModuleRegistry` once and the name infers the export type;
+   * otherwise pass it inline. `Partial<ArcModuleRegistry>` gives augmented
+   * apps typed direct access (`fastify.arc.modules.order`), while the
+   * `Record<string, unknown>` intersection keeps un-augmented reads open.
+   * Populated lazily by `registerResources` — absent until a module exports.
+   */
+  modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
 }
 declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
 declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;

package/dist/{generate-Brans3fW.mjs → generate-usRSdQmP.mjs}

@@ -1,4 +1,4 @@
-import { t as pluralize } from "./pluralize-DccFV9R7.mjs";
+import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/generate/name-helpers.ts
@@ -601,9 +601,10 @@ async function generate(type, args) {
 	if (!type) throw new Error("Missing type argument\nUsage: arc generate <resource|controller|model|repository|schemas> <name>");
 	const [name, ...restArgs] = args;
 	if (!name) throw new Error("Missing name argument\nUsage: arc generate <type> <name>\nExample: arc generate resource product");
+	if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(name)) throw new Error(`Invalid name "${name}". Use kebab-case: a letter followed by letters, digits, or hyphens (e.g. 'product', 'order-line'). No slashes, dots, spaces, or path segments.`);
 	const capitalizedName = toPascalCase(name);
 	const lowerName = name.toLowerCase();
-	if ((type === "resource" || type === "r" || type === "model" || type === "m") && new Set([
+	if ((type === "resource" || type === "r" || type === "model" || type === "m") && (/* @__PURE__ */ new Set([
 		"user",
 		"session",
 		"account",
@@ -614,7 +615,7 @@ async function generate(type, args) {
 		"team",
 		"team-member",
 		"apikey"
-	]).has(lowerName)) {
+	])).has(lowerName)) {
 		console.warn(`\n[arc generate] "${lowerName}" is a Better Auth-owned collection.\nBetter Auth's organization/admin/bearer plugins write this collection directly,\nso generating a parallel arc model would create a duplicate registration.\n\nRecommended pattern:\n  import { createBetterAuthOverlay } from '@classytic/mongokit/better-auth';\n  const adapter = await createBetterAuthOverlay({\n    auth, mongoose, collection: '${lowerName}',\n  });\n  // ...then \`defineResource({ name: '${lowerName}', adapter, ... })\` reads\n  //    BA's collection through arc with full pagination/filters/permissions.\n\nAborting. Re-run with a different name if you need a separate domain model.\n`);
 		return;
 	}

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-CUTG2Cuo.mjs";
+import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-_--GyzcO.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.mjs

@@ -387,7 +387,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		const statusCode = reply.statusCode;
 		if (statusCode < 200 || statusCode >= 300) return payload;
 		const headersToCache = {};
-		const excludeHeaders = new Set([
+		const excludeHeaders = /* @__PURE__ */ new Set([
 			"content-length",
 			"transfer-encoding",
 			"connection",

package/dist/{index-CRKiiP5o.d.mts → index-CdFkIMEd.d.mts}

@@ -669,6 +669,11 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
 /**
  * Read-only: list + get authenticated, write operations denied.
  * Useful for computed/derived resources.
+ *
+ * Writes carry an explicit `denyAll` check — an omitted CRUD permission
+ * mounts the route with NO gate (public-by-omission), so leaving
+ * create/update/delete undefined here would expose unauthenticated writes.
+ * Hosts that disable write routes entirely (`disabledRoutes`) are unaffected.
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion

package/dist/{index-CP6A1Ffj.d.mts → index-DUa8WHz3.d.mts}

@@ -1,4 +1,4 @@
-import { C as RequestContext, Et as AggregationConfig, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, L as RequestWithExtras, T as CrudRouterOptions, V as ResourceDefinition, bt as IControllerResponse, ht as RouteSchemaOptions, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, st as ResourceConfig, xt as IRequestContext, yt as IController } from "./index-CUTG2Cuo.mjs";
+import { C as RequestContext, Et as AggregationConfig, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, L as RequestWithExtras, T as CrudRouterOptions, V as ResourceDefinition, bt as IControllerResponse, ht as RouteSchemaOptions, pt as RouteMcpConfig, q as CrudController, qt as AnyRecord, st as ResourceConfig, xt as IRequestContext, yt as IController } from "./index-_--GyzcO.mjs";
 import { i as RequestScope } from "./types-LNebCoJx.mjs";
 import { c as PermissionCheck } from "./fields-C7ahdGYf.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";

package/dist/{index-CUTG2Cuo.d.mts → index-_--GyzcO.d.mts}

@@ -2467,6 +2467,25 @@ interface RouteDefinition {
    * pipeline entirely.
    */
   readonly fieldWrite?: boolean;
+  /**
+   * Per-route rate limit. A custom route is its own Fastify route, so this
+   * overrides the resource-level `rateLimit` for THIS endpoint only:
+   *
+   *   - omitted                → inherit the resource-level limit (or app default)
+   *   - `false`                → disable rate limiting on this route
+   *   - `{ max, timeWindow }`  → apply this specific limit
+   *
+   * Requires `@fastify/rate-limit` registered (arc's factory wires it by
+   * default). Use for an expensive `/export` or an auth-sensitive `/reset`
+   * that needs a tighter cap than the resource's read-heavy CRUD, or `false`
+   * on an internal health/webhook route that must not be throttled.
+   *
+   * Note: this is per-route because each custom route is a distinct endpoint.
+   * `actions` share ONE `POST /:id/action` mount by design, so a per-ACTION
+   * limit can't be expressed here — throttle a specific action by promoting
+   * it to a dedicated `routes:` entry, or rely on the resource-level limit.
+   */
+  readonly rateLimit?: RateLimitConfig | false;
   /**
    * Fastify route schema. Each slot (`body`, `querystring`, `params`,
    * `headers`, `response[status]`) accepts a plain JSON Schema object
@@ -2504,7 +2523,15 @@ interface RouteDefinition {
  * ID, action-specific data, and the request.
  */
 type ActionHandlerFn = (id: string, data: Record<string, unknown>, req: RequestWithExtras) => Promise<unknown>;
-/** Full action configuration with handler, permissions, and schema. */
+/**
+ * Full action configuration with handler, permissions, and schema.
+ *
+ * Rate limiting is intentionally NOT per-action: every action shares one
+ * `POST /:id/action` (or `POST /action`) mount, so Fastify's per-route limit
+ * can't distinguish them. Actions inherit the resource-level `rateLimit`; to
+ * throttle a specific operation, promote it to a `routes:` entry (which
+ * supports `RouteDefinition.rateLimit`).
+ */
 interface ActionDefinition {
   readonly handler: ActionHandlerFn;
   /** Per-action permission (overrides resource-level `actionPermissions`) */

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { $t as UserOrganization, A as RequestIdOptions, An as ArcCreateResult, At as AggregationMaterializedResult, B as defineResource, C as RequestContext, Ct as AggMeasureInput, D as HealthCheck, Dt as AggregationDateRangeRequirement, E as GracefulShutdownOptions, Et as AggregationConfig, F as FastifyWithDecorators, Fn as BaseControllerOptions, Ht as AuthPluginOptions, In as ControllerConfigurableOptions, J as CrudRouteKey, Jt as ApiResponse, L as RequestWithExtras, Ln as ControllerConstructionOptions, Mn as ArcGetResult, Mt as AggregationsMap, N as FastifyRequestExtras, Nn as ArcListResult, O as HealthOptions, Ot as AggregationIndexHint, P as FastifyWithAuth, Pn as ArcUpdateResult, Q as MiddlewareConfig, Rn as ListResult, S as QueryParserInterface, St as RouteHandler, T as CrudRouterOptions, Tt as AggregationCacheConfig, V as ResourceDefinition, X as EventDefinition, Xt as JWTPayload, Y as CrudSchemas, Yt as ArcRequest, Z as FieldRule, _t as ControllerLike, a as InferAdapterDoc, an as SlugExt, bt as IControllerResponse, c as TypedController, cn as BulkMixin, d as PaginationResult, en as BaseController, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, ht as RouteSchemaOptions, i as ValidationResult, in as TreeMixin, it as RateLimitConfig, jn as ArcDeleteResult, jt as AggregationRateLimit, k as IntrospectionPluginOptions, kt as AggregationMaterializedContext, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, n as ConfigError, nn as SoftDeleteMixin, o as InferDocType, on as SlugMixin, p as RegistryEntry, q as CrudController, qt as AnyRecord, r as ValidateOptions, rn as TreeExt, rt as PresetResult, s as InferResourceDoc, sn as BulkExt, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteExt, tt as PresetFunction, u as TypedResourceConfig, w as ServiceContext, wt as AggMeasureShorthand, xt as IRequestContext, y as OwnershipCheck, yt as IController } from "./index-CUTG2Cuo.mjs";
+import { $t as UserOrganization, A as RequestIdOptions, An as ArcCreateResult, At as AggregationMaterializedResult, B as defineResource, C as RequestContext, Ct as AggMeasureInput, D as HealthCheck, Dt as AggregationDateRangeRequirement, E as GracefulShutdownOptions, Et as AggregationConfig, F as FastifyWithDecorators, Fn as BaseControllerOptions, Ht as AuthPluginOptions, In as ControllerConfigurableOptions, J as CrudRouteKey, Jt as ApiResponse, L as RequestWithExtras, Ln as ControllerConstructionOptions, Mn as ArcGetResult, Mt as AggregationsMap, N as FastifyRequestExtras, Nn as ArcListResult, O as HealthOptions, Ot as AggregationIndexHint, P as FastifyWithAuth, Pn as ArcUpdateResult, Q as MiddlewareConfig, Rn as ListResult, S as QueryParserInterface, St as RouteHandler, T as CrudRouterOptions, Tt as AggregationCacheConfig, V as ResourceDefinition, X as EventDefinition, Xt as JWTPayload, Y as CrudSchemas, Yt as ArcRequest, Z as FieldRule, _t as ControllerLike, a as InferAdapterDoc, an as SlugExt, bt as IControllerResponse, c as TypedController, cn as BulkMixin, d as PaginationResult, en as BaseController, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, ht as RouteSchemaOptions, i as ValidationResult, in as TreeMixin, it as RateLimitConfig, jn as ArcDeleteResult, jt as AggregationRateLimit, k as IntrospectionPluginOptions, kt as AggregationMaterializedContext, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, n as ConfigError, nn as SoftDeleteMixin, o as InferDocType, on as SlugMixin, p as RegistryEntry, q as CrudController, qt as AnyRecord, r as ValidateOptions, rn as TreeExt, rt as PresetResult, s as InferResourceDoc, sn as BulkExt, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteExt, tt as PresetFunction, u as TypedResourceConfig, w as ServiceContext, wt as AggMeasureShorthand, xt as IRequestContext, y as OwnershipCheck, yt as IController } from "./index-_--GyzcO.mjs";
 import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, t as FieldPermission, u as PermissionResult } from "./fields-C7ahdGYf.mjs";
-import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-CP6A1Ffj.mjs";
-import { A as requireRoles, C as allOf, E as denyAll, M as when, O as requireAuth, S as createOrgPermissions, T as anyOf, a as presets_d_exports, c as readOnly, d as requireOrgRole, f as requireScopeContext, i as ownerWithAdminBypass, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "./index-CRKiiP5o.mjs";
+import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-DUa8WHz3.mjs";
+import { A as requireRoles, C as allOf, E as denyAll, M as when, O as requireAuth, S as createOrgPermissions, T as anyOf, a as presets_d_exports, c as readOnly, d as requireOrgRole, f as requireScopeContext, i as ownerWithAdminBypass, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "./index-CdFkIMEd.mjs";
 import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-DOHkjQlD.mjs";
 
 //#region src/index.d.ts

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-gaEeMlz-.mjs";
+import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-DNre0wRg.mjs";
 import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-DkO8Nk6-.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-Dy6EQHjM.mjs";
-import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-Ba-6Sue6.mjs";
-import { C as requireAuth, D as when, F as applyFieldWritePermissions, I as fields, P as applyFieldReadPermissions, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "./permissions-BPB1xqGf.mjs";
-import { l as getControllerScope } from "./actionPermissions-D7NGwcAR.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-D-MHZ27_.mjs";
+import { C as requireAuth, D as when, F as applyFieldWritePermissions, I as fields, P as applyFieldReadPermissions, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "./permissions-CgbOLJZG.mjs";
+import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-CWhyGkiM.mjs";
+import { l as getControllerScope } from "./actionPermissions-C9RMiIpc.mjs";
 //#region src/index.ts
-const version = "2.19.0";
+const version = "2.20.0";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAction, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };