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

package/src/runtime/obsidian/login-item.mjs

@@ -0,0 +1,332 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { canonicalJson, closedObject, isoTime } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { ensureServiceSettings } from './lifecycle.mjs'
+import { ensureWorkspaceIdentity, readLocalPointer, resolveDataRoot } from './machine-settings.mjs'
+import { SERVICE_MANAGER_KINDS } from './service-managers.mjs'
+import { readLastStartup, readServiceSettings, serviceNameFor, servicePaths, writeServiceSettings } from './service-record.mjs'
+import { resolveServiceWorkspace } from './service.mjs'
+import { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from './startup-adapters.mjs'
+
+// A login item: the operating system starts this workspace's maintenance
+// service when the person logs in, so a vault is fresh after a restart
+// without anything being run.
+//
+//   macOS  a launchd user agent: ~/Library/LaunchAgents/ai.mnstry.atelier.<project>.<workspace-id>.plist
+//   Linux  a systemd user unit:  ~/.config/systemd/user/atelier-obsidian-<workspace-id>.service
+//   Windows not offered (startup-platform-unqualified)
+//
+// One per workspace, each with its own label, port, log and consent, each
+// running its own project's installed release. The unit runs the service
+// entry of the package installed in the project, named by its path, so an
+// upgrade in the project is what the next start runs; the Node that ran the
+// installing command, by its real path, so a per-shell link of a version
+// manager is never named; the search path the person had then, absolute
+// entries only; the data root the workspace was resolved under and the
+// workspace, so the service at login finds the same workspace whatever its
+// manager's environment carries (XDG_DATA_HOME, the overlay's variable), and
+// records a refusal there even when the project no longer leads to it; and
+// `--startup`, under which the service refuses to run without a consent that
+// covers startup.
+//
+// Installing records that consent first, since the manager starts the
+// service as soon as it loads the unit, then hands the text to the injected
+// service manager (service-managers.mjs) and keeps
+//
+//   state/service/login-item.json   atelier-obsidian-login-item/v1
+//
+// { label, file, digest of the text, program: { node, entry }, searchPath }.
+// The label is allocated once and kept. Once installed, the service is
+// started through the manager (loginItemStarter), never as a child beside
+// it; a unit that differs from what would be written now (a Node that was
+// removed, another entry, an earlier release's format) is written again on
+// that way and reloaded, keeping the search path recorded at installation.
+// Removing lowers the consent to the service alone first, so a unit left
+// behind by a failed removal could only refuse, then removes the unit and
+// the record. A person who switched the item off (System Settings, or
+// `systemctl --user disable`) is not overridden: the manager is asked first,
+// the unit is neither written again nor started through it, and the service
+// is started as a child for that command only.
+
+export const LOGIN_ITEM_SCHEMA = 'atelier-obsidian-login-item/v1'
+export const LOGIN_ITEM_PACKAGE = '@mnstry/atelier'
+const ENTRY_IN_PACKAGE = Object.freeze(['src', 'runtime', 'obsidian', 'service-main.mjs'])
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const CONTROL = /[\u0000-\u001f\u007f]/
+// A package runner's cache: npx, pnpm dlx, bunx. A package there can be removed by the runner at any time.
+const RUNNER_CACHES = Object.freeze([/[\\/]_npx[\\/]/, /[\\/]pnpm[\\/]dlx[\\/]/, /[\\/]\.bun[\\/]install[\\/]cache[\\/]/])
+
+const sha256 = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`
+const isAbsolutePlain = (value) => typeof value === 'string' && path.isAbsolute(value) && !CONTROL.test(value)
+
+// ---------------------------------------------------------------------------
+// The record
+// ---------------------------------------------------------------------------
+
+function validateLoginItem(document, workspaceId) {
+  const code = 'invalid-login-item'
+  closedObject(document, { required: ['schema', 'workspaceId', 'kind', 'label', 'file', 'digest', 'program', 'searchPath', 'installedAt', 'updatedAt'] }, code, 'the login item record')
+  closedObject(document.program, { required: ['node', 'entry'] }, code, 'the program of the login item')
+  const ok = document.schema === LOGIN_ITEM_SCHEMA && document.workspaceId === workspaceId && SERVICE_MANAGER_KINDS.includes(document.kind)
+    && typeof document.label === 'string' && IDENTIFIER.test(document.label) && isAbsolutePlain(document.file) && path.basename(document.file).startsWith(document.label)
+    && typeof document.digest === 'string' && DIGEST.test(document.digest) && isAbsolutePlain(document.program.node) && isAbsolutePlain(document.program.entry)
+    && (document.searchPath === null || (typeof document.searchPath === 'string' && document.searchPath.split(':').every(isAbsolutePlain)))
+    && TIMESTAMP.test(document.installedAt) && TIMESTAMP.test(document.updatedAt)
+  if (!ok) refuse(code, 'the login item record is malformed')
+  return document
+}
+
+export function readLoginItemRecord({ workspaceRoot, workspaceId }) {
+  let text
+  try { text = readRegularTextNoFollow(servicePaths(workspaceRoot).loginItem) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    return refuse('invalid-login-item', 'the login item record cannot be read', { cause: error.code ?? 'unreadable' })
+  }
+  let document
+  try { document = JSON.parse(text) } catch { return refuse('invalid-login-item', 'the login item record is not JSON') }
+  return validateLoginItem(document, workspaceId)
+}
+
+function writeLoginItemRecord({ workspaceRoot, workspaceId, record }) {
+  validateLoginItem(record, workspaceId)
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot, directory: servicePaths(workspaceRoot).directory, label: 'Obsidian service state' })
+  atomicReplacePrivateText(path.join(directory, 'login-item.json'), canonicalJson(record))
+  return record
+}
+
+function removeLoginItemRecord({ workspaceRoot }) {
+  try { fs.unlinkSync(servicePaths(workspaceRoot).loginItem); return true } catch (error) { if (error.code === 'ENOENT') return false; throw error }
+}
+
+// ---------------------------------------------------------------------------
+// What a unit is made of
+// ---------------------------------------------------------------------------
+
+// The part of a launchd label that stands for the project: lower-case letters, digits and dashes, at most 40, from
+// its name, so a person who looks in ~/Library/LaunchAgents can tell whose it is. Pure.
+export function labelSlug(name) {
+  const slug = String(name ?? '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '')
+  return slug === '' ? 'project' : slug
+}
+
+// The label of this workspace's login item, as it is allocated the first time. Pure.
+export function loginItemLabel({ platform, projectName, workspaceId }) {
+  const id = String(workspaceId).replaceAll(':', '_')
+  return platform === 'darwin' ? `ai.mnstry.atelier.${labelSlug(projectName)}.${id}` : serviceNameFor(workspaceId).replaceAll(':', '_')
+}
+
+// The name people read for a project: its configured `name`, else the name of its folder.
+export const projectNameOf = (project) => (typeof project?.config?.name === 'string' && project.config.name.trim() !== '' ? project.config.name : path.basename(project?.configDir ?? 'project'))
+
+// Absolute folders whose contents do not outlive a restart, or not for long.
+export function temporaryRoots({ tmpdir = os.tmpdir() } = {}) {
+  const roots = new Set(['/tmp', '/private/tmp', '/var/tmp', '/private/var/tmp'])
+  if (isAbsolutePlain(tmpdir)) { roots.add(path.resolve(tmpdir)); try { roots.add(fs.realpathSync(tmpdir)) } catch { /* only as given */ } }
+  return [...roots]
+}
+
+const inside = (file, root) => file === root || file.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`)
+const isFile = (file) => { try { return fs.statSync(file).isFile() } catch { return false } }
+
+// The entry a login item runs: the service entry of the package installed for this project, found as Node finds a
+// package from the project's folder (in its node_modules or a folder's above), named by that path and not its real
+// path, so an upgrade in place is what the next start runs; else `ownEntry`, the entry of the package this command
+// runs from, unless that one is in a package runner's cache (npx) or a temporary folder, which are gone after a
+// restart (`login-item-needs-installed-package`). { entryPath, source: 'project' | 'command' }.
+export function resolveLoginItemEntry({ project, ownEntry, temporary = temporaryRoots(), exists = isFile } = {}) {
+  if (typeof project?.configDir === 'string' && path.isAbsolute(project.configDir)) {
+    for (let directory = path.resolve(project.configDir); ; directory = path.dirname(directory)) {
+      const candidate = path.join(directory, 'node_modules', ...LOGIN_ITEM_PACKAGE.split('/'), ...ENTRY_IN_PACKAGE)
+      if (exists(candidate)) return { entryPath: candidate, source: 'project' }
+      if (path.dirname(directory) === directory) break
+    }
+  }
+  const transient = typeof ownEntry !== 'string' || !path.isAbsolute(ownEntry) || RUNNER_CACHES.some((pattern) => pattern.test(ownEntry)) || temporary.some((root) => inside(path.resolve(ownEntry), root))
+  if (transient) refuse('login-item-needs-installed-package', 'a login item runs the package installed in the project, and this project has none; the command runs from a package runner\'s cache or a temporary folder, which may be gone after a restart')
+  return { entryPath: ownEntry, source: 'command' }
+}
+
+// The Node a unit names: the one running this command, by its real path.
+export const realNodePath = (execPath = process.execPath) => { try { return fs.realpathSync(execPath) } catch { return execPath } }
+
+// The data root this workspace is resolved under for this command (the flag, the pointer, the overlay's preference or
+// the platform default), which a unit names.
+export const loginItemDataRoot = ({ project, dataRoot, env = process.env, platform = process.platform }) => resolveDataRoot({ dataRoot, pointer: readLocalPointer(project), project, env, platform })
+
+// The unit this workspace's login item would have now. `dataRoot` is the resolved one (loginItemDataRoot), always named;
+// `entryArgs` follow `--project`, `--data-root` and `--workspace-id`. Pure but for the builder's refusals.
+export function planLoginItem({ platform, project, workspaceRoot, workspaceId, dataRoot, label, entryPath, entryArgs = [], nodePath, searchPath = null }) {
+  if (!isAbsolutePlain(dataRoot)) throw new TypeError('a login item names the absolute data root of its workspace')
+  if (typeof workspaceId !== 'string' || workspaceId === '') throw new TypeError('a login item names its workspace')
+  const args = [`--project=${project.configPath}`, `--data-root=${dataRoot}`, `--workspace-id=${workspaceId}`, ...entryArgs]
+  const unit = buildStartupAdapter({ platform, label, nodePath, entryPath, args, logPath: servicePaths(workspaceRoot).loginItemLog, searchPath })
+  return { ...unit, label, digest: sha256(unit.text), program: { node: nodePath, entry: entryPath }, searchPath }
+}
+
+function checkManager(manager, platform) {
+  if (!STARTUP_PLATFORMS.includes(platform)) buildStartupAdapter({ platform })
+  const operations = ['readUnit', 'install', 'start', 'remove', 'inspect']
+  if (manager === null || typeof manager !== 'object' || !operations.every((name) => typeof manager[name] === 'function') || !SERVICE_MANAGER_KINDS.includes(manager.kind)) {
+    throw new TypeError('a login item needs an injected service manager')
+  }
+  if (manager.platform !== platform) throw new TypeError('the service manager is not this platform\'s')
+}
+
+// ---------------------------------------------------------------------------
+// Install, remove, start through it, and what it looks like
+// ---------------------------------------------------------------------------
+
+// Installs, or installs again, this workspace's login item. `consent` ({ actor }) is the person's consent to the
+// service running at login; without it, a recorded consent must already cover startup (`startup-consent-required`).
+// `ownEntry` and `entryArgs` are the entry this command would start and its arguments (`--adapter=...`).
+// `beforeInstall({ entryPath })`, when given, runs once the consent is recorded and before the manager loads the unit,
+// which starts the service at once: the command stops a service of an earlier release there, so that start runs the
+// entry the unit names instead of finding the earlier one running.
+// { installed: true, label, file, kind, entry: { path, source }, node, searchPath } or, when the manager did not take
+// the unit, { installed: false, reason, label } with the consent recorded before, or, when none was, the one just
+// recorded covering the service alone.
+export async function installLoginItem(options = {}) {
+  const { loadProject, dataRoot, env = process.env, platform = process.platform, manager, consent, ownEntry, entryArgs = [], nodePath = realNodePath(), pathValue = env.PATH, clock = () => new Date(), temporary = temporaryRoots(), beforeInstall = null } = options
+  checkManager(manager, platform)
+  const project = loadProject()
+  ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }) })
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create: true })
+  const { entryPath, source } = resolveLoginItemEntry({ project, ownEntry, temporary })
+  const recorded = readLoginItemRecord(workspace)
+  const label = recorded?.label ?? loginItemLabel({ platform, projectName: projectNameOf(project), workspaceId: workspace.workspaceId })
+  const plan = planLoginItem({
+    platform, project, workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId, dataRoot: loginItemDataRoot({ project, dataRoot, env, platform }), label, entryPath, entryArgs, nodePath,
+    searchPath: startupSearchPath(pathValue, { temporary }),
+  })
+
+  // The consent first: the manager starts the service as soon as it loads the unit.
+  const now = isoTime(clock)
+  const before = readServiceSettings(workspace)
+  if (consent === undefined && before?.consent.coverage !== 'service-and-startup') refuse('startup-consent-required', 'a login item needs a consent that covers the service starting at login; name who gives it')
+  if (consent !== undefined && (typeof consent?.actor !== 'string' || consent.actor === '')) refuse('startup-consent-required', 'a consent names its actor')
+  await ensureServiceSettings(workspace, { consent: consent === undefined ? undefined : { actor: consent.actor, coverage: 'service-and-startup' }, now })
+  if (typeof beforeInstall === 'function') await beforeInstall({ entryPath })
+
+  const installed = await manager.install({ label, fileName: plan.fileName, text: plan.text })
+  if (!installed.ok) {
+    restoreConsent(workspace, before, now)
+    return { installed: false, reason: installed.code, label, message: installed.message ?? null }
+  }
+  writeLoginItemRecord({
+    ...workspace,
+    record: { schema: LOGIN_ITEM_SCHEMA, workspaceId: workspace.workspaceId, kind: manager.kind, label, file: installed.file, digest: plan.digest, program: plan.program, searchPath: plan.searchPath, installedAt: recorded?.installedAt ?? now, updatedAt: now },
+  })
+  return { installed: true, label, file: installed.file, kind: manager.kind, entry: { path: entryPath, source }, node: nodePath, searchPath: plan.searchPath }
+}
+
+// Back to the consent that was recorded before an installation the manager refused: the service may still run, as a
+// child, under the consent it had.
+function restoreConsent(workspace, before, now) {
+  const current = readServiceSettings(workspace)
+  if (current === null) return
+  const consent = before?.consent ?? { ...current.consent, coverage: 'service' }
+  if (JSON.stringify(consent) !== JSON.stringify(current.consent)) writeServiceSettings({ ...workspace, settings: { ...current, consent, updatedAt: now } })
+}
+
+// Removes this workspace's login item: the consent is lowered to the service alone first, then the manager unloads
+// and deletes the unit (a service it runs is stopped as it stops it), then the record goes. { removed, label, file }
+// or { removed: false, reason } when the manager kept it.
+export async function removeLoginItem(options = {}) {
+  const { loadProject, dataRoot, env = process.env, platform = process.platform, manager, clock = () => new Date() } = options
+  checkManager(manager, platform)
+  const project = loadProject()
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
+  if (!workspace?.workspaceRoot) return { removed: false, reason: 'workspace-not-prepared' }
+  const record = readLoginItemRecord(workspace)
+  const label = record?.label ?? loginItemLabel({ platform, projectName: projectNameOf(project), workspaceId: workspace.workspaceId })
+  const fileName = record === null ? `${label}${manager.kind === 'launchd-user-agent' ? '.plist' : '.service'}` : path.basename(record.file)
+  const now = isoTime(clock)
+  const settings = readServiceSettings(workspace)
+  if (settings?.consent.coverage === 'service-and-startup') await ensureServiceSettings(workspace, { consent: { actor: settings.consent.actor, coverage: 'service' }, now })
+  const removed = await manager.remove({ label, fileName })
+  if (!removed.ok) return { removed: false, reason: removed.code, label, message: removed.message ?? null }
+  removeLoginItemRecord(workspace)
+  return { removed: removed.removed === true || record !== null, label, file: manager.fileFor(fileName) }
+}
+
+// The unit this workspace's installed login item would have now, keeping its label and the search path recorded when
+// it was installed; null when no entry for it can be found from here (the command runs from a package runner and the
+// project has no package installed): what is installed then stays as it is.
+export function currentLoginItemPlan({ record, project, workspaceRoot, dataRoot, env = process.env, platform, ownEntry, entryArgs = [], nodePath = realNodePath(), temporary = temporaryRoots() }) {
+  try {
+    const { entryPath } = resolveLoginItemEntry({ project, ownEntry, temporary })
+    return planLoginItem({
+      platform, project, workspaceRoot, workspaceId: record.workspaceId, dataRoot: loginItemDataRoot({ project, dataRoot, env, platform }), label: record.label, entryPath, entryArgs, nodePath,
+      searchPath: record.searchPath,
+    })
+  } catch (error) {
+    if (error?.code === 'login-item-needs-installed-package' || error?.code === 'startup-adapter-input-invalid') return null
+    throw error
+  }
+}
+
+// { entryPath, start() } for startService: the entry the item runs, and a start through its manager. The manager is
+// asked first whether the person switched the item off (System Settings, `systemctl --user disable`): one that is off
+// is neither written again, reloaded, enabled nor started (`login-item-switched-off`), and startService starts a child
+// for that command only. A unit that differs from `plan` is written again and reloaded first (the answer then carries
+// `refreshed: true`); a unit whose file is gone was removed by somebody and is not put back.
+export function loginItemStarter({ workspace, manager, record, plan = null, clock = () => new Date() }) {
+  const fileName = path.basename(record.file)
+  let entryPath = record.program.entry
+  return {
+    get entryPath() { return entryPath },
+    async start() {
+      let refreshed = false
+      const text = manager.readUnit({ label: record.label, fileName })
+      if (text === null) return { ok: false, code: 'login-item-file-missing', refreshed }
+      let seen = null
+      try { seen = await manager.inspect({ label: record.label, fileName }) } catch { seen = null }
+      if (seen?.ok === true && seen.disabled === true) return { ok: false, code: 'login-item-switched-off', refreshed }
+      if (plan !== null && plan.fileName === fileName && text !== plan.text) {
+        const installed = await manager.install({ label: record.label, fileName, text: plan.text })
+        if (!installed.ok) return { ok: false, code: installed.code, refreshed }
+        writeLoginItemRecord({ ...workspace, record: { ...record, file: installed.file, digest: plan.digest, program: plan.program, updatedAt: isoTime(clock) } })
+        entryPath = plan.program.entry
+        refreshed = true
+      }
+      const started = await manager.start({ label: record.label, fileName })
+      return { ...started, refreshed, entryPath }
+    },
+  }
+}
+
+// What this workspace's login item looks like: the record, what the manager says about it, and how the last start by
+// it ended. `manager` is a manager, or a function that answers one (asked only when an item is recorded), or null
+// (it cannot be asked from here): the record alone is reported then.
+//   state  loaded | not-loaded | switched-off | file-missing | unknown
+export async function loginItemStatus({ workspace, manager: given = null }) {
+  const lastStartup = (() => { try { return readLastStartup(workspace) } catch { return null } })()
+  let record
+  try { record = readLoginItemRecord(workspace) } catch (error) { return { installed: null, reason: error.code ?? 'invalid-login-item', lastStartup } }
+  if (record === null) return { installed: false, lastStartup }
+  // A unit whose entry or Node is gone cannot start: its manager tries again every minute until it is removed or installed again.
+  const present = (file) => { try { return fs.statSync(file).isFile() } catch { return false } }
+  const shown = {
+    installed: true, label: record.label, file: record.file, kind: record.kind, entry: record.program.entry, node: record.program.node, installedAt: record.installedAt,
+    programPresent: present(record.program.entry) && present(record.program.node), lastStartup,
+  }
+  const manager = typeof given === 'function' ? await given() : given
+  if (manager === null) return { ...shown, state: 'unknown', inspected: false }
+  const fileName = path.basename(record.file)
+  let seen = null
+  try { seen = await manager.inspect({ label: record.label, fileName }) } catch { seen = null }
+  let text = null
+  try { text = manager.readUnit({ label: record.label, fileName }) } catch { text = null }
+  const state = seen === null || seen.ok !== true ? 'unknown'
+    : seen.present === false ? 'file-missing'
+      : seen.disabled === true ? 'switched-off'
+        : seen.loaded === true ? 'loaded'
+          : seen.loaded === false ? 'not-loaded' : 'unknown'
+  return { ...shown, state, inspected: true, running: seen?.running ?? null, pid: seen?.pid ?? null, lastExit: seen?.lastExit ?? null, changedOnDisk: typeof text === 'string' && sha256(text) !== record.digest }
+}

