@mnstry/atelier 0.2.0-alpha.14 → 0.2.0-alpha.16

package/src/readiness-protocols/runtime.mjs

@@ -1,6 +1,8 @@
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import formats from 'ajv-formats'
+import { canonicalize } from '../attestation/jcs.mjs'
 import { createProposalStore } from '../collaboration/proposals.mjs'
 import { readJson, writeJson } from '../project/config.mjs'
 import { bundledReadinessPack, bundledReadinessProtocols, protocolById } from './bundled-pack.mjs'
@@ -126,7 +128,40 @@ export function claimsForProtocolRun({ protocol, answers, projectName, runId, cr
   })
 }
 
+// createdAt is the existing run contract's date-time, rather than a filename or filesystem timestamp. Use the same
+// full-format validator as the schema and refuse values the host cannot place on a timeline (including leap seconds).
+const validCreatedAt = formats.get('date-time').validate
+function runInstant(createdAt) {
+  if (typeof createdAt !== 'string' || !validCreatedAt(createdAt)) throw new Error('invalid-readiness-run-created-at')
+  // Compare the whole second separately so fractions finer than a millisecond do not collapse into a false tie.
+  const fraction = /\.(\d+)/.exec(createdAt)?.[1] ?? ''
+  const wholeSecond = Date.parse(createdAt.replace(/\.\d+/, ''))
+  if (!Number.isFinite(wholeSecond)) throw new Error('invalid-readiness-run-created-at')
+  return { wholeSecond, fraction }
+}
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0
+function orderedProtocolRuns(runs) {
+  const seen = new Map()
+  return runs.map((run) => {
+    const instant = runInstant(run?.createdAt)
+    if (typeof run?.runId !== 'string' || !/^readiness-run-[a-f0-9]{24}$/.test(run.runId)) throw new Error('invalid-readiness-run-id')
+    const content = canonicalize(run)
+    if (seen.has(run.runId) && seen.get(run.runId) !== content) throw new Error('conflicting-readiness-run-id')
+    seen.set(run.runId, content)
+    return { run, ...instant }
+  }).sort((left, right) => {
+    const precision = Math.max(left.fraction.length, right.fraction.length)
+    return left.wholeSecond - right.wholeSecond
+      || compareText(left.fraction.padEnd(precision, '0'), right.fraction.padEnd(precision, '0'))
+      || compareText(left.run.runId, right.run.runId)
+  }).map(({ run }) => run)
+}
+function latestRunsByProtocol(runs) {
+  return new Map(orderedProtocolRuns(runs).map((run) => [run.protocolId, run]))
+}
+
 export function buildReadinessRun({ project, protocol, answers = {}, createdAt = nowIso() }) {
+  runInstant(createdAt)
   const normalizedAnswers = normalizeAnswers(protocol, answers)
   const evaluation = evaluateProtocolAnswers(protocol, normalizedAnswers)
   const seed = JSON.stringify({ project: project.config.name || path.basename(project.workspaceRoot), protocol: protocol.id, answers: normalizedAnswers, createdAt })
@@ -155,6 +190,7 @@ export function buildReadinessRun({ project, protocol, answers = {}, createdAt =
 }
 
 export function writeReadinessRun(project, run) {
+  runInstant(run?.createdAt)
   const dir = readinessRunsDir(project)
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
   const file = path.join(dir, `${run.runId}.json`)
@@ -188,7 +224,7 @@ export function createReadinessProposal(project, run) {
 export function listProtocolRuns(project) {
   const dir = readinessRunsDir(project)
   if (!fs.existsSync(dir)) return []
-  return fs.readdirSync(dir)
+  const runs = fs.readdirSync(dir)
     .filter((name) => name.endsWith('.json'))
     .sort()
     .map((name) => {
@@ -199,6 +235,7 @@ export function listProtocolRuns(project) {
       }
     })
     .filter(Boolean)
+  return orderedProtocolRuns(runs)
 }
 
 // Shared per-dimension facts derived from a stored run. Used by both the
@@ -222,8 +259,7 @@ function packProtocolRecords(registry) {
 }
 
 export function summarizeReadinessJourney(project, { runs = listProtocolRuns(project), registry = null } = {}) {
-  const runsByProtocol = new Map()
-  for (const run of runs) runsByProtocol.set(run.protocolId, run)
+  const runsByProtocol = latestRunsByProtocol(runs)
   const dimensions = DIMENSIONS.map(([key, label, protocolId]) => {
     const protocol = protocolById(protocolId)
     const facts = dimensionRunFacts(runsByProtocol.get(protocolId), protocolId)
@@ -281,8 +317,9 @@ function answersFor(run, key) {
 // the runtime and CLI tests instead; if it ever gets a schema, register it so
 // compat checking takes over.
 export function buildTenantPacket(project, { runs = listProtocolRuns(project), registry = null } = {}) {
-  const byId = new Map(runs.map((run) => [run.protocolId, run]))
-  const journey = summarizeReadinessJourney(project, { runs, registry })
+  const orderedRuns = orderedProtocolRuns(runs)
+  const byId = new Map(orderedRuns.map((run) => [run.protocolId, run]))
+  const journey = summarizeReadinessJourney(project, { runs: orderedRuns, registry })
   // Generic pack contribution: built entirely from run fields, no per-field
   // plucking (the literal byId.get(...) reads below stay bundled-only). Only
   // required-gate pack protocols can block export; advisory ones just report.
@@ -363,7 +400,7 @@ export function buildTenantPacket(project, { runs = listProtocolRuns(project), r
       ...packExportBlockers,
     ],
     openQuestions: answersFor(byId.get('mnstry.readiness:tenant-packet'), 'openQuestions') ?? [],
-    proposedClaims: runs.flatMap((run) => run.claims ?? []).map((claim) => claim.claimId),
+    proposedClaims: orderedRuns.flatMap((run) => run.claims ?? []).map((claim) => claim.claimId),
     ext: {
       'mnstry.atelier': {
         extensionPacks: packContribution,

package/src/runtime/obsidian/engine.mjs

@@ -12,11 +12,12 @@ import { readObsidianEnablement } from './enablement.mjs'
 import { ObsidianMaintenanceRefusal, refuse } from './errors.mjs'
 import { createMaintenanceExtensions } from './extension-points.mjs'
 import {
-  assertOutsideRepositories, authorizeAutomaticApply, defaultMachineSettings, ensureWorkspaceIdentity, protectedRoots, readLocalPointer,
-  readMachineSettings, resolveDataRoot, workspaceStateRoot, writeMachineSettings,
+  assertOutsideRepositories, authorizeAutomaticApply, ensureWorkspaceIdentity, initializeMachineSettings, protectedRoots, readLocalPointer,
+  readMachineSettings, resolveDataRoot, workspaceStateRoot,
 } from './machine-settings.mjs'
 import { configKey, hasIndexedHint, listConfigFiles, listSourceFiles, listVaultNotes, readFileFacts, reconcile, reconcileCooperatively, sha256Digest, sourceKey, vaultKey } from './observation.mjs'
 import { dispatchAutomaticApply, heldPaths, layoutHeldPaths, observeVaultEdits, preserveInRecoveryStore, trustedNoteBases } from './pending-edits.mjs'
+import { personalExclusionRootsNow } from './personal-selection.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'
@@ -107,7 +108,7 @@ export const ENGINE_PRIMITIVES = Object.freeze({
   observedAssetsOf: (graph) => (graph.assets ?? []).filter((asset) => asset.eligible === true).map(({ repo, path: assetPath }) => ({ repo, path: assetPath })),
   // A change the guard sees in the middle of a tick is read, where it may be a confirmed selection, while it is there.
   noteSelectionAtGuard: notePersonalSelectionNow,
-  // A loaded project pinned to a selection record below the highest record this process has read the history ending at
+  // A loaded project pinned to a selection different from the most recently accepted head in this process
   // is loaded again at the next tick, whatever the files say: another reader in the process may have read a
   // confirmation that is gone again before this engine looked (personalSelectionBehind).
   reloadsBehindSelection: personalSelectionBehind,
@@ -167,6 +168,11 @@ export const ENGINE_PRIMITIVES = Object.freeze({
 })
 
 const isTypedRefusal = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof AtelierDiagnosticError || error instanceof ObsidianContractRefusal || error instanceof PublicationRefusal
+// The private-state location proof refused (assertLocation's own code): the state root itself is no longer proven
+// outside every root declared now. That is never one view's refusal: it stops the whole tick, so no later view goes
+// on writing under roots it can no longer trust. A view's own vault in a bad place keeps its own codes and stops
+// only that view.
+const isLocationRefusal = (error) => isTypedRefusal(error) && error.code === 'managed-root-unproven'
 // 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.
@@ -287,7 +293,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   let firstTick = true
   let running = false
   let watching = { signature: null, handle: null }
-  let known = null // { stateStore, maintenanceMode } once a workspace has been resolved
+  let known = null // { stateStore, maintenanceMode, repositoryRoots } once a workspace has been resolved
   let heldLock = null
   let releaseOwed = false
   // Views somebody asked to have prepared and published once more, at the next tick.
@@ -310,7 +316,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     try { return (await readUnheldEvidence({ vaultRoot: store.vaultRoot }))?.unlisted === true } catch { return false }
   }
 
-  async function takeLock(workspaceRoot, workspaceId) {
+  async function takeLock(workspaceRoot, workspaceId, validateLocation = undefined) {
     // A lock an earlier tick could not give back is still this process's, and its ticket on disk unreleased: a tick
     // that tried to take it anew would find its own ticket and answer `busy` until the process ends. It is given back
     // first. A release that fails again fails this tick, and is owed to the next.
@@ -322,6 +328,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     if (heldLock) return { acquired: true }
     const lock = await rules.acquireEngineLock({
       workspaceRoot, directory: path.join(workspaceRoot, ENGINE_LOCK_DIRECTORY), workspaceId, purpose: 'maintenance-engine', service: lockOwner, clock, proveAbandoned,
+      ...(validateLocation === undefined ? {} : { validateLocation }),
     })
     if (lock.acquired) heldLock = lock
     return lock
@@ -369,7 +376,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     // 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 }
+      try { cached.store.checkAllocatedVault?.(); return cached.store } catch (error) { if (!isTypedRefusal(error) || isLocationRefusal(error)) throw error }
     }
     stores.delete(scope.scopeId)
     const store = seams.createRecoveryStore({ workspaceRoot, workspaceId, scopeId: scope.scopeId, repositoryRoots })
@@ -392,22 +399,67 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
   const blankEntry = (scopeId, now) => ({ scopeId, state: 'stale', reason: 'not-yet-published', generationId: null, preparedGenerationId: null, verified: false, heldNotes: [], changeClasses: [], retainedEdits: 0, checkedAt: now })
   const demote = (entry, state, reason, now) => ({ ...entry, state, reason, verified: false, checkedAt: now })
 
-  // Persists "refused" or "disabled" over whatever is known, and only when a workspace already has state.
-  async function persistOutcome({ enablement, state, reason, now, scopeIds = [] }) {
+  // The private-state location guard's own refusals: under one, the state root itself is in question.
+  const MANAGED_ROOT_REFUSALS = new Set(['managed-root-inside-repository', 'managed-root-not-absolute', 'managed-root-realpath-failed',
+    'managed-root-realpath-overlap', 'managed-root-symlink-alias', 'repository-inside-managed-root', 'managed-root-unproven'])
+  // The roots private state must stay outside, as declared now: each project's own, and a personal home's manifest
+  // read again rather than as it was when the project loaded. Throws when they cannot be read.
+  const currentExclusionRoots = (declared) => declared.flatMap((value) => {
+    const binding = personalWorkspaceBindingOf(value)
+    return [...protectedRoots(value), ...(binding === null ? [] : personalExclusionRootsNow(binding.personalHome))]
+  })
+  // Whether a state root is proven outside every root declared now. A locator that refuses, or roots that cannot be
+  // read, prove nothing.
+  const locationProvenNow = (root, loaded) => {
+    try {
+      const declared = [...(locateProject === null ? [] : [locateProject()]), ...(loaded === null ? [] : [loaded])]
+      if (declared.length === 0) return false
+      assertOutsideRepositories({ managedRoot: root, repositoryRoots: currentExclusionRoots(declared) })
+      return true
+    } catch { return false }
+  }
+
+  // Persists "refused" or "disabled" over whatever is known, and only when a workspace already has state. Nothing is
+  // written for a location refusal, or unless the state root is proven outside every root declared now: a manifest
+  // that newly declares a root holding this state is never written into, cached store or not. When no project can be
+  // read now, a cached store is held to the roots it was last proven outside; without either, nothing is written.
+  async function persistOutcome({ enablement, state, reason, now, scopeIds = [], locationRefused = false }) {
+    if (locationRefused) return
+    // The roots declared now. A configured locator that cannot answer leaves them unknown: earlier roots never stand
+    // in. Without a locator or a readable project, a cached store is held to the roots it was last proven outside.
+    const rootsNow = () => {
+      let located = null
+      if (locateProject !== null) located = locateProject()
+      const declared = [located, project].filter((value) => value !== null && value !== undefined)
+      if (declared.length > 0) return currentExclusionRoots(declared)
+      if (locateProject === null && Array.isArray(known?.repositoryRoots)) return known.repositoryRoots
+      return null
+    }
+    let repositoryRoots
+    try { repositoryRoots = rootsNow() } catch { return }
+    if (repositoryRoots === null) return
+    const outside = (root) => { try { assertOutsideRepositories({ managedRoot: root, repositoryRoots }); return true } catch { return false } }
+    const outsideNow = (root) => { try { const roots = rootsNow(); if (roots === null) return false; assertOutsideRepositories({ managedRoot: root, repositoryRoots: roots }); return true } catch { return false } }
     if (!known) {
-      let located = project
-      try { located ??= locateProject === null ? null : locateProject() } catch { located = null }
+      let source = project
+      if (locateProject !== null) { try { source = locateProject() } catch { return } }
+      if (source === null || source === undefined) return
       let pointer = null
-      try { pointer = located ? readLocalPointer(located) : null } catch { pointer = null }
+      try { pointer = readLocalPointer(source) } catch { pointer = null }
       if (!pointer) return
       let root
-      try { root = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project: located, env, platform }), pointer.workspaceId) } catch { return }
+      try { root = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project: source, env, platform }), pointer.workspaceId) } catch { return }
+      if (!outside(root)) return
       const stateStore = createMaintenanceStateStore({ workspaceRoot: root, workspaceId: pointer.workspaceId })
       if (!stateStore.exists()) return
-      known = { stateStore: createMaintenanceStateStore({ workspaceRoot: fs.realpathSync(root), workspaceId: pointer.workspaceId }), maintenanceMode: 'manual' }
+      known = { stateStore: createMaintenanceStateStore({ workspaceRoot: fs.realpathSync(root), workspaceId: pointer.workspaceId }), maintenanceMode: 'manual', repositoryRoots }
     }
+    if (!outside(known.stateStore.workspaceRoot)) return
+    // Proven again inside the acquisition and once it returns, against the roots declared then.
+    const stillOutside = () => { if (!outsideNow(known.stateStore.workspaceRoot)) refuse('managed-root-unproven', 'the private state can no longer be proved outside every root declared now; nothing is written') }
     // Another engine is ticking this workspace: its state is not ours to write.
-    if (!(await takeLock(known.stateStore.workspaceRoot, known.stateStore.workspaceId)).acquired) return
+    try { if (!(await takeLock(known.stateStore.workspaceRoot, known.stateStore.workspaceId, stillOutside)).acquired) return } catch (error) { if (isTypedRefusal(error) && error.code === 'managed-root-unproven') return; throw error }
+    if (!outsideNow(known.stateStore.workspaceRoot)) return
     const previous = readPreviousFreshness(known.stateStore)
     const entries = new Map()
     for (const entry of previous?.scopes ?? []) entries.set(entry.scopeId, demote(entry, state, reason, now))
@@ -466,20 +518,28 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     }
 
     // 2. Identity and machine settings, outside every repository.
-    const pointer = ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}) })
-    const { workspaceId } = pointer
-    const requestedRoot = workspaceStateRoot(resolveDataRoot({ dataRoot, pointer, project, env, platform }), workspaceId)
     const repositoryRoots = protectedRoots(project)
-    assertOutsideRepositories({ managedRoot: requestedRoot, repositoryRoots })
+    // The project this tick loaded. `project` itself may be cleared later in the tick to force a reload.
+    const loadedProject = project
+    // Each phase that writes after a cooperative wait proves the location again against the roots declared now; the
+    // refusal is a location refusal, so refusal bookkeeping writes nothing either. A held engine lock is still released.
+    const assertLocation = () => {
+      if (!locationProvenNow(workspaceRoot, loadedProject)) refuse('managed-root-unproven', 'the private state can no longer be proved outside every root declared now; this tick writes nothing more')
+    }
+    const stateRootOf = (named) => workspaceStateRoot(resolveDataRoot({ dataRoot, pointer: named, project, env, platform }), named.workspaceId)
+    const pointer = ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}),
+      validate: (named) => assertOutsideRepositories({ managedRoot: stateRootOf(named), repositoryRoots }) })
+    const { workspaceId } = pointer
+    const requestedRoot = stateRootOf(pointer)
     fs.mkdirSync(requestedRoot, { recursive: true, mode: 0o700 })
     const workspaceRoot = fs.realpathSync(requestedRoot)
-    const lock = await takeLock(workspaceRoot, workspaceId)
+    const lock = await takeLock(workspaceRoot, workspaceId, assertLocation)
     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 }) })
