@mnstry/atelier 0.2.0-alpha.5 → 0.2.0-alpha.8

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

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { acquirePrivateLock, publishPrivateFile } from '../../../project/durable-state.mjs'
+import { checkManagedRoots } from '../../../project/file-class.mjs'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow } from '../../../project/private-state.mjs'
+
+// Private per-workspace state for one Obsidian view:
+//
+//   <workspaceRoot>/vaults/<scopeId>/                 the editable vault (or an explicit vaultRoot)
+//   <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
+//   <workspaceRoot>/recovery/<journalId>/<unit>/      displaced files, receipts, and the unit's exchange candidate
+//   <workspaceRoot>/recovery/.exchange-probe/         scratch files of the exchange self-test, nothing else
+//   <workspaceRoot>/staging/<journalId>/              disposable generated bytes that no exchange ever names
+//   <vault>/.atelier-publication/                     the vault lock, shared by every view of the vault
+//
+// Immutable records are published with publishPrivateFile: a complete file
+// appears atomically under a name that is never overwritten. What that gives
+// is an all-or-nothing record that survives a process crash; it is fsynced,
+// which on some platforms is weaker than a full device flush. A displaced
+// file is different: it is the very file that occupied a note path, it is
+// moved and never copied over, and a program that still holds it open may
+// write into it later. It is therefore never treated as immutable; its digest
+// at the time of the move is recorded in a receipt and re-checked.
+//
+// A candidate that replaces an existing file is exchanged with it, so after
+// the exchange the candidate's path holds the displaced bytes. That path is
+// therefore in the unit's recovery directory, never in staging: staging is
+// discardable, and displaced bytes must not sit in a discardable area for an
+// instant. The candidate is written and fsynced in staging, where it is only
+// generated bytes, named with its digest by the journal, and only then moved
+// to its exchange path. What a file at an exchange path is, is decided from
+// the journal: bytes with the recorded candidate digest are generated and
+// ours; anything else is somebody's bytes and is kept. The candidate names
+// end in `.candidate`; everything else the store puts in a unit directory
+// ends in `.bin` or `.json`, so the names cannot collide.
+
+export const EXCHANGE_CANDIDATE_NAME = 'exchange.candidate'
+export const LATE_EXCHANGE_CANDIDATE_NAME = 'exchange.late.candidate'
+
+export const VAULT_LOCK_DIRECTORY = '.atelier-publication'
+
+// The vault lock, with the semantics of every private lock: the newest ticket
+// owns it, a release marker frees it, and a ticket whose process is gone on
+// this host is stale and is taken over. Nothing else is ever written here.
+// Tickets of superseded generations are removed while the lock is held, the
+// 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) {
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: store.vaultRoot, directory: path.dirname(store.vaultLockPath), label: 'vault publication lock' })
+  const release = acquirePrivateLock(path.join(directory, path.basename(store.vaultLockPath)))
+  try {
+    const owners = `${store.vaultLockPath}.owners`
+    const names = fs.readdirSync(owners).filter((name) => /^\d{12}\.(json|released)$/.test(name)).sort()
+    const newest = names.filter((name) => name.endsWith('.json')).at(-1)?.slice(0, 12)
+    for (const name of names.filter((item) => item.slice(0, 12) < newest).sort((left, right) => (left.endsWith('.released') ? -1 : 1) - (right.endsWith('.released') ? -1 : 1))) {
+      fs.rmSync(path.join(owners, name), { force: true })
+    }
+  } catch { /* history that cannot be pruned is harmless */ }
+  return release
+}
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+
+export const sha256Digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`
+
+export class PublicationRefusal extends Error {
+  constructor(code, message, detail = {}) {
+    super(`${code}: ${message}`)
+    this.name = 'PublicationRefusal'
+    this.code = code
+    this.detail = detail
+  }
+}
+
+export function refuse(code, message, detail) {
+  throw new PublicationRefusal(code, message, detail)
+}
+
+// Identifiers become directory names. ':' is legal in an identifier and is not
+// legal in a file name everywhere.
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export function readFileDigest(file) {
+  let descriptor
+  try {
+    descriptor = openRegularFileNoFollow(file)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try { return sha256Digest(fs.readFileSync(descriptor)) } finally { fs.closeSync(descriptor) }
+}
+
+export function readFileBytes(file) {
+  const descriptor = openRegularFileNoFollow(file)
+  try { return fs.readFileSync(descriptor) } finally { fs.closeSync(descriptor) }
+}
+
+function publishOnce(file, bytes) {
+  try {
+    publishPrivateFile(file, bytes)
+  } catch (error) {
+    // The name is taken by different bytes. An immutable record is never replaced.
+    if (error.code !== 'EEXIST') throw error
+    return false
+  }
+  return true
+}
+
+// `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.
+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]]) {
+    if (typeof value !== 'string' || !IDENTIFIER.test(value)) throw new TypeError(`${label} must be a contract identifier`)
+  }
+  if (!Array.isArray(repositoryRoots) || repositoryRoots.some((item) => typeof item !== 'string' || !path.isAbsolute(item))) {
+    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 })
+  if (!guard.ok) refuse(guard.refusals[0].code, guard.refusals[0].message, { refusals: guard.refusals })
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  const root = fs.realpathSync(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))
+  fs.mkdirSync(requestedVault, { recursive: true })
+  const vault = fs.realpathSync(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')
+  }
+  const manifests = privateDir('state', 'manifests', segment(scopeId))
+  const journals = privateDir('state', 'journals', segment(scopeId))
+  const locks = privateDir('state', 'locks')
+  const objects = privateDir('recovery', 'objects')
+  const staging = privateDir('staging')
+  const pointerFile = path.join(manifests, 'current.json')
+
+  const store = {
+    workspaceRoot: root,
+    workspaceId,
+    scopeId,
+    vaultRoot: vault,
+    journalsRoot: journals,
+    lockPath: path.join(locks, `${segment(scopeId)}.lock`),
+    // One publisher per vault, whichever view or workspace state it belongs to.
+    // Two stores share nothing but the vault, so this lock lives under the
+    // vault's real path, in a dot-directory no note path can name.
+    vaultLockPath: path.join(vault, VAULT_LOCK_DIRECTORY, 'vault.lock'),
+    ref: (absolute) => path.relative(root, absolute).split(path.sep).join('/'),
+    resolve(ref) {
+      const absolute = path.resolve(root, ref)
+      if (!inside(root, absolute) || absolute === root) throw new TypeError('a store reference must stay inside the workspace state')
+      return absolute
+    },
+    journalDir: (journalId) => privateDir('state', 'journals', segment(scopeId), segment(journalId)),
+    stagingDir: (journalId) => privateDir('staging', segment(journalId)),
+    stagingRoot: staging,
+    // Where the exchange self-test runs: inside recovery, because that is where exchange candidates live.
+    exchangeProbeDir: () => privateDir('recovery', '.exchange-probe'),
+    // Generated bytes on their way to a path: written here, and for a created file linked from here.
+    preparedPath: (journalId, unit, { late = false } = {}) => path.join(store.stagingDir(journalId), `${String(unit).padStart(6, '0')}${late ? '.late' : ''}.candidate`),
+    // The path handed to the exchange. Computed without creating anything; unitDir creates the directory.
+    exchangeCandidatePath: (journalId, unit, { late = false } = {}) => path.join(root, 'recovery', segment(journalId), String(unit).padStart(6, '0'), late ? LATE_EXCHANGE_CANDIDATE_NAME : EXCHANGE_CANDIDATE_NAME),
+    unitsRoot: (journalId) => path.join(root, 'recovery', segment(journalId)),
+    unitDir: (journalId, unit) => privateDir('recovery', segment(journalId), String(unit).padStart(6, '0')),
+    displacedPath: (journalId, unit, name = 'displaced.bin') => path.join(store.unitDir(journalId, unit), name),
+
+    // Immutable, content-addressed bytes (a base, an observed edit, an outside writer's bytes).
+    retainObject(bytes) {
+      const digest = sha256Digest(bytes)
+      const file = path.join(objects, `${digest.slice('sha256:'.length)}.bin`)
+      publishPrivateFile(file, bytes)
+      return { digest, ref: store.ref(file) }
+    },
+    readObject(digest) {
+      if (!DIGEST.test(digest)) throw new TypeError('digest required')
+      const bytes = readFileBytes(path.join(objects, `${digest.slice('sha256:'.length)}.bin`))
+      if (sha256Digest(bytes) !== digest) refuse('recovery-object-corrupt', 'a retained object no longer matches its name')
+      return bytes
+    },
+    writeReceipt(journalId, unit, receipt) {
+      const body = Buffer.from(`${JSON.stringify({ schema: 'atelier-obsidian-recovery-receipt/v1', journalId, unit, ...receipt }, null, 2)}\n`, 'utf8')
+      const file = path.join(store.unitDir(journalId, unit), `receipt-${receipt.role}-${sha256Digest(body).slice(7, 19)}.json`)
+      publishOnce(file, body)
+      return store.ref(file)
+    },
+    listReceipts(journalId) {
+      const base = path.join(root, 'recovery', segment(journalId))
+      if (!fs.existsSync(base)) return []
+      const receipts = []
+      for (const unit of fs.readdirSync(base).sort()) {
+        for (const name of fs.readdirSync(path.join(base, unit)).filter((entry) => /^receipt-.*\.json$/.test(entry)).sort()) {
+          receipts.push(JSON.parse(readRegularTextNoFollow(path.join(base, unit, name))))
+        }
+      }
+      return receipts
+    },
+
+    // Trusted manifest. The manifest file is immutable; only the small pointer
+    // is replaced, and only as the last step of a publication.
+    readCurrent() {
+      let text
+      try { text = readRegularTextNoFollow(pointerFile) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+      const pointer = JSON.parse(text)
+      if (pointer.scopeId !== scopeId || pointer.workspaceId !== workspaceId) refuse('state-mismatch', 'the manifest pointer belongs to another view')
+      return pointer
+    },
+    readCurrentManifest() {
+      const pointer = store.readCurrent()
+      if (!pointer) return null
+      const bytes = readFileBytes(path.join(manifests, pointer.manifestFile))
+      if (sha256Digest(bytes) !== pointer.manifestDigest) refuse('state-mismatch', 'the trusted manifest no longer matches its pointer')
+      return JSON.parse(bytes.toString('utf8'))
+    },
+    commitManifest({ manifestBytes, generationId, journalId, retained = [], committedAt }) {
+      const manifestDigest = sha256Digest(manifestBytes)
+      const manifestFile = `${segment(generationId)}--${manifestDigest.slice(7, 19)}.json`
+      publishPrivateFile(path.join(manifests, manifestFile), manifestBytes)
+      const pointer = { schema: 'atelier-obsidian-current-manifest/v1', workspaceId, scopeId, generationId, manifestFile, manifestDigest, journalId, committedAt, retained }
+      atomicReplacePrivateText(pointerFile, `${JSON.stringify(pointer, null, 2)}\n`)
+      return pointer
+    },
+  }
+  return store
+}

