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

package/src/runtime/obsidian/index.mjs

@@ -0,0 +1,34 @@
+// Continuous maintenance of Obsidian views: typed enablement, private machine
+// settings, observation by digest, pending edits and per-view freshness.
+// The engine starts no process, timer or listener; `tick()` is explicit. The
+// owned lifecycle (start / status / stop of one loopback service per
+// workspace) is separate, below, and is the only thing here that does.
+export { ObsidianMaintenanceRefusal } from './errors.mjs'
+export { DISABLED_REASONS, ENABLEMENT_STATES, readObsidianEnablement } from './enablement.mjs'
+export {
+  LOCAL_POINTER_SCHEMA, MACHINE_SETTINGS_SCHEMA, MAINTENANCE_MODES, authorizeAutomaticApply, defaultDataRoot, defaultMachineSettings, ensureWorkspaceIdentity,
+  installApplyPolicy, localPointerPath, protectedRoots, readInstalledApplyPolicy, readLocalPointer, readMachineSettings, resolveDataRoot, revokeApplyPolicy, workspaceStateRoot, writeLocalPointer, writeMachineSettings,
+} from './machine-settings.mjs'
+export { APPLY_RESULT_STATUSES, BUILT_IN_OPERATIONS, EXTENSION_KINDS, REPLACEABLE_OPERATIONS, UNAVAILABLE_APPLY_OPERATION, createCommandOperations, createMaintenanceExtensions, createObsidianRegistry } from './extension-points.mjs'
+export { CONTRIBUTIONS_DIRECTORY, loadContributions } from './contributions.mjs'
+export { APP_OUTCOMES, MINIMUM_APP_VERSION, compareAppVersions, createQualifiedAdapterFactory, meetsMinimumAppVersion, parseAppVersion, qualifyApp } from './app-capability.mjs'
+export { OPENING_OUTCOMES, describeOutcome, openScope, scopeReport } from './opening.mjs'
+export {
+  CHANGE_CLASSES, CLOSED_EDIT_STATES, EDIT_STATES, FRESHNESS_SCHEMA, FRESHNESS_STATES, LATE_WRITERS_SCHEMA, OPEN_EDIT_STATES, PENDING_EDITS_SCHEMA,
+  createMaintenanceStateStore, validateFreshness, validateLateWriters, validatePendingEdits,
+} from './state-store.mjs'
+export { listConfigFiles, listSourceFiles, listVaultNotes, reconcile } from './observation.mjs'
+export { createFsWatcherFactory, createNullWatcherFactory } from './watchers.mjs'
+export { DEFAULT_ELIGIBILITY, assetEligibilityFor, createProductionSeams } from './pipeline.mjs'
+export { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, DEFAULT_LATE_WRITER_WINDOW_MS, DEFAULT_RETRY_INTERVAL_MS, createMaintenanceEngine } from './engine.mjs'
+export { ENGINE_LOCK_DIRECTORY, LOCK_TICKET_SCHEMA, acquirePrivateGenerationLock, createAbandonmentProof, inspectPrivateGenerationLock } from './private-lock.mjs'
+export { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
+export { HEALTH_SCHEMA, LOOPBACK_HOSTS, probeHealth, requestLoopback } from './service-client.mjs'
+export {
+  CONSENT_COVERAGES, SERVICE_ERROR_SCHEMA, SERVICE_SETTINGS_SCHEMA, executableIdentity, publicRecord, readLastServiceError, readServiceRecord, readServiceSettings,
+  removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
+} from './service-record.mjs'
+export { MAX_REQUEST_BYTES, SERVICE_OPERATIONS, createServiceServer } from './service-server.mjs'
+export { DEFAULT_SHUTDOWN_GRACE_MS, SERVICE_STATUS_SCHEMA, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
+export { DEFAULT_START_TIMEOUT_MS, DEFAULT_STOP_TIMEOUT_MS, SERVICE_STATES, readServiceStatusDocument, requestServiceTick, serviceStatus, startService, stopService } from './lifecycle.mjs'
+export { STARTUP_PLATFORMS, buildStartupAdapter } from './startup-adapters.mjs'

package/src/runtime/obsidian/lifecycle.mjs

@@ -0,0 +1,258 @@
+import childProcess from 'node:child_process'
+import { randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import net from 'node:net'
+import { isoTime } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { ensureWorkspaceIdentity } from './machine-settings.mjs'
+import { acquirePrivateGenerationLock, createAbandonmentProof, isProcessAlive } from './private-lock.mjs'
+import { processRunsRecordedExecutable } from './process-identity.mjs'
+import { DEFAULT_PROBE_TIMEOUT_MS, LOOPBACK_HOSTS, probeHealth, requestLoopback } from './service-client.mjs'
+import { SERVICE_ENTRY_PATH } from './service-entry-path.mjs'
+import {
+  CONSENT_COVERAGES, SERVICE_SETTINGS_SCHEMA, executableIdentity, openServiceLog, publicRecord, readServiceRecord, readServiceSettings, removeServiceRecord,
+  serviceNameFor, servicePaths, writeServiceSettings,
+} from './service-record.mjs'
+import { resolveServiceWorkspace } from './service.mjs'
+
+// start / status / stop of the maintenance service of one workspace, as
+// docs/local-services.md describes them.
+//
+// Ownership is proven, never assumed. A running service is ours only when the
+// owner-only record and the health answer agree on service name, workspace,
+// runtime identifier, PID, executable digest and literal loopback address,
+// and that PID is alive. Anything else that answers on the port is
+// `occupied`: it is not adopted, not stopped and not replaced. One case is
+// told apart from it: a listener that accepts and does not answer in time
+// while the recorded PID is alive and provably runs the recorded executable is
+// our own service in a long tick. That is `busy`: never adopted, never
+// stopped and never started over; it is simply asked again later. A record whose
+// address refuses connections is `stale-record` when its PID is gone and
+// `pid-not-ours` when that PID is alive (the number was reused, or a process
+// outlived its listener): such a PID is never signalled.
+//
+// Nothing here looks a process up by port, name or pattern, and nothing here
+// removes anything but the one generated record.
+
+export const SERVICE_STATES = Object.freeze(['stopped', 'healthy', 'busy', 'occupied', 'stale-record', 'pid-not-ours'])
+export const DEFAULT_START_TIMEOUT_MS = 20 * 1000
+export const DEFAULT_STOP_TIMEOUT_MS = 45 * 1000
+
+const AGREEMENT = ['serviceName', 'workspaceId', 'runtimeId', 'pid', 'host', 'port']
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) })
+
+// The decisions the lifecycle oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
+export const LIFECYCLE_PRIMITIVES = Object.freeze({
+  // Every field the record and the health answer must agree on; the names of those that differ.
+  disagreements(record, health) {
+    const differing = AGREEMENT.filter((field) => record[field] !== health[field])
+    if (record.executable.digest !== health.executableDigest) differing.push('executableDigest')
+    return differing
+  },
+  // Whether start may report a running service as this workspace's own instead of creating one.
+  isOurs: (status) => status.state === 'healthy',
+  // Whether start gives up because something unproven answers on the port.
+  refusesOccupied: (status) => status.state === 'occupied',
+  // Whether a stop may be sent at all.
+  mayStop: (status) => status.state === 'healthy',
+  // Whether the live recorded PID provably runs the recorded executable, when health did not answer in time.
+  provesOurProcess: (record) => processRunsRecordedExecutable(record),
+})
+
+function context({ loadProject, dataRoot, env, platform, create = false, randomBytes }) {
+  if (typeof loadProject !== 'function') throw new TypeError('the service lifecycle needs loadProject')
+  const project = loadProject()
+  if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}) })
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create })
+  return { project, workspace }
+}
+
+async function evaluate({ workspaceRoot, workspaceId }, { probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS, alive = isProcessAlive, rules = LIFECYCLE_PRIMITIVES } = {}) {
+  // A malformed or foreign record refuses right here, typed; it is never repaired and never adopted.
+  const record = readServiceRecord({ workspaceRoot, workspaceId })
+  const settings = readServiceSettings({ workspaceRoot, workspaceId })
+  const address = record ? { host: record.host, port: record.port } : settings ? { host: settings.host, port: settings.port } : null
+  const base = { workspaceId, serviceName: serviceNameFor(workspaceId), address, record, logPath: servicePaths(workspaceRoot).log }
+  if (address === null) return { ...base, state: 'stopped', reason: 'never-started' }
+  const answer = await probeHealth({ ...address, timeoutMs: probeTimeoutMs })
+  if (record === null) return answer.kind === 'refused' ? { ...base, state: 'stopped', reason: 'no-record-and-nothing-listens' } : { ...base, state: 'occupied', reason: 'a-listener-without-a-record', answer: answer.kind }
+  if (answer.kind === 'refused') return alive(record.pid) ? { ...base, state: 'pid-not-ours', reason: 'recorded-pid-is-alive-but-nothing-listens' } : { ...base, state: 'stale-record', reason: 'recorded-pid-is-gone' }
+  // Only a timeout can be a busy service: a refusal, a foreign answer or a failed connection never is.
+  if (answer.kind === 'timeout' && alive(record.pid) && rules.provesOurProcess(record) === true) return { ...base, state: 'busy', reason: 'our-service-did-not-answer-health-in-time', answer: answer.kind }
+  if (answer.kind !== 'health') return { ...base, state: 'occupied', reason: answer.kind === 'timeout' ? 'listener-did-not-answer-in-time' : 'listener-is-not-this-service', answer: answer.kind }
+  const differing = rules.disagreements(record, answer.body)
+  if (differing.length > 0) return { ...base, state: 'occupied', reason: 'health-identity-differs', disagreements: differing }
+  if (!alive(record.pid)) return { ...base, state: 'occupied', reason: 'recorded-pid-is-gone-but-something-answers' }
+  return { ...base, state: 'healthy', reason: 'record-and-health-agree', health: answer.body }
+}
+
+const shown = ({ record, ...status }) => ({ ...status, record: publicRecord(record) })
+
+export async function serviceStatus({ loadProject, dataRoot, env = process.env, platform = process.platform, probeTimeoutMs, alive } = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  if (!workspace?.workspaceRoot) return { state: 'stopped', reason: 'workspace-not-prepared', workspaceId: workspace?.workspaceId ?? null, record: null, address: null }
+  return shown(await evaluate(workspace, { probeTimeoutMs, alive, rules }))
+}
+
+// A port nobody listens on right now, chosen once and then recorded, so later starts, status and an installed unit all name the same one.
+function freeLoopbackPort(host) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once('error', reject)
+    server.listen({ host, port: 0, exclusive: true }, () => { const { port } = server.address(); server.close(() => resolve(port)) })
+  })
+}
+
+async function resolveSettings({ workspaceRoot, workspaceId }, { host, port, consent, now }) {
+  const current = readServiceSettings({ workspaceRoot, workspaceId })
+  if (host !== undefined && !LOOPBACK_HOSTS.includes(host)) refuse('service-address-not-loopback', 'the service host must be the literal 127.0.0.1 or ::1')
+  if (port !== undefined && (!Number.isInteger(port) || port < 1024 || port > 65535)) refuse('service-address-not-loopback', 'the service port must be between 1024 and 65535')
+  if (consent !== undefined && (typeof consent?.actor !== 'string' || !CONSENT_COVERAGES.includes(consent.coverage ?? 'service'))) refuse('startup-consent-required', 'a consent names its actor and what it covers')
+  if (current === null && consent === undefined) refuse('startup-consent-required', 'the first start of this workspace needs an explicit consent naming its actor')
+  const nextHost = host ?? current?.host ?? '127.0.0.1'
+  const next = {
+    schema: SERVICE_SETTINGS_SCHEMA, workspaceId, host: nextHost, port: port ?? (current && current.host === nextHost ? current.port : await freeLoopbackPort(nextHost)),
+    consent: consent === undefined || (current && current.consent.actor === consent.actor && current.consent.coverage === (consent.coverage ?? 'service')) ? current.consent : { grantedAt: now, actor: consent.actor, coverage: consent.coverage ?? 'service' },
+    updatedAt: now,
+  }
+  const changed = current === null || ['host', 'port'].some((key) => current[key] !== next[key]) || current.consent !== next.consent
+  return changed ? writeServiceSettings({ workspaceRoot, workspaceId, settings: next }) : current
+}
+
+export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const {
+    loadProject, dataRoot, host, port, consent, detached = false, entryPath = SERVICE_ENTRY_PATH, entryArgs = [], intervalMs,
+    startTimeoutMs = DEFAULT_START_TIMEOUT_MS, probeTimeoutMs, clock = () => new Date(), env = process.env, platform = process.platform,
+    spawn = childProcess.spawn, execPath = process.execPath, alive = isProcessAlive, randomBytes = cryptoRandomBytes,
+  } = options
+  const { project, workspace } = context({ loadProject, dataRoot, env, platform, create: true })
+  const { workspaceRoot, workspaceId } = workspace
+  const deadline = Date.now() + startTimeoutMs
+
+  // One start at a time per workspace. A start is bounded by its own deadline, so a holder far older than that is gone.
+  const proveAbandoned = createAbandonmentProof({ alive, maxAgeMs: startTimeoutMs * 4 })
+  let lock
+  for (;;) {
+    lock = await acquirePrivateGenerationLock({ workspaceRoot, directory: servicePaths(workspaceRoot).startLock, workspaceId, purpose: 'service-start', clock, proveAbandoned })
+    if (lock.acquired) break
+    const meanwhile = await evaluate(workspace, { probeTimeoutMs, alive, rules })
+    if (rules.isOurs(meanwhile)) return { ...shown(meanwhile), started: false, alreadyRunning: true }
+    if (meanwhile.state === 'busy') return { ...shown(meanwhile), started: false, alreadyRunning: true, busy: true }
+    if (Date.now() >= deadline) refuse('service-start-in-progress', 'another start of this workspace holds the start lock', { reason: lock.reason })
+    await sleep(100)
+  }
+
+  let child = null
+  try {
+    const before = await evaluate(workspace, { probeTimeoutMs, alive, rules })
+    if (rules.isOurs(before)) return { ...shown(before), started: false, alreadyRunning: true }
+    // Running, and in a long tick: nothing is started beside it and nothing replaces it.
+    if (before.state === 'busy') return { ...shown(before), started: false, alreadyRunning: true, busy: true }
+    if (rules.refusesOccupied(before)) refuse('service-port-occupied', 'something that is not this service answers on the loopback port; it is never taken over', { reason: before.reason, address: before.address })
+    // `stale-record` and `pid-not-ours`: nothing listens, so the recorded runtime is not serving. Its PID is never signalled;
+    // the new service replaces the record once it listens. Nothing under recovery or staging is touched on the way.
+    const settings = await resolveSettings(workspace, { host, port, consent, now: isoTime(clock) })
+    if (before.address && (before.address.host !== settings.host || before.address.port !== settings.port)) {
+      const moved = await probeHealth({ host: settings.host, port: settings.port, timeoutMs: probeTimeoutMs })
+      if (moved.kind !== 'refused') refuse('service-port-occupied', 'something already answers on the selected loopback port; it is never taken over', { address: { host: settings.host, port: settings.port } })
+    }
+
+    const runtimeId = `rt-${randomBytes(16).toString('hex')}`
+    const executable = executableIdentity(entryPath)
+    const log = openServiceLog(workspaceRoot)
+    try {
+      const args = [executable.path, `--project=${project.configPath}`, ...(dataRoot === undefined ? [] : [`--data-root=${dataRoot}`]), `--runtime-id=${runtimeId}`, ...(intervalMs === undefined ? [] : [`--interval-ms=${intervalMs}`]), ...entryArgs]
+      // No shell. Detached only when the service is meant to outlive the command that starts it.
+      child = spawn(execPath, args, { detached, shell: false, windowsHide: true, stdio: ['ignore', log.descriptor, log.descriptor], env })
+    } finally {
+      fs.closeSync(log.descriptor)
+    }
+    let exited = null
+    child.once('exit', (code, signal) => { exited = { code, signal } })
+    child.once('error', (error) => { exited = { code: null, signal: null, error: error.code ?? 'spawn-failed' } })
+
+    // Health must echo the runtime identifier generated here and the PID of the child created here.
+    let last = null
+    while (Date.now() < deadline && exited === null) {
+      last = await evaluate(workspace, { probeTimeoutMs, alive, rules }).catch((error) => ({ state: 'refused', reason: error.code ?? 'untyped-error' }))
+      if (last.state === 'healthy' && last.record.runtimeId === runtimeId && last.record.pid === child.pid) {
+        if (detached) child.unref()
+        return { ...shown(last), started: true, alreadyRunning: false, ...(detached ? {} : { child }) }
+      }
+      await sleep(50)
+    }
+    // The child created here wrote the record and went straight into a long first tick: it runs, and is not stopped.
+    if (exited === null && last?.state === 'busy' && last.record?.runtimeId === runtimeId && last.record?.pid === child.pid) {
+      if (detached) child.unref()
+      return { ...shown(last), started: true, alreadyRunning: false, busy: true, ...(detached ? {} : { child }) }
+    }
+    // Ownership was never proven: only the child created here is stopped, by its handle.
+    if (exited === null) { child.kill(); const until = Date.now() + 5000; while (exited === null && Date.now() < until) await sleep(25) }
+    removeServiceRecord({ workspaceRoot, workspaceId, runtimeId, pid: child.pid })
+    return { state: 'start-failed', started: false, alreadyRunning: false, workspaceId, reason: exited?.error ?? (exited?.code === null || exited === null ? 'health-never-proved-ownership' : `service-exited-${exited.code}`), observed: last?.state ?? null, logPath: log.file }
+  } finally {
+    lock.release()
+  }
+}
+
+export async function stopService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const { loadProject, dataRoot, stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive, force = false, kill = process.kill.bind(process) } = options
+  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  if (!workspace?.workspaceRoot) return { state: 'stopped', stopped: false, refused: false, reason: 'workspace-not-prepared' }
+  const { workspaceRoot, workspaceId } = workspace
+  const status = await evaluate(workspace, { probeTimeoutMs, alive, rules })
+  if (status.state === 'stopped') return { ...shown(status), stopped: false, refused: false }
+  // Any disagreement refuses. Nothing is signalled, and the record stays for a person to look at.
+  if (status.state === 'busy') return { ...shown(status), stopped: false, refused: true, retry: true, reason: 'service-is-busy-ask-again-later' }
+  if (!rules.mayStop(status)) return { ...shown(status), stopped: false, refused: true }
+
+  const { record } = status
+  const answer = await requestLoopback({ host: record.host, port: record.port, method: 'POST', path: '/stop', bearer: record.ext.bearer, payload: { runtimeId: record.runtimeId }, timeoutMs: Math.max(probeTimeoutMs ?? 0, 2 * DEFAULT_PROBE_TIMEOUT_MS) })
+  const accepted = answer.kind === 'response' && answer.statusCode === 202 && answer.body?.runtimeId === record.runtimeId && answer.body?.pid === record.pid
+  if (!accepted) return { ...shown(status), stopped: false, refused: true, reason: 'stop-was-not-accepted-by-the-proven-runtime' }
+  const until = Date.now() + stopTimeoutMs
+  while (alive(record.pid) && Date.now() < until) await sleep(50)
+  if (alive(record.pid)) {
+    // Escalation is opt-in and proven again first: the same runtime and PID must still answer.
+    const again = force ? await evaluate(workspace, { probeTimeoutMs, alive, rules }).catch(() => null) : null
+    if (!(again?.state === 'healthy' && again.record.runtimeId === record.runtimeId && again.record.pid === record.pid)) return { ...shown(status), stopped: false, refused: true, reason: 'stop-timed-out' }
+    kill(record.pid, 'SIGKILL')
+    while (alive(record.pid) && Date.now() < until + 5000) await sleep(50)
+  }
+  // The service removes its own record on the way out; after a hard end it is removed here, and only if it still names that runtime.
+  removeServiceRecord({ workspaceRoot, workspaceId, runtimeId: record.runtimeId, pid: record.pid })
+  return { state: 'stopped', stopped: true, refused: false, reason: 'stopped-the-proven-runtime', workspaceId, runtimeId: record.runtimeId, pid: record.pid }
+}
+
+// One authenticated request to the proven runtime, and to nothing else: anything but a healthy status is answered
+// with that status and no request is made.
+async function askProvenRuntime(options, rules, { method, operation, timeoutMs }) {
+  const { loadProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
+  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  if (!workspace?.workspaceRoot) return { requested: false, state: 'stopped', reason: 'workspace-not-prepared' }
+  const status = await evaluate(workspace, { probeTimeoutMs, alive, rules })
+  if (status.state !== 'healthy') return { requested: false, state: status.state, reason: status.reason }
+  const { record } = status
+  const answer = await requestLoopback({ host: record.host, port: record.port, method, path: operation, bearer: record.ext.bearer, payload: method === 'POST' ? { runtimeId: record.runtimeId } : null, timeoutMs })
+  return { requested: true, state: 'healthy', answer }
+}
+
+// Asks the proven runtime for one tick now and returns what that tick reported. A tick that outlasts the wait is
+// `pending`, not an error.
+export async function requestServiceTick(options = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const asked = await askProvenRuntime(options, rules, { method: 'POST', operation: '/tick', timeoutMs: options.tickTimeoutMs ?? 60 * 1000 })
+  if (!asked.requested) return asked
+  const { answer } = asked
+  if (answer.kind === 'timeout') return { requested: true, state: 'healthy', pending: true, tick: null, reason: 'tick-still-running' }
+  if (answer.kind !== 'response' || answer.statusCode !== 200 || answer.body === null) return { requested: true, state: 'healthy', pending: false, tick: null, reason: 'tick-was-not-answered' }
+  return { requested: true, state: 'healthy', pending: false, tick: answer.body, reason: 'tick-ran' }
+}
+
+// The status document of the proven runtime: loop, last tick, last error code, freshness summary and, where the
+// service qualifies an app, what it last learned about it. Null when it did not answer.
+export async function readServiceStatusDocument(options = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const asked = await askProvenRuntime(options, rules, { method: 'GET', operation: '/status', timeoutMs: options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS })
+  if (!asked.requested) return { ...asked, document: null }
+  const { answer } = asked
+  return { requested: true, state: 'healthy', document: answer.kind === 'response' && answer.statusCode === 200 ? answer.body : null }
+}

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

@@ -0,0 +1,260 @@
+import { randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+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 { 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/apply-policy.json  the installed apply policy
+//   <project>/.atelier-local/obsidian.json                           pointer: workspace id, optional data root
+//
+// Nothing here is project configuration and nothing here is ever serialized
+// into a note. The data directory sits outside every enrolled repository. The
+// pointer is the one ignored file a project gains: it holds the persisted
+// random workspace identity (never a hash of a checkout path, so moving a
+// 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 LOCAL_POINTER_SCHEMA = 'atelier-obsidian-local-pointer/v1'
+export const LOCAL_POINTER_FILE = 'obsidian.json'
+export const MAINTENANCE_MODES = Object.freeze(['manual', 'automatic'])
+
+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 segment = (identifier) => identifier.replaceAll(':', '_')
+
+// ---------------------------------------------------------------------------
+// Where the data directory is
+// ---------------------------------------------------------------------------
+
+// Pure: computes a path from its arguments and touches nothing.
+export function defaultDataRoot({ platform = process.platform, env = process.env, homedir = os.homedir() } = {}) {
+  const flavor = platform === 'win32' ? path.win32 : path.posix
+  const absolute = (value) => typeof value === 'string' && value !== '' && flavor.isAbsolute(value)
+  if (platform === 'win32') {
+    if (!absolute(env.LOCALAPPDATA)) refuse('data-root-unresolvable', 'LOCALAPPDATA does not name an absolute directory')
+    return flavor.join(env.LOCALAPPDATA, 'Atelier')
+  }
+  if (!absolute(homedir)) refuse('data-root-unresolvable', 'the home directory is not an absolute path')
+  if (platform === 'darwin') return flavor.join(homedir, 'Library', 'Application Support', 'Atelier')
+  // A relative XDG_DATA_HOME is invalid by its specification and is ignored.
+  return flavor.join(absolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : flavor.join(homedir, '.local', 'share'), 'atelier')
+}
+
+// The data root for this run: an injected root, else the project's pointer,
+// else the local overlay preference, else the platform default. Pure. Under
+// the Node test runner the platform default refuses, so a test that forgot to
+// inject a root can never reach a person's real data directory.
+export function resolveDataRoot({ dataRoot, pointer = null, project = null, platform = process.platform, env = process.env, homedir } = {}) {
+  const preference = project?.localOverlay?.overlay?.preferences?.[OBSIDIAN_EXT_KEY]
+  const configured = dataRoot ?? pointer?.dataRoot ?? (isPlainObject(preference) ? preference.dataRoot : undefined)
+  if (configured !== undefined) {
+    if (typeof configured !== 'string' || !path.isAbsolute(configured)) refuse('data-root-not-absolute', 'a configured data root must be an absolute path')
+    return path.resolve(configured)
+  }
+  if (env.NODE_TEST_CONTEXT !== undefined) refuse('real-data-root-under-test', 'the platform data directory is never used under the test runner; inject a data root')
+  return defaultDataRoot({ platform, env, ...(homedir === undefined ? {} : { homedir }) })
+}
+
+export function workspaceStateRoot(dataRoot, workspaceId) {
+  if (typeof workspaceId !== 'string' || !IDENTIFIER.test(workspaceId)) refuse('invalid-workspace-identity', 'a workspace identity must be a contract identifier')
+  return path.join(dataRoot, 'obsidian', segment(workspaceId))
+}
+
+// Every enrolled repository root plus the directories the project itself
+// occupies. Private state may overlap none of them, in either direction.
+export function protectedRoots(project) {
+  const roots = new Set()
+  for (const repo of project?.repos ?? []) if (!repo.external && typeof repo.path === 'string') roots.add(path.resolve(repo.path))
+  if (typeof project?.configDir === 'string') roots.add(path.resolve(project.configDir))
+  return [...roots].sort()
+}
+
+export function assertOutsideRepositories({ managedRoot, repositoryRoots }) {
+  const guard = checkManagedRoots({ managedRoots: [managedRoot], repositoryRoots })
+  if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals.map(({ code }) => code) })
+}
+
+// ---------------------------------------------------------------------------
+// The pointer a project keeps in its ignored local state
+// ---------------------------------------------------------------------------
+
+function validatePointer(document) {
+  closedObject(document, { required: ['schema', 'workspaceId'], optional: ['dataRoot'] }, 'invalid-local-pointer', 'the Obsidian pointer')
+  if (document.schema !== LOCAL_POINTER_SCHEMA) refuse('invalid-local-pointer', 'the Obsidian pointer names an unknown schema')
+  if (typeof document.workspaceId !== 'string' || !IDENTIFIER.test(document.workspaceId)) refuse('invalid-local-pointer', 'the Obsidian pointer carries no usable workspace identity')
+  if (document.dataRoot !== undefined && (typeof document.dataRoot !== 'string' || !path.isAbsolute(document.dataRoot))) {
+    refuse('invalid-local-pointer', 'the Obsidian pointer names a data root that is not an absolute path')
+  }
+  return document
+}
+
+export const localPointerPath = (project) => path.join(localStateRoot(project), LOCAL_POINTER_FILE)
+
+function readJsonFile(file, code, label) {
+  let text
+  try { text = readRegularTextNoFollow(file) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    refuse(code, `${label} cannot be read`, { cause: error.code ?? String(error.message) })
+  }
+  try { return JSON.parse(text) } catch { return refuse(code, `${label} is not JSON`) }
+}
+
+export function readLocalPointer(project) {
+  const document = readJsonFile(localPointerPath(project), 'invalid-local-pointer', 'the Obsidian pointer')
+  return document === null ? null : validatePointer(document)
+}
+
+// The pointer is written only where the project's local state is proven
+// ignored, so a machine-local value can never be committed by accident.
+export function writeLocalPointer(project, pointer) {
+  validatePointer(pointer)
+  if (project?.localState?.ignored !== true) refuse('local-state-not-ignored', `${LOCAL_STATE_DIR}/ is not ignored in this project; the Obsidian pointer is not written`)
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: project.configDir, directory: localStateRoot(project), label: 'project local state' })
+  atomicReplacePrivateText(path.join(directory, LOCAL_POINTER_FILE), canonicalJson(pointer))
+  return pointer
+}
+
+// Reads the persisted workspace identity, or issues a random one and persists
+// it. `randomBytes` is injectable so tests are deterministic.
+export function ensureWorkspaceIdentity({ project, dataRoot, randomBytes = cryptoRandomBytes } = {}) {
+  const existing = readLocalPointer(project)
+  if (existing) return existing
+  const pointer = { schema: LOCAL_POINTER_SCHEMA, workspaceId: `ws-${randomBytes(12).toString('hex')}`, ...(dataRoot === undefined ? {} : { dataRoot: path.resolve(dataRoot) }) }
+  return writeLocalPointer(project, pointer)
+}
+
+// ---------------------------------------------------------------------------
+// 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')
+  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))
+    || new Set(document.audienceAllow).size !== document.audienceAllow.length) {
+    refuse('invalid-machine-settings', 'audienceAllow must be a list of distinct audience identifiers')
+  }
+  if (document.applyPolicy !== null) {
+    closedObject(document.applyPolicy, { required: ['policyId', 'version', 'digest'] }, 'invalid-machine-settings', 'the apply policy reference')
+    const { policyId, version, digest } = document.applyPolicy
+    if (typeof policyId !== 'string' || !IDENTIFIER.test(policyId) || !Number.isInteger(version) || version < 1 || typeof digest !== 'string' || !DIGEST.test(digest)) {
+      refuse('invalid-machine-settings', 'the apply policy reference is malformed')
+    }
+  }
+  if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse('invalid-machine-settings', 'updatedAt must be a UTC timestamp')
+  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.
+export function defaultMachineSettings({ workspaceId, updatedAt }) {
+  return { schema: MACHINE_SETTINGS_SCHEMA, workspaceId, maintenanceMode: 'manual', audienceAllow: [], applyPolicy: null, updatedAt }
+}
+
+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)
+
+export function readMachineSettings({ workspaceRoot, workspaceId }) {
+  const document = readJsonFile(settingsFile(workspaceRoot, 'machine.json'), 'invalid-machine-settings', 'machine settings')
+  return document === null ? null : validateMachineSettings(document, workspaceId)
+}
+
+export function writeMachineSettings({ workspaceRoot, workspaceId, settings, repositoryRoots }) {
+  validateMachineSettings(settings, workspaceId)
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'machine.json'), canonicalJson(settings))
+  return settings
+}
+
+// ---------------------------------------------------------------------------
+// Installed apply policy
+// ---------------------------------------------------------------------------
+
+// `digestOf` is the canonical digest of a policy, handed in by the caller that installs for a person (the command):
+// the decision that reads the policy recomputes that digest on every apply, so a policy that carries another one
+// could be installed and would then refuse every automatic apply. With it, such a policy is refused here, naming the
+// digest it has to carry. A digest is not a secret. The file of the person is never rewritten.
+export function installApplyPolicy({ workspaceRoot, workspaceId, policy, repositoryRoots, updatedAt, digestOf = null }) {
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the apply policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  if (policy.workspaceId !== workspaceId) refuse('invalid-apply-policy', 'the apply policy belongs to another workspace')
+  if (digestOf !== null) {
+    const expected = digestOf(policy)
+    if (policy.digest !== expected) refuse('policy-digest-mismatch', `the policy does not carry the digest of its content; it has to carry ${expected}`, { expected, carried: policy.digest })
+  }
+  const current = readMachineSettings({ workspaceRoot, workspaceId }) ?? defaultMachineSettings({ workspaceId, updatedAt })
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'apply-policy.json'), canonicalJson(policy))
+  return writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: { ...current, applyPolicy: { policyId: policy.policyId, version: policy.version, digest: policy.digest }, updatedAt } })
+}
+
+// Whether an automatic dispatch is authorized right now. Reads both files
+// from disk on every call; the engine calls this immediately before each
+// dispatch, so a revocation or a pause takes effect for the very next edit.
+// Anything missing, malformed or mismatched is "not authorized", never an
+// error that could be mistaken for permission.
+// `assumeAutomatic` answers "would automatic mode be authorized": the check `mode set automatic` makes before it writes.
+export function authorizeAutomaticApply({ workspaceRoot, workspaceId, assumeAutomatic = false }) {
+  const denied = (reason) => ({ authorized: false, reason, policy: null })
+  let settings
+  try { settings = readMachineSettings({ workspaceRoot, workspaceId }) } catch { return denied('machine-settings-invalid') }
+  if (!settings) return denied('machine-settings-absent')
+  if (settings.maintenanceMode !== 'automatic' && assumeAutomatic !== true) return denied('maintenance-mode-manual')
+  if (settings.applyPolicy === null) return denied('no-apply-policy-installed')
+  let policy
+  try {
+    policy = readJsonFile(settingsFile(workspaceRoot, 'apply-policy.json'), 'invalid-apply-policy', 'the apply policy')
+    if (policy !== null) assertObsidianContract('apply-policy', policy)
+  } catch { return denied('apply-policy-invalid') }
+  if (policy === null) return denied('apply-policy-absent')
+  const reference = settings.applyPolicy
+  if (policy.workspaceId !== workspaceId || policy.policyId !== reference.policyId || policy.version !== reference.version || policy.digest !== reference.digest) {
+    return denied('apply-policy-reference-mismatch')
+  }
+  if (policy.mode !== 'automatic') return denied('apply-policy-manual')
+  if (policy.status !== 'active') return denied(`apply-policy-${policy.status}`)
+  return { authorized: true, reason: 'apply-policy-active', policy }
+}
+
+// The installed policy as stored, validated, or null. A stored policy that does not validate refuses.
+export function readInstalledApplyPolicy({ workspaceRoot, workspaceId }) {
+  const policy = readJsonFile(settingsFile(workspaceRoot, 'apply-policy.json'), 'invalid-apply-policy', 'the apply policy')
+  if (policy === null) return null
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the stored apply policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  if (policy.workspaceId !== workspaceId) refuse('invalid-apply-policy', 'the stored apply policy belongs to another workspace')
+  return policy
+}
+
+// Revocation. The stored policy is marked revoked first: from that write on, every authorization read denies, so an
+// apply that is queued behind it is never dispatched. Then maintenance goes back to manual, so installing a policy
+// later does not resume automatic apply by itself.
+export function revokeApplyPolicy({ workspaceRoot, workspaceId, repositoryRoots, updatedAt }) {
+  const policy = readInstalledApplyPolicy({ workspaceRoot, workspaceId })
+  const current = readMachineSettings({ workspaceRoot, workspaceId })
+  if (policy === null && (current === null || current.applyPolicy === null)) return { revoked: false, reason: 'no-apply-policy-installed', policy: null }
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  const revoked = policy === null ? null : { ...policy, status: 'revoked' }
+  if (revoked !== null) atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'apply-policy.json'), canonicalJson(revoked))
+  if (current !== null) writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: { ...current, maintenanceMode: 'manual', updatedAt } })
+  return { revoked: true, reason: policy?.status === 'revoked' ? 'already-revoked' : 'revoked', policy: revoked }
+}