@agoric/swingset-liveslots 0.10.3-dev-ecf2d8e.0 → 0.10.3-other-dev-70beeb7.0

package/src/vatDataTypes.d.ts

@@ -1,230 +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, Pattern } from '@endo/patterns';
-import type {
-  MapStore,
-  SetStore,
-  StoreOptions,
-  WeakMapStore,
-  WeakSetStore,
-} from '@agoric/store';
-
-// TODO should be moved into @endo/patterns and eventually imported here
-// instead of this local definition.
-export type InterfaceGuardKit = Record<string, InterfaceGuard>;
-
-export type { MapStore, Pattern };
-
-// This needs `any` values.  If they were `unknown`, code that uses Baggage
-// would need explicit runtime checks or casts for every fetch, which is
-// onerous.
-export type Baggage = MapStore<string, any>;
-
-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.
-   * Only applicable if this is a class kind. A class kit kind should use
-   * `interfaceGuardKit` instead.
-   *
-   * 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 `undefined`.
-   * Exo classes use this internally to protect their raw class methods
-   * using the provided interface.
-   * In absence, an exo is protected anyway, while a bare kind is
-   * not (detected by `!thisfulMethods`),
-   */
-  interfaceGuard?: InterfaceGuard;
-
-  /**
-   * Intended for internal use only.
-   * Only applicable if this is a class kit kind. A class kind should use
-   * `interfaceGuard` instead.
-   *
-   * If an `interfaceGuardKit` is provided, then each member of the
-   * interfaceGuardKit is used to guard the corresponding facet of the
-   * class kit.
-   *
-   * In `defineDurableKindMulti` and its siblings, this defaults to `undefined`.
-   * Exo class kits use this internally to protect their facets.
-   * In absence, an exo is protected anyway, while a bare kind is
-   * not (detected by `!thisfulMethods`),
-   */
-  interfaceGuardKit?: InterfaceGuardKit;
-};
-
-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>;

package/src/vatDataTypes.js

@@ -1,2 +0,0 @@
-// Empty JS file to correspond with vatDataTypes.d.ts
-export {};

package/tools/fakeCollectionManager.js

@@ -1,44 +0,0 @@
-import { makeCollectionManager } from '../src/collectionManager.js';
-
-export function makeFakeCollectionManager(vrm, fakeStuff, _options = {}) {
-  const {
-    makeScalarBigMapStore,
-    makeScalarBigWeakMapStore,
-    makeScalarBigSetStore,
-    makeScalarBigWeakSetStore,
-    provideBaggage,
-    initializeStoreKindInfo,
-    flushSchemaCache,
-  } = makeCollectionManager(
-    fakeStuff.syscall,
-    vrm,
-    fakeStuff.allocateExportID,
-    fakeStuff.allocateCollectionID,
-    fakeStuff.convertValToSlot,
-    fakeStuff.convertSlotToVal,
-    fakeStuff.registerEntry,
-    fakeStuff.marshal.serialize,
-    fakeStuff.marshal.unserialize,
-    fakeStuff.assertAcceptableSyscallCapdataSize,
-  );
-  initializeStoreKindInfo();
-
-  const normalCM = {
-    makeScalarBigMapStore,
-    makeScalarBigWeakMapStore,
-    makeScalarBigSetStore,
-    makeScalarBigWeakSetStore,
-    provideBaggage,
-    flushSchemaCache,
-  };
-
-  const debugTools = {
-    getValForSlot: fakeStuff.getValForSlot,
-    setValForSlot: fakeStuff.setValForSlot,
-    registerEntry: fakeStuff.registerEntry,
-    deleteEntry: fakeStuff.deleteEntry,
-    dumpStore: fakeStuff.dumpStore,
-  };
-
-  return harden({ ...normalCM, ...debugTools });
-}

package/tools/fakeVirtualObjectManager.js

