@kronos-ts/messaging 0.1.0

package/dist/tracking-event-processor.d.ts

@@ -0,0 +1,72 @@
+import type { EventHandlerDefinition } from "./event-handler.js";
+import type { StreamableEventSource } from "./event-source.js";
+import type { UoWRunner } from "./unit-of-work.js";
+import type { TokenStore } from "./token-store.js";
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.js";
+import type { CommandBus } from "./command-bus.js";
+import type { QueryBus } from "./query-bus.js";
+/**
+ * A tracking event processor that reads events from a streamable event source
+ * and delivers them to registered event handlers.
+ *
+ * Uses {@link StreamableEventSource.open} to get a persistent {@link MessageStream}.
+ * Each batch of events is processed within a UnitOfWork, enabling
+ * transactional event processing and coordinated token updates.
+ *
+ * Supports replay via {@link resetTokens} — the processor can be stopped,
+ * reset to a starting position, and restarted.
+ */
+export interface TrackingEventProcessor {
+    readonly name: string;
+    readonly running: boolean;
+    /** Current effective position in the event stream. */
+    readonly position: bigint;
+    /** Whether the processor is currently replaying events. */
+    readonly replaying: boolean;
+    start(): Promise<void>;
+    stop(): void;
+    /**
+     * Reset the processor to replay events from a starting position.
+     * The processor must be stopped before calling this.
+     */
+    resetTokens(startPosition?: bigint, resetContext?: unknown): Promise<void>;
+}
+export interface TrackingEventProcessorOptions {
+    name: string;
+    eventSource: StreamableEventSource;
+    eventHandlers: ReadonlyArray<EventHandlerDefinition>;
+    /** State manager injected into ALS at handler-invocation entry (D-44). */
+    stateManager?: unknown;
+    /** Command bus injected into ALS at handler-invocation entry (D-44). */
+    commandBus?: CommandBus;
+    /** Query bus injected into ALS at handler-invocation entry (D-44). */
+    queryBus?: QueryBus;
+    /** Optional per-event callback fired inside the UoW before handler invocation (e.g. monitoring). */
+    onEventDelivery?: () => void;
+    unitOfWorkRunner?: UoWRunner;
+    tokenStore?: TokenStore;
+    /** Polling interval when no events are available (ms). Default: 500. */
+    pollingIntervalMs?: number;
+    batchSize?: number;
+    errorHandler?: EventProcessingErrorHandler;
+    /** Optional handler enhancer applied to all event handlers at setup time. */
+    handlerEnhancer?: HandlerEnhancerDefinition;
+    /** Reset callback invoked from resetTokens(). */
+    onReset?: () => Promise<void> | void;
+}
+/**
+ * Determines what happens when an event handler fails.
+ */
+export interface EventProcessingErrorHandler {
+    handleError(error: unknown, eventName: string, position: bigint): void | Promise<void>;
+}
+/**
+ * Logs errors and continues processing. Default behavior.
+ */
+export declare function loggingErrorHandler(processorName: string): EventProcessingErrorHandler;
+/**
+ * Rethrows errors, aborting the current batch and triggering rollback.
+ */
+export declare function propagatingErrorHandler(): EventProcessingErrorHandler;
+export declare function createTrackingEventProcessor(options: TrackingEventProcessorOptions): TrackingEventProcessor;
+//# sourceMappingURL=tracking-event-processor.d.ts.map

package/dist/tracking-event-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-event-processor.d.ts","sourceRoot":"","sources":["../src/tracking-event-processor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAiC,MAAM,mBAAmB,CAAA;AAC7F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAWlD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAK9C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,IAAI,CAAA;IACZ;;;OAGG;IACH,WAAW,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3E;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,qBAAqB,CAAA;IAClC,aAAa,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAA;IACpD,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,wEAAwE;IACxE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,oGAAoG;IACpG,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,gBAAgB,CAAC,EAAE,SAAS,CAAA;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,6EAA6E;IAC7E,eAAe,CAAC,EAAE,yBAAyB,CAAA;IAC3C,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,2BAA2B,CAStF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,2BAA2B,CAMrE;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,sBAAsB,CAkOxB"}

