@peers-app/peers-sdk 0.26.4 → 0.26.6

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

@@ -48,6 +48,8 @@ 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 remote_contract_transport_1 = require("../contracts/remote-contract-transport");
+const device_operations_contract_1 = require("../contracts/system/device-operations-contract");
 const tool_catalog_identity_1 = require("../contracts/tool-catalog-identity");
 const access_level_1 = require("../data/access-level");
 const groupPermissions = require("../data/group-permissions");
@@ -59,6 +61,33 @@ const isolated_runtime_1 = require("./isolated-runtime");
 const package_loader_1 = require("./package-loader");
 const consumedContracts = require("./resolve-consumed-contracts");
 describe("host load invalidation", () => {
+    it("retains legacy package identity and refuses system calls before forwarding", async () => {
+        const packageId = (0, utils_1.newid)();
+        const context = { dataContextId: (0, utils_1.newid)() };
+        const loader = new package_loader_1.PackageLoader(context);
+        Object.assign(context, { packageLoader: loader });
+        const emit = jest.fn(async () => "must not execute");
+        (0, remote_contract_transport_1.setRemoteContractTransportFactory)(() => ({ emit, on: () => () => { } }));
+        const definition = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = packageId;
+            pkg.version = "1.0.0";
+            pkg.remote(system_ids_1.deviceOperationsContractId, 1);
+        });
+        try {
+            await loader.catalogReady;
+            loader.contractRegistry.register(system_ids_1.peersSystemPackageId, (0, device_operations_contract_1.getDeviceOperationsContractDefinition)());
+            await consumedContracts.resolveConsumedContracts(context, loader.contractRegistry, definition);
+            const remote = (await definition.remotes?.[0].handle
+                ?.consumer);
+            await expect(remote.device((0, utils_1.newid)()).tools.getDeviceStatus()).rejects.toThrow("packages cannot call system contract");
+            expect(emit).not.toHaveBeenCalled();
+            remote.dispose();
+        }
+        finally {
+            (0, remote_contract_transport_1.setRemoteContractTransportFactory)(undefined);
+            await loader.dispose();
+        }
+    });
     it.each([
         ["contract", "quarantine"],
         ["contract", "unload"],
@@ -294,7 +323,7 @@ describe("host load invalidation", () => {
         const externalConsumer = (0, contract_proxy_1.createContractConsumer)(definition.contracts[0], clientTransport);
         try {
             await load();
-            consumer = await loader.resolveConsumedContract({ contractId, version: 1 });
+            consumer = await loader.resolveConsumedContract({ contractId, version: 1 }, (0, utils_1.newid)());
             expect(await consumer?.tools.read()).toBe("OLD");
             expect(await externalConsumer.tools.read()).toBe("OLD");
             endpoint = await loader.resolveContractEndpoint({
@@ -834,6 +863,7 @@ describe("PackageLoader isolated artifacts", () => {
                 installed.add(next.manifest.packageId);
                 return { packageId: next.manifest.packageId, provided: [], consumes: [] };
             }),
+            updateContractLifecycle: jest.fn(async () => { }),
             uninstall: jest.fn(async (id) => {
                 installed.delete(id);
             }),
@@ -1289,6 +1319,12 @@ describe("PackageLoader isolated artifacts", () => {
     });
     it("retires isolated state only after a legacy bundle evaluates successfully", async () => {
         const runtime = makeRuntime();
+        Object.assign(runtime, {
+            getPackageHealth: () => ({
+                workerRunning: false,
+                lastWorkerError: { message: "old worker", at: 1 },
+            }),
+        });
         mockGet.mockResolvedValue(selectedVersion());
         mockGetFileContents
             .mockResolvedValueOnce(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)))
@@ -1301,5 +1337,381 @@ describe("PackageLoader isolated artifacts", () => {
         expect(runtime.uninstall).toHaveBeenCalledWith(packageId, { preserveRegistry: false });
         expect(runtime.isInstalled(packageId)).toBe(false);
         expect(loader.isIsolatedInstalled(packageId)).toBe(false);
+        expect(loader.runtimeStates()[packageId].worker).toBeUndefined();
+        expect(loader.getPackageRuntimeState(packageId)?.worker).toBeUndefined();
+    });
+    describe("runtime state", () => {
+        beforeEach(() => {
+            // An earlier executionMode case leaves the shared artifact privileged.
+            delete artifact.manifest.executionMode;
+        });
+        it("records running state with the runtime's provides and consumes", async () => {
+            const runtime = makeRuntime();
+            const provided = [{ contractId, version: 1 }];
+            const consumes = [{ contractId: (0, utils_1.newid)(), version: 2, optional: true, satisfied: false }];
+            runtime.install.mockImplementationOnce((async (next) => ({
+                packageId: next.manifest.packageId,
+                provided,
+                consumes,
+            })));
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-running" });
+            const seen = [];
+            loader.runtimeStates.subscribe((states) => seen.push(states[packageId]?.status));
+            await loader.loadPackage(pkg);
+            expect(loader.getPackageRuntimeState(packageId)).toEqual({
+                packageId,
+                status: "running",
+                running: {
+                    packageVersionId: pkg.activePackageVersionId,
+                    version: "1.0.0",
+                    versionTag: "stable",
+                    kind: "isolated",
+                    executionMode: "sandbox",
+                    provides: provided,
+                    consumes,
+                },
+                updatedAt: expect.any(Number),
+            });
+            expect(seen).toContain("running");
+            await loader.dispose();
+            expect(loader.getPackageRuntimeStates()).toEqual({});
+        });
+        it("keeps the running build on an onlyIfChanged load and reloads a changed one", async () => {
+            const runtime = makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion({ versionTag: "dev" }));
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: (0, utils_1.newid)() });
+            try {
+                const first = await loader.loadPackage(pkg);
+                expect(runtime.install).toHaveBeenCalledTimes(1);
+                await expect(loader.loadPackage(pkg, { force: true, onlyIfChanged: true })).resolves.toBe(first);
+                expect(runtime.replace).not.toHaveBeenCalled();
+                // A promotion changes only the tag, which is not part of the bundle.
+                mockGet.mockResolvedValue(selectedVersion({ versionTag: "beta" }));
+                await loader.loadPackage(pkg, { force: true, onlyIfChanged: true });
+                expect(runtime.replace).not.toHaveBeenCalled();
+                expect(loader.getPackageRuntimeState(packageId)?.running?.versionTag).toBe("beta");
+                mockGet.mockResolvedValue(selectedVersion({ versionTag: "stable" }));
+                await loader.loadPackage(pkg, { force: true, onlyIfChanged: true });
+                expect(runtime.updateContractLifecycle).toHaveBeenLastCalledWith(packageId, expect.objectContaining({ contractLifecycle: "stable", versionTag: "stable" }));
+                expect(runtime.replace).not.toHaveBeenCalled();
+                mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)({
+                    ...artifact,
+                    providerSource: `${artifact.providerSource}\n// rebuilt`,
+                })));
+                await loader.loadPackage(pkg, { force: true, onlyIfChanged: true });
+                expect(runtime.replace).toHaveBeenCalledTimes(1);
+                await loader.loadPackage(pkg, { force: true });
+                expect(runtime.replace).toHaveBeenCalledTimes(2);
+            }
+            finally {
+                await loader.dispose();
+            }
+        });
+        it.each([
+            "unload",
+            "dispose",
+            "replace",
+        ])("does not overwrite %s while an unchanged-build comparison is pending", async (action) => {
+            const runtime = makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion({ versionTag: "dev" }));
+            const bundle = Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact));
+            mockGetFileContents.mockResolvedValue(bundle);
+            const loader = new package_loader_1.PackageLoader({ dataContextId: (0, utils_1.newid)() });
+            let release;
+            let entered;
+            const waiting = new Promise((resolve) => {
+                entered = resolve;
+            });
+            const pendingRead = new Promise((resolve) => {
+                release = resolve;
+            });
+            try {
+                await loader.loadPackage(pkg);
+                mockGet.mockResolvedValue(selectedVersion({ versionTag: "beta" }));
+                mockGetFileContents.mockImplementationOnce(() => {
+                    entered();
+                    return pendingRead;
+                });
+                const pending = loader.loadPackage(pkg, { force: true, onlyIfChanged: true });
+                await waiting;
+                if (action === "replace") {
+                    mockGet.mockResolvedValue(selectedVersion({ versionTag: "stable" }));
+                    await loader.loadPackage(pkg, { force: true });
+                }
+                else if (action === "unload") {
+                    await loader.unloadPackage(packageId);
+                }
+                else {
+                    await loader.dispose();
+                }
+                const latest = loader.getPackageRuntimeState(packageId);
+                release(bundle);
+                await expect(pending).resolves.toBeUndefined();
+                expect(loader.getPackageRuntimeState(packageId)).toEqual(latest);
+                expect(runtime.updateContractLifecycle).not.toHaveBeenCalled();
+                expect(runtime.install).toHaveBeenCalledTimes(1);
+                expect(runtime.replace).toHaveBeenCalledTimes(action === "replace" ? 1 : 0);
+            }
+            finally {
+                release(bundle);
+                await loader.dispose();
+            }
+        });
+        it("validates a changed version label even when its bundle is unchanged", async () => {
+            makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: (0, utils_1.newid)() });
+            try {
+                await loader.loadPackage(pkg);
+                mockGet.mockResolvedValue(selectedVersion({ version: "2.0.0" }));
+                await expect(loader.loadPackage(pkg, { force: true, onlyIfChanged: true })).rejects.toThrow(/version mismatch/);
+                expect(loader.getPackageRuntimeState(packageId)?.running?.version).toBe("1.0.0");
+            }
+            finally {
+                await loader.dispose();
+            }
+        });
+        it("keeps the previous running version when a replacement fails", async () => {
+            const runtime = makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-replace" });
+            await loader.loadPackage(pkg);
+            runtime.replace.mockRejectedValueOnce(new Error("replacement rejected"));
+            await expect(loader.loadPackage(pkg, { force: true })).rejects.toThrow(/replacement rejected/);
+            const state = loader.getPackageRuntimeState(packageId);
+            expect(state?.status).toBe("failed");
+            expect(state?.running?.version).toBe("1.0.0");
+            expect(state?.lastError).toEqual({
+                phase: "load",
+                message: "replacement rejected",
+                packageVersionId: pkg.activePackageVersionId,
+                version: "1.0.0",
+                at: expect.any(Number),
+            });
+            await loader.loadPackage(pkg, { force: true });
+            expect(loader.getPackageRuntimeState(packageId)?.status).toBe("running");
+            expect(loader.getPackageRuntimeState(packageId)?.lastError).toBeUndefined();
+        });
+        it("records a malformed isolated envelope as a failed load", async () => {
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from("PEERS_ISOLATED_PACKAGE_V1\n{nope"));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-malformed" });
+            await expect(loader.loadPackage(pkg)).rejects.toThrow(/JSON is invalid/);
+            const state = loader.getPackageRuntimeState(packageId);
+            expect(state?.status).toBe("failed");
+            expect(state?.running).toBeUndefined();
+            expect(state?.lastError?.message).toMatch(/JSON is invalid/);
+        });
+        it("records a failed legacy evaluation", async () => {
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from("throw new Error('legacy failed');"));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-legacy" });
+            try {
+                await expect(loader.loadPackage(pkg)).resolves.toBeUndefined();
+                expect(loader.getPackageRuntimeState(packageId)).toMatchObject({
+                    status: "failed",
+                    lastError: { phase: "load", message: "legacy failed" },
+                });
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it.each([
+            "module.exports = 42;",
+            "// No exports",
+            "module.exports = {};",
+            "module.exports = { default: {} };",
+        ])("records unusable legacy exports as a failed load: %s", async (bundle) => {
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from(bundle));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-empty" });
+            try {
+                await expect(loader.loadPackage(pkg)).resolves.toBeUndefined();
+                expect(loader.getPackageRuntimeState(packageId)).toMatchObject({
+                    status: "failed",
+                    lastError: { phase: "load", message: "Package bundle exports nothing usable" },
+                });
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it("keeps the previous package when a replacement exports nothing", async () => {
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from(`module.exports = { packageId: "${packageId}" };`));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: (0, utils_1.newid)() });
+            try {
+                const previous = await loader.loadPackage(pkg);
+                const running = loader.getPackageRuntimeState(packageId)?.running;
+                mockGetFileContents.mockResolvedValue(Buffer.from("// No exports"));
+                await expect(loader.loadPackage(pkg, { force: true })).resolves.toBeUndefined();
+                expect(loader.getPackageRuntimeState(packageId)).toMatchObject({
+                    status: "failed",
+                    running,
+                    lastError: { message: "Package bundle exports nothing usable" },
+                });
+                await expect(loader.loadPackage(pkg)).resolves.toBe(previous);
+            }
+            finally {
+                warn.mockRestore();
+                await loader.dispose();
+            }
+        });
+        it("records unsupported when the host has no isolated runtime", async () => {
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-unsupported" });
+            try {
+                await loader.loadPackage(pkg);
+                expect(loader.getPackageRuntimeState(packageId)).toMatchObject({
+                    status: "unsupported",
+                    reason: expect.stringMatching(/no isolated package runtime/),
+                });
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it("records unavailable when the selected bundle is not on this device", async () => {
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+            makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(undefined);
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-unavailable" });
+            try {
+                await expect(loader.loadPackage(pkg)).resolves.toBeUndefined();
+                expect(loader.getPackageRuntimeState(packageId)).toMatchObject({
+                    status: "unavailable",
+                    reason: expect.stringMatching(/not on this device/),
+                });
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it("records disabled and unloaded packages without a running version", async () => {
+            makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-disabled" });
+            await loader.loadPackage(pkg);
+            await loader.loadPackage({ ...pkg, disabled: true });
+            expect(loader.getPackageRuntimeState(packageId)).toEqual({
+                packageId,
+                status: "disabled",
+                reason: expect.any(String),
+                updatedAt: expect.any(Number),
+            });
+            await loader.unloadPackage(packageId, { reason: "uninstalled" });
+            expect(loader.getPackageRuntimeState(packageId)).toEqual({
+                packageId,
+                status: "unloaded",
+                reason: "uninstalled",
+                updatedAt: expect.any(Number),
+            });
+        });
+        it("does not let a superseded load overwrite newer state", async () => {
+            const runtime = makeRuntime();
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-superseded" });
+            let release;
+            let entered;
+            const gate = new Promise((resolve) => {
+                release = resolve;
+            });
+            const waiting = new Promise((resolve) => {
+                entered = resolve;
+            });
+            mockSignAndSave.mockImplementationOnce(async () => {
+                entered();
+                await gate;
+            });
+            mockGet.mockResolvedValue(selectedVersion({ version: "0.0.1", versionTag: "dev" }));
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const reading = jest.fn(() => (0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact));
+            loader._readLocalBundle = reading;
+            try {
+                const installing = loader.loadPackage(pkg, { force: true, localPath: "/pkg" });
+                await waiting;
+                await loader.unloadPackage(packageId);
+                release();
+                await expect(installing).rejects.toThrow(/invalidated/);
+                expect(runtime.install).not.toHaveBeenCalled();
+                expect(loader.getPackageRuntimeState(packageId)?.status).toBe("unloaded");
+                expect(loader.getPackageRuntimeState(packageId)?.lastError).toBeUndefined();
+            }
+            finally {
+                release();
+                await loader.dispose();
+            }
+        });
+        it("publishes isolated worker health and detaches on disposal", async () => {
+            const runtime = makeRuntime();
+            let health = {
+                workerRunning: false,
+            };
+            let notify;
+            const unsubscribe = jest.fn();
+            Object.assign(runtime, {
+                getPackageHealth: jest.fn(() => health),
+                subscribePackageHealth: (listener) => {
+                    notify = listener;
+                    return unsubscribe;
+                },
+            });
+            mockGet.mockResolvedValue(selectedVersion());
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            const loader = new package_loader_1.PackageLoader({ dataContextId: "ctx-state-health" });
+            await loader.loadPackage(pkg);
+            const seen = [];
+            loader.runtimeStates.subscribe((states) => seen.push(states[packageId]?.worker));
+            health = { workerRunning: false, lastWorkerError: { message: "boom", at: 1 } };
+            notify(packageId);
+            expect(loader.getPackageRuntimeState(packageId)?.worker).toEqual(health);
+            expect(loader.getPackageRuntimeStates()[packageId]?.worker).toEqual(health);
+            expect(loader.runtimeStates()[packageId]?.worker).toEqual(health);
+            expect(seen).toContainEqual(health);
+            await loader.dispose();
+            expect(unsubscribe).toHaveBeenCalledTimes(1);
+            notify(packageId);
+            expect(loader.runtimeStates()).toEqual({});
+        });
+        it.each([
+            "failure",
+            "unavailable",
+        ])("ignores an older load's late %s after a newer load", async (outcome) => {
+            makeRuntime();
+            mockGet.mockResolvedValue(selectedVersion());
+            let finish;
+            let fail;
+            const pending = new Promise((resolve, reject) => {
+                finish = resolve;
+                fail = reject;
+            });
+            mockGetFileContents.mockReturnValueOnce(pending);
+            const loader = new package_loader_1.PackageLoader({ dataContextId: (0, utils_1.newid)() });
+            const older = loader.loadPackage(pkg, { force: true });
+            // Let the older load start its file read before the newer attempt.
+            await Promise.resolve();
+            mockGetFileContents.mockResolvedValue(Buffer.from((0, isolated_artifact_1.serializeIsolatedPackageArtifact)(artifact)));
+            await loader.loadPackage(pkg, { force: true });
+            if (outcome === "failure")
+                fail(new Error("old failure"));
+            else
+                finish(undefined);
+            await older;
+            expect(loader.getPackageRuntimeState(packageId)?.status).toBe("running");
+            expect(loader.getPackageRuntimeState(packageId)?.lastError).toBeUndefined();
+            await loader.dispose();
+        });
     });
 });

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

@@ -0,0 +1,112 @@
+/**
+ * Observed, per-device runtime state of the packages in one data context.
+ *
+ * The {@link import("./package-loader").PackageLoader} records what it actually
+ * loaded, what failed, and why. State is in memory only: it describes this
+ * process and resets when the process restarts (and reloads everything).
+ */
+/**
+ * Outcome of the most recent load, unload, or replacement attempt for a package.
+ *
+ * - `running` — the selected version loaded and is serving.
+ * - `failed` — the last attempt failed. {@link IPackageRuntimeState.running} still names
+ *   the previous version when it kept serving.
+ * - `unavailable` — the selected version's bundle is not on this device yet (for example
+ *   still syncing).
+ * - `unsupported` — this host cannot run the package (an isolated package on a host
+ *   without an isolated runtime).
+ * - `disabled` — the package row is disabled for the group.
+ * - `unloaded` — the package was unloaded or uninstalled.
+ */
+export type PackageRuntimeStatus = "running" | "failed" | "unavailable" | "unsupported" | "disabled" | "unloaded";
+/**
+ * How a running package executes.
+ *
+ * - `isolated` — an isolated artifact served by the host's isolated runtime.
+ * - `contract` — an in-process `definePackage()` bundle.
+ * - `legacy` — an in-process legacy bundle without a package definition.
+ */
+export type PackageRuntimeKind = "isolated" | "contract" | "legacy";
+/** A contract a running package provides. */
+export interface IPackageRuntimeProvidedContract {
+    /** Provided contract identity. */
+    contractId: string;
+    /** Provided contract version. */
+    version: number;
+}
+/** A contract a running isolated package consumes, with whether a provider matched. */
+export interface IPackageRuntimeConsumedContract {
+    /** Consumed contract identity. */
+    contractId: string;
+    /** Consumed contract version. */
+    version: number;
+    /** True when the package declared the dependency optional. */
+    optional?: boolean;
+    /** True when a provider for the dependency was available at install time. */
+    satisfied: boolean;
+}
+/** The package version currently serving on this device. */
+export interface IPackageRunningVersion {
+    /** PackageVersion record that was loaded, when known. */
+    packageVersionId?: string;
+    /** Semantic version of the loaded PackageVersion. */
+    version?: string;
+    /** Release channel of the loaded PackageVersion (`dev`, `beta`, `stable`, ...). */
+    versionTag?: string;
+    /** How the package executes. */
+    kind: PackageRuntimeKind;
+    /** Isolated execution mode; absent for in-process packages. */
+    executionMode?: "sandbox" | "privileged";
+    /** Contracts the isolated runtime reported as provided. */
+    provides?: IPackageRuntimeProvidedContract[];
+    /** Contracts the isolated runtime reported as consumed. */
+    consumes?: IPackageRuntimeConsumedContract[];
+}
+/** The most recent failure observed for a package. */
+export interface IPackageRuntimeError {
+    /** `load` — installing or evaluating the bundle; `worker` — starting the isolated worker. */
+    phase: "load" | "worker";
+    /** Error message. */
+    message: string;
+    /** PackageVersion whose load failed, when known. */
+    packageVersionId?: string;
+    /** Semantic version whose load failed, when known. */
+    version?: string;
+    /** Epoch milliseconds when the failure was recorded. */
+    at: number;
+}
+/** Health of a package's isolated worker, reported by the isolated runtime. */
+export interface IPackageWorkerHealth {
+    /** True while a worker process/thread is running for the package. */
+    workerRunning: boolean;
+    /** Last worker start or crash failure since the package was installed or replaced. */
+    lastWorkerError?: {
+        message: string;
+        at: number;
+    };
+}
+/** Observed runtime state of one package on this device, in one data context. */
+export interface IPackageRuntimeState {
+    /** Package the state describes. */
+    packageId: string;
+    /** Outcome of the most recent attempt. */
+    status: PackageRuntimeStatus;
+    /** What is serving now; kept when a replacement fails. */
+    running?: IPackageRunningVersion;
+    /** Most recent failure; cleared when a later load succeeds. */
+    lastError?: IPackageRuntimeError;
+    /** Human-readable explanation for `unavailable`, `unsupported`, `disabled`, or `unloaded`. */
+    reason?: string;
+    /** Isolated worker health, merged on read when the runtime reports it. */
+    worker?: IPackageWorkerHealth;
+    /** Epoch milliseconds of the last change. */
+    updatedAt: number;
+}
+/** Map of package id to observed runtime state for one data context. */
+export type PackageRuntimeStates = Record<string, IPackageRuntimeState>;
+/**
+ * Return the message of an unknown thrown value.
+ *
+ * @param error - Thrown value.
+ */
+export declare function runtimeErrorMessage(error: unknown): string;

package/dist/package-loader/package-runtime-state.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Observed, per-device runtime state of the packages in one data context.
+ *
+ * The {@link import("./package-loader").PackageLoader} records what it actually
+ * loaded, what failed, and why. State is in memory only: it describes this
+ * process and resets when the process restarts (and reloads everything).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeErrorMessage = runtimeErrorMessage;
+/**
+ * Return the message of an unknown thrown value.
+ *
+ * @param error - Thrown value.
+ */
+function runtimeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/package-loader/resolve-consumed-contracts.js

@@ -31,8 +31,8 @@ async function resolveConsumedContracts(dataContext, registry, packageDefinition
                 continue;
             }
             const consumer = dataContext.packageLoader?.resolveConsumedContract
-                ? await dataContext.packageLoader.resolveConsumedContract(dep)
-                : await resolveLegacyLocalConsumer(dataContext, selected, dep.contractId, dep.version);
+                ? await dataContext.packageLoader.resolveConsumedContract(dep, packageDefinition.packageId)
+                : await resolveLegacyLocalConsumer(dataContext, selected, dep.contractId, dep.version, packageDefinition.packageId);
             if (!consumer) {
                 settleMissing(dep.optional === true, handle, dep.contractId, dep.version, `provider ${selected.providerPackageId} has no live endpoint`);
                 continue;
@@ -61,7 +61,7 @@ async function resolveRemoteContracts(dataContext, packageDefinition) {
             if (!loader?.resolveRemoteContract) {
                 throw new Error(`Remote contract ${key} requires a package loader on the data context`);
             }
-            const remote = await loader.resolveRemoteContract(declaration);
+            const remote = await loader.resolveRemoteContract(declaration, packageDefinition.packageId);
             if (!remote) {
                 throw new Error(`Remote contract ${key} could not be resolved: its definition is not registered on this device`);
             }
@@ -72,7 +72,7 @@ async function resolveRemoteContracts(dataContext, packageDefinition) {
         }
     }
 }
-async function resolveLegacyLocalConsumer(dataContext, selected, contractId, version) {
+async function resolveLegacyLocalConsumer(dataContext, selected, contractId, version, callerPackageId) {
     const resolver = (0, contract_resolvers_1.getContractResolver)(contractId, version, selected.providerPackageId, dataContext);
     if (!resolver) {
         return undefined;
@@ -80,6 +80,7 @@ async function resolveLegacyLocalConsumer(dataContext, selected, contractId, ver
     const resolution = await resolver({ dataContext });
     return (0, create_local_consumer_1.createLocalContractConsumer)(selected.definition, resolution, {
         dataContextId: dataContext.dataContextId,
+        context: { dataContext, callerPackageId },
     });
 }
 function settleMissing(optional, handle, contractId, version, reason) {

package/dist/package-loader/resolve-consumed-contracts.test.js

@@ -135,7 +135,7 @@ describe("resolveConsumedContracts", () => {
                 remoteHandle = pkg.remote(contractId, 1);
             });
             await (0, resolve_consumed_contracts_1.resolveConsumedContracts)(dataContext, new registry_1.ContractRegistry(), packageDefinition);
-            expect(resolveRemoteContract).toHaveBeenCalledWith(expect.objectContaining({ contractId, version: 1 }));
+            expect(resolveRemoteContract).toHaveBeenCalledWith(expect.objectContaining({ contractId, version: 1 }), packageDefinition.packageId);
             await expect(remoteHandle?.consumer).resolves.toBe(remote);
         });
         it("rejects a remote handle when the contract definition is unknown locally", async () => {