+    assertLocation()
+    const machine = initializeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, updatedAt: now, personal: personalWorkspaceBindingOf(project) !== null })
     const eligibility = fixedEligibility ?? eligibilityFor({ machine, project })
     const stateStore = createMaintenanceStateStore({ workspaceRoot, workspaceId })
-    known = { stateStore, maintenanceMode: machine.maintenanceMode }
+    known = { stateStore, maintenanceMode: machine.maintenanceMode, repositoryRoots }
     // A view refused for a file-system error (a vault folder that could not be allocated or placed, a configuration
     // file that could not be read again, a source removed while it was read, candidates that could not be staged) is
     // settled under the refusal's code alone, and such a tick ends without a failure. The error's code (`EACCES`, `EIO`,
@@ -496,6 +556,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     // A view whose own vault cannot be placed: a typed refusal's code and detail, or `vault-location-unusable` for a
     // file-system error there, whose code is its cause.
     const refuseViewAlone = (scopeId, error) => {
+      if (isLocationRefusal(error)) throw error
       const code = viewRefusalCode(error)
       if (code === null) throw error
       allocationRefusals.set(scopeId, code)
@@ -528,6 +589,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           const record = readVaultAllocation({ workspaceRoot, workspaceId, scopeId: scope.scopeId })
           if (record === null ? !hasCommittedGeneration({ workspaceRoot, scopeId: scope.scopeId }) : allocatedFolderState(record) === 'missing') {
             const known = await appList()
+            assertLocation()
             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
           }
@@ -575,6 +637,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
         looked.push({ scope, store, manifest, bases, vault })
       }
     } finally { reportPhase('vault-observation', vaultStartedMs) }
