@venizia/ignis-kernel 0.2.0-10 → 0.2.0-11

package/dist/cjs/base/events/common/constants.d.ts

@@ -1,5 +1,37 @@
+import type { TConstValue } from '@venizia/ignis-helpers/common';
 export declare class EventDispatchRetry {
     static readonly MAX_ATTEMPTS = 3;
     static readonly BASE_DELAY_MS = 100;
+    /**
+     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
+     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
+     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
+     * leaves room to tune without permitting an attempt storm.
+     */
+    static readonly MAX_ATTEMPTS_CEILING = 10;
+    /**
+     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
+     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
+     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
+     * a database connection - for its entire retry window, so the sum across every attempt gets the
+     * same "unreasonable beyond this" line the framework already draws for one attempt.
+     */
+    static readonly MAX_TOTAL_WINDOW_MS = 30000;
 }
+/**
+ * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
+ * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
+ * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
+ * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
+ * watching.
+ */
+export declare class EventHandlerTypes {
+    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
+    static readonly BINDING_KEY = "binding-key";
+    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
+    static readonly FUNCTION = "function";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): value is TEventHandlerType;
+}
+export type TEventHandlerType = TConstValue<typeof EventHandlerTypes>;
 //# sourceMappingURL=constants.d.ts.map

package/dist/cjs/base/events/common/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,OAAO;CACrC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,OAAO;IAEpC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,MAAM;IAE1C;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAU;CAC9C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,2HAA2H;IAC3H,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAE5C,wKAAwK;IACxK,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc;IAEtC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAAsD;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB;CAG1D;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/cjs/base/events/common/constants.js

@@ -1,9 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventDispatchRetry = void 0;
+exports.EventHandlerTypes = exports.EventDispatchRetry = void 0;
 class EventDispatchRetry {
     static { this.MAX_ATTEMPTS = 3; }
     static { this.BASE_DELAY_MS = 100; }
+    /**
+     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
+     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
+     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
+     * leaves room to tune without permitting an attempt storm.
+     */
+    static { this.MAX_ATTEMPTS_CEILING = 10; }
+    /**
+     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
+     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
+     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
+     * a database connection - for its entire retry window, so the sum across every attempt gets the
+     * same "unreasonable beyond this" line the framework already draws for one attempt.
+     */
+    static { this.MAX_TOTAL_WINDOW_MS = 30_000; }
 }
 exports.EventDispatchRetry = EventDispatchRetry;
