@peers-app/peers-sdk 0.28.0 → 0.28.2

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. */
@@ -16,6 +17,12 @@ export interface IPackageTableDefinition<S extends z.AnyZodObject = z.AnyZodObje
     versionNumber?: number;
     /** Keep rows on this device only. They never sync. */
     localOnly?: boolean;
+    /**
+     * Indexes for the fields queries filter or sort by, each in order (a field name, or a name with
+     * `"ASC"` or `"DESC"`). A local-only table can also make one `unique`. Changing them is a
+     * schema change, so raise `versionNumber`.
+     */
+    indexes?: IPackageTableIndex<S>[];
     /**
      * The table's class, to override its methods: `Feeds(ctx)` returns one, and so does every
      * consumer call through a contract, so an override is always the logic in use. Defaults to
@@ -23,6 +30,15 @@ export interface IPackageTableDefinition<S extends z.AnyZodObject = z.AnyZodObje
      */
     tableClass?: PackageTableClass<S>;
 }
+/** One index of a {@link defineTable} table: its fields in order, each ascending unless set. */
+export interface IPackageTableIndex<S extends z.AnyZodObject = z.AnyZodObject> {
+    fields: (Extract<keyof z.infer<S>, string> | {
+        name: Extract<keyof z.infer<S>, string>;
+        order: "ASC" | "DESC";
+    })[];
+    /** No two rows share these values. Only on a `localOnly` table: synced rows can collide. */
+    unique?: true;
+}
 /** A class extending {@link PackageTable} for a table's schema. */
 export type PackageTableClass<S extends z.AnyZodObject = z.AnyZodObject> = new (ctx: IPackageContext, definition: Readonly<IPackageTableDefinition<S>>) => PackageTable<S>;
 /** One table's methods, bound to one handler call. */
@@ -38,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>;
 }
@@ -88,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-artifact.d.ts

