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

package/src/runtime/obsidian/pipeline.mjs

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { buildCanonicalGraph, createGraphFileCache } from '../../graph/graph.mjs'
+import { EMITTER_VERSION, createPreparationCache, prepareView, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { publishView } from '../../projection/obsidian/publication/publisher.mjs'
+import { recheckDisplacedFiles } from '../../projection/obsidian/recovery/late-writer.mjs'
+import { createRecoveryStore, readFileBytes } from '../../projection/obsidian/recovery/store.mjs'
+import { compareText } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { readFileFacts, sha256Digest, sourceKey } from './observation.mjs'
+
+// The production seams between the engine and the projection modules:
+//
+//   canonical graph -> source snapshot -> prepareView -> publishView
+//
+// The engine receives these as one object and tests replace single members.
+// Nothing here talks to a network, and nothing here asks git anything; the
+// canonical graph builder reads local ignore rules through the local git
+// executable and that is all.
+
+// Fails closed twice. A document is eligible only when the census classified
+// it: an unclassified one, or one that carries no classification at all, is
+// withheld. An embedded asset has no audience of its own, so it is eligible
+// only when at least one note that embeds it is itself eligible; a file that
+// only withheld notes embed never reaches a view, a snapshot or a state
+// document. `isAssetEligible(asset, { embeds, isEligibleSource })` may be
+// supplied to replace the asset rule; only an exact `true` admits an asset, and
+// `revision()` must change whenever either rule does.
+export const DEFAULT_ELIGIBILITY = Object.freeze({
+  revision: () => 'classified-documents/v2+assets-embedded-by-eligible-documents/v1',
+  isEligible: (node) => node.classification === 'classified',
+})
+
+export function assetEligibilityFor({ graph, eligibility }) {
+  const eligibleSources = new Set(graph.nodes.filter((node) => eligibility.isEligible(node) === true).map((node) => node.id))
+  const embeds = Array.isArray(graph.embeds) ? graph.embeds : []
+  if (typeof eligibility.isAssetEligible === 'function') {
+    return (asset) => eligibility.isAssetEligible(asset, { embeds: embeds.filter((embed) => embed?.asset?.id === asset.id), isEligibleSource: (id) => eligibleSources.has(id) }) === true
+  }
+  const embedded = new Set(embeds.filter((embed) => eligibleSources.has(embed?.source)).map((embed) => embed?.asset?.id))
+  return (asset) => embedded.has(asset.id)
+}
+
+const posix = (value) => value.split(path.sep).join('/')
+
+// The corpus profile of a loaded project. Repository roots are recorded
+// relative to the workspace root, since a profile is a portable shape; a
+// repository kept elsewhere on this machine is recorded by name only.
+export function profileFor({ project, workspaceId, audienceAllow }) {
+  const repositories = (project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => {
+    const relative = posix(path.relative(project.workspaceRoot, repo.path))
+    const inside = relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+    return { repoId: repo.name, root: relative === '' ? '.' : inside ? relative : `elsewhere/${repo.name}`, enrollment: 'enrolled' }
+  })
+  return { schema: 'atelier-obsidian-corpus-profile/v1', workspaceId, repositories, audience: { allow: [...audienceAllow] } }
+}
+
+// `cache` (createGraphFileCache) is the engine's per-file census cache; without it every source is parsed again.
+// `index` is the engine's observation index. With both, a source whose observed digest is the cached one is not
+// opened: observation already decided by digest that it did not change, under the stat-hint bound observation
+// documents, and a full reconciliation hashes it again. Without an index every source is read and hashed here.
+export function buildGraph({ project, eligibility, cache = null, index = null }) {
+  const observedDigest = cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null
+  const canonical = buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+  if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
+  return withEligibility(canonical, eligibility.isEligible, assetEligibilityFor({ graph: canonical, eligibility }))
+}
+
+// A source snapshot pinned to the digests observation decided on. prepareView
+// reads every source it emits again and refuses with `mixed-read` when the
+// bytes it gets are not the pinned ones, so an emitted note never carries a
+// stale digest. A note reused from the preparation cache is not read again:
+// its pinned digest is unchanged and the cached bytes are the ones that digest
+// describes, so bytes that drift under an unchanged pin are not consulted
+// until observation hashes the file again (the same bound as the graph stage).
+export function captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt }) {
+  const roots = new Map((project.repos ?? []).filter((repo) => !repo.external).map((repo) => [repo.name, repo.path]))
+  const absolute = (repoId, relative) => {
+    const root = roots.get(repoId)
+    if (!root) refuse('source-not-in-snapshot', 'a node names a repository the project does not enrol')
+    return path.join(root, ...relative.split('/'))
+  }
+  const byRepo = new Map([...roots.keys()].map((repoId) => [repoId, new Map()]))
+  // Every node, and every asset a view may copy. A withheld asset is never pinned: it is in no snapshot document.
+  const pinned = [...graph.nodes, ...(Array.isArray(graph.assets) ? graph.assets.filter((asset) => asset.eligible === true) : [])]
+  for (const item of pinned) {
+    if (!byRepo.has(item.repo)) refuse('source-not-in-snapshot', 'the graph names a repository the project does not enrol')
+    const observed = index.get(sourceKey(item.repo, item.path))
+    const facts = observed?.digest ? observed : readFileFacts(absolute(item.repo, item.path))
+    if (!facts) refuse('mixed-read', 'a file the graph read is no longer there')
+    byRepo.get(item.repo).set(item.path, { path: item.path, rawDigest: facts.digest, byteLength: facts.byteLength })
+  }
+  const repositories = [...byRepo].sort(([left], [right]) => compareText(left, right))
+    .map(([repoId, files]) => ({ repoId, head: null, dirty: true, files: [...files.values()].sort((left, right) => compareText(left.path, right.path)) }))
+  // Embeds and assets are part of what was read: an embed that changes alone yields another snapshot.
+  const graphDigest = sha256Digest(Buffer.from(JSON.stringify([graph.nodes, graph.edges, graph.embeds ?? [], graph.assets ?? []])))
+  const identity = createHash('sha256').update(JSON.stringify([workspaceId, graphDigest, configDigest, repositories])).digest('hex').slice(0, 32)
+  return {
+    document: {
+      schema: 'atelier-obsidian-source-snapshot/v1',
+      contractVersion: '1.0.0',
+      snapshotId: `snap-${identity}`,
+      workspaceId,
+      capturedAt,
+      readConsistency: 'single-read',
+      graphPin: { graphDigest, nodeCount: graph.nodes.length, edgeCount: graph.edges.length },
+      versions: { source: '1', config: configDigest.slice('sha256:'.length, 'sha256:'.length + 16), emitter: EMITTER_VERSION },
+      repositories,
+    },
+    graph,
+    readSource: (repoId, relative) => readFileBytes(absolute(repoId, relative)),
+  }
+}
+
+// The engine keeps one graph file cache and one preparation cache per scope
+// for as long as it runs, and hands them to buildGraph and prepareView on
+// every tick, so a tick after a one-note change parses that source and emits
+// that note and reuses the rest. Both caches are derived, in-memory state: a
+// test may replace either seam with `() => null` to build or prepare in full.
+export function createProductionSeams() {
+  return { buildGraph, captureSnapshot, profileFor, prepareView, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
+}

package/src/runtime/obsidian/private-lock.mjs

@@ -0,0 +1,156 @@
+import { createHash, randomBytes as cryptoRandomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import { hostname } from 'node:os'
+import path from 'node:path'
+import { isPendingPrivateWrite, publishPrivateFile } from '../../project/durable-state.mjs'
+import { ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
+import { closedObject, isoTime } from './documents.mjs'
+import { ObsidianMaintenanceRefusal } from './errors.mjs'
+
+// A private lock between processes of one machine, as a directory of owner
+// tickets:
+//
+//   <lock>/000000000007.json      the ticket of generation 7: who holds it
+//   <lock>/000000000007.released  the same bytes: generation 7 was given back
+//
+// Only the highest generation means anything. A ticket is published with a
+// non-overwriting hard link, so of two contenders for generation N+1 exactly
+// one wins; the winner then confirms that nothing higher exists (a contender
+// that decided on an old listing finds the newer ticket and withdraws) and
+// removes every lower generation, so a lock taken on every tick does not grow.
+//
+// Nothing is ever taken from a holder that may still be working. A ticket
+// whose holder did not release it is passed over only with proof:
+//
+//   - its process is gone; or
+//   - it is a maintenance service that recorded where it answers health, and
+//     that address refuses connections or answers as another runtime or PID.
+//     A service listens from before its first tick until after its last, so
+//     either answer proves the recorded runtime is not ticking.
+//
+// No answer in time proves nothing (a busy holder answers late). A ticket
+// from another machine, an unreadable ticket, an unknown file, or a live
+// process that recorded no health address all need a person: see
+// `inspectPrivateGenerationLock` and docs/local-services.md.
+
+export const LOCK_TICKET_SCHEMA = 'atelier-obsidian-lock-ticket/v1'
+export const ENGINE_LOCK_DIRECTORY = path.join('state', 'maintenance', 'engine-lock')
+
+const TICKET_NAME = /^(\d{12})\.(json|released)$/
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const LOOPBACK = new Set(['127.0.0.1', '::1'])
+const MAX_GENERATION = 999999999999
+
+export const machineDigest = () => createHash('sha256').update(hostname()).digest('hex')
+
+export function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true } catch (error) { return error.code !== 'ESRCH' }
+}
+
+function validateTicket(document, workspaceId) {
+  closedObject(document, { required: ['schema', 'workspaceId', 'purpose', 'pid', 'machine', 'nonce', 'acquiredAt', 'service'] }, 'invalid-lock-ticket', 'a lock ticket')
+  const ok = document.schema === LOCK_TICKET_SCHEMA && document.workspaceId === workspaceId && typeof document.purpose === 'string' && IDENTIFIER.test(document.purpose)
+    && Number.isSafeInteger(document.pid) && document.pid > 0 && /^[0-9a-f]{64}$/.test(document.machine) && /^[0-9a-f]{32}$/.test(document.nonce) && typeof document.acquiredAt === 'string'
+  if (!ok) throw new ObsidianMaintenanceRefusal('invalid-lock-ticket', 'a lock ticket is malformed or belongs to another workspace')
+  if (document.service !== null) {
+    closedObject(document.service, { required: ['host', 'port', 'runtimeId'] }, 'invalid-lock-ticket', 'the service of a lock ticket')
+    if (!LOOPBACK.has(document.service.host) || !Number.isInteger(document.service.port) || document.service.port < 1 || document.service.port > 65535 || typeof document.service.runtimeId !== 'string' || !IDENTIFIER.test(document.service.runtimeId)) {
+      throw new ObsidianMaintenanceRefusal('invalid-lock-ticket', 'the service of a lock ticket is malformed')
+    }
+  }
+  return document
+}
+
+// Whether the holder of an unreleased ticket is provably not working any more.
+// `probe` answers { kind: 'refused' | 'health' | ... , body }.
+export function createAbandonmentProof({ probe = null, alive = isProcessAlive, machine = machineDigest(), maxAgeMs = null } = {}) {
+  return async function proveAbandoned(ticket, { nowMs } = {}) {
+    if (ticket.machine !== machine) return { abandoned: false, reason: 'held-on-another-machine' }
+    if (!alive(ticket.pid)) return { abandoned: true, reason: 'holder-process-gone' }
+    if (ticket.pid === process.pid) return { abandoned: false, reason: 'held-by-this-process' }
+    // A purpose whose holder is bounded in time by construction (a start) may name a maximum age.
+    if (maxAgeMs !== null && Number.isFinite(nowMs) && nowMs - Date.parse(ticket.acquiredAt) > maxAgeMs) return { abandoned: true, reason: 'holder-older-than-its-bound' }
+    if (ticket.service === null || typeof probe !== 'function') return { abandoned: false, reason: 'live-process-unproven' }
+    const answer = await probe({ host: ticket.service.host, port: ticket.service.port })
+    if (answer.kind === 'refused') return { abandoned: true, reason: 'service-address-closed' }
+    if (answer.kind === 'health' && (answer.body.runtimeId !== ticket.service.runtimeId || answer.body.pid !== ticket.pid)) return { abandoned: true, reason: 'service-address-answers-as-another-runtime' }
+    return { abandoned: false, reason: answer.kind === 'health' ? 'holder-answers-health' : 'live-process-unproven' }
+  }
+}
+
+function listGenerations(directory) {
+  let names
+  try { names = fs.readdirSync(directory) } catch (error) { if (error.code === 'ENOENT') return { names: [], highest: 0, unknown: null }; throw error }
+  names = names.filter((name) => !isPendingPrivateWrite(name))
+  const unknown = names.find((name) => !TICKET_NAME.test(name)) ?? null
+  const highest = names.reduce((most, name) => Math.max(most, Number(TICKET_NAME.exec(name)?.[1] ?? 0)), 0)
+  return { names, highest, unknown }
+}
+
+const ticketName = (generation, kind) => `${String(generation).padStart(12, '0')}.${kind}`
+
+// Read-only. { available, reason, generation, ticket }
+export async function inspectPrivateGenerationLock({ directory, workspaceId, proveAbandoned = createAbandonmentProof(), nowMs = Date.now() }) {
+  const { names, highest, unknown } = listGenerations(directory)
+  if (unknown) return { available: false, reason: 'unknown-lock-file', generation: highest, ticket: null }
+  if (highest === 0) return { available: true, reason: 'unused', generation: 0, ticket: null }
+  let body
+  let ticket
+  try {
+    body = readRegularTextNoFollow(path.join(directory, ticketName(highest, 'json')))
+    ticket = validateTicket(JSON.parse(body), workspaceId)
+  } catch (error) {
+    // Pruned or replaced between the listing and the read: somebody is working here right now.
+    return { available: false, reason: error.code === 'ENOENT' ? 'lock-changed-while-reading' : 'unreadable-lock-ticket', generation: highest, ticket: null }
+  }
+  if (names.includes(ticketName(highest, 'released'))) {
+    let released
+    try { released = readRegularTextNoFollow(path.join(directory, ticketName(highest, 'released'))) } catch { released = null }
+    return released === body ? { available: true, reason: 'released', generation: highest, ticket } : { available: false, reason: 'release-identity-differs', generation: highest, ticket }
+  }
+  const proof = await proveAbandoned(ticket, { nowMs })
+  return { available: proof.abandoned, reason: proof.reason, generation: highest, ticket }
+}
+
+// { acquired: true, generation, release() } or { acquired: false, reason, holder }.
+// Never waits and never throws for a lock that is merely held.
+export async function acquirePrivateGenerationLock({ workspaceRoot, directory, workspaceId, purpose, service = null, clock, proveAbandoned, randomBytes = cryptoRandomBytes }) {
+  const contained = ensureContainedPrivateDirectory({ workspaceRoot, directory, label: 'private lock' })
+  const acquiredAt = isoTime(clock)
+  const status = await inspectPrivateGenerationLock({ directory: contained, workspaceId, proveAbandoned, nowMs: Date.parse(acquiredAt) })
+  const holder = status.ticket ? { pid: status.ticket.pid, purpose: status.ticket.purpose, runtimeId: status.ticket.service?.runtimeId ?? null } : null
+  if (!status.available) return { acquired: false, reason: status.reason, holder }
+  if (status.generation >= MAX_GENERATION) return { acquired: false, reason: 'lock-generations-exhausted', holder }
+  const generation = status.generation + 1
+  const ticket = validateTicket({ schema: LOCK_TICKET_SCHEMA, workspaceId, purpose, pid: process.pid, machine: machineDigest(), nonce: randomBytes(16).toString('hex'), acquiredAt, service }, workspaceId)
+  const body = JSON.stringify(ticket)
+  const file = path.join(contained, ticketName(generation, 'json'))
+  try { publishPrivateFile(file, body) } catch (error) {
+    if (error.code === 'EEXIST') return { acquired: false, reason: 'lost-the-race-for-this-generation', holder: null }
+    throw error
+  }
+  // Confirm: a decision made on an old listing finds the newer ticket here and withdraws.
+  const after = listGenerations(contained)
+  if (after.highest !== generation) {
+    try { fs.unlinkSync(file) } catch { /* a lower generation is ignored and pruned by the next holder */ }
+    return { acquired: false, reason: 'a-newer-holder-exists', holder: null }
+  }
+  for (const name of after.names) {
+    if (Number(TICKET_NAME.exec(name)[1]) < generation) try { fs.unlinkSync(path.join(contained, name)) } catch { /* pruned by somebody else */ }
+  }
+  let released = false
+  return {
+    acquired: true,
+    generation,
+    release() {
+      if (released) return false
+      released = true
+      let current
+      try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') return false; throw error }
+      // Taken over after a proof of abandonment (this process was thought gone): nothing here is ours to release.
+      if (current !== body) return false
+      publishPrivateFile(path.join(contained, ticketName(generation, 'released')), body)
+      return true
+    },
+  }
+}

package/src/runtime/obsidian/process-identity.mjs

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import { executableIdentity } from './service-record.mjs'
+
+// Whether a live PID provably runs the executable a service record names,
+// without that process answering anything. Used for one decision only: telling
+// a service of ours that is too busy to answer health (`busy`) from a listener
+// nobody proved (`occupied`). Whatever cannot be established is "not proven".
+//
+//   Linux    /proc/<pid>/cmdline, the exact argument list
+//   macOS    /bin/ps -ww -o args= -p <pid>, one line of text
+//   Windows  not established: a busy service reads as `occupied` there
+//
+// Nothing is looked up by name, port or pattern: the one PID asked about is
+// the PID the owner-only record names.
+
+const RUNTIME_ARGUMENT = '--runtime-id='
+
+// string[] (exact arguments), string (one joined line) or null.
+export function readProcessCommandLine(pid, { platform = process.platform, readFile = fs.readFileSync, run = execFileSync } = {}) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null
+  try {
+    if (platform === 'linux') {
+      const words = readFile(`/proc/${pid}/cmdline`, 'utf8').split('\u0000').filter((word) => word !== '')
+      return words.length > 0 ? words : null
+    }
+    if (platform === 'darwin' || platform === 'freebsd' || platform === 'openbsd') {
+      const line = run('/bin/ps', ['-ww', '-o', 'args=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, maxBuffer: 1024 * 1024 }).trim()
+      return line === '' ? null : line
+    }
+  } catch { /* not established */ }
+  return null
+}
+
+// Pure. The command line must name the recorded entry module, and a runtime
+// identifier it carries must be the recorded one.
+export function commandLineNamesRecord(commandLine, record) {
+  const entry = record?.executable?.path
+  if (typeof entry !== 'string' || entry === '' || typeof record.runtimeId !== 'string') return false
+  if (Array.isArray(commandLine)) {
+    if (!commandLine.slice(1).includes(entry)) return false
+    const named = commandLine.filter((word) => word.startsWith(RUNTIME_ARGUMENT)).map((word) => word.slice(RUNTIME_ARGUMENT.length))
+    return named.every((runtimeId) => runtimeId === record.runtimeId)
+  }
+  if (typeof commandLine !== 'string') return false
+  if (!` ${commandLine} `.includes(` ${entry} `)) return false
+  const named = [...commandLine.matchAll(/(?:^|\s)--runtime-id=(\S+)/g)].map((match) => match[1])
+  return named.every((runtimeId) => runtimeId === record.runtimeId)
+}
+
+// The recorded executable is still the bytes that were recorded, and the live
+// process was started on it.
+export function processRunsRecordedExecutable(record, { commandLineOf = readProcessCommandLine, identityOf = executableIdentity } = {}) {
+  try {
+    if (identityOf(record.executable.path).digest !== record.executable.digest) return false
+  } catch { return false }
+  return commandLineNamesRecord(commandLineOf(record.pid), record)
+}

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

@@ -0,0 +1,66 @@
+import http from 'node:http'
+import { isPlainObject } from './documents.mjs'
+import { refuse } from './errors.mjs'
+
+// The only client of the maintenance service, and the only place this runtime
+// opens a connection. It connects to a literal loopback address and nothing
+// else: a hostname, a wildcard address or any other value refuses before a
+// socket exists, so no name is ever resolved and nothing leaves the machine.
+
+export const LOOPBACK_HOSTS = Object.freeze(['127.0.0.1', '::1'])
+export const HEALTH_SCHEMA = 'atelier-obsidian-service-health/v1'
+// Long enough for a closed port to refuse on every platform: some answer a refused loopback connection only after retrying for about two seconds.
+export const DEFAULT_PROBE_TIMEOUT_MS = 5000
+const MAX_RESPONSE_BYTES = 64 * 1024
+
+export const authorityOf = (host, port) => (host === '::1' ? `[::1]:${port}` : `${host}:${port}`)
+
+function assertLoopback(host, port) {
+  if (!LOOPBACK_HOSTS.includes(host)) refuse('service-address-not-loopback', 'the maintenance service is reached at a literal loopback address only')
+  if (!Number.isInteger(port) || port < 1 || port > 65535) refuse('service-address-not-loopback', 'the maintenance service port is not a port')
+}
+
+// { kind: 'refused' }              nothing listens there
+// { kind: 'timeout' }              something accepted the connection and did not answer in time
+// { kind: 'error', code }          the connection failed some other way
+// { kind: 'response', statusCode, body }   body is parsed JSON, or null
+export function requestLoopback({ host, port, method = 'GET', path = '/health', bearer = null, payload = null, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS }) {
+  assertLoopback(host, port)
+  return new Promise((resolve) => {
+    let settled = false
+    const settle = (value) => { if (!settled) { settled = true; resolve(value) } }
+    const text = payload === null ? null : JSON.stringify(payload)
+    const headers = { Host: authorityOf(host, port), Connection: 'close', ...(bearer === null ? {} : { Authorization: `Bearer ${bearer}` }), ...(text === null ? {} : { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(text) }) }
+    // The target is one of two literals, whatever was passed in.
+    const request = http.request({ host: host === '::1' ? '::1' : '127.0.0.1', port, family: host === '::1' ? 6 : 4, method, path, headers, agent: false, timeout: timeoutMs }, (response) => {
+      const chunks = []
+      let size = 0
+      response.on('data', (chunk) => {
+        size += chunk.length
+        if (size > MAX_RESPONSE_BYTES) { request.destroy(); settle({ kind: 'response', statusCode: response.statusCode, body: null }) } else chunks.push(chunk)
+      })
+      response.on('end', () => {
+        let body = null
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { body = null }
+        settle({ kind: 'response', statusCode: response.statusCode, body: isPlainObject(body) ? body : null })
+      })
+      response.on('error', () => settle({ kind: 'error', code: 'response-failed' }))
+    })
+    const timer = setTimeout(() => { request.destroy(); settle({ kind: 'timeout' }) }, timeoutMs)
+    request.on('timeout', () => { request.destroy(); settle({ kind: 'timeout' }) })
+    request.on('error', (error) => settle(error.code === 'ECONNREFUSED' ? { kind: 'refused' } : { kind: 'error', code: error.code ?? 'request-failed' }))
+    request.on('close', () => clearTimeout(timer))
+    request.end(text ?? undefined)
+  })
+}
+
+// { kind: 'health', body } only for a well-formed health document; any other
+// answer on the port is { kind: 'foreign' }: occupied, by something else.
+export async function probeHealth({ host, port, timeoutMs }) {
+  const answer = await requestLoopback({ host, port, method: 'GET', path: '/health', ...(timeoutMs === undefined ? {} : { timeoutMs }) })
+  if (answer.kind !== 'response') return answer
+  const body = answer.body
+  const wellFormed = answer.statusCode === 200 && body?.schema === HEALTH_SCHEMA && typeof body.serviceName === 'string' && typeof body.workspaceId === 'string' && typeof body.runtimeId === 'string'
+    && Number.isInteger(body.pid) && typeof body.host === 'string' && Number.isInteger(body.port) && typeof body.executableDigest === 'string'
+  return wellFormed ? { kind: 'health', body } : { kind: 'foreign', statusCode: answer.statusCode }
+}

package/src/runtime/obsidian/service-entry-path.mjs

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url'
+
+// The absolute path of the maintenance service entry, kept in its own module
+// so that nothing which needs the path has to import the entry itself. The
+// entry awaits at top level (it loads the command contributions before it
+// serves), and a module that both reaches it through a static import and is
+// itself reached by that load would deadlock the process: the contribution
+// graph waits for the entry, the entry waits for the contribution graph.
+export const SERVICE_ENTRY_PATH = fileURLToPath(new URL('./service-main.mjs', import.meta.url))

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { firstString, parseArgs, resolveProjectConfig } from '../../project/config.mjs'
+import { runMaintenanceService } from './service.mjs'
+
+// The process of the maintenance service. `start` runs it as a child; a unit
+// installed at the operating-system level runs it with `--startup`.
+//
+//   --project=<absolute atelier.project.json>   required
+//   --data-root=<absolute directory>            optional; otherwise the pointer, the overlay or the platform default
+//   --runtime-id=<identifier>                   given by `start`, so it can recognise the child it created
+//   --interval-ms=<milliseconds>                optional
+//   --startup                                   run by an operating-system unit; needs a consent that covers startup
+//   --adapter=obsidian-cli                      the editor adapter; there is no default
+//
+// Without `--adapter` the process refuses before it listens or ticks: reaching
+// a running app is a decision of whoever starts the service, never a default.
+
+// Reaching a real app happens here and nowhere else in the service: the
+// production probe and the CLI transport are imported only once `--adapter`
+// selected them. The editor adapter is constructed only for an app that meets
+// the minimum version; below it, or when the version cannot be read, the
+// factory refuses, the engine records that reason and nothing is published.
+const ADAPTERS = Object.freeze({
+  'obsidian-cli': async () => {
+    const [{ createObsidianCliAdapter }, { createProductionAppProbe }, { createQualifiedAdapterFactory }] = await Promise.all([
+      import('../../projection/obsidian/publication/transport.mjs'), import('./app-production-seams.mjs'), import('./app-capability.mjs'),
+    ])
+    const adapterFactory = createQualifiedAdapterFactory({ appProbe: createProductionAppProbe(), createAdapter: () => createObsidianCliAdapter() })
+    return { adapterFactory, appStatus: () => { const known = adapterFactory.lastQualification(); return known === null ? null : { outcome: known.outcome, reason: known.reason, version: known.version, floor: known.floor } } }
+  },
+})
+
+import { SERVICE_ENTRY_PATH } from './service-entry-path.mjs'
+
+export { SERVICE_ENTRY_PATH }
+export const EXIT_REFUSED = 2
+
+const log = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
+
+// The common body of a service process: run, end cleanly on a signal, exit 0
+// after a clean stop and EXIT_REFUSED when the service refused to run.
+export async function runServiceProcess(options) {
+  try {
+    const service = await runMaintenanceService({ log, ...options })
+    for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { void service.shutdown(`signal-${signal}`) })
+    await service.done
+    // Everything durable is on disk by now; nothing left over may keep a stopped service's PID alive.
+    process.exit(0)
+  } catch (error) {
+    log({ at: new Date().toISOString(), event: 'refused', code: error?.code ?? 'untyped-error', message: String(error?.message ?? error) })
+    process.exitCode = typeof error?.code === 'string' ? EXIT_REFUSED : 1
+  }
+}
+
+export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
+  const args = parseArgs(argv)
+  const configPath = firstString(args.project)
+  if (!configPath || !path.isAbsolute(configPath)) throw Object.assign(new Error('--project must be the absolute path of a project configuration'), { code: 'service-arguments-invalid' })
+  const dataRoot = firstString(args['data-root']) ?? undefined
+  const intervalMs = args['interval-ms'] === undefined ? undefined : Number(args['interval-ms'])
+  if (intervalMs !== undefined && (!Number.isInteger(intervalMs) || intervalMs < 1)) throw Object.assign(new Error('--interval-ms must be a positive integer'), { code: 'service-arguments-invalid' })
+  return {
+    loadProject: () => resolveProjectConfig({ argv: [`--project=${configPath}`], cwd: path.dirname(configPath), env, writeLocalState: false }),
+    ...(dataRoot === undefined ? {} : { dataRoot }), ...(intervalMs === undefined ? {} : { intervalMs }),
+    ...(firstString(args['runtime-id']) ? { runtimeId: firstString(args['runtime-id']) } : {}),
+    startup: args.startup === true, adapter: firstString(args.adapter),
+  }
+}
+
+const invokedDirectly = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)) } catch { return false } })()
+
+if (invokedDirectly) {
+  let options = null
+  try {
+    options = serviceOptionsFromArgv(process.argv.slice(2))
+    if (!options.adapter || !Object.hasOwn(ADAPTERS, options.adapter)) throw Object.assign(new Error('no editor adapter was selected; pass --adapter explicitly'), { code: 'service-adapter-not-selected' })
+  } catch (error) {
+    log({ at: new Date().toISOString(), event: 'refused', code: error.code ?? 'untyped-error', message: error.message })
+    process.exitCode = EXIT_REFUSED
+    options = null
+  }
+  if (options) {
+    const { adapter, ...rest } = options
+    const [{ loadContributions }, { createObsidianRegistry }] = await Promise.all([import('./contributions.mjs'), import('./extension-points.mjs')])
+    const registry = createObsidianRegistry({ contributions: await loadContributions() })
+    await runServiceProcess({ ...rest, entryPath: SERVICE_ENTRY_PATH, ...(await ADAPTERS[adapter]()), engineOptions: { extensions: registry.extensions } })
+  }
+}