@classytic/arc 2.22.0 → 2.25.0

package/dist/{createApp-Ci7yG5gv.mjs → preloadResources-DfyngIN9.mjs}

@@ -1,66 +1,128 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { arcLog, configureArcLogger, createPinoWriter } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE } from "./types-bHblZ9YN.mjs";
+import { n as PUBLIC_SCOPE } from "./types-CSyCxl2V.mjs";
 import { t as createTenantKeyGenerator } from "./rateLimitKey-BoWRH3e7.mjs";
-import { t as createRequestIdGenerator } from "./requestId-5BhTVzBv.mjs";
+import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-CB_m4S32.mjs";
 import { t as parseJsonBody } from "./jsonBody-BlzAoGCe.mjs";
 import Fastify from "fastify";
 import qs from "qs";
-//#region src/testing/preloadResources.ts
+//#region src/factory/module/resolve.ts
 /**
-* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
-*
-* Accepts either:
-* - `{ import: 'default' }` form: values are the resource directly
-* - default form: values are the full module — picks first export with `toPlugin()`
-*
-* Throws if any module doesn't yield a valid `ResourceLike`.
+* 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.
 */
-function preloadResources(globResult) {
-	const resources = [];
-	for (const [path, value] of Object.entries(globResult)) {
-		const resource = pickResource(value);
-		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		resources.push(resource);
-	}
-	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+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;
+}
+/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
+async function resolveContribution(contribution, fastify) {
+	if (!contribution) return [];
+	return typeof contribution === "function" ? await contribution(fastify) : contribution;
 }
+//#endregion
+//#region src/factory/module/contributions.ts
 /**
-* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
-*
-* Use this when resources depend on prior bootstrap (e.g., engine init) and
-* cannot be evaluated at import time of the preload file.
+* Collect every module's `healthChecks` in the caller's order. Fails at boot
+* on a duplicate check `name` across modules, naming BOTH owning modules.
+* The host's app-level checks are appended AFTER this (modules-first,
+* host-last) by the caller.
 */
-async function preloadResourcesAsync(globResult) {
-	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
-		const resource = pickResource(await loader());
-		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		return resource;
-	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+function collectModuleHealthChecks(modules) {
+	return mergeHealthChecks(modules.map((module) => ({
+		owner: `module "${module.name}"`,
+		checks: module.healthChecks
+	})));
 }
-function pickResource(value) {
-	if (!value || typeof value !== "object") return void 0;
-	if (typeof value.toPlugin === "function") return value;
-	const mod = value;
-	const candidates = [
-		mod.default,
-		mod.resource,
-		...Object.values(mod)
-	];
-	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
+/**
+* Collect every module's `workflows`. Resolves factory contributions (so a
+* factory can close over a container the caller has already decorated on
+* `fastify`) and flattens to a single opaque array. Arc core deliberately
+* does NOT validate or interpret the values — the streamline integration
+* owns name/shape checks and registration. Called by the integration at init
+* time, not by arc's boot pipeline (workflows depend on the integration's
+* container).
+*/
+async function collectModuleWorkflows(fastify, modules) {
+	const out = [];
+	for (const m of modules) {
+		const wfs = await resolveContribution(m.workflows, fastify);
+		out.push(...wfs);
+	}
+	return out;
+}
+/**
+* Collect every module's `scheduledJobs`. Resolves factory contributions
+* (after bootstraps) and fails at boot on a duplicate job `name` across
+* modules. The caller passes the returned definitions to the canonical
+* schedules plugin; factories must therefore be resolved only once.
+*/
+async function collectModuleScheduledJobs(fastify, modules) {
+	const owner = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const m of modules) {
+		const jobs = await resolveContribution(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.`);
+			owner.set(job.name, m.name);
+			out.push(job);
+		}
+	}
+	return out;
 }
 //#endregion
-//#region src/factory/module.ts
+//#region src/factory/module/lifecycle.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.
+* Subscribe every module's `eventHandlers` in dependency order (pass the
+* `orderModules`-sorted list). Returns the ordered list of unsubscribe
+* functions so the caller can tear them down at shutdown BEFORE module
+* `onClose` (while module deps are still alive). Fails at boot on:
+*   - a duplicate NAMED handler across modules (attributing both owners);
+*   - a module declaring handlers while the event subsystem is unavailable.
+* Resolves factory contributions (after bootstraps) so a handler can close over
+* booted engines rather than a global getter.
 */
-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;
+async function subscribeModuleEventHandlers(fastify, modules) {
+	const unsubscribes = [];
+	const owner = /* @__PURE__ */ new Map();
+	try {
+		for (const m of modules) {
+			const handlers = await resolveContribution(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.`);
+			for (const def of handlers) {
+				if (def.name !== void 0) {
+					const prior = owner.get(def.name);
+					if (prior !== void 0) throw new Error(`[arc] duplicate event-handler name "${def.name}" — declared by module "${prior}" and module "${m.name}". Named event handlers must be unique across the module graph; prefix names with the owning module.`);
+					owner.set(def.name, m.name);
+				}
+				const patterns = Array.isArray(def.event) ? def.event : [def.event];
+				for (const pattern of patterns) unsubscribes.push(await bus.subscribe(pattern, def.handler));
+			}
+		}
+		return unsubscribes;
+	} catch (err) {
+		const rollbackErrors = await unsubscribeModuleEventHandlers(unsubscribes);
+		for (const rollbackError of rollbackErrors) fastify.log.error({ err: rollbackError }, "[arc] module event-handler activation rollback failed");
+		throw err;
+	}
+}
+/** Best-effort reverse-order teardown; every unsubscribe is attempted. */
+async function unsubscribeModuleEventHandlers(unsubscribes) {
+	const errors = [];
+	for (let index = unsubscribes.length - 1; index >= 0; index--) try {
+		await unsubscribes[index]?.();
+	} catch (err) {
+		errors.push(err);
+	}
+	return errors;
 }
