@agoric/async-flow 0.1.1-upgrade-16-dev-d45b478.0 → 0.1.1-upgrade-17-dev-3b97a9f.0

package/src/replay-membrane.js

@@ -1,32 +1,41 @@
 /* eslint-disable no-use-before-define */
+import { isVow } from '@agoric/vow/src/vow-utils.js';
+import { heapVowE } from '@agoric/vow/vat.js';
+import { throwLabeled } from '@endo/common/throw-labeled.js';
 import { Fail, X, b, makeError, q } from '@endo/errors';
-import { Far, Remotable, getInterfaceOf } from '@endo/pass-style';
 import { E } from '@endo/eventual-send';
 import { getMethodNames } from '@endo/eventual-send/utils.js';
-import { makeEquate } from './equate.js';
+import { Far, Remotable, getInterfaceOf } from '@endo/pass-style';
 import { makeConvertKit } from './convert.js';
+import { makeEquate } from './equate.js';
 
 /**
  * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Passable, PassableCap, CopyTagged} from '@endo/pass-style'
+ * @import {Vow, VowTools, VowKit} from '@agoric/vow'
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ * @import {Host, HostVow, LogEntry, Outcome} from '../src/types.js';
  */
 
 const { fromEntries, defineProperties, assign } = Object;
 
 /**
- * @param {LogStore} log
- * @param {Bijection} bijection
- * @param {VowTools} vowTools
- * @param {(vowish: Promise | Vow) => void} watchWake
- * @param {(problem: Error) => never} panic
+ * @param {object} arg
+ * @param {LogStore} arg.log
+ * @param {Bijection} arg.bijection
+ * @param {VowTools} arg.vowTools
+ * @param {(vowish: Promise | Vow) => void} arg.watchWake
+ * @param {(problem: Error) => never} arg.panic
  */
