@peers-app/peers-sdk 0.28.7 → 0.28.9

package/dist/contracts/system/contract-catalog-contract.d.ts

@@ -71,6 +71,12 @@ export interface IContractDefinitionWithPolicy {
     definition: IContractDefinition;
     /** Each tool's policy, where the Runtime knows it. */
     tools?: IContractToolPolicy[];
+    /** Active provider's table settings, when known; absent on older hosts. */
+    tables?: {
+        name: string;
+        versionNumber?: number;
+        localOnly?: boolean;
+    }[];
 }
 /**
  * Consumer shape for the System Contract Catalog.

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

@@ -47,6 +47,7 @@ function getContractCatalogDefinition() {
                 outputFields: [
                     field("definition", field_type_1.FieldType.object, "The registered definition, in Peers IR."),
                     field("tools", field_type_1.FieldType.object, "Each tool's name, accessLevel, and authorityPropagation on the active provider.", { isArray: true, optional: true }),
+                    field("tables", field_type_1.FieldType.object, "Each table's name, versionNumber, and localOnly setting on the active provider.", { isArray: true, optional: true }),
                 ],
             },
         ],

package/dist/contracts/system/packages-contract.d.ts

@@ -42,6 +42,8 @@ export interface IPackageObservedRuntime {
 export interface IPackageRequestedVersion {
     /** Group-wide active version (`Packages.activePackageVersionId`). */
     groupActivePackageVersionId?: string;
+    /** The group selected a version whose row is not on this device yet. */
+    groupVersionMissing?: boolean;
     /** This device's override, when set. */
     deviceActivePackageVersionId?: string;
     /** The version this device should run: the device override, else the group version. */
