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

package/src/graph/enroll.mjs

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { PRIVATE_AUDIENCES, loadBoundaryPolicy } from '../boundary/policy.mjs'
+import { parseProjectOptions } from '../cli/project-options.mjs'
+import { AtelierDiagnosticError, commandProject } from '../project/config.mjs'
+import { VALID_AUDIENCES } from '../projection/policy.mjs'
+import { canonicalGraphOptions } from './graph.mjs'
+import { SOURCE_SIDECAR_SCHEMA, buildKnowledgeGraph, validateSourceSidecar } from './knowledge-graph.mjs'
+
+// Document enrollment writes the sidecar the census demands of every
+// non-Markdown document that has none: the smallest classification that lets
+// `atelier graph` pass, never a judgement about the document. It reads the same
+// census as the graph (scope, Git ignore rules and all), writes only where no
+// sidecar exists, and never changes a source.
+
+export const DEFAULT_ENROLLMENT_AUDIENCE = 'private'
+
+const AUDIENCE_ORDER = ['private', 'sensitive', 'staff', 'operator', 'team', 'public']
+const orderedAudiences = (audiences) => AUDIENCE_ORDER.filter((audience) => audiences.includes(audience))
+
+// The audiences a repository's boundary policy lets a node carry, by the same
+// three rules the boundary check applies to every node. Null when the policy
+// does not cover the repository, which the boundary check reports on its own.
+export function enrollableAudiences(repoPolicy) {
+  if (!repoPolicy || typeof repoPolicy !== 'object') return null
+  const allowed = Array.isArray(repoPolicy.allowedAudiences) ? repoPolicy.allowedAudiences : []
+  const forbidden = Array.isArray(repoPolicy.forbiddenAudiences) ? repoPolicy.forbiddenAudiences : []
+  return orderedAudiences(
+    allowed.filter((audience) => !forbidden.includes(audience) && !(PRIVATE_AUDIENCES.has(audience) && repoPolicy.kind !== 'private_domain')),
+  )
+}
+
+export function assertEnrollmentAudience(audience) {
+  if (typeof audience === 'string' && VALID_AUDIENCES.has(audience)) return audience
+  throw new AtelierDiagnosticError('enroll-audience-invalid', `--audience must be one of ${orderedAudiences([...VALID_AUDIENCES]).join(', ')}`, {
+    hint: `Omit --audience to enroll documents as ${DEFAULT_ENROLLMENT_AUDIENCE}.`,
+  })
+}
+
+// Refuses, before anything is written, an audience the boundary policy would
+// reject in any repository that has a document to enroll. A policy in
+// legacy-warning mode only warns about placement, and so does not refuse here.
+export function assertAudienceAllowed({ policy, repoNames, audience }) {
+  if (policy?.mode === 'legacy-warning') return
+  for (const repoName of repoNames) {
+    const repoPolicy = policy?.repos && Object.hasOwn(policy.repos, repoName) ? policy.repos[repoName] : null
+    const allowed = enrollableAudiences(repoPolicy)
+    if (!allowed || allowed.includes(audience)) continue
+    // The message names the allowed audiences itself: adopt prints only the
+    // message of a refusal, not its hint.
+    const kind = typeof repoPolicy.kind === 'string' ? `${repoPolicy.kind.replaceAll('_', ' ')} ` : ''
+    const allows = allowed.length ? `it allows ${allowed.join(', ')}` : 'it allows no audience there'
+    throw new AtelierDiagnosticError(
+      'enroll-audience-not-allowed',
+      `the boundary policy does not allow audience ${audience} in ${kind}repository ${repoName}; ${allows}`,
+      {
+        hint: allowed.length
+          ? 'Pass --audience with one of the audiences it allows.'
+          : 'Review boundary-policy.v1.json before enrolling documents in that repository.',
+      },
+    )
+  }
+}
+
+const idSegment = (value) =>
+  String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+const pathSegment = (rel) =>
+  String(rel)
+    .toLowerCase()
+    .replace(/[^a-z0-9._/-]+/g, '-')
+    .replace(/-+([./])/g, '$1')
+    .replace(/([./])-+/g, '$1')
+    .replace(/-{2,}/g, '-')
+
+const shortDigest = (value) => createHash('sha256').update(value).digest('hex').slice(0, 8)
+
+// `<repo>:asset:<path>` keeps the source's folders and file name readable in
+// the id. Two documents whose paths fold to one id (case, spaces) each get a
+// digest of their exact path, as does one whose id is already taken, so the
+// result does not depend on the order documents are found in.
+function assignIds(wanted, taken) {
+  const bases = wanted.map((item) => `${idSegment(item.repo) || 'repo'}:asset:${pathSegment(item.path)}`)
+  const counts = new Map()
+  for (const base of bases) counts.set(base, (counts.get(base) ?? 0) + 1)
+  const used = new Set(taken)
+  return wanted.map((item, index) => {
+    const base = bases[index]
+    const id = counts.get(base) > 1 || used.has(base) ? `${base}-${shortDigest(`${item.repo}/${item.path}`)}` : base
+    if (used.has(id)) throw new Error('document enrollment could not derive a unique kg.id')
+    used.add(id)
+    return id
+  })
+}
+
+function sidecarDocument(node, id, audience) {
+  return {
+    schema: SOURCE_SIDECAR_SCHEMA,
+    asset: path.posix.basename(node.path),
+    title: node.title || path.posix.basename(node.path),
+    summary: '',
+    tags: [],
+    kg: {
+      id,
+      type: node.extension,
+      domain: node.domain,
+      lifecycle: node.lifecycle,
+      status: node.status,
+      audience,
+      relations: {},
+    },
+  }
+}
+
+// What enrollment would write, and what it leaves alone. `policy` defaults to
+// the project's boundary policy; a missing or unreadable one is not consulted,
+// since the graph itself does not need it.
+export function planDocumentEnrollment(project, { audience = DEFAULT_ENROLLMENT_AUDIENCE, policy = undefined } = {}) {
+  assertEnrollmentAudience(audience)
+  const { options } = canonicalGraphOptions(project)
+  const result = buildKnowledgeGraph(options)
+  if (!result.workspaceGraph) {
+    throw new AtelierDiagnosticError('enroll-census-unavailable', 'the knowledge graph census could not run, so no document was enrolled', {
+      hint: 'Run atelier graph with the same --project path to see why, fix that, then retry.',
+    })
+  }
+  const roots = new Map(options.repoEntries.map((entry) => [entry.name, entry.path]))
+  const nodes = result.workspaceGraph.nodes
+  // Code-point order, so the report reads the same under every locale.
+  const byPath = (a, b) => (`${a.repo}/${a.path}` < `${b.repo}/${b.path}` ? -1 : 1)
+  const demanded = nodes.filter((node) => node.extension !== 'md' && !node.hasSidecar).sort(byPath)
+
+  const wanted = []
+  const skipped = []
+  for (const node of demanded) {
+    const sidecar = `${node.path}.kg.json`
+    const target = path.join(roots.get(node.repo), ...sidecar.split('/'))
+    const existing = fs.lstatSync(target, { throwIfNoEntry: false })
+    // A sidecar that exists but is not visible to the census is Git-ignored,
+    // or is a link or folder. Either way it is someone's, and stays as it is.
+    if (existing) {
+      skipped.push({ repo: node.repo, path: node.path, sidecar, reason: existing.isFile() ? 'sidecar-ignored' : 'sidecar-not-a-file' })
+      continue
+    }
+    wanted.push({ repo: node.repo, path: node.path, sidecar, target, node })
+  }
+
+  if (wanted.length) {
+    const loaded = policy === undefined ? loadBoundaryPolicy(project) : { ok: Boolean(policy), policy }
+    if (loaded.ok) assertAudienceAllowed({ policy: loaded.policy, repoNames: [...new Set(wanted.map((item) => item.repo))], audience })
+  }
+
+  const enrolling = new Set(wanted.map((item) => item.node))
+  const ids = assignIds(wanted, nodes.filter((node) => !enrolling.has(node)).map((node) => node.id))
+  const enroll = wanted.map((item, index) => {
+    const document = sidecarDocument(item.node, ids[index], audience)
+    const errors = validateSourceSidecar(document, document.asset)
+    if (errors.length) throw new Error(`document enrollment built an invalid sidecar: ${errors.join('; ')}`)
+    return { repo: item.repo, path: item.path, sidecar: item.sidecar, target: item.target, id: ids[index], document }
+  })
+  return { audience, enroll, skipped }
+}
+
+// Writes each planned sidecar with an exclusive create, so a file, link or
+// folder that appeared since the plan is never replaced or followed; it is
+// reported as skipped instead. Sources are never opened.
+export function writeDocumentEnrollment(plan) {
+  const written = []
+  const skipped = [...plan.skipped]
+  for (const item of plan.enroll) {
+    try {
+      fs.writeFileSync(item.target, `${JSON.stringify(item.document, null, 2)}\n`, { flag: 'wx' })
+      written.push(item)
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      skipped.push({ repo: item.repo, path: item.path, sidecar: item.sidecar, reason: 'sidecar-exists' })
+    }
+  }
+  return { audience: plan.audience, written, skipped }
+}
+
+const SKIP_REASONS = {
+  'sidecar-ignored': 'a sidecar exists but Git ignores it',
+  'sidecar-not-a-file': 'a link or folder has the sidecar name',
+  'sidecar-exists': 'a sidecar appeared while enrolling',
+}
+
+export function enrollmentReport({ written = [], skipped = [], audience, dryRun = false }) {
+  return {
+    ok: true,
+    command: 'enroll documents',
+    dryRun,
+    audience,
+    enrolled: written.map((item) => ({ repo: item.repo, path: item.path, sidecar: item.sidecar, id: item.id })),
+    skipped: skipped.map((item) => ({ repo: item.repo, path: item.path, sidecar: item.sidecar, reason: item.reason })),
+  }
+}
+
+function printReport(report) {
+  const count = report.enrolled.length
+  const noun = count === 1 ? 'document' : 'documents'
+  if (count === 0) console.log('No document needs a sidecar.')
+  else console.log(`${report.dryRun ? 'Would enroll' : 'Enrolled'} ${count} ${noun} with ${report.audience} sidecars:`)
+  for (const item of report.enrolled) console.log(`  ${item.repo}/${item.sidecar}`)
+  if (report.skipped.length) {
+    console.log(`Left ${report.skipped.length} unchanged; the graph still needs a sidecar for each:`)
+    for (const item of report.skipped) console.log(`  ${item.repo}/${item.path}: ${SKIP_REASONS[item.reason] ?? item.reason}`)
+  }
+  if (count && !report.dryRun) {
+    console.log('Next: review the sidecars (title, audience), then run atelier graph with the same --project path.')
+  }
+}
+
+const usage = () =>
+  new AtelierDiagnosticError('usage', 'enroll has one subcommand, documents', {
+    hint: 'Run atelier enroll documents [--audience private] [--dry-run] [--json] [--project ./atelier.project.json].',
+  })
+
+export function parseEnrollArgs(argv = []) {
+  const { remaining } = parseProjectOptions(argv)
+  const args = { subcommand: null, audience: DEFAULT_ENROLLMENT_AUDIENCE, dryRun: false, json: false }
+  for (let index = 0; index < remaining.length; index += 1) {
+    const arg = remaining[index]
+    if (arg === '--dry-run') args.dryRun = true
+    else if (arg === '--json') args.json = true
+    else if (arg === '--audience') args.audience = remaining[++index]
+    else if (arg.startsWith('--audience=')) args.audience = arg.slice('--audience='.length)
+    else if (!arg.startsWith('-') && args.subcommand === null) args.subcommand = arg
+    else throw usage()
+  }
+  if (args.subcommand !== 'documents') throw usage()
+  assertEnrollmentAudience(args.audience)
+  return args
+}
+
+export function runEnrollCommand(argv = process.argv.slice(2)) {
+  const args = parseEnrollArgs(argv)
+  const project = commandProject({ argv })
+  const plan = planDocumentEnrollment(project, { audience: args.audience })
+  const outcome = args.dryRun ? { audience: plan.audience, written: plan.enroll, skipped: plan.skipped } : writeDocumentEnrollment(plan)
+  const report = enrollmentReport({ ...outcome, dryRun: args.dryRun })
+  if (args.json) console.log(JSON.stringify(report, null, 2))
+  else printReport(report)
+}