@@ -125,6 +125,20 @@ export interface IIsolatedPackageTable {
      * of a contract's table shape.
      */
     localOnly?: boolean;
+    /**
+     * Indexes for the fields queries filter or sort by, each in order. Unique only on a local-only
+     * table. Storage policy, like `localOnly`: changing them needs a higher `versionNumber`.
+     */
+    indexes?: IIsolatedTableIndex[];
+}
+/** One index of an isolated package table: field names in order, each ascending unless set. */
+export interface IIsolatedTableIndex {
+    fields: (string | {
+        name: string;
+        order: "ASC" | "DESC";
+    })[];
+    /** No two rows share these values. Local-only tables only. */
+    unique?: true;
 }
 /** Name-only reference that exposes one package table through a contract. */
 export interface IIsolatedContractTableRef {

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

@@ -19,6 +19,7 @@ exports.findPackageTable = findPackageTable;
 exports.toConsumedContracts = toConsumedContracts;
 const contract_definition_schema_1 = require("../contracts/contract-definition-schema");
 const access_level_1 = require("../data/access-level");
+const package_table_identity_1 = require("../data/package-table-identity");
 const persistent_var_identity_1 = require("../data/persistent-var-identity");
 const field_type_1 = require("../types/field-type");
 const utils_1 = require("../utils");
@@ -300,7 +301,7 @@ function validatePackageTables(manifest, strict) {
         if (forbiddenIdentity) {
             throw new Error(`${tableLabel} must not declare ${forbiddenIdentity}`);
         }
-        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber", "localOnly"], tableLabel);
+        assertOnlyKeys(table, ["name", "description", "primaryKeyName", "fields", "versionNumber", "localOnly", "indexes"], tableLabel);
         if (typeof table.name !== "string" || table.name.trim() === "") {
             throw new Error(`${tableLabel}.name is required`);
         }
@@ -336,6 +337,7 @@ function validatePackageTables(manifest, strict) {
         else {
             table.versionNumber = 1;
         }
+        (0, package_table_identity_1.validateTableIndexes)(table.indexes, new Set(table.fields.map((field) => field.name)), `${tableLabel}.indexes`, table.localOnly);
     }
 }
 function validateProvidedContract(contract, index, packageTables, guestApi, strict) {

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

@@ -4,12 +4,34 @@ import type { IContractCall, IContractProviderEndpoint } from "../contracts/cont
 import type { ContractRegistry } from "../contracts/registry";
 import type { PersistentVarScope } from "../data/persistent-vars";
 import type { IField } from "../types/field-type";
-import type { IIsolatedContractToolRef, IIsolatedInstalledPackage, IIsolatedInstallResult, IIsolatedPackageArtifact } from "./isolated-artifact";
+import type { IIsolatedContractToolRef, IIsolatedInstalledPackage, IIsolatedInstallResult, IIsolatedPackageArtifact, IIsolatedTableIndex } from "./isolated-artifact";
 import type { IPackageWorkerHealth } from "./package-runtime-state";
 /** Standard table methods exposed through isolated contract-table references. */
 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.
@@ -165,6 +187,8 @@ export interface IIsolatedPackageTableDeclaration extends IIsolatedPackageTableR
     versionNumber?: number;
     /** Rows stay on the writing device; see `IIsolatedPackageTable.localOnly`. */
     localOnly?: boolean;
+    /** Indexes; see `IIsolatedPackageTable.indexes`. */
+    indexes?: IIsolatedTableIndex[];
 }
 /**
  * Trusted host capability for isolated-package table persistence.
@@ -301,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/isolated-table-gateway.js

@@ -43,6 +43,7 @@ function validateDeclaration(declaration) {
     if (declaration.localOnly !== undefined && typeof declaration.localOnly !== "boolean") {
         throw new Error("Isolated table localOnly must be a boolean");
     }
+    (0, package_table_identity_1.validateTableIndexes)(declaration.indexes, fieldNames, "Isolated table indexes", declaration.localOnly);
     const { localOnly, ...rest } = declaration;
     return {
         ...rest,
@@ -61,8 +62,9 @@ function toMetaData(rawDeclaration) {
         primaryKeyName: declaration.primaryKeyName,
         fields: declaration.fields,
         versionNumber: versionNumber(declaration),
-        // Only when set: stored definitions hash their metadata, and older ones have no such key.
+        // Only when set: stored definitions hash their metadata, and older ones have no such keys.
         ...(declaration.localOnly ? { localOnly: true } : {}),
+        ...(declaration.indexes?.length ? { indexes: declaration.indexes } : {}),
     };
 }
 function normalizedMetaData(metaData) {
@@ -111,6 +113,7 @@ function declarationFromMetaData(metaData) {
         fields: metaData.fields,
         versionNumber: metaData.versionNumber,
         localOnly: metaData.localOnly,
+        ...(metaData.indexes?.length ? { indexes: metaData.indexes } : {}),
     });
 }
 function metaDataFromStoredDefinition(record, incoming) {

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/peer-id.d.ts

@@ -1,5 +1,24 @@
 /** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
 export declare function cryptoRandomString(length: number): string;
+/**
+ * A 25-character peer id derived from `input`: `prefix`, then base-36 characters of its SHA-512
+ * hash. The same input always gives the same id. Each kind of derived id has its own prefix, so
+ * kinds can't collide.
+ *
+ * @param prefix - Fixed leading characters naming the kind of id.
+ * @param input - What the id is derived from.
+ */
+export declare function deterministicPeerId(prefix: string, input: string): string;
+/**
+ * A peer id derived from `key`, the same on every device. Rows different devices save under the
+ * same key are then one row, which sync merges as ordinary updates: how a synced table keeps one
+ * row per key, where a unique index can't (two devices could each save a row the other's index
+ * refuses). Start the key with what it identifies (`` `store:${name}` ``) so ids for different
+ * things can't collide.
+ *
+ * @param key - What the row stands for.
+ */
+export declare function idFromKey(key: string): string;
 /**
  * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
  * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.

package/dist/peer-id.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_ID = exports.MIN_ID = void 0;
 exports.cryptoRandomString = cryptoRandomString;
+exports.deterministicPeerId = deterministicPeerId;
+exports.idFromKey = idFromKey;
 exports.newid = newid;
 exports.isid = isid;
 exports.idTime = idTime;
@@ -35,6 +37,45 @@ function cryptoRandomString(length) {
     }
     return s.substring(0, length);
 }
+/**
+ * Converts a byte array to a base-36 string of the requested length, using unbiased modular reduction.
+ * Bytes >= 252 are skipped to avoid bias (same technique as {@link cryptoRandomString}).
+ */
+function bytesToBase36(bytes, length) {
+    let s = "";
+    for (let i = 0; i < bytes.length && s.length < length; i++) {
+        const n = bytes[i];
+        if (n >= 252)
+            continue;
+        s += (n % 36).toString(36);
+    }
+    return s.substring(0, length);
+}
+/**
+ * A 25-character peer id derived from `input`: `prefix`, then base-36 characters of its SHA-512
+ * hash. The same input always gives the same id. Each kind of derived id has its own prefix, so
+ * kinds can't collide.
+ *
+ * @param prefix - Fixed leading characters naming the kind of id.
+ * @param input - What the id is derived from.
+ */
+function deterministicPeerId(prefix, input) {
+    const hashSuffixLength = 25 - prefix.length;
+    const hash = nacl.hash(new TextEncoder().encode(input));
+    return prefix + bytesToBase36(hash, hashSuffixLength);
+}
+/**
+ * A peer id derived from `key`, the same on every device. Rows different devices save under the
+ * same key are then one row, which sync merges as ordinary updates: how a synced table keeps one
+ * row per key, where a unique index can't (two devices could each save a row the other's index
+ * refuses). Start the key with what it identifies (`` `store:${name}` ``) so ids for different
+ * things can't collide.
+ *
+ * @param key - What the row stands for.
+ */
+function idFromKey(key) {
+    return deterministicPeerId("000key00", key);
+}
 /**
  * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
  * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.

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 () => {