+    assertLocation()
     const pending = stateStore.readPendingEdits()
     let edits = pending.edits
     for (const { scope, store, manifest, bases, vault } of looked) {
@@ -599,6 +662,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     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' } }
+      assertLocation()
     }
 
     // 4. Automatic apply, through the registered operation only.
@@ -608,6 +672,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
         edits, applyOperation: extensions.applyOperation(), now, nowMs, retryIntervalMs,
         authorize: () => rules.authorize({ workspaceRoot, workspaceId }),
       })
+      assertLocation()
       edits = outcome.edits
       dispatched = outcome.dispatched
       stateStore.writePendingEdits({ ...pending, edits })
@@ -619,6 +684,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     let proposals = null
     if (proposalAdapter !== null) {
       try { proposals = await proposalAdapter.propose(adapterContext()) } catch { proposals = { adapterId: proposalAdapter.id, failed: 'proposal-adapter-threw' } }
+      assertLocation()
     }
 
     // 5. Late writers. The publisher looks twice per publication; a holder can write later still.
@@ -652,6 +718,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
     const sourcesStartedMs = phaseTime()
     let sources
     try { sources = await reconcileCooperatively({ index, files: listSourceFiles(project, { assets: observedAssets }), prefix: SOURCE_PREFIX, full, hinted, lstat }, createCooperativeBudget()) } finally { reportPhase('source-observation', sourcesStartedMs) }
