@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

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

@@ -3,12 +3,13 @@ import fsp from 'node:fs/promises'
 import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { acquirePrivateLock, publishPrivateFile, syncPrivateDirectory } from '../../../project/durable-state.mjs'
-import { ObsidianContractRefusal, assertObsidianContract } from '../contracts.mjs'
-import { isPolicySettingsPath, isUserOwnedSettingsPath, prepareSettings } from '../materialize/settings.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract, manifestLayoutVersion } from '../contracts.mjs'
+import { isPluginOwnedPath, isPolicySettingsPath, isUserOwnedSettingsPath, preparePolicySettingsFile } from '../materialize/settings.mjs'
+import { PLUGIN_DATA_MODE, PLUGIN_DATA_PATH, PLUGIN_SOURCE_MODE } from '../plugin-bridge/channel.mjs'
 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'
@@ -36,14 +37,53 @@ import { createDirectAdapter } from './transport.mjs'
 // from `recovery/<journalId>/<unit>/`, never from staging. Staging holds only
 // generated bytes that no exchange names: every candidate while it is written,
 // and the candidates of created files until they are linked into the vault.
+//
+// Atelier's own plugin files (kind `plugin`) go through the same units, with
+// two differences: each is compared with what the disk holds when the run
+// begins rather than with an earlier generation, so whatever is there is
+// 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
+// publishView, which reports it for that unit only.
+const READ_ATTEMPTS = 5
 function readNote(file) {
-  try { return readFileBytes(file) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+  for (let attempt = 1; ; attempt += 1) {
+    try { return readFileBytes(file) } catch (error) {
+      if (error.code === 'ENOENT') return null
+      if (error.code !== 'ELEAFCHANGED' || attempt >= READ_ATTEMPTS) throw error
+    }
+  }
 }
 
 function validatePreparedView(preparedView, store) {
@@ -61,22 +101,35 @@ function validatePreparedView(preparedView, store) {
     if (expected.has(declared)) refuse('invalid-prepared-view', 'the manifest declares one path more than once')
     expected.set(declared, fileDigest)
   }
+  // Atelier's plugin files are pinned by the settings unit's record in the manifest.
+  const pinnedPlugin = manifest.ext?.[OBSIDIAN_EXT_KEY]?.settings?.pluginOwned?.files
+  const pinned = new Map(Array.isArray(pinnedPlugin) ? pinnedPlugin.map((file) => [file?.path, file?.digest]) : [])
   const seen = new Set()
   for (const file of preparedView.files) {
     if (!isAddressableVaultPath(file.path) || isUserOwnedSettingsPath(file.path)) refuse('invalid-prepared-view', 'a prepared path is outside what the publisher may write')
     if (seen.has(file.path)) refuse('invalid-prepared-view', 'a prepared path appears twice')
     seen.add(file.path)
     if (file.kind === 'settings') {
-      if (!isPolicySettingsPath(file.path)) refuse('invalid-prepared-view', 'only the policy settings file may be prepared as settings')
+      if (!isPolicySettingsPath(file.path)) refuse('invalid-prepared-view', 'only a policy settings file may be prepared as settings')
       continue
     }
-    if (!['note', 'attachment'].includes(file.kind) || isPolicySettingsPath(file.path)) refuse('invalid-prepared-view', 'a prepared file has an unknown kind')
+    if (file.kind === 'plugin') {
+      if (!isPluginOwnedPath(file.path) || !Buffer.isBuffer(file.bytes) || sha256Digest(file.bytes) !== file.digest || pinned.get(file.path) !== file.digest) {
+        refuse('invalid-prepared-view', 'a plugin file, its digest and the digest the manifest pins disagree')
+      }
+      // Read by the app, never run by anyone: the data file owner-only, the others readable.
+      if (file.mode !== (file.path === PLUGIN_DATA_PATH ? PLUGIN_DATA_MODE : PLUGIN_SOURCE_MODE)) refuse('invalid-prepared-view', 'a plugin file has a mode Atelier never gives one')
+      pinned.delete(file.path)
+      continue
+    }
+    if (!['note', 'attachment'].includes(file.kind) || isPolicySettingsPath(file.path) || isPluginOwnedPath(file.path)) refuse('invalid-prepared-view', 'a prepared file has an unknown kind')
     if (!Buffer.isBuffer(file.bytes) || sha256Digest(file.bytes) !== file.digest || expected.get(file.path) !== file.digest) {
       refuse('invalid-prepared-view', 'prepared bytes, their digest and the manifest disagree')
     }
     expected.delete(file.path)
   }
   if (expected.size > 0) refuse('invalid-prepared-view', 'the manifest names a file the prepared view does not carry')
+  if (pinned.size > 0) refuse('invalid-prepared-view', 'the manifest pins a plugin file the prepared view does not carry')
   let parsedBytes = null
   if (Buffer.isBuffer(preparedView.manifestBytes)) {
     try { parsedBytes = JSON.parse(preparedView.manifestBytes.toString('utf8')) } catch { refuse('invalid-prepared-view', 'manifest bytes are not JSON') }
@@ -169,7 +222,65 @@ async function holdsCandidateBytes(vaultRoot, relativePath, candidateDigest) {
   }
 }
 
-function planUnits({ files, priorManifest, pointer, ledger }) {
+// The digest of what a vault path holds now: null when it is absent, sits
+// under a parent that is not a real directory, is not a regular file or cannot
+// be read. Only Atelier's plugin files are planned from it.
+function currentDigestOf(vaultRoot, relativePath) {
+  let current = vaultRoot
+  for (const part of relativePath.split('/').slice(0, -1)) {
+    current = path.join(current, part)
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false })
+    if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) return null
+  }
+  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, 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)
+    if (current === file.digest || (current === null && file.onlyIfPresent === true)) return false
+    try { return !leftForThePerson(store, file.path) } catch { return true }
+  })
+}
+
+// One unit per file the publication creates, keeps, replaces or removes. Exported for the oracle tests.
+export function planUnits({ files, priorManifest, pointer, ledger, pluginDisk = new Map() }) {
   const trusted = new Map()
   for (const note of priorManifest?.notes ?? []) trusted.set(note.path, note.noteDigest)
   for (const attachment of priorManifest?.attachments ?? []) trusted.set(attachment.path, attachment.digest)
@@ -177,24 +288,67 @@ function planUnits({ files, priorManifest, pointer, ledger }) {
   for (const item of pointer?.retained ?? []) if (item.priorDigest && !item.movedToRecovery) trusted.set(item.path, item.priorDigest)
   for (const [notePath, digest] of ledger) { if (digest === null) trusted.delete(notePath); else trusted.set(notePath, digest) }
 
+  // A file leaves as an attachment when the prior generation listed it as one. Layout 1 kept every file under
+  // `attachments/`, so there that folder says it too (of a file an interrupted run published); in layout 2 it is only
+  // a repository's folder.
+  const priorAttachments = new Set((priorManifest?.attachments ?? []).map((attachment) => attachment.path))
+  const underAttachments = !priorManifest || manifestLayoutVersion(priorManifest) === 1
   const units = []
   const present = new Set()
   for (const file of files) {
     present.add(file.path)
-    if (file.kind === 'settings') { units.push({ path: file.path, kind: 'settings', op: 'settings' }); continue }
+    // A settings file prepared from the bytes it held when the view was prepared carries their digest: it is written only over them.
+    if (file.kind === 'settings') { units.push({ path: file.path, kind: 'settings', op: 'settings', ...(Object.hasOwn(file, 'expectedDigest') ? { expectedDigest: file.expectedDigest } : {}) }); continue }
+    if (file.kind === 'plugin') {
+      const current = pluginDisk.get(file.path) ?? null
+      // A plugin file the person removed while the plugin is off in this vault stays removed.
+      if (current === null && file.onlyIfPresent === true) { units.push({ path: file.path, kind: 'plugin', op: 'leave-absent' }); continue }
+      units.push({ path: file.path, kind: 'plugin', op: current === null ? 'create' : current === file.digest ? 'keep' : 'replace', baseDigest: current, candidateDigest: file.digest, bytes: file.bytes, mode: file.mode })
+      continue
+    }
     const base = trusted.get(file.path)
     const op = base === undefined ? 'create' : base === file.digest ? 'keep' : 'replace'
     units.push({ path: file.path, kind: file.kind, op, baseDigest: base ?? null, candidateDigest: file.digest, bytes: file.bytes })
   }
   for (const [notePath, digest] of [...trusted].sort(([left], [right]) => (left < right ? -1 : 1))) {
-    if (!present.has(notePath)) units.push({ path: notePath, kind: notePath.startsWith('attachments/') ? 'attachment' : 'note', op: 'remove', baseDigest: digest, candidateDigest: null })
+    if (!present.has(notePath)) units.push({ path: notePath, kind: priorAttachments.has(notePath) || (underAttachments && notePath.startsWith('attachments/')) ? 'attachment' : 'note', op: 'remove', baseDigest: digest, candidateDigest: null })
   }
   units.forEach((unit, index) => { unit.unit = index })
   return units
 }
 
-export async function publishView(options = {}) {
+// 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 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')
@@ -209,30 +363,43 @@ 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?.()
     const recovered = recoverPublicationsLocked({ store, clock })
     const pointer = store.readCurrent()
-    if (pointer?.generationId === manifest.generationId) {
+    if (pointer?.generationId === manifest.generationId && !pluginFilesDrifted(preparedView, store)) {
       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 })
 
-    // Path selection.
+    // 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('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.
@@ -247,7 +414,8 @@ export async function publishView(options = {}) {
     const exchange = probeExchange({ directory: probeDir, ...exchangeOptions })
     if (!exchange.supported) refuse(exchange.code, exchange.message)
 
-    const units = planUnits({ files: preparedView.files, priorManifest: store.readCurrentManifest(), pointer, ledger: publishedSinceCommit({ store }) })
+    const pluginDisk = new Map(preparedView.files.filter((file) => file.kind === 'plugin').map((file) => [file.path, currentDigestOf(store.vaultRoot, file.path)]))
+    const units = planUnits({ files: preparedView.files, priorManifest: store.readCurrentManifest(), pointer, ledger: publishedSinceCommit({ store }), pluginDisk })
 
     // Stage every known candidate before anything is touched.
     const journalId = newJournalId(clock)
@@ -256,10 +424,11 @@ 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))))) {
         const existing = fs.lstatSync(path.join(store.vaultRoot, unit.path), { throwIfNoEntry: false })
         unit.preparedPath = store.preparedPath(journalId, unit.unit)
-        stageCandidate(unit.preparedPath, unit.bytes, existing?.isFile() ? existing.mode & 0o777 : 0o644, created)
+        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
       }
