@kronos-ts/messaging 0.1.0

package/src/command-handler.ts

@@ -0,0 +1,116 @@
+import type { z } from "zod"
+import type { Metadata } from "@kronos-ts/common"
+import type { CommandDescriptor } from "./descriptor.js"
+import type { EventCriteria } from "./event-criteria.js"
+
+/**
+ * A registered command handler — pairs a command descriptor with its handler function.
+ * When the descriptor has a result schema, the handler must return that type.
+ */
+export interface CommandHandlerDefinition<
+  P extends z.ZodType = z.ZodType,
+  R extends z.ZodType | undefined = undefined,
+> {
+  readonly kind: "command-handler"
+  readonly descriptor: CommandDescriptor<P, R>
+  readonly handler: (
+    command: z.infer<P>,
+    metadata: Metadata,
+  ) => R extends z.ZodType ? Promise<z.infer<R>> | z.infer<R> : Promise<void> | void
+  readonly appendCondition?: (
+    command: z.infer<P>,
+    sourcedCriteria: EventCriteria,
+  ) => EventCriteria
+}
+
+/**
+ * Defines a command handler.
+ *
+ * Void command (no result on descriptor):
+ * ```
+ * commandHandler(ChangeCourseCapacity, async (command, metadata) => {
+ *   const course = await load(Course, command.courseId)
+ *   append(CourseCapacityChanged, { courseId: command.courseId, capacity: command.capacity })
+ * })
+ * ```
+ *
+ * Typed result command (result on descriptor):
+ * ```
+ * const CreateCourse = command({
+ *   name: qn("university", "CreateCourse"),
+ *   payload: z.object({ courseId: z.string(), name: z.string() }),
+ *   result: z.object({ courseId: z.string() }),
+ * })
+ *
+ * commandHandler(CreateCourse, async (command, metadata) => {
+ *   append(CourseCreated, { ... })
+ *   return { courseId: command.courseId }  // ← must match descriptor's result schema
+ * })
+ * ```
+ *
+ * With append condition override:
+ * ```
+ * commandHandler(CreateCourse, {
+ *   handler: async (command, metadata) => { ... },
+ *   appendCondition: (command, criteria) => criteria,
+ * })
+ * ```
+ */
+export function commandHandler<P extends z.ZodType>(
+  descriptor: CommandDescriptor<P, undefined>,
+  handler: (
+    command: z.infer<P>,
+    metadata: Metadata,
+  ) => Promise<void> | void,
+): CommandHandlerDefinition<P, undefined>
+
+export function commandHandler<P extends z.ZodType, R extends z.ZodType>(
+  descriptor: CommandDescriptor<P, R>,
+  handler: (
+    command: z.infer<P>,
+    metadata: Metadata,
+  ) => Promise<z.infer<R>> | z.infer<R>,
+): CommandHandlerDefinition<P, R>
+
+export function commandHandler<P extends z.ZodType>(
+  descriptor: CommandDescriptor<P, undefined>,
+  options: {
+    handler: (
+      command: z.infer<P>,
+      metadata: Metadata,
+    ) => Promise<void> | void
+    appendCondition?: (
+      command: z.infer<P>,
+      sourcedCriteria: EventCriteria,
+    ) => EventCriteria
+  },
+): CommandHandlerDefinition<P, undefined>
+
+export function commandHandler<P extends z.ZodType, R extends z.ZodType>(
+  descriptor: CommandDescriptor<P, R>,
+  options: {
+    handler: (
+      command: z.infer<P>,
+      metadata: Metadata,
+    ) => Promise<z.infer<R>> | z.infer<R>
+    appendCondition?: (
+      command: z.infer<P>,
+      sourcedCriteria: EventCriteria,
+    ) => EventCriteria
+  },
+): CommandHandlerDefinition<P, R>
+
+export function commandHandler(
+  descriptor: CommandDescriptor,
+  handlerOrOptions: any,
+): CommandHandlerDefinition {
+  if (typeof handlerOrOptions === "function") {
+    return { kind: "command-handler", descriptor, handler: handlerOrOptions }
+  }
+  return {
+    kind: "command-handler",
+    descriptor,
+    handler: handlerOrOptions.handler,
+    appendCondition: handlerOrOptions.appendCondition,
+  }
+}

package/src/command-handling-module.ts

