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

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

@@ -0,0 +1,174 @@
+import { createHmac } from 'node:crypto'
+
+// The channel between Atelier's own plugin, inside a vault Atelier manages,
+// and the maintenance service of the workspace that manages that vault.
+//
+// A closed command surface over the service's literal loopback listener:
+//
+//   POST /plugin/challenge  a fresh nonce and the time it was made, and a hint
+//                           at which vault's key it means that only the holder
+//                           of that key can read; the service answers, once
+//                           and only while it is fresh, with its own nonce and
+//                           a proof that it holds the key
+//   POST /plugin/hello      only after the plugin checked that proof: its own
+//                           proof, the plugin and app versions, an id of this
+//                           launch of the plugin, and a proof of the vault path
+//                           the app has open (the path itself is never sent)
+//   POST /plugin/lease      "this vault is open in an app", renewed every two
+//                           seconds; it lapses on its own six seconds later
+//   POST /plugin/release    the vault closed, or the plugin unloaded
+//   POST /plugin/status     freshness, reason and held edits of this view
+//
+// The key is the vault's bearer, which Atelier writes into the plugin's data
+// file of that vault only and keeps in private state. It never crosses the
+// wire, and neither does anything that names the view or the vault before the
+// listener proved it holds the key: a program squatting the service's port
+// while the service is down learns a nonce and a hint it cannot link to a
+// vault, and cannot answer. Both proofs bind the listener's exact address, so
+// an answer relayed from a service listening elsewhere does not verify.
+//
+// A challenge recorded by such a program and sent to the service later is
+// worth little: the service answers a challenge only within thirty seconds of
+// the time it names, and a nonce only once, and at most four handshakes wait
+// for their hello per view, so one view's challenges never hold up another's.
+//
+// The handshake derives a key for one session. Every later request carries
+// the session, a counter that only goes up, and a MAC over both and the
+// command under that key; every answer carries a MAC over the request's counter
+// and the exact bytes of the answer. A handshake is used once and lapses after
+// five seconds, a session after fifteen minutes. Nothing here takes a path to
+// act on, a command or code, and every command maps to state the service
+// already keeps (see docs/obsidian-plugin.md).
+//
+// The plugin cannot import this module: it runs inside the app, from the
+// vault. It carries the same constants and the same computations, and the test
+// suite holds the two to each other: a plugin that computes any one of them
+// otherwise cannot complete a handshake.
+
+export const PLUGIN_ID = 'atelier-projection'
+export const PLUGIN_DIRECTORY = `.obsidian/plugins/${PLUGIN_ID}`
+// Shipped with the package under plugins/obsidian/ and copied into every vault unchanged.
+export const PLUGIN_SOURCE_FILES = Object.freeze(['manifest.json', 'main.js', 'styles.css'])
+// Written per vault: the channel address and that vault's bearer.
+export const PLUGIN_DATA_FILE = 'data.json'
+export const PLUGIN_DATA_PATH = `${PLUGIN_DIRECTORY}/${PLUGIN_DATA_FILE}`
+// The data file holds the vault's key: only the person who runs the vault reads it. The app reads the others.
+export const PLUGIN_DATA_MODE = 0o600
+export const PLUGIN_SOURCE_MODE = 0o644
+
+export const PLUGIN_CHANNEL_PROTOCOL = 'atelier-obsidian-plugin-channel/v2'
+export const PLUGIN_DATA_SCHEMA = 'atelier-obsidian-plugin-data/v1'
+export const PLUGIN_STATUS_SCHEMA = 'atelier-obsidian-plugin-status/v1'
+
+export const PLUGIN_COMMANDS = Object.freeze(['challenge', 'hello', 'lease', 'release', 'status'])
+export const PLUGIN_ROUTES = Object.freeze(Object.fromEntries(PLUGIN_COMMANDS.map((command) => [command, `/plugin/${command}`])))
+export const PLUGIN_REQUEST_FIELDS = Object.freeze({
+  challenge: Object.freeze(['protocol', 'keyHint', 'clientNonce', 'issuedAt']),
+  hello: Object.freeze(['handshakeId', 'pluginVersion', 'appVersion', 'instanceId', 'vaultProof', 'clientProof']),
+  lease: Object.freeze(['sessionId', 'counter', 'mac']),
+  release: Object.freeze(['sessionId', 'counter', 'mac']),
+  status: Object.freeze(['sessionId', 'counter', 'mac']),
+})
+
+export const PLUGIN_MAX_REQUEST_BYTES = 1024
+export const PLUGIN_RENEW_INTERVAL_MS = 2000
+// Three renewals may be missed before a vault stops counting as open.
+export const PLUGIN_LEASE_TTL_MS = 3 * PLUGIN_RENEW_INTERVAL_MS
+export const PLUGIN_MAX_SESSIONS_PER_SCOPE = 8
+export const PLUGIN_HANDSHAKE_TTL_MS = 5000
+// A challenge is answered only this close to the time it names (both sides read one machine's clock).
+export const PLUGIN_CHALLENGE_WINDOW_MS = 30 * 1000
+export const PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE = 4
+// A session key is short-lived: the plugin shakes hands again after this long.
+export const PLUGIN_MAX_SESSION_AGE_MS = 15 * 60 * 1000
+// The app version the plugin needs, the floor of the publication protocol (app-capability.mjs).
+export const PLUGIN_MINIMUM_APP_VERSION = '1.13.7'
+
+export const PLUGIN_BEARER = /^[A-Za-z0-9_-]{43}$/
+export const PLUGIN_NONCE = /^[0-9a-f]{64}$/
+// A key hint, a proof and a MAC are each one HMAC-SHA256, in hex.
+export const PLUGIN_MAC = /^[0-9a-f]{64}$/
+export const PLUGIN_HANDSHAKE_ID = /^ph-[0-9a-f]{32}$/
+export const PLUGIN_SESSION_ID = /^ps-[0-9a-f]{32}$/
+export const PLUGIN_INSTANCE_ID = /^pi-[0-9a-f]{32}$/
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const VERSION_TEXT = /^[0-9A-Za-z.+-]{1,40}$/
+const LOOPBACK_HOSTS = Object.freeze(['127.0.0.1', '::1'])
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The route of a request path, or null. Exact paths only: no query, no prefix.
+export function pluginCommandOf(requestPath) {
+  return PLUGIN_COMMANDS.find((command) => PLUGIN_ROUTES[command] === requestPath) ?? null
+}
+
+// { ok: true, body } or { ok: false, code }. The body has exactly the fields
+// of its command, each of its own shape; anything else refuses.
+export function validatePluginRequest(command, body) {
+  const fields = PLUGIN_REQUEST_FIELDS[command]
+  if (fields === undefined) return { ok: false, code: 'unknown-command' }
+  if (!isPlainObject(body)) return { ok: false, code: 'request-malformed' }
+  const keys = Object.keys(body)
+  if (keys.length !== fields.length || !fields.every((field) => Object.hasOwn(body, field))) return { ok: false, code: 'request-malformed' }
+  const shaped = (field, pattern) => typeof body[field] === 'string' && pattern.test(body[field])
+  if (command === 'challenge') {
+    if (body.protocol !== PLUGIN_CHANNEL_PROTOCOL) return { ok: false, code: 'protocol-unsupported' }
+    if (!shaped('keyHint', PLUGIN_MAC) || !shaped('clientNonce', PLUGIN_NONCE) || !Number.isSafeInteger(body.issuedAt) || body.issuedAt < 1) return { ok: false, code: 'request-malformed' }
+  } else if (command === 'hello') {
+    if (!shaped('handshakeId', PLUGIN_HANDSHAKE_ID) || !shaped('instanceId', PLUGIN_INSTANCE_ID) || !shaped('vaultProof', PLUGIN_MAC) || !shaped('clientProof', PLUGIN_MAC)) return { ok: false, code: 'request-malformed' }
+    if (!shaped('pluginVersion', VERSION_TEXT) || !shaped('appVersion', VERSION_TEXT)) return { ok: false, code: 'request-malformed' }
+  } else if (!shaped('sessionId', PLUGIN_SESSION_ID) || !shaped('mac', PLUGIN_MAC) || !Number.isSafeInteger(body.counter) || body.counter < 1) {
+    return { ok: false, code: 'request-malformed' }
+  }
+  return { ok: true, body }
+}
+
+// The computations of the handshake and the session, shared with the plugin.
+// Every input but a vault path is one of the shapes above, without a line
+// break, and a vault path is the only input of its computation, so joining
+// them by lines is unambiguous. `key` is the vault's bearer text, or a
+// session key.
+const transcript = (label, fields) => [PLUGIN_CHANNEL_PROTOCOL, label, ...fields.map(String)].join('\n')
+const hmac = (key, label, fields) => createHmac('sha256', key).update(transcript(label, fields), 'utf8').digest()
+const hmacHex = (key, label, fields) => hmac(key, label, fields).toString('hex')
+
+// A hint at the vault's key, fresh with every nonce and bound to the time the
+// challenge names: the service finds the key it names by computing it for each
+// key it holds, and a listener that holds none cannot tell two hints of one
+// vault apart, nor move one to another time.
+export const pluginKeyHint = ({ bearer, clientNonce, issuedAt }) => hmacHex(bearer, 'key-hint', [clientNonce, issuedAt])
+// What binds a handshake: the view, the listener's exact address, both nonces and the handshake.
+const handshakeFields = ({ scopeId, authority, clientNonce, serverNonce, handshakeId }) => [scopeId, authority, clientNonce, serverNonce, handshakeId]
+export const pluginServerProof = (input) => hmacHex(input.bearer, 'server-proof', handshakeFields(input))
+export const pluginSessionKey = (input) => hmac(input.bearer, 'session-key', handshakeFields(input))
+// The vault the app has open, proven under the session key rather than named.
+export const pluginVaultProof = ({ sessionKey, vaultPath }) => hmacHex(sessionKey, 'vault', [vaultPath])
+export const pluginClientProof = (input) => hmacHex(input.bearer, 'client-proof', [...handshakeFields(input), input.pluginVersion, input.appVersion, input.instanceId, input.vaultProof])
+export const pluginRequestMac = ({ sessionKey, command, sessionId, counter }) => hmacHex(sessionKey, 'request', [command, sessionId, counter])
+// An answer is the exact text of its JSON document and a MAC over it, the command and the request's counter.
+export const pluginResponseMac = ({ sessionKey, command, sessionId, counter, payload }) => hmacHex(sessionKey, 'response', [command, sessionId, counter, payload])
+
+// The plugin's data file of one vault: where the service listens and the
+// bearer of this vault. Canonical bytes, so an unchanged channel republishes
+// nothing.
+export function pluginDataDocument({ host, port, scopeId, bearer }) {
+  const document = { schema: PLUGIN_DATA_SCHEMA, channel: { host, port }, scopeId, bearer }
+  if (validatePluginData(document) === null) throw new TypeError('the plugin data needs a literal loopback address, a port, a view and a bearer')
+  return document
+}
+
+export function pluginDataBytes(input) {
+  const { schema, channel, scopeId, bearer } = pluginDataDocument(input)
+  return Buffer.from(`${JSON.stringify({ schema, channel: { host: channel.host, port: channel.port }, scopeId, bearer }, null, 2)}\n`, 'utf8')
+}
+
+// The document when it is exactly a plugin data document, else null.
+export function validatePluginData(document) {
+  if (!isPlainObject(document) || Object.keys(document).sort().join(',') !== 'bearer,channel,schema,scopeId') return null
+  if (document.schema !== PLUGIN_DATA_SCHEMA || typeof document.scopeId !== 'string' || !IDENTIFIER.test(document.scopeId)) return null
+  if (typeof document.bearer !== 'string' || !PLUGIN_BEARER.test(document.bearer)) return null
+  const { channel } = document
+  if (!isPlainObject(channel) || Object.keys(channel).sort().join(',') !== 'host,port') return null
+  if (!LOOPBACK_HOSTS.includes(channel.host) || !Number.isInteger(channel.port) || channel.port < 1024 || channel.port > 65535) return null
+  return document
+}

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

