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

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

@@ -5,9 +5,10 @@ import { VALID_AUDIENCES as PROJECTION_AUDIENCES } from '../projection/policy.mj
 import {
   REPO_ACCESS_SCHEMA,
   VALID_RELATION_TYPES,
-  buildKnowledgeGraph,
+  buildKnowledgeGraphSteps,
   createGraphFileCache,
   parseYamlSubset,
+  runGraphSteps,
 } from './knowledge-graph.mjs'
 
 export { createGraphFileCache }
@@ -19,6 +20,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 +44,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',
@@ -103,11 +117,12 @@ function externalRepos(project) {
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
-function canonicalBuild(project, overrides = {}) {
+function* canonicalBuildSteps(project, overrides = {}) {
   const input = canonicalInput(project)
-  const result = buildKnowledgeGraph({ ...input.options, ...overrides })
+  const result = yield* buildKnowledgeGraphSteps({ ...input.options, ...overrides })
   return { input, result }
 }
+const canonicalBuild = (project, overrides = {}) => runGraphSteps(canonicalBuildSteps(project, overrides))
 
 // The supported project-to-options seam: the exact buildKnowledgeGraph options
 // every graph consumer derives from a loaded project, plus the configured
@@ -131,8 +146,14 @@ const canonicalEdgeId = (edge) => JSON.stringify([edge.source, edge.type, edge.t
 // bytes did not change; the result is the same as without it. `observedDigest`
 // (see createGraphFileCache) lets a caller that observes sources by digest
 // spare the read of a source it knows unchanged.
-export function buildCanonicalGraph(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
-  const { input, result } = canonicalBuild(project, {
+// buildCanonicalGraphSteps is the same build as steps (see buildKnowledgeGraphSteps), for a caller that waits between
+// them; buildCanonicalGraph runs them through.
+export function buildCanonicalGraph(project, options = {}) {
+  return runGraphSteps(buildCanonicalGraphSteps(project, options))
+}
+
+export function* buildCanonicalGraphSteps(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
+  const { input, result } = yield* canonicalBuildSteps(project, {
     ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}),
     ...(isAssetEligible ? { isAssetEligible } : {}),
     ...(fileCache ? { fileCache } : {}),
@@ -211,6 +232,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)
@@ -1342,7 +1387,24 @@ function markdownCensus({ repoName, repoRoot, coverage, file, accessConfig, cach
   return { node: structuredClone(entry.node), scan: structuredClone(entry.scan), reused: entry === cached, read }
 }
 
-export function buildKnowledgeGraph({
+// Runs the steps of a graph build through, with no wait, and answers what the build answers.
+export function runGraphSteps(steps) {
+  for (;;) {
+    const step = steps.next()
+    if (step.done) return step.value
+  }
+}
+
+// The knowledge graph of a workspace, in one stretch. Every caller but the maintenance engine's tick builds it this way.
+export function buildKnowledgeGraph(options) {
+  return runGraphSteps(buildKnowledgeGraphSteps(options))
+}
+
+// The same build as steps: one after each Markdown source of the census (its read, hash and parse, or its reuse from
+// the file cache), named 'graph-census'. A caller that gives the event loop a turn between steps (the maintenance
+// engine) keeps a large census from holding it; walking the directories, resolving links and assembling the graph
+// are not split. The answer is the one buildKnowledgeGraph gives.
+export function* buildKnowledgeGraphSteps({
   workspaceRoot,
   repoAccessConfig,
   repoRoots = null,
@@ -1362,7 +1424,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 +1462,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))
@@ -1416,6 +1483,7 @@ export function buildKnowledgeGraph({
         scanned.set(node, entry.scan)
         reuse[entry.reused ? 'reused' : 'derived'] += 1
         if (entry.read) reuse.read += 1
+        yield 'graph-census'
       } else {
         node = nodeForFile(repoName, repoRoot, coverage, file, accessConfig)
       }

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
+}