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

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,
@@ -186,6 +234,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 +244,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

@@ -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",
@@ -147,12 +168,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 +183,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 +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

@@ -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
     };
   };
 }

package/src/components/EventLog/EventPublish_Callback.res

@@ -4,6 +4,13 @@ type publishedEvent = {
   eventCount: int,
   eventsJson: array<JSON.t>,
   meta: Reventless.Message.meta,
+  // Per-event metas, parallel to eventsJson. Populated by publishers whose
+  // eventsJson entries do NOT carry the meta fields inline (DcbEventLog: bare
+  // {TAG, ...data} payloads) so hook consumers can still correlate per event
+  // (e.g. the local projection checkpoint resolves pending appends by msgId).
+  // Aggregate EventLog eventsJson are flat stored events with meta at the top
+  // level, so it omits this field.
+  metas?: array<Reventless.Message.meta>,
 }
 
 type beforePublishHook = publishedEvent => promise<publishedEvent>

package/src/components/StateChangeSlice/StateChangeSlice_Callback.res

@@ -199,13 +199,33 @@ module Make = (
       Some(Reventless.DcbTag.getCompositePartitionKeyValue(tags, spec))
     }
 
-    let cacheKey = query->JSON.stringifyAny->Option.getOr("")
+    // Fail closed: a query that can't be serialized yields `None`, not the empty
+    // string. The old `""` fallback made every unserializable query collide on
+    // one shared cache slot, so one slice's folded state could seed another's —
+    // a silent correctness bug. `None` simply bypasses the cache (cold read, no
+    // write) for that operation.
+    let cacheKey = query->JSON.stringifyAny
+    let cacheGet = () =>
+      switch cacheKey {
+      | Some(k) => Lru.get(projectionCache, k)
+      | None => None
+      }
+    let cachePut = v =>
+      switch cacheKey {
+      | Some(k) => Lru.put(projectionCache, k, v)
+      | None => ()
+      }
+    let cacheInvalidate = () =>
+      switch cacheKey {
+      | Some(k) => Lru.invalidate(projectionCache, k)
+      | None => ()
+      }
 
     // Working seed across retries: the `(state, head)` the read folds from.
     // Starts from the projection cache (warm) or empty (cold); the conflict
     // branch re-seeds it with the just-read `(state, head)` so each retry reads
     // only the delta the conflicting writer added rather than full history.
