@classytic/arc 2.30.0 → 2.31.0

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

@@ -1,12 +1,158 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
 import { arcLog, configureArcLogger, createPinoWriter } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE } from "./types-CSyCxl2V.mjs";
-import { t as createTenantKeyGenerator } from "./rateLimitKey-BoWRH3e7.mjs";
-import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-CB_m4S32.mjs";
-import { t as parseJsonBody } from "./jsonBody-BlzAoGCe.mjs";
-import { r as wrapWithBoundary } from "./subscribe-helpers-DfzsivM6.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 Fastify from "fastify";
 import qs from "qs";
+//#region src/factory/security/pluginLoader.ts
+const PLUGIN_REGISTRY = {
+	cors: {
+		package: "@fastify/cors",
+		loader: () => import("@fastify/cors").then((m) => m.default)
+	},
+	helmet: {
+		package: "@fastify/helmet",
+		loader: () => import("@fastify/helmet").then((m) => m.default)
+	},
+	rateLimit: {
+		package: "@fastify/rate-limit",
+		loader: () => import("@fastify/rate-limit").then((m) => m.default)
+	},
+	underPressure: {
+		package: "@fastify/under-pressure",
+		loader: () => import("@fastify/under-pressure").then((m) => m.default)
+	},
+	sensible: {
+		package: "@fastify/sensible",
+		loader: () => import("@fastify/sensible").then((m) => m.default)
+	},
+	multipart: {
+		package: "@fastify/multipart",
+		loader: () => import("@fastify/multipart").then((m) => m.default),
+		optional: true
+	},
+	rawBody: {
+		package: "fastify-raw-body",
+		loader: () => import("fastify-raw-body").then((m) => m.default),
+		optional: true
+	},
+	static: {
+		package: "@fastify/static",
+		loader: () => import("@fastify/static").then((m) => m.default),
+		optional: true
+	}
+};
+async function loadPlugin(name, logger) {
+	const entry = PLUGIN_REGISTRY[name];
+	if (!entry) throw new Error(`Unknown plugin: ${name}`);
+	try {
+		return await entry.loader();
+	} catch (error) {
+		const err = error;
+		const isModuleNotFound = err.message.includes("Cannot find module") || err.message.includes("Cannot find package") || err.message.includes("MODULE_NOT_FOUND") || err.message.includes("Could not resolve");
+		if (isModuleNotFound && entry.optional) {
+			logger?.warn(`Optional plugin '${name}' skipped (${entry.package} not installed)`);
+			return null;
+		}
+		if (isModuleNotFound) throw new Error(`Plugin '${name}' requires package '${entry.package}' which is not installed.\nInstall it with: npm install ${entry.package}\nOr disable this plugin by setting ${name}: false in createApp options.`);
+		throw new Error(`Failed to load plugin '${name}': ${err.message}`);
+	}
+}
+//#endregion
+//#region src/factory/assets.ts
+/**
+* Cache-Control per preset.
+*
+* - `immutable` — content-addressed output ONLY (a hashed filename that changes
+*   when the bytes change). One year + `immutable` so a revalidation is never
+*   even attempted.
+* - `revalidate` — the default. The client may cache but MUST check freshness;
+*   `@fastify/static`'s `ETag`/`Last-Modified` then makes the common case a 304
+*   with no body, which is nearly as cheap as a cache hit and always correct.
+* - `none` — never store. For a path that is authorization-dependent, where a
+*   shared cache holding the bytes would leak them to the next caller.
+*/
+const CACHE_CONTROL = {
+	immutable: "public, max-age=31536000, immutable",
+	revalidate: "public, max-age=0, must-revalidate",
+	none: "no-store"
+};
+/**
+* Resolve one asset root's declaration into the header policy arc applies per
+* file. Pure — no Fastify, no filesystem — so the policy is unit-testable
+* without booting an app.
+*/
+function resolveAssetPolicy(root) {
+	const cache = root.cache ?? "revalidate";
+	const crossOrigin = root.crossOrigin ?? "same-site";
+	const disposition = root.disposition ?? "attachment";
+	return {
+		cacheControl: CACHE_CONTROL[cache],
+		crossOriginResourcePolicy: crossOrigin,
+		disposition,
+		varyOrigin: crossOrigin !== "same-origin"
+	};
+}
+/** Quote a filename for `Content-Disposition` per RFC 6266 / RFC 5987. */
+function contentDisposition(type, filePath) {
+	const name = filePath.split(/[\\/]/).pop() ?? "download";
+	return `${type}; filename="${name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "\\$&")}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+/**
+* Register every declared asset root.
+*
+* Each root becomes its OWN `@fastify/static` registration. That is deliberate:
+* `@fastify/static` scopes `prefix`, `root`, and the send options per
+* registration, so two roots with different cache or cross-origin policy stay
+* genuinely independent instead of sharing one mutable options bag.
+*
+* Registered AFTER the security plugins so the per-prefix CORP override lands on
+* top of helmet's app-wide default — helmet sets its headers in an `onRequest`
+* hook, while `setHeaders` runs at send time, so the asset policy wins.
+*/
+async function registerAssetRoots(fastify, roots) {
+	if (roots.length === 0) return;
+	const staticPlugin = await loadPlugin("static", fastify.log);
+	if (!staticPlugin) throw new Error("[arc] `assets` was configured but '@fastify/static' is not installed. Install it with: npm install @fastify/static — arc delegates ranges, ETags, immutable caching and pre-compressed variants to it rather than reimplementing them.");
+	const seen = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		const prior = seen.get(root.prefix);
+		if (prior !== void 0) throw new Error(`[arc] duplicate asset prefix "${root.prefix}" — declared for roots "${prior}" and "${root.root}". Asset prefixes must be unique; nest them (e.g. "/files/public" and "/files/private") instead of sharing one.`);
+		seen.set(root.prefix, String(root.root));
+	}
+	for (const root of roots) {
+		const policy = resolveAssetPolicy(root);
+		await fastify.register(staticPlugin, {
+			root: root.root,
+			prefix: root.prefix,
+			decorateReply: root.decorateReply ?? false,
+			list: false,
+			index: root.index ?? false,
+			dotfiles: "deny",
+			serveDotFiles: false,
+			cacheControl: false,
+			etag: root.etag ?? true,
+			lastModified: root.lastModified ?? true,
+			acceptRanges: root.acceptRanges ?? true,
+			...root.preCompressed !== void 0 ? { preCompressed: root.preCompressed } : {},
+			...root.allowedPath ? { allowedPath: root.allowedPath } : {},
+			setHeaders: (reply, filePath) => {
+				reply.header("Cache-Control", policy.cacheControl);
+				reply.header("Cross-Origin-Resource-Policy", policy.crossOriginResourcePolicy);
+				reply.header("Content-Disposition", contentDisposition(policy.disposition, filePath));
+				reply.header("X-Content-Type-Options", "nosniff");
+				if (policy.varyOrigin) reply.header("Vary", "Origin, Accept-Encoding");
+				root.setHeaders?.(reply, filePath);
+			}
+		});
+		fastify.log.debug(`[arc] asset root "${root.prefix}" → ${String(root.root)} (cache: ${root.cache ?? "revalidate"}, cross-origin: ${policy.crossOriginResourcePolicy})`);
+	}
+}
+//#endregion
 //#region src/factory/module/resolve.ts
 /**
 * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
@@ -16,6 +162,7 @@ import qs from "qs";
 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.");
+	if (resolved.name.trim().length === 0) throw new Error("[arc] a `modules` entry has an empty (or whitespace-only) `name`. A module's name is its graph key, its `arc.modules` export key, its `dependsOn` target, and its label in every boot diagnostic — give it a stable, non-empty identifier.");
 	return resolved;
 }
 /** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
@@ -23,6 +170,26 @@ async function resolveContribution(contribution, fastify) {
 	if (!contribution) return [];
 	return typeof contribution === "function" ? await contribution(fastify) : contribution;
 }
+/**
+* `resolveContribution` with module attribution — the form every arm collector
+* should use.
+*
+* A contribution factory closes over booted engines, so it throws for exactly
+* the reasons a bootstrap does ("connection unavailable", "engine not ready").
+* Bare, that message names neither the module nor the arm, which in a graph of
+* twenty modules turns a one-line fix into a bisect. Every other module
+* boundary (`plugins`, `bootstrap`, `resources`, `afterResources`) already
+* wraps with the owning module's name; this keeps the arms consistent with
+* them. The original error is preserved via `{ cause }`.
+*/
+async function resolveModuleArm(module, arm, contribution, fastify) {
+	try {
+		return 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 });
+	}
+}
 //#endregion
 //#region src/factory/module/contributions.ts
 /**
@@ -49,7 +216,7 @@ function collectModuleHealthChecks(modules) {
 async function collectModuleWorkflows(fastify, modules) {
 	const out = [];
 	for (const m of modules) {
-		const wfs = await resolveContribution(m.workflows, fastify);
+		const wfs = await resolveModuleArm(m, "workflows", m.workflows, fastify);
 		out.push(...wfs);
 	}
 	return out;
@@ -64,7 +231,7 @@ async function collectModuleScheduledJobs(fastify, modules) {
 	const owner = /* @__PURE__ */ new Map();
 	const out = [];
 	for (const m of modules) {
-		const jobs = await resolveContribution(m.scheduledJobs, fastify);
+		const jobs = await resolveModuleArm(m, "scheduledJobs", m.scheduledJobs, fastify);
 		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.`);
