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

package/src/runtime/obsidian/engine.mjs

@@ -1,23 +1,26 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { AtelierDiagnosticError } from '../../project/config.mjs'
-import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../../projection/obsidian/contracts.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, manifestLayoutVersion } from '../../projection/obsidian/contracts.mjs'
+import { PERSONAL_VALIDATION_PENDING, personalWorkspaceBindingOf, personalWorkspaceInputs, validatePersonalWorkspace } from '../../projection/obsidian/personal-workspace.mjs'
 import { PROTOCOL_ID } from '../../projection/obsidian/publication/bridge-script.mjs'
-import { PublicationRefusal } from '../../projection/obsidian/recovery/store.mjs'
+import { PublicationRefusal, allocatedFolderState, hasCommittedGeneration, readVaultAllocation } from '../../projection/obsidian/recovery/store.mjs'
 import { canonicalJson, compareText, isoTime } from './documents.mjs'
 import { readObsidianEnablement } from './enablement.mjs'
-import { ObsidianMaintenanceRefusal } from './errors.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { createMaintenanceExtensions } from './extension-points.mjs'
 import {
   assertOutsideRepositories, authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, protectedRoots, readLocalPointer,
   readMachineSettings, resolveDataRoot, workspaceStateRoot, writeMachineSettings,
 } from './machine-settings.mjs'
 import { configKey, listConfigFiles, listSourceFiles, listVaultNotes, readFileFacts, reconcile, sha256Digest, sourceKey, vaultKey } from './observation.mjs'
