@classytic/arc 2.41.1 → 2.44.0

package/dist/{eventPlugin-zZY-unhr.mjs → eventPlugin-BweHAVws.mjs}

@@ -1,11 +1,14 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { d as createDomainError } from "./errors-BH7YU_9O.mjs";
-import { n as requestContext } from "./requestContext-cDkAUr-P.mjs";
-import { n as MemoryEventTransport, r as createEvent, t as ARC_EVENT_TRANSPORT } from "./EventTransport-DSqD_Xsg.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { t as arcLog } from "./logger-D4V1zGLI.mjs";
+import { d as createDomainError } from "./errors-CW4anJBy.mjs";
+import { n as requestContext } from "./requestContext-C10UeFe5.mjs";
+import { i as runAdmittedWork, n as isAdmittedWork, r as registerShutdownParticipant } from "./shutdown-LpLMH8T1.mjs";
+import { n as MemoryEventTransport, r as createEvent, t as ARC_EVENT_TRANSPORT } from "./EventTransport-DZWDsaPa.mjs";
+import { n as preserveSubscriberIdentity } from "./subscriberIdentity-DeyppIif.mjs";
 import { isProductionEnv } from "@classytic/primitives/environment";
 import fp from "fastify-plugin";
+import { NonDurablePublishError } from "@classytic/primitives/durable-events";
 //#region src/events/retry.ts
 /**
 * Wrap an event handler with retry logic and dead letter support.
@@ -21,7 +24,7 @@ import fp from "fastify-plugin";
 function withRetry(handler, options = {}) {
 	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, transport, deadLetter, onDead, dlqFailureMode = "rethrow", name, logger = console } = options;
 	const label = name ?? handler.name ?? "anonymous";
-	return async (event) => {
+	return preserveSubscriberIdentity(handler, async (event) => {
 		const errors = [];
 		let firstFailedAt;
 		let lastFailedAt;
@@ -76,8 +79,9 @@ function withRetry(handler, options = {}) {
 		} catch (dlqErr) {
 			logger.error("[Arc Events] onDead observability callback failed:", dlqErr);
 		}
+		if (!transport?.deadLetter && !deadLetter && dlqFailureMode === "rethrow") throw new Error(`[Arc Events] Handler '${label}' exhausted retries for ${event.type} and no dead-letter sink is wired — rethrowing so the delivery stays owed (the outbox relay retries and dead-letters it) instead of acknowledging a lost event. Set dlqFailureMode: 'log-and-drop' on a handler whose loss is acceptable.`, { cause: errors[errors.length - 1] });
 		if (dlqPersistError && dlqFailureMode === "rethrow") throw new Error(`[Arc Events] Handler '${label}' exhausted retries for ${event.type} AND dead-letter persistence failed — rethrowing so the transport redelivers instead of acknowledging a lost event (set dlqFailureMode: 'log-and-drop' to accept loss).`, { cause: dlqPersistError });
-	};
+	});
 }
 /**
 * Create a dead letter publisher that sends failed events to a `$deadLetter` channel.
@@ -134,8 +138,23 @@ function sleep(ms) {
 */
 var eventPlugin_exports = /* @__PURE__ */ __exportAll({
 	default: () => eventPlugin_default,
+	emitObserved: () => emitObserved,
 	eventPlugin: () => eventPlugin
 });
+const OBSERVERS = Symbol.for("arc.events.observers");
+/** Notify `fastify.events.observe` listeners. Internal: the plugin and the outbox relay call it. */
+function emitObserved(events, event) {
+	const listeners = events?.[OBSERVERS];
+	if (!listeners) return;
+	for (const listener of listeners) try {
+		listener(event);
+	} catch {}
+}
+/** A consumer that can register subscriptions now and start consuming later (`RedisStreamTransport`). */
+function isHoldable(transport) {
+	const t = transport;
+	return typeof t.hold === "function" && typeof t.start === "function";
+}
 const eventPlugin = async (fastify, opts = {}) => {
 	/**
 	* Lifecycle ownership: arc closes ONLY the transport it built.
@@ -148,6 +167,18 @@ const eventPlugin = async (fastify, opts = {}) => {
 	*/
 	const ownsTransport = opts.transport === void 0;
 	const { transport = new MemoryEventTransport(opts.memoryTransport), singleProcess = false, logEvents = false, failOpen = true, retry: retryOpts, deadLetterQueue: dlqOpts, wal, onPublish, onPublishError, registry, validateMode: rawValidateMode, warnOnDuplicate: rawWarnOnDuplicate } = opts;
+	/** A host telemetry callback — isolated like an observer, so it can never change delivery. */
+	const notify = (hook, run, eventType) => {
+		try {
+			run();
+		} catch (error) {
+			fastify.log?.warn?.({
+				hook,
+				eventType,
+				error
+			}, "[Arc Events] publish telemetry callback threw — ignored");
+		}
+	};
 	const validateMode = rawValidateMode ?? (registry ? "warn" : "off");
 	const warnOnDuplicate = rawWarnOnDuplicate ?? !isProductionEnv(process.env.NODE_ENV);
 	const DUP_WINDOW_MS = 5e3;
@@ -159,7 +190,27 @@ const eventPlugin = async (fastify, opts = {}) => {
 			recentPublishes.delete(key);
 		}
 	};
