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

package/src/runtime/obsidian/lifecycle.mjs

@@ -15,10 +15,11 @@ import {
   CONSENT_COVERAGES, SERVICE_SETTINGS_SCHEMA, executableIdentity, openServiceLog, publicRecord, readLastStartup, readServiceRecord, readServiceSettings, releaseOfEntry, removeServiceRecord,
   serviceNameFor, servicePaths, writeServiceSettings,
 } from './service-record.mjs'
-import { resolveServiceWorkspace } from './service.mjs'
+import { personalHomeOf } from './personal-selection.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,
@@ -61,10 +62,12 @@ export const LIFECYCLE_PRIMITIVES = Object.freeze({
   provesOurProcess: (record) => processRunsRecordedExecutable(record),
 })
 
-function context({ loadProject, dataRoot, env, platform, create = false, randomBytes }) {
+// `locateProject`, when given, answers what the workspace is resolved from without loading the project (a bound
+// personal home, locatePersonalHome): its service is then found, started and stopped whatever its selection holds.
+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 = loadProject()
-  if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}) })
+  const project = locateProject === null ? loadProject() : locateProject()
+  if (create) ensureWorkspaceIdentity({ project, ...(randomBytes ? { randomBytes } : {}), validate: serviceLocationCheck({ project, dataRoot, env, platform }) })
   const workspace = resolveServiceWorkspace({ project, dataRoot, env, platform, create })
   return { project, workspace }
 }
