@delali/sirannon-db 0.2.3-next.37 → 0.2.3-next.39

package/dist/{chunk-ZKDBGX7H.mjs → chunk-OJQHM4MT.mjs}

@@ -1,8 +1,12 @@
-import { checkpointLog, logFrameOffset, LOG_HEADER_BYTES, readLogHeader, readValidLogFrame } from './chunk-72I5UI5C.mjs';
-import { BackupManager, BackupScheduler, DEFAULT_PIECE_BYTES, sendFileInPieces } from './chunk-BQTVNI5H.mjs';
-import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS } from './chunk-GBM4AU24.mjs';
-import { DEFAULT_CHAIN_NAME, readBackupChains, readChainHeadAt, readChainHeads, appendChainRecord, appendChainHead, isBackupChainPosition } from './chunk-YVF2ZJTE.mjs';
+import { verifyBackupRecord } from './chunk-7SC2TZAS.mjs';
+import { BackupManager, BackupScheduler, DEFAULT_PIECE_BYTES, sendFileInPieces } from './chunk-DXXCLTFF.mjs';
+import { DEFAULT_BACKUP_NAME_PREFIX, defaultStagingDir, DEFAULT_CAPTURE_INTERVAL_MS, DEFAULT_FULL_COPY_INTERVAL_MS } from './chunk-LXCGPZPA.mjs';
 import { WORKER_CANCELLED_CODE, deserializeError } from './chunk-YLAVDZCS.mjs';
+import { readCycleState, writeCycleState, removeCycleState, stagedCapturePath, captureAndCheckpointTurn } from './chunk-W77EEVOT.mjs';
+import { checkpointLog } from './chunk-U445A3C4.mjs';
+import { logPathFor } from './chunk-2QCPVE67.mjs';
+import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS } from './chunk-DVS4QSIZ.mjs';
+import { DEFAULT_CHAIN_NAME, readBackupChains, appendChainRecord, appendChainHead, readChainHeadAt, readChainHeads } from './chunk-YVF2ZJTE.mjs';
 import { randomHex } from './chunk-V5FUJEYY.mjs';
 import { SirannonError, ExtensionError } from './chunk-PBRXXISQ.mjs';
 import { Worker } from 'worker_threads';
@@ -10,7 +14,7 @@ import { existsSync } from 'fs';
 import { resolve, dirname, join, sep } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { AsyncLocalStorage } from 'async_hooks';
-import { mkdir, rm, readFile, writeFile, rename, stat, open } from 'fs/promises';
+import { mkdir, rm, stat } from 'fs/promises';
 import { createRequire } from 'module';
 
 // src/core/driver/extension.ts
@@ -403,196 +407,6 @@ function clearPendingTimers(entry) {
   if (entry.timer) clearTimeout(entry.timer);
   if (entry.graceTimer) clearTimeout(entry.graceTimer);
 }
