@kronos-ts/messaging 0.1.0

package/src/message-monitor.ts

@@ -0,0 +1,68 @@
+import type { Message } from "./message.js"
+
+/**
+ * Callback returned by a MessageMonitor when a message is ingested.
+ * Call `reportSuccess()` or `reportFailure()` when processing completes.
+ */
+export interface MonitorCallback {
+  /** Report that the message was processed successfully. */
+  reportSuccess(): void
+  /** Report that processing failed. */
+  reportFailure(error?: Error): void
+}
+
+/**
+ * Monitors message processing — observes ingestion, success, and failure
+ * of messages flowing through the framework.
+ *
+ * Used by tracing, metrics, and custom observability extensions.
+ * Monitors are registered via the kronos() App messageMonitorRegistry slot
+ * (Phase 8 reshape — was previously the MessagingConfigurer surface).
+ *
+ */
+export interface MessageMonitor<M extends Message = Message> {
+  /**
+   * Called when a message enters processing.
+   * Returns a callback to report the outcome.
+   */
+  onMessageIngested(message: M): MonitorCallback
+}
+
+/**
+ * A no-op monitor that does nothing. Default when no monitors are registered.
+ */
+export function noOpMessageMonitor<M extends Message = Message>(): MessageMonitor<M> {
+  const noOpCallback: MonitorCallback = {
+    reportSuccess() {},
+    reportFailure() {},
+  }
+  return {
+    onMessageIngested(): MonitorCallback {
+      return noOpCallback
+    },
+  }
+}
+
+/**
+ * Combines multiple monitors into one. Each monitor is called for every message.
+ */
+export function multiMessageMonitor<M extends Message = Message>(
+  monitors: ReadonlyArray<MessageMonitor<M>>,
+): MessageMonitor<M> {
+  if (monitors.length === 0) return noOpMessageMonitor()
+  if (monitors.length === 1) return monitors[0]!
+
+  return {
+    onMessageIngested(message: M): MonitorCallback {
+      const callbacks = monitors.map(m => m.onMessageIngested(message))
+      return {
+        reportSuccess() {
+          for (const cb of callbacks) cb.reportSuccess()
+        },
+        reportFailure(error?: Error) {
+          for (const cb of callbacks) cb.reportFailure(error)
+        },
+      }
+    },
+  }
+}

package/src/message.ts

@@ -0,0 +1,41 @@
+import type { QualifiedName, Metadata } from "@kronos-ts/common"
+
+/**
+ * A message carrying a payload and metadata, identified by a unique ID
+ * and routed by its qualified name.
+ */
+export interface Message<P = unknown> {
+  readonly identifier: string
+  readonly name: QualifiedName
+  readonly payload: P
+  readonly metadata: Metadata
+  readonly timestamp: number
+}
+
+/**
+ * A command message — dispatched to exactly one handler, may return a result.
+ */
+export interface CommandMessage<P = unknown> extends Message<P> {}
+
+/**
+ * A command result message — the response from handling a command.
+ */
+export interface CommandResultMessage<R = unknown> {
+  readonly identifier: string
+  readonly payload: R | undefined
+  readonly metadata: Metadata
+  readonly error?: Error
+}
+
+/**
+ * An event message — published to all interested handlers.
+ */
+export interface EventMessage<P = unknown> extends Message<P> {
+  readonly version: string
+  readonly tags: ReadonlyArray<{ readonly key: string; readonly value: string }>
+}
+
+/**
+ * A query message — dispatched to handler(s) that can answer it.
+ */
+export interface QueryMessage<P = unknown> extends Message<P> {}

package/src/processing-state.ts

