@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/define/events-observables.test.js

@@ -0,0 +1,1013 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const peer_id_1 = require("../peer-id");
+const index_1 = require("./index");
+const manifest_1 = require("./manifest");
+const packageId = (0, peer_id_1.newid)();
+const contractId = (0, peer_id_1.newid)();
+const otherContractId = (0, peer_id_1.newid)();
+/** A worker ctx that records emits and publishes, and keeps the observable write handlers. */
+function workerHost(publish = async () => null) {
+    const calls = [];
+    const saves = [];
+    const setters = new Map();
+    const ctx = {
+        emitContractEvent: async (...args) => {
+            calls.push(["emit", ...args]);
+            return null;
+        },
+        publishOwnedObservable: async (...args) => {
+            calls.push(["publish", ...args]);
+            return publish(args[3]);
+        },
+        onOwnedObservableSet: (id, version, name, handler) => {
+            setters.set(`${id}@${version}:${name}`, handler);
+        },
+        getOwnedPersistentVar: async () => null,
+        setOwnedPersistentVar: async (...args) => {
+            saves.push(args);
+            return args[2];
+        },
+        watchOwnedPersistentVar: async () => () => undefined,
+    };
+    return { ctx, calls, saves, setters };
+}
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+const ping = (0, index_1.defineTool)({
+    name: "ping",
+    usageDescription: "Answers.",
+    accessLevel: index_1.AccessLevel.Reader,
+    inputSchema: index_1.z.object({}),
+    outputSchema: index_1.z.object({}),
+    handler: () => ({}),
+});
+const alertEvent = (0, index_1.defineEvent)({
+    name: "alert",
+    description: "Something finished.",
+    payloadSchema: index_1.z.object({
+        title: index_1.z.string().describe("Short title."),
+        kind: index_1.z.string().default("info").describe("Alert kind."),
+    }),
+});
+/** Declare a package with `fill` adding members to two provided contracts. */
+function define(fill) {
+    const main = { events: [], observables: [] };
+    const other = { events: [], observables: [] };
+    fill(main, other);
+    return (0, index_1.definePackage)((pkg) => {
+        pkg.packageId = packageId;
+        pkg.version = "1.0.0";
+        pkg.provides((0, index_1.defineContract)({
+            contractId,
+            version: 1,
+            name: "Main",
+            description: "The main contract.",
+            tools: [ping],
+            events: main.events,
+            observables: main.observables,
+        }));
+        pkg.provides((0, index_1.defineContract)({
+            contractId: otherContractId,
+            version: 1,
+            name: "Other",
+            description: "Another contract.",
+            tools: [ping],
+            events: other.events,
+            observables: other.observables,
+        }));
+    });
+}
+describe("outside a worker", () => {
+    test("emit checks the payload and sends nothing", async () => {
+        await expect(alertEvent.emit({ title: "Done" })).resolves.toBeUndefined();
+        await expect(alertEvent.emit({ title: 5 })).rejects.toThrow(/Expected string/);
+        const heartbeat = (0, index_1.defineEvent)({ name: "heartbeat", description: "No payload." });
+        await expect(heartbeat.emit()).resolves.toBeUndefined();
+    });
+    test("emit checks what the bridge can carry, without structuredClone (jsdom lacks it)", async () => {
+        const event = (0, index_1.defineEvent)({
+            name: "anything",
+            description: "An untyped payload.",
+            payloadSchema: index_1.z.object({ value: index_1.z.any() }),
+        });
+        const global = globalThis;
+        const original = global.structuredClone;
+        delete global.structuredClone;
+        try {
+            const shared = { label: "same" };
+            await expect(event.emit({ value: { a: shared, b: [shared], when: new Date(0) } })).resolves.toBeUndefined();
+            await expect(event.emit({ value: new Map() })).rejects.toThrow("value.value is a Map, which can't be sent");
+            await expect(event.emit({ value: [() => 1] })).rejects.toThrow("value.value[0] is a function, which can't be sent");
+            await expect(event.emit({ value: Number.NaN })).rejects.toThrow(/only finite numbers/);
+            const cycle = {};
+            cycle.self = cycle;
+            await expect(event.emit({ value: cycle })).rejects.toThrow(/cycles can't be sent/);
+        }
+        finally {
+            global.structuredClone = original;
+        }
+    });
+    test("an object payload schema rejects null instead of treating it as an empty object", async () => {
+        const event = (0, index_1.defineEvent)({
+            name: "defaults",
+            description: "An object payload.",
+            payloadSchema: index_1.z.object({ kind: index_1.z.string().default("info") }),
+        });
+        await expect(event.emit(null)).rejects.toThrow(/Expected object/);
+    });
+    test("an event or observable is checked when it's declared", () => {
+        expect(() => (0, index_1.defineEvent)({ name: "", description: "" })).toThrow(/requires a name/);
+        expect(() => (0, index_1.defineEvent)({
+            name: "x",
+            description: "",
+            payloadSchema: index_1.z.object({}),
+            payloadFields: [],
+        })).toThrow(/either payloadSchema or payloadFields/);
+        const source = (0, index_1.observable)(0);
+        expect(() => (0, index_1.defineObservable)({ name: "count", description: "Count.", source })).toThrow(/either a schema or a valueType/);
+        expect(() => (0, index_1.defineObservable)({
+            name: "count",
+            description: "Count.",
+            schema: index_1.z.number(),
+            source: 0,
+        })).toThrow(/needs a source/);
+        expect(() => (0, index_1.defineObservable)({
+            name: "count",
+            description: "Count.",
+            schema: index_1.z.number(),
+            source: (0, index_1.deviceVar)(`no-default-${(0, peer_id_1.newid)()}`),
+        })).toThrow(/needs a defaultValue/);
+    });
+});
+test("an emit made before the worker starts waits for the start", async () => {
+    const definition = define((main) => {
+        main.events = [alertEvent];
+    });
+    const global = globalThis;
+    global.onWorkerStart = () => undefined;
+    try {
+        const host = workerHost();
+        const pending = alertEvent.emit({ title: "Early" });
+        await settle();
+        expect(host.calls).toEqual([]);
+        await (0, index_1.startPackage)(definition, host.ctx);
+        await pending;
+        expect(host.calls).toEqual([
+            ["emit", contractId, 1, "alert", { title: "Early", kind: "info" }],
+        ]);
+    }
+    finally {
+        delete global.onWorkerStart;
+    }
+});
+describe("the manifest", () => {
+    test.each([
+        index_1.z.object({ note: index_1.z.string().optional() }).nullable().readonly(),
+        index_1.z.object({ note: index_1.z.string().optional() }).nullable().brand(),
+        index_1.z
+            .object({ note: index_1.z.string().optional() })
+            .nullable()
+            .refine(() => true),
+        index_1.z.object({ note: index_1.z.string().optional() }).nullable().default(null),
+    ])("a wrapped nullable whole observable value is allowed (%#)", (schema) => {
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "maybe",
+                    description: "May have no value.",
+                    schema,
+                    source: (0, index_1.observable)(null),
+                }),
+            ];
+        });
+        const manifest = (0, manifest_1.buildPackageManifest)(definition);
+        expect(manifest.provides[0].observables?.[0].value).toMatchObject({
+            type: "object",
+            optional: true,
+            fields: [{ name: "note", type: "string", optional: true }],
+        });
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "void 0;" }, { strict: true })).not.toThrow();
+    });
+    test("nullable fields inside a nullable observable still fail the build", () => {
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "maybe",
+                    description: "May have no value.",
+                    schema: index_1.z.object({ note: index_1.z.string().nullable() }).nullable().readonly(),
+                    source: (0, index_1.observable)(null),
+                }),
+            ];
+        });
+        expect(() => (0, manifest_1.buildPackageManifest)(definition)).toThrow('Observable maybe value: Field "value.note" uses .nullable()');
+    });
+    test("an IR event configuration may leave payloadSchema undefined", () => {
+        const options = {
+            name: "configured",
+            description: "Configured from IR.",
+            payloadSchema: undefined,
+            payloadFields: [{ name: "title", type: index_1.FieldType.string }],
+        };
+        const event = (0, index_1.defineEvent)(options);
+        const definition = define((main) => {
+            main.events = [event];
+        });
+        expect((0, manifest_1.buildPackageManifest)(definition).provides[0].events).toEqual([
+            {
+                name: options.name,
+                description: options.description,
+                payloadFields: options.payloadFields,
+            },
+        ]);
+    });
+    test("event fields describe parsed output through wrappers, transforms, and arrays", () => {
+        const event = (0, index_1.defineEvent)({
+            name: "shapes",
+            description: "Parsed event values.",
+            payloadSchema: index_1.z.object({
+                maybe: index_1.z.string().optional().brand().readonly(),
+                detail: index_1.z.string().nullish(),
+                size: index_1.z.string().transform((value) => value.length),
+                matrix: index_1.z.array(index_1.z.array(index_1.z.number())),
+                nullableItems: index_1.z.array(index_1.z.string().nullable()),
+            }),
+        });
+        const definition = define((main) => {
+            main.events = [event];
+        });
+        expect((0, manifest_1.buildPackageManifest)(definition).provides[0].events?.[0].payloadFields).toEqual([
+            { name: "maybe", type: "string", optional: true },
+            { name: "detail", type: "string", optional: true },
+            { name: "size", type: "any", optional: true },
+            { name: "matrix", type: "any", isArray: true },
+            { name: "nullableItems", type: "any", isArray: true },
+        ]);
+    });
+    test("nested event fields use parsed output rules at every level", () => {
+        const event = (0, index_1.defineEvent)({
+            name: "nested",
+            description: "Nested parsed values.",
+            payloadSchema: index_1.z.object({
+                detail: index_1.z.object({
+                    changed: index_1.z.string().transform((value) => value.length),
+                    piped: index_1.z.string().transform(Number).pipe(index_1.z.number()),
+                    items: index_1.z.array(index_1.z.object({ matrix: index_1.z.array(index_1.z.array(index_1.z.number())) })),
+                    modes: index_1.z.array(index_1.z.enum(["on", "off"]).nullable()),
+                }),
+            }),
+        });
+        const definition = define((main) => {
+            main.events = [event];
+        });
+        const manifest = (0, manifest_1.buildPackageManifest)(definition);
+        expect(manifest.provides[0].events?.[0].payloadFields).toEqual([
+            {
+                name: "detail",
+                type: "object",
+                fields: [
+                    { name: "changed", type: "any", optional: true },
+                    { name: "piped", type: "number" },
+                    {
+                        name: "items",
+                        type: "object",
+                        isArray: true,
+                        fields: [{ name: "matrix", type: "any", isArray: true }],
+                    },
+                    { name: "modes", type: "any", isArray: true },
+                ],
+            },
+        ]);
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "void 0;" }, { strict: true })).not.toThrow();
+    });
+    test("carries events and observables as IR", () => {
+        const location = (0, index_1.groupVar)(`location-${(0, peer_id_1.newid)()}`, {
+            defaultValue: { query: "", unit: "F" },
+        });
+        const conditions = (0, index_1.observable)(null);
+        const definition = define((main, other) => {
+            main.events = [
+                alertEvent,
+                (0, index_1.defineEvent)({ name: "ping", description: "No payload." }),
+                { name: "raw", description: "IR as is.", payloadFields: [] },
+            ];
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "location",
+                    description: "Saved city.",
+                    schema: index_1.z.object({ query: index_1.z.string(), unit: index_1.z.enum(["F", "C"]) }),
+                    writable: true,
+                    source: location,
+                }),
+                (0, index_1.defineObservable)({
+                    name: "conditions",
+                    description: "Latest reading.",
+                    schema: index_1.z.object({ temp: index_1.z.number() }).nullable(),
+                    source: conditions,
+                }),
+                (0, index_1.defineObservable)({
+                    name: "recent",
+                    description: "Recent cities.",
+                    schema: index_1.z.array(index_1.z.string()),
+                    source: (0, index_1.observable)([]),
+                }),
+                (0, index_1.defineObservable)({
+                    name: "status",
+                    description: "IR value type.",
+                    valueType: index_1.FieldType.string,
+                    source: (0, index_1.observable)("idle"),
+                }),
+                (0, index_1.defineObservable)({
+                    name: "mode",
+                    description: "An enum.",
+                    schema: index_1.z.enum(["a", "b"]).default("a"),
+                    source: (0, index_1.observable)("a"),
+                }),
+                (0, index_1.defineObservable)({
+                    name: "answer",
+                    description: "A literal.",
+                    schema: index_1.z.literal(42),
+                    source: (0, index_1.observable)(42),
+                }),
+                (0, index_1.defineObservable)({
+                    name: "owner",
+                    description: "A peer id.",
+                    schema: index_1.zodPeerId,
+                    source: (0, index_1.observable)((0, peer_id_1.newid)()),
+                }),
+            ];
+            other.observables = [
+                {
+                    name: "skill",
+                    description: "IR with its variable.",
+                    valueType: index_1.FieldType.object,
+                    writable: false,
+                    persistentVar: { scope: "device", name: "skill", defaultValue: {} },
+                },
+            ];
+        });
+        const manifest = (0, manifest_1.buildPackageManifest)(definition);
+        const [main, other] = manifest.provides;
+        expect(main.events).toEqual([
+            {
+                name: "alert",
+                description: "Something finished.",
+                payloadFields: [
+                    { name: "title", type: "string", description: "Short title." },
+                    { name: "kind", type: "string", description: "Alert kind." },
+                ],
+            },
+            { name: "ping", description: "No payload.", payloadFields: [] },
+            { name: "raw", description: "IR as is.", payloadFields: [] },
+        ]);
+        expect(main.observables).toEqual([
+            {
+                name: "location",
+                description: "Saved city.",
+                valueType: "object",
+                value: {
+                    type: "object",
+                    fields: [
+                        { name: "query", type: "string" },
+                        { name: "unit", type: "string", enumValues: ["F", "C"] },
+                    ],
+                },
+                writable: true,
+                persistentVar: {
+                    scope: "group",
+                    name: expect.stringMatching(/^location-/),
+                    defaultValue: { query: "", unit: "F" },
+                },
+            },
+            {
+                name: "conditions",
+                description: "Latest reading.",
+                valueType: "any",
+                // The full shape says what `valueType` can't: an object, or empty (null).
+                value: { type: "object", optional: true, fields: [{ name: "temp", type: "number" }] },
+                writable: false,
+            },
+            {
+                name: "recent",
+                description: "Recent cities.",
+                valueType: "object",
+                value: { type: "string", isArray: true },
+                writable: false,
+            },
+            { name: "status", description: "IR value type.", valueType: "string", writable: false },
+            {
+                name: "mode",
+                description: "An enum.",
+                valueType: "string",
+                value: { type: "string", enumValues: ["a", "b"] },
+                writable: false,
+            },
+            {
+                name: "answer",
+                description: "A literal.",
+                valueType: "number",
+                value: { type: "number", enumValues: [42] },
+                writable: false,
+            },
+            {
+                name: "owner",
+                description: "A peer id.",
+                valueType: "id",
+                value: { type: "id" },
+                writable: false,
+            },
+        ]);
+        expect(other.observables).toEqual([
+            {
+                name: "skill",
+                description: "IR with its variable.",
+                valueType: "object",
+                writable: false,
+                persistentVar: { scope: "device", name: "skill", defaultValue: {} },
+            },
+        ]);
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest, providerSource: "x" })).not.toThrow();
+    });
+    test("transforms use any without executing schema code to infer the wire type", () => {
+        const transform = jest.fn((value) => value.length);
+        const refine = jest.fn(() => true);
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "length",
+                    description: "A transformed value.",
+                    schema: index_1.z.string().transform(transform),
+                    writable: true,
+                    source: (0, index_1.observable)(0),
+                }),
+                (0, index_1.defineObservable)({
+                    name: "optional",
+                    description: "An optional refined value.",
+                    schema: index_1.z.string().optional().refine(refine),
+                    source: (0, index_1.observable)(),
+                }),
+            ];
+        });
+        expect((0, manifest_1.buildPackageManifest)(definition).provides[0].observables?.map((o) => o.valueType)).toEqual([index_1.FieldType.any, index_1.FieldType.any]);
+        expect(transform).not.toHaveBeenCalled();
+        expect(refine).not.toHaveBeenCalled();
+    });
+    test.each([
+        index_1.z.date().nullable(),
+        index_1.z.bigint().optional(),
+        index_1.z.array(index_1.z.date()),
+        index_1.z.object({ nested: index_1.z.map(index_1.z.string(), index_1.z.number()) }),
+        index_1.z.record(index_1.z.set(index_1.z.string())),
+        index_1.z.tuple([index_1.z.string(), index_1.z.symbol()]),
+        index_1.z.union([index_1.z.string(), index_1.z.date()]),
+        index_1.z.lazy(() => index_1.z.object({ nested: index_1.z.date() })),
+        index_1.z.literal(1n),
+        index_1.z.nan(),
+    ])("rejects non-JSON schemas inside wrappers and containers (%#)", (schema) => {
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "invalid",
+                    description: "Non-JSON.",
+                    schema,
+                    source: (0, index_1.observable)(null),
+                }),
+            ];
+        });
+        expect(() => (0, manifest_1.buildPackageManifest)(definition)).toThrow(/its value must be JSON/);
+    });
+    test("rejects what an observable can't hold or a contract can't list", () => {
+        const withObservable = (item) => define((main) => {
+            main.observables = [item];
+        });
+        expect(() => (0, manifest_1.buildPackageManifest)(withObservable((0, index_1.defineObservable)({
+            name: "when",
+            description: "A date.",
+            schema: index_1.z.date(),
+            source: (0, index_1.observable)(new Date()),
+        })))).toThrow(/ZodDate schema; its value must be JSON/);
+        expect(() => (0, manifest_1.buildPackageManifest)(withObservable((0, index_1.defineObservable)({
+            name: "unit",
+            description: "Unit.",
+            schema: index_1.z.enum(["F", "C"]),
+            source: (0, index_1.deviceVar)(`unit-${(0, peer_id_1.newid)()}`, { defaultValue: "K" }),
+        })))).toThrow(/defaultValue doesn't match the schema/);
+        // The worker publishes an in-memory source's value at start; one the host would reject
+        // fails the build rather than every worker start.
+        expect(() => (0, manifest_1.buildPackageManifest)(withObservable((0, index_1.defineObservable)({
+            name: "label",
+            description: "Unset label.",
+            schema: index_1.z.string(),
+            source: (0, index_1.observable)(),
+        })))).toThrow(/label's source starts as undefined, which doesn't match its valueType string/);
+        expect(() => (0, manifest_1.buildPackageManifest)(withObservable((0, index_1.defineObservable)({
+            name: "reading",
+            description: "No reading yet.",
+            schema: index_1.z.object({ temp: index_1.z.number() }),
+            source: (0, index_1.observable)(null),
+        })))).toThrow(/reading's source starts as null, which doesn't match its valueType object/);
+        expect(() => (0, manifest_1.buildPackageManifest)(withObservable((0, index_1.defineObservable)({
+            name: "count",
+            description: "IR value type.",
+            valueType: index_1.FieldType.number,
+            source: (0, index_1.observable)("zero"),
+        })))).toThrow(/count's source starts as a string, which doesn't match its valueType number/);
+        expect(() => withObservable({ name: "status", description: "No binding.", valueType: "string" })).toThrow(/IR without a persistentVar/);
+        expect(() => withObservable({ description: "No name." })).toThrow(/isn't from defineObservable/);
+        const status = (0, index_1.defineObservable)({
+            name: "status",
+            description: "Status.",
+            valueType: index_1.FieldType.string,
+            source: (0, index_1.observable)("idle"),
+        });
+        expect(() => define((main) => {
+            main.observables = [status, status];
+        })).toThrow(/observable "status" twice/);
+        expect(() => define((main) => {
+            main.events = [alertEvent, { name: "alert", description: "Again." }];
+        })).toThrow(/event "alert" twice/);
+    });
+});
+describe("in a worker", () => {
+    test("emits omit undefined fields and snapshot optional array entries without losing wire types", async () => {
+        const event = (0, index_1.defineEvent)({
+            name: "optional",
+            description: "Optional payload values.",
+            payloadSchema: index_1.z.object({
+                extra: index_1.z.string().optional(),
+                nested: index_1.z.object({ extra: index_1.z.string().optional() }),
+                items: index_1.z.array(index_1.z.string().optional()),
+                when: index_1.z.date(),
+                bytes: index_1.z.instanceof(Uint8Array),
+            }),
+        });
+        const definition = define((main) => {
+            main.events = [event];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        const when = new Date("2026-10-21T00:00:00Z");
+        const bytes = new Uint8Array([1, 2]);
+        const payload = {
+            extra: undefined,
+            nested: { extra: undefined },
+            items: [undefined],
+            when,
+            bytes,
+        };
+        const sent = event.emit(payload);
+        bytes[0] = 3;
+        await sent;
+        expect(host.calls).toEqual([
+            [
+                "emit",
+                contractId,
+                1,
+                "optional",
+                { nested: {}, items: [null], when, bytes: new Uint8Array([1, 2]) },
+            ],
+        ]);
+        expect(Object.hasOwn(payload, "extra")).toBe(true);
+        expect(payload.nested).toEqual({ extra: undefined });
+        expect(payload.items).toEqual([undefined]);
+    });
+    test("emits, writes, and publications leave out empty optional fields", async () => {
+        const event = (0, index_1.defineEvent)({
+            name: "rated",
+            description: "A rating changed.",
+            payloadSchema: index_1.z.object({
+                note: index_1.z.string().optional(),
+                where: index_1.z.object({ zip: index_1.z.string().optional() }),
+                count: index_1.z.number().default(1),
+            }),
+        });
+        const place = (0, index_1.observable)({
+            query: "a",
+            unit: null,
+        });
+        const definition = define((main) => {
+            main.events = [event];
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "place",
+                    description: "Saved place.",
+                    schema: index_1.z.object({ query: index_1.z.string(), unit: index_1.z.enum(["F", "C"]).optional() }),
+                    writable: true,
+                    source: place,
+                }),
+            ];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        expect(host.calls).toEqual([["publish", contractId, 1, "place", { query: "a" }]]);
+        await event.emit({ note: null, where: { zip: null }, count: null });
+        expect(host.calls.at(-1)).toEqual(["emit", contractId, 1, "rated", { where: {}, count: 1 }]);
+        const write = host.setters.get(`${contractId}@1:place`);
+        await expect(Promise.resolve(write?.({ query: "b", unit: null }))).resolves.toEqual({
+            query: "b",
+        });
+        expect(place()).toEqual({ query: "b" });
+    });
+    test("array observables clean their object fields on publication and write", async () => {
+        const source = (0, index_1.observable)([{ note: null }]);
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "items",
+                    description: "Items.",
+                    schema: index_1.z.array(index_1.z.object({ note: index_1.z.string().optional() })),
+                    writable: true,
+                    source,
+                }),
+            ];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        expect(host.calls).toEqual([["publish", contractId, 1, "items", [{}]]]);
+        const write = host.setters.get(`${contractId}@1:items`);
+        await expect(Promise.resolve(write?.([{ note: null }]))).resolves.toStrictEqual([{}]);
+        expect(source()).toStrictEqual([{}]);
+    });
+    test("variables load before the initial publication of sources derived from them", async () => {
+        const saved = (0, index_1.deviceVar)(`derived-${(0, peer_id_1.newid)()}`, { defaultValue: 0 });
+        const source = (0, index_1.observable)(0);
+        const subscription = saved.subscribe(source);
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "derived",
+                    description: "Derived from stored state.",
+                    schema: index_1.z.number(),
+                    source,
+                }),
+            ];
+        });
+        let release = () => { };
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const host = workerHost(async (value) => {
+            if (value === 7)
+                await gate;
+        });
+        host.ctx.getOwnedPersistentVar = async () => 7;
+        let started = false;
+        const starting = (0, index_1.startPackage)(definition, host.ctx).then(() => {
+            started = true;
+        });
+        try {
+            await settle();
+            expect(host.calls).toEqual([["publish", contractId, 1, "derived", 7]]);
+            expect(started).toBe(false);
+        }
+        finally {
+            release();
+            await starting;
+            subscription.dispose();
+        }
+    });
+    test("onStart hooks run in order after variables load, before the first publication", async () => {
+        const saved = (0, index_1.deviceVar)(`hooked-${(0, peer_id_1.newid)()}`, { defaultValue: 0 });
+        const source = (0, index_1.observable)(0);
+        const seen = [];
+        const host = workerHost();
+        host.ctx.getOwnedPersistentVar = async () => 7;
+        const definition = (0, index_1.definePackage)((pkg) => {
+            pkg.packageId = packageId;
+            pkg.version = "1.0.0";
+            pkg.provides((0, index_1.defineContract)({
+                contractId,
+                version: 1,
+                name: "Main",
+                description: "The main contract.",
+                tools: [ping],
+                observables: [
+                    (0, index_1.defineObservable)({
+                        name: "loaded",
+                        description: "Set at the start.",
+                        schema: index_1.z.number(),
+                        source,
+                    }),
+                ],
+            }));
+            pkg.onStart(async (ctx) => {
+                seen.push(["first", saved(), ctx === host.ctx]);
+                await settle();
+                source(saved() + 1);
+            });
+            pkg.onStart(() => {
+                seen.push(["second", source()]);
+            });
+        });
+        await (0, index_1.startPackage)(definition, host.ctx);
+        expect(seen).toEqual([
+            ["first", 7, true],
+            ["second", 8],
+        ]);
+        // Readers' first value is the one the hook set.
+        expect(host.calls).toEqual([["publish", contractId, 1, "loaded", 8]]);
+    });
+    test("a failing onStart hook fails the start, and onStart takes only functions", async () => {
+        const definition = (0, index_1.definePackage)((pkg) => {
+            pkg.packageId = packageId;
+            pkg.version = "1.0.0";
+            pkg.onStart(() => {
+                throw new Error("no cache");
+            });
+        });
+        await expect((0, index_1.startPackage)(definition, workerHost().ctx)).rejects.toThrow("no cache");
+        expect(() => (0, index_1.definePackage)((pkg) => {
+            pkg.packageId = packageId;
+            pkg.version = "1.0.0";
+            pkg.onStart("later");
+        })).toThrow("pkg.onStart takes a function");
+    });
+    test("emit parses the payload and sends it on every contract that lists the event, in order", async () => {
+        const unlisted = (0, index_1.defineEvent)({ name: "unlisted", description: "On no contract." });
+        const definition = define((main, other) => {
+            main.events = [alertEvent];
+            other.events = [alertEvent];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        const first = alertEvent.emit({ title: "One" });
+        const second = alertEvent.emit({ title: "Two", kind: "timer" });
+        await Promise.all([first, second]);
+        expect(host.calls).toEqual([
+            ["emit", contractId, 1, "alert", { title: "One", kind: "info" }],
+            ["emit", otherContractId, 1, "alert", { title: "One", kind: "info" }],
+            ["emit", contractId, 1, "alert", { title: "Two", kind: "timer" }],
+            ["emit", otherContractId, 1, "alert", { title: "Two", kind: "timer" }],
+        ]);
+        await expect(alertEvent.emit({})).rejects.toThrow(/Required/);
+        await expect(unlisted.emit(undefined)).rejects.toThrow(/isn't listed on a contract/);
+    });
+    test("an in-memory observable publishes at the start and after each change, one at a time", async () => {
+        const count = (0, index_1.observable)(0);
+        const stored = (0, index_1.deviceVar)(`stored-${(0, peer_id_1.newid)()}`, { defaultValue: 1 });
+        const definition = define((main, other) => {
+            const counter = (0, index_1.defineObservable)({
+                name: "count",
+                description: "A count.",
+                schema: index_1.z.number(),
+                source: count,
+            });
+            main.observables = [
+                counter,
+                (0, index_1.defineObservable)({
+                    name: "stored",
+                    description: "Served by the host.",
+                    schema: index_1.z.number(),
+                    source: stored,
+                }),
+            ];
+            other.observables = [counter];
+        });
+        let active = 0;
+        let overlapped = false;
+        const host = workerHost(async () => {
+            active += 1;
+            overlapped ||= active > 2;
+            await settle();
+            active -= 1;
+            return null;
+        });
+        await (0, index_1.startPackage)(definition, host.ctx);
+        expect(host.calls).toEqual([
+            ["publish", contractId, 1, "count", 0],
+            ["publish", otherContractId, 1, "count", 0],
+        ]);
+        count(1);
+        count(2);
+        stored(5);
+        await settle();
+        await settle();
+        await settle();
+        expect(host.calls.slice(2)).toEqual([
+            ["publish", contractId, 1, "count", 1],
+            ["publish", otherContractId, 1, "count", 1],
+            ["publish", contractId, 1, "count", 2],
+            ["publish", otherContractId, 1, "count", 2],
+        ]);
+        // Each value's publishes run together; the next value waits for them.
+        expect(overlapped).toBe(false);
+        // The variable-backed observable is saved like any variable; the host serves it.
+        expect(host.saves).toEqual([["device", expect.stringMatching(/^stored-/), 5]]);
+        // Read-only: no write handler.
+        expect(host.setters.size).toBe(0);
+    });
+    test("queued publications capture each object before later mutation", async () => {
+        const value = (0, index_1.observable)({ count: 0 });
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "snapshot",
+                    description: "A snapshot.",
+                    schema: index_1.z.object({ count: index_1.z.number() }),
+                    source: value,
+                }),
+            ];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        host.calls.length = 0;
+        const next = { count: 1 };
+        value(next);
+        next.count = 2;
+        value.notifySubscribers();
+        await settle();
+        expect(host.calls).toEqual([
+            ["publish", contractId, 1, "snapshot", { count: 1 }],
+            ["publish", contractId, 1, "snapshot", { count: 2 }],
+        ]);
+    });
+    test("publications and parsed write replies normalize optional values without changing the source", async () => {
+        const source = (0, index_1.observable)({
+            extra: undefined,
+            nested: { extra: undefined },
+            items: [undefined],
+        });
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "optional",
+                    description: "Optional values.",
+                    schema: index_1.z.string().transform(() => ({
+                        extra: undefined,
+                        nested: { extra: undefined },
+                        items: [undefined],
+                    })),
+                    writable: true,
+                    source,
+                }),
+            ];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        expect(host.calls).toEqual([
+            ["publish", contractId, 1, "optional", { nested: {}, items: [null] }],
+        ]);
+        const write = host.setters.get(`${contractId}@1:optional`);
+        await expect(Promise.resolve(write?.("next"))).resolves.toEqual({ nested: {}, items: [null] });
+        expect(host.calls.at(-1)).toEqual([
+            "publish",
+            contractId,
+            1,
+            "optional",
+            { nested: {}, items: [null] },
+        ]);
+        expect(Object.hasOwn(source(), "extra")).toBe(true);
+        expect(source().nested).toEqual({ extra: undefined });
+        expect(source().items).toEqual([undefined]);
+    });
+    test("a write is parsed, set on the source, and resolves once the stored value is published", async () => {
+        const level = (0, index_1.observable)(1);
+        level.subscribe((value) => {
+            if (value > 10)
+                level(10);
+        });
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "level",
+                    description: "Level, at most 10.",
+                    schema: index_1.z.number().int(),
+                    writable: true,
+                    source: level,
+                }),
+            ];
+        });
+        const host = workerHost();
+        await (0, index_1.startPackage)(definition, host.ctx);
+        const write = host.setters.get(`${contractId}@1:level`);
+        expect(write).toBeDefined();
+        host.calls.length = 0;
+        await expect(Promise.resolve(write?.(1.5))).rejects.toThrow(/integer/);
+        expect(level()).toBe(1);
+        expect(host.calls).toEqual([]);
+        await expect(Promise.resolve(write?.(4))).resolves.toBe(4);
+        expect(level()).toBe(4);
+        expect(host.calls).toEqual([["publish", contractId, 1, "level", 4]]);
+        // The source's own subscriber clamps the value; what's published and returned is the result.
+        host.calls.length = 0;
+        await expect(Promise.resolve(write?.(50))).resolves.toBe(10);
+        expect(host.calls).toEqual([["publish", contractId, 1, "level", 10]]);
+    });
+    test("publications need no structuredClone and keep a __proto__ key as a field", async () => {
+        const source = (0, index_1.observable)(JSON.parse('{"__proto__": 1}'));
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "counts",
+                    description: "Counts by name.",
+                    valueType: index_1.FieldType.object,
+                    writable: true,
+                    source,
+                }),
+            ];
+        });
+        const global = globalThis;
+        const original = global.structuredClone;
+        delete global.structuredClone;
+        try {
+            const host = workerHost();
+            await (0, index_1.startPackage)(definition, host.ctx);
+            const published = host.calls[0]?.[4];
+            expect(Object.getPrototypeOf(published)).toBe(Object.prototype);
+            expect(Object.getOwnPropertyDescriptor(published, "__proto__")?.value).toBe(1);
+            const write = host.setters.get(`${contractId}@1:counts`);
+            await expect(Promise.resolve(write?.({ total: 2 }))).resolves.toEqual({ total: 2 });
+        }
+        finally {
+            global.structuredClone = original;
+        }
+    });
+    test("an object write returns the published snapshot even if its source mutates meanwhile", async () => {
+        const source = (0, index_1.observable)({ count: 0 });
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "snapshot",
+                    description: "A snapshot.",
+                    writable: true,
+                    schema: index_1.z.object({ count: index_1.z.number() }),
+                    source,
+                }),
+            ];
+        });
+        let release = () => { };
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const host = workerHost(async (value) => {
+            if (value.count === 1)
+                await gate;
+        });
+        await (0, index_1.startPackage)(definition, host.ctx);
+        const write = host.setters.get(`${contractId}@1:snapshot`);
+        const pending = Promise.resolve(write?.({ count: 1 }));
+        try {
+            await settle();
+            source().count = 2;
+        }
+        finally {
+            release();
+        }
+        await expect(pending).resolves.toEqual({ count: 1 });
+    });
+    test("an initial publish failure rejects startup; later background failures are logged", async () => {
+        const status = (0, index_1.observable)("idle");
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({
+                    name: "status",
+                    description: "Status.",
+                    schema: index_1.z.string(),
+                    source: status,
+                }),
+            ];
+        });
+        const errors = jest.spyOn(console, "error").mockImplementation(() => undefined);
+        let fail = true;
+        const host = workerHost(async () => {
+            if (fail)
+                throw new Error("host said no");
+            return null;
+        });
+        try {
+            await expect((0, index_1.startPackage)(definition, host.ctx)).rejects.toThrow("host said no");
+            fail = false;
+            await (0, index_1.startPackage)(definition, host.ctx);
+            fail = true;
+            status("broken");
+            await settle();
+            expect(errors).toHaveBeenCalledWith('Publishing observable "status" failed', expect.any(Error));
+            fail = false;
+            status("busy");
+            await settle();
+            expect(host.calls.at(-1)).toEqual(["publish", contractId, 1, "status", "busy"]);
+        }
+        finally {
+            errors.mockRestore();
+        }
+    });
+    test("starting again serves the new ctx only", async () => {
+        const mood = (0, index_1.observable)("calm");
+        const definition = define((main) => {
+            main.observables = [
+                (0, index_1.defineObservable)({ name: "mood", description: "Mood.", schema: index_1.z.string(), source: mood }),
+            ];
+        });
+        const first = workerHost();
+        const second = workerHost();
+        await (0, index_1.startPackage)(definition, first.ctx);
+        await (0, index_1.startPackage)(definition, second.ctx);
+        mood("busy");
+        await settle();
+        expect(first.calls).toEqual([["publish", contractId, 1, "mood", "calm"]]);
+        expect(second.calls).toEqual([
+            ["publish", contractId, 1, "mood", "calm"],
+            ["publish", contractId, 1, "mood", "busy"],
+        ]);
+    });
+});