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

package/src/runtime/obsidian/plugin-channel.mjs

@@ -0,0 +1,281 @@
+import { createHash, randomBytes as cryptoRandomBytes, timingSafeEqual } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow, realPathAsStored } from '../../project/private-state.mjs'
+import {
+  PLUGIN_BEARER, PLUGIN_CHALLENGE_WINDOW_MS, PLUGIN_CHANNEL_PROTOCOL, PLUGIN_HANDSHAKE_TTL_MS, PLUGIN_LEASE_TTL_MS, PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE, PLUGIN_MAX_SESSION_AGE_MS, PLUGIN_MAX_SESSIONS_PER_SCOPE,
+  PLUGIN_RENEW_INTERVAL_MS, PLUGIN_STATUS_SCHEMA, pluginClientProof, pluginKeyHint, pluginRequestMac, pluginResponseMac, pluginServerProof, pluginSessionKey, pluginVaultProof,
+} from '../../projection/obsidian/plugin-bridge/channel.mjs'
+import { canonicalJson, compareText, isPlainObject, isoTime } from './documents.mjs'
+
+// The service's half of the plugin channel (plugin-bridge/channel.mjs).
+//
+//   bearers    one random bearer per view, minted when the view's vault first
+//              receives the plugin, kept owner-only under state/plugin/ and
+//              written into that vault's plugin data file, nowhere else; it
+//              is the key of the handshake and never crosses the wire
+//   sessions   who holds a view open right now: a plugin that proved it holds
+//              the vault's key and renews its lease; in memory, gone when the
+//              service stops
+//   commands   challenge, hello, lease, release and status, answered from
+//              state the service already keeps; nothing here writes a vault, a
+//              source, a manifest or an edit, and no command decides anything
+//
+// A live session also tells the app version the plugin runs in, and an id of
+// that launch of the plugin. That version counts as checked for app
+// qualification (app-capability.mjs) while one launch alone holds the view:
+// the plugin runs inside exactly that app.
+
+export const PLUGIN_BEARER_SCHEMA = 'atelier-obsidian-plugin-bearer/v1'
+export const PLUGIN_PRESENCE_SCHEMA = 'atelier-obsidian-plugin-presence/v1'
+const MAX_BEARER_FILES = 256
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export function pluginBearerDirectory(workspaceRoot) {
+  return path.join(workspaceRoot, 'state', 'plugin')
+}
+
+function readBearerFile(file, workspaceId) {
+  let document
+  try { document = JSON.parse(readRegularTextNoFollow(file)) } catch { return null }
+  if (!isPlainObject(document) || Object.keys(document).sort().join(',') !== 'bearer,createdAt,schema,scopeId,workspaceId') return null
+  if (document.schema !== PLUGIN_BEARER_SCHEMA || document.workspaceId !== workspaceId || typeof document.scopeId !== 'string' || !PLUGIN_BEARER.test(document.bearer ?? '')) return null
+  return document
+}
+
+// The bearer of one view's vault, minted on first use. A file that does not
+// read as this view's bearer is replaced: it cannot authenticate anything, and
+// the vault receives the new bearer with its next publication.
+export function ensurePluginBearer({ workspaceRoot, workspaceId, scopeId, randomBytes = cryptoRandomBytes, clock = () => new Date() }) {
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot, directory: pluginBearerDirectory(workspaceRoot), label: 'Obsidian plugin state' })
+  const file = path.join(directory, `${segment(scopeId)}.json`)
+  const existing = readBearerFile(file, workspaceId)
+  if (existing?.scopeId === scopeId) return existing.bearer
+  const bearer = randomBytes(32).toString('base64url')
+  atomicReplacePrivateText(file, canonicalJson({ schema: PLUGIN_BEARER_SCHEMA, workspaceId, scopeId, bearer, createdAt: isoTime(clock) }))
+  return bearer
+}
+
+// Every view's bearer this workspace has minted: scopeId -> bearer.
+export function readPluginBearers({ workspaceRoot, workspaceId }) {
+  const directory = pluginBearerDirectory(workspaceRoot)
+  let names
+  try { names = fs.readdirSync(directory) } catch (error) { if (error.code === 'ENOENT') return new Map(); throw error }
+  const bearers = new Map()
+  for (const name of names.filter((item) => item.endsWith('.json')).sort().slice(0, MAX_BEARER_FILES)) {
+    const document = readBearerFile(path.join(directory, name), workspaceId)
+    if (document !== null && name === `${segment(document.scopeId)}.json`) bearers.set(document.scopeId, document.bearer)
+  }
+  return bearers
+}
+
+// The bearers in memory. They are read again only when the directory changed
+// (a bearer minted, replaced, or deleted to rotate it), so a request costs a
+// stat and a listing of the directory, not a read of every file. The names
+// are part of what is compared: not every platform changes a directory's times
+// when an entry goes away. A bearer the service replaces under the same name
+// is announced with `invalidate()`.
+export function createPluginBearerCache({ workspaceRoot, workspaceId, read = readPluginBearers }) {
+  const directory = pluginBearerDirectory(workspaceRoot)
+  const signature = () => {
+    try {
+      const stat = fs.statSync(directory, { bigint: true })
+      return `${stat.ino}:${stat.mtimeNs}:${stat.ctimeNs}:${fs.readdirSync(directory).sort().join('/')}`
+    } catch (error) { if (error.code === 'ENOENT') return 'absent'; throw error }
+  }
+  let seen = null
+  let bearers = new Map()
+  return {
+    current() {
+      // Taken before the read: a change during the read is seen by the next call.
+      const now = signature()
+      if (now !== seen) { bearers = read({ workspaceRoot, workspaceId }); seen = now }
+      return bearers
+    },
+    invalidate() { seen = null },
+  }
+}
+
+// The decisions the channel's oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
+export const PLUGIN_CHANNEL_PRIMITIVES = Object.freeze({
+  // Two HMACs in hex of validated shape, compared in constant time.
+  macMatches: (presented, expected) => typeof presented === 'string' && presented.length === expected.length && timingSafeEqual(Buffer.from(presented, 'hex'), Buffer.from(expected, 'hex')),
+  counterIsNew: (counter, last) => counter > last,
+  handshakeUsedOnce: true,
+  // A challenge is answered only within this long of the time it names, and each of its nonces once.
+  challengeWindowMs: PLUGIN_CHALLENGE_WINDOW_MS,
+  noncesAnsweredOnce: true,
+})
+
+// Sessions of the plugin, per view. A session lives as long as its lease: a
+// hello grants one, each renewal extends it by `ttlMs`, and a release, a lapse
+// or `maxAgeMs` ends it. At most `maxPerScope` live sessions per view. A
+// session holds the key its handshake derived; nothing it hands out carries it.
+export function createPluginSessions({ now = () => Date.now(), ttlMs = PLUGIN_LEASE_TTL_MS, maxPerScope = PLUGIN_MAX_SESSIONS_PER_SCOPE, maxAgeMs = PLUGIN_MAX_SESSION_AGE_MS, randomBytes = cryptoRandomBytes } = {}) {
+  const sessions = new Map()
+  const prune = () => { const at = now(); for (const [sessionId, session] of sessions) if (session.expiresAt <= at || at - session.openedAt >= maxAgeMs) sessions.delete(sessionId) }
+  const liveFor = (scopeId) => { prune(); return [...sessions.values()].filter((session) => session.scopeId === scopeId) }
+  const shown = ({ sessionKey: _key, keyDigest: _digest, ...session }) => ({ ...session })
+  return {
+    open({ scopeId, pluginVersion, appVersion, instanceId, sessionKey, keyDigest }) {
+      if (liveFor(scopeId).length >= maxPerScope) return null
+      const at = now()
+      const session = { sessionId: `ps-${randomBytes(16).toString('hex')}`, scopeId, pluginVersion, appVersion, instanceId, sessionKey, keyDigest, counter: 0, openedAt: at, renewedAt: at, expiresAt: at + ttlMs }
+      sessions.set(session.sessionId, session)
+      return shown(session)
+    },
+    // The live session with this id, key included, for the channel only; null once it lapsed or was released.
+    held(sessionId) { prune(); return sessions.get(sessionId) ?? null },
+    renew(sessionId) {
+      const session = sessions.get(sessionId)
+      if (!session) return null
+      session.renewedAt = now()
+      session.expiresAt = session.renewedAt + ttlMs
+      return shown(session)
+    },
+    release: (sessionId) => sessions.delete(sessionId),
+    live: (scopeId) => liveFor(scopeId).map(shown),
+    // What the most recently renewed live session reports, or null when no plugin holds the view. `instances` counts
+    // the launches of the plugin behind the live sessions: more than one means more than one app holds the vault.
+    report(scopeId) {
+      const live = liveFor(scopeId).sort((left, right) => right.renewedAt - left.renewedAt)
+      if (live.length === 0) return null
+      const [newest] = live
+      return { scopeId, appVersion: newest.appVersion, pluginVersion: newest.pluginVersion, sessions: live.length, instances: new Set(live.map((session) => session.instanceId)).size, renewedAt: new Date(newest.renewedAt).toISOString() }
+    },
+    scopeIds() { prune(); return [...new Set([...sessions.values()].map((session) => session.scopeId))] },
+  }
+}
+
+// The commands of the plugin channel (plugin-bridge/channel.mjs). `statusOf(scopeId)`
+// returns the view's freshness entry as the service reports it and its open
+// pending edits; the vault a hello must prove is the view's vault under the
+// workspace state. `authority` is the exact address the request reached.
+export function createPluginChannelForOracleTests({
+  workspaceRoot, workspaceId, runtimeId, sessions, statusOf, serviceStatus, now = () => Date.now(), randomBytes = cryptoRandomBytes,
+  bearers = createPluginBearerCache({ workspaceRoot, workspaceId }),
+  // Told each time a plugin opened a session for a view: the app it runs in has the view's entry.
+  onSessionOpened = () => {},
+}, primitives = PLUGIN_CHANNEL_PRIMITIVES) {
+  const rules = { ...PLUGIN_CHANNEL_PRIMITIVES, ...primitives }
+  // As the file system stores the path, as the store registers the vault in the app (realPathAsStored): a data root given
+  // in another letter case names the same vault.
+  const vaultRootOf = (scopeId) => { try { return realPathAsStored(path.join(workspaceRoot, 'vaults', segment(scopeId))) } catch { return null } }
+  const keyDigestOf = (bearer) => createHash('sha256').update(bearer, 'utf8').digest()
+  const handshakes = new Map()
+  const pruneHandshakes = () => { const at = now(); for (const [handshakeId, handshake] of handshakes) if (handshake.expiresAt <= at) handshakes.delete(handshakeId) }
+  // The nonces of the challenges each view's key answered, until their time has left the window: a challenge recorded
+  // by whoever squatted the address, sent later, is answered at most once and only while it is fresh.
+  const answered = new Map()
+  const seenBefore = (scopeId, clientNonce, issuedAt) => {
+    const at = now()
+    const nonces = answered.get(scopeId) ?? new Map()
+    for (const [nonce, until] of nonces) if (until <= at) nonces.delete(nonce)
+    const seen = nonces.has(clientNonce)
+    if (rules.noncesAnsweredOnce) nonces.set(clientNonce, issuedAt + rules.challengeWindowMs + 1)
+    answered.set(scopeId, nonces)
+    return seen
+  }
+  const answer = (statusCode, body) => ({ statusCode, body })
+  // An answer only the session's key can have made: the exact text of the document, and a MAC over it.
+  const sealed = ({ sessionKey, command, sessionId, counter }, document) => {
+    const payload = JSON.stringify(document)
+    return answer(200, { payload, mac: pluginResponseMac({ sessionKey, command, sessionId, counter, payload }) })
+  }
+  // A request of a session: its MAC verifies under the session's key and its counter was never seen. A session
+  // whose vault's bearer was rotated since its handshake ends: its key came from the old bearer.
+  const authenticated = (command, body) => {
+    const session = sessions.held(body.sessionId)
+    if (session === null) return { refusal: answer(409, { error: 'session-unknown' }) }
+    if (!rules.macMatches(body.mac, pluginRequestMac({ sessionKey: session.sessionKey, command, sessionId: session.sessionId, counter: body.counter }))) return { refusal: answer(401, { error: 'request-not-authenticated' }) }
+    if (!rules.counterIsNew(body.counter, session.counter)) return { refusal: answer(401, { error: 'request-replayed' }) }
+    session.counter = body.counter
+    const bearer = bearers.current().get(session.scopeId)
+    if (typeof bearer !== 'string' || !timingSafeEqual(keyDigestOf(bearer), session.keyDigest)) {
+      sessions.release(session.sessionId)
+      return { refusal: answer(409, { error: 'session-unknown' }) }
+    }
+    return { session, seal: (document) => sealed({ sessionKey: session.sessionKey, command, sessionId: session.sessionId, counter: body.counter }, document) }
+  }
+  const commands = {
+    challenge({ body, authority }) {
+      if (Math.abs(now() - body.issuedAt) > rules.challengeWindowMs) return answer(401, { error: 'challenge-stale' })
+      // The key the hint was made with: every key is tried, all of them, whichever matches.
+      let found = null
+      for (const [scopeId, bearer] of bearers.current()) {
+        if (rules.macMatches(body.keyHint, pluginKeyHint({ bearer, clientNonce: body.clientNonce, issuedAt: body.issuedAt })) && found === null) found = { scopeId, bearer }
+      }
+      if (found === null) return answer(401, { error: 'plugin-key-unknown' })
+      if (seenBefore(found.scopeId, body.clientNonce, body.issuedAt)) return answer(401, { error: 'challenge-replayed' })
+      pruneHandshakes()
+      // Bounded per view: one view's waiting handshakes never hold up another's.
+      if ([...handshakes.values()].filter((handshake) => handshake.scopeId === found.scopeId).length >= PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE) return answer(429, { error: 'too-many-handshakes' })
+      const handshake = { handshakeId: `ph-${randomBytes(16).toString('hex')}`, scopeId: found.scopeId, authority, clientNonce: body.clientNonce, serverNonce: randomBytes(32).toString('hex'), expiresAt: now() + PLUGIN_HANDSHAKE_TTL_MS }
+      handshakes.set(handshake.handshakeId, handshake)
+      return answer(200, { protocol: PLUGIN_CHANNEL_PROTOCOL, handshakeId: handshake.handshakeId, serverNonce: handshake.serverNonce, serverProof: pluginServerProof({ bearer: found.bearer, ...handshake }) })
+    },
+    hello({ body, authority }) {
+      pruneHandshakes()
+      const handshake = handshakes.get(body.handshakeId) ?? null
+      if (rules.handshakeUsedOnce) handshakes.delete(body.handshakeId)
+      const bearer = handshake === null ? undefined : bearers.current().get(handshake.scopeId)
+      if (handshake === null || handshake.authority !== authority || typeof bearer !== 'string') return answer(401, { error: 'handshake-unknown' })
+      const { scopeId } = handshake
+      const bound = { bearer, scopeId, authority, clientNonce: handshake.clientNonce, serverNonce: handshake.serverNonce, handshakeId: handshake.handshakeId }
+      const expected = pluginClientProof({ ...bound, pluginVersion: body.pluginVersion, appVersion: body.appVersion, instanceId: body.instanceId, vaultProof: body.vaultProof })
+      if (!rules.macMatches(body.clientProof, expected)) return answer(401, { error: 'plugin-not-authenticated' })
+      const sessionKey = pluginSessionKey(bound)
+      // Compared, never named: the vault the app has open, proven under this session's key.
+      const vaultRoot = vaultRootOf(scopeId)
+      if (vaultRoot === null || !rules.macMatches(body.vaultProof, pluginVaultProof({ sessionKey, vaultPath: vaultRoot }))) return answer(409, { error: 'wrong-vault' })
+      const session = sessions.open({ scopeId, pluginVersion: body.pluginVersion, appVersion: body.appVersion, instanceId: body.instanceId, sessionKey, keyDigest: keyDigestOf(bearer) })
+      if (session === null) return answer(429, { error: 'too-many-sessions' })
+      onSessionOpened(scopeId)
+      return sealed({ sessionKey, command: 'hello', sessionId: session.sessionId, counter: 0 }, {
+        schema: PLUGIN_CHANNEL_PROTOCOL, scopeId, sessionId: session.sessionId, runtimeId, leaseTtlMs: session.expiresAt - session.openedAt, renewEveryMs: PLUGIN_RENEW_INTERVAL_MS,
+      })
+    },
+    lease({ body }) {
+      const request = authenticated('lease', body)
+      if (request.refusal) return request.refusal
+      const session = sessions.renew(request.session.sessionId)
+      return request.seal({ schema: PLUGIN_CHANNEL_PROTOCOL, scopeId: session.scopeId, sessionId: session.sessionId, leaseTtlMs: session.expiresAt - session.renewedAt })
+    },
+    release({ body }) {
+      const request = authenticated('release', body)
+      if (request.refusal) return request.refusal
+      return request.seal({ schema: PLUGIN_CHANNEL_PROTOCOL, scopeId: request.session.scopeId, released: sessions.release(request.session.sessionId) })
+    },
+    status({ body }) {
+      const request = authenticated('status', body)
+      if (request.refusal) return request.refusal
+      const { scopeId } = request.session
+      const { view, pendingEdits } = statusOf(scopeId)
+      return request.seal({ schema: PLUGIN_STATUS_SCHEMA, scopeId, service: { status: serviceStatus() }, view, pendingEdits })
+    },
+  }
+  return {
+    bearers: () => bearers.current(),
+    // The service minted a bearer: whatever the directory's times say, the next lookup reads the bearers again.
+    bearersChanged: () => bearers.invalidate?.(),
+    handle: (command, request) => commands[command](request),
+  }
+}
+
+export function createPluginChannel(options) {
+  return createPluginChannelForOracleTests(options, PLUGIN_CHANNEL_PRIMITIVES)
+}
+
+// Which views a plugin holds open, for the service's status document, and
+// whether the person wants the plugin in each vault (`entry`: undecided,
+// requested, on or off; see plugin-choice.mjs). Counts, versions and states
+// only: no vault path, no session identity.
+export function pluginPresence({ sessions, scopeIds, entryOf = () => null }) {
+  const scopes = [...new Set([...scopeIds, ...sessions.scopeIds()])].sort(compareText).map((scopeId) => {
+    const report = sessions.report(scopeId)
+    const entry = entryOf(scopeId)
+    const presence = report === null ? { scopeId, present: false, sessions: 0 } : { scopeId, present: true, sessions: report.sessions, appVersion: report.appVersion, pluginVersion: report.pluginVersion, renewedAt: report.renewedAt }
+    return entry === null ? presence : { ...presence, entry }
+  })
+  return { schema: PLUGIN_PRESENCE_SCHEMA, leaseTtlMs: PLUGIN_LEASE_TTL_MS, scopes }
+}

