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

package/src/runtime/obsidian/pending-edits.mjs

@@ -91,6 +91,16 @@ export function heldPaths(edits, scopeId) {
   return [...new Set(edits.filter((edit) => edit.scopeId === scopeId && isOpenEdit(edit)).map((edit) => edit.path))].sort(compareText)
 }
 
+// The notes a view must keep in the vault layout they were published in: those
+// held for an open edit, and those whose edit closed on this tick (automatic
+// mode applies and closes an edit on the tick it observes it). The view is
+// prepared in that layout once more, so the file the person edited becomes the
+// published note, and a later tick lays the view out again and retires it.
+export function layoutHeldPaths(edits, scopeId, now) {
+  const closedNow = edits.filter((edit) => edit.scopeId === scopeId && edit.closedAt !== null && edit.closedAt === now)
+  return [...new Set([...heldPaths(edits, scopeId), ...closedNow.map((edit) => edit.path)])].sort(compareText)
+}
+
 // Automatic dispatch. `authorize()` reads the machine settings and the policy
 // from disk. It is called before the batch and again immediately before each
 // edit, so a revocation, a pause or a switch back to manual stops the very

package/src/runtime/obsidian/pipeline.mjs

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto'
 import path from 'node:path'
 import { buildCanonicalGraph, createGraphFileCache } from '../../graph/graph.mjs'
