@classytic/arc 2.41.1 → 2.43.0

package/dist/events/transports/redis-stream-entry.mjs

@@ -1,25 +1,17 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { r as workSeedFromEvent, t as runWorkScope } from "../../workScope-CxKqoIFn.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { n as evictToSize } from "../../boundedMap-BULzfXYU.mjs";
+import { r as workSeedFromEvent, t as runWorkScope } from "../../workScope-zpPyge4t.mjs";
+import { t as getSubscriberId } from "../../subscriberIdentity-CW39uA8G.mjs";
 import sjson from "secure-json-parse";
-import { matchEventPattern } from "@classytic/primitives/events";
+import { createEventRouter } from "@classytic/primitives/events";
 //#region src/events/transports/redis-stream.ts
 /**
-* Redis Stream Event Transport — Durable Event Delivery
+* Redis Stream Event Transport — durable, at-least-once delivery via
+* `XADD`/`XREADGROUP` consumer groups (one consumer per group gets each event).
 *
-* Uses Redis Streams (`XADD`/`XREADGROUP`) for persistent, at-least-once event
-* delivery across multiple service instances. Unlike Pub/Sub, events are stored
-* in Redis and survive crashes/restarts.
-*
-* **Delivery guarantee:** at-least-once. Failed messages are left unacked and
-* reclaimed after `claimTimeoutMs`, which can result in duplicate handler
-* execution. Consumers must be idempotent (e.g. use `event.meta.id` as a
-* deduplication key) to achieve effectively-once processing.
-*
-* Key features:
-* - Consumer groups: each event delivered to exactly one consumer per group
-* - Crash recovery: pending entries are auto-claimed after `claimTimeoutMs`
-* - Dead letter stream: events exceeding `maxRetries` are moved to a DLQ
-* - Backpressure: configurable block time and batch size
+* Failed messages stay unacked and are reclaimed after `claimTimeoutMs`, so
+* handlers may run more than once — they must be idempotent (dedupe on
+* `event.meta.id`). Entries exceeding `maxRetries` move to a dead-letter stream.
 *
 * @example
 * ```typescript
@@ -36,13 +28,9 @@ import { matchEventPattern } from "@classytic/primitives/events";
 * ```
 */
 /**
-* Hard cap on the failure-context map. Entries are deleted on local ack and
-* on DLQ write, but a message that fails HERE and is later acked or
-* dead-lettered by a DIFFERENT consumer in the group never gets cleared
-* locally — without a cap the map grows for the life of the process in
-* multi-consumer deployments. Eviction is oldest-first (Map insertion
-* order); an evicted entry only degrades the eventual DLQ envelope to the
-* existing cross-consumer fallback message, never loses the event itself.
+* Cap on the failure-context map: a message that fails here but is resolved by
+* ANOTHER consumer is never cleared locally. Eviction is oldest-first and only
+* degrades the DLQ envelope's error detail, never loses the event.
 */
 const MAX_FAILURE_CONTEXT_ENTRIES = 1024;
 var RedisStreamTransport = class {
@@ -58,36 +46,34 @@ var RedisStreamTransport = class {
 	claimTimeoutMs;
 	deadLetterStream;
 	maxLen;
+	groupStartId;
 	maxPayloadBytes;
 	logger;
-	/** Tracks the lifecycle policy — set in constructor, read in close(). */
 	externalLifecycle;
 	closeTimeoutMs;
-	handlers = /* @__PURE__ */ new Map();
+	router = createEventRouter();
 	running = false;
 	pollPromise = null;
 	/**
-	* Monotonic counter bumped every time the poll loop should stop —
-	* `unsubscribe` (last handler removed) and `close()` increment it. Each
-	* `pollLoop` instance captures its generation at start and exits when
-	* `this.generation` no longer matches. Prevents the
-	* subscribe → unsubscribe → fast-resubscribe race where the old loop
-	* would still be in `XREADGROUP BLOCK` while a new loop started, leading
-	* to two concurrent poll loops on the same consumer name.
+	* Bumped whenever the poll loop should stop (last unsubscribe, `close()`).
+	* Each loop exits once its captured generation is stale, so a fast
+	* unsubscribe → resubscribe never leaves two loops on one consumer name.
 	*/
 	generation = 0;
 	groupCreated = false;
 	/**
-	* Last-seen failure context per message id, populated when an in-process
-	* handler throws in {@link processEntry}. Consumed (and cleared) by
-	* {@link moveToDlq} so the dead-letter envelope carries the actual error
-	* message instead of opaque "reclaimed without context". Entries are
-	* deleted on ack and on DLQ write; messages resolved by ANOTHER consumer
-	* never drain locally, so the map is additionally hard-capped at
-	* {@link MAX_FAILURE_CONTEXT_ENTRIES} with oldest-first eviction.
+	* Last handler failure per message id, so the DLQ envelope carries the real
+	* error. Cleared on ack / DLQ write; capped at {@link MAX_FAILURE_CONTEXT_ENTRIES}.
 	*/
 	failureContext = /* @__PURE__ */ new Map();
-	/** One-shot guard so the "client lacks xrange" warning fires once per process. */
+	/** Set by `hold()`: subscriptions register, consumption waits for `start()`. */
+	held = false;
+	/** Handler → a key stable across replicas: pattern, name, and order among same-named handlers. */
+	handlerKeys = /* @__PURE__ */ new Map();
+	handlerKeyOwners = /* @__PURE__ */ new Map();
+	handlerPatterns = /* @__PURE__ */ new Map();
+	handlerProgressTtlMs;
+	tracksProgress;
 	xrangeWarningEmitted = false;
 	constructor(redis, options = {}) {
 		this.redis = redis;
@@ -100,15 +86,25 @@ var RedisStreamTransport = class {
 		this.maxRetries = options.maxRetries ?? 5;
 		this.claimTimeoutMs = options.claimTimeoutMs ?? 3e4;
 		this.deadLetterStream = options.deadLetterStream ?? "arc:events:dlq";
-		this.maxLen = options.maxLen ?? 1e4;
+		this.maxLen = options.maxLen ?? 0;
+		this.groupStartId = options.groupStart === "beginning" ? "0" : "$";
 		this.maxPayloadBytes = options.maxPayloadBytes ?? 1e6;
 		this.externalLifecycle = options.externalLifecycle ?? false;
 		this.closeTimeoutMs = options.closeTimeoutMs ?? 1e3;
 		this.logger = options.logger ?? console;
+		this.handlerProgressTtlMs = options.handlerProgressTtlMs ?? 6048e5;
+		this.tracksProgress = [
+			"hset",
+			"hgetall",
+			"del",
+			"pexpire"
+		].every((m) => typeof redis[m] === "function");
+		if (!this.tracksProgress) this.logger.warn("[RedisStreamTransport] redis client lacks hset/hgetall/del/pexpire — a retried message re-runs handlers that already succeeded. Use ioredis or add them to the wrapper.");
 	}
 	async publish(event) {
 		const serialized = JSON.stringify(event);
-		if (serialized.length > this.maxPayloadBytes) throw new Error(`[RedisStreamTransport] Event payload (${serialized.length} bytes) exceeds limit (${this.maxPayloadBytes}). Consider breaking into smaller events or increasing maxPayloadBytes.`);
+		const payloadBytes = Buffer.byteLength(serialized, "utf8");
+		if (payloadBytes > this.maxPayloadBytes) throw new Error(`[RedisStreamTransport] Event payload (${payloadBytes} bytes) exceeds limit (${this.maxPayloadBytes}). Consider breaking into smaller events or increasing maxPayloadBytes.`);
 		const args = [
 			this.stream,
 			...this.maxLen > 0 ? [
@@ -125,66 +121,77 @@ var RedisStreamTransport = class {
 		await this.redis.xadd(...args);
 	}
 	async subscribe(pattern, handler) {
-		if (!this.handlers.has(pattern)) this.handlers.set(pattern, /* @__PURE__ */ new Set());
-		this.handlers.get(pattern)?.add(handler);
-		if (!this.running) {
-			await this.ensureGroup();
-			this.running = true;
-			const myGen = ++this.generation;
-			this.pollPromise = this.pollLoop(myGen).catch((err) => {
-				this.logger.error("[RedisStreamTransport] Poll loop crashed:", err);
-				if (this.generation === myGen) this.running = false;
-			});
+		if (!this.handlerKeys.has(handler)) {
+			const id = getSubscriberId(handler);
+			const key = id === void 0 ? `${pattern}#${handler.name || "anonymous"}` : `subscriber:${id}`;
+			const owner = this.handlerKeyOwners.get(key);
+			if (owner && owner !== handler) throw new Error(`[RedisStreamTransport] Ambiguous subscriber identity '${key}' — wrap each handler withSubscriberId using a stable unique id.`);
+			this.handlerKeyOwners.set(key, handler);
+			this.handlerKeys.set(handler, key);
 		}
+		const patterns = this.handlerPatterns.get(handler) ?? /* @__PURE__ */ new Set();
+		patterns.add(pattern);
+		this.handlerPatterns.set(handler, patterns);
+		this.router.add(pattern, handler);
+		if (!this.held) await this.startPolling();
 		return () => {
-			const set = this.handlers.get(pattern);
-			if (set) {
-				set.delete(handler);
-				if (set.size === 0) this.handlers.delete(pattern);
+			this.router.remove(pattern, handler);
+			patterns.delete(pattern);
+			if (patterns.size === 0) {
+				const key = this.handlerKeys.get(handler);
+				if (key && this.handlerKeyOwners.get(key) === handler) this.handlerKeyOwners.delete(key);
+				this.handlerKeys.delete(handler);
+				this.handlerPatterns.delete(handler);
 			}
-			if (this.handlers.size === 0 && this.running) {
+			if (this.router.size === 0 && this.running) {
 				this.running = false;
 				this.generation++;
 			}
 		};
 	}
 	/**
-	* Stop polling and release transport state.
-	*
-	* **Two close contracts** — pick the one that matches your deployment:
-	*
-	* 1. **Default (`externalLifecycle: false`) — strict bounded close.**
-	*    `close()` waits up to `closeTimeoutMs` for the in-flight
-	*    `XREADGROUP BLOCK` to drain. On timeout it calls `redis.disconnect()`
-	*    (or `quit()` if the client lacks `disconnect`) to break the BLOCK
-	*    immediately, then awaits the loop's exit. After `close()` returns
-	*    the transport is fully closed and the connection is released.
-	*
-	* 2. **`externalLifecycle: true` — bounded RETURN, background drain.**
-	*    Arc must NOT touch a connection it doesn't own. `close()` returns
-	*    within `closeTimeoutMs`, but the poll loop is left to drain on its
-	*    own when its outstanding `XREADGROUP BLOCK` returns (up to
-	*    `blockTimeMs`). Arc silently absorbs the loop's eventual completion
-	*    so the host doesn't see unhandled rejections / log spam against a
-	*    transport it considers closed. The host's own `redis.quit()` /
-	*    process exit is what ultimately tears the connection down.
+	* Register subscriptions without consuming until `start()`. arc holds consumption for the whole
+	* boot, so an entry for a module whose handler installs later is not acked with no handler.
+	*/
+	hold() {
+		this.held = true;
+	}
+	/** Begin consuming — every handler registered while held sees the stream from here. */
+	async start() {
+		this.held = false;
+		if (this.router.size > 0) await this.startPolling();
+	}
+	async startPolling() {
+		if (this.running) return;
+		await this.ensureGroup();
+		this.running = true;
+		const myGen = ++this.generation;
+		this.pollPromise = this.pollLoop(myGen).catch((err) => {
+			this.logger.error("[RedisStreamTransport] Poll loop crashed:", err);
+			if (this.generation === myGen) this.running = false;
+		});
+	}
+	/**
+	* Stop polling and release transport state. Waits up to `closeTimeoutMs`
+	* for the in-flight `XREADGROUP BLOCK`, then:
 	*
-	*    Practical implication: under `externalLifecycle: true`, set
-	*    `blockTimeMs` low (e.g. 500ms) so the background drain window is
-	*    short. The transport is "closed enough" to stop dispatching to
-	*    handlers (handlers map is cleared and generation is bumped) but is
-	*    not "fully closed" in the connection-lifecycle sense until the host
-	*    closes the underlying client.
+	* - default: force-disconnects the client to break the BLOCK and awaits the
+	*   loop — the transport is fully closed on return.
+	* - `externalLifecycle: true`: returns without touching the host's client;
+	*   the loop drains in the background (up to `blockTimeMs` — keep it low)
+	*   with its outcome silenced. Handlers are already cleared, so nothing
+	*   dispatches meanwhile.
 	*
-	* In both modes the generation counter is bumped, so a follow-up
-	* `subscribe()` spawns a fresh poll loop with a new generation — the
-	* stale loop exits on its next iteration and never overlaps the new one.
+	* A later `subscribe()` starts a fresh loop that never overlaps the stale one.
 	*/
 	async close() {
 		this.running = false;
 		this.generation++;
-		this.handlers.clear();
+		this.router.clear();
 		this.failureContext.clear();
+		this.handlerKeys.clear();
+		this.handlerKeyOwners.clear();
+		this.handlerPatterns.clear();
 		if (this.pollPromise !== null) {
 			if (await Promise.race([this.pollPromise.then(() => "drained"), this.sleep(this.closeTimeoutMs).then(() => "timeout")]) === "timeout") {
 				if (!this.externalLifecycle) {
@@ -202,7 +209,7 @@ var RedisStreamTransport = class {
 	async ensureGroup() {
 		if (this.groupCreated) return;
 		try {
-			await this.redis.xgroup("CREATE", this.stream, this.group, "$", "MKSTREAM");
+			await this.redis.xgroup("CREATE", this.stream, this.group, this.groupStartId, "MKSTREAM");
 		} catch (err) {
 			if (err instanceof Error && !err.message.includes("BUSYGROUP")) throw err;
 		}
@@ -227,13 +234,8 @@ var RedisStreamTransport = class {
 		if (!result) return;
 		for (const [, entries] of result) await this.processEntries(entries);
 	}
-	/**
-	* Process a batch's entries with bounded concurrency
-	* (`processingConcurrency`, default 1 = strict order). Worker-pool over a
-	* shared index — at most N entries in flight, each entry's own handlers
-	* still sequential inside `processEntry`.
-	*/
-	async processEntries(entries) {
+	/** Process a batch with at most `processingConcurrency` entries in flight. */
+	async processEntries(entries, retry = false) {
 		const live = [];
 		const ghostIds = [];
 		for (const [messageId, fields] of entries) if (fields) live.push([messageId, fields]);
@@ -244,14 +246,14 @@ var RedisStreamTransport = class {
 			this.logger.error(`[RedisStreamTransport] Failed to ack ${ghostIds.length} trimmed entr(ies):`, err);
 		}
 		if (this.processingConcurrency <= 1) {
-			for (const [messageId, fields] of live) await this.processEntry(messageId, fields);
+			for (const [messageId, fields] of live) await this.processEntry(messageId, fields, retry);
 			return;
 		}
 		let next = 0;
 		const workers = Array.from({ length: Math.min(this.processingConcurrency, live.length) }, async () => {
 			while (next < live.length) {
 				const entry = live[next++];
-				if (entry) await this.processEntry(entry[0], entry[1]);
+				if (entry) await this.processEntry(entry[0], entry[1], retry);
 			}
 		});
 		await Promise.all(workers);
@@ -272,13 +274,13 @@ var RedisStreamTransport = class {
 			if (overRetryIds.length > 0) await this.moveToDlq(overRetryIds);
 			if (staleIds.length > 0) {
 				const claimed = await this.redis.xclaim(this.stream, this.group, this.consumer, this.claimTimeoutMs, ...staleIds);
-				await this.processEntries(claimed);
+				await this.processEntries(claimed, true);
 			}
 		} catch (err) {
 			this.logger.error("[RedisStreamTransport] claimPending error:", err);
 		}
 	}
-	async processEntry(messageId, fields) {
+	async processEntry(messageId, fields, retry = false) {
 		const event = parseStreamFields(fields);
 		if (!event) {
 			this.logger.warn(`[RedisStreamTransport] Malformed entry ${messageId} — missing type/data or invalid JSON, acking and skipping`);
@@ -286,24 +288,37 @@ var RedisStreamTransport = class {
 			return;
 		}
 		const matchingHandlers = this.getMatchingHandlers(event.type);
+		const progressKey = `${this.stream}:handled:${this.group}:${messageId}`;
+		const alreadyDone = retry && this.tracksProgress ? new Set(Object.keys(await this.redis.hgetall?.(progressKey) ?? {})) : /* @__PURE__ */ new Set();
+		const completed = [];
 		let allSucceeded = true;
 		let lastError;
 		let lastHandlerName;
 		await runWorkScope(workSeedFromEvent(event), async () => {
-			for (const handler of matchingHandlers) try {
-				await handler(event);
-			} catch (err) {
-				allSucceeded = false;
-				lastError = err instanceof Error ? err : new Error(String(err));
-				lastHandlerName = handler.name || lastHandlerName;
-				this.logger.error(`[RedisStreamTransport] Handler error for ${event.type}:`, err);
+			for (const handler of matchingHandlers) {
+				const key = this.handlerKeys.get(handler) ?? handler.name;
+				if (alreadyDone.has(key)) continue;
+				try {
+					await handler(event);
+					completed.push(key);
+				} catch (err) {
+					allSucceeded = false;
+					lastError = err instanceof Error ? err : new Error(String(err));
+					lastHandlerName = handler.name || lastHandlerName;
+					this.logger.error(`[RedisStreamTransport] Handler error for ${event.type}:`, err);
+				}
 			}
 		});
 		if (allSucceeded) {
 			await this.redis.xack(this.stream, this.group, messageId);
+			if (alreadyDone.size > 0) await this.redis.del?.(progressKey);
 			this.failureContext.delete(messageId);
 			return;
 		}
+		if (this.tracksProgress && completed.length > 0) {
+			await this.redis.hset?.(progressKey, ...completed.flatMap((k) => [k, "1"]));
+			await this.redis.pexpire?.(progressKey, this.handlerProgressTtlMs);
+		}
 		const now = /* @__PURE__ */ new Date();
 		const prior = this.failureContext.get(messageId);
 		this.failureContext.delete(messageId);
@@ -314,21 +329,15 @@ var RedisStreamTransport = class {
 			attempts: (prior?.attempts ?? 0) + 1,
 			handlerName: lastHandlerName ?? prior?.handlerName
 		});
-		if (this.failureContext.size > MAX_FAILURE_CONTEXT_ENTRIES) {
-			const oldest = this.failureContext.keys().next().value;
-			if (oldest !== void 0) this.failureContext.delete(oldest);
-		}
+		evictToSize(this.failureContext, MAX_FAILURE_CONTEXT_ENTRIES);
 	}
 	/**
-	* The canonical matcher from primitives — the SAME glob rules the memory
-	* transport speaks. A private matcher here once accepted `prefix.*` but not
-	* `prefix:*`, so an `order:*` subscription that worked in-process received
-	* nothing after a move to the stream, with no error.
+	* Uses the primitives router — the same glob rules (and dedup) as the memory
+	* transport. Don't swap in a private matcher: subscriptions must behave
+	* identically in-process and on the stream.
 	*/
 	getMatchingHandlers(eventType) {
-		const matched = [];
-		for (const [pattern, handlers] of this.handlers) if (matchEventPattern(pattern, eventType)) for (const h of handlers) matched.push(h);
-		return matched;
+		return this.router.route(eventType);
 	}
 	async moveToDlq(ids) {
 		if (this.deadLetterStream === false) {
@@ -354,17 +363,10 @@ var RedisStreamTransport = class {
 		}
 	}
 	/**
-	* Reconstruct a `DeadLetteredEvent` for a message id. Reads the original
-	* entry via `xrange` (when the client supports it) and merges in any
-	* in-process failure context. Returns `null` only when BOTH sources are
-	* missing — callers ack-and-drop rather than re-queuing a ghost.
-	*
-	* Graceful degradation paths:
-	*   - Client lacks `xrange` (older custom wrappers) → log once, build the
-	*     envelope from `failureContext` alone. Payload is absent but the
-	*     error reason + attempt accounting still survive.
-	*   - `xrange` throws (network blip, ACL) → same fallback.
-	*   - Source entry trimmed before DLQ write → same fallback.
+	* Build a `DeadLetteredEvent` from the original entry (via `xrange`) plus
+	* any local failure context. If the entry is unreadable (no `xrange`, error,
+	* or trimmed) the envelope keeps just the error and attempts. Returns `null`
+	* only when both are missing.
 	*/
 	async buildDlqEnvelope(id) {
 		const ctx = this.failureContext.get(id);
@@ -404,24 +406,14 @@ var RedisStreamTransport = class {
 		return new Promise((resolve) => setTimeout(resolve, ms));
 	}
 };
-/** Poll-error backoff tuning — see {@link fullJitterBackoffMs}. */
 const POLL_ERROR_BACKOFF_BASE_MS = 1e3;
 const POLL_ERROR_BACKOFF_MAX_MS = 3e4;
 const POLL_ERROR_BACKOFF_FLOOR_MS = 100;
 /**
-* Exponential backoff with full jitter for poll-error retries.
-*
-* The delay is drawn uniformly from the capped exponential window
-* `[floor, min(max, base * 2^(attempt-1))]` — the AWS "full jitter"
-* strategy. Full jitter decorrelates a fleet of consumers that all observed
-* the same Redis blip; the small floor keeps a near-zero draw from
-* hot-spinning the loop while Redis is hard-down.
-*
-* Sibling of `exponentialBackoff()` in `src/events/outbox.ts`, which is a
-* PUBLIC store-author helper with additive jitter and `Date` (retryAt)
-* semantics. Deliberately not shared: the two have different jitter models
-* and audiences, and coupling them would hang this internal tuning off the
-* public API surface.
+* Poll-error delay drawn uniformly from `[floor, min(max, base * 2^(attempt-1))]`
+* ("full jitter"). The floor stops a near-zero draw from hot-spinning while
+* Redis is down. Intentionally separate from the public `exponentialBackoff()`
+* (different jitter model and audience).
 *
 * @param attempt 1-indexed consecutive poll-error count (reset on success)
 * @param random injectable for deterministic tests; defaults to `Math.random`
@@ -431,11 +423,7 @@ function fullJitterBackoffMs(attempt, random = Math.random) {
 	const capped = Math.min(POLL_ERROR_BACKOFF_MAX_MS, exp);
 	return POLL_ERROR_BACKOFF_FLOOR_MS + random() * (capped - POLL_ERROR_BACKOFF_FLOOR_MS);
 }
-/**
-* Convert a thrown value into the `DeadLetteredEvent.error` shape — message
-* always present, optional `code` (string only) and `stack`. Centralised so
-* the failure-context tracker and the DLQ envelope writer agree.
-*/
+/** Convert a thrown value into the `DeadLetteredEvent.error` shape. */
 function toErrorRecord(err) {
 	const e = err instanceof Error ? err : new Error(String(err));
 	const code = e.code;
@@ -446,15 +434,9 @@ function toErrorRecord(err) {
 	};
 }
 /**
-* Parse a Redis Stream entry's flat `[key, value, key, value, ...]` field
-* array into a typed `DomainEvent`, or `null` when the entry is malformed
-* (missing `type` / `data`, unparseable JSON, or missing required event
-* structure).
-*
-* Pure on purpose — used by both `processEntry` (the live consumer path)
-* and `buildDlqEnvelope` (the dead-letter writer). Keeping the parse logic
-* in one place avoids the silent drift class that produced the original
-* "DLQ has no payload" bug.
+* Parse a stream entry's flat `[key, value, ...]` fields into a `DomainEvent`,
+* or `null` when malformed. Shared by the consumer and the DLQ writer so the
+* two can't drift.
 */
 function parseStreamFields(fields) {
 	let eventType;

package/dist/events/transports/redis.d.mts

@@ -1,5 +1,5 @@
 
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-CbUKDzZZ.mjs";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler } from "../../EventTransport-CiicKz2Z.mjs";
 //#region src/events/transports/redis.d.ts
 interface RedisLike {
   publish(channel: string, message: string): Promise<number>;

package/dist/events/transports/redis.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { r as workSeedFromEvent, t as runWorkScope } from "../../workScope-CxKqoIFn.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { r as workSeedFromEvent, t as runWorkScope } from "../../workScope-zpPyge4t.mjs";
 import sjson from "secure-json-parse";
 //#region src/events/transports/redis.ts
 /**

package/dist/factory/index.d.mts

@@ -1,23 +1,15 @@
 
-import { _ as HealthCheck, a as ModuleContribution, c as LoadResourcesOptions, d as loadResources, i as EventHandlerDefinition, l as ResourceLike, n as ArcModuleInput, o as ModuleDisposer, r as ArcModuleRegistry, s as ModuleSetupContext, t as ArcModule, u as ResourceModule } from "../types-DfVDvkdP.mjs";
-import { _ as collectModuleScheduledJobs, a as lazyModuleExports, c as getModuleState, d as resolveModule, f as orderModules, g as collectModuleHealthChecks, h as extendModule, i as hasModuleExports, l as hasModule, m as ModuleExtension, n as getModuleExports, o as lazyRequiredModuleExports, p as subscribeModuleEventHandlers, r as getOptionalModuleExports, s as ModuleState, t as defineModule, u as resolveContribution, v as collectModuleWorkflows } from "../index-CFfLKMH4.mjs";
-import { c as ResolvedResourceDescriptor, l as describeResolvedModule, o as ResolvedModuleDescriptor, s as ResolvedModuleLifecycle } from "../fastify-augmentation-Cq2nHVaW.mjs";
-import { a as RawBodyOptions, c as BetterAuthOption, d as JwtAuthOption, i as MultipartOptions, l as CustomAuthenticatorOption, n as preloadResourcesAsync, o as UnderPressureOptions, r as CreateAppOptions, s as AuthOption, t as preloadResources, u as CustomPluginAuthOption } from "../preloadResources-CjS2OfpU.mjs";
+import { _ as ResourceLike, a as ArcPortRegistry, c as LazyBridge, d as ModulePorts, f as ModuleRequirements, g as LoadResourcesOptions, h as ModuleSetupContext, i as ArcModuleRegistry, l as ModuleContribution, m as ModuleDisposer, n as ArcModule, o as ArcPorts, p as PortName, r as ArcModuleInput, s as EventHandlerDefinition, t as ArcCompositionConfig, u as ModuleName, v as ResourceModule, w as HealthCheck, y as loadResources } from "../types-BJ-2XqVF.mjs";
+import { $ as verifyModuleGraph, A as AsyncApiCatalogEntry, B as ModuleGraphMode, C as planModules, D as ModuleExtension, E as subscribeModuleEventHandlers, F as DurabilityFacts, G as activateBridges, H as ModuleGraphOptions, I as HandlerDurabilityFact, J as crudEventsOf, K as analyzeModuleGraph, L as ModuleGraph, M as toAsyncApi, N as CrudSurface, O as extendModule, P as DerivedPublishes, Q as verifyEventDurability, R as ModuleGraphAnalysis, S as compositionProblems, T as orderModules, U as ModuleKind, V as ModuleGraphNode, W as SkippedBridge, X as eventTopology, Y as dependentsOf, Z as renderModuleGraph, _ as ClosureNode, a as lazyModuleExports, b as PlanModulesOptions, c as getModuleResources, d as resolveContribution, f as resolveModule, g as withRelayNudge, h as createRelayNudge, i as hasModuleExports, j as AsyncApiInfo, k as collectModuleWorkflows, l as getModuleState, m as RelayOption, n as getModuleExports, o as lazyRequiredModuleExports, p as RelayNudge, q as buildModuleGraph, r as getOptionalModuleExports, s as ModuleState, t as defineModule, u as hasModule, v as CompositionProblem, w as resolveModuleClosure, x as assertComposable, y as ModulePlan, z as ModuleGraphIssue } from "../index-JdbZAIsm.mjs";
+import { a as ResolvedModuleDescriptor, o as ResolvedModuleLifecycle, s as ResolvedResourceDescriptor } from "../fastify-augmentation-DhUJ-mvo.mjs";
+import { a as UnderPressureOptions, c as CustomAuthenticatorOption, i as RawBodyOptions, l as CustomPluginAuthOption, n as CreateAppOptions, o as AuthOption, r as MultipartOptions, s as BetterAuthOption, t as BootDisposer, u as JwtAuthOption } from "../index-C8zVGYsk.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 //#region src/factory/createApp.d.ts
 /**
- * Default redact paths layered into Fastify's pino logger when the host
- * doesn't supply a `logger.redact` of their own. Covers the common token /
- * cookie / password leak surfaces — `Authorization` and `Cookie` headers
- * (and their case-variants because Node lower-cases incoming headers but
- * outgoing logs may carry either), API-key headers, and any nested
- * `password` / `token` / `secret` / `apiKey` fields anywhere in the log
- * tree.
- *
- * Hosts that need NO redaction (test fixtures, security audits) opt out
- * with `logger: { redact: [] }`. Hosts that need MORE redaction supply
- * their own `redact` and arc steps aside — this default never overrides
- * an explicit setting.
+ * Default pino redact paths (auth/cookie/API-key headers, nested
+ * password/token/secret fields), applied only when the host supplies no
+ * `logger.redact`. Opt out with `logger: { redact: [] }`; an explicit
+ * `redact` always wins.
  */
 declare const DEFAULT_LOGGER_REDACT_PATHS: readonly ["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"]', "*.password", "*.passwordHash", "*.token", "*.accessToken", "*.refreshToken", "*.secret", "*.apiKey"];
 /**
@@ -111,6 +103,29 @@ interface FetchHandlerOptions {
  */
 declare function toFetchHandler(app: FastifyInstance, options?: FetchHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
+//#region src/factory/preloadResources.d.ts
+/** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
+type EagerGlobResult = Record<string, unknown>;
+/** Lazy glob result: `{ '/path/to/file.ts': () => Promise<unknown> }` */
+type LazyGlobResult = Record<string, () => Promise<unknown>>;
+/**
+ * Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
+ *
+ * Accepts either:
+ * - `{ import: 'default' }` form: values are the resource directly
+ * - default form: values are the full module — picks first export with `toPlugin()`
+ *
+ * Throws if any module doesn't yield a valid `ResourceLike`.
+ */
+declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
+/**
+ * Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
+ *
+ * Use this when resources depend on prior bootstrap (e.g., engine init) and
+ * cannot be evaluated at import time of the preload file.
+ */
+declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
+//#endregion
 //#region src/factory/presets.d.ts
 /**
  * Production preset - strict security, performance optimized
@@ -152,4 +167,4 @@ declare const testingPreset: Partial<CreateAppOptions>;
 declare const edgePreset: Partial<CreateAppOptions>;
 declare function getPreset(name: "production" | "development" | "testing" | "edge" | "worker"): Partial<CreateAppOptions>;
 //#endregion
-export { ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcWorker, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CreateWorkerOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, DEFAULT_LOGGER_REDACT_PATHS, type EventHandlerDefinition, type FetchHandlerOptions, type JwtAuthOption, type LoadResourcesOptions, type ModuleContribution, type ModuleDisposer, type ModuleExtension, type ModuleSetupContext, type ModuleState, type MultipartOptions, type RawBodyOptions, type ResolvedModuleDescriptor, type ResolvedModuleLifecycle, type ResolvedResourceDescriptor, type ResourceLike, type ResourceModule, type UnderPressureOptions, type WorkerHealthOptions, collectModuleHealthChecks, collectModuleScheduledJobs, collectModuleWorkflows, createApp, createWorker, defineModule, describeResolvedModule, developmentPreset, edgePreset, extendModule, getModuleExports, getModuleState, getOptionalModuleExports, getPreset, hasModule, hasModuleExports, lazyModuleExports, lazyRequiredModuleExports, loadResources, orderModules, preloadResources, preloadResourcesAsync, productionPreset, resolveContribution, resolveModule, subscribeModuleEventHandlers, testingPreset, toFetchHandler };
+export { type ArcCompositionConfig, ArcFactory, type ArcModule, type ArcModuleInput, type ArcModuleRegistry, type ArcPortRegistry, type ArcPorts, type ArcWorker, type AsyncApiCatalogEntry, type AsyncApiInfo, type AuthOption, type BetterAuthOption, type BootDisposer, type ClosureNode, type CompositionProblem, type CreateAppOptions, type CreateWorkerOptions, type CrudSurface, type CustomAuthenticatorOption, type CustomPluginAuthOption, DEFAULT_LOGGER_REDACT_PATHS, type DerivedPublishes, type DurabilityFacts, type EagerGlobResult, type EventHandlerDefinition, type FetchHandlerOptions, type HandlerDurabilityFact, type JwtAuthOption, type LazyBridge, type LazyGlobResult, type LoadResourcesOptions, type ModuleContribution, type ModuleDisposer, type ModuleExtension, type ModuleGraph, type ModuleGraphAnalysis, type ModuleGraphIssue, type ModuleGraphMode, type ModuleGraphNode, type ModuleGraphOptions, type ModuleKind, type ModuleName, type ModulePlan, type ModulePorts, type ModuleRequirements, type ModuleSetupContext, type ModuleState, type MultipartOptions, type PlanModulesOptions, type PortName, type RawBodyOptions, type RelayNudge, type RelayOption, type ResolvedModuleDescriptor, type ResolvedModuleLifecycle, type ResolvedResourceDescriptor, type ResourceLike, type ResourceModule, type SkippedBridge, type UnderPressureOptions, type WorkerHealthOptions, activateBridges, analyzeModuleGraph, assertComposable, buildModuleGraph, collectModuleWorkflows, compositionProblems, createApp, createRelayNudge, createWorker, crudEventsOf, defineModule, dependentsOf, developmentPreset, edgePreset, eventTopology, extendModule, getModuleExports, getModuleResources, getModuleState, getOptionalModuleExports, getPreset, hasModule, hasModuleExports, lazyModuleExports, lazyRequiredModuleExports, loadResources, orderModules, planModules, preloadResources, preloadResourcesAsync, productionPreset, renderModuleGraph, resolveContribution, resolveModule, resolveModuleClosure, subscribeModuleEventHandlers, testingPreset, toAsyncApi, toFetchHandler, verifyEventDurability, verifyModuleGraph, withRelayNudge };