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

package/src/projection/obsidian/selection-ui/policy-setup.mjs

@@ -0,0 +1,107 @@
+import { ObsidianMaintenanceRefusal, refuse } from '../../../runtime/obsidian/errors.mjs'
+import { authorizeAutomaticApply, installApplyPolicy, readInstalledApplyPolicy, readMachineSettings, revokeApplyPolicy } from '../../../runtime/obsidian/machine-settings.mjs'
+import { IMPLEMENTED_EDIT_CLASSES, ObsidianContractRefusal, assertObsidianContract } from '../contracts.mjs'
+import { APPLY_MODES, applyPolicyDigest, withApplyPolicyDigest } from '../edits/policy.mjs'
+
+// Apply policy setup, noninteractive: a structured request in, a structured
+// answer out. Three actions:
+//
+//   create   build a manual or automatic policy document from a request,
+//            digest it, validate it against the frozen contract and install
+//            it through AOP-1's installer. Only the implemented edit class
+//            can be allowed; the conflict disposition is `hold`, the only
+//            one that exists.
+//   show     the installed policy, the reference machine settings hold, and
+//            whether an automatic apply would be authorized right now.
+//   revoke   AOP-1's revocation: the stored policy is written `revoked`
+//            first, then maintenance goes back to manual. Every later
+//            authorization read denies, and the engine reads authorization
+//            again immediately before each queued dispatch, so a revocation
+//            is durable and wins over anything queued behind it.
+//
+// Nothing here changes the maintenance mode to automatic: that is the
+// person's separate `mode set automatic`, which itself checks that an active
+// automatic policy is installed.
+
+export const POLICY_SETUP_ACTIONS = Object.freeze(['create', 'show', 'revoke'])
+export const POLICY_SETUP_SCHEMA = 'atelier-obsidian-policy-setup/v1'
+export const DEFAULT_MAX_BATCH_SIZE = 10
+export const DEFAULT_RETRY_BUDGET = 0
+export const CONFLICT_DISPOSITION = 'hold'
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const isTyped = (error) => error instanceof ObsidianMaintenanceRefusal || error instanceof ObsidianContractRefusal
+
+// The policy document a request describes, with the digest of its content.
+// `version` is taken from the request, else one above the installed policy of
+// the same identity, else 1.
+export function buildApplyPolicy({ workspaceId, policyId, mode, actor, selector, allowedEditClasses, maxBatchSize = DEFAULT_MAX_BATCH_SIZE, retryBudget = DEFAULT_RETRY_BUDGET, version = 1, status = 'active', ext } = {}) {
+  if (!APPLY_MODES.includes(mode)) refuse('invalid-apply-policy', 'policy mode must be manual or automatic', { mode: String(mode).slice(0, 32) })
+  if (!isPlainObject(actor) || !['user', 'agent'].includes(actor.kind) || typeof actor.id !== 'string' || !IDENTIFIER.test(actor.id)) refuse('invalid-apply-policy', 'the actor is { kind: user|agent, id }')
+  const classes = allowedEditClasses === undefined ? (mode === 'automatic' ? [...IMPLEMENTED_EDIT_CLASSES] : []) : allowedEditClasses
+  if (!Array.isArray(classes) || classes.some((item) => typeof item !== 'string')) refuse('invalid-apply-policy', 'allowedEditClasses is a list of edit classes')
+  const unimplemented = classes.filter((item) => !IMPLEMENTED_EDIT_CLASSES.includes(item))
+  if (unimplemented.length > 0) refuse('unimplemented-edit-class', 'only an edit class with an apply implementation can be allowed', { editClasses: unimplemented.map((item) => item.slice(0, 64)) })
+  const content = {
+    schema: 'atelier-obsidian-apply-policy/v1',
+    policyId, workspaceId, mode, status,
+    actor: { kind: actor.kind, id: actor.id },
+    version, allowedEditClasses: classes, selector, maxBatchSize, retryBudget,
+    conflictDisposition: CONFLICT_DISPOSITION,
+    ...(ext === undefined ? {} : { ext }),
+  }
+  const policy = withApplyPolicyDigest(content)
+  try { assertObsidianContract('apply-policy', policy) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-apply-policy', 'the policy does not satisfy its contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  return policy
+}
+
+const reference = (policy) => (policy === null ? null : { policyId: policy.policyId, version: policy.version, digest: policy.digest, mode: policy.mode, status: policy.status })
+const authorizationOf = (workspace) => {
+  const { authorized, reason } = authorizeAutomaticApply(workspace)
+  return { authorized, reason }
+}
+
+// The authorization the engine reads before each queued dispatch, in the
+// form a caller sees: read from disk now, never cached.
+export function dispatchGate(workspace) {
+  const authorization = authorizeAutomaticApply(workspace)
+  return { authorized: authorization.authorized, reason: authorization.reason, policyDigest: authorization.policy?.digest ?? null }
+}
+
+function showDocument(workspace) {
+  const policy = readInstalledApplyPolicy(workspace)
+  let machine = null
+  try { machine = readMachineSettings(workspace) } catch (error) { if (!isTyped(error)) throw error }
+  return { installed: policy !== null, policy, reference: machine?.applyPolicy ?? null, maintenanceMode: machine?.maintenanceMode ?? null, automaticApply: authorizationOf(workspace) }
+}
+
+// `workspace` is { workspaceRoot, workspaceId }; `repositoryRoots` the roots
+// private state may not overlap; `now` the timestamp to record.
+export function runPolicySetup({ action, input = {}, workspace, repositoryRoots, now }) {
+  const answer = (document) => ({ schema: POLICY_SETUP_SCHEMA, ok: true, action, ...document })
+  try {
+    if (!POLICY_SETUP_ACTIONS.includes(action)) refuse('usage', 'policy setup takes create, show or revoke', { action: String(action).slice(0, 32) })
+    if (!isPlainObject(workspace) || typeof workspace.workspaceRoot !== 'string' || typeof workspace.workspaceId !== 'string') refuse('usage', 'policy setup needs the workspace')
+    if (action === 'show') return answer(showDocument(workspace))
+    if (action === 'revoke') {
+      const result = revokeApplyPolicy({ ...workspace, repositoryRoots, updatedAt: now })
+      return answer({ revoked: result.revoked, reason: result.reason, policy: reference(result.policy), maintenanceMode: 'manual', automaticApply: authorizationOf(workspace) })
+    }
+    if (!isPlainObject(input)) refuse('usage', 'create takes a request object')
+    const installed = readInstalledApplyPolicy(workspace)
+    const version = input.version ?? (installed !== null && installed.policyId === input.policyId ? installed.version + 1 : 1)
+    if (installed !== null && installed.policyId === input.policyId && installed.version >= version) {
+      refuse('policy-version-not-newer', 'a policy of this identity is installed with an equal or higher version', { installed: installed.version, requested: version })
+    }
+    const policy = buildApplyPolicy({ ...input, workspaceId: workspace.workspaceId, version })
+    installApplyPolicy({ ...workspace, policy, repositoryRoots, updatedAt: now, digestOf: applyPolicyDigest })
+    return answer({ installed: true, policy, reference: reference(policy), maintenanceMode: readMachineSettings(workspace)?.maintenanceMode ?? 'manual', automaticApply: authorizationOf(workspace) })
+  } catch (error) {
+    if (!isTyped(error)) throw error
+    return { schema: POLICY_SETUP_SCHEMA, ok: false, action, refusal: { code: error.code, message: String(error.message).replace(`${error.code}: `, ''), detail: error.detail ?? {} } }
+  }
+}

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

@@ -0,0 +1,173 @@
+import { OBSIDIAN_EXT_KEY, validateObsidianContract } from '../contracts.mjs'
+
+// Acceptance receipt validation for the gates AOP-4 owns. This is schema
+// validation and required-field checking of a document. It proves that a
+// receipt is shaped as a receipt of that gate: exact candidate, pinned
+// versions, host and operator identity, hashed raw evidence in every role
+// the procedure calls for, and the separately recorded human or adopter
+// acceptance where the gate needs one.
+//
+// It proves nothing about what happened in the app, on the host or with the
+// adopter. `gateClosed` is always false. A gate is closed by its owner
+// inspecting the actual evidence and recording that in the parent matrix; a
+// document that passes here is an input to that inspection, never its result.
+
+export const RECEIPT_VALIDATION_LABEL = 'schema-validation-only'
+export const RECEIPT_EXT_KEY = OBSIDIAN_EXT_KEY
+export const ACCEPTANCE_KINDS = Object.freeze(['human', 'adopter'])
+
+// Per gate: the procedure of ACCEPTANCE.md that produces it, the evidence
+// type the receipt carries, the evidence roles that must each name a hashed
+// raw-evidence entry, and what is separately recorded.
+export const RECEIPT_GATES = Object.freeze({
+  G07: Object.freeze({ procedure: 'AP-01', evidenceType: 'real-app', roles: Object.freeze(['cli-link-inspection', 'app-observation']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G13: Object.freeze({ procedure: 'AP-02', evidenceType: 'real-app', roles: Object.freeze(['on-disk-membership', 'app-index-membership', 'graph-filter-observation']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G14: Object.freeze({ procedure: 'AP-03', evidenceType: 'host', roles: Object.freeze(['source-refresh-trace', 'dropped-event-recovery', 'sleep-wake-clock']), acceptance: null, wallClock: true, dataset: false, tarball: false }),
+  G15: Object.freeze({ procedure: 'AP-03', evidenceType: 'host', roles: Object.freeze(['ownership-health', 'terminal-closure']), acceptance: null, wallClock: true, dataset: false, tarball: false }),
+  G16: Object.freeze({ procedure: 'AP-04', evidenceType: 'real-app', roles: Object.freeze(['dataset-manifest', 'resource-samples', 'app-indexing-timings', 'warm-update-latencies']), acceptance: null, wallClock: true, dataset: true, tarball: false }),
+  G17: Object.freeze({ procedure: 'AP-05', evidenceType: 'real-app', roles: Object.freeze(['multi-vault-edit-trace', 'manual-apply-trace', 'automatic-apply-trace', 'uninstall-retention']), acceptance: 'human', wallClock: false, dataset: false, tarball: false }),
+  G18: Object.freeze({ procedure: 'AP-06', evidenceType: 'human', roles: Object.freeze(['tarball-audit', 'adopter-acceptance']), acceptance: 'adopter', wallClock: false, dataset: false, tarball: true }),
+})
+export const RECEIPT_GATE_IDS = Object.freeze(Object.keys(RECEIPT_GATES))
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const PLACEHOLDER = /^(?:unknown|n\/a|na|none|null|tbd|todo|latest|-+|\?+|0)$/i
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const isIdentifier = (value) => typeof value === 'string' && IDENTIFIER.test(value)
+const isTime = (value) => typeof value === 'string' && !Number.isNaN(Date.parse(value))
+const pinned = (value) => typeof value === 'string' && value.trim() !== '' && !PLACEHOLDER.test(value.trim())
+
+// Every check answers a list of { code, pointer, message }. Each is a
+// separate rule so the mutation controls of the test suite can switch one
+// off and prove the negative case that depends on it then passes.
+export const RECEIPT_RULES = Object.freeze({
+  gate(receipt, { gateId }) {
+    return receipt.gate === gateId ? [] : [{ code: 'gate-mismatch', pointer: '/gate', message: `the receipt is for ${receipt.gate}, not ${gateId}` }]
+  },
+  procedure(receipt, { gate }) {
+    const expected = new RegExp(`^${gate.procedure}(?:[.:-][A-Za-z0-9._:-]+)?$`)
+    return expected.test(receipt.procedureId) ? [] : [{ code: 'procedure-mismatch', pointer: '/procedureId', message: `this gate is produced by ${gate.procedure}` }]
+  },
+  evidenceType(receipt, { gate }) {
+    return receipt.evidenceType === gate.evidenceType ? [] : [{ code: 'evidence-type-mismatch', pointer: '/evidenceType', message: `this gate needs ${gate.evidenceType} evidence; a node result cannot stand for it` }]
+  },
+  versionPins(receipt) {
+    const missing = []
+    for (const [pointer, value] of [['/environment/os/name', receipt.environment.os.name], ['/environment/os/version', receipt.environment.os.version], ['/environment/app/name', receipt.environment.app.name], ['/environment/app/version', receipt.environment.app.version], ['/environment/cli/version', receipt.environment.cli.version]]) {
+      if (!pinned(value)) missing.push({ code: 'version-not-pinned', pointer, message: 'an exact installed version is recorded, never a placeholder' })
+    }
+    return missing
+  },
+  candidateIdentity(receipt, { gate }) {
+    const missing = []
+    if (/^0{40}$/.test(receipt.candidate.commit)) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/commit', message: 'the candidate commit is a placeholder' })
+    if (!DIGEST.test(String(receipt.candidate.treeDigest))) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/treeDigest', message: 'the candidate tree digest is missing' })
+    if (gate.tarball && !DIGEST.test(String(receipt.candidate.tarballDigest ?? ''))) missing.push({ code: 'candidate-not-pinned', pointer: '/candidate/tarballDigest', message: 'this gate binds the exact tarball' })
+    return missing
+  },
+  hostIdentity(receipt, { ext }) {
+    const missing = []
+    if (!isPlainObject(ext.host) || !isIdentifier(ext.host.id)) missing.push({ code: 'host-identity-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/host/id`, message: 'the host the procedure ran on is identified' })
+    if (!isPlainObject(ext.operator) || !isIdentifier(ext.operator.id)) missing.push({ code: 'operator-identity-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/operator/id`, message: 'the operator who ran the procedure is identified' })
+    return missing
+  },
+  evidenceHashes(receipt, { gate, ext }) {
+    const missing = []
+    const names = new Map(receipt.evidence.map((item) => [item.name, item]))
+    receipt.evidence.forEach((item, index) => {
+      if (!DIGEST.test(String(item.digest)) || !Number.isInteger(item.byteLength) || item.byteLength < 1) missing.push({ code: 'evidence-not-hashed', pointer: `/evidence/${index}`, message: 'every raw evidence file is hashed and non-empty' })
+    })
+    const roles = isPlainObject(ext.evidenceRoles) ? ext.evidenceRoles : {}
+    for (const role of gate.roles) {
+      const name = roles[role]
+      if (typeof name !== 'string' || !names.has(name)) missing.push({ code: 'evidence-role-missing', pointer: `/ext/${RECEIPT_EXT_KEY}/evidenceRoles/${role}`, message: `the procedure records ${role} as hashed raw evidence` })
+    }
+    for (const role of Object.keys(roles)) if (!gate.roles.includes(role)) missing.push({ code: 'evidence-role-unknown', pointer: `/ext/${RECEIPT_EXT_KEY}/evidenceRoles/${role}`, message: 'this gate has no such evidence role' })
+    return missing
+  },
+  acceptance(receipt, { gate, ext }) {
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/acceptance`
+    if (gate.acceptance === null) return ext.acceptance === undefined ? [] : [{ code: 'acceptance-not-expected', pointer, message: 'this gate records automation and host evidence; a separate acceptance belongs to another gate' }]
+    const acceptance = ext.acceptance
+    if (!isPlainObject(acceptance)) return [{ code: 'acceptance-missing', pointer, message: `this gate needs the separately recorded ${gate.acceptance} acceptance` }]
+    const missing = []
+    if (acceptance.kind !== gate.acceptance) missing.push({ code: 'acceptance-kind-mismatch', pointer: `${pointer}/kind`, message: `this gate needs a ${gate.acceptance} acceptance` })
+    if (!isIdentifier(acceptance.actor)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/actor`, message: 'the person who accepted is identified' })
+    if (!isTime(acceptance.recordedAt)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/recordedAt`, message: 'when the acceptance was recorded' })
+    if (typeof acceptance.evidenceName !== 'string' || !receipt.evidence.some((item) => item.name === acceptance.evidenceName)) missing.push({ code: 'acceptance-missing', pointer: `${pointer}/evidenceName`, message: 'the acceptance names its own hashed evidence entry' })
+    if (isPlainObject(ext.operator) && isIdentifier(acceptance.actor) && acceptance.actor === ext.operator.id && gate.acceptance === 'adopter') missing.push({ code: 'acceptance-not-separate', pointer: `${pointer}/actor`, message: 'the adopter acceptance is recorded by the adopter, not the operator' })
+    return missing
+  },
+  wallClock(receipt, { gate, ext }) {
+    if (!gate.wallClock) return []
+    const clock = ext.wallClock
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/wallClock`
+    if (!isPlainObject(clock) || !isTime(clock.startedAt) || !isTime(clock.endedAt)) return [{ code: 'wall-clock-missing', pointer, message: 'host procedures record the wall clock before and after' }]
+    return Date.parse(clock.endedAt) >= Date.parse(clock.startedAt) ? [] : [{ code: 'wall-clock-missing', pointer, message: 'the wall clock ends after it starts' }]
+  },
+  dataset(receipt, { gate, ext }) {
+    if (!gate.dataset) return []
+    const dataset = ext.dataset
+    const pointer = `/ext/${RECEIPT_EXT_KEY}/dataset`
+    if (!isPlainObject(dataset) || !Number.isInteger(dataset.nodes) || dataset.nodes < 1 || !Number.isInteger(dataset.edges) || dataset.edges < 0 || !DIGEST.test(String(dataset.fixtureDigest))) {
+      return [{ code: 'dataset-missing', pointer, message: 'the generated dataset is described by node count, edge count and fixture digest' }]
+    }
+    return []
+  },
+})
+
+const EXT_KEYS = new Set(['host', 'operator', 'evidenceRoles', 'acceptance', 'wallClock', 'dataset'])
+
+function extensionOf(receipt) {
+  const ext = receipt.ext?.[RECEIPT_EXT_KEY]
+  if (ext === undefined) return { ext: {}, missing: [{ code: 'extension-missing', pointer: `/ext/${RECEIPT_EXT_KEY}`, message: 'host, operator, evidence roles and acceptance are recorded under the extension key' }] }
+  if (!isPlainObject(ext)) return { ext: {}, missing: [{ code: 'extension-missing', pointer: `/ext/${RECEIPT_EXT_KEY}`, message: 'the extension member is an object' }] }
+  const unknown = Object.keys(ext).filter((key) => !EXT_KEYS.has(key)).sort()
+  return { ext, missing: unknown.map((key) => ({ code: 'extension-key-unknown', pointer: `/ext/${RECEIPT_EXT_KEY}/${key}`, message: 'the receipt extension is a closed shape' })) }
+}
+
+// Test seam: the mutation controls substitute a rule table with one rule
+// switched off. Production uses validateAcceptanceReceipt.
+export function createReceiptValidatorForOracleTests(rules = RECEIPT_RULES) {
+  const table = { ...RECEIPT_RULES, ...rules }
+  return function validateAcceptanceReceipt(receipt, { gate: gateId } = {}) {
+    const constant = { label: RECEIPT_VALIDATION_LABEL, gateClosed: false, closes: 'nothing', note: 'A schema-valid receipt closes no gate. The gate owner inspects the actual app, host or adopter evidence and records the closing in the parent matrix.' }
+    const requested = gateId ?? (isPlainObject(receipt) ? receipt.gate : undefined)
+    if (!RECEIPT_GATE_IDS.includes(requested)) {
+      return { ...constant, gate: typeof requested === 'string' ? requested.slice(0, 8) : null, schemaValid: false, requirementsMet: false, valid: false, outcome: null, evidenceType: null, missing: [{ code: 'gate-not-owned', pointer: '/gate', message: `this validator knows the gates ${RECEIPT_GATE_IDS.join(', ')}` }] }
+    }
+    const gate = RECEIPT_GATES[requested]
+    const schemaErrors = validateObsidianContract('acceptance-receipt', receipt)
+    if (schemaErrors.length > 0) {
+      return { ...constant, gate: requested, schemaValid: false, requirementsMet: false, valid: false, outcome: null, evidenceType: null, missing: schemaErrors.map((error) => ({ code: error.code, pointer: null, message: error.message })) }
+    }
+    const { ext, missing: extensionShape } = extensionOf(receipt)
+    const context = { gateId: requested, gate, ext }
+    // The rules run in table order, gate identity first, so a receipt of another gate is told that before anything about its extension.
+    const missing = []
+    for (const name of Object.keys(RECEIPT_RULES)) missing.push(...table[name](receipt, context))
+    missing.push(...extensionShape)
+    const requirementsMet = missing.length === 0
+    return { ...constant, gate: requested, schemaValid: true, requirementsMet, valid: requirementsMet, outcome: receipt.outcome, evidenceType: receipt.evidenceType, missing }
+  }
+}
+
+export const validateAcceptanceReceipt = createReceiptValidatorForOracleTests()
+
+// The field table, for documentation and for the test that pins it.
+export function receiptRequirementsFor(gateId) {
+  const gate = RECEIPT_GATES[gateId]
+  if (!gate) return null
+  return {
+    gate: gateId,
+    procedure: gate.procedure,
+    evidenceType: gate.evidenceType,
+    always: ['candidate.commit', 'candidate.treeDigest', 'environment.os.{name,version}', 'environment.app.{name,version}', 'environment.cli.version', 'evidence[].{name,digest,byteLength>0}', `ext.${RECEIPT_EXT_KEY}.host.id`, `ext.${RECEIPT_EXT_KEY}.operator.id`],
+    evidenceRoles: [...gate.roles],
+    acceptance: gate.acceptance,
+    wallClock: gate.wallClock,
+    dataset: gate.dataset,
+    tarballDigest: gate.tarball,
+  }
+}

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

@@ -0,0 +1,122 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../../project/private-state.mjs'
+import { canonicalJson, closedObject, compareText } from '../../../runtime/obsidian/documents.mjs'
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { assertOutsideRepositories } from '../../../runtime/obsidian/machine-settings.mjs'
+import { SCOPE_MODES, assertObsidianContract } from '../contracts.mjs'
+import { SETTINGS_ROOT } from '../materialize/settings.mjs'
+import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSION } from './focus.mjs'
+import { SELECTION_SCHEMA } from './selection.mjs'
+
+// Where a selector is kept: Atelier's own private state of the workspace,
+//
+//   <data>/obsidian/<workspace-id>/state/selection/<scope-id>.json
+//
+// beside the maintenance and settings documents AOP-1 keeps there, through
+// the same private-state primitives (owner-only, atomic replace, no symlink
+// following) and the same guard that keeps private state outside every
+// enrolled repository. It is not under any vault, and it is never one of the
+// files the app's UI owns under `.obsidian/`.
+
+export const SELECTION_STATE_SCHEMA = 'atelier-obsidian-selection-state/v1'
+export const SELECTION_DIRECTORY = path.join('state', 'selection')
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export function validateSelectionState(document, workspaceId) {
+  const code = 'invalid-selection-state'
+  closedObject(document, { required: ['schema', 'workspaceId', 'scopeId', 'mode', 'selector', 'expansion', 'focus', 'updatedAt'] }, code, 'the selection state')
+  if (document.schema !== SELECTION_STATE_SCHEMA) refuse(code, 'the selection state names an unknown schema')
+  if (document.workspaceId !== workspaceId) refuse(code, 'the selection state belongs to another workspace')
+  if (typeof document.scopeId !== 'string' || !IDENTIFIER.test(document.scopeId)) refuse(code, 'the selection state names no scope')
+  if (!SCOPE_MODES.includes(document.mode)) refuse(code, 'the selection state carries an unknown mode')
+  // The selector and the expansion are exactly a scope document's: the contract decides whether they are well formed.
+  assertObsidianContract('scope', { schema: 'atelier-obsidian-scope/v1', scopeId: document.scopeId, mode: document.mode, selector: document.selector, ...(document.expansion === null ? {} : { expansion: document.expansion }) })
+  if (document.focus !== null) {
+    closedObject(document.focus, { required: ['version', 'query', 'queryDigest', 'paths', 'bookmark'] }, code, 'the persisted focus')
+    if (document.focus.version !== FOCUS_QUERY_VERSION || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
+    if (!Array.isArray(document.focus.paths) || document.focus.paths.length === 0 || document.focus.paths.some((item) => typeof item !== 'string')) refuse(code, 'the persisted focus names no path')
+    closedObject(document.focus.bookmark, { required: ['type', 'title', 'options'] }, code, 'the persisted bookmark payload')
+    if (document.focus.bookmark.type !== FOCUS_BOOKMARK_TYPE) refuse(code, 'the persisted bookmark payload is not a graph bookmark')
+  }
+  if (document.mode === 'focus' ? document.focus === null : document.focus !== null) refuse(code, 'a focus is persisted exactly for a focus scope')
+  if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse(code, 'updatedAt must be a UTC timestamp')
+  return document
+}
+
+// A path Atelier may write: under the workspace's private state and never under a vault's `.obsidian/`.
+export function assertWritableSelectionPath({ workspaceRoot, file }) {
+  const relative = path.relative(workspaceRoot, file)
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) refuse('selection-state-outside-workspace', 'the selection state is written under the workspace private state only')
+  const parts = relative.split(path.sep)
+  if (parts.includes(SETTINGS_ROOT) || parts[0] === 'vaults') refuse('ui-owned-file-refused', 'Atelier never writes a vault or a file under .obsidian/; the app owns those')
+  if (parts.length !== 3 || parts[0] !== 'state' || parts[1] !== 'selection') refuse('selection-state-outside-workspace', 'the selection state lives in state/selection')
+  return file
+}
+
+export function selectionStateDocument({ workspaceId, selection, now }) {
+  if (selection?.schema !== SELECTION_SCHEMA) refuse('invalid-selection', 'a resolved selection is persisted, nothing else')
+  return {
+    schema: SELECTION_STATE_SCHEMA,
+    workspaceId,
+    scopeId: selection.scope.scopeId,
+    mode: selection.scope.mode,
+    selector: selection.scope.selector,
+    expansion: selection.scope.expansion ?? null,
+    focus: selection.focus === null ? null : { version: selection.focus.version, query: selection.focus.query, queryDigest: selection.focus.queryDigest, paths: selection.focus.paths, bookmark: selection.focus.bookmark },
+    updatedAt: now,
+  }
+}
+
+const selectionFile = (workspaceRoot, scopeId) => path.join(workspaceRoot, SELECTION_DIRECTORY, `${segment(scopeId)}.json`)
+
+// Writes only when the bytes change. Returns { file, changed, document }.
+export function writeSelectionState({ workspaceRoot, workspaceId, repositoryRoots, selection, now }) {
+  const document = validateSelectionState(selectionStateDocument({ workspaceId, selection, now }), workspaceId)
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  const file = assertWritableSelectionPath({ workspaceRoot, file: selectionFile(workspaceRoot, document.scopeId) })
+  const text = canonicalJson(document)
+  let existing = null
+  try { existing = readRegularTextNoFollow(file) } catch (error) { if (error.code !== 'ENOENT') throw error }
+  // A rewrite that changes only the time is not a change to the selection.
+  if (existing !== null) {
+    let previous = null
+    try { previous = JSON.parse(existing) } catch { previous = null }
+    if (previous !== null && canonicalJson({ ...previous, updatedAt: document.updatedAt }) === text) return { file, changed: false, document: previous }
+  }
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, SELECTION_DIRECTORY), label: 'Obsidian selection state' })
+  atomicReplacePrivateText(path.join(directory, path.basename(file)), text)
+  return { file, changed: true, document }
+}
+
+export function readSelectionState({ workspaceRoot, workspaceId, scopeId }) {
+  if (typeof scopeId !== 'string' || !IDENTIFIER.test(scopeId)) refuse('invalid-scope', 'name the scope whose selection to read')
+  let text
+  try { text = readRegularTextNoFollow(selectionFile(workspaceRoot, scopeId)) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    refuse('invalid-selection-state', 'the selection state cannot be read', { cause: error.code ?? String(error.message) })
+  }
+  let document
+  try { document = JSON.parse(text) } catch { refuse('invalid-selection-state', 'the selection state is not JSON') }
+  const validated = validateSelectionState(document, workspaceId)
+  if (validated.scopeId !== scopeId) refuse('invalid-selection-state', 'the selection state names another scope')
+  return validated
+}
+
+export function listSelectionStates({ workspaceRoot, workspaceId }) {
+  let names
+  try { names = fs.readdirSync(path.join(workspaceRoot, SELECTION_DIRECTORY)) } catch (error) { if (error.code === 'ENOENT') return []; throw error }
+  const documents = []
+  for (const name of names.filter((item) => item.endsWith('.json')).sort(compareText)) {
+    const text = readRegularTextNoFollow(path.join(workspaceRoot, SELECTION_DIRECTORY, name))
+    let document
+    try { document = JSON.parse(text) } catch { refuse('invalid-selection-state', 'a selection state is not JSON', { file: name }) }
+    documents.push(validateSelectionState(document, workspaceId))
+  }
+  return documents.sort((left, right) => compareText(left.scopeId, right.scopeId))
+}

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

@@ -0,0 +1,109 @@
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { EXPANSION_DIRECTIONS, EXPANSION_ORDERS, MAX_EXPANSION_DEPTH, ObsidianContractRefusal, SCOPE_MODES, assertObsidianContract, selectScope } from '../contracts.mjs'
+import { allocateWorkspacePaths } from '../materialize/path-registry.mjs'
+import { buildFocusQuery, focusBookmarkPayload } from './focus.mjs'
+
+// Selection: a requested scope (full, scoped or focus, with an optional
+// bounded expansion) becomes an exact scope document, the exact selected set
+// and, for a focus, the graph query and bookmark payload derived from it.
+//
+// Selection is the contract's selectScope, unchanged: this module adds no
+// selector, no default and no fallback. An empty result is reported as
+// empty, or refused when the caller did not say empty is acceptable. It is
+// never widened. The note paths are the ones the workspace path registry
+// allocates, so a focus names the files a full vault of this workspace holds.
+
+export const SELECTION_SCHEMA = 'atelier-obsidian-selection/v1'
+export const SCOPE_CONTRACT_SCHEMA = 'atelier-obsidian-scope/v1'
+export const EMPTY_SELECTION_REASONS = Object.freeze(['explicit-empty', 'no-visible-members'])
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The exact document: the caller's members, the two expansion defaults the
+// contract allows filled in, and nothing else. A budget is never defaulted.
+export function scopeDocumentOf({ scopeId, mode, selector, expansion, ext } = {}) {
+  if (typeof scopeId !== 'string' || scopeId === '') refuse('invalid-scope', 'a scope names itself with a scopeId')
+  if (!SCOPE_MODES.includes(mode)) refuse('invalid-scope', 'scope mode must be full, focus or scoped', { mode: String(mode).slice(0, 32) })
+  if (!isPlainObject(selector)) refuse('invalid-scope', 'a scope carries a selector object')
+  let normalizedExpansion
+  if (expansion !== undefined && expansion !== null) {
+    if (!isPlainObject(expansion)) refuse('invalid-expansion', 'expansion must be an object')
+    if (expansion.depth === undefined || expansion.maxNodes === undefined) refuse('missing-expansion-budget', 'expansion requires both a depth and a maxNodes budget; neither is defaulted')
+    // The budgets are checked here, before the contract, so a bad budget is an expansion fault and not a generic scope fault.
+    if (!Number.isInteger(expansion.depth) || expansion.depth < 1 || expansion.depth > MAX_EXPANSION_DEPTH) refuse('invalid-expansion', `depth must be an integer from 1 to ${MAX_EXPANSION_DEPTH}`)
+    if (!Number.isInteger(expansion.maxNodes) || expansion.maxNodes < 1) refuse('invalid-expansion', 'maxNodes must be a positive integer')
+    const direction = expansion.direction ?? 'outgoing'
+    const order = expansion.order ?? 'canonical-id'
+    if (!EXPANSION_DIRECTIONS.includes(direction)) refuse('invalid-expansion', 'unknown expansion direction')
+    if (!EXPANSION_ORDERS.includes(order)) refuse('invalid-expansion', 'unknown expansion order')
+    normalizedExpansion = { depth: expansion.depth, maxNodes: expansion.maxNodes, direction, order, ...(expansion.ext === undefined ? {} : { ext: expansion.ext }) }
+  }
+  const document = {
+    schema: SCOPE_CONTRACT_SCHEMA,
+    scopeId,
+    mode,
+    selector,
+    ...(normalizedExpansion === undefined ? {} : { expansion: normalizedExpansion }),
+    ...(ext === undefined ? {} : { ext }),
+  }
+  try { assertObsidianContract('scope', document) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-scope', 'the requested scope does not satisfy the scope contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  return document
+}
+
+function contractRefusalToTyped(error) {
+  if (error instanceof ObsidianContractRefusal) refuse(error.code, error.message.replace(`${error.code}: `, ''), error.detail ?? {})
+  throw error
+}
+
+// `pathRegistry` is the workspace's persisted path registry when the caller
+// has one (AOP-1 keeps it in the maintenance state store); without it the
+// paths are those a fresh workspace would allocate. Both are deterministic.
+export function resolveSelection({ canonicalSnapshot, profile, scope, allowEmpty = false, pathRegistry = null, select = selectScope } = {}) {
+  const document = scopeDocumentOf(scope)
+  let result
+  try {
+    result = select({ canonicalSnapshot, profile, selector: document.selector, expansion: document.expansion, mode: document.mode })
+  } catch (error) { contractRefusalToTyped(error) }
+
+  const empty = result.nodes.length === 0
+  const emptyReason = empty ? (result.diagnostics.includes('selection-has-no-visible-members') ? 'no-visible-members' : 'explicit-empty') : null
+  if (empty && document.mode === 'focus') {
+    // A graph filter naming no note would show the whole vault or nothing, depending on the app. Neither is the request.
+    refuse('focus-selection-empty', 'the focus selects no visible note; a focus is never widened', { reason: emptyReason, unresolvedIds: result.unresolvedIds })
+  }
+  if (empty && allowEmpty !== true) refuse('selection-empty', 'the selection has no visible member; pass allowEmpty to produce an honest empty scope', { reason: emptyReason, unresolvedIds: result.unresolvedIds })
+
+  const workspaceId = typeof profile?.workspaceId === 'string' ? profile.workspaceId : 'ws-unnamed'
+  const nodeById = new Map(canonicalSnapshot.nodes.map((node) => [node.id, node]))
+  const vaultNodes = result.vaultNodes.map((id) => nodeById.get(id))
+  let pathOf
+  try { ({ pathOf } = allocateWorkspacePaths({ registry: pathRegistry, workspaceId, nodes: vaultNodes })) } catch (error) { contractRefusalToTyped(error) }
+  const notePaths = Object.fromEntries(result.nodes.map((id) => [id, pathOf(nodeById.get(id).repo, id)]))
+
+  let focus = null
+  if (document.mode === 'focus') {
+    const built = buildFocusQuery(result.nodes.map((id) => notePaths[id]))
+    focus = { ...built, bookmark: focusBookmarkPayload({ scopeId: document.scopeId, query: built.query }) }
+  }
+
+  return {
+    schema: SELECTION_SCHEMA,
+    scope: document,
+    mode: document.mode,
+    nodes: result.nodes,
+    edges: result.edges,
+    outsideSelectionEdges: result.outsideSelectionEdges,
+    vaultNodes: result.vaultNodes,
+    vaultEdges: result.vaultEdges,
+    truncated: result.truncated,
+    unresolvedIds: result.unresolvedIds,
+    diagnostics: result.diagnostics,
+    empty,
+    emptyReason,
+    notePaths,
+    focus,
+  }
+}

package/src/projection/project.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+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'
@@ -50,7 +51,7 @@ export function buildProjectProjection(project) {
   const dimensionCards = readinessJourney.dimensions.map((item) => `<article class="readiness-card" data-protocol="${esc(item.protocolId)}">
     <p class="eyebrow">${esc(item.label)}</p>
     <h3>${esc(item.title)}</h3>
-    <p><strong>${esc(item.status)}</strong> · ${esc(item.score)} / 100</p>
+    <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>
   </article>`).join('\n')
@@ -93,6 +94,7 @@ ${branding.themeCss}</style>
     <div>
       <p class="eyebrow">MNSTRY Tenant Readiness</p>
       <h2 id="tenant-readiness-title">Readiness Journey</h2>
+      <p>Scores measure answer completeness, not evidence confidence, approval or runtime readiness.</p>
       <p>${esc(readinessJourney.dimensions.length)} dimensions · next protocol: ${esc(readinessJourney.nextProtocol || 'none')}</p>
     </div>
     <div class="readiness-score">${esc(readinessJourney.score)}%</div>
@@ -117,36 +119,43 @@ document.addEventListener('click', async (event) => {
   return { output, html, graph, readinessJourney }
 }
 
+export function buildProjectManifest(project, projection) {
+  return {
+    schema: 'mnstry.atelier-manifest@v1',
+    generatedAt: 'deterministic',
+    graphPath: path.relative(project.outputRoot, project.graphPath).split(path.sep).join('/'),
+    entry: 'index.html',
+    tenantReadiness: {
+      score: projection.readinessJourney.score,
+      ready: projection.readinessJourney.ready,
+      dimensions: projection.readinessJourney.dimensions.map((item) => ({
+        key: item.key,
+        protocolId: item.protocolId,
+        status: item.status,
+        score: item.score,
+      })),
+    },
+    nodes: projection.graph.nodes.map((node) => ({ id: node.id, title: node.title, audience: node.audience, path: node.path })),
+  }
+}
+
 export function runProjectCommand(argv = process.argv.slice(2)) {
   const check = argv.includes('--check')
   const project = commandProject({ argv })
   const projection = buildProjectProjection(project)
   if (check) {
     const current = fs.existsSync(projection.output) ? fs.readFileSync(projection.output, 'utf8') : null
-    if (current !== projection.html) {
+    const manifestPath = path.join(project.outputRoot, 'atelier.manifest.json')
+    let manifest = null
+    try { manifest = readJson(manifestPath) } catch { /* Missing or invalid artifacts are stale. */ }
+    if (current !== projection.html || !isDeepStrictEqual(manifest, JSON.parse(JSON.stringify(buildProjectManifest(project, projection))))) {
       console.error(`project projection is stale: ${projection.output}`)
       process.exit(1)
     }
   } else {
     fs.mkdirSync(path.dirname(projection.output), { recursive: true })
     fs.writeFileSync(projection.output, projection.html)
-    writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), {
-      schema: 'mnstry.atelier-manifest@v1',
-      generatedAt: 'deterministic',
-      graphPath: project.graphPath,
-      entry: 'index.html',
-      tenantReadiness: {
-        score: projection.readinessJourney.score,
-        ready: projection.readinessJourney.ready,
-        dimensions: projection.readinessJourney.dimensions.map((item) => ({
-          key: item.key,
-          protocolId: item.protocolId,
-          status: item.status,
-          score: item.score,
-        })),
-      },
-      nodes: projection.graph.nodes.map((node) => ({ id: node.id, title: node.title, audience: node.audience, path: node.path })),
-    })
+    writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), buildProjectManifest(project, projection))
   }
   console.log(`project projection: ${projection.graph.counts.nodes} nodes -> ${projection.output}`)
 }