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

package/src/projection/obsidian/recovery/store.mjs

@@ -7,7 +7,8 @@ import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularF
 
 // Private per-workspace state for one Obsidian view:
 //
-//   <workspaceRoot>/vaults/<scopeId>/                 the editable vault (or an explicit vaultRoot)
+//   <workspaceRoot>/vaults/<scopeId>/                 the editable vault, unless it was allocated elsewhere or a vaultRoot is named
+//   <workspaceRoot>/state/allocations/<scopeId>.json  where the view's vault was allocated, when it was (see below)
 //   <workspaceRoot>/state/manifests/<scopeId>/        trusted manifests and the current pointer
 //   <workspaceRoot>/state/journals/<scopeId>/<id>/    publication journals
 //   <workspaceRoot>/recovery/objects/<sha256>.bin     immutable content-addressed bytes
@@ -49,7 +50,15 @@ export const VAULT_LOCK_DIRECTORY = '.atelier-publication'
 // marker before its ticket, so the directory does not grow inside a person's
 // vault and an interrupted removal never leaves a marker without its ticket.
 export function acquireVaultLock(store) {
+  // Only in the vault the store was made for, reached through no link: the lock's folder is made inside whatever the
+  // vault root leads to.
+  let real = null
+  try { real = realPathAsStored(store.vaultRoot) } catch { /* not reachable: refused below */ }
+  if (real !== store.vaultRoot) refuse(store.allocation ? 'vault-allocation-moved' : 'vault-root-moved', 'the vault is no longer the folder this publication was prepared for: its path now leads somewhere else; nothing was written', { path: store.vaultRoot, leadsTo: real })
   const directory = ensureContainedPrivateDirectory({ workspaceRoot: store.vaultRoot, directory: path.dirname(store.vaultLockPath), label: 'vault publication lock' })
+  // The lock's folder resolved, again, to the one inside the vault: a link put there after the check above is refused
+  // before any ticket is written (only the empty folder may have been made through it).
+  if (directory !== path.dirname(store.vaultLockPath)) refuse(store.allocation ? 'vault-allocation-moved' : 'vault-root-moved', 'the vault is no longer the folder this publication was prepared for: its path now leads somewhere else; no lock was taken', { path: store.vaultRoot, leadsTo: path.dirname(directory) })
   const release = acquirePrivateLock(path.join(directory, path.basename(store.vaultLockPath)))
   try {
     const owners = `${store.vaultLockPath}.owners`
@@ -111,11 +120,135 @@ function publishOnce(file, bytes) {
   return true
 }
 
+// ---------------------------------------------------------------------------
+// Where a view's vault is
+// ---------------------------------------------------------------------------
+
+// A view of a workspace that decided where its vaults live gets a folder
+// there, allocated once at its first publication (by the maintenance engine)
+// and recorded, owner only, in the workspace's private state:
+//
+//   <workspaceRoot>/state/allocations/<scopeId>.json   atelier-obsidian-vault-allocation/v1
+//
+// A view without a record has its vault where every earlier release put it,
+// `<workspaceRoot>/vaults/<scopeId>`: a vault published there stays there
+// until it is moved, and a workspace that decided no place publishes there as
+// before. The record is the one thing that names another folder, and the
+// store reads it, so every reader of a view's vault (the engine, source apply,
+// the proposal adapter, `open`) finds the same one.
+
+export const VAULT_ALLOCATION_SCHEMA = 'atelier-obsidian-vault-allocation/v1'
+export const VAULT_ORIGINS = Object.freeze(['allocated', 'legacy-data-root'])
+
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+const CONTROL = /[\u0000-\u001f\u007f]/
+// `device` and `inode` name the folder that was made, as decimal strings (a 64-bit number does not fit a JSON number):
+// a folder at the recorded path that is another one (restored, moved in, made again by someone else) is never
+// published into.
+const ALLOCATION_KEYS = Object.freeze(['schema', 'workspaceId', 'scopeId', 'path', 'name', 'parent', 'device', 'inode', 'allocatedAt'])
+const DECIMAL = /^(0|[1-9][0-9]{0,19})$/
+const isPlainPath = (value) => typeof value === 'string' && value.length <= 4096 && !CONTROL.test(value) && path.isAbsolute(value) && path.resolve(value) === value
+
+export const allocationFile = (workspaceRoot, scopeId) => path.join(workspaceRoot, 'state', 'allocations', `${segment(scopeId)}.json`)
+export const legacyVaultRoot = (workspaceRoot, scopeId) => path.join(workspaceRoot, 'vaults', segment(scopeId))
+
+export function validateVaultAllocation(document, { workspaceId, scopeId }) {
+  const code = 'invalid-vault-allocation'
+  if (document === null || typeof document !== 'object' || Array.isArray(document)) refuse(code, 'a vault allocation is an object')
+  const unknown = Object.keys(document).filter((key) => !ALLOCATION_KEYS.includes(key))
+  if (unknown.length > 0 || ALLOCATION_KEYS.some((key) => !Object.hasOwn(document, key))) refuse(code, 'a vault allocation carries exactly its own members', { unknown: unknown.sort() })
+  if (document.schema !== VAULT_ALLOCATION_SCHEMA) refuse(code, 'a vault allocation names an unknown schema')
+  if (document.workspaceId !== workspaceId || document.scopeId !== scopeId || !IDENTIFIER.test(String(scopeId))) refuse(code, 'the vault allocation belongs to another workspace or view')
+  if (!isPlainPath(document.path) || !isPlainPath(document.parent)) refuse(code, 'the vault allocation names a folder that is not an absolute, plainly written path')
+  if (path.dirname(document.path) !== document.parent || path.basename(document.path) !== document.name) refuse(code, 'the vault allocation names its folder inconsistently')
+  if (typeof document.device !== 'string' || !DECIMAL.test(document.device) || typeof document.inode !== 'string' || !DECIMAL.test(document.inode)) refuse(code, 'the vault allocation names its folder\'s device and inode as decimal strings')
+  if (typeof document.allocatedAt !== 'string' || !TIMESTAMP.test(document.allocatedAt)) refuse(code, 'the vault allocation needs a UTC time')
+  return document
+}
+
+// The record of a view, validated, or null when it has none. Reads only.
+export function readVaultAllocation({ workspaceRoot, workspaceId, scopeId }) {
+  let text
+  try { text = readRegularTextNoFollow(allocationFile(workspaceRoot, scopeId)) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    return refuse('invalid-vault-allocation', 'the vault allocation cannot be read', { cause: error.code ?? String(error.message) })
+  }
+  let document
+  try { document = JSON.parse(text) } catch { return refuse('invalid-vault-allocation', 'the vault allocation is not JSON') }
+  return validateVaultAllocation(document, { workspaceId, scopeId })
+}
+
+// The device and inode of a folder, as an allocation records them; null when nothing is there.
+export function folderIdentity(folder) {
+  const stat = fs.lstatSync(folder, { bigint: true, throwIfNoEntry: false })
+  return stat === undefined ? null : { device: String(stat.dev), inode: String(stat.ino), directory: stat.isDirectory(), link: stat.isSymbolicLink() }
+}
+
+// Whether the folder at an allocation's path is the one it recorded: 'same', 'missing', or 'replaced'.
+export function allocatedFolderState(allocation) {
+  const found = folderIdentity(allocation.path)
+  if (found === null) return 'missing'
+  return found.directory && !found.link && found.device === allocation.device && found.inode === allocation.inode ? 'same' : 'replaced'
+}
+
+// Refuses, typed, unless the folder at an allocation's path is the one it recorded, at that real path: checked when a store is made, by
+// the maintenance engine before it uses a store again, and by the publisher before and after it takes the vault lock,
+// so a folder replaced while a service runs is never published into.
+export function assertAllocatedFolder(allocation) {
+  const found = allocatedFolderState(allocation)
+  if (found === 'missing') refuse('vault-allocation-missing', 'the folder allocated to this view is gone; the maintenance service makes it again at its next tick', { path: allocation.path })
+  if (found === 'replaced') refuse('vault-allocation-replaced', 'another folder is where this view\'s vault was allocated; Atelier publishes only into the folder it made', { path: allocation.path })
+  // Reached through no link: the record holds the folder's real path, so the same folder moved elsewhere (into a
+  // vault the app lists, say) and linked back, which keeps its device and inode, is not published into either.
+  let real = null
+  try { real = realPathAsStored(allocation.path) } catch { /* not reachable: refused below */ }
+  if (real !== allocation.path) refuse('vault-allocation-moved', 'this view\'s vault is now reached through a link, somewhere else than where it was allocated; Atelier publishes only into the folder at the path it recorded', { path: allocation.path, leadsTo: real })
+  return allocation
+}
+
+// Written only by the maintenance engine, under its lock, and by what moves a vault under the same lock.
+export function writeVaultAllocation({ workspaceRoot, allocation }) {
+  validateVaultAllocation(allocation, allocation)
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot, directory: path.dirname(allocationFile(workspaceRoot, allocation.scopeId)), label: 'Obsidian vault allocations' })
+  atomicReplacePrivateText(path.join(directory, path.basename(allocationFile(workspaceRoot, allocation.scopeId))), `${JSON.stringify(allocation, null, 2)}\n`)
+  return allocation
+}
+
+// A view without a record that was published, and has no vault under the data root, where a view published there
+// always has its folder: its record was lost (removed, or a backup restored without it), or, for a view that was never
+// allocated a folder, its folder under the data root was removed. Refused, typed, rather than published again into a
+// new, empty vault under the data root while a vault it had elsewhere stays orphaned.
+function refuseLostAllocation({ workspaceRoot, scopeId }) {
+  const legacy = legacyVaultRoot(workspaceRoot, scopeId)
+  if (!hasCommittedGeneration({ workspaceRoot, scopeId }) || fs.lstatSync(legacy, { throwIfNoEntry: false }) !== undefined) return
+  refuse('vault-allocation-lost', `this view was published, and its vault is not where Atelier can find it: there is no record of a folder allocated for it, and no folder under the data root. If its vault was allocated elsewhere, restore ${allocationFile(workspaceRoot, scopeId)} from a backup; otherwise, or to publish the view under the data root from now on, make the folder ${legacy}: the view is published there at the next change at its sources`, { record: allocationFile(workspaceRoot, scopeId), path: legacy })
+}
+
+// Where a view's vault is, without creating anything: { path, origin, allocation }.
+export function vaultRootFor({ workspaceRoot, workspaceId, scopeId }) {
+  const allocation = readVaultAllocation({ workspaceRoot, workspaceId, scopeId })
+  if (allocation === null) refuseLostAllocation({ workspaceRoot, scopeId })
+  return allocation === null
+    ? { path: legacyVaultRoot(workspaceRoot, scopeId), origin: 'legacy-data-root', allocation: null }
+    : { path: allocation.path, origin: 'allocated', allocation }
+}
+
+// Whether a view has a committed generation, whichever folder it was published into.
+export const hasCommittedGeneration = ({ workspaceRoot, scopeId }) => fs.existsSync(path.join(workspaceRoot, 'state', 'manifests', segment(scopeId), 'current.json'))
+
 // `repositoryRoots` is required: every enrolled repository root of the loaded
 // project. Neither the workspace state nor the vault may overlap one of them,
 // in either direction, lexically or by real path; the store refuses before it
 // creates anything. A caller with no enrolled repository (a test in a
 // temporary directory) says so with an explicit empty list.