-import { EMITTER_VERSION, createPreparationCache, prepareView, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { markdownMetadata } from '../../graph/knowledge-graph.mjs'
+import { EMITTER_VERSION, createPreparationCache, prepareView, readMarkdownLens, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { personalWorkspaceGraph } from '../../projection/obsidian/personal-workspace.mjs'
 import { publishView } from '../../projection/obsidian/publication/publisher.mjs'
 import { recheckDisplacedFiles } from '../../projection/obsidian/recovery/late-writer.mjs'
 import { createRecoveryStore, readFileBytes } from '../../projection/obsidian/recovery/store.mjs'
@@ -31,6 +33,68 @@ export const DEFAULT_ELIGIBILITY = Object.freeze({
   isEligible: (node) => node.classification === 'classified',
 })
 
+// A vault that is the person's own also shows the notes that carry no classification, when they decided so: the
+// audience decision `only-you` with `unclassified: 'shown'`, which no other audience decision may carry. Those notes
+// are the person's own files, in a vault only they see. One is admitted only when its bytes read as a note (the byte
+// lens the emitter reads it with), so a file the emitter would refuse never stops the vault: it stays withheld, as does
+// one that cannot be read. A note whose labels are unknown is never admitted: front matter Atelier could not read
+// (`malformed-frontmatter`: a block scalar, a wrapped value), or any top-level `kg` key that is not a
+// block, may carry an audience such as `sensitive` that "only you" leaves out. Only a note with no front matter, or
+// front matter of plain top-level keys at column 0 none of which is `kg` (plainTopLevelKeys) and in which the graph
+// reads no `kg` either, is the person's plain note. Assets follow the documents that
+// embed them, as always.
+export function onlyYouEligibility({ project }) {
+  const roots = new Map((project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => [repo.name, repo.path]))
+  const readsAsNote = (node) => {
+    const root = roots.get(node.repo)
+    if (root === undefined || node.extension !== 'md' || typeof node.path !== 'string') return false
+    let bytes
+    let lens
+    try { bytes = readFileBytes(path.join(root, ...node.path.split('/'))); lens = readMarkdownLens(bytes) } catch { return false }
+    // Read now, not as the graph saw it: a file that gained front matter since is judged by what it holds now.
+    if (lens.frontmatter === null) return node.classificationReason === 'absent-frontmatter'
+    if (node.classificationReason !== 'missing-kg-block') return false
+    const text = bytes.toString('utf8')
+    const block = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+    if (block === null || !plainTopLevelKeys(block[1])) return false
+    // A second layer: the graph's own reading of the front matter has no kg key either.
+    try { return !('kg' in markdownMetadata(text)) } catch { return false }
+  }
+  return Object.freeze({
+    revision: () => 'classified-documents/v2+unclassified-notes-read-as-notes-for-only-you/v4+assets-embedded-by-eligible-documents/v1',
+    isEligible: (node) => node.classification === 'classified' || (node.classification === 'unclassified' && readsAsNote(node)),
+  })
+}
+
+// Whether front matter is plain `key: value` lines at its top level, none of them `kg`: every line that is not blank,
+// a comment, or indented (a nested value or a continuation) starts with a bare key. A quoted key, a flow or JSON
+// mapping, a complex key (`? `), a top-level list or anything else unusual is not plain, so a label it may hold (a
+// `kg.audience: sensitive` Atelier did not read) keeps the note withheld. An allow-list, never a pattern to find.
+const PLAIN_KEY = /^([A-Za-z_][A-Za-z0-9_-]*)[ \t]*:(?:[ \t]|$)/
+function plainTopLevelKeys(frontmatter) {
+  // Line breaks YAML 1.1 readers honour and this reading does not (NEL, LS, PS) could hide a kg from it.
+  if (/[\u0085\u2028\u2029]/.test(frontmatter)) return false
+  let rooted = false
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    // An indented line is a nested value or a continuation only below a key at column 0; YAML also lets a whole root
+    // mapping be indented, and then its keys (kg among them) are indented too.
+    if (/^[ \t]/.test(line)) { if (!rooted) return false; continue }
+    const key = PLAIN_KEY.exec(line)
+    if (key === null || key[1] === 'kg') return false
+    rooted = true
+  }
+  return true
+}
+
+// The eligibility a workspace's machine settings decide: the one above only for "only you" with unclassified notes
+// shown, and the default, which withholds them, for every other decision and for none.
+export function eligibilityFor({ machine, project }) {
+  const audience = machine?.decisions?.audience
+  return audience?.choice === 'only-you' && audience.unclassified === 'shown' ? onlyYouEligibility({ project }) : DEFAULT_ELIGIBILITY
+}
+
 export function assetEligibilityFor({ graph, eligibility }) {
   const eligibleSources = new Set(graph.nodes.filter((node) => eligibility.isEligible(node) === true).map((node) => node.id))
   const embeds = Array.isArray(graph.embeds) ? graph.embeds : []
@@ -59,9 +123,13 @@ export function profileFor({ project, workspaceId, audienceAllow }) {
 // `index` is the engine's observation index. With both, a source whose observed digest is the cached one is not
 // opened: observation already decided by digest that it did not change, under the stat-hint bound observation
 // documents, and a full reconciliation hashes it again. Without an index every source is read and hashed here.
-export function buildGraph({ project, eligibility, cache = null, index = null }) {
+// A project bound to a personal workspace (personal-workspace.mjs) is built by that route, for every caller, with the
+// same caches: the composition's graph, served only under a validity key the composition confirmed. With
+// `deferPersonalValidation` (the engine), an unconfirmed key refuses `personal-validation-pending` instead of composing
+// on this thread.
+export function buildGraph({ project, eligibility, cache = null, index = null, deferPersonalValidation = false }) {
   const observedDigest = cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null
-  const canonical = buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+  const canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation }) ?? buildCanonicalGraph(project, { fileCache: cache, observedDigest })
   if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
   return withEligibility(canonical, eligibility.isEligible, assetEligibilityFor({ graph: canonical, eligibility }))
 }

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

@@ -0,0 +1,289 @@
+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 { assertAllocatedFolder, vaultRootFor } from '../../projection/obsidian/recovery/store.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 }
+  // The view's vault wherever it is (vaultRootFor: allocated for the view, else under the data root), and an allocated one
+  // only while it is the folder recorded; 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 {
+      const found = vaultRootFor({ workspaceRoot, workspaceId, scopeId })
+      if (found.allocation !== null) assertAllocatedFolder(found.allocation)
+      return realPathAsStored(found.path)
+    } 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,182 @@
+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 { vaultRootFor } from '../../projection/obsidian/recovery/store.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 a view's vault is, as the recovery store finds it (vaultRootFor): the folder allocated to the view where the
+// workspace decided its vaults live, else its folder under the data root. A record that cannot be read, or was lost,
+// refuses, typed. Pass `workspaceId`; every caller here does. The two-argument form of earlier releases still works:
+// it takes the name of the workspace's private-state folder as the id, which a record of another workspace (or a
+// folder reached through a link) does not match, and such a record refuses, typed, rather than answering another vault.
+export function viewVaultRoot(workspaceRoot, scopeId, workspaceId = path.basename(String(workspaceRoot))) {
+  return vaultRootFor({ workspaceRoot, workspaceId, scopeId }).path
+}
+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 })
+  // A view whose vault cannot be found (its record cannot be read) shows what was recorded; its view says why.
+  let vaultRoot
+  try { vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId) } catch (error) { if (typeof error?.code !== 'string') throw error; return recorded }
+  const change = changeShown(recorded, readCommunityEntry(vaultRoot).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). So is one published into a vault no Obsidian listed
+// while one ran (`direct-unheld`): the evidence covers only the lists Atelier
+// can read, not another profile's or another machine's.
+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 })
+}