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

package/src/ses-utils.js

@@ -5,15 +5,41 @@
  *   either directly or indirectly (e.g. by @endo imports).
  */
 
-import { q, Fail, makeError, annotateError, X } from '@endo/errors';
-import { deeplyFulfilled, isObject } from '@endo/marshal';
+import { objectMap } from '@endo/common/object-map.js';
+import { objectMetaMap } from '@endo/common/object-meta-map.js';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+import { q, b, Fail, makeError, annotateError, X } from '@endo/errors';
+import { deeplyFulfilled, isPrimitive } from '@endo/pass-style';
 import { makePromiseKit } from '@endo/promise-kit';
 import { makeQueue } from '@endo/stream';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore TS7016 The 'jessie.js' library may need to update its package.json or typings
 import { asyncGenerate } from 'jessie.js';
+import { logLevels } from './js-utils.js';
+
+/**
+ * @import {LimitedConsole} from './js-utils.js';
+ * @import {AsyncQueue} from '@endo/stream';
+ * @import {PromiseKit} from '@endo/promise-kit';
+ */
+
+/** @import {ERef} from '@endo/far'; */
+/** @import {RemotableBrand} from '@endo/eventual-send'; */
+/** @import {Primitive, RemotableObject} from '@endo/pass-style'; */
+/** @import {Permit, Attenuated} from './types.js'; */
+
+export { objectMap, objectMetaMap, fromUniqueEntries };
 
 const { fromEntries, keys, values } = Object;
 
-/** @import {ERef} from '@endo/far' */
+/** @param {(level: string) => (...args: unknown[]) => void} makeLogger */
+export const makeLimitedConsole = makeLogger => {
+  const limitedConsole = /** @type {any} */ (
+    fromEntries(logLevels.map(level => [level, makeLogger(level)]))
+  );
+  return /** @type {LimitedConsole} */ (harden(limitedConsole));
+};
+harden(makeLimitedConsole);
 
 /**
  * @template T
@@ -37,9 +63,11 @@ const { fromEntries, keys, values } = Object;
  * @template T
  * @typedef {T extends PromiseLike<any>
  *     ? Awaited<T>
- *     : T extends {}
- *       ? Simplify<DeeplyAwaitedObject<T>>
- *       : Awaited<T>} DeeplyAwaited
+ *     : T extends RemotableBrand<any, any> | RemotableObject
+ *       ? T
+ *       : T extends {}
+ *         ? Simplify<DeeplyAwaitedObject<T>>
+ *         : Awaited<T>} DeeplyAwaited
  */
 
 /**
@@ -50,7 +78,7 @@ const { fromEntries, keys, values } = Object;
  * @type {<T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>}
  */
 export const deeplyFulfilledObject = async obj => {
-  isObject(obj) || Fail`param must be an object`;
+  !isPrimitive(obj) || Fail`param must be an object`;
   return deeplyFulfilled(obj);
 };
 
@@ -69,6 +97,101 @@ const makeAggregateError =
         });
       };
 
