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

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

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
+import { canonicalJson, closedObject } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { LOOPBACK_HOSTS } from './service-client.mjs'
+
+// Private documents of the maintenance service of one workspace, under
+//
+//   <data>/obsidian/<workspace-id>/state/service/
+//     runtime.json     the adapter record of the running service (service-state v1)
+//     settings.json    what this machine chose: loopback host, port, startup consent
+//     last-error.json  the last tick that failed for a reason nobody typed
+//     service.log      the operational log of the service process
+//     start-lock/      serializes `start` for this workspace
+//
+// Owner-only, replaced atomically, outside every repository and every vault.
+// Every document is validated on every read. One that does not validate, or
+// that names another workspace, service or state location, refuses: it is
+// never repaired, never adopted and never overwritten without a person.
+
+export const SERVICE_SETTINGS_SCHEMA = 'atelier-obsidian-service-settings/v1'
+export const SERVICE_ERROR_SCHEMA = 'atelier-obsidian-service-last-error/v1'
+export const CONSENT_COVERAGES = Object.freeze(['service', 'service-and-startup'])
+
+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 BEARER = /^[A-Za-z0-9_-]{43}$/
+
+export function serviceNameFor(workspaceId) {
+  const name = `atelier-obsidian-${workspaceId}`
+  if (!IDENTIFIER.test(name)) refuse('invalid-workspace-identity', 'the workspace identity cannot name a service')
+  return name
+}
+
+export function servicePaths(workspaceRoot) {
+  const directory = path.join(workspaceRoot, 'state', 'service')
+  return {
+    stateLocation: path.join(workspaceRoot, 'state'), directory, record: path.join(directory, 'runtime.json'), settings: path.join(directory, 'settings.json'),
+    lastError: path.join(directory, 'last-error.json'), log: path.join(directory, 'service.log'), startLock: path.join(directory, 'start-lock'),
+  }
+}
+
+const serviceDirectory = (workspaceRoot) => ensureContainedPrivateDirectory({ workspaceRoot, directory: servicePaths(workspaceRoot).directory, label: 'Obsidian service state' })
+
+function readJson(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`) }
+}
+
+// The identity of what runs: the service entry module and the digest of its bytes.
+export function executableIdentity(entryPath) {
+  const resolved = fs.realpathSync(entryPath)
+  return { path: resolved, digest: `sha256:${createHash('sha256').update(fs.readFileSync(resolved)).digest('hex')}` }
+}
+
+// ---------------------------------------------------------------------------
+// The adapter record
+// ---------------------------------------------------------------------------
+
+export function validateServiceRecord(document, { workspaceRoot, workspaceId }) {
+  const code = 'invalid-service-record'
+  try { assertObsidianContract('service-state', document) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse(code, 'the service record does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  if (document.workspaceId !== workspaceId || document.serviceName !== serviceNameFor(workspaceId)) refuse(code, 'the service record belongs to another workspace or service')
+  if (document.stateLocation !== servicePaths(workspaceRoot).stateLocation) refuse(code, 'the service record names another state location')
+  if (!path.isAbsolute(document.executable.path)) refuse(code, 'the service record names an executable that is not an absolute path')
+  // The bearer of the running service lives here and nowhere else.
+  closedObject(document.ext, { required: ['bearer'] }, code, 'the private part of the service record')
+  if (typeof document.ext.bearer !== 'string' || !BEARER.test(document.ext.bearer)) refuse(code, 'the service record carries no usable bearer')
+  return document
+}
+
+export function readServiceRecord({ workspaceRoot, workspaceId }) {
+  const document = readJson(servicePaths(workspaceRoot).record, 'invalid-service-record', 'the service record')
+  return document === null ? null : validateServiceRecord(document, { workspaceRoot, workspaceId })
+}
+
+export function writeServiceRecord({ workspaceRoot, workspaceId, record }) {
+  validateServiceRecord(record, { workspaceRoot, workspaceId })
+  atomicReplacePrivateText(path.join(serviceDirectory(workspaceRoot), 'runtime.json'), canonicalJson(record))
+  return record
+}
+
+// Removes the record only while it still names this runtime and PID. Nothing else is ever removed here.
+export function removeServiceRecord({ workspaceRoot, workspaceId, runtimeId, pid }) {
+  let current
+  try { current = readServiceRecord({ workspaceRoot, workspaceId }) } catch { return false }
+  if (current === null || current.runtimeId !== runtimeId || current.pid !== pid) return false
+  try { fs.unlinkSync(servicePaths(workspaceRoot).record); return true } catch (error) { if (error.code === 'ENOENT') return false; throw error }
+}
+
+// What may be shown: everything but the bearer.
+export function publicRecord(record) {
+  if (record === null) return null
+  const { ext: _private, ...shown } = record
+  return shown
+}
+
+// ---------------------------------------------------------------------------
+// Machine-specific service settings
+// ---------------------------------------------------------------------------
+
+function validateServiceSettings(document, workspaceId) {
+  const code = 'invalid-service-settings'
+  closedObject(document, { required: ['schema', 'workspaceId', 'host', 'port', 'consent', 'updatedAt'] }, code, 'service settings')
+  if (document.schema !== SERVICE_SETTINGS_SCHEMA || document.workspaceId !== workspaceId) refuse(code, 'service settings name an unknown schema or another workspace')
+  if (!LOOPBACK_HOSTS.includes(document.host)) refuse(code, 'the service host must be the literal 127.0.0.1 or ::1')
+  if (!Number.isInteger(document.port) || document.port < 1024 || document.port > 65535) refuse(code, 'the service port must be between 1024 and 65535')
+  closedObject(document.consent, { required: ['grantedAt', 'actor', 'coverage'] }, code, 'the startup consent')
+  if (!TIMESTAMP.test(document.consent.grantedAt) || typeof document.consent.actor !== 'string' || !IDENTIFIER.test(document.consent.actor) || !CONSENT_COVERAGES.includes(document.consent.coverage)) refuse(code, 'the startup consent is malformed')
+  if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse(code, 'updatedAt must be a UTC timestamp')
+  return document
+}
+
+export function readServiceSettings({ workspaceRoot, workspaceId }) {
+  const document = readJson(servicePaths(workspaceRoot).settings, 'invalid-service-settings', 'service settings')
+  return document === null ? null : validateServiceSettings(document, workspaceId)
+}
+
+export function writeServiceSettings({ workspaceRoot, workspaceId, settings }) {
+  validateServiceSettings(settings, workspaceId)
+  atomicReplacePrivateText(path.join(serviceDirectory(workspaceRoot), 'settings.json'), canonicalJson(settings))
+  return settings
+}
+
+// ---------------------------------------------------------------------------
+// The last untyped tick error, and the operational log
+// ---------------------------------------------------------------------------
+
+function validateLastError(document, workspaceId) {
+  const code = 'invalid-service-last-error'
+  closedObject(document, { required: ['schema', 'workspaceId', 'runtimeId', 'code', 'name', 'at', 'consecutiveFailures', 'totalFailures', 'resolvedAt'] }, code, 'the last service error')
+  const ok = document.schema === SERVICE_ERROR_SCHEMA && document.workspaceId === workspaceId && typeof document.runtimeId === 'string' && IDENTIFIER.test(document.runtimeId)
+    && typeof document.code === 'string' && document.code.length <= 64 && typeof document.name === 'string' && document.name.length <= 64 && TIMESTAMP.test(document.at)
+    && Number.isInteger(document.consecutiveFailures) && document.consecutiveFailures >= 0 && Number.isInteger(document.totalFailures) && document.totalFailures >= 1
+    && (document.resolvedAt === null || TIMESTAMP.test(document.resolvedAt))
+  if (!ok) refuse(code, 'the last service error is malformed')
+  return document
+}
+
+export function readLastServiceError({ workspaceRoot, workspaceId }) {
+  const document = readJson(servicePaths(workspaceRoot).lastError, 'invalid-service-last-error', 'the last service error')
+  return document === null ? null : validateLastError(document, workspaceId)
+}
+
+// An error code and class only: a message can carry a path or a title, and goes to the private log instead.
+export function writeLastServiceError({ workspaceRoot, workspaceId, document }) {
+  validateLastError(document, workspaceId)
+  atomicReplacePrivateText(path.join(serviceDirectory(workspaceRoot), 'last-error.json'), canonicalJson(document))
+  return document
+}
+
+// The log is bounded: past the ceiling it becomes the one previous log, and a new one begins.
+export const SERVICE_LOG_MAX_BYTES = 1024 * 1024
+
+export function openServiceLog(workspaceRoot) {
+  const file = path.join(serviceDirectory(workspaceRoot), 'service.log')
+  try { if (fs.lstatSync(file).size > SERVICE_LOG_MAX_BYTES) fs.renameSync(file, `${file}.1`) } catch (error) { if (error.code !== 'ENOENT') throw error }
+  return { file, descriptor: openRegularFileNoFollow(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600) }
+}

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 }) }
+}