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

package/src/projection/obsidian/materialize/prepare-view.mjs

@@ -1,3 +1,59 @@
+import { performance } from 'node:perf_hooks'
+
+// What the caller of cooperative work stopped it with: its `signal`, or its
+// `guard` (the engine's check that the settings which selected a view still
+// hold). Such an error is marked, so whatever catches it on the way out can
+// tell it from a failure of the work itself and hand it on under its own code.
+const SCHEDULING_STOP = Symbol('atelier.cooperative-stop')
+const markedStop = (error) => {
+  if (error !== null && typeof error === 'object') { try { Object.defineProperty(error, SCHEDULING_STOP, { value: true }) } catch { /* a frozen error stays unmarked */ } }
+  return error
+}
+export const isSchedulingStop = (error) => error !== null && typeof error === 'object' && error[SCHEDULING_STOP] === true
+
+// Internal scheduling shared by preparation and publication. The budget is a
+// yield target, not a deadline: one checked unit and native fsync stay atomic.
+export function createCooperativeBudget({ budgetMs = 8, maxUnits = 32, signal, guard = null, onBurst = null } = {}) {
+  if (!(Number.isFinite(budgetMs) && budgetMs > 0 && Number.isInteger(maxUnits) && maxUnits > 0)) throw new TypeError('finite positive scheduling budget required')
+  let started = performance.now(), units = 0, maxUnitMs = 0, last = started
+  const checkSignal = () => {
+    if (signal?.aborted) { const error = new Error('cooperative work cancelled at a completed boundary'); error.code = 'ABORT_ERR'; throw markedStop(error) }
+  }
+  const check = () => {
+    checkSignal()
+    if (guard) { try { guard() } catch (error) { throw markedStop(error) } }
+  }
+  const checkpoint = async (phase, force = false) => {
+    const now = performance.now()
+    maxUnitMs = Math.max(maxUnitMs, now - last); units += 1
+    checkSignal()
+    if (force || units >= maxUnits || now - started >= budgetMs) {
+      check()
+      onBurst?.({ phase, elapsedMs: now - started, units, maxUnitMs })
+      await new Promise(resolve => setImmediate(resolve))
+      check()
+      started = performance.now(); units = 0; maxUnitMs = 0
+    }
+    last = performance.now()
+  }
+  const finish = phase => { const now = performance.now(); maxUnitMs = Math.max(maxUnitMs, now - last); onBurst?.({ phase, elapsedMs: now - started, units: units + 1, maxUnitMs }) }
+  return { checkpoint, check, finish }
+}
+
+async function runCooperatively(iterator, options) {
+  const budget = createCooperativeBudget(options)
+  budget.check()
+  try {
+    for (;;) {
+      const step = iterator.next()
+      if (step.done) { budget.finish('prepare-finalize'); return step.value }
+      if (step.value === 'final-cache-commit') budget.check()
+      else await budget.checkpoint(step.value)
+    }
+  } catch (error) { iterator.return?.(); throw error }
+}
+
+
 import { createHash } from 'node:crypto'
 import { unclosedFenceAtEnd } from '../../../graph/knowledge-graph.mjs'
 import {
@@ -19,7 +75,7 @@ import { isUserOwnedSettingsPath, prepareSettings } from './settings.mjs'
 //
 // A view is laid out in vault layout 2: folders mirror the repository, the
 // file name is the note's title and each note names its identity in generated
-// front-matter properties (see "Vault layout" in docs/obsidian-contract.md).
+// front-matter properties (see "Vault layout" in docs/reference/obsidian-contract.md).
 // Layout 1, the earlier release's, is kept for a view whose prior generation
 // is in layout 1 and holds a note with an open edit, and for recovering a
 // layout 1 generation as it was published.
@@ -638,14 +694,14 @@ function layoutOf({ layout, priorManifest, layoutHeld }) {
 }
 
 export function prepareView(options = {}) {
-  return prepareWithRules(REDACTION_RULES, options)
+  return drainPreparation(prepareSteps(REDACTION_RULES, options))
 }
 
 // Test seam only: the mutation controls of the redaction guard substitute a
 // rule through this. Runtime code uses prepareView.
 export function createViewPreparationForOracleTests(rules = REDACTION_RULES) {
   const guard = { ...REDACTION_RULES, ...rules }
-  return (options = {}) => prepareWithRules(guard, options)
+  return (options = {}) => drainPreparation(prepareSteps(guard, options))
 }
 
 // `heldNotePaths` are the vault files held for an open edit: they stay in the
@@ -653,7 +709,7 @@ export function createViewPreparationForOracleTests(rules = REDACTION_RULES) {
 // notes that hold a layout 1 view in layout 1 (open edits and edits closed on
 // this tick); without it, `heldNotePaths` do. `viewScopeIds`, when given, are
 // the views still maintained: the registry drops the sections of any other.
-function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegistry = null, priorManifest = null, existingSettings = null, plugin = null, clock, generationId, vaultRootBytes, maxFullPathBytes, cache = null, heldNotePaths = null, layoutHeldNotePaths = null, viewScopeIds = null, layout: requestedLayout } = {}) {
+function* prepareSteps(guard, { snapshot, profile, scope, persistentPathRegistry = null, priorManifest = null, existingSettings = null, plugin = null, clock, generationId, vaultRootBytes, maxFullPathBytes, cache = null, heldNotePaths = null, layoutHeldNotePaths = null, viewScopeIds = null, layout: requestedLayout } = {}, recheckSources = false) {
   if (cache !== null && !isPreparationCache(cache)) refuse('invalid-preparation-cache', 'the preparation cache must come from createPreparationCache')
   assertObsidianContract('corpus-profile', profile)
   assertObsidianContract('scope', scope)
@@ -670,6 +726,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   if (viewScopeIds !== null && !(Array.isArray(viewScopeIds) && viewScopeIds.every((id) => typeof id === 'string'))) refuse('invalid-view-scopes', 'viewScopeIds must be an array of scope identities')
   const layout = layoutOf({ layout: requestedLayout, priorManifest, layoutHeld: layoutHeldNotePaths ?? heldNotePaths ?? [] })
   const checkedAt = timestampFrom(clock)
+  yield 'prepare-validation'
   const canonical = canonicalSnapshotOf(snapshot.graph)
 
   // Selection and visibility come from the contract, never from this module.
@@ -686,6 +743,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   // Every view's allocation of the registry, this one's included; a registry of another shape or workspace refuses.
   const views = viewsOfRegistry(persistentPathRegistry, profile.workspaceId)
 
+  yield 'selection-and-universe'
   const edgeById = new Map(canonical.edges.map((edge) => [edge.id, edge]))
   const vaultEdges = selection.vaultEdges.map((id) => edgeById.get(id)).filter((edge) => vault.has(edge.source) && vault.has(edge.target))
   const outsideEdges = selection.outsideSelectionEdges.map((id) => edgeById.get(id)).filter((edge) => vault.has(edge.source) !== vault.has(edge.target))
@@ -714,6 +772,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   // taken. A view prepared in layout 1 holds layout 1 files, none of which is a
   // layout 2 path. The registry keeps the result as this view's section,
   // whichever layout the view is prepared in.
+  yield 'link-and-asset-index'
   const readable = allocateViewPaths({
     published: publishedOf(priorManifest),
     nodes: [...vault].map((id) => nodeById.get(id)),
@@ -747,6 +806,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
     return { key: { edgeKey: occurrence.target }, markdown: target.markdown, wikilink: target.wikilink, alias: true }
   }
 
+  yield 'path-allocation'
   const read = sourceReader(snapshot)
   const orderedNodes = [...vault].map((id) => nodeById.get(id)).sort((left, right) => compare(left.repo, right.repo) || compare(left.id, right.id))
   // Edges indexed by endpoint once, so a note's rows cost its degree and not
@@ -778,6 +838,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   const titles = titleRenderings()
 
   for (const node of orderedNodes) {
+    yield 'emit-note'
     const notePathValue = pathOf(node)
     const attachmentPathValue = node.extension === 'md' ? null : attachmentOf(node)
     const pinned = read.pinned(node.repo, node.path)
@@ -814,12 +875,14 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   // One copy per asset, however many notes embed it, read through the pinned
   // snapshot like every other source.
   for (const asset of embeddedAssets.values()) {
+    yield 'emit-asset'
     const attachmentPath = assetPaths.get(asset.id)
     const { bytes, rawDigest } = read(asset.repo, asset.path)
     attachments.push({ path: attachmentPath, digest: rawDigest, byteLength: bytes.length, ext: { [EXT_KEY]: { kind: 'embedded-asset', repoId: asset.repo, assetPath: asset.path } } })
     files.push({ path: attachmentPath, kind: 'attachment', bytes, digest: rawDigest })
   }
 
+  yield 'emit-complete'
   const links = vaultEdges
     .map((edge) => {
       const inversions = edge.type === DERIVED_RELATION_TYPE ? inversionsByEdge.get(`${edge.source}\u0000${edge.target}`) ?? [] : []
@@ -835,6 +898,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
     })
     .sort((left, right) => compare(left.edgeId, right.edgeId))
 
+  yield 'manifest-links'
   const settings = prepareSettings({ existing: existingSettings, plugin })
   files.push(...settings.files)
   const occupied = new Set()
@@ -847,6 +911,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   files.sort((left, right) => compare(left.path, right.path))
   attachments.sort((left, right) => compare(left.path, right.path))
 
+  yield 'settings-and-path-guard'
   const contentDigest = createHash('sha256')
   for (const file of files) contentDigest.update(`${file.path}\u0000${file.digest}\n`)
   const manifest = {
@@ -877,6 +942,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   // the audience may see but this view does not select, every identifier is
   // reported. An identifier this view's own notes share names nothing outside
   // it.
+  yield 'manifest-validation'
   const viewAttachments = new Set(attachments.map((item) => item.path))
   const visible = new Set(universe.nodes)
   const censusRepositories = new Set([...canonical.nodes, ...censusAssets].filter(usable).map((item) => item.repo))
@@ -927,6 +993,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   const allocatedInView = new Map(orderedNodes.map((node) => [node.id, pathOf(node)]))
   const wrapperAttachments = new Set(orderedNodes.filter((node) => node.extension !== 'md').map((node) => (legacy ? `attachments/${legacyBasename(pathOf(node))}.${/^[a-z0-9]{1,16}$/.test(String(node.extension).toLowerCase()) ? String(node.extension).toLowerCase() : 'bin'}` : attachmentOf(node))))
   const allowedAttachments = new Set([...wrapperAttachments, ...assetPaths.values()])
+  yield 'redaction-index'
   const guardReported = assertViewRedaction({
     manifest,
     files,
@@ -954,6 +1021,7 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
     })
   }
 
+  yield 'redaction-validation'
   const prior = new Map((priorManifest?.notes ?? []).map((note) => [note.path, note.noteDigest]))
   const changes = { added: [], changed: [], unchanged: [], removed: [] }
   for (const note of notes) changes[!prior.has(note.path) ? 'added' : prior.get(note.path) === note.noteDigest ? 'unchanged' : 'changed'].push(note.path)
@@ -962,8 +1030,16 @@ function prepareWithRules(guard, { snapshot, profile, scope, persistentPathRegis
   // under the publication protocol.
   changes.removed = [...prior.keys()].filter((notePathValue) => !present.has(notePathValue)).sort(compare)
 
-  // The cache is replaced only by a preparation that passed every check, and
-  // holds exactly the notes of this view.
+  // A yield lets a source change after it was emitted (or reused). Check the
+  // selected sources against the same pin again, before exposing the result
+  // or replacing the derived cache. This does not create a new snapshot.
+  if (recheckSources) {
+    for (const node of orderedNodes) { yield 'recheck-source'; read(node.repo, node.path) }
+    for (const asset of embeddedAssets.values()) { yield 'recheck-asset'; read(asset.repo, asset.path) }
+  }
+  // The last cancellation boundary precedes the cache commit. There is no
+  // yield between that commit and returning its complete prepared result.
+  yield 'final-cache-commit'
   if (nextCache) cache.notes = nextCache
   if (noteDiagnostics.length > 0) manifest.ext[EXT_KEY].diagnostics = noteDiagnostics
 
@@ -995,3 +1071,9 @@ export function withEligibility(graph, isEligible, isAssetEligible = null) {
       : {}),
   }
 }
+
+function drainPreparation(iterator) { for (;;) { const step = iterator.next(); if (step.done) return step.value } }
+// A wait lets a source change after it was emitted or reused, so the selected sources are read against their pins once
+// more before the result is returned. A caller that checks them itself, as the engine does by stat hint, turns that
+// second reading off with `scheduling.recheckSources: false`.
+export async function prepareViewCooperatively(options = {}) { return runCooperatively(prepareSteps(REDACTION_RULES, options, options.scheduling?.recheckSources !== false), options.scheduling) }

package/src/projection/obsidian/materialize/redaction.mjs

@@ -5,7 +5,7 @@ import { refuse } from './byte-lens.mjs'
 // judges the assembled result, every note included, whether the note was
 // emitted on this call or reused from the preparation cache, and refuses the
 // view with `redaction-failure`, naming the in-view note (or file) and the
-// rule, never the value. See "The redaction guard" in docs/obsidian-contract.md.
+// rule, never the value. See "The redaction guard" in docs/reference/obsidian-contract.md.
 //
 //   allow-list  every path the emitter wrote (note and attachment paths,
 //               rewritten link and embed targets, link targets in generated

package/src/projection/obsidian/personal-workspace.mjs

@@ -5,8 +5,9 @@ import { Worker, isMainThread, parentPort, workerData } from 'node:worker_thread
 import { PersonalWorkspaceRefusal, composePersonalWorkspace } from '@mnstry/atelier/personal-workspace'
 import { ensureLocalState, resolveProjectConfig, validateProjectConfigDoc } from '@mnstry/atelier/project'
 import { buildCanonicalGraph } from '../../graph/graph.mjs'
-import { refuse } from '../../runtime/obsidian/errors.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from '../../runtime/obsidian/errors.mjs'
 import { OBSIDIAN_EXT_KEY } from './contracts.mjs'
+import { readPersonalSelectionSnapshot } from '../../personal-workspace/selection.mjs'
 
 // The one personal-workspace route of the Obsidian projection.
 //
@@ -60,6 +61,9 @@ const BINDING = Symbol('atelier.obsidian.personal-workspace-binding')
 const ROUTES = new WeakMap()
 // The last validity key the composition confirmed for each binding: { inputs, facts }.
 const CONFIRMED = new WeakMap()
+// The selection record a binding was loaded under, when its loader followed the person's confirmed selection instead of
+// naming a generation itself (runtime/obsidian/personal-selection.mjs): { sequence, head, observe, recheck }.
+const SELECTED = new WeakMap()
 export const EVERYTHING_SCOPE_ID = 'everything'
 const EXT_SCHEMA = 'atelier-obsidian-ext-settings/v1'
 // The settings member of a bound project names its generation here. It survives any copy of the project (a structured
@@ -389,6 +393,12 @@ export async function validatePersonalWorkspace(project) {
   if (binding === null) return null
   const route = ROUTES.get(binding)
   if (route === undefined) return { ok: false, code: 'personal-binding-unrecognized' }
+  // A project pinned to a confirmed selection holds only while the history still ends, intact, with that selection's
+  // record: what observation of the record cannot see (a record before it broken, a confirmation that landed before
+  // the engine first looked) is seen here.
+  if (SELECTED.get(binding)?.recheck) {
+    try { assertPersonalSelection(project) } catch (error) { if (!(error instanceof ObsidianMaintenanceRefusal)) throw error; CONFIRMED.delete(binding); return { ok: false, code: error.code } }
+  }
   let composed
   if (route.offThread) composed = await composeInWorker(binding, route.worker)
   else {
@@ -400,12 +410,79 @@ export async function validatePersonalWorkspace(project) {
   return { ok: true, changed: previous?.inputs !== composed.key.inputs || previous?.facts !== composed.key.facts }
 }
 
+const selectionRecord = ({ personalHome }, sequence) => path.join(personalHome, 'selections', `${String(sequence).padStart(6, '0')}.json`)
+
+// The most recently accepted head observed in this process. Durable continuity is checked by the loader's note
+// callback before this index changes. The index only tells an engine when another reader requires it to reload.
+const READ_UP_TO = new Map()
+
+export function notePersonalSelectionHead(personalHome, head, { refusesShortened = true, note = null } = {}) {
+  if (note !== null) note(head)
+  else {
+    const before = READ_UP_TO.get(personalHome)?.sequence ?? 0
+    if (refusesShortened && head.sequence < before) refuse('selection-history-shortened', 'the selection history of the personal workspace ends at an earlier record than this process has read; nothing is used from it', { source: 'personal-workspace' })
+  }
+  if (refusesShortened) READ_UP_TO.set(personalHome, { sequence: head.sequence, head: head.head })
+  return head
+}
+
+// Pins a bound project to the selection record it was loaded under, and answers the project. From then on the engine
+// observes that record and the place of the next one as configuration (personalWorkspaceInputs): a confirmation
+// appended to the history, or a history cut short, is a change. And every time the composition is asked again
+// (validatePersonalWorkspace) the history is read again and must still end with that record. `observe: false`,
+// `recheck: false` and `refusesShortened: false` are test seams only, the mutation controls of each.
+export function pinPersonalSelection(project, { sequence, head }, { observe = true, recheck = true, refusesShortened = true, note = null } = {}) {
+  SELECTED.set(personalWorkspaceBindingOf(project), Object.freeze({ sequence, head, observe, recheck, refusesShortened, note }))
+  return project
+}
+
+// The selection a project is pinned to, as { personalHome, generationId, sequence, head }; null for any other project.
+export function personalSelectionOf(project) {
+  const binding = personalWorkspaceBindingOf(project)
+  const pinned = binding === null ? undefined : SELECTED.get(binding)
+  return pinned === undefined ? null : { personalHome: binding.personalHome, generationId: binding.generationId, sequence: pinned.sequence, head: pinned.head }
+}
+
+// Refuses `personal-selection-changed` unless the history still ends with the record this project is pinned to; a
+// history that cannot be read refuses with the module's own code. What is read is noted first
+// (notePersonalSelectionHead): the same durable continuity rule applies to this read, before its head is compared
+// with the pin. Nothing for a project that is not pinned.
+export function assertPersonalSelection(project) {
+  const pinned = personalSelectionOf(project)
+  if (pinned === null) return
+  let now
+  try { now = readPersonalSelectionSnapshot({ personalHome: pinned.personalHome }) } catch (error) { asMaintenanceRefusal(error, 'the selection history of the personal workspace could not be read; nothing is used from it') }
+  notePersonalSelectionHead(pinned.personalHome, now, SELECTED.get(personalWorkspaceBindingOf(project)))
+  if (now.sequence !== pinned.sequence || now.head !== pinned.head) refuse('personal-selection-changed', 'the confirmed selection of the personal workspace is no longer the one this project was loaded under; nothing is used from it', { source: 'personal-workspace' })
+}
+
+// Whether another reader in this process accepted a head different from the pin: a later confirmation or a newly
+// confirmed shorter history. In memory, with no read. False for a project that is not pinned.
+export function personalSelectionBehind(project) {
+  const pinned = personalSelectionOf(project)
+  const latest = pinned === null ? null : READ_UP_TO.get(pinned.personalHome)
+  return latest !== undefined && latest !== null && (latest.sequence !== pinned.sequence || latest.head !== pinned.head)
+}
+
+// Reads where the history of a pinned project's home ends now, for the note alone: what the read refuses is not this
+// caller's to raise. For the engine's guard, which sees a selection record's file change in the middle of a tick and
+// stops the view as `mixed-read` without reading the history: the record that stopped it is read while it is there, so
+// it counts when it is removed before the next tick. Nothing for a project that is not pinned.
+export function notePersonalSelectionNow(project) {
+  try { assertPersonalSelection(project) } catch (error) { if (!(error instanceof ObsidianMaintenanceRefusal)) throw error }
+}
+
 // The authored and generation files whose change means the binding must be asked again: the manifest, the overlay and
-// the bound generation's record. Observed as configuration by the engine. Empty for any other project.
+// the bound generation's record; and, for a project pinned to a selection, that selection's record and the place of the
+// next one. Observed as configuration by the engine. Empty for any other project.
 export function personalWorkspaceInputs(project) {
   const binding = personalWorkspaceBindingOf(project)
   if (binding === null) return []
-  return [path.join(binding.personalHome, 'atelier.personal.json'), path.join(binding.personalHome, 'atelier.overlay.json'), path.join(generationRoot(binding), 'generation.json')]
+  const pinned = SELECTED.get(binding)
+  return [
+    path.join(binding.personalHome, 'atelier.personal.json'), path.join(binding.personalHome, 'atelier.overlay.json'), path.join(generationRoot(binding), 'generation.json'),
+    ...(pinned?.observe ? [selectionRecord(binding, pinned.sequence), selectionRecord(binding, pinned.sequence + 1)] : []),
+  ]
 }
 
 // The repository of a bound project's private notes, or null. A vault edit to one of them is never applied into a
@@ -415,10 +492,12 @@ export function personalOverlayRepoOf(project) {
 }
 
 // Settings that a personal binding takes from the overlay or does not have yet. A saved view is authored in the
-// overlay, so `view add` would write a module-owned generation file; who may see and where vaults live wait for a
-// stable per-person projection configuration. Refused before anything is resolved or written.
+// overlay, so `view add` would write a module-owned generation file. The machine records an owner-only audience or
+// an explicit clear. Custom audiences refuse; vault location remains unavailable for this binding.
 export function refuseOnPersonalBinding(project, operation) {
   if (personalWorkspaceBindingOf(project) === null) return
+  if (operation === 'audience set me' || operation === 'audience clear') return
+  if (operation.startsWith('audience ')) refuse('personal-binding-owner-only', 'a personal workspace vault is owner only; use `audience set me` or `audience clear`', { operation })
   if (operation === 'view add') refuse('views-from-personal-overlay', 'the views of a personal workspace come from its overlay; nothing was written', { operation })
   refuse('personal-binding-decision-unavailable', `${operation} is not available for a personal workspace yet; nothing was written`, { operation })
 }

package/src/projection/obsidian/plugin-bridge/channel.mjs

@@ -38,7 +38,7 @@ import { createHmac } from 'node:crypto'
 // and the exact bytes of the answer. A handshake is used once and lapses after
 // five seconds, a session after fifteen minutes. Nothing here takes a path to
 // act on, a command or code, and every command maps to state the service
-// already keeps (see docs/obsidian-plugin.md).
+// already keeps (see docs/reference/obsidian-plugin.md).
 //
 // The plugin cannot import this module: it runs inside the app, from the
 // vault. It carries the same constants and the same computations, and the test

package/src/projection/obsidian/proposals/adapter.mjs

@@ -15,6 +15,7 @@ import { isIdentifier } from '../edits/object-identity.mjs'
 import { openObjectStore } from '../edits/object-store.mjs'
 import { decideApply } from '../edits/policy.mjs'
 import { applyEditLens } from '../edits/regions.mjs'
+import { createCooperativeBudget } from '../materialize/prepare-view.mjs'
 import { PERSONAL_VALIDATION_PENDING, personalOverlayRepoOf } from '../personal-workspace.mjs'
 import { PublicationRefusal } from '../recovery/store.mjs'
 import {
@@ -188,6 +189,9 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
     // Set when an observation found the personal workspace's graph pending: the edits it could not look at are offered
     // again on the next observation, not parked until a full reconciliation.
     let observePendingAgain = false
+    // The observation under way, if any. An observation waits between two edits, and what it reads of this adapter
+    // (the flag above, the workspace it opens) is read when it begins: so the next one begins when this one has ended.
+    let observing = Promise.resolve()
 
     // -- the workspace of one call -------------------------------------------
 
@@ -431,10 +435,13 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
 
     // One repository: its lock, then each of its operations in turn. What goes wrong with one repository, or with one
     // operation, is reported by its code and stops nothing else.
-    async function settleRepository(workspace, repoId, works, report) {
+    // `budget`, when a tick hands one over, gives the event loop a turn between two operations: each operation is
+    // settled without interruption, and the lock of the repository is held from the first to the last.
+    async function settleRepository(workspace, repoId, works, report, budget = null) {
       try {
-        const held = await withRepositoryLock(workspace, repoId, () => {
-          for (const work of works) {
+        const held = await withRepositoryLock(workspace, repoId, async () => {
+          for (const [index, work] of works.entries()) {
+            if (budget !== null && index > 0) await budget.checkpoint('settle-operation', true)
             try { report.outcomes.push(settleOne(workspace, work.item, work)) } catch (error) {
               if (error?.crashSeam === true || !isTyped(error)) throw error
               report.outcomes.push({ status: 'failed', code: error.code, editId: work.item.editId, repoId, nodeId: work.item.nodeId, adapterOperationId: work.item.adapterOperationId, state: null, proposalId: null })
@@ -448,6 +455,26 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       }
     }
 
+    // One observation, from opening the workspace to the flag it leaves for the next.
+    async function observeNow(context, { retryRefused = false } = {}) {
+      const workspace = open(context)
+      const edits = Array.isArray(context.edits) ? context.edits : []
+      // A private note of a personal workspace lives in a generation the personal-workspace module owns: its edit is
+      // not observed, recorded or proposed, and stays held in the vault. Answered by name, with nothing written.
+      const overlayRepoId = personalOverlayRepoOf(workspace.project)
+      const isPrivate = (edit) => overlayRepoId !== null && edit?.identity?.repoId === overlayRepoId
+      const privateNotes = edits.filter((edit) => isPrivate(edit) && edit.closedAt === null)
+        .map((edit) => ({ editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, status: 'refused', code: 'personal-overlay-not-proposed' }))
+      const shared = edits.filter((edit) => !isPrivate(edit))
+      // The graph is built only when an edit is looked at, as for any project. When the personal workspace's graph is
+      // pending, the edits it reached are not reported or recorded, and are offered again on the next observation.
+      const retry = retryRefused || observePendingAgain
+      const looked = await observation.run.cooperatively(workspace, { edits: shared, retryRefused: retry })
+      const pending = looked.filter((item) => item.code === PERSONAL_VALIDATION_PENDING)
+      observePendingAgain = pending.length > 0
+      return { adapterId: PROPOSAL_ADAPTER_ID, observed: [...privateNotes, ...looked.filter((item) => item.code !== PERSONAL_VALIDATION_PENDING)], ...(pending.length > 0 ? { deferred: PERSONAL_VALIDATION_PENDING } : {}) }
+    }
+
     return {
       id: PROPOSAL_ADAPTER_ID,
 
@@ -455,23 +482,10 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       // observed from its preserved bytes against the source as it is now and recorded as what it is, a bounded number
       // per tick and never twice. `retryRefused` offers once more the edits whose observation refused before anything
       // could be recorded. Writes no source and no vault. Returns codes and identifiers only.
-      async observe(context, { retryRefused = false } = {}) {
-        const workspace = open(context)
-        const edits = Array.isArray(context.edits) ? context.edits : []
-        // A private note of a personal workspace lives in a generation the personal-workspace module owns: its edit is
-        // not observed, recorded or proposed, and stays held in the vault. Answered by name, with nothing written.
-        const overlayRepoId = personalOverlayRepoOf(workspace.project)
-        const isPrivate = (edit) => overlayRepoId !== null && edit?.identity?.repoId === overlayRepoId
-        const privateNotes = edits.filter((edit) => isPrivate(edit) && edit.closedAt === null)
-          .map((edit) => ({ editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, status: 'refused', code: 'personal-overlay-not-proposed' }))
-        const shared = edits.filter((edit) => !isPrivate(edit))
-        // The graph is built only when an edit is looked at, as for any project. When the personal workspace's graph is
-        // pending, the edits it reached are not reported or recorded, and are offered again on the next observation.
-        const retry = retryRefused || observePendingAgain
-        const looked = observation.run(workspace, { edits: shared, retryRefused: retry })
-        const pending = looked.filter((item) => item.code === PERSONAL_VALIDATION_PENDING)
-        observePendingAgain = pending.length > 0
-        return { adapterId: PROPOSAL_ADAPTER_ID, observed: [...privateNotes, ...looked.filter((item) => item.code !== PERSONAL_VALIDATION_PENDING)], ...(pending.length > 0 ? { deferred: PERSONAL_VALIDATION_PENDING } : {}) }
+      observe(context, options = {}) {
+        const run = observing.then(() => observeNow(context, options))
+        observing = run.catch(() => {})
+        return run
       },
 
       // The tick. `context` is { project, workspaceRoot, workspaceId, repositoryRoots, edits }: the pending edit
@@ -481,6 +495,9 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         const nowMs = Date.parse(isoTime(clock))
         const report = { adapterId: PROPOSAL_ADAPTER_ID, examined: 0, outcomes: [], repositories: [] }
         const edits = Array.isArray(context.edits) ? context.edits : []
+        // The tick goes on answering while it routes: a turn of the event loop when describing has taken its share
+        // of time, and one before each repository and between two of its operations.
+        const budget = createCooperativeBudget()
         const { operations: heads, unreadable } = workspace.queue().heads()
         for (const item of unreadable) report.repositories.push({ repoId: null, code: item.code })
         const byEdit = new Map(edits.map((edit) => [edit.editId, edit]))
@@ -497,7 +514,8 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
           const editState = edit === null || edit.closedAt === null ? 'open' : ['withdrawn', 'superseded'].includes(edit.state) ? edit.state : 'closed'
           let item = itemOfHead(head, edit)
           if (edit !== null && head.state !== 'submitted') {
-            try { item = { ...item, ...(describe(workspace, edit) ?? {}) } } catch (error) { if (!isTyped(error)) throw error; report.outcomes.push({ status: 'failed', code: error.code, editId: head.editId, repoId: head.repoId, nodeId: head.nodeId, adapterOperationId: head.adapterOperationId, state: head.state, proposalId: null }); continue }
+            try { item = { ...item, ...(describe(workspace, edit) ?? {}) } } catch (error) { if (!isTyped(error)) throw error; report.outcomes.push({ status: 'failed', code: error.code, editId: head.editId, repoId: head.repoId, nodeId: head.nodeId, adapterOperationId: head.adapterOperationId, state: head.state, proposalId: null }); await budget.checkpoint('describe-operation'); continue }
+            await budget.checkpoint('describe-operation')
           }
           add(head.repoId, { item, editState })
         }
@@ -510,11 +528,16 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         for (const edit of looked) {
           report.examined += 1
           let item
-          try { item = describe(workspace, edit) } catch (error) { if (!isTyped(error)) throw error; report.outcomes.push({ status: 'failed', code: error.code, editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, adapterOperationId: null, state: null, proposalId: null }); continue }
+          try { item = describe(workspace, edit) } catch (error) { if (!isTyped(error)) throw error; report.outcomes.push({ status: 'failed', code: error.code, editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, adapterOperationId: null, state: null, proposalId: null }); await budget.checkpoint('describe-edit'); continue }
           if (item !== null) add(item.repoId, { item, editState: 'open' })
+          await budget.checkpoint('describe-edit')
         }
 
-        for (const [repoId, list] of [...works].sort(([left], [right]) => compareText(left, right))) await settleRepository(workspace, repoId, list, report)
+        for (const [repoId, list] of [...works].sort(([left], [right]) => compareText(left, right))) {
+          await budget.checkpoint('settle-repository', true)
+          await settleRepository(workspace, repoId, list, report, budget)
+        }
+        budget.finish('propose-finalize')
         return report
       },
 

package/src/projection/obsidian/proposals/observation.mjs

@@ -10,6 +10,7 @@ import { SOURCE_APPLY_PRIMITIVES, SourceApplyRefusal, locateSource } from '../ed
 import { EditArbitrationRefusal } from '../edits/arbitrate.mjs'
 import { createEditObserverForOracleTests, editIdempotencyKey, observeEdit } from '../edits/observe.mjs'
 import { decideApply } from '../edits/policy.mjs'
+import { createCooperativeBudget } from '../materialize/prepare-view.mjs'
 import { PublicationRefusal, readFileBytes, sha256Digest } from '../recovery/store.mjs'
 import { PROPOSAL_BACKPRESSURE } from './backpressure.mjs'
 
@@ -38,6 +39,14 @@ import { PROPOSAL_BACKPRESSURE } from './backpressure.mjs'
 // reconciliation cadence, never on every tick. A bounded number of edits is
 // looked at per tick, in the order they were observed, starting where the last
 // tick stopped.
+//
+// One edit is one unit: it is read, judged and recorded without interruption.
+// Between two edits the cooperative form (`cooperatively`, which the adapter
+// uses on a tick) gives the event loop a turn, so the process that runs the
+// tick goes on answering while a burst of edits is observed. A second
+// cooperative observation waits for the first to finish; what is looked at,
+// and in what order, is the same in both forms. The uninterrupted form
+// cannot wait, so it refuses to run beside a cooperative one.
 
 const EXT = OBSIDIAN_EXT_KEY
 const GONE = new Set(['ENOENT', 'ENOTDIR', 'ELOOP'])
@@ -203,7 +212,8 @@ export function createTickObservation(options = {}) {
   // `workspace` is the opened workspace of the adapter; `edits` the pending edit records, open and closed;
   // `retryRefused` offers the edits whose observation refused earlier once more. Returns one entry per edit looked
   // at: { editId, repoId, nodeId, status: 'observed' | 'refused', code, kind?, operationState?, idempotencyKey? }.
-  return function observePendingEdits(workspace, { edits, retryRefused = false }) {
+  // Yields between two edits, never within one, and returns the entries when it is done.
+  function* observeSteps(workspace, { edits, retryRefused = false }) {
     if (retryRefused) unobservable.clear()
     const now = isoTime(workspace.clock)
     const candidates = edits.filter((edit) => edit.closedAt === null && OPEN_EDIT_STATES.includes(edit.state) && !recorded.has(edit.editId) && !unobservable.has(edit.editId))
@@ -212,7 +222,8 @@ export function createTickObservation(options = {}) {
     const looked = [...candidates.slice(start), ...candidates.slice(0, start)].slice(0, bounds.maxObservedPerTick)
     cursor = candidates.length > bounds.maxObservedPerTick ? start + looked.length : 0
     const observed = []
-    for (const edit of looked) {
+    for (const [index, edit] of looked.entries()) {
+      if (index > 0) yield 'observe-edit'
       const entry = { editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId }
       try {
         const outcome = observeOne(workspace, edit, now)
@@ -226,4 +237,31 @@ export function createTickObservation(options = {}) {
     }
     return observed
   }
+
+  // Cooperative observations asked for and not yet finished, and the last of them.
+  let underWay = 0
+  let last = Promise.resolve()
+  function observePendingEdits(workspace, input) {
+    if (underWay > 0) throw Object.assign(new Error('a cooperative observation of this instance is under way; the uninterrupted form cannot run beside it'), { code: 'observation-under-way' })
+    const steps = observeSteps(workspace, input)
+    for (;;) { const step = steps.next(); if (step.done) return step.value }
+  }
+  // The same observation with a turn of the event loop between two edits. One at a time: an observation asked for
+  // while another is under way starts when that one has finished, so no edit is looked at by both. One that failed
+  // holds back none that follow.
+  observePendingEdits.cooperatively = (workspace, input) => {
+    underWay += 1
+    const run = last.then(async () => {
+      const budget = createCooperativeBudget()
+      const steps = observeSteps(workspace, input)
+      for (;;) {
+        const step = steps.next()
+        if (step.done) { budget.finish('observe-finalize'); return step.value }
+        await budget.checkpoint(step.value, true)
+      }
+    }).finally(() => { underWay -= 1 })
+    last = run.catch(() => {})
+    return run
+  }
+  return observePendingEdits
 }