+//
+// Without `vaultRoot` the vault is where the view's allocation says, else in
+// the workspace's `vaults/` (vaultRootFor). An allocated folder must be the
+// very folder the record names (device and inode): one that has gone is made
+// again by the maintenance engine under its lock (ensureVaultAllocation), and
+// until then, like one that another folder replaced, the store refuses. A
+// published view whose record was lost is refused too, never published again
+// into a new vault under the data root.
 export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vaultRoot, repositoryRoots } = {}) {
   if (typeof workspaceRoot !== 'string' || !path.isAbsolute(workspaceRoot)) throw new TypeError('workspaceRoot must be an absolute path')
   for (const [label, value] of [['workspaceId', workspaceId], ['scopeId', scopeId]]) {
@@ -125,20 +258,28 @@ export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vault
     throw new TypeError('repositoryRoots must list the absolute root of every enrolled repository; pass an explicit empty list when there is none')
   }
   if (vaultRoot !== undefined && (typeof vaultRoot !== 'string' || !path.isAbsolute(vaultRoot))) throw new TypeError('vaultRoot must be an absolute path')
-  const guard = checkManagedRoots({ managedRoots: [workspaceRoot, ...(vaultRoot === undefined ? [] : [vaultRoot])], repositoryRoots })
+  const allocation = vaultRoot === undefined ? readVaultAllocation({ workspaceRoot, workspaceId, scopeId }) : null
+  const namedVault = vaultRoot ?? allocation?.path
+  // A folder that is there but is not the one allocated (a link put where it was, say) is refused as such first, with
+  // its own next step; the checks below only read. One that has gone is checked against the repositories first.
+  if (allocation !== null && allocatedFolderState(allocation) !== 'missing') assertAllocatedFolder(allocation)
+  const guard = checkManagedRoots({ managedRoots: [workspaceRoot, ...(namedVault === undefined ? [] : [namedVault])], repositoryRoots })
   if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals })
