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

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

@@ -1,8 +1,12 @@
+import fs from 'node:fs'
 import path from 'node:path'
-import { PersonalWorkspaceRefusal, readPersonalSelectionHead } from '@mnstry/atelier/personal-workspace'
+import { PersonalWorkspaceRefusal } 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'
+import { readPersonalSelectionSnapshot } from '../../personal-workspace/selection.mjs'
+import { assertOutsideRepositories, ensureWorkspaceIdentity, resolveDataRoot, workspaceStateRoot } from './machine-settings.mjs'
+import { createSelectionContinuity } from './selection-continuity.mjs'
 
 // A person's confirmed selection, bound to the maintenance runtime.
 //
@@ -42,21 +46,19 @@ import { refuse } from './errors.mjs'
 // 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
+// history that ends earlier than the highest record noted requires a fresh confirmation or refuses
+// `selection-history-shortened` at a load and at a recheck; 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).
+// The highest number, accepted head and observed record identities are also kept in the workspace's private
+// continuity state. A start of the service reads that evidence too. A shorter history remains refused until the
+// removed records return or the person makes a fresh confirmation. New confirmations have a unique identity, so
+// confirming the same generation against the same predecessor is distinct from restoring an old record's bytes.
 //
-// Who may see a vault is not decided here: that stays the machine's setting.
+// Who may see a vault stays the machine's setting: the engine initializes an undecided personal binding as owner only.
 //
 // 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