-    let seed = ref(Lru.get(projectionCache, cacheKey))
+    let seed = ref(cacheGet())
 
     let rec attempt = (~retries) => {
       let (baseState, afterPos) = switch seed.contents {
@@ -275,7 +295,7 @@ module Make = (
           switch Behavior.decide(state, command'.command) {
           | Ok(newEvents) if newEvents->Array.length == 0 =>
             // No append, but the read snapshot is valid — cache it for the next command.
-            Lru.put(projectionCache, cacheKey, (state, headPosition))
+            cachePut((state, headPosition))
             CommandTopic_Helpers.reportAccepted(
               cmdJson.meta.msgId,
               switch entityId {
@@ -326,7 +346,7 @@ module Make = (
                   // Cache the decided-on state at the read head (NOT including the
                   // events we just appended, and NOT the returned position): the
                   // next command's delta read picks our events up from `headPosition`.
-                  Lru.put(projectionCache, cacheKey, (state, headPosition))
+                  cachePut((state, headPosition))
                   CommandTopic_Helpers.reportAccepted(
                     cmdJson.meta.msgId,
                     switch entityId {
@@ -354,7 +374,7 @@ module Make = (
                   } else {
                     // Retries exhausted — drop any cached snapshot so the next
                     // command for this entity takes the cold full-read path.
-                    Lru.invalidate(projectionCache, cacheKey)
+                    cacheInvalidate()
                     let errorCode = err->String.startsWith("Conflict") ? "Conflict" : "AppendFailed"
                     // A surfaced Conflict means the 3-retry loop could not absorb
                     // the contention — the operator signal for "this slice is hot"
@@ -375,7 +395,7 @@ module Make = (
             )
           | Error(error) =>
             // Business-rule rejection — no append, but the read snapshot is valid; cache it.
-            Lru.put(projectionCache, cacheKey, (state, headPosition))
+            cachePut((state, headPosition))
             let errorJson = error->S.reverseConvertToJsonOrThrow(Spec.errorSchema)
             let errorCode = errorJson->Message.variantNameOfJson
             let (_, payloadDict) = errorJson->Message.splitMessage

package/src/components/StateChangeSlice/StateChangeSlice_Callback.res.mjs

@@ -82,9 +82,24 @@ function Make(Spec) {
         let tags = DcbTag$Reventless.extractTags(Spec.commandSchema, command$p.command);
         entityId = DcbTag$Reventless.getCompositePartitionKeyValue(tags, derivedPartitionTag._0);
       }
-      let cacheKey = Stdlib_Option.getOr(JSON.stringify(query), "");
+      let cacheKey = JSON.stringify(query);
+      let cacheGet = () => {
+        if (cacheKey !== undefined) {
+          return Lru$ReventlessCore.get(projectionCache, cacheKey);
+        }
+      };
+      let cachePut = v => {
+        if (cacheKey !== undefined) {
+          return Lru$ReventlessCore.put(projectionCache, cacheKey, v);
+        }
+      };
+      let cacheInvalidate = () => {
+        if (cacheKey !== undefined) {
+          return Lru$ReventlessCore.invalidate(projectionCache, cacheKey);
+        }
+      };
       let seed = {
-        contents: Lru$ReventlessCore.get(projectionCache, cacheKey)
+        contents: cacheGet()
       };
       let attempt = retries => {
         let match = seed.contents;
@@ -150,7 +165,7 @@ function Make(Spec) {
             if (newEvents.TAG === "Ok") {
               let newEvents$1 = newEvents._0;
               if (newEvents$1.length === 0) {
-                Lru$ReventlessCore.put(projectionCache, cacheKey, [
+                cachePut([
                   state,
                   headPosition
                 ]);
@@ -204,7 +219,7 @@ function Make(Spec) {
               };
               return Effect.flatMap(Effect.flatMap(EffectLogger$ReventlessCore.logInfo(comp, eventJsons, `produced ` + eventCount + ` event(s): [` + eventDetails + `]`), () => Effect.promise(() => dcbEventLog.append(rawEvents, condition))), appendResult => {
                 if (appendResult.TAG === "Ok") {
-                  Lru$ReventlessCore.put(projectionCache, cacheKey, [
+                  cachePut([
                     state,
                     headPosition
                   ]);
@@ -228,7 +243,7 @@ function Make(Spec) {
                   Metrics$ReventlessCore.emitCount("AppendRetry", Spec.name, undefined);
                   return Effect.flatMap(EffectLogger$ReventlessCore.logWarn(comp, undefined, `append failed (retrying ` + ((3 - retries | 0) + 1 | 0).toString() + `/` + (3).toString() + `): ` + err), () => attempt(retries - 1 | 0));
                 }
-                Lru$ReventlessCore.invalidate(projectionCache, cacheKey);
+                cacheInvalidate();
                 let errorCode = err.startsWith("Conflict") ? "Conflict" : "AppendFailed";
                 if (errorCode === "Conflict") {
                   Metrics$ReventlessCore.emitCount("AppendConflict", Spec.name, undefined);
@@ -243,7 +258,7 @@ function Make(Spec) {
                 }));
               });
             }
-            Lru$ReventlessCore.put(projectionCache, cacheKey, [
+            cachePut([
               state,
               headPosition
             ]);

package/src/plugin/lifecycle/PluginBehavior.res

@@ -30,6 +30,12 @@ type state = {
 
 let initialState = {current: None, known: Dict.make()}
 
+// The @@reventless.behavior snapshot injection is gated to Aggregate/ folders;
+// this framework-internal behavior lives under plugin/lifecycle, so the
+// Behavior.T field is satisfied manually. The admin Plugin aggregate's history
+// is short (lifecycle transitions), so persisted snapshots would buy nothing.
+let snapshot = None
+
 let atomicCounter = None
 
 let uiRegisterEvents = (pluginId, manifest) =>

package/src/plugin/lifecycle/PluginBehavior.res.mjs

@@ -366,6 +366,8 @@ function evolve(state, event) {
 
 let Spec;
 
+let snapshot;
+
 let atomicCounter;
 
 let moduleUrl = "@reventlessdev/reventless-core/src/plugin/lifecycle/PluginBehavior.res.mjs";
@@ -376,6 +378,7 @@ export {
   knownVersionSchema,
   stateSchema,
   initialState,
+  snapshot,
   atomicCounter,
   uiRegisterEvents,
   uiDeregisterEvents,

package/src/util/Logger.res

@@ -37,6 +37,11 @@ type t = {
   info: logFn,
   warn: logFn,
   error: logFn,
+  // Lazy debug: the message thunk runs only when debug output is actually
+  // enabled. On a hot path (e.g. per-projection-action logging) this avoids
+  // building — and serializing state into — a string that is then dropped at
+  // the default Info level.
+  debugLazy: (~comp: string=?, unit => string) => unit,
 }
 
 type level = Debug | Info | Warn | Error
@@ -172,6 +177,10 @@ let makeLogger = (~minLevel=Info): t => {
     info: (~comp=?, ~data=?, msg) => log(Info, ~comp?, ~data?, msg),
     warn: (~comp=?, ~data=?, msg) => log(Warn, ~comp?, ~data?, msg),
     error: (~comp=?, ~data=?, msg) => log(Error, ~comp?, ~data?, msg),
+    debugLazy: (~comp=?, makeMsg) =>
+      if shouldLog(Debug) {
+        emit(~level=Debug, ~comp?, makeMsg())
+      },
   }
 }
 
@@ -180,6 +189,7 @@ let silent: t = {
   info: (~comp as _=?, ~data as _=?, _) => (),
   warn: (~comp as _=?, ~data as _=?, _) => (),
   error: (~comp as _=?, ~data as _=?, _) => (),
+  debugLazy: (~comp as _=?, _) => (),
 }
 
 // Reads LOG_LEVEL from process.env and returns a configured logger.

package/src/util/Logger.res.mjs

@@ -156,7 +156,12 @@ function makeLogger(minLevelOpt) {
     debug: (comp, data, msg) => log("Debug", comp, data, msg),
     info: (comp, data, msg) => log("Info", comp, data, msg),
     warn: (comp, data, msg) => log("Warn", comp, data, msg),
-    error: (comp, data, msg) => log("Error", comp, data, msg)
+    error: (comp, data, msg) => log("Error", comp, data, msg),
+    debugLazy: (comp, makeMsg) => {
+      if (shouldLog("Debug")) {
+        return emit("Debug", comp, undefined, undefined, undefined, makeMsg());
+      }
+    }
   };
 }
 
@@ -176,11 +181,16 @@ function silent_error(param, param$1, param$2) {
   
 }
 
+function silent_debugLazy(param, param$1) {
+  
+}
+
 let silent = {
   debug: silent_debug,
   info: silent_info,
   warn: silent_warn,
-  error: silent_error
+  error: silent_error,
+  debugLazy: silent_debugLazy
 };
 
 function fromEnv() {