@kronos-ts/axon-server 0.3.2 → 0.5.0

package/dist/axon-server.js

@@ -1,74 +1,48 @@
 /**
- * Axon Server backend for kronos.
+ * The Axon Server command and query buses.
  *
- * `axonServer(config)` is an async factory: it connects eagerly, hands back
- * the four components it provides (eventStore, snapshotStore, commandBus,
- * queryBus), and gives you a `start`/`close` pair. There is no lifecycle
- * framework — the ordering that used to be encoded as `onStart("connect")` /
- * `onStart("processors")` / `onStop("connect")` is now three lines you write
- * in your composition root:
+ * Axon Server is a SMART HUB: outbound dispatch always goes to the server, and
+ * the server decides which node handles it — there is no client-side
+ * prefer-next fork here, which is the whole difference from the dumb-pipe
+ * broker in `@kronos-ts/rabbitmq`.
  *
- * ```ts
- * const axon = await axonServer({
- *   componentName: "university-service",
- *   serializer,
- *   unitOfWorkFactory,
- * })
- * const app = kronos({
- *   components: { ...inMemoryComponents({ serializer, unitOfWorkFactory }), ...axon.components },
- *   modules,
- * })
- * await axon.start()   // readiness barrier: the server can route to our handlers
- * // …
- * await app.stop(); await axon.close()
- * ```
- *
- * Connecting before the app is built is what removes the lazy proxies and
- * subscribe-buffering wrappers the container version needed: by the time
- * `kronos` subscribes a handler, the gRPC streams are already live.
- *
- * REMOTE ADMINISTRATION IS NOT IN HERE. Processor instructions (pause / start /
- * release / split / merge) and processor status reporting are the platform
- * CONTROL PLANE — they are neither persistence nor transport, and lived here
- * only because they share this gRPC connection. They are now an opt-in second
- * object built on the platform stream this backend exposes:
+ * Both buses are plain functions over the shared connection and YOUR next bus:
  *
  * ```ts
- * const control = await axonServerControlPlane(axon.platform, app.processors.values())
+ * const commandBus = interceptingCommandBus(
+ *   axonServerCommandBus(localCommandBus(unitOfWork), axon), correlation)
+ * const queryBus = interceptingQueryBus(
+ *   axonServerQueryBus(localQueryBus(unitOfWork), axon), correlation)
  * ```
  *
- * `start()` therefore takes NO arguments and does exactly one thing: the
- * data-path readiness barrier. See `control-plane.ts`.
- *
  * Axon-specific protocol invariants are preserved byte-for-byte:
  *
  *   - CLIENT_SUPPORTS_STREAMING capability advertised on every dispatched
  *     query via `defaultQueryInstructions(...)`;
  *   - AxonIQ-Context + AxonIQ-Access-Token gRPC metadata headers built by
- *     `createAxonMetadata(...)` and attached to every outbound stream/RPC;
+ *     `contextView(...)` and attached to every outbound stream/RPC;
  *   - permits-AFTER-subscriptions stream ordering preserved on the initial
  *     handshake AND on reconnect (see `ensureStreamStarted` /
- *     `reestablishStreamBody`);
- *   - shutdown ordering: busLatches → platform.stop → connection.close.
+ *     `reestablishStreamBody`).
  */
-import { qualifiedNameToString, qualifiedNameFromString, generateIdentifier, withRetry, healthCheck, } from "@kronos-ts/common";
-import { applySubscriptionFilter, correlationDataDispatchInterceptor, interceptingCommandBus, interceptingQueryBus, updateHandler, runAfterCommitOrImmediately, } from "@kronos-ts/messaging";
-import { Metadata } from "nice-grpc";
-import { connectToAxonServer } from "./connection.js";
-import { axonServerEventStore } from "./axon-server-event-store.js";
-import { axonServerSnapshotStore } from "./axon-server-snapshot-store.js";
+import { qualifiedNameToString, qualifiedNameFromString, generateIdentifier, } from "@kronos-ts/core";
+import { withRetry } from "./resilience.js";
+import { applySubscriptionFilter, updateHandler, runAfterCommitOrImmediately, } from "@kronos-ts/core";
+import { contextView } from "./context-view.js";
 import { metadataToProto, metadataFromProto } from "./metadata-conversion.js";
 import { outboundStream } from "./outbound-stream.js";
 import { mapErrorCode, AxonServerErrorCode } from "./errors.js";
-import { shutdownLatch } from "./shutdown-latch.js";
-import { platformConnection, } from "./platform-service.js";
 /** Default flow control settings — aligned with Java's 5000 permits. */
 const DEFAULT_PERMITS = 5000n;
 const DEFAULT_THRESHOLD = 2500n;
+/** Default query dispatch timeout — aligned with Java's one hour. */
+const DEFAULT_QUERY_TIMEOUT_MS = 3_600_000;
+/** Default command handler load factor — aligned with Java's 100. */
+const DEFAULT_LOAD_FACTOR = 100;
 // Processing instruction keys — aligned with proto ProcessingKey enum.
 // CLIENT_SUPPORTS_STREAMING (key=8) is an Axon-Server-specific capability
