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

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

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["shutdown.js"],"names":[],"mappings":"AAKO;;EA+DN;AAGM,wDAON"}
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["shutdown.js"],"names":[],"mappings":"AAKO;;EA8DN;AAGM,wDAON"}

package/src/node/shutdown.js

@@ -22,7 +22,6 @@ export const makeFreshShutdown = (verbose = true) => {
     process.off('SIGINT', shutdown);
     process.off('SIGTERM', shutdown);
     process.off('beforeExit', shutdown);
-    // eslint-disable-next-line no-use-before-define
     process.off('uncaughtException', uncaughtShutdown);
     verbose && console.error(`Shutting down cleanly...`);
     const shutdowners = [...shutdownThunks.keys()];

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":"AAKA,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

@@ -1,7 +1,6 @@
+import { Fail, q } from '@endo/errors';
 import { E, Far } from '@endo/far';
 
-const { Fail, quote: q } = assert;
-
 const PRIORITY_SENDERS_NAMESPACE_RE = /^[a-zA-Z0-9_-]{1,50}$/;
 
 /** @type {(namespace: string) => string} */
@@ -20,9 +19,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 +50,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/ses-utils.d.ts

@@ -0,0 +1,60 @@
+/** @import {ERef} from '@endo/far' */
+/**
+ * @template T
+ * @typedef {{ [KeyType in keyof T]: T[KeyType] } & {}} Simplify flatten the
+ *   type output to improve type hints shown in editors
+ *   https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+/**
+ * @typedef {(...args: any[]) => any} Callable
+ */
+/**
+ * @template {{}} T
+ * @typedef {{
+ *   [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]>;
+ * }} DeeplyAwaitedObject
+ */
+/**
+ * @template T
+ * @typedef {T extends PromiseLike<any>
+ *     ? Awaited<T>
+ *     : T extends {}
+ *       ? Simplify<DeeplyAwaitedObject<T>>
+ *       : Awaited<T>} DeeplyAwaited
+ */
+/**
+ * A more constrained version of {deeplyFulfilled} for type safety until
+ * https://github.com/endojs/endo/issues/1257 Useful in starting contracts that
+ * need all terms to be fulfilled in order to be durable.
+ *
+ * @type {<T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>}
+ */
+export const deeplyFulfilledObject: <T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>;
+export function PromiseAllOrErrors<T>(items: readonly (T | PromiseLike<T>)[]): Promise<T[]>;
+export function aggregateTryFinally<T>(trier: () => Promise<T>, finalizer: (error?: unknown) => Promise<unknown>): ReturnType<() => Promise<T>>;
+export function withDeferredCleanup<T>(fn: (addCleanup: (fn: (err?: unknown) => Promise<void>) => void) => Promise<T>): ReturnType<(addCleanup: (fn: (err?: unknown) => Promise<void>) => void) => Promise<T>>;
+export function assertAllDefined<T extends Record<string, unknown>>(obj: T): asserts obj is AllDefined<T>;
+export const forever: AsyncIterable<undefined>;
+export function whileTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
+export function untilTrue<T>(produce: () => T): AsyncIterable<Awaited<T>>;
+/** @type {<X, Y>(xs: X[], ys: Y[]) => [X, Y][]} */
+export const zip: <X, Y>(xs: X[], ys: Y[]) => [X, Y][];
+/**
+ * @type {<T extends Record<string, ERef<any>>>(
+ *   obj: T,
+ * ) => Promise<{ [K in keyof T]: Awaited<T[K]> }>}
+ */
+export const allValues: <T extends Record<string, ERef<any>>>(obj: T) => Promise<{ [K in keyof T]: Awaited<T[K]>; }>;
+export function synchronizedTee<T = unknown>(sourceStream: AsyncIterator<T, void, void>, readerCount: number): AsyncGenerator<T, void, void>[];
+/**
+ * flatten the
+ *   type output to improve type hints shown in editors
+ *   https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+export type Simplify<T> = { [KeyType in keyof T]: T[KeyType]; } & {};
+export type Callable = (...args: any[]) => any;
+export type DeeplyAwaitedObject<T extends {}> = { [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]>; };
+export type DeeplyAwaited<T> = T extends PromiseLike<any> ? Awaited<T> : T extends {} ? Simplify<DeeplyAwaitedObject<T>> : Awaited<T>;
+export type AllDefined<T extends Record<string, unknown>> = { [P in keyof T]: Exclude<T[P], undefined>; };
+import type { ERef } from '@endo/far';
+//# sourceMappingURL=ses-utils.d.ts.map

package/src/ses-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ses-utils.d.ts","sourceRoot":"","sources":["ses-utils.js"],"names":[],"mappings":"AAeA,sCAAsC;AAEtC;;;;;GAKG;AAEH;;GAEG;AAEH;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,oCAFU,CAAC,CAAY,SAAF,EAAE,EAAE,gBAAgB,EAAE,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAKxE;AAsBK,mCAJM,CAAC,SACH,SAAS,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,GAC7B,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBxB;AAQM,oCALM,CAAC,SACH,MAAM,OAAO,CAAC,CAAC,CAAC,aAChB,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GACnC,UAAU,OAFN,OAAO,CAAC,CAAC,CAAC,CAEG,CAY3B;AAWI,oCANM,CAAC,MACH,CACN,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,KACvD,OAAO,CAAC,CAAC,CAAC,GACL,UAAU,cAFN,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,KACvD,OAAO,CAAC,CAAC,CAAC,CACS,CAmB1B;AAgBM,iCALgC,CAAC,SAA1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAE,OAC3B,CAAC,GACC,QAAQ,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAaxC;AAQD,+CAAoD;AAS7C,0BANM,CAAC,WACH,MAAM,CAAC,GAGL,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAYlC;AASG,0BANM,CAAC,WACH,MAAM,CAAC,GAGL,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAelC;AAEJ,mDAAmD;AACnD,kBADW,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CACsB;AAErE;;;;GAIG;AACH,wBAJU,CAAC,CAAmC,SAAzB,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,CAAC,EACzC,GAAG,EAAE,CAAC,KACH,OAAO,CAAC,GAAG,CAAY,IAAP,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,CAAC,CAMhD;AAWK,gCAJO,CAAC,0BACJ,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,eAC5B,MAAM,mCA8GhB;;;;;;qBAvUY,CAAC,IACD,GAAG,OAAkB,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAE,GAAG,EAAE;uBAMzC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;gCAIlB,CAAC,SAAN,EAAI,IACJ,GACP,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACnE;0BAIS,CAAC,IACD,CAAC,SAAS,WAAW,CAAC,GAAG,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,GACV,CAAC,SAAS,EAAE,GACV,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC;uBAmGkB,CAAC,SAA1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAE,IACzB,GAAG,CAAY,IAAP,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAE;0BA9HjC,WAAW"}

package/src/ses-utils.js

@@ -0,0 +1,346 @@
+// @ts-check
+// @jessie-check
+/**
+ * @file Utility functions that are dependent upon a hardened environment,
+ *   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 { makePromiseKit } from '@endo/promise-kit';
+import { makeQueue } from '@endo/stream';
+import { asyncGenerate } from 'jessie.js';
+
+const { fromEntries, keys, values } = Object;
+
+/** @import {ERef} from '@endo/far' */
+
+/**
+ * @template T
+ * @typedef {{ [KeyType in keyof T]: T[KeyType] } & {}} Simplify flatten the
+ *   type output to improve type hints shown in editors
+ *   https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+
+/**
+ * @typedef {(...args: any[]) => any} Callable
+ */
+
+/**
+ * @template {{}} T
+ * @typedef {{
+ *   [K in keyof T]: T[K] extends Callable ? T[K] : DeeplyAwaited<T[K]>;
+ * }} DeeplyAwaitedObject
+ */
+
+/**
+ * @template T
+ * @typedef {T extends PromiseLike<any>
+ *     ? Awaited<T>
+ *     : T extends {}
+ *       ? Simplify<DeeplyAwaitedObject<T>>
+ *       : Awaited<T>} DeeplyAwaited
+ */
+
+/**
+ * A more constrained version of {deeplyFulfilled} for type safety until
+ * https://github.com/endojs/endo/issues/1257 Useful in starting contracts that
+ * need all terms to be fulfilled in order to be durable.
+ *
+ * @type {<T extends {}>(unfulfilledTerms: T) => Promise<DeeplyAwaited<T>>}
+ */
+export const deeplyFulfilledObject = async obj => {
+  isObject(obj) || Fail`param must be an object`;
+  return deeplyFulfilled(obj);
+};
+
+/**
+ * Tolerate absence of AggregateError in e.g. xsnap.
+ *
+ * @type {(errors: Error[], message?: string, options?: object) => Error}
+ */
+const makeAggregateError =
+  typeof AggregateError === 'function'
+    ? (errors, message, options) => AggregateError(errors, message, options)
+    : (errors, message, options) => {
+        return makeError(message ?? 'multiple errors', undefined, {
+          ...options,
+          errors,
+        });
+      };
+
+/**
+ * @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 makeAggregateError(errors);
+    }
+  });
+};
+
+/**
+ * @template T
+ * @param {() => Promise<T>} trier
+ * @param {(error?: unknown) => Promise<unknown>} finalizer
+ * @returns {ReturnType<trier>}
+ */
+export const aggregateTryFinally = async (trier, finalizer) =>
+  trier().then(
+    async result => finalizer().then(() => result),
+    async tryError =>
+      finalizer(tryError)
+        .then(
+          () => tryError,
+          finalizeError => makeAggregateError([tryError, finalizeError]),
+        )
+        .then(error => Promise.reject(error)),
+  );
+
+/**
+ * Run a function with the ability to defer last-in-first-out cleanup callbacks.
+ *
+ * @template T
+ * @param {(
+ *   addCleanup: (fn: (err?: unknown) => Promise<void>) => void,
+ * ) => Promise<T>} fn
+ * @returns {ReturnType<fn>}
+ */
+export const withDeferredCleanup = async fn => {
+  /** @type {((err?: unknown) => unknown)[]} */
+  const cleanupsLIFO = [];
+  /** @type {(cleanup: (err?: unknown) => unknown) => void} */
+  const addCleanup = cleanup => {
+    cleanupsLIFO.unshift(cleanup);
+  };
+  /** @type {(err?: unknown) => Promise<void>} */
+  const finalizer = async err => {
+    // Run each cleanup in its own isolated stack.
+    const cleanupResults = cleanupsLIFO.map(async cleanup => {
+      await null;
+      return cleanup(err);
+    });
+    await PromiseAllOrErrors(cleanupResults);
+  };
+  return aggregateTryFinally(() => fn(addCleanup), finalizer);
+};
+
+/**
+ * @template {Record<string, unknown>} T
+ * @typedef {{ [P in keyof T]: Exclude<T[P], undefined> }} AllDefined
+ */
+
+/**
+ * Concise way to check values are available from object literal shorthand.
+ * Throws error message to specify the missing values.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} obj
+ * @returns {asserts obj is AllDefined<T>}
+ * @throws if any value in the object entries is not defined
+ */
+export const assertAllDefined = obj => {
+  const missing = [];
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === undefined) {
+      missing.push(key);
+    }
+  }
+  if (missing.length > 0) {
+    Fail`missing ${q(missing)}`;
+  }
+};
+
+/** @type {IteratorResult<undefined, never>} */
+const notDone = harden({ done: false, value: undefined });
+
+/** @type {IteratorResult<never, void>} */
+const alwaysDone = harden({ done: true, value: undefined });
+
+export const forever = asyncGenerate(() => notDone);
+
+/**
+ * @template T
+ * @param {() => T} produce The value of `await produce()` is used for its
+ *   truthiness vs falsiness. IOW, it is coerced to a boolean so the caller need
+ *   not bother doing this themselves.
+ * @returns {AsyncIterable<Awaited<T>>}
+ */
+export const whileTrue = produce =>
+  asyncGenerate(async () => {
+    const value = await produce();
+    if (!value) {
+      return alwaysDone;
+    }
+    return harden({
+      done: false,
+      value,
+    });
+  });
+
+/**
+ * @template T
+ * @param {() => T} produce The value of `await produce()` is used for its
+ *   truthiness vs falsiness. IOW, it is coerced to a boolean so the caller need
+ *   not bother doing this themselves.
+ * @returns {AsyncIterable<Awaited<T>>}
+ */
+export const untilTrue = produce =>
+  asyncGenerate(async () => {
+    const value = await produce();
+    if (value) {
+      return harden({
+        done: true,
+        value,
+      });
+    }
+    return harden({
+      done: false,
+      value,
+    });
+  });
+
+/** @type {<X, Y>(xs: X[], ys: Y[]) => [X, Y][]} */
+export const zip = (xs, ys) => harden(xs.map((x, i) => [x, ys[+i]]));
+
+/**
+ * @type {<T extends Record<string, ERef<any>>>(
+ *   obj: T,
+ * ) => Promise<{ [K in keyof T]: Awaited<T[K]> }>}
+ */
+export const allValues = async obj => {
+  const resolved = await Promise.all(values(obj));
+  // @ts-expect-error cast
+  return harden(fromEntries(zip(keys(obj), resolved)));
+};
+
+/**
+ * A tee implementation where all readers are synchronized with each other. They
+ * all consume the source stream in lockstep, and any one returning or throwing
+ * early will affect the others.
+ *
+ * @template [T=unknown]
+ * @param {AsyncIterator<T, void, void>} sourceStream
+ * @param {number} readerCount
+ */
+export const synchronizedTee = (sourceStream, readerCount) => {
+  /** @type {IteratorReturnResult<void> | undefined} */
+  let doneResult;
+
+  /**
+   * @typedef {IteratorResult<
+   *   (value: PromiseLike<IteratorResult<T>>) => void
+   * >} QueuePayload
+   */
+  /** @type {import('@endo/stream').AsyncQueue<QueuePayload>[]} */
+  const queues = [];
+
+  /** @returns {Promise<void>} */
+  const pullNext = async () => {
+    const requests = await Promise.allSettled(queues.map(queue => queue.get()));
+    const rejections = [];
+    /** @type {Array<(value: PromiseLike<IteratorResult<T>>) => void>} */
+    const resolvers = [];
+    let done = false;
+    for (const settledResult of requests) {
+      if (settledResult.status === 'rejected') {
+        rejections.push(settledResult.reason);
+      } else {
+        done ||= !!settledResult.value.done;
+        resolvers.push(settledResult.value.value);
+      }
+    }
+    /** @type {Promise<IteratorResult<T>>} */
+    let result;
+    if (doneResult) {
+      result = Promise.resolve(doneResult);
+    } else if (rejections.length) {
+      const error = makeError(X`Teed stream threw`);
+      annotateError(error, X`Teed rejections: ${rejections}`);
+      result =
+        sourceStream.throw?.(error) ||
+        Promise.resolve(sourceStream.return?.()).then(() =>
+          Promise.reject(error),
+        );
+    } else if (done) {
+      result =
+        sourceStream.return?.() ||
+        Promise.resolve({ done: true, value: undefined });
+    } else {
+      result = sourceStream.next();
+    }
+    result.then(
+      r => {
+        if (r.done) {
+          doneResult = r;
+        }
+      },
+      () => {
+        doneResult = { done: true, value: undefined };
+      },
+    );
+    for (const resolve of resolvers) {
+      resolve(result);
+    }
+    return pullNext();
+  };
+
+  const readers = Array.from({ length: readerCount }).map(() => {
+    /** @type {import('@endo/stream').AsyncQueue<QueuePayload>} */
+    const queue = makeQueue();
+    queues.push(queue);
+
+    /** @type {AsyncGenerator<T, void, void>} */
+    const reader = harden({
+      async next() {
+        /**
+         * @type {import('@endo/promise-kit').PromiseKit<
+         *   IteratorResult<T>
+         * >}
+         */
+        const { promise, resolve } = makePromiseKit();
+        queue.put({ value: resolve, done: false });
+        return promise;
+      },
+      async return() {
+        /**
+         * @type {import('@endo/promise-kit').PromiseKit<
+         *   IteratorResult<T>
+         * >}
+         */
+        const { promise, resolve } = makePromiseKit();
+        queue.put({ value: resolve, done: true });
+        return promise;
+      },
+      async throw(reason) {
+        const rejection = Promise.reject(reason);
+        queue.put(rejection);
+        return rejection;
+      },
+      // eslint-disable-next-line no-restricted-globals
+      [Symbol.asyncIterator]() {
+        return reader;
+      },
+      // eslint-disable-next-line no-restricted-globals
+      async [Symbol.asyncDispose]() {
+        await reader.return();
+      },
+    });
+    return reader;
+  });
+
+  void pullNext();
+  return readers;
+};