@peers-app/peers-sdk 0.28.0 → 0.28.2

package/dist/contracts/host-contract-client.js

@@ -6,6 +6,7 @@ const user_context_singleton_1 = require("../context/user-context-singleton");
 const contract_ref_1 = require("../define/contract-ref");
 const lazy_members_1 = require("../define/lazy-members");
 const table_handle_1 = require("../define/table-handle");
+const wire_value_1 = require("../define/wire-value");
 const observable_1 = require("../observable");
 const contract_proxy_1 = require("./contract-proxy");
 const host_contract_transport_1 = require("./host-contract-transport");
@@ -265,7 +266,8 @@ function createHostContractClient(ref, options, onDispose) {
         const next = await connect({ timeoutMs });
         return untilReplaced(Promise.resolve().then(() => send(next.members)), next.signal);
     };
-    const tools = (0, lazy_members_1.lazyMembers)((toolName) => (...args) => call((members) => members.tool(toolName)(...args)));
+    // Arguments and values go as the bridge carries them: a field left undefined is omitted.
+    const tools = (0, lazy_members_1.lazyMembers)((toolName) => (...args) => call((members) => members.tool(toolName)(...args.map((arg) => (arg === undefined ? arg : (0, wire_value_1.snapshotPackageValue)(arg))))));
     const tables = (0, lazy_members_1.lazyMembers)((tableName) => ({
         ...(0, table_handle_1.packageTableMethods)((operation, args) => call((members) => members.table(tableName)[operation](...args))),
         dataChanged: {
@@ -317,7 +319,7 @@ function createHostContractClient(ref, options, onDispose) {
                     if (next.signal.aborted)
                         throw next.signal.reason;
                     const before = remoteRevision;
-                    const result = await untilReplaced(next.members.setObservable(observableName, value), next.signal);
+                    const result = await untilReplaced(next.members.setObservable(observableName, value === undefined ? value : (0, wire_value_1.snapshotPackageValue)(value)), next.signal);
                     if (!disposed &&
                         connection === next &&
                         remoteRevision === before &&

package/dist/data/orm/sql.data-source.js

@@ -10,6 +10,16 @@ const tool_catalog_fields_1 = require("../tool-catalog-fields");
 const data_query_1 = require("./data-query");
 const data_query_sqlite_1 = require("./data-query.sqlite");
 const types_1 = require("./types");
+/**
+ * The SQLite name {@link SQLDataSource} gives one of a table's indexes.
+ *
+ * @param tableName - Full (physical) table name.
+ * @param index - One entry of `ITableMetaData.indexes`.
+ */
+function sqlIndexName(tableName, index) {
+    const fieldNames = index.fields.map((f) => `_${typeof f === "string" ? f : f.name}`).join("");
+    return `${tableName}_${fieldNames}_${(0, utils_1.simpleHash)(JSON.stringify(index))}`;
+}
 /** SQLite-backed table storage with additive schema migration and serialized initialization. */
 class SQLDataSource {
     db;
@@ -79,22 +89,12 @@ class SQLDataSource {
         // create indexes if they don't exist
         if (this.metaData.indexes) {
             for (const index of this.metaData.indexes) {
-                let fieldNames = "";
+                // Quoted: a field may be named like an SQL keyword (`order`, `group`).
                 const fields = index.fields
-                    .map((f) => {
-                    if (typeof f === "string") {
-                        fieldNames += `_${f}`;
-                        return f;
-                    }
-                    else {
-                        fieldNames += `_${f.name}`;
-                        return `${f.name} ${f.order}`;
-                    }
-                })
+                    .map((f) => (typeof f === "string" ? `"${f}"` : `"${f.name}" ${f.order}`))
                     .join(", ");
-                const hash = (0, utils_1.simpleHash)(JSON.stringify(index));
                 const unique = index.unique ? "UNIQUE" : "";
-                const indexName = `${this.tableName}_${fieldNames}_${hash}`;
+                const indexName = sqlIndexName(this.tableName, index);
                 indexNames.push(indexName);
                 const sql = `CREATE ${unique} INDEX IF NOT EXISTS "${indexName}" ON "${this.tableName}"(${fields});`;
                 try {
@@ -102,6 +102,9 @@ class SQLDataSource {
                 }
                 catch (e) {
                     console.error(`Error creating index "${indexName}" on table "${this.tableName}": ${String(e)}`);
+                    // A package must not accept writes without its declared uniqueness constraint.
+                    if (this.metaData.packageId && index.unique)
+                        throw e;
                 }
             }
         }

package/dist/data/orm/table-container.js

@@ -160,9 +160,12 @@ class TableContainer {
         this.savingDefinitions = true;
         const tableName = (0, utils_1.getFullTableName)(metaData);
         try {
-            // Lazy import to avoid circular dependency at module load time
-            const { TableDefinitions } = require("../table-definitions-table");
-            const tableDefsTable = TableDefinitions();
+            // Lazy import to avoid circular dependency at module load time; it registers the
+            // TableDefinitions system table. Use this container's own copy: a definition belongs to
+            // the data context the table lives in, not whichever group is active.
+            require("../table-definitions-table");
+            const definitions = table_definitions_system_1.systemTableDefinitions.TableDefinitions;
+            const tableDefsTable = this.getTable(definitions.metaData, definitions.schema);
             const record = {
                 tableId: metaData.tableId,
                 name: tableName,

package/dist/data/package-table-identity.d.ts

@@ -13,6 +13,21 @@ import type { ITableDefinitionRecord } from "./table-definitions-table";
  * @throws When the identifier is empty or contains SQL syntax.
  */
 export declare function validateIsolatedSqlIdentifier(identifier: string, label?: string): string;
+/**
+ * Validate a table's index declarations: each lists at least one of the table's fields, in
+ * order, by name or as `{ name, order }` with `"ASC"` or `"DESC"`.
+ *
+ * @param indexes - The declared indexes, if any.
+ * @param fieldNames - The table's field names.
+ * @param label - Where the indexes come from, for errors.
+ * @param allowUnique - Whether an index may be unique. A package may make one unique only on a
+ *   local-only table: on a synced table two devices can each write a row the other's unique
+ *   index refuses, and package tables have no conflict resolver. A stored definition may have
+ *   one anyway (an old-style package's).
+ * @throws When an index is malformed, names a field the table lacks, or is unique when not
+ *   allowed.
+ */
+export declare function validateTableIndexes(indexes: unknown, fieldNames: ReadonlySet<string>, label: string, allowUnique?: boolean): void;
 /**
  * Validate a package-local table name.
  *

package/dist/data/package-table-identity.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateIsolatedSqlIdentifier = validateIsolatedSqlIdentifier;
+exports.validateTableIndexes = validateTableIndexes;
 exports.validatePackageTableName = validatePackageTableName;
 exports.packageScopedTableName = packageScopedTableName;
 exports.packageScopedTableId = packageScopedTableId;
@@ -29,6 +30,53 @@ function validateIsolatedSqlIdentifier(identifier, label = "Isolated SQL identif
     }
     return identifier;
 }
+/**
+ * Validate a table's index declarations: each lists at least one of the table's fields, in
+ * order, by name or as `{ name, order }` with `"ASC"` or `"DESC"`.
+ *
+ * @param indexes - The declared indexes, if any.
+ * @param fieldNames - The table's field names.
+ * @param label - Where the indexes come from, for errors.
+ * @param allowUnique - Whether an index may be unique. A package may make one unique only on a
+ *   local-only table: on a synced table two devices can each write a row the other's unique
+ *   index refuses, and package tables have no conflict resolver. A stored definition may have
+ *   one anyway (an old-style package's).
+ * @throws When an index is malformed, names a field the table lacks, or is unique when not
+ *   allowed.
+ */
+function validateTableIndexes(indexes, fieldNames, label, allowUnique = false) {
+    if (indexes === undefined)
+        return;
+    if (!Array.isArray(indexes))
+        throw new Error(`${label} must be an array`);
+    for (const [position, index] of indexes.entries()) {
+        const at = `${label}[${position}]`;
+        const { fields, unique } = (index ?? {});
+        if (!index ||
+            typeof index !== "object" ||
+            Object.keys(index).some((key) => key !== "fields" && key !== "unique") ||
+            !Array.isArray(fields) ||
+            fields.length === 0) {
+            throw new Error(`${at} must be { fields: [...] } with at least one field`);
+        }
+        if (unique !== undefined && (unique !== true || !allowUnique)) {
+            throw new Error(`${at} can be unique only on a local-only table`);
+        }
+        for (const field of fields) {
+            const name = typeof field === "string"
+                ? field
+                : field &&
+                    typeof field === "object" &&
+                    Object.keys(field).every((key) => key === "name" || key === "order") &&
+                    (field.order === "ASC" || field.order === "DESC")
+                    ? field.name
+                    : undefined;
+            if (typeof name !== "string" || !fieldNames.has(name)) {
+                throw new Error(`${at} names a field the table doesn't have`);
+            }
+        }
+    }
+}
 /**
  * Validate a package-local table name.
  *
@@ -105,18 +153,6 @@ function validateTableDefinitionRecord(record) {
     }
     if (!names.has(meta.primaryKeyName))
         throw new Error("Missing primary key column");
-    if (meta.indexes !== undefined && !Array.isArray(meta.indexes))
-        throw new Error("Invalid indexes");
-    for (const index of meta.indexes ?? []) {
-        if (!Array.isArray(index.fields) || !index.fields.length)
-            throw new Error("Missing index fields");
-        for (const field of index.fields) {
-            const name = typeof field === "string" ? field : field.name;
-            if (!names.has(name))
-                throw new Error("Index must name a declared column");
-            if (typeof field !== "string" && field.order !== "ASC" && field.order !== "DESC") {
-                throw new Error("Invalid index order");
-            }
-        }
-    }
+    // Only what reaches SQL here: an old-style package may keep a unique index on a synced table.
+    validateTableIndexes(meta.indexes, names, "Table indexes", true);
 }

package/dist/data/package-version-resolver.js

@@ -17,6 +17,7 @@ exports.resolveDevicePackageVersion = resolveDevicePackageVersion;
 exports.hasDeviceFollowOverride = hasDeviceFollowOverride;
 exports.readStoredPackageLocalPath = readStoredPackageLocalPath;
 const user_context_singleton_1 = require("../context/user-context-singleton");
+const keys_1 = require("../keys");
 const assistants_1 = require("./assistants");
 const file_types_1 = require("./files/file.types");
 const group_member_roles_1 = require("./group-member-roles");
@@ -100,12 +101,23 @@ async function assertPackageVersionRunnable(pkg, pv, dataContext, localDev = fal
     if (!localDev) {
         const prefs = packagePrefsVar(pkg.packageId, dataContext);
         await prefs.loadingPromise;
-        const deviceSelected = prefs()?.activePackageVersionId === pv.packageVersionId;
+        let selection = prefs();
+        const deviceSelected = selection?.activePackageVersionId === pv.packageVersionId;
+        if (selection && deviceSelected && !selection.activePackageVersionTag) {
+            // A selection saved before 0.28.0 has no tag. Record this version's tag once when this
+            // device's own user signed the version (their own build or release), so it keeps running;
+            // a version someone else retagged still needs a fresh activation.
+            const me = await dataContext.userContext.getMe();
+            if (me?.publicKey && (0, keys_1.signedByKey)(pv) === me.publicKey) {
+                selection = { ...selection, activePackageVersionTag: pv.versionTag };
+                prefs(selection);
+            }
+        }
         if (!deviceSelected && !(await isPackageRowAdminSigned(pkg, dataContext))) {
             throw new Error("A group package selection needs an Admin's signature before it can run");
         }
         if (pv.versionTag === "dev" &&
-            (!deviceSelected || prefs()?.activePackageVersionTag !== "dev")) {
+            (!deviceSelected || selection?.activePackageVersionTag !== "dev")) {
             throw new Error("Activate this dev version on this device before running it");
         }
     }

package/dist/define/context.d.ts

@@ -1,3 +1,4 @@
+import type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
 import type { PersistentVarScope } from "../data/persistent-var-identity";
 import type { IsolatedContractTableOperation } from "../package-loader/isolated-runtime";
 /**
@@ -21,6 +22,11 @@ export interface IPackageProviderOptions {
  * events, and observables need none; use these directly only for what those don't cover yet.
  */
 export interface IPackageContext {
+    /**
+     * The device this worker runs on. It says where the code is running, not who is calling:
+     * never use it to decide what a caller may do.
+     */
+    readonly deviceId: string;
     /** Run a tool on a contract this package consumes (or provides), as this call's caller. */
     callConsumedTool(contractId: string, version: number, toolName: string, args?: unknown, options?: IPackageProviderOptions): Promise<unknown>;
     /** Run a tool on another device. The remote device authorizes the call. */
@@ -61,6 +67,12 @@ export interface IPackageContext {
      * read it again.
      */
     watchOwnedPersistentVar(scope: PersistentVarScope, name: string, handler: () => unknown): Promise<PackageUnsubscribe>;
+    /**
+     * Call `handler` with each change to one of this package's own tables, made here or synced
+     * from another device, until the returned function is called or the worker stops. Changes
+     * arrive in order, one at a time.
+     */
+    watchOwnedTable(tableName: string, handler: (event: IDataChangedEvent<unknown>) => unknown): Promise<PackageUnsubscribe>;
     /**
      * Set the value of an in-memory observable this package provides (one declared without a
      * `persistentVar`). The host checks it against the observable's `valueType`, keeps it for

package/dist/define/define-package.d.ts

@@ -140,12 +140,19 @@ export interface IPackageDefinition {
     readonly consumes: readonly IPackageConsumedContract[];
     /** Run when the package's worker starts, in the order they were added. */
     readonly startHooks: readonly PackageStartHook[];
+    /** Run when the package's worker stops, in the order they were added. */
+    readonly stopHooks: readonly PackageStopHook[];
 }
 /**
  * Background work for when the package's worker starts. Its `ctx` belongs to no call: it can use
  * the package's own tables and variables, but calls to other contracts are refused.
  */
 export type PackageStartHook = (ctx: IPackageContext) => unknown;
+/**
+ * Local cleanup for when the package's worker stops: end child processes, close files. It gets
+ * no `ctx`: the worker's calls to Peers are refused by then.
+ */
+export type PackageStopHook = () => unknown;
 /** The builder {@link definePackage} passes its callback. */
 export declare class PackageBuilder {
     /** The package's id, from `newid()`. */
@@ -163,6 +170,7 @@ export declare class PackageBuilder {
     private readonly provided;
     private readonly consumed;
     private readonly starts;
+    private readonly stops;
     /**
      * Run `fn` each time the package's worker starts, after the package's variables load and
      * before its in-memory observables publish, so a value set here is the first one readers
@@ -176,6 +184,19 @@ export declare class PackageBuilder {
      * @param fn - Called with the worker's `ctx`.
      */
     onStart(fn: PackageStartHook): void;
+    /**
+     * Run `fn` when the package's worker stops: when another version replaces this one, when the
+     * package is turned off or removed, and when Peers quits. Use it for local cleanup, such as
+     * ending child processes or closing files. It gets no `ctx`, because the worker's calls to
+     * Peers (its tables, variables, events) are refused once it is stopping.
+     *
+     * The worker gets 5 seconds for its stop hooks, then it is ended. A privileged package's child
+     * processes end with it, unless they detached from it on purpose (a daemon such as a tmux
+     * server); clean those up here. A crash or a forced kill runs no stop hooks.
+     *
+     * @param fn - Called with no arguments; the worker waits for a returned promise.
+     */
+    onStop(fn: PackageStopHook): void;
     /**
      * Provide a contract: this package serves its tools and holds its tables, observables, and
      * events.

package/dist/define/define-package.js

@@ -172,6 +172,7 @@ class PackageBuilder {
     provided = [];
     consumed = [];
     starts = [];
+    stops = [];
     /**
      * Run `fn` each time the package's worker starts, after the package's variables load and
      * before its in-memory observables publish, so a value set here is the first one readers
@@ -190,6 +191,24 @@ class PackageBuilder {
         }
         this.starts.push(fn);
     }
+    /**
+     * Run `fn` when the package's worker stops: when another version replaces this one, when the
+     * package is turned off or removed, and when Peers quits. Use it for local cleanup, such as
+     * ending child processes or closing files. It gets no `ctx`, because the worker's calls to
+     * Peers (its tables, variables, events) are refused once it is stopping.
+     *
+     * The worker gets 5 seconds for its stop hooks, then it is ended. A privileged package's child
+     * processes end with it, unless they detached from it on purpose (a daemon such as a tmux
+     * server); clean those up here. A crash or a forced kill runs no stop hooks.
+     *
+     * @param fn - Called with no arguments; the worker waits for a returned promise.
+     */
+    onStop(fn) {
+        if (typeof fn !== "function") {
+            throw new Error("pkg.onStop takes a function");
+        }
+        this.stops.push(fn);
+    }
     /**
      * Provide a contract: this package serves its tools and holds its tables, observables, and
      * events.
@@ -271,6 +290,7 @@ class PackageBuilder {
             provides: Object.freeze(provides),
             consumes: Object.freeze(this.consumed.map((consumed) => Object.freeze({ ...consumed }))),
             startHooks: Object.freeze([...this.starts]),
+            stopHooks: Object.freeze([...this.stops]),
         });
     }
 }

package/dist/define/index.d.ts

@@ -11,7 +11,8 @@ export { AccessLevel } from "../data/access-level";
 export type { DataFilter, IDataQueryParams } from "../data/orm/data-query";
 export type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
 export { type Observable, observable, type Subscription } from "../observable";
-export { isid, newid } from "../peer-id";
+export type { IPackageSaveOptions } from "../package-loader/isolated-runtime";
+export { idFromKey, isid, newid } from "../peer-id";
 export { FieldType, type IField } from "../types/field-type";
 export { zodPeerId } from "../types/zod-types";
 export * from "./context";

package/dist/define/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writePackageVar = exports.userVar = exports.readPackageVar = exports.groupVar = exports.groupUserVar = exports.groupDeviceVar = exports.deviceVar = exports.isImplementedObservable = exports.defineObservable = exports.declareObservable = exports.generatedField = exports.defineEvent = exports.zodPeerId = exports.FieldType = exports.newid = exports.isid = exports.observable = exports.AccessLevel = exports.z = void 0;
+exports.writePackageVar = exports.userVar = exports.readPackageVar = exports.groupVar = exports.groupUserVar = exports.groupDeviceVar = exports.deviceVar = exports.isImplementedObservable = exports.defineObservable = exports.declareObservable = exports.generatedField = exports.defineEvent = exports.zodPeerId = exports.FieldType = exports.newid = exports.isid = exports.idFromKey = exports.observable = exports.AccessLevel = exports.z = void 0;
 /**
  * `@peers-app/peers-sdk/define`: declare an isolated package.
  *
@@ -30,6 +30,7 @@ Object.defineProperty(exports, "AccessLevel", { enumerable: true, get: function
 var observable_1 = require("../observable");
 Object.defineProperty(exports, "observable", { enumerable: true, get: function () { return observable_1.observable; } });
 var peer_id_1 = require("../peer-id");
+Object.defineProperty(exports, "idFromKey", { enumerable: true, get: function () { return peer_id_1.idFromKey; } });
 Object.defineProperty(exports, "isid", { enumerable: true, get: function () { return peer_id_1.isid; } });
 Object.defineProperty(exports, "newid", { enumerable: true, get: function () { return peer_id_1.newid; } });
 var field_type_1 = require("../types/field-type");

package/dist/define/manifest.js

@@ -116,9 +116,12 @@ function fieldDetails(schema, shape, input, depth, path, event = false, wholeVal
         throw new Error(`Field "${path}" uses .nullable(); an empty field is a missing field in Peers, so use .optional() (a null sent for it is removed)`);
     }
     const details = nullable || (wholeValue && optional) ? { optional: true } : {};
+    // An object with no listed fields (`z.object({}).passthrough()`) is opaque: it gets no
+    // `fields`, as a `generatedField` copy of it has none.
     if (current._def.typeName === "ZodObject" &&
         type === field_type_1.FieldType.object &&
-        depth < isolated_artifact_1.ISOLATED_MAX_FIELD_DEPTH) {
+        depth < isolated_artifact_1.ISOLATED_MAX_FIELD_DEPTH &&
+        Object.keys(current.shape).length > 0) {
         details.fields = event
             ? eventFields(current, depth + 1, path)
             : irFields(current, input, depth + 1, path);
@@ -501,7 +504,7 @@ function observableValueShape(name, schema) {
     return empty ? { ...shape, optional: true } : shape;
 }
 function tableManifest(table) {
-    const { name, description, primaryKeyName, schema, versionNumber, localOnly } = table.definition;
+    const { name, description, primaryKeyName, schema, versionNumber, localOnly, indexes } = table.definition;
     return {
         name,
         description,
@@ -509,6 +512,14 @@ function tableManifest(table) {
         fields: describing(`Table ${name}`, () => irFields(schema)),
         ...(versionNumber === undefined ? {} : { versionNumber }),
         ...(localOnly ? { localOnly: true } : {}),
+        ...(indexes?.length
+            ? {
+                indexes: indexes.map((index) => ({
+                    fields: index.fields.map((f) => typeof f === "string" ? f : { name: f.name, order: f.order }),
+                    ...(index.unique ? { unique: true } : {}),
+                })),
+            }
+            : {}),
     };
 }
 /** One contract's manifest entry, with name-only references to its tables. */

package/dist/define/serve.d.ts

@@ -10,12 +10,19 @@ import type { IPackageDefinition } from "./define-package";
  * @param ctx - The worker's context, bound to no call.
  */
 export declare function startPackage(definition: IPackageDefinition, ctx: IPackageContext): Promise<void>;
+/**
+ * Run a package's `pkg.onStop` hooks in order. A hook that fails is logged, and the rest still
+ * run. `servePackage` runs this when the worker stops; call it yourself only in tests.
+ *
+ * @param definition - The package's default export from `src/package.ts`.
+ */
+export declare function stopPackage(definition: IPackageDefinition): Promise<void>;
 /**
  * Register every provided tool's handler with the Runtime, serve each provided contract's
  * tables, observables, and events from the worker (guest API 3: every consumer call and
- * outgoing message goes through the package), and start the package's variables, events, and
- * observables when the worker starts, before any call. `peers-package build` generates the
- * call; packages don't call this themselves.
+ * outgoing message goes through the package), start the package's variables, events, and
+ * observables when the worker starts, before any call, and run its `pkg.onStop` hooks when the
+ * worker stops. `peers-package build` generates the call; packages don't call this themselves.
  *
  * @param definition - The package's default export from `src/package.ts`.
  */

package/dist/define/serve.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startPackage = startPackage;
+exports.stopPackage = stopPackage;
 exports.servePackage = servePackage;
 const events_1 = require("./events");
 const observables_1 = require("./observables");
@@ -30,12 +31,28 @@ async function startPackage(definition, ctx) {
     }
     await (0, observables_1.servePackageObservables)(definition.provides, ctx);
 }
+/**
+ * Run a package's `pkg.onStop` hooks in order. A hook that fails is logged, and the rest still
+ * run. `servePackage` runs this when the worker stops; call it yourself only in tests.
+ *
+ * @param definition - The package's default export from `src/package.ts`.
+ */
+async function stopPackage(definition) {
+    for (const hook of definition.stopHooks) {
+        try {
+            await hook();
+        }
+        catch (error) {
+            console.error("A pkg.onStop hook failed", error);
+        }
+    }
+}
 /**
  * Register every provided tool's handler with the Runtime, serve each provided contract's
  * tables, observables, and events from the worker (guest API 3: every consumer call and
- * outgoing message goes through the package), and start the package's variables, events, and
- * observables when the worker starts, before any call. `peers-package build` generates the
- * call; packages don't call this themselves.
+ * outgoing message goes through the package), start the package's variables, events, and
+ * observables when the worker starts, before any call, and run its `pkg.onStop` hooks when the
+ * worker stops. `peers-package build` generates the call; packages don't call this themselves.
  *
  * @param definition - The package's default export from `src/package.ts`.
  */
@@ -43,12 +60,19 @@ function servePackage(definition) {
     const worker = globalThis;
     const register = worker.registerContractTool;
     const registerHandler = worker.registerHandler;
+    const onWorkerStop = worker.onWorkerStop;
+    const stops = definition.stopHooks.length > 0;
     if (typeof register !== "function" ||
         typeof registerHandler !== "function" ||
-        typeof worker.onWorkerStart !== "function") {
+        typeof worker.onWorkerStart !== "function" ||
+        // Only a package with stop hooks needs the worker's stop.
+        (stops && typeof onWorkerStop !== "function")) {
         throw new Error("servePackage runs inside an isolated package worker");
     }
     worker.onWorkerStart((ctx) => startPackage(definition, ctx));
+    if (stops) {
+        onWorkerStop?.(() => stopPackage(definition));
+    }
     for (const contract of definition.provides) {
         for (const tool of contract.tools) {
             register(contract.contractId, contract.version, tool.definition.name, (args, ctx) => (0, tool_1.runPackageTool)(tool, args, ctx));

package/dist/define/table-handle.d.ts

@@ -1,12 +1,21 @@
-import type { IsolatedContractTableOperation } from "../package-loader/isolated-runtime";
+import { type IsolatedContractTableOperation } from "../package-loader/isolated-runtime";
 import type { IPackageTableHandle } from "./table";
+/**
+ * A table call's arguments as the bridge carries them. In a filter, a field set to `undefined`
+ * matches an empty field, as `null` does, so it's sent as `null`; anywhere else (options, a
+ * record) it's left out.
+ *
+ * @param operation - The table operation.
+ * @param args - Its arguments, as the caller passed them.
+ */
+export declare function bridgeTableArgs(operation: IsolatedContractTableOperation, args: unknown[]): unknown[];
 /** Sends one table operation with its arguments and resolves with the host's reply. */
 export type PackageTableCall = (operation: IsolatedContractTableOperation, args: unknown[]) => Promise<unknown>;
 /**
  * A consumer's table methods over one way of calling the host: a consumed contract's
  * (`News(ctx).tables.Feeds`) or a UI client's (`hostContract`). Replies are normalized the same
- * way for both: a missing row is `undefined`, a list is an array. Saved records are copied for
- * the bridge (undefined fields omitted); the providing package's table parses a `save`.
+ * way for both: a missing row is `undefined`, a list is an array. Arguments are copied for the
+ * bridge ({@link bridgeTableArgs}); the providing package's table parses a `save`.
  *
  * @param call - Sends an operation to the table.
  */

package/dist/define/table-handle.js

@@ -1,36 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeTableArgs = bridgeTableArgs;
 exports.packageTableMethods = packageTableMethods;
+const isolated_runtime_1 = require("../package-loader/isolated-runtime");
 const wire_value_1 = require("./wire-value");
+/** Operations whose first argument is a filter. */
+const FILTER_OPERATIONS = new Set(["list", "count", "findOne"]);
+/**
+ * A table call's arguments as the bridge carries them. In a filter, a field set to `undefined`
+ * matches an empty field, as `null` does, so it's sent as `null`; anywhere else (options, a
+ * record) it's left out.
+ *
+ * @param operation - The table operation.
+ * @param args - Its arguments, as the caller passed them.
+ */
+function bridgeTableArgs(operation, args) {
+    return args.map((arg, index) => (0, wire_value_1.snapshotPackageValue)(arg, {
+        undefinedFieldsAsNull: index === 0 && FILTER_OPERATIONS.has(operation),
+    }));
+}
 /**
  * A consumer's table methods over one way of calling the host: a consumed contract's
  * (`News(ctx).tables.Feeds`) or a UI client's (`hostContract`). Replies are normalized the same
- * way for both: a missing row is `undefined`, a list is an array. Saved records are copied for
- * the bridge (undefined fields omitted); the providing package's table parses a `save`.
+ * way for both: a missing row is `undefined`, a list is an array. Arguments are copied for the
+ * bridge ({@link bridgeTableArgs}); the providing package's table parses a `save`.
  *
  * @param call - Sends an operation to the table.
  */
 function packageTableMethods(call) {
+    const send = (operation, args) => call(operation, bridgeTableArgs(operation, args));
     return {
         async get(recordId) {
-            return ((await call("get", [recordId])) ?? undefined);
+            return ((await send("get", [recordId])) ?? undefined);
         },
         async list(filter = {}, options = {}) {
-            const rows = await call("list", [filter, options]);
+            const rows = await send("list", [filter, options]);
             return (Array.isArray(rows) ? rows : []);
         },
         async count(filter = {}) {
-            return Number(await call("count", [filter]));
+            return Number(await send("count", [filter]));
         },
         async findOne(filter = {}) {
-            return ((await call("findOne", [filter])) ?? undefined);
+            return ((await send("findOne", [filter])) ?? undefined);
         },
-        async save(record) {
-            // A field left undefined is omitted (stored unset); the bridge carries no undefined.
-            return (await call("save", [(0, wire_value_1.snapshotPackageValue)(record)]));
+        async save(record, options) {
+            const allowed = (0, isolated_runtime_1.isolatedSaveOptions)(options);
+            return (await send("save", allowed ? [record, allowed] : [record]));
         },
         async delete(recordId) {
-            await call("delete", [recordId]);
+            await send("delete", [recordId]);
         },
     };
 }