@@ -91,7 +258,7 @@ async function subscribeModuleEventHandlers(fastify, modules) {
 	const owner = /* @__PURE__ */ new Map();
 	try {
 		for (const m of modules) {
-			const handlers = await resolveContribution(m.eventHandlers, fastify);
+			const handlers = await resolveModuleArm(m, "eventHandlers", m.eventHandlers, fastify);
 			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.`);
@@ -235,6 +402,98 @@ function describeModuleCycle(remaining, byName) {
 	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.`;
 }
 //#endregion
+//#region src/factory/module/state.ts
+/**
+* The honest read of the state map. `fastify.arc` is optional (see
+* fastify-augmentation.ts) and `moduleStates` is populated by
+* registerResources — both absent means "no module graph composed here"
+* (or a pre-2.31 embedding), so accessors degrade to undefined/false
+* rather than throwing.
+*/
+function readStates(fastify) {
+	return fastify.arc?.moduleStates;
+}
+/**
+* Record every composed module as `resolved`. Runs at the top of
+* registerResources, BEFORE any side-effecting phase — so from the first
+* lifecycle callback onward, `hasModule()` answers for the whole graph.
+* Null-proto map for the same reason as `arc.modules`: a module named
+* "__proto__" must be an own key, not a prototype write.
+*/
+function initModuleStates(fastify, names) {
+	const arc = fastify.arc;
+	if (!arc) return;
+	const states = Object.create(null);
+	for (const name of names) states[name] = "resolved";
+	arc.moduleStates = states;
+}
+/**
+* Internal transition writer — no-op when no state map exists (see above),
+* and no-op OUT of `failed`, which is terminal: rollback closes a module whose
+* bootstrap threw, and that cleanup succeeding must not erase the fact that
+* initialization failed (see the file header).
+*/
+function setModuleState(fastify, name, state) {
+	const states = readStates(fastify);
+	if (!states) return;
+	if (states[name] === "failed") return;
+	states[name] = state;
+}
+/**
+* Is `name` in the composed module graph? TRUE for resource-only modules and
+* modules that exported nothing — the question `hasModuleExports()` cannot
+* answer. FALSE before registerResources runs (no graph yet) and for
+* uncomposed names.
+*/
+function hasModule(fastify, name) {
+	const states = readStates(fastify);
+	return states !== void 0 && Object.hasOwn(states, name);
+}
+/**
+* The module's current lifecycle state, or `undefined` when the module is not
+* composed (or no graph has been composed on this instance). See the state
+* machine in the file header.
+*/
+function getModuleState(fastify, name) {
+	const states = readStates(fastify);
+	return states !== void 0 && Object.hasOwn(states, name) ? states[name] : void 0;
+}
+//#endregion
+//#region src/factory/module/teardown.ts
+function createModuleTeardown(fastify, modules) {
+	const initializedNames = /* @__PURE__ */ new Set();
+	const consumed = /* @__PURE__ */ new Set();
+	async function closeInitialized() {
+		const errors = [];
+		for (let index = modules.length - 1; index >= 0; index--) {
+			const m = modules[index];
+			if (!m || !initializedNames.has(m.name) || consumed.has(m.name)) continue;
+			consumed.add(m.name);
+			if (!m.onClose) {
+				setModuleState(fastify, m.name, "closed");
+				continue;
+			}
+			setModuleState(fastify, m.name, "closing");
+			try {
+				await m.onClose(fastify);
+				setModuleState(fastify, m.name, "closed");
+			} catch (err) {
+				setModuleState(fastify, m.name, "failed");
+				errors.push(new Error(`[arc] module "${m.name}" onClose() threw during teardown: ${err instanceof Error ? err.message : String(err)}`, { cause: err }));
+			}
+		}
+		return errors;
+	}
+	return {
+		markInitialized(module) {
+			initializedNames.add(module.name);
+		},
+		rollback: closeInitialized,
+		closeAll: closeInitialized,
+		hasComposedModules: () => modules.length > 0
+	};
+}
+//#endregion
 //#region src/factory/presets.ts
 /**
 * Production preset - strict security, performance optimized
@@ -460,7 +719,7 @@ async function registerArcCore(fastify, config, trackPlugin) {
 	await fastify.register(arcCorePlugin, { emitEvents: config.arcPlugins?.emitEvents !== false });
 	trackPlugin("arc-core");
 	if (config.arcPlugins?.events !== false) {
-		const { default: eventPlugin } = await import("./eventPlugin-D2NNR4py.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-CkffEihm.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -508,15 +767,15 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 		trackPlugin("arc-graceful-shutdown");
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-_NJeDd1_.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-BFHA6Scf.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-DSGuSVLW.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-BZr8v46E.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = config.stores?.queryCache ?? new (await (import("./memory-CmnzXE5Z.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-DR6wpa9F.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
@@ -525,26 +784,26 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 	}
 	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-BQ1w0dfl.mjs").then((n) => n.r);
+		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?.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-B9nmIY5V.mjs").then((n) => n.r);
+		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?.metrics) {
-		const { default: metricsPlugin } = await import("./metrics-fdxI5mn_.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-CUdw_wLB.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-gKWyryT3.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-CHDTor3P.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -613,7 +872,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-CIz1GjGm.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-D2l1mh4g.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -628,7 +887,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-Bq2OeEQL.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-C5NeD6bT.mjs").then((n) => n.r);
 	let errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 	if (moduleErrorMappers && moduleErrorMappers.length > 0) errorOpts = {
 		...errorOpts,
@@ -701,14 +960,29 @@ async function registerOne(parent, resource, mountRoutes) {
 * 5.  resources factory (if any) — resolved AFTER bootstrap, so engine-backed
 *                                  adapters can `await ensureEngine()` and pass
 *                                  live models/repos into `defineResource(...)`
-* 5b. module resources           — RESOLVED after the app factory, but PREPENDED
+* 5a. module resources           — RESOLVED after the app factory, but PREPENDED
 *                                  so they REGISTER before app resources (two
-*                                  orderings, both intentional — see §5b)
+*                                  orderings, both intentional — see §5a)
+* 5b. owns validation + filter   — verify each claim is supplied by its claimant,
+*                                  THEN drop the app forks it supersedes
 * 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.
+*
+* Boot is TRANSACTIONAL for module-held resources: phases 2–6 run inside one
+* try/catch. On any failure, arc unsubscribes already-active module event
+* handlers, then closes every module that ENTERED an init phase — reverse
+* composition order, best-effort (see module/teardown.ts) — and rethrows the
+* ORIGINAL boot error. Without this, a failure after module A's bootstrap but
+* before the §7b hook registration leaked A's clients/timers/engines with no
+* teardown path.
+*
+* "Entered", not "completed": a module is eligible for teardown from the
+* moment it enters `plugins()`/`bootstrap()`, so the callback that allocates a
+* client and THEN throws — the commonest partial-init shape — gets its closer
+* called too.
 */
 async function registerResources(fastify, config, preResolvedModules) {
 	if (config.preset === "production") {
@@ -722,160 +996,190 @@ async function registerResources(fastify, config, preResolvedModules) {
 		};
 	}
 	const modules = preResolvedModules ?? 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 });
+	initModuleStates(fastify, modules.map((m) => m.name));
+	const teardown = createModuleTeardown(fastify, modules);
+	let eventUnsubscribes = [];
+	try {
+		if (config.plugins) {
+			await config.plugins(fastify);
+			fastify.log.debug("Custom plugins registered");
 		}
-		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;
+		for (const m of modules) {
+			if (!m.plugins) continue;
+			teardown.markInitialized(m);
+			try {
+				await m.plugins(fastify);
+			} catch (err) {
+				setModuleState(fastify, m.name, "failed");
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`[arc] module "${m.name}" plugins() threw: ${msg}`, { cause: err });
+			}
 		}
-	}
-	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`);
-	}
-	let resolvedResources;
-	if (isResourcesFactory(config.resources)) {
-		try {
-			resolvedResources = await config.resources(fastify);
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			fastify.log.error(`Resources factory threw during boot: ${msg}`);
-			throw new Error(`[arc] resources factory threw: ${msg}. Check engine bootstrap order (did you forget a bootstrap step?) and that \`defineResource(...)\` calls inside the factory receive fully-booted adapters / repositories.`, { cause: err });
+		for (const m of modules) {
+			if (!m.bootstrap) {
+				setModuleState(fastify, m.name, "ready");
+				teardown.markInitialized(m);
+				continue;
+			}
+			let exported;
+			teardown.markInitialized(m);
+			setModuleState(fastify, m.name, "bootstrapping");
+			try {
+				exported = await m.bootstrap(fastify);
+			} catch (err) {
+				setModuleState(fastify, m.name, "failed");
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`[arc] module "${m.name}" bootstrap threw: ${msg}`, { cause: err });
+			}
+			setModuleState(fastify, m.name, "ready");
+			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;
+			}
 		}
