@peers-app/peers-sdk 0.23.2 → 0.23.5

package/dist/package-loader/isolated-table-gateway.test.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const package_table_identity_1 = require("../data/package-table-identity");
+const field_type_1 = require("../types/field-type");
+const utils_1 = require("../utils");
+const isolated_table_gateway_1 = require("./isolated-table-gateway");
+function makeDeclaration(overrides = {}) {
+    const packageId = overrides.packageId ?? (0, utils_1.newid)();
+    return {
+        packageId,
+        tableName: "State",
+        description: "Owned state",
+        primaryKeyName: "stateId",
+        fields: [
+            { name: "stateId", type: field_type_1.FieldType.id },
+            { name: "count", type: field_type_1.FieldType.number },
+        ],
+        ...overrides,
+    };
+}
+describe("isolated package table gateway", () => {
+    test("memory gateway binds a table and persists get/save across re-register", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const declaration = makeDeclaration();
+        const recordId = (0, utils_1.newid)();
+        await gateway.register(declaration);
+        expect(await gateway.get(declaration, recordId)).toBeUndefined();
+        await expect(gateway.save(declaration, { stateId: recordId, count: 1 })).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+        });
+        await expect(gateway.get(declaration, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+        });
+        await expect(gateway.call(declaration, "count", [{}])).resolves.toBe(1);
+        await expect(gateway.call(declaration, "list", [{ count: 1 }])).resolves.toEqual([
+            { stateId: recordId, count: 1 },
+        ]);
+        await expect(gateway.call(declaration, "findOne", [{ count: 1 }])).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+        });
+        await gateway.register(declaration);
+        await expect(gateway.get(declaration, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+        });
+        await expect(gateway.call(declaration, "update", [{ stateId: recordId, count: 2 }])).resolves.toEqual({ stateId: recordId, count: 2 });
+        await expect(gateway.call(declaration, "delete", [recordId])).resolves.toBeUndefined();
+        await expect(gateway.call(declaration, "get", [recordId])).resolves.toBeUndefined();
+    });
+    test("memory gateway denies undeclared tables and separates package-local names", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const owner = makeDeclaration();
+        const other = makeDeclaration({ tableName: owner.tableName });
+        const recordId = (0, utils_1.newid)();
+        await gateway.register(owner);
+        await gateway.register(other);
+        await gateway.save(owner, { stateId: recordId, count: 1 });
+        await gateway.save(other, { stateId: recordId, count: 2 });
+        await expect(gateway.get(owner, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+        });
+        await expect(gateway.get(other, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 2,
+        });
+        await expect(gateway.get({ ...owner, packageId: (0, utils_1.newid)() }, (0, utils_1.newid)())).rejects.toThrow(/Undeclared isolated table/);
+    });
+    test("memory gateway preserves Date and binary fields without retaining references", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const declaration = makeDeclaration({
+            fields: [
+                { name: "stateId", type: field_type_1.FieldType.id },
+                { name: "count", type: field_type_1.FieldType.number },
+                { name: "savedAt", type: field_type_1.FieldType.Date },
+                { name: "payload", type: field_type_1.FieldType.blob },
+            ],
+        });
+        const recordId = (0, utils_1.newid)();
+        const input = {
+            stateId: recordId,
+            count: 1,
+            savedAt: new Date("2026-08-24T12:00:00.000Z"),
+            payload: new Uint8Array([4, 5, 6]),
+        };
+        await gateway.register(declaration);
+        await gateway.save(declaration, input);
+        input.savedAt.setUTCFullYear(2030);
+        input.payload[0] = 9;
+        await expect(gateway.get(declaration, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 1,
+            savedAt: new Date("2026-08-24T12:00:00.000Z"),
+            payload: new Uint8Array([4, 5, 6]),
+        });
+    });
+    test("memory gateway preserves rows across upgrades and rejects unsafe schema changes", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const v1 = makeDeclaration({ versionNumber: 1 });
+        const rowId = (0, utils_1.newid)();
+        await gateway.register(v1);
+        await gateway.save(v1, { stateId: rowId, count: 1 });
+        const conflictingV1 = {
+            ...v1,
+            fields: [...v1.fields, { name: "other", type: field_type_1.FieldType.string, optional: true }],
+        };
+        await expect(gateway.register(conflictingV1)).rejects.toThrow(/different schemas at version 1/);
+        const v2 = { ...conflictingV1, versionNumber: 2 };
+        await gateway.register(v2);
+        await expect(gateway.get(v2, rowId)).resolves.toEqual({ stateId: rowId, count: 1 });
+        await expect(gateway.register(v1)).rejects.toThrow(/schema downgrade/);
+        await expect(gateway.register(makeDeclaration({ tableName: 'Unsafe"; DROP TABLE State; --' }))).rejects.toThrow(/only letters, numbers, and underscores/);
+    });
+    test("rejects a table batch without publishing declarations that came before the conflict", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const first = makeDeclaration({ versionNumber: 1 });
+        const conflicting = {
+            ...first,
+            fields: [...first.fields, { name: "other", type: field_type_1.FieldType.string, optional: true }],
+        };
+        await expect(gateway.registerBatch([first, conflicting])).rejects.toThrow(/different schemas at version 1/);
+        await expect(gateway.get(first, (0, utils_1.newid)())).rejects.toThrow(/Undeclared isolated table/);
+    });
+    test("preflights every stored schema before applying a data-context table batch", async () => {
+        const first = makeDeclaration({ versionNumber: 1 });
+        const second = makeDeclaration({
+            packageId: first.packageId,
+            tableName: "OtherState",
+            versionNumber: 1,
+        });
+        const secondTableId = (0, package_table_identity_1.packageScopedTableId)(second.packageId, second.tableName);
+        const storedDefinitions = new Map([
+            [
+                secondTableId,
+                {
+                    tableId: secondTableId,
+                    name: `${second.tableName}_${second.packageId}`,
+                    metaData: {
+                        tableId: secondTableId,
+                        packageId: second.packageId,
+                        name: second.tableName,
+                        description: second.description,
+                        primaryKeyName: second.primaryKeyName,
+                        fields: second.fields,
+                        versionNumber: 2,
+                    },
+                    versionNumber: 2,
+                },
+            ],
+        ]);
+        const table = {
+            get: jest.fn(async (id) => storedDefinitions.get(id)),
+            save: jest.fn(async (record) => record),
+        };
+        const registerTableDefinition = jest.fn();
+        const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)({
+            tableContainer: { registerTableDefinition, getTable: jest.fn(() => table) },
+        });
+        await expect(gateway.registerBatch([first, second])).rejects.toThrow(/schema downgrade/);
+        expect(table.save).not.toHaveBeenCalled();
+        expect(registerTableDefinition).not.toHaveBeenCalled();
+    });
+    test("data-context gateway registers the host table and copies rows", async () => {
+        const declaration = makeDeclaration();
+        const recordId = (0, utils_1.newid)();
+        const rows = new Map();
+        const table = {
+            get: jest.fn(async (id) => rows.get(id)),
+            save: jest.fn(async (record) => {
+                rows.set(String(record.stateId), record);
+                return record;
+            }),
+        };
+        const registerTableDefinition = jest.fn();
+        const getTable = jest.fn(() => table);
+        const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)({
+            tableContainer: { registerTableDefinition, getTable },
+        });
+        await gateway.register(declaration);
+        expect(registerTableDefinition).toHaveBeenCalled();
+        await gateway.save(declaration, { stateId: recordId, count: 4 });
+        expect(registerTableDefinition).toHaveBeenCalledWith(expect.objectContaining({
+            metaData: expect.objectContaining({
+                tableId: (0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName),
+                packageId: declaration.packageId,
+                name: "State",
+                primaryKeyName: "stateId",
+            }),
+        }), { overwrite: true });
+        const registeredMetaData = registerTableDefinition.mock.calls[0][0].metaData;
+        expect(registeredMetaData.tableId).toBe((0, package_table_identity_1.packageScopedTableId)(declaration.packageId, declaration.tableName));
+        expect((0, utils_1.getFullTableName)(registeredMetaData)).toBe(`${declaration.tableName}_${declaration.packageId}`);
+        expect(getTable).toHaveBeenCalled();
+        await expect(gateway.get(declaration, recordId)).resolves.toEqual({
+            stateId: recordId,
+            count: 4,
+        });
+        await expect(gateway.call(declaration, "get", [recordId])).resolves.toEqual({
+            stateId: recordId,
+            count: 4,
+        });
+    });
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Copy a value accepted by the isolated package boundary without losing
+ * Peers' Date or binary field types.
+ *
+ * The worker codec performs the same authority-boundary validation. Gateways
+ * repeat the copy so in-process tests and host-side adapters cannot retain
+ * mutable guest references.
+ *
+ * @param value Value to copy.
+ * @returns A detached value containing only supported primitives, arrays,
+ *   plain objects, Dates, and Uint8Arrays.
+ * @throws When a value is cyclic, non-finite, or has an unsupported prototype.
+ */
+export declare function copyIsolatedValue<T>(value: T): T;

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyIsolatedValue = copyIsolatedValue;
+/**
+ * Copy a value accepted by the isolated package boundary without losing
+ * Peers' Date or binary field types.
+ *
+ * The worker codec performs the same authority-boundary validation. Gateways
+ * repeat the copy so in-process tests and host-side adapters cannot retain
+ * mutable guest references.
+ *
+ * @param value Value to copy.
+ * @returns A detached value containing only supported primitives, arrays,
+ *   plain objects, Dates, and Uint8Arrays.
+ * @throws When a value is cyclic, non-finite, or has an unsupported prototype.
+ */
+function copyIsolatedValue(value) {
+    return copyValue(value, new WeakSet());
+}
+function copyValue(value, seen) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        value === undefined) {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Isolated value numbers must be finite");
+        }
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new Error("Isolated value contains an unsupported value");
+    }
+    if (seen.has(value)) {
+        throw new Error("Isolated value must not contain cycles");
+    }
+    if (value instanceof Date) {
+        const time = value.getTime();
+        if (!Number.isFinite(time)) {
+            throw new Error("Isolated value contains an invalid Date");
+        }
+        return new Date(time);
+    }
+    if (value instanceof Uint8Array) {
+        return new Uint8Array(value);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        throw new Error("Isolated value contains an unsupported object");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => copyValue(item, seen));
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyValue(item, seen)]));
+    }
+    finally {
+        seen.delete(value);
+    }
+}

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

