@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

package/src/runtime/obsidian/service.mjs

@@ -1,7 +1,9 @@
+import { prepareViewCooperatively } from '../../projection/obsidian/materialize/prepare-view.mjs'
 import { randomBytes as cryptoRandomBytes } from 'node:crypto'
 import fs from 'node:fs'
+import path from 'node:path'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
-import { ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
 import { prepareView as productionPrepareView } from '../../projection/obsidian/materialize/index.mjs'
 import { preparePluginFiles } from '../../projection/obsidian/plugin-bridge/bundle.mjs'
 import { publishView as productionPublishView } from '../../projection/obsidian/publication/publisher.mjs'
@@ -21,6 +23,7 @@ import {
 import { createServiceServer } from './service-server.mjs'
 import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs'
 import { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
+import { createLoadReport, createViewPermission } from './view-permission.mjs'
 import { createFsWatcherFactory } from './watchers.mjs'
 
 // The maintenance service of one workspace, inside one process.
@@ -48,12 +51,33 @@ import { createFsWatcherFactory } from './watchers.mjs'
 //
 // `adapterFactory` has no default here either: whoever starts the service
 // decides whether it may reach a running app.
+//
+// Started by a login item (`startup`), the service also asks `releaseWatch`
+// after every tick whether the package it runs from changed on disk; when it
+// did, it finishes that tick and shuts down with the reason RELEASE_CHANGED,
+// which its process turns into an exit code the service manager restarts, on
+// the new release (release-watch.mjs, service-main.mjs).
 
 export const SERVICE_STATUS_SCHEMA = 'atelier-obsidian-service-status/v1'
 export const DEFAULT_SHUTDOWN_GRACE_MS = 30 * 1000
+export const RELEASE_CHANGED = 'release-changed'
+
+// What of a project its workspace is resolved from, as a project that holds nothing else: the folder its pointer is
+// under (readLocalPointer), the data root its local overlay prefers (resolveDataRoot), and the repositories private
+// state may not overlap (protectedRoots). resolveServiceWorkspace reads these and nothing else of a project, so two
+// projects with the same inputs resolve alike, and the plugin's status read compares exactly them (view-permission.mjs).
+export function serviceWorkspaceInputs(project) {
+  const preference = project?.localOverlay?.overlay?.preferences?.[OBSIDIAN_EXT_KEY]
+  return {
+    ...(typeof project?.configDir === 'string' ? { configDir: project.configDir } : {}),
+    repos: (Array.isArray(project?.repos) ? project.repos : []).map((repo) => ({ path: repo?.path, external: Boolean(repo?.external) })),
+    localOverlay: { overlay: { preferences: preference === undefined ? {} : { [OBSIDIAN_EXT_KEY]: preference } } },
+  }
+}
 
 // Where a workspace keeps its private state, without creating an identity.
-export function resolveServiceWorkspace({ project, dataRoot, env = process.env, platform = process.platform, create = false }) {
+export function resolveServiceWorkspace({ project: whole, dataRoot, env = process.env, platform = process.platform, create = false }) {
+  const project = serviceWorkspaceInputs(whole)
   const pointer = readLocalPointer(project)
   if (pointer === null) return null
   const requested = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), pointer.workspaceId)
@@ -79,18 +103,37 @@ async function writeRecordPatiently(input) {
 
 export async function runMaintenanceService(options = {}) {
   const {
-    loadProject, dataRoot, adapterFactory, entryPath, runtimeId = `rt-${cryptoRandomBytes(16).toString('hex')}`, startup = false,
+    loadProject, dataRoot,
+    // What the workspace is resolved from at once, where the loader may answer a promise (locatePersonalHome): the service
+    // starts from it, and the engine awaits the loader at its ticks. Without it, the loader's own first answer is used.
+    locateProject = null, adapterFactory, entryPath, runtimeId = `rt-${cryptoRandomBytes(16).toString('hex')}`, startup = false,
     intervalMs = DEFAULT_TICK_INTERVAL_MS, maxBackoffMs = Math.max(DEFAULT_MAX_BACKOFF_MS, intervalMs), shutdownGraceMs = DEFAULT_SHUTDOWN_GRACE_MS,
     clock = () => new Date(), log = () => {}, pid = process.pid, randomBytes = cryptoRandomBytes, env = process.env, platform = process.platform,
     engineOptions = {}, createEngine = createMaintenanceEngine,
     // What the adapter factory last learned about the installed app, when it qualifies one. Codes and versions only.
     appStatus = null,
+    // Under `startup`: { changed() } (createReleaseWatch), asked after every tick.
+    releaseWatch = null,
+    // The entry as this process was started by it (`process.argv[1]`), when that is not its real path: a login item
+    // names the installed entry by its path. It is recorded, so the process table can still prove this process ours.
+    invokedAs = null,
   } = options
   if (typeof loadProject !== 'function') throw new TypeError('the service needs loadProject')
   if (typeof adapterFactory !== 'function') throw new TypeError('the service needs an adapterFactory')
   if (typeof entryPath !== 'string') throw new TypeError('the service needs the path of its entry module')
 
-  const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+  // The workspace comes from the project the loader answers now, or the locator. A loader without a locator, or a locator,
+  // that answers a promise is refused, typed, before anything is read from the promise (it has no pointer, no overlay and
+  // no repositories); its answer is let go unread. A located project names its folder, or is refused.
+  const project = locateProject === null ? loadProject() : locateProject()
+  if (typeof project?.then === 'function') {
+    // Let go without calling a `then` of its own, which a promise whose `constructor` reads as this realm's `Promise`
+    // may carry and which may throw; any other thenable is adopted, its `then` called once.
+    Promise.prototype.then.call(Promise.resolve(project), undefined, () => {})
+    refuse('service-loader-not-synchronous', 'the service resolves its workspace from a project its loader answers at once; a loader that answers a promise is not supported when the service starts')
+  }
+  if (locateProject !== null && typeof project?.configDir !== 'string') refuse('service-locator-invalid', 'the locator of this service answered no folder to resolve its workspace from')
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
   if (!workspace?.workspaceRoot) refuse('service-workspace-not-prepared', 'this workspace has no private state yet; `start` prepares it')
   const { workspaceId, workspaceRoot } = workspace
   const settings = readServiceSettings({ workspaceRoot, workspaceId })
@@ -107,6 +150,7 @@ export async function runMaintenanceService(options = {}) {
   }
 
   const executable = executableIdentity(entryPath)
+  const alias = typeof invokedAs === 'string' && path.isAbsolute(invokedAs) && path.resolve(invokedAs) !== executable.path ? path.resolve(invokedAs) : null
   const startedAt = isoTime(clock)
   const identity = { serviceName: serviceNameFor(workspaceId), workspaceId, runtimeId, pid, host, port, executableDigest: executable.digest, startedAt }
   const bearer = randomBytes(32).toString('base64url')
@@ -117,6 +161,10 @@ export async function runMaintenanceService(options = {}) {
   let stopping = false
   let consecutiveFailures = 0
   let lastTick = null
+  // What the last tick that did not fail named each refused view for (refusalCauses). A view the next tick names for the
+  // same reason is not written to the log again: a refusal that lasts (a folder that stays unwritable is tried again at
+  // every tick) is written once, and again when its reason changes or after a tick that failed or did not name it.
+  let refusedLastTick = new Map()
   let settleDone
   const done = new Promise((resolve) => { settleDone = resolve })
 
@@ -126,7 +174,7 @@ export async function runMaintenanceService(options = {}) {
   // view without the plugin for this tick; the view itself is prepared as ever.
   const pluginFor = (scopeId) => {
     try {
-      const vaultRoot = viewVaultRoot(workspaceRoot, scopeId)
+      const vaultRoot = viewVaultRoot(workspaceRoot, scopeId, workspaceId)
       const { choice, community } = decidePluginChoice({ workspaceRoot, workspaceId, scopeId, vaultRoot, clock })
       const off = choice.state === 'off'
       const bearer = ensurePluginBearer({ workspaceRoot, workspaceId, scopeId, randomBytes, clock })
@@ -146,6 +194,14 @@ export async function runMaintenanceService(options = {}) {
     }
   }
   const prepareWithPlugin = (input) => (engineOptions.seams?.prepareView ?? productionPrepareView)({ ...input, plugin: pluginFor(input.scope.scopeId) })
+  // The engine's rule (engine.mjs): a prepareView that is not the one that ships, handed in with the cooperative
+  // preparation left as it ships or absent, prepares the view, synchronously; the engine then gets no cooperative seam.
+  // Nor does it when the cooperative preparation was handed in as null: that says there is none, as it does to the engine.
+  const handed = engineOptions.seams ?? {}
+  const replacedPrepare = typeof handed.prepareView === 'function' && handed.prepareView !== productionPrepareView
+    && (handed.prepareViewCooperatively === undefined || handed.prepareViewCooperatively === prepareViewCooperatively)
+  const cooperative = replacedPrepare || handed.prepareViewCooperatively === null ? null : handed.prepareViewCooperatively ?? prepareViewCooperatively
+  const prepareCooperativelyWithPlugin = cooperative === null ? null : (input) => cooperative({ ...input, plugin: pluginFor(input.scope.scopeId) })
   // An entry offered to a vault and now in place is confirmed: from then on, a list without it is the person's decision.
   const publishAndConfirm = async (input) => {
     const result = await (engineOptions.seams?.publishView ?? productionPublishView)(input)
@@ -160,8 +216,8 @@ export async function runMaintenanceService(options = {}) {
   // The engine also asks the factory itself (`forget`, on a tick somebody asked for): the wrapper keeps its methods.
   const pluginAwareAdapterFactory = Object.assign((input) => adapterFactory({ ...input, pluginReport: typeof input?.scope?.scopeId === 'string' ? pluginReportOf(input.scope.scopeId) : null }), adapterFactory)
   const engine = createEngine({
-    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, publishView: publishAndConfirm },
-    loadProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
+    watcherFactory: createFsWatcherFactory(), ...engineOptions, seams: { ...(engineOptions.seams ?? {}), prepareView: prepareWithPlugin, prepareViewCooperatively: prepareCooperativelyWithPlugin, publishView: publishAndConfirm },
+    loadProject, locateProject, dataRoot, adapterFactory: pluginAwareAdapterFactory, clock, env, platform, lockOwner: { host, port, runtimeId },
   })
 
   const recordIsOurs = () => {
@@ -173,11 +229,20 @@ export async function runMaintenanceService(options = {}) {
     consecutiveFailures = outcome.consecutiveFailures
     if (outcome.ok) {
       lastTick = { at, state: outcome.report.state, reason: outcome.report.reason ?? outcome.report.refusal?.code ?? null }
+      // A view the tick refused for a file-system error: the view's freshness names the refusal, and this line the error.
+      const refused = new Map()
+      for (const item of outcome.report.refusalCauses ?? []) {
+        const reason = JSON.stringify([item.code, item.cause ?? null, item.cleanupCause ?? null])
+        refused.set(item.scopeId, reason)
+        if (refusedLastTick.get(item.scopeId) !== reason) log({ at, event: 'view-refused', scopeId: item.scopeId, code: item.code, ...(item.cause ? { cause: item.cause } : {}), ...(item.cleanupCause ? { cleanupCause: item.cleanupCause } : {}) })
+      }
+      refusedLastTick = refused
       const previous = readLastServiceError({ workspaceRoot, workspaceId })
       if (previous && previous.resolvedAt === null) writeLastServiceError({ workspaceRoot, workspaceId, document: { ...previous, consecutiveFailures: 0, resolvedAt: at } })
       return
     }
     lastTick = { at, state: 'failed', reason: errorCode(outcome.error) }
+    refusedLastTick = new Map()
     // The message may carry a path or a title: it goes to the private log and nowhere else.
     log({ at, event: 'tick-failed', code: errorCode(outcome.error), name: errorName(outcome.error), message: String(outcome.error?.message ?? outcome.error), consecutiveFailures })
     let previous = null
@@ -193,6 +258,18 @@ export async function runMaintenanceService(options = {}) {
       log({ at: isoTime(clock), event: 'plugin-drift-not-read', code: errorCode(error), name: errorName(error) })
     }
   }
+  // What a publication of this tick could not change is no drift to ask about again (plugin-drift.mjs).
+  const settleDriftLooks = () => {
+    try { pluginDrift.settle([...pluginChannel.bearers().keys()]) } catch (error) {
+      log({ at: isoTime(clock), event: 'plugin-drift-not-read', code: errorCode(error), name: errorName(error) })
+    }
+  }
+
+  // A package that changed on disk: another release, loaded module by module into this process from then on.
+  const releaseChanged = () => {
+    if (!startup || releaseWatch === null) return false
+    try { return releaseWatch.changed() === true } catch { return false }
+  }
 
   const loop = createTickLoop({
     intervalMs, maxBackoffMs, onOutcome: recordOutcome,
@@ -200,7 +277,14 @@ export async function runMaintenanceService(options = {}) {
       // The service runs only while its record names it: a replaced or removed record ends it, cleanly.
       if (!recordIsOurs()) { void shutdown('record-no-longer-names-this-runtime'); return { state: 'stopping', reason: 'record-no-longer-names-this-runtime' } }
       askForDriftedViews()
-      return engine.tick()
+      try {
+        const report = await engine.tick()
+        if (report?.state === 'ticked') settleDriftLooks()
+        return report
+      } finally {
+        // After the tick, whether it succeeded or not: the next one runs in a process of the release now on disk.
+        if (!stopping && releaseChanged()) { log({ at: isoTime(clock), event: RELEASE_CHANGED }); void shutdown(RELEASE_CHANGED) }
+      }
     },
   })
 
@@ -218,8 +302,16 @@ export async function runMaintenanceService(options = {}) {
 
   const healthStatus = () => (stopping ? 'stopped' : consecutiveFailures > 0 ? 'degraded' : 'healthy')
 
+  // What is stored about a view is not permission to tell it: the project is asked as it is now (view-permission.mjs).
+  // Its loads are counted for the status document; the log gets a line for those somebody has to see (createLoadReport).
+  const statusLoads = createLoadReport({ write: (entry) => log({ at: isoTime(clock), ...entry }) })
+  const viewPermitted = createViewPermission({
+    loadProject, resolveWorkspace: (loaded) => resolveServiceWorkspace({ project: loaded, dataRoot, env, platform }), workspaceInputsOf: serviceWorkspaceInputs,
+    workspaceId, workspaceRoot, onLoad: statusLoads.onLoad,
+  })
   // One view as the plugin is told about it: its freshness entry with held notes counted, and its open pending edits.
   function pluginStatusOf(scopeId) {
+    if (!viewPermitted(scopeId)) return { view: null, pendingEdits: null }
     let entry = null
     try { entry = stateStore.readFreshness()?.scopes.find((item) => item.scopeId === scopeId) ?? null } catch (error) { if (!isTyped(error)) throw error; return { view: null, pendingEdits: null } }
     let open = null
@@ -248,6 +340,7 @@ export async function runMaintenanceService(options = {}) {
         return {
           schema: SERVICE_STATUS_SCHEMA, service: { ...identity, status: healthStatus() }, loop: loop.state(), lastTick, lastError, freshness: freshnessSummary(),
           plugins: pluginPresence({ sessions: pluginSessions, scopeIds: [...pluginChannel.bearers().keys()], entryOf: (scopeId) => currentPluginChoice({ workspaceRoot, workspaceId, scopeId }).state }),
+          statusLoads: statusLoads.counts(),
           ...(typeof appStatus === 'function' ? { app: appStatus() } : {}),
         }
       },
@@ -296,7 +389,7 @@ export async function runMaintenanceService(options = {}) {
       workspaceRoot, workspaceId,
       record: {
         schema: 'atelier-obsidian-service-state/v1', contractVersion: '1.0.0', workspaceId, serviceName: identity.serviceName, host, port, runtimeId, pid,
-        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath, release: releaseIdentity() } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
+        executable: { path: executable.path, digest: executable.digest, ext: { runner: process.execPath, release: releaseIdentity(), ...(alias === null ? {} : { invokedAs: alias }) } }, stateLocation: servicePaths(workspaceRoot).stateLocation,
         health: { status: 'healthy', checkedAt: startedAt }, consent: settings.consent, ext: { bearer },
       },
     })

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

@@ -4,9 +4,8 @@ import { refuse } from './errors.mjs'
 // Builds the text of an operating-system startup unit for the maintenance
 // service. Pure: it returns text and touches nothing. It writes no file,
 // installs nothing and runs no service manager. Installing a unit is a
-// separate system change that needs a person's explicit authorization and a
-// recorded consent that covers startup; the service refuses `--startup`
-// without one.
+// separate step (login-item.mjs) that a person asks for, and the service
+// refuses `--startup` without a recorded consent that covers startup.
 //
 // Every machine-specific value is an input. Nothing is looked up here: no
 // home directory, no environment, no current directory, no installed path.
@@ -15,17 +14,30 @@ import { refuse } from './errors.mjs'
 //   Linux    a systemd user unit
 //   Windows  refused, typed: startup there has not been qualified
 //
-// The unit runs the service entry in the foreground with `--startup`; the
-// service writes its own record once it listens, exactly as under `start`.
+// The unit runs the service entry in the foreground with `--startup`, in the
+// root directory (never one that could be a vault), with the search path it
+// is given, so the service finds the same programs the person uses. It is
+// restarted after a crash and after an exit with a code the service uses to
+// ask for it (a new release on disk), never after a clean stop and never in a
+// tight loop; a refusal under `--startup` exits cleanly. The service writes
+// its own bounded log; the unit's output file receives only what happens
+// before it can, such as a module that cannot be loaded.
 
 export const STARTUP_PLATFORMS = Object.freeze(['darwin', 'linux'])
 const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const CONTROL = /[\u0000-\u001f\u007f]/
+// Seconds: the least time between two starts, and how long a stop may take before the manager ends the process. The
+// service gives a tick in flight 30 seconds to finish when it is asked to stop.
+const THROTTLE_SECONDS = 60
+const EXIT_TIMEOUT_SECONDS = 60
 
 const xml = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;')
 // systemd: quoted, with its specifier and variable characters doubled.
 const unitWord = (value) => `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('$', '$$$$')}"`
+// systemd: one quoted assignment of Environment=, where `$` has no meaning and only specifiers are expanded.
+const unitAssignment = (name, value) => `"${`${name}=${value}`.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`
 
-function launchdText({ label, words, logPath, workingDirectory }) {
+function launchdText({ label, words, logPath, workingDirectory, searchPath }) {
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
@@ -33,12 +45,15 @@ function launchdText({ label, words, logPath, workingDirectory }) {
     '<dict>',
     '  <key>Label</key>', `  <string>${xml(label)}</string>`,
     '  <key>ProgramArguments</key>', '  <array>', ...words.map((word) => `    <string>${xml(word)}</string>`), '  </array>',
+    ...(searchPath === null ? [] : ['  <key>EnvironmentVariables</key>', '  <dict>', '    <key>PATH</key>', `    <string>${xml(searchPath)}</string>`, '  </dict>']),
+    '  <key>WorkingDirectory</key>', `  <string>${xml(workingDirectory)}</string>`,
     '  <key>RunAtLoad</key>', '  <true/>',
-    // Restarted after a crash, not after a clean stop; a refusal is not retried in a tight loop.
+    // Restarted after a crash or a non-zero exit, not after a clean stop; a refusal exits cleanly and is not retried.
     '  <key>KeepAlive</key>', '  <dict>', '    <key>SuccessfulExit</key>', '    <false/>', '  </dict>',
-    '  <key>ThrottleInterval</key>', '  <integer>60</integer>',
-    '  <key>ProcessType</key>', '  <string>Background</string>',
-    ...(workingDirectory === undefined ? [] : ['  <key>WorkingDirectory</key>', `  <string>${xml(workingDirectory)}</string>`]),
+    '  <key>ThrottleInterval</key>', `  <integer>${THROTTLE_SECONDS}</integer>`,
+    '  <key>ExitTimeOut</key>', `  <integer>${EXIT_TIMEOUT_SECONDS}</integer>`,
+    // Standard, not Background: the service's budgets were measured without the I/O throttling of a background process.
+    '  <key>ProcessType</key>', '  <string>Standard</string>',
     '  <key>StandardOutPath</key>', `  <string>${xml(logPath)}</string>`,
     '  <key>StandardErrorPath</key>', `  <string>${xml(logPath)}</string>`,
     '</dict>',
@@ -47,7 +62,7 @@ function launchdText({ label, words, logPath, workingDirectory }) {
   return `${lines.join('\n')}\n`
 }
 
-function systemdText({ label, words, logPath, workingDirectory }) {
+function systemdText({ label, words, logPath, workingDirectory, searchPath }) {
   const lines = [
     '[Unit]',
     `Description=Atelier Obsidian maintenance (${label.replaceAll(/[^A-Za-z0-9._-]/g, '')})`,
@@ -55,11 +70,13 @@ function systemdText({ label, words, logPath, workingDirectory }) {
     '[Service]',
     'Type=simple',
     `ExecStart=${words.map(unitWord).join(' ')}`,
-    ...(workingDirectory === undefined ? [] : [`WorkingDirectory=${workingDirectory.replaceAll('%', '%%')}`]),
-    // Restarted after a crash; not after a clean stop, and not after a refusal (exit status 2).
+    ...(searchPath === null ? [] : [`Environment=${unitAssignment('PATH', searchPath)}`]),
+    `WorkingDirectory=${workingDirectory.replaceAll('%', '%%')}`,
+    // Restarted after a crash or a non-zero exit; not after a clean stop, and not after a refusal (exit status 2).
     'Restart=on-failure',
-    'RestartSec=60',
+    `RestartSec=${THROTTLE_SECONDS}`,
     'RestartPreventExitStatus=2',
+    `TimeoutStopSec=${EXIT_TIMEOUT_SECONDS}`,
     `StandardOutput=append:${logPath.replaceAll('%', '%%')}`,
     `StandardError=append:${logPath.replaceAll('%', '%%')}`,
     '',
@@ -69,19 +86,40 @@ function systemdText({ label, words, logPath, workingDirectory }) {
   return `${lines.join('\n')}\n`
 }
 
-// { platform, kind, fileName, text }. `args` are the arguments of the entry after `--startup`.
-export function buildStartupAdapter({ platform, label, nodePath, entryPath, args = [], logPath, workingDirectory } = {}) {
+// The search path a unit carries: the entries of `value` (a PATH as the environment holds it) that are absolute
+// directories, in their order, each once, and none inside a temporary directory (`temporary`, absolute prefixes): a
+// relative entry would be resolved in the unit's working directory, and a temporary one (an agent's session, say) is
+// gone after a restart. Pure. Null when nothing is left.
+export function startupSearchPath(value, { temporary = [] } = {}) {
+  if (typeof value !== 'string') return null
+  const inside = (entry) => temporary.some((prefix) => typeof prefix === 'string' && path.posix.isAbsolute(prefix) && (entry === prefix || entry.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`)))
+  const kept = []
+  for (const raw of value.split(':')) {
+    const entry = raw.length > 1 ? raw.replace(/\/+$/, '') : raw
+    if (!path.posix.isAbsolute(entry) || CONTROL.test(entry) || inside(entry) || kept.includes(entry)) continue
+    kept.push(entry)
+  }
+  return kept.length === 0 ? null : kept.join(':')
+}
+
+// { platform, kind, fileName, text }. `args` are the arguments of the entry after `--startup`; `searchPath` is the PATH
+// the unit sets (absolute entries joined by `:`; see startupSearchPath), none when omitted.
+export function buildStartupAdapter({ platform, label, nodePath, entryPath, args = [], logPath, workingDirectory = '/', searchPath = null } = {}) {
   if (platform === 'win32') refuse('startup-platform-unqualified', 'operating-system startup on Windows has not been qualified; no unit is generated for it', { platform })
   if (!STARTUP_PLATFORMS.includes(platform)) refuse('startup-platform-unsupported', 'no startup unit is known for this platform', { platform: String(platform) })
   if (typeof label !== 'string' || !LABEL.test(label)) refuse('startup-adapter-input-invalid', 'the unit label must be a plain identifier')
   const flavor = path.posix
-  for (const [name, value] of [['nodePath', nodePath], ['entryPath', entryPath], ['logPath', logPath], ...(workingDirectory === undefined ? [] : [['workingDirectory', workingDirectory]])]) {
-    if (typeof value !== 'string' || !flavor.isAbsolute(value) || /[\u0000-\u001f]/.test(value)) refuse('startup-adapter-input-invalid', `${name} must be an absolute path given by the caller`, { name })
+  for (const [name, value] of [['nodePath', nodePath], ['entryPath', entryPath], ['logPath', logPath], ['workingDirectory', workingDirectory]]) {
+    if (typeof value !== 'string' || !flavor.isAbsolute(value) || CONTROL.test(value)) refuse('startup-adapter-input-invalid', `${name} must be an absolute path given by the caller`, { name })
+  }
+  if (searchPath !== null && (typeof searchPath !== 'string' || searchPath.split(':').some((entry) => !flavor.isAbsolute(entry) || CONTROL.test(entry)))) {
+    refuse('startup-adapter-input-invalid', 'searchPath must be absolute directories joined by ":"', { name: 'searchPath' })
   }
-  if (!Array.isArray(args) || args.some((word) => typeof word !== 'string' || word === '' || /[\u0000-\u001f]/.test(word))) refuse('startup-adapter-input-invalid', 'args must be a list of plain words')
+  if (!Array.isArray(args) || args.some((word) => typeof word !== 'string' || word === '' || CONTROL.test(word))) refuse('startup-adapter-input-invalid', 'args must be a list of plain words')
   if (args.includes('--startup')) refuse('startup-adapter-input-invalid', '--startup is added by the builder')
   const words = [nodePath, entryPath, '--startup', ...args]
+  const input = { label, words, logPath, workingDirectory, searchPath }
   return platform === 'darwin'
-    ? { platform, kind: 'launchd-user-agent', fileName: `${label}.plist`, text: launchdText({ label, words, logPath, workingDirectory }) }
-    : { platform, kind: 'systemd-user-unit', fileName: `${label}.service`, text: systemdText({ label, words, logPath, workingDirectory }) }
+    ? { platform, kind: 'launchd-user-agent', fileName: `${label}.plist`, text: launchdText(input) }
+    : { platform, kind: 'systemd-user-unit', fileName: `${label}.service`, text: systemdText(input) }
 }

package/src/runtime/obsidian/unheld-evidence.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
+import { realPathOfLocation } from './vault-location.mjs'
+
+// Whether the Obsidian this account runs lists a vault Atelier is filling for
+// the first time, as the publisher's `direct-unheld` path needs to know
+// (publisher.mjs; docs/obsidian-contract.md, "First publication into a vault
+// no Obsidian lists"). Read from the app's settings file, never from the app:
+//
+//   { unlisted: true }                   the file was read, and none of its entries is the vault root, a folder above
+//                                        it or a folder inside it
+//   { unlisted: false, reason, ... }     anything else, which gives no evidence
+//
+// It errs towards "no evidence": a file that is missing (an app that has shown
+// only its starter window writes none), that cannot be read after `attempts`
+// reads `delayMs` apart (the app rewrites it with a plain write, so a reader
+// can find it empty or cut short while it writes), that is not a JSON object,
+// or that has an entry whose folder is not an absolute path or has a `..`
+// segment (after a link, `..` leads where the text does not); and a Flatpak or
+// snap build of the app anywhere on this account, whose list lives in its
+// sandbox and not in this file. The root and every listed folder are compared
+// as written and as their real paths, in any letter case, so a link on the way
+// to either side, or another spelling, does not hide an entry.
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const folded = (target) => target.normalize('NFC').toLowerCase()
+// The real path of a folder that may not exist, and its lexical path when it cannot be resolved (a volume that is gone).
+const realOrLexical = (target) => { try { return realPathOfLocation(target) } catch { return path.resolve(target) } }
+const spellings = (target) => [...new Set([path.resolve(target), realOrLexical(target)].map(folded))]
+// Strictly inside: `..x` is a folder name, not a way up.
+const inside = (parent, child) => { const relative = path.relative(parent, child); return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) }
+
+// How a listed folder stands to the vault root, or null when it is neither the root, above it, nor inside it.
+function relationOf(entryPath, root) {
+  const listed = spellings(entryPath)
+  if (listed.some((folder) => root.includes(folder))) return 'vault-listed'
+  if (listed.some((folder) => root.some((candidate) => inside(folder, candidate)))) return 'vault-inside-listed-vault'
+  if (listed.some((folder) => root.some((candidate) => inside(candidate, folder)))) return 'listed-vault-inside-vault'
+  return null
+}
+
+const noEvidence = (reason, extra = {}) => ({ unlisted: false, reason, ...extra })
+
+// `read` answers readObsidianSettings for the app's user-data directory; `sandboxed` answers whether a Flatpak or snap
+// build is present. Either one that throws gives no evidence.
+export async function readUnheldEvidence({ vaultRoot, read, sandboxed, attempts = 3, delayMs = 50, sleep = delay } = {}) {
+  if (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot)) return noEvidence('vault-root-unknown')
+  if (typeof read !== 'function' || typeof sandboxed !== 'function') return noEvidence('obsidian-settings-location-unknown')
+  let present = true
+  try { present = sandboxed() !== false } catch { present = true }
+  if (present) return noEvidence('obsidian-sandboxed')
+  let answer = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try { answer = read() } catch { answer = { ok: false, code: 'obsidian-settings-unreadable' } }
+    if (answer?.ok === true || answer?.code !== 'obsidian-settings-unreadable') break
+    if (attempt < attempts) await sleep(delayMs)
+  }
+  if (answer?.ok !== true) return noEvidence(typeof answer?.code === 'string' ? answer.code : 'obsidian-settings-unreadable')
+  const vaults = answer.vaults ?? {}
+  if (!isPlainObject(vaults)) return noEvidence('obsidian-settings-not-object')
+  const root = spellings(vaultRoot)
+  for (const [id, entry] of Object.entries(vaults)) {
+    if (!isPlainObject(entry) || typeof entry.path !== 'string' || !path.isAbsolute(entry.path) || entry.path.split(/[\\/]/).includes('..')) return noEvidence('obsidian-settings-entry-unreadable', { id })
+    const relation = relationOf(entry.path, root)
+    if (relation !== null) return noEvidence(relation, { id, path: entry.path })
+  }
+  return { unlisted: true }
+}
+
+// The reader the maintenance service gives its engine: the settings file of the app for this account (HOME, and on
+// Linux XDG_CONFIG_HOME), and any Flatpak or snap build, installed or having left its list, whichever wrote last.
+// `exists` answers whether a path exists: the build's system-wide places (/var/lib/flatpak, /snap) are looked up through
+// it too.
+export function createProductionUnheldEvidence({ platform = process.platform, env = process.env, exists = fs.existsSync } = {}) {
+  const userDataDir = obsidianUserDataDir({ platform, env })
+  return ({ vaultRoot }) => readUnheldEvidence({
+    vaultRoot,
+    read: () => (userDataDir === null ? { ok: false, code: 'obsidian-settings-location-unknown' } : readObsidianSettings({ userDataDir })),
+    // Present at all, not only when its list was written last: with no list time given, any installation or list counts.
+    sandboxed: () => obsidianSandboxedBuild({ platform, env, exists, modified: () => null }) !== null,
+  })
+}