+/**
+ * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
+ * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
+ * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
+ * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
+ * watching.
+ */
+class EventHandlerTypes {
+    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
+    static { this.BINDING_KEY = 'binding-key'; }
+    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
+    static { this.FUNCTION = 'function'; }
+    static { this.SCHEME_SET = new Set([this.BINDING_KEY, this.FUNCTION]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.EventHandlerTypes = EventHandlerTypes;
 //# sourceMappingURL=constants.js.map

package/dist/cjs/base/events/common/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":";;;AAAA,MAAa,kBAAkB;aACb,iBAAY,GAAG,CAAC,CAAC;aACjB,kBAAa,GAAG,GAAG,CAAC;;AAFtC,gDAGC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":";;;AAEA,MAAa,kBAAkB;aACb,iBAAY,GAAG,CAAC,CAAC;aACjB,kBAAa,GAAG,GAAG,CAAC;IAEpC;;;;;OAKG;aACa,yBAAoB,GAAG,EAAE,CAAC;IAE1C;;;;;;OAMG;aACa,wBAAmB,GAAG,MAAM,CAAC;;AAnB/C,gDAoBC;AAED;;;;;;GAMG;AACH,MAAa,iBAAiB;IAC5B,2HAA2H;aAC3G,gBAAW,GAAG,aAAa,CAAC;IAE5C,wKAAwK;aACxJ,aAAQ,GAAG,UAAU,CAAC;aAEtB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAXH,8CAYC"}

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

@@ -1,3 +1,5 @@
+import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
+import { EventHandlerTypes } from './constants';
 /** 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/cjs/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/cjs/base/events/event-bus.d.ts

@@ -1,21 +1,52 @@
 import type { Container } from '../../helpers/inversion/container';
 import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { IEventHandlerRetryOptions, TEventHandlerReference } from './common/types';
 /** 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/cjs/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":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,UAAU,EAKX,MAAM,6BAA6B,CAAC;AAGrC,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/cjs/base/events/event-bus.js

@@ -8,28 +8,142 @@ const core_1 = require("@venizia/ignis-helpers/core");
 const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
 const constants_1 = require("./common/constants");
 /** 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`. */
 class EventBus extends core_1.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 += core_1.RetryHelper.computeBackoffDelayMs({
+                attempt,
+                backoff: {
+                    strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
+                    initialDelayMs: baseDelayMs,
+                    jitter: core_1.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 (0, core_1.getError)({
+                message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,
+            });
+        }
+        if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,
+            });
+        }
+        if (maxAttempts > constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,
+            });
+        }
+        const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });
+        if (totalWindowMs > constants_1.EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${constants_1.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 ((0, isEmpty_1.default)(handler)) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,
+            });
+        }
+        switch (handler.type) {
+            case constants_1.EventHandlerTypes.BINDING_KEY: {
+                const { key } = handler;
+                if ((0, isEmpty_1.default)(key)) {
+                    throw (0, core_1.getError)({
+                        message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,
+                    });
+                }
+                return {
+                    invokeHandler: ({ event }) => container.get({ key }).handle({ event }),
+                    description: `binding-key:${key}`,
+                };
+            }
+            case constants_1.EventHandlerTypes.FUNCTION: {
+                const { fn } = handler;
+                if (typeof fn !== 'function') {
+                    throw (0, core_1.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 (0, core_1.getError)({
+                    message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...constants_1.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 ((0, isEmpty_1.default)(name) || (0, isEmpty_1.default)(handlerBindingKey)) {
+        const { name, handler, retry } = opts;
+        if ((0, isEmpty_1.default)(name)) {
             throw (0, core_1.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 ?? constants_1.EventDispatchRetry.MAX_ATTEMPTS;
+        const baseDelayMs = retry?.baseDelayMs ?? constants_1.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
@@ -44,55 +158,61 @@ class EventBus extends core_1.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 core_1.RetryHelper.executeWithRetry({
                 operation: `EventBus.dispatch:${event.name}`,
-                maxAttempts: constants_1.EventDispatchRetry.MAX_ATTEMPTS,
+                maxAttempts,
                 backoff: {
                     strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
-                    initialDelayMs: constants_1.EventDispatchRetry.BASE_DELAY_MS,
-                    jitter: core_1.RetryJitterModes.NONE,
+                    initialDelayMs: baseDelayMs,
+                    jitter: core_1.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/cjs/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/cjs/base/models/common/types.d.ts

@@ -21,6 +21,26 @@ export type NumberIdType = number;
 export type StringIdType = string;
 export type BigIntIdType = bigint;
 export type IdType = NumberIdType | StringIdType | BigIntIdType;
+declare const entityIdBrand: unique symbol;
+/**
+ * A string id a plain `string` cannot be assigned to, so passing a name, code or email where an id
+ * belongs is a compile error. Opt a column in with `.$type<TEntityId>()`.
+ *
+ * IT VALIDATES NOTHING. `toEntityId` is a cast with a non-empty check; the value is making the
+ * laundering VISIBLE at each boundary, not proving the string is a real id.
+ *
+ * The cost is not optional: Drizzle derives `$inferInsert` and `$inferSelect` from the same field,
+ * so a branded column rejects every literal - `create({ data: { merchantId: 'M1' } })`, seeds,
+ * fixtures, path params - until each converts. A union with `string` would restore those but makes
+ * a plain `string` assignable again, which erases the whole guarantee. Measured, not assumed.
+ */
+export type TEntityId = string & {
+    readonly [entityIdBrand]: never;
+};
+/** The only way into `TEntityId`. Rejects an empty string - an id that is `''` collapses a `where` to no condition. */
+export declare const toEntityId: (opts: {
+    value: string;
+}) => TEntityId;
 /** Path-param id shape every entity family resolves to (`AbstractEntity.getIdType()`). */
 export type TIdSchemaType = 'number' | 'string';
 export declare const idParamsSchema: (opts?: {

package/dist/cjs/base/models/common/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/models/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;iBA6BpB,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEhE,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,eAAO,MAAM,cAAc,GAAI,OAAO;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE;;;;iBAkC9D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM;IACrD,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;;;;;;;CAMA,CAAC;AAEF,mCAAmC;AACnC,KAAK,aAAa,GAAG;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACpD,CAAC;AAEF,4CAA4C;AAC5C,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEtD,KAAK,iBAAiB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,gBAAgB,GAAG,SAAS,IAAI;IACpF,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,aAAa,SAAS,CAAC,CAAC,OAAO,EAC/B,YAAY,SAAS,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAE7D,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAcrD,CAAC;AAEF,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,GACxE,GAAG,CAAC,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,GACzC,CAAC,CAAC;AAEN,KAAK,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,IAAI;KAC5C,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAC1F,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACZ,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,0SAW7D,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/models/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;iBA6BpB,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEhE,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAErE,uHAAuH;AACvH,eAAO,MAAM,UAAU,GAAI,MAAM;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAG,SAMpD,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,eAAO,MAAM,cAAc,GAAI,OAAO;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE;;;;iBAkC9D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM;IACrD,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;;;;;;;CAMA,CAAC;AAEF,mCAAmC;AACnC,KAAK,aAAa,GAAG;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACpD,CAAC;AAEF,4CAA4C;AAC5C,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEtD,KAAK,iBAAiB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,gBAAgB,GAAG,SAAS,IAAI;IACpF,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,aAAa,SAAS,CAAC,CAAC,OAAO,EAC/B,YAAY,SAAS,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAE7D,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAcrD,CAAC;AAEF,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,GACxE,GAAG,CAAC,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,GACzC,CAAC,CAAC;AAEN,KAAK,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,IAAI;KAC5C,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAC1F,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACZ,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,0SAW7D,CAAC"}

package/dist/cjs/base/models/common/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.snakeToCamel = exports.jsonResponse = exports.jsonContent = exports.idParamsSchema = exports.ErrorSchema = void 0;
+exports.snakeToCamel = exports.jsonResponse = exports.jsonContent = exports.idParamsSchema = exports.toEntityId = exports.ErrorSchema = void 0;
 const zod_openapi_1 = require("@hono/zod-openapi");
 const core_1 = require("@venizia/ignis-helpers/core");
 const common_1 = require("@venizia/ignis-helpers/common");
@@ -40,6 +40,14 @@ exports.ErrorSchema = zod_openapi_1.z
         details: { url: 'http://localhost:3000/categories', path: '/categories' },
     },
 });
+/** The only way into `TEntityId`. Rejects an empty string - an id that is `''` collapses a `where` to no condition. */
+const toEntityId = (opts) => {
+    if (opts.value.length === 0) {
+        throw (0, core_1.getError)({ message: '[toEntityId] Refusing an empty string as an entity id' });
+    }
+    return opts.value;
+};
+exports.toEntityId = toEntityId;
 const idParamsSchema = (opts) => {
     const { idType = 'number' } = opts ?? {};
     switch (idType) {

package/dist/cjs/base/models/common/types.js.map

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

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

@@ -1,5 +1,37 @@
+import type { TConstValue } from '@venizia/ignis-helpers/common';
 export declare class EventDispatchRetry {
     static readonly MAX_ATTEMPTS = 3;
     static readonly BASE_DELAY_MS = 100;
+    /**
+     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
+     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
+     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
+     * leaves room to tune without permitting an attempt storm.
+     */
+    static readonly MAX_ATTEMPTS_CEILING = 10;
+    /**
+     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
+     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
+     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
+     * a database connection - for its entire retry window, so the sum across every attempt gets the
+     * same "unreasonable beyond this" line the framework already draws for one attempt.
+     */
+    static readonly MAX_TOTAL_WINDOW_MS = 30000;
 }
+/**
+ * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
+ * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
+ * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
+ * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
+ * watching.
+ */
+export declare class EventHandlerTypes {
+    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
+    static readonly BINDING_KEY = "binding-key";
+    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
+    static readonly FUNCTION = "function";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): value is TEventHandlerType;
+}
+export type TEventHandlerType = TConstValue<typeof EventHandlerTypes>;
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,OAAO;CACrC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,YAAY,KAAK;IACjC,MAAM,CAAC,QAAQ,CAAC,aAAa,OAAO;IAEpC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,MAAM;IAE1C;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAAU;CAC9C;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,2HAA2H;IAC3H,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAE5C,wKAAwK;IACxK,MAAM,CAAC,QAAQ,CAAC,QAAQ,cAAc;IAEtC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAAsD;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB;CAG1D;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/esm/base/events/common/constants.js

@@ -1,5 +1,37 @@
 export class EventDispatchRetry {
     static { this.MAX_ATTEMPTS = 3; }
     static { this.BASE_DELAY_MS = 100; }
+    /**
+     * Ceiling on `register`'s `retry.maxAttempts`. Dispatch is fire-and-forget - nobody awaits it - so
+     * an attempt count high enough to matter is already high enough to hammer a struggling downstream
+     * resource attempt after attempt. Twice the highest count any known consumer has asked for (5)
+     * leaves room to tune without permitting an attempt storm.
+     */
+    static { this.MAX_ATTEMPTS_CEILING = 10; }
+    /**
+     * Ceiling, in ms, on the total backoff window `register`'s `retry` can produce (the sum of every
+     * inter-attempt delay, computed without jitter since jitter only shrinks it). Matches
+     * `RetryHelper`'s own default cap on a SINGLE delay: a dispatch holds a handler's resources - e.g.
+     * a database connection - for its entire retry window, so the sum across every attempt gets the
+     * same "unreasonable beyond this" line the framework already draws for one attempt.
+     */
+    static { this.MAX_TOTAL_WINDOW_MS = 30_000; }
+}
+/**
+ * Tag for `EventBus.register`'s `handler` union (`TEventHandlerReference`). The tag makes the
+ * caller's choice explicit at the call site instead of implicit in whichever field is present, so a
+ * mismatched `type`/field pair (`BINDING_KEY` with `fn`, or `FUNCTION` with `key`) is a compile
+ * error there rather than a runtime surprise later, inside a `queueMicrotask` where nobody is
+ * watching.
+ */
+export class EventHandlerTypes {
+    /** `handler.key` is resolved from the container on every retry attempt - a rebind reaches an attempt already in flight. */
+    static { this.BINDING_KEY = 'binding-key'; }
+    /** `handler.fn` is invoked directly as a captured closure - there is nothing to rebind, so every attempt in a retry window calls the exact function registered here. */
+    static { this.FUNCTION = 'function'; }
+    static { this.SCHEME_SET = new Set([this.BINDING_KEY, this.FUNCTION]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
 }
 //# sourceMappingURL=constants.js.map

package/dist/esm/base/events/common/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,kBAAkB;aACb,iBAAY,GAAG,CAAC,CAAC;aACjB,kBAAa,GAAG,GAAG,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/base/events/common/constants.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,kBAAkB;aACb,iBAAY,GAAG,CAAC,CAAC;aACjB,kBAAa,GAAG,GAAG,CAAC;IAEpC;;;;;OAKG;aACa,yBAAoB,GAAG,EAAE,CAAC;IAE1C;;;;;;OAMG;aACa,wBAAmB,GAAG,MAAM,CAAC;;AAG/C;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IAC5B,2HAA2H;aAC3G,gBAAW,GAAG,aAAa,CAAC;IAE5C,wKAAwK;aACxJ,aAAQ,GAAG,UAAU,CAAC;aAEtB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhF,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC"}

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":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,UAAU,EAKX,MAAM,6BAA6B,CAAC;AAGrC,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 { 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(handler)) {
+            throw getError({
+                message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,
+            });
+        }
+        switch (handler.type) {
+            case EventHandlerTypes.BINDING_KEY: {
+                const { key } = handler;
+                if (isEmpty(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(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/models/common/types.d.ts

@@ -21,6 +21,26 @@ export type NumberIdType = number;
 export type StringIdType = string;
 export type BigIntIdType = bigint;
 export type IdType = NumberIdType | StringIdType | BigIntIdType;
+declare const entityIdBrand: unique symbol;
+/**
+ * A string id a plain `string` cannot be assigned to, so passing a name, code or email where an id
+ * belongs is a compile error. Opt a column in with `.$type<TEntityId>()`.
+ *
+ * IT VALIDATES NOTHING. `toEntityId` is a cast with a non-empty check; the value is making the
+ * laundering VISIBLE at each boundary, not proving the string is a real id.
+ *
+ * The cost is not optional: Drizzle derives `$inferInsert` and `$inferSelect` from the same field,
+ * so a branded column rejects every literal - `create({ data: { merchantId: 'M1' } })`, seeds,
+ * fixtures, path params - until each converts. A union with `string` would restore those but makes
+ * a plain `string` assignable again, which erases the whole guarantee. Measured, not assumed.
+ */
+export type TEntityId = string & {
+    readonly [entityIdBrand]: never;
+};
+/** The only way into `TEntityId`. Rejects an empty string - an id that is `''` collapses a `where` to no condition. */
+export declare const toEntityId: (opts: {
+    value: string;
+}) => TEntityId;
 /** Path-param id shape every entity family resolves to (`AbstractEntity.getIdType()`). */
 export type TIdSchemaType = 'number' | 'string';
 export declare const idParamsSchema: (opts?: {

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/models/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;iBA6BpB,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEhE,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,eAAO,MAAM,cAAc,GAAI,OAAO;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE;;;;iBAkC9D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM;IACrD,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;;;;;;;CAMA,CAAC;AAEF,mCAAmC;AACnC,KAAK,aAAa,GAAG;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACpD,CAAC;AAEF,4CAA4C;AAC5C,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEtD,KAAK,iBAAiB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,gBAAgB,GAAG,SAAS,IAAI;IACpF,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,aAAa,SAAS,CAAC,CAAC,OAAO,EAC/B,YAAY,SAAS,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAE7D,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAcrD,CAAC;AAEF,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,GACxE,GAAG,CAAC,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,GACzC,CAAC,CAAC;AAEN,KAAK,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,IAAI;KAC5C,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAC1F,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACZ,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,0SAW7D,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/base/models/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;iBA6BpB,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEhE,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAErE,uHAAuH;AACvH,eAAO,MAAM,UAAU,GAAI,MAAM;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAG,SAMpD,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,eAAO,MAAM,cAAc,GAAI,OAAO;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE;;;;iBAkC9D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM;IACrD,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;;;;;;;CAMA,CAAC;AAEF,mCAAmC;AACnC,KAAK,aAAa,GAAG;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACpD,CAAC;AAEF,4CAA4C;AAC5C,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEtD,KAAK,iBAAiB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,gBAAgB,GAAG,SAAS,IAAI;IACpF,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,aAAa,SAAS,CAAC,CAAC,OAAO,EAC/B,YAAY,SAAS,gBAAgB,GAAG,SAAS,GAAG,SAAS,EAE7D,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAcrD,CAAC;AAEF,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,GACxE,GAAG,CAAC,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,GACzC,CAAC,CAAC;AAEN,KAAK,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,IAAI;KAC5C,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAC1F,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACZ,CAAC,CAAC,CAAC,CAAC;CACT,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,0SAW7D,CAAC"}

package/dist/esm/base/models/common/types.js

@@ -37,6 +37,13 @@ export const ErrorSchema = z
         details: { url: 'http://localhost:3000/categories', path: '/categories' },
     },
 });
+/** The only way into `TEntityId`. Rejects an empty string - an id that is `''` collapses a `where` to no condition. */
+export const toEntityId = (opts) => {
+    if (opts.value.length === 0) {
+        throw getError({ message: '[toEntityId] Refusing an empty string as an entity id' });
+    }
+    return opts.value;
+};
 export const idParamsSchema = (opts) => {
     const { idType = 'number' } = opts ?? {};
     switch (idType) {

package/dist/esm/base/models/common/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-kernel",
-  "version": "0.2.0-10",
+  "version": "0.2.0-11",
   "description": "Browser-pure kernel of the IGNIS framework: dependency injection, lifecycle, REST controllers, repository and datasource abstractions, and the authentication and authorization seams. No node builtin and no server-only peer, so the same kernel serves a Bun server and a browser Worker.",
   "keywords": [
     "authentication",