@agoric/swingset-liveslots 0.10.3-u18a.0 → 0.10.3-u19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swingset-liveslots",
-  "version": "0.10.3-u18a.0",
+  "version": "0.10.3-u19.0",
   "description": "SwingSet ocap support layer",
   "type": "module",
   "main": "src/index.js",
@@ -14,31 +14,32 @@
     "lint-fix": "yarn lint:eslint --fix",
     "lint": "run-s --continue-on-error lint:*",
     "lint:types": "tsc",
-    "lint:eslint": "eslint ."
+    "lint:eslint": "eslint .",
+    "prepack": "tsc --build tsconfig.build.json",
+    "postpack": "git clean -f ':!src/types-index.d.ts' '*.d.ts*' '*.tsbuildinfo'"
   },
   "dependencies": {
-    "@agoric/internal": "^0.4.0-u18a.0",
-    "@agoric/store": "^0.9.3-u18.1",
+    "@agoric/internal": "^0.4.0-u19.0",
+    "@agoric/store": "^0.9.3-u19.0",
     "@endo/env-options": "^1.1.8",
-    "@endo/errors": "^1.2.8",
-    "@endo/eventual-send": "^1.2.8",
-    "@endo/exo": "^1.5.7",
-    "@endo/far": "^1.1.9",
-    "@endo/init": "^1.1.7",
-    "@endo/marshal": "^1.6.2",
-    "@endo/nat": "^5.0.13",
-    "@endo/pass-style": "^1.4.7",
-    "@endo/patterns": "^1.4.7",
-    "@endo/promise-kit": "^1.1.8"
+    "@endo/errors": "^1.2.9",
+    "@endo/eventual-send": "^1.3.0",
+    "@endo/exo": "^1.5.8",
+    "@endo/far": "^1.1.10",
+    "@endo/init": "^1.1.8",
+    "@endo/marshal": "^1.6.3",
+    "@endo/nat": "^5.0.14",
+    "@endo/pass-style": "^1.4.8",
+    "@endo/patterns": "^1.4.8",
+    "@endo/promise-kit": "^1.1.9"
   },
   "devDependencies": {
-    "@agoric/kmarshal": "^0.1.1-u18.1",
+    "@agoric/kmarshal": "^0.1.1-u19.0",
     "ava": "^5.3.0"
   },
   "files": [
-    "src/**/*.js",
-    "src/**/*.d.ts",
-    "test/**/*.js",
+    "src",
+    "test",
     "tools",
     "exported.js"
   ],
@@ -59,14 +60,13 @@
     "require": [
       "@endo/init/debug.js"
     ],
-    "timeout": "20m",
-    "workerThreads": false
+    "timeout": "20m"
   },
   "publishConfig": {
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 75.24
+    "atLeast": 75.2
   },
-  "gitHead": "4e4d2b4dedc5a268178712fc6beb89496518480a"
+  "gitHead": "29e9704c375a06bb617027093b30d2d25faa6471"
 }

package/src/boyd-gc.d.ts

@@ -0,0 +1,12 @@
+export function makeBOYDKit({ gcTools, slotToVal, vrm, kernelRecognizableRemotables, syscall, possiblyDeadSet, possiblyRetiredSet, }: {
+    gcTools: any;
+    slotToVal: any;
+    vrm: any;
+    kernelRecognizableRemotables: any;
+    syscall: any;
+    possiblyDeadSet: any;
+    possiblyRetiredSet: any;
+}): {
+    scanForDeadObjects: () => Promise<void>;
+};
+//# sourceMappingURL=boyd-gc.d.ts.map

package/src/boyd-gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boyd-gc.d.ts","sourceRoot":"","sources":["boyd-gc.js"],"names":[],"mappings":"AA+YO;;;;;;;;;;EAqMN"}

