@peers-app/peers-sdk 0.28.1 → 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/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,6 +11,7 @@ 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 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";

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);

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]);
         },
     };
 }

package/dist/define/table.d.ts

@@ -1,7 +1,8 @@
 import type { z } from "zod";
 import type { DataFilter, IDataQueryParams } from "../data/orm/data-query";
 import type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
-import type { IPackageContext } from "./context";
+import { type IPackageSaveOptions } from "../package-loader/isolated-runtime";
+import type { IPackageContext, PackageUnsubscribe } from "./context";
 /** What {@link defineTable} takes. */
 export interface IPackageTableDefinition<S extends z.AnyZodObject = z.AnyZodObject> {
     /** Table name, unique in the package. Other packages reach it only through a contract. */
@@ -53,8 +54,10 @@ export interface IPackageTableHandle<T extends Record<string, any>, TInput = T>
     /**
      * Insert or replace a row. It reaches the providing package's table, which parses it with the
      * schema first (so defaults and transforms apply), through any override its class makes.
+     * Pass `{ restoreIfDeleted: true }` to save a row whose id was deleted before; without it,
+     * that save is refused.
      */
-    save(record: TInput): Promise<T>;
+    save(record: TInput, options?: IPackageSaveOptions): Promise<T>;
     /** Delete a row by id. */
     delete(recordId: string): Promise<void>;
 }
@@ -103,10 +106,29 @@ export declare class PackageTable<S extends z.AnyZodObject = z.AnyZodObject> imp
      * Insert or replace a row, parsed with the schema first so defaults and transforms apply. An
      * optional field that is `null` or `undefined` is left out, so it's stored unset; a field with
      * a default gets the default. Resolves to the row as stored.
+     *
+     * @param record - The row.
+     * @param options - `{ restoreIfDeleted: true }` saves a row whose id was deleted before;
+     *   without it, that save is refused. An override that calls `super.save` passes it on.
      */
-    save(record: z.input<S>): Promise<z.infer<S>>;
+    save(record: z.input<S>, options?: IPackageSaveOptions): Promise<z.infer<S>>;
     /** Delete a row by id. */
     delete(recordId: string): Promise<void>;
+    /**
+     * Call `handler` with each change to this table: inserts, updates, and deletes, made by this
+     * package, by a consumer, or synced from another device. Changes arrive in order, one at a
+     * time; the package's own writes from `handler` arrive too. A handler gets a tool call's
+     * deadline; past it, later changes stop waiting for it. Subscribe in `pkg.onStart`: it lasts
+     * until the returned function is called or the worker stops, and nothing is replayed from
+     * while the worker was stopped, so subscribe first, then read what's already there.
+     *
+     * Only the package itself can subscribe this way; consumers subscribe to `dataChanged`
+     * through a contract.
+     *
+     * @param handler - Gets each change, with the row as `list` returns it.
+     * @returns Stops the subscription.
+     */
+    subscribe(handler: (event: IDataChangedEvent<z.infer<S>>) => unknown): Promise<PackageUnsubscribe>;
     /**
      * One change on its way to one subscriber of the table's `dataChanged`, with `this.ctx`
      * carrying that subscriber. Return it to send it, a changed copy to send that instead, or

package/dist/define/table.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageTable = void 0;
 exports.defineTable = defineTable;
+const isolated_runtime_1 = require("../package-loader/isolated-runtime");
 const empty_fields_1 = require("./empty-fields");
-const wire_value_1 = require("./wire-value");
+const table_handle_1 = require("./table-handle");
 /**
  * One of the package's tables, for one call: what `Feeds(ctx)` returns, and what answers a
  * consumer's call through a contract (from a UI or another package). It runs in the provider's
@@ -40,7 +41,7 @@ class PackageTable {
     }
     /** Send one operation to storage and clean rows before provider code receives them. */
     async store(operation, args) {
-        const result = await this.ctx.callOwnedTable(this.definition.name, operation, args);
+        const result = await this.ctx.callOwnedTable(this.definition.name, operation, (0, table_handle_1.bridgeTableArgs)(operation, args));
         const { schema } = this.definition;
         if (operation === "list" && Array.isArray(result)) {
             return result.map((row) => (0, empty_fields_1.withoutEmptySchemaFields)(schema, row));
@@ -71,16 +72,42 @@ class PackageTable {
      * Insert or replace a row, parsed with the schema first so defaults and transforms apply. An
      * optional field that is `null` or `undefined` is left out, so it's stored unset; a field with
      * a default gets the default. Resolves to the row as stored.
+     *
+     * @param record - The row.
+     * @param options - `{ restoreIfDeleted: true }` saves a row whose id was deleted before;
+     *   without it, that save is refused. An override that calls `super.save` passes it on.
      */
-    async save(record) {
+    async save(record, options) {
         const { schema } = this.definition;
-        const row = (0, wire_value_1.snapshotPackageValue)(schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, record)));
-        return (await this.store("save", [row]));
+        const row = schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, record));
+        const allowed = (0, isolated_runtime_1.isolatedSaveOptions)(options);
+        return (await this.store("save", allowed ? [row, allowed] : [row]));
     }
     /** Delete a row by id. */
     async delete(recordId) {
         await this.store("delete", [recordId]);
     }
