@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

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

@@ -1,3 +1,4 @@
+import { createCooperativeBudget, isSchedulingStop } from '../materialize/prepare-view.mjs'
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import path from 'node:path'
@@ -9,7 +10,7 @@ import { PLUGIN_DATA_MODE, PLUGIN_DATA_PATH, PLUGIN_SOURCE_MODE } from '../plugi
 import { createJournal, newJournalId } from '../recovery/journal.mjs'
 import { recheckDisplacedFiles } from '../recovery/late-writer.mjs'
 import { publishedSinceCommit, reconcileUnit, recordDisplaced, recoverPublicationsLocked, retireStagedFile } from '../recovery/restart.mjs'
-import { PublicationRefusal, acquireVaultLock, readFileBytes, readFileDigest, refuse, sha256Digest } from '../recovery/store.mjs'
+import { PublicationRefusal, acquireVaultLock, allocatedFolderState, readFileBytes, readFileDigest, refuse, sha256Digest } from '../recovery/store.mjs'
 import { PROTOCOL_ID, isAddressableVaultPath } from './bridge-script.mjs'
 import { probeExchange } from './exchange.mjs'
 import { CRASH_INJECTION_TEST_SEAM } from './test-seam.mjs'
@@ -44,11 +45,34 @@ import { createDirectAdapter } from './transport.mjs'
 // displaced to recovery and never lost, and a plugin path that a person has to
 // repair never holds the view back. The plugin's data file names a bearer and
 // is written only into a vault root that is private to this user.
+//
+// First publication into a vault no Obsidian lists (`direct-unheld`). A running
+// or unknowable app that cannot be coordinated with still refuses the whole
+// publication, as ever, except in one case: the view has never been committed,
+// its vault is the folder Atelier allocated for it (the record's device and
+// inode), and the evidence (`unheldEvidence`, read by the caller from the app's
+// own settings file) says no list this account's Obsidian keeps names that
+// folder, a folder above it or one inside it, on macOS or Linux. The vault is
+// then filled in this process, with no editor, by creating files only: every
+// file appears through the exclusive link, where nothing is, or not at all. A
+// unit that would replace or remove a file, or write a settings file over one
+// that is there, refuses as `editor-uncoordinated` (blocking) and writes
+// nothing. No editor can hold an unsaved buffer of a file that does not exist,
+// so nothing a person wrote can be lost, whoever holds the vault. The evidence
+// is read again immediately before the first unit and whenever two seconds
+// have passed since the last reading; once a reading gives no evidence, every
+// remaining unit refuses and nothing is committed. A run that completes is
+// committed before `open` tells the app about the vault; a run that stops
+// partway reports why, and what it left is published through the app.
 
 const hex = (digest) => digest.slice('sha256:'.length)
 const iso = (clock) => { const value = clock(); return (value instanceof Date ? value : new Date(value)).toISOString() }
 const REFUSED_BY_EDIT = new Set(['editor-edit', 'disk-changed'])
 const unreleased = new Map()
+// A release kept earlier whose lock folder is gone when it is tried again (the vault deleted, replaced, or made again
+// empty at its path) holds nothing there, and is dropped rather than holding every later publication of that vault back.
+// A vault put back holds its ticket again, and the release kept for it then succeeds.
+const lockFolderGone = (error) => error?.code === 'ENOENT' || error?.code === 'ENOTDIR'
 
 // A note another program replaces by rename can change between the check of its leaf and the open
 // (ELEAFCHANGED). Every rename leaves a complete file, so it is read again; one that keeps changing is left to
@@ -212,17 +236,47 @@ function currentDigestOf(vaultRoot, relativePath) {
   try { return readFileDigest(path.join(vaultRoot, relativePath)) } catch { return null }
 }
 