@@ -0,0 +1,258 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { Metadata, ResourceKey } from "@kronos-ts/common"
+
+/**
+ * Lifecycle phases for message processing, ordered by execution priority.
+ *
+ * Phases execute in ascending order. Actions within the same phase
+ * execute in registration order. Actions registered during execution
+ * (e.g., onPrepareCommit from a handler) are picked up when their
+ * phase comes.
+ *
+ * Plan 03-04 (CTX-04 / D-34): Phase enum relocated here from the
+ * deleted processing-context.ts. The numeric values are stable —
+ * external code (handler enhancers, processors) compares phase numbers.
+ */
+export const Phase = {
+  /** Setup before handler invocation (e.g., transaction start). */
+  PRE_INVOCATION: -10000,
+  /** Actual handler execution. */
+  INVOCATION: 0,
+  /** Cleanup after handler, before commit. */
+  POST_INVOCATION: 10000,
+  /** Prepare for commit (e.g., event store flush, token store). */
+  PREPARE_COMMIT: 20000,
+  /** Actual commit (e.g., database transaction commit). */
+  COMMIT: 30000,
+  /** Post-commit notifications (e.g., subscription query updates). */
+  AFTER_COMMIT: 40000,
+} as const
+
+export type PhaseValue = (typeof Phase)[keyof typeof Phase]
+
+// D-13: NOT exported.
+type PhaseAction = () => Promise<void> | void
+type ErrorHandler = (error: unknown, phase?: PhaseValue) => Promise<void> | void
+type CompleteHandler = () => void
+
+type Status = "not_started" | "started" | "completed" | "error"
+
+type InternalProcessingState = {
+  resources: Map<symbol, unknown>
+  phaseActions: Map<PhaseValue, PhaseAction[]>
+  errorHandlers: ErrorHandler[]
+  completeHandlers: CompleteHandler[]
+  currentPhase: PhaseValue | null
+  status: Status
+  metadata: Metadata
+}
+
+// D-04: Framework-wide ALS instance. Exported (deep-path only per D-05).
+export const processingStateStorage = new AsyncLocalStorage<InternalProcessingState>()
+
+// D-10: stable error name.
+export class NoActiveUnitOfWork extends Error {
+  constructor(message = "No active UnitOfWork: accessor called outside processingStateStorage.run()") {
+    super(message)
+    this.name = "NoActiveUnitOfWork"
+  }
+}
+
+/**
+ * Plan 04-01 (HDL-02 / D-43): thrown by mutating helpers (append, send, emitUpdate)
+ * when called outside the INVOCATION phase. Distinct class (not a NoActiveUnitOfWork
+ * subclass) — a UoW IS active, but it's in the wrong phase. Catches the real bug
+ * pattern of mutations from lifecycle hooks (onCommit, onPrepareCommit, etc.).
+ */
+export class WrongUoWPhase extends Error {
+  readonly currentPhase: PhaseValue | null
+  constructor(currentPhase: PhaseValue | null) {
+    super(
+      `Mutating helper called during phase ${currentPhase} — must be called during INVOCATION (${Phase.INVOCATION}) only. ` +
+      `Do not call append/send/emitUpdate from lifecycle hooks (onPrepareCommit, onCommit, onAfterCommit, onError, whenComplete).`
+    )
+    this.name = "WrongUoWPhase"
+    this.currentPhase = currentPhase
+  }
+}
+
+function requireState(): InternalProcessingState {
+  const state = processingStateStorage.getStore()
+  if (state === undefined) throw new NoActiveUnitOfWork()
+  return state
+}
+
+/**
+ * Plan 04-01 (HDL-02 / D-43): mutator guard. Throws NoActiveUnitOfWork outside a UoW;
+ * throws WrongUoWPhase when active phase != INVOCATION; otherwise returns the state.
+ * Used by append (eventsourcing), send + emitUpdate (messaging).
+ * Internal — NOT exported from index.ts barrel. Consumed via deep-path import.
+ */
+export function requireInvocationPhase(): InternalProcessingState {
+  const state = processingStateStorage.getStore()
+  if (state === undefined) throw new NoActiveUnitOfWork()
+  if (state.currentPhase !== Phase.INVOCATION) throw new WrongUoWPhase(state.currentPhase)
+  return state
+}
+
+// ── Resource accessors ──────────────────────────────────────────────────
+
+export function getResource<T>(key: ResourceKey<T>): T | undefined {
+  const state = requireState()
+  return state.resources.get(key.symbol) as T | undefined
+}
+
+export function setResource<T>(key: ResourceKey<T>, value: T): T | undefined {
+  const state = requireState()
+  const previous = state.resources.get(key.symbol) as T | undefined
+  state.resources.set(key.symbol, value)
+  return previous
+}
+
+export function computeIfAbsent<T>(key: ResourceKey<T>, supplier: () => T): T {
+  const state = requireState()
+  const existing = state.resources.get(key.symbol)
+  if (existing !== undefined) return existing as T
+  const value = supplier()
+  state.resources.set(key.symbol, value)
+  return value
+}
+
+export function removeResource<T>(key: ResourceKey<T>): T | undefined {
+  const state = requireState()
+  const previous = state.resources.get(key.symbol) as T | undefined
+  state.resources.delete(key.symbol)
+  return previous
+}
+
+export function hasResource<T>(key: ResourceKey<T>): boolean {
+  const state = requireState()
+  return state.resources.has(key.symbol)
+}
+
+export function updateResource<T>(
+  key: ResourceKey<T>,
+  updater: (current: T | undefined) => T,
+): T {
+  const state = requireState()
+  const current = state.resources.get(key.symbol) as T | undefined
+  const updated = updater(current)
+  state.resources.set(key.symbol, updated)
+  return updated
+}
+
+// ── Lifecycle registration ──────────────────────────────────────────────
+
+export function registerPhaseAction(phase: PhaseValue, action: PhaseAction): void {
+  const state = requireState()
+  let bucket = state.phaseActions.get(phase)
+  if (!bucket) {
+    bucket = []
+    state.phaseActions.set(phase, bucket)
+  }
+  bucket.push(action)
+}
+
+export function registerErrorHandler(handler: ErrorHandler): void {
+  const state = requireState()
+  state.errorHandlers.push(handler)
+}
+
+export function registerCompleteHandler(handler: CompleteHandler): void {
+  const state = requireState()
+  state.completeHandlers.push(handler)
+}
+
+// ── Lifecycle accessors (CTX-03, D-30) ──────────────────────────────────
+//
+// Module-level equivalents of ctx.on / ctx.onError / ctx.whenComplete /
+// ctx.onPrepareCommit / ctx.onCommit / ctx.onAfterCommit. Thin wrappers
+// over the Phase 1 accessors (registerPhaseAction / registerErrorHandler /
+// registerCompleteHandler). Same fail-fast contract (D-31): throw
+// NoActiveUnitOfWork outside an active processingStateStorage.run.
+
+export function on(phase: PhaseValue, action: PhaseAction): void {
+  registerPhaseAction(phase, action)
+}
+
+export function onPrepareCommit(action: PhaseAction): void {
+  registerPhaseAction(Phase.PREPARE_COMMIT, action)
+}
+
+export function onCommit(action: PhaseAction): void {
+  registerPhaseAction(Phase.COMMIT, action)
+}
+
+export function onAfterCommit(action: PhaseAction): void {
+  registerPhaseAction(Phase.AFTER_COMMIT, action)
+}
+
+export function onError(handler: ErrorHandler): void {
+  registerErrorHandler(handler)
+}
+
+export function whenComplete(handler: CompleteHandler): void {
+  registerCompleteHandler(handler)
+}
+
+// ── withOverride (D-07..D-09) ──────────────────────────────────────────
+
+/**
+ * Run `fn` in a nested processingStateStorage context where `key` resolves to `value`.
+ *
+ * Only the `resources` Map is forked (D-08). All other fields — phaseActions,
+ * errorHandlers, completeHandlers, status, currentPhase, metadata — are SHARED
+ * references to the parent state. Registering a phase action or error handler
+ * inside `fn` targets the parent's lifecycle.
+ *
+ * After `fn` resolves, the parent's resources are unchanged (D-09) — nested
+ * `storage.run()` naturally pops the forked state.
+ *
+ * Throws NoActiveUnitOfWork if called outside an existing processingStateStorage.run().
+ */
+export function withOverride<T, R>(
+  key: ResourceKey<T>,
+  value: T,
+  fn: () => Promise<R>,
+): Promise<R> {
+  const parent = requireState()
+  const forkedResources = new Map(parent.resources)
+  forkedResources.set(key.symbol, value)
+
+  const forkedState: InternalProcessingState = {
+    resources: forkedResources,
+    // SHARED references to parent (D-08):
+    phaseActions: parent.phaseActions,
+    errorHandlers: parent.errorHandlers,
+    completeHandlers: parent.completeHandlers,
+    status: parent.status,
+    currentPhase: parent.currentPhase,
+    metadata: parent.metadata,
+  }
+
+  return processingStateStorage.run(forkedState, fn)
+}
+
+/**
+ * INTERNAL — used by UnitOfWork to construct the initial state passed to
+ * processingStateStorage.run(). The InternalProcessingState type is intentionally
+ * non-exported (D-13); this factory is the sanctioned construction point.
+ * Deep-path import only; NOT re-exported from the package barrel (D-05).
+ *
+ * Return type is intentionally INFERRED (no `: InternalProcessingState` annotation).
+ * Annotating the return type with a non-exported name produces TS4023 under
+ * `declaration: true` / `isolatedDeclarations`, breaking the package build.
+ * Inference preserves D-13 (the type remains non-exported) while allowing `.d.ts`
+ * emission.
+ */
+export function createInitialProcessingState(metadata: Metadata) {
+  return {
+    resources: new Map<symbol, unknown>(),
+    phaseActions: new Map<PhaseValue, PhaseAction[]>(),
+    errorHandlers: [] as ErrorHandler[],
+    completeHandlers: [] as CompleteHandler[],
+    currentPhase: null as PhaseValue | null,
+    status: "not_started" as Status,
+    metadata,
+  }
+}

