@peers-app/peers-sdk 0.26.6 → 0.27.0

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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_PACKAGE_MAGIC = void 0;
+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;
 exports.parseIsolatedPackageArtifact = parseIsolatedPackageArtifact;
@@ -15,6 +17,7 @@ exports.packageProvidesEvent = packageProvidesEvent;
 exports.packageProvidesTable = packageProvidesTable;
 exports.findPackageTable = findPackageTable;
 exports.toConsumedContracts = toConsumedContracts;
+const contract_definition_schema_1 = require("../contracts/contract-definition-schema");
 const access_level_1 = require("../data/access-level");
 const persistent_var_identity_1 = require("../data/persistent-var-identity");
 const field_type_1 = require("../types/field-type");
@@ -25,6 +28,30 @@ const utils_1 = require("../utils");
  * opt-in format without evaluating source.
  */
 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.
+ */
+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. */
@@ -35,6 +62,8 @@ exports.ISOLATED_TABLE_HOST_MEMBER = "package.table";
 exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
 /** Host-contract member guests use to emit a provided-contract event. */
 exports.ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
+/** Host-contract member guests use to publish an in-memory provided-contract observable. */
+exports.ISOLATED_OBSERVABLE_HOST_MEMBER = "package.observable";
 const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
 const OBSERVABLE_FIELD_TYPES = new Set([
     field_type_1.FieldType.id,
@@ -62,35 +91,139 @@ function assertContractVersion(version, label) {
         throw new Error(`${label} must be a positive integer, got ${String(version)}`);
     }
 }
-function validateFields(fields, label) {
+/**
+ * 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.
+ */
+exports.ISOLATED_MAX_FIELD_DEPTH = 16;
+/** Field keys this SDK knows. Hosts drop any other key; the build refuses it (likely a typo). */
+const FIELD_KEYS = new Set([
+    "name",
+    "description",
+    "type",
+    "defaultValue",
+    "optional",
+    "isArray",
+    "subType",
+    "fields",
+    "enumValues",
+]);
+/**
+ * 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.
+ */
+function enumValueFits(value, type) {
+    switch (type) {
+        case field_type_1.FieldType.string:
+            return typeof value === "string";
+        case field_type_1.FieldType.number:
+            return typeof value === "number" && Number.isFinite(value);
+        case field_type_1.FieldType.boolean:
+            return typeof value === "boolean";
+        case field_type_1.FieldType.any:
+            return (typeof value === "string" ||
+                typeof value === "boolean" ||
+                (typeof value === "number" && Number.isFinite(value)));
+        default:
+            return false;
+    }
+}
+/**
+ * Validate one field and rebuild it from the keys this SDK knows. A key it doesn't know can only
+ * describe the value further (a key the host must honor comes with a new guest API version, which
+ * older hosts refuse), so it is dropped, or refused when `strict`.
+ */
+function validateField(field, label, strict, depth, named = true) {
+    if (!field || typeof field !== "object" || Array.isArray(field)) {
+        throw new Error(`${label} must be an object`);
+    }
+    const record = field;
+    if (strict) {
+        const unsupported = Object.keys(record).find((key) => !FIELD_KEYS.has(key) || (!named && key === "name"));
+        if (unsupported) {
+            throw new Error(`${label}.${unsupported} is not supported by isolated package artifacts`);
+        }
+    }
+    if (named && (typeof record.name !== "string" || record.name.trim() === "")) {
+        throw new Error(`${label}.name is required`);
+    }
+    if (typeof record.type !== "string" || !FIELD_TYPES.has(record.type)) {
+        throw new Error(`${label}.type must be a FieldType`);
+    }
+    const type = record.type;
+    if (record.enumValues !== undefined) {
+        if (!Array.isArray(record.enumValues) || record.enumValues.length === 0) {
+            throw new Error(`${label}.enumValues must be a non-empty array`);
+        }
+        if (!record.enumValues.every((value) => enumValueFits(value, type))) {
+            throw new Error(`${label}.enumValues must all be ${type === field_type_1.FieldType.any ? "strings, numbers, or booleans" : `${type} values`}`);
+        }
+    }
+    let fields;
+    if (record.fields !== undefined) {
+        if (type !== field_type_1.FieldType.object) {
+            throw new Error(`${label}.fields is only allowed on object fields`);
+        }
+        if (depth >= exports.ISOLATED_MAX_FIELD_DEPTH) {
+            throw new Error(`${label}.fields nests more than ${exports.ISOLATED_MAX_FIELD_DEPTH} levels deep`);
+        }
+        fields = validateFields(record.fields, `${label}.fields`, strict, depth + 1);
+    }
+    return {
+        ...(named ? { name: record.name } : {}),
+        type,
+        ...(typeof record.description === "string" ? { description: record.description } : {}),
+        ...(record.optional === true ? { optional: true } : {}),
+        ...(record.isArray === true ? { isArray: true } : {}),
+        ...(typeof record.subType === "string" ? { subType: record.subType } : {}),
+        ...(record.defaultValue !== undefined ? { defaultValue: record.defaultValue } : {}),
+        ...(record.enumValues !== undefined ? { enumValues: [...record.enumValues] } : {}),
+        ...(fields ? { fields } : {}),
+    };
+}
+function validateFields(fields, label, strict, depth = 1) {
     if (fields === undefined) {
         return [];
     }
     if (!Array.isArray(fields)) {
         throw new Error(`${label} must be an array`);
     }
-    return fields.map((field, index) => {
-        if (!field || typeof field !== "object" || Array.isArray(field)) {
-            throw new Error(`${label}[${index}] must be an object`);
-        }
-        const record = field;
-        assertOnlyKeys(record, ["name", "description", "type", "defaultValue", "optional", "isArray", "subType"], `${label}[${index}]`);
-        if (typeof record.name !== "string" || record.name.trim() === "") {
-            throw new Error(`${label}[${index}].name is required`);
-        }
-        if (typeof record.type !== "string" || !FIELD_TYPES.has(record.type)) {
-            throw new Error(`${label}[${index}].type must be a FieldType`);
+    return fields.map((field, index) => validateField(field, `${label}[${index}]`, strict, depth));
+}
+/** Check carried fields before the recursive schema parse, including the host's depth bound. */
+function validateCarriedFields(definition, label, strict) {
+    if (!definition || typeof definition !== "object" || Array.isArray(definition))
+        return;
+    const record = definition;
+    for (const [kind, fieldLists] of [
+        ["tables", ["fields"]],
+        ["tools", ["inputFields", "outputFields"]],
+        ["events", ["payloadFields"]],
+        ["observables", ["value"]],
+    ]) {
+        const members = record[kind];
+        if (!Array.isArray(members))
+            continue;
+        for (const [index, member] of members.entries()) {
+            if (!member || typeof member !== "object" || Array.isArray(member))
+                continue;
+            for (const fields of fieldLists) {
+                const value = member[fields];
+                const fieldLabel = `${label}.${kind}[${index}].${fields}`;
+                if (fields === "value") {
+                    if (value !== undefined)
+                        validateField(value, fieldLabel, strict, 1, false);
+                }
+                else {
+                    validateFields(value, fieldLabel, strict);
+                }
+            }
         }
-        return {
-            name: record.name,
-            type: record.type,
-            ...(typeof record.description === "string" ? { description: record.description } : {}),
-            ...(record.optional === true ? { optional: true } : {}),
-            ...(record.isArray === true ? { isArray: true } : {}),
-            ...(typeof record.subType === "string" ? { subType: record.subType } : {}),
-            ...(record.defaultValue !== undefined ? { defaultValue: record.defaultValue } : {}),
-        };
-    });
+    }
 }
 function assertJsonCompatible(value, label, seen = new WeakSet()) {
     if (value === null ||
@@ -142,7 +275,7 @@ function validateObservableDefault(value, type, label) {
         throw new Error(`${label} must match observable valueType ${type}`);
     }
 }
-function validatePackageTables(manifest) {
+function validatePackageTables(manifest, strict) {
     if (manifest.tables === undefined) {
         manifest.tables = [];
         return;
@@ -167,13 +300,16 @@ function validatePackageTables(manifest) {
         if (forbiddenIdentity) {
             throw new Error(`${tableLabel} must not declare ${forbiddenIdentity}`);
         }
-        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber"], tableLabel);
+        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber", "localOnly"], tableLabel);
         if (typeof table.name !== "string" || table.name.trim() === "") {
             throw new Error(`${tableLabel}.name is required`);
         }
         if (table.description !== undefined && typeof table.description !== "string") {
             throw new Error(`${tableLabel}.description must be a string`);
         }
+        if (table.localOnly !== undefined && typeof table.localOnly !== "boolean") {
+            throw new Error(`${tableLabel}.localOnly must be a boolean`);
+        }
         if (tableNames.has(table.name)) {
             throw new Error(`manifest declares duplicate table "${table.name}"`);
         }
@@ -181,7 +317,7 @@ function validatePackageTables(manifest) {
         if (typeof table.primaryKeyName !== "string" || table.primaryKeyName.trim() === "") {
             throw new Error(`${tableLabel}.primaryKeyName is required`);
         }
-        table.fields = validateFields(table.fields, `${tableLabel}.fields`);
+        table.fields = validateFields(table.fields, `${tableLabel}.fields`, strict);
         if (table.fields.length === 0) {
             throw new Error(`${tableLabel}.fields must not be empty`);
         }
@@ -202,7 +338,7 @@ function validatePackageTables(manifest) {
         }
     }
 }
-function validateProvidedContract(contract, index, packageTables) {
+function validateProvidedContract(contract, index, packageTables, guestApi, strict) {
     const label = `provides[${index}]`;
     if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
         throw new Error(`${label} must be an object`);
@@ -217,6 +353,7 @@ function validateProvidedContract(contract, index, packageTables) {
         "observables",
         "events",
         "alsoImplements",
+        "exposes",
     ], label);
     assertPeerId(contract.contractId, `${label}.contractId`);
     assertContractVersion(contract.version, `${label}.version`);
@@ -256,8 +393,8 @@ function validateProvidedContract(contract, index, packageTables) {
         if (typeof tool.usageDescription !== "string") {
             throw new Error(`${toolLabel}.usageDescription is required`);
         }
-        tool.inputFields = validateFields(tool.inputFields, `${toolLabel}.inputFields`);
-        tool.outputFields = validateFields(tool.outputFields, `${toolLabel}.outputFields`);
+        tool.inputFields = validateFields(tool.inputFields, `${toolLabel}.inputFields`, strict);
+        tool.outputFields = validateFields(tool.outputFields, `${toolLabel}.outputFields`, strict);
         if (tool.authorityPropagation !== undefined &&
             tool.authorityPropagation !== "cap" &&
             tool.authorityPropagation !== "preserve")
@@ -326,7 +463,7 @@ function validateProvidedContract(contract, index, packageTables) {
         if (!observable || typeof observable !== "object" || Array.isArray(observable)) {
             throw new Error(`${observableLabel} must be an object`);
         }
-        assertOnlyKeys(observable, ["name", "description", "valueType", "writable", "persistentVar"], observableLabel);
+        assertOnlyKeys(observable, ["name", "description", "valueType", "value", "writable", "persistentVar"], observableLabel);
         if (typeof observable.name !== "string" || observable.name.trim() === "") {
             throw new Error(`${observableLabel}.name is required`);
         }
@@ -341,12 +478,23 @@ function validateProvidedContract(contract, index, packageTables) {
             !OBSERVABLE_FIELD_TYPES.has(observable.valueType)) {
             throw new Error(`${observableLabel}.valueType must be a JSON-compatible FieldType`);
         }
+        if (observable.value !== undefined) {
+            const { name: _name, ...value } = validateField(observable.value, `${observableLabel}.value`, strict, 1, false);
+            observable.value = value;
+        }
         if (typeof observable.writable !== "boolean") {
             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`);
+            }
+            continue;
+        }
         if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
-            throw new Error(`${observableLabel}.persistentVar is required`);
+            throw new Error(`${observableLabel}.persistentVar must be an object`);
         }
         assertOnlyKeys(binding, ["scope", "name", "defaultValue"], `${observableLabel}.persistentVar`);
         if (typeof binding.scope !== "string" || !PERSISTENT_VAR_SCOPE_SET.has(binding.scope)) {
@@ -385,7 +533,7 @@ function validateProvidedContract(contract, index, packageTables) {
         if (typeof event.description !== "string") {
             throw new Error(`${eventLabel}.description is required`);
         }
-        event.payloadFields = validateFields(event.payloadFields, `${eventLabel}.payloadFields`);
+        event.payloadFields = validateFields(event.payloadFields, `${eventLabel}.payloadFields`, strict);
     }
     if (contract.tools.length +
         contract.tables.length +
@@ -405,8 +553,23 @@ function validateProvidedContract(contract, index, packageTables) {
         if (!declaration || typeof declaration !== "object" || Array.isArray(declaration)) {
             throw new Error(`${declarationLabel} must be an object`);
         }
-        assertOnlyKeys(declaration, ["contractId", "version"], declarationLabel);
+        assertOnlyKeys(declaration, ["contractId", "version", "definition"], declarationLabel);
         assertPeerId(declaration.contractId, `${declarationLabel}.contractId`);
+        if (declaration.definition !== undefined) {
+            // The target's definition, carried so the host can register it on a cold start.
+            if (typeof declaration.version !== "number") {
+                throw new Error(`${declarationLabel}.definition needs a single version`);
+            }
+            validateCarriedFields(declaration.definition, `${declarationLabel}.definition`, strict);
+            const checked = contract_definition_schema_1.contractDefinitionSchema.safeParse(declaration.definition);
+            if (!checked.success) {
+                throw new Error(`${declarationLabel}.definition is invalid: ${checked.error.message}`);
+            }
+            if (declaration.definition.contractId !== declaration.contractId ||
+                declaration.definition.version !== declaration.version) {
+                throw new Error(`${declarationLabel}.definition must be the declared contract version`);
+            }
+        }
         if (typeof declaration.version === "number") {
             assertContractVersion(declaration.version, `${declarationLabel}.version`);
             continue;
@@ -423,6 +586,34 @@ function validateProvidedContract(contract, index, packageTables) {
             throw new Error(`${declarationLabel}.version.from must not exceed .to`);
         }
     }
+    validateExposes(contract, label);
+}
+/** Check a provided contract's `exposes` list; the manifest checks that it names provided contracts. */
+function validateExposes(contract, label) {
+    if (contract.exposes === undefined) {
+        return;
+    }
+    if (!Array.isArray(contract.exposes)) {
+        throw new Error(`${label}.exposes must be an array`);
+    }
+    const seen = new Set();
+    for (const [index, exposed] of contract.exposes.entries()) {
+        const exposedLabel = `${label}.exposes[${index}]`;
+        if (!exposed || typeof exposed !== "object" || Array.isArray(exposed)) {
+            throw new Error(`${exposedLabel} must be an object`);
+        }
+        assertOnlyKeys(exposed, ["contractId", "version"], exposedLabel);
+        assertPeerId(exposed.contractId, `${exposedLabel}.contractId`);
+        assertContractVersion(exposed.version, `${exposedLabel}.version`);
+        const key = `${exposed.contractId}@${exposed.version}`;
+        if (key === `${contract.contractId}@${contract.version}`) {
+            throw new Error(`${exposedLabel}: a contract can't expose itself`);
+        }
+        if (seen.has(key)) {
+            throw new Error(`${exposedLabel}: ${key} is exposed twice`);
+        }
+        seen.add(key);
+    }
 }
 function validateConsumedContract(dep, index) {
     const label = `consumes[${index}]`;
@@ -565,11 +756,17 @@ function looksLikeIsolatedPackageArtifact(bundle) {
  * 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.
  */
-function validateIsolatedPackageArtifact(artifact) {
+function validateIsolatedPackageArtifact(artifact, options = {}) {
+    const strict = options.strict === true;
     if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
         throw new Error("Package artifact must be an object");
     }
@@ -586,8 +783,10 @@ function validateIsolatedPackageArtifact(artifact) {
         "tables",
         "network",
         "appNavs",
+        // Voice Skill v1's retired action aliases: an older manifest may carry them; ignored.
         "actionAliases",
         "executionMode",
+        "guestApi",
     ], "manifest");
     if (typeof providerSource !== "string" || providerSource.trim() === "") {
         throw new Error("Package artifact.providerSource must be a non-empty string");
@@ -597,6 +796,9 @@ function validateIsolatedPackageArtifact(artifact) {
         manifest.executionMode !== "privileged") {
         throw new Error('manifest.executionMode must be "sandbox" or "privileged"');
     }
+    if (manifest.guestApi !== undefined && manifest.guestApi !== 2 && manifest.guestApi !== 3) {
+        throw new Error("manifest.guestApi must be 2 or 3 when set");
+    }
     assertPeerId(manifest.packageId, "packageId");
     if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
         throw new Error("package version is required");
@@ -607,36 +809,39 @@ function validateIsolatedPackageArtifact(artifact) {
     if (!Array.isArray(manifest.consumes)) {
         throw new Error("package.consumes must be an array");
     }
-    validatePackageTables(manifest);
+    validatePackageTables(manifest, strict);
     const packageTables = manifest.tables ?? [];
     const providedKeys = new Set();
     for (const [index, contract] of manifest.provides.entries()) {
-        validateProvidedContract(contract, index, packageTables);
+        validateProvidedContract(contract, index, packageTables, manifest.guestApi, strict);
         const key = `${contract.contractId}@${contract.version}`;
         if (providedKeys.has(key)) {
             throw new Error(`Duplicate provided contract ${key}`);
         }
         providedKeys.add(key);
     }
-    for (const [index, dep] of manifest.consumes.entries()) {
-        validateConsumedContract(dep, index);
-    }
-    if (manifest.actionAliases !== undefined) {
-        if (!Array.isArray(manifest.actionAliases))
-            throw new Error("actionAliases must be an array");
-        const names = new Set();
-        for (const alias of manifest.actionAliases) {
-            if (!alias || typeof alias.name !== "string" || !alias.name || names.has(alias.name)) {
-                throw new Error("Invalid or duplicate action alias");
+    for (const [index, contract] of manifest.provides.entries()) {
+        for (const target of contract.alsoImplements ?? []) {
+            // Legacy ranges may cover an explicitly provided version. Its own handlers take
+            // precedence in the registry; retain that behavior for existing hand-written manifests.
+            // A carried definition already requires a single version during contract validation.
+            if (typeof target.version !== "number")
+                continue;
+            const key = `${target.contractId}@${target.version}`;
+            if (providedKeys.has(key)) {
+                throw new Error(`provides[${index}] also implements ${key}, which the package provides explicitly`);
             }
-            names.add(alias.name);
-            const target = alias.target;
-            if (!target ||
-                !packageProvidesTool(manifest.provides, target.contractId, target.version, target.toolName)) {
-                throw new Error(`Action alias ${alias.name} has no registered target`);
+        }
+        for (const exposed of contract.exposes ?? []) {
+            const key = `${exposed.contractId}@${exposed.version}`;
+            if (!providedKeys.has(key)) {
+                throw new Error(`provides[${index}] exposes ${key}, which the package doesn't provide`);
             }
         }
     }
+    for (const [index, dep] of manifest.consumes.entries()) {
+        validateConsumedContract(dep, index);
+    }
     manifest.appNavs = validateAppNavs(manifest.appNavs);
     validatePackageNetwork(manifest);
     return manifest;
@@ -716,6 +921,7 @@ function isolatedContractToDefinition(contract, packageTables) {
         name: observable.name,
         description: observable.description,
         valueType: observable.valueType,
+        ...(observable.value ? { value: observable.value } : {}),
         writable: observable.writable,
     }));
     const events = (contract.events ?? []).map((event) => ({