+/**
+ * Assert that a string has a prefix, and return the part that follows it.
+ *
+ * @param {string} prefix
+ * @param {string} str
+ * @returns {string}
+ */
+export const stripPrefix = (prefix, str) => {
+  str.startsWith(prefix) || Fail`${str} is missing prefix ${q(prefix)}`;
+  return str.slice(prefix.length);
+};
+
+/**
+ * Throw an error with an own "code" data property, supporting identification
+ * without parsing `message`. Note that such errors are not Passable and thus
+ * cannot appear inside a Passable structure, and even at top level the "code"
+ * property will be silently dropped by marshalling.
+ *
+ * @template {string} Code
+ * @param {Parameters<typeof makeError>[0]} details
+ * @param {Code} code
+ * @param {Parameters<typeof makeError>[2] & {
+ *   constructor?: Parameters<typeof makeError>[1];
+ * }} [opts]
+ */
+export const throwErrorCode = (details, code, opts) => {
+  const err = makeError(details, opts?.constructor, {
+    ...opts,
+    sanitize: false,
+  });
+  Object.defineProperty(err, 'code', { value: code, enumerable: true });
+  harden(err);
+  throw err;
+};
+
+/**
+ * Synchronusly invoke a function with the opportunity to handle any error
+ * similarly to a Promise `catch` callback (e.g., substituting a non-error
+ * returned value or throwing a possibly-new error). This is useful for (among
+ * other things) replacing generic error messages with specific ones (as in
+ * {@see tryJsonParse}).
+ *
+ * @template {(...args: any[]) => any} F
+ * @template [U=ReturnType<F>]
+ * @param {F} fn to invoke
+ * @param {(err: Error) => U} transformError callback to receive any error from
+ *   invoking `fn` and either return a substitute value or throw a potentially
+ *   new error
+ * @param {Parameters<F>} args for `fn`
+ * @returns {ReturnType<F> | U}
+ */
+export const tryNow = (fn, transformError, ...args) => {
+  try {
+    return fn(...args);
+  } catch (err) {
+    try {
+      return transformError(err);
+    } catch (newErr) {
+      // Try to associate `err` with `newErr`.
+      if (!newErr.cause) {
+        const desc = {
+          value: err,
+          configurable: true,
+          enumerable: false,
+          writable: true,
+        };
+        if (!Reflect.defineProperty(newErr, 'cause', desc)) {
+          assert.note(newErr, err.message);
+        }
+      }
+      throw newErr;
+    }
+  }
+};
+
+/**
+ * Parse JSON text, or handle an error by e.g. substituting a default value or
+ * replacing it with one bearing a non-generic message.
+ *
+ * @param {string} jsonText
+ * @param {string | ((err: Error) => unknown)} onError an error message or
+ *   callback
+ */
+export const tryJsonParse = (jsonText, onError) => {
+  const transformError =
+    typeof onError === 'function'
+      ? onError
+      : err => Fail([`${onError}: ${err.message} for input `, ''], jsonText);
+  return tryNow(() => {
+    const type = typeof jsonText;
+    type === 'string' || Fail`Input must be a string, not ${b(type)}`;
+    return JSON.parse(jsonText);
+  }, transformError);
+};
+
 /**
  * @template T
  * @param {readonly (T | PromiseLike<T>)[]} items
@@ -163,6 +286,61 @@ export const assertAllDefined = obj => {
   }
 };
 
+/**
+ * Attenuate `specimen` to only properties allowed by `permit`.
+ *
+ * @template T
+ * @template {Permit<T>} P
+ * @param {T} specimen
+ * @param {P} permit
+ * @param {<U, SubP extends Permit<U>>(attenuation: U, permit: SubP) => U} [transform]
+ *   used to replace the results of recursive picks (but not blanket permits)
+ * @returns {Attenuated<T, P>}
+ */
+export const attenuate = (specimen, permit, transform = x => x) => {
+  // Fast-path for no attenuation.
+  if (permit === true || typeof permit === 'string') {
+    return /** @type {Attenuated<T, P>} */ (specimen);
+  }
+
+  /** @type {string[]} */
+  const path = [];
+  /**
+   * @template SubT
+   * @template {Exclude<Permit<SubT>, Primitive>} SubP
+   * @type {(specimen: SubT, permit: SubP) => Attenuated<SubT, SubP>}
+   */
+  const extract = (subSpecimen, subPermit) => {
+    if (subPermit === null || typeof subPermit !== 'object') {
+      throw path.length === 0
+        ? Fail`invalid permit: ${q(permit)}`
+        : Fail`invalid permit at path ${q(path)}: ${q(subPermit)}`;
+    } else if (subSpecimen === null || typeof subSpecimen !== 'object') {
+      throw path.length === 0
+        ? Fail`specimen must be an object for permit ${q(permit)}`
+        : Fail`specimen at path ${q(path)} must be an object for permit ${q(subPermit)}`;
+    }
+    const picks = Object.entries(subPermit).map(([subKey, deepPermit]) => {
+      if (!Object.hasOwn(subSpecimen, subKey)) {
+        throw Fail`specimen is missing path ${q(path.concat(subKey))}`;
+      }
+      const deepSpecimen = Reflect.get(subSpecimen, subKey);
+      if (deepPermit === true || typeof deepPermit === 'string') {
+        return [subKey, deepSpecimen];
+      }
+      path.push(subKey);
+      const extracted = extract(/** @type {any} */ (deepSpecimen), deepPermit);
+      const entry = [subKey, extracted];
+      path.pop();
+      return entry;
+    });
+    return transform(Object.fromEntries(picks), subPermit);
+  };
+
+  // @ts-expect-error cast
+  return extract(specimen, permit);
+};
+
 /** @type {IteratorResult<undefined, never>} */
 const notDone = harden({ done: false, value: undefined });
 