-import { dispatchAutomaticApply, heldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
-import { DEFAULT_ELIGIBILITY, createProductionSeams } from './pipeline.mjs'
+import { dispatchAutomaticApply, heldPaths, layoutHeldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
+import { createProductionSeams, eligibilityFor } from './pipeline.mjs'
+import { PLUGIN_FILES_WAIT_FOR_APP } from './plugin-presence.mjs'
 import { ENGINE_LOCK_DIRECTORY, acquirePrivateGenerationLock, createAbandonmentProof } from './private-lock.mjs'
 import { probeHealth } from './service-client.mjs'
 import { FRESHNESS_SCHEMA, LATE_WRITERS_SCHEMA, createMaintenanceStateStore } from './state-store.mjs'
+import { ensureVaultAllocation, projectDisplayName } from './vault-location.mjs'
 import { createNullWatcherFactory } from './watchers.mjs'
 
 // The maintenance engine. One explicit `tick()`; no timer, no process, no
@@ -38,6 +41,18 @@ import { createNullWatcherFactory } from './watchers.mjs'
 //      prepareView -> publishView, unless that would replace a held note
 //   7. persist the freshness of every view
 //
+// A view is prepared and published once more, whatever its state, on the
+// next tick after `requestPreparation(scopeId)`: a one-shot request per view
+// the project declared at the last tick (at most 64 wait before the first),
+// which the service makes for a tick requested for that view over its
+// listener (`open` requests its own). A view whose last publication did not
+// settle (stale, updating, or refused as a publisher conflict) is also tried
+// again without a request: at the full reconciliation; as soon as the app
+// looks different from when it was last tried (`observeApp`, when given: an
+// app that quit, started, or opened or closed a vault); and otherwise after a
+// delay that doubles per attempt from `publicationRetryMs` up to the full
+// reconciliation interval.
+//
 // From the moment a workspace is resolved until the tick ends, the tick holds
 // the workspace's private engine lock, so two engines (a service and a
 // foreground command, or two services) never tick one workspace together. An
@@ -50,12 +65,13 @@ import { createNullWatcherFactory } from './watchers.mjs'
 
 export const DEFAULT_FULL_RECONCILIATION_INTERVAL_MS = 5 * 60 * 1000
 export const DEFAULT_RETRY_INTERVAL_MS = 60 * 1000
+export const DEFAULT_PUBLICATION_RETRY_MS = 30 * 1000
 export const DEFAULT_LATE_WRITER_WINDOW_MS = 7 * 24 * 60 * 60 * 1000
 export const LATE_WRITER_EVERY_TICK_WINDOW_MS = 60 * 60 * 1000
 
 // A refusal that means "someone else is publishing or editing here" rather
 // than "this machine cannot publish".
-const CONFLICT_REFUSALS = new Set(['publication-in-progress', 'generation-mismatch', 'editor-uncoordinated', 'state-mismatch'])
+const CONFLICT_REFUSALS = new Set(['publication-in-progress', 'generation-mismatch', 'editor-uncoordinated', 'vault-open-in-several-windows', 'state-mismatch'])
 const EDIT_OUTCOMES = new Set(['disk-changed', 'editor-edit'])
 const RETRIED_STATES = new Set(['stale', 'updating', 'publisher-conflict'])
 // A file changed or went away under a tick: everything is hashed again on the next one.
@@ -76,6 +92,15 @@ export const ENGINE_PRIMITIVES = Object.freeze({
   dispatchAllowed: (maintenanceMode) => maintenanceMode === 'automatic',
   // Every file is hashed, whatever its stat says, at least this often.
   isFullReconciliationDue: ({ nowMs, lastFullMs, intervalMs }) => lastFullMs === null || nowMs - lastFullMs >= intervalMs,
+  // A view whose last attempt did not settle, between full reconciliations: again once a delay has passed that doubles
+  // per attempt in a row, from `retryMs` up to `maxMs`, and at once when the app looks different from when it was last
+  // tried. `appState()` answers what it looks like now, or null when that is not known.
+  isRetryDue({ nowMs, unsettled, appState, retryMs, maxMs }) {
+    if (unsettled === undefined) return false
+    if (nowMs - unsettled.lastAttemptMs >= Math.min(maxMs, retryMs * 2 ** Math.min(unsettled.attempts - 1, 20))) return true
+    const now = appState()
+    return now !== null && now !== unsettled.appState
+  },
   // The embedded assets observed beside the walk: those the last built graph lets a view copy, and no withheld one.
   observedAssetsOf: (graph) => (graph.assets ?? []).filter((asset) => asset.eligible === true).map(({ repo, path: assetPath }) => ({ repo, path: assetPath })),
   // One engine per workspace at a time, across processes.
@@ -104,7 +129,37 @@ export const ENGINE_PRIMITIVES = Object.freeze({
 })
 
 const isTypedRefusal = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal || error instanceof PublicationRefusal
+// The code a view is refused with when its own vault cannot be placed: a typed refusal's, or `vault-location-unusable`
+// for a file-system error there (a file in the way, no permission, a read-only volume). Null for anything else, which
+// is a fault of the engine and stops the tick.
+const viewRefusalCode = (error) => (isTypedRefusal(error) ? error.code : typeof error?.code === 'string' && /^E[A-Z]+$/.test(error.code) ? 'vault-location-unusable' : null)
 const digestOfJson = (value) => sha256Digest(Buffer.from(canonicalJson(value)))
+// The configuration a tick observes. A project bound to a personal workspace adds the person's authored manifest and
+// overlay and its generation's record: a change to any of them is a configuration change, so every view is prepared
+// again, asks the composition, and is refused at once when the generation no longer holds.
+const configFilesOf = (project) => [...listConfigFiles(project), ...personalWorkspaceInputs(project).map((absolute) => ({ key: configKey(absolute), changeClass: 'config', absolute }))]
+
+// An editor adapter that `build` makes, synchronously or not, the first time the publisher calls it; a refusal of
+// `build` is thrown from that call, and `refusal()` answers it afterwards.
+function builtOnFirstUse(build) {
+  let adapter = null
+  let refused = null
+  const built = () => (adapter ??= Promise.resolve().then(build).catch((error) => { refused = error; throw error }))
+  return {
+    refusal: () => refused,
+    probe: async (input) => (await built()).probe(input),
+    inspect: async (payload) => (await built()).inspect(payload),
+    collect: async (payload) => (await built()).collect(payload),
+    publish: async (payload) => (await built()).publish(payload),
+  }
+}
+// The adapter a publication gets when the factory refused the app: it coordinates with nothing and never calls it.
+function uncoordinatedAdapter(refusal) {
+  const never = async () => { throw refusal }
+  return { probe: async () => ({ state: 'uncoordinated', reason: `${refusal.code}: the installed Obsidian does not qualify, and nothing is published through it` }), inspect: never, collect: never, publish: never }
+}
+// Views a tick may be asked to prepare again, at most, before it runs.
+const MAX_PREPARATION_REQUESTS = 64
 
 function journalTime(journalId) {
   const match = /^journal-(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{3})-/.exec(journalId)
@@ -127,8 +182,19 @@ function journalsToRecheck(store, { nowMs, full, windowMs }) {
 export function createMaintenanceEngineForOracleTests(options = {}, primitives = ENGINE_PRIMITIVES) {
   const {
     loadProject, dataRoot, adapterFactory, clock,
-    watcherFactory = createNullWatcherFactory(), extensions = createMaintenanceExtensions(), eligibility = DEFAULT_ELIGIBILITY,
+    // Which notes may enter a view: what the machine settings decide at each tick (eligibilityFor), unless a test fixes it.
+    watcherFactory = createNullWatcherFactory(), extensions = createMaintenanceExtensions(), eligibility: fixedEligibility = null,
     fullReconciliationIntervalMs = DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, lateWriterWindowMs = DEFAULT_LATE_WRITER_WINDOW_MS,
+    publicationRetryMs = DEFAULT_PUBLICATION_RETRY_MS, observeApp = null,
+    // Reads the app's own vault list without asking the app (readAppVaultListForAllocation): { ok: true, vaults } with
+    // the map id -> { path }, or { ok: false, code }. A folder for a new vault is never allocated inside a vault it
+    // lists, nor under a name a vault it lists already has, nor while the list cannot be read.
+    readAppVaultList = null,
+    // Reads the app's own vault list from its file, without asking the app (unheld-evidence.mjs): { unlisted: true } only
+    // when no list names a view's vault, a folder above it or one inside it. A view never published into its allocated
+    // folder is then published even while an app runs that cannot be coordinated with, creating files only (the
+    // publisher's `direct-unheld` path). An engine given no reader never takes that path.
+    readUnheldEvidence = null,
     quietPeriodMs, lstat = fs.lstatSync, randomBytes, env = process.env, platform = process.platform,
     // A service names where it answers health, so a lock it leaves behind can be proven abandoned.
     lockOwner = null, lockProbe = probeHealth,
@@ -163,8 +229,26 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   let watching = { signature: null, handle: null }
   let known = null // { stateStore, maintenanceMode } once a workspace has been resolved
   let heldLock = null
+  // Views somebody asked to have prepared and published once more, at the next tick.
+  const preparationRequests = new Set()
+  // The views the project declared at the last tick; null before the first.
+  let declaredScopes = null
+  // Views whose last attempt did not settle, by scope: { attempts in a row, lastAttemptMs, appState then }. Kept in
+  // memory only: a new engine attempts every view on its first tick.
+  const unsettled = new Map()
+  // Views kept current although publishing their committed generation again (a drifted plugin file) needed an app
+  // that did not qualify: tried again on the same schedule as an unsettled view, and forgotten once one settles.
+  const waitingForApp = new Map()
   const proveAbandoned = createAbandonmentProof({ probe: lockProbe })
 
+  // Whether a view kept from publication by an app that does not qualify may still be published on the publisher's
+  // `direct-unheld` path: never committed, its vault the folder allocated for it, and the app's list naming no folder
+  // on the way. The publisher checks every condition again, under its locks.
+  async function unheldMayApply(store, pointer) {
+    if (typeof readUnheldEvidence !== 'function' || pointer !== null || store.vaultOrigin !== 'allocated') return false
+    try { return (await readUnheldEvidence({ vaultRoot: store.vaultRoot }))?.unlisted === true } catch { return false }
+  }
+
   async function takeLock(workspaceRoot, workspaceId) {
     if (heldLock) return { acquired: true }
     const lock = await rules.acquireEngineLock({
@@ -199,9 +283,18 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   }
 
   function storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) {
-    const signature = JSON.stringify([workspaceRoot, workspaceId, repositoryRoots])
+    // A view's vault can be allocated, made again or moved while the engine runs: the store follows its record. A
+    // store is used again only while its allocated folder is still the one the record names; otherwise it is dropped,
+    // and the store made in its place refuses, typed (vault-allocation-replaced, say), so a folder replaced while the
+    // service runs, or a link put where it was, is never published into.
+    const signature = JSON.stringify([workspaceRoot, workspaceId, repositoryRoots, readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })])
     const cached = stores.get(scope.scopeId)
-    if (cached?.signature === signature) return cached.store
+    // A vault root that is gone (a folder under the data root the person removed, say) is looked for again too, so the
+    // store made in its place says why rather than failing on the folder that is not there.
+    if (cached?.signature === signature && fs.lstatSync(cached.store.vaultRoot, { throwIfNoEntry: false }) !== undefined) {
+      try { cached.store.checkAllocatedVault?.(); return cached.store } catch (error) { if (!isTypedRefusal(error)) throw error }
+    }
+    stores.delete(scope.scopeId)
     const store = seams.createRecoveryStore({ workspaceRoot, workspaceId, scopeId: scope.scopeId, repositoryRoots })
     stores.set(scope.scopeId, { signature, store })
     return store
@@ -246,6 +339,17 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   async function runTick() {
     const now = isoTime(clock)
     const nowMs = Date.parse(now)
+    // A request that arrives while this tick runs belongs to the next one.
+    const requested = new Set(preparationRequests)
+    preparationRequests.clear()
+    // What the app looked like, asked at most once per tick and only when a decision needs it.
+    let appState
+    const appNow = () => {
+      if (appState === undefined) { try { appState = typeof observeApp === 'function' ? observeApp() ?? null : null } catch { appState = null } }
+      return appState
+    }
+    // An adapter built on a tick somebody asked for asks the app again instead of reusing an answer from before it changed.
+    if (requested.size > 0) try { adapterFactory.forget?.() } catch { /* a factory that remembers nothing */ }
     const full = firstTick || forceFull || rules.isFullReconciliationDue({ nowMs, lastFullMs, intervalMs: fullReconciliationIntervalMs })
     const changes = []
     // The hints collected so far belong to this tick; one that arrives while it runs belongs to the next.
@@ -257,20 +361,25 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
 
     // 1. Project and enablement. The digests are seeded before the project is
     // loaded for good, so the loaded project is never older than the index.
+    // A loader may answer a promise (one that composes a personal workspace off
+    // the event loop). A project bound to a personal workspace is loaded once:
+    // what a generation holds is fixed, and an input that changed after the load
+    // changes the validity key every build is checked against.
     if (project === null) {
-      project = loadProject()
-      reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full: true, lstat })
-      project = loadProject()
+      project = await loadProject()
+      reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full: true, lstat })
+      if (personalWorkspaceBindingOf(project) === null) project = await loadProject()
     } else {
-      const config = reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full, hinted, lstat })
+      const config = reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full, hinted, lstat })
       if (config.changes.length > 0) {
-        project = loadProject()
-        reconcile({ index, files: listConfigFiles(project), prefix: CONFIG_PREFIX, full: true, lstat })
+        project = await loadProject()
+        reconcile({ index, files: configFilesOf(project), prefix: CONFIG_PREFIX, full: true, lstat })
       }
     }
     const enablement = readObsidianEnablement(project)
     if (enablement.state === 'disabled') {
       stopWatching()
+      declaredScopes = new Set()
       await persistOutcome({ enablement: 'disabled', state: 'disabled', reason: enablement.reason, now, scopeIds: enablement.scopes.map((scope) => scope.scopeId) })
       semantic = null
       firstTick = true
@@ -289,14 +398,63 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (!lock.acquired) return { state: 'busy', reason: 'engine-lock-held', lock: { reason: lock.reason, holder: lock.holder ?? null }, changes: [], scopes: [], pendingEdits: [], dispatched: [], lateWriters: [] }
     const machine = readMachineSettings({ workspaceRoot, workspaceId })
       ?? writeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, settings: defaultMachineSettings({ workspaceId, updatedAt: now }) })
