@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/runtime/obsidian/opening.mjs

@@ -0,0 +1,243 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRecoveryStore as createStore, readFileBytes, sha256Digest } from '../../projection/obsidian/recovery/store.mjs'
+import { inspectApp, qualifyApp } from './app-capability.mjs'
+import { readObsidianEnablement } from './enablement.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
+import { UNAVAILABLE_APPLY_OPERATION } from './extension-points.mjs'
+import { LIFECYCLE_PRIMITIVES, requestServiceTick, serviceStatus, startService } from './lifecycle.mjs'
+import { protectedRoots } from './machine-settings.mjs'
+import { trustedNoteBases } from './pending-edits.mjs'
+import { resolveServiceWorkspace } from './service.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from './state-store.mjs'
+
+// Opening a view, and saying honestly how fresh it is.
+//
+// Every answer is one of the typed outcomes below. Only `current` is success,
+// and it means all of:
+//
+//   - the owned maintenance service is healthy and ran a tick after this
+//     request, so the generation it prepared comes from the present sources;
+//   - the persisted freshness of the view says `current`, which the state
+//     store only accepts for a verified generation equal to the prepared one;
+//   - read back here, independently: the trusted pointer of the view names
+//     that same generation and every note in the vault has the bytes that
+//     generation was published with;
+//   - the installed app is present, has its command-line capability, meets
+//     the minimum version, was asked to open the vault, answers for exactly
+//     this vault and has finished reading it.
+//
+// Nothing here talks to an app or an operating system itself: `appProbe` and
+// `launcher` are injected, and there is no default for either.
+
+export const OPENING_OUTCOMES = Object.freeze({
+  current: { summary: 'the vault is the present generation, verified by read-back, and the app has it open', next: 'nothing to do' },
+  updating: { summary: 'maintenance is publishing or has not finished; the vault is not confirmed current', next: 'run `obsidian open` again in a moment' },
+  'held-for-your-edit': { summary: 'a note you edited is preserved and held; the view is not republished over it', next: 'apply or withdraw the pending edit, then open again' },
+  'stale-readable': { summary: 'a last good vault exists and can be read, but it is not proven to be the present generation', next: 'see `obsidian status` for the reason; `obsidian open --allow-stale` opens it as it is' },
+  'not-prepared': { summary: 'no generation of this view has been published yet', next: 'see `obsidian status` for the reason' },
+  'app-missing': { summary: 'no Obsidian installation was found', next: 'install Obsidian, then open again' },
+  'app-version-unsupported': { summary: 'the installed Obsidian is below the minimum supported version, or its version cannot be read', next: 'update Obsidian, then open again' },
+  'app-cli-unavailable': { summary: 'the installed Obsidian has no usable command-line capability', next: 'enable the command-line interface in Obsidian, then open again' },
+  indexing: { summary: 'the app answered for this vault but has not finished reading it', next: 'wait for Obsidian to finish indexing, then open again' },
+  'publisher-conflict': { summary: 'another publisher or an uncoordinated editor holds this vault', next: 'close the other publisher or let it finish; it is retried automatically' },
+  'launch-failed': { summary: 'the operating system or the app did not open this vault', next: 'open the vault folder in Obsidian once by hand, then open again' },
+  'service-unavailable': { summary: 'the maintenance service of this workspace could not be started or reached as ours', next: 'see `obsidian service status`' },
+  busy: { summary: 'the maintenance service runs but is in a long tick and did not answer in time', next: 'run `obsidian open` again in a moment; nothing was stopped or restarted' },
+  disabled: { summary: 'the Obsidian integration is not enabled for this project, or this view is not configured', next: 'enable it in the project configuration' },
+})
+
+// A sub-state of pending edits, never an opening failure.
+export const APPLY_UNAVAILABLE = 'apply-unavailable'
+
+export function describeOutcome(code) {
+  if (!Object.hasOwn(OPENING_OUTCOMES, code)) throw new TypeError(`unknown opening outcome: ${String(code)}`)
+  return { outcome: code, ...OPENING_OUTCOMES[code] }
+}
+
+// The decisions the opening oracles are sensitive to; tests substitute broken ones to prove the oracles can fail.
+export const OPENING_PRIMITIVES = Object.freeze({
+  // The freshness states that are their own outcome.
+  outcomeOfState: (state) => (['updating', 'held-for-your-edit', 'publisher-conflict', 'disabled'].includes(state) ? state : null),
+  // Whether a persisted `current` may be believed after reading the vault back.
+  readBackAgrees: ({ entry, verification }) => verification.readable && verification.generationId === entry.preparedGenerationId && verification.intact,
+  // Whether the app may be shown this vault at all.
+  appQualifies: (qualification) => qualification.outcome === 'qualified',
+})
+
+const segment = (identifier) => identifier.replaceAll(':', '_')
+const STORE_AREAS = (scopeId) => [['vaults', segment(scopeId)], ['state', 'manifests', segment(scopeId)], ['state', 'journals', segment(scopeId)], ['state', 'locks'], ['recovery', 'objects'], ['staging']]
+
+// Reads the trusted pointer of a view and every note of its vault. Read-only:
+// the store is only constructed when everything it would create already exists.
+export function readBackTrustedGeneration({ workspaceRoot, workspaceId, scopeId, repositoryRoots, createRecoveryStore = createStore }) {
+  const unreadable = (reason) => ({ readable: false, reason, generationId: null, intact: false, noteCount: 0, differing: 0, missing: 0 })
+  if (!STORE_AREAS(scopeId).every((parts) => fs.existsSync(path.join(workspaceRoot, ...parts)))) return unreadable('no-published-vault')
+  let store
+  let trusted
+  try {
+    store = createRecoveryStore({ workspaceRoot, workspaceId, scopeId, repositoryRoots })
+    trusted = { pointer: store.readCurrent(), ...trustedNoteBases(store) }
+  } catch (error) {
+    if (typeof error?.code === 'string') return unreadable(error.code)
+    throw error
+  }
+  if (!trusted.pointer || !trusted.manifest) return unreadable('no-trusted-generation')
+  let differing = 0
+  let missing = 0
+  for (const [notePath, base] of trusted.bases) {
+    let bytes
+    try { bytes = readFileBytes(path.join(store.vaultRoot, ...notePath.split('/'))) } catch (error) {
+      if (error.code === 'ENOENT') { missing += 1; continue }
+      return unreadable(error.code ?? 'vault-unreadable')
+    }
+    if (sha256Digest(bytes) !== base.digest) differing += 1
+  }
+  return { readable: true, reason: 'read-back', generationId: trusted.pointer.generationId, intact: differing === 0 && missing === 0, noteCount: trusted.bases.size, differing, missing, vaultRoot: store.vaultRoot }
+}
+
+function pendingSummary(stateStore, scopeId, applyAvailable) {
+  const open = stateStore.readPendingEdits().edits.filter((edit) => edit.scopeId === scopeId && OPEN_EDIT_STATES.includes(edit.state))
+  const byState = Object.fromEntries(OPEN_EDIT_STATES.map((state) => [state, open.filter((edit) => edit.state === state).length]))
+  // Said whenever no apply operation exists, not only after a dispatch found that out.
+  return { open: open.length, byState, apply: applyAvailable ? 'available' : APPLY_UNAVAILABLE }
+}
+
+// The honest freshness of one view, from persisted state plus a read-back.
+// `serviceState` is the proven lifecycle state; a persisted `current` is not
+// repeated as `current` while nothing proves maintenance is looking.
+export function scopeReport({ workspace, scopeId, repositoryRoots, serviceState, applyAvailable = false, freshness = undefined, createRecoveryStore }, rules = OPENING_PRIMITIVES) {
+  const stateStore = createMaintenanceStateStore(workspace)
+  let document = freshness
+  let unreadableCode = null
+  if (document === undefined) {
+    try { document = stateStore.readFreshness() } catch (error) { if (!(error instanceof ObsidianMaintenanceRefusal)) throw error; document = null; unreadableCode = error.code }
+  }
+  const entry = document?.scopes.find((item) => item.scopeId === scopeId) ?? null
+  const verification = readBackTrustedGeneration({ ...workspace, scopeId, repositoryRoots, ...(createRecoveryStore ? { createRecoveryStore } : {}) })
+  const lastGood = verification.readable ? 'stale-readable' : 'not-prepared'
+  let outcome
+  let reason
+  if (entry === null) { outcome = lastGood; reason = unreadableCode ?? 'no-freshness-recorded' }
+  else if (rules.outcomeOfState(entry.state) !== null) { outcome = rules.outcomeOfState(entry.state); reason = entry.reason }
+  else if (entry.state !== 'current') { outcome = lastGood; reason = entry.reason }
+  else if (!rules.readBackAgrees({ entry, verification })) {
+    // Notes that differ are an edit the engine has not looked at yet; a pointer that differs is another generation.
+    const edited = verification.readable && verification.generationId === entry.preparedGenerationId
+    outcome = edited ? 'updating' : lastGood
+    reason = edited ? 'vault-differs-from-trusted-generation' : verification.readable ? 'trusted-generation-differs' : verification.reason
+  } else if (serviceState !== 'healthy') { outcome = 'stale-readable'; reason = serviceState === 'busy' ? 'maintenance-busy-not-rechecked' : 'maintenance-not-running' }
+  else { outcome = 'current'; reason = entry.reason }
+  return {
+    scopeId, ...describeOutcome(outcome), reason,
+    freshness: entry === null ? null : { state: entry.state, reason: entry.reason, verified: entry.verified, generationId: entry.generationId, preparedGenerationId: entry.preparedGenerationId, heldNoteCount: entry.heldNotes.length, retainedEdits: entry.retainedEdits, checkedAt: entry.checkedAt },
+    readBack: { readable: verification.readable, reason: verification.reason, generationId: verification.generationId, intact: verification.intact, noteCount: verification.noteCount, differing: verification.differing, missing: verification.missing },
+    pendingEdits: pendingSummary(stateStore, scopeId, applyAvailable),
+    vaultRoot: verification.vaultRoot ?? null,
+  }
+}
+
+export function resolveScope(enablement, requested) {
+  const scopeId = requested ?? enablement.defaultScopeId ?? enablement.scopes[0]?.scopeId ?? null
+  if (scopeId === null) refuse('unknown-scope', 'this project declares no view to open')
+  if (!enablement.scopes.some((scope) => scope.scopeId === scopeId)) refuse('unknown-scope', 'no declared view has this identity', { scopeId: String(scopeId).slice(0, 128) })
+  return scopeId
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms) })
+const READABLE = new Set(['stale-readable', 'held-for-your-edit', 'updating', 'publisher-conflict'])
+
+// Starts or reconnects the owned service, asks it for a tick, reads the view
+// back, qualifies the app, has the vault opened and reports one outcome.
+export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIMITIVES, lifecycleRules = LIFECYCLE_PRIMITIVES) {
+  const {
+    loadProject, dataRoot, scopeId: requestedScope, appProbe, launcher, service = {}, consent, allowStale = false, extensions = null,
+    tickTimeoutMs = 120 * 1000, appWaitMs = 30 * 1000, appPollMs = 500, sleep = defaultSleep, monotonic = () => Date.now(),
+    env = process.env, platform = process.platform, probeTimeoutMs,
+  } = options
+  if (typeof loadProject !== 'function') throw new TypeError('open needs loadProject')
+  // No defaults: reaching an app or the operating system is a decision of the entry that composes this.
+  if (typeof appProbe?.inspect !== 'function' || typeof appProbe?.vaultState !== 'function') throw new TypeError('open needs an injected appProbe')
+  if (typeof launcher?.open !== 'function') throw new TypeError('open needs an injected launcher')
+  if (typeof service.entryPath !== 'string') throw new TypeError('open needs the service entry it may start')
+
+  const project = loadProject()
+  const enablement = readObsidianEnablement(project)
+  const applyAvailable = extensions !== null && extensions.applyOperation() !== UNAVAILABLE_APPLY_OPERATION
+  const finish = (outcome, extra = {}) => ({ ok: outcome === 'current', ...describeOutcome(outcome), launched: false, ...extra })
+  if (enablement.state === 'disabled') return finish('disabled', { reason: enablement.reason, scopeId: requestedScope ?? null })
+  const scopeId = resolveScope(enablement, requestedScope)
+  const lifecycle = { loadProject, dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
+
+  // 1. The owned service: reconnect, or start. Never adopt, never replace.
+  let status = await serviceStatus(lifecycle, lifecycleRules)
+  if (status.state === 'busy') return finish('busy', { scopeId, reason: status.reason, service: { state: status.state } })
+  if (status.state !== 'healthy') {
+    let started
+    try {
+      started = await startService({ ...lifecycle, detached: true, ...service, ...(consent === undefined ? {} : { consent }) }, lifecycleRules)
+    } catch (error) {
+      if (!(error instanceof ObsidianMaintenanceRefusal)) throw error
+      return finish('service-unavailable', { scopeId, reason: error.code, service: { state: status.state } })
+    }
+    if (started.state === 'busy') return finish('busy', { scopeId, reason: started.reason, service: { state: 'busy', started: started.started } })
+    if (started.state !== 'healthy') return finish('service-unavailable', { scopeId, reason: started.reason ?? started.state, service: { state: started.state } })
+    status = started
+  }
+
+  // 2. A tick that starts after this request, bounded.
+  const asked = await requestServiceTick({ ...lifecycle, tickTimeoutMs }, lifecycleRules)
+  const serviceShown = { state: asked.state, runtimeId: status.record?.runtimeId ?? null }
+  if (asked.state === 'busy') return finish('busy', { scopeId, reason: asked.reason, service: serviceShown })
+  if (!asked.requested) return finish('service-unavailable', { scopeId, reason: asked.reason, service: serviceShown })
+  const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform })
+  const report = (freshnessOverride) => scopeReport({ workspace, scopeId, repositoryRoots: protectedRoots(project), serviceState: 'healthy', applyAvailable, ...(freshnessOverride === undefined ? {} : { freshness: freshnessOverride }) }, rules)
+  let view = report()
+  const tick = asked.pending ? null : asked.tick
+  if (asked.pending && view.outcome === 'current') view = { ...view, ...describeOutcome('updating'), reason: 'tick-still-running' }
+  else if (!asked.pending && tick?.state === 'busy') return finish('busy', { scopeId, reason: 'engine-lock-held', service: serviceShown })
+  else if (!asked.pending && (tick === null || tick.ok !== true || tick.state !== 'ticked') && view.outcome === 'current') {
+    // The tick after this request did not complete: what was current before is not proven current now.
+    view = { ...view, ...describeOutcome('stale-readable'), reason: `tick-${tick?.state ?? tick?.error?.code ?? 'unanswered'}` }
+  }
+  const common = { scopeId, reason: view.reason, service: serviceShown, freshness: view.freshness, readBack: view.readBack, pendingEdits: view.pendingEdits }
+  if (view.outcome !== 'current' && !(allowStale && READABLE.has(view.outcome) && view.readBack.readable)) return finish(view.outcome, common)
+
+  // 3. The app, before anything is launched.
+  const before = qualifyApp(await inspectApp(appProbe), { requireVersion: false })
+  const app = (qualification) => ({ outcome: qualification.outcome, reason: qualification.reason, version: qualification.version, floor: qualification.floor })
+  if (!rules.appQualifies(before)) return finish(before.outcome, { ...common, reason: before.reason, app: app(before) })
+
+  // 4. Launch, then wait, bounded, for the app to answer for exactly this vault.
+  let launch
+  try { launch = await launcher.open({ vaultRoot: view.vaultRoot }) } catch { launch = { launched: false, reason: 'launcher-threw' } }
+  if (launch?.launched !== true) return finish('launch-failed', { ...common, reason: typeof launch?.reason === 'string' ? launch.reason : 'launcher-refused', app: app(before) })
+  const deadline = monotonic() + appWaitMs
+  let after = before
+  let vault = { answered: false, indexReady: false }
+  for (;;) {
+    after = qualifyApp(await inspectApp(appProbe), { requireVersion: true })
+    // A running app below the floor is final; an app that has not come up yet is asked again.
+    if (!rules.appQualifies(after) && after.reason !== 'version-unknown') return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after) })
+    if (rules.appQualifies(after)) {
+      try { vault = await appProbe.vaultState({ vaultRoot: view.vaultRoot }) } catch { vault = { answered: false, indexReady: false } }
+      if (vault?.answered === true && vault.indexReady === true) break
+    }
+    if (monotonic() >= deadline) break
+    await sleep(appPollMs)
+  }
+  if (!rules.appQualifies(after)) return finish(after.outcome, { ...common, launched: true, reason: after.reason, app: app(after) })
+  if (vault?.answered !== true) return finish('launch-failed', { ...common, launched: true, reason: 'app-did-not-answer-for-this-vault', app: app(after) })
+  if (vault.indexReady !== true) return finish('indexing', { ...common, launched: true, reason: 'metadata-cache-not-ready', app: app(after) })
+
+  // 5. Still what was verified? The launch took time.
+  if (view.outcome !== 'current') return finish(view.outcome, { ...common, launched: true, app: app(after) })
+  const again = report()
+  if (again.outcome !== 'current') return finish(again.outcome, { ...common, launched: true, reason: again.reason, freshness: again.freshness, readBack: again.readBack, app: app(after) })
+  return finish('current', { ...common, launched: true, app: app(after) })
+}
+
+// Production entry point: the production decisions, always.
+export function openScope(options = {}) {
+  return openScopeForOracleTests(options, OPENING_PRIMITIVES, LIFECYCLE_PRIMITIVES)
+}

