@agoric/async-flow 0.1.1-dev-16095c5.0

package/src/convert.js

@@ -0,0 +1,131 @@
+import { Fail, X, annotateError, makeError, q } from '@endo/errors';
+import { throwLabeled } from '@endo/common/throw-labeled.js';
+import {
+  getErrorConstructor,
+  getTag,
+  isObject,
+  makeTagged,
+  passStyleOf,
+} from '@endo/pass-style';
+import { isVow } from '@agoric/vow/src/vow-utils.js';
+import { objectMap } from '@endo/common/object-map.js';
+
+const makeConvert = (convertRemotable, convertPromiseOrVow, convertError) => {
+  const convertRecur = (specimen, label) => {
+    // Open code the synchronous part of applyLabelingError, because
+    // we need to preserve returned promise identity.
+    // TODO switch to Richard Gibson's suggestion for a better way
+    // to keep track of the error labeling.
+    // See https://github.com/endojs/endo/pull/1795#issuecomment-1756093032
+    if (label === undefined) {
+      // eslint-disable-next-line no-use-before-define
+      return innerConvert(specimen);
+    }
+    try {
+      // eslint-disable-next-line no-use-before-define
+      return innerConvert(specimen);
+    } catch (err) {
+      throwLabeled(err, label);
+    }
+  };
+
+  const innerConvert = specimen => {
+    if (!isObject(specimen)) {
+      return specimen;
+    }
+    const passStyle = passStyleOf(specimen);
+    switch (passStyle) {
+      case 'copyArray': {
+        return specimen.map((element, i) => convertRecur(element, i));
+      }
+      case 'copyRecord': {
+        return objectMap(specimen, (value, name) => convertRecur(value, name));
+      }
+      case 'tagged': {
+        if (isVow(specimen)) {
+          return convertPromiseOrVow(specimen);
+        }
+        const tag = getTag(specimen);
+        const { payload } = specimen;
+        return makeTagged(tag, convertRecur(payload, `${tag} payload`));
+      }
+      case 'error': {
+        return convertError(specimen);
+      }
+      case 'remotable': {
+        return convertRemotable(specimen);
+      }
+      case 'promise': {
+        return convertPromiseOrVow(specimen);
+      }
+      default: {
+        throw Fail`unexpected passStyle ${q(passStyle)}`;
+      }
+    }
+  };
+
+  /**
+   * @param {Passable} specimen
+   * @param {string} [label]
+   */
+  const convert = (specimen, label = undefined) =>
+    convertRecur(harden(specimen), label);
+  return harden(convert);
+};
+
+export const makeConvertKit = (
+  bijection,
+  makeGuestForHostRemotable,
+  makeGuestForHostVow,
+) => {
+  const guestToHost = makeConvert(
+    gRem => {
+      if (bijection.hasGuest(gRem)) {
+        return bijection.guestToHost(gRem);
+      }
+      throw Fail`cannot yet send guest remotables ${gRem}`;
+    },
+    gProm => {
+      if (bijection.hasGuest(gProm)) {
+        return bijection.guestToHost(gProm);
+      }
+      throw Fail`cannot yet send guest promises ${gProm}`;
+    },
+    gErr => {
+      const hErr = harden(
+        makeError(gErr.message, getErrorConstructor(gErr.name)),
+      );
+      annotateError(hErr, X`from guest error ${gErr}`);
+      return hErr;
+    },
+  );
+
+  const hostToGuest = makeConvert(
+    hRem => {
+      if (bijection.hasHost(hRem)) {
+        return bijection.hostToGuest(hRem);
+      }
+      const gRem = makeGuestForHostRemotable(hRem);
+      bijection.init(gRem, hRem);
+      return gRem;
+    },
+    hVow => {
+      if (bijection.hasHost(hVow)) {
+        return bijection.hostToGuest(hVow);
+      }
+      const gP = makeGuestForHostVow(hVow);
+      bijection.init(gP, hVow);
+      return gP;
+    },
+    hErr => {
+      const gErr = harden(
+        makeError(hErr.message, getErrorConstructor(hErr.name)),
+      );
+      annotateError(gErr, X`from host error ${hErr}`);
+      return gErr;
+    },
+  );
+
+  return harden({ guestToHost, hostToGuest });
+};
+harden(makeConvertKit);

package/src/ephemera.d.ts

@@ -0,0 +1,2 @@
+export function makeEphemera<S extends WeakKey = WeakKey, V extends unknown = any>(reinit: (self: S) => V): Ephemera<S, V>;
+//# sourceMappingURL=ephemera.d.ts.map

