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

package/src/runtime/obsidian/engine.mjs

@@ -1,7 +1,7 @@
 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 { PROTOCOL_ID } from '../../projection/obsidian/publication/bridge-script.mjs'
 import { PublicationRefusal } from '../../projection/obsidian/recovery/store.mjs'
 import { canonicalJson, compareText, isoTime } from './documents.mjs'
@@ -13,7 +13,7 @@ import {
   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 { dispatchAutomaticApply, heldPaths, layoutHeldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
 import { DEFAULT_ELIGIBILITY, createProductionSeams } from './pipeline.mjs'
 import { ENGINE_LOCK_DIRECTORY, acquirePrivateGenerationLock, createAbandonmentProof } from './private-lock.mjs'
 import { probeHealth } from './service-client.mjs'
@@ -38,6 +38,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 +62,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 +89,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.
@@ -106,6 +128,23 @@ export const ENGINE_PRIMITIVES = Object.freeze({
 const isTypedRefusal = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal || error instanceof PublicationRefusal
 const digestOfJson = (value) => sha256Digest(Buffer.from(canonicalJson(value)))
 
+// 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),
+  }
+}
+// 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)
   return match ? Date.UTC(+match[1], +match[2] - 1, +match[3], +match[4], +match[5], +match[6], +match[7]) : null
@@ -129,6 +168,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     loadProject, dataRoot, adapterFactory, clock,
     watcherFactory = createNullWatcherFactory(), extensions = createMaintenanceExtensions(), eligibility = DEFAULT_ELIGIBILITY,
     fullReconciliationIntervalMs = DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, lateWriterWindowMs = DEFAULT_LATE_WRITER_WINDOW_MS,
+    publicationRetryMs = DEFAULT_PUBLICATION_RETRY_MS, observeApp = 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,6 +203,16 @@ 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 })
 
   async function takeLock(workspaceRoot, workspaceId) {
@@ -246,6 +296,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.
@@ -271,6 +332,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     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
@@ -305,10 +367,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 })
@@ -391,6 +455,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (full) { lastFullMs = nowMs; forceFull = false }
 
     // 7. Which views are invalid.
+    declaredScopes = new Set(scopes.map(({ scope }) => scope.scopeId))
     const previous = readPreviousFreshness(stateStore)
     const entries = new Map()
     const unseen = new Set()
@@ -401,10 +466,17 @@ 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)
 
