@classytic/arc 2.23.0 → 2.28.0

package/dist/health-CB_m4S32.mjs

@@ -0,0 +1,377 @@
+import { randomUUID } from "node:crypto";
+import fp from "fastify-plugin";
+//#region src/plugins/requestId.ts
+/**
+* Request ID Plugin
+*
+* Propagates request IDs for distributed tracing.
+* - Accepts incoming x-request-id header (sanitized)
+* - Generates UUID if not provided
+* - Echoes the id on the response header + W3C trace-context propagation
+*
+* ID RESOLUTION LIVES AT THE SERVER LEVEL, NOT HERE. Fastify binds
+* `request.log = logger.child({ reqId: request.id })` at request
+* construction — before any hook runs — so an id assigned inside a hook
+* never reaches the logs. `createApp` therefore wires
+* {@link createRequestIdGenerator} into Fastify's `genReqId` option, and
+* this plugin simply adopts `request.id`. Standalone registration on a
+* bare Fastify instance falls back to the legacy in-hook resolution
+* (header echo / UUID), with the documented limitation that
+* `request.log`'s `reqId` binding predates the overwrite — pass
+* `genReqId: createRequestIdGenerator()` to `Fastify()` to fix that.
+*
+* @example
+* import { requestIdPlugin, createRequestIdGenerator } from '@classytic/arc';
+*
+* const fastify = Fastify({ genReqId: createRequestIdGenerator() });
+* await fastify.register(requestIdPlugin);
+*
+* fastify.get('/', async (request) => {
+*   request.log.info('traced');   // carries the same reqId as the header
+*   return { id: request.id };
+* });
+*/
+/**
+* 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.
+*/
+function sanitizeRequestId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 && trimmed.length <= 128 && /^[\w.:-]+$/.test(trimmed) ? trimmed : void 0;
+}
+/**
+* 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.
+*/
+function createRequestIdGenerator(opts = {}) {
+	const { header = "x-request-id", generator = randomUUID } = opts;
+	const headerName = header.toLowerCase();
+	return (req) => sanitizeRequestId(req.headers[headerName]) ?? generator();
+}
+/** Fastify's default request ids are `req-<base36 counter>`. */
+const FASTIFY_DEFAULT_ID = /^req-[0-9a-z]+$/;
+/** 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 incoming = sanitizeRequestId(request.headers[header]);
+		let requestId = String(request.id);
+		if (incoming && incoming !== requestId) requestId = incoming;
+		else if (!incoming && FASTIFY_DEFAULT_ID.test(requestId)) requestId = generator();
+		if (requestId !== request.id) 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.log?.debug?.("Request ID plugin registered");
+};
+var requestId_default = fp(requestIdPlugin, {
+	name: "arc-request-id",
+	fastify: "5.x"
+});
+//#endregion
+//#region src/plugins/health.ts
+/**
+* Merge health checks without losing ownership information.
+*
+* Check names are the identity used in readiness responses and criticality
+* lookup, so duplicates are ambiguous and fail at boot instead of silently
+* picking the first declaration. Input order is preserved.
+*/
+function mergeHealthChecks(groups) {
+	const owners = /* @__PURE__ */ new Map();
+	const merged = [];
+	for (const group of groups) for (const check of group.checks ?? []) {
+		const prior = owners.get(check.name);
+		if (prior !== void 0) throw new Error(`[arc] duplicate health-check name "${check.name}" — declared by ${prior} and ${group.owner}. Health-check names must be unique.`);
+		owners.set(check.name, group.owner);
+		merged.push(check);
+	}
+	return merged;
+}
+/**
+* Fixed histogram bucket upper bounds (ms). Recording is O(#buckets) per
+* request; the scrape derives quantile UPPER BOUNDS from cumulative counts
+* in O(#buckets) — no sample retention, no per-scrape sort (the previous
+* 10k-sample ring buffer copied + sorted on EVERY scrape), and bucket
+* counts aggregate correctly across instances.
+*/
+const DURATION_BUCKETS_MS = [
+	1,
+	2,
+	5,
+	10,
+	25,
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2500,
+	5e3,
+	1e4
+];
+function createHttpMetrics() {
+	return {
+		requestsTotal: {},
+		durationBuckets: new Array(DURATION_BUCKETS_MS.length + 1).fill(0),
+		durationCount: 0,
+		durationSumMs: 0,
+		startTime: Date.now()
+	};
+}
+/** Smallest bucket upper bound whose cumulative count reaches `q × total`. */
+function bucketQuantile(metrics, q) {
+	const target = Math.ceil(metrics.durationCount * q);
+	let cumulative = 0;
+	for (let i = 0; i < metrics.durationBuckets.length; i++) {
+		cumulative += metrics.durationBuckets[i] ?? 0;
+		if (cumulative >= target) return DURATION_BUCKETS_MS[i] ?? DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
+	}
+	return DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
+}
+const healthPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
+	const readinessChecks = mergeHealthChecks([{
+		owner: "healthPlugin options",
+		checks
+	}]);
+	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" }
+				}
+			}
+		}
+	} }, async (_, reply) => {
+		const results = await runChecks(readinessChecks);
+		const criticalFailed = results.some((result, index) => !result.healthy && (readinessChecks[index]?.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.durationCount > 0) {
+				const p50 = bucketQuantile(httpMetrics, .5);
+				const p95 = bucketQuantile(httpMetrics, .95);
+				const p99 = bucketQuantile(httpMetrics, .99);
+				lines.push("# HELP http_request_duration_milliseconds HTTP request duration (bucket upper bounds)", "# 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 ${httpMetrics.durationSumMs.toFixed(2)}`, `http_request_duration_milliseconds_count ${httpMetrics.durationCount}`, "");
+			}
+		}
+		return lines.join("\n");
+	});
+	if (collectHttpMetrics) fastify.addHook("onResponse", async (_request, reply) => {
+		const duration = reply.elapsedTime;
+		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
+		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
+		let bucket = DURATION_BUCKETS_MS.length;
+		for (let i = 0; i < DURATION_BUCKETS_MS.length; i++) {
+			const bound = DURATION_BUCKETS_MS[i];
+			if (bound !== void 0 && duration <= bound) {
+				bucket = i;
+				break;
+			}
+		}
+		httpMetrics.durationBuckets[bucket] = (httpMetrics.durationBuckets[bucket] ?? 0) + 1;
+		httpMetrics.durationCount++;
+		httpMetrics.durationSumMs += duration;
+	});
+	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) {
+	return Promise.all(checks.map(async (check) => {
+		const start = Date.now();
+		const timeout = check.timeout ?? 5e3;
+		let timer;
+		const abort = new AbortController();
+		try {
+			const checkPromise = Promise.resolve(check.check(abort.signal));
+			const timeoutPromise = new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					const err = /* @__PURE__ */ new Error("Health check timeout");
+					abort.abort(err);
+					reject(err);
+				}, timeout);
+			});
+			const healthy = await Promise.race([checkPromise, timeoutPromise]);
+			return {
+				name: check.name,
+				healthy: Boolean(healthy),
+				duration: Date.now() - start
+			};
+		} catch (err) {
+			return {
+				name: check.name,
+				healthy: false,
+				duration: Date.now() - start,
+				error: err.message
+			};
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}));
+}
+var health_default = fp(healthPlugin, {
+	name: "arc-health",
+	fastify: "5.x"
+});
+//#endregion
+export { requestIdPlugin as a, createRequestIdGenerator as i, health_default as n, requestId_default as o, mergeHealthChecks as r, sanitizeRequestId as s, healthPlugin as t };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { An as defineHook, Cn as afterCreate, Dn as beforeDelete, En as beforeCreate, On as beforeUpdate, Sn as HookSystemOptions, Tn as afterUpdate, _n as HookHandler, bn as HookRegistration, gn as HookContext, hn as DefineHookOptions, kn as createHookSystem, vn as HookOperation, wn as afterDelete, xn as HookSystem, yn as HookPhase } from "../index-BBsvQt7U.mjs";
+import { Cn as defineHook, Sn as createHookSystem, _n as afterDelete, bn as beforeDelete, cn as DefineHookOptions, dn as HookOperation, fn as HookPhase, gn as afterCreate, hn as HookSystemOptions, ln as HookContext, mn as HookSystem, pn as HookRegistration, un as HookHandler, vn as afterUpdate, xn as beforeUpdate, yn as beforeCreate } from "../index-DPRH0Cme.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.mjs