@@ -0,0 +1,183 @@
+import { qualifiedNameToString, resourceKey } from "@kronos-ts/common"
+import type { CommandHandlerDefinition } from "./command-handler.js"
+
+/**
+ * Minimal Configuration shape consumed by createCommandInvocation /
+ * registerCommandHandlersNatively. Phase 8 D-82 reshape: messaging no longer
+ * depends on the full @kronos-ts/common Configuration interface (deleted
+ * with the configurer trio in Plan 08-04). Callers (kronos() AppImpl.start())
+ * pass a shim that satisfies just these methods.
+ *
+ * The component-key strings used by createCommandInvocation are inlined
+ * below (COMMAND_INVOCATION_KEYS) so this file owns its own key set.
+ */
+export interface MinimalConfiguration {
+  hasComponent(type: string, name?: string): boolean
+  getComponent<T>(type: string, name?: string): T
+  getOptionalComponent<T>(type: string, name?: string): T | undefined
+}
+
+/**
+ * Component-key strings consumed by createCommandInvocation. Inlined here
+ * so this file has no shared-constant dependency. The kronos() AppImpl
+ * populates its config-shim with the same string keys.
+ */
+const COMMAND_INVOCATION_KEYS = {
+  STATE_MANAGER: "stateManager",
+  COMMAND_BUS: "commandBus",
+  QUERY_BUS: "queryBus",
+  EVENT_STORE: "eventStore",
+  TAG_RESOLVER: "tagResolver",
+} as const
+
+const EVENT_FLUSH_REGISTERED_KEY = resourceKey<boolean>("commandInvocationEventFlushRegistered")
+import type { CommandBus } from "./command-bus.js"
+import type { QueryBus } from "./query-bus.js"
+import type { HandlerEnhancerDefinition } from "./handler-enhancer.js"
+import { CORRELATION_DATA_KEY } from "./correlation-data.js"
+import { getResource, setResource, onPrepareCommit, hasResource } from "./processing-state.js"
+import { COMMAND_BUS_KEY } from "./send.js"
+import { QUERY_BUS_KEY } from "./emit-update.js"
+import type { CommandMessage, EventMessage } from "./message.js"
+import {
+  BUFFERED_EVENTS_KEY,
+  SOURCING_INFOS_KEY,
+  STATE_MANAGER_KEY,
+} from "@kronos-ts/eventsourcing"
+
+// ---------------------------------------------------------------------------
+// Command invocation — D-82: byte-identical ALS resource setup at invocation entry.
+// Plan 08-03a expanded the ALS three-key set: STATE_MANAGER + COMMAND_BUS + QUERY_BUS.
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a command handler invocation function that uses the ProcessingContext
+ * for state caching, event buffering, and lifecycle-aware event flushing.
+ *
+ * D-82: ALS resource setup is preserved BYTE-IDENTICAL across the configurer
+ * deletion. The invocation entry seeds the three-key ALS set so module-level
+ * helpers (load/append/send/emitUpdate) and the onPrepareCommit closure all
+ * resolve their dependencies from the active UoW state.
+ */
+export function createCommandInvocation(
+  handler: CommandHandlerDefinition<any, any>,
+  config: MinimalConfiguration,
+) {
+  return async (message: CommandMessage): Promise<unknown> => {
+    // D-82 — full ALS resource setup at command invocation entry.
+    // STATE_MANAGER: read by load() helper. COMMAND_BUS: read by send() helper.
+    // QUERY_BUS: read by emitUpdate() helper.
+    if (config.hasComponent(COMMAND_INVOCATION_KEYS.STATE_MANAGER)) {
+      setResource(STATE_MANAGER_KEY, config.getComponent<any>(COMMAND_INVOCATION_KEYS.STATE_MANAGER))
+    }
+    if (config.hasComponent(COMMAND_INVOCATION_KEYS.COMMAND_BUS)) {
+      setResource(COMMAND_BUS_KEY, config.getComponent<CommandBus>(COMMAND_INVOCATION_KEYS.COMMAND_BUS))
+    }
+    if (config.hasComponent(COMMAND_INVOCATION_KEYS.QUERY_BUS)) {
+      setResource(QUERY_BUS_KEY, config.getComponent<QueryBus>(COMMAND_INVOCATION_KEYS.QUERY_BUS))
+    }
+
+    // Register event flush in PREPARE_COMMIT phase once per UnitOfWork.
+    // Nested context-aware dispatch re-enters createCommandInvocation inside
+    // the same ALS state; without this guard every nested command registers an
+    // additional flush and the same buffered events are appended repeatedly.
+    if (!hasResource(EVENT_FLUSH_REGISTERED_KEY)) {
+      setResource(EVENT_FLUSH_REGISTERED_KEY, true)
+      onPrepareCommit(async () => {
+        const buffered = getResource(BUFFERED_EVENTS_KEY)
+        if (!buffered || buffered.length === 0) return
+        if (!config.hasComponent(COMMAND_INVOCATION_KEYS.EVENT_STORE)) return
+
+        const eventStore = config.getComponent<{ append: (events: ReadonlyArray<EventMessage>, condition?: any) => Promise<unknown> }>(COMMAND_INVOCATION_KEYS.EVENT_STORE)
+
+        // Enrich events with correlation data from ProcessingContext
+        // (set by the CorrelationDataHandlerInterceptor during handler execution)
+        const correlationData = getResource(CORRELATION_DATA_KEY)
+        const enrichedEvents = correlationData
+          ? buffered.map(event => ({
+              ...event,
+              metadata: { ...event.metadata, ...correlationData },
+            }))
+          : buffered
+
+        // Resolve tags via TagResolver (if configured)
+        const tagResolver = config.getOptionalComponent<{ resolve: (event: EventMessage) => Array<{ key: string; value: string }> }>(COMMAND_INVOCATION_KEYS.TAG_RESOLVER)
+        const resolvedEvents = tagResolver
+          ? enrichedEvents.map(event => ({
+              ...event,
+              tags: [...event.tags, ...tagResolver.resolve(event)],
+            }))
+          : enrichedEvents
+        const sourcingInfos = getResource(SOURCING_INFOS_KEY) ?? []
+
+        let appendCondition: any = undefined
+        if (sourcingInfos.length > 0) {
+          const combinedCriteria = sourcingInfos.length === 1
+            ? sourcingInfos[0]!.criteria
+            : { kind: "either" as const, criteria: sourcingInfos.map((s) => s.criteria) }
+
+          const maxMarker = sourcingInfos.reduce(
+            (max, s) => s.markerPosition > max ? s.markerPosition : max,
+            -1n,
+          )
+
+          const finalCriteria = handler.appendCondition
+            ? handler.appendCondition(message.payload, combinedCriteria)
+            : combinedCriteria
+
+          appendCondition = {
+            criteria: finalCriteria,
+            marker: { position: maxMarker },
+          }
+        }
+
+        await eventStore.append(resolvedEvents, appendCondition)
+      })
+    }
+
+    return handler.handler(message.payload, message.metadata)
+  }
+}
+
+/**
+ * Plan 08-03a (D-82 reshape): function-style helper called by AppImpl.start()
+ * to subscribe command handlers natively, without the configurer's Module shape.
+ *
+ * Subscribes each handler onto the commandBus with the createCommandInvocation
+ * wrapper that does Phase 4 D-44 ALS resource setup at invocation entry.
+ *
+ * @param handlers Array of handler definitions to register
+ * @param deps Resolved dependencies — commandBus to subscribe onto, plus a
+ *             Configuration shim (built natively in AppImpl.start()) that
+ *             createCommandInvocation reads inside the dispatch hot path.
+ *             Optional handlerEnhancer mirrors the legacy module's enhancer
+ *             wrap (kept for parity; default-decorator pipeline already
+ *             handles framework-default interceptors).
+ * @param moduleName Logical name passed to the handler enhancer for
+ *                   discriminating command handler groups (default: "commands").
+ */
+export function registerCommandHandlersNatively(
+  handlers: ReadonlyArray<CommandHandlerDefinition<any, any>>,
+  deps: {
+    commandBus: CommandBus
+    config: MinimalConfiguration
+    handlerEnhancer?: HandlerEnhancerDefinition
+    moduleName?: string
+  },
+): void {
+  const moduleName = deps.moduleName ?? "commands"
+  for (const handler of handlers) {
+    const commandName = qualifiedNameToString(handler.descriptor.name)
+    let invocation = createCommandInvocation(handler, deps.config)
+
+    if (deps.handlerEnhancer) {
+      invocation = deps.handlerEnhancer.wrapHandler(invocation, {
+        messageType: "command",
+        messageName: commandName,
+        handlerGroup: moduleName,
+      })
+    }
+
+    deps.commandBus.subscribe(commandName, invocation)
+  }
+}

