@reventlessdev/reventless-aws 3.0.0-alpha.276 → 3.0.0-alpha.278

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.278 (2026-08-09)
+
+**Note:** Version bump only for package @reventlessdev/reventless-aws
+
+
+
+
+
+# 3.0.0-alpha.277 (2026-08-09)
+
+### Features
+
+* **core,aws:** bundle a runtime extension's companion packages, guard imports at deploy ([e975175](https://github.com/ReventlessDev/reventless-core/commit/e9751758f51582a8e46db362219f725bb5f1bcde))
+
+
 # 3.0.0-alpha.276 (2026-08-09)
 
 **Note:** Version bump only for package @reventlessdev/reventless-aws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.276",
+  "version": "3.0.0-alpha.278",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -12,18 +12,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.5",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.68",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.3",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.6",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.69",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.219",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.130",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.221",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.132",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.83",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.104",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.85",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.106"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/util/Util_Bundle.res

@@ -256,17 +256,138 @@ let runtimeExtensionSpecifiers = (): array<string> =>
   ReventlessCore.RuntimeExtension.moduleUrls()->Array.map(getModuleSpecifier)
 
 /**
- * Add every registered runtime extension's package to `packageDirs`, so the
- * archive carries the modules the entry shell imports at cold start.
+ * Add every registered runtime extension's package to `packageDirs` — and every
+ * package its `companionModuleUrls` name — so the archive carries both the
+ * modules the entry shell imports at cold start and the packages those modules
+ * import. Companions are bundle-only: they never appear in `RUNTIME_EXTENSIONS`;
+ * Node resolves them from the archive's `node_modules` when the extension's own
+ * import runs.
  *
  * Rooted through `getModuleSpecifier`, which caches the package root it walked
  * to. That matters: an extension is an out-of-tree package the framework has no
- * dependency on, so a framework-rooted `require.resolve` would not find it.
+ * dependency on, so a framework-rooted `require.resolve` would not find it —
+ * and the same holds for its companions, which is why the contract asks for a
+ * module URL per companion rather than a bare package name.
+ *
+ * Returns the packages this mechanism put into the archive (name → root): the
+ * set `assertRuntimeExtensionImportsResolvable` scans.
  */