+// Whether publishing would only leave this plugin path for the person, as it
+// stands: a parent that is a link or not a directory, a leaf that is not a
+// regular file (path-unsafe), or the data file where the vault root cannot hold
+// the bearer and is not one Atelier makes private itself (vault-not-private;
+// see ensurePrivateVaultRoot). Read-only. Conservative: a leaf nobody may
+// read, a parent that cannot be looked into, and a vault root Atelier keeps
+// whose mode cannot be changed are left for the person too, but count here as
+// a drift, as before.
+function leftForThePerson(store, relativePath) {
+  let current = store.vaultRoot
+  for (const part of relativePath.split('/').slice(0, -1)) {
+    current = path.join(current, part)
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false })
+    if (!stat) break
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return true
+  }
+  const leaf = fs.lstatSync(path.join(store.vaultRoot, relativePath), { throwIfNoEntry: false })
+  if (leaf && !leaf.isFile()) return true
+  if (relativePath !== PLUGIN_DATA_PATH) return false
+  if (store.linkedVaultRoot === true) return true
+  const uid = typeof process.getuid === 'function' ? process.getuid() : null
+  const root = fs.lstatSync(store.vaultRoot, { throwIfNoEntry: false })
+  if (!root?.isDirectory() || uid === null || root.uid !== uid) return true
+  return (root.mode & 0o077) !== 0 && store.managedVaultRoot !== true
+}
+
 // A generation that is already committed is published again, as it is, when a
 // plugin file it carries is not on disk as it pins it: the person repaired a
 // path Atelier had to leave, or removed or changed a file. The bytes are
 // Atelier's and nothing else of the view changed, so the generation stays the
 // same; its notes are kept, and its plugin units are planned from the disk as
-// ever. A file prepared only where present that is gone is not a drift.
+// ever. A file prepared only where present that is gone is not a drift, and
+// neither is one that publishing would only leave for the person again: it
+// would change nothing, and it would need the app for nothing (a view that
+// waits for an app for it would wait for a write that never comes).
 function pluginFilesDrifted(preparedView, store) {
   return preparedView.files.some((file) => {
     if (file.kind !== 'plugin') return false
     const current = currentDigestOf(store.vaultRoot, file.path)
-    return current !== file.digest && !(current === null && file.onlyIfPresent === true)
+    if (current === file.digest || (current === null && file.onlyIfPresent === true)) return false
+    try { return !leftForThePerson(store, file.path) } catch { return true }
   })
 }
 
