@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.10

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
+}

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

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { acquirePrivateLock, publishPrivateFile } from '../../../project/durable-state.mjs'
+import { checkManagedRoots } from '../../../project/file-class.mjs'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../../project/private-state.mjs'
+
+// Private per-workspace state for one Obsidian view:
+//
+//   <workspaceRoot>/vaults/<scopeId>/                 the editable vault (or an explicit vaultRoot)
+//   <workspaceRoot>/state/manifests/<scopeId>/        trusted manifests and the current pointer
+//   <workspaceRoot>/state/journals/<scopeId>/<id>/    publication journals
+//   <workspaceRoot>/recovery/objects/<sha256>.bin     immutable content-addressed bytes
+//   <workspaceRoot>/recovery/<journalId>/<unit>/      displaced files, receipts, and the unit's exchange candidate
+//   <workspaceRoot>/recovery/.exchange-probe/         scratch files of the exchange self-test, nothing else
+//   <workspaceRoot>/staging/<journalId>/              disposable generated bytes that no exchange ever names
+//   <vault>/.atelier-publication/                     the vault lock, shared by every view of the vault
+//
+// Immutable records are published with publishPrivateFile: a complete file
+// appears atomically under a name that is never overwritten. What that gives
+// is an all-or-nothing record that survives a process crash; it is fsynced,
+// which on some platforms is weaker than a full device flush. A displaced
+// file is different: it is the very file that occupied a note path, it is
+// moved and never copied over, and a program that still holds it open may
+// write into it later. It is therefore never treated as immutable; its digest
+// at the time of the move is recorded in a receipt and re-checked.
+//
+// A candidate that replaces an existing file is exchanged with it, so after
+// the exchange the candidate's path holds the displaced bytes. That path is
+// therefore in the unit's recovery directory, never in staging: staging is
+// discardable, and displaced bytes must not sit in a discardable area for an
+// instant. The candidate is written and fsynced in staging, where it is only
+// generated bytes, named with its digest by the journal, and only then moved
+// to its exchange path. What a file at an exchange path is, is decided from
+// the journal: bytes with the recorded candidate digest are generated and
+// ours; anything else is somebody's bytes and is kept. The candidate names
+// end in `.candidate`; everything else the store puts in a unit directory
+// ends in `.bin` or `.json`, so the names cannot collide.
+
+export const EXCHANGE_CANDIDATE_NAME = 'exchange.candidate'
+export const LATE_EXCHANGE_CANDIDATE_NAME = 'exchange.late.candidate'
+
+export const VAULT_LOCK_DIRECTORY = '.atelier-publication'
+
+// The vault lock, with the semantics of every private lock: the newest ticket
+// owns it, a release marker frees it, and a ticket whose process is gone on
+// this host is stale and is taken over. Nothing else is ever written here.
+// Tickets of superseded generations are removed while the lock is held, the
+// marker before its ticket, so the directory does not grow inside a person's
+// vault and an interrupted removal never leaves a marker without its ticket.
+export function acquireVaultLock(store) {
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: store.vaultRoot, directory: path.dirname(store.vaultLockPath), label: 'vault publication lock' })
+  const release = acquirePrivateLock(path.join(directory, path.basename(store.vaultLockPath)))
+  try {
+    const owners = `${store.vaultLockPath}.owners`
+    const names = fs.readdirSync(owners).filter((name) => /^\d{12}\.(json|released)$/.test(name)).sort()
+    const newest = names.filter((name) => name.endsWith('.json')).at(-1)?.slice(0, 12)
+    for (const name of names.filter((item) => item.slice(0, 12) < newest).sort((left, right) => (left.endsWith('.released') ? -1 : 1) - (right.endsWith('.released') ? -1 : 1))) {
+      fs.rmSync(path.join(owners, name), { force: true })
+    }
+  } catch { /* history that cannot be pruned is harmless */ }
+  return release
+}
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+
+export const sha256Digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+
+export class PublicationRefusal extends Error {
+  constructor(code, message, detail = {}) {
+    super(`${code}: ${message}`)
+    this.name = 'PublicationRefusal'
+    this.code = code
+    this.detail = detail
+  }
+}
+
+export function refuse(code, message, detail) {
+  throw new PublicationRefusal(code, message, detail)
+}
+
+// Identifiers become directory names. ':' is legal in an identifier and is not
+// legal in a file name everywhere.
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export function readFileDigest(file) {
+  let descriptor
+  try {
+    descriptor = openRegularFileNoFollow(file)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try { return sha256Digest(fs.readFileSync(descriptor)) } finally { fs.closeSync(descriptor) }
+}
+
+export function readFileBytes(file) {
+  const descriptor = openRegularFileNoFollow(file)
+  try { return fs.readFileSync(descriptor) } finally { fs.closeSync(descriptor) }
+}
+
+function publishOnce(file, bytes) {
+  try {
+    publishPrivateFile(file, bytes)
+  } catch (error) {
+    // The name is taken by different bytes. An immutable record is never replaced.
+    if (error.code !== 'EEXIST') throw error
+    return false
+  }
+  return true
+}
+
+// `repositoryRoots` is required: every enrolled repository root of the loaded
+// project. Neither the workspace state nor the vault may overlap one of them,
+// in either direction, lexically or by real path; the store refuses before it
+// creates anything. A caller with no enrolled repository (a test in a
+// temporary directory) says so with an explicit empty list.
+export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vaultRoot, repositoryRoots } = {}) {
+  if (typeof workspaceRoot !== 'string' || !path.isAbsolute(workspaceRoot)) throw new TypeError('workspaceRoot must be an absolute path')
+  for (const [label, value] of [['workspaceId', workspaceId], ['scopeId', scopeId]]) {
+    if (typeof value !== 'string' || !IDENTIFIER.test(value)) throw new TypeError(`${label} must be a contract identifier`)
+  }
+  if (!Array.isArray(repositoryRoots) || repositoryRoots.some((item) => typeof item !== 'string' || !path.isAbsolute(item))) {
+    throw new TypeError('repositoryRoots must list the absolute root of every enrolled repository; pass an explicit empty list when there is none')
+  }
+  if (vaultRoot !== undefined && (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot))) throw new TypeError('vaultRoot must be an absolute path')
+  const guard = checkManagedRoots({ managedRoots: [workspaceRoot, ...(vaultRoot === undefined ? [] : [vaultRoot])], repositoryRoots })
+  if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  const root = fs.realpathSync(workspaceRoot)
+  const privateDir = (...parts) => ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, ...parts), label: 'Obsidian publication state' })
+  const requestedVault = vaultRoot ?? path.join(root, 'vaults', segment(scopeId))
+  fs.mkdirSync(requestedVault, { recursive: true })
+  const vault = fs.realpathSync(requestedVault)
+  const inside = (parent, child) => { const relative = path.relative(parent, child); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)) }
+  for (const area of ['state', 'recovery', 'staging']) {
+    if (inside(path.join(root, area), vault) || inside(vault, path.join(root, area))) throw new TypeError('the vault may not overlap private publication state')
+  }
+  const manifests = privateDir('state', 'manifests', segment(scopeId))
+  const journals = privateDir('state', 'journals', segment(scopeId))
+  const locks = privateDir('state', 'locks')
+  const objects = privateDir('recovery', 'objects')
+  const staging = privateDir('staging')
+  const pointerFile = path.join(manifests, 'current.json')
+
+  const store = {
+    workspaceRoot: root,
+    workspaceId,
+    scopeId,
+    vaultRoot: vault,
+    journalsRoot: journals,
+    lockPath: path.join(locks, `${segment(scopeId)}.lock`),
+    // One publisher per vault, whichever view or workspace state it belongs to.
+    // Two stores share nothing but the vault, so this lock lives under the
+    // vault's real path, in a dot-directory no note path can name.
+    vaultLockPath: path.join(vault, VAULT_LOCK_DIRECTORY, 'vault.lock'),
+    ref: (absolute) => path.relative(root, absolute).split(path.sep).join('/'),
+    resolve(ref) {
+      const absolute = path.resolve(root, ref)
+      if (!inside(root, absolute) || absolute === root) throw new TypeError('a store reference must stay inside the workspace state')
+      return absolute
+    },
+    journalDir: (journalId) => privateDir('state', 'journals', segment(scopeId), segment(journalId)),
+    stagingDir: (journalId) => privateDir('staging', segment(journalId)),
+    stagingRoot: staging,
+    // Where the exchange self-test runs: inside recovery, because that is where exchange candidates live.
+    exchangeProbeDir: () => privateDir('recovery', '.exchange-probe'),
+    // Generated bytes on their way to a path: written here, and for a created file linked from here.
+    preparedPath: (journalId, unit, { late = false } = {}) => path.join(store.stagingDir(journalId), `${String(unit).padStart(6, '0')}${late ? '.late' : ''}.candidate`),
+    // The path handed to the exchange. Computed without creating anything; unitDir creates the directory.
+    exchangeCandidatePath: (journalId, unit, { late = false } = {}) => path.join(root, 'recovery', segment(journalId), String(unit).padStart(6, '0'), late ? LATE_EXCHANGE_CANDIDATE_NAME : EXCHANGE_CANDIDATE_NAME),
+    unitsRoot: (journalId) => path.join(root, 'recovery', segment(journalId)),
+    unitDir: (journalId, unit) => privateDir('recovery', segment(journalId), String(unit).padStart(6, '0')),
+    displacedPath: (journalId, unit, name = 'displaced.bin') => path.join(store.unitDir(journalId, unit), name),
+
+    // Immutable, content-addressed bytes (a base, an observed edit, an outside writer's bytes).
+    retainObject(bytes) {
+      const digest = sha256Digest(bytes)
+      const file = path.join(objects, `${digest.slice('sha256:'.length)}.bin`)
+      publishPrivateFile(file, bytes)
+      return { digest, ref: store.ref(file) }
+    },
+    readObject(digest) {
+      if (!DIGEST.test(digest)) throw new TypeError('digest required')
+      const bytes = readFileBytes(path.join(objects, `${digest.slice('sha256:'.length)}.bin`))
+      if (sha256Digest(bytes) !== digest) refuse('recovery-object-corrupt', 'a retained object no longer matches its name')
+      return bytes
+    },
+    writeReceipt(journalId, unit, receipt) {
+      const body = Buffer.from(`${JSON.stringify({ schema: 'atelier-obsidian-recovery-receipt/v1', journalId, unit, ...receipt }, null, 2)}\n`, 'utf8')
+      const file = path.join(store.unitDir(journalId, unit), `receipt-${receipt.role}-${sha256Digest(body).slice(7, 19)}.json`)
+      publishOnce(file, body)
+      return store.ref(file)
+    },
+    listReceipts(journalId) {
+      const base = path.join(root, 'recovery', segment(journalId))
+      if (!fs.existsSync(base)) return []
+      const receipts = []
+      for (const unit of fs.readdirSync(base).sort()) {
+        for (const name of fs.readdirSync(path.join(base, unit)).filter((entry) => /^receipt-.*\.json$/.test(entry)).sort()) {
+          receipts.push(JSON.parse(readRegularTextNoFollow(path.join(base, unit, name))))
+        }
+      }
+      return receipts
+    },
+
+    // Trusted manifest. The manifest file is immutable; only the small pointer
+    // is replaced, and only as the last step of a publication.
+    readCurrent() {
+      let text
+      try { text = readRegularTextNoFollow(pointerFile) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+      const pointer = JSON.parse(text)
+      if (pointer.scopeId !== scopeId || pointer.workspaceId !== workspaceId) refuse('state-mismatch', 'the manifest pointer belongs to another view')
+      return pointer
+    },
+    readCurrentManifest() {
+      const pointer = store.readCurrent()
+      if (!pointer) return null
+      const bytes = readFileBytes(path.join(manifests, pointer.manifestFile))
+      if (sha256Digest(bytes) !== pointer.manifestDigest) refuse('state-mismatch', 'the trusted manifest no longer matches its pointer')
+      return JSON.parse(bytes.toString('utf8'))
+    },
+    commitManifest({ manifestBytes, generationId, journalId, retained = [], committedAt }) {
+      const manifestDigest = sha256Digest(manifestBytes)
+      const manifestFile = `${segment(generationId)}--${manifestDigest.slice(7, 19)}.json`
+      publishPrivateFile(path.join(manifests, manifestFile), manifestBytes)
+      const pointer = { schema: 'atelier-obsidian-current-manifest/v1', workspaceId, scopeId, generationId, manifestFile, manifestDigest, journalId, committedAt, retained }
+      atomicReplacePrivateText(pointerFile, `${JSON.stringify(pointer, null, 2)}\n`)
+      return pointer
+    },
+  }
+  return store
+}

