@kronos-ts/messaging 0.1.0

package/dist/transaction.js

@@ -0,0 +1,74 @@
+import { resourceKey } from "@kronos-ts/common";
+import { processingStateStorage, setResource, on, onError, Phase, } from "./processing-state.js";
+/**
+ * A no-op transaction manager for when no database transactions are needed.
+ */
+export function noTransactionManager() {
+    return {
+        begin: async () => { },
+        commit: async () => { },
+        rollback: async () => { },
+    };
+}
+/** Resource key for storing the active transaction in the active UnitOfWork's ALS-backed resources. */
+export const TRANSACTION_KEY = resourceKey("transaction");
+/**
+ * Get the active transaction from the active UnitOfWork's ALS-backed resources.
+ * Returns undefined if no UnitOfWork is active or no transaction has been stored.
+ *
+ * ORM integrations use this to participate in the framework's transaction:
+ * ```
+ * const db = drizzle(pool, {
+ *   transaction: () => getActiveTransaction(),
+ * })
+ * ```
+ *
+ * Permissive undefined-return preserved (D-12 / D-23): callers outside a UoW
+ * get `undefined`, NOT a NoActiveUnitOfWork throw — this is an ORM escape hatch,
+ * not a framework-internal accessor.
+ */
+export function getActiveTransaction() {
+    const state = processingStateStorage.getStore();
+    if (!state)
+        return undefined;
+    return state.resources.get(TRANSACTION_KEY.symbol);
+}
+/**
+ * Wraps a delegate runner with transaction management. The transaction is:
+ * - Started before the delegate's action runs
+ * - Available via `getActiveTransaction()` throughout
+ * - Committed in the COMMIT phase
+ * - Rolled back on error
+ *
+ * The transaction is stored as a resource on the active UoW's ALS state,
+ * so all phases (PRE_INVOCATION through AFTER_COMMIT) and any code calling
+ * `getActiveTransaction()` inside the UoW see it.
+ *
+ * ```
+ * const txRunner = transactionalUnitOfWorkFactory(runInUoW, myTransactionManager)
+ * await txRunner(metadata, async () => { ... })
+ * ```
+ *
+ * Plan 03-04 (CTX-04 / D-34): rewritten as a composable runner wrapper.
+ * Previously took/returned `UnitOfWorkFactory`; the UoW interface and
+ * factory are gone, so this now takes/returns `UoWRunner`. The name is
+ * preserved despite the shape change — public docs and extension code
+ * import `transactionalUnitOfWorkFactory` by name. Phase 9 (Extension
+ * Migration) can rename if the kronos() app API warrants.
+ */
+export function transactionalUnitOfWorkFactory(delegate, txManager) {
+    return async (metadata, action) => {
+        const tx = await txManager.begin();
+        return delegate(metadata, async () => {
+            setResource(TRANSACTION_KEY, tx);
+            on(Phase.COMMIT, async () => {
+                await txManager.commit(tx);
+            });
+            onError(async () => {
+                await txManager.rollback(tx);
+            });
+            return action();
+        });
+    };
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,mBAAmB,CAAA;AACjE,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,EAAE,EACF,OAAO,EACP,KAAK,GACN,MAAM,uBAAuB,CAAA;AAe9B;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;QACrB,MAAM,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;QACtB,QAAQ,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;KACzB,CAAA;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,MAAM,eAAe,GAAyB,WAAW,CAAC,aAAa,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,EAAE,CAAA;IAC/C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,OAAO,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,MAAM,CAAkB,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAmB,EACnB,SAAgC;IAEhC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE;QAChC,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,CAAA;QAClC,OAAO,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnC,WAAW,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;YAChC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;gBAC1B,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAC5B,CAAC,CAAC,CAAA;YACF,OAAO,CAAC,KAAK,IAAI,EAAE;gBACjB,MAAM,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YAC9B,CAAC,CAAC,CAAA;YACF,OAAO,MAAM,EAAE,CAAA;QACjB,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}

package/dist/unit-of-work.d.ts

