@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

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

@@ -0,0 +1,121 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import http from 'node:http'
+import { requestHeader, sameOrigin } from '../../server/security.mjs'
+import { isPlainObject } from './documents.mjs'
+import { HEALTH_SCHEMA, LOOPBACK_HOSTS, authorityOf } from './service-client.mjs'
+
+// The listener of the maintenance service: four fixed operations and nothing
+// else. There is no file serving, no command, no evaluation and no route that
+// takes a path, a name or code from a request.
+//
+//   GET  /health   who answers here; open, and says nothing else
+//   GET  /status   service and per-view freshness summary; bearer required
+//   POST /tick     run one tick now; bearer required
+//   POST /stop     finish the tick in flight and exit; bearer required
+//
+// Every request, before its operation is even looked up:
+//
+//   - `Host` is exactly the literal loopback authority this listener is bound
+//     to, so a name that resolves to loopback (DNS rebinding) is refused;
+//   - a `Sec-Fetch-Site` other than `none` or `same-origin`, or an `Origin`
+//     that is not this listener itself, is refused: no web page drives this;
+//   - the path is one of the four, exactly, with no query; the method is the
+//     one that path has.
+//
+// Everything but health needs the per-runtime random bearer that exists only
+// in the owner-only record. A POST body is JSON of at most 1 KiB naming the
+// runtime it is meant for, so a request aimed at an earlier runtime on the
+// same port does nothing.
+
+export const MAX_REQUEST_BYTES = 1024
+export const SERVICE_OPERATIONS = Object.freeze({ '/health': 'GET', '/status': 'GET', '/tick': 'POST', '/stop': 'POST' })
+
+const digestOf = (value) => createHash('sha256').update(String(value)).digest()
+
+// The decisions the request oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
+export const SERVER_PRIMITIVES = Object.freeze({
+  bearerMatches: (presented, expected) => typeof presented === 'string' && presented !== '' && timingSafeEqual(digestOf(presented), digestOf(expected)),
+  hostMatches: (header, authority) => header === authority,
+  originAllowed(headers, authority) {
+    const site = requestHeader(headers, 'sec-fetch-site').toLowerCase()
+    if (site !== '' && site !== 'none' && site !== 'same-origin') return false
+    const origin = requestHeader(headers, 'origin')
+    return origin === '' || sameOrigin(origin, `http://${authority}`)
+  },
+  maxRequestBytes: MAX_REQUEST_BYTES,
+})
+
+function send(response, statusCode, body) {
+  const text = JSON.stringify(body)
+  response.writeHead(statusCode, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text), 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', Connection: 'close' })
+  response.end(text)
+}
+
+function readBoundedJson(request, limit) {
+  return new Promise((resolve) => {
+    const declared = Number(request.headers['content-length'] ?? 0)
+    if (!Number.isFinite(declared) || declared > limit) return resolve({ ok: false, statusCode: 413, code: 'payload-too-large' })
+    const chunks = []
+    let size = 0
+    let done = false
+    const finish = (value) => { if (!done) { done = true; resolve(value) } }
+    request.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) { finish({ ok: false, statusCode: 413, code: 'payload-too-large' }); request.resume() } else chunks.push(chunk)
+    })
+    request.on('end', () => {
+      let body = null
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { body = null }
+      finish(isPlainObject(body) ? { ok: true, body } : { ok: false, statusCode: 400, code: 'payload-not-json-object' })
+    })
+    request.on('error', () => finish({ ok: false, statusCode: 400, code: 'payload-unreadable' }))
+  })
+}
+
+// identity: { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt }
+// operations: { healthStatus(), status(), tick(), stop() }
+export function createServiceServerForOracleTests({ identity, bearer, operations }, primitives = SERVER_PRIMITIVES) {
+  if (!LOOPBACK_HOSTS.includes(identity?.host)) throw new TypeError('the service listens on a literal loopback address only')
+  if (typeof bearer !== 'string' || bearer.length < 32) throw new TypeError('the service needs its random bearer')
+  const rules = { ...SERVER_PRIMITIVES, ...primitives }
+
+  async function handle(request, response) {
+    const authority = authorityOf(identity.host, identity.port)
+    if (!rules.hostMatches(requestHeader(request.headers, 'host'), authority)) return send(response, 403, { error: 'host-not-this-loopback-listener' })
+    if (!rules.originAllowed(request.headers, authority)) return send(response, 403, { error: 'cross-site-request' })
+    const method = Object.hasOwn(SERVICE_OPERATIONS, request.url) ? SERVICE_OPERATIONS[request.url] : null
+    if (method === null) return send(response, 404, { error: 'unknown-operation' })
+    if (request.method !== method) return send(response, 405, { error: 'method-not-allowed' })
+    if (request.url === '/health') {
+      const { serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt } = identity
+      return send(response, 200, { schema: HEALTH_SCHEMA, serviceName, workspaceId, runtimeId, pid, host, port, executableDigest, startedAt, status: operations.healthStatus() })
+    }
+    const presented = /^Bearer ([A-Za-z0-9_-]+)$/.exec(requestHeader(request.headers, 'authorization'))?.[1] ?? null
+    if (!rules.bearerMatches(presented, bearer)) return send(response, 401, { error: 'bearer-required' })
+    if (request.url === '/status') return send(response, 200, await operations.status())
+    const payload = await readBoundedJson(request, rules.maxRequestBytes)
+    if (!payload.ok) return send(response, payload.statusCode, { error: payload.code })
+    if (Object.keys(payload.body).length !== 1 || payload.body.runtimeId !== identity.runtimeId) return send(response, 409, { error: 'request-names-another-runtime' })
+    if (request.url === '/tick') return send(response, 200, await operations.tick())
+    // The answer leaves first; the service then finishes its tick and exits.
+    response.once('finish', () => { void operations.stop() })
+    return send(response, 202, { stopping: true, runtimeId: identity.runtimeId, pid: identity.pid })
+  }
+
+  const server = http.createServer({ requestTimeout: 10_000, headersTimeout: 5_000, keepAliveTimeout: 1_000, maxHeaderSize: 8 * 1024 }, (request, response) => {
+    handle(request, response).catch(() => { if (!response.headersSent) send(response, 500, { error: 'operation-failed' }); else response.destroy() })
+  })
+  return {
+    server,
+    listen: () => new Promise((resolve, reject) => {
+      server.once('error', reject)
+      // A literal address and `ipv6Only`: never a wildcard, never a name.
+      server.listen({ host: identity.host, port: identity.port, ipv6Only: identity.host === '::1', exclusive: true }, () => { server.off('error', reject); resolve(server.address()) })
+    }),
+    close: () => new Promise((resolve) => { server.close(() => resolve()); server.closeAllConnections() }),
+  }
+}
+
+export function createServiceServer(options) {
+  return createServiceServerForOracleTests(options, SERVER_PRIMITIVES)
+}