-		config = {
-			...config,
-			resources: resolvedResources
-		};
-	} else resolvedResources = config.resources;
-	let discoveryRawDir;
-	let discoveryPath;
-	let discoveryYieldedZero = false;
-	if (resolvedResources === void 0 && config.resourceDir) {
-		const { loadResources } = await import("./loadResources-DpU8pfjV.mjs").then((n) => n.n);
-		const { resolve, dirname } = await import("node:path");
-		const { fileURLToPath } = await import("node:url");
-		const rawDir = config.resourceDir;
-		const dir = rawDir.startsWith("file://") ? dirname(fileURLToPath(rawDir)) : resolve(rawDir);
-		discoveryRawDir = rawDir;
-		discoveryPath = dir;
-		const discovered = await loadResources(dir, { logger: fastify.log });
-		if (discovered.length === 0) {
-			if (config.strictResourceDir) throw new Error(`[arc] loadResources: resourceDir "${rawDir}" resolved to "${dir}" 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.`);
-			discoveryYieldedZero = true;
+		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`);
 		}
-		resolvedResources = discovered;
-	}
-	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);
-		if (owned.size > 0) {
-			const before = resolvedResources.length;
-			resolvedResources = resolvedResources.filter((r) => !(r.name != null && owned.has(r.name)));
-			const dropped = before - resolvedResources.length;
-			if (dropped > 0) fastify.log.debug(`[arc] ${dropped} app resource(s) superseded by module owns() — the module version registers instead`);
+		let resolvedResources;
+		if (isResourcesFactory(config.resources)) {
+			try {
+				resolvedResources = await config.resources(fastify);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				fastify.log.error(`Resources factory threw during boot: ${msg}`);
+				throw new Error(`[arc] resources factory threw: ${msg}. Check engine bootstrap order (did you forget a bootstrap step?) and that \`defineResource(...)\` calls inside the factory receive fully-booted adapters / repositories.`, { cause: err });
+			}
+			config = {
+				...config,
+				resources: resolvedResources
+			};
+		} else resolvedResources = config.resources;
+		let discoveryRawDir;
+		let discoveryPath;
+		let discoveryYieldedZero = false;
+		if (resolvedResources === void 0 && config.resourceDir) {
+			const { loadResources } = await import("./loadResources-yawi9tAE.mjs").then((n) => n.n);
+			const { resolve, dirname } = await import("node:path");
+			const { fileURLToPath } = await import("node:url");
+			const rawDir = config.resourceDir;
+			const dir = rawDir.startsWith("file://") ? dirname(fileURLToPath(rawDir)) : resolve(rawDir);
+			discoveryRawDir = rawDir;
+			discoveryPath = dir;
+			const discovered = await loadResources(dir, { logger: fastify.log });
+			if (discovered.length === 0) {
+				if (config.strictResourceDir) throw new Error(`[arc] loadResources: resourceDir "${rawDir}" resolved to "${dir}" 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.`);
+				discoveryYieldedZero = true;
+			}
+			resolvedResources = discovered;
 		}
