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

package/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./src/async-flow.js";
+export * from "./src/types.js";
+export { makeSharedStateRecord } from "./src/endowments.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1 +1,3 @@
 export * from './src/async-flow.js';
+export * from './src/types.js';
+export { makeSharedStateRecord } from './src/endowments.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/async-flow",
-  "version": "0.1.1-upgrade-16-dev-d492653.0+d492653",
+  "version": "0.1.1-upgrade-17-dev-3b97a9f.0+3b97a9f",
   "description": "Upgrade async functions at await points by replay",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -24,24 +24,25 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/base-zone": "0.1.1-upgrade-16-dev-d492653.0+d492653",
-    "@agoric/store": "0.9.3-upgrade-16-dev-d492653.0+d492653",
-    "@agoric/vow": "0.1.1-upgrade-16-dev-d492653.0+d492653",
-    "@endo/common": "^1.2.2",
-    "@endo/errors": "^1.2.2",
-    "@endo/eventual-send": "^1.2.2",
-    "@endo/marshal": "^1.5.0",
-    "@endo/pass-style": "^1.4.0",
-    "@endo/patterns": "^1.4.0",
-    "@endo/promise-kit": "^1.1.2"
+    "@agoric/base-zone": "0.1.1-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@agoric/internal": "0.3.3-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@agoric/store": "0.9.3-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@agoric/vow": "0.1.1-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@endo/common": "^1.2.5",
+    "@endo/errors": "^1.2.5",
+    "@endo/eventual-send": "^1.2.5",
+    "@endo/marshal": "^1.5.3",
+    "@endo/pass-style": "^1.4.3",
+    "@endo/patterns": "^1.4.3",
+    "@endo/promise-kit": "^1.1.5"
   },
   "devDependencies": {
-    "@agoric/internal": "0.3.3-upgrade-16-dev-d492653.0+d492653",
-    "@agoric/swingset-liveslots": "0.10.3-upgrade-16-dev-d492653.0+d492653",
-    "@agoric/zone": "0.2.3-upgrade-16-dev-d492653.0+d492653",
-    "@endo/env-options": "^1.1.4",
-    "@endo/ses-ava": "^1.2.2",
-    "ava": "^5.3.0"
+    "@agoric/swingset-liveslots": "0.10.3-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@agoric/zone": "0.2.3-upgrade-17-dev-3b97a9f.0+3b97a9f",
+    "@endo/env-options": "^1.1.6",
+    "@endo/ses-ava": "^1.2.5",
+    "ava": "^5.3.0",
+    "tsd": "^0.31.1"
   },
   "publishConfig": {
     "access": "public"
@@ -60,7 +61,7 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 77.83
+    "atLeast": 77.1
   },
-  "gitHead": "d49265372b3cdd681558791b0c780e1c3062bdcc"
+  "gitHead": "3b97a9f0bc7d5dcd24d20dd81ca2af5d59d6e43d"
 }

package/src/async-flow.d.ts

@@ -15,8 +15,8 @@ export function prepareAsyncFlowTools(outerZone: Zone, outerOptions?: Preparatio
              */
             restart(eager?: boolean | undefined): void;
             wake(): void;
-            getOutcome(): Vow<any>;
-            dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+            getOutcome(): import("@agoric/vow").Vow<any>;
+            dump(): ([op: "doFulfill", vow: import("@agoric/vow").Vow<import("@endo/pass-style").Passable>, fulfillment: import("@endo/pass-style").Passable] | [op: "doReject", vow: import("@agoric/vow").Vow<import("@endo/pass-style").Passable>, reason: import("@endo/pass-style").Passable] | [op: "doReturn", callIndex: number, result: import("@endo/pass-style").Passable] | [op: "doThrow", callIndex: number, problem: import("@endo/pass-style").Passable] | [op: "checkCall", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number] | [op: "checkSendOnly", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number] | [op: "checkSend", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number])[];
             getOptFatalProblem(): any;
         };
         admin: {
@@ -29,19 +29,20 @@ export function prepareAsyncFlowTools(outerZone: Zone, outerOptions?: Preparatio
             onRejected(_fulfillment: any): void;
         };
     }>;
