@agoric/internal 0.4.0-upgrade-14-dev-c8f9e7b.0 → 0.4.0-upgrade-16a-dev-fb592e4.0

package/src/lib-chainStorage.d.ts

@@ -1,41 +1,34 @@
 /**
- * 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: (message: StorageMessage) => any, rootPath: string, rootOptions?: {
     sequence?: boolean | undefined;
-} | undefined): {
+} | undefined): import("@endo/exo").Guarded<{
     getPath(): string;
     /**
      * @deprecated use getPath
      * @type {() => Promise<VStorageKey>}
      */
     getStoreKey(): Promise<VStorageKey>;
-    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
-    makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): StorageNode;
-    /** @type {(value: string) => Promise<void>} */
-    setValue(value: string): Promise<void>;
-} & import("@endo/eventual-send").RemotableBrand<{}, {
-    getPath(): string;
     /**
-     * @deprecated use getPath
-     * @type {() => Promise<VStorageKey>}
+     * @type {(
+     *   name: string,
+     *   childNodeOptions?: { sequence?: boolean },
+     * ) => StorageNode}
      */
-    getStoreKey(): Promise<VStorageKey>;
-    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
     makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): StorageNode;
+        sequence?: boolean;
+    }): StorageNode;
     /** @type {(value: string) => Promise<void>} */
     setValue(value: string): Promise<void>;
 }>;
@@ -44,48 +37,39 @@ export function makeChainStorageRoot(handleStorageMessage: (message: StorageMess
  * 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>}
  */
-export function makeStorageNodeChild(storageNodeRef: import('@endo/far').ERef<StorageNode | null>, childName: string): Promise<StorageNode>;
-export function isStreamCell(cell: any): cell is StreamCell<unknown>;
+export function makeStorageNodeChild(storageNodeRef: ERef<StorageNode | null>, childName: string): Promise<StorageNode>;
+export function isStreamCell(cell: any): cell is StreamCell;
 export function assertCapData(data: unknown): asserts data is import("@endo/marshal").CapData<string>;
-export function unmarshalFromVstorage(data: Map<string, string>, key: string, fromCapData: ReturnType<typeof import('@endo/marshal').makeMarshal>['fromCapData'], index?: number | undefined): any;
 /** @type {(name: string) => void} */
 export const assertPathSegment: (name: string) => void;
-export function prepareChainStorageNode(zone: import('@agoric/zone').Zone): (args_0: import("./types.js").Callback<(message: StorageMessage) => any>, args_1: string, args_2?: {
+export function prepareChainStorageNode(zone: import("@agoric/base-zone").Zone): (messenger: import("./types.js").Callback<(message: StorageMessage) => any>, path: string, args_2?: {
     sequence?: boolean | undefined;
-} | undefined) => {
+} | undefined) => import("@endo/exo").Guarded<{
     getPath(): string;
     /**
      * @deprecated use getPath
      * @type {() => Promise<VStorageKey>}
      */
     getStoreKey(): Promise<VStorageKey>;
-    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
-    makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): StorageNode;
-    /** @type {(value: string) => Promise<void>} */
-    setValue(value: string): Promise<void>;
-} & import("@endo/eventual-send").RemotableBrand<{}, {
-    getPath(): string;
     /**
-     * @deprecated use getPath
-     * @type {() => Promise<VStorageKey>}
+     * @type {(
+     *   name: string,
+     *   childNodeOptions?: { sequence?: boolean },
+     * ) => StorageNode}
      */
-    getStoreKey(): Promise<VStorageKey>;
-    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
     makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): StorageNode;
+        sequence?: boolean;
+    }): StorageNode;
     /** @type {(value: string) => Promise<void>} */
     setValue(value: string): Promise<void>;
 }>;
-export function makeSerializeToStorage(storageNode: import('@endo/far').ERef<StorageNode>, marshaller: import('@endo/far').ERef<Marshaller>): (value: unknown) => Promise<void>;
-export type Marshaller = ReturnType<typeof import('@endo/marshal').makeMarshal>;
-export type Unserializer = Pick<Marshaller, 'fromCapData'>;
+export function makeSerializeToStorage(storageNode: ERef<StorageNode>, marshaller: ERef<Marshaller>): (value: PassableCap) => Promise<void>;
+export type Marshaller = ReturnType<typeof import("@endo/marshal").makeMarshal>;
+export type Unserializer = Pick<Marshaller, "fromCapData">;
 /**
  * Defined by vstorageStoreKey in vstorage.go
  */
