Merge pull request #7057 from Agoric/mfig-zones

feat(zone): abstract heap, virtual, and durable object interface

.github/workflows/test-all-packages.yml

@@ -201,6 +201,8 @@ jobs:
         run: cd packages/time && yarn ${{ steps.vars.outputs.test }} | $TEST_COLLECT
       - name: yarn test (swingset-liveslots)
         run: cd packages/swingset-liveslots && yarn ${{ steps.vars.outputs.test }} | $TEST_COLLECT
+      - name: yarn test (zone)
+        run: cd packages/zone && yarn ${{ steps.vars.outputs.test }} | $TEST_COLLECT
 
         # The meta-test!
       - name: Check for untested packages

packages/agoric-cli/src/sdk-package-names.js

@@ -43,5 +43,6 @@ export default [
   "@agoric/xsnap",
   "@agoric/xsnap-lockdown",
   "@agoric/zoe",
+  "@agoric/zone",
   "agoric"
 ];

packages/store/src/patterns/exo-makers.js

@@ -47,15 +47,14 @@ export const initEmpty = () => emptyRecord;
  */
 
 /**
- * @template A args to init
- * @template S state from init
- * @template {Record<string | symbol, CallableFunction>} T methods
+ * @template {(...args: any[]) => any} I init function
+ * @template {Record<string | symbol, CallableFunction>} M methods
  * @param {string} tag
  * @param {any} interfaceGuard
- * @param {(...args: A[]) => S} init
- * @param {T & ThisType<{ self: T, state: S }>} methods
- * @param {FarClassOptions<Context<S,T>>} [options]
- * @returns {(...args: A[]) => (T & import('@endo/eventual-send').RemotableBrand<{}, T>)}
+ * @param {I} init
+ * @param {M & ThisType<{ self: M, state: ReturnType<I> }>} methods
+ * @param {FarClassOptions<Context<ReturnType<I>, M>>} [options]
+ * @returns {(...args: Parameters<I>) => (M & import('@endo/eventual-send').RemotableBrand<{}, M>)}
  */
 export const defineExoClass = (
   tag,
@@ -64,7 +63,7 @@ export const defineExoClass = (
   methods,
   { finish = undefined } = {},
 ) => {
-  /** @type {WeakMap<T,Context<S, T>>} */
+  /** @type {WeakMap<M,Context<ReturnType<I>, M>>} */
   const contextMap = new WeakMap();
   const prototype = defendPrototype(
     tag,
@@ -73,14 +72,17 @@ export const defineExoClass = (
     true,
     interfaceGuard,
   );
+  /**
+   * @param  {Parameters<I>} args
+   */
   const makeInstance = (...args) => {
     // Be careful not to freeze the state record
     const state = seal(init(...args));
-    /** @type {T} */
+    /** @type {M} */
     // @ts-expect-error could be instantiated with different subtype
     const self = harden({ __proto__: prototype });
     // Be careful not to freeze the state record
-    /** @type {Context<S,T>} */
+    /** @type {Context<ReturnType<I>,M>} */
     const context = freeze({ state, self });
     contextMap.set(self, context);
     if (finish) {
@@ -94,15 +96,14 @@ export const defineExoClass = (
 harden(defineExoClass);
 
 /**
- * @template A args to init
- * @template S state from init
- * @template {Record<string, Record<string | symbol, CallableFunction>>} F methods
+ * @template {(...args: any[]) => any} I init function
+ * @template {Record<string, Record<string | symbol, CallableFunction>>} F facet methods
  * @param {string} tag
  * @param {any} interfaceGuardKit
- * @param {(...args: A[]) => S} init
- * @param {F & ThisType<{ facets: F, state: S }> } methodsKit
- * @param {FarClassOptions<KitContext<S,F>>} [options]
- * @returns {(...args: A[]) => F}
+ * @param {I} init
+ * @param {F & ThisType<{ facets: F, state: ReturnType<I> }> } methodsKit
+ * @param {FarClassOptions<KitContext<ReturnType<I>,F>>} [options]
+ * @returns {(...args: Parameters<I>) => F}
  */
 export const defineExoClassKit = (
   tag,
@@ -119,6 +120,9 @@ export const defineExoClassKit = (
     true,
     interfaceGuardKit,
   );
+  /**
+   * @param {Parameters<I>} args
+   */
   const makeInstanceKit = (...args) => {
     // Be careful not to freeze the state record
     const state = seal(init(...args));
@@ -145,7 +149,7 @@ export const defineExoClassKit = (
 harden(defineExoClassKit);
 
 /**
- * @template {Record<string, Method>} T
+ * @template {Record<string | symbol, CallableFunction>} T
  * @param {string} tag
  * @param {InterfaceGuard | undefined} interfaceGuard CAVEAT: static typing does not yet support `callWhen` transformation
  * @param {T} methods

packages/store/src/types.js

@@ -753,10 +753,17 @@
 
 /**
  * @typedef {any} MethodGuardMaker
- * a parameter list like foo(a, b, c = d, …e) => f should be guarded by
- * something like
- * foo: M.call(AShape, BShape).optional(CShape).rest(EShape).returns(FShape)
- * optional is for optional (=) params. rest is for … (varargs) params
+ * A method name and parameter/return signature like:
+ * ```js
+ *   foo(a, b, c = d, ...e) => f
+ * ```
+ * should be guarded by something like:
+ * ```js
+ * {
+ *   ...otherMethodGuards,
+ *   foo: M.call(AShape, BShape).optional(CShape).rest(EShape).returns(FShape),
+ * }
+ * ```
  */
 
 /** @typedef {{ klass: 'methodGuard', callKind: 'sync' | 'async', returnGuard: unknown }} MethodGuard */

packages/store/test/test-heap-classes.js

@@ -106,6 +106,7 @@ test('test makeExo', t => {
   t.throws(() => upCounter.incr(-3), {
     message: 'In "incr" method of (upCounter): arg 0?: -3 - Must be >= 0',
   });
+  // @ts-expect-error deliberately bad arg for testing
   t.throws(() => upCounter.incr('foo'), {
     message:
       'In "incr" method of (upCounter): arg 0?: string "foo" - Must be a number',

packages/vat-data/src/index.js

@@ -21,6 +21,7 @@ export {
   provideDurableMapStore,
   provideDurableWeakMapStore,
   provideDurableSetStore,
+  provideDurableWeakSetStore,
   // deprecated
   defineKind,
   defineKindMulti,

packages/vat-data/src/vat-data-bindings.js

@@ -152,6 +152,8 @@ export const makeStoreUtils = VatData => {
     makeScalarBigWeakMapStore,
     // eslint-disable-next-line no-shadow -- these literally do shadow the globals
     makeScalarBigSetStore,
+    // eslint-disable-next-line no-shadow -- these literally do shadow the globals
+    makeScalarBigWeakSetStore,
   } = VatData;
 
   /**
@@ -187,10 +189,22 @@ export const makeStoreUtils = VatData => {
     );
   harden(provideDurableSetStore);
 
+  /**
+   * @param {import('./types').Baggage} baggage
+   * @param {string} name
+   * @param {Omit<StoreOptions, 'durable'>} options
+   */
+  const provideDurableWeakSetStore = (baggage, name, options = {}) =>
+    provide(baggage, name, () =>
+      makeScalarBigWeakSetStore(name, { durable: true, ...options }),
+    );
+  harden(provideDurableWeakSetStore);
+
   return harden({
     provideDurableMapStore,
     provideDurableWeakMapStore,
     provideDurableSetStore,
+    provideDurableWeakSetStore,
   });
 };
 
@@ -199,4 +213,5 @@ export const {
   provideDurableMapStore,
   provideDurableWeakMapStore,
   provideDurableSetStore,
+  provideDurableWeakSetStore,
 } = globalStoreUtils;

packages/zone/durable.js

@@ -0,0 +1 @@
+export * from './src/durable.js';

packages/zone/heap.js

@@ -0,0 +1 @@
+export * from './src/heap.js';

packages/zone/jsconfig.json

@@ -0,0 +1,19 @@
+// This file can contain .js-specific Typescript compiler config.
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "checkJs": true,
+    "noEmit": true,
+    "downlevelIteration": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "moduleResolution": "node",
+  },
+  "include": [
+    "*.js",
+    "scripts",
+    "src",
+    "test",
+  ],
+}

packages/zone/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agoric/zone",
+  "version": "0.1.0",
+  "description": "Allocation zone abstraction for objects on the heap, persistent stores, etc.",
+  "type": "module",
+  "repository": "https://github.com/Agoric/agoric-sdk",
+  "main": "./src/index.js",
+  "scripts": {
+    "build": "exit 0",
+    "test": "true || ava",
+    "test:c8": "true || c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
+    "test:xs": "exit 0",
+    "lint-fix": "yarn lint:eslint --fix",
+    "lint": "run-s --continue-on-error lint:*",
+    "lint:types": "tsc -p jsconfig.json",
+    "lint:eslint": "eslint ."
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./durable.js": "./durable.js",
+    "./heap.js": "./heap.js",
+    "./virtual.js": "./virtual.js"
+  },
+  "keywords": [],
+  "author": "Agoric",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@agoric/store": "^0.8.3",
+    "@agoric/vat-data": "^0.4.3",
+    "@endo/far": "^0.2.14"
+  },
+  "devDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14.15.0"
+  },
+  "ava": {
+    "files": [
+      "test/**/test-*.js"
+    ],
+    "timeout": "20m",
+    "workerThreads": false
+  }
+}

packages/zone/src/durable.js

@@ -0,0 +1,82 @@
+import {
+  canBeDurable,
+  makeScalarMapStore,
+  prepareExo,
+  prepareExoClass,
+  prepareExoClassKit,
+  provideDurableMapStore,
+  provideDurableSetStore,
+  provideDurableWeakMapStore,
+  provideDurableWeakSetStore,
+  M,
+} from '@agoric/vat-data';
+
+import { Far } from '@endo/far';
+
+/**
+ * @param {() => import('@agoric/vat-data').Baggage} getBaggage
+ */
+const attachDurableStores = getBaggage => {
+  /** @type {import('.').Zone['mapStore']} */
+  const mapStore = (label, options) =>
+    provideDurableMapStore(getBaggage(), label, options);
+  /** @type {import('.').Zone['setStore']} */
+  const setStore = (label, options) =>
+    provideDurableSetStore(getBaggage(), label, options);
+  /** @type {import('.').Zone['weakSetStore']} */
+  const weakSetStore = (label, options) =>
+    provideDurableWeakSetStore(getBaggage(), label, options);
+  /** @type {import('.').Zone['weakMapStore']} */
+  const weakMapStore = (label, options) =>
+    provideDurableWeakMapStore(getBaggage(), label, options);
+
+  /** @type {import('.').Stores} */
+  return Far('durableStores', {
+    // eslint-disable-next-line no-use-before-define
+    detached: () => detachedDurableStores,
+    isStorable: canBeDurable,
+    mapStore,
+    setStore,
+    weakMapStore,
+    weakSetStore,
+  });
+};
+
+/** @type {import('.').Stores} */
+export const detachedDurableStores = attachDurableStores(() =>
+  makeScalarMapStore('detached'),
+);
+
+/**
+ * Create a zone whose objects persist between Agoric vat upgrades.
+ *
+ * @param {import('@agoric/vat-data').Baggage} baggage
+ * @returns {import('.').Zone}
+ */
+export const makeDurableZone = baggage => {
+  /** @type {import('.').Zone['exoClass']} */
+  const exoClass = (...args) => prepareExoClass(baggage, ...args);
+  /** @type {import('.').Zone['exoClassKit']} */
+  const exoClassKit = (...args) => prepareExoClassKit(baggage, ...args);
+  /** @type {import('.').Zone['exo']} */
+  const exo = (...args) => prepareExo(baggage, ...args);
+
+  const attachedStores = attachDurableStores(() => baggage);
+
+  /** @type {import('.').Zone['subZone']} */
+  const subZone = (label, options = {}) => {
+    const subBaggage = provideDurableMapStore(baggage, label, options);
+    return makeDurableZone(subBaggage);
+  };
+
+  return Far('durableZone', {
+    exo,
+    exoClass,
+    exoClassKit,
+    subZone,
+    ...attachedStores,
+  });
+};
+harden(makeDurableZone);
+
+export { M };

packages/zone/src/heap.js

@@ -0,0 +1,40 @@
+import {
+  makeExo,
+  defineExoClass,
+  defineExoClassKit,
+  makeScalarMapStore,
+  makeScalarSetStore,
+  makeScalarWeakMapStore,
+  makeScalarWeakSetStore,
+  M,
+} from '@agoric/store';
+
+import { Far } from '@endo/far';
+
+/**
+ * @type {import('.').Stores}
+ */
+const heapStores = Far('heapStores', {
+  detached: () => heapStores,
+  isStorable: _specimen => true,
+
+  setStore: makeScalarSetStore,
+  mapStore: makeScalarMapStore,
+  weakMapStore: makeScalarWeakMapStore,
+  weakSetStore: makeScalarWeakSetStore,
+});
+
+/**
+ * A heap (in-memory) zone that uses the default exo and store implementations.
+ *
+ * @type {import('.').Zone}
+ */
+export const heapZone = Far('heapZone', {
+  exoClass: defineExoClass,
+  exoClassKit: defineExoClassKit,
+  exo: makeExo,
+  subZone: (_label, _options) => heapZone,
+  ...heapStores,
+});
+
+export { M };