package/src/runtime/obsidian/plugin-choice.mjs

@@ -0,0 +1,170 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { PLUGIN_ID } from '../../projection/obsidian/plugin-bridge/channel.mjs'
+import { COMMUNITY_PLUGINS_PATH } from '../../projection/obsidian/materialize/settings.mjs'
+import { sha256Digest } from '../../projection/obsidian/materialize/byte-lens.mjs'
+import { canonicalJson, isPlainObject, isoTime } from './documents.mjs'
+
+// Whether the person wants Atelier's plugin in one vault, as the vault itself
+// says it: the `atelier-projection` entry of .obsidian/community-plugins.json.
+//
+//   (no record)   nothing decided yet: Atelier offers the entry and the files
+//   requested     `atelier obsidian plugin on` asked for it: offered again
+//   offered       the entry is in place, but it was written while an app held
+//                 the vault; that app keeps the list it read in memory and may
+//                 write it back without the entry, so a list without it is no
+//                 decision of the person's yet: the entry is offered again
+//   on            the app has the entry: it was in place before an app next
+//                 opened the vault (published while none ran), or the plugin
+//                 ran in the app; from now on a list without it is the
+//                 person's decision
+//   off           the person removed the entry (turned the plugin off, or
+//                 uninstalled it, in Obsidian): Atelier never adds it back and
+//                 never creates a plugin file that is not there; it only keeps
+//                 the files that are present current
+//
+// The decision is read before a view is prepared, from the bytes of the file
+// on disk, and those bytes travel with the prepared view: the publisher writes
+// the entry only over exactly those bytes, so a change the person makes while
+// a publication runs is never written over, and the next preparation reads it.
+// A file that is absent or is not a list decides nothing. A record that cannot
+// be read counts as `off`: nothing is re-added on a guess. Status reads the
+// same change without recording it (currentPluginChoice), so it says what the
+// person did before the view's next preparation records it.
+
+export const PLUGIN_CHOICE_SCHEMA = 'atelier-obsidian-plugin-choice/v1'
+export const PLUGIN_CHOICE_STATES = Object.freeze(['requested', 'offered', 'on', 'off'])
+const REASONS = Object.freeze(['requested-by-command', 'entry-offered-while-the-app-runs', 'entry-confirmed', 'entry-seen-by-the-app', 'entry-removed-by-person', 'entry-restored-by-person'])
+// The states in which a list without the entry is not the person's decision: the entry is offered again.
+const NOT_YET_CONFIRMED = Object.freeze(['undecided', 'requested', 'offered'])
+const MAX_SETTINGS_BYTES = 256 * 1024
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export const pluginChoiceDirectory = (workspaceRoot) => path.join(workspaceRoot, 'state', 'plugin', 'choices')
+// Where the recovery store places a view's vault.
+export const viewVaultRoot = (workspaceRoot, scopeId) => path.join(workspaceRoot, 'vaults', segment(scopeId))
+const choiceFile = (workspaceRoot, scopeId) => path.join(pluginChoiceDirectory(workspaceRoot), `${segment(scopeId)}.json`)
+
+function validChoice(document, { workspaceId, scopeId }) {
+  return isPlainObject(document) && Object.keys(document).sort().join(',') === 'reason,schema,scopeId,since,state,workspaceId'
+    && document.schema === PLUGIN_CHOICE_SCHEMA && document.workspaceId === workspaceId && document.scopeId === scopeId
+    && PLUGIN_CHOICE_STATES.includes(document.state) && REASONS.includes(document.reason) && typeof document.since === 'string'
+}
+
+// { state: 'undecided' | 'requested' | 'offered' | 'on' | 'off', reason, since, unreadable? }
+export function readPluginChoice({ workspaceRoot, workspaceId, scopeId }) {
+  let text
+  try { text = readRegularTextNoFollow(choiceFile(workspaceRoot, scopeId)) } catch (error) {
+    if (error.code === 'ENOENT') return { state: 'undecided', reason: null, since: null }
+    return { state: 'off', reason: 'choice-unreadable', since: null, unreadable: true }
+  }
+  let document = null
+  try { document = JSON.parse(text) } catch { document = null }
+  if (!validChoice(document, { workspaceId, scopeId })) return { state: 'off', reason: 'choice-unreadable', since: null, unreadable: true }
+  return { state: document.state, reason: document.reason, since: document.since }
+}
+
+export function writePluginChoice({ workspaceRoot, workspaceId, scopeId, state, reason, clock = () => new Date() }) {
+  const document = { schema: PLUGIN_CHOICE_SCHEMA, workspaceId, scopeId, state, reason, since: isoTime(clock) }
+  if (!validChoice(document, { workspaceId, scopeId })) throw new TypeError('a plugin choice names a known state and reason')
+  ensureContainedPrivateDirectory({ workspaceRoot, directory: pluginChoiceDirectory(workspaceRoot), label: 'Obsidian plugin state' })
+  atomicReplacePrivateText(choiceFile(workspaceRoot, scopeId), canonicalJson(document))
+  return { state, reason, since: document.since }
+}
+
+// 'absent', 'unreadable' (a parent is a link or not a directory) or 'reachable'.
+function parentsOf(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) return 'absent'
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return 'unreadable'
+  }
+  return 'reachable'
+}
+
+// Whether a vault path holds a regular file under real directories.
+export function vaultFilePresent(vaultRoot, relativePath) {
+  return parentsOf(vaultRoot, relativePath) === 'reachable' && fs.lstatSync(path.join(vaultRoot, relativePath), { throwIfNoEntry: false })?.isFile() === true
+}
+
+// The bytes of a settings file of a vault, read without following a link and
+// bounded: { state: 'absent' | 'present' | 'unreadable', bytes, digest }.
+export function readVaultSettingsFile(vaultRoot, relativePath) {
+  const parents = parentsOf(vaultRoot, relativePath)
+  if (parents !== 'reachable') return { state: parents, bytes: null, digest: null }
+  let descriptor
+  try { descriptor = openRegularFileNoFollow(path.join(vaultRoot, relativePath)) } catch (error) {
+    return error.code === 'ENOENT' ? { state: 'absent', bytes: null, digest: null } : { state: 'unreadable', bytes: null, digest: null }
+  }
+  try {
+    if (fs.fstatSync(descriptor).size > MAX_SETTINGS_BYTES) return { state: 'unreadable', bytes: null, digest: null }
+    const bytes = fs.readFileSync(descriptor)
+    return { state: 'present', bytes, digest: sha256Digest(bytes) }
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}
+
+// What the vault's community plugin list says about Atelier's entry:
+// 'listed', 'not-listed' (a list without it), or 'no-list' (absent, unreadable
+// or not a list), with the bytes read.
+export function readCommunityEntry(vaultRoot) {
+  const file = readVaultSettingsFile(vaultRoot, COMMUNITY_PLUGINS_PATH)
+  if (file.state !== 'present') return { entry: 'no-list', file }
+  let list = null
+  try { list = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(file.bytes)) } catch { list = null }
+  if (!Array.isArray(list)) return { entry: 'no-list', file }
+  return { entry: list.includes(PLUGIN_ID) ? 'listed' : 'not-listed', file }
+}
+
+// A change of the decision the vault shows against the record, or null: an
+// entry removed after it was confirmed is the person turning the plugin off; an
+// entry the person put back turns it on again.
+function changeShown(choice, entry) {
+  if (choice.state === 'on' && entry === 'not-listed') return { state: 'off', reason: 'entry-removed-by-person' }
+  if (choice.state === 'off' && !choice.unreadable && entry === 'listed') return { state: 'on', reason: 'entry-restored-by-person' }
+  return null
+}
+
+// The decision for one view, from its record and what its vault says now, as
+// the view is prepared: a change is recorded here.
+export function decidePluginChoice({ workspaceRoot, workspaceId, scopeId, vaultRoot, clock }) {
+  const recorded = readPluginChoice({ workspaceRoot, workspaceId, scopeId })
+  const community = readCommunityEntry(vaultRoot)
+  const change = changeShown(recorded, community.entry)
+  return { choice: change === null ? recorded : writePluginChoice({ workspaceRoot, workspaceId, scopeId, ...change, clock }), community }
+}
+
+// The same decision for status, read only: a change not recorded yet is marked
+// `pending` (the view's next preparation records it).
+export function currentPluginChoice({ workspaceRoot, workspaceId, scopeId }) {
+  const recorded = readPluginChoice({ workspaceRoot, workspaceId, scopeId })
+  const change = changeShown(recorded, readCommunityEntry(viewVaultRoot(workspaceRoot, scopeId)).entry)
+  return change === null ? recorded : { ...change, since: null, pending: true }
+}
+
+// After a publication: an offered entry that is now in place. Published while
+// no app ran, it is confirmed: an app reads the list, entry and all, when it
+// next opens the vault. Published through a running app, it is only offered:
+// that app may not have read it, and the plugin running there confirms it
+// (confirmPluginSeen).
+const IN_PLACE = new Set(['policy-satisfied', 'created', 'published', 'published-external-captured', 'already-current'])
+export function confirmPluginEntry({ workspaceRoot, workspaceId, scopeId, result, clock }) {
+  const unit = (result?.notes ?? []).find((entry) => entry.path === COMMUNITY_PLUGINS_PATH)
+  if (!unit || !IN_PLACE.has(unit.outcome) || unit.changedAfterPublication === true) return null
+  const choice = readPluginChoice({ workspaceRoot, workspaceId, scopeId })
+  if (!NOT_YET_CONFIRMED.includes(choice.state)) return null
+  if (result.mode === 'direct') return writePluginChoice({ workspaceRoot, workspaceId, scopeId, state: 'on', reason: 'entry-confirmed', clock })
+  if (choice.state === 'offered') return null
+  return writePluginChoice({ workspaceRoot, workspaceId, scopeId, state: 'offered', reason: 'entry-offered-while-the-app-runs', clock })
+}
+
+// The plugin said hello from the vault: the app it runs in has the entry, so it is confirmed.
+export function confirmPluginSeen({ workspaceRoot, workspaceId, scopeId, clock }) {
+  const choice = readPluginChoice({ workspaceRoot, workspaceId, scopeId })
+  if (!NOT_YET_CONFIRMED.includes(choice.state)) return null
+  return writePluginChoice({ workspaceRoot, workspaceId, scopeId, state: 'on', reason: 'entry-seen-by-the-app', clock })
+}

