@reventlessdev/reventless-aws 3.0.0-alpha.266 → 3.0.0-alpha.268

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.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
+
+* **admin:** serve the complete plugin structure to developer tooling ([e99cda0](https://github.com/ReventlessDev/reventless-core/commit/e99cda02a2f862b36bcfdb018a0fb34bb7426a2b))
+
+
 # 3.0.0-alpha.266 (2026-08-04)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.266",
+  "version": "3.0.0-alpha.268",
   "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-node": "2.0.0-alpha.1",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.65",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.66",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.211",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.126",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.100",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.127",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.213",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.75"
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.77",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.101"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/Platform.res

@@ -1452,6 +1452,7 @@ module MakeWithConfig = (
         ~api=platformApi,
         ~pluginReadModelTableName=tableName,
         ~offloadBucketName,
+        ~schemaReady=admin.adminSchemaPushed,
         ~opts={},
       )
     | None => ()

package/src/Platform.res.mjs

@@ -861,7 +861,7 @@ function MakeWithConfig(Config) {
     Pulumi$Pulumi.$$export("offloadBucket", offloadBucketName);
     if (pluginReadModelTableName !== undefined) {
       AggregateRuntime_Builder_Single$ReventlessAws.setPluginReadModelTable(pluginReadModelTableName);
-      Platform_ComponentDefinitions_Lambda$ReventlessAws.make(platformApi, pluginReadModelTableName, offloadBucketName, {});
+      Platform_ComponentDefinitions_Lambda$ReventlessAws.make(platformApi, pluginReadModelTableName, offloadBucketName, admin.adminSchemaPushed, {});
     }
     let rm = admin.stateViewSlicesOutputs["UiFragments"];
     if (rm !== undefined) {
@@ -2096,7 +2096,7 @@ function Make($star) {
     Pulumi$Pulumi.$$export("offloadBucket", offloadBucketName);
     if (pluginReadModelTableName !== undefined) {
       AggregateRuntime_Builder_Single$ReventlessAws.setPluginReadModelTable(pluginReadModelTableName);
-      Platform_ComponentDefinitions_Lambda$ReventlessAws.make(platformApi, pluginReadModelTableName, offloadBucketName, {});
+      Platform_ComponentDefinitions_Lambda$ReventlessAws.make(platformApi, pluginReadModelTableName, offloadBucketName, admin.adminSchemaPushed, {});
     }
     let rm = admin.stateViewSlicesOutputs["UiFragments"];
     if (rm !== undefined) {

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda.res

@@ -24,10 +24,29 @@ export function response(ctx) {
 }
 `->Pulumi.Input.make
 
+// `Platform_PluginStructures` — the same scan, unfiltered. The `complete` flag is
+// the whole difference; see the handler's `toEntryWith`.
+let completeResolverCode = `
+import { util } from '@aws-appsync/utils';
+export function request(ctx) {
+  return { operation: 'Invoke', payload: { complete: true } };
+}
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
+  return ctx.result;
+}
+`->Pulumi.Input.make
+
 let make = (
   ~api: Pulumi.Output.t<AppSync.GraphQLApi.t>,
   ~pluginReadModelTableName: Pulumi.Output.t<string>,
   ~offloadBucketName: Pulumi.Output.t<string>,
+  // Resolves once the admin schema push is ACTIVE (Platform_Admin.adminSchemaPushed).
+  // Only the `Platform_PluginStructures` resolver is gated on it: that field is new,
+  // so CreateResolver would otherwise race StartSchemaCreation on the deploy that
+  // first ships it. `Platform_ComponentDefinitions` predates the gate and is left
+  // ungated so this change adds no dependency edge to an already-deployed resource.
+  ~schemaReady: Pulumi.Output.t<unit>,
   ~opts: Pulumi.ComponentResource.options,
 ) => {
   let opts = opts->ReventlessCore.Util.Pulumi.ComponentResourceOptions.toCustomResourceOptions
@@ -215,4 +234,21 @@ let make = (
     ~code=resolverCode,
     ~opts,
   )
+
+  // Second field, same DataSource and same Lambda — the developer-tooling read of
+  // the identical scan. Sharing the data source is what keeps the two answers from
+  // drifting: there is one place that decides what a deployed plugin's structure is.
+  // Created only after the schema carrying `Platform_PluginStructures` is ACTIVE.
+  let _structuresResolver =
+    schemaReady->Pulumi.Output.apply(() =>
+      AppSync_Resolver_Native.makeUnitJsResolver(
+        ~name=name ++ "StructuresResolver",
+        ~api,
+        ~dataSourceName=dataSource.name->Pulumi.Output.asInput,
+        ~type_="Query"->Pulumi.Input.make,
+        ~field="Platform_PluginStructures"->Pulumi.Input.make,
+        ~code=completeResolverCode,
+        ~opts,
+      )
+    )
 }

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda.res.mjs

@@ -27,7 +27,18 @@ export function response(ctx) {
 }
 `;
 
-function make(api, pluginReadModelTableName, offloadBucketName, opts) {
+let completeResolverCode = `
+import { util } from '@aws-appsync/utils';
+export function request(ctx) {
+  return { operation: 'Invoke', payload: { complete: true } };
+}
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
+  return ctx.result;
+}
+`;
+
+function make(api, pluginReadModelTableName, offloadBucketName, schemaReady, opts) {
   let opts$1 = Util_Pulumi$ReventlessCore.ComponentResourceOptions.toCustomResourceOptions(opts);
   let name = "PlatformUIDefinitions";
   let lambdaRole = IAM$PulumiAws.Role.makeWithDefaultPolicy(name + "Lambda", Pulumi.output(AWS$ReventlessAws.Lambda.principal), AWS_Tags$ReventlessAws.make(name + "Lambda", "Platform", "Identity", "Platform", undefined, undefined, undefined, undefined), opts$1);
@@ -131,10 +142,12 @@ function make(api, pluginReadModelTableName, offloadBucketName, opts) {
     serviceRoleArn: dataSourceRole.arn
   }, opts$1);
   AppSync_Resolver_Native$ReventlessAws.makeUnitJsResolver(name + "Resolver", api, dataSource.name, "Query", "Platform_ComponentDefinitions", resolverCode, opts$1);
+  schemaReady.apply(() => AppSync_Resolver_Native$ReventlessAws.makeUnitJsResolver(name + "StructuresResolver", api, dataSource.name, "Query", "Platform_PluginStructures", completeResolverCode, opts$1));
 }
 
 export {
   resolverCode,
+  completeResolverCode,
   make,
 }
 /* @pulumi/aws Not a pure module */

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda_Ops.res

@@ -43,11 +43,21 @@ let filterStructure = (structure: JSON.t): option<dict<JSON.t>> =>
     Some(out)
   }
 
-// `{pluginId: name, ...filterStructure(structure)}` — pluginId first so the
-// structure's fields win on the (never-expected) key collision, matching the JS
-// spread. Drops a row with no decodable structure (former `!item.structure`).
-let toEntry = (item: dict<JSON.t>, ~name: string): option<JSON.t> =>
-  switch item->Dict.get("structure")->Option.flatMap(filterStructure) {
+// `{pluginId: name, ...structure}` — pluginId first so the structure's fields win
+// on the (never-expected) key collision, matching the JS spread. Drops a row with
+// no decodable structure (former `!item.structure`).
+//
+// `~filter` is what separates the two fields this handler serves: AutoUI
+// (`Platform_ComponentDefinitions`) gets the public-queryable subset, developer
+// tooling (`Platform_PluginStructures`) gets the structure exactly as persisted,
+// including Internal components and the producer-side `extensionPoints` that the
+// AutoUI entry type does not declare.
+let toEntryWith = (~filter: bool, item: dict<JSON.t>, ~name: string): option<JSON.t> => {
+  let structure =
+    item
+    ->Dict.get("structure")
+    ->Option.flatMap(s => filter ? filterStructure(s) : s->JSON.Decode.object)
+  switch structure {
   | None => None
   | Some(structureObj) =>
     let entry = Dict.make()
@@ -55,10 +65,17 @@ let toEntry = (item: dict<JSON.t>, ~name: string): option<JSON.t> =>
     structureObj->Dict.toArray->Array.forEach(((k, v)) => entry->Dict.set(k, v))
     Some(JSON.Encode.object(entry))
   }
+}
+
 
 // The built-in Platform_Admin entry, injected at deploy time as the
 // ADMIN_ENTRY_JSON env var (the admin never Connects to itself, so its structure
 // never enters the Plugin read model).
+//
+// Shared by both fields. The admin structure has no Internal components and no
+// extension points, so its filtered and complete encodings carry the same
+// components; the structure-level fields the complete entry adds are absent from
+// this JSON and resolve to null, which is what `extensionPoints: None` means.
 let adminEntry: option<JSON.t> =
   switch NodeProcess.env->Dict.get("ADMIN_ENTRY_JSON") {
   | Some(s) if s != "" => Some(JSON.parseOrThrow(s))
@@ -94,7 +111,21 @@ let resolveStructure = (
     }
   }
 
-let handler = async (_event: JSON.t): array<JSON.t> => {
+// One Lambda serves both fields — the scan, the offload resolution and the
+// latest-version-per-plugin collapse are identical work, and duplicating them into
+// a second function would mean a second cold start and a second chance for the two
+// to disagree about what "the deployed structure" is. The resolver for
+// `Platform_PluginStructures` invokes with `{complete: true}`.
+let isComplete = (event: JSON.t): bool =>
+  event
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get("complete"))
+  ->Option.flatMap(JSON.Decode.bool)
+  ->Option.getOr(false)
+
+let handler = async (event: JSON.t): array<JSON.t> => {
+  let complete = isComplete(event)
+  let toEntry = (item, ~name) => toEntryWith(~filter=!complete, item, ~name)
   let admin = adminEntry->Option.mapOr([], e => [e])
   switch NodeProcess.env->Dict.get("PLUGIN_RM_TABLE") {
   | None | Some("") =>

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda_Ops.res.mjs

@@ -31,14 +31,20 @@ function filterStructure(structure) {
   return out;
 }
 
-function toEntry(item, name) {
-  let structureObj = Stdlib_Option.flatMap(item["structure"], filterStructure);
-  if (structureObj === undefined) {
+function toEntryWith(filter, item, name) {
+  let structure = Stdlib_Option.flatMap(item["structure"], s => {
+    if (filter) {
+      return filterStructure(s);
+    } else {
+      return Stdlib_JSON.Decode.object(s);
+    }
+  });
+  if (structure === undefined) {
     return;
   }
   let entry = {};
   entry["pluginId"] = name;
-  Object.entries(structureObj).forEach(param => {
+  Object.entries(structure).forEach(param => {
     entry[param[0]] = param[1];
   });
   return entry;
@@ -65,7 +71,13 @@ function resolveStructure(fetch, item) {
   }
 }
 
-async function handler(_event) {
+function isComplete(event) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(event), o => o["complete"]), Stdlib_JSON.Decode.bool), false);
+}
+
+async function handler(event) {
+  let complete = isComplete(event);
+  let toEntry = (item, name) => toEntryWith(!complete, item, name);
   let admin = Stdlib_Option.mapOr(adminEntry, [], e => [e]);
   let table = process.env["PLUGIN_RM_TABLE"];
   if (table !== undefined) {
@@ -94,9 +106,10 @@ export {
   str,
   isPublicQueryable,
   filterStructure,
-  toEntry,
+  toEntryWith,
   adminEntry,
   resolveStructure,
+  isComplete,
   handler,
 }
 /* s Not a pure module */

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() }),
+    ),
+  }));
+}