+    assertLocation()
     for (const change of sources.changes) changes.push({ changeClass: change.changeClass })
     const { scopes: _declared, ...settingsWithoutScopes } = enablement.settings
     // What the configuration says apart from this integration's own member: a change to the member alone is an
@@ -712,7 +779,9 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       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 }))
+    // Freshness is written only while the state root is still proven outside the roots declared now: a manifest that
+    // changed during this tick to enclose it gets no write, refusal or not.
+    const persist = () => { if (locationProvenNow(workspaceRoot, loadedProject)) stateStore.writeFreshness(freshnessDocument({ workspaceId, enablement: 'enabled', maintenanceMode: machine.maintenanceMode, now, entries })) }
     persist()
 
     // 8. Rebuild and publish.
@@ -729,6 +798,8 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
       let selectionNoted = false
       const noteSelectionOnce = () => { if (!selectionNoted) { selectionNoted = true; rules.noteSelectionAtGuard(project) } }
       const assertBindings = () => {
+        // Every cooperative wait of preparation and publication resumes here before it writes again.
+        assertLocation()
         let changed
         try {
           changed = bindings.some(file => (readFileFacts(file.absolute)?.digest ?? null) !== file.digest)
@@ -835,7 +906,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           profile: seams.profileFor({ project, workspaceId, audienceAllow: machine.audienceAllow }),
         }
       } catch (error) {
-        if (!isTypedRefusal(error)) throw error
+        if (!isTypedRefusal(error) || isLocationRefusal(error)) throw error
         for (const scopeId of attempt.keys()) { entries.set(scopeId, demote(entries.get(scopeId), 'stale', error.code, now)); noteRefusalCause(scopeId, error) }
         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
@@ -845,7 +916,7 @@ 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)
-        // What this attempt found worth naming: notes and rules (see "Notes that were laid out anyway" in docs/obsidian-contract.md).
+        // What this attempt found worth naming: notes and rules (see "Notes that were laid out anyway" in docs/reference/obsidian-contract.md).
         let diagnostics = []
         const settle = (state, reason, extra = {}) => {
           const { diagnostics: _earlier, ...rest } = { ...entry, ...extra, state, reason, verified: extra.verified === true, checkedAt: now }
@@ -951,6 +1022,8 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           }
         } catch (error) {
           if (!isTypedRefusal(error)) { settle('stale', 'publisher-error'); persist(); throw error }
+          // Nothing more is recorded for any view: the tick stops and refuses as a whole.
+          if (isLocationRefusal(error)) 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 } : {}) }] : []
@@ -1010,7 +1083,7 @@ export function createMaintenanceEngineForOracleTests(options = {}, primitives =
           throw error
         }
         // Fail closed: nothing is published under a refusal, and every known view says why.
