@kronos-ts/axon-server 0.3.2 → 0.5.0

package/dist/resilience.js

@@ -0,0 +1,103 @@
+/**
+ * Connection resilience — PACKAGE-PRIVATE.
+ *
+ * Exponential backoff with full jitter, per-event attempt caps, terminal-error
+ * short-circuit, and a warn-then-continue health probe. Nothing here is
+ * exported from this package's barrel.
+ *
+ * It used to live in `@kronos-ts/core`, and it does not belong there. Core is
+ * only what cannot be a helper, and this is a helper by every test: it touches
+ * no core shape, no message, no unit of work — it is `setTimeout` and a loop
+ * over a function anybody could have written. Its only consumers were the
+ * transports and the pool, core's own `src/` never called it, and a helper
+ * lives with its users. Same reasoning that moved each persistence package's
+ * transaction glue out of core, applied one folder up.
+ *
+ * Each consuming package keeps its own copy, carrying only what it uses, so
+ * each can also state its own retry policy without negotiating with the others.
+ */
+const DEFAULTS = {
+    initialDelayMs: 100,
+    maxDelayMs: 30_000,
+    maxAttempts: 10,
+    multiplier: 2,
+    healthCheckThresholdMs: 5_000,
+};
+const ATTEMPTS_BY_EVENT = {
+    "initial-connect": 10,
+    "reconnect": 30,
+    "per-operation": 5,
+    "health-check": 3,
+};
+function resolveConfig(event, partial) {
+    return {
+        ...DEFAULTS,
+        maxAttempts: ATTEMPTS_BY_EVENT[event],
+        ...partial,
+    };
+}
+function fullJitterDelay(attempt, cfg) {
+    const exponential = Math.min(cfg.initialDelayMs * Math.pow(cfg.multiplier, attempt), cfg.maxDelayMs);
+    return Math.random() * exponential;
+}
+/**
+ * Run `fn` with exponential-backoff full-jitter retries.
+ *
+ * Resolves with the first successful result, or rejects with the last error
+ * after `maxAttempts` exhausted. If `isRetryable(err)` returns false on any
+ * attempt, the error is rethrown immediately (terminal error short-circuit).
+ *
+ * D-101: opts may carry caller-supplied resilience overrides — this is the
+ * per-extension knob path (`kronosDbConnection({ resilience: { ... } })`).
+ */
+export async function withRetry(fn, opts) {
+    const cfg = resolveConfig(opts.event, opts);
+    let lastErr;
+    for (let attempt = 0; attempt < cfg.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (cfg.isRetryable && !cfg.isRetryable(err))
+                throw err;
+            if (attempt === cfg.maxAttempts - 1)
+                break;
+            const delay = fullJitterDelay(attempt, cfg);
+            cfg.log?.(`[kronos:resilience] ${opts.event} attempt ${attempt + 1}/${cfg.maxAttempts} ` +
+                `failed; retrying in ${Math.round(delay)}ms — ${err?.message ?? String(err)}`);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Run a health-check probe with warn-then-continue semantics (D-100).
+ *
+ * Resolves WITHOUT throwing on success OR after `thresholdMs` elapses with
+ * the probe still pending — production loops should NEVER stall on a flaky
+ * health probe. Failures (rejection or threshold breach) emit a single warn
+ * via `log` and otherwise resolve normally.
+ */
+export async function healthCheck(fn, opts = {}) {
+    const threshold = opts.thresholdMs ?? DEFAULTS.healthCheckThresholdMs;
+    const log = opts.log ?? ((m) => console.warn(m));
+    let timer;
+    try {
+        await Promise.race([
+            fn(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("health-check threshold exceeded")), threshold);
+            }),
+        ]);
+    }
+    catch (err) {
+        log(`[kronos:resilience] health-check soft-failed (${err?.message ?? String(err)}); continuing`);
+        // warn-then-continue: do NOT rethrow.
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.js","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0BH,MAAM,QAAQ,GAAkD;IAC9D,cAAc,EAAE,GAAG;IACnB,UAAU,EAAE,MAAM;IAClB,WAAW,EAAE,EAAE;IACf,UAAU,EAAE,CAAC;IACb,sBAAsB,EAAE,KAAK;CAC9B,CAAA;AAED,MAAM,iBAAiB,GAA+B;IACpD,iBAAiB,EAAE,EAAE;IACrB,WAAW,EAAE,EAAE;IACf,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,CAAC;CAClB,CAAA;AAED,SAAS,aAAa,CACpB,KAAiB,EACjB,OAAmC;IAEnC,OAAO;QACL,GAAG,QAAQ;QACX,WAAW,EAAE,iBAAiB,CAAC,KAAK,CAAC;QACrC,GAAG,OAAO;KACX,CAAA;AACH,CAAC;AAED,SAAS,eAAe,CAAC,OAAe,EAAE,GAAqB;IAC7D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,GAAG,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,EACtD,GAAG,CAAC,UAAU,CACf,CAAA;IACD,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAA;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,IAAuD;IAEvD,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAC3C,IAAI,OAAgB,CAAA;IACpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAA;YACb,IAAI,GAAG,CAAC,WAAW,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAA;YACvD,IAAI,OAAO,KAAK,GAAG,CAAC,WAAW,GAAG,CAAC;gBAAE,MAAK;YAC1C,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;YAC3C,GAAG,CAAC,GAAG,EAAE,CACP,uBAAuB,IAAI,CAAC,KAAK,YAAY,OAAO,GAAG,CAAC,IAAI,GAAG,CAAC,WAAW,GAAG;gBAC5E,uBAAuB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QACrC,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CACvC,EAAE,CACL,CAAA;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAA;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAuB,EACvB,IAAI,GAA0D,EAAE;IAEhE,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,sBAAsB,CAAA;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IACxD,IAAI,KAAgD,CAAA;IACpD,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC;YACjB,EAAE,EAAE;YACJ,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;gBAC/B,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC,EAC1D,SAAS,CACV,CAAA;YACH,CAAC,CAAC;SACH,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CACD,iDACG,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CACvC,eAAe,CAChB,CAAA;QACD,sCAAsC;IACxC,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IAChC,CAAC;AACH,CAAC"}

package/dist/shutdown-latch.d.ts

@@ -10,7 +10,7 @@
  *
  * This is the TypeScript equivalent of AF5's ShutdownLatch pattern.
  */
-export interface ShutdownLatch {
+export type ShutdownLatch = {
     /**
      * Register an in-flight activity. Throws if shutdown is in progress.
      * Call `end()` on the returned handle when the activity completes.
@@ -26,11 +26,11 @@ export interface ShutdownLatch {
     readonly shuttingDown: boolean;
     /** Number of currently in-flight activities. */
     readonly activeCount: number;
-}
-export interface ActivityHandle {
+};
+export type ActivityHandle = {
     /** Mark this activity as complete. */
     end(): void;
-}
+};
 export declare class ShutdownInProgressError extends Error {
     constructor(message?: string);
 }

package/dist/shutdown-latch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown-latch.d.ts","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,gBAAgB,IAAI,cAAc,CAAA;IAElC;;;;OAIG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjC,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAE9B,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,GAAG,IAAI,IAAI,CAAA;CACZ;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,GAAE,MAA+B;CAIrD;AAED,wBAAgB,aAAa,IAAI,aAAa,CAmD7C"}
+{"version":3,"file":"shutdown-latch.d.ts","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,gBAAgB,IAAI,cAAc,CAAA;IAElC;;;;OAIG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjC,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAE9B,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,sCAAsC;IACtC,GAAG,IAAI,IAAI,CAAA;CACZ,CAAA;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,GAAE,MAA+B,EAGnD;CACF;AAED,wBAAgB,aAAa,IAAI,aAAa,CAmD7C"}

package/dist/shutdown-latch.js.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown-latch.js","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAsCA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,UAAkB,sBAAsB;QAClD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,IAAI,YAAY,GAAwB,IAAI,CAAA;IAE5C,SAAS,YAAY;QACnB,IAAI,YAAY,IAAI,WAAW,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;YACtD,YAAY,EAAE,CAAA;YACd,YAAY,GAAG,IAAI,CAAA;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,gBAAgB;YACd,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,uBAAuB,EAAE,CAAA;YACrC,CAAC;YAED,WAAW,EAAE,CAAA;YACb,IAAI,KAAK,GAAG,KAAK,CAAA;YAEjB,OAAO;gBACL,GAAG;oBACD,IAAI,KAAK;wBAAE,OAAM;oBACjB,KAAK,GAAG,IAAI,CAAA;oBACZ,WAAW,EAAE,CAAA;oBACb,YAAY,EAAE,CAAA;gBAChB,CAAC;aACF,CAAA;QACH,CAAC;QAED,gBAAgB;YACd,YAAY,GAAG,IAAI,CAAA;YAEnB,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;YAC1B,CAAC;YAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC7B,YAAY,GAAG,OAAO,CAAA;YACxB,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,IAAI,YAAY;YACd,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,WAAW;YACb,OAAO,WAAW,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"shutdown-latch.js","sourceRoot":"","sources":["../src/shutdown-latch.ts"],"names":[],"mappings":"AAsCA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAO,GAAW,sBAAsB;QAClD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,IAAI,YAAY,GAAwB,IAAI,CAAA;IAE5C,SAAS,YAAY;QACnB,IAAI,YAAY,IAAI,WAAW,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;YACtD,YAAY,EAAE,CAAA;YACd,YAAY,GAAG,IAAI,CAAA;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,gBAAgB;YACd,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,uBAAuB,EAAE,CAAA;YACrC,CAAC;YAED,WAAW,EAAE,CAAA;YACb,IAAI,KAAK,GAAG,KAAK,CAAA;YAEjB,OAAO;gBACL,GAAG;oBACD,IAAI,KAAK;wBAAE,OAAM;oBACjB,KAAK,GAAG,IAAI,CAAA;oBACZ,WAAW,EAAE,CAAA;oBACb,YAAY,EAAE,CAAA;gBAChB,CAAC;aACF,CAAA;QACH,CAAC;QAED,gBAAgB;YACd,YAAY,GAAG,IAAI,CAAA;YAEnB,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;YAC1B,CAAC;YAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC7B,YAAY,GAAG,OAAO,CAAA;YACxB,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,IAAI,YAAY;YACd,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,WAAW;YACb,OAAO,WAAW,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@kronos-ts/axon-server",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Axon Server extension for Kronos — event store and command bus over Axon Server.",
   "license": "Apache-2.0",
   "type": "module",
   "author": "Theo Emanuelsson",
-  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/extensions/axon-server#readme",
+  "homepage": "https://github.com/KronosDB/kronos-ts/tree/main/packages/axon-server#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/KronosDB/kronos-ts.git",
-    "directory": "packages/extensions/axon-server"
+    "directory": "packages/axon-server"
   },
   "bugs": {
     "url": "https://github.com/KronosDB/kronos-ts/issues"
@@ -33,7 +33,7 @@
     "!src/**/*.bench.ts"
   ],
   "scripts": {
-    "generate-proto": "grpc_tools_node_protoc --ts_proto_out=./src/generated --ts_proto_opt=outputServices=nice-grpc,outputServices=generic-definitions,useExactTypes=false,esModuleInterop=true --proto_path=./proto ./proto/*.proto",
+    "generate-proto": "grpc_tools_node_protoc --ts_proto_out=./src/generated --ts_proto_opt=outputServices=nice-grpc,outputServices=generic-definitions,useExactTypes=false,esModuleInterop=true --proto_path=./proto ./proto/*.proto && bun ../../scripts/interface-to-type/convert.ts ./src/generated",
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
@@ -49,11 +49,7 @@
     }
   },
   "dependencies": {
-    "@kronos-ts/common": "0.1.2",
-    "@kronos-ts/app": "0.6.2",
-    "@kronos-ts/eventsourcing": "0.4.2",
-    "@kronos-ts/messaging": "0.11.0",
-    "@kronos-ts/modelling": "0.3.2",
+    "@kronos-ts/core": "0.3.0",
     "@bufbuild/protobuf": "^2.3",
     "@grpc/grpc-js": "^1.12",
     "nice-grpc": "^2.1",

package/src/axon-server-event-store.ts

@@ -3,15 +3,15 @@ import {
   qualifiedNameFromString,
   type Tag,
   type Serializer,
-} from "@kronos-ts/common"
+} from "@kronos-ts/core"
 import type {
   EventCriteria,
   EventMessage,
   MessageStream,
   SequencedEvent,
   StreamingCondition,
-} from "@kronos-ts/messaging"
-import { messageStream } from "@kronos-ts/messaging"
+} from "@kronos-ts/core"
+import { messageStream, compileQuery } from "@kronos-ts/core"
 import type {
   EventStore,
   SourcingResult,
@@ -19,11 +19,12 @@ import type {
   AppendCondition,
   ConsistencyMarker,
   AppendTransaction,
-} from "@kronos-ts/eventsourcing"
-import type { TrackingToken } from "@kronos-ts/messaging"
-import { globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/messaging"
-import { markerAt, noMarker } from "@kronos-ts/eventsourcing"
-import type { AxonServerConnection } from "./connection.js"
+} from "@kronos-ts/core"
+import type { TrackingToken } from "@kronos-ts/core"
+import { globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/core"
+import { markerAt, noMarker } from "@kronos-ts/core"
+import type { AxonServerStoreSource } from "./connection.js"
+import { contextView } from "./context-view.js"
 import type {
   Criterion,
   TagsAndNamesCriterion,
@@ -32,7 +33,6 @@ import type {
   Event as ProtoEvent,
   SourceEventsResponse,
 } from "./generated/dcb.js"
-import { Metadata } from "nice-grpc"
 
 // ---------------------------------------------------------------------------
 // Criteria conversion — framework EventCriteria → proto Criterion[]
@@ -57,24 +57,26 @@ function tagFromProto(tag: ProtoTag): Tag {
 function criteriaToCriterions(criteria: EventCriteria): Criterion[] {
   switch (criteria.kind) {
     case "tags":
-      return [{
-        tagsAndNames: {
-          name: [],
-          tag: criteria.tags.map(tagToProto),
+      return [
+        {
+          tagsAndNames: {
+            name: [],
+            tag: criteria.tags.map(tagToProto),
+          },
         },
-      }]
+      ]
 
     case "type-restricted":
       // Inner must be tags or any-tag
-      const innerTags = criteria.inner.kind === "tags"
-        ? criteria.inner.tags.map(tagToProto)
-        : []
-      return [{
-        tagsAndNames: {
-          name: [...criteria.types],
-          tag: innerTags,
+      const innerTags = criteria.inner.kind === "tags" ? criteria.inner.tags.map(tagToProto) : []
+      return [
+        {
+          tagsAndNames: {
+            name: [...criteria.types],
+            tag: innerTags,
+          },
         },
-      }]
+      ]
 
     case "either":
       // Flatten all sub-criteria into a list of criterions (OR semantics)
@@ -111,9 +113,14 @@ function createEventConverters(serializer: Serializer) {
     },
 
     eventFromProto(protoEvent: ProtoEvent, tags: ProtoTag[]): EventMessage {
-      const payload = protoEvent.payload.length > 0
-        ? serializer.deserialize({ data: protoEvent.payload, type: protoEvent.name, revision: protoEvent.version })
-        : {}
+      const payload =
+        protoEvent.payload.length > 0
+          ? serializer.deserialize({
+              data: protoEvent.payload,
+              type: protoEvent.name,
+              revision: protoEvent.version,
+            })
+          : {}
 
       const metadata: Record<string, unknown> = {}
       for (const [k, v] of Object.entries(protoEvent.metadata)) {
@@ -139,27 +146,37 @@ function createEventConverters(serializer: Serializer) {
 // ---------------------------------------------------------------------------
 
 /**
- * Creates an EventStore implementation backed by Axon Server's DCB event store.
+ * An EventStore over Axon Server's DCB event store, in one context.
  *
  * This bridges the framework's EventStore interface to the gRPC
  * DcbEventStore service, handling conversion between framework types
  * and proto messages.
  *
+ * `context` is Axon Server's tenancy boundary and is a per-call header, so
+ * several contexts share the one channel `conn` holds — see `contextView`. The
+ * serializer is the connection's: one codec for everything this client puts on
+ * the wire.
+ *
  * The {@link open} method returns a persistent {@link MessageStream} backed by
  * a single gRPC Stream RPC call that stays open indefinitely, aligned with
  * Java's infinite {@code ResultStream}.
  */
-export function axonServerEventStore(connection: AxonServerConnection, serializer: Serializer): EventStore {
-  const { eventToProto, eventFromProto } = createEventConverters(serializer)
+/**
+ * Axon Server's way of saying "there is nothing at or after that position".
+ *
+ * Matched on the gRPC status code first — `OUT_OF_RANGE` is 11 — with the
+ * server's own message as a second, narrower gate, so an unrelated future
+ * OUT_OF_RANGE is not swallowed along with it.
+ */
+function isStartPastHead(err: unknown): boolean {
+  const code = (err as { code?: unknown }).code
+  const details = String((err as { details?: unknown }).details ?? "")
+  return code === 11 && details.includes("Start sequence cannot be larger than end sequence")
+}
 
-  function createAxonMetadata(): Metadata {
-    const axonMetadata = new Metadata()
-    axonMetadata.set("AxonIQ-Context", connection.config.context)
-    if (connection.config.token) {
-      axonMetadata.set("AxonIQ-Access-Token", connection.config.token)
-    }
-    return axonMetadata
-  }
+export function axonServerEventStore(conn: AxonServerStoreSource, context: string): EventStore {
+  const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context)
+  const { eventToProto, eventFromProto } = createEventConverters(serializer)
 
   // Push-based subscriber registry (EventBus.subscribe contract). Axon Server's
   // own distribution is the server-side Stream RPC (see open()); these in-process
@@ -177,31 +194,50 @@ export function axonServerEventStore(connection: AxonServerConnection, serialize
 
   return {
     async source(condition: SourcingCondition): Promise<SourcingResult> {
-      const criterions = criteriaToCriterions(condition.criteria)
+      const criterions = criteriaToCriterions(compileQuery(condition.query))
+      const start = condition.start ?? 0n
 
       const request = {
-        fromSequence: condition.start ?? 0n,
+        fromSequence: start,
         criterion: criterions,
       }
 
       const events: EventMessage[] = []
       let marker: ConsistencyMarker = noMarker()
 
-      const stream = connection.eventStore.source(request, { metadata: createAxonMetadata() })
-      for await (const response of stream) {
-        if (response.event) {
-          const taggedEvent = response.event
-          const protoEvent = taggedEvent.event
-          if (protoEvent) {
-            // DCB source/stream responses carry no tags — the server indexes
-            // them write-side but does not echo them back (SequencedEvent has
-            // only sequence + event). Reconstructed events get empty tags.
-            events.push(eventFromProto(protoEvent, []))
+      try {
+        const stream = connection.eventStore.source(request, { metadata: createAxonMetadata() })
+        for await (const response of stream) {
+          if (response.event) {
+            const taggedEvent = response.event
+            const protoEvent = taggedEvent.event
+            if (protoEvent) {
+              // DCB source/stream responses carry no tags — the server indexes
+              // them write-side but does not echo them back (SequencedEvent has
+              // only sequence + event). Reconstructed events get empty tags.
+              events.push(eventFromProto(protoEvent, []))
+            }
+          }
+          if (response.consistencyMarker !== undefined) {
+            marker = markerAt(response.consistencyMarker)
           }
         }
-        if (response.consistencyMarker !== undefined) {
-          marker = markerAt(response.consistencyMarker)
-        }
+      } catch (err) {
+        // READING PAST THE HEAD IS AN EMPTY ANSWER, NOT AN ERROR — and Axon
+        // Server disagrees, so this is where the two vocabularies are
+        // reconciled. `Source` fails OUT_OF_RANGE with "Start sequence cannot
+        // be larger than end sequence" whenever `fromSequence` is beyond the
+        // global head, which is the ORDINARY STEADY STATE of a snapshotted
+        // load: an entry written at the head means the very next read resumes
+        // at head + 1 and legitimately finds nothing.
+        //
+        // The marker is `start - 1`, and it is exact rather than conservative:
+        // the caller has already accounted for everything up to there (that is
+        // what asking to start later MEANS), and nothing can exist after it or
+        // the server would not have refused. So an append conditioned on this
+        // read is checked against precisely the range that was read.
+        if (!isStartPastHead(err)) throw err
+        return { events: [], marker: start > 0n ? markerAt(start - 1n) : noMarker() }
       }
 
       return { events, marker }
@@ -213,10 +249,12 @@ export function axonServerEventStore(connection: AxonServerConnection, serialize
     ): Promise<AppendTransaction> {
       const taggedEvents = newEvents.map(eventToProto)
       const request = {
-        condition: condition ? {
-          consistencyMarker: condition.marker.position,
-          criterion: criteriaToCriterions(condition.criteria),
-        } : undefined,
+        condition: condition
+          ? {
+              consistencyMarker: condition.marker.position,
+              criterion: criteriaToCriterions(compileQuery(condition.query)),
+            }
+          : undefined,
         event: taggedEvents,
       }
 
@@ -229,7 +267,9 @@ export function axonServerEventStore(connection: AxonServerConnection, serialize
           async function* requestStream() {
             yield request
           }
-          const response = await connection.eventStore.append(requestStream(), { metadata: createAxonMetadata() })
+          const response = await connection.eventStore.append(requestStream(), {
+            metadata: createAxonMetadata(),
+          })
           responseMarker = response.consistencyMarker
           await notifySubscribers(newEvents)
         },
@@ -252,7 +292,7 @@ export function axonServerEventStore(connection: AxonServerConnection, serialize
     },
 
     open(condition: StreamingCondition): MessageStream<SequencedEvent> {
-      const criterions = condition.criteria ? criteriaToCriterions(condition.criteria) : []
+      const criterions = condition.query ? criteriaToCriterions(compileQuery(condition.query)) : []
 
       const request = {
         fromSequence: condition.position,

package/src/axon-server-snapshotting-event-store.ts

@@ -0,0 +1,191 @@
+// ---------------------------------------------------------------------------
+// AXON SERVER SNAPSHOTS — the capability tier, served by `DcbSnapshotStore`.
+//
+// THE PROBE, AND WHAT IT SETTLED. Axon Server's public API defines both a
+// snapshot STORE service (`DcbSnapshotStore`: Add / Delete / List / GetLast)
+// and, on newer API drops, a fused `SnapshottedDcbEventStore.Source` whose
+// stream leads with the snapshot. Only the first of those is actually served:
+//
+//   axoniq/axonserver:2025.2.5   DcbSnapshotStore/GetLast   → answers
+//                                SnapshottedDcbEventStore/Source → UNIMPLEMENTED
+//   axoniq/axonserver:2026.0.4   same, both ways
+//
+// So there is no server-side fusion to call here — there is nothing on the
+// other end of the wire. The READ is therefore fused CLIENT-SIDE: `GetLast` for
+// the entry, then a source after its position, assembled into the one
+// `SourcingResult` a fold expects. Two round trips, the same answers, correct
+// today.
+//
+// When a server version does serve `SnapshottedDcbEventStore.Source`, the fused
+// call lands INSIDE this function — `source` stops making two calls and starts
+// making one — and no host changes a line, because the capability was never a
+// promise about round trips.
+// ---------------------------------------------------------------------------
+
+import type {
+  EventStore,
+  Snapshot,
+  SnapshotCapability,
+  SourcingCondition,
+  SourcingResult,
+} from "@kronos-ts/core"
+import type { Serializer } from "@kronos-ts/core"
+import { withoutSnapshotKey } from "@kronos-ts/core"
+import type { AxonServerStoreSource } from "./connection.js"
+import { contextView } from "./context-view.js"
+import type { Snapshot as ProtoSnapshot } from "./generated/dcb.js"
+
+// ---------------------------------------------------------------------------
+// Conversion — framework Snapshot ↔ proto Snapshot
+// ---------------------------------------------------------------------------
+
+const encoder = new TextEncoder()
+
+/**
+ * The proto message carries `name`, `version`, `timestamp` and a metadata map
+ * the narrowed seam has no equivalent for. `name` carries the cache key,
+ * `timestamp` is filled at write time for operators, and `version` stays EMPTY
+ * — snapshots have no versions, and inventing one to fill a proto field would
+ * be exactly the bookkeeping this design removed. The metadata map stays empty
+ * too: a cache entry carries no cargo.
+ */
+function createSnapshotConverters(serializer: Serializer) {
+  return {
+    snapshotToProto(name: string, snapshot: Snapshot): ProtoSnapshot {
+      const serialized = serializer.serialize(snapshot.state, name, "")
+      return {
+        name,
+        version: "",
+        payload: serialized.data,
+        timestamp: BigInt(Date.now()),
+        metadata: {},
+      }
+    },
+
+    snapshotFromProto(name: string, proto: ProtoSnapshot, position: bigint): Snapshot {
+      const state =
+        proto.payload.length > 0
+          ? serializer.deserialize({ data: proto.payload, type: name, revision: "" })
+          : {}
+
+      return { state, position }
+    },
+  }
+}
+
+function encodeKey(key: string): Uint8Array {
+  return encoder.encode(key)
+}
+
+// ---------------------------------------------------------------------------
+// Axon Server snapshot store
+// ---------------------------------------------------------------------------
+
+/**
+ * Add the snapshotting capability to an Axon Server-backed log.
+ *
+ * ```ts
+ * const eventStore = axonServerSnapshottingEventStore(
+ *   axonServerEventStore(axon, "default"),
+ *   axon,
+ *   "default",
+ * )
+ * ```
+ *
+ * ADDITIVE, NOT COLLAPSING. It returns `E & SnapshotCapability` — the store you
+ * passed in, plus the write — so capabilities stack in either order and nothing
+ * the inner store carried is laundered on the way through.
+ *
+ * `context` is a per-call header, so this shares the one channel `conn` holds
+ * with every other context — see `contextView`. Payloads go through the
+ * connection's serializer.
+ *
+ * LATEST-ONLY, over a service that is not. `DcbSnapshotStore` keeps a sequence
+ * of snapshots per key; the capability keeps one. `add` therefore sets
+ * `prune: true`, so writing an entry retires the ones before it, and `getLast`
+ * is the only read. That is the narrowing doing its job: the framework programs
+ * against the cache it needs, not against everything the backend happens to
+ * offer.
+ */
+export function axonServerSnapshottingEventStore<E extends EventStore>(
+  next: E,
+  conn: AxonServerStoreSource,
+  context: string,
+): E & SnapshotCapability {
+  const { connection, serializer, metadata: createAxonMetadata } = contextView(conn, context)
+  const { snapshotToProto, snapshotFromProto } = createSnapshotConverters(serializer)
+
+  /** The cached fold filed under `key`, or nothing — the first of the two calls. */
+  async function loadSnapshot(key: string): Promise<Snapshot | undefined> {
+    try {
+      const response = await connection.snapshotStore.getLast(
+        { key: encodeKey(key) },
+        { metadata: createAxonMetadata() },
+      )
+
+      if (!response.snapshot) {
+        return undefined
+      }
+
+      return snapshotFromProto(key, response.snapshot, response.sequence)
+    } catch (err) {
+      // Axon Server throws rather than answering empty when no snapshot
+      // exists — and a cache miss is not an error to anybody upstream.
+      if (
+        String(err).includes("No snapshot found") ||
+        String(err).includes("not found")
+      ) {
+        return undefined
+      }
+      throw err
+    }
+  }
+
+  return {
+    ...next,
+
+    async storeSnapshot(key: string, snapshot: Snapshot): Promise<void> {
+      await connection.snapshotStore.add(
+        {
+          key: encodeKey(key),
+          sequence: snapshot.position,
+          prune: true,
+          snapshot: snapshotToProto(key, snapshot),
+        },
+        { metadata: createAxonMetadata() },
+      )
+    },
+
+    /**
+     * THE CLIENT-SIDE FUSION. Two calls, assembled into the one result a fold
+     * expects — and the cache is NEVER LOAD-BEARING, so a miss or an outright
+     * throw from the snapshot service both fall through to a full read.
+     */
+    async source(condition: SourcingCondition): Promise<SourcingResult> {
+      const key = condition.snapshot
+      if (key === undefined) return next.source(condition)
+
+      // The strategy is CONSUMED here; the store below gets a plain condition.
+      const plain = withoutSnapshotKey(condition)
+
+      let snapshot: Snapshot | undefined
+      try {
+        snapshot = await loadSnapshot(key.key)
+      } catch {
+        // A cache you cannot reach is a cache miss. Loads stay correct; they
+        // just cost what they always cost.
+        return next.source(plain)
+      }
+      if (snapshot === undefined) return next.source(plain)
+
+      // Resume AFTER the position the snapshot already folded; a condition that
+      // independently asked to start later keeps its own floor.
+      const resumeFrom = snapshot.position + 1n
+      const start =
+        plain.start !== undefined && plain.start > resumeFrom ? plain.start : resumeFrom
+
+      const result = await next.source({ ...plain, start })
+      return { ...result, snapshot }
+    },
+  } as E & SnapshotCapability
+}