@endo/eventual-send 1.0.1 → 1.1.1

package/README.md

@@ -8,8 +8,6 @@ Create a HandledPromise class to implement the eventual-send API.  This API is u
 
 ## How to use
 
-> Note: If you're writing an application, you probably don't want to use this package directly. You'll want to use the eventual-send `~.` operator (tildot) provided in [SES](https://github.com/Agoric/SES) or other platforms.
-
 To install the `HandledPromise` global property shim, do:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo/eventual-send",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Extend a Promise class to implement the eventual-send API",
   "type": "module",
   "main": "src/no-shim.js",
@@ -26,7 +26,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/endojs/endo.git"
+    "url": "git+https://github.com/endojs/endo.git",
+    "directory": "packages/eventual-send"
   },
   "author": "Endo contributors",
   "license": "Apache-2.0",
@@ -35,11 +36,11 @@
   },
   "homepage": "https://github.com/endojs/endo#readme",
   "dependencies": {
-    "@endo/env-options": "^1.0.1"
+    "@endo/env-options": "^1.1.1"
   },
   "devDependencies": {
-    "@endo/lockdown": "^1.0.1",
-    "@endo/ses-ava": "^1.0.1",
+    "@endo/lockdown": "^1.0.3",
+    "@endo/ses-ava": "^1.1.1",
     "ava": "^5.3.0",
     "c8": "^7.14.0",
     "tsd": "^0.28.1"
@@ -70,7 +71,7 @@
     "timeout": "2m"
   },
   "typeCoverage": {
-    "atLeast": 77.79
+    "atLeast": 77.81
   },
-  "gitHead": "c02aec92c3caa417d6bdf3c4f555f0b2694d9f9e"
+  "gitHead": "f731c5c12f8d185dbf2daf53ec6a57e5ac56e4e9"
 }

package/src/E.d.ts

