@peers-app/peers-sdk 0.26.4 → 0.26.5

package/dist/package-installer/package-installer.js

@@ -12,8 +12,8 @@ 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 persistent_vars_1 = require("../data/persistent-vars");
-const rpc_types_1 = require("../rpc-types");
 const utils_1 = require("../utils");
+const package_author_signer_1 = require("./package-author-signer");
 /**
  * Install or update a dev PackageVersion from locally-built bundle files.
  *
@@ -21,6 +21,11 @@ const utils_1 = require("../utils");
  * bundles from `dist/`, hashes them for deduplication, saves File records
  * only when content has changed, upserts the PackageVersion, and optionally
  * triggers the package loader and device version resolution.
+ *
+ * When the bundle hash matches the existing PackageVersion, no files or PV are
+ * rewritten. The Packages row still gets a missing `activePackageVersionId`
+ * (and description), and when the id was missing the version is activated on
+ * this device unless `skipResolve`.
  */
 async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     const versionTag = opts?.versionTag ?? "dev";
@@ -53,23 +58,24 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     const uiHash = uiBundle ? (0, file_types_1.computeFileHash)(uiBundle) : undefined;
     // 5. Compute PV hash
     const pvHash = (0, package_versions_1.computePackageVersionHash)(version, "", packageHash, routesHash, uiHash);
