@reventlessdev/reventless-aws 3.0.0-alpha.267 → 3.0.0-alpha.269

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.269 (2026-08-07)
+
+### Features
+
+* **core,aws:** add the EventLogProvisioning seam for out-of-tree consumers ([82477b3](https://github.com/ReventlessDev/reventless-core/commit/82477b38c1ef90fbe3a6f4a114a9798770329470))
+
+
+# 3.0.0-alpha.268 (2026-08-05)
+
+### Features
+
+* **local,aws:** carry the changed row in the live-update descriptor ([9272e2e](https://github.com/ReventlessDev/reventless-core/commit/9272e2e18e9e1d740f9a2c5aa83eccbcb41feff7))
+* **local:** scoped seed:reset for the local platform ([a4dd003](https://github.com/ReventlessDev/reventless-core/commit/a4dd0033b7d01be23be91bac3f01d38ebeab7d45))
+
+
 # 3.0.0-alpha.267 (2026-08-04)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.267",
+  "version": "3.0.0-alpha.269",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -11,18 +11,18 @@
     "@aws-sdk/s3-request-presigner": "3.970.0",
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.3",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.4",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.65",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.1",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.66",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.126",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.212",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.76",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.100"
+    "@reventlessdev/reventless-core": "3.0.0-alpha.214",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.78",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.101",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.127"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/EventLog/EventLogStorage.res

@@ -1,4 +1,10 @@
-module DynamoDb = EventLogStorage_DynamoDb
+// Classic event-log tables stream unconditionally. A stream costs nothing until it
+// is consumed, and without one the `EventLogProvisioning` seam has nothing to hand
+// a backend for a classic log while DCB logs (which always stream) work — a silent
+// capability difference between two adapters presenting the same port. The
+// non-streaming maker had no callers; `DynamoDb` stays as an alias so out-of-tree
+// references keep compiling.
+module DynamoDb = EventLogStorage_DynamoDbStream
 module DynamoDbStream = EventLogStorage_DynamoDbStream
 module DynamoDb_Runtime = EventLogStorage_DynamoDb_Runtime
 module Postgres = EventLogStorage_Postgres

package/src/adapter/Runtime/StateTopicPublish.mjs

@@ -12,7 +12,9 @@
 //
 // Channel:  /default/{pathSegment(topicName)}/{pathSegment(entityKey)}
 // Descriptor: { changeKind: "Updated" | "Removed", id: <entityKey>,
-//               sortKeyValue?: <updatedAt | createdAt if present> }
+//               sortKeyValue?: <updatedAt | createdAt if present>,
+//               seq: <monotonic ordering token>,
+//               state?: <the full new row, saves only> }
 //
 // changeKind is fixed per operation (save→"Updated", delete→"Removed"): a
 // Postgres upsert doesn't distinguish insert vs update, and the Sqlite/InMemory
@@ -64,8 +66,8 @@ function pathSegment(value) {
 }
 
 // Pick the natural sort timestamp from the saved state (updatedAt preferred,
-// createdAt fallback). Mirrors StateTopic_AppSync.pickSortKeyValue and
-// LocalBus.pickSortKeyValue.
+// createdAt fallback). Mirrors StateTopic_AppSync_Ops.pickSortKeyValue and
+// LocalStateChangeDescriptor.pickSortKeyValue.
 function pickSortKeyValue(state) {
   if (state && typeof state === "object" && !Array.isArray(state)) {
     if (typeof state.updatedAt === "string") return state.updatedAt;
@@ -74,21 +76,62 @@ function pickSortKeyValue(state) {
   return undefined;
 }
 
+// Cap on the serialised state payload, in characters. Must match
+// LocalStateChangeDescriptor.maxStateChars and StateTopic_AppSync_Ops.maxStateChars
+// — see the local module for the reasoning.
+const MAX_STATE_CHARS = 60 * 1024;
+
+// Monotonic ordering token, seeded from the wall clock so it keeps rising across
+// container restarts. Per Lambda instance: two instances writing the same entity
+// within one millisecond have no defined order. This is an ordering hint, not a
+// lock, and it is sparse — the client rule is "greater than what I hold", never
+// "exactly one more". See docs/analysis/live-update-descriptor-sequencing.md.
+let lastSequence = 0;
+export function nextSequence() {
+  const now = Date.now();
+  lastSequence = now > lastSequence ? now : lastSequence + 1;
+  return String(lastSequence);
+}
+
+// Assemble the descriptor. `state` is the full new row for a save, undefined for a
+// delete — which carries neither `state` nor `sortKeyValue`, matching the other two
+// implementations. Over the size cap the state is dropped and the downgrade logged:
+// a metadata-only descriptor still tells the client to refetch, where a publish
+// rejected for size would tell it nothing.
+export function makeDescriptor({ changeKind, entityKey, state, seq }) {
+  const descriptor = { changeKind, id: entityKey };
+  if (state !== undefined) {
+    const sortKeyValue = pickSortKeyValue(state);
+    if (sortKeyValue !== undefined) descriptor.sortKeyValue = sortKeyValue;
+  }
+  descriptor.seq = seq;
+  if (state !== undefined) {
+    const encoded = JSON.stringify(state);
+    if (encoded.length <= MAX_STATE_CHARS) {
+      descriptor.state = state;
+    } else {
+      console.warn(
+        "STATE_PAYLOAD_DOWNGRADED id=" + entityKey + " chars=" + encoded.length,
+      );
+    }
+  }
+  return descriptor;
+}
+
 // Build the descriptor + channel and POST to {endpoint}/event.
 // - endpoint:   base AppSync Events HTTP endpoint (no trailing /event).
 // - region:     AWS region for the SigV4 credential scope.
 // - topicName:  the plugin-prefixed query LIST field name (channel root).
 // - entityKey:  ORIGINAL entity key (id or `id-subKey`) — descriptor body + path.
 // - changeKind: "Updated" (save) | "Removed" (delete).
-// - sortKeyValue: optional; included when defined.
+// - state:      the full new row for a save; omitted for a delete.
 // - dedupeId:   AppSync publish `id` (idempotency hint).
-export async function publishStateChange({ endpoint, region, topicName, entityKey, changeKind, sortKeyValue, dedupeId }) {
+export async function publishStateChange({ endpoint, region, topicName, entityKey, changeKind, state, dedupeId }) {
   if (!endpoint || !topicName) return; // not live-enabled — no-op
   try {
     const url = new URL(endpoint);
     const channel = "/default/" + pathSegment(topicName) + "/" + pathSegment(entityKey);
-    const descriptor = { changeKind, id: entityKey };
-    if (sortKeyValue !== undefined) descriptor.sortKeyValue = sortKeyValue;
+    const descriptor = makeDescriptor({ changeKind, entityKey, state, seq: nextSequence() });
     const body = JSON.stringify({
       id: dedupeId || (topicName + ":" + entityKey + ":" + changeKind),
       channel,
@@ -154,7 +197,7 @@ export function withLiveUpdates(ops, liveConfig) {
       endpoint, region, topicName,
       entityKey: entityKeyFor(id, state, subIdField),
       changeKind: "Updated",
-      sortKeyValue: pickSortKeyValue(state),
+      state,
     });
 
   const publishRemovedKey = async (entityKey) =>

package/src/adapter/StateTopic/StateTopic_AppSync_Ops.res

@@ -6,9 +6,16 @@
 //
 // Triggered by DynamoDB streams (one shared Lambda; routing is per-record via
 // STATE_TOPIC_MAP). For each changed row it derives the entity channel and a
-// `{changeKind, id, sortKeyValue?}` descriptor and publishes it. 4xx failures
-// are logged and skipped; 5xx / network failures are recorded and rethrown after
-// the batch so the EventSourceMapping retries (bisectBatchOnFunctionError).
+// `{changeKind, id, sortKeyValue?, seq, state?}` descriptor and publishes it. 4xx
+// failures are logged and skipped; 5xx / network failures are recorded and
+// rethrown after the batch so the EventSourceMapping retries
+// (bisectBatchOnFunctionError).
+//
+// The descriptor is one of three implementations of a shared wire format (the
+// others: `LocalStateChangeDescriptor` in reventless-local, `StateTopicPublish.mjs`
+// for Postgres read models). They share no code — this module stays Pulumi-free so
+// a core import can't drag deploy-time code into the Lambda's import graph — so
+// `StateChangeDescriptorParityTest` drives all three and asserts they agree.
 
 
 let endpoint = NodeProcess.env->Dict.get("APPSYNC_ENDPOINT")->Option.getOr("")
@@ -31,6 +38,10 @@ type streamRecord = {
   @as("Keys") keys: dict<attributeValue>,
   @as("NewImage") newImage?: dict<attributeValue>,
   @as("OldImage") oldImage?: dict<attributeValue>,
+  // Monotonic within the entity's shard lineage — records for one partition key
+  // always land on the same shard — so it orders an entity's changes without
+  // anything being written to the table. Sparse, so it detects staleness, not gaps.
+  @as("SequenceNumber") sequenceNumber?: string,
 }
 type record = {
   eventID: string,
@@ -103,6 +114,52 @@ let pickSortKeyValue = (image: dict<JSON.t>): option<string> =>
   | None => image->Dict.get("createdAt")->Option.flatMap(JSON.Decode.string)
   }
 
+/** Cap on the serialised state payload, in characters. Must match
+    `LocalStateChangeDescriptor.maxStateChars` and `StateTopicPublish.mjs`'s
+    MAX_STATE_CHARS — see the local module for the reasoning. */
+let maxStateChars = 60 * 1024
+
+/** Build the change descriptor. Split out of `processRecord` so the wire format
+    can be asserted against the other two implementations without a network call.
+
+    `image` is the unmarshalled NewImage for a save, the OldImage for a REMOVE.
+    A REMOVE carries neither `state` (there is no new row) nor `sortKeyValue`
+    (a sort position for a deleted row has no consumer, and the other two
+    implementations cannot produce one). */
+let makeDescriptor = (
+  ~changeKind: string,
+  ~entityKey: string,
+  ~image: dict<JSON.t>,
+  ~seq: option<string>,
+): JSON.t => {
+  let removed = changeKind == "Removed"
+  let descriptor = Dict.make()
+  descriptor->Dict.set("changeKind", JSON.Encode.string(changeKind))
+  descriptor->Dict.set("id", JSON.Encode.string(entityKey))
+  if !removed {
+    pickSortKeyValue(image)->Option.forEach(v =>
+      descriptor->Dict.set("sortKeyValue", JSON.Encode.string(v))
+    )
+  }
+  seq->Option.forEach(s => descriptor->Dict.set("seq", JSON.Encode.string(s)))
+  if !removed {
+    let state = image->JSON.Encode.object
+    let encoded = state->JSON.stringify
+    if encoded->String.length <= maxStateChars {
+      descriptor->Dict.set("state", state)
+    } else {
+      // Metadata-only still tells the client to refetch; a publish rejected for
+      // size would tell it nothing at all.
+      Console.warn(
+        `STATE_PAYLOAD_DOWNGRADED id=${entityKey} chars=${encoded
+          ->String.length
+          ->Int.toString}`,
+      )
+    }
+  }
+  descriptor->JSON.Encode.object
+}
+
 // Publish one record; returns Some(errorMessage) on a transient (5xx / network)
 // failure so the caller can rethrow after the batch, None otherwise.
 let processRecord = async (
@@ -129,20 +186,17 @@ let processRecord = async (
         let entityKey = entityKeyFromRecord(dynamodb)
         let channel = `/default/${topicRoot}/${AppSyncEventsSigner_Ops.pathSegment(entityKey)}`
         let unmarshalled: dict<JSON.t> = AwsSdk.DynamoDb_Util_Helpers.unmarshallDict(image)
-        let descriptor = Dict.make()
-        descriptor->Dict.set("changeKind", JSON.Encode.string(changeKindFor(record.eventName)))
-        descriptor->Dict.set("id", JSON.Encode.string(entityKey))
-        pickSortKeyValue(unmarshalled)->Option.forEach(v =>
-          descriptor->Dict.set("sortKeyValue", JSON.Encode.string(v))
+        let descriptor = makeDescriptor(
+          ~changeKind=changeKindFor(record.eventName),
+          ~entityKey,
+          ~image=unmarshalled,
+          ~seq=dynamodb.sequenceNumber,
         )
         let body =
           Dict.fromArray([
             ("id", JSON.Encode.string(record.eventID)),
             ("channel", JSON.Encode.string(channel)),
-            (
-              "events",
-              JSON.Encode.array([JSON.Encode.string(descriptor->JSON.Encode.object->JSON.stringify)]),
-            ),
+            ("events", JSON.Encode.array([JSON.Encode.string(descriptor->JSON.stringify)])),
           ])
           ->JSON.Encode.object
           ->JSON.stringify

package/src/adapter/StateTopic/StateTopic_AppSync_Ops.res.mjs

@@ -89,6 +89,30 @@ function pickSortKeyValue(image) {
   }
 }
 
+function makeDescriptor(changeKind, entityKey, image, seq) {
+  let removed = changeKind === "Removed";
+  let descriptor = {};
+  descriptor["changeKind"] = changeKind;
+  descriptor["id"] = entityKey;
+  if (!removed) {
+    Stdlib_Option.forEach(pickSortKeyValue(image), v => {
+      descriptor["sortKeyValue"] = v;
+    });
+  }
+  Stdlib_Option.forEach(seq, s => {
+    descriptor["seq"] = s;
+  });
+  if (!removed) {
+    let encoded = JSON.stringify(image);
+    if (encoded.length <= 61440) {
+      descriptor["state"] = image;
+    } else {
+      console.warn(`STATE_PAYLOAD_DOWNGRADED id=` + entityKey + ` chars=` + encoded.length.toString());
+    }
+  }
+  return descriptor;
+}
+
 async function processRecord(record, region, creds) {
   let topicRoot = topicRootFromEventSourceArn(record.eventSourceARN);
   if (topicRoot !== undefined) {
@@ -103,12 +127,7 @@ async function processRecord(record, region, creds) {
     let entityKey = entityKeyFromRecord(dynamodb);
     let channel = `/default/` + topicRoot + `/` + AppSyncEventsSigner_Ops$ReventlessAws.pathSegment(entityKey);
     let unmarshalled = DynamoDb_Util_Helpers$AwsSdk.unmarshallDict(undefined, image);
-    let descriptor = {};
-    descriptor["changeKind"] = changeKindFor(record.eventName);
-    descriptor["id"] = entityKey;
-    Stdlib_Option.forEach(pickSortKeyValue(unmarshalled), v => {
-      descriptor["sortKeyValue"] = v;
-    });
+    let descriptor = makeDescriptor(changeKindFor(record.eventName), entityKey, unmarshalled, dynamodb.SequenceNumber);
     let body = JSON.stringify(Object.fromEntries([
       [
         "id",
@@ -169,6 +188,8 @@ async function handler(event) {
   }
 }
 
+let maxStateChars = 61440;
+
 export {
   endpoint,
   topicMap,
@@ -177,6 +198,8 @@ export {
   entityKeyFromRecord,
   changeKindFor,
   pickSortKeyValue,
+  maxStateChars,
+  makeDescriptor,
   processRecord,
   handler,
 }

package/src/util/Util_StoreLayout.res

@@ -138,7 +138,7 @@ machinery: a stack that predates a change to this function empties its stores
 (`seed:reset`, which wipes per plugin) and re-seeds. Carrying a permanent prefix
 set to spare a disposable stack one wipe is the worse trade.
 */
-let keyPrefixFor = (~plugin: string, ~store: string): string => `${plugin}/${store}`
+let keyPrefixFor = ReventlessCore.StoreLayout.keyPrefixFor
 
 /**
 Who serves the declared stores — and the answer is never "both".

package/src/util/Util_StoreLayout.res.mjs

@@ -3,6 +3,7 @@
 import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.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 StoreLayout$ReventlessCore from "@reventlessdev/reventless-core/src/util/StoreLayout.res.mjs";
 
 let defaultEphemeralPrefixes = ["pr-"];
 
@@ -31,10 +32,6 @@ function bucketNameFor(layout, stack, plugin, store) {
   }
 }
 
-function keyPrefixFor(plugin, store) {
-  return plugin + `/` + store;
-}
-
 function servingFor(hasHostUiBundle, declaredBucketCount) {
   if (declaredBucketCount !== 0) {
     if (hasHostUiBundle) {
@@ -81,6 +78,8 @@ function pendingExpiryFor(config, store) {
     })[0];
 }
 
+let keyPrefixFor = StoreLayout$ReventlessCore.keyPrefixFor;
+
 export {
   defaultEphemeralPrefixes,
   layoutFor,

package/tests/StateChangeDescriptorParityTest.res

@@ -0,0 +1,58 @@
+// Parity of the live-update change descriptor across its three implementations:
+//
+//   - LocalStateChangeDescriptor      (reventless-local, both backends)
+//   - StateTopic_AppSync_Ops          (DynamoDB stream relay)
+//   - StateTopicPublish.mjs           (Postgres projection-side publisher)
+//
+// They share no code on purpose — the relay module stays Pulumi-free so a core
+// import can't pull deploy-time code into its Lambda graph — which makes drift
+// the standing risk: three sites, one wire format, and a browser that cannot tell
+// which one produced a frame. This test is the guard.
+//
+// `seq` is normalised away by the harness because the three take it from different
+// monotonic sources by design (a DynamoDB stream SequenceNumber vs a wall-clock
+// counter); the harness still asserts each produced a non-empty string.
+
+open JestGlobals
+
+type case = {
+  name: string,
+  local: JSON.t,
+  relay: JSON.t,
+  postgres: JSON.t,
+}
+
+@module("./stateChangeDescriptorParity.mjs")
+external buildAll: unit => promise<array<case>> = "buildAll"
+
+describe("state-change descriptor parity", () => {
+  testAsync("every implementation builds the same descriptor", async () => {
+    let cases = await buildAll()
+    // A silent zero-case run would pass while asserting nothing.
+    expect(cases->Array.length)->toBe(6)
+    cases->Array.forEach(c => {
+      expect((c.name, c.relay))->toEqual((c.name, c.local))
+      expect((c.name, c.postgres))->toEqual((c.name, c.local))
+    })
+  })
+
+  testAsync("a save carries the row, a delete carries none", async () => {
+    let cases = await buildAll()
+    let stateOf = (d: JSON.t) =>
+      d->JSON.Decode.object->Option.flatMap(o => o->Dict.get("state"))
+    let byName = name => cases->Array.find(c => c.name == name)
+
+    switch byName("single-key save with updatedAt") {
+    | Some(c) => expect(stateOf(c.local)->Option.isSome)->toBe(true)
+    | None => expect("save case missing")->toBe("present")
+    }
+    switch byName("delete carries no row") {
+    | Some(c) => expect(stateOf(c.local))->toEqual(None)
+    | None => expect("delete case missing")->toBe("present")
+    }
+    switch byName("oversized row degrades to metadata only") {
+    | Some(c) => expect(stateOf(c.local))->toEqual(None)
+    | None => expect("oversized case missing")->toBe("present")
+    }
+  })
+})

package/tests/StateChangeDescriptorParityTest.res.mjs

@@ -0,0 +1,60 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as StateChangeDescriptorParityMjs from "./stateChangeDescriptorParity.mjs";
+
+function buildAll(prim) {
+  return StateChangeDescriptorParityMjs.buildAll();
+}
+
+globalThis.describe("state-change descriptor parity", () => {
+  globalThis.test("every implementation builds the same descriptor", async () => {
+    let cases = await StateChangeDescriptorParityMjs.buildAll();
+    globalThis.expect(cases.length).toBe(6);
+    cases.forEach(c => {
+      globalThis.expect([
+        c.name,
+        c.relay
+      ]).toEqual([
+        c.name,
+        c.local
+      ]);
+      globalThis.expect([
+        c.name,
+        c.postgres
+      ]).toEqual([
+        c.name,
+        c.local
+      ]);
+    });
+  });
+  globalThis.test("a save carries the row, a delete carries none", async () => {
+    let cases = await StateChangeDescriptorParityMjs.buildAll();
+    let stateOf = d => Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(d), o => o["state"]);
+    let byName = name => cases.find(c => c.name === name);
+    let c = byName("single-key save with updatedAt");
+    if (c !== undefined) {
+      globalThis.expect(Stdlib_Option.isSome(stateOf(c.local))).toBe(true);
+    } else {
+      globalThis.expect("save case missing").toBe("present");
+    }
+    let c$1 = byName("delete carries no row");
+    if (c$1 !== undefined) {
+      globalThis.expect(stateOf(c$1.local)).toEqual(undefined);
+    } else {
+      globalThis.expect("delete case missing").toBe("present");
+    }
+    let c$2 = byName("oversized row degrades to metadata only");
+    if (c$2 !== undefined) {
+      globalThis.expect(stateOf(c$2.local)).toEqual(undefined);
+    } else {
+      globalThis.expect("oversized case missing").toBe("present");
+    }
+  });
+});
+
+export {
+  buildAll,
+}
+/*  Not a pure module */

package/tests/StateTopicPublishTest.res

@@ -17,9 +17,14 @@ open JestGlobals
 let run: string => promise<JSON.t> = %raw(`
 async function(scenario) {
   const mod = await import("../src/adapter/Runtime/StateTopicPublish.mjs");
-  const { withLiveUpdates } = mod;
+  const { withLiveUpdates, makeDescriptor } = mod;
   const captured = [];
-  const publish = async (call) => { captured.push(call); };
+  // Record the descriptor the real publisher would build alongside the call, with
+  // a fixed seq so assertions stay deterministic. sortKeyValue/state derivation
+  // lives in makeDescriptor, so this keeps it under test at the wrapper level.
+  const publish = async (call) => {
+    captured.push({ ...call, descriptor: makeDescriptor({ ...call, seq: "1" }) });
+  };
   const ok = async () => ({ TAG: "Ok", _0: undefined });
 
   // Mock ops. load returns the composite partition's rows for the enumerate case.
@@ -53,6 +58,9 @@ async function(scenario) {
     case "save-no-sortkey":
       await w(undefined).save("p1", { id: "p1" }, "Insert", undefined);
       break;
+    case "save-oversized":
+      await w(undefined).save("p1", { id: "p1", blob: "x".repeat(70 * 1024) }, "Insert", undefined);
+      break;
     case "saveBatch":
       await w(undefined).saveBatch([
         ["a", { id: "a", updatedAt: "t1" }, undefined],
@@ -86,6 +94,11 @@ let getField = (call: JSON.t, key: string): option<JSON.t> =>
 
 let str = (call, key) => getField(call, key)->Option.flatMap(JSON.Decode.string)
 
+let descriptorField = (call: JSON.t, key: string): option<JSON.t> =>
+  getField(call, "descriptor")->Option.flatMap(d => getField(d, key))
+
+let descriptorStr = (call, key) => descriptorField(call, key)->Option.flatMap(JSON.Decode.string)
+
 let calls = (j: JSON.t): array<JSON.t> => j->JSON.Decode.array->Option.getOr([])
 
 describe("withLiveUpdates (B3.3a Postgres live updates)", () => {
@@ -96,8 +109,11 @@ describe("withLiveUpdates (B3.3a Postgres live updates)", () => {
     let call = arr->Array.getUnsafe(0)
     expect(str(call, "entityKey"))->toEqual(Some("p1"))
     expect(str(call, "changeKind"))->toEqual(Some("Updated"))
-    expect(str(call, "sortKeyValue"))->toEqual(Some("2024-01-02"))
+    expect(descriptorStr(call, "sortKeyValue"))->toEqual(Some("2024-01-02"))
     expect(str(call, "topicName"))->toEqual(Some("Shop_Orders"))
+    // The saved row rides along so a subscriber can apply it without refetching.
+    expect(descriptorField(call, "state"))->toEqual(getField(call, "state"))
+    expect(descriptorStr(call, "seq"))->toEqual(Some("1"))
   })
 
   testAsync("save on a composite table uses id-subKey and createdAt fallback", async () => {
@@ -105,13 +121,21 @@ describe("withLiveUpdates (B3.3a Postgres live updates)", () => {
     let call = calls(c)->Array.getUnsafe(0)
     expect(str(call, "entityKey"))->toEqual(Some("o1-L2"))
     expect(str(call, "changeKind"))->toEqual(Some("Updated"))
-    expect(str(call, "sortKeyValue"))->toEqual(Some("2024-03-04"))
+    expect(descriptorStr(call, "sortKeyValue"))->toEqual(Some("2024-03-04"))
   })
 
   testAsync("save without updatedAt/createdAt omits sortKeyValue", async () => {
     let c = await run("save-no-sortkey")
     let call = calls(c)->Array.getUnsafe(0)
-    expect(getField(call, "sortKeyValue"))->toEqual(None)
+    expect(descriptorField(call, "sortKeyValue"))->toEqual(None)
+  })
+
+  testAsync("an oversized row degrades to a metadata-only descriptor", async () => {
+    let c = await run("save-oversized")
+    let call = calls(c)->Array.getUnsafe(0)
+    expect(descriptorField(call, "state"))->toEqual(None)
+    expect(descriptorStr(call, "changeKind"))->toEqual(Some("Updated"))
+    expect(descriptorStr(call, "seq"))->toEqual(Some("1"))
   })
 
   testAsync("saveBatch publishes one Updated per item", async () => {

package/tests/StateTopicPublishTest.res.mjs

@@ -5,9 +5,14 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let run = (async function(scenario) {
   const mod = await import("../src/adapter/Runtime/StateTopicPublish.mjs");
-  const { withLiveUpdates } = mod;
+  const { withLiveUpdates, makeDescriptor } = mod;
   const captured = [];
-  const publish = async (call) => { captured.push(call); };
+  // Record the descriptor the real publisher would build alongside the call, with
+  // a fixed seq so assertions stay deterministic. sortKeyValue/state derivation
+  // lives in makeDescriptor, so this keeps it under test at the wrapper level.
+  const publish = async (call) => {
+    captured.push({ ...call, descriptor: makeDescriptor({ ...call, seq: "1" }) });
+  };
   const ok = async () => ({ TAG: "Ok", _0: undefined });
 
   // Mock ops. load returns the composite partition's rows for the enumerate case.
@@ -41,6 +46,9 @@ let run = (async function(scenario) {
     case "save-no-sortkey":
       await w(undefined).save("p1", { id: "p1" }, "Insert", undefined);
       break;
+    case "save-oversized":
+      await w(undefined).save("p1", { id: "p1", blob: "x".repeat(70 * 1024) }, "Insert", undefined);
+      break;
     case "saveBatch":
       await w(undefined).saveBatch([
         ["a", { id: "a", updatedAt: "t1" }, undefined],
@@ -76,6 +84,14 @@ function str(call, key) {
   return Stdlib_Option.flatMap(getField(call, key), Stdlib_JSON.Decode.string);
 }
 
+function descriptorField(call, key) {
+  return Stdlib_Option.flatMap(getField(call, "descriptor"), d => getField(d, key));
+}
+
+function descriptorStr(call, key) {
+  return Stdlib_Option.flatMap(descriptorField(call, key), Stdlib_JSON.Decode.string);
+}
+
 function calls(j) {
   return Stdlib_Option.getOr(Stdlib_JSON.Decode.array(j), []);
 }
@@ -88,20 +104,29 @@ globalThis.describe("withLiveUpdates (B3.3a Postgres live updates)", () => {
     let call = arr[0];
     globalThis.expect(str(call, "entityKey")).toEqual("p1");
     globalThis.expect(str(call, "changeKind")).toEqual("Updated");
-    globalThis.expect(str(call, "sortKeyValue")).toEqual("2024-01-02");
+    globalThis.expect(descriptorStr(call, "sortKeyValue")).toEqual("2024-01-02");
     globalThis.expect(str(call, "topicName")).toEqual("Shop_Orders");
+    globalThis.expect(descriptorField(call, "state")).toEqual(getField(call, "state"));
+    globalThis.expect(descriptorStr(call, "seq")).toEqual("1");
   });
   globalThis.test("save on a composite table uses id-subKey and createdAt fallback", async () => {
     let c = await run("save-composite");
     let call = calls(c)[0];
     globalThis.expect(str(call, "entityKey")).toEqual("o1-L2");
     globalThis.expect(str(call, "changeKind")).toEqual("Updated");
-    globalThis.expect(str(call, "sortKeyValue")).toEqual("2024-03-04");
+    globalThis.expect(descriptorStr(call, "sortKeyValue")).toEqual("2024-03-04");
   });
   globalThis.test("save without updatedAt/createdAt omits sortKeyValue", async () => {
     let c = await run("save-no-sortkey");
     let call = calls(c)[0];
-    globalThis.expect(getField(call, "sortKeyValue")).toEqual(undefined);
+    globalThis.expect(descriptorField(call, "sortKeyValue")).toEqual(undefined);
+  });
+  globalThis.test("an oversized row degrades to a metadata-only descriptor", async () => {
+    let c = await run("save-oversized");
+    let call = calls(c)[0];
+    globalThis.expect(descriptorField(call, "state")).toEqual(undefined);
+    globalThis.expect(descriptorStr(call, "changeKind")).toEqual("Updated");
+    globalThis.expect(descriptorStr(call, "seq")).toEqual("1");
   });
   globalThis.test("saveBatch publishes one Updated per item", async () => {
     let c = await run("saveBatch");
@@ -153,6 +178,8 @@ export {
   run,
   getField,
   str,
+  descriptorField,
+  descriptorStr,
   calls,
 }
 /* run Not a pure module */

package/tests/stateChangeDescriptorParity.mjs

@@ -0,0 +1,102 @@
+// Harness for StateChangeDescriptorParityTest.
+//
+// The live-update change descriptor has three independent implementations and no
+// shared code (the DynamoDB relay's module is deliberately Pulumi-free, so it
+// cannot import a core builder without risking deploy-time code in its Lambda
+// graph). This harness drives all three through the same logical changes and
+// hands the results back for comparison.
+//
+// Plain ESM rather than ReScript because two of the three modules live outside
+// this package and one is hand-written JS; the assertions stay in the .res test.
+
+const LOCAL = "../../local/src/adapter/LocalStateChangeDescriptor.res.mjs";
+const RELAY = "../src/adapter/StateTopic/StateTopic_AppSync_Ops.res.mjs";
+const POSTGRES = "../src/adapter/Runtime/StateTopicPublish.mjs";
+
+// Each case is one logical change expressed three ways. `changeKind` is already
+// normalised: the three sites derive it differently (local compares against the
+// stored row, the relay maps the stream eventName, Postgres has only upserts), and
+// that derivation is covered by their own tests — what is asserted here is that
+// the same logical change produces the same descriptor.
+const CASES = [
+  {
+    name: "single-key save with updatedAt",
+    changeKind: "Updated",
+    entityKey: "p1",
+    state: { id: "p1", name: "Widget", updatedAt: "2026-05-19T12:00:00Z" },
+  },
+  {
+    name: "composite-key save falling back to createdAt",
+    changeKind: "Updated",
+    entityKey: "o1-L2",
+    state: { id: "o1", lineId: "L2", createdAt: "2026-03-04T08:00:00Z" },
+  },
+  {
+    name: "save with no sort timestamp",
+    changeKind: "Updated",
+    entityKey: "p1",
+    state: { id: "p1", name: "Widget" },
+  },
+  {
+    name: "first save of a key",
+    changeKind: "Added",
+    entityKey: "p2",
+    state: { id: "p2", name: "Gadget", updatedAt: "2026-05-19T12:00:00Z" },
+  },
+  {
+    name: "oversized row degrades to metadata only",
+    changeKind: "Updated",
+    entityKey: "p3",
+    state: { id: "p3", blob: "x".repeat(70 * 1024), updatedAt: "2026-05-19T12:00:00Z" },
+  },
+  {
+    name: "delete carries no row",
+    changeKind: "Removed",
+    entityKey: "p1",
+    state: undefined,
+  },
+];
+
+/**
+ * Build every case with every implementation.
+ *
+ * Returns `[{ name, local, relay, postgres }]`, each descriptor a plain object
+ * with `seq` replaced by the literal "<seq>" — the three sites take their
+ * sequence from different monotonic sources by design (stream SequenceNumber vs
+ * a wall-clock counter), so the values differ while the field's presence and
+ * type must not.
+ */
+export async function buildAll() {
+  const local = await import(LOCAL);
+  const relay = await import(RELAY);
+  const postgres = await import(POSTGRES);
+
+  const normalise = (descriptor) => {
+    const seq = descriptor.seq;
+    if (typeof seq !== "string" || seq.length === 0) {
+      throw new Error("descriptor is missing a string seq: " + JSON.stringify(descriptor));
+    }
+    return { ...descriptor, seq: "<seq>" };
+  };
+
+  return CASES.map(({ name, changeKind, entityKey, state }) => ({
+    name,
+    local: normalise(
+      local.make(changeKind, entityKey, state === undefined ? undefined : state, local.nextSequence()),
+    ),
+    relay: normalise(
+      relay.makeDescriptor(
+        changeKind,
+        entityKey,
+        // The relay unmarshalls the stream image before building the descriptor,
+        // so it takes the same plain row the other two do. A REMOVE is handed the
+        // OldImage, which makeDescriptor then drops.
+        state === undefined ? { id: entityKey } : state,
+        "49590300000000016818000000",
+      ),
+    ),
+    postgres: normalise(
+      postgres.makeDescriptor({ changeKind, entityKey, state, seq: postgres.nextSequence() }),
+    ),
+  }));
+}

package/src/adapter/EventLog/EventLogStorage_DynamoDb.res

@@ -1,27 +0,0 @@
-let make: ReventlessCore.EventLog_Adapter.storageMaker = (~name, ~owner, ~opts) => {
-  let tags = AWS.Tags.make(~name, ~kind=ReventlessCore.EventLog.componentType, ~role=EventLog, ~owner?)
-  let table = Util.DynamoDb.makeTable(
-    name,
-    ~attributes=[{name: "id", type_: "S"}, {name: "position", type_: "S"}],
-    ~rangeKey="position",
-    ~tags,
-    ~opts,
-  )
-
-  {
-    resources: [table->Util_DynamoDb.toResource(~tags=tags->Pulumi.Output.fromInput)],
-    operations: table
-    ->Util_DynamoDb.toResolvedTableOutput
-    ->Pulumi.Output.apply(resolvedTable => {
-      ReventlessCore.EventLog_Adapter.append: EventLogStorage_DynamoDb_Runtime.append(
-        resolvedTable,
-        ...
-      ),
-      replay: EventLogStorage_DynamoDb_Runtime.replay(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

@@ -1,36 +0,0 @@
-// Generated by ReScript, PLEASE EDIT WITH CARE
-
-import * as AWS_Tags$ReventlessAws from "../AWS_Tags.res.mjs";
-import * as EventLog$ReventlessCore from "@reventlessdev/reventless-core/src/components/EventLog/EventLog.res.mjs";
-import * as Util_DynamoDb$ReventlessAws from "../../util/Util_DynamoDb.res.mjs";
-import * as EventLogStorage_DynamoDb_Runtime$ReventlessAws from "./EventLogStorage_DynamoDb_Runtime.res.mjs";
-
-function make(name, owner, opts) {
-  let tags = AWS_Tags$ReventlessAws.make(name, EventLog$ReventlessCore.componentType, "EventLog", undefined, undefined, owner, undefined, undefined);
-  let table = Util_DynamoDb$ReventlessAws.makeTable([
-    {
-      name: "id",
-      type: "S"
-    },
-    {
-      name: "position",
-      type: "S"
-    }
-  ], undefined, undefined, "position", tags, opts, name);
-  return {
-    resources: [Util_DynamoDb$ReventlessAws.toResource(tags, table)],
-    operations: Util_DynamoDb$ReventlessAws.toResolvedTableOutput(table).apply(resolvedTable => ({
-      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),
-      latestSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.latestSnapshot(resolvedTable),
-      writeSnapshot: EventLogStorage_DynamoDb_Runtime$ReventlessAws.writeSnapshot(resolvedTable)
-    }))
-  };
-}
-
-export {
-  make,
-}
-/* AWS_Tags-ReventlessAws Not a pure module */