@peers-app/peers-sdk 0.28.5 → 0.28.7

package/README.md

@@ -32,7 +32,7 @@ NaCl-based key management, message signing and verification, box encryption, and
 
 ### Tools Framework
 
-Define AI-callable tools with `ITool` and `IToolInstance`. Tools are registered at runtime and available to built-in and user-defined AI assistants and workflows.
+Declare AI-callable tools with `definePackage()` and provide their implementations through contract resolvers. Use `IContractToolImplementation` for provider implementations.
 
 ### Identity and Groups
 
@@ -58,7 +58,7 @@ The fastest way to build a Peers package is to start from the template:
 | `DataQuery` / `DataFilter`           | Mongo-style query filters translated to SQL                             |
 | `observable()` / `computed()`        | Reactive state primitives                                               |
 | `deviceVar` / `userVar` / `groupVar` | Persistent variables — observables backed by the database               |
-| `ITool` / `IToolInstance`            | AI-callable tool definitions                                            |
+| `ITool` / `IContractToolImplementation`            | AI-callable tool definitions                                            |
 | `IPeersUI` / `IPeersUIRoute`         | Screen and route declarations for package UIs                           |
 | `newid()`                            | Generate 25-character time-sortable peer IDs                            |
 | `newKeys()` / `hydrateKeys()`        | Cryptographic key pair generation and hydration                         |

package/dist/contracts/builder.d.ts