@@ -101,8 +103,8 @@ export interface IPackageOperationResult {
     /** True when `createPackage` scaffolded a new package instead of importing an existing folder. */
     created?: boolean;
     /**
-     * Non-fatal problem the caller should show: for example a missing package template, or a
-     * reloaded dev build that reuses a released version number and should be bumped.
+     * Non-fatal problem the caller should show, for example a missing package template.
+     * Older hosts also report released-number conflicts here instead of refusing reload.
      */
     warning?: string;
     /** The package after the operation. */
@@ -120,7 +122,7 @@ export interface IPackageReloadOutcome {
     changed?: boolean;
     /** Failure message when `ok` is false. */
     error?: string;
-    /** Non-fatal problem, such as a dev build that reuses a released version number. */
+    /** Non-fatal problem; older hosts may warn here about a reused released number. */
     warning?: string;
 }
 /** Result of `reloadAllPackages`. */
@@ -141,11 +143,19 @@ export interface IPromotePackageVersionResult extends IPackageOperationResult {
     /** True when this device holds the package signing key and signed the promoted version. */
     signed: boolean;
     /**
-     * True when the version this device was running now matches the group's follow policy
-     * and was activated, for the group unless this device overrides group settings.
+     * True when activation ran, either explicitly with activateForGroup or automatically
+     * under the group follow policy. See groupRunsPromotedVersion for the group outcome.
      */
     activated: boolean;
+    /** Group selection after promotion, when one is set. */
+    groupActivePackageVersionId?: string;
+    /** True even when the group already selected this id before it was re-tagged. */
+    groupRunsPromotedVersion?: boolean;
+    /** What the group now runs, why selection stayed unchanged, and any next command. */
+    activationNote?: string;
 }
+/** Explain a group version missing locally and how to select an available release. */
+export declare function packageGroupVersionWarning(packageId: string, requested: Pick<IPackageRequestedVersion, "groupActivePackageVersionId" | "groupVersionMissing">): string | undefined;
 /**
  * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
  * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
@@ -207,7 +217,7 @@ export interface IPackagesConsumer extends IContractConsumerBase {
             packageVersionId?: string;
             scope?: "device" | "group";
         }): Promise<IPackageOperationResult>;
-        /** Rebuild the dev version from disk when it changed, then force-reload the package. */
+        /** Read local bundles, then force-reload the selected version even when unchanged. */
         reloadPackage(input: {
             packageId: string;
         }): Promise<IPackageOperationResult>;
@@ -228,10 +238,13 @@ export interface IPackagesConsumer extends IContractConsumerBase {
          * Promote a stored version to `beta` or `stable`: re-tag, re-sign with the package author
          * key when this device has it, record the promotion in the version's history, and
          * activate it when this device was running it and the group follows the new tag.
+         * activateForGroup explicitly selects it for the group and follows that selection here.
          */
         promotePackageVersion(input: {
             packageVersionId: string;
             versionTag: string;
+            /** Also select the promoted version for the group and follow it here (Admin). */
+            activateForGroup?: boolean;
         }): Promise<IPromotePackageVersionResult>;
         /** Install the default packages into the bound data context. */
         installDefaultPackages(): Promise<{

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PACKAGES_CONTRACT_VERSION = void 0;
+exports.packageGroupVersionWarning = packageGroupVersionWarning;
 exports.packageVersionPromotionTargets = packageVersionPromotionTargets;
 exports.isPackageRepositoryUrl = isPackageRepositoryUrl;
 exports.getPackagesContractDefinition = getPackagesContractDefinition;
@@ -9,6 +10,12 @@ const field_type_1 = require("../../types/field-type");
 const system_contracts_1 = require("../system-contracts");
 /** Version of the built-in System Packages contract. */
 exports.PACKAGES_CONTRACT_VERSION = 1;
+/** Explain a group version missing locally and how to select an available release. */
+function packageGroupVersionWarning(packageId, requested) {
+    if (!requested.groupVersionMissing || !requested.groupActivePackageVersionId)
+        return undefined;
+    return `The group's selected version ${requested.groupActivePackageVersionId} isn't on this device; it may not have synced yet. To select an available beta or stable version for the group, run: peers packages activate ${packageId} <packageVersionId> --group`;
+}
 /**
  * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
  * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
@@ -138,7 +145,7 @@ function getPackagesContractDefinition() {
             },
             {
                 name: "reloadPackage",
-                usageDescription: "Rebuild the dev version from the package folder when it changed, then force-reload the package on this device.",
+                usageDescription: "Read local bundles, then force-reload the selected version even when unchanged. Changed builds at a released number are refused.",
                 inputFields: [packageIdField],
                 outputFields: operationResultFields,
             },
@@ -170,10 +177,11 @@ function getPackagesContractDefinition() {
             },
             {
                 name: "promotePackageVersion",
-                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag.",
+                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag. Optionally selects it for the group with activateForGroup. Reports the group selection and any next command.",
                 inputFields: [
                     field("packageVersionId", field_type_1.FieldType.id, "Version to promote."),
                     field("versionTag", field_type_1.FieldType.string, "New release channel: beta or stable."),
+                    field("activateForGroup", field_type_1.FieldType.boolean, "Also select this version for the group and follow it here (Admin).", { optional: true }),
                 ],
                 outputFields: [
                     ...operationResultFields,
@@ -181,6 +189,11 @@ function getPackagesContractDefinition() {
                     field("version", field_type_1.FieldType.string, "Its version number."),
                     field("versionTag", field_type_1.FieldType.string, "Its new release channel."),
                     field("signed", field_type_1.FieldType.boolean, "True when this device signed the promoted version."),
+                    field("groupActivePackageVersionId", field_type_1.FieldType.id, "Group selection after promotion.", {
+                        optional: true,
+                    }),
+                    field("groupRunsPromotedVersion", field_type_1.FieldType.boolean, "Whether the group now selects the promoted version, including an already-selected id.", { optional: true }),
+                    field("activationNote", field_type_1.FieldType.string, "What the group now runs and any next command.", { optional: true }),
                     field("activated", field_type_1.FieldType.boolean, "True when the promotion also activated the version for the group or this device."),
                 ],
             },

package/dist/contracts/tool-catalog.d.ts

@@ -91,8 +91,15 @@ export declare class ToolCatalog {
     })[]): Promise<void>;
     /** Reject quarantined or conflicting retained evidence before a contract tool call. */
     assertTargetUsable(target: ToolCatalogTarget): Promise<void>;
-    /** Serialize host removal with pending publications while retaining all catalog rows. */
-    removeProvider(provider: string, deactivate: () => void): Promise<void>;
+    /**
+     * Serialize host removal with pending publications while retaining all catalog rows.
+     * An optional load-generation guard runs before any live registration is changed.
+     *
+     * @param provider - Package whose registrations are being removed.
+     * @param deactivate - Synchronously retire its host endpoints and bookkeeping.
+     * @param assertCurrent - Reject a superseded removal without changing the active provider.
+     */
+    removeProvider(provider: string, deactivate: () => void, assertCurrent?: () => void): Promise<void>;
     /** Stop subscriptions and queued lifecycle work; permanent rows are retained. */
     dispose(): Promise<void>;
 }

package/dist/contracts/tool-catalog.js

@@ -605,12 +605,20 @@ class ToolCatalog {
             validateToolCatalogWrite({ toolId, ...resolvedFields(target, toolId) }, row);
         }
     }
-    /** Serialize host removal with pending publications while retaining all catalog rows. */
-    async removeProvider(provider, deactivate) {
+    /**
+     * Serialize host removal with pending publications while retaining all catalog rows.
+     * An optional load-generation guard runs before any live registration is changed.
+     *
+     * @param provider - Package whose registrations are being removed.
+     * @param deactivate - Synchronously retire its host endpoints and bookkeeping.
+     * @param assertCurrent - Reject a superseded removal without changing the active provider.
+     */
+    async removeProvider(provider, deactivate, assertCurrent) {
         // Join the same readiness boundary as publish(), including on a cold context,
         // so an earlier install cannot enqueue its activation behind this removal.
         await this.ready();
         await this.enqueue(async () => {
+            assertCurrent?.();
             this.registry.unregister(provider);
             deactivate();
         });

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

@@ -115,6 +115,10 @@ declare const schema: z.ZodObject<{
 }>;
 /** A signed package build and its bundle hashes, tag, and lifecycle history. */
 export type IPackageVersion = z.infer<typeof schema>;
+/** Find a beta or stable build with the same package and version number, excluding a supplied id. */
+export declare function releasedVersionWithNumber(versions: readonly IPackageVersion[], candidate: Pick<IPackageVersion, "packageId" | "version"> & {
+    packageVersionId?: string;
+}): IPackageVersion | undefined;
 /** Package version table with signature and group promotion permission checks. */
 export declare class PackageVersionsTable extends Table<IPackageVersion> {
     static isPassthrough: boolean;

package/dist/data/package-versions.js

@@ -35,6 +35,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageVersionsTable = void 0;
+exports.releasedVersionWithNumber = releasedVersionWithNumber;
 exports.PackageVersions = PackageVersions;
 exports.computePackageVersionHash = computePackageVersionHash;
 exports.isVersionInRange = isVersionInRange;
@@ -100,6 +101,13 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(schema),
     indexes: [{ fields: ["packageId"] }],
 };
+/** Find a beta or stable build with the same package and version number, excluding a supplied id. */
+function releasedVersionWithNumber(versions, candidate) {
+    return versions.find((other) => other.packageId === candidate.packageId &&
+        other.packageVersionId !== candidate.packageVersionId &&
+        other.version === candidate.version &&
+        (other.versionTag === "beta" || other.versionTag === "stable"));
+}
 // Symbol.for keeps signer registration shared by separately installed SDK copies.
 const signingKey = Symbol.for("@peers-app/peers-sdk/package-version-signing");
 const signingGlobals = globalThis;

package/dist/package-build/cli.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const node_fs_1 = require("node:fs");
 const path = require("node:path");
+const sdk_version_1 = require("../sdk-version");
 const build_package_1 = require("./build-package");
 const contract_add_1 = require("./contract-add");
 const freeze_contracts_1 = require("./freeze-contracts");
@@ -11,7 +12,7 @@ const USAGE = `Usage: peers-package <command> [options]
 Commands:
   manifest              Write dist/manifest.json from the package's declarations (src/package.ts).
   build                 Write the manifest and dist/package.bundle.js, the artifact the Runtime
-                        installs.
+                        installs. Prints the SDK version used to build it.
   contract add <source> Write src/contracts/<name>.v<version>.ts, a declaration of a contract this
                         package implements or calls, generated from <source>: a declaration module
                         and its export (path/to/file.ts#Name), a provider's manifest.json or
@@ -96,13 +97,13 @@ async function main(argv) {
                 console.error(`Build failed: ${result.message}`);
                 return;
             }
-            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
         });
         console.log("Watching for changes");
         return new Promise(() => undefined);
     }
     const result = await (0, build_package_1.buildPackage)(options);
-    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
     return 0;
 }
 /** `peers-package contract add <source> [options]` or `peers-package contract freeze [options]`. */

package/dist/package-build/contract-add.d.ts

@@ -1,11 +1,13 @@
+import { type IContractSource } from "./contract-source";
 /** What {@link addContract} takes. */
 export interface IContractAddOptions {
     /**
      * Where the contract comes from: a declaration module and its export
      * (`../voice-hub/src/contracts/voice-skill.ts#VoiceSkill`), a provider's `manifest.json` or
-     * `package.bundle.js`, or the JSON `getContractDefinition` returned.
+     * `package.bundle.js`, the JSON `getContractDefinition` returned, or an in-memory
+     * contract source (for example from `contractSourceFromDefinition`).
      */
-    source: string;
+    source: string | IContractSource;
     /** `contractId@version`, for a manifest that provides more than one contract. */
     contract?: string;
     /** Package root. Defaults to the current directory. */

package/dist/package-build/contract-add.js

@@ -19,9 +19,10 @@ const contract_source_1 = require("./contract-source");
  */
 async function addContract(options) {
     const root = path.resolve(options.root ?? process.cwd());
-    const contract = await readContractSource(root, options);
+    const contract = typeof options.source === "string"
+        ? await readContractSource(root, { ...options, source: options.source })
+        : options.source;
     const generated = (0, contract_source_1.generateContractDeclaration)(contract, {
-        from: sourceLabel(root, options.source),
         ...(options.name ? { exportName: options.name } : {}),
     });
     const target = path.join(path.resolve(root, options.outDir ?? "src/contracts"), generated.fileName);
@@ -41,15 +42,6 @@ function splitSource(source) {
         ? { file: source.slice(0, hash), exportName: source.slice(hash + 1) }
         : { file: source };
 }
-/**
- * The source as the file's header names it: relative to the package root, with `/`, so the
- * generated file (and `--check`) doesn't depend on where the command ran or on local paths.
- */
-function sourceLabel(root, source) {
-    const { file, exportName } = splitSource(source);
-    const relative = path.relative(root, path.resolve(file)).split(path.sep).join("/");
-    return exportName === undefined ? relative : `${relative}#${exportName}`;
-}
 async function readContractSource(root, options) {
     const { file, exportName } = splitSource(options.source);
     if (exportName !== undefined) {

package/dist/package-build/contract-source.d.ts

@@ -49,11 +49,14 @@ export declare function parseContractSelector(selector: string): {
  * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
  * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
  *
+ * Table storage settings are preserved: implementing the declaration uses its tables.
+ * Default settings (schema version 1 and synced storage) are omitted.
+ *
  * @param input - The contract and its tables.
- * @param options - Where it came from (for the file's header), and an export name to use
- *   instead of the one made from the contract's name.
+ * @param options - An export name to use instead of the one made from the contract's name.
  */
-export declare function generateContractDeclaration(input: IContractSource, options: {
-    from: string;
+export declare function generateContractDeclaration(input: IContractSource, options?: {
+    /** Ignored for compatibility with older callers; generated headers never name a source. */
+    from?: string;
     exportName?: string;
 }): IGeneratedContractDeclaration;

package/dist/package-build/contract-source.js

@@ -67,6 +67,7 @@ function contractSourceFromDefinition(input) {
         throw new Error("Expected getContractDefinition's result: { definition, tools }");
     }
     const policy = new Map((input.tools ?? []).map((tool) => [tool.name, tool]));
+    const tablePolicy = new Map((input.tables ?? []).map((table) => [table.name, table]));
     const tools = definition.tools.map((tool) => {
         const toolPolicy = policy.get(tool.name);
         if (toolPolicy?.accessLevel === undefined) {
@@ -101,12 +102,17 @@ function contractSourceFromDefinition(input) {
             ...(definition.observables?.length ? { observables: definition.observables } : {}),
             ...(definition.events?.length ? { events: definition.events } : {}),
         },
-        tables: (definition.tables ?? []).map((table) => ({
-            name: table.name,
-            description: table.description,
-            primaryKeyName: table.primaryKeyName,
-            fields: table.fields,
-        })),
+        tables: (definition.tables ?? []).map((table) => {
+            const settings = tablePolicy.get(table.name);
+            return {
+                name: table.name,
+                description: table.description,
+                primaryKeyName: table.primaryKeyName,
+                fields: table.fields,
+                ...(settings?.versionNumber === undefined ? {} : { versionNumber: settings.versionNumber }),
+                ...(settings?.localOnly ? { localOnly: true } : {}),
+            };
+        }),
     };
 }
 /**
@@ -131,11 +137,13 @@ function parseContractSelector(selector) {
  * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
  * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
  *
+ * Table storage settings are preserved: implementing the declaration uses its tables.
+ * Default settings (schema version 1 and synced storage) are omitted.
+ *
  * @param input - The contract and its tables.
- * @param options - Where it came from (for the file's header), and an export name to use
- *   instead of the one made from the contract's name.
+ * @param options - An export name to use instead of the one made from the contract's name.
  */
-function generateContractDeclaration(input, options) {
+function generateContractDeclaration(input, options = {}) {
     const { contract, tables } = input;
     assertVersion(contract.version, "Contract version");
     const exportName = options.exportName ?? pascalCase(contract.name);
@@ -145,7 +153,7 @@ function generateContractDeclaration(input, options) {
     const imports = new Set(["declareContract"]);
     const code = new Code(imports);
     const lines = [];
-    lines.push(`// Generated by \`peers-package contract add\` from ${docText(options.from)}.`, "// Regenerate it rather than edit it; a stable package release freezes the contract's shape.", "");
+    lines.push(`// Generated contract declaration. Regenerate with \`peers contracts add ${docText(contract.contractId)}@${contract.version}\``, "// or `peers-package contract add <source>`; do not edit by hand.", "");
     const eventNames = new Map();
     for (const event of contract.events ?? []) {
         const name = uniqueName(`${camelCase(exportName)}${pascalCase(event.name)}`, new Set([...RESERVED_NAMES, exportName, ...eventNames.values()]));
@@ -223,7 +231,7 @@ class Code {
             ["description", JSON.stringify(table.description ?? "")],
             ["primaryKeyName", JSON.stringify(table.primaryKeyName)],
             ["schema", this.objectSchema(table.fields, depth + 1)],
-            ...(table.versionNumber === undefined
+            ...(table.versionNumber === undefined || table.versionNumber === 1
                 ? []
                 : [["versionNumber", String(table.versionNumber)]]),
             ...(table.localOnly ? [["localOnly", "true"]] : []),
@@ -237,7 +245,7 @@ class Code {
             ["name", JSON.stringify(tool.name)],
             ["usageDescription", JSON.stringify(tool.usageDescription)],
             ["accessLevel", this.accessLevel(level)],
-            ...(tool.authorityPropagation
+            ...(tool.authorityPropagation && tool.authorityPropagation !== "cap"
                 ? [["authorityPropagation", JSON.stringify(tool.authorityPropagation)]]
                 : []),
             ...(tool.remoteAccessLevel === undefined
@@ -323,7 +331,10 @@ class Code {
         return `generatedField(${schema}, ${this.shapeSource(metadata)}${valueType === undefined ? "" : `, ${this.fieldType(valueType)}`})`;
     }
     shapeSource(shape) {
-        const entries = Object.entries(shape).map(([key, value]) => {
+        const entries = Object.entries(shape)
+            .filter(([, value]) => value !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, value]) => {
             const source = key === "type"
                 ? this.fieldType(value)
                 : key === "fields"
@@ -422,6 +433,8 @@ function dataSource(value) {
         return `[${value.map(dataSource).join(", ")}]`;
     if (value && typeof value === "object") {
         return `{ ${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
             .map(([key, entry]) => `${propertyKey(key)}: ${dataSource(entry)}`)
             .join(", ")} }`;
     }

package/dist/package-build/index.d.ts

@@ -0,0 +1,3 @@
+/** Node-only helpers for generating package contract declarations. */
+export { addContract, type IContractAddOptions, type IContractAddResult } from "./contract-add";
+export { contractSourceFromDefinition, contractSourceFromManifest, generateContractDeclaration, type IContractSource, type IGeneratedContractDeclaration, parseContractSelector, } from "./contract-source";

package/dist/package-build/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseContractSelector = exports.generateContractDeclaration = exports.contractSourceFromManifest = exports.contractSourceFromDefinition = exports.addContract = void 0;
+/** Node-only helpers for generating package contract declarations. */
+var contract_add_1 = require("./contract-add");
+Object.defineProperty(exports, "addContract", { enumerable: true, get: function () { return contract_add_1.addContract; } });
+var contract_source_1 = require("./contract-source");
+Object.defineProperty(exports, "contractSourceFromDefinition", { enumerable: true, get: function () { return contract_source_1.contractSourceFromDefinition; } });
+Object.defineProperty(exports, "contractSourceFromManifest", { enumerable: true, get: function () { return contract_source_1.contractSourceFromManifest; } });
+Object.defineProperty(exports, "generateContractDeclaration", { enumerable: true, get: function () { return contract_source_1.generateContractDeclaration; } });
+Object.defineProperty(exports, "parseContractSelector", { enumerable: true, get: function () { return contract_source_1.parseContractSelector; } });

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

@@ -126,5 +126,6 @@ async function clonePackage(dataContext, deps, opts) {
         localPath: location,
         remoteRepo: opts.remoteRepo,
         packageVersion: result.packageVersion,
+        warning: result.warning,
     };
 }

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

@@ -313,6 +313,7 @@ async function importExistingPackage(dataContext, deps, opts) {
         packageId,
         localPath: opts.location,
         packageVersion: result.packageVersion,
+        warning: result.warning,
     };
 }
 /**
@@ -413,6 +414,7 @@ async function createPackage(dataContext, deps, opts) {
         packageId,
         localPath: location,
         packageVersion: result.packageVersion,
+        warning: result.warning,
         templateWarning,
     };
 }

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

@@ -9,7 +9,9 @@ import type { IInstallOpts, IInstallResult, IPackageInfo, IPackageInstallerDeps
  * only when content has changed, upserts the PackageVersion, and optionally
  * triggers the package loader and device version resolution.
  *
- * When the bundle hash matches the existing PackageVersion, no files or PV are
+ * A matching released version is returned without any writes or loading, even when
+ * the group has no selected version. Changed bundles at a released number are refused.
+ * When the bundle hash matches the existing dev PackageVersion, no files or PV are
  * rewritten. An Admin's Packages row still gets a missing `activePackageVersionId`
  * (and description), and when the id was missing the version is activated on
  * this device unless `skipResolve`.

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

@@ -14,8 +14,10 @@ const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
 const persistent_vars_1 = require("../data/persistent-vars");
+const sdk_version_1 = require("../sdk-version");
 const utils_1 = require("../utils");
 const package_author_signer_1 = require("./package-author-signer");
+const package_sdk_version_1 = require("./package-sdk-version");
 /**
  * Install or update a dev PackageVersion from locally-built bundle files.
  *
@@ -24,7 +26,9 @@ const package_author_signer_1 = require("./package-author-signer");
  * only when content has changed, upserts the PackageVersion, and optionally
  * triggers the package loader and device version resolution.
  *
- * When the bundle hash matches the existing PackageVersion, no files or PV are
+ * A matching released version is returned without any writes or loading, even when
+ * the group has no selected version. Changed bundles at a released number are refused.
+ * When the bundle hash matches the existing dev PackageVersion, no files or PV are
  * rewritten. An Admin's Packages row still gets a missing `activePackageVersionId`
  * (and description), and when the id was missing the version is activated on
  * this device unless `skipResolve`.
@@ -39,6 +43,7 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     // 2. Read package info
     const info = await getPackageInfo(deps, localPath);
     const version = info.version ?? "0.0.1";
+    const warning = await installedSdkWarning(deps, localPath);
     // 3. Read bundle files
     const distDir = deps.resolvePath(localPath, "dist");
     const packageBundlePath = deps.resolvePath(distDir, "package.bundle.js");
@@ -60,12 +65,26 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     const uiHash = uiBundle ? (0, file_types_1.computeFileHash)(uiBundle) : undefined;
     // 5. Compute PV hash
     const pvHash = (0, package_versions_1.computePackageVersionHash)(version, "", packageHash, routesHash, uiHash);
-    // 6. Early exit if unchanged. Still repair missing appNavs (see syncDevBundles
-    // skipLoad), and still fill an empty activePackageVersionId (e.g. reimport after
-    // the Packages row was deleted). If it was empty, activate on the device unless
-    // skipResolve.
+    // 6. Check released numbers before looking for a mutable local build.
     const pvTable = (0, package_versions_1.PackageVersions)(dataContext);
-    const existingPv = await pvTable.findOne({ packageId, versionTag });
+    const released = (0, package_versions_1.releasedVersionWithNumber)(await pvTable.list({ packageId }), {
+        packageId,
+        version,
+    });
+    if (released) {
+        if (released.packageBundleFileHash !== packageHash ||
+            released.routesBundleFileHash !== routesHash ||
+            released.uiBundleFileHash !== uiHash) {
+            throw new Error(`v${version} is already released as ${released.versionTag}; bump the version in package.json, rebuild, and reload`);
+        }
+        return { packageVersion: released, loaded: undefined, unchanged: true, warning };
+    }
+    // Released rows are immutable builds: a new number gets a new row even when
+    // an SDK caller explicitly installs with a release tag.
+    const existingPv = versionTag === "beta" || versionTag === "stable"
+        ? undefined
+        : await pvTable.findOne({ packageId, versionTag });
+    // An unchanged dev build can still repair appNavs and an empty group selection.
     if (existingPv && existingPv.packageVersionHash === pvHash) {
         let loaded;
         let unchanged = true;
@@ -77,7 +96,7 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
             skipResolve: opts?.skipResolve,
             resolveOnlyWhenActivated: true,
         });
-        return { packageVersion: existingPv, loaded, unchanged };
+        return { packageVersion: existingPv, loaded, unchanged, warning };
     }
     // 7. Save bundle files (deduped by hash)
     const packageFile = await saveBundleFile(dataContext, packageBundle, `${packageId}-package.bundle.js`, packageId);
@@ -122,7 +141,17 @@ async function installPackageFromBundles(dataContext, deps, packageId, opts) {
     await activateInstalledPackageVersion(dataContext, packageId, savedPv, info, localPath, {
         skipResolve: opts?.skipResolve,
     });
-    return { packageVersion: savedPv, loaded, unchanged: false };
+    return { packageVersion: savedPv, loaded, unchanged: false, warning };
+}
+async function installedSdkWarning(deps, localPath) {
+    try {
+        const metadata = await deps.fs.readJson(deps.resolvePath(localPath, "node_modules", "@peers-app", "peers-sdk", "package.json"));
+        return (0, package_sdk_version_1.packageSdkVersionWarning)(metadata?.version, sdk_version_1.SDK_VERSION);
+    }
+    catch {
+        // Packages may ship without node_modules, or the host may not be able to read it.
+        return undefined;
+    }
 }
 /**
  * Sync the Packages row with an installed PackageVersion, then activate it on

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

@@ -0,0 +1,5 @@
+/**
+ * Warn when a package's installed SDK is newer than the host's, using SemVer precedence.
+ * Missing or invalid versions are ignored; build metadata does not affect precedence.
+ */
+export declare function packageSdkVersionWarning(packageVersion: unknown, hostVersion: unknown): string | undefined;

package/dist/package-installer/package-sdk-version.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageSdkVersionWarning = packageSdkVersionWarning;
+/**
+ * Warn when a package's installed SDK is newer than the host's, using SemVer precedence.
+ * Missing or invalid versions are ignored; build metadata does not affect precedence.
+ */
+function packageSdkVersionWarning(packageVersion, hostVersion) {
+    const incoming = parseVersion(packageVersion);
+    const host = parseVersion(hostVersion);
+    if (!incoming || !host || compareVersions(incoming, host) <= 0)
+        return undefined;
+    return `Built with @peers-app/peers-sdk ${packageVersion}, newer than this Peers (${hostVersion}); update Peers, or pin the SDK to ${hostVersion} in package.json`;
+}
+function parseVersion(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+    if (!match || match[0] !== value)
+        return undefined;
+    const prerelease = match[4]?.split(".") ?? [];
+    if (prerelease.some((part) => /^0\d+$/.test(part)))
+        return undefined;
+    return { core: match.slice(1, 4), prerelease };
+}
+function compareIdentifiers(a, b) {
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric && a.length !== b.length)
+        return a.length - b.length;
+    if (aNumeric !== bNumeric)
+        return aNumeric ? -1 : 1;
+    return a === b ? 0 : a > b ? 1 : -1;
+}
+function compareVersions(a, b) {
+    for (let index = 0; index < a.core.length; index++) {
+        const difference = compareIdentifiers(a.core[index], b.core[index]);
+        if (difference)
+            return difference;
+    }
+    if (!a.prerelease.length || !b.prerelease.length) {
+        return Number(!a.prerelease.length) - Number(!b.prerelease.length);
+    }
+    for (let index = 0; index < Math.min(a.prerelease.length, b.prerelease.length); index++) {
+        const difference = compareIdentifiers(a.prerelease[index], b.prerelease[index]);
+        if (difference)
+            return difference;
+    }
+    return a.prerelease.length - b.prerelease.length;
+}

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

@@ -45,7 +45,7 @@ export interface IPackageInstallerDeps {
 export interface IInstallOpts {
     /** Override local path; otherwise read from the packageLocalPath device var. */
     localPath?: string;
-    /** Version tag for the created PackageVersion. Defaults to `"dev"`. */
+    /** Tag for a new build (default `"dev"`). An identical existing release is returned as-is. */
     versionTag?: string;
     /** Skip keeping the package in the loader cache for activation. AppNavs are still backfilled when missing. */
     skipLoad?: boolean;
@@ -54,12 +54,15 @@ export interface IInstallOpts {
 }
 /** Result of {@link installPackageFromBundles}. */
 export interface IInstallResult {
+    /** Non-fatal SDK compatibility warning for a folder install. */
+    warning?: string;
     packageVersion: IPackageVersion;
     loaded: IPeersPackage | undefined;
     /**
      * True when the on-disk bundles match the existing PackageVersion hash and this
      * call persisted no new appNavs. Bundle files and the PackageVersion row are not
-     * rewritten; the Packages row and device activation may still be updated.
+     * rewritten; for a dev version the Packages row and device activation may still
+     * be updated. A matching beta/stable version causes no writes or loading.
      */
     unchanged: boolean;
 }
@@ -109,11 +112,13 @@ export interface ITemplateCacheResult {
 }
 /** Result of {@link createPackage}. */
 export interface ICreatePackageResult {
+    /** Non-fatal SDK compatibility warning from installing the folder's bundles. */
+    warning?: string;
     /** New or imported package ID. */
     packageId: string;
     /** On-disk package directory. */
     localPath: string;
-    /** Installed local/dev package version record. */
+    /** Installed build, or an identical already-released version. */
     packageVersion: IPackageVersion;
     /**
      * Present when the default template cache could not be refreshed and a
@@ -136,12 +141,14 @@ export interface IClonePackageOpts {
 }
 /** Result of {@link clonePackage}. */
 export interface IClonePackageResult {
+    /** Non-fatal SDK compatibility warning from installing the folder's bundles. */
+    warning?: string;
     /** Imported package ID from the cloned repo. */
     packageId: string;
     /** On-disk clone directory. */
     localPath: string;
     /** Git URL that was cloned. */
     remoteRepo: string;
-    /** Installed local/dev package version record. */
+    /** Installed build, or an identical already-released version. */
     packageVersion: IPackageVersion;
 }

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

@@ -92,11 +92,13 @@ export interface IIsolatedPackageUninstallOptions {
 /**
  * Host-owned supervisor for isolated package providers.
  *
- * `peers-sdk` defines the interface only. Electron (or a future PWA host)
+ * `peers-sdk` defines the interface only. Each Electron, headless or browser host
  * registers a factory that constructs an implementation backed by
  * `peers-isolate` workers. The SDK never depends on Node or SES.
  */
 export interface IIsolatedPackageRuntime {
+    /** Supported provider execution modes. Omitted by older hosts that support both modes. */
+    readonly supportedExecutionModes?: readonly ("sandbox" | "privileged")[];
     /**
      * Register a validated artifact. Provider source is stored, not evaluated
      * on the host.

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

@@ -955,13 +955,50 @@ class PackageLoader {
                 throw wrapIsolatedArtifactError(new Error(`Isolated package version mismatch: artifact has "${artifact.manifest.version}" but selected PackageVersion has "${selectedPackageVersion.version}"`));
             }
         }
+        const hasProvider = artifact.providerSource.trim() !== "";
+        const executionMode = artifact.manifest.executionMode ?? "sandbox";
+        const unsupportedReason = hasProvider
+            ? !this.isolatedRuntime
+                ? "This host has no isolated package runtime"
+                : this.isolatedRuntime.supportedExecutionModes &&
+                    !this.isolatedRuntime.supportedExecutionModes.includes(executionMode)
+                    ? "This package runs only on desktop or headless"
+                    : undefined
+            : undefined;
+        if (unsupportedReason) {
+            await this.unloadPackage(pkg.packageId, { status: "unsupported", reason: unsupportedReason });
+            console.warn(!this.isolatedRuntime
+                ? `[PackageLoader] Skipping isolated package "${pkg.name}" because this host does not provide an isolated runtime.`
+                : `[PackageLoader] Skipping isolated package "${pkg.name}": ${unsupportedReason}`);
+            return undefined;
+        }
+        // Empty provider source is the validated screen-only artifact shape. A host with
+        // no runtime still publishes its navigation, just as a desktop runtime does.
         if (!this.isolatedRuntime) {
-            await this.unloadPackage(pkg.packageId, {
-                status: "unsupported",
-                reason: "This host has no isolated package runtime",
+            await this.toolCatalog.removeProvider(pkg.packageId, () => {
+                this.retireHostEndpoints(pkg.packageId);
+                (0, contract_resolvers_1.unregisterPackageContractResolvers)(this.dataContext, pkg.packageId);
+                this.hostConsumes.delete(pkg.packageId);
+                this.contractInstalledPackages.delete(pkg.packageId);
+            }, assertCurrent);
+            assertCurrent();
+            const instance = {
+                packageId: artifact.manifest.packageId,
+                appNavs: artifact.manifest.appNavs,
+            };
+            this.packageInstances[pkg.packageId] = instance;
+            this.recordRunning(pkg.packageId, {
+                ...runningVersionFields(selectedPackageVersion),
+                kind: "isolated",
+                executionMode,
+                provides: [],
+                consumes: artifact.manifest.consumes.map(({ contractId, version }) => ({
+                    contractId,
+                    version,
+                    satisfied: !!this.contractRegistry.getProviderPackageId(contractId, version),
+                })),
             });
-            console.warn(`[PackageLoader] Skipping isolated package "${pkg.name}" because this host does not provide an isolated runtime.`);
-            return undefined;
+            return instance;
         }
         assertCurrent();
         if (this.isolatedPackageNames.get(pkg.packageId) !== pkg.name) {

package/dist/sdk-version.d.ts

@@ -0,0 +1,2 @@
+/** Version of this installed SDK, included by host bundlers from its package metadata. */
+export declare const SDK_VERSION: string;

package/dist/sdk-version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+/** Version of this installed SDK, included by host bundlers from its package metadata. */
+exports.SDK_VERSION = require("../package.json").version;

package/package.json

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