@@ -270,7 +439,7 @@ export async function publishView(options = {}) {
         detail: { mode, manifestRef: store.ref(manifestFile), manifestDigest: sha256Digest(manifestBytes),
           // The units this run may write. A kept note is compared and never written; the one case that writes
           // it after all (a kept note gone missing) is a late candidate with its own write-ahead entry.
-          units: units.filter((item) => item.op !== 'keep').map(({ unit, path: unitPath, kind, op }) => ({ unit, path: unitPath, kind, op })),
+          units: units.filter((item) => item.op !== 'keep' && item.op !== 'leave-absent').map(({ unit, path: unitPath, kind, op }) => ({ unit, path: unitPath, kind, op })),
           staged: units.filter((item) => item.stagedPath).map((item) => ({ unit: item.unit, path: item.path, candidateDigest: item.candidateDigest, stagedRef: store.ref(item.stagedPath),
             ...(item.stagedPath === item.preparedPath ? {} : { preparedRef: store.ref(item.preparedPath) }) })) } })
       crash('before-candidate-move')
@@ -295,7 +464,7 @@ export async function publishView(options = {}) {
     }
     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)
@@ -306,6 +475,8 @@ 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) {
       if (mode === 'direct' && (lastProbe === null || Date.now() - lastProbe > 2000)) {
@@ -313,18 +484,28 @@ export async function publishView(options = {}) {
         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
       }
-      results.push(await publishUnit(unit, context))
+      try { results.push(await publishUnit(unit, context)) } catch (error) {
+        if (error.code !== 'ELEAFCHANGED') throw error
+        // Another program kept replacing this file while it was read: its bytes are left as they are, the unit's
+        // journal stays open for recovery like an interrupted one, and the other units go on.
+        results.push({ path: unit.path, kind: unit.kind, op: unit.op, outcome: 'disk-changed', blocking: true })
+      }
     }
 
     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 }
     }
