@classytic/arc 2.31.0 → 2.33.0

package/dist/{createApp-Df89BEni.mjs → createApp-CLGegqiG.mjs}

@@ -1,11 +1,13 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DNg-KNCk.mjs";
 import { arcLog, configureArcLogger, createPinoWriter } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE } from "./types-Cys0ko9Z.mjs";
-import { t as createTenantKeyGenerator } from "./rateLimitKey-Dn5JNmkj.mjs";
-import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-DjZYjM7H.mjs";
-import { t as parseJsonBody } from "./jsonBody-BYbLDi5D.mjs";
-import { r as wrapWithBoundary } from "./subscribe-helpers-C0Tb2aUp.mjs";
+import { n as PUBLIC_SCOPE } from "./types-CoqIRrkY.mjs";
+import { t as auditRuntimeCapabilities } from "./runtimeCapabilities-Dm88DaTW.mjs";
+import { t as createTenantKeyGenerator } from "./rateLimitKey-XngqVNEV.mjs";
+import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-CasG2A28.mjs";
+import { t as parseJsonBody } from "./jsonBody-CfGH-GxO.mjs";
+import { r as wrapWithBoundary } from "./subscribe-helpers-CLIOHsOK.mjs";
+import { isProductionEnv } from "@classytic/primitives/environment";
 import Fastify from "fastify";
 import qs from "qs";
 //#region src/factory/security/pluginLoader.ts
