@reventlessdev/reventless-aws 3.0.0-alpha.168 → 3.0.0-alpha.170

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.170 (2026-07-03)
+
+### Features
+
+* **core,local,aws:** EventLog snapshot storage surface, all backends (aggregate-snapshotting plan, steps 3+4) ([b6e50e2](https://github.com/ReventlessDev/reventless-core/commit/b6e50e2e5fe50b7372e54811f883fa91f6758dd1))
+
+
+# 3.0.0-alpha.169 (2026-07-02)
+
+**Note:** Version bump only for package @reventlessdev/reventless-aws
+
+
+
+
+
 # 3.0.0-alpha.168 (2026-06-29)
 
 **Note:** Version bump only for package @reventlessdev/reventless-aws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.168",
+  "version": "3.0.0-alpha.170",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -8,16 +8,16 @@
     "@aws-sdk/client-cloudfront": "3.970.0",
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.23",
     "@reventlessdev/rescript-aws-sdk": "2.2.0-alpha.20",
     "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.44",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.5",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.3",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.24",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.13",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.135",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.82",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.21",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.62"
+    "@reventlessdev/reventless-core": "3.0.0-alpha.137",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.84",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.23",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.64"
   },
   "devDependencies": {
     "rescript": "^12.3.0",

package/src/Platform.res.mjs

@@ -764,6 +764,7 @@ function MakeWithConfig(Config) {
     initialState: PluginBehavior$ReventlessCore.initialState,
     evolve: PluginBehavior$ReventlessCore.evolve,
     decide: PluginBehavior$ReventlessCore.decide,
+    snapshot: undefined,
     moduleUrl: PluginBehavior$ReventlessCore.moduleUrl
   })(NoEventMappings$ReventlessInfra.Make({
     name: PluginSpec$ReventlessCore.name,
@@ -1851,6 +1852,7 @@ function Make($star) {
     initialState: PluginBehavior$ReventlessCore.initialState,
     evolve: PluginBehavior$ReventlessCore.evolve,
     decide: PluginBehavior$ReventlessCore.decide,
+    snapshot: undefined,
     moduleUrl: PluginBehavior$ReventlessCore.moduleUrl
   })(NoEventMappings$ReventlessInfra.Make({
     name: PluginSpec$ReventlessCore.name,

package/src/adapter/EventLog/EventLogStorage_DynamoDb.res

@@ -18,8 +18,10 @@ let make: ReventlessCore.EventLog_Adapter.storageMaker = (~name, ~opts) => {
         ...
       ),
       replay: EventLogStorage_DynamoDb_Runtime.replay(resolvedTable, ...),
-      replayStream: EventLogStorage_DynamoDb_Runtime.replayStream(resolvedTable, ...),
+      replayStream: EventLogStorage_DynamoDb_Runtime.replayStream(resolvedTable),
       appendStream: EventLogStorage_DynamoDb_Runtime.appendStream(resolvedTable, ...),
+      latestSnapshot: EventLogStorage_DynamoDb_Runtime.latestSnapshot(resolvedTable),
+      writeSnapshot: EventLogStorage_DynamoDb_Runtime.writeSnapshot(resolvedTable),
     }),
   }
 }

package/src/adapter/EventLog/EventLogStorage_DynamoDb.res.mjs

@@ -23,7 +23,9 @@ function make(name, opts) {
       append: EventLogStorage_DynamoDb_Runtime$ReventlessAws.append(resolvedTable),
       replay: EventLogStorage_DynamoDb_Runtime$ReventlessAws.replay(resolvedTable),
       replayStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.replayStream(resolvedTable),
-      appendStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.appendStream(resolvedTable)
+      appendStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.appendStream(resolvedTable),
+      latestSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.latestSnapshot(resolvedTable),
+      writeSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.writeSnapshot(resolvedTable)
     }))
   };
 }

package/src/adapter/EventLog/EventLogStorage_DynamoDbStream.res

@@ -19,8 +19,10 @@ let make: ReventlessCore.EventLog_Adapter.storageMaker = (~name, ~opts) => {
         ...
       ),
       replay: EventLogStorage_DynamoDb_Runtime.replay(resolvedTable, ...),
