@peers-app/peers-sdk 0.23.4 → 0.23.5

package/dist/package-loader/package-loader.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageLoader = void 0;
 exports.setDefaultRequire = setDefaultRequire;
+const contract_provider_router_1 = require("../contracts/contract-provider-router");
+const contract_proxy_1 = require("../contracts/contract-proxy");
+const contract_resolvers_1 = require("../contracts/contract-resolvers");
+const contract_transport_1 = require("../contracts/contract-transport");
 const registry_1 = require("../contracts/registry");
 const system_contracts_1 = require("../contracts/system-contracts");
 const files_1 = require("../data/files");
@@ -11,51 +15,329 @@ const packages_1 = require("../data/packages");
 const tools_1 = require("../data/tools");
 const tools_2 = require("../tools");
 const contract_package_loader_1 = require("./contract-package-loader");
+const isolated_artifact_1 = require("./isolated-artifact");
+const isolated_persistent_var_gateway_1 = require("./isolated-persistent-var-gateway");
+const isolated_runtime_1 = require("./isolated-runtime");
+const isolated_table_gateway_1 = require("./isolated-table-gateway");
 const resolve_consumed_contracts_1 = require("./resolve-consumed-contracts");
 // Ensure built-in system contracts are cataloged before any PackageLoader installs them.
 require("../contracts/system");
