feat(compartment-mapper): Thread native flag to opt-in for native XS …

…runtime modules
endojs · Oct 18, 2024 · dfeb0a4 · dfeb0a4
1 parent cbd6814
commit dfeb0a4
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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]
  */