@agoric/vat-data 0.5.3-other-dev-1f26562.0 → 0.5.3-other-dev-3eb1a1d.0

package/CHANGELOG.md

@@ -3,14 +3,6 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-### [0.5.3-u11.0](https://github.com/Agoric/agoric-sdk/compare/@agoric/vat-data@0.5.2...@agoric/vat-data@0.5.3-u11.0) (2023-08-24)
-
-**Note:** Version bump only for package @agoric/vat-data
-
-
-
-
-
 ### [0.5.2](https://github.com/Agoric/agoric-sdk/compare/@agoric/vat-data@0.5.1...@agoric/vat-data@0.5.2) (2023-06-02)
 
 **Note:** Version bump only for package @agoric/vat-data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/vat-data",
-  "version": "0.5.3-other-dev-1f26562.0+1f26562",
+  "version": "0.5.3-other-dev-3eb1a1d.0+3eb1a1d",
   "description": "Safe access to VatData global",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -8,7 +8,6 @@
   "scripts": {
     "build": "exit 0",
     "test": "ava",
-    "test:c8": "exit 0",
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
     "lint": "run-s --continue-on-error lint:*",
@@ -19,20 +18,36 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/assert": "0.6.1-other-dev-1f26562.0+1f26562",
-    "@agoric/internal": "0.3.3-other-dev-1f26562.0+1f26562",
-    "@agoric/store": "0.9.3-other-dev-1f26562.0+1f26562"
+    "@agoric/base-zone": "0.1.1-other-dev-3eb1a1d.0+3eb1a1d",
+    "@agoric/store": "0.9.3-other-dev-3eb1a1d.0+3eb1a1d",
+    "@agoric/swingset-liveslots": "0.10.3-other-dev-3eb1a1d.0+3eb1a1d",
+    "@endo/errors": "^1.2.8",
+    "@endo/exo": "^1.5.7",
+    "@endo/patterns": "^1.4.7"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "0.32.3-other-dev-1f26562.0+1f26562",
-    "ava": "^5.2.0",
-    "tsd": "^0.28.1"
+    "@endo/far": "^1.1.9",
+    "@endo/init": "^1.1.7",
+    "@endo/ses-ava": "^1.2.8",
+    "ava": "^5.3.0",
+    "tsd": "^0.31.1"
+  },
+  "ava": {
+    "require": [
+      "@endo/init/debug.js"
+    ],
+    "files": [
+      "test/**/*.test.*"
+    ]
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^18.12 || ^20.9"
+  },
+  "typeCoverage": {
+    "atLeast": 99.33
   },
-  "gitHead": "1f265627270d514ab48943f86c668eb58a280552"
+  "gitHead": "3eb1a1d2d75b2b4a94807cd3bf759bc9fc531f05"
 }

package/src/exo-utils.js

@@ -4,19 +4,28 @@ import { initEmpty } from '@agoric/store';
 
 import { provide, VatData as globalVatData } from './vat-data-bindings.js';
 
-/** @template L,R @typedef {import('@endo/eventual-send').RemotableBrand<L, R>} RemotableBrand */
-/** @template T @typedef {import('@endo/far').ERef<T>} ERef */
-/** @typedef {import('./types.js').Baggage} Baggage */
-/** @template T @typedef {import('./types.js').DefineKindOptions<T>} DefineKindOptions */
-/** @template T @typedef {import('./types.js').KindFacet<T>} KindFacet */
-/** @template T @typedef {import('./types.js').KindFacets<T>} KindFacets */
-/** @typedef {import('./types.js').DurableKindHandle} DurableKindHandle */
+/**
+ * @import {InterfaceGuard} from '@endo/patterns';
+ * @import {RemotableObject} from '@endo/pass-style';
+ * @import {Baggage, DefineKindOptions, DurableKindHandle, InterfaceGuardKit} from '@agoric/swingset-liveslots';
+ */
+
+// Some feedback if the init function is async
+/**
+ * @typedef {(...args: any[]) => any} InitState
+ */
+/**
+ * @template {InitState} I
+ * @typedef {ReturnType<I> extends Promise<any> ? never : ReturnType<I>} StateResult
+ */
 
 /**
- * Make a version of the argument function that takes a kind context but
- * ignores it.
+ * Make a version of the argument function that takes a kind context but ignores
+ * it.
  *
- * @type {<T extends Function>(fn: T) => import('./types.js').PlusContext<never, T>}
+ * @type {<T extends (...args: any) => any>(
+ *   fn: T,
+ * ) => import('@agoric/swingset-liveslots').PlusContext<never, T>}
  */
 export const ignoreContext =
   fn =>
@@ -25,6 +34,7 @@ export const ignoreContext =
 harden(ignoreContext);
 
 // TODO: Find a good home for this function used by @agoric/vat-data and testing code
