@peers-app/peers-sdk 0.23.4 → 0.23.5

package/dist/data/package-version-resolver.js

@@ -13,6 +13,7 @@ exports.updatePackagePrefs = updatePackagePrefs;
 exports.getEffectivePackagePrefs = getEffectivePackagePrefs;
 exports.resolveDevicePackageVersion = resolveDevicePackageVersion;
 exports.hasDeviceFollowOverride = hasDeviceFollowOverride;
+exports.readStoredPackageLocalPath = readStoredPackageLocalPath;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const assistants_1 = require("./assistants");
 const group_member_roles_1 = require("./group-member-roles");
@@ -60,7 +61,13 @@ async function updatePackagePrefs(packageId, prefs, dataContext) {
         const { activePackageVersionId: _, ...rest } = prefs;
         effectivePrefs = rest;
     }
-    pvar({ ...existing, ...effectivePrefs });
+    const next = { ...existing, ...effectivePrefs };
+    for (const key of Object.keys(next)) {
+        if (next[key] === undefined) {
+            delete next[key];
+        }
+    }
+    pvar(next);
 }
 /**
  * Pure function: merge raw device prefs with the group-level `IPackage`
@@ -111,6 +118,37 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (!effectiveActivePvId) {
         return { loaded: false, upgraded: false };
     }
+    const localPath = opts?.localPath ??
+        (await readStoredPackageLocalPath(pkg.packageId, dataContext).catch(() => undefined));
+    const compatibilityTargetId = rawPrefs.compatibilityFallbackForPackageVersionId;
+    if (compatibilityTargetId &&
+        compatibilityTargetId !== effectiveActivePvId &&
+        dataContext.packageLoader.supportsIsolatedPackages()) {
+        const compatibilityTarget = await (0, package_versions_1.PackageVersions)(dataContext)
+            .get(compatibilityTargetId)
+            .catch(() => undefined);
+        if (compatibilityTarget) {
+            try {
+                const restored = await dataContext.packageLoader.loadPackage(pkg, {
+                    force: true,
+                    localPath,
+                    packageVersionId: compatibilityTargetId,
+                });
+                if (restored) {
+                    await updatePackagePrefs(pkg.packageId, {
+                        activePackageVersionId: compatibilityTargetId === pkg.activePackageVersionId
+                            ? undefined
+                            : compatibilityTargetId,
+                        compatibilityFallbackForPackageVersionId: undefined,
+                    }, dataContext);
+                    return { loaded: true, pv: compatibilityTarget, upgraded: true };
+                }
+            }
+            catch (error) {
+                console.warn(`[PackageVersionResolver] Compatibility target ${compatibilityTarget.version} remains unavailable for ${pkg.name}:`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
     // If the device (or the group-level default) has pinned this package, just load
     // the current version — never auto-upgrade.
     if (isPinned) {
@@ -121,9 +159,15 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
             return { loaded: false, pv: undefined, upgraded: false };
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
             force: opts?.force,
-            localPath: opts?.localPath,
+            localPath,
             packageVersionId: effectiveActivePvId,
         });
+        if (!instance) {
+            const fallback = await loadOlderCompatiblePackageVersion(pkg, dataContext, pv, followRange, followTags, localPath, rawPrefs.pinned === true);
+            if (fallback) {
+                return { loaded: true, pv: fallback.pv, upgraded: false };
+            }
+        }
         return { loaded: !!instance, pv, upgraded: false };
     }
     // Load the currently active PV for comparison
@@ -139,9 +183,15 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (activePv?.versionTag === "dev") {
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
             force: opts?.force,
-            localPath: opts?.localPath,
+            localPath,
             packageVersionId: effectiveActivePvId,
         });
+        if (!instance) {
+            const fallback = await loadOlderCompatiblePackageVersion(pkg, dataContext, activePv, followRange, followTags, localPath, rawPrefs.pinned === true);
+            if (fallback) {
+                return { loaded: true, pv: fallback.pv, upgraded: false };
+            }
+        }
         return { loaded: !!instance, pv: activePv, upgraded: false };
     }
     // Evaluate all available PVs to find the best one
@@ -167,9 +217,15 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (activePv) {
             const instance = await dataContext.packageLoader.loadPackage(pkg, {
                 force: opts?.force,
-                localPath: opts?.localPath,
+                localPath,
                 packageVersionId: effectiveActivePvId,
             });
+            if (!instance) {
+                const fallback = await loadOlderCompatiblePackageVersion(pkg, dataContext, activePv, followRange, followTags, localPath, rawPrefs.pinned === true);
+                if (fallback) {
+                    return { loaded: true, pv: fallback.pv, upgraded: false };
+                }
+            }
             return { loaded: !!instance, pv: activePv, upgraded: false };
         }
         return { loaded: false, upgraded: false };
@@ -178,7 +234,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     // auto-download missing chunks from peers)
     const instance = await dataContext.packageLoader.loadPackage(pkg, {
         force: true,
-        localPath: opts?.localPath,
+        localPath,
         packageVersionId: bestPv.packageVersionId,
     });
     if (!instance) {
@@ -186,9 +242,15 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (activePv) {
             const fallbackInstance = await dataContext.packageLoader.loadPackage(pkg, {
                 force: opts?.force,
-                localPath: opts?.localPath,
+                localPath,
                 packageVersionId: effectiveActivePvId,
             });
+            if (!fallbackInstance) {
+                const olderFallback = await loadOlderCompatiblePackageVersion(pkg, dataContext, activePv, followRange, followTags, localPath, rawPrefs.pinned === true);
+                if (olderFallback) {
+                    return { loaded: true, pv: olderFallback.pv, upgraded: false };
+                }
+            }
             return { loaded: !!fallbackInstance, pv: activePv, upgraded: false };
         }
         return { loaded: false, upgraded: false };
@@ -227,9 +289,60 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     }
     await updatePackagePrefs(pkg.packageId, {
         activePackageVersionId: advancedGroupActiveVersion ? undefined : bestPv.packageVersionId,
+        compatibilityFallbackForPackageVersionId: undefined,
     }, dataContext);
     return { loaded: true, pv: bestPv, upgraded: true };
 }
+async function loadOlderCompatiblePackageVersion(pkg, dataContext, unavailableVersion, followRange, followTags, localPath, devicePinned) {
+    if (dataContext.packageLoader.supportsIsolatedPackages()) {
+        return undefined;
+    }
+    const versions = await (0, package_versions_1.PackageVersions)(dataContext).list({ packageId: pkg.packageId });
+    const candidates = versions
+        .filter((candidate) => {
+        if (candidate.packageVersionId === unavailableVersion.packageVersionId) {
+            return false;
+        }
+        if ((0, package_versions_1.isNewerVersion)(unavailableVersion.version, candidate.version)) {
+            return false;
+        }
+        if (!(0, package_versions_1.doesTagMatch)(unavailableVersion.versionTag, candidate.versionTag, followTags, undefined)) {
+            return false;
+        }
+        return (0, package_versions_1.isVersionInRange)(unavailableVersion.version, candidate.version, followRange);
+    })
+        .sort((left, right) => {
+        if ((0, package_versions_1.isNewerVersion)(right.version, left.version)) {
+            return -1;
+        }
+        if ((0, package_versions_1.isNewerVersion)(left.version, right.version)) {
+            return 1;
+        }
+        return 0;
+    });
+    for (const candidate of candidates) {
+        try {
+            const instance = await dataContext.packageLoader.loadPackage(pkg, {
+                force: true,
+                localPath,
+                packageVersionId: candidate.packageVersionId,
+            });
+            if (!instance) {
+                continue;
+            }
+            await updatePackagePrefs(pkg.packageId, {
+                activePackageVersionId: candidate.packageVersionId,
+                compatibilityFallbackForPackageVersionId: unavailableVersion.packageVersionId,
+                ...(devicePinned ? { pinned: true } : {}),
+            }, dataContext);
+            return { instance, pv: candidate };
+        }
+        catch (error) {
+            console.warn(`[PackageVersionResolver] Compatibility fallback ${candidate.version} failed for ${pkg.name}:`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return undefined;
+}
 /**
  * Save a loaded package's assistants and workflows into the data context.
  * Contract-installed packages are skipped because their content is already
@@ -255,6 +368,29 @@ function hasDeviceFollowOverride(prefs) {
         return false;
     return prefs.followRange != null || prefs.followTags != null || prefs.pinned != null;
 }
+/**
+ * Read the stored local checkout path for a package, if one is set.
+ *
+ * Used so isolated local-dev packages can load `dist/package.bundle.js` from
+ * disk even when startup resolution does not receive an explicit `localPath`.
+ *
+ * @param packageId - Package whose `packageLocalPath_*` device var to read.
+ * @param dataContext - Data context that owns the device var.
+ * @returns Trimmed path, or `undefined` when unset or empty.
+ */
+async function readStoredPackageLocalPath(packageId, dataContext) {
+    const pvar = (0, persistent_vars_1.groupDeviceVar)(`packageLocalPath_${packageId}`, {
+        defaultValue: "",
+        dataContext,
+    });
+    await pvar.loadingPromise;
+    const value = pvar();
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
 /** Convert `IPackage.versionFollowRange` to the resolver's range type. */
 function rangeFromPkg(pkg) {
     const r = pkg.versionFollowRange;

package/dist/data/package-version-resolver.test.js

@@ -180,6 +180,48 @@ describe("resolveDevicePackageVersion — regression coverage", () => {
         expect(result.upgraded).toBe(true);
         expect(loadedPvIds).toContain(betaPv.packageVersionId);
     });
+    it("falls back locally when isolation is unavailable and automatically recovers later", async () => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const legacyV1 = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const legacyV1_5 = makePV(packageId, { version: "1.5.0", versionTag: "stable" });
+        const isolatedV2 = makePV(packageId, { version: "2.0.0", versionTag: "stable" });
+        await (0, package_versions_1.PackageVersions)(dc).save(legacyV1);
+        await (0, package_versions_1.PackageVersions)(dc).save(legacyV1_5);
+        await (0, package_versions_1.PackageVersions)(dc).save(isolatedV2);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: isolatedV2.packageVersionId,
+            versionFollowRange: "pinned",
+            followVersionTags: "stable",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        let isolationAvailable = false;
+        jest
+            .spyOn(dc.packageLoader, "supportsIsolatedPackages")
+            .mockImplementation(() => isolationAvailable);
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId === isolatedV2.packageVersionId && !isolationAvailable) {
+                return undefined;
+            }
+            return { packageId };
+        });
+        const fallback = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(fallback.loaded).toBe(true);
+        expect(fallback.upgraded).toBe(false);
+        expect(fallback.pv?.packageVersionId).toBe(legacyV1_5.packageVersionId);
+        const prefs = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await prefs.loadingPromise;
+        expect(prefs()?.activePackageVersionId).toBe(legacyV1_5.packageVersionId);
+        expect(prefs()?.compatibilityFallbackForPackageVersionId).toBe(isolatedV2.packageVersionId);
+        isolationAvailable = true;
+        const recovered = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(recovered.loaded).toBe(true);
+        expect(recovered.upgraded).toBe(true);
+        expect(recovered.pv?.packageVersionId).toBe(isolatedV2.packageVersionId);
+        expect(prefs()?.activePackageVersionId).toBeUndefined();
+        expect(prefs()?.compatibilityFallbackForPackageVersionId).toBeUndefined();
+    });
 });
 describe("resolveDevicePackageVersion — expected behavior (control)", () => {
     it("advances the group active version when an admin auto-upgrades without device overrides", async () => {

package/dist/data/persistent-var-identity.d.ts

@@ -0,0 +1,37 @@
+/** Storage/synchronization scopes supported by Peers persistent variables. */
+export declare const PERSISTENT_VAR_SCOPES: readonly ["device", "user", "group", "groupDevice", "groupUser"];
+/** One of the five Peers persistent-variable storage scopes. */
+export type PersistentVarScope = (typeof PERSISTENT_VAR_SCOPES)[number];
+/**
+ * Prefix a package-local pvar name with trusted package identity.
+ *
+ * This must run on the host before deterministic ID generation. Guest code
+ * supplies only `logicalName`; it never chooses `packageId`.
+ *
+ * @param packageId - Trusted owning package ID.
+ * @param logicalName - Package-local variable name.
+ * @returns Stable package-prefixed base name.
+ */
+export declare function packageScopedPersistentVarName(packageId: string, logicalName: string): string;
+/**
+ * Return the physical DB name for a pvar scope.
+ *
+ * Group-device and group-user pvars append the trusted route context so one
+ * logical variable can hold a different value for each group.
+ *
+ * @param name - Base variable name, already package-prefixed when package-owned.
+ * @param scope - Persistent-variable scope.
+ * @param dataContextId - Trusted route context required by group-dependent scopes.
+ * @returns Name stored in `PersistentVars` and hashed by `deterministicPvarId`.
+ */
+export declare function persistentVarStorageName(name: string, scope: PersistentVarScope, dataContextId?: string): string;
+/**
+ * Derive the full physical DB name for an isolated package-owned pvar.
+ *
+ * @param packageId - Trusted owning package ID.
+ * @param logicalName - Guest-visible package-local name.
+ * @param scope - Persistent-variable scope.
+ * @param dataContextId - Trusted route context for group-dependent scopes.
+ * @returns Package-prefixed, scope-qualified storage name.
+ */
+export declare function packageScopedPersistentVarStorageName(packageId: string, logicalName: string, scope: PersistentVarScope, dataContextId?: string): string;

package/dist/data/persistent-var-identity.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSISTENT_VAR_SCOPES = void 0;
+exports.packageScopedPersistentVarName = packageScopedPersistentVarName;
+exports.persistentVarStorageName = persistentVarStorageName;
+exports.packageScopedPersistentVarStorageName = packageScopedPersistentVarStorageName;
+const utils_1 = require("../utils");
+/** Storage/synchronization scopes supported by Peers persistent variables. */
+exports.PERSISTENT_VAR_SCOPES = [
+    "device",
+    "user",
+    "group",
+    "groupDevice",
+    "groupUser",
+];
+/**
+ * Prefix a package-local pvar name with trusted package identity.
+ *
+ * This must run on the host before deterministic ID generation. Guest code
+ * supplies only `logicalName`; it never chooses `packageId`.
+ *
+ * @param packageId - Trusted owning package ID.
+ * @param logicalName - Package-local variable name.
+ * @returns Stable package-prefixed base name.
+ */
+function packageScopedPersistentVarName(packageId, logicalName) {
+    if (!(0, utils_1.isid)(packageId)) {
+        throw new Error(`Invalid package ID for persistent variable: ${packageId}`);
+    }
+    if (typeof logicalName !== "string" || logicalName.trim() === "") {
+        throw new Error("Persistent variable name must be a non-empty string");
+    }
+    return `${packageId}_${logicalName}`;
+}
+/**
+ * Return the physical DB name for a pvar scope.
+ *
+ * Group-device and group-user pvars append the trusted route context so one
+ * logical variable can hold a different value for each group.
+ *
+ * @param name - Base variable name, already package-prefixed when package-owned.
+ * @param scope - Persistent-variable scope.
+ * @param dataContextId - Trusted route context required by group-dependent scopes.
+ * @returns Name stored in `PersistentVars` and hashed by `deterministicPvarId`.
+ */
+function persistentVarStorageName(name, scope, dataContextId) {
+    if (!exports.PERSISTENT_VAR_SCOPES.includes(scope)) {
+        throw new Error(`Invalid persistent variable scope: ${String(scope)}`);
+    }
+    if (scope === "groupDevice" || scope === "groupUser") {
+        if (!dataContextId) {
+            throw new Error(`Persistent variable scope ${scope} requires a data context`);
+        }
+        return `${name}_${dataContextId}`;
+    }
+    return name;
+}
+/**
+ * Derive the full physical DB name for an isolated package-owned pvar.
+ *
+ * @param packageId - Trusted owning package ID.
+ * @param logicalName - Guest-visible package-local name.
+ * @param scope - Persistent-variable scope.
+ * @param dataContextId - Trusted route context for group-dependent scopes.
+ * @returns Package-prefixed, scope-qualified storage name.
+ */
+function packageScopedPersistentVarStorageName(packageId, logicalName, scope, dataContextId) {
+    return persistentVarStorageName(packageScopedPersistentVarName(packageId, logicalName), scope, dataContextId);
+}

package/dist/data/persistent-vars.d.ts

@@ -11,6 +11,8 @@ import { type Observable } from "../observable";
 import type { ISaveOptions } from "./orm";
 import { Table } from "./orm/table";
 import { type ITableMetaData } from "./orm/types";
+import { type PersistentVarScope } from "./persistent-var-identity";
+export { PERSISTENT_VAR_SCOPES, type PersistentVarScope, packageScopedPersistentVarName, packageScopedPersistentVarStorageName, persistentVarStorageName, } from "./persistent-var-identity";
 declare const schema: z.ZodObject<{
     persistentVarId: z.ZodEffects<z.ZodString, string, string>;
     name: z.ZodString;
@@ -26,7 +28,6 @@ declare const schema: z.ZodObject<{
     userCreated: z.ZodOptional<z.ZodBoolean>;
     isSecret: z.ZodOptional<z.ZodBoolean>;
     modifiedAt: z.ZodOptional<z.ZodNumber>;
-    packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     value: {
@@ -38,7 +39,6 @@ declare const schema: z.ZodObject<{
     userCreated?: boolean | undefined;
     isSecret?: boolean | undefined;
     modifiedAt?: number | undefined;
-    packageId?: string | undefined;
 }, {
     name: string;
     value: {
@@ -50,7 +50,6 @@ declare const schema: z.ZodObject<{
     userCreated?: boolean | undefined;
     isSecret?: boolean | undefined;
     modifiedAt?: number | undefined;
-    packageId?: string | undefined;
 }>;
 /** Table metadata for persisted observable variables. */
 export declare const persistentVarsMetaData: ITableMetaData;
@@ -91,7 +90,7 @@ export type PersistentVar<T> = Observable<T> & {
 /** Resolve a persistent-variable record by name, preferring device scope. */
 export declare function getPersistentVar(name: string, dataContext?: DataContext): Promise<IPersistentVar | undefined>;
 interface IPersistentVarOptionsBase {
-    scope?: "device" | "user" | "group" | "groupDevice" | "groupUser";
+    scope?: PersistentVarScope;
     userContext?: UserContext;
     dataContext?: DataContext;
     isSecret?: boolean;
@@ -133,4 +132,3 @@ export declare function groupDeviceVar<T = string>(name: string, opts?: Omit<IPe
  */
 export declare function groupUserVar<T = string>(name: string, opts: Omit<IPersistentVarOptionsWithDefault<T>, "scope">): PersistentVar<T>;
 export declare function groupUserVar<T = string>(name: string, opts?: Omit<IPersistentVarOptionsWithoutDefault<T>, "scope">): PersistentVar<T | undefined>;
-export {};

package/dist/data/persistent-vars.js

@@ -40,7 +40,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     done = true;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PersistentVarsTable = exports.persistentVarsMetaData = void 0;
+exports.PersistentVarsTable = exports.persistentVarsMetaData = exports.persistentVarStorageName = exports.packageScopedPersistentVarStorageName = exports.packageScopedPersistentVarName = exports.PERSISTENT_VAR_SCOPES = void 0;
 exports.PersistentVars = PersistentVars;
 exports.getPersistentVar = getPersistentVar;
 exports.deviceVar = deviceVar;
@@ -59,10 +59,16 @@ const decorators_1 = require("./orm/decorators");
 const table_1 = require("./orm/table");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
+const persistent_var_identity_1 = require("./persistent-var-identity");
+var persistent_var_identity_2 = require("./persistent-var-identity");
+Object.defineProperty(exports, "PERSISTENT_VAR_SCOPES", { enumerable: true, get: function () { return persistent_var_identity_2.PERSISTENT_VAR_SCOPES; } });
+Object.defineProperty(exports, "packageScopedPersistentVarName", { enumerable: true, get: function () { return persistent_var_identity_2.packageScopedPersistentVarName; } });
+Object.defineProperty(exports, "packageScopedPersistentVarStorageName", { enumerable: true, get: function () { return persistent_var_identity_2.packageScopedPersistentVarStorageName; } });
+Object.defineProperty(exports, "persistentVarStorageName", { enumerable: true, get: function () { return persistent_var_identity_2.persistentVarStorageName; } });
 const schema = zod_1.z.object({
     persistentVarId: zod_types_1.zodPeerId,
     name: zod_1.z.string(),
-    scope: zod_1.z.enum(["device", "user", "group", "groupDevice", "groupUser"]),
+    scope: zod_1.z.enum(persistent_var_identity_1.PERSISTENT_VAR_SCOPES),
     value: zod_1.z
         .object({
         value: zod_1.z.any(),
@@ -75,9 +81,6 @@ const schema = zod_1.z.object({
         .number()
         .optional()
         .describe("Timestamp of when this pvar was last modified (Date.now())"),
-    packageId: zod_types_1.zodPeerId
-        .optional()
-        .describe("The package that owns this persistent variable, if any"),
 });
 /** Table metadata for persisted observable variables. */
 exports.persistentVarsMetaData = {
@@ -186,8 +189,21 @@ async function getPersistentVar(name, dataContext) {
     }
     return pVars[0];
 }
-/** Cache for pvar instances keyed by scope:name:userContextId:dataContextId */
+/** Cache for pvar instances keyed by scope, name, user-context instance, and data context. */
 const pvarCache = new Map();
+const userContextCacheIds = new WeakMap();
+let nextUserContextCacheId = 1;
+function userContextCacheId(userContext) {
+    if (!userContext) {
+        return "";
+    }
+    let id = userContextCacheIds.get(userContext);
+    if (id === undefined) {
+        id = nextUserContextCacheId++;
+        userContextCacheIds.set(userContext, id);
+    }
+    return String(id);
+}
 function deviceVar(name, opts) {
     const fullOpts = { ...opts, scope: "device" };
     if (opts?.defaultValue !== undefined) {
@@ -236,7 +252,7 @@ function groupUserVar(name, opts) {
 function persistentVarFactory(name, opts) {
     const scope = opts.scope || "device";
     // Check cache - key is based on the parameters passed in
-    const cacheKey = `${scope}:${name}:${opts?.userContext?.userId ?? ""}:${opts?.dataContext?.dataContextId ?? ""}`;
+    const cacheKey = `${scope}:${name}:${userContextCacheId(opts?.userContext)}:${opts?.dataContext?.dataContextId ?? ""}`;
     const cached = pvarCache.get(cacheKey);
     if (cached) {
         return cached;
@@ -273,12 +289,8 @@ function persistentVarFactory(name, opts) {
                     }
                 }
                 function getVarNameInDb() {
-                    if (scope === "groupDevice" || scope === "groupUser") {
-                        const dc = opts?.dataContext || userContext.defaultDataContext();
-                        // if it's a group var saved in the user's personal db, it's postfixed with the dataContextId to make it unique
-                        return `${name}_${dc?.dataContextId}`;
-                    }
-                    return name;
+                    const dc = opts?.dataContext || userContext.defaultDataContext();
+                    return (0, persistent_var_identity_1.persistentVarStorageName)(name, scope, dc?.dataContextId);
                 }
                 async function loadRecFromDb() {
                     const dc = getDataContext();

package/dist/data/persistent-vars.package-scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/persistent-vars.package-scope.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+const persistent_var_identity_1 = require("./persistent-var-identity");
+describe("package-scoped persistent variable identity", () => {
+    test("prefixes package identity before deterministic ID generation", () => {
+        const packageId = (0, utils_1.newid)();
+        const physicalName = (0, persistent_var_identity_1.packageScopedPersistentVarStorageName)(packageId, "settings", "device", (0, utils_1.newid)());
+        expect(physicalName).toBe(`${packageId}_settings`);
+        expect((0, utils_1.deterministicPvarId)(physicalName)).not.toBe((0, utils_1.deterministicPvarId)("settings"));
+    });
+    test("qualifies group-dependent scopes with the trusted context", () => {
+        const packageId = (0, utils_1.newid)();
+        const dataContextId = (0, utils_1.newid)();
+        const baseName = (0, persistent_var_identity_1.packageScopedPersistentVarName)(packageId, "thread:dynamic");
+        expect((0, persistent_var_identity_1.persistentVarStorageName)(baseName, "device", dataContextId)).toBe(baseName);
+        expect((0, persistent_var_identity_1.persistentVarStorageName)(baseName, "user", dataContextId)).toBe(baseName);
+        expect((0, persistent_var_identity_1.persistentVarStorageName)(baseName, "group", dataContextId)).toBe(baseName);
+        expect((0, persistent_var_identity_1.persistentVarStorageName)(baseName, "groupDevice", dataContextId)).toBe(`${baseName}_${dataContextId}`);
+        expect((0, persistent_var_identity_1.persistentVarStorageName)(baseName, "groupUser", dataContextId)).toBe(`${baseName}_${dataContextId}`);
+    });
+    test("rejects invalid identity inputs", () => {
+        expect(() => (0, persistent_var_identity_1.packageScopedPersistentVarName)("not-an-id", "settings")).toThrow(/package ID/);
+        expect(() => (0, persistent_var_identity_1.packageScopedPersistentVarName)((0, utils_1.newid)(), " ")).toThrow(/non-empty/);
+        expect(() => (0, persistent_var_identity_1.persistentVarStorageName)("settings", "groupUser")).toThrow(/data context/);
+    });
+});

package/dist/data/tools.d.ts

@@ -250,7 +250,6 @@ export declare const toolSchema: z.ZodObject<{
         }[];
     };
     accessLevel: number;
-    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -266,6 +265,7 @@ export declare const toolSchema: z.ZodObject<{
     } | undefined;
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    packageId?: string | undefined;
 }, {
     name: string;
     toolId: string;
@@ -295,7 +295,6 @@ export declare const toolSchema: z.ZodObject<{
         }[] | undefined;
     };
     code?: string | undefined;
-    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -311,6 +310,7 @@ export declare const toolSchema: z.ZodObject<{
     } | undefined;
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    packageId?: string | undefined;
     accessLevel?: number | undefined;
 }>;
 /** A tool definition stored in the Tools table. */
@@ -357,7 +357,6 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
         }[];
     };
     accessLevel: number;
-    packageId?: string | undefined;
     detailedDescription?: string | undefined;
     configSchema?: {
         type: IOSchemaType;
@@ -373,4 +372,5 @@ export declare function Tools(dataContext?: DataContext): import("..").Table<{
     } | undefined;
     codeRepository?: string | undefined;
     isAssistantRunner?: boolean | undefined;
+    packageId?: string | undefined;
 }>;

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

@@ -19,9 +19,8 @@ const tools_2 = require("../tools");
 async function installContractPackage(dataContext, packageDefinition, opts) {
     const { packageId } = packageDefinition;
     const registry = opts?.registry;
-    // Register contracts in the in-memory registry
-    if (registry) {
-        for (const contract of packageDefinition.contracts) {
+    const registrations = registry
+        ? packageDefinition.contracts.map((contract) => {
             const key = `${contract.contractId}@${contract.version}`;
             const alsoImpl = packageDefinition.alsoImplements.get(key) ?? [];
             // If the contract is already frozen in the registry, re-register as
@@ -31,11 +30,14 @@ async function installContractPackage(dataContext, packageDefinition, opts) {
             if (existing && !existing.devTag && contract.devTag === "dev") {
                 effectiveContract = { ...contract, devTag: undefined };
             }
-            const result = registry.register(packageId, effectiveContract, alsoImpl);
-            if (!result.valid) {
-                console.error(`[ContractPackageLoader] Contract registration failed for ${contract.name}:`, result.errors);
-            }
-        }
+            return { definition: effectiveContract, alsoImplements: alsoImpl };
+        })
+        : undefined;
+    const validation = registrations ? registry?.validateBatch(packageId, registrations) : undefined;
+    if (validation && !validation.valid) {
+        throw new Error(`Atomic contract registration failed for package ${packageId}: ${validation.errors
+            .map((error) => error.message)
+            .join("; ")}`);
     }
     // Install tool instances with packageId
     for (const toolInstance of packageDefinition.toolInstances) {
@@ -55,6 +57,16 @@ async function installContractPackage(dataContext, packageDefinition, opts) {
         const assistantWithPackageId = { ...assistant, packageId };
         await Assistants(dataContext).save(assistantWithPackageId);
     }
+    // Activate the new provider only after all fallible package-owned persistence
+    // has succeeded, so a failed update leaves the previous provider routable.
+    if (registry && registrations) {
+        const result = registry.replaceBatch(packageId, registrations);
+        if (!result.valid) {
+            throw new Error(`Atomic contract registration failed for package ${packageId}: ${result.errors
+                .map((error) => error.message)
+                .join("; ")}`);
+        }
+    }
 }
 /**
  * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.

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

@@ -66,6 +66,22 @@ describe("installContractPackage registry wiring", () => {
         const dataContext = mockDataContext();
         await expect((0, contract_package_loader_1.installContractPackage)(dataContext, makeDefinition())).resolves.toBeUndefined();
     });
+    it("keeps the previous provider active when package persistence fails", async () => {
+        const registry = new registry_1.ContractRegistry();
+        const previous = makeDefinition();
+        previous.contracts[0] = { ...previous.contracts[0], name: "Previous Contract" };
+        await (0, contract_package_loader_1.installContractPackage)(mockDataContext(), previous, { registry });
+        const dataContext = mockDataContext();
+        dataContext.tableContainer.registerTableDefinition.mockImplementation(() => {
+            throw new Error("table registration failed");
+        });
+        const replacement = makeDefinition({
+            tableDefinitions: [{}],
+        });
+        await expect((0, contract_package_loader_1.installContractPackage)(dataContext, replacement, { registry })).rejects.toThrow(/table registration failed/);
+        expect(registry.resolve(contractId, 1)?.name).toBe("Previous Contract");
+        expect(registry.getProviderPackageId(contractId, 1)).toBe(packageId);
+    });
 });
 describe("extractPackageDefinition", () => {
     it("returns a package definition when packageId and contracts are present", () => {