package/src/ephemera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ephemera.d.ts","sourceRoot":"","sources":["ephemera.js"],"names":[],"mappings":"AAkBO,6BAFe,CAAC,4BAAC,CAAC,gCADd,CAAC,IAAI,EACM,CAAC,AADJ,KACK,CAAC,AADA,GACZ,QAAQ,CAAC,CAAC,EAAC,CAAC,CAAC,CAiBzB"}

package/src/ephemera.js

@@ -0,0 +1,35 @@
+/**
+ * Used by a possibly-durable exo to store per-instance ephemeral state.
+ * Each ephemera is created at the exo class prepare level, and then
+ * used from within the exo class methods to get state `eph.for(self)`.
+ * At the beginning of a new incarnation, there is no such state, so
+ * the first time it is accessed, it is initialized from `reinit(self)`.
+ * The ephemeral state can be dropped explicitly during an incarnation
+ * with `eph.resetFor(self)`, in which case the `eph.for(self)` will
+ * call it to be reinitialized again from `reinit(self)`.
+ *
+ * TODO consolidate with `makeEphemeraProvider` from `@agoric/zoe`, since
+ * they are serving similar purposes in similar ways.
+ *
+ * @template {WeakKey} [S=WeakKey]
+ * @template {any} [V=any]
+ * @param {(self: S) => V} reinit
+ * @returns {Ephemera<S,V>}
+ */
+export const makeEphemera = reinit => {
+  /** @type {WeakMap<S,V>} */
+  const map = new WeakMap();
+
+  return harden({
+    for(self) {
+      if (!map.has(self)) {
+        map.set(self, reinit(self));
+      }
+      return /** @type {V} */ (map.get(self));
+    },
+    resetFor(self) {
+      return map.delete(self);
+    },
+  });
+};
+harden(makeEphemera);

package/src/equate.d.ts

@@ -0,0 +1,2 @@
+export function makeEquate(bijection: any): (g: any, h: any, label: any) => void;
+//# sourceMappingURL=equate.d.ts.map

package/src/equate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equate.d.ts","sourceRoot":"","sources":["equate.js"],"names":[],"mappings":"AAQO,iFAiHN"}

package/src/equate.js