@@ -0,0 +1,10 @@
+// Atelier's own Obsidian plugin: the channel it speaks and the files that put
+// it into a vault. The plugin source ships under plugins/obsidian/.
+export {
+  PLUGIN_BEARER, PLUGIN_CHALLENGE_WINDOW_MS, PLUGIN_CHANNEL_PROTOCOL, PLUGIN_COMMANDS, PLUGIN_DATA_FILE, PLUGIN_DATA_PATH, PLUGIN_DATA_SCHEMA, PLUGIN_DIRECTORY, PLUGIN_HANDSHAKE_ID, PLUGIN_HANDSHAKE_TTL_MS,
+  PLUGIN_ID, PLUGIN_INSTANCE_ID, PLUGIN_LEASE_TTL_MS, PLUGIN_MAC, PLUGIN_MAX_PENDING_HANDSHAKES_PER_SCOPE, PLUGIN_MAX_REQUEST_BYTES, PLUGIN_MAX_SESSION_AGE_MS, PLUGIN_MAX_SESSIONS_PER_SCOPE,
+  PLUGIN_MINIMUM_APP_VERSION, PLUGIN_NONCE, PLUGIN_RENEW_INTERVAL_MS, PLUGIN_REQUEST_FIELDS, PLUGIN_ROUTES, PLUGIN_SESSION_ID, PLUGIN_SOURCE_FILES,
+  PLUGIN_STATUS_SCHEMA, pluginClientProof, pluginCommandOf, pluginDataBytes, pluginDataDocument, pluginKeyHint, pluginRequestMac, pluginResponseMac, pluginServerProof, pluginSessionKey,
+  pluginVaultProof, validatePluginData, validatePluginRequest,
+} from './channel.mjs'
+export { PLUGIN_DATA_MODE, PLUGIN_SOURCE_MODE, PLUGIN_SOURCE_ROOT, preparePluginFiles, readPluginSource } from './bundle.mjs'

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