-// advertisement that MUST survive the migration verbatim — see file-level
-// JSDoc above and `defaultQueryInstructions` below.
+// advertisement that MUST survive verbatim — see file-level JSDoc above and
+// `defaultQueryInstructions` below.
 const INSTRUCTION_KEY = {
     ROUTING_KEY: 0,
     PRIORITY: 1,
@@ -84,10 +58,16 @@ function toProtoProcessingInstructions(instructions) {
         result.push({ key: INSTRUCTION_KEY.ROUTING_KEY, value: { textValue: instructions.routingKey } });
     }
     if (instructions.priority !== undefined) {
-        result.push({ key: INSTRUCTION_KEY.PRIORITY, value: { numberValue: BigInt(instructions.priority) } });
+        result.push({
+            key: INSTRUCTION_KEY.PRIORITY,
+            value: { numberValue: BigInt(instructions.priority) },
+        });
     }
     if (instructions.timeoutMs !== undefined) {
-        result.push({ key: INSTRUCTION_KEY.TIMEOUT, value: { numberValue: BigInt(instructions.timeoutMs) } });
+        result.push({
+            key: INSTRUCTION_KEY.TIMEOUT,
+            value: { numberValue: BigInt(instructions.timeoutMs) },
+        });
     }
     return result;
 }
@@ -104,102 +84,8 @@ function defaultQueryInstructions(timeoutMs) {
         { key: INSTRUCTION_KEY.CLIENT_SUPPORTS_STREAMING, value: { booleanValue: true } },
     ];
 }
-/**
- * Build the gRPC metadata headers required by Axon Server. AxonIQ-Context
- * is mandatory (identifies the tenant/context); AxonIQ-Access-Token is
- * optional auth. Both must be attached to every outbound stream/RPC —
- * preserved verbatim from the legacy enhancer.
- */
-function createAxonMetadata(config) {
-    const metadata = new Metadata();
-    metadata.set("AxonIQ-Context", config.context);
-    if (config.token) {
-        metadata.set("AxonIQ-Access-Token", config.token);
-    }
-    return metadata;
-}
-/**
- * Connect to Axon Server and build the components it backs.
- *
- * `serializer` and `unitOfWorkFactory` are arguments rather than slot lookups:
- * the buses serialize payloads with the former and run every inbound command /
- * query in the latter, so they must be the SAME instances the rest of the app
- * uses. Pass the ones you hand to `kronos`.
- */
-export async function axonServer(options) {
-    const config = options;
-    const { serializer, unitOfWorkFactory, resilience } = config;
-    const connection = await withRetry(async () => connectToAxonServer(config), {
-        event: "initial-connect",
-        ...resilience,
-    });
-    // Health-check ping with warn-then-continue (D-100). AxonServerConnection has
-    // no dedicated probe surface today; the gRPC channel itself is created
-    // eagerly in connectToAxonServer so the meaningful probe is a round-trip — we
-    // approximate via a soft no-op promise that satisfies the threshold contract.
-    // Real network failure is surfaced by the first bus call against the channel.
-    await healthCheck(async () => undefined, {
-        thresholdMs: resilience?.healthCheckThresholdMs,
-        log: resilience?.log,
-    });
-    // One latch per bus, drained in close() before the transport goes away.
-    const commandLatch = shutdownLatch();
-    const queryLatch = shutdownLatch();
-    const busLatches = [commandLatch, queryLatch];
-    // The connection is live before anything below is built, so the buses open
-    // their gRPC streams for real and `subscribe()` reaches the wire immediately —
-    // no lazy proxy, no subscription buffering, no readiness promise.
-    const components = {
-        eventStore: axonServerEventStore(connection, serializer),
-        snapshotStore: axonServerSnapshotStore(connection, serializer),
-        commandBus: distributedCommandBus(connection, unitOfWorkFactory, commandLatch, serializer, config.commandFlowControl, config.commandLoadFactor, resilience),
-        queryBus: distributedQueryBus(connection, unitOfWorkFactory, queryLatch, serializer, config.queryFlowControl, config.shortcutQueriesToLocalHandlers, config.queryTimeoutMs, resilience),
-    };
-    // Built here, started by the control plane (or by the caller). Constructing it
-    // eagerly is what lets the control plane be a separate object at all — and it
-    // keeps `platformService` tuning and `stop()` ownership in one place, so the
-    // documented shutdown order below holds whether or not anyone opted in.
-    const platform = platformConnection(connection, config.platformService);
-    return {
-        components,
-        platform,
-        async start() {
-            // RECONNECT DETECTION IS DATA PATH. The heartbeat on the platform stream
-            // is what notices a dead channel and calls `connection.reconnect()`; both
-            // buses above hook `connection.onReconnect(...)` to rebuild their own
-            // streams. Arming it used to be a side effect of `platform.start()`, which
-            // only `axonServerControlPlane(...)` calls — so a service that never opted
-            // into remote administration had NO reconnect detection at all and would
-            // sit on a dead channel forever. It is armed here, unconditionally,
-            // independent of whether anyone administers this service.
-            //
-            // `armConnectionMonitoring()` opens the stream and starts heartbeats but
-            // arms NO processor status reporting; that stays the control plane's, and
-            // a later `platform.start()` adds it to this same live stream. Both calls
-            // are idempotent, so either order works.
-            await platform.armConnectionMonitoring();
-            // The only thing the data path has to wait for: Axon Server's
-            // command/query routing tables registering the subscribe frames sent on
-            // the BUS streams. It cannot be derived from the platform stream, because
-            // subscribes travel on a different stream entirely — and the platform
-            // stream's own `subscriptionsAcked()` latch says nothing about them (it
-            // latches unconditionally once `register` has been flushed; see
-            // platform-service.ts). So this barrier is the settle wait, and it is
-            // deliberately independent of whether the platform stream is up at all.
-            // The legacy enhancer carried the same 1s wait.
-            await new Promise((r) => setTimeout(r, config.busSubscriptionAckDelayMs ?? 1000));
-        },
-        async close() {
-            await Promise.all(busLatches.map((l) => l.initiateShutdown()));
-            // Idempotent, and independent of `control.close()` — a backend that was
-            // never administered still stops a platform stream someone else started.
-            platform.stop();
-            connection.close();
-        },
-    };
-}
 // ---------------------------------------------------------------------------