-    asyncFlow: (zone: Zone, tag: string, guestFunc: GuestAsyncFunc, options?: {
+    asyncFlow: <F extends GuestAsyncFunc>(zone: Zone, tag: string, guestFunc: F, options?: {
         startEager?: boolean;
-    } | undefined) => HostAsyncFuncWrapper;
+    } | undefined) => HostOf<F>;
     adminAsyncFlow: import("@endo/exo").Guarded<{
-        getFailures(): import("@endo/patterns").CopyMap<any, Passable>;
+        getFailures(): import("@endo/patterns").CopyMap<any, import("@endo/pass-style").Passable>;
         wakeAll(): void;
         getFlowForOutcomeVow(outcomeVow: any): any;
     }>;
     allWokenP: Promise<void>;
+    prepareEndowment: (zone: Zone, tag: string, e: unknown) => any;
 };
 export type AsyncFlowTools = ReturnType<(outerZone: Zone, outerOptions?: PreparationOptions | undefined) => {
     prepareAsyncFlowKit: (zone: Zone, tag: string, guestAsyncFunc: GuestAsyncFunc, options?: {
-        startEager?: boolean | undefined;
+        startEager?: boolean;
     } | undefined) => (activationArgs: any) => import("@endo/exo").GuardedKit<{
         flow: {
             /**
@@ -56,8 +57,8 @@ export type AsyncFlowTools = ReturnType<(outerZone: Zone, outerOptions?: Prepara
              */
             restart(eager?: boolean | undefined): void;
             wake(): void;
-            getOutcome(): Vow<any>;
-            dump(): ([op: "doFulfill", vow: Vow<Passable>, fulfillment: Passable] | [op: "doReject", vow: Vow<Passable>, reason: Passable] | [op: "doReturn", callIndex: number, result: Passable] | [op: "doThrow", callIndex: number, problem: Passable] | [op: "checkCall", target: Passable, optVerb: PropertyKey | undefined, args: Passable[], callIndex: number])[];
+            getOutcome(): import("@agoric/vow").Vow<any>;
+            dump(): ([op: "doFulfill", vow: import("@agoric/vow").Vow<import("@endo/pass-style").Passable>, fulfillment: import("@endo/pass-style").Passable] | [op: "doReject", vow: import("@agoric/vow").Vow<import("@endo/pass-style").Passable>, reason: import("@endo/pass-style").Passable] | [op: "doReturn", callIndex: number, result: import("@endo/pass-style").Passable] | [op: "doThrow", callIndex: number, problem: import("@endo/pass-style").Passable] | [op: "checkCall", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number] | [op: "checkSendOnly", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number] | [op: "checkSend", target: import("@endo/pass-style").Passable, optVerb: PropertyKey | undefined, args: import("@endo/pass-style").Passable[], callIndex: number])[];
             getOptFatalProblem(): any;
         };
         admin: {
@@ -70,18 +71,24 @@ export type AsyncFlowTools = ReturnType<(outerZone: Zone, outerOptions?: Prepara
             onRejected(_fulfillment: any): void;
         };
     }>;
-    asyncFlow: (zone: Zone, tag: string, guestFunc: GuestAsyncFunc, options?: {
-        startEager?: boolean | undefined;
-    } | undefined) => HostAsyncFuncWrapper;
+    asyncFlow: <F extends GuestAsyncFunc>(zone: Zone, tag: string, guestFunc: F, options?: {
+        startEager?: boolean;
+    } | undefined) => HostOf<F>;
     adminAsyncFlow: import("@endo/exo").Guarded<{
-        getFailures(): import("@endo/patterns").CopyMap<any, Passable>;
+        getFailures(): import("@endo/patterns").CopyMap<any, import("@endo/pass-style").Passable>;
         wakeAll(): void;
         getFlowForOutcomeVow(outcomeVow: any): any;
     }>;
     allWokenP: Promise<void>;
+    prepareEndowment: (zone: Zone, tag: string, e: unknown) => any;
 }>;
 export type AdminAsyncFlow = AsyncFlowTools["adminAsyncFlow"];
 export type MakeAsyncFlowKit = ReturnType<AsyncFlowTools["prepareAsyncFlowKit"]>;
 export type AsyncFlowKit = ReturnType<MakeAsyncFlowKit>;
 export type AsyncFlow = AsyncFlowKit["flow"];
+import type { Zone } from '@agoric/base-zone';
+import type { PreparationOptions } from '../src/types.js';
+import type { GuestAsyncFunc } from '../src/types.js';
+import type { FlowState } from '../src/types.js';
+import type { HostOf } from '../src/types.js';
 //# sourceMappingURL=async-flow.d.ts.map

package/src/async-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-flow.d.ts","sourceRoot":"","sources":["async-flow.js"],"names":[],"mappings":"AA4CO;2CAuCM,MAAM,kBACN,cAAc;qBACC,OAAO;;;YA4BzB;;eAEG;4BADU,SAAS;YAkCtB;;;;;eAKG;;;;;;;;;;;;;;;;;iCAkRA,MAAM,aACN,cAAc;qBACC,OAAO;sBACpB,oBAAoB;;;;;;;EAkDlC;6BAIY,UAAU;2CAjZV,MAAM,kBACN,cAAc;;;;YA6BjB;;eAEG;;YAiCH;;;;;eAKG;;;;;;;;;;;;;;;;;iCAkRA,MAAM,aACN,cAAc;;;;;;;;;EAwDmB;6BAIjC,cAAc,CAAC,gBAAgB,CAAC;+BAIhC,UAAU,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAC;2BAIjD,UAAU,CAAC,gBAAgB,CAAC;wBAI5B,YAAY,CAAC,MAAM,CAAC"}
+{"version":3,"file":"async-flow.d.ts","sourceRoot":"","sources":["async-flow.js"],"names":[],"mappings":"AAgDO,iDAHI,IAAI;gCA6CF,IAAI,OACJ,MAAM,kBACN,cAAc;qBACC,OAAO;;;YA4BzB;;eAEG;4BADU,SAAS;YAkCtB;;;;;eAKG;;;;;;;;;;;;;;;;;gBAmRmB,CAAC,SAAlB,cAAgB,QAClB,IAAI,OACJ,MAAM,aACN,CAAC;qBACc,OAAO;sBACpB,OAAO,CAAC,CAAC;;;;;;;;EAsDvB;6BAIY,UAAU,aAtcZ,IAAI;gCA6CF,IAAI,OACJ,MAAM,kBACN,cAAc;qBACC,OAAO;;;YA4BzB;;eAEG;4BADU,SAAS;YAkCtB;;;;;eAKG;;;;;;;;;;;;;;;;;gBAmRmB,CAAC,SAAlB,cAAgB,QAClB,IAAI,OACJ,MAAM,aACN,CAAC;qBACc,OAAO;sBACpB,OAAO,CAAC,CAAC;;;;;;;;EA0DsB;6BAIjC,cAAc,CAAC,gBAAgB,CAAC;+BAIhC,UAAU,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAC;2BAIjD,UAAU,CAAC,gBAAgB,CAAC;wBAI5B,YAAY,CAAC,MAAM,CAAC;0BArfV,mBAAmB;wCACoD,iBAAiB;oCAAjB,iBAAiB;+BAAjB,iBAAiB;4BAAjB,iBAAiB"}

package/src/async-flow.js

@@ -7,10 +7,14 @@ import { prepareVowTools, toPassableCap, VowShape } from '@agoric/vow';
 import { makeReplayMembrane } from './replay-membrane.js';
 import { prepareLogStore } from './log-store.js';
 import { prepareBijection } from './bijection.js';
+import { prepareEndowmentTools } from './endowments.js';
 import { LogEntryShape, FlowStateShape } from './type-guards.js';
 
 /**
- * @import { WeakMapStore } from '@agoric/store'
+ * @import {WeakMapStore} from '@agoric/store'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {FlowState, GuestAsyncFunc, HostAsyncFuncWrapper, HostOf, PreparationOptions} from '../src/types.js'
+ * @import {ReplayMembrane} from '../src/replay-membrane.js'
  */
 
 const { defineProperties } = Object;
@@ -46,7 +50,11 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
   const {
     vowTools = prepareVowTools(outerZone),
     makeLogStore = prepareLogStore(outerZone),
-    makeBijection = prepareBijection(outerZone),
+    endowmentTools: { prepareEndowment, unwrap } = prepareEndowmentTools(
+      outerZone,
+      { vowTools },
+    ),
+    makeBijection = prepareBijection(outerZone, unwrap),
   } = outerOptions;
   const { watch, makeVowKit } = vowTools;
 
@@ -170,7 +178,7 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
               eagerWakers.delete(flow);
             }
 