@@ -90,8 +93,8 @@ async function evaluate({ workspaceRoot, workspaceId }, { probeTimeoutMs = DEFAU
 
 const shown = ({ record, ...status }) => ({ ...status, record: publicRecord(record) })
 
-export async function serviceStatus({ loadProject, dataRoot, env = process.env, platform = process.platform, probeTimeoutMs, alive } = {}, rules = LIFECYCLE_PRIMITIVES) {
-  const { workspace } = context({ loadProject, dataRoot, env, platform })
+export async function serviceStatus({ loadProject, locateProject, dataRoot, env = process.env, platform = process.platform, probeTimeoutMs, alive } = {}, rules = LIFECYCLE_PRIMITIVES) {
+  const { workspace } = context({ loadProject, locateProject, dataRoot, env, platform })
   if (!workspace?.workspaceRoot) return { state: 'stopped', reason: 'workspace-not-prepared', workspaceId: workspace?.workspaceId ?? null, record: null, address: null }
   return shown(await evaluate(workspace, { probeTimeoutMs, alive, rules }))
 }
@@ -177,11 +180,11 @@ async function startThroughLoginItem({ workspace, loginItem, entryPath, deadline
 // proven runtime is answered as already running.
 export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
   const {
-    loadProject, dataRoot, host, port, consent, detached = false, entryPath = SERVICE_ENTRY_PATH, entryArgs = [], intervalMs,
+    loadProject, locateProject, dataRoot, host, port, consent, detached = false, entryPath = SERVICE_ENTRY_PATH, entryArgs = [], intervalMs,
     startTimeoutMs = DEFAULT_START_TIMEOUT_MS, probeTimeoutMs, clock = () => new Date(), env = process.env, platform = process.platform,
     spawn = childProcess.spawn, execPath = process.execPath, alive = isProcessAlive, randomBytes = cryptoRandomBytes, loginItem = null, replaceOutdated = false,
   } = options
-  const { project, workspace } = context({ loadProject, dataRoot, env, platform, create: true })
+  const { project, workspace } = context({ loadProject, locateProject, dataRoot, env, platform, create: true })
   const { workspaceRoot, workspaceId } = workspace
   const deadline = Date.now() + startTimeoutMs
 
@@ -208,7 +211,7 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
       const standing = replaceOutdated ? runtimeRelease(before, entryPath) : null
       if (standing === 'later') return { ...shown(before), started: false, alreadyRunning: true, release: 'later' }
       if (standing !== 'outdated') return { ...shown(before), started: false, alreadyRunning: true }
-      const stopped = await stopService({ loadProject, dataRoot, env, platform, probeTimeoutMs, alive }, rules)
+      const stopped = await stopService({ loadProject, locateProject, dataRoot, env, platform, probeTimeoutMs, alive }, rules)
       if (!stopped.stopped) return { ...shown(before), started: false, alreadyRunning: true, release: 'outdated', reason: stopped.reason ?? 'the-runtime-was-not-stopped' }
       replaced = 'outdated'
       before = await evaluate(workspace, { probeTimeoutMs, alive, rules })
@@ -241,7 +244,9 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
     const executable = executableIdentity(entryPath)
     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]
+      // A bound personal home is named instead of a project: the service follows the selection confirmed there.
+      const home = personalHomeOf(project)
+      const args = [executable.path, home === null ? `--project=${project.configPath}` : `--personal-home=${home}`, ...(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. 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 })
@@ -277,8 +282,8 @@ export async function startService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
 }
 
 export async function stopService(options = {}, rules = LIFECYCLE_PRIMITIVES) {
-  const { loadProject, dataRoot, stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive, force = false, kill = process.kill.bind(process) } = options
-  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  const { loadProject, locateProject, dataRoot, stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive, force = false, kill = process.kill.bind(process) } = options
+  const { workspace } = context({ loadProject, locateProject, dataRoot, env, platform })
   if (!workspace?.workspaceRoot) return { state: 'stopped', stopped: false, refused: false, reason: 'workspace-not-prepared' }
   const { workspaceRoot, workspaceId } = workspace
   const status = await evaluate(workspace, { probeTimeoutMs, alive, rules })
@@ -308,8 +313,8 @@ 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, body = {} }) {
-  const { loadProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
-  const { workspace } = context({ loadProject, dataRoot, env, platform })
+  const { loadProject, locateProject, dataRoot, probeTimeoutMs, env = process.env, platform = process.platform, alive = isProcessAlive } = options
+  const { workspace } = context({ loadProject, locateProject, 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 }

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

@@ -9,7 +9,8 @@ import { ensureServiceSettings } from './lifecycle.mjs'
 import { ensureWorkspaceIdentity, readLocalPointer, resolveDataRoot } from './machine-settings.mjs'
 import { SERVICE_MANAGER_KINDS } from './service-managers.mjs'
 import { readLastStartup, readServiceSettings, serviceNameFor, servicePaths, writeServiceSettings } from './service-record.mjs'
-import { resolveServiceWorkspace } from './service.mjs'
+import { personalHomeOf } from './personal-selection.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
@@ -164,7 +165,9 @@ export const loginItemDataRoot = ({ project, dataRoot, env = process.env, platfo
 export function planLoginItem({ platform, project, workspaceRoot, workspaceId, dataRoot, label, entryPath, entryArgs = [], nodePath, searchPath = null }) {
   if (!isAbsolutePlain(dataRoot)) throw new TypeError('a login item names the absolute data root of its workspace')
   if (typeof workspaceId !== 'string' || workspaceId === '') throw new TypeError('a login item names its workspace')
-  const args = [`--project=${project.configPath}`, `--data-root=${dataRoot}`, `--workspace-id=${workspaceId}`, ...entryArgs]
+  // A bound personal home is named instead of a project, as `start` names it (lifecycle.mjs).
+  const home = personalHomeOf(project)
+  const args = [home === null ? `--project=${project.configPath}` : `--personal-home=${home}`, `--data-root=${dataRoot}`, `--workspace-id=${workspaceId}`, ...entryArgs]
   const unit = buildStartupAdapter({ platform, label, nodePath, entryPath, args, logPath: servicePaths(workspaceRoot).loginItemLog, searchPath })
   return { ...unit, label, digest: sha256(unit.text), program: { node: nodePath, entry: entryPath }, searchPath }
 }
@@ -195,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/observation.mjs

@@ -123,24 +123,52 @@ export function readFileFacts(file) {
 
 const sameHint = (left, right) => left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.ino === right.ino
 
+// Whether a file still has the stat hint it was indexed with: what a reconcile that is not full decides by before it
+// would hash the file again. `entry` is the file's entry in the index. A file never hashed, or gone, has none.
+export function hasIndexedHint(entry, absolute, lstat = fs.lstatSync) {
+  if (!entry || entry.digest === null || !entry.hint) return false
+  const hint = statHint(absolute, lstat)
+  return hint !== null && sameHint(entry.hint, hint)
+}
+
 // Reconciles `files` against `index` (a Map owned by the caller) and returns
 // the changes, decided by digest alone. `full` hashes everything; otherwise a
 // file is hashed when it is new, when its stat hint differs or when a watcher
 // named it. Entries under `prefix` that are no longer listed are removals.
-export function reconcile({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
+export function reconcile(input) {
+  const steps = reconcileSteps(input)
+  for (;;) { const step = steps.next(); if (step.done) return step.value }
+}
+
+// The same reconciliation with the event loop given a turn between files, under the caller's cooperative budget
+// (createCooperativeBudget): for a walk long enough to hold a service's listener, such as the read-back of a large
+// view. Each file is still looked at once, in the listed order, and the index holds what was seen when each was read;
+// a file that changes after its turn is the next look's to see, as one that changes after an uninterrupted walk is.
+// The caller must not let another reconciliation of the same index run before this one has answered.
+export async function reconcileCooperatively(input, budget) {
+  const steps = reconcileSteps(input)
+  for (;;) {
+    const step = steps.next()
+    if (step.done) return step.value
+    await budget.checkpoint('reconcile-file')
+  }
+}
+
+// One step a listed file; the removals and the answer after the last.
+function* reconcileSteps({ index, files, prefix, full, hinted = () => false, lstat = fs.lstatSync }) {
   const changes = []
   const present = new Set()
   let hashed = 0
-  for (const file of files) {
+  const look = (file) => {
     present.add(file.key)
     const previous = index.get(file.key)
     const hint = statHint(file.absolute, lstat)
     if (hint === null) {
       if (previous && previous.digest !== null) changes.push({ key: file.key, changeClass: previous.changeClass, kind: 'removed' })
       index.set(file.key, { changeClass: file.changeClass, hint: null, digest: null, byteLength: null })
-      continue
+      return
     }
-    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) continue
+    if (!full && previous && previous.digest !== null && previous.hint && sameHint(previous.hint, hint) && !hinted(file.key)) return
     const facts = readFileFacts(file.absolute)
     const digest = facts?.digest ?? null
     hashed += 1
@@ -149,6 +177,10 @@ export function reconcile({ index, files, prefix, full, hinted = () => false, ls
     }
     index.set(file.key, { changeClass: file.changeClass, hint: digest === null ? null : hint, digest, byteLength: facts?.byteLength ?? null })
   }
+  for (const file of files) {
+    look(file)
+    yield
+  }
   for (const [key, previous] of index) {
     if (!key.startsWith(prefix) || present.has(key)) continue
     if (previous.digest !== null) changes.push({ key, changeClass: previous.changeClass, kind: 'removed' })

package/src/runtime/obsidian/opening.mjs

@@ -134,6 +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 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',
 })
 
@@ -252,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,
   }
@@ -358,7 +359,7 @@ function settingsWritten(written) {
 // again for a view the app kept from being published, and reports one outcome.
 export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIMITIVES, lifecycleRules = LIFECYCLE_PRIMITIVES) {
   const {
-    loadProject, dataRoot, scopeId: requestedScope, appProbe, launcher, registry, quitter = null, restartApp = false, service = {}, consent, allowStale = false, extensions = null,
+    loadProject, locateProject, dataRoot, scopeId: requestedScope, appProbe, launcher, registry, quitter = null, restartApp = false, service = {}, consent, allowStale = false, extensions = null,
     tickTimeoutMs = 120 * 1000, appWaitMs = 30 * 1000, appPollMs = 500, sleep = defaultSleep, monotonic = () => Date.now(),
     env = process.env, platform = process.platform, probeTimeoutMs,
   } = options
@@ -382,7 +383,7 @@ export async function openScopeForOracleTests(options = {}, rules = OPENING_PRIM
   }
   if (enablement.state === 'disabled') return finish('disabled', { reason: enablement.reason, scopeId: requestedScope ?? null })
   const scopeId = resolveScope(enablement, requestedScope)
-  const lifecycle = { loadProject, dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
+  const lifecycle = { loadProject, ...(locateProject === undefined ? {} : { locateProject }), dataRoot, env, platform, ...(probeTimeoutMs === undefined ? {} : { probeTimeoutMs }) }
 
   // 1. The owned service: reconnect, or start. Never adopt; a runtime of ours is replaced only when it runs an earlier
   //    release, under the consent already recorded, when a tick is asked of it (requestServiceTick).

package/src/runtime/obsidian/personal-selection.mjs

@@ -0,0 +1,187 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { PersonalWorkspaceRefusal } from '@mnstry/atelier/personal-workspace'
+import { ensureLocalState } from '@mnstry/atelier/project'
+import { assertPersonalSelection, loadBoundProject, loadBoundProjectOffThread, notePersonalSelectionHead, personalSelectionOf, pinPersonalSelection } from '../../projection/obsidian/personal-workspace.mjs'
+import { refuse } from './errors.mjs'
+import { readPersonalSelectionSnapshot } from '../../personal-workspace/selection.mjs'
+import { assertOutsideRepositories, ensureWorkspaceIdentity, resolveDataRoot, workspaceStateRoot } from './machine-settings.mjs'
+import { createSelectionContinuity } from './selection-continuity.mjs'
+
+// A person's confirmed selection, bound to the maintenance runtime.
+//
+// A personal home keeps a history of the generations its person confirmed
+// (`selectPersonalGeneration` of the personal-workspace module). The loaders
+// here follow that history instead of naming a generation themselves:
+//
+//   read the head -> load the generation it names -> read the head again
+//
+// The head is read from the history alone, in the caller's thread: one
+// directory listing and one bounded read per record. Whether the generation
+// may be used is composition's to decide, as for any binding: in a worker for
+// a service, in the calling thread for a command run once. A head that moved
+// while the generation was loaded is another selection, and refuses
+// `personal-selection-changed`.
+//
+// Nothing is confirmed here and nothing is chosen for the person. A history
+// with no record, one that does not hold, a home that cannot be read and a
+// generation its composition refuses each refuse as a maintenance refusal
+// with the module's own code (`nothing-selected`, `selection-history-corrupt`,
+// `personal-home-unavailable`, `root-missing`, `stale-generation` and the
+// rest). There is no project to fall back to: an engine whose loader refuses
+// publishes nothing, and every view it knows says why.
+//
+// A loaded project is pinned to the record it was loaded under
+// (pinPersonalSelection), so the engine observes that record and the place of
+// the next one, and loads again at the tick after a confirmation or after the
+// history was cut short. At every full reconciliation the history is read
+// again, and a project whose record it no longer ends with is refused.
+//
+// A history never gets shorter through the module: selections are appended and
+// nothing removes one. So a history that ends at a lower record than this
+// process has read it ending at was cut short by something else, and following
+// it back could publish what nobody confirmed after the records removed. Every
+// read of the history's end is noted (notePersonalSelectionHead): the first
+// read here, the read once the generation is loaded, the recheck of a project
+// already loaded, and a read the engine asks for when its guard stops a view
+// because an observed file changed or could not be read (once for views
+// stopped one after another). A
+// history that ends earlier than the highest record noted requires a fresh confirmation or refuses
+// `selection-history-shortened` at a load and at a recheck; the guard's read only notes, and
+// its view says `mixed-read`. An engine whose project is pinned below the
+// highest record noted loads it again at its next tick
+// (personalSelectionBehind). A record added and removed between two of those
+// reads was never read, and does not count.
+//
+// The highest number, accepted head and observed record identities are also kept in the workspace's private
+// continuity state. A start of the service reads that evidence too. A shorter history remains refused until the
+// removed records return or the person makes a fresh confirmation. New confirmations have a unique identity, so
+// confirming the same generation against the same predecessor is distinct from restoring an old record's bytes.
+//
+// Who may see a vault stays the machine's setting: the engine initializes an undecided personal binding as owner only.
+//
+// Where the workspace is does not wait for a load: a bound project's folder is
+// its private home, so the home alone locates it (locatePersonalHome). A
+// service resolves its workspace from that at once, and starts, whether or not
+// a selection is confirmed; its engine then awaits the loader at each tick.
+
+// The decisions the oracles in test/obsidian-personal-selection.test.mjs are
+// sensitive to. Production always uses these; a test hands a loader a broken
+// one (`rules`) to prove that its oracle can fail.
+export const SELECTION_PRIMITIVES = Object.freeze({
+  // A history that ends at a lower record than this process has read is refused, at every read of it.
+  refusesShortened: true,
+  // The head is read again once the generation is loaded.
+  readsHeadAgain: true,
+  // What the loaded project is pinned for (pinPersonalSelection).
+  pin: Object.freeze({ observe: true, recheck: true }),
+})
+
+const SOURCE = Object.freeze({ source: 'personal-workspace' })
+const LOCATED = Symbol('atelier.obsidian.located-personal-home')
+
+const CONTINUITY = new Map()
+
+// Exclusion roots only, shared by location and continuity. Composition remains
+// the authority for the manifest and generation. Never wait on an irregular
+// file while resolving the machine's private state.
+function manifestExclusionRoots(personalHome) {
+  let manifest
+  let descriptor
+  try {
+    descriptor = fs.openSync(path.join(personalHome, 'atelier.personal.json'), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK ?? 0))
+    const stat = fs.fstatSync(descriptor)
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new PersonalWorkspaceRefusal('malformed-input')
+    const bytes = fs.readFileSync(descriptor)
+    if (bytes.length > 1024 * 1024) throw new PersonalWorkspaceRefusal('malformed-input')
+    try { manifest = JSON.parse(bytes) } catch { throw new PersonalWorkspaceRefusal('malformed-input') }
+    if (!Array.isArray(manifest?.repos) || manifest.repos.some((repo) => typeof repo?.root !== 'string' || !path.isAbsolute(repo.root) || repo.root.includes('\0'))) throw new PersonalWorkspaceRefusal('malformed-input')
+  } catch (error) {
+    refuse(error instanceof PersonalWorkspaceRefusal ? error.code : 'personal-home-unavailable', 'the personal workspace manifest could not be read; no selection is loaded', SOURCE)
+  } finally { if (descriptor !== undefined) fs.closeSync(descriptor) }
+  return manifest.repos.map((repo) => repo.root)
+}
+
+function continuityFor({ personalHome, dataRoot, env = process.env, platform = process.platform }) {
+  const project = locatePersonalHome({ personalHome })
+  const repositoryRoots = [personalHome, ...project.repos.map((repo) => repo.path)]
+  const rootOf = (named) => workspaceStateRoot(resolveDataRoot({ dataRoot, pointer: named, project, env, platform }), named.workspaceId)
+  // The location is proven outside every declared root before a first use writes its pointer.
+  const pointer = ensureWorkspaceIdentity({ project, ...(dataRoot === undefined ? {} : { dataRoot }),
+    validate: (named) => assertOutsideRepositories({ managedRoot: rootOf(named), repositoryRoots }) })
+  const root = rootOf(pointer)
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 })
+  const workspaceRoot = fs.realpathSync(root)
+  const key = `${personalHome}\0${workspaceRoot}`
+  // A retained store writes later, after the manifest may have changed: each write proves the location again from
+  // the manifest as it reads now, and a refusal there writes nothing.
+  if (!CONTINUITY.has(key)) CONTINUITY.set(key, createSelectionContinuity({ workspaceRoot, workspaceId: pointer.workspaceId, personalHome,
+    validateLocation: () => assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots: personalExclusionRootsNow(personalHome) }) }))
+  return CONTINUITY.get(key)
+}
+
+// The roots a personal home's private state must stay outside, read from its manifest now. Read-only.
+export function personalExclusionRootsNow(personalHome) {
+  return [personalHome, ...manifestExclusionRoots(personalHome)]
+}
+
+function confirmedHead(options, rules) {
+  const { personalHome } = options
+  locatePersonalHome({ personalHome })
+  let head
+  try { head = readPersonalSelectionSnapshot({ personalHome }) } catch (error) {
+    if (!(error instanceof PersonalWorkspaceRefusal)) throw error
+    refuse(error.code, 'the selection history of the personal workspace could not be read; nothing is loaded from it', SOURCE)
+  }
+  const continuity = continuityFor(options)
+  const note = (current) => { if (rules.refusesShortened) continuity.note(current) }
+  notePersonalSelectionHead(personalHome, head, { ...rules, note })
+  if (head.selected === null) refuse('nothing-selected', 'no generation of the personal workspace is confirmed; nothing is loaded until one is', SOURCE)
+  return { head, note }
+}
+
+function pinned(project, { head, note }, rules) {
+  pinPersonalSelection(project, head, { ...rules.pin, refusesShortened: rules.refusesShortened, note })
+  if (rules.readsHeadAgain) assertPersonalSelection(project)
+  return project
+}
+
+// What the workspace of a bound personal home is resolved from, without loading anything: a project that holds the home
+// as its folder, plus the manifest's repository roots for exclusion only. A locator never admits a generation or
+// notes a history head. Its pointer is under the home, the data root is the pointer's or the caller's, and a home is
+// outside every Git worktree. Synchronous; nothing is composed. A missing home still locates no prepared workspace.
+export function locatePersonalHome({ personalHome } = {}) {
+  if (typeof personalHome !== 'string' || !path.isAbsolute(personalHome) || path.resolve(personalHome) !== personalHome) refuse('path-not-absolute', 'a personal home is named by its absolute path', SOURCE)
+  let stat = null
+  try { stat = fs.lstatSync(personalHome) } catch (error) { if (error.code !== 'ENOENT') refuse('personal-home-unavailable', 'the personal home could not be inspected', SOURCE) }
+  if (stat !== null) {
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(personalHome) !== personalHome) refuse('root-symlinked', 'a personal home is its private directory, not a link', SOURCE)
+    if (typeof process.getuid !== 'function' || stat.uid !== process.getuid() || (stat.mode & 0o022) !== 0) refuse('not-private-location', 'a personal home is private to its owner', SOURCE)
+  }
+  // Include all declared roots, even a withdrawn enrollment: locating state
+  // must not write into a repository while composition is unavailable.
+  const roots = stat === null ? [] : manifestExclusionRoots(personalHome)
+  const located = { configDir: personalHome, repos: roots.map((root) => ({ path: root, external: false })), [LOCATED]: personalHome }
+  located.localState = ensureLocalState(located, { write: false, env: { PATH: process.env.PATH } })
+  return located
+}
+
+// The personal home a located or a loaded project follows, which a service it starts or a login item it installs is
+// given instead of a project (--personal-home); null for any other project.
+export const personalHomeOf = (project) => project?.[LOCATED] ?? personalSelectionOf(project)?.personalHome ?? null
+export { personalSelectionOf }
+
+// The project of the confirmed selection, for a loader that may block (a command run once). `bind` and `rules` are
+// test seams.
+export function loadSelectedProject(options = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const { personalHome } = options
+  const selected = confirmedHead(options, rules)
+  return pinned(loadBoundProject({ personalHome, generationId: selected.head.selected }, { bind }), selected, rules)
+}
+
+// The same, for a loader on a service's event loop: the composition runs in a worker, and the engine awaits it.
+export async function loadSelectedProjectOffThread(options = {}, { bind, rules = SELECTION_PRIMITIVES } = {}) {
+  const { personalHome } = options
+  const selected = confirmedHead(options, rules)
+  return pinned(await loadBoundProjectOffThread({ personalHome, generationId: selected.head.selected }, { bind }), selected, rules)
+}