@peers-app/peers-sdk 0.23.4 → 0.23.6

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

@@ -0,0 +1,643 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
+exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
+exports.parseIsolatedPackageArtifact = parseIsolatedPackageArtifact;
+exports.serializeIsolatedPackageArtifact = serializeIsolatedPackageArtifact;
+exports.isolatedContractToDefinition = isolatedContractToDefinition;
+exports.packageDeclaresConsume = packageDeclaresConsume;
+exports.packageProvidesTool = packageProvidesTool;
+exports.findProvidedContractTable = findProvidedContractTable;
+exports.findProvidedContractObservable = findProvidedContractObservable;
+exports.packageProvidesTable = packageProvidesTable;
+exports.findPackageTable = findPackageTable;
+exports.toConsumedContracts = toConsumedContracts;
+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");
+const utils_1 = require("../utils");
+/**
+ * First line of an isolated package bundle. Existing `package.bundle.js`
+ * artifacts never start with this token, so the loader can detect the
+ * opt-in format without evaluating source.
+ */
+exports.ISOLATED_PACKAGE_MAGIC = "PEERS_ISOLATED_PACKAGE_V1";
+/** Host-contract member guests use to request a consumed-contract tool call. */
+exports.ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
+/** Host-contract member guests use to read or write a package-owned table. */
+exports.ISOLATED_TABLE_HOST_MEMBER = "package.table";
+/** Host-contract member guests use to read or write package-prefixed pvars. */
+exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
+const OBSERVABLE_FIELD_TYPES = new Set([
+    field_type_1.FieldType.id,
+    field_type_1.FieldType.string,
+    field_type_1.FieldType.number,
+    field_type_1.FieldType.boolean,
+    field_type_1.FieldType.object,
+    field_type_1.FieldType.any,
+]);
+const PERSISTENT_VAR_SCOPE_SET = new Set(persistent_var_identity_1.PERSISTENT_VAR_SCOPES);
+function assertOnlyKeys(value, allowed, label) {
+    const allowedKeys = new Set(allowed);
+    const unsupported = Object.keys(value).find((key) => !allowedKeys.has(key));
+    if (unsupported) {
+        throw new Error(`${label}.${unsupported} is not supported by isolated package artifacts`);
+    }
+}
+function assertPeerId(id, label) {
+    if (!(0, utils_1.isid)(id)) {
+        throw new Error(`${label} must be a valid 25-character peer id, got "${id}"`);
+    }
+}
+function assertContractVersion(version, label) {
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`${label} must be a positive integer, got ${String(version)}`);
+    }
+}
+function validateFields(fields, label) {
+    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 {
+            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 ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))) {
+        return;
+    }
+    if (typeof value !== "object") {
+        throw new Error(`${label} must be JSON-compatible`);
+    }
+    if (seen.has(value)) {
+        throw new Error(`${label} must be JSON-compatible`);
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            assertJsonCompatible(item, label, seen);
+        }
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new Error(`${label} must be JSON-compatible`);
+        }
+        for (const item of Object.values(value)) {
+            assertJsonCompatible(item, label, seen);
+        }
+    }
+    seen.delete(value);
+}
+function validateObservableDefault(value, type, label) {
+    if (value === undefined) {
+        throw new Error(`${label} is required`);
+    }
+    try {
+        assertJsonCompatible(value, label);
+    }
+    catch {
+        throw new Error(`${label} must be JSON-compatible`);
+    }
+    const valid = type === field_type_1.FieldType.any ||
+        (type === field_type_1.FieldType.id && typeof value === "string" && (0, utils_1.isid)(value)) ||
+        (type === field_type_1.FieldType.string && typeof value === "string") ||
+        (type === field_type_1.FieldType.number && typeof value === "number") ||
+        (type === field_type_1.FieldType.boolean && typeof value === "boolean") ||
+        (type === field_type_1.FieldType.object && value !== null && typeof value === "object");
+    if (!valid) {
+        throw new Error(`${label} must match observable valueType ${type}`);
+    }
+}
+function validatePackageTables(manifest) {
+    if (manifest.tables === undefined) {
+        manifest.tables = [];
+        return;
+    }
+    if (!Array.isArray(manifest.tables)) {
+        throw new Error("manifest.tables must be an array");
+    }
+    const tableNames = new Set();
+    for (const [tableIndex, table] of manifest.tables.entries()) {
+        const tableLabel = `manifest.tables[${tableIndex}]`;
+        if (!table || typeof table !== "object" || Array.isArray(table)) {
+            throw new Error(`${tableLabel} must be an object`);
+        }
+        const forbiddenIdentity = [
+            "tableId",
+            "visibility",
+            "contractId",
+            "contractVersion",
+            "packageId",
+            "physicalName",
+        ].find((key) => key in table);
+        if (forbiddenIdentity) {
+            throw new Error(`${tableLabel} must not declare ${forbiddenIdentity}`);
+        }
+        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber"], 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 (tableNames.has(table.name)) {
+            throw new Error(`manifest declares duplicate table "${table.name}"`);
+        }
+        tableNames.add(table.name);
+        if (typeof table.primaryKeyName !== "string" || table.primaryKeyName.trim() === "") {
+            throw new Error(`${tableLabel}.primaryKeyName is required`);
+        }
+        table.fields = validateFields(table.fields, `${tableLabel}.fields`);
+        if (table.fields.length === 0) {
+            throw new Error(`${tableLabel}.fields must not be empty`);
+        }
+        const primaryKey = table.fields.find((field) => field.name === table.primaryKeyName);
+        if (!primaryKey) {
+            throw new Error(`${tableLabel}.primaryKeyName "${table.primaryKeyName}" is not present in fields`);
+        }
+        if (primaryKey.type !== field_type_1.FieldType.id) {
+            throw new Error(`${tableLabel}.primaryKeyName must refer to a field of type id`);
+        }
+        if (table.versionNumber !== undefined) {
+            if (!Number.isInteger(table.versionNumber) || table.versionNumber < 1) {
+                throw new Error(`${tableLabel}.versionNumber must be a positive integer`);
+            }
+        }
+        else {
+            table.versionNumber = 1;
+        }
+    }
+}
+function validateProvidedContract(contract, index, packageTables) {
+    const label = `provides[${index}]`;
+    if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
+        throw new Error(`${label} must be an object`);
+    }
+    assertOnlyKeys(contract, [
+        "contractId",
+        "version",
+        "name",
+        "description",
+        "tools",
+        "tables",
+        "observables",
+        "alsoImplements",
+    ], label);
+    assertPeerId(contract.contractId, `${label}.contractId`);
+    assertContractVersion(contract.version, `${label}.version`);
+    if (typeof contract.name !== "string" || contract.name.trim() === "") {
+        throw new Error(`${label}.name is required`);
+    }
+    if (contract.description !== undefined && typeof contract.description !== "string") {
+        throw new Error(`${label}.description must be a string`);
+    }
+    if (!Array.isArray(contract.tools)) {
+        throw new Error(`${label}.tools must be an array`);
+    }
+    const names = new Set();
+    for (const [toolIndex, tool] of contract.tools.entries()) {
+        const toolLabel = `${label}.tools[${toolIndex}]`;
+        if (!tool || typeof tool !== "object" || Array.isArray(tool)) {
+            throw new Error(`${toolLabel} must be an object`);
+        }
+        assertOnlyKeys(tool, ["name", "usageDescription", "inputFields", "outputFields", "suggestedAccessLevel"], toolLabel);
+        if (typeof tool.name !== "string" || tool.name.trim() === "") {
+            throw new Error(`${toolLabel}.name is required`);
+        }
+        if (names.has(tool.name)) {
+            throw new Error(`${label} declares duplicate tool "${tool.name}"`);
+        }
+        names.add(tool.name);
+        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`);
+        if (tool.suggestedAccessLevel !== undefined) {
+            if (!Number.isInteger(tool.suggestedAccessLevel) ||
+                tool.suggestedAccessLevel < access_level_1.MIN_ACCESS_LEVEL ||
+                tool.suggestedAccessLevel > access_level_1.MAX_ACCESS_LEVEL) {
+                throw new Error(`${toolLabel}.suggestedAccessLevel must be an integer 0–100`);
+            }
+        }
+    }
+    if (contract.tables === undefined) {
+        contract.tables = [];
+    }
+    if (!Array.isArray(contract.tables)) {
+        throw new Error(`${label}.tables must be an array`);
+    }
+    const tableNames = new Set();
+    for (const [tableIndex, tableRef] of contract.tables.entries()) {
+        const tableLabel = `${label}.tables[${tableIndex}]`;
+        if (!tableRef || typeof tableRef !== "object" || Array.isArray(tableRef)) {
+            throw new Error(`${tableLabel} must be an object`);
+        }
+        const keys = Object.keys(tableRef);
+        if (keys.length !== 1 || keys[0] !== "name") {
+            throw new Error(`${tableLabel} must contain only a package table name`);
+        }
+        if (typeof tableRef.name !== "string" || tableRef.name.trim() === "") {
+            throw new Error(`${tableLabel}.name is required`);
+        }
+        if (tableNames.has(tableRef.name)) {
+            throw new Error(`${label} declares duplicate table "${tableRef.name}"`);
+        }
+        if (!findPackageTable(packageTables, tableRef.name)) {
+            throw new Error(`${tableLabel} references undeclared package table "${tableRef.name}"`);
+        }
+        tableNames.add(tableRef.name);
+    }
+    if (contract.observables === undefined) {
+        contract.observables = [];
+    }
+    if (!Array.isArray(contract.observables)) {
+        throw new Error(`${label}.observables must be an array`);
+    }
+    const observableNames = new Set();
+    const pvarBindings = new Set();
+    for (const [observableIndex, observable] of contract.observables.entries()) {
+        const observableLabel = `${label}.observables[${observableIndex}]`;
+        if (!observable || typeof observable !== "object" || Array.isArray(observable)) {
+            throw new Error(`${observableLabel} must be an object`);
+        }
+        assertOnlyKeys(observable, ["name", "description", "valueType", "writable", "persistentVar"], observableLabel);
+        if (typeof observable.name !== "string" || observable.name.trim() === "") {
+            throw new Error(`${observableLabel}.name is required`);
+        }
+        if (observableNames.has(observable.name)) {
+            throw new Error(`${label} declares duplicate observable "${observable.name}"`);
+        }
+        observableNames.add(observable.name);
+        if (typeof observable.description !== "string") {
+            throw new Error(`${observableLabel}.description is required`);
+        }
+        if (typeof observable.valueType !== "string" ||
+            !OBSERVABLE_FIELD_TYPES.has(observable.valueType)) {
+            throw new Error(`${observableLabel}.valueType must be a JSON-compatible FieldType`);
+        }
+        if (typeof observable.writable !== "boolean") {
+            throw new Error(`${observableLabel}.writable must be a boolean`);
+        }
+        const binding = observable.persistentVar;
+        if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+            throw new Error(`${observableLabel}.persistentVar is required`);
+        }
+        assertOnlyKeys(binding, ["scope", "name", "defaultValue"], `${observableLabel}.persistentVar`);
+        if (typeof binding.scope !== "string" || !PERSISTENT_VAR_SCOPE_SET.has(binding.scope)) {
+            throw new Error(`${observableLabel}.persistentVar.scope is invalid`);
+        }
+        if (typeof binding.name !== "string" || binding.name.trim() === "") {
+            throw new Error(`${observableLabel}.persistentVar.name is required`);
+        }
+        const bindingKey = `${binding.scope}:${binding.name}`;
+        if (pvarBindings.has(bindingKey)) {
+            throw new Error(`${label} exposes persistent variable "${bindingKey}" more than once`);
+        }
+        pvarBindings.add(bindingKey);
+        validateObservableDefault(binding.defaultValue, observable.valueType, `${observableLabel}.persistentVar.defaultValue`);
+    }
+    if (contract.tools.length + contract.tables.length + contract.observables.length === 0) {
+        throw new Error(`${label} must declare at least one contract member`);
+    }
+    if (contract.alsoImplements === undefined) {
+        contract.alsoImplements = [];
+    }
+    if (!Array.isArray(contract.alsoImplements)) {
+        throw new Error(`${label}.alsoImplements must be an array`);
+    }
+    for (const [declarationIndex, declaration] of contract.alsoImplements.entries()) {
+        const declarationLabel = `${label}.alsoImplements[${declarationIndex}]`;
+        if (!declaration || typeof declaration !== "object" || Array.isArray(declaration)) {
+            throw new Error(`${declarationLabel} must be an object`);
+        }
+        assertOnlyKeys(declaration, ["contractId", "version"], declarationLabel);
+        assertPeerId(declaration.contractId, `${declarationLabel}.contractId`);
+        if (typeof declaration.version === "number") {
+            assertContractVersion(declaration.version, `${declarationLabel}.version`);
+            continue;
+        }
+        if (!declaration.version ||
+            typeof declaration.version !== "object" ||
+            Array.isArray(declaration.version)) {
+            throw new Error(`${declarationLabel}.version must be an integer or inclusive range`);
+        }
+        assertOnlyKeys(declaration.version, ["from", "to"], `${declarationLabel}.version`);
+        assertContractVersion(declaration.version.from, `${declarationLabel}.version.from`);
+        assertContractVersion(declaration.version.to, `${declarationLabel}.version.to`);
+        if (declaration.version.from > declaration.version.to) {
+            throw new Error(`${declarationLabel}.version.from must not exceed .to`);
+        }
+    }
+}
+function validateConsumedContract(dep, index) {
+    const label = `consumes[${index}]`;
+    if (!dep || typeof dep !== "object" || Array.isArray(dep)) {
+        throw new Error(`${label} must be an object`);
+    }
+    assertOnlyKeys(dep, ["contractId", "version", "optional", "providerPackageIds", "fallbackToDefaultProvider"], label);
+    assertPeerId(dep.contractId, `${label}.contractId`);
+    assertContractVersion(dep.version, `${label}.version`);
+    if (dep.optional !== undefined && typeof dep.optional !== "boolean") {
+        throw new Error(`${label}.optional must be a boolean`);
+    }
+    if (dep.fallbackToDefaultProvider !== undefined &&
+        typeof dep.fallbackToDefaultProvider !== "boolean") {
+        throw new Error(`${label}.fallbackToDefaultProvider must be a boolean`);
+    }
+    if (dep.providerPackageIds !== undefined) {
+        if (!Array.isArray(dep.providerPackageIds)) {
+            throw new Error(`${label}.providerPackageIds must be an array`);
+        }
+        for (const [providerIndex, providerId] of dep.providerPackageIds.entries()) {
+            assertPeerId(providerId, `${label}.providerPackageIds[${providerIndex}]`);
+        }
+    }
+}
+function validateAppNavs(appNavs) {
+    if (appNavs === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(appNavs)) {
+        throw new Error("manifest.appNavs must be an array");
+    }
+    return appNavs.map((nav, index) => {
+        if (!nav || typeof nav !== "object" || Array.isArray(nav)) {
+            throw new Error(`manifest.appNavs[${index}] must be an object`);
+        }
+        const record = nav;
+        assertOnlyKeys(record, ["name", "displayName", "iconClassName", "navigationPath"], `manifest.appNavs[${index}]`);
+        if (typeof record.name !== "string" || record.name.trim() === "") {
+            throw new Error(`manifest.appNavs[${index}].name is required`);
+        }
+        if (typeof record.iconClassName !== "string") {
+            throw new Error(`manifest.appNavs[${index}].iconClassName is required`);
+        }
+        if (typeof record.navigationPath !== "string") {
+            throw new Error(`manifest.appNavs[${index}].navigationPath is required`);
+        }
+        return {
+            name: record.name,
+            iconClassName: record.iconClassName,
+            navigationPath: record.navigationPath,
+            ...(typeof record.displayName === "string" ? { displayName: record.displayName } : {}),
+        };
+    });
+}
+/**
+ * True when `bundle` starts with {@link ISOLATED_PACKAGE_MAGIC}.
+ *
+ * A recognized header must never fall through to `new Function` evaluation,
+ * even if the rest of the envelope is malformed.
+ *
+ * @param bundle - Package bundle text from Files or `dist/package.bundle.js`.
+ */
+function looksLikeIsolatedPackageArtifact(bundle) {
+    if (typeof bundle !== "string") {
+        return false;
+    }
+    const trimmed = bundle.trimStart();
+    return (trimmed === exports.ISOLATED_PACKAGE_MAGIC ||
+        trimmed.startsWith(`${exports.ISOLATED_PACKAGE_MAGIC}\n`) ||
+        trimmed.startsWith(`${exports.ISOLATED_PACKAGE_MAGIC}\r\n`));
+}
+/**
+ * Validate a wire-safe isolated package artifact. Does not evaluate
+ * `providerSource`.
+ *
+ * @param artifact - Parsed artifact object.
+ * @returns The same manifest after in-place field normalization.
+ * @throws If identity, contracts, tools, or source are invalid.
+ */
+function validateIsolatedPackageArtifact(artifact) {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+        throw new Error("Package artifact must be an object");
+    }
+    assertOnlyKeys(artifact, ["manifest", "providerSource"], "artifact");
+    const { manifest, providerSource } = artifact;
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+        throw new Error("Package artifact.manifest is required");
+    }
+    assertOnlyKeys(manifest, ["packageId", "version", "provides", "consumes", "tables", "appNavs"], "manifest");
+    if (typeof providerSource !== "string" || providerSource.trim() === "") {
+        throw new Error("Package artifact.providerSource must be a non-empty string");
+    }
+    assertPeerId(manifest.packageId, "packageId");
+    if (typeof manifest.version !== "string" || manifest.version.trim() === "") {
+        throw new Error("package version is required");
+    }
+    if (!Array.isArray(manifest.provides) || manifest.provides.length === 0) {
+        throw new Error("package must provide at least one contract");
+    }
+    if (!Array.isArray(manifest.consumes)) {
+        throw new Error("package.consumes must be an array");
+    }
+    validatePackageTables(manifest);
+    const packageTables = manifest.tables ?? [];
+    const providedKeys = new Set();
+    for (const [index, contract] of manifest.provides.entries()) {
+        validateProvidedContract(contract, index, packageTables);
+        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);
+    }
+    manifest.appNavs = validateAppNavs(manifest.appNavs);
+    return manifest;
+}
+/**
+ * Parse a magic-header + JSON isolated package bundle.
+ *
+ * @param bundle - Full package-bundle text.
+ * @returns The validated artifact.
+ * @throws If the magic header is present but the envelope is malformed.
+ */
+function parseIsolatedPackageArtifact(bundle) {
+    if (!looksLikeIsolatedPackageArtifact(bundle)) {
+        throw new Error("Bundle is not an isolated package artifact");
+    }
+    const trimmed = bundle.trimStart();
+    const newline = trimmed.indexOf("\n");
+    if (newline < 0) {
+        throw new Error("Isolated package artifact is missing its JSON envelope");
+    }
+    const jsonText = trimmed.slice(newline + 1).trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (err) {
+        throw new Error(`Isolated package artifact JSON is invalid: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const artifact = parsed;
+    validateIsolatedPackageArtifact(artifact);
+    return artifact;
+}
+/**
+ * Serialize an isolated artifact into the package-bundle slot format.
+ *
+ * @param artifact - Validated or soon-to-be-validated artifact.
+ */
+function serializeIsolatedPackageArtifact(artifact) {
+    validateIsolatedPackageArtifact(artifact);
+    return `${exports.ISOLATED_PACKAGE_MAGIC}\n${JSON.stringify(artifact)}\n`;
+}
+/**
+ * Convert a provided-contract declaration into an SDK contract definition.
+ *
+ * Name-only table references are resolved from the package's schema list.
+ * Persistent-variable bindings stay host-only and are omitted from the public
+ * observable definition.
+ *
+ * @param contract - Isolated provided-contract declaration.
+ * @param packageTables - Package-owned schemas available for contract exposure.
+ */
+function isolatedContractToDefinition(contract, packageTables) {
+    const tools = contract.tools.map((tool) => ({
+        name: tool.name,
+        usageDescription: tool.usageDescription,
+        inputFields: tool.inputFields ?? [],
+        outputFields: tool.outputFields ?? [],
+    }));
+    const tables = (contract.tables ?? []).map((tableRef) => {
+        const table = findPackageTable(packageTables, tableRef.name);
+        if (!table) {
+            throw new Error(`Contract references undeclared package table "${tableRef.name}"`);
+        }
+        return {
+            name: table.name,
+            description: table.description ?? "",
+            primaryKeyName: table.primaryKeyName,
+            fields: table.fields,
+        };
+    });
+    const observables = (contract.observables ?? []).map((observable) => ({
+        name: observable.name,
+        description: observable.description,
+        valueType: observable.valueType,
+        writable: observable.writable,
+    }));
+    return {
+        contractId: contract.contractId,
+        version: contract.version,
+        name: contract.name,
+        description: contract.description ?? "",
+        tables,
+        tools,
+        observables,
+        events: [],
+    };
+}
+/**
+ * True when `consumes` names this exact contract version.
+ *
+ * @param consumes - Declared package dependencies.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ */
+function packageDeclaresConsume(consumes, contractId, version) {
+    return consumes.some((dep) => dep.contractId === contractId && dep.version === version);
+}
+/**
+ * True when the package advertises this tool on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param toolName - Tool name on that contract.
+ */
+function packageProvidesTool(provides, contractId, version, toolName) {
+    const contract = provides.find((item) => item.contractId === contractId && item.version === version);
+    return Boolean(contract?.tools.some((tool) => tool.name === toolName));
+}
+/**
+ * Return a consumer-facing table reference from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param tableName Public table name.
+ */
+function findProvidedContractTable(provides, contractId, version, tableName) {
+    return provides
+        .find((contract) => contract.contractId === contractId && contract.version === version)
+        ?.tables?.find((table) => table.name === tableName);
+}
+/**
+ * Return a pvar-backed observable from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param observableName Public observable name.
+ */
+function findProvidedContractObservable(provides, contractId, version, observableName) {
+    return provides
+        .find((contract) => contract.contractId === contractId && contract.version === version)
+        ?.observables?.find((observable) => observable.name === observableName);
+}
+/**
+ * True when the package declares a private table.
+ *
+ * @param tables - Package-private table schemas.
+ * @param tableName - Package-local table name.
+ */
+function packageProvidesTable(tables, tableName) {
+    return tables.some((table) => table.name === tableName);
+}
+/**
+ * Return the declared table when this package owns it.
+ *
+ * @param tables - Package-private table schemas.
+ * @param tableName - Package-local table name.
+ */
+function findPackageTable(tables, tableName) {
+    return tables.find((table) => table.name === tableName);
+}
+/**
+ * Map isolated consume declarations onto the registry's
+ * {@link IConsumedContract} shape (no deferred handles).
+ *
+ * @param consumes - Isolated consume list.
+ */
+function toConsumedContracts(consumes) {
+    return consumes.map((dep) => ({
+        contractId: dep.contractId,
+        version: dep.version,
+        optional: dep.optional,
+        providerPackageIds: dep.providerPackageIds,
+        fallbackToDefaultProvider: dep.fallbackToDefaultProvider,
+    }));
+}

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

@@ -0,0 +1 @@
+export {};