package/src/projection/obsidian/selection-ui/conflict-view.mjs

@@ -0,0 +1,91 @@
+import { compareText } from '../../../runtime/obsidian/documents.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
+import { openObjectStore } from '../edits/object-store.mjs'
+
+// A read-only, typed view of the shared conflict state AOP-2's arbitration
+// keeps per object: which objects are conflicted, pending, settled or
+// unreadable, which operations are involved and why, and which pending edit
+// records of which views feed them. Identities, states, codes and digests
+// only: no note text, title or path.
+//
+// `conflictView` is pure: it is a function of the object entries (the
+// object store's `list()` or an `arbitrateEvents` summary) and the pending
+// edit records. `readConflictView` reads both from the workspace's private
+// state. Neither decides anything, writes an event or touches a source file
+// or a vault.
+
+export const CONFLICT_VIEW_SCHEMA = 'atelier-obsidian-conflict-view/v1'
+export const OBJECT_VIEW_STATES = Object.freeze(['conflicted', 'pending', 'settled', 'empty', 'inconsistent', 'unreadable'])
+
+// What a person or an agent does next. A conflict is resolved by a new
+// operation that names the ones it resolves; nothing here chooses a winner.
+const NEXT = Object.freeze({
+  conflicted: 'offer a resolution that names every conflicted operation; no operation is dropped and no winner is chosen',
+  pending: 'apply explicitly, or let an active automatic policy dispatch it',
+  settled: 'nothing: every recorded operation is applied, superseded or refused',
+  empty: 'nothing: no operation is recorded for this object',
+  inconsistent: 'a person looks at the object log; an event the log did not allow is recorded',
+  unreadable: 'a person looks at the object directory; nothing is decided until then',
+})
+
+const NEEDS_PERSON = new Set(['conflicted', 'inconsistent', 'unreadable'])
+
+function operationView(operation) {
+  return {
+    idempotencyKey: operation.idempotencyKey,
+    kind: operation.kind ?? null,
+    state: operation.state,
+    reason: operation.reason ?? null,
+    by: operation.by ?? null,
+  }
+}
+
+export function conflictView({ objects, edits = [], scopeId } = {}) {
+  if (!Array.isArray(objects)) throw new TypeError('conflictView needs the list of object entries')
+  const openEdits = edits.filter((edit) => OPEN_EDIT_STATES.includes(edit.state) && (scopeId === undefined || edit.scopeId === scopeId))
+  const editsOf = (repoId, nodeId) => openEdits
+    .filter((edit) => edit.identity?.repoId === repoId && edit.identity?.nodeId === nodeId)
+    .map((edit) => ({ editId: edit.editId, scopeId: edit.scopeId, state: edit.state, lastCode: edit.lastResult?.code ?? null }))
+    .sort((left, right) => compareText(left.scopeId, right.scopeId) || compareText(left.editId, right.editId))
+
+  const entries = objects.map((object) => {
+    const state = OBJECT_VIEW_STATES.includes(object.state) ? object.state : 'unreadable'
+    const identity = object.identity ?? object
+    const repoId = identity.repoId ?? null
+    const nodeId = identity.nodeId ?? null
+    const operations = (object.operations ?? []).map(operationView)
+    const intentOutcomeUnknown = object.intentOutcomeUnknown === true || (object.intent !== undefined && object.intent !== null)
+    const needsPerson = NEEDS_PERSON.has(state) || intentOutcomeUnknown
+    return {
+      repoId, nodeId, state,
+      code: object.code ?? null,
+      sourceDigest: object.sourceDigest ?? null,
+      leaseHeld: object.leaseHeld === true || (object.lease !== undefined && object.lease !== null),
+      intentOutcomeUnknown,
+      operations,
+      conflictedOperations: operations.filter((operation) => operation.state === 'conflicted').map((operation) => operation.idempotencyKey),
+      pendingEdits: repoId === null ? [] : editsOf(repoId, nodeId),
+      needsPerson,
+      next: intentOutcomeUnknown && !NEEDS_PERSON.has(state) ? 'an apply was started and its outcome is not recorded; the next lease holder reads the source and decides' : NEXT[state],
+    }
+  }).sort((left, right) => compareText(left.repoId ?? '', right.repoId ?? '') || compareText(left.nodeId ?? '', right.nodeId ?? ''))
+
+  const byState = Object.fromEntries(OBJECT_VIEW_STATES.map((state) => [state, entries.filter((entry) => entry.state === state).length]))
+  return {
+    schema: CONFLICT_VIEW_SCHEMA,
+    scopeId: scopeId ?? null,
+    objects: entries,
+    summary: { total: entries.length, byState, needsPerson: entries.filter((entry) => entry.needsPerson).length, openEdits: openEdits.length },
+    needsPerson: entries.some((entry) => entry.needsPerson),
+  }
+}
+
+// Reads the object index (a cache the store rebuilds from the events where
+// it is not current) and the pending edit records of the workspace.
+export function readConflictView({ workspaceRoot, workspaceId, repositoryRoots, clock, scopeId, objectStore = openObjectStore }) {
+  const store = objectStore({ stateRoot: workspaceRoot, workspaceId, repositoryRoots, clock })
+  const { objects, foreign } = store.list(scopeId === undefined ? {} : { scopeId })
+  const edits = createMaintenanceStateStore({ workspaceRoot, workspaceId }).readPendingEdits().edits
+  const view = conflictView({ objects, edits, scopeId })
+  return { ...view, foreign }
+}