@agoric/swing-store 0.9.1 → 0.9.2-calypso-dev-84eb287.0

package/src/bundleStore.js

@@ -7,7 +7,6 @@ import { checkBundle } from '@endo/check-bundle/lite.js';
 import { Nat } from '@endo/nat';
 import { Fail, q } from '@agoric/assert';
 import { createSHA256 } from './hasher.js';
-import { buffer } from './util.js';
 
 /**
  * @typedef { { moduleFormat: 'getExport', source: string, sourceMap?: string } } GetExportBundle
@@ -16,7 +15,8 @@ import { buffer } from './util.js';
  * @typedef { EndoZipBase64Bundle | GetExportBundle | NestedEvaluateBundle } Bundle
  */
 /**
- * @typedef { import('./swingStore').SwingStoreExporter } SwingStoreExporter
+ * @typedef { import('./exporter.js').SwingStoreExporter } SwingStoreExporter
+ * @typedef { import('./internal.js').ArtifactMode } ArtifactMode
  *
  * @typedef {{
  *   addBundle: (bundleID: string, bundle: Bundle) => void;
@@ -27,7 +27,10 @@ import { buffer } from './util.js';
  *
  * @typedef {{
  *   exportBundle: (name: string) => AsyncIterableIterator<Uint8Array>,
- *   importBundle: (artifactName: string, exporter: SwingStoreExporter, bundleID: string) => void,
+ *   repairBundleRecord: (key: string, value: string) => void,
+ *   importBundleRecord: (key: string, value: string) => void,
+ *   importBundle: (name: string, dataProvider: () => Promise<Buffer>) => Promise<void>,
+ *   assertComplete: (checkMode: Omit<ArtifactMode, 'debug'>) => void,
  *   getExportRecords: () => IterableIterator<readonly [key: string, value: string]>,
  *   getArtifactNames: () => AsyncIterableIterator<string>,
  *   getBundleIDs: () => IterableIterator<string>,
@@ -39,6 +42,18 @@ import { buffer } from './util.js';
  *
  */
 