+  if (allocation !== null) assertAllocatedFolder(allocation)
+  else if (vaultRoot === undefined) refuseLostAllocation({ workspaceRoot, scopeId })
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
   // Both as the file system stores them: the vault root is what the app is told, and what it compares its own
   // working-directory spelling with.
   const root = realPathAsStored(workspaceRoot)
   const privateDir = (...parts) => ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, ...parts), label: 'Obsidian publication state' })
-  const requestedVault = vaultRoot ?? path.join(root, 'vaults', segment(scopeId))
-  // A vault this store places itself is private to this user from the start: it will hold the plugin's bearer.
+  const requestedVault = namedVault ?? legacyVaultRoot(root, scopeId)
+  // A vault this store places itself, under the data root or where the view's vault was allocated, is private to this
+  // user from the start: it will hold the plugin's bearer.
   fs.mkdirSync(requestedVault, { recursive: true, ...(vaultRoot === undefined ? { mode: 0o700 } : {}) })
   const vault = realPathAsStored(requestedVault)
   const inside = (parent, child) => { const relative = path.relative(parent, child); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)) }
   for (const area of ['state', 'recovery', 'staging']) {
-    if (inside(path.join(root, area), vault) || inside(vault, path.join(root, area))) throw new TypeError('the vault may not overlap private publication state')
+    if (inside(path.join(root, area), vault) || inside(vault, path.join(root, area))) refuse('vault-overlaps-private-state', 'the vault may not overlap private publication state')
   }
   const manifests = privateDir('state', 'manifests', segment(scopeId))
   const journals = privateDir('state', 'journals', segment(scopeId))
