@kronos-ts/messaging 0.1.0

package/src/retrying-command-bus.ts

@@ -0,0 +1,80 @@
+import type { CommandBus } from "./command-bus.js"
+import type { CommandMessage } from "./message.js"
+
+/**
+ * Determines whether a failed command dispatch should be retried.
+ */
+export interface RetryPolicy {
+  /**
+   * Returns the delay in ms before the next retry, or undefined to stop retrying.
+   * @param error The error from the previous attempt
+   * @param attempt The attempt number (0-based, so 0 = first failure)
+   */
+  shouldRetry(error: unknown, attempt: number): number | undefined
+}
+
+/**
+ * Retries on transient errors (like AppendConditionError) with exponential backoff.
+ * Non-transient errors are rethrown immediately.
+ */
+export function exponentialBackoffRetryPolicy(options?: {
+  maxRetries?: number
+  initialDelayMs?: number
+  isTransient?: (error: unknown) => boolean
+}): RetryPolicy {
+  const maxRetries = options?.maxRetries ?? 5
+  const initialDelayMs = options?.initialDelayMs ?? 10
+  const isTransient = options?.isTransient ?? defaultIsTransient
+
+  return {
+    shouldRetry(error: unknown, attempt: number): number | undefined {
+      if (attempt >= maxRetries) return undefined
+      if (!isTransient(error)) return undefined
+      return initialDelayMs * Math.pow(2, attempt)
+    },
+  }
+}
+
+function defaultIsTransient(error: unknown): boolean {
+  if (error instanceof Error) {
+    return error.name === "AppendConditionError"
+  }
+  return false
+}
+
+/**
+ * A command bus decorator that retries failed dispatches based on a retry policy.
+ *
+ * When a command fails with a transient error (e.g., AppendConditionError from
+ * an optimistic concurrency conflict), the entire dispatch is retried. This means
+ * the handler re-sources state and re-makes its decision based on fresh data.
+ *
+ * Non-transient errors propagate immediately to the caller.
+ */
+export function createRetryingCommandBus(
+  delegate: CommandBus,
+  policy: RetryPolicy,
+): CommandBus {
+  return {
+    async dispatch(message: CommandMessage): Promise<unknown> {
+      let attempt = 0
+      while (true) {
+        try {
+          return await delegate.dispatch(message)
+        } catch (error) {
+          const delay = policy.shouldRetry(error, attempt)
+          if (delay === undefined) throw error
+
+          attempt++
+          if (delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay))
+          }
+        }
+      }
+    },
+
+    subscribe(commandName: string, handler: (message: CommandMessage) => Promise<unknown>) {
+      delegate.subscribe(commandName, handler)
+    },
+  }
+}

package/src/routing-strategy.ts

@@ -0,0 +1,59 @@
+import type { CommandMessage } from "./message.js"
+
+/**
+ * Determines the routing key for a command message.
+ *
+ * Used by the distributed command bus to route commands to the correct
+ * handler instance via consistent hashing. Commands with the same routing
+ * key are routed to the same handler.
+ */
+export interface RoutingStrategy {
+  /**
+   * Get the routing key for the given command message.
+   * Returns a string that identifies the target for this command
+   * (typically an aggregate identifier).
+   */
+  getRoutingKey(message: CommandMessage): string
+}
+
+/**
+ * Extracts the routing key from a command message's metadata.
+ *
+ * @param metadataKey The metadata key to extract the routing key from.
+ */
+export function metadataRoutingStrategy(metadataKey: string): RoutingStrategy {
+  return {
+    getRoutingKey(message: CommandMessage): string {
+      const value = message.metadata[metadataKey]
+      if (value == null) {
+        throw new Error(
+          `No routing key found in metadata key "${metadataKey}" ` +
+          `for command "${String(message.name)}"`,
+        )
+      }
+      return String(value)
+    },
+  }
+}
+
+/**
+ * Extracts the routing key from a field of the command payload.
+ * The field name is specified explicitly on the descriptor/configuration.
+ *
+ * @param field The payload field to extract the routing key from.
+ */
+export function payloadFieldRoutingStrategy(field: string): RoutingStrategy {
+  return {
+    getRoutingKey(message: CommandMessage): string {
+      const payload = message.payload as Record<string, unknown>
+      const value = payload?.[field]
+      if (value == null) {
+        throw new Error(
+          `No routing key found in payload field "${field}" ` +
+          `for command "${String(message.name)}"`,
+        )
+      }
+      return String(value)
+    },
+  }
+}