@@ -0,0 +1,123 @@
+import { Fail, X, annotateError, q } from '@endo/errors';
+import { throwLabeled } from '@endo/common/throw-labeled.js';
+import { getTag, isObject, passStyleOf } from '@endo/pass-style';
+import { isVow } from '@agoric/vow/src/vow-utils.js';
+import { recordNames } from '@endo/marshal';
+
+const { is } = Object;
+
+export const makeEquate = bijection => {
+  const equate = (g, h, label) => {
+    // Open code the synchronous part of applyLabelingError, because
+    // we need to preserve returned promise identity.
+    // TODO switch to Richard Gibson's suggestion for a better way
+    // to keep track of the error labeling.
+    if (label === undefined) {
+      // eslint-disable-next-line no-use-before-define
+      innerEquate(g, h);
+    }
+    try {
+      // eslint-disable-next-line no-use-before-define
+      innerEquate(g, h);
+    } catch (err) {
+      throwLabeled(err, label);
+    }
+  };
+
+  const innerEquate = (g, h) => {
+    if (!isObject(g)) {
+      is(g, h) ||
+        // separate line so I can set a breakpoint
+        Fail`unequal ${g} vs ${h}`;
+      return;
+    }
+    if (bijection.has(g, h)) {
+      return;
+    }
+    const gPassStyle = passStyleOf(g);
+    if (gPassStyle === 'promise' && isVow(h)) {
+      // Important special case, because vows have passStyle 'tagged'.
+      // However, we do not yet support passing guest promise to host.
+      // TODO when we do, delete the `throw Fail` line and uncomment
+      // the two lines below it.
+      // We *do* support passing a guest wrapper of a hostVow back
+      // to the host, but that would be cause by `bijection.has` above.
+      throw Fail`guest promises not yet passable`;
+      // `init` does not yet do enough checking anyway. For this case,
+      // we should ensure that h is a host wrapper of a guest promise,
+      // which is a wrapping we don't yet support.
+      // bijection.init(g, h);
+      // return;
+    }
+    const hPassStyle = passStyleOf(h);
+    gPassStyle === hPassStyle ||
+      Fail`unequal passStyles ${q(gPassStyle)} vs ${q(hPassStyle)}`;
+    switch (gPassStyle) {
+      case 'copyArray': {
+        equate(g.length, h.length, 'length');
+        // eslint-disable-next-line github/array-foreach
+        g.forEach((gEl, i) => equate(gEl, h[i], i));
+        return;
+      }
+      case 'copyRecord': {
+        const gNames = recordNames(g);
+        const hNames = recordNames(h);
+        equate(gNames, hNames, 'propertyNames');
+        for (const name of gNames) {
+          equate(g[name], h[name], name);
+        }
+        return;
+      }
+      case 'tagged': {
+        equate(getTag(g), getTag(h), 'tag');
+        equate(g.payload, h.payload, 'payload');
+        return;
+      }
+      case 'error': {
+        equate(g.name, h.name, 'error name');
+        // For errors, all that needs to agree on replay is the `name`
+        // property. All others can differ. That's because everything else
+        // is assumed to be diagnostic info useful to programmers, which
+        // we'd like to improve over time. No programmatic use of additional
+        // error diagnostic info other than to better inform developers.
+        // A program should not take a semantically significant branch
+        // based on any of this diagnostic info, aside from `name`.
+        //
+        // Error annotations are not observable outside the console output,
+        // so this does not breach membrane isolation.
+        annotateError(g, X`replay of error ${h}`);
+        annotateError(h, X`replayed as error ${g}`);
+        return;
+      }
+      case 'remotable': {
+        // Note that we can send a guest wrapping of a host remotable
+        // back to the host,
+        // but that should have already been taken care of by the
+        // `bijection.has` above.
+        throw Fail`cannot yet send guest remotables to host ${g} vs ${h}`;
+        // `init` does not yet do enough checking anyway. For this case,
+        // we should ensure that h is a host wrapper of a guest remotable,
+        // which is a wrapping we don't yet support.
+        // bijection.init(g, h);
+        // return;
+      }
+      case 'promise': {
+        // Note that we can send a guest wrapping of a host promise
+        // (or vow) back to the host,
+        // but that should have already been taken care of by the
+        // `bijection.has` above.
+        throw Fail`cannot yet send guest promises to host ${g} vs ${h}`;
+        // `init` does not yet do enough checking anyway. For this case,
+        // we should ensure that h is a host wrapper of a guest promise,
+        // which is a wrapping we don't yet support.
+        // bijection.init(g, h);
+        // return;
+      }
+      default: {
+        throw Fail`unexpected passStyle ${q(gPassStyle)}`;
+      }
+    }
+  };
+  return harden(equate);
+};
+harden(makeEquate);

package/src/log-store.d.ts

@@ -0,0 +1,25 @@
+export function prepareLogStore(zone: Zone): () => import("@endo/exo").Guarded<{
+    reset(): void;
+    dispose(): void;
+    getIndex(): number;
+    getLength(): number;
+    isReplaying(): boolean;
+    peekEntry(): LogEntry;
+    nextEntry(): LogEntry;
+    pushEntry(entry: any): number;
+    dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+    promiseReplayDone(): Promise<undefined>;
+}>;
+export type LogStore = ReturnType<ReturnType<(zone: Zone) => () => import("@endo/exo").Guarded<{
+    reset(): void;
+    dispose(): void;
+    getIndex(): number;
+    getLength(): number;
+    isReplaying(): boolean;
+    peekEntry(): LogEntry;
+    nextEntry(): LogEntry;
+    pushEntry(entry: any): number;
+    dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+    promiseReplayDone(): Promise<undefined>;
+}>>>;
+//# sourceMappingURL=log-store.d.ts.map

package/src/log-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-store.d.ts","sourceRoot":"","sources":["log-store.js"],"names":[],"mappings":"AA4BO;;;;;;;;;;;GAoIN;uBAGY,UAAU,CAAC,UAAU;;;;;;;;;;;GAAiB,CAAC"}

package/src/log-store.js