+function isolatedContractLifecycle(packageVersion) {
+    return {
+        contractLifecycle: packageVersion?.versionTag === "dev" || packageVersion?.versionTag === "beta"
+            ? "mutable"
+            : "stable",
+        packageVersionId: packageVersion?.packageVersionId,
+        packageVersion: packageVersion?.version,
+        versionTag: packageVersion?.versionTag,
+    };
+}
+/**
+ * Loads package versions for one {@link DataContext}.
+ *
+ * Isolated artifacts (magic-header JSON) are installed without host
+ * evaluation. Legacy `package.bundle.js` files still evaluate in-process.
+ */
 class PackageLoader {
     dataContext;
+    /** Host-injected SDK module used as the `peers-sdk` / `PeersSDK` require. */
     static PeersSDK;
+    /** Host-injected Zod module used as the `zod` require. */
     static Zod;
     packageInstances = {};
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     contractInstalledPackages = new Set();
+    /** Packages installed through the isolated runtime (no host eval). */
+    isolatedPackageIds = new Set();
     /**
      * In-memory contract providers for this data context. Seeded with system
      * contracts at construction; package providers are added via
-     * {@link installContractPackage}.
+     * {@link installContractPackage} or the isolated runtime.
      */
     contractRegistry;
+    /** Optional isolated-provider supervisor created from the host factory. */
+    isolatedRuntime;
+    /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
     require = undefined;
+    /**
+     * @param dataContext - Owning personal or group data context. Its
+     *   `tableContainer` must already be assigned so isolated packages that
+     *   declare tables receive a host gateway.
+     */
     constructor(dataContext) {
         this.dataContext = dataContext;
         this.contractRegistry = new registry_1.ContractRegistry();
         (0, system_contracts_1.installSystemContracts)(this.contractRegistry);
+        const factory = (0, isolated_runtime_1.getIsolatedPackageRuntimeFactory)();
+        if (factory) {
+            this.isolatedRuntime = factory({
+                registry: this.contractRegistry,
+                dataContextId: dataContext.dataContextId,
+                tableGateway: dataContext.tableContainer
+                    ? (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)(dataContext)
+                    : undefined,
+                persistentVarGateway: dataContext.userContext
+                    ? (0, isolated_persistent_var_gateway_1.createIsolatedPackagePersistentVarGateway)(dataContext)
+                    : undefined,
+                providerGateway: {
+                    resolveEndpoint: (request) => this.resolveContractEndpoint(request, {
+                        providerPackageId: request.providerPackageId,
+                        resolverOnly: true,
+                    }),
+                },
+            });
+        }
     }
-    /** Returns true if a package was installed via the contract-based definePackage() path. */
+    /**
+     * Returns true if a package was installed via the contract-based
+     * `definePackage()` path or as an isolated artifact.
+     *
+     * @param packageId - Package to query.
+     */
     isContractInstalled(packageId) {
         return this.contractInstalledPackages.has(packageId);
     }
+    /**
+     * Returns true if `packageId` was installed as an isolated artifact.
+     *
+     * @param packageId - Package to query.
+     */
+    isIsolatedInstalled(packageId) {
+        return this.isolatedPackageIds.has(packageId);
+    }
+    /** Return whether this host configured an isolated-package runtime. */
+    supportsIsolatedPackages() {
+        return this.isolatedRuntime !== undefined;
+    }
+    /**
+     * Return the active provider selected by this data context's trusted registry.
+     *
+     * @param contractId - Target contract identity.
+     * @param version - Target contract version.
+     */
+    getActiveContractProviderPackageId(contractId, version) {
+        return this.contractRegistry.getProviderPackageId(contractId, version);
+    }
+    /**
+     * Resolve one authorized endpoint through the registry-selected provider.
+     *
+     * Isolated providers are delegated to the host runtime; resolver-backed
+     * providers are looked up by provider package. Contracts that predate package
+     * registration may still use their legacy unscoped resolver.
+     * Provider identity comes only from trusted registry/options state, never
+     * from an {@link import("../contracts/contract-proxy").IContractCall}.
+     *
+     * @param request - Authorized contract route and notification sink.
+     * @param opts - Trusted provider override and host-only resolver capabilities.
+     * @throws If no provider or matching endpoint implementation is available.
+     */
+    async resolveContractEndpoint(request, opts = {}) {
+        const providerPackageId = opts.providerPackageId ??
+            request.providerPackageId ??
+            this.contractRegistry.getProviderPackageId(request.contractId, request.version);
+        if (!providerPackageId) {
+            const legacyResolver = (0, contract_resolvers_1.getContractResolver)(request.contractId, request.version);
+            if (!legacyResolver) {
+                throw new Error(`No contract provider registered for ${request.contractId} v${request.version}`);
+            }
+            const resolution = await legacyResolver({ dataContext: this.dataContext });
+            const localResolution = opts.resolveVariable
+                ? {
+                    ...resolution,
+                    toolContext: {
+                        dataContextId: this.dataContext.dataContextId,
+                        getVariable: opts.resolveVariable,
+                    },
+                }
+                : resolution;
+            return (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
+                context: request.context,
+                notify: request.notify,
+            });
+        }
+        if (!this.contractRegistry
+            .getRegisteredProviderIds(request.contractId, request.version)
+            .includes(providerPackageId)) {
+            throw new Error(`Package ${providerPackageId} is not a registered provider for ${request.contractId} v${request.version}`);
+        }
+        const trustedRequest = {
+            ...request,
+            providerPackageId,
+        };
+        if (!opts.resolverOnly && this.isolatedRuntime?.isInstalled(providerPackageId)) {
+            const isolatedEndpoint = await this.isolatedRuntime.resolveEndpoint(trustedRequest);
+            if (!isolatedEndpoint) {
+                throw new Error(`Isolated provider ${providerPackageId} could not resolve ${request.contractId} v${request.version}`);
+            }
+            return isolatedEndpoint;
+        }
+        const implementation = this.contractRegistry.getProviderImplementation(request.contractId, request.version, providerPackageId) ?? {
+            contractId: request.contractId,
+            version: request.version,
+        };
+        const resolver = (0, contract_resolvers_1.getContractResolver)(implementation.contractId, implementation.version, providerPackageId);
+        if (!resolver) {
+            throw new Error(`Provider ${providerPackageId} has no live resolver for ${request.contractId} v${request.version}`);
+        }
+        const resolution = await resolver({ dataContext: this.dataContext });
+        const localResolution = opts.resolveVariable
+            ? {
+                ...resolution,
+                toolContext: {
+                    dataContextId: this.dataContext.dataContextId,
+                    getVariable: opts.resolveVariable,
+                },
+            }
+            : resolution;
+        const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(localResolution, {
+            context: request.context,
+            notify: (notification) => request.notify({
+                ...notification,
+                contractId: request.contractId,
+            }),
+        });
+        if (implementation.contractId === request.contractId &&
+            implementation.version === request.version) {
+            return endpoint;
+        }
+        return {
+            handleCall: (call, context) => endpoint.handleCall({
+                ...call,
+                contractId: implementation.contractId,
+                version: implementation.version,
+            }, context),
+            dispose: () => endpoint.dispose(),
+        };
+    }
+    /**
+     * Bind a legacy package's declared consume to its selected provider.
+     *
+     * The returned proxy can target either a resolver-backed or isolated provider.
+     * Its provider choice is captured from {@link ContractRegistry.selectProvider}
+     * before any consumer call payload is processed.
+     *
+     * @param dependency - Validated package consume declaration.
+     * @returns A live consumer proxy, or `undefined` when no provider matches.
+     */
+    async resolveConsumedContract(dependency) {
+        const selected = this.contractRegistry.selectProvider(dependency);
+        if (!selected) {
+            return undefined;
+        }
+        const providerPackageId = selected.providerPackageId;
+        const [consumerTransport, providerTransport] = (0, contract_transport_1.inProcessTransportPair)();
+        const router = (0, contract_provider_router_1.createContractProviderRouter)(providerTransport, {
+            authorizeCall: () => ({
+                dataContextId: this.dataContext.dataContextId,
+                context: { dataContext: this.dataContext },
+            }),
+            resolveProviderPackageId: () => providerPackageId,
+            resolveEndpoint: (request) => this.resolveContractEndpoint(request, { providerPackageId }),
+        });
+        const consumer = (0, contract_proxy_1.createContractConsumer)(selected.definition, consumerTransport, {
+            dataContextId: this.dataContext.dataContextId,
+        });
+        const dispose = consumer.dispose.bind(consumer);
+        consumer.dispose = () => {
+            dispose();
+            router.dispose();
+        };
+        return consumer;
+    }
+    /**
+     * Resolve a sandbox-backed provider endpoint when this context owns an
+     * isolated provider for the requested contract.
+     *
+     * @param request - Authorized contract/version/data-context route.
+     */
+    async resolveIsolatedEndpoint(request) {
+        const providerPackageId = request.providerPackageId ??
+            this.contractRegistry.getProviderPackageId(request.contractId, request.version);
+        if (!this.isolatedRuntime ||
+            !providerPackageId ||
+            !this.isolatedRuntime.isInstalled(providerPackageId)) {
+            return undefined;
+        }
+        return this.isolatedRuntime.resolveEndpoint({ ...request, providerPackageId });
+    }
+    /**
+     * Stop an isolated worker (if any) and drop the in-memory package instance.
+     *
+     * @param packageId - Package to unload.
+     */
+    async unloadPackage(packageId) {
+        if (this.isolatedRuntime?.isInstalled(packageId)) {
+            await this.isolatedRuntime.uninstall(packageId);
+        }
+        this.contractRegistry.unregister(packageId);
+        this.isolatedPackageIds.delete(packageId);
+        this.contractInstalledPackages.delete(packageId);
+        delete this.packageInstances[packageId];
+    }
+    /**
+     * Dispose the isolated runtime for this data context.
+     */
+    async dispose() {
+        if (this.isolatedRuntime) {
+            await this.isolatedRuntime.dispose();
+        }
+        this.isolatedPackageIds.clear();
+        this.contractInstalledPackages.clear();
+        this.packageInstances = {};
+    }
+    /**
+     * Resolve and load every non-disabled package in this data context.
+     * Disabled packages that were previously loaded are unloaded.
+     *
+     * @param opts - Forwarded to {@link resolveDevicePackageVersion}.
+     */
     async loadAllPackages(opts) {
         const packages = await (0, packages_1.Packages)(this.dataContext).list();
-        await Promise.all(packages
-            .filter((pkg) => !pkg.disabled)
-            .map((pkg) => (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, this.dataContext, opts)));
+        await Promise.all(packages.map(async (pkg) => {
+            if (pkg.disabled) {
+                await this.unloadPackage(pkg.packageId);
+                return;
+            }
+            try {
+                await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, this.dataContext, opts);
+            }
+            catch (error) {
+                console.warn(`[PackageLoader] Failed to load package "${pkg.name}" (${pkg.packageId}):`, error instanceof Error ? error.message : String(error));
+            }
+        }));
     }