+/** @param {import('@agoric/swingset-liveslots').VatData} VatData */
 export const makeExoUtils = VatData => {
   const {
     defineKind,
@@ -35,6 +45,7 @@ export const makeExoUtils = VatData => {
   } = VatData;
 
   /**
+   * @deprecated Use Exos/ExoClasses instead of Kinds
    * @param {Baggage} baggage
    * @param {string} kindName
    * @returns {DurableKindHandle}
@@ -45,7 +56,7 @@ export const makeExoUtils = VatData => {
 
   /**
    * @deprecated Use prepareExoClass instead
-   * @type {import('./types.js').PrepareKind}
+   * @type {import('@agoric/swingset-liveslots').PrepareKind}
    */
   const prepareKind = (
     baggage,
@@ -64,7 +75,7 @@ export const makeExoUtils = VatData => {
 
   /**
    * @deprecated Use prepareExoClassKit instead
-   * @type {import('./types.js').PrepareKindMulti}
+   * @type {import('@agoric/swingset-liveslots').PrepareKindMulti}
    */
   const prepareKindMulti = (
     baggage,
@@ -81,18 +92,25 @@ export const makeExoUtils = VatData => {
     );
   harden(prepareKindMulti);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
+   * @template {InitState} I init state function
    * @template T behavior
    * @param {string} tag
-   * @param {any} interfaceGuard
+   * @param {InterfaceGuard | undefined} interfaceGuard
    * @param {I} init
-   * @param {T & ThisType<{ self: T, state: ReturnType<I> }>} methods
-   * @param {DefineKindOptions<{ self: T, state: ReturnType<I> }>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     self: T;
+   *     state: StateResult<I>;
+   *   }>} methods
+   * @param {DefineKindOptions<{
+   *   self: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').Guarded<T>}
    */
   const defineVirtualExoClass = (tag, interfaceGuard, init, methods, options) =>
+    // @ts-expect-error cast
     defineKind(tag, init, methods, {
       ...options,
       thisfulMethods: true,
@@ -100,16 +118,22 @@ export const makeExoUtils = VatData => {
     });
   harden(defineVirtualExoClass);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
-   * @template {Record<string, Record<string | symbol, CallableFunction>>} T facets
+   * @template {InitState} I init state function
+   * @template {Record<string, Record<PropertyKey, CallableFunction>>} T facets
    * @param {string} tag
-   * @param {any} interfaceGuardKit
+   * @param {InterfaceGuardKit | undefined} interfaceGuardKit
    * @param {I} init
-   * @param {T & ThisType<{ facets: T, state: ReturnType<I> }> } facets
-   * @param {DefineKindOptions<{ facets: T, state: ReturnType<I> }>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     facets: import('@endo/exo').GuardedKit<T>;
+   *     state: StateResult<I>;
+   *   }>} facets
+   * @param {DefineKindOptions<{
+   *   facets: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').GuardedKit<T>}
    */
   const defineVirtualExoClassKit = (
     tag,
@@ -118,23 +142,30 @@ export const makeExoUtils = VatData => {
     facets,
     options,
   ) =>
+    // @ts-expect-error cast
     defineKindMulti(tag, init, facets, {
       ...options,
       thisfulMethods: true,
-      interfaceGuard: interfaceGuardKit,
+      interfaceGuardKit,
     });
   harden(defineVirtualExoClassKit);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
-   * @template {Record<string | symbol, CallableFunction>} T methods
+   * @template {InitState} I init state function
+   * @template {Record<PropertyKey, CallableFunction>} T methods
    * @param {DurableKindHandle} kindHandle
-   * @param {any} interfaceGuard
+   * @param {InterfaceGuard | undefined} interfaceGuard
    * @param {I} init
-   * @param {T & ThisType<{ self: T, state: ReturnType<I> }>} methods
-   * @param {DefineKindOptions<{ self: T, state: ReturnType<I> }>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     self: T;
+   *     state: StateResult<I>;
+   *   }>} methods
+   * @param {DefineKindOptions<{
+   *   self: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').Guarded<T>}
    */
   const defineDurableExoClass = (
     kindHandle,
@@ -143,6 +174,7 @@ export const makeExoUtils = VatData => {
     methods,
     options,
   ) =>
+    // @ts-expect-error cast
     defineDurableKind(kindHandle, init, methods, {
       ...options,
       thisfulMethods: true,
@@ -150,16 +182,22 @@ export const makeExoUtils = VatData => {
     });
   harden(defineDurableExoClass);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
-   * @template {Record<string, Record<string | symbol, CallableFunction>>} T facets
+   * @template {InitState} I init state function
+   * @template {Record<string, Record<PropertyKey, CallableFunction>>} T facets
    * @param {DurableKindHandle} kindHandle
-   * @param {any} interfaceGuardKit
+   * @param {InterfaceGuardKit | undefined} interfaceGuardKit
    * @param {I} init
-   * @param {T & ThisType<{ facets: T, state: ReturnType<I>}> } facets
-   * @param {DefineKindOptions<{ facets: T, state: ReturnType<I>}>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     facets: import('@endo/exo').GuardedKit<T>;
+   *     state: StateResult<I>;
+   *   }>} facets
+   * @param {DefineKindOptions<{
+   *   facets: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').GuardedKit<T>}
    */
   const defineDurableExoClassKit = (
     kindHandle,
@@ -168,24 +206,31 @@ export const makeExoUtils = VatData => {
     facets,
     options,
   ) =>
+    // @ts-expect-error cast
     defineDurableKindMulti(kindHandle, init, facets, {
       ...options,
       thisfulMethods: true,
-      interfaceGuard: interfaceGuardKit,
+      interfaceGuardKit,
     });
   harden(defineDurableExoClassKit);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
-   * @template {Record<string | symbol, CallableFunction>} T methods
+   * @template {InitState} I init state function
+   * @template {Record<PropertyKey, CallableFunction>} T methods
    * @param {Baggage} baggage
    * @param {string} kindName
-   * @param {any} interfaceGuard
+   * @param {InterfaceGuard | undefined} interfaceGuard
    * @param {I} init
-   * @param {T & ThisType<{ self: T, state: ReturnType<I> }>} methods
-   * @param {DefineKindOptions<{ self: T, state: ReturnType<I> }>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     self: RemotableObject & T;
+   *     state: StateResult<I>;
+   *   }>} methods
+   * @param {DefineKindOptions<{
+   *   self: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').Guarded<T>}
    */
   const prepareExoClass = (
     baggage,
@@ -204,17 +249,23 @@ export const makeExoUtils = VatData => {
     );
   harden(prepareExoClass);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {(...args: any) => any} I init state function
-   * @template {Record<string, Record<string | symbol, CallableFunction>>} T facets
+   * @template {InitState} I init state function
+   * @template {Record<string, Record<PropertyKey, CallableFunction>>} T facets
    * @param {Baggage} baggage
    * @param {string} kindName
-   * @param {any} interfaceGuardKit
+   * @param {InterfaceGuardKit | undefined} interfaceGuardKit
    * @param {I} init
-   * @param {T & ThisType<{ facets: T, state: ReturnType<I> }> } facets
-   * @param {DefineKindOptions<{ facets: T, state: ReturnType<I> }>} [options]
-   * @returns {(...args: Parameters<I>) => (T & RemotableBrand<{}, T>)}
+   * @param {T &
+   *   ThisType<{
+   *     facets: import('@endo/exo').GuardedKit<T>;
+   *     state: StateResult<I>;
+   *   }>} facets
+   * @param {DefineKindOptions<{
+   *   facets: T;
+   *   state: StateResult<I>;
+   * }>} [options]
+   * @returns {(...args: Parameters<I>) => import('@endo/exo').GuardedKit<T>}
    */
   const prepareExoClassKit = (
     baggage,
@@ -233,15 +284,17 @@ export const makeExoUtils = VatData => {
     );
   harden(prepareExoClassKit);
 
-  // TODO interfaceGuard type https://github.com/Agoric/agoric-sdk/issues/6206
   /**
-   * @template {Record<string | symbol, CallableFunction>} M methods
+   * @template {Record<PropertyKey, CallableFunction>} M methods
    * @param {Baggage} baggage
    * @param {string} kindName
-   * @param {any} interfaceGuard
-   * @param {M} methods
+   * @param {InterfaceGuard | undefined} interfaceGuard
+   * @param {M &
+   *   ThisType<{
+   *     self: RemotableObject & M;
+   *   }>} methods
    * @param {DefineKindOptions<{ self: M }>} [options]
-   * @returns {M & RemotableBrand<{}, M>}
+   * @returns {import('@endo/exo').Guarded<M>}
    */
   const prepareExo = (
     baggage,
@@ -264,13 +317,13 @@ export const makeExoUtils = VatData => {
   harden(prepareExo);
 
   /**
-   * @template {Record<string | symbol, CallableFunction>} M methods
    * @deprecated Use prepareExo instead.
+   * @template {Record<PropertyKey, CallableFunction>} M methods
    * @param {Baggage} baggage
    * @param {string} kindName
    * @param {M} methods
    * @param {DefineKindOptions<{ self: M }>} [options]
-   * @returns {M & RemotableBrand<{}, M>}
+   * @returns {import('@endo/exo').Guarded<M>}
    */
   const prepareSingleton = (baggage, kindName, methods, options = undefined) =>
     prepareExo(baggage, kindName, undefined, methods, options);
@@ -284,8 +337,8 @@ export const makeExoUtils = VatData => {
     prepareExoClass,
     prepareExoClassKit,
     prepareExo,
-    prepareSingleton,
 
+    prepareSingleton,
     provideKindHandle,
     prepareKind,
     prepareKindMulti,

package/src/index.js

@@ -1,6 +1,6 @@
 // @jessie-check
 
-/// <reference types="ses"/>
+/// <reference types="ses" />
 export {
   M,
   makeScalarMapStore,
@@ -42,9 +42,15 @@ export {
   prepareSingleton,
 } from './exo-utils.js';
 
-/** @typedef {import('./types.js').Baggage} Baggage */
-/** @typedef {import('./types.js').DurableKindHandle} DurableKindHandle */
-/** @template T @typedef {import('./types.js').DefineKindOptions<T>} DefineKindOptions */
+// TODO re-export these
+/**
+ * @template T @typedef
+ *   {import('@agoric/swingset-liveslots').DefineKindOptions<T>}
+ *   DefineKindOptions
+ */
+// Copy this type because aliasing it by `import('@agoric/swingset-liveslots').Baggage`
+// causes this error in typedoc: Expected a symbol for node with kind Identifier
+/** @typedef {MapStore<string, any>} Baggage */
 
 // //////////////////////////// deprecated /////////////////////////////////////
 

package/src/index.test-d.ts

@@ -1,18 +1,22 @@
-/* eslint-disable no-use-before-define, import/no-extraneous-dependencies */
 import { expectType } from 'tsd';
+import type {
+  KindFacets,
+  DurableKindHandle,
+  KindFacet,
+  FunctionsPlusContext,
+} from '@agoric/swingset-liveslots';
+import type { VirtualObjectManager } from '@agoric/swingset-liveslots/src/virtualObjectManager.js';
 import {
   defineKind,
   defineKindMulti,
   makeKindHandle,
   defineDurableKind,
   partialAssign,
-} from '.';
-import {
-  KindFacets,
-  DurableKindHandle,
-  KindFacet,
-  FunctionsPlusContext,
-} from './types.js';
+  watchPromise,
+} from './index.js';
+
+// for use in assignments below
+const anyVal = null as any;
 
 /*
 export const makePaymentMaker = (allegedName: string, brand: unknown) => {
@@ -154,7 +158,32 @@ const someBehavior: FunctionsPlusContext<SomeContext, SomeFacet> = {
     return b > context.state.a;
   },
 };
-const someFacet: KindFacet<typeof someBehavior> = null as any;
+const someFacet: KindFacet<typeof someBehavior> = anyVal;
 // @ts-expect-error
 someFacet.gt();
 expectType<boolean>(someFacet.gt(1));
+
+const vom: VirtualObjectManager = anyVal;
+// @ts-expect-error
+vom.missingMethod;
+// @ts-expect-error Expected 0-4 arguments but got 5
+vom.defineDurableKind(anyVal, anyVal, anyVal, anyVal, 'extra');
+
+const p: Promise<bigint> = anyVal;
+watchPromise(
+  p,
+  {
+    onFulfilled(value, extra1, extra2) {
+      expectType<bigint>(value);
+      expectType<string>(extra1);
+      // @ts-expect-error str
+      expectType<number>(extra2);
+    },
+    onRejected(reason, extra1) {
+      expectType<unknown>(reason);
+      expectType<string>(extra1);
+    },
+  },
+  'extraString',
+  'alsoString',
+);

package/src/vat-data-bindings.js

@@ -1,31 +1,34 @@
 /* global globalThis */
 
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import { provideLazy } from '@agoric/store';
 
-/** @type {import('./types').VatData} */
+/** @import {Baggage, PickFacet, VatData} from '@agoric/swingset-liveslots' */
+
+/** @type {VatData} */
 let VatDataGlobal;
 if ('VatData' in globalThis) {
   globalThis.VatData || Fail`VatData defined in global as null or undefined`;
-  VatDataGlobal = globalThis.VatData;
+  // XXX types incompatibility
+  VatDataGlobal = /** @type {any} */ (globalThis.VatData);
 } else {
   // XXX this module has been known to get imported (transitively) in cases that
   // never use it so we make a version that will satisfy module resolution but
   // fail at runtime.
-  const unvailable = () => Fail`VatData unavailable`;
+  const unavailable = () => Fail`VatData unavailable`;
   VatDataGlobal = {
-    defineKind: unvailable,
-    defineKindMulti: unvailable,
-    defineDurableKind: unvailable,
-    defineDurableKindMulti: unvailable,
-    makeKindHandle: unvailable,
-    providePromiseWatcher: unvailable,
-    watchPromise: unvailable,
-    makeScalarBigMapStore: unvailable,
-    makeScalarBigWeakMapStore: unvailable,
-    makeScalarBigSetStore: unvailable,
-    makeScalarBigWeakSetStore: unvailable,
-    canBeDurable: unvailable,
+    defineKind: unavailable,
+    defineKindMulti: unavailable,
+    defineDurableKind: unavailable,
+    defineDurableKindMulti: unavailable,
+    makeKindHandle: unavailable,
+    providePromiseWatcher: unavailable,
+    watchPromise: unavailable,
+    makeScalarBigMapStore: unavailable,
+    makeScalarBigWeakMapStore: unavailable,
+    makeScalarBigSetStore: unavailable,
+    makeScalarBigWeakSetStore: unavailable,
+    canBeDurable: unavailable,
   };
 }
 
@@ -54,7 +57,8 @@ export const {
 } = VatDataGlobal;
 
 /**
- * When making a multi-facet kind, it's common to pick one facet to expose. E.g.,
+ * When making a multi-facet kind, it's common to pick one facet to expose.
+ * E.g.,
  *
  *     const makeFoo = (a, b, c, d) => makeFooBase(a, b, c, d).self;
  *
@@ -62,7 +66,7 @@ export const {
  *
  *     const makeFoo = pickFacet(makeFooBase, 'self');
  *
- * @type {import('./types').PickFacet}
+ * @type {PickFacet}
  */
 export const pickFacet =
   (maker, facetName) =>
@@ -83,67 +87,45 @@ export const partialAssign = (target, source) => {
 };
 harden(partialAssign);
 
-// XXX copied from @agoric/store types
-// UNTIL https://github.com/Agoric/agoric-sdk/issues/4560
-/**
- * @typedef {object} StoreOptions
- * Of the dimensions on which KeyedStores can differ, we only represent a few
- * of them as standard options. A given store maker should document which
- * options it supports, as well as its positions on dimensions for which it
- * does not support options.
- * @property {boolean} [longLived=true] Which way to optimize a weak store. True means
- * that we expect this weak store to outlive most of its keys, in which
- * case we internally may use a JavaScript `WeakMap`. Otherwise we internally
- * may use a JavaScript `Map`.
- * Defaults to true, so please mark short lived stores explicitly.
- * @property {boolean} [durable=false]  The contents of this store survive termination
- *   of its containing process, allowing for restart or upgrade but at the cost
- *   of forbidding storage of references to ephemeral data.  Defaults to false.
- * @property {boolean} [fakeDurable=false]  This store pretends to be a durable store
- *   but does not enforce that the things stored in it actually be themselves
- *   durable (whereas an actual durable store would forbid storage of such
- *   items).  This is in service of allowing incremental transition to use of
- *   durable stores, to enable normal operation and testing when some stuff
- *   intended to eventually be durable has not yet been made durable.  A store
- *   marked as fakeDurable will appear to operate normally but any attempt to
- *   upgrade its containing vat will fail with an error.
- * @property {import('./types').Pattern} [keyShape]
- * @property {import('./types').Pattern} [valueShape]
- */
+/** @import {StoreOptions} from '@agoric/store' */
+
 /**
- * Unlike `provideLazy`, `provide` should be called at most once
- * within any vat incarnation with a given `baggage`,`key` pair.
+ * Unlike `provideLazy`, `provide` should be called at most once within any vat
+ * incarnation with a given `baggage`,`key` pair.
+ *
+ * `provide` should only be used to populate baggage, where the total number of
+ * calls to `provide` must be low cardinality, since we keep the bookkeeping to
+ * detect collisions in normal language-heap memory. All the other
+ * baggage-oriented `provide*` and `prepare*` functions call `provide`, and so
+ * impose the same constraints. This is consistent with our expected durability
+ * patterns: What we store in baggage are
  *
- * `provide` should only to be used to populate baggage,
- * where the total number of calls to `provide` must be
- * low cardinality, since we keep the bookkeeping to detect collisions
- * in normal language-heap memory. All the other baggage-oriented
- * `provide*` and `prepare*` functions call `provide`,
- * and so impose the same constraints. This is consistent with
- * our expected durability patterns: What we store in baggage are
- *    * kindHandles, which are per kind, which must be low cardinality
- *    * data "variables" for reestablishing the lexical scope, especially
- *      of singletons
- *    * named non-baggage collections at the leaves of the baggage tree.
+ * - kindHandles, which are per kind, which must be low cardinality
+ * - data "variables" for reestablishing the lexical scope, especially of
+ *   singletons
+ * - named non-baggage collections at the leaves of the baggage tree.
  *
- * What is expected to be high cardinality are the instances of the kinds,
- * and the members of the non-bagggage collections.
+ * What is expected to be high cardinality are the instances of the kinds, and
+ * the members of the non-bagggage collections.
  *
- * TODO https://github.com/Agoric/agoric-sdk/pull/5875 :
- * Implement development-time instrumentation to detect when
- * `provide` violates the above prescription, and is called more
- * than once in the same vat incarnation with the same
- * baggage,key pair.
+ * TODO https://github.com/Agoric/agoric-sdk/pull/5875 : Implement
+ * development-time instrumentation to detect when `provide` violates the above
+ * prescription, and is called more than once in the same vat incarnation with
+ * the same baggage,key pair.
  */
 
 export const provide =
   // XXX cast because provideLazy is `any` due to broken type import
-  /** @type {<K, V>(baggage: import('./types.js').Baggage, key: K, makeValue: (key: K) => V) => V} */ (
-    provideLazy
-  );
+  /**
+   * @type {<K, V>(
+   *   baggage: Baggage,
+   *   key: K,
+   *   makeValue: (key: K) => V,
+   * ) => V}
+   */ (provideLazy);
 
 // TODO: Find a good home for this function used by @agoric/vat-data and testing code
-/** @param {import('@agoric/vat-data/src/types').VatData} VatData */
+/** @param {VatData} VatData */
 export const makeStoreUtils = VatData => {
   const {
     // eslint-disable-next-line no-shadow -- these literally do shadow the globals
@@ -157,7 +139,7 @@ export const makeStoreUtils = VatData => {
   } = VatData;
 
   /**
-   * @param {import('./types').Baggage} baggage
+   * @param {Baggage} baggage
    * @param {string} name
    * @param {Omit<StoreOptions, 'durable'>} options
    */
@@ -168,7 +150,7 @@ export const makeStoreUtils = VatData => {
   harden(provideDurableMapStore);
 
   /**
-   * @param {import('./types').Baggage} baggage
+   * @param {Baggage} baggage
    * @param {string} name
    * @param {Omit<StoreOptions, 'durable'>} options
    */
@@ -179,7 +161,7 @@ export const makeStoreUtils = VatData => {
   harden(provideDurableWeakMapStore);
 
   /**
-   * @param {import('./types').Baggage} baggage
+   * @param {Baggage} baggage
    * @param {string} name
    * @param {Omit<StoreOptions, 'durable'>} options
    */
@@ -190,7 +172,7 @@ export const makeStoreUtils = VatData => {
   harden(provideDurableSetStore);
 
   /**
-   * @param {import('./types').Baggage} baggage
+   * @param {Baggage} baggage
    * @param {string} name
    * @param {Omit<StoreOptions, 'durable'>} options
    */

package/test/absent.test.js

@@ -1,9 +1,13 @@
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import test from 'ava';
+
 /* global globalThis */
+// @ts-expect-error VatData not optional
 delete globalThis.VatData;
 
 /** @see present.test.js */
 test('methods available that throw', async t => {
   const { defineKind } = await import('../src/index.js');
-  t.throws(defineKind, { message: /VatData unavailable/ });
+  t.throws(() => defineKind('someTag', () => {}, {}), {
+    message: /VatData unavailable/,
+  });
 });

package/test/amplify-virtual-class-kits.test.js

@@ -0,0 +1,90 @@
+// modeled on test-amplify-heap-class-kits.js
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
+import { M } from '@endo/patterns';
+import {
+  defineVirtualExoClass,
+  defineVirtualExoClassKit,
+} from '../src/exo-utils.js';
+
+const UpCounterI = M.interface('UpCounter', {
+  incr: M.call().optional(M.gte(0)).returns(M.number()),
+});
+
+const DownCounterI = M.interface('DownCounter', {
+  decr: M.call().optional(M.gte(0)).returns(M.number()),
+});
+
+test('test amplify defineVirtualExoClass fails', t => {
+  t.throws(
+    () =>
+      defineVirtualExoClass(
+        'UpCounter',
+        UpCounterI,
+        /** @param {number} [x] */
+        (x = 0) => ({ x }),
+        {
+          incr(y = 1) {
+            const { state } = this;
+            state.x += y;
+            return state.x;
+          },
+        },
+        {
+          receiveAmplifier(_) {},
+        },
+      ),
+    {
+      message:
+        'Only facets of an exo class kit can be amplified, not "UpCounter"',
+    },
+  );
+});
+
+test('test amplify defineVirtualExoClassKit', t => {
+  /** @type {import('@endo/exo').Amplify} */
+  let amp;
+  const makeCounterKit = defineVirtualExoClassKit(
+    'Counter',
+    { up: UpCounterI, down: DownCounterI },
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      up: {
+        incr(y = 1) {
+          const { state } = this;
+          state.x += y;
+          return state.x;
+        },
+      },
+      down: {
+        decr(y = 1) {
+          const { state } = this;
+          state.x -= y;
+          return state.x;
+        },
+      },
+    },
+    {
+      receiveAmplifier(a) {
+        amp = a;
+      },
+    },
+  );
+  // @ts-expect-error TS thinks it is used before assigned, which is a hazard
+  // TS is correct to bring to our attention, since there is not enough static
+  // into to infer otherwise.
+  assert(amp !== undefined);
+
+  const counterKit = makeCounterKit(3);
+  const { up: upCounter, down: downCounter } = counterKit;
+  t.is(upCounter.incr(5), 8);
+  t.is(downCounter.decr(), 7);
+
+  t.throws(() => amp(harden({})), {
+    message: 'Must be a facet of "Counter": {}',
+  });
+  t.deepEqual(amp(upCounter), counterKit);
+  t.deepEqual(amp(downCounter), counterKit);
+});

package/test/{test-durable-classes.js → durable-classes.test.js}

@@ -1,6 +1,8 @@
 // Modeled on test-heap-classes.js
 
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
 import { M } from '@agoric/store';
 import {
   makeKindHandle,
@@ -31,7 +33,7 @@ test('test defineDurableExoClass', t => {
   const makeUpCounter = defineDurableExoClass(
     upCounterKind,
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       incr(y = 1) {
@@ -67,7 +69,7 @@ test('test defineDurableExoClassKit', t => {
   const makeCounterKit = defineDurableExoClassKit(
     counterKindHandle,
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {
@@ -122,7 +124,7 @@ test('finish option', t => {
     UpCounterI,
     /**
      * @param {string} name
-     * @param {number} x
+     * @param {number} [x]
      */
     (name, x = 0) => ({ name, x }),
     {

package/test/is-instance-virtual-class-kits.test.js

@@ -0,0 +1,110 @@
+// modeled on test-is-instance-heap-class-kits.js
+
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
+import { M } from '@endo/patterns';
+import {
+  defineVirtualExoClass,
+  defineVirtualExoClassKit,
+} from '../src/exo-utils.js';
+
+const UpCounterI = M.interface('UpCounter', {
+  incr: M.call().optional(M.gte(0)).returns(M.number()),
+});
+
+const DownCounterI = M.interface('DownCounter', {
+  decr: M.call().optional(M.gte(0)).returns(M.number()),
+});
+
+test('test isInstance defineVirtualExoClass', t => {
+  /** @type {import('@endo/exo').IsInstance} */
+  let isInstance;
+  const makeUpCounter = defineVirtualExoClass(
+    'UpCounter',
+    UpCounterI,
+    /** @param {number} x */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+    },
+    {
+      receiveInstanceTester(i) {
+        isInstance = i;
+      },
+    },
+  );
+  // @ts-expect-error TS thinks it is used before assigned, which is a hazard
+  // TS is correct to bring to our attention, since there is not enough static
+  // into to infer otherwise.
+  assert(isInstance !== undefined);
+
+  t.is(isInstance(harden({})), false);
+  t.throws(() => isInstance(harden({}), 'up'), {
+    message:
+      'facetName can only be used with an exo class kit: "UpCounter" has no facet "up"',
+  });
+
+  const upCounter = makeUpCounter(3);
+
+  t.is(isInstance(upCounter), true);
+  t.throws(() => isInstance(upCounter, 'up'), {
+    message:
+      'facetName can only be used with an exo class kit: "UpCounter" has no facet "up"',
+  });
+});
+
+test('test isInstance defineVirtualExoClassKit', t => {
+  /** @type {import('@endo/exo').IsInstance} */
+  let isInstance;
+  const makeCounterKit = defineVirtualExoClassKit(
+    'Counter',
+    { up: UpCounterI, down: DownCounterI },
+    /** @param {number} x */
+    (x = 0) => ({ x }),
+    {
+      up: {
+        incr(y = 1) {
+          const { state } = this;
+          state.x += y;
+          return state.x;
+        },
+      },
+      down: {
+        decr(y = 1) {
+          const { state } = this;
+          state.x -= y;
+          return state.x;
+        },
+      },
+    },
+    {
+      receiveInstanceTester(i) {
+        isInstance = i;
+      },
+    },
+  );
+  // @ts-expect-error TS thinks it is used before assigned, which is a hazard
+  // TS is correct to bring to our attention, since there is not enough static
+  // into to infer otherwise.
+  assert(isInstance !== undefined);
+
+  t.is(isInstance(harden({})), false);
+  t.is(isInstance(harden({}), 'up'), false);
+  t.throws(() => isInstance(harden({}), 'foo'), {
+    message: 'exo class kit "Counter" has no facet named "foo"',
+  });
+
+  const { up: upCounter } = makeCounterKit(3);
+
+  t.is(isInstance(upCounter), true);
+  t.is(isInstance(upCounter, 'up'), true);
+  t.is(isInstance(upCounter, 'down'), false);
+  t.throws(() => isInstance(upCounter, 'foo'), {
+    message: 'exo class kit "Counter" has no facet named "foo"',
+  });
+});

package/test/prepare-test-env-ava.js

@@ -0,0 +1,7 @@
+import './prepare-test-env.js';
+
+import { wrapTest } from '@endo/ses-ava';
+import rawTest from 'ava';
+
+/** @type {typeof rawTest} */
+export const test = wrapTest(rawTest);

package/test/prepare-test-env.js

@@ -0,0 +1 @@
+import '@agoric/swingset-liveslots/tools/prepare-test-env.js';

package/test/{test-prepare.js → prepare.test.js}

@@ -1,6 +1,8 @@
 // Modeled on test-heap-classes.js
 
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
 import { M } from '@agoric/store';
 import {
   prepareExoClass,
@@ -30,7 +32,7 @@ test('test prepareExoClass', t => {
     baggage,
     'UpCounter',
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       incr(y = 1) {
@@ -64,7 +66,7 @@ test('test prepareExoClassKit', t => {
     baggage,
     'Counter',
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {

package/test/present.test.js

@@ -1,7 +1,12 @@
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import test from 'ava';
+
+const mockDefineKind = /** @type {any} */ (harden({}));
+
+/* global globalThis */
+// @ts-expect-error missing fields
+globalThis.VatData ||= { defineKind: mockDefineKind };
 
 test('methods available', async t => {
   const { defineKind } = await import('../src/index.js');
-  defineKind('test', () => {}, {});
-  t.pass();
+  t.is(defineKind, mockDefineKind);
 });

package/test/{test-scalar-only-keys.js → scalar-only-keys.test.js}

@@ -1,14 +1,14 @@
 // From https://github.com/Agoric/agoric-sdk/pull/6903#discussion_r1098067133
 
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import { test } from './prepare-test-env-ava.js';
 
+// eslint-disable-next-line import/order
 import { M, makeScalarMapStore } from '@agoric/store';
-
 import { makeScalarBigMapStore } from '../src/vat-data-bindings.js';
 
 test('scalar maps should reject non-scalar keys', t => {
   const bigMap = makeScalarMapStore('dummy', { keyShape: M.key() });
-  t.throws(() => bigMap.init(harden({ label: 'not a scalar' })), {
+  t.throws(() => bigMap.init(harden({ label: 'not a scalar' }), 'val'), {
     message:
       /A "copyRecord" cannot be a scalar key: \{"label":"not a scalar"\}/,
   });
@@ -16,7 +16,7 @@ test('scalar maps should reject non-scalar keys', t => {
 
 test('scalar big maps should reject non-scalar keys', t => {
   const bigMap = makeScalarBigMapStore('dummy', { keyShape: M.key() });
-  t.throws(() => bigMap.init(harden({ label: 'not a scalar' })), {
+  t.throws(() => bigMap.init(harden({ label: 'not a scalar' }), null), {
     message:
       /A "copyRecord" cannot be a scalar key: \{"label":"not a scalar"\}/,
   });

package/test/{test-virtual-classes.js → virtual-classes.test.js}

@@ -1,6 +1,8 @@
 // Modeled on test-heap-classes.js
 
-import { test } from '@agoric/swingset-vat/tools/prepare-test-env-ava.js';
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
 import { M } from '@agoric/store';
 import {
   defineVirtualExoClass,
@@ -25,7 +27,7 @@ test('test defineVirtualExoClass', t => {
   const makeUpCounter = defineVirtualExoClass(
     'UpCounter',
     UpCounterI,
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       incr(y = 1) {
@@ -56,7 +58,7 @@ test('test defineVirtualExoClassKit', t => {
   const makeCounterKit = defineVirtualExoClassKit(
     'Counter',
     { up: UpCounterI, down: DownCounterI },
-    /** @param {number} x */
+    /** @param {number} [x] */
     (x = 0) => ({ x }),
     {
       up: {

package/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": false, // for compat with peer packages using ambient types
+    // XXX to resolve the swingset-liveslots types
+    // "strict": true, // disabled for compat with >0 module depth
+    // "noImplicitAny": false, // for compat with peer packages using ambient types
   },
   "include": [
     "src/**/*.js",

package/typedoc.json

@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+    ]
+}

package/src/types.d.ts

@@ -1,203 +0,0 @@
-/**
- * @file Types for vat-data
- *
- * Facet is a single object with methods.
- * Behavior is a description when defining a kind of what facets it will have.
- * For the non-multi defineKind, there is just one facet so it doesn't have a key.
- */
-import type {
-  InterfaceGuard,
-  MapStore,
-  Pattern,
-  SetStore,
-  StoreOptions,
-  WeakMapStore,
-  WeakSetStore,
-} from '@agoric/store';
-
-export type { Pattern };
-
-export type Baggage = MapStore<string, unknown>;
-
-type Tail<T extends any[]> = T extends [head: any, ...rest: infer Rest]
-  ? Rest
-  : [];
-
-type MinusContext<
-  F extends (context, ...rest: any[]) => any,
-  P extends any[] = Parameters<F>, // P: are the parameters of F
-  R = ReturnType<F>, // R: the return type of F
-> = (...args: Tail<P>) => R;
-
-export type KindFacet<O> = { [K in keyof O]: MinusContext<O[K]> };
-
-export type KindFacets<B> = {
-  [FacetKey in keyof B]: KindFacet<B[FacetKey]>;
-};
-
-export type KindContext<S, F> = { state: S; self: KindFacet<F> };
-export type MultiKindContext<S, B> = { state: S; facets: KindFacets<B> };
-
-export type PlusContext<C, M> = (c: C, ...args: Parameters<M>) => ReturnType<M>;
-export type FunctionsPlusContext<C, O> = {
-  [K in keyof O]: PlusContext<C, O[K]>;
-};
-
-declare class DurableKindHandleClass {
-  private descriptionTag: string;
-}
-export type DurableKindHandle = DurableKindHandleClass;
-
-/**
- * Grab bag of options that can be provided to `defineDurableKind` and its
- * siblings. Not all options are meaningful in all contexts. See the
- * doc-comments on each option.
- */
-export type DefineKindOptions<C> = {
-  /**
-   * If provided, the `finish` function will be called after the instance is
-   * made and internally registered, but before it is returned. The finish
-   * function is to do any post-intantiation initialization that should be
-   * done before exposing the object to its clients.
-   */
-  finish?: (context: C) => void;
-
-  /**
-   * Meaningful to `makeScalarBigMapStore` and its siblings. These maker
-   * fuctions will make either virtual or durable stores, depending on
-   * this flag. Defaults to off, making virtual but not durable collections.
-   *
-   * Generally, durable collections are provided with `provideDurableMapStore`
-   * and its sibling, which use this flag internally. If you do not make
-   * durable collections by other means, you can consider this as
-   * intended for internal use only.
-   */
-  durable?: boolean;
-
-  /**
-   * If provided, it describes the shape of all state records of instances
-   * of this kind.
-   */
-  stateShape?: { [name: string]: Pattern };
-
-  /**
-   * Intended for internal use only.
-   * Should the raw methods receive their `context` argument as their first
-   * argument or as their `this` binding? For `defineDurableKind` and its
-   * siblings (including `prepareSingleton`), this defaults to off, meaning that
-   * their behavior methods receive `context` as their first argument.
-   * `prepareExoClass` and its siblings (including `prepareExo`) use
-   * this flag internally to indicate that their methods receive `context`
-   * as their `this` binding.
-   */
-  thisfulMethods?: boolean;
-
-  /**
-   * Intended for internal use only.
-   * If an `interfaceGuard` is provided, then the raw methods passed alongside
-   * it are wrapped by a function that first checks that this method's guard
-   * pattern is satisfied before calling the raw method.
-   *
-   * In `defineDurableKind` and its siblings, this defaults to off.
-   * `prepareExoClass` use this internally to protect their raw class methods
-   * using the provided interface.
-   */
-  interfaceGuard?: InterfaceGuard<unknown>;
-};
-
-export type VatData = {
-  // virtual kinds
-  /** @deprecated Use defineVirtualExoClass instead */
-  defineKind: <P, S, F>(
-    tag: string,
-    init: (...args: P) => S,
-    facet: F,
-    options?: DefineKindOptions<KindContext<S, F>>,
-  ) => (...args: P) => KindFacet<F>;
-
-  /** @deprecated Use defineVirtualExoClassKit instead */
-  defineKindMulti: <P, S, B>(
-    tag: string,
-    init: (...args: P) => S,
-    behavior: B,
-    options?: DefineKindOptions<MultiKindContext<S, B>>,
-  ) => (...args: P) => KindFacets<B>;
-
-  // durable kinds
-  makeKindHandle: (descriptionTag: string) => DurableKindHandle;
-
-  /** @deprecated Use defineDurableExoClass instead */
-  defineDurableKind: <P, S, F>(
-    kindHandle: DurableKindHandle,
-    init: (...args: P) => S,
-    facet: F,
-    options?: DefineKindOptions<KindContext<S, F>>,
-  ) => (...args: P) => KindFacet<F>;
-
-  /** @deprecated Use defineDurableExoClassKit instead */
-  defineDurableKindMulti: <P, S, B>(
-    kindHandle: DurableKindHandle,
-    init: (...args: P) => S,
-    behavior: B,
-    options?: DefineKindOptions<MultiKindContext<S, B>>,
-  ) => (...args: P) => KindFacets<B>;
-
-  providePromiseWatcher: unknown;
-  watchPromise: unknown;
-
-  makeScalarBigMapStore: <K, V>(
-    label: string,
-    options?: StoreOptions,
-  ) => MapStore<K, V>;
-  makeScalarBigWeakMapStore: <K, V>(
-    label: string,
-    options?: StoreOptions,
-  ) => WeakMapStore<K, V>;
-
-  makeScalarBigSetStore: <K>(
-    label: string,
-    options?: StoreOptions,
-  ) => SetStore<K>;
-  makeScalarBigWeakSetStore: <K>(
-    label: string,
-    options?: StoreOptions,
-  ) => WeakSetStore<K>;
-  canBeDurable: (specimen: unknown) => boolean;
-};
-
-// The JSDoc is repeated here and at the function definition so it appears
-// in IDEs where it's used, regardless of type resolution.
-export interface PickFacet {
-  /**
-   * When making a multi-facet kind, it's common to pick one facet to
-   * expose. E.g.,
-   *
-   *     const makeFoo = (a, b, c, d) => makeFooBase(a, b, c, d).self;
-   *
-   * This helper reduces the duplication:
-   *
-   *     const makeFoo = pickFacet(makeFooBase, 'self');
-   */
-  <M extends (...args: any[]) => any, F extends keyof ReturnType<M>>(
-    maker: M,
-    facetName: F,
-  ): (...args: Parameters<M>) => ReturnType<M>[F];
-}
-
-/** @deprecated Use prepareExoClass instead */
-export type PrepareKind = <P, S, F>(
-  baggage: Baggage,
-  tag: string,
-  init: (...args: P) => S,
-  facet: F,
-  options?: DefineKindOptions<KindContext<S, F>>,
-) => (...args: P) => KindFacet<F>;
-
-/** @deprecated Use prepareExoClassKit instead */
-export type PrepareKindMulti = <P, S, B>(
-  baggage: Baggage,
-  tag: string,
-  init: (...args: P) => S,
-  behavior: B,
-  options?: DefineKindOptions<MultiKindContext<S, B>>,
-) => (...args: P) => KindFacets<B>;