@peers-app/peers-sdk 0.18.8 → 0.19.6

package/README.md

@@ -1 +1,74 @@
-Common types, zod schemas, functions, and classes that are used internally in Peers and for building packages.  
+# @peers-app/peers-sdk
+
+The core SDK for building [Peers](https://peers.app) packages.
+
+## What is Peers?
+
+Peers is a local-first personal computing platform. Your data lives on your devices, syncs peer-to-peer, and is end-to-end encrypted — no servers in the middle. You own your data and your identity. Build apps with the SDK or use AI coding tools to create them; either way, the platform handles sync, encryption, and persistence automatically.
+
+## What this package provides
+
+### Package System
+
+`definePackage()` and the contract builder API let you declare tables, tools, assistants, screens, and navigation entries. The runtime installs, loads, and hot-reloads your package across all devices.
+
+### ORM
+
+Table definitions with Zod schemas, data queries with a Mongo-style filter syntax, and async cursors. Tables sync across devices and encrypt automatically — you just define the schema.
+
+### Observables and Persistent Variables
+
+Lightweight reactive primitives (`observable()`, `computed()`) with `.subscribe()`. Persistent variables (`deviceVar`, `userVar`, `groupVar`) are observables backed by the database — write once, subscribe everywhere, synced across devices.
+
+### Types and Schemas
+
+Zod schemas and TypeScript types for the entire Peers data model: users, groups, devices, packages, tools, assistants, workflows, messages, channels, and more.
+
+### Encryption
+
+NaCl-based key management, message signing and verification, box encryption, and deterministic hashing. Identity is a cryptographic key pair — no passwords, no email.
+
+### Tools Framework
+
+Define AI-callable tools with `ITool` and `IToolInstance`. Tools are registered at runtime and available to built-in and user-defined AI assistants and workflows.
+
+### Identity and Groups
+
+User, group, and permission management types. Group-scoped data contexts for multi-tenant data isolation. Invite flows and trust levels.
+
+## Quick Start
+
+```bash
+npm install @peers-app/peers-sdk
+```
+
+The fastest way to build a Peers package is to start from the template:
+
+**[peers-package-template](https://github.com/peers-app/peers-package-template)** — scaffold, build, and install a custom package into the Peers runtime.  This will be setup automatically when you create a new package in the desktop app.  
+
+## Key Interfaces
+
+
+| Export                               | Purpose                                                                 |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| `definePackage()`                    | Entry point for declaring a package's contracts, tools, tables, and nav |
+| `Table`                              | ORM table with CRUD, Zod validation, and `dataChanged` events           |
+| `DataQuery` / `DataFilter`           | Mongo-style query filters translated to SQL                             |
+| `observable()` / `computed()`        | Reactive state primitives                                               |
+| `deviceVar` / `userVar` / `groupVar` | Persistent variables — observables backed by the database               |
+| `ITool` / `IToolInstance`            | AI-callable tool definitions                                            |
+| `IPeersUI` / `IPeersUIRoute`         | Screen and route declarations for package UIs                           |
+| `newid()`                            | Generate 25-character time-sortable peer IDs                            |
+| `newKeys()` / `hydrateKeys()`        | Cryptographic key pair generation and hydration                         |
+| `UserContext` / `DataContext`        | Multi-group data scoping and package loading                            |
+
+
+## Links
+
+- [peers.app](https://peers.app) — try Peers in your browser or download the desktop app
+- [Documentation](https://peers-app.github.io) — architecture, package development, and API reference
+- [GitHub](https://github.com/peers-app) — source repositories and package template
+
+## License
+
+MIT

package/dist/data/files/file-read-stream.js

@@ -36,6 +36,13 @@ class FileReadStream {
         else {
             throw new Error(`File ${this.fileRecord.fileId} has neither chunkHashes nor indexFileId`);
         }
+        if (!this.skipVerification) {
+            const computedFileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(this.chunkHashes)));
+            if (computedFileHash !== this.fileRecord.fileHash) {
+                throw new Error(`File integrity check failed for ${this.fileRecord.fileId}: ` +
+                    `chunk hashes produce ${computedFileHash}, expected ${this.fileRecord.fileHash}`);
+            }
+        }
     }
     async loadChunkByIndex(chunkIndex) {
         await this.loadChunkHashes();

package/dist/data/files/file.types.d.ts

@@ -35,6 +35,12 @@ export declare const FILE_CHUNK_SIZE: number;
 export declare const CHUNKS_DIR = "file_chunks";
 export declare let CHUNK_INDEX_THRESHOLD: number;
 export declare function setChunkIndexThreshold(threshold: number): void;
+/**
+ * Compute the file-system hash for content without saving it.
+ * Mirrors the chunking + hashing logic of FileWriteStream so the result
+ * matches `IFile.fileHash` for the same bytes.
+ */
+export declare function computeFileHash(content: string | Uint8Array): string;
 export interface FileOps {
     downloadFileChunk(chunkHash: string): Promise<Uint8Array | null>;
     fileExists(path: string): Promise<boolean>;

package/dist/data/files/file.types.js

@@ -2,10 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CHUNK_INDEX_THRESHOLD = exports.CHUNKS_DIR = exports.FILE_CHUNK_SIZE = exports.filesMetaData = exports.fileSchema = void 0;
 exports.setChunkIndexThreshold = setChunkIndexThreshold;
+exports.computeFileHash = computeFileHash;
 exports.setFileOps = setFileOps;
 exports.getFileOps = getFileOps;
 exports.resetFileOps = resetFileOps;
 const zod_1 = require("zod");
+const keys_1 = require("../../keys");
 const zod_types_1 = require("../../types/zod-types");
 const types_1 = require("../orm/types");
 exports.fileSchema = zod_1.z.object({
@@ -38,6 +40,22 @@ exports.CHUNK_INDEX_THRESHOLD = 1000; // Use chunk index file for files with >10
 function setChunkIndexThreshold(threshold) {
     exports.CHUNK_INDEX_THRESHOLD = threshold;
 }
+/**
+ * Compute the file-system hash for content without saving it.
+ * Mirrors the chunking + hashing logic of FileWriteStream so the result
+ * matches `IFile.fileHash` for the same bytes.
+ */
+function computeFileHash(content) {
+    const data = typeof content === "string" ? new Uint8Array(Buffer.from(content, "utf8")) : content;
+    const chunkHashes = [];
+    let offset = 0;
+    while (offset < data.length) {
+        const end = Math.min(offset + exports.FILE_CHUNK_SIZE, data.length);
+        chunkHashes.push((0, keys_1.hashBytes)(data.subarray(offset, end)));
+        offset = end;
+    }
+    return (0, keys_1.hashBytes)(new Uint8Array(Buffer.from(JSON.stringify(chunkHashes), "utf8")));
+}
 let fileOps = null;
 let fileOpsReady = null;
 function setFileOps(ops) {

package/dist/data/files/files.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const keys_1 = require("../../keys");
 const field_type_1 = require("../../types/field-type");
 const utils_1 = require("../../utils");
 const file_types_1 = require("./file.types");
@@ -201,7 +202,7 @@ describe("FileTable", () => {
             const result = await fileTable.getFileContents("non-existent");
             expect(result).toBeNull();
         });
-        it("should return null when chunk is missing", async () => {
+        it("should throw integrity error when fileHash doesn't match chunk hashes", async () => {
             const fileId = (0, utils_1.newid)();
             const metadata = {
                 fileId,
@@ -210,10 +211,9 @@ describe("FileTable", () => {
                 fileHash: "hash123",
                 chunkHashes: ["hash1", "hash2"],
             };
-            // Insert metadata directly without saving chunks
+            // Insert metadata directly with mismatched fileHash
             await fileTable.dataSource.insert(metadata);
-            const result = await fileTable.getFileContents(fileId);
-            expect(result).toBeNull();
+            await expect(fileTable.getFileContents(fileId)).rejects.toThrow("File integrity check failed");
         });
         it("should return null when chunk is missing during read", async () => {
             const result = await fileTable.getFileContents("non-existent");
@@ -674,20 +674,63 @@ describe("FileTable", () => {
             });
             it("should return null when chunk is unavailable", async () => {
                 const fileId = (0, utils_1.newid)();
+                const chunkHashes = ["missing_chunk_hash"];
+                const fileHash = (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(chunkHashes)));
                 const metadata = {
                     fileId,
                     name: "missing-chunk.txt",
                     fileSize: 50,
-                    fileHash: "hash123",
-                    chunkHashes: ["missing_chunk_hash"],
+                    fileHash,
+                    chunkHashes,
                 };
                 // Insert file metadata without storing the actual chunk
                 await fileTable.dataSource.insert(metadata);
                 // This should return null when the chunk can't be found
-                // instead of throwing an error or hanging
                 const result = await fileTable.getFileContents(fileId);
                 expect(result).toBeNull();
             });
+            it("should throw when fileHash does not match chunk hashes", async () => {
+                const fileId = (0, utils_1.newid)();
+                const data = new Uint8Array(Buffer.from("Valid content", "utf8"));
+                const metadata = {
+                    fileId,
+                    name: "tampered.txt",
+                    fileSize: data.length,
+                    mimeType: "text/plain",
+                };
+                // Save file normally to get valid chunks on disk
+                const saved = await fileTable.saveFile(metadata, data);
+                // Tamper with the fileHash in the database record
+                const tamperedRecord = {
+                    ...saved,
+                    fileHash: "tampered-hash-value",
+                };
+                await fileTable.dataSource.save(tamperedRecord);
+                // Reading should throw a file integrity error
+                await expect(fileTable.getFileContents(fileId)).rejects.toThrow("File integrity check failed");
+            });
+            it("should skip fileHash verification when skipVerification is true", async () => {
+                const fileId = (0, utils_1.newid)();
+                const data = new Uint8Array(Buffer.from("Valid content", "utf8"));
+                const metadata = {
+                    fileId,
+                    name: "skip-verify.txt",
+                    fileSize: data.length,
+                    mimeType: "text/plain",
+                };
+                // Save file normally to get valid chunks on disk
+                const saved = await fileTable.saveFile(metadata, data);
+                // Tamper with the fileHash in the database record
+                const tamperedRecord = {
+                    ...saved,
+                    fileHash: "tampered-hash-value",
+                };
+                await fileTable.dataSource.save(tamperedRecord);
+                // Reading with skipVerification should succeed
+                const result = await fileTable.getFileContents(fileId, { skipVerification: true });
+                expect(result).not.toBeNull();
+                expect(new Uint8Array(result)).toEqual(data);
+            });
         });
         describe("Round-trip streaming", () => {
             it("should write and read back identical data using streams", async () => {

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

@@ -1,14 +1,14 @@
 /**
  * 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.
+ * Each device resolves which package version to run from the shared group
+ * package settings plus optional device-local prefs. When an admin device
+ * upgrades a non-dev version while following group settings, the shared
+ * `IPackage.activePackageVersionId` advances so the group stays aligned.
  */
 import type { DataContext } from "../context/data-context";
 import { type IPackageVersion } from "./package-versions";
-import type { IPackage } from "./packages";
+import { type IPackage } from "./packages";
 import { type PersistentVar } from "./persistent-vars";
 /**
  * Device-local preferences for a single package. Stored in a `groupDeviceVar`
@@ -68,6 +68,7 @@ export interface IEffectivePackagePrefs {
  * resolver and by UI components that need to reflect device behavior.
  */
 export declare function getEffectivePackagePrefs(pkg: IPackage, devicePrefs: IDevicePackagePrefs | undefined): IEffectivePackagePrefs;
+/** Result of a device-level package version resolution attempt. */
 export interface IResolveResult {
     /** Whether a package was successfully loaded */
     loaded: boolean;
@@ -90,3 +91,10 @@ export declare function resolveDevicePackageVersion(pkg: IPackage, dataContext:
     force?: boolean;
     localPath?: string;
 }): Promise<IResolveResult>;
+/**
+ * Returns true when the device has an explicit follow-policy override
+ * (`followRange`, `followTags`, or `pinned`). Used by the UI to drive the
+ * "Override on this device" toggle and by the resolver to decide whether
+ * to advance the group-level active version on upgrade.
+ */
+export declare function hasDeviceFollowOverride(prefs: IDevicePackagePrefs | undefined): boolean;

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

@@ -2,19 +2,23 @@
 /**
  * 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.
+ * Each device resolves which package version to run from the shared group
+ * package settings plus optional device-local prefs. When an admin device
+ * upgrades a non-dev version while following group settings, the shared
+ * `IPackage.activePackageVersionId` advances so the group stays aligned.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.packagePrefsVar = packagePrefsVar;
 exports.updatePackagePrefs = updatePackagePrefs;
 exports.getEffectivePackagePrefs = getEffectivePackagePrefs;
 exports.resolveDevicePackageVersion = resolveDevicePackageVersion;
+exports.hasDeviceFollowOverride = hasDeviceFollowOverride;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const assistants_1 = require("./assistants");
+const group_member_roles_1 = require("./group-member-roles");
+const group_permissions_1 = require("./group-permissions");
 const package_versions_1 = require("./package-versions");
+const packages_1 = require("./packages");
 const persistent_vars_1 = require("./persistent-vars");
 const workflows_1 = require("./workflows");
 /**
@@ -129,6 +133,17 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
             .get(effectiveActivePvId)
             .catch(() => undefined);
     }
+    // Dev versions are intentionally local working versions. If a device is
+    // currently running dev, keep loading that exact PV until the user manually
+    // activates a non-dev version.
+    if (activePv?.versionTag === "dev") {
+        const instance = await dataContext.packageLoader.loadPackage(pkg, {
+            force: opts?.force,
+            localPath: opts?.localPath,
+            packageVersionId: effectiveActivePvId,
+        });
+        return { loaded: !!instance, pv: activePv, upgraded: false };
+    }
     // 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;
@@ -178,9 +193,41 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         }
         return { loaded: false, upgraded: false };
     }
-    // Load succeeded - install assistants/workflows, then update device prefs
+    // Load succeeded - install assistants/workflows, then persist the activation
+    // either as a group-level active version or as device-local state.
     await installPackageContents(dataContext, pkg, instance);
-    await updatePackagePrefs(pkg.packageId, { activePackageVersionId: bestPv.packageVersionId }, dataContext);
+    // When the device is following group settings (no device-level follow
+    // override) and the upgraded version is non-dev, also advance the group's
+    // activePackageVersionId so other devices stay in sync. Only admin+ users
+    // are allowed to write to the Packages record.
+    let advancedGroupActiveVersion = false;
+    if (bestPv.versionTag !== "dev" && !hasDeviceFollowOverride(rawPrefs)) {
+        try {
+            const groupId = dataContext.groupId;
+            if (groupId) {
+                const userCtx = await (0, user_context_singleton_1.getUserContext)();
+                const role = await (0, group_permissions_1.getUserRole)(groupId, userCtx.userId);
+                if (role >= group_member_roles_1.GroupMemberRole.Admin) {
+                    const freshPkg = await (0, packages_1.Packages)(dataContext).get(pkg.packageId);
+                    if (freshPkg) {
+                        if (freshPkg.activePackageVersionId !== bestPv.packageVersionId) {
+                            freshPkg.activePackageVersionId = bestPv.packageVersionId;
+                            await (0, packages_1.Packages)(dataContext).signAndSave(freshPkg);
+                        }
+                        advancedGroupActiveVersion = true;
+                    }
+                }
+            }
+        }
+        catch {
+            // Non-critical: personal contexts have no group, signature checks may
+            // fail for non-admins. Swallow and continue — the device upgrade
+            // already succeeded.
+        }
+    }
+    await updatePackagePrefs(pkg.packageId, {
+        activePackageVersionId: advancedGroupActiveVersion ? undefined : bestPv.packageVersionId,
+    }, dataContext);
     return { loaded: true, pv: bestPv, upgraded: true };
 }
 /**
@@ -197,6 +244,17 @@ async function installPackageContents(dataContext, pkg, instance) {
     ];
     await Promise.all(saves);
 }
+/**
+ * Returns true when the device has an explicit follow-policy override
+ * (`followRange`, `followTags`, or `pinned`). Used by the UI to drive the
+ * "Override on this device" toggle and by the resolver to decide whether
+ * to advance the group-level active version on upgrade.
+ */
+function hasDeviceFollowOverride(prefs) {
+    if (!prefs)
+        return false;
+    return prefs.followRange != null || prefs.followTags != null || prefs.pinned != null;
+}
 /** Convert `IPackage.versionFollowRange` to the resolver's range type. */
 function rangeFromPkg(pkg) {
     const r = pkg.versionFollowRange;

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

@@ -1,8 +1,4 @@
 /**
  * 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

@@ -1,10 +1,6 @@
 "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");
@@ -12,6 +8,8 @@ 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 group_member_roles_1 = require("./group-member-roles");
+const groups_1 = require("./groups");
 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");
@@ -51,6 +49,11 @@ function groupDc() {
     dc.setAsDefault();
     return dc;
 }
+function freshGroupDc() {
+    const dc = userContext.getDataContext((0, utils_1.newid)());
+    dc.setAsDefault();
+    return dc;
+}
 function makePV(packageId, overrides = {}) {
     return {
         packageVersionId: (0, utils_1.newid)(),
@@ -72,6 +75,7 @@ function makePkg(overrides = {}) {
         name: "test-package",
         description: "test",
         createdBy: testUserId,
+        publishPublicKey: "",
         signature: "",
         ...overrides,
     };
@@ -84,6 +88,7 @@ beforeAll(async () => {
     userContext.deviceId((0, utils_1.newid)());
     (0, user_context_singleton_1.setUserContext)(userContext);
     packages_1.PackagesTable.isPassthrough = true;
+    packages_1.PackagesTable.enablePackageSigning((pkg) => pkg);
     package_versions_1.PackageVersionsTable.isPassthrough = true;
 });
 afterAll(async () => {
@@ -95,7 +100,7 @@ afterAll(async () => {
 afterEach(() => {
     jest.restoreAllMocks();
 });
-describe("resolveDevicePackageVersion — known gaps (expected to fail until fixed)", () => {
+describe("resolveDevicePackageVersion — regression coverage", () => {
     it("does not auto-upgrade when IPackage.versionFollowRange is pinned (no device prefs)", async () => {
         const dc = groupDc();
         const packageId = (0, utils_1.newid)();
@@ -176,6 +181,123 @@ describe("resolveDevicePackageVersion — known gaps (expected to fail until fix
     });
 });
 describe("resolveDevicePackageVersion — expected behavior (control)", () => {
+    it("advances the group active version when an admin auto-upgrades without device overrides", async () => {
+        const dc = freshGroupDc();
+        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",
+            followVersionTags: "stable",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        jest.spyOn(dc.packageLoader, "loadPackage").mockResolvedValue({ packageId });
+        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 savedPkg = await (0, packages_1.Packages)(dc).get(packageId);
+        expect(savedPkg?.activePackageVersionId).toBe(stableV2.packageVersionId);
+        const pvar = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await pvar.loadingPromise;
+        expect(pvar()?.activePackageVersionId).toBeUndefined();
+    });
+    it("keeps an auto-upgrade device-local when device follow overrides are enabled", async () => {
+        const dc = freshGroupDc();
+        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",
+            followVersionTags: "stable",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { followRange: "latest", followTags: "stable" }, dc);
+        jest.spyOn(dc.packageLoader, "loadPackage").mockResolvedValue({ packageId });
+        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 savedPkg = await (0, packages_1.Packages)(dc).get(packageId);
+        expect(savedPkg?.activePackageVersionId).toBe(stablePv.packageVersionId);
+        const pvar = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await pvar.loadingPromise;
+        expect(pvar()?.activePackageVersionId).toBe(stableV2.packageVersionId);
+    });
+    it("keeps an auto-upgrade device-local when the device user is not a group admin", async () => {
+        const dc = freshGroupDc();
+        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);
+        await (0, groups_1.Groups)(userContext.userDataContext).save({
+            groupId: dc.dataContextId,
+            name: "Non-admin resolver test",
+            description: "test",
+            founderUserId: (0, utils_1.newid)(),
+            publicRole: group_member_roles_1.GroupMemberRole.Writer,
+            publicKey: "",
+            publicBoxKey: "",
+            signature: "",
+        });
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+            versionFollowRange: "latest",
+            followVersionTags: "stable",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        jest.spyOn(dc.packageLoader, "loadPackage").mockResolvedValue({ packageId });
+        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 savedPkg = await (0, packages_1.Packages)(dc).get(packageId);
+        expect(savedPkg?.activePackageVersionId).toBe(stablePv.packageVersionId);
+        const pvar = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await pvar.loadingPromise;
+        expect(pvar()?.activePackageVersionId).toBe(stableV2.packageVersionId);
+    });
+    it("keeps a local dev activation on this device without turning override on", async () => {
+        const dc = freshGroupDc();
+        const packageId = (0, utils_1.newid)();
+        const stablePv = makePV(packageId, { version: "1.0.0", versionTag: "stable" });
+        const devPv = makePV(packageId, { version: "1.2.0", versionTag: "dev" });
+        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(devPv);
+        await (0, package_versions_1.PackageVersions)(dc).save(stableV2);
+        const pkg = makePkg({
+            packageId,
+            activePackageVersionId: stablePv.packageVersionId,
+            versionFollowRange: "latest",
+            followVersionTags: "stable",
+        });
+        await (0, packages_1.Packages)(dc).save(pkg);
+        await (0, package_version_resolver_1.updatePackagePrefs)(packageId, { activePackageVersionId: devPv.packageVersionId }, dc);
+        const pvar = (0, package_version_resolver_1.packagePrefsVar)(packageId, dc);
+        await pvar.loadingPromise;
+        expect((0, package_version_resolver_1.hasDeviceFollowOverride)(pvar())).toBe(false);
+        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(result.pv?.packageVersionId).toBe(devPv.packageVersionId);
+        expect(loadedPvIds).toEqual([devPv.packageVersionId]);
+        const savedPkg = await (0, packages_1.Packages)(dc).get(packageId);
+        expect(savedPkg?.activePackageVersionId).toBe(stablePv.packageVersionId);
+        expect(pvar()?.activePackageVersionId).toBe(devPv.packageVersionId);
+    });
     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)();

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

@@ -30,6 +30,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }>, "many">>;
+    packageAuthorSignature: z.ZodOptional<z.ZodString>;
     history: z.ZodOptional<z.ZodArray<z.ZodObject<{
         action: z.ZodString;
         by: z.ZodString;
@@ -76,6 +77,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }[] | undefined;
+    packageAuthorSignature?: string | undefined;
 }, {
     version: string;
     signature: string;
@@ -103,6 +105,7 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }[] | undefined;
+    packageAuthorSignature?: string | undefined;
 }>;
 export type IPackageVersion = z.infer<typeof schema>;
 export declare class PackageVersionsTable extends Table<IPackageVersion> {

package/dist/data/package-versions.js

@@ -66,6 +66,11 @@ const schema = zod_1.z.object({
         .array()
         .optional()
         .describe("The app navigation items that this version provides"),
+    packageAuthorSignature: zod_1.z
+        .string()
+        .optional()
+        .describe("Publisher's Ed25519 detached signature over the author-signed payload. " +
+        "Enables cross-group trust verification without needing the original source."),
     history: zod_1.z
         .array(zod_1.z.object({
         action: zod_1.z.string().describe("created | promoted:beta | promoted:stable | activated"),