package/src/runtime/obsidian/service.mjs

@@ -0,0 +1,216 @@
+import { randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import { AtelierDiagnosticError } from '../../project/config.mjs'
+import { ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { isoTime } from './documents.mjs'
+import { createMaintenanceEngine } from './engine.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
+import { assertOutsideRepositories, protectedRoots, readLocalPointer, resolveDataRoot, workspaceStateRoot } from './machine-settings.mjs'
+import { isProcessAlive } from './private-lock.mjs'
+import { probeHealth } from './service-client.mjs'
+import {
+  SERVICE_ERROR_SCHEMA, executableIdentity, readLastServiceError, readServiceRecord, readServiceSettings, removeServiceRecord, serviceNameFor, servicePaths,
+  writeLastServiceError, writeServiceRecord,
+} from './service-record.mjs'
+import { createServiceServer } from './service-server.mjs'
+import { createMaintenanceStateStore } from './state-store.mjs'
+import { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
+import { createFsWatcherFactory } from './watchers.mjs'
+
+// The maintenance service of one workspace, inside one process.
+//
+//   resolve the workspace -> read this machine's service settings -> refuse if
+//   another runtime of this workspace answers -> listen on the literal
+//   loopback address -> write the owner-only record -> tick on an interval
+//
+// It listens before its first tick and until after its last, and it removes
+// its record before it stops listening, so a record whose address refuses
+// connections never belongs to a working service.
+//
+// The service owns a process and a listener and nothing else. Every write to
+// a vault, to recovery or to staging is the engine's and the publisher's. On
+// shutdown the tick in flight is allowed to finish; nothing is swept, and a
+// publication that was cut short is settled by the publisher's own restart
+// recovery on a later tick, never by deleting what it left behind.
+//
+// `adapterFactory` has no default here either: whoever starts the service
+// decides whether it may reach a running app.
+
+export const SERVICE_STATUS_SCHEMA = 'atelier-obsidian-service-status/v1'
+export const DEFAULT_SHUTDOWN_GRACE_MS = 30 * 1000
+
+// Where a workspace keeps its private state, without creating an identity.
+export function resolveServiceWorkspace({ project, dataRoot, env = process.env, platform = process.platform, create = false }) {
+  const pointer = readLocalPointer(project)
+  if (pointer === null) return null
+  const requested = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), pointer.workspaceId)
+  assertOutsideRepositories({ managedRoot: requested, repositoryRoots: protectedRoots(project) })
+  if (create) fs.mkdirSync(requested, { recursive: true, mode: 0o700 })
+  else if (!fs.existsSync(requested)) return { workspaceId: pointer.workspaceId, workspaceRoot: null }
+  return { workspaceId: pointer.workspaceId, workspaceRoot: fs.realpathSync(requested) }
+}
+
+const isTyped = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal
+const errorCode = (error) => (typeof error?.code === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(error.code) ? error.code : 'untyped-error')
+const errorName = (error) => (typeof error?.name === 'string' ? error.name.slice(0, 64) : 'Error')
+
+// Where a rename over a file somebody is reading can fail for a moment (Windows), the one record write is tried again.
+async function writeRecordPatiently(input) {
+  for (let attempt = 0; ; attempt += 1) {
+    try { return writeServiceRecord(input) } catch (error) {
+      if (attempt >= 5 || !['EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error
+      await new Promise((resolve) => { setTimeout(resolve, 50) })
+    }
+  }
+}
+
+export async function runMaintenanceService(options = {}) {
+  const {
+    loadProject, dataRoot, adapterFactory, entryPath, runtimeId = `rt-${cryptoRandomBytes(16).toString('hex')}`, startup = false,
+    intervalMs = DEFAULT_TICK_INTERVAL_MS, maxBackoffMs = Math.max(DEFAULT_MAX_BACKOFF_MS, intervalMs), shutdownGraceMs = DEFAULT_SHUTDOWN_GRACE_MS,
+    clock = () => new Date(), log = () => {}, pid = process.pid, randomBytes = cryptoRandomBytes, env = process.env, platform = process.platform,
+    engineOptions = {}, createEngine = createMaintenanceEngine,
+    // What the adapter factory last learned about the installed app, when it qualifies one. Codes and versions only.
+    appStatus = null,
+  } = options
+  if (typeof loadProject !== 'function') throw new TypeError('the service needs loadProject')
+  if (typeof adapterFactory !== 'function') throw new TypeError('the service needs an adapterFactory')
+  if (typeof entryPath !== 'string') throw new TypeError('the service needs the path of its entry module')
+
+  const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+  if (!workspace?.workspaceRoot) refuse('service-workspace-not-prepared', 'this workspace has no private state yet; `start` prepares it')
+  const { workspaceId, workspaceRoot } = workspace
+  const settings = readServiceSettings({ workspaceRoot, workspaceId })
+  if (settings === null) refuse('service-settings-absent', 'this machine recorded no loopback port and no consent for this workspace')
+  // A unit installed at the operating-system level runs only under a consent that covers it.
+  if (startup && settings.consent.coverage !== 'service-and-startup') refuse('startup-consent-absent', 'the recorded consent covers the service, not operating-system startup')
+  const { host, port } = settings
+
+  // Another runtime of this workspace that proves itself is never displaced. A malformed record refuses here.
+  const existing = readServiceRecord({ workspaceRoot, workspaceId })
+  if (existing && existing.runtimeId !== runtimeId && isProcessAlive(existing.pid)) {
+    const answer = await probeHealth({ host: existing.host, port: existing.port })
+    if (answer.kind === 'health' && answer.body.runtimeId === existing.runtimeId && answer.body.pid === existing.pid) refuse('service-already-running', 'another runtime of this workspace answers health', { runtimeId: existing.runtimeId, pid: existing.pid })
+  }
+
+  const executable = executableIdentity(entryPath)
+  const startedAt = isoTime(clock)
+  const identity = { serviceName: serviceNameFor(workspaceId), workspaceId, runtimeId, pid, host, port, executableDigest: executable.digest, startedAt }
+  const bearer = randomBytes(32).toString('base64url')
+  const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
+
+  let stopping = false
+  let consecutiveFailures = 0
+  let lastTick = null
+  let settleDone
+  const done = new Promise((resolve) => { settleDone = resolve })
+
+  const engine = createEngine({ watcherFactory: createFsWatcherFactory(), ...engineOptions, loadProject, dataRoot, adapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId } })
+
+  const recordIsOurs = () => {
+    try { const record = readServiceRecord({ workspaceRoot, workspaceId }); return record !== null && record.runtimeId === runtimeId && record.pid === pid } catch { return false }
+  }
+
+  function recordOutcome(outcome) {
+    const at = isoTime(clock)
+    consecutiveFailures = outcome.consecutiveFailures
+    if (outcome.ok) {
+      lastTick = { at, state: outcome.report.state, reason: outcome.report.reason ?? outcome.report.refusal?.code ?? null }
+      const previous = readLastServiceError({ workspaceRoot, workspaceId })
+      if (previous && previous.resolvedAt === null) writeLastServiceError({ workspaceRoot, workspaceId, document: { ...previous, consecutiveFailures: 0, resolvedAt: at } })
+      return
+    }
+    lastTick = { at, state: 'failed', reason: errorCode(outcome.error) }
+    // The message may carry a path or a title: it goes to the private log and nowhere else.
+    log({ at, event: 'tick-failed', code: errorCode(outcome.error), name: errorName(outcome.error), message: String(outcome.error?.message ?? outcome.error), consecutiveFailures })
+    let previous = null
+    try { previous = readLastServiceError({ workspaceRoot, workspaceId }) } catch { previous = null }
+    writeLastServiceError({ workspaceRoot, workspaceId, document: { schema: SERVICE_ERROR_SCHEMA, workspaceId, runtimeId, code: errorCode(outcome.error), name: errorName(outcome.error), at, consecutiveFailures, totalFailures: (previous?.totalFailures ?? 0) + 1, resolvedAt: null } })
+  }
+
+  const loop = createTickLoop({
+    intervalMs, maxBackoffMs, onOutcome: recordOutcome,
+    async tick() {
+      // The service runs only while its record names it: a replaced or removed record ends it, cleanly.
+      if (!recordIsOurs()) { void shutdown('record-no-longer-names-this-runtime'); return { state: 'stopping', reason: 'record-no-longer-names-this-runtime' } }
+      return engine.tick()
+    },
+  })
+
+  const summary = (report) => ({ state: report.state, reason: report.reason ?? report.refusal?.code ?? null, scopes: (report.scopes ?? []).map(({ scopeId, state, reason, verified }) => ({ scopeId, state, reason, verified })) })
+
+  function freshnessSummary() {
+    let document
+    try { document = stateStore.readFreshness() } catch (error) { if (isTyped(error)) return { readable: false, code: error.code }; throw error }
+    if (document === null) return null
+    const { enablement, maintenanceMode, lastTickAt, lastFullReconciliationAt } = document
+    // Counts, never the held paths: a note path carries a title.
+    const scopes = document.scopes.map(({ scopeId, state, reason, verified, generationId, preparedGenerationId, heldNotes, retainedEdits, checkedAt }) => ({ scopeId, state, reason, verified, generationId, preparedGenerationId, heldNoteCount: heldNotes.length, retainedEdits, checkedAt }))
+    return { readable: true, enablement, maintenanceMode, lastTickAt, lastFullReconciliationAt, scopes }
+  }
+
+  const healthStatus = () => (stopping ? 'stopped' : consecutiveFailures > 0 ? 'degraded' : 'healthy')
+  const server = createServiceServer({
+    identity, bearer,
+    operations: {
+      healthStatus,
+      status() {
+        let lastError = null
+        try { lastError = readLastServiceError({ workspaceRoot, workspaceId }) } catch (error) { if (!isTyped(error)) throw error; lastError = { unreadable: error.code } }
+        if (lastError?.schema) { const { schema: _schema, workspaceId: _workspace, ...shown } = lastError; lastError = shown }
+        return { schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(), ...(typeof appStatus === 'function' ? { app: appStatus() } : {}) }
+      },
+      async tick() {
+        const outcome = await loop.tickNow()
+        if (outcome.stopped) return { ok: false, stopped: true }
+        return outcome.ok ? { ok: true, ...summary(outcome.report) } : { ok: false, error: { code: errorCode(outcome.error), name: errorName(outcome.error) } }
+      },
+      stop: () => shutdown('stop-requested'),
+    },
+  })
+
+  let shuttingDown = null
+  function shutdown(reason) {
+    if (shuttingDown) return shuttingDown
+    stopping = true
+    shuttingDown = (async () => {
+      log({ at: isoTime(clock), event: 'stopping', reason })
+      // The tick in flight finishes, within the grace period. Past it the process ends anyway: the publisher journals every step.
+      let timer
+      await Promise.race([loop.stop(), new Promise((resolve) => { timer = setTimeout(resolve, shutdownGraceMs) })])
+      clearTimeout(timer)
+      try { engine.stop() } catch { /* watchers only */ }
+      // Drafts, pending edits, recovery and staging stay exactly as they are. Only the generated record goes, and before the listener does.
+      try { removeServiceRecord({ workspaceRoot, workspaceId, runtimeId, pid }) } catch { /* a record that cannot be removed is reported stale later */ }
+      await server.close()
+      log({ at: isoTime(clock), event: 'stopped', reason })
+      settleDone({ reason })
+      return { reason }
+    })()
+    return shuttingDown
+  }
+
+  try {
+    await server.listen()
+  } catch (error) {
+    try { engine.stop() } catch { /* nothing was watched yet */ }
+    if (error.code === 'EADDRINUSE') refuse('service-port-occupied', 'something else listens on the recorded loopback port; it is never taken over', { host, port })
+    throw error
+  }
+  try {
+    await writeRecordPatiently({
+      workspaceRoot, workspaceId,
+      record: {
+        schema: 'atelier-obsidian-service-state/v1', contractVersion: '1.0.0', workspaceId, serviceName: identity.serviceName, host, port, runtimeId, pid,
+        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
+        health: { status: 'healthy', checkedAt: startedAt }, consent: settings.consent, ext: { bearer },
+      },
+    })
+  } catch (error) {
+    await server.close()
+    throw error
+  }
+  log({ at: startedAt, event: 'started', runtimeId, pid, host, port, startup })
+  loop.start()
+  return { identity, workspaceRoot, tickNow: () => loop.tickNow(), shutdown, done }
+}

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

@@ -0,0 +1,87 @@
+import path from 'node:path'
+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.
+//
+// Every machine-specific value is an input. Nothing is looked up here: no
+// home directory, no environment, no current directory, no installed path.
+//
+//   macOS    a launchd user agent (property list)
+//   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`.
+
+export const STARTUP_PLATFORMS = Object.freeze(['darwin', 'linux'])
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
+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('$', '$$$$')}"`
+
+function launchdText({ label, words, logPath, workingDirectory }) {
+  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">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>', `  <string>${xml(label)}</string>`,
+    '  <key>ProgramArguments</key>', '  <array>', ...words.map((word) => `    <string>${xml(word)}</string>`), '  </array>',
+    '  <key>RunAtLoad</key>', '  <true/>',
+    // Restarted after a crash, not after a clean stop; a refusal is not retried in a tight loop.
+    '  <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>StandardOutPath</key>', `  <string>${xml(logPath)}</string>`,
+    '  <key>StandardErrorPath</key>', `  <string>${xml(logPath)}</string>`,
+    '</dict>',
+    '</plist>',
+  ]
+  return `${lines.join('\n')}\n`
+}
+
+function systemdText({ label, words, logPath, workingDirectory }) {
+  const lines = [
+    '[Unit]',
+    `Description=Atelier Obsidian maintenance (${label.replaceAll(/[^A-Za-z0-9._-]/g, '')})`,
+    '',
+    '[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).
+    'Restart=on-failure',
+    'RestartSec=60',
+    'RestartPreventExitStatus=2',
+    `StandardOutput=append:${logPath.replaceAll('%', '%%')}`,
+    `StandardError=append:${logPath.replaceAll('%', '%%')}`,
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+  ]
+  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 } = {}) {
+  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 })
+  }
+  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 (args.includes('--startup')) refuse('startup-adapter-input-invalid', '--startup is added by the builder')
+  const words = [nodePath, entryPath, '--startup', ...args]
+  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 }) }
+}