@@ -105,7 +89,8 @@ export type StreamCell<T = unknown> = {
 /**
  * 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
@@ -117,7 +102,8 @@ export type StorageNode = {
      */
     setValue: (data: string) => Promise<void>;
     /**
-     * the chain storage path at which the node was constructed
+     * the chain storage path at which the node was
+     * constructed
      */
     getPath: () => string;
     /**
@@ -130,26 +116,28 @@ export type StorageNode = {
 };
 export type StoredFacet = {
     /**
-     * the chain storage path at which the node was constructed
+     * the chain storage path at which the
+     * node was constructed
      */
     getPath: () => Promise<string>;
     /**
      * DEPRECATED use getPath
      */
-    getStoreKey: StorageNode['getStoreKey'];
+    getStoreKey: StorageNode["getStoreKey"];
     /**
-     * get the unserializer for the stored data
+     * get the unserializer for the
+     * stored data
      */
     getUnserializer: () => Unserializer;
 };
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  */
-export type StorageGetByPathMessageMethod = 'get' | 'getStoreKey' | 'has' | 'children' | 'entries' | 'values' | 'size';
+export type StorageGetByPathMessageMethod = "get" | "getStoreKey" | "has" | "children" | "entries" | "values" | "size";
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  */
-export type StorageUpdateEntriesMessageMethod = 'set' | 'setWithoutNotify' | 'append';
+export type StorageUpdateEntriesMessageMethod = "set" | "setWithoutNotify" | "append";
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  */
@@ -165,15 +153,17 @@ export type StorageEntry = [path: string, value?: string | null];
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  */
-export type StorageUpdateEntriesMessageArgs = [path: string, value?: string | null | undefined][];
+export type StorageUpdateEntriesMessageArgs = StorageEntry[];
 /**
  * Must match the switch in vstorage.go using `vstorageMessage` type
  */
 export type StorageMessage = {
     method: StorageGetByPathMessageMethod;
-    args: [path: string];
+    args: StorageGetByPathMessageArgs;
 } | {
     method: StorageUpdateEntriesMessageMethod;
     args: StorageUpdateEntriesMessageArgs;
 };
+import type { ERef } from '@endo/far';
+import type { PassableCap } from '@endo/marshal';
 //# sourceMappingURL=lib-chainStorage.d.ts.map

