@venizia/ignis-kernel 0.2.0-8 → 0.2.0

package/dist/esm/base/events/common/types.d.ts

@@ -1,3 +1,5 @@
+import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
+import { EventHandlerTypes } from './constants.js';
 /** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */
 export interface IDomainEvent<TPayload = unknown> {
     name: string;
@@ -6,7 +8,41 @@ export interface IDomainEvent<TPayload = unknown> {
     traceId?: string;
 }
 /**
- * Handles one `IDomainEvent`.
+ * Per-registration retry override for `EventBus.register`. Both fields must be positive integers,
+ * and are bounded by `EventDispatchRetry.MAX_ATTEMPTS_CEILING` / `MAX_TOTAL_WINDOW_MS` - a value
+ * outside either throws at `register()`, never clamps.
+ */
+export interface IEventHandlerRetryOptions {
+    /** Default `EventDispatchRetry.MAX_ATTEMPTS`. */
+    maxAttempts?: number;
+    /** First backoff delay in ms; exponential growth is computed from it. Default `EventDispatchRetry.BASE_DELAY_MS`. */
+    baseDelayMs?: number;
+}
+/** A handler callback - synchronous or asynchronous, `EventBus` awaits either the same way. */
+export type TEventHandlerFunction<TPayload = unknown> = (opts: {
+    event: IDomainEvent<TPayload>;
+}) => ValueOrPromise<void>;
+/** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */
+export interface IEventHandlerBindingKeyReference {
+    type: typeof EventHandlerTypes.BINDING_KEY;
+    key: string;
+}
+/** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */
+export interface IEventHandlerFunctionReference<TPayload = unknown> {
+    type: typeof EventHandlerTypes.FUNCTION;
+    fn: TEventHandlerFunction<TPayload>;
+}
+/**
+ * The two shapes `EventBus.register`'s `handler` accepts, tagged by `type` so the caller states
+ * which rather than the bus inferring it from whichever field is present. Only `BINDING_KEY` shares
+ * `IEventHandler`'s rebind property; see its doc.
+ */
+export type TEventHandlerReference<TPayload = unknown> = IEventHandlerBindingKeyReference | IEventHandlerFunctionReference<TPayload>;
+/**
+ * Handles one `IDomainEvent`. Implemented by whatever is bound into the container under
+ * `register`'s `{ type: EventHandlerTypes.BINDING_KEY, key }` form - see `TEventHandlerReference`
+ * for the `FUNCTION` form, which does not implement this interface and does not share its rebind
+ * property.
  *
  * MUST be idempotent. The bus retries a failed handler, so delivery is at-least-once: one that
  * half-succeeds then throws runs again from the top, re-applying whatever already landed. Three
@@ -16,11 +52,13 @@ export interface IDomainEvent<TPayload = unknown> {
  * audit row, which simply gains a duplicate - corrupting the record used to diagnose the retry.
  *
  * Resolved from the container by binding key at dispatch time, never captured as a direct reference,
- * so rebinding the key takes effect on the next attempt - including one already in flight.
+ * so rebinding the key takes effect on the next attempt - including one already in flight. A
+ * `FUNCTION`-form handler does NOT have this property: `fn` is a captured closure, so every attempt
+ * in a long retry window calls the exact function registered at startup.
  */
 export interface IEventHandler<TEvent extends IDomainEvent = IDomainEvent> {
     handle(opts: {
         event: TEvent;
-    }): Promise<void>;
+    }): ValueOrPromise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/esm/base/events/common/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACvE,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,+FAA+F;AAC/F,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,qHAAqH;IACrH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+FAA+F;AAC/F,MAAM,MAAM,qBAAqB,CAAC,QAAQ,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE;IAC7D,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CAC/B,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;AAE3B,2GAA2G;AAC3G,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,OAAO,iBAAiB,CAAC,WAAW,CAAC;IAC3C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2HAA2H;AAC3H,MAAM,WAAW,8BAA8B,CAAC,QAAQ,GAAG,OAAO;IAChE,IAAI,EAAE,OAAO,iBAAiB,CAAC,QAAQ,CAAC;IACxC,EAAE,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,QAAQ,GAAG,OAAO,IACnD,gCAAgC,GAAG,8BAA8B,CAAC,QAAQ,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACvE,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;CACvD"}

