@kronos-ts/messaging 0.1.0

package/dist/dead-letter-queue.d.ts

@@ -0,0 +1,134 @@
+import type { EventMessage } from "./message.js";
+/**
+ * A dead letter — an event that failed processing and was parked
+ * for later retry or manual intervention.
+ */
+export interface DeadLetter {
+    /** The original event message that failed. */
+    readonly message: EventMessage;
+    /** The error that caused the failure. */
+    readonly cause: Error;
+    /** When this letter was first enqueued. */
+    readonly enqueuedAt: number;
+    /** When this letter was last touched (enqueued or requeued). */
+    readonly lastTouched: number;
+    /** Additional diagnostics metadata about the failure. */
+    readonly diagnostics: Record<string, unknown>;
+    /** The sequence identifier this letter belongs to. */
+    readonly sequenceIdentifier: string;
+}
+/**
+ * Decision on whether to enqueue a failed event as a dead letter.
+ */
+export interface EnqueueDecision {
+    /** Whether to enqueue the failed event. */
+    readonly shouldEnqueue: boolean;
+    /** Optional updated cause (may differ from original). */
+    readonly cause?: Error;
+    /** Additional diagnostics to attach. */
+    readonly diagnostics?: Record<string, unknown>;
+}
+/**
+ * Policy that determines whether a failed event should be dead-lettered.
+ */
+export interface EnqueuePolicy {
+    /**
+     * Decide whether to enqueue a failed event.
+     * @param letter The dead letter candidate
+     * @param cause The error that caused the failure
+     */
+    decide(letter: DeadLetter, cause: Error): EnqueueDecision;
+}
+/**
+ * Default policy: always enqueue with the original cause.
+ */
+export declare function alwaysEnqueuePolicy(): EnqueuePolicy;
+/**
+ * A sequenced dead letter queue that maintains ordering within sequences.
+ *
+ * Events in the same sequence (identified by `sequenceIdentifier`) are
+ * ordered by insertion. When a sequence has dead letters, subsequent
+ * events in that sequence are also dead-lettered to preserve ordering.
+ *
+ * Typical sequence identifier: aggregate ID or correlation ID.
+ *
+ * Database-backed implementations participate in the active UnitOfWork via
+ * the ALS-managed transaction (read through `getActiveTransaction()` /
+ * `getResource(TRANSACTION_KEY)`); no `ProcessingContext` parameter is
+ * threaded through the public surface.
+ */
+export interface SequencedDeadLetterQueue {
+    /**
+     * Enqueue a dead letter into the given sequence.
+     */
+    enqueue(letter: DeadLetter): Promise<void>;
+    /**
+     * Enqueue a dead letter only if the sequence already has dead letters.
+     * Used to block subsequent events in a failed sequence.
+     * The supplier is only called if the sequence exists (avoids creating
+     * unnecessary objects).
+     * Returns true if the letter was enqueued (sequence existed).
+     */
+    enqueueIfPresent(sequenceIdentifier: string, letterSupplier: () => DeadLetter): Promise<boolean>;
+    /**
+     * Remove a dead letter from the queue (successfully reprocessed).
+     */
+    evict(sequenceIdentifier: string, letter: DeadLetter): Promise<void>;
+    /**
+     * Re-insert a dead letter at the front of its sequence with updated properties.
+     */
+    requeue(letter: DeadLetter, update?: Partial<Pick<DeadLetter, "cause" | "diagnostics">>): Promise<void>;
+    /**
+     * Check if a sequence has any dead letters.
+     */
+    contains(sequenceIdentifier: string): Promise<boolean>;
+    /**
+     * Get all dead letters in a sequence, in insertion order.
+     */
+    deadLetterSequence(sequenceIdentifier: string): Promise<DeadLetter[]>;
+    /**
+     * Get all sequence identifiers that have dead letters.
+     */
+    sequenceIdentifiers(): Promise<string[]>;
+    /**
+     * Process the oldest dead letter sequence matching the filter.
+     * For each letter in the sequence:
+     * - If processingTask returns `{ shouldEnqueue: false }`: letter is evicted, continue
+     * - If processingTask returns `{ shouldEnqueue: true }`: letter is requeued, stop
+     *
+     * Returns true if a sequence was processed.
+     */
+    process(sequenceFilter: (sequenceId: string) => boolean, processingTask: (letter: DeadLetter) => Promise<EnqueueDecision>): Promise<boolean>;
+    /** Total number of dead letters across all sequences. */
+    size(): number;
+    /** Number of sequences with dead letters. */
+    amountOfSequences(): number;
+    /** Clear all dead letters. */
+    clear(): Promise<void>;
+    /**
+     * Check if the queue is full for the given sequence.
+     * Returns true if max sequences or max sequence size is reached.
+     */
+    isFull(sequenceIdentifier: string): boolean;
+}
+/**
+ * Creates an in-memory dead letter queue.
+ *
+ * @param options.maxSequences Maximum number of sequences (default: 1024)
+ * @param options.maxSequenceSize Maximum letters per sequence (default: 1024)
+ */
+export declare function createInMemoryDeadLetterQueue(options?: {
+    maxSequences?: number;
+    maxSequenceSize?: number;
+}): SequencedDeadLetterQueue;
+/**
+ * Thrown when the dead letter queue is full.
+ */
+export declare class DeadLetterQueueOverflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * Creates a DeadLetter from a failed event.
+ */
+export declare function createDeadLetter(message: EventMessage, cause: Error, sequenceIdentifier: string, diagnostics?: Record<string, unknown>): DeadLetter;
+//# sourceMappingURL=dead-letter-queue.d.ts.map

