@reventlessdev/reventless-aws 3.0.0-alpha.177 → 3.0.0-alpha.178

package/src/adapter/Runtime/EventCollectorRuntime_Builder_Single.res.mjs

@@ -11,9 +11,11 @@ import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/co
 import * as DcbBackend$ReventlessAws from "../DcbEventLog/DcbBackend.res.mjs";
 import * as PolicyDocument$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/IAM/PolicyDocument.res.mjs";
 import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.res.mjs";
+import * as PgConnection$ReventlessAws from "../Postgres/PgConnection.res.mjs";
 import * as Util_Pulumi$ReventlessCore from "@reventlessdev/reventless-core/src/util/Util_Pulumi.res.mjs";
 import * as QueryDbBackend$ReventlessAws from "../QueryDb/QueryDbBackend.res.mjs";
 import * as EventLogBackend$ReventlessAws from "../EventLog/EventLogBackend.res.mjs";
+import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_Helpers.res.mjs";
 import * as PgProjectionFeed$ReventlessAws from "../Postgres/PgProjectionFeed.res.mjs";
 import * as RuntimeEnvironment_Lambda$ReventlessAws from "./RuntimeEnvironment_Lambda.res.mjs";
 import * as EventCollectorChannel_DynamoDbStream$ReventlessAws from "../EventCollector/EventCollectorChannel_DynamoDbStream.res.mjs";
@@ -22,6 +24,14 @@ let log = Logger$ReventlessCore.fromEnv();
 
 let readModelInfos = {};
 