-    // 6. Early exit if unchanged (still repair missing appNavs — see syncDevBundles skipLoad)
+    // 6. Early exit if unchanged. Still repair missing appNavs (see syncDevBundles
+    // skipLoad), and still fill an empty activePackageVersionId (e.g. reimport after
+    // the Packages row was deleted). If it was empty, activate on the device unless
+    // skipResolve.
     const pvTable = (0, package_versions_1.PackageVersions)(dataContext);
     const existingPv = await pvTable.findOne({ packageId, versionTag });
     if (existingPv && existingPv.packageVersionHash === pvHash) {
-        if (existingPv.appNavs?.length) {
-            return {
-                packageVersion: existingPv,
-                loaded: undefined,
-                unchanged: true,
-            };
+        let loaded;
+        let unchanged = true;
+        if (!existingPv.appNavs?.length) {
+            loaded = await loadAndPersistAppNavs(dataContext, packageId, existingPv, localPath);
+            unchanged = !loaded?.appNavs?.length;
         }
-        const loaded = await loadAndPersistAppNavs(dataContext, packageId, existingPv, localPath);
-        return {
-            packageVersion: existingPv,
-            loaded,
-            unchanged: !loaded?.appNavs?.length,
-        };
+        await activateInstalledPackageVersion(dataContext, packageId, existingPv, info, localPath, {
+            skipResolve: opts?.skipResolve,
+            resolveOnlyWhenActivated: true,
+        });
+        return { packageVersion: existingPv, loaded, unchanged };
     }
     // 7. Save bundle files (deduped by hash)
     const packageFile = await saveBundleFile(dataContext, packageBundle, `${packageId}-package.bundle.js`, packageId);
@@ -110,31 +116,48 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     if (!opts?.skipLoad || !savedPv.appNavs?.length) {
         loaded = await loadAndPersistAppNavs(dataContext, packageId, savedPv, localPath);
     }
-    // 10. Update package record if needed (description, first-install activation)
+    // 10–11. Update package record and activate on device (unless skipResolve)
+    await activateInstalledPackageVersion(dataContext, packageId, savedPv, info, localPath, {
+        skipResolve: opts?.skipResolve,
+    });
+    return { packageVersion: savedPv, loaded, unchanged: false };
+}
+/**
+ * Sync the Packages row with an installed PackageVersion, then activate it on
+ * this device.
+ *
+ * Updates the description when it differs, and sets `activePackageVersionId`
+ * when it is empty (first install, or reimport after the row was deleted).
+ * Unless `skipResolve`, writes device prefs and force-resolves the version.
+ * With `resolveOnlyWhenActivated`, the device step runs only when this call
+ * filled an empty `activePackageVersionId`.
+ */
+async function activateInstalledPackageVersion(dataContext, packageId, packageVersion, info, localPath, opts) {
+    // Update package record if needed (description, first-install activation)
     const pkg = await (0, packages_1.Packages)(dataContext).get(packageId);
-    if (pkg) {
-        let needsSave = false;
-        if (info.description && info.description !== pkg.description) {
-            pkg.description = info.description;
-            needsSave = true;
-        }
-        if (!pkg.activePackageVersionId) {
-            pkg.activePackageVersionId = savedPv.packageVersionId;
-            needsSave = true;
-        }
-        if (needsSave) {
-            await (0, packages_1.Packages)(dataContext).signAndSave(pkg);
-        }
+    if (!pkg)
+        return;
+    let needsSave = false;
+    if (info.description && info.description !== pkg.description) {
+        pkg.description = info.description;
+        needsSave = true;
     }
-    // 11. Activate on device (unless skipResolve)
-    if (!opts?.skipResolve && pkg) {
-        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { activePackageVersionId: savedPv.packageVersionId }, dataContext);
-        await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dataContext, {
-            force: true,
-            localPath,
-        });
+    const activated = !pkg.activePackageVersionId;
+    if (activated) {
+        pkg.activePackageVersionId = packageVersion.packageVersionId;
+        needsSave = true;
     }
-    return { packageVersion: savedPv, loaded, unchanged: false };
+    if (needsSave) {
+        await (0, packages_1.Packages)(dataContext).signAndSave(pkg);
+    }
+    // Activate on device
+    if (opts.skipResolve || (opts.resolveOnlyWhenActivated && !activated))
+        return;
+    await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { activePackageVersionId: packageVersion.packageVersionId }, dataContext);
+    await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dataContext, {
+        force: true,
+        localPath,
+    });
 }
 /**
  * Load a package bundle and persist `appNavs` onto the PackageVersion when the
@@ -159,7 +182,7 @@ async function loadAndPersistAppNavs(dataContext, packageId, pv, localPath) {
         return loaded;
     pv.appNavs = loaded.appNavs;
     if (pv.packageAuthorSignature) {
-        const authorSig = await rpc_types_1.rpcServerCalls.signPackageAuthorVersion({
+        const authorSig = await (0, package_author_signer_1.signPackageAuthorVersionOnHost)({
             packageId: pv.packageId,
             packageVersionId: pv.packageVersionId,
             version: pv.version,

package/dist/package-installer/package-installer.test.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const file_types_1 = require("../data/files/file.types");
 const utils_1 = require("../utils");
+const package_author_signer_1 = require("./package-author-signer");
 const package_installer_1 = require("./package-installer");
 // --- Mocks for SDK internals ---
 const mockFindOnePV = jest.fn();
@@ -258,6 +259,28 @@ describe("installPackageFromBundles", () => {
         });
         return { deps, files };
     }
+    /** A PV whose hash matches the `setupBasicInstall` bundles. */
+    function matchingPv(overrides = {}) {
+        const packageHash = (0, file_types_1.computeFileHash)(packageBundle);
+        const routesHash = (0, file_types_1.computeFileHash)(routesBundle);
+        const uiHash = (0, file_types_1.computeFileHash)(uiBundle);
+        const { computePackageVersionHash } = jest.requireActual("../data/package-versions");
+        return {
+            packageVersionId: (0, utils_1.newid)(),
+            packageId,
+            version: "1.2.3",
+            versionTag: "dev",
+            packageVersionHash: computePackageVersionHash("1.2.3", "", packageHash, routesHash, uiHash),
+            packageBundleFileId: (0, utils_1.newid)(),
+            packageBundleFileHash: packageHash,
+            routesBundleFileHash: routesHash,
+            uiBundleFileHash: uiHash,
+            signature: "",
+            createdBy: "user1",
+            createdAt: "2024-01-01T00:00:00.000Z",
+            ...overrides,
+        };
+    }
     it("installs a new package version from bundles", async () => {
         const { deps } = setupBasicInstall();
         const dc = mockDataContext();
@@ -455,6 +478,31 @@ describe("installPackageFromBundles", () => {
         expect(mockSignAndSavePV).toHaveBeenCalledTimes(2);
         expect(mockSignAndSavePV.mock.calls[1][0].appNavs).toEqual(appNavs);
     });
+    it.each([
+        ["re-signs with the host signer", "new-signature"],
+        ["clears the signature without a host signer", undefined],
+    ])("%s when appNavs change on a signed version", async (_name, expected) => {
+        const { deps } = setupBasicInstall();
+        const signer = jest.fn(async () => "new-signature");
+        (0, package_author_signer_1.setPackageAuthorVersionSigner)(expected ? signer : undefined);
+        mockFindOnePV.mockResolvedValue(matchingPv({ packageAuthorSignature: "old-signature" }));
+        const appNavs = [{ name: "App", iconClassName: "bi bi-app", navigationPath: "app" }];
+        const dc = mockDataContext({
+            packageLoader: { loadPackage: jest.fn().mockResolvedValue({ packageId, appNavs }) },
+        });
+        try {
+            await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, { skipResolve: true });
+            const saved = mockSignAndSavePV.mock.calls.at(-1)?.[0];
+            expect(saved.appNavs).toEqual(appNavs);
+            expect(saved.packageAuthorSignature).toBe(expected);
+            if (expected) {
+                expect(signer).toHaveBeenCalledWith(expect.objectContaining({ packageId, appNavs, versionTag: "dev" }));
+            }
+        }
+        finally {
+            (0, package_author_signer_1.setPackageAuthorVersionSigner)(undefined);
+        }
+    });
     it("repairs missing appNavs on unchanged early-return", async () => {
         const { deps } = setupBasicInstall();
         const packageHash = (0, file_types_1.computeFileHash)(packageBundle);
@@ -489,6 +537,87 @@ describe("installPackageFromBundles", () => {
         expect(result.packageVersion.appNavs).toEqual(appNavs);
         expect(mockSignAndSavePV).toHaveBeenCalledTimes(1);
     });
+    it("reimport after Packages row deletion fills activePackageVersionId and activates", async () => {
+        const { deps } = setupBasicInstall();
+        const dc = mockDataContext();
+        const localPath = `/packages/${packageId}`;
+        const freshPkg = () => ({
+            packageId,
+            name: "test-pkg",
+            description: "Test package",
+            signature: "",
+            createdBy: "user1",
+        });
+        mockGetPkg.mockResolvedValue(freshPkg());
+        const first = await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, {
+            localPath,
+            skipLoad: true,
+            skipResolve: true,
+        });
+        expect(first.unchanged).toBe(false);
+        const pvId = first.packageVersion.packageVersionId;
+        // Uninstall deleted the Packages row; the PV row remains.
+        mockFindOnePV.mockResolvedValue(first.packageVersion);
+        mockSignAndSavePkg.mockClear();
+        mockSignAndSavePV.mockClear();
+        mockSaveFile.mockClear();
+        mockUpdatePackagePrefs.mockClear();
+        mockResolveDevicePackageVersion.mockClear();
+        mockGetPkg.mockResolvedValue(freshPkg());
+        const result = await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, { localPath });
+        expect(result.unchanged).toBe(true);
+        expect(result.packageVersion.packageVersionId).toBe(pvId);
+        expect(mockSaveFile).not.toHaveBeenCalled();
+        expect(mockSignAndSavePV).not.toHaveBeenCalled();
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({ activePackageVersionId: pvId }));
+        expect(mockUpdatePackagePrefs).toHaveBeenCalledWith(packageId, { activePackageVersionId: pvId }, dc);
+        expect(mockResolveDevicePackageVersion).toHaveBeenCalledWith(expect.objectContaining({ packageId, activePackageVersionId: pvId }), dc, { force: true, localPath });
+    });
+    it("unchanged with skipResolve fills activePackageVersionId without resolving", async () => {
+        const { deps } = setupBasicInstall();
+        const dc = mockDataContext();
+        const localPath = `/packages/${packageId}`;
+        const existingPv = matchingPv();
+        mockFindOnePV.mockResolvedValue(existingPv);
+        mockGetPkg.mockResolvedValue({
+            packageId,
+            name: "test-pkg",
+            description: "Test package",
+            signature: "",
+            createdBy: "user1",
+        });
+        const result = await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, {
+            localPath,
+            skipLoad: true,
+            skipResolve: true,
+        });
+        expect(result.unchanged).toBe(true);
+        expect(mockSignAndSavePkg).toHaveBeenCalledWith(expect.objectContaining({ activePackageVersionId: existingPv.packageVersionId }));
+        expect(mockUpdatePackagePrefs).not.toHaveBeenCalled();
+        expect(mockResolveDevicePackageVersion).not.toHaveBeenCalled();
+    });
+    it("unchanged with an active version does not re-activate", async () => {
+        const { deps } = setupBasicInstall();
+        const dc = mockDataContext();
+        const localPath = `/packages/${packageId}`;
+        const existingPv = matchingPv({
+            appNavs: [{ name: "App", iconClassName: "bi bi-app", navigationPath: "app" }],
+        });
+        mockFindOnePV.mockResolvedValue(existingPv);
+        mockGetPkg.mockResolvedValue({
+            packageId,
+            name: "test-pkg",
+            description: "Test package",
+            activePackageVersionId: existingPv.packageVersionId,
+            signature: "",
+            createdBy: "user1",
+        });
+        const result = await (0, package_installer_1.installPackageFromBundles)(dc, deps, packageId, { localPath });
+        expect(result.unchanged).toBe(true);
+        expect(mockSignAndSavePkg).not.toHaveBeenCalled();
+        expect(mockUpdatePackagePrefs).not.toHaveBeenCalled();
+        expect(mockResolveDevicePackageVersion).not.toHaveBeenCalled();
+    });
     it("calls updatePackagePrefs and resolveDevicePackageVersion when skipResolve is false", async () => {
         const { deps } = setupBasicInstall();
         const dc = mockDataContext();

package/dist/package-installer/types.d.ts

@@ -56,7 +56,11 @@ export interface IInstallOpts {
 export interface IInstallResult {
     packageVersion: IPackageVersion;
     loaded: IPeersPackage | undefined;
-    /** True when the on-disk bundles match the existing PackageVersion hash — no writes occurred. */
+    /**
+     * True when the on-disk bundles match the existing PackageVersion hash and this
+     * call persisted no new appNavs. Bundle files and the PackageVersion row are not
+     * rewritten; the Packages row and device activation may still be updated.
+     */
     unchanged: boolean;
 }
 /** Metadata extracted from a local package directory's `package.json`. */
@@ -117,16 +121,6 @@ export interface ICreatePackageResult {
      */
     templateWarning?: string;
 }
-/** Host/RPC result for adding, creating, or updating a package. */
-export interface IAddOrUpdatePackageResult {
-    /** Package that was created, imported, cloned, or updated. */
-    packageId: string;
-    /**
-     * Non-fatal notice after a successful local create (for example a stale
-     * template cache). Undefined on update, clone, and import of an existing directory.
-     */
-    warning?: string;
-}
 /** Options for {@link clonePackage}. */
 export interface IClonePackageOpts {
     /** Remote git URL to clone. */

package/dist/package-loader/index.d.ts

@@ -5,3 +5,4 @@ export * from "./isolated-runtime";
 export * from "./isolated-table-gateway";
 export * from "./package-loader";
 export * from "./package-network-policy";
+export * from "./package-runtime-state";

package/dist/package-loader/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./isolated-runtime"), exports);
 __exportStar(require("./isolated-table-gateway"), exports);
 __exportStar(require("./package-loader"), exports);
 __exportStar(require("./package-network-policy"), exports);
+__exportStar(require("./package-runtime-state"), exports);

package/dist/package-loader/isolated-runtime.d.ts

@@ -5,6 +5,7 @@ import type { ContractRegistry } from "../contracts/registry";
 import type { PersistentVarScope } from "../data/persistent-vars";
 import type { IField } from "../types/field-type";
 import type { IIsolatedContractToolRef, IIsolatedInstallResult, IIsolatedPackageArtifact } from "./isolated-artifact";
+import type { IPackageWorkerHealth } from "./package-runtime-state";
 /** Standard table methods exposed through isolated contract-table references. */
 export declare const ISOLATED_CONTRACT_TABLE_OPERATIONS: readonly ["get", "list", "count", "findOne", "save", "insert", "update", "delete"];
 /** Consumer-callable operation on an isolated contract table. */
@@ -68,6 +69,12 @@ export interface IIsolatedPackageRuntime {
      * previous worker and preserve the old registration if replacement fails.
      */
     replace(artifact: IIsolatedPackageArtifact, options?: IIsolatedPackageInstallOptions): Promise<IIsolatedInstallResult>;
+    /**
+     * Refresh trusted contract maturity for an unchanged installed artifact, without
+     * restarting its worker or invalidating calls in flight. Stable promotion freezes
+     * the contract shapes in the registry through the normal catalog publication checks.
+     */
+    updateContractLifecycle?(packageId: string, options: IIsolatedPackageInstallOptions): Promise<void>;
     /** Stop the package worker (if any) and optionally unregister its contracts. */
     uninstall(packageId: string, options?: IIsolatedPackageUninstallOptions): Promise<void>;
     /**
@@ -84,6 +91,17 @@ export interface IIsolatedPackageRuntime {
     provides(contractId: string, version: number): boolean;
     /** True when this runtime has installed `packageId`. */
     isInstalled(packageId: string): boolean;
+    /**
+     * Report whether the package's worker is running and its last worker start or crash
+     * failure since install or replacement. Workers start lazily, so a broken provider only
+     * shows here after its first call.
+     *
+     * @param packageId - Installed package to query.
+     * @returns Health, or `undefined` when the package is not installed here.
+     */
+    getPackageHealth?(packageId: string): IPackageWorkerHealth | undefined;
+    /** Subscribe to worker health changes without starting workers. Returns an unsubscribe function. */
+    subscribePackageHealth?(listener: (packageId: string) => void): () => void;
     /** Read effective policy without starting a worker. */
     getEffectiveToolLevel?(ref: {
         contractId: string;

package/dist/package-loader/package-loader.d.ts

@@ -5,9 +5,18 @@ import { ContractRegistry } from "../contracts/registry";
 import { ToolCatalog } from "../contracts/tool-catalog";
 import type { IConsumedContract, IRemoteContract, IRemoteContractConsumer } from "../contracts/types";
 import { type IPackage } from "../data/packages";
+import { type Observable } from "../observable";
 import type { IPeersPackage } from "../types/peers-package";
 import { type IIsolatedPackageRuntime } from "./isolated-runtime";
+import { type IPackageRuntimeState, type PackageRuntimeStates, type PackageRuntimeStatus } from "./package-runtime-state";
 import "../contracts/system";
+/** Options for {@link PackageLoader.unloadPackage}. */
+export interface IPackageUnloadOptions {
+    /** Runtime status to record once the package is unloaded. Defaults to `unloaded`. */
+    status?: Extract<PackageRuntimeStatus, "unloaded" | "disabled" | "unsupported">;
+    /** Explanation recorded with the status. */
+    reason?: string;
+}
 /** Host-only options for {@link PackageLoader.resolveContractEndpoint}. */
 export interface IPackageContractEndpointOptions {
     /** Provider package selected from trusted registry state. */
@@ -39,6 +48,17 @@ export declare class PackageLoader {
     private contractInstalledPackages;
     /** Packages installed through the isolated runtime (no host eval). */
     private isolatedPackageIds;
+    /** Per-package counter bumped on every runtime-state change; lets slow unloads yield. */
+    private runtimeStateSequences;
+    /** Hash of the bundle each loaded package was built from, for `onlyIfChanged` loads. */
+    private loadedBundleHashes;
+    private 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}.
+     */
+    readonly runtimeStates: Observable<PackageRuntimeStates>;
     /**
      * In-memory contract providers for this data context. Seeded with system
      * contracts after catalog readiness; package providers are added via
@@ -74,6 +94,23 @@ export declare class PackageLoader {
     isIsolatedInstalled(packageId: string): boolean;
     /** Return whether this host configured an isolated-package runtime. */
     supportsIsolatedPackages(): boolean;
+    /**
+     * 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: string): IPackageRuntimeState | undefined;
+    /** Return every recorded package runtime state, merged with isolated worker health. */
+    getPackageRuntimeStates(): PackageRuntimeStates;
+    private setRuntimeState;
+    private recordRunning;
+    private recordStatus;
+    /**
+     * 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.
+     */
+    private recordLoadFailure;
     private dispatchToolFromProvider;
     /**
      * Return the active provider selected by this data context's trusted registry.
@@ -105,9 +142,10 @@ export declare 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.
      */
-    resolveConsumedContract(dependency: IConsumedContract): Promise<IContractConsumer | undefined>;
+    resolveConsumedContract(dependency: IConsumedContract, callerPackageId: string): Promise<IContractConsumer | undefined>;
     /**
      * Bind a legacy package's `remote()` declaration to a per-device consumer factory.
      *
@@ -119,9 +157,10 @@ export declare 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.
      */
-    resolveRemoteContract(declaration: IRemoteContract): Promise<IRemoteContractConsumer<IContractConsumer> | undefined>;
+    resolveRemoteContract(declaration: IRemoteContract, callerPackageId: string): Promise<IRemoteContractConsumer<IContractConsumer> | undefined>;
     /**
      * Resolve a sandbox-backed provider endpoint when this context owns an
      * isolated provider for the requested contract.
@@ -132,9 +171,13 @@ export declare 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.
      */
-    unloadPackage(packageId: string): Promise<void>;
+    unloadPackage(packageId: string, opts?: IPackageUnloadOptions): Promise<void>;
     /**
      * Dispose the isolated runtime for this data context.
      */
@@ -158,14 +201,34 @@ export declare 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.
      */
     loadPackage(pkg: IPackage, opts?: {
         force?: boolean;
+        onlyIfChanged?: boolean;
         localPath?: string;
         packageVersionId?: string;
     }): Promise<IPeersPackage | undefined>;
+    /**
+     * 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.
+     */
+    private readSelectedBundle;
+    /**
+     * 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.
+     */
+    private keepRunningBuild;
+    /** Record the bundle a current, successful load ran, and pass its result through. */
+    private rememberBundle;
     private _readLocalBundle;
     private guardLoad;
     /**