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

package/src/runtime/obsidian/lifecycle.mjs

@@ -15,6 +15,7 @@ import {
   CONSENT_COVERAGES, SERVICE_SETTINGS_SCHEMA, executableIdentity, openServiceLog, publicRecord, readLastStartup, readServiceRecord, readServiceSettings, releaseOfEntry, removeServiceRecord,
   serviceNameFor, servicePaths, writeServiceSettings,
 } from './service-record.mjs'
+import { personalHomeOf } from './personal-selection.mjs'
 import { resolveServiceWorkspace } from './service.mjs'
 
 // start / status / stop of the maintenance service of one workspace, as
@@ -61,9 +62,11 @@ export const LIFECYCLE_PRIMITIVES = Object.freeze({
   provesOurProcess: (record) => processRunsRecordedExecutable(record),
 })
 
-function context({ loadProject, dataRoot, env, platform, create = false, randomBytes }) {
+// `locateProject`, when given, answers what the workspace is resolved from without loading the project (a bound
+// personal home, locatePersonalHome): its service is then found, started and stopped whatever its selection holds.
+function context({ loadProject, locateProject = null, dataRoot, env, platform, create = false, randomBytes }) {
   if (typeof loadProject !== 'function') throw new TypeError('the service lifecycle needs loadProject')
-  const project = loadProject()
+  const project = locateProject === null ? loadProject() : locateProject()
   if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}) })
   const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create })
   return { project, workspace }
@@ -90,8 +93,8 @@ async function evaluate({ workspaceRoot, workspaceId }, { probeTimeoutMs = DEFAU
 
 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 })
+export async function serviceStatus({ loadProject, locateProject, dataRoot, env = process.env, platform = process.platform, probeTimeoutMs, alive } = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const { workspace } = context({ loadProject, locateProject, 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 }))
 }
@@ -177,11 +180,11 @@ async function startThroughLoginItem({ workspace, loginItem, entryPath, deadline
 // proven runtime is answered as already running.
 export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
   const {
-    loadProject, dataRoot, host, port, consent, detached = false, entryPath = SERVICE_ENTRY_PATH, entryArgs = [], intervalMs,
+    loadProject, locateProject, 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, loginItem = null, replaceOutdated = false,
   } = options
-  const { project, workspace } = context({ loadProject, dataRoot, env, platform, create: true })
+  const { project, workspace } = context({ loadProject, locateProject, dataRoot, env, platform, create: true })
   const { workspaceRoot, workspaceId } = workspace
   const deadline = Date.now() + startTimeoutMs
 
@@ -208,7 +211,7 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
       const standing = replaceOutdated ? runtimeRelease(before, entryPath) : null
       if (standing === 'later') return { ...shown(before), started: false, alreadyRunning: true, release: 'later' }
       if (standing !== 'outdated') return { ...shown(before), started: false, alreadyRunning: true }
-      const stopped = await stopService({ loadProject, dataRoot, env, platform, probeTimeoutMs, alive }, rules)
+      const stopped = await stopService({ loadProject, locateProject, dataRoot, env, platform, probeTimeoutMs, alive }, rules)
       if (!stopped.stopped) return { ...shown(before), started: false, alreadyRunning: true, release: 'outdated', reason: stopped.reason ?? 'the-runtime-was-not-stopped' }
       replaced = 'outdated'
       before = await evaluate(workspace, { probeTimeoutMs, alive, rules })
@@ -241,7 +244,9 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
     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]
+      // A bound personal home is named instead of a project: the service follows the selection confirmed there.
+      const home = personalHomeOf(project)
+      const args = [executable.path, home === null ? `--project=${project.configPath}` : `--personal-home=${home}`, ...(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. It runs in the root
       // directory, never in the one the command was started in, which may be a vault or a folder somebody removes.
       child = spawn(execPath, args, { detached, shell: false, windowsHide: true, stdio: ['ignore', log.descriptor, log.descriptor], env, cwd: path.parse(executable.path).root })
@@ -277,8 +282,8 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
 }
 
 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 })
+  const { loadProject, locateProject, 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, locateProject, 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 })
@@ -308,8 +313,8 @@ export async function stopService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
 // 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, body = {} }) {
