@agoric/vow 0.1.1-calypso-dev-84eb287.0

package/src/message-breakpoints.js

@@ -0,0 +1,180 @@
+// @ts-check
+import { getEnvironmentOption } from '@endo/env-options';
+
+const { quote: q, Fail } = assert;
+
+const { hasOwn, freeze, entries } = Object;
+
+/**
+ * @typedef {string | '*'} MatchStringTag
+ *   A star `'*'` matches any recipient. Otherwise, the string is
+ *   matched against the value of a recipient's `@@toStringTag`
+ *   after stripping out any leading `'Alleged: '` or `'DebugName: '`
+ *   prefix. For objects defined with `Far` this is the first argument,
+ *   known as the `farName`. For exos, this is the tag.
+ */
+/**
+ * @typedef {string | '*'} MatchMethodName
+ *   A star `'*'` matches any method name. Otherwise, the string is
+ *   matched against the method name. Currently, this is only an exact match.
+ *   However, beware that we may introduce a string syntax for
+ *   symbol method names.
+ */
+/**
+ * @typedef {number | '*'} MatchCountdown
+ *   A star `'*'` will always breakpoint. Otherwise, the string
+ *   must be a non-negative integer. Once that is zero, always breakpoint.
+ *   Otherwise decrement by one each time it matches until it reaches zero.
+ *   In other words, the countdown represents the number of
+ *   breakpoint occurrences to skip before actually breakpointing.
+ */
+
+/**
+ * This is the external JSON representation, in which
+ * - the outer property name is the class-like tag or '*',
+ * - the inner property name is the method name or '*',
+ * - the value is a non-negative integer countdown or '*'.
+ *
+ * @typedef {Record<MatchStringTag, Record<MatchMethodName, MatchCountdown>>} MessageBreakpoints
+ */
+
+/**
+ * This is the internal JSON representation, in which
+ * - the outer property name is the method name or '*',
+ * - the inner property name is the class-like tag or '*',
+ * - the value is a non-negative integer countdown or '*'.
+ *
+ * @typedef {Record<MatchMethodName, Record<MatchStringTag, MatchCountdown>>} BreakpointTable
+ */
+
+/**
+ * @typedef {object} MessageBreakpointTester
+ * @property {() => MessageBreakpoints} getBreakpoints
+ * @property {(newBreakpoints?: MessageBreakpoints) => void} setBreakpoints
+ * @property {(
+ *   recipient: object,
+ *   methodName: string | symbol | undefined
+ * ) => boolean} shouldBreakpoint
+ */
+
+/**
+ * @param {any} val
+ * @returns {val is Record<string, any>}
+ */
+const isJSONRecord = val =>
+  typeof val === 'object' && val !== null && !Array.isArray(val);
+
+/**
+ * Return `tag` after stripping off any `'Alleged: '` or `'DebugName: '`
+ * prefix if present.
+ * ```js
+ * simplifyTag('Alleged: moola issuer') === 'moola issuer'
+ * ```
+ * If there are multiple such prefixes, only the outer one is removed.
+ *
+ * @param {string} tag
+ * @returns {string}
+ */
+const simplifyTag = tag => {
+  for (const prefix of ['Alleged: ', 'DebugName: ']) {
+    if (tag.startsWith(prefix)) {
+      return tag.slice(prefix.length);
+    }
+  }
+  return tag;
+};
+
+/**
+ * @param {string} optionName
+ * @returns {MessageBreakpointTester | undefined}
+ */
+export const makeMessageBreakpointTester = optionName => {
+  let breakpoints = JSON.parse(getEnvironmentOption(optionName, 'null'));
+
+  if (breakpoints === null) {
+    return undefined;
+  }
+
+  /** @type {BreakpointTable} */
+  let breakpointsTable;
+
+  const getBreakpoints = () => breakpoints;
+  freeze(getBreakpoints);
+
+  const setBreakpoints = (newBreakpoints = breakpoints) => {
+    isJSONRecord(newBreakpoints) ||
+      Fail`Expected ${q(optionName)} option to be a JSON breakpoints record`;
+
+    /** @type {BreakpointTable} */
+    // @ts-expect-error confused by __proto__
+    const newBreakpointsTable = { __proto__: null };
+
+    for (const [tag, methodBPs] of entries(newBreakpoints)) {
+      tag === simplifyTag(tag) ||
+        Fail`Just use simple tag ${q(simplifyTag(tag))} rather than ${q(tag)}`;
+      isJSONRecord(methodBPs) ||
+        Fail`Expected ${q(optionName)} option's ${q(
+          tag,
+        )} to be a JSON methods breakpoints record`;
+      for (const [methodName, count] of entries(methodBPs)) {
+        count === '*' ||
+          (typeof count === 'number' &&
+            Number.isSafeInteger(count) &&
+            count >= 0) ||
+          Fail`Expected ${q(optionName)} option's ${q(tag)}.${q(
+            methodName,
+          )} to be "*" or a non-negative integer`;
+
+        const classBPs = hasOwn(newBreakpointsTable, methodName)
+          ? newBreakpointsTable[methodName]
+          : (newBreakpointsTable[methodName] = {
+              // @ts-expect-error confused by __proto__
+              __proto__: null,
+            });
+        classBPs[tag] = count;
+      }
+    }
+    breakpoints = newBreakpoints;
+    breakpointsTable = newBreakpointsTable;
+  };
+  freeze(setBreakpoints);
+
+  const shouldBreakpoint = (recipient, methodName) => {
+    if (methodName === undefined || methodName === null) {
+      // TODO enable function breakpointing
+      return false;
+    }
+    const classBPs = breakpointsTable[methodName] || breakpointsTable['*'];
+    if (classBPs === undefined) {
+      return false;
+    }
+    let tag = simplifyTag(recipient[Symbol.toStringTag]);
+    let count = classBPs[tag];
+    if (count === undefined) {
+      tag = '*';
+      count = classBPs[tag];
+      if (count === undefined) {
+        return false;
+      }
+    }
+    if (count === '*') {
+      return true;
+    }
+    if (count === 0) {
+      return true;
+    }
+    assert(typeof count === 'number' && count >= 1);
+    classBPs[tag] = count - 1;
+    return false;
+  };
+  freeze(shouldBreakpoint);
+
+  const breakpointTester = freeze({
+    getBreakpoints,
+    setBreakpoints,
+    shouldBreakpoint,
+  });
+  breakpointTester.setBreakpoints();
+  return breakpointTester;
+};
+freeze(makeMessageBreakpointTester);