@@ -183,12 +185,15 @@ async function resolveContribution(contribution, fastify) {
 * them. The original error is preserved via `{ cause }`.
 */
 async function resolveModuleArm(module, arm, contribution, fastify) {
+	let resolved;
 	try {
-		return await resolveContribution(contribution, fastify);
+		resolved = await resolveContribution(contribution, fastify);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		throw new Error(`[arc] module "${module.name}" ${arm} factory threw: ${msg}`, { cause: err });
 	}
+	if (!Array.isArray(resolved)) throw new TypeError(`[arc] module "${module.name}" ${arm} factory must return an array — received ${resolved === null ? "null" : typeof resolved}.`);
+	return resolved;
 }
 //#endregion
 //#region src/factory/module/contributions.ts
@@ -227,11 +232,12 @@ async function collectModuleWorkflows(fastify, modules) {
 * modules. The caller passes the returned definitions to the canonical
 * schedules plugin; factories must therefore be resolved only once.
 */
-async function collectModuleScheduledJobs(fastify, modules) {
+async function collectModuleScheduledJobs(fastify, modules, countsByModule) {
 	const owner = /* @__PURE__ */ new Map();
 	const out = [];
 	for (const m of modules) {
 		const jobs = await resolveModuleArm(m, "scheduledJobs", m.scheduledJobs, fastify);
+		countsByModule?.set(m.name, jobs.length);
 		for (const job of jobs) {
 			const prior = owner.get(job.name);
 			if (prior !== void 0) throw new Error(`[arc] duplicate scheduled-job name "${job.name}" — declared by module "${prior}" and module "${m.name}". Scheduled-job names must be unique across the module graph.`);
@@ -242,6 +248,69 @@ async function collectModuleScheduledJobs(fastify, modules) {
 	return out;
 }
 //#endregion
+//#region src/factory/module/descriptor.ts
+/**
+* Build a descriptor. Called by `registerResources` once per module, after
+* resources are resolved and `owns` is effective.
+*
+* Frozen at every level: a descriptor is a snapshot of a completed decision,
+* and a consumer mutating it would silently disagree with the running app.
+*/
+function describeResolvedModule(input) {
+	return Object.freeze({
+		name: input.name,
+		dependsOn: Object.freeze([...input.dependsOn ?? []]),
+		resources: Object.freeze(input.resources.map((r) => Object.freeze({
+			...r.name !== void 0 ? { name: r.name } : {},
+			...r.prefix !== void 0 ? { prefix: r.prefix } : {},
+			skipGlobalPrefix: r.skipGlobalPrefix === true
+		}))),
+		owns: Object.freeze([...input.owns]),
+		lifecycle: Object.freeze({ ...input.lifecycle })
+	});
+}
+//#endregion
+//#region src/factory/module/disposers.ts
+function createDisposerRegistry(fastify) {
+	const stacks = /* @__PURE__ */ new Map();
+	const drained = /* @__PURE__ */ new Set();
+	const contexts = /* @__PURE__ */ new Map();
+	return {
+		contextFor(moduleName) {
+			const existing = contexts.get(moduleName);
+			if (existing) return existing;
+			const ctx = { defer(disposer) {
+				if (typeof disposer !== "function") throw new TypeError(`[arc] module "${moduleName}" called defer() with a ${typeof disposer} — expected a function.`);
+				if (drained.has(moduleName)) {
+					(async () => {
+						try {
+							await disposer();
+						} catch (err) {
+							fastify.log?.error({
+								err,
+								module: moduleName
+							}, `[arc] module "${moduleName}" deferred a disposer after teardown had already run; it was invoked immediately and threw.`);
+						}
+					})();
+					return;
+				}
+				const stack = stacks.get(moduleName);
+				if (stack) stack.push(disposer);
+				else stacks.set(moduleName, [disposer]);
+			} };
+			contexts.set(moduleName, ctx);
+			return ctx;
+		},
+		take(moduleName) {
+			drained.add(moduleName);
+			const stack = stacks.get(moduleName);
+			if (!stack?.length) return [];
+			stacks.delete(moduleName);
+			return stack.reverse();
+		}
+	};
+}
+//#endregion
 //#region src/factory/module/lifecycle.ts
 /**
 * Subscribe every module's `eventHandlers` in dependency order (pass the
@@ -253,12 +322,13 @@ async function collectModuleScheduledJobs(fastify, modules) {
 * Resolves factory contributions (after bootstraps) so a handler can close over
 * booted engines rather than a global getter.
 */
-async function subscribeModuleEventHandlers(fastify, modules) {
+async function subscribeModuleEventHandlers(fastify, modules, countsByModule) {
 	const unsubscribes = [];
 	const owner = /* @__PURE__ */ new Map();
 	try {
 		for (const m of modules) {
 			const handlers = await resolveModuleArm(m, "eventHandlers", m.eventHandlers, fastify);
+			countsByModule?.set(m.name, handlers.length);
 			if (handlers.length === 0) continue;
 			const bus = fastify.events;
 			if (!bus) throw new Error(`[arc] module "${m.name}" declares eventHandlers but the event subsystem is unavailable (fastify.events). Enable arcPlugins.events.`);
@@ -460,7 +530,7 @@ function getModuleState(fastify, name) {
 }
 //#endregion
 //#region src/factory/module/teardown.ts
-function createModuleTeardown(fastify, modules) {
+function createModuleTeardown(fastify, modules, disposers) {
 	const initializedNames = /* @__PURE__ */ new Set();
 	const consumed = /* @__PURE__ */ new Set();
 	async function closeInitialized() {
@@ -469,18 +539,30 @@ function createModuleTeardown(fastify, modules) {
 			const m = modules[index];
 			if (!m || !initializedNames.has(m.name) || consumed.has(m.name)) continue;
 			consumed.add(m.name);
-			if (!m.onClose) {
+			const stack = disposers?.take(m.name) ?? [];
+			if (!m.onClose && stack.length === 0) {
 				setModuleState(fastify, m.name, "closed");
 				continue;
 			}
 			setModuleState(fastify, m.name, "closing");
-			try {
+			let teardownFailed = false;
+			if (m.onClose) try {
 				await m.onClose(fastify);
-				setModuleState(fastify, m.name, "closed");
 			} catch (err) {
-				setModuleState(fastify, m.name, "failed");
+				teardownFailed = true;
 				errors.push(new Error(`[arc] module "${m.name}" onClose() threw during teardown: ${err instanceof Error ? err.message : String(err)}`, { cause: err }));
 			}
+			for (let d = 0; d < stack.length; d++) {
+				const dispose = stack[d];
+				if (!dispose) continue;
+				try {
+					await dispose();
+				} catch (err) {
+					teardownFailed = true;
+					errors.push(new Error(`[arc] module "${m.name}" deferred disposer #${stack.length - d} threw during teardown: ${err instanceof Error ? err.message : String(err)}`, { cause: err }));
+				}
+			}
+			setModuleState(fastify, m.name, teardownFailed ? "failed" : "closed");
 		}
 		return errors;
 	}
@@ -554,8 +636,8 @@ const productionPreset = {
 		exposeStatusRoute: true,
 		maxEventLoopDelay: 3e3,
 		maxEventLoopUtilization: .98,
-		maxHeapUsedBytes: 1024 * 1024 * 1024,
-		maxRssBytes: 1024 * 1024 * 1024
+		maxHeapUsedBytes: 1073741824,
+		maxRssBytes: 1073741824
 	}
 };
 /**
@@ -625,7 +707,7 @@ const testingPreset = {
 	arcPlugins: { gracefulShutdown: false },
 	sensible: true,
 	multipart: { limits: {
-		fileSize: 1024 * 1024,
+		fileSize: 1048576,
 		files: 5
 	} }
 };
@@ -719,9 +801,20 @@ 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-CkffEihm.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-Dar8qRaj.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
+			/**
+			* An EXPLICIT `runtime: 'memory'` is the host's single-instance
+			* declaration (its JSDoc says exactly that), so it flows down as the
+			* event plugin's `singleProcess` flag — one topology axis, declared
+			* once, no second knob to keep in sync. The comparison is against the
+			* literal, not the resolved default: `runtime` UNSET also means memory
+			* stores, but an unstated topology must keep the forgotten-default
+			* warn. `eventOpts` spreads after, so a direct
+			* `arcPlugins.events.singleProcess` still wins either way.
+			*/
+			...config.runtime === "memory" ? { singleProcess: true } : {},
 			...eventOpts,
 			transport: config.stores?.events
 		});
@@ -767,43 +860,47 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 		trackPlugin("arc-graceful-shutdown");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-BFHA6Scf.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-BcGmvnHh.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-BZr8v46E.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-DhsZ0ZIc.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = config.stores?.queryCache ?? new (await (import("./memory-DR6wpa9F.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-qYSB7rMQ.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
 		});
 		trackPlugin("arc-query-cache", opts);
 	}
-	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-CUTo9y0X.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?.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-Cf0jUHsh.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?.realtime) if (config.arcPlugins?.events === false) fastify.log.warn("Realtime plugin requires events plugin (arcPlugins.events). Realtime disabled.");
-	else {
-		const { default: realtimePlugin } = await import("./realtime-C5NoxWFY.mjs").then((n) => n.r);
-		const opts = config.arcPlugins.realtime === true ? {} : config.arcPlugins.realtime;
-		await fastify.register(realtimePlugin, opts);
-		trackPlugin("arc-realtime", opts);
+	if (config.arcPlugins?.realtime) {
+		if (config.arcPlugins?.events === false) fastify.log.warn("Realtime plugin requires events plugin (arcPlugins.events). Realtime disabled.");
+		else {
+			const { default: realtimePlugin } = await import("./realtime-CTkv3O59.mjs").then((n) => n.r);
+			const opts = config.arcPlugins.realtime === true ? {} : config.arcPlugins.realtime;
+			await fastify.register(realtimePlugin, opts);
+			trackPlugin("arc-realtime", opts);
+		}
 	}
 	if (config.arcPlugins?.metrics) {
-		const { default: metricsPlugin } = await import("./metrics-CUdw_wLB.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-D7uchLjN.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-CHDTor3P.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-rZbyLVD-.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -811,6 +908,12 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 //#endregion
 //#region src/factory/registerAuth.ts
 /**
+* Authentication registration for createApp.
+*
+* Extracted from createApp step 9: scope decoration, auth strategy,
+* elevation plugin, and error handler.
+*/
+/**
 * Decorate request.scope with PUBLIC_SCOPE default.
 * Every request starts as public; auth hooks upgrade it.
 */
@@ -849,10 +952,12 @@ async function registerAuth(fastify, config, trackPlugin) {
 			fastify.decorate("authenticate", async (request, reply) => {
 				await authenticate(request, reply);
 			});
-			if (!fastify.hasDecorator("optionalAuthenticate")) if (optionalAuthenticate) fastify.decorate("optionalAuthenticate", async (request, reply) => {
-				await optionalAuthenticate(request, reply);
-			});
-			else fastify.decorate("optionalAuthenticate", createOptionalAuthenticate(authenticate));
+			if (!fastify.hasDecorator("optionalAuthenticate")) {
+				if (optionalAuthenticate) fastify.decorate("optionalAuthenticate", async (request, reply) => {
+					await optionalAuthenticate(request, reply);
+				});
+				else fastify.decorate("optionalAuthenticate", createOptionalAuthenticate(authenticate));
+			}
 			trackPlugin("auth-authenticator");
 			fastify.log.debug("Custom authenticator enabled");
 			break;
@@ -872,7 +977,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-D2l1mh4g.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-B0tlY8y1.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -887,8 +992,51 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-C5NeD6bT.mjs").then((n) => n.r);
-	let errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
+	const { errorHandlerPlugin } = await import("./errorHandler-C7xBqHsI.mjs").then((n) => n.r);
+	/**
+	* DISCLOSURE DEFAULTS MERGE — they used to be REPLACED, and that was two bugs.
+	*
+	* This was a ternary: an object from the host was used verbatim, otherwise
+	* `{ includeStack: config.preset !== "production" }`. Both branches leaked.
+	*
+	*   1. A host that passed ANY key — even just `errorMappers` — lost the preset-derived
+	*      `includeStack` and fell through to `errorHandlerPlugin`'s own default, which is
+	*      `!(process.env.NODE_ENV === "production")`. That comparison knows only the long
+	*      spelling, so under `NODE_ENV=prod` it yields `true` and stack traces ship to clients in
+	*      production. Nobody writing `errorHandler: { errorMappers: [...] }` could reasonably
+	*      expect it to change stack-trace exposure.
+	*   2. The derived branch never set `exposeInternalMessages` AT ALL, so that switch fell
+	*      through to the same raw read for EVERY arc app however it was configured. A truthy value
+	*      is what skips `wire.message = "Internal Server Error"` for a 500, putting the raw thrown
+	*      message — driver text, query fragments — on the wire.
+	*
+	* `preset` is the right source: it is the deployment's EXPLICIT declaration, and a specific
+	* setting must never be overridden by an ambient default. Host keys still win over `derived`,
+	* so an operator can widen deliberately; what they can no longer do is widen by accident.
+	*
+	*   3. And `preset` is OPTIONAL, so its ABSENCE must not read as "not production" either.
+	*      `config.preset !== "production"` is true for an unset preset, and plenty of hosts set
+	*      only `NODE_ENV` — which turns "the operator said nothing" into "the operator said
+	*      development", the widest possible reading of silence, on the two switches where being
+	*      wrong ships stack traces and raw driver text.
+	*
+	* So: an explicit `preset` wins; its absence falls back to the ENVIRONMENT rather than to a
+	* guess; and that fallback goes through `isProductionEnv` from the shared classifier, never a raw
+	* `process.env.NODE_ENV === "production"`. The raw form recognises only the long spelling, so a
+	* preset-less host on `NODE_ENV=prod` read as non-production and re-opened both switches — the
+	* same defect class this fallback exists to close, one layer in. Verified against a real 500 in
+	* every state, including a Mongo connection string reaching the response body before the fix
+	* (`tests/factory/error-disclosure-defaults.test.ts`).
+	*/
+	const productionEnv = config.preset !== void 0 ? config.preset === "production" : isProductionEnv(process.env.NODE_ENV);
+	const derived = {
+		includeStack: !productionEnv,
+		exposeInternalMessages: !productionEnv
+	};
+	let errorOpts = typeof config.errorHandler === "object" ? {
+		...derived,
+		...config.errorHandler
+	} : derived;
 	if (moduleErrorMappers && moduleErrorMappers.length > 0) errorOpts = {
 		...errorOpts,
 		errorMappers: [...errorOpts.errorMappers ?? [], ...moduleErrorMappers]
@@ -997,7 +1145,8 @@ async function registerResources(fastify, config, preResolvedModules) {
 	}
 	const modules = preResolvedModules ?? orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
 	initModuleStates(fastify, modules.map((m) => m.name));
-	const teardown = createModuleTeardown(fastify, modules);
+	const disposers = createDisposerRegistry(fastify);
+	const teardown = createModuleTeardown(fastify, modules, disposers);
 	let eventUnsubscribes = [];
 	try {
 		if (config.plugins) {
@@ -1008,7 +1157,11 @@ async function registerResources(fastify, config, preResolvedModules) {
 			if (!m.plugins) continue;
 			teardown.markInitialized(m);
 			try {
-				await m.plugins(fastify);
+				const returned = await m.plugins(fastify, disposers.contextFor(m.name));
+				if (typeof returned === "function") {
+					assertNotAReturnedPlugin(returned, m.name, fastify);
+					disposers.contextFor(m.name).defer(returned);
+				}
 			} catch (err) {
 				setModuleState(fastify, m.name, "failed");
 				const msg = err instanceof Error ? err.message : String(err);
@@ -1025,7 +1178,7 @@ async function registerResources(fastify, config, preResolvedModules) {
 			teardown.markInitialized(m);
 			setModuleState(fastify, m.name, "bootstrapping");
 			try {
-				exported = await m.bootstrap(fastify);
+				exported = await m.bootstrap(fastify, disposers.contextFor(m.name));
 			} catch (err) {
 				setModuleState(fastify, m.name, "failed");
 				const msg = err instanceof Error ? err.message : String(err);
@@ -1048,6 +1201,7 @@ async function registerResources(fastify, config, preResolvedModules) {
 		if (isResourcesFactory(config.resources)) {
 			try {
 				resolvedResources = await config.resources(fastify);
+				if (!Array.isArray(resolvedResources)) throw new TypeError(`resources factory must return an array — received ${resolvedResources === null ? "null" : typeof resolvedResources}`);
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				fastify.log.error(`Resources factory threw during boot: ${msg}`);
@@ -1062,7 +1216,7 @@ async function registerResources(fastify, config, preResolvedModules) {
 		let discoveryPath;
 		let discoveryYieldedZero = false;
 		if (resolvedResources === void 0 && config.resourceDir) {
-			const { loadResources } = await import("./loadResources-yawi9tAE.mjs").then((n) => n.n);
+			const { loadResources } = await import("./loadResources-Bj-aSsXi.mjs").then((n) => n.n);
 			const { resolve, dirname } = await import("node:path");
 			const { fileURLToPath } = await import("node:url");
 			const rawDir = config.resourceDir;
@@ -1077,6 +1231,7 @@ async function registerResources(fastify, config, preResolvedModules) {
 			resolvedResources = discovered;
 		}
 		const moduleResourceNames = /* @__PURE__ */ new Map();
+		const perModuleResources = /* @__PURE__ */ new Map();
 		const moduleResources = [];
 		for (const m of modules) {
 			if (!m.resources) continue;
@@ -1087,24 +1242,37 @@ async function registerResources(fastify, config, preResolvedModules) {
 				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 (!Array.isArray(rs)) throw new TypeError(`[arc] module "${m.name}" resources factory must return an array — received ${rs === null ? "null" : typeof rs}.`);
 			const names = /* @__PURE__ */ new Set();
-			for (const r of rs) if (r.name != null) names.add(r.name);
+			for (const r of rs) {
+				if (r.name == null) continue;
+				if (names.has(r.name)) throw new Error(`[arc] module "${m.name}" provides two resources named "${r.name}". Resource names must be unique within a module — arc registers one route group per name, so the second would be dropped.`);
+				names.add(r.name);
+			}
 			moduleResourceNames.set(m.name, names);
+			perModuleResources.set(m.name, rs);
 			moduleResources.push(...rs);
 		}
+		const effectiveOwns = /* @__PURE__ */ new Map();
 		for (const m of modules) {
-			if (!m.owns?.length) continue;
 			const supplied = moduleResourceNames.get(m.name);
+			if (m.owns === "provided") {
+				if (!supplied?.size) throw new Error(`[arc] module "${m.name}" declares \`owns: "provided"\` but supplies no named resources. Either give it resources to own, or drop the \`owns\` entry — an empty claim is almost always a resources factory that returned early.`);
+				effectiveOwns.set(m.name, [...supplied]);
+				continue;
+			}
+			if (!m.owns?.length) continue;
 			const missing = m.owns.filter((name) => !supplied?.has(name));
 			if (missing.length > 0) {
 				const provided = supplied?.size ? [...supplied].join(", ") : "(none)";
-				throw new Error(`[arc] module "${m.name}" declares owns: [${missing.map((n) => `"${n}"`).join(", ")}] but its own \`resources\` do not supply ${missing.length === 1 ? "that name" : "those names"}. \`owns\` DROPS the app-level resource of that name, so an unmet claim removes the route entirely and nothing serves it. Provide it in this module's \`resources\`, or drop the \`owns\` entry.
+				throw new Error(`[arc] module "${m.name}" declares owns: [${missing.map((n) => `"${n}"`).join(", ")}] but its own \`resources\` do not supply ${missing.length === 1 ? "that name" : "those names"}. \`owns\` DROPS the app-level resource of that name, so an unmet claim removes the route entirely and nothing serves it. Provide it in this module's \`resources\`, drop the \`owns\` entry, or use \`owns: "provided"\` to derive it.
 Resources supplied by "${m.name}": ${provided}.`);
 			}
+			effectiveOwns.set(m.name, m.owns);
 		}
 		if (modules.length && resolvedResources && resolvedResources.length > 0) {
 			const owned = /* @__PURE__ */ new Set();
-			for (const m of modules) for (const name of m.owns ?? []) owned.add(name);
+			for (const m of modules) for (const name of effectiveOwns.get(m.name) ?? []) owned.add(name);
 			if (owned.size > 0) {
 				const before = resolvedResources.length;
 				resolvedResources = resolvedResources.filter((r) => !(r.name != null && owned.has(r.name)));
@@ -1128,10 +1296,12 @@ Resources supplied by "${m.name}": ${provided}.`);
 			for (const resource of resolvedResources) if (resource.skipGlobalPrefix) root.push(resource);
 			else prefixed.push(resource);
 			for (const resource of root) await registerOne(fastify, resource, config.mountRoutes);
-			if (prefixed.length) if (config.resourcePrefix) await fastify.register(async (scoped) => {
-				for (const resource of prefixed) await registerOne(scoped, resource, config.mountRoutes);
-			}, { prefix: config.resourcePrefix });
-			else for (const resource of prefixed) await registerOne(fastify, resource, config.mountRoutes);
+			if (prefixed.length) {
+				if (config.resourcePrefix) await fastify.register(async (scoped) => {
+					for (const resource of prefixed) await registerOne(scoped, resource, config.mountRoutes);
+				}, { prefix: config.resourcePrefix });
+				else for (const resource of prefixed) await registerOne(fastify, resource, config.mountRoutes);
+			}
 			const names = resolvedResources.map((r) => r.name ?? "?").join(", ");
 			const prefix = config.resourcePrefix ? ` (prefix: ${config.resourcePrefix})` : "";
 			fastify.log.info(`${resolvedResources.length} resource(s) registered${prefix}: ${names}`);
@@ -1144,19 +1314,35 @@ Resources supplied by "${m.name}": ${provided}.`);
 		for (const m of modules) {
 			if (!m.afterResources) continue;
 			try {
-				await m.afterResources(fastify);
+				const returned = await m.afterResources(fastify, disposers.contextFor(m.name));
+				if (typeof returned === "function") disposers.contextFor(m.name).defer(returned);
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				throw new Error(`[arc] module "${m.name}" afterResources() threw: ${msg}`, { cause: err });
 			}
 		}
-		const scheduledJobs = await collectModuleScheduledJobs(fastify, modules);
+		const scheduleCounts = /* @__PURE__ */ new Map();
+		const collectedJobs = await collectModuleScheduledJobs(fastify, modules, scheduleCounts);
+		/**
+		* ROLE gate (CreateAppOptions.role). Arms a role does not run are SKIPPED
+		* and logged by name, never fatal: a module legitimately declares arms
+		* that a different deployment of the same codebase executes. 'relay' runs
+		* only kind:'relay' arms (the outbox relays); 'api'/'worker' run none;
+		* 'scheduler'/'all' run everything.
+		*/
+		const role = config.role ?? "all";
+		const scheduledJobs = role === "scheduler" || role === "all" ? collectedJobs : role === "relay" ? collectedJobs.filter((j) => j.kind === "relay") : [];
+		const skipped = collectedJobs.filter((j) => !scheduledJobs.includes(j));
+		if (skipped.length > 0) fastify.log.info({
+			role,
+			skipped: skipped.map((j) => j.name)
+		}, `[arc] role '${role}': ${skipped.length} schedule arm(s) not mounted here — a deployment with the owning role runs them`);
 		if (scheduledJobs.length > 0) {
 			if (config.arcPlugins?.schedules === false) throw new Error("[arc] modules declare scheduledJobs but arcPlugins.schedules is false. Enable the scheduler or remove the declarations.");
 			if (fastify.hasDecorator("getScheduleStats")) throw new Error("[arc] modules declare scheduledJobs but schedulesPlugin was already registered manually. Configure their runner through arcPlugins.schedules so Arc can compose one schedule table.");
 			const frozenJobs = Object.freeze(scheduledJobs.map((job) => Object.freeze({ ...job })));
 			const scheduleOptions = typeof config.arcPlugins?.schedules === "object" ? config.arcPlugins.schedules : {};
-			const { default: schedulesPlugin } = await import("./schedules-DdtlICTf.mjs").then((n) => n.r);
+			const { default: schedulesPlugin } = await import("./schedules-CAcZgia0.mjs").then((n) => n.r);
 			await fastify.register(schedulesPlugin, {
 				...scheduleOptions,
 				schedules: frozenJobs
@@ -1170,7 +1356,21 @@ Resources supplied by "${m.name}": ${provided}.`);
 				});
 			}
 		}
-		eventUnsubscribes = await subscribeModuleEventHandlers(fastify, modules);
+		const subscriptionCounts = /* @__PURE__ */ new Map();
+		eventUnsubscribes = await subscribeModuleEventHandlers(fastify, modules, subscriptionCounts);
+		if (fastify.arc) fastify.arc.moduleDescriptors = Object.freeze(modules.map((m) => describeResolvedModule({
+			name: m.name,
+			dependsOn: m.dependsOn,
+			resources: perModuleResources.get(m.name) ?? [],
+			owns: effectiveOwns.get(m.name) ?? [],
+			lifecycle: {
+				hasClose: typeof m.onClose === "function",
+				subscriptions: subscriptionCounts.get(m.name) ?? 0,
+				scheduledJobs: scheduleCounts.get(m.name) ?? 0,
+				healthChecks: m.healthChecks?.length ?? 0,
+				exports: typeof m.bootstrap === "function"
+			}
+		})));
 		if (config.afterResources) {
 			await config.afterResources(fastify);
 			fastify.log.debug("afterResources hook executed");
@@ -1198,6 +1398,22 @@ Resources supplied by "${m.name}": ${provided}.`);
 		if (closeErrors.length > 0) throw closeErrors[0];
 	});
 }
+/**
+* `plugins()` is CALLED by arc, never handed to `fastify.register()` — so a
+* module author who returns a Fastify plugin expecting arc to register it
+* gets silence: nothing is registered, and the "disposer" shorthand then
+* invokes their plugin at shutdown with no arguments.
+*
+* The `fastify-plugin` case is unambiguous (its marker symbols are only ever
+* set by `fp()`), so it throws. A bare `(fastify, opts)` function is a strong
+* but not certain signal — arc's disposer contract calls it with ZERO
+* arguments, so a 2-parameter disposer is meaningless either way — and warns.
+*/
+function assertNotAReturnedPlugin(returned, moduleName, fastify) {
+	const fn = returned;
+	if (fn[Symbol.for("skip-override")] !== void 0 || fn[Symbol.for("plugin-meta")] !== void 0 || fn[Symbol.for("fastify.display-name")] !== void 0) throw new Error(`[arc] module "${moduleName}" returned a fastify-plugin from plugins(). That slot is a SETUP function arc calls directly — it is never passed to fastify.register(), so the returned value is read as a disposer and your plugin would be invoked at shutdown instead of registered at boot. Register it yourself: \`plugins: async (fastify) => { await fastify.register(myPlugin) }\`.`);
+	if (returned.length >= 2) fastify.log?.warn?.(`[arc] module "${moduleName}" returned a ${returned.length}-argument function from plugins(). Arc calls disposers with NO arguments, so this looks like a Fastify plugin that was meant to be registered (\`await fastify.register(fn)\`) rather than a teardown callback. If it really is a disposer, declare it with no parameters.`);
+}
 //#endregion
 //#region src/factory/security/cors.ts
 /**
@@ -1399,7 +1615,7 @@ async function registerUtilityPlugins(fastify, config) {
 				throwFileSizeLimit: true,
 				...hostMultipart,
 				limits: {
-					fileSize: 10 * 1024 * 1024,
+					fileSize: 10485760,
 					files: 10,
 					fields: 100,
 					parts: 120,
@@ -1589,6 +1805,14 @@ Missing:\n${lines}\n\nFix: pass durable adapters under \`stores\`, or use runtim
 * instance is closed before the error propagates — see the wrapper below.
 */
 async function createApp(options) {
+	/**
+	* ROLE contradiction check — before anything constructs. A relay/scheduler
+	* process declaring HTTP resources is a wiring error, not a preference:
+	* those roles exist to NOT serve traffic, and mounting routes anyway would
+	* hide the misdeployment behind a working endpoint.
+	*/
+	const declaredRole = options.role ?? "all";
+	if ((declaredRole === "relay" || declaredRole === "scheduler") && (options.resources !== void 0 || options.resourceDir !== void 0)) throw new Error(`createApp: role '${declaredRole}' declares HTTP resources — a ${declaredRole} process must not serve routes. Remove \`resources\`/\`resourceDir\`, or change the role.`);
 	let partial;
 	try {
 		return await buildApp(options, (instance) => {
@@ -1683,7 +1907,7 @@ async function buildApp(options, onInstance) {
 	await registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers);
 	await registerResources(fastify, config, resolvedModules);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-DIiZKGUt.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-BSBVCwL3.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
 	if (config.serializeBigInt) {
@@ -1700,6 +1924,7 @@ async function buildApp(options, onInstance) {
 		});
 	}
 	const authMode = config.auth === false ? "none" : config.auth ? config.auth.type : "none";
+	auditRuntimeCapabilities(fastify, config.runtime ?? "memory");
 	fastify.log.info({
 		preset: config.preset ?? "custom",
 		runtime: config.runtime ?? "memory",
@@ -1734,4 +1959,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { resolveContribution as _, edgePreset as a, testingPreset as c, hasModule as d, orderModules as f, collectModuleWorkflows as g, collectModuleScheduledJobs as h, developmentPreset as i, workerPreset as l, collectModuleHealthChecks as m, createApp as n, getPreset as o, subscribeModuleEventHandlers as p, createApp_exports as r, productionPreset as s, ArcFactory as t, getModuleState as u, resolveModule as v };
+export { collectModuleScheduledJobs as _, developmentPreset as a, resolveModule as b, productionPreset as c, getModuleState as d, hasModule as f, collectModuleHealthChecks as g, describeResolvedModule as h, createApp_exports as i, testingPreset as l, subscribeModuleEventHandlers as m, DEFAULT_LOGGER_REDACT_PATHS as n, edgePreset as o, orderModules as p, createApp as r, getPreset as s, ArcFactory as t, workerPreset as u, collectModuleWorkflows as v, resolveContribution as y };

package/dist/{defineAggregation-DbPPS8RI.mjs → defineAggregation-Nv-DwfOf.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/core/aggregation/defineAggregation.ts
 /**
 * Declare a single resource aggregation. Exported configs flow into