-      replayStream: EventLogStorage_DynamoDb_Runtime.replayStream(resolvedTable, ...),
+      replayStream: EventLogStorage_DynamoDb_Runtime.replayStream(resolvedTable),
       appendStream: EventLogStorage_DynamoDb_Runtime.appendStream(resolvedTable, ...),
+      latestSnapshot: EventLogStorage_DynamoDb_Runtime.latestSnapshot(resolvedTable),
+      writeSnapshot: EventLogStorage_DynamoDb_Runtime.writeSnapshot(resolvedTable),
     }),
   }
 }

package/src/adapter/EventLog/EventLogStorage_DynamoDbStream.res.mjs

@@ -24,7 +24,9 @@ function make(name, opts) {
       append: EventLogStorage_DynamoDb_Runtime$ReventlessAws.append(resolvedTable),
       replay: EventLogStorage_DynamoDb_Runtime$ReventlessAws.replay(resolvedTable),
       replayStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.replayStream(resolvedTable),
-      appendStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.appendStream(resolvedTable)
+      appendStream: EventLogStorage_DynamoDb_Runtime$ReventlessAws.appendStream(resolvedTable),
+      latestSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.latestSnapshot(resolvedTable),
+      writeSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.writeSnapshot(resolvedTable)
     }))
   };
 }

package/src/adapter/EventLog/EventLogStorage_DynamoDb_Runtime.res