-	}
-	if (modules.length) {
+		const moduleResourceNames = /* @__PURE__ */ new Map();
 		const moduleResources = [];
 		for (const m of modules) {
 			if (!m.resources) continue;
+			let rs;
 			try {
-				const rs = typeof m.resources === "function" ? await m.resources(fastify) : m.resources;
-				moduleResources.push(...rs);
+				rs = typeof m.resources === "function" ? await m.resources(fastify) : m.resources;
 			} 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 });
 			}
+			const names = /* @__PURE__ */ new Set();
+			for (const r of rs) if (r.name != null) names.add(r.name);
+			moduleResourceNames.set(m.name, names);
+			moduleResources.push(...rs);
+		}
+		for (const m of modules) {
+			if (!m.owns?.length) continue;
+			const supplied = moduleResourceNames.get(m.name);
+			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.
+Resources supplied by "${m.name}": ${provided}.`);
+			}
+		}
+		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);
+			if (owned.size > 0) {
+				const before = resolvedResources.length;
+				resolvedResources = resolvedResources.filter((r) => !(r.name != null && owned.has(r.name)));
+				const dropped = before - resolvedResources.length;
+				if (dropped > 0) fastify.log.debug(`[arc] ${dropped} app resource(s) superseded by module owns() — the module version registers instead`);
+			}
 		}
 		if (moduleResources.length) resolvedResources = [...moduleResources, ...resolvedResources ?? []];
-	}
-	if (resolvedResources && resolvedResources.length > 0) {
-		const seen = /* @__PURE__ */ new Set();
-		for (const resource of resolvedResources) if (resource.name) {
-			if (seen.has(resource.name)) {
-				const msg = `Duplicate resource name "${resource.name}" detected. This will cause route conflicts. Check your resources array and loadResources() output. Common cause: stale compiled files in dist/ alongside src/. Use \`strictResources: true\` to fail boot.`;
-				if (config.strictResources) throw new Error(msg);
-				fastify.log.warn(msg);
+		if (resolvedResources && resolvedResources.length > 0) {
+			const seen = /* @__PURE__ */ new Set();
+			for (const resource of resolvedResources) if (resource.name) {
+				if (seen.has(resource.name)) {
+					const msg = `Duplicate resource name "${resource.name}" detected. This will cause route conflicts. Check your resources array and loadResources() output. Common cause: stale compiled files in dist/ alongside src/. Use \`strictResources: true\` to fail boot.`;
+					if (config.strictResources) throw new Error(msg);
+					fastify.log.warn(msg);
+				}
+				seen.add(resource.name);
 			}
-			seen.add(resource.name);
+			const prefixed = [];
+			const root = [];
+			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);
+			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}`);
+		} else {
+			const prefix = config.resourcePrefix ? ` (prefix: ${config.resourcePrefix})` : "";
+			const scanned = discoveryPath ? ` — resourceDir "${discoveryRawDir}" resolved to "${discoveryPath}"` : "";
+			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}`);
 		}
