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

package/src/projection/obsidian/plugin-bridge/channel.mjs

@@ -0,0 +1,174 @@
+import { createHmac } from 'node:crypto'
+
+// The channel between Atelier's own plugin, inside a vault Atelier manages,
+// and the maintenance service of the workspace that manages that vault.
+//
+// A closed command surface over the service's literal loopback listener:
+//
+//   POST /plugin/challenge  a fresh nonce and the time it was made, and a hint
+//                           at which vault's key it means that only the holder
+//                           of that key can read; the service answers, once
+//                           and only while it is fresh, with its own nonce and
+//                           a proof that it holds the key
+//   POST /plugin/hello      only after the plugin checked that proof: its own
+//                           proof, the plugin and app versions, an id of this
+//                           launch of the plugin, and a proof of the vault path
+//                           the app has open (the path itself is never sent)
+//   POST /plugin/lease      "this vault is open in an app", renewed every two
+//                           seconds; it lapses on its own six seconds later
+//   POST /plugin/release    the vault closed, or the plugin unloaded
+//   POST /plugin/status     freshness, reason and held edits of this view
+//
+// The key is the vault's bearer, which Atelier writes into the plugin's data
+// file of that vault only and keeps in private state. It never crosses the
+// wire, and neither does anything that names the view or the vault before the
+// listener proved it holds the key: a program squatting the service's port
+// while the service is down learns a nonce and a hint it cannot link to a
+// vault, and cannot answer. Both proofs bind the listener's exact address, so
+// an answer relayed from a service listening elsewhere does not verify.
+//
+// A challenge recorded by such a program and sent to the service later is
+// worth little: the service answers a challenge only within thirty seconds of
+// the time it names, and a nonce only once, and at most four handshakes wait
+// for their hello per view, so one view's challenges never hold up another's.
+//
+// The handshake derives a key for one session. Every later request carries
+// the session, a counter that only goes up, and a MAC over both and the
+// command under that key; every answer carries a MAC over the request's counter
+// and the exact bytes of the answer. A handshake is used once and lapses after
+// five seconds, a session after fifteen minutes. Nothing here takes a path to
+// act on, a command or code, and every command maps to state the service
+// already keeps (see docs/obsidian-plugin.md).
+//
+// The plugin cannot import this module: it runs inside the app, from the
+// vault. It carries the same constants and the same computations, and the test
+// suite holds the two to each other: a plugin that computes any one of them
+// otherwise cannot complete a handshake.
+
+export const PLUGIN_ID = 'atelier-projection'
+export const PLUGIN_DIRECTORY = `.obsidian/plugins/${PLUGIN_ID}`
+// Shipped with the package under plugins/obsidian/ and copied into every vault unchanged.
+export const PLUGIN_SOURCE_FILES = Object.freeze(['manifest.json', 'main.js', 'styles.css'])
+// Written per vault: the channel address and that vault's bearer.
+export const PLUGIN_DATA_FILE = 'data.json'
+export const PLUGIN_DATA_PATH = `${PLUGIN_DIRECTORY}/${PLUGIN_DATA_FILE}`
+// The data file holds the vault's key: only the person who runs the vault reads it. The app reads the others.
+export const PLUGIN_DATA_MODE = 0o600
+export const PLUGIN_SOURCE_MODE = 0o644
+
+export const PLUGIN_CHANNEL_PROTOCOL = 'atelier-obsidian-plugin-channel/v2'
+export const PLUGIN_DATA_SCHEMA = 'atelier-obsidian-plugin-data/v1'
+export const PLUGIN_STATUS_SCHEMA = 'atelier-obsidian-plugin-status/v1'
+
+export const PLUGIN_COMMANDS = Object.freeze(['challenge', 'hello', 'lease', 'release', 'status'])
+export const PLUGIN_ROUTES = Object.freeze(Object.fromEntries(PLUGIN_COMMANDS.map((command) => [command, `/plugin/${command}`])))
+export const PLUGIN_REQUEST_FIELDS = Object.freeze({
+  challenge: Object.freeze(['protocol', 'keyHint', 'clientNonce', 'issuedAt']),
+  hello: Object.freeze(['handshakeId', 'pluginVersion', 'appVersion', 'instanceId', 'vaultProof', 'clientProof']),
+  lease: Object.freeze(['sessionId', 'counter', 'mac']),
+  release: Object.freeze(['sessionId', 'counter', 'mac']),
+  status: Object.freeze(['sessionId', 'counter', 'mac']),
+})
+
+export const PLUGIN_MAX_REQUEST_BYTES = 1024
+export const PLUGIN_RENEW_INTERVAL_MS = 2000
+// Three renewals may be missed before a vault stops counting as open.
+export const PLUGIN_LEASE_TTL_MS = 3 * PLUGIN_RENEW_INTERVAL_MS
+export const PLUGIN_MAX_SESSIONS_PER_SCOPE = 8
+export const PLUGIN_HANDSHAKE_TTL_MS = 5000
+// A challenge is answered only this close to the time it names (both sides read one machine's clock).
+export const PLUGIN_CHALLENGE_WINDOW_MS = 30 * 1000
+export const PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE = 4
+// A session key is short-lived: the plugin shakes hands again after this long.
+export const PLUGIN_MAX_SESSION_AGE_MS = 15 * 60 * 1000
+// The app version the plugin needs, the floor of the publication protocol (app-capability.mjs).
+export const PLUGIN_MINIMUM_APP_VERSION = '1.13.7'
+
+export const PLUGIN_BEARER = /^[A-Za-z0-9_-]{43}$/
+export const PLUGIN_NONCE = /^[0-9a-f]{64}$/
+// A key hint, a proof and a MAC are each one HMAC-SHA256, in hex.
+export const PLUGIN_MAC = /^[0-9a-f]{64}$/
+export const PLUGIN_HANDSHAKE_ID = /^ph-[0-9a-f]{32}$/
+export const PLUGIN_SESSION_ID = /^ps-[0-9a-f]{32}$/
+export const PLUGIN_INSTANCE_ID = /^pi-[0-9a-f]{32}$/
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const VERSION_TEXT = /^[0-9A-Za-z.+-]{1,40}$/
+const LOOPBACK_HOSTS = Object.freeze(['127.0.0.1', '::1'])
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The route of a request path, or null. Exact paths only: no query, no prefix.
+export function pluginCommandOf(requestPath) {
+  return PLUGIN_COMMANDS.find((command) => PLUGIN_ROUTES[command] === requestPath) ?? null
+}
+
+// { ok: true, body } or { ok: false, code }. The body has exactly the fields
+// of its command, each of its own shape; anything else refuses.
+export function validatePluginRequest(command, body) {
+  const fields = PLUGIN_REQUEST_FIELDS[command]
+  if (fields === undefined) return { ok: false, code: 'unknown-command' }
+  if (!isPlainObject(body)) return { ok: false, code: 'request-malformed' }
+  const keys = Object.keys(body)
+  if (keys.length !== fields.length || !fields.every((field) => Object.hasOwn(body, field))) return { ok: false, code: 'request-malformed' }
+  const shaped = (field, pattern) => typeof body[field] === 'string' && pattern.test(body[field])
+  if (command === 'challenge') {
+    if (body.protocol !== PLUGIN_CHANNEL_PROTOCOL) return { ok: false, code: 'protocol-unsupported' }
+    if (!shaped('keyHint', PLUGIN_MAC) || !shaped('clientNonce', PLUGIN_NONCE) || !Number.isSafeInteger(body.issuedAt) || body.issuedAt < 1) return { ok: false, code: 'request-malformed' }
+  } else if (command === 'hello') {
+    if (!shaped('handshakeId', PLUGIN_HANDSHAKE_ID) || !shaped('instanceId', PLUGIN_INSTANCE_ID) || !shaped('vaultProof', PLUGIN_MAC) || !shaped('clientProof', PLUGIN_MAC)) return { ok: false, code: 'request-malformed' }
+    if (!shaped('pluginVersion', VERSION_TEXT) || !shaped('appVersion', VERSION_TEXT)) return { ok: false, code: 'request-malformed' }
+  } else if (!shaped('sessionId', PLUGIN_SESSION_ID) || !shaped('mac', PLUGIN_MAC) || !Number.isSafeInteger(body.counter) || body.counter < 1) {
+    return { ok: false, code: 'request-malformed' }
+  }
+  return { ok: true, body }
+}
+
+// The computations of the handshake and the session, shared with the plugin.
+// Every input but a vault path is one of the shapes above, without a line
+// break, and a vault path is the only input of its computation, so joining
+// them by lines is unambiguous. `key` is the vault's bearer text, or a
+// session key.
+const transcript = (label, fields) => [PLUGIN_CHANNEL_PROTOCOL, label, ...fields.map(String)].join('\n')
+const hmac = (key, label, fields) => createHmac('sha256', key).update(transcript(label, fields), 'utf8').digest()
+const hmacHex = (key, label, fields) => hmac(key, label, fields).toString('hex')
+
+// A hint at the vault's key, fresh with every nonce and bound to the time the
+// challenge names: the service finds the key it names by computing it for each
+// key it holds, and a listener that holds none cannot tell two hints of one
+// vault apart, nor move one to another time.
+export const pluginKeyHint = ({ bearer, clientNonce, issuedAt }) => hmacHex(bearer, 'key-hint', [clientNonce, issuedAt])
+// What binds a handshake: the view, the listener's exact address, both nonces and the handshake.
+const handshakeFields = ({ scopeId, authority, clientNonce, serverNonce, handshakeId }) => [scopeId, authority, clientNonce, serverNonce, handshakeId]
+export const pluginServerProof = (input) => hmacHex(input.bearer, 'server-proof', handshakeFields(input))
+export const pluginSessionKey = (input) => hmac(input.bearer, 'session-key', handshakeFields(input))
+// The vault the app has open, proven under the session key rather than named.
+export const pluginVaultProof = ({ sessionKey, vaultPath }) => hmacHex(sessionKey, 'vault', [vaultPath])
+export const pluginClientProof = (input) => hmacHex(input.bearer, 'client-proof', [...handshakeFields(input), input.pluginVersion, input.appVersion, input.instanceId, input.vaultProof])
+export const pluginRequestMac = ({ sessionKey, command, sessionId, counter }) => hmacHex(sessionKey, 'request', [command, sessionId, counter])
+// An answer is the exact text of its JSON document and a MAC over it, the command and the request's counter.
+export const pluginResponseMac = ({ sessionKey, command, sessionId, counter, payload }) => hmacHex(sessionKey, 'response', [command, sessionId, counter, payload])
+
+// The plugin's data file of one vault: where the service listens and the
+// bearer of this vault. Canonical bytes, so an unchanged channel republishes
+// nothing.
+export function pluginDataDocument({ host, port, scopeId, bearer }) {
+  const document = { schema: PLUGIN_DATA_SCHEMA, channel: { host, port }, scopeId, bearer }
+  if (validatePluginData(document) === null) throw new TypeError('the plugin data needs a literal loopback address, a port, a view and a bearer')
+  return document
+}
+
+export function pluginDataBytes(input) {
+  const { schema, channel, scopeId, bearer } = pluginDataDocument(input)
+  return Buffer.from(`${JSON.stringify({ schema, channel: { host: channel.host, port: channel.port }, scopeId, bearer }, null, 2)}\n`, 'utf8')
+}
+
+// The document when it is exactly a plugin data document, else null.
+export function validatePluginData(document) {
+  if (!isPlainObject(document) || Object.keys(document).sort().join(',') !== 'bearer,channel,schema,scopeId') return null
+  if (document.schema !== PLUGIN_DATA_SCHEMA || typeof document.scopeId !== 'string' || !IDENTIFIER.test(document.scopeId)) return null
+  if (typeof document.bearer !== 'string' || !PLUGIN_BEARER.test(document.bearer)) return null
+  const { channel } = document
+  if (!isPlainObject(channel) || Object.keys(channel).sort().join(',') !== 'host,port') return null
+  if (!LOOPBACK_HOSTS.includes(channel.host) || !Number.isInteger(channel.port) || channel.port < 1024 || channel.port > 65535) return null
+  return document
+}