package/dist/dead-letter-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter-queue.d.ts","sourceRoot":"","sources":["../src/dead-letter-queue.ts"],"names":[],"mappings":"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"}

package/dist/dead-letter-queue.js

@@ -0,0 +1,176 @@
+/**
+ * Default policy: always enqueue with the original cause.
+ */
+export function alwaysEnqueuePolicy() {
+    return {
+        decide() {
+            return { shouldEnqueue: true };
+        },
+    };
+}
+/**
+ * Creates an in-memory dead letter queue.
+ *
+ * @param options.maxSequences Maximum number of sequences (default: 1024)
+ * @param options.maxSequenceSize Maximum letters per sequence (default: 1024)
+ */
+export function createInMemoryDeadLetterQueue(options) {
+    const maxSequences = options?.maxSequences ?? 1024;
+    const maxSequenceSize = options?.maxSequenceSize ?? 1024;
+    const sequences = new Map();
+    const processing = new Set();
+    return {
+        async enqueue(letter) {
+            const seq = sequences.get(letter.sequenceIdentifier);
+            if (seq) {
+                if (seq.length >= maxSequenceSize) {
+                    throw new DeadLetterQueueOverflowError(`sequence "${letter.sequenceIdentifier}" has reached max size ${maxSequenceSize}`);
+                }
+                seq.push(letter);
+            }
+            else {
+                if (sequences.size >= maxSequences) {
+                    throw new DeadLetterQueueOverflowError(`max sequences ${maxSequences} reached`);
+                }
+                sequences.set(letter.sequenceIdentifier, [letter]);
+            }
+        },
+        async enqueueIfPresent(sequenceIdentifier, letterSupplier) {
+            const seq = sequences.get(sequenceIdentifier);
+            if (!seq)
+                return false;
+            if (seq.length >= maxSequenceSize) {
+                throw new DeadLetterQueueOverflowError(`sequence "${sequenceIdentifier}" has reached max size ${maxSequenceSize}`);
+            }
+            seq.push(letterSupplier());
+            return true;
+        },
+        async evict(sequenceIdentifier, letter) {
+            const seq = sequences.get(sequenceIdentifier);
+            if (!seq)
+                return;
+            const idx = seq.indexOf(letter);
+            if (idx >= 0)
+                seq.splice(idx, 1);
+            if (seq.length === 0)
+                sequences.delete(sequenceIdentifier);
+        },
+        async requeue(letter, update) {
+            const seq = sequences.get(letter.sequenceIdentifier);
+            if (!seq)
+                return;
+            const updated = {
+                ...letter,
+                lastTouched: Date.now(),
+                cause: update?.cause ?? letter.cause,
+                diagnostics: update?.diagnostics
+                    ? { ...letter.diagnostics, ...update.diagnostics }
+                    : letter.diagnostics,
+            };
+            const idx = seq.indexOf(letter);
+            if (idx >= 0)
+                seq.splice(idx, 1);
+            seq.unshift(updated);
+        },
+        async contains(sequenceIdentifier) {
+            const seq = sequences.get(sequenceIdentifier);
+            return seq !== undefined && seq.length > 0;
+        },
+        async deadLetterSequence(sequenceIdentifier) {
+            return sequences.get(sequenceIdentifier) ?? [];
+        },
+        async sequenceIdentifiers() {
+            return [...sequences.keys()];
+        },
+        async process(sequenceFilter, processingTask) {
+            // Find oldest untaken sequence matching filter
+            let oldestId;
+            let oldestTime = Infinity;
+            for (const [id, letters] of sequences) {
+                if (processing.has(id))
+                    continue;
+                if (letters.length === 0)
+                    continue;
+                if (!sequenceFilter(id))
+                    continue;
+                const firstTouched = letters[0].lastTouched;
+                if (firstTouched < oldestTime) {
+                    oldestTime = firstTouched;
+                    oldestId = id;
+                }
+            }
+            if (!oldestId)
+                return false;
+            processing.add(oldestId);
+            try {
+                const letters = sequences.get(oldestId);
+                if (!letters)
+                    return false;
+                // Process letters in order — take a snapshot of current letters
+                const snapshot = [...letters];
+                for (const letter of snapshot) {
+                    const decision = await processingTask(letter);
+                    if (decision.shouldEnqueue) {
+                        // Requeue and stop — sequence is still blocked
+                        await this.requeue(letter, {
+                            cause: decision.cause,
+                            diagnostics: decision.diagnostics,
+                        });
+                        return true;
+                    }
+                    // Evict — successfully reprocessed
+                    await this.evict(oldestId, letter);
+                }
+                return true;
+            }
+            finally {
+                processing.delete(oldestId);
+            }
+        },
+        size() {
+            let total = 0;
+            for (const letters of sequences.values()) {
+                total += letters.length;
+            }
+            return total;
+        },
+        amountOfSequences() {
+            return sequences.size;
+        },
+        async clear() {
+            sequences.clear();
+            processing.clear();
+        },
+        isFull(sequenceIdentifier) {
+            const seq = sequences.get(sequenceIdentifier);
+            if (seq) {
+                return seq.length >= maxSequenceSize;
+            }
+            return sequences.size >= maxSequences;
+        },
+    };
+}
+/**
+ * Thrown when the dead letter queue is full.
+ */
+export class DeadLetterQueueOverflowError extends Error {
+    constructor(message) {
+        super(`Dead letter queue overflow: ${message}`);
+        this.name = "DeadLetterQueueOverflowError";
+    }
+}
+/**
+ * Creates a DeadLetter from a failed event.
+ */
+export function createDeadLetter(message, cause, sequenceIdentifier, diagnostics) {
+    const now = Date.now();
+    return {
+        message,
+        cause,
+        enqueuedAt: now,
+        lastTouched: now,
+        diagnostics: diagnostics ?? {},
+        sequenceIdentifier,
+    };
+}
+//# sourceMappingURL=dead-letter-queue.js.map