@@ -0,0 +1,41 @@
+import { type Metadata } from "@kronos-ts/common";
+/**
+ * Runner type: the canonical "enter a UnitOfWork" shape.
+ *
+ * Plan 03-04 (CTX-04 / D-34): replaces the old `UnitOfWorkFactory` shape.
+ * Extensions (kronosdb, axon-server) and transactional wrappers compose
+ * runners — `transactionalUnitOfWorkFactory` accepts a delegate runner
+ * and returns a new runner that begins/commits/rolls-back a transaction
+ * around the inner action.
+ */
+export type UoWRunner = <R>(metadata: Metadata | undefined, action: () => Promise<R>) => Promise<R>;
+/**
+ * Run `action` inside a NEW UnitOfWork. Always creates a fresh UoW even
+ * if one is already active on the ALS stack.
+ *
+ * Used by gateways (D-32): `commandGateway.send`, `queryGateway.query`,
+ * and any external entry point. This keeps gateway calls isolated from
+ * an injected dispatcher that reuses the active UoW.
+ */
+export declare function runInNewUoW<R>(metadata: Metadata | undefined, action: () => Promise<R>): Promise<R>;
+/**
+ * Run `action` inside a UnitOfWork. ALS-aware:
+ *
+ * - If `processingStateStorage` already has an active state (we are
+ *   nested inside a parent UoW), this REUSES the parent's state and
+ *   calls `action` directly — no new `processingStateStorage.run`, no
+ *   new phase lifecycle. This is CTX-02: nested dispatch threads through
+ *   the same UoW so transactionality spans handler-internal bus calls.
+ *
+ * - If no state is active, behaves identically to `runInNewUoW` —
+ *   creates a fresh UoW and drives the full phase lifecycle.
+ *
+ * Used by `queryBus.query` so handler-internal queries auto-nest, while
+ * a primary query (no active UoW) starts a new one.
+ *
+ * NOTE: `commandBus.dispatch` deliberately does NOT use this — for AF5
+ * parity every command gets its own fresh UnitOfWork via `runInNewUoW`,
+ * nested or not. See `createSimpleCommandBus`.
+ */
+export declare function runInUoW<R>(metadata: Metadata | undefined, action: () => Promise<R>): Promise<R>;
+//# sourceMappingURL=unit-of-work.d.ts.map

package/dist/unit-of-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-of-work.d.ts","sourceRoot":"","sources":["../src/unit-of-work.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAQhE;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,EACxB,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/unit-of-work.js