@@ -78,30 +80,88 @@ export const SELECTION_PRIMITIVES = Object.freeze({
 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) {
+const CONTINUITY = new Map()
+
+// Exclusion roots only, shared by location and continuity. Composition remains
+// the authority for the manifest and generation. Never wait on an irregular
+// file while resolving the machine's private state.
+function manifestExclusionRoots(personalHome) {
+  let manifest
+  let descriptor
+  try {
+    descriptor = fs.openSync(path.join(personalHome, 'atelier.personal.json'), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK ?? 0))
+    const stat = fs.fstatSync(descriptor)
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new PersonalWorkspaceRefusal('malformed-input')
+    const bytes = fs.readFileSync(descriptor)
+    if (bytes.length > 1024 * 1024) throw new PersonalWorkspaceRefusal('malformed-input')
+    try { manifest = JSON.parse(bytes) } catch { throw new PersonalWorkspaceRefusal('malformed-input') }
+    if (!Array.isArray(manifest?.repos) || manifest.repos.some((repo) => typeof repo?.root !== 'string' || !path.isAbsolute(repo.root) || repo.root.includes('\0'))) throw new PersonalWorkspaceRefusal('malformed-input')
+  } catch (error) {
+    refuse(error instanceof PersonalWorkspaceRefusal ? error.code : 'personal-home-unavailable', 'the personal workspace manifest could not be read; no selection is loaded', SOURCE)
+  } finally { if (descriptor !== undefined) fs.closeSync(descriptor) }
+  return manifest.repos.map((repo) => repo.root)
+}
+
+function continuityFor({ personalHome, dataRoot, env = process.env, platform = process.platform }) {
+  const project = locatePersonalHome({ personalHome })
+  const repositoryRoots = [personalHome, ...project.repos.map((repo) => repo.path)]
+  const rootOf = (named) => workspaceStateRoot(resolveDataRoot({ dataRoot, pointer: named, project, env, platform }), named.workspaceId)
+  // The location is proven outside every declared root before a first use writes its pointer.
+  const pointer = ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }),
+    validate: (named) => assertOutsideRepositories({ managedRoot: rootOf(named), repositoryRoots }) })
+  const root = rootOf(pointer)
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 })
+  const workspaceRoot = fs.realpathSync(root)
+  const key = `${personalHome}\0${workspaceRoot}`
+  // A retained store writes later, after the manifest may have changed: each write proves the location again from
+  // the manifest as it reads now, and a refusal there writes nothing.
+  if (!CONTINUITY.has(key)) CONTINUITY.set(key, createSelectionContinuity({ workspaceRoot, workspaceId: pointer.workspaceId, personalHome,
+    validateLocation: () => assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots: personalExclusionRootsNow(personalHome) }) }))
+  return CONTINUITY.get(key)
+}
+
+// The roots a personal home's private state must stay outside, read from its manifest now. Read-only.
+export function personalExclusionRootsNow(personalHome) {
+  return [personalHome, ...manifestExclusionRoots(personalHome)]
+}
+
+function confirmedHead(options, rules) {
+  const { personalHome } = options
+  locatePersonalHome({ personalHome })
   let head
-  try { head = readPersonalSelectionHead({ personalHome }) } catch (error) {
+  try { head = readPersonalSelectionSnapshot({ 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)
+  const continuity = continuityFor(options)
+  const note = (current) => { if (rules.refusesShortened) continuity.note(current) }
+  notePersonalSelectionHead(personalHome, head, { ...rules, note })
   if (head.selected === null) refuse('nothing-selected', 'no generation of the personal workspace is confirmed; nothing is loaded until one is', SOURCE)
-  return head
+  return { head, note }
 }
 
-function pinned(project, head, rules) {
-  pinPersonalSelection(project, head, { ...rules.pin, refusesShortened: rules.refusesShortened })
+function pinned(project, { head, note }, rules) {
+  pinPersonalSelection(project, head, { ...rules.pin, refusesShortened: rules.refusesShortened, note })
   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.
+// as its folder, plus the manifest's repository roots for exclusion only. A locator never admits a generation or
+// notes a history head. 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. A missing home still locates no prepared workspace.
 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 }
+  let stat = null
+  try { stat = fs.lstatSync(personalHome) } catch (error) { if (error.code !== 'ENOENT') refuse('personal-home-unavailable', 'the personal home could not be inspected', SOURCE) }
+  if (stat !== null) {
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(personalHome) !== personalHome) refuse('root-symlinked', 'a personal home is its private directory, not a link', SOURCE)
+    if (typeof process.getuid !== 'function' || stat.uid !== process.getuid() || (stat.mode & 0o022) !== 0) refuse('not-private-location', 'a personal home is private to its owner', SOURCE)
+  }
+  // Include all declared roots, even a withdrawn enrollment: locating state
+  // must not write into a repository while composition is unavailable.
+  const roots = stat === null ? [] : manifestExclusionRoots(personalHome)
+  const located = { configDir: personalHome, repos: roots.map((root) => ({ path: root, external: false })), [LOCATED]: personalHome }
   located.localState = ensureLocalState(located, { write: false, env: { PATH: process.env.PATH } })
   return located
 }
@@ -113,13 +173,15 @@ 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)
+export function loadSelectedProject(options = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const { personalHome } = options
+  const selected = confirmedHead(options, rules)
+  return pinned(loadBoundProject({ personalHome, generationId: selected.head.selected }, { bind }), selected, 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)
+export async function loadSelectedProjectOffThread(options = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const { personalHome } = options
+  const selected = confirmedHead(options, rules)
+  return pinned(await loadBoundProjectOffThread({ personalHome, generationId: selected.head.selected }, { bind }), selected, rules)
 }

package/src/runtime/obsidian/pipeline.mjs

@@ -1,5 +1,6 @@
 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, buildCanonicalGraphSteps, createGraphFileCache } from '../../graph/graph.mjs'
 import { markdownMetadata } from '../../graph/knowledge-graph.mjs'
@@ -130,8 +131,14 @@ export function profileFor({ project, workspaceId, audienceAllow }) {
 // on this thread.
 export function buildGraph({ project, eligibility, cache = null, index = null, deferPersonalValidation = false }) {
   const observedDigest = observedDigestOf(cache, index)
-  const canonical = personalWorkspaceGraph(project, { fileCache: cache, observedDigest, defer: deferPersonalValidation }) ?? buildCanonicalGraph(project, { fileCache: cache, observedDigest })
-  return eligibleGraph(canonical, eligibility)
+  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
@@ -143,7 +150,7 @@ export async function buildGraphCooperatively({ project, eligibility, cache = nu
   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)
+  if (personal !== null) return eligibleGraph(personal, eligibility, { project, index })
   const budget = createCooperativeBudget(scheduling)
   budget.check()
   const steps = buildCanonicalGraphSteps(project, { fileCache: cache, observedDigest })
@@ -156,16 +163,66 @@ export async function buildGraphCooperatively({ project, eligibility, cache = nu
     }
   } catch (error) {
     steps.return?.()
+    refuseObservedDirectory(error, { project, index })
     throw error
   }
   budget.finish('graph-assembled')
-  return eligibleGraph(canonical, eligibility)
+  return eligibleGraph(canonical, eligibility, { project, index })
 }
 
 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 })
+// 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 }))
 }
 
@@ -190,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 })
@@ -217,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
+      }
+    },
   }
 }
 

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')
@@ -128,7 +128,11 @@ 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) {
@@ -140,6 +144,7 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
   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)
@@ -167,6 +172,10 @@ export async function acquirePrivateGenerationLock({ workspaceRoot, directory, w
     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 */ }
   }

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