-        try { await persistOutcome({ enablement: 'refused', state: 'stale', reason: error.code, now: isoTime(clock) }) } catch { /* the refusal itself is still reported */ }
+        try { await persistOutcome({ enablement: 'refused', state: 'stale', reason: error.code, now: isoTime(clock), locationRefused: MANAGED_ROOT_REFUSALS.has(error.code) }) } catch { /* the refusal itself is still reported */ }
         project = null
         semantic = null
         firstTick = true

package/src/runtime/obsidian/lifecycle.mjs

@@ -16,10 +16,10 @@ import {
   serviceNameFor, servicePaths, writeServiceSettings,
 } from './service-record.mjs'
 import { personalHomeOf } from './personal-selection.mjs'
-import { resolveServiceWorkspace } from './service.mjs'
+import { resolveServiceWorkspace, serviceLocationCheck } from './service.mjs'
 
 // start / status / stop of the maintenance service of one workspace, as
-// docs/local-services.md describes them.
+// docs/reference/local-services.md describes them.
 //
 // Ownership is proven, never assumed. A running service is ours only when the
 // owner-only record and the health answer agree on service name, workspace,
@@ -67,7 +67,7 @@ export const LIFECYCLE_PRIMITIVES = Object.freeze({
 function context({ loadProject, locateProject = null, dataRoot, env, platform, create = false, randomBytes }) {
   if (typeof loadProject !== 'function') throw new TypeError('the service lifecycle needs loadProject')
   const project = locateProject === null ? loadProject() : locateProject()
-  if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}) })
+  if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}), validate: serviceLocationCheck({ project, dataRoot, env, platform }) })
   const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create })
   return { project, workspace }
 }

