@peers-app/peers-sdk 0.27.3 → 0.27.5

package/dist/define/define.test.js

@@ -1,1010 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = require("node:fs");
-const path = require("node:path");
-const types_1 = require("../data/orm/types");
-const contract_members_1 = require("../package-loader/contract-members");
-const isolated_artifact_1 = require("../package-loader/isolated-artifact");
-const peer_id_1 = require("../peer-id");
-const system_ids_1 = require("../system-ids");
-const index_1 = require("./index");
-const manifest_1 = require("./manifest");
-/** A ctx whose host calls are recorded and answered by `answer`. */
-function fakeContext(answer = () => null) {
-    const calls = [];
-    const ctx = new Proxy({}, {
-        get(_target, method) {
-            return async (...args) => {
-                calls.push([method, ...args]);
-                return answer(method, args);
-            };
-        },
-    });
-    return { ctx, calls };
-}
-const itemSchema = index_1.z.object({
-    itemId: index_1.zodPeerId.describe("Item id."),
-    name: index_1.z.string().describe("Item name."),
-    done: index_1.z.boolean().default(false).describe("Checked off."),
-    note: index_1.z.string().optional().describe("Free text."),
-});
-const Items = (0, index_1.defineTable)({
-    name: "Items",
-    description: "Things to do.",
-    primaryKeyName: "itemId",
-    schema: itemSchema,
-});
-describe("defineTable", () => {
-    test("calls the owned table with each method's arguments", async () => {
-        const { ctx, calls } = fakeContext((_method, args) => {
-            if (args[1] === "list")
-                return [{ itemId: "a" }];
-            if (args[1] === "count")
-                return 3;
-            if (args[1] === "save")
-                return args[2][0];
-            return null;
-        });
-        const items = Items(ctx);
-        expect(await items.list({ done: false }, { pageSize: 5 })).toEqual([{ itemId: "a" }]);
-        expect(await items.count()).toBe(3);
-        expect(await items.get("x")).toBeUndefined();
-        expect(await items.findOne({ name: "milk" })).toBeUndefined();
-        await items.delete("x");
-        expect(calls).toEqual([
-            ["callOwnedTable", "Items", "list", [{ done: false }, { pageSize: 5 }]],
-            ["callOwnedTable", "Items", "count", [{}]],
-            ["callOwnedTable", "Items", "get", ["x"]],
-            ["callOwnedTable", "Items", "findOne", [{ name: "milk" }]],
-            ["callOwnedTable", "Items", "delete", ["x"]],
-        ]);
-    });
-    test("parses a saved row with the schema, so defaults apply and bad rows fail", async () => {
-        const { ctx, calls } = fakeContext((_method, args) => args[2][0]);
-        const itemId = (0, peer_id_1.newid)();
-        await expect(Items(ctx).save({ itemId, name: "milk" })).resolves.toEqual({
-            itemId,
-            name: "milk",
-            done: false,
-        });
-        await expect(Items(ctx).save({ itemId: "nope", name: "milk" })).rejects.toThrow();
-        expect(calls).toHaveLength(1);
-    });
-    test("rejects a primary key that isn't in the schema", () => {
-        expect(() => (0, index_1.defineTable)({
-            name: "Bad",
-            description: "",
-            primaryKeyName: "missing",
-            schema: itemSchema,
-        })).toThrow(/primary key "missing"/);
-    });
-});
-describe("defineTool", () => {
-    const echo = (0, index_1.defineTool)({
-        name: "echo",
-        usageDescription: "Echo a count.",
-        accessLevel: index_1.AccessLevel.Reader,
-        inputSchema: index_1.z.object({ count: index_1.z.number().default(1) }),
-        outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-        handler: (args) => ({ doubled: args.count * 2 }),
-    });
-    test("parses input with the schema before the handler runs", async () => {
-        const { ctx } = fakeContext();
-        await expect((0, index_1.runPackageTool)(echo, null, ctx)).resolves.toEqual({ doubled: 2 });
-        await expect((0, index_1.runPackageTool)(echo, { count: 4, extra: true }, ctx)).resolves.toEqual({
-            doubled: 8,
-        });
-        await expect((0, index_1.runPackageTool)(echo, { count: "4" }, ctx)).rejects.toThrow();
-    });
-    test.each([
-        index_1.z.number().default(1),
-        index_1.z
-            .number()
-            .default(1)
-            .refine((value) => value > 0),
-        index_1.z.number().default(1).brand(),
-        index_1.z.number().default(1).readonly(),
-        index_1.z.number().catch(1),
-    ])("defaulted tool inputs pass catalog validation (%#)", async (count) => {
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema: index_1.z.object({ count }),
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: (args) => ({ doubled: args.count * 2 }),
-        });
-        const definition = (0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "Echo", tools: [tool] }));
-        });
-        const manifest = (0, manifest_1.buildPackageManifest)(definition);
-        const fields = manifest.provides[0].tools[0].inputFields ?? [];
-        expect(fields).toEqual([{ name: "count", type: "number", optional: true }]);
-        const args = (0, types_1.fieldsToSchema)(fields).passthrough().parse({});
-        const { ctx } = fakeContext();
-        await expect((0, index_1.runPackageTool)(tool, args, ctx)).resolves.toEqual({ doubled: 2 });
-    });
-    test("an array element's default does not make the array input optional", () => {
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema: index_1.z.object({ counts: index_1.z.number().default(1).array().brand() }),
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: ({ counts }) => ({ doubled: counts.length * 2 }),
-        });
-        const definition = (0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "Echo", tools: [tool] }));
-        });
-        const fields = (0, manifest_1.buildPackageManifest)(definition).provides[0].tools[0].inputFields ?? [];
-        expect(fields).toEqual([{ name: "counts", type: "number", isArray: true }]);
-        expect((0, types_1.fieldsToSchema)(fields).safeParse({}).success).toBe(false);
-    });
-    test("enums and literals are scalar types in table and tool IR, as in events", () => {
-        const status = index_1.z.enum(["running", "paused"]);
-        const Rows = (0, index_1.defineTable)({
-            name: "Rows",
-            description: "Rows.",
-            primaryKeyName: "rowId",
-            schema: index_1.z.object({
-                rowId: index_1.zodPeerId,
-                status: status.describe("Status."),
-                kind: index_1.z.literal("timer").optional(),
-                steps: index_1.z.array(status),
-                size: index_1.z.literal(3),
-            }),
-        });
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema: index_1.z.object({ status: status.default("running") }),
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: () => ({ doubled: 2 }),
-        });
-        const definition = (0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({
-                contractId: (0, peer_id_1.newid)(),
-                version: 1,
-                name: "E",
-                tables: [Rows],
-                tools: [tool],
-            }));
-        });
-        const manifest = (0, manifest_1.buildPackageManifest)(definition);
-        expect(manifest.tables?.[0].fields.map(({ name, type, optional, isArray }) => ({
-            name,
-            type,
-            optional,
-            isArray,
-        }))).toEqual([
-            { name: "rowId", type: "id", optional: undefined, isArray: undefined },
-            { name: "status", type: "string", optional: undefined, isArray: undefined },
-            { name: "kind", type: "string", optional: true, isArray: undefined },
-            { name: "steps", type: "string", optional: undefined, isArray: true },
-            { name: "size", type: "number", optional: undefined, isArray: undefined },
-        ]);
-        expect(manifest.tables?.[0].fields.map(({ enumValues }) => enumValues)).toEqual([
-            undefined,
-            ["running", "paused"],
-            ["timer"],
-            ["running", "paused"],
-            [3],
-        ]);
-        expect(manifest.provides[0].tools[0].inputFields).toEqual([
-            { name: "status", type: "string", optional: true, enumValues: ["running", "paused"] },
-        ]);
-    });
-    test("enum and literal inference keeps valid empty, transformed, and nested values", () => {
-        const schema = index_1.z.object({
-            rowId: index_1.zodPeerId,
-            maybe: index_1.z.enum(["running", "paused"]).nullish(),
-            transformed: index_1.z.literal("yes").transform(() => true),
-            nullableItems: index_1.z.array(index_1.z.enum(["running"]).nullable()),
-            optionalItems: index_1.z.array(index_1.z.literal(3).optional()),
-            nested: index_1.z.array(index_1.z.array(index_1.z.literal(false))),
-            flag: index_1.z.literal(true),
-        });
-        const Rows = (0, index_1.defineTable)({
-            name: "Rows",
-            description: "Rows.",
-            primaryKeyName: "rowId",
-            schema,
-        });
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema: schema,
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: () => ({ doubled: 2 }),
-        });
-        const manifest = (0, manifest_1.buildPackageManifest)((0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({
-                contractId: (0, peer_id_1.newid)(),
-                version: 1,
-                name: "E",
-                tables: [Rows],
-                tools: [tool],
-            }));
-        }));
-        const input = {
-            rowId: (0, peer_id_1.newid)(),
-            maybe: null,
-            transformed: "yes",
-            nullableItems: [null, "running"],
-            optionalItems: [3, undefined],
-            nested: [[false]],
-            flag: true,
-        };
-        // The host removes empty optional fields before it checks types.
-        const inputFields = manifest.provides[0].tools[0].inputFields ?? [];
-        expect((0, types_1.fieldsToSchema)(inputFields).safeParse((0, types_1.withoutEmptyFields)(inputFields, input)).success).toBe(true);
-        const fields = manifest.tables?.[0].fields ?? [];
-        expect((0, types_1.fieldsToSchema)(fields).safeParse((0, types_1.withoutEmptyFields)(fields, schema.parse(input))).success).toBe(true);
-        expect(fields.find((field) => field.name === "flag")?.type).toBe("boolean");
-    });
-    test("the manifest describes nested objects, enum values, and empty fields", () => {
-        let Color;
-        (function (Color) {
-            Color["Red"] = "red";
-            Color["Blue"] = "blue";
-        })(Color || (Color = {}));
-        let Level;
-        (function (Level) {
-            Level[Level["Low"] = 1] = "Low";
-            Level[Level["High"] = 2] = "High";
-        })(Level || (Level = {}));
-        const place = index_1.z.object({
-            city: index_1.z.string().describe("City."),
-            unit: index_1.z.enum(["F", "C"]).default("F"),
-            zone: index_1.z.string().nullable().optional(),
-        });
-        const inputSchema = index_1.z.object({
-            place,
-            places: index_1.z.array(place).optional(),
-            maybePlace: place.nullish(),
-            color: index_1.z.nativeEnum(Color),
-            level: index_1.z.nativeEnum(Level),
-            size: index_1.z.union([index_1.z.literal("small"), index_1.z.literal("large")]),
-            mixed: index_1.z.union([index_1.z.literal("auto"), index_1.z.literal(3)]),
-            refined: index_1.z
-                .string()
-                .refine((value) => value.length > 0)
-                .optional()
-                .nullable(),
-            items: index_1.z.array(index_1.z.string().nullable()),
-            // Where the schema stops describing the value in IR terms, the IR says no more.
-            transformed: place.transform((value) => value.city),
-            grid: index_1.z.array(index_1.z.array(place)),
-            record: index_1.z.record(index_1.z.string()),
-            lazy: index_1.z.lazy(() => place),
-            anything: index_1.z.unknown(),
-        });
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema,
-            outputSchema: index_1.z.object({ place }),
-            handler: () => ({ place: { city: "Austin", unit: "F" } }),
-        });
-        const manifest = (0, manifest_1.buildPackageManifest)((0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "E", tools: [tool] }));
-        }));
-        const [inputs, outputs] = [
-            manifest.provides[0].tools[0].inputFields ?? [],
-            manifest.provides[0].tools[0].outputFields ?? [],
-        ];
-        const byName = new Map(inputs.map((field) => [field.name, field]));
-        const placeFields = (input) => [
-            { name: "city", type: "string", description: "City." },
-            // A defaulted input may be omitted; a parsed output always has it.
-            {
-                name: "unit",
-                type: "string",
-                enumValues: ["F", "C"],
-                ...(input ? { optional: true } : {}),
-            },
-            { name: "zone", type: "string", optional: true },
-        ];
-        expect(byName.get("place")).toEqual({
-            name: "place",
-            type: "object",
-            fields: placeFields(true),
-        });
-        expect(outputs[0]).toEqual({ name: "place", type: "object", fields: placeFields(false) });
-        expect(byName.get("places")).toMatchObject({
-            isArray: true,
-            optional: true,
-            fields: placeFields(true),
-        });
-        expect(byName.get("maybePlace")).toMatchObject({ type: "object", optional: true });
-        expect(byName.get("color")).toEqual({
-            name: "color",
-            type: "string",
-            enumValues: ["red", "blue"],
-        });
-        expect(byName.get("level")).toEqual({ name: "level", type: "number", enumValues: [1, 2] });
-        expect(byName.get("size")).toEqual({
-            name: "size",
-            type: "any",
-            enumValues: ["small", "large"],
-        });
-        expect(byName.get("mixed")).toEqual({ name: "mixed", type: "any", enumValues: ["auto", 3] });
-        // `.optional().nullable()` is optional too, though `schemaToFields` reads only the outer
-        // wrapper.
-        expect(byName.get("refined")).toEqual({ name: "refined", type: "string", optional: true });
-        // An array's nullable elements aren't an empty field.
-        expect(byName.get("items")).toEqual({ name: "items", type: "string", isArray: true });
-        for (const name of ["transformed", "grid", "record", "lazy", "anything"]) {
-            const { fields, enumValues, optional } = byName.get(name) ?? {};
-            expect({ name, fields, enumValues, optional }).toEqual({ name });
-        }
-        // The build validates strictly, and the host's type-level checks accept every valid input.
-        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "void 0;" }, { strict: true })).not.toThrow();
-        const input = inputSchema.parse({
-            place: { city: "Austin" },
-            maybePlace: null,
-            color: "red",
-            level: 2,
-            size: "small",
-            mixed: 3,
-            refined: null,
-            // Not null items or a grid: tool IR can't express nullable elements or nested arrays,
-            // and the host's type check refuses them (as before this IR).
-            items: ["a"],
-            transformed: { city: "Austin" },
-            grid: [],
-            record: { a: "b" },
-            lazy: { city: "Austin" },
-            anything: null,
-        });
-        expect((0, types_1.fieldsToSchema)(inputs).safeParse((0, types_1.withoutEmptyFields)(inputs, { ...input, transformed: { city: "Austin" } })).success).toBe(true);
-    });
-    test("nested fields stop at the depth the host accepts", () => {
-        let schema = index_1.z.object({ leaf: index_1.z.string() });
-        for (let level = 0; level < 20; level++) {
-            schema = index_1.z.object({ next: schema });
-        }
-        const tool = (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema: index_1.z.object({ deep: schema }),
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: () => ({ doubled: 2 }),
-        });
-        const manifest = (0, manifest_1.buildPackageManifest)((0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "E", tools: [tool] }));
-        }));
-        let depth = 0;
-        let fields = manifest.provides[0].tools[0].inputFields;
-        while (fields?.length) {
-            depth++;
-            fields = fields[0].fields;
-        }
-        expect(depth).toBe(isolated_artifact_1.ISOLATED_MAX_FIELD_DEPTH);
-        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "void 0;" }, { strict: true })).not.toThrow();
-    });
-    test("an empty enum field is optional and keeps its existing any type", () => {
-        const schema = index_1.z.object({
-            mode: index_1.z.enum(["on", "off"]).nullish(),
-            size: index_1.z
-                .union([index_1.z.literal("auto"), index_1.z.literal(3)])
-                .optional()
-                .nullable(),
-            modes: index_1.z.array(index_1.z.enum(["on", "off"]).nullable()),
-            optionalModes: index_1.z.array(index_1.z.enum(["on", "off"]).optional()),
-        });
-        const fields = (0, manifest_1.irFields)(schema, true);
-        expect(fields).toEqual([
-            { name: "mode", type: "any", optional: true, enumValues: ["on", "off"] },
-            { name: "size", type: "any", optional: true, enumValues: ["auto", 3] },
-            // Empty elements have no IR representation; don't add a narrower enum.
-            { name: "modes", type: "any", isArray: true },
-            { name: "optionalModes", type: "any", isArray: true },
-        ]);
-        const value = { mode: null, size: null, modes: [null], optionalModes: [undefined] };
-        expect(schema.safeParse(value).success).toBe(true);
-        const sent = (0, types_1.withoutEmptyFields)(fields, value);
-        expect(sent).toEqual({ modes: [null], optionalModes: [undefined] });
-        expect((0, types_1.fieldsToShapeSchema)(fields).safeParse(sent).success).toBe(true);
-        expect((0, types_1.fieldsToShapeSchema)(fields).safeParse({ ...sent, mode: "invalid" }).success).toBe(false);
-    });
-    test("an empty array field is optional, whatever its element type", () => {
-        const schema = index_1.z.object({
-            records: index_1.z.array(index_1.z.record(index_1.z.string())).nullish(),
-            anything: index_1.z.array(index_1.z.unknown()).nullish(),
-            modes: index_1.z.array(index_1.z.enum(["on", "off"]).nullable()).nullish(),
-        });
-        const fields = (0, manifest_1.irFields)(schema, true);
-        expect(fields).toEqual([
-            { name: "records", type: "any", isArray: true, optional: true },
-            { name: "anything", type: "any", isArray: true, optional: true },
-            { name: "modes", type: "any", isArray: true, optional: true },
-        ]);
-        for (const value of [
-            { records: null, anything: null, modes: null },
-            { records: [{ a: "b" }], anything: [1, null], modes: ["on", null] },
-        ]) {
-            expect(schema.safeParse(value).success).toBe(true);
-            const sent = (0, types_1.withoutEmptyFields)(fields, value);
-            expect((0, types_1.fieldsToSchema)(fields).safeParse(sent).success).toBe(true);
-            expect((0, types_1.fieldsToShapeSchema)(fields).safeParse(sent).success).toBe(true);
-        }
-    });
-    test("the build refuses .nullable() unless the field is also optional and has no default", () => {
-        const build = (contract) => () => (0, manifest_1.buildPackageManifest)((0, index_1.definePackage)((pkg) => {
-            pkg.packageId = (0, peer_id_1.newid)();
-            pkg.version = "1.0.0";
-            pkg.provides((0, index_1.defineContract)(contract));
-        }));
-        const contract = { contractId: (0, peer_id_1.newid)(), version: 1, name: "E" };
-        const toolWith = (inputSchema) => (0, index_1.defineTool)({
-            ...echo.definition,
-            inputSchema,
-            outputSchema: index_1.z.object({ doubled: index_1.z.number() }),
-            handler: () => ({ doubled: 2 }),
-        });
-        expect(build({ ...contract, tools: [toolWith(index_1.z.object({ rating: index_1.z.number().nullable() }))] })).toThrow('Tool echo input: Field "rating" uses .nullable(); an empty field is a missing field in Peers, so use .optional() (a null sent for it is removed)');
-        expect(build({
-            ...contract,
-            tools: [toolWith(index_1.z.object({ rating: index_1.z.number().nullable().default(3) }))],
-        })).toThrow('Tool echo input: Field "rating" has a default and uses .nullable()');
-        const Rows = (0, index_1.defineTable)({
-            name: "Rows",
-            description: "Rows.",
-            primaryKeyName: "rowId",
-            schema: index_1.z.object({
-                rowId: index_1.zodPeerId,
-                where: index_1.z.object({ zip: index_1.z.string().nullable() }),
-            }),
-        });
-        expect(build({ ...contract, tables: [Rows] })).toThrow('Table Rows: Field "where.zip" uses .nullable()');
-        expect(build({ ...contract, tools: [toolWith(index_1.z.object({ rating: index_1.z.number().nullish() }))] })).not.toThrow();
-    });
-    test("a tool's empty optional inputs and outputs are left out", async () => {
-        const tool = (0, index_1.defineTool)({
-            name: "rate",
-            usageDescription: "Rate something.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputSchema: index_1.z.object({
-                rating: index_1.z.number().optional(),
-                limit: index_1.z.number().default(10),
-                where: index_1.z.object({ city: index_1.z.string(), zip: index_1.z.string().optional() }).optional(),
-            }),
-            outputSchema: index_1.z.object({ note: index_1.z.string().nullish(), seen: index_1.z.unknown() }),
-            handler: (input) => ({ note: null, seen: input }),
-        });
-        const { ctx } = fakeContext();
-        // As models often send: null for an optional input, including in a nested object.
-        await expect((0, index_1.runPackageTool)(tool, { rating: null, limit: null, where: { city: "Austin", zip: null } }, ctx)).resolves.toEqual({ seen: { limit: 10, where: { city: "Austin" } } });
-    });
-    test("handlers return complete results because output schemas aren't parsed", async () => {
-        const withDefault = (0, index_1.defineTool)({
-            name: "length",
-            usageDescription: "Return a length.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputSchema: index_1.z.object({}),
-            outputSchema: index_1.z.object({ length: index_1.z.number().default(3) }),
-            handler: () => ({ length: 3 }),
-        });
-        const { ctx } = fakeContext();
-        await expect((0, index_1.runPackageTool)(withDefault, {}, ctx)).resolves.toEqual({ length: 3 });
-        // @ts-expect-error Results aren't parsed, so the handler must return the output type.
-        (0, index_1.defineTool)({
-            name: "invalidLength",
-            usageDescription: "Invalid result type.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputSchema: index_1.z.object({}),
-            outputSchema: index_1.z.object({ length: index_1.z.number().default(3) }),
-            handler: () => ({}),
-        });
-    });
-    test("passes input through untouched for a tool declared in IR", async () => {
-        let received;
-        const raw = (0, index_1.defineTool)({
-            name: "raw",
-            usageDescription: "Raw.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputFields: [{ name: "args", type: "object", description: "Anything." }],
-            outputFields: [],
-            handler: (args) => {
-                received = args;
-                return args;
-            },
-        });
-        const { ctx } = fakeContext();
-        const args = { args: { nested: { kept: true } } };
-        await expect((0, index_1.runPackageTool)(raw, args, ctx)).resolves.toEqual(args);
-        expect(received).toBe(args);
-    });
-    test("a result's undefined fields are omitted, as the bridge carries it", async () => {
-        const reply = (0, index_1.defineTool)({
-            name: "reply",
-            usageDescription: "Reply.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputSchema: index_1.z.object({}),
-            outputSchema: index_1.z.object({ result: index_1.z.string(), speech: index_1.z.string().optional() }),
-            handler: () => ({ result: "ok", speech: undefined }),
-        });
-        const { ctx } = fakeContext();
-        const result = await (0, index_1.runPackageTool)(reply, {}, ctx);
-        expect(result).toEqual({ result: "ok" });
-        expect(Object.hasOwn(result, "speech")).toBe(false);
-        const nothing = (0, index_1.defineTool)({
-            name: "nothing",
-            usageDescription: "Nothing.",
-            accessLevel: index_1.AccessLevel.Reader,
-            inputFields: [],
-            outputFields: [],
-            handler: () => undefined,
-        });
-        await expect((0, index_1.runPackageTool)(nothing, {}, ctx)).resolves.toBeUndefined();
-    });
-    test("needs schemas or fields, a handler, and a valid access level", () => {
-        const base = { name: "t", usageDescription: "", handler: () => null };
-        expect(() => (0, index_1.defineTool)({ ...base, accessLevel: 101, inputFields: [], outputFields: [] })).toThrow(/accessLevel/);
-        expect(() => (0, index_1.defineTool)({ ...base, accessLevel: 20 })).toThrow(/either inputSchema/);
-    });
-});
-describe("contractRef", () => {
-    test("a contract client runs tools as consumed calls", async () => {
-        const { ctx, calls } = fakeContext(() => ({ ok: true }));
-        const client = (0, index_1.SystemHttp)(ctx);
-        // A field left undefined is omitted, as the bridge carries the arguments.
-        await client.tools.request({
-            requestId: "r",
-            method: "GET",
-            url: "https://a.example",
-            body: undefined,
-        });
-        expect(client.tools.then).toBeUndefined();
-        expect(calls).toEqual([
-            [
-                "callConsumedTool",
-                index_1.SystemHttp.contractId,
-                1,
-                "request",
-                { requestId: "r", method: "GET", url: "https://a.example" },
-            ],
-        ]);
-        expect(Object.hasOwn(calls[0][4], "body")).toBe(false);
-        expect(() => (0, index_1.contractRef)((0, peer_id_1.newid)(), 0)).toThrow(/positive integer/);
-    });
-    test("SystemContractCatalog lists every provider of a contract", async () => {
-        const { ctx, calls } = fakeContext(() => ({ providers: [] }));
-        const listed = await (0, index_1.SystemContractCatalog)(ctx).tools.listContractProviders({
-            contractId: "c",
-            version: 1,
-        });
-        expect(listed).toEqual({ providers: [] });
-        expect(calls).toEqual([
-            [
-                "callConsumedTool",
-                system_ids_1.contractCatalogContractId,
-                1,
-                "listContractProviders",
-                { contractId: "c", version: 1 },
-            ],
-        ]);
-    });
-    test("awaiting, logging, or converting a client calls no tools", async () => {
-        const { ctx, calls } = fakeContext(() => {
-            throw new Error("No tool should run");
-        });
-        const client = (0, index_1.SystemHttp)(ctx);
-        // The sandbox console formats objects with JSON.stringify.
-        expect(JSON.stringify(client)).toBe('{"tools":{},"tables":{},"observables":{}}');
-        expect(() => String(client.tools)).toThrow(TypeError);
-        expect(await client.tools).toBe(client.tools);
-        expect(await client.tables).toBe(client.tables);
-        expect(await client.observables).toBe(client.observables);
-        expect(calls).toEqual([]);
-    });
-    test("a reference typed with a contract types its tools and tables", async () => {
-        const contractId = "00muxgugn6u6qncnno1ywu6tl";
-        const add = (0, index_1.defineTool)({
-            name: "add",
-            usageDescription: "Add an item.",
-            accessLevel: index_1.AccessLevel.Writer,
-            inputSchema: index_1.z.object({ name: index_1.z.string() }),
-            outputSchema: index_1.z.object({ count: index_1.z.number() }),
-            handler: () => ({ count: 1 }),
-        });
-        const ping = (0, index_1.defineTool)({
-            name: "ping",
-            usageDescription: "Nothing to send.",
-            accessLevel: 0,
-            inputSchema: index_1.z.object({ note: index_1.z.string().optional() }),
-            outputSchema: index_1.z.object({}),
-            handler: () => ({}),
-        });
-        const Main = (0, index_1.defineContract)({
-            contractId,
-            version: 2,
-            name: "Main",
-            tables: [Items],
-            tools: [add, ping],
-        });
-        const { ctx, calls } = fakeContext((method, args) => {
-            if (method === "callConsumedTool")
-                return { count: 4 };
-            if (args[3] === "list")
-                return [{ itemId: "a", name: "milk", done: false }];
-            if (args[3] === "save")
-                return args[4][0];
-            return null;
-        });
-        expect(Object.isFrozen(Main.tools)).toBe(true);
-        expect(() => {
-            // @ts-expect-error contract members are immutable
-            Main.tools.push(ping);
-        }).toThrow(TypeError);
-        const MainRef = (0, index_1.contractRef)(contractId, 2);
-        const main = MainRef(ctx);
-        const added = await main.tools.add({ name: "milk" });
-        expect(added).toEqual({ count: 4 });
-        await main.tools.ping();
-        const rows = await main.tables.Items.list({ done: false });
-        const name = rows[0].name;
-        expect(name).toBe("milk");
-        expect(await main.tables.Items.get("a")).toBeUndefined();
-        // Sent as given: the providing package's table parses it, defaults included.
-        const saved = await main.tables.Items.save({
-            itemId: "b",
-            name: "eggs",
-            done: true,
-            note: undefined,
-        });
-        expect(Object.hasOwn(saved, "note")).toBe(false);
-        expect(calls).toEqual([
-            ["callConsumedTool", contractId, 2, "add", { name: "milk" }],
-            ["callConsumedTool", contractId, 2, "ping", undefined],
-            ["callConsumedTable", contractId, 2, "Items", "list", [{ done: false }, {}]],
-            ["callConsumedTable", contractId, 2, "Items", "get", ["a"]],
-            [
-                "callConsumedTable",
-                contractId,
-                2,
-                "Items",
-                "save",
-                [{ itemId: "b", name: "eggs", done: true }],
-            ],
-        ]);
-        const inputTypeChecks = () => {
-            // The provider fills `done`'s default, so a consumer may leave it out.
-            void main.tables.Items.save({ itemId: "c", name: "bread" });
-            // @ts-expect-error `name` has no default
-            void main.tables.Items.save({ itemId: "c" });
-        };
-        void inputTypeChecks;
-        // @ts-expect-error the version doesn't match the contract's
-        (0, index_1.contractRef)(contractId, 1);
-        // @ts-expect-error nor does the id
-        (0, index_1.contractRef)((0, peer_id_1.newid)(), 2);
-        // @ts-expect-error add needs its input
-        void main.tools.add();
-        // @ts-expect-error no such tool
-        void main.tools.remove;
-        // @ts-expect-error no such table
-        void main.tables.Notes;
-    });
-});
-/** Owned pvars kept in memory, notifying watchers the way the host does after each write. */
-function pvarHost(initial = {}) {
-    const store = new Map(Object.entries(initial));
-    const watchers = new Map();
-    const saves = [];
-    const write = (name, value) => {
-        store.set(name, value);
-        for (const watcher of watchers.get(name) ?? []) {
-            void watcher();
-        }
-    };
-    const ctx = {
-        getOwnedPersistentVar: async (_scope, name) => store.get(name) ?? null,
-        setOwnedPersistentVar: async (scope, name, value) => {
-            saves.push([scope, name, value]);
-            write(name, value);
-            return value;
-        },
-        watchOwnedPersistentVar: async (_scope, name, handler) => {
-            const set = watchers.get(name) ?? new Set();
-            set.add(handler);
-            watchers.set(name, set);
-            return () => set.delete(handler);
-        },
-    };
-    return { ctx, store, saves, changeElsewhere: write };
-}
-const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
-/** A package with nothing on it, to start the variables with. */
-const bare = (0, index_1.definePackage)((pkg) => {
-    pkg.packageId = (0, peer_id_1.newid)();
-    pkg.version = "1.0.0";
-});
-describe("package variables", () => {
-    test("outside a worker a variable is an in-memory observable with its default", async () => {
-        const name = `memory-${(0, peer_id_1.newid)()}`;
-        const schedule = (0, index_1.deviceVar)(name, { defaultValue: "" });
-        expect((0, index_1.deviceVar)(name, { defaultValue: "" })).toBe(schedule);
-        expect(schedule()).toBe("");
-        expect(await schedule.loadingPromise).toBe(schedule);
-        schedule("s1");
-        expect(schedule()).toBe("s1");
-        expect((0, index_1.deviceVar)(`unset-${(0, peer_id_1.newid)()}`)()).toBeUndefined();
-        expect(() => (0, index_1.deviceVar)("")).toThrow(/needs a name/);
-    });
-    test("the worker start loads stored values, saves writes, and follows changes from elsewhere", async () => {
-        const name = `count-${(0, peer_id_1.newid)()}`;
-        const count = (0, index_1.userVar)(name, { defaultValue: 0 });
-        const host = pvarHost({ [name]: 5 });
-        await (0, index_1.startPackage)(bare, host.ctx);
-        expect(count()).toBe(5);
-        const seen = [];
-        count.subscribe((value) => seen.push(value));
-        count(6);
-        await count.loadingPromise;
-        expect(host.saves).toEqual([["user", name, 6]]);
-        host.changeElsewhere(name, 9);
-        await settle();
-        expect(count()).toBe(9);
-        expect(seen).toEqual([6, 9]);
-        // A value read from the host isn't saved back.
-        expect(host.saves).toHaveLength(1);
-    });
-    test("a subscriber's write in response to a change from elsewhere is saved", async () => {
-        const name = `clamp-${(0, peer_id_1.newid)()}`;
-        const level = (0, index_1.deviceVar)(name, { defaultValue: 0 });
-        const host = pvarHost();
-        await (0, index_1.startPackage)(bare, host.ctx);
-        level.subscribe((value) => {
-            if (value > 10)
-                level(10);
-        });
-        host.changeElsewhere(name, 50);
-        await settle();
-        await level.loadingPromise;
-        await settle();
-        expect(level()).toBe(10);
-        expect(host.saves).toEqual([["device", name, 10]]);
-        expect(host.store.get(name)).toBe(10);
-    });
-    test("writes save in order and the variable ends on the last one", async () => {
-        const name = `order-${(0, peer_id_1.newid)()}`;
-        const host = pvarHost();
-        await (0, index_1.startPackage)(bare, host.ctx);
-        const step = (0, index_1.deviceVar)(name, { defaultValue: 0 });
-        await step.loadingPromise;
-        step(1);
-        step(2);
-        step(3);
-        await step.loadingPromise;
-        await settle();
-        expect(host.saves.map(([, , value]) => value)).toEqual([1, 2, 3]);
-        expect(step()).toBe(3);
-        expect(host.store.get(name)).toBe(3);
-    });
-    test("a variable declared after the worker starts loads right away, and delete resets it", async () => {
-        const name = `late-${(0, peer_id_1.newid)()}`;
-        const host = pvarHost({ [name]: { theme: "dark" } });
-        await (0, index_1.startPackage)(bare, host.ctx);
-        const prefs = (0, index_1.deviceVar)(name, { defaultValue: { theme: "light" } });
-        await prefs.loadingPromise;
-        expect(prefs()).toEqual({ theme: "dark" });
-        // An equal object from a re-read notifies no one.
-        const seen = [];
-        prefs.subscribe((value) => seen.push(value));
-        host.changeElsewhere(name, { theme: "dark" });
-        await settle();
-        expect(seen).toEqual([]);
-        await prefs.delete();
-        await settle();
-        expect(prefs()).toEqual({ theme: "light" });
-        expect(host.store.get(name)).toBeNull();
-        expect(host.saves.at(-1)).toEqual(["device", name, null]);
-    });
-});
-describe("definePackage and buildPackageManifest", () => {
-    const packageId = (0, peer_id_1.newid)();
-    const contractId = (0, peer_id_1.newid)();
-    const Notes = (0, index_1.defineTable)({
-        name: "Notes",
-        description: "Private notes.",
-        primaryKeyName: "noteId",
-        schema: index_1.z.object({ noteId: index_1.zodPeerId, text: index_1.z.string() }),
-        localOnly: true,
-    });
-    const add = (0, index_1.defineTool)({
-        name: "add",
-        usageDescription: "Add an item.",
-        accessLevel: index_1.AccessLevel.Writer,
-        timeoutMs: 5_000,
-        inputSchema: index_1.z.object({ name: index_1.z.string().describe("Item name.") }),
-        outputSchema: index_1.z.object({ items: index_1.z.array(itemSchema).describe("All items.") }),
-        handler: async () => ({ items: [] }),
-    });
-    const Other = (0, index_1.contractRef)((0, peer_id_1.newid)(), 2);
-    function define(overrides) {
-        return (0, index_1.definePackage)((pkg) => {
-            pkg.packageId = packageId;
-            pkg.version = "1.2.3";
-            pkg.tables = [Notes];
-            pkg.provides((0, index_1.defineContract)({
-                contractId,
-                version: 1,
-                name: "Main",
-                description: "The main contract.",
-                tables: [Items],
-                tools: [add],
-            }));
-            pkg.consumes(index_1.SystemHttp);
-            pkg.consumes(Other, { optional: true });
-            pkg.network = { allowedHosts: ["a.example"] };
-            pkg.appNavs = [{ name: "Main", iconClassName: "bi bi-list", navigationPath: "app" }];
-            overrides(pkg);
-        });
-    }
-    test("produces the manifest in Peers IR, and it validates", () => {
-        const manifest = (0, manifest_1.buildPackageManifest)(define(() => undefined));
-        expect(manifest).toEqual({
-            packageId,
-            version: "1.2.3",
-            guestApi: 3,
-            provides: [
-                {
-                    contractId,
-                    version: 1,
-                    name: "Main",
-                    description: "The main contract.",
-                    tables: [{ name: "Items" }],
-                    tools: [
-                        {
-                            name: "add",
-                            usageDescription: "Add an item.",
-                            suggestedAccessLevel: 40,
-                            timeoutMs: 5_000,
-                            inputFields: [{ name: "name", type: "string", description: "Item name." }],
-                            outputFields: [
-                                {
-                                    name: "items",
-                                    type: "object",
-                                    isArray: true,
-                                    description: "All items.",
-                                    fields: [
-                                        { name: "itemId", type: "id", description: "Item id." },
-                                        { name: "name", type: "string", description: "Item name." },
-                                        { name: "done", type: "boolean", description: "Checked off." },
-                                        { name: "note", type: "string", optional: true, description: "Free text." },
-                                    ],
-                                },
-                            ],
-                        },
-                    ],
-                },
-            ],
-            consumes: [
-                { contractId: index_1.SystemHttp.contractId, version: 1 },
-                { contractId: Other.contractId, version: 2, optional: true },
-            ],
-            tables: [
-                {
-                    name: "Notes",
-                    description: "Private notes.",
-                    primaryKeyName: "noteId",
-                    fields: [
-                        { name: "noteId", type: "id" },
-                        { name: "text", type: "string" },
-                    ],
-                    localOnly: true,
-                },
-                {
-                    name: "Items",
-                    description: "Things to do.",
-                    primaryKeyName: "itemId",
-                    // The default for `done` is a function; it stays in the package.
-                    fields: [
-                        { name: "itemId", type: "id", description: "Item id." },
-                        { name: "name", type: "string", description: "Item name." },
-                        { name: "done", type: "boolean", description: "Checked off." },
-                        { name: "note", type: "string", optional: true, description: "Free text." },
-                    ],
-                },
-            ],
-            network: { allowedHosts: ["a.example"] },
-            appNavs: [{ name: "Main", iconClassName: "bi bi-list", navigationPath: "app" }],
-        });
-        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "void 0;" })).not.toThrow();
-    });
-    test("rejects bad ids, duplicate tools, and clashing tables", () => {
-        expect(() => define((pkg) => {
-            pkg.packageId = "nope";
-        })).toThrow(/packageId/);
-        expect(() => (0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "Dup", tools: [add, add] })).toThrow(/declares tool "add" twice/);
-        expect(() => (0, index_1.defineContract)({ contractId: "nope", version: 1, name: "Bad id" })).toThrow(/25-character contract id/);
-        expect(() => (0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 0, name: "Bad version" })).toThrow(/positive integer/);
-        expect(() => (0, index_1.defineContract)({ contractId: (0, peer_id_1.newid)(), version: 1, name: "Not a tool", tools: [{}] })).toThrow(/isn't a tool from defineTool/);
-        expect(() => define((pkg) => {
-            pkg.provides((0, index_1.defineContract)({ contractId, version: 1, name: "Again" }));
-        })).toThrow(/is provided twice/);
-        expect(() => define((pkg) => {
-            pkg.provides({ contractId, version: 1 });
-        })).toThrow(/pkg.provides takes a contract from defineContract/);
-        expect(() => define((pkg) => {
-            pkg.consumes({ contractId, version: 1 });
-        })).toThrow(/pkg.consumes takes a reference from contractRef/);
-        expect(() => define((pkg) => {
-            pkg.tables = [
-                Notes,
-                (0, index_1.defineTable)({
-                    name: "Notes",
-                    description: "",
-                    primaryKeyName: "id",
-                    schema: index_1.z.object({ id: index_1.zodPeerId }),
-                }),
-            ];
-        })).toThrow(/Two different tables are named "Notes"/);
-    });
-    test("servePackage registers each provided tool, and only inside a worker", async () => {
-        const definition = define(() => undefined);
-        expect(() => (0, index_1.servePackage)(definition)).toThrow(/inside an isolated package worker/);
-        const registered = new Map();
-        const handlers = [];
-        const startHooks = [];
-        const global = globalThis;
-        global.registerContractTool = (id, version, name, fn) => registered.set(`${id}@${version}:${name}`, fn);
-        global.registerHandler = (name) => handlers.push(name);
-        global.onWorkerStart = (fn) => startHooks.push(fn);
-        try {
-            (0, index_1.servePackage)(definition);
-        }
-        finally {
-            delete global.registerContractTool;
-            delete global.registerHandler;
-            delete global.onWorkerStart;
-        }
-        expect([...registered.keys()]).toEqual([`${contractId}@1:add`]);
-        // The contract's tables, observables, and events are served by the package (guest API 3).
-        expect(handlers).toEqual([
-            (0, contract_members_1.contractMemberHandlerName)(contractId, 1),
-            (0, contract_members_1.contractDeliveryHandlerName)(contractId, 1),
-        ]);
-        // Package variables load when the worker starts.
-        expect(startHooks).toHaveLength(1);
-        const { ctx } = fakeContext();
-        await expect(registered.get(`${contractId}@1:add`)?.({ name: "x" }, ctx)).resolves.toEqual({
-            items: [],
-        });
-    });
-});
-describe("the package entry", () => {
-    /** Runtime imports reachable from `src/define/index.ts`, following relative modules. */
-    function runtimeImports() {
-        const bare = new Set();
-        const seen = new Set();
-        const visit = (file) => {
-            if (seen.has(file))
-                return;
-            seen.add(file);
-            const source = (0, node_fs_1.readFileSync)(file, "utf8");
-            const specifiers = [
-                ...source.matchAll(/^(?:import|export)\s+(?!type\b)[^;]*?from\s+"([^"]+)";/gms),
-            ].map((match) => match[1]);
-            for (const specifier of specifiers) {
-                if (specifier.startsWith(".")) {
-                    visit(path.resolve(path.dirname(file), `${specifier}.ts`));
-                }
-                else {
-                    bare.add(specifier);
-                }
-            }
-        };
-        visit(path.join(__dirname, "index.ts"));
-        return bare;
-    }
-    test("loads only zod and tweetnacl, so a sandbox bundle stays small", () => {
-        expect([...runtimeImports()].sort()).toEqual(["tweetnacl", "zod"]);
-    });
-});