@peers-app/peers-sdk 0.28.6 → 0.28.8

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-artifact.d.ts

@@ -48,34 +48,17 @@ export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields"
      * {@link ISOLATED_TOOL_TIMEOUT_MAX_MS}. Host calls made during the invoke,
      * including System HTTP, count against this deadline, as does time a handler spends
      * waiting on the package's own locks. A call that times out is rejected; its handler keeps
-     * running unless the worker is stuck, in either guest API.
+     * running unless the worker is stuck.
      */
     timeoutMs?: number;
 }
 /**
- * The latest guest API version an isolated manifest targets.
- *
- * - `3`: as `2`, and the package serves its own contract members. The host sends consumers'
- *   table calls, observable reads and writes, and subscriptions to the provider's worker
- *   (`contractMemberHandlerName`), and passes every table change, event, and observable
- *   value bound for a subscriber through it first (`contractDeliveryHandlerName`).
- * - `2`: handlers receive `(args, ctx)` and calls run concurrently; the package orders any
- *   state it shares between calls itself. The host serves contract tables and stored
- *   observables from storage, without the worker.
- * - Omitted: the legacy global helpers, with one call at a time.
- *
- * Hosts that predate a version reject it.
+ * The guest API version built and run by Peers. Consumers' contract member calls and
+ * notifications pass through the provider's worker under the caller's authority.
  */
 export declare const ISOLATED_GUEST_API_VERSION = 3;
