@cosmicdrift/kumiko-framework 0.143.0 → 0.144.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.143.0",
+  "version": "0.144.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.143.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.144.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/queries/event-store.ts

@@ -135,18 +135,35 @@ export type SaveSnapshotParams = {
   // Plain object — see SubsequentEventInsertParams on why pre-stringified
   // JSON double-encodes under Bun.SQL's ::jsonb binding.
   readonly state: Record<string, unknown>;
+  readonly snapshotVersion: number;
 };
 
+// kumiko_snapshots predates snapshot_version — idempotent heal for existing
+// installs, run from the same ensure path as table creation.
+export async function ensureSnapshotVersionColumn(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(
+    `ALTER TABLE "kumiko_snapshots" ADD COLUMN IF NOT EXISTS "snapshot_version" integer NOT NULL DEFAULT 1`,
+  );
+}
+
 export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void> {
   await asRawClient(db).unsafe(
     `INSERT INTO "kumiko_snapshots"
-       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state")
-     VALUES ($1, $2, $3, $4, $5::jsonb)
+       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state", "snapshot_version")
+     VALUES ($1, $2, $3, $4, $5::jsonb, $6)
      ON CONFLICT ("aggregate_id", "version") DO UPDATE SET
        "state" = $5::jsonb,
        "aggregate_type" = $3,
+       "snapshot_version" = $6,
        "created_at" = now()`,
-    [params.aggregateId, params.tenantId, params.aggregateType, params.version, params.state],
+    [
+      params.aggregateId,
+      params.tenantId,
+      params.aggregateType,
+      params.version,
+      params.state,
+      params.snapshotVersion,
+    ],
   );
 }
 

package/src/engine/__tests__/define-feature-crud.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+import { registerEntityCrud } from "../entity-handlers";
+import { createEntity, createTextField } from "../factories";
+
+const taskEntity = createEntity({
+  table: "crud_sugar_tasks",
+  fields: {
+    title: createTextField({ required: true }),
+  },
+  softDelete: true,
+});
+
+const access = {
+  write: { access: { roles: ["Admin"] } },
+  read: { access: { openToAll: true } },
+} as const;
+
+describe("r.crud", () => {
+  test("registers the same entity + handlers as registerEntityCrud", () => {
+    const viaCrud = defineFeature("crud-sugar", (r) => {
+      r.crud("task", taskEntity, access);
+    });
+    const viaHelper = defineFeature("crud-sugar", (r) => {
+      registerEntityCrud(r, "task", taskEntity, access);
+    });
+
+    expect(viaCrud.entities).toEqual(viaHelper.entities);
+    expect(Object.keys(viaCrud.writeHandlers)).toEqual(Object.keys(viaHelper.writeHandlers));
+    expect(Object.keys(viaCrud.queryHandlers)).toEqual(Object.keys(viaHelper.queryHandlers));
+    expect(Object.keys(viaCrud.writeHandlers)).toEqual([
+      "task:create",
+      "task:update",
+      "task:delete",
+      "task:restore",
+    ]);
+    expect(Object.keys(viaCrud.queryHandlers)).toEqual(["task:list", "task:detail"]);
+    expect(viaCrud.writeHandlers["task:create"]?.access).toEqual({ roles: ["Admin"] });
+    expect(viaCrud.queryHandlers["task:list"]?.access).toEqual({ openToAll: true });
+  });
+
+  test("returns an EntityRef like r.entity", () => {
+    defineFeature("crud-sugar", (r) => {
+      const ref = r.crud("task", taskEntity, access);
+      expect(ref).toEqual({ name: "task", table: "crud_sugar_tasks" });
+    });
+  });
+
+  test("verbs opt-out skips handlers", () => {
+    const feature = defineFeature("crud-sugar", (r) => {
+      r.crud("task", taskEntity, { ...access, verbs: { delete: false, restore: false } });
+    });
+    expect(Object.keys(feature.writeHandlers)).toEqual(["task:create", "task:update"]);
+  });
+});