@@ -152,10 +293,22 @@ export function createRecoveryStore({ workspaceRoot, workspaceId, scopeId, vault
     workspaceId,
     scopeId,
     vaultRoot: vault,
-    // Placed by this store under the workspace state, rather than named by the caller, and really there: a vault path
-    // that is a link leads to a folder someone else chose, which is only looked at and never receives the bearer.
+    // Placed by this store under the workspace state or where the view's vault was allocated, rather than named by the
+    // caller, and really there: a vault path that is a link leads to a folder someone else chose, which is only looked
+    // at and never receives the bearer.
     managedVaultRoot: vaultRoot === undefined && vault === requestedVault,
     linkedVaultRoot: vaultRoot === undefined && vault !== requestedVault,
+    // Where the vault is and why: named by the caller, allocated for the view, or under the data root.
+    vaultOrigin: vaultRoot !== undefined ? 'explicit' : allocation === null ? 'legacy-data-root' : 'allocated',
+    allocation,
+    // Refuses, typed, once the folder of an allocated vault is no longer the one this store was made for (see
+    // assertAllocatedFolder), and once any other vault root is gone or leads elsewhere (vault-root-moved).
+    checkAllocatedVault() {
+      if (allocation !== null) { assertAllocatedFolder(allocation); return }
+      let real = null
+      try { real = realPathAsStored(vault) } catch { /* gone: refused below */ }
+      if (real !== vault) refuse('vault-root-moved', 'this view\'s vault is gone, or its path now leads somewhere else; nothing more is written into it', { path: vault, leadsTo: real })
+    },
     journalsRoot: journals,
     lockPath: path.join(locks, `${segment(scopeId)}.lock`),
     // One publisher per vault, whichever view or workspace state it belongs to.

package/src/projection/obsidian/selection-ui/contribution.mjs

@@ -4,7 +4,7 @@ import { isoTime } from '../../../runtime/obsidian/documents.mjs'
 import { refuse } from '../../../runtime/obsidian/errors.mjs'
 import { protectedRoots, readMachineSettings } from '../../../runtime/obsidian/machine-settings.mjs'
 import { resolveScope } from '../../../runtime/obsidian/opening.mjs'
-import { DEFAULT_ELIGIBILITY, createProductionSeams } from '../../../runtime/obsidian/pipeline.mjs'
+import { createProductionSeams, eligibilityFor } from '../../../runtime/obsidian/pipeline.mjs'
 import { createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
 import { readConflictView } from './conflict-view.mjs'
 import { runPolicySetup } from './policy-setup.mjs'
@@ -28,8 +28,9 @@ const EXIT = Object.freeze({ ok: 0, notSuccess: 3 })
 const MAX_REQUEST_BYTES = 64 * 1024
 
 // The canonical snapshot selectScope reads, built exactly as the engine
-// builds it: the canonical graph with fail-closed eligibility, and the
-// declared relations whose both endpoints the census knows.
+// builds it: the canonical graph with the eligibility the machine settings
+// decide (fail closed), and the declared relations whose both endpoints the
+// census knows.
 function snapshotNow({ project, seams, eligibility }) {
   const graph = seams.buildGraph({ project, eligibility })
   const known = new Set(graph.nodes.map((node) => node.id))
@@ -49,7 +50,7 @@ function readRequest(value) {
   }
 }
 
-export function createSelectionOperation({ seams = createProductionSeams(), eligibility = DEFAULT_ELIGIBILITY } = {}) {
+export function createSelectionOperation({ seams = createProductionSeams(), eligibility: fixedEligibility = null } = {}) {
   return {
     name: 'selection',
     summary: 'resolve ID | persist ID [allow-empty] | show ID | list  The exact selected set of a declared view, its note paths and, for a focus, the graph query; persisted in Atelier state.',
@@ -74,7 +75,7 @@ export function createSelectionOperation({ seams = createProductionSeams(), elig
       const usable = workspace !== null && workspace.workspaceRoot !== null
       const machine = usable ? readMachineSettings(workspace) : null
       const profile = seams.profileFor({ project, workspaceId: workspace?.workspaceId ?? 'ws-unprepared', audienceAllow: machine?.audienceAllow ?? [] })
-      const canonicalSnapshot = snapshotNow({ project, seams, eligibility })
+      const canonicalSnapshot = snapshotNow({ project, seams, eligibility: fixedEligibility ?? eligibilityFor({ machine, project }) })
       const pathRegistry = usable ? createMaintenanceStateStore(workspace).readPathRegistry() : null
       // Explicit empty is an honest answer of `resolve`; `persist` of an empty selection is refused and asks for it by name.
       const selection = resolveSelection({ canonicalSnapshot, profile, scope, pathRegistry, allowEmpty: sub === 'resolve' || option === 'allow-empty' })

package/src/projection/project.mjs

@@ -3,6 +3,7 @@ import { isDeepStrictEqual } from 'node:util'
 import path from 'node:path'
 import { commandProject, readJson, writeJson } from '../project/config.mjs'
 import { summarizeReadinessJourney } from '../readiness-protocols/runtime.mjs'
+import { atelierControlStyles } from '../ui/control-system.mjs'
 
 const esc = (value) => String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
 
@@ -53,7 +54,7 @@ export function buildProjectProjection(project) {
     <h3>${esc(item.title)}</h3>
     <p><strong>${esc(item.status)}</strong> · ${esc(item.score)} / 100 answers complete</p>
     <p>${esc(item.blockers[0] || 'review-ready')}</p>
-    <button type="button" data-copy="${esc(item.agentPrompt)}">Copy protocol prompt</button>
+    <button type="button" class="system-control" data-variant="secondary" data-size="compact" data-copy="${esc(item.agentPrompt)}">Copy protocol prompt</button>
   </article>`).join('\n')
   const cards = graph.nodes.map((node) => `<article class="card" data-node="${esc(node.id)}">
     <p class="eyebrow">${esc(node.repo)} · ${esc(node.type)} · ${esc(node.audience)}</p>
@@ -80,9 +81,9 @@ h1{font-size:clamp(2rem,4vw,4rem);margin:.2em 0}
 .readiness-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px;margin-top:16px}
 .readiness-card{border:1px solid #342b26;border-radius:8px;padding:14px;background:#171312}
 .readiness-card h3{font-size:1.05rem;margin:.2rem 0}
-.readiness-card button{min-height:44px;border:1px solid #755f43;border-radius:6px;background:#241d18;color:var(--atelier-text);padding:8px 10px;cursor:pointer}
 .eyebrow{color:var(--atelier-eyebrow);text-transform:uppercase;letter-spacing:.08em;font-size:.8rem}
 a{color:var(--atelier-accent)}
+${atelierControlStyles}
 ${branding.themeCss}</style>
 </head>
 <body><main>

package/src/readiness/readiness.mjs

@@ -123,6 +123,13 @@ function buildPackageReadiness({
   }
 }
 
+// Paths in the written artifact are relative to the project config directory
+// in POSIX form, so `readiness --check` does not depend on where the project
+// is checked out and the artifact names no machine-specific directory.
+function configRelative(project, file) {
+  return path.relative(project.configDir, file).split(path.sep).join('/') || '.'
+}
+
 function buildProjectReadiness({ project, graph = null } = {}) {
   const loadedGraph = graph || (fs.existsSync(project.graphPath) ? readJson(project.graphPath) : null)
   const projectionEntry = path.join(project.outputRoot, 'index.html')
@@ -142,14 +149,14 @@ function buildProjectReadiness({ project, graph = null } = {}) {
     blockers,
     warnings,
     graph: {
-      path: project.graphPath,
+      path: configRelative(project, project.graphPath),
       nodes: loadedGraph?.counts?.nodes ?? loadedGraph?.nodes?.length ?? 0,
       edges: loadedGraph?.counts?.edges ?? loadedGraph?.edges?.length ?? 0,
       diagnostics: loadedGraph?.counts?.diagnostics ?? loadedGraph?.diagnostics?.length ?? 0,
     },
     projection: {
-      outputRoot: project.outputRoot,
-      entry: projectionEntry,
+      outputRoot: configRelative(project, project.outputRoot),
+      entry: configRelative(project, projectionEntry),
     },
     support: {
       telemetry: 'none',

package/src/reflection/index.mjs

@@ -0,0 +1,56 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-interaction.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true }); addFormats(ajv)
+const validators = new Map()
+export function validateInteraction(value, shape) {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  if (!['observation', 'assessment', 'act', 'policy'].includes(shape)) return ['unsupported interaction shape']
+  if (!validators.has(shape)) validators.set(shape, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(shape)
+  return validate(value) ? [] : validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+}
+export function assertInteraction(value, shape) {
+  const errors = validateInteraction(value, shape)
+  if (errors.length) throw new Error(`invalid ${shape}: ${errors.join('; ')}`)
+  return value
+}
+export function reflectionReference(record) {
+  const kind = record?.schema === 'atelier-reflection-observation@v1' ? 'observation' : 'assessment'
+  assertInteraction(record, kind)
+  return { kind, id: record.id, digest: digest(record) }
+}
+export function qualifyReflection({ assessment, observations, scope, purpose }) {
+  assertInteraction(assessment, 'assessment'); boundedLearningValue(observations)
+  if (!Array.isArray(observations) || observations.length > 128) throw new Error('bounded observations required')
+  for (const o of observations) assertInteraction(o, 'observation')
+  if (new Set(observations.map(o => o.id)).size !== observations.length) throw new Error('ambiguous observation identity')
+  const reasons = []
+  if (assessment.scope !== scope || assessment.purpose !== purpose || assessment.status !== 'active') reasons.push('assessment-outside-active-purpose')
+  if (!assessment.evidence.length) reasons.push('assessment-without-evidence')
+  if (new Set(assessment.evidence.map(e => `${e.kind}:${e.id}`)).size !== assessment.evidence.length) reasons.push('duplicate-evidence')
+  const admitted = []
+  for (const pin of assessment.evidence) {
+    const o = observations.find(o => o.id === pin.id)
+    if (pin.kind !== 'observation' || !o || digest(o) !== pin.digest || o.status !== 'active' || o.scope !== scope || o.purpose !== purpose) reasons.push(`evidence-stale-or-outside-purpose:${pin.id}`)
+    else admitted.push(o)
+  }
+  if (assessment.claimKind === 'independent-capacity' && (assessment.subject.kind !== 'person' || admitted.some(o => o.assistance !== 'independent' || o.subject.kind !== 'person' || o.subject.id !== assessment.subject.id))) reasons.push('independent-capacity-not-supported-by-admitted-evidence')
+  if (assessment.claimKind === 'system-friction' && assessment.subject.kind === 'person') reasons.push('system-friction-cannot-be-a-personal-capacity-claim')
+  return { reference: reflectionReference(assessment), current: reasons.length === 0, reasons,
+    uncertainty: assessment.uncertainty, limits: assessment.limits, semanticTruthVerified: false, observationAuthorityTransferred: false }
+}
+// The caller supplies an attributed judgment. This function qualifies its exact
+// evidence, never invents a developmental score or silently persists a profile.
+export function prepareReflectiveAct({ assessment, observations, act }) {
+  assertInteraction(act, 'act')
+  const result = qualifyReflection({ assessment, observations, scope: act.scope, purpose: act.purpose })
+  if (!result.current) throw new Error(`reflection unavailable: ${result.reasons.join('; ')}`)
+  if (act.origin !== 'witness' || !['reflective', 'coaching'].includes(act.mode)) throw new Error('reflective contribution requires Witness origin and declared mode')
+  const required = [reflectionReference(assessment), ...assessment.evidence]
+  for (const pin of required) if (!act.dependencies.some(p => digest(p) === digest(pin))) throw new Error('reflective act must pin its assessment and evidence')
+  if (act.mode === 'coaching' && !act.dependencies.some(p => p.kind === 'intention')) throw new Error('coaching requires a current chosen intention')
+  return { act: structuredClone(act), assessment: result, deliverable: false, executionAuthorized: false }
+}

package/src/runtime/obsidian/app-production-seams.mjs

@@ -1,25 +1,28 @@
-import { execFile, spawnSync } from 'node:child_process'
+import { execFile, execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
+import { performance } from 'node:perf_hooks'
 import path from 'node:path'
 import { NEUTRAL_DIRECTORY, defaultCliPath, defaultObsidianProcessProbe, routedCall } from '../../projection/obsidian/publication/transport.mjs'
 import { obsidianSandboxedBuild, obsidianUserDataDir, readObsidianSettings } from '../../projection/obsidian/publication/vault-list.mjs'
 import { realPathAsStored } from '../../project/private-state.mjs'
 import { appAnswered, readEvalAnswer, readVersionAnswer } from './app-capability.mjs'
-import { registerVaultInObsidianSettings } from './app-registration.mjs'
+import { backupObsidianSettings, registerVaultInObsidianSettings } from './app-registration.mjs'
+import { createAppQuitter } from './app-restart.mjs'
 import { launchPlan, runLaunchPlan, urlProcessed } from './launch-plan.mjs'
 
 // The production seams of `obsidian open` and of the service's adapter
-// factory: the only code that asks the installed Obsidian anything or asks the
-// operating system to open it.
+// factory: the only code that asks the installed Obsidian anything, asks the
+// operating system to open it, or quits it (for a restart a person asked for).
 //
 // This module is imported by exactly two places, both real command-line
 // entries and both behind an explicit `--adapter=obsidian-cli`: the service
 // entry (service-main.mjs) and the command entry (src/commands/obsidian.mjs,
 // `production: true`). No test of the default suite imports it in-process, and
-// importing it leaves a trace below that the test suite asserts is absent. One
-// test imports it in a child process, with a stand-in for the command-line
-// tool, to read the version answers it parses; the opt-in real-app suite
-// imports it to reach an isolated app through that app's private HOME.
+// importing it leaves a trace below that the test suite asserts is absent.
+// Tests import it in child processes only, with a private HOME: with a
+// stand-in for the command-line tool, to read the answers it parses, and with
+// a stand-in execFile, to check the launcher's executors; the opt-in real-app
+// suite imports it to reach an isolated app through that app's private HOME.
 //
 // Status: exercised against an isolated Obsidian 1.13.7 (installer 1.12.7) on
 // macOS by the opt-in real-app suite in test/obsidian-first-open-real-app.test.mjs;
@@ -127,7 +130,8 @@ function vaultRegisterCode(vaultRoot) {
 //   listThroughApp()                  -> { answered: true, vaults } | { answered: false, reason }
 //   registerThroughApp({ vaultRoot }) -> { answered: true, result } | { answered: false, reason }
 //   readSettings()                    -> readObsidianSettings answer (never writes)
-//   registerInSettings({ vaultRoot }) -> registerVaultInObsidianSettings answer
+//   registerInSettings({ vaultRoot, keepBackups }) -> registerVaultInObsidianSettings answer
+//   backupSettings()                  -> backupObsidianSettings answer (a copy beside the file; the file is not written)
 //
 // Through the app only while it runs and answers; in its settings file only
 // while no Obsidian runs, which registerVaultInObsidianSettings checks itself.
@@ -155,9 +159,13 @@ export function createProductionAppRegistry({
       return answer.answered ? { answered: true, result: answer.value?.result ?? null } : answer
     },
     readSettings: () => (sandbox === null ? readObsidianSettings({ userDataDir }) : sandboxed),
-    registerInSettings: ({ vaultRoot }) => (sandbox !== null ? sandboxed : userDataDir === null
+    // A copy of the settings file as it is, before a restart sends the app any signal (backupObsidianSettings).
+    backupSettings: () => (sandbox !== null ? sandboxed : userDataDir === null
       ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
-      : registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe })),
+      : backupObsidianSettings({ userDataDir })),
+    registerInSettings: ({ vaultRoot, keepBackups = [] }) => (sandbox !== null ? sandboxed : userDataDir === null
+      ? { ok: false, code: 'obsidian-settings-location-unknown', message: 'where Obsidian keeps its settings on this system is not known' }
+      : registerVaultInObsidianSettings({ userDataDir, vaultRoot, processProbe, keepBackups })),
   }
 }
 
@@ -167,18 +175,25 @@ export function createProductionAppRegistry({
 // the app itself answers the tool; a running app is handed the URL through its
 // tool, which takes a URL even with its command line turned off, and through the
 // operating system when the tool did not take it. A URL is never handed to the
-// operating system for an app this launch started. No shell.
+// operating system for an app this launch started. No shell. `execFile` is
+// node's, and a stand-in in the test of these executors, which runs in a child
+// process (the default suite never imports this module in-process).
 export function createProductionLauncher({
-  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep,
+  platform = process.platform, env = process.env, cliPath = defaultCliPath(platform), workingDirectory = NEUTRAL_DIRECTORY, waitMs, pollMs, sleep, execFile: runFile = execFile,
 } = {}) {
   const osCommand = platform === 'darwin' ? '/usr/bin/open' : platform === 'linux' ? 'xdg-open' : null
   const run = (file, args, timeout = 15_000) => new Promise((resolve) => {
-    execFile(file, args, { env, cwd: workingDirectory, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve({ failed: Boolean(error), stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }))
+    runFile(file, args, { env, cwd: workingDirectory, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => resolve({ failed: Boolean(error), stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }))
   })
   return {
-    open({ vaultId = null, vaultPath = null, appRunning }) {
+    // Starts a quit app with no URL, so it reopens the vaults its list flags open: for giving back an app `open`
+    // quit to restart it, when the vault could not be added after all. macOS only, as the restart is.
+    startPlain: async () => platform === 'darwin' && !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
+    // `startedByThisOpen`: this `open` started the app with an earlier launch; the link goes through its tool only.
+    open({ vaultId = null, vaultPath = null, appRunning, startedByThisOpen = false }) {
       const plan = launchPlan({ platform, appRunning, vaultId, vaultPath })
       return runLaunchPlan(plan, {
+        startedEarlier: startedByThisOpen === true,
         start: async () => !(await run(osCommand, ['-b', 'md.obsidian'])).failed,
         answered: async () => { const reply = await run(cliPath, ['version'], CLI_TIMEOUT_MS); return appAnswered({ stdout: reply.stdout, stderr: reply.stderr, exited: !reply.failed }) },
         handLink: async (uri) => urlProcessed((await run(cliPath, [uri], CLI_TIMEOUT_MS)).stdout),
@@ -189,6 +204,23 @@ export function createProductionLauncher({
   }
 }
 
+// Quits the running app for a restart a person asked for (app-restart.mjs): SIGTERM to its main process only, proven
+// from this machine's process table (`ps`, never a pattern search) as this account's, then waits until the process
+// probe says no Obsidian runs. The table is `pid ppid uid executable`; one process is described again by its parent,
+// user, start time and executable immediately before the signal.
+export function createProductionAppQuitter({ platform = process.platform, processProbe = () => defaultObsidianProcessProbe({ platform }), waitMs } = {}) {
+  const ps = (args) => execFileSync('/bin/ps', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024, timeout: 5000, killSignal: 'SIGKILL' })
+  return createAppQuitter({
+    platform, uid: typeof process.getuid === 'function' ? process.getuid() : null, processProbe,
+    readTable: () => ps(['-ww', '-A', '-o', 'pid=,ppid=,uid=,comm=']),
+    readProcess: (pid) => ps(['-ww', '-o', 'ppid=,uid=,lstart=,comm=', '-p', String(pid)]),
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    // The wait and the linger are measured on a monotonic clock: a step of the wall clock changes neither.
+    now: () => performance.now(),
+    ...(waitMs === undefined ? {} : { waitMs }),
+  })
+}
+
 export function createProductionAppSeams(options = {}) {
-  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options) }
+  return { appProbe: createProductionAppProbe(options), launcher: createProductionLauncher(options), registry: createProductionAppRegistry(options), quitter: createProductionAppQuitter(options) }
 }