-/** Guest API versions a manifest may declare. */
-export type IsolatedGuestApi = 2 | 3;
-/**
- * True when the package serves its contract members itself (guest API 3): every consumer call
- * and outgoing message goes through its worker.
- *
- * @param manifest - The package's manifest.
- */
-export declare function servesContractMembers(manifest: Pick<IIsolatedPackageManifest, "guestApi">): boolean;
+/** Guest API version for packages built with peers-package. */
+export type IsolatedGuestApi = 3;
 /** Longest per-tool invoke deadline an isolated manifest may declare. */
 export declare const ISOLATED_TOOL_TIMEOUT_MAX_MS = 120000;
 /**
@@ -152,9 +135,9 @@ export interface IIsolatedContractPersistentVarBinding {
 }
 /**
  * Observable contract member. With `persistentVar`, a package-owned persistent variable holds
- * the value. Without it (guest API 2 or later), the worker holds the value in memory and
- * publishes it with `publishOwnedObservable`. Guest API 3 serves all consumer calls and
- * deliveries through the worker; older packages serve stored values directly from the host.
+ * the value. Without it, the worker holds the value in memory and
+ * publishes it with `publishOwnedObservable`. All consumer calls and deliveries pass
+ * through the worker.
  */
 export interface IIsolatedContractObservable extends IContractObservable {
     persistentVar?: IIsolatedContractPersistentVarBinding;
@@ -224,9 +207,8 @@ export interface IIsolatedPackageManifest {
     network?: IIsolatedPackageNetwork;
     appNavs?: IAppNav[];
     /**
-     * Guest API version ({@link ISOLATED_GUEST_API_VERSION}). `2` for handlers that take
-     * `(args, ctx)`; `3` when the package also serves its own contract members; omit for the
-     * legacy global helpers, which run one call at a time.
+     * Guest API version ({@link ISOLATED_GUEST_API_VERSION}). Required by the runtime;
+     * optional here so build tools can inspect historical bundles without running them.
      */
     guestApi?: IsolatedGuestApi;
 }
@@ -311,15 +293,20 @@ export declare function looksLikeIsolatedPackageArtifact(bundle: string): boolea
  */
 export declare function validateIsolatedPackageArtifact(artifact: IIsolatedPackageArtifact, options?: {
     strict?: boolean;
+    /** Refuse unsupported guest APIs before validating their contents for execution. */
+    requireCurrentGuestApi?: boolean;
+    /** Display name to include alongside the package ID in a runtime refusal. */
+    packageName?: string;
 }): IIsolatedPackageManifest;
 /**
  * Parse a magic-header + JSON isolated package bundle.
  *
  * @param bundle - Full package-bundle text.
+ * @param options - Runtime loaders require the current guest API; build tools may inspect older bundles.
  * @returns The validated artifact.
  * @throws If the magic header is present but the envelope is malformed.
  */
-export declare function parseIsolatedPackageArtifact(bundle: string): IIsolatedPackageArtifact;
+export declare function parseIsolatedPackageArtifact(bundle: string, options?: Parameters<typeof validateIsolatedPackageArtifact>[1]): IIsolatedPackageArtifact;
 /**
  * Serialize an isolated artifact into the package-bundle slot format.
  *

package/dist/package-loader/isolated-artifact.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ISOLATED_MAX_FIELD_DEPTH = exports.ISOLATED_OBSERVABLE_HOST_MEMBER = exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = exports.ISOLATED_GUEST_API_VERSION = exports.ISOLATED_PACKAGE_MAGIC = void 0;
-exports.servesContractMembers = servesContractMembers;
 exports.enumValueFits = enumValueFits;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
@@ -30,29 +29,10 @@ const utils_1 = require("../utils");
  */
 exports.ISOLATED_PACKAGE_MAGIC = "PEERS_ISOLATED_PACKAGE_V1";
 /**
- * The latest guest API version an isolated manifest targets.
- *
- * - `3`: as `2`, and the package serves its own contract members. The host sends consumers'
- *   table calls, observable reads and writes, and subscriptions to the provider's worker
- *   (`contractMemberHandlerName`), and passes every table change, event, and observable
- *   value bound for a subscriber through it first (`contractDeliveryHandlerName`).
- * - `2`: handlers receive `(args, ctx)` and calls run concurrently; the package orders any
- *   state it shares between calls itself. The host serves contract tables and stored
- *   observables from storage, without the worker.
- * - Omitted: the legacy global helpers, with one call at a time.
- *
- * Hosts that predate a version reject it.
+ * The guest API version built and run by Peers. Consumers' contract member calls and
+ * notifications pass through the provider's worker under the caller's authority.
  */
 exports.ISOLATED_GUEST_API_VERSION = 3;
-/**
- * True when the package serves its contract members itself (guest API 3): every consumer call
- * and outgoing message goes through its worker.
- *
- * @param manifest - The package's manifest.
- */
-function servesContractMembers(manifest) {
-    return manifest.guestApi === 3;
-}
 /** Longest per-tool invoke deadline an isolated manifest may declare. */
 exports.ISOLATED_TOOL_TIMEOUT_MAX_MS = 120_000;
 /** Host-contract member guests use to request a consumed-contract tool call. */
@@ -340,7 +320,7 @@ function validatePackageTables(manifest, strict) {
         (0, package_table_identity_1.validateTableIndexes)(table.indexes, new Set(table.fields.map((field) => field.name)), `${tableLabel}.indexes`, table.localOnly);
     }
 }
