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

package/src/runtime/obsidian/startup-adapters.mjs

@@ -4,9 +4,8 @@ import { refuse } from './errors.mjs'
 // Builds the text of an operating-system startup unit for the maintenance
 // service. Pure: it returns text and touches nothing. It writes no file,
 // installs nothing and runs no service manager. Installing a unit is a
-// separate system change that needs a person's explicit authorization and a
-// recorded consent that covers startup; the service refuses `--startup`
-// without one.
+// separate step (login-item.mjs) that a person asks for, and the service
+// refuses `--startup` without a recorded consent that covers startup.
 //
 // Every machine-specific value is an input. Nothing is looked up here: no
 // home directory, no environment, no current directory, no installed path.
@@ -15,17 +14,30 @@ import { refuse } from './errors.mjs'
 //   Linux    a systemd user unit
 //   Windows  refused, typed: startup there has not been qualified
 //
-// The unit runs the service entry in the foreground with `--startup`; the
-// service writes its own record once it listens, exactly as under `start`.
+// The unit runs the service entry in the foreground with `--startup`, in the
+// root directory (never one that could be a vault), with the search path it
+// is given, so the service finds the same programs the person uses. It is
+// restarted after a crash and after an exit with a code the service uses to
+// ask for it (a new release on disk), never after a clean stop and never in a
+// tight loop; a refusal under `--startup` exits cleanly. The service writes
+// its own bounded log; the unit's output file receives only what happens
+// before it can, such as a module that cannot be loaded.
 
 export const STARTUP_PLATFORMS = Object.freeze(['darwin', 'linux'])
 const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const CONTROL = /[\u0000-\u001f\u007f]/
+// Seconds: the least time between two starts, and how long a stop may take before the manager ends the process. The
+// service gives a tick in flight 30 seconds to finish when it is asked to stop.
+const THROTTLE_SECONDS = 60
+const EXIT_TIMEOUT_SECONDS = 60
 
 const xml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;')
 // systemd: quoted, with its specifier and variable characters doubled.
 const unitWord = (value) => `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', '$$$$')}"`
+// systemd: one quoted assignment of Environment=, where `$` has no meaning and only specifiers are expanded.
+const unitAssignment = (name, value) => `"${`${name}=${value}`.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`
 