@@ -1,28 +1,139 @@
 import type { DataContext } from "../context/data-context";
+import { type IContractProviderEndpointRequest } from "../contracts/contract-provider-router";
+import { type IContractConsumer, type IContractProviderEndpoint } from "../contracts/contract-proxy";
 import { ContractRegistry } from "../contracts/registry";
+import type { IConsumedContract } from "../contracts/types";
 import { type IPackage } from "../data/packages";
 import type { IPeersPackage } from "../types/peers-package";
+import { type IIsolatedPackageRuntime } from "./isolated-runtime";
 import "../contracts/system";
+/** Host-only options for {@link PackageLoader.resolveContractEndpoint}. */
+export interface IPackageContractEndpointOptions {
+    /** Provider package selected from trusted registry state. */
+    providerPackageId?: string;
+    /** Host-only package-variable resolver appended to local tool context. */
+    resolveVariable?: (variableName: string, requestingToolId: string) => Promise<string>;
+    /** Prevent recursion when an isolated consumer asks for a host provider. */
+    resolverOnly?: boolean;
+}
+/**
+ * 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.
+ */
 export declare class PackageLoader {
     readonly dataContext: DataContext;
+    /** Host-injected SDK module used as the `peers-sdk` / `PeersSDK` require. */
     static PeersSDK: any;
+    /** Host-injected Zod module used as the `zod` require. */
     static Zod: any;
     private packageInstances;
     /** Packages that were installed via the contract-based path (tools/assistants/tables already saved with packageId). */
     private contractInstalledPackages;
+    /** Packages installed through the isolated runtime (no host eval). */
+    private isolatedPackageIds;
     /**
      * In-memory contract providers for this data context. Seeded with system
      * contracts at construction; package providers are added via
-     * {@link installContractPackage}.
+     * {@link installContractPackage} or the isolated runtime.
      */
     readonly contractRegistry: ContractRegistry;
+    /** Optional isolated-provider supervisor created from the host factory. */
+    readonly isolatedRuntime?: IIsolatedPackageRuntime;
+    /** Optional host `require` used when reading local bundles or evaluating legacy packages. */
     require: (<T>(module: string) => T) | undefined;
+    /**
+     * @param dataContext - Owning personal or group data context. Its
+     *   `tableContainer` must already be assigned so isolated packages that
+     *   declare tables receive a host gateway.
+     */
     constructor(dataContext: DataContext);
-    /** Returns true if a package was installed via the contract-based definePackage() path. */
+    /**
+     * Returns true if a package was installed via the contract-based
+     * `definePackage()` path or as an isolated artifact.
+     *
+     * @param packageId - Package to query.
+     */
     isContractInstalled(packageId: string): boolean;
+    /**
+     * Returns true if `packageId` was installed as an isolated artifact.
+     *
+     * @param packageId - Package to query.
+     */
+    isIsolatedInstalled(packageId: string): boolean;
+    /** Return whether this host configured an isolated-package runtime. */
+    supportsIsolatedPackages(): boolean;
+    /**
+     * Return the active provider selected by this data context's trusted registry.
+     *
+     * @param contractId - Target contract identity.
+     * @param version - Target contract version.
+     */
+    getActiveContractProviderPackageId(contractId: string, version: number): string | undefined;
+    /**
+     * Resolve one authorized endpoint through the registry-selected provider.
+     *
+     * Isolated providers are delegated to the host runtime; resolver-backed
+     * providers are looked up by provider package. Contracts that predate package
+     * registration may still use their legacy unscoped resolver.
+     * Provider identity comes only from trusted registry/options state, never
+     * from an {@link import("../contracts/contract-proxy").IContractCall}.
+     *
+     * @param request - Authorized contract route and notification sink.
+     * @param opts - Trusted provider override and host-only resolver capabilities.
+     * @throws If no provider or matching endpoint implementation is available.
+     */
+    resolveContractEndpoint(request: IContractProviderEndpointRequest, opts?: IPackageContractEndpointOptions): Promise<IContractProviderEndpoint>;
+    /**
+     * Bind a legacy 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}
+     * before any consumer call payload is processed.
+     *
+     * @param dependency - Validated package consume declaration.
+     * @returns A live consumer proxy, or `undefined` when no provider matches.
+     */
+    resolveConsumedContract(dependency: IConsumedContract): Promise<IContractConsumer | undefined>;
+    /**
+     * Resolve a sandbox-backed provider endpoint when this context owns an
+     * isolated provider for the requested contract.
+     *
+     * @param request - Authorized contract/version/data-context route.
+     */
+    resolveIsolatedEndpoint(request: IContractProviderEndpointRequest): Promise<IContractProviderEndpoint | undefined>;
+    /**
+     * Stop an isolated worker (if any) and drop the in-memory package instance.
+     *
+     * @param packageId - Package to unload.
+     */
+    unloadPackage(packageId: string): Promise<void>;
+    /**
+     * Dispose the isolated runtime for this data context.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Resolve and load every non-disabled package in this data context.
+     * Disabled packages that were previously loaded are unloaded.
+     *
+     * @param opts - Forwarded to {@link resolveDevicePackageVersion}.
+     */
     loadAllPackages(opts?: {
         force?: boolean;
     }): Promise<void>;
+    /**
+     * Load one package version into this data context.
+     *
+     * Isolated artifacts are parsed and installed without evaluating provider
+     * source. A recognized but malformed isolated envelope fails closed and
+     * never falls back to `new Function`. When `localPath` points at a rebuilt
+     * isolated `dist/package.bundle.js`, that disk artifact wins over a stale
+     * stored Files bundle so local-dev packages pick up new contract versions.
+     *
+     * @param pkg - Package row.
+     * @param opts - Optional force reload, local path fallback, and PV id.
+     */
     loadPackage(pkg: IPackage, opts?: {
         force?: boolean;
         localPath?: string;
@@ -31,11 +142,19 @@ export declare class PackageLoader {
     private _readLocalBundle;
     /**
      * Post-correction: if the package definition carries a version string,
-     * update the active IPackageVersion record to match — but only when that
-     * active version is the mutable `dev` working copy. Never rewrite
+     * update the selected IPackageVersion record to match — but only when that
+     * selected version is the mutable `dev` working copy. Never rewrite
      * beta/stable version labels from a local package.json bump.
      */
     private correctPackageVersion;
+    private _loadBundle;
+    private _installIsolated;
     private _evaluateBundle;
 }
+/**
+ * Set the process-wide `require` used when a {@link PackageLoader} instance
+ * does not supply its own.
+ *
+ * @param require - Host `require` function.
+ */
 export declare function setDefaultRequire(require: <T>(module: string) => T): void;