@@ -1,60 +0,0 @@
-import { makeVirtualObjectManager } from '../src/virtualObjectManager.js';
-
-// Note: `fakeVirtualObjectManager` is something of a misnomer here.  The
-// virtual object manager being used to implement this realized by the actual
-// virtual object manager code.  What's being faked is everything else the
-// virtual object manager is embedded in, i.e., the kernel and the rest of
-// liveslots.  In particular, this module can be (and is, and is intended to be)
-// used for unit tests for the virtual object manager itself.  What you get back
-// from `makeFakeVirtualObjectManager` can't be used to program as if you were
-// running in a vat because the rest of the vat environment is not present, but
-// it *will* execute virtual object manager operations in the same way that the
-// real one will because underneath it *is* the real one.
-
-export function makeFakeVirtualObjectManager(vrm, fakeStuff) {
-  const {
-    initializeKindHandleKind,
-    defineKind,
-    defineKindMulti,
-    defineDurableKind,
-    defineDurableKindMulti,
-    makeKindHandle,
-    VirtualObjectAwareWeakMap,
-    VirtualObjectAwareWeakSet,
-    flushStateCache,
-    canBeDurable,
-  } = makeVirtualObjectManager(
-    fakeStuff.syscall,
-    vrm,
-    fakeStuff.allocateExportID,
-    fakeStuff.getSlotForVal,
-    fakeStuff.requiredValForSlot,
-    fakeStuff.registerEntry,
-    fakeStuff.marshal.serialize,
-    fakeStuff.marshal.unserialize,
-    fakeStuff.assertAcceptableSyscallCapdataSize,
-  );
-
-  const normalVOM = {
-    initializeKindHandleKind,
-    defineKind,
-    defineKindMulti,
-    defineDurableKind,
-    defineDurableKindMulti,
-    makeKindHandle,
-    canBeDurable,
-    VirtualObjectAwareWeakMap,
-    VirtualObjectAwareWeakSet,
-  };
-
-  const debugTools = {
-    getValForSlot: fakeStuff.getValForSlot,
-    setValForSlot: fakeStuff.setValForSlot,
-    registerEntry: fakeStuff.registerEntry,
-    deleteEntry: fakeStuff.deleteEntry,
-    flushStateCache,
-    dumpStore: fakeStuff.dumpStore,
-  };
-
-  return harden({ ...normalVOM, ...debugTools });
-}

package/tools/fakeVirtualSupport.js

