@reventlessdev/reventless-core 3.0.0-alpha.136 → 3.0.0-alpha.138

package/src/components/Aggregate/Aggregate_Callback.res

@@ -7,6 +7,11 @@ module type Ops = {
 module type T = {
   module Spec: Reventless.Aggregate.Spec
   let handleCommands: CommandTopic.commandsHandler<Message.command'<Spec.Id.t, Spec.command>>
+
+  /** Flushes this aggregate's in-process replay cache. The cache is a pure read
+      optimization (the OCC append fences staleness), so this is only needed for
+      test isolation — production code never has to call it. */
+  let resetCache: unit => unit
 }
 
 module Make = (
@@ -95,6 +100,176 @@ module Make = (
 
   let maxConflictRetries = 3
 
+  // In-process replay cache (per warm Lambda instance, per aggregate — the
+  // functor instance owns the cache, so the event log is implicit and the key
+  // is just the aggregate id). Holds the `(state, sequenceNr)` the previous
+  // command batch for that id left behind.
+  //
+  // On a hit, `replayProcessAppend` skips the event-log replay entirely and
+  // decides on the cached state; after a successful append it stores the
+  // already-folded post-append state (aggregates have no consumed-vs-produced
+  // event split, so `evolve` over the appended events IS the replay result).
+  // Correctness rests on the append's optimistic-concurrency check: a stale
+  // cached state only changes the *decision*, and a stale sequenceNr conflicts
+  // at append time → the conflict branch invalidates the entry and the retry
+  // replays cold. Mirrors the StateChangeSlice decision-model cache, including
+  // the fixed capacity (a per-aggregate knob is a future refinement — see
+  // docs/plans/aggregate-snapshotting.md).
+  let replayCacheCapacity = 100
+  let replayCache: Lru.t<string, (Behavior.state, int)> = Lru.make(
+    ~capacity=replayCacheCapacity,
+  )
+
+  let resetCache = () => replayCache->Lru.clear
+
+  // Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+  // `None` (the default) keeps full replay; `Some({interval, stateSchema})`
+  // seeds cold replays from the latest persisted snapshot and writes a fresh
+  // one every `interval` events. Snapshots are a read optimization only — the
+  // OCC append remains the sole consistency primitive, so a missing, drifted,
+  // or corrupt snapshot degrades silently to full replay.
+  let snapshotConfig = Behavior.snapshot
+
+  // Structural hash of the state schema, computed once. Stored on every written
+  // snapshot and compared on read: a snapshot whose hash differs from the
+  // current schema (a state-shape change since it was written) is ignored and
+  // overwritten at the next boundary, so a redeploy that changes `type state`
+  // can't decode stale bytes into the wrong shape. NOTE: this catches *shape*
+  // drift only — a semantics-only `evolve` change with an unchanged state type
+  // is invisible (see the plan's open question; for alpha, wipe snapshots on
+  // such changes, consistent with the alpha-wipe-over-migration convention).
+  let stateSchemaHash = switch snapshotConfig {
+  | Some({stateSchema}) =>
+    HashObj.hashDict(
+      ~dict=Dict.fromArray([("state", SchemaWalker.describeSchema(stateSchema->Obj.magic))]),
+      ~options={algorithm: SHA256},
+    )
+  | None => ""
+  }
+
+  // State ⇄ JSON via the configured stateSchema. Both swallow sury failures to
+  // `None` — an unserializable state just skips the snapshot write, and an
+  // undecodable snapshot falls back to full replay; neither can fail a command.
+  let encodeState = (state: Behavior.state): option<JSON.t> =>
+    switch snapshotConfig {
+    | Some({stateSchema}) =>
+      switch state->S.reverseConvertToJsonOrThrow(stateSchema) {
+      | json => Some(json)
+      | exception _ => None
+      }
+    | None => None
+    }
+
+  let decodeState = (json: JSON.t): option<Behavior.state> =>
+    switch snapshotConfig {
+    | Some({stateSchema}) =>
+      switch json->S.parseJsonOrThrow(stateSchema) {
+      | state => Some(state)
+      | exception _ => None
+      }
+    | None => None
+    }
+
+  // Cold read (in-process cache miss): when snapshots are enabled, seed from the
+  // latest persisted snapshot (hash-gated) and replay only the events after it;
+  // otherwise replay full history from seq 0. Returns `(state, sequenceNr)` where
+  // sequenceNr is the total event count (the OCC condition for the next append).
+  let coldReadState = id => {
+    let idStr = id->Spec.Id.toString
+    let seedEffect = switch snapshotConfig {
+    | None => Effect.succeed((Behavior.initialState, 0))
+    | Some(_) =>
+      Effect.promise(() => Ops.eventLog.latestSnapshot(id))
+      ->Effect.map(snapResult =>
+        switch snapResult {
+        | Ok(Some(snap)) if snap.EventLog.schemaHash == stateSchemaHash =>
+          switch decodeState(snap.state) {
+          | Some(state) => (state, snap.seqNr)
+          | None =>
+            EffectLogger.logWarn(
+              ~comp,
+              `snapshot ignored (undecodable): id=${idStr}, seq=${snap.seqNr->Int.toString} — full replay`,
+            )->Effect.runSync
+            (Behavior.initialState, 0)
+          }
+        | Ok(Some(snap)) =>
+          EffectLogger.logWarn(
+            ~comp,
+            `snapshot ignored (schema drift): id=${idStr}, seq=${snap.EventLog.seqNr->Int.toString} — full replay`,
+          )->Effect.runSync
+          (Behavior.initialState, 0)
+        | Ok(None) => (Behavior.initialState, 0)
+        | Error(msg) =>
+          EffectLogger.logWarn(
+            ~comp,
+            `snapshot read failed (ignored): id=${idStr}: ${msg} — full replay`,
+          )->Effect.runSync
+          (Behavior.initialState, 0)
+        }
+      )
+    }
+    seedEffect->Effect.flatMap(((seedState, seedSeq)) =>
+      Ops.eventLog.replayStream(id, ~fromSeq=seedSeq)
+      ->Stream.runFold((seedState, seedSeq), ((st, n), ev) => (Behavior.evolve(st, ev), n + 1))
+      ->Effect.tap(((_, n)) => {
+        let detail =
+          seedSeq > 0
+            ? `(snapshot@${seedSeq->Int.toString}, ${(n - seedSeq)->Int.toString} delta event(s))`
+            : `${n->Int.toString} event(s)`
+        EffectLogger.logInfo(~comp, `replay: id=${idStr}, ${detail}`)
+      })
+    )
+  }
+
+  // Fire-and-forget snapshot write — never awaited, never fails the command. A
+  // failed write just means the next cold replay reads a longer delta.
+  let fireSnapshotWrite = (id, idStr, snap: EventLog.snapshot) => {
+    let _ =
+      Ops.eventLog.writeSnapshot(id, snap)
+      ->Promise.then(result => {
+        switch result {
+        | Ok() =>
+          EffectLogger.logDebug(
+            ~comp,
+            `snapshot written: id=${idStr}, seq=${snap.seqNr->Int.toString}`,
+          )->Effect.runSync
+        | Error(msg) =>
+          EffectLogger.logWarn(
+            ~comp,
+            `snapshot write failed (ignored): id=${idStr}: ${msg}`,
+          )->Effect.runSync
+        }
+        Promise.resolve()
+      })
+      ->Promise.catch(err => {
+        let msg = err->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown")
+        EffectLogger.logWarn(
+          ~comp,
+          `snapshot write threw (ignored): id=${idStr}: ${msg}`,
+        )->Effect.runSync
+        Promise.resolve()
+      })
+  }
+
+  // Write a snapshot when this append crossed an `interval` boundary (a multiple
+  // of interval lies in (oldSeq, newSeq]). Keep-one: on a batch that crosses
+  // several boundaries we still write just the latest state at newSeq. No-op
+  // when snapshots are disabled or the state can't be serialized.
+  let maybeWriteSnapshot = (id, idStr, ~oldSeq, ~newSeq, state) =>
+    switch snapshotConfig {
+    | Some({interval}) if interval > 0 && newSeq / interval > oldSeq / interval =>
+      switch encodeState(state) {
+      | Some(stateJson) =>
+        fireSnapshotWrite(id, idStr, {EventLog.seqNr: newSeq, state: stateJson, schemaHash: stateSchemaHash})
+      | None =>
+        EffectLogger.logWarn(
+          ~comp,
+          `snapshot skipped (state not serializable): id=${idStr}, seq=${newSeq->Int.toString}`,
+        )->Effect.runSync
+      }
+    | _ => ()
+    }
+
   // Reports per-command outcomes on the inline side-channels and produces the
   // per-reference Ok/Error array consumed by SQS-style consumers. Domain rejections
   // are always Ok(reference) — SQS deletes the message because retry would not help —
@@ -133,13 +308,22 @@ module Make = (
   ) => {
     let idStr = id->Spec.Id.toString
 
-    Ops.eventLog.replayStream(id)
-    ->Stream.runFold((Behavior.initialState, 0), ((st, n), ev) => (Behavior.evolve(st, ev), n + 1))
-    ->Effect.tap(((_, n)) =>
-      EffectLogger.logInfo(~comp, `replay: id=${idStr}, ${n->Int.toString} event(s)`)
-    )
+    // Warm path: seed from the in-process cache and skip both the snapshot read
+    // and the event-log replay; the OCC append below fences any staleness. Cold
+    // path (`coldReadState`): seed from the persisted snapshot when enabled, else
+    // full replay.
+    let readState = switch replayCache->Lru.get(idStr) {
+    | Some((state, seqNr)) =>
+      EffectLogger.logInfo(
+        ~comp,
+        `replay skipped (cached): id=${idStr}, seq=${seqNr->Int.toString}`,
+      )->Effect.map(_ => (state, seqNr))
+    | None => coldReadState(id)
+    }
+
+    readState
     ->Effect.flatMap(((initialState, sequenceNr)) => {
-      let (_finalState, outcomes) =
+      let (finalState, outcomes) =
         topicItemsForId->Array.reduce((initialState, []), processCommand)
 
       let eventsToAppend =
@@ -154,6 +338,9 @@ module Make = (
 
       switch eventsToAppend {
       | [] =>
+        // Nothing appended, but the read snapshot is valid — keep it warm for
+        // the next command (also refreshes recency on a cache hit).
+        replayCache->Lru.put(idStr, (initialState, sequenceNr))
         let perRef = reportFinalOutcomes(
           outcomes,
           ~entityId=idStr,
@@ -178,6 +365,13 @@ module Make = (
           appendResult =>
             switch appendResult {
             | Ok(_) =>
+              // The post-decide fold state IS the post-append replay result;
+              // cache it so the next command for this id skips the replay.
+              let newSeq = sequenceNr + generatedEvents'->Array.length
+              replayCache->Lru.put(idStr, (finalState, newSeq))
+              // Persist a snapshot if this append crossed an interval boundary
+              // (fire-and-forget — never blocks or fails the command).
+              maybeWriteSnapshot(id, idStr, ~oldSeq=sequenceNr, ~newSeq, finalState)
               let perRef = reportFinalOutcomes(
                 outcomes,
                 ~entityId=idStr,
@@ -186,6 +380,9 @@ module Make = (
               )
               EffectLogger.logInfo(~comp, `append: id=${idStr}`)->Effect.map(_ => Ok(perRef))
             | Error(EventLog.Conflict) =>
+              // Another writer advanced the stream past our (possibly cached)
+              // sequenceNr — drop the entry so the retry replays cold.
+              replayCache->Lru.invalidate(idStr)
               // Signal the outer replay+re-decide retry loop (which matches
               // Error(_)); the string is an internal marker, no longer a
               // cross-component substring sentinel.
@@ -193,6 +390,10 @@ module Make = (
                 _ => Error("conflict"),
               )
             | Error(EventLog.StorageFailure(msg)) =>
+              // Appends are atomic, so the read snapshot is likely still valid —
+              // but a storage error means we can't be sure what committed;
+              // drop the entry so the next attempt reads authoritative state.
+              replayCache->Lru.invalidate(idStr)
               let perRef = reportFinalOutcomes(
                 outcomes,
                 ~entityId=idStr,

package/src/components/Aggregate/Aggregate_Callback.res.mjs

@@ -1,12 +1,20 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as S from "sury/src/S.res.mjs";
+import HashObject from "hash-object";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
+import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Lru$ReventlessCore from "../../util/Lru.res.mjs";
 import * as Message$ReventlessCore from "../../Message.res.mjs";
 import * as LogFormat$ReventlessCore from "../../util/LogFormat.res.mjs";
 import * as EffectLogger$ReventlessCore from "../../util/EffectLogger.res.mjs";
+import * as SchemaWalker$ReventlessCore from "../../plugin/component/SchemaWalker.res.mjs";
 import * as CommandTopic_Helpers$ReventlessCore from "../CommandTopic/CommandTopic_Helpers.res.mjs";
 
 function Make(Spec) {
@@ -64,6 +72,127 @@ function Make(Spec) {
           ]])
       ];
     };
+    let replayCache = Lru$ReventlessCore.make(100);
+    let resetCache = () => Lru$ReventlessCore.clear(replayCache);
+    let snapshotConfig = Behavior.snapshot;
+    let stateSchemaHash = snapshotConfig !== undefined ? HashObject(Object.fromEntries([[
+          "state",
+          SchemaWalker$ReventlessCore.describeSchema(snapshotConfig.stateSchema)
+        ]]), {
+        algorithm: "sha256"
+      }) : "";
+    let encodeState = state => {
+      if (snapshotConfig === undefined) {
+        return;
+      }
+      let json;
+      try {
+        json = S.reverseConvertToJsonOrThrow(state, snapshotConfig.stateSchema);
+      } catch (exn) {
+        return;
+      }
+      return json;
+    };
+    let decodeState = json => {
+      if (snapshotConfig === undefined) {
+        return;
+      }
+      let state;
+      try {
+        state = S.parseJsonOrThrow(json, snapshotConfig.stateSchema);
+      } catch (exn) {
+        return;
+      }
+      return Primitive_option.some(state);
+    };
+    let coldReadState = id => {
+      let idStr = Spec.Id.toString(id);
+      let seedEffect = snapshotConfig !== undefined ? Effect.map(Effect.promise(() => Ops.eventLog.latestSnapshot(id)), snapResult => {
+          if (snapResult.TAG === "Ok") {
+            let snap = snapResult._0;
+            if (snap === undefined) {
+              return [
+                Behavior.initialState,
+                0
+              ];
+            }
+            if (snap.schemaHash === stateSchemaHash) {
+              let state = decodeState(snap.state);
+              if (state !== undefined) {
+                return [
+                  Primitive_option.valFromOption(state),
+                  snap.seqNr
+                ];
+              } else {
+                Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot ignored (undecodable): id=` + idStr + `, seq=` + snap.seqNr.toString() + ` — full replay`));
+                return [
+                  Behavior.initialState,
+                  0
+                ];
+              }
+            }
+            Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot ignored (schema drift): id=` + idStr + `, seq=` + snap.seqNr.toString() + ` — full replay`));
+            return [
+              Behavior.initialState,
+              0
+            ];
+          }
+          Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot read failed (ignored): id=` + idStr + `: ` + snapResult._0 + ` — full replay`));
+          return [
+            Behavior.initialState,
+            0
+          ];
+        }) : Effect.succeed([
+          Behavior.initialState,
+          0
+        ]);
+      return Effect.flatMap(seedEffect, param => {
+        let seedSeq = param[1];
+        return Effect.tap(Stream.runFold(Ops.eventLog.replayStream(id, seedSeq), [
+          param[0],
+          seedSeq
+        ], (param, ev) => [
+          Behavior.evolve(param[0], ev),
+          param[1] + 1 | 0
+        ]), param => {
+          let n = param[1];
+          let detail = seedSeq > 0 ? `(snapshot@` + seedSeq.toString() + `, ` + (n - seedSeq | 0).toString() + ` delta event(s))` : n.toString() + ` event(s)`;
+          return EffectLogger$ReventlessCore.logInfo(comp, undefined, `replay: id=` + idStr + `, ` + detail);
+        });
+      });
+    };
+    let maybeWriteSnapshot = (id, idStr, oldSeq, newSeq, state) => {
+      if (snapshotConfig === undefined) {
+        return;
+      }
+      let interval = snapshotConfig.interval;
+      if (!(interval > 0 && Primitive_int.div(newSeq, interval) > Primitive_int.div(oldSeq, interval))) {
+        return;
+      }
+      let stateJson = encodeState(state);
+      if (stateJson !== undefined) {
+        let snap = {
+          seqNr: newSeq,
+          state: stateJson,
+          schemaHash: stateSchemaHash
+        };
+        Stdlib_Promise.$$catch(Ops.eventLog.writeSnapshot(id, snap).then(result => {
+          if (result.TAG === "Ok") {
+            Effect.runSync(EffectLogger$ReventlessCore.logDebug(comp, undefined, `snapshot written: id=` + idStr + `, seq=` + snap.seqNr.toString()));
+          } else {
+            Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot write failed (ignored): id=` + idStr + `: ` + result._0));
+          }
+          return Promise.resolve();
+        }), err => {
+          let msg = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(err), Stdlib_JsExn.message), "unknown");
+          Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot write threw (ignored): id=` + idStr + `: ` + msg));
+          return Promise.resolve();
+        });
+        return;
+      } else {
+        return Effect.runSync(EffectLogger$ReventlessCore.logWarn(comp, undefined, `snapshot skipped (state not serializable): id=` + idStr + `, seq=` + newSeq.toString()));
+      }
+    };
     let reportFinalOutcomes = (outcomes, entityId, appendSucceeded, appendedEventCount, appendErrorDetailOpt) => {
       let appendErrorDetail = appendErrorDetailOpt !== undefined ? appendErrorDetailOpt : "";
       return outcomes.map(param => {
@@ -102,19 +231,27 @@ function Make(Spec) {
     };
     let replayProcessAppend = (id, topicItemsForId) => {
       let idStr = Spec.Id.toString(id);
-      return Effect.flatMap(Effect.tap(Stream.runFold(Ops.eventLog.replayStream(id), [
-        Behavior.initialState,
-        0
-      ], (param, ev) => [
-        Behavior.evolve(param[0], ev),
-        param[1] + 1 | 0
-      ]), param => EffectLogger$ReventlessCore.logInfo(comp, undefined, `replay: id=` + idStr + `, ` + param[1].toString() + ` event(s)`)), param => {
+      let match = Lru$ReventlessCore.get(replayCache, idStr);
+      let readState;
+      if (match !== undefined) {
+        let seqNr = match[1];
+        let state = match[0];
+        readState = Effect.map(EffectLogger$ReventlessCore.logInfo(comp, undefined, `replay skipped (cached): id=` + idStr + `, seq=` + seqNr.toString()), () => [
+          state,
+          seqNr
+        ]);
+      } else {
+        readState = coldReadState(id);
+      }
+      return Effect.flatMap(readState, param => {
         let sequenceNr = param[1];
+        let initialState = param[0];
         let match = Stdlib_Array.reduce(topicItemsForId, [
-          param[0],
+          initialState,
           []
         ], processCommand);
         let outcomes = match[1];
+        let finalState = match[0];
         let eventsToAppend = outcomes.map(param => {
           let meta = param[2];
           let outcome = param[1];
@@ -139,6 +276,12 @@ function Make(Spec) {
           let eventJsons = eventsToAppend.map(event$p => Message$ReventlessCore.encode(event$p.event, Spec.eventSchema));
           return Effect.flatMap(Effect.flatMap(EffectLogger$ReventlessCore.logInfo(comp, eventJsons, `produced ` + eventCount + ` event(s): [` + eventDetails + `]`), () => Effect.promise(() => Ops.eventLog.append(sequenceNr, id, eventsToAppend))), appendResult => {
             if (appendResult.TAG === "Ok") {
+              let newSeq = sequenceNr + eventsToAppend.length | 0;
+              Lru$ReventlessCore.put(replayCache, idStr, [
+                finalState,
+                newSeq
+              ]);
+              maybeWriteSnapshot(id, idStr, sequenceNr, newSeq, finalState);
               let perRef = reportFinalOutcomes(outcomes, idStr, true, eventsToAppend.length, undefined);
               return Effect.map(EffectLogger$ReventlessCore.logInfo(comp, undefined, `append: id=` + idStr), () => ({
                 TAG: "Ok",
@@ -147,12 +290,14 @@ function Make(Spec) {
             }
             let msg = appendResult._0;
             if (typeof msg !== "object") {
+              Lru$ReventlessCore.invalidate(replayCache, idStr);
               return Effect.map(EffectLogger$ReventlessCore.logWarn(comp, undefined, `conflict: id=` + idStr + `, will retry`), () => ({
                 TAG: "Error",
                 _0: "conflict"
               }));
             }
             let msg$1 = msg._0;
+            Lru$ReventlessCore.invalidate(replayCache, idStr);
             let perRef$1 = reportFinalOutcomes(outcomes, idStr, false, 0, msg$1);
             return Effect.map(EffectLogger$ReventlessCore.logError(comp, undefined, `append failed: id=` + idStr + `: ` + msg$1), () => ({
               TAG: "Ok",
@@ -160,6 +305,10 @@ function Make(Spec) {
             }));
           });
         }
+        Lru$ReventlessCore.put(replayCache, idStr, [
+          initialState,
+          sequenceNr
+        ]);
         let perRef = reportFinalOutcomes(outcomes, idStr, true, 0, undefined);
         return Effect.map(EffectLogger$ReventlessCore.logInfo(comp, undefined, `no events produced: id=` + idStr), () => ({
           TAG: "Ok",
@@ -198,7 +347,8 @@ function Make(Spec) {
     }), prim => prim.flat()));
     return {
       Spec: Spec,
-      handleCommands: handleCommands
+      handleCommands: handleCommands,
+      resetCache: resetCache
     };
   });
 }
@@ -206,4 +356,4 @@ function Make(Spec) {
 export {
   Make,
 }
-/* effect/Effect Not a pure module */
+/* S Not a pure module */

package/src/components/DcbEventLog/DcbEventLog_Operations.res

@@ -92,6 +92,9 @@ module Make = (Ops: Ops): T => {
           eventCount: finalRawEventsJson->Array.length,
           eventsJson: finalRawEventsJson,
           meta: representativeMeta,
+          // Bare payloads carry no meta inline — expose the per-event metas so
+          // afterPublish consumers can correlate each published event.
+          metas: rawEvents->Array.map(re => re.meta),
         }
         let _ = await hook(published)
       } catch {

package/src/components/DcbEventLog/DcbEventLog_Operations.res.mjs

@@ -62,12 +62,14 @@ function Make(Ops) {
     }
     try {
       let published_eventCount$1 = finalRawEventsJson.length;
+      let published_metas = rawEvents.map(re => re.meta);
       let published$1 = {
         componentName: name,
         entityId: name,
         eventCount: published_eventCount$1,
         eventsJson: finalRawEventsJson,
-        meta: representativeMeta
+        meta: representativeMeta,
+        metas: published_metas
       };
       await hook$1(published$1);
       return;

package/src/components/EventLog/EventLog.res

@@ -19,10 +19,27 @@ type appendError =
   | Conflict
   | StorageFailure(string)
 
+// A persisted aggregate-state snapshot: `state` is the fold of events
+// seq 0..seqNr-1, so `seqNr` doubles as the sequence number to resume the
+// replay from (and the OCC condition for the next append). `schemaHash` gates
+// staleness — consumers ignore a snapshot whose hash differs from their current
+// state schema and fall back to full replay. Snapshots are a read optimization
+// only; the OCC append remains the sole consistency primitive
+// (docs/plans/aggregate-snapshotting.md).
+type snapshot = {seqNr: int, state: JSON.t, schemaHash: string}
+
 type append<'id, 'event> = (int, 'id, array<'event>) => promise<result<unit, appendError>>
 type replay<'id, 'event> = 'id => promise<array<'event>>
-type replayStream<'id, 'event> = 'id => Stream.t<'event, string, unit>
+// `fromSeq` starts the replay at that sequence number (inclusive; default 0) —
+// the delta read after seeding from a snapshot at seqNr = fromSeq.
+type replayStream<'id, 'event> = ('id, ~fromSeq: int=?) => Stream.t<'event, string, unit>
 type appendStream<'id, 'event> = (int, 'id, Stream.t<'event, string, unit>) => Effect.t<unit, string, unit>
+// Keep-one semantics: `writeSnapshot` overwrites the single snapshot per
+// aggregate; recovery from a corrupt snapshot is full replay, not older
+// snapshots. Failures are plain strings — a snapshot op failure must never
+// fail a command, so no retryable/typed error channel is needed.
+type latestSnapshot<'id> = 'id => promise<result<option<snapshot>, string>>
+type writeSnapshot<'id> = ('id, snapshot) => promise<result<unit, string>>
 
 module type T = {
   module Spec: ReventlessInfra.EventLog.T
@@ -32,6 +49,8 @@ module type T = {
     replay: replay<Spec.Id.t, Spec.event>,
     replayStream: replayStream<Spec.Id.t, Spec.event>,
     appendStream: appendStream<Spec.Id.t, Spec.event>,
+    latestSnapshot: latestSnapshot<Spec.Id.t>,
+    writeSnapshot: writeSnapshot<Spec.Id.t>,
   }
   type component = component<operations>
 

package/src/components/EventLog/EventLog_Adapter.res

@@ -1,8 +1,10 @@
 type operations = {
   append: EventLog.append<string, JSON.t>,
   replay: EventLog.replay<string, JSON.t>,
-  replayStream: string => Stream.t<JSON.t, string, unit>,
+  replayStream: (string, ~fromSeq: int=?) => Stream.t<JSON.t, string, unit>,
   appendStream: EventLog.appendStream<string, JSON.t>,
+  latestSnapshot: EventLog.latestSnapshot<string>,
+  writeSnapshot: EventLog.writeSnapshot<string>,
 }
 type storage = {
   resources: array<ReventlessInfra.Adapter.resource>,

package/src/components/EventLog/EventLog_Builder.res

@@ -10,6 +10,8 @@ module Make = (
     replay: EventLog.replay<Spec.Id.t, Spec.event>,
     replayStream: EventLog.replayStream<Spec.Id.t, Spec.event>,
     appendStream: EventLog.appendStream<Spec.Id.t, Spec.event>,
+    latestSnapshot: EventLog.latestSnapshot<Spec.Id.t>,
+    writeSnapshot: EventLog.writeSnapshot<Spec.Id.t>,
   }
   type component = Component.t<EventLog.t, EventLog.outputs, operations>
 
@@ -44,6 +46,8 @@ module Make = (
           replay: Ops.replay,
           replayStream: Ops.replayStream,
           appendStream: Ops.appendStream,
+          latestSnapshot: Ops.latestSnapshot,
+          writeSnapshot: Ops.writeSnapshot,
         }
       }),
     )

package/src/components/EventLog/EventLog_Builder.res.mjs

@@ -32,7 +32,9 @@ function Make(Spec) {
           append: Ops.append,
           replay: Ops.replay,
           replayStream: Ops.replayStream,
-          appendStream: Ops.appendStream
+          appendStream: Ops.appendStream,
+          latestSnapshot: Ops.latestSnapshot,
+          writeSnapshot: Ops.writeSnapshot
         };
       }));
       let outputs_resources = storage.resources;

package/src/components/EventLog/EventLog_Operations.res

@@ -11,6 +11,8 @@ module type T = {
   let replay: EventLog.replay<Spec.Id.t, Spec.event>
   let replayStream: EventLog.replayStream<Spec.Id.t, Spec.event>
   let appendStream: EventLog.appendStream<Spec.Id.t, Spec.event>
+  let latestSnapshot: EventLog.latestSnapshot<Spec.Id.t>
+  let writeSnapshot: EventLog.writeSnapshot<Spec.Id.t>
 }
 
 // Retry schedule for transient storage errors.
@@ -187,12 +189,19 @@ module Make = (Spec: ReventlessInfra.EventLog.T, Ops: Ops with module Spec = Spe
 
   // Lazy streaming replay — wraps decodeEvent in Effect.sync so thrown exceptions
   // surface through the stream's error channel rather than as unhandled exceptions.
-  let replayStream = id =>
-    Ops.storage.replayStream(id->Spec.Id.toString)
+  let replayStream = (id, ~fromSeq=?) =>
+    Ops.storage.replayStream(id->Spec.Id.toString, ~fromSeq=?fromSeq)
     ->Stream.mapEffect(json =>
       Effect.sync(() => decodeEvent(id->Spec.Id.toString, json))
     )
 
+  // Snapshot passthrough — the state stays JSON at this layer; the consumer
+  // (Aggregate_Callback) decodes it against its own state schema and hash-gates
+  // staleness, so a drifted snapshot degrades to full replay, never to an error.
+  let latestSnapshot = id => Ops.storage.latestSnapshot(id->Spec.Id.toString)
+
+  let writeSnapshot = (id, snap) => Ops.storage.writeSnapshot(id->Spec.Id.toString, snap)
+
   // Streaming append — encodes each Spec.event to the {type, data} storage format
   // and writes sequentially via the storage adapter.
   // Accepts Spec.event items (symmetric with replayStream) to enable direct

package/src/components/EventLog/EventLog_Operations.res.mjs

@@ -186,7 +186,9 @@ function Make(Spec) {
       let id$1 = Spec.Id.toString(id);
       return eventsJson.map(json => decodeEvent(id$1, json));
     };
-    let replayStream = id => Stream.mapEffect(Ops.storage.replayStream(Spec.Id.toString(id)), json => Effect$1.sync(() => decodeEvent(Spec.Id.toString(id), json)));
+    let replayStream = (id, fromSeq) => Stream.mapEffect(Ops.storage.replayStream(Spec.Id.toString(id), fromSeq), json => Effect$1.sync(() => decodeEvent(Spec.Id.toString(id), json)));
+    let latestSnapshot = id => Ops.storage.latestSnapshot(Spec.Id.toString(id));
+    let writeSnapshot = (id, snap) => Ops.storage.writeSnapshot(Spec.Id.toString(id), snap);
     let appendStream = (startingSeqNr, id, stream) => Ops.storage.appendStream(startingSeqNr, Spec.Id.toString(id), Stream.map(stream, event => {
       let json = Message$ReventlessCore.encode(event, Spec.eventSchema);
       let match = Message$ReventlessCore.splitMessage(json);
@@ -206,7 +208,9 @@ function Make(Spec) {
       append: append,
       replay: replay,
       replayStream: replayStream,
-      appendStream: appendStream
+      appendStream: appendStream,
+      latestSnapshot: latestSnapshot,
+      writeSnapshot: writeSnapshot
     };
   };
 }