package/src/runtime/obsidian/machine-settings.mjs

@@ -6,12 +6,13 @@ import { LOCAL_STATE_DIR, localStateRoot } from '../../project/config.mjs'
 import { checkManagedRoots } from '../../project/file-class.mjs'
 import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
+import { LOCAL_AUDIENCES } from '../../projection/policy.mjs'
 import { refuse } from './errors.mjs'
 import { canonicalJson, closedObject, isPlainObject } from './documents.mjs'
 
 // Machine-private settings of the Obsidian maintenance runtime.
 //
-//   <data>/obsidian/<workspace-id>/state/settings/machine.json       mode, audiences, policy reference
+//   <data>/obsidian/<workspace-id>/state/settings/machine.json       mode, audiences, policy reference, remembered decisions
 //   <data>/obsidian/<workspace-id>/state/settings/apply-policy.json  the installed apply policy
 //   <project>/.atelier-local/obsidian.json                           pointer: workspace id, optional data root
 //
@@ -22,14 +23,33 @@ import { canonicalJson, closedObject, isPlainObject } from './documents.mjs'
 // checkout keeps its vaults) and, optionally, where this machine keeps the
 // data directory.
 
-export const MACHINE_SETTINGS_SCHEMA = 'atelier-obsidian-machine-settings/v1'
+export const MACHINE_SETTINGS_SCHEMA = 'atelier-obsidian-machine-settings/v2'
+// What releases up to 0.2.0-alpha.12 wrote. It is still read, as the v2 document it stands for, and never written:
+// the next write writes v2. A release that knows only v1 refuses a v2 document, so a downgrade stops, loudly, rather
+// than working from settings it cannot read.
+export const MACHINE_SETTINGS_SCHEMA_V1 = 'atelier-obsidian-machine-settings/v1'
 export const LOCAL_POINTER_SCHEMA = 'atelier-obsidian-local-pointer/v1'
 export const LOCAL_POINTER_FILE = 'obsidian.json'
 export const MAINTENANCE_MODES = Object.freeze(['manual', 'automatic'])
 