@@ -18,7 +18,6 @@ export declare class ContractBuilder {
     private _events;
     private _alsoImplements;
     private _exposes;
-    private warnedAboutToolInstances;
     /** Full table definitions for this contract (used by the install flow). */
     private _tableDefinitions;
     constructor(contractId: string, version: number, name: string, description?: string | undefined);
@@ -35,11 +34,6 @@ export declare class ContractBuilder {
      */
     set events(events: IContractEvent[]);
     get events(): IContractEvent[];
-    /**
-     * Discard executable assignments from bundles compiled against an older SDK.
-     * @deprecated Implement tools with registerContractResolver instead.
-     */
-    set toolInstances(_instances: never);
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs: ITableDefinition[]);
     get tableDefinitions(): ITableDefinition[];

package/dist/contracts/builder.js

@@ -26,7 +26,6 @@ class ContractBuilder {
     _events = [];
     _alsoImplements = [];
     _exposes = [];
-    warnedAboutToolInstances = false;
     /** Full table definitions for this contract (used by the install flow). */
     _tableDefinitions = [];
     constructor(contractId, version, name, description) {
@@ -64,16 +63,6 @@ class ContractBuilder {
     get events() {
         return this._events;
     }
-    /**
-     * Discard executable assignments from bundles compiled against an older SDK.
-     * @deprecated Implement tools with registerContractResolver instead.
-     */
-    set toolInstances(_instances) {
-        if (this.warnedAboutToolInstances)
-            return;
-        this.warnedAboutToolInstances = true;
-        console.warn(`Contract ${this.name} (${this.contractId}@${this.version}) assigned toolInstances, which no longer run; implement these tools with registerContractResolver (docs/Packages/contracts.md#migrating-from-toolinstances)`);
-    }
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs) {
         this._tableDefinitions = defs;

package/dist/contracts/contract-proxy.d.ts

@@ -1,6 +1,7 @@
+import type { z } from "zod";
 import type { DataContext } from "../context/data-context";
 import type { Table } from "../data/orm/table";
-import type { ITool, IToolInstance } from "../data/tools";
+import type { ITool } from "../data/tools";
 import type { Event, ISubscriptionResult } from "../events";
 import { type Observable } from "../observable";
 import { type IIsolatedCallPrincipal } from "../package-loader/isolated-runtime";
@@ -359,15 +360,15 @@ export declare function createRemoteContractConsumer(contract: IContractDefiniti
     dataContextId?: string;
 }): IRemoteContractConsumer<IContractConsumer>;
 /**
- * Provider-local executable metadata. Existing IToolInstance values remain assignable;
- * new implementations need no catalog ID, persisted row, or executable registration.
+ * Provider-local executable metadata for contract tools.
+ * Implementations need no catalog ID, persisted row, or executable registration.
  */
 export interface IContractToolImplementation {
     /** Provider metadata; the contract member name supplies identity, without a Tools row. */
     tool: Pick<ITool, "name" | "usageDescription"> & Partial<Pick<ITool, "toolId" | "detailedDescription" | "inputSchema" | "outputSchema" | "accessLevel" | "authorityPropagation" | "remoteAccessLevel">>;
-    toolFn: IToolInstance["toolFn"];
-    inputSchema?: IToolInstance["inputSchema"];
-    outputSchema?: IToolInstance["outputSchema"];
+    toolFn: (...args: any[]) => any;
+    inputSchema?: z.ZodObject<any>;
+    outputSchema?: z.ZodObject<any>;
 }
 /** Context-bound live members of a provider; executable ownership stays with the contract. */
 export interface IContractResolution {

package/dist/contracts/extract.d.ts

@@ -18,7 +18,7 @@ export interface IExtractableTableDef {
 }
 /**
  * Minimal tool-instance shape accepted by extractToolShape.
- * Mirrors the subset of IToolInstance we need.
+ * Mirrors the subset of IContractToolImplementation we need.
  */
 export interface IExtractableToolInstance {
     /** Host-only workflow policy carried into the contract definition. */

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

@@ -18,14 +18,12 @@ exports.hasDeviceFollowOverride = hasDeviceFollowOverride;
 exports.readStoredPackageLocalPath = readStoredPackageLocalPath;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const keys_1 = require("../keys");
-const assistants_1 = require("./assistants");
 const file_types_1 = require("./files/file.types");
 const group_member_roles_1 = require("./group-member-roles");
 const group_permissions_1 = require("./group-permissions");
 const package_versions_1 = require("./package-versions");
 const packages_1 = require("./packages");
 const persistent_vars_1 = require("./persistent-vars");
-const workflows_1 = require("./workflows");
 /**
  * Reactive, cached observable holding device-local preferences for a single
  * package. Backed by a `groupDeviceVar` so the UI can subscribe via
@@ -344,9 +342,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         }
         return { loaded: false, upgraded: false };
     }
-    // Load succeeded - install assistants/workflows, then persist the activation
-    // either as a group-level active version or as device-local state.
-    await installPackageContents(dataContext, pkg, instance);
+    // Load succeeded; persist activation as a group default or device-local state.
     // When the device is following group settings (no device-level follow
     // override) and the upgraded version is non-dev, also advance the group's
     // activePackageVersionId so other devices stay in sync. Only admin+ users
@@ -436,20 +432,6 @@ async function loadOlderCompatiblePackageVersion(pkg, dataContext, unavailableVe
     }
     return undefined;
 }
-/**
- * Save a loaded package's assistants and workflows into the data context.
- * Contract-installed packages are skipped because their content is already
- * managed by the contract loader.
- */
-async function installPackageContents(dataContext, pkg, instance) {
-    if (dataContext.packageLoader.isContractInstalled(pkg.packageId))
-        return;
-    const saves = [
-        ...(instance.assistants?.map((a) => (0, assistants_1.Assistants)(dataContext).save(a)) ?? []),
-        ...(instance.workflows?.map((w) => (0, workflows_1.Workflows)(dataContext).save(w)) ?? []),
-    ];
-    await Promise.all(saves);
-}
 /**
  * Returns true when the device has an explicit follow-policy override
  * (`followRange`, `followTags`, or `pinned`). Used by the UI to drive the

package/dist/data/packages.utils.d.ts

@@ -1,3 +1,7 @@
 import type { DataContext } from "../context/data-context";
 import { type IPackage } from "./packages";
+/**
+ * Copy a package and its active version's bundles into another context.
+ * Restores an uninstalled package; uninstall keeps version and file rows.
+ */
 export declare function copyPackageToAnotherDataContext(packageId: string, fromDataContext: DataContext, toDataContext: DataContext): Promise<IPackage>;

package/dist/data/packages.utils.js

@@ -15,6 +15,10 @@ async function copyBundleFile(fileId, fromFiles, toFiles, label) {
         console.warn(`${label} file ${fileId} not found in source context`);
     }
 }
+/**
+ * Copy a package and its active version's bundles into another context.
+ * Restores an uninstalled package; uninstall keeps version and file rows.
+ */
 async function copyPackageToAnotherDataContext(packageId, fromDataContext, toDataContext) {
     const fromPackages = (0, packages_1.Packages)(fromDataContext);
     const toPackages = (0, packages_1.Packages)(toDataContext);
@@ -35,5 +39,5 @@ async function copyPackageToAnotherDataContext(packageId, fromDataContext, toDat
             await toPvTable.signAndSave(pv, { saveAsSnapshot: true });
         }
     }
-    return toPackages.signAndSave(pkg);
+    return toPackages.signAndSave(pkg, { restoreIfDeleted: true, saveAsSnapshot: true });
 }

package/dist/data/tools.d.ts

@@ -172,16 +172,6 @@ export declare const toolSchema: z.ZodObject<{
 }>;
 /** A tool definition stored in the Tools table. */
 export type ITool = z.infer<typeof toolSchema>;
-/**
- * Historical tool instance shape used by older packages.
- * @deprecated Use IContractToolImplementation with a contract resolver.
- */
-export interface IToolInstance {
-    tool: ITool;
-    toolFn: (...args: any[]) => any;
-    inputSchema?: z.ZodObject<any>;
-    outputSchema?: z.ZodObject<any>;
-}
 /**
  * Accessor for the Tools table.
  *

package/dist/define/context.d.ts

@@ -14,7 +14,7 @@ export interface IPackageProviderOptions {
     providerPackageId?: string;
 }
 /**
- * The host functions the Runtime gives one handler call (guest API 2 and 3).
+ * The host functions the Runtime gives one guest API 3 handler call.
  *
  * Every tool handler gets its own `ctx`, and host calls made through it act for that call's
  * caller, even while other calls run. The table and contract handles in this module take a
@@ -75,15 +75,13 @@ export interface IPackageContext {
     watchOwnedTable(tableName: string, handler: (event: IDataChangedEvent<unknown>) => unknown): Promise<PackageUnsubscribe>;
     /**
      * Set the value of an in-memory observable this package provides (one declared without a
-     * `persistentVar`). The host checks it against the observable's `valueType`, keeps it for
-     * readers, and pushes it to subscribers. Allowed at any time while the worker runs.
+     * `persistentVar`). The host checks it against the observable's `valueType` and pushes it
+     * to subscribers. Allowed at any time while the worker runs.
      */
     publishOwnedObservable(contractId: string, version: number, observableName: string, value: unknown): Promise<unknown>;
     /**
-     * Take guest API 2 consumers' writes to a writable in-memory observable this package
-     * provides. `handler` gets the value with no caller authority, stores and publishes it, and
-     * returns what it stored. A later call replaces the handler. Guest API 3 instead routes
-     * writes through the contract member handler under the caller's authority.
+     * Compatibility no-op retained for built guest API 3 bundles. Consumer writes are
+     * served through the contract member handler under the caller's authority.
      */
     onOwnedObservableSet(contractId: string, version: number, observableName: string, handler: (value: unknown) => unknown): void;
 }

package/dist/define/observables.js

@@ -162,8 +162,7 @@ async function serveObservable(observable, targets, ctx) {
     });
     serving.set(observable, () => subscription.dispose());
     if (definition.writable) {
-        // Guest API 3 calls this from its member handler under the caller's authority; guest
-        // API 2 uses onOwnedObservableSet without a caller frame. Both parse before writing.
+        // The member handler runs this under the caller's authority and parses before writing.
         const write = async (value) => {
             const next = schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, value)) : value;
             applying = true;
@@ -177,9 +176,6 @@ async function serveObservable(observable, targets, ctx) {
             return publish(source());
         };
         writers.set(observable, write);
-        for (const target of targets) {
-            ctx.onOwnedObservableSet(target.contractId, target.version, name, write);
-        }
     }
     // A successful start guarantees readers have a published value. Later background failures
     // are logged, but a failed initial publish must fail startup rather than silently serve null.

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);

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