@@ -0,0 +1,96 @@
+import { emptyMetadata } from "@kronos-ts/common";
+import { processingStateStorage, createInitialProcessingState, Phase, } from "./processing-state.js";
+/**
+ * Run `action` inside a NEW UnitOfWork. Always creates a fresh UoW even
+ * if one is already active on the ALS stack.
+ *
+ * Used by gateways (D-32): `commandGateway.send`, `queryGateway.query`,
+ * and any external entry point. This keeps gateway calls isolated from
+ * an injected dispatcher that reuses the active UoW.
+ */
+export function runInNewUoW(metadata, action) {
+    const resolvedMetadata = metadata ?? emptyMetadata();
+    const state = createInitialProcessingState(resolvedMetadata);
+    return processingStateStorage.run(state, () => drivePhases(state, action));
+}
+/**
+ * Run `action` inside a UnitOfWork. ALS-aware:
+ *
+ * - If `processingStateStorage` already has an active state (we are
+ *   nested inside a parent UoW), this REUSES the parent's state and
+ *   calls `action` directly — no new `processingStateStorage.run`, no
+ *   new phase lifecycle. This is CTX-02: nested dispatch threads through
+ *   the same UoW so transactionality spans handler-internal bus calls.
+ *
+ * - If no state is active, behaves identically to `runInNewUoW` —
+ *   creates a fresh UoW and drives the full phase lifecycle.
+ *
+ * Used by `queryBus.query` so handler-internal queries auto-nest, while
+ * a primary query (no active UoW) starts a new one.
+ *
+ * NOTE: `commandBus.dispatch` deliberately does NOT use this — for AF5
+ * parity every command gets its own fresh UnitOfWork via `runInNewUoW`,
+ * nested or not. See `createSimpleCommandBus`.
+ */
+export function runInUoW(metadata, action) {
+    if (processingStateStorage.getStore() !== undefined)
+        return action();
+    return runInNewUoW(metadata, action);
+}
+async function drivePhases(state, action) {
+    state.status = "started";
+    try {
+        await runPhase(state, Phase.PRE_INVOCATION);
+        state.currentPhase = Phase.INVOCATION;
+        let actions = state.phaseActions.get(Phase.INVOCATION);
+        while (actions && actions.length > 0) {
+            const bucket = actions;
+            state.phaseActions.set(Phase.INVOCATION, []);
+            for (const a of bucket)
+                await a();
+            actions = state.phaseActions.get(Phase.INVOCATION);
+        }
+        const result = await action();
+        await runPhase(state, Phase.POST_INVOCATION);
+        await runPhase(state, Phase.PREPARE_COMMIT);
+        await runPhase(state, Phase.COMMIT);
+        await runPhase(state, Phase.AFTER_COMMIT);
+        state.status = "completed";
+        for (const h of state.completeHandlers) {
+            try {
+                h();
+            }
+            catch (e) {
+                console.warn("UnitOfWork: completion handler threw an exception:", e);
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        state.status = "error";
+        const failedPhase = state.currentPhase ?? undefined;
+        for (const h of state.errorHandlers) {
+            try {
+                await h(error, failedPhase);
+            }
+            catch (e) {
+                console.warn("UnitOfWork: error handler threw an exception:", e);
+            }
+        }
+        throw error;
+    }
+}
+async function runPhase(state, phase) {
+    state.currentPhase = phase;
+    // Late registration: actions registered during a phase's own execution
+    // fire next loop iteration (still within the same phase).
+    let actions = state.phaseActions.get(phase);
+    while (actions && actions.length > 0) {
+        const bucket = actions;
+        state.phaseActions.set(phase, []);
+        for (const a of bucket)
+            await a();
+        actions = state.phaseActions.get(phase);
+    }
+}
+//# sourceMappingURL=unit-of-work.js.map

package/dist/unit-of-work.js.map

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

package/dist/upcaster.d.ts

@@ -0,0 +1,91 @@
+import type { Serializer } from "@kronos-ts/common";
+/**
+ * An intermediate representation of an event during the upcasting pipeline.
+ *
+ * After deserialization from bytes (JSON.parse) but before Zod validation,
+ * the event passes through the upcaster chain as an IntermediateEventRepresentation.
+ * Each upcaster can transform the payload, type name, revision, and metadata.
+ */
+export interface IntermediateEventRepresentation {
+    /** The deserialized payload (raw JSON, not yet Zod-validated). */
+    readonly payload: unknown;
+    /** The qualified type name (e.g., "university.CourseCreated"). */
+    readonly typeName: string;
+    /** The schema revision (e.g., "1.0"). */
+    readonly revision: string;
+    /** Event metadata. */
+    readonly metadata: Record<string, unknown>;
+}
+/**
+ * An event upcaster transforms events from one schema version to another.
+ *
+ * Upcasters run after JSON deserialization but before Zod validation,
+ * so the payload is raw parsed JSON. The upcaster can add fields, rename
+ * fields, change the type name, bump the revision, etc.
+ *
+ * An upcaster can return:
+ * - A single representation (one-to-one transform)
+ * - An array of representations (one-to-many, e.g., splitting events)
+ * - An empty array (filtering out an event)
+ */
+export interface EventUpcaster {
+    /** Whether this upcaster can handle the given type + revision. */
+    canUpcast(typeName: string, revision: string): boolean;
+    /**
+     * Transform the intermediate representation.
+     * Return the upcasted representation(s).
+     */
+    upcast(event: IntermediateEventRepresentation): IntermediateEventRepresentation | IntermediateEventRepresentation[];
+}
+/**
+ * Convenience function for the common case: a single event type
+ * being transformed from one revision to the next.
+ *
+ * ```typescript
+ * const upcaster = singleEventUpcaster({
+ *   typeName: "university.CourseCreated",
+ *   fromRevision: "1.0",
+ *   toRevision: "2.0",
+ *   upcast: (payload: any) => ({
+ *     ...payload,
+ *     capacity: payload.capacity ?? 30,  // added in v2
+ *   }),
+ * })
+ * ```
+ */
+export declare function singleEventUpcaster(options: {
+    typeName: string;
+    fromRevision: string;
+    toRevision: string;
+    upcast: (payload: unknown) => unknown;
+    upcastMetadata?: (metadata: Record<string, unknown>) => Record<string, unknown>;
+}): EventUpcaster;
+/**
+ * Chains multiple upcasters into a single upcaster.
+ * Upcasters are applied in order. Each upcaster's output becomes
+ * the next upcaster's input. Handles one-to-many expansion.
+ *
+ * ```typescript
+ * const chain = upcasterChain(
+ *   courseCreatedV1ToV2,
+ *   courseCreatedV2ToV3,
+ * )
+ * ```
+ */
+export declare function upcasterChain(...upcasters: EventUpcaster[]): EventUpcaster;
+/**
+ * Creates an upcasting serializer decorator.
+ *
+ * On deserialization, the raw payload is first deserialized by the delegate,
+ * then passed through the upcaster chain before being returned. The type name
+ * and revision from the SerializedObject drive upcaster selection.
+ *
+ * ```typescript
+ * const serializer = upcastingSerializer(
+ *   jsonSerializer(),
+ *   upcasterChain(v1ToV2, v2ToV3),
+ * )
+ * ```
+ */
+export declare function upcastingSerializer(delegate: Serializer, upcaster: EventUpcaster): Serializer;
+//# sourceMappingURL=upcaster.d.ts.map

package/dist/upcaster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upcaster.d.ts","sourceRoot":"","sources":["../src/upcaster.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,+BAA+B;IAC9C,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sBAAsB;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IAEtD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,+BAA+B,GAAG,+BAA+B,GAAG,+BAA+B,EAAE,CAAA;CACpH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;IACrC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChF,GAAG,aAAa,CAiBhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,SAAS,EAAE,aAAa,EAAE,GAAG,aAAa,CA6B1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,aAAa,GACtB,UAAU,CA6BZ"}

package/dist/upcaster.js

@@ -0,0 +1,114 @@
+/**
+ * Convenience function for the common case: a single event type
+ * being transformed from one revision to the next.
+ *
+ * ```typescript
+ * const upcaster = singleEventUpcaster({
+ *   typeName: "university.CourseCreated",
+ *   fromRevision: "1.0",
+ *   toRevision: "2.0",
+ *   upcast: (payload: any) => ({
+ *     ...payload,
+ *     capacity: payload.capacity ?? 30,  // added in v2
+ *   }),
+ * })
+ * ```
+ */
+export function singleEventUpcaster(options) {
+    return {
+        canUpcast(typeName, revision) {
+            return typeName === options.typeName && revision === options.fromRevision;
+        },
+        upcast(event) {
+            return {
+                payload: options.upcast(event.payload),
+                typeName: options.typeName,
+                revision: options.toRevision,
+                metadata: options.upcastMetadata
+                    ? options.upcastMetadata(event.metadata)
+                    : event.metadata,
+            };
+        },
+    };
+}
+/**
+ * Chains multiple upcasters into a single upcaster.
+ * Upcasters are applied in order. Each upcaster's output becomes
+ * the next upcaster's input. Handles one-to-many expansion.
+ *
+ * ```typescript
+ * const chain = upcasterChain(
+ *   courseCreatedV1ToV2,
+ *   courseCreatedV2ToV3,
+ * )
+ * ```
+ */
+export function upcasterChain(...upcasters) {
+    return {
+        canUpcast(typeName, revision) {
+            return upcasters.some((u) => u.canUpcast(typeName, revision));
+        },
+        upcast(event) {
+            let representations = [event];
+            for (const upcaster of upcasters) {
+                const next = [];
+                for (const rep of representations) {
+                    if (upcaster.canUpcast(rep.typeName, rep.revision)) {
+                        const result = upcaster.upcast(rep);
+                        if (Array.isArray(result)) {
+                            next.push(...result);
+                        }
+                        else {
+                            next.push(result);
+                        }
+                    }
+                    else {
+                        next.push(rep);
+                    }
+                }
+                representations = next;
+            }
+            return representations.length === 1 ? representations[0] : representations;
+        },
+    };
+}
+/**
+ * Creates an upcasting serializer decorator.
+ *
+ * On deserialization, the raw payload is first deserialized by the delegate,
+ * then passed through the upcaster chain before being returned. The type name
+ * and revision from the SerializedObject drive upcaster selection.
+ *
+ * ```typescript
+ * const serializer = upcastingSerializer(
+ *   jsonSerializer(),
+ *   upcasterChain(v1ToV2, v2ToV3),
+ * )
+ * ```
+ */
+export function upcastingSerializer(delegate, upcaster) {
+    return {
+        serialize(value, type, revision) {
+            return delegate.serialize(value, type, revision);
+        },
+        deserialize(data) {
+            const raw = delegate.deserialize(data);
+            if (!upcaster.canUpcast(data.type, data.revision)) {
+                return raw;
+            }
+            const representation = {
+                payload: raw,
+                typeName: data.type,
+                revision: data.revision,
+                metadata: {},
+            };
+            const result = upcaster.upcast(representation);
+            const upcasted = Array.isArray(result) ? result[0] : result;
+            return upcasted.payload;
+        },
+        canConvert(type) {
+            return delegate.canConvert(type);
+        },
+    };
+}
+//# sourceMappingURL=upcaster.js.map

package/dist/upcaster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upcaster.js","sourceRoot":"","sources":["../src/upcaster.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAMnC;IACC,OAAO;QACL,SAAS,CAAC,QAAQ,EAAE,QAAQ;YAC1B,OAAO,QAAQ,KAAK,OAAO,CAAC,QAAQ,IAAI,QAAQ,KAAK,OAAO,CAAC,YAAY,CAAA;QAC3E,CAAC;QAED,MAAM,CAAC,KAAK;YACV,OAAO;gBACL,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;gBACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,QAAQ,EAAE,OAAO,CAAC,UAAU;gBAC5B,QAAQ,EAAE,OAAO,CAAC,cAAc;oBAC9B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC;oBACxC,CAAC,CAAC,KAAK,CAAC,QAAQ;aACnB,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAG,SAA0B;IACzD,OAAO;QACL,SAAS,CAAC,QAAQ,EAAE,QAAQ;YAC1B,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;QAC/D,CAAC;QAED,MAAM,CAAC,KAAK;YACV,IAAI,eAAe,GAAsC,CAAC,KAAK,CAAC,CAAA;YAEhE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAsC,EAAE,CAAA;gBAClD,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;oBAClC,IAAI,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;wBACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;wBACnC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;4BAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAA;wBACtB,CAAC;6BAAM,CAAC;4BACN,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;wBACnB,CAAC;oBACH,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;oBAChB,CAAC;gBACH,CAAC;gBACD,eAAe,GAAG,IAAI,CAAA;YACxB,CAAC;YAED,OAAO,eAAe,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,eAAe,CAAA;QAC7E,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAoB,EACpB,QAAuB;IAEvB,OAAO;QACL,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ;YAC7B,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;QAClD,CAAC;QAED,WAAW,CAAI,IAAsB;YACnC,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAU,IAAI,CAAC,CAAA;YAE/C,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAClD,OAAO,GAAQ,CAAA;YACjB,CAAC;YAED,MAAM,cAAc,GAAoC;gBACtD,OAAO,EAAE,GAAG;gBACZ,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,EAAE;aACb,CAAA;YAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;YAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAA;YAC5D,OAAO,QAAQ,CAAC,OAAY,CAAA;QAC9B,CAAC;QAED,UAAU,CAAC,IAAI;YACb,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/with-namespace.d.ts

@@ -0,0 +1,59 @@
+import { type Tag } from "@kronos-ts/common";
+import { command as createCommand, query as createQuery } from "./descriptor.js";
+import type { z } from "zod";
+/**
+ * Creates a namespace-scoped factory for message descriptors.
+ * Reduces repetition when defining many messages in the same bounded context.
+ *
+ * ```typescript
+ * const ns = withNamespace("university.courses")
+ *
+ * const CreateCourse = ns.command("CreateCourse", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ *
+ * const CourseCreated = ns.event("CourseCreated", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => [tag("courseId", p.courseId)],
+ * })
+ *
+ * const GetCourse = ns.query("GetCourse", {
+ *   payload: z.object({ courseId: z.string() }),
+ * })
+ * ```
+ */
+export declare function withNamespace(namespace: string): {
+    /** Create a command descriptor in this namespace. */
+    command: {
+        <P extends z.ZodType>(name: string, def: {
+            payload: P;
+            version?: string;
+            routingKey?: string;
+        }): ReturnType<typeof createCommand<P>>;
+        <P extends z.ZodType, R extends z.ZodType>(name: string, def: {
+            payload: P;
+            result: R;
+            version?: string;
+            routingKey?: string;
+        }): ReturnType<typeof createCommand<P, R>>;
+    };
+    /** Create an event descriptor in this namespace. */
+    event<P extends z.ZodType>(name: string, def: {
+        payload: P;
+        version?: string;
+        tags?: (payload: z.infer<P>) => Tag[];
+    }): import("./descriptor.js").EventDescriptor<P>;
+    /** Create a query descriptor in this namespace. */
+    query: {
+        <P extends z.ZodType>(name: string, def: {
+            payload: P;
+            version?: string;
+        }): ReturnType<typeof createQuery<P>>;
+        <P extends z.ZodType, R extends z.ZodType>(name: string, def: {
+            payload: P;
+            result: R;
+            version?: string;
+        }): ReturnType<typeof createQuery<P, R>>;
+    };
+};
+//# sourceMappingURL=with-namespace.d.ts.map

package/dist/with-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-namespace.d.ts","sourceRoot":"","sources":["../src/with-namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EACL,OAAO,IAAI,aAAa,EAExB,KAAK,IAAI,WAAW,EACrB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM;IA8B3C,qDAAqD;;SA7BtC,CAAC,SAAS,CAAC,CAAC,OAAO,QAAQ,MAAM,OAAO;YACvD,OAAO,EAAE,CAAC,CAAA;YACV,OAAO,CAAC,EAAE,MAAM,CAAA;YAChB,UAAU,CAAC,EAAE,MAAM,CAAA;SACpB,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;SACtB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,QAAQ,MAAM,OAAO;YAC5E,OAAO,EAAE,CAAC,CAAA;YACV,MAAM,EAAE,CAAC,CAAA;YACT,OAAO,CAAC,EAAE,MAAM,CAAA;YAChB,UAAU,CAAC,EAAE,MAAM,CAAA;SACpB,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;;IAsBxC,oDAAoD;UAC9C,CAAC,SAAS,CAAC,CAAC,OAAO,QAAQ,MAAM,OAAO;QAC5C,OAAO,EAAE,CAAC,CAAA;QACV,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAA;KACtC;IAID,mDAAmD;;SA1BtC,CAAC,SAAS,CAAC,CAAC,OAAO,QAAQ,MAAM,OAAO;YACrD,OAAO,EAAE,CAAC,CAAA;YACV,OAAO,CAAC,EAAE,MAAM,CAAA;SACjB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;SACtB,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,QAAQ,MAAM,OAAO;YAC1E,OAAO,EAAE,CAAC,CAAA;YACV,MAAM,EAAE,CAAC,CAAA;YACT,OAAO,CAAC,EAAE,MAAM,CAAA;SACjB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;;EAqBzC"}

package/dist/with-namespace.js

@@ -0,0 +1,42 @@
+import { qn } from "@kronos-ts/common";
+import { command as createCommand, event as createEvent, query as createQuery, } from "./descriptor.js";
+/**
+ * Creates a namespace-scoped factory for message descriptors.
+ * Reduces repetition when defining many messages in the same bounded context.
+ *
+ * ```typescript
+ * const ns = withNamespace("university.courses")
+ *
+ * const CreateCourse = ns.command("CreateCourse", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ *
+ * const CourseCreated = ns.event("CourseCreated", {
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => [tag("courseId", p.courseId)],
+ * })
+ *
+ * const GetCourse = ns.query("GetCourse", {
+ *   payload: z.object({ courseId: z.string() }),
+ * })
+ * ```
+ */
+export function withNamespace(namespace) {
+    function command(name, def) {
+        return createCommand({ name: qn(namespace, name), ...def });
+    }
+    function query(name, def) {
+        return createQuery({ name: qn(namespace, name), ...def });
+    }
+    return {
+        /** Create a command descriptor in this namespace. */
+        command,
+        /** Create an event descriptor in this namespace. */
+        event(name, def) {
+            return createEvent({ name: qn(namespace, name), ...def });
+        },
+        /** Create a query descriptor in this namespace. */
+        query,
+    };
+}
+//# sourceMappingURL=with-namespace.js.map

package/dist/with-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-namespace.js","sourceRoot":"","sources":["../src/with-namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAY,MAAM,mBAAmB,CAAA;AAChD,OAAO,EACL,OAAO,IAAI,aAAa,EACxB,KAAK,IAAI,WAAW,EACpB,KAAK,IAAI,WAAW,GACrB,MAAM,iBAAiB,CAAA;AAGxB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAY7C,SAAS,OAAO,CAAC,IAAY,EAAE,GAA2B;QACxD,OAAO,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,EAAW,CAAC,CAAA;IACtE,CAAC;IAWD,SAAS,KAAK,CAAC,IAAY,EAAE,GAA2B;QACtD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,EAAW,CAAC,CAAA;IACpE,CAAC;IAED,OAAO;QACL,qDAAqD;QACrD,OAAO;QAEP,oDAAoD;QACpD,KAAK,CAAsB,IAAY,EAAE,GAIxC;YACC,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;QAC3D,CAAC;QAED,mDAAmD;QACnD,KAAK;KACN,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@kronos-ts/messaging",
+  "version": "0.1.0",
+  "description": "Messaging primitives for Kronos — commands, events, handlers, and event processors.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Theo Emanuelsson",
+  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/messaging#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KronosDB/kronos-ts.git",
+    "directory": "packages/messaging"
+  },
+  "bugs": {
+    "url": "https://github.com/KronosDB/kronos-ts/issues"
+  },
+  "keywords": [
+    "kronos",
+    "event-sourcing",
+    "cqrs",
+    "dcb",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./processing-state": "./src/processing-state.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.bench.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./processing-state": {
+        "types": "./dist/processing-state.d.ts",
+        "default": "./dist/processing-state.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@kronos-ts/common": "workspace:*",
+    "@kronos-ts/eventsourcing": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2"
+  }
+}