package/src/segment.ts

@@ -0,0 +1,136 @@
+/**
+ * Represents a fraction of the event stream assigned to a processor instance.
+ *
+ * Segments use bitmask-based routing to deterministically assign events
+ * to processors. An event matches a segment when `(hash(event) & mask) === segmentId`.
+ *
+ * Segments can be split (doubling parallelism) and merged (halving parallelism).
+ * This is the foundation for horizontal scaling — multiple instances of the
+ * same processor each claim different segments.
+ *
+ * The ROOT_SEGMENT (segmentId=0, mask=0) matches ALL events and is the
+ * starting point before any splitting.
+ */
+export interface Segment {
+  /** The unique identifier of this segment. */
+  readonly segmentId: number
+  /**
+   * The bitmask used to match events to this segment.
+   * An event matches when `(hash & mask) === segmentId`.
+   */
+  readonly mask: number
+}
+
+/** The root segment — matches all events. Starting point before splitting. */
+export const ROOT_SEGMENT: Segment = { segmentId: 0, mask: 0 }
+
+/**
+ * Create a segment with the given id and mask.
+ */
+export function segment(segmentId: number, mask: number): Segment {
+  return { segmentId, mask }
+}
+
+/**
+ * Check if a hash value matches this segment.
+ * Used to route events to the correct processor instance.
+ *
+ * @param seg The segment to check against
+ * @param hash The hash of the event's sequence identifier (e.g., aggregate ID hash)
+ */
+export function segmentMatches(seg: Segment, hash: number): boolean {
+  return (hash & seg.mask) === seg.segmentId
+}
+
+/**
+ * Split a segment into two child segments.
+ * Doubles the processing parallelism for this segment's portion of the stream.
+ *
+ * Returns a tuple of [segment keeping the original ID, new sibling segment].
+ */
+export function splitSegment(seg: Segment): [Segment, Segment] {
+  const newMask = (seg.mask << 1) | 1
+  const newSegmentId = seg.segmentId | (seg.mask + 1)
+
+  return [
+    { segmentId: seg.segmentId, mask: newMask },
+    { segmentId: newSegmentId, mask: newMask },
+  ]
+}
+
+/**
+ * Check if two segments can be merged (they are siblings from the same split).
+ */
+export function isMergeable(a: Segment, b: Segment): boolean {
+  if (a.mask !== b.mask) return false
+  if (a.mask === 0) return false
+  // Siblings differ only in the highest bit of the mask
+  return (a.segmentId ^ b.segmentId) === (a.mask >>> 0) - (a.mask >>> 1)
+}
+
+/**
+ * Merge two sibling segments back into their parent.
+ * Halves the processing parallelism.
+ *
+ * @throws Error if segments are not mergeable
+ */
+export function mergeSegments(a: Segment, b: Segment): Segment {
+  if (!isMergeable(a, b)) {
+    throw new Error(
+      `Segments ${a.segmentId}/${a.mask} and ${b.segmentId}/${b.mask} are not mergeable`,
+    )
+  }
+
+  return {
+    segmentId: Math.min(a.segmentId, b.segmentId),
+    mask: a.mask >>> 1,
+  }
+}
+
+/**
+ * Compute the total number of segments at the current split level.
+ * For a segment with mask M, the total count is M + 1.
+ */
+export function segmentCount(seg: Segment): number {
+  return seg.mask + 1
+}
+
+/**
+ * Compute a hash from a string value (for event routing).
+ * Uses a simple but well-distributed hash function.
+ */
+export function hashOf(value: string): number {
+  let hash = 0
+  for (let i = 0; i < value.length; i++) {
+    const char = value.charCodeAt(i)
+    hash = ((hash << 5) - hash + char) | 0
+  }
+  return hash >>> 0 // Ensure unsigned
+}
+
+/**
+ * Create N balanced segments by splitting the root segment.
+ *
+ * @param count Number of segments (must be a power of 2)
+ * @returns Array of segments that together cover the entire event stream
+ */
+export function createSegments(count: number): Segment[] {
+  if (count <= 0) throw new Error("Segment count must be positive")
+  if (count === 1) return [ROOT_SEGMENT]
+
+  // Find the nearest power of 2
+  const power = Math.ceil(Math.log2(count))
+  const actualCount = Math.pow(2, power)
+
+  let segments: Segment[] = [ROOT_SEGMENT]
+  while (segments.length < actualCount) {
+    const next: Segment[] = []
+    for (const seg of segments) {
+      const [a, b] = splitSegment(seg)
+      next.push(a, b)
+    }
+    segments = next
+  }
+
+  return segments
+}