package/src/tools.d.ts

@@ -0,0 +1,25 @@
+export function prepareVowTools(zone: Zone, powers?: {
+    isRetryableReason?: IsRetryableReason | undefined;
+} | undefined): {
+    E: (<T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => ECallableOrMethods<RemoteFunctions<T>>) & {
+        readonly get: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => EGetters<LocalRecord<T>>;
+        readonly resolve: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => Promise<Awaited<T>>;
+        readonly sendOnly: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => ESendOnlyCallableOrMethods<RemoteFunctions<T>>;
+        readonly when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(x: import("./E.js").ERef<T>, onfulfilled?: ((value: import("./types.js").EUnwrap<T>) => ERef<TResult1>) | undefined, onrejected?: ((reason: any) => ERef<TResult2>) | undefined, opts?: import("./types.js").EUnwrapOptions | undefined) => Promise<TResult1 | TResult2>;
+    } & {
+        when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./types.js").EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+        watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => import("./types.js").Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+    };
+    when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./types.js").EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => import("./types.js").Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+    makeVowKit: <T>() => import("./types.js").VowKit<T>;
+    allVows: (maybeVows: EVow<unknown>[]) => import("./types.js").Vow<any[]>;
+    asVow: <T extends unknown>(fn: (...args: any[]) => import("./types.js").Vow<Awaited<T>> | Awaited<T> | import("./types.js").PromiseVow<T>) => import("./types.js").Vow<Awaited<T>>;
+    asPromise: AsPromiseFunction;
+};
+export type VowTools = ReturnType<typeof prepareVowTools>;
+import type { Zone } from '@agoric/base-zone';
+import type { IsRetryableReason } from './types.js';
+import type { EVow } from './types.js';
+import type { AsPromiseFunction } from './types.js';
+//# sourceMappingURL=tools.d.ts.map

package/src/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAkBO,sCAJI,IAAI;;;;;;;;;;;;;;;yBAuBF,KAAK,OAAO,CAAC,EAAE;oCAaqyC,GAAG;;EAJn0C;uBAGa,UAAU,CAAC,OAAO,eAAe,CAAC;0BAxCzB,mBAAmB;uCACmB,YAAY;0BAAZ,YAAY;uCAAZ,YAAY"}

package/src/tools.js

@@ -0,0 +1,50 @@
+// @ts-check
+import { makeWhen } from './when.js';
+import { prepareVowKit } from './vow.js';
+import { prepareWatch } from './watch.js';
+import { prepareWatchUtils } from './watch-utils.js';
+import { makeAsVow } from './vow-utils.js';
+import { makeVowE } from './vow-e.js';
+
+/**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {IsRetryableReason, AsPromiseFunction, EVow} from './types.js';
+ */
+
+/**
+ * @param {Zone} zone
+ * @param {object} [powers]
+ * @param {IsRetryableReason} [powers.isRetryableReason]
+ */
+export const prepareVowTools = (zone, powers = {}) => {
+  const { isRetryableReason = /** @type {IsRetryableReason} */ (() => false) } =
+    powers;
+  const makeVowKit = prepareVowKit(zone);
+  const when = makeWhen(isRetryableReason);
+  const watch = prepareWatch(zone, makeVowKit, isRetryableReason);
+  const makeWatchUtils = prepareWatchUtils(zone, {
+    watch,
+    when,
+    makeVowKit,
+    isRetryableReason,
+  });
+  const watchUtils = makeWatchUtils();
+  const asVow = makeAsVow(makeVowKit);
+  const E = makeVowE(zone, { isRetryableReason, when, watch });
+
+  /**
+   * Vow-tolerant implementation of Promise.all.
+   *
+   * @param {EVow<unknown>[]} maybeVows
+   */
+  const allVows = maybeVows => watchUtils.all(maybeVows);
+
+  /** @type {AsPromiseFunction} */
+  const asPromise = (specimenP, ...watcherArgs) =>
+    watchUtils.asPromise(specimenP, ...watcherArgs);
+
+  return harden({ E, when, watch, makeVowKit, allVows, asVow, asPromise });
+};
+harden(prepareVowTools);
+
+/** @typedef {ReturnType<typeof prepareVowTools>} VowTools */

package/src/track-turns.d.ts

@@ -0,0 +1,7 @@
+export function trackTurns<T extends TurnStarterFn[]>(funcs: T): T;
+/**
+ * An optional function that is not this-sensitive, expected to be called at
+ * bottom of stack to start a new turn.
+ */
+export type TurnStarterFn = ((...args: any[]) => any) | undefined;
+//# sourceMappingURL=track-turns.d.ts.map

package/src/track-turns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-turns.d.ts","sourceRoot":"","sources":["track-turns.js"],"names":[],"mappings":"AAyFO,2BAJwB,CAAC,SAAlB,aAAa,EAAG,SACnB,CAAC,GACC,CAAC,CAmBb;;;;;4BAMY,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS"}

package/src/track-turns.js

@@ -0,0 +1,114 @@
+// @ts-check
+/* global globalThis */
+import {
+  getEnvironmentOption,
+  environmentOptionsListHas,
+} from '@endo/env-options';
+
+// NOTE: We can't import these because they're not in scope before lockdown.
+// import { assert, details as X, Fail } from '@agoric/assert';
+
+// WARNING: Global Mutable State!
+// This state is communicated to `assert` that makes it available to the
+// causal console, which affects the console log output. Normally we
+// regard the ability to see console log output as a meta-level privilege
+// analogous to the ability to debug. Aside from that, this module should
+// not have any observably mutable state.
+
+let hiddenPriorError;
+let hiddenCurrentTurn = 0;
+let hiddenCurrentEvent = 0;
+
+// Turn on if you seem to be losing error logging at the top of the event loop
+const VERBOSE = environmentOptionsListHas('DEBUG', 'track-turns');
+
+// Track-turns is disabled by default and can be enabled by an environment
+// option.
+const ENABLED =
+  getEnvironmentOption('TRACK_TURNS', 'disabled', ['enabled']) === 'enabled';
+
+// We hoist the following functions out of trackTurns() to discourage the
+// closures from holding onto 'args' or 'func' longer than necessary,
+// which we've seen cause HandledPromise arguments to be retained for
+// a surprisingly long time.
+
+const addRejectionNote = detailsNote => reason => {
+  if (reason instanceof Error) {
+    assert.note(reason, detailsNote);
+  }
+  if (VERBOSE) {
+    console.log('REJECTED at top of event loop', reason);
+  }
+};
+
+const wrapFunction =
+  (func, sendingError, X) =>
+  (...args) => {
+    hiddenPriorError = sendingError;
+    hiddenCurrentTurn += 1;
+    hiddenCurrentEvent = 0;
+    try {
+      let result;
+      try {
+        result = func(...args);
+      } catch (err) {
+        if (err instanceof Error) {
+          assert.note(
+            err,
+            X`Thrown from: ${hiddenPriorError}:${hiddenCurrentTurn}.${hiddenCurrentEvent}`,
+          );
+        }
+        if (VERBOSE) {
+          console.log('THROWN to top of event loop', err);
+        }
+        throw err;
+      }
+      // Must capture this now, not when the catch triggers.
+      const detailsNote = X`Rejection from: ${hiddenPriorError}:${hiddenCurrentTurn}.${hiddenCurrentEvent}`;
+      Promise.resolve(result).catch(addRejectionNote(detailsNote));
+      return result;
+    } finally {
+      hiddenPriorError = undefined;
+    }
+  };
+
+/**
+ * Given a list of `TurnStarterFn`s, returns a list of `TurnStarterFn`s whose
+ * `this`-free call behaviors are not observably different to those that
+ * cannot see console output. The only purpose is to cause additional
+ * information to appear on the console.
+ *
+ * The call to `trackTurns` is itself a sending event, that occurs in some call
+ * stack in some turn number at some event number within that turn. Each call
+ * to any of the returned `TurnStartFn`s is a receiving event that begins a new
+ * turn. This sending event caused each of those receiving events.
+ *
+ * @template {TurnStarterFn[]} T
+ * @param {T} funcs
+ * @returns {T}
+ */
+export const trackTurns = funcs => {
+  if (!ENABLED || typeof globalThis === 'undefined' || !globalThis.assert) {
+    return funcs;
+  }
+  const { details: X } = assert;
+
+  hiddenCurrentEvent += 1;
+  const sendingError = Error(
+    `Event: ${hiddenCurrentTurn}.${hiddenCurrentEvent}`,
+  );
+  if (hiddenPriorError !== undefined) {
+    assert.note(sendingError, X`Caused by: ${hiddenPriorError}`);
+  }
+
+  return /** @type {T} */ (
+    funcs.map(func => func && wrapFunction(func, sendingError, X))
+  );
+};
+
+/**
+ * An optional function that is not this-sensitive, expected to be called at
+ * bottom of stack to start a new turn.
+ *
+ * @typedef {((...args: any[]) => any) | undefined} TurnStarterFn
+ */

package/src/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Return truthy if a rejection reason should result in a retry.
+ */
+export type IsRetryableReason = (reason: any, priorRetryValue?: any) => any;
+/**
+ * Return type of a function that may
+ * return a promise or a vow.
+ */
+export type PromiseVow<T> = Promise<T | Vow<T>>;
+export type EUnwrapOptions = {
+    watch?: boolean | [] | AnyWatcher | [AnyWatcher, ...args: any[]] | undefined;
+};
+export type ERef<T> = T | PromiseLike<T>;
+/**
+ * Eventually a value T or Vow for it.
+ */
+export type EVow<T> = ERef<T | Vow<T>>;
+/**
+ * Follow the chain of vow shortening to the end, returning the final value.
+ * This is used within E, so we must narrow the type to its remote form.
+ */
+export type EUnwrap<T> = (T extends Vow<infer U> ? EUnwrap<U> : T extends PromiseLike<infer U> ? EUnwrap<U> : T);
+/**
+ * The first version of the vow implementation
+ * object.  CAVEAT: These methods must never be changed or added to, to provide
+ * forward/backward compatibility.  Create a new object and bump its version
+ * number instead.
+ */
+export type VowV0<T = any> = {
+    /**
+     * Attempt to unwrap all vows in this
+     * promise chain, returning a promise for the final value.  A rejection may
+     * indicate a temporary routing failure requiring a retry, otherwise that the
+     * decider of the terminal promise rejected it.
+     */
+    shorten: () => Promise<T>;
+};
+export type VowPayload<T = any> = {
+    vowV0: RemotableObject & Remote<VowV0<T>>;
+};
+export type Vow<T = any> = CopyTagged<"Vow", VowPayload<T>>;
+export type VowKit<T = any> = {
+    vow: Vow<T>;
+    resolver: VowResolver<T>;
+};
+export type VowResolver<T = any> = {
+    resolve(value?: T | PromiseVow<T>): void;
+    reject(reason?: any): void;
+};
+export type Watcher<T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]> = {
+    onFulfilled?: ((value: T, ...args: C) => Vow<TResult1> | PromiseVow<TResult1> | TResult1) | undefined;
+    onRejected?: ((reason: any, ...args: C) => Vow<TResult2> | PromiseVow<TResult2> | TResult2) | undefined;
+};
+/**
+ * Converts a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+ */
+export type AsPromiseFunction<T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]> = (specimenP: ERef<T | Vow<T>>, watcher?: Watcher<T, TResult1, TResult2, C> | undefined, watcherArgs?: C | undefined) => Promise<TResult1 | TResult2>;
+export type AnyWatcher = Watcher<any, any, any, any[]>;
+import type { RemotableObject } from '@endo/pass-style';
+import type { Remote } from '@agoric/internal';
+import type { CopyTagged } from '@endo/pass-style';
+//# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":";;;yCAYW,GAAG,oBACH,GAAG,KAED,GAAG;;;;;uBAKH,CAAC,IACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;;;;iBAUnB,CAAC,IACD,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;;;;iBAKlB,CAAC,IACD,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;;;;;oBAMhB,CAAC,IACD,CACZ,CAAK,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvC,CAAK,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC/C,CAAK,CACF;;;;;;;kBAIU,CAAC;;;;;;;aAMD,MAAM,OAAO,CAAC,CAAC,CAAC;;uBAOhB,CAAC;WAED,eAAe,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;;gBAIlC,CAAC,UACF,WAAW,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;mBAI/B,CAAC,UACF;IACZ,GAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAChB,QAAY,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CAC1B;wBAIU,CAAC,UACF;IAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CAAE;oBAIvE,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG;2BAEE,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;2BAChE,GAAG,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;;;;;8BAM5E,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG,wBAET,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,2FAGd,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;yBAI5B,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;qCA7GR,kBAAkB;4BAC3B,kBAAkB;gCAFd,kBAAkB"}