-// Shared payload helpers (moved verbatim from legacy enhancer)
+// Shared payload helpers
 // ---------------------------------------------------------------------------
 function createPayloadHelpers(serializer) {
     return {
@@ -214,68 +100,66 @@ function createPayloadHelpers(serializer) {
     };
 }
 // ---------------------------------------------------------------------------
-// Distributed Command Bus
-//
-// Bus implementation moved verbatim from the legacy enhancer with TWO
-// behavioural additions per D-97:
-//   1) reestablishStream() body wrapped in withRetry({ event: "reconnect" })
-//   2) inbound-stream backoff replaced by the same withRetry path
-//
-// Axon-specific protocol invariants preserved BYTE-FOR-BYTE:
-//   - AxonIQ-Context + AxonIQ-Access-Token gRPC metadata headers via
-//     createAxonMetadata(connection.config)
-//   - permits-AFTER-subscriptions ordering on reestablishStreamBody (subs
-//     are sent BEFORE grantPermits() in the reconnect path; the initial
-//     handshake matches this — see ensureStreamStarted's grantPermits call
-//     in subscribe()).
+// Axon Server Command Bus
 // ---------------------------------------------------------------------------
 /**
- * A command bus backed by Axon Server.
+ * A command bus backed by Axon Server, over YOUR next bus.
  *
- * - **Outbound dispatch**: Always goes through Axon Server via the unary Dispatch RPC.
- *   Axon Server routes the command to the appropriate node (which may be this one).
- * - **Local segment**: Handlers subscribed via `subscribe()` are registered with
- *   Axon Server (so other nodes can route to us) and stored locally. When Axon Server
- *   routes an inbound command to this node, it's executed on the local segment
- *   within a UnitOfWork.
- */
-/**
- * A command bus backed by Axon Server.
+ * - **Outbound dispatch**: ALWAYS through Axon Server, via the unary Dispatch
+ *   RPC. Axon Server routes the command to the appropriate node (which may be
+ *   this one). There is deliberately no client-side prefer-next fork: the hub
+ *   is the router, and short-circuiting it would silently defeat load factors,
+ *   priorities and routing keys.
+ * - **Inbound**: a command the server routes here is dispatched into `next` —
+ *   not into a privately-held handler map. That is what makes the unit-of-work
+ *   policy you chose for `next` (say `postgresUnitOfWork(unitOfWork, pg)`)
+ *   apply to server-routed work exactly as it applies to work this process
+ *   originated. It is also why this function takes no `unitOfWork` argument:
+ *   `next` carries that policy now.
+ * - **subscribe**: registers the handler on `next` AND announces the name to
+ *   Axon Server, so other nodes can route to us.
  *
- * ## Correlation lineage and the interceptor layer
+ * ## correlation and the interceptor layer
  *
- * The returned bus is wrapped in {@link interceptingCommandBus} carrying
- * {@link correlationDataDispatchInterceptor}, so lineage is stamped onto the
- * outgoing message BEFORE it is serialized onto the wire.
+ * The returned bus stamps no correlation of its own. A host that wants it wraps the
+ * OUTERMOST bus:
+ *
+ * ```ts
+ * interceptingCommandBus(axonServerCommandBus(next, conn), correlation)
+ * ```
+ *
+ * so whatever a host adds runs BEFORE the message is serialized onto the wire.
+ * Correlation itself is usually already on `message.metadata` by then — `ctx.send`
+ * stamps the unit of work's correlation data before any bus sees the message.
  *
  * This is precisely how the Java client does it. AF4's `AxonServerCommandBus`
  * holds its own `DispatchInterceptors` and dispatches as
  * `doDispatch(dispatchInterceptors.intercept(commandMessage), cb)` — one call
- * site, at the top, ahead of any routing; and its `doDispatch` (like this one)
- * always goes to the server, letting Axon Server decide where the command lands.
- * AF5 keeps the property via decorator order:
- * `DISTRIBUTED_COMMAND_BUS_ORDER = InterceptingCommandBus.DECORATION_ORDER - 50`
- * stacks `InterceptingCommandBus → DistributedCommandBus → SimpleCommandBus`.
- *
- * Before this wrap, an Axon-backed service lost lineage on EVERY command: the
- * only registration of `correlationDataDispatchInterceptor` lives in
- * `@kronos-ts/app`'s in-memory default bus, and `components.commandBus` from
- * this backend replaces it wholesale.
+ * site, at the top, ahead of any routing. AF5 keeps the property via decorator
+ * order: `DISTRIBUTED_COMMAND_BUS_ORDER = InterceptingCommandBus.DECORATION_ORDER - 50`
+ * stacks `InterceptingCommandBus → DistributedCommandBus → LocalCommandBus`.
  *
- * No double-application risk: the local segment here is a plain handler map, not
- * a `CommandBus`, so this is the only interceptor in the chain. Inbound commands
- * from the server are invoked through that map directly, which matches AF —
- * `CommandProcessingTask` runs the local segment WITHOUT re-running dispatch
- * interceptors.
+ * If `next` is itself an intercepting bus, a server-routed command sees
+ * `correlation` twice. That is harmless: both of its fields are `??` seeds, so the
+ * second application finds them set and changes nothing.
  */
-export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatch, serializer, flowControl, commandLoadFactor, resilience) {
-    const metadata = createAxonMetadata(connection.config);
+export function axonServerCommandBus(next, conn, options = {}) {
+    const { connection, serializer, metadata: axonMetadata, } = contextView(conn, options.context ?? conn.connection.config.context);
+    const shutdownLatch = conn.shutdown;
+    const resilience = options.resilience ?? conn.resilience;
+    const metadata = axonMetadata();
     const { serializePayload, deserializePayload } = createPayloadHelpers(serializer);
-    const PERMITS = BigInt(flowControl?.permits ?? Number(DEFAULT_PERMITS));
-    const THRESHOLD = BigInt(flowControl?.refillThreshold ?? Number(DEFAULT_THRESHOLD));
-    // Local segment — handlers that execute on this node
-    const localSegment = new Map();
-    // Bidirectional stream for handler registration + inbound command handling
+    const PERMITS = BigInt(options.flowControl?.permits ?? Number(DEFAULT_PERMITS));
+    const THRESHOLD = BigInt(options.flowControl?.refillThreshold ?? Number(DEFAULT_THRESHOLD));
+    const loadFactor = options.loadFactor ?? DEFAULT_LOAD_FACTOR;
+    /**
+     * The names this node announced to Axon Server. The handlers themselves live
+     * on `next`; this set exists so an inbound command for a name we never
+     * subscribed still answers NO_HANDLER_FOR_COMMAND rather than whatever
+     * `next.dispatch` happens to throw — and so a reconnect can re-announce.
+     */
+    const subscribedNames = new Set();
+    // Bidirectional stream for handler subscription + inbound command handling
     let outbound = outboundStream();
     let streamStarted = false;
     let permits = 0n;
@@ -294,8 +178,20 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
         });
         permits += PERMITS;
     }