package/dist/dead-letter-queue.js.map

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

package/dist/dead-lettering-handler.d.ts

@@ -0,0 +1,42 @@
+import type { EventMessage } from "./message.js";
+import type { EventHandlerRegistration } from "./handler.js";
+import type { SequencedEvent } from "./event-source.js";
+import { type SequencedDeadLetterQueue, type EnqueuePolicy } from "./dead-letter-queue.js";
+/**
+ * Options for dead-lettering event handler wrapper.
+ */
+export interface DeadLetteringOptions {
+    /** The dead letter queue to use. */
+    queue: SequencedDeadLetterQueue;
+    /** Policy deciding whether to dead-letter a failed event. Default: always. */
+    policy?: EnqueuePolicy;
+    /**
+     * Extract a sequence identifier from an event. Events in the same
+     * sequence are ordered — if one fails, subsequent ones are blocked.
+     * Default: uses the first tag value or event name.
+     */
+    sequenceIdentifier?: (event: EventMessage) => string;
+}
+/**
+ * Wraps event delivery with dead-letter support.
+ *
+ * When a handler fails:
+ * 1. Creates a DeadLetter and consults the EnqueuePolicy
+ * 2. If policy says enqueue: adds to DLQ, continues with next event
+ * 3. If policy says don't enqueue: error is swallowed
+ *
+ * When processing an event whose sequence already has dead letters:
+ * - The event is automatically dead-lettered (sequence is blocked)
+ * - This preserves ordering within the sequence
+ */
+export declare function createDeadLetteringDelivery(options: DeadLetteringOptions): {
+    /**
+     * Deliver an event to handlers, with dead-letter support.
+     *
+     * The DLQ participates in any active transaction via ALS — both the
+     * caller and the DLQ implementation read transactional state from the
+     * UnitOfWork ALS store, no explicit ProcessingContext is threaded.
+     */
+    deliver(sequencedEvent: SequencedEvent, handlers: Array<EventHandlerRegistration<any>>): Promise<void>;
+};
+//# sourceMappingURL=dead-lettering-handler.d.ts.map

