@agoric/swing-store 0.9.2-dev-7bfadd3.0 → 0.9.2-dev-f2445bc.0

package/src/transcriptStore.js

@@ -11,6 +11,8 @@ import { createSHA256 } from './hasher.js';
  */
 
 /**
+ * @typedef { import('./internal.js').ArtifactMode } ArtifactMode
+ *
  * @typedef {{
  *   initTranscript: (vatID: string) => void,
  *   rolloverSpan: (vatID: string) => number,
@@ -24,10 +26,10 @@ import { createSHA256 } from './hasher.js';
  * @typedef {{
  *   exportSpan: (name: string) => AsyncIterableIterator<Uint8Array>
  *   getExportRecords: (includeHistorical: boolean) => IterableIterator<readonly [key: string, value: string]>,
- *   getArtifactNames: (includeHistorical: boolean) => AsyncIterableIterator<string>,
+ *   getArtifactNames: (artifactMode: ArtifactMode) => AsyncIterableIterator<string>,
  *   importTranscriptSpanRecord: (key: string, value: string) => void,
- *   populateTranscriptSpan: (name: string, makeChunkIterator: () => AnyIterableIterator<Uint8Array>, options: { includeHistorical: boolean }) => Promise<void>,
- *   assertComplete: (level: 'operational') => void,
+ *   populateTranscriptSpan: (name: string, makeChunkIterator: () => AnyIterableIterator<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}>
  * }} TranscriptStoreInternal
@@ -331,6 +333,13 @@ export function makeTranscriptStore(
     ORDER BY vatID, startPos
   `);
 
+  const sqlGetIncarnationSpanMetadata = db.prepare(`
+    SELECT vatID, startPos, endPos, hash, isCurrent, incarnation
+    FROM transcriptSpans
+    WHERE vatID=? AND incarnation=?
+    ORDER BY vatID, startPos
+  `);
+
   const sqlGetCurrentSpanMetadata = db.prepare(`
     SELECT vatID, startPos, endPos, hash, isCurrent, incarnation
     FROM transcriptSpans
@@ -338,6 +347,11 @@ export function makeTranscriptStore(
     ORDER BY vatID, startPos
   `);
 
+  function dbRecToExportRec(dbRec) {
+    const { vatID, startPos, endPos, hash, isCurrent, incarnation } = dbRec;
+    return spanRec(vatID, startPos, endPos, hash, isCurrent, incarnation);
+  }
+
   /**
    * Obtain artifact metadata records for spans contained in this store.
    *
@@ -360,63 +374,77 @@ export function makeTranscriptStore(
    * replay will never be required or because such replay would be prohibitively
    * expensive regardless of need and therefor other repair strategies employed.
    *
+   * The only code path which could use 'false' would be `swingstore.dump()`,
+   * which takes the same flag.
+   *
    * @yields {readonly [key: string, value: string]}
    * @returns {IterableIterator<readonly [key: string, value: string]>}
    *    An iterator over pairs of [spanMetadataKey, rec], where `rec` is a
    *    JSON-encoded metadata record for the span named by `spanMetadataKey`.
    */
   function* getExportRecords(includeHistorical = true) {
-    const sql = includeHistorical
-      ? sqlGetAllSpanMetadata
-      : sqlGetCurrentSpanMetadata;
-    for (const rec of sql.iterate()) {
-      const { vatID, startPos, endPos, hash, isCurrent, incarnation } = rec;
-      const exportRec = spanRec(
-        vatID,
-        startPos,
-        endPos,
-        hash,
-        isCurrent,
-        incarnation,
-      );
-      yield [spanMetadataKey(rec), JSON.stringify(exportRec)];
+    if (includeHistorical) {
+      for (const rec of sqlGetAllSpanMetadata.iterate()) {
+        yield [spanMetadataKey(rec), JSON.stringify(dbRecToExportRec(rec))];
+      }
+    } else {
+      for (const rec of sqlGetCurrentSpanMetadata.iterate()) {
+        yield [spanMetadataKey(rec), JSON.stringify(dbRecToExportRec(rec))];
+      }
     }
   }
 
-  // 'position' is not recycled across incarnations, so strictly
-  // speaking this query doesn't need to filter on 'incarnation = ?',
-  // but this will catch problems like items with incorrect or missing
-  // incarnation values
-
-  const sqlCountPopulatedSpanItems = db.prepare(`
+  const sqlCountSpanItems = db.prepare(`
     SELECT COUNT(*) FROM transcriptItems
-      WHERE vatID = ? AND incarnation = ? AND position >= ? AND position < ?
+      WHERE vatID = ? AND position >= ? AND position < ?
   `);
-  sqlCountPopulatedSpanItems.pluck();
+  sqlCountSpanItems.pluck();
 
   /**
    * Obtain artifact names for spans contained in this store.
    *
-   * @param {boolean} includeHistorical If true, include all spans that are
-   * present in the store regardless of their currency; if false, only include
-   * the current span for each vat.
-   *
+   * @param {ArtifactMode} artifactMode Control which artifacts should be exported.
+   *   At 'operational', only include current spans. At 'replay',
+   *   include all spans of the current incarnation for each vat. At
+   *   'archival' and 'debug', include all spans.
    * @yields {string}
    * @returns {AsyncIterableIterator<string>}  An iterator over the names of all the artifacts requested
    */
-  async function* getArtifactNames(includeHistorical) {
-    const sql = includeHistorical
-      ? sqlGetAllSpanMetadata
-      : sqlGetCurrentSpanMetadata;
-    for (const rec of sql.iterate()) {
-      const { vatID, incarnation, startPos, endPos } = rec;
-      if (
-        !sqlCountPopulatedSpanItems.get(vatID, incarnation, startPos, endPos)
-      ) {
-        continue;
+  async function* getArtifactNames(artifactMode) {
+    // for all non-'debug' modes, the exporter asserts that all
+    // requested items are present (i.e. the artifacts will be
+    // complete), so we don't need to check that ourselves
+    if (artifactMode === 'operational') {
+      for (const rec of sqlGetCurrentSpanMetadata.iterate()) {
+        yield spanArtifactName(rec);
+      }
+    } else if (artifactMode === 'replay') {
+      for (const curRec of sqlGetCurrentSpanMetadata.iterate()) {
+        const { vatID, incarnation } = curRec;
+        for (const rec of sqlGetIncarnationSpanMetadata.iterate(
+          vatID,
+          incarnation,
+        )) {
+          yield spanArtifactName(rec);
+        }
+      }
+    } else if (artifactMode === 'archival') {
+      // everything
+      for (const rec of sqlGetAllSpanMetadata.iterate()) {
+        yield spanArtifactName(rec);
+      }
+    } else if (artifactMode === 'debug') {
+      // everything that is a complete span
+      for (const rec of sqlGetAllSpanMetadata.iterate()) {
+        const { vatID, startPos, endPos } = rec;
+        const count = sqlCountSpanItems.get(vatID, startPos, endPos);
+        if (count !== endPos - startPos) {
+          // skip incomplete spans, because the exporter did not
+          // already do a completeness check in 'debug' mode
+          continue;
+        }
+        yield spanArtifactName(rec);
       }
-
-      yield spanArtifactName(rec);
     }
   }
 
@@ -590,19 +618,27 @@ export function makeTranscriptStore(
       WHERE vatID = ? AND startPos = ?
   `);
 
+  const sqlGetStartOfIncarnation = db.prepare(`
+    SELECT startPos
+      FROM transcriptSpans
+      WHERE vatID=? AND incarnation=?
+      ORDER BY startPos ASC LIMIT 1
+  `);
+  sqlGetStartOfIncarnation.pluck();
+
   /**
    * 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 {object} options
-   * @param {boolean} options.includeHistorical
+   * @param {ArtifactMode} options.artifactMode
    *
    * @returns {Promise<void>}
    */
   async function populateTranscriptSpan(name, makeChunkIterator, options) {
     ensureTxn();
-    const { includeHistorical } = options;
+    const { artifactMode } = options;
     const parts = name.split('.');
     const [type, vatID, rawStartPos, rawEndPos] = parts;
     // prettier-ignore
@@ -614,11 +650,23 @@ export function makeTranscriptStore(
     const metadata =
       sqlGetSpanMetadataFor.get(vatID, startPos) ||
       Fail`no metadata for transcript span ${name}`;
-    if (!metadata.isCurrent && !includeHistorical) {
-      return; // ignore old spans
-    }
     assert.equal(metadata.endPos, endPos);
 
+    if (artifactMode === 'operational') {
+      if (!metadata.isCurrent) {
+        return; // ignore old spans
+      }
+    }
+    if (artifactMode === 'replay') {
+      // ignore spans that aren't for the current incarnation
+      const { incarnation } = sqlGetCurrentSpanBounds.get(vatID);
+      const incStart = sqlGetStartOfIncarnation.get(vatID, incarnation);
+      if (startPos < incStart) {
+        return;
+      }
+    }
+    // 'archival' and 'debug' modes accept all spans
+
     const artifactChunks = await makeChunkIterator();
     const inStream = Readable.from(artifactChunks);
     const lineTransform = new BufferLineTransform();
@@ -679,19 +727,36 @@ export function makeTranscriptStore(
     }
   }
 
-  function assertComplete(level) {
-    assert.equal(level, 'operational'); // for now
-    // every 'isCurrent' transcript span must have all items
+  function assertComplete(checkMode) {
+    assert(checkMode !== 'debug', checkMode);
     for (const rec of sqlGetCurrentSpanMetadata.iterate()) {
       const { vatID, startPos, endPos, incarnation } = rec;
-      const count = sqlCountPopulatedSpanItems.get(
-        vatID,
-        incarnation,
-        startPos,
-        endPos,
-      );
-      if (count !== endPos - startPos) {
-        throw Fail`incomplete current transcript span: ${count} items, ${rec}`;
+
+      if (checkMode === 'operational') {
+        // at 'operational', every 'isCurrent' transcript span must
+        // have all items
+        const count = sqlCountSpanItems.get(vatID, startPos, endPos);
+        if (count !== endPos - startPos) {
+          throw Fail`incomplete current transcript span: ${count} items, ${rec}`;
+        }
+      } else if (checkMode === 'replay') {
+        // at 'replay', every vat's current incarnation must be fully
+        // populated (which implies 'operational')
+        const incStart = sqlGetStartOfIncarnation.get(vatID, incarnation);
+        const incCount = sqlCountSpanItems.get(vatID, incStart, endPos);
+        if (incCount !== endPos - incStart) {
+          throw Fail`incomplete current incarnation transcript: ${incCount} items`;
+        }
+      } else if (checkMode === 'archival') {
+        // at 'archival', every incarnation must be fully populated,
+        // which means position=0 up through endPos-1 (which implies
+        // 'replay')
+        const arcCount = sqlCountSpanItems.get(vatID, 0, endPos);
+        if (arcCount !== endPos) {
+          throw Fail`incomplete archival transcript: ${arcCount} vs ${endPos}`;
+        }
+      } else {
+        throw Fail`unknown checkMode ${checkMode}`;
       }
     }
   }

package/src/types.d.ts

@@ -2,13 +2,14 @@ export type {
   SwingStore,
   SwingStoreKernelStorage,
   SwingStoreHostStorage,
-} from './src/swingStore.js';
-export type { KVStore } from './src/kvStore.js';
-export type { BundleStore } from './src/bundleStore.js';
+} from './swingStore.js';
+export type { KVStore } from './kvStore.js';
+export type { BundleStore } from './bundleStore.js';
+export type { SnapStore, SnapshotResult, SnapshotInfo } from './snapStore.js';
+export type { TranscriptStore } from './transcriptStore.js';
+export type { ArtifactMode } from './internal.js';
+export type { ImportSwingStoreOptions } from './importer.js';
 export type {
-  SnapStore,
-  SnapshotResult,
-  SnapshotInfo,
-} from './src/snapStore.js';
-export type { TranscriptStore } from './src/transcriptStore.js';
-export type { SwingStoreExporter, ExportMode } from './src/exporter.js';
+  SwingStoreExporter,
+  ExportSwingStoreOptions,
+} from './exporter.js';

package/test/test-export.js

@@ -7,6 +7,14 @@ import { initSwingStore, makeSwingStoreExporter } from '../src/index.js';
 
 import { tmpDir, getSnapshotStream, makeB0ID } from './util.js';
 
+const rank = {
+  operational: 1,
+  replay: 2,
+  archival: 3,
+  debug: 4,
+  'debug-on-pruned': 4,
+};
+
 const snapshotData = 'snapshot data';
 // this snapHash was computed manually
 const snapHash =
@@ -28,48 +36,57 @@ const exportTest = test.macro(async (t, mode) => {
   const ss1 = initSwingStore(dbDir, options);
   const ks = ss1.kernelStorage;
 
-  // build a DB with three spans (only one inUse) and two snapshots
-  // (same)
+  // build a DB with four spans (one in an old incarnation, two
+  // historical but current incarnation, only one inUse) and two
+  // snapshots (only one inUSe)
 
   ks.kvStore.set('key1', 'value1');
   ks.bundleStore.addBundle(bundle0ID, bundle0);
   ks.transcriptStore.initTranscript('v1');
 
+  // incarnation 0
   ks.transcriptStore.addItem('v1', 'start-worker'); // 0
-  ks.transcriptStore.addItem('v1', 'delivery1'); // 1
-  await ks.snapStore.saveSnapshot('v1', 2, getSnapshotStream(snapshotData));
-  ks.transcriptStore.addItem('v1', 'save-snapshot'); // 2
-  ks.transcriptStore.rolloverSpan('v1'); // range= 0..3
+  ks.transcriptStore.addItem('v1', 'shutdown-worker'); // 1
+  ks.transcriptStore.rolloverIncarnation('v1');
+  const spanHash0 =
+    '5bee0f44eca02f23eab03703e84ed2647d5d117fed99e1c30a3b424b7f082ab9';
+
+  // incarnation 1
+  ks.transcriptStore.addItem('v1', 'start-worker'); // 2
+  ks.transcriptStore.addItem('v1', 'delivery1'); // 3
+  await ks.snapStore.saveSnapshot('v1', 4, getSnapshotStream(snapshotData));
+  ks.transcriptStore.addItem('v1', 'save-snapshot'); // 4
+  ks.transcriptStore.rolloverSpan('v1'); // range= 2..5
   const spanHash1 =
     '57152efdd7fdf75c03371d2b4f1088d5bf3eae7fe643babce527ff81df38998c';
 
-  ks.transcriptStore.addItem('v1', 'load-snapshot'); // 3
-  ks.transcriptStore.addItem('v1', 'delivery2'); // 4
-  await ks.snapStore.saveSnapshot('v1', 5, getSnapshotStream(snapshotData));
-  ks.transcriptStore.addItem('v1', 'save-snapshot'); // 5
-  ks.transcriptStore.rolloverSpan('v1'); // range= 3..6
+  ks.transcriptStore.addItem('v1', 'load-snapshot'); // 5
+  ks.transcriptStore.addItem('v1', 'delivery2'); // 6
+  await ks.snapStore.saveSnapshot('v1', 7, getSnapshotStream(snapshotData));
+  ks.transcriptStore.addItem('v1', 'save-snapshot'); // 7
+  ks.transcriptStore.rolloverSpan('v1'); // range= 5..8
   const spanHash2 =
     '1947001e78e01bd1e773feb22b4ffc530447373b9de9274d5d5fbda3f23dbf2b';
 
-  ks.transcriptStore.addItem('v1', 'load-snapshot'); // 6
-  ks.transcriptStore.addItem('v1', 'delivery3'); // 7
+  ks.transcriptStore.addItem('v1', 'load-snapshot'); // 8
+  ks.transcriptStore.addItem('v1', 'delivery3'); // 9
   const spanHash3 =
     'e6b42c6a3fb94285a93162f25a9fc0145fd4c5bb144917dc572c50ae2d02ee69';
-  // current range= 6..8
+  // current range= 8..10
 
-  ss1.hostStorage.commit();
+  await ss1.hostStorage.commit();
 
   // create an export, and assert that the pieces match what we
-  // expect. exportMode='current' means we get all metadata, no
+  // expect. artifactMode='operational' means we get all metadata, no
   // historical transcript spans, and no historical snapshots
 
   assert.typeof(mode, 'string');
-  /** @typedef {import('../src/exporter.js').ExportMode} ExportMode */
-  let exportMode = /** @type {ExportMode} */ (mode);
+  /** @typedef {import('../src/internal.js').ArtifactMode} ArtifactMode */
+  let artifactMode = /** @type {ArtifactMode} */ (mode);
   if (mode === 'debug-on-pruned') {
-    exportMode = 'debug';
+    artifactMode = 'debug';
   }
-  const exporter = makeSwingStoreExporter(dbDir, exportMode);
+  const exporter = makeSwingStoreExporter(dbDir, { artifactMode });
 
   // exportData
   {
@@ -90,36 +107,46 @@ const exportTest = test.macro(async (t, mode) => {
     };
 
     check('kv.key1', 'value1');
-    check('snapshot.v1.2', {
+    check('snapshot.v1.4', {
       vatID: 'v1',
-      snapPos: 2,
+      snapPos: 4,
       inUse: 0,
       hash: snapHash,
     });
-    check('snapshot.v1.5', {
+    check('snapshot.v1.7', {
       vatID: 'v1',
-      snapPos: 5,
+      snapPos: 7,
       inUse: 1,
       hash: snapHash,
     });
-    check('snapshot.v1.current', 'snapshot.v1.5');
-    const base = { vatID: 'v1', incarnation: 0, isCurrent: 0 };
+    check('snapshot.v1.current', 'snapshot.v1.7');
+    const base = { vatID: 'v1', isCurrent: 0 };
     check('transcript.v1.0', {
       ...base,
+      incarnation: 0,
       startPos: 0,
-      endPos: 3,
+      endPos: 2,
+      hash: spanHash0,
+    });
+    check('transcript.v1.2', {
+      ...base,
+      incarnation: 1,
+      startPos: 2,
+      endPos: 5,
       hash: spanHash1,
     });
-    check('transcript.v1.3', {
+    check('transcript.v1.5', {
       ...base,
-      startPos: 3,
-      endPos: 6,
+      incarnation: 1,
+      startPos: 5,
+      endPos: 8,
       hash: spanHash2,
     });
     check('transcript.v1.current', {
       ...base,
-      startPos: 6,
-      endPos: 8,
+      incarnation: 1,
+      startPos: 8,
+      endPos: 10,
       isCurrent: 1,
       hash: spanHash3,
     });
@@ -153,29 +180,35 @@ const exportTest = test.macro(async (t, mode) => {
       t.deepEqual(data, expected);
     };
 
-    // export mode 'current' means we omit historical snapshots and
+    // export mode 'operational' means we omit historical snapshots and
     // transcript spans
 
-    await check('snapshot.v1.5', 'snapshot data');
-    await check('transcript.v1.6.8', 'load-snapshot\ndelivery3\n');
+    await check('snapshot.v1.7', 'snapshot data');
+    await check('transcript.v1.8.10', 'load-snapshot\ndelivery3\n');
     await check(`bundle.${bundle0ID}`, bundle0);
 
-    if (mode === 'archival' || mode === 'debug' || mode === 'debug-on-pruned') {
-      // adds the old transcript spans
+    t.true(rank[mode] > 0);
+    if (rank[mode] >= rank.replay) {
+      // add the old transcript spans of the current incarnation
       await check(
-        'transcript.v1.0.3',
+        'transcript.v1.2.5',
         'start-worker\ndelivery1\nsave-snapshot\n',
       );
       await check(
-        'transcript.v1.3.6',
+        'transcript.v1.5.8',
         'load-snapshot\ndelivery2\nsave-snapshot\n',
       );
     }
 
+    if (rank[mode] >= rank.archival) {
+      // add the spans of the old incarnation
+      await check('transcript.v1.0.2', 'start-worker\nshutdown-worker\n');
+    }
+
     if (mode === 'debug') {
       // adds the old snapshots, which are only present if
       // initSwingStore() was given {keepSnapshots: true}
-      await check('snapshot.v1.2', 'snapshot data');
+      await check('snapshot.v1.4', 'snapshot data');
       // mode='debug-on-pruned' exercises the keepSnapshots:false case
     }
 
@@ -187,7 +220,8 @@ const exportTest = test.macro(async (t, mode) => {
   }
 });
 
-test('export current', exportTest, 'current');
+test('export operational', exportTest, 'operational');
+test('export replay', exportTest, 'replay');
 test('export archival', exportTest, 'archival');
 test('export debug', exportTest, 'debug');
 test('export debug-on-pruned', exportTest, 'debug-on-pruned');
@@ -220,9 +254,10 @@ test('export omits pruned span artifacts', async t => {
   const spanHash2 =
     'b26c8faf425c3c2738e0c5a5e9a7cd71075c68f0c9f2d6cdfd83c68204801dbb';
 
-  ss1.hostStorage.commit();
+  await ss1.hostStorage.commit();
 
-  const exporter = makeSwingStoreExporter(dbDir, 'archival');
+  const artifactMode = 'debug';
+  const exporter = makeSwingStoreExporter(dbDir, { artifactMode });
 
   // exportData
   {

package/test/test-exportImport.js

@@ -123,7 +123,8 @@ test('crank abort leaves no debris in export log', async t => {
     await ssOut.hostStorage.commit();
   }
 
-  const exporter = makeSwingStoreExporter(dbDir, 'current');
+  const artifactMode = 'operational';
+  const exporter = makeSwingStoreExporter(dbDir, { artifactMode });
 
   const exportData = [];
   for await (const elem of exporter.getExportData()) {
@@ -172,12 +173,13 @@ async function testExportImport(
   exportMode,
   importMode,
   expectedArtifactNames,
+  failureMode = 'none',
 ) {
   const exportLog = makeExportLog();
   const [dbDir, cleanup] = await tmpDir('testdb');
   t.teardown(cleanup);
 
-  const keepTranscripts = runMode !== 'current';
+  const keepTranscripts = runMode !== 'operational';
   const keepSnapshots = runMode === 'debug';
   const ssOut = initSwingStore(dbDir, {
     exportCallback: exportLog.callback,
@@ -218,7 +220,15 @@ async function testExportImport(
     await ssOut.hostStorage.commit();
   }
 
-  const exporter = makeSwingStoreExporter(dbDir, exportMode);
+  const incomplete = 'incomplete archival transcript: 3 vs 12';
+  function doExport() {
+    return makeSwingStoreExporter(dbDir, { artifactMode: exportMode });
+  }
+  if (failureMode === 'export') {
+    await t.throws(doExport, { message: incomplete });
+    return;
+  }
+  const exporter = doExport();
 
   const exportData = [];
   for await (const elem of exporter.getExportData()) {
@@ -302,13 +312,36 @@ async function testExportImport(
   }
   t.deepEqual(artifactNames, expectedArtifactNames);
 
-  const includeHistorical = importMode !== 'current';
-
   const beforeDump = debug.dump(keepSnapshots);
-  const ssIn = await importSwingStore(exporter, null, { includeHistorical });
+  function doImport() {
+    return importSwingStore(exporter, null, { artifactMode: importMode });
+  }
+
+  if (failureMode === 'import') {
+    await t.throwsAsync(doImport, { message: incomplete });
+    return;
+  }
+  t.is(failureMode, 'none');
+  const ssIn = await doImport();
   await ssIn.hostStorage.commit();
-  const dumpsShouldMatch =
-    runMode !== 'debug' || (exportMode === 'debug' && importMode !== 'current');
+  let dumpsShouldMatch = true;
+  if (runMode === 'operational') {
+    dumpsShouldMatch = true; // there's no data to lose
+  } else if (runMode === 'archival') {
+    if (exportMode === 'current') {
+      dumpsShouldMatch = false; // export omits some data
+    }
+    if (importMode === 'current') {
+      dumpsShouldMatch = false; // import ignores some data
+    }
+  } else if (runMode === 'debug') {
+    if (exportMode !== 'debug') {
+      dumpsShouldMatch = false; // export omits some data
+    }
+    if (importMode !== 'debug') {
+      dumpsShouldMatch = false; // import ignores some data
+    }
+  }
   if (dumpsShouldMatch) {
     const afterDump = ssIn.debug.dump(keepSnapshots);
     t.deepEqual(beforeDump, afterDump);
@@ -343,35 +376,43 @@ const expectedDebugArtifacts = [
   'transcript.vatB.5.10',
 ];
 
-const C = 'current';
+const C = 'operational'; // nee 'current'
+// we don't try to test 'replay' here: see test-import.js and test-export.js
 const A = 'archival';
 const D = 'debug';
 
+// importMode='archival' requires a non-pruned DB
+// (runMode!=='current'), with exportMode as 'archival' or 'debug'
+
+// the expected artifacts are a function of the runMode and exportMode, not importMode
+
 test('export and import data for state sync - current->current->current', async t => {
   await testExportImport(t, C, C, C, expectedCurrentArtifacts);
 });
+// so this one fails during import
 test('export and import data for state sync - current->current->archival', async t => {
-  await testExportImport(t, C, C, A, expectedCurrentArtifacts);
+  await testExportImport(t, C, C, A, expectedCurrentArtifacts, 'import');
 });
 test('export and import data for state sync - current->current->debug', async t => {
   await testExportImport(t, C, C, D, expectedCurrentArtifacts);
 });
 
+// these all throw an error during export, because 'archival' requires a non-pruned DB
 test('export and import data for state sync - current->archival->current', async t => {
-  await testExportImport(t, C, A, C, expectedCurrentArtifacts);
+  await testExportImport(t, C, A, C, [], 'export');
 });
 test('export and import data for state sync - current->archival->archival', async t => {
-  await testExportImport(t, C, A, A, expectedCurrentArtifacts);
+  await testExportImport(t, C, A, A, [], 'export');
 });
 test('export and import data for state sync - current->archival->debug', async t => {
-  await testExportImport(t, C, A, D, expectedCurrentArtifacts);
+  await testExportImport(t, C, A, D, [], 'export');
 });
 
 test('export and import data for state sync - current->debug->current', async t => {
   await testExportImport(t, C, D, C, expectedCurrentArtifacts);
 });
 test('export and import data for state sync - current->debug->archival', async t => {
-  await testExportImport(t, C, D, A, expectedCurrentArtifacts);
+  await testExportImport(t, C, D, A, expectedCurrentArtifacts, 'import');
 });
 test('export and import data for state sync - current->debug->debug', async t => {
   await testExportImport(t, C, D, D, expectedCurrentArtifacts);
@@ -383,7 +424,7 @@ test('export and import data for state sync - archival->current->current', async
   await testExportImport(t, A, C, C, expectedCurrentArtifacts);
 });
 test('export and import data for state sync - archival->current->archival', async t => {
-  await testExportImport(t, A, C, A, expectedCurrentArtifacts);
+  await testExportImport(t, A, C, A, expectedCurrentArtifacts, 'import');
 });
 test('export and import data for state sync - archival->current->debug', async t => {
   await testExportImport(t, A, C, D, expectedCurrentArtifacts);
@@ -415,7 +456,7 @@ test('export and import data for state sync - debug->current->current', async t
   await testExportImport(t, D, C, C, expectedCurrentArtifacts);
 });
 test('export and import data for state sync - debug->current->archival', async t => {
-  await testExportImport(t, D, C, A, expectedCurrentArtifacts);
+  await testExportImport(t, D, C, A, expectedCurrentArtifacts, 'import');
 });
 test('export and import data for state sync - debug->current->debug', async t => {
   await testExportImport(t, D, C, D, expectedCurrentArtifacts);