package/src/runtime/obsidian/login-item.mjs

@@ -10,7 +10,7 @@ import { ensureWorkspaceIdentity, readLocalPointer, resolveDataRoot } from './ma
 import { SERVICE_MANAGER_KINDS } from './service-managers.mjs'
 import { readLastStartup, readServiceSettings, serviceNameFor, servicePaths, writeServiceSettings } from './service-record.mjs'
 import { personalHomeOf } from './personal-selection.mjs'
-import { resolveServiceWorkspace } from './service.mjs'
+import { resolveServiceWorkspace, serviceLocationCheck } from './service.mjs'
 import { STARTUP_PLATFORMS, buildStartupAdapter, startupSearchPath } from './startup-adapters.mjs'
 
 // A login item: the operating system starts this workspace's maintenance
@@ -198,7 +198,7 @@ export async function installLoginItem(options = {}) {
   const { loadProject, dataRoot, env = process.env, platform = process.platform, manager, consent, ownEntry, entryArgs = [], nodePath = realNodePath(), pathValue = env.PATH, clock = () => new Date(), temporary = temporaryRoots(), beforeInstall = null } = options
   checkManager(manager, platform)
   const project = loadProject()
-  ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }) })
+  ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }), validate: serviceLocationCheck({ project, dataRoot, env, platform }) })
   const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create: true })
   const { entryPath, source } = resolveLoginItemEntry({ project, ownEntry, temporary })
   const recorded = readLoginItemRecord(workspace)

