@kronos-ts/messaging 0.2.0 → 0.3.0

package/src/handler.ts

@@ -1,10 +1,10 @@
 import type { z } from "zod"
-import type { Metadata } from "@kronos-ts/common"
 import type {
   CommandDescriptor,
   EventDescriptor,
   QueryDescriptor,
 } from "./descriptor.js"
+import type { EventMessage, QueryMessage, SequencedEventMessage } from "./message.js"
 
 // ---------------------------------------------------------------------------
 // Handler context shapes — DELETED (Plan 04-02, D-41)
@@ -22,10 +22,7 @@ import type {
 export interface EventHandlerRegistration<P extends z.ZodType = z.ZodType> {
   readonly kind: "event-handler"
   readonly descriptor: EventDescriptor<P>
-  readonly handler: (
-    event: z.infer<P>,
-    metadata: Metadata,
-  ) => Promise<void> | void
+  readonly handler: (message: SequencedEventMessage<z.infer<P>>) => Promise<void> | void
 }
 
 /**
@@ -40,7 +37,7 @@ export interface EvolverRegistration<
 > {
   readonly kind: "evolver"
   readonly descriptor: EventDescriptor<P>
-  readonly evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>
+  readonly evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>
 }
 
 /** A paired query descriptor + handler function, with result type on the handler. */
@@ -50,10 +47,7 @@ export interface QueryHandlerRegistration<
 > {
   readonly kind: "query-handler"
   readonly descriptor: QueryDescriptor<Q>
-  readonly handler: (
-    query: z.infer<Q>,
-    metadata: Metadata,
-  ) => Promise<R> | R
+  readonly handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R
 }
 
 // ---------------------------------------------------------------------------
@@ -65,13 +59,13 @@ export interface QueryHandlerRegistration<
  * Pairs a descriptor with its handler for use in handler/evolve arrays.
  *
  * Usage:
- * - Event handlers:  `on(CourseCreated, async (event, ctx) => { ... })`
- * - Query handlers:  `on(GetCourse, async (query, ctx) => { return { ... } })`
- * - Evolvers:        `on(CourseCreated, (state, event) => ({ ...state, name: event.name }))`
+ * - Event handlers:  `on(CourseCreated, async ({ payload, metadata }) => { ... })`
+ * - Query handlers:  `on(GetCourse, async ({ payload, metadata }) => { return { ... } })`
+ * - Evolvers:        `on(CourseCreated, (state, { payload }) => ({ ...state, name: payload.name }))`
  *
  * The overload is resolved by the descriptor kind and how many arguments
- * the callback declares. Evolvers receive `(state, event)` or `(state, event, id)`,
- * while event handlers receive `(event, context)`.
+ * the callback declares. Event and query handlers receive the full typed message.
+ * Evolvers receive the current state plus the full typed event message.
  *
  * In practice the distinction is enforced by the array type:
  * - `evolve: [on(...)]` expects `EvolverRegistration`
@@ -81,22 +75,19 @@ export interface QueryHandlerRegistration<
 // Overload: evolver (event descriptor + state evolve function)
 export function on<S, P extends z.ZodType>(
   descriptor: EventDescriptor<P>,
-  evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>,
+  evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>,
 ): EvolverRegistration<S, P>
 
 // Overload: event handler (event descriptor + handler function)
 export function on<P extends z.ZodType>(
   descriptor: EventDescriptor<P>,
-  handler: (event: z.infer<P>, metadata: Metadata) => Promise<void> | void,
+  handler: (message: SequencedEventMessage<z.infer<P>>) => Promise<void> | void,
 ): EventHandlerRegistration<P>
 
 // Overload: query handler
 export function on<Q extends z.ZodType, R>(
   descriptor: QueryDescriptor<Q>,
-  handler: (
-    query: z.infer<Q>,
-    metadata: Metadata,
-  ) => Promise<R> | R,
+  handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R,
 ): QueryHandlerRegistration<Q, R>
 
 export function on(
@@ -127,7 +118,7 @@ export function on(
  */
 export function onEvent<S, P extends z.ZodType>(
   descriptor: EventDescriptor<P>,
-  evolve: (state: S, event: z.infer<P>, id: unknown) => S | Promise<S>,
+  evolve: (state: S, message: EventMessage<z.infer<P>>) => S | Promise<S>,
 ): EvolverRegistration<S, P> {
   return { kind: "evolver", descriptor, evolve }
 }

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   type CommandMessage,
   type CommandResultMessage,
   type EventMessage,
+  type SequencedEventMessage,
   type QueryMessage,
 } from "./message.js"
 
@@ -375,4 +376,3 @@ export {
 
 // Namespace factory
 export { withNamespace } from "./with-namespace.js"
-

package/src/intercepting-command-bus.ts

@@ -15,10 +15,10 @@ export function createInterceptingCommandBus(
   /** Register a dispatch interceptor. Returns an unsubscribe function. */
   registerDispatchInterceptor(interceptor: DispatchInterceptor<CommandMessage>): () => void
   /** Register a handler interceptor. Returns an unsubscribe function. */
-  registerHandlerInterceptor(interceptor: HandlerInterceptor): () => void
+  registerHandlerInterceptor(interceptor: HandlerInterceptor<CommandMessage>): () => void
 } {
   const dispatchInterceptors: Array<DispatchInterceptor<CommandMessage>> = []
-  const handlerInterceptors: Array<HandlerInterceptor> = []
+  const handlerInterceptors: Array<HandlerInterceptor<CommandMessage>> = []
 
   return {
     async dispatch(message: CommandMessage): Promise<unknown> {
@@ -35,20 +35,21 @@ export function createInterceptingCommandBus(
       commandName: string,
       handler: (message: CommandMessage) => Promise<unknown>,
     ) {
-      // Wrap the handler with handler interceptors
       const wrappedHandler = (message: CommandMessage) => {
         if (handlerInterceptors.length === 0) {
           return handler(message)
         }
 
-        let chain = () => handler(message)
+        let chain = (currentMessage: CommandMessage) => handler(currentMessage)
         for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
           const interceptor = handlerInterceptors[i]!
           const next = chain
-          chain = () => interceptor(message, next)
+          chain = (currentMessage: CommandMessage) =>
+            interceptor(currentMessage, (replacementMessage) =>
+              next(replacementMessage ?? currentMessage))
         }
 
-        return chain()
+        return chain(message)
       }
 
       delegate.subscribe(commandName, wrappedHandler)

package/src/intercepting-query-bus.ts

@@ -17,10 +17,10 @@ export function createInterceptingQueryBus(
   /** Register a dispatch interceptor. Returns an unsubscribe function. */
   registerDispatchInterceptor(interceptor: DispatchInterceptor<QueryMessage>): () => void
   /** Register a handler interceptor. Returns an unsubscribe function. */
-  registerHandlerInterceptor(interceptor: HandlerInterceptor): () => void
+  registerHandlerInterceptor(interceptor: HandlerInterceptor<QueryMessage>): () => void
 } {
   const dispatchInterceptors: Array<DispatchInterceptor<QueryMessage>> = []
-  const handlerInterceptors: Array<HandlerInterceptor> = []
+  const handlerInterceptors: Array<HandlerInterceptor<QueryMessage>> = []
 
   return {
     async query(message: QueryMessage): Promise<unknown> {
@@ -36,20 +36,21 @@ export function createInterceptingQueryBus(
       queryName: string,
       handler: (message: QueryMessage) => Promise<unknown>,
     ) {
-      // Wrap the handler with handler interceptors
       const wrappedHandler = (message: QueryMessage) => {
         if (handlerInterceptors.length === 0) {
           return handler(message)
         }
 
-        let chain = () => handler(message)
+        let chain = (currentMessage: QueryMessage) => handler(currentMessage)
         for (let i = handlerInterceptors.length - 1; i >= 0; i--) {
           const interceptor = handlerInterceptors[i]!
           const next = chain
-          chain = () => interceptor(message, next)
+          chain = (currentMessage: QueryMessage) =>
+            interceptor(currentMessage, (replacementMessage) =>
+              next(replacementMessage ?? currentMessage))
         }
 
-        return chain()
+        return chain(message)
       }
 
       delegate.subscribe(queryName, wrappedHandler)

package/src/interceptor.ts

@@ -1,4 +1,3 @@
-import type { Metadata } from "@kronos-ts/common"
 import type { Message } from "./message.js"
 
 /**
@@ -38,11 +37,29 @@ export interface DispatchInterceptor<M extends Message = Message> {
  * accessors (`getResource` / `setResource`) — no `ProcessingContext`
  * parameter is threaded.
  *
+ * The first argument is the full message object. Prefer keeping it as
+ * `message` when transforming or inspecting broad message details:
+ *
+ * ```
+ * app.handlerInterceptor(async (message, next) => {
+ *   const { payload, metadata, timestamp } = message
+ *   return next({
+ *     ...message,
+ *     metadata: { ...metadata, tenantId: "tenant-1" },
+ *   })
+ * })
+ * ```
+ *
  * The `next` function calls the next interceptor in the chain, or the
- * actual handler if this is the last interceptor.
+ * actual handler if this is the last interceptor. Call `next()` to proceed
+ * with the current message, or `next(replacementMessage)` to proceed with a
+ * transformed message.
  *
  * To skip handling entirely, don't call `next()` and return a result directly.
  */
-export interface HandlerInterceptor<R = unknown> {
-  (message: Message, next: () => Promise<R>): Promise<R>
+export interface HandlerInterceptor<
+  M extends Message = Message,
+  R = unknown,
+> {
+  (message: M, next: (message?: M) => Promise<R>): Promise<R>
 }

package/src/message.ts

@@ -35,6 +35,11 @@ export interface EventMessage<P = unknown> extends Message<P> {
   readonly tags: ReadonlyArray<{ readonly key: string; readonly value: string }>
 }
 
+export interface SequencedEventMessage<P = unknown> extends EventMessage<P> {
+  /** Stream position when the source has one; absent for push-only delivery. */
+  readonly sequence?: bigint
+}
+
 /**
  * A query message — dispatched to handler(s) that can answer it.
  */

package/src/query-handler.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod"
-import type { Metadata } from "@kronos-ts/common"
 import type { QueryDescriptor } from "./descriptor.js"
+import type { QueryMessage } from "./message.js"
 
 // ---------------------------------------------------------------------------
 // Singular factory — mirrors commandHandler / eventHandler.
@@ -23,15 +23,15 @@ export interface QueryHandlerDefinition<
 > {
   readonly kind: "query-handler"
   readonly descriptor: QueryDescriptor<Q, z.ZodType | undefined>
-  readonly handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R
+  readonly handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R
 }
 
 /**
  * Defines a singular query handler.
  *
  * ```
- * const getCourseView = queryHandler(GetCourseView, async (q, metadata) => {
- *   const view = courseViews.get(q.courseId)
+ * const getCourseView = queryHandler(GetCourseView, async ({ payload, metadata }) => {
+ *   const view = courseViews.get(payload.courseId)
  *   if (!view) throw new Error("not found")
  *   return view
  * })
@@ -43,7 +43,7 @@ export interface QueryHandlerDefinition<
  */
 export function queryHandler<Q extends z.ZodType, R>(
   descriptor: QueryDescriptor<Q, z.ZodType | undefined>,
-  handler: (query: z.infer<Q>, metadata: Metadata) => Promise<R> | R,
+  handler: (message: QueryMessage<z.infer<Q>>) => Promise<R> | R,
 ): QueryHandlerDefinition<Q, R> {
   return { kind: "query-handler", descriptor, handler }
 }

package/src/query-handling-module.ts

@@ -31,7 +31,7 @@ export function registerQueryHandlersNatively(
   for (const reg of handlers) {
     const queryName = qualifiedNameToString(reg.descriptor.name)
     let invocation = async (message: QueryMessage) =>
-      reg.handler(message.payload, message.metadata)
+      reg.handler(message)
     if (deps.handlerEnhancer) {
       invocation = deps.handlerEnhancer.wrapHandler(invocation, {
         messageType: "query",

package/src/simple-command-bus.ts

@@ -1,6 +1,6 @@
 import type { CommandBus } from "./command-bus.js"
 import type { CommandMessage } from "./message.js"
-import { runInNewUoW } from "./unit-of-work.js"
+import { runInNewUoW, type UoWRunner } from "./unit-of-work.js"
 import { qualifiedNameToString } from "@kronos-ts/common"
 
 /**
@@ -16,14 +16,20 @@ import { qualifiedNameToString } from "@kronos-ts/common"
  * 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.
+ * The handler runs through `unitOfWorkRunner` — by default `runInNewUoW`, but
+ * the configurer injects the resolved `unitOfWorkFactory` slot (e.g. a
+ * transactional runner from a storage extension) so the per-command UoW
+ * carries whatever transaction that backend provides. This mirrors the
+ * distributed command buses (kronosdb / axon-server), which already run
+ * handlers through the configured runner. The runner is always built on
+ * `runInNewUoW`, so a command — primary OR nested via `send()` — still gets
+ * its own fresh UoW (and its own independent transaction); composition does
+ * not change AF5 isolation, only whether that fresh UoW has a transaction.
  *
  * Interceptor support is provided by wrapping with
  * {@link createInterceptingCommandBus}.
  */
-export function createSimpleCommandBus(): CommandBus {
+export function createSimpleCommandBus(unitOfWorkRunner: UoWRunner = runInNewUoW): CommandBus {
   const handlers = new Map<string, (message: CommandMessage) => Promise<unknown>>()
 
   return {
@@ -34,12 +40,12 @@ export function createSimpleCommandBus(): CommandBus {
         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))
+      // AF5 parity: every command gets its own fresh UnitOfWork (the runner is
+      // built on runInNewUoW), 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 unitOfWorkRunner(message.metadata, () => handler(message))
     },
 
     subscribe(

package/src/streaming-event-processor.ts

@@ -249,7 +249,7 @@ export function createStreamingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler({ ...event, sequence: sequencedEvent.sequence })
       } catch (err) {
         await errorHandler.handleError(err, eventName, sequencedEvent.sequence)
       }

package/src/subscribing-event-processor.ts

@@ -135,7 +135,7 @@ export function createSubscribingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler(event)
       } catch (err) {
         // SubscribingEventProcessor doesn't have position tracking,
         // so pass -1n as position indicator

package/src/tracking-event-processor.ts

@@ -268,7 +268,7 @@ export function createTrackingEventProcessor(
 
     for (const reg of handlers) {
       try {
-        await reg.handler(event.payload, event.metadata)
+        await reg.handler({ ...event, sequence: sequencedEvent.sequence })
       } catch (err) {
         await errorHandler.handleError(err, eventName, sequencedEvent.sequence)
       }