@agoric/base-zone 0.1.1-orchestration-dev-096c4e8.0 → 0.1.1-u17.0

package/CHANGELOG.md

@@ -2,3 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+### 0.1.1-u17.0 (2024-09-17)
+
+
+### Features
+
+* **base-zone:** add `zone.watchPromise` ([9ce80d0](https://github.com/Agoric/agoric-sdk/commit/9ce80d06c0a56471d2da9f372b0b2d93d31d159a))
+* **base-zone:** alt revocable api using amplifier ([#8977](https://github.com/Agoric/agoric-sdk/issues/8977)) ([5cdf6e3](https://github.com/Agoric/agoric-sdk/commit/5cdf6e3a8b4fbb5cb8e276e6efeec65d9c3d6623))
+* **base-zone:** new package ([b7bc677](https://github.com/Agoric/agoric-sdk/commit/b7bc677238eee5969ac0a95dc066434ef676216e))
+* **watchUtils:** handle non-storables ([8c27c67](https://github.com/Agoric/agoric-sdk/commit/8c27c6725ba7ef4b71d3ab0ccfdbddd755bcd926))
+
+
+### Bug Fixes
+
+* **base-zone,zone:** import `isPassable` from @endo/pass-style ([#9230](https://github.com/Agoric/agoric-sdk/issues/9230)) ([fbd8633](https://github.com/Agoric/agoric-sdk/commit/fbd8633ae9f8420a589dd9bc32925418f2dde060))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/base-zone",
-  "version": "0.1.1-orchestration-dev-096c4e8.0+096c4e8",
+  "version": "0.1.1-u17.0",
   "description": "Allocation zone abstraction library and heap implementation",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -27,27 +27,28 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/store": "0.9.3-orchestration-dev-096c4e8.0+096c4e8",
-    "@endo/common": "^1.1.0",
-    "@endo/exo": "^1.2.1",
-    "@endo/far": "^1.0.4",
-    "@endo/pass-style": "^1.2.0",
-    "@endo/patterns": "^1.2.0"
+    "@agoric/store": "^0.9.3-u17.0",
+    "@endo/common": "^1.2.5",
+    "@endo/errors": "^1.2.5",
+    "@endo/exo": "^1.5.3",
+    "@endo/far": "^1.1.5",
+    "@endo/pass-style": "^1.4.3",
+    "@endo/patterns": "^1.4.3"
   },
   "devDependencies": {
-    "@endo/init": "^1.0.4",
-    "@endo/ses-ava": "^1.1.2",
+    "@endo/init": "^1.1.4",
+    "@endo/ses-ava": "^1.2.5",
     "ava": "^5.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^18.12 || ^20.9"
   },
   "ava": {
     "files": [
-      "test/**/test-*.js"
+      "test/**/*.test.*"
     ],
     "require": [
       "@endo/init/debug.js"
@@ -56,7 +57,7 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 89.25
+    "atLeast": 91.4
   },
-  "gitHead": "096c4e8fce80e9a509b0e1a30fda11736c4570e1"
+  "gitHead": "515c4c0efccfc91b97da30037c10fc4b076851e2"
 }

package/src/exports.d.ts

@@ -5,5 +5,4 @@
 //   Types exposed from modules.
 //
 
-// @ts-expect-error TS1383: Only named exports may use 'export type'.
 export type * from './types.js';

package/src/heap.d.ts

@@ -1,2 +1,2 @@
-export function makeHeapZone(baseLabel?: string | undefined): import('./types.js').Zone;
+export function makeHeapZone(baseLabel?: string | undefined): import("./types.js").Zone;
 //# sourceMappingURL=heap.d.ts.map

package/src/heap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heap.d.ts","sourceRoot":"","sources":["heap.js"],"names":[],"mappings":"AAmCO,8DAFM,OAAO,YAAY,EAAE,IAAI,CA2BrC"}
+{"version":3,"file":"heap.d.ts","sourceRoot":"","sources":["heap.js"],"names":[],"mappings":"AAmCO,8DAFM,OAAO,YAAY,EAAE,IAAI,CA4BrC"}

package/src/heap.js

@@ -1,7 +1,7 @@
 // @ts-check
 // @jessie-check
 
-import { Far } from '@endo/far';
+import { Far, isPassable } from '@endo/pass-style';
 import { makeExo, defineExoClass, defineExoClassKit } from '@endo/exo';
 import {
   makeScalarMapStore,
@@ -12,7 +12,7 @@ import {
 
 import { makeOnceKit } from './make-once.js';
 import { agoricVatDataKeys as keys } from './keys.js';
-import { isPassable } from './is-passable.js';
+import { watchPromise } from './watch-promise.js';
 
 /**
  * @type {import('./types.js').Stores}
@@ -50,6 +50,7 @@ export const makeHeapZone = (baseLabel = 'heapZone') => {
     subZone: wrapProvider(makeSubZone),
 
     makeOnce,
+    watchPromise,
     detached: detachedHeapStores.detached,
     isStorable: detachedHeapStores.isStorable,
 

package/src/index.d.ts

@@ -2,4 +2,5 @@ export * from "./exports.js";
 export * from "./make-once.js";
 export * from "./keys.js";
 export * from "./is-passable.js";
+export * from "./watch-promise.js";
 //# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -1,5 +1,7 @@
 // @jessie-check
 
+/// <reference types="@agoric/store/exported.js" />
+
 // eslint-disable-next-line import/export
 export * from './exports.js';
 
@@ -7,3 +9,4 @@ export * from './exports.js';
 export * from './make-once.js';
 export * from './keys.js';
 export * from './is-passable.js';
+export * from './watch-promise.js';

package/src/is-passable.d.ts

@@ -1,2 +1,2 @@
-export function isPassable(specimen: any): specimen is any;
+export function isPassable(specimen: any): specimen is Passable;
 //# sourceMappingURL=is-passable.d.ts.map

package/src/is-passable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-passable.d.ts","sourceRoot":"","sources":["is-passable.js"],"names":[],"mappings":"AAcO,qCAHI,GAAG,mBAWb"}
+{"version":3,"file":"is-passable.d.ts","sourceRoot":"","sources":["is-passable.js"],"names":[],"mappings":"AAOO,qCAHI,GAAG,GACD,QAAQ,IAAI,QAAQ,CAE6B"}

package/src/is-passable.js

@@ -1,23 +1,8 @@
-import { passStyleOf } from '@endo/pass-style';
+import { isPassable as realIsPassable } from '@endo/pass-style';
 
 /**
- * Is `specimen` Passable? This returns true iff `passStyleOf(specimen)`
- * returns a string. This returns `false` iff `passStyleOf(specimen)` throws.
- * Under no normal circumstance should `isPassable(specimen)` throw.
- *
- * TODO implement an isPassable that does not rely on try/catch, and
- * move it to @endo/pass-style.
- * This implementation is just a standin until then
- *
+ * @deprecated Import `isPassable` directly from `@endo/pass-style`
  * @param {any} specimen
  * @returns {specimen is Passable}
  */
-export const isPassable = specimen => {
-  try {
-    // In fact, it never returns undefined. It either returns a
-    // string or throws.
-    return passStyleOf(specimen) !== undefined;
-  } catch (_) {
-    return false;
-  }
-};
+export const isPassable = specimen => realIsPassable(specimen);

package/src/keys.d.ts

@@ -3,5 +3,5 @@
  *
  * @type {import('./types.js').KeyMakers}
  */
-export const agoricVatDataKeys: import('./types.js').KeyMakers;
+export const agoricVatDataKeys: import("./types.js").KeyMakers;
 //# sourceMappingURL=keys.d.ts.map

package/src/make-once.d.ts

@@ -1,5 +1,5 @@
-export function makeOnceKit(debugName: string, stores: import('./types.js').Stores, backingStore?: any): {
+export function makeOnceKit(debugName: string, stores: import("./types.js").Stores, backingStore?: globalThis.MapStore<string, any> | undefined): {
     makeOnce: <V>(key: string, maker: (key: string) => V) => V;
-    wrapProvider: <T extends (key: string, ...rest: unknown[]) => any>(provider: T, labelToKeys?: ((label: string) => string[]) | undefined) => T;
+    wrapProvider: <T extends (key: string, ...rest: any[]) => any>(provider: T, labelToKeys?: ((label: string) => string[]) | undefined) => T;
 };
 //# sourceMappingURL=make-once.d.ts.map

package/src/make-once.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make-once.d.ts","sourceRoot":"","sources":["make-once.js"],"names":[],"mappings":"AAYO,uCAJI,MAAM,UACN,OAAO,YAAY,EAAE,MAAM;uBA0DzB,MAAM,eACA,MAAM;mCA/BH,MAAM,WAAW,OAAO,EAAE,KAAK,GAAG,sCAEnC,MAAM,KAAK,MAAM,EAAE;EA6CvC"}
+{"version":3,"file":"make-once.d.ts","sourceRoot":"","sources":["make-once.js"],"names":[],"mappings":"AAYO,uCAJI,MAAM,UACN,OAAO,YAAY,EAAE,MAAM;eAyDvB,CAAC,OACH,MAAM,SACN,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,KAChB,CAAC;mBAhCsC,CAAC,SAAxC,CAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAI,YACxC,CAAC,yBACO,MAAM,KAAK,MAAM,EAAE,kBACzB,CAAC;EA4Cf"}

package/src/make-once.js

@@ -1,5 +1,5 @@
 // @ts-check
-const { Fail } = assert;
+import { Fail } from '@endo/errors';
 
 /** @param {string} label */
 const defaultLabelToKeys = label => harden([label]);
@@ -35,7 +35,7 @@ export const makeOnceKit = (debugName, stores, backingStore = undefined) => {
    * Ensure the wrapped function is only called once per incarnation.  It is
    * expected to update the backing store directly.
    *
-   * @template {(key: string, ...rest: unknown[]) => any} T
+   * @template {(key: string, ...rest: any[]) => any} T
    * @param {T} provider
    * @param {(label: string) => string[]} [labelToKeys]
    * @returns {T}

package/src/prepare-revocable.d.ts

@@ -1,9 +1,16 @@
-export function prepareRevocableKit<U extends unknown = any>(zone: import('@agoric/base-zone').Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<any> | undefined): (underlying: U) => RevocableKit<U>;
-export type Revoker = {
+export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<any> | undefined): RevocableMakerKit<U>;
+export type RevocableMakerKit<U = any> = {
+    revoke: (revocable: U) => boolean;
+    /**
+     *   Forwards to the underlying exo object, until revoked
+     */
+    makeRevocable: (underlying: U) => U;
+};
+export type RevokerFacet = {
     revoke: () => boolean;
 };
-export type RevocableKit<U extends unknown = any> = {
-    revoker: Revoker;
+export type RevocableKit<U = any> = {
+    revoker: RevokerFacet;
     /**
      *   Forwards to the underlying exo object, until revoked
      */
@@ -15,7 +22,7 @@ export type RevocableKitThis<U = any> = {
         underlying: U;
     };
 };
-export type RevocableKitOptions<U extends unknown = any> = {
+export type RevocableKitOptions<U = any> = {
     /**
      * The `interfaceName` of the underlying interface guard.
      * Defaults to the `uKindName`.

package/src/prepare-revocable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AA6DO,mEATI,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,sFAiF3B;;YAjIa,MAAM,OAAO;;;aAMb,OAAO;;;;eACP,CAAC;;;YAOD,aAAa,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;;;;;;;;;;;;;;;;;kDAkBnB,iBAAiB,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}
+{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AAqEO,yCAVO,CAAC,cACJ,OAAO,mBAAmB,EAAE,IAAI,aAChC,MAAM,gBAEN,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,mDAIf,iBAAiB,CAAC,CAAC,CAAC,CAyGhC;8BArKa,CAAC;YAED,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO;;;;mBACzB,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC;;;YAMpB,MAAM,OAAO;;yBAIb,CAAC;aAED,YAAY;;;;eACZ,CAAC;;6BAKD,CAAC;YAED,YAAY,CAAC,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;gCAIjB,CAAC;;;;;;;;;;;;;;;;kDAcH,gBAAgB,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG"}

package/src/prepare-revocable.js

@@ -1,17 +1,26 @@
-import { M } from '@endo/patterns';
+import { Fail, q } from '@endo/errors';
 import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+import { M } from '@endo/patterns';
 
-const { Fail, quote: q } = assert;
+/** @import {Amplify} from '@endo/exo'; */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableMakerKit
+ * @property {(revocable: U) => boolean} revoke
+ * @property {(underlying: U) => U} makeRevocable
+ *   Forwards to the underlying exo object, until revoked
+ */
 
 /**
- * @typedef {object} Revoker
+ * @typedef {object} RevokerFacet
  * @property {() => boolean} revoke
  */
 
 /**
- * @template {any} [U=any]
+ * @template [U=any]
  * @typedef {object} RevocableKit
- * @property {Revoker} revoker
+ * @property {RevokerFacet} revoker
  * @property {U} revocable
  *   Forwards to the underlying exo object, until revoked
  */
@@ -24,7 +33,7 @@ const { Fail, quote: q } = assert;
  */
 
 /**
- * @template {any} [U=any]
+ * @template [U=any]
  * @typedef {object} RevocableKitOptions
  * @property {string} [uInterfaceName]
  *   The `interfaceName` of the underlying interface guard.
@@ -48,8 +57,7 @@ const { Fail, quote: q } = assert;
  * Make an exo class kit for wrapping an underlying exo class,
  * where the wrapper is a revocable forwarder.
  *
- * @deprecated Change to `prepareRevocableMakerKit` once #8977 happens
- * @template {any} [U=any]
+ * @template [U=any]
  * @param {import('@agoric/base-zone').Zone} zone
  * @param {string} uKindName
  *   The `kindName` of the underlying exo class
@@ -57,9 +65,9 @@ const { Fail, quote: q } = assert;
  *   The method names of the underlying exo class that should be represented
  *   by transparently-forwarding methods of the revocable caretaker.
  * @param {RevocableKitOptions} [options]
- * @returns {(underlying: U) => RevocableKit<U>}
+ * @returns {RevocableMakerKit<U>}
  */
-export const prepareRevocableKit = (
+export const prepareRevocableMakerKit = (
   zone,
   uKindName,
   uMethodNames,
@@ -87,6 +95,9 @@ export const prepareRevocableKit = (
 
   const revocableKindName = `${uKindName}_caretaker`;
 
+  /** @type {Amplify<any>} */
+  let amplifier;
+
   const makeRevocableKit = zone.exoClassKit(
     revocableKindName,
     RevocableIKit,
@@ -128,11 +139,36 @@ export const prepareRevocableKit = (
       stateShape: {
         underlying: M.opt(M.remotable('underlying')),
       },
+      receiveAmplifier: amp => {
+        amplifier = amp;
+      },
     },
   );
 
-  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
-  // @ts-ignore parameter confusion
-  return makeRevocableKit;
+  /**
+   * @param {U} underlying
+   * @returns {U}
+   */
+  const makeRevocable = underlying =>
+    // @ts-expect-error some confusion about UU vs Guarded<U> I think
+    makeRevocableKit(underlying).revocable;
+
+  /**
+   * @param {U} revocable
+   * @returns {boolean}
+   */
+  const revoke = revocable => {
+    /** @type {RevocableKit<U>} */
+    const facets = amplifier(revocable);
+    if (facets === undefined) {
+      return false;
+    }
+    return facets.revoker.revoke();
+  };
+
+  return harden({
+    revoke,
+    makeRevocable,
+  });
 };
-harden(prepareRevocableKit);
+harden(prepareRevocableMakerKit);

package/src/types.d.ts

@@ -1,11 +1,5 @@
-export type KeyCategories = 'exoClass' | 'exoClassKit' | 'exo' | 'store' | 'zone';
-export type KeyMakers = {
-    exoClass: (label: string) => string[];
-    exoClassKit: (label: string) => string[];
-    exo: (label: string) => string[];
-    store: (label: string) => string[];
-    zone: (label: string) => string[];
-};
+export type KeyCategories = "exoClass" | "exoClassKit" | "exo" | "store" | "zone";
+export type KeyMakers = Record<KeyCategories, (label: string) => string[]>;
 /**
  * A bag of methods for creating defensible objects and
  * collections with the same allocation semantics (ephemeral, persistent, etc)
@@ -32,6 +26,10 @@ export type ExoZone = {
      * create a new Zone that can be passed to untrusted consumers without exposing the storage of the parent zone
      */
     subZone: (label: string, options?: StoreOptions) => Zone;
+    /**
+     * register a promise watcher created by this zone
+     */
+    watchPromise: typeof watchPromise;
 };
 export type Stores = {
     /**
@@ -45,21 +43,22 @@ export type Stores = {
     /**
      * provide a Map-like store named `label` in the zone
      */
-    mapStore: <K, V>(label: string, options?: StoreOptions) => MapStore<K, V>;
+    mapStore: (label: string, options?: StoreOptions) => MapStore<any, any>;
     /**
      * provide a Set-like store named `label` in the zone
      */
-    setStore: <K_1>(label: string, options?: StoreOptions) => SetStore<K_1>;
+    setStore: <K>(label: string, options?: StoreOptions) => SetStore<K>;
     /**
      * provide a WeakMap-like store named `label` in the zone
      */
-    weakMapStore: <K_2, V_1>(label: string, options?: StoreOptions) => WeakMapStore<K_2, V_1>;
+    weakMapStore: <K, V>(label: string, options?: StoreOptions) => WeakMapStore<K, V>;
     /**
      * provide a WeakSet-like store named `label` in the zone
      */
-    weakSetStore: <K_3>(label: string, options?: StoreOptions) => WeakSetStore<K_3>;
+    weakSetStore: <K>(label: string, options?: StoreOptions) => WeakSetStore<K>;
 };
 import { makeExo } from '@endo/exo';
 import { defineExoClass } from '@endo/exo';
 import { defineExoClassKit } from '@endo/exo';
+import { watchPromise } from './watch-promise.js';
 //# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"4BAGc,UAAU,GAAG,aAAa,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM;;sBACvB,MAAM,KAAK,MAAM,EAAE;yBAAnB,MAAM,KAAK,MAAM,EAAE;iBAAnB,MAAM,KAAK,MAAM,EAAE;mBAAnB,MAAM,KAAK,MAAM,EAAE;kBAAnB,MAAM,KAAK,MAAM,EAAE;;;;;;mBAGlD,OAAO,GAAG,MAAM;;;;;SAMf,cAAc;;;;cACd,qBAAqB;;;;iBACrB,wBAAwB;;;;uBACf,MAAM,eAAe,MAAM;;;;qBAC5B,MAAM,YAAY,YAAY,KAAK,IAAI;;;;;;cAK/C,MAAM,MAAM;;;;2BACD,OAAO,KAAK,OAAO;;;;4BACjB,MAAM,YAAY,YAAY;;;;2BAChC,MAAM,YAAY,YAAY;;;;oCAE3C,MAAM,YAAY,YAAY;;;;+BAG9B,MAAM,YAAY,YAAY;;wBA7BiB,WAAW;+BAAX,WAAW;kCAAX,WAAW"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"4BAac,UAAU,GAAG,aAAa,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM;wBACrD,MAAM,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;;;;;mBAGnD,OAAO,GAAG,MAAM;;;;;SAMf,OAAO,OAAO;;;;cACd,OAAO,cAAc;;;;iBACrB,OAAO,iBAAiB;;;;cACxB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,KAAK,CAAC;;;;aAChD,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI;;;;kBAC/C,OAAO,YAAY;;;;;;cAKnB,MAAM,MAAM;;;;gBACZ,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO;;;;cAC9B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;;;;cAC7D,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC;;;;kBACzD,CAAC,CAAC,EAAE,CAAC,EAClB,KAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;kBAEnD,CAAC,CAAC,EACf,KAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,CAAC;;wBAxCH,WAAW;+BAAX,WAAW;kCAAX,WAAW;6BAEzC,oBAAoB"}

package/src/types.js

@@ -1,5 +1,15 @@
 // eslint-disable-next-line no-unused-vars
 import { makeExo, defineExoClass, defineExoClassKit } from '@endo/exo';
+// eslint-disable-next-line no-unused-vars
+import { watchPromise } from './watch-promise.js';
+
+// Ensure this is a module.
+export {};
+
+/**
+ * @import {Key} from '@endo/patterns';
+ * @import {Passable} from '@endo/pass-style';
+ */
 
 /** @typedef {'exoClass' | 'exoClassKit' | 'exo' | 'store' | 'zone'} KeyCategories */
 /** @typedef {Record<KeyCategories, (label: string) => string[]>} KeyMakers */
@@ -16,15 +26,16 @@ import { makeExo, defineExoClass, defineExoClassKit } from '@endo/exo';
  * @property {typeof defineExoClassKit} exoClassKit create a "kit" maker function that can be used to create a record of exo-objects sharing the same state
  * @property {<T>(key: string, maker: (key: string) => T) => T} makeOnce create or retrieve a singleton object bound to this zone
  * @property {(label: string, options?: StoreOptions) => Zone} subZone create a new Zone that can be passed to untrusted consumers without exposing the storage of the parent zone
+ * @property {typeof watchPromise} watchPromise register a promise watcher created by this zone
  */
 
 /**
  * @typedef {object} Stores
  * @property {() => Stores} detached obtain store providers which are detached (the stores are anonymous rather than bound to `label` in the zone)
  * @property {(specimen: unknown) => boolean} isStorable return true if the specimen can be stored in the zone, whether as exo-object state or in a store
- * @property {<K,V>(label: string, options?: StoreOptions) => MapStore<K, V>} mapStore provide a Map-like store named `label` in the zone
+ * @property {(label: string, options?: StoreOptions) => MapStore<any, any>} mapStore provide a Map-like store named `label` in the zone
  * @property {<K>(label: string, options?: StoreOptions) => SetStore<K>} setStore provide a Set-like store named `label` in the zone
- * @property {<K,V>(
+ * @property {<K, V>(
  *   label: string, options?: StoreOptions) => WeakMapStore<K, V>
  * } weakMapStore provide a WeakMap-like store named `label` in the zone
  * @property {<K>(

package/src/watch-promise.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A PromiseWatcher method guard callable with or more arguments, returning void.
+ */
+export const PromiseWatcherHandler: import("@endo/patterns").MethodGuard;
+/**
+ * A PromiseWatcher interface that has both onFulfilled and onRejected handlers.
+ */
+export const PromiseWatcherI: import("@endo/patterns").InterfaceGuard<{
+    onFulfilled: import("@endo/patterns").MethodGuard;
+    onRejected: import("@endo/patterns").MethodGuard;
+}>;
+/**
+ * A PromiseWatcher interface that has only an onFulfilled handler.
+ */
+export const PromiseWatcherFulfilledI: import("@endo/patterns").InterfaceGuard<{
+    onFulfilled: import("@endo/patterns").MethodGuard;
+}>;
+/**
+ * A PromiseWatcher interface that has only an onRejected handler.
+ */
+export const PromiseWatcherRejectedI: import("@endo/patterns").InterfaceGuard<{
+    onRejected: import("@endo/patterns").MethodGuard;
+}>;
+export function watchPromise(p: Promise<any>, watcher: PromiseWatcher, ...watcherArgs: unknown[]): void;
+export type PromiseWatcher = {
+    onFulfilled?: ((fulfilment: unknown, ...args: unknown[]) => void) | undefined;
+    onRejected?: ((reason: unknown, ...args: unknown[]) => void) | undefined;
+};
+//# sourceMappingURL=watch-promise.d.ts.map

package/src/watch-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-promise.d.ts","sourceRoot":"","sources":["watch-promise.js"],"names":[],"mappings":"AAOA;;GAEG;AACH,yEAA6E;AAE7E;;GAEG;AACH;;;GAGG;AAEH;;GAEG;AACH;;GAEG;AAEH;;GAEG;AACH;;GAEG;AAuCI,gCALI,OAAO,CAAC,GAAG,CAAC,WACZ,cAAc,kBACX,OAAO,EAAA,GACR,IAAI,CAUhB;;gCA3C0B,OAAO,WAAW,OAAO,EAAE,KAAK,IAAI;2BACxC,OAAO,WAAW,OAAO,EAAE,KAAK,IAAI"}

package/src/watch-promise.js

@@ -0,0 +1,81 @@
+// @ts-check
+import { Fail } from '@endo/errors';
+import { M } from '@endo/patterns';
+import { E } from '@endo/far';
+
+const { apply } = Reflect;
+
+/**
+ * A PromiseWatcher method guard callable with or more arguments, returning void.
+ */
+export const PromiseWatcherHandler = M.call(M.raw()).rest(M.raw()).returns();
+
+/**
+ * A PromiseWatcher interface that has both onFulfilled and onRejected handlers.
+ */
+export const PromiseWatcherI = M.interface('PromiseWatcher', {
+  onFulfilled: PromiseWatcherHandler,
+  onRejected: PromiseWatcherHandler,
+});
+
+/**
+ * A PromiseWatcher interface that has only an onFulfilled handler.
+ */
+export const PromiseWatcherFulfilledI = M.interface('PromiseWatcherFulfilled', {
+  onFulfilled: PromiseWatcherHandler,
+});
+
+/**
+ * A PromiseWatcher interface that has only an onRejected handler.
+ */
+export const PromiseWatcherRejectedI = M.interface('PromiseWatcherRejected', {
+  onRejected: PromiseWatcherHandler,
+});
+
+/**
+ * @typedef {object} PromiseWatcher
+ * @property {(fulfilment: unknown, ...args: unknown[]) => void} [onFulfilled]
+ * @property {(reason: unknown, ...args: unknown[]) => void} [onRejected]
+ */
+
+/**
+ * Adapt a promise watcher method to E.when.
+ * @param {Record<PropertyKey, (...args: unknown[]) => unknown>} that
+ * @param {PropertyKey} prop
+ * @param {unknown[]} postArgs
+ */
+const callMeMaybe = (that, prop, postArgs) => {
+  const fn = that[prop];
+  if (!fn) {
+    return undefined;
+  }
+  assert.typeof(fn, 'function');
+  /**
+   * @param {unknown} arg value or reason
+   */
+  const wrapped = arg => {
+    // Don't return a value, to prevent E.when from subscribing to a resulting
+    // promise.
+    apply(fn, that, [arg, ...postArgs]);
+  };
+  return wrapped;
+};
+
+/**
+ * Shim the promise watcher behaviour when VatData.watchPromise is not available.
+ *
+ * @param {Promise<any>} p
+ * @param {PromiseWatcher} watcher
+ * @param {...unknown} watcherArgs
+ * @returns {void}
+ */
+export const watchPromise = (p, watcher, ...watcherArgs) => {
+  Promise.resolve(p) === p || Fail`watchPromise only watches promises`;
+  const onFulfilled = callMeMaybe(watcher, 'onFulfilled', watcherArgs);
+  const onRejected = callMeMaybe(watcher, 'onRejected', watcherArgs);
+  onFulfilled ||
+    onRejected ||
+    Fail`promise watcher must implement at least one handler method`;
+  void E.when(p, onFulfilled, onRejected);
+};
+harden(watchPromise);

package/test/{test-exos.js → exos.test.js}

@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/order
 import { test } from './prepare-test-env-ava.js';
 
 import { makeHeapZone } from '../heap.js';

package/test/{test-prepare-revocable.js → prepare-revocable.test.js}

@@ -5,7 +5,7 @@ import { test } from './prepare-test-env-ava.js';
 // eslint-disable-next-line import/order
 import { M } from '@endo/patterns';
 import { makeHeapZone } from '../src/heap.js';
-import { prepareRevocableKit } from '../src/prepare-revocable.js';
+import { prepareRevocableMakerKit } from '../src/prepare-revocable.js';
 
 const UpCounterI = M.interface('UpCounter', {
   incr: M.call()
@@ -38,16 +38,17 @@ test('test revoke defineVirtualExoClass', t => {
     },
   );
 
-  const makeRevocableUpCounterKit = prepareRevocableKit(zone, 'UpCounter', [
-    'incr',
-  ]);
+  const { revoke, makeRevocable } = prepareRevocableMakerKit(
+    zone,
+    'UpCounter',
+    ['incr'],
+  );
 
-  const makeUpCounterKit = x =>
-    makeRevocableUpCounterKit(makeUnderlyingUpCounter(x));
+  const makeUpCounter = x => makeRevocable(makeUnderlyingUpCounter(x));
 
-  const { revoker, revocable: upCounter } = makeUpCounterKit(3);
+  const upCounter = makeUpCounter(3);
   t.is(upCounter.incr(5), 8);
-  t.is(revoker.revoke(), true);
+  t.is(revoke(upCounter), true);
   t.throws(() => upCounter.incr(1), {
     message: '"UpCounter_caretaker" revoked',
   });
@@ -79,7 +80,7 @@ test('test revoke defineVirtualExoClassKit', t => {
     },
   );
 
-  const makeRevocableUpCounterKit = prepareRevocableKit(
+  const { revoke, makeRevocable } = prepareRevocableMakerKit(
     zone,
     'UpCounter',
     ['incr'],
@@ -89,8 +90,12 @@ test('test revoke defineVirtualExoClassKit', t => {
       },
       extraMethods: {
         selfRevoke() {
-          const { revoker } = this.facets;
-          return revoker.revoke();
+          // Could directly use the revoker facet instead, but this
+          // should now be considered more of an internal detail that
+          // we should deemphasize. This tests the code pattern we wish
+          // to encourage.
+          const { revocable } = this.facets;
+          return revoke(revocable);
         },
       },
     },
@@ -98,8 +103,7 @@ test('test revoke defineVirtualExoClassKit', t => {
 
   const makeCounterKit = x => {
     const { up: upCounter, down: downCounter } = makeUnderlyingCounterKit(x);
-    const { revocable: revocableUpCounter } =
-      makeRevocableUpCounterKit(upCounter);
+    const revocableUpCounter = makeRevocable(upCounter);
     return harden({
       up: revocableUpCounter,
       down: downCounter,

package/tsconfig.json

@@ -1,9 +1,7 @@
 // This file can contain .js-specific Typescript compiler config.
 {
   "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "maxNodeModuleJsDepth": 2,
-  },
+  "compilerOptions": {},
   "include": [
     "*.js",
     "scripts",