@agoric/base-zone 0.1.1-other-dev-3eb1a1d.0 → 0.1.1-other-dev-d15096d.0.d15096d

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@agoric/base-zone",
-  "version": "0.1.1-other-dev-3eb1a1d.0+3eb1a1d",
+  "version": "0.1.1-other-dev-d15096d.0.d15096d",
   "description": "Allocation zone abstraction library and heap implementation",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
   "main": "./src/index.js",
   "scripts": {
     "build": "exit 0",
-    "prepack": "tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' '*.tsbuildinfo'",
+    "prepack": "yarn run -T tsc --build tsconfig.build.json",
+    "postpack": "git clean -f '*.d.*ts*' '*.tsbuildinfo'",
     "test": "ava",
-    "test:c8": "c8 --all $C8_OPTIONS ava",
+    "test:c8": "c8 --all ${C8_OPTIONS:-} ava",
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc",
-    "lint:eslint": "eslint ."
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:types": "yarn run -T tsc",
+    "lint:eslint": "yarn run -T eslint ."
   },
   "exports": {
     ".": "./src/index.js",
@@ -27,24 +27,24 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/store": "0.9.3-other-dev-3eb1a1d.0+3eb1a1d",
-    "@endo/common": "^1.2.8",
-    "@endo/errors": "^1.2.8",
-    "@endo/exo": "^1.5.7",
-    "@endo/far": "^1.1.9",
-    "@endo/pass-style": "^1.4.7",
-    "@endo/patterns": "^1.4.7"
+    "@agoric/store": "0.9.3-other-dev-d15096d.0.d15096d",
+    "@endo/common": "^1.2.13",
+    "@endo/errors": "^1.2.13",
+    "@endo/exo": "^1.5.12",
+    "@endo/far": "^1.1.14",
+    "@endo/pass-style": "^1.6.3",
+    "@endo/patterns": "^1.7.0"
   },
   "devDependencies": {
-    "@endo/init": "^1.1.7",
-    "@endo/ses-ava": "^1.2.8",
+    "@endo/init": "^1.1.12",
+    "@endo/ses-ava": "^1.3.2",
     "ava": "^5.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": "^18.12 || ^20.9"
+    "node": "^20.9 || ^22.11"
   },
   "ava": {
     "files": [
@@ -57,7 +57,7 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 91.4
+    "atLeast": 93.22
   },
-  "gitHead": "3eb1a1d2d75b2b4a94807cd3bf759bc9fc531f05"
+  "gitHead": "d15096dc4ff8b96e9b6cd11954c20d3a9efbb393"
 }

package/src/heap.d.ts

@@ -1,2 +1,3 @@
-export function makeHeapZone(baseLabel?: string | undefined): import("./types.js").Zone;
+export function makeHeapZone(baseLabel?: string): Zone;
+import type { Zone } from './types.js';
 //# 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,CA4BrC"}
+{"version":3,"file":"heap.d.ts","sourceRoot":"","sources":["heap.js"],"names":[],"mappings":"AAwCO,yCAHI,MAAM,GACJ,IAAI,CA4BhB;0BAhDsB,YAAY"}

package/src/heap.js