package/src/processor-configuration.ts

@@ -0,0 +1,59 @@
+import type { TokenStore } from "./token-store.js"
+import type { UoWRunner } from "./unit-of-work.js"
+import type { EventProcessingErrorHandler } from "./tracking-event-processor.js"
+import type { SequencedDeadLetterQueue } from "./dead-letter-queue.js"
+
+/**
+ * Configuration for an individual event processor.
+ *
+ * All properties are optional — when not specified, the processor
+ * uses the global defaults from the messaging configurer.
+ *
+ * This enables per-processor tuning: different processors can have
+ * different batch sizes, token stores, error handlers, etc.
+ *
+ * ```typescript
+ * messagingConfigurer({
+ *   eventHandlers: [courseProjection],
+ *   processorConfiguration: {
+ *     "course-projection": {
+ *       batchSize: 50,
+ *       initialSegmentCount: 4,
+ *       errorHandler: propagatingErrorHandler(),
+ *     },
+ *   },
+ * })
+ * ```
+ */
+/**
+ * @deprecated Use `trackingProcessor()` / `subscribingProcessor()` builders
+ * with `registerEventProcessor()` instead.
+ */
+export interface ProcessorConfiguration {
+  /** Events per transaction. Default: 100 */
+  batchSize?: number
+
+  /** Number of segments to create on first startup. Default: 1 */
+  initialSegmentCount?: number
+
+  /** Polling interval in ms (for TrackingEventProcessor). Default: 500 */
+  pollingIntervalMs?: number
+
+  /** Override the token store for this processor. */
+  tokenStore?: TokenStore
+
+  /** Override the UnitOfWork runner for this processor. */
+  unitOfWorkRunner?: UoWRunner
+
+  /** Override the error handler for this processor. */
+  errorHandler?: EventProcessingErrorHandler
+
+  /** Dead letter queue for this processor. */
+  deadLetterQueue?: SequencedDeadLetterQueue
+
+  /** How often to extend claims in ms. Default: 5000 */
+  claimExtensionThresholdMs?: number
+
+  /** How often to attempt claiming new segments in ms. Default: 5000 */
+  tokenClaimIntervalMs?: number
+}