package/src/runtime/obsidian/plugin-drift.mjs

@@ -0,0 +1,76 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { OBSIDIAN_EXT_KEY } from '../../projection/obsidian/contracts.mjs'
+import { sha256Digest } from '../../projection/obsidian/materialize/byte-lens.mjs'
+import { readFileBytes, readFileDigest } from '../../projection/obsidian/recovery/store.mjs'
+import { viewVaultRoot } from './plugin-choice.mjs'
+
+// Whether the plugin files a view's committed generation pins are on disk as
+// pinned. A person may remove one, change one, or repair a path Atelier had to
+// leave (a folder where a file goes, say). The publisher then publishes the
+// same generation again (publisher.mjs), but only when the view is prepared
+// again, which nothing else asks for while its sources are unchanged.
+//
+// `observe(scopeIds)` looks at each view once per tick and returns the views
+// to prepare again: those whose files differ from their pins and look
+// different from the last look. A drift Atelier leaves for the person (a link
+// where a file goes) is asked about once, not at every tick; a change to it is
+// asked about again. Where the plugin is turned off in the vault, a pinned
+// file that is gone is no drift: the publisher never makes one again.
+
+const segment = (identifier) => identifier.replaceAll(':', '_')
+const TURNED_OFF = 'turned-off-in-this-vault'
+
+// The plugin record of the view's committed manifest, read as the store reads
+// it: the pointer names the manifest and its digest. Null when there is none.
+function pinnedPlugin(workspaceRoot, workspaceId, scopeId) {
+  const manifests = path.join(workspaceRoot, 'state', 'manifests', segment(scopeId))
+  try {
+    const pointer = JSON.parse(readRegularTextNoFollow(path.join(manifests, 'current.json')))
+    if (pointer?.workspaceId !== workspaceId || pointer?.scopeId !== scopeId || typeof pointer.manifestFile !== 'string' || pointer.manifestFile.includes('/')) return null
+    const bytes = readFileBytes(path.join(manifests, pointer.manifestFile))
+    if (sha256Digest(bytes) !== pointer.manifestDigest) return null
+    const owned = JSON.parse(bytes.toString('utf8'))?.ext?.[OBSIDIAN_EXT_KEY]?.settings?.pluginOwned
+    if (!Array.isArray(owned?.files)) return null
+    return { files: owned.files.filter((file) => typeof file?.path === 'string' && typeof file?.digest === 'string'), off: owned.withheldBecause === TURNED_OFF }
+  } catch {
+    return null
+  }
+}
+
+// What one pinned path holds: its digest, 'absent', or 'unreadable' (a link, a
+// folder where a file goes, a path nobody may read).
+function onDisk(vaultRoot, relativePath) {
+  let current = vaultRoot
+  for (const part of relativePath.split('/').slice(0, -1)) {
+    current = path.join(current, part)
+    let stat
+    try { stat = fs.lstatSync(current, { throwIfNoEntry: false }) } catch { return 'unreadable' }
+    if (!stat) return 'absent'
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return 'unreadable'
+  }
+  try { return readFileDigest(path.join(vaultRoot, relativePath)) ?? 'absent' } catch { return 'unreadable' }
+}
+
+export function createPluginDriftObserver({ workspaceRoot, workspaceId }) {
+  const looked = new Map()
+  return {
+    observe(scopeIds) {
+      const drifted = []
+      for (const scopeId of scopeIds) {
+        const pinned = pinnedPlugin(workspaceRoot, workspaceId, scopeId)
+        if (pinned === null || pinned.files.length === 0) { looked.delete(scopeId); continue }
+        const vaultRoot = viewVaultRoot(workspaceRoot, scopeId)
+        let root = 'absent'
+        try { const stat = fs.lstatSync(vaultRoot); root = stat.isSymbolicLink() ? 'link' : (stat.mode & 0o777).toString(8) } catch { root = 'absent' }
+        const disk = pinned.files.map((file) => onDisk(vaultRoot, file.path))
+        const differs = disk.some((found, index) => found !== pinned.files[index].digest && !(pinned.off && found === 'absent'))
+        const signature = JSON.stringify([root, pinned.files.map((file) => file.digest), disk])
+        if (differs && looked.get(scopeId) !== signature) drifted.push(scopeId)
+        looked.set(scopeId, signature)
+      }
+      return drifted
+    },
+  }
+}