package/src/engine/__tests__/event-migration-declarative.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+import type { DeclarativeEventMigration, EventUpcastCtx } from "../types";
+
+// Transforms under test are pure — ctx is never touched.
+const upcastCtx = {} as EventUpcastCtx;
+
+function compile(spec: DeclarativeEventMigration) {
+  const feature = defineFeature("billing", (r) => {
+    r.eventMigration("invoicePaid", 1, 2, spec);
+  });
+  const def = feature.eventMigrations["invoicePaid"]?.[0];
+  if (!def) throw new Error("migration not registered");
+  return (payload: unknown) => def.transform(payload, upcastCtx);
+}
+
+describe("declarative eventMigration", () => {
+  test("rename moves the value and drops the old key; missing source is a no-op", async () => {
+    const run = compile({ rename: { amount: "amountCents", missing: "other" } });
+    expect(await run({ amount: 5, currency: "EUR" })).toEqual({
+      amountCents: 5,
+      currency: "EUR",
+    });
+  });
+
+  test("default fills absent keys only — existing values win", async () => {
+    const run = compile({ default: { currency: "EUR", status: "open" } });
+    expect(await run({ currency: "CHF" })).toEqual({ currency: "CHF", status: "open" });
+  });
+
+  test("map runs after rename on the new key; absent keys are skipped", async () => {
+    const run = compile({
+      rename: { amount: "amountCents" },
+      map: { amountCents: (v) => Math.round(Number(v) * 100), missing: () => "never" },
+    });
+    expect(await run({ amount: 19.99 })).toEqual({ amountCents: 1999 });
+  });
+
+  test("non-object payload fails loud", () => {
+    const run = compile({ default: { a: 1 } });
+    expect(() => run("not-an-object")).toThrow(/object payload/);
+    expect(() => run([1, 2])).toThrow(/object payload/);
+  });
+
+  test("imperative function variant is stored untouched", () => {
+    const fn = (payload: unknown) => payload;
+    const feature = defineFeature("billing", (r) => {
+      r.eventMigration("invoicePaid", 1, 2, fn);
+    });
+    expect(feature.eventMigrations["invoicePaid"]?.[0]?.transform).toBe(fn);
+  });
+});

package/src/engine/define-feature.ts

@@ -3,6 +3,7 @@ import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
+import { type RegisterEntityCrudOptions, registerEntityCrud } from "./entity-handlers";
 import { isKebabSegment, QnTypes, qn, toKebab } from "./qualified-name";
 import type {
   AccessRule,
@@ -14,6 +15,7 @@ import type {
   ConfigKeyHandle,
   ConfigKeyType,
   ConfigSeedDef,
+  DeclarativeEventMigration,
   EntityDefinition,
   EntityProjectionExtension,
   EntityRef,
@@ -261,6 +263,15 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       return { name: entityName, table: definition.table ?? toTableName(entityName) };
     },
 
+    crud(
+      entityName: string,
+      definition: EntityDefinition,
+      options?: RegisterEntityCrudOptions,
+    ): EntityRef {
+      registerEntityCrud(registrar, entityName, definition, options);
+      return { name: entityName, table: definition.table ?? toTableName(entityName) };
+    },
+
     writeHandler<TName extends string, TSchema extends ZodType>(
       nameOrDef: string | WriteHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
@@ -568,7 +579,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       eventName: string,
       fromVersion: number,
       toVersion: number,
-      transform: EventUpcastFn,
+      transform: EventUpcastFn | DeclarativeEventMigration,
     ): void {
       if (toVersion !== fromVersion + 1) {
         throw new Error(
@@ -590,7 +601,9 @@ export function defineFeature<const TName extends string, TExports = undefined>(
             `a migration from v${fromVersion} is already registered. Each step may only be declared once.`,
         );
       }
-      list.push({ eventName: qualified, fromVersion, toVersion, transform });
+      const transformFn =
+        typeof transform === "function" ? transform : compileEventMigration(transform);
+      list.push({ eventName: qualified, fromVersion, toVersion, transform: transformFn });
       eventMigrations[eventName] = list;
     },
 
@@ -1039,3 +1052,28 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     ...(envSchema !== undefined && { envSchema }),
   };
 }