@@ -244,7 +422,7 @@ export const synchronizedTee = (sourceStream, readerCount) => {
    *   (value: PromiseLike<IteratorResult<T>>) => void
    * >} QueuePayload
    */
-  /** @type {import('@endo/stream').AsyncQueue<QueuePayload>[]} */
+  /** @type {AsyncQueue<QueuePayload>[]} */
   const queues = [];
 
   /** @returns {Promise<void>} */
@@ -298,7 +476,7 @@ export const synchronizedTee = (sourceStream, readerCount) => {
   };
 
   const readers = Array.from({ length: readerCount }).map(() => {
-    /** @type {import('@endo/stream').AsyncQueue<QueuePayload>} */
+    /** @type {AsyncQueue<QueuePayload>} */
     const queue = makeQueue();
     queues.push(queue);
 
@@ -306,9 +484,7 @@ export const synchronizedTee = (sourceStream, readerCount) => {
     const reader = harden({
       async next() {
         /**
-         * @type {import('@endo/promise-kit').PromiseKit<
-         *   IteratorResult<T>
-         * >}
+         * @type {PromiseKit<IteratorResult<T>>}
          */
         const { promise, resolve } = makePromiseKit();
         queue.put({ value: resolve, done: false });
@@ -316,9 +492,7 @@ export const synchronizedTee = (sourceStream, readerCount) => {
       },
       async return() {
         /**
-         * @type {import('@endo/promise-kit').PromiseKit<
-         *   IteratorResult<T>
-         * >}
+         * @type {PromiseKit<IteratorResult<T>>}
          */
         const { promise, resolve } = makePromiseKit();
         queue.put({ value: resolve, done: true });

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

@@ -9,8 +9,21 @@ export const defaultMarshaller: {
     serialize: import("@endo/marshal").ToCapData<string>;
     unserialize: import("@endo/marshal").FromCapData<string>;
 };
+export namespace defaultSerializer {
+    let parse: (text: string) => unknown;
+    let stringify: (obj: any) => string;
+}
 export const slotStringUnserialize: (capData: any) => any;
-export function makeFakeStorageKit(rootPath: string, rootOptions?: Parameters<typeof makeChainStorageRoot>[2]): {
+export function makeAsyncQueue<T>(): {
+    enqueue: (data: T) => void;
+    iterable: {
+        [Symbol.asyncIterator](): AsyncGenerator<Awaited<T> | undefined, void, unknown>;
+    };
+    cancel: () => boolean;
+};
+export function makeFakeStorageKit(rootPath: string, rootOptions?: Parameters<typeof makeChainStorageRoot>[2], { eachMessage }?: {
+    eachMessage?: (m: StorageMessage) => void;
+}): {
     rootNode: import("@endo/exo").Guarded<{
         getPath(): string;
         getStoreKey(): Promise<VStorageKey>;
@@ -20,17 +33,19 @@ export function makeFakeStorageKit(rootPath: string, rootOptions?: Parameters<ty
         setValue(value: string): Promise<void>;
     }>;
     data: Map<string, string>;
+    updateNewCellBlockHeight: (blockHeight?: number) => void;
+    getValues: (path: string) => string[];
     messages: StorageMessage[];
-    toStorage: ((message: StorageMessage) => string | number | any[] | {
+    toStorage: ((message: StorageMessage) => string | number | true | any[] | {
         storeName: string;
         storeSubkey: string;
-    } | null | undefined) & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, (message: StorageMessage) => string | number | any[] | {
+    } | null) & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, (message: StorageMessage) => string | number | true | any[] | {
         storeName: string;
         storeSubkey: string;
-    } | null | undefined>;
+    } | null>;
 };
 export function makeMockChainStorageRoot(): MockChainStorageRoot;
-export function documentStorageSchema(t: import("ava").ExecutionContext<unknown>, storage: MockChainStorageRoot | FakeStorageKit, opts: ({
+export function documentStorageSchema(t: ExecutionContext<unknown>, storage: MockChainStorageRoot | FakeStorageKit, opts: ({
     note: string;
 } | {
     node: string;
@@ -38,7 +53,9 @@ export function documentStorageSchema(t: import("ava").ExecutionContext<unknown>
 }) & ({
     pattern: string;
     replacement: string;
-} | {})): Promise<void>;
+} | {}) & {
+    showValue?: (v: string) => unknown;
+}): Promise<void>;
 export type FakeStorageKit = ReturnType<typeof makeFakeStorageKit>;
 export type MockChainStorageRootMethods = {
     /**
@@ -52,7 +69,8 @@ export type MockChainStorageRootMethods = {
 };
 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 { StorageNode } from './lib-chainStorage.js';
+import type { ExecutionContext } from 'ava';
 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":"AAwBO,yCAHI,MAAM,UACN,MAAM,6GAGC;AAElB;;;GAGG;AACH;;;;;EAEG;AA4CH,8CAtBuB,GAAG,KAAK,GAAG,CAsB+B;AAU1D,6CAHI,MAAM,gBACN,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC;;;;;oBA2GjD,CAAA;;;;UAEiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;;0BAjFxB,cAAc;;;0JAAd,cAAc;;;;EAqF7B;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;6BAtFa,UAAU,CAAC,OAAO,kBAAkB,CAAC;;;;;;;;aAIrC,CACT,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,UAAU,EACvB,KAAK,CAAC,EAAE,MAAM,KACX,OAAO;UAKD,MAAM,MAAM,EAAE;;mCAEd,WAAW,GAAG,2BAA2B;qCAjNJ,uBAAuB;iCAMF,uBAAuB;oCAAvB,uBAAuB;gCAAvB,uBAAuB"}
+{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AA0BO,yCAHI,MAAM,UACN,MAAM,6GAGC;AAElB;;;GAGG;AACH;;;;;EAEG;;eAMU,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO;mBAEzB,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM;;AA8CjC,8CAtBuB,GAAG,KAAK,GAAG,CAsB+B;AAa1D,+BAFM,CAAC;oBASA,CAAC;;;;;EA6Bd;AAWM,6CAJI,MAAM,gBACN,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAC1C;IAAE,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAA;CAAE;;;;;oBAwD3B,CAAC;;;;UA4FT,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;;sBAd3B,MAAM,KACJ,MAAM,EAAE;;0BA/FP,cAAc;;;8IAAd,cAAc;;;;EAkH7B;AAoBM,4CADO,oBAAoB,CA2BjC;AAUM,yCAPI,iBAAiB,OAAO,CAAC,WACzB,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,GAAG;IAChD,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC,iBAkDL;6BAtGa,UAAU,CAAC,OAAO,kBAAkB,CAAC;;;;;;;;aAIrC,CACT,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,UAAU,EACvB,KAAK,CAAC,EAAE,MAAM,KACX,OAAO;UAKD,MAAM,MAAM,EAAE;;mCAEd,WAAW,GAAG,2BAA2B;qCAxTJ,uBAAuB;oCAOU,uBAAuB;iCAAvB,uBAAuB;sCACxE,KAAK;gCAD4C,uBAAuB"}

package/src/storage-test-utils.js

@@ -2,15 +2,17 @@
 import { Fail } from '@endo/errors';
 import { Far } from '@endo/far';
 import { makeMarshal, Remotable } from '@endo/marshal';
-import { unmarshalFromVstorage } from './marshal.js';
 import { makeTracer } from './debug.js';
+import { NonNullish } from './errors.js';
 import { isStreamCell, makeChainStorageRoot } from './lib-chainStorage.js';
+import { unmarshalFromVstorage } from './marshal/board-client-utils.js';
 import { bindAllMethods } from './method-tools.js';
 import { eventLoopIteration } from './testing-utils.js';
 
 /**
  * @import {TotalMap} from './types.js';
- * @import {Marshaller, StorageEntry, StorageMessage, StorageNode} from './lib-chainStorage.js';
+ * @import {Marshaller, StorageEntry, StorageMessage, StorageNode, StreamCell} from './lib-chainStorage.js';
+ * @import {ExecutionContext} from 'ava';
  */
 
 const trace = makeTracer('StorTU', false);
@@ -33,6 +35,16 @@ export const defaultMarshaller = makeMarshal(undefined, slotToRemotable, {
   serializeBodyFormat: 'smallcaps',
 });
 
+/**
+ * Serialize/deserialize functions using {@link defaultMarshaller}
+ */
+export const defaultSerializer = {
+  /** @type {(text: string) => unknown} */
+  parse: txt => defaultMarshaller.fromCapData(JSON.parse(txt)),
+  /** @type {(obj: any) => string} */
+  stringify: obj => JSON.stringify(defaultMarshaller.toCapData(obj)),
+};
+
 /**
  * A deserializer which produces slot strings instead of Remotables, so if `a =
  * Far('iface')`, and serializing `{ a }` into `capData` assigned it slot
@@ -77,6 +89,55 @@ const makeSlotStringUnserialize = () => {
 };
 export const slotStringUnserialize = makeSlotStringUnserialize();
 
+/**
+ * @example to iterate over storage messages
+ *
+ * ```js
+ * const q = makeAsyncQueue<StorageMessage>();
+ * const storage = makeFakeStorageKit('published', undefined, { eachMessage: q.enqueue });
+ * for (const message of q.iterable) { ... }
+ * ```
+ *
+ * @template T
+ */
+export const makeAsyncQueue = () => {
+  /** @type {T[]} */
+  const queue = [];
+  /** @type {null | ((r: undefined) => void)} */
+  let resolve = null;
+  let done = false;
+
+  /** @param {T} data */
+  const enqueue = data => {
+    queue.push(data);
+    if (resolve) {
+      resolve(undefined);
+      resolve = null;
+    }
+  };
+
+  let alreadyIterating = false;
+  const iterable = {
+    async *[Symbol.asyncIterator]() {
+      assert(!alreadyIterating, `AsyncQueue is already iterating`);
+      alreadyIterating = true;
+      await null;
+      while (!done) {
+        if (queue.length === 0) {
+          await new Promise(r => (resolve = r));
+        }
+
+        while (queue.length > 0) {
+          yield queue.shift();
+        }
+      }
+    },
+  };
+
+  const cancel = () => (done = true);
+  return harden({ enqueue, iterable, cancel });
+};
+
 /**
  * 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`
@@ -84,11 +145,24 @@ export const slotStringUnserialize = makeSlotStringUnserialize();
  *
  * @param {string} rootPath
  * @param {Parameters<typeof makeChainStorageRoot>[2]} [rootOptions]
+ * @param {{ eachMessage?: (m: StorageMessage) => void }} [spyOpts]
  */
-export const makeFakeStorageKit = (rootPath, rootOptions) => {
+export const makeFakeStorageKit = (
+  rootPath,
+  rootOptions,
+  { eachMessage } = {},
+) => {
   const resolvedOptions = { sequence: true, ...rootOptions };
   /** @type {TotalMap<string, string>} */
   const data = new Map();
+  let currentBlockHeight = 0;
+
+  const updateNewCellBlockHeight = (blockHeight = currentBlockHeight + 1) => {
+    blockHeight > currentBlockHeight ||
+      Fail`blockHeight ${blockHeight} must be greater than ${currentBlockHeight}`;
+    currentBlockHeight = blockHeight;
+  };
+
   /** @param {string} prefix */
   const getChildEntries = prefix => {
     assert(prefix.endsWith('.'));
@@ -114,6 +188,7 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
     /** @param {StorageMessage} message */
     message => {
       messages.push(message);
+      eachMessage?.(message);
       switch (message.method) {
         case 'getStoreKey': {
           const [key] = message.args;
@@ -147,7 +222,7 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
               data.delete(key);
             }
           }
-          break;
+          return true;
         }
         case 'append': {
           trace('toStorage append', message);
@@ -155,8 +230,10 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
           const newEntries = message.args;
           for (const [key, value] of newEntries) {
             value != null || Fail`attempt to append with no value`;
-            // In the absence of block boundaries, everything goes in a single StreamCell.
-            const oldVal = data.get(key);
+
+            /** @type {string | undefined} */
+            let oldVal = data.get(key);
+            /** @type {StreamCell | undefined} */
             let streamCell;
             if (oldVal != null) {
               try {
@@ -165,17 +242,26 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
               } catch (_err) {
                 streamCell = undefined;
               }
+              // StreamCells reset at block boundaries.
+              if (
+                streamCell &&
+                Number(streamCell.blockHeight) !== currentBlockHeight
+              ) {
+                streamCell = undefined;
+                oldVal = undefined;
+              }
             }
+
             if (streamCell === undefined) {
               streamCell = {
-                blockHeight: '0',
+                blockHeight: String(currentBlockHeight),
                 values: oldVal != null ? [oldVal] : [],
               };
             }
             streamCell.values.push(value);
             data.set(key, JSON.stringify(streamCell));
           }
-          break;
+          return true;
         }
         case 'size':
           // Intentionally incorrect because it counts non-child descendants,
@@ -189,10 +275,27 @@ export const makeFakeStorageKit = (rootPath, rootOptions) => {
     },
   );
   const rootNode = makeChainStorageRoot(toStorage, rootPath, resolvedOptions);
+
+  /**
+   * Get the values at a sequence node
+   *
+   * @param {string} path
+   * @returns {string[]}
+   */
+  const getValues = path => {
+    assert(resolvedOptions.sequence);
+    const nodeData = data.get(path);
+    assert(nodeData, `no data at path ${path}`);
+    const wrapper = JSON.parse(nodeData);
+    return wrapper.values;
+  };
+
   return {
     rootNode,
-    // eslint-disable-next-line object-shorthand
+
     data: /** @type {Map<string, string>} */ (data),
+    updateNewCellBlockHeight,
+    getValues,
     messages,
     toStorage,
   };
@@ -234,9 +337,7 @@ export const makeMockChainStorageRoot = () => {
     getBody: (path, marshaller = defaultMarshaller, index = -1) => {
       data.size || Fail`no data in storage`;
       /**
-       * @type {ReturnType<
-       *   typeof import('@endo/marshal').makeMarshal
-       * >['fromCapData']}
+       * @type {ReturnType<typeof makeMarshal>['fromCapData']}
        */
       const fromCapData = (...args) =>
         Reflect.apply(marshaller.fromCapData, marshaller, args);
@@ -247,33 +348,51 @@ export const makeMockChainStorageRoot = () => {
 };
 
 /**
- * @param {import('ava').ExecutionContext<unknown>} t
+ * @param {ExecutionContext<unknown>} t
  * @param {MockChainStorageRoot | FakeStorageKit} storage
  * @param {({ note: string } | { node: string; owner: string }) &
- *   ({ pattern: string; replacement: string } | {})} opts
+ *   ({ pattern: string; replacement: string } | {}) & {
+ *     showValue?: (v: string) => unknown;
+ *   }} opts
  */
 export const documentStorageSchema = async (t, storage, opts) => {
   // chainStorage publication is unsynchronized
   await eventLoopIteration();
 
+  const getLast = (/** @type {string} */ cell) =>
+    JSON.parse(cell).values.at(-1) || assert.fail();
+  const { showValue = s => s } = opts;
+  /** @type {(d: Map<string, string>, k: string) => unknown} */
+  const getBodyDefault = (d, k) => showValue(getLast(NonNullish(d.get(k))));
+
   const [keys, getBody] =
     'keys' in storage
       ? [storage.keys(), (/** @type {string} */ k) => storage.getBody(k)]
-      : [storage.data.keys(), (/** @type {string} */ k) => storage.data.get(k)];
+      : [
+          storage.data.keys(),
+          (/** @type {string} */ k) => getBodyDefault(storage.data, k),
+        ];
 
   const { pattern, replacement } =
     'pattern' in opts
       ? opts
       : { pattern: 'mockChainStorageRoot.', replacement: 'published.' };
-  const illustration = [...keys].sort().map(
+
+  const pruned = [...keys]
+    .sort()
+    .filter(
+      'node' in opts
+        ? key =>
+            key
+              .replace(pattern, replacement)
+              .startsWith(`published.${opts.node}`)
+        : _entry => true,
+    );
+
+  const illustration = pruned.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
@@ -283,5 +402,5 @@ export const documentStorageSchema = async (t, storage, opts) => {
 The example below illustrates the schema of the data published there.
 
 See also board marshalling conventions (_to appear_).`;
-  t.snapshot(pruned, note + boilerplate);
+  t.snapshot(illustration, note + boilerplate);
 };

package/src/tagged.d.ts

@@ -1,4 +1,7 @@
-/** @file adapted from https://raw.githubusercontent.com/sindresorhus/type-fest/main/source/opaque.d.ts */
+/** @file adapted from https://raw.githubusercontent.com/sindresorhus/type-fest/main/source/tagged.d.ts */
+
+// different name to avoid confusion with pass-style "tagged"
+export { Tagged as TypeTag };
 
 declare const tag: unique symbol;
 

package/src/testing-utils.js

@@ -28,7 +28,7 @@ const stringOrTag = value => {
 };
 /**
  * @param {MapStore} store
- * @returns {object} tree of the contents of the storeÂ
+ * @returns {object} tree of the contents of the store
  */
 export const inspectMapStore = store => {
   /** @type {Record<string, unknown>} */

package/src/tmpDir.d.ts

@@ -0,0 +1,2 @@
+export function makeTempDirFactory(tmp: Pick<typeof import("tmp"), "dirSync">): (prefix?: string) => [dirName: string, cleanup: () => void];
+//# sourceMappingURL=tmpDir.d.ts.map

package/src/tmpDir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmpDir.d.ts","sourceRoot":"","sources":["tmpDir.js"],"names":[],"mappings":"AAMO,wCAFI,IAAI,CAAC,oBAAa,EAAE,SAAS,CAAC,aAGlB,MAAM,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,CASvE"}

package/src/tmpDir.js

@@ -0,0 +1,17 @@
+/**
+ * Create a `tmpDir` function that synchronously creates a temporary directory
+ * and a function for deleting it along with any added contents.
+ *
+ * @param {Pick<import('tmp'), 'dirSync'>} tmp
+ */
+export const makeTempDirFactory = tmp => {
+  /** @type {(prefix?: string) => [dirName: string, cleanup: () => void]} */
+  const tmpDir = prefix => {
+    const { name, removeCallback } = tmp.dirSync({
+      prefix,
+      unsafeCleanup: true,
+    });
+    return [name, removeCallback];
+  };
+  return tmpDir;
+};

package/src/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["tokens.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;2BAEc,KAAK,GAAG,KAAK;AAA3B,4CAA4C;AAE5C;;;GAGG;AACH,yBAAkB"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["tokens.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;2BAEc,KAAK,GAAG,KAAK;AAA3B,4CAA4C;AAE5C;;;GAGG;AACH,mBAAY,KAAK,CAAC"}