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

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.138 (2026-07-04)
+
+### Features
+
+* **core:** wire aggregate snapshots into the command callback (aggregate-snapshotting plan, step 5) ([09fda78](https://github.com/ReventlessDev/reventless-core/commit/09fda78a19bb758482111cebedfdb115d0ec7a35))
+
+
 # 3.0.0-alpha.137 (2026-07-03)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.137",
+  "version": "3.0.0-alpha.138",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,13 +28,13 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.24",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
+    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.11",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.5",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.10",
-    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.11",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.24",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.11",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.13",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.23",
     "@reventlessdev/reventless-spec": "3.0.0-alpha.64",

package/src/components/Aggregate/Aggregate_Callback.res

@@ -122,6 +122,154 @@ module Make = (
 
   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 —
@@ -160,20 +308,17 @@ module Make = (
   ) => {
     let idStr = id->Spec.Id.toString
 
-    // Warm path: seed from the replay cache and skip the event-log read; the
-    // OCC append below fences any staleness. Cold path: full replay as before.
+    // 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 =>
-      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)`)
-      )
+    | None => coldReadState(id)
     }
 
     readState
@@ -222,10 +367,11 @@ module Make = (
             | Ok(_) =>
               // The post-decide fold state IS the post-append replay result;
               // cache it so the next command for this id skips the replay.
-              replayCache->Lru.put(
-                idStr,
-                (finalState, sequenceNr + generatedEvents'->Array.length),
-              )
+              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,

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

@@ -1,13 +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) {
@@ -67,6 +74,125 @@ 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 => {
@@ -115,13 +241,7 @@ function Make(Spec) {
           seqNr
         ]);
       } else {
-        readState = Effect.tap(Stream.runFold(Ops.eventLog.replayStream(id, undefined), [
-          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)`));
+        readState = coldReadState(id);
       }
       return Effect.flatMap(readState, param => {
         let sequenceNr = param[1];
@@ -156,10 +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,
-                sequenceNr + eventsToAppend.length | 0
+                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",
@@ -234,4 +356,4 @@ function Make(Spec) {
 export {
   Make,
 }
-/* effect/Effect Not a pure module */
+/* S Not a pure module */