+
+// Compile the declarative {rename, default, map} migration spec into an
+// EventUpcastFn. Fixed order: rename → default → map.
+function compileEventMigration(spec: DeclarativeEventMigration): EventUpcastFn {
+  return (payload) => {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("Declarative event migration expects an object payload");
+    }
+    // @cast-boundary parse — payload is guarded as a plain object above
+    const next = { ...(payload as Record<string, unknown>) };
+    for (const [from, to] of Object.entries(spec.rename ?? {})) {
+      if (from in next) {
+        next[to] = next[from];
+        delete next[from];
+      }
+    }
+    for (const [key, value] of Object.entries(spec.default ?? {})) {
+      if (!(key in next)) next[key] = value;
+    }
+    for (const [key, fn] of Object.entries(spec.map ?? {})) {
+      if (key in next) next[key] = fn(next[key]);
+    }
+    return next;
+  };
+}

package/src/engine/types/feature.ts

@@ -7,6 +7,7 @@ import type { EntityTableMeta } from "../../db/entity-table-meta";
 type PgTable = unknown;
 
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "../define-handler";
+import type { RegisterEntityCrudOptions } from "../entity-handlers";
 import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
@@ -33,6 +34,7 @@ import type {
   ClaimKeyDefinition,
   ClaimKeyHandle,
   ClaimKeyType,
+  DeclarativeEventMigration,
   EntityRef,
   EventDef,
   EventMigrationDef,
@@ -424,6 +426,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     options?: { readonly table?: unknown },
   ): EntityRef;
 
+  // One-call CRUD for an event-sourced entity — delegates to registerEntityCrud():
+  // r.entity + create/update/delete/restore/list/detail handlers per verb flag.
+  // Access stays explicit — no openToAll default.
+  crud(name: string, definition: EntityDefinition, options?: RegisterEntityCrudOptions): EntityRef;
+
   writeHandler<TName extends string, TSchema extends ZodType>(
     def: WriteHandlerDefinition<TName, TSchema>,
   ): HandlerRef;
@@ -542,7 +549,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     eventName: string,
     fromVersion: number,
     toVersion: number,
-    transform: EventUpcastFn,
+    transform: EventUpcastFn | DeclarativeEventMigration,
   ): void;
 
   readsConfig(...qualifiedKeys: string[]): void;

package/src/engine/types/handlers.ts

@@ -431,7 +431,8 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // hold the state (e.g. just reduced the stream in a queryHandler, or
   // finished a write batch) pass it in alongside the version it reflects.
   // The framework handles storage + upsert semantics; the snapshot policy
-  // (every N events, every M minutes, on-demand) stays with the feature.
+  // (every N events, every M minutes, on-demand) stays with the feature —
+  // or pass { snapshotEvery } to loadAggregateWithSnapshot for the common case.
   // Snapshots are a perf optimisation — the event log remains the source
   // of truth.
   readonly snapshotAggregate: (args: {
@@ -439,6 +440,9 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly aggregateType: string;
     readonly version: number;
     readonly state: Record<string, unknown>;
+    // Reducer-shape generation stamped onto the snapshot (default 1) — see
+    // loadAggregateWithSnapshot's snapshotVersion option.
+    readonly snapshotVersion?: number;
   }) => Promise<void>;
 
   // Snapshot-aware rehydrate. Loads the latest snapshot (if any), runs the
@@ -454,6 +458,7 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     aggregateId: string,
     reducer: import("../../event-store").SnapshotReducer<TState>,
     initial: TState,
+    options?: Omit<import("../../event-store").LoadAggregateWithSnapshotOptions, "upcastEvent">,
   ) => Promise<import("../../event-store").LoadAggregateWithSnapshotResult<TState>>;
 
   // Read rows from a registered projection table, tenant-scoped to the
