From 15628bc136241f085988efd3bcb2dbac529a0821 Mon Sep 17 00:00:00 2001
From: Kris Kowal <kris@agoric.com>
Date: Tue, 8 Oct 2024 22:52:59 -0700
Subject: [PATCH] feat(compartment-mapper): Thread native flag to opt-in for
 native XS runtime modules

---
 packages/compartment-mapper/NEWS.md                |  9 +++++++++
 packages/compartment-mapper/README.md              | 14 ++++++++++++++
 .../compartment-mapper/src/import-archive-lite.js  |  2 ++
 packages/compartment-mapper/src/import-lite.js     |  3 +++
 packages/compartment-mapper/src/link.js            |  2 ++
 packages/compartment-mapper/src/types.js           |  3 +++
 6 files changed, 33 insertions(+)

diff --git a/packages/compartment-mapper/NEWS.md b/packages/compartment-mapper/NEWS.md
index c47d55de5c..f992833183 100644
--- a/packages/compartment-mapper/NEWS.md
+++ b/packages/compartment-mapper/NEWS.md
@@ -30,6 +30,15 @@ Experimental:
   enabled by default. See the signature of `loadFromMap()` in `import-lite.js`
   for details.
 
+Experimental:
+
+- Adds a `__native__: true` option to all paths to import, that indicates that
+  the application will fall through to the native implementation of
+  Compartment, currently only available on XS, which lacks support for
+  precompiled module sources (as exist in many archived applications,
+  particularly Agoric smart contract bundles) and instead supports loading
+  modules from original sources (which is not possible at runtime on XS).
+
 # v1.2.0 (2024-07-30)
 
 - Fixes incompatible behavior with Node.js package conditional exports #2276.
diff --git a/packages/compartment-mapper/README.md b/packages/compartment-mapper/README.md
index 4013b692ec..166fb046d2 100644
--- a/packages/compartment-mapper/README.md
+++ b/packages/compartment-mapper/README.md
@@ -305,6 +305,20 @@ These will be appended to each module from the archive, for debugging purposes.
 The `@endo/bundle-source` and `@endo/import-bundle` tools integrate source maps
 for an end-to-end debugging experience.
 
+# XS (experimental)
+
+The Compartment Mapper can use native XS `Compartment` and `ModuleSource` under
+certain conditions:
+
+1. The application must be an XS script that was compiled with the `xs`
+  package condition.
+  This causes `ses`, `@endo/module-source`, and `@endo/import-bundle` to
+  provide slightly different implementations that can fall through to native
+  behavior.
+2. The application must opt-in with the `__native__: true` option on any
+  of the compartment mapper methods that import modules like `importLocation`
+  and `importArchive`.
+
 # Design
 
 Each of the workflows the compartment mapper executes a portion of one sequence
diff --git a/packages/compartment-mapper/src/import-archive-lite.js b/packages/compartment-mapper/src/import-archive-lite.js
index 6d48630f7d..270817892c 100644
--- a/packages/compartment-mapper/src/import-archive-lite.js
+++ b/packages/compartment-mapper/src/import-archive-lite.js
@@ -373,6 +373,7 @@ export const parseArchive = async (
       modules,
       transforms,
       __shimTransforms__,
+      __native__,
       Compartment,
       importHook: exitModuleImportHook,
     } = options || {};
@@ -399,6 +400,7 @@ export const parseArchive = async (
       modules,
       transforms,
       __shimTransforms__,
+      __native__,
       Compartment,
     });
 
diff --git a/packages/compartment-mapper/src/import-lite.js b/packages/compartment-mapper/src/import-lite.js
index 408ac58a23..1943a3ad9c 100644
--- a/packages/compartment-mapper/src/import-lite.js
+++ b/packages/compartment-mapper/src/import-lite.js
@@ -150,6 +150,7 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
       modules,
       transforms,
       __shimTransforms__,
+      __native__,
       Compartment,
       importHook: exitModuleImportHook,
     } = options;
@@ -199,6 +200,7 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
         transforms,
         syncModuleTransforms,
         __shimTransforms__,
+        __native__,
         Compartment,
       }));
     } else {
@@ -214,6 +216,7 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
         moduleTransforms,
         syncModuleTransforms,
         __shimTransforms__,
+        __native__,
         Compartment,
       }));
     }
diff --git a/packages/compartment-mapper/src/link.js b/packages/compartment-mapper/src/link.js
index d099f9adbb..b0b184e846 100644
--- a/packages/compartment-mapper/src/link.js
+++ b/packages/compartment-mapper/src/link.js
@@ -258,6 +258,7 @@ export const link = (
     moduleTransforms,
     syncModuleTransforms,
     __shimTransforms__ = [],
+    __native__ = false,
     archiveOnly = false,
     Compartment = defaultCompartment,
   } = options;
@@ -379,6 +380,7 @@ export const link = (
       transforms,
       __shimTransforms__,
       __options__: true,
+      __native__,
     });
 
     if (!archiveOnly) {
diff --git a/packages/compartment-mapper/src/types.js b/packages/compartment-mapper/src/types.js
index f022c9f032..4054bcfcd8 100644
--- a/packages/compartment-mapper/src/types.js
+++ b/packages/compartment-mapper/src/types.js
@@ -440,6 +440,7 @@ export {};
  * @property {object} [globals]
  * @property {Array<Transform>} [transforms]
  * @property {Array<Transform>} [__shimTransforms__]
+ * @property {boolean} [__native__] Use native Compartment and native
  * @property {Record<string, object>} [modules]
  * @property {ExitModuleImportHook} [importHook]
  * @property {Record<string, object>} [attenuations]
@@ -480,6 +481,8 @@ export {};
  * @property {LanguageForExtension} [languageForExtension]
  * @property {ModuleTransforms} [moduleTransforms]
  * @property {SyncModuleTransforms} [syncModuleTransforms]
+ * @property {boolean} [__native__] Use native Compartment and native
+ * ModuleSource (XS only at time of writing)
  * @property {boolean} [archiveOnly]
  */