-		const prefixed = [];
-		const root = [];
-		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);
-		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}`);
-	} else {
-		const prefix = config.resourcePrefix ? ` (prefix: ${config.resourcePrefix})` : "";
-		const scanned = discoveryPath ? ` — resourceDir "${discoveryRawDir}" resolved to "${discoveryPath}"` : "";
-		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 });
+		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 });
+			}
 		}
-	}
-	const scheduledJobs = await collectModuleScheduledJobs(fastify, modules);
-	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-CjOd2MG9.mjs").then((n) => n.r);
-		await fastify.register(schedulesPlugin, {
-			...scheduleOptions,
-			schedules: frozenJobs
-		});
-		if (fastify.arc) {
-			fastify.arc.scheduledJobs = frozenJobs;
-			fastify.arc.plugins.set("arc-schedules", {
-				name: "arc-schedules",
-				options: { scheduleCount: frozenJobs.length },
-				registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+		const scheduledJobs = await collectModuleScheduledJobs(fastify, modules);
+		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);
+			await fastify.register(schedulesPlugin, {
+				...scheduleOptions,
+				schedules: frozenJobs
 			});
+			if (fastify.arc) {
+				fastify.arc.scheduledJobs = frozenJobs;
+				fastify.arc.plugins.set("arc-schedules", {
+					name: "arc-schedules",
+					options: { scheduleCount: frozenJobs.length },
+					registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+		}
+		eventUnsubscribes = await subscribeModuleEventHandlers(fastify, modules);
+		if (config.afterResources) {
+			await config.afterResources(fastify);
+			fastify.log.debug("afterResources hook executed");
 		}
-	}
-	const eventUnsubscribes = await subscribeModuleEventHandlers(fastify, modules);
-	if (config.afterResources) try {
-		await config.afterResources(fastify);
-		fastify.log.debug("afterResources hook executed");
 	} catch (err) {
-		const rollbackErrors = await unsubscribeModuleEventHandlers(eventUnsubscribes);
-		for (const rollbackError of rollbackErrors) fastify.log.error({ err: rollbackError }, "[arc] module event-handler rollback after afterResources failure failed");
+		const unsubscribeErrors = await unsubscribeModuleEventHandlers(eventUnsubscribes);
+		for (const unsubscribeError of unsubscribeErrors) fastify.log.error({ err: unsubscribeError }, "[arc] module event-handler rollback after boot failure failed");
+		const closeErrors = await teardown.rollback();
+		for (const closeError of closeErrors) fastify.log.error({ err: closeError }, "[arc] module onClose rollback after boot failure failed");
 		throw err;
 	}
 	if (config.onReady) {
@@ -884,13 +1188,14 @@ async function registerResources(fastify, config, preResolvedModules) {
 			await onReady(fastify);
 		});
 	}
-	const closers = modules.filter((m) => m.onClose).reverse();
 	const appOnClose = config.onClose;
-	if (closers.length || appOnClose || eventUnsubscribes.length) fastify.addHook("onClose", async () => {
+	if (teardown.hasComposedModules() || appOnClose || eventUnsubscribes.length) fastify.addHook("onClose", async () => {
 		const unsubscribeErrors = await unsubscribeModuleEventHandlers(eventUnsubscribes);
 		for (const err of unsubscribeErrors) fastify.log.error({ err }, "[arc] module event-handler shutdown unsubscribe failed");
-		for (const m of closers) await m.onClose?.(fastify);
+		const closeErrors = await teardown.closeAll();
+		for (const err of closeErrors) fastify.log.error({ err }, "[arc] module onClose failed during shutdown");
 		if (appOnClose) await appOnClose(fastify);
+		if (closeErrors.length > 0) throw closeErrors[0];
 	});
 }
 //#endregion
@@ -956,56 +1261,6 @@ function resolveCorsOptions(config) {
 	};
 }
 //#endregion
-//#region src/factory/security/pluginLoader.ts
-const PLUGIN_REGISTRY = {
-	cors: {
-		package: "@fastify/cors",
-		loader: () => import("@fastify/cors").then((m) => m.default)
-	},
-	helmet: {
-		package: "@fastify/helmet",
-		loader: () => import("@fastify/helmet").then((m) => m.default)
-	},
-	rateLimit: {
-		package: "@fastify/rate-limit",
-		loader: () => import("@fastify/rate-limit").then((m) => m.default)
-	},
-	underPressure: {
-		package: "@fastify/under-pressure",
-		loader: () => import("@fastify/under-pressure").then((m) => m.default)
-	},
-	sensible: {
-		package: "@fastify/sensible",
-		loader: () => import("@fastify/sensible").then((m) => m.default)
-	},
-	multipart: {
-		package: "@fastify/multipart",
-		loader: () => import("@fastify/multipart").then((m) => m.default),
-		optional: true
-	},
-	rawBody: {
-		package: "fastify-raw-body",
-		loader: () => import("fastify-raw-body").then((m) => m.default),
-		optional: true
-	}
-};
-async function loadPlugin(name, logger) {
-	const entry = PLUGIN_REGISTRY[name];
-	if (!entry) throw new Error(`Unknown plugin: ${name}`);
-	try {
-		return await entry.loader();
-	} catch (error) {
-		const err = error;
-		const isModuleNotFound = err.message.includes("Cannot find module") || err.message.includes("Cannot find package") || err.message.includes("MODULE_NOT_FOUND") || err.message.includes("Could not resolve");
-		if (isModuleNotFound && entry.optional) {
-			logger?.warn(`Optional plugin '${name}' skipped (${entry.package} not installed)`);
-			return null;
-		}
-		if (isModuleNotFound) throw new Error(`Plugin '${name}' requires package '${entry.package}' which is not installed.\nInstall it with: npm install ${entry.package}\nOr disable this plugin by setting ${name}: false in createApp options.`);
-		throw new Error(`Failed to load plugin '${name}': ${err.message}`);
-	}
-}
-//#endregion
 //#region src/factory/security/rateLimit.ts
 /** "Unlimited" as a number — @fastify/rate-limit's `max` fn must return one. */
 const UNLIMITED_MAX = Number.MAX_SAFE_INTEGER;
@@ -1329,8 +1584,26 @@ Missing:\n${lines}\n\nFix: pass durable adapters under \`stores\`, or use runtim
 * 10. afterResources() — post-registration wiring
 * 11. onReady/onClose  — lifecycle hooks
 * ```