package/src/runtime/obsidian/plugin-presence.mjs

@@ -0,0 +1,48 @@
+import { isPlainObject } from './documents.mjs'
+
+// What `status` and `open` say about Atelier's plugin, read from the status
+// document of the running service (`plugins`, see plugin-channel.mjs). The
+// plugin is present for a view while it holds a live lease on it.
+
+export const PLUGIN_PRESENCE_REASONS = Object.freeze(['live-lease', 'no-live-lease', 'turned-off-in-this-vault', 'service-not-running', 'service-reports-no-plugin-channel'])
+
+// The two ways back, for a view whose vault turned the plugin off.
+export const turnPluginOnNext = (scopeId) => `turn Atelier on in Obsidian (Settings, Community plugins), or run \`atelier obsidian plugin on --scope ${scopeId}\`, which restores it at the view's next publication`
+
+export function pluginPresenceOf(statusDocument, scopeId) {
+  if (!isPlainObject(statusDocument)) return { present: false, reason: 'service-not-running' }
+  const scopes = isPlainObject(statusDocument.plugins) && Array.isArray(statusDocument.plugins.scopes) ? statusDocument.plugins.scopes : null
+  if (scopes === null) return { present: false, reason: 'service-reports-no-plugin-channel' }
+  const entry = scopes.find((item) => isPlainObject(item) && item.scopeId === scopeId)
+  if (entry?.present === true && typeof entry.appVersion === 'string') {
+    return { present: true, reason: 'live-lease', appVersion: entry.appVersion, pluginVersion: typeof entry.pluginVersion === 'string' ? entry.pluginVersion : null, sessions: Number.isInteger(entry.sessions) ? entry.sessions : 1 }
+  }
+  if (entry?.entry === 'off') return { present: false, reason: 'turned-off-in-this-vault', next: turnPluginOnNext(scopeId) }
+  return { present: false, reason: 'no-live-lease' }
+}
+
+// An app probe that takes the version from the plugin when one holds the view
+// and the command-line tool gives none: that plugin runs inside the app, so its
+// version is the app's. A version the tool did give decides, since the tool may
+// reach another app that holds the same vault. Whether the app is installed and
+// has its command-line capability is still the probe's answer; that capability
+// opens and coordinates the vault in this phase. So is whether the app runs: a
+// lease outlives a crashed app by up to its lease time.
+// The presence is asked at most once per `maxAgeMs`: open's wait loop asks the
+// app far more often, and each answer about the plugin costs a round trip to
+// the service.
+export function withPluginReportedVersion(appProbe, readPresence, { maxAgeMs = 1000, now = () => Date.now() } = {}) {
+  let last = null
+  const presenceNow = () => {
+    if (last === null || now() - last.at >= maxAgeMs) last = { at: now(), presence: Promise.resolve().then(readPresence).catch(() => null) }
+    return last.presence
+  }
+  return {
+    async inspect() {
+      const [observation, presence] = await Promise.all([appProbe.inspect(), presenceNow()])
+      if (presence?.present !== true || observation?.installed !== true || observation?.cli !== true || observation.running === false || typeof observation.version === 'string') return observation
+      return { ...observation, running: true, version: presence.appVersion, noVaultOpen: false, versionSource: 'plugin' }
+    },
+    vaultState: (input) => appProbe.vaultState(input),
+  }
+}

