@classytic/arc 2.20.0 → 2.22.0

package/dist/plugins/index.d.mts

@@ -1,11 +1,10 @@
-import { Q as MiddlewareConfig, ft as RouteDefinition, ht as RouteSchemaOptions, nt as PresetHook, qt as AnyRecord } from "../index-_--GyzcO.mjs";
-import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-CCQJEDgh.mjs";
-import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$7, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$6, v as _default$3, y as healthPlugin } from "../versioning-D_eBCfNr.mjs";
-import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-BtUUDPEa.mjs";
-import { t as TracingOptions } from "../tracing-D8jlGXP7.mjs";
+import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-C6yv4ZTW.mjs";
+import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-9_fuetB4.mjs";
+import { _ as HealthOptions, a as MetricsCollector, c as metricsPlugin, d as ssePlugin, f as CachingOptions, g as HealthCheck, h as cachingPlugin, i as MetricEntry, l as SSEOptions, m as _default$1, n as _default$8, o as MetricsOptions, p as CachingRule, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as _default$7, v as _default$3, y as healthPlugin } from "../versioning-DLwklPlG.mjs";
+import { t as TracingOptions } from "../tracing-CsGKQJGg.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
-
 //#region src/plugins/createPlugin.d.ts
 interface PluginResourceResult {
   /** Additional routes to add to the resource (v2.8 `RouteDefinition` shape) */
@@ -146,7 +145,97 @@ declare module "fastify" {
     };
   }
 }
+/**
+ * Sanitize an incoming request-id header value: max 128 chars, alphanumeric
+ * plus dashes/underscores/dots/colons only. Returns `undefined` for anything
+ * else (crafted values could pollute logs or response headers). Array values
+ * (repeated headers) are rejected outright — a client sending multiple
+ * request-id headers is not tracing in good faith.
+ */
+declare function sanitizeRequestId(value: unknown): string | undefined;
+/**
+ * Build a Fastify `genReqId` function: adopt a sanitized incoming request-id
+ * header, or generate one. Wire this into the `Fastify()` constructor so
+ * `request.id`, `request.log`'s `reqId` binding, and the echoed response
+ * header all agree — `createApp` does this automatically.
+ */
+declare function createRequestIdGenerator(opts?: Pick<RequestIdOptions, "header" | "generator">): (req: {
+  headers: Record<string, string | string[] | undefined>;
+}) => string;
 declare const requestIdPlugin: FastifyPluginAsync<RequestIdOptions>;
 declare const _default$5: FastifyPluginAsync<RequestIdOptions>;
 //#endregion
