@agoric/internal 0.3.3-other-dev-8f8782b.0 → 0.3.3-other-dev-3eb1a1d.0

package/src/lib-chainStorage.js

@@ -1,10 +1,15 @@
 // @ts-check
 
-import { E } from '@endo/far';
-import { M, heapZone } from '@agoric/zone';
+import { Fail } from '@endo/errors';
+import { E, Far } from '@endo/far';
+import { M } from '@endo/patterns';
+import { makeHeapZone } from '@agoric/base-zone/heap.js';
 import * as cb from './callback.js';
 
-const { Fail } = assert;
+/**
+ * @import {ERef} from '@endo/far';
+ * @import {PassableCap} from '@endo/marshal';
+ */
 
 /** @typedef {ReturnType<typeof import('@endo/marshal').makeMarshal>} Marshaller */
 /** @typedef {Pick<Marshaller, 'fromCapData'>} Unserializer */
@@ -29,7 +34,8 @@ const { Fail } = assert;
 /**
  * This represents a node in an IAVL tree.
  *
- * The active implementation is x/vstorage, an Agoric extension of the Cosmos SDK.
+ * The active implementation is x/vstorage, an Agoric extension of the Cosmos
+ * SDK.
  *
  * Vstorage is a hierarchical externally-reachable storage structure that
  * identifies children by restricted ASCII name and is associated with arbitrary
@@ -37,9 +43,13 @@ const { Fail } = assert;
  *
  * @typedef {object} StorageNode
  * @property {(data: string) => Promise<void>} setValue publishes some data
- * @property {() => string} getPath the chain storage path at which the node was constructed
+ * @property {() => string} getPath the chain storage path at which the node was
+ *   constructed
  * @property {() => Promise<VStorageKey>} getStoreKey DEPRECATED use getPath
- * @property {(subPath: string, options?: {sequence?: boolean}) => StorageNode} makeChildNode
+ * @property {(
+ *   subPath: string,
+ *   options?: { sequence?: boolean },
+ * ) => StorageNode} makeChildNode
  */
 
 const ChainStorageNodeI = M.interface('StorageNode', {
@@ -53,9 +63,8 @@ const ChainStorageNodeI = M.interface('StorageNode', {
 
 /**
  * This is an imperfect heuristic to navigate the migration from value cells to
- * stream cells.
- * At time of writing, no legacy cells have the same shape as a stream cell,
- * and we do not intend to create any more legacy value cells.
+ * stream cells. At time of writing, no legacy cells have the same shape as a
+ * stream cell, and we do not intend to create any more legacy value cells.
  *
  * @param {any} cell
  * @returns {cell is StreamCell}
@@ -83,49 +92,20 @@ export const assertCapData = data => {
 };
 harden(assertCapData);
 
-/**
- * Read and unmarshal a value from a map representation of vstorage data
- *
- * @param {Map<string, string>} data
- * @param {string} key
- * @param {ReturnType<typeof import('@endo/marshal').makeMarshal>['fromCapData']} fromCapData
- * @param {number} [index=-1] index of the desired value in a deserialized stream cell
- */
-export const unmarshalFromVstorage = (data, key, fromCapData, index = -1) => {
-  const serialized = data.get(key) || Fail`no data for ${key}`;
-  assert.typeof(serialized, 'string');
-
-  const streamCell = JSON.parse(serialized);
-  if (!isStreamCell(streamCell)) {
-    throw Fail`not a StreamCell: ${streamCell}`;
-  }
-
-  const { values } = streamCell;
-  values.length > 0 || Fail`no StreamCell values: ${streamCell}`;
-
-  const marshalled = values.at(index);
-  assert.typeof(marshalled, 'string');
-
-  /** @type {import("@endo/marshal").CapData<string>} */
-  const capData = harden(JSON.parse(marshalled));
-  assertCapData(capData);
-
-  const unmarshalled = fromCapData(capData);
-  return unmarshalled;
-};
-harden(unmarshalFromVstorage);
-
 /**
  * @typedef {object} StoredFacet
- * @property {() => Promise<string>} getPath the chain storage path at which the node was constructed
+ * @property {() => Promise<string>} getPath the chain storage path at which the
+ *   node was constructed
  * @property {StorageNode['getStoreKey']} getStoreKey DEPRECATED use getPath
- * @property {() => Unserializer} getUnserializer get the unserializer for the stored data
+ * @property {() => Unserializer} getUnserializer get the unserializer for the
+ *   stored data
  */
 
 // TODO: Formalize segment constraints.
 // Must be nonempty and disallow (unescaped) `.`, and for simplicity
 // (and future possibility of e.g. escaping) we currently limit to
 // ASCII alphanumeric plus underscore and dash.
+// Should remain consistent with golang/cosmos/x/vstorage/types/path_keys.go
 const pathSegmentPattern = /^[a-zA-Z0-9_-]{1,100}$/;
 
 /** @type {(name: string) => void} */
@@ -138,44 +118,65 @@ harden(assertPathSegment);
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  *
- * @typedef { 'get' | 'getStoreKey' | 'has' | 'children' | 'entries' | 'values' |'size' } StorageGetByPathMessageMethod
- * @typedef { 'set' | 'setWithoutNotify' | 'append' } StorageUpdateEntriesMessageMethod
- * @typedef {StorageGetByPathMessageMethod | StorageUpdateEntriesMessageMethod } StorageMessageMethod
- * @typedef { [path: string] } StorageGetByPathMessageArgs
- * @typedef { [path: string, value?: string | null] } StorageEntry
- * @typedef { StorageEntry[] } StorageUpdateEntriesMessageArgs
+ * @typedef {'get'
+ *   | 'getStoreKey'
+ *   | 'has'
+ *   | 'children'
+ *   | 'entries'
+ *   | 'values'
+ *   | 'size'} StorageGetByPathMessageMethod
+ *
+ *
+ * @typedef {'set' | 'setWithoutNotify' | 'append'} StorageUpdateEntriesMessageMethod
+ *
+ *
+ * @typedef {StorageGetByPathMessageMethod
+ *   | StorageUpdateEntriesMessageMethod} StorageMessageMethod
+ *
+ *
+ * @typedef {[path: string]} StorageGetByPathMessageArgs
+ *
+ * @typedef {[path: string, value?: string | null]} StorageEntry
+ *
+ * @typedef {StorageEntry[]} StorageUpdateEntriesMessageArgs
+ *
  * @typedef {{
- *   method: StorageGetByPathMessageMethod;
- *   args: StorageGetByPathMessageArgs;
- *  } | {
- *   method: StorageUpdateEntriesMessageMethod;
- *   args: StorageUpdateEntriesMessageArgs;
- * }} StorageMessage
+ *       method: StorageGetByPathMessageMethod;
+ *       args: StorageGetByPathMessageArgs;
+ *     }
+ *   | {
+ *       method: StorageUpdateEntriesMessageMethod;
+ *       args: StorageUpdateEntriesMessageArgs;
+ *     }} StorageMessage
  */
 
 /**
- * @param {import('@agoric/zone').Zone} zone
+ * @param {import('@agoric/base-zone').Zone} zone
  */
 export const prepareChainStorageNode = zone => {
   /**
    * Create a storage node for a given backing storage interface and path.
    *
-   * @param {import('./callback').Callback<(message: StorageMessage) => any>} messenger a callback
-   * for sending a storageMessage object to the storage implementation
-   * (cf. golang/cosmos/x/vstorage/vstorage.go)
+   * @param {import('./types.js').Callback<
+   *   (message: StorageMessage) => any
+   * >} messenger
+   *   a callback for sending a storageMessage object to the storage
+   *   implementation (cf. golang/cosmos/x/vstorage/vstorage.go)
    * @param {string} path
    * @param {object} [options]
-   * @param {boolean} [options.sequence] set values with `append` messages rather than `set` messages
-   * so the backing implementation employs a wrapping structure that
-   * preserves each value set within a single block.
-   * Child nodes default to inheriting this option from their parent.
+   * @param {boolean} [options.sequence] set values with `append` messages
+   *   rather than `set` messages so the backing implementation employs a
+   *   wrapping structure that preserves each value set within a single block.
+   *   Child nodes default to inheriting this option from their parent.
    * @returns {StorageNode}
    */
   const makeChainStorageNode = zone.exoClass(
     'ChainStorageNode',
     ChainStorageNodeI,
     /**
-     * @param {import('./callback').Callback<(message: StorageMessage) => any>} messenger
+     * @param {import('./types.js').Callback<
+     *   (message: StorageMessage) => any
+     * >} messenger
      * @param {string} path
      * @param {object} [options]
      * @param {boolean} [options.sequence]
@@ -200,7 +201,12 @@ export const prepareChainStorageNode = zone => {
           args: [path],
         });
       },
-      /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+      /**
+       * @type {(
+       *   name: string,
+       *   childNodeOptions?: { sequence?: boolean },
+       * ) => StorageNode}
+       */
       makeChildNode(name, childNodeOptions = {}) {
         const { sequence, path, messenger } = this.state;
         assertPathSegment(name);
@@ -239,19 +245,20 @@ export const prepareChainStorageNode = zone => {
   return makeChainStorageNode;
 };
 
-const makeHeapChainStorageNode = prepareChainStorageNode(heapZone);
+const makeHeapChainStorageNode = prepareChainStorageNode(makeHeapZone());
 
 /**
- * Create a heap-based root storage node for a given backing function and root path.
+ * Create a heap-based root storage node for a given backing function and root
+ * path.
  *
  * @param {(message: StorageMessage) => any} handleStorageMessage a function for
- * sending a storageMessage object to the storage implementation
- * (cf. golang/cosmos/x/vstorage/vstorage.go)
+ *   sending a storageMessage object to the storage implementation (cf.
+ *   golang/cosmos/x/vstorage/vstorage.go)
  * @param {string} rootPath
  * @param {object} [rootOptions]
  * @param {boolean} [rootOptions.sequence] employ a wrapping structure that
- * preserves each value set within a single block, and default child nodes
- * to do the same
+ *   preserves each value set within a single block, and default child nodes to
+ *   do the same
  */
 export function makeChainStorageRoot(
   handleStorageMessage,
@@ -266,11 +273,15 @@ export function makeChainStorageRoot(
 }
 
 /**
- * @returns {StorageNode} an object that confirms to StorageNode API but does not store anywhere.
+ * @returns {StorageNode} an object that confirms to StorageNode API but does
+ *   not store anywhere.
  */
 const makeNullStorageNode = () => {
   // XXX re-use "ChainStorage" methods above which don't actually depend on chains
-  return makeChainStorageRoot(() => null, 'null');
+  return makeChainStorageRoot(
+    Far('NullMessenger', () => null),
+    'null',
+  );
 };
 
 /**
@@ -278,7 +289,7 @@ const makeNullStorageNode = () => {
  * falling back to an inert object with the correct interface (but incomplete
  * behavior) when that is unavailable.
  *
- * @param {import('@endo/far').ERef<StorageNode?>} storageNodeRef
+ * @param {ERef<StorageNode?>} storageNodeRef
  * @param {string} childName
  * @returns {Promise<StorageNode>}
  */
@@ -291,9 +302,9 @@ harden(makeStorageNodeChild);
 
 // TODO find a better module for this
 /**
- * @param {import('@endo/far').ERef<StorageNode>} storageNode
- * @param {import('@endo/far').ERef<Marshaller>} marshaller
- * @returns {(value: unknown) => Promise<void>}
+ * @param {ERef<StorageNode>} storageNode
+ * @param {ERef<Marshaller>} marshaller
+ * @returns {(value: PassableCap) => Promise<void>}
  */
 export const makeSerializeToStorage = (storageNode, marshaller) => {
   return async value => {

package/src/lib-nodejs/engine-gc.d.ts

@@ -0,0 +1,3 @@
+export default engineGC;
+declare const engineGC: GCFunction;
+//# sourceMappingURL=engine-gc.d.ts.map

package/src/lib-nodejs/engine-gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-gc.d.ts","sourceRoot":"","sources":["engine-gc.js"],"names":[],"mappings":";AAoBA,mCAAwB"}

package/src/lib-nodejs/engine-gc.js

@@ -0,0 +1,22 @@
+import v8 from 'v8';
+import vm from 'vm';
+
+/* global globalThis */
+let bestGC = globalThis.gc;
+if (typeof bestGC !== 'function') {
+  // Node.js v8 wizardry.
+  v8.setFlagsFromString('--expose_gc');
+  bestGC = vm.runInNewContext('gc');
+  assert(bestGC);
+  // We leave --expose_gc turned on, otherwise AVA's shared workers
+  // may race and disable it before we manage to extract the
+  // binding. This won't cause 'gc' to be visible to new Compartments
+  // because SES strips out everything it doesn't recognize.
+
+  // // Hide the gc global from new contexts/workers.
+  // v8.setFlagsFromString('--no-expose_gc');
+}
+
+// Export a const.
+const engineGC = bestGC;
+export default engineGC;

package/src/lib-nodejs/gc-and-finalize.d.ts

@@ -0,0 +1,2 @@
+export function makeGcAndFinalize(gcPower: any): () => Promise<void>;
+//# sourceMappingURL=gc-and-finalize.d.ts.map

package/src/lib-nodejs/gc-and-finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc-and-finalize.d.ts","sourceRoot":"","sources":["gc-and-finalize.js"],"names":[],"mappings":"AAkEA,qEAwBC"}

package/src/lib-nodejs/gc-and-finalize.js

@@ -0,0 +1,91 @@
+/* global setImmediate */
+
+/* A note on our GC terminology:
+ *
+ * We define four states for any JS object to be in:
+ *
+ * REACHABLE: There exists a path from some root (live export or top-level
+ * global) to this object, making it ineligible for collection. Userspace vat
+ * code has a strong reference to it (and userspace is not given access to
+ * WeakRef, so it has no weak reference that might be used to get access).
+ *
+ * UNREACHABLE: There is no strong reference from a root to the object.
+ * Userspace vat code has no means to access the object, although liveslots
+ * might (via a WeakRef). The object is eligible for collection, but that
+ * collection has not yet happened. The liveslots WeakRef is still alive: if
+ * it were to call `.deref()`, it would get the object.
+ *
+ * COLLECTED: The JS engine has performed enough GC to notice the
+ * unreachability of the object, and has collected it. The liveslots WeakRef
+ * is dead: `wr.deref() === undefined`. Neither liveslots nor userspace has
+ * any way to reach the object, and never will again. A finalizer callback
+ * has been queued, but not yet executed.
+ *
+ * FINALIZED: The JS engine has run the finalizer callback. Once the
+ * callback completes, the object is thoroughly dead and unremembered,
+ * and no longer exists in one of these four states.
+ *
+ * The transition from REACHABLE to UNREACHABLE always happens as a result of
+ * a message delivery or resolution notification (e.g when userspace
+ * overwrites a variable, deletes a Map entry, or a callback on the promise
+ * queue which closed over some objects is retired and deleted).
+ *
+ * The transition from UNREACHABLE to COLLECTED can happen spontaneously, as
+ * the JS engine decides it wants to perform GC. It will also happen
+ * deliberately if we provoke a GC call with a magic function like `gc()`
+ * (when Node.js imports `engine-gc`, which is morally-equivalent to
+ * running with `--expose-gc`, or when XS is configured to provide it as a
+ * C-level callback). We can force GC, but we cannot prevent it from happening
+ * at other times.
+ *
+ * FinalizationRegistry callbacks are defined to run on their own turn, so
+ * the transition from COLLECTED to FINALIZED occurs at a turn boundary.
+ * Node.js appears to schedule these finalizers on the timer/IO queue, not
+ * the promise/microtask queue. So under Node.js, you need a `setImmediate()`
+ * or two to ensure that finalizers have had a chance to run. XS is different
+ * but responds well to similar techniques.
+ */
+
+/*
+ * `gcAndFinalize` must be defined in the start compartment. It uses
+ * platform-specific features to provide a function which provokes a full GC
+ * operation: all "UNREACHABLE" objects should transition to "COLLECTED"
+ * before it returns. In addition, `gcAndFinalize()` returns a Promise. This
+ * Promise will resolve (with `undefined`) after all FinalizationRegistry
+ * callbacks have executed, causing all COLLECTED objects to transition to
+ * FINALIZED. If the caller can manage call gcAndFinalize with an empty
+ * promise queue, then their .then callback will also start with an empty
+ * promise queue, and there will be minimal uncollected unreachable objects
+ * in the heap when it begins.
+ *
+ * `gcAndFinalize` depends upon platform-specific tools to provoke a GC sweep
+ * and wait for finalizers to run: a `gc()` function, and `setImmediate`. If
+ * these tools do not exist, this function will do nothing, and return a
+ * dummy pre-resolved Promise.
+ */
+
+export function makeGcAndFinalize(gcPower) {
+  if (typeof gcPower !== 'function') {
+    if (gcPower !== false) {
+      // We weren't explicitly disabled, so warn.
+      console.warn(
+        Error(`no gcPower() function; skipping finalizer provocation`),
+      );
+    }
+  }
+  return async function gcAndFinalize() {
+    if (typeof gcPower !== 'function') {
+      return;
+    }
+
+    // on Node.js, GC seems to work better if the promise queue is empty first
+    await new Promise(setImmediate);
+    // on xsnap, we must do it twice for some reason
+    await new Promise(setImmediate);
+    gcPower();
+    // this gives finalizers a chance to run
+    await new Promise(setImmediate);
+    // Node.js seems to need another for promises to get cleared out
+    await new Promise(setImmediate);
+  };
+}

package/src/lib-nodejs/spawnSubprocessWorker.d.ts

@@ -0,0 +1,15 @@
+export function startSubprocessWorker(execPath: any, procArgs?: any[], { netstringMaxChunkSize }?: {
+    netstringMaxChunkSize?: undefined;
+}): {
+    fromChild: {
+        on: (...args: any[]) => import("stream").Transform;
+    };
+    toChild: {
+        write: (...args: any[]) => boolean;
+    };
+    terminate: () => void;
+    done: Promise<any>;
+};
+export type IOType = import("child_process").IOType;
+export type Writable = import("stream").Writable;
+//# sourceMappingURL=spawnSubprocessWorker.d.ts.map

package/src/lib-nodejs/spawnSubprocessWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawnSubprocessWorker.d.ts","sourceRoot":"","sources":["spawnSubprocessWorker.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;EA0DC;qBApEa,OAAO,eAAe,EAAE,MAAM;uBAC9B,OAAO,QAAQ,EAAE,QAAQ"}

package/src/lib-nodejs/spawnSubprocessWorker.js

@@ -0,0 +1,89 @@
+// this file is loaded by the controller, in the start compartment
+import { spawn } from 'child_process';
+import { makePromiseKit } from '@endo/promise-kit';
+import { NonNullish } from '../errors.js';
+import { arrayEncoderStream, arrayDecoderStream } from './worker-protocol.js';
+import {
+  netstringEncoderStream,
+  netstringDecoderStream,
+} from '../netstring.js';
+
+// Start a subprocess from a given executable, and arrange a bidirectional
+// message channel with a "supervisor" within that process. Return a {
+// toChild, fromChild } pair of Streams which accept/emit hardened Arrays of
+// JSON-serializable data.
+
+// eslint-disable-next-line no-unused-vars
+function parentLog(first, ...args) {
+  // console.error(`--parent: ${first}`, ...args);
+}
+
+/** @typedef {import('child_process').IOType} IOType */
+/** @typedef {import('stream').Writable} Writable */
+
+// we send on fd3, and receive on fd4. We pass fd1/2 (stdout/err) through, so
+// console log/err from the child shows up normally. We don't use Node's
+// built-in serialization feature ('ipc') because the child process won't
+// always be Node.
+/** @type {IOType[]} */
+const stdio = harden(['inherit', 'inherit', 'inherit', 'pipe', 'pipe']);
+
+export function startSubprocessWorker(
+  execPath,
+  procArgs = [],
+  { netstringMaxChunkSize = undefined } = {},
+) {
+  const proc = spawn(execPath, procArgs, { stdio });
+
+  const toChild = arrayEncoderStream();
+  toChild
+    .pipe(netstringEncoderStream())
+    .pipe(/** @type {Writable} */ (proc.stdio[3]));
+  // proc.stdio[4].setEncoding('utf-8');
+  const fromChild = NonNullish(proc.stdio[4])
+    .pipe(netstringDecoderStream(netstringMaxChunkSize))
+    .pipe(arrayDecoderStream());
+
+  // fromChild.addListener('data', data => parentLog(`fd4 data`, data));
+  // toChild.write('hello child');
+
+  const pk = makePromiseKit();
+
+  proc.once('exit', code => {
+    parentLog('child exit', code);
+    pk.resolve(code);
+  });
+  proc.once('error', e => {
+    parentLog('child error', e);
+    pk.reject(e);
+  });
+  parentLog(`waiting on child`);
+
+  function terminate() {
+    proc.kill();
+  }
+
+  // the Transform objects don't like being hardened, so we wrap the methods
+  // that get used
+  /* @type {typeof fromChild} */
+  const wrappedFromChild = {
+    on: (...args) =>
+      fromChild.on(
+        .../** @type {Parameters<(typeof fromChild)['on']>} */ (args),
+      ),
+  };
+  /* @type {typeof toChild} */
+  const wrappedToChild = {
+    write: (...args) =>
+      toChild.write(
+        .../** @type {Parameters<(typeof toChild)['write']>} */ (args),
+      ),
+  };
+
+  return harden({
+    fromChild: wrappedFromChild,
+    toChild: wrappedToChild,
+    terminate,
+    done: pk.promise,
+  });
+}

package/src/lib-nodejs/waitUntilQuiescent.d.ts

@@ -0,0 +1,2 @@
+export function waitUntilQuiescent(): Promise<void>;
+//# sourceMappingURL=waitUntilQuiescent.d.ts.map

package/src/lib-nodejs/waitUntilQuiescent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waitUntilQuiescent.d.ts","sourceRoot":"","sources":["waitUntilQuiescent.js"],"names":[],"mappings":"AAMA,oDAWC"}

package/src/lib-nodejs/waitUntilQuiescent.js

@@ -0,0 +1,18 @@
+/* global setImmediate */
+import { makePromiseKit } from '@endo/promise-kit';
+
+// This can only be imported from the Start Compartment, where 'setImmediate'
+// is available.
+
+export function waitUntilQuiescent() {
+  // the delivery might cause some number of (native) Promises to be
+  // created and resolved, so we use the IO queue to detect when the
+  // Promise queue is empty. The IO queue (setImmediate and setTimeout) is
+  // lower-priority than the Promise queue on browsers and Node 11, but on
+  // Node 10 it is higher. So this trick requires Node 11.
+  // https://jsblog.insiderattack.net/new-changes-to-timers-and-microtasks-from-node-v11-0-0-and-above-68d112743eb3
+  /** @type {import('@endo/promise-kit').PromiseKit<void>} */
+  const { promise: queueEmptyP, resolve } = makePromiseKit();
+  setImmediate(() => resolve());
+  return queueEmptyP;
+}

package/src/lib-nodejs/worker-protocol.d.ts

@@ -0,0 +1,4 @@
+export function arrayEncoderStream(): Transform;
+export function arrayDecoderStream(): Transform;
+import { Transform } from 'stream';
+//# sourceMappingURL=worker-protocol.d.ts.map

package/src/lib-nodejs/worker-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["worker-protocol.js"],"names":[],"mappings":"AAMA,gDAqBC;AAED,gDAwBC;0BApDyB,QAAQ"}

package/src/lib-nodejs/worker-protocol.js

@@ -0,0 +1,54 @@
+/* eslint-env node */
+import { Transform } from 'stream';
+
+// Transform objects which convert from hardened Arrays of JSON-serializable
+// data into Buffers suitable for netstring conversion.
+
+export function arrayEncoderStream() {
+  /**
+   * @param {any} object
+   * @param {BufferEncoding} encoding
+   * @param {any} callback
+   * @this {{ push: (b: Buffer) => void }}
+   */
+  function transform(object, encoding, callback) {
+    if (!Array.isArray(object)) {
+      throw Error('stream requires Arrays');
+    }
+    let err;
+    try {
+      this.push(Buffer.from(JSON.stringify(object)));
+    } catch (e) {
+      err = e;
+    }
+    callback(err);
+  }
+  // Array in, Buffer out, hence writableObjectMode
+  return new Transform({ transform, writableObjectMode: true });
+}
+
+export function arrayDecoderStream() {
+  /**
+   * @param {Buffer} buf
+   * @param {BufferEncoding} encoding
+   * @param {any} callback
+   * @this {{ push: (b: Buffer) => void }}
+   */
+  function transform(buf, encoding, callback) {
+    let err;
+    try {
+      if (!Buffer.isBuffer(buf)) {
+        throw Error('stream expects Buffers');
+      }
+      this.push(JSON.parse(buf.toString()));
+    } catch (e) {
+      err = e;
+    }
+    // this Transform is a one-to-one conversion of Buffer into Array, so we
+    // always consume the input each time we're called
+    callback(err);
+  }
+
+  // Buffer in, Array out, hence readableObjectMode
+  return new Transform({ transform, readableObjectMode: true });
+}

package/src/magic-cookie-test-only.js

@@ -3,8 +3,8 @@
 const cookie = harden({});
 
 /**
- * Facilitate static analysis to prevent
- * demo/test facilities from being bundled in production.
+ * Facilitate static analysis to prevent demo/test facilities from being bundled
+ * in production.
  */
 export const notForProductionUse = () => {
   return cookie;

package/src/marshal.d.ts

@@ -0,0 +1,20 @@
+export function makeBoardRemote({ boardId, iface }: {
+    boardId: string | null;
+    iface?: string;
+}): BoardRemote;
+export function slotToBoardRemote(boardId: string, iface: string): BoardRemote;
+export function boardSlottingMarshaller(slotToVal?: ((slot: string, iface: string) => any) | undefined): Omit<import("@endo/marshal").Marshal<string | null>, "serialize" | "unserialize">;
+export function unmarshalFromVstorage(data: Map<string, string>, key: string, fromCapData: ReturnType<typeof import("@endo/marshal").makeMarshal>["fromCapData"], index: number): any;
+export function makeHistoryReviver(entries: [string, string][], slotToVal?: ((slot: string, iface?: string) => any) | undefined): {
+    getItem: (key: string) => any;
+    children: (prefix: string) => string[];
+    has: (k: string) => boolean;
+};
+/**
+ * Should be a union with Remotable, but that's `any`, making this type
+ * meaningless
+ */
+export type BoardRemote = {
+    getBoardId: () => string | null;
+};
+//# sourceMappingURL=marshal.d.ts.map

package/src/marshal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marshal.d.ts","sourceRoot":"","sources":["marshal.js"],"names":[],"mappings":"AAiBO,oDAHI;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,WAAW,CAKvB;AAMM,2CAHI,MAAM,SACN,MAAM,eAGoB;AAqB9B,4DANW,MAAM,SAAS,MAAM,KAAK,GAAG,gBAClC,IAAI,CAChB,OAAW,eAAe,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAClD,WAAe,GAAG,aAAa,CAC5B,CAMH;AA6BM,4CATI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OACnB,MAAM,eACN,UAAU,CACpB,cAAkB,eAAe,EAAE,WAAW,CAC3C,CAAC,aAAa,CAAC,SACR,MAAM,GAEJ,GAAG,CAwBf;AASM,4CAHI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,sBACX,MAAM,UAAU,MAAM,KAAK,GAAG;mBAQlC,MAAM;uBAEN,MAAM;aAYN,MAAM;EAInB;;;;;0BA9HY;IAAE,UAAU,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;CAAE"}