package/dist/tracking-event-processor.js

@@ -0,0 +1,223 @@
+import { emptyMetadata, qualifiedNameToString } from "@kronos-ts/common";
+import { runInNewUoW } from "./unit-of-work.js";
+import { globalSequenceToken, replayToken, isReplayToken, isReplaying, advanceToken, } from "./tracking-token.js";
+import { REPLAY_STATE_KEY } from "./replay-token.js";
+import { setResource, onPrepareCommit } from "./processing-state.js";
+import { STATE_MANAGER_KEY } from "@kronos-ts/eventsourcing";
+import { COMMAND_BUS_KEY } from "./send.js";
+import { QUERY_BUS_KEY } from "./emit-update.js";
+/**
+ * Logs errors and continues processing. Default behavior.
+ */
+export function loggingErrorHandler(processorName) {
+    return {
+        handleError(error, eventName, position) {
+            console.error(`Event processor "${processorName}": handler failed for "${eventName}" at position ${position}:`, error);
+        },
+    };
+}
+/**
+ * Rethrows errors, aborting the current batch and triggering rollback.
+ */
+export function propagatingErrorHandler() {
+    return {
+        handleError(error) {
+            throw error;
+        },
+    };
+}
+export function createTrackingEventProcessor(options) {
+    const { name, eventSource, eventHandlers, stateManager, commandBus, queryBus, onEventDelivery, unitOfWorkRunner = runInNewUoW, tokenStore, pollingIntervalMs = 500, batchSize = 100, errorHandler = loggingErrorHandler(name), handlerEnhancer, onReset, } = options;
+    const segment = 0;
+    const handlerMap = new Map();
+    for (const reg of eventHandlers) {
+        const eventName = qualifiedNameToString(reg.descriptor.name);
+        if (!handlerMap.has(eventName)) {
+            handlerMap.set(eventName, []);
+        }
+        const enhanced = handlerEnhancer
+            ? {
+                ...reg,
+                handler: handlerEnhancer.wrapHandler(reg.handler, {
+                    messageType: "event",
+                    messageName: eventName,
+                    handlerGroup: name,
+                }),
+            }
+            : reg;
+        handlerMap.get(eventName).push(enhanced);
+    }
+    let token = globalSequenceToken(0n);
+    let isRunning = false;
+    let stream = null;
+    let pollTimer = null;
+    let processing = false;
+    async function initialize() {
+        if (tokenStore) {
+            await tokenStore.initializeSegments(name, 1);
+            const stored = await tokenStore.get(name, segment);
+            if (stored !== undefined) {
+                token = stored;
+            }
+        }
+    }
+    function openStream() {
+        stream = eventSource.open({ position: token.position() });
+        stream.setCallback(() => {
+            if (isRunning && !processing) {
+                scheduleImmediate();
+            }
+        });
+    }
+    async function poll() {
+        if (!isRunning || processing)
+            return;
+        processing = true;
+        try {
+            if (!stream) {
+                openStream();
+            }
+            // Check for stream errors — reopen if needed
+            if (stream.error()) {
+                console.error(`Event processor "${name}": stream error, reopening:`, stream.error());
+                stream.close();
+                stream = null;
+                openStream();
+                processing = false;
+                return;
+            }
+            const batch = [];
+            let event = stream.next();
+            while (event && batch.length < batchSize) {
+                batch.push(event);
+                if (batch.length < batchSize && stream.hasNextAvailable()) {
+                    event = stream.next();
+                }
+                else {
+                    break;
+                }
+            }
+            if (batch.length > 0) {
+                await processBatch(batch);
+                if (isRunning) {
+                    if (stream.hasNextAvailable()) {
+                        scheduleImmediate();
+                    }
+                    // else: stream callback will wake us when events arrive
+                }
+            }
+            else {
+                // If replay is done and no more events, unwrap
+                if (isReplayToken(token)) {
+                    token = globalSequenceToken(token.position());
+                    if (tokenStore) {
+                        await tokenStore.store(name, segment, token);
+                    }
+                }
+                // No events available — wait for callback or poll again after interval
+                if (isRunning) {
+                    pollTimer = setTimeout(poll, pollingIntervalMs);
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Event processor "${name}" error during poll:`, err);
+            if (isRunning)
+                pollTimer = setTimeout(poll, pollingIntervalMs * 2);
+        }
+        finally {
+            processing = false;
+        }
+    }
+    async function processBatch(batch) {
+        let batchEndToken = token;
+        await unitOfWorkRunner(emptyMetadata(), async () => {
+            for (const sequencedEvent of batch) {
+                setResource(REPLAY_STATE_KEY, { replaying: isReplaying(batchEndToken) });
+                await deliverEvent(sequencedEvent);
+                batchEndToken = advanceToken(batchEndToken, sequencedEvent.sequence + 1n);
+            }
+            if (tokenStore) {
+                onPrepareCommit(async () => {
+                    await tokenStore.store(name, segment, batchEndToken);
+                    await tokenStore.extendClaim(name, segment, name);
+                });
+            }
+        });
+        token = batchEndToken;
+    }
+    async function deliverEvent(sequencedEvent) {
+        const event = sequencedEvent.event;
+        const eventName = qualifiedNameToString(event.name);
+        const handlers = handlerMap.get(eventName);
+        if (!handlers || handlers.length === 0)
+            return;
+        // D-44 wiring: write framework components into ALS at per-event invocation entry.
+        if (stateManager !== undefined)
+            setResource(STATE_MANAGER_KEY, stateManager);
+        if (commandBus !== undefined)
+            setResource(COMMAND_BUS_KEY, commandBus);
+        if (queryBus !== undefined)
+            setResource(QUERY_BUS_KEY, queryBus);
+        // Optional per-event callback (e.g. monitoring hooks registered inside the UoW).
+        if (onEventDelivery)
+            onEventDelivery();
+        for (const reg of handlers) {
+            try {
+                await reg.handler(event.payload, event.metadata);
+            }
+            catch (err) {
+                await errorHandler.handleError(err, eventName, sequencedEvent.sequence);
+            }
+        }
+    }
+    function scheduleImmediate() {
+        if (pollTimer !== null) {
+            clearTimeout(pollTimer);
+        }
+        pollTimer = setTimeout(poll, 0);
+    }
+    return {
+        get name() { return name; },
+        get running() { return isRunning; },
+        get position() { return token.position(); },
+        get replaying() { return isReplaying(token); },
+        async start() {
+            if (isRunning)
+                return;
+            await initialize();
+            isRunning = true;
+            poll();
+        },
+        stop() {
+            isRunning = false;
+            if (pollTimer !== null) {
+                clearTimeout(pollTimer);
+                pollTimer = null;
+            }
+            if (stream) {
+                stream.close();
+                stream = null;
+            }
+        },
+        async resetTokens(startPosition = 0n, resetContext) {
+            if (isRunning) {
+                throw new Error(`Processor "${name}" must be stopped before resetting tokens`);
+            }
+            const headPosition = await eventSource.getHeadPosition();
+            if (headPosition <= startPosition) {
+                token = globalSequenceToken(startPosition);
+            }
+            else {
+                token = replayToken(globalSequenceToken(headPosition), globalSequenceToken(startPosition), resetContext);
+            }
+            if (tokenStore) {
+                await tokenStore.store(name, segment, token);
+            }
+            if (onReset) {
+                await onReset();
+            }
+        },
+    };
+}
+//# sourceMappingURL=tracking-event-processor.js.map

package/dist/tracking-event-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-event-processor.js","sourceRoot":"","sources":["../src/tracking-event-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAKxE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG/C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,GACb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAIpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AA4DhD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAqB;IACvD,OAAO;QACL,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ;YACpC,OAAO,CAAC,KAAK,CACX,oBAAoB,aAAa,0BAA0B,SAAS,iBAAiB,QAAQ,GAAG,EAChG,KAAK,CACN,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,WAAW,CAAC,KAAK;YACf,MAAM,KAAK,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,OAAsC;IAEtC,MAAM,EACJ,IAAI,EACJ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,GAAG,WAAW,EAC9B,UAAU,EACV,iBAAiB,GAAG,GAAG,EACvB,SAAS,GAAG,GAAG,EACf,YAAY,GAAG,mBAAmB,CAAC,IAAI,CAAC,EACxC,eAAe,EACf,OAAO,GACR,GAAG,OAAO,CAAA;IAEX,MAAM,OAAO,GAAG,CAAC,CAAA;IAEjB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAgD,CAAA;IAC1E,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,qBAAqB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QAC5D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;QAC/B,CAAC;QACD,MAAM,QAAQ,GAAG,eAAe;YAC9B,CAAC,CAAC;gBACE,GAAG,GAAG;gBACN,OAAO,EAAE,eAAe,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE;oBAChD,WAAW,EAAE,OAAgB;oBAC7B,WAAW,EAAE,SAAS;oBACtB,YAAY,EAAE,IAAI;iBACnB,CAAC;aACH;YACH,CAAC,CAAC,GAAG,CAAA;QACP,UAAU,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC,QAAyC,CAAC,CAAA;IAC5E,CAAC;IAED,IAAI,KAAK,GAAkB,mBAAmB,CAAC,EAAE,CAAC,CAAA;IAClD,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,IAAI,MAAM,GAAyC,IAAI,CAAA;IACvD,IAAI,SAAS,GAAyC,IAAI,CAAA;IAC1D,IAAI,UAAU,GAAG,KAAK,CAAA;IAEtB,KAAK,UAAU,UAAU;QACvB,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,UAAU,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;YAC5C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YAClD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,KAAK,GAAG,MAAM,CAAA;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,UAAU;QACjB,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;QACzD,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YACtB,IAAI,SAAS,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC7B,iBAAiB,EAAE,CAAA;YACrB,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,UAAU,IAAI;QACjB,IAAI,CAAC,SAAS,IAAI,UAAU;YAAE,OAAM;QACpC,UAAU,GAAG,IAAI,CAAA;QAEjB,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,UAAU,EAAE,CAAA;YACd,CAAC;YAED,6CAA6C;YAC7C,IAAI,MAAO,CAAC,KAAK,EAAE,EAAE,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,6BAA6B,EAAE,MAAO,CAAC,KAAK,EAAE,CAAC,CAAA;gBACrF,MAAO,CAAC,KAAK,EAAE,CAAA;gBACf,MAAM,GAAG,IAAI,CAAA;gBACb,UAAU,EAAE,CAAA;gBACZ,UAAU,GAAG,KAAK,CAAA;gBAClB,OAAM;YACR,CAAC;YAED,MAAM,KAAK,GAAqB,EAAE,CAAA;YAClC,IAAI,KAAK,GAAG,MAAO,CAAC,IAAI,EAAE,CAAA;YAC1B,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBACzC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACjB,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,IAAI,MAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;oBAC3D,KAAK,GAAG,MAAO,CAAC,IAAI,EAAE,CAAA;gBACxB,CAAC;qBAAM,CAAC;oBACN,MAAK;gBACP,CAAC;YACH,CAAC;YAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,YAAY,CAAC,KAAK,CAAC,CAAA;gBACzB,IAAI,SAAS,EAAE,CAAC;oBACd,IAAI,MAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;wBAC/B,iBAAiB,EAAE,CAAA;oBACrB,CAAC;oBACD,wDAAwD;gBAC1D,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,+CAA+C;gBAC/C,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,KAAK,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAA;oBAC7C,IAAI,UAAU,EAAE,CAAC;wBACf,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;oBAC9C,CAAC;gBACH,CAAC;gBACD,uEAAuE;gBACvE,IAAI,SAAS,EAAE,CAAC;oBACd,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;gBACjD,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,sBAAsB,EAAE,GAAG,CAAC,CAAA;YAClE,IAAI,SAAS;gBAAE,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,CAAC,CAAA;QACpE,CAAC;gBAAS,CAAC;YACT,UAAU,GAAG,KAAK,CAAA;QACpB,CAAC;IACH,CAAC;IAED,KAAK,UAAU,YAAY,CAAC,KAAuB;QACjD,IAAI,aAAa,GAAkB,KAAK,CAAA;QAExC,MAAM,gBAAgB,CAAC,aAAa,EAAE,EAAE,KAAK,IAAI,EAAE;YACjD,KAAK,MAAM,cAAc,IAAI,KAAK,EAAE,CAAC;gBACnC,WAAW,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC,CAAA;gBAExE,MAAM,YAAY,CAAC,cAAc,CAAC,CAAA;gBAElC,aAAa,GAAG,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAA;YAC3E,CAAC;YAED,IAAI,UAAU,EAAE,CAAC;gBACf,eAAe,CAAC,KAAK,IAAI,EAAE;oBACzB,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,CAAA;oBACpD,MAAM,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;gBACnD,CAAC,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,KAAK,GAAG,aAAa,CAAA;IACvB,CAAC;IAED,KAAK,UAAU,YAAY,CAAC,cAA8B;QACxD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAA;QAClC,MAAM,SAAS,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACnD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QAC1C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAE9C,kFAAkF;QAClF,IAAI,YAAY,KAAK,SAAS;YAAE,WAAW,CAAC,iBAAiB,EAAE,YAAmB,CAAC,CAAA;QACnF,IAAI,UAAU,KAAK,SAAS;YAAE,WAAW,CAAC,eAAe,EAAE,UAAU,CAAC,CAAA;QACtE,IAAI,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;QAChE,iFAAiF;QACjF,IAAI,eAAe;YAAE,eAAe,EAAE,CAAA;QAEtC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;YAClD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;YACzE,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,iBAAiB;QACxB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,YAAY,CAAC,SAAS,CAAC,CAAA;QACzB,CAAC;QACD,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IACjC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,KAAK,OAAO,IAAI,CAAA,CAAC,CAAC;QAC1B,IAAI,OAAO,KAAK,OAAO,SAAS,CAAA,CAAC,CAAC;QAClC,IAAI,QAAQ,KAAK,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAA,CAAC,CAAC;QAC1C,IAAI,SAAS,KAAK,OAAO,WAAW,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC;QAE7C,KAAK,CAAC,KAAK;YACT,IAAI,SAAS;gBAAE,OAAM;YACrB,MAAM,UAAU,EAAE,CAAA;YAClB,SAAS,GAAG,IAAI,CAAA;YAChB,IAAI,EAAE,CAAA;QACR,CAAC;QAED,IAAI;YACF,SAAS,GAAG,KAAK,CAAA;YACjB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBACvB,YAAY,CAAC,SAAS,CAAC,CAAA;gBACvB,SAAS,GAAG,IAAI,CAAA;YAClB,CAAC;YACD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,KAAK,EAAE,CAAA;gBACd,MAAM,GAAG,IAAI,CAAA;YACf,CAAC;QACH,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,gBAAwB,EAAE,EAAE,YAAsB;YAClE,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,2CAA2C,CAAC,CAAA;YAChF,CAAC;YAED,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,eAAe,EAAE,CAAA;YAExD,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;gBAClC,KAAK,GAAG,mBAAmB,CAAC,aAAa,CAAC,CAAA;YAC5C,CAAC;iBAAM,CAAC;gBACN,KAAK,GAAG,WAAW,CACjB,mBAAmB,CAAC,YAAY,CAAC,EACjC,mBAAmB,CAAC,aAAa,CAAC,EAClC,YAAY,CACb,CAAA;YACH,CAAC;YAED,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;YAC9C,CAAC;YAED,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,EAAE,CAAA;YACjB,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tracking-token.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A tracking token represents a processor's position in an event stream.
+ *
+ * This interface is extensible — event store implementations can define
+ * their own token types (e.g., a PostgreSQL extension might track
+ * commit timestamps alongside sequence positions).
+ *
+ * The framework ships two built-in implementations:
+ * - `GlobalSequenceToken` — for sequential event stores (in-memory, Axon Server)
+ * - `ReplayToken` — wraps any token to mark replay-in-progress state
+ *
+ * Tokens are immutable. All operations return new instances.
+ */
+export interface TrackingToken {
+    /**
+     * Discriminant for type narrowing and serialization.
+     * Each token implementation has a unique kind string.
+     */
+    readonly kind: string;
+    /**
+     * The effective read position in the event stream.
+     * Used by the event source to know where to start reading.
+     */
+    position(): bigint;
+    /**
+     * Does this token's position include all events covered by the other?
+     * Returns true if every event that `other` has seen, this token has also seen.
+     *
+     * Used for replay completion detection and segment merging.
+     */
+    covers(other: TrackingToken): boolean;
+    /**
+     * Create a token representing the lower bound of this and another token.
+     * When opening a shared stream for multiple segments, use the lower bound
+     * to ensure no events are missed by any segment.
+     */
+    lowerBound(other: TrackingToken): TrackingToken;
+    /**
+     * Create a token representing the upper bound of this and another token.
+     * Represents the furthest position — used for segment merging.
+     */
+    upperBound(other: TrackingToken): TrackingToken;
+    /**
+     * Check if this token represents the same position as the other.
+     * Default: `this.covers(other) && other.covers(this)`.
+     */
+    samePositionAs(other: TrackingToken): boolean;
+}
+export interface GlobalSequenceToken extends TrackingToken {
+    readonly kind: "global-sequence";
+    readonly sequence: bigint;
+}
+/**
+ * Creates a token for a global-sequence event store (monotonically increasing positions).
+ * This is the default token type for in-memory stores and Axon Server.
+ */
+export declare function globalSequenceToken(sequence: bigint): GlobalSequenceToken;
+/**
+ * Sentinel token representing the beginning of the event stream.
+ * A processor starting with FIRST_TOKEN will read from position 0.
+ */
+export declare const FIRST_TOKEN: TrackingToken;
+/**
+ * Sentinel token representing the tail of the event stream.
+ * A processor starting with LATEST_TOKEN will skip all existing events
+ * and only process new events appended after startup.
+ */
+export declare const LATEST_TOKEN: TrackingToken;
+export interface ReplayToken extends TrackingToken {
+    readonly kind: "replay";
+    /** The wrapped token representing current progress during replay. */
+    readonly currentToken: TrackingToken;
+    /** The token representing the position when reset was triggered. Events before this are replayed. */
+    readonly tokenAtReset: TrackingToken;
+    /** Optional user-provided context (e.g., reason for the reset). */
+    readonly resetContext?: unknown;
+}
+/**
+ * Creates a replay token that wraps another token to mark replay-in-progress.
+ *
+ * During replay, events are re-delivered from `currentToken` up to `tokenAtReset`.
+ * Once `currentToken.covers(tokenAtReset)`, the replay is complete and the
+ * token unwraps to the current position.
+ *
+ * @param tokenAtReset The head position when reset was triggered
+ * @param currentToken Where replay is currently reading from
+ * @param resetContext Optional user-provided context
+ */
+export declare function replayToken(tokenAtReset: TrackingToken, currentToken: TrackingToken, resetContext?: unknown): ReplayToken;
+export declare function isReplayToken(token: TrackingToken): token is ReplayToken;
+export declare function isGlobalSequenceToken(token: TrackingToken): token is GlobalSequenceToken;
+/**
+ * Advance a token to a new position. If the token is a ReplayToken and
+ * the new position covers the reset point, unwraps to a plain token.
+ */
+export declare function advanceToken(token: TrackingToken, newPosition: bigint): TrackingToken;
+/**
+ * Check whether the given token represents a replay in progress.
+ * Returns true if the token is a ReplayToken AND the current position
+ * has not yet passed the reset position.
+ *
+ * A ReplayToken that has been fully replayed (current covers reset)
+ * would have been unwrapped by advanceToken — so any ReplayToken
+ * that still exists is mid-replay.
+ */
+export declare function isReplaying(token: TrackingToken): boolean;
+/**
+ * Unwrap a token to its innermost non-replay token.
+ * If the token is not a ReplayToken, returns it unchanged.
+ */
+export declare function unwrapToken(token: TrackingToken): TrackingToken;
+/**
+ * Check if an event at the given position was already processed before
+ * the reset (i.e., it's a replayed event, not a new one).
+ *
+ * Uses the token's `covers()` semantics: if the reset token covers
+ * the event position, then the event existed before the reset.
+ */
+export declare function wasProcessedBeforeReset(token: ReplayToken, eventPosition: bigint): boolean;
+//# sourceMappingURL=tracking-token.d.ts.map

package/dist/tracking-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-token.d.ts","sourceRoot":"","sources":["../src/tracking-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAA;IAElB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAA;IAErC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAAA;IAE/C;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAAA;IAE/C;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAA;CAC9C;AAMD,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAUzE;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,aAAuC,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,aAO1B,CAAA;AAMD,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAA;IACpC,qGAAqG;IACrG,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAA;IACpC,mEAAmE;IACnE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,aAAa,EAC3B,YAAY,EAAE,aAAa,EAC3B,YAAY,CAAC,EAAE,OAAO,GACrB,WAAW,CA+Bb;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,WAAW,CAExE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,mBAAmB,CAExF;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,CAcrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAEzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAK/D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAE1F"}

package/dist/tracking-token.js

@@ -0,0 +1,132 @@
+/**
+ * Creates a token for a global-sequence event store (monotonically increasing positions).
+ * This is the default token type for in-memory stores and Axon Server.
+ */
+export function globalSequenceToken(sequence) {
+    return {
+        kind: "global-sequence",
+        sequence,
+        position: () => sequence,
+        covers: (other) => sequence >= other.position(),
+        lowerBound: (other) => globalSequenceToken(sequence < other.position() ? sequence : other.position()),
+        upperBound: (other) => globalSequenceToken(sequence > other.position() ? sequence : other.position()),
+        samePositionAs: (other) => sequence === other.position(),
+    };
+}
+/**
+ * Sentinel token representing the beginning of the event stream.
+ * A processor starting with FIRST_TOKEN will read from position 0.
+ */
+export const FIRST_TOKEN = globalSequenceToken(0n);
+/**
+ * Sentinel token representing the tail of the event stream.
+ * A processor starting with LATEST_TOKEN will skip all existing events
+ * and only process new events appended after startup.
+ */
+export const LATEST_TOKEN = {
+    kind: "latest",
+    position: () => BigInt(Number.MAX_SAFE_INTEGER),
+    covers: () => true,
+    lowerBound: (other) => other,
+    upperBound: () => LATEST_TOKEN,
+    samePositionAs: (other) => other === LATEST_TOKEN || (other.kind === "latest"),
+};
+/**
+ * Creates a replay token that wraps another token to mark replay-in-progress.
+ *
+ * During replay, events are re-delivered from `currentToken` up to `tokenAtReset`.
+ * Once `currentToken.covers(tokenAtReset)`, the replay is complete and the
+ * token unwraps to the current position.
+ *
+ * @param tokenAtReset The head position when reset was triggered
+ * @param currentToken Where replay is currently reading from
+ * @param resetContext Optional user-provided context
+ */
+export function replayToken(tokenAtReset, currentToken, resetContext) {
+    return {
+        kind: "replay",
+        currentToken,
+        tokenAtReset,
+        resetContext,
+        position: () => currentToken.position(),
+        covers: (other) => currentToken.covers(other),
+        lowerBound: (other) => {
+            const inner = currentToken.lowerBound(other);
+            // If the lower bound is still within replay range, keep the replay wrapper
+            if (!inner.covers(tokenAtReset)) {
+                return replayToken(tokenAtReset, inner, resetContext);
+            }
+            return inner;
+        },
+        upperBound: (other) => {
+            const inner = currentToken.upperBound(other);
+            // If the upper bound has passed the reset point, replay is done
+            if (inner.covers(tokenAtReset)) {
+                return inner;
+            }
+            return replayToken(tokenAtReset, inner, resetContext);
+        },
+        samePositionAs: (other) => currentToken.samePositionAs(other),
+    };
+}
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+export function isReplayToken(token) {
+    return token.kind === "replay";
+}
+export function isGlobalSequenceToken(token) {
+    return token.kind === "global-sequence";
+}
+// ---------------------------------------------------------------------------
+// Token operations
+// ---------------------------------------------------------------------------
+/**
+ * Advance a token to a new position. If the token is a ReplayToken and
+ * the new position covers the reset point, unwraps to a plain token.
+ */
+export function advanceToken(token, newPosition) {
+    const advanced = globalSequenceToken(newPosition);
+    if (!isReplayToken(token)) {
+        return advanced;
+    }
+    // Check if replay is complete
+    if (advanced.covers(token.tokenAtReset)) {
+        return advanced;
+    }
+    // Still replaying — wrap the advanced position
+    return replayToken(token.tokenAtReset, advanced, token.resetContext);
+}
+/**
+ * Check whether the given token represents a replay in progress.
+ * Returns true if the token is a ReplayToken AND the current position
+ * has not yet passed the reset position.
+ *
+ * A ReplayToken that has been fully replayed (current covers reset)
+ * would have been unwrapped by advanceToken — so any ReplayToken
+ * that still exists is mid-replay.
+ */
+export function isReplaying(token) {
+    return isReplayToken(token);
+}
+/**
+ * Unwrap a token to its innermost non-replay token.
+ * If the token is not a ReplayToken, returns it unchanged.
+ */
+export function unwrapToken(token) {
+    if (isReplayToken(token)) {
+        return unwrapToken(token.currentToken);
+    }
+    return token;
+}
+/**
+ * Check if an event at the given position was already processed before
+ * the reset (i.e., it's a replayed event, not a new one).
+ *
+ * Uses the token's `covers()` semantics: if the reset token covers
+ * the event position, then the event existed before the reset.
+ */
+export function wasProcessedBeforeReset(token, eventPosition) {
+    return token.tokenAtReset.covers(globalSequenceToken(eventPosition));
+}
+//# sourceMappingURL=tracking-token.js.map

package/dist/tracking-token.js.map

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

package/dist/transaction.d.ts

@@ -0,0 +1,60 @@
+import { type ResourceKey } from "@kronos-ts/common";
+import type { UoWRunner } from "./unit-of-work.js";
+/**
+ * Manages transaction lifecycle. Users provide an implementation
+ * for their specific database/ORM.
+ *
+ * The framework calls begin/commit/rollback — users never touch these directly.
+ */
+export interface TransactionManager<T = unknown> {
+    begin(): Promise<T>;
+    commit(tx: T): Promise<void>;
+    rollback(tx: T): Promise<void>;
+}
+/**
+ * A no-op transaction manager for when no database transactions are needed.
+ */
+export declare function noTransactionManager(): TransactionManager<void>;
+/** Resource key for storing the active transaction in the active UnitOfWork's ALS-backed resources. */
+export declare const TRANSACTION_KEY: ResourceKey<unknown>;
+/**
+ * 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 declare function getActiveTransaction<T = unknown>(): T | undefined;
+/**
+ * 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 declare function transactionalUnitOfWorkFactory<T>(delegate: UoWRunner, txManager: TransactionManager<T>): UoWRunner;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAQjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IACnB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAM/D;AAED,uGAAuG;AACvG,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,OAAO,CAA8B,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAC9C,QAAQ,EAAE,SAAS,EACnB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,SAAS,CAcX"}