@peers-app/peers-sdk 0.26.4 → 0.26.6

package/dist/contracts/system/packages-contract.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGES_CONTRACT_VERSION = void 0;
+exports.packageVersionPromotionTargets = packageVersionPromotionTargets;
+exports.isPackageRepositoryUrl = isPackageRepositoryUrl;
+exports.getPackagesContractDefinition = getPackagesContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the built-in System Packages contract. */
+exports.PACKAGES_CONTRACT_VERSION = 1;
+/**
+ * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
+ * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
+ * matching the Versions screen. Promotion never demotes.
+ *
+ * @param versionTag - The version's current tag.
+ */
+function packageVersionPromotionTargets(versionTag) {
+    switch (versionTag || "dev") {
+        case "dev":
+            return ["beta", "stable"];
+        case "beta":
+            return ["stable"];
+        default:
+            return [];
+    }
+}
+/**
+ * Whether user input names a remote repository for `clonePackage` (`http(s)://` or
+ * `git@host:`) rather than a local folder or package name. The host still validates the
+ * URL; this only routes input in the CLI and UI the same way.
+ *
+ * @param target - Input as typed.
+ */
+function isPackageRepositoryUrl(target) {
+    return /^(https?:\/\/|git@[^:/\s]+:)/.test(target.trim());
+}
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const packageIdField = field("packageId", field_type_1.FieldType.id, "Package id.");
+const operationResultFields = [
+    packageIdField,
+    field("created", field_type_1.FieldType.boolean, "True when a new package was scaffolded.", {
+        optional: true,
+    }),
+    field("warning", field_type_1.FieldType.string, "Non-fatal problem to show the caller.", { optional: true }),
+    field("package", field_type_1.FieldType.object, "The package after the operation."),
+];
+let definition;
+/**
+ * Return the System Packages contract shape.
+ *
+ * Tools carry no `remoteAccessLevel`, so only callers this device trusts as `Self` (the
+ * user's own devices and users explicitly granted Self) can reach them remotely; group
+ * members, Admins included, are refused. Package code and workflows are refused
+ * everywhere. The provider binds every call to the route's
+ * data context; a package's group is the data boundary. Tools the host cannot perform
+ * throw `System Packages <tool> is not supported on this host (...)`; `getCapabilities`
+ * reports support up front.
+ */
+function getPackagesContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.packagesContractId,
+        version: exports.PACKAGES_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Packages",
+        description: "Install, inspect, reload, activate, and uninstall packages, with each device's observed runtime state.",
+        tables: [],
+        tools: [
+            {
+                name: "getCapabilities",
+                usageDescription: "Report which package operations this host supports.",
+                inputFields: [],
+                outputFields: [field("capabilities", field_type_1.FieldType.object, "Supported operations.")],
+            },
+            {
+                name: "listPackages",
+                usageDescription: "List packages in this data context with their requested version and runtime state on this device.",
+                inputFields: [],
+                outputFields: [
+                    field("packages", field_type_1.FieldType.object, "Package summaries.", { isArray: true }),
+                ],
+            },
+            {
+                name: "getPackage",
+                usageDescription: "Return one package with its versions, local folder, and runtime state.",
+                inputFields: [packageIdField],
+                outputFields: [field("package", field_type_1.FieldType.object, "Package details.")],
+            },
+            {
+                name: "importPackage",
+                usageDescription: "Import an existing package folder on this device and load it.",
+                inputFields: [
+                    field("path", field_type_1.FieldType.string, "Absolute or ~-prefixed folder path on the host."),
+                    field("name", field_type_1.FieldType.string, "Display name; defaults to package.json.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "createPackage",
+                usageDescription: "Scaffold a new package from the template, or import the folder when it already exists.",
+                inputFields: [
+                    field("name", field_type_1.FieldType.string, "Package display name."),
+                    field("location", field_type_1.FieldType.string, "Folder; defaults to the packages directory.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "clonePackage",
+                usageDescription: "Clone a package repository, build it, and import it.",
+                inputFields: [field("url", field_type_1.FieldType.string, "Git repository URL.")],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "installPackage",
+                usageDescription: "Re-enable a disabled package, or copy one here from another of your data contexts, then load it.",
+                inputFields: [
+                    packageIdField,
+                    field("fromDataContextId", field_type_1.FieldType.id, "Context to copy from; searched when omitted.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "activatePackageVersion",
+                usageDescription: "Select a stored version for this device or the whole group, then load it on this device.",
+                inputFields: [
+                    packageIdField,
+                    field("packageVersionId", field_type_1.FieldType.id, "Version to activate; omit with device scope to follow the group again.", { optional: true }),
+                    field("scope", field_type_1.FieldType.string, "device (default) or group.", { optional: true }),
+                ],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "reloadPackage",
+                usageDescription: "Rebuild the dev version from the package folder when it changed, then force-reload the package on this device.",
+                inputFields: [packageIdField],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "reloadAllPackages",
+                usageDescription: "Re-read every package folder on this device and reload the packages whose bundles changed.",
+                inputFields: [],
+                outputFields: [
+                    field("skipped", field_type_1.FieldType.string, "Why the host skipped the reload.", {
+                        optional: true,
+                    }),
+                    field("results", field_type_1.FieldType.object, "Per-package outcomes.", { isArray: true }),
+                ],
+            },
+            {
+                name: "linkRemoteRepo",
+                usageDescription: "Create a remote repository for a local package and link it.",
+                inputFields: [packageIdField],
+                outputFields: operationResultFields,
+            },
+            {
+                name: "uninstallPackage",
+                usageDescription: "Remove a package from this data context for every member device and unload it here. Versions, files, and device preferences are kept.",
+                inputFields: [packageIdField],
+                outputFields: [
+                    packageIdField,
+                    field("removed", field_type_1.FieldType.boolean, "True when the package row was removed."),
+                ],
+            },
+            {
+                name: "promotePackageVersion",
+                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag.",
+                inputFields: [
+                    field("packageVersionId", field_type_1.FieldType.id, "Version to promote."),
+                    field("versionTag", field_type_1.FieldType.string, "New release channel: beta or stable."),
+                ],
+                outputFields: [
+                    ...operationResultFields,
+                    field("packageVersionId", field_type_1.FieldType.id, "Promoted version."),
+                    field("version", field_type_1.FieldType.string, "Its version number."),
+                    field("versionTag", field_type_1.FieldType.string, "Its new release channel."),
+                    field("signed", field_type_1.FieldType.boolean, "True when this device signed the promoted version."),
+                    field("activated", field_type_1.FieldType.boolean, "True when the promotion also activated the version for the group or this device."),
+                ],
+            },
+            {
+                name: "installDefaultPackages",
+                usageDescription: "Install the default packages into this data context.",
+                inputFields: [],
+                outputFields: [
+                    field("installed", field_type_1.FieldType.boolean, "True when anything was installed or updated."),
+                ],
+            },
+        ],
+        observables: [
+            {
+                name: "runtimeStates",
+                description: "Runtime state of this context's packages on this device, keyed by package id.",
+                valueType: field_type_1.FieldType.object,
+                writable: false,
+            },
+        ],
+        events: [],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.packagesContractId,
+    version: exports.PACKAGES_CONTRACT_VERSION,
+    getDefinition: getPackagesContractDefinition,
+});

package/dist/data/create-group.d.ts

@@ -19,6 +19,6 @@ export declare const GROUP_NAME_MAX_LENGTH = 100;
  *
  * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
  * through the host rather than duplicating the steps. Package seeding for the new context
- * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ * (for example System Packages `installDefaultPackages`) is the caller's responsibility.
  */
 export declare function createGroup(userContext: UserContext, input: CreateGroupInput): Promise<IGroup>;

package/dist/data/create-group.js

@@ -20,7 +20,7 @@ exports.GROUP_NAME_MAX_LENGTH = 100;
  *
  * Runs on a host with signing enabled (`GroupsTable.enableGroupSigning`); UIs reach it
  * through the host rather than duplicating the steps. Package seeding for the new context
- * (for example `seedBundledPeersCore`) is the caller's responsibility.
+ * (for example System Packages `installDefaultPackages`) is the caller's responsibility.
  */
 async function createGroup(userContext, input) {
     const name = input.name.trim();

package/dist/data/group-members.d.ts

@@ -3,6 +3,7 @@ import type { DataContext } from "../context/data-context";
 import { GroupMemberRole } from "./group-member-roles";
 import type { ISaveOptions } from "./orm/data-query";
 import { Table } from "./orm/table";
+/** Schema for a signed group membership, including its role and soft deletion state. */
 export declare const groupMemberSchema: z.ZodObject<{
     groupMemberId: z.ZodEffects<z.ZodString, string, string>;
     groupId: z.ZodEffects<z.ZodString, string, string>;
@@ -25,18 +26,22 @@ export declare const groupMemberSchema: z.ZodObject<{
     groupMemberId: string;
     deleted?: boolean | undefined;
 }>;
+/** A signed association between a user and a group with an assigned role. */
 export type IGroupMember = z.infer<typeof groupMemberSchema>;
+/** System table name for group membership records. */
 export declare const groupMembersTableName = "GroupMembers";
+/** Group membership table with signature checks and signed soft deletion. */
 export declare class GroupMembersTable extends Table<IGroupMember> {
     static isPassthrough: boolean;
     save(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     signAndSave(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     delete(groupMemberId: string): Promise<void>;
-    private static addSignatureToGroupMember;
+    /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableGroupMemberSigning(fn: (groupMember: IGroupMember) => IGroupMember): void;
     /** @deprecated Forbidden on GroupsTable; use save() */
     insert(..._args: Parameters<Table<IGroupMember>["insert"]>): never;
     /** @deprecated Forbidden on GroupsTable; use save() */
     update(..._args: Parameters<Table<IGroupMember>["update"]>): never;
 }
+/** Returns the GroupMembers table for the given context or the current default context. */
 export declare function GroupMembers(dataContext?: DataContext): GroupMembersTable;

package/dist/data/group-members.js

@@ -46,6 +46,7 @@ const table_1 = require("./orm/table");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
 const users_1 = require("./users");
+/** Schema for a signed group membership, including its role and soft deletion state. */
 exports.groupMemberSchema = zod_1.z.object({
     groupMemberId: zod_types_1.zodPeerId,
     groupId: zod_types_1.zodPeerId.describe("The id of the group"),
@@ -59,6 +60,7 @@ exports.groupMemberSchema = zod_1.z.object({
         .optional()
         .describe("Whether this membership has been deleted (soft delete)"),
 });
+/** System table name for group membership records. */
 exports.groupMembersTableName = "GroupMembers";
 const metaData = {
     name: exports.groupMembersTableName,
@@ -67,6 +69,10 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(exports.groupMemberSchema),
     indexes: [{ fields: ["groupId", "userId"], unique: true }],
 };
+// Symbol.for keeps signer registration shared by separately installed SDK copies.
+const signingKey = Symbol.for("@peers-app/peers-sdk/group-member-signing");
+const signingGlobals = globalThis;
+/** Group membership table with signature checks and signed soft deletion. */
 let GroupMembersTable = (() => {
     let _classSuper = table_1.Table;
     let _instanceExtraInitializers = [];
@@ -96,10 +102,11 @@ let GroupMembersTable = (() => {
             throw new Error("Group member signature is not valid");
         }
         async signAndSave(groupMember, opts) {
-            if (!GroupMembersTable.addSignatureToGroupMember) {
+            const sign = signingGlobals[signingKey];
+            if (!sign) {
                 throw new Error("Group member signing must be enabled to sign and save group members. Call GroupMembersTable.enableGroupMemberSigning(fn) to enable it.");
             }
-            groupMember = GroupMembersTable.addSignatureToGroupMember(groupMember);
+            groupMember = sign.call(GroupMembersTable, groupMember);
             return this.save(groupMember, {
                 saveAsSnapshot: true,
                 restoreIfDeleted: true,
@@ -118,9 +125,9 @@ let GroupMembersTable = (() => {
                 await this.signAndSave(groupMember);
             }
         }
-        static addSignatureToGroupMember = undefined;
+        /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableGroupMemberSigning(fn) {
-            GroupMembersTable.addSignatureToGroupMember = fn;
+            signingGlobals[signingKey] = fn;
         }
         /** @deprecated Forbidden on GroupsTable; use save() */
         insert(..._args) {
@@ -138,6 +145,7 @@ let GroupMembersTable = (() => {
 })();
 exports.GroupMembersTable = GroupMembersTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.groupMemberSchema, GroupMembersTable);
+/** Returns the GroupMembers table for the given context or the current default context. */
 function GroupMembers(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.groupMemberSchema, GroupMembersTable);
 }

package/dist/data/groups.d.ts

@@ -3,6 +3,7 @@ import type { DataContext } from "../context/data-context";
 import { GroupMemberRole } from "./group-member-roles";
 import type { ISaveOptions } from "./orm/data-query";
 import { Table } from "./orm/table";
+/** Schema for a signed group record, including membership policy and group public keys. */
 export declare const groupSchema: z.ZodObject<{
     groupId: z.ZodEffects<z.ZodString, string, string>;
     name: z.ZodString;
@@ -37,18 +38,22 @@ export declare const groupSchema: z.ZodObject<{
     iconClassName?: string | undefined;
     publicRole?: GroupMemberRole | undefined;
 }>;
+/** A signed group record shared between personal and group contexts. */
 export type IGroup = z.infer<typeof groupSchema>;
+/** System table name for group records. */
 export declare const groupsTableName = "Groups";
+/** Group table with signature enforcement outside the personal context. */
 export declare class GroupsTable extends Table<IGroup> {
     static isPassthrough: boolean;
     save(group: IGroup, opts?: ISaveOptions): Promise<IGroup>;
     signAndSave(group: IGroup, opts?: ISaveOptions): Promise<IGroup>;
     delete(groupId: string): Promise<void>;
-    private static addSignatureToGroup;
+    /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableGroupSigning(fn: (group: IGroup) => IGroup): void;
     /** @deprecated Direct inserts forbidden; use save() */
     insert(..._args: Parameters<Table<IGroup>["insert"]>): never;
     /** @deprecated Direct updates forbidden; use save() */
     update(..._args: Parameters<Table<IGroup>["update"]>): never;
 }
+/** Returns the Groups table for the given context or the current default context. */
 export declare function Groups(dataContext?: DataContext): GroupsTable;

package/dist/data/groups.js

@@ -45,6 +45,7 @@ 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");
+/** Schema for a signed group record, including membership policy and group public keys. */
 exports.groupSchema = zod_1.z.object({
     groupId: zod_types_1.zodPeerId,
     name: zod_1.z.string(),
@@ -67,6 +68,7 @@ exports.groupSchema = zod_1.z.object({
         .string()
         .describe("The public key used to encrypt data that only group members with writer permissions or higher can decrypt"),
 });
+/** System table name for group records. */
 exports.groupsTableName = "Groups";
 const metaData = {
     name: exports.groupsTableName,
@@ -76,6 +78,10 @@ const metaData = {
     iconClassName: "bi bi-people-fill",
     indexes: [{ fields: ["name"] }],
 };
+// Symbol.for keeps signer registration shared by separately installed SDK copies.
+const signingKey = Symbol.for("@peers-app/peers-sdk/group-signing");
+const signingGlobals = globalThis;
+/** Group table with signature enforcement outside the personal context. */
 let GroupsTable = (() => {
     let _classSuper = table_1.Table;
     let _instanceExtraInitializers = [];
@@ -103,10 +109,11 @@ let GroupsTable = (() => {
             return super.save(group, opts);
         }
         async signAndSave(group, opts) {
-            if (!GroupsTable.addSignatureToGroup) {
+            const sign = signingGlobals[signingKey];
+            if (!sign) {
                 throw new Error("Group signing must be enabled to sign and save groups. Call GroupsTable.enableGroupSigning(fn) to enable it.");
             }
-            group = GroupsTable.addSignatureToGroup(group);
+            group = sign.call(GroupsTable, group);
             return this.save(group, opts);
         }
         async delete(groupId) {
@@ -117,9 +124,9 @@ let GroupsTable = (() => {
             }
             throw new Error("Only deleting groups from the user context Groups table is allowed");
         }
-        static addSignatureToGroup = undefined;
+        /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableGroupSigning(fn) {
-            GroupsTable.addSignatureToGroup = fn;
+            signingGlobals[signingKey] = fn;
         }
         /** @deprecated Direct inserts forbidden; use save() */
         insert(..._args) {
@@ -137,6 +144,7 @@ let GroupsTable = (() => {
 })();
 exports.GroupsTable = GroupsTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.groupSchema, GroupsTable);
+/** Returns the Groups table for the given context or the current default context. */
 function Groups(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.groupSchema, GroupsTable);
 }

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

@@ -81,17 +81,23 @@ export interface IResolveResult {
 }
 /**
  * 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".
+ * follow policy and loads the best one. A dev version runs only on a device whose own
+ * selection points at it; a group selection of a dev version is left unloaded here.
  *
  * Callers:
  * - `PackagesTrackedDataSource.applyChanges` (on sync)
  * - `PackageLoader.loadAllPackages` (startup)
  * - `package-installer.ts` (after saving new bundles)
+ *
+ * @param opts.force - Reload even when the package is already loaded.
+ * @param opts.localPath - Package folder whose rebuilt dev bundle wins over the stored one.
+ * @param opts.onlyIfChanged - With `force`, keep a running package whose selected version and
+ *   bundle are unchanged instead of restarting it (sync reconciliation).
  */
 export declare function resolveDevicePackageVersion(pkg: IPackage, dataContext: DataContext, opts?: {
     force?: boolean;
     localPath?: string;
+    onlyIfChanged?: boolean;
 }): Promise<IResolveResult>;
 /**
  * Returns true when the device has an explicit follow-policy override

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

@@ -85,13 +85,18 @@ function getEffectivePackagePrefs(pkg, devicePrefs) {
 }
 /**
  * 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".
+ * follow policy and loads the best one. A dev version runs only on a device whose own
+ * selection points at it; a group selection of a dev version is left unloaded here.
  *
  * Callers:
  * - `PackagesTrackedDataSource.applyChanges` (on sync)
  * - `PackageLoader.loadAllPackages` (startup)
  * - `package-installer.ts` (after saving new bundles)
+ *
+ * @param opts.force - Reload even when the package is already loaded.
+ * @param opts.localPath - Package folder whose rebuilt dev bundle wins over the stored one.
+ * @param opts.onlyIfChanged - With `force`, keep a running package whose selected version and
+ *   bundle are unchanged instead of restarting it (sync reconciliation).
  */
 async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     const pvar = packagePrefsVar(pkg.packageId, dataContext);
@@ -118,6 +123,21 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (!effectiveActivePvId) {
         return { loaded: false, upgraded: false };
     }
+    // A dev version runs only on a device that activated it. The group's selection can be a
+    // dev version (a new package, or one copied from another context); other devices leave it
+    // unloaded until they activate it themselves. Once activated here, rebuilds of that same
+    // version row keep loading through the dev branch below.
+    if (rawPrefs.activePackageVersionId !== effectiveActivePvId) {
+        const groupSelection = await (0, package_versions_1.PackageVersions)(dataContext)
+            .get(effectiveActivePvId)
+            .catch(() => undefined);
+        if (groupSelection?.versionTag === "dev") {
+            await dataContext.packageLoader.unloadPackage(pkg.packageId, {
+                reason: `Only a dev version (v${groupSelection.version}) is selected; activate it on this device to run it`,
+            });
+            return { loaded: false, pv: groupSelection, upgraded: false };
+        }
+    }
     const localPath = opts?.localPath ??
         (await readStoredPackageLocalPath(pkg.packageId, dataContext).catch(() => undefined));
     const compatibilityTargetId = rawPrefs.compatibilityFallbackForPackageVersionId;
@@ -130,6 +150,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (compatibilityTarget) {
             try {
                 const restored = await dataContext.packageLoader.loadPackage(pkg, {
+                    onlyIfChanged: opts?.onlyIfChanged,
                     force: true,
                     localPath,
                     packageVersionId: compatibilityTargetId,
@@ -158,6 +179,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         if (!pv)
             return { loaded: false, pv: undefined, upgraded: false };
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            onlyIfChanged: opts?.onlyIfChanged,
             force: opts?.force,
             localPath,
             packageVersionId: effectiveActivePvId,
@@ -182,6 +204,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     // activates a non-dev version.
     if (activePv?.versionTag === "dev") {
         const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            onlyIfChanged: opts?.onlyIfChanged,
             force: opts?.force,
             localPath,
             packageVersionId: effectiveActivePvId,
@@ -216,6 +239,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     if (!bestPv || bestPv.packageVersionId === effectiveActivePvId) {
         if (activePv) {
             const instance = await dataContext.packageLoader.loadPackage(pkg, {
+                onlyIfChanged: opts?.onlyIfChanged,
                 force: opts?.force,
                 localPath,
                 packageVersionId: effectiveActivePvId,
@@ -233,6 +257,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
     // A better PV was found - attempt to load it (getFileContents will
     // auto-download missing chunks from peers)
     const instance = await dataContext.packageLoader.loadPackage(pkg, {
+        onlyIfChanged: opts?.onlyIfChanged,
         force: true,
         localPath,
         packageVersionId: bestPv.packageVersionId,
@@ -241,6 +266,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         // Bundle unavailable even after download attempt - keep current version
         if (activePv) {
             const fallbackInstance = await dataContext.packageLoader.loadPackage(pkg, {
+                onlyIfChanged: opts?.onlyIfChanged,
                 force: opts?.force,
                 localPath,
                 packageVersionId: effectiveActivePvId,

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

@@ -368,6 +368,48 @@ describe("resolveDevicePackageVersion — expected behavior (control)", () => {
         expect(loadedPvIds).toContain(stablePv.packageVersionId);
         expect(loadedPvIds).not.toContain(devPv.packageVersionId);
     });
+    it.each([
+        ["no prefs", false],
+        ["a pin", true],
+    ])("leaves a group-selected dev version unloaded on a device with %s", async (_label, pinned) => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const devPv = makePV(packageId, { version: "0.1.0", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({ packageId, activePackageVersionId: devPv.packageVersionId });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        if (pinned)
+            await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { pinned: true }, dc);
+        const load = jest.spyOn(dc.packageLoader, "loadPackage");
+        const unload = jest
+            .spyOn(dc.packageLoader, "unloadPackage")
+            .mockImplementation(async () => undefined);
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result).toMatchObject({ loaded: false, upgraded: false });
+        expect(result.pv?.packageVersionId).toBe(devPv.packageVersionId);
+        expect(load).not.toHaveBeenCalled();
+        expect(unload).toHaveBeenCalledWith(packageId, {
+            reason: "Only a dev version (v0.1.0) is selected; activate it on this device to run it",
+        });
+    });
+    it("runs a group-selected dev version once this device activates it", async () => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const devPv = makePV(packageId, { version: "0.1.0", versionTag: "dev" });
+        await (0, package_versions_1.PackageVersions)(dc).save(devPv);
+        const pkg = makePkg({ packageId, activePackageVersionId: devPv.packageVersionId });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        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 };
+        });
+        const result = await (0, package_version_resolver_1.resolveDevicePackageVersion)(pkg, dc, { force: true });
+        expect(result.loaded).toBe(true);
+        expect(loadedPvIds).toEqual([devPv.packageVersionId]);
+    });
     it("installs assistants and workflows into the data context on auto-upgrade", async () => {
         const dc = groupDc();
         const packageId = (0, utils_1.newid)();

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

@@ -107,16 +107,19 @@ declare const schema: z.ZodObject<{
     uiBundleFileHash?: string | undefined;
     packageAuthorSignature?: string | undefined;
 }>;
+/** A signed package build and its bundle hashes, tag, and lifecycle history. */
 export type IPackageVersion = z.infer<typeof schema>;
+/** Package version table with signature and group promotion permission checks. */
 export declare class PackageVersionsTable extends Table<IPackageVersion> {
     static isPassthrough: boolean;
     insert(packageVersion: IPackageVersion, opts?: ISaveOptions): Promise<IPackageVersion>;
     update(packageVersion: IPackageVersion, opts?: ISaveOptions): Promise<IPackageVersion>;
     save(packageVersion: IPackageVersion, opts?: ISaveOptions): Promise<IPackageVersion>;
     signAndSave(packageVersion: IPackageVersion, opts?: ISaveOptions): Promise<IPackageVersion>;
-    private static addSignatureToPackageVersion;
+    /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enablePackageVersionSigning(fn: (packageVersion: IPackageVersion) => IPackageVersion): void;
 }
+/** Returns the PackageVersions table for the given context or the current default context. */
 export declare function PackageVersions(dataContext?: DataContext): PackageVersionsTable;
 /**
  * Compute a content hash from bundle file hashes. The hash represents code
@@ -134,6 +137,7 @@ export declare function PackageVersions(dataContext?: DataContext): PackageVersi
 export declare function computePackageVersionHash(version: string, 
 /** @deprecated Ignored — will be removed in a future release. */
 _versionTag: string, packageBundleFileHash: string, routesBundleFileHash?: string, uiBundleFileHash?: string): string;
+/** Checks whether an incoming version falls within the selected automatic update range. */
 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).