+    const eligibility = fixedEligibility ?? eligibilityFor({ machine, project })
     const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
     known = { stateStore, maintenanceMode: machine.maintenanceMode }
-    const scopes = enablement.scopes.map((scope) => ({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }))
+    // Each view's vault: allocated now where this workspace decided its vaults live, when it has none and was never
+    // published under the data root (vault-location.mjs). A view whose folder cannot be allocated is not prepared on
+    // this tick, and its freshness says why; the other views go on.
+    const allocationRefusals = new Map()
+    if (machine.decisions.location !== null) {
+      // The app's list, read once per tick and only when a view is about to be allocated. An engine given no reader
+      // coordinates with no app, and knows no list. A list that cannot be read allocates nothing: the view says why,
+      // and its folder is allocated at a later tick, once the list reads.
+      let list = null
+      const appList = async () => {
+        if (typeof readAppVaultList !== 'function') return { ok: true, vaults: null }
+        if (list === null) {
+          let answer
+          try { answer = await readAppVaultList() } catch { answer = null }
+          list = answer?.ok === true ? { ok: true, vaults: answer.vaults ?? {} } : { ok: false, code: typeof answer?.code === 'string' ? answer.code : 'obsidian-settings-unreadable' }
+        }
+        return list
+      }
+      // The folders allocated to the views; a record that cannot be read refuses only its own view, below.
+      const allocatedPaths = enablement.scopes.map((scope) => { try { return readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })?.path } catch { return undefined } }).filter((item) => typeof item === 'string')
+      for (const scope of enablement.scopes) {
+        try {
+          let vaults = null
+          // The list is read where a folder is about to be made: a first allocation, or an allocated folder that has gone.
+          const record = readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })
+          if (record === null ? !hasCommittedGeneration({ workspaceRoot, scopeId: scope.scopeId }) : allocatedFolderState(record) === 'missing') {
+            const known = await appList()
+            if (!known.ok) refuse('app-vault-list-unreadable', 'Obsidian\'s vault list could not be read, so no folder is allocated for this view yet; it is tried again at the next tick', { cause: known.code })
+            vaults = known.vaults
+          }
+          ensureVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId, location: machine.decisions.location, projectName: projectDisplayName(project), repositoryRoots, vaults, allocatedPaths, now })
+        } catch (error) {
+          const code = viewRefusalCode(error)
+          if (code === null) throw error
+          allocationRefusals.set(scope.scopeId, code)
+        }
+      }
+    }
+    // Each view's store, on its own: one whose vault cannot be placed (a record naming a folder inside a repository,
+    // say) is refused alone, and the other views go on.
+    const scopes = []
+    for (const scope of enablement.scopes) {
+      if (allocationRefusals.has(scope.scopeId)) continue
+      try { scopes.push({ scope, store: storeFor(scope, workspaceRoot, workspaceId, repositoryRoots) }) } catch (error) {
+        const code = viewRefusalCode(error)
+        if (code === null) throw error
+        allocationRefusals.set(scope.scopeId, code)
+      }
+    }
 
     watch([
       ...(project.repos ?? []).filter((repo) => !repo.external && typeof repo.path === 'string').map((repo) => ({ id: `repo:${repo.name}`, path: repo.path, recursive: true, keyPrefix: sourceKey(repo.name, ''), keyOf: (relative) => sourceKey(repo.name, relative) })),
       ...scopes.map(({ scope, store }) => ({ id: `vault:${scope.scopeId}`, path: store.vaultRoot, recursive: true, keyPrefix: vaultKey(scope.scopeId, ''), keyOf: (relative) => vaultKey(scope.scopeId, relative) })),
-      ...[...new Set(listConfigFiles(project).map((file) => path.dirname(file.absolute)))].filter((directory) => fs.existsSync(directory))
+      ...[...new Set(configFilesOf(project).map((file) => path.dirname(file.absolute)))].filter((directory) => fs.existsSync(directory))
         .map((directory) => ({ id: `config:${directory}`, path: directory, recursive: false, keyPrefix: CONFIG_PREFIX, keyOf: (relative) => configKey(path.join(directory, relative)) })),
     ])
 