package/dist/esm/base/events/event-bus.d.ts

@@ -1,21 +1,52 @@
 import type { Container } from '../../helpers/inversion/container.js';
 import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { IEventHandlerRetryOptions, TEventHandlerReference } from './common/types.js';
 /** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name
- * or payload shape is a compile error. Delivery is always async and retry is fixed - there is no
- * knob for either, so "published" guarantees the same thing at every call site. Retry makes delivery
- * at-least-once: handlers must be idempotent, see `IEventHandler`. */
+ * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the
+ * handler's own failure mode, not of the event, so `register` may tune it per registration. But
+ * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a
+ * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no
+ * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can
+ * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes
+ * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */
 export declare class EventBus<TPayloadMap extends object> extends BaseHelper {
     private readonly container;
     /** `register` appends, never replaces - two handlers may share an event name, and replacing would
      * drop the first with no way for the caller to notice. */
-    private readonly handlerBindingKeysByName;
+    private readonly registrationsByName;
     constructor(opts: {
         scope?: string;
         container: Container;
     });
+    /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -
+     * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */
+    private static computeTotalWindowMs;
+    /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is
+     * worse off than one who sees the ceiling at boot. */
+    private static assertValidRetry;
+    /**
+     * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.
+     * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads
+     * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is
+     * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,
+     * not which field happens to be present - see `EventHandlerTypes`' doc.
+     */
+    private static buildHandlerInvoker;
+    /**
+     * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the
+     * handler's own failure mode, and two handlers on the same event name may each pick their own.
+     * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the
+     * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either
+     * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.
+     */
     register<K extends keyof TPayloadMap & string>(opts: {
         name: K;
-        handlerBindingKey: string;
+        /** A `BINDING_KEY` reference re-resolves through the container on every retry attempt, so a
+         * rebind reaches a dispatch already in flight. A `FUNCTION` reference is captured as-is: a
+         * rebind has nothing to reach, and every attempt in a long retry window calls the exact `fn`
+         * registered here. */
+        handler: TEventHandlerReference<TPayloadMap[K]>;
+        retry?: IEventHandlerRetryOptions;
     }): void;
     /**
      * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via
@@ -28,9 +59,15 @@ export declare class EventBus<TPayloadMap extends object> extends BaseHelper {
         traceId?: string;
     }): void;
     /**
-     * Fixed 3 attempts / ~100ms exponential backoff, no jitter - see `EventDispatchRetry`. The
-     * handler is resolved fresh from the container on every attempt rather than once up front, so a
-     * rebind takes effect on the very next attempt of a dispatch already in flight.
+     * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),
+     * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,
+     * so many handlers retrying the same lock do not collide on the same instant a second and third
+     * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured
+     * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that
+     * throws synchronously is caught exactly like one that returns a rejected promise: `execution`
+     * here is itself `async`, and JS converts a synchronous throw inside an async function body into a
+     * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never
+     * sees the difference.
      *
      * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion
      * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone

package/dist/esm/base/events/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EACL,UAAU,EAKX,MAAM,6BAA6B,CAAC;AAKrC;;;sEAGsE;AACtE,qBAAa,QAAQ,CAAC,WAAW,SAAS,MAAM,CAAE,SAAQ,UAAU;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;8DAC0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAwB;gBAErD,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE;IAM1D,QAAQ,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QACnD,IAAI,EAAE,CAAC,CAAC;QACR,iBAAiB,EAAE,MAAM,CAAC;KAC3B,GAAG,IAAI;IAkBR;;;;OAIG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QAClD,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAiCR;;;;;;;;OAQG;YACW,QAAQ;CAmCvB"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,UAAU,EAKX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAGV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AAexB;;;;;;;+EAO+E;AAC/E,qBAAa,QAAQ,CAAC,WAAW,SAAS,MAAM,CAAE,SAAQ,UAAU;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;8DAC0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA4C;gBAEpE,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE;IAM1D;sGACkG;IAClG,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAkBnC;0DACsD;IACtD,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAiC/B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkDlC;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QACnD,IAAI,EAAE,CAAC,CAAC;QACR;;;8BAGsB;QACtB,OAAO,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,KAAK,CAAC,EAAE,yBAAyB,CAAC;KACnC,GAAG,IAAI;IAmCR;;;;OAIG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,EAAE;QAClD,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAiCR;;;;;;;;;;;;;;OAcG;YACW,QAAQ;CAmCvB"}

package/dist/esm/base/events/event-bus.js

@@ -1,29 +1,143 @@
+import { isEmpty } from '@venizia/ignis-helpers/common';
 import { BaseHelper, getError, RetryBackoffStrategies, RetryHelper, RetryJitterModes, } from '@venizia/ignis-helpers/core';
-import isEmpty from 'lodash/isEmpty';
-import { EventDispatchRetry } from './common/constants.js';
+import { EventDispatchRetry, EventHandlerTypes } from './common/constants.js';
 /** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name
- * or payload shape is a compile error. Delivery is always async and retry is fixed - there is no
- * knob for either, so "published" guarantees the same thing at every call site. Retry makes delivery
- * at-least-once: handlers must be idempotent, see `IEventHandler`. */
+ * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the
+ * handler's own failure mode, not of the event, so `register` may tune it per registration. But
+ * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a
+ * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no
+ * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can
+ * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes
+ * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */
 export class EventBus extends BaseHelper {
     constructor(opts) {
         super({ scope: opts.scope ?? EventBus.name });
         this.container = opts.container;
-        this.handlerBindingKeysByName = new Map();
+        this.registrationsByName = new Map();
     }
+    /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -
+     * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */
+    static computeTotalWindowMs(opts) {
+        const { maxAttempts, baseDelayMs } = opts;
+        let totalWindowMs = 0;
+        for (let attempt = 1; attempt < maxAttempts; attempt++) {
+            totalWindowMs += RetryHelper.computeBackoffDelayMs({
+                attempt,
+                backoff: {
+                    strategy: RetryBackoffStrategies.EXPONENTIAL,
+                    initialDelayMs: baseDelayMs,
+                    jitter: RetryJitterModes.NONE,
+                },
+            });
+        }
+        return totalWindowMs;
+    }
+    /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is
+     * worse off than one who sees the ceiling at boot. */
+    static assertValidRetry(opts) {
+        const { name, maxAttempts, baseDelayMs } = opts;
+        if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+            throw getError({
+                message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,
+            });
+        }
+        if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {
+            throw getError({
+                message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,
+            });
+        }
+        if (maxAttempts > EventDispatchRetry.MAX_ATTEMPTS_CEILING) {
+            throw getError({
+                message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,
+            });
+        }
+        const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });
+        if (totalWindowMs > EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {
+            throw getError({
+                message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,
+            });
+        }
+    }
+    /**
+     * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.
+     * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads
+     * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is
+     * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,
+     * not which field happens to be present - see `EventHandlerTypes`' doc.
+     */
+    static buildHandlerInvoker(opts) {
+        const { container, handler, name } = opts;
+        if (isEmpty({ value: handler })) {
+            throw getError({
+                message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,
+            });
+        }
+        switch (handler.type) {
+            case EventHandlerTypes.BINDING_KEY: {
+                const { key } = handler;
+                if (isEmpty({ value: key })) {
+                    throw getError({
+                        message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,
+                    });
+                }
+                return {
+                    invokeHandler: ({ event }) => container.get({ key }).handle({ event }),
+                    description: `binding-key:${key}`,
+                };
+            }
+            case EventHandlerTypes.FUNCTION: {
+                const { fn } = handler;
+                if (typeof fn !== 'function') {
+                    throw getError({
+                        message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,
+                    });
+                }
+                return {
+                    invokeHandler: ({ event }) => fn({ event }),
+                    description: `function:${fn.name || 'anonymous'}`,
+                };
+            }
+            default: {
+                throw getError({
+                    message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${handler.type}`,
+                });
+            }
+        }
+    }
+    /**
+     * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the
+     * handler's own failure mode, and two handlers on the same event name may each pick their own.
+     * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the
+     * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either
+     * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.
+     */
     register(opts) {
-        const { name, handlerBindingKey } = opts;
-        if (isEmpty(name) || isEmpty(handlerBindingKey)) {
+        const { name, handler, retry } = opts;
+        if (isEmpty({ value: name })) {
             throw getError({
-                message: `[EventBus][register] Invalid registration | name: ${String(name)} | handlerBindingKey: ${handlerBindingKey}`,
+                message: `[EventBus][register] Invalid registration | name: ${String(name)}`,
             });
         }
-        const existing = this.handlerBindingKeysByName.get(name);
+        const maxAttempts = retry?.maxAttempts ?? EventDispatchRetry.MAX_ATTEMPTS;
+        const baseDelayMs = retry?.baseDelayMs ?? EventDispatchRetry.BASE_DELAY_MS;
+        EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });
+        const { invokeHandler, description } = EventBus.buildHandlerInvoker({
+            container: this.container,
+            handler,
+            name,
+        });
+        const registration = {
+            invokeHandler,
+            description,
+            maxAttempts,
+            baseDelayMs,
+        };
+        const existing = this.registrationsByName.get(name);
         if (existing) {
-            existing.push(handlerBindingKey);
+            existing.push(registration);
             return;
         }
-        this.handlerBindingKeysByName.set(name, [handlerBindingKey]);
+        this.registrationsByName.set(name, [registration]);
     }
     /**
      * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via
@@ -38,55 +152,61 @@ export class EventBus extends BaseHelper {
             occurredAt: new Date().toISOString(),
             traceId,
         };
-        const handlerBindingKeys = this.handlerBindingKeysByName.get(name);
-        if (!handlerBindingKeys?.length) {
+        const registrations = this.registrationsByName.get(name);
+        if (!registrations?.length) {
             // A typo is already a compile error, so at runtime this only means nobody is listening yet -
             // a legitimate state on a fire-and-forget bus, not an incident.
             this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);
             return;
         }
-        for (const handlerBindingKey of handlerBindingKeys) {
+        for (const registration of registrations) {
             queueMicrotask(() => {
                 // `dispatch` catches every failure path itself and never rejects - this `.catch` is an
                 // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.
-                this.dispatch({ event, handlerBindingKey }).catch((error) => {
+                this.dispatch({ event, registration }).catch((error) => {
                     this.logger.error('[publish] Unexpected dispatch failure | name: %s | Error: %s', event.name, error);
                 });
             });
         }
     }
     /**
-     * Fixed 3 attempts / ~100ms exponential backoff, no jitter - see `EventDispatchRetry`. The
-     * handler is resolved fresh from the container on every attempt rather than once up front, so a
-     * rebind takes effect on the very next attempt of a dispatch already in flight.
+     * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),
+     * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,
+     * so many handlers retrying the same lock do not collide on the same instant a second and third
+     * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured
+     * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that
+     * throws synchronously is caught exactly like one that returns a rejected promise: `execution`
+     * here is itself `async`, and JS converts a synchronous throw inside an async function body into a
+     * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never
+     * sees the difference.
      *
      * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion
      * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone
      * relies on. The one line below, logged only on final failure, is.
      */
     async dispatch(opts) {
-        const { event, handlerBindingKey } = opts;
+        const { event, registration } = opts;
+        const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;
         let lastAttempt = 0;
         try {
             await RetryHelper.executeWithRetry({
                 operation: `EventBus.dispatch:${event.name}`,
-                maxAttempts: EventDispatchRetry.MAX_ATTEMPTS,
+                maxAttempts,
                 backoff: {
                     strategy: RetryBackoffStrategies.EXPONENTIAL,
-                    initialDelayMs: EventDispatchRetry.BASE_DELAY_MS,
-                    jitter: RetryJitterModes.NONE,
+                    initialDelayMs: baseDelayMs,
+                    jitter: RetryJitterModes.FULL,
                 },
                 execution: async ({ attempt }) => {
                     lastAttempt = attempt;
-                    const handler = this.container.get({ key: handlerBindingKey });
-                    await handler.handle({ event });
+                    await invokeHandler({ event });
                 },
             });
         }
         catch (error) {
             // The only trace this failure leaves: it is caught here and never reaches the publisher, so
             // the event name, traceId and attempt count all have to be on this one line.
-            this.logger.error('[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handlerBindingKey: %s | Error: %s', event.name, event.traceId, lastAttempt, handlerBindingKey, error);
+            this.logger.error('[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handler: %s | Error: %s', event.name, event.traceId, lastAttempt, description, error);
         }
     }
 }

package/dist/esm/base/events/event-bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/esm/base/index.d.ts

@@ -1,6 +1,7 @@
 export * from './applications/index.js';
 export * from './auth/index.js';
 export * from './components/index.js';
+export * from './configurations/index.js';
 export * from './controllers/index.js';
 export * from './datasources/index.js';
 export * from './events/index.js';

package/dist/esm/base/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/esm/base/index.js

@@ -1,6 +1,7 @@
 export * from './applications/index.js';
 export * from './auth/index.js';
 export * from './components/index.js';
+export * from './configurations/index.js';
 export * from './controllers/index.js';
 export * from './datasources/index.js';
 export * from './events/index.js';

package/dist/esm/base/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/esm/base/metadata/index.d.ts

@@ -1,3 +1,4 @@
+export * from './injectable.js';
 export * from './injectors.js';
 export * from './persistents.js';
 export * from './routes/index.js';

package/dist/esm/base/metadata/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/esm/base/metadata/index.js

@@ -1,3 +1,4 @@
+export * from './injectable.js';
 export * from './injectors.js';
 export * from './persistents.js';
 export * from './routes/index.js';

package/dist/esm/base/metadata/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/esm/base/metadata/injectable.d.ts

@@ -0,0 +1,16 @@
+import type { IArtifactMetadata, IArtifactRegistrationOptions, TBindingScope } from '../../helpers/inversion/index.js';
+/** The root stereotype: marks a class as an artifact the application registers, with its registration defaults. Every other stereotype calls it. */
+export declare const injectable: <ApplicationType = unknown>(opts: IArtifactMetadata<ApplicationType>) => ClassDecorator;
+export declare const service: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+export declare const component: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+export declare const configuration: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+/** Marks a component method as the provider of `key`. `registerArtifacts` binds the key to a lazy provider that resolves the component and calls the method; SINGLETON unless `scope` says otherwise. */
+export declare const provide: (opts: {
+    key: string;
+    scope?: TBindingScope;
+}) => MethodDecorator;
+/** The registration defaults a stereotype forwards to `@injectable`, copied field by field so an absent option stays absent. */
+export declare const pickRegistrationOptions: <ApplicationType = unknown>(opts: {
+    metadata: IArtifactRegistrationOptions<ApplicationType>;
+}) => IArtifactRegistrationOptions<ApplicationType>;
+//# sourceMappingURL=injectable.d.ts.map

package/dist/esm/base/metadata/injectable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,aAAa,EACd,MAAM,qBAAqB,CAAC;AAK7B,oJAAoJ;AACpJ,eAAO,MAAM,UAAU,GAAI,eAAe,GAAG,OAAO,EAClD,MAAM,iBAAiB,CAAC,eAAe,CAAC,KACvC,cAoCF,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,eAAe,GAAG,OAAO,EAC/C,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,eAAe,GAAG,OAAO,EACjD,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,eAAe,GAAG,OAAO,EACrD,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AACF,yMAAyM;AACzM,eAAO,MAAM,OAAO,GAAI,MAAM;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,KAAG,eAWtE,CAAC;AAEF,gIAAgI;AAChI,eAAO,MAAM,uBAAuB,GAAI,eAAe,GAAG,OAAO,EAAE,MAAM;IACvE,QAAQ,EAAE,4BAA4B,CAAC,eAAe,CAAC,CAAC;CACzD,KAAG,4BAA4B,CAAC,eAAe,CA6B/C,CAAC"}

package/dist/esm/base/metadata/injectable.js

@@ -0,0 +1,82 @@
+import { ArtifactNamespaces, BindingNamespaces } from '../../common/bindings.js';
+import { ArtifactTypes, BindingKeys, MetadataRegistry } from '../../helpers/inversion/index.js';
+import { getError } from '@venizia/ignis-helpers/core';
+/** The root stereotype: marks a class as an artifact the application registers, with its registration defaults. Every other stereotype calls it. */
+export const injectable = (opts) => {
+    return target => {
+        if (!ArtifactTypes.isValid(opts.type)) {
+            throw getError({
+                message: `[injectable][${target.name}] Invalid artifact type: '${opts.type}' | Expected one of: ${[...ArtifactTypes.SCHEME_SET].join(', ')}`,
+            });
+        }
+        // At import time, so the failure lands where the binding is written, not at boot.
+        if (opts.binding) {
+            BindingNamespaces.assertArtifactNamespace({
+                namespace: opts.binding.namespace,
+                artifact: target.name,
+                caller: 'injectable',
+            });
+        }
+        const registry = MetadataRegistry.getInstance();
+        registry.setArtifactMetadata({ target, metadata: opts });
+        // Discovery happens HERE, at import time. A boot-time filesystem scan cannot see a compiled
+        // single-file binary, and a class exists at run time only because something imported it.
+        registry.addDiscoveredArtifact({ target });
+        // The key this class WOULD get; `registerArtifact` overwrites it with the one actually bound.
+        registry.setBindingKey({
+            target,
+            key: BindingKeys.build(opts.binding ?? {
+                namespace: ArtifactNamespaces.resolve({ type: opts.type }),
+                key: target.name,
+            }),
+            isProvisional: true,
+        });
+    };
+};
+export const service = (opts) => {
+    return injectable({ type: ArtifactTypes.SERVICE, ...opts });
+};
+export const component = (opts) => {
+    return injectable({ type: ArtifactTypes.COMPONENT, ...opts });
+};
+export const configuration = (opts) => {
+    return injectable({ type: ArtifactTypes.CONFIGURATION, ...opts });
+};
+/** Marks a component method as the provider of `key`. `registerArtifacts` binds the key to a lazy provider that resolves the component and calls the method; SINGLETON unless `scope` says otherwise. */
+export const provide = (opts) => {
+    return (target, propertyKey) => {
+        MetadataRegistry.getInstance().addProvideMetadata({
+            target: target.constructor,
+            metadata: {
+                methodName: propertyKey,
+                key: opts.key,
+                ...(opts.scope ? { scope: opts.scope } : {}),
+            },
+        });
+    };
+};
+/** The registration defaults a stereotype forwards to `@injectable`, copied field by field so an absent option stays absent. */
+export const pickRegistrationOptions = (opts) => {
+    const { binding, allowOverride, scope, order, when, after } = opts.metadata;
+    const registration = {};
+    if (binding !== undefined) {
+        registration.binding = binding;
+    }
+    if (allowOverride !== undefined) {
+        registration.allowOverride = allowOverride;
+    }
+    if (scope !== undefined) {
+        registration.scope = scope;
+    }
+    if (order !== undefined) {
+        registration.order = order;
+    }
+    if (when !== undefined) {
+        registration.when = when;
+    }
+    if (after !== undefined) {
+        registration.after = after;
+    }
+    return registration;
+};
+//# sourceMappingURL=injectable.js.map

package/dist/esm/base/metadata/injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.js","sourceRoot":"","sources":["../../../../src/base/metadata/injectable.ts"],"names":[],"mappings":"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"}

package/dist/esm/base/metadata/injectors.d.ts

@@ -1,7 +1,16 @@
-import type { TBindingKey } from '../../helpers/inversion/index.js';
-/** Marks a property or constructor parameter for dependency injection. */
-export declare const inject: (opts: {
-    key: TBindingKey;
-    isOptional?: boolean;
-}) => (target: any, propertyName: string | symbol | undefined, parameterIndex?: number) => void;
+import type { TInjectOptions as TCoreInjectOptions } from '@venizia/ignis-inversion';
+/** Distributes over the union, so `key` and `target` stay mutually exclusive - a bare `Omit` collapses the two branches into one shape declaring both. */
+type TWithoutRegistry<T> = T extends unknown ? Omit<T, 'registry'> : never;
+/**
+ * Either a binding key or the class bound under it - never both. The shape is inversion's; the
+ * `registry` member is not, because this wrapper is the one that supplies it.
+ */
+export type TInjectOptions = TWithoutRegistry<TCoreInjectOptions>;
+/**
+ * `@inject`, bound to the kernel's registry. The container reads
+ * `MetadataRegistry.getInstance()` (`helpers/inversion/container.ts`), while inversion's own
+ * `inject` writes to its module-level registry - metadata written there is never read back.
+ */
+export declare const inject: (opts: TInjectOptions) => (target: any, propertyName: string | symbol | undefined, parameterIndex?: number) => void;
+export {};
 //# sourceMappingURL=injectors.d.ts.map

package/dist/esm/base/metadata/injectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"injectors.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,0EAA0E;AAC1E,eAAO,MAAM,MAAM,GAAI,MAAM;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,8FAEtE,CAAC"}
+{"version":3,"file":"injectors.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAErF,0JAA0J;AAC1J,KAAK,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,cAAc,8FAS1C,CAAC"}