-            const wakeWatch = vowish => {
+            const watchWake = vowish => {
               // Extra paranoid because we're getting
               // "promise watcher must be a virtual object"
               // in the general vicinity.
@@ -181,13 +189,13 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
               watch(vowish, wakeWatcher);
             };
             const panic = err => admin.panic(err);
-            const membrane = makeReplayMembrane(
+            const membrane = makeReplayMembrane({
               log,
               bijection,
               vowTools,
-              wakeWatch,
+              watchWake,
               panic,
-            );
+            });
             initMembrane(flow, membrane);
             const guestArgs = membrane.hostToGuest(activationArgs);
 
@@ -218,7 +226,9 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
               // gating condition, the next line could grow the bijection
               // of a failed flow, subverting other gating checks on bijection
               // membership.
-              bijection.init(guestResultP, outcomeKit.vow);
+              const g = bijection.unwrapInit(guestResultP, outcomeKit.vow);
+              g === guestResultP ||
+                Fail`internal: promises should not be unwrapped ${g}`;
             }
             // log is driven at first by guestAyncFunc interaction through the
             // membrane with the host activationArgs. At the end of its first
@@ -415,7 +425,7 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
       const asyncFlowKit = internalMakeAsyncFlowKit(activationArgs);
       const { flow } = asyncFlowKit;
 