package/src/correlation-data.ts

@@ -0,0 +1,169 @@
+import { type Metadata, type ResourceKey, resourceKey, mergeMetadata } from "@kronos-ts/common"
+import type { Message } from "./message.js"
+import type { DispatchInterceptor, HandlerInterceptor } from "./interceptor.js"
+import { processingStateStorage, setResource } from "./processing-state.js"
+
+/**
+ * Resource key for storing correlation data in a ProcessingContext.
+ */
+export const CORRELATION_DATA_KEY: ResourceKey<Record<string, string>> = resourceKey("correlationData")
+
+/**
+ * Provides correlation data to attach to outgoing messages based on the
+ * incoming message being processed.
+ *
+ * @see messageOriginProvider
+ * @see simpleCorrelationDataProvider
+ */
+export interface CorrelationDataProvider {
+  /**
+   * Extract correlation data from the given message.
+   * Returns a map of key-value pairs to attach to outgoing messages.
+   * Should not throw — exceptions are caught and logged by the framework.
+   */
+  correlationDataFor(message: Message): Record<string, string>
+}
+
+/**
+ * Get the active correlation data from the active UnitOfWork (D-29 permissive read).
+ *
+ * Reads directly from the ALS state. Returns `undefined` when called outside
+ * an active UnitOfWork (e.g. primary dispatch path, no handler running) —
+ * callers MUST tolerate this no-UoW case.
+ *
+ * Plan 03-04 (CTX-04 / D-29): no-arg permissive ALS read; the explicit
+ * ProcessingContext parameter is gone.
+ */
+export function getActiveCorrelationData(): Record<string, string> | undefined {
+  const state = processingStateStorage.getStore()
+  if (!state) return undefined
+  return state.resources.get(CORRELATION_DATA_KEY.symbol) as
+    | Record<string, string>
+    | undefined
+}
+
+// ---------------------------------------------------------------------------
+// Built-in providers
+// ---------------------------------------------------------------------------
+
+/**
+ * Default correlation data provider that tracks message lineage.
+ *
+ * - `correlationId`: preserved from the incoming message's metadata, or falls
+ *   back to the message's own identifier (starts a new correlation chain).
+ * - `causationId`: always set to the incoming message's identifier (direct cause).
+ *
+ * @param correlationKey metadata key for correlation ID (default: "correlationId")
+ * @param causationKey metadata key for causation ID (default: "causationId")
+ */
+export function messageOriginProvider(
+  correlationKey = "correlationId",
+  causationKey = "causationId",
+): CorrelationDataProvider {
+  return {
+    correlationDataFor(message: Message): Record<string, string> {
+      const existingCorrelation = message.metadata[correlationKey]
+      return {
+        [correlationKey]: existingCorrelation != null
+          ? String(existingCorrelation)
+          : message.identifier,
+        [causationKey]: message.identifier,
+      }
+    },
+  }
+}
+
+/**
+ * Copies specific metadata keys from the incoming message to outgoing messages.
+ *
+ * Silently ignores missing keys.
+ */
+export function simpleCorrelationDataProvider(...metadataKeys: string[]): CorrelationDataProvider {
+  return {
+    correlationDataFor(message: Message): Record<string, string> {
+      const result: Record<string, string> = {}
+      for (const key of metadataKeys) {
+        if (key in message.metadata && message.metadata[key] != null) {
+          result[key] = String(message.metadata[key])
+        }
+      }
+      return result
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Interceptor factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a handler interceptor that extracts correlation data from the
+ * incoming message and stores it in the ProcessingContext.
+ *
+ * This is the "extract" phase of the dual-interceptor pattern.
+ *
+ * Each provider is called with the message. Exceptions are caught and
+ * logged (they don't break message processing). Results are merged —
+ * later providers override earlier ones on key conflicts.
+ *
+ * The correlation data is stored as a ProcessingContext resource under
+ * `CORRELATION_DATA_KEY`, where the dispatch interceptor reads it.
+ */
+export function correlationDataHandlerInterceptor(
+  providers: ReadonlyArray<CorrelationDataProvider>,
+): HandlerInterceptor {
+  return (message, next) => {
+    const correlationData: Record<string, string> = {}
+
+    for (const provider of providers) {
+      try {
+        const data = provider.correlationDataFor(message)
+        Object.assign(correlationData, data)
+      } catch (err) {
+        console.warn(
+          "Encountered exception creating correlation data from provider:",
+          err,
+        )
+      }
+    }
+
+    // Store in ALS-backed processing state.
+    // CTX-01 / Plan 03-03: HandlerInterceptor no longer threads ProcessingContext;
+    // resource writes go directly through the module-level ALS accessor.
+    setResource(CORRELATION_DATA_KEY, correlationData)
+
+    return next()
+  }
+}
+
+/**
+ * Creates a dispatch interceptor that reads correlation data from the
+ * active ProcessingContext and merges it into the outgoing message's
+ * metadata.
+ *
+ * This is the "apply" phase of the dual-interceptor pattern.
+ *
+ * When a ProcessingContext is available (nested dispatch from a handler),
+ * the interceptor reads correlation data stored by the handler interceptor
+ * and merges it into the outgoing message's metadata. For the primary
+ * dispatch path (no context), this is a no-op — correlation data flows
+ * through message metadata inheritance.
+ */
+export function correlationDataDispatchInterceptor<M extends Message>(): DispatchInterceptor<M> {
+  return (message: M): M => {
+    // D-24: single code path. Read directly from the ALS state — `getResource`
+    // throws on no-UoW, but the dispatch interceptor MUST tolerate the no-UoW
+    // primary-dispatch path and return the message unchanged.
+    // CTX-01 / Plan 03-03: vestigial _context parameter removed.
+    const state = processingStateStorage.getStore()
+    if (!state) return message
+    const correlationData = state.resources.get(CORRELATION_DATA_KEY.symbol) as
+      | Record<string, string>
+      | undefined
+    if (!correlationData || Object.keys(correlationData).length === 0) return message
+    return {
+      ...message,
+      metadata: mergeMetadata(message.metadata, correlationData),
+    }
+  }
+}