package/src/projection/obsidian/selection-ui/conflict-view.mjs

@@ -0,0 +1,91 @@
+import { compareText } from '../../../runtime/obsidian/documents.mjs'
+import { OPEN_EDIT_STATES, createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
+import { openObjectStore } from '../edits/object-store.mjs'
+
+// A read-only, typed view of the shared conflict state AOP-2's arbitration
+// keeps per object: which objects are conflicted, pending, settled or
+// unreadable, which operations are involved and why, and which pending edit
+// records of which views feed them. Identities, states, codes and digests
+// only: no note text, title or path.
+//
+// `conflictView` is pure: it is a function of the object entries (the
+// object store's `list()` or an `arbitrateEvents` summary) and the pending
+// edit records. `readConflictView` reads both from the workspace's private
+// state. Neither decides anything, writes an event or touches a source file
+// or a vault.
+
+export const CONFLICT_VIEW_SCHEMA = 'atelier-obsidian-conflict-view/v1'
+export const OBJECT_VIEW_STATES = Object.freeze(['conflicted', 'pending', 'settled', 'empty', 'inconsistent', 'unreadable'])
+
+// What a person or an agent does next. A conflict is resolved by a new
+// operation that names the ones it resolves; nothing here chooses a winner.
+const NEXT = Object.freeze({
+  conflicted: 'offer a resolution that names every conflicted operation; no operation is dropped and no winner is chosen',
+  pending: 'apply explicitly, or let an active automatic policy dispatch it',
+  settled: 'nothing: every recorded operation is applied, superseded or refused',
+  empty: 'nothing: no operation is recorded for this object',
+  inconsistent: 'a person looks at the object log; an event the log did not allow is recorded',
+  unreadable: 'a person looks at the object directory; nothing is decided until then',
+})
+
+const NEEDS_PERSON = new Set(['conflicted', 'inconsistent', 'unreadable'])
+
+function operationView(operation) {
+  return {
+    idempotencyKey: operation.idempotencyKey,
+    kind: operation.kind ?? null,
+    state: operation.state,
+    reason: operation.reason ?? null,
+    by: operation.by ?? null,
+  }
+}
+
+export function conflictView({ objects, edits = [], scopeId } = {}) {
+  if (!Array.isArray(objects)) throw new TypeError('conflictView needs the list of object entries')
+  const openEdits = edits.filter((edit) => OPEN_EDIT_STATES.includes(edit.state) && (scopeId === undefined || edit.scopeId === scopeId))
+  const editsOf = (repoId, nodeId) => openEdits
+    .filter((edit) => edit.identity?.repoId === repoId && edit.identity?.nodeId === nodeId)
+    .map((edit) => ({ editId: edit.editId, scopeId: edit.scopeId, state: edit.state, lastCode: edit.lastResult?.code ?? null }))
+    .sort((left, right) => compareText(left.scopeId, right.scopeId) || compareText(left.editId, right.editId))
+
+  const entries = objects.map((object) => {
+    const state = OBJECT_VIEW_STATES.includes(object.state) ? object.state : 'unreadable'
+    const identity = object.identity ?? object
+    const repoId = identity.repoId ?? null
+    const nodeId = identity.nodeId ?? null
+    const operations = (object.operations ?? []).map(operationView)
+    const intentOutcomeUnknown = object.intentOutcomeUnknown === true || (object.intent !== undefined && object.intent !== null)
+    const needsPerson = NEEDS_PERSON.has(state) || intentOutcomeUnknown
+    return {
+      repoId, nodeId, state,
+      code: object.code ?? null,
+      sourceDigest: object.sourceDigest ?? null,
+      leaseHeld: object.leaseHeld === true || (object.lease !== undefined && object.lease !== null),
+      intentOutcomeUnknown,
+      operations,
+      conflictedOperations: operations.filter((operation) => operation.state === 'conflicted').map((operation) => operation.idempotencyKey),
+      pendingEdits: repoId === null ? [] : editsOf(repoId, nodeId),
+      needsPerson,
+      next: intentOutcomeUnknown && !NEEDS_PERSON.has(state) ? 'an apply was started and its outcome is not recorded; the next lease holder reads the source and decides' : NEXT[state],
+    }
+  }).sort((left, right) => compareText(left.repoId ?? '', right.repoId ?? '') || compareText(left.nodeId ?? '', right.nodeId ?? ''))
+
+  const byState = Object.fromEntries(OBJECT_VIEW_STATES.map((state) => [state, entries.filter((entry) => entry.state === state).length]))
+  return {
+    schema: CONFLICT_VIEW_SCHEMA,
+    scopeId: scopeId ?? null,
+    objects: entries,
+    summary: { total: entries.length, byState, needsPerson: entries.filter((entry) => entry.needsPerson).length, openEdits: openEdits.length },
+    needsPerson: entries.some((entry) => entry.needsPerson),
+  }
+}
+
+// Reads the object index (a cache the store rebuilds from the events where
+// it is not current) and the pending edit records of the workspace.
+export function readConflictView({ workspaceRoot, workspaceId, repositoryRoots, clock, scopeId, objectStore = openObjectStore }) {
+  const store = objectStore({ stateRoot: workspaceRoot, workspaceId, repositoryRoots, clock })
+  const { objects, foreign } = store.list(scopeId === undefined ? {} : { scopeId })
+  const edits = createMaintenanceStateStore({ workspaceRoot, workspaceId }).readPendingEdits().edits
+  const view = conflictView({ objects, edits, scopeId })
+  return { ...view, foreign }
+}

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

@@ -0,0 +1,141 @@
+import fs from 'node:fs'
+import path from 'node:path'
+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 { createMaintenanceStateStore } from '../../../runtime/obsidian/state-store.mjs'
+import { readConflictView } from './conflict-view.mjs'
+import { runPolicySetup } from './policy-setup.mjs'
+import { listSelectionStates, readSelectionState, writeSelectionState } from './selection-state.mjs'
+import { resolveSelection } from './selection.mjs'
+
+// The `obsidian` command operations of selection, conflict state and policy
+// setup, registered on the command's operation registry the way AOP-1 laid
+// out: a contribution `{ id, register({ operations }) }`. Nothing in the
+// command dispatcher is edited. The built-in `scope`, `policy` and `mode`
+// names are reserved, so these are `selection`, `conflicts` and
+// `apply-policy`.
+//
+// Every operation is noninteractive and read-only towards sources, vaults
+// and the app: `selection persist` writes the workspace's private selection
+// state, `apply-policy create|revoke` write the private policy files through
+// AOP-1's installer and revocation, and nothing else writes at all.
+
+export const SELECTION_CONTRIBUTION_ID = 'atelier.selection-ui'
+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.
+function snapshotNow({ project, seams, eligibility }) {
+  const graph = seams.buildGraph({ project, eligibility })
+  const known = new Set(graph.nodes.map((node) => node.id))
+  return { nodes: graph.nodes, edges: graph.edges.filter((edge) => known.has(edge.source) && known.has(edge.target)) }
+}
+
+// FILE is resolved from the working directory of the process, as the built-in `policy install FILE` resolves its file.
+function readRequest(value) {
+  if (value === undefined) refuse('usage', 'apply-policy create FILE')
+  const file = path.resolve(value)
+  try {
+    if (fs.statSync(file).size > MAX_REQUEST_BYTES) refuse('invalid-apply-policy', 'the request file is larger than a request can be')
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    if (typeof error?.code === 'string' && error.name === 'ObsidianMaintenanceRefusal') throw error
+    return refuse('invalid-apply-policy', 'the request file cannot be read as JSON', { cause: error.code ?? 'not-json' })
+  }
+}
+
+export function createSelectionOperation({ seams = createProductionSeams(), eligibility = DEFAULT_ELIGIBILITY } = {}) {
+  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.',
+    async run({ args, readable, writable, clock }) {
+      const [sub = 'list', requested, option] = args
+      if (option !== undefined && !(sub === 'persist' && option === 'allow-empty')) refuse('usage', 'selection persist ID [allow-empty]')
+      if (sub === 'list') {
+        const { workspace, workspaceId } = readable()
+        const selections = workspace === null ? [] : listSelectionStates({ workspaceRoot: workspace.workspaceRoot, workspaceId })
+        return { exit: EXIT.ok, document: { selections }, human: selections.length === 0 ? ['no persisted selection'] : selections.map((item) => `${item.scopeId}\t${item.mode}\t${item.updatedAt}${item.focus ? `\t${item.focus.paths.length} focused note(s)` : ''}`) }
+      }
+      if (!['resolve', 'persist', 'show'].includes(sub)) refuse('usage', 'selection resolve ID | persist ID | show ID | list')
+      if (sub === 'show') {
+        const { enablement, workspace, workspaceId } = readable()
+        const scopeId = resolveScope(enablement, requested)
+        const selection = workspace === null ? null : readSelectionState({ workspaceRoot: workspace.workspaceRoot, workspaceId, scopeId })
+        return { exit: selection === null ? EXIT.notSuccess : EXIT.ok, document: { scopeId, persisted: selection !== null, selection }, human: [selection === null ? `no persisted selection for ${scopeId}` : JSON.stringify(selection, null, 2)] }
+      }
+      const { project, enablement, workspace, repositoryRoots, now } = sub === 'persist' ? writable() : { ...readable(), repositoryRoots: null, now: isoTime(clock) }
+      const scopeId = resolveScope(enablement, requested)
+      const scope = enablement.scopes.find((item) => item.scopeId === scopeId)
+      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 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' })
+      if (sub === 'resolve') {
+        return { exit: EXIT.ok, document: { scopeId, selection, persisted: false }, human: [`${scopeId}: ${selection.mode}, ${selection.nodes.length} note(s), ${selection.edges.length} edge(s)${selection.truncated ? ', expansion truncated' : ''}${selection.focus ? `; focus query ${selection.focus.query}` : ''}`] }
+      }
+      const written = writeSelectionState({ workspaceRoot: workspace.workspaceRoot, workspaceId: workspace.workspaceId, repositoryRoots, selection, now })
+      return { exit: EXIT.ok, document: { scopeId, selection, persisted: true, changed: written.changed, file: path.relative(workspace.workspaceRoot, written.file).split(path.sep).join('/') }, human: [`${scopeId}: persisted${written.changed ? '' : ' (unchanged)'}; ${selection.nodes.length} note(s)${selection.focus ? `; focus query ${selection.focus.query}` : ''}`, 'No file under .obsidian/ was written; apply a focus in the app.'] }
+    },
+  }
+}
+
+export function createConflictsOperation() {
+  return {
+    name: 'conflicts',
+    summary: '[ID]  The shared conflict state of edited objects, read from the arbitration record: what is conflicted, pending or unreadable, and what a person does next. Read-only.',
+    async run({ args, readable, clock }) {
+      const [requested] = args
+      const { project, enablement, workspace, workspaceId } = readable()
+      const scopeId = requested === undefined ? undefined : resolveScope(enablement, requested)
+      if (workspace === null) return { exit: EXIT.ok, document: { scopeId: scopeId ?? null, objects: [], summary: { total: 0 }, needsPerson: false, workspace: 'not-prepared' }, human: ['no private state yet: no edit was ever recorded'] }
+      const view = readConflictView({ workspaceRoot: workspace.workspaceRoot, workspaceId, repositoryRoots: protectedRoots(project), clock, scopeId })
+      return {
+        exit: EXIT.ok, document: view,
+        human: view.objects.length === 0 ? ['no recorded object'] : view.objects.map((object) => `${object.repoId}\t${object.nodeId}\t${object.state}${object.needsPerson ? '\tneeds a person' : ''}\t${object.next}`),
+      }
+    },
+  }
+}
+
+export function createApplyPolicyOperation() {
+  return {
+    name: 'apply-policy',
+    summary: 'create FILE | show | revoke  Build, digest and install a manual or automatic apply policy from a JSON request; show it; revoke it durably.',
+    async run({ args, readable, writable }) {
+      const [action, value] = args
+      if (action === undefined || action === 'show') {
+        const { workspace } = readable()
+        if (workspace === null) return { exit: EXIT.ok, document: { ok: true, action: 'show', installed: false, policy: null, reference: null, automaticApply: { authorized: false, reason: 'machine-settings-absent' } }, human: ['no apply policy is installed'] }
+        const result = runPolicySetup({ action: 'show', workspace })
+        return { exit: result.ok ? EXIT.ok : EXIT.notSuccess, document: result, human: [result.ok ? (result.installed ? `${result.policy.policyId} v${result.policy.version} ${result.policy.mode} ${result.policy.status}; automatic apply ${result.automaticApply.authorized ? 'authorized' : `not authorized (${result.automaticApply.reason})`}` : 'no apply policy is installed') : `[${result.refusal.code}] ${result.refusal.message}`] }
+      }
+      if (action !== 'create' && action !== 'revoke') refuse('usage', 'apply-policy create FILE | show | revoke')
+      const input = action === 'create' ? readRequest(value) : {}
+      const { workspace, repositoryRoots, now } = writable()
+      const result = runPolicySetup({ action, input, workspace, repositoryRoots, now })
+      const human = result.ok
+        ? [action === 'create' ? `installed ${result.policy.policyId} v${result.policy.version} (${result.policy.mode}, ${result.policy.status}); maintenance mode ${result.maintenanceMode}` : (result.revoked ? `revoked (${result.reason}); no queued edit is applied from now on, and the mode is manual` : 'no apply policy was installed')]
+        : [`[${result.refusal.code}] ${result.refusal.message}`]
+      return { exit: result.ok ? EXIT.ok : EXIT.notSuccess, document: result, human }
+    },
+  }
+}
+
+export function createSelectionContribution(options = {}) {
+  return {
+    id: SELECTION_CONTRIBUTION_ID,
+    register({ operations }) {
+      operations.register(createSelectionOperation(options))
+      operations.register(createConflictsOperation())
+      operations.register(createApplyPolicyOperation())
+    },
+  }
+}

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

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto'
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+
+// Focus: the full vault stays on disk and the native Graph view is filtered
+// with a "Search files" query derived from the selected set. The query names
+// every selected note by its exact vault-relative path, quoted and escaped
+// the way the app's search syntax reads a quoted term, joined with OR.
+//
+// Nothing here writes a file. The query and the core-Bookmark payload are
+// values a person, an agent or the acceptance procedure applies in the app;
+// `.obsidian/workspace.json`, `.obsidian/graph.json` and
+// `.obsidian/bookmarks.json` belong to the person and are never written by
+// Atelier. Whether the installed app applies the query as built is an
+// acceptance question (AP-02), not something this module can answer.
+
+export const FOCUS_QUERY_VERSION = 'obsidian-graph-search-paths/v1'
+export const FOCUS_BOOKMARK_TYPE = 'graph'
+// The files under .obsidian/ the app's UI owns. Atelier reads none of them
+// and writes none of them; a focus is applied through the app, never by
+// editing these.
+export const UI_OWNED_SETTINGS_FILES = Object.freeze(['workspace.json', 'graph.json', 'bookmarks.json'])
+export const MAX_FOCUS_PATHS = 100000
+
+// A quoted search term: backslash and double quote are escaped; anything
+// that is not printable text cannot be typed into a search box and refuses.
+export const FOCUS_QUERY_PRIMITIVES = Object.freeze({
+  escape(value) {
+    return value.replace(/[\\"]/g, (character) => `\\${character}`)
+  },
+  term(path) {
+    return `path:"${path}"`
+  },
+  join(terms) {
+    return terms.join(' OR ')
+  },
+})
+
+function normalizePath(value, index) {
+  if (typeof value !== 'string' || value === '') refuse('focus-path-unrepresentable', 'a focus path must be a non-empty string', { index })
+  const normalized = value.normalize('NFC')
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(normalized)) refuse('focus-path-unrepresentable', 'a focus path carries a control character and cannot be a search term', { index })
+  if (normalized.startsWith('/') || normalized.includes('\\') || normalized.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+    refuse('focus-path-unrepresentable', 'a focus path must be a normalized vault-relative path', { index })
+  }
+  return normalized
+}
+
+// Test seam: the oracles in test/obsidian-acceptance.test.mjs substitute a
+// builder that drops escaping to prove the escaping oracle can fail.
+// Production uses buildFocusQuery.
+export function createFocusQueryBuilderForOracleTests(primitives = FOCUS_QUERY_PRIMITIVES) {
+  const { escape, term, join } = { ...FOCUS_QUERY_PRIMITIVES, ...primitives }
+  return function buildFocusQuery(paths) {
+    if (!Array.isArray(paths)) refuse('focus-selection-empty', 'a focus needs the list of selected note paths')
+    if (paths.length === 0) refuse('focus-selection-empty', 'a focus with no selected note would filter nothing; it is refused, never widened to the whole vault')
+    if (paths.length > MAX_FOCUS_PATHS) refuse('focus-too-large', `a focus names at most ${MAX_FOCUS_PATHS} notes`, { count: paths.length })
+    const normalized = paths.map(normalizePath)
+    if (new Set(normalized).size !== normalized.length) refuse('duplicate-identity', 'a focus names a note path more than once')
+    // The order is the order given (canonical-id order from the selection), so the same selection is the same query.
+    const terms = normalized.map((path) => term(escape(path)))
+    const query = join(terms)
+    return {
+      version: FOCUS_QUERY_VERSION,
+      query,
+      queryDigest: `sha256:${createHash('sha256').update(query, 'utf8').digest('hex')}`,
+      paths: normalized,
+    }
+  }
+}
+
+export const buildFocusQuery = createFocusQueryBuilderForOracleTests()
+
+// The payload of a core-plugin graph bookmark that retains this focus. The
+// app assigns the creation time when the bookmark is made there; nothing
+// nondeterministic is part of the payload. Only the graph type is supported:
+// core Bookmarks retain graph views, not local-graph views.
+export function focusBookmarkPayload({ scopeId, query }) {
+  if (typeof scopeId !== 'string' || scopeId === '') refuse('invalid-scope', 'a focus bookmark names its scope')
+  if (typeof query !== 'string' || query === '') refuse('focus-selection-empty', 'a focus bookmark carries a non-empty query')
+  return { type: FOCUS_BOOKMARK_TYPE, title: `Atelier focus ${scopeId}`, options: { search: query } }
+}

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

@@ -0,0 +1,12 @@
+// Selection, focus, apply policy setup, conflict state and acceptance receipt
+// validation for the Obsidian projection. Selection and focus are pure;
+// selection state, policy setup and the conflict view read and write the
+// workspace's private state through the runtime's own primitives; the receipt
+// validator is schema validation only and closes no gate.
+export { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_PRIMITIVES, FOCUS_QUERY_VERSION, MAX_FOCUS_PATHS, UI_OWNED_SETTINGS_FILES, buildFocusQuery, createFocusQueryBuilderForOracleTests, focusBookmarkPayload } from './focus.mjs'
+export { EMPTY_SELECTION_REASONS, SCOPE_CONTRACT_SCHEMA, SELECTION_SCHEMA, resolveSelection, scopeDocumentOf } from './selection.mjs'
+export { SELECTION_DIRECTORY, SELECTION_STATE_SCHEMA, assertWritableSelectionPath, listSelectionStates, readSelectionState, selectionStateDocument, validateSelectionState, writeSelectionState } from './selection-state.mjs'
+export { CONFLICT_DISPOSITION, DEFAULT_MAX_BATCH_SIZE, DEFAULT_RETRY_BUDGET, POLICY_SETUP_ACTIONS, POLICY_SETUP_SCHEMA, buildApplyPolicy, dispatchGate, runPolicySetup } from './policy-setup.mjs'
+export { CONFLICT_VIEW_SCHEMA, OBJECT_VIEW_STATES, conflictView, readConflictView } from './conflict-view.mjs'
+export { ACCEPTANCE_KINDS, RECEIPT_EXT_KEY, RECEIPT_GATES, RECEIPT_GATE_IDS, RECEIPT_RULES, RECEIPT_VALIDATION_LABEL, createReceiptValidatorForOracleTests, receiptRequirementsFor, validateAcceptanceReceipt } from './receipt.mjs'
+export { SELECTION_CONTRIBUTION_ID, createApplyPolicyOperation, createConflictsOperation, createSelectionContribution, createSelectionOperation } from './contribution.mjs'