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

package/src/node/buffer-line-transform.js

@@ -5,16 +5,19 @@ import { Transform } from 'node:stream';
 
 /**
  * @typedef {object} BufferLineTransformOptions
- * @property {Buffer | string | number} [break] line break matcher for Buffer.indexOf() (default: 10)
- * @property {BufferEncoding} [breakEncoding] if break is a string, the encoding to use
+ * @property {Buffer | string | number} [break] line break matcher for
+ *   Buffer.indexOf() (default: 10)
+ * @property {BufferEncoding} [breakEncoding] if break is a string, the encoding
+ *   to use
  */
 
 export default class BufferLineTransform extends Transform {
   /**
-   * The BufferLineTransform is reading String or Buffer content from a Readable stream
-   * and writing each line as a Buffer in object mode
+   * The BufferLineTransform is reading String or Buffer content from a Readable
+   * stream and writing each line as a Buffer in object mode
    *
-   * @param {import('node:stream').TransformOptions & BufferLineTransformOptions} [options]
+   * @param {import('node:stream').TransformOptions &
+   *   BufferLineTransformOptions} [options]
    */
   constructor(options) {
     const {
@@ -37,15 +40,15 @@ export default class BufferLineTransform extends Transform {
     }
     this._breakLength = breakLength;
 
-    /** @type {Array<Buffer>} */
+    /** @type {Buffer[]} */
     this._chunks = [];
   }
 
   /**
-   * @override
    * @param {any} chunk
    * @param {BufferEncoding | 'buffer'} encoding
    * @param {import('node:stream').TransformCallback} cb
+   * @override
    */
   _transform(chunk, encoding, cb) {
     try {
@@ -96,8 +99,8 @@ export default class BufferLineTransform extends Transform {
   }
 
   /**
-   * @override
    * @param {import('node:stream').TransformCallback} cb
+   * @override
    */
   _flush(cb) {
     if (this._chunks.length) {

package/src/node/fs-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-stream.d.ts","sourceRoot":"","sources":["fs-stream.js"],"names":[],"mappings":"AAQO,sCAHI,OAAO,IAAI,EAAE,UAAU,GAAG,OAAO,IAAI,EAAE,WAAW,GAChD,QAAQ,IAAI,CAAC,CAgCtB;AAQG,6CADK,MAAM,GAAG,SAAS,GAAG,IAAI;;;;eA2DpC;6BA5Da,YAAY,QAAQ,WAAW,yBAAyB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"fs-stream.d.ts","sourceRoot":"","sources":["fs-stream.js"],"names":[],"mappings":"AAOO,sCAHI,OAAO,IAAI,EAAE,UAAU,GAAG,OAAO,IAAI,EAAE,WAAW,GAChD,OAAO,CAAC,IAAI,CAAC,CAgCtB;AAQG,6CADK,MAAM,GAAG,SAAS,GAAG,IAAI;;;;eA2DpC;6BA5Da,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC"}

package/src/node/fs-stream.js

@@ -1,9 +1,8 @@
 import { createWriteStream } from 'node:fs';
 import { open } from 'node:fs/promises';
-import { makeAggregateError } from '../utils.js';
 
 /**
- * @param {import("fs").ReadStream | import("fs").WriteStream} stream
+ * @param {import('fs').ReadStream | import('fs').WriteStream} stream
  * @returns {Promise<void>}
  */
 export const fsStreamReady = stream =>
@@ -78,7 +77,7 @@ export const makeFsStreamWriter = async filePath => {
         Promise.reject(
           written.then(
             () => err,
-            writtenError => makeAggregateError([err, writtenError]),
+            writtenError => AggregateError([err, writtenError]),
           ),
         ),
     );

package/src/node/utils.d.ts

@@ -0,0 +1,9 @@
+export function PromiseAllOrErrors<T>(items: readonly (T | PromiseLike<T>)[]): Promise<T[]>;
+/**
+ * @type {<T>(
+ *   trier: () => Promise<T>,
+ *   finalizer: (error?: unknown) => Promise<void>,
+ * ) => Promise<T>}
+ */
+export const aggregateTryFinally: <T>(trier: () => Promise<T>, finalizer: (error?: unknown) => Promise<void>) => Promise<T>;
+//# sourceMappingURL=utils.d.ts.map

package/src/node/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAYO,mCAJM,CAAC,SACH,SAAS,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,GAC7B,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBxB;AAED;;;;;GAKG;AACH,kCALU,CAAC,CAAC,EACX,KAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,SAAa,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,KAC1C,OAAO,CAAC,CAAC,CAAC,CAYd"}

package/src/node/utils.js

@@ -0,0 +1,46 @@
+// @ts-check
+// @jessie-check
+
+// These tools seem cross platform, but they rely on AggregateError in the error
+// handling path, which is currently not available in xsnap
+import 'node:process';
+
+/**
+ * @template T
+ * @param {readonly (T | PromiseLike<T>)[]} items
+ * @returns {Promise<T[]>}
+ */
+export const PromiseAllOrErrors = async items => {
+  return Promise.allSettled(items).then(results => {
+    const errors = /** @type {PromiseRejectedResult[]} */ (
+      results.filter(({ status }) => status === 'rejected')
+    ).map(result => result.reason);
+    if (!errors.length) {
+      return /** @type {PromiseFulfilledResult<T>[]} */ (results).map(
+        result => result.value,
+      );
+    } else if (errors.length === 1) {
+      throw errors[0];
+    } else {
+      throw AggregateError(errors);
+    }
+  });
+};
+
+/**
+ * @type {<T>(
+ *   trier: () => Promise<T>,
+ *   finalizer: (error?: unknown) => Promise<void>,
+ * ) => Promise<T>}
+ */
+export const aggregateTryFinally = async (trier, finalizer) =>
+  trier().then(
+    async result => finalizer().then(() => result),
+    async tryError =>
+      finalizer(tryError)
+        .then(
+          () => tryError,
+          finalizeError => AggregateError([tryError, finalizeError]),
+        )
+        .then(error => Promise.reject(error)),
+  );

package/src/priority-senders.d.ts

@@ -13,7 +13,7 @@ export function makePrioritySendersManager(sendersNode: ERef<import("./lib-chain
      * @returns {Promise<void>}
      */
     remove: (rawNamespace: string, address: string) => Promise<void>;
-} & import("@endo/eventual-send").RemotableBrand<{}, {
+} & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
     /**
      * @param {string} rawNamespace
      * @param {string} address

package/src/priority-senders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"priority-senders.d.ts","sourceRoot":"","sources":["priority-senders.js"],"names":[],"mappings":"AAMA,4CAA4C;AAC5C,mDADuB,MAAM,KAAK,MAAM,CAMtC;AAQK;IAoCH;;;;OAIG;wBAHQ,MAAM,WACN,MAAM,KACJ,QAAQ,IAAI,CAAC;IAe1B;;;;OAIG;2BAHQ,MAAM,WACN,MAAM,KACJ,QAAQ,IAAI,CAAC;;IArB1B;;;;OAIG;wBAHQ,MAAM,WACN,MAAM,KACJ,QAAQ,IAAI,CAAC;IAe1B;;;;OAIG;2BAHQ,MAAM,WACN,MAAM,KACJ,QAAQ,IAAI,CAAC;GAuB7B;qCAGa,WAAW,iCAAiC,CAAC"}
+{"version":3,"file":"priority-senders.d.ts","sourceRoot":"","sources":["priority-senders.js"],"names":[],"mappings":"AAMA,4CAA4C;AAC5C,uCADW,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAMtC;AAQK,wDAFI,IAAI,CAAC,OAAO,uBAAuB,EAAE,WAAW,CAAC;IA0CxD;;;;OAIG;wBAHQ,MAAM,WACN,MAAM,KACJ,OAAO,CAAC,IAAI,CAAC;IAe1B;;;;OAIG;2BAHQ,MAAM,WACN,MAAM,KACJ,OAAO,CAAC,IAAI,CAAC;;IArB1B;;;;OAIG;wBAHQ,MAAM,WACN,MAAM,KACJ,OAAO,CAAC,IAAI,CAAC;IAe1B;;;;OAIG;2BAHQ,MAAM,WACN,MAAM,KACJ,OAAO,CAAC,IAAI,CAAC;GAuB7B;qCAGa,UAAU,CAAC,OAAO,0BAA0B,CAAC"}

package/src/priority-senders.js

@@ -20,9 +20,13 @@ harden(normalizeSenderNamespace);
  */
 export const makePrioritySendersManager = sendersNode => {
   /**
-   * address to tuple with storage node and set of namespaces that requested priority
+   * address to tuple with storage node and set of namespaces that requested
+   * priority
    *
-   * @type {Map<string, readonly [node: StorageNode, namespaces: Set<string>]>}
+   * @type {Map<
+   *   string,
+   *   readonly [node: StorageNode, namespaces: Set<string>]
+   * >}
    */
   const addressRecords = new Map();
 
@@ -47,7 +51,7 @@ export const makePrioritySendersManager = sendersNode => {
     const node = await E(sendersNode).makeChildNode(address, {
       sequence: false,
     });
-    /** @type {readonly [ node: StorageNode, namespaces: Set<string> ]} */
+    /** @type {readonly [node: StorageNode, namespaces: Set<string>]} */
     const r = [node, new Set()];
     addressRecords.set(address, r);
     return r;

package/src/queue.d.ts

@@ -1,2 +1,2 @@
-export function makeWithQueue(): <T extends any[], R>(inner: (...args: T) => Promise<R>) => (...args: T) => Promise<R>;
+export function makeWithQueue(): <T extends (...args: any[]) => any>(inner: T) => (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 //# sourceMappingURL=queue.d.ts.map

package/src/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["queue.js"],"names":[],"mappings":"AAQO,uHAiDN"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["queue.js"],"names":[],"mappings":"AAQO,kCAwBkC,CAAC,SAA3B,CAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAI,SAC3B,CAAC,eAIC,UAAU,CAAC,CAAC,CAAC,KACX,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAkB/C"}

package/src/queue.js

@@ -3,8 +3,8 @@
 import { makePromiseKit } from '@endo/promise-kit';
 
 /**
- * Return a function that can wrap an async or sync method, but
- * ensures only one of them (in order) is running at a time.
+ * Return a function that can wrap an async or sync method, but ensures only one
+ * of them (in order) is running at a time.
  */
 export const makeWithQueue = () => {
   const queue = [];
@@ -16,7 +16,7 @@ export const makeWithQueue = () => {
     }
     const [thunk, resolve, reject] = queue[0];
     // Run the thunk in a new turn.
-    Promise.resolve()
+    void Promise.resolve()
       .then(thunk)
       // Resolve or reject our caller with the thunk's value.
       .then(resolve, reject)
@@ -30,14 +30,13 @@ export const makeWithQueue = () => {
   };
 
   /**
-   * @template {any[]} T
-   * @template R
-   * @param {(...args: T) => Promise<R>} inner
+   * @template {(...args: any[]) => any} T
+   * @param {T} inner
    */
   return function withQueue(inner) {
     /**
-     * @param {T} args
-     * @returns {Promise<R>}
+     * @param {Parameters<T>} args
+     * @returns {Promise<Awaited<ReturnType<T>>>}
      */
     return function queueCall(...args) {
       // Curry the arguments into the inner function, and

package/src/scratch.d.ts

@@ -6,7 +6,7 @@ export default function makeScratchPad(): {
     keys: () => Promise<any[]>;
     list: () => Promise<any[]>;
     set: (keyP: any, objP: any) => Promise<any>;
-} & import("@endo/eventual-send").RemotableBrand<{}, {
+} & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
     delete: (keyP: any) => Promise<void>;
     get: (keyP: any) => Promise<any>;
     lookup: (...path: any[]) => any;

package/src/scratch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["scratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgDC;yBACa,WAAW,qBAAqB,CAAC"}
+{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["scratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgDC;yBACa,UAAU,CAAC,OAAO,cAAc,CAAC"}

package/src/storage-test-utils.d.ts

@@ -1,101 +1,63 @@
-export function slotToRemotable(_slotId: string, iface?: string): import("@endo/eventual-send").RemotableBrand<{}, {}>;
+export function slotToRemotable(_slotId: string, iface?: string): import("@endo/marshal").RemotableObject<string> & import("@endo/eventual-send").RemotableBrand<{}, {}>;
 /**
- * A basic marshaller whose unserializer produces Remotables. It can
- * only serialize plain data, not Remotables.
+ * A basic marshaller whose unserializer produces Remotables. It can only
+ * serialize plain data, not Remotables.
  */
 export const defaultMarshaller: {
-    toCapData: import("@endo/marshal/src/marshal.js").ToCapData<string>;
-    fromCapData: import("@endo/marshal/src/marshal.js").FromCapData<string>;
-    serialize: import("@endo/marshal/src/marshal.js").ToCapData<string>;
-    unserialize: import("@endo/marshal/src/marshal.js").FromCapData<string>;
+    toCapData: import("@endo/marshal").ToCapData<string>;
+    fromCapData: import("@endo/marshal").FromCapData<string>;
+    serialize: import("@endo/marshal").ToCapData<string>;
+    unserialize: import("@endo/marshal").FromCapData<string>;
 };
-export function slotStringUnserialize(capData: any): any;
-export function makeFakeStorageKit(rootPath: string, rootOptions?: [handleStorageMessage: (message: import("./lib-chainStorage.js").StorageMessage) => any, rootPath: string, rootOptions?: {
-    sequence?: boolean | undefined;
-} | undefined][2]): {
-    rootNode: {
+export const slotStringUnserialize: (capData: any) => any;
+export function makeFakeStorageKit(rootPath: string, rootOptions?: Parameters<typeof makeChainStorageRoot>[2]): {
+    rootNode: import("@endo/exo").Guarded<{
         getPath(): string;
-        getStoreKey(): Promise<import("./lib-chainStorage.js").VStorageKey>;
+        getStoreKey(): Promise<VStorageKey>;
         makeChildNode(name: string, childNodeOptions?: {
-            sequence?: boolean | undefined;
-        } | undefined): import("./lib-chainStorage.js").StorageNode;
-        setValue(value: string): Promise<void>;
-    } & import("@endo/eventual-send").RemotableBrand<{}, {
-        getPath(): string;
-        getStoreKey(): Promise<import("./lib-chainStorage.js").VStorageKey>;
-        makeChildNode(name: string, childNodeOptions?: {
-            sequence?: boolean | undefined;
-        } | undefined): import("./lib-chainStorage.js").StorageNode;
+            sequence?: boolean;
+        }): StorageNode;
         setValue(value: string): Promise<void>;
     }>;
     data: Map<string, string>;
-    messages: import("./lib-chainStorage.js").StorageMessage[];
-    toStorage: (message: import('../src/lib-chainStorage.js').StorageMessage) => string | number | any[] | {
+    messages: StorageMessage[];
+    toStorage: (message: StorageMessage) => string | number | any[] | {
         storeName: string;
         storeSubkey: string;
     } | null | undefined;
 };
-export function makeMockChainStorageRoot(): {
-    /**
-     * Defaults to deserializing slot references into plain Remotable
-     * objects having the specified interface name (as from `Far(iface)`),
-     * but can accept a different marshaller for producing Remotables
-     * that e.g. embed the slot string in their iface name.
-     *
-     * @param {string} path
-     * @param {import('./lib-chainStorage.js').Marshaller} marshaller
-     * @param {number} [index]
-     * @returns {unknown}
-     */
-    getBody: (path: string, marshaller?: import('./lib-chainStorage.js').Marshaller, index?: number | undefined) => unknown;
-    keys: () => string[];
-    getPath(): string;
-    getStoreKey(): Promise<import("./lib-chainStorage.js").VStorageKey>;
-    makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): import("./lib-chainStorage.js").StorageNode;
-    setValue(value: string): Promise<void>;
-} & import("@endo/eventual-send").RemotableBrand<{}, {
-    /**
-     * Defaults to deserializing slot references into plain Remotable
-     * objects having the specified interface name (as from `Far(iface)`),
-     * but can accept a different marshaller for producing Remotables
-     * that e.g. embed the slot string in their iface name.
-     *
-     * @param {string} path
-     * @param {import('./lib-chainStorage.js').Marshaller} marshaller
-     * @param {number} [index]
-     * @returns {unknown}
-     */
-    getBody: (path: string, marshaller?: import('./lib-chainStorage.js').Marshaller, index?: number | undefined) => unknown;
-    keys: () => string[];
-    getPath(): string;
-    getStoreKey(): Promise<import("./lib-chainStorage.js").VStorageKey>;
-    makeChildNode(name: string, childNodeOptions?: {
-        sequence?: boolean | undefined;
-    } | undefined): import("./lib-chainStorage.js").StorageNode;
-    setValue(value: string): Promise<void>;
-}>;
+export function makeMockChainStorageRoot(): MockChainStorageRoot;
+export function documentStorageSchema(t: import("ava").ExecutionContext<unknown>, storage: MockChainStorageRoot | FakeStorageKit, opts: ({
+    note: string;
+} | {
+    node: string;
+    owner: string;
+}) & ({
+    pattern: string;
+    replacement: string;
+} | {})): Promise<void>;
 /**
- * A map corresponding with a total function such that `get(key)`
- * is assumed to always succeed.
+ * A map corresponding with a total function such that `get(key)` is assumed to
+ * always succeed.
  */
-export type TotalMap<K, V> = {
-    [Symbol.iterator]: () => IterableIterator<[K, V]>;
-    [Symbol.toStringTag]: string;
-    entries: () => IterableIterator<[K, V]>;
-    keys: () => IterableIterator<K>;
-    values: () => IterableIterator<V>;
-    has: (key: K) => boolean;
-    size: number;
-    set: (key: K, value: V) => Map<K, V>;
-    clear: () => void;
-    delete: (key: K) => boolean;
-    forEach: (callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any) => void;
-} & {
+export type TotalMap<K, V> = { [k in Exclude<keyof Map<K, V>, "get">]: Map<K, V>[k]; } & {
     get: (key: K) => V;
 };
 export type TotalMapFrom<T> = T extends Map<infer K, infer V> ? TotalMap<K, V> : never;
 export type FakeStorageKit = ReturnType<typeof makeFakeStorageKit>;
-export type MockChainStorageRoot = ReturnType<typeof makeMockChainStorageRoot>;
+export type MockChainStorageRootMethods = {
+    /**
+     *   Defaults to deserializing slot references into plain Remotable objects having
+     *   the specified interface name (as from `Far(iface)`), but can accept a
+     *   different marshaller for producing Remotables that e.g. embed the slot
+     *   string in their iface name.
+     */
+    getBody: (path: string, marshaller?: Marshaller, index?: number) => unknown;
+    keys: () => string[];
+};
+export type MockChainStorageRoot = StorageNode & MockChainStorageRootMethods;
+import { makeChainStorageRoot } from './lib-chainStorage.js';
+import type { StorageNode } from './lib-chainStorage.js';
+import type { StorageMessage } from './lib-chainStorage.js';
+import type { Marshaller } from './lib-chainStorage.js';
 //# sourceMappingURL=storage-test-utils.d.ts.map

package/src/storage-test-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAkCO,yCAHI,MAAM,UACN,MAAM,wDAGC;AAElB;;;GAGG;AACH;;;;;EAEG;AAsBW,+CAAU,GAAG,GAAK,GAAG,CAAA;AAgC5B,6CAHI,MAAM,gBACN;;eAAwC,CAAC,CAAC;;;;;;;;;;;;;;;;;;yBAyBvC,OAAO,4BAA4B,EAAE,cAAc;;;;EAoFhE;AAIM;IAIH;;;;;;;;;;OAUG;oBAJQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,iCAExC,OAAO;;;;;;;;;IATpB;;;;;;;;;;OAUG;oBAJQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,iCAExC,OAAO;;;;;;;;GAWvB;;;;;;;;;;;;;;;;;;eApNiF,CAAC,KAAK,CAAC;;;6BA0L3E,WAAY,yBAAyB,CAAC;mCA2BtC,WAAW,+BAA+B,CAAC"}
+{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAsCO,yCAHI,MAAM,UACN,MAAM,0GAGC;AAElB;;;GAGG;AACH;;;;;EAEG;AA4CH,8CAtBuB,GAAG,KAAK,GAAG,CAsB+B;AAU1D,6CAHI,MAAM,gBACN,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC;;;;;oBAkGX,CAAC;;;;UAOtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;;yBAhF1B,cAAc;;;;EAoF3B;AAoBM,4CADO,oBAAoB,CA6BjC;AAQM,yCALI,OAAO,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,WACvC,oBAAoB,GAAG,cAAc,QACrC,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,CAAK;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,EAAE,CAAC,iBAkCnD;;;;;qBAnRY,CAAC,EAAE,CAAC,IACJ,GAAG,CAAoC,IAA/B,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,GAAG;IACvE,GAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;CACpB;yBAGS,CAAC,IACD,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK;6BAsLvD,UAAU,CAAC,OAAO,kBAAkB,CAAC;;;;;;;;aAIrC,CACb,IAAQ,EAAE,MAAM,EAChB,UAAc,CAAC,EAAE,UAAU,EAC3B,KAAS,CAAC,EAAE,MAAM,KACX,OAAO;UAKD,MAAM,MAAM,EAAE;;mCAEd,WAAW,GAAG,2BAA2B;qCA5NJ,uBAAuB;iCAKF,uBAAuB;oCAAvB,uBAAuB;gCAAvB,uBAAuB"}

package/src/storage-test-utils.js

@@ -1,24 +1,28 @@
 // @ts-check
 import { Far } from '@endo/far';
 import { makeMarshal, Remotable } from '@endo/marshal';
+import { unmarshalFromVstorage } from './marshal.js';
 import { makeTracer } from './debug.js';
-import {
-  isStreamCell,
-  makeChainStorageRoot,
-  unmarshalFromVstorage,
-} from './lib-chainStorage.js';
+import { isStreamCell, makeChainStorageRoot } from './lib-chainStorage.js';
 import { bindAllMethods } from './method-tools.js';
+import { eventLoopIteration } from './testing-utils.js';
+
+/**
+ * @import {Marshaller, StorageEntry, StorageMessage, StorageNode} from './lib-chainStorage.js';
+ */
 
 const { Fail } = assert;
 
 const trace = makeTracer('StorTU', false);
 
 /**
- * A map corresponding with a total function such that `get(key)`
- * is assumed to always succeed.
+ * A map corresponding with a total function such that `get(key)` is assumed to
+ * always succeed.
  *
  * @template K, V
- * @typedef {{[k in Exclude<keyof Map<K, V>, 'get'>]: Map<K, V>[k]} & {get: (key: K) => V}} TotalMap
+ * @typedef {{ [k in Exclude<keyof Map<K, V>, 'get'>]: Map<K, V>[k] } & {
+ *   get: (key: K) => V;
+ * }} TotalMap
  */
 /**
  * @template T
@@ -26,8 +30,8 @@ const trace = makeTracer('StorTU', false);
  */
 
 /**
- * A convertSlotToVal function that produces basic Remotables. Assumes
- * that all slots are Remotables (i.e. none are Promises).
+ * A convertSlotToVal function that produces basic Remotables. Assumes that all
+ * slots are Remotables (i.e. none are Promises).
  *
  * @param {string} _slotId
  * @param {string} iface
@@ -36,34 +40,34 @@ export const slotToRemotable = (_slotId, iface = 'Remotable') =>
   Remotable(iface);
 
 /**
- * A basic marshaller whose unserializer produces Remotables. It can
- * only serialize plain data, not Remotables.
+ * A basic marshaller whose unserializer produces Remotables. It can only
+ * serialize plain data, not Remotables.
  */
 export const defaultMarshaller = makeMarshal(undefined, slotToRemotable, {
   serializeBodyFormat: 'smallcaps',
 });
 
 /**
- * A deserializer which produces slot strings instead of Remotables,
- * so if `a = Far('iface')`, and serializing `{ a }` into `capData`
- * assigned it slot `board123`, then `slotStringUnserialize(capData)`
- * would produce `{ a: 'board123' }`.
+ * A deserializer which produces slot strings instead of Remotables, so if `a =
+ * Far('iface')`, and serializing `{ a }` into `capData` assigned it slot
+ * `board123`, then `slotStringUnserialize(capData)` would produce `{ a:
+ * 'board123' }`.
  *
  * This may be useful for display purposes.
  *
  * Limitations:
- *  * it cannot handle Symbols (registered or well-known)
- *  * it can handle BigInts, but serialized data that contains a
- *     particular unusual string will be unserialized into a BigInt by
- *     mistake
- *  * it cannot handle Promises, NaN, +/- Infinity, undefined, or
- *    other non-JSONable JavaScript values
+ *
+ * - it cannot handle Symbols (registered or well-known)
+ * - it can handle BigInts, but serialized data that contains a particular unusual
+ *   string will be unserialized into a BigInt by mistake
+ * - it cannot handle Promises, NaN, +/- Infinity, undefined, or other
+ *   non-JSONable JavaScript values
  */
 const makeSlotStringUnserialize = () => {
-  /** @type { (slot: string, iface: string) => any } */
+  /** @type {(slot: string, iface: string) => any} */
   const identitySlotToValFn = (slot, _) => Far('unk', { toJSON: () => slot });
   const { fromCapData } = makeMarshal(undefined, identitySlotToValFn);
-  /** @type { (capData: any) => any } */
+  /** @type {(capData: any) => any} */
   const unserialize = capData =>
     JSON.parse(
       JSON.stringify(fromCapData(capData), (_, val) => {
@@ -88,9 +92,9 @@ const makeSlotStringUnserialize = () => {
 export const slotStringUnserialize = makeSlotStringUnserialize();
 
 /**
- * For testing, creates a chainStorage root node over an in-memory map
- * and exposes both the map and the sequence of received messages.
- * The `sequence` option defaults to true.
+ * For testing, creates a chainStorage root node over an in-memory map and
+ * exposes both the map and the sequence of received messages. The `sequence`
+ * option defaults to true.
  *
  * @param {string} rootPath
  * @param {Parameters<typeof makeChainStorageRoot>[2]} [rootOptions]
@@ -116,10 +120,10 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
     }
     return childEntries;
   };
-  /** @type {import('../src/lib-chainStorage.js').StorageMessage[]} */
+  /** @type {StorageMessage[]} */
   const messages = [];
-  /** @param {import('../src/lib-chainStorage.js').StorageMessage} message */
-  // eslint-disable-next-line consistent-return
+  /** @param {StorageMessage} message */
+
   const toStorage = message => {
     messages.push(message);
     switch (message.method) {
@@ -146,7 +150,7 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
       case 'set':
       case 'setWithoutNotify': {
         trace('toStorage set', message);
-        /** @type {import('../src/lib-chainStorage.js').StorageEntry[]} */
+        /** @type {StorageEntry[]} */
         const newEntries = message.args;
         for (const [key, value] of newEntries) {
           if (value != null) {
@@ -159,7 +163,7 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
       }
       case 'append': {
         trace('toStorage append', message);
-        /** @type {import('../src/lib-chainStorage.js').StorageEntry[]} */
+        /** @type {StorageEntry[]} */
         const newEntries = message.args;
         for (const [key, value] of newEntries) {
           value != null || Fail`attempt to append with no value`;
@@ -204,26 +208,46 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
   };
 };
 harden(makeFakeStorageKit);
-/** @typedef {ReturnType< typeof makeFakeStorageKit>} FakeStorageKit */
+/** @typedef {ReturnType<typeof makeFakeStorageKit>} FakeStorageKit */
+
+/**
+ * @typedef MockChainStorageRootMethods
+ * @property {(
+ *   path: string,
+ *   marshaller?: Marshaller,
+ *   index?: number,
+ * ) => unknown} getBody
+ *   Defaults to deserializing slot references into plain Remotable objects having
+ *   the specified interface name (as from `Far(iface)`), but can accept a
+ *   different marshaller for producing Remotables that e.g. embed the slot
+ *   string in their iface name.
+ * @property {() => string[]} keys
+ */
+/** @typedef {StorageNode & MockChainStorageRootMethods} MockChainStorageRoot */
 
+/** @returns {MockChainStorageRoot} */
 export const makeMockChainStorageRoot = () => {
   const { rootNode, data } = makeFakeStorageKit('mockChainStorageRoot');
   return Far('mockChainStorage', {
     ...bindAllMethods(rootNode),
     /**
-     * Defaults to deserializing slot references into plain Remotable
-     * objects having the specified interface name (as from `Far(iface)`),
-     * but can accept a different marshaller for producing Remotables
-     * that e.g. embed the slot string in their iface name.
+     * Defaults to deserializing slot references into plain Remotable objects
+     * having the specified interface name (as from `Far(iface)`), but can
+     * accept a different marshaller for producing Remotables that e.g. embed
+     * the slot string in their iface name.
      *
      * @param {string} path
-     * @param {import('./lib-chainStorage.js').Marshaller} marshaller
+     * @param {Marshaller} marshaller
      * @param {number} [index]
      * @returns {unknown}
      */
     getBody: (path, marshaller = defaultMarshaller, index = -1) => {
       data.size || Fail`no data in storage`;
-      /** @type {ReturnType<typeof import('@endo/marshal').makeMarshal>['fromCapData']} */
+      /**
+       * @type {ReturnType<
+       *   typeof import('@endo/marshal').makeMarshal
+       * >['fromCapData']}
+       */
       const fromCapData = (...args) =>
         Reflect.apply(marshaller.fromCapData, marshaller, args);
       return unmarshalFromVstorage(data, path, fromCapData, index);
@@ -231,4 +255,43 @@ export const makeMockChainStorageRoot = () => {
     keys: () => [...data.keys()],
   });
 };
-/** @typedef {ReturnType<typeof makeMockChainStorageRoot>} MockChainStorageRoot */
+
+/**
+ * @param {import('ava').ExecutionContext<unknown>} t
+ * @param {MockChainStorageRoot | FakeStorageKit} storage
+ * @param {({ note: string } | { node: string; owner: string }) &
+ *   ({ pattern: string; replacement: string } | {})} opts
+ */
+export const documentStorageSchema = async (t, storage, opts) => {
+  // chainStorage publication is unsynchronized
+  await eventLoopIteration();
+
+  const [keys, getBody] =
+    'keys' in storage
+      ? [storage.keys(), (/** @type {string} */ k) => storage.getBody(k)]
+      : [storage.data.keys(), (/** @type {string} */ k) => storage.data.get(k)];
+
+  const { pattern, replacement } =
+    'pattern' in opts
+      ? opts
+      : { pattern: 'mockChainStorageRoot.', replacement: 'published.' };
+  const illustration = [...keys].sort().map(
+    /** @type {(k: string) => [string, unknown]} */
+    key => [key.replace(pattern, replacement), getBody(key)],
+  );
+  const pruned = illustration.filter(
+    'node' in opts
+      ? ([key, _]) => key.startsWith(`published.${opts.node}`)
+      : _entry => true,
+  );
+
+  const note =
+    'note' in opts
+      ? opts.note
+      : `Under "published", the "${opts.node}" node is delegated to ${opts.owner}.`;
+  const boilerplate = `
+The example below illustrates the schema of the data published there.
+
+See also board marshalling conventions (_to appear_).`;
+  t.snapshot(pruned, note + boilerplate);
+};