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

package/src/runtime/obsidian/engine.mjs

@@ -1,8 +1,10 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { performance } from 'node:perf_hooks'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, manifestLayoutVersion } from '../../projection/obsidian/contracts.mjs'
-import { PERSONAL_VALIDATION_PENDING, personalWorkspaceBindingOf, personalWorkspaceInputs, validatePersonalWorkspace } from '../../projection/obsidian/personal-workspace.mjs'
+import { createCooperativeBudget } from '../../projection/obsidian/materialize/prepare-view.mjs'
+import { PERSONAL_VALIDATION_PENDING, notePersonalSelectionNow, personalSelectionBehind, personalWorkspaceBindingOf, personalWorkspaceInputs, validatePersonalWorkspace } from '../../projection/obsidian/personal-workspace.mjs'
 import { PROTOCOL_ID } from '../../projection/obsidian/publication/bridge-script.mjs'
 import { PublicationRefusal, allocatedFolderState, hasCommittedGeneration, readVaultAllocation } from '../../projection/obsidian/recovery/store.mjs'
 import { canonicalJson, compareText, isoTime } from './documents.mjs'
@@ -13,7 +15,7 @@ import {
   assertOutsideRepositories, authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, protectedRoots, readLocalPointer,
   readMachineSettings, resolveDataRoot, workspaceStateRoot, writeMachineSettings,
 } from './machine-settings.mjs'
-import { configKey, listConfigFiles, listSourceFiles, listVaultNotes, readFileFacts, reconcile, sha256Digest, sourceKey, vaultKey } from './observation.mjs'
+import { configKey, hasIndexedHint, listConfigFiles, listSourceFiles, listVaultNotes, readFileFacts, reconcile, reconcileCooperatively, sha256Digest, sourceKey, vaultKey } from './observation.mjs'
 import { dispatchAutomaticApply, heldPaths, layoutHeldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
 import { createProductionSeams, eligibilityFor } from './pipeline.mjs'
 import { PLUGIN_FILES_WAIT_FOR_APP } from './plugin-presence.mjs'
@@ -103,6 +105,15 @@ export const ENGINE_PRIMITIVES = Object.freeze({
   },
   // The embedded assets observed beside the walk: those the last built graph lets a view copy, and no withheld one.
   observedAssetsOf: (graph) => (graph.assets ?? []).filter((asset) => asset.eligible === true).map(({ repo, path: assetPath }) => ({ repo, path: assetPath })),
+  // A change the guard sees in the middle of a tick is read, where it may be a confirmed selection, while it is there.
+  noteSelectionAtGuard: notePersonalSelectionNow,
+  // A loaded project pinned to a selection record below the highest record this process has read the history ending at
+  // is loaded again at the next tick, whatever the files say: another reader in the process may have read a
+  // confirmation that is gone again before this engine looked (personalSelectionBehind).
+  reloadsBehindSelection: personalSelectionBehind,
+  // After a tick that failed without a typed reason, the next one looks at every view again, as the first tick of a
+  // process does: see tick().
+  rechecksEveryViewAfterFailure: true,
   // One engine per workspace at a time, across processes.
   acquireEngineLock: acquirePrivateGenerationLock,
   // The registered proposal adapter observes the open edits on every tick, so a structural edit is recorded as
@@ -126,6 +137,33 @@ export const ENGINE_PRIMITIVES = Object.freeze({
   heldNoteDigest({ file }) {
     try { return readFileFacts(file)?.digest ?? null } catch { return null }
   },
+  // Whether an error met by the check of a tick's settings, at a wait, is a failure to read them: a file-system error
+  // (no permission, an I/O error, no descriptor left), recognised as one is where a vault is placed. Anything else is a
+  // fault of the engine and stops the tick.
+  guardReadFailed: (error) => typeof error?.code === 'string' && /^E[A-Z]+$/.test(error.code),
+  // Whether an error met when the graph build, a view's preparation or the look again before its commit reads a
+  // source is a source, or a folder of sources, removed after this tick observed it: no such file (or a parent that is
+  // no longer a folder), at a path that is gone now and that this tick's walks over the sources (before the build, and
+  // the look again after it) recorded with a digest (a source of a repository the project observes), or a folder that
+  // held such a source. A source changed during the tick is refused as `mixed-read`; one removed is refused the same,
+  // and the next tick reads everything again. Anything else stops the tick, as before: a path still there, a path the
+  // walk listed and could not read (it was recorded without a digest), or one it never listed, so a path that can never
+  // be read still fails every tick.
+  sourceRemovedSinceObserved(error, { project, index }) {
+    if ((error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') || typeof error.path !== 'string' || !(index instanceof Map)) return false
+    const missing = path.resolve(error.path)
+    if (fs.existsSync(missing)) return false
+    for (const repo of project?.repos ?? []) {
+      if (repo?.external || typeof repo?.path !== 'string' || typeof repo?.name !== 'string') continue
+      const relative = path.relative(path.resolve(repo.path), missing)
+      if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) continue
+      const posix = relative.split(path.sep).join('/')
+      if (typeof index.get(sourceKey(repo.name, posix))?.digest === 'string') return true
+      const folder = sourceKey(repo.name, `${posix}/`)
+      for (const [key, entry] of index) if (key.startsWith(folder) && typeof entry?.digest === 'string') return true
+    }
+    return false
+  },
 })
 
 const isTypedRefusal = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal || error instanceof PublicationRefusal
@@ -137,7 +175,7 @@ const digestOfJson = (value) => sha256Digest(Buffer.from(canonicalJson(value)))
 // The configuration a tick observes. A project bound to a personal workspace adds the person's authored manifest and
 // overlay and its generation's record: a change to any of them is a configuration change, so every view is prepared
 // again, asks the composition, and is refused at once when the generation no longer holds.
-const configFilesOf = (project) => [...listConfigFiles(project), ...personalWorkspaceInputs(project).map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))]
+export const configFilesOf = (project) => [...listConfigFiles(project), ...personalWorkspaceInputs(project).map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))]
 
 // An editor adapter that `build` makes, synchronously or not, the first time the publisher calls it; a refusal of
 // `build` is thrown from that call, and `refusal()` answers it afterwards.