@@ -264,14 +318,68 @@ export function planUnits({ files, priorManifest, pointer, ledger, pluginDisk =
   return units
 }
 
-export async function publishView(options = {}) {
+// The code of a failure met while candidates were being cleaned up after a staging that did not complete, for the detail
+// of what ended it. Nothing else of the failure is kept: its message may name a path.
+const cleanupCauseOf = (failure) => (failure === null ? {} : { cleanupCause: typeof failure?.code === 'string' && failure.code !== '' ? failure.code.slice(0, 64) : 'unknown' })
+// The stop or refusal itself is handed on, so the caller can still tell it by identity: its `detail` is replaced by a
+// copy that adds `cleanupCause`, and an object shared as its detail is left as it was. A caller that throws the same
+// error object again keeps that field on it.
+function withCleanupCause(error, failure) {
+  if (failure !== null) try { error.detail = { ...(error.detail ?? {}), ...cleanupCauseOf(failure) } } catch { /* an error that cannot be extended is handed on as it is */ }
+  return error
+}
+
+// The rules the oracle tests are sensitive to. Production always uses these; the tests substitute a deliberately
+// broken one through publishViewForOracleTests to prove the oracle can fail.
+export const PUBLICATION_PRIMITIVES = Object.freeze({
+  // The one operation the `direct-unheld` path writes into the vault: a file created where nothing is.
+  unheldWrites: (op) => op === 'create',
+  // Whether an error that stopped staging was the caller's stop (its settings check, or a cancellation), handed on
+  // under its own code once the candidates are cleaned up, rather than reported as a staging failure.
+  callerStoppedStaging: (error) => isSchedulingStop(error),
+  // Whether a refusal raised while candidates are being staged (the vault's folder replaced or gone under the run) is
+  // handed on only once those candidates are cleaned up, as a stop is. A candidate staged before the journal is
+  // written is named by no journal, so restart recovery would never remove one left there.
+  refusedStagingCleansUp: () => true,
+  // The code the journal's last entry gives an error that ended the publication once the journal was open: a
+  // caller's stop under its own code, which is what the caller is told, and anything else as a fault of the publisher.
+  // Decided by the tag a stop carries, never by what an error looks like; a stop that carries no code has none to give.
+  journalFailureCode: (error) => (isSchedulingStop(error) && typeof error.code === 'string' && error.code !== '' ? error.code.slice(0, 200) : 'publisher-error'),
+})
+
+// Whether the `direct-unheld` path applies, after the adapter found an app it cannot coordinate with (see the head of
+// this file). Every condition must hold; an evidence reader that is absent, throws or answers anything but
+// `unlisted: true` gives none.
+async function unheldPathApplies({ probe, pointer, store, unheldEvidence, platform }) {
+  if (probe.code !== undefined || pointer !== null) return false
+  if (platform !== 'darwin' && platform !== 'linux') return false
+  const { allocation } = store
+  if (store.vaultOrigin !== 'allocated' || store.managedVaultRoot !== true || !allocation || store.vaultRoot !== allocation.path || allocatedFolderState(allocation) !== 'same') return false
+  return readsUnlisted(unheldEvidence, store)
+}
+
+async function readsUnlisted(unheldEvidence, store) {
+  if (typeof unheldEvidence !== 'function') return false
+  try { return (await unheldEvidence({ vaultRoot: store.vaultRoot }))?.unlisted === true } catch { return false }
+}
+
+export function publishView(options = {}) {
+  return publishViewForOracleTests(options, PUBLICATION_PRIMITIVES)
+}
+
+export async function publishViewForOracleTests(options = {}, primitives = PUBLICATION_PRIMITIVES) {
   const { preparedView, protocolId, expectedGeneration, recoveryStore: store, adapter, clock = () => new Date(), quietPeriodMs = 1500, exchangeOptions = {} } = options
+  // `unheldEvidence({ vaultRoot })` answers whether the app's own list names this vault (see the head of this file).
+  const { unheldEvidence = null, platform = process.platform } = options
+  const rules = { ...PUBLICATION_PRIMITIVES, ...primitives }
   const seam = options[CRASH_INJECTION_TEST_SEAM] ?? null
   const crash = (point) => { if (seam && seam.at === point) seam.halt(point) }
   if (!store || typeof store.commitManifest !== 'function') throw new TypeError('publishView needs a recoveryStore')
   if (!adapter || typeof adapter.probe !== 'function') throw new TypeError('publishView needs an editor coordination adapter')
   if (expectedGeneration !== null && typeof expectedGeneration !== 'string') throw new TypeError('expectedGeneration must be a generation identity or null')
 
+  const budget = createCooperativeBudget(options.scheduling)
+  budget.check()
   const releases = []
   let journal = null
   try {
@@ -280,22 +388,37 @@ export async function publishView(options = {}) {
     // A release that could not be written (a full disk) is finished first.
     for (const lockPath of [store.vaultLockPath, store.lockPath]) {
       if (!unreleased.has(lockPath)) continue
-      try { unreleased.get(lockPath)() } catch (error) { refuse('state-unwritable', 'private publication state cannot be written; nothing in the vault was touched', { cause: error.code ?? String(error.message) }) }
+      try { unreleased.get(lockPath)() } catch (error) { if (!lockFolderGone(error)) refuse('state-unwritable', 'private publication state cannot be written; nothing in the vault was touched', { cause: error.code ?? String(error.message) }) }
       unreleased.delete(lockPath)
     }
     // Two locks, the view's and then the vault's: a second view or a second
     // workspace state pointed at the same vault refuses instead of racing.
     const acquire = (lockPath, take, held) => {
       try { releases.push([lockPath, take()]) } catch (error) {
+        if (error instanceof PublicationRefusal) throw error
         if (error.code === 'EEXIST') refuse('publication-in-progress', `another publication ${held} holds the lock`)
         refuse('state-unwritable', 'private publication state cannot be written; nothing in the vault was touched', { cause: error.code ?? String(error.message) })
       }
     }
     acquire(store.lockPath, () => acquirePrivateLock(store.lockPath), 'of this view')
+    // A vault allocated for the view is still the folder it made, before anything is written in it (the vault lock
+    // included) and again once the lock is held: a store kept by a long-running service may outlive its folder. It is
+    // checked again after every wait on the app, before each unit and before the commit, so a folder replaced during a
+    // publication refuses it and is never reported current. (Only this account can replace it; the check and the
+    // write that follows it are still two steps.)
+    store.checkAllocatedVault?.()
     acquire(store.vaultLockPath, () => acquireVaultLock(store), 'into this vault')
+    store.checkAllocatedVault?.()
+    await budget.checkpoint('recover', true)
+    store.checkAllocatedVault?.()
     const recovered = recoverPublicationsLocked({ store, clock })
+    await budget.checkpoint('recovery-complete', true)
+    store.checkAllocatedVault?.()
     const pointer = store.readCurrent()
     if (pointer?.generationId === manifest.generationId && !pluginFilesDrifted(preparedView, store)) {
+      await options.beforeCommit?.()
+      budget.check()
+      store.checkAllocatedVault?.()
       return { state: 'committed', alreadyCommitted: true, generationId: manifest.generationId, journalId: pointer.journalId, notes: [], retainedEdits: pointer.retained ?? [], lateWriters: [], recovered }
     }
     if ((pointer?.generationId ?? null) !== expectedGeneration) refuse('generation-mismatch', 'the committed generation is not the one this publication expects', { committed: pointer?.generationId ?? null })
@@ -303,8 +426,12 @@ export async function publishView(options = {}) {
     // Path selection. An app with this vault open in several windows is refused as such: publishing through one of
     // them would leave the others uncoordinated.
     const probe = await adapter.probe({ vaultRoot: store.vaultRoot })
-    if (probe.state !== 'coordinated' && probe.state !== 'absent') refuse(probe.code === 'vault-open-in-several-windows' ? probe.code : 'editor-uncoordinated', `an Obsidian process may have this vault open and cannot be coordinated with: ${probe.reason}`)
-    const mode = probe.state === 'coordinated' ? 'in-app' : 'direct'
+    store.checkAllocatedVault?.()
+    const unheld = probe.state !== 'coordinated' && probe.state !== 'absent' && await unheldPathApplies({ probe, pointer, store, unheldEvidence, platform })
+    // The evidence took time to read: the folder is checked again.
+    if (unheld) store.checkAllocatedVault?.()
+    if (probe.state !== 'coordinated' && probe.state !== 'absent' && !unheld) refuse(probe.code === 'vault-open-in-several-windows' ? probe.code : 'editor-uncoordinated', `an Obsidian process may have this vault open and cannot be coordinated with: ${probe.reason}`)
+    const mode = probe.state === 'coordinated' ? 'in-app' : unheld ? 'direct-unheld' : 'direct'
     const channel = mode === 'in-app' ? adapter : createDirectAdapter({ crashSeam: seam })
 
     // Same volume, and an exchange that works on it.
@@ -329,13 +456,18 @@ export async function publishView(options = {}) {
     let stagingDir = null
     try {
       stagingDir = store.stagingDir(journalId)
-      for (const unit of units.filter((item) => item.op === 'replace' || item.op === 'create')) {
+      // On the `direct-unheld` path a replacement is never written, so no candidate is staged for one.
+      for (const unit of units.filter((item) => item.op === 'create' || (item.op === 'replace' && (mode !== 'direct-unheld' || rules.unheldWrites(item.op))))) {
+        await budget.checkpoint('stage-candidate')
+        store.checkAllocatedVault?.()
         const existing = fs.lstatSync(path.join(store.vaultRoot, unit.path), { throwIfNoEntry: false })
         unit.preparedPath = store.preparedPath(journalId, unit.unit)
         stageCandidate(unit.preparedPath, unit.bytes, unit.mode ?? (existing?.isFile() ? existing.mode & 0o777 : 0o644), created)
         // A replacement is exchanged, and the exchange leaves the displaced bytes at this path: it is in recovery.
         unit.stagedPath = unit.op === 'replace' ? store.exchangeCandidatePath(journalId, unit.unit) : unit.preparedPath
       }
+      await budget.checkpoint('staging-complete', true)
+      store.checkAllocatedVault?.()
       syncPrivateDirectory(stagingDir)
       const manifestFile = path.join(store.journalDir(journalId), 'manifest.json')
       publishPrivateFile(manifestFile, manifestBytes)
@@ -350,25 +482,42 @@ export async function publishView(options = {}) {
       // The journal now names every exchange candidate by path and digest. Only complete, fsynced files are moved
       // in, so a file at an exchange path is never a partial candidate.
       for (const unit of units.filter((item) => item.stagedPath && item.stagedPath !== item.preparedPath)) {
+        await budget.checkpoint('move-candidate')
+        store.checkAllocatedVault?.()
         moveToExchangePath(store, journalId, unit, moved)
       }
     } catch (error) {
-      if (error instanceof PublicationRefusal) throw error
+      const stopped = rules.callerStoppedStaging(error)
+      // A refusal raised between two candidates (the publisher's own check found the vault's folder replaced or gone)
+      // is handed on under its own code too, and like a stop only after the cleanup below.
+      const refused = error instanceof PublicationRefusal && !stopped
+      if (refused && !rules.refusedStagingCleansUp(error)) throw error
       // No payload has named any of these paths, so nothing was exchanged and they can only hold our own
       // candidates. In staging they are removed by name. In recovery a file is removed only when its bytes are
       // the candidate's; anything else stays for restart recovery, which the journal header points at it. Only
       // empty directories are removed, so a failed staging leaves nothing that looks like an unfinished unit.
+      // Each file is cleaned up on its own, so one that cannot be removed (EBUSY, EPERM, a volume gone) leaves the
+      // others removed; the first such failure is kept.
+      let cleanupFailure = null
+      const cleanUp = (operation) => { try { operation() } catch (failure) { cleanupFailure ??= failure } }
       for (const unit of moved) {
-        if (readFileDigest(unit.stagedPath) === unit.candidateDigest) fs.rmSync(unit.stagedPath, { force: true })
+        cleanUp(() => { if (readFileDigest(unit.stagedPath) === unit.candidateDigest) fs.rmSync(unit.stagedPath, { force: true }) })
         try { fs.rmdirSync(path.dirname(unit.stagedPath)) } catch { /* not empty: left for restart recovery */ }
       }
-      for (const file of created) fs.rmSync(file, { force: true })
+      for (const file of created) cleanUp(() => fs.rmSync(file, { force: true }))
       for (const directory of [stagingDir, store.unitsRoot(journalId)]) if (directory) try { fs.rmdirSync(directory) } catch { /* absent, or not empty */ }
-      refuse('staging-failed', 'the candidates could not be staged; nothing in the vault was touched', { cause: error.code ?? String(error.message) })
+      // The caller stopped the publication between two candidates: nothing failed to stage, and its reason (a
+      // setting that changed during the tick, `mixed-read`, or a cancellation) is the one reported. So is a refusal's.
+      // A cleanup that failed does not replace either: it is named in their detail as `cleanupCause`, and what it could
+      // not remove stays where it is.
+      if (stopped || refused) throw withCleanupCause(error, cleanupFailure)
+      refuse('staging-failed', 'the candidates could not be staged; nothing in the vault was touched', { cause: error.code ?? String(error.message), ...cleanupCauseOf(cleanupFailure) })
     }
+    await budget.checkpoint('journal-and-moves-complete', true)
+    store.checkAllocatedVault?.()
     crash('after-staging')
 
-    const context = { store, journal, journalId, channel, clock, crash, mode }
+    const context = { store, journal, journalId, channel, clock, crash, mode, rules }
     const results = []
     // Kept notes are compared first, several at a time; one that holds exactly its candidate bytes is unchanged.
     const unchanged = await unchangedKeepUnits(units, store)
@@ -379,15 +528,24 @@ export async function publishView(options = {}) {
     // passed since the last reading. An app that starts after a reading and
     // before the next is not seen; that window is at most two seconds plus
     // one note's publication.
+    // The `direct-unheld` path reads its evidence on the same schedule, and once a reading gives none, every remaining
+    // unit refuses, a kept one included, so nothing is committed.
     let lastProbe = null
     for (const unit of units) {
+      await budget.checkpoint('publish-unit')
+      store.checkAllocatedVault?.()
       if (mode === 'direct' && (lastProbe === null || Date.now() - lastProbe > 2000)) {
         lastProbe = Date.now()
         const again = await adapter.probe({ vaultRoot: store.vaultRoot })
         if (again.state !== 'absent') context.uncoordinated = again.reason
       }
+      if (mode === 'direct-unheld' && !context.uncoordinated && (lastProbe === null || Date.now() - lastProbe > 2000)) {
+        lastProbe = Date.now()
+        if (!(await readsUnlisted(unheldEvidence, store))) context.uncoordinated = 'the vault list of the app no longer shows, positively, that no Obsidian lists this vault'
+      }
+      store.checkAllocatedVault?.()
       if (unit.op === 'keep' && unchanged.has(unit.path)) {
-        results.push({ path: unit.path, kind: unit.kind, op: unit.op, outcome: context.uncoordinated ? 'editor-uncoordinated' : 'unchanged', blocking: false })
+        results.push({ path: unit.path, kind: unit.kind, op: unit.op, outcome: context.uncoordinated ? 'editor-uncoordinated' : 'unchanged', blocking: mode === 'direct-unheld' && Boolean(context.uncoordinated) })
         continue
       }
       try { results.push(await publishUnit(unit, context)) } catch (error) {
@@ -398,11 +556,13 @@ export async function publishView(options = {}) {
       }
     }
 
+    await budget.checkpoint('publication-complete', true)
+    store.checkAllocatedVault?.()
     const blocking = results.filter((result) => result.blocking)
     const retainedEdits = results.filter((result) => result.retained).map((result) => result.retained)
     // Notes kept earlier stay surfaced until they leave the vault or come back into a view.
     const base = { journalId, generationId: manifest.generationId, mode, notes: results.map(({ retained, ...rest }) => rest), retainedEdits, recovered }
-    if (blocking.length > 0) {
+    if (blocking.length > 0 || (mode === 'direct-unheld' && context.uncoordinated)) {
       const lateWriters = recheckDisplacedFiles({ store, journalIds: [journalId], clock })
       return { ...base, state: 'updating', lateWriters }
     }
@@ -414,8 +574,19 @@ export async function publishView(options = {}) {
       journal.append({ step: 'verify', outcome: 'conflict', state: 'verifying', notePath: finding.notePath, beforeDigest: finding.digestAtMove, afterDigest: finding.observedDigest, recoveryRef: finding.displacedRef,
         detail: { unit: finding.unit, code: 'late-writer-captured', objectRef: finding.objectRef } })
     }
+    await budget.checkpoint('verify-before-commit', true)
+    // The resident engine revalidates the selected source pins here, while
+    // publication still owns its locks. Its check may yield; no durability
+    // unit or committed pointer is half-written across that wait. It comes
+    // before the entry that says the publication settled: restart recovery
+    // commits a journal that holds that entry, so a refusal after it would be
+    // committed by the next publication of this view.
+    await options.beforeCommit?.()
+    budget.check()
+    store.checkAllocatedVault?.()
     journal.append({ step: 'verify', outcome: 'ok', state: 'verifying', detail: { settled: true, retained: retainedEdits } })
     crash('before-manifest-commit')
+    store.checkAllocatedVault?.()
     store.commitManifest({ manifestBytes, generationId: manifest.generationId, journalId, retained: retainedEdits, committedAt: iso(clock) })
     crash('after-manifest-pointer')
     journal.append({ step: 'manifest-commit', outcome: 'ok', state: 'committed', detail: { manifestDigest: sha256Digest(manifestBytes) } })
@@ -424,11 +595,13 @@ export async function publishView(options = {}) {
     return { ...base, state: 'committed', lateWriters }
   } catch (error) {
     if (!(error instanceof PublicationRefusal)) {
-      if (journal) try { journal.append({ step: 'verify', outcome: 'failed', state: 'failed', detail: { code: 'publisher-error', message: String(error.code ?? error.message).slice(0, 200) } }) } catch { /* the journal itself cannot be written */ }
+      if (journal) try { journal.append({ step: 'verify', outcome: 'failed', state: 'failed', detail: { code: rules.journalFailureCode(error), message: String(error.code ?? error.message).slice(0, 200) } }) } catch { /* the journal itself cannot be written */ }
       throw error
     }
     return { state: 'refused', refusal: { code: error.code, message: error.message, detail: error.detail }, notes: [], retainedEdits: [], lateWriters: [] }
   } finally {
+    // A release that fails is kept and tried again before the next publication of that lock, even when the lock's folder
+    // is not there now: a vault moved away keeps its ticket and may be put back.
     for (const [lockPath, release] of releases.reverse()) try { release() } catch { unreleased.set(lockPath, release) }
   }
 }
@@ -487,9 +660,15 @@ async function publishOneUnit(unit, context) {
   const { store, journal, journalId, clock } = context
   const note = path.join(store.vaultRoot, unit.path)
   const outcome = (code, extra = {}) => ({ path: unit.path, kind: unit.kind, op: unit.op, outcome: code, blocking: false, ...extra })
-  if (unit.op === 'leave-absent') return outcome('left-absent')
+  // On the `direct-unheld` path a unit after a failed reading refuses, whatever it would have done, so the run says why
+  // it stopped.
+  if (unit.op === 'leave-absent') return context.mode === 'direct-unheld' && context.uncoordinated ? outcome('editor-uncoordinated', { blocking: true }) : outcome('left-absent')
   const observe = (bytes) => store.retainObject(bytes)
-  if (context.uncoordinated) return outcome('editor-uncoordinated', { blocking: unit.op !== 'keep' })
+  if (context.uncoordinated) return outcome('editor-uncoordinated', { blocking: unit.op !== 'keep' || context.mode === 'direct-unheld' })
+  // The `direct-unheld` path creates files and nothing else. A unit planned as a replacement or a removal has no
+  // candidate staged, and is refused before its file is even read. (A kept unit may still become a create; a settings
+  // unit is decided in planSettings.)
+  if (context.mode === 'direct-unheld' && unit.op !== 'keep' && unit.op !== 'settings' && !context.rules.unheldWrites(unit.op)) return outcome('editor-uncoordinated', { blocking: true })
   // A settings path that cannot be written safely (a symlinked `.obsidian`,
   // say) is reported and left alone; it must not keep every note from
   // converging while the person repairs it. Notes and attachments block.
@@ -532,6 +711,11 @@ async function publishOneUnit(unit, context) {
     if (plan.stagedPath) retire(plan, context)
     return outcome('already-current')
   }
+  // Whatever a unit became on the way here, the `direct-unheld` path writes nothing below this point but a create.
+  if (context.mode === 'direct-unheld' && !context.rules.unheldWrites(plan.op)) {
+    if (plan.stagedPath) retire(plan, context)
+    return outcome('editor-uncoordinated', { blocking: true })
+  }
 
   if (unit.path === PLUGIN_DATA_PATH && plan.op !== 'remove') {
     const privacy = ensurePrivateVaultRoot(store)
@@ -706,6 +890,11 @@ function planSettings(unit, context) {
   if (Object.hasOwn(unit, 'expectedDigest') && (existing === null ? null : sha256Digest(existing)) !== unit.expectedDigest) {
     return { path: unit.path, kind: 'settings', op: 'settings', outcome: 'settings-changed', blocking: true }
   }
+  // On the `direct-unheld` path a settings file that is there is never written over, and no candidate is staged for it.
+  // Only one that already holds exactly what the policy asks (Atelier's own, from an interrupted run) is left as it is.
+  if (context.mode === 'direct-unheld' && existing !== null && !context.rules.unheldWrites('replace') && !holdsPolicy(unit.path, existing)) {
+    return { path: unit.path, kind: 'settings', op: 'settings', outcome: 'editor-uncoordinated', blocking: true }
+  }
   let file
   try { file = preparePolicySettingsFile(unit.path, existing) } catch (error) {
     if (error instanceof ObsidianContractRefusal) return { path: unit.path, kind: 'settings', op: 'settings', outcome: 'settings-invalid', blocking: false }
@@ -720,6 +909,13 @@ function planSettings(unit, context) {
   return plan
 }
 
+function holdsPolicy(settingsPath, bytes) {
+  try { return preparePolicySettingsFile(settingsPath, bytes).bytes.equals(bytes) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) return false
+    throw error
+  }
+}
+
 function verify(unit, plan, { store, journal }, result) {
   const bytes = readNote(path.join(store.vaultRoot, unit.path))
   const digest = bytes === null ? null : sha256Digest(bytes)

package/src/projection/obsidian/publication/vault-list.mjs

@@ -109,13 +109,14 @@ const currentUid = () => (typeof process.getuid === 'function' ? process.getuid(
 // { ok: false, code, message }. The user-data directory and the file must be
 // this user's own, a real directory and a regular file; the file must be a
 // JSON object whose `vaults`, when present, is an object. A missing directory
-// or file means Obsidian has not run on this account.
+// or file means Obsidian has not run on this account, or has shown only its
+// starter window, which writes no list: that refusal names `userDataDir`.
 export function readObsidianSettings({ userDataDir, uid = currentUid() } = {}) {
   if (typeof userDataDir !== 'string' || !path.isAbsolute(userDataDir)) return refused('obsidian-settings-location-unknown', 'where Obsidian keeps its settings on this system is not known')
   const owned = (stat) => uid === null || stat.uid === uid
   let directory
   try { directory = fs.lstatSync(userDataDir) } catch (error) {
-    if (error.code === 'ENOENT') return refused('obsidian-settings-missing', 'Obsidian has no settings directory on this account; it has not run here')
+    if (error.code === 'ENOENT') return { ...refused('obsidian-settings-missing', 'Obsidian has no settings directory on this account; it has not run here'), userDataDir }
     return refused('obsidian-settings-unreadable', 'the Obsidian settings directory cannot be read')
   }
   if (directory.isSymbolicLink() || !directory.isDirectory()) return refused('obsidian-settings-unsafe', 'the Obsidian settings directory is a link or not a directory')
@@ -123,7 +124,7 @@ export function readObsidianSettings({ userDataDir, uid = currentUid() } = {}) {
   const file = path.join(userDataDir, OBSIDIAN_SETTINGS_FILE)
   let leaf
   try { leaf = fs.lstatSync(file) } catch (error) {
-    if (error.code === 'ENOENT') return refused('obsidian-settings-missing', 'Obsidian has no settings file on this account; it has not run here')
+    if (error.code === 'ENOENT') return { ...refused('obsidian-settings-missing', 'Obsidian has no settings file on this account; it has not run here'), userDataDir }
     return refused('obsidian-settings-unreadable', 'the Obsidian settings file cannot be read')
   }
   if (leaf.isSymbolicLink() || !leaf.isFile()) return refused('obsidian-settings-unsafe', 'the Obsidian settings file is a link or not a regular file')

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

@@ -1,6 +1,9 @@
 // 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 {
+  EXCHANGE_CANDIDATE_NAME, LATE_EXCHANGE_CANDIDATE_NAME, PublicationRefusal, VAULT_ALLOCATION_SCHEMA, VAULT_LOCK_DIRECTORY, VAULT_ORIGINS, acquireVaultLock, allocatedFolderState, assertAllocatedFolder, allocationFile, folderIdentity,
+  createRecoveryStore, hasCommittedGeneration, legacyVaultRoot, readFileDigest, readVaultAllocation, sha256Digest, validateVaultAllocation, vaultRootFor, writeVaultAllocation,
+} 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'