-function validateProvidedContract(contract, index, packageTables, guestApi, strict) {
+function validateProvidedContract(contract, index, packageTables, strict) {
     const label = `provides[${index}]`;
     if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
         throw new Error(`${label} must be an object`);
@@ -488,13 +468,8 @@ function validateProvidedContract(contract, index, packageTables, guestApi, stri
             throw new Error(`${observableLabel}.writable must be a boolean`);
         }
         const binding = observable.persistentVar;
-        if (binding === undefined) {
-            // Held by the worker, which publishes it: that needs guest API 2 or later.
-            if (guestApi === undefined) {
-                throw new Error(`${observableLabel}.persistentVar is required unless the package uses guestApi 2 or later`);
-            }
+        if (binding === undefined)
             continue;
-        }
         if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
             throw new Error(`${observableLabel}.persistentVar must be an object`);
         }
@@ -777,6 +752,15 @@ function validateIsolatedPackageArtifact(artifact, options = {}) {
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
         throw new Error("Package artifact.manifest is required");
     }
+    if (options.requireCurrentGuestApi && manifest.guestApi !== exports.ISOLATED_GUEST_API_VERSION) {
+        const identity = options.packageName
+            ? `'${options.packageName}' (${manifest.packageId})`
+            : manifest.packageId;
+        if (typeof manifest.guestApi === "number" && manifest.guestApi > exports.ISOLATED_GUEST_API_VERSION) {
+            throw new Error(`Package ${identity} needs a newer version of Peers; update Peers to use it.`);
+        }
+        throw new Error(`Package ${identity} has an unsupported guest API. Rebuild it with peers-package; guest API 2 and packages without guestApi are no longer supported.`);
+    }
     assertOnlyKeys(manifest, [
         "packageId",
         "version",
@@ -802,7 +786,9 @@ function validateIsolatedPackageArtifact(artifact, options = {}) {
         manifest.executionMode !== "privileged") {
         throw new Error('manifest.executionMode must be "sandbox" or "privileged"');
     }
-    if (manifest.guestApi !== undefined && manifest.guestApi !== 2 && manifest.guestApi !== 3) {
+    const guestApi = manifest.guestApi;
+    // Contract import/freezing tools still inspect historical bundles without executing them.
+    if (guestApi !== undefined && guestApi !== 2 && guestApi !== 3) {
         throw new Error("manifest.guestApi must be 2 or 3 when set");
     }
     assertPeerId(manifest.packageId, "packageId");
@@ -820,7 +806,7 @@ function validateIsolatedPackageArtifact(artifact, options = {}) {
     const packageTables = manifest.tables ?? [];
     const providedKeys = new Set();
     for (const [index, contract] of manifest.provides.entries()) {
-        validateProvidedContract(contract, index, packageTables, manifest.guestApi, strict);
+        validateProvidedContract(contract, index, packageTables, strict);
         const key = `${contract.contractId}@${contract.version}`;
         if (providedKeys.has(key)) {
             throw new Error(`Duplicate provided contract ${key}`);
@@ -857,10 +843,11 @@ function validateIsolatedPackageArtifact(artifact, options = {}) {
  * Parse a magic-header + JSON isolated package bundle.
  *
  * @param bundle - Full package-bundle text.
+ * @param options - Runtime loaders require the current guest API; build tools may inspect older bundles.
  * @returns The validated artifact.
  * @throws If the magic header is present but the envelope is malformed.
  */
-function parseIsolatedPackageArtifact(bundle) {
+function parseIsolatedPackageArtifact(bundle, options = {}) {
     if (!looksLikeIsolatedPackageArtifact(bundle)) {
         throw new Error("Bundle is not an isolated package artifact");
     }
@@ -878,7 +865,7 @@ function parseIsolatedPackageArtifact(bundle) {
         throw new Error(`Isolated package artifact JSON is invalid: ${err instanceof Error ? err.message : String(err)}`);
     }
     const artifact = parsed;
-    validateIsolatedPackageArtifact(artifact);
+    validateIsolatedPackageArtifact(artifact, options);
     return artifact;
 }
 /**

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

@@ -30,7 +30,7 @@ export interface IPackageContractEndpointOptions {
  * Loads package versions for one {@link DataContext}.
  *
  * Isolated artifacts (magic-header JSON) are installed without host
- * evaluation. Legacy `package.bundle.js` files still evaluate in-process.
+ * evaluation. Host-backed `definePackage()` bundles evaluate in-process.
  */
 export declare class PackageLoader {
     readonly dataContext: DataContext;
@@ -75,7 +75,7 @@ export declare class PackageLoader {
     get catalogReady(): Promise<void>;
     /** Optional isolated-provider supervisor created from the host factory. */
     readonly isolatedRuntime?: IIsolatedPackageRuntime;
-    /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
+    /** Optional host `require` used when reading local bundles or evaluating host-backed packages. */
     require: (<T>(module: string) => T) | undefined;
     /**
      * @param dataContext - Owning personal or group data context. Its
@@ -116,7 +116,7 @@ export declare class PackageLoader {
      */
     private recordLoadFailure;
     private dispatchToolFromProvider;
-    /** Project a legacy caller's declared tool reach and authority for advisory catalog listings. */
+    /** Project a host caller's declared tool reach and authority for advisory catalog listings. */
     hostToolPrincipal(principal: IIsolatedCallPrincipal, packageId: string, target: {
         contractId: string;
         version: number;
@@ -146,7 +146,7 @@ export declare class PackageLoader {
     resolveContractEndpoint(request: IContractProviderEndpointRequest, opts?: IPackageContractEndpointOptions): Promise<IContractProviderEndpoint>;
     private guardResolutionTools;
     /**
-     * Bind a legacy package's declared consume to its selected provider.
+     * Bind a host-backed package's declared consume to its selected provider.
      *
      * The returned proxy can target either a resolver-backed or isolated provider.
      * Its provider choice is captured from {@link ContractRegistry.selectProvider}
@@ -158,7 +158,7 @@ export declare class PackageLoader {
      */
     resolveConsumedContract(dependency: IConsumedContract, callerPackageId: string): Promise<IContractConsumer | undefined>;
     /**
-     * Bind a legacy package's `remote()` declaration to a per-device consumer factory.
+     * Bind a host-backed package's `remote()` declaration to a per-device consumer factory.
      *
      * No local provider is selected: every device consumer stamps `targetDeviceId` and
      * this loader's own router forwards the call through

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

@@ -46,7 +46,7 @@ function isolatedContractLifecycle(packageVersion) {
  * Loads package versions for one {@link DataContext}.
  *
  * Isolated artifacts (magic-header JSON) are installed without host
- * evaluation. Legacy `package.bundle.js` files still evaluate in-process.
+ * evaluation. Host-backed `definePackage()` bundles evaluate in-process.
  */
 class PackageLoader {
     dataContext;
@@ -93,7 +93,7 @@ class PackageLoader {
     }
     /** Optional isolated-provider supervisor created from the host factory. */
     isolatedRuntime;
-    /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
+    /** Optional host `require` used when reading local bundles or evaluating host-backed packages. */
     require = undefined;
     /**
      * @param dataContext - Owning personal or group data context. Its
@@ -264,7 +264,7 @@ class PackageLoader {
             endpoint.dispose();
         }
     }
-    /** Project a legacy caller's declared tool reach and authority for advisory catalog listings. */
+    /** Project a host caller's declared tool reach and authority for advisory catalog listings. */
     hostToolPrincipal(principal, packageId, target) {
         if (!principal.userId || this.isolatedRuntime?.isInstalled(packageId))
             return undefined;
@@ -473,7 +473,7 @@ class PackageLoader {
         };
     }
     /**
-     * Bind a legacy package's declared consume to its selected provider.
+     * Bind a host-backed package's declared consume to its selected provider.
      *
      * The returned proxy can target either a resolver-backed or isolated provider.
      * Its provider choice is captured from {@link ContractRegistry.selectProvider}
@@ -514,7 +514,7 @@ class PackageLoader {
         return consumer;
     }
     /**
-     * Bind a legacy package's `remote()` declaration to a per-device consumer factory.
+     * Bind a host-backed package's `remote()` declaration to a per-device consumer factory.
      *
      * No local provider is selected: every device consumer stamps `targetDeviceId` and
      * this loader's own router forwards the call through
@@ -910,7 +910,10 @@ class PackageLoader {
         assertCurrent();
         if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(bundleCode)) {
             try {
-                const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundleCode);
+                const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(bundleCode, {
+                    requireCurrentGuestApi: true,
+                    packageName: pkg.name,
+                });
                 return await this._installIsolated(pkg, artifact, selectedPackageVersion, usingLocalBundle, force, assertCurrent);
             }
             catch (err) {
@@ -920,7 +923,7 @@ class PackageLoader {
         await this.catalogReady;
         assertCurrent();
         const replacingIsolated = this.isolatedRuntime?.isInstalled(pkg.packageId) ?? false;
-        const instance = await this._evaluateBundle(pkg, bundleCode, selectedPackageVersion, force, assertCurrent);
+        const instance = await this._evaluateBundle(pkg, bundleCode, selectedPackageVersion, assertCurrent);
         if (!instance) {
             return undefined;
         }
@@ -995,7 +998,7 @@ class PackageLoader {
         });
         return instance;
     }
-    async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, force, assertCurrent = this.guardLoad(pkg.packageId)) {
+    async _evaluateBundle(pkg, bundleCode, selectedPackageVersion, assertCurrent = this.guardLoad(pkg.packageId)) {
         // 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
@@ -1063,19 +1066,16 @@ class PackageLoader {
             const bundleFunction = new Function("module", "exports", "require", bundleCode);
             const activateResolvers = (0, contract_resolvers_1.stagePackageContractResolvers)(this.dataContext, pkg.packageId, () => bundleFunction(module, moduleExports, customRequire));
             const bundleExports = module.exports;
-            // Check for contract-based package definition (new path)
+            // Host bundles must export a definePackage() definition.
             const packageDefinition = (0, contract_package_loader_1.extractPackageDefinition)(bundleExports);
             if (packageDefinition) {
                 if (packageDefinition.packageId !== pkg.packageId) {
                     console.warn(`[PackageLoader] packageId mismatch: definition has "${packageDefinition.packageId}" but DB record has "${pkg.packageId}"`);
                 }
-                // Build a proper IPeersPackage from the contract definition so callers
-                // (e.g. package-installer) can read appNavs, assistants, etc.
+                // Expose loaded identity and navigation to callers such as package-installer.
                 const contractPackageInstance = {
                     packageId: packageDefinition.packageId,
                     appNavs: packageDefinition.appNavs,
-                    assistants: packageDefinition.assistants,
-                    tableDefinitions: packageDefinition.tableDefinitions,
                 };
                 await (0, contract_package_loader_1.installContractPackage)(this.dataContext, packageDefinition, {
                     registry: this.contractRegistry,
@@ -1100,36 +1100,7 @@ class PackageLoader {
                 assertCurrent();
                 return contractPackageInstance;
             }
-            // Legacy path: extract IPeersPackage for backward compat
-            const packageInstance = bundleExports?.exports || bundleExports?.package || bundleExports?.default || bundleExports;
-            if (packageInstance &&
-                typeof packageInstance === "object" &&
-                typeof packageInstance.packageId === "string" &&
-                packageInstance.packageId.length > 0) {
-                const tools = packageInstance.toolInstances;
-                if (Array.isArray(tools) && tools.length)
-                    throw new Error(`Package '${pkg.name}' (${pkg.packageId}) ships legacy executable tools, which this runtime no longer runs; upgrade it to definePackage() contract tools (docs/Packages/contracts.md#migrating-from-toolinstances)`);
-                await this.toolCatalog.publish(pkg.packageId, [], async () => assertCurrent(), () => {
-                    assertCurrent();
-                    // Final catalog writes must succeed before changing active host tables.
-                    if (packageInstance.tableDefinitions?.length) {
-                        this.dataContext.tableContainer.registerTableDefinitions(packageInstance.tableDefinitions, { overwrite: true });
-                    }
-                    activateResolvers();
-                    this.retireHostEndpoints(pkg.packageId);
-                    if (force && this.contractInstalledPackages.has(pkg.packageId)) {
-                        this.contractRegistry.unregister(pkg.packageId);
-                        this.contractInstalledPackages.delete(pkg.packageId);
-                    }
-                    this.packageInstances[pkg.packageId] = packageInstance;
-                    this.recordRunning(pkg.packageId, {
-                        ...runningVersionFields(selectedPackageVersion),
-                        kind: "legacy",
-                    });
-                });
-                return packageInstance;
-            }
-            throw new Error("Package bundle exports nothing usable");
+            throw new Error(`Package '${pkg.name}' (${pkg.packageId}) has an unsupported bundle format. Rebuild it with definePackage() and peers-package.`);
         }
         catch (err) {
             this.recordLoadFailure(pkg.packageId, selectedPackageVersion, err, assertCurrent);