package/src/runtime/obsidian/state-store.mjs

@@ -0,0 +1,180 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { PATH_REGISTRY_SCHEMA } from '../../projection/obsidian/materialize/path-registry.mjs'
+import { canonicalJson, closedObject, compareText } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { APPLY_RESULT_STATUSES } from './extension-points.mjs'
+
+// Private, versioned documents of the maintenance engine, under
+//
+//   <data>/obsidian/<workspace-id>/state/maintenance/
+//     freshness.json      per-scope freshness, read by the opening commands
+//     pending-edits.json  edits made in a vault, preserved and waiting
+//     late-writers.json   writes that arrived in a displaced file after publication
+//     path-registry.json  the workspace path registry prepareView grows
+//
+// None of the frozen contracts describes these, so each is a closed document
+// of this module: an unknown key, state or schema refuses on read and on
+// write. Files are owner-only and replaced atomically. A document is written
+// only when its bytes change.
+
+export const FRESHNESS_SCHEMA = 'atelier-obsidian-freshness/v1'
+export const PENDING_EDITS_SCHEMA = 'atelier-obsidian-pending-edits/v1'
+export const LATE_WRITERS_SCHEMA = 'atelier-obsidian-late-writers/v1'
+
+export const FRESHNESS_STATES = Object.freeze(['current', 'updating', 'held-for-your-edit', 'stale', 'publisher-conflict', 'disabled'])
+export const CHANGE_CLASSES = Object.freeze(['source-body', 'sidecar', 'asset', 'config', 'ext-settings', 'scope', 'eligibility', 'vault-note'])
+
+// queued            waiting for a person (manual) or for the next dispatch (automatic)
+// apply-unavailable dispatched, and no apply operation exists yet
+// apply-failed      dispatched, and the operation refused, conflicted or failed
+// retry-exhausted   the retry budget is spent; still pending, no longer dispatched
+// applied           the operation reported the edit applied to source
+// withdrawn         the note is back at the bytes it was generated with
+// superseded        the note was edited again; a newer record carries the newer bytes
+export const OPEN_EDIT_STATES = Object.freeze(['queued', 'apply-unavailable', 'apply-failed', 'retry-exhausted'])
+export const CLOSED_EDIT_STATES = Object.freeze(['applied', 'withdrawn', 'superseded'])
+export const EDIT_STATES = Object.freeze([...OPEN_EDIT_STATES, ...CLOSED_EDIT_STATES])
+
+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{3}Z$/
+const EDIT_ID = /^edit-[0-9a-f]{32}$/
+
+const isIdentifier = (value) => typeof value === 'string' && IDENTIFIER.test(value)
+const isDigest = (value) => typeof value === 'string' && DIGEST.test(value)
+const isTimestamp = (value) => typeof value === 'string' && TIMESTAMP.test(value)
+const isRelative = (value) => typeof value === 'string' && value !== '' && !value.startsWith('/') && !value.includes('\\') && !value.split('/').some((part) => part === '' || part === '.' || part === '..')
+const isCount = (value) => Number.isInteger(value) && value >= 0
+
+function check(condition, code, message) {
+  if (!condition) refuse(code, message)
+}
+
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+
+export function validateFreshness(document, workspaceId) {
+  const code = 'invalid-freshness-state'
+  closedObject(document, { required: ['schema', 'workspaceId', 'enablement', 'maintenanceMode', 'lastTickAt', 'lastFullReconciliationAt', 'scopes'] }, code, 'the freshness document')
+  check(document.schema === FRESHNESS_SCHEMA, code, 'the freshness document names an unknown schema')
+  check(document.workspaceId === workspaceId, code, 'the freshness document belongs to another workspace')
+  check(['enabled', 'disabled', 'refused'].includes(document.enablement), code, 'enablement is unknown')
+  check(['manual', 'automatic'].includes(document.maintenanceMode), code, 'maintenanceMode is unknown')
+  check(isTimestamp(document.lastTickAt) && (document.lastFullReconciliationAt === null || isTimestamp(document.lastFullReconciliationAt)), code, 'a tick time is not a UTC timestamp')
+  check(Array.isArray(document.scopes), code, 'scopes must be a list')
+  const seen = new Set()
+  for (const scope of document.scopes) {
+    closedObject(scope, { required: ['scopeId', 'state', 'reason', 'generationId', 'preparedGenerationId', 'verified', 'heldNotes', 'changeClasses', 'retainedEdits', 'checkedAt'] }, code, 'a scope freshness entry')
+    check(isIdentifier(scope.scopeId) && !seen.has(scope.scopeId), code, 'a scope identity is malformed or repeated')
+    seen.add(scope.scopeId)
+    check(FRESHNESS_STATES.includes(scope.state), code, 'a scope carries an unknown freshness state')
+    check(typeof scope.reason === 'string' && scope.reason !== '' && scope.reason.length <= 160, code, 'a scope reason must be a short code')
+    check((scope.generationId === null || isIdentifier(scope.generationId)) && (scope.preparedGenerationId === null || isIdentifier(scope.preparedGenerationId)), code, 'a generation identity is malformed')
+    check(typeof scope.verified === 'boolean', code, 'verified must be a boolean')
+    check(Array.isArray(scope.heldNotes) && scope.heldNotes.every(isRelative), code, 'heldNotes must list vault-relative paths')
+    // `current` is a claim about exact generations and verified bytes; a document that claims it otherwise refuses.
+    check(scope.state !== 'current' || (scope.verified && scope.generationId !== null && scope.generationId === scope.preparedGenerationId && scope.heldNotes.length === 0), code, 'a scope claims current without an exact verified generation')
+    check(Array.isArray(scope.changeClasses) && scope.changeClasses.every((item) => CHANGE_CLASSES.includes(item)), code, 'changeClasses names an unknown class')
+    check(isCount(scope.retainedEdits) && isTimestamp(scope.checkedAt), code, 'a scope entry is malformed')
+  }
+  return document
+}
+
+export function validatePendingEdits(document, workspaceId) {
+  const code = 'invalid-pending-edits'
+  closedObject(document, { required: ['schema', 'workspaceId', 'edits'] }, code, 'the pending edit document')
+  check(document.schema === PENDING_EDITS_SCHEMA, code, 'the pending edit document names an unknown schema')
+  check(document.workspaceId === workspaceId, code, 'the pending edit document belongs to another workspace')
+  check(Array.isArray(document.edits), code, 'edits must be a list')
+  const seen = new Set()
+  for (const edit of document.edits) {
+    closedObject(edit, { required: ['editId', 'identity', 'scopeId', 'generationId', 'path', 'baseNoteDigest', 'observedDigest', 'objectRef', 'observedAt', 'state', 'attempts', 'retryBudget', 'lastAttemptAt', 'lastResult', 'closedAt'] }, code, 'a pending edit')
+    check(typeof edit.editId === 'string' && EDIT_ID.test(edit.editId) && !seen.has(edit.editId), code, 'an edit identity is malformed or repeated')
+    seen.add(edit.editId)
+    closedObject(edit.identity, { required: ['workspaceId', 'repoId', 'nodeId'] }, code, 'a pending edit identity')
+    check(edit.identity.workspaceId === workspaceId && isIdentifier(edit.identity.repoId) && isIdentifier(edit.identity.nodeId), code, 'a pending edit identity is malformed')
+    check(isIdentifier(edit.scopeId) && isIdentifier(edit.generationId) && isRelative(edit.path), code, 'a pending edit origin is malformed')
+    check(isDigest(edit.baseNoteDigest) && isDigest(edit.observedDigest) && edit.baseNoteDigest !== edit.observedDigest, code, 'a pending edit needs two different digests')
+    // The edited bytes are preserved before an edit is recorded, so a record without its object refuses.
+    check(edit.objectRef === `recovery/objects/${edit.observedDigest.slice('sha256:'.length)}.bin`, code, 'a pending edit must name the retained object of its observed bytes')
+    check(isTimestamp(edit.observedAt) && EDIT_STATES.includes(edit.state) && isCount(edit.attempts), code, 'a pending edit is malformed')
+    check(edit.retryBudget === null || (isCount(edit.retryBudget) && edit.retryBudget <= 16), code, 'retryBudget is out of range')
+    check(edit.lastAttemptAt === null || isTimestamp(edit.lastAttemptAt), code, 'lastAttemptAt is malformed')
+    if (edit.lastResult !== null) {
+      closedObject(edit.lastResult, { required: ['status', 'code', 'operationId', 'policyDigest'] }, code, 'a pending edit result')
+      check(APPLY_RESULT_STATUSES.includes(edit.lastResult.status) && typeof edit.lastResult.code === 'string' && typeof edit.lastResult.operationId === 'string' && isDigest(edit.lastResult.policyDigest), code, 'a pending edit result is malformed')
+    }
+    check(CLOSED_EDIT_STATES.includes(edit.state) ? isTimestamp(edit.closedAt) : edit.closedAt === null, code, 'closedAt must be set exactly when an edit is closed')
+    check(edit.state !== 'applied' || edit.lastResult?.status === 'applied', code, 'an edit is applied only when the apply operation said so')
+  }
+  return document
+}
+
+export function validateLateWriters(document, workspaceId) {
+  const code = 'invalid-late-writers'
+  closedObject(document, { required: ['schema', 'workspaceId', 'findings'] }, code, 'the late writer document')
+  check(document.schema === LATE_WRITERS_SCHEMA && document.workspaceId === workspaceId && Array.isArray(document.findings), code, 'the late writer document is malformed')
+  for (const finding of document.findings) {
+    closedObject(finding, { required: ['scopeId', 'journalId', 'unit', 'notePath', 'digestAtMove', 'observedDigest', 'objectRef', 'detectedAt'] }, code, 'a late writer finding')
+    check(isIdentifier(finding.scopeId) && isIdentifier(finding.journalId) && isCount(finding.unit) && (finding.notePath === null || isRelative(finding.notePath)), code, 'a late writer finding is malformed')
+    check((finding.digestAtMove === null || isDigest(finding.digestAtMove)) && isDigest(finding.observedDigest) && isRelative(finding.objectRef) && isTimestamp(finding.detectedAt), code, 'a late writer finding is malformed')
+  }
+  return document
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+export function sortEdits(edits) {
+  return [...edits].sort((left, right) => compareText(left.identity.repoId, right.identity.repoId) || compareText(left.identity.nodeId, right.identity.nodeId)
+    || compareText(left.scopeId, right.scopeId) || compareText(left.observedAt, right.observedAt) || compareText(left.editId, right.editId))
+}
+
+export function createMaintenanceStateStore({ workspaceRoot, workspaceId }) {
+  const directory = () => ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, 'state', 'maintenance'), label: 'Obsidian maintenance state' })
+  const file = (name) => path.join(workspaceRoot, 'state', 'maintenance', name)
+
+  function read(name, validate, code) {
+    let text
+    try { text = readRegularTextNoFollow(file(name)) } catch (error) {
+      if (error.code === 'ENOENT') return null
+      refuse(code, 'a maintenance state document cannot be read', { cause: error.code ?? String(error.message) })
+    }
+    let document
+    try { document = JSON.parse(text) } catch { refuse(code, 'a maintenance state document is not JSON') }
+    return validate(document, workspaceId)
+  }
+
+  function write(name, document, validate) {
+    validate(document, workspaceId)
+    const text = canonicalJson(document)
+    let existing = null
+    try { existing = fs.readFileSync(file(name), 'utf8') } catch (error) { if (error.code !== 'ENOENT') throw error }
+    if (existing === text) return false
+    atomicReplacePrivateText(path.join(directory(), name), text)
+    return true
+  }
+
+  const registryValidator = (document) => {
+    if (document?.schema !== PATH_REGISTRY_SCHEMA || document.workspaceId !== workspaceId || !Array.isArray(document.entries)) refuse('invalid-path-registry', 'the persisted path registry is malformed')
+    return document
+  }
+
+  return {
+    workspaceRoot,
+    workspaceId,
+    exists: () => fs.existsSync(path.join(workspaceRoot, 'state', 'maintenance')),
+    readFreshness: () => read('freshness.json', validateFreshness, 'invalid-freshness-state'),
+    writeFreshness: (document) => write('freshness.json', { ...document, scopes: [...document.scopes].sort((left, right) => compareText(left.scopeId, right.scopeId)) }, validateFreshness),
+    readPendingEdits: () => read('pending-edits.json', validatePendingEdits, 'invalid-pending-edits') ?? { schema: PENDING_EDITS_SCHEMA, workspaceId, edits: [] },
+    writePendingEdits: (document) => write('pending-edits.json', { ...document, edits: sortEdits(document.edits) }, validatePendingEdits),
+    readLateWriters: () => read('late-writers.json', validateLateWriters, 'invalid-late-writers') ?? { schema: LATE_WRITERS_SCHEMA, workspaceId, findings: [] },
+    writeLateWriters: (document) => write('late-writers.json', document, validateLateWriters),
+    readPathRegistry: () => read('path-registry.json', registryValidator, 'invalid-path-registry'),
+    writePathRegistry: (document) => write('path-registry.json', document, registryValidator),
+  }
+}

