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

package/src/runtime/obsidian/pipeline.mjs

@@ -1,6 +1,8 @@
+import { createCooperativeBudget, prepareViewCooperatively } from '../../projection/obsidian/materialize/prepare-view.mjs'
 import { createHash } from 'node:crypto'
+import fs from 'node:fs'
 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,9 +130,99 @@ 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 canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation }) ?? buildCanonicalGraph(project, { fileCache: cache, observedDigest })
-  if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
+  const observedDigest = observedDigestOf(cache, index)
+  let canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation })
+  if (canonical === null) {
+    try { canonical = buildCanonicalGraph(project, { fileCache: cache, observedDigest }) } catch (error) {
+      refuseObservedDirectory(error, { project, index })
+      throw error
+    }
+  }
+  return eligibleGraph(canonical, eligibility, { project, index })
+}
+
+// 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, { project, index })
+  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?.()
+    refuseObservedDirectory(error, { project, index })
+    throw error
+  }
+  budget.finish('graph-assembled')
+  return eligibleGraph(canonical, eligibility, { project, index })
+}
+
+const observedDigestOf = (cache, index) => (cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null)
+
+// Only a digest from this tick's observation establishes that the path was a readable source before the build.
+// These exceptional checks never enrol a path or admit an invalid graph; without prior observation its error stays.
+function* observedSources({ project, index }, changeClass = null) {
+  if (!(index instanceof Map)) return
+  for (const repo of project?.repos ?? []) {
+    if (repo?.external || typeof repo?.path !== 'string' || typeof repo?.name !== 'string') continue
+    const root = path.resolve(repo.path)
+    const prefix = sourceKey(repo.name, '')
+    for (const [key, entry] of index) {
+      if (typeof key !== 'string' || !key.startsWith(prefix) || typeof entry?.digest !== 'string' || (changeClass !== null && entry.changeClass !== changeClass)) continue
+      const relative = key.slice(prefix.length)
+      const file = path.resolve(root, ...relative.split('/'))
+      const inside = path.relative(root, file)
+      if (inside === '' || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) continue
+      yield file
+    }
+  }
+}
+
+function directoryNow(file) {
+  try { return fs.lstatSync(file).isDirectory() } catch { return false }
+}
+
+function refuseObservedDirectory(error, observed) {
+  if (error?.code !== 'EISDIR') return
+  // readFileSync's EISDIR need not name a path. In that case an observed file that is now a directory still proves
+  // this build spans two source states; the next full observation decides what the directory now contributes.
+  const named = typeof error.path === 'string' ? path.resolve(error.path) : null
+  for (const file of observedSources(observed)) {
+    if ((named === null || named === file) && directoryNow(file)) refuse('mixed-read', 'an observed source became a directory while the canonical graph was being built', { cause: 'EISDIR' })
+  }
+}
+
+function eligibleGraph(canonical, eligibility, observed) {
+  if (!canonical.ok) {
+    // The graph records a sidecar read failure as invalid metadata. A sidecar this tick already read and that is
+    // gone now is instead a mixed read, as a source removed during the census is. A never-observed sidecar stays invalid.
+    const roots = new Map((observed.project?.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => [repo.name, repo.path]))
+    const sidecars = new Set((canonical.nodes ?? []).flatMap((node) => typeof node.sidecar === 'string' && roots.has(node.repo)
+      ? [path.resolve(roots.get(node.repo), ...node.sidecar.split('/'))] : []))
+    for (const file of observedSources(observed, 'sidecar')) {
+      if (!sidecars.has(file)) continue
+      let stat
+      try { stat = fs.lstatSync(file) } catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') refuse('mixed-read', 'an observed sidecar was removed while the canonical graph was being built', { cause: error.code })
+        continue
+      }
+      if (stat.isDirectory()) refuse('mixed-read', 'an observed sidecar became a directory while the canonical graph was being built', { cause: 'EISDIR' })
+    }
+    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 +233,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) => {
@@ -149,11 +247,13 @@ export function captureSnapshot({ project, graph, workspaceId, index, configDige
     return path.join(root, ...relative.split('/'))
   }
   const byRepo = new Map([...roots.keys()].map((repoId) => [repoId, new Map()]))
+  const observedReads = new Set()
   // Every node, and every asset a view may copy. A withheld asset is never pinned: it is in no snapshot document.
   const pinned = [...graph.nodes, ...(Array.isArray(graph.assets) ? graph.assets.filter((asset) => asset.eligible === true) : [])]
   for (const item of pinned) {
     if (!byRepo.has(item.repo)) refuse('source-not-in-snapshot', 'the graph names a repository the project does not enrol')
     const observed = index.get(sourceKey(item.repo, item.path))
+    if (typeof observed?.digest === 'string') observedReads.add(sourceKey(item.repo, item.path))
     const facts = observed?.digest ? observed : readFileFacts(absolute(item.repo, item.path))
     if (!facts) refuse('mixed-read', 'a file the graph read is no longer there')
     byRepo.get(item.repo).set(item.path, { path: item.path, rawDigest: facts.digest, byteLength: facts.byteLength })
@@ -176,7 +276,16 @@ export function captureSnapshot({ project, graph, workspaceId, index, configDige
       repositories,
     },
     graph,
-    readSource: (repoId, relative) => readFileBytes(absolute(repoId, relative)),
+    readSource: (repoId, relative) => {
+      const file = absolute(repoId, relative)
+      try { return readFileBytes(file) } catch (error) {
+        if (observedReads.has(sourceKey(repoId, relative))) {
+          if (error?.code === 'ELEAFCHANGED') refuse('mixed-read', 'a selected source was replaced while its view was being prepared or published', { cause: error.code })
+          if ((error?.code === 'EISDIR' || error?.message === 'state leaf is not a regular file') && directoryNow(file)) refuse('mixed-read', 'a selected source became a directory while its view was being prepared or published', { cause: 'EISDIR' })
+        }
+        throw error
+      }
+    },
   }
 }
 
@@ -186,5 +295,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

@@ -31,7 +31,7 @@ import { ObsidianMaintenanceRefusal } from './errors.mjs'
 // No answer in time proves nothing (a busy holder answers late). A ticket
 // from another machine, an unreadable ticket, an unknown file, or a live
 // process that recorded no health address all need a person: see
-// `inspectPrivateGenerationLock` and docs/local-services.md.
+// `inspectPrivateGenerationLock` and docs/reference/local-services.md.
 
 export const LOCK_TICKET_SCHEMA = 'atelier-obsidian-lock-ticket/v1'
 export const ENGINE_LOCK_DIRECTORY = path.join('state', 'maintenance', 'engine-lock')
@@ -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)
@@ -114,42 +128,72 @@ export async function inspectPrivateGenerationLock({ directory, workspaceId, pro
 
 // { acquired: true, generation, release() } or { acquired: false, reason, holder }.
 // Never waits and never throws for a lock that is merely held.
-export async function acquirePrivateGenerationLock({ workspaceRoot, directory, workspaceId, purpose, service = null, clock, proveAbandoned, randomBytes = cryptoRandomBytes }) {
+// `validateLocation`, when given, proves the private state's location before the lock directory is made, again after
+// the asynchronous inspection, and once a ticket is published, before predecessors are pruned. A refusal at the first
+// two writes nothing; a refusal at the last withdraws the ticket just published, and prunes nothing.
+export async function acquirePrivateGenerationLock({ workspaceRoot, directory, workspaceId, purpose, service = null, clock, proveAbandoned, randomBytes = cryptoRandomBytes, validateLocation = () => {} }) {
+  validateLocation()
   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
   if (!status.available) return { acquired: false, reason: status.reason, holder }
   if (status.generation >= MAX_GENERATION) return { acquired: false, reason: 'lock-generations-exhausted', holder }
+  validateLocation()
   const generation = status.generation + 1
   const ticket = validateTicket({ schema: LOCK_TICKET_SCHEMA, workspaceId, purpose, pid: process.pid, machine: machineDigest(), nonce: randomBytes(16).toString('hex'), acquiredAt, service }, workspaceId)
   const body = JSON.stringify(ticket)
   const file = path.join(contained, ticketName(generation, 'json'))
+  // 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 }
   }
+  try { validateLocation() } catch (error) {
+    withdraw()
+    throw error
+  }
   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/selection-continuity.mjs

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { inspectPrivateLock, withPrivateLock } from '../../project/durable-state.mjs'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../../project/private-state.mjs'
+import { canonicalJson, closedObject } from './documents.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
+
+// Machine-private continuity evidence, separate from the person's append-only selection history. The maximum never
+// decreases, and previously observed record identities remain known after the person confirms a shorter history.
+export const SELECTION_CONTINUITY_SCHEMA = 'atelier-obsidian-selection-continuity/v1'
+export const MAX_SELECTION_IDENTITIES = 8192
+export const MAX_SELECTION_CONTINUITY_BYTES = 1024 * 1024
+const DIGEST = /^[0-9a-f]{64}$/
+const CONFIRMATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+const SOURCE = Object.freeze({ source: 'personal-workspace' })
+const invalid = () => refuse('invalid-selection-continuity', 'the private selection continuity state cannot be verified; nothing is loaded', SOURCE)
+const count = (value) => Number.isSafeInteger(value) && value >= 0
+
+function validate(document, workspaceId, homeDigest) {
+  closedObject(document, { required: ['schema', 'workspaceId', 'homeDigest', 'highestSequence', 'accepted', 'seen', 'confirmations'] }, 'invalid-selection-continuity', 'the selection continuity state')
+  closedObject(document.accepted, { required: ['sequence', 'head'] }, 'invalid-selection-continuity', 'the accepted selection')
+  if (document.schema !== SELECTION_CONTINUITY_SCHEMA || document.workspaceId !== workspaceId || document.homeDigest !== homeDigest
+    || !count(document.highestSequence) || !count(document.accepted.sequence) || document.accepted.sequence > document.highestSequence
+    || !Array.isArray(document.seen) || document.seen.length > MAX_SELECTION_IDENTITIES || document.seen.some((digest) => typeof digest !== 'string' || !DIGEST.test(digest))
+    || !Array.isArray(document.confirmations) || document.confirmations.length > MAX_SELECTION_IDENTITIES || document.confirmations.some((id) => typeof id !== 'string' || !CONFIRMATION_ID.test(id))
+    || new Set(document.confirmations).size !== document.confirmations.length
+    || new Set(document.seen).size !== document.seen.length || document.highestSequence > document.seen.length
+    || (document.accepted.sequence === 0 ? document.accepted.head !== 'genesis' : !document.seen.includes(document.accepted.head))) invalid()
+  return document
+}
+
+export function createSelectionContinuity({ workspaceRoot, workspaceId, personalHome, validateLocation = () => {} }) {
+  const homeDigest = createHash('sha256').update(personalHome).digest('hex')
+  const directory = () => ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, 'state', 'maintenance'), label: 'selection continuity state' })
+  const file = path.join(workspaceRoot, 'state', 'maintenance', 'selection-continuity.json')
+  const lockPath = path.join(workspaceRoot, 'state', 'maintenance', 'selection-continuity.lock')
+  let observedState = false
+  let pending = null // an observed head whose durable write has not yet been proved
+  // The durable accepted head that pending was planned over. Pending keeps its maxima and identities, but never its
+  // accepted head once another writer has durably accepted something else.
+  let pendingBase = null
+  function read({ initializing = false } = {}) {
+    directory()
+    let fd
+    try {
+      fd = openRegularFileNoFollow(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0))
+      if (fs.fstatSync(fd).size > MAX_SELECTION_CONTINUITY_BYTES) invalid()
+      const bytes = fs.readFileSync(fd)
+      if (bytes.length > MAX_SELECTION_CONTINUITY_BYTES) invalid()
+      const document = validate(JSON.parse(bytes), workspaceId, homeDigest)
+      observedState = true
+      return document
+    } catch (error) {
+      if (error.code === 'ENOENT' && !observedState) {
+        const ownership = inspectPrivateLock(lockPath)
+        const unused = ownership.available && ownership.reason === 'unused' && ownership.generation === 0
+        // Only called inside withPrivateLock's operation: generation one is this operation's own first ticket.
+        const ownFirstTicket = initializing && !ownership.available && ownership.reason === 'process exists' && ownership.generation === 1
+        if (ownership.legacyDigest === null && (initializing ? ownFirstTicket : unused)) return null
+      }
+      invalid()
+    } finally { if (fd !== undefined) fs.closeSync(fd) }
+  }
+  function next(before, head) {
+    const seen = new Set(before?.seen ?? [])
+    const confirmations = new Set(before?.confirmations ?? [])
+    const same = before?.accepted.sequence === head.sequence && before?.accepted.head === head.head
+    // Length alone never proves continuation: the verified chain must still hold the accepted head at its position.
+    const extendsAccepted = before === null || before.accepted.sequence === 0
+      || (head.sequence > before.accepted.sequence && head.recordDigests[before.accepted.sequence - 1] === before.accepted.head)
+    const shorter = before !== null && (head.sequence < before.highestSequence || head.sequence <= before.accepted.sequence || !extendsAccepted)
+    const fresh = head.confirmationId !== null && !confirmations.has(head.confirmationId) && !seen.has(head.head)
+    if (!same && shorter && !fresh) refuse('selection-history-shortened', 'the selection history no longer follows the private continuity state; restore the removed records or confirm the selection again', SOURCE)
+    for (const digest of head.recordDigests) seen.add(digest)
+    for (const id of head.confirmationIds) confirmations.add(id)
+    if (seen.size > MAX_SELECTION_IDENTITIES || confirmations.size > MAX_SELECTION_IDENTITIES) refuse('selection-continuity-capacity', 'the private selection continuity state has reached its identity limit; nothing is loaded', SOURCE)
+    return validate({ schema: SELECTION_CONTINUITY_SCHEMA, workspaceId, homeDigest,
+      highestSequence: Math.max(before?.highestSequence ?? 0, head.sequence), accepted: { sequence: head.sequence, head: head.head }, seen: [...seen].sort(), confirmations: [...confirmations].sort() }, workspaceId, homeDigest)
+  }
+  function withPending(current) {
+    if (pending === null) return current
+    if (current === null) return pending
+    const seen = [...new Set([...current.seen, ...pending.seen])].sort()
+    const confirmations = [...new Set([...current.confirmations, ...pending.confirmations])].sort()
+    if (seen.length > MAX_SELECTION_IDENTITIES || confirmations.length > MAX_SELECTION_IDENTITIES) refuse('selection-continuity-capacity', 'the private selection continuity state has reached its identity limit; nothing is loaded', SOURCE)
+    const durableMoved = canonicalJson(current.accepted) !== pendingBase
+    return { ...pending, highestSequence: Math.max(current.highestSequence, pending.highestSequence), seen, confirmations,
+      accepted: durableMoved || current.highestSequence > pending.highestSequence ? current.accepted : pending.accepted }
+  }
+  function note(head) {
+    try {
+      validateLocation()
+      const disk = read()
+      const before = withPending(disk)
+      const planned = next(before, head)
+      if (disk !== null && canonicalJson(disk) === canonicalJson(planned)) { pending = null; pendingBase = null; return head }
+      if (pending === null || (disk !== null && canonicalJson(disk.accepted) !== pendingBase)) pendingBase = disk === null ? null : canonicalJson(disk.accepted)
+      pending = planned
+      // Proven again before the lock is taken and before the checkpoint is replaced.
+      validateLocation()
+      withPrivateLock(lockPath, () => {
+        const current = read({ initializing: disk === null })
+        // Decided again over the checkpoint as it reads under the lock.
+        const document = next(withPending(current), head)
+        pendingBase = current === null ? null : canonicalJson(current.accepted)
+        pending = document
+        const text = canonicalJson(document)
+        if (Buffer.byteLength(text) > MAX_SELECTION_CONTINUITY_BYTES) invalid()
+        validateLocation()
+        if (current === null || canonicalJson(current) !== text) atomicReplacePrivateText(file, text)
+        // An uncertain write is never authority to return a project.
+        if (canonicalJson(read()) !== text) invalid()
+      })
+      pending = null
+      pendingBase = null
+      return head
+    } catch (error) {
+      if (error instanceof ObsidianMaintenanceRefusal) throw error
+      refuse('selection-continuity-unavailable', 'the private selection continuity state could not be kept; nothing is loaded', SOURCE)
+    }
+  }
+  return Object.freeze({ note })
+}

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 { RELEASE_CHANGED, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
+import { loadSelectedProjectOffThread, locatePersonalHome } from './personal-selection.mjs'
+import { RELEASE_CHANGED, isLocationRefusalCode, 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,17 +82,54 @@ 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),
+    threw: () => first.threw === true,
+    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, and null when locating the workspace refused or a personal home's locator refused: the recorded
+// coordinates are not proven outside the roots declared now. A refusal is then printed only, into the unit's own
+// output file.
+function startupWorkspace({ project, located = false, locatorRefused = false, dataRoot, workspaceId, env = process.env, platform = process.platform }) {
+  if (located && locatorRefused) return null
   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 */ }
+  } catch { return null }
   if (typeof dataRoot !== 'string' || !path.isAbsolute(dataRoot) || typeof workspaceId !== 'string') return null
   try {
     const root = workspaceStateRoot(path.resolve(dataRoot), workspaceId)
@@ -120,10 +162,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, located, locatorRefused: first?.threw() === true, 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,9 +177,12 @@ 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) })
-    if (startup && code !== null) { recordStartup(workspace, { at, outcome: 'refused', code }); process.exitCode = 0; return }
+    // 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)
+    // A location refusal is printed only: nothing more is written under that private-state root.
+    const location = isLocationRefusalCode(code)
+    ;(location ? printed : log)({ at, event: 'refused', code: code ?? 'untyped-error', message: readOr(() => String(error?.message ?? error), 'unprintable') })
+    if (startup && code !== null) { if (!location) recordStartup(workspace, { at, outcome: 'refused', code }); process.exitCode = 0; return }
     process.exitCode = code !== null ? EXIT_REFUSED : 1
   }
 }
@@ -149,13 +198,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, dataRoot, env }) : () => 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),
@@ -167,7 +219,7 @@ const invokedDirectly = (() => { try { return Boolean(process.argv[1]) && fs.rea
 if (invokedDirectly) {
   const argv = process.argv.slice(2)
   // As early as this entry can: its static imports have already loaded most of the modules, so a release that changes
-  // between this process's start and this reading is not noticed until the next change (docs/obsidian.md says so).
+  // between this process's start and this reading is not noticed until the next change (docs/guides/obsidian.md says so).
   const releaseWatch = argv.includes('--startup') ? watchRelease(process.argv[1]) : null
   let options = null
   try {