@@ -5,7 +5,7 @@ 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'
+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`.
@@ -108,6 +108,7 @@ function firstAnswerOf(loadProject) {
   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
@@ -120,12 +121,15 @@ function firstAnswerOf(loadProject) {
 // 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, 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 }) {
+// 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 = 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)
@@ -162,7 +166,7 @@ export async function runServiceProcess(options) {
   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 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, ...(first === null ? {} : { [located ? 'locateProject' : 'loadProject']: first.loadProject }) })
@@ -175,8 +179,10 @@ export async function runServiceProcess(options) {
     const at = new Date().toISOString()
     // 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 }
+    // 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
   }
 }
@@ -200,7 +206,7 @@ export function serviceOptionsFromArgv(argv, { env = process.env } = {}) {
   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: personalHome !== null ? () => loadSelectedProjectOffThread({ personalHome }) : () => 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']) } : {}),
@@ -213,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 {

package/src/runtime/obsidian/service.mjs

@@ -76,6 +76,15 @@ export function serviceWorkspaceInputs(project) {
 }
 
 // Where a workspace keeps its private state, without creating an identity.
+// The same location check resolveServiceWorkspace applies, for an identity that is not yet persisted.
+export function serviceLocationCheck({ project: whole, dataRoot, env = process.env, platform = process.platform }) {
+  const project = serviceWorkspaceInputs(whole)
+  return (pointer) => assertOutsideRepositories({
+    managedRoot: workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), pointer.workspaceId),
+    repositoryRoots: protectedRoots(project),
+  })
+}
+
 export function resolveServiceWorkspace({ project: whole, dataRoot, env = process.env, platform = process.platform, create = false }) {
   const project = serviceWorkspaceInputs(whole)
   const pointer = readLocalPointer(project)
@@ -87,6 +96,8 @@ export function resolveServiceWorkspace({ project: whole, dataRoot, env = proces
   return { workspaceId: pointer.workspaceId, workspaceRoot: fs.realpathSync(requested) }
 }
 
+// A refusal that the private-state root is no longer proven outside every declared root: nothing more is written there.
+export const isLocationRefusalCode = (code) => /^managed-root-|^repository-inside-managed-root$/.test(String(code ?? ''))
 const isTyped = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal
 const errorCode = (error) => (typeof error?.code === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(error.code) ? error.code : 'untyped-error')
 const errorName = (error) => (typeof error?.name === 'string' ? error.name.slice(0, 64) : 'Error')
@@ -237,6 +248,8 @@ export async function runMaintenanceService(options = {}) {
         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
+      // A tick the engine refused for the location of private state leaves the error record as it is.
+      if (isLocationRefusalCode(outcome.report.refusal?.code)) return
       const previous = readLastServiceError({ workspaceRoot, workspaceId })
       if (previous && previous.resolvedAt === null) writeLastServiceError({ workspaceRoot, workspaceId, document: { ...previous, consecutiveFailures: 0, resolvedAt: at } })
       return
@@ -245,6 +258,7 @@ export async function runMaintenanceService(options = {}) {
     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 })
+    if (isLocationRefusalCode(outcome.error?.code)) return
     let previous = null
     try { previous = readLastServiceError({ workspaceRoot, workspaceId }) } catch { previous = null }
     writeLastServiceError({ workspaceRoot, workspaceId, document: { schema: SERVICE_ERROR_SCHEMA, workspaceId, runtimeId, code: errorCode(outcome.error), name: errorName(outcome.error), at, consecutiveFailures, totalFailures: (previous?.totalFailures ?? 0) + 1, resolvedAt: null } })

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

@@ -6,7 +6,7 @@ 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
+// (publisher.mjs; docs/reference/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

package/src/runtime/obsidian/view-permission.mjs

@@ -167,7 +167,8 @@ export const DEFAULT_ROW_ENDS_AFTER_MS = 60 * 1000
 // fails at every reload and answers only at its retry keeps one row. A row of loads after which nothing is kept ends
 // at the next that keeps a project. A load that named other files than it started over (the first, or one after a
 // change that names other files) neither counts nor ends that row, so a start and a change, each with one load that
-// has nothing to agree with yet, write none of these, unless the change lands while a load reads the files. Any other
+// has nothing to agree with yet, write none of these, unless the change lands while a load reads the files, names the
+// same files and changes the views or what the workspace is resolved from (docs/reference/obsidian-plugin.md). Any other
 // load that answered in time and kept the project writes nothing unless it ends a row of failures: that is every load
 // of a healthy service. A line holds the event, milliseconds, the outcome, flags and counts; never a path, a view or a
 // message.