+    function sendSubscribe(commandName) {
+        outbound.send({
+            subscribe: {
+                messageId: generateIdentifier(),
+                command: commandName,
+                componentName: connection.config.componentName,
+                clientId: connection.config.clientId,
+                loadFactor,
+            },
+            instructionId: generateIdentifier(),
+        });
+    }
     /**
-     * Re-establish the bidirectional stream and re-subscribe all handlers.
+     * Re-establish the bidirectional stream and re-announce all handlers.
      * Called on stream error or when the connection reconnects.
      *
      * ORDER (preserves Axon-specific invariant): subscriptions are
@@ -309,18 +205,8 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
         permits = 0n;
         ensureStreamStarted();
         // Re-subscribe all handlers FIRST
-        for (const commandName of localSegment.keys()) {
-            outbound.send({
-                subscribe: {
-                    messageId: generateIdentifier(),
-                    command: commandName,
-                    componentName: connection.config.componentName,
-                    clientId: connection.config.clientId,
-                    loadFactor: commandLoadFactor ?? 100,
-                },
-                instructionId: generateIdentifier(),
-            });
-        }
+        for (const commandName of subscribedNames)
+            sendSubscribe(commandName);
         // Permits AFTER subscriptions (Axon-specific ordering invariant)
         grantPermits();
     }
@@ -336,7 +222,7 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
     connection.onReconnect(() => {
         if (!shutdownLatch.shuttingDown && streamStarted) {
             reestablishStreamWithRetry().catch((err) => {
-                console.error("Distributed command bus: reconnect retries exhausted", err);
+                console.error("Axon Server command bus: reconnect retries exhausted", err);
             });
         }
     });
@@ -348,11 +234,10 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
                 permits--;
                 const proto = message.command;
                 const commandName = proto.name;
-                const handler = localSegment.get(commandName);
                 let resultPayload;
                 let errorCode = "";
                 let errorMsg = "";
-                if (handler) {
+                if (subscribedNames.has(commandName)) {
                     try {
                         const commandMessage = {
                             kind: "command",
@@ -362,8 +247,12 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
                             metadata: metadataFromProto(proto.metaData),
                             timestamp: Number(proto.timestamp),
                         };
-                        // Execute inbound command within its own UnitOfWork (AF5 parity)
-                        resultPayload = await unitOfWorkRunner(commandMessage.metadata, () => handler(commandMessage));
+                        // Through the LOCAL BUS, so the caller's unit-of-work policy runs.
+                        // AF parity is preserved: `CommandProcessingTask` runs the next
+                        // segment without re-running dispatch interceptors, and a `next`
+                        // that happens to carry `correlation` re-applies a pair of `??` seeds
+                        // that are already set.
+                        resultPayload = await next.dispatch(commandMessage);
                     }
                     catch (err) {
                         errorCode = AxonServerErrorCode.COMMAND_EXECUTION_ERROR;
@@ -372,7 +261,7 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
                 }
                 else {
                     errorCode = AxonServerErrorCode.NO_HANDLER_FOR_COMMAND;
-                    errorMsg = `No local handler for command "${commandName}"`;
+                    errorMsg = `No next handler for command "${commandName}"`;
                 }
                 // Send response back to Axon Server
                 outbound.send({
@@ -381,11 +270,14 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
                         requestIdentifier: proto.messageIdentifier,
                         errorCode,
                         errorMessage: errorCode
-                            ? { message: errorMsg, location: connection.config.componentName, details: [], errorCode }
-                            : undefined,
-                        payload: resultPayload !== undefined
-                            ? serializePayload("result", resultPayload)
+                            ? {
+                                message: errorMsg,
+                                location: connection.config.componentName,
+                                details: [],
+                                errorCode,
+                            }
                             : undefined,
+                        payload: resultPayload !== undefined ? serializePayload("result", resultPayload) : undefined,
                         metaData: {},
                         processingInstructions: [],
                     },
@@ -406,14 +298,20 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
                 return;
             if (String(err).includes("Connection dropped"))
                 return;
-            console.error("Distributed command bus: inbound stream error, attempting re-establishment via withRetry", err);
+            console.error("Axon Server command bus: inbound stream error, attempting re-establishment via withRetry", err);
             await reestablishStreamWithRetry().catch((retryErr) => {
-                console.error("Distributed command bus: reconnect retries exhausted", retryErr);
+                console.error("Axon Server command bus: reconnect retries exhausted", retryErr);
             });
         }
     }
-    const routing = {
-        async dispatch(message) {
+    return {
+        async dispatch(unstamped) {
+            // A transport is not a task: it has no unit of work, so it has no clock.
+            // A message that reaches the wire with no instant yet gets one from system
+            // time here — the envelope crosses a process boundary and must be fully
+            // formed. A locally-shortcut message is handed to `next` untouched
+            // instead, so the task that handles it supplies the instant.
+            const message = { ...unstamped, timestamp: unstamped.timestamp ?? Date.now() };
             const activity = shutdownLatch.registerActivity();
             try {
                 const commandName = qualifiedNameToString(message.name);
@@ -437,58 +335,56 @@ export function distributedCommandBus(connection, unitOfWorkRunner, shutdownLatc
             }
         },
         subscribe(commandName, handler) {
-            localSegment.set(commandName, handler);
+            subscribedNames.add(commandName);
+            next.subscribe(commandName, handler);
             ensureStreamStarted();
             // Subscription FIRST
-            outbound.send({
-                subscribe: {
-                    messageId: generateIdentifier(),
-                    command: commandName,
-                    componentName: connection.config.componentName,
-                    clientId: connection.config.clientId,
-                    loadFactor: commandLoadFactor ?? 100,
-                },
-                instructionId: generateIdentifier(),
-            });
+            sendSubscribe(commandName);
             // Permits AFTER subscription (Axon-specific ordering invariant)
             grantPermits();
         },
     };
-    // Interception OUTSIDE routing — see the note on this function.
-    const bus = interceptingCommandBus(routing);
-    bus.registerDispatchInterceptor(correlationDataDispatchInterceptor());
-    return bus;
 }
 // ---------------------------------------------------------------------------
-// Distributed Query Bus
+// Axon Server Query Bus
 // ---------------------------------------------------------------------------
 /**
- * A query bus backed by Axon Server.
+ * A query bus backed by Axon Server, over YOUR next bus.
  *
- * Same architecture as the distributed command bus:
- * - **Outbound dispatch**: Always through Axon Server.
- * - **Local segment**: Handlers registered here are stored locally and
- *   registered with Axon Server for inbound routing. Inbound queries
- *   are executed within a UnitOfWork.
+ * Same architecture as {@link axonServerCommandBus}: outbound dispatch goes
+ * through Axon Server, and a query the server routes here runs through `next`,
+ * so your unit-of-work policy applies to server-routed reads too. `subscribe`
+ * registers on `next` and announces the name to the server.
  *
- * Wrapped in {@link interceptingQueryBus} with
- * {@link correlationDataDispatchInterceptor}, matching AF4's
- * `AxonServerQueryBus`, which calls `dispatchInterceptors.intercept(...)` at the
- * top of `query`, `streamingQuery`, `scatterGather` and `subscriptionQuery`.
- * Because the wrap is outside, the `shortcutQueriesToLocalHandlers` branch in
- * `query()` gets identical lineage to the remote branch.
+ * The one asymmetry with commands is `shortcutQueriesToLocalHandlers` — Java
+ * has it for queries and not for commands, and so do we. When it is on and this
+ * node subscribed the name, `query()` goes straight to `next` and the caller's
+ * unit of work is passed through, so the next branch nests exactly as the
+ * in-process bus does.
+ *
+ * Correlation, if wanted, is `interceptingQueryBus(bus, correlation)` at the host,
+ * matching AF4's `AxonServerQueryBus`, which calls
+ * `dispatchInterceptors.intercept(...)` at the top of `query`, `streamingQuery`,
+ * `scatterGather` and `subscriptionQuery`. Because the wrap is outside, the
+ * shortcut branch gets identical correlation to the remote branch.
  *
  * KNOWN GAP: `subscriptionQuery` / `subscribeToUpdates` build their proto
  * straight from `message.metadata`, and `interceptingQueryBus` (in
- * `@kronos-ts/messaging`) forwards those two calls to the delegate without
- * running the dispatch chain. Closing that needs a messaging-package change.
+ * `@kronos-ts/core`) forwards those two calls to the delegate without
+ * running the dispatch chain. Closing that needs a core change.
  */
