@classytic/arc 2.38.0 → 2.41.0

package/dist/plugins/index.mjs

@@ -1,20 +1,20 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { p as MUTATION_OPERATIONS } from "../constants-BONghE1Y.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS } from "../constants-BxLgNFF7.mjs";
 import { arcLog } from "../logger/index.mjs";
-import { c as getOrgId } from "../types-BqLyyH0o.mjs";
-import { n as requestContext } from "../requestContext-DpmntRZy.mjs";
-import { t as hasEvents } from "../typeGuards-DHTnEs5X.mjs";
-import { t as HookSystem } from "../HookSystem-C0ikzqQf.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-DPcX--zk.mjs";
-import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-Bh0N_FLk.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-a3ZEcJJs.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-BdmIWPba.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-CsWaIVTa.mjs";
-import { n as realtime_default, t as realtimePlugin } from "../realtime-CPmjjgqd.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-BHebarf0.mjs";
-import { n as schedules_default, t as schedulesPlugin } from "../schedules-DthM8Qag.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-D4MYqkic.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-C2r0eOZ4.mjs";
+import { c as getOrgId } from "../types-CDy3-zw1.mjs";
+import { n as requestContext } from "../requestContext-cSVKnYPk.mjs";
+import { t as hasEvents } from "../typeGuards-D7tHFdH6.mjs";
+import { t as HookSystem } from "../HookSystem-CxvZBo77.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-Cu7uTJp9.mjs";
+import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-CxQzbJmr.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-DsWDjIxx.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-CIMkCOWm.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-BaKnq8ag.mjs";
+import { n as realtime_default, t as realtimePlugin } from "../realtime-FnnD0n3Z.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-DPHsdw-5.mjs";
+import { n as schedules_default, t as schedulesPlugin } from "../schedules-BktJb3Y3.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-CH7Slxc1.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-DuVWcu-F.mjs";
 import fp from "fastify-plugin";
 import { performance as performance$1 } from "node:perf_hooks";
 //#region src/core/arcCorePlugin.ts
