@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.10

package/src/runtime/obsidian/observation.mjs

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { DOC_EXTENSIONS } from '../../graph/knowledge-graph.mjs'
+import { localOverlayCandidatePaths } from '../../project/config.mjs'
+import { openRegularFileNoFollow } from '../../project/private-state.mjs'
+import { compareText } from './documents.mjs'
+
+// Observation by digest. The git-based observation of the synchronization
+// loop sees only what git tracks inside a repository; a vault is outside every
+// repository and ignored by design, so this module looks at files directly and
+// never asks git anything.
+//
+// Three layers, each only ever an accelerator for the next:
+//
+//   watcher event   names a path to look at now. Events may be lost, repeated
+//                   or late on every platform; nothing is decided from one.
+//   stat hint       size, modification time, change time and inode. A
+//                   difference means "hash this file"; equality means "skip it
+//                   on this tick". A hint never reports a change by itself.
+//   digest          the only thing that decides. A full reconciliation hashes
+//                   every observed file whatever its stat says, so a change
+//                   the first two layers missed converges there.
+
+export const sha256Digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules'])
+const SIDECAR_SUFFIX = '.kg.json'
+
+export const sourceKey = (repoId, relative) => `source\u0000${repoId}\u0000${relative}`
+export const configKey = (absolute) => `config\u0000${absolute}`
+export const vaultKey = (scopeId, relative) => `vault\u0000${scopeId}\u0000${relative}`
+
+function walk(root, relative, found) {
+  let entries
+  try { entries = fs.readdirSync(path.join(root, relative), { withFileTypes: true }) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return found
+    throw error
+  }
+  for (const entry of entries.sort((left, right) => compareText(left.name, right.name))) {
+    if (entry.name.startsWith('.') || SKIPPED_DIRECTORIES.has(entry.name)) continue
+    const child = relative === '' ? entry.name : `${relative}/${entry.name}`
+    // Links are not followed: a link could lead outside the repository.
+    if (entry.isDirectory()) walk(root, child, found)
+    else if (entry.isFile()) found.push(child)
+  }
+  return found
+}
+
+function sourceClass(relative, names) {
+  if (relative.endsWith(SIDECAR_SUFFIX)) return 'sidecar'
+  const extension = path.posix.extname(relative).toLowerCase()
+  if (extension === '.md') return 'source-body'
+  // Any other file is a source only when the census could enrol it: a document
+  // extension, or a file with a sidecar beside it.
+  return DOC_EXTENSIONS.has(extension) || names.has(`${relative}${SIDECAR_SUFFIX}`) ? 'asset' : null
+}
+
+// Every file whose bytes can change a view: source bodies, sidecars and the
+// assets they enrol, in every enrolled repository. Deliberately a superset of
+// the census (it does not apply ignore rules): observing one file too many
+// costs a rebuild that produces the same generation, observing one too few
+// would leave a view stale.
+export function listSourceFiles(project, { assets = [] } = {}) {
+  const files = []
+  const roots = new Map()
+  for (const repo of project.repos ?? []) {
+    if (repo.external || typeof repo.path !== 'string' || typeof repo.name !== 'string') continue
+    roots.set(repo.name, repo.path)
+    const relatives = walk(repo.path, '', [])
+    const names = new Set(relatives)
+    for (const relative of relatives) {
+      const changeClass = sourceClass(relative, names)
+      if (changeClass) files.push({ key: sourceKey(repo.name, relative), changeClass, absolute: path.join(repo.path, relative), repoId: repo.name, relative })
+    }
+  }
+  // Embedded assets of the last built graph. The resolver accepts a file in a
+  // dot-directory, which the walk skips, and an image has no sidecar, so these
+  // are listed by name. Only assets a view may copy are passed in.
+  const listed = new Set(files.map((file) => file.key))
+  for (const asset of assets) {
+    const key = sourceKey(asset.repo, asset.path)
+    if (!roots.has(asset.repo) || listed.has(key)) continue
+    listed.add(key)
+    files.push({ key, changeClass: 'asset', absolute: path.join(roots.get(asset.repo), ...asset.path.split('/')), repoId: asset.repo, relative: asset.path })
+  }
+  return files
+}
+
+// The files that decide what a project is: its configuration, its repository
+// access file and every place a local overlay may appear. A path that does
+// not exist yet is observed too, so its appearance is a change.
+export function listConfigFiles(project) {
+  const paths = new Set([project.configPath, project.repoAccessPath, ...localOverlayCandidatePaths({ configDir: project.configDir, env: {} }), ...(project.localOverlay?.paths ?? [])].filter((item) => typeof item === 'string'))
+  return [...paths].sort().map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))
+}
+
+export function listVaultNotes({ scopeId, vaultRoot, manifest }) {
+  return (manifest?.notes ?? []).map((note) => ({ key: vaultKey(scopeId, note.path), changeClass: 'vault-note', absolute: path.join(vaultRoot, ...note.path.split('/')), scopeId, relative: note.path }))
+}
+
+function statHint(file, lstat) {
+  let stat
+  try { stat = lstat(file) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+    throw error
+  }
+  return stat.isFile() ? { size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino } : null
+}
+
+// One read: the digest and the length are of the same bytes.
+export function readFileFacts(file) {
+  let descriptor
+  try { descriptor = openRegularFileNoFollow(file) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'ELOOP' || error.message === 'state leaf is not a regular file') return null
+    throw error
+  }
+  try {
+    const bytes = fs.readFileSync(descriptor)
+    return { digest: sha256Digest(bytes), byteLength: bytes.length }
+  } finally { fs.closeSync(descriptor) }
+}
+
+const sameHint = (left, right) => left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.ino === right.ino
+
+// Reconciles `files` against `index` (a Map owned by the caller) and returns
+// the changes, decided by digest alone. `full` hashes everything; otherwise a
+// file is hashed when it is new, when its stat hint differs or when a watcher
+// named it. Entries under `prefix` that are no longer listed are removals.
+export function reconcile({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
+  const changes = []
+  const present = new Set()
+  let hashed = 0
+  for (const file of files) {
+    present.add(file.key)
+    const previous = index.get(file.key)
+    const hint = statHint(file.absolute, lstat)
+    if (hint === null) {
+      if (previous && previous.digest !== null) changes.push({ key: file.key, changeClass: previous.changeClass, kind: 'removed' })
+      index.set(file.key, { changeClass: file.changeClass, hint: null, digest: null, byteLength: null })
+      continue
+    }
+    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) continue
+    const facts = readFileFacts(file.absolute)
+    const digest = facts?.digest ?? null
+    hashed += 1
+    if (!previous || previous.digest !== digest || previous.changeClass !== file.changeClass) {
+      if (digest !== null || (previous && previous.digest !== null)) changes.push({ key: file.key, changeClass: file.changeClass, kind: !previous || previous.digest === null ? 'added' : digest === null ? 'removed' : 'changed' })
+    }
+    index.set(file.key, { changeClass: file.changeClass, hint: digest === null ? null : hint, digest, byteLength: facts?.byteLength ?? null })
+  }
+  for (const [key, previous] of index) {
+    if (!key.startsWith(prefix) || present.has(key)) continue
+    if (previous.digest !== null) changes.push({ key, changeClass: previous.changeClass, kind: 'removed' })
+    index.delete(key)
+  }
+  return { changes, hashed }
+}