package/src/runtime/obsidian/machine-settings.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { LOCAL_STATE_DIR, localStateRoot } from '../../project/config.mjs'
+import { withPrivateLock } from '../../project/durable-state.mjs'
 import { checkManagedRoots } from '../../project/file-class.mjs'
 import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../project/private-state.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../../projection/obsidian/contracts.mjs'
@@ -146,12 +147,20 @@ export function writeLocalPointer(project, pointer) {
 }
 
 // Reads the persisted workspace identity, or issues a random one and persists
-// it. `randomBytes` is injectable so tests are deterministic.
-export function ensureWorkspaceIdentity({ project, dataRoot, randomBytes = cryptoRandomBytes } = {}) {
+// it. `randomBytes` is injectable so tests are deterministic. `validate`, when
+// given, checks the location an identity names: a new identity is checked
+// before its pointer is written, so a refused location leaves no pointer, and
+// the identity actually persisted is checked again before it is returned.
+export function ensureWorkspaceIdentity({ project, dataRoot, randomBytes = cryptoRandomBytes, validate = null } = {}) {
   const existing = readLocalPointer(project)
-  if (existing) return existing
-  const pointer = { schema: LOCAL_POINTER_SCHEMA, workspaceId: `ws-${randomBytes(12).toString('hex')}`, ...(dataRoot === undefined ? {} : { dataRoot: path.resolve(dataRoot) }) }
-  return writeLocalPointer(project, pointer)
+  if (existing) { validate?.(existing); return existing }
+  const pointer = validatePointer({ schema: LOCAL_POINTER_SCHEMA, workspaceId: `ws-${randomBytes(12).toString('hex')}`, ...(dataRoot === undefined ? {} : { dataRoot: path.resolve(dataRoot) }) })
+  validate?.(pointer)
+  writeLocalPointer(project, pointer)
+  const persisted = readLocalPointer(project)
+  if (persisted === null) refuse('invalid-local-pointer', 'the Obsidian pointer was not kept')
+  validate?.(persisted)
+  return persisted
 }
 
 // ---------------------------------------------------------------------------
@@ -260,6 +269,18 @@ export function defaultMachineSettings({ workspaceId, updatedAt }) {
   }
 }
 
+// The already adopted owner-only audience for a personal binding, recorded in the same machine setting an ordinary
+// workspace uses. Existing explicit decisions keep their exact list and unclassified choice; a clear stays empty.
+export function ownerOnlyPersonalSettings(settings, { decidedAt }) {
+  const decision = settings.decisions.audience
+  if (decision === null && settings.audienceAllow.length === 0) {
+    return withDecision({ ...settings, audienceAllow: [...ONLY_YOU_AUDIENCES], updatedAt: decidedAt }, 'audience',
+      { choice: 'only-you', unclassified: 'shown' }, { decidedAt, via: 'defaults' })
+  }
+  if (decision?.choice === 'only-you' || (decision?.choice === 'custom' && settings.audienceAllow.length === 0)) return settings
+  refuse('personal-binding-owner-only', 'a personal workspace vault is owner only; select `audience set me` or clear its audience before publishing')
+}
+
 // The settings with one decision recorded, validated; nothing is written. `decision` holds the decision's own members
 // (`{ choice, unclassified }`, `{ parent }`, `{ choice }`); the stamp says when, by whom (an identifier, or null when not
 // known) and how.
@@ -278,15 +299,38 @@ export function readMachineSettings({ workspaceRoot, workspaceId }) {
   return document === null ? null : normalizeMachineSettings(document, workspaceId)
 }
 