@@ -6,7 +6,7 @@ import { AtelierDiagnosticError } from '../../../project/config.mjs'
 import { compareText, isoTime } from '../../../runtime/obsidian/documents.mjs'
 import { ObsidianMaintenanceRefusal } from '../../../runtime/obsidian/errors.mjs'
 import { readMachineSettings } from '../../../runtime/obsidian/machine-settings.mjs'
-import { DEFAULT_ELIGIBILITY, createProductionSeams } from '../../../runtime/obsidian/pipeline.mjs'
+import { createProductionSeams, eligibilityFor } from '../../../runtime/obsidian/pipeline.mjs'
 import { acquirePrivateGenerationLock, createAbandonmentProof } from '../../../runtime/obsidian/private-lock.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../contracts.mjs'
 import { SOURCE_APPLY_PRIMITIVES } from '../edits/apply.mjs'
@@ -15,6 +15,7 @@ import { isIdentifier } from '../edits/object-identity.mjs'
 import { openObjectStore } from '../edits/object-store.mjs'
 import { decideApply } from '../edits/policy.mjs'
 import { applyEditLens } from '../edits/regions.mjs'
+import { PERSONAL_VALIDATION_PENDING, personalOverlayRepoOf } from '../personal-workspace.mjs'
 import { PublicationRefusal } from '../recovery/store.mjs'
 import {
   PROPOSAL_BACKPRESSURE, PROPOSAL_LEDGER_LIMITS, classifyLedgerRead, classifyStoreRefusal, estimateEventLineBytes, isDue, isExhausted, nextAttemptAt, preflightAppend,
@@ -168,7 +169,7 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
   // two questions asked of the machine; `proveAbandoned` is the proof a held lock is passed over with.
   return function createProposalAdapter(options = {}) {
     const {
-      crash = () => {}, bounds: boundsInput = {}, limits = PROPOSAL_LEDGER_LIMITS, eligibility = DEFAULT_ELIGIBILITY,
+      crash = () => {}, bounds: boundsInput = {}, limits = PROPOSAL_LEDGER_LIMITS, eligibility: fixedEligibility = null,
       openStore = createProposalStore, objectStore = openObjectStore, isGitIgnored = SOURCE_APPLY_PRIMITIVES.isGitIgnored, proveAbandoned = createAbandonmentProof(), queueCrash = () => {},
     } = options
     const bounds = { ...PROPOSAL_BACKPRESSURE, ...boundsInput }
@@ -184,6 +185,9 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
     let observation = { key: null, run: null }
     // Edits whose operation is known not to be a proposal. A cache: losing it costs one read of an object.
     const notProposals = new Set()
+    // Set when an observation found the personal workspace's graph pending: the edits it could not look at are offered
+    // again on the next observation, not parked until a full reconciliation.
+    let observePendingAgain = false
 
     // -- the workspace of one call -------------------------------------------
 
@@ -198,12 +202,31 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         if (!stores.has(scopeId)) stores.set(scopeId, seams.createRecoveryStore({ workspaceRoot, workspaceId, scopeId, repositoryRoots }))
         return stores.get(scopeId)
       }
-      // The canonical graph as it is now and the corpus profile of this machine, built once per call. Throws typed.
+      // The canonical graph as it is now and the corpus profile of this machine, built once per call with the notes the
+      // machine settings let into a view, as the engine builds it (eligibilityFor). Throws typed.
       let corpus = null
-      const currentCorpus = () => (corpus ??= {
-        graph: seams.buildGraph({ project, eligibility }),
-        profile: seams.profileFor({ project, workspaceId, audienceAllow: readMachineSettings({ workspaceRoot, workspaceId })?.audienceAllow ?? [] }),
-      })
+      // A pending answer is kept for the call too, so a call that looks at several edits builds at most once.
+      let pendingCorpus = null
+      const currentCorpus = () => {
+        if (corpus !== null) return corpus
+        if (pendingCorpus !== null) throw pendingCorpus
+        const machine = readMachineSettings({ workspaceRoot, workspaceId })
+        corpus = {
+          // The engine hands its deferral over: a personal workspace is then never composed on its event loop here.
+          graph: (() => {
+            try { return seams.buildGraph({ project, eligibility: fixedEligibility ?? eligibilityFor({ machine, project }), deferPersonalValidation: context.deferPersonalValidation === true }) } catch (error) {
+              if (error?.code === PERSONAL_VALIDATION_PENDING) pendingCorpus = error
+              throw error
+            }
+          })(),
+          profile: seams.profileFor({ project, workspaceId, audienceAllow: machine?.audienceAllow ?? [] }),
+        }
+        return corpus
+      }
+      // Whether the personal workspace's graph is pending on this call. Asked only where a graph would be built anyway.
+      const personalPending = () => {
+        try { currentCorpus(); return false } catch (error) { if (error?.code === PERSONAL_VALIDATION_PENDING) return true; if (isTyped(error)) return false; throw error }
+      }
       // true, false, or null when the canonical graph cannot be read now. The rule is the one source apply asks.
       const visible = options.isVisible ? (identity) => options.isVisible(identity, context) : ({ repoId, nodeId }) => {
         let built
@@ -223,6 +246,7 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       return {
         ...context, recoveryOf, visible, clock, env: env ?? context.env ?? process.env,
         corpus: currentCorpus,
+        personalPending,
         objects: () => (objects ??= objectStore({ stateRoot: workspaceRoot, workspaceId, repositoryRoots, clock })),
         queue,
         managedRoots: () => [workspaceRoot, ...[...stores.values()].map((store) => store.vaultRoot)],
@@ -304,6 +328,8 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         if (requireOpenEdit && editState !== 'open') return known ? refused(`edit-${editState}`) : outcome('skipped', null, { code: `edit-${editState}` })
         // The object store no longer says this is a proposed structural edit, so there is nothing to describe.
         if (item.observed === null) return refused('operation-not-proposed')
+        // A personal workspace whose graph is pending leaves the operation as it is: no attempt is spent on this tick.
+        if (workspace.deferPersonalValidation === true && personalOverlayRepoOf(workspace.project) !== null && workspace.personalPending()) return outcome('deferred', history?.head ?? null, { code: PERSONAL_VALIDATION_PENDING })
         const resolved = resolveProposalRoute({ project: workspace.project, workspaceId: workspace.workspaceId, identity: item, sourcePath: item.sourcePath, managedRoots: workspace.managedRoots(), isVisible: workspace.visible, isGitIgnored, env: env ?? workspace.env ?? process.env })
         if (!resolved.ok && !resolved.transient) return refused(resolved.code)
         // Recorded before anything is asked of the store.
@@ -432,7 +458,20 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       async observe(context, { retryRefused = false } = {}) {
         const workspace = open(context)
         const edits = Array.isArray(context.edits) ? context.edits : []
-        return { adapterId: PROPOSAL_ADAPTER_ID, observed: observation.run(workspace, { edits, retryRefused }) }
+        // A private note of a personal workspace lives in a generation the personal-workspace module owns: its edit is
+        // not observed, recorded or proposed, and stays held in the vault. Answered by name, with nothing written.
+        const overlayRepoId = personalOverlayRepoOf(workspace.project)
+        const isPrivate = (edit) => overlayRepoId !== null && edit?.identity?.repoId === overlayRepoId
+        const privateNotes = edits.filter((edit) => isPrivate(edit) && edit.closedAt === null)
+          .map((edit) => ({ editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, status: 'refused', code: 'personal-overlay-not-proposed' }))
+        const shared = edits.filter((edit) => !isPrivate(edit))
+        // The graph is built only when an edit is looked at, as for any project. When the personal workspace's graph is
+        // pending, the edits it reached are not reported or recorded, and are offered again on the next observation.
+        const retry = retryRefused || observePendingAgain
+        const looked = observation.run(workspace, { edits: shared, retryRefused: retry })
+        const pending = looked.filter((item) => item.code === PERSONAL_VALIDATION_PENDING)
+        observePendingAgain = pending.length > 0
+        return { adapterId: PROPOSAL_ADAPTER_ID, observed: [...privateNotes, ...looked.filter((item) => item.code !== PERSONAL_VALIDATION_PENDING)], ...(pending.length > 0 ? { deferred: PERSONAL_VALIDATION_PENDING } : {}) }
       },
 
       // The tick. `context` is { project, workspaceRoot, workspaceId, repositoryRoots, edits }: the pending edit

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

@@ -5,7 +5,7 @@ import { compareText, isoTime } from '../../../runtime/obsidian/documents.mjs'
 import { readObsidianEnablement } from '../../../runtime/obsidian/enablement.mjs'
 import { ObsidianMaintenanceRefusal } from '../../../runtime/obsidian/errors.mjs'
 import { OPEN_EDIT_STATES, createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
-import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal } from '../contracts.mjs'
+import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, manifestLayoutVersion } from '../contracts.mjs'
 import { SOURCE_APPLY_PRIMITIVES, SourceApplyRefusal, locateSource } from '../edits/apply.mjs'
 import { EditArbitrationRefusal } from '../edits/arbitrate.mjs'
 import { createEditObserverForOracleTests, editIdempotencyKey, observeEdit } from '../edits/observe.mjs'
@@ -126,22 +126,35 @@ export function createTickObservation(options = {}) {
   // The note exactly as it was published, which the lens needs to tell generated bytes from authored ones. The
   // publisher keeps no copy of a note it created, so the note is prepared again from the sources as they are now and
   // used only when it has the digest the manifest recorded; a retained object of that digest serves as well.
+  //
+  // A source replaced between the look at its path and its open (ELEAFCHANGED) is another program writing it, as it
+  // is to the publisher and to source apply: the preparation answers null, and the caller reads the source again and
+  // refuses stale-source when it changed. Only a preparation that succeeded is kept for its scope and generation: one
+  // failure tells of one moment and is never the answer for the other edits of that generation in the tick.
   function publishedNoteOf(workspace, { scope, manifest, noteEntry }, now) {
     const store = workspace.recoveryOf(scope.scopeId)
     const kept = retained(store, noteEntry.noteDigest)
     if (kept) return kept
     workspace.prepared ??= new Map()
-    if (!workspace.prepared.has(scope.scopeId)) {
-      let files = []
+    // Prepared in the vault layout of the edit's generation, once per generation.
+    const preparedKey = `${scope.scopeId}\u0000${manifest.generationId}`
+    if (!workspace.prepared.has(preparedKey)) {
+      let files
       try {
         const { graph, profile } = workspace.corpus()
         const snapshot = seams.captureSnapshot({ project: workspace.project, graph, workspaceId: workspace.workspaceId, index: new Map(), configDigest: manifest.ext?.[EXT]?.configDigest ?? `sha256:${'0'.repeat(64)}`, capturedAt: now })
         const persistentPathRegistry = createMaintenanceStateStore({ workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId }).readPathRegistry()
-        files = seams.prepareView({ snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock, vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8') }).files
-      } catch (error) { if (!isTyped(error) && !GONE.has(error?.code)) throw error }
-      workspace.prepared.set(scope.scopeId, files)
+        files = seams.prepareView({
+          snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock,
+          vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8'), layout: manifestLayoutVersion(manifest),
+        }).files
+      } catch (error) {
+        if (!isTyped(error) && error?.code !== 'ELEAFCHANGED' && !GONE.has(error?.code)) throw error
+        return null
+      }
+      workspace.prepared.set(preparedKey, files)
     }
-    const file = workspace.prepared.get(scope.scopeId).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)
+    const file = workspace.prepared.get(preparedKey).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)
     return file ? file.bytes : null
   }
 

package/src/projection/obsidian/publication/bridge-script.mjs

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module'
+import { PLUGIN_OWNED_PATHS, POLICY_SETTINGS_PATHS } from '../materialize/settings.mjs'
 import { EXCHANGE_CONSTANTS } from './exchange.mjs'
 
 // The fixed script that performs one conditional publication. It runs in two
@@ -26,11 +27,14 @@ const KEYS = {
 const isAbsolute = (value) => typeof value === 'string' && value.startsWith('/') && !value.includes('\u0000')
 
 // A vault-relative path the publisher may address: visible files only, plus
-// the one policy-owned settings file. Every other settings path is the
-// person's and cannot be named in a payload at all.
+// the settings Atelier owns (the two policy settings files and its own
+// plugin's files). Every other settings path is the person's and cannot be
+// named in a payload at all.
+const ATELIER_OWNED_SETTINGS = new Set([...POLICY_SETTINGS_PATHS, ...PLUGIN_OWNED_PATHS])
+
 export function isAddressableVaultPath(value) {
   if (typeof value !== 'string' || value.length === 0 || value.length > 1024 || value.startsWith('/') || value.includes('\\') || value.includes('\u0000')) return false
-  if (value === POLICY_SETTINGS_PATH) return true
+  if (ATELIER_OWNED_SETTINGS.has(value)) return true
   return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..' && !part.startsWith('.'))
 }
 
@@ -43,7 +47,7 @@ export function validatePayload(payload) {
   for (const key of Object.keys(payload)) if (!allowed.includes(key)) fail(`unknown key ${key}`)
   for (const key of allowed) if (payload[key] === undefined) fail(`missing key ${key}`)
   if (!isAbsolute(payload.vaultRoot)) fail('vaultRoot must be absolute')
-  if (!isAddressableVaultPath(payload.path)) fail('path must be a relative visible path or the policy settings file')
+  if (!isAddressableVaultPath(payload.path)) fail('path must be a relative visible path or a settings file Atelier owns')
   if (payload.op === 'publish') {
     if (!OPERATION_ID.test(payload.operationId)) fail('operationId required')
     if (!SHA.test(payload.baseSha256)) fail('baseSha256 required')
@@ -76,7 +80,9 @@ export function criticalSection(P, host) {
   const trace = []
   const step = (event, detail) => trace.push({ ms: Number((host.performance.now() - t0).toFixed(3)), event, ...(detail || {}) })
   const crash = (point) => { if (host.crashSeam && host.crashSeam.at === point) host.crashSeam.halt(point) }
-  const real = (target) => { try { return fs.realpathSync(target) } catch (error) { return null } }
+  // As the file system stores the path, except on Windows (see realPathAsStored): an app that holds the vault under
+  // another spelling of its folder (a letter case, on a volume that folds it) holds this vault.
+  const real = (target) => { try { return host.process.platform !== 'win32' && fs.realpathSync.native ? fs.realpathSync.native(target) : fs.realpathSync(target) } catch (error) { return null } }
   const vaultBasePath = app ? real(app.vault.adapter.getBasePath()) : real(P.vaultRoot)
   const full = nodePath.join(P.vaultRoot, P.path)
   const views = () => {

package/src/projection/obsidian/publication/index.mjs

@@ -1,5 +1,6 @@
 // Conditional publication of a prepared view into an editable Obsidian vault.
 export { PROTOCOL_ID, buildEvalCode, createInProcessHost, criticalSection, isAddressableVaultPath, runInProcess, validatePayload } from './bridge-script.mjs'
 export { EXCHANGE_CONSTANTS, ExchangeRefusal, exchangeFiles, probeExchange, resetExchangeProbeCache, resolveExchange } from './exchange.mjs'
-export { TransportTimeout, createDirectAdapter, createEditorAdapter, createInProcessCall, createObsidianCliAdapter, createObsidianCliCall, defaultCliPath, defaultObsidianProcessProbe } from './transport.mjs'
+export { NEUTRAL_DIRECTORY, TransportTimeout, createDirectAdapter, createEditorAdapter, createInProcessCall, createObsidianCliAdapter, createObsidianCliCall, defaultCliPath, defaultObsidianProcessProbe, publicationRoute } from './transport.mjs'
+export { MAX_OBSIDIAN_SETTINGS_BYTES, OBSIDIAN_SETTINGS_FILE, enclosingVaults, findVaultEntry, obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings, vaultRoute } from './vault-list.mjs'
 export { publishView } from './publisher.mjs'