package/src/cache.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @template V
+ * @callback CacheGet
+ * @param {string} key
+ * @returns {V | undefined}
+ */
+/**
+ * @template V
+ * @callback CacheSet
+ * @param {string} key
+ * @param {V} value
+ * @returns {void}
+ */
+/**
+ * @callback CacheDelete
+ * @param {string} key
+ * @returns {void}
+ *
+ * @callback CacheFlush
+ * @returns {void}
+ *
+ * @callback CacheInsistClear
+ * @returns {void}
+ */
+/**
+ * @template V
+ * @typedef {object} Cache
+ * @property {CacheGet<V>} get
+ * @property {CacheSet<V>} set
+ * @property {CacheDelete} delete
+ * @property {CacheFlush} flush
+ * @property {CacheInsistClear} insistClear
+ */
+/**
+ * Cache of virtual object/collection state
+ *
+ * This cache is empty between deliveries. Within a delivery, the
+ * first access to some data will cause vatstore reads to populate the
+ * cache, then the data is retained until end-of-delivery. Writes to
+ * data will update the cache entry and mark it as dirty. At
+ * end-of-delivery, we flush the cache, writing out any dirty entries,
+ * and deleting all entries.
+ *
+ * This needs RAM for everything read during a delivery (rather than
+ * having a fixed maximum size), but yields a simple (easy to debug)
+ * deterministic relationship between data access and reads/writes to
+ * the backing store.
+ *
+ * @template V
+ * @param {(key: string) => V} readBacking
+ * @param {(key: string, value: V) => void} writeBacking
+ * @param {(key: string) => void} deleteBacking
+ * @returns {Cache<V>}
+ *
+ * This cache is part of the virtual object manager and is not intended to be
+ * used independently; it is exported only for the benefit of test code.
+ */
+export function makeCache<V>(readBacking: (key: string) => V, writeBacking: (key: string, value: V) => void, deleteBacking: (key: string) => void): Cache<V>;
+export type CacheGet<V> = (key: string) => V | undefined;
+export type CacheSet<V> = (key: string, value: V) => void;
+export type CacheDelete = (key: string) => void;
+export type CacheFlush = () => void;
+export type CacheInsistClear = () => void;
+export type Cache<V> = {
+    get: CacheGet<V>;
+    set: CacheSet<V>;
+    delete: CacheDelete;
+    flush: CacheFlush;
+    insistClear: CacheInsistClear;
+};
+//# sourceMappingURL=cache.d.ts.map

package/src/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["cache.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;;;;;GAMG;AACH;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0BATa,CAAC,eACH,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,gBAClB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,iBAC/B,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACnB,KAAK,CAAC,CAAC,CAAC,CAkDpB;qBAvGY,CAAC,UAEH,MAAM,KACJ,CAAC,GAAG,SAAS;qBAIb,CAAC,UAEH,MAAM,SACN,CAAC,KACC,IAAI;gCAIN,MAAM,KACJ,IAAI;+BAGJ,IAAI;qCAGJ,IAAI;kBAGJ,CAAC;SAEA,QAAQ,CAAC,CAAC,CAAC;SACX,QAAQ,CAAC,CAAC,CAAC;YACX,WAAW;WACX,UAAU;iBACV,gBAAgB"}

package/src/capdata.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Assert function to ensure that something expected to be a capdata object
+ * actually is.  A capdata object should have a .body property that's a string
+ * and a .slots property that's an array of strings.
+ *
+ * @param {any} capdata  The object to be tested
+ * @throws {Error} if, upon inspection, the parameter does not satisfy the above
+ *   criteria.
+ * @returns {asserts capdata is import('./types.js').SwingSetCapData}
+ */
+export function insistCapData(capdata: any): asserts capdata is import("./types.js").SwingSetCapData;
+//# sourceMappingURL=capdata.d.ts.map

package/src/capdata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capdata.d.ts","sourceRoot":"","sources":["capdata.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,uCALW,GAAG,GAGD,QAAQ,OAAO,IAAI,OAAO,YAAY,EAAE,eAAe,CAQnE"}

