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

package/src/projection/obsidian/personal-workspace.mjs

@@ -0,0 +1,436 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { PersonalWorkspaceRefusal, composePersonalWorkspace } from '@mnstry/atelier/personal-workspace'
+import { ensureLocalState, resolveProjectConfig, validateProjectConfigDoc } from '@mnstry/atelier/project'
+import { buildCanonicalGraph } from '../../graph/graph.mjs'
+import { refuse } from '../../runtime/obsidian/errors.mjs'
+import { OBSIDIAN_EXT_KEY } from './contracts.mjs'
+
+// The one personal-workspace route of the Obsidian projection.
+//
+// A person's private home holds the authored manifest and overlay, and the
+// generations the personal-workspace module materialized from them. A binding
+// names one home and one generation, both explicitly: nothing here discovers
+// either from the environment or the working directory. The module's
+// `composePersonalWorkspace` is the only authority on whether that generation
+// may be used.
+//
+// One graph. Every caller (the engine, view counts, source apply, the proposal
+// adapter and the selection operation) builds through the pipeline's
+// `buildGraph`, which builds a bound project here: the canonical graph of the
+// generation's configuration, with the composition's own rule that no private
+// note is a link target, and the caller's file cache. A plain build would
+// differ wherever a shared note's link names a private note.
+//
+// Validity. A graph is returned only under a validity key the composition has
+// confirmed: the key names the inputs a stat or a bounded read can see (see
+// inputsDigest) and a digest of the built graph's facts. The inputs are read
+// before composing, so a key is confirmed only when the composition accepted
+// those inputs and composed a graph with exactly those facts, and a returned
+// graph is always one the composition built too (a change and its exact undo
+// during one composition is caught at the next full reconciliation). A key not yet confirmed is
+// confirmed by composing: synchronously for a caller that builds once, and off
+// the event loop, in a worker with a deadline, for the engine and the proposal
+// adapter it runs (`validatePersonalWorkspace`). What no key names is asked of
+// the composition at every full reconciliation.
+//
+// What a binding returns:
+//   project      the generation's atelier.project.json, resolved, with the
+//                Obsidian settings member built in memory from the overlay's
+//                saved views (each a scope) plus an `everything` scope, and the
+//                frozen binding under one symbol key. No generation file is
+//                ever written.
+//   binding      { personalHome, generationId, overlayRepoId }, frozen.
+//   preferences  the overlay's preferences, read only. A theme is reported,
+//                never written: the vault's appearance is the person's.
+//   coverage     passed through as the module returned it. Nothing here reads
+//                it: it describes what is not enforced, and is never permission.
+//
+// The project's own folder is the private home rather than the generation:
+// the projection keeps its workspace pointer in `<folder>/.atelier-local/`,
+// and a generation is a closed, verified inventory that any extra file
+// invalidates. A home is outside every Git worktree, so its local state is
+// ignored by construction.
+
+const BINDING = Symbol('atelier.obsidian.personal-workspace-binding')
+// What each binding was made with: the composition that admitted it, the build that serves its graph, and whether the
+// composition can run in a worker (only the module's own can).
+const ROUTES = new WeakMap()
+// The last validity key the composition confirmed for each binding: { inputs, facts }.
+const CONFIRMED = new WeakMap()
+export const EVERYTHING_SCOPE_ID = 'everything'
+const EXT_SCHEMA = 'atelier-obsidian-ext-settings/v1'
+// The settings member of a bound project names its generation here. It survives any copy of the project (a structured
+// clone, a JSON round trip) that drops the symbol-keyed binding, so such a copy is refused instead of being built as an
+// ordinary project; and a rebound generation changes the member, which invalidates every view. An ordinary project's
+// settings may not use this key.
+export const PERSONAL_MEMBER_KEY = 'mnstry.atelier.personal-workspace'
+// The Obsidian settings contract's limits: at most 256 scopes, one of them `everything`, and at most 256 members in a
+// selector's union.
+const MAX_SAVED_VIEWS = 255
+const MAX_VIEW_REPOSITORIES = 256
+// A build that found its validity key unconfirmed, for a caller that confirms it off the event loop and builds again.
+export const PERSONAL_VALIDATION_PENDING = 'personal-validation-pending'
+const WORKER_KIND = 'atelier-obsidian-personal-composition'
+
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex')
+const deepFreeze = (value) => { if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); Object.freeze(value) } return value }
+const sortKeys = (value) => (Array.isArray(value) ? value.map(sortKeys)
+  : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])])) : value)
+const digestOf = (value) => sha256(JSON.stringify(sortKeys(value)))
+const generationRoot = ({ personalHome, generationId }) => path.join(personalHome, 'generations', generationId)
+const linkTargetRule = (overlayRepoId) => (node) => node.repo !== overlayRepoId
+
+// The facts of a graph every caller reads: nodes, edges, embeds, assets, resolved links and every finding.
+const graphFactsDigest = (graph) => digestOf([graph.nodes, graph.edges, graph.embeds ?? [], graph.assets ?? [], graph.links ?? [], graph.linkDiagnostics ?? [], graph.diagnostics ?? []])
+
+// The personal-workspace module's read limits: an authored input, and a generation file.
+const AUTHORED_LIMIT = 1024 * 1024
+const GENERATION_LIMIT = 8 * 1024 * 1024
+const NONBLOCK = fs.constants.O_NONBLOCK ?? 0
+
+// One regular file, opened without following a link and without waiting on it (a FIFO or a device never blocks the
+// caller), and read up to `limit`. Anything else refuses `code`, as the composition would.
+function regularFileBytes(file, limit, code, { follow = false } = {}) {
+  let fd
+  try { fd = fs.openSync(file, fs.constants.O_RDONLY | (follow ? 0 : fs.constants.O_NOFOLLOW) | NONBLOCK) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+    throw new PersonalWorkspaceRefusal(code)
+  }
+  try {
+    const stat = fs.fstatSync(fd)
+    if (!stat.isFile() || stat.size > limit) throw new PersonalWorkspaceRefusal(code)
+    return fs.readFileSync(fd)
+  } finally { fs.closeSync(fd) }
+}
+const regularFileDigest = (file, limit, code) => { const bytes = regularFileBytes(file, limit, code); return bytes === null ? 'missing' : sha256(bytes) }
+// A Git configuration file, which Git itself reads through a link (a managed dotfile): followed, but still only a
+// regular file, bounded, and never waited on.
+const configDigest = (file) => { try { const bytes = regularFileBytes(file, AUTHORED_LIMIT, 'malformed-input', { follow: true }); return bytes === null ? 'missing' : sha256(bytes) } catch { return 'not-regular' } }
+// The configuration files of an enrolled repository: `.git/config` (through `.git` when it is a link to a directory),
+// or, where `.git` is a file (a separate Git directory, a linked worktree, a submodule), the configuration of the
+// directory it names and of its common directory. A root that cannot be looked at (a file, a link loop, no permission)
+// is recorded as such, so the composition answers with its own code.
+function repositoryConfigDigests(repoRoot) {
+  const dotGit = path.join(repoRoot, '.git')
+  let kind
+  try { kind = fs.lstatSync(dotGit, { throwIfNoEntry: false }) } catch (error) { return [`unreadable:${error.code ?? 'error'}`] }
+  if (kind === undefined) return ['missing']
+  if (kind.isDirectory()) return [configDigest(path.join(dotGit, 'config'))]
+  if (kind.isSymbolicLink()) {
+    try { if (fs.statSync(dotGit).isDirectory()) return ['linked', fs.realpathSync(dotGit), configDigest(path.join(dotGit, 'config'))] } catch (error) { return [`unreadable:${error.code ?? 'error'}`] }
+  }
+  let pointer
+  try { pointer = regularFileBytes(dotGit, AUTHORED_LIMIT, 'malformed-input', { follow: true }) } catch { return ['not-regular'] }
+  const named = /^gitdir:\s*(.+?)\s*$/m.exec(pointer?.toString('utf8') ?? '')
+  if (named === null) return ['unnamed']
+  const gitDir = path.resolve(repoRoot, named[1])
+  let commonDir = null
+  try { const common = regularFileBytes(path.join(gitDir, 'commondir'), AUTHORED_LIMIT, 'malformed-input', { follow: true }); if (common !== null) commonDir = path.resolve(gitDir, common.toString('utf8').trim()) } catch { commonDir = 'not-regular' }
+  return [gitDir, configDigest(path.join(gitDir, 'config')), commonDir, commonDir === null || commonDir === 'not-regular' ? null : configDigest(path.join(commonDir, 'config'))]
+}
+
+// Everything outside the graph that a composition's answer depends on and a stat or a bounded read can see: the authored
+// inputs (regular files only), every file of the generation (an extra, missing or irregular one too), the private home's
+// own state and any `.git` above it, each enrolled root's link status and Git configuration (its remote and its helpers),
+// the user's Git configuration, and any ambient Git variable. A file that is not regular refuses here with the code the
+// composition gives it, before anything waits on it.
+function inputsDigest({ personalHome, generationId }) {
+  const stat = (file) => { try { const s = fs.lstatSync(file); return [s.mode, s.uid, s.ino, s.isSymbolicLink()] } catch (error) { return `missing:${error.code ?? 'error'}` } }
+  const authoredBytes = ['atelier.personal.json', 'atelier.overlay.json'].map((name) => regularFileBytes(path.join(personalHome, name), AUTHORED_LIMIT, 'malformed-input'))
+  const authored = ['atelier.personal.json', 'atelier.overlay.json'].map((name, index) => [stat(path.join(personalHome, name)), authoredBytes[index] === null ? 'missing' : sha256(authoredBytes[index])])
+  const generation = []
+  const walk = (directory, prefix) => {
+    let entries
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }) } catch (error) { generation.push([prefix, `unreadable:${error.code ?? 'error'}`]); return }
+    for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+      const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+      const absolute = path.join(directory, entry.name)
+      if (entry.isDirectory()) { generation.push([relative, stat(absolute)]); walk(absolute, relative) } else if (entry.isFile()) generation.push([relative, regularFileDigest(absolute, GENERATION_LIMIT, 'generation-corrupt')])
+      else throw new PersonalWorkspaceRefusal('generation-corrupt')
+    }
+  }
+  const root = generationRoot({ personalHome, generationId })
+  walk(root, '')
+  let realHome
+  try { realHome = fs.realpathSync(personalHome) === personalHome } catch { realHome = false }
+  const ancestorsWithGit = []
+  for (let ancestor = personalHome; ; ancestor = path.dirname(ancestor)) {
+    if (fs.lstatSync(path.join(ancestor, '.git'), { throwIfNoEntry: false }) !== undefined) ancestorsWithGit.push(ancestor)
+    if (ancestor === path.dirname(ancestor)) break
+  }
+  let repos = []
+  // The bytes read above, never the file again.
+  try { repos = JSON.parse(authoredBytes[0]?.toString('utf8') ?? '{}').repos.filter((repo) => repo.enrolled).map((repo) => repo.root) } catch { repos = [] }
+  const enrolled = repos.map((repoRoot) => {
+    let real
+    try { real = fs.realpathSync(repoRoot) === repoRoot } catch { real = false }
+    return [repoRoot, stat(repoRoot), real, repositoryConfigDigests(repoRoot)]
+  })
+  const home = process.env.HOME
+  const userGit = typeof home === 'string' && path.isAbsolute(home)
+    ? [path.join(home, '.gitconfig'), path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'git', 'config')].map(configDigest)
+    : ['no-home']
+  return digestOf({
+    authored,
+    generation,
+    roots: [stat(personalHome), realHome, stat(path.join(personalHome, 'generations')), stat(path.join(personalHome, 'generations', '.git')), stat(root), ancestorsWithGit],
+    enrolled,
+    userGit,
+    ambientGit: Object.keys(process.env).filter((name) => /^GIT_/i.test(name)).sort(),
+  })
+}
+
+// One generation file, read without following a link, and checked against the
+// digest the generation records for it (and compose verified a moment ago).
+function generationFile(generation, final, relative) {
+  const listed = generation.files.find((file) => file.path === relative)
+  if (!listed) throw new PersonalWorkspaceRefusal('generation-corrupt')
+  let bytes
+  try {
+    const fd = fs.openSync(path.join(final, ...relative.split('/')), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+    try { bytes = fs.readFileSync(fd) } finally { fs.closeSync(fd) }
+  } catch { throw new PersonalWorkspaceRefusal('generation-corrupt') }
+  if (sha256(bytes) !== listed.sha256) throw new PersonalWorkspaceRefusal('generation-corrupt')
+  return bytes
+}
+
+function selectorFor(repoIds) {
+  const repos = [...new Set(repoIds)]
+  if (repos.length === 0) return { ids: [] }
+  if (repos.length === 1) return { repo: repos[0] }
+  return { union: repos.map((repo) => ({ repo })) }
+}
+
+// The Obsidian settings member of a personal binding: one scoped view per saved
+// selection of repositories, in the overlay's order, and one full view of the
+// whole composed graph. A preferred view that names a saved one is the default.
+// Refused, typed, where the overlay allows more than a projection can declare.
+export function personalWorkspaceScopes(overlay, generationId) {
+  if (overlay.views.some((view) => view.id === EVERYTHING_SCOPE_ID)) {
+    refuse('personal-view-id-reserved', `a saved view may not be named "${EVERYTHING_SCOPE_ID}"; that view is the whole personal workspace`)
+  }
+  if (overlay.views.length > MAX_SAVED_VIEWS) refuse('personal-views-exceed-settings-limit', `a personal workspace can show at most ${MAX_SAVED_VIEWS} saved views; nothing is bound`, { limit: MAX_SAVED_VIEWS, kind: 'views' })
+  if (overlay.views.some((view) => new Set(view.repoIds).size > MAX_VIEW_REPOSITORIES)) {
+    refuse('personal-views-exceed-settings-limit', `a saved view can name at most ${MAX_VIEW_REPOSITORIES} repositories; nothing is bound`, { limit: MAX_VIEW_REPOSITORIES, kind: 'repositories' })
+  }
+  const scopes = [
+    ...overlay.views.map((view) => ({ scopeId: view.id, mode: 'scoped', selector: selectorFor(view.repoIds) })),
+    { scopeId: EVERYTHING_SCOPE_ID, mode: 'full', selector: { all: true } },
+  ]
+  const preferred = overlay.preferences?.defaultView
+  const defaultScopeId = typeof preferred === 'string' && overlay.views.some((view) => view.id === preferred) ? preferred : EVERYTHING_SCOPE_ID
+  return { schema: EXT_SCHEMA, enabled: true, defaultScopeId, scopes, ext: { [PERSONAL_MEMBER_KEY]: { generationId } } }
+}
+
+// The bound project, from a composition the caller just made: `composed` carries the generation's record, the
+// preferences and the coverage, and the validity key that composition confirmed.
+function assemble({ personalHome, generationId }, composed, route) {
+  const final = generationRoot({ personalHome, generationId })
+  const projectBytes = generationFile(composed.generation, final, 'atelier.project.json')
+  const inputs = JSON.parse(generationFile(composed.generation, final, 'inputs.json').toString('utf8'))
+  const configPath = path.join(final, 'atelier.project.json')
+  const resolved = resolveProjectConfig({ argv: [`--project-config=${configPath}`], cwd: final, env: { PATH: process.env.PATH }, writeLocalState: false })
+  // The same pinned resolution compose made; anything else means the generation changed between the two reads.
+  if (JSON.stringify(resolved.config) !== JSON.stringify(JSON.parse(projectBytes.toString('utf8')))) throw new PersonalWorkspaceRefusal('generation-corrupt')
+  if (validateProjectConfigDoc(resolved.config).length > 0) throw new PersonalWorkspaceRefusal('generation-corrupt')
+  if (resolved.localOverlay.paths.length > 0 || resolved.repos.some((repo) => repo.pathSource !== 'tracked-config')) throw new PersonalWorkspaceRefusal('ambient-overlay-present')
+  const overlayRepoId = `personal-${inputs.manifest.workspaceId}`
+  const overlayRepo = resolved.repos.find((repo) => repo.name === overlayRepoId)
+  if (!overlayRepo || overlayRepo.path !== path.join(final, 'overlay')) throw new PersonalWorkspaceRefusal('generation-corrupt')
+
+  const binding = Object.freeze({ personalHome, generationId, overlayRepoId })
+  ROUTES.set(binding, route)
+  CONFIRMED.set(binding, composed.key)
+  const member = deepFreeze(personalWorkspaceScopes(inputs.overlay, generationId))
+  const project = {
+    ...resolved,
+    config: { ...resolved.config, ext: { ...(resolved.config.ext ?? {}), [OBSIDIAN_EXT_KEY]: member } },
+    configDir: personalHome,
+    [BINDING]: binding,
+  }
+  project.localState = ensureLocalState(project, { write: false, env: { PATH: process.env.PATH } })
+  return Object.freeze({ project, binding, preferences: deepFreeze(structuredClone(composed.preferences ?? {})), coverage: composed.coverage })
+}
+
+// A composition in this thread, as the summary a worker sends back.
+// The inputs are digested BEFORE composing: a single change that lands while the composition runs then either is seen by
+// it, or leaves the confirmed key behind, so the next build composes again. A change and its exact undo within one
+// composition (A, then B, then A again) is not seen this way: it is caught at the next full reconciliation.
+function composeHere(compose, binding) {
+  const inputs = inputsDigest(binding)
+  const composed = compose({ personalHome: binding.personalHome, generationId: binding.generationId })
+  return { generation: composed.generation, preferences: composed.preferences, coverage: composed.coverage, key: { inputs, facts: graphFactsDigest(composed.graph) } }
+}
+
+// A composition in a worker thread, so the event loop of the caller stays free while it runs. Resolves to the summary, or
+// to `{ code }` for a refusal; a worker that cannot run answers `personal-composition-unavailable`.
+// A worker that does not answer within the deadline is terminated and let go of, and the composition refuses
+// `personal-composition-unavailable`: the tick does not wait on it. A worker blocked in a system call (a FIFO opened
+// for reading, say) cannot be stopped until that call returns: until then it keeps the process from exiting, and each
+// such expiry leaves one thread behind. A service stopped in that state needs a kill.
+export const WORKER_DEADLINE_MS = 120 * 1000
+function composeInWorker({ personalHome, generationId }, { deadlineMs = WORKER_DEADLINE_MS, stallMs = 0 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    let worker = null
+    let timer = null
+    const settle = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (value.code === 'personal-composition-unavailable' && worker !== null) { worker.unref(); worker.terminate().catch(() => {}) }
+      resolve(value)
+    }
+    try { worker = new Worker(new URL(import.meta.url), { workerData: { kind: WORKER_KIND, personalHome, generationId, stallMs } }) } catch { settle({ code: 'personal-composition-unavailable' }); return }
+    timer = setTimeout(() => settle({ code: 'personal-composition-unavailable' }), deadlineMs)
+    timer.unref?.()
+    worker.once('message', settle)
+    worker.once('error', () => settle({ code: 'personal-composition-unavailable' }))
+    worker.once('exit', () => settle({ code: 'personal-composition-unavailable' }))
+  })
+}
+
+// Test seam only: `compose` replaces the module's composePersonalWorkspace for the binding and every validation of
+// it, `build` the canonical build that serves its graph, and `worker` the worker's deadline (and a stall, so a worker that
+// never answers can be shown). Production code uses bindPersonalWorkspace.
+export function createPersonalWorkspaceBinderForOracleTests({ compose = composePersonalWorkspace, build = null, worker = {} } = {}) {
+  const route = { compose, offThread: compose === composePersonalWorkspace, build, worker }
+  const bind = ({ personalHome, generationId } = {}) => {
+    // The validity authority first: a refusal propagates as the module's own typed refusal, and nothing is read or
+    // written after it.
+    const composed = composeHere(compose, { personalHome, generationId })
+    return assemble({ personalHome, generationId }, composed, route)
+  }
+  // The same binding, with the composition off the event loop.
+  bind.offThread = async ({ personalHome, generationId } = {}) => {
+    const composed = route.offThread ? await composeInWorker({ personalHome, generationId }, route.worker) : composeHere(compose, { personalHome, generationId })
+    if (typeof composed.code === 'string') {
+      if (composed.code === 'personal-composition-unavailable') refuse(composed.code, 'the personal workspace could not be composed off the event loop; nothing is bound')
+      throw new PersonalWorkspaceRefusal(composed.code)
+    }
+    return assemble({ personalHome, generationId }, composed, route)
+  }
+  return bind
+}
+
+export const bindPersonalWorkspace = createPersonalWorkspaceBinderForOracleTests()
+
+// A refusal of the personal-workspace module becomes the maintenance refusal with the same code, as at every build, so
+// the engine and every command report it typed and no view stays current.
+const asMaintenanceRefusal = (error, message) => {
+  if (error instanceof PersonalWorkspaceRefusal) refuse(error.code, message, { source: 'personal-workspace' })
+  throw error
+}
+
+// The project of a binding, for a loader that may block (a command run once).
+export function loadBoundProject({ personalHome, generationId } = {}, { bind = bindPersonalWorkspace } = {}) {
+  try { return bind({ personalHome, generationId }).project } catch (error) { return asMaintenanceRefusal(error, 'the personal workspace refused this generation; nothing is loaded from it') }
+}
+
+// The project of a binding, for a loader on a service's event loop: the composition runs in a worker. The engine
+// awaits its loader, so this is the loader a service uses.
+export async function loadBoundProjectOffThread({ personalHome, generationId } = {}, { bind = bindPersonalWorkspace } = {}) {
+  try { return (await bind.offThread({ personalHome, generationId })).project } catch (error) { return asMaintenanceRefusal(error, 'the personal workspace refused this generation; nothing is loaded from it') }
+}
+
+// The binding a project carries, or null for every other project.
+export function personalWorkspaceBindingOf(project) {
+  return project !== null && typeof project === 'object' && Object.hasOwn(project, BINDING) ? project[BINDING] : null
+}
+
+// The graph of a bound project, or null when the project carries no binding. `fileCache` and `observedDigest` are the
+// caller's, as for any build. With `defer`, a key the composition has not confirmed is not confirmed here: the build
+// refuses `personal-validation-pending`, and the caller confirms it off the event loop (validatePersonalWorkspace) and
+// builds again.
+export function personalWorkspaceGraph(project, { fileCache = null, observedDigest = null, defer = false } = {}) {
+  const binding = personalWorkspaceBindingOf(project)
+  if (binding === null) {
+    if (project?.config?.ext?.[OBSIDIAN_EXT_KEY]?.ext?.[PERSONAL_MEMBER_KEY] !== undefined) {
+      refuse('personal-binding-lost', `the project's Obsidian settings use the reserved key ext["${PERSONAL_MEMBER_KEY}"], which only a personal-workspace binding sets, and the project carries no binding; nothing is prepared from it`)
+    }
+    return null
+  }
+  const route = ROUTES.get(binding)
+  if (route === undefined) refuse('personal-binding-unrecognized', 'the project carries a personal-workspace binding this release did not make; nothing is prepared from it')
+  if (project.configPath !== path.join(generationRoot(binding), 'atelier.project.json')) refuse('personal-binding-mismatch', 'the project is not the configuration of the generation it is bound to; nothing is prepared from it')
+  const pending = () => refuse(PERSONAL_VALIDATION_PENDING, 'the personal workspace has changed since it was last composed; it is composed again before a graph is used', { source: 'personal-workspace-pending' })
+  const confirmed = CONFIRMED.get(binding)
+  // Inputs that changed are composed before anything is built from them.
+  let inputs
+  try { inputs = inputsDigest(binding) } catch (error) { CONFIRMED.delete(binding); asMaintenanceRefusal(error, 'the personal workspace refused this generation; nothing is prepared from it') }
+  if (confirmed?.inputs !== inputs) {
+    if (defer) pending()
+    confirmHere(route, binding)
+  }
+  const build = route.build ?? ((target, options) => buildCanonicalGraph(target, { ...options, isLinkTargetEligible: linkTargetRule(binding.overlayRepoId) }))
+  const graph = build(project, { fileCache, observedDigest })
+  if (CONFIRMED.get(binding)?.facts === graphFactsDigest(graph)) return graph
+  if (defer) pending()
+  confirmHere(route, binding)
+  if (CONFIRMED.get(binding)?.facts === graphFactsDigest(graph)) return graph
+  // Composed just now, and still another graph: the sources moved between the two reads, or the build is not the
+  // composition's. Nothing is prepared from it.
+  return refuse('personal-graph-unconfirmed', 'the graph built for the personal workspace is not the one its composition built; nothing is prepared from it', { source: 'personal-workspace' })
+}
+
+function confirmHere(route, binding) {
+  try { CONFIRMED.set(binding, composeHere(route.compose, binding).key) } catch (error) { CONFIRMED.delete(binding); asMaintenanceRefusal(error, 'the personal workspace refused this generation; nothing is prepared from it') }
+}
+
+// Asks the composition again, off the event loop when it can: `{ ok: true, changed }` when it accepts the generation
+// (`changed` when its key differs from the one last confirmed), `{ ok: false, code }` when it refuses. Null for a project
+// without a binding. The engine asks this before a build that found its key unconfirmed, and at every full
+// reconciliation of a bound project.
+export async function validatePersonalWorkspace(project) {
+  const binding = personalWorkspaceBindingOf(project)
+  if (binding === null) return null
+  const route = ROUTES.get(binding)
+  if (route === undefined) return { ok: false, code: 'personal-binding-unrecognized' }
+  let composed
+  if (route.offThread) composed = await composeInWorker(binding, route.worker)
+  else {
+    try { composed = composeHere(route.compose, binding) } catch (error) { if (!(error instanceof PersonalWorkspaceRefusal)) throw error; composed = { code: error.code } }
+  }
+  if (typeof composed.code === 'string') { CONFIRMED.delete(binding); return { ok: false, code: composed.code } }
+  const previous = CONFIRMED.get(binding)
+  CONFIRMED.set(binding, composed.key)
+  return { ok: true, changed: previous?.inputs !== composed.key.inputs || previous?.facts !== composed.key.facts }
+}
+
+// The authored and generation files whose change means the binding must be asked again: the manifest, the overlay and
+// the bound generation's record. Observed as configuration by the engine. Empty for any other project.
+export function personalWorkspaceInputs(project) {
+  const binding = personalWorkspaceBindingOf(project)
+  if (binding === null) return []
+  return [path.join(binding.personalHome, 'atelier.personal.json'), path.join(binding.personalHome, 'atelier.overlay.json'), path.join(generationRoot(binding), 'generation.json')]
+}
+
+// The repository of a bound project's private notes, or null. A vault edit to one of them is never applied into a
+// module-owned generation, and is not proposed yet: it stays held in the vault.
+export function personalOverlayRepoOf(project) {
+  return personalWorkspaceBindingOf(project)?.overlayRepoId ?? null
+}
+
+// Settings that a personal binding takes from the overlay or does not have yet. A saved view is authored in the
+// overlay, so `view add` would write a module-owned generation file; who may see and where vaults live wait for a
+// stable per-person projection configuration. Refused before anything is resolved or written.
+export function refuseOnPersonalBinding(project, operation) {
+  if (personalWorkspaceBindingOf(project) === null) return
+  if (operation === 'view add') refuse('views-from-personal-overlay', 'the views of a personal workspace come from its overlay; nothing was written', { operation })
+  refuse('personal-binding-decision-unavailable', `${operation} is not available for a personal workspace yet; nothing was written`, { operation })
+}
+
+// The worker side of composeInWorker: one composition, its summary, and exit.
+if (!isMainThread && workerData?.kind === WORKER_KIND) {
+  const binding = { personalHome: workerData.personalHome, generationId: workerData.generationId }
+  // A worker that never answers, for the deadline test only: blocked as a system call would block it.
+  if (workerData.stallMs > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, workerData.stallMs)
+  try {
+    parentPort.postMessage(composeHere(composePersonalWorkspace, binding))
+  } catch (error) {
+    parentPort.postMessage({ code: error instanceof PersonalWorkspaceRefusal ? error.code : 'personal-composition-unavailable' })
+  }
+}