-// Writes v2, whatever version it is handed, and returns what it wrote.
-export function writeMachineSettings({ workspaceRoot, workspaceId, settings, repositoryRoots }) {
-  const document = normalizeMachineSettings(settings, workspaceId)
+function withMachineSettingsWriteLock({ workspaceRoot, repositoryRoots }, operation) {
   assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  return withPrivateLock(path.join(settingsDirectory(workspaceRoot), 'machine-settings.lock'), operation)
+}
+
+function writeMachineSettingsUnlocked({ workspaceRoot, document }) {
   atomicReplacePrivateText(path.join(settingsDirectory(workspaceRoot), 'machine.json'), canonicalJson(document))
   return document
 }
 
+// Writes v2, whatever version it is handed, and returns what it wrote. Commands and initialization share this lock.
+export function writeMachineSettings({ workspaceRoot, workspaceId, settings, repositoryRoots }) {
+  const document = normalizeMachineSettings(settings, workspaceId)
+  return withMachineSettingsWriteLock({ workspaceRoot, repositoryRoots }, () => writeMachineSettingsUnlocked({ workspaceRoot, document }))
+}
+
+// Read-only when already decided. If initialization is needed, reread under the write lock so a committed clear wins.
+export function initializeMachineSettings({ workspaceRoot, workspaceId, repositoryRoots, updatedAt, personal = false }) {
+  const initialized = (current) => {
+    const initial = current ?? defaultMachineSettings({ workspaceId, updatedAt })
+    return personal ? ownerOnlyPersonalSettings(initial, { decidedAt: updatedAt }) : initial
+  }
+  const existing = readMachineSettings({ workspaceRoot, workspaceId })
+  if (initialized(existing) === existing) return existing
+  return withMachineSettingsWriteLock({ workspaceRoot, repositoryRoots }, () => {
+    const current = readMachineSettings({ workspaceRoot, workspaceId })
+    const document = normalizeMachineSettings(initialized(current), workspaceId)
+    return document === current ? current : writeMachineSettingsUnlocked({ workspaceRoot, document })
+  })
+}
+
 // ---------------------------------------------------------------------------
 // Installed apply policy
 // ---------------------------------------------------------------------------

package/src/runtime/obsidian/opening.mjs

@@ -134,7 +134,7 @@ export const REASON_NEXT = Object.freeze({
   // publisher or editor is involved.
   'plugin-file-changed': 'a file of Atelier\'s plugin in this vault (under .obsidian/plugins) changed while the view was published, by another program or by you, so the publication did not finish; it is retried automatically, and if this keeps happening, stop what keeps writing there (a sync tool, say)',
   'settings-changed': 'a settings file Atelier writes in this vault (the plugin list or a plugin setting under .obsidian) changed while the view was published, by Obsidian, another program or you, and was not written over; it is retried automatically, reading the file as it is then',
-  'selection-history-shortened': 'the selection history of the personal home ends at an earlier record than the running maintenance service has read: records were removed by something other than a confirmation, and the service publishes nothing while the history is shorter. Put the removed records back, and it goes on as before. Or accept the history as it now stands: a service started again (`atelier obsidian service stop`, then open again) reads the history as it is and follows the selection it then ends with, publishing it if its generation still holds (`atelier obsidian status` reports that selection, or why it cannot be used); a confirmation made after the records were removed is followed without a restart once the history is as long as it was',
+  'selection-history-shortened': 'the selection history no longer follows the machine-private continuity evidence, so nothing is published. Put the removed records back, or explicitly confirm the generation again through the personal workspace selection operation. One fresh confirmation accepts the shorter history if the generation is still eligible. Restarting the service preserves this refusal.',
   'vault-inside-another-vault': 'Obsidian lists another vault at a folder that contains this view\'s vault; open never adds a vault inside another one, and never sends a call that could reach that vault instead: remove that vault from Obsidian\'s vault list, or keep Atelier\'s data root outside that folder, then open again',
 })
 
@@ -253,7 +253,7 @@ export function scopeReport({ workspace, scopeId, repositoryRoots, serviceState,
     freshness: entry === null ? null : { state: entry.state, reason: entry.reason, verified: entry.verified, generationId: entry.generationId, preparedGenerationId: entry.preparedGenerationId, heldNoteCount: entry.heldNotes.length, retainedEdits: entry.retainedEdits, checkedAt: entry.checkedAt },
     readBack: { readable: verification.readable, reason: verification.reason, generationId: verification.generationId, intact: verification.intact, noteCount: verification.noteCount, differing: verification.differing, missing: verification.missing },
     pendingEdits: pendingSummary(stateStore, scopeId, applyAvailable),
-    // Notes of the view worth naming, and the rule concerned; see "Notes that were laid out anyway" in docs/obsidian-contract.md.
+    // Notes of the view worth naming, and the rule concerned; see "Notes that were laid out anyway" in docs/reference/obsidian-contract.md.
     ...(entry?.diagnostics ? { diagnostics: entry.diagnostics } : {}),
     vaultRoot: verification.vaultRoot ?? null,
   }