package/dist/dead-lettering-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-lettering-handler.d.ts","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAGnB,MAAM,wBAAwB,CAAA;AAE/B;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,KAAK,EAAE,wBAAwB,CAAA;IAC/B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAA;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB;IAQrE;;;;;;OAMG;4BAEe,cAAc,YACpB,KAAK,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC;EA2CnB"}

package/dist/dead-lettering-handler.js

@@ -0,0 +1,67 @@
+import { qualifiedNameToString } from "@kronos-ts/common";
+import { alwaysEnqueuePolicy, createDeadLetter, } from "./dead-letter-queue.js";
+/**
+ * Wraps event delivery with dead-letter support.
+ *
+ * When a handler fails:
+ * 1. Creates a DeadLetter and consults the EnqueuePolicy
+ * 2. If policy says enqueue: adds to DLQ, continues with next event
+ * 3. If policy says don't enqueue: error is swallowed
+ *
+ * When processing an event whose sequence already has dead letters:
+ * - The event is automatically dead-lettered (sequence is blocked)
+ * - This preserves ordering within the sequence
+ */
+export function createDeadLetteringDelivery(options) {
+    const { queue, policy = alwaysEnqueuePolicy(), sequenceIdentifier = defaultSequenceIdentifier, } = options;
+    return {
+        /**
+         * Deliver an event to handlers, with dead-letter support.
+         *
+         * The DLQ participates in any active transaction via ALS — both the
+         * caller and the DLQ implementation read transactional state from the
+         * UnitOfWork ALS store, no explicit ProcessingContext is threaded.
+         */
+        async deliver(sequencedEvent, handlers) {
+            const event = sequencedEvent.event;
+            const seqId = sequenceIdentifier(event);
+            // If this sequence already has dead letters, block this event too
+            const blocked = await queue.enqueueIfPresent(seqId, () => createDeadLetter(event, new Error("Blocked: previous event in sequence failed"), seqId, { blocked: true, position: Number(sequencedEvent.sequence) }));
+            if (blocked)
+                return;
+            // Try to deliver to all handlers
+            for (const reg of handlers) {
+                try {
+                    await reg.handler(event.payload, event.metadata);
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    const letter = createDeadLetter(event, error, seqId, {
+                        position: Number(sequencedEvent.sequence),
+                        handlerName: qualifiedNameToString(reg.descriptor.name),
+                    });
+                    const decision = policy.decide(letter, error);
+                    if (decision.shouldEnqueue) {
+                        await queue.enqueue({
+                            ...letter,
+                            cause: decision.cause ?? letter.cause,
+                            diagnostics: decision.diagnostics
+                                ? { ...letter.diagnostics, ...decision.diagnostics }
+                                : letter.diagnostics,
+                        });
+                    }
+                    // Error is consumed by DLQ — don't propagate
+                    return;
+                }
+            }
+        },
+    };
+}
+function defaultSequenceIdentifier(event) {
+    // Use first tag value if available, otherwise event name
+    if (event.tags && event.tags.length > 0) {
+        return event.tags[0].value;
+    }
+    return qualifiedNameToString(event.name);
+}
+//# sourceMappingURL=dead-lettering-handler.js.map

package/dist/dead-lettering-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-lettering-handler.js","sourceRoot":"","sources":["../src/dead-lettering-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAIzD,OAAO,EAGL,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,wBAAwB,CAAA;AAkB/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAA6B;IACvE,MAAM,EACJ,KAAK,EACL,MAAM,GAAG,mBAAmB,EAAE,EAC9B,kBAAkB,GAAG,yBAAyB,GAC/C,GAAG,OAAO,CAAA;IAEX,OAAO;QACL;;;;;;WAMG;QACH,KAAK,CAAC,OAAO,CACX,cAA8B,EAC9B,QAA8C;YAE9C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAA;YAClC,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;YAEvC,kEAAkE;YAClE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAC1C,KAAK,EACL,GAAG,EAAE,CAAC,gBAAgB,CACpB,KAAK,EACL,IAAI,KAAK,CAAC,4CAA4C,CAAC,EACvD,KAAK,EACL,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAC7D,CACF,CAAA;YACD,IAAI,OAAO;gBAAE,OAAM;YAEnB,iCAAiC;YACjC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;gBAClD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;oBACjE,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;wBACnD,QAAQ,EAAE,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC;wBACzC,WAAW,EAAE,qBAAqB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;qBACxD,CAAC,CAAA;oBAEF,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;oBAC7C,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;wBAC3B,MAAM,KAAK,CAAC,OAAO,CAAC;4BAClB,GAAG,MAAM;4BACT,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;4BACrC,WAAW,EAAE,QAAQ,CAAC,WAAW;gCAC/B,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,WAAW,EAAE;gCACpD,CAAC,CAAC,MAAM,CAAC,WAAW;yBACvB,CAAC,CAAA;oBACJ,CAAC;oBACD,6CAA6C;oBAC7C,OAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAmB;IACpD,yDAAyD;IACzD,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,CAAA;IAC7B,CAAC;IACD,OAAO,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AAC1C,CAAC"}