package/src/projection/obsidian/proposals/adapter.mjs

@@ -6,7 +6,7 @@ import { AtelierDiagnosticError } from '../../../project/config.mjs'
 import { compareText, isoTime } from '../../../runtime/obsidian/documents.mjs'
 import { ObsidianMaintenanceRefusal } from '../../../runtime/obsidian/errors.mjs'
 import { readMachineSettings } from '../../../runtime/obsidian/machine-settings.mjs'
-import { DEFAULT_ELIGIBILITY, createProductionSeams } from '../../../runtime/obsidian/pipeline.mjs'
+import { createProductionSeams, eligibilityFor } from '../../../runtime/obsidian/pipeline.mjs'
 import { acquirePrivateGenerationLock, createAbandonmentProof } from '../../../runtime/obsidian/private-lock.mjs'
 import { OBSIDIAN_EXT_KEY, ObsidianContractRefusal, assertObsidianContract } from '../contracts.mjs'
 import { SOURCE_APPLY_PRIMITIVES } from '../edits/apply.mjs'
@@ -15,6 +15,7 @@ import { isIdentifier } from '../edits/object-identity.mjs'
 import { openObjectStore } from '../edits/object-store.mjs'
 import { decideApply } from '../edits/policy.mjs'
 import { applyEditLens } from '../edits/regions.mjs'