package/src/send.ts

@@ -0,0 +1,44 @@
+import { resourceKey, generateIdentifier, type ResourceKey } from "@kronos-ts/common"
+import { requireInvocationPhase } from "./processing-state.js"
+import type { CommandBus } from "./command-bus.js"
+import type { CommandDescriptor } from "./descriptor.js"
+import type { z } from "zod"
+
+type CommandDispatchFunction = <P extends z.ZodType, R extends z.ZodType | undefined = undefined>(
+  descriptor: CommandDescriptor<P, R>,
+  payload: z.infer<P>,
+) => Promise<unknown>
+
+/**
+ * Resource key for the command bus component.
+ * Written by handling modules + processors at handler-invocation entry (D-44).
+ */
+export const COMMAND_BUS_KEY: ResourceKey<CommandBus> = resourceKey("commandBus")
+
+/**
+ * Send a command from inside a handler.
+ *
+ * AF5-aligned semantics: every command is handled in its own fresh
+ * UnitOfWork (`commandBus.dispatch` always starts a new one — see
+ * `createSimpleCommandBus`). The command handler is therefore its own
+ * atomic boundary: it loads state, decides, appends events, and commits
+ * once — independent of the caller's UnitOfWork.
+ *
+ * The caller's `metadata` IS carried onto the outgoing command, so
+ * correlation/causation lineage propagates the AF5 way — through message
+ * metadata, applied by the correlation-data dispatch interceptor — across
+ * any transport, local or distributed. No processing-context object is
+ * threaded through the command API or over the wire.
+ */
+export const send: CommandDispatchFunction = async (descriptor, payload) => {
+  const state = requireInvocationPhase() // D-43 mutator guard
+  const bus = state.resources.get(COMMAND_BUS_KEY.symbol) as CommandBus | undefined
+  if (!bus) throw new Error("No command bus configured")
+  return bus.dispatch({
+    identifier: generateIdentifier(),
+    name: descriptor.name,
+    payload,
+    metadata: state.metadata,
+    timestamp: Date.now(),
+  })
+}

package/src/serializer.ts