package/src/command-bus.ts

@@ -0,0 +1,34 @@
+import type { CommandMessage } from "./message.js"
+
+/**
+ * The command bus — low-level infrastructure for dispatching command messages
+ * to handlers. The bus is swappable: SimpleCommandBus for local, Axon Server connector
+ * for distributed.
+ *
+ * Users don't interact with the bus directly — they use the CommandGateway.
+ */
+export interface CommandBus {
+  /**
+   * Dispatch a fully-formed command message to its handler.
+   *
+   * The bus auto-nests via ALS (CTX-02): when called outside a UnitOfWork,
+   * `runInUoW` creates one; when called inside an active UoW (handler-internal
+   * re-dispatch), the active UoW is reused. No explicit context parameter is
+   * threaded.
+   */
+  dispatch(message: CommandMessage): Promise<unknown>
+
+  /**
+   * Subscribe a handler for the given command name. The handler is invoked
+   * inside the active UnitOfWork — module-level accessors
+   * (`getResource`, `setResource`, `on`, `onError`, …) read/write that UoW's
+   * ALS-backed state.
+   *
+   * Plan 03-04 (CTX-04 / D-34): handler signature dropped its `ctx`
+   * parameter. The ProcessingContext type is gone.
+   */
+  subscribe(
+    commandName: string,
+    handler: (message: CommandMessage) => Promise<unknown>,
+  ): void
+}