@@ -160,6 +198,9 @@ function uncoordinatedAdapter(refusal) {
 }
 // Views a tick may be asked to prepare again, at most, before it runs.
 const MAX_PREPARATION_REQUESTS = 64
+// At most this many views a tick refuses for a file-system error are named with that error's code (`refusalCauses`); the
+// others of that tick are not named.
+const MAX_REFUSAL_CAUSES = 64
 
 function journalTime(journalId) {
   const match = /^journal-(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{3})-/.exec(journalId)
@@ -198,13 +239,32 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     quietPeriodMs, lstat = fs.lstatSync, randomBytes, env = process.env, platform = process.platform,
     // A service names where it answers health, so a lock it leaves behind can be proven abandoned.
     lockOwner = null, lockProbe = probeHealth,
+    // Answers at once, without loading, what the workspace is resolved from (locatePersonalHome), for a loader that can
+    // refuse before any project was loaded: the views published before are then told why nothing is published now.
+    locateProject = null,
   } = options
   if (typeof loadProject !== 'function') throw new TypeError('the engine needs loadProject')
   if (typeof clock !== 'function') throw new TypeError('the engine needs an injected clock')
   // No default: the production adapter reaches a running app, and only the owner of the lifecycle may decide that.
   if (typeof adapterFactory !== 'function') throw new TypeError('the engine needs an adapterFactory')
-  const seams = { ...createProductionSeams(), ...(options.seams ?? {}) }
+  const production = createProductionSeams()
+  const seams = { ...production, ...(options.seams ?? {}) }
+  // A caller that replaced prepareView and left the cooperative preparation as it ships prepares views its own way: its
+  // seam is used, synchronously, whether it handed in that one member or the production seams with that member replaced.
+  if (seams.prepareView !== production.prepareView && seams.prepareViewCooperatively === production.prepareViewCooperatively) seams.prepareViewCooperatively = null
+  // The same for the graph: a caller that replaced buildGraph and left the cooperative build as it ships builds its own way.
+  if (seams.buildGraph !== production.buildGraph && seams.buildGraphCooperatively === production.buildGraphCooperatively) seams.buildGraphCooperatively = null
   const rules = { ...ENGINE_PRIMITIVES, ...primitives }
+  // Optional local qualification telemetry. It has no authority to change a
+  // tick's result, and records elapsed boundaries rather than a budget claim.
+  const phaseTime = () => performance.timeOrigin + performance.now()
+  const reportPhase = (phase, startedMs) => {
+    try { seams.onPhase?.({ phase, startedMs, endedMs: phaseTime() }) } catch { /* telemetry never changes custody */ }
+  }
+  const measured = (phase, operation) => {
+    const startedMs = phaseTime()
+    try { return operation() } finally { reportPhase(phase, startedMs) }
+  }
 
   const index = new Map()
   const hintedKeys = new Set()
@@ -229,6 +289,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   let watching = { signature: null, handle: null }
   let known = null // { stateStore, maintenanceMode } once a workspace has been resolved
   let heldLock = null
+  let releaseOwed = false
   // Views somebody asked to have prepared and published once more, at the next tick.
   const preparationRequests = new Set()
   // The views the project declared at the last tick; null before the first.