@@ -305,10 +463,12 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     const pending = stateStore.readPendingEdits()
     let edits = pending.edits
     const basesOf = new Map()
+    const earlierLayout = new Set()
     for (const { scope, store } of scopes) {
       const { manifest, bases } = trustedNoteBases(store)
       basesOf.set(scope.scopeId, bases)
       if (!manifest) continue
+      if (manifestLayoutVersion(manifest) === 1) earlierLayout.add(scope.scopeId)
       const vault = reconcile({ index, files: listVaultNotes({ scopeId: scope.scopeId, vaultRoot: store.vaultRoot, manifest }), prefix: vaultKey(scope.scopeId, ''), full, hinted, lstat })
       const digestOf = (notePath) => index.get(vaultKey(scope.scopeId, notePath))?.digest ?? null
       const observed = observeVaultEdits({ store, workspaceId, scopeId: scope.scopeId, manifest, bases, digestOf, edits, now, preserve: rules.preserve })
@@ -321,9 +481,12 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     // Observation. The registered proposal adapter is handed a copy of the pending edits and observes the open ones
     // the object store does not know yet, a bounded number per tick: each is classified from its preserved bytes
     // against the source as it is now and recorded as what it is, in manual and in automatic mode alike, and no
-    // source is written. What refused before anything was recorded is offered again on a full reconciliation only.
+    // source is written. What refused before anything was recorded is offered again on a full reconciliation only;
+    // for a personal workspace, also on the tick after one whose graph was pending, which offers every earlier
+    // refusal again.
     const proposalAdapter = extensions.get('proposal-adapter')
-    const adapterContext = () => ({ project, workspaceRoot, workspaceId, repositoryRoots, edits: structuredClone(edits), clock, env })
+    // A personal workspace is never composed on this event loop by the adapter: its builds defer, as the engine's do.
+    const adapterContext = () => ({ project, workspaceRoot, workspaceId, repositoryRoots, edits: structuredClone(edits), clock, env, deferPersonalValidation: true })
     let observed = null
     if (proposalAdapter !== null && rules.observeEdits(proposalAdapter)) {
       try { observed = await proposalAdapter.observe(adapterContext(), { retryRefused: full }) } catch { observed = { adapterId: proposalAdapter.id, failed: 'proposal-adapter-threw' } }
@@ -391,6 +554,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (full) { lastFullMs = nowMs; forceFull = false }
 
     // 7. Which views are invalid.
+    declaredScopes = new Set(enablement.scopes.map((scope) => scope.scopeId))
     const previous = readPreviousFreshness(stateStore)
     const entries = new Map()
     const unseen = new Set()
@@ -401,15 +565,34 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     }
     const attempt = new Map()
     const invalidate = (scopeId, changeClass) => attempt.set(scopeId, new Set([...(attempt.get(scopeId) ?? []), ...(changeClass ? [changeClass] : [])]))
+    // The notes that keep a view in the vault layout they were published in (see layoutHeldPaths).
+    const layoutHeldOf = (scopeId) => layoutHeldPaths(edits, scopeId, now)
     for (const { scope } of scopes) {
       const entry = entries.get(scope.scopeId)
-      // A view that did not settle is tried again at the full reconciliation cadence, not on every tick.
-      if (firstTick || unseen.has(scope.scopeId) || (full && RETRIED_STATES.has(entry.state))) invalidate(scope.scopeId, null)
+      // A view that did not settle is tried again, not on every tick: see the head of this file.
+      const retried = (RETRIED_STATES.has(entry.state)
+        && (full || rules.isRetryDue({ nowMs, unsettled: unsettled.get(scope.scopeId), appState: appNow, retryMs: publicationRetryMs, maxMs: fullReconciliationIntervalMs })))
+        || (waitingForApp.has(scope.scopeId) && rules.isRetryDue({ nowMs, unsettled: waitingForApp.get(scope.scopeId), appState: appNow, retryMs: publicationRetryMs, maxMs: fullReconciliationIntervalMs }))
+      if (firstTick || unseen.has(scope.scopeId) || requested.has(scope.scopeId) || retried) invalidate(scope.scopeId, null)
+      // A settled view still in the earlier vault layout is laid out again at the first tick where no note holds it.
+      if (earlierLayout.has(scope.scopeId) && entry.state === 'current' && layoutHeldOf(scope.scopeId).length === 0) invalidate(scope.scopeId, null)
     }
     for (const change of changes) for (const { scope } of scopes) if (change.scopeId === undefined || change.scopeId === scope.scopeId) invalidate(scope.scopeId, change.changeClass)
+    // A bound personal workspace is composed again, off the event loop, at every full reconciliation, whatever else is
+    // being prepared: a cause outside its validity key can stop a generation holding without a file this engine
+    // observes. Its views are prepared again only when the composition refuses, or confirms another key.
+    let personalRefusal = null
+    if (full && personalWorkspaceBindingOf(project) !== null) {
+      const verdict = await validatePersonalWorkspace(project)
+      if (verdict.ok !== true) personalRefusal = verdict.code
+      if (verdict.ok !== true || verdict.changed) for (const { scope } of scopes) invalidate(scope.scopeId, null)
+    }
 
     // Invalidation is durable before any work: a view is not reported current while it is being rebuilt.
     for (const [scopeId, classes] of attempt) entries.set(scopeId, { ...demote(entries.get(scopeId), 'stale', 'invalidated', now), changeClasses: [...classes].sort() })
+    for (const [scopeId, code] of allocationRefusals) {
+      entries.set(scopeId, demote(previous?.scopes.find((entry) => entry.scopeId === scopeId && entry.state !== 'disabled') ?? blankEntry(scopeId, now), 'stale', code, now))
+    }
     for (const entry of previous?.scopes ?? []) if (!entries.has(entry.scopeId)) entries.set(entry.scopeId, demote(entry, 'disabled', 'scope-not-configured', now))
     const persist = () => stateStore.writeFreshness(freshnessDocument({ workspaceId, enablement: 'enabled', maintenanceMode: machine.maintenanceMode, now, entries }))
     persist()
@@ -418,7 +601,19 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (attempt.size > 0) {
       let built = null
       try {
-        const graph = seams.buildGraph({ project, eligibility, cache: graphCache, index })
+        if (personalRefusal !== null) refuse(personalRefusal, 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
+        // A personal workspace whose validity key is not confirmed yet is composed off the event loop, then built again.
+        const build = () => seams.buildGraph({ project, eligibility, cache: graphCache, index, deferPersonalValidation: true })
+        let graph
+        try { graph = build() } catch (error) {
+          if (error?.code !== PERSONAL_VALIDATION_PENDING) throw error
+          const verdict = await validatePersonalWorkspace(project)
+          if (verdict?.ok !== true) refuse(verdict?.code ?? 'personal-binding-unrecognized', 'the personal workspace refused this generation; nothing is prepared from it', { source: 'personal-workspace' })
+          try { graph = build() } catch (again) {
+            if (again?.code !== PERSONAL_VALIDATION_PENDING) throw again
+            refuse('personal-graph-unconfirmed', 'the graph built for the personal workspace is not the one its composition built; nothing is prepared from it', { source: 'personal-workspace' })
+          }
+        }
         // The assets this graph lets a view copy are observed from now on, and hashed now so the snapshot pins
         // what observation saw. A withheld asset is not observed: its bytes can change no view.
         const formerAssetKeys = new Set(observedAssets.map((asset) => sourceKey(asset.repo, asset.path)))
@@ -436,20 +631,30 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
         if (!isTypedRefusal(error)) throw error
         for (const scopeId of attempt.keys()) entries.set(scopeId, demote(entries.get(scopeId), 'stale', error.code, now))
         if (REREAD_CODES.has(error.code)) forceFull = true
+        // The personal workspace refused the bound generation: the project is loaded again at the next tick, so a
+        // loader that now binds another generation is followed.
+        if (error.detail?.source === 'personal-workspace') project = null
       }
       for (const { scope, store } of built ? scopes.filter((item) => attempt.has(item.scope.scopeId)) : []) {
         const { scopeId } = scope
         const entry = entries.get(scopeId)
-        const settle = (state, reason, extra = {}) => entries.set(scopeId, { ...entry, ...extra, state, reason, verified: extra.verified === true, checkedAt: now })
+        // What this attempt found worth naming: notes and rules (see "Notes that were laid out anyway" in docs/obsidian-contract.md).
+        let diagnostics = []
+        const settle = (state, reason, extra = {}) => {
+          const { diagnostics: _earlier, ...rest } = { ...entry, ...extra, state, reason, verified: extra.verified === true, checkedAt: now }
+          entries.set(scopeId, diagnostics.length > 0 ? { ...rest, diagnostics } : rest)
+        }
         try {
+          const held = heldPaths(edits, scopeId)
           const prepared = seams.prepareView({
             snapshot: built.snapshot, profile: built.profile, scope, persistentPathRegistry: stateStore.readPathRegistry(), priorManifest: store.readCurrentManifest(),
             existingSettings: null, clock, vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8'), cache: preparationCacheFor(scopeId),
+            heldNotePaths: held, layoutHeldNotePaths: layoutHeldOf(scopeId), viewScopeIds: scopes.map((item) => item.scope.scopeId),
           })
           stateStore.writePathRegistry(prepared.persistentPathRegistry)
+          diagnostics = (prepared.manifest.ext?.[OBSIDIAN_EXT_KEY]?.diagnostics ?? []).slice(0, 100)
           const preparedGenerationId = prepared.manifest.generationId
           const trusted = () => store.readCurrent()
-          const held = heldPaths(edits, scopeId)
           const observed = new Map(held.map((notePath) => [notePath, rules.heldNoteDigest({ file: path.join(store.vaultRoot, notePath), indexed: index.get(vaultKey(scopeId, notePath))?.digest ?? null })]))
           const conflicts = rules.publicationConflicts({ prepared, held, bases: basesOf.get(scopeId) ?? new Map(), observed })
           if (conflicts.length > 0) {
@@ -459,10 +664,43 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           }
           settle('updating', 'publishing', { generationId: trusted()?.generationId ?? null, preparedGenerationId, heldNotes: held })
           persist()
-          const result = await seams.publishView({
-            preparedView: prepared, protocolId: PROTOCOL_ID, expectedGeneration: trusted()?.generationId ?? null, recoveryStore: store, adapter: adapterFactory({ store, scope }), clock,
-            ...(quietPeriodMs === undefined ? {} : { quietPeriodMs }),
-          })
+          // A generation that is already the committed one needs no app: the publisher settles it after its own restart
+          // recovery, before it would probe. Its adapter is then built only if the publisher asks for one, so an app
+          // that cannot be qualified never makes a current view stale. Any other publication builds the adapter first,
+          // and an app that does not qualify keeps the publisher from being reached at all.
+          const lazy = trusted()?.generationId === preparedGenerationId ? builtOnFirstUse(() => adapterFactory({ store, scope })) : null
+          // A view never published into its allocated folder is not kept from its first publication by an app that
+          // does not qualify, while that app's list shows no entry for the folder: the publisher is reached with an
+          // adapter that coordinates with nothing, and may take its `direct-unheld` path. Any other outcome is the
+          // factory's refusal, as before.
+          let heldBackBy = null
+          let adapter = lazy
+          if (adapter === null) {
+            try { adapter = await adapterFactory({ store, scope }) } catch (error) {
+              if (!isTypedRefusal(error) || !(await unheldMayApply(store, trusted()))) throw error
+              heldBackBy = error
+              adapter = uncoordinatedAdapter(error)
+            }
+          }
+          let result
+          try {
+            result = await seams.publishView({
+              preparedView: prepared, protocolId: PROTOCOL_ID, expectedGeneration: trusted()?.generationId ?? null, recoveryStore: store, adapter, clock,
+              ...(quietPeriodMs === undefined ? {} : { quietPeriodMs }),
+              ...(typeof readUnheldEvidence === 'function' ? { unheldEvidence: readUnheldEvidence, platform } : {}),
+            })
+            // Stopped before its commit for want of an app that coordinates: the app's refusal is what the person has to
+            // act on, and `open` answers it before it would add the vault to the app.
+            if (heldBackBy !== null && (result.state === 'refused' || (result.state === 'updating' && result.notes.some((note) => note.blocking && note.outcome === 'editor-uncoordinated')))) throw heldBackBy
+          } catch (error) {
+            // The publisher asked for the app only to publish the committed generation again (a plugin file drifted),
+            // and the app did not qualify: nothing was written, and the committed generation is read back as it is.
+            // The file is written at a later attempt, once the app qualifies.
+            if (lazy === null || lazy.refusal() !== error || !isTypedRefusal(error) || trusted()?.generationId !== preparedGenerationId) throw error
+            result = { state: 'committed', alreadyCommitted: true, notes: [], waitsForApp: true }
+          }
+          if (result.waitsForApp === true) waitingForApp.set(scopeId, { attempts: (waitingForApp.get(scopeId)?.attempts ?? 0) + 1, lastAttemptMs: nowMs, appState: appNow() })
+          else waitingForApp.delete(scopeId)
           const pointerNow = trusted()
           const common = { generationId: pointerNow?.generationId ?? null, preparedGenerationId, retainedEdits: pointerNow?.retained?.length ?? 0 }
           if (result.state === 'refused') {
@@ -483,16 +721,27 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
             // Somebody wrote during the publication. The next tick preserves and queues it.
             else if (differing.length > 0 || editedUnderPublisher) settle('updating', 'read-back-differs', common)
             else if (common.generationId !== preparedGenerationId) settle('stale', 'committed-generation-differs', common)
-            else settle('current', result.alreadyCommitted ? 'verified-by-read-back' : 'published-and-verified', { ...common, heldNotes: [], verified: true })
+            // Kept current while a plugin file waits for the app: the reason says so, and status shows it on the plugin line.
+            else settle('current', result.waitsForApp === true ? PLUGIN_FILES_WAIT_FOR_APP : result.alreadyCommitted ? 'verified-by-read-back' : 'published-and-verified', { ...common, heldNotes: [], verified: true })
           }
         } catch (error) {
           if (!isTypedRefusal(error)) { settle('stale', 'publisher-error'); persist(); throw error }
+          // A redaction refusal names the note and the rule it concerns, never the value.
+          const where = error.code === 'redaction-failure' ? error.detail ?? {} : {}
+          diagnostics = typeof where.rule === 'string' ? [{ code: error.code, rule: where.rule, ...(typeof where.notePath === 'string' ? { notePath: where.notePath } : {}), ...(typeof where.filePath === 'string' ? { filePath: where.filePath } : {}) }] : []
           settle('stale', error.code)
           if (REREAD_CODES.has(error.code)) forceFull = true
         }
       }
     }
     persist()
+    for (const scopeId of attempt.keys()) {
+      const settled = !RETRIED_STATES.has(entries.get(scopeId).state)
+      if (settled) unsettled.delete(scopeId)
+      else unsettled.set(scopeId, { attempts: (unsettled.get(scopeId)?.attempts ?? 0) + 1, lastAttemptMs: nowMs, appState: appNow() })
+    }
+    for (const scopeId of [...unsettled.keys()]) if (!entries.has(scopeId) || entries.get(scopeId).state === 'disabled') unsettled.delete(scopeId)
+    for (const scopeId of [...waitingForApp.keys()]) if (entries.get(scopeId)?.state !== 'current') waitingForApp.delete(scopeId)
     semantic = nextSemantic
     firstTick = false
     return {
@@ -505,6 +754,16 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
 
   return {
     extensions,
+    // The next tick that starts prepares and publishes this view once more, whatever its state. A view this
+    // project does not declare is ignored then.
+    // A view the project declared at the last tick (before the first, any view), and at most MAX_PREPARATION_REQUESTS
+    // of them; whether the request was taken.
+    requestPreparation(scopeId) {
+      if (typeof scopeId !== 'string' || scopeId === '' || (declaredScopes !== null && !declaredScopes.has(scopeId))) return false
+      if (!preparationRequests.has(scopeId) && preparationRequests.size >= MAX_PREPARATION_REQUESTS) return false
+      preparationRequests.add(scopeId)
+      return true
+    },
     async tick() {
       if (running) return { state: 'busy' }
       running = true

package/src/runtime/obsidian/extension-points.mjs

@@ -65,7 +65,7 @@ export function normalizeApplyResult(value) {
 // an apply operation replaces it.
 const OPERATION_NAME = /^[a-z][a-z0-9-]{0,31}$/
 // The operations the command ships. The service composes the same registry, so both refuse the same contributions.
-export const BUILT_IN_OPERATIONS = Object.freeze(['status', 'scope', 'audience', 'mode', 'policy', 'service', 'open', 'apply', 'help'])
+export const BUILT_IN_OPERATIONS = Object.freeze(['status', 'settings', 'location', 'scope', 'view', 'audience', 'mode', 'policy', 'service', 'open', 'uninstall', 'plugin', 'apply', 'help'])
 export const REPLACEABLE_OPERATIONS = Object.freeze(['apply'])
 
 export function createCommandOperations({ reserved = [] } = {}) {

package/src/runtime/obsidian/index.mjs

@@ -6,29 +6,36 @@
 export { ObsidianMaintenanceRefusal } from './errors.mjs'
 export { DISABLED_REASONS, ENABLEMENT_STATES, readObsidianEnablement } from './enablement.mjs'
 export {
-  LOCAL_POINTER_SCHEMA, MACHINE_SETTINGS_SCHEMA, MAINTENANCE_MODES, authorizeAutomaticApply, defaultDataRoot, defaultMachineSettings, ensureWorkspaceIdentity,
-  installApplyPolicy, localPointerPath, protectedRoots, readInstalledApplyPolicy, readLocalPointer, readMachineSettings, resolveDataRoot, revokeApplyPolicy, workspaceStateRoot, writeLocalPointer, writeMachineSettings,
+  DECISIONS, DECISION_SOURCES, LOCAL_POINTER_SCHEMA, MACHINE_SETTINGS_SCHEMA, MACHINE_SETTINGS_SCHEMA_V1, MAINTENANCE_MODES, ONLY_YOU_AUDIENCES, authorizeAutomaticApply,
+  defaultDataRoot, defaultMachineSettings, ensureWorkspaceIdentity, installApplyPolicy, localPointerPath, protectedRoots, readInstalledApplyPolicy, readLocalPointer,
+  readMachineSettings, resolveDataRoot, revokeApplyPolicy, withDecision, workspaceStateRoot, writeLocalPointer, writeMachineSettings,
 } from './machine-settings.mjs'
 export { APPLY_RESULT_STATUSES, BUILT_IN_OPERATIONS, EXTENSION_KINDS, REPLACEABLE_OPERATIONS, UNAVAILABLE_APPLY_OPERATION, createCommandOperations, createMaintenanceExtensions, createObsidianRegistry } from './extension-points.mjs'
 export { CONTRIBUTIONS_DIRECTORY, loadContributions } from './contributions.mjs'
 export { APP_OUTCOMES, MINIMUM_APP_VERSION, compareAppVersions, createQualifiedAdapterFactory, meetsMinimumAppVersion, parseAppVersion, qualifyApp } from './app-capability.mjs'
 export { OPENING_OUTCOMES, describeOutcome, openScope, scopeReport } from './opening.mjs'
+export { appStateSignature, registerVaultInObsidianSettings } from './app-registration.mjs'
 export {
   CHANGE_CLASSES, CLOSED_EDIT_STATES, EDIT_STATES, FRESHNESS_SCHEMA, FRESHNESS_STATES, LATE_WRITERS_SCHEMA, OPEN_EDIT_STATES, PENDING_EDITS_SCHEMA,
   createMaintenanceStateStore, validateFreshness, validateLateWriters, validatePendingEdits,
 } from './state-store.mjs'
 export { listConfigFiles, listSourceFiles, listVaultNotes, reconcile } from './observation.mjs'
 export { createFsWatcherFactory, createNullWatcherFactory } from './watchers.mjs'
-export { DEFAULT_ELIGIBILITY, assetEligibilityFor, createProductionSeams } from './pipeline.mjs'
-export { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, DEFAULT_LATE_WRITER_WINDOW_MS, DEFAULT_RETRY_INTERVAL_MS, createMaintenanceEngine } from './engine.mjs'
+export { DEFAULT_ELIGIBILITY, assetEligibilityFor, createProductionSeams, eligibilityFor, onlyYouEligibility } from './pipeline.mjs'
+export { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, DEFAULT_LATE_WRITER_WINDOW_MS, DEFAULT_PUBLICATION_RETRY_MS, DEFAULT_RETRY_INTERVAL_MS, createMaintenanceEngine } from './engine.mjs'
 export { ENGINE_LOCK_DIRECTORY, LOCK_TICKET_SCHEMA, acquirePrivateGenerationLock, createAbandonmentProof, inspectPrivateGenerationLock } from './private-lock.mjs'
 export { DEFAULT_MAX_BACKOFF_MS, DEFAULT_TICK_INTERVAL_MS, createTickLoop } from './tick-loop.mjs'
 export { HEALTH_SCHEMA, LOOPBACK_HOSTS, probeHealth, requestLoopback } from './service-client.mjs'
 export {
-  CONSENT_COVERAGES, SERVICE_ERROR_SCHEMA, SERVICE_SETTINGS_SCHEMA, executableIdentity, publicRecord, readLastServiceError, readServiceRecord, readServiceSettings,
-  removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
+  CONSENT_COVERAGES, LAST_STARTUP_SCHEMA, SERVICE_ERROR_SCHEMA, SERVICE_SETTINGS_SCHEMA, STARTUP_OUTCOMES, executableIdentity, publicRecord, readLastServiceError, readLastStartup,
+  readServiceRecord, readServiceSettings, removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
 } from './service-record.mjs'
 export { MAX_REQUEST_BYTES, SERVICE_OPERATIONS, createServiceServer } from './service-server.mjs'
-export { DEFAULT_SHUTDOWN_GRACE_MS, SERVICE_STATUS_SCHEMA, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
+export { PLUGIN_BEARER_SCHEMA, PLUGIN_PRESENCE_SCHEMA, createPluginChannel, createPluginSessions, ensurePluginBearer, pluginBearerDirectory, pluginPresence, readPluginBearers } from './plugin-channel.mjs'
+export { PLUGIN_PRESENCE_REASONS, pluginPresenceOf, turnPluginOnNext, withPluginReportedVersion } from './plugin-presence.mjs'
+export { PLUGIN_CHOICE_SCHEMA, PLUGIN_CHOICE_STATES, confirmPluginEntry, confirmPluginSeen, currentPluginChoice, decidePluginChoice, pluginChoiceDirectory, readCommunityEntry, readPluginChoice, viewVaultRoot, writePluginChoice } from './plugin-choice.mjs'
+export { DEFAULT_SHUTDOWN_GRACE_MS, RELEASE_CHANGED, SERVICE_STATUS_SCHEMA, resolveServiceWorkspace, runMaintenanceService } from './service.mjs'
 export { DEFAULT_START_TIMEOUT_MS, DEFAULT_STOP_TIMEOUT_MS, SERVICE_STATES, readServiceStatusDocument, requestServiceTick, serviceStatus, startService, stopService } from './lifecycle.mjs'
-export { STARTUP_PLATFORMS, buildStartupAdapter } from './startup-adapters.mjs'
+export { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from './startup-adapters.mjs'
+export { LOGIN_ITEM_SCHEMA, installLoginItem, loginItemStatus, removeLoginItem, resolveLoginItemEntry } from './login-item.mjs'
+export { SERVICE_MANAGER_KINDS, createLaunchdManager, createSystemdManager } from './service-managers.mjs'