@@ -1,375 +0,0 @@
-/* global globalThis */
-/* eslint-disable max-classes-per-file */
-import { makeMarshal } from '@endo/marshal';
-import { assert } from '@agoric/assert';
-import { parseVatSlot } from '../src/parseVatSlots.js';
-
-import { makeVirtualReferenceManager } from '../src/virtualReferences.js';
-import { makeWatchedPromiseManager } from '../src/watchedPromises.js';
-import { makeFakeVirtualObjectManager } from './fakeVirtualObjectManager.js';
-import { makeFakeCollectionManager } from './fakeCollectionManager.js';
-
-const { Fail } = assert;
-
-const {
-  WeakRef: RealWeakRef,
-  WeakMap: RealWeakMap,
-  WeakSet: RealWeakSet,
-} = globalThis;
-
-class FakeFinalizationRegistry {
-  // eslint-disable-next-line no-useless-constructor, no-empty-function
-  constructor() {}
-
-  // eslint-disable-next-line class-methods-use-this
-  register(_target, _heldValue, _unregisterToken) {}
-
-  // eslint-disable-next-line class-methods-use-this
-  unregister(_unregisterToken) {}
-}
-
-class FakeWeakRef {
-  constructor(target) {
-    this.target = target;
-  }
-
-  deref() {
-    return this.target; // strong ref
-  }
-}
-
-export function makeFakeLiveSlotsStuff(options = {}) {
-  let vrm;
-  function setVrm(vrmToUse) {
-    assert(!vrm, 'vrm already configured');
-    vrm = vrmToUse;
-  }
-
-  const {
-    fakeStore = new Map(),
-    weak = false,
-    log,
-    FinalizationRegistry = FakeFinalizationRegistry,
-    WeakRef = FakeWeakRef, // VRM uses this
-    WeakMap = RealWeakMap,
-    WeakSet = RealWeakSet,
-    addToPossiblyDeadSet = () => {},
-    addToPossiblyRetiredSet = () => {},
-  } = options;
-
-  let sortedKeys;
-  let priorKeyReturned;
-  let priorKeyIndex;
-
-  function s(v) {
-    switch (typeof v) {
-      case 'symbol':
-        return v.toString();
-      case 'bigint':
-        return `${v}n`;
-      default:
-        return `${v}`;
-    }
-  }
-
-  function ensureSorted() {
-    if (!sortedKeys) {
-      sortedKeys = [];
-      for (const key of fakeStore.keys()) {
-        sortedKeys.push(key);
-      }
-      sortedKeys.sort((k1, k2) => k1.localeCompare(k2));
-    }
-  }
-
-  function clearGetNextKeyCache() {
-    priorKeyReturned = undefined;
-    priorKeyIndex = -1;
-  }
-  clearGetNextKeyCache();
-
-  function clearSorted() {
-    sortedKeys = undefined;
-    clearGetNextKeyCache();
-  }
-
-  function dumpStore() {
-    ensureSorted();
-    const result = [];
-    for (const key of sortedKeys) {
-      result.push([key, fakeStore.get(key)]);
-    }
-    return result;
-  }
-
-  const syscall = {
-    vatstoreGet(key) {
-      const result = fakeStore.get(key);
-      if (log) {
-        log.push(`get ${s(key)} => ${s(result)}`);
-      }
-      return result;
-    },
-    vatstoreGetNextKey(priorKey) {
-      assert.typeof(priorKey, 'string');
-      ensureSorted();
-      // TODO: binary search for priorKey (maybe missing), then get
-      // the one after that. For now we go simple and slow. But cache
-      // a starting point, because the main use case is a full
-      // iteration. OTOH, the main use case also deletes everything,
-      // which will clobber the cache on each deletion, so it might
-      // not help.
-      const start = priorKeyReturned === priorKey ? priorKeyIndex : 0;
-      let result;
-      for (let i = start; i < sortedKeys.length; i += 1) {
-        const key = sortedKeys[i];
-        if (key > priorKey) {
-          priorKeyReturned = key;
-          priorKeyIndex = i;
-          result = key;
-          break;
-        }
-      }
-      if (!result) {
-        // reached end without finding the key, so clear our cache
-        clearGetNextKeyCache();
-      }
-      if (log) {
-        log.push(`getNextKey ${s(priorKey)} => ${s(result)}`);
-      }
-      return result;
-    },
-    vatstoreSet(key, value) {
-      if (log) {
-        log.push(`set ${s(key)} ${s(value)}`);
-      }
-      if (!fakeStore.has(key)) {
-        clearSorted();
-      }
-      fakeStore.set(key, value);
-    },
-    vatstoreDelete(key) {
-      if (log) {
-        log.push(`delete ${s(key)}`);
-      }
-      if (fakeStore.has(key)) {
-        clearSorted();
-      }
-      fakeStore.delete(key);
-    },
-  };
-
-  function allocateExportID() {
-    return vrm.allocateNextID('exportID');
-  }
-
-  function allocateCollectionID() {
-    return vrm.allocateNextID('collectionID');
-  }
-
-  // note: The real liveslots slotToVal() maps slots (vrefs) to a WeakRef,
-  // and the WeakRef may or may not contain the target value. Use
-  // options={weak:true} to match that behavior, or the default weak:false to
-  // keep strong references.
-  const valToSlot = new WeakMap();
-  const slotToVal = new Map();
-
-  function getSlotForVal(val) {
-    return valToSlot.get(val);
-  }
-
-  function getValForSlot(slot) {
-    const d = slotToVal.get(slot);
-    return d && (weak ? d.deref() : d);
-  }
-
-  function requiredValForSlot(slot) {
-    const val = getValForSlot(slot);
-    assert(val, `${slot} must have a value`);
-    return val;
-  }
-
-  function setValForSlot(slot, val) {
-    slotToVal.set(slot, weak ? new RealWeakRef(val) : val);
-  }
-
-  function convertValToSlot(val) {
-    if (!valToSlot.has(val)) {
-      const slot = `o+${allocateExportID()}`;
-      valToSlot.set(val, slot);
-      setValForSlot(slot, val);
-    }
-    return valToSlot.get(val);
-  }
-
-  function convertSlotToVal(slot) {
-    const { type, id, virtual, durable, facet, baseRef } = parseVatSlot(slot);
-    assert.equal(type, 'object');
-    let val = getValForSlot(baseRef);
-    if (val) {
-      if (virtual || durable) {
-        if (facet !== undefined) {
-          return vrm.getFacet(id, val, facet);
-        }
-      }
-      return val;
-    }
-    let result;
-    if (virtual || durable) {
-      if (vrm) {
-        val = vrm.reanimate(slot);
-        if (facet !== undefined) {
-          result = vrm.getFacet(id, val, facet);
-        }
-      } else {
-        assert.fail('fake liveSlots stuff configured without vrm');
-      }
-    }
-    // eslint-disable-next-line no-use-before-define
-    registerEntry(baseRef, val, facet !== undefined);
-    if (!result) {
-      result = val;
-    }
-    return result;
-  }
-
-  const marshal = makeMarshal(convertValToSlot, convertSlotToVal, {
-    serializeBodyFormat: 'smallcaps',
-  });
-
-  function registerEntry(baseRef, val, valIsCohort) {
-    const { facet } = parseVatSlot(baseRef);
-    !facet ||
-      Fail`registerEntry(${baseRef} should not receive individual facets`;
-    setValForSlot(baseRef, val);
-    if (valIsCohort) {
-      const { id } = parseVatSlot(baseRef);
-      for (const [index, name] of vrm.getFacetNames(id).entries()) {
-        valToSlot.set(val[name], `${baseRef}:${index}`);
-      }
-    } else {
-      valToSlot.set(val, baseRef);
-    }
-  }
-
-  function deleteEntry(slot, val) {
-    if (!val) {
-      val = getValForSlot(slot);
-    }
-    slotToVal.delete(slot);
-    valToSlot.delete(val);
-  }
-
-  function assertAcceptableSyscallCapdataSize(_capdatas) {}
-
-  const maybeExportPromise = _vref => false;
-
-  return {
-    syscall,
-    allocateExportID,
-    allocateCollectionID,
-    getSlotForVal,
-    requiredValForSlot,
-    getValForSlot,
-    setValForSlot,
-    registerEntry,
-    valToSlot,
-    slotToVal,
-    convertValToSlot,
-    convertSlotToVal,
-    marshal,
-    deleteEntry,
-    FinalizationRegistry,
-    WeakRef,
-    WeakMap,
-    WeakSet,
-    addToPossiblyDeadSet,
-    addToPossiblyRetiredSet,
-    dumpStore,
-    setVrm,
-    assertAcceptableSyscallCapdataSize,
-    maybeExportPromise,
-  };
-}
-
-export function makeFakeVirtualReferenceManager(
-  fakeStuff,
-  relaxDurabilityRules = true,
-) {
-  return makeVirtualReferenceManager(
-    fakeStuff.syscall,
-    fakeStuff.getSlotForVal,
-    fakeStuff.getValForSlot,
-    fakeStuff.FinalizationRegistry,
-    fakeStuff.WeakRef,
-    fakeStuff.addToPossiblyDeadSet,
-    fakeStuff.addToPossiblyRetiredSet,
-    relaxDurabilityRules,
-  );
-}
-
-export function makeFakeWatchedPromiseManager(
-  vrm,
-  vom,
-  collectionManager,
-  fakeStuff,
-) {
-  return makeWatchedPromiseManager({
-    syscall: fakeStuff.syscall,
-    vrm,
-    vom,
-    collectionManager,
-    convertValToSlot: fakeStuff.convertValToSlot,
-    convertSlotToVal: fakeStuff.convertSlotToVal,
-    maybeExportPromise: fakeStuff.maybeExportPromise,
-  });
-}
-/**
- * Configure virtual stuff with relaxed durability rules and fake liveslots
- *
- * @param {object} [options]
- * @param {number} [options.cacheSize]
- * @param {boolean} [options.relaxDurabilityRules]
- * @param {Map<any, any>} [options.fakeStore]
- * @param {WeakMapConstructor} [options.WeakMap]
- * @param {WeakSetConstructor} [options.WeakSet]
- * @param {boolean} [options.weak]
- */
-export function makeFakeVirtualStuff(options = {}) {
-  const actualOptions = {
-    relaxDurabilityRules: true,
-    ...options,
-  };
-  const { relaxDurabilityRules } = actualOptions;
-  const fakeStuff = makeFakeLiveSlotsStuff(actualOptions);
-  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
-  fakeStuff.setVrm(vrm);
-  const vom = makeFakeVirtualObjectManager(vrm, fakeStuff);
-  vom.initializeKindHandleKind();
-  const cm = makeFakeCollectionManager(vrm, fakeStuff, actualOptions);
-  const wpm = makeFakeWatchedPromiseManager(vrm, vom, cm, fakeStuff);
-  return { fakeStuff, vrm, vom, cm, wpm };
-}
-
-export function makeStandaloneFakeVirtualObjectManager(options = {}) {
-  const fakeStuff = makeFakeLiveSlotsStuff(options);
-  const { relaxDurabilityRules = true } = options;
-  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
-  fakeStuff.setVrm(vrm);
-  const vom = makeFakeVirtualObjectManager(vrm, fakeStuff);
-  vom.initializeKindHandleKind();
-  return vom;
-}
-
-export function makeStandaloneFakeCollectionManager(options = {}) {
-  const fakeStuff = makeFakeLiveSlotsStuff(options);
-  const { relaxDurabilityRules = true } = options;
-  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
-  fakeStuff.setVrm(vrm);
-  return makeFakeCollectionManager(vrm, fakeStuff, options);
-}
-
-export {
-  makeStandaloneFakeVirtualObjectManager as makeFakeVirtualObjectManager,
-  makeStandaloneFakeCollectionManager as makeFakeCollectionManager,
-};