package/src/collectionManager.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @param {*} syscall
+ * @param {import('./virtualReferences.js').VirtualReferenceManager} vrm
+ * @param {() => number} allocateExportID
+ * @param {() => number} allocateCollectionID
+ * @param {(val: any) => string | undefined} convertValToSlot
+ * @param {*} convertSlotToVal
+ * @param {*} registerValue
+ * @param {ToCapData<string>} serialize
+ * @param {FromCapData<string>} unserialize
+ * @param {(capDatas: any) => void} assertAcceptableSyscallCapdataSize
+ */
+export function makeCollectionManager(syscall: any, vrm: import("./virtualReferences.js").VirtualReferenceManager, allocateExportID: () => number, allocateCollectionID: () => number, convertValToSlot: (val: any) => string | undefined, convertSlotToVal: any, registerValue: any, serialize: ToCapData<string>, unserialize: FromCapData<string>, assertAcceptableSyscallCapdataSize: (capDatas: any) => void): {
+    initializeStoreKindInfo: () => void;
+    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>;
+    provideBaggage: () => any;
+    flushSchemaCache: () => void;
+    getRetentionStats: () => {};
+    testHooks: {
+        obtainStoreKindID: (kindName: any) => any;
+        storeSizeInternal: (vobjID: any) => number;
+        makeCollection: (label: any, kindName: any, isDurable: any, keyShape: any, valueShape: any) => (string | {
+            has: (key: any) => boolean;
+            get: (key: any) => any;
+            init: (key: any, value: any) => void;
+            addToSet: (key: any) => void;
+            addAllToSet: (elems: any) => void;
+            addAllToMap: (mapEntries: any) => void;
+            set: (key: any, value: any) => void;
+            delete: (key: any) => void;
+        })[];
+    };
+};
+export const collectionMetaKeys: Set<string>;
+export type SchemaCacheValue = {
+    keyShape: Pattern;
+    valueShape: Pattern;
+    label: string;
+    schemataCapData: object;
+};
+import type { ToCapData } from '@endo/marshal';
+import type { FromCapData } from '@endo/marshal';
+//# sourceMappingURL=collectionManager.d.ts.map

package/src/collectionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionManager.d.ts","sourceRoot":"","sources":["collectionManager.js"],"names":[],"mappings":"AAmHA;;;;;;;;;;;GAWG;AACH,+CAXW,GAAC,OACD,OAAO,wBAAwB,EAAE,uBAAuB,oBACxD,MAAM,MAAM,wBACZ,MAAM,MAAM,oBACZ,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,oBAChC,GAAC,iBACD,GAAC,aACD,UAAU,MAAM,CAAC,eACjB,YAAY,MAAM,CAAC,sCACnB,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI;;4BAs+BnB,CAAC,EAAC,CAAC,UACL,MAAM,YACN,YAAY,KACV,QAAQ,CAAC,CAAC,EAAC,CAAC,CAAC;gCASb,CAAC,EAAC,CAAC,UACL,MAAM,YACN,YAAY,KACV,YAAY,CAAC,CAAC,EAAC,CAAC,CAAC;4BASjB,CAAC,UACH,MAAM,YACN,YAAY,KACV,QAAQ,CAAC,CAAC,CAAC;gCASX,CAAC,UACH,MAAM,YACN,YAAY,KACV,YAAY,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;EAsB7B;AA7lCD,6CAIG;;cAIW,OAAO;gBACP,OAAO;WACP,MAAM;qBACN,MAAM;;+BAlDqB,eAAe;iCAAf,eAAe"}

package/src/facetiousness.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Assess the facetiousness of a value.  If the value is an object containing
+ * only named properties and each such property's value is a function, `obj`
+ * represents a single facet and 'one' is returned.  If each property's value
+ * is instead an object of facetiousness 'one', `obj` represents multiple
+ * facets and 'many' is returned.  In all other cases `obj` does not represent
+ * any kind of facet abstraction and 'not' is returned.
+ *
+ * @typedef {'one'|'many'|'not'} Facetiousness
+ *
+ * @param {*} obj  The (alleged) object to be assessed
+ * @returns {Facetiousness} an assessment of the facetiousness of `obj`
+ */
+export function assessFacetiousness(obj: any): Facetiousness;
+export function checkAndUpdateFacetiousness(tag: any, desc: any, proposedFacetNames: any): any;
+/**
+ * Assess the facetiousness of a value.  If the value is an object containing
+ * only named properties and each such property's value is a function, `obj`
+ * represents a single facet and 'one' is returned.  If each property's value
+ * is instead an object of facetiousness 'one', `obj` represents multiple
+ * facets and 'many' is returned.  In all other cases `obj` does not represent
+ * any kind of facet abstraction and 'not' is returned.
+ */
+export type Facetiousness = "one" | "many" | "not";
+//# sourceMappingURL=facetiousness.d.ts.map