package/src/types.js

@@ -0,0 +1,116 @@
+// @ts-check
+export {};
+
+/**
+ * @import {CopyTagged} from '@endo/pass-style'
+ * @import {RemotableObject} from '@endo/pass-style';
+ * @import {Remote} from '@agoric/internal';
+ */
+
+/**
+ * @callback IsRetryableReason
+ * Return truthy if a rejection reason should result in a retry.
+ * @param {any} reason
+ * @param {any} [priorRetryValue] the previous value returned by this function
+ * when deciding whether to retry the same logical operation
+ * @returns {any} If falsy, the reason is not retryable. If truthy, the
+ * priorRetryValue for the next call.
+ */
+
+/**
+ * @template T
+ * @typedef {Promise<T | Vow<T>>} PromiseVow Return type of a function that may
+ * return a promise or a vow.
+ */
+
+/**
+ * @typedef {object} EUnwrapOptions
+ * @property {boolean | AnyWatcher | [] | [AnyWatcher, ...args: any[]]} [watch]
+ */
+
+/**
+ * @template T
+ * @typedef {T | PromiseLike<T>} ERef
+ */
+
+/**
+ * Eventually a value T or Vow for it.
+ * @template T
+ * @typedef {ERef<T | Vow<T>>} EVow
+ */
+
+/**
+ * Follow the chain of vow shortening to the end, returning the final value.
+ * This is used within E, so we must narrow the type to its remote form.
+ * @template T
+ * @typedef {(
+ *   T extends Vow<infer U> ? EUnwrap<U> :
+ *   T extends PromiseLike<infer U> ? EUnwrap<U> :
+ *   T
+ * )} EUnwrap
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {object} VowV0 The first version of the vow implementation
+ * object.  CAVEAT: These methods must never be changed or added to, to provide
+ * forward/backward compatibility.  Create a new object and bump its version
+ * number instead.
+ *
+ * @property {() => Promise<T>} shorten Attempt to unwrap all vows in this
+ * promise chain, returning a promise for the final value.  A rejection may
+ * indicate a temporary routing failure requiring a retry, otherwise that the
+ * decider of the terminal promise rejected it.
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {object} VowPayload
+ * @property {RemotableObject & Remote<VowV0<T>>} vowV0
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {CopyTagged<'Vow', VowPayload<T>>} Vow
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {{
+ *   vow: Vow<T>,
+ *   resolver: VowResolver<T>,
+ * }} VowKit
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {{ resolve(value?: T | PromiseVow<T>): void, reject(reason?: any): void }} VowResolver
+ */
+
+/**
+ * @template [T=any]
+ * @template [TResult1=T]
+ * @template [TResult2=never]
+ * @template {any[]} [C=any[]] watcher args
+ * @typedef {object} Watcher
+ * @property {(value: T, ...args: C) => Vow<TResult1> | PromiseVow<TResult1> | TResult1} [onFulfilled]
+ * @property {(reason: any, ...args: C) => Vow<TResult2> | PromiseVow<TResult2> | TResult2} [onRejected]
+ */
+
+/**
+ * Converts a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+ *
+ * @template [T=any]
+ * @template [TResult1=T]
+ * @template [TResult2=never]
+ * @template {any[]} [C=any[]]
+ * @callback AsPromiseFunction
+ * @param {ERef<T | Vow<T>>} specimenP
+ * @param {Watcher<T, TResult1, TResult2, C>} [watcher]
+ * @param {C} [watcherArgs]
+ * @returns {Promise<TResult1 | TResult2>}
+ */
+
+/**
+ * @typedef {Watcher<any, any, any, any[]>} AnyWatcher
+ */