package/src/runtime/obsidian/sync-notice.mjs

@@ -0,0 +1,33 @@
+import { readObsidianEnablement } from './enablement.mjs'
+import { ObsidianMaintenanceRefusal } from './errors.mjs'
+import { readServiceRecord } from './service-record.mjs'
+import { resolveServiceWorkspace } from './service.mjs'
+import { createMaintenanceStateStore } from './state-store.mjs'
+
+// What Git synchronization may say about Obsidian maintenance: a report, read
+// from persisted state, and a hint. Null when the project does not declare
+// the integration or has it switched off, so the output of `sync` is then
+// exactly what it always was. Nothing here starts or asks a service, ticks an
+// engine, publishes a view or writes a file.
+export function maintenanceNoticeFor(project, { dataRoot, env = process.env, platform = process.platform } = {}) {
+  let enablement
+  try { enablement = readObsidianEnablement(project) } catch (error) {
+    if (!(error instanceof ObsidianMaintenanceRefusal)) throw error
+    return { state: 'refused', code: error.code, hint: 'atelier obsidian status' }
+  }
+  if (enablement.state !== 'enabled') return null
+  const notice = { state: 'enabled', maintainedBy: 'the Obsidian maintenance service, not by sync', hint: 'atelier obsidian status' }
+  try {
+    const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
+    if (!workspace?.workspaceRoot) return { ...notice, service: 'never-started', scopes: [] }
+    const freshness = createMaintenanceStateStore(workspace).readFreshness()
+    // A record is not proof that a service runs; only `obsidian service status` proves that.
+    return {
+      ...notice, service: readServiceRecord(workspace) === null ? 'no-record' : 'recorded-not-verified', lastTickAt: freshness?.lastTickAt ?? null,
+      scopes: (freshness?.scopes ?? []).map(({ scopeId, state, reason, checkedAt }) => ({ scopeId, lastKnownState: state, reason, checkedAt })),
+    }
+  } catch (error) {
+    if (!(error instanceof ObsidianMaintenanceRefusal)) throw error
+    return { ...notice, service: 'unknown', code: error.code, scopes: [] }
+  }
+}