@@ -338,6 +519,7 @@ export async function publishView(options = {}) {
     }
     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) } })
@@ -351,26 +533,85 @@ export async function publishView(options = {}) {
     }
     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) }
   }
 }
 
 // ---------------------------------------------------------------------------
-// One note, attachment or settings file
+// One note, attachment, settings file or plugin file
 // ---------------------------------------------------------------------------
 
+// Atelier's own plugin never waits on a person: a plugin path that cannot be
+// written safely, a vault root not private enough for the bearer, or a file
+// that could not be made or replaced there (a plugin folder the person can read
+// but not write, say) is reported and left for the person while every note
+// converges, and its candidate is retired at once. A plugin file that another
+// writer changed under this run is a race: it blocks like a note, so the view
+// is tried again and the file is planned from the disk anew. Nothing reads a
+// plugin file as a person's edit of a note: its outcomes carry their own names.
+const PLUGIN_LEFT_FOR_A_PERSON = new Set(['path-unsafe', 'vault-not-private', 'create-failed', 'exchange-failed'])
+// A leaf or a parent nobody may look into or read (another owner, mode 000) or a link loop: the person's to repair,
+// like a leaf that is not a file. It is reported, never thrown, so the rest of the view and every later view go on.
+const UNREADABLE_PATH = new Set(['EACCES', 'EPERM', 'ELOOP'])
+const PLUGIN_FILE_CHANGED = new Set(['edit-kept', 'disk-changed', 'editor-edit'])
+
 async function publishUnit(unit, context) {
+  let result
+  try { result = await publishOneUnit(unit, context) } catch (error) {
+    // A plugin or settings file another program kept replacing while it was opened (see readNote) is a race of that
+    // file, like one that changed under the run: blocking, tried again, and never taken for a person's edit of a note.
+    if (error?.code !== 'ELEAFCHANGED' || (unit.kind !== 'plugin' && unit.kind !== 'settings')) throw error
+    // Its candidate is left as #83 leaves a note's: the unit's journal stays open for recovery like an interrupted one.
+    result = { path: unit.path, kind: unit.kind, op: unit.op, outcome: unit.kind === 'settings' ? 'settings-changed' : 'disk-changed', blocking: true }
+  }
+  if (unit.kind !== 'plugin') return result
+  const { changedAfterPublication, retained: _retained, ...rest } = result
+  if (rest.outcome === 'path-unsafe' && unit.stagedPath) retire(unit, context)
+  const changed = PLUGIN_FILE_CHANGED.has(rest.outcome)
+  return { ...rest, outcome: changed ? 'plugin-file-changed' : rest.outcome, blocking: changed || (rest.blocking && !PLUGIN_LEFT_FOR_A_PERSON.has(rest.outcome)), ...(changedAfterPublication ? { pluginFileChanged: true } : {}) }
+}
+
+// The vault root holds the plugin's bearer once its data file is there, so it
+// must be private to this user. A vault root Atelier placed under its own data
+// root is made private here; any other one is only looked at, and a vault path
+// under the data root that is a link to somewhere else never receives it.
+function ensurePrivateVaultRoot(store) {
+  if (store.linkedVaultRoot === true) return { private: false, reason: 'vault-root-is-a-link' }
+  const uid = typeof process.getuid === 'function' ? process.getuid() : null
+  let stat = fs.lstatSync(store.vaultRoot, { throwIfNoEntry: false })
+  if (!stat?.isDirectory() || uid === null || stat.uid !== uid) return { private: false, reason: 'vault-root-not-owned' }
+  if ((stat.mode & 0o077) !== 0 && store.managedVaultRoot === true) {
+    try { fs.chmodSync(store.vaultRoot, stat.mode & 0o700) } catch { /* looked at again below */ }
+    stat = fs.lstatSync(store.vaultRoot, { throwIfNoEntry: false })
+  }
+  return stat?.isDirectory() && (stat.mode & 0o077) === 0 ? { private: true } : { private: false, reason: 'vault-root-not-private' }
+}
+
+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 })
+  // 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.
   const unsafeBlocks = unit.op !== 'settings'