package/src/lib-chainStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib-chainStorage.d.ts","sourceRoot":"","sources":["lib-chainStorage.js"],"names":[],"mappings":"AAoPA;;;;;;;;;;;GAWG;AACH,qEATqB,cAAc,KAAK,GAAG,YAGhC,MAAM;;;;IA1DX;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;;;IAtB3C;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;GAoDhD;AAUD;;;;;;;;GAQG;AACH,qDAJW,OAAO,WAAW,EAAE,IAAI,CAAC,WAAW,QAAE,aACtC,MAAM,GACJ,QAAQ,WAAW,CAAC,CAMhC;AAnOM,mCAHI,GAAG,+BAQ8B;AASrC,oCAHI,OAAO,2DASjB;AAWM,4CALI,IAAI,MAAM,EAAE,MAAM,CAAC,OACnB,MAAM,eACN,WAAW,cAAc,eAAe,EAAE,WAAW,CAAC,CAAC,aAAa,CAAC,mCAwB/E;AAiBD,qCAAqC;AACrC,uCADkB,MAAM,KAAK,IAAI,CAI/B;AAwBK,8CAFI,OAAO,cAAc,EAAE,IAAI,oDAqBiB,cAAc,KAAK,GAAG;;;;IAcvE;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;;;IAtB3C;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;GA0BhD;AA0DM,oDAJI,OAAO,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,cACrC,OAAO,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAC1B,OAAO,KAAK,QAAQ,IAAI,CAAC,CAQ7C;yBAxSa,WAAW,cAAc,eAAe,EAAE,WAAW,CAAC;2BACtD,KAAK,UAAU,EAAE,aAAa,CAAC;;;;;eAM/B,MAAM;iBACN,MAAM;qBACN,MAAM;;;;;;;iBAON,MAAM;YACN,CAAC,EAAE;;;;;;;;;;;;;;;qBAaI,MAAM,KAAK,QAAQ,IAAI,CAAC;;;;aAC/B,MAAM,MAAM;;;;iBACZ,MAAM,QAAQ,WAAW,CAAC;6BAChB,MAAM,YAAY;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,WAAW;;;;;;aA8EhE,MAAM,QAAQ,MAAM,CAAC;;;;iBACrB,WAAW,CAAC,aAAa,CAAC;;;;qBAC1B,MAAM,YAAY;;;;;4CAoBlB,KAAK,GAAG,aAAa,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAE,MAAM;;;;gDACzE,KAAK,GAAG,kBAAkB,GAAG,QAAQ;;;;mCACtC,6BAA6B,GAAG,iCAAiC;;;;0CAChE,CAAC,IAAI,EAAE,MAAM,CAAC;;;;2BACd,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;;;;8CACrC,mDAAc;;;;6BACf;IACZ,MAAU,EAAE,6BAA6B,CAAC;IAC1C,IAAQ,iBAA8B;CAClC,GAAG;IACP,MAAU,EAAE,iCAAiC,CAAC;IAC9C,IAAQ,kCAAkC;CACvC"}
+{"version":3,"file":"lib-chainStorage.d.ts","sourceRoot":"","sources":["lib-chainStorage.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,2DATW,CAAC,OAAO,EAAE,cAAc,KAAK,GAAG,YAGhC,MAAM;;;;IAhEX;;;OAGG;mBADa,OAAO,CAAC,WAAW,CAAC;IASpC;;;;;OAKG;wBAHQ,MAAM,qBACO;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,WAAW;IAYnB,+CAA+C;oBAA5B,MAAM,GAAK,OAAO,CAAC,IAAI,CAAC;GAqDhD;AAWD;;;;;;;;GAQG;AACH,qDAJW,KAAK,WAAW,OAAC,CAAC,aAClB,MAAM,GACJ,OAAO,CAAC,WAAW,CAAC,CAMhC;AAjOM,mCAHI,GAAG,GACD,IAAI,IAAI,UAAU,CAOa;AASrC,oCAHI,OAAO,GACL,QAAQ,IAAI,IAAI,OAAO,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAQnE;AAmBD,qCAAqC;AACrC,gCADW,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAI/B;AAyCK,8CAFI,OAAO,mBAAmB,EAAE,IAAI,uDAwBxB,cAAc,KAAK,GAAG;;;;IAenC;;;OAGG;mBADa,OAAO,CAAC,WAAW,CAAC;IASpC;;;;;OAKG;wBAHQ,MAAM,qBACO;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,WAAW;IAYnB,+CAA+C;oBAA5B,MAAM,GAAK,OAAO,CAAC,IAAI,CAAC;GA0BhD;AA4DM,oDAJI,KAAK,WAAW,CAAC,cACjB,KAAK,UAAU,CAAC,GACd,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAQjD;yBA1Sa,UAAU,CAAC,cAAc,eAAe,EAAE,WAAW,CAAC;2BACtD,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC;;;;;eAM/B,MAAM;iBACN,MAAM;qBACN,MAAM;;;uBAKN,CAAC;;;;iBAED,MAAM;YACN,CAAC,EAAE;;;;;;;;;;;;;;;;cAcH,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;;;;;aAC/B,MAAM,MAAM;;;;iBAEZ,MAAM,OAAO,CAAC,WAAW,CAAC;mBAC1B,CACb,OAAW,EAAE,MAAM,EACnB,OAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAC7B,WAAW;;;;;;;aA6CL,MAAM,OAAO,CAAC,MAAM,CAAC;;;;iBAErB,WAAW,CAAC,aAAa,CAAC;;;;;qBAC1B,MAAM,YAAY;;;;;4CAqBnB,KAAK,GACX,aAAa,GACb,KAAK,GACL,UAAU,GACV,SAAS,GACT,QAAQ,GACR,MAAM;;;;gDAGA,KAAK,GAAG,kBAAkB,GAAG,QAAQ;;;;mCAGrC,6BAA6B,GACnC,iCAAiC;;;;0CAG3B,CAAC,IAAI,EAAE,MAAM,CAAC;;;;2BAEd,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;;;;8CAErC,YAAY,EAAE;;;;6BAEd;IACZ,MAAc,EAAE,6BAA6B,CAAC;IAC9C,IAAY,EAAE,2BAA2B,CAAC;CACnC,GACD;IACN,MAAc,EAAE,iCAAiC,CAAC;IAClD,IAAY,EAAE,+BAA+B,CAAC;CACvC;0BA9Ie,WAAW;iCACJ,eAAe"}

package/src/lib-chainStorage.js

@@ -1,9 +1,15 @@
 // @ts-check
 
 import { E } from '@endo/far';
-import { M, heapZone } from '@agoric/zone';
+import { M } from '@endo/patterns';
+import { makeHeapZone } from '@agoric/base-zone/heap.js';
 import * as cb from './callback.js';
 
+/**
+ * @import {ERef} from '@endo/far';
+ * @import {PassableCap} from '@endo/marshal';
+ */
+
 const { Fail } = assert;
 
 /** @typedef {ReturnType<typeof import('@endo/marshal').makeMarshal>} Marshaller */
@@ -29,7 +35,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 +44,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 +64,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,43 +93,13 @@ 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.
@@ -139,44 +119,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]
@@ -201,7 +202,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);
@@ -240,19 +246,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,
@@ -267,7 +274,8 @@ 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
@@ -279,7 +287,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>}
  */
@@ -292,9 +300,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: () => void;
+//# 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"}