-export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch, serializer, flowControl, shortcutQueriesToLocalHandlers, queryTimeoutMs, resilience) {
-    const metadata = createAxonMetadata(connection.config);
-    const PERMITS = BigInt(flowControl?.permits ?? Number(DEFAULT_PERMITS));
-    const THRESHOLD = BigInt(flowControl?.refillThreshold ?? Number(DEFAULT_THRESHOLD));
+export function axonServerQueryBus(next, conn, options = {}) {
+    const { connection, serializer, metadata: axonMetadata, } = contextView(conn, options.context ?? conn.connection.config.context);
+    const shutdownLatch = conn.shutdown;
+    const resilience = options.resilience ?? conn.resilience;
+    const metadata = axonMetadata();
+    const PERMITS = BigInt(options.flowControl?.permits ?? Number(DEFAULT_PERMITS));
+    const THRESHOLD = BigInt(options.flowControl?.refillThreshold ?? Number(DEFAULT_THRESHOLD));
+    const shortcutQueriesToLocalHandlers = options.shortcutQueriesToLocalHandlers ?? false;
+    const queryTimeoutMs = options.timeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS;
     const { serializePayload, deserializePayload } = createPayloadHelpers(serializer);
-    const localSegment = new Map();
+    /** Query names announced to Axon Server; the handlers live on `next`. */
+    const subscribedNames = new Set();
     // Local subscription store — subscription queries opened by THIS instance.
     // Inbound updates from the server are offered into these via the Subscription RPC loop.
     const subscriptions = new Map();
@@ -515,8 +411,20 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
         });
         permits += PERMITS;
     }