-  const { loadProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
-  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  const { loadProject, locateProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
+  const { workspace } = context({ loadProject, locateProject, 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 }

package/src/runtime/obsidian/login-item.mjs

@@ -9,6 +9,7 @@ import { ensureServiceSettings } from './lifecycle.mjs'
 import { ensureWorkspaceIdentity, readLocalPointer, resolveDataRoot } from './machine-settings.mjs'
 import { SERVICE_MANAGER_KINDS } from './service-managers.mjs'
 import { readLastStartup, readServiceSettings, serviceNameFor, servicePaths, writeServiceSettings } from './service-record.mjs'
+import { personalHomeOf } from './personal-selection.mjs'
 import { resolveServiceWorkspace } from './service.mjs'
 import { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from './startup-adapters.mjs'
 
@@ -164,7 +165,9 @@ export const loginItemDataRoot = ({ project, dataRoot, env = process.env, platfo
 export function planLoginItem({ platform, project, workspaceRoot, workspaceId, dataRoot, label, entryPath, entryArgs = [], nodePath, searchPath = null }) {
   if (!isAbsolutePlain(dataRoot)) throw new TypeError('a login item names the absolute data root of its workspace')
   if (typeof workspaceId !== 'string' || workspaceId === '') throw new TypeError('a login item names its workspace')
-  const args = [`--project=${project.configPath}`, `--data-root=${dataRoot}`, `--workspace-id=${workspaceId}`, ...entryArgs]
+  // A bound personal home is named instead of a project, as `start` names it (lifecycle.mjs).
+  const home = personalHomeOf(project)
+  const args = [home === null ? `--project=${project.configPath}` : `--personal-home=${home}`, `--data-root=${dataRoot}`, `--workspace-id=${workspaceId}`, ...entryArgs]
   const unit = buildStartupAdapter({ platform, label, nodePath, entryPath, args, logPath: servicePaths(workspaceRoot).loginItemLog, searchPath })
   return { ...unit, label, digest: sha256(unit.text), program: { node: nodePath, entry: entryPath }, searchPath }
 }

package/src/runtime/obsidian/observation.mjs

@@ -123,24 +123,52 @@ export function readFileFacts(file) {
 
 const sameHint = (left, right) => left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.ino === right.ino
 
+// Whether a file still has the stat hint it was indexed with: what a reconcile that is not full decides by before it
+// would hash the file again. `entry` is the file's entry in the index. A file never hashed, or gone, has none.
+export function hasIndexedHint(entry, absolute, lstat = fs.lstatSync) {
+  if (!entry || entry.digest === null || !entry.hint) return false
+  const hint = statHint(absolute, lstat)
+  return hint !== null && sameHint(entry.hint, hint)
+}
+
 // Reconciles `files` against `index` (a Map owned by the caller) and returns
 // the changes, decided by digest alone. `full` hashes everything; otherwise a
 // file is hashed when it is new, when its stat hint differs or when a watcher
 // named it. Entries under `prefix` that are no longer listed are removals.
-export function reconcile({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
+export function reconcile(input) {
+  const steps = reconcileSteps(input)
+  for (;;) { const step = steps.next(); if (step.done) return step.value }
+}
+
+// The same reconciliation with the event loop given a turn between files, under the caller's cooperative budget
+// (createCooperativeBudget): for a walk long enough to hold a service's listener, such as the read-back of a large
+// view. Each file is still looked at once, in the listed order, and the index holds what was seen when each was read;
+// a file that changes after its turn is the next look's to see, as one that changes after an uninterrupted walk is.
+// The caller must not let another reconciliation of the same index run before this one has answered.
+export async function reconcileCooperatively(input, budget) {
+  const steps = reconcileSteps(input)
+  for (;;) {
+    const step = steps.next()
+    if (step.done) return step.value
+    await budget.checkpoint('reconcile-file')
+  }
+}
+
+// One step a listed file; the removals and the answer after the last.
+function* reconcileSteps({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
   const changes = []
   const present = new Set()
   let hashed = 0
-  for (const file of files) {
+  const look = (file) => {
     present.add(file.key)
     const previous = index.get(file.key)
     const hint = statHint(file.absolute, lstat)
     if (hint === null) {
       if (previous && previous.digest !== null) changes.push({ key: file.key, changeClass: previous.changeClass, kind: 'removed' })
       index.set(file.key, { changeClass: file.changeClass, hint: null, digest: null, byteLength: null })
-      continue
+      return
     }
-    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) continue
+    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) return
     const facts = readFileFacts(file.absolute)
     const digest = facts?.digest ?? null
     hashed += 1
@@ -149,6 +177,10 @@ export function reconcile({ index, files, prefix, full, hinted = () => false, ls
     }
     index.set(file.key, { changeClass: file.changeClass, hint: digest === null ? null : hint, digest, byteLength: facts?.byteLength ?? null })
   }
+  for (const file of files) {
+    look(file)
+    yield
+  }
   for (const [key, previous] of index) {
     if (!key.startsWith(prefix) || present.has(key)) continue
     if (previous.digest !== null) changes.push({ key, changeClass: previous.changeClass, kind: 'removed' })

package/src/runtime/obsidian/opening.mjs

@@ -134,6 +134,7 @@ export const REASON_NEXT = Object.freeze({
   // publisher or editor is involved.
   'plugin-file-changed': 'a file of Atelier\'s plugin in this vault (under .obsidian/plugins) changed while the view was published, by another program or by you, so the publication did not finish; it is retried automatically, and if this keeps happening, stop what keeps writing there (a sync tool, say)',
   'settings-changed': 'a settings file Atelier writes in this vault (the plugin list or a plugin setting under .obsidian) changed while the view was published, by Obsidian, another program or you, and was not written over; it is retried automatically, reading the file as it is then',
+  'selection-history-shortened': 'the selection history of the personal home ends at an earlier record than the running maintenance service has read: records were removed by something other than a confirmation, and the service publishes nothing while the history is shorter. Put the removed records back, and it goes on as before. Or accept the history as it now stands: a service started again (`atelier obsidian service stop`, then open again) reads the history as it is and follows the selection it then ends with, publishing it if its generation still holds (`atelier obsidian status` reports that selection, or why it cannot be used); a confirmation made after the records were removed is followed without a restart once the history is as long as it was',
   'vault-inside-another-vault': 'Obsidian lists another vault at a folder that contains this view\'s vault; open never adds a vault inside another one, and never sends a call that could reach that vault instead: remove that vault from Obsidian\'s vault list, or keep Atelier\'s data root outside that folder, then open again',
 })
 
@@ -358,7 +359,7 @@ function settingsWritten(written) {
 // again for a view the app kept from being published, and reports one outcome.
 export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIMITIVES, lifecycleRules = LIFECYCLE_PRIMITIVES) {
   const {
-    loadProject, dataRoot, scopeId: requestedScope, appProbe, launcher, registry, quitter = null, restartApp = false, service = {}, consent, allowStale = false, extensions = null,
+    loadProject, locateProject, dataRoot, scopeId: requestedScope, appProbe, launcher, registry, quitter = null, restartApp = false, service = {}, consent, allowStale = false, extensions = null,
     tickTimeoutMs = 120 * 1000, appWaitMs = 30 * 1000, appPollMs = 500, sleep = defaultSleep, monotonic = () => Date.now(),
     env = process.env, platform = process.platform, probeTimeoutMs,
   } = options
@@ -382,7 +383,7 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   }
   if (enablement.state === 'disabled') return finish('disabled', { reason: enablement.reason, scopeId: requestedScope ?? null })
   const scopeId = resolveScope(enablement, requestedScope)
-  const lifecycle = { loadProject, dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
+  const lifecycle = { loadProject, ...(locateProject === undefined ? {} : { locateProject }), dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
 
   // 1. The owned service: reconnect, or start. Never adopt; a runtime of ours is replaced only when it runs an earlier
   //    release, under the consent already recorded, when a tick is asked of it (requestServiceTick).

package/src/runtime/obsidian/personal-selection.mjs

@@ -0,0 +1,125 @@
+import path from 'node:path'
+import { PersonalWorkspaceRefusal, readPersonalSelectionHead } from '@mnstry/atelier/personal-workspace'
+import { ensureLocalState } from '@mnstry/atelier/project'
+import { assertPersonalSelection, loadBoundProject, loadBoundProjectOffThread, notePersonalSelectionHead, personalSelectionOf, pinPersonalSelection } from '../../projection/obsidian/personal-workspace.mjs'
+import { refuse } from './errors.mjs'
+
+// A person's confirmed selection, bound to the maintenance runtime.
+//
+// A personal home keeps a history of the generations its person confirmed
+// (`selectPersonalGeneration` of the personal-workspace module). The loaders
+// here follow that history instead of naming a generation themselves:
+//
+//   read the head -> load the generation it names -> read the head again
+//
+// The head is read from the history alone, in the caller's thread: one
+// directory listing and one bounded read per record. Whether the generation
+// may be used is composition's to decide, as for any binding: in a worker for
+// a service, in the calling thread for a command run once. A head that moved
+// while the generation was loaded is another selection, and refuses
+// `personal-selection-changed`.
+//
+// Nothing is confirmed here and nothing is chosen for the person. A history
+// with no record, one that does not hold, a home that cannot be read and a
+// generation its composition refuses each refuse as a maintenance refusal
+// with the module's own code (`nothing-selected`, `selection-history-corrupt`,
+// `personal-home-unavailable`, `root-missing`, `stale-generation` and the
+// rest). There is no project to fall back to: an engine whose loader refuses
+// publishes nothing, and every view it knows says why.
+//
+// A loaded project is pinned to the record it was loaded under
+// (pinPersonalSelection), so the engine observes that record and the place of
+// the next one, and loads again at the tick after a confirmation or after the
+// history was cut short. At every full reconciliation the history is read
+// again, and a project whose record it no longer ends with is refused.
+//
+// A history never gets shorter through the module: selections are appended and
+// nothing removes one. So a history that ends at a lower record than this
+// process has read it ending at was cut short by something else, and following
+// it back could publish what nobody confirmed after the records removed. Every
+// read of the history's end is noted (notePersonalSelectionHead): the first
+// read here, the read once the generation is loaded, the recheck of a project
+// already loaded, and a read the engine asks for when its guard stops a view
+// because an observed file changed or could not be read (once for views
+// stopped one after another). A
+// history that ends earlier than the highest record noted refuses
+// `selection-history-shortened` at a load and at a recheck, and nothing is
+// loaded or used from it while it is shorter; the guard's read only notes, and
+// its view says `mixed-read`. An engine whose project is pinned below the
+// highest record noted loads it again at its next tick
+// (personalSelectionBehind). A record added and removed between two of those
+// reads was never read, and does not count.
+//
+// Only the record number is kept, and only in this process. A record in a
+// place already read, with other content, is read as a confirmation. A process
+// started after the cut reads the history as it then stands and publishes what
+// it ends with: starting the service again accepts the shorter history, and so
+// does any start of it (a login, a restart after an upgrade or a failure).
+//
+// Who may see a vault is not decided here: that stays the machine's setting.
+//
+// Where the workspace is does not wait for a load: a bound project's folder is
+// its private home, so the home alone locates it (locatePersonalHome). A
+// service resolves its workspace from that at once, and starts, whether or not
+// a selection is confirmed; its engine then awaits the loader at each tick.
+
+// The decisions the oracles in test/obsidian-personal-selection.test.mjs are
+// sensitive to. Production always uses these; a test hands a loader a broken
+// one (`rules`) to prove that its oracle can fail.
+export const SELECTION_PRIMITIVES = Object.freeze({
+  // A history that ends at a lower record than this process has read is refused, at every read of it.
+  refusesShortened: true,
+  // The head is read again once the generation is loaded.
+  readsHeadAgain: true,
+  // What the loaded project is pinned for (pinPersonalSelection).
+  pin: Object.freeze({ observe: true, recheck: true }),
+})
+
+const SOURCE = Object.freeze({ source: 'personal-workspace' })
+const LOCATED = Symbol('atelier.obsidian.located-personal-home')
+
+// The record the history ends with. A history without one refuses, and so does one shorter than this process read it.
+function confirmedHead(personalHome, rules) {
+  let head
+  try { head = readPersonalSelectionHead({ personalHome }) } catch (error) {
+    if (!(error instanceof PersonalWorkspaceRefusal)) throw error
+    refuse(error.code, 'the selection history of the personal workspace could not be read; nothing is loaded from it', SOURCE)
+  }
+  notePersonalSelectionHead(personalHome, head, rules)
+  if (head.selected === null) refuse('nothing-selected', 'no generation of the personal workspace is confirmed; nothing is loaded until one is', SOURCE)
+  return head
+}
+
+function pinned(project, head, rules) {
+  pinPersonalSelection(project, head, { ...rules.pin, refusesShortened: rules.refusesShortened })
+  if (rules.readsHeadAgain) assertPersonalSelection(project)
+  return project
+}
+
+// What the workspace of a bound personal home is resolved from, without loading anything: a project that holds the home
+// as its folder and nothing else, as a bound project's folder is. Its pointer is under the home, the data root is the
+// pointer's or the caller's, and a home is outside every Git worktree. Synchronous; nothing is composed.
+export function locatePersonalHome({ personalHome } = {}) {
+  if (typeof personalHome !== 'string' || !path.isAbsolute(personalHome) || path.resolve(personalHome) !== personalHome) refuse('path-not-absolute', 'a personal home is named by its absolute path', SOURCE)
+  const located = { configDir: personalHome, [LOCATED]: personalHome }
+  located.localState = ensureLocalState(located, { write: false, env: { PATH: process.env.PATH } })
+  return located
+}
+
+// The personal home a located or a loaded project follows, which a service it starts or a login item it installs is
+// given instead of a project (--personal-home); null for any other project.
+export const personalHomeOf = (project) => project?.[LOCATED] ?? personalSelectionOf(project)?.personalHome ?? null
+export { personalSelectionOf }
+
+// The project of the confirmed selection, for a loader that may block (a command run once). `bind` and `rules` are
+// test seams.
+export function loadSelectedProject({ personalHome } = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const head = confirmedHead(personalHome, rules)
+  return pinned(loadBoundProject({ personalHome, generationId: head.selected }, { bind }), head, rules)
+}
+
+// The same, for a loader on a service's event loop: the composition runs in a worker, and the engine awaits it.
+export async function loadSelectedProjectOffThread({ personalHome } = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const head = confirmedHead(personalHome, rules)
+  return pinned(await loadBoundProjectOffThread({ personalHome, generationId: head.selected }, { bind }), head, rules)
+}

package/src/runtime/obsidian/pipeline.mjs

@@ -1,6 +1,7 @@
+import { createCooperativeBudget, prepareViewCooperatively } from '../../projection/obsidian/materialize/prepare-view.mjs'
 import { createHash } from 'node:crypto'
 import path from 'node:path'
-import { buildCanonicalGraph, createGraphFileCache } from '../../graph/graph.mjs'
+import { buildCanonicalGraph, buildCanonicalGraphSteps, createGraphFileCache } from '../../graph/graph.mjs'
 import { markdownMetadata } from '../../graph/knowledge-graph.mjs'
 import { EMITTER_VERSION, createPreparationCache, prepareView, readMarkdownLens, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
 import { personalWorkspaceGraph } from '../../projection/obsidian/personal-workspace.mjs'
@@ -128,8 +129,42 @@ export function profileFor({ project, workspaceId, audienceAllow }) {
 // `deferPersonalValidation` (the engine), an unconfirmed key refuses `personal-validation-pending` instead of composing
 // on this thread.
 export function buildGraph({ project, eligibility, cache = null, index = null, deferPersonalValidation = false }) {
-  const observedDigest = cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null
+  const observedDigest = observedDigestOf(cache, index)
   const canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation }) ?? buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+  return eligibleGraph(canonical, eligibility)
+}
+
+// The same graph, built with the event loop given a turn between the Markdown sources of the census, under the
+// caller's cooperative budget (`scheduling`: createCooperativeBudget's options, its guard checked at every wait). For
+// the maintenance engine's tick: a first tick reads every source, and a large corpus would hold the service's
+// listener for the whole census. A project bound to a personal workspace is built by its own route, in one stretch,
+// as buildGraph builds it.
+export async function buildGraphCooperatively({ project, eligibility, cache = null, index = null, deferPersonalValidation = false, scheduling = {} }) {
+  const observedDigest = observedDigestOf(cache, index)
+  // The personal route answers for a bound project, and refuses a project that carries the reserved key unbound.
+  const personal = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation })
+  if (personal !== null) return eligibleGraph(personal, eligibility)
+  const budget = createCooperativeBudget(scheduling)
+  budget.check()
+  const steps = buildCanonicalGraphSteps(project, { fileCache: cache, observedDigest })
+  let canonical
+  try {
+    for (;;) {
+      const step = steps.next()
+      if (step.done) { canonical = step.value; break }
+      await budget.checkpoint(step.value)
+    }
+  } catch (error) {
+    steps.return?.()
+    throw error
+  }
+  budget.finish('graph-assembled')
+  return eligibleGraph(canonical, eligibility)
+}
+
+const observedDigestOf = (cache, index) => (cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null)
+
+function eligibleGraph(canonical, eligibility) {
   if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
   return withEligibility(canonical, eligibility.isEligible, assetEligibilityFor({ graph: canonical, eligibility }))
 }
@@ -141,6 +176,12 @@ export function buildGraph({ project, eligibility, cache = null, index = null, d
 // its pinned digest is unchanged and the cached bytes are the ones that digest
 // describes, so bytes that drift under an unchanged pin are not consulted
 // until observation hashes the file again (the same bound as the graph stage).
+// The engine keeps that bound when it prepares cooperatively. Called on its
+// own, prepareViewCooperatively waits between notes and so reads every
+// selected source against its pin once more before it returns. The engine
+// turns that second reading off and checks the selected sources itself, after
+// the preparation and again before the commit, as observation does: by stat
+// hint, and by digest only where the hint moved.
 export function captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt }) {
   const roots = new Map((project.repos ?? []).filter((repo) => !repo.external).map((repo) => [repo.name, repo.path]))
   const absolute = (repoId, relative) => {
@@ -186,5 +227,5 @@ export function captureSnapshot({ project, graph, workspaceId, index, configDige
 // that note and reuses the rest. Both caches are derived, in-memory state: a
 // test may replace either seam with `() => null` to build or prepare in full.
 export function createProductionSeams() {
-  return { buildGraph, captureSnapshot, profileFor, prepareView, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
+  return { buildGraph, buildGraphCooperatively, captureSnapshot, profileFor, prepareView, prepareViewCooperatively, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
 }

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

@@ -89,6 +89,20 @@ function listGenerations(directory) {
 
 const ticketName = (generation, kind) => `${String(generation).padStart(12, '0')}.${kind}`
 
+// A ticket is removed only while it holds the given bytes: one that holds others is another holder's. Answers whether
+// nothing of these bytes is left at the path (removed now, or gone already); throws what reading or removing it threw.
+function removeIfStill(file, body) {
+  let current
+  try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') return true; throw error }
+  if (current !== body) return true
+  fs.unlinkSync(file)
+  return true
+}
+
+// Tickets this process published and could not remove after its acquisition failed, by lock directory. Each is
+// removed at this process's next acquisition in that directory, before the directory is looked at.
+const UNWITHDRAWN = new Map()
+
 // Read-only. { available, reason, generation, ticket }
 export async function inspectPrivateGenerationLock({ directory, workspaceId, proveAbandoned = createAbandonmentProof(), nowMs = Date.now() }) {
   const { names, highest, unknown } = listGenerations(directory)
@@ -116,6 +130,11 @@ export async function inspectPrivateGenerationLock({ directory, workspaceId, pro
 // 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 owed = UNWITHDRAWN.get(contained)
+  if (owed !== undefined) {
+    // Still failing: the ticket stays, and this acquisition finds it as held by this process, as before.
+    try { if (removeIfStill(owed.file, owed.body)) UNWITHDRAWN.delete(contained) } catch { /* tried again at the next acquisition */ }
+  }
   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
@@ -125,12 +144,25 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
   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'))
+  // A ticket published and then not handed to its caller, because a later step failed (the directory sync or the
+  // read-back of the publication, the listing that confirms it), is removed while it still holds these bytes: nobody
+  // would release it, and every later acquisition by this process would find it held by this process. One that does
+  // not hold them is another holder's and is left alone. A removal that fails too (the same fault, say) is owed, and
+  // made at the next acquisition in this directory.
+  const withdraw = () => {
+    try { removeIfStill(file, body) } catch { UNWITHDRAWN.set(contained, { file, body }) }
+  }
   try { publishPrivateFile(file, body) } catch (error) {
     if (error.code === 'EEXIST') return { acquired: false, reason: 'lost-the-race-for-this-generation', holder: null }
+    withdraw()
     throw error
   }
   // Confirm: a decision made on an old listing finds the newer ticket here and withdraws.
-  const after = listGenerations(contained)
+  let after
+  try { after = listGenerations(contained) } catch (error) {
+    withdraw()
+    throw error
+  }
   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 }
@@ -138,18 +170,21 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
   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 */ }
   }
+  // Settled once the lock is given back, or found not to be ours any more. A release that throws (a full disk, an
+  // I/O error while the released ticket is written) settles nothing: the lock is still held, and calling release()
+  // again tries again. Writing the same released ticket a second time is harmless.
   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 }
+      try { current = readRegularTextNoFollow(file) } catch (error) { if (error.code === 'ENOENT') { released = true; 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
+      if (current !== body) { released = true; return false }
       publishPrivateFile(path.join(contained, ticketName(generation, 'released')), body)
+      released = true
       return true
     },
   }

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

@@ -4,12 +4,17 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { firstString, parseArgs, resolveProjectConfig } from '../../project/config.mjs'
 import { workspaceStateRoot } from './machine-settings.mjs'
+import { loadSelectedProjectOffThread, locatePersonalHome } from './personal-selection.mjs'
 import { RELEASE_CHANGED, resolveServiceWorkspace, 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
+//   --project=<absolute atelier.project.json>   required, unless a personal home is named instead
+//   --personal-home=<absolute directory>        instead of --project: the private home of a personal workspace. The
+//                                               service follows the generation its person confirmed there, composed off
+//                                               the event loop, and starts whether or not one is confirmed: it locates
+//                                               its workspace from the home alone (personal-selection.mjs)
 //   --data-root=<absolute directory>            optional; otherwise the pointer, the overlay or the platform default
 //   --workspace-id=<identifier>                 named by a login item: under `--startup`, where a refusal is recorded
 //                                               when the project no longer leads to a workspace
@@ -77,15 +82,48 @@ export const EXIT_REFUSED = 2
 // manager restarts it (a non-zero exit), on the release now installed. EX_TEMPFAIL.
 export const EXIT_RELEASE_CHANGED = 75
 
+const readOr = (read, otherwise) => { try { return read() } catch { return otherwise } }
 const printed = (entry) => { try { process.stdout.write(`${JSON.stringify(entry)}\n`) } catch { /* a closed log never ends the service */ } }
 
+// The first answer of the loader, or of the locator of a personal home, asked for once and handed to both who need it
+// at a start under a login item: the lookup of the workspace below, and the service's own start, which takes it as the
+// answer to its first call. One that answers a promise or another thenable is not waited for by either. A promise whose
+// `constructor` reads as this realm's `Promise` is kept as it is; any other thenable (as a rule another realm's promise
+// or a subclass's) is adopted here, once, as a native promise (so its `then` is called once in all). That promise is let go, handled
+// without calling a `then` of its own: a refusal of it never goes unhandled and ends the process with an error where
+// the service's typed refusal should end it cleanly. The service is handed that promise. Whatever is thrown,
+// `undefined` included, and a `then` that cannot be read, is thrown again at the service's first call, so it ends the
+// start as a failure of the loader would.
+function firstAnswerOf(loadProject) {
+  let first
+  try {
+    const project = loadProject()
+    if (typeof project?.then === 'function') {
+      const promised = Promise.resolve(project)
+      Promise.prototype.then.call(promised, undefined, () => {})
+      first = { promised }
+    } else first = { project }
+  } catch (error) { first = { threw: true, error } }
+  let taken = false
+  return {
+    // The project, when the loader answered one at once; null when it threw or answered a promise.
+    project: () => (first.threw || first.promised ? null : first.project),
+    loadProject() {
+      if (taken) return loadProject()
+      taken = true
+      if (first.threw) throw first.error
+      return first.promised ?? first.project
+    },
+  }
+}
+
 // The workspace of a service a login item started, when it can be found: where it keeps its log and records how its
-// start ended. When the project no longer leads to one (it moved, its pointer is gone), the workspace the unit names by
-// its data root and identity, if that exists; it is never created here. Null otherwise; a refusal is then printed
-// only, into the unit's own output file.
-function startupWorkspace({ loadProject, dataRoot, workspaceId, env = process.env, platform = process.platform }) {
+// start ended. When the project no longer leads to one (it moved, its pointer is gone, its loader answered no project
+// at once), the workspace the unit names by its data root and identity, if that exists; it is never created here. Null
+// otherwise; a refusal is then printed only, into the unit's own output file.
+function startupWorkspace({ project, dataRoot, workspaceId, env = process.env, platform = process.platform }) {
   try {
-    const workspace = resolveServiceWorkspace({ project: loadProject(), dataRoot, env, platform })
+    const workspace = project === null ? null : resolveServiceWorkspace({ project, dataRoot, env, platform })
     if (workspace?.workspaceRoot) return workspace
   } catch { /* the workspace the unit names, below */ }
   if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot) || typeof workspaceId !== 'string') return null
@@ -120,10 +158,14 @@ function recordStartup(workspace, { at, outcome, code }) {
 // and the manager restarts it after its throttle.
 export async function runServiceProcess(options) {
   const startup = options.startup === true
-  const workspace = startup ? startupWorkspace(options) : null
+  // A located personal home is asked instead of the loader: the loader is then not asked before the service's engine.
+  const located = typeof options.locateProject === 'function'
+  const asked = located ? options.locateProject : options.loadProject
+  const first = startup && typeof asked === 'function' ? firstAnswerOf(asked) : null
+  const workspace = startup ? startupWorkspace({ ...options, project: first === null ? null : first.project() }) : null
   const log = workspace === null ? printed : workspaceLog(workspace.workspaceRoot)
   try {
-    const service = await runMaintenanceService({ log, invokedAs: process.argv[1], ...options })
+    const service = await runMaintenanceService({ log, invokedAs: process.argv[1], ...options, ...(first === null ? {} : { [located ? 'locateProject' : 'loadProject']: first.loadProject }) })
     if (startup) recordStartup(workspace, { at: new Date().toISOString(), outcome: 'started', code: null })
     for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { void service.shutdown(`signal-${signal}`) })
     const { reason } = await service.done
@@ -131,8 +173,9 @@ export async function runServiceProcess(options) {
     process.exit(reason === RELEASE_CHANGED ? EXIT_RELEASE_CHANGED : 0)
   } catch (error) {
     const at = new Date().toISOString()
-    const code = typeof error?.code === 'string' ? error.code : null
-    log({ at, event: 'refused', code: code ?? 'untyped-error', message: String(error?.message ?? error) })
+    // What was thrown is read without trusting it: a value with no prototype, or a getter that throws, is still logged.
+    const code = readOr(() => (typeof error?.code === 'string' ? error.code : null), null)
+    log({ at, event: 'refused', code: code ?? 'untyped-error', message: readOr(() => String(error?.message ?? error), 'unprintable') })
     if (startup && code !== null) { recordStartup(workspace, { at, outcome: 'refused', code }); process.exitCode = 0; return }
     process.exitCode = code !== null ? EXIT_REFUSED : 1
   }
@@ -149,13 +192,16 @@ function watchRelease(invokedAs) {
 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 personalHome = firstString(args['personal-home'])
+  if (personalHome !== null && (configPath !== null || !path.isAbsolute(personalHome))) throw Object.assign(new Error('--personal-home must be the absolute path of a private home, given instead of --project'), { code: 'service-arguments-invalid' })
+  if (personalHome === null && (!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 workspaceId = firstString(args['workspace-id']) ?? 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 }),
+    loadProject: personalHome !== null ? () => loadSelectedProjectOffThread({ personalHome }) : () => resolveProjectConfig({ argv: [`--project=${configPath}`], cwd: path.dirname(configPath), env, writeLocalState: false }),
+    ...(personalHome === null ? {} : { locateProject: () => locatePersonalHome({ personalHome }) }),
     ...(dataRoot === undefined ? {} : { dataRoot }), ...(workspaceId === undefined ? {} : { workspaceId }), ...(intervalMs === undefined ? {} : { intervalMs }),
     ...(firstString(args['runtime-id']) ? { runtimeId: firstString(args['runtime-id']) } : {}),
     startup: args.startup === true, adapter: firstString(args.adapter),