+*
+* **Boot is all-or-nothing.** If any phase throws, the partially-built
+* instance is closed before the error propagates — see the wrapper below.
 */
 async function createApp(options) {
+	let partial;
+	try {
+		return await buildApp(options, (instance) => {
+			partial = instance;
+		});
+	} catch (err) {
+		if (partial) try {
+			await partial.close();
+		} catch (closeErr) {
+			partial.log?.error?.({ err: closeErr }, "[arc] cleanup of a partially-booted app failed; original boot error follows");
+		}
+		throw err;
+	}
+}
+async function buildApp(options, onInstance) {
 	if (options.debug !== void 0 && options.debug !== false) configureArcLogger({ debug: options.debug });
 	validateAuthOptions(options);
 	const deferredWarnings = validateDistributedRuntime(options);
@@ -1371,6 +1644,7 @@ async function createApp(options) {
 			keywords: ["example", ...config.ajv?.keywords ?? []]
 		} }
 	});
+	onInstance(fastify);
 	if (resolvedLogger !== false) configureArcLogger({
 		...options.debug !== void 0 && options.debug !== false ? { debug: options.debug } : {},
 		writer: createPinoWriter(fastify.log)
@@ -1386,6 +1660,7 @@ async function createApp(options) {
 		}
 	});
 	await registerSecurityPlugins(fastify, config);
+	if (config.assets?.length) await registerAssetRoots(fastify, config.assets);
 	await registerUtilityPlugins(fastify, config);
 	const trackPlugin = (name, opts) => {
 		const arc = fastify.arc;
@@ -1408,7 +1683,7 @@ async function createApp(options) {
 	await registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers);
 	await registerResources(fastify, config, resolvedModules);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-67tRawQZ.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-DIiZKGUt.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
 	if (config.serializeBigInt) {
@@ -1459,4 +1734,4 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { edgePreset as a, testingPreset as c, subscribeModuleEventHandlers as d, collectModuleHealthChecks as f, resolveModule as g, resolveContribution as h, developmentPreset as i, workerPreset as l, collectModuleWorkflows as m, createApp as n, getPreset as o, collectModuleScheduledJobs as p, createApp_exports as r, productionPreset as s, ArcFactory as t, orderModules as u };
+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 };