@agoric/swing-store 0.9.2-dev-3825031.0 → 0.9.2-dev-d1ef359.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swing-store",
-  "version": "0.9.2-dev-3825031.0+3825031",
+  "version": "0.9.2-dev-d1ef359.0+d1ef359",
   "description": "Persistent storage for SwingSet",
   "type": "module",
   "main": "./src/index.js",
@@ -21,7 +21,7 @@
     "lint:eslint": "eslint ."
   },
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-3825031.0+3825031",
+    "@agoric/internal": "0.3.3-dev-d1ef359.0+d1ef359",
     "@endo/base64": "^1.0.9",
     "@endo/bundle-source": "^3.5.1",
     "@endo/check-bundle": "^1.0.13",
@@ -51,5 +51,5 @@
   "typeCoverage": {
     "atLeast": 79.04
   },
-  "gitHead": "38250315cedf68dc801b75bee867818a3846fae7"
+  "gitHead": "d1ef35965047ef31f0fa5451d4cfb8bd06c59247"
 }

package/src/assertComplete.js

@@ -1,6 +1,6 @@
 /**
- * @param {import('./internal.js').SwingStoreInternal} internal
- * @param {Omit<import('./internal.js').ArtifactMode, 'debug'>} checkMode
+ * @param {Pick<import('./internal.js').SwingStoreInternal, 'bundleStore' | 'transcriptStore' | 'snapStore'>} internal
+ * @param {Exclude<import('./internal.js').ArtifactMode, 'debug'>} checkMode
  * @returns {void}
  */
 export function assertComplete(internal, checkMode) {

package/src/bundleStore.js

@@ -42,7 +42,7 @@ import { createSHA256 } from './hasher.js';
  *
  */
 
-function bundleIDFromName(name) {
+export const bundleIDFromName = name => {
   typeof name === 'string' || Fail`artifact name must be a string`;
   const [tag, ...pieces] = name.split('.');
   if (tag !== 'bundle' || pieces.length !== 1) {
@@ -52,7 +52,8 @@ function bundleIDFromName(name) {
   }
   const bundleID = pieces[0];
   return bundleID;
-}
+};
+harden(bundleIDFromName);
 
 /**
  * @param {*} db

package/src/exporter.js

@@ -15,10 +15,6 @@ import { validateArtifactMode } from './internal.js';
  * @template T
  * @typedef  { Iterable<T> | AsyncIterable<T> } AnyIterable
  */
-/**
- * @template T
- * @typedef  { IterableIterator<T> | AsyncIterableIterator<T> } AnyIterableIterator
- */
 
 /**
  *
@@ -41,7 +37,7 @@ import { validateArtifactMode } from './internal.js';
  * Retrieve a value from the "host" portion of the kvStore, just like
  * hostStorage.hostKVStore.get() would do.
  *
- * @property {() => AnyIterableIterator<KVPair>} getExportData
+ * @property {() => AnyIterable<KVPair>} getExportData
  *
  * Get a full copy of the first-stage export data (key-value pairs) from the
  * swingStore. This represents both the contents of the KVStore (excluding host
@@ -56,7 +52,7 @@ import { validateArtifactMode } from './internal.js';
  * - transcript.${vatID}.${startPos} = ${{ vatID, startPos, endPos, hash }}
  * - transcript.${vatID}.current = ${{ vatID, startPos, endPos, hash }}
  *
- * @property {() => AnyIterableIterator<string>} getArtifactNames
+ * @property {() => AnyIterable<string>} getArtifactNames
  *
  * Get a list of name of artifacts available from the swingStore.  A name
  * returned by this method guarantees that a call to `getArtifact` on the same
@@ -69,7 +65,7 @@ import { validateArtifactMode } from './internal.js';
  * - snapshot.${vatID}.${snapPos}
  * - bundle.${bundleID}
  *
- * @property {(name: string) => AnyIterableIterator<Uint8Array>} getArtifact
+ * @property {(name: string) => AnyIterable<Uint8Array>} getArtifact
  *
  * Retrieve an artifact by name as a sequence of binary chunks.  May throw if
  * the artifact is not available, which can occur if the artifact is historical

package/src/index.js

@@ -4,10 +4,12 @@ export { importSwingStore } from './importer.js';
 
 export { makeArchiveSnapshot, makeArchiveTranscript } from './archiver.js';
 
-// temporary, for the benefit of SwingSet/misc-tools/replay-transcript.js
+// for the benefit of tools like SwingSet/misc-tools/replay-transcript.js
+export { makeKVStore, getKeyType } from './kvStore.js';
+export { makeTranscriptStore } from './transcriptStore.js';
 export { makeSnapStore } from './snapStore.js';
-// and less temporary, for SwingSet/test/vat-warehouse/test-reload-snapshot.js
 export { makeSnapStoreIO } from './snapStoreIO.js';
+export { makeBundleStore, bundleIDFromName } from './bundleStore.js';
 
 // eslint-disable-next-line import/export
 export * from './types-index.js';

package/src/internal.js

@@ -7,6 +7,8 @@ import { Fail, q } from '@endo/errors';
  *
  * @typedef {{
  *    dirPath: string | null,
+ *    db: ReturnType<import('better-sqlite3')>,
+ *    kvStore: import('./kvStore.js').KVStore,
  *    transcriptStore: TranscriptStoreInternal,
  *    snapStore: SnapStoreInternal,
  *    bundleStore: BundleStoreInternal,

package/src/kvStore.js

@@ -27,7 +27,7 @@ export function getKeyType(key) {
 /**
  * @param {object} db  The SQLite database connection.
  * @param {() => void} ensureTxn  Called before mutating methods to establish a DB transaction
- * @param {(...args: string[]) => void} trace  Called after sets/gets to record a debug log
+ * @param {(...args: string[]) => void} trace  Called after set/delete to record a debug log
  * @returns { KVStore }
  */
 

package/src/snapStore.js

@@ -7,6 +7,11 @@ import { Fail, q } from '@endo/errors';
 import { withDeferredCleanup } from '@agoric/internal';
 import { buffer } from './util.js';
 
+/**
+ * @import { AnyIterable, SwingStoreExporter } from './exporter.js';
+ * @import { ArtifactMode } from './internal.js';
+ */
+
 /**
  * @typedef {object} SnapshotResult
  * @property {string} hash sha256 hash of (uncompressed) snapshot
@@ -26,13 +31,6 @@ import { buffer } from './util.js';
  */
 
 /**
- * @import {AnyIterableIterator} from './exporter.js'
- */
-
-/**
- * @typedef { import('./exporter.js').SwingStoreExporter } SwingStoreExporter
- * @typedef { import('./internal.js').ArtifactMode } ArtifactMode
- *
  * @typedef {{
  *   loadSnapshot: (vatID: string) => AsyncIterableIterator<Uint8Array>,
  *   saveSnapshot: (vatID: string, snapPos: number, snapshotStream: AsyncIterable<Uint8Array>) => Promise<SnapshotResult>,
@@ -47,17 +45,23 @@ import { buffer } from './util.js';
  *   getExportRecords: (includeHistorical: boolean) => IterableIterator<readonly [key: string, value: string]>,
  *   getArtifactNames: (artifactMode: ArtifactMode) => AsyncIterableIterator<string>,
  *   importSnapshotRecord: (key: string, value: string) => void,
- *   populateSnapshot: (name: string, makeChunkIterator: () => AnyIterableIterator<Uint8Array>, options: { artifactMode: ArtifactMode }) => Promise<void>,
+ *   populateSnapshot: (name: string, makeChunkIterator: () => AnyIterable<Uint8Array>, options: { artifactMode: ArtifactMode }) => Promise<void>,
  *   assertComplete: (checkMode: Omit<ArtifactMode, 'debug'>) => void,
  *   repairSnapshotRecord: (key: string, value: string) => void,
  * }} SnapStoreInternal
  *
  * @typedef {{
  *   hasHash: (vatID: string, hash: string) => boolean,
- *   dumpSnapshots: (includeHistorical?: boolean) => {},
+ *   listAllSnapshots: () => Iterable<{}>,
+ *   dumpSnapshots: (includeHistorical?: boolean) => Record<string, Array<{snapPos: number, hash: string, compressedSnapshot: Buffer, inUse: (null | 0 | 1)}>>,
  *   deleteSnapshotByHash: (vatID: string, hash: string) => void,
  * }} SnapStoreDebug
  *
+ * @callback SnapshotCallback
+ * Called with the gzipped contents of a new heap snapshot.
+ * @param {string} name  an export key, e.g. `snapshot.${vatID}.${deliveryCount}`
+ * @param {Parameters<import('stream').Readable.from>[0]} compressedData
+ * @returns {Promise<void>}
  */
 
 const finished = promisify(finishedCallback);
@@ -71,7 +75,7 @@ const finished = promisify(finishedCallback);
  * @param {(key: string, value: string | undefined) => void} noteExport
  * @param {object} [options]
  * @param {boolean | undefined} [options.keepSnapshots]
- * @param {(name: string, compressedData: Parameters<import('stream').Readable.from>[0]) => Promise<void>} [options.archiveSnapshot]
+ * @param {SnapshotCallback} [options.archiveSnapshot]
  * @returns {SnapStore & SnapStoreInternal & SnapStoreDebug}
  */
 export function makeSnapStore(
@@ -605,7 +609,7 @@ export function makeSnapStore(
 
   /**
    * @param {string} name  Artifact name of the snapshot
-   * @param {() => AnyIterableIterator<Uint8Array>} makeChunkIterator  get an iterator of snapshot byte chunks
+   * @param {() => AnyIterable<Uint8Array>} makeChunkIterator  get an iterator of snapshot byte chunks
    * @param {object} options
    * @param {ArtifactMode} options.artifactMode
    * @returns {Promise<void>}
@@ -677,7 +681,6 @@ export function makeSnapStore(
 
   /**
    * debug function to list all snapshots
-   *
    */
   function* listAllSnapshots() {
     yield* sqlListAllSnapshots.iterate();
@@ -706,6 +709,7 @@ export function makeSnapStore(
     const sql = includeHistorical
       ? sqlDumpAllSnapshots
       : sqlDumpCurrentSnapshots;
+    /** @type {Record<string, Array<{snapPos: number, hash: string, compressedSnapshot: Buffer, inUse: (null | 0 | 1)}>>} */
     const dump = {};
     for (const row of sql.iterate()) {
       const { vatID, snapPos, hash, compressedSnapshot, inUse } = row;

package/src/swingStore.js

@@ -1,12 +1,15 @@
 // @ts-check
 /* eslint-env node */
 import * as fs from 'fs';
-import * as path from 'path';
+import * as pathlib from 'path';
 
 import sqlite3 from 'better-sqlite3';
 
 import { Fail, q } from '@endo/errors';
 
+import { attenuate } from '@agoric/internal';
+import { TRUE } from '@agoric/internal/src/js-utils.js';
+
 import { dbFileInDirectory } from './util.js';
 import { makeKVStore, getKeyType } from './kvStore.js';
 import { makeTranscriptStore } from './transcriptStore.js';
@@ -16,6 +19,14 @@ import { createSHA256 } from './hasher.js';
 import { makeSnapStoreIO } from './snapStoreIO.js';
 import { doRepairMetadata } from './repairMetadata.js';
 
+// https://github.com/WiseLibs/better-sqlite3/blob/HEAD/docs/api.md#new-databasepath-options
+const IN_MEMORY = ':memory:';
+
+/**
+ * @template T
+ * @typedef {(input: T) => T} Replacer
+ */
+
 /**
  * @typedef { import('./kvStore.js').KVStore } KVStore
  *
@@ -119,24 +130,63 @@ import { doRepairMetadata } from './repairMetadata.js';
  * relative the relevant transactional unit.
  */
 
+/**
+ * @typedef {object} SwingStoreOptions
+ * @property {boolean} [asFile]  For testing, interpret path as a file rather than a swingstore.sqlite parent directory
+ * @property {Buffer} [serialized]  Binary data to load in memory
+ * @property {boolean} [unsafeFastMode]  Disable SQLite safeties for e.g. fast import
+ * @property {boolean} [readonly]
+ * @property {string} [traceFile]  Path at which to record KVStore set/delete activity
+ * @property {boolean} [keepSnapshots]  Retain old heap snapshots
+ * @property {boolean} [keepTranscripts]  Retain old transcript span items
+ * @property {import('./snapStore.js').SnapshotCallback} [archiveSnapshot]  Called after creation of a new heap snapshot
+ * @property {import('./transcriptStore.js').TranscriptCallback} [archiveTranscript]  Called after a formerly-current transcript span is finalized
+ * @property {(pendingExports: Iterable<[key: string, value: string | null]>) => void} [exportCallback]
+ * @property {Replacer<ReturnType<makeKVStore>>} [wrapKvStore]
+ * @property {Replacer<ReturnType<makeTranscriptStore>>} [wrapTranscriptStore]
+ * @property {Replacer<ReturnType<makeSnapStore>>} [wrapSnapStore]
+ * @property {Replacer<ReturnType<makeBundleStore>>} [wrapBundleStore]
+ */
+
 /**
  * Do the work of `initSwingStore` and `openSwingStore`.
  *
- * @param {string|null} dirPath  Path to a directory in which database files may
- *   be kept.  If this is null, the database will be an in-memory ephemeral
+ * @param {string|null} path  Path to a directory in which database files may
+ *   be kept (or when the `asFile` option is true, the path to such a database
+ *   file).  If this is null, the database will be an in-memory ephemeral
  *   database that evaporates when the process exits, which is useful for testing.
  * @param {boolean} forceReset  If true, initialize the database to an empty
  *   state if it already exists
- * @param {object} options  Configuration options
- *
+ * @param {SwingStoreOptions} [options]
  * @returns {SwingStore}
  */
-export function makeSwingStore(dirPath, forceReset, options = {}) {
-  const { serialized } = options;
+export function makeSwingStore(path, forceReset, options = {}) {
+  const {
+    asFile = false,
+    serialized,
+    unsafeFastMode,
+    readonly = false,
+
+    traceFile,
+    keepSnapshots,
+    keepTranscripts,
+    archiveSnapshot,
+    archiveTranscript,
+    exportCallback,
+    wrapKvStore = x => x,
+    wrapTranscriptStore = x => x,
+    wrapSnapStore = x => x,
+    wrapBundleStore = x => x,
+  } = options;
+
   if (serialized) {
     Buffer.isBuffer(serialized) || Fail`options.serialized must be Buffer`;
-    dirPath === null || Fail`options.serialized makes :memory: DB`;
+    path === null || Fail`options.serialized makes :memory: DB`;
   }
+  exportCallback === undefined ||
+    typeof exportCallback === 'function' ||
+    Fail`export callback must be a function`;
+
   let crankhasher;
   function resetCrankhash() {
     crankhasher = createSHA256();
@@ -144,40 +194,22 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
   resetCrankhash();
 
   let filePath;
-  if (dirPath) {
+  if (path) {
     if (forceReset) {
-      try {
-        // Node.js 16.8.0 warns:
-        // In future versions of Node.js, fs.rmdir(path, { recursive: true }) will
-        // be removed. Use fs.rm(path, { recursive: true }) instead
-        if (fs.rmSync) {
-          fs.rmSync(dirPath, { recursive: true });
-        } else {
-          fs.rmdirSync(dirPath, { recursive: true });
-        }
-      } catch (e) {
-        // Attempting to delete a non-existent directory is allowed
-        if (e.code !== 'ENOENT') {
-          throw e;
-        }
-      }
+      fs.rmSync(path, { recursive: true, force: true });
+    }
+    if (asFile) {
+      filePath = path;
+    } else {
+      fs.mkdirSync(path, { recursive: true });
+      filePath = dbFileInDirectory(path);
     }
-    fs.mkdirSync(dirPath, { recursive: true });
-    filePath = dbFileInDirectory(dirPath);
   } else {
     filePath = ':memory:';
   }
 
-  const {
-    traceFile,
-    keepSnapshots,
-    keepTranscripts,
-    archiveSnapshot,
-    archiveTranscript,
-  } = options;
-
   let traceOutput = traceFile
-    ? fs.createWriteStream(path.resolve(traceFile), {
+    ? fs.createWriteStream(pathlib.resolve(traceFile), {
         flags: 'a',
       })
     : null;
@@ -194,10 +226,10 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
   }
 
   /** @type {*} */
-  let db = sqlite3(
-    serialized || filePath,
-    // { verbose: console.log },
-  );
+  let db = sqlite3(/** @type {string} */ (serialized || filePath), {
+    readonly,
+    // verbose: console.log,
+  });
 
   // We use WAL (write-ahead log) mode to allow a background export process to
   // keep reading from an earlier DB state, while allowing execution to proceed
@@ -230,7 +262,7 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
   }
 
   // PRAGMAs have to happen outside a transaction
-  setUnsafeFastMode(options.unsafeFastMode);
+  if (!readonly) setUnsafeFastMode(unsafeFastMode);
 
   // We use IMMEDIATE because the kernel is supposed to be the sole writer of
   // the DB, and if some other process is holding a write lock, we want to find
@@ -273,11 +305,6 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
     )
   `);
 
-  const { exportCallback } = options;
-  exportCallback === undefined ||
-    typeof exportCallback === 'function' ||
-    Fail`export callback must be a function`;
-
   const sqlAddPendingExport = db.prepare(`
     INSERT INTO pendingExports (key, value)
     VALUES (?, ?)
@@ -290,31 +317,22 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
     }
   }
 
-  const kvStore = makeKVStore(db, ensureTxn, trace);
+  const kvStore = wrapKvStore(makeKVStore(db, ensureTxn, trace));
 
-  const { dumpTranscripts, ...transcriptStore } = makeTranscriptStore(
-    db,
-    ensureTxn,
-    noteExport,
-    {
+  const { dumpTranscripts, ...transcriptStoreInternal } = wrapTranscriptStore(
+    makeTranscriptStore(db, ensureTxn, noteExport, {
       keepTranscripts,
       archiveTranscript,
-    },
+    }),
   );
-  const { dumpSnapshots, ...snapStore } = makeSnapStore(
-    db,
-    ensureTxn,
-    makeSnapStoreIO(),
-    noteExport,
-    {
+  const { dumpSnapshots, ...snapStoreInternal } = wrapSnapStore(
+    makeSnapStore(db, ensureTxn, makeSnapStoreIO(), noteExport, {
       keepSnapshots,
       archiveSnapshot,
-    },
+    }),
   );
-  const { dumpBundles, ...bundleStore } = makeBundleStore(
-    db,
-    ensureTxn,
-    noteExport,
+  const { dumpBundles, ...bundleStoreInternal } = wrapBundleStore(
+    makeBundleStore(db, ensureTxn, noteExport),
   );
 
   const sqlCommit = db.prepare('COMMIT');
@@ -325,13 +343,9 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
   let inCrank = false;
 
   function diskUsage() {
-    if (dirPath) {
-      const dataFilePath = dbFileInDirectory(dirPath);
-      const stat = fs.statSync(dataFilePath);
-      return stat.size;
-    } else {
-      return 0;
-    }
+    if (filePath === IN_MEMORY) return 0;
+    const stat = fs.statSync(filePath);
+    return stat.size;
   }
 
   const kernelKVStore = {
@@ -503,10 +517,13 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
 
   /** @type {import('./internal.js').SwingStoreInternal} */
   const internal = harden({
-    dirPath,
-    snapStore,
-    transcriptStore,
-    bundleStore,
+    dirPath: asFile ? null : path,
+    asFile,
+    db,
+    kvStore,
+    snapStore: snapStoreInternal,
+    transcriptStore: transcriptStoreInternal,
+    bundleStore: bundleStoreInternal,
   });
 
   async function repairMetadata(exporter) {
@@ -549,38 +566,38 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
     return db;
   }
 
-  const transcriptStorePublic = {
-    initTranscript: transcriptStore.initTranscript,
-    rolloverSpan: transcriptStore.rolloverSpan,
-    rolloverIncarnation: transcriptStore.rolloverIncarnation,
-    getCurrentSpanBounds: transcriptStore.getCurrentSpanBounds,
-    addItem: transcriptStore.addItem,
-    readSpan: transcriptStore.readSpan,
-    stopUsingTranscript: transcriptStore.stopUsingTranscript,
-    deleteVatTranscripts: transcriptStore.deleteVatTranscripts,
-  };
+  const transcriptStore = attenuate(transcriptStoreInternal, {
+    initTranscript: TRUE,
+    rolloverSpan: TRUE,
+    rolloverIncarnation: TRUE,
+    getCurrentSpanBounds: TRUE,
+    addItem: TRUE,
+    readSpan: TRUE,
+    stopUsingTranscript: TRUE,
+    deleteVatTranscripts: TRUE,
+  });
 
-  const snapStorePublic = {
-    loadSnapshot: snapStore.loadSnapshot,
-    saveSnapshot: snapStore.saveSnapshot,
-    deleteAllUnusedSnapshots: snapStore.deleteAllUnusedSnapshots,
-    deleteVatSnapshots: snapStore.deleteVatSnapshots,
-    stopUsingLastSnapshot: snapStore.stopUsingLastSnapshot,
-    getSnapshotInfo: snapStore.getSnapshotInfo,
-  };
+  const snapStore = attenuate(snapStoreInternal, {
+    loadSnapshot: TRUE,
+    saveSnapshot: TRUE,
+    deleteAllUnusedSnapshots: TRUE,
+    deleteVatSnapshots: TRUE,
+    stopUsingLastSnapshot: TRUE,
+    getSnapshotInfo: TRUE,
+  });
 
-  const bundleStorePublic = {
-    addBundle: bundleStore.addBundle,
-    hasBundle: bundleStore.hasBundle,
-    getBundle: bundleStore.getBundle,
-    deleteBundle: bundleStore.deleteBundle,
-  };
+  const bundleStore = attenuate(bundleStoreInternal, {
+    addBundle: TRUE,
+    hasBundle: TRUE,
+    getBundle: TRUE,
+    deleteBundle: TRUE,
+  });
 
   const kernelStorage = {
     kvStore: kernelKVStore,
-    transcriptStore: transcriptStorePublic,
-    snapStore: snapStorePublic,
-    bundleStore: bundleStorePublic,
+    transcriptStore,
+    snapStore,
+    bundleStore,
     startCrank,
     establishCrankSavepoint,
     rollbackCrank,
@@ -610,43 +627,40 @@ export function makeSwingStore(dirPath, forceReset, options = {}) {
 }
 
 /**
- * Create a new swingset store.  If given a directory path string, a persistent
- * store will be created in that directory; if there is already a store there,
- * it will be reinitialized to an empty state.  If the path is null or
- * undefined, a memory-only ephemeral store will be created that will evaporate
- * on program exit.
- *
- * @param {string|null} dirPath Path to a directory in which database files may
- *   be kept.  This directory need not actually exist yet (if it doesn't it will
- *   be created) but it is reserved (by the caller) for the exclusive use of
- *   this swing store instance.  If null, an ephemeral (memory only) store will
- *   be created.
- * @param {object?} options  Optional configuration options
+ * Create a new swingset store at the given `path`, overwriting any prior store
+ * there.
  *
+ * @param {string|null} [path] Path to a directory in which database files may
+ *   be kept (or when the `asFile` option is true, the path to such a database
+ *   file).  This directory or file need not actually exist yet (if it doesn't
+ *   it will be created) but it is reserved (by the caller) for the exclusive
+ *   use of this swing store instance.  If null, an ephemeral (memory only)
+ *   store will be created.
+ * @param {SwingStoreOptions} [options]
  * @returns {SwingStore}
  */
-export function initSwingStore(dirPath = null, options = {}) {
-  if (dirPath) {
-    typeof dirPath === 'string' || Fail`dirPath must be a string`;
+export function initSwingStore(path = null, options = {}) {
+  if (path) {
+    typeof path === 'string' || Fail`path must be a string`;
   }
-  return makeSwingStore(dirPath, true, options);
+  return makeSwingStore(path, true, options);
 }
 
 /**
  * Open a persistent swingset store.  If there is no existing store at the given
- * `dirPath`, a new, empty store will be created.
- *
- * @param {string} dirPath  Path to a directory in which database files may be kept.
- *   This directory need not actually exist yet (if it doesn't it will be
- *   created) but it is reserved (by the caller) for the exclusive use of this
- *   swing store instance.
- * @param {object?} options  Optional configuration options
+ * `path`, a new, empty store will be created.
  *
+ * @param {string} path  Path to a directory in which database files may be kept
+ *   (or when the `asFile` option is true, the path to such a database file).
+ *   This directory or file need not actually exist yet (if it doesn't it will
+ *   be created) but it is reserved (by the caller) for the exclusive use of
+ *   this swing store instance.
+ * @param {SwingStoreOptions} [options]
  * @returns {SwingStore}
  */
-export function openSwingStore(dirPath, options = {}) {
-  typeof dirPath === 'string' || Fail`dirPath must be a string`;
-  return makeSwingStore(dirPath, false, options);
+export function openSwingStore(path, options = {}) {
+  typeof path === 'string' || Fail`path must be a string`;
+  return makeSwingStore(path, false, options);
 }
 
 /**

package/src/transcriptStore.js

@@ -6,13 +6,11 @@ import BufferLineTransform from '@agoric/internal/src/node/buffer-line-transform
 import { createSHA256 } from './hasher.js';
 
 /**
- * @template T
- *  @typedef  { IterableIterator<T> | AsyncIterableIterator<T> } AnyIterableIterator<T>
+ * @import { AnyIterable } from './exporter.js';
+ * @import { ArtifactMode } from './internal.js';
  */
 
 /**
- * @typedef { import('./internal.js').ArtifactMode } ArtifactMode
- *
  * @typedef {{
  *   initTranscript: (vatID: string) => void,
  *   rolloverSpan: (vatID: string) => Promise<number>,
@@ -29,7 +27,7 @@ import { createSHA256 } from './hasher.js';
  *   getExportRecords: (includeHistorical: boolean) => IterableIterator<readonly [key: string, value: string]>,
  *   getArtifactNames: (artifactMode: ArtifactMode) => AsyncIterableIterator<string>,
  *   importTranscriptSpanRecord: (key: string, value: string) => void,
- *   populateTranscriptSpan: (name: string, makeChunkIterator: () => AnyIterableIterator<Uint8Array>, options: { artifactMode: ArtifactMode }) => Promise<void>,
+ *   populateTranscriptSpan: (name: string, makeChunkIterator: () => AnyIterable<Uint8Array>, options: { artifactMode: ArtifactMode }) => Promise<void>,
  *   assertComplete: (checkMode: Omit<ArtifactMode, 'debug'>) => void,
  *   repairTranscriptSpanRecord: (key: string, value: string) => void,
  *   readFullVatTranscript: (vatID: string) => Iterable<{position: number, item: string}>
@@ -39,6 +37,11 @@ import { createSHA256 } from './hasher.js';
  *   dumpTranscripts: (includeHistorical?: boolean) => {[vatID: string]: {[position: number]: string}}
  * }} TranscriptStoreDebug
  *
+ * @callback TranscriptCallback
+ * Called with the entries of a newly-finalized transcript span.
+ * @param {string} spanName  e.g., `transcript.${vatID}.${startPos}.${endPos}`
+ * @param {AnyIterable<Uint8Array>} entries  as from `exportSpan`
+ * @returns {Promise<void>}
  */
 
 function* empty() {
@@ -62,7 +65,7 @@ function insistTranscriptPosition(position) {
  * @param {(key: string, value: string | undefined ) => void} noteExport
  * @param {object} [options]
  * @param {boolean} [options.keepTranscripts]
- * @param {(spanName: string, entries: ReturnType<exportSpan>) => Promise<void>} [options.archiveTranscript]
+ * @param {TranscriptCallback} [options.archiveTranscript]
  * @returns { TranscriptStore & TranscriptStoreInternal & TranscriptStoreDebug }
  */
 export function makeTranscriptStore(
@@ -775,7 +778,7 @@ export function makeTranscriptStore(
    * Import a transcript span from another store.
    *
    * @param {string} name  Artifact Name of the transcript span
-   * @param {() => AnyIterableIterator<Uint8Array>} makeChunkIterator  get an iterator of transcript byte chunks
+   * @param {() => AnyIterable<Uint8Array>} makeChunkIterator  get an iterator of transcript byte chunks
    * @param {object} options
    * @param {ArtifactMode} options.artifactMode
    *