@@ -35,12 +35,14 @@ const arcCorePlugin = async (fastify, opts = {}) => {
 	for (const field of [
 		"_policyFilters",
 		"_ownershipCheck",
+		"_crossTenantRead",
 		"fieldMask",
 		"policyMetadata",
 		"document"
 	]) if (!fastify.hasRequestDecorator(field)) fastify.decorateRequest(field, void 0);
 	fastify.addHook("onRequest", (request, _reply, done) => {
 		const store = {
+			kind: "request",
 			requestId: request.id,
 			startTime: performance.now()
 		};
@@ -153,18 +155,20 @@ function createPlugin(name, definition) {
 //#endregion
 //#region src/plugins/gracefulShutdown.ts
 const gracefulShutdownPlugin = async (fastify, opts = {}) => {
-	const { timeout = 3e4, onShutdown, signals = ["SIGTERM", "SIGINT"], logEvents = true, onForceExit = () => process.exit(1) } = opts;
-	let isShuttingDown = false;
+	const { timeout = 3e4, onShutdown, signals = ["SIGTERM", "SIGINT"], logEvents = true, drainDelayMs = 0, onForceExit = () => process.exit(1) } = opts;
+	const state = { draining: false };
 	const signalHandlers = /* @__PURE__ */ new Map();
 	const shutdown = async (signal) => {
-		if (isShuttingDown) {
+		if (state.draining) {
 			if (logEvents) fastify.log?.warn?.({ signal }, "Shutdown already in progress, ignoring signal");
 			return;
 		}
-		isShuttingDown = true;
+		state.draining = true;
+		state.since = /* @__PURE__ */ new Date();
 		if (logEvents) fastify.log?.info?.({
 			signal,
-			timeout
+			timeout,
+			drainDelayMs
 		}, "Shutdown signal received, starting graceful shutdown");
 		const forceExitTimer = setTimeout(() => {
 			if (logEvents) fastify.log?.error?.("Graceful shutdown timeout exceeded, forcing exit");
@@ -172,6 +176,10 @@ const gracefulShutdownPlugin = async (fastify, opts = {}) => {
 		}, timeout);
 		forceExitTimer.unref();
 		try {
+			if (drainDelayMs > 0) {
+				if (logEvents) fastify.log?.info?.({ drainDelayMs }, "Draining — readiness failing, still serving");
+				await new Promise((resolve) => setTimeout(resolve, drainDelayMs));
+			}
 			if (logEvents) fastify.log?.info?.("Closing server to new connections");
 			await fastify.close();
 			if (onShutdown) {
@@ -200,7 +208,11 @@ const gracefulShutdownPlugin = async (fastify, opts = {}) => {
 	fastify.decorate("shutdown", async () => {
 		await shutdown("MANUAL");
 	});
-	if (logEvents) fastify.log?.debug?.({ signals }, "Graceful shutdown plugin registered");
+	fastify.decorate("shutdownState", state);
+	if (logEvents) fastify.log?.debug?.({
+		signals,
+		drainDelayMs
+	}, "Graceful shutdown plugin registered");
 };
 var gracefulShutdown_default = fp(gracefulShutdownPlugin, {
 	name: "arc-graceful-shutdown",

package/dist/plugins/response-cache.mjs

@@ -1,5 +1,6 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { t as hasEvents } from "../typeGuards-DHTnEs5X.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-DSA_dH1_.mjs";
+import { t as hasEvents } from "../typeGuards-D7tHFdH6.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**
@@ -96,6 +97,12 @@ const responseCachePluginImpl = async (fastify, opts = {}) => {
 	if (maxEntries > 5e3) fastify.log.warn(`[arc] responseCache maxEntries=${maxEntries}: prefix invalidation scans all entries synchronously on every mutating request — expect event-loop pauses at this size. This cache is an instance-local micro-cache; for large shared caching use the queryCache with a Redis store instead.`);
 	const cache = new LRUCache(maxEntries);
 	const invalidateMethods = new Set(invalidateOn.map((m) => m.toUpperCase()));
+	declareRuntimeCapability(fastify, {
+		subsystem: "http.response-cache",
+		durability: "memory",
+		accepted: true,
+		detail: "per-replica micro-cache; correctness comes from short TTLs, not shared state"
+	});
 	if (!fastify.hasRequestDecorator("__arcCacheTTL")) fastify.decorateRequest("__arcCacheTTL", void 0);
 	/** Find TTL for a given URL path (seconds) */
 	function getTTL(url) {

package/dist/plugins/tracing-entry.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
 import { createRequire } from "node:module";
 import fp from "fastify-plugin";
 //#region src/plugins/tracing.ts
@@ -59,7 +59,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.38.0";
+	const resolvedVersion = serviceVersion ?? "2.41.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-Da7IT_qJ.mjs → pluralize-2_U6QZQg.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
 //#region src/utils/pluralize.ts
 /**
 * Lightweight English pluralization for the Arc CLI.

package/dist/{preloadResources-DlhH81py.mjs → preloadResources-Bbp4QJ8V.mjs}

@@ -1,12 +1,12 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-Add2L50I.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-DjDuyglE.mjs";
 import { arcLog, configureArcLogger, createPinoWriter, enterArcLoggerScope, runWithArcLogger } from "./logger/index.mjs";
-import { n as PUBLIC_SCOPE } from "./types-BqLyyH0o.mjs";
-import { t as auditRuntimeCapabilities } from "./runtimeCapabilities-D793Pxci.mjs";
-import { t as createTenantKeyGenerator } from "./rateLimitKey-CewdR-m6.mjs";
-import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-Bh0N_FLk.mjs";
-import { t as parseJsonBody } from "./jsonBody-DVui0uJl.mjs";
-import { r as wrapWithBoundary } from "./subscribe-helpers-CBZOi6pk.mjs";
+import { n as PUBLIC_SCOPE } from "./types-CDy3-zw1.mjs";
+import { r as initRuntimeCapabilityRegistry, t as auditRuntimeCapabilities } from "./runtimeCapabilities-DSA_dH1_.mjs";
+import { n as isScopeAwareKeyGenerator, t as createTenantKeyGenerator } from "./rateLimitKey-CK-EU2L8.mjs";
+import { i as createRequestIdGenerator, r as mergeHealthChecks } from "./health-CxQzbJmr.mjs";
+import { t as parseJsonBody } from "./jsonBody-Cq9KYl2Z.mjs";
+import { r as wrapWithBoundary } from "./subscribe-helpers-AVYPgqTl.mjs";
 import { isProductionEnv } from "@classytic/primitives/environment";
 import Fastify from "fastify";
 import qs from "qs";
@@ -851,7 +851,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-DJwpGMzx.mjs").then((n) => n.n);
+		const { default: eventPlugin } = await import("./eventPlugin-CmXaPWLv.mjs").then((n) => n.n);
 		const eventOpts = typeof config.arcPlugins?.events === "object" ? config.arcPlugins.events : {};
 		await fastify.register(eventPlugin, {
 			/**
@@ -906,19 +906,20 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 		trackPlugin("arc-health", { checkCount: healthOpts.checks?.length ?? 0 });
 	}
 	if (config.arcPlugins?.gracefulShutdown !== false) {
-		await fastify.register(gracefulShutdownPlugin);
-		trackPlugin("arc-graceful-shutdown");
+		const shutdownOpts = typeof config.arcPlugins?.gracefulShutdown === "object" ? config.arcPlugins.gracefulShutdown : {};
+		await fastify.register(gracefulShutdownPlugin, shutdownOpts);
+		trackPlugin("arc-graceful-shutdown", shutdownOpts);
 	}
 	if (config.arcPlugins?.caching) {
-		const { default: cachingPlugin } = await import("./caching-a3ZEcJJs.mjs").then((n) => n.r);
+		const { default: cachingPlugin } = await import("./caching-DsWDjIxx.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-oTsmVyEQ.mjs").then((n) => n.n);
+		const { queryCachePlugin } = await import("./queryCachePlugin-B5F09bYr.mjs").then((n) => n.n);
 		const opts = config.arcPlugins.queryCache === true ? {} : config.arcPlugins.queryCache;
-		const store = config.stores?.queryCache ?? new (await (import("./memory-BiPVaCPg.mjs").then((n) => n.n))).MemoryCacheStore();
+		const store = config.stores?.queryCache ?? new (await (import("./memory-CpDZ9NPw.mjs").then((n) => n.n))).MemoryCacheStore();
 		await fastify.register(queryCachePlugin, {
 			store,
 			...opts
@@ -928,7 +929,7 @@ 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-D4MYqkic.mjs").then((n) => n.r);
+			const { default: ssePlugin } = await import("./sse-CH7Slxc1.mjs").then((n) => n.r);
 			const opts = config.arcPlugins.sse === true ? {} : config.arcPlugins.sse;
 			await fastify.register(ssePlugin, opts);
 			trackPlugin("arc-sse", opts);
@@ -937,20 +938,20 @@ async function registerArcPlugins(fastify, config, trackPlugin, modules, moduleH
 	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-CPmjjgqd.mjs").then((n) => n.r);
+			const { default: realtimePlugin } = await import("./realtime-FnnD0n3Z.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-CsWaIVTa.mjs").then((n) => n.r);
+		const { default: metricsPlugin } = await import("./metrics-BaKnq8ag.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-C2r0eOZ4.mjs").then((n) => n.r);
+		const { default: versioningPlugin } = await import("./versioning-DuVWcu-F.mjs").then((n) => n.r);
 		await fastify.register(versioningPlugin, config.arcPlugins.versioning);
 		trackPlugin("arc-versioning", config.arcPlugins.versioning);
 	}
@@ -1027,7 +1028,7 @@ async function registerAuth(fastify, config, trackPlugin) {
 */
 async function registerElevation(fastify, config, trackPlugin) {
 	if (!config.elevation) return;
-	const { elevationPlugin } = await import("./elevation-C6woysGC.mjs").then((n) => n.r);
+	const { elevationPlugin } = await import("./elevation-BF-vhGxY.mjs").then((n) => n.r);
 	await fastify.register(elevationPlugin, config.elevation);
 	trackPlugin("arc-elevation", config.elevation);
 	fastify.log.debug("Elevation plugin enabled");
@@ -1042,7 +1043,7 @@ async function registerElevation(fastify, config, trackPlugin) {
 */
 async function registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers) {
 	if (config.errorHandler === false) return;
-	const { errorHandlerPlugin } = await import("./errorHandler-BdmIWPba.mjs").then((n) => n.r);
+	const { errorHandlerPlugin } = await import("./errorHandler-CIMkCOWm.mjs").then((n) => n.r);
 	/**
 	* DISCLOSURE DEFAULTS MERGE — they used to be REPLACED, and that was two bugs.
 	*
@@ -1266,7 +1267,7 @@ async function registerResources(fastify, config, preResolvedModules) {
 		let discoveryPath;
 		let discoveryYieldedZero = false;
 		if (resolvedResources === void 0 && config.resourceDir) {
-			const { loadResources } = await import("./loadResources-CNd1DWnK.mjs").then((n) => n.n);
+			const { loadResources } = await import("./loadResources-CblF7xt2.mjs").then((n) => n.n);
 			const { resolve, dirname } = await import("node:path");
 			const { fileURLToPath } = await import("node:url");
 			const rawDir = config.resourceDir;
@@ -1392,7 +1393,7 @@ Resources supplied by "${m.name}": ${provided}.`);
 			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-DthM8Qag.mjs").then((n) => n.r);
+			const { default: schedulesPlugin } = await import("./schedules-BktJb3Y3.mjs").then((n) => n.r);
 			await fastify.register(schedulesPlugin, {
 				...scheduleOptions,
 				schedules: frozenJobs
@@ -1566,6 +1567,7 @@ function buildPlanOpts(rest, plan) {
 */
 function buildRateLimitOpts(input) {
 	const { skipPaths, allowList, plan, ...bare } = input;
+	applyScopeAwareHook(bare);
 	const rest = plan ? buildPlanOpts(bare, plan) : bare;
 	if (!skipPaths || skipPaths.length === 0) return allowList === void 0 ? rest : {
 		...rest,
@@ -1584,6 +1586,27 @@ function buildRateLimitOpts(input) {
 		allowList: combined
 	};
 }
+/**
+* A scope-keyed generator must run AFTER authentication, so arc places the hook itself.
+*
+* `@fastify/rate-limit` defaults to `onRequest`; arc authenticates in a `preHandler`. A
+* generator from `createTenantKeyGenerator` therefore saw `PUBLIC_SCOPE` and returned the
+* caller's IP for EVERY request — and behind a proxy with `trustProxy` unset that is one
+* address, so a whole deployment shared a single bucket. Nothing threw: the limiter ran,
+* the host's key function ran, and the answer was silently wrong.
+*
+* Defaulted rather than merely warned, because the correct value is knowable here and the
+* failure is unobservable in production. An explicit `onRequest` is REFUSED rather than
+* honoured — it cannot do what the caller is asking for.
+*/
+function applyScopeAwareHook(bare) {
+	if (!isScopeAwareKeyGenerator(bare.keyGenerator)) return;
+	if (bare.hook === void 0) {
+		bare.hook = "preHandler";
+		return;
+	}
+	if (bare.hook === "onRequest") throw new Error("[arc] rateLimit.hook: 'onRequest' cannot be combined with a scope-aware keyGenerator (createTenantKeyGenerator). Authentication runs in a preHandler, so the generator would see PUBLIC_SCOPE and key every caller by IP — behind a proxy that is one bucket for the whole deployment. Use hook: 'preHandler' (arc's default for this generator), or supply a keyGenerator that derives identity without the scope.");
+}
 function compilePathMatcher(patterns) {
 	const prefixes = [];
 	const exact = /* @__PURE__ */ new Set();
@@ -1626,8 +1649,9 @@ async function registerSecurityPlugins(fastify, config) {
 			timeWindow: "1 minute"
 		});
 		await fastify.register(rateLimit, rateLimitOpts);
-		if (!(typeof rateLimitOpts === "object" && "store" in rateLimitOpts)) {
-			if (config.runtime === "distributed") throw new Error("[Arc] runtime: 'distributed' with rate limiting requires a shared store.\nProvide rateLimit: { store: new RedisStore({ ... }) } or disable rate limiting: rateLimit: false");
+		const rateLimitRecord = typeof rateLimitOpts === "object" && rateLimitOpts !== null ? rateLimitOpts : void 0;
+		if (!(rateLimitRecord !== void 0 && (rateLimitRecord.store != null || rateLimitRecord.redis != null))) {
+			if (config.runtime === "distributed") throw new Error("[Arc] runtime: 'distributed' with rate limiting requires a shared store.\nProvide rateLimit: { redis: ioredisClient } (or { store: CustomStore }) or disable rate limiting: rateLimit: false");
 			else if (config.preset === "production") fastify.log.warn("Rate limiting is using in-memory store. In multi-instance deployments, each instance tracks limits independently. Configure a Redis store for distributed rate limiting.");
 		}
 		fastify.log.debug("Rate limiting enabled");
@@ -1738,6 +1762,17 @@ var createApp_exports = /* @__PURE__ */ __exportAll({
 	createApp: () => createApp,
 	resolveLoggerConfig: () => resolveLoggerConfig
 });
+/**
+* The fail-loud switches, and what each one costs while OFF.
+*
+* Every one is a SPECIFIC instruction defeated by a GENERAL default, which is
+* why they are reported together rather than one at a time.
+*/
+const STRICT_ENV_FLAGS = [
+	["ARC_STRICT_PERMISSIONS", "An ungated write route warns instead of failing boot."],
+	["ARC_STRICT_QUERY_PARAMS", "An unknown filter key is DROPPED, which WIDENS the read."],
+	["ARC_STRICT_IMMUTABLE_WRITES", "A PATCH of an immutable field returns 200, unchanged."]
+];
 const MEMORY_STORE_NAMES = /* @__PURE__ */ new Set(["memory", "memory-cache"]);
 /**
 * Default redact paths layered into Fastify's pino logger when the host
@@ -1757,6 +1792,7 @@ const DEFAULT_LOGGER_REDACT_PATHS = [
 	"req.headers.authorization",
 	"req.headers[\"x-api-key\"]",
 	"req.headers[\"x-internal-api-key\"]",
+	"req.headers[\"x-device-token\"]",
 	"req.headers.cookie",
 	"req.headers[\"set-cookie\"]",
 	"res.headers[\"set-cookie\"]",
@@ -1828,7 +1864,10 @@ function validateDistributedRuntime(options) {
 		});
 	}
 	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 (schedules && typeof schedules === "object" && schedules.enabled !== false && !schedules.lock && !schedules.singleReplica) missing.push({
+		key: "arcPlugins.schedules.lock",
+		hint: "a LockAdapter for single-firer leases (e.g. createMongoLockAdapter) — or `arcPlugins.schedules.singleReplica: true` if exactly one replica arms schedules"
+	});
 	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.
@@ -1953,6 +1992,7 @@ async function buildApp(options, loggerScope, onInstance) {
 		} }
 	});
 	onInstance(fastify);
+	initRuntimeCapabilityRegistry(fastify);
 	if (resolvedLogger !== false) {
 		const writer = createPinoWriter(fastify.log);
 		loggerScope.writer = writer;
@@ -1967,6 +2007,22 @@ async function buildApp(options, loggerScope, onInstance) {
 	for (const warning of deferredWarnings) fastify.log.warn(warning);
 	if (numericTrustProxy) fastify.log.warn(`[arc] trustProxy: ${String(config.trustProxy)} (a hop COUNT) trusts nothing on Fastify >= 5.12.1 — hop-count trust cannot validate the immediate peer, so it fails closed upstream to stop clients spoofing X-Forwarded-* with padded hops. \`request.ip\` is therefore the PROXY's address: rate-limit keys collapse onto one bucket and audit rows record the wrong client. Name the proxies instead — trustProxy: 'loopback', '10.0.0.0/8', a comma-separated list, or \`true\` if every upstream hop is genuinely trusted.`);
 	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.");
+	/**
+	* `preset: 'production'` REPORTS the fail-loud switches it cannot set.
+	*
+	* All three are read where the object is CONSTRUCTED — `defineResource` at
+	* define time, `QueryParser` and `BodySanitizer` in their constructors — and a
+	* host imports its resources before it calls `createApp`. So setting
+	* `process.env` here would be too late for everything already built: wired to
+	* read, doing nothing. Reporting cannot fail that way.
+	*
+	* Set them in the process entrypoint, BEFORE the first resource import, with
+	* `??=` so an operator's explicit `false` still wins.
+	*/
+	if (config.preset === "production") {
+		const off = STRICT_ENV_FLAGS.filter(([name]) => process.env[name] !== "true");
+		if (off.length > 0) fastify.log.warn(`[arc] preset: 'production' with fail-loud OFF: ${off.map(([n]) => n).join(", ")}. ${off.map(([, what]) => what).join(" ")} Set them in the entrypoint BEFORE any resource import — they are read when resources, parsers and sanitizers are CONSTRUCTED, so setting them later is silently too late. Per-resource options still override.`);
+	}
 	fastify.removeContentTypeParser("application/json");
 	fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
 		try {
@@ -1999,7 +2055,7 @@ async function buildApp(options, loggerScope, onInstance) {
 	await registerErrorHandler(fastify, config, trackPlugin, moduleErrorMappers);
 	await registerResources(fastify, config, resolvedModules);
 	if (config.replyHelpers) {
-		const { replyHelpersPlugin } = await import("./replyHelpers-BHebarf0.mjs").then((n) => n.n);
+		const { replyHelpersPlugin } = await import("./replyHelpers-DPHsdw-5.mjs").then((n) => n.n);
 		await fastify.register(replyHelpersPlugin);
 	}
 	if (config.serializeBigInt) {

package/dist/{preloadResources-BbBkNkqK.d.mts → preloadResources-CjS2OfpU.d.mts}

@@ -1,15 +1,15 @@
 
-import { It as Authenticator } from "./index-B78WZom8.mjs";
+import { It as Authenticator } from "./index-DHbyPo5j.mjs";
 import { r as CacheStore } from "./interface-BOk3YnTz.mjs";
 import { n as ElevationOptions } from "./elevation-BXCfVcNG.mjs";
-import { a as EventTransport } from "./EventTransport-Cx60_s-6.mjs";
+import { a as EventTransport } from "./EventTransport-CbUKDzZZ.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-BzqxconG.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-DI5AN2b5.mjs";
-import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-BRU-Kd3t.mjs";
-import "./index-D2uIUSQk.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DFvHa4Nf.mjs";
-import { g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-B843jOYX.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler--4rSMMvq.mjs";
+import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-DfVDvkdP.mjs";
+import "./index-CFfLKMH4.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-B52abJ8W.mjs";
+import { b as GracefulShutdownOptions, g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-D6JIK8Tk.mjs";
 import { r as IdempotencyStore } from "./interface-DEWNOMza.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 //#region src/factory/types/assets.d.ts
@@ -652,8 +652,13 @@ interface CreateAppOptions {
      * ```
      */
     health?: boolean | HealthOptions;
-    /** Graceful shutdown handling (default: true) */
-    gracefulShutdown?: boolean;
+    /**
+     * Graceful shutdown handling (default: true). Pass `GracefulShutdownOptions`
+     * to configure it inline — in particular `drainDelayMs`, the lame-duck
+     * window behind a load balancer (readiness fails first, the server keeps
+     * serving until the LB has deregistered the instance, then closes).
+     */
+    gracefulShutdown?: boolean | GracefulShutdownOptions;
     /** Emit events for CRUD operations (default: true) */
     emitEvents?: boolean;
     /**

package/dist/presets/filesUpload.d.mts

@@ -1,7 +1,7 @@
 
 import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
-import { l as PermissionCheck } from "../base-C-NL2fTi.mjs";
-import { Y as PresetResult } from "../index-B78WZom8.mjs";
+import { l as PermissionCheck } from "../base-CxrV1LmG.mjs";
+import { Y as PresetResult } from "../index-DHbyPo5j.mjs";
 import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Cx9Sz3Ou.mjs";
 //#region src/presets/filesUpload.d.ts
 interface FilesUploadPresetRoutes {

package/dist/presets/filesUpload.mjs

@@ -1,8 +1,8 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { i as NotFoundError, u as ValidationError } from "../errors-2ExmOgIJ.mjs";
-import { c as getOrgId, g as getUserId } from "../types-BqLyyH0o.mjs";
-import { B as requireAuth, F as allowPublic } from "../permissions-H7Zcb82Z.mjs";
-import { t as multipartBody } from "../multipartBody-u6VrS_iH.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { i as NotFoundError, u as ValidationError } from "../errors-C_YhELhe.mjs";
+import { c as getOrgId, g as getUserId } from "../types-CDy3-zw1.mjs";
+import { B as requireAuth, F as allowPublic } from "../permissions-DiHXy8Ck.mjs";
+import { t as multipartBody } from "../multipartBody-C92aJ8am.mjs";
 //#region src/presets/filesUpload.ts
 const DEFAULT_FIELD_NAME = "file";
 const DEFAULT_MAX_FILE_SIZE = 10485760;

package/dist/presets/index.d.mts

@@ -1,6 +1,6 @@
 
-import { t as AnyRecord } from "../base-C-NL2fTi.mjs";
-import { Fn as IControllerResponse, In as IRequestContext, U as ResourceConfig, Y as PresetResult, d as PaginationResult } from "../index-B78WZom8.mjs";
+import { t as AnyRecord } from "../base-CxrV1LmG.mjs";
+import { Fn as IControllerResponse, In as IRequestContext, U as ResourceConfig, Y as PresetResult, d as PaginationResult } from "../index-DHbyPo5j.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,6 +1,6 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
 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-CNyfaxGL.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-BdlugYTc.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,5 +1,5 @@
 
-import { X as CrudRouteKey, Y as PresetResult } from "../index-B78WZom8.mjs";
+import { X as CrudRouteKey, Y as PresetResult } from "../index-DHbyPo5j.mjs";
 //#region src/presets/multiTenant.d.ts
 /**
  * One tenant dimension for multi-field filtering. Discriminated by source:
@@ -65,6 +65,43 @@ interface MultiTenantOptions {
    * multiTenantPreset({ allowPublic: ['list', 'get'] })
    */
   allowPublic?: CrudRouteKey[];
+  /**
+   * Reads that are NOT scoped to a tenant at all — a marketplace listing.
+   *
+   * `allowPublic` answers "may an anonymous caller reach this route?". That is a different
+   * question from "is this listing scoped to a tenant?", and until this option there was no way
+   * to answer the second one with "no". An `allowPublic` route still filters by the caller's
+   * organization whenever they have one, and a signed-in user of a multi-org product ALWAYS has
+   * one, because choosing an organization writes it onto the session. So a cross-tenant catalog
+   * silently became single-tenant the moment one of its own sellers browsed it: the same URL,
+   * with no header and no query parameter to explain the difference, returned a different world
+   * depending on who was asking.
+   *
+   * The only escape was to drop this preset from the resource entirely, which also drops tenant
+   * INJECTION on create/update — the thing that stops a member moving a document into another
+   * organization. Trading a write guarantee for a read behaviour is not a real choice.
+   *
+   * Listed routes get no tenant middleware: no filter, and nothing stashed for the repo layer.
+   * Everything else keeps its filter, so writes are unaffected.
+   *
+   * READS ONLY, by type. A cross-tenant `create` or `update` is not a listing, it is an escape
+   * from tenancy, and it should never be one option away by accident.
+   *
+   * THIS DOES NOT AUTHORIZE ANYTHING. Removing the tenant filter widens what the query can
+   * return, so the resource owes a row-level `policy` from its permission check saying what a
+   * stranger may see (`{ status: 'active' }`, `{ visibility: 'public' }`). Declaring this without
+   * one publishes every row in every tenant.
+   *
+   * @default []
+   * @example
+   * // A public catalog: anyone may browse every seller's LIVE products,
+   * // while create/update/delete stay pinned to the caller's own shop.
+   * multiTenantPreset({
+   *   allowPublic: ['list', 'get'],
+   *   crossTenant: ['list', 'get'],
+   * })
+   */
+  crossTenant?: readonly Extract<CrudRouteKey, "list" | "get">[];
 }
 declare function multiTenantPreset(options?: MultiTenantOptions): PresetResult;
 //#endregion

package/dist/presets/multiTenant.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import "../constants-BONghE1Y.mjs";
-import { b as isElevated, c as getOrgId, d as getScopeContext, m as getTeamId, u as getRequestScope, v as hasOrgAccess } from "../types-BqLyyH0o.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import "../constants-BxLgNFF7.mjs";
+import { b as isElevated, c as getOrgId, d as getScopeContext, m as getTeamId, u as getRequestScope, v as hasOrgAccess } from "../types-CDy3-zw1.mjs";
 //#region src/presets/multiTenant.ts
 /**
 * Resolve a single TenantFieldSpec against the current scope.
@@ -162,7 +162,7 @@ function createTenantInjection(specs) {
 	};
 }
 function multiTenantPreset(options = {}) {
-	const { tenantField, tenantFields, allowPublic = [] } = options;
+	const { tenantField, tenantFields, allowPublic = [], crossTenant = [] } = options;
 	if (tenantField !== void 0 && tenantFields !== void 0) throw new Error("multiTenantPreset: pass either `tenantField` (single-field) or `tenantFields` (multi-field), not both");
 	const specs = tenantFields ?? [{
 		field: tenantField ?? "organizationId",
@@ -173,6 +173,24 @@ function multiTenantPreset(options = {}) {
 	const flexibleTenantFilter = createFlexibleTenantFilter(specs);
 	const tenantInjection = createTenantInjection(specs);
 	const getFilter = (route) => allowPublic.includes(route) ? flexibleTenantFilter : strictTenantFilter;
+	/**
+	* A cross-tenant read MARKS the request rather than simply skipping the filter.
+	*
+	* Skipping is not enough, because this middleware is only the first of four places that scope a
+	* read, and the other three each re-derive the organization from the request scope on their own:
+	* `QueryResolver` adds the tenant filter for `list`, `buildTenantRepoOptions` forwards it to the
+	* repository as tenant context, and `checkOrgScope` re-checks it post-fetch on `get`. Removing
+	* one of four changes nothing observable, which is exactly what made this look unfixable from the
+	* preset: the listing stayed single-tenant no matter what the preset decided.
+	*
+	* So the decision travels on the request instead, and each of those layers honours it. The
+	* repository layer needs no change of its own — kits already accept `bypassTenant`, which is the
+	* same door elevated cross-tenant reads have always used.
+	*/
+	const markCrossTenantRead = async (request) => {
+		request._crossTenantRead = true;
+	};
+	const readMiddleware = (route) => crossTenant.includes(route) ? [markCrossTenantRead] : [getFilter(route)];
 	const fieldRules = {};
 	for (const spec of specs) fieldRules[spec.field] = {
 		systemManaged: true,
@@ -182,8 +200,8 @@ function multiTenantPreset(options = {}) {
 		name: "multiTenant",
 		schemaOptions: { fieldRules },
 		middlewares: {
-			list: [getFilter("list")],
-			get: [getFilter("get")],
+			list: readMiddleware("list"),
+			get: readMiddleware("get"),
 			create: [tenantInjection],
 			update: [getFilter("update"), tenantInjection],
 			delete: [getFilter("delete")],

package/dist/presets/search.d.mts

@@ -1,6 +1,6 @@
 
-import { l as PermissionCheck } from "../base-C-NL2fTi.mjs";
-import { At as RouteDefinition, Y as PresetResult, jn as ControllerHandler, jt as RouteMcpConfig } from "../index-B78WZom8.mjs";
+import { l as PermissionCheck } from "../base-CxrV1LmG.mjs";
+import { At as RouteDefinition, Y as PresetResult, jn as ControllerHandler, jt as RouteMcpConfig } from "../index-DHbyPo5j.mjs";
 //#region src/presets/search.d.ts
 /**
  * Search Preset — backend-agnostic search / vector / embed routes

package/dist/presets/search.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { B as requireAuth, F as allowPublic } from "../permissions-H7Zcb82Z.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { B as requireAuth, F as allowPublic } from "../permissions-DiHXy8Ck.mjs";
 //#region src/presets/search.ts
 const BUILTINS = [
 	{

package/dist/{presets-CNyfaxGL.mjs → presets-BdlugYTc.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.38.0 | MIT | https://classytic.com */
-import { l as UnauthorizedError } from "./errors-2ExmOgIJ.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE } from "./types-BqLyyH0o.mjs";
-import { B as requireAuth, F as allowPublic, U as requireRoles } from "./permissions-H7Zcb82Z.mjs";
+/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
+import { l as UnauthorizedError } from "./errors-C_YhELhe.mjs";
+import { b as isElevated, n as PUBLIC_SCOPE } from "./types-CDy3-zw1.mjs";
+import { B as requireAuth, F as allowPublic, U as requireRoles } from "./permissions-DiHXy8Ck.mjs";
 import { multiTenantPreset } from "./presets/multiTenant.mjs";
 //#region src/presets/ownedByUser.ts
 /**