+//#endregion
+//#region src/factory/module/order.ts
 /**
 * Order modules for composition by their `dependsOn` edges — a STABLE
 * topological sort. Called once at the start of the bootstrap phase; every
@@ -151,6 +213,8 @@ 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/index.ts
 /**
 * Identity helper for authoring a typed module — mirrors `defineResource`.
 * Gives inference + a single obvious construction site; does no work.
@@ -200,7 +264,7 @@ const productionPreset = {
 			censor: "[REDACTED]"
 		}
 	},
-	trustProxy: true,
+	trustProxy: false,
 	helmet: { contentSecurityPolicy: { directives: {
 		defaultSrc: ["'self'"],
 		styleSrc: ["'self'", "'unsafe-inline'"],
@@ -237,6 +301,7 @@ const productionPreset = {
 	underPressure: {
 		exposeStatusRoute: true,
 		maxEventLoopDelay: 3e3,
+		maxEventLoopUtilization: .98,
 		maxHeapUsedBytes: 1024 * 1024 * 1024,
 		maxRssBytes: 1024 * 1024 * 1024
 	}
@@ -402,7 +467,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-DJG2D7sy.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-DrQ_FesK.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			...eventOpts,
@@ -423,16 +488,27 @@ async function registerArcCore(fastify, config, trackPlugin) {
 *
 * @param modules - Plugin modules loaded by registerArcCore (avoids re-importing)
 */