-var READ_CHUNK_BYTES = 4 * 1024 * 1024;
-async function openForReading(path) {
-  try {
-    return await open(path, "r");
-  } catch (err) {
-    if (err.code === "ENOENT") return void 0;
-    throw err;
-  }
-}
-async function readLogFileHeader(logPath) {
-  const file = await openForReading(logPath);
-  if (!file) return void 0;
-  try {
-    const buffer = Buffer.allocUnsafe(LOG_HEADER_BYTES);
-    const { bytesRead } = await file.read(buffer, 0, LOG_HEADER_BYTES, 0);
-    if (bytesRead < LOG_HEADER_BYTES) return void 0;
-    return readLogHeader(buffer);
-  } finally {
-    await file.close();
-  }
-}
-async function scanLogFrames(logPath, header, from) {
-  const stopped = {
-    lastCommitFrame: from.frame,
-    endOffset: logFrameOffset(from.frame + 1, header.frameBytes),
-    checksum: from.checksum
-  };
-  const file = await openForReading(logPath);
-  if (!file) return stopped;
-  try {
-    const { size } = await file.stat();
-    const framesInFile = Math.max(0, Math.floor((size - LOG_HEADER_BYTES) / header.frameBytes));
-    const framesPerChunk = Math.max(1, Math.floor(READ_CHUNK_BYTES / header.frameBytes));
-    const buffer = Buffer.allocUnsafe(framesPerChunk * header.frameBytes);
-    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-    let running = from.checksum;
-    let found = stopped;
-    let frame = from.frame + 1;
-    while (frame <= framesInFile) {
-      const frames = Math.min(framesPerChunk, framesInFile - frame + 1);
-      const wanted = frames * header.frameBytes;
-      let filled = 0;
-      while (filled < wanted) {
-        const { bytesRead } = await file.read(
-          buffer,
-          filled,
-          wanted - filled,
-          logFrameOffset(frame, header.frameBytes) + filled
-        );
-        if (bytesRead === 0) break;
-        filled += bytesRead;
-      }
-      const readable = Math.floor(filled / header.frameBytes);
-      if (readable === 0) break;
-      for (let inChunk = 0; inChunk < readable; inChunk++) {
-        const read = readValidLogFrame(view, inChunk * header.frameBytes, header, running);
-        if (!read) return found;
-        running = read.checksum;
-        if (read.frame.databasePages !== 0) {
-          found = {
-            lastCommitFrame: frame + inChunk,
-            endOffset: logFrameOffset(frame + inChunk + 1, header.frameBytes),
-            checksum: running
-          };
-        }
-      }
-      frame += readable;
-    }
-    return found;
-  } finally {
-    await file.close();
-  }
-}
-async function copyLogRange(logPath, startOffset, endOffset, destPath) {
-  const source = await open(logPath, "r");
-  try {
-    const dest = await open(destPath, "w");
-    try {
-      const buffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, Math.max(endOffset - startOffset, 1)));
-      let at = startOffset;
-      let written = 0;
-      while (at < endOffset) {
-        const wanted = Math.min(buffer.byteLength, endOffset - at);
-        const { bytesRead } = await source.read(buffer, 0, wanted, at);
-        if (bytesRead === 0) {
-          throw new SirannonError(
-            `The write-ahead log '${logPath}' ends at byte ${at} while the frames captured from it run to byte ${endOffset}, so it lost frames while Sirannon was reading it. Another connection checkpointed the log. Route every write and every checkpoint through Sirannon, and take a fresh full copy so a new chain starts from a known state.`,
-            "BACKUP_LOG_REWOUND"
-          );
-        }
-        let put = 0;
-        while (put < bytesRead) {
-          const { bytesWritten } = await dest.write(buffer, put, bytesRead - put);
-          if (bytesWritten === 0) {
-            throw new SirannonError(
-              `The capture of '${logPath}' could write no more than ${written + put} of its ${endOffset - startOffset} bytes into '${destPath}'. Check the free space and the permissions on that directory.`,
-              "BACKUP_ERROR"
-            );
-          }
-          put += bytesWritten;
-        }
-        at += bytesRead;
-        written += bytesRead;
-      }
-      return written;
-    } finally {
-      await dest.close();
-    }
-  } finally {
-    await source.close();
-  }
-}
-function cursorChecksum(cursor) {
-  return { first: cursor.checksum1, second: cursor.checksum2 };
-}
-function sameLog(header, cursor) {
-  return header.salt1 === cursor.salt1 && header.salt2 === cursor.salt2;
-}
-
-// src/core/backup/cycle-capture.ts
-function stagedCapturePath(stagingDir, sequence) {
-  return join(stagingDir, `capture-${sequence}.wal`);
-}
-function rewoundError(request, detail) {
-  return new SirannonError(
-    `The write-ahead log of '${request.sourcePath}' ${detail}, so the frames written before it did are in no backup. Another connection checkpointed the log, or the database file was replaced. Route every write and every checkpoint through Sirannon, and take a fresh full copy so a new chain starts from a known state.`,
-    "BACKUP_LOG_REWOUND"
-  );
-}
-async function captureLogFrames(request) {
-  const startedAt = Date.now();
-  const cursor = request.cursor;
-  const header = await readLogFileHeader(request.logPath);
-  const holdsEveryCapturedFrame = cursor !== null && header !== void 0 && sameLog(header, cursor);
-  const newLogAllowed = cursor === null || cursor.checkpointed || request.expectNewLog;
-  if (!holdsEveryCapturedFrame && !newLogAllowed && cursor) {
-    throw rewoundError(
-      request,
-      header ? `restarted at checkpoint sequence ${header.logSequence} while the chain reaches frame ${cursor.lastFrame} of sequence ${cursor.logSequence}` : `holds no frames while the chain reaches frame ${cursor.lastFrame} of sequence ${cursor.logSequence}`
-    );
-  }
-  if (!header) return void 0;
-  const from = cursor && holdsEveryCapturedFrame ? { frame: cursor.lastFrame, checksum: cursorChecksum(cursor) } : { frame: 0, checksum: header.checksum };
-  const scan = await scanLogFrames(request.logPath, header, from);
-  if (scan.lastCommitFrame <= from.frame) {
-    if (from.frame > 0 && scan.lastCommitFrame < from.frame) {
-      throw rewoundError(
-        request,
-        `now ends at frame ${scan.lastCommitFrame} while the chain reaches frame ${from.frame}`
-      );
-    }
-    return void 0;
-  }
-  const firstFrame = from.frame + 1;
-  const startOffset = firstFrame === 1 ? 0 : logFrameOffset(firstFrame, header.frameBytes);
-  const byteLength = await copyLogRange(
-    request.logPath,
-    startOffset,
-    scan.endOffset,
-    stagedCapturePath(request.stagingDir, request.sequence)
-  );
-  const capturedAt = Date.now();
-  return {
-    name: `${request.namePrefix}-${request.chainId}-${String(request.sequence).padStart(6, "0")}.wal`,
-    runId: randomHex(8),
-    sequence: request.sequence,
-    position: {
-      logSequence: header.logSequence,
-      salt1: header.salt1,
-      salt2: header.salt2,
-      firstFrame,
-      lastFrame: scan.lastCommitFrame
-    },
-    cursor: {
-      logSequence: header.logSequence,
-      salt1: header.salt1,
-      salt2: header.salt2,
-      lastFrame: scan.lastCommitFrame,
-      checksum1: scan.checksum.first,
-      checksum2: scan.checksum.second,
-      checkpointed: false
-    },
-    startedAt,
-    capturedAt,
-    copyMs: capturedAt - startedAt,
-    frameCount: scan.lastCommitFrame - from.frame,
-    byteLength,
-    pageSize: header.pageSize
-  };
-}
 
 // src/core/backup/preferred-node.ts
 function preferredBackupNode(membership, preference) {
@@ -726,15 +540,209 @@ async function logGrownPastLimit(logPath, maxBytes, databaseId) {
     "BACKUP_CHAIN_BROKEN"
   );
 }