-function launchdText({ label, words, logPath, workingDirectory }) {
+function launchdText({ label, words, logPath, workingDirectory, searchPath }) {
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
@@ -33,12 +45,15 @@ function launchdText({ label, words, logPath, workingDirectory }) {
     '<dict>',
     '  <key>Label</key>', `  <string>${xml(label)}</string>`,
     '  <key>ProgramArguments</key>', '  <array>', ...words.map((word) => `    <string>${xml(word)}</string>`), '  </array>',
+    ...(searchPath === null ? [] : ['  <key>EnvironmentVariables</key>', '  <dict>', '    <key>PATH</key>', `    <string>${xml(searchPath)}</string>`, '  </dict>']),
+    '  <key>WorkingDirectory</key>', `  <string>${xml(workingDirectory)}</string>`,
     '  <key>RunAtLoad</key>', '  <true/>',
-    // Restarted after a crash, not after a clean stop; a refusal is not retried in a tight loop.
+    // Restarted after a crash or a non-zero exit, not after a clean stop; a refusal exits cleanly and is not retried.
     '  <key>KeepAlive</key>', '  <dict>', '    <key>SuccessfulExit</key>', '    <false/>', '  </dict>',
-    '  <key>ThrottleInterval</key>', '  <integer>60</integer>',
-    '  <key>ProcessType</key>', '  <string>Background</string>',
-    ...(workingDirectory === undefined ? [] : ['  <key>WorkingDirectory</key>', `  <string>${xml(workingDirectory)}</string>`]),
+    '  <key>ThrottleInterval</key>', `  <integer>${THROTTLE_SECONDS}</integer>`,
+    '  <key>ExitTimeOut</key>', `  <integer>${EXIT_TIMEOUT_SECONDS}</integer>`,
+    // Standard, not Background: the service's budgets were measured without the I/O throttling of a background process.
+    '  <key>ProcessType</key>', '  <string>Standard</string>',
     '  <key>StandardOutPath</key>', `  <string>${xml(logPath)}</string>`,
     '  <key>StandardErrorPath</key>', `  <string>${xml(logPath)}</string>`,
     '</dict>',
@@ -47,7 +62,7 @@ function launchdText({ label, words, logPath, workingDirectory }) {
   return `${lines.join('\n')}\n`
 }
 
-function systemdText({ label, words, logPath, workingDirectory }) {
+function systemdText({ label, words, logPath, workingDirectory, searchPath }) {
   const lines = [
     '[Unit]',
     `Description=Atelier Obsidian maintenance (${label.replaceAll(/[^A-Za-z0-9._-]/g, '')})`,
@@ -55,11 +70,13 @@ function systemdText({ label, words, logPath, workingDirectory }) {
     '[Service]',
     'Type=simple',
     `ExecStart=${words.map(unitWord).join(' ')}`,
-    ...(workingDirectory === undefined ? [] : [`WorkingDirectory=${workingDirectory.replaceAll('%', '%%')}`]),
-    // Restarted after a crash; not after a clean stop, and not after a refusal (exit status 2).
+    ...(searchPath === null ? [] : [`Environment=${unitAssignment('PATH', searchPath)}`]),
+    `WorkingDirectory=${workingDirectory.replaceAll('%', '%%')}`,
+    // Restarted after a crash or a non-zero exit; not after a clean stop, and not after a refusal (exit status 2).
     'Restart=on-failure',
-    'RestartSec=60',
+    `RestartSec=${THROTTLE_SECONDS}`,
     'RestartPreventExitStatus=2',
+    `TimeoutStopSec=${EXIT_TIMEOUT_SECONDS}`,
     `StandardOutput=append:${logPath.replaceAll('%', '%%')}`,
     `StandardError=append:${logPath.replaceAll('%', '%%')}`,
     '',
@@ -69,19 +86,40 @@ function systemdText({ label, words, logPath, workingDirectory }) {
   return `${lines.join('\n')}\n`
 }
 
-// { platform, kind, fileName, text }. `args` are the arguments of the entry after `--startup`.
-export function buildStartupAdapter({ platform, label, nodePath, entryPath, args = [], logPath, workingDirectory } = {}) {
+// The search path a unit carries: the entries of `value` (a PATH as the environment holds it) that are absolute
+// directories, in their order, each once, and none inside a temporary directory (`temporary`, absolute prefixes): a
+// relative entry would be resolved in the unit's working directory, and a temporary one (an agent's session, say) is
+// gone after a restart. Pure. Null when nothing is left.
+export function startupSearchPath(value, { temporary = [] } = {}) {
+  if (typeof value !== 'string') return null
+  const inside = (entry) => temporary.some((prefix) => typeof prefix === 'string' && path.posix.isAbsolute(prefix) && (entry === prefix || entry.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`)))
+  const kept = []
+  for (const raw of value.split(':')) {
+    const entry = raw.length > 1 ? raw.replace(/\/+$/, '') : raw
+    if (!path.posix.isAbsolute(entry) || CONTROL.test(entry) || inside(entry) || kept.includes(entry)) continue
+    kept.push(entry)
+  }
+  return kept.length === 0 ? null : kept.join(':')
+}
+
+// { platform, kind, fileName, text }. `args` are the arguments of the entry after `--startup`; `searchPath` is the PATH
+// the unit sets (absolute entries joined by `:`; see startupSearchPath), none when omitted.
+export function buildStartupAdapter({ platform, label, nodePath, entryPath, args = [], logPath, workingDirectory = '/', searchPath = null } = {}) {
   if (platform === 'win32') refuse('startup-platform-unqualified', 'operating-system startup on Windows has not been qualified; no unit is generated for it', { platform })
   if (!STARTUP_PLATFORMS.includes(platform)) refuse('startup-platform-unsupported', 'no startup unit is known for this platform', { platform: String(platform) })
   if (typeof label !== 'string' || !LABEL.test(label)) refuse('startup-adapter-input-invalid', 'the unit label must be a plain identifier')
   const flavor = path.posix
-  for (const [name, value] of [['nodePath', nodePath], ['entryPath', entryPath], ['logPath', logPath], ...(workingDirectory === undefined ? [] : [['workingDirectory', workingDirectory]])]) {
-    if (typeof value !== 'string' || !flavor.isAbsolute(value) || /[\u0000-\u001f]/.test(value)) refuse('startup-adapter-input-invalid', `${name} must be an absolute path given by the caller`, { name })
+  for (const [name, value] of [['nodePath', nodePath], ['entryPath', entryPath], ['logPath', logPath], ['workingDirectory', workingDirectory]]) {
+    if (typeof value !== 'string' || !flavor.isAbsolute(value) || CONTROL.test(value)) refuse('startup-adapter-input-invalid', `${name} must be an absolute path given by the caller`, { name })
+  }
+  if (searchPath !== null && (typeof searchPath !== 'string' || searchPath.split(':').some((entry) => !flavor.isAbsolute(entry) || CONTROL.test(entry)))) {
+    refuse('startup-adapter-input-invalid', 'searchPath must be absolute directories joined by ":"', { name: 'searchPath' })
   }
-  if (!Array.isArray(args) || args.some((word) => typeof word !== 'string' || word === '' || /[\u0000-\u001f]/.test(word))) refuse('startup-adapter-input-invalid', 'args must be a list of plain words')
+  if (!Array.isArray(args) || args.some((word) => typeof word !== 'string' || word === '' || CONTROL.test(word))) refuse('startup-adapter-input-invalid', 'args must be a list of plain words')
   if (args.includes('--startup')) refuse('startup-adapter-input-invalid', '--startup is added by the builder')
   const words = [nodePath, entryPath, '--startup', ...args]
+  const input = { label, words, logPath, workingDirectory, searchPath }
   return platform === 'darwin'
-    ? { platform, kind: 'launchd-user-agent', fileName: `${label}.plist`, text: launchdText({ label, words, logPath, workingDirectory }) }
-    : { platform, kind: 'systemd-user-unit', fileName: `${label}.service`, text: systemdText({ label, words, logPath, workingDirectory }) }
+    ? { platform, kind: 'launchd-user-agent', fileName: `${label}.plist`, text: launchdText(input) }
+    : { platform, kind: 'systemd-user-unit', fileName: `${label}.service`, text: systemdText(input) }
 }

package/src/runtime/obsidian/unheld-evidence.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
+import { realPathOfLocation } from './vault-location.mjs'
+
+// Whether the Obsidian this account runs lists a vault Atelier is filling for
+// the first time, as the publisher's `direct-unheld` path needs to know
+// (publisher.mjs; docs/obsidian-contract.md, "First publication into a vault
+// no Obsidian lists"). Read from the app's settings file, never from the app:
+//
+//   { unlisted: true }                   the file was read, and none of its entries is the vault root, a folder above
+//                                        it or a folder inside it
+//   { unlisted: false, reason, ... }     anything else, which gives no evidence
+//
+// It errs towards "no evidence": a file that is missing (an app that has shown
+// only its starter window writes none), that cannot be read after `attempts`
+// reads `delayMs` apart (the app rewrites it with a plain write, so a reader
+// can find it empty or cut short while it writes), that is not a JSON object,
+// or that has an entry whose folder is not an absolute path or has a `..`
+// segment (after a link, `..` leads where the text does not); and a Flatpak or
+// snap build of the app anywhere on this account, whose list lives in its
+// sandbox and not in this file. The root and every listed folder are compared
+// as written and as their real paths, in any letter case, so a link on the way
+// to either side, or another spelling, does not hide an entry.
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const folded = (target) => target.normalize('NFC').toLowerCase()
+// The real path of a folder that may not exist, and its lexical path when it cannot be resolved (a volume that is gone).
+const realOrLexical = (target) => { try { return realPathOfLocation(target) } catch { return path.resolve(target) } }
+const spellings = (target) => [...new Set([path.resolve(target), realOrLexical(target)].map(folded))]
+// Strictly inside: `..x` is a folder name, not a way up.
+const inside = (parent, child) => { const relative = path.relative(parent, child); return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) }
+
+// How a listed folder stands to the vault root, or null when it is neither the root, above it, nor inside it.
+function relationOf(entryPath, root) {
+  const listed = spellings(entryPath)
+  if (listed.some((folder) => root.includes(folder))) return 'vault-listed'
+  if (listed.some((folder) => root.some((candidate) => inside(folder, candidate)))) return 'vault-inside-listed-vault'
+  if (listed.some((folder) => root.some((candidate) => inside(candidate, folder)))) return 'listed-vault-inside-vault'
+  return null
+}
+
+const noEvidence = (reason, extra = {}) => ({ unlisted: false, reason, ...extra })
+
+// `read` answers readObsidianSettings for the app's user-data directory; `sandboxed` answers whether a Flatpak or snap
+// build is present. Either one that throws gives no evidence.
+export async function readUnheldEvidence({ vaultRoot, read, sandboxed, attempts = 3, delayMs = 50, sleep = delay } = {}) {
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return noEvidence('vault-root-unknown')
+  if (typeof read !== 'function' || typeof sandboxed !== 'function') return noEvidence('obsidian-settings-location-unknown')
+  let present = true
+  try { present = sandboxed() !== false } catch { present = true }
+  if (present) return noEvidence('obsidian-sandboxed')
+  let answer = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try { answer = read() } catch { answer = { ok: false, code: 'obsidian-settings-unreadable' } }
+    if (answer?.ok === true || answer?.code !== 'obsidian-settings-unreadable') break
+    if (attempt < attempts) await sleep(delayMs)
+  }
+  if (answer?.ok !== true) return noEvidence(typeof answer?.code === 'string' ? answer.code : 'obsidian-settings-unreadable')
+  const vaults = answer.vaults ?? {}
+  if (!isPlainObject(vaults)) return noEvidence('obsidian-settings-not-object')
+  const root = spellings(vaultRoot)
+  for (const [id, entry] of Object.entries(vaults)) {
+    if (!isPlainObject(entry) || typeof entry.path !== 'string' || !path.isAbsolute(entry.path) || entry.path.split(/[\\/]/).includes('..')) return noEvidence('obsidian-settings-entry-unreadable', { id })
+    const relation = relationOf(entry.path, root)
+    if (relation !== null) return noEvidence(relation, { id, path: entry.path })
+  }
+  return { unlisted: true }
+}
+
+// The reader the maintenance service gives its engine: the settings file of the app for this account (HOME, and on
+// Linux XDG_CONFIG_HOME), and any Flatpak or snap build, installed or having left its list, whichever wrote last.
+// `exists` answers whether a path exists: the build's system-wide places (/var/lib/flatpak, /snap) are looked up through
+// it too.
+export function createProductionUnheldEvidence({ platform = process.platform, env = process.env, exists = fs.existsSync } = {}) {
+  const userDataDir = obsidianUserDataDir({ platform, env })
+  return ({ vaultRoot }) => readUnheldEvidence({
+    vaultRoot,
+    read: () => (userDataDir === null ? { ok: false, code: 'obsidian-settings-location-unknown' } : readObsidianSettings({ userDataDir })),
+    // Present at all, not only when its list was written last: with no list time given, any installation or list counts.
+    sandboxed: () => obsidianSandboxedBuild({ platform, env, exists, modified: () => null }) !== null,
+  })
+}

package/src/runtime/obsidian/vault-location.mjs

@@ -0,0 +1,300 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { checkManagedRoots, realLocation } from '../../project/file-class.mjs'
+import { realPathAsStored } from '../../project/private-state.mjs'
+import { VAULT_ALLOCATION_SCHEMA, VAULT_LOCK_DIRECTORY, allocatedFolderState, folderIdentity, hasCommittedGeneration, readVaultAllocation, writeVaultAllocation } from '../../projection/obsidian/recovery/store.mjs'
+import { refuse } from './errors.mjs'
+
+// Where the vaults of a workspace live when a person decided it (the
+// `location` decision of its machine settings), and the folder each view
+// gets there.
+//
+//   <location>/<project> (<view>)          e.g. ~/Atelier/harbor-notes (everything)
+//
+// The folder's name is the vault's name in Obsidian (its vault switcher, its
+// window title, a `vault=` call), so it carries the project and the view:
+// readable, the same in the file manager and in the app, and unique across
+// projects and views. The view is the text in the last parentheses, up to
+// its first space (a number follows it when the name was taken; view ids
+// never contain a space), and no
+// name of this form is the beginning of another one's path, which matters
+// because the app matches an `obsidian://open?path=` by the longest string
+// prefix among the folders it lists.
+//
+// A folder is allocated once per view, at its first publication, by the
+// maintenance engine under its lock, and recorded (see
+// src/projection/obsidian/recovery/store.mjs). It is never recomputed: a
+// renamed project or a new location leaves an allocated vault where it is.
+// A view published before, under the data root, stays there; a workspace
+// that decided no location publishes there as before.
+
+export const MAX_PROJECT_NAME_BYTES = 80
+
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029/\\:*?"<>|#^[\]()]/g
+// Bidirectional controls and marks, and characters that show nothing: a name reads as it is.
+const INVISIBLE = /[\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff]/g
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)$/i
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+
+// The longest start of `text` of at most `maxBytes` bytes that ends between two characters as a person reads them: a
+// letter and its accents, or an emoji sequence, stay together or go together.
+function cutToBytes(text, maxBytes) {
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text
+  let cut = ''
+  for (const { segment } of GRAPHEMES.segment(text)) {
+    if (Buffer.byteLength(cut + segment, 'utf8') > maxBytes) break
+    cut += segment
+  }
+  return cut
+}
+
+// A piece of text as a folder name on macOS, Linux and Windows, and in the app: NFC, no control, separator, reserved
+// or link character, no parentheses (they end the view's part), single spaces, no leading or trailing space or dot
+// (a leading dot hides a folder from the app), cut to a number of bytes between two characters as a person reads them,
+// and no Windows device name. May be empty.
+export function safeFolderPart(text, maxBytes = MAX_PROJECT_NAME_BYTES) {
+  const cleaned = String(text ?? '').normalize('NFC').replace(INVISIBLE, '').replace(UNSAFE, ' ').replace(/\s+/gu, ' ').replace(/^[\s.]+|[\s.]+$/gu, '')
+  const cut = cutToBytes(cleaned, maxBytes).replace(/[\s.]+$/u, '')
+  return WINDOWS_DEVICE.test(cut.split('.')[0]) ? `_${cut}` : cut
+}
+
+// The name people and Obsidian read for a project: its configured `name`, else the name of its folder.
+export function projectDisplayName(project) {
+  return safeFolderPart(project?.config?.name) || safeFolderPart(path.basename(String(project?.configDir ?? ''))) || 'project'
+}
+
+// `<project> (<view>)`, or `<project> (<view> <number>)` from the second.
+export function vaultFolderName({ projectName, scopeId, number = 1 }) {
+  const view = String(scopeId).replaceAll(':', '_')
+  return `${projectName} (${view}${number > 1 ? ` ${number}` : ''})`
+}
+
+const isInside = (parent, child) => { const relative = path.relative(parent, child); return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative) }
+const isSameOrInside = (parent, child) => parent === child || isInside(parent, child)
+
+// The nearest folder that exists on the way up from `target` (itself included).
+function nearestExisting(target) {
+  let current = path.resolve(target)
+  for (;;) {
+    if (fs.existsSync(current)) return current
+    const parent = path.dirname(current)
+    if (parent === current) return current
+    current = parent
+  }
+}
+
+// A path compared with another as a volume that folds letter case would: NFC, lower case. Used where a false match
+// only refuses (an enclosing vault, a synced or protected folder, a listed name), so a case-sensitive volume is at worst
+// refused a folder whose name differs from a listed vault's in letter case only.
+const folded = (target) => target.normalize('NFC').toLowerCase()
+const foldedInside = (parent, child) => isSameOrInside(folded(parent), folded(child))
+// The real path of a folder that may not exist yet, as the file system stores it (realPathAsStored): the nearest
+// existing folder on the way up resolved, links and letter case included, and the missing tail appended.
+export const realPathOfLocation = (target) => realLocation(target, realPathAsStored)
+// The same, for a folder read from somewhere else (the app's list, the home folder): its lexical path when it cannot be
+// resolved, since it may be on a volume that is gone.
+const realOrLexical = (target) => { try { return realPathOfLocation(target) } catch { return path.resolve(target) } }
+// A path as written and as its real path, both.
+const spellings = (target) => [...new Set([path.resolve(target), realOrLexical(target)])]
+
+// A folder a sync client of this account keeps in step with other machines, by name; null for any other folder.
+// `exists` answers whether a path exists. iCloud also syncs Desktop and Documents when "Desktop & Documents Folders"
+// is on, which shows as their folders inside iCloud Drive.
+export function syncedFolderOf(target, { homedir, exists = fs.existsSync } = {}) {
+  if (typeof homedir !== 'string' || !path.isAbsolute(homedir)) return null
+  const resolved = path.resolve(target)
+  const within = (...parts) => foldedInside(path.join(homedir, ...parts), resolved)
+  if (within('Library', 'Mobile Documents')) return 'iCloud Drive'
+  if (within('Library', 'CloudStorage')) return 'a cloud storage provider'
+  for (const [folder, name] of [['Dropbox', 'Dropbox'], ['OneDrive', 'OneDrive'], ['Google Drive', 'Google Drive'], ['Box', 'Box']]) if (within(folder)) return name
+  for (const folder of ['Desktop', 'Documents']) {
+    if (!within(folder)) continue
+    try { if (exists(path.join(homedir, 'Library', 'Mobile Documents', 'com~apple~CloudDocs', folder))) return `iCloud (${folder})` } catch { /* not known */ }
+  }
+  return null
+}
+
+// A folder for which macOS asks a person before an app, or a background service, may read it; null otherwise.
+export function protectedFolderOf(target, { homedir, platform = process.platform } = {}) {
+  if (platform !== 'darwin' || typeof homedir !== 'string' || !path.isAbsolute(homedir)) return null
+  const resolved = path.resolve(target)
+  return ['Desktop', 'Documents', 'Downloads'].find((folder) => foldedInside(path.join(homedir, folder), resolved)) ?? null
+}
+
+// The folder of a vault Atelier publishes into that contains `target`, or null: the vault lock of a published vault,
+// or a folder another view of this workspace was allocated.
+function enclosingAtelierVault(target, allocatedPaths = []) {
+  const candidates = spellings(target)
+  for (const allocated of allocatedPaths) if (spellings(allocated).some((folder) => candidates.some((candidate) => foldedInside(folder, candidate)))) return allocated
+  for (const resolved of candidates) {
+    let current = resolved
+    for (;;) {
+      try { if (fs.statSync(path.join(current, VAULT_LOCK_DIRECTORY)).isDirectory()) return current } catch { /* not a published vault */ }
+      const parent = path.dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+  }
+  return null
+}
+
+// The folder of a vault the app lists that contains `target` or is it; null when there is none or no list is known.
+// `vaults` is the app's own map, id -> { path }. Both sides are compared as written and as their real paths, in any
+// letter case, so neither a link nor another spelling of a listed folder hides it.
+function enclosingListedVault(target, vaults) {
+  if (vaults === null || typeof vaults !== 'object') return null
+  const candidates = spellings(target)
+  for (const entry of Object.values(vaults)) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.path !== 'string' || !path.isAbsolute(entry.path)) continue
+    if (spellings(entry.path).some((folder) => candidates.some((candidate) => foldedInside(folder, candidate)))) return entry.path
+  }
+  return null
+}
+
+// A folder a sync client keeps in step, or one macOS protects, for any spelling of the target and the home folder.
+const anySpelling = (check, target, homedir) => {
+  if (typeof homedir !== 'string' || !path.isAbsolute(homedir)) return null
+  for (const home of spellings(homedir)) for (const candidate of spellings(target)) { const found = check(candidate, home); if (found !== null) return found }
+  return null
+}
+
+// Whether `parent` may hold this workspace's vaults, checked before it is decided and again before a folder is
+// allocated there. Refuses, typed, a folder inside an enrolled repository or the project, inside a vault Atelier
+// publishes, inside a vault the app lists (when `vaults` is known), or on another volume than the workspace's private
+// state (the atomic exchange that publishes a note cannot cross volumes); and a folder a sync client keeps in step,
+// unless `allowSynced`. Answers the warnings a person should hear: { synced, protected }. `deviceOf` answers the
+// device a path is on.
+export function checkVaultParent({ parent, workspaceRoot, repositoryRoots, vaults = null, allocatedPaths = [], allowSynced = false, homedir, platform = process.platform, deviceOf = (target) => fs.statSync(target).dev }) {
+  if (typeof parent !== 'string' || !path.isAbsolute(parent) || path.resolve(parent) !== parent) refuse('vault-location-not-absolute', 'where vaults live must be an absolute folder, written plainly')
+  // A repository beside the vaults, below the same folder (a home folder, say), is no overlap: each vault folder is
+  // checked again against every repository when its store is made.
+  const overlaps = checkManagedRoots({ managedRoots: [parent], repositoryRoots }).refusals.filter(({ code }) => code !== 'repository-inside-managed-root')
+  // A folder that is itself a link: the folder it leads to is named instead, so the decision says where vaults are.
+  if (overlaps.some(({ code }) => code === 'managed-root-symlink-alias')) refuse('vault-location-is-link', 'this folder is a link; name the folder it leads to', { refusals: overlaps.map(({ code }) => code) })
+  if (overlaps.length > 0) refuse('vault-location-inside-repository', 'vaults never live inside an enrolled repository or the project', { refusals: overlaps.map(({ code }) => code) })
+  // Atelier's own private state: publication state, recovery and staging live there, and a vault inside it would be
+  // published over them.
+  if (typeof workspaceRoot === 'string' && spellings(workspaceRoot).some((root) => spellings(parent).some((candidate) => foldedInside(root, candidate)))) {
+    refuse('vault-location-inside-private-state', 'vaults never live inside Atelier\'s private state for this workspace')
+  }
+  // A folder a vault can be made in: the nearest folder that exists on the way is a folder this user can write in.
+  const nearest = nearestExisting(parent)
+  try {
+    if (!fs.statSync(nearest).isDirectory()) refuse('vault-location-unusable', 'no folder can be made there: a file is in the way', { path: nearest })
+    fs.accessSync(nearest, fs.constants.W_OK | fs.constants.X_OK)
+  } catch (error) {
+    if (typeof error?.code === 'string' && !/^E[A-Z]+$/.test(error.code)) throw error
+    refuse('vault-location-unusable', 'no folder can be made there: this user cannot write in the nearest folder that exists', { path: nearest, cause: error.code ?? null })
+  }
+  const inAtelierVault = enclosingAtelierVault(parent, allocatedPaths)
+  if (inAtelierVault !== null) refuse('vault-location-inside-vault', 'vaults never live inside a vault Atelier publishes', { vault: inAtelierVault })
+  const inListedVault = enclosingListedVault(parent, vaults)
+  if (inListedVault !== null) refuse('vault-location-inside-vault', 'vaults never live inside a folder Obsidian lists as a vault: that vault would show their notes too, and a call run in their folders would reach it', { vault: inListedVault })
+  if (typeof workspaceRoot === 'string' && deviceOf(nearestExisting(parent)) !== deviceOf(nearestExisting(workspaceRoot))) {
+    refuse('vault-location-other-volume', 'vaults live on the volume of Atelier\'s private data, because a note is published by an exchange that cannot cross volumes; name another data root (--data-root) on that volume to use it')
+  }
+  const synced = anySpelling((candidate, home) => syncedFolderOf(candidate, { homedir: home }), parent, homedir)
+  if (synced !== null && !allowSynced) {
+    refuse('vault-location-synced', `this folder is kept in step by ${synced}: another machine's Obsidian could hold a vault there unseen, and a sync conflict is not a publication; pass --allow-synced-location to use it anyway`, { synced })
+  }
+  return { synced, protected: anySpelling((candidate, home) => protectedFolderOf(candidate, { homedir: home, platform }), parent, homedir) }
+}
+
+// The folder that holds the vaults, made when it is missing: private to this user, as each vault in it is. A folder on
+// the way to it that is missing too is made as any other folder is, so naming ~/Projects/Atelier makes ~/Projects an
+// ordinary folder.
+function makeHoldingFolder(parent) {
+  fs.mkdirSync(path.dirname(parent), { recursive: true })
+  try { fs.mkdirSync(parent, { mode: 0o700 }) } catch (error) { if (error?.code !== 'EEXIST') throw error }
+}
+
+// The view's allocation, allocated now when this workspace decided where its vaults live and the view has none yet
+// and was never published under the data root; null when the view's vault stays under the data root. The folder is
+// made here, exclusively and private to this user, under the first name that is free: taken by nothing on the disk
+// and, when the app's list is known, by no vault it lists with that name in any letter case.
+// `storedPathOf` answers a folder's real path as the file system stores it (realPathAsStored).
+export function ensureVaultAllocation({ workspaceRoot, workspaceId, scopeId, location, projectName, repositoryRoots, vaults = null, allocatedPaths = [], homedir, now, storedPathOf = realPathAsStored }) {
+  const existing = readVaultAllocation({ workspaceRoot, workspaceId, scopeId })
+  // An allocated folder that has gone is made again where it was, private, and recorded as the folder it now is; one
+  // another folder replaced is left alone, and the store refuses to publish into it. `vaults` is the app's list here
+  // too: a folder is made again only where one would be allocated.
+  if (existing !== null && allocatedFolderState(existing) === 'missing') {
+    // Only where the store would publish: a record that names a folder inside a repository, the project or the
+    // private state (edited, or copied from elsewhere) makes nothing there.
+    const guard = checkManagedRoots({ managedRoots: [workspaceRoot, existing.path], repositoryRoots })
+    if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals.map(({ code }) => code) })
+    if (spellings(workspaceRoot).some((root) => spellings(existing.path).some((candidate) => foldedInside(root, candidate)))) {
+      refuse('vault-location-inside-private-state', 'vaults never live inside Atelier\'s private state for this workspace')
+    }
+    // Only where it was: the folder that held it leads where it did, through no link put on the way since (into a
+    // vault the app lists, a synced folder), and passes every check a location is decided with.
+    const moved = (leadsTo) => refuse('vault-allocation-moved', 'the folder that held this view\'s vault now leads somewhere else, through a link; its vault is not made again there', { parent: existing.parent, leadsTo })
+    let realParent = null
+    try { realParent = realPathOfLocation(existing.parent) } catch { /* not reachable */ }
+    if (realParent !== existing.parent) moved(realParent)
+    checkVaultParent({ parent: existing.parent, workspaceRoot, repositoryRoots, vaults, allocatedPaths: allocatedPaths.filter((allocated) => allocated !== existing.path), allowSynced: true, homedir })
+    try { makeHoldingFolder(existing.parent); fs.mkdirSync(existing.path, { mode: 0o700 }) } catch (error) {
+      if (error?.code === 'EEXIST') return existing
+      refuse('vault-location-unusable', 'the folder for this view\'s vault cannot be made again there', { parent: existing.parent, cause: error?.code ?? null })
+    }
+    // Made where the record says and nowhere else: a link put on the way between the check and the folder is found here.
+    let madeAt = null
+    try { madeAt = realPathAsStored(existing.path) } catch { /* not reachable */ }
+    if (madeAt !== existing.path) {
+      try { fs.rmdirSync(existing.path) } catch { /* not ours to remove */ }
+      moved(madeAt)
+    }
+    const made = folderIdentity(existing.path)
+    return writeVaultAllocation({ workspaceRoot, allocation: { ...existing, device: made.device, inode: made.inode } })
+  }
+  if (existing !== null) return existing
+  if (location === null || location === undefined || hasCommittedGeneration({ workspaceRoot, scopeId })) return null
+  const parent = location.parent
+  // A synced location was allowed when it was decided; it is checked again for everything else.
+  checkVaultParent({ parent, workspaceRoot, repositoryRoots, vaults, allocatedPaths, allowSynced: true, homedir })
+  const unusable = (error) => refuse('vault-location-unusable', 'the folder for this view\'s vault cannot be made there', { parent, cause: error?.code ?? String(error?.message ?? error) })
+  try { makeHoldingFolder(parent) } catch (error) { unusable(error) }
+  // The folder is recorded by its real path, as the file system stores it: a link on the way to the location decided
+  // then leads nowhere else later, and the path is the one the app and every check see.
+  const realParent = realPathAsStored(parent)
+  const listedNames = new Set(Object.values(vaults ?? {}).filter((entry) => typeof entry?.path === 'string').map((entry) => folded(path.basename(entry.path))))
+  for (let number = 1; number <= 99; number += 1) {
+    const name = vaultFolderName({ projectName, scopeId, number })
+    const folder = path.join(realParent, name)
+    if (listedNames.has(folded(name)) || fs.lstatSync(folder, { throwIfNoEntry: false }) !== undefined) continue
+    try { fs.mkdirSync(folder, { mode: 0o700 }) } catch (error) { if (error.code === 'EEXIST') continue; unusable(error) }
+    try { fs.chmodSync(folder, 0o700) } catch { /* a file system without modes */ }
+    const made = folderIdentity(folder)
+    // Recorded as the file system stores the folder's path, which is what every later check reads back: a volume that
+    // stores names in another Unicode form (HFS+ stores NFD) would otherwise never match the name as it was asked for.
+    let stored = null
+    try { stored = storedPathOf(folder) } catch { /* not reachable: refused below */ }
+    // Only the folder just made, under the parent that was checked: its name may come back in another Unicode form, and
+    // nothing else may differ. A link put on the way since would otherwise be recorded, and then trusted.
+    if (stored === null || path.dirname(stored) !== realParent || path.basename(stored).normalize('NFC') !== name.normalize('NFC')) {
+      try { fs.rmdirSync(folder) } catch { /* not ours to remove */ }
+      refuse('vault-allocation-moved', 'the folder that holds the vaults led somewhere else once this view\'s folder was made; nothing is recorded', { parent: realParent, leadsTo: stored })
+    }
+    return writeVaultAllocation({ workspaceRoot, allocation: { schema: VAULT_ALLOCATION_SCHEMA, workspaceId, scopeId, path: stored, name: path.basename(stored), parent: path.dirname(stored), device: made.device, inode: made.inode, allocatedAt: now } })
+  }
+  return refuse('vault-location-full', 'no free vault name is left for this view in that folder', { parent })
+}
+
+// The app's vault list for an allocation, from its settings file and never from the app: { ok: true, vaults } when it
+// was read, or when the app never ran here (no file, and no Flatpak or snap build whose list lives elsewhere), and
+// { ok: false, code } otherwise, so a folder is never allocated while a listed vault could enclose it or have its
+// name. `read` answers readObsidianSettings; a file the app is writing can read as unreadable for a moment, so an
+// unreadable file is read again, up to `attempts` times `delayMs` apart. `sandboxed` is true for such a build.
+export async function readAppVaultListForAllocation({ read, sandboxed = false, attempts = 3, delayMs = 50, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+  if (sandboxed) return { ok: false, code: 'obsidian-sandboxed' }
+  let answer = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try { answer = read() } catch { answer = { ok: false, code: 'obsidian-settings-unreadable' } }
+    if (answer?.ok === true) return { ok: true, vaults: answer.vaults ?? {} }
+    if (answer?.code === 'obsidian-settings-missing') return { ok: true, vaults: {} }
+    if (answer?.code !== 'obsidian-settings-unreadable') break
+    if (attempt < attempts) await sleep(delayMs)
+  }
+  return { ok: false, code: typeof answer?.code === 'string' ? answer.code : 'obsidian-settings-unreadable' }
+}
+

package/src/runtime/obsidian/view-counts.mjs

@@ -0,0 +1,34 @@
+import { selectScope } from '../../projection/obsidian/contracts.mjs'
+import { DEFAULT_ELIGIBILITY, buildGraph, profileFor } from './pipeline.mjs'
+
+// How many notes a view would show on this machine, and why the other notes
+// its selector names are withheld: the numbers a person sees before a view is
+// declared or first opened. Read-only. The canonical graph is built as the
+// engine builds it, with the eligibility the caller names (the one the machine
+// settings decide, `eligibilityFor`), and the selection is the contract's own
+// selectScope, so the count is the view's.
+
+// { corpus, named, shown, withheld: { unclassified, audience }, truncated }: the notes of the project; those the
+// view's selector names, whatever their classification and audience; those the view shows under `audienceAllow`
+// and `eligibility` (with its expansion); and, of the named ones, how many are withheld because they are not
+// eligible (they carry no classification, or, in a vault that is only yours, cannot be read as notes), or carry an
+// audience that is not admitted.
+export function viewCounts({ project, audienceAllow, scope, eligibility = DEFAULT_ELIGIBILITY, workspaceId = 'ws-unprepared' }) {
+  const graph = buildGraph({ project, eligibility })
+  const known = new Set(graph.nodes.map((node) => node.id))
+  const edges = graph.edges.filter((edge) => known.has(edge.source) && known.has(edge.target))
+  const profile = profileFor({ project, workspaceId, audienceAllow })
+  const selection = selectScope({ canonicalSnapshot: { nodes: graph.nodes, edges }, profile, selector: scope.selector, expansion: scope.expansion, mode: scope.mode })
+  // The same selector over every note made visible names what it would show if nothing were withheld.
+  const everyNote = graph.nodes.map((node) => ({ ...node, eligible: true, audience: undefined }))
+  const named = selectScope({ canonicalSnapshot: { nodes: everyNote, edges: [] }, profile, selector: scope.selector, mode: scope.mode === 'focus' ? 'scoped' : scope.mode }).nodes
+  const byId = new Map(graph.nodes.map((node) => [node.id, node]))
+  const allowed = new Set(audienceAllow)
+  const withheld = { unclassified: 0, audience: 0 }
+  for (const id of named) {
+    const node = byId.get(id)
+    if (node.eligible !== true) withheld.unclassified += 1
+    else if (node.audience !== undefined && !allowed.has(node.audience)) withheld.audience += 1
+  }
+  return { corpus: graph.nodes.length, named: named.length, shown: selection.nodes.length, withheld, truncated: selection.truncated }
+}