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

package/src/capabilities/files.mjs

@@ -0,0 +1,124 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { openRegularFileNoFollow, atomicReplacePrivateText, syncPrivateDirectory } from '../project/private-state.mjs'
+
+export const LIMITS = Object.freeze({ files: 512, directories: 256, bytes: 8 * 1024 * 1024, depth: 16 })
+export const digest = (bytes) => `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`
+  return JSON.stringify(value)
+}
+export const objectDigest = (value) => digest(canonical(value))
+export const jsonText = (value) => `${JSON.stringify(value, null, 2)}\n`
+export function stat(file) {
+  try { return fs.lstatSync(file) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+
+export function relativeFile(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(value) ||
+      value.split('/').some(part => part === '.' || part === '..' || part.toLowerCase() === '.git' || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+    throw new Error('invalid portable relative path')
+  }
+  return value
+}
+
+// All callers resolve an explicitly supplied root once. No links below it are
+// followed, including intermediate components and absent write destinations.
+export function within(root, relative, { directory = false, create = false } = {}) {
+  relativeFile(relative)
+  const parts = relative.split('/')
+  let current = root
+  for (let index = 0; index < parts.length; index += 1) {
+    current = path.join(current, parts[index])
+    const isDirectory = index < parts.length - 1 || directory
+    let entry = stat(current)
+    if (!entry && isDirectory && create) {
+      fs.mkdirSync(current, { mode: 0o700 })
+      syncPrivateDirectory(path.dirname(current))
+      entry = stat(current)
+    }
+    if (entry && (entry.isSymbolicLink() || (isDirectory ? !entry.isDirectory() : !entry.isFile()))) throw new Error('redirected or non-regular path component')
+  }
+  return current
+}
+
+export function bytesAt(root, relative) {
+  const file = within(root, relative)
+  const fd = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(fd).size > LIMITS.bytes) throw new Error('file exceeds byte ceiling')
+    const bytes = fs.readFileSync(fd)
+    if (bytes.length > LIMITS.bytes) throw new Error('file exceeds byte ceiling')
+    return bytes
+  } finally { fs.closeSync(fd) }
+}
+
+export function jsonAt(root, relative) {
+  return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesAt(root, relative)))
+}
+
+export function tree(root, relative = '', state = { files: [], bytes: 0, directories: 0 }) {
+  const directory = relative ? within(root, relative, { directory: true }) : root
+  if (!stat(directory)?.isDirectory() || stat(directory).isSymbolicLink()) throw new Error('bundle directory missing or redirected')
+  if (++state.directories > LIMITS.directories || relative.split('/').length > LIMITS.depth) throw new Error('bundle directory ceiling exceeded')
+  for (const name of fs.readdirSync(directory).sort()) {
+    const file = relative ? `${relative}/${name}` : name
+    relativeFile(file)
+    const entry = stat(path.join(root, file))
+    if (entry.isSymbolicLink()) throw new Error('bundle contains a symbolic link')
+    if (entry.isDirectory()) { tree(root, file, state); continue }
+    if (!entry.isFile()) throw new Error('bundle contains a non-regular file')
+    if (state.files.length >= LIMITS.files || state.bytes + entry.size > LIMITS.bytes) throw new Error('bundle size ceiling exceeded')
+    const bytes = bytesAt(root, file)
+    state.bytes += bytes.length
+    if (state.bytes > LIMITS.bytes) throw new Error('bundle size ceiling exceeded')
+    state.files.push({ path: file, bytes })
+  }
+  return state.files
+}
+
+export const fileInventory = (files) => files.map(file => ({ path: file.path, digest: digest(file.bytes), bytes: file.bytes.length }))
+export const treeDigest = (files) => objectDigest(fileInventory(files))
+export function currentTree(root, relative) {
+  const directory = within(root, relative, { directory: true })
+  return stat(directory) ? treeDigest(tree(directory)) : null
+}
+
+export function writeNew(root, relative, bytes) {
+  const parent = path.posix.dirname(relative)
+  if (parent !== '.') within(root, parent, { directory: true, create: true })
+  const file = within(root, relative)
+  const fd = openRegularFileNoFollow(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600)
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+  syncPrivateDirectory(path.dirname(file))
+}
+
+export function replaceJson(root, relative, value) {
+  const parent = path.posix.dirname(relative)
+  if (parent !== '.') within(root, parent, { directory: true, create: true })
+  atomicReplacePrivateText(within(root, relative), jsonText(value))
+}
+
+export function workspaceRoot(input, { write = false } = {}) {
+  const root = fs.realpathSync(path.resolve(input))
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')))
+  const git = args => execFileSync('git', ['-C', root, ...args], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+  const top = fs.realpathSync(git(['rev-parse', '--show-toplevel']))
+  // Git can expand a Windows short-name alias. Preserve case-sensitive paths
+  // and compare actual directory identity when the resolved spellings differ.
+  const rootStat = fs.statSync(root, { bigint: true }), topStat = fs.statSync(top, { bigint: true })
+  if (!rootStat.isDirectory() || !topStat.isDirectory() ||
+      (top !== root && !(rootStat.ino !== 0n && rootStat.dev === topStat.dev && rootStat.ino === topStat.ino))) {
+    throw new Error('capability workspace must be the repository root')
+  }
+  if (write) {
+    if (process.platform === 'win32') throw new Error('capability writes require a qualified POSIX filesystem')
+    if (git(['ls-files', '--', '.atelier-local'])) throw new Error('private capability state is tracked')
+    try { git(['check-ignore', '--quiet', '.atelier-local/']) } catch { throw new Error('capability writes require ignored .atelier-local/ state') }
+  }
+  within(root, '.atelier-local', { directory: true })
+  return root
+}

package/src/capabilities/index.mjs

@@ -0,0 +1,4 @@
+export { HOST_PROFILES, PACKAGE_FILE, RELEASE_FILE, inventorySkillSurfaces, prepareCapabilityRelease, sealCapabilityRelease, validateCapabilityDocument, verifyCapabilityRelease } from './package.mjs'
+export { CAPABILITY_STATE, applyCapabilityAdoption, inspectCapabilityAdoption, inspectCapabilityFleet, inspectCapabilityRecovery, planCapabilityAdoption, recoverCapabilityAdoption } from './adoption.mjs'
+export { capabilityEvidenceStatus, capabilityGraphSources, capabilityImprovementCandidates, readCapabilityEvents, recordCapabilityEvent } from './evidence.mjs'
+export * from './instructions.mjs'

package/src/capabilities/instructions.mjs

@@ -0,0 +1,250 @@
+import fs from 'node:fs'
+import { createLearningStore } from '../learning/store.mjs'
+import { boundedLearningValue, learningDigest } from '../learning/contracts.mjs'
+import { bytesAt, digest, jsonAt, replaceJson, stat, within, workspaceRoot, writeNew } from './files.mjs'
+import { syncPrivateDirectory } from '../project/private-state.mjs'
+import { publishPrivateFile, withPrivateLock } from '../project/durable-state.mjs'
+import { exchangeFiles, probeExchange } from '../projection/obsidian/publication/exchange.mjs'
+import path from 'node:path'
+import Ajv from 'ajv/dist/2020.js'
+
+const instructionSchema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-instruction-adoption.v1.schema.json', import.meta.url)))
+const validateDocument = new Ajv({ strict: true, allErrors: true }).compile(instructionSchema)
+export function validateInstructionAdoption(value) {
+  try { boundedLearningValue(value) } catch (error) { return [error.message] }
+  return validateDocument(value) ? [] : validateDocument.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+}
+function assertDocument(value) {
+  const errors = validateInstructionAdoption(value)
+  if (errors.length) throw new Error(`invalid instruction document: ${errors.slice(0, 3).join('; ')}`)
+  return value
+}
+
+const BASE = '.atelier-local/capabilities/instructions'
+const STATE = `${BASE}/state.json`, ACTIVE = `${BASE}/active.json`
+function withOperationLock(root, operation) {
+  within(root, BASE, { directory: true, create: true })
+  return withPrivateLock(within(root, `${BASE}/operation.lock`), operation)
+}
+const identifier = /^[a-z][a-z0-9-]{0,63}$/
+const clone = value => structuredClone(value)
+const seal = value => assertDocument({ ...value, digest: learningDigest(value) })
+function verified(value, label) {
+  assertDocument(value)
+  const { digest: actual, ...body } = boundedLearningValue(value)
+  if (actual !== learningDigest(body)) throw new Error(`${label} integrity mismatch`)
+  return value
+}
+function readText(root, target) {
+  const file = within(root, target)
+  return stat(file) ? new TextDecoder('utf-8', { fatal: true }).decode(bytesAt(root, target)) : null
+}
+function stateAt(root) {
+  const state = stat(within(root, STATE)) ? verified(jsonAt(root, STATE), 'instruction state') : seal({ schema: 'atelier-instruction-state@v1', workspace: digest(root), revision: 0, bindings: [] })
+  if (state.schema !== 'atelier-instruction-state@v1' || state.workspace !== digest(root) || !Array.isArray(state.bindings) || !Number.isSafeInteger(state.revision)) throw new Error('invalid instruction state')
+  return state
+}
+function activeAt(root) {
+  return stat(within(root, ACTIVE)) ? verified(jsonAt(root, ACTIVE), 'instruction transaction') : null
+}
+function inputOf(options) {
+  const { workspaceId, scope, harnessId, lessonId, target, slot, mode = 'adopt' } = options
+  const input = boundedLearningValue({ workspaceId, scope, harnessId, lessonId, target, slot, mode })
+  if (!identifier.test(slot) || !['adopt', 'retire'].includes(mode) || typeof target !== 'string' ||
+    !/^(?:[A-Za-z0-9_-]+\/)*(?:AGENTS|CLAUDE)\.md$/.test(target)) throw new Error('instruction profile requires a scoped AGENTS.md or CLAUDE.md and stable slot')
+  return input
+}
+function markers(slot) { return [`<!-- atelier:practice:${slot}:start -->`, `<!-- atelier:practice:${slot}:end -->`] }
+function blockOf(text, slot) {
+  const [start, end] = markers(slot), a = text?.indexOf(start) ?? -1, b = text?.indexOf(end) ?? -1
+  if (a === -1 && b === -1) return null
+  if (a === -1 || b === -1 || b < a || text.indexOf(start, a + 1) !== -1 || text.indexOf(end, b + 1) !== -1) throw new Error('instruction markers are ambiguous')
+  return text.slice(a, b + end.length)
+}
+function selected(root, input) {
+  const store = createLearningStore({ workspaceRoot: root, workspaceId: input.workspaceId })
+  const context = store.context({ scope: input.scope, harnessId: input.harnessId })
+  const lesson = context.lessons.find(item => item.id === input.lessonId)
+  if (!lesson || lesson.artifact.kind !== 'instruction') throw new Error('instruction requires current, scoped, explicitly activated learning')
+  if ([lesson.artifact.content, ...lesson.exceptions].some(text => text.includes('<!-- atelier:practice:'))) throw new Error('reserved instruction marker in guidance')
+  return { context, lesson }
+}
+function prepare(root, options) {
+  const input = inputOf(options), state = stateAt(root)
+  if (activeAt(root)) throw new Error('unfinished instruction adoption; recover first')
+  const previous = state.bindings.find(b => b.target.toLowerCase() === input.target.toLowerCase() && b.slot === input.slot)
+  if (previous && (previous.target !== input.target || previous.workspaceId !== input.workspaceId || previous.harnessId !== input.harnessId || learningDigest(previous.scope) !== learningDigest(input.scope))) throw new Error('instruction slot has another owner or scope')
+  if (state.bindings.length >= 128 && !previous) throw new Error('instruction binding ceiling reached')
+  const before = readText(root, input.target), oldBlock = blockOf(before, input.slot)
+  if ((previous?.block ?? null) !== oldBlock) throw new Error('instruction slot is unmanaged or drifted')
+  let pin = previous?.pin ?? null, block = null, learningRevision = null
+  if (input.mode === 'adopt') {
+    const { context, lesson } = selected(root, input)
+    learningRevision = context.revision
+    pin = { lessonId: lesson.id, lessonDigest: lesson.lessonDigest, artifactDigest: lesson.artifact.digest, activationId: lesson.activationId, decisionId: lesson.decisionId }
+    const [start, end] = markers(input.slot)
+    block = [start, `Scope: project ${input.scope.project}; activity ${input.scope.activity}; harness ${input.harnessId}.`,
+      `Practice: ${lesson.id} (${lesson.lessonDigest}). Apply only in this scope; host instructions and tool permissions retain their precedence.`, '',
+      lesson.artifact.content, '', 'Exceptions:', ...lesson.exceptions.map(e => `- ${e}`), end].join('\n')
+  } else if (!previous || previous.pin.lessonId !== input.lessonId) throw new Error('retirement requires the exact owned lesson')
+  const after = oldBlock ? before.replace(oldBlock, () => block ?? '') : `${before ?? ''}${before && !before.endsWith('\n') ? '\n' : ''}${block}\n`
+  const binding = { ...input, pin, block, blockDigest: block === null ? null : digest(block) }
+  const bindings = state.bindings.filter(b => !(b.target === input.target && b.slot === input.slot))
+  if (block !== null) bindings.push(binding)
+  const { digest: ignoredDigest, ...stateBody } = state
+  const next = seal({ ...stateBody, revision: state.revision + 1, bindings })
+  return seal({ schema: 'atelier-instruction-plan@v1', workspace: digest(root), input, previousState: state.digest, nextState: next,
+    learningRevision, pin, before, beforeDigest: before === null ? null : digest(before), after, afterDigest: digest(after),
+    effect: 'write-scoped-instruction-guidance', precedence: 'host-owned', authenticated: false })
+}
+export function planInstructionAdoption(options) {
+  return prepare(workspaceRoot(options.workspaceRoot, { write: true }), options)
+}
+function assertCurrentLearning(root, plan) {
+  if (plan.input.mode === 'retire') return
+  const { lesson } = selected(root, plan.input)
+  if (lesson.lessonDigest !== plan.pin.lessonDigest || lesson.activationId !== plan.pin.activationId || lesson.decisionId !== plan.pin.decisionId) throw new Error('instruction practice is no longer eligible')
+}
+function finish(root, plan) {
+  verified(plan, 'instruction plan'); inputOf(plan.input)
+  if (plan.workspace !== digest(root)) throw new Error('instruction plan belongs to another workspace')
+  const current = readText(root, plan.input.target), state = stateAt(root)
+  if (![plan.previousState, plan.nextState.digest].includes(state.digest)) throw new Error('instruction state changed during recovery')
+  if (current !== plan.before && current !== plan.after) throw new Error('instruction destination changed; preserve edits and reconcile')
+  // Identical re-adoption changes the adoption record, not the file. Recovery
+  // bytes exist only when an exchange was needed; equality alone cannot prove it.
+  if (current === plan.after && plan.before !== null && plan.before !== plan.after && readText(root, `${BASE}/recovery/${plan.digest.slice(7)}/displaced.md`) !== plan.before) throw new Error('displaced instruction source requires reconciliation')
+  // A completed write can be recorded even after withdrawal; inspection then
+  // reports reconsideration and an explicit retirement reconciles the file.
+  if (current !== plan.after) {
+    assertCurrentLearning(root, plan)
+    const target = within(root, plan.input.target)
+    const parent = plan.input.target.split('/').slice(0, -1).join('/')
+    if (parent) within(root, parent, { directory: true, create: true })
+    if (readText(root, plan.input.target) !== plan.before) throw new Error('instruction destination changed before write')
+    if (plan.before === null) {
+      // Non-overwriting publication: a concurrent create refuses.
+      publishPrivateFile(target, plan.after)
+    } else {
+      const recovery = `${BASE}/recovery/${plan.digest.slice(7)}`
+      const directory = within(root, recovery, { directory: true, create: true })
+      const candidatePath = within(root, `${recovery}/displaced.md`)
+      const probe = probeExchange({ directory })
+      if (!probe.supported || fs.statSync(directory).dev !== fs.statSync(path.dirname(target)).dev) throw new Error('instruction atomic exchange unavailable on this volume')
+      if (fs.lstatSync(target).nlink !== 1) throw new Error('hard-linked instruction destination refused')
+      if (!stat(candidatePath)) writeNew(root, `${recovery}/displaced.md`, plan.after)
+      if (readText(root, `${recovery}/displaced.md`) !== plan.after) throw new Error('retained displaced source requires reconciliation')
+      fs.chmodSync(candidatePath, fs.statSync(target).mode & 0o777)
+      exchangeFiles(candidatePath, target)
+      syncPrivateDirectory(directory); syncPrivateDirectory(path.dirname(target))
+      const displaced = readText(root, `${recovery}/displaced.md`)
+      if (displaced !== plan.before) {
+        // Retain the displaced writer before exchanging back. Further writers
+        // can change either path; both sides remain in the recovery directory.
+        writeNew(root, `${recovery}/concurrent-${digest(displaced).slice(7)}.md`, displaced)
+        if (readText(root, plan.input.target) === plan.after) {
+          exchangeFiles(candidatePath, target)
+          syncPrivateDirectory(directory); syncPrivateDirectory(path.dirname(target))
+        }
+        throw new Error('concurrent instruction writer; retained bytes require reconciliation')
+      }
+    }
+  }
+  if (readText(root, plan.input.target) !== plan.after) throw new Error('instruction readback mismatch')
+  if (state.digest !== plan.nextState.digest) replaceJson(root, STATE, plan.nextState)
+  const receipt = seal({ schema: 'atelier-instruction-receipt@v1', workspace: digest(root), planDigest: plan.digest,
+    target: plan.input.target, slot: plan.input.slot, pin: plan.pin, mode: plan.input.mode, resultDigest: plan.afterDigest,
+    stateDigest: plan.nextState.digest, status: 'persisted-and-read-back', hostLoaded: false, behaviorVerified: false })
+  const receiptPath = `${BASE}/receipts/${plan.digest.slice(7)}.json`
+  if (stat(within(root, receiptPath))) {
+    if (learningDigest(jsonAt(root, receiptPath)) !== learningDigest(receipt)) throw new Error('instruction receipt differs')
+  } else writeNew(root, receiptPath, JSON.stringify(receipt, null, 2) + '\n')
+  fs.unlinkSync(within(root, ACTIVE)); syncPrivateDirectory(path.dirname(within(root, ACTIVE)))
+  return receipt
+}
+export function applyInstructionAdoption(options) {
+  const root = workspaceRoot(options.workspaceRoot, { write: true })
+  return withOperationLock(root, () => {
+    const pending = activeAt(root)
+    if (pending) {
+      if (pending.digest !== options.confirm || learningDigest(inputOf(options)) !== learningDigest(pending.input)) throw new Error('another instruction transaction requires recovery')
+      return finish(root, pending)
+    }
+    if (/^sha256:[a-f0-9]{64}$/.test(options.confirm ?? '')) {
+      const receiptPath = `${BASE}/receipts/${options.confirm.slice(7)}.json`
+      if (stat(within(root, receiptPath))) {
+        const receipt = verified(jsonAt(root, receiptPath), 'instruction receipt')
+        const recordedPlan = verified(jsonAt(root, `${BASE}/plans/${options.confirm.slice(7)}.json`), 'instruction plan')
+        if (learningDigest(inputOf(options)) !== learningDigest(recordedPlan.input)) throw new Error('instruction retry input differs')
+        return { ...receipt, duplicate: true, currentDestinationDigest: readText(root, receipt.target) === null ? null : digest(readText(root, receipt.target)) }
+      }
+    }
+    const plan = prepare(root, options)
+    if (plan.digest !== options.confirm) throw new Error('instruction adoption requires the exact current plan digest')
+    const planFile = `${BASE}/plans/${plan.digest.slice(7)}.json`
+    if (stat(within(root, planFile))) {
+      if (learningDigest(jsonAt(root, planFile)) !== learningDigest(plan)) throw new Error('retained plan differs')
+    } else writeNew(root, planFile, JSON.stringify(plan, null, 2) + '\n')
+    replaceJson(root, ACTIVE, plan)
+    return finish(root, plan)
+  })
+}
+export function recoverInstructionAdoption({ workspaceRoot: input, confirm }) {
+  const root = workspaceRoot(input, { write: true })
+  return withOperationLock(root, () => {
+    const plan = activeAt(root)
+    if (!plan || plan.digest !== confirm) throw new Error('recovery requires the exact pending instruction plan digest')
+    return finish(root, plan)
+  })
+}
+export function abandonInstructionAdoption({ workspaceRoot: input, confirm, destinationDigest }) {
+  const root = workspaceRoot(input, { write: true })
+  return withOperationLock(root, () => {
+    const plan = activeAt(root)
+    if (!plan || plan.digest !== confirm) throw new Error('abandonment requires the exact pending instruction plan digest')
+    const current = readText(root, plan.input.target), actual = current === null ? null : digest(current)
+    if (actual !== destinationDigest) throw new Error('destination changed since abandonment inspection')
+    if (current === plan.after || stateAt(root).digest !== plan.previousState) throw new Error('reconcile the applied instruction before retirement')
+    const record = { schema: 'atelier-instruction-abandonment@v1', planDigest: plan.digest, destinationDigest: actual,
+      stateDigest: plan.previousState, sourceMutation: false, retainedRecovery: `${BASE}/recovery/${plan.digest.slice(7)}` }
+    const file = `${BASE}/abandoned/${plan.digest.slice(7)}.json`
+    if (stat(within(root, file))) {
+      if (learningDigest(jsonAt(root, file)) !== learningDigest(record)) throw new Error('prior abandonment has a different destination')
+    } else writeNew(root, file, JSON.stringify(record, null, 2) + '\n')
+    fs.unlinkSync(within(root, ACTIVE)); syncPrivateDirectory(path.dirname(within(root, ACTIVE)))
+    return record
+  })
+}
+export function inspectInstructionAdoption({ workspaceRoot: input }) {
+  const root = workspaceRoot(input), state = stateAt(root)
+  const bindings = state.bindings.map(binding => {
+    let status = 'current', reason = null
+    try {
+      if (blockOf(readText(root, binding.target), binding.slot) !== binding.block) throw new Error('destination drift')
+      const { lesson } = selected(root, binding)
+      if (lesson.lessonDigest !== binding.pin.lessonDigest || lesson.activationId !== binding.pin.activationId) throw new Error('practice revised')
+    } catch (error) { status = 'reconsider'; reason = error.message }
+    return { ...clone(binding), status, reason, hostLoaded: 'unverified' }
+  })
+  const pending = activeAt(root)
+  const text = pending ? readText(root, pending.input.target) : null
+  return { schema: 'atelier-instruction-status@v1', revision: state.revision, pending, pendingDestinationDigest: text === null ? null : digest(text), bindings }
+}
+// Host integration seam. This returns verified selected guidance and records what
+// the consumer actually received. It cannot prove that an agent obeyed the text.
+export function consumeInstructionContext({ workspaceRoot: input, target, slot, session, scope, harnessId }) {
+  if (!identifier.test(session)) throw new Error('bounded session identity required')
+  const root = workspaceRoot(input, { write: true })
+  return withOperationLock(root, () => {
+    if (activeAt(root)) throw new Error('instruction adoption is unsettled')
+    const binding = inspectInstructionAdoption({ workspaceRoot: root }).bindings.find(b => b.target === target && b.slot === slot)
+    if (!binding || binding.status !== 'current' || binding.harnessId !== harnessId || learningDigest(scope) !== learningDigest(binding.scope)) throw new Error('current scoped instruction binding required')
+    const { lesson } = selected(root, binding)
+    const context = { content: lesson.artifact.content, exceptions: lesson.exceptions, scope: binding.scope, pin: binding.pin }
+    const receipt = seal({ schema: 'atelier-instruction-context-receipt@v1', session, target, slot, pin: binding.pin,
+      contextDigest: learningDigest(context), delivery: 'returned-to-calling-consumer', behaviorVerified: false })
+    const file = `${BASE}/use/${receipt.digest.slice(7)}.json`
+    if (!stat(within(root, file))) writeNew(root, file, JSON.stringify(receipt, null, 2) + '\n')
+    return { context, receipt }
+  })
+}

package/src/capabilities/package.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs'
+import { parseSkillFrontmatter } from '../skills/steward.mjs'
+import { bytesAt, canonical, digest, fileInventory, jsonAt, jsonText, objectDigest, relativeFile, stat, tree, treeDigest, within, writeNew } from './files.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-capability.v1.schema.json', import.meta.url), 'utf8'))
+export const PACKAGE_FILE = 'capability-package.json'
+export const RELEASE_FILE = 'capability-release.json'
+export const HOST_PROFILES = Object.freeze({
+  'codex-repo-v1': Object.freeze({ target: '.agents/skills', adapterVersion: 1, discovery: 'repository SKILL.md projection', precedence: 'host-owned; overlapping names require inspection', permissions: 'advisory declarations only', reload: 're-observe in the intended host session after every adoption' }),
+  'claude-repo-v1': Object.freeze({ target: '.claude/skills', adapterVersion: 1, discovery: 'project SKILL.md projection', precedence: 'host-owned; personal, enterprise and plugin surfaces may change resolution', permissions: 'advisory declarations only', reload: 're-observe in the intended host session after every adoption' }),
+})
+
+export function validateCapabilityDocument(document, shape) {
+  return validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }, document)
+}
+export function assertDocument(document, shape) {
+  const errors = validateCapabilityDocument(document, shape)
+  if (errors.length) throw new Error(`invalid capability ${shape}: ${errors.join('; ')}`)
+  return document
+}
+export function unique(values, label) {
+  if (new Set(values).size !== values.length) throw new Error(`duplicate ${label}`)
+}
+
+function validatePackage(descriptor, files) {
+  assertDocument(descriptor, 'package')
+  unique(descriptor.skills.map(skill => skill.id), 'skill identity')
+  unique(descriptor.skills.map(skill => skill.path.toLowerCase()), 'skill path')
+  unique(descriptor.capabilities.map(capability => capability.id), 'capability identity')
+  unique(descriptor.dependencies.map(dependency => dependency.id), 'dependency identity')
+  unique(files.map(file => file.path.toLowerCase()), 'case-insensitive payload path')
+  const paths = new Set(files.map(file => file.path))
+  for (const evaluation of descriptor.evaluations) if (!paths.has(evaluation.path)) throw new Error('evaluation evidence is missing from package')
+  for (const migration of descriptor.migrations) if (!paths.has(migration.path)) throw new Error('migration guidance is missing from package')
+  for (const skill of descriptor.skills) {
+    relativeFile(skill.path)
+    if (!skill.path.startsWith('skills/')) throw new Error('skill path must be below skills/')
+    if (descriptor.skills.some(other => other !== skill && other.path.startsWith(`${skill.path}/`))) throw new Error('overlapping skill roots')
+    if (skill.capabilities.some(id => !descriptor.capabilities.some(item => item.id === id))) throw new Error('skill refers to an unknown capability')
+    const skillFiles = files.filter(file => file.path.startsWith(`${skill.path}/`))
+    const entry = skillFiles.find(file => file.path === `${skill.path}/SKILL.md`)
+    if (!entry) throw new Error('skill entrypoint missing')
+    const parsed = parseSkillFrontmatter(new TextDecoder('utf-8', { fatal: true }).decode(entry.bytes))
+    if (!parsed.ok || parsed.values.name !== skill.name || !parsed.values.description || ['|', '>'].includes(parsed.values.description)) throw new Error('portable skill requires matching name and a single-line description')
+    // References in every Markdown resource are checked, not just SKILL.md.
+    // Scripts remain inert payloads; this is not static program verification.
+    for (const file of skillFiles.filter(file => file.path.endsWith('.md'))) {
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(file.bytes)
+      for (const match of text.matchAll(/!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+        const link = match[1].replace(/^<|>$/g, '').split('#')[0]
+        if (!link || /^[a-z][a-z0-9+.-]*:/i.test(link)) continue
+        const decoded = decodeURIComponent(link)
+        if (path.posix.isAbsolute(decoded) || decoded.includes('\\')) throw new Error('skill resource escapes its bundle')
+        const normalized = path.posix.normalize(path.posix.join(path.posix.dirname(file.path), decoded))
+        if (!normalized.startsWith(`${skill.path}/`) || !paths.has(normalized)) throw new Error('skill resource is missing or escapes its bundle')
+      }
+    }
+  }
+}
+
+export function prepareCapabilityRelease({ packageRoot }) {
+  const root = fs.realpathSync(path.resolve(packageRoot))
+  const files = tree(root).filter(file => file.path !== RELEASE_FILE)
+  const entry = files.find(file => file.path === PACKAGE_FILE)
+  if (!entry) throw new Error('capability-package.json is missing')
+  const descriptor = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(entry.bytes))
+  validatePackage(descriptor, files)
+  const payload = { schema: 'mnstry.atelier-capability-release@v1', package: descriptor, files: fileInventory(files) }
+  const release = { ...payload, digest: objectDigest(payload) }
+  assertDocument(release, 'release')
+  return release
+}
+
+export function sealCapabilityRelease(options) {
+  const release = prepareCapabilityRelease(options)
+  const root = fs.realpathSync(path.resolve(options.packageRoot))
+  // Exclusive creation prevents a release identifier from silently changing.
+  writeNew(root, RELEASE_FILE, jsonText(release))
+  return release
+}
+
+export function verifyCapabilityRelease({ packageRoot, expectedDigest }) {
+  const root = fs.realpathSync(path.resolve(packageRoot))
+  const release = assertDocument(jsonAt(root, RELEASE_FILE), 'release')
+  const actual = prepareCapabilityRelease({ packageRoot: root })
+  if (canonical(release) !== canonical(actual)) throw new Error('release payload or manifest integrity mismatch')
+  if (expectedDigest && release.digest !== expectedDigest) throw new Error('release does not match the adopted digest')
+  return release
+}
+
+export function projectSkill({ packageRoot, release, skillId, alias, host }) {
+  if (!HOST_PROFILES[host] || !release.package.hosts.includes(host)) throw new Error('package does not support the selected host profile')
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(alias) || alias.length > 64) throw new Error('invalid skill alias')
+  const skill = release.package.skills.find(item => item.id === skillId)
+  if (!skill) throw new Error('binding selects an unknown skill')
+  const root = fs.realpathSync(packageRoot)
+  const files = tree(within(root, skill.path, { directory: true }))
+  const entry = files.find(file => file.path === 'SKILL.md')
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(entry.bytes).replaceAll('\r\n', '\n')
+  const end = text.indexOf('\n---\n', 4)
+  const header = text.slice(0, end)
+  if ((header.match(/^name:/gm) ?? []).length !== 1) throw new Error('ambiguous skill name metadata')
+  entry.bytes = Buffer.from(header.replace(/^name:.*$/m, `name: ${alias}`) + text.slice(end))
+  return { files, digest: treeDigest(files), target: `${HOST_PROFILES[host].target}/${alias}` }
+}
+
+export function inventorySkillSurfaces({ surfaces }) {
+  if (!Array.isArray(surfaces) || surfaces.length > 32) throw new Error('inventory requires at most 32 explicit surfaces')
+  unique(surfaces.map(surface => surface.id), 'surface id')
+  const entries = [], findings = []
+  for (const surface of surfaces) {
+    if (!/^[a-z][a-z0-9.-]{0,63}$/.test(surface.id)) throw new Error('invalid inventory surface id')
+    if (!['personal', 'organization', 'repository', 'nested', 'plugin', 'other'].includes(surface.scope)) throw new Error('invalid inventory scope')
+    if (!stat(surface.root)) { findings.push({ surface: surface.id, code: 'surface-missing' }); continue }
+    if (stat(surface.root).isSymbolicLink() || !stat(surface.root).isDirectory()) { findings.push({ surface: surface.id, code: 'surface-redirected-or-not-directory' }); continue }
+    const root = fs.realpathSync(surface.root)
+    const names = fs.readdirSync(root).filter(name => !name.startsWith('.')).sort()
+    if (names.length > 256) throw new Error('inventory surface ceiling exceeded')
+    for (const name of names) {
+      try {
+        const skillRoot = within(root, name, { directory: true })
+        if (!stat(skillRoot)?.isDirectory()) continue
+        const files = tree(skillRoot)
+        const entry = files.find(file => file.path === 'SKILL.md')
+        if (!entry) { findings.push({ surface: surface.id, name, code: 'no-entrypoint' }); continue }
+        const parsed = parseSkillFrontmatter(new TextDecoder('utf-8', { fatal: true }).decode(entry.bytes))
+        entries.push({ surface: surface.id, scope: surface.scope, name, declaredName: parsed.values.name ?? null, digest: treeDigest(files), ownership: 'unclaimed', hostLoaded: 'unknown' })
+      } catch { findings.push({ surface: surface.id, name, code: 'unreadable-or-unsafe-bundle' }) }
+    }
+  }
+  const collisions = entries.filter((entry, index) => entries.some((other, otherIndex) => index !== otherIndex && other.declaredName === entry.declaredName))
+    .map(entry => ({ surface: entry.surface, name: entry.name, code: 'name-overlap-requires-host-inspection' }))
+  return { schema: 'mnstry.atelier-capability-inventory@v1', entries, findings: [...findings, ...collisions], scope: 'explicit-surfaces-only', mutation: false }
+}