@@ -250,6 +311,14 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   }
 
   async function takeLock(workspaceRoot, workspaceId) {
+    // A lock an earlier tick could not give back is still this process's, and its ticket on disk unreleased: a tick
+    // that tried to take it anew would find its own ticket and answer `busy` until the process ends. It is given back
+    // first. A release that fails again fails this tick, and is owed to the next.
+    if (heldLock && releaseOwed) {
+      heldLock.release()
+      heldLock = null
+      releaseOwed = false
+    }
     if (heldLock) return { acquired: true }
     const lock = await rules.acquireEngineLock({
       workspaceRoot, directory: path.join(workspaceRoot, ENGINE_LOCK_DIRECTORY), workspaceId, purpose: 'maintenance-engine', service: lockOwner, clock, proveAbandoned,
@@ -258,10 +327,18 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     return lock
   }
 
+  // Gives the lock back at the end of a tick. One that cannot be given back (its released ticket could not be written)
+  // stays held, and the failure is the tick's: the next tick gives it back before anything else. One given back owes
+  // nothing more, whether this tick took it or an earlier one could not give it back.
   function dropLock() {
     const lock = heldLock
+    if (lock === null) return
+    try { lock.release() } catch (error) {
+      releaseOwed = true
+      throw error
+    }
     heldLock = null
-    lock?.release()
+    releaseOwed = false
   }
 
   function onWatcherEvent(roots, { rootId, relative }) {
@@ -318,11 +395,13 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   // Persists "refused" or "disabled" over whatever is known, and only when a workspace already has state.
   async function persistOutcome({ enablement, state, reason, now, scopeIds = [] }) {
     if (!known) {
+      let located = project
+      try { located ??= locateProject === null ? null : locateProject() } catch { located = null }
       let pointer = null
-      try { pointer = project ? readLocalPointer(project) : null } catch { pointer = null }
+      try { pointer = located ? readLocalPointer(located) : null } catch { pointer = null }
       if (!pointer) return
       let root
-      try { root = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), pointer.workspaceId) } catch { return }
+      try { root = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project: located, env, platform }), pointer.workspaceId) } catch { return }
       const stateStore = createMaintenanceStateStore({ workspaceRoot: root, workspaceId: pointer.workspaceId })
       if (!stateStore.exists()) return
       known = { stateStore: createMaintenanceStateStore({ workspaceRoot: fs.realpathSync(root), workspaceId: pointer.workspaceId }), maintenanceMode: 'manual' }
@@ -371,7 +450,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       if (personalWorkspaceBindingOf(project) === null) project = await loadProject()
     } else {
       const config = reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full, hinted, lstat })
-      if (config.changes.length > 0) {
+      if (config.changes.length > 0 || rules.reloadsBehindSelection(project)) {
         project = await loadProject()
         reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full: true, lstat })
       }
@@ -401,6 +480,27 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     const eligibility = fixedEligibility ?? eligibilityFor({ machine, project })
     const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
     known = { stateStore, maintenanceMode: machine.maintenanceMode }
+    // A view refused for a file-system error (a vault folder that could not be allocated or placed, a configuration
+    // file that could not be read again, a source removed while it was read, candidates that could not be staged) is
+    // settled under the refusal's code alone, and such a tick ends without a failure. The error's code (`EACCES`, `EIO`,
+    // `ENOENT`), and that of a cleanup after it that failed too, are reported beside it for the service's log. Only
+    // codes shaped as a file-system error's are kept: never a message, which may name a path.
+    const refusalCauses = []
+    const errnoOf = (value) => (typeof value === 'string' && /^E[A-Z]+$/.test(value) ? value : null)
+    const noteRefusalCause = (scopeId, refusal) => {
+      const cause = errnoOf(refusal?.detail?.cause)
+      const cleanupCause = errnoOf(refusal?.detail?.cleanupCause)
+      if ((cause === null && cleanupCause === null) || refusalCauses.length >= MAX_REFUSAL_CAUSES) return
+      refusalCauses.push({ scopeId, code: refusal.code, ...(cause === null ? {} : { cause }), ...(cleanupCause === null ? {} : { cleanupCause }) })
+    }
+    // A view whose own vault cannot be placed: a typed refusal's code and detail, or `vault-location-unusable` for a
+    // file-system error there, whose code is its cause.
+    const refuseViewAlone = (scopeId, error) => {
+      const code = viewRefusalCode(error)
+      if (code === null) throw error
+      allocationRefusals.set(scopeId, code)
+      noteRefusalCause(scopeId, isTypedRefusal(error) ? error : { code, detail: { cause: error.code } })
+    }
     // Each view's vault: allocated now where this workspace decided its vaults live, when it has none and was never
     // published under the data root (vault-location.mjs). A view whose folder cannot be allocated is not prepared on
     // this tick, and its freshness says why; the other views go on.
@@ -432,11 +532,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
             vaults = known.vaults
           }
           ensureVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId, location: machine.decisions.location, projectName: projectDisplayName(project), repositoryRoots, vaults, allocatedPaths, now })