+let eventsApiConfig = {
+  contents: undefined
+};
+
+function setEventsApiConfig(cfg) {
+  eventsApiConfig.contents = cfg;
+}
+
 function registerReadModel(readModelName, specModulePath, mappingsModulePath, queryDbTableName, pgBackedOpt) {
   let pgBacked = pgBackedOpt !== undefined ? pgBackedOpt : false;
   readModelInfos[readModelName] = {
@@ -95,31 +105,7 @@ function finish() {
       let feedArnOutput = feedQueue !== undefined ? feedQueue.arn : Pulumi.output("");
       let qdbSelection = QueryDbBackend$ReventlessAws.get();
       let anyPgBacked = Object.values(readModelInfos).some(info => info.pgBacked);
-      let pgConnectionFragment = qdbSelection !== undefined && anyPgBacked ? qdbSelection.connectionConfig.apply(cc => {
-          let pgConnectionJson = JSON.stringify(Object.fromEntries([
-            [
-              "host",
-              cc.host
-            ],
-            [
-              "port",
-              cc.port
-            ],
-            [
-              "database",
-              cc.database
-            ],
-            [
-              "username",
-              cc.username
-            ],
-            [
-              "secretArn",
-              cc.secretArn
-            ]
-          ]));
-          return `,"pgConnection":` + pgConnectionJson;
-        }) : Pulumi.output("");
+      let pgConnectionFragment = qdbSelection !== undefined && anyPgBacked ? qdbSelection.connectionConfig.apply(cc => `,"pgConnection":` + JSON.stringify(PgConnection$ReventlessAws.connectionConfigToJson(undefined, cc))) : Pulumi.output("");
       let handlerOutputs = [];
       let packageDirs = {};
       let sortedSpecs = storedSpecs.toSorted((a, b) => Primitive_string.compare(a.componentName, b.componentName));
@@ -135,6 +121,13 @@ function finish() {
         let specModule = Stdlib_Option.getOr(JSON.stringify(info.specModulePath), `""`);
         let mappingsModule = Stdlib_Option.getOr(JSON.stringify(info.mappingsModulePath), `""`);
         let handlerPgFragment = info.pgBacked ? pgConnectionFragment : Pulumi.output("");
+        let stateTopicFragment;
+        if (info.pgBacked && QueryDbBackend$ReventlessAws.postgresStreamRegistry.has(spec.componentName) && Stdlib_Option.isSome(eventsApiConfig.contents)) {
+          let topic = Stdlib_Option.getOr(Stdlib_Option.map(Plugin_Helpers$ReventlessCore.queryFieldNamesRegistry[spec.componentName], qn => qn.listFieldName), spec.componentName);
+          stateTopicFragment = `,"stateTopicName":` + JSON.stringify(topic);
+        } else {
+          stateTopicFragment = "";
+        }
         let handlerJson = Pulumi.all([
           info.queryDbTableName,
           spec.sourceUrns,
@@ -142,13 +135,24 @@ function finish() {
           handlerPgFragment
         ]).apply(param => {
           let sourceUrn = Stdlib_Option.getOr(param[1][0], param[2]);
-          return `{"specModule":` + specModule + `,"mappingsModule":` + mappingsModule + `,"queryDbTableName":"` + param[0] + `","sourceUrn":"` + sourceUrn + `"` + param[3] + `}`;
+          return `{"specModule":` + specModule + `,"mappingsModule":` + mappingsModule + `,"queryDbTableName":"` + param[0] + `","sourceUrn":"` + sourceUrn + `"` + param[3] + stateTopicFragment + `}`;
         });
         handlerOutputs.push(handlerJson);
       });
       let handlerConfigOutput = Pulumi.all(handlerOutputs).apply(handlers => `{"handlers":[` + handlers.join(",") + `]}`);
       let envVars = {};
       envVars["HANDLER_CONFIG"] = handlerConfigOutput;
+      let anyPgStream = Object.keys(readModelInfos).some(rmName => {
+        if (Stdlib_Option.mapOr(readModelInfos[rmName], false, i => i.pgBacked)) {
+          return QueryDbBackend$ReventlessAws.postgresStreamRegistry.has(rmName);
+        } else {
+          return false;
+        }
+      });
+      let pgStreamConfig = anyPgStream ? eventsApiConfig.contents : undefined;
+      if (pgStreamConfig !== undefined) {
+        envVars["APPSYNC_ENDPOINT"] = pgStreamConfig.endpoint;
+      }
       let match$1 = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/ReadModelEntryPoint.mjs", packageDirs, undefined);
       let vpcConfig = qdbSelection !== undefined && anyPgBacked ? qdbSelection.securityGroupId.apply(sgId => ({
           subnetIds: qdbSelection.subnetIds,
@@ -166,6 +170,17 @@ function finish() {
           role: runtime.parts.lambdaRole.id
         }));
       }
+      if (pgStreamConfig !== undefined) {
+        pgStreamConfig.apiArn.apply(apiArn => new (Aws.iam.RolePolicy)("AllReadModels-appsyncPublish", {
+          policy: PolicyDocument$PulumiAws.toJsonString(PolicyDocument$PulumiAws.make(undefined, "AllReadModels-appsyncPublishPolicy", [{
+              Sid: "AllowPublishAppSyncEvents",
+              Effect: "Allow",
+              Action: "appsync:EventPublish",
+              Resource: apiArn + "/*"
+            }])),
+          role: runtime.parts.lambdaRole.id
+        }));
+      }
       let channelSpecs = storedSpecs.map(param => param.channelSpec);
       EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllReadModels", channelSpecs, runtime, opts);
       if (feedQueue !== undefined) {
@@ -187,6 +202,8 @@ export {
   RuntimeEnvironment,
   log,
   readModelInfos,
+  eventsApiConfig,
+  setEventsApiConfig,
   registerReadModel,
   storedSpecs,
   grandParent,

package/src/adapter/Runtime/PgMigrationEntryPoint.mjs

@@ -0,0 +1,40 @@
+// One-shot Postgres schema-migration Lambda entry point (A3).
+//
+// Invoked once during `pulumi up` by an `aws.lambda.Invocation` resource, from
+// INSIDE the DB's VPC, so the deploy runner needs no network path to a private
+// RDS instance. Runs the exact idempotent `PgSchema.ensureSchema` the local
+// backend runs at startup (reventless-local's `postgres` smart constructor), so
+// the AWS schema is byte-identical to local — zero drift. Every statement is
+// `IF NOT EXISTS`, so re-invocation (e.g. after a schema-DDL change bumps the
+// Lambda layer) is safe.
+//
+// HANDLER_CONFIG shape:
+//   { "pgConnection": { host, port, database, username, secretArn } }
+
+import { poolFor } from "@reventlessdev/reventless-aws/src/adapter/Postgres/PgRuntime.res.mjs";
+import { ensureSchema } from "@reventlessdev/reventless-postgres/src/PgSchema.res.mjs";
+import { log } from "./HandlerFactoryHelpers.mjs";
+
+// Config parse → pool → ensureSchema, with the pool source injectable so the
+// orchestration is integration-testable against a real Postgres without the
+// Secrets Manager round-trip (mirrors PgChangeFeedRelay_Runtime's
+// relayWithPool/relay split). `opts.makePool` defaults to the production `poolFor`.
+export async function runMigration(config, opts = {}) {
+  if (!config.pgConnection) {
+    throw new Error("PgMigrationEntryPoint: HANDLER_CONFIG has no pgConnection");
+  }
+  // `poolFor` memoises one pool per secret ARN per container and resolves the
+  // RDS-managed password from Secrets Manager via a cached provider.
+  const makePool = opts.makePool ?? poolFor;
+  const pool = makePool(config.pgConnection);
+  await ensureSchema(pool);
+  log.info("ensureSchema completed for " + config.pgConnection.database, {
+    comp: "PgMigration",
+  });
+  return "ok";
+}
+
+export async function handler(_event, _context) {
+  const config = JSON.parse(process.env["HANDLER_CONFIG"] || "{}");
+  return runMigration(config);
+}

package/src/adapter/Runtime/ReadModelEntryPoint.mjs

@@ -8,6 +8,7 @@ import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/Req
 import { Make as readModelCallbackMake } from "@reventlessdev/reventless-core/src/components/ReadModel/ReadModel_Callback.res.mjs";
 import { load as qdbLoad, loadStream as qdbLoadStream, save as qdbSave, saveBatch as qdbSaveBatch, count as qdbCount, $$delete as qdbDelete, deleteBatch as qdbDeleteBatch } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_DynamoDb_Runtime.res.mjs";
 import { opsFor as pgQdbOpsFor } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_Postgres_Runtime.res.mjs";
+import { withLiveUpdates } from "./StateTopicPublish.mjs";
 import { handleStreamEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_DynamoDbStream_Runtime.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
@@ -74,17 +75,28 @@ function groupBySource(records) {
 // runtime builder injected for a Postgres-backed read model: bind the Postgres
 // operation set (queryDbTableName is then the read-model spec name, the shared
 // `qdb_<name>` discriminator). Absent → the DynamoDB path is byte-identical.
-function buildReadModelHandler(specModule, mappingsModule, queryDbTableName, pgConnection) {
+function buildReadModelHandler(specModule, mappingsModule, queryDbTableName, pgConnection, stateTopicName) {
   const patchedSpec = patchSpecId(specModule);
   let operations;
   if (pgConnection) {
     const indexes = (patchedSpec.config && patchedSpec.config.indexes) || [];
     const subIdField = patchedSpec.subIdConfig ? patchedSpec.subIdConfig.subIdField : undefined;
     const pgOps = pgQdbOpsFor(pgConnection, queryDbTableName, indexes, subIdField);
+    // B3.3: on a subscription-enabled (Stream) Postgres read model, publish a
+    // live-update descriptor after each save/delete (no DynamoDB stream exists).
+    // `stateTopicName` (present only for stream RMs) + APPSYNC_ENDPOINT gate it;
+    // absent → withLiveUpdates returns pgOps unchanged. Wrap BEFORE mkInjectIdSave
+    // so the publish sees the id-injected state (id, subId, updatedAt).
+    const livePgOps = withLiveUpdates(pgOps, {
+      endpoint: process.env.APPSYNC_ENDPOINT,
+      region: process.env.AWS_REGION,
+      topicName: stateTopicName,
+      subIdField,
+    });
     operations = {
-      ...pgOps,
-      save: mkInjectIdSave(pgOps.save),
-      saveBatch: mkInjectIdSaveBatch(pgOps.saveBatch),
+      ...livePgOps,
+      save: mkInjectIdSave(livePgOps.save),
+      saveBatch: mkInjectIdSaveBatch(livePgOps.saveBatch),
     };
   } else {
     const table = makeTableRef(queryDbTableName);
@@ -119,7 +131,7 @@ async function buildAllHandlers() {
   await Promise.all(config.handlers.map(async h => {
     const specModule = await dynamicImport(h.specModule);
     const mappingsModule = await dynamicImport(h.mappingsModule);
-    const handler = buildReadModelHandler(specModule, mappingsModule, h.queryDbTableName, h.pgConnection);
+    const handler = buildReadModelHandler(specModule, mappingsModule, h.queryDbTableName, h.pgConnection, h.stateTopicName);
     // Multiple read models can share one source stream — e.g. every admin read
     // model (Plugins, PluginHistory, PlatformEventGraph, UIFragmentRegistry)
     // projects the Plugin aggregate's EventLog stream. Accumulate ALL handlers

package/src/adapter/Runtime/RuntimeEnvironment_Lambda.res

@@ -180,6 +180,16 @@ let makeFromCodeAsset: (
     variables->Dict.set(key, value)
   })
 
+  // ESM self-containment (Option C): every code archive built by
+  // Util_Bundle.buildCodeArchive ships register-hook.mjs + layer-resolver.mjs at
+  // /var/task. --import registers the resolve hook so the ESM entry point (and the
+  // user spec/behavior modules it dynamically imports) can resolve bare specifiers
+  // — @reventlessdev/*, effect, sury from the layer, @aws-sdk/* from the runtime —
+  // that ESM `import` would otherwise not find outside /var/task. Framework
+  // invariant: set last so it wins over any caller-supplied value.
+  variables->Dict.set("NODE_OPTIONS", Util_Bundle.esmLoaderNodeOptions->Pulumi.Input.make)
+  variables->Dict.set("ESM_FALLBACK_DIRS", Util_Bundle.esmFallbackDirs->Pulumi.Input.make)
+
   let tags = AWS.Tags.make(~name, ReventlessCore.CommandTopic.componentType)
   let lambda = Lambda.Function.make(
     ~name,

package/src/adapter/Runtime/RuntimeEnvironment_Lambda.res.mjs

@@ -13,6 +13,7 @@ import * as AWS_Tags$ReventlessAws from "../AWS_Tags.res.mjs";
 import * as Adapter$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Adapter.res.mjs";
 import * as Runtime$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Runtime/Runtime.res.mjs";
 import * as PolicyDocument$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/IAM/PolicyDocument.res.mjs";
+import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.res.mjs";
 import * as Util_Lambda$ReventlessAws from "../../util/Util_Lambda.res.mjs";
 import * as Util_Pulumi$ReventlessCore from "@reventlessdev/reventless-core/src/util/Util_Pulumi.res.mjs";
 import * as CommandTopic$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic.res.mjs";
@@ -91,6 +92,8 @@ function makeFromCodeAsset(name, code, sourceCodeHash, envVarsOpt, memorySizeOpt
   Stdlib_Dict.forEachWithKey(additionalEnvVars, (value, key) => {
     variables[key] = value;
   });
+  variables["NODE_OPTIONS"] = Util_Bundle$ReventlessAws.esmLoaderNodeOptions;
+  variables["ESM_FALLBACK_DIRS"] = Util_Bundle$ReventlessAws.esmFallbackDirs;
   let tags = AWS_Tags$ReventlessAws.make(name, CommandTopic$ReventlessCore.componentType);
   let lambda = new (Aws.lambda.Function)(name, {
     handler: "index.handler",

package/src/adapter/Runtime/StateChangeSliceRuntime_Builder_Single.res

@@ -95,20 +95,15 @@ let forDcbCommandTopic = (
     // fragment merged into HANDLER_CONFIG below.
     let pgConnectionFragment = switch pgSelection {
     | Some(sel) =>
-      sel.connectionConfig->Pulumi.Output.apply(cc => {
-        let pgConnectionJson =
-          [
-            ("host", cc.host->JSON.Encode.string),
-            ("port", cc.port->Int.toFloat->JSON.Encode.float),
-            ("database", cc.database->JSON.Encode.string),
-            ("username", cc.username->JSON.Encode.string),
-            ("secretArn", cc.secretArn->JSON.Encode.string),
-          ]
-          ->Dict.fromArray
-          ->JSON.Encode.object
-          ->JSON.stringify
-        `,"pgConnection":${pgConnectionJson}`
-      })
+      // C2: the DCB command Lambda is the only Postgres path that takes an append
+      // lock, so `lockStrategy` rides in this fragment (not in `connectionConfig`,
+      // which the classic/QueryDb paths share). The entry point passes it to
+      // `DcbEventLogStorage_Postgres_Runtime.opsFor`.
+      sel.connectionConfig->Pulumi.Output.apply(cc =>
+        `,"pgConnection":${cc
+          ->PgConnection.connectionConfigToJson(~lockStrategy=sel.lockStrategy)
+          ->JSON.stringify}`
+      )
     | None => Pulumi.Output.make("")
     }
 

package/src/adapter/Runtime/StateChangeSliceRuntime_Builder_Single.res.mjs

@@ -9,6 +9,7 @@ import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/co
 import * as DcbBackend$ReventlessAws from "../DcbEventLog/DcbBackend.res.mjs";
 import * as PolicyDocument$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/IAM/PolicyDocument.res.mjs";
 import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.res.mjs";
+import * as PgConnection$ReventlessAws from "../Postgres/PgConnection.res.mjs";
 import * as CommandTopicChannel_SQS$ReventlessAws from "../CommandTopic/CommandTopicChannel_SQS.res.mjs";
 import * as RuntimeEnvironment_Lambda$ReventlessAws from "./RuntimeEnvironment_Lambda.res.mjs";
 
@@ -51,31 +52,7 @@ function forDcbCommandTopic(slicePaths, dcbTableName, pluginName, syncConfig, as
     let b = Stdlib_Option.getOr(JSON.stringify(param[1]), `""`);
     return `{"spec":` + s + `,"behavior":` + b + `}`;
   }).join(",");
-  let pgConnectionFragment = pgSelection !== undefined ? pgSelection.connectionConfig.apply(cc => {
-      let pgConnectionJson = JSON.stringify(Object.fromEntries([
-        [
-          "host",
-          cc.host
-        ],
-        [
-          "port",
-          cc.port
-        ],
-        [
-          "database",
-          cc.database
-        ],
-        [
-          "username",
-          cc.username
-        ],
-        [
-          "secretArn",
-          cc.secretArn
-        ]
-      ]));
-      return `,"pgConnection":` + pgConnectionJson;
-    }) : Pulumi.output("");
+  let pgConnectionFragment = pgSelection !== undefined ? pgSelection.connectionConfig.apply(cc => `,"pgConnection":` + JSON.stringify(PgConnection$ReventlessAws.connectionConfigToJson(pgSelection.lockStrategy, cc))) : Pulumi.output("");
   let handlerConfigJson = Pulumi.all([
     dcbTableName$1,
     queue.id,

package/src/adapter/Runtime/StateTopicPublish.mjs

@@ -0,0 +1,204 @@
+// StateTopicPublish.mjs
+// B3.3: Postgres live-update publisher — the projection-Lambda-side counterpart
+// of the DynamoDB StateTopic Lambda (StateTopic_AppSync.res).
+//
+// On the DynamoDB path a shared Lambda reads the table's stream and POSTs a
+// change descriptor to the AppSync Events API. Postgres read models have no
+// stream, so (design (a), mirroring the reventless-local Sqlite/InMemory
+// backends) the projection Lambda publishes the SAME descriptor itself, right
+// after it writes the `qdb_<name>` row. The wire contract — channel layout,
+// descriptor shape, SigV4 signing — is byte-identical to StateTopic_AppSync so
+// the browser/AutoLive side cannot tell the two backends apart.
+//
+// Channel:  /default/{pathSegment(topicName)}/{pathSegment(entityKey)}
+// Descriptor: { changeKind: "Updated" | "Removed", id: <entityKey>,
+//               sortKeyValue?: <updatedAt | createdAt if present> }
+//
+// changeKind is fixed per operation (save→"Updated", delete→"Removed"): a
+// Postgres upsert doesn't distinguish insert vs update, and the Sqlite/InMemory
+// backends already collapse save→"Updated" (LocalBus.res:213) — the UI treats a
+// first-seen "Updated" row as an insert, so no Added detection is needed.
+//
+// Publish failures are LOGGED AND SWALLOWED: the projection row is already
+// committed when this runs, and the projection Lambda is at-least-once — throwing
+// would re-run the projection and duplicate work. A dropped live notification
+// only means the UI refreshes the list on its next load, not data loss.
+//
+// Uses native Node.js crypto + fetch with SigV4; credentials come from the
+// Lambda execution role via the process.env AWS_* variables.
+
+import { createHmac, createHash } from "node:crypto";
+
+function sha256hex(data) {
+  return createHash("sha256").update(typeof data === "string" ? data : JSON.stringify(data)).digest("hex");
+}
+function hmacBuf(key, data) {
+  return createHmac("sha256", key).update(data).digest();
+}
+
+async function signedHeaders(host, path, body, region) {
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+  const sessionToken = process.env.AWS_SESSION_TOKEN;
+  const now = new Date();
+  const amzDate = now.toISOString().replace(/[:\-]|\..../g, "").slice(0, 15) + "Z";
+  const dateStamp = now.toISOString().slice(0, 10).replace(/-/g, "");
+  const headers = { host, "x-amz-date": amzDate, ...(sessionToken ? { "x-amz-security-token": sessionToken } : {}) };
+  const canonH = Object.entries(headers).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${v}\n`).join("");
+  const signH = Object.keys(headers).sort().join(";");
+  const cr = ["POST", path, "", canonH, signH, sha256hex(body)].join("\n");
+  const scope = `${dateStamp}/${region}/appsync/aws4_request`;
+  const sts = ["AWS4-HMAC-SHA256", amzDate, scope, sha256hex(cr)].join("\n");
+  const kDate = hmacBuf("AWS4" + secretAccessKey, dateStamp);
+  const kSigning = hmacBuf(hmacBuf(hmacBuf(kDate, region), "appsync"), "aws4_request");
+  const sig = createHmac("sha256", kSigning).update(sts).digest("hex");
+  return { ...headers, Authorization: `AWS4-HMAC-SHA256 Credential=${accessKeyId}/${scope}, SignedHeaders=${signH}, Signature=${sig}` };
+}
+
+// AppSync Events channel segments allow only [A-Za-z0-9-]; anything else
+// collapses to `-`. The descriptor body keeps the ORIGINAL entityKey so the UI
+// can match it against GraphQL row ids. Same rule as StateTopic_AppSync and the
+// UI's AutoLive.normalizeSegment.
+function pathSegment(value) {
+  return String(value).replace(/[^A-Za-z0-9-]/g, "-");
+}
+
+// Pick the natural sort timestamp from the saved state (updatedAt preferred,
+// createdAt fallback). Mirrors StateTopic_AppSync.pickSortKeyValue and
+// LocalBus.pickSortKeyValue.
+function pickSortKeyValue(state) {
+  if (state && typeof state === "object" && !Array.isArray(state)) {
+    if (typeof state.updatedAt === "string") return state.updatedAt;
+    if (typeof state.createdAt === "string") return state.createdAt;
+  }
+  return undefined;
+}
+
+// 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.
+// - dedupeId:   AppSync publish `id` (idempotency hint).
+export async function publishStateChange({ endpoint, region, topicName, entityKey, changeKind, sortKeyValue, 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 body = JSON.stringify({
+      id: dedupeId || (topicName + ":" + entityKey + ":" + changeKind),
+      channel,
+      events: [JSON.stringify(descriptor)],
+    });
+    const auth = await signedHeaders(url.hostname, "/event", body, region || process.env.AWS_REGION || "eu-west-1");
+    const res = await fetch(endpoint + "/event", {
+      method: "POST",
+      headers: {
+        accept: "application/json, text/javascript",
+        "content-encoding": "amz-1.0",
+        "content-type": "application/json; charset=UTF-8",
+        ...auth,
+      },
+      body,
+    });
+    if (!res.ok) {
+      const txt = await res.text();
+      // Swallow (see module docstring): the row is already committed. Log
+      // structurally so a CloudWatch metric filter on
+      // "PG_STATE_TOPIC_PUBLISH_FAILED" can surface persistent breakage.
+      console.error(
+        "PG_STATE_TOPIC_PUBLISH_FAILED status=" + res.status +
+        " channel=" + channel +
+        " body=" + txt.slice(0, 500)
+      );
+    }
+  } catch (e) {
+    console.error("PG_STATE_TOPIC_PUBLISH_FAILED status=network err=" + (e && e.message));
+  }
+}
+
+// Compose the entity key from a save/delete's id + optional sub-key. Matches
+// StateTopic_AppSync.entityKeyFromRecord and QueryDbStorage_Sqlite.entityKeyFor:
+// single-key tables → id; composite tables → `id-subKeyValue`.
+export function entityKeyFor(id, state, subIdField) {
+  if (subIdField === undefined || subIdField === null) return String(id);
+  const subValue =
+    state && typeof state === "object" && !Array.isArray(state) ? state[subIdField] : undefined;
+  return subValue === undefined || subValue === null
+    ? String(id)
+    : String(id) + "-" + String(subValue);
+}
+
+// Wrap a Postgres QueryDb operation set so every save/delete also publishes a
+// live-update descriptor. `liveConfig` = { endpoint, region, topicName,
+// subIdField }. When endpoint/topicName are absent the ops pass through
+// unchanged (non-stream / non-live read models pay nothing).
+//
+// Note on batch ops: saveBatch/deleteBatch fan out one publish per item, after
+// the batch write resolves — the row set is committed as a unit, and each row
+// gets its own descriptor exactly as N single writes would.
+export function withLiveUpdates(ops, liveConfig) {
+  const { endpoint, topicName, region, subIdField } = liveConfig || {};
+  if (!endpoint || !topicName) return ops;
+  // `publish` is injectable for headless testing (default = the real SigV4
+  // publisher); tests pass a capturing stub so the wrapping logic can be
+  // asserted without fetch/crypto.
+  const publish = (liveConfig && liveConfig.publish) || publishStateChange;
+
+  const publishSaved = async (id, state) =>
+    publish({
+      endpoint, region, topicName,
+      entityKey: entityKeyFor(id, state, subIdField),
+      changeKind: "Updated",
+      sortKeyValue: pickSortKeyValue(state),
+    });
+
+  const publishRemovedKey = async (entityKey) =>
+    publish({ endpoint, region, topicName, entityKey, changeKind: "Removed" });
+
+  // Resolve the entity keys a delete will remove — computed BEFORE the delete so
+  // a partition-wide delete on a composite table can still enumerate its rows
+  // (mirrors QueryDbStorage_Sqlite.delete's rowKeysForPartition). `subIdOpt` is
+  // the adapter's `option<(field, subValue)>`: undefined (partition-wide) or a
+  // `[field, subValue]` array (one specific row).
+  const removedKeysFor = async (id, subIdOpt) => {
+    if (subIdOpt) return [String(id) + "-" + String(subIdOpt[1])];
+    if (subIdField === undefined || subIdField === null) return [String(id)];
+    // Composite table, whole-partition delete (`Delete(id)` / `DeleteMany`):
+    // read the live rows so each removed sub-row gets its own descriptor,
+    // exactly as N DynamoDB stream REMOVE records would.
+    const res = await ops.load(id);
+    const rows = res && res.TAG === "Ok" ? res._0 : [];
+    return rows.map((row) => entityKeyFor(id, row, subIdField));
+  };
+
+  return {
+    ...ops,
+    save: async (id, state, saveMode, ttl) => {
+      const r = await ops.save(id, state, saveMode, ttl);
+      await publishSaved(id, state);
+      return r;
+    },
+    saveBatch: async (items) => {
+      const r = await ops.saveBatch(items);
+      await Promise.all(items.map(([id, state]) => publishSaved(id, state)));
+      return r;
+    },
+    delete: async (id, subIdOpt) => {
+      const keys = await removedKeysFor(id, subIdOpt);
+      const r = await ops.delete(id, subIdOpt);
+      await Promise.all(keys.map(publishRemovedKey));
+      return r;
+    },
+    deleteBatch: async (entries) => {
+      const keyGroups = await Promise.all(entries.map(([id, subIdOpt]) => removedKeysFor(id, subIdOpt)));
+      const r = await ops.deleteBatch(entries);
+      await Promise.all(keyGroups.flat().map(publishRemovedKey));
+      return r;
+    },
+  };
+}

package/src/adapter/Runtime/StateViewSliceEntryPoint.mjs

@@ -11,6 +11,7 @@ import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/Req
 import { handleAction } from "@reventlessdev/reventless-core/src/Projection.res.mjs";
 import { load, loadStream, save, saveBatch, count, $$delete, deleteBatch } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_DynamoDb_Runtime.res.mjs";
 import { opsFor as pgQdbOpsFor } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_Postgres_Runtime.res.mjs";
+import { withLiveUpdates } from "./StateTopicPublish.mjs";
 import { handleStreamEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_DynamoDbStream_Runtime.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
@@ -44,12 +45,22 @@ function groupBySource(records) {
 // `pgConnection`, when present, selects the Postgres QueryDb runtime for this
 // slice's view table (`queryDbTableName` is then the slice spec name, the shared
 // `qdb_<name>` discriminator). Absent → the DynamoDB path is byte-identical.
-function buildJsonEventsHandler(specModule, projectionModule, queryDbTableName, pgConnection) {
+function buildJsonEventsHandler(specModule, projectionModule, queryDbTableName, pgConnection, stateTopicName) {
   let queryDbOps;
   if (pgConnection) {
     const indexes = (specModule.config && specModule.config.indexes) || [];
     const subIdField = specModule.subIdConfig ? specModule.subIdConfig.subIdField : undefined;
-    queryDbOps = pgQdbOpsFor(pgConnection, queryDbTableName, indexes, subIdField);
+    const pgOps = pgQdbOpsFor(pgConnection, queryDbTableName, indexes, subIdField);
+    // B3.3: subscription-enabled (Stream) Postgres view slice → publish a
+    // live-update descriptor after save/delete. `stateTopicName` + APPSYNC_ENDPOINT
+    // gate it; absent → withLiveUpdates passes pgOps through. The view slice's id
+    // is the save's first arg (no id injection), so no wrap-ordering concern.
+    queryDbOps = withLiveUpdates(pgOps, {
+      endpoint: process.env.APPSYNC_ENDPOINT,
+      region: process.env.AWS_REGION,
+      topicName: stateTopicName,
+      subIdField,
+    });
   } else {
     const table = makeTableRef(queryDbTableName);
     queryDbOps = {
@@ -105,6 +116,9 @@ function expandHandlers(config) {
       // Shared across a plugin's slices (all follow the platform backend toggle);
       // hoisted to the top level of the compressed config like base/sourceUrn.
       pgConnection: config.pgConnection,
+      // B3.3: per-slice AppSync Events channel root (list field name). Present
+      // only for subscription-enabled (Stream) Postgres view slices.
+      stateTopicName: h.t,
     };
   });
 }
@@ -118,7 +132,7 @@ async function buildAllHandlers() {
       dynamicImport(h.specModule),
       dynamicImport(h.projectionModule),
     ]);
-    const jsonEventsHandler = buildJsonEventsHandler(specModule, projectionModule, h.queryDbTableName, h.pgConnection);
+    const jsonEventsHandler = buildJsonEventsHandler(specModule, projectionModule, h.queryDbTableName, h.pgConnection, h.stateTopicName);
     const streamHandler = (event, context) => handleStreamEvent(jsonEventsHandler, event, context);
     const existing = handlers[h.sourceUrn] || [];
     existing.push(streamHandler);