package/src/runtime/obsidian/pending-edits.mjs

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { publishedSinceCommit } from '../../projection/obsidian/recovery/restart.mjs'
+import { readFileBytes, sha256Digest } from '../../projection/obsidian/recovery/store.mjs'
+import { compareText } from './documents.mjs'
+import { normalizeApplyResult } from './extension-points.mjs'
+import { OPEN_EDIT_STATES } from './state-store.mjs'
+
+// Edits a person (or another program) made in a vault.
+//
+// A note whose bytes differ from the digest its view was generated with has
+// been edited. The order is fixed: the edited bytes are copied into the
+// recovery object store first, and only then is a record queued. The engine
+// never writes such a note. Whether an edit reaches a source file is a
+// separate, explicit operation: never on a tick in manual mode, and in
+// automatic mode only through the registered apply operation under an
+// installed policy that is read again immediately before every dispatch.
+
+const DISPATCHABLE = new Set(['queued', 'apply-unavailable', 'apply-failed'])
+export const isOpenEdit = (edit) => OPEN_EDIT_STATES.includes(edit.state)
+
+export function editIdentifier({ workspaceId, repoId, nodeId, scopeId, generationId, observedDigest }) {
+  return `edit-${createHash('sha256').update([workspaceId, repoId, nodeId, scopeId, generationId, observedDigest].join('\u0000')).digest('hex').slice(0, 32)}`
+}
+
+// The digest each note of a view is bound to, exactly as the publisher binds
+// it: the trusted manifest, then whatever an unfinished publication of this
+// view has verifiably published since. Without the second part a note written
+// by an interrupted run would look like somebody's edit.
+export function trustedNoteBases(store) {
+  const manifest = store.readCurrentManifest()
+  const bases = new Map()
+  if (!manifest) return { manifest: null, bases }
+  const published = publishedSinceCommit({ store })
+  for (const note of manifest.notes) {
+    const digest = published.has(note.path) ? published.get(note.path) : note.noteDigest
+    if (digest !== null) bases.set(note.path, { digest, repoId: note.repoId, nodeId: note.nodeId })
+  }
+  return { manifest, bases }
+}
+
+// Production preservation: an immutable, content-addressed copy in the
+// recovery object store, through the store's own primitive.
+export const preserveInRecoveryStore = (store, bytes) => store.retainObject(bytes)
+
+// Compares each note with its base and returns the next list of edit records.
+// `digestOf(path)` is the digest observation found; the bytes are read again
+// here and hashed, and that second reading is what gets preserved and recorded.
+export function observeVaultEdits({ store, workspaceId, scopeId, manifest, bases, digestOf, edits, now, preserve = preserveInRecoveryStore }) {
+  const next = edits.map((edit) => ({ ...edit }))
+  const events = []
+  const openFor = (notePath) => next.filter((edit) => edit.scopeId === scopeId && edit.path === notePath && isOpenEdit(edit))
+  const close = (edit, state) => { edit.state = state; edit.closedAt = now }
+
+  for (const [notePath, base] of bases) {
+    const observed = digestOf(notePath)
+    // A missing note holds no bytes to keep; the publisher restores it.
+    if (observed === null || observed === undefined) continue
+    if (observed === base.digest) {
+      for (const edit of openFor(notePath)) { close(edit, 'withdrawn'); events.push({ kind: 'withdrawn', scopeId, path: notePath, editId: edit.editId }) }
+      continue
+    }
+    if (openFor(notePath).some((edit) => edit.observedDigest === observed)) continue
+    let bytes
+    try { bytes = readFileBytes(path.join(store.vaultRoot, ...notePath.split('/'))) } catch (error) {
+      if (error.code === 'ENOENT') continue
+      throw error
+    }
+    const observedDigest = sha256Digest(bytes)
+    if (observedDigest === base.digest) continue
+    // Preserved first. If this throws, nothing has been recorded.
+    const object = preserve(store, bytes)
+    if (openFor(notePath).some((edit) => edit.observedDigest === observedDigest)) continue
+    for (const edit of openFor(notePath)) { close(edit, 'superseded'); events.push({ kind: 'superseded', scopeId, path: notePath, editId: edit.editId }) }
+    const identity = { workspaceId, repoId: base.repoId, nodeId: base.nodeId }
+    const editId = editIdentifier({ ...identity, scopeId, generationId: manifest.generationId, observedDigest })
+    // The same bytes over the same generation, seen again after being closed: reopened, not duplicated.
+    const index = next.findIndex((edit) => edit.editId === editId)
+    const record = {
+      editId, identity, scopeId, generationId: manifest.generationId, path: notePath, baseNoteDigest: base.digest, observedDigest, objectRef: object.ref,
+      observedAt: now, state: 'queued', attempts: 0, retryBudget: null, lastAttemptAt: null, lastResult: null, closedAt: null,
+    }
+    if (index === -1) next.push(record); else next[index] = record
+    events.push({ kind: 'queued', scopeId, path: notePath, editId })
+  }
+  // A note that left the view is no longer compared; its record stays open and its bytes stay kept.
+  return { edits: next, events }
+}
+
+export function heldPaths(edits, scopeId) {
+  return [...new Set(edits.filter((edit) => edit.scopeId === scopeId && isOpenEdit(edit)).map((edit) => edit.path))].sort(compareText)
+}
+
+// Automatic dispatch. `authorize()` reads the machine settings and the policy
+// from disk. It is called before the batch and again immediately before each
+// edit, so a revocation, a pause or a switch back to manual stops the very
+// next dispatch. Attempts are bounded by the policy's retry budget and spaced
+// by `retryIntervalMs`; an exhausted edit stays pending and is not dispatched
+// again until the operation or the policy changes.
+export async function dispatchAutomaticApply({ edits, authorize, applyOperation, now, nowMs, retryIntervalMs }) {
+  const next = edits.map((edit) => ({ ...edit }))
+  const dispatched = []
+  const first = authorize()
+  if (!first.authorized) return { edits: next, dispatched, authorization: first.reason }
+  let authorization = first.reason
+  let remaining = first.policy.maxBatchSize
+  const ordered = next.filter((edit) => isOpenEdit(edit)).sort((left, right) => compareText(left.observedAt, right.observedAt) || compareText(left.editId, right.editId))
+  for (const edit of ordered) {
+    if (remaining <= 0) break
+    const current = authorize()
+    if (!current.authorized) { authorization = current.reason; break }
+    const { policy } = current
+    if (!policy.allowedEditClasses.includes('body-replacement')) { authorization = 'edit-class-not-allowed'; break }
+    // A new operation or a new policy revision is a new situation: the budget starts again.
+    if (edit.lastResult && (edit.lastResult.operationId !== applyOperation.id || edit.lastResult.policyDigest !== policy.digest)) {
+      edit.attempts = 0
+      if (edit.state === 'retry-exhausted') edit.state = 'queued'
+    }
+    edit.retryBudget = policy.retryBudget
+    if (edit.attempts >= policy.retryBudget + 1) { edit.state = 'retry-exhausted'; continue }
+    if (!DISPATCHABLE.has(edit.state)) continue
+    if (edit.lastAttemptAt !== null && nowMs - Date.parse(edit.lastAttemptAt) < retryIntervalMs) continue
+    remaining -= 1
+    let result
+    try {
+      result = normalizeApplyResult(await applyOperation.apply({
+        edit: structuredClone(edit), policy: structuredClone(policy), policyDigest: policy.digest, idempotencyKey: edit.editId,
+      }))
+    } catch {
+      result = { status: 'failed', code: 'apply-operation-threw' }
+    }
+    edit.attempts += 1
+    edit.lastAttemptAt = now
+    edit.lastResult = { ...result, operationId: applyOperation.id, policyDigest: policy.digest }
+    if (result.status === 'applied') { edit.state = 'applied'; edit.closedAt = now }
+    else if (edit.attempts >= policy.retryBudget + 1) edit.state = 'retry-exhausted'
+    else edit.state = result.status === 'apply-unavailable' ? 'apply-unavailable' : 'apply-failed'
+    dispatched.push({ editId: edit.editId, status: result.status, code: result.code, state: edit.state })
+  }
+  return { edits: next, dispatched, authorization }
+}

