@peers-app/peers-sdk 0.18.5 → 0.18.8

package/dist/data/index.d.ts

@@ -10,11 +10,12 @@ export * from "./group-members";
 export * from "./group-permissions";
 export * from "./group-share";
 export * from "./groups";
-export * from "./peer-types";
 export * from "./messages";
+export * from "./package-version-resolver";
 export * from "./package-versions";
 export * from "./packages";
 export * from "./packages.utils";
+export * from "./peer-types";
 export * from "./persistent-vars";
 export * from "./table-definitions-table";
 export * from "./tool-tests";

package/dist/data/index.js

@@ -26,11 +26,12 @@ __exportStar(require("./group-members"), exports);
 __exportStar(require("./group-permissions"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
-__exportStar(require("./peer-types"), exports);
 __exportStar(require("./messages"), exports);
+__exportStar(require("./package-version-resolver"), exports);
 __exportStar(require("./package-versions"), exports);
 __exportStar(require("./packages"), exports);
 __exportStar(require("./packages.utils"), exports);
+__exportStar(require("./peer-types"), exports);
 __exportStar(require("./persistent-vars"), exports);
 __exportStar(require("./table-definitions-table"), exports);
 __exportStar(require("./tool-tests"), exports);

package/dist/data/package-version-resolver.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Device-local package version resolver.
+ *
+ * Each device independently decides which package version to run based on a
+ * per-package `groupDeviceVar` containing the active PV ID and follow
+ * preferences. The shared `IPackage.activePackageVersionId` serves only as
+ * the group-level default for new devices.
+ */
+import type { DataContext } from "../context/data-context";
+import { type IPackageVersion } from "./package-versions";
+import type { IPackage } from "./packages";
+import { type PersistentVar } from "./persistent-vars";
+/**
+ * Device-local preferences for a single package. Stored in a `groupDeviceVar`
+ * keyed by `packagePrefs_${packageId}`. When undefined or empty, the device
+ * falls back to the shared `IPackage` fields (zero-migration backward compat).
+ */
+export interface IDevicePackagePrefs {
+    /** Which PV this device currently runs */
+    activePackageVersionId?: string;
+    /** If true, never auto-update this package */
+    pinned?: boolean;
+    /** Auto-update range: patch | minor | latest */
+    followRange?: "patch" | "minor" | "latest";
+    /** Tag policy: "stable" | "stable,beta" | "*" */
+    followTags?: string;
+}
+/**
+ * Reactive, cached observable holding device-local preferences for a single
+ * package. Backed by a `groupDeviceVar` so the UI can subscribe via
+ * `useObservable` and get automatic updates when prefs change (including
+ * cross-process DB writes and group context switches).
+ *
+ * DB record name: `packagePrefs_${packageId}_${dataContextId}` -- identical to
+ * the previous manual naming convention, so existing records load without
+ * migration.
+ *
+ * @param dataContext - Pinned data context for server-side callers. When
+ *   omitted the var tracks the user's default group context.
+ */
+export declare function packagePrefsVar(packageId: string, dataContext?: DataContext): PersistentVar<IDevicePackagePrefs>;
+/**
+ * Merge partial updates into device-local package preferences. Preserves
+ * existing fields that are not overridden.
+ *
+ * Guard: when the device is already pinned, callers cannot silently overwrite
+ * `activePackageVersionId`. Include `pinned` in the same update to signal
+ * intent (e.g. unpinning + activating in one step).
+ *
+ * @param dataContext - Pinned data context for server-side callers. When
+ *   omitted the var tracks the user's default group context.
+ */
+export declare function updatePackagePrefs(packageId: string, prefs: Partial<IDevicePackagePrefs>, dataContext?: DataContext): Promise<void>;
+/**
+ * Effective device-local preferences for a package after merging the device's
+ * raw prefs with the group-level `IPackage` defaults. Every field is resolved
+ * -- no `undefined` means "use the IPackage field" ambiguity remains.
+ */
+export interface IEffectivePackagePrefs {
+    activePackageVersionId: string | undefined;
+    isPinned: boolean;
+    followRange: "patch" | "minor" | "latest";
+    followTags: string | undefined;
+}
+/**
+ * Pure function: merge raw device prefs with the group-level `IPackage`
+ * defaults to produce fully-resolved effective preferences. Used by the
+ * resolver and by UI components that need to reflect device behavior.
+ */
+export declare function getEffectivePackagePrefs(pkg: IPackage, devicePrefs: IDevicePackagePrefs | undefined): IEffectivePackagePrefs;
+export interface IResolveResult {
+    /** Whether a package was successfully loaded */
+    loaded: boolean;
+    /** The PV that was resolved (may be the current one if no upgrade found) */
+    pv?: IPackageVersion;
+    /** Whether the active PV changed */
+    upgraded: boolean;
+}
+/**
+ * Core resolver: evaluates available package versions against the device's
+ * follow policy and loads the best one. Never auto-activates dev versions
+ * unless the device explicitly follows "dev".
+ *
+ * Callers:
+ * - `PackagesTrackedDataSource.applyChanges` (on sync)
+ * - `PackageLoader.loadAllPackages` (startup)
+ * - `package-installer.ts` (after saving new bundles)
+ */
+export declare function resolveDevicePackageVersion(pkg: IPackage, dataContext: DataContext, opts?: {
+    force?: boolean;
+    localPath?: string;
+}): Promise<IResolveResult>;

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

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Device-local package version resolver.
+ *
+ * Each device independently decides which package version to run based on a
+ * per-package `groupDeviceVar` containing the active PV ID and follow
+ * preferences. The shared `IPackage.activePackageVersionId` serves only as
+ * the group-level default for new devices.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packagePrefsVar = packagePrefsVar;
+exports.updatePackagePrefs = updatePackagePrefs;
+exports.getEffectivePackagePrefs = getEffectivePackagePrefs;
+exports.resolveDevicePackageVersion = resolveDevicePackageVersion;
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const assistants_1 = require("./assistants");
+const package_versions_1 = require("./package-versions");
+const persistent_vars_1 = require("./persistent-vars");
+const workflows_1 = require("./workflows");
+/**
+ * Reactive, cached observable holding device-local preferences for a single
+ * package. Backed by a `groupDeviceVar` so the UI can subscribe via
+ * `useObservable` and get automatic updates when prefs change (including
+ * cross-process DB writes and group context switches).
+ *
+ * DB record name: `packagePrefs_${packageId}_${dataContextId}` -- identical to
+ * the previous manual naming convention, so existing records load without
+ * migration.
+ *
+ * @param dataContext - Pinned data context for server-side callers. When
+ *   omitted the var tracks the user's default group context.
+ */
+function packagePrefsVar(packageId, dataContext) {
+    return (0, persistent_vars_1.groupDeviceVar)(`packagePrefs_${packageId}`, {
+        defaultValue: {},
+        dataContext,
+    });
+}
+/**
+ * Merge partial updates into device-local package preferences. Preserves
+ * existing fields that are not overridden.
+ *
+ * Guard: when the device is already pinned, callers cannot silently overwrite
+ * `activePackageVersionId`. Include `pinned` in the same update to signal
+ * intent (e.g. unpinning + activating in one step).
+ *
+ * @param dataContext - Pinned data context for server-side callers. When
+ *   omitted the var tracks the user's default group context.
+ */
+async function updatePackagePrefs(packageId, prefs, dataContext) {
+    const pvar = packagePrefsVar(packageId, dataContext);
+    await pvar.loadingPromise;
+    const existing = pvar() ?? {};
+    let effectivePrefs = prefs;
+    if (existing.pinned && !("pinned" in prefs) && "activePackageVersionId" in prefs) {
+        const { activePackageVersionId: _, ...rest } = prefs;
+        effectivePrefs = rest;
+    }
+    pvar({ ...existing, ...effectivePrefs });
+}
+/**
+ * Pure function: merge raw device prefs with the group-level `IPackage`
+ * defaults to produce fully-resolved effective preferences. Used by the
+ * resolver and by UI components that need to reflect device behavior.
+ */
+function getEffectivePackagePrefs(pkg, devicePrefs) {
+    const hasDevicePrefs = devicePrefs != null && Object.keys(devicePrefs).length > 0;
+    return {
+        activePackageVersionId: devicePrefs?.activePackageVersionId ?? pkg.activePackageVersionId,
+        isPinned: !!devicePrefs?.pinned || (!hasDevicePrefs && pkg.versionFollowRange === "pinned"),
+        followRange: devicePrefs?.followRange ?? rangeFromPkg(pkg),
+        followTags: devicePrefs?.followTags ?? pkg.followVersionTags,
+    };
+}
+/**
+ * Core resolver: evaluates available package versions against the device's
+ * follow policy and loads the best one. Never auto-activates dev versions
+ * unless the device explicitly follows "dev".
+ *
+ * Callers:
+ * - `PackagesTrackedDataSource.applyChanges` (on sync)
+ * - `PackageLoader.loadAllPackages` (startup)
+ * - `package-installer.ts` (after saving new bundles)
+ */
+async function resolveDevicePackageVersion(pkg, dataContext, opts) {
+    const pvar = packagePrefsVar(pkg.packageId, dataContext);
+    await pvar.loadingPromise;
+    // Migrate legacy per-group deviceVersionTag pvar into per-package followTags.
+    // The old system stored a single tag preference per group; the new system is
+    // per-package.  We copy the value on first resolution so future calls skip
+    // this path (the legacy pvar stays around harmlessly for other packages that
+    // haven't resolved yet).
+    let rawPrefs = pvar() ?? {};
+    if (!rawPrefs.followTags) {
+        const legacyVarName = `deviceVersionTag_${dataContext.dataContextId}`;
+        const userCtx = await (0, user_context_singleton_1.getUserContext)();
+        const legacyRec = await (0, persistent_vars_1.PersistentVars)(userCtx.userDataContext).findOne({
+            name: legacyVarName,
+        });
+        const legacyTag = legacyRec?.value?.value;
+        if (legacyTag) {
+            await updatePackagePrefs(pkg.packageId, { followTags: legacyTag }, dataContext);
+            rawPrefs = pvar() ?? {};
+        }
+    }
+    const { activePackageVersionId: effectiveActivePvId, isPinned, followRange, followTags, } = getEffectivePackagePrefs(pkg, rawPrefs);
+    if (!effectiveActivePvId) {
+        return { loaded: false, upgraded: false };
+    }
+    // If the device (or the group-level default) has pinned this package, just load
+    // the current version — never auto-upgrade.
+    if (isPinned) {
+        const pv = await (0, package_versions_1.PackageVersions)(dataContext)
+            .get(effectiveActivePvId)
+            .catch(() => undefined);
+        if (!pv)
+            return { loaded: false, pv: undefined, upgraded: false };
+        const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            force: opts?.force,
+            localPath: opts?.localPath,
+            packageVersionId: effectiveActivePvId,
+        });
+        return { loaded: !!instance, pv, upgraded: false };
+    }
+    // Load the currently active PV for comparison
+    let activePv;
+    if (effectiveActivePvId) {
+        activePv = await (0, package_versions_1.PackageVersions)(dataContext)
+            .get(effectiveActivePvId)
+            .catch(() => undefined);
+    }
+    // Evaluate all available PVs to find the best one
+    const allVersions = await (0, package_versions_1.PackageVersions)(dataContext).list({ packageId: pkg.packageId });
+    let bestPv = activePv;
+    for (const candidate of allVersions) {
+        if (candidate.packageVersionId === effectiveActivePvId)
+            continue;
+        const tagOk = (0, package_versions_1.doesTagMatch)(activePv?.versionTag, candidate.versionTag, followTags, undefined);
+        if (!tagOk)
+            continue;
+        const activeVersion = bestPv?.version ?? "0.0.0";
+        const inRange = (0, package_versions_1.isVersionInRange)(activeVersion, candidate.version, followRange);
+        if (!inRange)
+            continue;
+        const newer = (0, package_versions_1.isNewerVersion)(activeVersion, candidate.version);
+        if (!newer)
+            continue;
+        bestPv = candidate;
+    }
+    // If the best candidate is the same as what we already have, just load it
+    if (!bestPv || bestPv.packageVersionId === effectiveActivePvId) {
+        if (activePv) {
+            const instance = await dataContext.packageLoader.loadPackage(pkg, {
+                force: opts?.force,
+                localPath: opts?.localPath,
+                packageVersionId: effectiveActivePvId,
+            });
+            return { loaded: !!instance, pv: activePv, upgraded: false };
+        }
+        return { loaded: false, upgraded: false };
+    }
+    // A better PV was found - attempt to load it (getFileContents will
+    // auto-download missing chunks from peers)
+    const instance = await dataContext.packageLoader.loadPackage(pkg, {
+        force: true,
+        localPath: opts?.localPath,
+        packageVersionId: bestPv.packageVersionId,
+    });
+    if (!instance) {
+        // Bundle unavailable even after download attempt - keep current version
+        if (activePv) {
+            const fallbackInstance = await dataContext.packageLoader.loadPackage(pkg, {
+                force: opts?.force,
+                localPath: opts?.localPath,
+                packageVersionId: effectiveActivePvId,
+            });
+            return { loaded: !!fallbackInstance, pv: activePv, upgraded: false };
+        }
+        return { loaded: false, upgraded: false };
+    }
+    // Load succeeded - install assistants/workflows, then update device prefs
+    await installPackageContents(dataContext, pkg, instance);
+    await updatePackagePrefs(pkg.packageId, { activePackageVersionId: bestPv.packageVersionId }, dataContext);
+    return { loaded: true, pv: bestPv, upgraded: true };
+}
+/**
+ * Save a loaded package's assistants and workflows into the data context.
+ * Contract-installed packages are skipped because their content is already
+ * managed by the contract loader.
+ */
+async function installPackageContents(dataContext, pkg, instance) {
+    if (dataContext.packageLoader.isContractInstalled(pkg.packageId))
+        return;
+    const saves = [
+        ...(instance.assistants?.map((a) => (0, assistants_1.Assistants)(dataContext).save(a)) ?? []),
+        ...(instance.workflows?.map((w) => (0, workflows_1.Workflows)(dataContext).save(w)) ?? []),
+    ];
+    await Promise.all(saves);
+}
+/** Convert `IPackage.versionFollowRange` to the resolver's range type. */
+function rangeFromPkg(pkg) {
+    const r = pkg.versionFollowRange;
+    if (r === "pinned")
+        return "latest"; // unreachable — isPinned check returns early
+    if (r === "patch" || r === "minor")
+        return r;
+    return "latest";
+}