-  if (!ensureParents(store.vaultRoot, unit.path)) return outcome('path-unsafe', { blocking: unsafeBlocks })
-  const leaf = fs.lstatSync(note, { throwIfNoEntry: false })
+  const unreadable = (error) => { if (!UNREADABLE_PATH.has(error?.code)) throw error; return outcome('path-unsafe', { blocking: unsafeBlocks, errorCode: error.code }) }
+  let leaf
+  try {
+    if (!ensureParents(store.vaultRoot, unit.path)) return outcome('path-unsafe', { blocking: unsafeBlocks })
+    leaf = fs.lstatSync(note, { throwIfNoEntry: false })
+  } catch (error) { return unreadable(error) }
   if (leaf && !leaf.isFile()) return outcome('path-unsafe', { blocking: unsafeBlocks })
 
   let plan = unit
@@ -378,7 +619,8 @@ async function publishUnit(unit, context) {
     plan = planSettings(unit, context)
     if (plan.outcome) return plan
   }
-  const current = readNote(note)
+  let current
+  try { current = readNote(note) } catch (error) { return unreadable(error) }
   const currentDigest = current === null ? null : sha256Digest(current)
 
   if (plan.op === 'keep') {
@@ -402,6 +644,19 @@ async function publishUnit(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)
+    if (!privacy.private) {
+      if (plan.stagedPath) retire(plan, context)
+      return outcome('vault-not-private', { reason: privacy.reason })
+    }
+  }
 
   const operationId = `${journalId}:${unit.unit}`
   const displaced = plan.op === 'create' ? null : store.displacedPath(journalId, unit.unit)