@@ -0,0 +1,122 @@
+import type { Serializer, SerializedObject } from "@kronos-ts/common"
+import type { z } from "zod"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+/**
+ * JSON serializer — the default serializer for the TypeScript framework.
+ *
+ * Serializes values as JSON-encoded Uint8Array. Handles `undefined`,
+ * `null`, and all JSON-compatible values.
+ */
+export function jsonSerializer(): Serializer {
+  return {
+    serialize(value: unknown, type: string, revision: string = ""): SerializedObject {
+      return {
+        type,
+        revision,
+        data: encoder.encode(JSON.stringify(value)),
+      }
+    },
+
+    deserialize<T>(data: SerializedObject): T {
+      if (data.data.length === 0) return undefined as T
+      return JSON.parse(decoder.decode(data.data)) as T
+    },
+
+    canConvert(): boolean {
+      return true
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schema registries — per message type
+// ---------------------------------------------------------------------------
+
+/**
+ * A registry of Zod schemas indexed by type name + revision.
+ * Used by the validating serializer decorator to validate
+ * deserialized payloads against their expected schema.
+ */
+export interface SchemaRegistry {
+  register(typeName: string, revision: string, schema: z.ZodType): void
+  get(typeName: string, revision: string): z.ZodType | undefined
+}
+
+/** Schema registry for event payloads. */
+export function createEventSchemaRegistry(): SchemaRegistry {
+  return createSchemaRegistry()
+}
+
+/** Schema registry for command payloads. */
+export function createCommandSchemaRegistry(): SchemaRegistry {
+  return createSchemaRegistry()
+}
+
+/** Schema registry for query payloads. */
+export function createQuerySchemaRegistry(): SchemaRegistry {
+  return createSchemaRegistry()
+}
+
+function createSchemaRegistry(): SchemaRegistry {
+  const schemas = new Map<string, z.ZodType>()
+
+  function key(typeName: string, revision: string): string {
+    return `${typeName}@${revision}`
+  }
+
+  return {
+    register(typeName, revision, schema) {
+      schemas.set(key(typeName, revision), schema)
+    },
+
+    get(typeName, revision) {
+      // Try exact match first, then fallback to no revision
+      return schemas.get(key(typeName, revision)) ?? schemas.get(key(typeName, ""))
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Zod-validating serializer decorator
+// ---------------------------------------------------------------------------
+
+/**
+ * Wraps a delegate serializer with Zod validation on deserialization.
+ *
+ * When deserializing, looks up the schema in the registry by type name
+ * and revision. If found, validates the deserialized value against it.
+ * If not found, passes through without validation.
+ *
+ * ```typescript
+ * const serializer = zodValidatingSerializer(
+ *   jsonSerializer(),
+ *   mySchemaRegistry,
+ * )
+ * ```
+ */
+export function zodValidatingSerializer(
+  delegate: Serializer,
+  schemaRegistry: SchemaRegistry,
+): Serializer {
+  return {
+    serialize(value, type, revision) {
+      return delegate.serialize(value, type, revision)
+    },
+
+    deserialize<T>(data: SerializedObject): T {
+      const raw = delegate.deserialize<unknown>(data)
+      const schema = schemaRegistry.get(data.type, data.revision)
+      if (schema) {
+        return schema.parse(raw) as T
+      }
+      return raw as T
+    },
+
+    canConvert(type) {
+      return delegate.canConvert(type)
+    },
+  }
+}

package/src/simple-command-bus.ts

@@ -0,0 +1,59 @@
+import type { CommandBus } from "./command-bus.js"
+import type { CommandMessage } from "./message.js"
+import { runInNewUoW } from "./unit-of-work.js"
+import { qualifiedNameToString } from "@kronos-ts/common"
+
+/**
+ * Simple in-process command bus.
+ *
+ * Maintains a local handler map and dispatches commands directly,
+ * wrapping each dispatch in a fresh UnitOfWork via `runInNewUoW`.
+ *
+ * AF5 parity: like `SimpleCommandBus`, every command — primary OR nested
+ * (dispatched from inside another handler via `send()`) — is handled in
+ * its own independent UnitOfWork with its own commit boundary. A command
+ * handler is the atomic unit; commands compose by independent commit, not
+ * by sharing a transaction. DCB read-set / append-condition merging
+ * happens only WITHIN a single handler's UnitOfWork.
+ *
+ * Transactional wiring composes at the runner level via
+ * `transactionalUnitOfWorkFactory(runInNewUoW, txManager)` and is consumed
+ * by extensions / processors directly, not by the bus.
+ *
+ * Interceptor support is provided by wrapping with
+ * {@link createInterceptingCommandBus}.
+ */
+export function createSimpleCommandBus(): CommandBus {
+  const handlers = new Map<string, (message: CommandMessage) => Promise<unknown>>()
+
+  return {
+    async dispatch(message: CommandMessage): Promise<unknown> {
+      const key = qualifiedNameToString(message.name)
+      const handler = handlers.get(key)
+      if (!handler) {
+        throw new Error(`No handler registered for command "${key}"`)
+      }
+
+      // AF5 parity: every command gets its own fresh UnitOfWork, even when
+      // dispatched from inside another handler. Dispatch interceptors have
+      // already run in the caller's context (the intercepting bus wraps
+      // this one), so correlation data is carried on `message.metadata`
+      // before we cross into the new UoW.
+      return runInNewUoW(message.metadata, () => handler(message))
+    },
+
+    subscribe(
+      commandName: string,
+      handler: (message: CommandMessage) => Promise<unknown>,
+    ) {
+      const existing = handlers.get(commandName)
+      if (existing && existing !== handler) {
+        throw new Error(
+          `A different handler is already registered for command "${commandName}". ` +
+          `Duplicate command handler subscriptions are not allowed.`,
+        )
+      }
+      handlers.set(commandName, handler)
+    },
+  }
+}

package/src/simple-query-bus.ts

@@ -0,0 +1,158 @@
+import type { QueryBus } from "./query-bus.js"
+import type { QueryMessage } from "./message.js"
+import type { SubscriptionQueryResult, UpdateHandler } from "./subscription-query.js"
+import { createUpdateHandler, runAfterCommitOrImmediately } from "./subscription-query.js"
+import { runInUoW } from "./unit-of-work.js"
+import { qualifiedNameToString } from "@kronos-ts/common"
+
+/**
+ * Simple in-process query bus with subscription query support.
+ *
+ * Direct queries are dispatched within a UnitOfWork via `runInUoW`.
+ * Subscription queries receive an initial result plus a stream of
+ * incremental updates emitted via `emitUpdate()`.
+ *
+ * Plan 03-04 (CTX-04 / D-34): the explicit `unitOfWorkFactory`
+ * parameter and branch are gone. `runInUoW` is the only codepath.
+ *
+ * Interceptor support is provided by wrapping with
+ * {@link createInterceptingQueryBus}.
+ */
+export function createSimpleQueryBus(): QueryBus {
+  const handlers = new Map<string, (message: QueryMessage) => Promise<unknown>>()
+
+  // Active subscription query handlers, keyed by query identifier
+  const subscriptions = new Map<string, UpdateHandler>()
+
+  const bus: QueryBus = {
+    async query(message: QueryMessage): Promise<unknown> {
+      const key = qualifiedNameToString(message.name)
+      const handler = handlers.get(key)
+      if (!handler) {
+        throw new Error(`No handler registered for query "${key}"`)
+      }
+
+      // Plan 03-01 (D-32) / Plan 03-04 (CTX-04): mirrors
+      // simple-command-bus.dispatch. ALS-aware nesting; primary dispatch
+      // creates a new UoW.
+      return runInUoW(message.metadata, () => handler(message))
+    },
+
+    subscribe(
+      queryName: string,
+      handler: (message: QueryMessage) => Promise<unknown>,
+    ) {
+      const existing = handlers.get(queryName)
+      if (existing && existing !== handler) {
+        throw new Error(
+          `A different handler is already registered for query "${queryName}". ` +
+          `Duplicate query handler subscriptions are not allowed.`,
+        )
+      }
+      handlers.set(queryName, handler)
+    },
+
+    subscriptionQuery(message: QueryMessage, bufferSize?: number): SubscriptionQueryResult {
+      const queryId = message.identifier
+
+      if (subscriptions.has(queryId)) {
+        throw new Error(`Subscription query already registered for identifier "${queryId}"`)
+      }
+
+      const updateHandler = createUpdateHandler(message, bufferSize)
+      subscriptions.set(queryId, updateHandler)
+
+      const initialResult = bus.query(message)
+
+      return {
+        initialResult,
+        updates: updateHandler.iterable,
+        close: () => {
+          subscriptions.delete(queryId)
+          updateHandler.complete()
+        },
+      }
+    },
+
+    subscribeToUpdates(message: QueryMessage, bufferSize?: number): AsyncIterable<unknown> & { close(): void } {
+      const queryId = message.identifier
+
+      if (subscriptions.has(queryId)) {
+        throw new Error(`Subscription query already registered for identifier "${queryId}"`)
+      }
+
+      const updateHandler = createUpdateHandler(message, bufferSize)
+      subscriptions.set(queryId, updateHandler)
+
+      return {
+        [Symbol.asyncIterator]: () => updateHandler.iterable[Symbol.asyncIterator](),
+        close: () => {
+          subscriptions.delete(queryId)
+          updateHandler.complete()
+        },
+      }
+    },
+
+    async emitUpdate(
+      queryName: string,
+      filter: (queryPayload: unknown) => boolean,
+      update: unknown,
+    ): Promise<void> {
+      runAfterCommitOrImmediately(() => {
+        for (const [id, handler] of subscriptions) {
+          if (!handler.active) {
+            subscriptions.delete(id)
+            continue
+          }
+
+          const handlerQueryName = qualifiedNameToString(handler.query.name)
+          if (handlerQueryName !== queryName) continue
+          if (!filter(handler.query.payload)) continue
+
+          const accepted = handler.offer(update)
+          if (!accepted) {
+            handler.completeExceptionally(
+              new Error("Subscription query update buffer overflow"),
+            )
+            subscriptions.delete(id)
+          }
+        }
+      })
+    },
+
+    async completeSubscription(
+      queryName: string,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      runAfterCommitOrImmediately(() => {
+        for (const [id, handler] of subscriptions) {
+          const handlerQueryName = qualifiedNameToString(handler.query.name)
+          if (handlerQueryName !== queryName) continue
+          if (filter && !filter(handler.query.payload)) continue
+
+          handler.complete()
+          subscriptions.delete(id)
+        }
+      })
+    },
+
+    async completeSubscriptionExceptionally(
+      queryName: string,
+      error: Error,
+      filter?: (queryPayload: unknown) => boolean,
+    ): Promise<void> {
+      runAfterCommitOrImmediately(() => {
+        for (const [id, handler] of subscriptions) {
+          const handlerQueryName = qualifiedNameToString(handler.query.name)
+          if (handlerQueryName !== queryName) continue
+          if (filter && !filter(handler.query.payload)) continue
+
+          handler.completeExceptionally(error)
+          subscriptions.delete(id)
+        }
+      })
+    },
+  }
+
+  return bus
+}