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

package/src/adapter/Runtime/StateViewSliceRuntime_Builder_Single.res

@@ -13,6 +13,9 @@ type handlerEntry = {
   projectionModule: string,
   queryDbTableName: string,
   sourceUrn: string,
+  // B3.3: AppSync Events channel root for a subscription-enabled Postgres view
+  // slice; "" when the slice isn't live-enabled (compact key `t`, omitted then).
+  stateTopicName: string,
 }
 
 // Longest common prefix of a set of strings. Used to factor the shared
@@ -40,6 +43,27 @@ type sliceInfo = {
 
 let sliceInfos: dict<sliceInfo> = Dict.make()
 
+// B3.3: the AppSync Events API a Postgres-backed stream view slice publishes live
+// updates to. Set once by `Platform.makePlatform` before plugins build (mirrors
+// EventCollectorRuntime_Builder_Single). None → no live updates.
+type eventsApiConfig = {
+  endpoint: Pulumi.Output.t<string>,
+  apiArn: Pulumi.Output.t<string>,
+}
+let eventsApiConfig: ref<option<eventsApiConfig>> = ref(None)
+let setEventsApiConfig = (cfg: eventsApiConfig) => eventsApiConfig := Some(cfg)
+
+// Channel root for a subscription-enabled Postgres view slice (the plural LIST
+// field name, same source as the DynamoDB subscriptionInfraHook); "" when the
+// slice isn't stream-routed or there's no events API.
+let stateTopicNameFor = (name: string): string =>
+  QueryDbBackend.postgresStreamRegistry->Set.has(name) && eventsApiConfig.contents->Option.isSome
+    ? ReventlessCore.Plugin_Helpers.queryFieldNamesRegistry
+      ->Dict.get(name)
+      ->Option.map(qn => qn.listFieldName)
+      ->Option.getOr(name)
+    : ""
+
 let registerStateViewSlice = (
   ~name,
   ~specModulePath,
@@ -130,6 +154,9 @@ let buildLambda = (
   ~packageDirs,
   ~channelSpecs,
   ~feedQueue: option<PulumiAws.SQS.Queue.t>=None,
+  // B3.3: Some when any slice on this Lambda is a subscription-enabled Postgres
+  // view slice — arms the APPSYNC_ENDPOINT env + appsync:EventPublish IAM.
+  ~pgStreamConfig: option<eventsApiConfig>=None,
   ~memorySize=1024,
   ~timeout=30,
 ) => {
@@ -141,20 +168,9 @@ let buildLambda = (
   let qdbSelection = QueryDbBackend.get()
   let pgConnectionFragment = switch qdbSelection {
   | 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}`
-    })
+    sel.connectionConfig->Pulumi.Output.apply(cc =>
+      `,"pgConnection":${cc->PgConnection.connectionConfigToJson->JSON.stringify}`
+    )
   | None => Pulumi.Output.make("")
   }
 
@@ -191,11 +207,16 @@ let buildLambda = (
             ->JSON.stringifyAny
             ->Option.getOr(`""`)
           let q = h.queryDbTableName->JSON.stringifyAny->Option.getOr(`""`)
+          // B3.3: compact key `t` = live-update channel root; omit when empty.
+          let t =
+            h.stateTopicName == ""
+              ? ""
+              : `,"t":${h.stateTopicName->JSON.Encode.string->JSON.stringify}`
           if sharedUrn != "" {
-            `{"s":${s},"p":${p},"q":${q}}`
+            `{"s":${s},"p":${p},"q":${q}${t}}`
           } else {
             let u = h.sourceUrn->JSON.stringifyAny->Option.getOr(`""`)
-            `{"s":${s},"p":${p},"q":${q},"u":${u}}`
+            `{"s":${s},"p":${p},"q":${q},"u":${u}${t}}`
           }
         })
         ->Array.join(",")
@@ -207,6 +228,13 @@ let buildLambda = (
   let envVars: dict<Pulumi.Input.t<string>> = Dict.make()
   envVars->Dict.set("HANDLER_CONFIG", handlerConfigOutput->Pulumi.Output.asInput)
 
+  // B3.3: give the projection Lambda the AppSync Events endpoint when any of its
+  // slices publish live updates (IAM added below).
+  switch pgStreamConfig {
+  | Some(cfg) => envVars->Dict.set("APPSYNC_ENDPOINT", cfg.endpoint->Pulumi.Output.asInput)
+  | None => ()
+  }
+
   // Bundle the framework packages alongside the entry point so the deployed
   // Lambda picks up local edits without waiting for a Lambda Layer rebuild
   // (the layer fetches @reventlessdev/reventless-* from GitHub Packages, not
@@ -286,6 +314,35 @@ let buildLambda = (
   | None => ()
   }
 
+  // B3.3: grant appsync:EventPublish so subscription-enabled Postgres view slices
+  // can push live-update descriptors from this Lambda.
+  switch pgStreamConfig {
+  | Some(cfg) =>
+    let _ = cfg.apiArn->Pulumi.Output.apply(apiArn => {
+      open PulumiAws.PolicyDocument
+      PulumiAws.IAM.RolePolicy.make(
+        ~name="AllStateViewSlices-appsyncPublish",
+        ~args={
+          policy: PulumiAws.PolicyDocument.make(
+            ~id="AllStateViewSlices-appsyncPublishPolicy",
+            ~statements=[
+              {
+                sid: "AllowPublishAppSyncEvents",
+                effect: Allow,
+                actions: Action("appsync:EventPublish"),
+                resources: Resource(apiArn ++ "/*"),
+              },
+            ],
+          )
+          ->PulumiAws.PolicyDocument.toJsonString
+          ->Pulumi.Input.make,
+          role: runtime.parts.lambdaRole.id->Pulumi.Output.asInput,
+        },
+      )
+    })
+  | None => ()
+  }
+
   let _connectResources = EventCollectorChannel.connect(
     ~name="AllStateViewSlices",
     ~channelSpecs,
@@ -347,7 +404,7 @@ let finishWithDcbEventLog = (dcbEventLog: ReventlessCore.DcbEventLog.component)
         let packageDirs: dict<string> = Dict.make()
         let allQueryDbResources: array<ReventlessInfra.Adapter.resource> = []
 
-        sliceInfos->Dict.forEachWithKey((info, _name) => {
+        sliceInfos->Dict.forEachWithKey((info, name) => {
           info.queryDbResources->Array.forEach(r => allQueryDbResources->Array.push(r)->ignore)
           let specPkg = Util_Bundle.extractPackageName(info.specModulePath)
           packageDirs->Dict.set(specPkg, Util_Bundle.resolvePackageRoot(specPkg))
@@ -369,18 +426,24 @@ let finishWithDcbEventLog = (dcbEventLog: ReventlessCore.DcbEventLog.component)
                 projectionModule: info.projectionModulePath,
                 queryDbTableName: tableName,
                 sourceUrn: urn,
+                stateTopicName: stateTopicNameFor(name),
               }
               entry
             })
           let _ = handlerOutputs->Array.push(handlerJson)
         })
 
+        let anyPgStream =
+          sliceInfos
+          ->Dict.keysToArray
+          ->Array.some(n => QueryDbBackend.postgresStreamRegistry->Set.has(n))
         buildLambda(
           ~parent,
           ~handlerOutputs,
           ~packageDirs,
           ~channelSpecs=[{channel: channel, eventTopics, resources: allQueryDbResources}],
           ~feedQueue,
+          ~pgStreamConfig=anyPgStream ? eventsApiConfig.contents : None,
         )
       | None =>
         log.warn(
@@ -445,6 +508,7 @@ let finish = () =>
                   queryDbTableName: tableName,
                   // No stream resource (Postgres) → dispatch on the feed queue ARN.
                   sourceUrn: urns->Array.get(0)->Option.getOr(feedArn),
+                  stateTopicName: stateTopicNameFor(spec.componentName),
                 }
                 entry
               })
@@ -457,12 +521,17 @@ let finish = () =>
           }
         })
 
+        let anyPgStream =
+          storedSpecs->Array.some(spec =>
+            QueryDbBackend.postgresStreamRegistry->Set.has(spec.componentName)
+          )
         buildLambda(
           ~parent,
           ~handlerOutputs,
           ~packageDirs,
           ~channelSpecs=storedSpecs->Array.map(({channelSpec}) => channelSpec),
           ~feedQueue,
+          ~pgStreamConfig=anyPgStream ? eventsApiConfig.contents : None,
           ~memorySize=maxMemorySize,
           ~timeout=maxTimeout,
         )

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

@@ -13,8 +13,10 @@ 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 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";
@@ -38,6 +40,22 @@ function commonPrefix(strings) {
 
 let sliceInfos = {};
 
+let eventsApiConfig = {
+  contents: undefined
+};
+
+function setEventsApiConfig(cfg) {
+  eventsApiConfig.contents = cfg;
+}
+
+function stateTopicNameFor(name) {
+  if (QueryDbBackend$ReventlessAws.postgresStreamRegistry.has(name) && Stdlib_Option.isSome(eventsApiConfig.contents)) {
+    return Stdlib_Option.getOr(Stdlib_Option.map(Plugin_Helpers$ReventlessCore.queryFieldNamesRegistry[name], qn => qn.listFieldName), name);
+  } else {
+    return "";
+  }
+}
+
 function registerStateViewSlice(name, specModulePath, projectionModulePath, queryDbTableName, queryDbResourcesOpt) {
   let queryDbResources = queryDbResourcesOpt !== undefined ? queryDbResourcesOpt : [];
   sliceInfos[name] = {
@@ -88,8 +106,9 @@ let finished = {
   contents: false
 };
 
-function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueueOpt, memorySizeOpt, timeoutOpt) {
+function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueueOpt, pgStreamConfigOpt, memorySizeOpt, timeoutOpt) {
   let feedQueue = feedQueueOpt !== undefined ? Primitive_option.valFromOption(feedQueueOpt) : undefined;
+  let pgStreamConfig = pgStreamConfigOpt !== undefined ? Primitive_option.valFromOption(pgStreamConfigOpt) : undefined;
   let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
   let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
   let opts_parent = parent;
@@ -97,31 +116,7 @@ function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueu
     parent: opts_parent
   };
   let qdbSelection = QueryDbBackend$ReventlessAws.get();
-  let pgConnectionFragment = qdbSelection !== undefined ? 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 ? qdbSelection.connectionConfig.apply(cc => `,"pgConnection":` + JSON.stringify(PgConnection$ReventlessAws.connectionConfigToJson(undefined, cc))) : Pulumi.output("");
   let handlerConfigOutput = Pulumi.all([
     Pulumi.all(handlerOutputs),
     pgConnectionFragment
@@ -140,11 +135,12 @@ function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueu
       let s = Stdlib_Option.getOr(JSON.stringify(h.specModule.slice(baseLen, h.specModule.length)), `""`);
       let p = Stdlib_Option.getOr(JSON.stringify(h.projectionModule.slice(baseLen, h.projectionModule.length)), `""`);
       let q = Stdlib_Option.getOr(JSON.stringify(h.queryDbTableName), `""`);
+      let t = h.stateTopicName === "" ? "" : `,"t":` + JSON.stringify(h.stateTopicName);
       if (sharedUrn !== "") {
-        return `{"s":` + s + `,"p":` + p + `,"q":` + q + `}`;
+        return `{"s":` + s + `,"p":` + p + `,"q":` + q + t + `}`;
       }
       let u = Stdlib_Option.getOr(JSON.stringify(h.sourceUrn), `""`);
-      return `{"s":` + s + `,"p":` + p + `,"q":` + q + `,"u":` + u + `}`;
+      return `{"s":` + s + `,"p":` + p + `,"q":` + q + `,"u":` + u + t + `}`;
     }).join(",");
     let baseJson = Stdlib_Option.getOr(JSON.stringify(base), `""`);
     let urnJson = Stdlib_Option.getOr(JSON.stringify(sharedUrn), `""`);
@@ -152,6 +148,9 @@ function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueu
   });
   let envVars = {};
   envVars["HANDLER_CONFIG"] = handlerConfigOutput;
+  if (pgStreamConfig !== undefined) {
+    envVars["APPSYNC_ENDPOINT"] = pgStreamConfig.endpoint;
+  }
   packageDirs["@reventlessdev/reventless-aws"] = Util_Bundle$ReventlessAws.resolvePackageRoot("@reventlessdev/reventless-aws");
   packageDirs["@reventlessdev/reventless-core"] = Util_Bundle$ReventlessAws.resolvePackageRoot("@reventlessdev/reventless-core");
   let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/StateViewSliceEntryPoint.mjs", packageDirs, undefined);
@@ -171,6 +170,17 @@ function buildLambda(parent, handlerOutputs, packageDirs, channelSpecs, feedQueu
       role: runtime.parts.lambdaRole.id
     }));
   }
+  if (pgStreamConfig !== undefined) {
+    pgStreamConfig.apiArn.apply(apiArn => new (Aws.iam.RolePolicy)("AllStateViewSlices-appsyncPublish", {
+      policy: PolicyDocument$PulumiAws.toJsonString(PolicyDocument$PulumiAws.make(undefined, "AllStateViewSlices-appsyncPublishPolicy", [{
+          Sid: "AllowPublishAppSyncEvents",
+          Effect: "Allow",
+          Action: "appsync:EventPublish",
+          Resource: apiArn + "/*"
+        }])),
+      role: runtime.parts.lambdaRole.id
+    }));
+  }
   EventCollectorChannel_DynamoDbStream$ReventlessAws.connect("AllStateViewSlices", channelSpecs, runtime, opts);
   if (feedQueue !== undefined) {
     return PgProjectionFeed$ReventlessAws.connect("AllStateViewSlicesFeed", feedQueue, runtime.parts.lambda, runtime.parts.lambdaRole, Util_Pulumi$ReventlessCore.ComponentResourceOptions.toCustomResourceOptions(opts));
@@ -201,7 +211,7 @@ function finishWithDcbEventLog(dcbEventLog) {
       let handlerOutputs = [];
       let packageDirs = {};
       let allQueryDbResources = [];
-      Stdlib_Dict.forEachWithKey(sliceInfos, (info, _name) => {
+      Stdlib_Dict.forEachWithKey(sliceInfos, (info, name) => {
         info.queryDbResources.forEach(r => {
           allQueryDbResources.push(r);
         });
@@ -219,15 +229,17 @@ function finishWithDcbEventLog(dcbEventLog) {
           specModule: info.specModulePath,
           projectionModule: info.projectionModulePath,
           queryDbTableName: param[0],
-          sourceUrn: param[1]
+          sourceUrn: param[1],
+          stateTopicName: stateTopicNameFor(name)
         }));
         handlerOutputs.push(handlerJson);
       });
+      let anyPgStream = Object.keys(sliceInfos).some(n => QueryDbBackend$ReventlessAws.postgresStreamRegistry.has(n));
       buildLambda(parent, handlerOutputs, packageDirs, [{
           channel: channel,
           eventTopics: eventTopics,
           resources: allQueryDbResources
-        }], Primitive_option.some(feedQueue), undefined, undefined);
+        }], Primitive_option.some(feedQueue), Primitive_option.some(anyPgStream ? eventsApiConfig.contents : undefined), undefined, undefined);
     } else {
       log.warn("StateViewSliceRuntime_Builder_Single", undefined, "finishWithDcbEventLog: DCB EventLog has no parent");
     }
@@ -273,11 +285,13 @@ function finish() {
           specModule: info.specModulePath,
           projectionModule: info.projectionModulePath,
           queryDbTableName: param[0],
-          sourceUrn: Stdlib_Option.getOr(param[1][0], param[2])
+          sourceUrn: Stdlib_Option.getOr(param[1][0], param[2]),
+          stateTopicName: stateTopicNameFor(spec.componentName)
         }));
         handlerOutputs.push(handlerJson);
       });
-      buildLambda(parent, handlerOutputs, packageDirs, storedSpecs.map(param => param.channelSpec), Primitive_option.some(feedQueue), match[0], match[1]);
+      let anyPgStream = storedSpecs.some(spec => QueryDbBackend$ReventlessAws.postgresStreamRegistry.has(spec.componentName));
+      buildLambda(parent, handlerOutputs, packageDirs, storedSpecs.map(param => param.channelSpec), Primitive_option.some(feedQueue), Primitive_option.some(anyPgStream ? eventsApiConfig.contents : undefined), match[0], match[1]);
     } else {
       log.warn("StateViewSliceRuntime_Builder_Single", undefined, `finish: grandParent not set`);
     }
@@ -295,6 +309,9 @@ export {
   log,
   commonPrefix,
   sliceInfos,
+  eventsApiConfig,
+  setEventsApiConfig,
+  stateTopicNameFor,
   registerStateViewSlice,
   storedSpecs,
   grandParent,

package/src/adapter/StateTopic/StateTopic_AppSync.res

@@ -354,8 +354,12 @@ let finish = (
       "index.mjs",
       Pulumi.Asset.stringAsset(handlerCode)->Pulumi.Archive.assetToAssetOrArchive,
     )
+    // ESM self-containment: the handler imports @aws-sdk/util-dynamodb, provided
+    // by the nodejs22.x runtime only under /var/runtime — unreachable from
+    // /var/task ESM without the resolver hook. Ship the loader + set its env vars.
+    let loaderHash = Util_Bundle.addEsmLoaderAssets(archiveContents)
     let code = Pulumi.Archive.assetArchive(archiveContents)
-    let sourceCodeHash = Util_Bundle.hashString(handlerCode)
+    let sourceCodeHash = Util_Bundle.hashString(handlerCode ++ "\n---\n" ++ loaderHash)
 
     let layers =
       Lambda.reventlessLayerArn
@@ -383,6 +387,8 @@ let finish = (
               ("Environment", Pulumi.Pulumi.getStackName()->Pulumi.Input.make),
               ("APPSYNC_ENDPOINT", appsyncEndpoint->Pulumi.Output.asInput),
               ("STATE_TOPIC_MAP", topicMapJson->Pulumi.Output.asInput),
+              ("NODE_OPTIONS", Util_Bundle.esmLoaderNodeOptions->Pulumi.Input.make),
+              ("ESM_FALLBACK_DIRS", Util_Bundle.esmFallbackDirs->Pulumi.Input.make),
             ]),
           }: Lambda.Function.functionEnvironment
         )->Pulumi.Input.make,

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

@@ -243,8 +243,9 @@ function finish(eventsApi, opts) {
   });
   let archiveContents = {};
   archiveContents["index.mjs"] = new (Pulumi.asset.StringAsset)(handlerCode);
+  let loaderHash = Util_Bundle$ReventlessAws.addEsmLoaderAssets(archiveContents);
   let code = new (Pulumi.asset.AssetArchive)(archiveContents);
-  let sourceCodeHash = Util_Bundle$ReventlessAws.hashString(handlerCode);
+  let sourceCodeHash = Util_Bundle$ReventlessAws.hashString(handlerCode + "\n---\n" + loaderHash);
   let layers = Stdlib_Option.getOr(Stdlib_Option.map(Lambda$PulumiAws.reventlessLayerArn, arn => [arn]), []);
   let appsyncEndpoint = AppSync_EventsApi$ReventlessAws.httpEndpoint(eventsApi);
   let lambda = new (Aws.lambda.Function)(name + "StateTopicPublisher", {
@@ -269,6 +270,14 @@ function finish(eventsApi, opts) {
         [
           "STATE_TOPIC_MAP",
           topicMapJson
+        ],
+        [
+          "NODE_OPTIONS",
+          Util_Bundle$ReventlessAws.esmLoaderNodeOptions
+        ],
+        [
+          "ESM_FALLBACK_DIRS",
+          Util_Bundle$ReventlessAws.esmFallbackDirs
         ]
       ])
     },

package/src/plugin/cloner/ClonerRunner_Fargate.res

@@ -116,8 +116,12 @@ export const handler = async (event) => {
     "index.mjs",
     Pulumi.Asset.stringAsset(entryPointCode)->Pulumi.Archive.assetToAssetOrArchive,
   )
+  // ESM self-containment: the handler imports @aws-sdk/client-ecs, provided by the
+  // nodejs22.x runtime only under /var/runtime — unreachable from /var/task ESM
+  // without the resolver hook. Ship the loader + set its env vars on the Lambda.
+  let loaderHash = Util_Bundle.addEsmLoaderAssets(clonerArchiveContents)
   let code = Pulumi.Archive.assetArchive(clonerArchiveContents)
-  let sourceCodeHash = Util_Bundle.hashString(entryPointCode)
+  let sourceCodeHash = Util_Bundle.hashString(entryPointCode ++ "\n---\n" ++ loaderHash)
 
   let layers =
     Lambda.reventlessLayerArn
@@ -231,6 +235,8 @@ export const handler = async (event) => {
                   ->Pulumi.Input.make,
                 ),
                 ("Environment", Pulumi.Pulumi.getStackName()->Pulumi.Input.make),
+                ("NODE_OPTIONS", Util_Bundle.esmLoaderNodeOptions->Pulumi.Input.make),
+                ("ESM_FALLBACK_DIRS", Util_Bundle.esmFallbackDirs->Pulumi.Input.make),
               ]),
             }: Lambda.Function.functionEnvironment
           )->Pulumi.Input.make,

package/src/plugin/cloner/ClonerRunner_Fargate.res.mjs

@@ -81,8 +81,9 @@ export const handler = async (event) => {
 };`;
   let clonerArchiveContents = {};
   clonerArchiveContents["index.mjs"] = new (Pulumi.asset.StringAsset)(entryPointCode);
+  let loaderHash = Util_Bundle$ReventlessAws.addEsmLoaderAssets(clonerArchiveContents);
   let code = new (Pulumi.asset.AssetArchive)(clonerArchiveContents);
-  let sourceCodeHash = Util_Bundle$ReventlessAws.hashString(entryPointCode);
+  let sourceCodeHash = Util_Bundle$ReventlessAws.hashString(entryPointCode + "\n---\n" + loaderHash);
   let layers = Stdlib_Option.getOr(Stdlib_Option.map(Lambda$PulumiAws.reventlessLayerArn, arn => [arn]), []);
   let vpcStackName = Stdlib_Option.getOrThrow(new Pulumi.Config("vpc").get("stack"), undefined);
   let vpcConfig = Util_Vpc$ReventlessAws.getVpcConfig(vpcStackName, "vpc");
@@ -168,6 +169,14 @@ export const handler = async (event) => {
           [
             "Environment",
             Pulumi.getStack()
+          ],
+          [
+            "NODE_OPTIONS",
+            Util_Bundle$ReventlessAws.esmLoaderNodeOptions
+          ],
+          [
+            "ESM_FALLBACK_DIRS",
+            Util_Bundle$ReventlessAws.esmFallbackDirs
           ]
         ])
       },

package/src/util/Util_Bundle.res

@@ -112,6 +112,72 @@ let resolvePackageRoot = (packageName: string): string => {
 let hashString = (str: string): string =>
   createHash("sha256")->update(str)->digest("base64")
 
+// ── ESM self-containment loader (Option C) ──────────────────────────────────
+// Deployed Lambda entry points are ESM (`.mjs`) and statically/dynamically import
+// bare specifiers (`@reventlessdev/*`, `effect`, `sury`, `@aws-sdk/*`) that live in
+// the attached layer at /opt/nodejs/node_modules or the runtime SDK dir. ESM
+// `import` ignores NODE_PATH and /opt, so those imports fail from /var/task with
+// ERR_MODULE_NOT_FOUND. These two files install a `resolve` hook that, on an
+// unresolved bare specifier, retries against each dir named in ESM_FALLBACK_DIRS
+// (set on the Lambda env by RuntimeEnvironment_Lambda.makeFromCodeAsset). Shipped
+// at the root of every code archive; NODE_OPTIONS=--import points Node at
+// register-hook.mjs. Validated on a Node 22.17.1 rig; see
+// docs/plans/deployed-lambda-esm-self-containment.md.
+let registerHookFileName = "register-hook.mjs"
+let layerResolverFileName = "layer-resolver.mjs"
+
+let registerHookSource = `import { register } from "node:module";
+register("./${layerResolverFileName}", import.meta.url);
+`
+
+let layerResolverSource = `// Fallback dirs (real Lambda: /opt/nodejs for the layer, /var/runtime for the SDK).
+// Passed via env so the same hook is testable locally.
+const FALLBACKS = (process.env.ESM_FALLBACK_DIRS || "").split(":").filter(Boolean);
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    const bare = !/^[./]|^file:|^node:/.test(specifier);
+    if (err?.code !== "ERR_MODULE_NOT_FOUND" || !bare) throw err;
+    for (const dir of FALLBACKS) {
+      try {
+        // Re-resolve as if imported from a virtual file inside the fallback dir,
+        // so Node's own node_modules walk finds it (honours package.json exports).
+        const parentURL = new URL("file://" + dir + "/__resolver__.mjs").href;
+        return await nextResolve(specifier, { ...context, parentURL });
+      } catch { /* try next fallback */ }
+    }
+    throw err;
+  }
+}
+`
+
+// Env vars that activate the loader. Any Lambda whose archive includes the loader
+// files (via addEsmLoaderAssets / buildCodeArchive) MUST also set these two; any
+// that does NOT ship the loader MUST NOT set NODE_OPTIONS (it would --import a
+// missing file and fail cold start). --import registers the resolve hook;
+// ESM_FALLBACK_DIRS names the layer (/opt/nodejs) and runtime-SDK (/var/runtime)
+// node_modules dirs the hook retries against for @aws-sdk/*.
+let esmLoaderNodeOptions = `--import file:///var/task/${registerHookFileName}`
+let esmFallbackDirs = "/opt/nodejs/node_modules:/var/runtime/node_modules"
+
+/**
+ * Add the ESM self-containment loader files to an archive-contents dict and return
+ * a hash fragment so callers can fold them into their sourceCodeHash. Every code
+ * archive whose Lambda sets the esmLoader env vars MUST include these files.
+ */
+let addEsmLoaderAssets = (archiveContents: dict<Pulumi.Archive.assetOrArchive>): string => {
+  archiveContents->Dict.set(
+    registerHookFileName,
+    Pulumi.Asset.stringAsset(registerHookSource)->Pulumi.Archive.assetToAssetOrArchive,
+  )
+  archiveContents->Dict.set(
+    layerResolverFileName,
+    Pulumi.Asset.stringAsset(layerResolverSource)->Pulumi.Archive.assetToAssetOrArchive,
+  )
+  hashString(registerHookSource ++ "\n---\n" ++ layerResolverSource)
+}
+
 let isSkippedDir = (n: string) =>
   n == "node_modules" ||
   n == "lib" ||
@@ -207,6 +273,8 @@ let buildCodeArchive = (
     "index.mjs",
     Pulumi.Asset.stringAsset(reExportCode)->Pulumi.Archive.assetToAssetOrArchive,
   )
+  // ESM self-containment loader — shipped in every archive (see addEsmLoaderAssets).
+  let loaderHash = addEsmLoaderAssets(archiveContents)
   extraStringAssets->Dict.forEachWithKey((content, fileName) => {
     archiveContents->Dict.set(
       fileName,
@@ -249,7 +317,9 @@ let buildCodeArchive = (
       "\n---\n" ++
       packageContentHashes.contents->Array.join(",") ++
       "\n---\n" ++
-      extraHashEntries->Array.join("\n"),
+      extraHashEntries->Array.join("\n") ++
+      "\n---\n" ++
+      loaderHash,
     )
   {code, sourceCodeHash}
 }

package/src/util/Util_Bundle.res.mjs

@@ -78,6 +78,44 @@ function hashString(str) {
   return Crypto.createHash("sha256").update(str).digest("base64");
 }
 
+let registerHookFileName = "register-hook.mjs";
+
+let layerResolverFileName = "layer-resolver.mjs";
+
+let registerHookSource = `import { register } from "node:module";
+register("./` + layerResolverFileName + `", import.meta.url);
+`;
+
+let layerResolverSource = `// Fallback dirs (real Lambda: /opt/nodejs for the layer, /var/runtime for the SDK).
+// Passed via env so the same hook is testable locally.
+const FALLBACKS = (process.env.ESM_FALLBACK_DIRS || "").split(":").filter(Boolean);
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    const bare = !/^[./]|^file:|^node:/.test(specifier);
+    if (err?.code !== "ERR_MODULE_NOT_FOUND" || !bare) throw err;
+    for (const dir of FALLBACKS) {
+      try {
+        // Re-resolve as if imported from a virtual file inside the fallback dir,
+        // so Node's own node_modules walk finds it (honours package.json exports).
+        const parentURL = new URL("file://" + dir + "/__resolver__.mjs").href;
+        return await nextResolve(specifier, { ...context, parentURL });
+      } catch { /* try next fallback */ }
+    }
+    throw err;
+  }
+}
+`;
+
+let esmLoaderNodeOptions = `--import file:///var/task/` + registerHookFileName;
+
+function addEsmLoaderAssets(archiveContents) {
+  archiveContents[registerHookFileName] = new (Pulumi.asset.StringAsset)(registerHookSource);
+  archiveContents[layerResolverFileName] = new (Pulumi.asset.StringAsset)(layerResolverSource);
+  return hashString(registerHookSource + "\n---\n" + layerResolverSource);
+}
+
 function isSkippedDir(n) {
   if (n === "node_modules" || n === "lib" || n === "cjs" || n === "dts" || n === "tests" || n === "test" || n === "__mocks__" || n === "__tests__" || n === ".git") {
     return true;
@@ -129,6 +167,7 @@ function buildCodeArchive(entryPointModule, packageDirs, extraStringAssetsOpt) {
   let reExportCode = `export { handler } from "` + entryPointModule + `";`;
   let archiveContents = {};
   archiveContents["index.mjs"] = new (Pulumi.asset.StringAsset)(reExportCode);
+  let loaderHash = addEsmLoaderAssets(archiveContents);
   Stdlib_Dict.forEachWithKey(extraStringAssets, (content, fileName) => {
     archiveContents[fileName] = new (Pulumi.asset.StringAsset)(content);
   });
@@ -157,13 +196,15 @@ function buildCodeArchive(entryPointModule, packageDirs, extraStringAssetsOpt) {
   });
   let code = new (Pulumi.asset.AssetArchive)(archiveContents);
   packageContentHashes.contents.sort(Primitive_string.compare);
-  let sourceCodeHash = hashString(reExportCode + "\n---\n" + packageContentHashes.contents.join(",") + "\n---\n" + extraHashEntries.join("\n"));
+  let sourceCodeHash = hashString(reExportCode + "\n---\n" + packageContentHashes.contents.join(",") + "\n---\n" + extraHashEntries.join("\n") + "\n---\n" + loaderHash);
   return {
     code: code,
     sourceCodeHash: sourceCodeHash
   };
 }
 
+let esmFallbackDirs = "/opt/nodejs/node_modules:/var/runtime/node_modules";
+
 export {
   packageRootCache,
   localRequire,
@@ -171,6 +212,13 @@ export {
   extractPackageName,
   resolvePackageRoot,
   hashString,
+  registerHookFileName,
+  layerResolverFileName,
+  registerHookSource,
+  layerResolverSource,
+  esmLoaderNodeOptions,
+  esmFallbackDirs,
+  addEsmLoaderAssets,
   isSkippedDir,
   walkDir,
   createFilteredPackageArchive,

package/tests/PgChangeFeedRelay_IntegrationTest.res

@@ -1,8 +1,8 @@
 // Live-Postgres integration suite for the change-feed relay (B2.4).
 //
-// Skipped unless PG_URL is set, so the default `pnpm test` stays dependency-free.
-// Run against a real database with e.g.:
-//   PG_URL=postgres://postgres:postgres@localhost:5432/postgres pnpm test
+// Run via `pnpm run test:integration:pg` (boots a Postgres sidecar, runs the PG
+// suites serially, tears down). Excluded from the default parallel `pnpm test`;
+// self-skips unless PG_URL is set (the script exports it).
 //
 // Exercises the deployed propagation path end-to-end minus AWS: DCB events are
 // appended to a real `dcb_event` log (classic events to `event_log`), then