+    /**
+     * Load one package version into this data context.
+     *
+     * Isolated artifacts are parsed and installed without evaluating provider
+     * source. A recognized but malformed isolated envelope fails closed and
+     * never falls back to `new Function`. When `localPath` points at a rebuilt
+     * isolated `dist/package.bundle.js`, that disk artifact wins over a stale
+     * stored Files bundle so local-dev packages pick up new contract versions.
+     *
+     * @param pkg - Package row.
+     * @param opts - Optional force reload, local path fallback, and PV id.
+     */
     async loadPackage(pkg, opts) {
+        if (pkg.disabled) {
+            await this.unloadPackage(pkg.packageId);
+            return undefined;
+        }
         if (this.packageInstances[pkg.packageId] && !opts?.force) {
             return this.packageInstances[pkg.packageId];
         }
         const localPath = opts?.localPath;
+        let selectedPackageVersion;
         try {
             let bundleCode = "";
+            let usingLocalBundle = false;
             let bundleFileId;
             const pvId = opts?.packageVersionId ?? pkg.activePackageVersionId;
             if (pvId) {
                 try {
                     const pv = await (0, package_versions_1.PackageVersions)(this.dataContext).get(pvId);
                     if (pv) {
+                        selectedPackageVersion = pv;
                         bundleFileId = pv.packageBundleFileId;
                     }
                 }
@@ -76,25 +358,33 @@ class PackageLoader {
             else {
                 console.warn(`Package ${pkg.name} does not have a bundle file defined.`);
             }
-            // Fallback: try loading from local path if stored bundle is not available
-            if (!bundleCode && localPath) {
-                bundleCode = this._readLocalBundle(localPath) ?? "";
+            if (localPath && selectedPackageVersion?.versionTag === "dev") {
+                const localBundleCode = this._readLocalBundle(localPath);
+                if (localBundleCode) {
+                    bundleCode = localBundleCode;
+                    usingLocalBundle = true;
+                }
             }
             if (!bundleCode)
                 return;
-            return this._evaluateBundle(pkg, bundleCode);
+            return await this._loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, opts?.force === true);
         }
         catch (err) {
-            // If stored bundle failed to evaluate, try local path as fallback
-            if (localPath) {
+            if (isIsolatedArtifactError(err)) {
+                throw err;
+            }
+            if (localPath && selectedPackageVersion?.versionTag === "dev") {
                 console.warn(`[PackageLoader] Stored bundle failed for ${pkg.name}, trying local path fallback`, err.message);
                 try {
                     const localBundleCode = this._readLocalBundle(localPath);
                     if (localBundleCode) {
-                        return this._evaluateBundle(pkg, localBundleCode);
+                        return await this._loadBundle(pkg, localBundleCode, selectedPackageVersion, true, opts?.force === true);
                     }
                 }
                 catch (localErr) {
+                    if (isIsolatedArtifactError(localErr)) {
+                        throw localErr;
+                    }
                     console.debug(`Could not load local bundle for ${pkg.name}`, localErr);
                 }
             }
@@ -117,40 +407,100 @@ class PackageLoader {
     }
     /**
      * Post-correction: if the package definition carries a version string,
-     * update the active IPackageVersion record to match — but only when that
-     * active version is the mutable `dev` working copy. Never rewrite
+     * update the selected IPackageVersion record to match — but only when that
+     * selected version is the mutable `dev` working copy. Never rewrite
      * beta/stable version labels from a local package.json bump.
      */
-    correctPackageVersion(pkg, def) {
-        if (!pkg.activePackageVersionId)
-            return;
-        if (!def.version)
+    async correctPackageVersion(pkg, selectedPackageVersion, declaredVersion) {
+        if (!selectedPackageVersion ||
+            selectedPackageVersion.versionTag !== "dev" ||
+            !declaredVersion ||
+            selectedPackageVersion.version === declaredVersion) {
             return;
-        const pvTable = (0, package_versions_1.PackageVersions)(this.dataContext);
-        pvTable
-            .get(pkg.activePackageVersionId)
-            .then((pv) => {
-            if (!pv)
-                return;
-            if (pv.versionTag !== "dev")
-                return;
-            if (def.version && pv.version !== def.version) {
-                const packageVersionHash = (0, package_versions_1.computePackageVersionHash)(def.version, pv.versionTag || "dev", pv.packageBundleFileHash, pv.routesBundleFileHash, pv.uiBundleFileHash);
-                // Version is part of both the content hash and the author-signed
-                // payload — clear any prior author signature so it cannot go stale.
-                const { packageAuthorSignature: _staleSig, ...rest } = pv;
-                return pvTable.signAndSave({
-                    ...rest,
-                    version: def.version,
-                    packageVersionHash,
-                });
+        }
+        try {
+            const packageVersionHash = (0, package_versions_1.computePackageVersionHash)(declaredVersion, selectedPackageVersion.versionTag, selectedPackageVersion.packageBundleFileHash, selectedPackageVersion.routesBundleFileHash, selectedPackageVersion.uiBundleFileHash);
+            // Version is part of both the content hash and the author-signed
+            // payload — clear any prior author signature so it cannot go stale.
+            const { packageAuthorSignature: _staleSig, ...rest } = selectedPackageVersion;
+            await (0, package_versions_1.PackageVersions)(this.dataContext).signAndSave({
+                ...rest,
+                version: declaredVersion,
+                packageVersionHash,
+            });
+            selectedPackageVersion.version = declaredVersion;
+            selectedPackageVersion.packageVersionHash = packageVersionHash;
+        }
+        catch (error) {
+            console.warn(`[PackageLoader] Failed to correct version for ${pkg.name}:`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    async _loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, force) {
+        if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(bundleCode)) {
+            try {
+                const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundleCode);
+                return await this._installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force);
             }
-        })
-            .catch((err) => {
-            console.warn(`[PackageLoader] Failed to correct version for ${pkg.name}:`, err.message);
-        });
+            catch (err) {
+                throw wrapIsolatedArtifactError(err);
+            }
+        }
+        const replacingIsolated = this.isolatedRuntime?.isInstalled(pkg.packageId) ?? false;
+        const instance = await this._evaluateBundle(pkg, bundleCode, selectedPackageVersion, force);
+        if (!instance) {
+            return undefined;
+        }
+        if (replacingIsolated && this.isolatedRuntime) {
+            await this.isolatedRuntime.uninstall(pkg.packageId, {
+                preserveRegistry: this.contractInstalledPackages.has(pkg.packageId),
+            });
+            this.isolatedPackageIds.delete(pkg.packageId);
+        }
+        return instance;
+    }
+    async _installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force) {
+        if (artifact.manifest.packageId !== pkg.packageId) {
+            throw wrapIsolatedArtifactError(new Error(`Isolated packageId mismatch: artifact has "${artifact.manifest.packageId}" but DB record has "${pkg.packageId}"`));
+        }
+        if (!selectedPackageVersion) {
+            throw wrapIsolatedArtifactError(new Error(`No selected PackageVersion is available for isolated package ${pkg.packageId}`));
+        }
+        if (artifact.manifest.version !== selectedPackageVersion.version) {
+            if (usingLocalBundle && selectedPackageVersion.versionTag === "dev") {
+                await this.correctPackageVersion(pkg, selectedPackageVersion, artifact.manifest.version);
+                if (artifact.manifest.version !== selectedPackageVersion.version) {
+                    throw wrapIsolatedArtifactError(new Error(`Could not correct selected dev PackageVersion to isolated artifact version "${artifact.manifest.version}"`));
+                }
+            }
+            else {
+                throw wrapIsolatedArtifactError(new Error(`Isolated package version mismatch: artifact has "${artifact.manifest.version}" but selected PackageVersion has "${selectedPackageVersion.version}"`));
+            }
+        }
+        if (!this.isolatedRuntime) {
+            await this.unloadPackage(pkg.packageId);
+            console.warn(`[PackageLoader] Skipping isolated package "${pkg.name}" because this host does not provide an isolated runtime.`);
+            return undefined;
+        }
+        const installOptions = isolatedContractLifecycle(selectedPackageVersion);
+        if (this.isolatedRuntime.isInstalled(pkg.packageId)) {
+            if (!force) {
+                return this.packageInstances[pkg.packageId];
+            }
+            await this.isolatedRuntime.replace(artifact, installOptions);
+        }
+        else {
+            await this.isolatedRuntime.install(artifact, installOptions);
+        }
+        this.isolatedPackageIds.add(pkg.packageId);
+        this.contractInstalledPackages.add(pkg.packageId);
+        const instance = {
+            packageId: artifact.manifest.packageId,
+            appNavs: artifact.manifest.appNavs,
+        };
+        this.packageInstances[pkg.packageId] = instance;
+        return instance;
     }
-    async _evaluateBundle(pkg, bundleCode) {
+    async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, force) {
         // Node.js built-in modules that do not exist in React Native (and would cause
         // a fatal native error if passed through to RN's require). We block them here
         // and throw a descriptive JS Error instead, which the surrounding try/catch
@@ -187,14 +537,16 @@ class PackageLoader {
         const moduleExports = {};
         const module = { exports: moduleExports };
         const customRequire = (moduleId) => {
-            const _require = (this.require ?? defaultRequire ?? typeof require === "function") ? require : undefined;
+            const _require = this.require ??
+                defaultRequire ??
+                (typeof require === "function" ? require : undefined);
             if (!_require) {
                 throw new Error("You must set the `require` function in package loader before loading a package");
             }
             switch (moduleId) {
                 case "peers-sdk":
                 case "PeersSDK":
-                    return PackageLoader.PeersSDK || _require("../index");
+                    return PackageLoader.PeersSDK || _require("@peers-app/peers-sdk");
                 case "zod":
                     return PackageLoader.Zod || _require("zod");
                 default:
@@ -221,12 +573,12 @@ class PackageLoader {
                 if (packageDefinition.packageId !== pkg.packageId) {
                     console.warn(`[PackageLoader] packageId mismatch: definition has "${packageDefinition.packageId}" but DB record has "${pkg.packageId}"`);
                 }
+                await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(this.dataContext, this.contractRegistry, packageDefinition);
                 await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
                     registry: this.contractRegistry,
                 });
-                await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(this.dataContext, this.contractRegistry, packageDefinition);
                 this.contractInstalledPackages.add(packageDefinition.packageId);
-                this.correctPackageVersion(pkg, packageDefinition);
+                await this.correctPackageVersion(pkg, selectedPackageVersion, packageDefinition.version);
                 // Build a proper IPeersPackage from the contract definition so callers
                 // (e.g. package-installer) can read appNavs, assistants, etc.
                 const contractPackageInstance = {
@@ -241,7 +593,6 @@ class PackageLoader {
             }
             // Legacy path: extract IPeersPackage for backward compat
             const packageInstance = bundleExports?.exports || bundleExports?.package || bundleExports?.default || bundleExports;
-            this.packageInstances[pkg.packageId] = packageInstance;
             if (packageInstance && typeof packageInstance === "object") {
                 packageInstance.toolInstances?.forEach((toolInstance) => {
                     (0, tools_2.registerTool)(toolInstance);
@@ -252,6 +603,11 @@ class PackageLoader {
                         overwrite: true,
                     });
                 });
+                if (force && this.contractInstalledPackages.has(pkg.packageId)) {
+                    this.contractRegistry.unregister(pkg.packageId);
+                    this.contractInstalledPackages.delete(pkg.packageId);
+                }
+                this.packageInstances[pkg.packageId] = packageInstance;
                 return packageInstance;
             }
             return;
@@ -263,7 +619,22 @@ class PackageLoader {
     }
 }
 exports.PackageLoader = PackageLoader;
+const ISOLATED_ARTIFACT_ERROR = "IsolatedPackageArtifactError";
+function wrapIsolatedArtifactError(err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    error.name = ISOLATED_ARTIFACT_ERROR;
+    return error;
+}
+function isIsolatedArtifactError(err) {
+    return err instanceof Error && err.name === ISOLATED_ARTIFACT_ERROR;
+}
 let defaultRequire;
+/**
+ * Set the process-wide `require` used when a {@link PackageLoader} instance
+ * does not supply its own.
+ *
+ * @param require - Host `require` function.
+ */
 function setDefaultRequire(require) {
     defaultRequire = require;
 }