-        } catch (error) {
-          const code = viewRefusalCode(error)
-          if (code === null) throw error
-          allocationRefusals.set(scope.scopeId, code)
-        }
+        } catch (error) { refuseViewAlone(scope.scopeId, error) }
       }
     }
     // Each view's store, on its own: one whose vault cannot be placed (a record naming a folder inside a repository,
@@ -444,11 +540,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     const scopes = []
     for (const scope of enablement.scopes) {
       if (allocationRefusals.has(scope.scopeId)) continue
-      try { scopes.push({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }) } catch (error) {
-        const code = viewRefusalCode(error)
-        if (code === null) throw error
-        allocationRefusals.set(scope.scopeId, code)
-      }
+      try { scopes.push({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }) } catch (error) { refuseViewAlone(scope.scopeId, error) }
     }
 
     watch([
@@ -460,20 +552,37 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
 
     // 3. Vault notes: preserve, then queue. Compared with the bytes each note
     // was generated with, not with the previous look.
-    const pending = stateStore.readPendingEdits()
-    let edits = pending.edits
+    //
+    // Every view's notes are looked at first, and the walk waits between notes, so a large vault does not hold the
+    // listener for its whole length (at a full reconciliation every note is hashed, and after a publication the
+    // watcher has named each note it wrote). Nothing is checked at those waits and nothing is written: within
+    // Atelier only this engine commits a manifest or writes the pending edits, under the lock this tick holds, so the
+    // manifest read before the walk is the one after it. A note changed after its turn is the next tick's to see, by
+    // its stat hint or the watcher, as one changed just after a walk that ran through is. The pending edits are then
+    // read, compared and written in one stretch, as before; the bytes an edit keeps are read there, not at the walk.
     const basesOf = new Map()
     const earlierLayout = new Set()
-    for (const { scope, store } of scopes) {
-      const { manifest, bases } = trustedNoteBases(store)
-      basesOf.set(scope.scopeId, bases)
-      if (!manifest) continue
-      if (manifestLayoutVersion(manifest) === 1) earlierLayout.add(scope.scopeId)
-      const vault = reconcile({ index, files: listVaultNotes({ scopeId: scope.scopeId, vaultRoot: store.vaultRoot, manifest }), prefix: vaultKey(scope.scopeId, ''), full, hinted, lstat })
+    const looked = []
+    const vaultStartedMs = phaseTime()
+    try {
+      const budget = createCooperativeBudget()
+      for (const { scope, store } of scopes) {
+        const { manifest, bases } = trustedNoteBases(store)
+        basesOf.set(scope.scopeId, bases)
+        if (!manifest) continue
+        if (manifestLayoutVersion(manifest) === 1) earlierLayout.add(scope.scopeId)
+        const vault = await reconcileCooperatively({ index, files: listVaultNotes({ scopeId: scope.scopeId, vaultRoot: store.vaultRoot, manifest }), prefix: vaultKey(scope.scopeId, ''), full, hinted, lstat }, budget)
+        looked.push({ scope, store, manifest, bases, vault })
+      }
+    } finally { reportPhase('vault-observation', vaultStartedMs) }
+    const pending = stateStore.readPendingEdits()
+    let edits = pending.edits
+    for (const { scope, store, manifest, bases, vault } of looked) {
       const digestOf = (notePath) => index.get(vaultKey(scope.scopeId, notePath))?.digest ?? null
       const observed = observeVaultEdits({ store, workspaceId, scopeId: scope.scopeId, manifest, bases, digestOf, edits, now, preserve: rules.preserve })
       edits = observed.edits
-      // A note that has gone is restored by the publisher; its disappearance is a change, once.
+      // A note that has gone is a change, once: the view is prepared again and its read-back says the note is missing.
+      // The publisher writes it back when it next publishes a generation of the view.
       if (observed.events.length > 0 || vault.changes.some((change) => change.kind === 'removed')) changes.push({ changeClass: 'vault-note', scopeId: scope.scopeId })
     }
     stateStore.writePendingEdits({ ...pending, edits })
@@ -516,24 +625,33 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     const lateWriters = []
     const lateDocument = stateStore.readLateWriters()
     const knownFindings = new Set(lateDocument.findings.map((item) => `${item.scopeId}\u0000${item.journalId}\u0000${item.unit}\u0000${item.observedDigest}`))
-    for (const { scope, store } of scopes) {
-      const journalIds = journalsToRecheck(store, { nowMs, full, windowMs: lateWriterWindowMs })
-      if (journalIds.length === 0) continue
-      for (const finding of seams.recheckDisplacedFiles({ store, journalIds, clock })) {
-        if (finding.code !== 'late-writer-captured') continue
-        const key = `${scope.scopeId}\u0000${finding.journalId}\u0000${finding.unit}\u0000${finding.observedDigest}`
-        if (knownFindings.has(key)) continue
-        knownFindings.add(key)
-        lateWriters.push({ scopeId: scope.scopeId, journalId: finding.journalId, unit: finding.unit, notePath: finding.notePath ?? null, digestAtMove: finding.digestAtMove ?? null, observedDigest: finding.observedDigest, objectRef: finding.objectRef, detectedAt: now })
+    const lateStartedMs = phaseTime()
+    try {
+      for (const { scope, store } of scopes) {
+        const journalIds = journalsToRecheck(store, { nowMs, full, windowMs: lateWriterWindowMs })
+        if (journalIds.length === 0) continue
+        for (const finding of seams.recheckDisplacedFiles({ store, journalIds, clock })) {
+          if (finding.code !== 'late-writer-captured') continue
+          const key = `${scope.scopeId}\u0000${finding.journalId}\u0000${finding.unit}\u0000${finding.observedDigest}`
+          if (knownFindings.has(key)) continue
+          knownFindings.add(key)
+          lateWriters.push({ scopeId: scope.scopeId, journalId: finding.journalId, unit: finding.unit, notePath: finding.notePath ?? null, digestAtMove: finding.digestAtMove ?? null, observedDigest: finding.observedDigest, objectRef: finding.objectRef, detectedAt: now })
+        }
       }
-    }
+    } finally { reportPhase('late-writer-recheck', lateStartedMs) }
     if (lateWriters.length > 0) {
       const findings = [...lateDocument.findings, ...lateWriters].sort((left, right) => compareText(left.detectedAt, right.detectedAt) || compareText(left.journalId, right.journalId) || left.unit - right.unit || compareText(left.observedDigest, right.observedDigest))
       stateStore.writeLateWriters({ schema: LATE_WRITERS_SCHEMA, workspaceId, findings })
     }
 
-    // 6. Sources, settings, scopes, eligibility.
-    const sources = reconcile({ index, files: listSourceFiles(project, { assets: observedAssets }), prefix: SOURCE_PREFIX, full, hinted, lstat })
+    // 6. Sources, settings, scopes, eligibility. The walk over the sources waits between files, as the walk over the
+    // vault does; at a full reconciliation it hashes every one. A source changed after its turn is the next tick's to
+    // see, by its stat hint or the watcher, or at the latest by the next full reconciliation. When this tick builds the
+    // graph, the look again at the sources after the build (`graph-source-recheck`) refuses such a change as
+    // `mixed-read`.
+    const sourcesStartedMs = phaseTime()
+    let sources
+    try { sources = await reconcileCooperatively({ index, files: listSourceFiles(project, { assets: observedAssets }), prefix: SOURCE_PREFIX, full, hinted, lstat }, createCooperativeBudget()) } finally { reportPhase('source-observation', sourcesStartedMs) }
     for (const change of sources.changes) changes.push({ changeClass: change.changeClass })
     const { scopes: _declared, ...settingsWithoutScopes } = enablement.settings
     // What the configuration says apart from this integration's own member: a change to the member alone is an
@@ -599,37 +717,126 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
 
     // 8. Rebuild and publish.
     if (attempt.size > 0) {
+      // Cooperative preparation/publication can outlive the settings that
+      // selected this tick. Reuse the existing configuration/personal-input
+      // observation keys, machine settings and eligibility revision as the
+      // fence; do not invent another selection authority.
+      const bindings = configFilesOf(project).map(file => ({ ...file, digest: index.get(file.key)?.digest ?? null }))
+      const machineDigest = digestOfJson(machine)
+      const eligibilityRevision = String(eligibility.revision())
+      // The history's end is read once for a run of stopped views, however many views one change stops; a check that
+      // passes ends the run, so a change that stops a later view is read again.
+      let selectionNoted = false
+      const noteSelectionOnce = () => { if (!selectionNoted) { selectionNoted = true; rules.noteSelectionAtGuard(project) } }
+      const assertBindings = () => {
+        let changed
+        try {
+          changed = bindings.some(file => (readFileFacts(file.absolute)?.digest ?? null) !== file.digest)
+            || digestOfJson(readMachineSettings({ workspaceRoot, workspaceId })) !== machineDigest
+            || String(eligibility.revision()) !== eligibilityRevision
+        } catch (error) {
+          // A file that cannot be read now is not known to hold what this tick observed. The view is refused as one
+          // whose settings changed, and the next tick reads everything again: what an unreadable configuration file
+          // means is decided there, by observation and the project loader, as before.
+          if (!rules.guardReadFailed(error)) throw error
+          forceFull = true
+          // The file may be a selection record that cannot be read now (no permission, an I/O error, a file replaced while
+          // it was read): the history's end is read for the note.
+          noteSelectionOnce()
+          refuse('mixed-read', 'a file that decides source selection could not be read again while a view was being prepared or published', { cause: error.code })
+        }
+        if (changed) {
+          forceFull = true
+          // The change may be a confirmation in a personal home. The guard compares files and reads no history, so the
+          // history's end is read here for the note: a record that stopped this view counts from now on, also when it
+          // is gone again before the next tick looks.
+          noteSelectionOnce()
+          refuse('mixed-read', 'source selection or eligibility changed while a view was being prepared or published')
+        }
+        selectionNoted = false
+      }
       let built = null
+      // Whether a selected source of a prepared view moved since this tick observed it, decided as observation
+      // decides (reconcile): a source that still has the stat hint it was indexed with is taken as unchanged, and one
+      // whose hint moved is read and must still be the pinned bytes. Bytes that drift under an unchanged hint stay
+      // within observation's own bound, as they do for the graph and for a reused note: the next full reconciliation
+      // sees them. It waits between sources, and the settings that selected the view are checked at each wait.
+      const assertSourcesUnmoved = async (prepared) => {
+        const startedMs = phaseTime()
+        try {
+          const budget = createCooperativeBudget({ guard: assertBindings })
+          budget.check()
+          const roots = new Map((project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => [repo.name, repo.path]))
+          const selected = new Set(prepared.manifest.notes.map((note) => note.nodeId))
+          const attachments = new Set(prepared.manifest.attachments.map((item) => {
+            const source = item.ext?.[OBSIDIAN_EXT_KEY]
+            return source?.kind === 'embedded-asset' ? sourceKey(source.repoId, source.assetPath) : null
+          }))
+          const nodes = built.snapshot.graph.nodes.filter((node) => selected.has(node.id))
+          const assets = (built.snapshot.graph.assets ?? []).filter((asset) => attachments.has(sourceKey(asset.repo, asset.path)))
+          const pins = new Map(built.snapshot.document.repositories.flatMap((repo) => repo.files.map((file) => [sourceKey(repo.repoId, file.path), file])))
+          for (const source of [...nodes, ...assets]) {
+            await budget.checkpoint('commit-source-recheck')
+            const key = sourceKey(source.repo, source.path)
+            const root = roots.get(source.repo)
+            if (root !== undefined && hasIndexedHint(index.get(key), path.join(root, ...source.path.split('/')), lstat)) continue
+            const bytes = built.snapshot.readSource(source.repo, source.path)
+            const pin = pins.get(key)
+            if (!pin || !Buffer.isBuffer(bytes) || bytes.length !== pin.byteLength || sha256Digest(bytes) !== pin.rawDigest) refuse('mixed-read', 'a selected source changed while its view was being prepared or published; its generation is not committed')
+          }
+          budget.check()
+        } finally { reportPhase('commit-source-recheck', startedMs) }
+      }
       try {
         if (personalRefusal !== null) refuse(personalRefusal, 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
         // A personal workspace whose validity key is not confirmed yet is composed off the event loop, then built again.
         const build = () => seams.buildGraph({ project, eligibility, cache: graphCache, index, deferPersonalValidation: true })
         let graph
-        try { graph = build() } catch (error) {
-          if (error?.code !== PERSONAL_VALIDATION_PENDING) throw error
-          const verdict = await validatePersonalWorkspace(project)
-          if (verdict?.ok !== true) refuse(verdict?.code ?? 'personal-binding-unrecognized', 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
-          try { graph = build() } catch (again) {
-            if (again?.code !== PERSONAL_VALIDATION_PENDING) throw again
-            refuse('personal-graph-unconfirmed', 'the graph built for the personal workspace is not the one its composition built; nothing is prepared from it', { source: 'personal-workspace' })
+        try {
+          // Any other project is built with the event loop given a turn between the Markdown sources of the census: a
+          // first tick reads every source. The settings that select the views are checked at each wait, as during a
+          // preparation, and the look again at the sources after the build sees a source that moved during it.
+          if (typeof seams.buildGraphCooperatively === 'function' && personalWorkspaceBindingOf(project) === null) {
+            graph = await seams.buildGraphCooperatively({ project, eligibility, cache: graphCache, index, scheduling: { guard: assertBindings } })
+          } else try { graph = build() } catch (error) {
+            if (error?.code !== PERSONAL_VALIDATION_PENDING) throw error
+            const verdict = await validatePersonalWorkspace(project)
+            if (verdict?.ok !== true) refuse(verdict?.code ?? 'personal-binding-unrecognized', 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
+            try { graph = build() } catch (again) {
+              if (again?.code !== PERSONAL_VALIDATION_PENDING) throw again
+              refuse('personal-graph-unconfirmed', 'the graph built for the personal workspace is not the one its composition built; nothing is prepared from it', { source: 'personal-workspace' })
+            }
           }
+        } catch (error) {
+          if (!isTypedRefusal(error) && rules.sourceRemovedSinceObserved(error, { project, index })) refuse('mixed-read', 'a source was removed while the canonical graph was being built', { cause: error.code })
+          throw error
         }
         // The assets this graph lets a view copy are observed from now on, and hashed now so the snapshot pins
         // what observation saw. A withheld asset is not observed: its bytes can change no view.
         const formerAssetKeys = new Set(observedAssets.map((asset) => sourceKey(asset.repo, asset.path)))
         observedAssets = rules.observedAssetsOf(graph)
         const assetKeys = new Set(observedAssets.map((asset) => sourceKey(asset.repo, asset.path)))
-        const settled = reconcile({ index, files: listSourceFiles(project, { assets: observedAssets }), prefix: SOURCE_PREFIX, full: false, lstat })
+        const settled = measured('graph-source-recheck', () => reconcile({ index, files: listSourceFiles(project, { assets: observedAssets }), prefix: SOURCE_PREFIX, full: false, lstat }))
         // An asset newly observed, or one no longer embedded, is the list changing. Anything else that moved since this tick looked at the sources moved while the graph was being read.
         if (settled.changes.some((change) => !(change.kind === 'added' && assetKeys.has(change.key)) && !(change.kind === 'removed' && formerAssetKeys.has(change.key) && !assetKeys.has(change.key)))) throw new ObsidianMaintenanceRefusal('mixed-read', 'a source changed while the canonical graph was being built')
         const configDigest = digestOfJson([...index].filter(([key]) => key.startsWith(CONFIG_PREFIX)).map(([key, entry]) => [path.basename(key.slice(CONFIG_PREFIX.length)), entry.digest]))
+        const snapshot = seams.captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt: now })
+        const observedProject = project
         built = {
-          snapshot: seams.captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt: now }),
+          // A view's preparation, and the look again at its sources before the commit, read a source through the
+          // snapshot. A selected source removed after this tick observed it, read there, refuses the view as
+          // `mixed-read`, as a removal during the build does; the other views of the tick are still prepared.
+          snapshot: { ...snapshot, readSource: (repoId, relative) => {
+            try { return snapshot.readSource(repoId, relative) } catch (error) {
+              if (!isTypedRefusal(error) && rules.sourceRemovedSinceObserved(error, { project: observedProject, index })) refuse('mixed-read', 'a selected source was removed while its view was being prepared or published', { cause: error.code })
+              throw error
+            }
+          } },
           profile: seams.profileFor({ project, workspaceId, audienceAllow: machine.audienceAllow }),
         }
       } catch (error) {
         if (!isTypedRefusal(error)) throw error
-        for (const scopeId of attempt.keys()) entries.set(scopeId, demote(entries.get(scopeId), 'stale', error.code, now))
+        for (const scopeId of attempt.keys()) { entries.set(scopeId, demote(entries.get(scopeId), 'stale', error.code, now)); noteRefusalCause(scopeId, error) }
         if (REREAD_CODES.has(error.code)) forceFull = true
         // The personal workspace refused the bound generation: the project is loaded again at the next tick, so a
         // loader that now binds another generation is followed.
@@ -646,11 +853,17 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
         }
         try {
           const held = heldPaths(edits, scopeId)
-          const prepared = seams.prepareView({
+          const prepared = await (seams.prepareViewCooperatively ?? seams.prepareView)({
             snapshot: built.snapshot, profile: built.profile, scope, persistentPathRegistry: stateStore.readPathRegistry(), priorManifest: store.readCurrentManifest(),
             existingSettings: null, clock, vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8'), cache: preparationCacheFor(scopeId),
             heldNotePaths: held, layoutHeldNotePaths: layoutHeldOf(scopeId), viewScopeIds: scopes.map((item) => item.scope.scopeId),
+            // The cooperative preparation would read every selected source once more before it returns. The engine
+            // checks them itself, below and again before the commit, without opening a source observation would not.
+            scheduling: { guard: assertBindings, recheckSources: false },
           })
+          assertBindings()
+          // Before anything is written: a source that moved while the view was being prepared refuses it here.
+          await assertSourcesUnmoved(prepared)
           stateStore.writePathRegistry(prepared.persistentPathRegistry)
           diagnostics = (prepared.manifest.ext?.[OBSIDIAN_EXT_KEY]?.diagnostics ?? []).slice(0, 100)
           const preparedGenerationId = prepared.manifest.generationId
@@ -684,10 +897,13 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           }
           let result
           try {
+            // Once more while the publisher holds its locks, before it says the publication settled.
+            const beforeCommit = () => assertSourcesUnmoved(prepared)
             result = await seams.publishView({
               preparedView: prepared, protocolId: PROTOCOL_ID, expectedGeneration: trusted()?.generationId ?? null, recoveryStore: store, adapter, clock,
               ...(quietPeriodMs === undefined ? {} : { quietPeriodMs }),
               ...(typeof readUnheldEvidence === 'function' ? { unheldEvidence: readUnheldEvidence, platform } : {}),
+              scheduling: { guard: assertBindings }, beforeCommit,
             })
             // Stopped before its commit for want of an app that coordinates: the app's refusal is what the person has to
             // act on, and `open` answers it before it would add the vault to the app.
@@ -705,15 +921,24 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           const common = { generationId: pointerNow?.generationId ?? null, preparedGenerationId, retainedEdits: pointerNow?.retained?.length ?? 0 }
           if (result.state === 'refused') {
             settle(CONFLICT_REFUSALS.has(result.refusal.code) ? 'publisher-conflict' : 'stale', result.refusal.code, { ...common, heldNotes: held })
+            noteRefusalCause(scopeId, result.refusal)
           } else if (result.state === 'updating') {
             const blocking = result.notes.filter((note) => note.blocking)
             const byEdit = blocking.length > 0 && blocking.every((note) => EDIT_OUTCOMES.has(note.outcome))
             settle(byEdit ? 'held-for-your-edit' : 'publisher-conflict', blocking[0]?.outcome ?? 'publication-incomplete', { ...common, heldNotes: [...new Set([...held, ...blocking.filter((note) => EDIT_OUTCOMES.has(note.outcome)).map((note) => note.path)])].sort(compareText) })
           } else {
-            // Read back: every note of the committed generation, by digest.
-            const { manifest, bases } = trustedNoteBases(store)
+            // Read back: every note of the committed generation, by digest. The walk waits between notes, so a large
+            // view does not hold the service's listener for its whole length. Nothing is checked at those waits: the
+            // generation is committed, the view is reported as it was read, and what changes from here on is the next
+            // tick's to see, as it is after a read-back that ran through.
+            const readBackStartedMs = phaseTime()
+            let bases
+            try {
+              const committed = trustedNoteBases(store)
+              bases = committed.bases
+              await reconcileCooperatively({ index, files: listVaultNotes({ scopeId, vaultRoot: store.vaultRoot, manifest: committed.manifest }), prefix: vaultKey(scopeId, ''), full: true, lstat }, createCooperativeBudget())
+            } finally { reportPhase('publication-read-back', readBackStartedMs) }
             basesOf.set(scopeId, bases)
-            reconcile({ index, files: listVaultNotes({ scopeId, vaultRoot: store.vaultRoot, manifest }), prefix: vaultKey(scopeId, ''), full: true, lstat })
             const differing = [...bases].filter(([notePath, base]) => index.get(vaultKey(scopeId, notePath))?.digest !== base.digest).map(([notePath]) => notePath).sort(compareText)
             const editedUnderPublisher = result.notes.some((note) => note.outcome === 'edit-kept' || note.changedAfterPublication === true)
             if (held.length > 0) settle('held-for-your-edit', 'edit-pending', { ...common, heldNotes: held })
@@ -730,6 +955,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           const where = error.code === 'redaction-failure' ? error.detail ?? {} : {}
           diagnostics = typeof where.rule === 'string' ? [{ code: error.code, rule: where.rule, ...(typeof where.notePath === 'string' ? { notePath: where.notePath } : {}), ...(typeof where.filePath === 'string' ? { filePath: where.filePath } : {}) }] : []
           settle('stale', error.code)
+          noteRefusalCause(scopeId, error)
           if (REREAD_CODES.has(error.code)) forceFull = true
         }
       }
@@ -748,7 +974,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       state: 'ticked', full, workspaceId, maintenanceMode: machine.maintenanceMode,
       changes: changes.map((change) => ({ ...change })), scopes: [...entries.values()].sort((left, right) => compareText(left.scopeId, right.scopeId)),
       pendingEdits: edits.filter((edit) => edit.closedAt === null).map(({ editId, scopeId, path: notePath, state }) => ({ editId, scopeId, path: notePath, state })),
-      dispatched, lateWriters, ...(observed === null ? {} : { observed }), ...(proposals === null ? {} : { proposals }),
+      dispatched, lateWriters, ...(observed === null ? {} : { observed }), ...(proposals === null ? {} : { proposals }), ...(refusalCauses.length === 0 ? {} : { refusalCauses }),
     }
   }
 
@@ -770,7 +996,19 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       try {
         return await runTick()
       } catch (error) {
-        if (!isTypedRefusal(error)) throw error
+        if (!isTypedRefusal(error)) {
+          // A tick that failed without a typed reason may have looked at files and recorded what it saw in the index
+          // without acting on it: a note gone from a vault, a source that changed, or a configuration file that changed
+          // before the project could be loaded again, is a change once, and the next look would find nothing to change.
+          // The next tick therefore starts as the first tick of a process does: it loads the project again and looks
+          // at every view, so whatever is missing or changed makes its view stale, or is published, not left current.
+          if (rules.rechecksEveryViewAfterFailure) {
+            project = null
+            semantic = null
+            firstTick = true
+          }
+          throw error
+        }
         // Fail closed: nothing is published under a refusal, and every known view says why.
         try { await persistOutcome({ enablement: 'refused', state: 'stale', reason: error.code, now: isoTime(clock) }) } catch { /* the refusal itself is still reported */ }
         project = null