telstore 0.1.8 → 0.1.10

package/src/commands/verify.js

@@ -0,0 +1,294 @@
+import { chatName, describeChat } from '../chat.js'
+import {
+  MESSAGE_BATCH_SIZE,
+  closeQuietly,
+  connect as realConnect,
+  documentFileName,
+  documentSize,
+  findManifestMessage,
+  getDocuments as realGetDocuments,
+  readMessageBytes as realReadMessageBytes,
+} from '../client.js'
+import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { chunkFileName, manifestFileName, parseManifest } from '../manifest.js'
+import { formatBytes, formatDuration, plural } from '../progress.js'
+import { assertLoggedIn } from '../session.js'
+import { requireChat, resolveSettings } from '../settings.js'
+
+// parseManifest guarantees every number in a manifest, but not the file name — it is
+// decoration, and nothing verifies differently because of it. It is still text off a chat.
+function describeName(name) {
+  return typeof name === 'string' && name.trim() !== '' ? name : '—'
+}
+
+// What is wrong with one chunk, or null when nothing is. The first failing check wins: a
+// chunk is damaged or it is not, and listing three complaints about one message would make
+// "2 damaged" mean something other than two chunks.
+//
+// Every question here is one the chat can answer without sending a byte of the file. What
+// this cannot ask is whether the bytes inside are the bytes that went up — only downloading
+// them answers that, which is why the closing line says so rather than leaving it implied.
+function inspect(chunk, message, { backupId, total, chat }) {
+  const at = `Chunk ${chunk.i + 1}/${total}`
+
+  if (!message) {
+    return `${at} is gone: message ${chunk.msgId} is no longer in ${chatName(chat)}.`
+  }
+
+  const size = documentSize(message)
+
+  if (size === null) {
+    return `${at} is message ${chunk.msgId}, which has no file attached.`
+  }
+
+  const wanted = chunkFileName(backupId, chunk.i)
+  const fileName = documentFileName(message)
+
+  if (fileName !== wanted) {
+    return fileName === null
+      ? `${at} is message ${chunk.msgId}, whose file carries no name; the manifest expects ` +
+          `"${wanted}".`
+      : `${at} is message ${chunk.msgId}, which carries the file name ` +
+          `${JSON.stringify(fileName)} rather than "${wanted}".`
+  }
+
+  if (size !== chunk.size) {
+    return `${at} is ${size} bytes in the chat, the manifest records ${chunk.size}.`
+  }
+
+  return null
+}
+
+export async function runVerify(backupId, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    searchManifest = findManifestMessage,
+    readMessageBytes = realReadMessageBytes,
+    getDocuments = realGetDocuments,
+    retryOptions = {},
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  const config = await loadConfig(configDir)
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  // Ask about the login before the destination, as list does: telling someone who has never
+  // logged in to pick a chat sends them off after the wrong thing.
+  assertLoggedIn(config)
+  const chat = requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  // Upload and restore stay quiet until the third retry so a handful of -503s do not bury
+  // the progress bar. There is no bar here to bury — this command sends a handful of small
+  // requests and prints one verdict — so a wait long enough to notice is announced at once.
+  function onRetry(err, attempt, delayMs) {
+    warn(
+      `\nTemporary error (${err.message}), retry ${attempt} in ` +
+        `${formatDuration(delayMs / 1000)}.\n`,
+    )
+  }
+
+  const client = await connect(config, { verbose: settings.verbose })
+
+  try {
+    const manifestMessage = await searchManifest(client, chat, backupId)
+
+    if (!manifestMessage) {
+      throw new Error(
+        `No backup ${backupId} found in ${chatName(chat)}. Check the id with ` +
+          '"npx telstore list", or use --chat to point at the right chat.',
+      )
+    }
+
+    // The full layout checks, not the lenient path delete takes. delete reads a manifest to
+    // destroy what it names, so a broken one is exactly what somebody is there to remove;
+    // verify reads it to answer whether restore would work, and restore would refuse this
+    // one. Saying so in parseManifest's own words keeps one description of one fault.
+    const manifest = parseManifest(await readMessageBytes(client, manifestMessage))
+
+    // The same refusal delete makes, for the same reason from the other side: the manifest
+    // was found by the file name telstore wrote, so a body naming another backup is a file
+    // that was renamed or replaced, and its message ids describe somebody else's chunks.
+    // Reporting those as this backup's health is the one wrong answer this command can give.
+    if (manifest.id !== undefined && manifest.id !== backupId) {
+      throw new Error(
+        `The manifest named ${manifestFileName(backupId)} describes backup ` +
+          `${JSON.stringify(manifest.id)}, not ${backupId}. Its message ids point at another ` +
+          `backup's chunks, so telstore cannot say whether ${backupId} is still there.`,
+      )
+    }
+
+    const total = manifest.chunks.length
+
+    log(`Backup ${backupId}`)
+    log(
+      `File   ${describeName(manifest.name)} ` +
+        `(${formatBytes(manifest.size)}, ${plural(total, 'chunk')})`,
+    )
+    log(`In     ${describeChat(chat)}`)
+    log('')
+
+    // A backup at the 10000-chunk ceiling is a hundred requests, sent one at a time. Silence
+    // for that long reads as a hang, which is the one thing no wait in this project may look
+    // like — and below a single request there is no progress worth a line.
+    const loud = total > MESSAGE_BATCH_SIZE
+
+    const found = await getDocuments(
+      client,
+      chat,
+      manifest.chunks.map((chunk) => chunk.msgId),
+      {
+        retryOptions: { ...retryOptions, onRetry },
+        onBatch: (done, all) => {
+          if (loud) warn(`\rChecking chunk messages ${done}/${all}…`)
+        },
+      },
+    )
+
+    if (loud) warn('\n')
+
+    const damaged = []
+
+    for (const chunk of manifest.chunks) {
+      const fault = inspect(chunk, found.get(chunk.msgId), { backupId, total, chat })
+
+      if (fault) {
+        damaged.push(fault)
+        log(fault)
+      }
+    }
+
+    if (damaged.length > 0) {
+      log('')
+      log(
+        `${plural(total, 'chunk')} checked, ${damaged.length} damaged. ` +
+          'This backup cannot be restored.',
+      )
+    } else {
+      log(
+        `${plural(total, 'chunk')} present, at the ` +
+          `${total === 1 ? 'size' : 'sizes'} the manifest records.`,
+      )
+      log('This does not download them, so it cannot prove their contents.')
+      log('')
+      log(`Restore with: npx telstore restore ${backupId}`)
+    }
+
+    return { id: backupId, name: manifest.name, chunks: total, damaged }
+  } finally {
+    await closeQuietly(client, disconnect)
+  }
+}
+
+// A backup is a failure whether telstore could not look it up or looked and found it broken.
+// The command worked either way — but "did the run find everything it was asked to check"
+// is the question the exit code answers, and both answers to that are no.
+function isFailure(result) {
+  return Boolean(result.error) || result.damaged.length > 0
+}
+
+// The same shape as runDeletes and runRestores, minus the question: verify removes nothing,
+// so there is nothing to authorise. What is knowable before the connection is refused up
+// front; what only the chat can answer is per id, named when it happens and again at the end.
+export async function runVerifies(backupIds, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  // One id keeps its own wording and its own thrown error. A summary about one backup only
+  // repeats the lines above it.
+  if (backupIds.length === 1) {
+    const result = await runVerify(backupIds[0], options, deps)
+    return { results: [result], failed: isFailure(result) ? 1 : 0 }
+  }
+
+  const duplicate = backupIds.find((id, index) => backupIds.indexOf(id) !== index)
+
+  if (duplicate) {
+    throw new Error(
+      `${duplicate} is named twice. Checking one backup twice asks the chat the same ` +
+        'question again — name it once.',
+    )
+  }
+
+  const config = await loadConfig(configDir)
+
+  assertLoggedIn(config)
+
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  const chat = requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  let shared = null
+  const perId = {
+    ...deps,
+    connect: async (theirConfig, connectOptions) =>
+      (shared ??= await connect(theirConfig, connectOptions)),
+    disconnect: async () => {},
+  }
+
+  const results = []
+
+  try {
+    await perId.connect(config, { verbose: settings.verbose })
+
+    for (const [index, backupId] of backupIds.entries()) {
+      if (index > 0) log('')
+      log(`[${index + 1}/${backupIds.length}] ${backupId}`)
+
+      try {
+        results.push(await runVerify(backupId, options, perId))
+      } catch (err) {
+        // Unlike delete, an id nothing knows about does not stop the run: nothing here is
+        // destroyed, and the other ids are exactly the ones somebody is checking on.
+        results.push({ id: backupId, error: err.message, damaged: [] })
+        warn(`\n${backupId} failed: ${err.message}\n`)
+      }
+    }
+  } finally {
+    if (shared) {
+      await closeQuietly(shared, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+
+  const failed = results.filter(isFailure).length
+
+  log('')
+  for (const line of summaryLines(results, failed)) log(line)
+
+  return { results, failed }
+}
+
+// Every id gets a line whether it checked out or not: one missing from this list would be a
+// backup nobody could tell the state of, which is the whole reason this command exists.
+function summaryLines(results, failed) {
+  const width = Math.max(...results.map((result) => result.id.length))
+
+  return [
+    `${results.length} backups: ${results.length - failed} verified, ${failed} failed.`,
+    '',
+    ...results.map((result) => {
+      const id = result.id.padEnd(width)
+
+      if (result.error) return `  ${id}  failed: ${result.error}`
+
+      return result.damaged.length > 0
+        ? `  ${id}  ${plural(result.damaged.length, 'chunk')} damaged`
+        : `  ${id}  ${plural(result.chunks, 'chunk')} present`
+    }),
+  ]
+}

package/src/manifest.js

@@ -11,12 +11,69 @@ export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).t
   return `telstore-${yyyy}${mm}${dd}-${randomHex()}`
 }
 
+// The day a backup id carries, as the UTC second that day began. newBackupId stamps it above
+// from the clock of the machine making the backup, so it is that machine's idea of the day
+// rather than Telegram's — which is why the one reader of this (delete's walk of the chat)
+// gives it a day of slack and only ever uses it as a floor.
+//
+// A date that does not exist is not a day: `telstore-20269999-abc` would otherwise roll over
+// into a year's time and read as a floor above everything in the chat, which is an early stop
+// nobody would see. Null instead, and the caller falls back to a bound it can prove.
+const BACKUP_ID_DAY = /^telstore-(\d{4})(\d{2})(\d{2})-[0-9a-f]+$/
+
+export function backupIdDay(id) {
+  const match = BACKUP_ID_DAY.exec(String(id))
+
+  if (!match) return null
+
+  const [year, month, day] = match.slice(1).map(Number)
+  const at = new Date(Date.UTC(year, month - 1, day))
+
+  if (at.getUTCFullYear() !== year || at.getUTCMonth() !== month - 1 || at.getUTCDate() !== day) {
+    return null
+  }
+
+  return Math.floor(at.getTime() / 1000)
+}
+
+// The infix in every chunk's file name. A constant rather than a literal for the same reason
+// MANIFEST_SUFFIX is one: there are two readers of that name now — the writer below and
+// isChunkFileName — and a reader that disagrees with the writer by one character finds
+// nothing at all.
+const CHUNK_INFIX = '.part'
+
 export function chunkFileName(id, i) {
-  return `${id}.part${String(i + 1).padStart(4, '0')}`
+  return `${id}${CHUNK_INFIX}${String(i + 1).padStart(4, '0')}`
 }
 
+// Whether a document in a chat is a chunk of this backup, decided by the file name telstore
+// itself wrote and not by the caption beside it — the rule findManifestMessage already keeps,
+// for the same reason: a caption is text a person can edit and a file name is not.
+//
+// The number is checked but never read back. What the caller needs is which backup a document
+// belongs to, and a chunk whose index says something impossible is still that backup's chunk.
+// What the check is for is the other direction: without it `<id>.partial` or `<id>.part.bak`
+// — names telstore never writes, but names a person can give a file they upload themselves —
+// would be read as chunks of a backup and destroyed along with it.
+export function isChunkFileName(id, fileName) {
+  if (typeof fileName !== 'string') return false
+
+  const prefix = `${id}${CHUNK_INFIX}`
+
+  if (!fileName.startsWith(prefix)) return false
+
+  const number = fileName.slice(prefix.length)
+
+  return number.length > 0 && /^[0-9]+$/.test(number)
+}
+
+// The suffix telstore has written on every manifest since version 1, and what `list` picks
+// a manifest out of a chat by. One definition, because a reader that disagrees with the
+// writer by one character finds nothing at all.
+export const MANIFEST_SUFFIX = '.manifest.json'
+
 export function manifestFileName(id) {
-  return `${id}.manifest.json`
+  return `${id}${MANIFEST_SUFFIX}`
 }
 
 export function buildManifest({

package/src/progress.js

@@ -47,6 +47,57 @@ export function renderProgress({ done, total, elapsedMs, label, width = 24, tran
   return `${label} ${bar} ${percent}% ${formatBytes(done)}/${formatBytes(total)} ${speed} ETA ${formatDuration(remaining)}`
 }
 
+// A percentage of an unknown total is an invented number, and an ETA from one is worse: it
+// would count down to a finish nobody can predict.
+export function renderStreamProgress({ done, elapsedMs, label }) {
+  const bytesPerSecond = elapsedMs > 0 ? done / (elapsedMs / 1000) : 0
+
+  return `${label} ${formatBytes(done)} sent ${formatBytes(Math.round(bytesPerSecond))}/s`
+}
+
+export function createStreamProgress({
+  label,
+  write = (line) => process.stderr.write(line),
+  now = () => Date.now(),
+  minIntervalMs = 200,
+}) {
+  const startedAt = now()
+  let done = 0
+  let currentLabel = label
+  let lastDrawnAt = startedAt
+  let widestLine = 0
+
+  // Same \r discipline as createProgress: a redraw shorter than the one before it would
+  // leave the previous line's tail on screen, so pad every line out to the widest drawn so far.
+  function draw(suffix) {
+    const line = renderStreamProgress({ done, elapsedMs: now() - startedAt, label: currentLabel })
+    widestLine = Math.max(widestLine, line.length)
+    write(`\r${line.padEnd(widestLine)}${suffix}`)
+  }
+
+  return {
+    advance(bytes) {
+      done += bytes
+      if (now() - lastDrawnAt < minIntervalMs) return
+      lastDrawnAt = now()
+      draw('')
+    },
+    setLabel(next) {
+      currentLabel = next
+      lastDrawnAt = now()
+      draw('')
+    },
+    finish() {
+      draw('\n')
+    },
+  }
+}
+
+// A number turned into words a person reads: "1 chunk" for one, "3 chunks" for the rest.
+export function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`
+}
+
 export function createProgress({
   total,
   label,
@@ -99,3 +150,38 @@ export function createProgress({
     },
   }
 }
+
+// A walk of one page is over in about the time it takes to notice — 165ms against a real
+// chat — and that is the usual case, so nothing is drawn for the first stretch: a line that
+// appears and is wiped in the same breath is a flicker, not information. Past that the read
+// is long enough that silence reads as the hang this project refuses everywhere else.
+//
+// \r only moves the cursor home, so every line is padded to the widest one drawn and the last
+// write wipes the row: whatever the command prints next must never land on half a notice.
+//
+// Here rather than beside either caller: `list` walks a chat to find backups and `delete`
+// walks it to find chunks nothing on this machine names, and two copies of "when is a read
+// long enough to say something about" is how they start disagreeing about it.
+const NOTICE_QUIET_MS = 400
+const NOTICE_INTERVAL_MS = 200
+
+export function createWalkNotice({ write, now, quietMs = NOTICE_QUIET_MS, intervalMs = NOTICE_INTERVAL_MS }) {
+  const startedAt = now()
+  let lastDrawnAt = 0
+  let widest = 0
+
+  return {
+    tick(text) {
+      if (now() - startedAt < quietMs) return
+      if (lastDrawnAt !== 0 && now() - lastDrawnAt < intervalMs) return
+
+      lastDrawnAt = now()
+      widest = Math.max(widest, text.length)
+      write(`\r${text.padEnd(widest)}`)
+    },
+    clear() {
+      if (widest === 0) return
+      write(`\r${' '.repeat(widest)}\r`)
+    },
+  }
+}

package/src/shell.js

@@ -0,0 +1,33 @@
+// A command meant to be pasted has to survive the shell that receives it: anything a shell
+// would take apart comes back quoted, and a path with a space in it is the ordinary case,
+// not an exotic one. `status` and `down` both print resume commands, and two copies of this
+// rule is how they start disagreeing about which paths are safe to print bare.
+const BARE_ARG = /^[A-Za-z0-9_@%+:,./-]+$/
+
+export function shellArg(text) {
+  const value = String(text)
+
+  return BARE_ARG.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`
+}
+
+// The one line in telstore that destroys data when it is wrong. `delete` resolves its own
+// destination from config and then fires the recorded message ids at whatever peer that turns
+// out to be, so a command pasted next week — or one built here under a `--chat` this run was
+// given — would remove whatever happens to carry those ids in the chat it resolves. Naming a
+// chat that turns out to be the default costs a few characters; leaving it out when it is not
+// costs somebody else's messages, and nothing undoes that. Four commands print this string
+// (`upload-stream`'s rollback, `cli`'s second Ctrl-C, `status`, `down`) and they had four
+// copies of the rule, which is how three of them stayed right and one drifted.
+//
+// The chatless branch is not a convenience: it is for the single caller that genuinely does
+// not know where the chunks went. `bin/telstore.js` holds the chat the run handed it, and a
+// Ctrl-C arriving before the run ever reported one leaves the id — the only part of the
+// message with any value — rather than printing `--chat undefined`, which `delete` would read
+// as no destination at all while looking like one. A caller that would rather print nothing
+// than a command missing its chat decides that for itself before calling: `down` does, and
+// says why beside its own check.
+export function deleteCommand(id, chat) {
+  const where = chat === null || chat === undefined ? '' : String(chat).trim()
+
+  return `npx telstore delete ${shellArg(id)}${where === '' ? '' : ` --chat ${shellArg(where)}`}`
+}

package/src/spawn.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process'
+
+// stderr is inherited, never captured: when a producer command fails it explains itself in
+// its own words, on the stream the user is already watching. telstore adds the exit code
+// and what it did about it, and does not paraphrase.
+//
+// `exited` can be built before the caller has any chance to await it — the caller reads
+// `stdout` first, and only awaits `exited` once the stream ends. A rejected promise with no
+// handler attached yet makes Node report an unhandledRejection, so a no-op `.catch` is
+// attached here immediately. That does not consume the rejection: the `exited` this function
+// returns is the same promise, and `await`ing it later still resolves or rejects exactly as
+// it would have.
+export function spawnProducer(argv, { stdio = ['ignore', 'pipe', 'inherit'] } = {}) {
+  const [command, ...args] = argv
+  const child = spawn(command, args, { stdio })
+
+  const exited = new Promise((resolve, reject) => {
+    child.on('error', (err) => {
+      reject(
+        new Error(
+          err.code === 'ENOENT'
+            ? `Cannot run ${command}: no such command on this machine.`
+            : `Cannot run ${command}: ${err.message}`,
+        ),
+      )
+    })
+
+    child.on('close', (code, signal) => resolve({ code, signal }))
+  })
+  exited.catch(() => {})
+
+  return {
+    stdout: child.stdout,
+    stdin: child.stdin,
+    exited,
+    kill: (signal = 'SIGTERM') => child.kill(signal),
+  }
+}

package/src/state.js

@@ -8,6 +8,69 @@ export function stateDir(configDir = defaultConfigDir()) {
   return path.join(configDir, 'state')
 }
 
+// The other thing telstore keeps on this machine, and the only one that is not a record: a
+// stream upload borrows one chunk of disk at a time here while it sends it. Under
+// ~/.telstore rather than os.tmpdir() because /tmp is tmpfs on many Linux distributions, and
+// "borrow one chunk of disk" would silently mean "borrow 1800MB of RAM" — a memory limit
+// dressed up as a chunk size.
+//
+// It lives beside stateDir because it answers the same question — what has this machine got
+// of telstore's on it — and because `status` has to be able to ask without importing the
+// upload command, which would drag a second upload loop and teleproto in with it.
+export function tempDirFor(configDir = defaultConfigDir()) {
+  return path.join(configDir, 'tmp')
+}
+
+// What is in there now. A run removes its own chunk file on every ending it gets to run code
+// for, so a file here is either a run happening at this moment or a run that was stopped
+// where it stood — a SIGKILL, a crash, a machine losing power. Nothing here removes them:
+// from outside the run that owns one, those two cases look exactly the same, and deleting
+// the chunk a live upload is filling is the confident wrong thing this project refuses
+// everywhere else. Naming them is the whole job.
+//
+// A stat that fails yields an unknown size rather than a dropped row, the same care
+// listStates takes with mtimes: the file really can vanish between the readdir and the stat —
+// that is what a run finishing normally does — and status is the command someone runs
+// *because* something is wrong.
+export async function listTempChunks(configDir = defaultConfigDir()) {
+  const dir = tempDirFor(configDir)
+  let names
+
+  try {
+    names = await fs.readdir(dir)
+  } catch (err) {
+    // A machine that has never made a backup from a command has no such directory, and that
+    // is not a fault to report. Anything else is: a directory telstore cannot read may be
+    // holding a whole chunk, and answering "nothing there" would be the silent wrong answer
+    // this listing exists to prevent. The caller decides what to do with it.
+    if (err.code === 'ENOENT') return []
+
+    throw err
+  }
+
+  const found = []
+
+  for (const name of names.sort()) {
+    const file = path.join(dir, name)
+    let size = null
+
+    try {
+      const stat = await fs.stat(file)
+
+      if (!stat.isFile()) continue
+
+      size = stat.size
+    } catch {
+      // Gone or unreadable between the readdir and here. Still a name worth printing: the
+      // point of the listing is that nothing telstore left behind goes unmentioned.
+    }
+
+    found.push({ name, file, size })
+  }
+
+  return found
+}
+
 export function stateKey(absPath, size, mtimeMs) {
   return createHash('sha1').update(`${absPath}:${size}:${mtimeMs}`).digest('hex')
 }
@@ -16,6 +79,14 @@ export function stateFile(key, configDir = defaultConfigDir()) {
   return path.join(stateDir(configDir), `${key}.json`)
 }
 
+// stateKey hashes path:size:mtime, and a stream has none of the three. What holds still is
+// the backup id, and hashing it keeps the file name in the same 40-hex shape the directory
+// already sorts, prunes and filters on — a stream record is an upload record, not a third
+// kind, so it shares that namespace rather than getting a prefix of its own.
+export function streamKey(backupId) {
+  return createHash('sha1').update(`stream:${backupId}`).digest('hex')
+}
+
 // A restore's record is filed beside the uploads and must never compete with them for a
 // prune slot. Losing an upload record strands chunks in a chat where only the id can still
 // find them, which is why pruneStates reads each file back to name what it drops; losing a
@@ -218,6 +289,13 @@ export async function findStates(backupId, configDir = defaultConfigDir()) {
 // Never throws. status calls this for every record it prints, and one damaged path must not
 // take the rest of the report down with it.
 export async function canResume(key, state) {
+  // A stream cannot be resumed by anyone, so this is not a question about a file. Answering
+  // it by stat-ing state.path would report "missing" for a record that never had a path,
+  // and status would then offer a resume command that starts a brand new backup. This has
+  // to run before the stat below, not after it fails: a stream record's key could still
+  // happen to match a real file on disk, and that file is not what makes it unresumable.
+  if (state.kind === 'stream') return { ok: false, reason: 'stream' }
+
   let stat
 
   try {