package/src/vow-e.d.ts

@@ -0,0 +1,14 @@
+export function makeVowE(zone: import("@agoric/base-zone").Zone, { when, watch, isRetryableReason }: {
+    when: import("./when.js").When;
+    watch: import("./watch.js").Watch;
+    isRetryableReason: import("./types.js").IsRetryableReason;
+}): (<T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => ECallableOrMethods<RemoteFunctions<T>>) & {
+    readonly get: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => EGetters<LocalRecord<T>>;
+    readonly resolve: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => Promise<Awaited<T>>;
+    readonly sendOnly: <T>(x: T, opts?: import("./types.js").EUnwrapOptions | undefined) => ESendOnlyCallableOrMethods<RemoteFunctions<T>>;
+    readonly when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(x: import("./E.js").ERef<T>, onfulfilled?: ((value: import("./types.js").EUnwrap<T>) => ERef<TResult1>) | undefined, onrejected?: ((reason: any) => ERef<TResult2>) | undefined, opts?: import("./types.js").EUnwrapOptions | undefined) => Promise<TResult1 | TResult2>;
+} & {
+    when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./types.js").EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: import("./types.js").EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => import("./types.js").Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+};
+//# sourceMappingURL=vow-e.d.ts.map

package/src/vow-e.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vow-e.d.ts","sourceRoot":"","sources":["vow-e.js"],"names":[],"mappings":"AAkBO,+BANI,OAAO,mBAAmB,EAAE,IAAI,sCAExC;IAAyC,IAAI,EAArC,OAAO,WAAW,EAAE,IAAI;IACW,KAAK,EAAxC,OAAO,YAAY,EAAE,KAAK;IACqB,iBAAiB,EAAhE,OAAO,YAAY,EAAE,iBAAiB;CAChD;;;;;;;;EAmFA"}