@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/define/define.test.js

@@ -0,0 +1,1010 @@
+"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"]);
+    });
+});