-let addRuntimeExtensionPackages = (packageDirs: dict<string>) =>
-  runtimeExtensionSpecifiers()->Array.forEach(specifier => {
+let addRuntimeExtensionPackages = (packageDirs: dict<string>): dict<string> => {
+  let added: dict<string> = Dict.make()
+  runtimeExtensionSpecifiers()
+  ->Array.concat(
+    ReventlessCore.RuntimeExtension.companionModuleUrls()->Array.map(getModuleSpecifier),
+  )
+  ->Array.forEach(specifier => {
     let pkgName = extractPackageName(specifier)
-    packageDirs->Dict.set(pkgName, resolvePackageRoot(pkgName))
+    let root = resolvePackageRoot(pkgName)
+    packageDirs->Dict.set(pkgName, root)
+    added->Dict.set(pkgName, root)
+  })
+  added
+}
+
+/**
+ * The bare package specifiers of a module source's static top-level `import` /
+ * re-`export` declarations. A regex, not a parser: `import` declarations are
+ * only legal at a module's top level, so line-anchored matching is exact up to
+ * strings/comments that spell out an import — an acceptable imprecision for a
+ * guard (see `assertRuntimeExtensionImportsResolvable`). Dynamic `import()`
+ * deliberately does not match.
+ */
+let staticImportSpecifiers = (source: string): array<string> => {
+  let re = RegExp.fromString(
+    "(?:^|\\n)\\s*(?:import|export)\\s*(?:[\\w$*{},\\s]+?from\\s*)?[\"']([^\"']+)[\"']",
+    ~flags="g",
+  )
+  let specifiers: array<string> = []
+  let scanning = ref(true)
+  while scanning.contents {
+    switch re->RegExp.exec(source) {
+    | Some(result) =>
+      switch result->RegExp.Result.matches->Array.getUnsafe(0) {
+      | Some(specifier) => specifiers->Array.push(specifier)
+      | None => ()
+      }
+    | None => scanning := false
+    }
+  }
+  specifiers
+}
+
+let isBareSpecifier = (s: string) =>
+  !(s->String.startsWith(".")) &&
+  !(s->String.startsWith("/")) &&
+  !(s->String.startsWith("file:")) &&
+  !(s->String.startsWith("data:")) &&
+  // `#…` is a package-internal `imports` alias, resolved inside the package.
+  !(s->String.startsWith("#"))
+
+let nodeBuiltins = Set.fromArray(NodeModule.builtinModules)
+
+/**
+ * Whether a deployed runtime resolves this bare specifier without it riding in
+ * the archive: Node builtins, the @aws-sdk and @smithy scopes reachable through
+ * the ESM fallback dirs (runtime SDK dir and layer), or a package resolvable
+ * from the framework — an approximation of the Lambda layer, which bundles
+ * reventless-aws's dependency closure. The approximation errs toward passing
+ * (workspace hoisting can resolve more than the layer carries); a false pass
+ * still lands on the explicit `companionModuleUrls` declaration.
+ */
+let isRuntimeProvided = (specifier: string, ~pkgName: string): bool =>
+  specifier->String.startsWith("node:") ||
+  nodeBuiltins->Set.has(specifier) ||
+  nodeBuiltins->Set.has(pkgName) ||
+  pkgName->String.startsWith("@aws-sdk/") ||
+  pkgName->String.startsWith("@smithy/") ||
+  (
+    try {
+      let _ = resolvePackageRoot(pkgName)
+      true
+    } catch {
+    | _ => false
+    }
+  )
+
+/**
+ * Deploy-time guard: every bare package statically imported by a bundled
+ * runtime-extension (or companion) package must either be in the archive
+ * (`bundledPackages`) or be provided by the deployed runtime. Throws at archive
+ * build on a miss, naming the package, the file, the specifier and the
+ * `companionModuleUrls` remedy.
+ *
+ * Without this the failure mode is the worst kind: the deploy is green, the
+ * entry shell catches the load failure by design, logs at ERROR and fires zero
+ * extensions — the feature the extension carries is silently off on every cold
+ * start. Static parsing is a partial truth (dynamic `import()` escapes it),
+ * which is exactly why it is the check and not the mechanism: a false negative
+ * here still lands on the explicit declaration; the declaration never depends
+ * on parsing.
+ */
+let assertRuntimeExtensionImportsResolvable = (
+  ~extensionPackages: dict<string>,
+  ~bundledPackages: dict<string>,
+) =>
+  extensionPackages->Dict.forEachWithKey((pkgRoot, pkgName) => {
+    let assets: dict<Pulumi.Archive.assetOrArchive> = Dict.make()
+    let paths: array<(string, string)> = []
+    walkDir(~dir=pkgRoot, ~prefix="", ~assets, ~paths)
+    paths->Array.forEach(((relPath, absPath)) =>
+      if relPath->String.endsWith(".mjs") || relPath->String.endsWith(".js") {
+        NodeFs.readFileSync(absPath)
+        ->staticImportSpecifiers
+        ->Array.forEach(specifier =>
+          if isBareSpecifier(specifier) {
+            let dep = extractPackageName(specifier)
+            if !(bundledPackages->Dict.has(dep)) && !isRuntimeProvided(specifier, ~pkgName=dep) {
+              JsError.throwWithMessage(
+                `runtime extension package "${pkgName}" imports "${specifier}" (${relPath}), which is neither bundled into the code archive nor provided in the deployed runtime. The extension would be skipped at every cold start with "could not be loaded". Declare the package in the extension's companionModuleUrls — the import.meta.url of one of its modules — so it rides into the archive alongside the extension.`,
+              )
+            }
+          }
+        )
+      }
+    )
   })
 
 /**
@@ -322,11 +443,15 @@ let buildCodeArchive = (
     } else {
       packageDirs
     }
-  // Registered runtime extensions ride along, so the entry shell can import them
-  // at cold start. No-op when nothing is registered — the archive, and therefore
-  // `sourceCodeHash`, is unchanged.
+  // Registered runtime extensions ride along (with their declared companion
+  // packages), so the entry shell can import them at cold start. No-op when
+  // nothing is registered — the archive, and therefore `sourceCodeHash`, is
+  // unchanged. The guard then fails the deploy on any statically imported
+  // package that would not resolve at cold start — the alternative is a green
+  // deploy whose extensions are silently skipped.
   if bundleRuntimeExtensions {
-    allPackageDirs->addRuntimeExtensionPackages
+    let extensionPackages = allPackageDirs->addRuntimeExtensionPackages
+    assertRuntimeExtensionImportsResolvable(~extensionPackages, ~bundledPackages=allPackageDirs)
   }
   let packageContentHashes: ref<array<string>> = ref([])
   allPackageDirs->Dict.forEachWithKey((pkgRoot, pkgName) => {

package/src/util/Util_Bundle.res.mjs

@@ -182,9 +182,76 @@ function runtimeExtensionSpecifiers() {
 }
 
 function addRuntimeExtensionPackages(packageDirs) {
-  RuntimeExtension$ReventlessCore.moduleUrls().map(getModuleSpecifier).forEach(specifier => {
+  let added = {};
+  RuntimeExtension$ReventlessCore.moduleUrls().map(getModuleSpecifier).concat(RuntimeExtension$ReventlessCore.companionModuleUrls().map(getModuleSpecifier)).forEach(specifier => {
     let pkgName = extractPackageName(specifier);
-    packageDirs[pkgName] = resolvePackageRoot(undefined, pkgName);
+    let root = resolvePackageRoot(undefined, pkgName);
+    packageDirs[pkgName] = root;
+    added[pkgName] = root;
+  });
+  return added;
+}
+
+function staticImportSpecifiers(source) {
+  let re = new RegExp("(?:^|\\n)\\s*(?:import|export)\\s*(?:[\\w$*{},\\s]+?from\\s*)?[\"']([^\"']+)[\"']", "g");
+  let specifiers = [];
+  let scanning = true;
+  while (scanning) {
+    let result = re.exec(source);
+    if (result == null) {
+      scanning = false;
+    } else {
+      let specifier = result.slice(1)[0];
+      if (specifier !== undefined) {
+        specifiers.push(specifier);
+      }
+    }
+  };
+  return specifiers;
+}
+
+function isBareSpecifier(s) {
+  if (!s.startsWith(".") && !s.startsWith("/") && !s.startsWith("file:") && !s.startsWith("data:")) {
+    return !s.startsWith("#");
+  } else {
+    return false;
+  }
+}
+
+let nodeBuiltins = new Set(Nodemodule.builtinModules);
+
+function isRuntimeProvided(specifier, pkgName) {
+  if (specifier.startsWith("node:") || nodeBuiltins.has(specifier) || nodeBuiltins.has(pkgName) || pkgName.startsWith("@aws-sdk/") || pkgName.startsWith("@smithy/")) {
+    return true;
+  }
+  try {
+    resolvePackageRoot(undefined, pkgName);
+    return true;
+  } catch (exn) {
+    return false;
+  }
+}
+
+function assertRuntimeExtensionImportsResolvable(extensionPackages, bundledPackages) {
+  Stdlib_Dict.forEachWithKey(extensionPackages, (pkgRoot, pkgName) => {
+    let assets = {};
+    let paths = [];
+    walkDir(pkgRoot, "", assets, paths);
+    paths.forEach(param => {
+      let relPath = param[0];
+      if (relPath.endsWith(".mjs") || relPath.endsWith(".js")) {
+        staticImportSpecifiers(Nodefs.readFileSync(param[1], "utf8")).forEach(specifier => {
+          if (!isBareSpecifier(specifier)) {
+            return;
+          }
+          let dep = extractPackageName(specifier);
+          if (!(dep in bundledPackages) && !isRuntimeProvided(specifier, dep)) {
+            return Stdlib_JsError.throwWithMessage(`runtime extension package "` + pkgName + `" imports "` + specifier + `" (` + relPath + `), which is neither bundled into the code archive nor provided in the deployed runtime. The extension would be skipped at every cold start with "could not be loaded". Declare the package in the extension's companionModuleUrls — the import.meta.url of one of its modules — so it rides into the archive alongside the extension.`);
+          }
+        });
+        return;
+      }
+    });
   });
 }
 
@@ -207,7 +274,8 @@ function buildCodeArchive(entryPointModule, packageDirs, extraStringAssetsOpt, b
     allPackageDirs = packageDirs;
   }
   if (bundleRuntimeExtensions) {
-    addRuntimeExtensionPackages(allPackageDirs);
+    let extensionPackages = addRuntimeExtensionPackages(allPackageDirs);
+    assertRuntimeExtensionImportsResolvable(extensionPackages, allPackageDirs);
   }
   let packageContentHashes = {
     contents: []
@@ -254,6 +322,11 @@ export {
   createFilteredPackageArchive,
   runtimeExtensionSpecifiers,
   addRuntimeExtensionPackages,
+  staticImportSpecifiers,
+  isBareSpecifier,
+  nodeBuiltins,
+  isRuntimeProvided,
+  assertRuntimeExtensionImportsResolvable,
   buildCodeArchive,
 }
 /* localRequire Not a pure module */

package/tests/Util_BundleRuntimeExtensionTest.res

@@ -0,0 +1,172 @@
+open JestGlobals
+
+// The companion half of the runtime-extension seam: an extension declares the
+// packages its runtime import graph reaches (`companionModuleUrls`), the
+// bundler carries them into the archive, and the archive build fails loudly on
+// any statically imported package that would not resolve at cold start. See
+// docs/plans/runtime-extension-companion-packages.md.
+
+// realpath because macOS hands out /var/... symlinks for tmpdir while the
+// package-root walk reports paths as given.
+let makePkg = (name: string, files: array<(string, string)>): string => {
+  let root = NodeFs.realpathSync(NodeFs.mkdtempSync(NodePath.join([NodeOs.tmpdir(), "rt-ext-"])))
+  NodeFs.writeFileSync(
+    NodePath.join([root, "package.json"]),
+    `{"name":"${name}","version":"1.0.0"}`,
+  )
+  files->Array.forEach(((relPath, content)) => {
+    let abs = NodePath.join([root, relPath])
+    NodeFs.mkdirSync(NodePath.dirname(abs), {recursive: true})
+    NodeFs.writeFileSync(abs, content)
+  })
+  root
+}
+
+let fileUrl = (absPath: string) => "file://" ++ absPath
+
+let extensionModule = (~companions: array<string>=[], url: string): module(
+  ReventlessCore.RuntimeExtension.Extension
+) => {
+  module E = {
+    let moduleUrl = url
+    let companionModuleUrls = companions
+    let onColdStart = (~runtimeKind as _, ~component as _, ~plugin as _, ~platform as _) => ()
+  }
+  module(E: ReventlessCore.RuntimeExtension.Extension)
+}
+
+let caughtMessage = (run: unit => unit): option<string> =>
+  try {
+    run()
+    None
+  } catch {
+  | exn => Some(exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr(""))
+  }
+
+// One extension package whose artifact imports its companion plus one specifier
+// from every runtime-provided class the guard must wave through: a node:
+// builtin, a bare builtin, a framework dependency (the layer approximation),
+// and the @aws-sdk scope (runtime SDK dir).
+let extPkgName = "@fixture/runtime-ext"
+let companionPkgName = "@fixture/runtime-ext-companion"
+let extRoot = makePkg(
+  extPkgName,
+  [
+    (
+      "src/Ext_Extension.res.mjs",
+      `import * as Companion from "${companionPkgName}";
+import * as Fs from "node:fs";
+import * as Path from "path";
+import * as Effect from "effect";
+import * as Ddb from "@aws-sdk/client-dynamodb";
+export const moduleUrl = import.meta.url;
+export const onColdStart = () => Companion.mark(Fs, Path, Effect, Ddb);
+`,
+    ),
+  ],
+)
+let companionRoot = makePkg(
+  companionPkgName,
+  [
+    (
+      "src/Companion.res.mjs",
+      `export const moduleUrl = import.meta.url;
+export const mark = (x) => x;
+`,
+    ),
+  ],
+)
+let extUrl = fileUrl(NodePath.join([extRoot, "src/Ext_Extension.res.mjs"]))
+let companionUrl = fileUrl(NodePath.join([companionRoot, "src/Companion.res.mjs"]))
+
+let badPkgName = "@fixture/runtime-ext-bad"
+let badRoot = makePkg(
+  badPkgName,
+  [
+    (
+      "src/Bad_Extension.res.mjs",
+      `import * as Missing from "@fixture/never-declared";
+export const moduleUrl = import.meta.url;
+export const onColdStart = () => Missing.x;
+`,
+    ),
+  ],
+)
+let badUrl = fileUrl(NodePath.join([badRoot, "src/Bad_Extension.res.mjs"]))
+
+let build = () =>
+  Util_Bundle.buildCodeArchive(
+    ~entryPointModule="@reventlessdev/reventless-aws/src/adapter/Runtime/Entry.res.mjs",
+    ~packageDirs=Dict.make(),
+  )
+
+describe("Util_Bundle — runtime-extension companion packages", () => {
+  beforeEach(() => ReventlessCore.RuntimeExtension.reset())
+  afterAll(() => {
+    ReventlessCore.RuntimeExtension.reset()
+    [extRoot, companionRoot, badRoot]->Array.forEach(root =>
+      NodeFs.rmSync(root, {recursive: true, force: true})
+    )
+  })
+
+  testSync("a declared companion package is added to the archive's package set", () => {
+    ReventlessCore.RuntimeExtension.use(extensionModule(~companions=[companionUrl], extUrl))
+
+    let packageDirs: dict<string> = Dict.make()
+    let added = Util_Bundle.addRuntimeExtensionPackages(packageDirs)
+
+    expect(packageDirs->Dict.get(extPkgName))->toEqual(Some(extRoot))
+    expect(packageDirs->Dict.get(companionPkgName))->toEqual(Some(companionRoot))
+    // The returned set — what the import guard scans — matches what was added.
+    expect(added->Dict.keysToArray->Array.toSorted(String.compare))->toEqual([
+      extPkgName,
+      companionPkgName,
+    ])
+  })
+
+  testSync("the archive builds when every import is declared or runtime-provided", () => {
+    ReventlessCore.RuntimeExtension.use(extensionModule(~companions=[companionUrl], extUrl))
+    expect(build().sourceCodeHash->String.length > 0)->toBe(true)
+  })
+
+  testSync("sourceCodeHash shifts when the companion's content shifts", () => {
+    ReventlessCore.RuntimeExtension.use(extensionModule(~companions=[companionUrl], extUrl))
+    let before = build().sourceCodeHash
+
+    let companionFile = NodePath.join([companionRoot, "src/Companion.res.mjs"])
+    let original = NodeFs.readFileSync(companionFile)
+    NodeFs.writeFileSync(
+      companionFile,
+      original ++ "export const changed = true;\n",
+    )
+    let after = build().sourceCodeHash
+    NodeFs.writeFileSync(companionFile, original)
+
+    expect(before == after)->toBe(false)
+  })
+
+  testSync("an empty registry leaves the archive byte-identical", () => {
+    let withSeam = build().sourceCodeHash
+    let withoutSeam =
+      Util_Bundle.buildCodeArchive(
+        ~entryPointModule="@reventlessdev/reventless-aws/src/adapter/Runtime/Entry.res.mjs",
+        ~packageDirs=Dict.make(),
+        ~bundleRuntimeExtensions=false,
+      ).sourceCodeHash
+    expect(withSeam)->toBe(withoutSeam)
+  })
+
+  testSync("an undeclared, un-bundled import fails the archive build, naming the remedy", () => {
+    ReventlessCore.RuntimeExtension.use(extensionModule(badUrl))
+
+    switch caughtMessage(() => {
+      let _ = build()
+    }) {
+    | None => JsError.throwWithMessage("expected buildCodeArchive to throw")
+    | Some(message) =>
+      expect(message->String.includes(badPkgName))->toBe(true)
+      expect(message->String.includes("@fixture/never-declared"))->toBe(true)
+      expect(message->String.includes("companionModuleUrls"))->toBe(true)
+    }
+  })
+})

package/tests/Util_BundleRuntimeExtensionTest.res.mjs

@@ -0,0 +1,171 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeos from "node:os";
+import * as Nodepath from "node:path";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Util_Bundle$ReventlessAws from "../src/util/Util_Bundle.res.mjs";
+import * as RuntimeExtension$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/RuntimeExtension/RuntimeExtension.res.mjs";
+
+function makePkg(name, files) {
+  let root = Nodefs.realpathSync(Nodefs.mkdtempSync(Nodepath.join(Nodeos.tmpdir(), "rt-ext-")));
+  Nodefs.writeFileSync(Nodepath.join(root, "package.json"), `{"name":"` + name + `","version":"1.0.0"}`, "utf8");
+  files.forEach(param => {
+    let abs = Nodepath.join(root, param[0]);
+    Nodefs.mkdirSync(Nodepath.dirname(abs), {
+      recursive: true
+    });
+    Nodefs.writeFileSync(abs, param[1], "utf8");
+  });
+  return root;
+}
+
+function fileUrl(absPath) {
+  return "file://" + absPath;
+}
+
+function extensionModule(companionsOpt, url) {
+  let companions = companionsOpt !== undefined ? companionsOpt : [];
+  let onColdStart = (param, param$1, param$2, param$3) => {};
+  return {
+    moduleUrl: url,
+    companionModuleUrls: companions,
+    onColdStart: onColdStart
+  };
+}
+
+function caughtMessage(run) {
+  try {
+    run();
+    return;
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "");
+  }
+}
+
+let extPkgName = "@fixture/runtime-ext";
+
+let companionPkgName = "@fixture/runtime-ext-companion";
+
+let extRoot = makePkg(extPkgName, [[
+    "src/Ext_Extension.res.mjs",
+    `import * as Companion from "` + companionPkgName + `";
+import * as Fs from "node:fs";
+import * as Path from "path";
+import * as Effect from "effect";
+import * as Ddb from "@aws-sdk/client-dynamodb";
+export const moduleUrl = import.meta.url;
+export const onColdStart = () => Companion.mark(Fs, Path, Effect, Ddb);
+`
+  ]]);
+
+let companionRoot = makePkg(companionPkgName, [[
+    "src/Companion.res.mjs",
+    `export const moduleUrl = import.meta.url;
+export const mark = (x) => x;
+`
+  ]]);
+
+let extUrl = "file://" + Nodepath.join(extRoot, "src/Ext_Extension.res.mjs");
+
+let companionUrl = "file://" + Nodepath.join(companionRoot, "src/Companion.res.mjs");
+
+let badPkgName = "@fixture/runtime-ext-bad";
+
+let badRoot = makePkg(badPkgName, [[
+    "src/Bad_Extension.res.mjs",
+    `import * as Missing from "@fixture/never-declared";
+export const moduleUrl = import.meta.url;
+export const onColdStart = () => Missing.x;
+`
+  ]]);
+
+let badUrl = "file://" + Nodepath.join(badRoot, "src/Bad_Extension.res.mjs");
+
+function build() {
+  return Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/Entry.res.mjs", {}, undefined, undefined);
+}
+
+globalThis.describe("Util_Bundle — runtime-extension companion packages", () => {
+  globalThis.beforeEach(() => RuntimeExtension$ReventlessCore.reset());
+  globalThis.afterAll(() => {
+    RuntimeExtension$ReventlessCore.reset();
+    [
+      extRoot,
+      companionRoot,
+      badRoot
+    ].forEach(root => {
+      Nodefs.rmSync(root, {
+        recursive: true,
+        force: true
+      });
+    });
+  });
+  globalThis.test("a declared companion package is added to the archive's package set", () => {
+    RuntimeExtension$ReventlessCore.use(extensionModule([companionUrl], extUrl));
+    let packageDirs = {};
+    let added = Util_Bundle$ReventlessAws.addRuntimeExtensionPackages(packageDirs);
+    globalThis.expect(packageDirs[extPkgName]).toEqual(extRoot);
+    globalThis.expect(packageDirs[companionPkgName]).toEqual(companionRoot);
+    globalThis.expect(Object.keys(added).toSorted(Primitive_string.compare)).toEqual([
+      extPkgName,
+      companionPkgName
+    ]);
+  });
+  globalThis.test("the archive builds when every import is declared or runtime-provided", () => {
+    RuntimeExtension$ReventlessCore.use(extensionModule([companionUrl], extUrl));
+    globalThis.expect(build().sourceCodeHash.length > 0).toBe(true);
+  });
+  globalThis.test("sourceCodeHash shifts when the companion's content shifts", () => {
+    RuntimeExtension$ReventlessCore.use(extensionModule([companionUrl], extUrl));
+    let before = build().sourceCodeHash;
+    let companionFile = Nodepath.join(companionRoot, "src/Companion.res.mjs");
+    let original = Nodefs.readFileSync(companionFile, "utf8");
+    Nodefs.writeFileSync(companionFile, original + "export const changed = true;\n", "utf8");
+    let after = build().sourceCodeHash;
+    Nodefs.writeFileSync(companionFile, original, "utf8");
+    globalThis.expect(before === after).toBe(false);
+  });
+  globalThis.test("an empty registry leaves the archive byte-identical", () => {
+    let withSeam = build().sourceCodeHash;
+    let withoutSeam = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/Entry.res.mjs", {}, undefined, false).sourceCodeHash;
+    globalThis.expect(withSeam).toBe(withoutSeam);
+  });
+  globalThis.test("an undeclared, un-bundled import fails the archive build, naming the remedy", () => {
+    RuntimeExtension$ReventlessCore.use(extensionModule(undefined, badUrl));
+    let message = caughtMessage(() => {
+      build();
+    });
+    if (message !== undefined) {
+      globalThis.expect(message.includes(badPkgName)).toBe(true);
+      globalThis.expect(message.includes("@fixture/never-declared")).toBe(true);
+      globalThis.expect(message.includes("companionModuleUrls")).toBe(true);
+      return;
+    } else {
+      return Stdlib_JsError.throwWithMessage("expected buildCodeArchive to throw");
+    }
+  });
+});
+
+export {
+  makePkg,
+  fileUrl,
+  extensionModule,
+  caughtMessage,
+  extPkgName,
+  companionPkgName,
+  extRoot,
+  companionRoot,
+  extUrl,
+  companionUrl,
+  badPkgName,
+  badRoot,
+  badUrl,
+  build,
+}
+/* extRoot Not a pure module */