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

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() {

package/tests/aggregate/AggregateCacheTest.res

@@ -0,0 +1,271 @@
+// Tests for the Aggregate_Callback in-process replay cache (Phase 1 of
+// docs/plans/aggregate-snapshotting.md): a warm same-id command skips the
+// event-log replay and decides on the cached (state, sequenceNr); the OCC
+// append fences staleness — a stale cache conflicts, invalidates, and the
+// retry replays cold.
+//
+// Unlike the other aggregate mocks, this one enforces optimistic concurrency
+// (append conflicts unless seqNr matches the stored count), because the cache's
+// correctness argument rests on exactly that fence. The Checkpoint command
+// records the decision state's size as an event, making the cached fold state
+// observable through ordinary domain behavior.
+
+open JestGlobals
+
+S.enableJson()
+
+module AggSpec = {
+  module Id = Reventless.Id.StringPure
+  let name = "CacheTestAggregate"
+
+  @schema
+  type command =
+    | Add({name: string})
+    | Checkpoint
+    | Noop
+
+  @schema
+  type event =
+    | Added({name: string})
+    | CheckpointTaken({count: int})
+
+  @schema
+  type error = | Never
+
+  let moduleUrl: string = %raw(`import.meta.url`)
+}
+
+module TestBehavior = {
+  module Spec = AggSpec
+  type state = {names: array<string>}
+
+  let initialState = {names: []}
+
+  // Hand-written behavior (no @@reventless.behavior PPX) — satisfy the
+  // Behavior.T snapshot field manually.
+  let snapshot = None
+
+  let moduleUrl: string = %raw(`import.meta.url`)
+
+  let evolve = (state: state, event: AggSpec.event): state =>
+    switch event {
+    | Added({name}) => {names: state.names->Array.concat([name])}
+    | CheckpointTaken(_) => state
+    }
+
+  let decide = (state: state, command: AggSpec.command): result<
+    array<AggSpec.event>,
+    AggSpec.error,
+  > =>
+    switch command {
+    | Add({name}) => Ok([AggSpec.Added({name: name})])
+    | Checkpoint => Ok([AggSpec.CheckpointTaken({count: state.names->Array.length})])
+    | Noop => Ok([])
+    }
+}
+
+let testMeta: Message.meta = {
+  service: "CacheTestAggregate",
+  time: "2024-01-01T00:00:00Z",
+  ip: "127.0.0.1",
+  user: "test-user",
+  msgId: "msg-1",
+  correlationId: "corr-1",
+}
+
+type mockEL = {
+  appendFn: (
+    int,
+    string,
+    array<Message.event'<string, AggSpec.event>>,
+  ) => promise<result<unit, EventLog.appendError>>,
+  replayFn: string => promise<array<AggSpec.event>>,
+  replayStreamFn: string => Stream.t<AggSpec.event, string, unit>,
+  getAll: unit => array<Message.event'<string, AggSpec.event>>,
+  // Appends directly to storage, bypassing the handler — simulates a second
+  // writer the warm cache doesn't know about.
+  injectExternal: (string, AggSpec.event) => unit,
+  appendCallCount: ref<int>,
+  replayCallCount: ref<int>,
+  reset: unit => unit,
+}
+
+let makeMockEL = (): mockEL => {
+  let storedRef: ref<array<Message.event'<string, AggSpec.event>>> = ref([])
+  let appendCount = ref(0)
+  let replayCount = ref(0)
+
+  let eventsFor = id => storedRef.contents->Array.filter(e => e.id == id)
+
+  // Real OCC: the append succeeds only when seqNr matches the current count.
+  let appendFn = async (seqNr, id, newEvents) => {
+    appendCount := appendCount.contents + 1
+    if seqNr != eventsFor(id)->Array.length {
+      Error(EventLog.Conflict)
+    } else {
+      storedRef := storedRef.contents->Array.concat(newEvents)
+      Ok(())
+    }
+  }
+
+  let replayFn = async id => {
+    replayCount := replayCount.contents + 1
+    eventsFor(id)->Array.map(e => e.event)
+  }
+
+  let replayStreamFn = id => {
+    replayCount := replayCount.contents + 1
+    eventsFor(id)->Array.map(e => e.event)->Stream.fromIterable
+  }
+
+  {
+    appendFn,
+    replayFn,
+    replayStreamFn,
+    getAll: () => storedRef.contents,
+    injectExternal: (id, event) =>
+      storedRef := storedRef.contents->Array.concat([{Message.id, meta: testMeta, event}]),
+    appendCallCount: appendCount,
+    replayCallCount: replayCount,
+    reset: () => {
+      storedRef := []
+      appendCount := 0
+      replayCount := 0
+    },
+  }
+}
+
+let mock = makeMockEL()
+
+module OuterEventLog = EventLog
+
+module TestOps = {
+  module Spec = AggSpec
+  module EventLog = {
+    module Spec = {
+      module Id = AggSpec.Id
+      let name = "CacheMockEventLog"
+      @schema
+      type event = AggSpec.event
+    }
+    type operations = {
+      append: (
+        int,
+        string,
+        array<Message.event'<string, AggSpec.event>>,
+      ) => promise<result<unit, EventLog.appendError>>,
+      replay: string => promise<array<AggSpec.event>>,
+      replayStream: (string, ~fromSeq: int=?) => Stream.t<AggSpec.event, string, unit>,
+      appendStream: (int, string, Stream.t<AggSpec.event, string, unit>) => Effect.t<
+        unit,
+        string,
+        unit,
+      >,
+      latestSnapshot: string => promise<result<option<EventLog.snapshot>, string>>,
+      writeSnapshot: (string, EventLog.snapshot) => promise<result<unit, string>>,
+    }
+    type component = Component.t<OuterEventLog.t, OuterEventLog.outputs, operations>
+    // Never called — satisfies module type only
+    let make = (~name as _: string, ~opts as _=?): component => Obj.magic(0)
+  }
+  let eventLog: EventLog.operations = {
+    append: mock.appendFn,
+    replay: mock.replayFn,
+    replayStream: (id, ~fromSeq as _=?) => mock.replayStreamFn(id),
+    appendStream: (_startingSeqNr, _id, stream) => stream->Stream.runDrain,
+    latestSnapshot: async _ => Ok(None),
+    writeSnapshot: async (_, _) => Ok(),
+  }
+}
+
+module TestHandler = Aggregate_Callback.Make(AggSpec, TestBehavior, TestOps)
+
+let makeTopicItem = (reference, command): CommandTopic.topicItem<
+  Message.command'<string, AggSpec.command>,
+> => {
+  command: {
+    id: "agg-1",
+    meta: testMeta,
+    command,
+  },
+  reference,
+}
+
+let run = async command =>
+  await Stream.fromIterable([makeTopicItem("ref", command)])
+  ->TestHandler.handleCommands
+  ->Effect.runPromise
+
+let _ = beforeEach(() => {
+  mock.reset()
+  TestHandler.resetCache()
+})
+
+describe("Aggregate_Callback — replay cache:", () => {
+  testPromise("warm same-id command skips the replay", async () => {
+    let r1 = await run(AggSpec.Add({name: "a"}))
+    let r2 = await run(AggSpec.Add({name: "b"}))
+    expect((r1, r2))->toEqual(([Ok("ref")], [Ok("ref")]))
+    // Only the first command replayed; the second decided on the cached state.
+    expect(mock.replayCallCount.contents)->toBe(1)
+    // Both appends landed at their correct OCC positions (no conflict retries).
+    expect((mock.appendCallCount.contents, mock.getAll()->Array.length))->toEqual((2, 2))
+  })
+
+  testPromise("cached fold state equals a cold replay of the log", async () => {
+    let _ = await run(AggSpec.Add({name: "a"}))
+    let _ = await run(AggSpec.Add({name: "b"}))
+    let _ = await run(AggSpec.Add({name: "c"}))
+    // Warm checkpoint: decided on the cached state (no replay since call 1).
+    let _ = await run(AggSpec.Checkpoint)
+    expect(mock.replayCallCount.contents)->toBe(1)
+    // Cold checkpoint: same aggregate replayed from the log.
+    TestHandler.resetCache()
+    let _ = await run(AggSpec.Checkpoint)
+    expect(mock.replayCallCount.contents)->toBe(2)
+    // Both checkpoints observed the same state — cached fold ≡ replayed fold.
+    let checkpoints =
+      mock.getAll()
+      ->Array.filterMap(e =>
+        switch e.event {
+        | CheckpointTaken({count}) => Some(count)
+        | _ => None
+        }
+      )
+    expect(checkpoints)->toEqual([3, 3])
+  })
+
+  testPromise("stale cache conflicts, invalidates, and self-heals", async () => {
+    let _ = await run(AggSpec.Add({name: "a"}))
+    // A second writer appends behind the warm cache's back.
+    mock.injectExternal("agg-1", AggSpec.Added({name: "external"}))
+    // Warm path appends at the stale seq → OCC conflict → invalidate →
+    // cold retry reads the authoritative log and succeeds.
+    let results = await run(AggSpec.Add({name: "b"}))
+    expect(results)->toEqual([Ok("ref")])
+    // Replays: initial cold + post-conflict cold (the warm attempt skipped).
+    expect(mock.replayCallCount.contents)->toBe(2)
+    expect(mock.getAll()->Array.length)->toBe(3)
+    // The refreshed state includes the external event.
+    let _ = await run(AggSpec.Checkpoint)
+    let last = mock.getAll()->Array.getUnsafe(3)
+    expect(last.event)->toEqual(AggSpec.CheckpointTaken({count: 3}))
+  })
+
+  testPromise("Ok([]) keeps the read snapshot warm", async () => {
+    let _ = await run(AggSpec.Add({name: "a"}))
+    let _ = await run(AggSpec.Noop)
+    let _ = await run(AggSpec.Add({name: "b"}))
+    // Neither the Noop nor the third command replayed.
+    expect(mock.replayCallCount.contents)->toBe(1)
+    expect(mock.getAll()->Array.length)->toBe(2)
+  })
+
+  testPromise("resetCache forces the next command to replay cold", async () => {
+    let _ = await run(AggSpec.Add({name: "a"}))
+    TestHandler.resetCache()
+    let _ = await run(AggSpec.Add({name: "b"}))
+    expect(mock.replayCallCount.contents)->toBe(2)
+    expect(mock.getAll()->Array.length)->toBe(2)
+  })
+})