package/src/projection/obsidian/plugin-bridge/index.mjs

@@ -0,0 +1,10 @@
+// Atelier's own Obsidian plugin: the channel it speaks and the files that put
+// it into a vault. The plugin source ships under plugins/obsidian/.
+export {
+  PLUGIN_BEARER, PLUGIN_CHALLENGE_WINDOW_MS, PLUGIN_CHANNEL_PROTOCOL, PLUGIN_COMMANDS, PLUGIN_DATA_FILE, PLUGIN_DATA_PATH, PLUGIN_DATA_SCHEMA, PLUGIN_DIRECTORY, PLUGIN_HANDSHAKE_ID, PLUGIN_HANDSHAKE_TTL_MS,
+  PLUGIN_ID, PLUGIN_INSTANCE_ID, PLUGIN_LEASE_TTL_MS, PLUGIN_MAC, PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE, PLUGIN_MAX_REQUEST_BYTES, PLUGIN_MAX_SESSION_AGE_MS, PLUGIN_MAX_SESSIONS_PER_SCOPE,
+  PLUGIN_MINIMUM_APP_VERSION, PLUGIN_NONCE, PLUGIN_RENEW_INTERVAL_MS, PLUGIN_REQUEST_FIELDS, PLUGIN_ROUTES, PLUGIN_SESSION_ID, PLUGIN_SOURCE_FILES,
+  PLUGIN_STATUS_SCHEMA, pluginClientProof, pluginCommandOf, pluginDataBytes, pluginDataDocument, pluginKeyHint, pluginRequestMac, pluginResponseMac, pluginServerProof, pluginSessionKey,
+  pluginVaultProof, validatePluginData, validatePluginRequest,
+} from './channel.mjs'
+export { PLUGIN_DATA_MODE, PLUGIN_SOURCE_MODE, PLUGIN_SOURCE_ROOT, preparePluginFiles, readPluginSource } from './bundle.mjs'

