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

package/src/runtime/obsidian/errors.mjs

@@ -0,0 +1,14 @@
+// Every refusal of the maintenance runtime is this one typed error. `code` is
+// the stable, machine-readable reason; `detail` never carries note bytes.
+export class ObsidianMaintenanceRefusal extends Error {
+  constructor(code, message, detail = {}) {
+    super(`${code}: ${message}`)
+    this.name = 'ObsidianMaintenanceRefusal'
+    this.code = code
+    this.detail = detail
+  }
+}
+
+export function refuse(code, message, detail) {
+  throw new ObsidianMaintenanceRefusal(code, message, detail)
+}

package/src/runtime/obsidian/extension-points.mjs

@@ -0,0 +1,103 @@
+import { refuse } from './errors.mjs'
+
+// The neutral registration point for the operations that later work supplies:
+// the source apply operation and the proposal adapter. A registry is a plain
+// value created by whoever composes the engine and handed to it. There is no
+// module-level registry, so nothing registered in one engine (or one test) is
+// visible to another, and no shared dispatch file has to be edited to add an
+// implementation.
+
+export const EXTENSION_KINDS = Object.freeze(['apply-operation', 'proposal-adapter'])
+
+// What an apply operation may answer. Anything else is recorded as a failure:
+// an unknown answer is never read as success.
+export const APPLY_RESULT_STATUSES = Object.freeze(['applied', 'apply-unavailable', 'refused', 'conflict', 'failed'])
+
+const REQUIRED_METHODS = Object.freeze({
+  'apply-operation': ['apply'],
+  'proposal-adapter': ['propose'],
+})
+
+// Until a source apply operation is registered, automatic mode has nothing to
+// call. It says so; it does not pretend an edit was applied.
+export const UNAVAILABLE_APPLY_OPERATION = Object.freeze({
+  id: 'atelier.apply-unavailable',
+  async apply() {
+    return { status: 'apply-unavailable', code: 'no-apply-operation-registered' }
+  },
+})
+
+export function createMaintenanceExtensions() {
+  const registered = new Map()
+  return Object.freeze({
+    register(kind, implementation) {
+      if (!EXTENSION_KINDS.includes(kind)) refuse('unknown-extension-kind', 'only the declared extension kinds can be registered', { kind: String(kind) })
+      if (registered.has(kind)) refuse('extension-already-registered', 'an implementation is already registered for this extension kind', { kind })
+      const valid = implementation !== null && typeof implementation === 'object' && typeof implementation.id === 'string' && implementation.id !== ''
+        && REQUIRED_METHODS[kind].every((method) => typeof implementation[method] === 'function')
+      if (!valid) refuse('invalid-extension', `an ${kind} needs an id and its operation`, { kind })
+      registered.set(kind, implementation)
+      return implementation.id
+    },
+    get: (kind) => registered.get(kind) ?? null,
+    applyOperation: () => registered.get('apply-operation') ?? UNAVAILABLE_APPLY_OPERATION,
+    describe: () => EXTENSION_KINDS.map((kind) => ({ kind, id: registered.get(kind)?.id ?? null })),
+  })
+}
+
+// Normalizes whatever an apply operation returned or threw into one typed
+// result. The engine persists exactly this.
+export function normalizeApplyResult(value) {
+  if (value !== null && typeof value === 'object' && APPLY_RESULT_STATUSES.includes(value.status)) {
+    return { status: value.status, code: typeof value.code === 'string' ? value.code.slice(0, 120) : value.status }
+  }
+  return { status: 'failed', code: 'invalid-apply-result' }
+}
+
+// ---------------------------------------------------------------------------
+// Sub-operations of the `obsidian` command, and contributions
+// ---------------------------------------------------------------------------
+
+// Later work adds `obsidian <operation>` sub-operations the same way it adds
+// an apply operation: by registering on a value, never by editing the command
+// dispatcher. A built-in name cannot be taken, with one exception: `apply` is
+// a placeholder that only reports `apply-unavailable`, and the work that ships
+// an apply operation replaces it.
+const OPERATION_NAME = /^[a-z][a-z0-9-]{0,31}$/
+// The operations the command ships. The service composes the same registry, so both refuse the same contributions.
+export const BUILT_IN_OPERATIONS = Object.freeze(['status', 'scope', 'audience', 'mode', 'policy', 'service', 'open', 'apply', 'help'])
+export const REPLACEABLE_OPERATIONS = Object.freeze(['apply'])
+
+export function createCommandOperations({ reserved = [] } = {}) {
+  const registered = new Map()
+  return Object.freeze({
+    register(operation) {
+      const valid = operation !== null && typeof operation === 'object' && typeof operation.name === 'string' && OPERATION_NAME.test(operation.name)
+        && typeof operation.summary === 'string' && operation.summary !== '' && typeof operation.run === 'function'
+      if (!valid) refuse('invalid-extension', 'a command operation needs a name, a summary and run()')
+      // Optional: the shared options of the command this operation takes beyond the ones every operation takes.
+      if (operation.options !== undefined && !(Array.isArray(operation.options) && operation.options.every((item) => typeof item === 'string'))) refuse('invalid-extension', 'a command operation declares its options as a list of names')
+      if (reserved.includes(operation.name) && !REPLACEABLE_OPERATIONS.includes(operation.name)) refuse('operation-name-reserved', 'a built-in operation cannot be replaced', { name: operation.name })
+      if (registered.has(operation.name)) refuse('extension-already-registered', 'an operation of this name is already registered', { name: operation.name })
+      registered.set(operation.name, operation)
+      return operation.name
+    },
+    get: (name) => registered.get(name) ?? null,
+    describe: () => [...registered.values()].map(({ name, summary }) => ({ name, summary })).sort((left, right) => (left.name < right.name ? -1 : 1)),
+  })
+}
+
+// One registry per composition: the maintenance extensions the engine reads
+// and the operations the command reads. A contribution is
+// `{ id, register({ extensions, operations }) }`; each is applied once, in order.
+export function createObsidianRegistry({ reservedOperations = BUILT_IN_OPERATIONS, contributions = [] } = {}) {
+  const registry = Object.freeze({ extensions: createMaintenanceExtensions(), operations: createCommandOperations({ reserved: reservedOperations }) })
+  const applied = []
+  for (const contribution of contributions) {
+    if (contribution === null || typeof contribution !== 'object' || typeof contribution.id !== 'string' || contribution.id === '' || typeof contribution.register !== 'function') refuse('invalid-extension', 'a contribution needs an id and register()')
+    if (applied.includes(contribution.id)) refuse('extension-already-registered', 'a contribution of this id was already applied', { id: contribution.id })
+    contribution.register(registry)
+    applied.push(contribution.id)
+  }
+  return Object.freeze({ ...registry, contributions: Object.freeze(applied) })
+}

package/src/runtime/obsidian/index.mjs

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

package/src/runtime/obsidian/lifecycle.mjs

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