package/src/facetiousness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facetiousness.d.ts","sourceRoot":"","sources":["facetiousness.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,yCAHW,GAAC,GACC,aAAa,CA+BzB;AAGM,+FAwCN;;;;;;;;;4BA7EY,KAAK,GAAC,MAAM,GAAC,KAAK"}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types-index.js";
+export { makeLiveSlots, makeMarshaller } from "./liveslots.js";
+export { insistMessage, insistVatDeliveryObject, insistVatDeliveryResult, insistVatSyscallObject, insistVatSyscallResult } from "./message.js";
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}

package/src/kdebug.d.ts

@@ -0,0 +1,7 @@
+export function kdebugEnable(flag: any): void;
+export function kdebug(...args: any[]): void;
+export function legibilizeValue(val: any, slots: any, smallcaps: any): any;
+export function legibilizeMethod(method: any, smallcaps: any): string;
+export function extractMethod(methargsCapdata: any): string;
+export function legibilizeMessageArgs(methargsCapdata: any): any[] | "<unintelligible message args>";
+//# sourceMappingURL=kdebug.d.ts.map

package/src/kdebug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kdebug.d.ts","sourceRoot":"","sources":["kdebug.js"],"names":[],"mappings":"AAEA,8CAEC;AAED,6CAIC;AAED,2EAwEC;AAED,sEAmDC;AAED,4DAaC;AAED,qGAkBC"}

package/src/liveslots.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Instantiate the liveslots layer for a new vat and then populate the vat with
+ * a new root object and its initial associated object graph, if any.
+ *
+ * @param {*} syscall  Kernel syscall interface that the vat will have access to
+ * @param {*} forVatID  Vat ID label, for use in debug diagostics
+ * @param {*} vatPowers
+ * @param {import('./types.js').LiveSlotsOptions} liveSlotsOptions
+ * @param {*} gcTools { WeakRef, FinalizationRegistry, waitUntilQuiescent }
+ * @param {LimitedConsole} [liveSlotsConsole]
+ * @param {*} [buildVatNamespace]
+ *
+ * @returns {*} { dispatch }
+ *
+ * setBuildRootObject should be called, once, with a function that will
+ * create a root object for the new vat The caller provided buildRootObject
+ * function produces and returns the new vat's root object:
+ *
+ * buildRootObject(vatPowers, vatParameters)
+ *
+ * Within the vat, `import { E } from '@endo/eventual-send'` will
+ * provide the E wrapper. For any object x, E(x) returns a proxy object
+ * that converts any method invocation into a corresponding eventual send
+ * to x. That is, E(x).foo(arg1, arg2) is equivalent to x~.foo(arg1,
+ * arg2)
+ *
+ * If x is the presence in this vat of a remote object (that is, an object
+ * outside the vat), this will result in a message send out of the vat via
+ * the kernel syscall interface.
+ *
+ * In the same vein, if x is the presence in this vat of a kernel device,
+ * vatPowers.D(x) returns a proxy such that a method invocation on it is
+ * translated into the corresponding immediate invocation of the device
+ * (using, once again, the kernel syscall interface). D(x).foo(args) will
+ * perform an immediate syscall.callNow on the device node.
+ */
+export function makeLiveSlots(syscall: any, forVatID: any | undefined, vatPowers: any | undefined, liveSlotsOptions: import("./types.js").LiveSlotsOptions, gcTools: any, liveSlotsConsole?: LimitedConsole, buildVatNamespace?: any): any;
+export function makeMarshaller(syscall: any, gcTools: any, vatID?: string): {
+    m: any;
+};
+import type { LimitedConsole } from '@agoric/internal/src/js-utils.js';
+//# sourceMappingURL=liveslots.d.ts.map

