@peers-app/peers-sdk 0.18.3 → 0.18.5

package/dist/contracts/__tests__/builder.test.js

@@ -57,7 +57,7 @@ describe("definePackage", () => {
         expect(contract.version).toBe(1);
         expect(contract.name).toBe("Tasks");
         expect(contract.description).toBe("");
-        expect(contract.devTag).toBeUndefined();
+        expect(contract.devTag).toBe("dev");
         expect(contract.tables).toHaveLength(1);
         expect(contract.tables[0].name).toBe("Tasks");
         expect(contract.tables[0].fields).toHaveLength(2);
@@ -163,11 +163,11 @@ describe("definePackage", () => {
         expect(result.assistants).toEqual([assistant]);
         expect(result.appNavs).toEqual([nav]);
     });
-    it("supports devTag on contracts", () => {
+    it("always assigns devTag 'dev' to contracts from definePackage", () => {
         const devContractId = (0, utils_1.newid)();
         const result = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = TEST_PKG_ID;
-            const c = pkg.contract(devContractId, 1, "Dev Contract", "dev");
+            const c = pkg.contract(devContractId, 1, "Dev Contract");
             c.tables = [
                 {
                     metaData: {
@@ -227,12 +227,11 @@ describe("definePackage", () => {
         expect(result.contracts[0].name).toBe("Human-Readable Name");
         expect(result.contracts[0].description).toBe("");
     });
-    it("includes packageId, version, and versionTag in the result", () => {
+    it("includes packageId and version in the result", () => {
         const cid = (0, utils_1.newid)();
         const result = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = TEST_PKG_ID;
             pkg.version = "1.2.3";
-            pkg.versionTag = "dev";
             const c = pkg.contract(cid, 1, "C");
             c.tables = [
                 {
@@ -247,9 +246,8 @@ describe("definePackage", () => {
         });
         expect(result.packageId).toBe(TEST_PKG_ID);
         expect(result.version).toBe("1.2.3");
-        expect(result.versionTag).toBe("dev");
     });
-    it("leaves version and versionTag undefined when not set", () => {
+    it("leaves version undefined when not set", () => {
         const cid = (0, utils_1.newid)();
         const result = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = TEST_PKG_ID;
@@ -267,7 +265,6 @@ describe("definePackage", () => {
         });
         expect(result.packageId).toBe(TEST_PKG_ID);
         expect(result.version).toBeUndefined();
-        expect(result.versionTag).toBeUndefined();
     });
 });
 describe("definePackage — error cases", () => {

package/dist/contracts/__tests__/integration.test.js

@@ -266,7 +266,7 @@ describe("Package Contracts — integration", () => {
         // Define a broken fancy tasks that is missing the taskCount observable
         const brokenFancy = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = (0, utils_1.newid)();
-            const fancy = pkg.contract(FANCY_TASKS_CONTRACT_ID, 1, "Broken Fancy Tasks", "dev");
+            const fancy = pkg.contract(FANCY_TASKS_CONTRACT_ID, 1, "Broken Fancy Tasks");
             fancy.alsoImplements(TASKS_CONTRACT_ID, 1);
             fancy.tables = [
                 {

package/dist/contracts/builder.d.ts

@@ -11,7 +11,6 @@ export declare class ContractBuilder {
     readonly version: number;
     readonly name: string;
     readonly description?: string | undefined;
-    readonly devTag?: "dev" | undefined;
     private _tables;
     private _tools;
     private _observables;
@@ -20,7 +19,7 @@ export declare class ContractBuilder {
     private _toolInstances;
     /** Full table definitions for this contract (used by the install flow). */
     private _tableDefinitions;
-    constructor(contractId: string, version: number, name: string, description?: string | undefined, devTag?: "dev" | undefined);
+    constructor(contractId: string, version: number, name: string, description?: string | undefined);
     set tables(defs: IExtractableTableDef[]);
     get tables(): IExtractableTableDef[];
     set tools(instances: IExtractableToolInstance[]);
@@ -61,7 +60,6 @@ export declare class ContractBuilder {
 export declare class PackageBuilder {
     private _packageId?;
     private _version?;
-    private _versionTag?;
     private _contracts;
     private _consumes;
     /** Package-level assistants (not part of any contract). */
@@ -74,19 +72,19 @@ export declare class PackageBuilder {
     /** Semantic version string (e.g. "1.0.0"). Typically imported from package.json at build time. */
     set version(v: string);
     get version(): string | undefined;
-    /** Version channel tag (e.g. "dev", "beta", "stable"). */
-    set versionTag(tag: string);
-    get versionTag(): string | undefined;
     /**
      * Define (and implement) a contract at the given version.
      * Returns a `ContractBuilder` for assigning tables, tools, and observables.
      *
+     * Contracts are always registered as `devTag: "dev"` from code. The platform
+     * finalizes contracts (removes devTag) when the package version is promoted
+     * to stable. Previously-frozen contracts are preserved by the installer.
+     *
      * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
      * @param version - Positive integer version number.
      * @param name - Human-readable contract name. This is the meaningful identifier that creators can change over time.
-     * @param devTag - Set to `"dev"` while the contract shape is still mutable.
      */
-    contract(contractId: string, version: number, name: string, devTag?: "dev"): ContractBuilder;
+    contract(contractId: string, version: number, name: string): ContractBuilder;
     /**
      * Declare a dependency on another package's contract.
      */

package/dist/contracts/builder.js

@@ -14,7 +14,6 @@ class ContractBuilder {
     version;
     name;
     description;
-    devTag;
     _tables = [];
     _tools = [];
     _observables = [];
@@ -23,12 +22,11 @@ class ContractBuilder {
     _toolInstances = [];
     /** Full table definitions for this contract (used by the install flow). */
     _tableDefinitions = [];
-    constructor(contractId, version, name, description, devTag) {
+    constructor(contractId, version, name, description) {
         this.contractId = contractId;
         this.version = version;
         this.name = name;
         this.description = description;
-        this.devTag = devTag;
     }
     set tables(defs) {
         this._tables = defs;
@@ -78,7 +76,7 @@ class ContractBuilder {
             definition: {
                 contractId: this.contractId,
                 version: this.version,
-                devTag: this.devTag,
+                devTag: "dev",
                 name: this.name,
                 description: this.description ?? "",
                 tables: this._tables.map(extract_1.extractTableShape),
@@ -104,7 +102,6 @@ exports.ContractBuilder = ContractBuilder;
 class PackageBuilder {
     _packageId;
     _version;
-    _versionTag;
     _contracts = [];
     _consumes = [];
     /** Package-level assistants (not part of any contract). */
@@ -128,23 +125,19 @@ class PackageBuilder {
     get version() {
         return this._version;
     }
-    /** Version channel tag (e.g. "dev", "beta", "stable"). */
-    set versionTag(tag) {
-        this._versionTag = tag;
-    }
-    get versionTag() {
-        return this._versionTag;
-    }
     /**
      * Define (and implement) a contract at the given version.
      * Returns a `ContractBuilder` for assigning tables, tools, and observables.
      *
+     * Contracts are always registered as `devTag: "dev"` from code. The platform
+     * finalizes contracts (removes devTag) when the package version is promoted
+     * to stable. Previously-frozen contracts are preserved by the installer.
+     *
      * @param contractId - Must be a valid peer ID (25-char alphanumeric from `newid()`).
      * @param version - Positive integer version number.
      * @param name - Human-readable contract name. This is the meaningful identifier that creators can change over time.
-     * @param devTag - Set to `"dev"` while the contract shape is still mutable.
      */
-    contract(contractId, version, name, devTag) {
+    contract(contractId, version, name) {
         if (!(0, utils_1.isid)(contractId)) {
             throw new Error(`contractId must be a valid peer ID (25-char alphanumeric), got "${contractId}"`);
         }
@@ -155,7 +148,7 @@ class PackageBuilder {
         if (existing) {
             throw new Error(`Duplicate contract: ${contractId} v${version} is already defined in this package`);
         }
-        const builder = new ContractBuilder(contractId, version, name, undefined, devTag);
+        const builder = new ContractBuilder(contractId, version, name);
         this._contracts.push(builder);
         return builder;
     }
@@ -192,7 +185,6 @@ class PackageBuilder {
         return {
             packageId: this._packageId,
             version: this._version,
-            versionTag: this._versionTag,
             contracts,
             consumes: [...this._consumes],
             alsoImplements: alsoImplementsMap,

package/dist/contracts/contract-providers.table.d.ts

@@ -16,15 +16,15 @@ declare const schema: z.ZodObject<{
     registeredAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     version: number;
-    contractProviderId: string;
     contractId: string;
+    contractProviderId: string;
     providerPackageId: string;
     isActive: boolean;
     registeredAt: string;
 }, {
     version: number;
-    contractProviderId: string;
     contractId: string;
+    contractProviderId: string;
     providerPackageId: string;
     isActive: boolean;
     registeredAt: string;

package/dist/contracts/registry.d.ts

@@ -41,6 +41,10 @@ export declare class ContractRegistry {
     getProviderPackageId(contractId: string, version: number): string | undefined;
     /** Get the stored contract definition (regardless of active provider). */
     getDefinition(contractId: string, version: number): IContractDefinition | undefined;
+    /** Replace the stored definition for a contract (e.g. to freeze a dev contract). */
+    updateDefinition(contractId: string, version: number, definition: IContractDefinition): void;
+    /** Get all contract keys provided by a package. */
+    getContractKeysForPackage(packageId: string): string[];
     /**
      * Remove all contracts provided by a package. If the removed package was
      * the active provider for a contract, the next registered provider (if any)

package/dist/contracts/registry.js

@@ -102,6 +102,22 @@ class ContractRegistry {
     getDefinition(contractId, version) {
         return this.definitions.get((0, types_1.contractKey)(contractId, version));
     }
+    /** Replace the stored definition for a contract (e.g. to freeze a dev contract). */
+    updateDefinition(contractId, version, definition) {
+        const key = (0, types_1.contractKey)(contractId, version);
+        this.definitions.set(key, definition);
+        // Also update any active/all providers that reference this definition
+        const providers = this.allProviders.get(key);
+        if (providers) {
+            for (const p of providers) {
+                p.definition = definition;
+            }
+        }
+    }
+    /** Get all contract keys provided by a package. */
+    getContractKeysForPackage(packageId) {
+        return this.packageContracts.get(packageId) ?? [];
+    }
     /**
      * Remove all contracts provided by a package. If the removed package was
      * the active provider for a contract, the next registered provider (if any)

package/dist/contracts/types.d.ts

@@ -64,8 +64,6 @@ export interface IPackageDefinitionResult {
     packageId: string;
     /** Semantic version string baked in from package.json at build time. */
     version?: string;
-    /** Version channel tag (e.g. "dev", "beta", "stable"). */
-    versionTag?: string;
     /** Contracts this package defines and provides. */
     contracts: IContractDefinition[];
     /** Contracts this package depends on. */

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

@@ -1,7 +1,14 @@
 import type { IPackage } from "./packages";
 /**
- * Verifies that a package update signature is valid, throws on invalid signature
+ * Verifies that a package update signature is valid.
+ *
+ * Writers can create or update packages that have a dev active version.
+ * Admins are required for packages with beta or stable active versions.
+ *
  * @param packageObj The package record to verify
+ * @param opts.isDevVersion When true, allows Writer role (for dev version operations)
  * @throws Error if signature is invalid or unauthorized
  */
-export declare function verifyPackageSignature(packageObj: IPackage, groupId: string): Promise<void>;
+export declare function verifyPackageSignature(packageObj: IPackage, groupId: string, opts?: {
+    isDevVersion?: boolean;
+}): Promise<void>;

package/dist/data/package-permissions.js

@@ -4,15 +4,23 @@ exports.verifyPackageSignature = verifyPackageSignature;
 const keys_1 = require("../keys");
 const group_permissions_1 = require("./group-permissions");
 /**
- * Verifies that a package update signature is valid, throws on invalid signature
+ * Verifies that a package update signature is valid.
+ *
+ * Writers can create or update packages that have a dev active version.
+ * Admins are required for packages with beta or stable active versions.
+ *
  * @param packageObj The package record to verify
+ * @param opts.isDevVersion When true, allows Writer role (for dev version operations)
  * @throws Error if signature is invalid or unauthorized
  */
-async function verifyPackageSignature(packageObj, groupId) {
+async function verifyPackageSignature(packageObj, groupId, opts) {
     (0, keys_1.verifyObjectSignature)(packageObj);
     const signerPublicKey = (0, keys_1.getPublicKeyFromObjectSignature)(packageObj) ?? "";
     const signerRole = await (0, group_permissions_1.getUserRoleFromPublicKey)(groupId, signerPublicKey);
-    if (signerRole < group_permissions_1.GroupMemberRole.Admin) {
-        throw new Error("Only group admins can create or update packages");
+    const requiredRole = opts?.isDevVersion ? group_permissions_1.GroupMemberRole.Writer : group_permissions_1.GroupMemberRole.Admin;
+    if (signerRole < requiredRole) {
+        throw new Error(opts?.isDevVersion
+            ? "Only group writers or above can create or update dev packages"
+            : "Only group admins can create or update packages");
     }
 }

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

@@ -1,7 +1,14 @@
+import { GroupMemberRole } from "./group-permissions";
 import type { IPackageVersion } from "./package-versions";
 /**
- * Verifies that a package version update signature is valid, throws on invalid signature
+ * Verifies that a package version update signature is valid.
+ *
+ * Dev versions (`versionTag === "dev"`) require Writer role.
+ * Beta and stable versions require Admin role.
+ *
  * @param packageVersion The package version record to verify
+ * @param groupId The group context to check roles against
+ * @param signerRole Optional pre-resolved role (skips `getUserRoleFromPublicKey` lookup; useful in tests)
  * @throws Error if signature is invalid or unauthorized
  */
-export declare function verifyPackageVersionSignature(packageVersion: IPackageVersion, groupId: string): Promise<void>;
+export declare function verifyPackageVersionSignature(packageVersion: IPackageVersion, groupId: string, signerRole?: GroupMemberRole): Promise<void>;

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

@@ -4,15 +4,27 @@ exports.verifyPackageVersionSignature = verifyPackageVersionSignature;
 const keys_1 = require("../keys");
 const group_permissions_1 = require("./group-permissions");
 /**
- * Verifies that a package version update signature is valid, throws on invalid signature
+ * Verifies that a package version update signature is valid.
+ *
+ * Dev versions (`versionTag === "dev"`) require Writer role.
+ * Beta and stable versions require Admin role.
+ *
  * @param packageVersion The package version record to verify
+ * @param groupId The group context to check roles against
+ * @param signerRole Optional pre-resolved role (skips `getUserRoleFromPublicKey` lookup; useful in tests)
  * @throws Error if signature is invalid or unauthorized
  */
-async function verifyPackageVersionSignature(packageVersion, groupId) {
+async function verifyPackageVersionSignature(packageVersion, groupId, signerRole) {
     (0, keys_1.verifyObjectSignature)(packageVersion);
-    const signerPublicKey = (0, keys_1.getPublicKeyFromObjectSignature)(packageVersion) ?? "";
-    const signerRole = await (0, group_permissions_1.getUserRoleFromPublicKey)(groupId, signerPublicKey);
-    if (signerRole < group_permissions_1.GroupMemberRole.Admin) {
-        throw new Error("Only group admins can create or update package versions");
+    if (signerRole === undefined) {
+        const signerPublicKey = (0, keys_1.getPublicKeyFromObjectSignature)(packageVersion) ?? "";
+        signerRole = await (0, group_permissions_1.getUserRoleFromPublicKey)(groupId, signerPublicKey);
+    }
+    const isDevVersion = packageVersion.versionTag === "dev";
+    const requiredRole = isDevVersion ? group_permissions_1.GroupMemberRole.Writer : group_permissions_1.GroupMemberRole.Admin;
+    if (signerRole < requiredRole) {
+        throw new Error(isDevVersion
+            ? "Only group writers or above can create dev package versions"
+            : "Only group admins can create or update beta/stable package versions");
     }
 }

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

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

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_member_roles_1 = require("./group-member-roles");
+const package_version_permissions_1 = require("./package-version-permissions");
+describe("Package Version Permissions", () => {
+    const writerKeys = (0, keys_1.newKeys)();
+    const adminKeys = (0, keys_1.newKeys)();
+    function makePV(overrides = {}) {
+        return {
+            packageVersionId: (0, utils_1.newid)(),
+            packageId: (0, utils_1.newid)(),
+            version: "1.0.0",
+            versionTag: "dev",
+            packageVersionHash: "testhash",
+            packageBundleFileId: (0, utils_1.newid)(),
+            packageBundleFileHash: "bundlehash",
+            signature: "",
+            createdBy: (0, utils_1.newid)(),
+            createdAt: new Date().toISOString(),
+            ...overrides,
+        };
+    }
+    describe("dev versions", () => {
+        it("allows Writer to sign a dev version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "dev" }), writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Writer)).resolves.toBeUndefined();
+        });
+        it("allows Admin to sign a dev version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "dev" }), adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Admin)).resolves.toBeUndefined();
+        });
+        it("rejects Reader signing a dev version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "dev" }), writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Reader)).rejects.toThrow("Only group writers or above");
+        });
+    });
+    describe("beta versions", () => {
+        it("allows Admin to sign a beta version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "beta" }), adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Admin)).resolves.toBeUndefined();
+        });
+        it("allows Owner to sign a beta version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "beta" }), adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Owner)).resolves.toBeUndefined();
+        });
+        it("rejects Writer signing a beta version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "beta" }), writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Writer)).rejects.toThrow("Only group admins can create or update beta/stable");
+        });
+    });
+    describe("stable versions", () => {
+        it("allows Admin to sign a stable version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "stable" }), adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Admin)).resolves.toBeUndefined();
+        });
+        it("rejects Writer signing a stable version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "stable" }), writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Writer)).rejects.toThrow("Only group admins can create or update beta/stable");
+        });
+    });
+    describe("promotion scenarios (dev → beta → stable)", () => {
+        it("rejects Writer promoting dev to beta", async () => {
+            const devPV = makePV({ versionTag: "dev" });
+            const promoted = { ...devPV, versionTag: "beta" };
+            const signed = (0, keys_1.addSignatureToObject)(promoted, writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(signed, "test-group", group_member_roles_1.GroupMemberRole.Writer)).rejects.toThrow("Only group admins can create or update beta/stable");
+        });
+        it("rejects Writer promoting dev to stable", async () => {
+            const devPV = makePV({ versionTag: "dev" });
+            const promoted = { ...devPV, versionTag: "stable" };
+            const signed = (0, keys_1.addSignatureToObject)(promoted, writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(signed, "test-group", group_member_roles_1.GroupMemberRole.Writer)).rejects.toThrow("Only group admins can create or update beta/stable");
+        });
+        it("rejects Writer promoting beta to stable", async () => {
+            const betaPV = makePV({ versionTag: "beta" });
+            const promoted = { ...betaPV, versionTag: "stable" };
+            const signed = (0, keys_1.addSignatureToObject)(promoted, writerKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(signed, "test-group", group_member_roles_1.GroupMemberRole.Writer)).rejects.toThrow("Only group admins can create or update beta/stable");
+        });
+        it("allows Admin promoting dev to beta", async () => {
+            const devPV = makePV({ versionTag: "dev" });
+            const promoted = { ...devPV, versionTag: "beta" };
+            const signed = (0, keys_1.addSignatureToObject)(promoted, adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(signed, "test-group", group_member_roles_1.GroupMemberRole.Admin)).resolves.toBeUndefined();
+        });
+        it("allows Admin promoting beta to stable", async () => {
+            const betaPV = makePV({ versionTag: "beta" });
+            const promoted = { ...betaPV, versionTag: "stable" };
+            const signed = (0, keys_1.addSignatureToObject)(promoted, adminKeys.secretKey);
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(signed, "test-group", group_member_roles_1.GroupMemberRole.Admin)).resolves.toBeUndefined();
+        });
+    });
+    describe("signature tampering", () => {
+        it("rejects a tampered package version", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "dev" }), writerKeys.secretKey);
+            pv.version = "9.9.9";
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Admin)).rejects.toThrow();
+        });
+        it("rejects a version with tag changed after signing", async () => {
+            const pv = (0, keys_1.addSignatureToObject)(makePV({ versionTag: "dev" }), writerKeys.secretKey);
+            pv.versionTag = "stable";
+            await expect((0, package_version_permissions_1.verifyPackageVersionSignature)(pv, "test-group", group_member_roles_1.GroupMemberRole.Admin)).rejects.toThrow();
+        });
+    });
+});

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

@@ -30,6 +30,22 @@ declare const schema: z.ZodObject<{
         navigationPath: string;
         displayName?: string | undefined;
     }>, "many">>;
+    history: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodString;
+        by: z.ZodString;
+        at: z.ZodString;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        action: string;
+        signature: string;
+        by: string;
+    }, {
+        at: string;
+        action: string;
+        signature: string;
+        by: string;
+    }>, "many">>;
     signature: z.ZodString;
     createdBy: z.ZodEffects<z.ZodString, string, string>;
     createdAt: z.ZodString;
@@ -43,6 +59,12 @@ declare const schema: z.ZodObject<{
     packageBundleFileHash: string;
     createdBy: string;
     createdAt: string;
+    history?: {
+        at: string;
+        action: string;
+        signature: string;
+        by: string;
+    }[] | undefined;
     versionTag?: string | undefined;
     routesBundleFileId?: string | undefined;
     routesBundleFileHash?: string | undefined;
@@ -64,6 +86,12 @@ declare const schema: z.ZodObject<{
     packageBundleFileHash: string;
     createdBy: string;
     createdAt: string;
+    history?: {
+        at: string;
+        action: string;
+        signature: string;
+        by: string;
+    }[] | undefined;
     versionTag?: string | undefined;
     routesBundleFileId?: string | undefined;
     routesBundleFileHash?: string | undefined;
@@ -88,13 +116,25 @@ export declare class PackageVersionsTable extends Table<IPackageVersion> {
 }
 export declare function PackageVersions(dataContext?: DataContext): PackageVersionsTable;
 /**
- * Compute a hash combining the bundle file hashes to uniquely identify this version's content.
+ * Compute a content hash from bundle file hashes. The hash represents code
+ * content only — `versionTag` is intentionally excluded so the same code
+ * produces the same hash regardless of its promotion level (dev/beta/stable).
+ *
+ * @deprecated The `versionTag` parameter is accepted for backward compatibility
+ * but ignored. It will be removed in a future release.
  */
-export declare function computePackageVersionHash(version: string, versionTag: string, packageBundleFileHash: string, routesBundleFileHash?: string, uiBundleFileHash?: string): string;
+export declare function computePackageVersionHash(version: string, _versionTag: string, packageBundleFileHash: string, routesBundleFileHash?: string, uiBundleFileHash?: string): string;
 export declare function isVersionInRange(activeVersion: string, incomingVersion: string, range: "pinned" | "patch" | "minor" | "latest"): boolean;
 /**
  * Returns true if incomingVersion is strictly newer than activeVersion (semver comparison).
  */
 export declare function isNewerVersion(activeVersion: string, incomingVersion: string): boolean;
+/**
+ * Determines whether an incoming version tag matches the device's follow policy.
+ *
+ * `"dev"` tags are **never** auto-matched unless the device explicitly opts in
+ * via `deviceVersionTag: "dev"`. This prevents local development builds from
+ * auto-activating on other devices in the group.
+ */
 export declare function doesTagMatch(activeVersionTag: string | undefined, incomingVersionTag: string | undefined, followVersionTags: string | undefined, deviceVersionTag: string | undefined): boolean;
 export {};

package/dist/data/package-versions.js

@@ -66,6 +66,15 @@ const schema = zod_1.z.object({
         .array()
         .optional()
         .describe("The app navigation items that this version provides"),
+    history: zod_1.z
+        .array(zod_1.z.object({
+        action: zod_1.z.string().describe("created | promoted:beta | promoted:stable | activated"),
+        by: zod_1.z.string().describe("Peer ID of the actor"),
+        at: zod_1.z.string().describe("ISO 8601 timestamp"),
+        signature: zod_1.z.string().describe("Actor's signature over the action"),
+    }))
+        .optional()
+        .describe("Audit trail of lifecycle events for this version"),
     signature: zod_1.z.string().describe("The signed hash of this data excluding the signature itself"),
     createdBy: zod_types_1.zodPeerId.describe("The user who created this version"),
     createdAt: zod_1.z.string().describe("ISO timestamp of when this version was created"),
@@ -104,14 +113,7 @@ let PackageVersionsTable = (() => {
                 // users can do whatever they want to package versions in their personal space
                 return super.save(packageVersion, opts);
             }
-            try {
-                await (0, package_version_permissions_1.verifyPackageVersionSignature)(packageVersion, this.groupId);
-            }
-            catch (err) {
-                throw new Error("Package version verification failed.  Did you mean to call `signAndSave`?", {
-                    cause: err,
-                });
-            }
+            await (0, package_version_permissions_1.verifyPackageVersionSignature)(packageVersion, this.groupId);
             return super.save(packageVersion, opts);
         }
         async signAndSave(packageVersion, opts) {
@@ -119,7 +121,7 @@ let PackageVersionsTable = (() => {
                 throw new Error("Package version signing is not enabled. Call PackageVersionsTable.enablePackageVersionSigning(fn) to enable it.");
             }
             packageVersion = await PackageVersionsTable.addSignatureToPackageVersion(packageVersion);
-            return super.save(packageVersion, opts);
+            return this.save(packageVersion, opts);
         }
         static addSignatureToPackageVersion = undefined;
         static enablePackageVersionSigning(fn) {
@@ -137,16 +139,15 @@ function PackageVersions(dataContext) {
     return (0, context_1.getTableContainer)(dataContext).getTable(metaData, schema, PackageVersionsTable);
 }
 /**
- * Compute a hash combining the bundle file hashes to uniquely identify this version's content.
+ * Compute a content hash from bundle file hashes. The hash represents code
+ * content only — `versionTag` is intentionally excluded so the same code
+ * produces the same hash regardless of its promotion level (dev/beta/stable).
+ *
+ * @deprecated The `versionTag` parameter is accepted for backward compatibility
+ * but ignored. It will be removed in a future release.
  */
-function computePackageVersionHash(version, versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) {
-    return (0, keys_1.hashValue)([
-        version,
-        versionTag,
-        packageBundleFileHash,
-        routesBundleFileHash ?? "",
-        uiBundleFileHash ?? "",
-    ].join(":"));
+function computePackageVersionHash(version, _versionTag, packageBundleFileHash, routesBundleFileHash, uiBundleFileHash) {
+    return (0, keys_1.hashValue)([version, packageBundleFileHash, routesBundleFileHash ?? "", uiBundleFileHash ?? ""].join(":"));
 }
 function isVersionInRange(activeVersion, incomingVersion, range) {
     if (range === "pinned")
@@ -173,10 +174,21 @@ function isNewerVersion(activeVersion, incomingVersion) {
         return iMin > aMin;
     return iPat > aPat;
 }
+/**
+ * Determines whether an incoming version tag matches the device's follow policy.
+ *
+ * `"dev"` tags are **never** auto-matched unless the device explicitly opts in
+ * via `deviceVersionTag: "dev"`. This prevents local development builds from
+ * auto-activating on other devices in the group.
+ */
 function doesTagMatch(activeVersionTag, incomingVersionTag, followVersionTags, deviceVersionTag) {
     const inTag = incomingVersionTag || "stable";
+    // Device-level override: only match the exact tag the device requested
     if (deviceVersionTag)
         return inTag === deviceVersionTag;
+    // Dev versions never auto-activate unless explicitly followed
+    if (inTag === "dev")
+        return false;
     if (!followVersionTags) {
         return inTag === (activeVersionTag || "stable");
     }

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

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

package/dist/data/package-versions.test.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const user_context_1 = require("../context/user-context");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_member_roles_1 = require("./group-member-roles");
+const group_members_1 = require("./group-members");
+const groups_1 = require("./groups");
+const sql_data_source_1 = require("./orm/sql.data-source");
+const package_versions_1 = require("./package-versions");
+const users_1 = require("./users");
+// ---------------------------------------------------------------------------
+// In-memory SQLite harness (same pattern as sql.data-source.test.ts)
+// ---------------------------------------------------------------------------
+class DBHarness {
+    _db = null;
+    get db() {
+        if (!this._db) {
+            this._db = new SQLiteDB(":memory:");
+            this._db.pragma("journal_mode = WAL");
+        }
+        return this._db;
+    }
+    async get(sql, params = []) {
+        return this.db.prepare(sql).get(params);
+    }
+    async all(sql, params = []) {
+        return this.db.prepare(sql).all(params);
+    }
+    async exec(sql, params = []) {
+        const result = this.db.prepare(sql).run(params);
+        return { changes: result.changes };
+    }
+    async close() {
+        this._db?.close();
+        this._db = null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+const writerKeys = (0, keys_1.newKeys)();
+const adminKeys = (0, keys_1.newKeys)();
+const testGroupId = (0, utils_1.newid)();
+const writerUserId = (0, utils_1.newid)();
+const adminUserId = (0, utils_1.newid)();
+function makePV(overrides = {}) {
+    return {
+        packageVersionId: (0, utils_1.newid)(),
+        packageId: (0, utils_1.newid)(),
+        version: "1.0.0",
+        versionTag: "dev",
+        packageVersionHash: "testhash",
+        packageBundleFileId: (0, utils_1.newid)(),
+        packageBundleFileHash: "bundlehash",
+        signature: "",
+        createdBy: writerUserId,
+        createdAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Setup: create a real ephemeral UserContext with Users + GroupMembers seeded
+// so that getUserRoleFromPublicKey resolves Writer vs Admin from real data.
+// ---------------------------------------------------------------------------
+let userContext;
+beforeAll(async () => {
+    const db = new DBHarness();
+    const dataSourceFactory = (metaData, schema) => {
+        return new sql_data_source_1.SQLDataSource(db, metaData, schema);
+    };
+    userContext = new user_context_1.UserContext(writerUserId, dataSourceFactory, true);
+    await userContext.loadingPromise;
+    userContext.deviceId((0, utils_1.newid)());
+    (0, user_context_singleton_1.setUserContext)(userContext);
+    const dc = userContext.userDataContext;
+    // Enable passthrough so seeding skips signature checks on Groups/GroupMembers/Users
+    groups_1.GroupsTable.isPassthrough = true;
+    group_members_1.GroupMembersTable.isPassthrough = true;
+    users_1.UsersTable.isPassthrough = true;
+    // Seed the writer user
+    const { Users } = await Promise.resolve().then(() => require("./users"));
+    const writerUser = {
+        userId: writerUserId,
+        name: "Writer User",
+        publicKey: writerKeys.publicKey,
+        publicBoxKey: "",
+        signature: "",
+    };
+    await Users(dc).save(writerUser);
+    // Seed the admin user
+    const adminUser = {
+        userId: adminUserId,
+        name: "Admin User",
+        publicKey: adminKeys.publicKey,
+        publicBoxKey: "",
+        signature: "",
+    };
+    await Users(dc).save(adminUser);
+    // Seed a group so the group lookup finds real data (not "group not found → Founder")
+    const { Groups } = await Promise.resolve().then(() => require("./groups"));
+    await Groups(dc).save({
+        groupId: testGroupId,
+        name: "Test Group",
+        description: "",
+        founderUserId: (0, utils_1.newid)(), // different from writer/admin so nobody is auto-Founder
+        signature: "",
+        publicKey: "",
+        publicBoxKey: "",
+    });
+    // Seed group memberships with real roles
+    const { GroupMembers } = await Promise.resolve().then(() => require("./group-members"));
+    const writerMembership = {
+        groupMemberId: (0, utils_1.newid)(),
+        groupId: testGroupId,
+        userId: writerUserId,
+        role: group_member_roles_1.GroupMemberRole.Writer,
+        signature: "",
+    };
+    await GroupMembers(dc).save(writerMembership);
+    const adminMembership = {
+        groupMemberId: (0, utils_1.newid)(),
+        groupId: testGroupId,
+        userId: adminUserId,
+        role: group_member_roles_1.GroupMemberRole.Admin,
+        signature: "",
+    };
+    await GroupMembers(dc).save(adminMembership);
+    // Disable passthrough so the real permission checks apply during tests
+    groups_1.GroupsTable.isPassthrough = false;
+    group_members_1.GroupMembersTable.isPassthrough = false;
+    users_1.UsersTable.isPassthrough = false;
+    // Enable real signing
+    package_versions_1.PackageVersionsTable.enablePackageVersionSigning((pv) => (0, keys_1.addSignatureToObject)(pv, activeSecretKey));
+});
+let activeSecretKey = writerKeys.secretKey;
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("PackageVersionsTable.signAndSave — promotion permission enforcement", () => {
+    // These tests exercise the real signAndSave → save → verifyPackageVersionSignature
+    // chain against a real in-memory database with real group membership data.
+    //
+    // THE BUG: signAndSave previously called super.save() which skipped the
+    // overridden save() and its verifyPackageVersionSignature check. A Writer
+    // could promote dev → beta/stable unchallenged.
+    //
+    // THE FIX: signAndSave now calls this.save(), so the permission check fires.
+    // Helper: get the PackageVersions table in the test group context
+    function pvTable() {
+        const dc = userContext.getDataContext(testGroupId);
+        return (0, package_versions_1.PackageVersions)(dc);
+    }
+    describe("Writer role", () => {
+        beforeEach(() => {
+            activeSecretKey = writerKeys.secretKey;
+        });
+        it("can signAndSave a dev version", async () => {
+            const pv = makePV({ versionTag: "dev" });
+            const saved = await pvTable().signAndSave(pv);
+            expect(saved.versionTag).toBe("dev");
+            expect(saved.signature).toBeTruthy();
+        });
+        it("is blocked from signAndSave with versionTag=beta", async () => {
+            const pv = makePV({ versionTag: "beta" });
+            // Before the fix: this would PASS (super.save skipped the check)
+            // After the fix: this correctly REJECTS
+            await expect(pvTable().signAndSave(pv)).rejects.toThrow("Only group admins can create or update beta/stable package versions");
+        });
+        it("is blocked from signAndSave with versionTag=stable", async () => {
+            const pv = makePV({ versionTag: "stable" });
+            await expect(pvTable().signAndSave(pv)).rejects.toThrow("Only group admins can create or update beta/stable package versions");
+        });
+        it("is blocked from promoting an existing dev version to beta", async () => {
+            const pv = makePV({ versionTag: "dev" });
+            const saved = await pvTable().signAndSave(pv);
+            const promoted = { ...saved, versionTag: "beta" };
+            await expect(pvTable().signAndSave(promoted)).rejects.toThrow("Only group admins can create or update beta/stable package versions");
+        });
+    });
+    describe("Admin role", () => {
+        beforeEach(() => {
+            activeSecretKey = adminKeys.secretKey;
+        });
+        it("can signAndSave a dev version", async () => {
+            const pv = makePV({ versionTag: "dev" });
+            const saved = await pvTable().signAndSave(pv);
+            expect(saved.versionTag).toBe("dev");
+        });
+        it("can signAndSave a beta version", async () => {
+            const pv = makePV({ versionTag: "beta" });
+            const saved = await pvTable().signAndSave(pv);
+            expect(saved.versionTag).toBe("beta");
+        });
+        it("can signAndSave a stable version", async () => {
+            const pv = makePV({ versionTag: "stable" });
+            const saved = await pvTable().signAndSave(pv);
+            expect(saved.versionTag).toBe("stable");
+        });
+        it("can promote an existing dev version to beta", async () => {
+            const pv = makePV({ versionTag: "dev" });
+            const saved = await pvTable().signAndSave(pv);
+            const promoted = { ...saved, versionTag: "beta" };
+            const result = await pvTable().signAndSave(promoted);
+            expect(result.versionTag).toBe("beta");
+        });
+        it("can promote an existing beta version to stable", async () => {
+            const pv = makePV({ versionTag: "beta" });
+            const saved = await pvTable().signAndSave(pv);
+            const promoted = { ...saved, versionTag: "stable" };
+            const result = await pvTable().signAndSave(promoted);
+            expect(result.versionTag).toBe("stable");
+        });
+    });
+    describe("personal space (no group)", () => {
+        it("allows Writer to signAndSave any tag without restriction", async () => {
+            activeSecretKey = writerKeys.secretKey;
+            const dc = userContext.userDataContext;
+            const table = (0, package_versions_1.PackageVersions)(dc);
+            const pv = makePV({ versionTag: "stable" });
+            const saved = await table.signAndSave(pv);
+            expect(saved.versionTag).toBe("stable");
+        });
+    });
+});

package/dist/data/packages.js

@@ -106,14 +106,7 @@ let PackagesTable = (() => {
                 // users can do whatever they want to packages in their personal space
                 return super.save(packageObj, opts);
             }
-            try {
-                await (0, package_permissions_1.verifyPackageSignature)(packageObj, this.groupId);
-            }
-            catch (err) {
-                throw new Error("Package verification failed.  Did you mean to call `signAndSave`?", {
-                    cause: err,
-                });
-            }
+            await (0, package_permissions_1.verifyPackageSignature)(packageObj, this.groupId);
             return super.save(packageObj, opts);
         }
         async signAndSave(packageObj, opts) {
@@ -121,7 +114,7 @@ let PackagesTable = (() => {
                 throw new Error("Package signing is not enabled. Call PackagesTable.enablePackageSigning(fn) to enable it.");
             }
             packageObj = await PackagesTable.addSignatureToPackage(packageObj);
-            return super.save(packageObj, opts);
+            return this.save(packageObj, opts);
         }
         static addSignatureToPackage = undefined;
         static enablePackageSigning(fn) {

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

@@ -7,6 +7,9 @@ import type { IPackageDefinitionResult } from "../contracts/types";
  * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
  * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
  * with the `packageId` from the definition set, and registers table definitions.
+ *
+ * When a contract version was previously frozen (promoted to stable), the
+ * installer preserves its stable status rather than re-registering it as dev.
  */
 export declare function installContractPackage(dataContext: DataContext, packageDefinition: IPackageDefinitionResult, opts?: {
     registry?: ContractRegistry;
@@ -14,6 +17,9 @@ export declare function installContractPackage(dataContext: DataContext, package
 /**
  * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.
  * Returns undefined if the bundle doesn't export a contract-based package definition.
+ *
+ * Matches any bundle that exports a `packageDefinition` with a valid `packageId`,
+ * including UI-only packages with zero contracts.
  */
 export declare function extractPackageDefinition(bundleExports: Record<string, unknown>): IPackageDefinitionResult | undefined;
 /**
@@ -21,3 +27,9 @@ export declare function extractPackageDefinition(bundleExports: Record<string, u
  * indicating it should be installed via the new contract-aware path.
  */
 export declare function hasPackageDefinition(bundleExports: Record<string, unknown>): boolean;
+/**
+ * Finalize all dev contracts for a package when promoting to stable.
+ * Removes `devTag` from each contract in the registry, freezing their shapes.
+ * Returns the list of contract keys that were finalized.
+ */
+export declare function finalizeContractsForPromotion(registry: ContractRegistry, packageId: string): string[];

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.installContractPackage = installContractPackage;
 exports.extractPackageDefinition = extractPackageDefinition;
 exports.hasPackageDefinition = hasPackageDefinition;
+exports.finalizeContractsForPromotion = finalizeContractsForPromotion;
 const tools_1 = require("../data/tools");
 const tools_2 = require("../tools");
 /**
@@ -11,6 +12,9 @@ const tools_2 = require("../tools");
  * Handles packages that export an `IPackageDefinitionResult` from `definePackage()`.
  * Registers contracts in the provided ContractRegistry, saves tools/assistants/workflows
  * with the `packageId` from the definition set, and registers table definitions.
+ *
+ * When a contract version was previously frozen (promoted to stable), the
+ * installer preserves its stable status rather than re-registering it as dev.
  */
 async function installContractPackage(dataContext, packageDefinition, opts) {
     const { packageId } = packageDefinition;
@@ -20,7 +24,14 @@ async function installContractPackage(dataContext, packageDefinition, opts) {
         for (const contract of packageDefinition.contracts) {
             const key = `${contract.contractId}@${contract.version}`;
             const alsoImpl = packageDefinition.alsoImplements.get(key) ?? [];
-            const result = registry.register(packageId, contract, alsoImpl);
+            // If the contract is already frozen in the registry, re-register as
+            // stable instead of dev to preserve immutability.
+            const existing = registry.getDefinition(contract.contractId, contract.version);
+            let effectiveContract = contract;
+            if (existing && !existing.devTag && contract.devTag === "dev") {
+                effectiveContract = { ...contract, devTag: undefined };
+            }
+            const result = registry.register(packageId, effectiveContract, alsoImpl);
             if (!result.valid) {
                 console.error(`[ContractPackageLoader] Contract registration failed for ${contract.name}:`, result.errors);
             }
@@ -48,10 +59,13 @@ async function installContractPackage(dataContext, packageDefinition, opts) {
 /**
  * Attempts to extract an `IPackageDefinitionResult` from a bundle's module exports.
  * Returns undefined if the bundle doesn't export a contract-based package definition.
+ *
+ * Matches any bundle that exports a `packageDefinition` with a valid `packageId`,
+ * including UI-only packages with zero contracts.
  */
 function extractPackageDefinition(bundleExports) {
     const def = bundleExports?.packageDefinition;
-    if (def && Array.isArray(def.contracts) && def.contracts.length > 0) {
+    if (def && typeof def.packageId === "string" && Array.isArray(def.contracts)) {
         return def;
     }
     return undefined;
@@ -63,3 +77,23 @@ function extractPackageDefinition(bundleExports) {
 function hasPackageDefinition(bundleExports) {
     return extractPackageDefinition(bundleExports) !== undefined;
 }
+/**
+ * Finalize all dev contracts for a package when promoting to stable.
+ * Removes `devTag` from each contract in the registry, freezing their shapes.
+ * Returns the list of contract keys that were finalized.
+ */
+function finalizeContractsForPromotion(registry, packageId) {
+    const finalized = [];
+    const contractKeys = registry.getContractKeysForPackage(packageId);
+    for (const key of contractKeys) {
+        const [contractId, versionStr] = key.split("@");
+        const version = Number(versionStr);
+        const def = registry.getDefinition(contractId, version);
+        if (def?.devTag === "dev") {
+            const frozenDef = { ...def, devTag: undefined };
+            registry.updateDefinition(contractId, version, frozenDef);
+            finalized.push(key);
+        }
+    }
+    return finalized;
+}

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

@@ -21,7 +21,7 @@ export declare class PackageLoader {
     }): Promise<IPeersPackage | undefined>;
     private _readLocalBundle;
     /**
-     * Post-correction: if the package definition carries version/versionTag,
+     * Post-correction: if the package definition carries a version string,
      * update the active IPackageVersion record to match. This fixes cases where
      * the PV record was created with stale or placeholder values (e.g. "0.0.1")
      * before the bundle was evaluated.

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

@@ -99,7 +99,7 @@ class PackageLoader {
         }
     }
     /**
-     * Post-correction: if the package definition carries version/versionTag,
+     * Post-correction: if the package definition carries a version string,
      * update the active IPackageVersion record to match. This fixes cases where
      * the PV record was created with stale or placeholder values (e.g. "0.0.1")
      * before the bundle was evaluated.
@@ -107,28 +107,18 @@ class PackageLoader {
     correctPackageVersion(pkg, def) {
         if (!pkg.activePackageVersionId)
             return;
-        if (!def.version && !def.versionTag)
+        if (!def.version)
             return;
         const pvTable = (0, package_versions_1.PackageVersions)(this.dataContext);
         pvTable.get(pkg.activePackageVersionId).then((pv) => {
             if (!pv)
                 return;
-            let needsUpdate = false;
-            const updated = { ...pv };
             if (def.version && pv.version !== def.version) {
-                updated.version = def.version;
-                needsUpdate = true;
-            }
-            if (def.versionTag && pv.versionTag !== def.versionTag) {
-                updated.versionTag = def.versionTag;
-                needsUpdate = true;
-            }
-            if (needsUpdate) {
-                pvTable.save(updated);
+                pvTable.save({ ...pv, version: def.version });
             }
         });
     }
-    _evaluateBundle(pkg, bundleCode) {
+    async _evaluateBundle(pkg, bundleCode) {
         // Node.js built-in modules that do not exist in React Native (and would cause
         // a fatal native error if passed through to RN's require). We block them here
         // and throw a descriptive JS Error instead, which the surrounding try/catch
@@ -199,26 +189,34 @@ class PackageLoader {
                 if (packageDefinition.packageId !== pkg.packageId) {
                     console.warn(`[PackageLoader] packageId mismatch: definition has "${packageDefinition.packageId}" but DB record has "${pkg.packageId}"`);
                 }
-                (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition);
+                await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition);
                 this.contractInstalledPackages.add(packageDefinition.packageId);
                 this.correctPackageVersion(pkg, packageDefinition);
+                // Build a proper IPeersPackage from the contract definition so callers
+                // (e.g. package-installer) can read appNavs, assistants, etc.
+                const contractPackageInstance = {
+                    packageId: packageDefinition.packageId,
+                    appNavs: packageDefinition.appNavs,
+                    assistants: packageDefinition.assistants,
+                    toolInstances: packageDefinition.toolInstances,
+                    tableDefinitions: packageDefinition.tableDefinitions,
+                };
+                this.packageInstances[pkg.packageId] = contractPackageInstance;
+                return contractPackageInstance;
             }
             // Legacy path: extract IPeersPackage for backward compat
             const packageInstance = bundleExports?.exports || bundleExports?.package || bundleExports?.default || bundleExports;
             this.packageInstances[pkg.packageId] = packageInstance;
             if (packageInstance && typeof packageInstance === "object") {
-                // Skip legacy tool/table registration if the contract path already handled it
-                if (!packageDefinition) {
-                    packageInstance.toolInstances?.forEach((toolInstance) => {
-                        (0, tools_2.registerTool)(toolInstance);
-                        (0, tools_1.Tools)(this.dataContext).save(toolInstance.tool);
+                packageInstance.toolInstances?.forEach((toolInstance) => {
+                    (0, tools_2.registerTool)(toolInstance);
+                    (0, tools_1.Tools)(this.dataContext).save(toolInstance.tool);
+                });
+                packageInstance.tableDefinitions?.forEach((tableDefinition) => {
+                    this.dataContext.tableContainer.registerTableDefinition(tableDefinition, {
+                        overwrite: true,
                     });
-                    packageInstance.tableDefinitions?.forEach((tableDefinition) => {
-                        this.dataContext.tableContainer.registerTableDefinition(tableDefinition, {
-                            overwrite: true,
-                        });
-                    });
-                }
+                });
                 return packageInstance;
             }
             return;

package/package.json

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