+	const observers = /* @__PURE__ */ new Set();
+	const activeHandlers = /* @__PURE__ */ new Set();
+	let stopping = false;
+	registerShutdownParticipant(fastify, {
+		name: "events.handlers",
+		kind: "consumer",
+		stop: () => {
+			stopping = true;
+		},
+		drain: async () => {
+			while (activeHandlers.size) await Promise.allSettled([...activeHandlers]);
+		}
+	});
 	fastify.decorate("events", {
+		[OBSERVERS]: observers,
+		observe: (listener) => {
+			observers.add(listener);
+			return () => {
+				observers.delete(listener);
+			};
+		},
 		publish: async (type, payload, meta) => {
 			if (!type || typeof type !== "string") throw new Error("[Arc Events] Event type must be a non-empty string");
 			if (type.startsWith("$") && type !== "$deadLetter") throw new Error(`[Arc Events] Event type '${type}' uses reserved '$' prefix`);
@@ -170,6 +221,7 @@ const eventPlugin = async (fastify, opts = {}) => {
 				...meta
 			};
 			const event = createEvent(type, payload, enrichedMeta);
+			if (registry?.get(type, event.meta.schemaVersion)?.durability === "durable") throw new NonDurablePublishError(type, "fastify.events writes no outbox row — save it in the unit of work that made it true (dispatchDomainEvent, or outbox.save in the session)");
 			if (warnOnDuplicate && event.meta.correlationId) {
 				const now = Date.now();
 				evictExpiredPublishes(now);
@@ -200,16 +252,18 @@ const eventPlugin = async (fastify, opts = {}) => {
 				if (wal && !isInternalEvent) await wal.save(event);
 				await transport.publish(event);
 				if (wal?.acknowledge && !isInternalEvent) await wal.acknowledge(event.meta.id);
-				onPublish?.(event);
 			} catch (error) {
 				fastify.log?.error?.({
 					transport: transport.name,
 					eventType: type,
 					error
 				}, "[Arc Events] Failed to publish event");
-				onPublishError?.(event, error);
+				notify("onPublishError", () => onPublishError?.(event, error), type);
 				if (!failOpen) throw error;
+				return;
 			}
+			notify("onPublish", () => onPublish?.(event), type);
+			emitObserved(fastify.events, event);
 		},
 		subscribe: async (pattern, handler) => {
 			let wrappedHandler = handler;
@@ -222,17 +276,18 @@ const eventPlugin = async (fastify, opts = {}) => {
 				pattern,
 				retry: !!retryOpts
 			}, "Subscribing to events");
-			if (typeof transport.subscribe !== "function") {
-				const error = /* @__PURE__ */ new Error(`[Arc Events] transport '${transport.name}' is publish-only (no subscribe) — cannot register a handler for '${pattern}'. Use MemoryEventTransport / RedisEventTransport, or a transport that implements subscribe().`);
-				fastify.log?.error?.({
-					transport: transport.name,
-					pattern
-				}, error.message);
-				if (!failOpen) throw error;
-				return () => {};
-			}
+			if (typeof transport.subscribe !== "function") throw new Error(`[Arc Events] transport '${transport.name}' is publish-only (no subscribe) — cannot register a handler for '${pattern}'. Use MemoryEventTransport / RedisEventTransport, or a transport that implements subscribe().`);
 			try {
-				return await transport.subscribe(pattern, wrappedHandler);
+				const dispatch = wrappedHandler;
+				const tracked = (event) => {
+					if (stopping && !isAdmittedWork()) return Promise.reject(/* @__PURE__ */ new Error("[Arc Events] consumer is shutting down"));
+					const pending = runAdmittedWork(() => dispatch(event));
+					activeHandlers.add(pending);
+					return pending.finally(() => {
+						activeHandlers.delete(pending);
+					});
+				};
+				return await transport.subscribe(pattern, preserveSubscriberIdentity(handler, tracked));
 			} catch (error) {
 				fastify.log?.error?.({
 					transport: transport.name,
@@ -270,6 +325,12 @@ const eventPlugin = async (fastify, opts = {}) => {
 	* if a host's graph ends up with two arc copies.
 	*/
 	fastify.decorate(ARC_EVENT_TRANSPORT, transport);
+	if (isHoldable(transport)) {
+		transport.hold();
+		fastify.addHook("onReady", async () => {
+			await transport.start();
+		});
+	}
 	fastify.addHook("onClose", async () => {
 		if (!ownsTransport) return;
 		try {
@@ -295,4 +356,4 @@ var eventPlugin_default = fp(eventPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { withRetry as i, eventPlugin_exports as n, createDeadLetterPublisher as r, eventPlugin as t };
+export { withRetry as a, createDeadLetterPublisher as i, eventPlugin as n, eventPlugin_exports as r, emitObserved as t };

package/dist/{subscribe-helpers-DatDkcuG.mjs → eventTypes-N4-omQFR.mjs}

@@ -1,5 +1,7 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { r as createEvent } from "./EventTransport-DSqD_Xsg.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as createEvent } from "./EventTransport-DZWDsaPa.mjs";
+import { createRequire } from "node:module";
+import { durableEventMeta } from "@classytic/primitives/durable-events";
 //#region src/events/defineEvent.ts
 /**
 * Typed event declarations, a registry for introspection, and `.create()` to
@@ -24,25 +26,30 @@ import { r as createEvent } from "./EventTransport-DSqD_Xsg.mjs";
 * await fastify.events.publish(event.type, event.payload, event.meta);
 * ```
 */
-/**
-* Define a typed event with optional schema validation.
-*
-* @example
-* const OrderCreated = defineEvent({
-*   name: 'order.created',
-*   schema: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
-* });
-*
-* const event = OrderCreated.create({ orderId: '123' });
-*/
 function defineEvent(input) {
-	const { name, schema, version = 1, description } = input;
+	const { name, payload, version = 1, description } = input;
+	const durable = input.durability === "durable" ? input : void 0;
+	if (durable && typeof durable.occurrence !== "function") throw new Error(`[arc] durable event "${name}" must declare \`occurrence(payload)\`.`);
+	if (payload && input.schema) throw new Error(`[arc] event "${name}" declares both \`payload\` and \`schema\` — declare the payload once.`);
 	return {
 		name,
-		schema,
+		schema: payload ? payloadToJsonSchema(name, payload) : input.schema,
+		...payload ? { payloadSchema: payload } : {},
 		version,
 		description,
+		...input.durability !== void 0 ? { durability: input.durability } : {},
+		...durable ? { occurrence: (p) => durable.occurrence(p) } : {},
+		...durable?.produces ? { produces: durable.produces } : {},
 		create(payload, meta) {
+			if (durable) {
+				const fixed = durableEventMeta(name, version, durable.occurrence(payload));
+				if (meta?.id !== void 0 && meta.id !== fixed.id) throw new Error(`[arc] durable event "${name}": meta.id "${meta.id}" contradicts its occurrence id "${fixed.id}".`);
+				return createEvent(name, payload, {
+					schemaVersion: version,
+					...meta,
+					...fixed
+				});
+			}
 			return createEvent(name, payload, {
 				schemaVersion: version,
 				...meta
@@ -51,6 +58,24 @@ function defineEvent(input) {
 	};
 }
 /**
+* The payload's JSON Schema, via zod's own converter — loaded only here, so an app that never
+* declares a zod payload never loads zod. A payload JSON cannot carry fails AT DEFINITION.
+*/
+function payloadToJsonSchema(name, payload) {
+	let zod;
+	try {
+		zod = createRequire(import.meta.url)("zod");
+	} catch {
+		throw new Error(`[arc] event "${name}" declares a zod \`payload\` but zod is not installed.`);
+	}
+	if (typeof zod.toJSONSchema !== "function") throw new Error(`[arc] event "${name}": \`payload\` needs zod v4 (\`z.toJSONSchema\`).`);
+	try {
+		return zod.toJSONSchema(payload);
+	} catch (err) {
+		throw new Error(`[arc] event "${name}": its payload cannot travel as JSON — ${err.message}. An event crosses a transport as JSON: send dates as ISO strings (\`z.string()\`).`);
+	}
+}
+/**
 * Create an event registry for cataloging and validating events.
 *
 * The registry is opt-in — unregistered events pass validation.
@@ -87,7 +112,8 @@ function createEventRegistry(options) {
 				name: def.name,
 				version: def.version,
 				description: def.description,
-				schema: def.schema
+				schema: def.schema,
+				...def.durability !== void 0 ? { durability: def.durability } : {}
 			}));
 		},
 		validate(name, payload, version) {
@@ -100,6 +126,13 @@ function createEventRegistry(options) {
 				}
 			}
 			if (!target) return { valid: true };
+			if (target.payloadSchema) {
+				const parsed = target.payloadSchema.safeParse(payload);
+				return parsed.success ? { valid: true } : {
+					valid: false,
+					errors: (parsed.error?.issues ?? []).map((i) => `${i.path.map(String).join(".") || "(payload)"}: ${i.message}`)
+				};
+			}
 			if (!target.schema) return { valid: true };
 			return customValidator ? customValidator(target.schema, payload) : validatePayload(payload, target.schema);
 		}
@@ -258,6 +291,29 @@ async function subscribeWithSchema(fastify, definition, handler, options) {
 	return fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options));
 }
 /**
+* Wrap a handler so anything it throws names it: `[<name>] <message>`, the original as `cause`
+* and its string `code` kept. A transport's aggregate error — and so an outbox row's `lastError`
+* — then says WHICH subscriber failed. A message already carrying the label is left as is.
+*/
+function wrapWithAttribution(handler, name) {
+	const label = `[${name}]`;
+	return async (event) => {
+		try {
+			await handler(event);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (message.startsWith(label)) throw err;
+			const attributed = new Error(`${label} ${message}`, { cause: err });
+			if (err instanceof Error) {
+				attributed.name = err.name;
+				const code = Reflect.get(err, "code");
+				if (typeof code === "string") Reflect.set(attributed, "code", code);
+			}
+			throw attributed;
+		}
+	};
+}
+/**
 * Pure handler wrapper — returns a new `EventHandler` that catches handler
 * exceptions and routes them to `onError` (or logs and swallows). For
 * projection / cache-invalidation / fire-and-forget handlers where retry
@@ -309,4 +365,82 @@ async function subscribeWithBoundary(fastify, pattern, handler, options) {
 	return fastify.events.subscribe(pattern, wrapWithBoundary(handler, options));
 }
 //#endregion
-export { createEventRegistry as a, wrapWithSchema as i, subscribeWithSchema as n, defineEvent as o, wrapWithBoundary as r, subscribeWithBoundary as t };
+//#region src/events/eventTypes.ts
+/**
+* Event Type Constants and Helpers
+*
+* Provides well-typed event names for CRUD operations and lifecycle events.
+* Use these instead of hand-typing event strings to prevent typos.
+*
+* @example
+* ```typescript
+* import { crudEventType, ARC_LIFECYCLE_EVENTS } from '@classytic/arc/events';
+*
+* // Subscribe to product creation events
+* events.subscribe(crudEventType('product', 'created'), handler);
+*
+* // Subscribe to Arc lifecycle events
+* events.subscribe(ARC_LIFECYCLE_EVENTS.READY, handler);
+* ```
+*/
+/** Suffixes for auto-emitted CRUD events */
+const CRUD_EVENT_SUFFIXES = Object.freeze([
+	"created",
+	"updated",
+	"deleted"
+]);
+/**
+* Build a CRUD event type string.
+*
+* @example
+* ```typescript
+* crudEventType('product', 'created')  // 'product.created'
+* crudEventType('order', 'deleted')    // 'order.deleted'
+* ```
+*/
+function crudEventType(resource, suffix) {
+	return `${resource}.${suffix}`;
+}
+/** Arc framework lifecycle events — emitted automatically by the framework */
+const ARC_LIFECYCLE_EVENTS = Object.freeze({
+	/** Emitted when a resource plugin is registered */
+	RESOURCE_REGISTERED: "arc.resource.registered",
+	/** Emitted when Arc is fully ready (all resources registered, onReady fired) */
+	READY: "arc.ready"
+});
+/** Cache-specific event types for observability and external triggers */
+const CACHE_EVENTS = Object.freeze({
+	/** Emitted when a resource's cache version is bumped */
+	VERSION_BUMPED: "arc.cache.version.bumped",
+	/** Emitted when a tag version is bumped */
+	TAG_VERSION_BUMPED: "arc.cache.tag.bumped"
+});
+/**
+* The payload arc publishes for every auto-CRUD event (`<resource>.created|updated|deleted`).
+* `data` is the resource document as the route returned it.
+*/
+const CRUD_EVENT_SCHEMA = Object.freeze({
+	type: "object",
+	properties: {
+		resource: { type: "string" },
+		operation: {
+			type: "string",
+			enum: [
+				"create",
+				"update",
+				"delete"
+			]
+		},
+		data: {},
+		userId: {},
+		organizationId: { type: "string" },
+		timestamp: { type: "string" }
+	},
+	required: [
+		"resource",
+		"operation",
+		"timestamp"
+	]
+});
+//#endregion
+export { crudEventType as a, wrapWithAttribution as c, createEventRegistry as d, defineEvent as f, CRUD_EVENT_SUFFIXES as i, wrapWithBoundary as l, CACHE_EVENTS as n, subscribeWithBoundary as o, CRUD_EVENT_SCHEMA as r, subscribeWithSchema as s, ARC_LIFECYCLE_EVENTS as t, wrapWithSchema as u };

package/dist/events/index.d.mts

@@ -1,9 +1,10 @@
 
-import { i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions } from "../EventTransport-CbUKDzZZ.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-B52abJ8W.mjs";
-import { a as EventOutbox, c as OutboxRelayErrorKind, i as MemoryOutboxStore, l as RelayResult, n as OutboxModuleOptions, o as EventOutboxOptions, r as createOutboxModule, s as OutboxRelayErrorHandler, t as OutboxModuleExports } from "../outbox-module-BHdUnuuK.mjs";
+import { i as EventLogger, n as DomainEvent, o as MemoryEventTransport, r as EventHandler, s as MemoryEventTransportOptions } from "../EventTransport-CiicKz2Z.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-BtmA4-3P.mjs";
+import { a as MemoryOutboxStore, c as OutboxRelayErrorHandler, d as DEFAULT_RELAY_LAG_UNHEALTHY_MS, f as OutboxHealth, i as createOutboxModule, l as OutboxRelayErrorKind, m as readOutboxHealth, n as OutboxModuleExports, o as EventOutbox, p as OutboxHealthStore, r as OutboxModuleOptions, s as EventOutboxOptions, t as OutboxDrainResult, u as RelayResult } from "../outbox-module-gZCHoE4H.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-BPKscsTB.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-BMk-bpQS.mjs";
+import { IdempotencyClaimStore } from "@classytic/repo-core/idempotency";
 import { OutboxStore } from "@classytic/primitives/outbox";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/events/eventTypes.d.ts
@@ -25,7 +26,7 @@ import { RepositoryLike } from "@classytic/repo-core/adapter";
  * ```
  */
 /** Suffixes for auto-emitted CRUD events */
-declare const CRUD_EVENT_SUFFIXES: readonly ["created", "updated", "deleted"];
+export declare const CRUD_EVENT_SUFFIXES: readonly ["created", "updated", "deleted"];
 /** Type for CRUD event suffixes */
 type CrudEventSuffix = (typeof CRUD_EVENT_SUFFIXES)[number];
 /**
@@ -37,9 +38,9 @@ type CrudEventSuffix = (typeof CRUD_EVENT_SUFFIXES)[number];
  * crudEventType('order', 'deleted')    // 'order.deleted'
  * ```
  */
-declare function crudEventType(resource: string, suffix: CrudEventSuffix): string;
+export declare function crudEventType(resource: string, suffix: CrudEventSuffix): string;
 /** Arc framework lifecycle events — emitted automatically by the framework */
-declare const ARC_LIFECYCLE_EVENTS: Readonly<{
+export declare const ARC_LIFECYCLE_EVENTS: Readonly<{
   /** Emitted when a resource plugin is registered */
   readonly RESOURCE_REGISTERED: "arc.resource.registered";
   /** Emitted when Arc is fully ready (all resources registered, onReady fired) */
@@ -48,7 +49,7 @@ declare const ARC_LIFECYCLE_EVENTS: Readonly<{
 /** Type for Arc lifecycle event names */
 type ArcLifecycleEvent = (typeof ARC_LIFECYCLE_EVENTS)[keyof typeof ARC_LIFECYCLE_EVENTS];
 /** Cache-specific event types for observability and external triggers */
-declare const CACHE_EVENTS: Readonly<{
+export declare const CACHE_EVENTS: Readonly<{
   /** Emitted when a resource's cache version is bumped */
   readonly VERSION_BUMPED: "arc.cache.version.bumped";
   /** Emitted when a tag version is bumped */
@@ -57,6 +58,26 @@ declare const CACHE_EVENTS: Readonly<{
 /** Type for cache event names */
 type CacheEvent = (typeof CACHE_EVENTS)[keyof typeof CACHE_EVENTS];
 //#endregion
+//#region src/events/inbox.d.ts
+interface InboxOptions {
+  /** The claims store — ONE per deployment, shared with command idempotency. */
+  readonly store: IdempotencyClaimStore;
+  /** Must exceed the handler's worst-case run time. Default: the store's lease default. */
+  readonly leaseMs?: number;
+  /** Commit or roll back ALL work, including claim completion; external effects need their own key. */
+  readonly transaction?: <T>(work: (session: unknown) => Promise<T>) => Promise<T>;
+}
+interface InboxHandlerContext {
+  /** Use this session on every database write when a transaction is configured. */
+  readonly session?: unknown;
+  /** Stable effect deduplication key for external calls or nontransactional handlers. */
+  readonly eventId: string;
+}
+type InboxHandler<T> = (event: DomainEvent<T>, context: InboxHandlerContext) => Promise<void>;
+/** The claim operation every inbox row is filed under. */
+export declare const EVENT_INBOX_OPERATION = "event-inbox";
+export declare function withInbox<T = unknown>(name: string, handler: InboxHandler<T>, options: InboxOptions): EventHandler<T>;
+//#endregion
 //#region src/events/outbox/backoff.d.ts
 /**
  * Exponential backoff for outbox failure policies — pure date math shared
@@ -107,13 +128,13 @@ interface ExponentialBackoffOptions {
  * @example Tuning for a faster transport
  * ```typescript
  * exponentialBackoff({ attempt: 3, baseMs: 250, maxMs: 10_000, jitter: 0.3 });
- * // attempt=1 → ~250ms   ±30%
- * // attempt=2 → ~500ms   ±30%
- * // attempt=3 → ~1000ms  ±30%
+ * // attempt=1 → 250–325ms   (+0–30%: jitter only ever DELAYS, never schedules early)
+ * // attempt=2 → 500–650ms
+ * // attempt=3 → 1000–1300ms
  * // attempt=10 → capped at 10_000ms
  * ```
  */
-declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
+export declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
 //#endregion
 //#region src/events/repository-outbox-adapter.d.ts
 interface RepositoryOutboxStoreOptions {
@@ -143,7 +164,7 @@ interface RepositoryOutboxStoreOptions {
  * quietly does nothing and reports success.
  */
 type RepositoryOutboxStore = OutboxStore & Required<Pick<OutboxStore, "fail" | "getDeadLettered" | "purge" | "requeue" | "countByStatus" | "oldestPendingAgeMs">>;
-declare function repositoryAsOutboxStore(repository: RepositoryLike, options?: RepositoryOutboxStoreOptions): RepositoryOutboxStore;
+export declare function repositoryAsOutboxStore(repository: RepositoryLike, options?: RepositoryOutboxStoreOptions): RepositoryOutboxStore;
 //#endregion
 //#region src/events/subscribe-helpers.d.ts
 /**
@@ -223,7 +244,7 @@ interface WrapWithSchemaOptions<_T> {
  * );
  * ```
  */
-declare function wrapWithSchema<T>(definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): EventHandler<unknown>;
+export declare function wrapWithSchema<T>(definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): EventHandler<unknown>;
 /**
  * Convenience: validate + subscribe in one call. Equivalent to
  * `fastify.events.subscribe(definition.name, wrapWithSchema(definition, handler, options))`.
@@ -245,7 +266,7 @@ declare function wrapWithSchema<T>(definition: EventDefinitionOutput<T>, handler
  * );
  * ```
  */
-declare function subscribeWithSchema<T>(fastify: FastifyEventBus, definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): Promise<() => void>;
+export declare function subscribeWithSchema<T>(fastify: FastifyEventBus, definition: EventDefinitionOutput<T>, handler: EventHandler<T>, options?: WrapWithSchemaOptions<T>): Promise<() => void>;
 interface WrapWithBoundaryOptions {
   /**
    * Called when the handler throws. Default behaviour: log the error with
@@ -285,14 +306,14 @@ interface WrapWithBoundaryOptions {
  * );
  * ```
  */
-declare function wrapWithBoundary(handler: EventHandler, options?: WrapWithBoundaryOptions): EventHandler;
+export declare function wrapWithBoundary(handler: EventHandler, options?: WrapWithBoundaryOptions): EventHandler;
 /**
  * Convenience: subscribe + error-boundary in one call. Equivalent to
  * `fastify.events.subscribe(pattern, wrapWithBoundary(handler, options))`.
  *
  * Returns the unsubscribe function from the underlying transport.
  */
-declare function subscribeWithBoundary(fastify: FastifyEventBus, pattern: string, handler: EventHandler, options?: WrapWithBoundaryOptions): Promise<() => void>;
+export declare function subscribeWithBoundary(fastify: FastifyEventBus, pattern: string, handler: EventHandler, options?: WrapWithBoundaryOptions): Promise<() => void>;
 /**
  * Structural type — accepts anything with the `events.subscribe` method,
  * including `FastifyInstance` (declaration-merged in `eventPlugin.ts`) and
@@ -304,4 +325,8 @@ interface FastifyEventBus {
   };
 }
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type EventDefinitionInput, type EventDefinitionOutput, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type ExponentialBackoffOptions, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxModuleExports, type OutboxModuleOptions, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RepositoryOutboxStore, type RepositoryOutboxStoreOptions, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, createOutboxModule, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };
+//#region src/events/subscriberIdentity.d.ts
+/** Assign a deployment-stable identity for durable per-handler progress; never use an index. */
+export declare function withSubscriberId<T>(id: string, handler: EventHandler<T>): EventHandler<T>;
+//#endregion
+export { type ArcLifecycleEvent, type CacheEvent, type CrudEventSuffix, type CustomValidator, DEFAULT_RELAY_LAG_UNHEALTHY_MS, type EventDefinitionInput, type EventDefinitionOutput, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type ExponentialBackoffOptions, type FastifyEventBus, type InboxHandler, type InboxHandlerContext, type InboxOptions, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxDrainResult, type OutboxHealth, type OutboxHealthStore, type OutboxModuleExports, type OutboxModuleOptions, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type PayloadOf, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RepositoryOutboxStore, type RepositoryOutboxStoreOptions, type RetryOptions, type ValidationResult, type WrapWithBoundaryOptions, type WrapWithSchemaOptions, createDeadLetterPublisher, createEventRegistry, createOutboxModule, defineEvent, eventPlugin, readOutboxHealth, withRetry };

package/dist/events/index.mjs

@@ -1,58 +1,54 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as MemoryEventTransport } from "../EventTransport-DSqD_Xsg.mjs";
-import { a as createEventRegistry, i as wrapWithSchema, n as subscribeWithSchema, o as defineEvent, r as wrapWithBoundary, t as subscribeWithBoundary } from "../subscribe-helpers-DatDkcuG.mjs";
-import { i as withRetry, r as createDeadLetterPublisher, t as eventPlugin } from "../eventPlugin-zZY-unhr.mjs";
-import { i as exponentialBackoff, n as EventOutbox, r as repositoryAsOutboxStore, t as createOutboxModule } from "../outbox-module-D2z5WkDY.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { n as MemoryEventTransport } from "../EventTransport-DZWDsaPa.mjs";
+import { a as crudEventType, d as createEventRegistry, f as defineEvent, i as CRUD_EVENT_SUFFIXES, l as wrapWithBoundary, n as CACHE_EVENTS, o as subscribeWithBoundary, s as subscribeWithSchema, t as ARC_LIFECYCLE_EVENTS, u as wrapWithSchema } from "../eventTypes-N4-omQFR.mjs";
+import { r as withSubscriberId } from "../subscriberIdentity-DeyppIif.mjs";
+import { a as withRetry, i as createDeadLetterPublisher, n as eventPlugin } from "../eventPlugin-BweHAVws.mjs";
+import { r as readOutboxHealth, t as DEFAULT_RELAY_LAG_UNHEALTHY_MS } from "../health-BYAwA6YS.mjs";
+import { i as exponentialBackoff, n as EventOutbox, r as repositoryAsOutboxStore, t as createOutboxModule } from "../outbox-module-Ryk270jd.mjs";
+import { fingerprintRequest, runIdempotent } from "@classytic/repo-core/idempotency";
 import { MemoryOutboxStore } from "@classytic/primitives/memory-outbox";
-//#region src/events/eventTypes.ts
+//#region src/events/inbox.ts
 /**
-* Event Type Constants and Helpers
-*
-* Provides well-typed event names for CRUD operations and lifecycle events.
-* Use these instead of hand-typing event strings to prevent typos.
-*
-* @example
-* ```typescript
-* import { crudEventType, ARC_LIFECYCLE_EVENTS } from '@classytic/arc/events';
-*
-* // Subscribe to product creation events
-* events.subscribe(crudEventType('product', 'created'), handler);
-*
-* // Subscribe to Arc lifecycle events
-* events.subscribe(ARC_LIFECYCLE_EVENTS.READY, handler);
-* ```
+* Per-handler completion deduplication. Without a shared transaction, a crash between an
+* effect and completion can repeat the effect: handlers must dedupe effects by event id.
+* With `transaction`, the handler's DB effect and claim completion share one session; the
+* host must provide a transaction-aware claim store on the SAME database connection.
 */
-/** Suffixes for auto-emitted CRUD events */
-const CRUD_EVENT_SUFFIXES = Object.freeze([
-	"created",
-	"updated",
-	"deleted"
-]);
-/**
-* Build a CRUD event type string.
-*
-* @example
-* ```typescript
-* crudEventType('product', 'created')  // 'product.created'
-* crudEventType('order', 'deleted')    // 'order.deleted'
-* ```
-*/
-function crudEventType(resource, suffix) {
-	return `${resource}.${suffix}`;
+/** The claim operation every inbox row is filed under. */
+const EVENT_INBOX_OPERATION = "event-inbox";
+function withInbox(name, handler, options) {
+	if (typeof name !== "string" || name.length === 0) throw new Error("[Arc Events] withInbox: a handler name is required — it is the inbox key.");
+	return withSubscriberId(name, async (event) => {
+		const execute = async (session) => {
+			const run = await runIdempotent({
+				store: options.store,
+				identity: {
+					operation: EVENT_INBOX_OPERATION,
+					key: `${name}:${event.meta.id}`
+				},
+				requestFingerprint: fingerprintRequest({
+					type: event.type,
+					payload: event.payload
+				}),
+				...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
+				...session !== void 0 ? { storeOptions: { session } } : {},
+				execute: async () => {
+					await handler(event, {
+						session,
+						eventId: event.meta.id
+					});
+					return true;
+				}
+			});
+			if (run.outcome === "in_flight") throw new Error(`[Arc Events] Handler '${name}' for ${event.type} ${event.meta.id} is in flight elsewhere — retry later.`);
+			if (run.outcome === "exhausted") throw new Error(`[Arc Events] Handler '${name}' for ${event.type} ${event.meta.id} exhausted its takeovers: ${run.lastError ?? "unknown"}.`);
+		};
+		if (options.transaction) await options.transaction(async (session) => {
+			if (session === void 0 || session === null) throw new Error("[Arc Events] Inbox transaction must provide a database session.");
+			await execute(session);
+		});
+		else await execute();
+	});
 }
-/** Arc framework lifecycle events — emitted automatically by the framework */
-const ARC_LIFECYCLE_EVENTS = Object.freeze({
-	/** Emitted when a resource plugin is registered */
-	RESOURCE_REGISTERED: "arc.resource.registered",
-	/** Emitted when Arc is fully ready (all resources registered, onReady fired) */
-	READY: "arc.ready"
-});
-/** Cache-specific event types for observability and external triggers */
-const CACHE_EVENTS = Object.freeze({
-	/** Emitted when a resource's cache version is bumped */
-	VERSION_BUMPED: "arc.cache.version.bumped",
-	/** Emitted when a tag version is bumped */
-	TAG_VERSION_BUMPED: "arc.cache.tag.bumped"
-});
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEventRegistry, createOutboxModule, crudEventType, defineEvent, eventPlugin, exponentialBackoff, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withRetry, wrapWithBoundary, wrapWithSchema };
+export { ARC_LIFECYCLE_EVENTS, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, DEFAULT_RELAY_LAG_UNHEALTHY_MS, EVENT_INBOX_OPERATION, EventOutbox, MemoryEventTransport, MemoryOutboxStore, createDeadLetterPublisher, createEventRegistry, createOutboxModule, crudEventType, defineEvent, eventPlugin, exponentialBackoff, readOutboxHealth, repositoryAsOutboxStore, subscribeWithBoundary, subscribeWithSchema, withInbox, withRetry, withSubscriberId, wrapWithBoundary, wrapWithSchema };