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

package/src/build/ledger.mjs

@@ -0,0 +1,88 @@
+import { replay, unique } from '../harnesses/history.mjs'
+import { assertAudience, assertHandoff } from '../harnesses/contracts.mjs'
+const terminal = new Set(['completed', 'failed', 'cancelled'])
+export function inspectBuild(records) {
+  const attempts = new Map(), gates = new Map(), decisions = []
+  let candidate
+  const state = replay(records, 'build', 'objective', (record, ctx) => {
+    const d = record.data, refs = []
+    const resolve = (pin, kinds) => { const r = ctx.resolve(pin, kinds); refs.push(r.id); return r }
+    const objective = ctx.first.data
+    switch (record.kind) {
+      case 'objective':
+        unique(d.gates.map(g => g.id), 'build gate'); unique(d.dependencies.map(d => d.id), 'build dependency'); unique(d.allowedEffects, 'allowed effect')
+        if (!d.gates.some(g => g.required)) throw new Error('build needs a required gate')
+        for (const dependency of d.dependencies) {
+          const h = assertHandoff(dependency.handoff)
+          if (h.source.profile === 'build' || h.target.profile !== 'build' || h.target.repository !== d.repository) throw new Error('build dependency requires knowledge or inquiry handoff to this repository')
+          assertAudience(d.audience, h.audience)
+        }
+        break
+      case 'candidate':
+        resolve(d.objective, ['objective'])
+        if (d.repository !== objective.repository) throw new Error('candidate repository mismatch')
+        if (candidate) {
+          if (!d.supersedes || ctx.resolve(d.supersedes, ['candidate']).id !== candidate.id) throw new Error('candidate must supersede current candidate')
+          if ([...attempts.values()].some(a => a.candidate === candidate.id && !terminal.has(a.state))) throw new Error('unsettled attempt prevents candidate replacement')
+          ctx.invalidate(candidate.id, `candidate-replaced:${record.id}`)
+        } else if (d.supersedes) throw new Error('initial candidate cannot supersede missing work')
+        candidate = record
+        break
+      case 'attempt':
+        resolve(d.candidate, ['candidate']); unique(d.effects, 'attempt effect')
+        if (d.effects.some(effect => !objective.allowedEffects.includes(effect))) throw new Error('attempt effect is outside declared scope')
+        if (attempts.size >= objective.maxAttempts) throw new Error('build attempt budget exhausted')
+        if ([...attempts.values()].some(a => a.candidate === d.candidate.id && a.operation === d.operation && !['failed', 'cancelled'].includes(a.state))) throw new Error('operation already completed or unsettled; reconcile before retry')
+        attempts.set(record.id, { candidate: d.candidate.id, operation: d.operation, state: 'intent', last: record.id })
+        break
+      case 'progress': {
+        const original = resolve(d.attempt, ['attempt']), previous = attempts.get(original.id)
+        const allowed = { intent: ['running', 'uncertain', 'completed', 'failed', 'cancelled'], running: ['uncertain', 'completed', 'failed', 'cancelled'], uncertain: ['completed', 'failed', 'cancelled'] }
+        if (!allowed[previous.state]?.includes(d.state)) throw new Error('invalid or terminal attempt transition')
+        refs.push(previous.last)
+        attempts.set(original.id, { ...previous, state: d.state, last: record.id })
+        break
+      }
+      case 'gate': {
+        resolve(d.candidate, ['candidate'])
+        if (!objective.gates.some(g => g.id === d.gate)) throw new Error('undeclared build gate')
+        if (d.attempt) {
+          const a = resolve(d.attempt, ['attempt']), status = attempts.get(a.id)
+          if (a.data.candidate.id !== d.candidate.id || (d.status === 'passed' && status.state !== 'completed')) throw new Error('gate requires completed attempt on exact candidate')
+          refs.push(status.last)
+        }
+        const key = `${d.candidate.id}/${d.gate}`, old = gates.get(key)
+        if (old) ctx.invalidate(old.id, `gate-replaced:${record.id}`)
+        gates.set(key, record)
+        break
+      }
+      case 'decision': {
+        resolve(d.candidate, ['candidate']); unique(d.gates.map(g => g.id), 'decision gate')
+        const named = d.gates.map(pin => resolve(pin, ['gate']))
+        if (named.some(g => g.data.candidate.id !== d.candidate.id)) throw new Error('gate names another candidate')
+        if (d.disposition === 'accepted') {
+          for (const required of objective.gates.filter(g => g.required)) {
+            const gate = gates.get(`${d.candidate.id}/${required.id}`)
+            if (!gate || gate.data.status !== 'passed' || !named.some(r => r.id === gate.id)) throw new Error('accepted build requires all current required gates')
+          }
+          if ([...attempts.values()].some(a => a.candidate === d.candidate.id && !terminal.has(a.state))) throw new Error('unsettled attempt prevents acceptance')
+        }
+        if (decisions.length) ctx.invalidate(decisions.at(-1).id, `decision-replaced:${record.id}`)
+        decisions.push(record)
+        break
+      }
+      case 'delivery': {
+        const decision = resolve(d.decision, ['decision'])
+        if (decision.data.disposition !== 'accepted' || decisions.at(-1)?.id !== decision.id) throw new Error('delivery requires latest accepted decision')
+        break
+      }
+    }
+    return refs
+  })
+  const stale = new Set(state.reconsider.map(r => r.id))
+  const decision = decisions.filter(r => !stale.has(r.id)).at(-1)
+  return { ...state, candidate: candidate ?? null, attempts: Object.fromEntries(attempts),
+    gates: [...gates.values()].filter(r => !stale.has(r.id)), decision: decision ?? null,
+    reportedAccepted: decision?.data.disposition === 'accepted',
+    dependencyFreshness: 'unverified-until-snapshots-supplied', executionAuthorized: false, authenticatedAcceptance: false }
+}