package/src/query-bus.ts

@@ -0,0 +1,69 @@
+import type { QueryMessage } from "./message.js"
+import type { SubscriptionQueryResult } from "./subscription-query.js"
+
+/**
+ * The query bus — low-level infrastructure for dispatching query messages.
+ *
+ */
+export interface QueryBus {
+  /**
+   * Dispatch a query message to its handler(s).
+   *
+   * 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.
+   */
+  query(message: QueryMessage): Promise<unknown>
+
+  /**
+   * Subscribe a handler for the given query name.
+   *
+   * Plan 03-04 (CTX-04 / D-34): handler signature dropped its `ctx`
+   * parameter. The ProcessingContext type is gone.
+   */
+  subscribe(
+    queryName: string,
+    handler: (message: QueryMessage) => Promise<unknown>,
+  ): void
+
+  /**
+   * Start a subscription query — returns the initial result plus a stream
+   * of incremental updates.
+   */
+  subscriptionQuery(message: QueryMessage, bufferSize?: number): SubscriptionQueryResult
+
+  /**
+   * Subscribe to updates only (no initial result).
+   * Returns an async iterable of update payloads.
+   *
+   */
+  subscribeToUpdates(message: QueryMessage, bufferSize?: number): AsyncIterable<unknown> & { close(): void }
+
+  /**
+   * Emit an update to all active subscription queries matching the filter.
+   * When called within an active UnitOfWork (detected via ALS), the update is
+   * deferred to AFTER_COMMIT.
+   */
+  emitUpdate(
+    queryName: string,
+    filter: (queryPayload: unknown) => boolean,
+    update: unknown,
+  ): Promise<void>
+
+  /**
+   * Complete all subscription queries matching the filter.
+   */
+  completeSubscription(
+    queryName: string,
+    filter?: (queryPayload: unknown) => boolean,
+  ): Promise<void>
+
+  /**
+   * Complete all subscription queries matching the filter with an error.
+   */
+  completeSubscriptionExceptionally(
+    queryName: string,
+    error: Error,
+    filter?: (queryPayload: unknown) => boolean,
+  ): Promise<void>
+}