package/dist/data/package-version-resolver.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Regression tests for device-local package version resolution.
+ *
+ * Several cases document known gaps from the device-local package versions review.
+ * They are expected to fail until the resolver honors group-level pinned, legacy
+ * deviceVersionTag, and pinned devices are not overridden before resolve.
+ */
+export {};

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

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * Regression tests for device-local package version resolution.
+ *
+ * Several cases document known gaps from the device-local package versions review.
+ * They are expected to fail until the resolver honors group-level pinned, legacy
+ * deviceVersionTag, and pinned devices are not overridden before resolve.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const user_context_1 = require("../context/user-context");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const utils_1 = require("../utils");
+const assistants_1 = require("./assistants");
+const sql_data_source_1 = require("./orm/sql.data-source");
+const package_version_resolver_1 = require("./package-version-resolver");
+const package_versions_1 = require("./package-versions");
+const packages_1 = require("./packages");
+const persistent_vars_1 = require("./persistent-vars");
+const workflows_1 = require("./workflows");
+class DBHarness {
+    _db = null;
+    get db() {
+        if (!this._db) {
+            this._db = new SQLiteDB(":memory:");
+            this._db.pragma("journal_mode = WAL");
+        }
+        return this._db;
+    }
+    async get(sql, params = []) {
+        return this.db.prepare(sql).get(params);
+    }
+    async all(sql, params = []) {
+        return this.db.prepare(sql).all(params);
+    }
+    async exec(sql, params = []) {
+        const result = this.db.prepare(sql).run(params);
+        return { changes: result.changes };
+    }
+    async close() {
+        this._db?.close();
+        this._db = null;
+    }
+}
+const testUserId = (0, utils_1.newid)();
+const testGroupId = (0, utils_1.newid)();
+let userContext;
+let db;
+function groupDc() {
+    const dc = userContext.getDataContext(testGroupId);
+    dc.setAsDefault();
+    return dc;
+}
+function makePV(packageId, overrides = {}) {
+    return {
+        packageVersionId: (0, utils_1.newid)(),
+        packageId,
+        version: "1.0.0",
+        versionTag: "stable",
+        packageVersionHash: "hash",
+        packageBundleFileId: (0, utils_1.newid)(),
+        packageBundleFileHash: "bundlehash",
+        signature: "",
+        createdBy: testUserId,
+        createdAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+function makePkg(overrides = {}) {
+    return {
+        packageId: (0, utils_1.newid)(),
+        name: "test-package",
+        description: "test",
+        createdBy: testUserId,
+        signature: "",
+        ...overrides,
+    };
+}
+beforeAll(async () => {
+    db = new DBHarness();
+    const dataSourceFactory = (metaData, schema) => new sql_data_source_1.SQLDataSource(db, metaData, schema);
+    userContext = new user_context_1.UserContext(testUserId, dataSourceFactory, true);
+    await userContext.loadingPromise;
+    userContext.deviceId((0, utils_1.newid)());
+    (0, user_context_singleton_1.setUserContext)(userContext);
+    packages_1.PackagesTable.isPassthrough = true;
+    package_versions_1.PackageVersionsTable.isPassthrough = true;
+});
+afterAll(async () => {
+    packages_1.PackagesTable.isPassthrough = false;
+    package_versions_1.PackageVersionsTable.isPassthrough = false;
+    userContext?.dispose();
+    await db?.close();
+});
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+describe("resolveDevicePackageVersion — known gaps (expected to fail until fixed)", () => {
+    it("does not auto-upgrade when IPackage.versionFollowRange is pinned (no device prefs)", async () => {
+        const dc = groupDc();
+        const packageId = (0, utils_1.newid)();
+        const stableV1 = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const stableV2 = makePV(packageId, { version: "2.0.0", versionTag: "stable" });
+        await (0, package_versions_1.PackageVersions)(dc).save(stableV1);
+        await (0, package_versions_1.PackageVersions)(dc).save(stableV2);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stableV1.packageVersionId,
+            versionFollowRange: "pinned",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        const loadedPvIds = [];
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId)
+                loadedPvIds.push(opts.packageVersionId);
+            return { packageId };
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.upgraded).toBe(false);
+        expect(loadedPvIds).toContain(stableV1.packageVersionId);
+        expect(loadedPvIds).not.toContain(stableV2.packageVersionId);
+    });
+    it("pinned device keeps stable PV after activePackageVersionId is overwritten to dev (updatePackageBundle sequence)", async () => {
+        const dc = groupDc();
+        const packageId = (0, utils_1.newid)();
+        const stablePv = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const devPv = makePV(packageId, { version: "1.0.1", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(stablePv);
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { pinned: true, activePackageVersionId: stablePv.packageVersionId }, dc);
+        // Mirrors updatePackageBundle: unconditionally merges dev active id before resolve
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { activePackageVersionId: devPv.packageVersionId }, dc);
+        const loadedPvIds = [];
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId)
+                loadedPvIds.push(opts.packageVersionId);
+            return { packageId };
+        });
+        await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(loadedPvIds[loadedPvIds.length - 1]).toBe(stablePv.packageVersionId);
+    });
+    it("honors legacy deviceVersionTag pvar when choosing beta auto-upgrade", async () => {
+        const dc = groupDc();
+        const packageId = (0, utils_1.newid)();
+        const stablePv = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const betaPv = makePV(packageId, { version: "2.0.0", versionTag: "beta" });
+        await (0, package_versions_1.PackageVersions)(dc).save(stablePv);
+        await (0, package_versions_1.PackageVersions)(dc).save(betaPv);
+        const legacyVarName = `deviceVersionTag_${dc.dataContextId}`;
+        await (0, persistent_vars_1.PersistentVars)(userContext.userDataContext).save({
+            persistentVarId: (0, utils_1.deterministicPvarId)(legacyVarName),
+            name: legacyVarName,
+            scope: "groupDevice",
+            value: { value: "beta" },
+        });
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+            versionFollowRange: "latest",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        const loadedPvIds = [];
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId)
+                loadedPvIds.push(opts.packageVersionId);
+            return { packageId };
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.upgraded).toBe(true);
+        expect(loadedPvIds).toContain(betaPv.packageVersionId);
+    });
+});
+describe("resolveDevicePackageVersion — expected behavior (control)", () => {
+    it("does not auto-activate dev when device has no prefs and group default is stable", async () => {
+        const dc = groupDc();
+        const packageId = (0, utils_1.newid)();
+        const stablePv = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const devPv = makePV(packageId, { version: "9.9.9", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(stablePv);
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+            versionFollowRange: "latest",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        const pvar = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await pvar.loadingPromise;
+        expect(pvar()).toEqual({});
+        const loadedPvIds = [];
+        jest.spyOn(dc.packageLoader, "loadPackage").mockImplementation(async (_pkg, opts) => {
+            if (opts?.packageVersionId)
+                loadedPvIds.push(opts.packageVersionId);
+            return { packageId };
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.upgraded).toBe(false);
+        expect(loadedPvIds).toContain(stablePv.packageVersionId);
+        expect(loadedPvIds).not.toContain(devPv.packageVersionId);
+    });
+    it("installs assistants and workflows into the data context on auto-upgrade", async () => {
+        const dc = groupDc();
+        const packageId = (0, utils_1.newid)();
+        const stablePv = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const stableV2 = makePV(packageId, { version: "2.0.0", versionTag: "stable" });
+        await (0, package_versions_1.PackageVersions)(dc).save(stablePv);
+        await (0, package_versions_1.PackageVersions)(dc).save(stableV2);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+            versionFollowRange: "latest",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        // Explicitly set followTags so the legacy-pvar migration from earlier tests
+        // doesn't interfere (it would write "beta" followTags otherwise).
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { followTags: "stable" }, dc);
+        const testAssistantId = (0, utils_1.newid)();
+        const testWorkflowId = (0, utils_1.newid)();
+        const testAssistant = {
+            assistantId: testAssistantId,
+            name: "Upgrade Test Assistant",
+            packageId,
+            createdAt: new Date(),
+            assistantRunnerToolId: "000peers0tool00000runner1",
+            assistantRunnerConfig: {},
+            toolsToInclude: "",
+            toolInclusionStrategy: "Linked",
+        };
+        const testWorkflow = {
+            workflowId: testWorkflowId,
+            name: "Upgrade Test Workflow",
+            description: "test",
+            defaultAssistantId: testAssistantId,
+            createdBy: testUserId,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            instructions: [],
+            packageId,
+        };
+        jest.spyOn(dc.packageLoader, "loadPackage").mockResolvedValue({
+            packageId,
+            assistants: [testAssistant],
+            workflows: [testWorkflow],
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.upgraded).toBe(true);
+        expect(result.pv?.packageVersionId).toBe(stableV2.packageVersionId);
+        const savedAssistant = await (0, assistants_1.Assistants)(dc).get(testAssistantId);
+        expect(savedAssistant).toBeDefined();
+        expect(savedAssistant?.name).toBe("Upgrade Test Assistant");
+        const savedWorkflow = await (0, workflows_1.Workflows)(dc).get(testWorkflowId);
+        expect(savedWorkflow).toBeDefined();
+        expect(savedWorkflow?.name).toBe("Upgrade Test Workflow");
+    });
+});
+describe("getEffectivePackagePrefs", () => {
+    it("uses group defaults when device prefs are absent", () => {
+        const pkg = makePkg({
+            activePackageVersionId: "pv-group",
+            followVersionTags: "stable,beta",
+            versionFollowRange: "minor",
+        });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, undefined)).toEqual({
+            activePackageVersionId: "pv-group",
+            isPinned: false,
+            followRange: "minor",
+            followTags: "stable,beta",
+        });
+    });
+    it("honors group-level pinned when there are no device prefs", () => {
+        const pkg = makePkg({
+            activePackageVersionId: "pv-pin",
+            versionFollowRange: "pinned",
+        });
+        const eff = (0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, undefined);
+        expect(eff.isPinned).toBe(true);
+        expect(eff.activePackageVersionId).toBe("pv-pin");
+    });
+    it("prefers device active id over group default", () => {
+        const pkg = makePkg({ activePackageVersionId: "pv-group" });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, {
+            activePackageVersionId: "pv-device",
+        })).toMatchObject({
+            activePackageVersionId: "pv-device",
+            isPinned: false,
+        });
+    });
+    it("device pinned overrides group not pinned", () => {
+        const pkg = makePkg({
+            activePackageVersionId: "pv1",
+            versionFollowRange: "latest",
+        });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, { pinned: true }).isPinned).toBe(true);
+    });
+    it("empty device prefs falls back to group pinned (matches groupDeviceVar default)", () => {
+        const pkg = makePkg({
+            activePackageVersionId: "pv1",
+            versionFollowRange: "pinned",
+        });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, {}).isPinned).toBe(true);
+    });
+    it("device explicitly unpinned overrides group pinned", () => {
+        const pkg = makePkg({
+            activePackageVersionId: "pv1",
+            versionFollowRange: "pinned",
+        });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, { pinned: false }).isPinned).toBe(false);
+    });
+    it("device followRange overrides group default", () => {
+        const pkg = makePkg({ versionFollowRange: "latest" });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, { followRange: "patch" }).followRange).toBe("patch");
+    });
+    it("device followTags overrides group default", () => {
+        const pkg = makePkg({ followVersionTags: "stable" });
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, { followTags: "*" }).followTags).toBe("*");
+    });
+    it("falls back to 'latest' followRange when group has no setting", () => {
+        const pkg = makePkg({});
+        expect((0, package_version_resolver_1.getEffectivePackagePrefs)(pkg, undefined).followRange).toBe("latest");
+    });
+});
+describe("packagePrefsVar", () => {
+    it("returns the same observable instance for repeated calls with the same args", () => {
+        const dc = groupDc();
+        const id = (0, utils_1.newid)();
+        const a = (0, package_version_resolver_1.packagePrefsVar)(id, dc);
+        const b = (0, package_version_resolver_1.packagePrefsVar)(id, dc);
+        expect(a).toBe(b);
+    });
+});