@@ -552,18 +807,32 @@ function stageLate(plan, { store, journal, journalId, crash, updating }) {
   return unit.stagedPath
 }
 
-// Policy settings are owned per key. The candidate is the file on disk now
-// with only the owned keys set; the base is that same file. A file that is
-// not a JSON object or array is the person's to repair and is left alone.
+// Policy settings are owned per key or entry. The candidate is the file on
+// disk now with only what Atelier owns set; the base is that same file. A file
+// whose shape the policy does not know is the person's to repair and is left
+// alone.
 function planSettings(unit, context) {
   const note = path.join(context.store.vaultRoot, unit.path)
-  const existing = readNote(note)
-  let prepared
-  try { prepared = prepareSettings({ existing }) } catch (error) {
+  let existing
+  try { existing = readNote(note) } catch (error) {
+    if (!UNREADABLE_PATH.has(error?.code)) throw error
+    return { path: unit.path, kind: 'settings', op: 'settings', outcome: 'path-unsafe', blocking: false, errorCode: error.code }
+  }
+  // Prepared from other bytes than these: the person changed the file since, and whatever Atelier decided from the old
+  // bytes is not written over the change. The view is tried again, and the next preparation reads the file as it is.
+  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 }
     throw error
   }
-  const [file] = prepared.files
   if (existing !== null && file.bytes.equals(existing)) return { path: unit.path, kind: 'settings', op: 'settings', outcome: 'policy-satisfied', blocking: false }
   const plan = { ...unit, op: existing === null ? 'create' : 'replace', baseDigest: existing === null ? null : sha256Digest(existing), candidateDigest: file.digest, bytes: file.bytes,
     mode: existing === null ? 0o644 : fs.lstatSync(note).mode & 0o777 }
@@ -573,6 +842,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)