+    /**
+     * Call `handler` with each change to this table: inserts, updates, and deletes, made by this
+     * package, by a consumer, or synced from another device. Changes arrive in order, one at a
+     * time; the package's own writes from `handler` arrive too. A handler gets a tool call's
+     * deadline; past it, later changes stop waiting for it. Subscribe in `pkg.onStart`: it lasts
+     * until the returned function is called or the worker stops, and nothing is replayed from
+     * while the worker was stopped, so subscribe first, then read what's already there.
+     *
+     * Only the package itself can subscribe this way; consumers subscribe to `dataChanged`
+     * through a contract.
+     *
+     * @param handler - Gets each change, with the row as `list` returns it.
+     * @returns Stops the subscription.
+     */
+    async subscribe(handler) {
+        const { name, schema } = this.definition;
+        return this.ctx.watchOwnedTable(name, (event) => handler({
+            ...event,
+            dataObject: (0, empty_fields_1.withoutEmptySchemaFields)(schema, event.dataObject),
+        }));
+    }
     /**
      * One change on its way to one subscriber of the table's `dataChanged`, with `this.ctx`
      * carrying that subscriber. Return it to send it, a changed copy to send that instead, or

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

@@ -8,5 +8,10 @@
  * environments (jsdom) lack.
  *
  * @param value - The value to send: arguments, a result, a row, an event, or an observable value.
+ * @param options - `undefinedFieldsAsNull` sends a missing field as `null` instead of leaving it
+ *   out, for a table filter: there `{ tag: undefined }` matches an empty field, as `null` does,
+ *   and leaving it out would match every row.
  */
-export declare function snapshotPackageValue(value: unknown): unknown;
+export declare function snapshotPackageValue(value: unknown, options?: {
+    undefinedFieldsAsNull?: boolean;
+}): unknown;

package/dist/define/wire-value.js

@@ -11,8 +11,11 @@ exports.snapshotPackageValue = snapshotPackageValue;
  * environments (jsdom) lack.
  *
  * @param value - The value to send: arguments, a result, a row, an event, or an observable value.
+ * @param options - `undefinedFieldsAsNull` sends a missing field as `null` instead of leaving it
+ *   out, for a table filter: there `{ tag: undefined }` matches an empty field, as `null` does,
+ *   and leaving it out would match every row.
  */
