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

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

package/tests/PgConnectionJsonTest.res

@@ -0,0 +1,84 @@
+// Rung-1 guard for the `pgConnection` HANDLER_CONFIG serialization (A3/B/C).
+//
+// `PgConnection.connectionConfigToJson` is the single producer of the object
+// every Postgres entry point reads at cold start (`config.pgConnection.*` →
+// `PgRuntime.poolFor`). The field set is an untyped cross-language contract — a
+// dropped/renamed/retyped field here only fails at runtime in the deployed
+// Lambda, which no compile catches. These tests pin the exact shape so a drift
+// fails in CI instead. All seven deploy-time builders now route through this
+// helper, so pinning it pins them all.
+
+open JestGlobals
+
+let cc: PgConnection.connectionConfig = {
+  host: "db.example.eu-west-1.rds.amazonaws.com",
+  port: 5432,
+  database: "reventless",
+  username: "reventless_admin",
+  secretArn: "arn:aws:secretsmanager:eu-west-1:123456789012:secret:rds!db-abc-123",
+}
+
+let obj = json => json->JSON.Decode.object->Option.getOrThrow
+let field = (json, key) => json->obj->Dict.get(key)
+
+describe("PgConnection.connectionConfigToJson", () => {
+  testSync("emits exactly the five connection fields with correct types", () => {
+    let json = cc->PgConnection.connectionConfigToJson
+    // Exact key set — no extra keys, none missing (the cold-start contract).
+    expect(json->obj->Dict.keysToArray->Array.toSorted(String.compare))->toEqual([
+      "database",
+      "host",
+      "port",
+      "secretArn",
+      "username",
+    ])
+    expect(json->field("host"))->toEqual(Some(JSON.Encode.string(cc.host)))
+    expect(json->field("database"))->toEqual(Some(JSON.Encode.string(cc.database)))
+    expect(json->field("username"))->toEqual(Some(JSON.Encode.string(cc.username)))
+    expect(json->field("secretArn"))->toEqual(Some(JSON.Encode.string(cc.secretArn)))
+    // port MUST be a JSON number (poolFor reads it as an int), not a string.
+    expect(json->field("port"))->toEqual(Some(JSON.Encode.float(5432.)))
+  })
+
+  testSync("omits lockStrategy when not given (classic / QueryDb / migration paths)", () =>
+    expect(cc->PgConnection.connectionConfigToJson->field("lockStrategy"))->toEqual(None)
+  )
+
+  testSync("adds lockStrategy=\"AdvisoryLocks\" as the polyvariant string name", () =>
+    expect(
+      cc
+      ->PgConnection.connectionConfigToJson(~lockStrategy=#AdvisoryLocks)
+      ->field("lockStrategy"),
+    )->toEqual(Some(JSON.Encode.string("AdvisoryLocks")))
+  )
+
+  testSync("adds lockStrategy=\"RowLocks\" as the polyvariant string name", () =>
+    expect(
+      cc
+      ->PgConnection.connectionConfigToJson(~lockStrategy=#RowLocks)
+      ->field("lockStrategy"),
+    )->toEqual(Some(JSON.Encode.string("RowLocks")))
+  )
+
+  testSync("with lockStrategy the object has exactly six keys", () =>
+    expect(
+      cc
+      ->PgConnection.connectionConfigToJson(~lockStrategy=#RowLocks)
+      ->obj
+      ->Dict.keysToArray
+      ->Array.length,
+    )->toBe(6)
+  )
+
+  testSync("round-trips through JSON.parse as the entry points do", () => {
+    // The entry point does `JSON.parse(HANDLER_CONFIG).pgConnection` — prove the
+    // stringify→parse survives and still exposes the fields poolFor reads.
+    let parsed =
+      `{"pgConnection":${cc->PgConnection.connectionConfigToJson->JSON.stringify}}`
+      ->JSON.parseOrThrow
+      ->field("pgConnection")
+      ->Option.getOrThrow
+    expect(parsed->field("host"))->toEqual(Some(JSON.Encode.string(cc.host)))
+    expect(parsed->field("secretArn"))->toEqual(Some(JSON.Encode.string(cc.secretArn)))
+  })
+})

package/tests/PgConnectionJsonTest.res.mjs

@@ -0,0 +1,68 @@
+// 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 Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as PgConnection$ReventlessAws from "../src/adapter/Postgres/PgConnection.res.mjs";
+
+let cc = {
+  host: "db.example.eu-west-1.rds.amazonaws.com",
+  port: 5432,
+  database: "reventless",
+  username: "reventless_admin",
+  secretArn: "arn:aws:secretsmanager:eu-west-1:123456789012:secret:rds!db-abc-123"
+};
+
+function obj(json) {
+  return Stdlib_Option.getOrThrow(Stdlib_JSON.Decode.object(json), undefined);
+}
+
+function field(json, key) {
+  return obj(json)[key];
+}
+
+globalThis.describe("PgConnection.connectionConfigToJson", () => {
+  globalThis.test("emits exactly the five connection fields with correct types", () => {
+    let json = PgConnection$ReventlessAws.connectionConfigToJson(undefined, cc);
+    globalThis.expect(Object.keys(obj(json)).toSorted(Primitive_string.compare)).toEqual([
+      "database",
+      "host",
+      "port",
+      "secretArn",
+      "username"
+    ]);
+    globalThis.expect(obj(json)["host"]).toEqual("db.example.eu-west-1.rds.amazonaws.com");
+    globalThis.expect(obj(json)["database"]).toEqual("reventless");
+    globalThis.expect(obj(json)["username"]).toEqual("reventless_admin");
+    globalThis.expect(obj(json)["secretArn"]).toEqual("arn:aws:secretsmanager:eu-west-1:123456789012:secret:rds!db-abc-123");
+    globalThis.expect(obj(json)["port"]).toEqual(5432);
+  });
+  globalThis.test("omits lockStrategy when not given (classic / QueryDb / migration paths)", () => {
+    let json = PgConnection$ReventlessAws.connectionConfigToJson(undefined, cc);
+    globalThis.expect(obj(json)["lockStrategy"]).toEqual(undefined);
+  });
+  globalThis.test("adds lockStrategy=\"AdvisoryLocks\" as the polyvariant string name", () => {
+    let json = PgConnection$ReventlessAws.connectionConfigToJson("AdvisoryLocks", cc);
+    globalThis.expect(obj(json)["lockStrategy"]).toEqual("AdvisoryLocks");
+  });
+  globalThis.test("adds lockStrategy=\"RowLocks\" as the polyvariant string name", () => {
+    let json = PgConnection$ReventlessAws.connectionConfigToJson("RowLocks", cc);
+    globalThis.expect(obj(json)["lockStrategy"]).toEqual("RowLocks");
+  });
+  globalThis.test("with lockStrategy the object has exactly six keys", () => {
+    globalThis.expect(Object.keys(obj(PgConnection$ReventlessAws.connectionConfigToJson("RowLocks", cc))).length).toBe(6);
+  });
+  globalThis.test("round-trips through JSON.parse as the entry points do", () => {
+    let json = JSON.parse(`{"pgConnection":` + JSON.stringify(PgConnection$ReventlessAws.connectionConfigToJson(undefined, cc)) + `}`);
+    let parsed = Stdlib_Option.getOrThrow(obj(json)["pgConnection"], undefined);
+    globalThis.expect(obj(parsed)["host"]).toEqual("db.example.eu-west-1.rds.amazonaws.com");
+    globalThis.expect(obj(parsed)["secretArn"]).toEqual("arn:aws:secretsmanager:eu-west-1:123456789012:secret:rds!db-abc-123");
+  });
+});
+
+export {
+  cc,
+  obj,
+  field,
+}
+/*  Not a pure module */

package/tests/PgMigrationEntryPoint_IntegrationTest.res

@@ -0,0 +1,82 @@
+// Rung-1 integration guard for the A3 schema-migration Lambda entry point.
+//
+// Drives the real `PgMigrationEntryPoint.runMigration` — the orchestration the
+// deployed one-shot migration Lambda runs (parse HANDLER_CONFIG → build pool →
+// PgSchema.ensureSchema). The pool source is injected so this exercises the
+// whole path against a real Postgres WITHOUT the Secrets Manager round-trip
+// (that AWS boundary is the only remaining unvalidated piece). Proves the
+// migration leaves a queryable schema and is safely re-runnable.
+//
+// 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`.
+// The guard test (no pgConnection → throws) needs no DB; the live path is
+// skipped unless PG_URL is set (the script exports it).
+
+open JestGlobals
+
+@val external processEnv: dict<string> = "process.env"
+
+// Import the .mjs entry point and call runMigration with the pool injected.
+// Returns "ok" on success. A minimal pgConnection satisfies the guard; the real
+// fields are ignored because `makePool` is injected.
+let runMigrationWithPool: (
+  ReventlessPostgres.PgDriver.pool,
+) => promise<string> = %raw(`
+  async (pool) => {
+    const { runMigration } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/PgMigrationEntryPoint.mjs"
+    );
+    const config = {
+      pgConnection: {
+        host: "ignored", port: 5432, database: "ignored",
+        username: "ignored", secretArn: "ignored",
+      },
+    };
+    return await runMigration(config, { makePool: () => pool });
+  }
+`)
+
+// runMigration with an empty config — the guard must reject a HANDLER_CONFIG
+// that carries no pgConnection (a misconfigured deploy), rather than silently
+// building a bad pool.
+let runMigrationMissingConfigThrows: unit => promise<bool> = %raw(`
+  async () => {
+    const { runMigration } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/PgMigrationEntryPoint.mjs"
+    );
+    try { await runMigration({}, {}); return false; }
+    catch { return true; }
+  }
+`)
+
+describe("PgMigrationEntryPoint.runMigration", () => {
+  testPromise("rejects a HANDLER_CONFIG with no pgConnection", async () => {
+    let threw = await runMigrationMissingConfigThrows()
+    expect(threw)->toBe(true)
+  })
+
+  switch processEnv->Dict.get("PG_URL") {
+  | None =>
+    testSync("live migration (skipped — set PG_URL to run)", () => expect(true)->toBe(true))
+  | Some(url) =>
+    let pool = ReventlessPostgres.PgDriver.makePool({connectionString: url})
+    afterAll(() => {
+      let _ = pool->ReventlessPostgres.PgDriver.endPool
+    })
+
+    testPromise("runs ensureSchema, leaving both event logs queryable", async () => {
+      let _ = await runMigrationWithPool(pool)
+      // countAll queries the tables ensureSchema creates — it resolves (>= 0)
+      // only if `event_log` / `dcb_event` exist, and throws otherwise.
+      let classicCount = await ReventlessPostgres.EventLogStorage_Postgres.countAll(pool)
+      let dcbCount = await ReventlessPostgres.DcbEventLogStorage_Postgres.countAll(pool)
+      expect(classicCount >= 0 && dcbCount >= 0)->toBe(true)
+    })
+
+    testPromise("is idempotent — a second run does not throw", async () => {
+      let _ = await runMigrationWithPool(pool)
+      let again = await runMigrationWithPool(pool)
+      expect(again)->toBe("ok")
+    })
+  }
+})

package/tests/PgMigrationEntryPoint_IntegrationTest.res.mjs

@@ -0,0 +1,63 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as PgDriver$ReventlessPostgres from "@reventlessdev/reventless-postgres/src/PgDriver.res.mjs";
+import * as EventLogStorage_Postgres$ReventlessPostgres from "@reventlessdev/reventless-postgres/src/EventLogStorage_Postgres.res.mjs";
+import * as DcbEventLogStorage_Postgres$ReventlessPostgres from "@reventlessdev/reventless-postgres/src/DcbEventLogStorage_Postgres.res.mjs";
+
+let runMigrationWithPool = (async (pool) => {
+    const { runMigration } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/PgMigrationEntryPoint.mjs"
+    );
+    const config = {
+      pgConnection: {
+        host: "ignored", port: 5432, database: "ignored",
+        username: "ignored", secretArn: "ignored",
+      },
+    };
+    return await runMigration(config, { makePool: () => pool });
+  });
+
+let runMigrationMissingConfigThrows = (async () => {
+    const { runMigration } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/PgMigrationEntryPoint.mjs"
+    );
+    try { await runMigration({}, {}); return false; }
+    catch { return true; }
+  });
+
+globalThis.describe("PgMigrationEntryPoint.runMigration", () => {
+  globalThis.test("rejects a HANDLER_CONFIG with no pgConnection", async () => {
+    let threw = await runMigrationMissingConfigThrows();
+    globalThis.expect(threw).toBe(true);
+  });
+  let url = process.env["PG_URL"];
+  if (url !== undefined) {
+    let pool = PgDriver$ReventlessPostgres.makePool({
+      connectionString: url
+    });
+    globalThis.afterAll(() => {
+      PgDriver$ReventlessPostgres.endPool(pool);
+    });
+    globalThis.test("runs ensureSchema, leaving both event logs queryable", async () => {
+      await runMigrationWithPool(pool);
+      let classicCount = await EventLogStorage_Postgres$ReventlessPostgres.countAll(pool);
+      let dcbCount = await DcbEventLogStorage_Postgres$ReventlessPostgres.countAll(pool);
+      globalThis.expect(classicCount >= 0 && dcbCount >= 0).toBe(true);
+    });
+    globalThis.test("is idempotent — a second run does not throw", async () => {
+      await runMigrationWithPool(pool);
+      let again = await runMigrationWithPool(pool);
+      globalThis.expect(again).toBe("ok");
+    });
+    return;
+  }
+  globalThis.test("live migration (skipped — set PG_URL to run)", () => {
+    globalThis.expect(true).toBe(true);
+  });
+});
+
+export {
+  runMigrationWithPool,
+  runMigrationMissingConfigThrows,
+}
+/* runMigrationWithPool Not a pure module */

package/tests/PgPipeline_IntegrationTest.res

@@ -1,6 +1,8 @@
 // End-to-end Postgres projection pipeline (B1 + B3.0 + B3.1 composed), minus AWS.
 //
-// Skipped unless PG_URL is set. Exercises the full deployed classic path against
+// 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. Exercises the full deployed classic path against
 // a real database:
 //   classic append (`event_log`) → change-feed relay (`relayClassicWithPool`,
 //   emitting the EventCollector `{id, meta, event}` bodies) → feed-queue SQS