@@ -15,7 +15,12 @@ import { agoricVatDataKeys as keys } from './keys.js';
 import { watchPromise } from './watch-promise.js';
 
 /**
- * @type {import('./types.js').Stores}
+ * @import {Stores} from './types.js';
+ * @import {Zone} from './types.js';
+ */
+
+/**
+ * @type {Stores}
  */
 const detachedHeapStores = Far('heapStores', {
   detached: () => detachedHeapStores,
@@ -31,7 +36,7 @@ const detachedHeapStores = Far('heapStores', {
  * Create a heap (in-memory) zone that uses the default exo and store implementations.
  *
  * @param {string} [baseLabel]
- * @returns {import('./types.js').Zone}
+ * @returns {Zone}
  */
 export const makeHeapZone = (baseLabel = 'heapZone') => {
   const { makeOnce, wrapProvider } = makeOnceKit(baseLabel, detachedHeapStores);

package/src/is-passable.d.ts

@@ -1,2 +1,3 @@
 export function isPassable(specimen: any): specimen is Passable;
+import type { Passable } from '@endo/pass-style';
 //# 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":"AAOO,qCAHI,GAAG,GACD,QAAQ,IAAI,QAAQ,CAE6B"}
+{"version":3,"file":"is-passable.d.ts","sourceRoot":"","sources":["is-passable.js"],"names":[],"mappings":"AAWO,qCAHI,GAAG,GACD,QAAQ,IAAI,QAAQ,CAE6B;8BARnC,kBAAkB"}

package/src/is-passable.js

@@ -1,5 +1,9 @@
 import { isPassable as realIsPassable } from '@endo/pass-style';
 
+/**
+ * @import {Passable} from '@endo/pass-style';
+ */
+
 /**
  * @deprecated Import `isPassable` directly from `@endo/pass-style`
  * @param {any} specimen

package/src/keys.d.ts

@@ -1,7 +1,8 @@
 /**
  * KeyMakers compatible with `@agoric/vat-data`.
  *
- * @type {import('./types.js').KeyMakers}
+ * @type {KeyMakers}
  */
-export const agoricVatDataKeys: import("./types.js").KeyMakers;
+export const agoricVatDataKeys: KeyMakers;
+import type { KeyMakers } from './types.js';
 //# sourceMappingURL=keys.d.ts.map

package/src/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["keys.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,gCAFU,OAAO,YAAY,EAAE,SAAS,CAQtC"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["keys.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,gCAFU,SAAS,CAQjB;+BApB0B,YAAY"}

package/src/keys.js

@@ -1,5 +1,9 @@
 // @ts-check
 
+/**
+ * @import {KeyMakers} from './types.js';
+ */
+
 /** @param {string} label */
 const kind = label => `${label}_kindHandle`;
 
@@ -9,7 +13,7 @@ const singleton = label => `${label}_singleton`;
 /**
  * KeyMakers compatible with `@agoric/vat-data`.
  *
- * @type {import('./types.js').KeyMakers}
+ * @type {KeyMakers}
  */
 export const agoricVatDataKeys = {
   exoClass: label => harden([kind(label)]),

package/src/make-once.d.ts

@@ -1,5 +1,7 @@
-export function makeOnceKit(debugName: string, stores: import("./types.js").Stores, backingStore?: globalThis.MapStore<string, any> | undefined): {
+export function makeOnceKit(debugName: string, stores: Stores, backingStore?: MapStore<string, any>): {
     makeOnce: <V>(key: string, maker: (key: string) => V) => V;
-    wrapProvider: <T extends (key: string, ...rest: any[]) => any>(provider: T, labelToKeys?: ((label: string) => string[]) | undefined) => T;
+    wrapProvider: <T extends (key: string, ...rest: any[]) => any>(provider: T, labelToKeys?: (label: string) => string[]) => T;
 };
+import type { Stores } from './types.js';
+import type { MapStore } from '@agoric/swingset-liveslots';
 //# 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;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"}
+{"version":3,"file":"make-once.d.ts","sourceRoot":"","sources":["make-once.js"],"names":[],"mappings":"AAiBO,uCAJI,MAAM,UACN,MAAM,iBACN,SAAS,MAAM,EAAE,GAAG,CAAC;eAwDjB,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,gBACD,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,KACzB,CAAC;EA4Cf;4BArFwB,YAAY;8BACV,4BAA4B"}

package/src/make-once.js

@@ -1,14 +1,19 @@
 // @ts-check
 import { Fail } from '@endo/errors';
 
+/**
+ * @import {Stores} from './types.js';
+ * @import {MapStore} from '@agoric/swingset-liveslots';
+ */
+
 /** @param {string} label */
 const defaultLabelToKeys = label => harden([label]);
 harden(defaultLabelToKeys);
 
 /**
  * @param {string} debugName Only used internally for diagnostics, not available to user code
- * @param {import('./types.js').Stores} stores
- * @param {import('@agoric/swingset-liveslots').MapStore<string, any>} [backingStore]
+ * @param {Stores} stores
+ * @param {MapStore<string, any>} [backingStore]
  */
 export const makeOnceKit = (debugName, stores, backingStore = undefined) => {
   // We need a detached setStore so that it isn't persisted as part of the zone.

package/src/prepare-attenuator.d.ts

@@ -0,0 +1,33 @@
+export function wrapperMethods(wrapperKindName: string, uMethodNames: PropertyKey[], extraMethods?: Record<PropertyKey, (...args: any[]) => any>): {
+    [x: string]: ((...args: any[]) => any) | ((...args: any[]) => any);
+};
+export function prepareAttenuatorMaker<U = any>(zone: Zone, uKindName: string, uMethodNames: (keyof U)[], options?: AttenuatorOptions<U>): MakeAttenuator;
+export function attenuateOne<U extends unknown>(underlying: U, uMethodNames: (keyof U)[], options?: AttenuatorOptions<U>): Partial<U>;
+export type MakeAttenuator<U = any> = (underlying: U) => Partial<U>;
+export type AttenuatorThis<U = any> = {
+    self: Partial<U>;
+    state: {
+        underlying: U;
+    };
+};
+export type AttenuatorOptions<U = any> = {
+    /**
+     * The `interfaceName` of the underlying interface guard.
+     * Defaults to the `uKindName`.
+     */
+    uInterfaceName?: string | undefined;
+    /**
+     * For guarding the `extraMethods`, if you include them below. These appear
+     * only on the synthesized interface guard for the attenuator, and
+     * do not necessarily correspond to any method of the underlying.
+     */
+    extraMethodGuards?: Record<PropertyKey, MethodGuard> | undefined;
+    /**
+     * Extra methods adding behavior only to the attenuator, and
+     * do not necessarily correspond to any methods of the underlying.
+     */
+    extraMethods?: Record<PropertyKey, (this: AttenuatorThis<U>, ...args: any[]) => any> | undefined;
+};
+import type { Zone } from '@agoric/base-zone';
+import type { MethodGuard } from '@endo/patterns';
+//# sourceMappingURL=prepare-attenuator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-attenuator.d.ts","sourceRoot":"","sources":["prepare-attenuator.js"],"names":[],"mappings":"AAgCO,gDAJI,MAAM,gBACN,WAAW,EAAE,iBACb,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;4BAAd,GAAG,EAAE,KAAK,GAAG;EA6BlD;AAoDG,uCAVO,CAAC,cACJ,IAAI,aACJ,MAAM,gBAEN,CAAC,MAAM,CAAC,CAAC,EAAE,YAGX,iBAAiB,CAAC,CAAC,CAAC,GAClB,cAAc,CA8B1B;AAqBM,6BANY,CAAC,8BACT,CAAC,gBACD,CAAC,MAAM,CAAC,CAAC,EAAE,YACX,iBAAiB,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAetB;2BA9Ga,CAAC,uBAEJ,CAAC,KACC,OAAO,CAAC,CAAC,CAAC;2BAIT,CAAC;UAED,OAAO,CAAC,CAAC,CAAC;WACV;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;8BAIjB,CAAC;;;;;;;;;;;;;;;;8CAcH,cAAc,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG;;0BApF9B,mBAAmB;iCADZ,gBAAgB"}

package/src/prepare-attenuator.js

@@ -0,0 +1,175 @@
+import { Fail, q } from '@endo/errors';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+import { M } from '@endo/patterns';
+import { makeHeapZone } from './heap.js';
+
+/**
+ * @import {MethodGuard} from '@endo/patterns';
+ * @import {Zone} from '@agoric/base-zone';
+ */
+
+// This attenuator implementation is just a simplification of the
+// revocable kit implementation in prepare-revocable.js. The revocable kit
+// provides both attenuation and revocation, since we can have both for the
+// price of just one level of indirection. But if you don't need revocation,
+// the revocable kit has more API complexity than you need.
+//
+// We could have built `prepareAttenuatorMaker` as a trivial wrapper around
+// `prepareRevocableMakerKit`. But then we'd have the weird artifact that the
+// `extraMethods` would see a `{ state, facets: { revocable, revoker }}` context
+// rather than a `{ state, self }` context. So instead, we copied and edited it
+// down. Please co-maintain these two modules.
+
+// Because the attenuator just uses an exo class rather than a class kit,
+// it cannot support the privilege separation of a distinct revoker facet.
+// But it can still support `selfRevoke` as a separate `extraMethod`, as shown
+// in a testcase at `prepare-attenuator.test.js`
+
+/**
+ * @param {string} wrapperKindName
+ * @param {PropertyKey[]} uMethodNames
+ * @param {Record<PropertyKey, (...args: any[]) => any>} [extraMethods]
+ */
+export const wrapperMethods = (
+  wrapperKindName,
+  uMethodNames,
+  extraMethods = {},
+) =>
+  harden({
+    ...fromUniqueEntries(
+      uMethodNames.map(name => [
+        name,
+        {
+          // Use concise method syntax for exo methods
+          [name](...args) {
+            // @ts-expect-error normal exo-this typing confusion
+            const { underlying } = this.state;
+
+            // Because attenuators still support someone adding `selfRevoke`
+            // as an `extraMethod`, this test is still useful. See the
+            // testcase in `prepare-attenuator.test.js`.
+            underlying !== undefined || Fail`${q(wrapperKindName)} revoked`;
+
+            return underlying[name](...args);
+          },
+          // @ts-expect-error using possible symbol as index type
+        }[name],
+      ]),
+    ),
+    ...extraMethods,
+  });
+harden(wrapperMethods);
+
+/**
+ * @template [U=any]
+ * @callback MakeAttenuator
+ * @param {U} underlying
+ * @returns {Partial<U>}
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} AttenuatorThis
+ * @property {Partial<U>} self
+ * @property {{ underlying: U }} state
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} AttenuatorOptions
+ * @property {string} [uInterfaceName]
+ *   The `interfaceName` of the underlying interface guard.
+ *   Defaults to the `uKindName`.
+ * @property {Record<
+ *   PropertyKey,
+ *   MethodGuard
+ * >} [extraMethodGuards]
+ * For guarding the `extraMethods`, if you include them below. These appear
+ * only on the synthesized interface guard for the attenuator, and
+ * do not necessarily correspond to any method of the underlying.
+ * @property {Record<
+ *   PropertyKey,
+ *   (this: AttenuatorThis<U>, ...args: any[]) => any
+ * >} [extraMethods]
+ * Extra methods adding behavior only to the attenuator, and
+ * do not necessarily correspond to any methods of the underlying.
+ */
+
+/**
+ * Make an exo class for wrapping an underlying exo class,
+ * where the wrapper is an attenuator of the underlying.
+ *
+ * @template [U=any]
+ * @param {Zone} zone
+ * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
+ * @param {(keyof U)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the attenuator.
+ * @param {AttenuatorOptions<U>} [options]
+ * @returns {MakeAttenuator}
+ */
+export const prepareAttenuatorMaker = (
+  zone,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const {
+    uInterfaceName = uKindName,
+    extraMethodGuards = {},
+    extraMethods = {},
+  } = options;
+  const AttenuatorI = M.interface(
+    `${uInterfaceName}_attenuator`,
+    extraMethodGuards,
+    { defaultGuards: 'raw' },
+  );
+
+  const attenuatorKindName = `${uKindName}_attenuator`;
+
+  return zone.exoClass(
+    attenuatorKindName,
+    AttenuatorI,
+    underlying => ({ underlying }),
+    wrapperMethods(attenuatorKindName, uMethodNames, extraMethods),
+    {
+      stateShape: { underlying: M.opt(M.remotable('underlying')) },
+    },
+  );
+};
+harden(prepareAttenuatorMaker);
+
+// cf. https://endojs.github.io/endo/functions/_endo_pass_style.Remotable.html
+const RemotablePrefixRE = /^(Alleged: |DebugName: )/;
+
+/**
+ * A convenience above `prepareAttenuatorMaker` for doing a singleton
+ * ephemeral attenuator, i.e., a new attenuator instance (and hidden class)
+ * that is allocated in the heap zone, and therefore ephemeral. The underlying
+ * can be durable or not, with no conflict with the attenuator being
+ * ephemeral. The price of this convenience is the allocation of the hidden
+ * class and wrapper methods per `attenuateOne` call, i.e., per attenuator
+ * instance.
+ *
+ * @template {any} U
+ * @param {U} underlying
+ * @param {(keyof U)[]} uMethodNames
+ * @param {AttenuatorOptions<U>} [options]
+ * @returns {Partial<U>}
+ */
+export const attenuateOne = (underlying, uMethodNames, options = undefined) => {
+  const heapZone = makeHeapZone();
+  const uKindName = (underlying[Symbol.toStringTag] || 'Underlying').replace(
+    RemotablePrefixRE,
+    '',
+  );
+  const makeAttenuator = prepareAttenuatorMaker(
+    heapZone,
+    uKindName,
+    uMethodNames,
+    options,
+  );
+  return makeAttenuator(underlying);
+};
+harden(attenuateOne);

package/src/prepare-revocable.d.ts

@@ -1,10 +1,13 @@
-export function prepareRevocableMakerKit<U = any>(zone: import("@agoric/base-zone").Zone, uKindName: string, uMethodNames: (string | symbol)[], options?: RevocableKitOptions<any> | undefined): RevocableMakerKit<U>;
+export function prepareRevocableMakerKit<U = any>(zone: Zone, uKindName: string, uMethodNames: PropertyKey[], options?: RevocableKitOptions<U>): RevocableMakerKit<U>;
+export type MakeRevocable<U = any> = (underlying: U) => Partial<U>;
+export type MakeRevocableKit<U = any> = (underlying: U) => RevocableKit<U>;
 export type RevocableMakerKit<U = any> = {
     revoke: (revocable: U) => boolean;
     /**
      *   Forwards to the underlying exo object, until revoked
      */
-    makeRevocable: (underlying: U) => U;
+    makeRevocable: MakeRevocable<U>;
+    makeRevocableKit: MakeRevocableKit<U>;
 };
 export type RevokerFacet = {
     revoke: () => boolean;
@@ -14,7 +17,7 @@ export type RevocableKit<U = any> = {
     /**
      *   Forwards to the underlying exo object, until revoked
      */
-    revocable: U;
+    revocable: Partial<U>;
 };
 export type RevocableKitThis<U = any> = {
     facets: RevocableKit<U>;
@@ -33,11 +36,13 @@ export type RevocableKitOptions<U = any> = {
      * only on the synthesized interface guard for the revocable caretaker, and
      * do not necessarily correspond to any method of the underlying.
      */
-    extraMethodGuards?: Record<string | symbol, import("@endo/patterns").MethodGuard> | undefined;
+    extraMethodGuards?: Record<PropertyKey, MethodGuard> | undefined;
     /**
      * Extra methods adding behavior only to the revocable caretaker, and
      * do not necessarily correspond to any methods of the underlying.
      */
-    extraMethods?: Record<string | symbol, (this: RevocableKitThis<U>, ...args: any[]) => any> | undefined;
+    extraMethods?: Record<PropertyKey, (this: RevocableKitThis<U>, ...args: any[]) => any> | undefined;
 };
+import type { Zone } from '@agoric/base-zone';
+import type { MethodGuard } from '@endo/patterns';
 //# sourceMappingURL=prepare-revocable.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"prepare-revocable.d.ts","sourceRoot":"","sources":["prepare-revocable.js"],"names":[],"mappings":"AA6FO,yCAVO,CAAC,cACJ,IAAI,aACJ,MAAM,gBAEN,WAAW,EAAE,YAGb,mBAAmB,CAAC,CAAC,CAAC,GACpB,iBAAiB,CAAC,CAAC,CAAC,CA4EhC;0BAvJa,CAAC,uBAEJ,CAAC,KACC,OAAO,CAAC,CAAC,CAAC;6BAIT,CAAC,uBAEJ,CAAC,KACC,YAAY,CAAC,CAAC,CAAC;8BAId,CAAC;YAED,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO;;;;mBACzB,aAAa,CAAC,CAAC,CAAC;sBAEhB,gBAAgB,CAAC,CAAC,CAAC;;;YAKnB,MAAM,OAAO;;yBAIb,CAAC;aAED,YAAY;;;;eACZ,OAAO,CAAC,CAAC,CAAC;;6BAKV,CAAC;YAED,YAAY,CAAC,CAAC,CAAC;WACf;QAAE,UAAU,EAAE,CAAC,CAAA;KAAE;;gCAIjB,CAAC;;;;;;;;;;;;;;;;8CAcH,gBAAgB,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,GAAG;;0BAnEhC,mBAAmB;iCADZ,gBAAgB"}

package/src/prepare-revocable.js

@@ -1,15 +1,39 @@
-import { Fail, q } from '@endo/errors';
-import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
 import { M } from '@endo/patterns';
+import { wrapperMethods } from './prepare-attenuator.js';
 
-/** @import {Amplify} from '@endo/exo'; */
+/**
+ * @import {Amplify} from '@endo/exo';
+ * @import {MethodGuard} from '@endo/patterns';
+ * @import {Zone} from '@agoric/base-zone';
+ */
+
+// This revocable kit implementation provides for both attenuation and
+// revocation, since both can be provided at the cost of one level of
+// indirection. But if you just need attenuation without revocation, better to
+// use the attenuator implementation in prepare-attenuator.js.
+// Please co-maintain these two modules.
+
+/**
+ * @template [U=any]
+ * @callback MakeRevocable
+ * @param {U} underlying
+ * @returns {Partial<U>}
+ */
+
+/**
+ * @template [U=any]
+ * @callback MakeRevocableKit
+ * @param {U} underlying
+ * @returns {RevocableKit<U>}
+ */
 
 /**
  * @template [U=any]
  * @typedef {object} RevocableMakerKit
  * @property {(revocable: U) => boolean} revoke
- * @property {(underlying: U) => U} makeRevocable
+ * @property {MakeRevocable<U>} makeRevocable
  *   Forwards to the underlying exo object, until revoked
+ * @property {MakeRevocableKit<U>} makeRevocableKit
  */
 
 /**
@@ -21,7 +45,7 @@ import { M } from '@endo/patterns';
  * @template [U=any]
  * @typedef {object} RevocableKit
  * @property {RevokerFacet} revoker
- * @property {U} revocable
+ * @property {Partial<U>} revocable
  *   Forwards to the underlying exo object, until revoked
  */
 
@@ -39,14 +63,14 @@ import { M } from '@endo/patterns';
  *   The `interfaceName` of the underlying interface guard.
  *   Defaults to the `uKindName`.
  * @property {Record<
- *   string|symbol,
- *   import('@endo/patterns').MethodGuard
+ *   PropertyKey,
+ *   MethodGuard
  * >} [extraMethodGuards]
  * For guarding the `extraMethods`, if you include them below. These appear
  * only on the synthesized interface guard for the revocable caretaker, and
  * do not necessarily correspond to any method of the underlying.
  * @property {Record<
- *   string|symbol,
+ *   PropertyKey,
  *   (this: RevocableKitThis<U>, ...args: any[]) => any
  * >} [extraMethods]
  * Extra methods adding behavior only to the revocable caretaker, and
@@ -58,13 +82,13 @@ import { M } from '@endo/patterns';
  * where the wrapper is a revocable forwarder.
  *
  * @template [U=any]
- * @param {import('@agoric/base-zone').Zone} zone
+ * @param {Zone} zone
  * @param {string} uKindName
  *   The `kindName` of the underlying exo class
- * @param {(string|symbol)[]} uMethodNames
+ * @param {PropertyKey[]} uMethodNames
  *   The method names of the underlying exo class that should be represented
  *   by transparently-forwarding methods of the revocable caretaker.
- * @param {RevocableKitOptions} [options]
+ * @param {RevocableKitOptions<U>} [options]
  * @returns {RevocableMakerKit<U>}
  */
 export const prepareRevocableMakerKit = (
@@ -75,22 +99,16 @@ export const prepareRevocableMakerKit = (
 ) => {
   const {
     uInterfaceName = uKindName,
-    extraMethodGuards = undefined,
-    extraMethods = undefined,
+    extraMethodGuards = {},
+    extraMethods = {},
   } = options;
   const RevocableIKit = harden({
     revoker: M.interface(`${uInterfaceName}_revoker`, {
       revoke: M.call().returns(M.boolean()),
     }),
-    revocable: M.interface(
-      `${uInterfaceName}_revocable`,
-      {
-        ...extraMethodGuards,
-      },
-      {
-        defaultGuards: 'raw',
-      },
-    ),
+    revocable: M.interface(`${uInterfaceName}_revocable`, extraMethodGuards, {
+      defaultGuards: 'raw',
+    }),
   });
 
   const revocableKindName = `${uKindName}_caretaker`;
@@ -101,9 +119,7 @@ export const prepareRevocableMakerKit = (
   const makeRevocableKit = zone.exoClassKit(
     revocableKindName,
     RevocableIKit,
-    underlying => ({
-      underlying,
-    }),
+    underlying => ({ underlying }),
     {
       revoker: {
         revoke() {
@@ -115,30 +131,10 @@ export const prepareRevocableMakerKit = (
           return true;
         },
       },
-      revocable: {
-        ...fromUniqueEntries(
-          uMethodNames.map(name => [
-            name,
-            {
-              // Use concise method syntax for exo methods
-              [name](...args) {
-                // @ts-expect-error normal exo-this typing confusion
-                const { underlying } = this.state;
-                underlying !== undefined ||
-                  Fail`${q(revocableKindName)} revoked`;
-                return underlying[name](...args);
-              },
-              // @ts-expect-error using possible symbol as index type
-            }[name],
-          ]),
-        ),
-        ...extraMethods,
-      },
+      revocable: wrapperMethods(revocableKindName, uMethodNames, extraMethods),
     },
     {
-      stateShape: {
-        underlying: M.opt(M.remotable('underlying')),
-      },
+      stateShape: { underlying: M.opt(M.remotable('underlying')) },
       receiveAmplifier: amp => {
         amplifier = amp;
       },
@@ -146,12 +142,9 @@ export const prepareRevocableMakerKit = (
   );
 
   /**
-   * @param {U} underlying
-   * @returns {U}
+   * @type {MakeRevocable}
    */
-  const makeRevocable = underlying =>
-    // @ts-expect-error some confusion about UU vs Guarded<U> I think
-    makeRevocableKit(underlying).revocable;
+  const makeRevocable = underlying => makeRevocableKit(underlying).revocable;
 
   /**
    * @param {U} revocable
@@ -169,6 +162,8 @@ export const prepareRevocableMakerKit = (
   return harden({
     revoke,
     makeRevocable,
+    /** @type {MakeRevocableKit} */
+    makeRevocableKit,
   });
 };
 harden(prepareRevocableMakerKit);

package/src/types.d.ts

@@ -43,7 +43,7 @@ export type Stores = {
     /**
      * provide a Map-like store named `label` in the zone
      */
-    mapStore: (label: string, options?: StoreOptions) => MapStore<any, any>;
+    mapStore: <K, V>(label: string, options?: StoreOptions) => MapStore<K, V>;
     /**
      * provide a Set-like store named `label` in the zone
      */
@@ -60,5 +60,10 @@ export type Stores = {
 import { makeExo } from '@endo/exo';
 import { defineExoClass } from '@endo/exo';
 import { defineExoClassKit } from '@endo/exo';
+import type { StoreOptions } from '@agoric/store';
 import { watchPromise } from './watch-promise.js';
+import type { MapStore } from '@agoric/store';
+import type { SetStore } from '@agoric/store';
+import type { WeakMapStore } from '@agoric/store';
+import type { WeakSetStore } from '@agoric/store';
 //# 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":"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,EACd,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;kBAEnD,CAAC,CAAC,EACX,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,CAAC;;wBAxCH,WAAW;+BAAX,WAAW;kCAAX,WAAW;6BAEzC,oBAAoB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"4BAcc,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,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,SAAS,CAAC,EAAE,CAAC,CAAC;;;;cAC/D,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,SAAS,CAAC,CAAC;;;;kBACzD,CAAC,CAAC,EAAE,CAAC,EACd,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,EAAE,CAAC,CAAC;;;;kBAEnD,CAAC,CAAC,EACX,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,CAAC;;wBAzCH,WAAW;+BAAX,WAAW;kCAAX,WAAW;kCAQS,eAAe;6BANjE,oBAAoB;8BAM8B,eAAe;8BAAf,eAAe;kCAAf,eAAe;kCAAf,eAAe"}

package/src/types.js

@@ -7,6 +7,7 @@ import { watchPromise } from './watch-promise.js';
 export {};
 
 /**
+ * @import {MapStore, SetStore, StoreOptions, WeakMapStore, WeakSetStore} from '@agoric/store';
  * @import {Key} from '@endo/patterns';
  * @import {Passable} from '@endo/pass-style';
  */
@@ -33,7 +34,7 @@ export {};
  * @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 {(label: string, options?: StoreOptions) => MapStore<any, any>} mapStore provide a Map-like store named `label` in the zone
+ * @property {<K, V>(label: string, options?: StoreOptions) => MapStore<K, V>} 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>(
  *   label: string, options?: StoreOptions) => WeakMapStore<K, V>

package/test/prepare-attenuator.test.js

@@ -0,0 +1,110 @@
+// Modeled on test-heap-classes.js
+
+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 { prepareAttenuatorMaker } from '../src/prepare-attenuator.js';
+
+const CounterI = M.interface('Counter', {
+  incr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+  decr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+});
+
+test('test attenuate defineVirtualExoClass', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounter = zone.exoClass(
+    'Counter',
+    CounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+      decr(y = 1) {
+        const { state } = this;
+        state.x -= y;
+        return state.x;
+      },
+    },
+  );
+
+  const makeUpAttenuator = prepareAttenuatorMaker(zone, 'UpCounter', ['incr']);
+
+  const makeUpCounter = x => makeUpAttenuator(makeUnderlyingCounter(x));
+
+  const upCounter = makeUpCounter(3);
+  t.is(upCounter.incr(5), 8);
+  t.throws(() => upCounter.decr(1), {
+    message: 'upCounter.decr is not a function',
+  });
+});
+
+test('test revoke defineVirtualExoClassKit', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounter = zone.exoClass(
+    'Counter',
+    CounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+      decr(y = 1) {
+        const { state } = this;
+        state.x -= y;
+        return state.x;
+      },
+    },
+  );
+
+  const makeDownAttenuator = prepareAttenuatorMaker(
+    zone,
+    'DownCounter',
+    ['decr'],
+    {
+      extraMethodGuards: {
+        selfRevoke: M.call().returns(M.boolean()),
+      },
+      extraMethods: {
+        selfRevoke() {
+          const { state } = this;
+          if (state.underlying === undefined) {
+            return false;
+          }
+          // @ts-expect-error Setting this to `undefined` is purposely outside
+          // the type system.
+          state.underlying = undefined;
+          return true;
+        },
+      },
+    },
+  );
+
+  const makeDownCounter = x => makeDownAttenuator(makeUnderlyingCounter(x));
+
+  const downCounter = makeDownCounter(3);
+  t.throws(() => downCounter.incr(1), {
+    message: 'downCounter.incr is not a function',
+  });
+  t.is(downCounter.decr(), 2);
+  t.is(downCounter.selfRevoke(), true);
+  t.throws(() => downCounter.decr(3), {
+    message: '"DownCounter_attenuator" revoked',
+  });
+});

package/tools/greeter.js

@@ -1,5 +1,9 @@
 import { M, getInterfaceGuardPayload } from '@endo/patterns';
 
+/**
+ * @import {Zone} from '../src/types.js';
+ */
+
 /**
  * @template {{}} T
  * @param {T} obj
@@ -38,7 +42,7 @@ export const GreeterWithAdminI = M.interface('GreeterWithAdmin', {
 });
 
 /**
- * @param {import('../src/types.js').Zone} zone
+ * @param {Zone} zone
  * @param {string} label
  * @param {string} nick
  */
@@ -51,7 +55,7 @@ export const prepareGreeterSingleton = (zone, label, nick) => {
 };
 
 /**
- * @param {import('../src/types.js').Zone} zone
+ * @param {Zone} zone
  */
 export const prepareGreeter = zone =>
   zone.exoClass('Greeter', GreeterWithAdminI, nick => ({ nick }), {
@@ -60,7 +64,7 @@ export const prepareGreeter = zone =>
   });
 
 /**
- * @param {import('../src/types.js').Zone} zone
+ * @param {Zone} zone
  */
 export const prepareGreeterKit = zone =>
   zone.exoClassKit(

package/tools/testers.js

@@ -1,8 +1,13 @@
 import * as g from './greeter.js';
 
 /**
- * @param {import('ava').Assertions} t
- * @param {import('../src/index.js').Zone} rootZone
+ * @import {Assertions} from 'ava';
+ * @import {Zone} from '../src/index.js';
+ */
+
+/**
+ * @param {Assertions} t
+ * @param {Zone} rootZone
  */
 export const testMakeOnce = (t, rootZone) => {
   const subZone = rootZone.subZone('sub');
@@ -52,7 +57,7 @@ const alreadyExceptionSpec = {
 
 /**
  * @template T
- * @param {import('ava').Assertions} t
+ * @param {Assertions} t
  * @param {() => T} fn
  * @param {*} spec
  * @returns {T}
@@ -64,8 +69,8 @@ const secondThrows = (t, fn, spec = alreadyExceptionSpec) => {
 };
 
 /**
- * @param {import('ava').Assertions} t
- * @param {import('../src/index.js').Zone} rootZone
+ * @param {Assertions} t
+ * @param {Zone} rootZone
  */
 export const testFirstZoneIncarnation = (t, rootZone) => {
   const subZone = secondThrows(t, () => rootZone.subZone('sub'));
@@ -93,8 +98,8 @@ export const testFirstZoneIncarnation = (t, rootZone) => {
 };
 
 /**
- * @param {import('ava').Assertions} t
- * @param {import('../src/index.js').Zone} rootZone
+ * @param {Assertions} t
+ * @param {Zone} rootZone
  */
 export const testSecondZoneIncarnation = (t, rootZone) => {
   const subZone = secondThrows(t, () => rootZone.subZone('sub'));

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["./heap.js","./zone-helpers.js","./src/heap.js","./src/index.js","./src/is-passable.js","./src/keys.js","./src/make-once.js","./src/prepare-revocable.js","./src/types.js","./src/watch-promise.js"],"version":"5.6.3"}
+{"root":["./heap.js","./zone-helpers.js","./src/heap.js","./src/index.js","./src/is-passable.js","./src/keys.js","./src/make-once.js","./src/prepare-attenuator.js","./src/prepare-revocable.js","./src/types.js","./src/watch-promise.js"],"version":"5.9.3"}

package/zone-helpers.d.ts

@@ -1,2 +1,3 @@
 export * from "./src/prepare-revocable.js";
+export * from "./src/prepare-attenuator.js";
 //# sourceMappingURL=zone-helpers.d.ts.map

package/zone-helpers.js

@@ -1 +1,2 @@
 export * from './src/prepare-revocable.js';
+export * from './src/prepare-attenuator.js';