@@ -24,9 +24,8 @@ export type PackageRuntimeStatus = "running" | "failed" | "unavailable" | "unsup
  *
  * - `isolated` — an isolated artifact served by the host's isolated runtime.
  * - `contract` — an in-process `definePackage()` bundle.
- * - `legacy` — an in-process legacy bundle without a package definition.
  */
-export type PackageRuntimeKind = "isolated" | "contract" | "legacy";
+export type PackageRuntimeKind = "isolated" | "contract";
 /** A contract a running package provides. */
 export interface IPackageRuntimeProvidedContract {
     /** Provided contract identity. */

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

@@ -1,16 +1,10 @@
-import type { IAssistant } from "../data";
-import type { ITableDefinition } from "../data/orm/table-definitions.type";
 import type { IPeersUI } from "../peers-ui/peers-ui";
 import type { IPeersUIRoute } from "../peers-ui/peers-ui.types";
 import type { IAppNav } from "./app-nav";
-import type { IWorkflow } from "./workflow";
-/** Host package tables, assistants and UI; tools are provided by contracts. */
+/** Identity and navigation of a loaded package; content is installed from its definition. */
 export interface IPeersPackage {
     packageId: string;
-    assistants?: IAssistant[];
-    workflows?: IWorkflow[];
     appNavs?: IAppNav[];
-    tableDefinitions?: ITableDefinition[];
 }
 /** Routes exported by a host package. */
 export interface IPeersPackageRoutes {

package/package.json

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