-export const makeReplayMembrane = (
+export const makeReplayMembrane = ({
   log,
   bijection,
   vowTools,
   watchWake,
   panic,
-) => {
-  const { when } = vowTools;
+}) => {
+  const { when, makeVowKit } = vowTools;
 
   const equate = makeEquate(bijection);
 
@@ -208,14 +217,193 @@ export const makeReplayMembrane = (
 
   // //////////////// Eventual Send ////////////////////////////////////////////
 
+  /**
+   * @param {PassableCap} hostTarget
+   * @param {string | undefined} optVerb
+   * @param {Passable[]} hostArgs
+   */
+  const performSendOnly = (hostTarget, optVerb, hostArgs) => {
+    try {
+      optVerb
+        ? heapVowE.sendOnly(hostTarget)[optVerb](...hostArgs)
+        : // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore once we changed this from E to heapVowE,
+          // typescript started complaining that heapVowE(hostTarget)
+          // is not callable. I'm not sure if this is a just a typing bug
+          // in heapVowE or also reflects a runtime deficiency. But this
+          // case it not used yet anyway. We disable it
+          // with at-ts-ignore rather than at-ts-expect-error because
+          // the dependency-graph tests complains that the latter is unused.
+          heapVowE.sendOnly(hostTarget)(...hostArgs);
+    } catch (hostProblem) {
+      throw Panic`internal: eventual sendOnly synchrously failed ${hostProblem}`;
+    }
+  };
+
+  /**
+   * @param {PassableCap} hostTarget
+   * @param {string | undefined} optVerb
+   * @param {Passable[]} hostArgs
+   * @param {number} callIndex
+   * @param {VowKit} hostResultKit
+   * @param {Promise} guestReturnedP
+   * @returns {Outcome}
+   */
+  const performSend = (
+    hostTarget,
+    optVerb,
+    hostArgs,
+    callIndex,
+    hostResultKit,
+    guestReturnedP,
+  ) => {
+    const { vow, resolver } = hostResultKit;
+    try {
+      const hostPromise = optVerb
+        ? heapVowE(hostTarget)[optVerb](...hostArgs)
+        : // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore once we changed this from E to heapVowE,
+          // typescript started complaining that heapVowE(hostTarget)
+          // is not callable. I'm not sure if this is a just a typing bug
+          // in heapVowE or also reflects a runtime deficiency. But this
+          // case it not used yet anyway. We disable it
+          // with at-ts-ignore rather than at-ts-expect-error because
+          // the dependency-graph tests complains that the latter is unused.
+          heapVowE(hostTarget)(...hostArgs);
+      resolver.resolve(hostPromise); // TODO does this always work?
+    } catch (hostProblem) {
+      throw Panic`internal: eventual send synchrously failed ${hostProblem}`;
+    }
+    try {
+      const entry = harden(['doReturn', callIndex, vow]);
+      log.pushEntry(entry);
+      const guestPromise = makeGuestForHostVow(vow, guestReturnedP);
+      // Note that `guestPromise` is not registered in the bijection since
+      // guestReturnedP is already the guest for vow. Rather, the handler
+      // returns guestPromise to resolve guestReturnedP to guestPromise.
+      doReturn(callIndex, vow);
+      return harden({
+        kind: 'return',
+        result: guestPromise,
+      });
+    } catch (problem) {
+      throw panic(problem);
+    }
+  };
+
   const guestHandler = harden({
+    applyMethodSendOnly(guestTarget, optVerb, guestArgs) {
+      const callIndex = log.getIndex();
+      if (stopped || !bijection.hasGuest(guestTarget)) {
+        Fail`Sent from a previous run: ${guestTarget}`;
+      }
+      try {
+        const guestEntry = harden([
+          'checkSendOnly',
+          guestTarget,
+          optVerb,
+          guestArgs,
+          callIndex,
+        ]);
+        if (log.isReplaying()) {
+          const entry = log.nextEntry();
+          try {
+            equate(guestEntry, entry);
+          } catch (equateErr) {
+            // TODO consider Richard Gibson's suggestion for a better way
+            // to keep track of the error labeling.
+            throwLabeled(
+              equateErr,
+              `replay ${callIndex}:
+     ${q(guestEntry)}
+  vs ${q(entry)}
+    `,
+            );
+          }
+        } else {
+          const entry = guestToHost(guestEntry);
+          log.pushEntry(entry);
+          const [_op, hostTarget, _optVerb, hostArgs, _callIndex] = entry;
+          performSendOnly(hostTarget, optVerb, hostArgs);
+        }
+      } catch (fatalError) {
+        throw panic(fatalError);
+      }
+    },
     applyMethod(guestTarget, optVerb, guestArgs, guestReturnedP) {
-      if (optVerb === undefined) {
-        throw Panic`guest eventual call not yet supported: ${guestTarget}(${b(guestArgs)}) -> ${b(guestReturnedP)}`;
-      } else {
-        throw Panic`guest eventual send not yet supported: ${guestTarget}.${b(optVerb)}(${b(guestArgs)}) -> ${b(guestReturnedP)}`;
+      const callIndex = log.getIndex();
+      if (stopped || !bijection.hasGuest(guestTarget)) {
+        Fail`Sent from a previous run: ${guestTarget}`;
+      }
+      const hostResultKit = makeVowKit();
+      const g = bijection.unwrapInit(guestReturnedP, hostResultKit.vow);
+      g === guestReturnedP ||
+        Fail`internal: guestReturnedP should not unwrap: ${g} vs ${guestReturnedP}`;
+      /** @type {Outcome} */
+      let outcome;
+      try {
+        const guestEntry = harden([
+          'checkSend',
+          guestTarget,
+          optVerb,
+          guestArgs,
+          callIndex,
+        ]);
+        if (log.isReplaying()) {
+          const entry = log.nextEntry();
+          try {
+            equate(guestEntry, entry);
+          } catch (equateErr) {
+            // TODO consider Richard Gibson's suggestion for a better way
+            // to keep track of the error labeling.
+            throwLabeled(
+              equateErr,
+              `replay ${callIndex}:
+     ${q(guestEntry)}
+  vs ${q(entry)}
+    `,
+            );
+          }
+          outcome = /** @type {Outcome} */ (nestInterpreter(callIndex));
+        } else {
+          const entry = guestToHost(guestEntry);
+          log.pushEntry(entry);
+          const [_op, hostTarget, _optVerb, hostArgs, _callIndex] = entry;
+          nestInterpreter(callIndex);
+          outcome = performSend(
+            hostTarget,
+            optVerb,
+            hostArgs,
+            callIndex,
+            hostResultKit,
+            guestReturnedP,
+          );
+        }
+      } catch (fatalError) {
+        throw panic(fatalError);
+      }
+
+      switch (outcome.kind) {
+        case 'return': {
+          return outcome.result;
+        }
+        case 'throw': {
+          throw outcome.problem;
+        }
+        default: {
+          // @ts-expect-error TS correctly knows this case would be outside
+          // the type. But that's what we want to check.
+          throw Panic`unexpected outcome kind ${q(outcome.kind)}`;
+        }
       }
     },
+    applyFunctionSendOnly(guestTarget, guestArgs) {
+      return guestHandler.applyMethodSendOnly(
+        guestTarget,
+        undefined,
+        guestArgs,
+      );
+    },
     applyFunction(guestTarget, guestArgs, guestReturnedP) {
       return guestHandler.applyMethod(
         guestTarget,
@@ -224,6 +412,9 @@ export const makeReplayMembrane = (
         guestReturnedP,
       );
     },
+    getSendOnly(guestTarget, prop) {
+      throw Panic`guest eventual getSendOnly not yet supported: ${guestTarget}.${b(prop)}`;
+    },
     get(guestTarget, prop, guestReturnedP) {
       throw Panic`guest eventual get not yet supported: ${guestTarget}.${b(prop)} -> ${b(guestReturnedP)}`;
     },
@@ -315,11 +506,20 @@ export const makeReplayMembrane = (
 
   /**
    * @param {Vow} hVow
+   * @param {Promise} [promiseKey]
+   *   If provided, use this promise as the key in the guestPromiseMap
+   *   rather than the returned promise. This only happens when the
+   *   promiseKey ends up forwarded to the returned promise anyway, so
+   *   associating it with this resolve/reject pair is not incorrect.
+   *   It is needed when `promiseKey` is also entered into the bijection
+   *   paired with hVow.
    * @returns {Promise}
    */
-  const makeGuestForHostVow = hVow => {
+  const makeGuestForHostVow = (hVow, promiseKey = undefined) => {
+    isVow(hVow) || Fail`vow expected ${hVow}`;
     const { promise, resolve, reject } = makeGuestPromiseKit();
-    guestPromiseMap.set(promise, harden({ resolve, reject }));
+    promiseKey ??= promise;
+    guestPromiseMap.set(promiseKey, harden({ resolve, reject }));
 
     watchWake(hVow);
 
@@ -343,7 +543,7 @@ export const makeReplayMembrane = (
       hVow,
       async hostFulfillment => {
         await log.promiseReplayDone(); // should never reject
-        if (!stopped && guestPromiseMap.get(promise) !== 'settled') {
+        if (!stopped && guestPromiseMap.get(promiseKey) !== 'settled') {
           /** @type {LogEntry} */
           const entry = harden(['doFulfill', hVow, hostFulfillment]);
           log.pushEntry(entry);
@@ -358,7 +558,7 @@ export const makeReplayMembrane = (
       },
       async hostReason => {
         await log.promiseReplayDone(); // should never reject
-        if (!stopped && guestPromiseMap.get(promise) !== 'settled') {
+        if (!stopped && guestPromiseMap.get(promiseKey) !== 'settled') {
           /** @type {LogEntry} */
           const entry = harden(['doReject', hVow, hostReason]);
           log.pushEntry(entry);

package/src/type-guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["type-guards.js"],"names":[],"mappings":"AAGA,8DAME;AAEF,gEAA6D;AAE7D,6DAwCE"}
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["type-guards.js"],"names":[],"mappings":"AAGA,8DAME;AAEF,gEAA6D;AAE7D,6DAsDE"}

package/src/type-guards.js

@@ -23,6 +23,13 @@ export const LogEntryShape = M.or(
   //   M.number(),
   // ],
   // [
+  //   'doSendOnly',
+  //   M.or(M.remotable('host wrapper of guest target'), VowShape),
+  //   M.opt(PropertyKeyShape),
+  //   M.arrayOf(M.any()),
+  //   M.number(),
+  // ],
+  // [
   //   'doSend',
   //   M.or(M.remotable('host wrapper of guest target'), VowShape),
   //   M.opt(PropertyKeyShape),
@@ -42,13 +49,20 @@ export const LogEntryShape = M.or(
     M.arrayOf(M.any()),
     M.number(),
   ],
-  // [
-  //   'checkSend',
-  //   M.or(M.remotable('host target'), VowShape),
-  //   M.opt(PropertyKeyShape),
-  //   M.arrayOf(M.any()),
-  //   M.number(),
-  // ],
+  [
+    'checkSendOnly',
+    M.or(M.remotable('host target'), VowShape),
+    M.opt(PropertyKeyShape),
+    M.arrayOf(M.any()),
+    M.number(),
+  ],
+  [
+    'checkSend',
+    M.or(M.remotable('host target'), VowShape),
+    M.opt(PropertyKeyShape),
+    M.arrayOf(M.any()),
+    M.number(),
+  ],
   // ['checkReturn', M.number(), M.any()],
   // ['checkThrow', M.number(), M.any()],
 );

package/src/types.d.ts

@@ -1,70 +1,221 @@
-type FlowState = "Running" | "Sleeping" | "Replaying" | "Failed" | "Done";
-type Guest<T extends Passable = Passable> = T;
-type Host<T extends Passable = Passable> = T;
+import type { Passable } from '@endo/pass-style';
+import type { Vow, VowTools } from '@agoric/vow';
+import type { LogStore } from './log-store.js';
+import type { Bijection } from './bijection.js';
+import type { EndowmentTools } from './endowments.js';
+
+export type FlowState =
+  | 'Running'
+  | 'Sleeping'
+  | 'Replaying'
+  | 'Failed'
+  | 'Done';
+
+/**
+ * `T` defaults to `any`, not `Passable`, because unwrapped guests include
+ * non-passables, like unwrapped functions and unwrapped state records.
+ * (Unwrapped functions could be made into Remotables,
+ * but since they still could not be made durable, in this context
+ * it'd be pointless.)
+ */
+export type Guest<T extends unknown = any> = T;
+export type Host<T extends Passable = Passable> = T;
+
 /**
  * A HostVow must be durably storable. It corresponds to an
  * ephemeral guest promise.
  */
-type HostVow<T extends Passable = Passable> = import("@endo/pass-style").PassStyled<"tagged", "Vow"> & {
-    payload: import("@agoric/vow").VowPayload<T>;
+export type HostVow<T extends Passable = Passable> = Host<Vow<T>>;
+
+export type GuestAsyncFunc = (
+  ...activationArgs: Guest[]
+) => Guest<Promise<any>>;
+
+export type HostAsyncFuncWrapper = (
+  ...activationArgs: Host<any>[]
+) => HostVow<any>;
+
+/**
+ * The function from the host as it will be available in the guest.
+ *
+ * Specifically, Vow return values are converted to Promises.
+ */
+export type GuestOf<F extends HostAsyncFuncWrapper> = F extends (
+  ...args: infer A
+) => Vow<infer R>
+  ? (...args: A) => Promise<R>
+  : F;
+
+// from https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+/**
+ * Convert an entire Guest interface into what the host will implement.
+ */
+type HostInterface<T> = {
+  [K in keyof T]: T[K] extends CallableFunction
+    ? HostOf<T[K]>
+    : T[K] extends Record<string, any>
+      ? Simplify<HostInterface<T[K]>>
+      : T[K];
 };
-type GuestAsyncFunc = (...activationArgs: Guest[]) => Guest<Promise<any>>;
-type HostAsyncFuncWrapper = (...activationArgs: Host[]) => HostVow;
-type PreparationOptions = {
-    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 = any, TResult1_1 = T_1, TResult2_1 = never, C = any>(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<Exclude<TResult1_1, void> | Exclude<TResult2_1, void> extends never ? TResult1_1 : Exclude<TResult1_1, void> | Exclude<TResult2_1, void>>;
-        makeVowKit: <T_2>() => import("@agoric/vow").VowKit<T_2>;
-        allVows: (vows: unknown[]) => Vow<any[]>;
-    } | undefined;
-    makeLogStore?: (() => 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>;
-    }>) | undefined;
-    makeBijection?: (() => 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;
-    }>) | undefined;
+
+/**
+ * Convert an entire Host interface into what the Guest will receive.
+ */
+export type GuestInterface<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => Vow<infer R>
+    ? (...args: Parameters<T[K]>) => Promise<R>
+    : T[K] extends HostAsyncFuncWrapper
+      ? GuestOf<T[K]>
+      : T[K] extends (...args: any[]) => infer R
+        ? T[K]
+        : T[K] extends object
+          ? GuestInterface<T[K]>
+          : T[K];
 };
-type OutcomeKind = "return" | "throw";
-type Outcome = {
-    kind: "return";
-    result: any;
-} | {
-    kind: "throw";
-    problem: any;
+
+/**
+ * The function the host must provide to match an interface the guest expects.
+ *
+ * Specifically, Promise return values are converted to Vows.
+ */
+export type HostOf<F extends CallableFunction> = F extends (
+  ...args: infer A
+) => infer R
+  ? R extends Promise<infer T>
+    ? (...args: A) => Vow<T extends Passable ? T : HostInterface<T>>
+    : (...args: A) => HostInterface<R>
+  : F;
+
+export type HostArgs<GA extends any[]> = { [K in keyof GA]: HostOf<GA[K]> };
+
+export type PreparationOptions = {
+  vowTools?: VowTools;
+  makeLogStore?: (() => LogStore) | undefined;
+  makeBijection?: (() => Bijection) | undefined;
+  endowmentTools?: EndowmentTools;
 };
-type Ephemera<S extends WeakKey = WeakKey, V extends unknown = any> = {
-    for: (self: S) => V;
-    resetFor: (self: S) => void;
+export type OutcomeKind = 'return' | 'throw';
+
+export type Outcome =
+  | {
+      kind: 'return';
+      result: any;
+    }
+  | {
+      kind: 'throw';
+      problem: any;
+    };
+
+export type Ephemera<S extends WeakKey = WeakKey, V extends unknown = any> = {
+  for: (self: S) => V;
+  resetFor: (self: S) => void;
 };
+
 /**
- * This is the typedef for the membrane log entries we currently implement.
- * See comment below for the commented-out typedef for the full
- * membrane log entry, which we do not yet support.
+ * This is the type alias for the membrane log entries we currently implement.
+ *
+ * @see {FutureLogEntry} below for the full membrane log entry, which we do not
+ * yet support.
  */
-type LogEntry = [// ///////////////// From Host to Guest /////////////////////////
-op: "doFulfill", vow: HostVow, fulfillment: Host] | [op: "doReject", vow: HostVow, reason: Host] | [op: "doReturn", callIndex: number, result: Host] | [op: "doThrow", callIndex: number, problem: Host] | [// ///////////////////// From Guest to Host /////////////////////////
-op: "checkCall", target: Host, optVerb: PropertyKey | undefined, args: Host[], callIndex: number];
-import type { PromiseKit } from '@endo/promise-kit';
-import type { Passable } from '@endo/pass-style';
-import type { Zone } from '@agoric/base-zone';
-import type { Vow } from '@agoric/vow';
-import type { VowTools } from '@agoric/vow';
-import type { LogStore } from './log-store.js';
-import type { Bijection } from './bijection.js';
-import type { ReplayMembrane } from './replay-membrane.js';
-//# sourceMappingURL=types.d.ts.map
+export type LogEntry =
+  | [
+      // ///////////////// From Host to Guest /////////////////////////
+      op: 'doFulfill',
+      vow: HostVow,
+      fulfillment: Host,
+    ]
+  | [op: 'doReject', vow: HostVow, reason: Host]
+  | [op: 'doReturn', callIndex: number, result: Host]
+  | [op: 'doThrow', callIndex: number, problem: Host]
+  | [
+      // ///////////////////// From Guest to Host /////////////////////////
+      op: 'checkCall',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'checkSendOnly',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'checkSend',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ];
+
+/**
+ * This would be the type alias for the full membrane log, if we supported:
+ * - the guest sending guest-promises and guest-remotables to the host
+ * - the guest using `E` to eventual-send to guest wrappers of the host
+ *   vows and remotables.
+ */
+export type FutureLogEntry =
+  | [
+      // ///////////////// From Host to Guest ///////////////////////
+      op: 'doFulfill',
+      vow: HostVow,
+      fulfillment: Host,
+    ]
+  | [op: 'doReject', vow: HostVow, reason: Host]
+  | [
+      op: 'doCall',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'doSendOnly',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'doSend',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [op: 'doReturn', callIndex: number, result: Host]
+  | [op: 'doThrow', callIndex: number, problem: Host]
+  | [
+      // ///////////////////// From Guest to Host /////////////////////////
+      op: 'checkFulfill',
+      vow: HostVow,
+      fulfillment: Host,
+    ]
+  | [op: 'checkReject', vow: HostVow, reason: Host]
+  | [
+      op: 'checkCall',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'checkSendOnly',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [
+      op: 'checkSend',
+      target: Host,
+      optVerb: PropertyKey | undefined,
+      args: Host[],
+      callIndex: number,
+    ]
+  | [op: 'checkReturn', callIndex: number, result: Host]
+  | [op: 'checkThrow', callIndex: number, problem: Host];