package/src/projection/obsidian/proposals/observation.mjs

@@ -5,7 +5,7 @@ import { compareText, isoTime } from '../../../runtime/obsidian/documents.mjs'
 import { readObsidianEnablement } from '../../../runtime/obsidian/enablement.mjs'
 import { ObsidianMaintenanceRefusal } from '../../../runtime/obsidian/errors.mjs'
 import { OPEN_EDIT_STATES, createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
-import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../contracts.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, manifestLayoutVersion } from '../contracts.mjs'
 import { SOURCE_APPLY_PRIMITIVES, SourceApplyRefusal, locateSource } from '../edits/apply.mjs'
 import { EditArbitrationRefusal } from '../edits/arbitrate.mjs'
 import { createEditObserverForOracleTests, editIdempotencyKey, observeEdit } from '../edits/observe.mjs'
@@ -131,17 +131,22 @@ export function createTickObservation(options = {}) {
     const kept = retained(store, noteEntry.noteDigest)
     if (kept) return kept
     workspace.prepared ??= new Map()
-    if (!workspace.prepared.has(scope.scopeId)) {
+    // Prepared in the vault layout of the edit's generation, once per generation.
+    const preparedKey = `${scope.scopeId}\u0000${manifest.generationId}`
+    if (!workspace.prepared.has(preparedKey)) {
       let files = []
       try {
         const { graph, profile } = workspace.corpus()
         const snapshot = seams.captureSnapshot({ project: workspace.project, graph, workspaceId: workspace.workspaceId, index: new Map(), configDigest: manifest.ext?.[EXT]?.configDigest ?? `sha256:${'0'.repeat(64)}`, capturedAt: now })
         const persistentPathRegistry = createMaintenanceStateStore({ workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId }).readPathRegistry()
-        files = seams.prepareView({ snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock, vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8') }).files
+        files = seams.prepareView({
+          snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock,
+          vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8'), layout: manifestLayoutVersion(manifest),
+        }).files
       } catch (error) { if (!isTyped(error) && !GONE.has(error?.code)) throw error }
-      workspace.prepared.set(scope.scopeId, files)
+      workspace.prepared.set(preparedKey, files)
     }
-    const file = workspace.prepared.get(scope.scopeId).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)
+    const file = workspace.prepared.get(preparedKey).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)
     return file ? file.bytes : null
   }
 

package/src/projection/obsidian/publication/bridge-script.mjs

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module'
+import { PLUGIN_OWNED_PATHS, POLICY_SETTINGS_PATHS } from '../materialize/settings.mjs'
 import { EXCHANGE_CONSTANTS } from './exchange.mjs'
 
 // The fixed script that performs one conditional publication. It runs in two
@@ -26,11 +27,14 @@ const KEYS = {
 const isAbsolute = (value) => typeof value === 'string' && value.startsWith('/') && !value.includes('\u0000')
 
 // A vault-relative path the publisher may address: visible files only, plus
-// the one policy-owned settings file. Every other settings path is the
-// person's and cannot be named in a payload at all.
+// the settings Atelier owns (the two policy settings files and its own
+// plugin's files). Every other settings path is the person's and cannot be
+// named in a payload at all.
+const ATELIER_OWNED_SETTINGS = new Set([...POLICY_SETTINGS_PATHS, ...PLUGIN_OWNED_PATHS])
+
 export function isAddressableVaultPath(value) {
   if (typeof value !== 'string' || value.length === 0 || value.length > 1024 || value.startsWith('/') || value.includes('\\') || value.includes('\u0000')) return false
-  if (value === POLICY_SETTINGS_PATH) return true
+  if (ATELIER_OWNED_SETTINGS.has(value)) return true
   return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..' && !part.startsWith('.'))
 }
 
@@ -43,7 +47,7 @@ export function validatePayload(payload) {
   for (const key of Object.keys(payload)) if (!allowed.includes(key)) fail(`unknown key ${key}`)
   for (const key of allowed) if (payload[key] === undefined) fail(`missing key ${key}`)
   if (!isAbsolute(payload.vaultRoot)) fail('vaultRoot must be absolute')
-  if (!isAddressableVaultPath(payload.path)) fail('path must be a relative visible path or the policy settings file')
+  if (!isAddressableVaultPath(payload.path)) fail('path must be a relative visible path or a settings file Atelier owns')
   if (payload.op === 'publish') {
     if (!OPERATION_ID.test(payload.operationId)) fail('operationId required')
     if (!SHA.test(payload.baseSha256)) fail('baseSha256 required')
@@ -76,7 +80,9 @@ export function criticalSection(P, host) {
   const trace = []
   const step = (event, detail) => trace.push({ ms: Number((host.performance.now() - t0).toFixed(3)), event, ...(detail || {}) })
   const crash = (point) => { if (host.crashSeam && host.crashSeam.at === point) host.crashSeam.halt(point) }
-  const real = (target) => { try { return fs.realpathSync(target) } catch (error) { return null } }
+  // As the file system stores the path, except on Windows (see realPathAsStored): an app that holds the vault under
+  // another spelling of its folder (a letter case, on a volume that folds it) holds this vault.
+  const real = (target) => { try { return host.process.platform !== 'win32' && fs.realpathSync.native ? fs.realpathSync.native(target) : fs.realpathSync(target) } catch (error) { return null } }
   const vaultBasePath = app ? real(app.vault.adapter.getBasePath()) : real(P.vaultRoot)
   const full = nodePath.join(P.vaultRoot, P.path)
   const views = () => {

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

@@ -1,5 +1,6 @@
 // Conditional publication of a prepared view into an editable Obsidian vault.
 export { PROTOCOL_ID, buildEvalCode, createInProcessHost, criticalSection, isAddressableVaultPath, runInProcess, validatePayload } from './bridge-script.mjs'
 export { EXCHANGE_CONSTANTS, ExchangeRefusal, exchangeFiles, probeExchange, resetExchangeProbeCache, resolveExchange } from './exchange.mjs'
-export { TransportTimeout, createDirectAdapter, createEditorAdapter, createInProcessCall, createObsidianCliAdapter, createObsidianCliCall, defaultCliPath, defaultObsidianProcessProbe } from './transport.mjs'
+export { NEUTRAL_DIRECTORY, TransportTimeout, createDirectAdapter, createEditorAdapter, createInProcessCall, createObsidianCliAdapter, createObsidianCliCall, defaultCliPath, defaultObsidianProcessProbe, publicationRoute } from './transport.mjs'
+export { MAX_OBSIDIAN_SETTINGS_BYTES, OBSIDIAN_SETTINGS_FILE, enclosingVaults, findVaultEntry, obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings, vaultRoute } from './vault-list.mjs'
 export { publishView } from './publisher.mjs'

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

@@ -3,8 +3,9 @@ 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'
@@ -36,14 +37,30 @@ 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.
 
 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 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 +78,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 (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)) refuse('invalid-prepared-view', 'a prepared file has an unknown kind')
+    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 +199,35 @@ 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 }
+}
+
+// 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.
+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)
+  })
+}
+
+// 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,17 +235,30 @@ 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
@@ -224,14 +295,15 @@ export async function publishView(options = {}) {
     acquire(store.vaultLockPath, () => acquireVaultLock(store), 'into this vault')
     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}`)
+    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'
     const channel = mode === 'in-app' ? adapter : createDirectAdapter({ crashSeam: seam })
 
@@ -247,7 +319,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)
@@ -259,7 +332,7 @@ export async function publishView(options = {}) {
       for (const unit of units.filter((item) => item.op === 'replace' || item.op === 'create')) {
         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 +343,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')
@@ -317,7 +390,12 @@ export async function publishView(options = {}) {
         results.push({ path: unit.path, kind: unit.kind, op: unit.op, outcome: context.uncoordinated ? 'editor-uncoordinated' : 'unchanged', blocking: false })
         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)
@@ -356,21 +434,72 @@ export async function publishView(options = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// 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 })
+  if (unit.op === 'leave-absent') return outcome('left-absent')
   const observe = (bytes) => store.retainObject(bytes)
   if (context.uncoordinated) return outcome('editor-uncoordinated', { blocking: unit.op !== 'keep' })
   // 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 +507,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') {
@@ -403,6 +533,14 @@ async function publishUnit(unit, context) {
     return outcome('already-current')
   }
 
+  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)
   // The journal state never goes backwards: once a note has been published the transition is `updating`.
@@ -552,18 +690,27 @@ 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 }
+  }
+  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 }