-export { type ArcCore, type ArcCorePluginOptions, type ArcPlugin, type CachingOptions, type CachingRule, type CreatePluginDefinition, type ErrorHandlerOptions, type ErrorMapper, type GracefulShutdownOptions, type HealthCheck, type HealthOptions, type MetricEntry, type MetricsCollector, type MetricsOptions, type PluginMeta, type PluginResourceResult, type RequestIdOptions, type SSEOptions, type TracingOptions, type VersioningOptions, _default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, _default$1 as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, _default$2 as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, _default$3 as healthPlugin, healthPlugin as healthPluginFn, _default$4 as metricsPlugin, metricsPlugin as metricsPluginFn, replyHelpersPlugin, _default$5 as requestIdPlugin, requestIdPlugin as requestIdPluginFn, _default$6 as ssePlugin, ssePlugin as ssePluginFn, _default$7 as versioningPlugin, versioningPlugin as versioningPluginFn };
+//#region src/plugins/schedules.d.ts
+/**
+ * Structural view of the ecosystem lock contract — matches
+ * `LockAdapter` from `@classytic/repo-core/lock` (and every kit
+ * implementation) WITHOUT importing the subpath, so arc's emitted
+ * declarations carry no repo-core@>=0.8 subpath reference and the
+ * peer floor stays honest. Any conforming adapter assigns.
+ */
+interface ScheduleLockLike {
+  tryAcquire(name: string, holderId: string, leaseMs: number): Promise<boolean> | boolean;
+  release(name: string, holderId: string): Promise<boolean> | boolean;
+}
+interface ScheduleDefinition {
+  /** Unique name — also the lock key (`arc:schedule:<name>`). */
+  name: string;
+  /** Interval in milliseconds between the END of one run and the next tick. */
+  every: number;
+  /** The work. Receives the Fastify instance; errors are logged, never fatal. */
+  handler: (fastify: FastifyInstance) => void | Promise<void>;
+  /** Fire once immediately when the app becomes ready (default: false). */
+  runOnStart?: boolean;
+  /**
+   * Random extra delay in `[0, jitterMs)` added to the FIRST tick only.
+   * Spreads boot-aligned jobs so multiple same-cadence schedules don't all
+   * fire at exactly `boot + every` after every restart (and, with a lock,
+   * de-synchronizes replicas competing for the same lease). Ignored when
+   * `runOnStart` is true.
+   */
+  jitterMs?: number;
+  /**
+   * Lease duration when a `lock` is configured. Default: `every * 0.9`
+   * (capped at 5 minutes) — long enough that other replicas skip the same
+   * tick, short enough that a crashed leader fails over within one cycle.
+   */
+  leaseMs?: number;
+  /** Per-schedule kill switch (default: true). */
+  enabled?: boolean;
+}
+interface SchedulesPluginOptions {
+  schedules: ScheduleDefinition[];
+  /**
+   * Ecosystem lock adapter for multi-replica deployments. Omit for
+   * single-instance apps — every tick runs locally.
+   */
+  lock?: ScheduleLockLike;
+  /**
+   * Identity of this replica for lease ownership. Default: a random id per
+   * process (repo-core's `getInstanceId()` is a good explicit value).
+   */
+  holderId?: string;
+  /**
+   * Master switch — `false` registers a typed no-op (config-gated
+   * environments), same pattern as `idempotencyPlugin`.
+   */
+  enabled?: boolean;
+}
+/** Per-schedule runtime counters, readable via `fastify.getScheduleStats()`. */
+interface ScheduleStats {
+  name: string;
+  runs: number;
+  failures: number;
+  skippedByLock: number;
+  lastRunAt: string | null;
+  lastError: string | null;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    getScheduleStats?: () => ScheduleStats[];
+  }
+}
+declare const schedulesPlugin: FastifyPluginAsync<SchedulesPluginOptions>;
+declare const _default$6: FastifyPluginAsync<SchedulesPluginOptions>;
+//#endregion
+export { type ArcCore, type ArcCorePluginOptions, type ArcPlugin, type CachingOptions, type CachingRule, type CreatePluginDefinition, type ErrorHandlerOptions, type ErrorMapper, type GracefulShutdownOptions, type HealthCheck, type HealthOptions, type MetricEntry, type MetricsCollector, type MetricsOptions, type PluginMeta, type PluginResourceResult, type RequestIdOptions, type SSEOptions, type ScheduleDefinition, type ScheduleLockLike, type ScheduleStats, type SchedulesPluginOptions, type TracingOptions, type VersioningOptions, _default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, _default$1 as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, _default$2 as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, _default$3 as healthPlugin, healthPlugin as healthPluginFn, _default$4 as metricsPlugin, metricsPlugin as metricsPluginFn, replyHelpersPlugin, _default$5 as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, _default$6 as schedulesPlugin, schedulesPlugin as schedulesPluginFn, _default$7 as ssePlugin, ssePlugin as ssePluginFn, _default$8 as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/index.mjs

@@ -4,13 +4,14 @@ import { n as requestContext } from "../requestContext-BZKOr13H.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
 import { t as HookSystem } from "../HookSystem-C1vB_Gc9.mjs";
 import { t as ResourceRegistry } from "../ResourceRegistry-7RnrEWNP.mjs";
+import { i as sanitizeRequestId, n as requestIdPlugin, r as requestId_default, t as createRequestIdGenerator } from "../requestId-5BhTVzBv.mjs";
+import { n as health_default, t as healthPlugin } from "../health-ScyjIVo5.mjs";
 import { n as caching_default, t as cachingPlugin } from "../caching-_NJeDd1_.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-Dxf6P_kV.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-BTzXSwIg.mjs";
 import { n as metrics_default, t as metricsPlugin } from "../metrics-fdxI5mn_.mjs";
 import { t as replyHelpersPlugin } from "../replyHelpers-67tRawQZ.mjs";
 import { n as sse_default, t as ssePlugin } from "../sse-CfUjwjDk.mjs";
 import { n as versioning_default, t as versioningPlugin } from "../versioning-Dk-71iIz.mjs";
-import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/core/arcCorePlugin.ts
 const arcCorePlugin = async (fastify, opts = {}) => {
@@ -24,6 +25,13 @@ const arcCorePlugin = async (fastify, opts = {}) => {
 		externalOpenApiPaths: [],
 		plugins: /* @__PURE__ */ new Map()
 	});
+	for (const field of [
+		"_policyFilters",
+		"_ownershipCheck",
+		"fieldMask",
+		"policyMetadata",
+		"document"
+	]) if (!fastify.hasRequestDecorator(field)) fastify.decorateRequest(field, void 0);
 	fastify.addHook("onRequest", (request, _reply, done) => {
 		const store = {
 			requestId: request.id,
@@ -192,281 +200,91 @@ var gracefulShutdown_default = fp(gracefulShutdownPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-//#region src/plugins/health.ts
-function createHttpMetrics() {
-	return {
-		requestsTotal: {},
-		requestDurations: [],
-		_ringIndex: 0,
-		startTime: Date.now()
-	};
-}
-const healthPlugin = async (fastify, opts = {}) => {
-	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
-	const httpMetrics = createHttpMetrics();
-	fastify.get(prefix, { schema: {
-		tags: ["Health"],
-		summary: "Liveness probe (alias for /live)",
-		description: "Returns 200 if the process is alive",
-		response: { 200: {
-			type: "object",
-			properties: {
-				status: {
-					type: "string",
-					enum: ["ok"]
-				},
-				timestamp: { type: "string" },
-				version: { type: "string" }
-			}
-		} }
-	} }, async () => ({
-		status: "ok",
-		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-		...version ? { version } : {}
-	}));
-	fastify.get(`${prefix}/live`, { schema: {
-		tags: ["Health"],
-		summary: "Liveness probe",
-		description: "Returns 200 if the process is alive",
-		response: { 200: {
-			type: "object",
-			properties: {
-				status: {
-					type: "string",
-					enum: ["ok"]
-				},
-				timestamp: { type: "string" },
-				version: { type: "string" }
-			}
-		} }
-	} }, async () => {
-		return {
-			status: "ok",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			...version ? { version } : {}
-		};
-	});
-	fastify.get(`${prefix}/ready`, { schema: {
-		tags: ["Health"],
-		summary: "Readiness probe",
-		description: "Returns 200 if all dependencies are healthy",
-		response: {
-			200: {
-				type: "object",
-				properties: {
-					status: {
-						type: "string",
-						enum: ["ready", "not_ready"]
-					},
-					timestamp: { type: "string" },
-					checks: {
-						type: "array",
-						items: {
-							type: "object",
-							properties: {
-								name: { type: "string" },
-								healthy: { type: "boolean" },
-								duration: { type: "number" },
-								error: { type: "string" }
-							}
-						}
-					}
-				}
-			},
-			503: {
-				type: "object",
-				properties: {
-					status: {
-						type: "string",
-						enum: ["not_ready"]
-					},
-					timestamp: { type: "string" },
-					checks: { type: "array" }
+//#region src/plugins/schedules.ts
+const MIN_SAFE_INTERVAL_MS = 1e3;
+const MAX_DEFAULT_LEASE_MS = 3e5;
+const schedulesPlugin = async (fastify, opts) => {
+	const { schedules, lock, enabled = true } = opts;
+	const holderId = opts.holderId ?? `arc-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+	const stats = /* @__PURE__ */ new Map();
+	fastify.decorate("getScheduleStats", () => [...stats.values()].map((s) => ({ ...s })));
+	if (!enabled) {
+		fastify.log.debug("schedulesPlugin disabled — registered as no-op");
+		return;
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const s of schedules) {
+		if (!s.name) throw new TypeError("[arc-schedules] every schedule needs a name");
+		if (seen.has(s.name)) throw new TypeError(`[arc-schedules] duplicate schedule name "${s.name}"`);
+		seen.add(s.name);
+		if (!Number.isFinite(s.every) || s.every <= 0) throw new TypeError(`[arc-schedules] "${s.name}": \`every\` must be a positive number of ms`);
+		if (s.every < MIN_SAFE_INTERVAL_MS) fastify.log.warn(`[arc-schedules] "${s.name}" runs every ${s.every}ms — sub-second schedules are almost always a bug in production (DB pressure, lock churn). Intended for tests only.`);
+	}
+	const timers = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	let closing = false;
+	async function tick(s) {
+		const stat = stats.get(s.name);
+		if (!stat) return;
+		try {
+			if (lock) {
+				const leaseMs = s.leaseMs ?? Math.min(Math.floor(s.every * .9), MAX_DEFAULT_LEASE_MS);
+				if (!await lock.tryAcquire(`arc:schedule:${s.name}`, holderId, leaseMs)) {
+					stat.skippedByLock++;
+					return;
 				}
 			}
+			stat.runs++;
+			stat.lastRunAt = (/* @__PURE__ */ new Date()).toISOString();
+			await s.handler(fastify);
+			stat.lastError = null;
+		} catch (err) {
+			stat.failures++;
+			stat.lastError = err instanceof Error ? err.message : String(err);
+			fastify.log.error({
+				err,
+				schedule: s.name
+			}, "[arc-schedules] schedule run failed");
 		}
-	} }, async (_, reply) => {
-		const results = await runChecks(checks);
-		const criticalFailed = results.some((r) => !r.healthy && (checks.find((c) => c.name === r.name)?.critical ?? true));
-		const response = {
-			status: criticalFailed ? "not_ready" : "ready",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			checks: results
-		};
-		if (criticalFailed) reply.code(503);
-		return response;
-	});
-	if (metrics) fastify.get(`${prefix}/metrics`, async (_, reply) => {
-		reply.type("text/plain; charset=utf-8");
-		if (metricsCollector) return await metricsCollector();
-		const uptime = process.uptime();
-		const memory = process.memoryUsage();
-		const cpu = process.cpuUsage();
-		const lines = [
-			"# HELP process_uptime_seconds Process uptime in seconds",
-			"# TYPE process_uptime_seconds gauge",
-			`process_uptime_seconds ${uptime.toFixed(2)}`,
-			"",
-			"# HELP process_memory_heap_bytes Heap memory usage in bytes",
-			"# TYPE process_memory_heap_bytes gauge",
-			`process_memory_heap_bytes{type="used"} ${memory.heapUsed}`,
-			`process_memory_heap_bytes{type="total"} ${memory.heapTotal}`,
-			"",
-			"# HELP process_memory_rss_bytes RSS memory in bytes",
-			"# TYPE process_memory_rss_bytes gauge",
-			`process_memory_rss_bytes ${memory.rss}`,
-			"",
-			"# HELP process_memory_external_bytes External memory in bytes",
-			"# TYPE process_memory_external_bytes gauge",
-			`process_memory_external_bytes ${memory.external}`,
-			"",
-			"# HELP process_cpu_user_microseconds User CPU time in microseconds",
-			"# TYPE process_cpu_user_microseconds counter",
-			`process_cpu_user_microseconds ${cpu.user}`,
-			"",
-			"# HELP process_cpu_system_microseconds System CPU time in microseconds",
-			"# TYPE process_cpu_system_microseconds counter",
-			`process_cpu_system_microseconds ${cpu.system}`,
-			""
-		];
-		if (collectHttpMetrics && Object.keys(httpMetrics.requestsTotal).length > 0) {
-			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
-			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
-			lines.push("");
-			if (httpMetrics.requestDurations.length > 0) {
-				const sorted = [...httpMetrics.requestDurations].sort((a, b) => a - b);
-				const p50 = sorted[Math.floor(sorted.length * .5)] || 0;
-				const p95 = sorted[Math.floor(sorted.length * .95)] || 0;
-				const p99 = sorted[Math.floor(sorted.length * .99)] || 0;
-				const sum = sorted.reduce((a, b) => a + b, 0);
-				lines.push("# HELP http_request_duration_milliseconds HTTP request duration", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${sum.toFixed(2)}`, `http_request_duration_milliseconds_count ${sorted.length}`, "");
-			}
-		}
-		return lines.join("\n");
-	});
-	if (collectHttpMetrics) {
-		fastify.addHook("onRequest", async (request) => {
-			request._startTime = Date.now();
-		});
-		fastify.addHook("onResponse", async (request, reply) => {
-			const duration = Date.now() - (request._startTime ?? Date.now());
-			const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
-			httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
-			if (httpMetrics.requestDurations.length < 1e4) httpMetrics.requestDurations.push(duration);
-			else httpMetrics.requestDurations[httpMetrics._ringIndex % 1e4] = duration;
-			httpMetrics._ringIndex = httpMetrics._ringIndex + 1;
-		});
 	}
-	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
-};
-/**
-* Run all health checks with timeout
-*/
-async function runChecks(checks) {
-	const results = [];
-	for (const check of checks) {
-		const start = Date.now();
-		const timeout = check.timeout ?? 5e3;
-		let timer;
-		try {
-			const checkPromise = Promise.resolve(check.check());
-			const timeoutPromise = new Promise((_, reject) => {
-				timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Health check timeout")), timeout);
-			});
-			const healthy = await Promise.race([checkPromise, timeoutPromise]);
-			results.push({
-				name: check.name,
-				healthy: Boolean(healthy),
-				duration: Date.now() - start
-			});
-		} catch (err) {
-			results.push({
-				name: check.name,
-				healthy: false,
-				duration: Date.now() - start,
-				error: err.message
+	function scheduleNext(s, delay) {
+		if (closing) return;
+		const timer = setTimeout(() => {
+			const run = tick(s).finally(() => {
+				inFlight.delete(s.name);
+				scheduleNext(s, s.every);
 			});
-		} finally {
-			if (timer) clearTimeout(timer);
-		}
+			inFlight.set(s.name, run);
+		}, delay);
+		timer.unref?.();
+		timers.set(s.name, timer);
 	}
-	return results;
-}
-var health_default = fp(healthPlugin, {
-	name: "arc-health",
-	fastify: "5.x"
-});
-//#endregion
-//#region src/plugins/requestId.ts
-/**
-* Request ID Plugin
-*
-* Propagates request IDs for distributed tracing.
-* - Accepts incoming x-request-id header
-* - Generates UUID if not provided
-* - Attaches to request.id and response header
-*
-* @example
-* import { requestIdPlugin } from '@classytic/arc';
-*
-* await fastify.register(requestIdPlugin);
-*
-* // In handlers, access via request.id
-* fastify.get('/', async (request) => {
-*   console.log(request.id); // UUID
-* });
-*/
-/** W3C traceparent format: `version-traceid-parentid-flags` */
-const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
-/** W3C spec: version ff is reserved and invalid; trace/parent IDs must not be all zeros */
-const TRACEID_ZEROS = "0".repeat(32);
-const PARENTID_ZEROS = "0".repeat(16);
-/** tracestate: printable ASCII, <= 512 bytes */
-const TRACESTATE_MAX = 512;
-function isValidTraceparent(tp) {
-	const m = TRACEPARENT_RE.exec(tp);
-	if (!m) return false;
-	const version = m[1] ?? "";
-	const traceId = m[2] ?? "";
-	const parentId = m[3] ?? "";
-	if (version.toLowerCase() === "ff") return false;
-	if (traceId.toLowerCase() === TRACEID_ZEROS) return false;
-	if (parentId.toLowerCase() === PARENTID_ZEROS) return false;
-	return true;
-}
-const requestIdPlugin = async (fastify, opts = {}) => {
-	const { header = "x-request-id", generator = randomUUID, setResponseHeader = true, propagateTraceContext = true } = opts;
-	if (!fastify.hasRequestDecorator("requestId")) fastify.decorateRequest("requestId", "");
-	if (!fastify.hasRequestDecorator("traceContext")) fastify.decorateRequest("traceContext", void 0);
-	fastify.addHook("onRequest", async (request, reply) => {
-		const incomingId = request.headers[header];
-		const sanitized = typeof incomingId === "string" ? incomingId.trim() : "";
-		const requestId = sanitized.length > 0 && sanitized.length <= 128 && /^[\w.:-]+$/.test(sanitized) ? sanitized : generator();
-		request.id = requestId;
-		request.requestId = requestId;
-		if (setResponseHeader) reply.header(header, requestId);
-		if (propagateTraceContext) {
-			const rawTraceparent = request.headers["traceparent"];
-			const rawTracestate = request.headers["tracestate"];
-			if (typeof rawTraceparent === "string") {
-				const tp = rawTraceparent.trim();
-				if (isValidTraceparent(tp)) {
-					const ts = typeof rawTracestate === "string" && rawTracestate.length > 0 && rawTracestate.length <= TRACESTATE_MAX ? rawTracestate : void 0;
-					request.traceContext = {
-						traceparent: tp,
-						...ts ? { tracestate: ts } : {}
-					};
-					reply.header("traceparent", tp);
-					if (ts) reply.header("tracestate", ts);
-				}
-			}
+	fastify.addHook("onReady", async () => {
+		for (const s of schedules) {
+			if (s.enabled === false) continue;
+			stats.set(s.name, {
+				name: s.name,
+				runs: 0,
+				failures: 0,
+				skippedByLock: 0,
+				lastRunAt: null,
+				lastError: null
+			});
+			const jitter = !s.runOnStart && s.jitterMs ? Math.floor(Math.random() * s.jitterMs) : 0;
+			scheduleNext(s, s.runOnStart ? 0 : s.every + jitter);
 		}
+		if (stats.size > 0) fastify.log.debug(`[arc-schedules] ${stats.size} schedule(s) armed${lock ? ` (leader-safe, holder ${holderId})` : ""}`);
+	});
+	fastify.addHook("onClose", async () => {
+		closing = true;
+		for (const timer of timers.values()) clearTimeout(timer);
+		timers.clear();
+		await Promise.allSettled([...inFlight.values()]);
 	});
-	fastify.log?.debug?.("Request ID plugin registered");
 };
-var requestId_default = fp(requestIdPlugin, {
-	name: "arc-request-id",
+var schedules_default = fp(schedulesPlugin, {
+	name: "arc-schedules",
 	fastify: "5.x"
 });
 //#endregion
-export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };
+export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, schedules_default as schedulesPlugin, schedulesPlugin as schedulesPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/response-cache.d.mts

@@ -1,5 +1,4 @@
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
-
 //#region src/plugins/response-cache.d.ts
 interface ResponseCacheRule {
   /** Path prefix to match (e.g., '/api/products') */
@@ -57,8 +56,11 @@ interface ResponseCacheStats {
 declare module "fastify" {
   interface FastifyInstance {
     responseCache: {
-      /** Invalidate all cached responses matching a path prefix */invalidate: (pathPrefix: string) => number; /** Clear the entire cache */
-      invalidateAll: () => void; /** Get cache statistics */
+      /** Invalidate all cached responses matching a path prefix */
+      invalidate: (pathPrefix: string) => number;
+      /** Clear the entire cache */
+      invalidateAll: () => void;
+      /** Get cache statistics */
       stats: () => ResponseCacheStats;
       /**
        * Route-level preHandler for cache lookup.

package/dist/plugins/response-cache.mjs

@@ -94,6 +94,7 @@ const responseCachePluginImpl = async (fastify, opts = {}) => {
 	], xCacheHeader = true, statsPath = null, keyFn } = opts;
 	const cache = new LRUCache(maxEntries);
 	const invalidateMethods = new Set(invalidateOn.map((m) => m.toUpperCase()));
+	if (!fastify.hasRequestDecorator("__arcCacheTTL")) fastify.decorateRequest("__arcCacheTTL", void 0);
 	/** Find TTL for a given URL path (seconds) */
 	function getTTL(url) {
 		const path = url.split("?")[0] ?? url;

package/dist/plugins/tracing-entry.d.mts

@@ -1,2 +1,2 @@
-import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-D8jlGXP7.mjs";
+import { a as traced, i as isTracingAvailable, n as _default, r as createSpan, t as TracingOptions } from "../tracing-CsGKQJGg.mjs";
 export { type TracingOptions, createSpan, isTracingAvailable, traced, _default as tracingPlugin };

package/dist/plugins/tracing-entry.mjs

@@ -58,7 +58,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.20.0";
+	const resolvedVersion = serviceVersion ?? "2.22.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,
@@ -92,8 +92,11 @@ async function tracingPlugin(fastify, options = {}) {
 	}
 	const tracer = otelTrace.getTracer(serviceName);
 	fastify.decorateRequest("tracer", void 0);
-	fastify.addHook("onRequest", async (request, _reply) => {
-		if (Math.random() > sampleRate) return;
+	fastify.addHook("onRequest", (request, _reply, done) => {
+		if (Math.random() > sampleRate) {
+			done();
+			return;
+		}
 		const span = tracer.startSpan(`HTTP ${request.method} ${request.url}`, {
 			kind: 1,
 			attributes: {
@@ -109,7 +112,7 @@ async function tracingPlugin(fastify, options = {}) {
 			tracer,
 			currentSpan: span
 		};
-		otelContext.with(otelTrace.setSpan(otelContext.active(), span), () => {});
+		otelContext.with(otelTrace.setSpan(otelContext.active(), span), done);
 	});
 	fastify.addHook("onResponse", async (request, reply) => {
 		if (!request.tracer?.currentSpan) return;

package/dist/presets/filesUpload.d.mts

@@ -1,8 +1,7 @@
-import { rt as PresetResult } from "../index-_--GyzcO.mjs";
-import { i as RequestScope } from "../types-LNebCoJx.mjs";
-import { c as PermissionCheck } from "../fields-C7ahdGYf.mjs";
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Co_PQpeQ.mjs";
-
+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 { 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 {
   upload?: boolean;

package/dist/presets/filesUpload.mjs

@@ -1,6 +1,6 @@
 import { i as NotFoundError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
 import { c as getOrgId, g as getUserId } from "../types-bHblZ9YN.mjs";
-import { C as requireAuth, y as allowPublic } from "../permissions-CgbOLJZG.mjs";
+import { b as allowPublic, w as requireAuth } from "../permissions-BJMuKMl7.mjs";
 import { t as multipartBody } from "../multipartBody-CHEQSZ6G.mjs";
 //#region src/presets/filesUpload.ts
 const DEFAULT_FIELD_NAME = "file";

package/dist/presets/index.d.mts

@@ -1,8 +1,7 @@
-import { bt as IControllerResponse, d as PaginationResult, qt as AnyRecord, rt as PresetResult, st as ResourceConfig, xt as IRequestContext } from "../index-_--GyzcO.mjs";
+import { Rt as IControllerResponse, U as ResourceConfig, Y as PresetResult, d as PaginationResult, qt as AnyRecord, zt as IRequestContext } from "../index-DbtgCOCj.mjs";
 import { FilesUploadPresetOptions, FilesUploadPresetPermissions, FilesUploadPresetRoutes, filesUploadPreset } from "./filesUpload.mjs";
 import { MultiTenantOptions, TenantFieldSpec, multiTenantPreset } from "./multiTenant.mjs";
 import { SearchHandler, SearchPresetOptions, SearchRouteConfig, searchPreset } from "./search.mjs";
-
 //#region src/presets/ownedByUser.d.ts
 interface OwnedByUserOptions {
   ownerField?: string;

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-DWsYQdbV.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 { 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,4 @@
-import { J as CrudRouteKey, rt as PresetResult } from "../index-_--GyzcO.mjs";
-
+import { X as CrudRouteKey, Y as PresetResult } from "../index-DbtgCOCj.mjs";
 //#region src/presets/multiTenant.d.ts
 /**
  * One tenant dimension for multi-field filtering. Discriminated by source:

package/dist/presets/search.d.mts

@@ -1,6 +1,5 @@
-import { ft as RouteDefinition, gt as ControllerHandler, pt as RouteMcpConfig, rt as PresetResult } from "../index-_--GyzcO.mjs";
-import { c as PermissionCheck } from "../fields-C7ahdGYf.mjs";
-
+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";
 //#region src/presets/search.d.ts
 /**
  * Search Preset — backend-agnostic search / vector / embed routes

package/dist/presets/search.mjs

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