+function bundleIDFromName(name) {
+  typeof name === 'string' || Fail`artifact name must be a string`;
+  const [tag, ...pieces] = name.split('.');
+  if (tag !== 'bundle' || pieces.length !== 1) {
+    Fail`expected artifact name of the form 'bundle.{bundleID}', saw ${q(
+      name,
+    )}`;
+  }
+  const bundleID = pieces[0];
+  return bundleID;
+}
+
 /**
  * @param {*} db
  * @param {() => void} ensureTxn
@@ -54,6 +69,9 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     )
   `);
 
+  // A populated record contains both bundleID and bundle, while a
+  // pruned record has a bundle of NULL.
+
   function bundleArtifactName(bundleID) {
     return `bundle.${bundleID}`;
   }
@@ -62,20 +80,36 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     return `b${Nat(version)}-${hash}`;
   }
 
-  const sqlAddBundle = db.prepare(`
-    INSERT OR REPLACE INTO bundles
-      (bundleID, bundle)
-    VALUES (?, ?)
+  // the PRIMARY KEY constraint requires the bundleID not already
+  // exist
+  const sqlAddBundleRecord = db.prepare(`
+    INSERT INTO bundles (bundleID, bundle) VALUES (?, NULL)
   `);
 
-  /**
-   * Store a bundle.  Here the bundle itself is presumed valid.
-   *
-   * @param {string} bundleID
-   * @param {Bundle} bundle
-   */
-  function addBundle(bundleID, bundle) {
+  // this sees both populated and pruned (not-yet-populated) records
+  const sqlHasBundleRecord = db.prepare(`
+    SELECT count(*)
+    FROM bundles
+    WHERE bundleID = ?
+  `);
+  sqlHasBundleRecord.pluck();
+
+  const sqlPopulateBundleRecord = db.prepare(`
+    UPDATE bundles SET bundle = $serialized WHERE bundleID = $bundleID
+  `);
+
+  function addBundleRecord(bundleID) {
+    ensureTxn();
+    sqlAddBundleRecord.run(bundleID);
+  }
+
+  function populateBundle(bundleID, serialized) {
     ensureTxn();
+    sqlHasBundleRecord.get(bundleID) || Fail`missing ${bundleID}`;
+    sqlPopulateBundleRecord.run({ bundleID, serialized });
+  }
+
+  function serializeBundle(bundleID, bundle) {
     const { moduleFormat } = bundle;
     let serialized;
     if (bundleID.startsWith('b0-')) {
@@ -98,19 +132,55 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     } else {
       throw Fail`unsupported BundleID ${bundleID}`;
     }
-    sqlAddBundle.run(bundleID, serialized);
+    return serialized;
+  }
+
+  /**
+   * Store a complete bundle in a single operation, used by runtime
+   * (i.e. not an import). We rely upon the caller to provide a
+   * correct bundle (e.g. no unexpected properties), but we still
+   * check the ID against the contents.
+   *
+   * @param {string} bundleID
+   * @param {Bundle} bundle
+   */
+  function addBundle(bundleID, bundle) {
+    const serialized = serializeBundle(bundleID, bundle);
+    addBundleRecord(bundleID);
+    populateBundle(bundleID, serialized);
     noteExport(bundleArtifactName(bundleID), bundleID);
   }
 
-  const sqlHasBundle = db.prepare(`
+  const sqlGetPrunedBundles = db.prepare(`
+    SELECT bundleID
+    FROM bundles
+    WHERE bundle IS NULL
+    ORDER BY bundleID
+  `);
+  sqlGetPrunedBundles.pluck();
+
+  function getPrunedBundles() {
+    return sqlGetPrunedBundles.all();
+  }
+
+  function assertComplete(checkMode) {
+    assert(checkMode !== 'debug', checkMode);
+    const pruned = getPrunedBundles();
+    if (pruned.length) {
+      throw Fail`missing bundles for: ${pruned.join(',')}`;
+    }
+  }
+
+  const sqlHasPopulatedBundle = db.prepare(`
     SELECT count(*)
     FROM bundles
     WHERE bundleID = ?
+    AND bundle IS NOT NULL
   `);
-  sqlHasBundle.pluck(true);
+  sqlHasPopulatedBundle.pluck(true);
 
   function hasBundle(bundleID) {
-    const count = sqlHasBundle.get(bundleID);
+    const count = sqlHasPopulatedBundle.get(bundleID);
     return count !== 0;
   }
 
@@ -119,15 +189,15 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     FROM bundles
     WHERE bundleID = ?
   `);
-  sqlGetBundle.pluck(true);
 
   /**
    * @param {string} bundleID
    * @returns {Bundle}
    */
   function getBundle(bundleID) {
-    const rawBundle = sqlGetBundle.get(bundleID);
-    rawBundle || Fail`bundle ${q(bundleID)} not found`;
+    const row =
+      sqlGetBundle.get(bundleID) || Fail`bundle ${q(bundleID)} not found`;
+    const rawBundle = row.bundle || Fail`bundle ${q(bundleID)} pruned`;
     if (bundleID.startsWith('b0-')) {
       return harden(JSON.parse(rawBundle));
     } else if (bundleID.startsWith('b1-')) {
@@ -153,6 +223,31 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     }
   }
 
+  // take an export-data record (id/hash but not bundle contents) and
+  // insert something in the DB
+  function importBundleRecord(key, value) {
+    const bundleID = bundleIDFromName(key);
+    assert.equal(bundleID, value);
+    addBundleRecord(bundleID);
+  }
+
+  function repairBundleRecord(key, value) {
+    // Bundle records have no metadata, and all bundles must be
+    // present (there's no notion of "historical bundle"). So there's
+    // no "repair", and if the repair process supplies a bundle record
+    // that isn't already present, we throw an error. The repair
+    // process doesn't get artifacts, so adding a new record here
+    // would fail the subsequent completeness check anyways.
+
+    const bundleID = bundleIDFromName(key);
+    assert.equal(bundleID, value);
+    if (sqlHasBundleRecord.get(bundleID)) {
+      // record is present, there's no metadata to mismatch, so ignore quietly
+      return;
+    }
+    throw Fail`unexpected new bundle record for ${bundleID} during repair`;
+  }
+
   /**
    * Read a bundle and return it as a stream of data suitable for export to
    * another store.
@@ -166,16 +261,13 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
    * @returns {AsyncIterableIterator<Uint8Array>}
    */
   async function* exportBundle(name) {
-    typeof name === 'string' || Fail`artifact name must be a string`;
-    const parts = name.split('.');
-    const [type, bundleID] = parts;
-    // prettier-ignore
-    (parts.length === 2 && type === 'bundle') ||
-      Fail`expected artifact name of the form 'bundle.{bundleID}', saw ${q(name)}`;
-    const rawBundle = sqlGetBundle.get(bundleID);
-    rawBundle || Fail`bundle ${q(name)} not available`;
+    const bundleID = bundleIDFromName(name);
+    const row =
+      sqlGetBundle.get(bundleID) || Fail`bundle ${q(bundleID)} not found`;
+    const rawBundle = row.bundle || Fail`bundle ${q(bundleID)} pruned`;
     yield* Readable.from(Buffer.from(rawBundle));
   }
+  harden(exportBundle);
 
   const sqlGetBundleIDs = db.prepare(`
     SELECT bundleID
@@ -195,12 +287,14 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
       yield [bundleArtifactName(bundleID), bundleID];
     }
   }
+  harden(getExportRecords);
 
   async function* getArtifactNames() {
     for (const bundleID of sqlGetBundleIDs.iterate()) {
       yield bundleArtifactName(bundleID);
     }
   }
+  harden(getArtifactNames);
 
   function computeSha512(bytes) {
     const hash = createHash('sha512');
@@ -209,23 +303,17 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
   }
 
   /**
-   * @param {string} name  Artifact name of the bundle
-   * @param {SwingStoreExporter} exporter  Whence to get the bits
-   * @param {string} bundleID  Bundle ID of the bundle
+   * Call addBundleRecord() first, then this importBundle() will
+   * populate the record.
+   *
+   * @param {string} name  Artifact name, `bundle.${bundleID}`
+   * @param {() => Promise<Buffer>} dataProvider  Function to get bundle bytes
    * @returns {Promise<void>}
    */
-  async function importBundle(name, exporter, bundleID) {
+  async function importBundle(name, dataProvider) {
     await 0; // no synchronous prefix
-    const parts = name.split('.');
-    const [type, bundleIDkey] = parts;
-    // prettier-ignore
-    parts.length === 2 && type === 'bundle' ||
-      Fail`expected artifact name of the form 'bundle.{bundleID}', saw '${q(name)}'`;
-    bundleIDkey === bundleID ||
-      Fail`bundle artifact name ${name} doesn't match bundleID ${bundleID}`;
-    const artifactChunks = exporter.getArtifact(name);
-    const inStream = Readable.from(artifactChunks);
-    const data = await buffer(inStream);
+    const bundleID = bundleIDFromName(name);
+    const data = await dataProvider();
     if (bundleID.startsWith('b0-')) {
       // we dissect and reassemble the bundle, to exclude unexpected properties
       const { moduleFormat, source, sourceMap } = JSON.parse(data.toString());
@@ -234,7 +322,7 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
       const serialized = JSON.stringify(bundle);
       bundleID === bundleIdFromHash(0, createSHA256(serialized).finish()) ||
         Fail`bundleID ${q(bundleID)} does not match bundle artifact`;
-      addBundle(bundleID, bundle);
+      populateBundle(bundleID, serialized);
     } else if (bundleID.startsWith('b1-')) {
       /** @type {EndoZipBase64Bundle} */
       const bundle = harden({
@@ -243,9 +331,8 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
         endoZipBase64: encodeBase64(data),
       });
       // Assert that the bundle contents match the ID and hash
-      // eslint-disable-next-line @jessie.js/no-nested-await
       await checkBundle(bundle, computeSha512, bundleID);
-      addBundle(bundleID, bundle);
+      populateBundle(bundleID, serializeBundle(bundleID, bundle));
     } else {
       Fail`unsupported BundleID ${q(bundleID)}`;
     }
@@ -265,7 +352,7 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
     const dump = {};
     for (const row of sql.iterate()) {
       const { bundleID, bundle } = row;
-      dump[bundleID] = encodeBase64(bundle);
+      dump[bundleID] = encodeBase64(Buffer.from(bundle, 'utf-8'));
     }
     return dump;
   }
@@ -280,17 +367,23 @@ export function makeBundleStore(db, ensureTxn, noteExport = () => {}) {
   function* getBundleIDs() {
     yield* sqlListBundleIDs.iterate();
   }
+  harden(getBundleIDs);
 
   return harden({
+    importBundleRecord,
+    importBundle,
+    assertComplete,
+
     addBundle,
     hasBundle,
     getBundle,
     deleteBundle,
+
     getExportRecords,
     getArtifactNames,
     exportBundle,
-    importBundle,
     getBundleIDs,
+    repairBundleRecord,
 
     dumpBundles,
   });

package/src/exporter.js

@@ -0,0 +1,221 @@
+import sqlite3 from 'better-sqlite3';
+
+import { Fail, q } from '@agoric/assert';
+
+import { dbFileInDirectory } from './util.js';
+import { getKeyType } from './kvStore.js';
+import { makeBundleStore } from './bundleStore.js';
+import { makeSnapStore } from './snapStore.js';
+import { makeSnapStoreIO } from './snapStoreIO.js';
+import { makeTranscriptStore } from './transcriptStore.js';
+import { assertComplete } from './assertComplete.js';
+import { validateArtifactMode } from './internal.js';
+
+/**
+ * @template T
+ * @typedef  { Iterable<T> | AsyncIterable<T> } AnyIterable
+ */
+/**
+ * @template T
+ * @typedef  { IterableIterator<T> | AsyncIterableIterator<T> } AnyIterableIterator
+ */
+
+/**
+ *
+ * @typedef {readonly [
+ *   key: string,
+ *   value?: string | null | undefined,
+ * ]} KVPair
+ *
+ * @typedef {object} SwingStoreExporter
+ *
+ * Allows export of data from a swingStore as a fixed view onto the content as
+ * of the most recent commit point at the time the exporter was created.  The
+ * exporter may be used while another SwingStore instance is active for the same
+ * DB, possibly in another thread or process.  It guarantees that regardless of
+ * the concurrent activity of other swingStore instances, the data representing
+ * the commit point will stay consistent and available.
+ *
+ * @property {(key: string) => string | undefined} getHostKV
+ *
+ * Retrieve a value from the "host" portion of the kvStore, just like
+ * hostStorage.hostKVStore.get() would do.
+ *
+ * @property {() => AnyIterableIterator<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
+ * and local prefixes), as well as any data needed to validate all artifacts,
+ * both current and historical. As such it represents the root of trust for the
+ * application.
+ *
+ * Content of validation data (with supporting entries for indexing):
+ * - kv.${key} = ${value}  // ordinary kvStore data entry
+ * - snapshot.${vatID}.${snapPos} = ${{ vatID, snapPos, hash }};
+ * - snapshot.${vatID}.current = `snapshot.${vatID}.${snapPos}`
+ * - transcript.${vatID}.${startPos} = ${{ vatID, startPos, endPos, hash }}
+ * - transcript.${vatID}.current = ${{ vatID, startPos, endPos, hash }}
+ *
+ * @property {() => AnyIterableIterator<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
+ * exporter instance will succeed.  The `artifactMode` option to
+ * `makeSwingStoreExporter` controls the filtering of the artifact names
+ * yielded.
+ *
+ * Artifact names:
+ * - transcript.${vatID}.${startPos}.${endPos}
+ * - snapshot.${vatID}.${snapPos}
+ * - bundle.${bundleID}
+ *
+ * @property {(name: string) => AnyIterableIterator<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
+ * and wasn't preserved.
+ *
+ * @property {() => Promise<void>} close
+ *
+ * Dispose of all resources held by this exporter. Any further operation on this
+ * exporter or its outstanding iterators will fail.
+ */
+
+/**
+ * @typedef { object } ExportSwingStoreOptions
+ * @property { import('./internal.js').ArtifactMode } [artifactMode]  What artifacts should/must the exporter provide?
+ */
+
+/**
+ * @param {string} dirPath
+ * @param { ExportSwingStoreOptions } [options]
+ * @returns {SwingStoreExporter}
+ */
+export function makeSwingStoreExporter(dirPath, options = {}) {
+  typeof dirPath === 'string' || Fail`dirPath must be a string`;
+  const { artifactMode = 'operational' } = options;
+  validateArtifactMode(artifactMode);
+
+  const filePath = dbFileInDirectory(dirPath);
+  const db = sqlite3(filePath);
+
+  // Execute the data export in a (read) transaction, to ensure that we are
+  // capturing the state of the database at a single point in time. Our close()
+  // will ROLLBACK the txn just in case some bug tried to change the DB.
+  const sqlBeginTransaction = db.prepare('BEGIN TRANSACTION');
+  sqlBeginTransaction.run();
+
+  // ensureTxn can be a dummy, we just started one
+  const ensureTxn = () => {};
+  const snapStore = makeSnapStore(db, ensureTxn, makeSnapStoreIO());
+  const bundleStore = makeBundleStore(db, ensureTxn);
+  const transcriptStore = makeTranscriptStore(db, ensureTxn, () => {});
+
+  const sqlKVGet = db.prepare(`
+    SELECT value
+    FROM kvStore
+    WHERE key = ?
+  `);
+  sqlKVGet.pluck(true);
+
+  /**
+   * Obtain the value stored for a given host key. This is for the
+   * benefit of clients who need to briefly query the DB to ensure
+   * they are exporting the right thing, and need to avoid modifying
+   * anything (or creating a read-write DB lock) in the process.
+   *
+   * @param {string} key  The key whose value is sought.
+   *
+   * @returns {string | undefined} the (string) value for the given key, or
+   *    undefined if there is no such value.
+   *
+   * @throws if key is not a string, or the key is not in the host
+   * section
+   */
+  function getHostKV(key) {
+    typeof key === 'string' || Fail`key must be a string`;
+    getKeyType(key) === 'host' || Fail`getHostKV requires host keys`;
+    // @ts-expect-error unknown
+    return sqlKVGet.get(key);
+  }
+
+  /** @type {any} */
+  const sqlGetAllKVData = db.prepare(`
+    SELECT key, value
+    FROM kvStore
+    ORDER BY key
+  `);
+
+  /**
+   * @returns {AsyncIterableIterator<KVPair>}
+   * @yields {KVPair}
+   */
+  async function* getExportData() {
+    for (const { key, value } of sqlGetAllKVData.iterate()) {
+      if (getKeyType(key) === 'consensus') {
+        yield [`kv.${key}`, value];
+      }
+    }
+    yield* snapStore.getExportRecords(true);
+    yield* transcriptStore.getExportRecords(true);
+    yield* bundleStore.getExportRecords();
+  }
+  harden(getExportData);
+
+  /** @yields {string} */
+  async function* artifactNames() {
+    yield* snapStore.getArtifactNames(artifactMode);
+    yield* transcriptStore.getArtifactNames(artifactMode);
+    yield* bundleStore.getArtifactNames();
+  }
+  harden(artifactNames);
+
+  /**
+   * @returns {AsyncIterableIterator<string>}
+   */
+  function getArtifactNames() {
+    if (artifactMode !== 'debug') {
+      // throw if this DB will not be able to yield all the desired artifacts
+      const internal = { snapStore, bundleStore, transcriptStore };
+      assertComplete(internal, artifactMode);
+    }
+    return artifactNames();
+  }
+
+  /**
+   * @param {string} name
+   * @returns {AsyncIterableIterator<Uint8Array>}
+   */
+  function getArtifact(name) {
+    typeof name === 'string' || Fail`artifact name must be a string`;
+    const [type] = name.split('.', 1);
+
+    if (type === 'snapshot') {
+      return snapStore.exportSnapshot(name);
+    } else if (type === 'transcript') {
+      return transcriptStore.exportSpan(name);
+    } else if (type === 'bundle') {
+      return bundleStore.exportBundle(name);
+    } else {
+      throw Fail`invalid type in artifact name ${q(name)}`;
+    }
+  }
+
+  const sqlAbort = db.prepare('ROLLBACK');
+
+  async function close() {
+    // After all the data has been extracted, always abort the export
+    // transaction to ensure that the export was read-only (i.e., that no bugs
+    // inadvertantly modified the database).
+    sqlAbort.run();
+    db.close();
+  }
+
+  return harden({
+    getHostKV,
+    getExportData,
+    getArtifactNames,
+    getArtifact,
+    close,
+  });
+}

package/src/importer.js

@@ -0,0 +1,133 @@
+import { Fail, q } from '@agoric/assert';
+
+import { makeSwingStore } from './swingStore.js';
+import { buffer } from './util.js';
+import { validateArtifactMode } from './internal.js';
+import { assertComplete } from './assertComplete.js';
+
+/**
+ * @typedef { object } ImportSwingStoreOptions
+ * @property { import('./internal.js').ArtifactMode } [artifactMode]  What artifacts should the importer use and require?
+ */
+
+/**
+ * Function used to populate a swingStore from an object implementing the
+ * exporter API. The exporter API may be provided by a swingStore instance, or
+ * implemented by a host to restore data that was previously exported. The
+ * returned swingStore is not suitable for execution, and thus only contains
+ * the host facet for committing the populated swingStore.
+ *
+ * @param {import('./exporter.js').SwingStoreExporter} exporter
+ * @param {string | null} [dirPath]
+ * @param {ImportSwingStoreOptions} [options]
+ * @returns {Promise<Pick<import('./swingStore.js').SwingStore, 'hostStorage' | 'debug'>>}
+ */
+export async function importSwingStore(exporter, dirPath = null, options = {}) {
+  if (dirPath && typeof dirPath !== 'string') {
+    Fail`dirPath must be a string`;
+  }
+  const { artifactMode = 'operational', ...makeSwingStoreOptions } = options;
+  validateArtifactMode(artifactMode);
+
+  const { hostStorage, kernelStorage, internal, debug } = makeSwingStore(
+    dirPath,
+    true,
+    {
+      unsafeFastMode: true,
+      ...makeSwingStoreOptions,
+    },
+  );
+
+  // For every exportData entry, we add a DB record. 'kv' entries are
+  // the "kvStore shadow table", and are not associated with any
+  // artifacts. All other entries are associated with an artifact,
+  // however the import may or may not contain that artifact (the
+  // dataset can be incomplete: either the original DB was pruned at
+  // some point, or the exporter did not choose to include
+  // everything). The DB records we add are marked as incomplete (as
+  // if they had been pruned locally), and can be populated later when
+  // the artifact is retrieved.
+
+  // While unlikely, the getExportData() protocol *is* allowed to
+  // deliver multiple values for the same key (last one wins), or use
+  // 'null' to delete a previously-defined key. So our first pass both
+  // installs the kvStore shadow records, and de-dups/deletes the
+  // metadata records into this Map.
+
+  const allMetadata = new Map();
+
+  for await (const [key, value] of exporter.getExportData()) {
+    const [tag] = key.split('.', 1);
+    if (tag === 'kv') {
+      // 'kv' keys contain individual kvStore entries
+      const subKey = key.substring(tag.length + 1);
+      if (value == null) {
+        // Note '==' rather than '===': any nullish value implies deletion
+        kernelStorage.kvStore.delete(subKey);
+      } else {
+        kernelStorage.kvStore.set(subKey, value);
+      }
+    } else if (value == null) {
+      allMetadata.delete(key);
+    } else {
+      allMetadata.set(key, value);
+    }
+  }
+
+  // Now take each metadata record and install the stub/pruned entry
+  // into the DB.
+
+  for (const [key, value] of allMetadata.entries()) {
+    const [tag] = key.split('.', 1);
+    if (tag === 'bundle') {
+      internal.bundleStore.importBundleRecord(key, value);
+    } else if (tag === 'snapshot') {
+      internal.snapStore.importSnapshotRecord(key, value);
+    } else if (tag === 'transcript') {
+      internal.transcriptStore.importTranscriptSpanRecord(key, value);
+    } else {
+      Fail`unknown export-data type ${q(tag)} on import`;
+    }
+  }
+
+  // All the metadata is now installed, and we're prepared for
+  // artifacts. We walk `getArtifactNames()` and offer each one to the
+  // submodule, which may ignore it according to `artifactMode`, but
+  // otherwise validates and accepts it. This is an initial import, so
+  // we don't need to check if we already have the data, but the
+  // submodule function is free to do such checks.
+
+  for await (const name of exporter.getArtifactNames()) {
+    const makeChunkIterator = () => exporter.getArtifact(name);
+    const dataProvider = async () => buffer(makeChunkIterator());
+    const [tag] = name.split('.', 1);
+    // TODO: pass the same args to all artifact importers, and let
+    // stores register their functions by
+    // 'type'. https://github.com/Agoric/agoric-sdk/pull/8075#discussion_r1285265453
+    if (tag === 'bundle') {
+      await internal.bundleStore.importBundle(name, dataProvider);
+    } else if (tag === 'snapshot') {
+      await internal.snapStore.populateSnapshot(name, makeChunkIterator, {
+        artifactMode,
+      });
+    } else if (tag === 'transcript') {
+      await internal.transcriptStore.populateTranscriptSpan(
+        name,
+        makeChunkIterator,
+        { artifactMode },
+      );
+    } else {
+      Fail`unknown artifact type ${q(tag)} on import`;
+    }
+  }
+
+  // We've installed all the artifacts that we could, now do a
+  // completeness check. Enforce at least 'operational' completeness,
+  // even if the given mode was 'debug'.
+
+  const checkMode = artifactMode === 'debug' ? 'operational' : artifactMode;
+  assertComplete(internal, checkMode);
+
+  await exporter.close();
+  return { hostStorage, debug };
+}