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

package/src/lib-chainStorage.js

@@ -1,10 +1,16 @@
 // @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';
+ * @import {TypedPattern} from './types.js';
+ */
 
 /** @typedef {ReturnType<typeof import('@endo/marshal').makeMarshal>} Marshaller */
 /** @typedef {Pick<Marshaller, 'fromCapData'>} Unserializer */
@@ -26,10 +32,17 @@ const { Fail } = assert;
  * @property {T[]} values
  */
 
+/** @type {TypedPattern<StreamCell>} */
+export const StreamCellShape = harden({
+  blockHeight: M.string(),
+  values: M.array(),
+});
+
 /**
  * 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 +50,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 +70,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}
@@ -68,64 +84,20 @@ export const isStreamCell = cell =>
   /^0$|^[1-9][0-9]*$/.test(cell.blockHeight);
 harden(isStreamCell);
 
-// TODO: Consolidate with `insistCapData` functions from swingset-liveslots,
-// swingset-xsnap-supervisor, etc.
-/**
- * @param {unknown} data
- * @returns {asserts data is import('@endo/marshal').CapData<string>}
- */
-export const assertCapData = data => {
-  assert.typeof(data, 'object');
-  assert(data);
-  assert.typeof(data.body, 'string');
-  assert(Array.isArray(data.slots));
-  // XXX check that the .slots array elements are actually strings
-};
-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 +110,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 +193,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 +237,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 +265,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 +281,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 +294,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/ava-unhandled-rejection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @import {ExecutionContext, Macro, TestFn} from 'ava';
+ */
+export const AVA_EXPECT_UNHANDLED_REJECTIONS: "AGORIC_AVA_EXPECT_UNHANDLED_REJECTIONS";
+export const SUBTEST_PREFIX: "(unhandled rejection subprocess): ";
+export function makeExpectUnhandledRejection<C>({ test, importMetaUrl }: {
+    test: TestFn<C>;
+    importMetaUrl: string;
+}): (expectedUnhandled: number) => Macro<[name: string, impl: (t: ExecutionContext<C>) => any], C>;
+import type { TestFn } from 'ava';
+import type { ExecutionContext } from 'ava';
+import type { Macro } from 'ava';
+//# sourceMappingURL=ava-unhandled-rejection.d.ts.map

package/src/lib-nodejs/ava-unhandled-rejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ava-unhandled-rejection.d.ts","sourceRoot":"","sources":["ava-unhandled-rejection.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH,8CACE,wCAAwC,CAAC;AAE3C,6BAA8B,oCAAoC,CAAC;AAW5D,6CARM,CAAC,2BAEX;IAA0B,IAAI,EAAtB,OAAO,CAAC,CAAC;IACM,aAAa,EAA5B,MAAM;CACd,GAAU,CACR,iBAAiB,EAAE,MAAM,KACtB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CA0CtE;4BAzDiD,KAAK;sCAAL,KAAK;2BAAL,KAAK"}

package/src/lib-nodejs/ava-unhandled-rejection.js

@@ -0,0 +1,66 @@
+// @ts-check
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+import engineGC from './engine-gc.js';
+import { makeGcAndFinalize } from './gc-and-finalize.js';
+
+/**
+ * @import {ExecutionContext, Macro, TestFn} from 'ava';
+ */
+
+export const AVA_EXPECT_UNHANDLED_REJECTIONS =
+  'AGORIC_AVA_EXPECT_UNHANDLED_REJECTIONS';
+
+export const SUBTEST_PREFIX = '(unhandled rejection subprocess): ';
+
+/**
+ * @template C
+ * @param {object} powers
+ * @param {TestFn<C>} powers.test
+ * @param {string} powers.importMetaUrl
+ * @returns {(
+ *   expectedUnhandled: number,
+ * ) => Macro<[name: string, impl: (t: ExecutionContext<C>) => any], C>}
+ */
+export const makeExpectUnhandledRejection = ({ test, importMetaUrl }) => {
+  const self = fileURLToPath(importMetaUrl);
+  const gcAndFinalize = makeGcAndFinalize(engineGC);
+
+  if (process.env[AVA_EXPECT_UNHANDLED_REJECTIONS]) {
+    return _expectedUnhandled =>
+      test.macro({
+        title: (_, name, _impl) => SUBTEST_PREFIX + name,
+        exec: async (t, _name, impl) => {
+          await null;
+          try {
+            const result = await impl(t);
+            return result;
+          } finally {
+            await gcAndFinalize();
+          }
+        },
+      });
+  }
+
+  return expectedUnhandled =>
+    test.macro({
+      title: (_, name, _impl) => name,
+      exec: async (t, name, _impl) =>
+        new Promise((resolve, reject) => {
+          const ps = spawn('ava', [self, '-m', SUBTEST_PREFIX + name], {
+            env: {
+              ...process.env,
+              [AVA_EXPECT_UNHANDLED_REJECTIONS]: `${expectedUnhandled}`,
+            },
+            stdio: ['ignore', 'inherit', 'inherit', 'ignore'],
+          });
+
+          ps.on('close', code => {
+            t.is(code, 0, `got exit code ${code}, expected 0 for ${name}`);
+            resolve();
+          });
+          ps.on('error', reject);
+        }),
+    });
+};

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"}