@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

package/src/projection/obsidian/publication/transport.mjs

@@ -0,0 +1,139 @@
+import { execFile, execFileSync } from 'node:child_process'
+import { POLICY_SETTINGS_PATH, buildEvalCode, createInProcessHost, runInProcess, validatePayload } from './bridge-script.mjs'
+
+// Editor coordination adapter.
+//
+//   adapter.probe({ vaultRoot })  -> { state: 'coordinated' | 'absent' | 'uncoordinated', reason }
+//   adapter.inspect(payload)      -> reply          read-only, may retry
+//   adapter.collect(payload)      -> reply          read-only, may retry
+//   adapter.publish(payload)      -> reply          sent at most once
+//
+// A raw `call(payload)` sends one payload once and resolves with the parsed
+// reply. It throws TransportTimeout when the reply did not arrive in time and
+// any other error when the call could not be made. createEditorAdapter adds
+// the rules every transport must follow: calls are serialized, read-only calls
+// may retry, and a publish is never resent. When a publish reply is lost the
+// recorded outcome is re-read from the app; when none is recorded the caller
+// is told so and reconciles from the files themselves.
+
+export class TransportTimeout extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'TransportTimeout'
+    this.code = 'transport-timeout'
+  }
+}
+
+const READ_RETRIES = 2
+
+export function createEditorAdapter({ call, processProbe, kind = 'custom' }) {
+  if (typeof call !== 'function') throw new TypeError('createEditorAdapter needs a call function')
+  if (typeof processProbe !== 'function') throw new TypeError('createEditorAdapter needs a processProbe function')
+  const retries = []
+  let tail = Promise.resolve()
+  const serialized = (operation) => {
+    const next = tail.then(operation, operation)
+    tail = next.catch(() => {})
+    return next
+  }
+  const readOnly = async (payload) => {
+    for (let attempt = 0; ; attempt += 1) {
+      try { return await call(validatePayload(payload)) } catch (error) {
+        if (attempt >= READ_RETRIES || !(error instanceof TransportTimeout)) throw error
+        retries.push(payload.op)
+      }
+    }
+  }
+  return {
+    kind,
+    transportRetries: retries,
+    inspect: (payload) => serialized(() => readOnly({ ...payload, op: 'inspect' })),
+    collect: (payload) => serialized(() => readOnly({ ...payload, op: 'collect' })),
+    publish: (payload) => serialized(async () => {
+      validatePayload(payload)
+      if (payload.op !== 'publish') throw new TypeError('publish needs a publish payload')
+      try { return await call(payload) } catch (error) {
+        retries.push(error instanceof TransportTimeout ? 'publish-reply-lost' : 'publish-call-failed')
+        let record = null
+        try { record = await readOnly({ op: 'collect', vaultRoot: payload.vaultRoot, path: payload.path }) } catch { /* the app is not answering */ }
+        if (record && record.operationId === payload.operationId && typeof record.outcome === 'string') return { ...record, status: record.outcome, replyLost: true }
+        return { status: 'outcome-unknown', operationId: payload.operationId, wrote: null, replyLost: true, transportError: String(error.message || error).slice(0, 300) }
+      }
+    }),
+    // Path selection. `absent` is returned only when the process probe says,
+    // positively, that no Obsidian is running. A running or unknowable app
+    // that does not answer for this exact vault is `uncoordinated`.
+    probe: ({ vaultRoot }) => serialized(async () => {
+      let processes
+      try { processes = await processProbe() } catch { processes = 'unknown' }
+      if (processes === 'absent') return { state: 'absent', reason: 'no Obsidian process is running' }
+      try {
+        const reply = await readOnly({ op: 'inspect', vaultRoot, path: POLICY_SETTINGS_PATH })
+        // `path-unsafe` for the probe path still proves the app answered for this vault; the settings unit reports the path.
+        if (['inspected', 'path-unsafe'].includes(reply.status) && reply.vaultBasePath === vaultRoot) return { state: 'coordinated', reason: 'the app answered for this vault' }
+        return { state: 'uncoordinated', reason: reply.status === 'vault-mismatch' ? 'the app answered for another vault' : `the app answered ${reply.status}` }
+      } catch (error) {
+        return { state: 'uncoordinated', reason: `an Obsidian process may be running and the bridge did not answer: ${String(error.message || error).slice(0, 200)}` }
+      }
+    }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// In-process transport: the same script, run here. Used for the path with no
+// app, and by tests that supply a host modelling an app.
+// ---------------------------------------------------------------------------
+
+export function createInProcessCall(host = createInProcessHost()) {
+  return async (payload) => runInProcess(payload, host)
+}
+
+export function createDirectAdapter({ crashSeam } = {}) {
+  return createEditorAdapter({ call: createInProcessCall(createInProcessHost({ crashSeam })), processProbe: () => 'absent', kind: 'direct' })
+}
+
+// ---------------------------------------------------------------------------
+// Obsidian CLI transport
+// ---------------------------------------------------------------------------
+
+export function defaultCliPath(platform = process.platform) {
+  if (platform === 'darwin') return '/Applications/Obsidian.app/Contents/MacOS/obsidian-cli'
+  return 'obsidian-cli'
+}
+
+// The CLI reaches the app through a socket under $HOME, so `env` selects the
+// app instance. It is passed explicitly and never edited here. A call that
+// outlives its timeout is killed with SIGKILL: the CLI ignores SIGTERM while
+// it waits on the app.
+export function createObsidianCliCall({ cliPath = defaultCliPath(), env = process.env, timeoutMs = 20000 } = {}) {
+  return (payload) => new Promise((resolve, reject) => {
+    execFile(cliPath, ['eval', `code=${buildEvalCode(payload)}`], { env, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) return reject(error.killed ? new TransportTimeout(`CLI call timed out: ${payload.op}`) : new Error(`CLI call failed: ${String(error.message).slice(0, 300)}`))
+      const out = stdout || stderr || ''
+      const start = out.indexOf('=> ')
+      if (start < 0) return reject(new Error(`bridge returned no value: ${JSON.stringify(out.slice(0, 300))}`))
+      try { return resolve(JSON.parse(out.slice(start + 3))) } catch { return reject(new Error('bridge returned a value that is not JSON')) }
+    })
+  })
+}
+
+// Default process probe: 'absent' only when the process table was read and
+// holds no Obsidian. Limits: it sees this machine's processes as this user
+// can list them; it cannot see an app on another machine that reaches the
+// vault through a shared or synchronized folder, an app packaged under another
+// executable name, or an app that starts after the probe. Anything it cannot
+// establish is 'unknown', which the adapter treats as a running app.
+export function defaultObsidianProcessProbe({ platform = process.platform, run = execFileSync } = {}) {
+  if (platform !== 'darwin' && platform !== 'linux') return 'unknown'
+  try {
+    const table = run('/bin/ps', ['-A', '-o', 'args='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 })
+    if (typeof table !== 'string' || table.trim() === '') return 'unknown'
+    return /(^|[\\/ ])obsidian(\.app|\.exe|-cli)?([\\/ ]|$)/im.test(table.split('\n').filter((line) => !line.includes('/bin/ps')).join('\n')) ? 'running' : 'absent'
+  } catch {
+    return 'unknown'
+  }
+}
+
+export function createObsidianCliAdapter({ cliPath, env, timeoutMs, processProbe = () => defaultObsidianProcessProbe() } = {}) {
+  return createEditorAdapter({ call: createObsidianCliCall({ cliPath, env, timeoutMs }), processProbe, kind: 'obsidian-cli' })
+}

package/src/projection/obsidian/recovery/index.mjs

@@ -0,0 +1,6 @@
+// Recovery state for Obsidian publication: the immutable store, the durable
+// journal, restart recovery and the late-writer re-check.
+export { EXCHANGE_CANDIDATE_NAME, LATE_EXCHANGE_CANDIDATE_NAME, PublicationRefusal, VAULT_LOCK_DIRECTORY, acquireVaultLock, createRecoveryStore, readFileDigest, sha256Digest } from './store.mjs'
+export { JOURNAL_SCHEMA, createJournal, journalDetail, listJournals, newJournalId } from './journal.mjs'
+export { classifyCandidateFile, namedCandidates, publishedSinceCommit, reconcileUnit, recoverPublications, retireStagedFile } from './restart.mjs'
+export { recheckDisplacedFiles } from './late-writer.mjs'

package/src/projection/obsidian/recovery/journal.mjs

@@ -0,0 +1,134 @@
+import { randomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { isPendingPrivateWrite, publishPrivateFile } from '../../../project/durable-state.mjs'
+import { readRegularTextNoFollow } from '../../../project/private-state.mjs'
+import { OBSIDIAN_EXT_KEY, assertObsidianContract } from '../contracts.mjs'
+import { refuse } from './store.mjs'
+
+// Durable publication journal. The registered shape is one document; on disk
+// it is a header plus one immutable file per entry, each published atomically
+// under a name that is never overwritten, so an entry is either wholly present
+// or absent and history cannot be rewritten in place. The document is
+// assembled from those files and validated against the registered schema every
+// time it is read or extended.
+//
+// Entry steps follow the schema: `capture` (the write-ahead record binding a
+// note to its base, candidate, staged file and recovery path, written before
+// anything is exchanged), `conditional-update` (the exchange, exclusive
+// create or conditional removal and its outcome), `verify`, `manifest-commit`
+// and `restart`. Each entry file also carries the journal state that holds
+// after it.
+
+export const JOURNAL_SCHEMA = 'atelier-obsidian-publication-journal/v1'
+const ENTRY_FILE = /^\d{8}\.json$/
+const CLOSED_FILE = 'closed.json'
+
+const isoTime = (clock) => {
+  const value = clock()
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) throw new TypeError('the clock did not return a time')
+  return date.toISOString()
+}
+
+export function newJournalId(clock = () => new Date()) {
+  return `journal-${isoTime(clock).replace(/[-:.TZ]/g, '')}-${randomBytes(4).toString('hex')}`
+}
+
+function load(directory) {
+  const header = JSON.parse(readRegularTextNoFollow(path.join(directory, 'header.json')))
+  const entriesDir = path.join(directory, 'entries')
+  const names = fs.existsSync(entriesDir) ? fs.readdirSync(entriesDir).filter((name) => !isPendingPrivateWrite(name)).sort() : []
+  const records = names.map((name, index) => {
+    if (!ENTRY_FILE.test(name) || Number(name.slice(0, 8)) !== index) refuse('journal-corrupt', 'journal entries are not a contiguous sequence; preserve and inspect')
+    const record = JSON.parse(readRegularTextNoFollow(path.join(entriesDir, name)))
+    if (record.entry?.seq !== index) refuse('journal-corrupt', 'a journal entry does not carry its own sequence number')
+    return record
+  })
+  return { header, records }
+}
+
+function assemble({ header, records }) {
+  const restarts = records.filter((record) => record.entry.step === 'restart' && record.entry.ext?.[OBSIDIAN_EXT_KEY]?.phase === 'begin')
+  const document = {
+    ...header,
+    state: records.length > 0 ? records.at(-1).state : 'prepared',
+    entries: records.map((record) => record.entry),
+    restart: { count: restarts.length, ...(restarts.length > 0 ? { lastRecoveredAt: restarts.at(-1).entry.at } : {}) },
+  }
+  return assertObsidianContract('publication-journal', document)
+}
+
+function handle(store, directory, clock) {
+  // One writer at a time extends a journal (the publisher holds the view's
+  // lock), so the entries read once stay the entries on disk.
+  let cached = null
+  const current = () => (cached ??= load(directory))
+  const journal = {
+    directory,
+    document: () => assemble(current()),
+    // detail lands under the entry's ext container; the rest are schema fields.
+    append({ step, outcome, state, notePath, beforeDigest, afterDigest, recoveryRef, detail }) {
+      const loaded = current()
+      const entry = {
+        seq: loaded.records.length,
+        at: isoTime(clock),
+        step,
+        outcome,
+        ...(notePath === undefined ? {} : { notePath }),
+        ...(beforeDigest ? { beforeDigest } : {}),
+        ...(afterDigest ? { afterDigest } : {}),
+        ...(recoveryRef ? { recoveryRef } : {}),
+        ...(detail ? { ext: { [OBSIDIAN_EXT_KEY]: detail } } : {}),
+      }
+      const record = { entry, state: state ?? (loaded.records.at(-1)?.state ?? 'prepared') }
+      assemble({ header: loaded.header, records: [record] })
+      try {
+        publishPrivateFile(path.join(directory, 'entries', `${String(entry.seq).padStart(8, '0')}.json`), `${JSON.stringify(record, null, 2)}\n`)
+      } catch (error) {
+        cached = null
+        throw error
+      }
+      loaded.records.push(record)
+      return entry
+    },
+    // A journal that can no longer matter (committed, or superseded by a later
+    // commit) is closed so that later runs do not read it again. The flag file
+    // is advisory: a journal without one is simply read and judged again.
+    close() {
+      try { publishPrivateFile(path.join(directory, CLOSED_FILE), `${JSON.stringify({ state: assemble(current()).state })}\n`) } catch (error) { if (error.code !== 'EEXIST') throw error }
+    },
+  }
+  return journal
+}
+
+export function createJournal(store, { journalId, protocolId, expectedGeneration, targetGeneration, detail, clock = () => new Date() }) {
+  const directory = store.journalDir(journalId)
+  fs.mkdirSync(path.join(directory, 'entries'), { recursive: true, mode: 0o700 })
+  const header = {
+    schema: JOURNAL_SCHEMA,
+    contractVersion: '1.0.0',
+    journalId,
+    workspaceId: store.workspaceId,
+    scopeId: store.scopeId,
+    protocolId,
+    expectedGeneration,
+    targetGeneration,
+    ...(detail ? { ext: { [OBSIDIAN_EXT_KEY]: detail } } : {}),
+  }
+  assemble({ header, records: [] })
+  publishPrivateFile(path.join(directory, 'header.json'), `${JSON.stringify(header, null, 2)}\n`)
+  return handle(store, directory, clock)
+}
+
+// Journals of this view, oldest first. A directory without a header is a
+// journal that never began: nothing can refer to it.
+export function listJournals(store, { clock = () => new Date(), openOnly = false } = {}) {
+  if (!fs.existsSync(store.journalsRoot)) return []
+  return fs.readdirSync(store.journalsRoot).sort()
+    .filter((name) => fs.existsSync(path.join(store.journalsRoot, name, 'header.json')))
+    .filter((name) => !openOnly || !fs.existsSync(path.join(store.journalsRoot, name, CLOSED_FILE)))
+    .map((name) => handle(store, path.join(store.journalsRoot, name), clock))
+}
+
+export const journalDetail = (value) => value?.ext?.[OBSIDIAN_EXT_KEY] ?? {}

package/src/projection/obsidian/recovery/late-writer.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { listJournals } from './journal.mjs'
+import { readFileBytes, sha256Digest } from './store.mjs'
+
+// A program that opened a note before it was exchanged still holds the
+// displaced file, and may write into it at any later time. Those bytes land in
+// the recovery area, not in the vault, so nothing shows them to the person
+// unless the displaced files are looked at again. This compares every
+// displaced file with the digest recorded when it was moved. A difference is
+// kept as an immutable object and reported as `late-writer-captured`.
+//
+// The check is meaningful only after a quiet period, and one pass does not end
+// the obligation: a holder can write later still. Callers repeat it.
+export function recheckDisplacedFiles({ store, journalIds, clock = () => new Date() } = {}) {
+  const ids = journalIds ?? listJournals(store).map((journal) => journal.document().journalId)
+  const findings = []
+  for (const journalId of ids) {
+    const receipts = store.listReceipts(journalId)
+    const known = new Set(receipts.filter((receipt) => receipt.role === 'late-writer').map((receipt) => `${receipt.unit}\u0000${receipt.observedDigest}`))
+    for (const receipt of receipts.filter((item) => item.role === 'displaced')) {
+      // A recovery name that is a hard link to the live note (an interrupted
+      // put-back) is the note itself: edits to it are not a late writer's.
+      const live = receipt.notePath ? fs.lstatSync(path.join(store.vaultRoot, receipt.notePath), { throwIfNoEntry: false }) : null
+      const held = fs.lstatSync(store.resolve(receipt.displacedRef), { throwIfNoEntry: false })
+      if (live && held && live.ino === held.ino && live.dev === held.dev) continue
+      let bytes
+      try { bytes = readFileBytes(store.resolve(receipt.displacedRef)) } catch (error) {
+        if (error.code !== 'ENOENT') throw error
+        findings.push({ code: 'displaced-file-missing', journalId, unit: receipt.unit, notePath: receipt.notePath, displacedRef: receipt.displacedRef })
+        continue
+      }
+      const observedDigest = sha256Digest(bytes)
+      if (observedDigest === receipt.digestAtMove) continue
+      const object = store.retainObject(bytes)
+      const finding = { code: 'late-writer-captured', journalId, unit: receipt.unit, notePath: receipt.notePath, displacedRef: receipt.displacedRef, digestAtMove: receipt.digestAtMove, observedDigest, objectRef: object.ref }
+      if (!known.has(`${receipt.unit}\u0000${observedDigest}`)) {
+        const value = clock()
+        store.writeReceipt(journalId, receipt.unit, { role: 'late-writer', notePath: receipt.notePath, displacedRef: receipt.displacedRef, digestAtMove: receipt.digestAtMove, observedDigest, objectRef: object.ref,
+          at: (value instanceof Date ? value : new Date(value)).toISOString() })
+      }
+      findings.push(finding)
+    }
+  }
+  return findings
+}

package/src/projection/obsidian/recovery/restart.mjs

@@ -0,0 +1,316 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { acquirePrivateLock, syncPrivateDirectory } from '../../../project/durable-state.mjs'
+import { journalDetail, listJournals } from './journal.mjs'
+import { readFileBytes, readFileDigest, refuse, sha256Digest } from './store.mjs'
+
+// Restart recovery. Every decision here is made from what is on disk, never
+// from what a lost reply might have said, and every action is a move, a
+// non-overwriting link, the removal of a file proven to be our own candidate,
+// or an appended journal entry. Running it again changes nothing.
+//
+// Interrupted states of one note, identified by its write-ahead `capture`
+// entry (base, candidate, candidate path, recovery path) with no outcome
+// entry. The candidate path of a replacement is in the unit's recovery
+// directory, so whatever it holds is never in a discardable area:
+//
+//   candidate path == candidate digest  nothing was exchanged. The file is a
+//                                       generated candidate and is retired;
+//                                       the note is as it was.
+//   candidate path, any other bytes     the exchange happened and the move to
+//                                       the recovery name did not: the path
+//                                       holds the displaced bytes. They are
+//                                       moved to the recovery name and
+//                                       compared with base.
+//   path absent, recovery name present  exchange and move both happened.
+//   neither                             nothing happened.
+//
+// The journal names every exchange candidate, path and digest, before the file
+// is at that path (the header for candidates known when the run began, a
+// write-ahead entry for a late one), and only complete files are moved there.
+// classifyCandidateFile is the only place that decides between the two kinds.
+//
+// For the whole journal: a pointer that already names this journal gets its
+// missing `manifest-commit` entry; a journal that reached `verifying` with
+// every note settled commits its stored manifest; anything else is left as
+// `updating` for the next publication to converge, with the digests it did
+// publish still trusted as bases.
+
+const exists = (file) => { try { fs.lstatSync(file); return true } catch (error) { if (error.code === 'ENOENT') return false; throw error } }
+
+const RETIRING_NAME = 'retiring.bin'
+
+// What a file at a candidate path is. `generated-candidate` is claimed only
+// for bytes whose digest the journal recorded for that candidate; those are
+// ours and may be deleted. Everything else, including a file whose candidate
+// digest the journal does not give, is `displaced-bytes`: somebody's content,
+// which is moved or kept and never deleted.
+export function classifyCandidateFile({ file, candidateDigest }) {
+  const digest = file ? readFileDigest(file) : null
+  if (digest === null) return 'absent'
+  return candidateDigest && digest === candidateDigest ? 'generated-candidate' : 'displaced-bytes'
+}
+
+// Every candidate a journal names: from its header, and from the write-ahead
+// entries of late exchange candidates. `preparedRef` is where the bytes were
+// written, in staging, before they were moved to `stagedRef`.
+export function namedCandidates(document) {
+  const named = (journalDetail(document).staged ?? []).map(({ unit, path: notePath, candidateDigest, stagedRef, preparedRef }) => ({ unit, path: notePath, candidateDigest, stagedRef, preparedRef: preparedRef ?? null, late: false }))
+  for (const entry of document.entries) {
+    const detail = journalDetail(entry)
+    if (entry.step === 'capture' && detail.code === 'late-candidate' && detail.stagedRef) {
+      named.push({ unit: detail.unit, path: entry.notePath, candidateDigest: entry.afterDigest ?? null, stagedRef: detail.stagedRef, preparedRef: detail.preparedRef ?? null, late: true })
+    }
+  }
+  return named
+}
+
+function freeName(store, journalId, unit, stem = 'displaced') {
+  for (let index = 0; ; index += 1) {
+    const candidate = store.displacedPath(journalId, unit, index === 0 ? `${stem}.bin` : `${stem}-${index}.bin`)
+    if (!exists(candidate)) return candidate
+  }
+}
+
+// Judges a file already moved to the unit's retiring name: our own candidate
+// is deleted; anything else is somebody's bytes and stays in recovery under a
+// name of its own. This is both the second half of retireStagedFile and what
+// restart recovery runs for a retirement that was interrupted.
+function judgeRetiring({ store, journalId, unit, candidateDigest }) {
+  const retiring = store.displacedPath(journalId, unit, RETIRING_NAME)
+  if (!exists(retiring)) return { retired: false, capturedPaths: [] }
+  if (classifyCandidateFile({ file: retiring, candidateDigest }) === 'generated-candidate') {
+    fs.unlinkSync(retiring)
+    return { retired: true, capturedPaths: [] }
+  }
+  const capturedPath = freeName(store, journalId, unit, 'unexpected-at-staged-path')
+  fs.renameSync(retiring, capturedPath)
+  syncPrivateDirectory(path.dirname(capturedPath))
+  return { retired: false, capturedPaths: [capturedPath] }
+}
+
+// A candidate path is never unlinked in place: between a digest check and an
+// unlink, a late exchange could put displaced bytes there. It is first moved
+// to a private name, which no payload refers to, and only then judged. That
+// name lives in the unit's recovery directory, beside the exchange candidate,
+// never in staging: between the two steps the file may be the only copy of
+// bytes an exchange displaced. A process that dies between the steps leaves
+// `retiring.bin` there, and restart recovery finishes the judgement.
+// Returns { retired, capturedPaths }: every path in `capturedPaths` holds
+// bytes that were not the candidate and still needs a receipt.
+export function retireStagedFile({ store, journalId, unit, stagedPath, candidateDigest, crash = () => {} }) {
+  // An earlier interrupted retirement of this unit is finished first, so the move below never lands on it.
+  const earlier = judgeRetiring({ store, journalId, unit, candidateDigest })
+  if (!stagedPath || !exists(stagedPath)) return earlier
+  fs.renameSync(stagedPath, store.displacedPath(journalId, unit, RETIRING_NAME))
+  crash('after-retire-move')
+  const result = judgeRetiring({ store, journalId, unit, candidateDigest })
+  return { retired: result.retired, capturedPaths: [...earlier.capturedPaths, ...result.capturedPaths] }
+}
+
+// Units of one journal that still hold a `retiring.bin`.
+function interruptedRetirements(store, journalId) {
+  const base = path.join(store.workspaceRoot, 'recovery', journalId.replaceAll(':', '_'))
+  if (!exists(base)) return []
+  return fs.readdirSync(base).filter((name) => /^\d{6}$/.test(name) && exists(path.join(base, name, RETIRING_NAME))).map((name) => Number(name)).sort((a, b) => a - b)
+}
+
+// `digestAtMove` is the digest taken inside the critical section, right after
+// the move, when the caller has it. A holder of the old file may already have
+// written into it by the time this process reads it; that difference is left
+// for the late-writer check to report.
+export function recordDisplaced({ store, journalId, unit, notePath, displacedPath, baseDigest, at, digestAtMove: observedAtMove = null }) {
+  const bytes = readFileBytes(displacedPath)
+  const digestAtMove = observedAtMove ?? sha256Digest(bytes)
+  const externalCaptured = digestAtMove !== baseDigest
+  // The displaced file stays where it is. Bytes that are not the known base get an immutable copy as well.
+  const object = sha256Digest(bytes) !== baseDigest ? store.retainObject(bytes) : null
+  store.writeReceipt(journalId, unit, { role: 'displaced', notePath, displacedRef: store.ref(displacedPath), digestAtMove, baseDigest, externalCaptured, ...(object ? { objectRef: object.ref } : {}), at })
+  return { digestAtMove, externalCaptured, displacedRef: store.ref(displacedPath) }
+}
+
+// Settles one note whose outcome is unknown. Returns the entry to append.
+export function reconcileUnit({ store, journalId, capture, at }) {
+  const detail = journalDetail(capture)
+  const { unit, op } = detail
+  const notePath = capture.notePath
+  const note = path.join(store.vaultRoot, notePath)
+  const base = capture.beforeDigest ?? null
+  const candidate = capture.afterDigest ?? null
+  const staged = detail.stagedRef ? store.resolve(detail.stagedRef) : null
+  const displaced = capture.recoveryRef ? store.resolve(capture.recoveryRef) : null
+  const settle = (outcome, code, extra = {}) => ({ step: 'conditional-update', outcome, notePath, ...(base ? { beforeDigest: base } : {}), ...(outcome === 'ok' && candidate ? { afterDigest: candidate } : {}),
+    ...(extra.recoveryRef ? { recoveryRef: extra.recoveryRef } : {}), detail: { unit, op, kind: detail.kind, code, reconciled: true, ...(extra.externalCaptured ? { externalCaptured: true } : {}) } })
+
+  const keepUnexpected = (paths) => { for (const capturedPath of paths) recordDisplaced({ store, journalId, unit, notePath, displacedPath: capturedPath, baseDigest: base, at }) }
+  const completeAfterExchange = (holder) => {
+    const target = !displaced || exists(displaced) ? freeName(store, journalId, unit) : displaced
+    fs.renameSync(holder, target)
+    syncPrivateDirectory(path.dirname(target))
+    const recorded = recordDisplaced({ store, journalId, unit, notePath, displacedPath: target, baseDigest: base, at })
+    return settle('ok', 'completed-after-exchange', { recoveryRef: recorded.displacedRef, externalCaptured: recorded.externalCaptured })
+  }
+
+  if (op === 'replace') {
+    // A retirement interrupted between its two moves: the file that was at the
+    // staged path is at the retiring name. Bytes that are not the candidate
+    // can only have come from the exchange, exactly as if they were still staged.
+    const retiring = store.displacedPath(journalId, unit, RETIRING_NAME)
+    if (classifyCandidateFile({ file: retiring, candidateDigest: candidate }) === 'displaced-bytes') {
+      const entry = completeAfterExchange(retiring)
+      if (staged) keepUnexpected(retireStagedFile({ store, journalId, unit, stagedPath: staged, candidateDigest: candidate }).capturedPaths)
+      return entry
+    }
+    const atCandidatePath = classifyCandidateFile({ file: staged, candidateDigest: candidate })
+    if (atCandidatePath === 'generated-candidate') {
+      keepUnexpected(retireStagedFile({ store, journalId, unit, stagedPath: staged, candidateDigest: candidate }).capturedPaths)
+      return settle('skipped', 'interrupted-before-exchange')
+    }
+    if (atCandidatePath === 'displaced-bytes') return completeAfterExchange(staged)
+    keepUnexpected(judgeRetiring({ store, journalId, unit, candidateDigest: candidate }).capturedPaths)
+    if (displaced && exists(displaced)) {
+      const known = store.listReceipts(journalId).find((receipt) => receipt.role === 'displaced' && receipt.unit === unit && receipt.displacedRef === store.ref(displaced))
+      const recorded = known ?? recordDisplaced({ store, journalId, unit, notePath, displacedPath: displaced, baseDigest: base, at })
+      return settle('ok', 'completed-after-recovery-move', { recoveryRef: recorded.displacedRef, externalCaptured: recorded.externalCaptured })
+    }
+    return settle('skipped', 'nothing-happened')
+  }
+  if (op === 'create') {
+    const created = readFileDigest(note) === candidate
+    keepUnexpected(staged ? retireStagedFile({ store, journalId, unit, stagedPath: staged, candidateDigest: candidate }).capturedPaths : [])
+    return created ? settle('ok', 'completed-after-create') : settle('skipped', 'interrupted-before-create')
+  }
+  if (op === 'remove') {
+    if (!displaced || !exists(displaced)) return settle('skipped', 'interrupted-before-removal')
+    const noteStat = fs.lstatSync(note, { throwIfNoEntry: false })
+    const movedStat = fs.lstatSync(displaced)
+    if (noteStat && noteStat.ino === movedStat.ino && noteStat.dev === movedStat.dev) {
+      // An interrupted put-back: the note path already names these bytes again.
+      fs.unlinkSync(displaced)
+      return settle('skipped', 'remove-reverted')
+    }
+    const recorded = recordDisplaced({ store, journalId, unit, notePath, displacedPath: displaced, baseDigest: base, at })
+    return settle('ok', recorded.externalCaptured ? 'removed-external-captured' : 'completed-after-removal', { recoveryRef: recorded.displacedRef, externalCaptured: recorded.externalCaptured })
+  }
+  return refuse('journal-corrupt', 'a capture entry names an unknown operation')
+}
+
+// Late candidates in staging that no entry names. Every one counts: a journal
+// may hold a named late candidate and an orphaned one side by side. This looks
+// in staging only. Nothing in a unit's recovery directory is ever an orphan:
+// a late exchange candidate gets there after its write-ahead entry, and a
+// file there that the journal does not account for is kept.
+function strays(store, document) {
+  const directory = path.join(store.stagingRoot, document.journalId.replaceAll(':', '_'))
+  if (!exists(directory)) return []
+  const named = new Set(document.entries.flatMap((entry) => [journalDetail(entry).stagedRef, journalDetail(entry).preparedRef]).filter(Boolean))
+  return fs.readdirSync(directory).filter((name) => name.endsWith('.late.candidate')).map((name) => path.join(directory, name)).filter((file) => !named.has(store.ref(file)))
+}
+
+const iso = (clock) => { const value = clock(); return (value instanceof Date ? value : new Date(value)).toISOString() }
+
+// Caller holds the view's lock.
+export function recoverPublicationsLocked({ store, clock = () => new Date() }) {
+  const report = []
+  for (const journal of listJournals(store, { clock, openOnly: true })) {
+    const document = journal.document()
+    if (document.state === 'committed') { journal.close(); continue }
+    const header = journalDetail(document)
+    const settled = new Set(document.entries.filter((entry) => entry.step === 'conditional-update').map((entry) => journalDetail(entry).unit))
+    const pending = document.entries.filter((entry) => entry.step === 'capture' && journalDetail(entry).intent === true && !settled.has(journalDetail(entry).unit))
+    const pendingUnits = new Set(pending.map((entry) => journalDetail(entry).unit))
+    // Candidates the journal names that are still on disk. At the candidate path of a pending unit the file is
+    // reconcileUnit's to judge. A file still in staging was never moved to an exchange path, whatever its unit.
+    const leftovers = namedCandidates(document).flatMap((item) => [...(pendingUnits.has(item.unit) ? [] : [item.stagedRef]), item.preparedRef].filter(Boolean).map((ref) => ({ ...item, file: store.resolve(ref) })))
+      .filter((item) => exists(item.file))
+    // Retirements interrupted between their two moves, for notes that are otherwise settled.
+    const candidateOf = new Map((header.staged ?? []).map((item) => [item.unit, item.candidateDigest]))
+    for (const entry of document.entries) if (entry.step === 'capture' && journalDetail(entry).stagedRef && entry.afterDigest) candidateOf.set(journalDetail(entry).unit, entry.afterDigest)
+    const pathOf = new Map((header.units ?? []).map((item) => [item.unit, item.path]))
+    const retiring = interruptedRetirements(store, document.journalId).filter((unit) => !pendingUnits.has(unit))
+    const orphans = strays(store, document)
+    const pointer = store.readCurrent()
+    const hasCommitEntry = document.entries.some((entry) => entry.step === 'manifest-commit' && entry.outcome === 'ok')
+    const pointerNamesJournal = pointer?.journalId === document.journalId
+    const verifying = document.entries.findLast((entry) => entry.step === 'verify' && journalDetail(entry).settled === true)
+    const current = (pointer?.generationId ?? null) === document.expectedGeneration
+    const canCommit = Boolean(verifying) && !hasCommitEntry && !pointerNamesJournal && current
+    const stale = !current && !pointerNamesJournal
+    const atRest = document.state === 'failed' || document.state === 'updating' || document.state === 'captured' || document.state === 'prepared'
+    const work = pending.length > 0 || leftovers.length > 0 || retiring.length > 0 || orphans.length > 0 || (pointerNamesJournal && !hasCommitEntry) || canCommit || document.state === 'recovering' || (stale && document.state !== 'failed')
+    if (!work && atRest) { if (stale) journal.close(); continue }
+
+    const actions = []
+    journal.append({ step: 'restart', outcome: 'ok', state: 'recovering', detail: { phase: 'begin', pendingUnits: pending.length } })
+    for (const capture of pending) {
+      const entry = reconcileUnit({ store, journalId: document.journalId, capture, at: iso(clock) })
+      journal.append({ ...entry, state: 'recovering' })
+      actions.push({ path: capture.notePath, outcome: entry.outcome, code: entry.detail.code })
+      if (entry.outcome === 'ok' && entry.detail.op !== 'remove') {
+        const verified = readFileDigest(path.join(store.vaultRoot, capture.notePath)) === capture.afterDigest
+        journal.append({ step: 'verify', outcome: verified ? 'ok' : 'conflict', state: 'recovering', notePath: capture.notePath, afterDigest: capture.afterDigest,
+          detail: { unit: entry.detail.unit, code: verified ? 'verified' : 'changed-after-publication' } })
+      }
+    }
+    const keepUnexpected = (unit, notePath, capturedPaths) => {
+      for (const capturedPath of capturedPaths) {
+        // Not the candidate, and nothing says what it is: it is kept and surfaced as an outside writer's bytes.
+        recordDisplaced({ store, journalId: document.journalId, unit, notePath, displacedPath: capturedPath, baseDigest: null, at: iso(clock) })
+        actions.push({ path: notePath, outcome: 'ok', code: 'unexpected-bytes-at-staged-path-kept' })
+      }
+    }
+    for (const unit of retiring) {
+      const result = retireStagedFile({ store, journalId: document.journalId, unit, stagedPath: null, candidateDigest: candidateOf.get(unit) ?? null })
+      keepUnexpected(unit, pathOf.get(unit) ?? null, result.capturedPaths)
+      if (result.retired) actions.push({ path: pathOf.get(unit) ?? null, outcome: 'ok', code: 'interrupted-retirement-finished' })
+    }
+    for (const item of leftovers) {
+      const result = retireStagedFile({ store, journalId: document.journalId, unit: item.unit, stagedPath: item.file, candidateDigest: item.candidateDigest })
+      keepUnexpected(item.unit, item.path, result.capturedPaths)
+    }
+    // A file in staging that no entry names was never put in a payload, so nothing can have exchanged it.
+    for (const orphan of orphans) fs.rmSync(orphan, { force: true })
+    const stagingDir = store.stagingDir(document.journalId)
+    try { fs.rmdirSync(stagingDir) } catch { /* not empty, or already gone */ }
+
+    let committed = false
+    if (pointerNamesJournal && !hasCommitEntry) {
+      journal.append({ step: 'manifest-commit', outcome: 'ok', state: 'committed', detail: { code: 'pointer-already-committed', reconciled: true } })
+      committed = true
+    } else if (canCommit) {
+      const manifestBytes = readFileBytes(store.resolve(header.manifestRef))
+      if (sha256Digest(manifestBytes) !== header.manifestDigest) refuse('journal-corrupt', 'the manifest stored with a journal no longer matches its digest')
+      store.commitManifest({ manifestBytes, generationId: document.targetGeneration, journalId: document.journalId, retained: journalDetail(verifying).retained ?? [], committedAt: iso(clock) })
+      journal.append({ step: 'manifest-commit', outcome: 'ok', state: 'committed', detail: { code: 'committed-on-restart', reconciled: true } })
+      committed = true
+    } else {
+      journal.append({ step: 'restart', outcome: 'ok', state: stale ? 'failed' : 'updating', detail: { phase: 'complete', ...(stale ? { code: 'superseded' } : {}) } })
+    }
+    if (committed || stale) journal.close()
+    report.push({ journalId: document.journalId, actions, committed, state: journal.document().state })
+  }
+  return { journals: report }
+}
+
+export function recoverPublications({ store, clock = () => new Date() }) {
+  const release = acquirePrivateLock(store.lockPath)
+  try { return recoverPublicationsLocked({ store, clock }) } finally { release() }
+}
+
+// Digests this view has published since its trusted manifest was committed,
+// by journals that did not reach a commit. They are valid bases: without them
+// a note published by an interrupted run would look like an outside edit.
+export function publishedSinceCommit({ store }) {
+  const pointer = store.readCurrent()
+  const ledger = new Map()
+  for (const journal of listJournals(store, { openOnly: true })) {
+    const document = journal.document()
+    if (document.state === 'committed' || document.expectedGeneration !== (pointer?.generationId ?? null)) continue
+    for (const entry of document.entries) {
+      const detail = journalDetail(entry)
+      if (entry.step !== 'conditional-update' || entry.outcome !== 'ok' || detail.kind === 'settings') continue
+      ledger.set(entry.notePath, detail.op === 'remove' ? null : entry.afterDigest)
+    }
+  }
+  return ledger
+}