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

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-main.mjs

@@ -0,0 +1,89 @@
+#!/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 } } }
+  },
+})
+
+export const SERVICE_ENTRY_PATH = fileURLToPath(import.meta.url)
+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(SERVICE_ENTRY_PATH) } 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 } })
+  }
+}

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