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

package/src/Projection.res.mjs

@@ -10,6 +10,7 @@ import * as Stream$1 from "effect/Stream";
 import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Logger$ReventlessCore from "./util/Logger.res.mjs";
 import * as DisplayName$Reventless from "@reventlessdev/reventless-spec/src/components/DisplayName.res.mjs";
 import * as Message$ReventlessCore from "./Message.res.mjs";
@@ -30,8 +31,8 @@ let Mapping = {
   MakeGenericSource: MakeGenericSource
 };
 
-function logAction(str) {
-  log.debug("Projection", undefined, str);
+function logAction(makeStr) {
+  log.debugLazy("Projection", makeStr);
 }
 
 function overlayDisplayName(state, stateSchema, spec) {
@@ -148,15 +149,19 @@ async function applyChanges(action, id, beforeStates, afterStates, param, param$
   let addedSubIds = Belt_SetString.diff(afterSubIds, beforeSubIds);
   let addedStates = afterStates.filter(state => Belt_SetString.has(addedSubIds, getSubId(state)));
   let addedCount = addedStates.length;
+  let afterBySubId = {};
+  afterStates.forEach(after => {
+    afterBySubId[getSubId(after)] = after;
+  });
   let changedStates = Stdlib_Array.filterMap(beforeStates, before => {
-    let beforeSubId = getSubId(before);
-    return afterStates.find(after => {
-      if (getSubId(after) === beforeSubId) {
-        return Primitive_object.notequal(after, before);
-      } else {
-        return false;
-      }
-    });
+    let after = afterBySubId[getSubId(before)];
+    if (after === undefined) {
+      return;
+    }
+    let after$1 = Primitive_option.valFromOption(after);
+    if (Primitive_object.notequal(after$1, before)) {
+      return Primitive_option.some(after$1);
+    }
   });
   let changedCount = changedStates.length;
   let batchToSave = changedStates.concat(addedStates).map(state => [
@@ -173,19 +178,24 @@ async function applyChanges(action, id, beforeStates, afterStates, param, param$
     ]
   ]);
   let deletedCount = batchToDelete.length;
-  logAction(action + `(` + id + `): beforeStates:` + beforeCount.toString() + ` afterStates:` + afterCount.toString() + ` added:` + addedCount.toString() + ` changed:` + changedCount.toString() + ` deleted:` + deletedCount.toString());
-  await Promise.all([
+  log.debugLazy("Projection", () => action + `(` + id + `): beforeStates:` + beforeCount.toString() + ` afterStates:` + afterCount.toString() + ` added:` + addedCount.toString() + ` changed:` + changedCount.toString() + ` deleted:` + deletedCount.toString());
+  let result = await Promise.all([
     param.deleteBatch(batchToDelete),
     param.saveBatch(batchToSave)
   ]);
-  return {
-    TAG: "Ok",
-    _0: undefined
-  };
+  let err = result.find(r => r.TAG !== "Ok");
+  if (err !== undefined) {
+    return err;
+  } else {
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  }
 }
 
 function stateToString(state) {
-  return Stdlib_Option.getOrThrow(JSON.stringify(state), undefined);
+  return Stdlib_Option.getOr(JSON.stringify(state), "<unserializable>");
 }
 
 function statesToString(states) {
@@ -211,7 +221,7 @@ async function handleAction(action, operations, subIdConfig) {
     _0: e
   })));
   if (typeof action !== "object") {
-    logAction("Ignore");
+    log.debugLazy("Projection", () => "Ignore");
     return {
       TAG: "Ok",
       _0: undefined
@@ -221,7 +231,7 @@ async function handleAction(action, operations, subIdConfig) {
     case "Create" :
       let state = action._1;
       let id = action._0;
-      logAction(`Create(` + id + `, ` + stateToString(state) + `)`);
+      log.debugLazy("Projection", () => `Create(` + id + `, ` + stateToString(state) + `)`);
       return await save(id, state, "Init", undefined);
     case "CreateMany" :
       let batch = action._0.map(param => [
@@ -229,8 +239,7 @@ async function handleAction(action, operations, subIdConfig) {
         param[1],
         undefined
       ]);
-      let statesStr = batch.map(param => `(` + param[0] + `,` + stateToString(param[1]) + `)`).join(", ");
-      logAction(`CreateMany(` + statesStr + `)`);
+      log.debugLazy("Projection", () => `CreateMany(` + batch.map(param => `(` + param[0] + `,` + stateToString(param[1]) + `)`).join(", ") + `)`);
       return await saveBatch(batch);
     case "Update" :
       let id$1 = action._0;
@@ -245,13 +254,13 @@ async function handleAction(action, operations, subIdConfig) {
       let len = states$1.length;
       if (len !== 1) {
         if (len !== 0) {
-          logAction(`Update Error: Multiple oldStates for ` + id$1 + `)`);
+          log.debugLazy("Projection", () => `Update Error: Multiple oldStates for ` + id$1 + `)`);
           return {
             TAG: "Error",
             _0: "StaleState"
           };
         } else {
-          logAction(`Update Error: No oldState for ` + id$1 + `)`);
+          log.debugLazy("Projection", () => `Update Error: No oldState for ` + id$1 + `)`);
           return {
             TAG: "Error",
             _0: "StaleState"
@@ -260,35 +269,35 @@ async function handleAction(action, operations, subIdConfig) {
       }
       let oldState = states$1[0];
       let newState = action._1(oldState);
-      logAction(`Update(` + id$1 + `, ` + stateToString(oldState) + ` => ` + stateToString(newState) + `)`);
+      log.debugLazy("Projection", () => `Update(` + id$1 + `, ` + stateToString(oldState) + ` => ` + stateToString(newState) + `)`);
       return await save(id$1, newState, "Overwrite", undefined);
     case "UpdateWithDefault" :
       let $$default = action._1;
       let id$2 = action._0;
-      log.debug("Projection", undefined, `UpdateWithDefault(` + id$2 + `, loading ...`);
+      log.debugLazy("Projection", () => `UpdateWithDefault(` + id$2 + `, loading ...`);
       let states$2 = await loadAtMost(2, id$2);
       if (states$2.TAG === "Ok") {
         let states$3 = states$2._0;
         let len$1 = states$3.length;
         if (len$1 !== 1) {
           if (len$1 !== 0) {
-            logAction(`UpdateWithDefault Error: Multiple oldStates for ` + id$2 + `)`);
+            log.debugLazy("Projection", () => `UpdateWithDefault Error: Multiple oldStates for ` + id$2 + `)`);
             return {
               TAG: "Error",
               _0: "StaleState"
             };
           } else {
-            logAction(`UpdateWithDefault(` + id$2 + `, default: ` + stateToString($$default) + `)`);
+            log.debugLazy("Projection", () => `UpdateWithDefault(` + id$2 + `, default: ` + stateToString($$default) + `)`);
             return await save(id$2, $$default, "Init", undefined);
           }
         }
         let oldState$1 = states$3[0];
         let newState$1 = action._2(oldState$1);
-        logAction(`UpdateWithDefault(` + id$2 + `, ` + stateToString(oldState$1) + ` => ` + stateToString(newState$1) + `)`);
+        log.debugLazy("Projection", () => `UpdateWithDefault(` + id$2 + `, ` + stateToString(oldState$1) + ` => ` + stateToString(newState$1) + `)`);
         return await save(id$2, newState$1, "Overwrite", undefined);
       }
       let err = states$2._0;
-      logAction(`UpdateWithDefault Error: Couldn't load oldState(s) for ` + id$2 + `: ` + QueryDb$ReventlessCore.storageErrorToString(err) + `)`);
+      log.debugLazy("Projection", () => `UpdateWithDefault Error: Couldn't load oldState(s) for ` + id$2 + `: ` + QueryDb$ReventlessCore.storageErrorToString(err) + `)`);
       return {
         TAG: "Error",
         _0: err
@@ -296,7 +305,7 @@ async function handleAction(action, operations, subIdConfig) {
     case "Set" :
       let state$1 = action._1;
       let id$3 = action._0;
-      logAction(`Set(` + id$3 + `, ` + stateToString(state$1) + `)`);
+      log.debugLazy("Projection", () => `Set(` + id$3 + `, ` + stateToString(state$1) + `)`);
       return await save(id$3, state$1, "Any", undefined);
     case "SetMany" :
       let set = action._1;
@@ -305,16 +314,15 @@ async function handleAction(action, operations, subIdConfig) {
         set(id),
         undefined
       ]);
-      let statesStr$1 = batch$1.map(param => `(` + param[0] + `,` + stateToString(param[1]) + `)`).join(", ");
-      logAction(`SetMany(` + statesStr$1 + `)`);
+      log.debugLazy("Projection", () => `SetMany(` + batch$1.map(param => `(` + param[0] + `,` + stateToString(param[1]) + `)`).join(", ") + `)`);
       return await saveBatch(batch$1);
     case "Delete" :
       let id$4 = action._0;
-      logAction(`Delete(` + id$4 + `)`);
+      log.debugLazy("Projection", () => `Delete(` + id$4 + `)`);
       return await operations.delete(id$4, undefined);
     case "DeleteMany" :
       let ids = action._0;
-      logAction(`DeleteMany(` + ids.join(", ") + `)`);
+      log.debugLazy("Projection", () => `DeleteMany(` + ids.join(", ") + `)`);
       return await operations.deleteBatch(ids.map(id => [
         id,
         undefined
@@ -322,7 +330,7 @@ async function handleAction(action, operations, subIdConfig) {
     case "CreateMultiState" :
       let states$4 = action._1;
       let id$5 = action._0;
-      logAction(`CreateMultiState(` + id$5 + `, ` + states$4.map(stateToString).join(", ") + `)`);
+      log.debugLazy("Projection", () => `CreateMultiState(` + id$5 + `, ` + states$4.map(stateToString).join(", ") + `)`);
       let len$2 = states$4.length;
       if (len$2 !== 1) {
         if (len$2 === 0) {
@@ -349,30 +357,27 @@ async function handleAction(action, operations, subIdConfig) {
           let afterStates = action._1(states$5);
           return await applyChanges("UpdateMultiState", id$6, states$5, afterStates, operations, subIdConfig);
         }
-        logAction("UpdateMultiState Error: Missing SubIdConfig !");
-        return {
-          TAG: "Error",
-          _0: "MissingSubIdConfig"
-        };
-      }
-      if (subIdConfig !== undefined) {
+      } else if (subIdConfig !== undefined) {
         let err$1 = match._0;
-        logAction(`UpdateMultiState Error: Couldn't load states for ` + id$6 + `: ` + QueryDb$ReventlessCore.storageErrorToString(err$1) + `)`);
+        log.debugLazy("Projection", () => `UpdateMultiState Error: Couldn't load states for ` + id$6 + `: ` + QueryDb$ReventlessCore.storageErrorToString(err$1) + `)`);
         return {
           TAG: "Error",
           _0: err$1
         };
       }
-      logAction("UpdateMultiState Error: Missing SubIdConfig !");
+      log.debugLazy("Projection", () => "UpdateMultiState Error: Missing SubIdConfig !");
       return {
         TAG: "Error",
         _0: "MissingSubIdConfig"
       };
     default:
-      logAction("Error: Action not yet supported !");
+      log.debugLazy("Projection", () => "Error: projection action not supported");
       return {
-        TAG: "Ok",
-        _0: undefined
+        TAG: "Error",
+        _0: {
+          TAG: "NotSavedToStorage",
+          _0: "unsupported projection action"
+        }
       };
   }
 }
@@ -416,8 +421,7 @@ function actionsWithId(action) {
     case "UpdateManyWithDefault" :
     case "DeleteIf" :
     case "DeleteManyIf" :
-      logAction("Error: Action not yet supported !");
-      return [];
+      break;
     case "UpdateManyMultiStates" :
       let update = action._1;
       return action._0.map(id => [
@@ -434,18 +438,26 @@ function actionsWithId(action) {
           action
         ]];
   }
+  log.debugLazy("Projection", () => "Error: Action not yet supported !");
+  return [];
 }
 
 function groupActionsById(actions) {
   let allActionsWithId = actions.map(actionsWithId).flat();
-  let ids = allActionsWithId.map(param => param[0]);
-  return Belt_SetString.toArray(Belt_SetString.fromArray(ids)).map(id => [
+  let groups = {};
+  allActionsWithId.forEach(param => {
+    let action = param[1];
+    let id = param[0];
+    let arr = groups[id];
+    if (arr !== undefined) {
+      arr.push(action);
+    } else {
+      groups[id] = [action];
+    }
+  });
+  return Belt_SetString.toArray(Belt_SetString.fromArray(Object.keys(groups))).map(id => [
     id,
-    Stdlib_Array.filterMap(allActionsWithId, param => {
-      if (param[0] === id) {
-        return param[1];
-      }
-    })
+    groups[id]
   ]);
 }
 
@@ -456,7 +468,7 @@ function optimizeActions(actions) {
       return [action];
     }
     let lastAction = optimizedActions[optimizedActionsCount - 1 | 0];
-    let previousActions = optimizedActionsCount === 1 ? [] : optimizedActions.slice(0, optimizedActionsCount);
+    let previousActions = optimizedActions.slice(0, optimizedActionsCount - 1 | 0);
     if (typeof lastAction === "object") {
       switch (lastAction.TAG) {
         case "Create" :

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,28 @@ 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
+
   // 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 +160,25 @@ 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 replay cache and skip the event-log read; the
+    // OCC append below fences any staleness. Cold path: full replay as before.
+    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)`)
+      )
+    }
+
+    readState
     ->Effect.flatMap(((initialState, sequenceNr)) => {
-      let (_finalState, outcomes) =
+      let (finalState, outcomes) =
         topicItemsForId->Array.reduce((initialState, []), processCommand)
 
       let eventsToAppend =
@@ -154,6 +193,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 +220,12 @@ 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.
+              replayCache->Lru.put(
+                idStr,
+                (finalState, sequenceNr + generatedEvents'->Array.length),
+              )
               let perRef = reportFinalOutcomes(
                 outcomes,
                 ~entityId=idStr,
@@ -185,11 +233,21 @@ module Make = (
                 ~appendedEventCount=generatedEvents'->Array.length,
               )
               EffectLogger.logInfo(~comp, `append: id=${idStr}`)->Effect.map(_ => Ok(perRef))
-            | Error(msg) if msg->String.includes("conflict") =>
+            | 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.
               EffectLogger.logWarn(~comp, `conflict: id=${idStr}, will retry`)->Effect.map(
-                _ => Error(msg),
+                _ => Error("conflict"),
               )
-            | Error(msg) =>
+            | 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

@@ -4,6 +4,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.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 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";
@@ -64,6 +65,8 @@ function Make(Spec) {
           ]])
       ];
     };
+    let replayCache = Lru$ReventlessCore.make(100);
+    let resetCache = () => Lru$ReventlessCore.clear(replayCache);
     let reportFinalOutcomes = (outcomes, entityId, appendSucceeded, appendedEventCount, appendErrorDetailOpt) => {
       let appendErrorDetail = appendErrorDetailOpt !== undefined ? appendErrorDetailOpt : "";
       return outcomes.map(param => {
@@ -102,19 +105,33 @@ 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 = 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)`));
+      }
+      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 +156,10 @@ 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") {
+              Lru$ReventlessCore.put(replayCache, idStr, [
+                finalState,
+                sequenceNr + eventsToAppend.length | 0
+              ]);
               let perRef = reportFinalOutcomes(outcomes, idStr, true, eventsToAppend.length, undefined);
               return Effect.map(EffectLogger$ReventlessCore.logInfo(comp, undefined, `append: id=` + idStr), () => ({
                 TAG: "Ok",
@@ -146,19 +167,26 @@ function Make(Spec) {
               }));
             }
             let msg = appendResult._0;
-            if (msg.includes("conflict")) {
+            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: msg
+                _0: "conflict"
               }));
             }
-            let perRef$1 = reportFinalOutcomes(outcomes, idStr, false, 0, msg);
-            return Effect.map(EffectLogger$ReventlessCore.logError(comp, undefined, `append failed: id=` + idStr + `: ` + msg), () => ({
+            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",
               _0: perRef$1
             }));
           });
         }
+        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",
@@ -197,7 +225,8 @@ function Make(Spec) {
     }), prim => prim.flat()));
     return {
       Spec: Spec,
-      handleCommands: handleCommands
+      handleCommands: handleCommands,
+      resetCache: resetCache
     };
   });
 }

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

@@ -7,10 +7,39 @@ type component<'operations> = Component.t<t, outputs, 'operations>
 
 exception ReplayError(string)
 
-type append<'id, 'event> = (int, 'id, array<'event>) => promise<result<unit, string>>
+// Typed append outcome. `Conflict` is the optimistic-concurrency sentinel — the
+// deliberate append-condition failure (seq_nr/position already taken) that the
+// caller retries by re-reading and re-deciding. Every other failure is a
+// `StorageFailure` carrying its message. This replaces the former string sentinel
+// that was detected by substring-matching a pretty-printed Cause across three
+// layers — a real error whose text happened to contain "conflict" would have
+// been retried as an OCC conflict, and a misclassified conflict would surface as
+// a permanent error.
+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
@@ -20,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;