+// What a person decided once for this workspace on this machine, so that no later run has to ask again: who may see
+// its vaults, where they live, whether maintenance starts at login, and that the installed app may be reached. Each is
+// null until it is decided.
+export const DECISIONS = Object.freeze(['audience', 'location', 'loginItem', 'adapter'])
+// How a decision was made: answered to a question at a terminal, given on the command line (an operation or a flag),
+// taken as the defaults, or carried over from a v1 document.
+export const DECISION_SOURCES = Object.freeze(['question', 'command', 'defaults', 'v1'])
+// "Only you": every audience of a note, except `sensitive`, which a vault takes only when it is named. A vault is a
+// folder in which the app's community plugins run with full access to its files.
+export const ONLY_YOU_AUDIENCES = Object.freeze(LOCAL_AUDIENCES.filter((audience) => audience !== 'sensitive').sort())
+// Whether the notes that carry no classification enter this workspace's vaults. They may only for "only you": a vault
+// of any other audience never shows them. Withheld unless a person decided otherwise.
+export const UNCLASSIFIED_CHOICES = Object.freeze(['shown', 'withheld'])
+
 const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 const DIGEST = /^sha256:[0-9a-f]{64}$/
 const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+const CONTROL = /[\u0000-\u001f\u007f]/
 
 const segment = (identifier) => identifier.replaceAll(':', '_')
 
