@peers-app/peers-sdk 0.28.1 → 0.28.3

package/dist/context/user-context-singleton.js

@@ -9,6 +9,7 @@ exports.getTableContainer = getTableContainer;
 exports.setDefaultClientUserContext = setDefaultClientUserContext;
 exports.getAllTables = getAllTables;
 const client_proxy_data_source_1 = require("../data/orm/client-proxy.data-source");
+const decorators_1 = require("../data/orm/decorators");
 const rpc_types_1 = require("../rpc-types");
 const utils_1 = require("../utils");
 const user_context_1 = require("./user-context");
@@ -170,6 +171,7 @@ if (!rpc_types_1.isClient) {
         if (typeof method !== "function") {
             throw new Error(`Method ${methodName} not found on table ${tableName}`);
         }
+        (0, decorators_1.checkRemoteTableSaveOptions)(methodName, args);
         // @ts-expect-error - call this way to ensure 'this' is correct
         return table[methodName](...args);
     };

package/dist/contracts/contract-proxy.js

@@ -584,6 +584,7 @@ function createContractProvider(resolution, opts = {}) {
                     !(0, decorators_1.isContractRemoteTableMethod)(method)) {
                     throw new Error(`Table method '${call.name}.${call.operation}' is not remotely callable`);
                 }
