@endo/eventual-send 1.3.4 → 1.5.0

package/README.md

@@ -1,28 +1,332 @@
-# HandledPromise
+# `@endo/eventual-send`
 
-[![dependency status][deps-svg]][deps-url]
-[![dev dependency status][dev-deps-svg]][dev-deps-url]
-[![License][license-image]][license-url]
+Eventual send: a uniform async messaging API for local and remote objects.
 
-Create a HandledPromise class to implement the eventual-send API.  This API is used by the [ECMAScript eventual-send proposal](https://github.com/tc39/proposal-eventual-send).
+## Overview
 
-## How to use
+The **@endo/eventual-send** package provides the `E()` proxy for asynchronous
+message passing.
+Whether an object is in the same vat, a different vat, or across a network,
+`E()` provides a consistent API that always returns promises.
 
-To install the `HandledPromise` global property shim, do:
+This enables:
+- **Uniform communication**: Same code for local and remote objects
+- **Promise pipelining**: Chain operations without waiting for resolution
+- **Message ordering**: Preserve message order per target
+- **Future-proof code**: Local code works when migrated to distributed systems
+
+## Shim
+
+Eventual send relies on an Endo environment.
+Programs running in an existing Endo platform like an Agoric smart contract or
+an Endo plugin do not need to do anything special to set up HardenedJS,
+HandledPromise and related shims.
+To construct an environment suitable for Eventual Send requires the
+`HandledPromise` shim:
 
 ```js
-import '@agoric/eventual-send/shim';
+import '@agoric/eventual-send/shim.js';
 ```
 
-After that, you can use `HandledPromise` in any of your code.  If you need access to the `E` proxy maker, do:
+The shim ensures that every instance of Eventual Send can recognize every other
+instance's handled promises.
+This is how we mitigate, what we call, "eval twins".
 
-```js
-import { E } from '@agoric/eventual-send';
+## Importing
+
+```javascript
+import { E } from '@endo/eventual-send';
+```
+
+## Core API
+
+### E(target).method(...args)
+
+Eventual send: invoke a method, returning a promise for the result.
+
+```javascript
+import { E } from '@endo/eventual-send';
+
+const counter = makeCounter(10);
+
+// Send message, get promise
+const resultP = E(counter).increment(5);
+const result = await resultP;  // 15
+
+// Works even if counter is a promise
+const counterP = Promise.resolve(counter);
+const result2 = await E(counterP).increment(3);  // 18
+```
+
+**Key property:** Works uniformly whether the target is:
+- A local object
+- A local promise for an object
+- A remote presence in another vat
+- A promise for a remote presence
+
+All calls return promises, even for local objects, ensuring consistent async
+behavior throughout your codebase.
+
+### E.get(target).property
+
+Eventual get: retrieve a property, returning a promise for its value.
+
+```javascript
+const config = harden({
+  timeout: 5000,
+  retries: 3
+});
+
+const timeoutP = E.get(config).timeout;
+const timeout = await timeoutP;  // 5000
+```
+
+Useful for accessing properties on remote objects or promises.
+
+### E.sendOnly(target).method(...args)
+
+Fire-and-forget: send a message without waiting for or receiving the result.
+Returns `undefined` immediately.
+
+```javascript
+const logger = makeLogger();
+
+// Send log message, don't wait for result
+E.sendOnly(logger).log('Event occurred');
+// Continues immediately, logging happens eventually
 ```
 
-[deps-svg]: https://david-dm.org/Agoric/eventual-send.svg
-[deps-url]: https://david-dm.org/Agoric/eventual-send
-[dev-deps-svg]: https://david-dm.org/Agoric/eventual-send/dev-status.svg
-[dev-deps-url]: https://david-dm.org/Agoric/eventual-send?type=dev
-[license-image]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
-[license-url]: LICENSE
+**When to use:**
+- Don't need the return value
+- Want to optimize latency (no promise creation)
+- Logging, notifications, fire-and-forget operations
+
+**Note:** You won't get errors if the method fails.
+Use regular `E()` if you need error handling.
+
+### E.when(promiseOrValue, onFulfilled?, onRejected?)
+
+Shorthand for promise handling with turn tracking:
+
+```javascript
+E.when(
+  E(counter).getValue(),
+  value => console.log('Value:', value),
+  error => console.error('Error:', error)
+);
+
+// Equivalent to:
+E(counter).getValue().then(
+  value => console.log('Value:', value),
+  error => console.error('Error:', error)
+);
+```
+
+Primarily useful in contexts that need explicit turn tracking for debugging.
+
+### E.resolve(value)
+
+Convert a value to a handled promise:
+
+```javascript
+const promise = E.resolve(value);
+// promise is a HandledPromise wrapping value
+```
+
+Usually not needed directly; `E()` handles this automatically.
+
+## Promise Pipelining
+
+One of the most powerful features is **promise pipelining**: the ability to
+send messages to promises before they resolve.
+
+```javascript
+import { E } from '@endo/eventual-send';
+
+// All of these send immediately - no waiting!
+const mintP = E(bootstrap).getMint();
+const purseP = E(mintP).makePurse();
+const paymentP = E(purseP).withdraw(100);
+await E(receiverPurse).deposit(100, paymentP);
+
+// Only wait at the end for the final result
+```
+
+Without pipelining, you'd need to await each step:
+
+```javascript
+// Without pipelining: 4 round trips
+const mint = await bootstrap.getMint();        // wait
+const purse = await mint.makePurse();          // wait
+const payment = await purse.withdraw(100);     // wait
+await receiverPurse.deposit(100, payment);     // wait
+
+// With pipelining: messages sent immediately, only wait at end
+```
+
+This can **dramatically reduce latency** in distributed systems by eliminating
+round trips.
+
+**How it works:**
+- Messages to unresolved promises are queued
+- When the promise resolves, queued messages are delivered in order
+- Each message returns a new promise that resolves when the operation completes
+
+## Why Eventual Send?
+
+Eventual send provides four key benefits:
+
+### 1. Uniform API
+
+The same code works whether the target is local or remote:
+
+```javascript
+// This code works identically whether counter is:
+// - A local object
+// - In a different vat on the same machine
+// - On a different machine across the network
+const result = await E(counter).increment(5);
+```
+
+Write local code, deploy distributed, no changes needed.
+
+### 2. Message Ordering
+
+Messages to the same target are delivered and processed in send order:
+
+```javascript
+E(counter).increment(1);  // executed first
+E(counter).increment(2);  // executed second
+E(counter).increment(3);  // executed third
+// Order is guaranteed
+```
+
+This simplifies reasoning about concurrency.
+
+### 3. Pipeline Optimization
+
+As shown above, eliminates round trips in distributed systems.
+
+### 4. Future-Proof Code
+
+Code written with `E()` works locally today and distributed tomorrow:
+
+```javascript
+// Works in development (local)
+const result = await E(service).getData();
+
+// Same code works in production (distributed)
+// No changes needed when service moves to another vat/machine
+```
+
+## Integration with Exo
+
+Exos (from [@endo/exo](../exo/README.md)) are the ideal targets for eventual
+send:
+
+```javascript
+import { makeExo } from '@endo/exo';
+import { M } from '@endo/patterns';
+import { E } from '@endo/eventual-send';
+
+const CounterI = M.interface('Counter', {
+  increment: M.call(M.number()).returns(M.number())
+});
+
+const counter = makeExo('Counter', CounterI, {
+  increment(n) {
+    return count += n;
+  }
+});
+
+// E() provides async wrapper
+const resultP = E(counter).increment(5);
+
+// The InterfaceGuard validates n is a number
+// Even if counter is remote, validation happens on receive
+```
+
+Even for local exos, using `E()` provides benefits:
+- **Consistent async behavior** throughout your codebase
+- **Turn-based execution** prevents reentrancy bugs
+- **Error isolation** via promise rejection
+- **Future-proof** code that works when distributed
+
+## HandledPromise
+
+Under the hood, `E()` uses `HandledPromise`, a Promise subclass that supports
+handler-based dispatch:
+
+```javascript
+import { HandledPromise } from '@endo/eventual-send';
+
+// HandledPromise extends native Promise
+const hp = new HandledPromise((resolve, reject, resolveWithPresence) => {
+  // Three ways to settle the promise
+  resolve(value);           // Normal resolution
+  reject(reason);           // Rejection
+  resolveWithPresence(h);   // Resolve with a remote presence
+}, handler);
+
+// Handler intercepts operations
+const handler = {
+  get(target, prop) { /* ... */ },
+  applyMethod(target, verb, args) { /* ... */ }
+};
+```
+
+**Most users don't need to use HandledPromise directly.**
+The `E()` proxy provides the ergonomic interface.
+
+## Use in Tests
+
+Use `E()` even in unit tests for consistency:
+
+```javascript
+import test from 'ava';
+import { E } from '@endo/eventual-send';
+
+test('counter increments correctly', async t => {
+  const counter = makeCounter(0);
+
+  // Use E() even though counter is local
+  const result = await E(counter).increment(5);
+
+  t.is(result, 5);
+});
+```
+
+Benefits:
+- Tests mirror production code
+- Async behavior is tested
+- Easy to mock remote objects
+- Same code works for both local and remote targets
+
+## Integration with Endo Packages
+
+- **Foundation**: [@endo/pass-style](../pass-style/README.md) - What can be
+  sent as arguments
+- **Validation**: [@endo/patterns](../patterns/README.md) - Describe method
+  signatures with InterfaceGuards
+- **Defensive Objects**: [@endo/exo](../exo/README.md) - Exos are ideal targets
+  for `E()`
+- **Network Transport**: [@endo/captp](../captp/README.md) - Real network
+  communication using CapTP
+
+**Complete Tutorial**: See [Message Passing](../../docs/message-passing.md) for
+a comprehensive guide showing how eventual-send works with pass-style, patterns,
+and exo to enable safe distributed computing.
+
+## Background
+
+This package implements the
+[ECMAScript eventual-send proposal](https://github.com/tc39/proposal-eventual-send),
+which provides native language support for eventual send operations.
+
+## See Also
+
+- [ECMAScript eventual-send proposal](https://github.com/tc39/proposal-eventual-send)
+- [Concurrency Among Strangers](http://www.erights.org/talks/thesis/) - Mark S.
+  Miller's thesis on eventual send
+- [@endo/captp](../captp/README.md) - Cap'n Proto RPC implementation for network
+  transport

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@endo/eventual-send",
-  "version": "1.3.4",
+  "version": "1.5.0",
   "description": "Extend a Promise class to implement the eventual-send API",
   "type": "module",
   "main": "src/no-shim.js",
   "scripts": {
     "test": "ava",
-    "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
+    "test:c8": "c8 ${C8_OPTIONS:-} ava",
     "test:xs": "exit 0",
     "build": "exit 0",
-    "clean": "git clean -fX \"*.d.ts*\" \"*.d.cts*\" \"*.d.mts*\" \"*.tsbuildinfo\"",
-    "prepack": "tsc --build tsconfig.build.json",
+    "clean": "git clean -fX -e node_modules/",
+    "prepack": "git clean -fX -e node_modules/ && tsc --build tsconfig.build.json",
     "postpack": "yarn clean",
     "lint-fix": "yarn lint:eslint --fix && yarn lint:types",
     "lint": "yarn lint:types && yarn lint:eslint",
@@ -35,14 +35,17 @@
   },
   "homepage": "https://github.com/endojs/endo#readme",
   "dependencies": {
-    "@endo/env-options": "^1.1.11"
+    "@endo/env-options": "^1.1.11",
+    "@endo/harden": "^1.1.0"
   },
   "devDependencies": {
-    "@endo/lockdown": "^1.0.18",
-    "ava": "^6.1.3",
-    "c8": "^7.14.0",
-    "tsd": "^0.31.2",
-    "typescript": "~5.8.3"
+    "@endo/lockdown": "^1.0.19",
+    "ava": "catalog:dev",
+    "c8": "catalog:dev",
+    "eslint": "catalog:dev",
+    "ses": "^2.0.0",
+    "tsd": "catalog:dev",
+    "typescript": "catalog:dev"
   },
   "keywords": [
     "eventual send",
@@ -76,5 +79,5 @@
   "typeCoverage": {
     "atLeast": 77.81
   },
-  "gitHead": "9815aea9541f241389d2135c6097a7442bdffa17"
+  "gitHead": "e74ed050e9d1122d692b00ee14971299c6afbf30"
 }

package/src/E.d.ts

@@ -57,12 +57,12 @@ export type EProxy = ReturnType<(HandledPromise: HandledPromiseConstructor) => (
  * are distributed object creator components like the `Far` or `Remotable`
  * functions.
  */
-export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<Local & import("./types.js").RemotableBrand<Local, Primary>>;
+export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<Local & RemotableBrand<Local, Primary>>;
 /**
  * `DataOnly<T>` means to return a record type `T2` consisting only of
  * properties that are *not* functions.
  */
-export type DataOnly<T> = Omit<T, FilteredKeys<T, import("./types.js").Callable>>;
+export type DataOnly<T> = Omit<T, FilteredKeys<T, Callable>>;
 /**
  * Declare that `T` may or may not be a Promise.  This should be used only for
  * consumers of arguments and declarations; return values should specifically be
@@ -71,15 +71,31 @@ export type DataOnly<T> = Omit<T, FilteredKeys<T, import("./types.js").Callable>
 export type ERef<T> = PromiseLike<T> | T;
 /**
  * The awaited return type of a function.
+ * For the eventual result of an E call,
  */
 export type EReturn<T extends (...args: any[]) => any> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-export type ECallable<T extends import("./types.js").Callable> = (ReturnType<T> extends PromiseLike<infer U> ? T : (...args: Parameters<T>) => Promise<EReturn<T>>);
-export type EMethods<T> = { readonly [P in keyof T]: T[P] extends import("./types.js").Callable ? ECallable<T[P]> : never; };
+/**
+ * An eventual value where remotable objects are recursively mapped to Remote types
+ */
+export type EResult<T> = Awaited<T>;
+/**
+ * Experimental type mapping remotable objects to Remote types
+ */
+export type EAwaitedResult<T> = (0 extends (1 & T) ? T : T extends RemotableBrand<infer L, infer P> ? (P | RemotableBrand<L, P>) : T extends PromiseLike<infer U> ? Promise<EAwaitedResult<Awaited<T>>> : T extends (null | undefined | string | number | boolean | symbol | bigint | Callable) ? T : T extends object ? { [P in keyof T]: EAwaitedResult<T[P]>; } : T);
+/**
+ * The
+ */
+export type ECallableReturn<T extends (...args: any[]) => any> = (0 extends (1 & T) ? any : T extends (...args: any[]) => infer R ? EResult<R> : never);
+/**
+ * Maps a callable to its remotely called type
+ */
+export type ECallable<T extends Callable> = (ReturnType<T> extends PromiseLike<infer U> ? T : (...args: Parameters<T>) => Promise<ECallableReturn<T>>);
+export type EMethods<T> = { readonly [P in keyof T]: T[P] extends Callable ? ECallable<T[P]> : never; };
 export type EGetters<T> = { readonly [P in keyof T]: T[P] extends PromiseLike<infer U> ? T[P] : Promise<Awaited<T[P]>>; };
-export type ESendOnlyCallable<T extends import("./types.js").Callable> = (...args: Parameters<T>) => Promise<void>;
-export type ESendOnlyMethods<T> = { readonly [P in keyof T]: T[P] extends import("./types.js").Callable ? ESendOnlyCallable<T[P]> : never; };
-export type ESendOnlyCallableOrMethods<T> = (T extends import("./types.js").Callable ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>> : ESendOnlyMethods<Required<T>>);
-export type ECallableOrMethods<T> = (T extends import("./types.js").Callable ? ECallable<T> & EMethods<Required<T>> : EMethods<Required<T>>);
+export type ESendOnlyCallable<T extends Callable> = (...args: Parameters<T>) => Promise<void>;
+export type ESendOnlyMethods<T> = { readonly [P in keyof T]: T[P] extends Callable ? ESendOnlyCallable<T[P]> : never; };
+export type ESendOnlyCallableOrMethods<T> = (0 extends (1 & T) ? any : T extends Callable ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>> : ESendOnlyMethods<Required<T>>);
+export type ECallableOrMethods<T> = (0 extends (1 & T) ? any : T extends Callable ? ECallable<T> & EMethods<Required<T>> : EMethods<Required<T>>);
 /**
  * Return a union of property names/symbols/numbers P for which the record element T[P]'s type extends U.
  *
@@ -95,22 +111,22 @@ export type FilteredKeys<T, U> = { [P in keyof T]: T[P] extends U ? P : never; }
  * `PickCallable<T>` means to return a single root callable or a record type
  * consisting only of properties that are functions.
  */
-export type PickCallable<T> = (T extends import("./types.js").Callable ? (...args: Parameters<T>) => ReturnType<T> : Pick<T, FilteredKeys<T, import("./types.js").Callable>>);
+export type PickCallable<T> = (0 extends (1 & T) ? any : T extends Callable ? (...args: Parameters<T>) => ReturnType<T> : Pick<T, FilteredKeys<T, Callable>>);
 /**
  * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
  */
-export type RemoteFunctions<T> = (T extends import("./types.js").RemotableBrand<infer L, infer R> ? PickCallable<R> : Awaited<T> extends import("./types.js").RemotableBrand<infer L, infer R> ? PickCallable<R> : T extends PromiseLike<infer U> ? Awaited<T> : T);
-export type LocalRecord<T> = (T extends import("./types.js").RemotableBrand<infer L, infer R> ? L : Awaited<T> extends import("./types.js").RemotableBrand<infer L, infer R> ? L : T extends PromiseLike<infer U> ? Awaited<T> : T);
+export type RemoteFunctions<T> = (0 extends (1 & T) ? any : T extends RemotableBrand<infer L, infer R> ? PickCallable<R> : T extends PromiseLike<infer U> ? RemoteFunctions<U> : T);
+export type LocalRecord<T> = (T extends RemotableBrand<infer L, infer R> ? L : T extends PromiseLike<infer U> ? LocalRecord<U> : T);
 export type EPromiseKit<R = unknown> = {
     promise: Promise<R>;
-    settler: import("./types.js").Settler<R>;
+    settler: Settler<R>;
 };
 /**
  * Declare a near object that must only be invoked with E, even locally.  It
  * supports the `T` interface but additionally permits `T`'s methods to return
  * `PromiseLike`s even if `T` declares them as only synchronous.
  */
-export type EOnly<T> = (T extends import("./types.js").Callable ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>> : T extends Record<PropertyKey, import("./types.js").Callable> ? { [K in keyof T]: T[K] extends import("./types.js").Callable ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>> : T[K]; } : T);
+export type EOnly<T> = (T extends Callable ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>> : T extends Record<PropertyKey, Callable> ? { [K in keyof T]: T[K] extends Callable ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>> : T[K]; } : T);
 /**
  * @param {HandledPromiseConstructor} HandledPromise
  */
@@ -166,4 +182,7 @@ declare function makeE(HandledPromise: HandledPromiseConstructor): (<T>(x: T) =>
     readonly when: <T, U = T>(x: T | PromiseLike<T>, onfulfilled?: (value: T) => ERef<U>, onrejected?: (reason: any) => ERef<U>) => Promise<U>;
 };
 import type { HandledPromiseConstructor } from './types.js';
+import type { RemotableBrand } from './types.js';
+import type { Callable } from './types.js';
+import type { Settler } from './types.js';
 //# sourceMappingURL=E.d.ts.map

package/src/E.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":"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"}

package/src/E.js

@@ -1,3 +1,4 @@
+import harden from '@endo/harden';
 import { trackTurns } from './track-turns.js';
 import { makeMessageBreakpointTester } from './message-breakpoints.js';
 
@@ -5,7 +6,7 @@ const { details: X, quote: q, Fail, error: makeError } = assert;
 const { assign, freeze } = Object;
 
 /**
- * @import { HandledPromiseConstructor } from './types.js';
+ * @import { HandledPromiseConstructor, RemotableBrand, Callable, Settler } from './types.js';
  */
 
 const onSend = makeMessageBreakpointTester('ENDO_SEND_BREAKPOINTS');
@@ -282,7 +283,7 @@ export default makeE;
  *
  * @template Primary The type of the primary reference.
  * @template [Local=DataOnly<Primary>] The local properties of the object.
- * @typedef {ERef<Local & import('./types.js').RemotableBrand<Local, Primary>>} FarRef
+ * @typedef {ERef<Local & RemotableBrand<Local, Primary>>} FarRef
  */
 
 /**
@@ -290,7 +291,7 @@ export default makeE;
  * properties that are *not* functions.
  *
  * @template T The type to be filtered.
- * @typedef {Omit<T, FilteredKeys<T, import('./types.js').Callable>>} DataOnly
+ * @typedef {Omit<T, FilteredKeys<T, Callable>>} DataOnly
  */
 
 /**
@@ -304,24 +305,69 @@ export default makeE;
 
 /**
  * The awaited return type of a function.
+ * For the eventual result of an E call, @see {EResult} or @see {ECallableReturn}
  *
  * @template {(...args: any[]) => any} T
  * @typedef {T extends (...args: any[]) => infer R ? Awaited<R> : never} EReturn
  */
 
 /**
- * @template {import('./types.js').Callable} T
+ * An eventual value where remotable objects are recursively mapped to Remote types
+ *
+ * @template T
+ * @typedef {Awaited<T>} EResult
+ */
+
+/**
+ * Experimental type mapping remotable objects to Remote types
+ *
+ * @template T
  * @typedef {(
- *   ReturnType<T> extends PromiseLike<infer U>                       // if function returns a promise
- *     ? T                                                            // return the function
- *     : (...args: Parameters<T>) => Promise<EReturn<T>>  // make it return a promise
+ *   0 extends (1 & T)                                        // If T is any
+ *     ? T                                                    // Propagate the any type through the result
+ *     : T extends RemotableBrand<infer L, infer P>           // If we have a Remotable
+ *       ? (P | RemotableBrand<L, P>)                         // map it to its "maybe remote" form (primary behavior or remotable presence)
+ *       : T extends PromiseLike<infer U>                     // If T is a promise
+ *         ? Promise<EAwaitedResult<Awaited<T>>>              // map its resolution
+ *         : T extends (null | undefined | string | number | boolean | symbol | bigint | Callable) // Intersections of these types with objects are not mapped
+ *           ? T                                              // primitives and non-remotable functions are passed-through
+ *           : T extends object                               //
+ *             ? { [P in keyof T]: EAwaitedResult<T[P]>; }    // other objects are considered copy data and properties mapped
+ *             : T                                            // in case anything wasn't covered, fallback to pass-through
+ * )} EAwaitedResult
+ */
+
+/**
+ * The @see {EResult} return type of a remote function.
+ *
+ * @template {(...args: any[]) => any} T
+ * @typedef {(
+ *   0 extends (1 & T)                          // If T is any
+ *     ? any                                    // Propagate the any type through the result
+ *     : T extends (...args: any[]) => infer R  // Else infer the return type
+ *       ? EResult<R>                           // In the future, map the eventual result
+ *       : never
+ * )} ECallableReturn
+ */
+
+// TODO: Figure out a way to map generic callable return types, or at least better detect them.
+// See https://github.com/microsoft/TypeScript/issues/61838. Without that, `E(startGovernedUpgradable)`
+// in agoric-sdk doesn't propagate the start function type.
+/**
+ * Maps a callable to its remotely called type
+ *
+ * @template {Callable} T
+ * @typedef {(
+ *    ReturnType<T> extends PromiseLike<infer U>                  // Check if callable returns a promise
+ *      ? T                                                       // Bypass mapping to maintain any generic
+ *      : (...args: Parameters<T>) => Promise<ECallableReturn<T>> // Map it anyway to ensure promise return type
  * )} ECallable
  */
 
 /**
  * @template T
  * @typedef {{
- *   readonly [P in keyof T]: T[P] extends import('./types.js').Callable
+ *   readonly [P in keyof T]: T[P] extends Callable
  *     ? ECallable<T[P]>
  *     : never;
  * }} EMethods
@@ -337,14 +383,14 @@ export default makeE;
  */
 
 /**
- * @template {import('./types.js').Callable} T
+ * @template {Callable} T
  * @typedef {(...args: Parameters<T>) => Promise<void>} ESendOnlyCallable
  */
 
 /**
  * @template T
  * @typedef {{
- *   readonly [P in keyof T]: T[P] extends import('./types.js').Callable
+ *   readonly [P in keyof T]: T[P] extends Callable
  *     ? ESendOnlyCallable<T[P]>
  *     : never;
  * }} ESendOnlyMethods
@@ -353,18 +399,22 @@ export default makeE;
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
- *     ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
- *     : ESendOnlyMethods<Required<T>>
+ *   0 extends (1 & T)                              // if T is any
+ *     ? any                                        // propagate any cleanly
+ *     : T extends Callable
+ *       ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
+ *       : ESendOnlyMethods<Required<T>>
  * )} ESendOnlyCallableOrMethods
  */
 
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
- *     ? ECallable<T> & EMethods<Required<T>>
- *     : EMethods<Required<T>>
+ *   0 extends (1 & T)                              // if T is any
+ *     ? any                                        // propagate any cleanly (avoid distributive expansion that displays Pick<any,string>)
+ *     : T extends Callable
+ *       ? ECallable<T> & EMethods<Required<T>>
+ *       : EMethods<Required<T>>
  * )} ECallableOrMethods
  */
 
@@ -389,9 +439,11 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
- *     ? (...args: Parameters<T>) => ReturnType<T>                     // a root callable, no methods
- *     : Pick<T, FilteredKeys<T, import('./types.js').Callable>>          // any callable methods
+ *   0 extends (1 & T)                              // if T is any
+ *     ? any                                        // propagate any (avoid Pick<any, string> distributive collapse)
+ *     : T extends Callable
+ *       ? (...args: Parameters<T>) => ReturnType<T>  // a root callable, no methods
+ *       : Pick<T, FilteredKeys<T, Callable>>         // any callable methods
  * )} PickCallable
  */
 
@@ -400,25 +452,23 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').RemotableBrand<infer L, infer R>     // if a given T is some remote interface R
- *     ? PickCallable<R>                                              // then return the callable properties of R
- *     : Awaited<T> extends import('./types.js').RemotableBrand<infer L, infer R> // otherwise, if the final resolution of T is some remote interface R
- *     ? PickCallable<R>                                              // then return the callable properties of R
- *     : T extends PromiseLike<infer U>                               // otherwise, if T is a promise
- *     ? Awaited<T>                                                   // then return resolved value T
- *     : T                                                            // otherwise, return T
+ *   0 extends (1 & T)                            // if T is any
+ *     ? any                                      // propagate any (avoid distributive collapse to Pick<any,string>)
+ *     : T extends RemotableBrand<infer L, infer R>   // if a given T is some remote interface R
+ *       ? PickCallable<R>                        // then return the callable properties of R
+ *       : T extends PromiseLike<infer U>         // otherwise, if T is a promise
+ *         ? RemoteFunctions<U>                   // recurse on the resolved value of T
+ *         : T                                    // otherwise, return T
  * )} RemoteFunctions
  */
 
 /**
  * @template T
  * @typedef {(
- *   T extends import('./types.js').RemotableBrand<infer L, infer R>
- *     ? L
- *     : Awaited<T> extends import('./types.js').RemotableBrand<infer L, infer R>
+ *   T extends RemotableBrand<infer L, infer R>
  *     ? L
  *     : T extends PromiseLike<infer U>
- *     ? Awaited<T>
+ *     ? LocalRecord<U>
  *     : T
  * )} LocalRecord
  */
@@ -427,7 +477,7 @@ export default makeE;
  * @template [R = unknown]
  * @typedef {{
  *   promise: Promise<R>;
- *   settler: import('./types.js').Settler<R>;
+ *   settler: Settler<R>;
  * }} EPromiseKit
  */
 
@@ -438,11 +488,11 @@ export default makeE;
  *
  * @template T
  * @typedef {(
- *   T extends import('./types.js').Callable
+ *   T extends Callable
  *     ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>>
- *     : T extends Record<PropertyKey, import('./types.js').Callable>
+ *     : T extends Record<PropertyKey, Callable>
  *     ? {
- *         [K in keyof T]: T[K] extends import('./types.js').Callable
+ *         [K in keyof T]: T[K] extends Callable
  *           ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>>
  *           : T[K];
  *       }

package/src/exports.d.ts

@@ -13,6 +13,15 @@ export type {
   EProxy,
   EOnly,
   EReturn,
+  EResult,
+  ECallable,
+  ECallableReturn,
+  ECallableOrMethods,
+  EMethods,
+  EGetters,
+  ESendOnlyCallable,
+  ESendOnlyMethods,
+  ESendOnlyCallableOrMethods,
   RemoteFunctions,
   LocalRecord,
   FilteredKeys,

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

@@ -1 +1 @@
-{"version":3,"file":"handled-promise.d.ts","sourceRoot":"","sources":["handled-promise.js"],"names":[],"mappings":"AAyDO;SAyIe,CAAC,YAAY,eAAe,CAAC,CAAC,CAAC,uBAAuB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAAa,OAAO,CAAC,OAAO,CAAC;qDA2Y9I;oBAGY,CAAC,IACD;IACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC1G,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClF;0CAIc,CAAC,SAAN,EAAI,IACJ;IACR,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;KAC7C,CAAC;CACH;4BAIU,CAAC,cACF,CACR,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,EACnC,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,EACzC,mBAAmB,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,KAAK,MAAM,KACvG,IAAI;oBAIE,CAAC,cACF;IACR,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,mBAAmB,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;CACzG;0CAIS;IACR,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/E,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CACvD;wCAGU,UAAU,CAAC,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"handled-promise.d.ts","sourceRoot":"","sources":["handled-promise.js"],"names":[],"mappings":"AA0DO;SAyIe,CAAC,YAAY,eAAe,CAAC,CAAC,CAAC,uBAAuB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAAa,OAAO,CAAC,OAAO,CAAC;qDA2Y9I;oBAGY,CAAC,IACD;IACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC1G,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClF;0CAIc,CAAC,SAAN,EAAI,IACJ;IACR,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;KAC7C,CAAC;CACH;4BAIU,CAAC,cACF,CACR,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,EACnC,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,EACzC,mBAAmB,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,KAAK,MAAM,KACvG,IAAI;oBAIE,CAAC,cACF;IACR,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,mBAAmB,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;CACzG;0CAIS;IACR,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/E,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CACvD;wCAGU,UAAU,CAAC,OAAO,kBAAkB,CAAC"}

package/src/handled-promise.js

@@ -1,5 +1,6 @@
 /// <reference types="ses" />
 
+import harden from '@endo/harden';
 import { trackTurns } from './track-turns.js';
 import {
   localApplyFunction,

package/src/local.d.ts.map

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

package/src/local.js

@@ -1,3 +1,4 @@
+import harden from '@endo/harden';
 import { makeMessageBreakpointTester } from './message-breakpoints.js';
 
 const { details: X, quote: q, Fail } = assert;

package/src/no-shim.d.ts

@@ -27,7 +27,7 @@ import type { EGetters } from './E.js';
 import type { ESendOnlyCallableOrMethods } from './E.js';
 import type { ERef } from './E.js';
 /** @import {Handler, HandledExecutor} from './handled-promise.js' */
-/** @import {ECallableOrMethods, EGetters, ERef, ERemoteFunctions, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
+/** @import {ECallableOrMethods, EGetters, ERef, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
 declare const hp: {
     new <R>(executor: HandledExecutor<R>, unfulfilledHandler?: Handler<Promise<unknown>>): Promise<R>;
     prototype: Promise<unknown>;

package/src/no-shim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"no-shim.d.ts","sourceRoot":"","sources":["no-shim.js"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH;;;;;;;;;EAA2B;;;qCAduG,QAAQ;wCAAR,QAAQ;iCAAR,QAAQ;8BAAR,QAAQ;gDAAR,QAAQ;0BAAR,QAAQ;AAD1I,qEAAqE;AACrE,6IAA6I;AAE7I;;;oFAA0B;qCAHkB,sBAAsB;6BAAtB,sBAAsB"}
+{"version":3,"file":"no-shim.d.ts","sourceRoot":"","sources":["no-shim.js"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH;;;;;;;;;EAA2B;;;qCAdqF,QAAQ;wCAAR,QAAQ;iCAAR,QAAQ;8BAAR,QAAQ;gDAAR,QAAQ;0BAAR,QAAQ;AADxH,qEAAqE;AACrE,2HAA2H;AAE3H;;;oFAA0B;qCAHkB,sBAAsB;6BAAtB,sBAAsB"}

package/src/no-shim.js

@@ -2,7 +2,7 @@ import makeE from './E.js';
 
 // XXX module exports for HandledPromise fail if these aren't in scope
 /** @import {Handler, HandledExecutor} from './handled-promise.js' */
-/** @import {ECallableOrMethods, EGetters, ERef, ERemoteFunctions, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
+/** @import {ECallableOrMethods, EGetters, ERef, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
 
 const hp = HandledPromise;
 

package/src/types.d.ts

@@ -19,8 +19,16 @@ export type * from './track-turns.js';
 
 export type Callable = (...args: any[]) => any;
 
+// TODO(https://github.com/endojs/endo/issues/2979): We likely want to merge
+// the RemotableObject symbol shape into this type to reduce confusion about
+// why both exist, but all kinds of things blow up when trying to do that.
+
 /**
  * Nominal type to carry the local and remote interfaces of a Remotable.
+ *
+ * Note: this type does not currently include the structural aspect of the
+ * {@link RemotableObject} type, and as such is not suitable to represent a
+ * "remotable" for APIs that expect an object with a pass-style symbol.
  */
 export declare class RemotableBrand<Local, Remote> {
   /** The local properties of the object. */