@peers-app/peers-sdk 0.18.3 → 0.18.4

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,6 +1,10 @@
 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
  * @throws Error if signature is invalid or unauthorized
  */

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

@@ -4,7 +4,11 @@ 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
  * @throws Error if signature is invalid or unauthorized
  */
@@ -12,7 +16,11 @@ async function verifyPackageVersionSignature(packageVersion, groupId) {
     (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");
+    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-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"),
@@ -137,16 +146,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 +181,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/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.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"