@@ -40,7 +40,9 @@ let appendWithCondition = (tableName, jsons) => {
   if count > 100 {
     Effect.succeed(
       Error(
-        `EventLog.append: max 100 events per command, got ${count->Int.toString}`,
+        ReventlessCore.EventLog.StorageFailure(
+          `EventLog.append: max 100 events per command, got ${count->Int.toString}`,
+        ),
       ),
     )
   } else if count == 1 {
@@ -58,25 +60,117 @@ let append = table =>
     appendWithCondition(table.name, jsons)
     ->Effect.catchAll(err =>
       switch err {
-      | DynamoDb_Error.StaleState(_) => Effect.succeed(Error("conflict"))
+      | DynamoDb_Error.StaleState(_) =>
+        Effect.succeed(Error(ReventlessCore.EventLog.Conflict))
       | _ =>
         let msg = DynamoDb_Error.message(err)
-        Effect.succeed(Error(`DynamoDB conditional append failed: ${msg}`))
+        Effect.succeed(
+          Error(ReventlessCore.EventLog.StorageFailure(`DynamoDB conditional append failed: ${msg}`)),
+        )
       }
     )
     ->Effect.runPromise
 
+// ─── Aggregate snapshots (docs/plans/aggregate-snapshotting.md) ───
+// A snapshot lives in the SAME table as the events, on the reserved sort key
+// `position = "SNAPSHOT"`. Event positions are 9-digit zero-padded numbers, so
+// bounding the replay query to the all-digit range excludes the snapshot row
+// (and "S" > "9" keeps it out of any position-ordered event scan prefix).
+// Keep-one: writeSnapshot is a plain overwrite Put. The DynamoDB stream feed is
+// unaffected — Util_DynamoDbStream_Runtime.buildJsonEvent' drops rows without
+// an `event` column, so snapshot writes never reach event collectors.
+let snapshotPosition = "SNAPSHOT"
+let maxEventPosition = "999999999"
+let padSeq = seq => seq->Int.toString->String.padStart(9, "0")
+
+// Pure input builders, exposed for tests (same pattern as buildTransactItems).
+let replayQueryInput = (tableName, id, ~fromSeq=0): QueryCommand.input => {
+  tableName,
+  consistentRead: true,
+  keyConditionExpression: "id=:id AND #p BETWEEN :from AND :to",
+  expressionAttributeNames: positionAttrNames,
+  expressionAttributeValues: [
+    (":id", id->JSON.Encode.string),
+    (":from", padSeq(fromSeq)->JSON.Encode.string),
+    (":to", maxEventPosition->JSON.Encode.string),
+  ]->Dict.fromArray,
+}
+
+let snapshotKey = id =>
+  [
+    ("id", id->JSON.Encode.string),
+    ("position", snapshotPosition->JSON.Encode.string),
+  ]->Dict.fromArray
+
+let snapshotItem = (id, snap: ReventlessCore.EventLog.snapshot): JSON.t =>
+  [
+    ("id", id->JSON.Encode.string),
+    ("position", snapshotPosition->JSON.Encode.string),
+    ("seqNr", snap.seqNr->JSON.Encode.int),
+    ("state", snap.state),
+    ("schemaHash", snap.schemaHash->JSON.Encode.string),
+  ]
+  ->Dict.fromArray
+  ->JSON.Encode.object
+
+let decodeSnapshotItem = (item: JSON.t): option<ReventlessCore.EventLog.snapshot> =>
+  item
+  ->JSON.Decode.object
+  ->Option.flatMap(d =>
+    switch (d->Dict.get("seqNr"), d->Dict.get("state"), d->Dict.get("schemaHash")) {
+    | (Some(JSON.Number(n)), Some(state), Some(JSON.String(schemaHash))) =>
+      Some({ReventlessCore.EventLog.seqNr: Float.toInt(n), state, schemaHash})
+    | _ => None
+    }
+  )
+
+let exnMessage = (exn, fallback) =>
+  exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr(fallback)
+
+let latestSnapshot = table =>
+  async id =>
+    try {
+      let out = await GetCommand.send(
+        GetCommand.make({
+          tableName: table.Util_DynamoDb_Runtime.name,
+          key: snapshotKey(id),
+          consistentRead: true,
+        }),
+      )
+      switch out.item {
+      | Some(item) =>
+        switch decodeSnapshotItem(item) {
+        | Some(snap) => Ok(Some(snap))
+        | None => Error("snapshot item has unexpected shape")
+        }
+      | None => Ok(None)
+      }
+    } catch {
+    | exn => Error(exnMessage(exn, "snapshot read error"))
+    }
+
+let writeSnapshot = table =>
+  async (id, snap) =>
+    try {
+      let _ = await PutCommand.send(
+        PutCommand.make({
+          tableName: table.Util_DynamoDb_Runtime.name,
+          item: snapshotItem(id, snap),
+        }),
+      )
+      Ok()
+    } catch {
+    | exn => Error(exnMessage(exn, "snapshot write error"))
+    }
+
 // True lazy pagination: each DynamoDB page is fetched on demand.
 // Per-page retry is handled inside queryStream.
 // Stream.take(n) short-circuits pagination once n events are consumed.
+// `fromSeq` narrows the key condition so a snapshot-seeded delta read only
+// pays for the events it returns.
 let replayStream = table =>
-  id =>
-    queryStream({
-      tableName: table.name,
-      consistentRead: true,
-      keyConditionExpression: "id=:id",
-      expressionAttributeValues: [(":id", id->JSON.Encode.string)]->Dict.fromArray,
-    })
+  (id, ~fromSeq=?) =>
+    queryStream(replayQueryInput(table.Util_DynamoDb_Runtime.name, id, ~fromSeq=?fromSeq))
     ->Stream.catchAll(err => {
       let msg = DynamoDb_Error.message(err)
       Stream.fromEffect(Effect.fail(msg))

package/src/adapter/EventLog/EventLogStorage_DynamoDb_Runtime.res.mjs

@@ -2,8 +2,12 @@
 
 import * as Effect from "@reventlessdev/rescript-effect/src/Effect.res.mjs";
 import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect$1 from "effect/Effect";
 import * as Stream$1 from "effect/Stream";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as LibDynamodb from "@aws-sdk/lib-dynamodb";
 import * as EffectLogger$ReventlessCore from "@reventlessdev/reventless-core/src/util/EffectLogger.res.mjs";
 import * as DynamoDb_Error$ReventlessAws from "../../errors/DynamoDb_Error.res.mjs";
@@ -51,7 +55,10 @@ function appendWithCondition(tableName, jsons) {
   if (count > 100) {
     return Effect$1.succeed({
       TAG: "Error",
-      _0: `EventLog.append: max 100 events per command, got ` + count.toString()
+      _0: {
+        TAG: "StorageFailure",
+        _0: `EventLog.append: max 100 events per command, got ` + count.toString()
+      }
     });
   } else if (count === 1) {
     return Effect$1.map(Effect.tryPromise(DynamoDb_Error$ReventlessAws.classify, () => putItemConditional(tableName, jsons[0])), param => ({
@@ -69,7 +76,7 @@ function append(table) {
       case "StaleState" :
         return Effect$1.succeed({
           TAG: "Error",
-          _0: "conflict"
+          _0: "Conflict"
         });
       case "Transient" :
       case "Permanent" :
@@ -78,28 +85,170 @@ function append(table) {
     let msg = DynamoDb_Error$ReventlessAws.message(err);
     return Effect$1.succeed({
       TAG: "Error",
-      _0: `DynamoDB conditional append failed: ` + msg
+      _0: {
+        TAG: "StorageFailure",
+        _0: `DynamoDB conditional append failed: ` + msg
+      }
     });
   }));
 }
 
-function replayStream(table) {
-  return id => Stream$1.catchAll(Util_DynamoDb_Runtime$ReventlessAws.queryStream({
-    TableName: table.name,
+let snapshotPosition = "SNAPSHOT";
+
+let maxEventPosition = "999999999";
+
+function padSeq(seq) {
+  return seq.toString().padStart(9, "0");
+}
+
+function replayQueryInput(tableName, id, fromSeqOpt) {
+  let fromSeq = fromSeqOpt !== undefined ? fromSeqOpt : 0;
+  return {
+    TableName: tableName,
     ConsistentRead: true,
-    ExpressionAttributeValues: Object.fromEntries([[
+    ExpressionAttributeNames: positionAttrNames,
+    ExpressionAttributeValues: Object.fromEntries([
+      [
         ":id",
         id
-      ]]),
-    KeyConditionExpression: "id=:id"
-  }), err => {
+      ],
+      [
+        ":from",
+        padSeq(fromSeq)
+      ],
+      [
+        ":to",
+        maxEventPosition
+      ]
+    ]),
+    KeyConditionExpression: "id=:id AND #p BETWEEN :from AND :to"
+  };
+}
+
+function snapshotKey(id) {
+  return Object.fromEntries([
+    [
+      "id",
+      id
+    ],
+    [
+      "position",
+      snapshotPosition
+    ]
+  ]);
+}
+
+function snapshotItem(id, snap) {
+  return Object.fromEntries([
+    [
+      "id",
+      id
+    ],
+    [
+      "position",
+      snapshotPosition
+    ],
+    [
+      "seqNr",
+      snap.seqNr
+    ],
+    [
+      "state",
+      snap.state
+    ],
+    [
+      "schemaHash",
+      snap.schemaHash
+    ]
+  ]);
+}
+
+function decodeSnapshotItem(item) {
+  return Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => {
+    let match = d["seqNr"];
+    let match$1 = d["state"];
+    let match$2 = d["schemaHash"];
+    if (typeof match === "number" && match$1 !== undefined && typeof match$2 === "string") {
+      return {
+        seqNr: match | 0,
+        state: match$1,
+        schemaHash: match$2
+      };
+    }
+  });
+}
+
+function exnMessage(exn, fallback) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), fallback);
+}
+
+function latestSnapshot(table) {
+  return async id => {
+    try {
+      let out = await DynamoDb_DocumentClient$AwsSdk.GetCommand.send(new LibDynamodb.GetCommand({
+        TableName: table.name,
+        Key: snapshotKey(id),
+        ConsistentRead: true
+      }));
+      let item = out.Item;
+      if (item === undefined) {
+        return {
+          TAG: "Ok",
+          _0: undefined
+        };
+      }
+      let snap = decodeSnapshotItem(item);
+      if (snap !== undefined) {
+        return {
+          TAG: "Ok",
+          _0: snap
+        };
+      } else {
+        return {
+          TAG: "Error",
+          _0: "snapshot item has unexpected shape"
+        };
+      }
+    } catch (raw_exn) {
+      let exn = Primitive_exceptions.internalToException(raw_exn);
+      return {
+        TAG: "Error",
+        _0: exnMessage(exn, "snapshot read error")
+      };
+    }
+  };
+}
+
+function writeSnapshot(table) {
+  return async (id, snap) => {
+    try {
+      await DynamoDb_DocumentClient$AwsSdk.PutCommand.send(new LibDynamodb.PutCommand({
+        Item: snapshotItem(id, snap),
+        TableName: table.name
+      }));
+      return {
+        TAG: "Ok",
+        _0: undefined
+      };
+    } catch (raw_exn) {
+      let exn = Primitive_exceptions.internalToException(raw_exn);
+      return {
+        TAG: "Error",
+        _0: exnMessage(exn, "snapshot write error")
+      };
+    }
+  };
+}
+
+function replayStream(table) {
+  return (id, fromSeq) => Stream$1.catchAll(Util_DynamoDb_Runtime$ReventlessAws.queryStream(replayQueryInput(table.name, id, fromSeq)), err => {
     let msg = DynamoDb_Error$ReventlessAws.message(err);
     return Stream$1.fromEffect(Effect$1.fail(msg));
   });
 }
 
 function replay(table) {
-  return id => Effect$1.runPromise(Effect$1.catchAll(Stream.runCollect(replayStream(table)(id)), msg => Effect$1.flatMap(EffectLogger$ReventlessCore.logError("EventLogStorage_DynamoDb_Runtime-ReventlessAws", undefined, `Couldn't replay events for id ` + id + ` after retries: ` + msg), () => Effect$1.fail(msg))));
+  return id => Effect$1.runPromise(Effect$1.catchAll(Stream.runCollect(replayStream(table)(id, undefined)), msg => Effect$1.flatMap(EffectLogger$ReventlessCore.logError("EventLogStorage_DynamoDb_Runtime-ReventlessAws", undefined, `Couldn't replay events for id ` + id + ` after retries: ` + msg), () => Effect$1.fail(msg))));
 }
 
 function appendStream(table) {
@@ -130,6 +279,16 @@ export {
   transactWriteConditional,
   appendWithCondition,
   append,
+  snapshotPosition,
+  maxEventPosition,
+  padSeq,
+  replayQueryInput,
+  snapshotKey,
+  snapshotItem,
+  decodeSnapshotItem,
+  exnMessage,
+  latestSnapshot,
+  writeSnapshot,
   replayStream,
   replay,
   appendStream,

package/src/util/Util_DynamoDbStream_Runtime.res

@@ -4,9 +4,10 @@ type result =
   | NewAndOldImage(string, JSON.t, JSON.t)
   | Invalid
 
-// Returns None for rows that aren't events — e.g. DCB FENCE rows (no `event`
-// column). The caller filters these out via `Invalid` rather than synthesising
-// a bogus event that sury would later reject.
+// Returns None for rows that aren't events — e.g. DCB FENCE rows and aggregate
+// snapshot rows (position = "SNAPSHOT"; docs/plans/aggregate-snapshotting.md),
+// neither of which has an `event` column. The caller filters these out via
+// `Invalid` rather than synthesising a bogus event that sury would later reject.
 let buildJsonEvent' = dict => {
   switch (dict->Dict.get("event"), dict->Dict.get("data")) {
   | (Some(JSON.String(eventType)), data) =>

package/tests/EventLogStorage_DynamoDb_RuntimeTest.res

@@ -17,9 +17,10 @@ describe("Runtime.append", () => {
     let jsons = Array.fromInitializer(~length=101, mkJson)
     let result = await Runtime.append(table)(0, "test-id", jsons)
     switch result {
-    | Error(msg) =>
+    | Error(ReventlessCore.EventLog.StorageFailure(msg)) =>
       expect(msg->String.includes("max 100 events per command"))->toBe(true)
       expect(msg->String.includes("101"))->toBe(true)
+    | Error(Conflict) => expect("expected StorageFailure, got Conflict")->toBe("")
     | Ok(_) => expect("expected Error, got Ok")->toBe("")
     }
   })
@@ -55,3 +56,69 @@ describe("Runtime.buildTransactItems", () => {
     expect(items->Array.length)->toBe(0)
   })
 })
+
+// ─── Aggregate snapshots (docs/plans/aggregate-snapshotting.md) ───
+
+describe("Runtime.replayQueryInput", () => {
+  testSync("default bounds cover exactly the zero-padded event range", () => {
+    let input = Runtime.replayQueryInput(table.name, "agg-1")
+    expect(input.tableName)->toBe("TestTable")
+    expect(input.consistentRead)->toEqual(Some(true))
+    expect(input.keyConditionExpression)->toEqual(Some("id=:id AND #p BETWEEN :from AND :to"))
+    expect(input.expressionAttributeNames->Option.flatMap(Dict.get(_, "#p")))->toEqual(
+      Some("position"),
+    )
+    let values = input.expressionAttributeValues->Option.getOr(Dict.make())
+    expect(values->Dict.get(":from"))->toEqual(Some(JSON.Encode.string("000000000")))
+    expect(values->Dict.get(":to"))->toEqual(Some(JSON.Encode.string("999999999")))
+  })
+
+  testSync("fromSeq narrows the lower bound to the padded position", () => {
+    let input = Runtime.replayQueryInput(table.name, "agg-1", ~fromSeq=42)
+    let values = input.expressionAttributeValues->Option.getOr(Dict.make())
+    expect(values->Dict.get(":from"))->toEqual(Some(JSON.Encode.string("000000042")))
+  })
+
+  testSync("the snapshot sentinel sorts outside the event range", () => {
+    // DynamoDB compares string range keys lexicographically; the BETWEEN upper
+    // bound excludes the snapshot row because "S" > "9".
+    expect(Runtime.snapshotPosition > Runtime.maxEventPosition)->toBe(true)
+    // And every padded event position stays inside the bounds.
+    expect(Runtime.padSeq(0) >= "000000000" && Runtime.padSeq(0) <= "999999999")->toBe(true)
+    expect(Runtime.padSeq(999999999) <= "999999999")->toBe(true)
+  })
+})
+
+describe("Runtime snapshot item codec", () => {
+  let snap: ReventlessCore.EventLog.snapshot = {
+    seqNr: 50,
+    state: JSON.Encode.object(Dict.fromArray([("names", JSON.Encode.int(3))])),
+    schemaHash: "abc123",
+  }
+
+  testSync("snapshotItem round-trips through decodeSnapshotItem", () => {
+    let item = Runtime.snapshotItem("agg-1", snap)
+    expect(Runtime.decodeSnapshotItem(item))->toEqual(Some(snap))
+    // The item rides the reserved sort key.
+    let d = item->JSON.Decode.object->Option.getOr(Dict.make())
+    expect(d->Dict.get("position"))->toEqual(Some(JSON.Encode.string("SNAPSHOT")))
+    expect(d->Dict.get("id"))->toEqual(Some(JSON.Encode.string("agg-1")))
+  })
+
+  testSync("decodeSnapshotItem rejects a malformed item", () => {
+    let bad =
+      [("id", JSON.Encode.string("agg-1")), ("seqNr", JSON.Encode.string("not-a-number"))]
+      ->Dict.fromArray
+      ->JSON.Encode.object
+    expect(Runtime.decodeSnapshotItem(bad))->toEqual(None)
+  })
+
+  testSync("a snapshot row never reaches the event stream feed", () => {
+    // The DynamoDB stream decoder drops rows without an `event` column (same
+    // mechanism that filters DCB FENCE rows), so snapshot writes are invisible
+    // to event collectors.
+    let asDict =
+      Runtime.snapshotItem("agg-1", snap)->JSON.Decode.object->Option.getOr(Dict.make())
+    expect(Util_DynamoDbStream_Runtime.buildJsonEvent'(asDict))->toEqual(None)
+  })
+})

package/tests/EventLogStorage_DynamoDb_RuntimeTest.res.mjs

@@ -1,7 +1,9 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 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 Util_DynamoDbStream_Runtime$ReventlessAws from "../src/util/Util_DynamoDbStream_Runtime.res.mjs";
 import * as EventLogStorage_DynamoDb_Runtime$ReventlessAws from "../src/adapter/EventLog/EventLogStorage_DynamoDb_Runtime.res.mjs";
 
 let table = {
@@ -27,8 +29,13 @@ globalThis.describe("Runtime.append", () => {
       return;
     }
     let msg = result._0;
-    globalThis.expect(msg.includes("max 100 events per command")).toBe(true);
-    globalThis.expect(msg.includes("101")).toBe(true);
+    if (typeof msg !== "object") {
+      globalThis.expect("expected StorageFailure, got Conflict").toBe("");
+      return;
+    }
+    let msg$1 = msg._0;
+    globalThis.expect(msg$1.includes("max 100 events per command")).toBe(true);
+    globalThis.expect(msg$1.includes("101")).toBe(true);
   });
 });
 
@@ -58,6 +65,65 @@ globalThis.describe("Runtime.buildTransactItems", () => {
   });
 });
 
+globalThis.describe("Runtime.replayQueryInput", () => {
+  globalThis.test("default bounds cover exactly the zero-padded event range", () => {
+    let input = EventLogStorage_DynamoDb_Runtime$ReventlessAws.replayQueryInput("TestTable", "agg-1", undefined);
+    globalThis.expect(input.TableName).toBe("TestTable");
+    globalThis.expect(input.ConsistentRead).toEqual(true);
+    globalThis.expect(input.KeyConditionExpression).toEqual("id=:id AND #p BETWEEN :from AND :to");
+    globalThis.expect(Stdlib_Option.flatMap(input.ExpressionAttributeNames, __x => __x["#p"])).toEqual("position");
+    let values = Stdlib_Option.getOr(input.ExpressionAttributeValues, {});
+    globalThis.expect(values[":from"]).toEqual("000000000");
+    globalThis.expect(values[":to"]).toEqual("999999999");
+  });
+  globalThis.test("fromSeq narrows the lower bound to the padded position", () => {
+    let input = EventLogStorage_DynamoDb_Runtime$ReventlessAws.replayQueryInput("TestTable", "agg-1", 42);
+    let values = Stdlib_Option.getOr(input.ExpressionAttributeValues, {});
+    globalThis.expect(values[":from"]).toEqual("000000042");
+  });
+  globalThis.test("the snapshot sentinel sorts outside the event range", () => {
+    globalThis.expect(EventLogStorage_DynamoDb_Runtime$ReventlessAws.snapshotPosition > EventLogStorage_DynamoDb_Runtime$ReventlessAws.maxEventPosition).toBe(true);
+    globalThis.expect(EventLogStorage_DynamoDb_Runtime$ReventlessAws.padSeq(0) >= "000000000" && EventLogStorage_DynamoDb_Runtime$ReventlessAws.padSeq(0) <= "999999999").toBe(true);
+    globalThis.expect(EventLogStorage_DynamoDb_Runtime$ReventlessAws.padSeq(999999999) <= "999999999").toBe(true);
+  });
+});
+
+globalThis.describe("Runtime snapshot item codec", () => {
+  let snap_state = Object.fromEntries([[
+      "names",
+      3
+    ]]);
+  let snap = {
+    seqNr: 50,
+    state: snap_state,
+    schemaHash: "abc123"
+  };
+  globalThis.test("snapshotItem round-trips through decodeSnapshotItem", () => {
+    let item = EventLogStorage_DynamoDb_Runtime$ReventlessAws.snapshotItem("agg-1", snap);
+    globalThis.expect(EventLogStorage_DynamoDb_Runtime$ReventlessAws.decodeSnapshotItem(item)).toEqual(snap);
+    let d = Stdlib_Option.getOr(Stdlib_JSON.Decode.object(item), {});
+    globalThis.expect(d["position"]).toEqual("SNAPSHOT");
+    globalThis.expect(d["id"]).toEqual("agg-1");
+  });
+  globalThis.test("decodeSnapshotItem rejects a malformed item", () => {
+    let bad = Object.fromEntries([
+      [
+        "id",
+        "agg-1"
+      ],
+      [
+        "seqNr",
+        "not-a-number"
+      ]
+    ]);
+    globalThis.expect(EventLogStorage_DynamoDb_Runtime$ReventlessAws.decodeSnapshotItem(bad)).toEqual(undefined);
+  });
+  globalThis.test("a snapshot row never reaches the event stream feed", () => {
+    let asDict = Stdlib_Option.getOr(Stdlib_JSON.Decode.object(EventLogStorage_DynamoDb_Runtime$ReventlessAws.snapshotItem("agg-1", snap)), {});
+    globalThis.expect(Util_DynamoDbStream_Runtime$ReventlessAws.buildJsonEvent$p(asDict)).toEqual(undefined);
+  });
+});
+
 let Runtime;
 
 export {