@@ -0,0 +1,165 @@
+import { Fail, q } from '@endo/errors';
+import { makePromiseKit } from '@endo/promise-kit';
+import { M } from '@endo/patterns';
+import { LogEntryShape } from './type-guards.js';
+import { makeEphemera } from './ephemera.js';
+
+/**
+ * @import {MapStore} from '@agoric/store'
+ */
+
+const LogStoreI = M.interface('LogStore', {
+  reset: M.call().returns(),
+  dispose: M.call().returns(),
+  getIndex: M.call().returns(M.number()),
+  getLength: M.call().returns(M.number()),
+  isReplaying: M.call().returns(M.boolean()),
+  peekEntry: M.call().returns(LogEntryShape),
+  nextEntry: M.call().returns(LogEntryShape),
+  pushEntry: M.call(LogEntryShape).returns(M.number()),
+  dump: M.call().returns(M.arrayOf(LogEntryShape)),
+  promiseReplayDone: M.call().returns(M.promise()),
+});
+
+/**
+ * A growable, replayable, sequence of `LogEntry`s.
+ *
+ * @param {Zone} zone
+ */
+export const prepareLogStore = zone => {
+  /**
+   * @type {Ephemera<LogStore, {
+   *           index: number
+   *           replayDoneKit: PromiseKit<undefined>
+   *        }>}
+   */
+  const tmp = makeEphemera(log => {
+    const result = {
+      index: 0,
+      replayDoneKit: makePromiseKit(),
+    };
+    if (log.getLength() === 0) {
+      result.replayDoneKit.resolve(undefined);
+    }
+    return result;
+  });
+
+  return zone.exoClass(
+    'LogStore',
+    LogStoreI,
+    () => {
+      /**
+       * Really used to emulate a zone-storable vector, i.e., what in
+       * conventional JS you'd use a mutable array for, where you mutate
+       * only by `.push`
+       *
+       * @type {MapStore<number, LogEntry>}
+       */
+      const mapStore = zone.detached().mapStore('logMapStore', {
+        keyShape: M.number(),
+        valueShape: LogEntryShape,
+      });
+      return {
+        mapStore,
+      };
+    },
+    {
+      reset() {
+        const { self } = this;
+        tmp.resetFor(self);
+
+        // TODO: Should we resolve replayDoneKit here, in case we're
+        // transitioning to a Failed state, so that any pending watchers
+        // can exit?
+      },
+      dispose() {
+        const { state, self } = this;
+        const { mapStore } = state;
+
+        tmp.resetFor(self);
+        mapStore.clear();
+      },
+      getIndex() {
+        const { self } = this;
+        const eph = tmp.for(self);
+
+        return eph.index;
+      },
+      getLength() {
+        const { state } = this;
+        const { mapStore } = state;
+
+        return mapStore.getSize();
+      },
+      isReplaying() {
+        const { state, self } = this;
+        const { mapStore } = state;
+        const eph = tmp.for(self);
+
+        return eph.index < mapStore.getSize();
+      },
+      peekEntry() {
+        const { state, self } = this;
+        const { mapStore } = state;
+        const eph = tmp.for(self);
+
+        self.isReplaying() ||
+          Fail`No longer replaying: ${q(eph.index)} vs ${q(
+            mapStore.getSize(),
+          )}`;
+        const result = mapStore.get(eph.index);
+        return result;
+      },
+      nextEntry() {
+        const { self } = this;
+        const eph = tmp.for(self);
+
+        const result = self.peekEntry();
+        eph.index += 1;
+        if (!self.isReplaying()) {
+          eph.replayDoneKit.resolve(undefined);
+        }
+        return result;
+      },
+      pushEntry(entry) {
+        const { state, self } = this;
+        const { mapStore } = state;
+        const eph = tmp.for(self);
+
+        !self.isReplaying() ||
+          Fail`still replaying: ${q(eph.index)} vs ${q(mapStore.getSize())}`;
+        eph.index === mapStore.getSize() ||
+          Fail`internal: index confusion ${q(eph.index)} vs ${q(
+            mapStore.getSize(),
+          )}`;
+        mapStore.init(eph.index, entry);
+        eph.index += 1;
+        eph.index === mapStore.getSize() ||
+          Fail`internal: index confusion ${q(eph.index)} vs ${q(
+            mapStore.getSize(),
+          )}`;
+        return eph.index;
+      },
+      dump() {
+        const { state } = this;
+        const { mapStore } = state;
+        const len = mapStore.getSize();
+        const result = [];
+        for (let i = 0; i < len; i += 1) {
+          result.push(mapStore.get(i));
+        }
+        return harden(result);
+      },
+      promiseReplayDone() {
+        const { self } = this;
+        const eph = tmp.for(self);
+
+        return eph.replayDoneKit.promise;
+      },
+    },
+  );
+};
+
+/**
+ * @typedef {ReturnType<ReturnType<prepareLogStore>>} LogStore
+ */

package/src/replay-membrane.d.ts