+import { PERSONAL_VALIDATION_PENDING, personalOverlayRepoOf } from '../personal-workspace.mjs'
 import { PublicationRefusal } from '../recovery/store.mjs'
 import {
   PROPOSAL_BACKPRESSURE, PROPOSAL_LEDGER_LIMITS, classifyLedgerRead, classifyStoreRefusal, estimateEventLineBytes, isDue, isExhausted, nextAttemptAt, preflightAppend,
@@ -168,7 +169,7 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
   // two questions asked of the machine; `proveAbandoned` is the proof a held lock is passed over with.
   return function createProposalAdapter(options = {}) {
     const {
-      crash = () => {}, bounds: boundsInput = {}, limits = PROPOSAL_LEDGER_LIMITS, eligibility = DEFAULT_ELIGIBILITY,
+      crash = () => {}, bounds: boundsInput = {}, limits = PROPOSAL_LEDGER_LIMITS, eligibility: fixedEligibility = null,
       openStore = createProposalStore, objectStore = openObjectStore, isGitIgnored = SOURCE_APPLY_PRIMITIVES.isGitIgnored, proveAbandoned = createAbandonmentProof(), queueCrash = () => {},
     } = options
     const bounds = { ...PROPOSAL_BACKPRESSURE, ...boundsInput }
@@ -184,6 +185,9 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
     let observation = { key: null, run: null }
     // Edits whose operation is known not to be a proposal. A cache: losing it costs one read of an object.
     const notProposals = new Set()
+    // Set when an observation found the personal workspace's graph pending: the edits it could not look at are offered
+    // again on the next observation, not parked until a full reconciliation.
+    let observePendingAgain = false
 
     // -- the workspace of one call -------------------------------------------
 
@@ -198,12 +202,31 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         if (!stores.has(scopeId)) stores.set(scopeId, seams.createRecoveryStore({ workspaceRoot, workspaceId, scopeId, repositoryRoots }))
         return stores.get(scopeId)
       }
-      // The canonical graph as it is now and the corpus profile of this machine, built once per call. Throws typed.
+      // The canonical graph as it is now and the corpus profile of this machine, built once per call with the notes the
+      // machine settings let into a view, as the engine builds it (eligibilityFor). Throws typed.
       let corpus = null
-      const currentCorpus = () => (corpus ??= {
-        graph: seams.buildGraph({ project, eligibility }),
-        profile: seams.profileFor({ project, workspaceId, audienceAllow: readMachineSettings({ workspaceRoot, workspaceId })?.audienceAllow ?? [] }),
-      })
+      // A pending answer is kept for the call too, so a call that looks at several edits builds at most once.
+      let pendingCorpus = null
+      const currentCorpus = () => {
+        if (corpus !== null) return corpus
+        if (pendingCorpus !== null) throw pendingCorpus
+        const machine = readMachineSettings({ workspaceRoot, workspaceId })
+        corpus = {
+          // The engine hands its deferral over: a personal workspace is then never composed on its event loop here.
+          graph: (() => {
+            try { return seams.buildGraph({ project, eligibility: fixedEligibility ?? eligibilityFor({ machine, project }), deferPersonalValidation: context.deferPersonalValidation === true }) } catch (error) {
+              if (error?.code === PERSONAL_VALIDATION_PENDING) pendingCorpus = error
+              throw error
+            }
+          })(),
+          profile: seams.profileFor({ project, workspaceId, audienceAllow: machine?.audienceAllow ?? [] }),
+        }
+        return corpus
+      }
+      // Whether the personal workspace's graph is pending on this call. Asked only where a graph would be built anyway.
+      const personalPending = () => {
+        try { currentCorpus(); return false } catch (error) { if (error?.code === PERSONAL_VALIDATION_PENDING) return true; if (isTyped(error)) return false; throw error }
+      }
       // true, false, or null when the canonical graph cannot be read now. The rule is the one source apply asks.
       const visible = options.isVisible ? (identity) => options.isVisible(identity, context) : ({ repoId, nodeId }) => {
         let built
@@ -223,6 +246,7 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       return {
         ...context, recoveryOf, visible, clock, env: env ?? context.env ?? process.env,
         corpus: currentCorpus,
+        personalPending,
         objects: () => (objects ??= objectStore({ stateRoot: workspaceRoot, workspaceId, repositoryRoots, clock })),
         queue,
         managedRoots: () => [workspaceRoot, ...[...stores.values()].map((store) => store.vaultRoot)],
@@ -304,6 +328,8 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
         if (requireOpenEdit && editState !== 'open') return known ? refused(`edit-${editState}`) : outcome('skipped', null, { code: `edit-${editState}` })
         // The object store no longer says this is a proposed structural edit, so there is nothing to describe.
         if (item.observed === null) return refused('operation-not-proposed')
+        // A personal workspace whose graph is pending leaves the operation as it is: no attempt is spent on this tick.
+        if (workspace.deferPersonalValidation === true && personalOverlayRepoOf(workspace.project) !== null && workspace.personalPending()) return outcome('deferred', history?.head ?? null, { code: PERSONAL_VALIDATION_PENDING })
         const resolved = resolveProposalRoute({ project: workspace.project, workspaceId: workspace.workspaceId, identity: item, sourcePath: item.sourcePath, managedRoots: workspace.managedRoots(), isVisible: workspace.visible, isGitIgnored, env: env ?? workspace.env ?? process.env })
         if (!resolved.ok && !resolved.transient) return refused(resolved.code)
         // Recorded before anything is asked of the store.
@@ -432,7 +458,20 @@ export function createProposalAdapterForOracleTests(primitives = PROPOSAL_ADAPTE
       async observe(context, { retryRefused = false } = {}) {
         const workspace = open(context)
         const edits = Array.isArray(context.edits) ? context.edits : []
-        return { adapterId: PROPOSAL_ADAPTER_ID, observed: observation.run(workspace, { edits, retryRefused }) }
+        // A private note of a personal workspace lives in a generation the personal-workspace module owns: its edit is
+        // not observed, recorded or proposed, and stays held in the vault. Answered by name, with nothing written.
+        const overlayRepoId = personalOverlayRepoOf(workspace.project)
+        const isPrivate = (edit) => overlayRepoId !== null && edit?.identity?.repoId === overlayRepoId
+        const privateNotes = edits.filter((edit) => isPrivate(edit) && edit.closedAt === null)
+          .map((edit) => ({ editId: edit.editId, repoId: edit.identity.repoId, nodeId: edit.identity.nodeId, status: 'refused', code: 'personal-overlay-not-proposed' }))
+        const shared = edits.filter((edit) => !isPrivate(edit))
+        // The graph is built only when an edit is looked at, as for any project. When the personal workspace's graph is
+        // pending, the edits it reached are not reported or recorded, and are offered again on the next observation.
+        const retry = retryRefused || observePendingAgain
+        const looked = observation.run(workspace, { edits: shared, retryRefused: retry })
+        const pending = looked.filter((item) => item.code === PERSONAL_VALIDATION_PENDING)
+        observePendingAgain = pending.length > 0
+        return { adapterId: PROPOSAL_ADAPTER_ID, observed: [...privateNotes, ...looked.filter((item) => item.code !== PERSONAL_VALIDATION_PENDING)], ...(pending.length > 0 ? { deferred: PERSONAL_VALIDATION_PENDING } : {}) }
       },
 
       // The tick. `context` is { project, workspaceRoot, workspaceId, repositoryRoots, edits }: the pending edit

package/src/projection/obsidian/proposals/observation.mjs

@@ -126,6 +126,11 @@ export function createTickObservation(options = {}) {
   // The note exactly as it was published, which the lens needs to tell generated bytes from authored ones. The
   // publisher keeps no copy of a note it created, so the note is prepared again from the sources as they are now and
   // used only when it has the digest the manifest recorded; a retained object of that digest serves as well.
+  //
+  // A source replaced between the look at its path and its open (ELEAFCHANGED) is another program writing it, as it
+  // is to the publisher and to source apply: the preparation answers null, and the caller reads the source again and
+  // refuses stale-source when it changed. Only a preparation that succeeded is kept for its scope and generation: one
+  // failure tells of one moment and is never the answer for the other edits of that generation in the tick.
   function publishedNoteOf(workspace, { scope, manifest, noteEntry }, now) {
     const store = workspace.recoveryOf(scope.scopeId)
     const kept = retained(store, noteEntry.noteDigest)
@@ -134,7 +139,7 @@ export function createTickObservation(options = {}) {
     // Prepared in the vault layout of the edit's generation, once per generation.
     const preparedKey = `${scope.scopeId}\u0000${manifest.generationId}`
     if (!workspace.prepared.has(preparedKey)) {
-      let files = []
+      let files
       try {
         const { graph, profile } = workspace.corpus()
         const snapshot = seams.captureSnapshot({ project: workspace.project, graph, workspaceId: workspace.workspaceId, index: new Map(), configDigest: manifest.ext?.[EXT]?.configDigest ?? `sha256:${'0'.repeat(64)}`, capturedAt: now })
@@ -143,7 +148,10 @@ export function createTickObservation(options = {}) {
           snapshot, profile, scope, persistentPathRegistry, priorManifest: manifest, existingSettings: null, clock: workspace.clock,
           vaultRootBytes: Buffer.byteLength(store.vaultRoot, 'utf8'), layout: manifestLayoutVersion(manifest),
         }).files
-      } catch (error) { if (!isTyped(error) && !GONE.has(error?.code)) throw error }
+      } catch (error) {
+        if (!isTyped(error) && error?.code !== 'ELEAFCHANGED' && !GONE.has(error?.code)) throw error
+        return null
+      }
       workspace.prepared.set(preparedKey, files)
     }
     const file = workspace.prepared.get(preparedKey).find((item) => item.path === noteEntry.path && item.digest === noteEntry.noteDigest)