-      const vow = toPassableCap(flow.getOutcome());
+      const vow = flow.getOutcome();
       flowForOutcomeVowKey.init(toPassableCap(vow), flow);
       flow.restart();
       return asyncFlowKit;
@@ -424,21 +434,25 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
   };
 
   /**
+   * @template {GuestAsyncFunc} F
    * @param {Zone} zone
    * @param {string} tag
-   * @param {GuestAsyncFunc} guestFunc
+   * @param {F} guestFunc
    * @param {{ startEager?: boolean }} [options]
-   * @returns {HostAsyncFuncWrapper}
+   * @returns {HostOf<F>}
    */
   const asyncFlow = (zone, tag, guestFunc, options = undefined) => {
     const makeAsyncFlowKit = prepareAsyncFlowKit(zone, tag, guestFunc, options);
     const hostFuncName = `${tag}_hostFlow`;
-    const wrapperFunc = {
-      [hostFuncName](...args) {
-        const { flow } = makeAsyncFlowKit(args);
-        return flow.getOutcome();
-      },
-    }[hostFuncName];
+
+    const wrapperFunc = /** @type {HostOf<F>} */ (
+      {
+        [hostFuncName](...args) {
+          const { flow } = makeAsyncFlowKit(args);
+          return flow.getOutcome();
+        },
+      }[hostFuncName]
+    );
     defineProperties(wrapperFunc, {
       length: { value: guestFunc.length },
     });
@@ -477,6 +491,7 @@ export const prepareAsyncFlowTools = (outerZone, outerOptions = {}) => {
     asyncFlow,
     adminAsyncFlow,
     allWokenP,
+    prepareEndowment,
   });
 };
 harden(prepareAsyncFlowTools);

package/src/bijection.d.ts