package/src/cli/command-failure.mjs

@@ -0,0 +1,36 @@
+// A command's own refusal prints its message. Anything that can carry host
+// detail (Node system errors, child-process failures, parser excerpts, or a
+// message naming an absolute path) is rethrown to the command executor, which
+// prints only a typed code or `[internal-error]` with Node's code.
+// Node's system errors always carry errno and syscall; child-process failures
+// carry status and stderr. Atelier's own refusals carry neither, even when
+// their code is EEXIST.
+const NODE_DETAIL_KEYS = ['errno', 'syscall', 'path', 'dest', 'status', 'signal', 'stderr', 'stdout', 'cmd']
+const HOST_ROOT = /(?:^|[\s'"(=,])(?:\/(?:Users|home|private|var|tmp|Volumes|opt|etc|root|mnt|srv|usr|Library|System|Applications)\/|[A-Za-z]:\\|\\\\|~\/)/
+// A quoted absolute path, as Node and git print them, whatever its root.
+const QUOTED_ABSOLUTE = /['"`](?:\/[^'"`\s/]+\/|[A-Za-z]:[\\/]|\\\\)/
+
+export function safeCommandMessage(error) {
+  if (!(error instanceof Error) || error instanceof SyntaxError) return null
+  if (typeof error.code === 'string' && error.code.startsWith('ERR_')) return null
+  if (NODE_DETAIL_KEYS.some(key => Object.hasOwn(error, key))) return null
+  const message = error.message
+  // Atelier's own messages never interpolate host paths; Node and git quote
+  // theirs. Unquoted text such as a schema instance path `/data/0` stays.
+  if (typeof message !== 'string' || HOST_ROOT.test(message) || QUOTED_ABSOLUTE.test(message)) return null
+  return message
+}
+
+export function reportCommandFailure(error, stream = 'stderr') {
+  const message = safeCommandMessage(error)
+  if (message === null) throw error
+  const text = JSON.stringify({ ok: false, error: message })
+  if (stream === 'stdout') console.log(text)
+  else console.error(text)
+  process.exitCode = 1
+}
+
+export function parseJsonRequest(bytes, label) {
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) }
+  catch { throw new Error(`${label} must be UTF-8 JSON`) }
+}

package/src/cli/execute-command.mjs

@@ -5,18 +5,32 @@ import { pathToFileURL } from 'node:url'
 
 const [, , requestedScript, ...args] = process.argv
 
+// Only Atelier's own typed codes (lowercase words joined by hyphens) are
+// printed verbatim. Node's system and internal errors (ENOENT, EACCES, ERR_*)
+// carry a string code too, but their messages name absolute paths and no next
+// step, so they are redacted to the code and system call alone.
+const TYPED_CODE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+const NODE_CODE = /^(?:E[A-Z0-9]+|ERR_[A-Z0-9_]+)$/
+const SYSCALL = /^[a-z_]+$/
+
+function untypedDetail(error) {
+  if (typeof error?.code !== 'string' || !NODE_CODE.test(error.code)) return ''
+  const syscall = typeof error.syscall === 'string' && SYSCALL.test(error.syscall) ? ` from ${error.syscall}` : ''
+  return ` (${error.code}${syscall})`
+}
+
 function renderError(error) {
   const debug = process.env.ATELIER_DEBUG === '1'
   if (debug) {
     console.error(error?.stack || String(error))
     return Number.isInteger(error?.exitCode) ? error.exitCode : 1
   }
-  if (typeof error?.code === 'string' && error.code) {
+  if (typeof error?.code === 'string' && TYPED_CODE.test(error.code)) {
     console.error(`[${error.code}] ${error.message}`)
     if (error.hint) console.error(`Next: ${error.hint}`)
     return Number.isInteger(error.exitCode) ? error.exitCode : 2
   }
-  console.error('[internal-error] command failed without a safe diagnostic')
+  console.error(`[internal-error] command failed without a safe diagnostic${untypedDetail(error)}`)
   console.error('Next: rerun with ATELIER_DEBUG=1 to inspect the stack locally.')
   return 1
 }