@peers-app/peers-sdk 0.26.5 → 0.27.0

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

@@ -16,21 +16,66 @@ const package_dev_tools_1 = require("./package-dev-tools");
 const package_installer_1 = require("./package-installer");
 const DEFAULT_TEMPLATE_REPO = "https://github.com/peers-app/peers-package-template.git";
 const TEMPLATE_CACHE_DIR = ".peers-package-template";
-function patchTemplateTokens(contents, values) {
-    return contents
-        .replaceAll("<package-name>", values.packageName)
-        .replaceAll("<package-id>", values.packageId)
-        .replaceAll("<app-screen-id>", values.appScreenId)
-        .replaceAll("<contract-id>", values.contractId);
+/** Template files the creator fills in: the ids (in `src/ids.json` in older templates) and README. */
+const TEMPLATE_TOKEN_FILES = [["src", "ids.json"], ["src", "consts.ts"], ["README.md"]];
+/**
+ * A TypeScript string expression for `value`, usually quoted as Biome quotes a literal.
+ * Encode names containing text SES rejects even inside strings, so the bundled declaration
+ * can use the same display name without making a newly created package fail to build.
+ */
+function sourceStringLiteral(value) {
+    if (/(?:<!--|-->|\b(?:import|eval)\s*(?:\(|\/[/*]))/.test(value)) {
+        const encoded = JSON.stringify(value).replace(/[<>()/]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+        return `String(JSON.parse(${sourceStringLiteral(encoded)}))`;
+    }
+    // JSON leaves U+2028 and U+2029 unescaped, and Biome's formatter reads them as line breaks.
+    const json = JSON.stringify(value).replace(/[\u2028\u2029]/g, (separator) => `\\u${separator.charCodeAt(0).toString(16)}`);
+    if (value.split('"').length <= value.split("'").length) {
+        return json;
+    }
+    // JSON escapes every backslash, so each `\"` left in its body is an escaped quote.
+    return `'${json.slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+}
+/**
+ * Fill in a template file's tokens. A quoted `"<package-name>"` becomes a string expression in the
+ * file's own syntax, so a name with quotes or backslashes still makes valid source.
+ */
+function patchTemplateTokens(contents, fileName, values) {
+    const quotedName = fileName.endsWith(".json")
+        ? JSON.stringify(values.packageName)
+        : fileName.endsWith(".ts")
+            ? sourceStringLiteral(values.packageName)
+            : `"${values.packageName}"`;
+    // Replace once: names may themselves contain tokens or replacement patterns such as `$&`.
+    const replacements = {
+        '"<package-name>"': quotedName,
+        "<package-name>": values.packageName,
+        "<package-id>": values.packageId,
+        "<app-screen-id>": values.appScreenId,
+        "<contract-id>": values.contractId,
+    };
+    return contents.replace(/"<package-name>"|<package-name>|<package-id>|<app-screen-id>|<contract-id>/g, (token) => replacements[token]);
 }
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
+ * Keeps existing ASCII slugs so creation still imports folders made by older creators.
+ * Uses Unicode letters/numbers when the ASCII slug is empty, or a fresh package folder for
+ * names with no letters or numbers, rather than resolving to the packages root.
+ * Shortens names exceeding a filesystem component's byte limit with a stable hash suffix.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"
  */
 function nameToFolderSlug(name) {
-    let slug = name.replace(/[^a-zA-Z0-9]/g, " ");
+    let slug = name.replace(/[^a-zA-Z0-9]/g, " ").trim();
+    if (!slug)
+        slug = name.replace(/[^\p{L}\p{N}]/gu, " ");
     slug = slug.replace(/\s+/g, " ").trim();
-    return (0, utils_1.camelCaseToHyphens)(slug);
+    if (!slug)
+        return `package-${(0, utils_1.newid)()}`;
+    const folder = (0, utils_1.camelCaseToHyphens)(slug);
+    if (new TextEncoder().encode(folder).length <= 240)
+        return folder;
+    // Fifty code points use at most 200 UTF-8 bytes, leaving room for the suffix under 255.
+    return `${Array.from(folder).slice(0, 50).join("")}-${(0, utils_1.simpleHash)(name).toString(36)}`;
 }
 const OFFLINE_PULL_PATTERN = /unable to access|could not resolve host|failed to connect|connection (refused|timed out|reset)|network is unreachable|enotfound|etimedout|eai_again|offline|ssl connect error|could not fetch/i;
 /**
@@ -320,23 +365,19 @@ async function createPackage(dataContext, deps, opts) {
         packageObj.author = opts.author;
     }
     delete packageObj.repository;
-    await deps.fs.writeFile(packageJsonPath, JSON.stringify(packageObj, null, 2));
-    // Patch the isolated template's canonical IDs. consts.ts remains supported for custom
-    // legacy templates created before isolated package artifacts became the default.
+    await deps.fs.writeFile(packageJsonPath, `${JSON.stringify(packageObj, null, 2)}\n`);
+    // Fill in the template's ids and name.
     const templateValues = {
         packageId,
         packageName: opts.name,
         appScreenId,
         contractId,
     };
-    for (const relativePath of [
-        ["src", "ids.json"],
-        ["src", "consts.ts"],
-    ]) {
+    for (const relativePath of TEMPLATE_TOKEN_FILES) {
         const templatePath = deps.resolvePath(location, ...relativePath);
         if (await deps.fs.exists(templatePath)) {
             const contents = await deps.fs.readFile(templatePath);
-            await deps.fs.writeFile(templatePath, patchTemplateTokens(contents, templateValues));
+            await deps.fs.writeFile(templatePath, patchTemplateTokens(contents, relativePath[relativePath.length - 1], templateValues));
         }
     }
     // Initialize as a new project: remove template git history, install, build, fresh git

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

@@ -100,6 +100,21 @@ describe("nameToFolderSlug", () => {
     it("collapses multiple spaces", () => {
         expect((0, package_creator_1.nameToFolderSlug)("too   many   spaces")).toBe("too-many-spaces");
     });
+    it("preserves non-ASCII names and allocates a folder for symbol-only names", () => {
+        expect((0, package_creator_1.nameToFolderSlug)("買い物")).toBe("買い物");
+        expect((0, package_creator_1.nameToFolderSlug)("Café 漢字")).toBe("caf"); // Keep older creators' folder names.
+        const first = (0, package_creator_1.nameToFolderSlug)("🛒");
+        expect(first).toMatch(/^package-[a-z0-9]{25}$/);
+        expect((0, package_creator_1.nameToFolderSlug)("🛒")).not.toBe(first);
+    });
+    it("keeps long ASCII and Unicode names within a filesystem component's byte limit", () => {
+        for (const name of ["Long Name ".repeat(40), "漢".repeat(100)]) {
+            const folder = (0, package_creator_1.nameToFolderSlug)(name);
+            expect(Buffer.byteLength(folder, "utf8")).toBeLessThanOrEqual(255);
+            expect((0, package_creator_1.nameToFolderSlug)(name)).toBe(folder);
+            expect((0, package_creator_1.nameToFolderSlug)(`${name}more`)).not.toBe(folder);
+        }
+    });
 });
 describe("createPackage", () => {
     it("fails before scaffolding when Node.js or npm is missing", async () => {
@@ -458,6 +473,77 @@ describe("createPackage", () => {
         mockGetPackageInfo.mockResolvedValue({ name: "no-id-pkg" });
         await expect((0, package_creator_1.createPackage)(dc, deps, { name: "bad-pkg", location: "/some/path" })).rejects.toThrow("does not contain a valid Peers package");
     });
+    it("fills in the template's consts.ts and README, with the name as one string expression", async () => {
+        const template = {
+            "/packages/x/src/consts.ts": [
+                'export const packageId = "<package-id>";',
+                'export const packageName = "<package-name>";',
+                'export const contractId = "<contract-id>";',
+                'export const appScreenId = "<app-screen-id>";',
+            ].join("\n"),
+            "/packages/x/README.md": "# <package-name>\n",
+            "/packages/x/src/ids.json": '{"packageName":"<package-name>","packageId":"<package-id>"}',
+        };
+        async function create(name) {
+            const deps = makeMockDeps({});
+            deps.fs.exists.mockImplementation(async (path) => path in template);
+            deps.fs.readFile.mockImplementation(async (path) => template[path]);
+            deps.fs.readJson.mockResolvedValue({ name: "template", peers: {} });
+            mockGroupDeviceVar.mockReturnValue(jest.fn());
+            mockInstallPackageFromBundles.mockResolvedValue({
+                packageVersion: { packageVersionId: "pv" },
+                loaded: undefined,
+                unchanged: false,
+            });
+            await (0, package_creator_1.createPackage)(mockDataContext(), deps, { name, location: "/packages/x" });
+            const written = (path) => deps.fs.writeFile.mock.calls.find((call) => call[0] === path)[1];
+            const consts = written("/packages/x/src/consts.ts");
+            const literal = /packageName = (.*);/.exec(consts)?.[1] ?? "";
+            return {
+                consts,
+                literal,
+                readme: written("/packages/x/README.md"),
+                ids: JSON.parse(written("/packages/x/src/ids.json")),
+            };
+        }
+        const plain = await create("My Widget");
+        expect(plain.literal).toBe('"My Widget"');
+        expect(plain.consts).toMatch(/packageId = "[a-z0-9]{25}";/);
+        expect(plain.consts).not.toContain("<");
+        expect(plain.readme).toBe("# My Widget\n");
+        expect((await create("Cash $& Carry")).readme).toBe("# Cash $& Carry\n");
+        // Quoted as Biome's formatter would, so a new package passes `npm run lint`.
+        for (const [name, literal] of [
+            ["Mark's List", `"Mark's List"`],
+            ['The "Best" List', `'The "Best" List'`],
+            [`Mark's "Best" \\ List`, `'Mark\\'s "Best" \\\\ List'`],
+            ["Cash $& Carry", `"Cash $& Carry"`],
+            ["Café 漢字 🥛", `"Café 漢字 🥛"`],
+            ["Line\u2028and\u2029paragraph", `"Line\\u2028and\\u2029paragraph"`],
+            ['Say "hi"\u2028twice', `'Say "hi"\\u2028twice'`],
+            ["A <package-name> <package-id>", `"A <package-name> <package-id>"`],
+        ]) {
+            const created = await create(name);
+            expect(created.literal).toBe(literal);
+            expect(new Function(`return ${created.literal};`)()).toBe(name);
+            expect(created.readme).toBe(`# ${name}\n`);
+            expect(created.ids.packageName).toBe(name);
+            expect(created.ids.packageId).toMatch(/^[a-z0-9]{25}$/);
+        }
+        for (const name of [
+            "List <!-- comments -->",
+            "List import( jokes",
+            "List import /* notes",
+            'List eval( "quoted" \\ 漢字\u2028',
+        ]) {
+            const created = await create(name);
+            expect(created.literal).toMatch(/^String\(JSON.parse\(/);
+            expect(created.literal).not.toMatch(/<!--|-->|\b(?:import|eval)\s*(?:\(|\/[/*])/);
+            expect(new Function(`return ${created.literal};`)()).toBe(name);
+            expect(created.ids.packageName).toBe(name);
+            expect(created.readme).toBe(`# ${name}\n`);
+        }
+    });
     it("uses direct clone (no caching) when custom templateRepo is provided", async () => {
         const deps = makeMockDeps({});
         const dc = mockDataContext();

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

@@ -0,0 +1,53 @@
+/**
+ * How the host and a guest API 3 provider talk about contract members: the guest handler names
+ * the host invokes and what they carry. Kept apart from the manifest code so a provider bundle
+ * can import it cheaply.
+ */
+/**
+ * Guest handler name the host invokes with a consumer's call on one of a contract's tables,
+ * observables, or events (guest API 3). It takes an {@link IIsolatedContractMemberCall} under
+ * the caller's authority.
+ *
+ * @param contractId - The provided contract's id.
+ * @param version - The provided contract's version.
+ */
+export declare function contractMemberHandlerName(contractId: string, version: number): string;
+/**
+ * Guest handler name the host invokes with each table change, event, or observable value bound
+ * for one subscriber (guest API 3), under that subscriber's authority. It takes an
+ * {@link IIsolatedContractDelivery} and returns an {@link IIsolatedContractDeliveryResult}.
+ *
+ * @param contractId - The provided contract's id.
+ * @param version - The provided contract's version.
+ */
+export declare function contractDeliveryHandlerName(contractId: string, version: number): string;
+/** A consumer's call on a contract member, as the provider's worker receives it. */
+export interface IIsolatedContractMemberCall {
+    /** Which kind of member. Tools have their own handlers. */
+    member: "table" | "observable" | "event";
+    /** The member's name in the contract. */
+    name: string;
+    /**
+     * A table method (`get`, `list`, `count`, `findOne`, `save`, `delete`), an observable's `get`
+     * or `set`, or `subscribe` / `unsubscribe` (table `dataChanged`, events, observables).
+     */
+    operation: string;
+    /** The call's arguments. */
+    args: unknown[];
+}
+/** One outgoing message for one subscriber, as the provider's worker receives it. */
+export interface IIsolatedContractDelivery {
+    /** A table's `dataChanged`, an event, or an observable's value. */
+    member: "table" | "observable" | "event";
+    /** The member's name in the contract. */
+    name: string;
+    /** The change event, event payload, or observable value. */
+    value: unknown;
+}
+/** What the provider does with an outgoing message: send it (possibly changed), or drop it. */
+export interface IIsolatedContractDeliveryResult {
+    /** False drops the message for this subscriber. */
+    send: boolean;
+    /** What to send when `send` is true. */
+    value?: unknown;
+}

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

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * How the host and a guest API 3 provider talk about contract members: the guest handler names
+ * the host invokes and what they carry. Kept apart from the manifest code so a provider bundle
+ * can import it cheaply.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractMemberHandlerName = contractMemberHandlerName;
+exports.contractDeliveryHandlerName = contractDeliveryHandlerName;
+/**
+ * Guest handler name the host invokes with a consumer's call on one of a contract's tables,
+ * observables, or events (guest API 3). It takes an {@link IIsolatedContractMemberCall} under
+ * the caller's authority.
+ *
+ * @param contractId - The provided contract's id.
+ * @param version - The provided contract's version.
+ */
+function contractMemberHandlerName(contractId, version) {
+    return `contract:${JSON.stringify([contractId, version])}`;
+}
+/**
+ * Guest handler name the host invokes with each table change, event, or observable value bound
+ * for one subscriber (guest API 3), under that subscriber's authority. It takes an
+ * {@link IIsolatedContractDelivery} and returns an {@link IIsolatedContractDeliveryResult}.
+ *
+ * @param contractId - The provided contract's id.
+ * @param version - The provided contract's version.
+ */
+function contractDeliveryHandlerName(contractId, version) {
+    return `deliver:${JSON.stringify([contractId, version])}`;
+}

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

@@ -30,7 +30,11 @@ async function installContractPackage(dataContext, packageDefinition, opts) {
         const definition = existing && !existing.devTag && contract.devTag === "dev"
             ? { ...contract, devTag: undefined }
             : contract;
-        return { definition, alsoImplements: packageDefinition.alsoImplements.get(key) ?? [] };
+        return {
+            definition,
+            alsoImplements: packageDefinition.alsoImplements.get(key) ?? [],
+            exposes: packageDefinition.exposes?.get(key) ?? [],
+        };
     });
     const catalog = registry.toolCatalog ?? new tool_catalog_1.ToolCatalog(dataContext, registry);
     const prepare = async () => {

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

@@ -91,6 +91,17 @@ describe("installContractPackage registry wiring", () => {
         expect(registry.getProviderPackageId(contractId, 1)).toBe(packageId);
         expect(registry.getContractKeysForPackage(packageId)).toEqual([`${contractId}@1`]);
     });
+    it("registers what a hub implementation exposes", async () => {
+        const registry = new registry_1.ContractRegistry();
+        const hubId = (0, utils_1.newid)();
+        const definition = makeDefinition({
+            exposes: new Map([[`${hubId}@1`, [{ contractId, version: 1 }]]]),
+        });
+        definition.contracts.push({ ...definition.contracts[0], contractId: hubId, name: "Hub" });
+        await (0, contract_package_loader_1.installContractPackage)(mockDataContext(), definition, { registry });
+        expect(registry.getExposedContracts(hubId, 1, packageId)).toEqual([{ contractId, version: 1 }]);
+        expect(registry.getExposedContracts(contractId, 1, packageId)).toEqual([]);
+    });
     it("persists CLI runner metadata without executable registration", async () => {
         const registry = new registry_1.ContractRegistry();
         const context = mockDataContext();

package/dist/package-loader/host-authority-loading.test.js

@@ -50,22 +50,26 @@ test("host-backed package endpoints honor declared propagation and reread live m
         },
         toolFn: fn,
     });
-    const route = make("route", 20, (_, ctx) => ctx.dispatchAction("act", {}));
+    const route = make("route", 20, (_, ctx) => ctx.dispatchTool?.({ contractId, version: 1, toolName: "target", providerPackageId: packageId }, {}));
     route.tool.authorityPropagation = "preserve";
     const effect = jest.fn(() => "admin target");
     (0, index_1.registerContractResolver)(contractId, 1, () => ({
         contractId,
         version: 1,
-        tools: { route },
-        actionAliases: { act: "target" },
-        actionTools: { target: make("target", 60, effect) },
+        forwardCallContext: true,
+        tools: { route, target: make("target", 60, effect) },
     }), { providerPackageId: packageId });
     loader.contractRegistry.register(packageId, {
         contractId,
         version: 1,
         name: "Arbitrary",
         description: "",
-        tools: [{ name: "route", usageDescription: "route", inputFields: [], outputFields: [] }],
+        tools: ["route", "target"].map((name) => ({
+            name,
+            usageDescription: name,
+            inputFields: [],
+            outputFields: [],
+        })),
         tables: [],
         observables: [],
         events: [],

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

@@ -1,3 +1,4 @@
+export * from "./contract-members";
 export * from "./contract-package-loader";
 export * from "./isolated-artifact";
 export * from "./isolated-persistent-var-gateway";

package/dist/package-loader/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contract-members"), exports);
 __exportStar(require("./contract-package-loader"), exports);
 __exportStar(require("./isolated-artifact"), exports);
 __exportStar(require("./isolated-persistent-var-gateway"), exports);

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

@@ -1,4 +1,4 @@
-import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTool } from "../contracts/types";
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTool, IExposedContract } from "../contracts/types";
 import { type PersistentVarScope } from "../data/persistent-var-identity";
 import type { IAppNav } from "../types/app-nav";
 import { type IField } from "../types/field-type";
@@ -46,10 +46,36 @@ export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields"
      *
      * When omitted, the runtime's `invokeTimeoutMs` applies. Capped at
      * {@link ISOLATED_TOOL_TIMEOUT_MAX_MS}. Host calls made during the invoke,
-     * including System HTTP, count against this deadline.
+     * 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.
      */
     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.
+ */
+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;
 /** Longest per-tool invoke deadline an isolated manifest may declare. */
 export declare const ISOLATED_TOOL_TIMEOUT_MAX_MS = 120000;
 /**
@@ -92,6 +118,13 @@ export interface IIsolatedPackageTable {
     fields: IField[];
     /** Schema version for host table-definition updates. Defaults to `1`. */
     versionNumber?: number;
+    /**
+     * Keep rows on the device that writes them: no change rows are recorded, so no row syncs.
+     * The schema still syncs, so every device in the group has its own copy of the table. Changing
+     * it is a schema change, so it needs a higher `versionNumber`. It is storage policy, never part
+     * of a contract's table shape.
+     */
+    localOnly?: boolean;
 }
 /** Name-only reference that exposes one package table through a contract. */
 export interface IIsolatedContractTableRef {
@@ -103,12 +136,17 @@ export interface IIsolatedContractPersistentVarBinding {
     name: string;
     defaultValue: unknown;
 }
-/** Observable contract member backed by a package-owned persistent variable. */
+/**
+ * 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.
+ */
 export interface IIsolatedContractObservable extends IContractObservable {
-    persistentVar: IIsolatedContractPersistentVarBinding;
+    persistentVar?: IIsolatedContractPersistentVarBinding;
 }
 /**
- * Event an isolated provider may emit from an active tool invocation.
+ * Event an isolated provider may emit at any time while its current worker runs.
  *
  * Shape matches {@link IContractEvent}. `payloadFields` defaults to `[]`
  * during validation when omitted. Events are host-owned: the worker emits via
@@ -128,12 +166,17 @@ export interface IIsolatedProvidedContract {
     tools: IIsolatedContractTool[];
     /** Name-only references to package tables exposed to consumers. */
     tables?: IIsolatedContractTableRef[];
-    /** Pvar-backed observable values exposed to consumers. */
+    /** Observable values exposed to consumers, stored in a pvar or held by the worker. */
     observables?: IIsolatedContractObservable[];
-    /** Events the worker may emit during an active invocation. */
+    /** Events the worker may emit with `emitContractEvent`, at any time while it runs. */
     events?: IIsolatedContractEvent[];
     /** Older contract versions this provider shape also satisfies. */
     alsoImplements?: IAlsoImplementsDeclaration[];
+    /**
+     * Other contracts this package provides whose tools this contract's consumers may call on
+     * it: set when this contract is a hub's, such as Voice Skill. Not part of the contract's shape.
+     */
+    exposes?: IExposedContract[];
 }
 /** Contract this package is allowed to call through the trusted host. */
 export interface IIsolatedConsumedContract {
@@ -143,11 +186,6 @@ export interface IIsolatedConsumedContract {
     providerPackageIds?: string[];
     fallbackToDefaultProvider?: boolean;
 }
-/** Package-owned catalog selector bound to a registered canonical action. */
-export interface IIsolatedActionAlias {
-    name: string;
-    target: IIsolatedContractToolRef;
-}
 /**
  * Pure-data package description. Validated on the host; never executed there.
  */
@@ -171,8 +209,12 @@ export interface IIsolatedPackageManifest {
      */
     network?: IIsolatedPackageNetwork;
     appNavs?: IAppNav[];
-    /** Private checked targets, independent of the frozen Voice Skill catalog. */
-    actionAliases?: IIsolatedActionAlias[];
+    /**
+     * 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.
+     */
+    guestApi?: IsolatedGuestApi;
 }
 /**
  * Installable isolated package: declarative manifest plus provider source
@@ -205,8 +247,6 @@ export interface IIsolatedInstalledPackage {
     tables: IIsolatedPackageTable[];
     definitions: IContractDefinition[];
     appNavs?: IAppNav[];
-    /** Private checked targets, independent of the frozen Voice Skill catalog. */
-    actionAliases?: IIsolatedActionAlias[];
 }
 /** Host-contract member guests use to request a consumed-contract tool call. */
 export declare const ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
@@ -216,6 +256,22 @@ export declare const ISOLATED_TABLE_HOST_MEMBER = "package.table";
 export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 /** Host-contract member guests use to emit a provided-contract event. */
 export declare const ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
+/** Host-contract member guests use to publish an in-memory provided-contract observable. */
+export declare const ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
+/**
+ * How deep field lists may nest through object `fields`: a tool's inputs, say, are level 1.
+ * Deeper nesting is refused, so a hostile manifest can't exhaust the validator's stack.
+ */
+export declare const ISOLATED_MAX_FIELD_DEPTH = 16;
+/**
+ * True when `value` may appear in `enumValues` on a field of `type`: a string, number, or boolean
+ * of that type, or any of them on `any`. Shared with the manifest builder; not a public SDK export.
+ *
+ * @internal
+ * @param value - A candidate enum value.
+ * @param type - The field's type.
+ */
+export declare function enumValueFits(value: unknown, type: string): boolean;
 /**
  * True when `bundle` starts with {@link ISOLATED_PACKAGE_MAGIC}.
  *
@@ -229,11 +285,18 @@ export declare function looksLikeIsolatedPackageArtifact(bundle: string): boolea
  * Validate a wire-safe isolated package artifact. Does not evaluate
  * `providerSource`.
  *
+ * Fields keep only the keys this SDK knows: a host drops any other field key, since a newer
+ * SDK's keys only describe values further.
+ *
  * @param artifact - Parsed artifact object.
+ * @param options - `strict` refuses field keys this SDK doesn't know instead; the package build
+ *   uses it, where an unknown key is a mistake.
  * @returns The same manifest after in-place field normalization.
  * @throws If identity, contracts, tools, or source are invalid.
  */
-export declare function validateIsolatedPackageArtifact(artifact: IIsolatedPackageArtifact): IIsolatedPackageManifest;
+export declare function validateIsolatedPackageArtifact(artifact: IIsolatedPackageArtifact, options?: {
+    strict?: boolean;
+}): IIsolatedPackageManifest;
 /**
  * Parse a magic-header + JSON isolated package bundle.
  *