@peers-app/peers-sdk 0.26.4 → 0.26.6

package/dist/data/package-versions.js

@@ -92,6 +92,10 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(schema),
     indexes: [{ fields: ["packageId"] }],
 };
+// Symbol.for keeps signer registration shared by separately installed SDK copies.
+const signingKey = Symbol.for("@peers-app/peers-sdk/package-version-signing");
+const signingGlobals = globalThis;
+/** Package version table with signature and group promotion permission checks. */
 let PackageVersionsTable = (() => {
     let _classSuper = table_1.Table;
     let _instanceExtraInitializers = [];
@@ -122,15 +126,16 @@ let PackageVersionsTable = (() => {
             return super.save(packageVersion, opts);
         }
         async signAndSave(packageVersion, opts) {
-            if (!PackageVersionsTable.addSignatureToPackageVersion) {
+            const sign = signingGlobals[signingKey];
+            if (!sign) {
                 throw new Error("Package version signing is not enabled. Call PackageVersionsTable.enablePackageVersionSigning(fn) to enable it.");
             }
-            packageVersion = await PackageVersionsTable.addSignatureToPackageVersion(packageVersion);
+            packageVersion = await sign.call(PackageVersionsTable, packageVersion);
             return this.save(packageVersion, opts);
         }
-        static addSignatureToPackageVersion = undefined;
+        /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageVersionSigning(fn) {
-            PackageVersionsTable.addSignatureToPackageVersion = fn;
+            signingGlobals[signingKey] = fn;
         }
         constructor() {
             super(...arguments);
@@ -140,6 +145,7 @@ let PackageVersionsTable = (() => {
 })();
 exports.PackageVersionsTable = PackageVersionsTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, schema, PackageVersionsTable);
+/** Returns the PackageVersions table for the given context or the current default context. */
 function PackageVersions(dataContext) {
     return (0, context_1.getTableContainer)(dataContext).getTable(metaData, schema, PackageVersionsTable);
 }
@@ -161,6 +167,7 @@ function computePackageVersionHash(version,
 _versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) {
     return (0, keys_1.hashValue)([version, packageBundleFileHash, routesBundleFileHash ?? "", uiBundleFileHash ?? ""].join(":"));
 }
+/** Checks whether an incoming version falls within the selected automatic update range. */
 function isVersionInRange(activeVersion, incomingVersion, range) {
     if (range === "pinned")
         return false;

package/dist/data/packages.d.ts

@@ -42,19 +42,25 @@ declare const schema: z.ZodObject<{
     followVersionTags?: string | undefined;
     updateUrl?: string | undefined;
 }>;
+/** A signed package record with publisher identity and version selection policy. */
 export type IPackage = z.infer<typeof schema>;
+/** Package table with signature enforcement outside personal contexts. */
 export declare class PackagesTable extends Table<IPackage> {
     static isPassthrough: boolean;
     insert(packageObj: IPackage, opts?: ISaveOptions): Promise<IPackage>;
     update(packageObj: IPackage, opts?: ISaveOptions): Promise<IPackage>;
     save(packageObj: IPackage, opts?: ISaveOptions): Promise<IPackage>;
     signAndSave(packageObj: IPackage, opts?: ISaveOptions): Promise<IPackage>;
-    private static addSignatureToPackage;
+    /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enablePackageSigning(fn: (packageObj: IPackage) => IPackage): void;
     delete(packageId: string): Promise<void>;
 }
+/** Returns the Packages table for the given context or the current default context. */
 export declare function Packages(dataContext?: DataContext): PackagesTable;
+/** Default directory for locally stored package files. */
 export declare const packagesRootDir = "~/peers/packages";
+/** Device preference controlling package reloads when the UI refreshes. */
 export declare const reloadPackagesOnPageRefresh: import("./persistent-vars").PersistentVar<boolean>;
+/** Device preference enabling automatic peers-core updates. */
 export declare const autoUpdatePeersCore: import("./persistent-vars").PersistentVar<boolean>;
 export {};

package/dist/data/packages.js

@@ -83,6 +83,10 @@ const metaData = {
     iconClassName: "bi bi-box-fill",
     fields: (0, types_1.schemaToFields)(schema),
 };
+// Symbol.for keeps signer registration shared by separately installed SDK copies.
+const signingKey = Symbol.for("@peers-app/peers-sdk/package-signing");
+const signingGlobals = globalThis;
+/** Package table with signature enforcement outside personal contexts. */
 let PackagesTable = (() => {
     let _classSuper = table_1.Table;
     let _instanceExtraInitializers = [];
@@ -113,15 +117,16 @@ let PackagesTable = (() => {
             return super.save(packageObj, opts);
         }
         async signAndSave(packageObj, opts) {
-            if (!PackagesTable.addSignatureToPackage) {
+            const sign = signingGlobals[signingKey];
+            if (!sign) {
                 throw new Error("Package signing is not enabled. Call PackagesTable.enablePackageSigning(fn) to enable it.");
             }
-            packageObj = await PackagesTable.addSignatureToPackage(packageObj);
+            packageObj = await sign.call(PackagesTable, packageObj);
             return this.save(packageObj, opts);
         }
-        static addSignatureToPackage = undefined;
+        /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageSigning(fn) {
-            PackagesTable.addSignatureToPackage = fn;
+            signingGlobals[signingKey] = fn;
         }
         async delete(packageId) {
             // anyone (with write permissions) can delete packages since that isn't a security risk (unless something else is relying on a package to be present?)
@@ -141,11 +146,15 @@ let PackagesTable = (() => {
 })();
 exports.PackagesTable = PackagesTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, schema, PackagesTable);
+/** Returns the Packages table for the given context or the current default context. */
 function Packages(dataContext) {
     return (0, context_1.getTableContainer)(dataContext).getTable(metaData, schema, PackagesTable);
 }
+/** Default directory for locally stored package files. */
 exports.packagesRootDir = "~/peers/packages";
+/** Device preference controlling package reloads when the UI refreshes. */
 exports.reloadPackagesOnPageRefresh = (0, persistent_vars_1.deviceVar)("reloadPackagesOnPageRefresh", {
     defaultValue: true,
 });
+/** Device preference enabling automatic peers-core updates. */
 exports.autoUpdatePeersCore = (0, persistent_vars_1.deviceVar)("autoUpdatePeersCore", { defaultValue: true });

package/dist/data/table-signing.test.d.ts

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

package/dist/data/table-signing.test.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tableNames = ["package-version", "package", "group", "group-member", "user"];
+// These key strings are the contract between installed SDK versions; do not rename them.
+const signingKey = (name) => Symbol.for(`@peers-app/peers-sdk/${name}-signing`);
+// Restore process-global registrations so these tests never leave test signers installed.
+const priorSigners = tableNames.map((name) => {
+    const key = signingKey(name);
+    return { key, descriptor: Object.getOwnPropertyDescriptor(globalThis, key) };
+});
+beforeEach(() => {
+    for (const { key } of priorSigners) {
+        Reflect.deleteProperty(globalThis, key);
+    }
+});
+afterEach(() => {
+    for (const { key, descriptor } of priorSigners) {
+        if (descriptor) {
+            Object.defineProperty(globalThis, key, descriptor);
+        }
+        else {
+            Reflect.deleteProperty(globalThis, key);
+        }
+    }
+});
+function loadSigningTables() {
+    let tables;
+    jest.isolateModules(() => {
+        const { PackageVersionsTable } = require("./package-versions");
+        const { PackagesTable } = require("./packages");
+        const { GroupsTable } = require("./groups");
+        const { GroupMembersTable } = require("./group-members");
+        const { UsersTable } = require("./users");
+        tables = {
+            "package-version": {
+                prototype: PackageVersionsTable.prototype,
+                enable: PackageVersionsTable.enablePackageVersionSigning,
+            },
+            package: { prototype: PackagesTable.prototype, enable: PackagesTable.enablePackageSigning },
+            group: { prototype: GroupsTable.prototype, enable: GroupsTable.enableGroupSigning },
+            "group-member": {
+                prototype: GroupMembersTable.prototype,
+                enable: GroupMembersTable.enableGroupMemberSigning,
+            },
+            user: { prototype: UsersTable.prototype, enable: UsersTable.enableUserSigning },
+        };
+    });
+    return tables;
+}
+describe("table signing across SDK module instances", () => {
+    it.each(tableNames)("shares and replaces the %s signer across copies", async (name) => {
+        const first = loadSigningTables()[name];
+        const second = loadSigningTables()[name];
+        expect(first.prototype).not.toBe(second.prototype);
+        // Stub persistence only: exercise the real signAndSave and registration methods.
+        const receiver = { save: jest.fn(async (record) => record) };
+        const row = { name: "Example", signature: "" };
+        const opts = { saveAsSnapshot: false };
+        await expect(second.prototype.signAndSave.call(receiver, row, opts)).rejects.toThrow(/signing.*enabled/i);
+        expect(receiver.save).not.toHaveBeenCalled();
+        const sign = jest.fn((record) => ({ ...record, signature: "first" }));
+        first.enable(sign);
+        expect(Reflect.get(globalThis, signingKey(name))).toBe(sign);
+        await expect(second.prototype.signAndSave.call(receiver, row, opts)).resolves.toEqual({
+            ...row,
+            signature: "first",
+        });
+        expect(sign).toHaveBeenCalledWith(row);
+        expect(sign.mock.contexts.at(-1)).toBe(second.prototype.constructor);
+        expect(receiver.save).toHaveBeenLastCalledWith({ ...row, signature: "first" }, name === "group-member" ? { ...opts, restoreIfDeleted: true } : opts);
+        // Loading another copy must preserve a signer that is already registered.
+        const third = loadSigningTables()[name];
+        expect(third.prototype).not.toBe(first.prototype);
+        await expect(third.prototype.signAndSave.call(receiver, row)).resolves.toEqual({
+            ...row,
+            signature: "first",
+        });
+        expect(sign.mock.contexts.at(-1)).toBe(third.prototype.constructor);
+        second.enable((record) => ({ ...record, signature: "replacement" }));
+        for (const copy of [first, third]) {
+            await expect(copy.prototype.signAndSave.call(receiver, row)).resolves.toEqual({
+                ...row,
+                signature: "replacement",
+            });
+        }
+        receiver.save.mockClear();
+        const failsOnce = jest
+            .fn((record) => ({ ...record, signature: "recovered" }))
+            .mockImplementationOnce(() => {
+            throw new Error("signing failed");
+        });
+        first.enable(failsOnce);
+        await expect(second.prototype.signAndSave.call(receiver, row)).rejects.toThrow("signing failed");
+        expect(receiver.save).not.toHaveBeenCalled();
+        await expect(third.prototype.signAndSave.call(receiver, row)).resolves.toEqual({
+            ...row,
+            signature: "recovered",
+        });
+        expect(failsOnce).toHaveBeenCalledTimes(2);
+        receiver.save.mockRejectedValueOnce(new Error("save failed"));
+        await expect(second.prototype.signAndSave.call(receiver, row)).rejects.toThrow("save failed");
+        await expect(first.prototype.signAndSave.call(receiver, row)).resolves.toEqual({
+            ...row,
+            signature: "recovered",
+        });
+    });
+    it("keeps the five signer registrations independent", async () => {
+        const first = loadSigningTables();
+        const second = loadSigningTables();
+        for (const name of tableNames) {
+            first[name].enable((record) => ({ ...record, signature: name }));
+        }
+        const receiver = { save: jest.fn(async (record) => record) };
+        for (const name of tableNames) {
+            await expect(second[name].prototype.signAndSave.call(receiver, { name: "Example", signature: "" })).resolves.toEqual({ name: "Example", signature: name });
+        }
+    });
+});

package/dist/data/users.d.ts

@@ -84,8 +84,7 @@ export declare class UsersTable extends Table<IUser> {
      */
     save(user: IUser, opts?: ISaveOptions): Promise<IUser>;
     signAndSave(user: IUser, opts?: ISaveOptions): Promise<IUser>;
-    private static addSignatureToUser;
-    /** Enables signing for proxied `signAndSave` calls. */
+    /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableUserSigning(fn: (user: IUser) => IUser): void;
     /** @deprecated Forbidden on UsersTable; use save() */
     insert(..._args: Parameters<Table<IUser>["insert"]>): never;

package/dist/data/users.js

@@ -102,6 +102,9 @@ let userRowChangeGuard = refuseIdentityChanges;
 function setUserRowChangeGuard(guard) {
     userRowChangeGuard = guard ?? refuseIdentityChanges;
 }
+// Symbol.for keeps signer registration shared by separately installed SDK copies.
+const signingKey = Symbol.for("@peers-app/peers-sdk/user-signing");
+const signingGlobals = globalThis;
 /** User table with owner-signature enforcement outside the personal context. */
 let UsersTable = (() => {
     let _classSuper = table_1.Table;
@@ -170,20 +173,20 @@ let UsersTable = (() => {
             return super.save(verdict.row, opts);
         }
         async signAndSave(user, opts) {
-            if (!UsersTable.addSignatureToUser) {
+            const sign = signingGlobals[signingKey];
+            if (!sign) {
                 throw new Error("User signing must be enabled to sign and save users. Call UsersTable.enableUserSigning(fn) to enable it.");
             }
             user = {
                 ...user,
                 name: user.name.slice(0, devices_1.DISPLAY_NAME_MAX_LENGTH),
             };
-            user = UsersTable.addSignatureToUser(user);
+            user = sign.call(UsersTable, user);
             return this.save(user, opts);
         }
-        static addSignatureToUser = undefined;
-        /** Enables signing for proxied `signAndSave` calls. */
+        /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableUserSigning(fn) {
-            UsersTable.addSignatureToUser = fn;
+            signingGlobals[signingKey] = fn;
         }
         /** @deprecated Forbidden on UsersTable; use save() */
         insert(..._args) {

package/dist/package-installer/package-author-signer.d.ts

@@ -23,3 +23,22 @@ export declare function loadPackageSigningKey(packageId: string, getUserSecretKe
  * @param getUserSecretKey - Platform callback that returns the signed-in user's secret key
  */
 export declare function trySignPackageAuthorVersion(pvFields: AuthorSignableFields, getUserSecretKey: () => Promise<string>): Promise<string | undefined>;
+/** Host-installed signer for PackageVersion author signatures. */
+export type PackageAuthorVersionSigner = (pvFields: AuthorSignableFields) => Promise<string | undefined>;
+/**
+ * Install (or clear) the host's PackageVersion author signer.
+ *
+ * `peers-device` installs one at startup over the signed-in user's secret key, so Runtime
+ * code (the installer, System Packages) can re-sign versions without a host RPC.
+ *
+ * @param signer - Signer to use, or `undefined` to clear it.
+ */
+export declare function setPackageAuthorVersionSigner(signer: PackageAuthorVersionSigner | undefined): void;
+/**
+ * Sign PackageVersion fields with the installed host signer.
+ *
+ * @param pvFields - Author-signable PackageVersion fields.
+ * @returns The detached signature, or `undefined` when no signer is installed, the package
+ *   signing key is unavailable, or signing fails.
+ */
+export declare function signPackageAuthorVersionOnHost(pvFields: AuthorSignableFields): Promise<string | undefined>;

package/dist/package-installer/package-author-signer.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPackageSigningKey = loadPackageSigningKey;
 exports.trySignPackageAuthorVersion = trySignPackageAuthorVersion;
+exports.setPackageAuthorVersionSigner = setPackageAuthorVersionSigner;
+exports.signPackageAuthorVersionOnHost = signPackageAuthorVersionOnHost;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const persistent_vars_1 = require("../data/persistent-vars");
 const keys_1 = require("../keys");
@@ -55,3 +57,25 @@ async function trySignPackageAuthorVersion(pvFields, getUserSecretKey) {
         return undefined;
     }
 }
+let installedSigner;
+/**
+ * Install (or clear) the host's PackageVersion author signer.
+ *
+ * `peers-device` installs one at startup over the signed-in user's secret key, so Runtime
+ * code (the installer, System Packages) can re-sign versions without a host RPC.
+ *
+ * @param signer - Signer to use, or `undefined` to clear it.
+ */
+function setPackageAuthorVersionSigner(signer) {
+    installedSigner = signer;
+}
+/**
+ * Sign PackageVersion fields with the installed host signer.
+ *
+ * @param pvFields - Author-signable PackageVersion fields.
+ * @returns The detached signature, or `undefined` when no signer is installed, the package
+ *   signing key is unavailable, or signing fails.
+ */
+async function signPackageAuthorVersionOnHost(pvFields) {
+    return installedSigner?.(pvFields);
+}

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

@@ -1,11 +1,5 @@
 import type { DataContext } from "../context/data-context";
-import type { IAddOrUpdatePackageResult, ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps, ITemplateCacheResult, TemplateCacheRefreshFailure } from "./types";
-/**
- * Normalize `addOrUpdatePackage` RPC results.
- * Older hosts return a bare packageId string; current hosts return
- * {@link IAddOrUpdatePackageResult}.
- */
-export declare function unwrapAddOrUpdatePackageResult(result: string | IAddOrUpdatePackageResult): IAddOrUpdatePackageResult;
+import type { ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps, ITemplateCacheResult, TemplateCacheRefreshFailure } from "./types";
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"

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

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unwrapAddOrUpdatePackageResult = unwrapAddOrUpdatePackageResult;
 exports.nameToFolderSlug = nameToFolderSlug;
 exports.classifyTemplatePullFailure = classifyTemplatePullFailure;
 exports.ensureTemplateCache = ensureTemplateCache;
@@ -24,17 +23,6 @@ function patchTemplateTokens(contents, values) {
         .replaceAll("<app-screen-id>", values.appScreenId)
         .replaceAll("<contract-id>", values.contractId);
 }
-/**
- * Normalize `addOrUpdatePackage` RPC results.
- * Older hosts return a bare packageId string; current hosts return
- * {@link IAddOrUpdatePackageResult}.
- */
-function unwrapAddOrUpdatePackageResult(result) {
-    if (typeof result === "string") {
-        return { packageId: result };
-    }
-    return result;
-}
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"

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

@@ -87,22 +87,6 @@ beforeEach(() => {
     mockNewKeys.mockReturnValue(generatedKeys);
     mockPersistentVarsSave.mockReset();
 });
-describe("unwrapAddOrUpdatePackageResult", () => {
-    it("accepts a legacy packageId string", () => {
-        expect((0, package_creator_1.unwrapAddOrUpdatePackageResult)("00mnkoyo7mizav6tseubjzr3a")).toEqual({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-        });
-    });
-    it("passes through a structured result including a template warning", () => {
-        expect((0, package_creator_1.unwrapAddOrUpdatePackageResult)({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-            warning: "stale template",
-        })).toEqual({
-            packageId: "00mnkoyo7mizav6tseubjzr3a",
-            warning: "stale template",
-        });
-    });
-});
 describe("nameToFolderSlug", () => {
     it("converts a simple name", () => {
         expect((0, package_creator_1.nameToFolderSlug)("My Widget")).toBe("my-widget");

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

@@ -8,6 +8,11 @@ import type { IInstallOpts, IInstallResult, IPackageInfo, IPackageInstallerDeps
  * bundles from `dist/`, hashes them for deduplication, saves File records
  * only when content has changed, upserts the PackageVersion, and optionally
  * triggers the package loader and device version resolution.
+ *
+ * When the bundle hash matches the existing PackageVersion, no files or PV are
+ * rewritten. The Packages row still gets a missing `activePackageVersionId`
+ * (and description), and when the id was missing the version is activated on
+ * this device unless `skipResolve`.
  */
 export declare function installPackageFromBundles(dataContext: DataContext, deps: IPackageInstallerDeps, packageId: string, opts?: IInstallOpts): Promise<IInstallResult>;
 /**

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

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