@@ -1,6 +1,6 @@
-export function prepareBijection(zone: Zone): () => import("@endo/exo").Guarded<{
+export function prepareBijection(zone: Zone, unwrap?: ((hostWrapper: PassableCap | Vow, guestWrapper: PassableCap) => unknown) | undefined): () => import("@endo/exo").Guarded<{
     reset(): void;
-    init(g: any, h: any): void;
+    unwrapInit(g: any, h: any): unknown;
     hasGuest(g: any): boolean;
     hasHost(h: any): boolean;
     has(g: any, h: any): boolean;
@@ -16,13 +16,16 @@ export type VowishStore = ReturnType<(name: string) => {
     has: (k: any) => boolean;
     get: (k: any) => any;
 }>>;
-export type Bijection = ReturnType<ReturnType<(zone: Zone) => () => import("@endo/exo").Guarded<{
+export type Bijection = ReturnType<ReturnType<(zone: Zone, unwrap?: ((hostWrapper: PassableCap | Vow, guestWrapper: PassableCap) => unknown) | undefined) => () => import("@endo/exo").Guarded<{
     reset(): void;
-    init(g: any, h: any): void;
+    unwrapInit(g: any, h: any): unknown;
     hasGuest(g: any): boolean;
     hasHost(h: any): boolean;
     has(g: any, h: any): boolean;
     guestToHost(g: any): any;
     hostToGuest(h: any): any;
 }>>>;
+import type { Zone } from '@agoric/base-zone';
+import type { PassableCap } from '@endo/pass-style';
+import type { Vow } from '@agoric/vow';
 //# sourceMappingURL=bijection.d.ts.map

package/src/bijection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bijection.d.ts","sourceRoot":"","sources":["bijection.js"],"names":[],"mappings":"AA0DO;;;;;;;;GAoEN;0BAzEa,UAAU,QAhCb,MAAM;;;;;;;;GAgCwB;wBA6E5B,UAAU,CAAC,UAAU;;;;;;;;GAAkB,CAAC"}
+{"version":3,"file":"bijection.d.ts","sourceRoot":"","sources":["bijection.js"],"names":[],"mappings":"AA+GO,uCAJI,IAAI,0BACU,WAAW,GAAG,GAAG,gBAAgB,WAAW,KAAK,OAAO;;;;;;;;GA6FhF;0BAtIa,UAAU,QAhCb,MAAM;;;;;;;;GAgCwB;wBA0I5B,UAAU,CAAC,UAAU,QAlGvB,IAAI,0BACU,WAAW,GAAG,GAAG,gBAAgB,WAAW,KAAK,OAAO;;;;;;;;GAiG7B,CAAC;0BArM9B,mBAAmB;iCADZ,kBAAkB;yBAE1B,aAAa"}

package/src/bijection.js

@@ -1,19 +1,33 @@
 import { b, Fail } from '@endo/errors';
 import { M } from '@endo/patterns';
-import { Far } from '@endo/pass-style';
+import { Far, isPassable } from '@endo/pass-style';
 import { toPassableCap } from '@agoric/vow';
 import { makeEphemera } from './ephemera.js';
 
+/**
+ * @import {PassableCap} from '@endo/pass-style'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Vow} from '@agoric/vow'
+ * @import {Ephemera} from './types.js';
+ */
+
 const BijectionI = M.interface('Bijection', {
   reset: M.call().returns(),
-  init: M.call(M.any(), M.any()).returns(),
-  hasGuest: M.call(M.any()).returns(M.boolean()),
+  unwrapInit: M.call(M.raw(), M.any()).returns(M.raw()),
+  hasGuest: M.call(M.raw()).returns(M.boolean()),
   hasHost: M.call(M.any()).returns(M.boolean()),
-  has: M.call(M.any(), M.any()).returns(M.boolean()),
-  guestToHost: M.call(M.any()).returns(M.any()),
-  hostToGuest: M.call(M.any()).returns(M.any()),
+  has: M.call(M.raw(), M.any()).returns(M.boolean()),
+  guestToHost: M.call(M.raw()).returns(M.any()),
+  hostToGuest: M.call(M.any()).returns(M.raw()),
 });
 
+/**
+ * @param {unknown} k
+ */
+const toKey = k =>
+  // @ts-expect-error k specificity
+  isPassable(k) ? toPassableCap(k) : k;
+
 /**
  * Makes a store like a WeakMapStore except that Promises and Vows can also be
  * used as keys.
@@ -34,15 +48,15 @@ const makeVowishStore = name => {
 
   return Far(name, {
     init: (k, v) => {
-      const k2 = toPassableCap(k);
+      const k2 = toKey(k);
       !map.has(k2) ||
         // separate line so I can set a breakpoint
         Fail`${b(name)} key already bound: ${k} -> ${map.get(k2)} vs ${v}`;
       map.set(k2, v);
     },
-    has: k => map.has(toPassableCap(k)),
+    has: k => map.has(toKey(k)),
     get: k => {
-      const k2 = toPassableCap(k);
+      const k2 = toKey(k);
       map.has(k2) ||
         // separate line so I can set a breakpoint
         Fail`${b(name)} key not found: ${k}`;
@@ -54,14 +68,59 @@ const makeVowishStore = name => {
 /** @typedef {ReturnType<makeVowishStore>} VowishStore */
 
 /**
+ * As suggested by the name, this *mostly* represents a mathematical bijection,
+ * i.e., a one-to-one mapping. But rather than a general bijection map store
+ * (which would be interesting), this one is specialized to support the
+ * async-flow replay-membrane, where the two sides are "guest" and "host".
+ *
+ * If `unwrap` is omitted, it defaults to an identity function on its
+ * `guestWrapper` argument, in which case this does represent exactly a
+ * mathematical bijection between host and guest.
+ *
+ * If `unwrap` is provided, it supports the unwrapping of guest wrappers, into
+ * so-call unwrapped guests, like state records or functions,
+ * that are not themselves `Passable`. This was motivated to support endowments,
+ * which are often similar non-passables on the host-side.
+ * However, it can support the unwrapping of any guest remotable wrapper.
+ * When `unwrap` returns something `!==` its `guestWrapper` argument,
+ * then we preserve the bijection (one-to-one mapping) between the host
+ * and the unwrapped guest. To support the internal bookkeeping of the
+ * replay-membrane, we also map the guestWrapper to that same host, but
+ * not vice versa. Since the guest wrapper should not be visible outside
+ * the replay-membrane, this extra bookkeeping should be invisible.
+ *
+ * This bijection only grows monotonically until reset, which clears the entire
+ * mapping. Until reset, each pair, once entered, cannot be altered or deleted.
+ * The mapping itself is completely ephemeral, but the bijection object itself
+ * is durable. The mapping is also effectively reset by reincarnation, i.e,
+ * on upgrade.
+ * See also https://github.com/Agoric/agoric-sdk/issues/9365
+ *
+ * To eventually address https://github.com/Agoric/agoric-sdk/issues/9301
+ * the bijection itself persists to support passing guest-created remotables
+ * and promises through the membrane.
+ * The resulting host wrappers must not only survive upgrade, then must
+ * reestablish their mapping to the correct corresponding guest objects that
+ * they are taken to wrap. We plan to do this via `equate` repopulating
+ * the bijection by the time the host wrapper needs to know what
+ * corresponding guest it is now taken to wrap.
+ *
  * @param {Zone} zone
+ * @param {(hostWrapper: PassableCap | Vow, guestWrapper: PassableCap) => unknown} [unwrap]
+ *  defaults to identity function on `guestWrapper` arg
  */
-export const prepareBijection = zone => {
+export const prepareBijection = (
+  zone,
+  unwrap = (_hostWrapper, guestWrapper) => guestWrapper,
+) => {
   /** @type {Ephemera<Bijection, VowishStore>} */
   const g2h = makeEphemera(() => makeVowishStore('guestToHost'));
   /** @type {Ephemera<Bijection, VowishStore>} */
   const h2g = makeEphemera(() => makeVowishStore('hostToGuest'));
 
+  // Guest arguments and results are now unguarded, i.e., guarded by `M.raw()`,
+  // so that they can be non-passables. Therefore, we need to harden these
+  // here.
   return zone.exoClass('Bijection', BijectionI, () => ({}), {
     reset() {
       const { self } = this;
@@ -69,20 +128,31 @@ export const prepareBijection = zone => {
       g2h.resetFor(self);
       h2g.resetFor(self);
     },
-    init(g, h) {
+    unwrapInit(g, h) {
+      harden(g);
       const { self } = this;
       const guestToHost = g2h.for(self);
       const hostToGuest = h2g.for(self);
 
+      const gUnwrapped = unwrap(h, g);
       !hostToGuest.has(h) ||
-        Fail`hostToGuest key already bound: ${h} -> ${hostToGuest.get(h)} vs ${g}`;
-      guestToHost.init(g, h);
-      hostToGuest.init(h, g);
-      self.has(g, h) ||
+        Fail`hostToGuest key already bound: ${h} -> ${hostToGuest.get(h)} vs ${gUnwrapped}`;
+      guestToHost.init(gUnwrapped, h);
+      hostToGuest.init(h, gUnwrapped);
+      self.has(gUnwrapped, h) ||
         // separate line so I can set a breakpoint
         Fail`internal: ${g} <-> ${h}`;
+      if (g !== gUnwrapped) {
+        // When they are different, also map g to h without mapping h to g
+        !guestToHost.has(g) ||
+          // separate line so I can set a breakpoint
+          Fail`hidden guest wrapper already bound ${g}`;
+        guestToHost.init(g, h);
+      }
+      return gUnwrapped;
     },
     hasGuest(g) {
+      harden(g);
       const { self } = this;
       const guestToHost = g2h.for(self);
 
@@ -95,6 +165,7 @@ export const prepareBijection = zone => {
       return hostToGuest.has(h);
     },
     has(g, h) {
+      harden(g);
       const { self } = this;
       const guestToHost = g2h.for(self);
       const hostToGuest = h2g.for(self);
@@ -112,6 +183,7 @@ export const prepareBijection = zone => {
       }
     },
     guestToHost(g) {
+      harden(g);
       const { self } = this;
       const guestToHost = g2h.for(self);
 
@@ -121,6 +193,9 @@ export const prepareBijection = zone => {
       const { self } = this;
       const hostToGuest = h2g.for(self);
 
+      // Even though result is unguarded, i.e., guarded by `M.raw()`, don't
+      // need to harden here because was already harden when added to
+      // collection.
       return hostToGuest.get(h);
     },
   });

package/src/convert.d.ts

@@ -2,4 +2,5 @@ export function makeConvertKit(bijection: any, makeGuestForHostRemotable: any, m
     guestToHost: (specimen: Passable, label?: string | undefined) => any;
     hostToGuest: (specimen: Passable, label?: string | undefined) => any;
 };
+import type { Passable } from '@endo/pass-style';
 //# sourceMappingURL=convert.d.ts.map

package/src/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["convert.js"],"names":[],"mappings":"AA2EO;;;EAsDN"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["convert.js"],"names":[],"mappings":"AA+EO;4BARM,QAAQ;4BAAR,QAAQ;EA4DpB;8BAtH0B,kBAAkB"}

package/src/convert.js

@@ -1,5 +1,6 @@
 import { Fail, X, annotateError, makeError, q } from '@endo/errors';
 import { throwLabeled } from '@endo/common/throw-labeled.js';
+import { objectMap } from '@endo/common/object-map.js';
 import {
   getErrorConstructor,
   getTag,
@@ -8,7 +9,10 @@ import {
   passStyleOf,
 } from '@endo/pass-style';
 import { isVow } from '@agoric/vow/src/vow-utils.js';
-import { objectMap } from '@endo/common/object-map.js';
+
+/**
+ * @import {Passable} from '@endo/pass-style'
+ */
 
 const makeConvert = (convertRemotable, convertPromiseOrVow, convertError) => {
   const convertRecur = (specimen, label) => {
@@ -106,16 +110,14 @@ export const makeConvertKit = (
         return bijection.hostToGuest(hRem);
       }
       const gRem = makeGuestForHostRemotable(hRem);
-      bijection.init(gRem, hRem);
-      return gRem;
+      return bijection.unwrapInit(gRem, hRem);
     },
     hVow => {
       if (bijection.hasHost(hVow)) {
         return bijection.hostToGuest(hVow);
       }
       const gP = makeGuestForHostVow(hVow);
-      bijection.init(gP, hVow);
-      return gP;
+      return bijection.unwrapInit(gP, hVow);
     },
     hErr => {
       const gErr = harden(

package/src/endowments.d.ts

@@ -0,0 +1,16 @@
+export function forwardingMethods(rem: any): {
+    [k: string]: any;
+};
+export function makeSharedStateRecord<K extends string | number | symbol, R extends Record<K, any>>(dataRecord: R): R;
+export function prepareEndowmentTools(outerZone: Zone, outerOptions?: PreparationOptions | undefined): {
+    prepareEndowment: (zone: Zone, tag: string, e: unknown) => any;
+    unwrap: (wrapped: any, guestWrapped: any) => any;
+};
+export type EndowmentKind = "promise" | "storable" | "far" | "function" | "array" | "record" | "state";
+export type EndowmentTools = ReturnType<(outerZone: Zone, outerOptions?: PreparationOptions | undefined) => {
+    prepareEndowment: (zone: Zone, tag: string, e: unknown) => any;
+    unwrap: (wrapped: any, guestWrapped: any) => any;
+}>;
+import type { Zone } from '@agoric/base-zone';
+import type { PreparationOptions } from '../src/types.js';
+//# sourceMappingURL=endowments.d.ts.map

package/src/endowments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endowments.d.ts","sourceRoot":"","sources":["endowments.js"],"names":[],"mappings":"AA4CO;;EASN;AAaM,sCALmC,CAAC,SAA5B,MAAM,GAAG,MAAM,GAAG,MAAQ,EACX,CAAC,SAAjB,MAAM,CAAC,CAAC,EAAE,GAAG,CAAE,cAClB,CAAC,GACC,CAAC,CAqBX;AAMI,iDAHI,IAAI;6BA6GF,IAAI,OACJ,MAAM,KACN,OAAO;;EAyFnB;4BA9QY,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO;6BAkR1E,UAAU,aA5MZ,IAAI;6BA6GF,IAAI,OACJ,MAAM,KACN,OAAO;;EA6F0B;0BAxRvB,mBAAmB;wCAEL,iBAAiB"}