package/src/runtime/obsidian/service-main.mjs

@@ -23,15 +23,27 @@ import { runMaintenanceService } from './service.mjs'
 // selected them. The editor adapter is constructed only for an app that meets
 // the minimum version; below it, or when the version cannot be read, the
 // factory refuses, the engine records that reason and nothing is published.
-// An adapter qualified while no app ran carries that qualification and does
-// not coordinate with an app that starts before the next qualification.
+// The app is asked for its version only when a view is published, without
+// blocking the service. An adapter qualified while no app ran carries that
+// qualification and does not coordinate with an app that starts before the
+// next qualification. The engine is told what the app looks like from the
+// process table and the app's vault list alone (whether it runs, which vaults
+// its list shows open), so a view that did not settle is tried again as soon
+// as that changes, and the app is not asked anything to find out; the list is
+// only read here.
 const ADAPTERS = Object.freeze({
   'obsidian-cli': async () => {
-    const [{ createObsidianCliAdapter }, { createProductionAppProbe }, { createQualifiedAdapterFactory }] = await Promise.all([
+    const [{ createObsidianCliAdapter, defaultObsidianProcessProbe }, { createProductionAppProbe }, { createQualifiedAdapterFactory }, { obsidianUserDataDir, readObsidianSettings }, { appStateSignature }] = await Promise.all([
       import('../../projection/obsidian/publication/transport.mjs'), import('./app-production-seams.mjs'), import('./app-capability.mjs'),
+      import('../../projection/obsidian/publication/vault-list.mjs'), import('./app-registration.mjs'),
     ])
     const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: ({ qualification }) => createObsidianCliAdapter({ qualification }) })
-    return { adapterFactory, appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } } }
+    const userDataDir = obsidianUserDataDir()
+    const observeApp = () => appStateSignature({ processes: defaultObsidianProcessProbe(), settings: userDataDir === null ? null : readObsidianSettings({ userDataDir }) })
+    return {
+      adapterFactory, engineOptions: { observeApp },
+      appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } },
+    }
   },
 })
 
@@ -88,6 +100,7 @@ if (invokedDirectly) {
     const { adapter, ...rest } = options
     const [{ loadContributions }, { createObsidianRegistry }] = await Promise.all([import('./contributions.mjs'), import('./extension-points.mjs')])
     const registry = createObsidianRegistry({ contributions: await loadContributions() })
-    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...(await ADAPTERS[adapter]()), engineOptions: { extensions: registry.extensions } })
+    const { engineOptions, ...seams } = await ADAPTERS[adapter]()
+    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...seams, engineOptions: { ...engineOptions, extensions: registry.extensions } })
   }
 }