package/dist/descriptor.d.ts

@@ -0,0 +1,135 @@
+import type { z } from "zod";
+import type { QualifiedName, Tag } from "@kronos-ts/common";
+/**
+ * Describes a command message type — its name, payload schema,
+ * and optional result schema for typed gateway returns.
+ */
+export interface CommandDescriptor<P extends z.ZodType = z.ZodType, R extends z.ZodType | undefined = undefined> {
+    readonly kind: "command";
+    readonly name: QualifiedName;
+    /** Version of the command. Default: "1.0". */
+    readonly version: string;
+    readonly payload: P;
+    /** Optional result schema — enables typed return from `commandGateway.send()`. */
+    readonly result?: R;
+    /**
+     * The payload field that contains the routing key for distributed command routing.
+     *
+     * Used by the command gateway to extract the routing key before dispatch.
+     * Commands with the same routing key are routed to the same handler instance.
+     */
+    readonly routingKey?: string;
+}
+/**
+ * Describes an event message type — its name, payload schema, and tag derivation.
+ * Tags define how events are indexed for criteria-based sourcing.
+ */
+export interface EventDescriptor<P extends z.ZodType = z.ZodType> {
+    readonly kind: "event";
+    readonly name: QualifiedName;
+    readonly version: string;
+    readonly payload: P;
+    readonly tags?: (payload: z.infer<P>) => Tag[];
+}
+/**
+ * Describes a query message type — its name, payload schema,
+ * and optional result schema for typed gateway returns.
+ */
+export interface QueryDescriptor<P extends z.ZodType = z.ZodType, R extends z.ZodType | undefined = undefined> {
+    readonly kind: "query";
+    readonly name: QualifiedName;
+    /** Version of the query. Default: "1.0". */
+    readonly version: string;
+    readonly payload: P;
+    /** Optional result schema — enables typed return from `queryGateway.query()`. */
+    readonly result?: R;
+}
+/** Any message descriptor. */
+export type MessageDescriptor = CommandDescriptor | EventDescriptor | QueryDescriptor;
+/**
+ * Creates a command descriptor.
+ *
+ * Without result schema (void command):
+ * ```
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   routingKey: "courseId",
+ * })
+ * ```
+ *
+ * With result schema (typed return):
+ * ```
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ courseId: z.string() }),
+ *   routingKey: "courseId",
+ * })
+ * // commandGateway.send(CreateCourse, { courseId: "cs-101" }) → Promise<{ courseId: string }>
+ * ```
+ */
+export declare function command<P extends z.ZodType>(def: {
+    name: QualifiedName;
+    version?: string;
+    payload: P;
+    routingKey?: string;
+}): CommandDescriptor<P, undefined>;
+export declare function command<P extends z.ZodType, R extends z.ZodType>(def: {
+    name: QualifiedName;
+    version?: string;
+    payload: P;
+    result: R;
+    routingKey?: string;
+}): CommandDescriptor<P, R>;
+/**
+ * Creates an event descriptor.
+ *
+ * Tags can return `Tag[]` or a `Record<string, string>`:
+ * ```typescript
+ * event({
+ *   name: qn("university", "CourseCreated"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => ({ courseId: p.courseId }),
+ * })
+ * ```
+ */
+export declare function event<P extends z.ZodType>(def: {
+    name: QualifiedName;
+    version?: string;
+    payload: P;
+    tags?: (payload: z.infer<P>) => Tag[] | Record<string, string>;
+}): EventDescriptor<P>;
+/**
+ * Creates a query descriptor.
+ *
+ * Without result schema:
+ * ```
+ * const GetCourse = query({
+ *   name: qn("university", "GetCourseView"),
+ *   payload: z.object({ courseId: z.string() }),
+ * })
+ * ```
+ *
+ * With result schema (typed return):
+ * ```
+ * const GetCourse = query({
+ *   name: qn("university", "GetCourseView"),
+ *   payload: z.object({ courseId: z.string() }),
+ *   result: z.object({ courseId: z.string(), name: z.string() }),
+ * })
+ * // queryGateway.query(GetCourse, { courseId: "cs-101" }) → Promise<{ courseId: string, name: string }>
+ * ```
+ */
+export declare function query<P extends z.ZodType>(def: {
+    name: QualifiedName;
+    version?: string;
+    payload: P;
+}): QueryDescriptor<P, undefined>;
+export declare function query<P extends z.ZodType, R extends z.ZodType>(def: {
+    name: QualifiedName;
+    version?: string;
+    payload: P;
+    result: R;
+}): QueryDescriptor<P, R>;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/descriptor.d.ts.map

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