-async function registerArcPlugins(fastify, config, trackPlugin, modules) {
+async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleHealthChecks = []) {
 	const { requestIdPlugin, healthPlugin, gracefulShutdownPlugin } = modules;
 	if (config.arcPlugins?.requestId !== false) {
 		await fastify.register(requestIdPlugin);
 		trackPlugin("arc-request-id");
 	}
 	if (config.arcPlugins?.health !== false) {
-		const healthOpts = typeof config.arcPlugins?.health === "object" && config.arcPlugins.health !== null ? config.arcPlugins.health : {};
+		const appHealth = typeof config.arcPlugins?.health === "object" && config.arcPlugins.health !== null ? config.arcPlugins.health : {};
+		const checks = mergeHealthChecks([{
+			owner: "the module graph",
+			checks: moduleHealthChecks
+		}, {
+			owner: "arcPlugins.health",
+			checks: appHealth.checks
+		}]);
+		const healthOpts = {
+			...appHealth,
+			checks
+		};
 		await fastify.register(healthPlugin, healthOpts);
-		trackPlugin("arc-health", healthOpts);
+		trackPlugin("arc-health", { checkCount: healthOpts.checks?.length ?? 0 });
 	}
 	if (config.arcPlugins?.gracefulShutdown !== false) {
 		await fastify.register(gracefulShutdownPlugin);
@@ -445,9 +521,9 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-caching", opts);
 	}
 	if (config.arcPlugins?.queryCache) {
-		const { queryCachePlugin } = await import("./queryCachePlugin-DzqLN904.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-DSGuSVLW.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();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-CmnzXE5Z.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
@@ -456,11 +532,18 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 	}
 	if (config.arcPlugins?.sse) if (config.arcPlugins?.events === false) fastify.log.warn("SSE plugin requires events plugin (arcPlugins.events). SSE disabled.");
 	else {
-		const { default: ssePlugin } = await import("./sse-CfUjwjDk.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("./sse-BQ1w0dfl.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-Cuw_deA-.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 opts = config.arcPlugins.metrics === true ? {} : config.arcPlugins.metrics;
@@ -468,7 +551,7 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules) {
 		trackPlugin("arc-metrics", opts);
 	}
 	if (config.arcPlugins?.versioning) {
-		const { default: versioningPlugin } = await import("./versioning-Dk-71iIz.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-gKWyryT3.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -537,7 +620,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-COpYKt2h.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-CIz1GjGm.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -552,7 +635,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-BTzXSwIg.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-Bq2OeEQL.mjs").then((n) => n.r);
 	let errorOpts = typeof config.errorHandler === "object" ? config.errorHandler : { includeStack: config.preset !== "production" };
 	if (moduleErrorMappers && moduleErrorMappers.length > 0) errorOpts = {
 		...errorOpts,
@@ -773,9 +856,34 @@ async function registerResources(fastify, config, preResolvedModules) {
 			throw new Error(`[arc] module "${m.name}" afterResources() threw: ${msg}`, { cause: err });
 		}
 	}
-	if (config.afterResources) {
+	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 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");
+		throw err;
 	}
 	if (config.onReady) {
 		const onReady = config.onReady;
@@ -785,7 +893,9 @@ async function registerResources(fastify, config, preResolvedModules) {
 	}
 	const closers = modules.filter((m) => m.onClose).reverse();
 	const appOnClose = config.onClose;
-	if (closers.length || appOnClose) fastify.addHook("onClose", async () => {
+	if (closers.length || 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);
 		if (appOnClose) await appOnClose(fastify);
 	});
@@ -1011,7 +1121,21 @@ async function registerUtilityPlugins(fastify, config) {
 	if (config.preset === "production") fastify.log.warn("Response compression is not enabled (Fastify 5 stream issues). Use a reverse proxy (Nginx, Caddy, Cloudflare) for gzip/brotli in production.");
 	if (config.underPressure !== false) {
 		const underPressure = await loadPlugin("underPressure");
-		await fastify.register(underPressure, config.underPressure ?? { exposeStatusRoute: true });
+		const hostConfig = config.underPressure;
+		const effective = hostConfig ?? {
+			exposeStatusRoute: true,
+			maxEventLoopDelay: 3e3,
+			maxEventLoopUtilization: .98
+		};
+		if (config.preset === "production" && hostConfig && ![
+			"maxEventLoopDelay",
+			"maxEventLoopUtilization",
+			"maxHeapUsedBytes",
+			"maxRssBytes",
+			"pressureHandler",
+			"healthCheck"
+		].some((key) => key in hostConfig)) fastify.log.warn("[arc] underPressure is configured without any pressure threshold (maxEventLoopDelay / maxEventLoopUtilization / maxHeapUsedBytes / maxRssBytes) — it will monitor but never shed load. Set at least an event-loop threshold, and size heap/RSS limits from your container memory limit.");
+		await fastify.register(underPressure, effective);
 		fastify.log.debug("Health monitoring (under-pressure) enabled");
 	}
 	if (config.sensible !== false) {
@@ -1184,6 +1308,8 @@ function validateDistributedRuntime(options) {
 			hint: "a Redis-backed query-cache adapter"
 		});
 	}
+	const schedules = options.arcPlugins?.schedules;
+	if (schedules && typeof schedules === "object" && schedules.enabled !== false && !schedules.lock) deferredWarnings.push("runtime: 'distributed' — schedules configured without a `lock` adapter. EVERY replica will fire every schedule tick. Pass an ecosystem lock (e.g. createMongoLockAdapter) under arcPlugins.schedules.lock for single-firer leases.");
 	if (missing.length > 0) {
 		const lines = missing.map((m) => `  • ${m.key.padEnd(20)} → ${m.hint}`).join("\n");
 		throw new Error(`[Arc] runtime: 'distributed' requires durable (Redis/MongoDB) adapters, not memory.
@@ -1220,8 +1346,10 @@ async function createApp(options) {
 		...options.preset ? getPreset(options.preset) : {},
 		...options
 	};
+	const inheritedTrustProxyDefault = options.preset === "production" && options.trustProxy === void 0;
 	const resolvedModules = orderModules(await Promise.all((config.modules ?? []).map((m) => resolveModule(m))));
 	const moduleErrorMappers = resolvedModules.flatMap((m) => m.errorMappers ?? []);
+	const moduleHealthChecks = collectModuleHealthChecks(resolvedModules);
 	const resolvedLogger = resolveLoggerConfig(config.logger);
 	const fastify = Fastify({
 		logger: resolvedLogger,
@@ -1255,12 +1383,7 @@ async function createApp(options) {
 		writer: createPinoWriter(fastify.log)
 	});
 	for (const warning of deferredWarnings) fastify.log.warn(warning);
-	if (config.typeProvider === "typebox") try {
-		const { TypeBoxValidatorCompiler } = await import("@fastify/type-provider-typebox");
-		fastify.setValidatorCompiler(TypeBoxValidatorCompiler);
-	} catch {
-		fastify.log.warn("typeProvider: \"typebox\" requested but @fastify/type-provider-typebox is not installed.");
-	}
+	if (inheritedTrustProxyDefault) fastify.log.warn("[arc] preset: 'production' now defaults to trustProxy: false (fail-closed; was true before 2.24). If this app runs behind a load balancer or reverse proxy, request.ip is currently the PROXY's address — rate-limit keys collapse onto one bucket and audit logs record the wrong client. Set trustProxy explicitly: a hop count (trustProxy: 1), a CIDR allow-list ('10.0.0.0/8'), a resolver function, or false if clients truly connect directly.");
 	fastify.removeContentTypeParser("application/json");
 	fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
 		try {
@@ -1280,7 +1403,12 @@ async function createApp(options) {
 			registeredAt: (/* @__PURE__ */ new Date()).toISOString()
 		});
 	};
-	await registerArcPlugins(fastify, config, trackPlugin, await registerArcCore(fastify, config, trackPlugin));
+	const arcModules = await registerArcCore(fastify, config, trackPlugin);
+	if (fastify.arc) {
+		fastify.arc.healthChecks = Object.freeze([...moduleHealthChecks]);
+		fastify.arc.moduleDefinitions = Object.freeze([...resolvedModules]);
+	}
+	await registerArcPlugins(fastify, config, trackPlugin, arcModules, moduleHealthChecks);
 	decorateRequestScope(fastify);
 	await registerAuth(fastify, config, trackPlugin);
 	await registerElevation(fastify, config, trackPlugin);
@@ -1338,4 +1466,48 @@ const ArcFactory = {
 	}
 };
 //#endregion
-export { edgePreset as a, testingPreset as c, getModuleExports as d, orderModules as f, preloadResourcesAsync as h, developmentPreset as i, workerPreset as l, preloadResources as m, createApp as n, getPreset as o, resolveModule as p, createApp_exports as r, productionPreset as s, ArcFactory as t, defineModule as u };
+//#region src/factory/preloadResources.ts
+/**
+* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
+*
+* Accepts either:
+* - `{ import: 'default' }` form: values are the resource directly
+* - default form: values are the full module — picks first export with `toPlugin()`
+*
+* Throws if any module doesn't yield a valid `ResourceLike`.
+*/
+function preloadResources(globResult) {
+	const resources = [];
+	for (const [path, value] of Object.entries(globResult)) {
+		const resource = pickResource(value);
+		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
+		resources.push(resource);
+	}
+	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+}
+/**
+* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
+*
+* Use this when resources depend on prior bootstrap (e.g., engine init) and
+* cannot be evaluated at import time of the preload file.
+*/
+async function preloadResourcesAsync(globResult) {
+	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
+		const resource = pickResource(await loader());
+		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
+		return resource;
+	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+}
+function pickResource(value) {
+	if (!value || typeof value !== "object") return void 0;
+	if (typeof value.toPlugin === "function") return value;
+	const mod = value;
+	const candidates = [
+		mod.default,
+		mod.resource,
+		...Object.values(mod)
+	];
+	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
+}
+//#endregion
+export { collectModuleScheduledJobs as _, createApp_exports as a, resolveModule as b, getPreset as c, workerPreset as d, defineModule as f, collectModuleHealthChecks as g, subscribeModuleEventHandlers as h, createApp as i, productionPreset as l, orderModules as m, preloadResourcesAsync as n, developmentPreset as o, getModuleExports as p, ArcFactory as r, edgePreset as s, preloadResources as t, testingPreset as u, collectModuleWorkflows as v, resolveContribution as y };

package/dist/presets/filesUpload.d.mts

@@ -1,6 +1,6 @@
-import { Y as PresetResult } from "../index-DbtgCOCj.mjs";
-import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { Y as PresetResult } from "../index-DPRH0Cme.mjs";
+import { i as RequestScope } from "../types-DjC-KUCz.mjs";
+import { t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
 import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-DLUZ04kK.mjs";
 //#region src/presets/filesUpload.d.ts
 interface FilesUploadPresetRoutes {

package/dist/presets/filesUpload.mjs

@@ -1,7 +1,7 @@
 import { i as NotFoundError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
-import { c as getOrgId, g as getUserId } from "../types-bHblZ9YN.mjs";
-import { b as allowPublic, w as requireAuth } from "../permissions-BJMuKMl7.mjs";
-import { t as multipartBody } from "../multipartBody-CHEQSZ6G.mjs";
+import { c as getOrgId, g as getUserId } from "../types-CSyCxl2V.mjs";
+import { A as requireAuth, E as allowPublic } from "../permissions-BrtiBKGs.mjs";
+import { t as multipartBody } from "../multipartBody-D0eBvkeq.mjs";
 //#region src/presets/filesUpload.ts
 const DEFAULT_FIELD_NAME = "file";
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;

package/dist/presets/index.d.mts

@@ -1,4 +1,5 @@
-import { Rt as IControllerResponse, U as ResourceConfig, Y as PresetResult, d as PaginationResult, qt as AnyRecord, zt as IRequestContext } from "../index-DbtgCOCj.mjs";
+import { Rt as IControllerResponse, U as ResourceConfig, Y as PresetResult, d as PaginationResult, zt as IRequestContext } from "../index-DPRH0Cme.mjs";
+import { c as AnyRecord } from "../types-Dmw-6Qeo.mjs";
 import { FilesUploadPresetOptions, FilesUploadPresetPermissions, FilesUploadPresetRoutes, filesUploadPreset } from "./filesUpload.mjs";
 import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 import { SearchHandler, SearchPresetOptions, SearchRouteConfig, searchPreset } from "./search.mjs";

package/dist/presets/index.mjs

@@ -1,5 +1,5 @@
 import { multiTenantPreset } from "./multiTenant.mjs";
-import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-gw0ciIUD.mjs";
+import { a as registerPreset, c as auditedPreset, d as ownedByUserPreset, i as getPreset, l as softDeletePreset, n as flexibleMultiTenantPreset, o as treePreset, r as getAvailablePresets, s as bulkPreset, t as applyPresets, u as slugLookupPreset } from "../presets-DwFDVKP0.mjs";
 import { filesUploadPreset } from "./filesUpload.mjs";
 import { searchPreset } from "./search.mjs";
 export { applyPresets, auditedPreset, bulkPreset, filesUploadPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, searchPreset, slugLookupPreset, softDeletePreset, treePreset };

package/dist/presets/multiTenant.d.mts

@@ -1,4 +1,4 @@
-import { X as CrudRouteKey, Y as PresetResult } from "../index-DbtgCOCj.mjs";
+import { X as CrudRouteKey, Y as PresetResult } from "../index-DPRH0Cme.mjs";
 //#region src/presets/multiTenant.d.ts
 /**
  * One tenant dimension for multi-field filtering. Discriminated by source:

package/dist/presets/multiTenant.mjs

@@ -1,5 +1,5 @@
 import "../constants-DNre0wRg.mjs";
-import { b as isElevated, c as getOrgId, d as getScopeContext, m as getTeamId, u as getRequestScope, v as hasOrgAccess } from "../types-bHblZ9YN.mjs";
+import { b as isElevated, c as getOrgId, d as getScopeContext, m as getTeamId, u as getRequestScope, v as hasOrgAccess } from "../types-CSyCxl2V.mjs";
 //#region src/presets/multiTenant.ts
 /**
 * Resolve a single TenantFieldSpec against the current scope.

package/dist/presets/search.d.mts

@@ -1,5 +1,5 @@
-import { At as RouteDefinition, Pt as ControllerHandler, Y as PresetResult, jt as RouteMcpConfig } from "../index-DbtgCOCj.mjs";
-import { t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { At as RouteDefinition, Pt as ControllerHandler, Y as PresetResult, jt as RouteMcpConfig } from "../index-DPRH0Cme.mjs";
+import { t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
 //#region src/presets/search.d.ts
 /**
  * Search Preset — backend-agnostic search / vector / embed routes

package/dist/presets/search.mjs

@@ -1,4 +1,4 @@
-import { b as allowPublic, w as requireAuth } from "../permissions-BJMuKMl7.mjs";
+import { A as requireAuth, E as allowPublic } from "../permissions-BrtiBKGs.mjs";
 //#region src/presets/search.ts
 const BUILTINS = [
 	{

package/dist/{presets-gw0ciIUD.mjs → presets-DwFDVKP0.mjs}

@@ -1,5 +1,5 @@
-import { b as isElevated, n as PUBLIC_SCOPE } from "./types-bHblZ9YN.mjs";
-import { E as requireRoles, b as allowPublic, w as requireAuth } from "./permissions-BJMuKMl7.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE } from "./types-CSyCxl2V.mjs";
+import { A as requireAuth, E as allowPublic, M as requireRoles } from "./permissions-BrtiBKGs.mjs";
 import { multiTenantPreset } from "./presets/multiTenant.mjs";
 //#region src/presets/ownedByUser.ts
 /**

package/dist/{queryCachePlugin-DzqLN904.mjs → queryCachePlugin-DSGuSVLW.mjs}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
-import { t as MemoryCacheStore } from "./memory-CLXA2VeJ.mjs";
 import { t as hasEvents } from "./typeGuards-C9KXUly6.mjs";
 import { i as versionKey, r as tagVersionKey } from "./keys-Cd316u_y.mjs";
+import { t as MemoryCacheStore } from "./memory-CmnzXE5Z.mjs";
 import fp from "fastify-plugin";
 //#region src/cache/QueryCache.ts
 var QueryCache = class {
@@ -33,7 +33,9 @@ var QueryCache = class {
 		};
 	}
 	async set(key, data, config) {
-		const staleTimeSec = config.staleTime ?? 0;
+		const baseStaleTimeSec = config.staleTime ?? 0;
+		const jitter = config.jitter ?? 0;
+		const staleTimeSec = jitter > 0 ? Math.max(0, baseStaleTimeSec * (1 + (Math.random() * 2 - 1) * jitter)) : baseStaleTimeSec;
 		const totalTtlSec = staleTimeSec + (config.gcTime ?? 60);
 		const now = Date.now();
 		const envelope = {
@@ -54,9 +56,7 @@ var QueryCache = class {
 	}
 	/** Bump resource version — orphans all cached queries for this resource */
 	async bumpResourceVersion(resource) {
-		const key = versionKey(resource);
-		const newVersion = Date.now();
-		await this.store.set(key, newVersion, 1440 * 60);
+		await this.bumpVersion(versionKey(resource));
 	}
 	/** Get current version for a tag */
 	async getTagVersion(tag) {
@@ -64,11 +64,42 @@ var QueryCache = class {
 	}
 	/** Bump tag version — orphans all cached queries tagged with this tag */
 	async bumpTagVersion(tag) {
-		const key = tagVersionKey(tag);
-		const newVersion = Date.now();
-		await this.store.set(key, newVersion, 1440 * 60);
+		await this.bumpVersion(tagVersionKey(tag));
+	}
+	/**
+	* Version-bump semantics:
+	*
+	*  - `store.increment` present (Redis `INCR`) — atomic and strictly
+	*    monotonic across replicas; concurrent bumps can never collide or
+	*    go backwards.
+	*  - fallback — read-modify-write with `max(now, current + 1)`: two
+	*    bumps in the same millisecond and clock regressions still advance
+	*    the version. Concurrent bumps from DIFFERENT replicas can lose one
+	*    write, which is why distributed hosts should use an incrementing
+	*    store (`runtime: 'distributed'` already requires a shared one).
+	*
+	* Version keys must outlive every derived cache entry — that invariant
+	* is what makes version invalidation sound (a version key expiring back
+	* to 0 would make entries written under the pre-reset version
+	* addressable again). The 1-year TTL applies with the repo-core
+	* TTL-ON-CREATE semantics, so a version key expires one year after its
+	* FIRST bump — safe, because a revived collision would need an entry to
+	* outlive that reset and entry TTLs are minutes-scale (staleTime +
+	* gcTime). The read-modify-write fallback uses plain `set`, which
+	* refreshes the TTL per bump — strictly longer-lived, equally safe.
+	*/
+	async bumpVersion(key) {
+		if (typeof this.store.increment === "function") {
+			await this.store.increment(key, 1, VERSION_TTL_SECONDS);
+			return;
+		}
+		const current = await this.store.get(key);
+		const next = Math.max(Date.now(), (current ?? 0) + 1);
+		await this.store.set(key, next, VERSION_TTL_SECONDS);
 	}
 };
+/** See `bumpVersion` — effectively non-expiring, refreshed on every bump. */
+const VERSION_TTL_SECONDS = 365 * 24 * 60 * 60;
 //#endregion
 //#region src/cache/queryCachePlugin.ts
 var queryCachePlugin_exports = /* @__PURE__ */ __exportAll({ queryCachePlugin: () => queryCachePlugin });

package/dist/{queryCachePlugin-CfYWq-Ak.d.mts → queryCachePlugin-br4otiqF.d.mts}

@@ -1,5 +1,5 @@
-import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
-import { i as QueryCache } from "./QueryCache-Z1B38koh.mjs";
+import { r as CacheStore } from "./interface-BGZCzOGL.mjs";
+import { i as QueryCache } from "./QueryCache-DOMT_iq7.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/cache/queryCachePlugin.d.ts
 interface QueryCachePluginOptions {