package/src/capabilities/adoption.mjs

@@ -0,0 +1,381 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { syncPrivateDirectory } from '../project/private-state.mjs'
+import { acquirePrivateLock } from '../project/durable-state.mjs'
+import { assertDocument, HOST_PROFILES, projectSkill, unique, verifyCapabilityRelease } from './package.mjs'
+import { bytesAt, canonical, currentTree, digest, jsonAt, jsonText, objectDigest, replaceJson, stat, tree, within, workspaceRoot, writeNew } from './files.mjs'
+
+export const CAPABILITY_STATE = '.atelier-local/capabilities/state.json'
+const ACTIVE = '.atelier-local/capabilities/active.json'
+const OPERATION_LOCK = '.atelier-local/skill-steward/.operation.lock'
+const TX = '.atelier-local/capabilities/transactions'
+
+export function readCapabilityState(root) {
+  const file = within(root, CAPABILITY_STATE)
+  if (!stat(file)) return null
+  const state = assertDocument(jsonAt(root, CAPABILITY_STATE), 'state')
+  if (state.workspace !== digest(root)) throw new Error('capability state belongs to a different workspace')
+  unique(state.packages.map(item => item.id), 'installed package')
+  unique(state.packages.flatMap(item => item.bindings.map(binding => binding.target.toLowerCase())), 'installed target')
+  for (const item of state.packages) {
+    if (item.id !== item.release.package.id) throw new Error('installed package identity mismatch')
+    for (const binding of item.bindings) validateTarget(binding)
+  }
+  return state
+}
+
+function validateTarget(binding) {
+  if (`${HOST_PROFILES[binding.host]?.target}/${binding.alias}` !== binding.target) throw new Error('binding target differs from the host profile')
+}
+
+function activeJournal(root) {
+  if (!stat(within(root, ACTIVE))) return null
+  const pointer = jsonAt(root, ACTIVE)
+  if (Object.keys(pointer).length !== 1 || !/^[a-f0-9-]{36}$/.test(pointer.id)) throw new Error('invalid active capability transaction')
+  const journal = assertDocument(jsonAt(root, `${TX}/${pointer.id}/journal.json`), 'journal')
+  if (journal.id !== pointer.id || journal.workspace !== digest(root)) throw new Error('transaction belongs to a different workspace')
+  for (const action of journal.actions) {
+    if (!/^\.(agents|claude)\/skills\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(action.target)) throw new Error('transaction target is outside host profiles')
+  }
+  return journal
+}
+
+function prepare(options) {
+  const { adoption, sources = [], availableTools = [], notices = [] } = options
+  const root = workspaceRoot(options.workspaceRoot ?? process.cwd())
+  assertDocument(adoption, 'adoption')
+  unique(adoption.packages.map(item => item.id), 'adoption package')
+  unique(availableTools, 'tool observation')
+  if (availableTools.length > 64 || availableTools.some(tool => !/^[a-z][a-z0-9.-]{0,63}$/.test(tool))) throw new Error('invalid available tools')
+  if (!Array.isArray(sources) || sources.length > 32) throw new Error('too many release sources')
+  if (!Array.isArray(notices) || notices.length > 256) throw new Error('too many release notices')
+  for (const notice of notices) assertDocument(notice, 'notice')
+  const before = readCapabilityState(root)
+  const blockers = [], actions = [], changes = [], projected = new Map(), releases = new Map()
+  if (activeJournal(root)) blockers.push('unfinished-transaction: inspect recovery before applying')
+  if (before && before.enrollment !== adoption.id) blockers.push('enrollment-identity-changed')
+  for (const packageRoot of sources) {
+    const realSource = fs.realpathSync(path.resolve(packageRoot))
+    for (const profile of Object.values(HOST_PROFILES)) {
+      const target = path.join(root, profile.target)
+      if (realSource === target || realSource.startsWith(`${target}${path.sep}`) || target.startsWith(`${realSource}${path.sep}`)) throw new Error('release source overlaps a managed host surface')
+    }
+    const release = verifyCapabilityRelease({ packageRoot: realSource })
+    if (releases.has(release.package.id)) throw new Error('multiple sources for the same package')
+    releases.set(release.package.id, { release, root: realSource })
+  }
+  const versions = [...(before?.versions ?? [])]
+  const nextPackages = []
+  const claimed = new Set()
+  for (const desired of adoption.packages) {
+    const old = before?.packages.find(item => item.id === desired.id)
+    const supplied = releases.get(desired.id)
+    const release = supplied?.release ?? (['retired', 'customized'].includes(desired.mode) ? old?.release : null)
+    if (!release || release.digest !== desired.digest) { blockers.push(`${desired.id}: missing-or-unpinned-release`); continue }
+    const descriptor = release.package
+    if (['managed', 'customized'].includes(desired.mode) && notices.some(notice => notice.id === desired.id && notice.digest === release.digest && notice.status === 'withdrawn')) blockers.push(`${desired.id}: release-withdrawn-by-supplied-notice`)
+    const version = versions.find(item => item.id === desired.id && item.version === descriptor.version)
+    if (version && version.digest !== release.digest) blockers.push(`${desired.id}: immutable-version-reused`)
+    if (!version) versions.push({ id: desired.id, version: descriptor.version, digest: release.digest })
+    if (['customized', 'retired'].includes(desired.mode) && (!old || old.release.digest !== desired.digest)) blockers.push(`${desired.id}: ${desired.mode}-requires-current-adopted-release`)
+    if (['reference', 'retired'].includes(desired.mode) && desired.bindings.length) blockers.push(`${desired.id}: inactive-mode-has-bindings`)
+    if (desired.mode === 'managed' && !desired.bindings.length) blockers.push(`${desired.id}: managed-package-has-no-bindings`)
+    const toolsAdded = descriptor.requirements.tools.filter(tool => !old?.release.package.requirements.tools.includes(tool))
+    const effectsAdded = descriptor.requirements.effects.filter(effect => !old?.release.package.requirements.effects.includes(effect))
+    changes.push({ package: desired.id, fromDigest: old?.release.digest ?? null, toDigest: release.digest, fromMode: old?.mode ?? null, toMode: desired.mode, toolsAdded, effectsAdded })
+    if (['managed', 'customized'].includes(desired.mode)) {
+      for (const tool of descriptor.requirements.tools) {
+        if (!desired.allowedTools.includes(tool)) blockers.push(`${desired.id}: tool-not-admitted:${tool}`)
+        if (!availableTools.includes(tool)) blockers.push(`${desired.id}: tool-not-observed:${tool}`)
+      }
+      for (const effect of descriptor.requirements.effects) if (!desired.allowedEffects.includes(effect)) blockers.push(`${desired.id}: effect-not-admitted:${effect}`)
+    }
+    const bindings = []
+    for (const binding of desired.bindings) {
+      const target = `${HOST_PROFILES[binding.host].target}/${binding.alias}`
+      if (claimed.has(target.toLowerCase())) blockers.push(`${desired.id}: alias-collision:${target}`)
+      claimed.add(target.toLowerCase())
+      const currentDigest = currentTree(root, target)
+      const prior = old?.bindings.find(item => item.target === target)
+      // A different managed publisher cannot acquire an old binding by renaming.
+      const otherOwner = before?.packages.find(item => item.id !== desired.id && item.bindings.some(entry => entry.target === target))
+      if (otherOwner) blockers.push(`${desired.id}: target-owned-by-another-package:${target}`)
+      if (!prior && currentDigest) blockers.push(`${desired.id}: unmanaged-collision:${target}`)
+      const legacyLock = `${HOST_PROFILES[binding.host].target}/.atelier-skill-lock.json`
+      if (stat(within(root, legacyLock)) && jsonAt(root, legacyLock)?.skills?.some(item => item.name === binding.alias)) blockers.push(`${desired.id}: target-owned-by-legacy-steward:${target}`)
+      if (prior && !currentDigest) blockers.push(`${desired.id}: managed-target-missing:${target}`)
+      if (desired.mode === 'customized') {
+        if (!prior || prior.skill !== binding.skill || old.release.digest !== release.digest) {
+          blockers.push(`${desired.id}: customization-requires-existing-binding:${target}`)
+          continue
+        }
+        bindings.push({ ...prior, digest: currentDigest ?? prior.digest })
+        actions.push({ type: 'customize', package: desired.id, target, currentDigest, nextDigest: currentDigest })
+        continue
+      }
+      const restored = old?.mode === 'customized' && currentDigest === prior?.parentDigest
+      if (old?.mode === 'customized' && !restored) blockers.push(`${desired.id}: customization-requires-explicit-fork-or-restoration:${target}`)
+      if (prior && currentDigest !== prior.digest && !restored) blockers.push(`${desired.id}: local-drift:${target}`)
+      if (!supplied) { blockers.push(`${desired.id}: managed-source-required`); continue }
+      const projection = projectSkill({ packageRoot: supplied.root, release, skillId: binding.skill, alias: binding.alias, host: binding.host })
+      projected.set(target, projection.files)
+      bindings.push({ ...binding, target, digest: projection.digest, parentDigest: projection.digest })
+      actions.push({ type: !currentDigest ? 'add' : currentDigest === projection.digest ? 'keep' : 'update', package: desired.id, target, currentDigest, nextDigest: projection.digest })
+    }
+    for (const prior of old?.bindings ?? []) {
+      if (bindings.some(binding => binding.target === prior.target)) continue
+      const currentDigest = currentTree(root, prior.target)
+      const restored = old.mode === 'customized' && currentDigest === prior.parentDigest
+      if (currentDigest !== prior.digest && !restored) blockers.push(`${desired.id}: local-drift:${prior.target}`)
+      if (old.mode === 'customized' && !restored) blockers.push(`${desired.id}: customized-binding-must-be-preserved:${prior.target}`)
+      actions.push({ type: 'retire', package: desired.id, target: prior.target, currentDigest, nextDigest: null })
+    }
+    nextPackages.push({ id: desired.id, release, mode: desired.mode, bindings })
+  }
+  for (const old of before?.packages ?? []) if (!adoption.packages.some(item => item.id === old.id)) blockers.push(`${old.id}: explicit-retirement-required-before-removal`)
+  for (const item of nextPackages.filter(item => ['managed', 'customized'].includes(item.mode))) {
+    for (const dependency of item.release.package.dependencies) {
+      const target = nextPackages.find(entry => entry.id === dependency.id && ['managed', 'customized'].includes(entry.mode))
+      if (!target && dependency.optional) continue
+      if (!target || target.release.digest !== dependency.digest || target.release.package.version !== dependency.version) blockers.push(`${item.id}: unsatisfied-dependency:${dependency.id}`)
+      if (target) {
+        for (const host of new Set(item.bindings.map(binding => binding.host))) {
+          const provided = new Set(target.bindings.filter(binding => binding.host === host)
+            .flatMap(binding => target.release.package.skills.find(skill => skill.id === binding.skill)?.capabilities ?? []))
+          for (const required of dependency.capabilities) if (!provided.has(required)) blockers.push(`${item.id}: dependency-capability-not-bound:${dependency.id}:${required}:${host}`)
+        }
+      }
+    }
+  }
+  const visiting = new Set(), visited = new Set()
+  function visit(id) {
+    if (visiting.has(id)) { blockers.push(`${id}: dependency-cycle`); return }
+    if (visited.has(id)) return
+    visiting.add(id)
+    const entry = nextPackages.find(item => item.id === id && ['managed', 'customized'].includes(item.mode))
+    for (const dependency of entry?.release.package.dependencies ?? []) visit(dependency.id)
+    visiting.delete(id); visited.add(id)
+  }
+  for (const item of nextPackages) visit(item.id)
+  const payload = {
+    schema: 'mnstry.atelier-capability-plan@v1', workspace: digest(root), enrollment: adoption.id,
+    policyDigest: objectDigest(adoption), stateDigest: before ? objectDigest(before) : null,
+    sources: [...releases.values()].map(item => ({ id: item.release.package.id, digest: item.release.digest })).sort((a, b) => a.id.localeCompare(b.id)),
+    tools: [...availableTools].sort(), notices, actions, changes, blockers: [...new Set(blockers)], applyAllowed: blockers.length === 0,
+  }
+  const plan = { ...payload, planDigest: objectDigest(payload) }
+  assertDocument(plan, 'plan')
+  const after = { schema: 'mnstry.atelier-capability-state@v1', workspace: digest(root), enrollment: adoption.id, generation: plan.planDigest, policyDigest: objectDigest(adoption), packages: nextPackages, versions }
+  if (plan.applyAllowed) assertDocument(after, 'state')
+  return { root, plan, before, after, projected }
+}
+
+export function planCapabilityAdoption(options) { return prepare(options).plan }
+
+function operationLocked(reason) {
+  return Object.assign(new Error(`EEXIST: operation lock ${reason}`), { code: 'EEXIST' })
+}
+
+function sameLockFile(left, right) {
+  return left && right && left.identity.dev === right.identity.dev && left.identity.ino === right.identity.ino && left.bytes.equals(right.bytes)
+}
+
+function readOperationLock(root) {
+  const identity = stat(within(root, OPERATION_LOCK))
+  if (!identity) return null
+  // A competing recoverer may remove or replace the lock between the stat and
+  // the read; that is a change during inspection, not an unrelated I/O failure.
+  let bytes
+  try { bytes = bytesAt(root, OPERATION_LOCK) } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ELEAFCHANGED') throw operationLocked('changed during inspection')
+    throw error
+  }
+  const current = stat(within(root, OPERATION_LOCK))
+  if (!current || identity.dev !== current.dev || identity.ino !== current.ino || identity.mtimeMs !== current.mtimeMs || identity.ctimeMs !== current.ctimeMs) throw operationLocked('changed during inspection')
+  return { identity, bytes }
+}
+
+function requireDeadOperationOwner(observed) {
+  if (!observed) return
+  let owner
+  try { owner = JSON.parse(observed.bytes.toString('utf8')) } catch { throw operationLocked('requires its owner') }
+  if (owner?.owner !== 'capability-steward' || !Number.isSafeInteger(owner.pid) || owner.pid < 1 || !/^[a-f0-9-]{36}$/.test(owner.operationId)) throw operationLocked('requires its owner')
+  try { process.kill(owner.pid, 0) } catch (error) {
+    if (error.code === 'ESRCH') return
+    throw operationLocked('owner identity is unavailable')
+  }
+  // An existing PID may be a reused PID. Neither case permits reclamation.
+  throw operationLocked('owner is still alive')
+}
+
+function removeOperationLock(root, observed) {
+  if (!sameLockFile(readOperationLock(root), observed)) return false
+  fs.unlinkSync(within(root, OPERATION_LOCK))
+  syncPrivateDirectory(path.dirname(path.join(root, OPERATION_LOCK)))
+  return true
+}
+
+// After the callback has run, a lock that changed or vanished while cleanup
+// inspected it is not ours: preserve it. EEXIST means "not entered", so it must
+// never be reported for an operation that already committed.
+function releaseOwnedOperationLock(root, owned) {
+  try { return removeOperationLock(root, owned) } catch (error) {
+    if (error.code === 'EEXIST' || error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+function withOperationLock(root, callback) {
+  within(root, path.posix.dirname(OPERATION_LOCK), { directory: true, create: true })
+  const prior = readOperationLock(root)
+  requireDeadOperationOwner(prior)
+  // Durable owner generations serialize competing reclaimers. Keep the shared
+  // exclusive file as well, so the existing skill-sync writer still excludes us.
+  const release = acquirePrivateLock(within(root, OPERATION_LOCK))
+  let owned, failed = false
+  try {
+    if (prior) {
+      requireDeadOperationOwner(prior)
+      if (!removeOperationLock(root, prior)) throw operationLocked('changed before reclamation')
+    }
+    const bytes = Buffer.from(jsonText({ owner: 'capability-steward', operationId: crypto.randomUUID(), pid: process.pid }))
+    writeNew(root, OPERATION_LOCK, bytes)
+    const installed = readOperationLock(root)
+    if (!installed?.bytes.equals(bytes)) throw operationLocked('changed before the operation')
+    owned = installed
+    return callback()
+  } catch (error) { failed = true; throw error } finally {
+    let cleanupError
+    try { if (owned) releaseOwnedOperationLock(root, owned) } catch (error) { cleanupError = error }
+    try { release() } catch (error) { cleanupError ??= error }
+    // A missing or changed file never authorizes deleting a replacement; a
+    // cleanup failure must also preserve the operation's original exception.
+    if (cleanupError && !failed) throw cleanupError
+  }
+}
+
+function move(root, from, to) {
+  const source = within(root, from, { directory: true })
+  const parent = path.posix.dirname(to)
+  within(root, parent, { directory: true, create: true })
+  const target = within(root, to, { directory: true })
+  if (stat(target)) throw new Error('move destination already exists')
+  fs.renameSync(source, target)
+  syncPrivateDirectory(path.dirname(source))
+  syncPrivateDirectory(path.dirname(target))
+}
+
+export function applyCapabilityAdoption(options) {
+  const initial = prepare(options)
+  if (initial.plan.planDigest !== options.confirm) throw new Error('confirmation must exactly match the current adoption plan')
+  if (!initial.plan.applyAllowed) throw new Error(initial.plan.blockers.join('; '))
+  const root = workspaceRoot(initial.root, { write: true })
+  return withOperationLock(root, () => {
+    const prepared = prepare(options)
+    if (prepared.plan.planDigest !== options.confirm) throw new Error('adoption changed before the operation lock')
+    const { plan, before, after, projected } = prepared
+    if (before && canonical({ ...before, generation: null }) === canonical({ ...after, generation: null })) return { changed: false, plan, state: before }
+    const id = crypto.randomUUID(), base = `${TX}/${id}`
+    const journal = { schema: 'mnstry.atelier-capability-journal@v1', id, workspace: digest(root), planDigest: plan.planDigest, phase: 'prepared', before, after, actions: plan.actions }
+    assertDocument(journal, 'journal')
+    for (const action of plan.actions.filter(item => ['add', 'update'].includes(item.type))) {
+      for (const file of projected.get(action.target)) writeNew(root, `${base}/staged/${action.target}/${file.path}`, file.bytes)
+      if (currentTree(root, `${base}/staged/${action.target}`) !== action.nextDigest) throw new Error('staged binding verification failed')
+    }
+    // Re-read both supplied release bytes and repository state after staging.
+    if (prepare(options).plan.planDigest !== plan.planDigest) throw new Error('adoption changed during staging')
+    replaceJson(root, `${base}/journal.json`, journal)
+    writeNew(root, ACTIVE, jsonText({ id }))
+    try {
+      journal.phase = 'applying'; replaceJson(root, `${base}/journal.json`, journal)
+      for (const action of plan.actions) {
+        if (currentTree(root, action.target) !== action.currentDigest) throw new Error('binding changed during adoption')
+        if (['update', 'retire'].includes(action.type)) move(root, action.target, `${base}/before/${action.target}`)
+        if (['add', 'update'].includes(action.type)) move(root, `${base}/staged/${action.target}`, action.target)
+      }
+      for (const action of plan.actions) if (currentTree(root, action.target) !== action.nextDigest) throw new Error('installed binding readback failed')
+      if (objectDigest(readCapabilityState(root)) !== objectDigest(before)) throw new Error('adoption state changed during publication')
+      replaceJson(root, CAPABILITY_STATE, after)
+      if (objectDigest(readCapabilityState(root)) !== objectDigest(after)) throw new Error('adoption state readback failed')
+      journal.phase = 'committed'; replaceJson(root, `${base}/journal.json`, journal)
+      fs.unlinkSync(within(root, ACTIVE)); syncPrivateDirectory(path.dirname(path.join(root, ACTIVE)))
+      return { changed: true, plan, state: after, transaction: id, quarantine: `${base}/before` }
+    } catch (error) {
+      journal.phase = 'recovery-required'
+      replaceJson(root, `${base}/journal.json`, journal)
+      // The cause stays attached for local debugging; the message names no host path.
+      throw new Error('adoption interrupted; inspect capability recovery', { cause: error })
+    }
+  })
+}
+
+export function inspectCapabilityRecovery({ workspaceRoot: input }) {
+  const root = workspaceRoot(input ?? process.cwd())
+  const journal = activeJournal(root)
+  if (!journal) return { pending: false, planDigest: null, blockers: [], actions: [] }
+  const blockers = []
+  const actions = journal.actions.filter(item => ['add', 'update', 'retire'].includes(item.type)).map(action => {
+    const current = currentTree(root, action.target)
+    const backup = currentTree(root, `${TX}/${journal.id}/before/${action.target}`)
+    const held = currentTree(root, `${TX}/${journal.id}/rolled-back/${action.target}`)
+    // Accept each crash boundary, including an interrupted recovery itself.
+    const untouched = current === action.currentDigest && backup === null
+    const exchanged = backup === action.currentDigest && (current === action.nextDigest || current === null) && (held === null || held === action.nextDigest)
+    const added = action.type === 'add' && backup === null && (current === action.nextDigest || current === null) && (held === null || held === action.nextDigest)
+    if (!untouched && !exchanged && !added) blockers.push(`ambiguous-binding:${action.target}`)
+    return { ...action, observedDigest: current, backupDigest: backup, heldDigest: held }
+  })
+  const currentState = readCapabilityState(root)
+  if (![objectDigest(journal.before), objectDigest(journal.after)].includes(objectDigest(currentState))) blockers.push('adoption-state-changed')
+  const payload = { pending: true, transaction: journal.id, phase: journal.phase, actions, blockers, stateDigest: objectDigest(currentState), journalDigest: objectDigest(journal) }
+  return { ...payload, planDigest: objectDigest(payload) }
+}
+
+export function recoverCapabilityAdoption({ workspaceRoot: input, confirm }) {
+  const root = workspaceRoot(input ?? process.cwd(), { write: true })
+  const initial = inspectCapabilityRecovery({ workspaceRoot: root })
+  if (!initial.pending || initial.planDigest !== confirm || initial.blockers.length) throw new Error('recovery requires the exact unblocked recovery plan')
+  return withOperationLock(root, () => {
+    const plan = inspectCapabilityRecovery({ workspaceRoot: root })
+    if (plan.planDigest !== confirm || plan.blockers.length) throw new Error('recovery plan changed')
+    const journal = activeJournal(root), base = `${TX}/${journal.id}`
+    for (const action of [...plan.actions].reverse()) {
+      if (currentTree(root, action.target) !== action.observedDigest) throw new Error('binding changed during recovery')
+      if (action.observedDigest === action.currentDigest && action.backupDigest === null) continue
+      if (action.observedDigest !== null) move(root, action.target, `${base}/rolled-back/${action.target}`)
+      if (action.backupDigest !== null) move(root, `${base}/before/${action.target}`, action.target)
+    }
+    for (const action of plan.actions) if (currentTree(root, action.target) !== action.currentDigest) throw new Error('recovery binding readback failed')
+    if (journal.before) replaceJson(root, CAPABILITY_STATE, journal.before)
+    else if (stat(within(root, CAPABILITY_STATE))) { fs.unlinkSync(within(root, CAPABILITY_STATE)); syncPrivateDirectory(path.dirname(path.join(root, CAPABILITY_STATE))) }
+    journal.phase = 'rolled-back'; replaceJson(root, `${base}/journal.json`, journal)
+    fs.unlinkSync(within(root, ACTIVE)); syncPrivateDirectory(path.dirname(path.join(root, ACTIVE)))
+    return { recovered: true, transaction: journal.id, state: readCapabilityState(root), preserved: `${base}/rolled-back` }
+  })
+}
+
+export function inspectCapabilityAdoption({ workspaceRoot: input }) {
+  const root = workspaceRoot(input ?? process.cwd())
+  const state = readCapabilityState(root)
+  const packages = (state?.packages ?? []).map(item => ({
+    id: item.id, version: item.release.package.version, digest: item.release.digest, mode: item.mode,
+    bindings: item.bindings.map(binding => {
+      const observedDigest = currentTree(root, binding.target)
+      return { ...binding, observedDigest, installed: observedDigest === binding.digest ? 'current' : observedDigest === null ? 'missing' : 'drifted', hostObserved: 'unknown', exercised: 'unknown' }
+    }),
+  }))
+  return { schema: 'mnstry.atelier-capability-status@v1', workspace: digest(root), enrollment: state?.enrollment ?? null, generation: state?.generation ?? null, policyDigest: state?.policyDigest ?? null, recovery: inspectCapabilityRecovery({ workspaceRoot: root }), packages }
+}
+
+export function inspectCapabilityFleet({ workspaces }) {
+  if (!Array.isArray(workspaces) || workspaces.length > 64) throw new Error('fleet requires at most 64 explicitly enrolled repositories')
+  const repositories = workspaces.map(input => {
+    try { return { ok: true, status: inspectCapabilityAdoption({ workspaceRoot: input }) } }
+    catch { return { ok: false, workspace: digest(path.resolve(input)), error: 'repository-inspection-failed' } }
+  })
+  const ids = repositories.filter(item => item.ok && item.status.enrollment).map(item => item.status.enrollment)
+  return { schema: 'mnstry.atelier-capability-fleet@v1', repositories, duplicateEnrollments: [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))], atomicAcrossRepositories: false }
+}
+
+export { withOperationLock }

package/src/capabilities/evidence.mjs

@@ -0,0 +1,140 @@
+import fs from 'node:fs'
+import { inspectCapabilityAdoption, inspectCapabilityRecovery, readCapabilityState, withOperationLock } from './adoption.mjs'
+import { assertDocument, unique } from './package.mjs'
+import { currentTree, digest, jsonAt, jsonText, objectDigest, stat, within, workspaceRoot, writeNew } from './files.mjs'
+
+const EVENTS = '.atelier-local/capabilities/events'
+const IDENTIFIER_PATTERN = /^[a-z][a-z0-9.-]{0,63}$/
+
+export function readCapabilityEvents({ workspaceRoot: input }) {
+  const root = workspaceRoot(input ?? process.cwd())
+  const directory = within(root, EVENTS, { directory: true })
+  if (!stat(directory)) return []
+  const names = fs.readdirSync(directory).sort()
+  if (names.length > 4096) throw new Error('capability event ceiling reached; archive reviewed events before adding more')
+  return names.map(name => {
+    if (!/^[a-z][a-z0-9.-]{0,63}\.json$/.test(name)) throw new Error('unrecognized event file')
+    const event = assertDocument(jsonAt(root, `${EVENTS}/${name}`), 'event')
+    if (`${event.id}.json` !== name) throw new Error('event identity differs from its storage path')
+    return event
+  })
+}
+
+export function recordCapabilityEvent({ workspaceRoot: input, event }) {
+  const root = workspaceRoot(input ?? process.cwd(), { write: true })
+  assertDocument(event, 'event')
+  // Metadata is supplied by the caller, never harvested from a host session.
+  // Its schema cannot carry prompts, source excerpts, URLs or free-form prose.
+  if (event.ext && Object.keys(event.ext).length) throw new Error('event extensions are not admitted for local observation storage')
+  return withOperationLock(root, () => {
+    if (inspectCapabilityRecovery({ workspaceRoot: root }).pending) throw new Error('cannot record an event during unfinished adoption')
+    const state = readCapabilityState(root)
+    const item = state?.packages.find(entry => entry.id === event.package)
+    const binding = item?.bindings.find(entry => entry.target === event.binding)
+    if (!binding || item.release.digest !== event.releaseDigest || state.generation !== event.generation || binding.host !== event.host || binding.digest !== event.bindingDigest) throw new Error('event does not identify the current installed binding')
+    if (currentTree(root, binding.target) !== binding.digest) throw new Error('cannot record an event for a drifted binding')
+    const events = readCapabilityEvents({ workspaceRoot: root })
+    if (events.length >= 4096) throw new Error('capability event ceiling reached')
+    if (events.some(item => item.id === event.id)) throw new Error('event identity already recorded')
+    writeNew(root, `${EVENTS}/${event.id}.json`, jsonText(event))
+    return { recorded: true, event, assurance: 'caller-reported-evidence-reference' }
+  })
+}
+
+export function capabilityEvidenceStatus({ workspaceRoot: input, session = null }) {
+  if (session !== null && !IDENTIFIER_PATTERN.test(session)) throw new Error('invalid host session identifier')
+  const status = inspectCapabilityAdoption({ workspaceRoot: input })
+  const events = readCapabilityEvents({ workspaceRoot: input })
+  for (const item of status.packages) {
+    for (const binding of item.bindings) {
+      const related = events.filter(event => event.package === item.id && event.binding === binding.target)
+      const current = related.filter(event => event.generation === status.generation && event.releaseDigest === item.digest && event.bindingDigest === binding.observedDigest && session !== null && event.session === session)
+      for (const [kind, field] of [['host-observed', 'hostObserved'], ['exercise', 'exercised']]) {
+        const recent = current.filter(event => event.kind === kind).sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id)).at(-1)
+        binding[field] = recent ? `reported-${recent.outcome}` : related.some(event => event.kind === kind) ? 'historical-or-other-session' : 'unknown'
+      }
+    }
+  }
+  return { ...status, evidenceAssurance: 'caller-reported; no host probe or model execution', session, events }
+}
+
+export function capabilityImprovementCandidates({ workspaceRoot: input }) {
+  const status = capabilityEvidenceStatus({ workspaceRoot: input })
+  const grouped = new Map()
+  for (const event of status.events) {
+    const item = status.packages.find(item => item.id === event.package && item.digest === event.releaseDigest)
+    if (!item || !item.bindings.some(binding => binding.target === event.binding && binding.digest === event.bindingDigest && binding.installed === 'current') || event.generation !== status.generation) continue
+    const key = `${event.package}|${event.releaseDigest}|${event.binding}|${event.cause}`
+    if (!grouped.has(key)) grouped.set(key, [])
+    grouped.get(key).push(event)
+  }
+  const candidates = []
+  for (const events of grouped.values()) {
+    const failed = events.filter(event => event.outcome === 'failed' && ['exercise', 'feedback', 'evaluation'].includes(event.kind))
+    // Duplicate reports for one session/evidence do not count as repetition.
+    const independent = new Map(failed.map(event => [`${event.session}|${event.evidenceDigest}`, event]))
+    if (independent.size < 2) continue
+    const first = failed[0]
+    candidates.push({ package: first.package, releaseDigest: first.releaseDigest, binding: first.binding, cause: first.cause,
+      proposal: first.cause === 'skill' ? 'review-skill' : first.cause === 'unknown' ? 'investigate-cause' : `review-${first.cause}`,
+      evidence: [...independent.values()].map(event => event.id), automaticEdit: false, automaticRetirement: false })
+  }
+  return { schema: 'mnstry.atelier-capability-candidates@v1', candidates, inference: 'reported causes and repetition are review signals, not causal proof' }
+}
+
+// Return reviewable graph source documents, never write to canonical content.
+// The caller chooses a repository, audience and destination through its normal
+// authoring/graph workflow. Generated evidence remains an unreviewed claim.
+export function capabilityGraphSources({ workspaceRoot: input, namespace, audience = 'private' }) {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(namespace) || !['private', 'team', 'operator', 'staff', 'public', 'sensitive'].includes(audience)) throw new Error('invalid graph namespace or audience')
+  const root = workspaceRoot(input ?? process.cwd())
+  const state = readCapabilityState(root), events = readCapabilityEvents({ workspaceRoot: root })
+  if (!state) return { schema: 'mnstry.atelier-capability-graph-sources@v1', files: [], canonicalMutation: false }
+  const documents = new Map()
+  const nodeId = (kind, key) => `${namespace}:capability-${kind}-${objectDigest(key).slice(7)}`
+  function add(kind, key, title, body, relations = {}) {
+    const id = nodeId(kind, key)
+    const metadata = [
+      '---', `title: ${JSON.stringify(title)}`, 'kg:', `  id: ${JSON.stringify(id)}`, '  type: "document"',
+      '  lifecycle: "capability-stewardship"', '  status: "draft"', `  audience: ${JSON.stringify(audience)}`,
+    ]
+    if (Object.keys(relations).length) {
+      metadata.push('  relations:')
+      for (const [relation, targets] of Object.entries(relations)) {
+        metadata.push(`    ${relation}:`)
+        for (const target of targets) metadata.push(`      - ${JSON.stringify(target)}`)
+      }
+    }
+    metadata.push('---', '', `# ${title}`, '', body, '', 'This record describes evidence or adoption. It grants no execution or publication authority.', '')
+    documents.set(id, { path: `${id.split(':')[1]}.md`, content: metadata.join('\n') })
+    return id
+  }
+  const enrollmentId = add('adoption', [state.enrollment, state.generation], `Capability adoption ${state.enrollment}`, `Generation: ${state.generation}\n\nDesired policy digest: ${state.policyDigest}`)
+  for (const version of state.versions) {
+    const packageId = add('package', version.id, `Capability package ${version.id}`, 'Publisher identity is declared. A digest establishes integrity, not publisher authentication.')
+    add('release', [version.id, version.digest], `Release ${version.id} ${version.version}`, `Previously observed release digest: ${version.digest}`, { belongs_to: [packageId] })
+  }
+  for (const item of state.packages) {
+    const packageId = add('package', item.id, `Capability package ${item.id}`, 'Publisher identity is declared. A digest establishes integrity, not publisher authentication.')
+    const releaseId = add('release', [item.id, item.release.digest], `Release ${item.id} ${item.release.package.version}`, `Release digest: ${item.release.digest}\n\nMode: ${item.mode}`, { belongs_to: [packageId] })
+    for (const capability of item.release.package.capabilities) add('outcome', [item.id, capability.id, item.release.digest], `Capability ${capability.id}`, `Provided by release ${item.release.digest}.`, { belongs_to: [releaseId] })
+    for (const evaluation of item.release.package.evaluations) add('evaluation', [item.id, item.release.digest, evaluation.id], `Publisher evaluation ${evaluation.id}`, `Publisher-reported outcome: ${evaluation.outcome}\n\nEvidence is bound by the release payload, not independently verified by this graph.`, { evidences: [releaseId] })
+    for (const binding of item.bindings) {
+      add('binding', [state.enrollment, state.generation, binding.target], `Host binding ${binding.alias}`, `Profile: ${binding.host}\n\nInstalled digest: ${binding.digest}\n\nHost loading and successful exercise require separate evidence.`, { implements: [releaseId], belongs_to: [enrollmentId] })
+    }
+  }
+  for (const event of events) {
+    const releaseId = nodeId('release', [event.package, event.releaseDigest])
+    if (!documents.has(releaseId)) throw new Error('event release is absent from adoption history')
+    const adoptionId = nodeId('adoption', [state.enrollment, event.generation])
+    if (!documents.has(adoptionId)) add('adoption', [state.enrollment, event.generation], `Historical adoption ${state.enrollment}`, `Historical generation: ${event.generation}`)
+    const bindingId = nodeId('binding', [state.enrollment, event.generation, event.binding])
+    if (!documents.has(bindingId)) add('binding', [state.enrollment, event.generation, event.binding], `Historical host binding ${event.host}`, `Previously reported binding digest: ${event.bindingDigest}`, { implements: [releaseId], belongs_to: [adoptionId] })
+    add('event', [state.enrollment, event.id], `Reported ${event.kind} ${event.id}`, `Outcome: ${event.outcome}\n\nCause reported: ${event.cause}\n\nEvidence digest: ${event.evidenceDigest}\n\nReview status: unreviewed caller report.`, { evidences: [bindingId] })
+  }
+  for (const proposal of capabilityImprovementCandidates({ workspaceRoot: root }).candidates) {
+    add('proposal', [state.enrollment, proposal.package, proposal.releaseDigest, proposal.binding, proposal.cause], `Proposed ${proposal.proposal}`, 'A review proposal from reported evidence; no edit or retirement is authorized.', { related: proposal.evidence.map(id => nodeId('event', [state.enrollment, id])) })
+  }
+  unique([...documents.values()].map(item => item.path), 'graph source path')
+  return { schema: 'mnstry.atelier-capability-graph-sources@v1', files: [...documents.values()], canonicalMutation: false }
+}