@@ -440,16 +512,23 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       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 +538,27 @@ 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
+          const adapter = lazy ?? await adapterFactory({ store, scope })
+          let result
+          try {
+            result = await seams.publishView({
+              preparedView: prepared, protocolId: PROTOCOL_ID, expectedGeneration: trusted()?.generationId ?? null, recoveryStore: store, adapter, clock,
+              ...(quietPeriodMs === undefined ? {} : { quietPeriodMs }),
+            })
+          } 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') {
@@ -487,12 +583,22 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           }
         } 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 +611,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', 'scope', 'audience', 'mode', 'policy', 'service', 'open', 'plugin', 'apply', 'help'])
 export const REPLACEABLE_OPERATIONS = Object.freeze(['apply'])
 
 export function createCommandOperations({ reserved = [] } = {}) {

package/src/runtime/obsidian/index.mjs

@@ -13,6 +13,7 @@ export { APPLY_RESULT_STATUSES, BUILT_IN_OPERATIONS, EXTENSION_KINDS, REPLACEABL
 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,
@@ -20,7 +21,7 @@ export {
 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_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'
@@ -29,6 +30,9 @@ export {
   removeServiceRecord, serviceNameFor, servicePaths, validateServiceRecord, writeServiceRecord, writeServiceSettings,
 } from './service-record.mjs'
 export { MAX_REQUEST_BYTES, SERVICE_OPERATIONS, createServiceServer } from './service-server.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, 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'

package/src/runtime/obsidian/launch-plan.mjs

@@ -0,0 +1,88 @@
+// How `open` shows a vault in Obsidian, as steps a launcher carries out. Pure.
+//
+// Two facts of the app (1.13.7, read from its main process and checked on an
+// isolated instance) decide the steps:
+//
+//   - An app started with an `obsidian://` URL opens only that URL's vault and
+//     deletes the `open` flag of every other vault without a window, so the
+//     person's other vaults do not come back the next time Obsidian starts.
+//     Started plainly, it reopens every vault its list marks open (the view's
+//     vault included, when it was added to the list marked open) and keeps
+//     the flags.
+//   - `open?path=` picks the listed vault whose folder is the longest string
+//     prefix of the path, with no separator check; `open?vault=<id>` names one
+//     vault exactly.
+//
+// So a vault is named by its id where that id reaches it first (a vaultRoute
+// of `how: 'id'`), and otherwise by its own path, which the app then matches
+// exactly (a listed folder is the longest prefix of its own path); an app that is not running is
+// started plainly and handed the URL only once it answers: a URL reaching a
+// running app opens a window and changes no flag. On Linux a plain start is not
+// qualified, and the URL starts the app, with the flag loss as a known limit.
+//
+// Steps:
+//   { step: 'plain-start' }           start the app with no URL
+//   { step: 'wait-for-app' }          wait, bounded, until the app itself answers its command-line tool
+//   { step: 'url', uri }              hand the URL to the running app
+//   { step: 'url-start', uri }        start the app with the URL (Linux only)
+//
+// { ok: true, steps } or { ok: false, reason }.
+
+const VAULT_ID = /^[A-Za-z0-9_-]{1,64}$/
+
+export function launchPlan({ platform = process.platform, appRunning, vaultId = null, vaultPath = null } = {}) {
+  let uri
+  if (typeof vaultId === 'string' && VAULT_ID.test(vaultId)) uri = `obsidian://open?vault=${encodeURIComponent(vaultId)}`
+  else if (typeof vaultPath === 'string' && vaultPath.startsWith('/') && !vaultPath.includes('\u0000')) uri = `obsidian://open?path=${encodeURIComponent(vaultPath)}`
+  else return { ok: false, reason: 'vault-id-unknown' }
+  if (platform !== 'darwin' && platform !== 'linux') return { ok: false, reason: 'launcher-platform-unqualified' }
+  if (appRunning === true) return { ok: true, steps: [{ step: 'url', uri }] }
+  if (platform === 'darwin') return { ok: true, steps: [{ step: 'plain-start' }, { step: 'wait-for-app' }, { step: 'url', uri }] }
+  return { ok: true, steps: [{ step: 'url-start', uri }] }
+}
+
+// Pure. Whether the command-line tool's reply to a URL says the app took it ("Processed URI …").
+export const urlProcessed = (stdout) => typeof stdout === 'string' && /^processed uri\b/im.test(stdout)
+
+// Carries out a launchPlan with injected actions, so the order and the
+// fallbacks are the same for the production launcher and the test harness:
+//
+//   start()        -> Promise<boolean>  start the app with no URL
+//   answered()     -> Promise<boolean>  one poll: the app itself answered (appAnswered); a tool that cannot find the
+//                                       app yet is not an answer
+//   handLink(uri)  -> Promise<boolean>  the app's tool took the URL (urlProcessed)
+//   osOpen(uri)    -> Promise<boolean>  the operating system accepted the URL
+//
+// A URL is never handed to the operating system for an app this launch
+// started: that would start or reach it while it starts, which is what drops
+// the other vaults' reopen flags. The vault was added flagged open, so a plainly
+// started app opens it anyway, and `open` waits for it.
+export async function runLaunchPlan(plan, { start, answered, handLink, osOpen, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), waitMs = 30_000, pollMs = 500, now = () => Date.now() }) {
+  if (!plan?.ok) return { launched: false, reason: plan?.reason ?? 'launcher-refused' }
+  let started = false
+  let reason = 'url-accepted'
+  for (const { step, uri } of plan.steps) {
+    if (step === 'plain-start') {
+      if (!(await start())) return { launched: false, reason: 'os-open-failed' }
+      started = true
+    } else if (step === 'wait-for-app') {
+      const deadline = now() + waitMs
+      let up = false
+      while (!up) {
+        up = await answered()
+        if (up) break
+        if (now() >= deadline) return { launched: true, reason: 'app-started-not-answering' }
+        await sleep(pollMs)
+      }
+    } else if (step === 'url') {
+      if (await handLink(uri)) continue
+      if (started) return { launched: true, reason: 'app-started-link-not-taken' }
+      if (!(await osOpen(uri))) return { launched: false, reason: 'os-open-failed' }
+      reason = 'os-open-accepted'
+    } else if (step === 'url-start') {
+      if (!(await osOpen(uri))) return { launched: false, reason: 'os-open-failed' }
+      reason = 'os-open-accepted'
+    }
+  }
+  return { launched: true, reason: started && reason === 'url-accepted' ? 'plain-start-then-url' : reason }
+}

package/src/runtime/obsidian/lifecycle.mjs

@@ -2,15 +2,17 @@ import childProcess from 'node:child_process'
 import { randomBytes as cryptoRandomBytes } from 'node:crypto'
 import fs from 'node:fs'
 import net from 'node:net'
+import path from 'node:path'
+import { compareAppVersions } from './app-capability.mjs'
 import { isoTime } from './documents.mjs'
-import { refuse } from './errors.mjs'
+import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { ensureWorkspaceIdentity } from './machine-settings.mjs'
 import { acquirePrivateGenerationLock, createAbandonmentProof, isProcessAlive } from './private-lock.mjs'
 import { processRunsRecordedExecutable } from './process-identity.mjs'
 import { DEFAULT_PROBE_TIMEOUT_MS, LOOPBACK_HOSTS, probeHealth, requestLoopback } from './service-client.mjs'
 import { SERVICE_ENTRY_PATH } from './service-entry-path.mjs'
 import {
-  CONSENT_COVERAGES, SERVICE_SETTINGS_SCHEMA, executableIdentity, openServiceLog, publicRecord, readServiceRecord, readServiceSettings, removeServiceRecord,
+  CONSENT_COVERAGES, SERVICE_SETTINGS_SCHEMA, executableIdentity, openServiceLog, publicRecord, readServiceRecord, readServiceSettings, releaseIdentity, removeServiceRecord,
   serviceNameFor, servicePaths, writeServiceSettings,
 } from './service-record.mjs'
 import { resolveServiceWorkspace } from './service.mjs'
@@ -162,8 +164,9 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
     const log = openServiceLog(workspaceRoot)
     try {
       const args = [executable.path, `--project=${project.configPath}`, ...(dataRoot === undefined ? [] : [`--data-root=${dataRoot}`]), `--runtime-id=${runtimeId}`, ...(intervalMs === undefined ? [] : [`--interval-ms=${intervalMs}`]), ...entryArgs]
-      // No shell. Detached only when the service is meant to outlive the command that starts it.
-      child = spawn(execPath, args, { detached, shell: false, windowsHide: true, stdio: ['ignore', log.descriptor, log.descriptor], env })
+      // No shell. Detached only when the service is meant to outlive the command that starts it. It runs in the root
+      // directory, never in the one the command was started in, which may be a vault or a folder somebody removes.
+      child = spawn(execPath, args, { detached, shell: false, windowsHide: true, stdio: ['ignore', log.descriptor, log.descriptor], env, cwd: path.parse(executable.path).root })
     } finally {
       fs.closeSync(log.descriptor)
     }
@@ -226,26 +229,114 @@ export async function stopService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
 
 // One authenticated request to the proven runtime, and to nothing else: anything but a healthy status is answered
 // with that status and no request is made.
-async function askProvenRuntime(options, rules, { method, operation, timeoutMs }) {
+async function askProvenRuntime(options, rules, { method, operation, timeoutMs, body = {} }) {
   const { loadProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
   const { workspace } = context({ loadProject, dataRoot, env, platform })
   if (!workspace?.workspaceRoot) return { requested: false, state: 'stopped', reason: 'workspace-not-prepared' }
   const status = await evaluate(workspace, { probeTimeoutMs, alive, rules })
   if (status.state !== 'healthy') return { requested: false, state: status.state, reason: status.reason }
   const { record } = status
-  const answer = await requestLoopback({ host: record.host, port: record.port, method, path: operation, bearer: record.ext.bearer, payload: method === 'POST' ? { runtimeId: record.runtimeId } : null, timeoutMs })
-  return { requested: true, state: 'healthy', answer }
+  const answer = await requestLoopback({ host: record.host, port: record.port, method, path: operation, bearer: record.ext.bearer, payload: method === 'POST' ? { runtimeId: record.runtimeId, ...body } : null, timeoutMs })
+  return { requested: true, state: 'healthy', answer, runtimeId: record.runtimeId }
+}
+
+// Pure. How the release a runtime recorded at its start (`executable.ext.release`, see releaseIdentity: the package
+// version and a digest of every runtime module) stands to the installed one, `installed` being { entry, release }, the
+// digest of the entry this command would start and releaseIdentity():
+//   current   the same version, entry module and modules;
+//   outdated  an earlier version; the same version with another entry module or other modules; or no release named,
+//             as releases before the one that began recording it record none;
+//   later     a later version, or another version that cannot be ordered. The installed release never replaces it, so two
+//             installations used on one workspace do not replace each other's runtime.
+// Versions are ordered as semantic versions, a prerelease below its release (0.2.0-alpha.11 < 0.2.0-alpha.12 < 0.2.0).
+export function releaseStanding(executable, installed) {
+  const recorded = executable?.ext?.release
+  if (recorded === undefined || recorded === null) return 'outdated'
+  // The same version string is compared by content, whether or not it can be ordered: a fork's "dev" on both sides
+  // is this release when its modules match, and outdated otherwise, never later.
+  const order = recorded.version === installed.release.version ? 0 : compareAppVersions(recorded.version, installed.release.version)
+  if (order === null || order > 0) return 'later'
+  if (order < 0) return 'outdated'
+  return executable.digest === installed.entry && recorded.digest === installed.release.digest ? 'current' : 'outdated'
+}
+
+// How the release the proven runtime runs stands to the installed one (releaseStanding), `entryPath` being the entry
+// this command would start. Null when the runtime is not proven, or the installed side cannot be read.
+export function runtimeRelease(status, entryPath) {
+  if (status?.state !== 'healthy' || typeof status.record?.executable?.digest !== 'string' || typeof entryPath !== 'string') return null
+  let installed
+  try { installed = { entry: executableIdentity(entryPath).digest, release: releaseIdentity() } } catch { return null }
+  return releaseStanding(status.record.executable, installed)
+}
+
+// Stops the proven runtime of this workspace through its own listener and starts `entryPath` in its place, detached,
+// under the consent already recorded. Only a runtime that proves itself ours is ever stopped (stopService).
+// { ok: true } or { ok: false, state, reason }.
+async function restartProvenRuntime(options, rules) {
+  const { consent: _given, ...rest } = options
+  const stopped = await stopService(rest, rules)
+  if (!stopped.stopped) return { ok: false, state: stopped.state, reason: stopped.reason ?? 'the-runtime-was-not-stopped' }
+  let started
+  try { started = await startService({ ...rest, detached: true }, rules) } catch (error) {
+    if (!(error instanceof ObsidianMaintenanceRefusal)) throw error
+    return { ok: false, state: 'stopped', reason: error.code }
+  }
+  if (started.state === 'healthy') return { ok: true }
+  return { ok: false, state: started.state, reason: started.state === 'busy' ? 'restarted-service-in-its-first-tick' : started.reason ?? started.state }
 }
 
 // Asks the proven runtime for one tick now and returns what that tick reported. A tick that outlasts the wait is
-// `pending`, not an error.
+// `pending`, not an error. With `scopeId`, that view is prepared and published once more on the tick.
+//
+// `service`, the start options of the entry this command would start ({ entryPath, entryArgs, ... }), lets an
+// outdated runtime be replaced: one that runs an earlier release (runtimeRelease) is restarted before it is asked,
+// and one that refuses a tick naming a view (a runtime of 0.2.0-alpha.11 or earlier, which knows no view in a tick)
+// is restarted and asked again, each time under the consent already recorded (`restarted: 'outdated'`). A listener
+// of now refuses a tick only when it names another runtime: when a concurrent command replaced the runtime between
+// the check and the request, the one that took its place is asked, and nothing is restarted. A runtime of a later
+// release is never replaced by this one, nor asked: `service-other-release`. Without `service`, an outdated runtime
+// is only reported (`service-outdated`). `runtimeId` names the runtime that answered, or the one left running.
 export async function requestServiceTick(options = {}, rules = LIFECYCLE_PRIMITIVES) {
-  const asked = await askProvenRuntime(options, rules, { method: 'POST', operation: '/tick', timeoutMs: options.tickTimeoutMs ?? 60 * 1000 })
-  if (!asked.requested) return asked
-  const { answer } = asked
-  if (answer.kind === 'timeout') return { requested: true, state: 'healthy', pending: true, tick: null, reason: 'tick-still-running' }
-  if (answer.kind !== 'response' || answer.statusCode !== 200 || answer.body === null) return { requested: true, state: 'healthy', pending: false, tick: null, reason: 'tick-was-not-answered' }
-  return { requested: true, state: 'healthy', pending: false, tick: answer.body, reason: 'tick-ran' }
+  const { service = null, scopeId } = options
+  const ask = () => askProvenRuntime(options, rules, { method: 'POST', operation: '/tick', timeoutMs: options.tickTimeoutMs ?? 60 * 1000, ...(scopeId === undefined ? {} : { body: { scopeId } }) })
+  let restarted = null
+  const restart = async () => {
+    const renewed = await restartProvenRuntime({ ...options, ...service }, rules)
+    if (renewed.ok || renewed.reason === 'restarted-service-in-its-first-tick') restarted = 'outdated'
+    return renewed.ok ? null : { requested: false, state: renewed.state, reason: renewed.reason, ...(restarted === null ? {} : { restarted }) }
+  }
+  const later = (status) => ({ requested: false, state: 'healthy', runtimeId: status.record.runtimeId, reason: 'service-other-release' })
+  const replaces = typeof service?.entryPath === 'string'
+  if (replaces) {
+    const status = await serviceStatus(options, rules)
+    const standing = runtimeRelease(status, service.entryPath)
+    if (standing === 'later') return later(status)
+    if (standing === 'outdated') {
+      const failed = await restart()
+      if (failed) return failed
+    }
+  }
+  let asked = await ask()
+  const refusesView = () => asked.requested && scopeId !== undefined && asked.answer.kind === 'response' && asked.answer.statusCode === 409
+  if (refusesView() && replaces && restarted === null) {
+    // The record is read again first: a runtime that took this one's place meanwhile is asked, not replaced.
+    const now = await serviceStatus(options, rules)
+    if (now.state === 'healthy' && now.record?.runtimeId !== asked.runtimeId) asked = await ask()
+    if (refusesView()) {
+      if (runtimeRelease(now, service.entryPath) === 'later') return later(now)
+      const failed = await restart()
+      if (failed) return failed
+      asked = await ask()
+    }
+  }
+  const shown = restarted === null ? {} : { restarted }
+  if (!asked.requested) return { ...asked, ...shown }
+  const { answer, runtimeId } = asked
+  const base = { requested: true, state: 'healthy', runtimeId, ...shown }
+  if (refusesView()) return { ...base, pending: false, tick: null, reason: 'service-outdated' }
+  if (answer.kind === 'timeout') return { ...base, pending: true, tick: null, reason: 'tick-still-running' }
+  if (answer.kind !== 'response' || answer.statusCode !== 200 || answer.body === null) return { ...base, pending: false, tick: null, reason: 'tick-was-not-answered' }
+  return { ...base, pending: false, tick: answer.body, reason: 'tick-ran' }
 }
 
 // The status document of the proven runtime: loop, last tick, last error code, freshness summary and, where the