package/src/graph/graph.mjs

@@ -19,6 +19,18 @@ export const VALID_AUDIENCES = PROJECTION_AUDIENCES
 export const VALID_RELATIONS = VALID_RELATION_TYPES
 export const parseFrontmatterYaml = parseYamlSubset
 
+// setup.include and setup.exclude scope the census. Both are path patterns
+// relative to the project config's folder, so each repository learns where its
+// root sits relative to that folder.
+function censusScope(project, repoPath) {
+  const setup = project.config?.setup
+  const include = typeof setup?.include === 'string' && setup.include.trim() ? setup.include : null
+  const exclude = typeof setup?.exclude === 'string' && setup.exclude.trim() ? setup.exclude : null
+  if (!include && !exclude) return null
+  const base = path.relative(project.configDir, repoPath).split(path.sep).join('/')
+  return { base, include, exclude }
+}
+
 function canonicalInput(project) {
   const loadedAccess = loadRepoAccess(project)
   const managed = []
@@ -31,7 +43,8 @@ function canonicalInput(project) {
       missing.push(`configured repo is missing or unreadable: ${repo.name ?? '(unnamed)'}`)
       continue
     }
-    managed.push({ name: repo.name, path: repo.path })
+    const scope = censusScope(project, repo.path)
+    managed.push({ name: repo.name, path: repo.path, ...(scope ? { censusScope: scope } : {}) })
     accessRepos[repo.name] = {
       readBoundary:
         loadedAccess.repos?.[repo.name]?.readBoundary ?? repo.readBoundary ?? loadedAccess.defaultReadBoundary ?? 'team',
@@ -211,6 +224,9 @@ export function runGraphCommand(argv = process.argv.slice(2)) {
   for (const warning of ignoredSidecarWarnings(project)) console.warn(`warning: ${warning.message}`)
   if (graph.errors.length) {
     console.error(graph.errors.join('\n'))
+    if (graph.errors.some((error) => error.includes(': non-Markdown source requires sidecar '))) {
+      console.error('Next: run atelier enroll documents with the same --project path to write private sidecars for documents that have none, review them, then rerun atelier graph.')
+    }
     process.exit(1)
   }
   if (check) {

package/src/graph/knowledge-graph.mjs

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { VALID_AUDIENCES } from '../projection/policy.mjs'
 import { generatedProjectionBasenames, generatedProjectionDirectoryBasenames } from '../project/file-class.mjs'
 import { gitIgnoreFilter } from '../project/git-ignore.mjs'
+import { matchesPathPattern, normalizeRelPath } from '../project/path-match.mjs'
 
 export const KNOWLEDGE_GRAPH_SCHEMA = 'mnstry.knowledge-graph@v1'
 export const REPO_ACCESS_SCHEMA = 'mnstry.repo-access@v1'
@@ -339,14 +340,58 @@ export function listRepos(workspaceRoot) {
     .sort()
 }
 
+// The project's census scope: `include` and `exclude` are path patterns in the
+// kit's one dialect (src/project/path-match.mjs), relative to the project
+// config's folder, read from the tracked config so every machine walks the
+// same paths. `base` is the repository root relative to that folder. The
+// returned predicate takes a repository-relative path and says whether it is
+// outside the census; `directory` lets a folder that may still hold included
+// files be walked. A path is excluded when it or a folder above it matches
+// `exclude`; with `include`, a file is in the census only when it or a folder
+// above it matches. Exclude wins. A `<file>.kg.json` sidecar belongs to its
+// source and shares the source's scope. Null when the scope restricts nothing.
+export function censusScopeFilter({ base = '', include = null, exclude = null } = {}) {
+  // A trailing slash names a folder, which a pattern without one matches too.
+  const pattern = (value) => (typeof value === 'string' && value.trim() ? normalizeRelPath(value.trim()).replace(/\/+$/, '') || null : null)
+  const includePattern = pattern(include)
+  const excludePattern = pattern(exclude)
+  if (!includePattern && !excludePattern) return null
+  const prefix = normalizeRelPath(base).replace(/\/+$/, '')
+  const lineage = (rel) => {
+    const parts = path.posix.normalize(prefix ? `${prefix}/${rel}` : rel).split('/')
+    return parts.map((_, index) => parts.slice(0, index + 1).join('/'))
+  }
+  // A folder may lead to an included file when it lies on the pattern's
+  // literal leading path, or below it. A slashless pattern matches at any
+  // depth, so every folder may.
+  const segments = includePattern?.includes('/') ? includePattern.split('/') : null
+  const globAt = segments ? segments.findIndex((part) => part.includes('*')) : -1
+  const literalLead = segments ? (globAt === -1 ? segments : segments.slice(0, globAt)) : null
+  const mayLeadToInclude = (paths) => {
+    if (!literalLead) return true
+    const parts = paths.at(-1).split('/')
+    const shared = Math.min(parts.length, literalLead.length)
+    return parts.slice(0, shared).every((part, index) => part.toLowerCase() === literalLead[index].toLowerCase())
+  }
+  return (rel, { directory = false } = {}) => {
+    const paths = lineage(!directory && rel.endsWith('.kg.json') ? rel.slice(0, -'.kg.json'.length) : rel)
+    if (excludePattern && paths.some((candidate) => matchesPathPattern(excludePattern, candidate))) return true
+    if (!includePattern || paths.some((candidate) => matchesPathPattern(includePattern, candidate))) return false
+    return !(directory && mayLeadToInclude(paths))
+  }
+}
+
 // Git-ignored paths are machine-local. Counting them makes committed graph
 // artifacts differ per machine, which turns every sync tick into a conflict.
+// `isIgnored(rel, { directory })` also carries the project's census scope when
+// the builder composes one in (censusScopeFilter); a plain Git filter ignores
+// the second argument.
 export function walkDocuments(dir, root, acc = [], isIgnored = gitIgnoreFilter(root)) {
   for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
     if (SKIP_DIRS.has(ent.name) || ent.name.startsWith('.')) continue
     const abs = path.join(dir, ent.name)
     const rel = relPath(root, abs)
-    if (isIgnored(rel)) continue
+    if (isIgnored(rel, { directory: ent.isDirectory() })) continue
     if (ent.isDirectory()) {
       walkDocuments(abs, root, acc, isIgnored)
     } else if (ent.isFile()) {
@@ -384,7 +429,7 @@ export function ignoredSourceSidecars(repoName, repoRoot, isIgnored = gitIgnoreF
       const abs = path.join(dir, ent.name)
       const rel = relPath(repoRoot, abs)
       if (ent.isDirectory()) {
-        if (!isIgnored(rel)) visit(abs)
+        if (!isIgnored(rel, { directory: true })) visit(abs)
         continue
       }
       if (!ent.isFile() || !ent.name.endsWith('.kg.json') || !isIgnored(rel)) continue
@@ -402,7 +447,7 @@ export function walkSidecars(dir, root, acc = [], isIgnored = gitIgnoreFilter(ro
   for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
     if (SKIP_DIRS.has(ent.name) || ent.name.startsWith('.')) continue
     const abs = path.join(dir, ent.name)
-    if (isIgnored(relPath(root, abs))) continue
+    if (isIgnored(relPath(root, abs), { directory: ent.isDirectory() })) continue
     if (ent.isDirectory()) {
       walkSidecars(abs, root, acc, isIgnored)
     } else if (ent.isFile() && ent.name.endsWith('.kg.json')) {
@@ -898,7 +943,7 @@ const isMarkdownPath = (rel) => rel.toLowerCase().endsWith('.md')
 // a path is tested, not the path alone.
 function ignoredAtAnyDepth(isIgnored, rel) {
   const parts = rel.split('/')
-  return parts.some((_, index) => isIgnored(parts.slice(0, index + 1).join('/')))
+  return parts.some((_, index) => isIgnored(parts.slice(0, index + 1).join('/'), { directory: index < parts.length - 1 }))
 }
 
 // True only for a regular file whose real location is exactly `rel` under the
@@ -979,7 +1024,7 @@ export function resolveWorkspaceLinks({ repos = [], isLinkTargetEligible = () =>
             if (ent.name === '.git') continue
             const abs = path.join(dir, ent.name)
             const rel = relPath(owner.root, abs)
-            if (isIgnored(rel)) continue
+            if (isIgnored(rel, { directory: ent.isDirectory() })) continue
             // A nested enrolled repository owns its own files.
             if (ent.isDirectory()) {
               if (!roots.has(abs)) visit(abs)
@@ -1362,7 +1407,9 @@ export function buildKnowledgeGraph({
   const resolvedWorkspaceRoot = path.resolve(workspaceRoot)
   const external = new Set(externalRepos)
   const discoveredEntries = repoEntries
-    ? repoEntries.map((entry) => ({ name: entry.name, path: path.resolve(entry.path) })).sort((a, b) => String(a.name).localeCompare(String(b.name)))
+    ? repoEntries
+        .map((entry) => ({ name: entry.name, path: path.resolve(entry.path), ...(entry.censusScope ? { censusScope: entry.censusScope } : {}) }))
+        .sort((a, b) => String(a.name).localeCompare(String(b.name)))
     : (repoRoots ? repoRoots.map((repoRoot) => path.resolve(repoRoot)) : listRepos(resolvedWorkspaceRoot))
         .sort()
         .map((repoRoot) => ({ name: path.basename(repoRoot), path: repoRoot }))
@@ -1398,8 +1445,11 @@ export function buildKnowledgeGraph({
   for (const entry of roots) {
     const repoRoot = entry.path
     const repoName = entry.name
-    // One batched ignore lookup per repo, shared by every walk below.
-    const isIgnored = gitIgnoreFilter(repoRoot)
+    // One batched ignore lookup per repo, shared by every walk below. A path
+    // outside the project's census scope is treated exactly as an ignored one.
+    const gitIgnored = gitIgnoreFilter(repoRoot)
+    const outOfScope = censusScopeFilter(entry.censusScope ?? {})
+    const isIgnored = outOfScope ? (rel, info) => gitIgnored(rel) || outOfScope(rel, info) : gitIgnored
     const files = walkDocuments(repoRoot, repoRoot, [], isIgnored)
     workspaceOrphanSidecars.push(...activeOrphanSidecars(repoName, repoRoot, files, isIgnored))
     workspaceIgnoredSidecars.push(...ignoredSourceSidecars(repoName, repoRoot, isIgnored))

package/src/harnesses/contracts.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { objectDigest, digest } from '../capabilities/files.mjs'
+export const HARNESS_LIMITS = Object.freeze({ records: 256, bytes: 8 * 1024 * 1024, dependencyVerifications: 256, dependencyDepth: 12 })
+export const harnessDigest = objectDigest
+export const contentDigest = digest
+export const harnessRef = record => ({ id: record.id, digest: objectDigest(record) })
+export const EMPTY_HARNESS_HEAD = objectDigest([])
+const ajv = new Ajv({ allErrors: true, strict: true }); addFormats(ajv)
+const schemas = new Map(['harness', 'knowledge', 'build'].map(name => [name, JSON.parse(fs.readFileSync(new URL(`../../contracts/atelier-${name}.v1.schema.json`, import.meta.url)))]))
+const validators = new Map()
+export function validateHarnessDocument(value, profile, shape = 'record') {
+  const schema = schemas.get(profile), key = `${profile}/${shape}`
+  if (!schema || !Object.hasOwn(schema.$defs, shape)) return ['unknown harness profile or shape']
+  if (!validators.has(key)) validators.set(key, ajv.compile({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${shape}` }))
+  const validate = validators.get(key)
+  return validate(value) ? [] : validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+}
+export function assertHarness(value, profile, shape = 'record') {
+  const errors = validateHarnessDocument(value, profile, shape)
+  if (errors.length) throw new Error(`invalid ${profile} ${shape}: ${errors.slice(0, 5).join('; ')}`)
+  return value
+}
+// A private container may receive a public source. An export that includes that
+// container's metadata must retain the more restrictive combined audience.
+export function restrictiveAudience(...values) {
+  if (!values.length || values.some(v => !['public', 'team', 'operator', 'staff', 'private', 'sensitive'].includes(v))) throw new Error('unknown audience')
+  const restricted = [...new Set(values.filter(v => v !== 'public'))]
+  if (restricted.includes('sensitive')) return 'sensitive'
+  if (restricted.includes('private') || restricted.length > 1) return 'private'
+  return restricted[0] ?? 'public'
+}
+export function assertAudience(receiver, source) {
+  if (restrictiveAudience(receiver, source) !== receiver) throw new Error('audience exceeds receiving scope')
+}
+export function assertHandoff(value) {
+  assertHarness(value, 'harness', 'handoff')
+  if (contentDigest(value.payload) !== value.payloadDigest) throw new Error('handoff payload digest mismatch')
+  return value
+}

package/src/harnesses/exchange.mjs

@@ -0,0 +1,154 @@
+import { inspectInquiry } from '../inquiry/index.mjs'
+import { inspectKnowledge } from '../knowledge/ledger.mjs'
+import { inspectBuild } from '../build/ledger.mjs'
+import { assertHandoff, contentDigest, harnessDigest, harnessRef, restrictiveAudience, HARNESS_LIMITS } from './contracts.mjs'
+import { canonical } from '../capabilities/files.mjs'
+import { createHash } from 'node:crypto'
+
+export function inspectHarness(profile, records) {
+  if (profile === 'inquiry') return inspectInquiry(records)
+  if (profile === 'knowledge') return inspectKnowledge(records)
+  if (profile === 'build') return inspectBuild(records)
+  throw new Error('unknown harness profile')
+}
+function context(dependencySnapshots = [], verificationLimit = HARNESS_LIMITS.dependencyVerifications) {
+  if (!Array.isArray(dependencySnapshots) || dependencySnapshots.length > 64) throw new Error('dependency snapshot ceiling exceeded')
+  if (!Number.isSafeInteger(verificationLimit) || verificationLimit < 1 || verificationLimit > HARNESS_LIMITS.dependencyVerifications) throw new Error('invalid dependency verification limit')
+  return { snapshots: dependencySnapshots, inspections: new Map(), verified: new Map(), verificationLimit, verificationCalls: 0, historyReplays: 0, exhausted: false }
+}
+function inspect(profile, records, ctx) {
+  if (!ctx.inspections.has(profile)) ctx.inspections.set(profile, new Map())
+  const cache = ctx.inspections.get(profile)
+  if (!cache.has(records)) { cache.set(records, inspectHarness(profile, records)); ctx.historyReplays++ }
+  return cache.get(records)
+}
+const work = ctx => ({ verificationCalls: ctx.verificationCalls, historyReplays: ctx.historyReplays, verificationLimit: ctx.verificationLimit, exhausted: ctx.exhausted })
+const bounded = depth => { if (depth > HARNESS_LIMITS.dependencyDepth) throw new Error('harness dependency depth exceeded') }
+function artifact(profile, records, subjectId, ctx, depth) {
+  bounded(depth)
+  const state = inspect(profile, records, ctx), subject = records.find(r => r.id === subjectId)
+  if (!subject || state.reconsider.some(r => r.id === subjectId)) throw new Error('handoff subject is missing or requires reconsideration')
+  let audience, context
+  if (profile === 'knowledge') {
+    if (subject.kind !== 'contribution' || !state.accepted.includes(subject.id)) throw new Error('knowledge handoff requires an accepted contribution')
+    if (knowledgeFreshness(records, ctx, depth, [subject.id]).reconsider.some(r => r.id === subject.id)) throw new Error('knowledge import requires current source snapshots')
+    const review = records.findLast(r => r.kind === 'review' && r.data.target.id === subject.id)
+    context = [state.domain, review, ...review.data.evaluations.map(pin => records.find(r => r.id === pin.id))]
+    audience = restrictiveAudience(subject.data.audience, state.domain.data.audience)
+  } else if (profile === 'inquiry') {
+    if (subject.kind !== 'decision' || subject.data.disposition !== 'accepted') throw new Error('inquiry handoff requires an accepted decision')
+    const assessment = records.find(r => r.id === subject.data.assessment.id)
+    context = [records.find(r => r.id === assessment.data.hypothesis.id), assessment]
+    audience = state.campaign.data.audience
+  } else {
+    if (subject.kind !== 'candidate' || state.candidate?.id !== subject.id || !readiness(records, ctx, depth).readyReported) throw new Error('build handoff requires current accepted candidate and fresh dependencies')
+    context = [state.establishment, state.decision, ...state.gates]
+    audience = state.establishment.data.audience
+  }
+  return { state, audience, subject, payload: JSON.stringify({ subject, context, assurance: 'caller-reported; acceptance-is-not-truth-or-authority' }) }
+}
+function create({ profile, repository, records, subjectId, target }, ctx, depth) {
+  const { state, audience, subject, payload } = artifact(profile, records, subjectId, ctx, depth)
+  if (profile !== 'inquiry' && state.establishment.data.repository !== repository) throw new Error('handoff repository differs from establishment')
+  const repositoryBinding = profile === 'inquiry' ? 'caller-declared' : 'establishment-record'
+  return assertHandoff({ schema: 'atelier-harness-handoff@v1', source: { repository, repositoryBinding, profile, run: records[0].id, historyDigest: state.head, subject: harnessRef(subject) }, target, audience, payload, payloadDigest: contentDigest(payload), assurance: 'caller-reported', authority: 'none' })
+}
+function verify({ handoff, records }, ctx, depth) {
+  bounded(depth)
+  if (ctx.verificationCalls >= ctx.verificationLimit) { ctx.exhausted = true; throw new Error('harness dependency verification budget exhausted') }
+  ctx.verificationCalls++
+  assertHandoff(handoff)
+  if (!ctx.verified.has(records)) ctx.verified.set(records, new Map())
+  const cache = ctx.verified.get(records), key = harnessDigest(handoff), prior = cache.get(key)
+  if (prior?.active) throw new Error('harness dependency cycle detected')
+  if (prior?.result) return prior.result
+  cache.set(key, { active: true })
+  try {
+    inspect(handoff.source.profile, records, ctx)
+    const hash = createHash('sha256').update('[')
+    let extendsIssuedHistory = false
+    for (let i = 0; i < records.length; i++) {
+      if (i) hash.update(',')
+      hash.update(canonical(records[i]))
+      if (`sha256:${hash.copy().update(']').digest('hex')}` === handoff.source.historyDigest) extendsIssuedHistory = true
+    }
+    if (!extendsIssuedHistory) throw new Error('handoff source history changed or diverged')
+    const current = create({ ...handoff.source, records, subjectId: handoff.source.subject.id, target: handoff.target }, ctx, depth)
+    const observedHead = current.source.historyDigest
+    current.source.historyDigest = handoff.source.historyDigest
+    if (harnessDigest(current) !== harnessDigest(handoff)) throw new Error('handoff is stale or differs from its source history')
+    const result = { current: true, historyDigest: observedHead, issuedHistoryDigest: handoff.source.historyDigest, sourceRepositoryBinding: current.source.repositoryBinding, sourceAuthenticity: 'unverified', authority: 'none' }
+    cache.set(key, { result })
+    return result
+  } finally {
+    if (cache.get(key)?.active) cache.delete(key)
+  }
+}
+function matching(h, snapshots) {
+  return snapshots.filter(s => s.repository === h.source.repository && s.profile === h.source.profile && s.records?.[0]?.id === h.source.run)
+}
+function knowledgeFreshness(records, ctx, depth, subjects = null) {
+  bounded(depth)
+  const state = inspect('knowledge', records, ctx), stale = new Map(state.reconsider.map(r => [r.id, r.reasons]))
+  const needed = subjects ? new Set(subjects) : null
+  if (needed) for (const record of [...records].reverse()) if (needed.has(record.id) && record.kind === 'contribution') for (const item of record.data.basedOn) needed.add(item.contribution.id)
+  for (const record of records) {
+    if (record.kind !== 'contribution' || record.data.origin.method !== 'exchange' || (needed && !needed.has(record.id))) continue
+    const h = record.data.origin.handoff, snapshots = matching(h, ctx.snapshots)
+    let reason
+    if (snapshots.length !== 1) reason = 'import-source-missing-or-ambiguous'
+    else try { verify({ handoff: h, records: snapshots[0].records }, ctx, depth + 1) } catch { reason = ctx.exhausted ? 'import-source-verification-budget-exhausted' : 'import-source-requires-reconsideration' }
+    if (reason) stale.set(record.id, [...(stale.get(record.id) ?? []), reason])
+  }
+  // References always point backwards, so one history-order pass propagates
+  // changes discovered in external inputs through local meaning and activation.
+  for (const record of records) {
+    const d = record.data
+    const refs = record.kind === 'contribution' ? [d.domain, ...d.basedOn.map(e => e.contribution)]
+      : record.kind === 'evaluation' ? [d.contribution]
+      : record.kind === 'relation' ? [d.domain, d.subject, d.object]
+      : record.kind === 'review' ? [d.target, ...d.evaluations]
+      : record.kind === 'activation' ? d.reviews : []
+    const reasons = refs.flatMap(pin => stale.get(pin.id) ?? [])
+    if (reasons.length) stale.set(record.id, [...new Set([...(stale.get(record.id) ?? []), ...reasons])])
+  }
+  return { historyDigest: state.head, reconsider: [...stale].map(([id, reasons]) => ({ id, reasons })), freshness: 'relative-to-explicit-snapshots', canonicalMutation: false }
+}
+function readiness(records, ctx, depth) {
+  bounded(depth)
+  const state = inspect('build', records, ctx), blockers = []
+  if (!state.candidate) blockers.push('candidate-missing')
+  if (!state.reportedAccepted) blockers.push('current-accepted-decision-missing')
+  for (const [id, a] of Object.entries(state.attempts)) if (a.candidate === state.candidate?.id && !['completed', 'failed', 'cancelled'].includes(a.state)) blockers.push(`attempt-unsettled:${id}`)
+  for (const dependency of state.establishment?.data.dependencies ?? []) {
+    const h = dependency.handoff
+    const snapshots = matching(h, ctx.snapshots)
+    if (snapshots.length !== 1) { blockers.push(`dependency-missing-or-ambiguous:${dependency.id}`); continue }
+    try { verify({ handoff: h, records: snapshots[0].records }, ctx, depth + 1) } catch { blockers.push(`${ctx.exhausted ? 'dependency-verification-budget-exhausted' : 'dependency-requires-reconsideration'}:${dependency.id}`) }
+  }
+  return { candidate: state.candidate, readyReported: blockers.length === 0, blockers, historyDigest: state.head,
+    dependencyFreshness: 'relative-to-explicit-snapshots; no-live-observation', authenticatedAcceptance: false, executionAuthorized: false }
+}
+export function createHarnessHandoff(options) { return create(options, context(options.dependencySnapshots, options.verificationLimit), 0) }
+export function verifyHarnessHandoff(options) {
+  const ctx = context(options.dependencySnapshots, options.verificationLimit)
+  return { ...verify(options, ctx, 0), dependencyWork: work(ctx) }
+}
+export function buildReadiness(records, { dependencySnapshots, verificationLimit } = {}) {
+  const ctx = context(dependencySnapshots, verificationLimit)
+  return { ...readiness(records, ctx, 0), dependencyWork: work(ctx) }
+}
+export function reconcileKnowledge(records, { dependencySnapshots, verificationLimit } = {}) {
+  const ctx = context(dependencySnapshots, verificationLimit)
+  return { ...knowledgeFreshness(records, ctx, 0), dependencyWork: work(ctx) }
+}
+
+// A read-only projection that a Fabric adapter or another coordinator can read.
+// It imports no private registry, creates no tasks and grants no dispatch power.
+export function buildCoordinationProposal(records, options = {}) {
+  const state = inspectBuild(records), readiness = buildReadiness(records, options)
+  return { schema: 'atelier-build-coordination-proposal@v1', outcome: state.establishment?.data.purpose ?? null,
+    owner: state.establishment?.data.owner ?? null, candidate: state.candidate?.data ?? null,
+    dependencies: state.establishment?.data.dependencies ?? [], gates: state.gates.map(r => ({ id: r.data.gate, status: r.data.status, evidence: r.data.evidence, record: harnessRef(r) })),
+    ...readiness, reconsider: state.reconsider, acceptedByCoordinator: false }
+}

package/src/harnesses/feedback.mjs

@@ -0,0 +1,16 @@
+import { assertDocument } from '../capabilities/package.mjs'
+import { harnessRef } from './contracts.mjs'
+import { inspectHarness } from './exchange.mjs'
+export function prepareHarnessFeedback({ profile, records, subjectId, id, outcome, cause, evidenceDigest, at, by }) {
+  const state = inspectHarness(profile, records), subject = records.find(r => r.id === subjectId)
+  if (!subject) throw new Error('feedback subject missing')
+  const atSubject = inspectHarness(profile, records.slice(0, records.indexOf(subject) + 1))
+  const binding = (atSubject.domain ?? atSubject.establishment ?? atSubject.campaign)?.data.binding
+  if (!binding) throw new Error('harness establishment has no skill binding')
+  if (!['skill', 'host', 'tool', 'configuration', 'context', 'provider', 'unknown'].includes(cause)) throw new Error('unknown feedback cause')
+  const event = { schema: 'mnstry.atelier-capability-event@v1', id, kind: 'feedback', ...binding, observer: by, outcome,
+    cause: ['context', 'provider'].includes(cause) ? 'unknown' : cause, evidenceDigest, at }
+  assertDocument(event, 'event')
+  return { event, subject: harnessRef(subject), historyDigest: state.head, reportedCause: cause,
+    causeMapping: event.cause === cause ? 'exact' : 'unsupported-steward-cause-preserved-in-wrapper', recorded: false, authority: 'none' }
+}