@@ -138,9 +158,9 @@ export function ensureWorkspaceIdentity({ project, dataRoot, randomBytes = crypt
 // Machine settings
 // ---------------------------------------------------------------------------
 
-function validateMachineSettings(document, workspaceId) {
-  closedObject(document, { required: ['schema', 'workspaceId', 'maintenanceMode', 'audienceAllow', 'applyPolicy', 'updatedAt'] }, 'invalid-machine-settings', 'machine settings')
-  if (document.schema !== MACHINE_SETTINGS_SCHEMA) refuse('invalid-machine-settings', 'machine settings name an unknown schema')
+const MACHINE_FIELDS = Object.freeze(['schema', 'workspaceId', 'maintenanceMode', 'audienceAllow', 'applyPolicy', 'updatedAt'])
+
+function validateCommonFields(document, workspaceId) {
   if (document.workspaceId !== workspaceId) refuse('invalid-machine-settings', 'machine settings belong to another workspace')
   if (!MAINTENANCE_MODES.includes(document.maintenanceMode)) refuse('invalid-machine-settings', 'maintenanceMode must be manual or automatic')
   if (!Array.isArray(document.audienceAllow) || document.audienceAllow.length > 64 || document.audienceAllow.some((item) => typeof item !== 'string' || !IDENTIFIER.test(item))
@@ -155,29 +175,116 @@ function validateMachineSettings(document, workspaceId) {
     }
   }
   if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse('invalid-machine-settings', 'updatedAt must be a UTC timestamp')
+}
+
+const isOneOf = (values) => (value) => values.includes(value)
+const isAbsoluteDirectory = (value) => typeof value === 'string' && value.length <= 4096 && !CONTROL.test(value) && path.isAbsolute(value) && path.resolve(value) === value
+// The members of each decision besides its stamp, and what each may hold. A decision gains a member here, and a
+// document that carries it is refused by a release that does not know it, loudly.
+const DECISION_MEMBERS = Object.freeze({
+  audience: Object.freeze({ choice: isOneOf(['only-you', 'custom']), unclassified: isOneOf(UNCLASSIFIED_CHOICES) }),
+  location: Object.freeze({ parent: isAbsoluteDirectory }),
+  loginItem: Object.freeze({ choice: isOneOf(['on', 'off']) }),
+  adapter: Object.freeze({ choice: isOneOf(['obsidian-cli']) }),
+})
+function sameMembers(left, right) {
+  const [sortedLeft, sortedRight] = [[...left].sort(), [...right].sort()]
+  return sortedLeft.length === sortedRight.length && sortedLeft.every((item, index) => item === sortedRight[index])
+}
+
+// `deciding` is true when the audience decision is being recorded (withDecision). Only then must "only you" be exactly
+// the set this release stands for. Read, or written back by any other change, an "only you" list is the one recorded
+// when it was decided: any part of this release's set, never `sensitive` and never an audience this release does not
+// know. So a later release that adds an audience to "only you" still reads what an earlier one recorded, and
+// `audience set me` records the current set again.
+function validateDecisions(document, { deciding = false } = {}) {
+  const code = 'invalid-machine-settings'
+  closedObject(document.decisions, { required: DECISIONS }, code, 'the remembered decisions')
+  for (const name of DECISIONS) {
+    const decision = document.decisions[name]
+    if (decision === null) continue
+    const members = DECISION_MEMBERS[name]
+    closedObject(decision, { required: [...Object.keys(members), 'decidedAt', 'decidedBy', 'via'] }, code, `the ${name} decision`)
+    for (const [member, holds] of Object.entries(members)) if (!holds(decision[member])) refuse(code, `the ${name} decision carries an unknown ${member}`)
+    if (typeof decision.decidedAt !== 'string' || !TIMESTAMP.test(decision.decidedAt)) refuse(code, `the ${name} decision needs a UTC time`)
+    // Who decided, when it is known: an identifier, or null.
+    if (decision.decidedBy !== null && (typeof decision.decidedBy !== 'string' || !IDENTIFIER.test(decision.decidedBy))) refuse(code, `the ${name} decision names who decided as an identifier or null`)
+    if (!DECISION_SOURCES.includes(decision.via)) refuse(code, `the ${name} decision says how it was made`)
+  }
+  // "Only you" is a set of audiences, and the list the engine reads is exactly that set when it is decided.
+  if (document.decisions.audience?.choice === 'only-you') {
+    const recorded = document.audienceAllow.length > 0 && document.audienceAllow.every((audience) => ONLY_YOU_AUDIENCES.includes(audience))
+    if (deciding ? !sameMembers(document.audienceAllow, ONLY_YOU_AUDIENCES) : !recorded) refuse(code, 'the audiences allowed are not the ones "only you" stands for')
+  }
+  if (document.decisions.audience?.unclassified === 'shown' && document.decisions.audience.choice !== 'only-you') {
+    refuse(code, 'notes without a classification are shown only in a vault that is only yours')
+  }
+}
+
+function validateV1(document, workspaceId) {
+  closedObject(document, { required: MACHINE_FIELDS }, 'invalid-machine-settings', 'machine settings')
+  validateCommonFields(document, workspaceId)
   return document
 }
 
-// The defaults fail closed: edits are only queued, no audience is visible and
-// no apply policy is installed until the person says otherwise.
+function validateV2(document, workspaceId, { deciding = false } = {}) {
+  closedObject(document, { required: [...MACHINE_FIELDS, 'decisions'] }, 'invalid-machine-settings', 'machine settings')
+  if (document.schema !== MACHINE_SETTINGS_SCHEMA) refuse('invalid-machine-settings', 'machine settings name an unknown schema')
+  validateCommonFields(document, workspaceId)
+  validateDecisions(document, { deciding })
+  return document
+}
+
+// A v1 document as the v2 document it stands for. Nothing was remembered then, except that a list of audiences a
+// person set (`audience set`) is their decision, and is carried over as one, with the notes that carry no
+// classification withheld as they were; who made it is not known.
+function fromV1(document) {
+  const { schema: _v1, ...fields } = document
+  const audience = fields.audienceAllow.length === 0 ? null : { choice: 'custom', unclassified: 'withheld', decidedAt: fields.updatedAt, decidedBy: null, via: 'v1' }
+  return { ...fields, schema: MACHINE_SETTINGS_SCHEMA, decisions: { audience, location: null, loginItem: null, adapter: null } }
+}
+
+// Every document this module reads or is handed, as a validated v2 document.
+function normalizeMachineSettings(document, workspaceId) {
+  if (isPlainObject(document) && document.schema === MACHINE_SETTINGS_SCHEMA_V1) return validateV2(fromV1(validateV1(document, workspaceId)), workspaceId)
+  return validateV2(document, workspaceId)
+}
+
+// The defaults fail closed: edits are only queued, no audience is visible,
+// no apply policy is installed and nothing is decided until the person says
+// otherwise.
 export function defaultMachineSettings({ workspaceId, updatedAt }) {
-  return { schema: MACHINE_SETTINGS_SCHEMA, workspaceId, maintenanceMode: 'manual', audienceAllow: [], applyPolicy: null, updatedAt }
+  return {
+    schema: MACHINE_SETTINGS_SCHEMA, workspaceId, maintenanceMode: 'manual', audienceAllow: [], applyPolicy: null,
+    decisions: Object.fromEntries(DECISIONS.map((name) => [name, null])), updatedAt,
+  }
+}
+
+// The settings with one decision recorded, validated; nothing is written. `decision` holds the decision's own members
+// (`{ choice, unclassified }`, `{ parent }`, `{ choice }`); the stamp says when, by whom (an identifier, or null when not
+// known) and how.
+export function withDecision(settings, name, decision, { decidedAt, decidedBy = null, via }) {
+  if (!DECISIONS.includes(name)) throw new TypeError(`unknown decision: ${String(name)}`)
+  const next = { ...settings, decisions: { ...settings.decisions, [name]: { ...decision, decidedAt, decidedBy, via } } }
+  return validateV2(next, settings.workspaceId, { deciding: name === 'audience' })
 }
 
 const settingsDirectory = (workspaceRoot) => ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, 'state', 'settings'), label: 'Obsidian machine settings' })
 const settingsFile = (workspaceRoot, name) => path.join(workspaceRoot, 'state', 'settings', name)
 
+// A v1 document is returned as v2 (see fromV1); the file keeps its v1 bytes until the next write.
 export function readMachineSettings({ workspaceRoot, workspaceId }) {
   const document = readJsonFile(settingsFile(workspaceRoot, 'machine.json'), 'invalid-machine-settings', 'machine settings')
-  return document === null ? null : validateMachineSettings(document, workspaceId)
+  return document === null ? null : normalizeMachineSettings(document, workspaceId)
 }
 
+// Writes v2, whatever version it is handed, and returns what it wrote.
 export function writeMachineSettings({ workspaceRoot, workspaceId, settings, repositoryRoots }) {
-  validateMachineSettings(settings, workspaceId)
+  const document = normalizeMachineSettings(settings, workspaceId)
   assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
-  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'machine.json'), canonicalJson(settings))
-  return settings
+  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'machine.json'), canonicalJson(document))
+  return document
 }
 
 // ---------------------------------------------------------------------------