package/src/runtime/obsidian/pipeline.mjs

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { buildCanonicalGraph, createGraphFileCache } from '../../graph/graph.mjs'
+import { EMITTER_VERSION, createPreparationCache, prepareView, withEligibility } from '../../projection/obsidian/materialize/index.mjs'
+import { publishView } from '../../projection/obsidian/publication/publisher.mjs'
+import { recheckDisplacedFiles } from '../../projection/obsidian/recovery/late-writer.mjs'
+import { createRecoveryStore, readFileBytes } from '../../projection/obsidian/recovery/store.mjs'
+import { compareText } from './documents.mjs'
+import { refuse } from './errors.mjs'
+import { readFileFacts, sha256Digest, sourceKey } from './observation.mjs'
+
+// The production seams between the engine and the projection modules:
+//
+//   canonical graph -> source snapshot -> prepareView -> publishView
+//
+// The engine receives these as one object and tests replace single members.
+// Nothing here talks to a network, and nothing here asks git anything; the
+// canonical graph builder reads local ignore rules through the local git
+// executable and that is all.
+
+// Fails closed twice. A document is eligible only when the census classified
+// it: an unclassified one, or one that carries no classification at all, is
+// withheld. An embedded asset has no audience of its own, so it is eligible
+// only when at least one note that embeds it is itself eligible; a file that
+// only withheld notes embed never reaches a view, a snapshot or a state
+// document. `isAssetEligible(asset, { embeds, isEligibleSource })` may be
+// supplied to replace the asset rule; only an exact `true` admits an asset, and
+// `revision()` must change whenever either rule does.
+export const DEFAULT_ELIGIBILITY = Object.freeze({
+  revision: () => 'classified-documents/v2+assets-embedded-by-eligible-documents/v1',
+  isEligible: (node) => node.classification === 'classified',
+})
+
+export function assetEligibilityFor({ graph, eligibility }) {
+  const eligibleSources = new Set(graph.nodes.filter((node) => eligibility.isEligible(node) === true).map((node) => node.id))
+  const embeds = Array.isArray(graph.embeds) ? graph.embeds : []
+  if (typeof eligibility.isAssetEligible === 'function') {
+    return (asset) => eligibility.isAssetEligible(asset, { embeds: embeds.filter((embed) => embed?.asset?.id === asset.id), isEligibleSource: (id) => eligibleSources.has(id) }) === true
+  }
+  const embedded = new Set(embeds.filter((embed) => eligibleSources.has(embed?.source)).map((embed) => embed?.asset?.id))
+  return (asset) => embedded.has(asset.id)
+}
+
+const posix = (value) => value.split(path.sep).join('/')
+
+// The corpus profile of a loaded project. Repository roots are recorded
+// relative to the workspace root, since a profile is a portable shape; a
+// repository kept elsewhere on this machine is recorded by name only.
+export function profileFor({ project, workspaceId, audienceAllow }) {
+  const repositories = (project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => {
+    const relative = posix(path.relative(project.workspaceRoot, repo.path))
+    const inside = relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+    return { repoId: repo.name, root: relative === '' ? '.' : inside ? relative : `elsewhere/${repo.name}`, enrollment: 'enrolled' }
+  })
+  return { schema: 'atelier-obsidian-corpus-profile/v1', workspaceId, repositories, audience: { allow: [...audienceAllow] } }
+}
+
+// `cache` (createGraphFileCache) is the engine's per-file census cache; without it every source is parsed again.
+// `index` is the engine's observation index. With both, a source whose observed digest is the cached one is not
+// opened: observation already decided by digest that it did not change, under the stat-hint bound observation
+// documents, and a full reconciliation hashes it again. Without an index every source is read and hashed here.
+export function buildGraph({ project, eligibility, cache = null, index = null }) {
+  const observedDigest = cache && index ? (repoId, relative) => index.get(sourceKey(repoId, relative))?.digest ?? null : null
+  const canonical = buildCanonicalGraph(project, { fileCache: cache, observedDigest })
+  if (!canonical.ok) refuse('canonical-graph-invalid', 'the canonical graph has errors; no view is prepared from it', { errorCount: canonical.errors.length })
+  return withEligibility(canonical, eligibility.isEligible, assetEligibilityFor({ graph: canonical, eligibility }))
+}
+
+// A source snapshot pinned to the digests observation decided on. prepareView
+// reads every source it emits again and refuses with `mixed-read` when the
+// bytes it gets are not the pinned ones, so an emitted note never carries a
+// stale digest. A note reused from the preparation cache is not read again:
+// its pinned digest is unchanged and the cached bytes are the ones that digest
+// describes, so bytes that drift under an unchanged pin are not consulted
+// until observation hashes the file again (the same bound as the graph stage).
+export function captureSnapshot({ project, graph, workspaceId, index, configDigest, capturedAt }) {
+  const roots = new Map((project.repos ?? []).filter((repo) => !repo.external).map((repo) => [repo.name, repo.path]))
+  const absolute = (repoId, relative) => {
+    const root = roots.get(repoId)
+    if (!root) refuse('source-not-in-snapshot', 'a node names a repository the project does not enrol')
+    return path.join(root, ...relative.split('/'))
+  }
+  const byRepo = new Map([...roots.keys()].map((repoId) => [repoId, new Map()]))
+  // 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))
+    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 })
+  }
+  const repositories = [...byRepo].sort(([left], [right]) => compareText(left, right))
+    .map(([repoId, files]) => ({ repoId, head: null, dirty: true, files: [...files.values()].sort((left, right) => compareText(left.path, right.path)) }))
+  // Embeds and assets are part of what was read: an embed that changes alone yields another snapshot.
+  const graphDigest = sha256Digest(Buffer.from(JSON.stringify([graph.nodes, graph.edges, graph.embeds ?? [], graph.assets ?? []])))
+  const identity = createHash('sha256').update(JSON.stringify([workspaceId, graphDigest, configDigest, repositories])).digest('hex').slice(0, 32)
+  return {
+    document: {
+      schema: 'atelier-obsidian-source-snapshot/v1',
+      contractVersion: '1.0.0',
+      snapshotId: `snap-${identity}`,
+      workspaceId,
+      capturedAt,
+      readConsistency: 'single-read',
+      graphPin: { graphDigest, nodeCount: graph.nodes.length, edgeCount: graph.edges.length },
+      versions: { source: '1', config: configDigest.slice('sha256:'.length, 'sha256:'.length + 16), emitter: EMITTER_VERSION },
+      repositories,
+    },
+    graph,
+    readSource: (repoId, relative) => readFileBytes(absolute(repoId, relative)),
+  }
+}
+
+// The engine keeps one graph file cache and one preparation cache per scope
+// for as long as it runs, and hands them to buildGraph and prepareView on
+// every tick, so a tick after a one-note change parses that source and emits
+// that note and reuses the rest. Both caches are derived, in-memory state: a
+// test may replace either seam with `() => null` to build or prepare in full.
+export function createProductionSeams() {
+  return { buildGraph, captureSnapshot, profileFor, prepareView, publishView, createRecoveryStore, recheckDisplacedFiles, createGraphCache: createGraphFileCache, createPreparationCache }
+}