@@ -1,3 +1,4 @@
+import { n as requireSingleHeaderValue } from "../headers-BvlQSDMB.mjs";
 import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
 import { t as createIdempotencyResult } from "../interface-n5hpKg1d.mjs";
 import { createHash } from "node:crypto";
@@ -249,6 +250,26 @@ var MemoryIdempotencyStore = class {
 * // Idempotency-Key: order-123-abc
 *
 * // If same key sent again within TTL, returns cached response
+*
+* ## Guarantee: best-effort effectively-once, NOT exactly-once
+*
+* The plugin gives strong request replay + overlap protection: a
+* distributed lock guards execution (concurrent same-key requests get
+* 409), the store key includes a body/caller fingerprint (a different
+* body under the same key executes as its own operation instead of
+* replaying someone else's response), and a completed result replays on
+* hit. It does NOT make the business effect exactly-once, because the
+* domain write and the idempotency record live in different systems:
+*
+*  - a crash after the DB mutation but before the result is recorded
+*    (preSerialization) lets a retry re-execute the mutation;
+*  - a handler that outruns `lockTimeoutMs` can overlap its own retry —
+*    size the lock timeout above the slowest protected handler.
+*
+* For mutations where re-execution is unacceptable, write the idempotency
+* record in the SAME transaction as the business write inside the handler
+* (the store contract is public — `@classytic/arc/idempotency` exports it),
+* or make the handler naturally idempotent (upserts, compare-and-set).
 */
 const HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
 const HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
@@ -306,7 +327,11 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	*/
 	function normalizeBody(obj, depth = 0) {
 		if (obj === null || typeof obj !== "object") return obj;
-		if (depth >= MAX_FINGERPRINT_DEPTH) return "<truncated>";
+		if (depth >= MAX_FINGERPRINT_DEPTH) try {
+			return `<deep:${createHash("sha256").update(JSON.stringify(obj)).digest("hex").slice(0, 16)}>`;
+		} catch {
+			return "<truncated>";
+		}
 		if (Array.isArray(obj)) return obj.map((item) => normalizeBody(item, depth + 1));
 		const sorted = {};
 		const keys = Object.keys(obj).sort();
@@ -335,8 +360,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	}
 	const idempotencyMiddleware = async (request, reply) => {
 		if (!shouldApplyIdempotency(request)) return;
-		const keyHeader = request.headers[headerName.toLowerCase()];
-		const idempotencyKey = typeof keyHeader === "string" ? keyHeader.trim() : void 0;
+		const idempotencyKey = requireSingleHeaderValue(request.headers, headerName)?.trim();
 		if (!idempotencyKey) return;
 		request.idempotencyKey = idempotencyKey;
 		const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;

package/dist/{index-wMoWBLkn.d.mts → index-BMnbzvtO.d.mts}

@@ -1,6 +1,6 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-C1_WLTMK.mjs";
-import { i as RequestScope, n as Mandate } from "./types-DH0GupI7.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Csxga7d3.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-BGZCzOGL.mjs";
+import { i as RequestScope, n as Mandate } from "./types-DjC-KUCz.mjs";
+import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**

package/dist/{integrations/jobs.d.mts → index-CG4yqMDB.d.mts}

@@ -1,5 +1,59 @@
 import { FastifyPluginAsync } from "fastify";
-//#region src/integrations/jobs.d.ts
+//#region src/integrations/jobs/execution.d.ts
+/**
+ * Timed handler execution — the concurrency core of the jobs worker,
+ * extracted from the BullMQ registration so the algorithm is testable
+ * without queue mocks.
+ *
+ * Contract:
+ *  - The handler receives an `AbortSignal`, aborted when `timeoutMs`
+ *    elapses. The timeout rejects THIS call; the handler itself is only
+ *    signalled — cooperative cancellation.
+ *  - `releaseSlot` (the bulkhead semaphore) fires when the handler
+ *    promise SETTLES, not when the timeout rejects — a timed-out handler
+ *    that keeps running still occupies its concurrency slot, so retries
+ *    can't stack live executions past the limit.
+ *  - `cancelGraceMs` bounds that hold: a handler ignoring its signal past
+ *    timeout + grace has its slot force-released (logged loudly — beyond
+ *    this point the bulkhead can be exceeded by the abandoned execution).
+ *  - A timed-out handler's eventual settle is logged for observability;
+ *    its result is discarded.
+ *  - `releaseSlot` is invoked exactly once, on every path (success,
+ *    failure, timeout-then-settle, grace expiry). Synchronous throws from
+ *    the handler are converted to rejections so release always fires.
+ */
+interface TimedHandlerLogger {
+  warn(obj: Record<string, unknown>, msg: string): void;
+}
+interface ExecuteTimedHandlerOptions<T> {
+  /** The work. Must treat the signal as its cancellation channel. */
+  run: (signal: AbortSignal) => Promise<T>;
+  /** Job/queue label for timeout errors and logs. */
+  label: string;
+  /** Correlation id for logs (e.g. the BullMQ job id). */
+  jobId?: string;
+  /** Reject after this many ms and abort the signal. Omit = no timeout. */
+  timeoutMs?: number;
+  /** Slot hold-bound after timeout (default: 30_000). */
+  cancelGraceMs?: number;
+  /** Bulkhead slot release — called exactly once. Omit when unguarded. */
+  releaseSlot?: () => void;
+  logger?: TimedHandlerLogger;
+}
+declare function executeTimedHandler<T>(options: ExecuteTimedHandlerOptions<T>): Promise<T>;
+//#endregion
+//#region src/integrations/jobs/types.d.ts
+/**
+ * Job queue integration — public contract (definitions, meta, dispatcher).
+ *
+ * Directory map (mechanical split of the former single file):
+ *   types.ts     — this contract + `defineJob`
+ *   execution.ts — `executeTimedHandler` (timeout / cancellation / bulkhead)
+ *   repeat.ts    — repeatable-schedule reconciliation (boot hygiene)
+ *   plugin.ts    — BullMQ wiring (queues, workers, DLQ, routes, shutdown)
+ *   index.ts     — public barrel; `src/integrations/jobs.ts` re-exports it
+ *                  so the package subpath is unchanged
+ */
 /** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
 interface JobRepeatOptions {
   /** Cron pattern (e.g. '0 9 * * *' = every day 09:00). Mutually exclusive with `every`. */
@@ -44,13 +98,37 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
    * and appear as `throttled: true` in `GET /jobs/:id/status`.
    * Distinct from BullMQ `concurrency` — use this when the constraint is a
    * downstream resource (AI model rate limit, DB connection pool, external API).
+   *
+   * The slot is held until the handler actually SETTLES — a timed-out
+   * handler that keeps running (ignoring `meta.signal`) still counts
+   * against `maxConcurrent`, so retries can't stack live executions past
+   * the limit. `cancelGraceMs` bounds how long a stuck handler may hold
+   * its slot after timeout.
    */
   maxConcurrent?: number;
+  /**
+   * How long after a TIMEOUT a still-running handler may keep its
+   * `maxConcurrent` slot before the slot is force-released (default:
+   * 30_000). The bulkhead limits LIVE handlers, not worker awaits — but a
+   * handler that ignores `meta.signal` forever must not wedge the queue.
+   * A force-release is logged loudly: past that point the bulkhead can be
+   * exceeded by the abandoned execution.
+   */
+  cancelGraceMs?: number;
 }
 interface JobMeta {
   jobId: string;
   attemptsMade: number;
   timestamp: number;
+  /**
+   * Aborted when the job's `timeout` elapses. Pass it to fetch/DB calls so
+   * timed-out work actually STOPS — the timeout alone only rejects the
+   * worker's await (releasing the concurrency slot) while the handler keeps
+   * running; a BullMQ retry can then overlap the original execution.
+   * Handlers that ignore the signal must be idempotent / compare-and-set
+   * safe under that overlap.
+   */
+  signal: AbortSignal;
 }
 interface JobDispatchOptions {
   /** Delay job execution by ms */
@@ -148,6 +226,8 @@ interface QueueStats {
  * });
  */
 declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDefinition<TData, TResult>): JobDefinition<TData, TResult>;
+//#endregion
+//#region src/integrations/jobs/plugin.d.ts
 /**
  * Pluggable BullMQ job queue integration for Arc.
  *
@@ -156,4 +236,4 @@ declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDe
  */
 declare const jobsPlugin: FastifyPluginAsync<JobsPluginOptions>;
 //#endregion
-export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobStatus, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };
+export { JobMeta as a, JobsPluginOptions as c, ExecuteTimedHandlerOptions as d, TimedHandlerLogger as f, JobDispatcher as i, QueueStats as l, JobDefinition as n, JobRepeatOptions as o, executeTimedHandler as p, JobDispatchOptions as r, JobStatus as s, jobsPlugin as t, defineJob as u };