package/src/runtime/obsidian/opening.mjs

@@ -0,0 +1,263 @@
+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] }
+}
+
+// A reason whose next step is not its outcome's. With no vault open the app's
+// command line answers nothing, its version included, so the version floor
+// cannot be checked until a vault is open or the app is quit.
+// `editor-uncoordinated` is the publisher refusing to write while an Obsidian
+// runs that does not answer for this vault: nothing coordinates with the app,
+// so nothing is written. There is no other publisher to wait for. With the app
+// quit, the view is published directly, and `open` then starts the app on it.
+export const REASON_NEXT = Object.freeze({
+  'no-vault-open': 'open any vault in Obsidian, or quit Obsidian, then open again',
+  'editor-uncoordinated': 'Obsidian is running without this vault open, so nothing is written into it: quit Obsidian, let the view publish, then open again',
+})
+
+// The next step for an outcome and its reason; null for a code that is not an opening outcome.
+export function nextStep(outcome, reason) {
+  if (typeof reason === 'string' && Object.hasOwn(REASON_NEXT, reason)) return REASON_NEXT[reason]
+  return Object.hasOwn(OPENING_OUTCOMES, outcome) ? OPENING_OUTCOMES[outcome].next : null
+}
+
+// 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'])
+// After a launch: the app is still starting, or still opening the vault it was asked for.
+const NOT_UP_YET = new Set(['version-unknown', 'no-vault-open'])
+
+// 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), next: nextStep(outcome, extra.reason), 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, or not yet opened a vault, is asked again.
+    if (!rules.appQualifies(after) && !NOT_UP_YET.has(after.reason)) 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 }
+}