@@ -721,6 +726,17 @@ export type EventUpcastCtx = {
 
 export type EventUpcastFn = (payload: unknown, ctx: EventUpcastCtx) => unknown | Promise<unknown>;
 
+// Declarative single-step migration — common payload transforms without an
+// imperative function. Applied in fixed order: rename → default → map.
+export type DeclarativeEventMigration = {
+  // old key → new key; a missing source key is a no-op
+  readonly rename?: Readonly<Record<string, string>>;
+  // set only when the key is absent — never overwrites an existing value
+  readonly default?: Readonly<Record<string, unknown>>;
+  // per-key value transform; skipped when the key is absent
+  readonly map?: Readonly<Record<string, (value: unknown) => unknown>>;
+};
+
 export type EventMigrationDef = {
   // Qualified event name, matching r.defineEvent(...).name.
   readonly eventName: string;

package/src/engine/types/index.ts

@@ -133,6 +133,7 @@ export type {
   ClaimKeyHandle,
   ClaimKeyJsType,
   ClaimKeyType,
+  DeclarativeEventMigration,
   EntityRef,
   EventDef,
   EventMigrationDef,

package/src/event-store/__tests__/snapshot.integration.test.ts

@@ -242,3 +242,89 @@ describe("snapshot-store — loadAggregateWithSnapshot", () => {
     expect(archived.state.count).toBe(10);
   });
 });
+
+describe("snapshot-store — auto-snapshot policy (snapshotEvery)", () => {
+  test("first load persists a snapshot at the folded version; second load hits it", async () => {
+    const aggId = await seedAggregate(250);
+
+    const first = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100 },
+    );
+    expect(first.snapshotHit).toBe(false);
+    expect(first.version).toBe(250);
+    expect(first.state).toEqual(await loadFullState(aggId));
+
+    const stored = await loadLatestSnapshot<CounterState>(bun.db, aggId, tenant);
+    expect(stored?.version).toBe(250);
+    expect(stored?.snapshotVersion).toBe(1);
+    expect(stored?.aggregateType).toBe("counter");
+
+    const second = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100 },
+    );
+    expect(second.snapshotHit).toBe(true);
+    expect(second.state).toEqual(first.state);
+    expect(second.version).toBe(250);
+  });
+
+  test("fewer folded events than snapshotEvery → no snapshot written", async () => {
+    const aggId = await seedAggregate(10);
+    await loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+      snapshotEvery: 100,
+    });
+    expect(await loadLatestSnapshot(bun.db, aggId, tenant)).toBeNull();
+  });
+
+  test("snapshotVersion bump ignores the stored snapshot and restamps on auto-save", async () => {
+    const aggId = await seedAggregate(120);
+    await loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+      snapshotEvery: 100,
+    });
+
+    // Shape bump: the generation-1 snapshot must be ignored (full replay),
+    // and the auto-save restamps generation 2 at the same event version.
+    const bumped = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100, snapshotVersion: 2 },
+    );
+    expect(bumped.snapshotHit).toBe(false);
+    expect(bumped.state).toEqual(await loadFullState(aggId));
+
+    const restamped = await loadLatestSnapshot<CounterState>(bun.db, aggId, tenant);
+    expect(restamped?.snapshotVersion).toBe(2);
+    expect(restamped?.version).toBe(120);
+
+    const third = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100, snapshotVersion: 2 },
+    );
+    expect(third.snapshotHit).toBe(true);
+  });
+
+  test("invalid snapshotEvery fails loud", async () => {
+    const aggId = await seedAggregate(1);
+    await expect(
+      loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+        snapshotEvery: 0,
+      }),
+    ).rejects.toThrow(/snapshotEvery/);
+  });
+});

package/src/event-store/index.ts

