@peers-app/peers-sdk 0.26.4 → 0.26.5

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

@@ -13,14 +13,22 @@ const files_1 = require("../data/files");
 const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
+const keys_1 = require("../keys");
+const observable_1 = require("../observable");
 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 package_runtime_state_1 = require("./package-runtime-state");
 const resolve_consumed_contracts_1 = require("./resolve-consumed-contracts");
 // Ensure built-in system contracts are cataloged before any PackageLoader installs them.
 require("../contracts/system");
+/**
+ * Build the trusted install options for an isolated artifact from its selected version.
+ *
+ * @param packageVersion - Selected PackageVersion; `dev` and `beta` publish mutable contracts.
+ */
 function isolatedContractLifecycle(packageVersion) {
     return {
         contractLifecycle: packageVersion?.versionTag === "dev" || packageVersion?.versionTag === "beta"
@@ -53,6 +61,17 @@ class PackageLoader {
     contractInstalledPackages = new Set();
     /** Packages installed through the isolated runtime (no host eval). */
     isolatedPackageIds = new Set();
+    /** Per-package counter bumped on every runtime-state change; lets slow unloads yield. */
+    runtimeStateSequences = new Map();
+    /** Hash of the bundle each loaded package was built from, for `onlyIfChanged` loads. */
+    loadedBundleHashes = new Map();
+    unsubscribePackageHealth;
+    /**
+     * Observed runtime state of each package this loader has attempted, keyed by package id.
+     * In memory only; read merged with isolated worker health through
+     * {@link getPackageRuntimeState} and {@link getPackageRuntimeStates}.
+     */
+    runtimeStates = (0, observable_1.observable)({});
     /**
      * In-memory contract providers for this data context. Seeded with system
      * contracts after catalog readiness; package providers are added via
@@ -100,6 +119,20 @@ class PackageLoader {
                     }),
                 },
             });
+            this.unsubscribePackageHealth = this.isolatedRuntime.subscribePackageHealth?.((packageId) => {
+                const previous = this.runtimeStates()[packageId];
+                if (!previous || this.disposed)
+                    return;
+                const { worker: _worker, ...state } = previous;
+                const worker = state.running?.kind === "isolated"
+                    ? this.isolatedRuntime?.getPackageHealth?.(packageId)
+                    : undefined;
+                // Health does not supersede a load/unload; keep its sequence unchanged.
+                this.runtimeStates({
+                    ...this.runtimeStates(),
+                    [packageId]: { ...state, ...(worker ? { worker } : {}), updatedAt: Date.now() },
+                });
+            });
         }
     }
     /**
@@ -123,6 +156,68 @@ class PackageLoader {
     supportsIsolatedPackages() {
         return this.isolatedRuntime !== undefined;
     }
+    /**
+     * Return the observed runtime state of one package, merged with isolated worker health.
+     *
+     * @param packageId - Package to query.
+     * @returns The state, or `undefined` when this loader has never attempted the package.
+     */
+    getPackageRuntimeState(packageId) {
+        const state = this.runtimeStates()[packageId];
+        if (!state)
+            return undefined;
+        const worker = state.running?.kind === "isolated"
+            ? this.isolatedRuntime?.getPackageHealth?.(packageId)
+            : undefined;
+        return worker ? { ...state, worker } : state;
+    }
+    /** Return every recorded package runtime state, merged with isolated worker health. */
+    getPackageRuntimeStates() {
+        return Object.fromEntries(Object.keys(this.runtimeStates()).map((packageId) => [
+            packageId,
+            this.getPackageRuntimeState(packageId),
+        ]));
+    }
+    setRuntimeState(state) {
+        this.runtimeStateSequences.set(state.packageId, (this.runtimeStateSequences.get(state.packageId) ?? 0) + 1);
+        const worker = state.running?.kind === "isolated"
+            ? this.isolatedRuntime?.getPackageHealth?.(state.packageId)
+            : undefined;
+        this.runtimeStates({
+            ...this.runtimeStates(),
+            [state.packageId]: { ...state, ...(worker ? { worker } : {}) },
+        });
+    }
+    recordRunning(packageId, running) {
+        this.setRuntimeState({ packageId, status: "running", running, updatedAt: Date.now() });
+    }
+    recordStatus(packageId, status, reason) {
+        const previous = this.runtimeStates()[packageId];
+        this.setRuntimeState({ ...previous, packageId, status, reason, updatedAt: Date.now() });
+    }
+    /**
+     * Record a failed load attempt unless a newer load or unload superseded it. The previous
+     * `running` version is kept: a failed replacement leaves the old version serving.
+     */
+    recordLoadFailure(packageId, packageVersion, error, assertCurrent) {
+        if (!isCurrent(assertCurrent))
+            return;
+        const now = Date.now();
+        const previous = this.runtimeStates()[packageId];
+        this.setRuntimeState({
+            packageId,
+            status: "failed",
+            running: previous?.running,
+            lastError: {
+                phase: "load",
+                message: (0, package_runtime_state_1.runtimeErrorMessage)(error),
+                packageVersionId: packageVersion?.packageVersionId,
+                version: packageVersion?.version,
+                at: now,
+            },
+            updatedAt: now,
+        });
+    }
     async dispatchToolFromProvider(packageId, target, args, context) {
         if (!context.authority?.userId ||
             !context.dataContext ||
@@ -354,9 +449,12 @@ class PackageLoader {
      * before any consumer call payload is processed.
      *
      * @param dependency - Validated package consume declaration.
+     * @param callerPackageId - Owning package, supplied by the loader rather than call input.
      * @returns A live consumer proxy, or `undefined` when no provider matches.
      */
-    async resolveConsumedContract(dependency) {
+    async resolveConsumedContract(dependency, callerPackageId) {
+        if (!callerPackageId)
+            throw new Error("A package caller identity is required");
         await this.catalogReady;
         const selected = this.contractRegistry.selectProvider(dependency);
         if (!selected) {
@@ -367,7 +465,7 @@ class PackageLoader {
         const router = (0, contract_provider_router_1.createContractProviderRouter)(providerTransport, {
             authorizeCall: () => ({
                 dataContextId: this.dataContext.dataContextId,
-                context: { dataContext: this.dataContext },
+                context: { dataContext: this.dataContext, callerPackageId },
             }),
             resolveProviderPackageId: () => providerPackageId,
             resolveEndpoint: (request) => this.resolveContractEndpoint(request, { providerPackageId }),
@@ -395,9 +493,12 @@ class PackageLoader {
      * installed package) so the proxy knows the tool names.
      *
      * @param declaration - Validated package remote declaration.
+     * @param callerPackageId - Owning package, retained for local and remote authorization.
      * @returns A per-device consumer factory, or `undefined` when the contract is unknown.
      */
-    async resolveRemoteContract(declaration) {
+    async resolveRemoteContract(declaration, callerPackageId) {
+        if (!callerPackageId)
+            throw new Error("A package caller identity is required");
         await this.catalogReady;
         const definition = this.contractRegistry.getDefinition(declaration.contractId, declaration.version);
         if (!definition) {
@@ -407,7 +508,7 @@ class PackageLoader {
         const router = (0, contract_provider_router_1.createContractProviderRouter)(hostTransport, {
             authorizeCall: () => ({
                 dataContextId: this.dataContext.dataContextId,
-                context: { dataContext: this.dataContext },
+                context: { dataContext: this.dataContext, callerPackageId },
             }),
             resolveProviderPackageId: (request) => this.contractRegistry.getProviderPackageId(request.contractId, request.version),
             resolveEndpoint: (request) => this.resolveContractEndpoint(request),
@@ -441,12 +542,17 @@ class PackageLoader {
     /**
      * Stop an isolated worker (if any) and drop the in-memory package instance.
      *
+     * Records the given runtime status unless a newer load recorded state while the unload
+     * was in flight.
+     *
      * @param packageId - Package to unload.
+     * @param opts - Runtime status and reason to record.
      */
-    async unloadPackage(packageId) {
+    async unloadPackage(packageId, opts = {}) {
         // Invalidate loads before the first await, including those still resolving
         // bundles or consumed contracts outside the catalog publication queue.
         this.loadGenerations.set(packageId, (this.loadGenerations.get(packageId) ?? 0) + 1);
+        const stateSequence = this.runtimeStateSequences.get(packageId);
         // Uninstall also queues behind an install that has not published yet.
         await this.isolatedRuntime?.uninstall(packageId);
         await this.toolCatalog.removeProvider(packageId, () => {
@@ -456,13 +562,23 @@ class PackageLoader {
             this.isolatedPackageIds.delete(packageId);
             this.contractInstalledPackages.delete(packageId);
             delete this.packageInstances[packageId];
+            this.loadedBundleHashes.delete(packageId);
         });
+        if (!this.disposed && this.runtimeStateSequences.get(packageId) === stateSequence) {
+            this.setRuntimeState({
+                packageId,
+                status: opts.status ?? "unloaded",
+                reason: opts.reason,
+                updatedAt: Date.now(),
+            });
+        }
     }
     /**
      * Dispose the isolated runtime for this data context.
      */
     async dispose() {
         this.disposed = true;
+        this.unsubscribePackageHealth?.();
         for (const router of this.consumedContractRouters)
             router.dispose();
         this.consumedContractRouters.clear();
@@ -482,6 +598,9 @@ class PackageLoader {
         this.isolatedPackageIds.clear();
         this.contractInstalledPackages.clear();
         this.packageInstances = {};
+        this.loadedBundleHashes.clear();
+        this.runtimeStateSequences.clear();
+        this.runtimeStates({});
     }
     retireHostEndpoints(packageId) {
         this.hostActivationGenerations.set(packageId, (this.hostActivationGenerations.get(packageId) ?? 0) + 1);
@@ -499,7 +618,7 @@ class PackageLoader {
         const packages = await (0, packages_1.Packages)(this.dataContext).list();
         await Promise.all(packages.map(async (pkg) => {
             if (pkg.disabled) {
-                await this.unloadPackage(pkg.packageId);
+                await this.unloadPackage(pkg.packageId, DISABLED_UNLOAD);
                 return;
             }
             try {
@@ -519,63 +638,50 @@ class PackageLoader {
      * isolated `dist/package.bundle.js`, that disk artifact wins over a stale
      * stored Files bundle so local-dev packages pick up new contract versions.
      *
+     * With `onlyIfChanged`, a forced load is skipped when the package is running and the
+     * selected version and bundle are exactly the ones already loaded. A changed release
+     * channel updates the reported label and isolated contract maturity without restarting
+     * the worker. Sync reconciliation uses this so an echoed or unrelated row
+     * change does not restart the worker and fail calls in flight. Explicit reloads omit it.
+     *
      * @param pkg - Package row.
-     * @param opts - Optional force reload, local path fallback, and PV id.
+     * @param opts - Optional force reload, `onlyIfChanged`, local path fallback, and PV id.
      */
     async loadPackage(pkg, opts) {
         if (pkg.disabled) {
-            await this.unloadPackage(pkg.packageId);
+            await this.unloadPackage(pkg.packageId, DISABLED_UNLOAD);
             return undefined;
         }
-        const assertCurrent = this.guardLoad(pkg.packageId);
         if (this.packageInstances[pkg.packageId] && !opts?.force) {
             return this.packageInstances[pkg.packageId];
         }
+        const assertCurrent = this.guardLoad(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;
-                    }
-                }
-                catch {
-                    /* no version record */
-                }
-            }
-            if (bundleFileId) {
-                const filesTable = (0, files_1.Files)(this.dataContext);
-                const bundleBuffer = await filesTable.getFileContents(bundleFileId);
-                if (bundleBuffer) {
-                    bundleCode = Buffer.from(bundleBuffer).toString("utf8");
-                }
-                else {
-                    console.warn(`Package bundle file not found for ${pkg.name} (fileId: ${bundleFileId})`);
-                }
-            }
-            else {
-                console.warn(`Package ${pkg.name} does not have a bundle file defined.`);
+            if (opts?.onlyIfChanged &&
+                this.packageInstances[pkg.packageId] &&
+                (await this.keepRunningBuild(pkg, opts, assertCurrent))) {
+                assertCurrent();
+                return this.packageInstances[pkg.packageId];
             }
-            if (localPath && selectedPackageVersion?.versionTag === "dev") {
-                const localBundleCode = this._readLocalBundle(localPath);
-                if (localBundleCode) {
-                    bundleCode = localBundleCode;
-                    usingLocalBundle = true;
+            assertCurrent();
+            const selected = await this.readSelectedBundle(pkg, opts, true);
+            selectedPackageVersion = selected.packageVersion;
+            const { bundleCode, bundleFileId, usingLocalBundle } = selected;
+            if (!bundleCode) {
+                if (isCurrent(assertCurrent)) {
+                    this.recordStatus(pkg.packageId, "unavailable", bundleFileId
+                        ? "The selected version's bundle file is not on this device yet"
+                        : "No package version with a bundle is selected");
                 }
-            }
-            if (!bundleCode)
                 return;
-            return await this._loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, opts?.force === true, assertCurrent);
+            }
+            return this.rememberBundle(pkg.packageId, bundleCode, await this._loadBundle(pkg, bundleCode, selectedPackageVersion, usingLocalBundle, opts?.force === true, assertCurrent), assertCurrent);
         }
         catch (err) {
             if (isIsolatedArtifactError(err)) {
+                this.recordLoadFailure(pkg.packageId, selectedPackageVersion, err, assertCurrent);
                 throw err;
             }
             if (localPath && selectedPackageVersion?.versionTag === "dev") {
@@ -583,20 +689,116 @@ class PackageLoader {
                 try {
                     const localBundleCode = this._readLocalBundle(localPath);
                     if (localBundleCode) {
-                        return await this._loadBundle(pkg, localBundleCode, selectedPackageVersion, true, opts?.force === true, assertCurrent);
+                        return this.rememberBundle(pkg.packageId, localBundleCode, await this._loadBundle(pkg, localBundleCode, selectedPackageVersion, true, opts?.force === true, assertCurrent), assertCurrent);
                     }
                 }
                 catch (localErr) {
                     if (isIsolatedArtifactError(localErr)) {
+                        this.recordLoadFailure(pkg.packageId, selectedPackageVersion, localErr, assertCurrent);
                         throw localErr;
                     }
                     console.debug(`Could not load local bundle for ${pkg.name}`, localErr);
                 }
             }
+            this.recordLoadFailure(pkg.packageId, selectedPackageVersion, err, assertCurrent);
             console.debug(`Could not load package bundle for ${pkg.name}`, err);
             return;
         }
     }
+    /**
+     * Read the bundle a load would use: the selected version's stored file, replaced by the
+     * rebuilt local `dist/package.bundle.js` for a dev version with a local path.
+     */
+    async readSelectedBundle(pkg, opts, warn) {
+        let packageVersion;
+        let bundleFileId;
+        let bundleCode = "";
+        let usingLocalBundle = false;
+        const pvId = opts?.packageVersionId ?? pkg.activePackageVersionId;
+        if (pvId) {
+            try {
+                const pv = await (0, package_versions_1.PackageVersions)(this.dataContext).get(pvId);
+                if (pv) {
+                    packageVersion = pv;
+                    bundleFileId = pv.packageBundleFileId;
+                }
+            }
+            catch {
+                /* no version record */
+            }
+        }
+        if (bundleFileId) {
+            const bundleBuffer = await (0, files_1.Files)(this.dataContext).getFileContents(bundleFileId);
+            if (bundleBuffer) {
+                bundleCode = Buffer.from(bundleBuffer).toString("utf8");
+            }
+            else if (warn) {
+                console.warn(`Package bundle file not found for ${pkg.name} (fileId: ${bundleFileId})`);
+            }
+        }
+        else if (warn) {
+            console.warn(`Package ${pkg.name} does not have a bundle file defined.`);
+        }
+        if (opts?.localPath && packageVersion?.versionTag === "dev") {
+            const localBundleCode = this._readLocalBundle(opts.localPath);
+            if (localBundleCode) {
+                bundleCode = localBundleCode;
+                usingLocalBundle = true;
+            }
+        }
+        return { packageVersion, bundleFileId, bundleCode, usingLocalBundle };
+    }
+    /**
+     * True when the package is running the exact version and bundle a load would select, so an
+     * `onlyIfChanged` load can keep it. Promotion refreshes the release-channel label and
+     * isolated contract maturity without reloading, since the tag is not part of the bundle.
+     */
+    async keepRunningBuild(pkg, opts, assertCurrent) {
+        const loadedHash = this.loadedBundleHashes.get(pkg.packageId);
+        const state = this.runtimeStates()[pkg.packageId];
+        if (!loadedHash || state?.status !== "running" || !state.running)
+            return false;
+        try {
+            const { packageVersion, bundleCode } = await this.readSelectedBundle(pkg, opts, false);
+            assertCurrent();
+            if (!bundleCode ||
+                !packageVersion ||
+                packageVersion.packageVersionId !== state.running.packageVersionId ||
+                packageVersion.version !== state.running.version ||
+                (0, keys_1.hashValue)(bundleCode) !== loadedHash) {
+                return false;
+            }
+            if (packageVersion.versionTag !== state.running.versionTag) {
+                if (state.running.kind === "isolated") {
+                    // Promotion must freeze stable contract shapes even though the worker's code
+                    // stays identical. Older runtime implementations fall back to a normal load.
+                    if (!this.isolatedRuntime?.updateContractLifecycle)
+                        return false;
+                    await this.isolatedRuntime.updateContractLifecycle(pkg.packageId, {
+                        ...isolatedContractLifecycle(packageVersion),
+                        assertCurrent,
+                    });
+                    assertCurrent();
+                }
+                this.setRuntimeState({
+                    ...this.runtimeStates()[pkg.packageId],
+                    running: { ...state.running, ...runningVersionFields(packageVersion) },
+                    updatedAt: Date.now(),
+                });
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Record the bundle a current, successful load ran, and pass its result through. */
+    rememberBundle(packageId, bundleCode, instance, assertCurrent) {
+        if (instance && isCurrent(assertCurrent)) {
+            this.loadedBundleHashes.set(packageId, (0, keys_1.hashValue)(bundleCode));
+        }
+        return instance;
+    }
     _readLocalBundle(localPath) {
         try {
             const _require = this.require ?? defaultRequire ?? (typeof require === "function" ? require : null);
@@ -611,7 +813,8 @@ class PackageLoader {
         }
     }
     guardLoad(packageId) {
-        const generation = this.loadGenerations.get(packageId) ?? 0;
+        const generation = (this.loadGenerations.get(packageId) ?? 0) + 1;
+        this.loadGenerations.set(packageId, generation);
         return () => {
             if (this.disposed || generation !== (this.loadGenerations.get(packageId) ?? 0))
                 throw new Error(`Package load invalidated: ${packageId}`);
@@ -694,20 +897,24 @@ class PackageLoader {
             }
         }
         if (!this.isolatedRuntime) {
-            await this.unloadPackage(pkg.packageId);
+            await this.unloadPackage(pkg.packageId, {
+                status: "unsupported",
+                reason: "This host has no isolated package runtime",
+            });
             console.warn(`[PackageLoader] Skipping isolated package "${pkg.name}" because this host does not provide an isolated runtime.`);
             return undefined;
         }
         assertCurrent();
         const installOptions = { ...isolatedContractLifecycle(selectedPackageVersion), assertCurrent };
+        let installed;
         if (this.isolatedRuntime.isInstalled(pkg.packageId)) {
             if (!force) {
                 return this.packageInstances[pkg.packageId];
             }
-            await this.isolatedRuntime.replace(artifact, installOptions);
+            installed = await this.isolatedRuntime.replace(artifact, installOptions);
         }
         else {
-            await this.isolatedRuntime.install(artifact, installOptions);
+            installed = await this.isolatedRuntime.install(artifact, installOptions);
         }
         assertCurrent();
         this.retireHostEndpoints(pkg.packageId);
@@ -719,6 +926,13 @@ class PackageLoader {
             appNavs: artifact.manifest.appNavs,
         };
         this.packageInstances[pkg.packageId] = instance;
+        this.recordRunning(pkg.packageId, {
+            ...runningVersionFields(selectedPackageVersion),
+            kind: "isolated",
+            executionMode: artifact.manifest.executionMode ?? "sandbox",
+            provides: installed?.provided,
+            consumes: installed?.consumes,
+        });
         return instance;
     }
     async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, force, assertCurrent = this.guardLoad(pkg.packageId)) {
@@ -813,6 +1027,10 @@ class PackageLoader {
                         this.hostConsumes.set(packageDefinition.packageId, packageDefinition.consumes);
                         this.contractInstalledPackages.add(packageDefinition.packageId);
                         this.packageInstances[pkg.packageId] = contractPackageInstance;
+                        this.recordRunning(pkg.packageId, {
+                            ...runningVersionFields(selectedPackageVersion),
+                            kind: "contract",
+                        });
                     },
                 });
                 // A package may declare remote/consume handles for its own contracts.
@@ -824,7 +1042,10 @@ class PackageLoader {
             }
             // Legacy path: extract IPeersPackage for backward compat
             const packageInstance = bundleExports?.exports || bundleExports?.package || bundleExports?.default || bundleExports;
-            if (packageInstance && typeof packageInstance === "object") {
+            if (packageInstance &&
+                typeof packageInstance === "object" &&
+                typeof packageInstance.packageId === "string" &&
+                packageInstance.packageId.length > 0) {
                 const tools = packageInstance.toolInstances;
                 if (Array.isArray(tools) && tools.length)
                     throw new Error(`Package '${pkg.name}' (${pkg.packageId}) ships legacy executable tools, which this runtime no longer runs; upgrade it to definePackage() contract tools (docs/Packages/contracts.md#migrating-from-toolinstances)`);
@@ -841,12 +1062,17 @@ class PackageLoader {
                         this.contractInstalledPackages.delete(pkg.packageId);
                     }
                     this.packageInstances[pkg.packageId] = packageInstance;
+                    this.recordRunning(pkg.packageId, {
+                        ...runningVersionFields(selectedPackageVersion),
+                        kind: "legacy",
+                    });
                 });
                 return packageInstance;
             }
-            return;
+            throw new Error("Package bundle exports nothing usable");
         }
         catch (err) {
+            this.recordLoadFailure(pkg.packageId, selectedPackageVersion, err, assertCurrent);
             console.warn(`[PackageLoader] Failed to evaluate bundle for "${pkg.name}":`, err.message);
             return undefined;
         }
@@ -854,6 +1080,28 @@ class PackageLoader {
 }
 exports.PackageLoader = PackageLoader;
 const ISOLATED_ARTIFACT_ERROR = "IsolatedPackageArtifactError";
+const DISABLED_UNLOAD = {
+    status: "disabled",
+    reason: "The package is disabled in this group",
+};
+/** True when a load guard still holds (no newer unload or disposal). */
+function isCurrent(assertCurrent) {
+    try {
+        assertCurrent();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy the identifying fields of the loaded PackageVersion into a running-version record. */
+function runningVersionFields(packageVersion) {
+    return {
+        packageVersionId: packageVersion?.packageVersionId,
+        version: packageVersion?.version,
+        versionTag: packageVersion?.versionTag,
+    };
+}
 function wrapIsolatedArtifactError(err) {
     const error = err instanceof Error ? err : new Error(String(err));
     error.name = ISOLATED_ARTIFACT_ERROR;