package/src/query-handler.ts

@@ -0,0 +1,49 @@
+import type { z } from "zod"
+import type { Metadata } from "@kronos-ts/common"
+import type { QueryDescriptor } from "./descriptor.js"
+
+// ---------------------------------------------------------------------------
+// Singular factory — mirrors commandHandler / eventHandler.
+// The app consumes these via `app.queries(...handlers)` varargs.
+// ---------------------------------------------------------------------------
+
+/**
+ * A registered singular query handler — pairs a query descriptor with its handler
+ * function. Mirrors {@link import("./command-handler.js").CommandHandlerDefinition}
+ * structurally so all three handler shapes (command / event / query) share the same
+ * pattern.
+ *
+ * Note: queries do NOT carry a result schema on the descriptor (see `QueryDescriptor`
+ * in `./descriptor.ts` — no `result` field used here). The result type `R` is
+ * inferred from the handler's return type.
+ */
+export interface QueryHandlerDefinition<
+  Q extends z.ZodType = z.ZodType,
+  R = unknown,
+> {
+  readonly kind: "query-handler"
+  readonly descriptor: QueryDescriptor<Q, z.ZodType | undefined>
+  readonly handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R
+}
+
+/**
+ * Defines a singular query handler.
+ *
+ * ```
+ * const getCourseView = queryHandler(GetCourseView, async (q, metadata) => {
+ *   const view = courseViews.get(q.courseId)
+ *   if (!view) throw new Error("not found")
+ *   return view
+ * })
+ * ```
+ *
+ * Use with `app.queries(getCourseView, getAllCourses)`. Symmetric to
+ * {@link import("./command-handler.js").commandHandler} and
+ * {@link import("./event-handler.js").eventHandler}.
+ */
+export function queryHandler<Q extends z.ZodType, R>(
+  descriptor: QueryDescriptor<Q, z.ZodType | undefined>,
+  handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R,
+): QueryHandlerDefinition<Q, R> {
+  return { kind: "query-handler", descriptor, handler }
+}