+async function chainLostFromList(request, chainName, state) {
+  return chainMissingFromList(request.destination, chainName, state.chainId, request.databaseId, state.headIndex);
+}
 
-// src/core/backup/cycle-options.ts
-var DEFAULT_CAPTURE_INTERVAL_MS = 6e4;
-var DEFAULT_FULL_COPY_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-var DEFAULT_BACKUP_NAME_PREFIX = "sirannon-backup";
-function defaultStagingDir(sourcePath) {
-  return `${sourcePath}-backup`;
+// src/core/backup/cycle-callbacks.ts
+function reportQuietly(callback, value) {
+  if (!callback) return;
+  try {
+    callback(value);
+  } catch {
+  }
 }
 
+// src/core/backup/cycle-status.ts
+var BackupCycleStatusRecorder = class {
+  turnRunning = false;
+  turnStartedAt = 0;
+  latestProgress;
+  latestRun;
+  latestSkip;
+  latestError;
+  /** Marks a turn as under way and clears the progress the previous turn recorded. */
+  turnStarted() {
+    this.turnRunning = true;
+    this.turnStartedAt = Date.now();
+    this.latestProgress = void 0;
+  }
+  /** Marks the turn as finished. A caller then reads the outcome from the last run, skip, or failure. */
+  turnFinished() {
+    this.turnRunning = false;
+    this.turnStartedAt = 0;
+    this.latestProgress = void 0;
+  }
+  /** Records how far the turn under way has got. */
+  progressed(progress) {
+    this.latestProgress = progress;
+  }
+  /** Records what a finished turn wrote. */
+  ran(report) {
+    this.latestRun = report;
+  }
+  /** Records a turn the cycle passed over. */
+  skipped(skip) {
+    this.latestSkip = skip;
+  }
+  /**
+   * Records a failure, under the code a caller matches on, along with how far
+   * the run had got and which chain it was extending.
+   *
+   * @param err - What the turn failed with.
+   * @param chainId - The chain the cycle was extending, where it held one.
+   */
+  failed(err, chainId) {
+    const at = Date.now();
+    this.latestError = {
+      code: err instanceof SirannonError ? err.code : "BACKUP_ERROR",
+      message: err.message,
+      at,
+      durationMs: this.turnStartedAt === 0 ? 0 : at - this.turnStartedAt,
+      ...chainId === void 0 ? {} : { chainId },
+      ...this.latestProgress === void 0 ? {} : { progress: this.latestProgress }
+    };
+  }
+  /**
+   * Reads everything recorded so far.
+   *
+   * @param chainId - The chain the cycle is extending, where it has one.
+   * @returns What the cycle is doing, and what its recent turns produced.
+   */
+  read(chainId) {
+    return {
+      running: this.turnRunning,
+      ...chainId === void 0 ? {} : { chainId },
+      ...this.latestProgress === void 0 ? {} : { progress: this.latestProgress },
+      ...this.latestRun === void 0 ? {} : { lastRun: this.latestRun },
+      ...this.latestSkip === void 0 ? {} : { lastSkip: this.latestSkip },
+      ...this.latestError === void 0 ? {} : { lastError: this.latestError }
+    };
+  }
+};
+
+// src/core/backup/cycle-reporting.ts
+var BackupTurnLog = class {
+  constructor(audience, logPath) {
+    this.audience = audience;
+    this.logPath = logPath;
+  }
+  record = new BackupCycleStatusRecorder();
+  announced = /* @__PURE__ */ new Set();
+  /**
+   * Records a finished run and passes it to the caller.
+   *
+   * @param report - What that run produced.
+   */
+  ran(report) {
+    this.record.ran(report);
+    reportQuietly(this.audience.onRun, report);
+  }
+  /**
+   * Records how far the run under way has reached and passes that to the caller.
+   *
+   * @param progress - The counters that run has reached.
+   */
+  progressed(progress) {
+    this.record.progressed(progress);
+    reportQuietly(this.audience.onProgress, progress);
+  }
+  /** Marks a turn as under way, and forgets whatever failures the previous turn announced. */
+  turnStarted() {
+    this.announced.clear();
+    this.record.turnStarted();
+  }
+  /** Marks the turn as finished. */
+  turnFinished() {
+    this.record.turnFinished();
+  }
+  /**
+   * Records a failure as the turn's outcome and passes it to the caller.
+   *
+   * @param err - What the turn failed with.
+   * @param chainId - The chain to record it against, where the cycle holds one.
+   */
+  failed(err, chainId) {
+    this.announced.add(err);
+    const failure = toBackupError(err);
+    this.record.failed(failure, chainId);
+    reportQuietly(this.audience.onError, failure);
+  }
+  /**
+   * Answers whether this turn has already passed one failure to the caller.
+   *
+   * @param err - The failure to look for.
+   * @returns Whether the caller has already heard about that failure.
+   */
+  hasAnnounced(err) {
+    return this.announced.has(err);
+  }
+  /**
+   * Records a turn the cycle passed over and passes it to the caller, stating
+   * how much log this node was still holding as it skipped.
+   *
+   * @param skip - Why the cycle passed the turn over.
+   */
+  async skipped(skip) {
+    const held = await uncapturedLogBytes(this.logPath);
+    const passed = held === void 0 ? skip : { ...skip, uncapturedLogBytes: held };
+    this.record.skipped(passed);
+    reportQuietly(this.audience.onSkip, passed);
+  }
+  /**
+   * Reads everything recorded so far.
+   *
+   * @param chainId - The chain the cycle is extending, where it has one.
+   * @returns What the cycle is doing, and what its recent turns produced.
+   */
+  read(chainId) {
+    return this.record.read(chainId);
+  }
+};
+
+// src/core/backup/cycle-scheduling.ts
+var BackupCycleTimer = class {
+  handle = null;
+  /**
+   * Starts repeating. At an interval of zero or less the cycle takes a turn
+   * only when somebody asks it to.
+   *
+   * @param intervalMs - Milliseconds between one turn and the next.
+   * @param tick - Called on every interval.
+   */
+  arm(intervalMs, tick) {
+    this.disarm();
+    if (intervalMs <= 0) return;
+    this.handle = setInterval(tick, intervalMs);
+    this.handle.unref?.();
+  }
+  /** Stops repeating. */
+  disarm() {
+    if (!this.handle) return;
+    clearInterval(this.handle);
+    this.handle = null;
+  }
+};
+var SerialTurns = class {
+  inFlight = Promise.resolve();
+  /**
+   * Starts an operation once every turn asked for before it has settled.
+   *
+   * @param op - The turn to take.
+   * @returns Whatever that turn produced.
+   */
+  run(op) {
+    const turn = this.inFlight.then(op, op);
+    this.inFlight = turn.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return turn;
+  }
+};
+
 // src/core/backup/cycle-standdown.ts
 async function sendBeforeStandDown(cycle) {
   try {
@@ -762,43 +770,13 @@ async function releaseChainPastLogLimit(cycle) {
   cycle.report(lost);
   return true;
 }
-var STATE_FILE_NAME = "cycle.json";
-function isWholeNumber(value) {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0;
-}
-function isCursor(value) {
-  const cursor = value;
-  return isWholeNumber(cursor?.logSequence) && isWholeNumber(cursor.salt1) && isWholeNumber(cursor.salt2) && isWholeNumber(cursor.lastFrame) && isWholeNumber(cursor.checksum1) && isWholeNumber(cursor.checksum2) && typeof cursor.checkpointed === "boolean";
-}
-function isPendingCapture(value) {
-  const pending = value;
-  return typeof pending?.name === "string" && typeof pending.runId === "string" && isWholeNumber(pending.sequence) && pending.sequence >= 1 && isBackupChainPosition(pending.position) && isCursor(pending.cursor) && isWholeNumber(pending.startedAt) && isWholeNumber(pending.capturedAt) && isWholeNumber(pending.copyMs) && isWholeNumber(pending.frameCount) && isWholeNumber(pending.byteLength) && isWholeNumber(pending.pageSize);
-}
-function isCycleState(value) {
-  const state = value;
-  return typeof state?.chainName === "string" && typeof state.chainId === "string" && isWholeNumber(state.chainStartedAt) && (state.headIndex === void 0 || isWholeNumber(state.headIndex)) && isWholeNumber(state.records) && (state.cursor === null || isCursor(state.cursor)) && (state.pending === null || isPendingCapture(state.pending)) && typeof state.closedCleanly === "boolean";
-}
-function cycleStatePath(stagingDir) {
-  return join(stagingDir, STATE_FILE_NAME);
-}
-async function readCycleState(stagingDir) {
-  try {
-    const text = await readFile(cycleStatePath(stagingDir), "utf8");
-    const state = JSON.parse(text);
-    return isCycleState(state) ? state : void 0;
-  } catch {
-    return void 0;
-  }
-}
-async function writeCycleState(stagingDir, state) {
-  const path = cycleStatePath(stagingDir);
-  await mkdir(dirname(path), { recursive: true });
-  const staged = `${path}.writing`;
-  await writeFile(staged, JSON.stringify(state), "utf8");
-  await rename(staged, path);
-}
-async function removeCycleState(stagingDir) {
-  await rm(cycleStatePath(stagingDir), { force: true });
+async function confirmChainStillListed(grip) {
+  if (grip.verified || !grip.state) return grip.verified;
+  const lost = await chainLostFromList(grip.request, grip.chainName, grip.state);
+  if (!lost) return true;
+  await grip.discardState();
+  grip.report(lost);
+  return false;
 }
 async function startChain(request, chainName, namePrefix, previousChainId) {
   const chainId = randomHex(8);
@@ -814,7 +792,8 @@ async function startChain(request, chainName, namePrefix, previousChainId) {
     ...request.restartLimit === void 0 ? {} : { restartLimit: request.restartLimit },
     ...request.stallTimeoutMs === void 0 ? {} : { stallTimeoutMs: request.stallTimeoutMs },
     ...request.destinationTimeoutMs === void 0 ? {} : { destinationTimeoutMs: request.destinationTimeoutMs },
-    ...request.noProgressStepLimit === void 0 ? {} : { noProgressStepLimit: request.noProgressStepLimit }
+    ...request.noProgressStepLimit === void 0 ? {} : { noProgressStepLimit: request.noProgressStepLimit },
+    ...request.onProgress === void 0 ? {} : { onProgress: request.onProgress }
   });
   const base = {
     kind: "full",
@@ -845,8 +824,15 @@ async function transferCapture(request, chainName, chainId, pending, recordIndex
     pending.name,
     pieceBytes,
     request.fingerprint ?? true,
-    () => {
-    }
+    (piecesWritten, bytesWritten) => request.onProgress?.({
+      runId: pending.runId,
+      phase: "transfer",
+      totalPages: pending.frameCount,
+      remainingPages: 0,
+      restarts: 0,
+      piecesWritten,
+      bytesWritten
+    })
   );
   const finishedAt = Date.now();
   const record = {
@@ -907,20 +893,24 @@ async function sendStagedCapture(request, chainName, stagingDir, state) {
   request.onRun?.(report);
   return report;
 }
+async function beginReplacementChain(request, chainName, namePrefix, stagingDir, previousChainId) {
+  const started = await startChain(request, chainName, namePrefix, previousChainId);
+  const state = {
+    chainName,
+    chainId: started.chainId,
+    chainStartedAt: started.startedAt,
+    headIndex: started.headIndex,
+    records: 1,
+    cursor: null,
+    pending: null,
+    closedCleanly: false
+  };
+  await writeCycleState(stagingDir, state);
+  return { state, report: started.report };
+}
 
 // src/core/backup/cycle.ts
 var BackupCycle = class {
-  /** @internal */
-  constructor(request) {
-    this.request = request;
-    this.chainName = request.chainName ?? DEFAULT_CHAIN_NAME;
-    this.namePrefix = request.namePrefix ?? DEFAULT_BACKUP_NAME_PREFIX;
-    this.stagingDir = request.stagingDir ?? defaultStagingDir(request.sourcePath);
-    this.logPath = `${request.sourcePath}-wal`;
-    this.intervalMs = request.intervalMs ?? DEFAULT_CAPTURE_INTERVAL_MS;
-    this.fullCopyIntervalMs = request.fullCopyIntervalMs ?? DEFAULT_FULL_COPY_INTERVAL_MS;
-    this.preferredNode = request.preferredNode ?? "replica";
-  }
   chainName;
   namePrefix;
   stagingDir;
@@ -928,15 +918,34 @@ var BackupCycle = class {
   intervalMs;
   fullCopyIntervalMs;
   preferredNode;
-  timer = null;
+  timer = new BackupCycleTimer();
   state = null;
-  inFlight = Promise.resolve();
+  queued = null;
+  turns = new SerialTurns();
   started = false;
   verified = false;
   busy = false;
   captured = false;
   sendRefused = false;
   stopped = false;
+  request;
+  turnLog;
+  /** @internal */
+  constructor(request) {
+    this.logPath = logPathFor(request.sourcePath);
+    this.turnLog = new BackupTurnLog(request, this.logPath);
+    this.request = {
+      ...request,
+      onRun: (report) => this.turnLog.ran(report),
+      onProgress: (progress) => this.turnLog.progressed(progress)
+    };
+    this.chainName = request.chainName ?? DEFAULT_CHAIN_NAME;
+    this.namePrefix = request.namePrefix ?? DEFAULT_BACKUP_NAME_PREFIX;
+    this.stagingDir = request.stagingDir ?? defaultStagingDir(request.sourcePath);
+    this.intervalMs = request.intervalMs ?? DEFAULT_CAPTURE_INTERVAL_MS;
+    this.fullCopyIntervalMs = request.fullCopyIntervalMs ?? DEFAULT_FULL_COPY_INTERVAL_MS;
+    this.preferredNode = request.preferredNode ?? "replica";
+  }
   /**
    * Picks a chain up where the previous run left it, or starts a new one with a
    * full copy, and then repeats on the interval. A chain picked up takes an
@@ -957,22 +966,33 @@ var BackupCycle = class {
         this.report(err);
       }
     });
-    this.arm();
+    if (!this.stopped) this.timer.arm(this.intervalMs, () => void this.tick());
   }
   /**
-   * Runs one turn now. A turn sends any capture still waiting, reads the frames
-   * written since the previous turn, and checkpoints the log.
+   * Takes one turn now. A turn sends any capture still waiting, reads the
+   * frames written since the previous turn, and then checkpoints the log.
+   *
+   * One turn waits at a time. A call made while a turn is under way queues one
+   * behind it, and every call after that joins the queued turn, which reads the
+   * log once it begins and so covers their writes as well. Without that bound,
+   * a caller asking repeatedly during a long full copy would build a queue of
+   * turns with nothing left for any of them to capture.
    *
-   * A turn on a node its group backs up from somewhere else writes nothing and
-   * reports a skip instead.
+   * A turn on a node whose group backs up from somewhere else writes nothing
+   * and reports a skip.
    *
    * @returns What the turn wrote, or undefined where it wrote nothing.
    */
   runOnce() {
-    return this.runTurn(async () => {
+    const queued = this.queued;
+    if (queued) return queued;
+    const turn = this.runTurn(async () => {
+      this.queued = null;
       if (!await this.takesTheTurn()) return void 0;
       return this.turnOrStartOver();
     });
+    this.queued = turn;
+    return turn;
   }
   /**
    * Stops the cycle. It captures the log one final time first, so the writes
@@ -982,10 +1002,7 @@ var BackupCycle = class {
   async stop() {
     if (this.stopped) return;
     this.stopped = true;
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
+    this.timer.disarm();
     await this.runTurn(async () => {
       const state = this.state;
       if (!state) return;
@@ -1006,16 +1023,51 @@ var BackupCycle = class {
   chains() {
     return readBackupChains(this.request.destination, this.chainName);
   }
+  /**
+   * Reads what the cycle is doing at this moment, and what its recent turns
+   * produced.
+   *
+   * A caller following a long full copy reads this without having to wait on
+   * the turn, and it answers between turns as well.
+   *
+   * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
+   */
+  status() {
+    return this.turnLog.read(this.state?.chainId);
+  }
+  /**
+   * Reads one of this chain's backups back out of the destination and compares
+   * it against the record the backup that wrote it left behind.
+   *
+   * @param name - Name the backup is stored under.
+   * @returns The pieces read, the bytes they add up to, and the digest where the backup recorded one.
+   */
+  async verify(name) {
+    return verifyBackupRecord(this.request.destination, await this.chains(), name);
+  }
+  /**
+   * Runs one turn and passes whatever broke it to the operator. A deeper step
+   * announces some failures itself and then raises them, so this announces a
+   * failure only where no step has announced it already. The operator therefore
+   * hears each failure exactly once. Sirannon empties a log the turn has
+   * outgrown once all of that is done, and the report of writes reaching no
+   * backup replaces whatever failure the turn recorded.
+   */
   runTurn(op) {
-    return this.serialise(async () => {
+    return this.turns.run(async () => {
       this.busy = true;
       this.captured = false;
       this.sendRefused = false;
+      this.turnLog.turnStarted();
       try {
         return await op();
+      } catch (err) {
+        if (!this.turnLog.hasAnnounced(err)) this.report(err);
+        throw err;
       } finally {
         if (!this.captured) await this.releaseLogPastLimit();
         this.busy = false;
+        this.turnLog.turnFinished();
       }
     });
   }
@@ -1062,29 +1114,9 @@ var BackupCycle = class {
     }
     return false;
   }
-  /** Passes a skipped turn on, counting the log this node was holding as it skipped. */
+  /** Passes a skipped turn on, where the cycle has a reason to give for it. */
   async reportSkip(skip) {
-    if (!skip || !this.request.onSkip) return;
-    const held = await uncapturedLogBytes(this.logPath);
-    try {
-      this.request.onSkip(held === void 0 ? skip : { ...skip, uncapturedLogBytes: held });
-    } catch {
-    }
-  }
-  serialise(op) {
-    const run = this.inFlight.then(op, op);
-    this.inFlight = run.then(
-      () => {
-      },
-      () => {
-      }
-    );
-    return run;
-  }
-  arm() {
-    if (this.stopped || this.intervalMs <= 0) return;
-    this.timer = setInterval(() => void this.tick(), this.intervalMs);
-    this.timer.unref?.();
+    if (skip) await this.turnLog.skipped(skip);
   }
   async tick() {
     if (this.stopped) return;
@@ -1092,35 +1124,18 @@ var BackupCycle = class {
       await this.reportSkip(previousRunStillActive());
       return;
     }
-    try {
-      await this.runOnce();
-    } catch (err) {
-      this.report(err);
-    }
+    await this.runOnce().catch(() => {
+    });
   }
-  /**
-   * Checks that the destination still lists the chain the state file names,
-   * including one this cycle started itself, because a record appended under a
-   * chain no listing names is a record no restore reaches. A check that cannot
-   * reach the destination leaves the chain unverified for the next turn to try
-   * again before it appends anything.
-   */
   async verifyChain() {
-    if (this.verified || !this.state) return;
-    const request = this.request;
-    const lost = await chainMissingFromList(
-      request.destination,
-      this.chainName,
-      this.state.chainId,
-      request.databaseId,
-      this.state.headIndex
-    );
-    if (!lost) {
-      this.verified = true;
-      return;
-    }
-    await this.discardState();
-    this.report(lost);
+    this.verified = await confirmChainStillListed({
+      request: this.request,
+      chainName: this.chainName,
+      state: this.state,
+      verified: this.verified,
+      discardState: () => this.discardState(),
+      report: (err) => this.report(err)
+    });
   }
   async discardState() {
     const pending = this.state?.pending;
@@ -1131,14 +1146,19 @@ var BackupCycle = class {
    * Runs one turn. A log that restarted before the capture reached it leaves a
    * chain nothing can extend, so this starts a fresh one. The caller still gets
    * the error: those writes are in no backup, and an operator has to hear that.
+   * Where the replacement chain also fails to start, Sirannon records that
+   * second failure against the chain the restart broke, because the cycle holds
+   * no chain of its own by then and an operator reading the status has to know
+   * which one they have lost.
    */
   async turnOrStartOver() {
     try {
       return await this.turn();
     } catch (err) {
       if (startsAFreshChain(err)) {
-        this.report(err);
-        await this.replaceChain().catch((chainErr) => this.report(chainErr));
+        const broken = this.state?.chainId;
+        this.reportAgainstChain(err, broken);
+        await this.replaceChain().catch((chainErr) => this.reportAgainstChain(chainErr, broken));
       }
       throw err;
     }
@@ -1156,58 +1176,46 @@ var BackupCycle = class {
     last = await this.sendWaitingCapture() ?? last;
     return last;
   }
+  /**
+   * Passes a failure to the operator and records it as the turn's outcome.
+   *
+   * @param err - What the turn failed with.
+   * @param chainId - The chain to record it against, which defaults to the one the cycle holds now.
+   */
   report(err) {
-    if (!this.request.onError) return;
-    try {
-      this.request.onError(toBackupError(err));
-    } catch {
-    }
+    this.turnLog.failed(err, this.state?.chainId);
+  }
+  /** Records a failure against a chain the cycle may already have let go of. */
+  reportAgainstChain(err, chainId) {
+    this.turnLog.failed(err, chainId);
   }
   async replaceChain() {
     const previousChainId = this.state?.chainId;
     await this.discardState();
-    const started = await startChain(this.request, this.chainName, this.namePrefix, previousChainId);
+    const begun = await beginReplacementChain(
+      this.request,
+      this.chainName,
+      this.namePrefix,
+      this.stagingDir,
+      previousChainId
+    );
     this.verified = false;
-    this.state = {
-      chainName: this.chainName,
-      chainId: started.chainId,
-      chainStartedAt: started.startedAt,
-      headIndex: started.headIndex,
-      records: 1,
-      cursor: null,
-      pending: null,
-      closedCleanly: false
-    };
-    await writeCycleState(this.stagingDir, this.state);
+    this.state = begun.state;
     this.captured = true;
-    this.request.onRun?.(started.report);
-    return started.report;
+    this.request.onRun?.(begun.report);
+    return begun.report;
   }
   async captureAndCheckpoint() {
     const state = this.state;
     if (!state) return;
-    await this.request.runExclusive(async () => {
-      const captured = await captureLogFrames({
-        sourcePath: this.request.sourcePath,
-        logPath: this.logPath,
-        stagingDir: this.stagingDir,
-        chainId: state.chainId,
-        namePrefix: this.namePrefix,
-        sequence: state.records,
-        cursor: state.cursor,
-        expectNewLog: state.closedCleanly
-      });
-      if (captured) {
-        state.pending = captured;
-        await writeCycleState(this.stagingDir, state);
-      }
-      const checkpointed = (await checkpointLog(this.request.acquireWriter())).emptied;
-      const cursor = captured?.cursor ?? state.cursor;
-      if (cursor) cursor.checkpointed = checkpointed;
-      state.closedCleanly = false;
-      await writeCycleState(this.stagingDir, state);
-      this.captured = true;
+    await captureAndCheckpointTurn({
+      request: this.request,
+      state,
+      logPath: this.logPath,
+      stagingDir: this.stagingDir,
+      namePrefix: this.namePrefix
     });
+    this.captured = true;
   }
   /**
    * Sends the capture staged against the chain this cycle holds. A turn offers
@@ -1314,7 +1322,7 @@ function nodeBackupEngine(streaming) {
     copyToDestination: (conn, request) => manager.copyToDestination(conn, request),
     streamsToDestination: () => manager.streamsToDestination(),
     createCycle: (request) => createBackupCycle(request),
-    schedule: (conn, options, runExclusive) => scheduler.schedule(conn, options, runExclusive)
+    schedule: (conn, request) => scheduler.schedule(conn, request)
   };
 }