package/dist/index-CZY4EGga.d.mts

@@ -0,0 +1,107 @@
+import { a as ModuleContribution, h as HealthCheck, n as ArcModuleInput, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-Cu6vVJmh.mjs";
+import { FastifyInstance } from "fastify";
+//#region src/factory/module/contributions.d.ts
+/**
+ * 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.
+ */
+declare function collectModuleHealthChecks(modules: readonly ArcModule[]): HealthCheck[];
+/**
+ * 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).
+ */
+declare function collectModuleWorkflows(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<unknown[]>;
+/**
+ * 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.
+ */
+declare function collectModuleScheduledJobs(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<ScheduleDefinition[]>;
+//#endregion
+//#region src/factory/module/lifecycle.d.ts
+/**
+ * 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.
+ */
+declare function subscribeModuleEventHandlers(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<Array<() => void | Promise<void>>>;
+//#endregion
+//#region src/factory/module/order.d.ts
+/**
+ * Order modules for composition by their `dependsOn` edges — a STABLE
+ * topological sort. Called once at the start of the bootstrap phase; every
+ * subsequent phase (bootstrap, resources, afterResources, and reverse-order
+ * onClose) iterates the returned list, so a module's declared dependencies are
+ * always composed before it.
+ *
+ * "Stable" = modules with no edge between them keep their original list order,
+ * so declaring `dependsOn` on one module never silently reorders an unrelated
+ * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+ * returned unchanged.
+ *
+ * Fail-fast — throws (never reorders past a broken contract) on:
+ *   - duplicate module names (the name is the graph key)
+ *   - a `dependsOn` name not present in the composed set
+ *   - a self-reference (`dependsOn` includes the module's own name)
+ *   - a dependency cycle (reports the concrete `a → b → … → a` path)
+ */
+declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
+//#endregion
+//#region src/factory/module/resolve.d.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.
+ */
+declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
+/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
+declare function resolveContribution<T>(contribution: ModuleContribution<T> | undefined, fastify: FastifyInstance): Promise<readonly T[]>;
+//#endregion
+//#region src/factory/module/index.d.ts
+/**
+ * Identity helper for authoring a typed module — mirrors `defineResource`.
+ * Gives inference + a single obvious construction site; does no work.
+ *
+ * `TExports` is inferred from the `bootstrap` return value, so a module
+ * author gets a typed public export for free:
+ *
+ * ```ts
+ * export const accountingModule = (deps: Deps) =>
+ *   defineModule({
+ *     name: "accounting",
+ *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+ *   });
+ * ```
+ */
+declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
+/**
+ * Typed accessor for a module's public export (its `bootstrap` return value),
+ * recorded at `fastify.arc.modules[name]`.
+ *
+ * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
+ * accessors): a missing entry means the module either isn't composed, is
+ * composed AFTER the caller (list order = init order), or returned nothing —
+ * all wiring bugs that must surface at boot, not as `undefined` downstream.
+ *
+ * The type parameter is an assertion, not a proof. Two ways to type it:
+ *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
+ *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
+ *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
+ */
+declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
+declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
+//#endregion
+export { orderModules as a, collectModuleScheduledJobs as c, resolveModule as i, collectModuleWorkflows as l, getModuleExports as n, subscribeModuleEventHandlers as o, resolveContribution as r, collectModuleHealthChecks as s, defineModule as t };