package/src/query-handling-module.ts

@@ -0,0 +1,44 @@
+import { qualifiedNameToString } from "@kronos-ts/common"
+import type { QueryHandlerDefinition } from "./query-handler.js"
+import type { QueryBus } from "./query-bus.js"
+import type { QueryMessage } from "./message.js"
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.js"
+
+/**
+ * Function-style helper called by AppImpl.start() to subscribe query handlers
+ * natively, without the configurer's Module shape.
+ *
+ * Accepts a flat ReadonlyArray<QueryHandlerDefinition> (singular handler shape).
+ *
+ * Symmetric to registerCommandHandlersNatively — accepts an optional
+ * handlerEnhancer that wraps each query invocation so query handlers receive
+ * the same tracing / timing / cross-cutting treatment as command and event
+ * handlers. moduleName defaults to "queries" for HandlerMetadata.handlerGroup.
+ *
+ * Query handlers do NOT need a Configuration shim — queries don't append
+ * events, so no per-invocation ALS resource setup is required at query
+ * subscription level.
+ */
+export function registerQueryHandlersNatively(
+  handlers: ReadonlyArray<QueryHandlerDefinition>,
+  deps: {
+    queryBus: QueryBus
+    handlerEnhancer?: HandlerEnhancerDefinition
+    moduleName?: string
+  },
+): void {
+  const moduleName = deps.moduleName ?? "queries"
+  for (const reg of handlers) {
+    const queryName = qualifiedNameToString(reg.descriptor.name)
+    let invocation = async (message: QueryMessage) =>
+      reg.handler(message.payload, message.metadata)
+    if (deps.handlerEnhancer) {
+      invocation = deps.handlerEnhancer.wrapHandler(invocation, {
+        messageType: "query",
+        messageName: queryName,
+        handlerGroup: moduleName,
+      })
+    }
+    deps.queryBus.subscribe(queryName, invocation)
+  }
+}

package/src/replay-token.ts

@@ -0,0 +1,53 @@
+/**
+ * Re-exports from tracking-token.ts plus the isReplay() helper.
+ *
+ * Plan 03-04 (CTX-04 / D-29): `isReplay()` is a no-arg permissive ALS read.
+ * It returns `false` when called outside an active UnitOfWork (replay-state
+ * has only ever been set by the tracking processor; absence == not replaying).
+ */
+import { resourceKey, type ResourceKey } from "@kronos-ts/common"
+import { processingStateStorage } from "./processing-state.js"
+
+// Re-export token types and operations
+export {
+  type TrackingToken,
+  type GlobalSequenceToken,
+  type ReplayToken,
+  globalSequenceToken,
+  replayToken,
+  isReplayToken,
+  isGlobalSequenceToken,
+  advanceToken,
+  isReplaying,
+  unwrapToken,
+  wasProcessedBeforeReset,
+} from "./tracking-token.js"
+
+/** Resource key for storing replay state in the active UnitOfWork. */
+export const REPLAY_STATE_KEY: ResourceKey<{ replaying: boolean }> =
+  resourceKey("replayState")
+
+/**
+ * Check if the current processing is a replay.
+ * Use this in event handlers to skip side effects during replay.
+ *
+ * Plan 03-04 (D-29): no-arg permissive ALS read. Returns `false` when called
+ * outside an active UnitOfWork.
+ *
+ * ```
+ * on(OrderPlaced, async (event) => {
+ *   await db.orders.insert(event)
+ *   if (!isReplay()) {
+ *     await sendConfirmationEmail(event.email)
+ *   }
+ * })
+ * ```
+ */
+export function isReplay(): boolean {
+  const state = processingStateStorage.getStore()
+  if (!state) return false
+  const replayState = state.resources.get(REPLAY_STATE_KEY.symbol) as
+    | { replaying: boolean }
+    | undefined
+  return replayState?.replaying === true
+}