@@ -0,0 +1,71 @@
+export function makeReplayMembrane(log: import("@endo/exo").Guarded<{
+    reset(): void;
+    dispose(): void;
+    getIndex(): number;
+    getLength(): number;
+    isReplaying(): boolean;
+    peekEntry(): LogEntry;
+    nextEntry(): LogEntry;
+    pushEntry(entry: any): number;
+    dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+    promiseReplayDone(): Promise<undefined>;
+}>, bijection: import("@endo/exo").Guarded<{
+    reset(): void;
+    init(g: any, h: any): void;
+    hasGuest(g: any): boolean;
+    hasHost(h: any): boolean;
+    has(g: any, h: any): boolean;
+    guestToHost(g: any): any;
+    hostToGuest(h: any): any;
+}>, vowTools: {
+    when: <T, TResult1 = import("@agoric/vow").Unwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("@agoric/vow").Unwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+    watch: <T_1 = unknown, TResult1_1 = T_1, TResult2_1 = T_1, C = unknown>(specimenP: import("@agoric/vow").ERef<T_1 | Vow<T_1>>, watcher?: import("@agoric/vow").Watcher<T_1, TResult1_1, TResult2_1> | undefined, watcherContext?: C | undefined) => Vow<TResult1_1 | TResult2_1>;
+    makeVowKit: <T_2>() => import("@agoric/vow").VowKit<T_2>;
+    allVows: (vows: any) => Vow<any>;
+}, watchWake: (vowish: Promise<any> | Vow) => void, panic: (problem: Error) => never): {
+    hostToGuest: (specimen: Passable, label?: string | undefined) => any;
+    guestToHost: (specimen: Passable, label?: string | undefined) => any;
+    wake: () => void;
+    stop: () => void;
+} & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
+    hostToGuest: (specimen: Passable, label?: string | undefined) => any;
+    guestToHost: (specimen: Passable, label?: string | undefined) => any;
+    wake: () => void;
+    stop: () => void;
+}>;
+export type ReplayMembrane = ReturnType<(log: import("@endo/exo").Guarded<{
+    reset(): void;
+    dispose(): void;
+    getIndex(): number;
+    getLength(): number;
+    isReplaying(): boolean;
+    peekEntry(): LogEntry;
+    nextEntry(): LogEntry;
+    pushEntry(entry: any): number;
+    dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+    promiseReplayDone(): Promise<undefined>;
+}>, bijection: import("@endo/exo").Guarded<{
+    reset(): void;
+    init(g: any, h: any): void;
+    hasGuest(g: any): boolean;
+    hasHost(h: any): boolean;
+    has(g: any, h: any): boolean;
+    guestToHost(g: any): any;
+    hostToGuest(h: any): any;
+}>, vowTools: {
+    when: <T, TResult1 = import("@agoric/vow").Unwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("@agoric/vow").Unwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+    watch: <T_1 = unknown, TResult1_1 = T_1, TResult2_1 = T_1, C = unknown>(specimenP: import("@agoric/vow").ERef<T_1 | Vow<T_1>>, watcher?: import("@agoric/vow").Watcher<T_1, TResult1_1, TResult2_1> | undefined, watcherContext?: C | undefined) => Vow<TResult1_1 | TResult2_1>;
+    makeVowKit: <T_2>() => import("@agoric/vow").VowKit<T_2>;
+    allVows: (vows: any) => Vow<any>;
+}, watchWake: (vowish: Promise<any> | Vow) => void, panic: (problem: Error) => never) => {
+    hostToGuest: (specimen: Passable, label?: string | undefined) => any;
+    guestToHost: (specimen: Passable, label?: string | undefined) => any;
+    wake: () => void;
+    stop: () => void;
+} & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
+    hostToGuest: (specimen: Passable, label?: string | undefined) => any;
+    guestToHost: (specimen: Passable, label?: string | undefined) => any;
+    wake: () => void;
+    stop: () => void;
+}>>;
+//# sourceMappingURL=replay-membrane.d.ts.map

package/src/replay-membrane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-membrane.d.ts","sourceRoot":"","sources":["replay-membrane.js"],"names":[],"mappings":"AAkBO;;;;;;;;;;;;;;;;;;;;uFATK,CAAC;;;;8CAMyB,IAAI,SAC/B,CAAC,OAAO,EAAE,KAAK,KAAK,KAAK;;;;;;;;;;GA+ZnC;6BAGa,UAAU;;;;;;;;;;;;;;;;;;;;uFAzaZ,CAAC;;;;2DAOF,CAAC,OAAO,EAAE,KAAK,KAAK,KAAK;;;;;;;;;;GAkaQ"}