+    function sendSubscribe(queryName) {
+        outbound.send({
+            subscribe: {
+                messageId: generateIdentifier(),
+                query: queryName,
+                resultName: "",
+                componentName: connection.config.componentName,
+                clientId: connection.config.clientId,
+            },
+            instructionId: generateIdentifier(),
+        });
+    }
     /**
-     * Re-establish the bidirectional stream and re-subscribe all handlers.
+     * Re-establish the bidirectional stream and re-announce all handlers.
      * Called on stream error or when the connection reconnects.
      *
      * ORDER (preserves Axon-specific invariant): subscriptions are
@@ -528,18 +436,8 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
         streamStarted = false;
         permits = 0n;
         ensureStreamStarted();
-        for (const queryName of localSegment.keys()) {
-            outbound.send({
-                subscribe: {
-                    messageId: generateIdentifier(),
-                    query: queryName,
-                    resultName: "",
-                    componentName: connection.config.componentName,
-                    clientId: connection.config.clientId,
-                },
-                instructionId: generateIdentifier(),
-            });
-        }
+        for (const queryName of subscribedNames)
+            sendSubscribe(queryName);
         grantQueryPermits();
     }
     async function reestablishStreamWithRetry() {
@@ -554,7 +452,7 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
     connection.onReconnect(() => {
         if (!shutdownLatch.shuttingDown && streamStarted) {
             reestablishStreamWithRetry().catch((err) => {
-                console.error("Distributed query bus: reconnect retries exhausted", err);
+                console.error("Axon Server query bus: reconnect retries exhausted", err);
             });
         }
     });
@@ -568,11 +466,10 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
             const queryName = proto.query;
             const payload = deserializePayload(proto.payload?.data, proto.payload?.type, proto.payload?.revision);
             handlerSubscriptions.set(subId, { queryName, payload });
-            const handler = localSegment.get(queryName);
             let resultPayload;
             let errorCode = "";
             let errorMsg = "";
-            if (handler) {
+            if (subscribedNames.has(queryName)) {
                 try {
                     const queryMessage = {
                         kind: "query",
@@ -582,9 +479,7 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                         metadata: metadataFromProto(proto.metaData ?? {}),
                         timestamp: Number(proto.timestamp),
                     };
-                    resultPayload = await unitOfWorkRunner(queryMessage.metadata, async () => {
-                        return handler(queryMessage);
-                    });
+                    resultPayload = await next.query(queryMessage);
                 }
                 catch (err) {
                     errorCode = AxonServerErrorCode.QUERY_EXECUTION_ERROR;
@@ -593,11 +488,9 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
             }
             else {
                 errorCode = AxonServerErrorCode.NO_HANDLER_FOR_QUERY;
-                errorMsg = `No local handler for query "${queryName}"`;
+                errorMsg = `No next handler for query "${queryName}"`;
             }
-            const responseSerialized = resultPayload !== undefined
-                ? serializePayload("result", resultPayload)
-                : undefined;
+            const responseSerialized = resultPayload !== undefined ? serializePayload("result", resultPayload) : undefined;
             outbound.send({
                 subscriptionQueryResponse: {
                     messageIdentifier: generateIdentifier(),
@@ -607,7 +500,12 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                         requestIdentifier: proto.messageIdentifier,
                         errorCode,
                         errorMessage: errorCode
-                            ? { message: errorMsg, location: connection.config.componentName, details: [], errorCode }
+                            ? {
+                                message: errorMsg,
+                                location: connection.config.componentName,
+                                details: [],
+                                errorCode,
+                            }
                             : undefined,
                         payload: responseSerialized,
                         metaData: {},
@@ -635,11 +533,10 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                 permits--;
                 const proto = message.query;
                 const queryName = proto.query;
-                const handler = localSegment.get(queryName);
                 let resultPayload;
                 let errorCode = "";
                 let errorMsg = "";
-                if (handler) {
+                if (subscribedNames.has(queryName)) {
                     try {
                         const queryMessage = {
                             kind: "query",
@@ -649,9 +546,9 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                             metadata: metadataFromProto(proto.metaData),
                             timestamp: Number(proto.timestamp),
                         };
-                        resultPayload = await unitOfWorkRunner(queryMessage.metadata, async () => {
-                            return handler(queryMessage);
-                        });
+                        // Through the LOCAL BUS: no unit of work is handed in, so `next`
+                        // opens one under whatever policy the caller gave it.
+                        resultPayload = await next.query(queryMessage);
                     }
                     catch (err) {
                         errorCode = AxonServerErrorCode.QUERY_EXECUTION_ERROR;
@@ -660,7 +557,7 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                 }
                 else {
                     errorCode = AxonServerErrorCode.NO_HANDLER_FOR_QUERY;
-                    errorMsg = `No local handler for query "${queryName}"`;
+                    errorMsg = `No next handler for query "${queryName}"`;
                 }
                 outbound.send({
                     queryResponse: {
@@ -668,11 +565,14 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                         requestIdentifier: proto.messageIdentifier,
                         errorCode,
                         errorMessage: errorCode
-                            ? { message: errorMsg, location: connection.config.componentName, details: [], errorCode }
-                            : undefined,
-                        payload: resultPayload !== undefined
-                            ? serializePayload("result", resultPayload)
+                            ? {
+                                message: errorMsg,
+                                location: connection.config.componentName,
+                                details: [],
+                                errorCode,
+                            }
                             : undefined,
+                        payload: resultPayload !== undefined ? serializePayload("result", resultPayload) : undefined,
                         metaData: {},
                         processingInstructions: [],
                     },
@@ -699,33 +599,38 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                 return;
             if (String(err).includes("Connection dropped"))
                 return;
-            console.error("Distributed query bus: inbound stream error, attempting re-establishment via withRetry", err);
+            console.error("Axon Server query bus: inbound stream error, attempting re-establishment via withRetry", err);
             await reestablishStreamWithRetry().catch((retryErr) => {
-                console.error("Distributed query bus: reconnect retries exhausted", retryErr);
+                console.error("Axon Server query bus: reconnect retries exhausted", retryErr);
             });
         }
     }
     const routing = {
-        async query(message) {
+        async query(unstamped, uow) {
             const activity = shutdownLatch.registerActivity();
             try {
-                const queryName = qualifiedNameToString(message.name);
-                // Local shortcut — handle locally if handler is co-located
-                if (shortcutQueriesToLocalHandlers) {
-                    const localHandler = localSegment.get(queryName);
-                    if (localHandler) {
-                        return unitOfWorkRunner(message.metadata, async () => {
-                            return localHandler(message);
-                        });
-                    }
+                const queryName = qualifiedNameToString(unstamped.name);
+                // Local shortcut — handle locally if a handler is co-located. The
+                // caller's unit of work is passed straight through, so `next` makes the
+                // nest-or-open decision on the HANDLE exactly as it does for an
+                // in-process read: a live unit of work handed in by `ctx.query` is
+                // reused so the consulting read shares the caller's transaction.
+                if (shortcutQueriesToLocalHandlers && subscribedNames.has(queryName)) {
+                    return next.query(unstamped, uow);
                 }
+                // A transport is not a task: it has no unit of work, so it has no clock.
+                // A message that reaches the wire with no instant yet gets one from system
+                // time here — the envelope crosses a process boundary and must be fully
+                // formed. A locally-shortcut message is handed to `next` untouched
+                // instead, so the task that handles it supplies the instant.
+                const message = { ...unstamped, timestamp: unstamped.timestamp ?? Date.now() };
                 const responseStream = connection.queries.query({
                     messageIdentifier: message.identifier,
                     query: queryName,
                     timestamp: BigInt(message.timestamp),
                     payload: serializePayload(queryName, message.payload),
                     metaData: metadataToProto(message.metadata),
-                    processingInstructions: defaultQueryInstructions(queryTimeoutMs ?? 3600000),
+                    processingInstructions: defaultQueryInstructions(queryTimeoutMs),
                     clientId: connection.config.clientId,
                     componentName: connection.config.componentName,
                 }, { metadata });
@@ -742,22 +647,15 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
             }
         },
         subscribe(queryName, handler) {
-            localSegment.set(queryName, handler);
+            subscribedNames.add(queryName);
+            next.subscribe(queryName, handler);
             ensureStreamStarted();
-            outbound.send({
-                subscribe: {
-                    messageId: generateIdentifier(),
-                    query: queryName,
-                    resultName: "",
-                    componentName: connection.config.componentName,
-                    clientId: connection.config.clientId,
-                },
-                instructionId: generateIdentifier(),
-            });
+            sendSubscribe(queryName);
             // Permits AFTER subscription (Axon-specific ordering invariant)
             grantQueryPermits();
         },
-        subscriptionQuery(message, bufferSize) {
+        subscriptionQuery(unstamped, bufferSize) {
+            const message = { ...unstamped, timestamp: unstamped.timestamp ?? Date.now() };
             const queryId = message.identifier;
             if (subscriptions.has(queryId)) {
                 throw new Error(`Subscription query already registered for identifier "${queryId}"`);
@@ -777,7 +675,7 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                         timestamp: BigInt(message.timestamp),
                         payload: serializePayload(queryName, message.payload),
                         metaData: metadataToProto(message.metadata),
-                        processingInstructions: defaultQueryInstructions(queryTimeoutMs ?? 3600000),
+                        processingInstructions: defaultQueryInstructions(queryTimeoutMs),
                         clientId: connection.config.clientId,
                         componentName: connection.config.componentName,
                     },
@@ -793,7 +691,7 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                         timestamp: BigInt(message.timestamp),
                         payload: serializePayload(queryName, message.payload),
                         metaData: metadataToProto(message.metadata),
-                        processingInstructions: defaultQueryInstructions(queryTimeoutMs ?? 3600000),
+                        processingInstructions: defaultQueryInstructions(queryTimeoutMs),
                         clientId: connection.config.clientId,
                         componentName: connection.config.componentName,
                     },
@@ -831,7 +729,8 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                             break;
                         }
                         else if (response.completeExceptionally) {
-                            handler.completeExceptionally(new Error(response.completeExceptionally.errorMessage?.message ?? "Subscription query failed"));
+                            handler.completeExceptionally(new Error(response.completeExceptionally.errorMessage?.message ??
+                                "Subscription query failed"));
                             break;
                         }
                     }
@@ -863,7 +762,8 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
                 },
             };
         },
-        subscribeToUpdates(message, bufferSize) {
+        subscribeToUpdates(unstamped, bufferSize) {
+            const message = { ...unstamped, timestamp: unstamped.timestamp ?? Date.now() };
             const queryId = message.identifier;
             if (subscriptions.has(queryId)) {
                 throw new Error(`Subscription query already registered for identifier "${queryId}"`);
@@ -957,8 +857,6 @@ export function distributedQueryBus(connection, unitOfWorkRunner, shutdownLatch,
             });
         },
     };
-    const bus = interceptingQueryBus(routing);
-    bus.registerDispatchInterceptor(correlationDataDispatchInterceptor());
-    return bus;
+    return routing;
 }
 //# sourceMappingURL=axon-server.js.map