package/src/liveslots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveslots.d.ts","sourceRoot":"","sources":["liveslots.js"],"names":[],"mappings":"AAm9CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,uCAhCW,GAAC,YACD,GAAC,yBACD,GAAC,gCACD,OAAO,YAAY,EAAE,gBAAgB,WACrC,GAAC,qBACD,cAAc,sBACd,GAAC,GAEC,GAAC,CAgDb;AAGD;;EAIC;oCAtgDiC,kCAAkC"}

package/src/liveslots.js

@@ -14,6 +14,8 @@ import { makeCollectionManager } from './collectionManager.js';
 import { makeWatchedPromiseManager } from './watchedPromises.js';
 import { makeBOYDKit } from './boyd-gc.js';
 
+/** @import {LimitedConsole} from '@agoric/internal/src/js-utils.js'; */
+
 const SYSCALL_CAPDATA_BODY_SIZE_LIMIT = 10_000_000;
 const SYSCALL_CAPDATA_SLOTS_LENGTH_LIMIT = 10_000;
 
@@ -32,7 +34,7 @@ const SYSCALL_CAPDATA_SLOTS_LENGTH_LIMIT = 10_000;
  * @param {import('./types.js').LiveSlotsOptions} liveSlotsOptions
  * @param {*} gcTools { WeakRef, FinalizationRegistry, waitUntilQuiescent, gcAndFinalize,
  *                      meterControl }
- * @param {Pick<Console, 'debug' | 'log' | 'info' | 'warn' | 'error'>} console
+ * @param {LimitedConsole} console
  * @param {*} buildVatNamespace
  *
  * @returns {*} { dispatch }