@@ -41,6 +41,7 @@ export {
 export { toStoredEvent } from "./row-to-stored-event";
 export {
   createSnapshotsTable,
+  type LoadAggregateWithSnapshotOptions,
   type LoadAggregateWithSnapshotResult,
   loadAggregateWithSnapshot,
   loadLatestSnapshot,

package/src/event-store/snapshot.ts

@@ -12,7 +12,7 @@ import {
   text,
   uuid,
 } from "../db/dialect";
-import { upsertSnapshot } from "../db/queries/event-store";
+import { ensureSnapshotVersionColumn, upsertSnapshot } from "../db/queries/event-store";
 import { selectMany } from "../db/query";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
@@ -30,18 +30,17 @@ import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 //   3. loadEventsAfterVersion(aggregate, N) → only the delta
 //   4. reducer(snapshot, delta) → current state
 //
-// Write path: feature authors opt in via ctx.snapshotAggregate. Policy
-// (every N events, every M minutes, on-demand) is a feature-level decision
-// — the framework only offers the storage primitive.
+// Write path: manual via ctx.snapshotAggregate, or automatic via the
+// { snapshotEvery: N } load option — the read path persists a fresh
+// snapshot whenever it folded at least N delta events.
 //
-// Schema-migration policy: NO built-in snapshot versioning. A snapshot stores
-// the aggregate state in the reducer's current shape. When the reducer's
-// shape changes (added field, renamed property, moved compound), invalidate
-// the cache — DELETE from kumiko_snapshots WHERE aggregate_type = '...'.
-// The read path then falls back to full replay (which runs the upcaster
-// chain on events) until the next snapshotAggregate call. Cheaper than a
-// second migration mechanism; snapshots are a perf optimisation, not a
-// source of truth.
+// Schema-migration policy: explicit generations, no reducer hashing. A
+// snapshot stores the aggregate state in the reducer's current shape plus
+// a caller-declared snapshot_version. Bump { snapshotVersion } when the
+// reducer's shape changes — stored snapshots with another generation are
+// ignored (full replay through the upcaster chain on events) and restamped
+// on the next auto-save. Snapshots stay a perf optimisation, not a source
+// of truth.
 //
 // Upcaster interaction: the raw API (loadAggregateWithSnapshot below) does
 // NOT apply the upcaster chain on delta events — same layering as raw
@@ -63,6 +62,9 @@ export const snapshotsTable = pgTable(
     // returns events with version > this value.
     version: integer("version").notNull(),
     state: jsonb("state").$type<Record<string, unknown>>().notNull(),
+    // Reducer-shape generation — snapshots from another generation are
+    // ignored on load. See LoadAggregateWithSnapshotOptions.snapshotVersion.
+    snapshotVersion: integer("snapshot_version").notNull().default(sql`1`),
     createdAt: instant("created_at", { precision: 3 }).notNull().default(sql`now()`),
   },
   (t) => ({
@@ -76,7 +78,13 @@ export const snapshotsTable = pgTable(
 
 export async function createSnapshotsTable(db: DbConnection): Promise<void> {
   // skip: table already exists — idempotent boot + test-setup call
-  if (await tableExists(db, "public.kumiko_snapshots")) return;
+  if (await tableExists(db, "public.kumiko_snapshots")) {
+    // Installs that predate snapshot_version get healed by the same
+    // idempotent ensure that `kumiko schema apply` / test-setup already runs.
+    await ensureSnapshotVersionColumn(db);
+    // skip: table already ensured — only the column heal above was needed
+    return;
+  }
   await unsafePushTables(db, { kumikoSnapshots: snapshotsTable });
 }
 
@@ -86,6 +94,7 @@ export type Snapshot<TState extends Record<string, unknown> = Record<string, unk
   readonly aggregateType: string;
   readonly version: number;
   readonly state: TState;
+  readonly snapshotVersion: number;
   readonly createdAt: Temporal.Instant;
 };
 
@@ -95,6 +104,8 @@ export type SaveSnapshotArgs = {
   readonly aggregateType: string;
   readonly version: number;
   readonly state: Record<string, unknown>;
+  // Reducer-shape generation (default 1) — see LoadAggregateWithSnapshotOptions.
+  readonly snapshotVersion?: number;
 };
 
 // Upsert-style save so re-snapshotting the same (aggregateId, version) is
@@ -108,6 +119,7 @@ export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promis
     aggregateType: args.aggregateType,
     version: args.version,
     state: args.state,
+    snapshotVersion: args.snapshotVersion ?? 1,
   });
 }
 
@@ -123,6 +135,7 @@ export async function loadLatestSnapshot<
     aggregateType: string;
     version: number;
     state: unknown;
+    snapshotVersion: number;
     createdAt: Temporal.Instant;
   };
   const rows = await selectMany<SnapRow>(
@@ -139,6 +152,7 @@ export async function loadLatestSnapshot<
     aggregateType: row.aggregateType,
     version: row.version,
     state: row.state as TState, // @cast-boundary engine-payload
+    snapshotVersion: row.snapshotVersion,
     createdAt: row.createdAt,
   };
 }