-function snapshotPackageValue(value) {
+function snapshotPackageValue(value, options = {}) {
     const ancestors = new Set();
     const copy = (current, path) => {
         if (current === null || typeof current === "string" || typeof current === "boolean") {
@@ -56,10 +59,10 @@ function snapshotPackageValue(value) {
             }
             const record = {};
             for (const [key, field] of Object.entries(current)) {
-                if (field !== undefined) {
+                if (field !== undefined || options.undefinedFieldsAsNull) {
                     // Define rather than assign, so a "__proto__" key stays a field.
                     Object.defineProperty(record, key, {
-                        value: copy(field, `${path}.${key}`),
+                        value: field === undefined ? null : copy(field, `${path}.${key}`),
                         enumerable: true,
                         writable: true,
                         configurable: true,

package/dist/logging/console-logger.d.ts

@@ -27,9 +27,18 @@ export declare function extractCoreMessage(message: string): string;
  */
 export declare class Logger {
     private source;
+    private process;
     private pendingLogs;
     private waitingForConsoleLogsTable;
-    constructor(source?: string);
+    /**
+     * @param source - What the lines are about, such as a module or package name. Defaults to the
+     *   caller's file.
+     * @param options - `process` records the lines under another process's name (such as
+     *   `"worker"` for a package worker's output) instead of this one's.
+     */
+    constructor(source?: string, options?: {
+        process?: string;
+    });
     /**
      * Log a debug message
      */

package/dist/logging/console-logger.js

@@ -199,9 +199,11 @@ function extractSource(stackTrace) {
     return undefined;
 }
 /**
- * Write a log entry to the ConsoleLogs table with a specific source
+ * Write a log entry to the ConsoleLogs table with a specific source. `processName` names another
+ * process the line came from (such as a package worker); its stack is not this one's, so an
+ * error gets none.
  */
-async function writeLogToDatabaseWithSource(level, source, args) {
+async function writeLogToDatabaseWithSource(level, source, args, processName) {
     try {
         const timestamp = (0, utils_1.getTimestamp)();
         // Format message from arguments
@@ -223,12 +225,12 @@ async function writeLogToDatabaseWithSource(level, source, args) {
         }
         const context = args.length === 0 ? undefined : args.length === 1 ? args[0] : args;
         // Get stack trace for errors
-        const stackTrace = level === "error" ? getStackTrace() : undefined;
+        const stackTrace = level === "error" && !processName ? getStackTrace() : undefined;
         const logRecord = {
             logId: (0, utils_1.newid)(),
             timestamp,
             level,
-            process: currentProcessName,
+            process: processName ?? currentProcessName,
             processInstanceId: currentProcessInstanceId,
             source,
             message,
@@ -254,15 +256,23 @@ async function writeLogToDatabaseWithSource(level, source, args) {
  */
 class Logger {
     source;
+    process;
     pendingLogs = [];
     waitingForConsoleLogsTable = true;
-    constructor(source) {
+    /**
+     * @param source - What the lines are about, such as a module or package name. Defaults to the
+     *   caller's file.
+     * @param options - `process` records the lines under another process's name (such as
+     *   `"worker"` for a package worker's output) instead of this one's.
+     */
+    constructor(source, options = {}) {
         // If no source provided, try to extract from caller's location
         if (!source) {
             const stack = new Error().stack;
             source = extractSource(stack) || "unknown";
         }
         this.source = source;
+        this.process = options.process;
         (0, console_logs_table_1.ConsoleLogs)().then(() => {
             this.waitingForConsoleLogsTable = false;
             this.flushPendingLogs();
@@ -321,7 +331,7 @@ class Logger {
             return;
         }
         // System is initialized, write directly
-        writeLogToDatabaseWithSource(level, this.source, args).catch((err) => {
+        writeLogToDatabaseWithSource(level, this.source, args, this.process).catch((err) => {
             originalConsole.error("[console-logger] Failed to write log:", err);
         });
     }
@@ -330,7 +340,7 @@ class Logger {
         this.pendingLogs.length = 0;
         for (const { level, args } of _pendingLogs) {
             await (0, utils_1.sleep)(10); // small delay to avoid stampede
-            await writeLogToDatabaseWithSource(level, this.source, args).catch((err) => {
+            await writeLogToDatabaseWithSource(level, this.source, args, this.process).catch((err) => {
                 originalConsole.error("[console-logger] Failed to flush pending log:", err);
             });
         }

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

@@ -10,6 +10,28 @@ import type { IPackageWorkerHealth } from "./package-runtime-state";
 export declare const ISOLATED_CONTRACT_TABLE_OPERATIONS: readonly ["get", "list", "count", "findOne", "save", "insert", "update", "delete"];
 /** Consumer-callable operation on an isolated contract table. */
 export type IsolatedContractTableOperation = (typeof ISOLATED_CONTRACT_TABLE_OPERATIONS)[number];
+/** Options a package may pass with a table `save`. */
+export interface IPackageSaveOptions {
+    /** Save a row whose id was deleted before. Without it, that save is refused. */
+    restoreIfDeleted?: boolean;
+}
+/**
+ * The save options a package may use, from whatever a caller passed: only `restoreIfDeleted`.
+ * The host's other save options (snapshots, weak inserts) stay out of package hands.
+ *
+ * @param options - A table `save`'s second argument, as received.
+ * @returns The allowed options, or `undefined` when none are set.
+ */
+export declare function isolatedSaveOptions(options: unknown): IPackageSaveOptions | undefined;
+/** One line a package worker wrote to its stdout or stderr. */
+export interface IIsolatedWorkerOutput {
+    /** The worker's package. */
+    packageId: string;
+    /** Which stream the line came from. */
+    stream: "stdout" | "stderr";
+    /** The line, without its newline. */
+    line: string;
+}
 /**
  * Trusted caller identity for an isolated tool call. Never read from guest
  * payloads — the host derives this from `DataContext` / workflow state.
@@ -303,6 +325,10 @@ export interface IIsolatedPackageRuntimeFactoryOptions {
     persistentVarGateway?: IIsolatedPackagePersistentVarGateway;
     /** Gateway for consumed calls to selected host/system providers. */
     providerGateway?: IIsolatedContractProviderGateway;
+    /** Receives each line package workers write; without it, lines go to this process's output. */
+    onWorkerOutput?: (output: IIsolatedWorkerOutput) => void;
+    /** This device's id, which package code reads as `ctx.deviceId`. */
+    getDeviceId?: () => string | undefined;
 }
 /**
  * Host callback that builds an {@link IIsolatedPackageRuntime} for one

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ISOLATED_CONTRACT_TABLE_EVENTS = exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = void 0;
+exports.isolatedSaveOptions = isolatedSaveOptions;
 exports.setIsolatedPackageRuntimeFactory = setIsolatedPackageRuntimeFactory;
 exports.getIsolatedPackageRuntimeFactory = getIsolatedPackageRuntimeFactory;
 /** Standard table methods exposed through isolated contract-table references. */
@@ -14,6 +15,18 @@ exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = [
     "update",
     "delete",
 ];
+/**
+ * The save options a package may use, from whatever a caller passed: only `restoreIfDeleted`.
+ * The host's other save options (snapshots, weak inserts) stay out of package hands.
+ *
+ * @param options - A table `save`'s second argument, as received.
+ * @returns The allowed options, or `undefined` when none are set.
+ */
+function isolatedSaveOptions(options) {
+    return options?.restoreIfDeleted === true
+        ? { restoreIfDeleted: true }
+        : undefined;
+}
 /** Table events consumers may subscribe to on an isolated contract table. */
 exports.ISOLATED_CONTRACT_TABLE_EVENTS = ["dataChanged"];
 let isolatedRuntimeFactory;

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

@@ -48,6 +48,10 @@ export declare class PackageLoader {
     private contractInstalledPackages;
     /** Packages installed through the isolated runtime (no host eval). */
     private isolatedPackageIds;
+    /** Each isolated package's name, for its worker's log lines. */
+    private isolatedPackageNames;
+    /** One logger per package whose worker wrote output, writing as process `worker`. */
+    private workerLoggers;
     /** Per-package counter bumped on every runtime-state change; lets slow unloads yield. */
     private runtimeStateSequences;
     /** Hash of the bundle each loaded package was built from, for `onlyIfChanged` loads. */
@@ -189,6 +193,11 @@ export declare class PackageLoader {
      * Dispose the isolated runtime for this data context.
      */
     dispose(): Promise<void>;
+    /**
+     * Record one line a package worker wrote, under process `worker` with the package's name as
+     * its source. It still reaches this process's output too.
+     */
+    private logWorkerOutput;
     private retireHostEndpoints;
     /**
      * Resolve and load every non-disabled package in this data context.

package/dist/package-loader/package-loader.js

@@ -16,6 +16,7 @@ const package_version_resolver_1 = require("../data/package-version-resolver");
 const package_versions_1 = require("../data/package-versions");
 const packages_1 = require("../data/packages");
 const keys_1 = require("../keys");
+const console_logger_1 = require("../logging/console-logger");
 const observable_1 = require("../observable");
 const contract_package_loader_1 = require("./contract-package-loader");
 const isolated_artifact_1 = require("./isolated-artifact");
@@ -63,6 +64,10 @@ class PackageLoader {
     contractInstalledPackages = new Set();
     /** Packages installed through the isolated runtime (no host eval). */
     isolatedPackageIds = new Set();
+    /** Each isolated package's name, for its worker's log lines. */
+    isolatedPackageNames = new Map();
+    /** One logger per package whose worker wrote output, writing as process `worker`. */
+    workerLoggers = new Map();
     /** Per-package counter bumped on every runtime-state change; lets slow unloads yield. */
     runtimeStateSequences = new Map();
     /** Hash of the bundle each loaded package was built from, for `onlyIfChanged` loads. */
@@ -120,6 +125,8 @@ class PackageLoader {
                         resolverOnly: true,
                     }),
                 },
+                onWorkerOutput: (output) => this.logWorkerOutput(output),
+                getDeviceId: () => this.dataContext.userContext?.deviceId(),
             });
             this.unsubscribePackageHealth = this.isolatedRuntime.subscribePackageHealth?.((packageId) => {
                 const previous = this.runtimeStates()[packageId];
@@ -623,9 +630,28 @@ class PackageLoader {
         this.contractInstalledPackages.clear();
         this.packageInstances = {};
         this.loadedBundleHashes.clear();
+        this.workerLoggers.clear();
+        this.isolatedPackageNames.clear();
         this.runtimeStateSequences.clear();
         this.runtimeStates({});
     }
+    /**
+     * Record one line a package worker wrote, under process `worker` with the package's name as
+     * its source. It still reaches this process's output too.
+     */
+    logWorkerOutput({ packageId, stream, line }) {
+        let logger = this.workerLoggers.get(packageId);
+        if (!logger) {
+            logger = new console_logger_1.Logger(this.isolatedPackageNames.get(packageId) ?? packageId, {
+                process: "worker",
+            });
+            this.workerLoggers.set(packageId, logger);
+        }
+        if (stream === "stderr")
+            logger.error(line);
+        else
+            logger.log(line);
+    }
     retireHostEndpoints(packageId) {
         this.hostActivationGenerations.set(packageId, (this.hostActivationGenerations.get(packageId) ?? 0) + 1);
         for (const router of this.consumedContractRouters)
@@ -935,6 +961,10 @@ class PackageLoader {
             return undefined;
         }
         assertCurrent();
+        if (this.isolatedPackageNames.get(pkg.packageId) !== pkg.name) {
+            this.workerLoggers.delete(pkg.packageId);
+        }
+        this.isolatedPackageNames.set(pkg.packageId, pkg.name);
         const installOptions = { ...isolatedContractLifecycle(selectedPackageVersion), assertCurrent };
         let installed;
         if (this.isolatedRuntime.isInstalled(pkg.packageId)) {

package/dist/testing/mock-host-contract.js

@@ -237,6 +237,8 @@ function mockProviderContext(contractId, tables) {
         get(_target, property) {
             if (property === "callOwnedTable")
                 return callOwnedTable;
+            if (property === "deviceId")
+                return "mock-host-device";
             if (typeof property !== "string" || property === "then")
                 return undefined;
             return () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"