@@ -1496,7 +1498,7 @@ function build(
  * @param {*} vatPowers
  * @param {import('./types.js').LiveSlotsOptions} liveSlotsOptions
  * @param {*} gcTools { WeakRef, FinalizationRegistry, waitUntilQuiescent }
- * @param {Pick<Console, 'debug' | 'log' | 'info' | 'warn' | 'error'>} [liveSlotsConsole]
+ * @param {LimitedConsole} [liveSlotsConsole]
  * @param {*} [buildVatNamespace]
  *
  * @returns {*} { dispatch }

package/src/message.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @typedef {{
+ * methargs: import('./types.js').SwingSetCapData, // of [method, args]
+ * result: string | undefined | null,
+ * }} Message
+ */
+/**
+ * Assert function to ensure that something expected to be a message object
+ * actually is.  A message object should have a .method property that's a
+ * string, a .args property that's a capdata object, and optionally a .result
+ * property that, if present, must be a string.
+ *
+ * @param {any} message  The object to be tested
+ *
+ * @throws {Error} if, upon inspection, the parameter does not satisfy the above
+ *   criteria.
+ *
+ * @returns {asserts message is Message}
+ */
+export function insistMessage(message: any): asserts message is Message;
+/**
+ * @param {unknown} vdo
+ * @returns {asserts vdo is import('./types').VatDeliveryObject}
+ */
+export function insistVatDeliveryObject(vdo: unknown): asserts vdo is import("./types").VatDeliveryObject;
+/**
+ * @param {unknown} vdr
+ * @returns {asserts vdr is VatDeliveryResult}
+ */
+export function insistVatDeliveryResult(vdr: unknown): asserts vdr is VatDeliveryResult;
+/**
+ * @param {unknown} vso
+ * @returns {asserts vso is import('./types').VatSyscallObject}
+ */
+export function insistVatSyscallObject(vso: unknown): asserts vso is import("./types").VatSyscallObject;
+/**
+ * @param {unknown} vsr
+ * @returns {asserts vsr is import('./types').VatSyscallResult}
+ */
+export function insistVatSyscallResult(vsr: unknown): asserts vsr is import("./types").VatSyscallResult;
+export type Message = {
+    methargs: import("./types.js").SwingSetCapData;
+    result: string | undefined | null;
+};
+//# sourceMappingURL=message.d.ts.map

package/src/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["message.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AAEH,uCARW,GAAG,GAKD,QAAQ,OAAO,IAAI,OAAO,CAStC;AAED;;;GAGG;AAEH,6CAJW,OAAO,GACL,QAAQ,GAAG,IAAI,OAAO,SAAS,EAAE,iBAAiB,CAwD9D;AAED;;;GAGG;AAEH,6CAJW,OAAO,GACL,QAAQ,GAAG,IAAI,iBAAiB,CAkB5C;AAED;;;GAGG;AAEH,4CAJW,OAAO,GACL,QAAQ,GAAG,IAAI,OAAO,SAAS,EAAE,gBAAgB,CA4E7D;AAED;;;GAGG;AAEH,4CAJW,OAAO,GACL,QAAQ,GAAG,IAAI,OAAO,SAAS,EAAE,gBAAgB,CAkB7D;sBAlNY;IACV,QAAQ,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC;IAC/C,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACjC"}

package/src/parseVatSlots.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Parse a vref string into its component parts:
+ *   {
+ *      type: STRING, // 'object', 'device', 'promise'
+ *      allocatedByVat: BOOL, // true=>allocated by vat, false=>by the kernel
+ *      id: Nat,
+ *      subid: Nat,
+ *      baseRef: STRING,
+ *      facet: Nat,
+ *      virtual: BOOL, // true=>vref designates a "merely virtual" object (not durable, not ephemeral)
+ *      durable: BOOL, // designates a durable (not merely virtual, not ephemeral)
+ *   }
+ *
+ * A vref string can take one of the forms:
+ *
+ *   T-N
+ *   T+N
+ *   T+DN/I
+ *   T+DN/I:F
+ *
+ * Where:
+ *
+ *   T is a single character encoding the type of entity being referenced: 'd'
+ *      for 'device', 'o' for 'object', or 'p' for 'promise'.  One of the string
+ *      values 'device', 'object', or 'promise' is returned as the `type`
+ *      property of the result.
+ *
+ *   '+' or '-' encodes who allocated the reference: '-' for the kernel
+ *      (typically an import) or '+ for the vat (typically an export).  This is
+ *      returned in the `allocatedByVat` property of the result as a boolean.
+ *
+ *   D is the durability status: for object exports ("o+"), this will
+ *      be the letter 'd' for durable objects, the letter 'v' for
+ *      non-durable ("merely virtual") objects, or empty for
+ *      "Remotable" (ephemeral) objects. It is empty for object
+ *      imports ("o-"), and both both imports and exports of all other
+ *      types (promises, devices)
+ *
+ *   N is a decimal integer representing the identity of the referenced entity.
+ *      This is returned in the `id` property of the result as a BigInt.
+ *
+ *   I if present (only allowed if T is 'o') is a decimal integer representing
+ *      the instance id of the referenced object.  In this case N denotes a
+ *      category of objects that share a common shape, either one of the store
+ *      types or a virtual object kind, and I indicates which instance of that
+ *      category is being referred to.  If present this is returned as the
+ *      `subid` property of the result as a BigInt.
+ *
+ *   F if present (only allowed if I is also present) is a decimal integer
+ *      referencing a facet of the referenced object.  In this case N/I denotes
+ *      a particular object instance and F indicates which of several possible
+ *      facets of that instance is being addressed.  If present this is returned
+ *      in the `facet` property of the result as a BigInt.
+ *
+ * The `baseRef` property of the result is `vref` stripped of any facet indicator.
+ *
+ * A "vref" identifies an entity visible to vat code to which messages may be
+ * sent and which may be compared for equality to other such entities.  Let's
+ * call such an entity an "addressable object".
+ *
+ * A "baseRef" designates an entity that is managed by LiveSlots, both as a unit
+ * of garbage collection specifically and as a unit of memory management more
+ * generally.  Such an entity may be a promise or remotable object or imported
+ * presence, all of which will always be JavaScript objects in memory, or it may
+ * be a virtual object or collection, which can be in memory or on disk or both.
+ * Let's call such an entity a "base object".  In most cases this is one and the
+ * same with the addressable object that the vref designates, but in the case of
+ * a faceted object it is the cohort record as a whole rather than any particular
+ * individual facet.
+ *
+ * XXX TODO: The previous comment suggests some renaming is warranted:
+ *
+ * In the current implementation, a vref string may only include decimal digits,
+ * the letters 'd'/'o'/'p'/'v', and the punctuation characters '+', '-', '/',
+ * and ':'.  Future evolution of the vref syntax might add more characters to
+ * this set, but the characters '|' and ',' are permanently excluded: '|' is
+ * used (notably by the collection manager) as delimiter in vatstore keys that
+ * include vrefs, and ',' is used as a separator in lists of vrefs.
+ *
+ * `slotToVal` maps a baseRef to a base object (actually to a weakRef that
+ *    points to a base object)
+ * `getValForSlot` maps a baseRef to a base object, or to undefined if it is not
+ *    resident in memory
+ * `convertSlotToVal` maps a vref to to an addressable object, loading it from
+ *    disk if necessary
+ *
+ * `valToSlot` maps an addressable object to a vref
+ * `getSlotForVal` maps an addressable object to a vref
+ * `convertValToSlot` maps an addressable object to a vref, generating a new
+ *    vref if necessary
+ *
+ * @param {string} vref  The string to be parsed, as described above.
+ *
+ * @returns {*} a vref components descriptor corresponding to the vref string
+ *    parameter, assuming it is syntactically well formed.
+ *
+ * @throws if the given vref string is syntactically incorrect.
+ */
+export function parseVatSlot(vref: string): any;
+/**
+ * Generate a vat slot reference string given a type, ownership, and id.
+ *
+ * @param {'object'|'device'|'promise'} type The type
+ * @param {boolean} allocatedByVat  Flag: true=>vat allocated, false=>kernel allocated
+ * @param {number | bigint} id    The id, a Nat.
+ *
+ * @returns {string} the corresponding vat slot reference string.
+ *
+ * @throws if type is not one of the above known types.
+ */
+export function makeVatSlot(type: "object" | "device" | "promise", allocatedByVat: boolean, id: number | bigint): string;
+export function makeBaseRef(kindID: any, id: any, isDurable: any): string;
+/**
+ * Assert function to ensure that a vat slot reference string refers to a
+ * slot of a given type.
+ *
+ * @param {string} type  The vat slot type desired, a string.
+ * @param {string} vatSlot  The vat slot reference string being tested
+ *
+ * @throws if vatSlot is not of the given type or is malformed.
+ *
+ * @returns {void}
+ */
+export function insistVatType(type: string, vatSlot: string): void;
+//# sourceMappingURL=parseVatSlots.d.ts.map

package/src/parseVatSlots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseVatSlots.d.ts","sourceRoot":"","sources":["parseVatSlots.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,mCAPW,MAAM,GAEJ,GAAC,CA4Db;AAED;;;;;;;;;;GAUG;AACH,kCARW,QAAQ,GAAC,QAAQ,GAAC,SAAS,kBAC3B,OAAO,MACP,MAAM,GAAG,MAAM,GAEb,MAAM,CAsBlB;AAED,0EAEC;AAED;;;;;;;;;;GAUG;AACH,oCAPW,MAAM,WACN,MAAM,GAIJ,IAAI,CAKhB"}

package/src/types.d.ts

@@ -0,0 +1,76 @@
+export type makeLiveSlots = () => any;
+/**
+ * The MeterControl object gives liveslots a mechanism to disable metering for certain GC-sensitive
+ * regions of code. Only the XS worker can actually do metering, but we track the enabled/disabled
+ * status on all workers, so that the assertions can be exercised more thoroughly (via non-XS unit
+ * tests). MeterControl.isMeteringDisabled()===false does not mean metering is happening, it just
+ * means that MeterControl isn't disabling it.
+ */
+export type MeterControl = {
+    /**
+     * Ask whether metering is currently disabled.
+     */
+    isMeteringDisabled: () => boolean;
+    assertIsMetered: any;
+    assertNotMetered: any;
+    /**
+     * Run a callback outside metering
+     */
+    runWithoutMetering: any;
+    /**
+     * Run an async callback outside metering
+     */
+    runWithoutMeteringAsync: any;
+    /**
+     * Wrap a callback with runWithoutMetering
+     */
+    unmetered: any;
+};
+export type LiveSlotsOptions = {
+    enableDisavow?: boolean;
+    relaxDurabilityRules?: boolean;
+    allowStateShapeChanges?: boolean;
+};
+export type SwingSetCapData = import("@endo/marshal").CapData<string>;
+export type Message = {
+    methargs: SwingSetCapData;
+    result: string | undefined | null;
+};
+export type VatDeliveryMessage = [tag: "message", target: string, msg: Message];
+export type VatOneResolution = [vpid: string, isReject: boolean, data: SwingSetCapData];
+export type VatDeliveryNotify = [tag: "notify", resolutions: VatOneResolution[]];
+export type VatDeliveryDropExports = [tag: "dropExports", vrefs: string[]];
+export type VatDeliveryRetireExports = [tag: "retireExports", vrefs: string[]];
+export type VatDeliveryRetireImports = [tag: "retireImports", vrefs: string[]];
+export type VatDeliveryChangeVatOptions = [tag: "changeVatOptions", options: Record<string, unknown>];
+export type VatDeliveryStartVat = [tag: "startVat", vatParameters: SwingSetCapData];
+export type VatDeliveryStopVat = [tag: "stopVat", disconnectObject: SwingSetCapData];
+export type VatDeliveryBringOutYourDead = [tag: "bringOutYourDead"];
+export type VatDeliveryObject = VatDeliveryMessage | VatDeliveryNotify | VatDeliveryDropExports | VatDeliveryRetireExports | VatDeliveryRetireImports | VatDeliveryChangeVatOptions | VatDeliveryStartVat | VatDeliveryStopVat | VatDeliveryBringOutYourDead;
+export type MeterConsumption = {
+    compute: number;
+};
+export type VatDeliveryResult = [tag: "ok", results: any, usage: MeterConsumption | null] | [tag: "error", message: string, usage: MeterConsumption | null];
+export type VatSyscallSend = [tag: "send", target: string, msg: Message];
+export type VatSyscallCallNow = [tag: "callNow", target: string, method: string, args: SwingSetCapData];
+export type VatSyscallSubscribe = [tag: "subscribe", vpid: string];
+export type VatSyscallResolve = [tag: "resolve", resolutions: VatOneResolution[]];
+export type VatSyscallExit = [tag: "exit", isFailure: boolean, info: SwingSetCapData];
+export type VatSyscallVatstoreGet = [tag: "vatstoreGet", key: string];
+export type VatSyscallVatstoreGetNextKey = [tag: "vatstoreGetNextKey", priorKey: string];
+export type VatSyscallVatstoreSet = [tag: "vatstoreSet", key: string, data: string];
+export type VatSyscallVatstoreDelete = [tag: "vatstoreDelete", key: string];
+export type VatSyscallDropImports = [tag: "dropImports", slots: string[]];
+export type VatSyscallRetireImports = [tag: "retireImports", slots: string[]];
+export type VatSyscallRetireExports = [tag: "retireExports", slots: string[]];
+export type VatSyscallAbandonExports = [tag: "abandonExports", slots: string[]];
+export type VatSyscallObject = VatSyscallSend | VatSyscallCallNow | VatSyscallSubscribe | VatSyscallResolve | VatSyscallExit | VatSyscallVatstoreGet | VatSyscallVatstoreGetNextKey | VatSyscallVatstoreSet | VatSyscallVatstoreDelete | VatSyscallDropImports | VatSyscallRetireImports | VatSyscallRetireExports | VatSyscallAbandonExports;
+export type VatSyscallResultOk = [tag: "ok", data: SwingSetCapData | string | string[] | null];
+export type VatSyscallResultError = [tag: "error", err: string];
+export type VatSyscallResult = VatSyscallResultOk | VatSyscallResultError;
+export type VatSyscallHandler = (vso: VatSyscallObject) => VatSyscallResult;
+export type PromiseWatcher<V, A extends any[] = unknown[]> = {
+    onFulfilled?: (value: V, ...args: A) => void;
+    onRejected?: (reason: unknown, ...args: A) => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"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"}