@@ -1,15 +1,7 @@
 export default makeE;
 export type EProxy = ReturnType<(HandledPromise: {
     new <R>(executor: import("./handled-promise.js").HandledExecutor<R>, unfulfilledHandler?: import("./handled-promise.js").Handler<Promise<unknown>> | undefined): Promise<R>;
-    prototype: Promise<unknown>; /**
-     * E.sendOnly returns a proxy similar to E, but for which the results
-     * are ignored (undefined is returned).
-     *
-     * @template T
-     * @param {T} x target for method/function call
-     * @returns {ESendOnlyCallableOrMethods<RemoteFunctions<T>>} method/function call proxy
-     * @readonly
-     */
+    prototype: Promise<unknown>;
 } & PromiseConstructor & import("./handled-promise.js").HandledPromiseStaticMethods) => (<T>(x: T) => ECallableOrMethods<RemoteFunctions<T>>) & {
     /**
      * E.get(x) returns a proxy on which you can get arbitrary properties.

package/src/E.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":";qBAiNc;;iCArCN;;;;;;;;OAQG;;IAnCH;;;;;;;;;;OAUG;;IAMH;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;;IAMH;;;;;;;;;;;OAWG;;EAYoB;;;;;yDAQlB,KAAK,KAAK,GAAG,OAAO,SAAS,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;;;;;0BAQ9D,KAAK,CAAC,EAAE,aAAa,CAAC,EAAE,OAAO,SAAS,EAAE,QAAQ,CAAC,CAAC;sBAMpD,YAAY,CAAC,CAAC,GAAG,CAAC;yHAQZ,WAAW,CAAC,CAAC,KAAK,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC;;;gFAwB7C,WAAW,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC;;4CAczC,CACZ,CAAK,SAAS,OAAO,SAAS,EAAE,QAAQ,GAChC,kBAAkB,CAAC,CAAC,GAAG,iBAAiB,SAAS,CAAC,CAAC,CAAC,GACpD,iBAAiB,SAAS,CAAC,CAAC,CAAC,CAClC;oCAKS,CACZ,CAAK,SAAS,OAAO,SAAS,EAAE,QAAQ,GAChC,UAAU,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,GACpC,SAAS,SAAS,CAAC,CAAC,CAAC,CAC1B;;;;;;;;;;;;;;;;+EAyBe,WAAW,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC;;;;;;uCAmCrC;IACZ,OAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxB,OAAW,EAAE,OAAO,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACvC;;;;;wEAUe,WAAW,CAAC,CAAC,KAAK,KAAK,QAAQ,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AA3OxE;;GAEG;AACH,uCAFW,OAAO,SAAS,EAAE,yBAAyB;IAgB9C;;;;;;;;;;OAUG;;IAMH;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;;IAMH;;;;;;;;;;;OAWG;yIAHiB,GAAG;EAW9B"}
+{"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":";qBAoPc;;;;IAhEN;;;;;;;;;;OAUG;;IAMH;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;;IAMH;;;;;;;;;;;OAWG;;EAYoB;;;;;yDAQlB,KAAK,KAAK,GAAG,OAAO,SAAS,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;;;;;0BAQ9D,KAAK,CAAC,EAAE,aAAa,CAAC,EAAE,OAAO,SAAS,EAAE,QAAQ,CAAC,CAAC;sBAMpD,YAAY,CAAC,CAAC,GAAG,CAAC;yHAQZ,WAAW,CAAC,CAAC,KAAK,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC;;;gFAwB7C,WAAW,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC;;4CAczC,CACZ,CAAK,SAAS,OAAO,SAAS,EAAE,QAAQ,GAChC,kBAAkB,CAAC,CAAC,GAAG,iBAAiB,SAAS,CAAC,CAAC,CAAC,GACpD,iBAAiB,SAAS,CAAC,CAAC,CAAC,CAClC;oCAKS,CACZ,CAAK,SAAS,OAAO,SAAS,EAAE,QAAQ,GAChC,UAAU,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,GACpC,SAAS,SAAS,CAAC,CAAC,CAAC,CAC1B;;;;;;;;;;;;;;;;+EAyBe,WAAW,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC;;;;;;uCAmCrC;IACZ,OAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxB,OAAW,EAAE,OAAO,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACvC;;;;;wEAUe,WAAW,CAAC,CAAC,KAAK,KAAK,QAAQ,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AA3OxE;;GAEG;AACH,uCAFW,OAAO,SAAS,EAAE,yBAAyB;IAgB9C;;;;;;;;;;OAUG;;IAMH;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;;IAMH;;;;;;;;;;;OAWG;yIAHiB,GAAG;EAW9B"}

package/src/E.js

@@ -1,8 +1,11 @@
 import { trackTurns } from './track-turns.js';
+import { makeMessageBreakpointTester } from './message-breakpoints.js';
 
 const { details: X, quote: q, Fail } = assert;
 const { assign, create } = Object;
 
+const onSend = makeMessageBreakpointTester('ENDO_SEND_BREAKPOINTS');
+
 /** @type {ProxyHandler<any>} */
 const baseFreezableProxyHandler = {
   set(_target, _prop, _value) {
@@ -31,38 +34,55 @@ const baseFreezableProxyHandler = {
 /**
  * A Proxy handler for E(x).
  *
- * @param {any} x Any value passed to E(x)
+ * @param {any} recipient Any value passed to E(x)
  * @param {import('./types').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
-const makeEProxyHandler = (x, HandledPromise) =>
+const makeEProxyHandler = (recipient, HandledPromise) =>
   harden({
     ...baseFreezableProxyHandler,
-    get: (_target, p, receiver) => {
+    get: (_target, propertyKey, receiver) => {
       return harden(
         {
           // This function purposely checks the `this` value (see above)
           // In order to be `this` sensitive it is defined using concise method
           // syntax rather than as an arrow function. To ensure the function
           // is not constructable, it also avoids the `function` syntax.
-          [p](...args) {
+          [propertyKey](...args) {
             if (this !== receiver) {
               // Reject the async function call
               return HandledPromise.reject(
                 assert.error(
-                  X`Unexpected receiver for "${p}" method of E(${q(x)})`,
+                  X`Unexpected receiver for "${q(propertyKey)}" method of E(${q(
+                    recipient,
+                  )})`,
                 ),
               );
             }
 
-            return HandledPromise.applyMethod(x, p, args);
+            if (onSend && onSend.shouldBreakpoint(recipient, propertyKey)) {
+              // eslint-disable-next-line no-debugger
+              debugger; // LOOK UP THE STACK
+              // Stopped at a breakpoint on eventual-send of a method-call
+              // message,
+              // so that you can walk back on the stack to see how we came to
+              // make this eventual-send
+            }
+            return HandledPromise.applyMethod(recipient, propertyKey, args);
           },
           // @ts-expect-error https://github.com/microsoft/TypeScript/issues/50319
-        }[p],
+        }[propertyKey],
       );
     },
     apply: (_target, _thisArg, argArray = []) => {
-      return HandledPromise.applyFunction(x, argArray);
+      if (onSend && onSend.shouldBreakpoint(recipient, undefined)) {
+        // eslint-disable-next-line no-debugger
+        debugger; // LOOK UP THE STACK
+        // Stopped at a breakpoint on eventual-send of a function-call message,
+        // so that you can walk back on the stack to see how we came to
+        // make this eventual-send
+      }
+      return HandledPromise.applyFunction(recipient, argArray);
     },
     has: (_target, _p) => {
       // We just pretend everything exists.
@@ -74,35 +94,50 @@ const makeEProxyHandler = (x, HandledPromise) =>
  * A Proxy handler for E.sendOnly(x)
  * It is a variant on the E(x) Proxy handler.
  *
- * @param {any} x Any value passed to E.sendOnly(x)
+ * @param {any} recipient Any value passed to E.sendOnly(x)
  * @param {import('./types').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
-const makeESendOnlyProxyHandler = (x, HandledPromise) =>
+const makeESendOnlyProxyHandler = (recipient, HandledPromise) =>
   harden({
     ...baseFreezableProxyHandler,
-    get: (_target, p, receiver) => {
+    get: (_target, propertyKey, receiver) => {
       return harden(
         {
           // This function purposely checks the `this` value (see above)
           // In order to be `this` sensitive it is defined using concise method
           // syntax rather than as an arrow function. To ensure the function
           // is not constructable, it also avoids the `function` syntax.
-          [p](...args) {
+          [propertyKey](...args) {
             // Throw since the function returns nothing
             this === receiver ||
-              Fail`Unexpected receiver for "${q(p)}" method of E.sendOnly(${q(
-                x,
-              )})`;
-            HandledPromise.applyMethodSendOnly(x, p, args);
+              Fail`Unexpected receiver for "${q(
+                propertyKey,
+              )}" method of E.sendOnly(${q(recipient)})`;
+            if (onSend && onSend.shouldBreakpoint(recipient, propertyKey)) {
+              // eslint-disable-next-line no-debugger
+              debugger; // LOOK UP THE STACK
+              // Stopped at a breakpoint on eventual-send of a method-call
+              // message,
+              // so that you can walk back on the stack to see how we came to
+              // make this eventual-send
+            }
+            HandledPromise.applyMethodSendOnly(recipient, propertyKey, args);
             return undefined;
           },
           // @ts-expect-error https://github.com/microsoft/TypeScript/issues/50319
-        }[p],
+        }[propertyKey],
       );
     },
     apply: (_target, _thisArg, argsArray = []) => {
-      HandledPromise.applyFunctionSendOnly(x, argsArray);
+      if (onSend && onSend.shouldBreakpoint(recipient, undefined)) {
+        // eslint-disable-next-line no-debugger
+        debugger; // LOOK UP THE STACK
+        // Stopped at a breakpoint on eventual-send of a function-call message,
+        // so that you can walk back on the stack to see how we came to
+        // make this eventual-send
+      }
+      HandledPromise.applyFunctionSendOnly(recipient, argsArray);
       return undefined;
     },
     has: (_target, _p) => {

package/src/local.d.ts

@@ -1,5 +1,5 @@
 export function getMethodNames(val: any): (string | symbol)[];
-export function localApplyFunction(t: any, args: any): any;
-export function localApplyMethod(t: any, method: any, args: any): any;
+export function localApplyFunction(recipient: any, args: any): any;
+export function localApplyMethod(recipient: any, methodName: any, args: any): any;
 export function localGet(t: any, key: any): any;
 //# sourceMappingURL=local.d.ts.map

package/src/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["local.js"],"names":[],"mappings":"AA0CO,oCAHI,GAAG,GACD,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,CAqB7B;AAKM,2DAON;AAEM,sEAwBN;AAEM,gDAAmC"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["local.js"],"names":[],"mappings":"AA8CO,oCAHI,GAAG,GACD,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,CAqB7B;AAKM,mEAkBN;AAEM,kFAqCN;AAEM,gDAAmC"}

package/src/local.js

@@ -1,3 +1,5 @@
+import { makeMessageBreakpointTester } from './message-breakpoints.js';
+
 const { details: X, quote: q, Fail } = assert;
 
 const { getOwnPropertyDescriptors, getPrototypeOf, freeze } = Object;
@@ -5,6 +7,8 @@ const { apply, ownKeys } = Reflect;
 
 const ntypeof = specimen => (specimen === null ? 'null' : typeof specimen);
 
+const onDelivery = makeMessageBreakpointTester('ENDO_DELIVERY_BREAKPOINTS');
+
 /**
  * TODO Consolidate with `isObject` that's currently in `@endo/marshal`
  *
@@ -64,39 +68,63 @@ export const getMethodNames = val => {
 // ses creates `harden`, and so cannot rely on `harden` at top level.
 freeze(getMethodNames);
 
-export const localApplyFunction = (t, args) => {
-  typeof t === 'function' ||
+export const localApplyFunction = (recipient, args) => {
+  typeof recipient === 'function' ||
     assert.fail(
-      X`Cannot invoke target as a function; typeof target is ${q(ntypeof(t))}`,
+      X`Cannot invoke target as a function; typeof target is ${q(
+        ntypeof(recipient),
+      )}`,
       TypeError,
     );
-  return apply(t, undefined, args);
+  if (onDelivery && onDelivery.shouldBreakpoint(recipient, undefined)) {
+    // eslint-disable-next-line no-debugger
+    debugger; // STEP INTO APPLY
+    // Stopped at a breakpoint on this delivery of an eventual function call
+    // so that you can step *into* the following `apply` in order to see the
+    // function call as it happens. Or step *over* to see what happens
+    // after the function call returns.
+  }
+  const result = apply(recipient, undefined, args);
+  return result;
 };
 
-export const localApplyMethod = (t, method, args) => {
-  if (method === undefined || method === null) {
+export const localApplyMethod = (recipient, methodName, args) => {
+  if (methodName === undefined || methodName === null) {
     // Base case; bottom out to apply functions.
-    return localApplyFunction(t, args);
+    return localApplyFunction(recipient, args);
   }
-  if (t === undefined || t === null) {
+  if (recipient === undefined || recipient === null) {
     assert.fail(
-      X`Cannot deliver ${q(method)} to target; typeof target is ${q(
-        ntypeof(t),
+      X`Cannot deliver ${q(methodName)} to target; typeof target is ${q(
+        ntypeof(recipient),
       )}`,
       TypeError,
     );
   }
-  const fn = t[method];
+  const fn = recipient[methodName];
   if (fn === undefined) {
     assert.fail(
-      X`target has no method ${q(method)}, has ${q(getMethodNames(t))}`,
+      X`target has no method ${q(methodName)}, has ${q(
+        getMethodNames(recipient),
+      )}`,
       TypeError,
     );
   }
   const ftype = ntypeof(fn);
   typeof fn === 'function' ||
-    Fail`invoked method ${q(method)} is not a function; it is a ${q(ftype)}`;
-  return apply(fn, t, args);
+    Fail`invoked method ${q(methodName)} is not a function; it is a ${q(
+      ftype,
+    )}`;
+  if (onDelivery && onDelivery.shouldBreakpoint(recipient, methodName)) {
+    // eslint-disable-next-line no-debugger
+    debugger; // STEP INTO APPLY
+    // Stopped at a breakpoint on this delivery of an eventual method call
+    // so that you can step *into* the following `apply` in order to see the
+    // method call as it happens. Or step *over* to see what happens
+    // after the method call returns.
+  }
+  const result = apply(fn, recipient, args);
+  return result;
 };
 
 export const localGet = (t, key) => t[key];

package/src/message-breakpoints.d.ts

@@ -0,0 +1,44 @@
+export function makeMessageBreakpointTester(optionName: string): MessageBreakpointTester | undefined;
+/**
+ * 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.
+ */
+export type MatchStringTag = string | '*';
+/**
+ * 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.
+ */
+export type MatchMethodName = string | '*';
+/**
+ * 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.
+ */
+export type MatchCountdown = number | '*';
+/**
+ * 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 '*'.
+ */
+export type MessageBreakpoints = Record<MatchStringTag, Record<MatchMethodName, MatchCountdown>>;
+/**
+ * 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 '*'.
+ */
+export type BreakpointTable = Record<MatchMethodName, Record<MatchStringTag, MatchCountdown>>;
+export type MessageBreakpointTester = {
+    getBreakpoints: () => MessageBreakpoints;
+    setBreakpoints: (newBreakpoints?: MessageBreakpoints) => void;
+    shouldBreakpoint: (recipient: object, methodName: string | symbol | undefined) => boolean;
+};
+//# sourceMappingURL=message-breakpoints.d.ts.map

package/src/message-breakpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-breakpoints.d.ts","sourceRoot":"","sources":["message-breakpoints.js"],"names":[],"mappings":"AAyFO,wDAHI,MAAM,GACJ,uBAAuB,GAAG,SAAS,CA0F/C;;;;;;;;6BA1KY,MAAM,GAAG,GAAG;;;;;;;8BAQZ,MAAM,GAAG,GAAG;;;;;;;;6BAOZ,MAAM,GAAG,GAAG;;;;;;;iCAcZ,OAAO,cAAc,EAAE,OAAO,eAAe,EAAE,cAAc,CAAC,CAAC;;;;;;;8BAS/D,OAAO,eAAe,EAAE,OAAO,cAAc,EAAE,cAAc,CAAC,CAAC;;oBAK9D,MAAM,kBAAkB;sCACN,kBAAkB,KAAK,IAAI;kCAE3C,MAAM,cACL,MAAM,GAAG,MAAM,GAAG,SAAS,KACpC,OAAO"}

package/src/message-breakpoints.js

@@ -0,0 +1,179 @@
+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/track-turns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"track-turns.d.ts","sourceRoot":"","sources":["track-turns.js"],"names":[],"mappings":"AA4FO,mEAiBN;;;;;uCAMuB,GAAG,EAAE,KAAK,GAAG"}
+{"version":3,"file":"track-turns.d.ts","sourceRoot":"","sources":["track-turns.js"],"names":[],"mappings":"AAwFO,mEAiBN;;;;;uCAMuB,GAAG,EAAE,KAAK,GAAG"}

package/src/track-turns.js

@@ -1,7 +1,8 @@
 /* global globalThis */
-import { makeEnvironmentCaptor } from '@endo/env-options';
-
-const { getEnvironmentOption } = makeEnvironmentCaptor(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';
@@ -17,18 +18,13 @@ let hiddenPriorError;
 let hiddenCurrentTurn = 0;
 let hiddenCurrentEvent = 0;
 
-const DEBUG = getEnvironmentOption('DEBUG', '');
-
 // Turn on if you seem to be losing error logging at the top of the event loop
-const VERBOSE = DEBUG.split(':').includes('track-turns');
+const VERBOSE = environmentOptionsListHas('DEBUG', 'track-turns');
 
 // Track-turns is disabled by default and can be enabled by an environment
 // option.
-const TRACK_TURNS = getEnvironmentOption('TRACK_TURNS', 'disabled');
-if (TRACK_TURNS !== 'enabled' && TRACK_TURNS !== 'disabled') {
-  throw TypeError(`unrecognized TRACK_TURNS ${JSON.stringify(TRACK_TURNS)}`);
-}
-const ENABLED = (TRACK_TURNS || 'disabled') === 'enabled';
+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,

package/utils.d.ts

@@ -1,2 +1,3 @@
 export { getMethodNames } from "./src/local.js";
+export { makeMessageBreakpointTester } from "./src/message-breakpoints.js";
 //# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -1 +1,2 @@
 export { getMethodNames } from './src/local.js';
+export { makeMessageBreakpointTester } from './src/message-breakpoints.js';