+                (0, decorators_1.checkRemoteTableSaveOptions)(call.operation, call.args);
                 return impl.apply(table, call.args);
             }
             case "tool": {

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/group-members.js

@@ -131,9 +131,10 @@ let GroupMembersTable = (() => {
                 ...(await (0, write_checks_1.signingStamp)(this, groupMember, current)),
             });
             return this.save(groupMember, {
-                saveAsSnapshot: true,
                 restoreIfDeleted: true,
                 ...(opts || {}),
+                saveAsSnapshot: true,
+                writtenAt: groupMember.signedAt,
             });
         }
         async delete(groupMemberId) {

package/dist/data/group-resign.js

@@ -39,7 +39,10 @@ async function resignGroupAuthority(dataContext, opts = {}) {
             try {
                 if (opts.secretKey) {
                     const stamp = await (0, write_checks_1.signingStamp)(table, row, row);
-                    await table.save((0, keys_1.addSignatureToObject)({ ...row, ...stamp }, opts.secretKey), snapshot);
+                    await table.save((0, keys_1.addSignatureToObject)({ ...row, ...stamp }, opts.secretKey), {
+                        ...snapshot,
+                        writtenAt: stamp.signedAt,
+                    });
                 }
                 else {
                     await table.signAndSave(prepare(row), snapshot);

package/dist/data/groups.js

@@ -116,7 +116,8 @@ let GroupsTable = (() => {
                 ...group,
                 ...(await (0, write_checks_1.signingStamp)(this, group)),
             });
-            return this.save(group, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(group, { ...opts, saveAsSnapshot: true, writtenAt: group.signedAt });
         }
         /**
          * Re-sign this group's authority rows (group row, memberships, packages, package versions)

package/dist/data/orm/client-proxy.data-source.d.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource, type ISaveOptions } from "./data-query";
 import { type ITableMetaData } from "./types";
+/** A renderer's table data source, forwarding operations to the host over RPC. */
 export declare class ClientProxyDataSource<T extends {
     [key: string]: any;
 }> implements IDataSource<T> {

package/dist/data/orm/client-proxy.data-source.js

@@ -4,7 +4,9 @@ exports.ClientProxyDataSource = void 0;
 const rpc_types_1 = require("../../rpc-types");
 const utils_1 = require("../../utils");
 const data_query_1 = require("./data-query");
+const decorators_1 = require("./decorators");
 const types_1 = require("./types");
+/** A renderer's table data source, forwarding operations to the host over RPC. */
 class ClientProxyDataSource {
     metaData;
     schema;
@@ -38,6 +40,7 @@ class ClientProxyDataSource {
         return rpc_types_1.rpcServerCalls.tableMethodCall(this.dataContextId, this.tableName, "findOne", filter, opts);
     }
     async save(record, opts) {
+        (0, decorators_1.checkRemoteTableSaveOptions)("save", [record, opts]);
         return rpc_types_1.rpcServerCalls.tableMethodCall(this.dataContextId, this.tableName, "save", record, opts);
     }
     async insert(record) {

package/dist/data/orm/data-query.d.ts

@@ -1,9 +1,13 @@
+/** Options controlling how a host table save is recorded. */
 export interface ISaveOptions {
     restoreIfDeleted?: boolean;
+    /** @internal Host-only change time for signed rows; must match their signedAt. */
+    writtenAt?: number;
     saveAsSnapshot?: boolean;
     weakInsert?: boolean;
     insertOnly?: boolean;
 }
+/** Persistence operations for one table. */
 export interface IDataSource<T extends {
     [key: string]: any;
 }> {
@@ -18,6 +22,7 @@ export interface IDataSource<T extends {
     update: (record: T) => Promise<T>;
     delete: (data: string | T) => Promise<void>;
 }
+/** Table operations needed to execute a data query. */
 export interface ITable<T extends Record<string, any>> {
     tableName: string;
     metaData: {
@@ -34,6 +39,7 @@ export interface ITable<T extends Record<string, any>> {
         textSearch?: string;
     }) => Promise<T[]>;
 }
+/** Filtering, ordering and pagination for table reads. */
 export interface IDataQueryParams<T extends Record<string, any>> {
     page?: number;
     pageSize?: number;
@@ -43,6 +49,7 @@ export interface IDataQueryParams<T extends Record<string, any>> {
     textSearchExact?: boolean;
     skipPast?: T;
 }
+/** A table query that can be listed or consumed through a cursor. */
 export declare class DataQuery<T extends Record<string, any>> {
     readonly table: ITable<T>;
     constructor(table: ITable<T>, { page, pageSize, sortBy, filter, textSearch, textSearchExact }?: IDataQueryParams<T>);
@@ -55,18 +62,23 @@ export declare class DataQuery<T extends Record<string, any>> {
     cursor(): ICursorIterable<T>;
     list(): Promise<T[]>;
 }
+/** A cursor positioned at a row, with optional seek support. */
 export interface ICursor<T> {
     value: T | null;
     next: (skipPast?: T) => Promise<T | null>;
 }
+/** A cursor that also supports asynchronous iteration. */
 export type ICursorIterable<T> = ICursor<T> & AsyncIterable<T>;
+/** Adds asynchronous iteration to a cursor. */
 export declare function iterableCursor<T>(cursor: ICursor<T>): ICursorIterable<T>;
+/** Reads a data source in pages through an asynchronous cursor. */
 export declare function dataSourceCursor<T extends {
     [key: string]: any;
 }>(dataSource: {
     list: (filter?: DataFilter<T>, opts?: IDataQueryParams<T>) => Promise<T[]>;
     primaryKeyName: string;
 }, filter?: DataFilter<T>, opts?: IDataQueryParams<T>): ICursorIterable<T>;
+/** Counts matching rows, falling back to a cursor when native count is unavailable. */
 export declare function dataSourceCount<T extends {
     [key: string]: any;
 }>(dataSource: {
@@ -74,11 +86,15 @@ export declare function dataSourceCount<T extends {
     list: (filter?: DataFilter<T>, opts?: IDataQueryParams<T>) => Promise<T[]>;
     primaryKeyName: string;
 }, filter?: DataFilter<T>): Promise<number>;
+/** Ordered fields; a leading minus selects descending order. */
 export type SortBy<T extends {
     [key: string]: any;
 }> = (keyof T extends string | number ? keyof T | `-${keyof T}` : never)[];
+/** Scalar values accepted by data filters. */
 export type DataFieldScalar = boolean | number | string | Date | null;
+/** Comparison operators accepted in a field filter. */
 export type DataFilterValueOperator = "$eq" | "$ne" | "$gt" | "$gte" | "$lt" | "$lte" | "$exists" | "$matchWords" | "$substr" | "$expr" | "$in";
+/** A field value or comparison used in a data filter. */
 export type DataFilterValue = DataFieldScalar | DataFieldScalar[] | {
     [key in Exclude<DataFilterValueOperator, "$in">]?: DataFieldScalar;
 } | {
@@ -86,13 +102,17 @@ export type DataFilterValue = DataFieldScalar | DataFieldScalar[] | {
 } | {
     $in: DataFieldScalar[];
 };
+/** Field predicates combined with AND. */
 export type DataFilterAnd<T> = {
     [key in keyof T]?: DataFilterValue;
 };
+/** Alternative groups of field predicates combined with OR. */
 export type DataFilterOr<T> = DataFilterAnd<T>[] | {
     $or: DataFilterAnd<T>[];
 };
+/** A table filter composed of field predicates and logical groups. */
 export type DataFilter<T> = DataFilterAnd<T> | DataFilterOr<T> | {
     $and: DataFilter<T>[];
 };
+/** Adds predicates to resume an ordered query after the supplied row. */
 export declare function filterToSkipPastValue(filter: DataFilter<unknown>, sortBy: string[], skipPast: any): DataFilter<unknown>;

package/dist/data/orm/data-query.js

@@ -5,6 +5,7 @@ exports.iterableCursor = iterableCursor;
 exports.dataSourceCursor = dataSourceCursor;
 exports.dataSourceCount = dataSourceCount;
 exports.filterToSkipPastValue = filterToSkipPastValue;
+/** A table query that can be listed or consumed through a cursor. */
 class DataQuery {
     table;
     constructor(table, { page, pageSize, sortBy, filter, textSearch, textSearchExact } = {}) {
@@ -85,6 +86,7 @@ class DataQuery {
     }
 }
 exports.DataQuery = DataQuery;
+/** Adds asynchronous iteration to a cursor. */
 function iterableCursor(cursor) {
     // @ts-expect-error - we're explicitly extending the cursor object to have this symbol
     cursor[Symbol.asyncIterator] = () => {
@@ -97,6 +99,7 @@ function iterableCursor(cursor) {
     };
     return cursor;
 }
+/** Reads a data source in pages through an asynchronous cursor. */
 function dataSourceCursor(dataSource, filter = {}, opts = {}) {
     // if (dataSource.cursor) {
     //   return dataSource.cursor(filter, opts);
@@ -157,6 +160,7 @@ function dataSourceCursor(dataSource, filter = {}, opts = {}) {
     };
     return iterableCursor(cursor);
 }
+/** Counts matching rows, falling back to a cursor when native count is unavailable. */
 async function dataSourceCount(dataSource, filter = {}) {
     if (dataSource.count) {
         return dataSource.count(filter);
@@ -169,6 +173,7 @@ async function dataSourceCount(dataSource, filter = {}) {
     }
     return count;
 }
+/** Adds predicates to resume an ordered query after the supplied row. */
 function filterToSkipPastValue(filter, sortBy, skipPast) {
     const sortByFilters = [];
     for (let i = 0; i < sortBy.length; i++) {

package/dist/data/orm/decorators.d.ts

@@ -1,3 +1,5 @@
+/** Refuse host-only signed write times supplied through a table RPC or contract call. */
+export declare function checkRemoteTableSaveOptions(methodName: string, args: readonly unknown[]): void;
 /**
  * Return whether a table method was explicitly marked for remote invocation by
  * {@link ProxyClientTableMethodCalls}. Client proxies are recognized through their

package/dist/data/orm/decorators.js

@@ -1,9 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRemoteTableSaveOptions = checkRemoteTableSaveOptions;
 exports.isContractRemoteTableMethod = isContractRemoteTableMethod;
 exports.ProxyClientTableMethodCalls = ProxyClientTableMethodCalls;
 const rpc_types_1 = require("../../rpc-types");
 const contractRemoteTableMethod = Symbol("contractRemoteTableMethod");
+/** Refuse host-only signed write times supplied through a table RPC or contract call. */
+function checkRemoteTableSaveOptions(methodName, args) {
+    if (!["save", "insert", "update", "signAndSave"].includes(methodName))
+        return;
+    const options = args[1];
+    if (options && typeof options === "object" && "writtenAt" in options) {
+        throw new Error("writtenAt is host-only; use signAndSave to sign a new change");
+    }
+}
 function markContractRemoteTableMethod(method) {
     Object.defineProperty(method, contractRemoteTableMethod, { value: true });
 }
@@ -37,6 +47,7 @@ function ProxyClientTableMethodCalls() {
             const methodName = context.name;
             // WARNING: Using typescript's magical `this` param
             const proxyFn = function (...args) {
+                checkRemoteTableSaveOptions(methodName, args);
                 const dataContextId = this.dataSource.dataContextId || this.groupId || "";
                 return rpc_types_1.rpcServerCalls.tableMethodCall(dataContextId, this.tableName, methodName, ...args);
             };

package/dist/data/orm/write-checks.d.ts

@@ -57,10 +57,12 @@ export declare function checkLocalSave<T extends {
  */
 export declare const packageApprovalTables: ReadonlySet<string>;
 /**
- * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, now or
- * just after the row on record when that was signed by a clock running ahead, so the new
- * signature counts as the later one (and, for a package table, after the deleted row's
- * retained stamp); for a package table also the context the approval is for.
+ * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, a tick of
+ * the context's write clock (wall time without a tracked source) or just after the row on record
+ * when that was signed by a clock running ahead, so the new signature counts as the later one
+ * (and, for a package table, after the deleted row's retained stamp); for a package table also
+ * the context the approval is for. The save then records the change at this same time
+ * (`writtenAt`), so sync and the signed order agree on which concurrent write is later.
  *
  * @param table - The table being signed for.
  * @param row - The row being signed.

package/dist/data/orm/write-checks.js

@@ -56,10 +56,12 @@ async function checkLocalSave(table, row, check) {
  */
 exports.packageApprovalTables = new Set(["Packages", "PackageVersions"]);
 /**
- * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, now or
- * just after the row on record when that was signed by a clock running ahead, so the new
- * signature counts as the later one (and, for a package table, after the deleted row's
- * retained stamp); for a package table also the context the approval is for.
+ * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, a tick of
+ * the context's write clock (wall time without a tracked source) or just after the row on record
+ * when that was signed by a clock running ahead, so the new signature counts as the later one
+ * (and, for a package table, after the deleted row's retained stamp); for a package table also
+ * the context the approval is for. The save then records the change at this same time
+ * (`writtenAt`), so sync and the signed order agree on which concurrent write is later.
  *
  * @param table - The table being signed for.
  * @param row - The row being signed.
@@ -76,8 +78,13 @@ async function signingStamp(table, row, current) {
         const dataContext = (await getUserContext()).getDataContext(groupId);
         floor = await deletedSignedAt(tableName, { dataContext, recordId });
     }
+    // Duck typing also works when the data source comes from another installed SDK copy.
+    let source = table.dataSource;
+    while (source && !source.getWriteClock)
+        source = source.dataSource;
+    const clock = await source?.getWriteClock?.();
     return {
-        signedAt: Math.max(Date.now(), floor + 1),
+        signedAt: Math.max(clock ? Math.ceil(clock.tick()) : Date.now(), floor + 1),
         ...(packageTable ? { signedContextId: groupId } : {}),
     };
 }

package/dist/data/package-versions.js

@@ -137,7 +137,12 @@ let PackageVersionsTable = (() => {
                 ...packageVersion,
                 ...(await (0, write_checks_1.signingStamp)(this, packageVersion)),
             });
-            return this.save(packageVersion, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(packageVersion, {
+                ...opts,
+                saveAsSnapshot: true,
+                writtenAt: packageVersion.signedAt,
+            });
         }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageVersionSigning(fn) {

package/dist/data/packages.js

@@ -127,7 +127,8 @@ let PackagesTable = (() => {
                 ...packageObj,
                 ...(await (0, write_checks_1.signingStamp)(this, packageObj)),
             });
-            return this.save(packageObj, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(packageObj, { ...opts, saveAsSnapshot: true, writtenAt: packageObj.signedAt });
         }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageSigning(fn) {

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

@@ -9,18 +9,18 @@ export declare const tableDefinitionRecordSchema: z.ZodObject<{
     deleted: z.ZodOptional<z.ZodDate>;
 }, "strip", z.ZodTypeAny, {
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     versionNumber: number;
     deleted?: Date | undefined;
 }, {
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     deleted?: Date | undefined;
     versionNumber?: number | undefined;
 }>;
@@ -36,10 +36,10 @@ export type ITableDefinitionRecord = z.infer<typeof tableDefinitionRecordSchema>
  */
 export declare function TableDefinitions(dataContext?: DataContext): import("..").Table<{
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     versionNumber: number;
     deleted?: Date | undefined;
 }>;

package/dist/data/tool-access-approvals.d.ts

@@ -46,9 +46,9 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     nonce: string;
     status: ToolAccessApprovalStatus;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     scope: ToolAccessApprovalScope;
     createdAt: Date;
     dataContextId: string;
@@ -69,9 +69,9 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
     resultSummary?: string | undefined;
 }, {
     nonce: string;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     dataContextId: string;
     expiresAt: Date;
     toolAccessApprovalId: string;
@@ -102,9 +102,9 @@ export type IToolAccessApproval = z.infer<typeof toolAccessApprovalSchema>;
 export declare function ToolAccessApprovals(dataContext?: DataContext): import("..").Table<{
     nonce: string;
     status: ToolAccessApprovalStatus;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     scope: ToolAccessApprovalScope;
     createdAt: Date;
     dataContextId: string;

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,30 @@ 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.
+ * `writtenAt` must stay host-only even if this allowlist expands: it orders signed rows,
+ * and accepting it from a package would let that package backdate writes.
+ *
+ * @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 +327,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,20 @@ 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.
+ * `writtenAt` must stay host-only even if this allowlist expands: it orders signed rows,
+ * and accepting it from a package would let that package backdate writes.
+ *
+ * @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.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"