package/dist/descriptor.js

@@ -0,0 +1,36 @@
+import { tagsFromRecord } from "@kronos-ts/common";
+export function command(def) {
+    return { kind: "command", version: def.version ?? "1.0", ...def };
+}
+/**
+ * Creates an event descriptor.
+ *
+ * Tags can return `Tag[]` or a `Record<string, string>`:
+ * ```typescript
+ * event({
+ *   name: qn("university", "CourseCreated"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   tags: (p) => ({ courseId: p.courseId }),
+ * })
+ * ```
+ */
+export function event(def) {
+    const rawTags = def.tags;
+    const tags = rawTags
+        ? (payload) => {
+            const result = rawTags(payload);
+            return Array.isArray(result) ? result : tagsFromRecord(result);
+        }
+        : undefined;
+    return {
+        kind: "event",
+        name: def.name,
+        version: def.version ?? "1.0",
+        payload: def.payload,
+        ...(tags ? { tags } : {}),
+    };
+}
+export function query(def) {
+    return { kind: "query", version: def.version ?? "1.0", ...def };
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../src/descriptor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAmGlD,MAAM,UAAU,OAAO,CAAC,GAAQ;IAC9B,OAAO,EAAE,IAAI,EAAE,SAAkB,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK,EAAE,GAAG,GAAG,EAAE,CAAA;AAC5E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAsB,GAK1C;IACC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAA;IACxB,MAAM,IAAI,GAAiD,OAAO;QAChE,CAAC,CAAC,CAAC,OAAmB,EAAS,EAAE;YAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;YAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;QAChE,CAAC;QACH,CAAC,CAAC,SAAS,CAAA;IACb,OAAO;QACL,IAAI,EAAE,OAAgB;QACtB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK;QAC7B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1B,CAAA;AACH,CAAC;AAoCD,MAAM,UAAU,KAAK,CAAC,GAAQ;IAC5B,OAAO,EAAE,IAAI,EAAE,OAAgB,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK,EAAE,GAAG,GAAG,EAAE,CAAA;AAC1E,CAAC"}

package/dist/emit-update.d.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+import { type ResourceKey } from "@kronos-ts/common";
+import type { QueryBus } from "./query-bus.js";
+import type { QueryDescriptor } from "./descriptor.js";
+/** Emit a subscription-query update from within the current processing context. */
+export interface EmitUpdateFunction {
+    <Q extends z.ZodType>(query: QueryDescriptor<Q>, filter: (query: z.infer<Q>) => boolean, update: unknown): void;
+}
+/**
+ * Resource key for the query bus component.
+ * Written by handling modules + processors at handler-invocation entry (D-44).
+ */
+export declare const QUERY_BUS_KEY: ResourceKey<QueryBus>;
+/**
+ * Plan 04-01 (HDL-02 / D-42): module-level emitUpdate.
+ *
+ * Throws NoActiveUnitOfWork outside a UoW; throws WrongUoWPhase outside
+ * INVOCATION phase (D-43 mutator guard). Emits a subscription query update
+ * through the active query bus.
+ */
+export declare const emitUpdate: EmitUpdateFunction;
+//# sourceMappingURL=emit-update.d.ts.map

package/dist/emit-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-update.d.ts","sourceRoot":"","sources":["../src/emit-update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAExF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAClB,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,EACtC,MAAM,EAAE,OAAO,GACd,IAAI,CAAA;CACR;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,QAAQ,CAA2B,CAAA;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,kBAMxB,CAAA"}