@@ -167,6 +181,15 @@ export type LoadAggregateWithSnapshotOptions = {
   // r.eventMigration so feature code always sees current-version payloads.
   // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
   readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
+  // Auto-snapshot policy: when the fold applied at least this many delta
+  // events, persist a fresh snapshot at the folded version (best-effort —
+  // a failed save never fails the load). Omit to keep snapshotting manual.
+  readonly snapshotEvery?: number;
+  // Reducer-shape generation stamped onto saved snapshots (default 1). A
+  // stored snapshot with a different generation is ignored — full replay
+  // through the upcaster chain — and restamped on the next auto-save. Bump
+  // whenever the reducer's state shape changes.
+  readonly snapshotVersion?: number;
 };
 
 // Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
@@ -192,7 +215,17 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
       return { state: initial, version: 0, snapshotHit: false };
     }
   }
-  const snapshot = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
+  const shapeVersion = options?.snapshotVersion ?? 1;
+  if (
+    options?.snapshotEvery !== undefined &&
+    (!Number.isInteger(options.snapshotEvery) || options.snapshotEvery < 1)
+  ) {
+    throw new Error(
+      `loadAggregateWithSnapshot: snapshotEvery must be an integer >= 1, got ${String(options.snapshotEvery)}`,
+    );
+  }
+  const stored = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
+  const snapshot = stored && stored.snapshotVersion === shapeVersion ? stored : null;
   const baseState = snapshot ? snapshot.state : initial;
   const afterVersion = snapshot ? snapshot.version : 0;
   const delta = await loadEventsAfterVersion(db, aggregateId, tenantId, afterVersion);
@@ -204,6 +237,20 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
   }
   const lastDelta = delta[delta.length - 1];
   const latestVersion = lastDelta ? lastDelta.version : afterVersion;
+  if (options?.snapshotEvery !== undefined && lastDelta && delta.length >= options.snapshotEvery) {
+    try {
+      await saveSnapshot(db, {
+        aggregateId,
+        tenantId,
+        aggregateType: lastDelta.aggregateType,
+        version: latestVersion,
+        state,
+        snapshotVersion: shapeVersion,
+      });
+    } catch {
+      // Best-effort cache write — losing it only costs the next load a replay.
+    }
+  }
   return {
     state,
     version: latestVersion,

package/src/pipeline/dispatcher.ts

@@ -61,6 +61,7 @@ import {
   type StoredEvent,
 } from "../event-store/event-store";
 import {
+  type LoadAggregateWithSnapshotOptions,
   type LoadAggregateWithSnapshotResult,
   loadAggregateWithSnapshot,
   type SnapshotReducer,
@@ -451,6 +452,7 @@ export function createDispatcher(
         readonly aggregateType: string;
         readonly version: number;
         readonly state: Record<string, unknown>;
+        readonly snapshotVersion?: number;
       }): Promise<void> => {
         const dbSource = resolveDbSource(tx);
         if (!dbSource) {
@@ -464,12 +466,14 @@ export function createDispatcher(
           aggregateType: snapshotArgs.aggregateType,
           version: snapshotArgs.version,
           state: snapshotArgs.state,
+          snapshotVersion: snapshotArgs.snapshotVersion,
         });
       },
       loadAggregateWithSnapshot: async <TState extends Record<string, unknown>>(
         aggregateId: string,
         reducer: SnapshotReducer<TState>,
         initial: TState,
+        loadOptions?: Omit<LoadAggregateWithSnapshotOptions, "upcastEvent">,
       ): Promise<LoadAggregateWithSnapshotResult<TState>> => {
         const dbSource = resolveDbSource(tx);
         if (!dbSource) {
@@ -490,7 +494,10 @@ export function createDispatcher(
           user.tenantId,
           reducer,
           initial,
-          { upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx) }, // @wrapper-known semantic-alias
+          {
+            ...loadOptions,
+            upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx), // @wrapper-known semantic-alias
+          },
         );
       },
       queryProjection: async <T = Record<string, unknown>>(