package/dist/data/package-versions.d.ts

@@ -53,12 +53,12 @@ declare const schema: z.ZodObject<{
     version: string;
     signature: string;
     packageId: string;
+    createdBy: string;
+    createdAt: string;
     packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;
     packageBundleFileHash: string;
-    createdBy: string;
-    createdAt: string;
     history?: {
         at: string;
         action: string;
@@ -80,12 +80,12 @@ declare const schema: z.ZodObject<{
     version: string;
     signature: string;
     packageId: string;
+    createdBy: string;
+    createdAt: string;
     packageVersionId: string;
     packageVersionHash: string;
     packageBundleFileId: string;
     packageBundleFileHash: string;
-    createdBy: string;
-    createdAt: string;
     history?: {
         at: string;
         action: string;
@@ -120,10 +120,17 @@ export declare function PackageVersions(dataContext?: DataContext): PackageVersi
  * content only — `versionTag` is intentionally excluded so the same code
  * produces the same hash regardless of its promotion level (dev/beta/stable).
  *
- * @deprecated The `versionTag` parameter is accepted for backward compatibility
- * but ignored. It will be removed in a future release.
+ * @param version - Semver version string.
+ * @param _versionTag - **Deprecated.** Accepted for backward compatibility
+ *   but ignored. Will be removed in a future release.
+ * @param packageBundleFileHash - Hash of the main package bundle.
+ * @param routesBundleFileHash - Hash of the routes bundle, if any.
+ * @param uiBundleFileHash - Hash of the UI bundle, if any.
+ * @returns A content-addressable hash string.
  */
-export declare function computePackageVersionHash(version: string, _versionTag: string, packageBundleFileHash: string, routesBundleFileHash?: string, uiBundleFileHash?: string): string;
+export declare function computePackageVersionHash(version: string, 
+/** @deprecated Ignored — will be removed in a future release. */
+_versionTag: string, packageBundleFileHash: string, routesBundleFileHash?: string, uiBundleFileHash?: string): string;
 export declare function isVersionInRange(activeVersion: string, incomingVersion: string, range: "pinned" | "patch" | "minor" | "latest"): boolean;
 /**
  * Returns true if incomingVersion is strictly newer than activeVersion (semver comparison).

package/dist/data/package-versions.js

@@ -143,10 +143,17 @@ function PackageVersions(dataContext) {
  * content only — `versionTag` is intentionally excluded so the same code
  * produces the same hash regardless of its promotion level (dev/beta/stable).
  *
- * @deprecated The `versionTag` parameter is accepted for backward compatibility
- * but ignored. It will be removed in a future release.
+ * @param version - Semver version string.
+ * @param _versionTag - **Deprecated.** Accepted for backward compatibility
+ *   but ignored. Will be removed in a future release.
+ * @param packageBundleFileHash - Hash of the main package bundle.
+ * @param routesBundleFileHash - Hash of the routes bundle, if any.
+ * @param uiBundleFileHash - Hash of the UI bundle, if any.
+ * @returns A content-addressable hash string.
  */
-function computePackageVersionHash(version, _versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) {
+function computePackageVersionHash(version, 
+/** @deprecated Ignored — will be removed in a future release. */
+_versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) {
     return (0, keys_1.hashValue)([version, packageBundleFileHash, routesBundleFileHash ?? "", uiBundleFileHash ?? ""].join(":"));
 }
 function isVersionInRange(activeVersion, incomingVersion, range) {

package/dist/data/packages.d.ts

@@ -9,6 +9,7 @@ declare const schema: z.ZodObject<{
     createdBy: z.ZodEffects<z.ZodString, string, string>;
     disabled: z.ZodOptional<z.ZodBoolean>;
     remoteRepo: z.ZodOptional<z.ZodString>;
+    /** @deprecated Read appNavs from the active IPackageVersion record instead. */
     appNavs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         displayName: z.ZodOptional<z.ZodString>;

package/dist/data/packages.js

@@ -56,10 +56,11 @@ const schema = zod_1.z.object({
         .optional()
         .describe("Whether the package's components should be loaded and included in the app runtime"),
     remoteRepo: zod_1.z.string().optional().describe("The remote repository where the package is stored"),
+    /** @deprecated Read appNavs from the active IPackageVersion record instead. */
     appNavs: app_nav_1.appNavSchema
         .array()
         .optional()
-        .describe("The app navigation items that this package provides"),
+        .describe("DEPRECATED: Read appNavs from the active IPackageVersion record instead"),
     activePackageVersionId: zod_types_1.zodPeerId
         .optional()
         .describe("FK to PackageVersions — the currently active version"),

package/dist/data/workflow-runs.d.ts

@@ -32,7 +32,6 @@ export declare const workflowRunSchema: z.ZodObject<{
     parentWorkflowRunId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     defaultAssistantId: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    createdAt: Date;
     defaultAssistantId: string;
     instructions: {
         markdown?: string | undefined;
@@ -40,6 +39,7 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[];
+    createdAt: Date;
     workflowRunId: string;
     parentMessageId: string;
     currentInstructionIndex: number;
@@ -57,7 +57,6 @@ export declare const workflowRunSchema: z.ZodObject<{
     defaultAssistantId: string;
     workflowRunId: string;
     parentMessageId: string;
-    createdAt?: Date | undefined;
     workflowId?: string | undefined;
     instructions?: {
         markdown?: string | undefined;
@@ -65,6 +64,7 @@ export declare const workflowRunSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[] | undefined;
+    createdAt?: Date | undefined;
     scheduleDT?: Date | undefined;
     currentInstructionIndex?: number | undefined;
     instructionResults?: any[] | undefined;

package/dist/data/workflows.d.ts

@@ -2,8 +2,6 @@ import type { DataContext } from "../context/data-context";
 export declare function Workflows(dataContext?: DataContext): import("./orm").Table<{
     name: string;
     description: string;
-    createdBy: string;
-    createdAt: Date;
     workflowId: string;
     defaultAssistantId: string;
     instructions: {
@@ -12,6 +10,8 @@ export declare function Workflows(dataContext?: DataContext): import("./orm").Ta
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[];
+    createdBy: string;
+    createdAt: Date;
     updatedAt: Date;
     packageId?: string | undefined;
 }>;

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

@@ -18,6 +18,7 @@ export declare class PackageLoader {
     loadPackage(pkg: IPackage, opts?: {
         force?: boolean;
         localPath?: string;
+        packageVersionId?: string;
     }): Promise<IPeersPackage | undefined>;
     private _readLocalBundle;
     /**

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageLoader = void 0;
 exports.setDefaultRequire = setDefaultRequire;
 const files_1 = require("../data/files");
+const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
 const tools_1 = require("../data/tools");
@@ -25,7 +26,9 @@ class PackageLoader {
     }
     async loadAllPackages(opts) {
         const packages = await (0, packages_1.Packages)(this.dataContext).list();
-        await Promise.all(packages.filter((pkg) => !pkg.disabled).map((pkg) => this.loadPackage(pkg, opts)));
+        await Promise.all(packages
+            .filter((pkg) => !pkg.disabled)
+            .map((pkg) => (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, this.dataContext, opts)));
     }
     async loadPackage(pkg, opts) {
         if (this.packageInstances[pkg.packageId] && !opts?.force) {
@@ -35,9 +38,10 @@ class PackageLoader {
         try {
             let bundleCode = "";
             let bundleFileId;
-            if (pkg.activePackageVersionId) {
+            const pvId = opts?.packageVersionId ?? pkg.activePackageVersionId;
+            if (pvId) {
                 try {
-                    const pv = await (0, package_versions_1.PackageVersions)(this.dataContext).get(pkg.activePackageVersionId);
+                    const pv = await (0, package_versions_1.PackageVersions)(this.dataContext).get(pvId);
                     if (pv) {
                         bundleFileId = pv.packageBundleFileId;
                     }
@@ -110,12 +114,17 @@ class PackageLoader {
         if (!def.version)
             return;
         const pvTable = (0, package_versions_1.PackageVersions)(this.dataContext);
-        pvTable.get(pkg.activePackageVersionId).then((pv) => {
+        pvTable
+            .get(pkg.activePackageVersionId)
+            .then((pv) => {
             if (!pv)
                 return;
             if (def.version && pv.version !== def.version) {
-                pvTable.save({ ...pv, version: def.version });
+                return pvTable.signAndSave({ ...pv, version: def.version });
             }
+        })
+            .catch((err) => {
+            console.warn(`[PackageLoader] Failed to correct version for ${pkg.name}:`, err.message);
         });
     }
     async _evaluateBundle(pkg, bundleCode) {

package/dist/types/workflow.d.ts

@@ -44,8 +44,6 @@ export declare const workflowSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
-    createdBy: string;
-    createdAt: Date;
     workflowId: string;
     defaultAssistantId: string;
     instructions: {
@@ -54,22 +52,24 @@ export declare const workflowSchema: z.ZodObject<{
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[];
+    createdBy: string;
+    createdAt: Date;
     updatedAt: Date;
     packageId?: string | undefined;
 }, {
     name: string;
     description: string;
-    createdBy: string;
     workflowId: string;
     defaultAssistantId: string;
+    createdBy: string;
     packageId?: string | undefined;
-    createdAt?: Date | undefined;
     instructions?: {
         markdown?: string | undefined;
         onError?: string | undefined;
         directCallToolId?: string | undefined;
         subWorkflowId?: string | undefined;
     }[] | undefined;
+    createdAt?: Date | undefined;
     updatedAt?: Date | undefined;
 }>;
 export type IWorkflow = z.infer<typeof workflowSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.18.5",
+  "version": "0.18.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"