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

package/src/judgment/practice.mjs

@@ -0,0 +1,144 @@
+import { EVIDENCE_LIMITS, evidenceJson } from '../evidence-navigation/contracts.mjs'
+import { validateDecisionRequest } from '../decisions/contracts.mjs'
+import { contentDigest, harnessRef, validateHarnessDocument } from '../harnesses/contracts.mjs'
+import { inspectKnowledge } from '../knowledge/ledger.mjs'
+
+// Internal composition format. No schema, package export, CLI or separate store.
+export const DECISION_PRACTICE_FORMAT = 'atelier.decision-practice/v0'
+const flags = { executionAuthorized: false, authorityTransferred: false, semanticTruthVerified: false }
+const refusal = reason => ({ status: 'refused', reason, ...flags })
+const inputReason = (error, fallback) => Object.getOwnPropertyDescriptor(error ?? {}, 'message')?.value === 'evidence value exceeds bounds' ? 'practice-input-exceeds-bounds' : fallback
+const id = value => typeof value === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(value)
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 4000
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const closed = (value, keys) => object(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key))
+const ids = value => Array.isArray(value) && value.length > 0 && value.length <= 16 && value.every(id) && new Set(value).size === value.length
+
+// The shared copier reports per-string/NUL exclusions as non-JSON. Only a
+// bounded, descriptor-plain JSON graph can reclassify that as a profile limit.
+// Continue past strings to avoid hiding an accessor, cycle or prototype before
+// the bound. A bound reached first retains the shared copier's refusal order.
+function hasExcludedJsonString(value) {
+  const active = new Set()
+  let remaining = EVIDENCE_LIMITS.members, excluded = false
+  function inspect(item, depth) {
+    if (--remaining < 0 || depth > EVIDENCE_LIMITS.depth) return 'bounded'
+    if (item === null || typeof item === 'boolean') return 'plain'
+    if (typeof item === 'string') {
+      excluded ||= item.length > EVIDENCE_LIMITS.bytes || item.includes('\u0000')
+      return 'plain'
+    }
+    if (typeof item === 'number') return Number.isFinite(item) ? 'plain' : 'malformed'
+    if (typeof item !== 'object' || active.has(item)) return 'malformed'
+    const array = Array.isArray(item), prototype = Object.getPrototypeOf(item)
+    if (array ? prototype !== Array.prototype : ![Object.prototype, null].includes(prototype)) return 'malformed'
+    active.add(item)
+    let count = 0, dense = true
+    for (const key of Reflect.ownKeys(item)) {
+      if (array && key === 'length') continue
+      const descriptor = Object.getOwnPropertyDescriptor(item, key)
+      if (typeof key !== 'string' || !descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) return 'malformed'
+      const status = inspect(descriptor.value, depth + 1)
+      if (status !== 'plain') return status
+      if (array && key !== String(count)) dense = false
+      count++
+    }
+    active.delete(item)
+    return (!array || (dense && count === Object.getOwnPropertyDescriptor(item, 'length')?.value)) ? 'plain' : 'malformed'
+  }
+  const status = inspect(value, 0)
+  return status === 'bounded' || (status === 'plain' && excluded)
+}
+
+// Internal helpers shared only by the two allocated composition modules.
+export function decisionPracticeJson(input) {
+  try { return evidenceJson(input) } catch (error) {
+    if (Object.getOwnPropertyDescriptor(error ?? {}, 'message')?.value === 'evidence value must be JSON' && hasExcludedJsonString(input)) throw new Error('evidence value exceeds bounds')
+    throw error
+  }
+}
+
+export function decisionPracticeDraftValid(data) {
+  // Fixed envelope is for existing contribution shape validation only. It is
+  // never returned, appended, or evidence of a native actor/review/activation.
+  return validateHarnessDocument({ schema: 'atelier-knowledge-record@v1', id: 'decision-practice-draft',
+    run: 'decision-practice-check', at: '2000-01-01T00:00:00Z', by: 'validation-only', kind: 'contribution', data }, 'knowledge', 'contribution').length === 0
+}
+
+function inspect(value) {
+  const reasons = []
+  if (!closed(value, ['format', 'id', 'revision', 'purpose', 'applicability', 'rightsBasis', 'evidenceRoles', 'prerequisites', 'rubric', 'limits', 'allowedProposals', 'outcomeMap'])) return ['invalid-definition']
+  if (value.format !== DECISION_PRACTICE_FORMAT || !id(value.id) || !id(value.revision)) reasons.push('invalid-definition-identity')
+  if (![value.purpose, value.applicability, value.rightsBasis].every(text)) reasons.push('missing-purpose-applicability-or-rights')
+  if (!ids(value.evidenceRoles) || !ids(value.prerequisites)) reasons.push('invalid-evidence-roles-or-prerequisites')
+  if (!validateDecisionRequest(value.rubric).ok) reasons.push('invalid-rubric-request')
+  const question = value.rubric?.questions?.[value.outcomeMap?.question]
+  if (!closed(value.outcomeMap, ['question', 'choices']) || question?.type !== 'choice' ||
+      !closed(value.outcomeMap.choices, Object.keys(question?.criteria ?? {})) ||
+      !Object.values(value.outcomeMap.choices).every(outcome => ['proceed', 'stop', 'escalate'].includes(outcome)) ||
+      !Object.values(value.outcomeMap.choices).includes('proceed')) reasons.push('invalid-outcome-map')
+  if (!closed(value.limits, ['stages', 'evidence', 'assessments', 'proposals']) ||
+      !Object.values(value.limits).every(count => Number.isSafeInteger(count) && count >= 1 && count <= 256) ||
+      value.limits.evidence < value.evidenceRoles.length) reasons.push('invalid-budget')
+  if (!Array.isArray(value.allowedProposals) || value.allowedProposals.length !== 1 || value.allowedProposals[0] !== 'reconsideration') reasons.push('unsupported-proposal-type')
+  return reasons
+}
+
+/** Pure shape validation; purpose and rights text are declarations, not proof. */
+export function validateDecisionPractice(input) {
+  try {
+    const reasons = inspect(decisionPracticeJson(input))
+    return { valid: reasons.length === 0, reasons }
+  } catch (error) { return { valid: false, reasons: [inputReason(error, 'invalid-definition')] } }
+}
+
+/** Prepare an ordinary Knowledge contribution draft; never append or adopt it. */
+export function prepareDecisionPracticeContribution(input) {
+  try {
+    const value = decisionPracticeJson(input)
+    if (!closed(value, ['records', 'definition', 'title', 'term']) || !text(value.title) || !id(value.term) || inspect(value.definition).length) return refusal('invalid-definition')
+    let domain
+    try { domain = inspectKnowledge(value.records).domain } catch { return refusal('invalid-definition-history') }
+    if (!domain || !domain.data.vocabulary.types.some(term => term.id === value.term)) return refusal('unknown-domain-or-term')
+    const body = JSON.stringify(value.definition, null, 2)
+    const data = { domain: harnessRef(domain), category: 'decision-rationale', title: value.title, term: value.term,
+      body, audience: domain.data.audience, scope: domain.data.scope,
+      origin: { method: 'captured', locator: `decision-practice:${value.definition.id}`, contentDigest: contentDigest(body), rightsBasis: value.definition.rightsBasis }, basedOn: [] }
+    if (!decisionPracticeDraftValid(data)) return refusal('practice-output-exceeds-bounds')
+    // The adopted body and full rubric both travel in an operating instance.
+    // Bound that core with the supplied history and reserve 8 KiB for additional
+    // adoption/instance metadata. This is a size check, never a native record.
+    try {
+      const core = decisionPracticeJson({ records: [...value.records, { data }], instance: { request: value.definition.rubric } })
+      if (new TextEncoder().encode(JSON.stringify(core)).byteLength > EVIDENCE_LIMITS.bytes - 8192) return refusal('practice-output-exceeds-bounds')
+    } catch { return refusal('practice-output-exceeds-bounds') }
+    return { status: 'prepared', data, semanticAcceptance: 'pending', ...flags }
+  } catch (error) { return refusal(inputReason(error, 'invalid-definition')) }
+}
+
+/** Resolve exact reviewed/current activation from the caller's Knowledge history. */
+export function readAdoptedDecisionPractice(input) {
+  try {
+    const value = decisionPracticeJson(input)
+    if (!closed(value, ['records', 'definitionRef']) || !closed(value.definitionRef, ['id', 'digest'])) return refusal('invalid-definition-reference')
+    const state = inspectKnowledge(value.records)
+    const contribution = state.records.find(record => record.id === value.definitionRef.id)
+    if (!contribution || contribution.kind !== 'contribution') return refusal('unadopted-definition')
+    if (harnessRef(contribution).digest !== value.definitionRef.digest) return refusal('changed-definition')
+    if (!state.accepted.includes(contribution.id)) return refusal('unadopted-definition')
+    const stale = new Set(state.reconsider.map(item => item.id))
+    const activation = state.records.findLast(record => record.kind === 'activation' && !stale.has(record.id) && record.data.reviews.some(pin => {
+      const review = state.records.find(item => item.id === pin.id)
+      return review?.data.target.id === contribution.id
+    }))
+    if (!activation) return refusal('unadopted-definition')
+    let definition
+    try {
+      definition = decisionPracticeJson(JSON.parse(contribution.data.body))
+      if (inspect(definition).length || contribution.data.body !== JSON.stringify(definition, null, 2) ||
+          contribution.data.category !== 'decision-rationale' || contribution.data.origin.method !== 'captured' ||
+          contribution.data.origin.locator !== `decision-practice:${definition.id}`) return refusal('invalid-definition')
+    } catch (error) { return refusal(inputReason(error, 'invalid-definition')) }
+    return { status: 'resolved', definition, definitionRef: harnessRef(contribution), activationRef: harnessRef(activation), historyDigest: state.head, ...flags }
+  } catch (error) { return refusal(inputReason(error, 'invalid-definition-history')) }
+}

package/src/knowledge/context.mjs

@@ -0,0 +1,217 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+import { contextEligible, digest } from './plan.mjs'
+
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0
+const encode = value => `${JSON.stringify(value)}\n`
+const bytes = value => Buffer.byteLength(encode(value))
+const stop = new Set('what which when where would should could does have with from that this there their about into for the and are can how why'.split(' '))
+const terms = text => [...new Set(text.toLowerCase().match(/[\p{L}\p{N}]{3,}/gu) ?? [])].filter(t => !stop.has(t))
+const omissionReasons = new Map([
+  ['source-over-budget', 'source-over-budget'],
+  ['source-changed-since-census', 'changed-since-census'],
+  ['source-redirected', 'redirected'],
+  ['source-outside-repository', 'outside-repository'],
+  ['source-path-invalid', 'invalid-path'],
+  ['unsupported-source', 'unsupported-source'],
+])
+const omissionReason = error => error?.code === 'ERR_ENCODING_INVALID_ENCODED_DATA' ? 'decode'
+  : ['ELOOP', 'ELEAFCHANGED'].includes(error?.code) ? 'redirected'
+  : omissionReasons.get(error?.message) ?? 'unreadable'
+
+// Local operator context, never a recipient projection or an authorization API.
+// Read only enrolled Markdown records, binding text to the current canonical census.
+function sourceText(project, node, cache, maxBytes) {
+  const repo = project.repos.find(r => r.name === node.repo && !r.external)
+  if (!repo || node.extension !== 'md') throw new Error('unsupported-source')
+  const root = fs.realpathSync(repo.path)
+  const relative = node.path.split('/')
+  if (path.isAbsolute(node.path) || relative.some(x => !x || x === '..' || x === '.')) throw new Error('source-path-invalid')
+  let file = root
+  for (const part of relative) {
+    file = path.join(file, part)
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('source-redirected')
+  }
+  const real = fs.realpathSync(file)
+  const within = path.relative(root, real)
+  if (within.startsWith(`..${path.sep}`) || within === '..' || path.isAbsolute(within)) throw new Error('source-outside-repository')
+  const fd = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(fd).size > maxBytes) throw new Error('source-over-budget')
+    const buffer = Buffer.alloc(maxBytes + 1)
+    let count = 0
+    while (count < buffer.length) {
+      const read = fs.readSync(fd, buffer, count, buffer.length - count, null)
+      if (!read) break
+      count += read
+    }
+    if (count > maxBytes) throw new Error('source-over-budget')
+    const content = buffer.subarray(0, count)
+    const sha256 = digest(content)
+    if (cache.files.get(`${node.repo}\u0000${node.path}`)?.digest !== sha256) throw new Error('source-changed-since-census')
+    return { text: new TextDecoder('utf-8', { fatal: true }).decode(content), sha256, sourceBytes: count }
+  } finally { fs.closeSync(fd) }
+}
+
+export function createKnowledgeContext({ project, plan, sha256: planSha256, graph, cache, question, mode = 'graph', maxBytes = plan.budget.maxContextBytes }) {
+  if (!graph.ok) throw new Error('knowledge context requires a valid current graph')
+  if (!/^[a-f0-9]{64}$/.test(planSha256 ?? '')) throw new Error('knowledge context requires the raw plan SHA-256 from readKnowledgePlan')
+  if (!['graph', 'lexical'].includes(mode)) throw new Error('unknown retrieval mode')
+  if (typeof question !== 'string' || !question.trim() || question.length > 1000) throw new Error('question must contain 1 to 1000 characters')
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 8192 || maxBytes > plan.budget.maxContextBytes) throw new Error('max-bytes must be between 8192 and the plan budget')
+  const query = terms(question)
+  const eligible = graph.nodes.filter(contextEligible)
+  const eligibleById = new Map(eligible.map(n => [n.id, n]))
+  const ranked = eligible.map(node => {
+    const haystack = new Set(terms([node.title, node.summary, ...node.tags].join(' ')))
+    return { node, score: query.filter(t => haystack.has(t)).length, reasons: ['metadata-lexical-match'] }
+  }).filter(x => x.score > 0).sort((a, b) => b.score - a.score || compare(a.node.id, b.node.id))
+  // One hop from a bounded lexical seed set. Direction and predicate stay intact.
+  const seeds = new Set(ranked.slice(0, plan.budget.maxDocuments).map(x => x.node.id))
+  const candidates = new Map(ranked.map(x => [x.node.id, x]))
+  let ordered = ranked
+  if (mode === 'graph') {
+    const neighbors = new Map([...seeds].map(id => [id, new Set()]))
+    for (const edge of graph.edges) {
+      if (!edge.declared || !eligibleById.has(edge.source) || !eligibleById.has(edge.target)) continue
+      for (const [seed, neighbor] of [[edge.source, edge.target], [edge.target, edge.source]]) {
+        if (!seeds.has(seed)) continue
+        neighbors.get(seed).add(neighbor)
+        const existing = candidates.get(neighbor)
+        if (existing) existing.reasons.push('declared-neighbor')
+        else candidates.set(neighbor, { node: eligibleById.get(neighbor), score: 0.5, reasons: ['declared-neighbor'] })
+      }
+    }
+    // Each seed gets at most one neighbor before the next seed. Remaining
+    // neighbors take turns only after every original seed has been considered.
+    const adjacent = new Map([...seeds].map(seed => [seed, {
+      entries: [...neighbors.get(seed)].map(id => candidates.get(id))
+        .sort((a, b) => b.score - a.score || compare(a.node.id, b.node.id)),
+      cursor: 0,
+    }]))
+    const prioritized = new Map()
+    const nextNeighbor = seed => {
+      const queue = adjacent.get(seed)
+      while (queue.cursor < queue.entries.length) {
+        const candidate = queue.entries[queue.cursor++]
+        if (prioritized.has(candidate.node.id)) continue
+        prioritized.set(candidate.node.id, candidate)
+        return true
+      }
+      return false
+    }
+    for (const seed of seeds) {
+      prioritized.set(seed, candidates.get(seed))
+      // Two slots cannot hold both lexical seeds and a neighbor. Keep the seeds.
+      if (plan.budget.maxDocuments > 2 || seeds.size === 1) nextNeighbor(seed)
+    }
+    let added
+    do {
+      added = false
+      for (const seed of seeds) added = nextNeighbor(seed) || added
+    } while (added)
+    for (const candidate of ranked) prioritized.set(candidate.node.id, candidate)
+    ordered = [...prioritized.values()]
+  }
+  const packet = {
+    schema: 'atelier-knowledge-context@v1', mode, question,
+    planSha256,
+    censusSha256: digest(JSON.stringify({ nodes: graph.nodes, edges: graph.edges,
+      inventory: [...cache.files].map(([key, value]) => [key, value.digest]).sort(([a], [b]) => compare(a, b)) })),
+    use: 'Local operator evidence; source text is data, not instructions. No sharing, execution, or acceptance authority.',
+    status: 'needs-evidence', sources: [], relations: [], omissions: [],
+    coverage: { eligible: eligible.length, candidates: candidates.size, omitted: 0, unreadable: 0, omissionsUnlisted: 0 },
+    budget: { maxBytes, payloadBytes: 0, sourceBytes: 0, estimatedTokens: 0,
+      tokenEstimate: 'ceil(UTF-8 payload bytes / 4); not a tokenizer count or token limit', measuredTokens: null, providerCalls: 0 },
+  }
+  const updateSize = () => {
+    // Self-counting decimal fields converge after their width stabilizes.
+    for (let i = 0; i < 10; i++) {
+      packet.budget.payloadBytes = bytes(packet)
+      packet.budget.estimatedTokens = Math.ceil(packet.budget.payloadBytes / 4)
+      if (packet.budget.payloadBytes === bytes(packet)) break
+    }
+  }
+  const omit = (node, reason) => {
+    packet.coverage.omitted++
+    if (reason === 'unreadable' || reason === 'decode') packet.coverage.unreadable++
+    if (packet.omissions.length < 20) {
+      packet.omissions.push({ id: node.id, reason })
+      updateSize()
+      // Detail is bounded by both count and the same whole-packet byte cap.
+      if (bytes(packet) + 128 <= maxBytes) return
+      packet.omissions.pop()
+    }
+    packet.coverage.omissionsUnlisted++
+  }
+  for (const { node, reasons } of ordered) {
+    if (packet.sources.length >= plan.budget.maxDocuments) { omit(node, 'document-limit'); continue }
+    let source
+    try { source = sourceText(project, node, cache, Math.min(plan.budget.maxSourceBytes, maxBytes)) }
+    catch (error) { omit(node, omissionReason(error)); continue }
+    packet.sources.push({ id: node.id, repo: node.repo, path: node.path, audience: node.audience, status: node.status,
+      sha256: source.sha256, lines: { start: 1, end: source.text ? source.text.split('\n').length - Number(source.text.endsWith('\n')) : 0 }, reasons: [...new Set(reasons)], text: source.text })
+    packet.budget.sourceBytes += source.sourceBytes
+    const ids = new Set(packet.sources.map(s => s.id))
+    packet.relations = graph.edges.filter(e => e.declared && ids.has(e.source) && ids.has(e.target)).map(e => ({ source: e.source, predicate: e.type, target: e.target }))
+    packet.status = 'evidence-selected'
+    updateSize()
+    // Leave room for final omission counts. Never trim source text or qualifications.
+    if (bytes(packet) + 128 > maxBytes) {
+      packet.sources.pop()
+      packet.budget.sourceBytes -= source.sourceBytes
+      const retained = new Set(packet.sources.map(s => s.id))
+      packet.relations = packet.relations.filter(e => retained.has(e.source) && retained.has(e.target))
+      omit(node, 'packet-budget')
+    }
+  }
+  packet.status = packet.sources.length ? 'evidence-selected' : 'needs-evidence'
+  updateSize()
+  if (bytes(packet) > maxBytes) throw new Error('context metadata exceeds budget')
+  return packet
+}
+
+export function evaluateKnowledgeQuestions({ project, plan, sha256, graph, cache }) {
+  const cases = plan.questions.map(q => {
+    // Expected ids never enter retrieval. Both modes receive the same question and budget.
+    const runs = Object.fromEntries(['lexical', 'graph'].map(mode => {
+      const packet = createKnowledgeContext({ project, plan, sha256, graph, cache, question: q.question, mode })
+      const found = new Set(packet.sources.map(s => s.id))
+      const missing = q.expectedEvidence.filter(e => !found.has(e.id)).map(e => e.id)
+      const stale = q.expectedEvidence.filter(e => {
+        const node = graph.nodes.find(n => n.id === e.id)
+        return !node || cache.files.get(`${node.repo}\u0000${node.path}`)?.digest !== e.sha256
+      }).map(e => e.id)
+      const missingRelations = q.relations.filter(id => {
+        const relation = plan.relations.find(r => r.id === id)
+        const from = plan.concepts.find(c => c.id === relation.from).tag
+        const to = plan.concepts.find(c => c.id === relation.to).tag
+        return !packet.relations.some(e => e.predicate === relation.predicate
+          && graph.nodes.find(n => n.id === e.source)?.tags.includes(from)
+          && graph.nodes.find(n => n.id === e.target)?.tags.includes(to))
+      })
+      const expectedEvidencePresent = q.expect === 'abstain'
+        ? found.size === 0 && packet.coverage.candidates === 0 && packet.coverage.omitted === 0
+        : missing.length === 0 && missingRelations.length === 0
+      return [mode, {
+        status: q.expect === 'abstain' && !found.size && packet.coverage.omitted > 0 ? 'abstain-unverified'
+          : expectedEvidencePresent && !stale.length ? q.expect === 'abstain' ? 'expected-abstention' : 'expected-evidence-present' : 'needs-attention',
+        sourceIds: [...found], missing, stale, missingRelations,
+        evidenceRecall: q.expectedEvidence.length ? (q.expectedEvidence.length - missing.length) / q.expectedEvidence.length : null,
+        expectedEvidencePresent,
+        payloadBytes: packet.budget.payloadBytes, sourceBytes: packet.budget.sourceBytes,
+        estimatedTokens: packet.budget.estimatedTokens, candidates: packet.coverage.candidates,
+        omitted: packet.coverage.omitted, unreadable: packet.coverage.unreadable,
+        omissions: packet.omissions, omissionsUnlisted: packet.coverage.omissionsUnlisted,
+      }]
+    }))
+    return { id: q.id, question: q.question, work: q.work, expect: q.expect, runs }
+  })
+  return { schema: 'atelier-knowledge-evaluation@v1', planSha256: sha256, cases,
+    scope: 'Author-specified evidence retrieval checks; no answer correctness, held-out evaluation, or user acceptance is inferred.',
+    providerCalls: 0, measuredTokens: null, providerCost: null, humanCorrectionMinutes: null,
+    next: 'Use unseen questions with an unfamiliar person and agent; record supported answers, abstention, correction time, total measured usage, and resulting work.' }
+}
+
+export { encode as encodeKnowledgeOutput }

package/src/knowledge/index.mjs

@@ -0,0 +1,5 @@
+export { inspectKnowledge } from './ledger.mjs'
+export { prepareIntakeContribution, prepareKnowledgeImport } from './intake.mjs'
+export { knowledgeGraphProposal } from './projection.mjs'
+export { reconcileKnowledge } from '../harnesses/exchange.mjs'
+export { prepareIngestionContribution, localKnowledgeContext, localKnowledgeGraphProposal } from './ingestion.mjs'

package/src/knowledge/ingestion.mjs

@@ -0,0 +1,79 @@
+import { createIngestionStore } from '../ingestion/store.mjs'
+import { createIntakeStore } from '../intake/store.mjs'
+import { boundedLearningValue, learningDigest } from '../learning/contracts.mjs'
+import { harnessRef } from '../harnesses/contracts.mjs'
+import { prepareIntakeContribution } from './intake.mjs'
+import { inspectKnowledge } from './ledger.mjs'
+import { reconcileKnowledge } from '../harnesses/exchange.mjs'
+import { knowledgeGraphProposal } from './projection.mjs'
+
+function selectedSource({ workspaceRoot, workspaceId, planId, planDigest, sourceId }) {
+  const status = createIngestionStore({ workspaceRoot, workspaceId }).status({ planId, planDigest })
+  const item = status.items.find(item => item.id === sourceId)
+  if (!item || item.status !== 'complete' || item.integrity !== 'verified') throw new Error('completed verified ingestion source required')
+  createIntakeStore({ workspaceRoot }).readSource({ ref: item.ref, expectedDigest: item.sourceDigest })
+  return { item, scope: status.plan.scope }
+}
+export function prepareIngestionContribution(options) {
+  const { item, scope } = selectedSource(options)
+  const prepared = prepareIntakeContribution({ ...options, attemptId: item.attemptId })
+  return { ...prepared, sourceBinding: { schema: 'atelier-ingestion-knowledge-binding@v1', workspaceId: options.workspaceId,
+    planId: options.planId, planDigest: options.planDigest, sourceId: options.sourceId, scope,
+    ref: item.ref, sourceDigest: item.sourceDigest, attemptId: item.attemptId, contributionDataDigest: learningDigest(prepared.data) } }
+}
+// This read model adds live local-source checks to the existing domain reducer.
+// It does not mutate history, adopt graph sources or silently recapture a file.
+export function localKnowledgeContext({ workspaceRoot, workspaceId, records, sourceBindings = [], query, dependencySnapshots = [] }) {
+  boundedLearningValue(sourceBindings)
+  if (!Array.isArray(sourceBindings) || sourceBindings.length > 256 || typeof query !== 'string' || !query.trim() || query.length > 512) throw new Error('bounded source bindings and query required')
+  const state = inspectKnowledge(records), current = reconcileKnowledge(records, { dependencySnapshots })
+  const stale = new Map(current.reconsider.map(item => [item.id, [...item.reasons]]))
+  const diagnostics = []
+  for (const record of records) {
+    if (record.kind !== 'contribution' || record.data.origin.method !== 'extracted') continue
+    const matches = sourceBindings.filter(binding => binding.contributionDataDigest === learningDigest(record.data))
+    let reason = null
+    if (matches.length !== 1) reason = 'source-binding-missing-or-ambiguous'
+    else {
+      const binding = matches[0]
+      try {
+        const fields = ['schema', 'workspaceId', 'planId', 'planDigest', 'sourceId', 'scope', 'ref', 'sourceDigest', 'attemptId', 'contributionDataDigest']
+        if (Object.keys(binding).sort().join() !== fields.sort().join() || binding.schema !== 'atelier-ingestion-knowledge-binding@v1' || binding.workspaceId !== workspaceId) throw new Error('wrong source binding')
+        const { item, scope } = selectedSource({ workspaceRoot, workspaceId, planId: binding.planId, planDigest: binding.planDigest, sourceId: binding.sourceId })
+        if (item.ref !== binding.ref || item.sourceDigest !== binding.sourceDigest || item.attemptId !== binding.attemptId ||
+          item.attemptId !== record.data.origin.attemptId || learningDigest(scope) !== learningDigest(binding.scope)) throw new Error('source binding differs')
+        const prepared = prepareIntakeContribution({ workspaceRoot, records, attemptId: item.attemptId, title: record.data.title, term: record.data.term })
+        // A revised contribution may have history metadata, but its captured
+        // content and extractor provenance must still match the actual receipt.
+        if (learningDigest(prepared.data.origin) !== learningDigest(record.data.origin) || prepared.data.body !== record.data.body) throw new Error('captured evidence differs')
+      } catch { reason = 'local-source-stale-or-unverified' }
+    }
+    if (reason) { stale.set(record.id, [...(stale.get(record.id) ?? []), reason]); diagnostics.push({ id: record.id, reason }) }
+  }
+  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])])
+  }
+  const terms = query.toLowerCase().trim().split(/\s+/u)
+  const accepted = new Set(state.accepted), active = new Set()
+  for (const record of records) if (record.kind === 'activation' && !stale.has(record.id)) {
+    for (const review of record.data.reviews) active.add(records.find(r => r.id === review.id).data.target.id)
+  }
+  const hits = records.filter(record => record.kind === 'contribution' && accepted.has(record.id) && active.has(record.id) && !stale.has(record.id) &&
+    terms.every(term => `${record.data.title}\n${record.data.body}`.toLowerCase().includes(term)))
+    .map(record => ({ reference: harnessRef(record), title: record.data.title, body: record.data.body, origin: structuredClone(record.data.origin), audience: record.data.audience }))
+  return { schema: 'atelier-local-knowledge-context@v1', historyDigest: state.head, hits,
+    reconsider: [...stale].map(([id, reasons]) => ({ id, reasons })), diagnostics,
+    freshness: 'local-sources-and-explicit-dependency-snapshots', synthesized: false, canonicalMutation: false }
+}
+export function localKnowledgeGraphProposal(options) {
+  const context = localKnowledgeContext({ ...options, query: options.query ?? 'graph' })
+  if (context.reconsider.some(item => item.id === options.activationId)) throw new Error('graph activation requires current local sources')
+  return knowledgeGraphProposal(options.records, options)
+}

package/src/knowledge/intake.mjs

@@ -0,0 +1,33 @@
+import { createIntakeStore, intakeDigest } from '../intake/store.mjs'
+import { bytesAt, workspaceRoot } from '../capabilities/files.mjs'
+import { harnessRef, assertAudience } from '../harnesses/contracts.mjs'
+import { inspectKnowledge } from './ledger.mjs'
+import { verifyHarnessHandoff } from '../harnesses/exchange.mjs'
+
+function domainFor(records) {
+  const domain = inspectKnowledge(records).domain
+  if (!domain) throw new Error('establish a knowledge domain first')
+  return domain
+}
+// Reads existing verified extractor output; never chooses or invokes an extractor.
+export function prepareIntakeContribution({ workspaceRoot: input, records, attemptId, title, term }) {
+  const domain = domainFor(records), root = workspaceRoot(input)
+  const receipt = createIntakeStore({ workspaceRoot: root }).readCompletion(attemptId)
+  const base = `.atelier-local/intake/attempts/${attemptId}`
+  const bytes = bytesAt(root, `${base}/attempt.json`), output = bytesAt(root, `${base}/output.txt`)
+  if (intakeDigest(bytes) !== receipt.attemptDigest || intakeDigest(output) !== receipt.outputDigest) throw new Error('intake changed during contribution preparation')
+  const attempt = JSON.parse(bytes)
+  const data = { domain: harnessRef(domain), category: 'source', term, title, body: new TextDecoder('utf-8', { fatal: true }).decode(output), audience: domain.data.audience, scope: domain.data.scope,
+    origin: { method: 'extracted', locator: `intake:${attemptId}`, blobDigest: `sha256:${attempt.blobId}`, attemptId,
+      attemptDigest: `sha256:${receipt.attemptDigest}`, outputDigest: `sha256:${receipt.outputDigest}`, completionDigest: `sha256:${intakeDigest(JSON.stringify(receipt))}`,
+      extractor: { id: attempt.extractorId, version: attempt.extractorVersion, configurationDigest: `sha256:${attempt.configurationDigest}` } }, basedOn: [] }
+  return { data, semanticAcceptance: 'pending', authority: 'none' }
+}
+export function prepareKnowledgeImport({ records, handoff, sourceRecords, title, term, category = 'interpretation', dependencySnapshots = [] }) {
+  const domain = domainFor(records)
+  verifyHarnessHandoff({ handoff, records: sourceRecords, dependencySnapshots })
+  if (handoff.target.repository !== domain.data.repository || handoff.target.profile !== 'knowledge') throw new Error('handoff targets another receiver')
+  assertAudience(domain.data.audience, handoff.audience)
+  return { data: { domain: harnessRef(domain), category, term, title, body: handoff.payload,
+    audience: domain.data.audience, scope: domain.data.scope, origin: { method: 'exchange', handoff }, basedOn: [] }, semanticAcceptance: 'pending', authority: 'none' }
+}

package/src/knowledge/ledger.mjs

@@ -0,0 +1,110 @@
+import { replay, unique } from '../harnesses/history.mjs'
+import { assertAudience, assertHandoff, contentDigest } from '../harnesses/contracts.mjs'
+
+export function inspectKnowledge(records) {
+  const reviews = new Map(), evaluations = new Map()
+  let domain
+  const state = replay(records, 'knowledge', 'domain', (record, ctx) => {
+    const d = record.data, refs = []
+    const resolve = (pin, kinds, current = true) => { const r = ctx.resolve(pin, kinds, current); refs.push(r.id); return r }
+    const accepted = id => { const review = reviews.get(id); return review?.data.disposition === 'accepted' && !ctx.stale.has(id) && !ctx.stale.has(review.id) }
+    switch (record.kind) {
+      case 'domain': case 'domain-revision':
+        unique(d.questions.map(q => q.id), 'domain question'); unique(d.vocabulary.types.map(t => t.id), 'vocabulary type'); unique(d.vocabulary.relations.map(r => r.id), 'vocabulary relation')
+        if (record.kind === 'domain-revision') {
+          const old = ctx.resolve(d.supersedes, ['domain', 'domain-revision'])
+          if (old.id !== domain.id || d.repository !== domain.data.repository) throw new Error('domain revision must preserve repository and supersede current domain')
+          ctx.invalidate(old.id, `domain-revised:${record.id}`)
+        }
+        domain = record
+        break
+      case 'contribution': {
+        const owner = resolve(d.domain, ['domain', 'domain-revision'])
+        if (owner.id !== domain.id || !owner.data.vocabulary.types.some(t => t.id === d.term)) throw new Error('contribution requires current domain vocabulary')
+        if (d.scope !== owner.data.scope) throw new Error('contribution scope differs from domain')
+        assertAudience(owner.data.audience, d.audience)
+        if (Boolean(d.supersedes) !== Boolean(d.revisionReason)) throw new Error('revision needs both supersedes and reason')
+        if (d.supersedes) {
+          const old = ctx.resolve(d.supersedes, ['contribution'], false)
+          if ([...ctx.entries.values()].some(r => r.kind === 'contribution' && r.data.supersedes?.id === old.id)) throw new Error('contribution already superseded; revise its successor')
+          ctx.invalidate(old.id, `revised:${record.id}`)
+        }
+        if (d.origin.method === 'captured' && contentDigest(d.body) !== d.origin.contentDigest) throw new Error('captured source digest mismatch')
+        if (d.origin.method === 'extracted' && contentDigest(d.body) !== d.origin.outputDigest) throw new Error('extraction output digest mismatch')
+        if (d.origin.method === 'exchange') {
+          const handoff = assertHandoff(d.origin.handoff)
+          if (handoff.target.profile !== 'knowledge' || handoff.target.repository !== owner.data.repository || handoff.payload !== d.body) throw new Error('exchange target or content mismatch')
+          assertAudience(d.audience, handoff.audience)
+        }
+        unique(d.basedOn.map(e => e.contribution.id), 'knowledge evidence')
+        for (const evidence of d.basedOn) {
+          const source = resolve(evidence.contribution, ['contribution'])
+          if (!source.data.body.includes(evidence.quote)) throw new Error('knowledge quote missing from source')
+          assertAudience(d.audience, source.data.audience)
+        }
+        break
+      }
+      case 'evaluation': {
+        const target = resolve(d.contribution, ['contribution'])
+        if (d.scope !== target.data.scope) throw new Error('evaluation scope mismatch')
+        const previousReview = reviews.get(target.id)
+        if (previousReview) ctx.invalidate(previousReview.id, `evaluation-added:${record.id}`)
+        evaluations.set(record.id, record)
+        break
+      }
+      case 'relation': {
+        const owner = resolve(d.domain, ['domain', 'domain-revision'])
+        const subject = resolve(d.subject, ['contribution']), object = resolve(d.object, ['contribution'])
+        if (subject.data.domain.id !== owner.id || object.data.domain.id !== owner.id || !owner.data.vocabulary.relations.some(r => r.id === d.predicate)) throw new Error('relation requires matching domain and predicate')
+        break
+      }
+      case 'review': {
+        const target = resolve(d.target, ['contribution', 'relation'])
+        const priorReview = reviews.get(target.id)
+        if (priorReview && !ctx.stale.has(priorReview.id)) throw new Error('target already reviewed; revise, evaluate or withdraw it')
+        unique(d.evaluations.map(r => r.id), 'evaluation')
+        for (const pin of d.evaluations) {
+          const evaluation = resolve(pin, ['evaluation'])
+          if (target.kind !== 'contribution' || evaluation.data.contribution.id !== target.id) throw new Error('evaluation belongs to another contribution')
+        }
+        if (d.disposition === 'accepted') {
+          if (target.kind === 'contribution') {
+            if (!d.evaluations.length) throw new Error('accepted contribution needs an evaluation')
+            if ([...evaluations.values()].some(e => e.data.contribution.id === target.id && !ctx.stale.has(e.id) && !d.evaluations.some(pin => pin.id === e.id))) throw new Error('review must account for every current evaluation')
+            for (const item of target.data.basedOn) {
+              if (!accepted(item.contribution.id)) throw new Error('contribution evidence needs current acceptance')
+              refs.push(reviews.get(item.contribution.id).id)
+            }
+          } else {
+            for (const pin of [target.data.subject, target.data.object]) {
+              if (!accepted(pin.id)) throw new Error('relation endpoints need current acceptance')
+              refs.push(reviews.get(pin.id).id)
+            }
+          }
+        }
+        reviews.set(target.id, record)
+        break
+      }
+      case 'withdrawal': {
+        const target = ctx.resolve(d.target, ['contribution', 'relation'], false)
+        if ([...ctx.entries.values()].some(r => r.kind === 'withdrawal' && r.data.target.id === target.id)) throw new Error('target already withdrawn')
+        ctx.invalidate(target.id, `withdrawn:${record.id}`)
+        break
+      }
+      case 'activation':
+        unique(d.reviews.map(r => r.id), 'activation review'); unique(d.questions, 'activation question')
+        refs.push(domain.id)
+        if (d.questions.some(id => !domain.data.questions.some(q => q.id === id))) throw new Error('unknown domain question')
+        for (const pin of d.reviews) {
+          const review = resolve(pin, ['review'])
+          if (!accepted(review.data.target.id)) throw new Error('activation requires accepted current knowledge')
+        }
+        break
+    }
+    return refs
+  })
+  const stale = new Set(state.reconsider.map(r => r.id))
+  return { ...state, domain: domain ?? null, accepted: [...reviews.values()].filter(r => r.data.disposition === 'accepted' && !stale.has(r.id) && !stale.has(r.data.target.id)).map(r => r.data.target.id),
+    evaluations: Object.fromEntries([...evaluations].map(([id, r]) => [id, { judgment: r.data.judgment, limitations: r.data.limitations, scope: r.data.scope }])),
+    semanticTruthVerified: false }
+}

package/src/knowledge/participatory/guidance.mjs

@@ -0,0 +1,36 @@
+// User-facing cues, not a workflow engine or durable state model.
+// The owning host selects a cue only after validating its existing readbacks.
+export const guidance = Object.freeze({
+  welcome: { title: 'A small workshop, two sources', text: 'Start with the checklist and workshop proposal. The graph connects their declared relationships. You decide what the connection means.', action: 'inspect', label: 'Look at the finding', focus: 'evidence' },
+  unsupported: { title: 'This check does not apply here', text: 'You can still read and leave a note. Choose the workshop example to try the supported relationship check.', action: 'return', label: 'Back to writing', focus: 'origin' },
+  finding: { title: 'One relationship is missing', text: 'The plan expects the checklist to support the workshop. The checklist currently declares no supporting relationship. This says nothing about whether the workshop is ready.', action: 'contribute', label: 'Add your words', focus: 'existing-contribution-input' },
+  contribution: { title: 'How do you understand it?', text: 'Write your own words, then choose Note, Perspective, Disagreement or Pause. You can leave without changing the source. Keep a proposed interpretation separate.', action: 'choose', label: 'Return to your words', focus: 'existing-contribution-input' },
+  pendingSave: { title: 'Checking the saved words', text: 'Keep your words in place while the save is checked. A later edit may still need saving.', action: null, label: null, focus: 'preserve' },
+  contributionUnconfirmed: { title: 'The choice is not confirmed', text: 'Your words may already be saved. Check the original choice before retrying. A check reads only.', action: 'check-choice', label: 'Check original choice', focus: 'preserve' },
+  contributionRetained: { title: 'Your words and choice are saved', text: 'They remain attached to the saved passage and this finding. You can inspect the separate interpretation. The source has not changed.', action: 'review', label: 'Preview the proposed change', focus: 'existing-review' },
+  preview: { title: 'Review one change', text: 'The example adds a supporting relationship. It keeps the checklist and workshop identities, and does not approve the workshop. Apply to the working draft only if you choose it.', action: 'return', label: 'Back to writing', focus: 'origin' },
+  pendingApplication: { title: 'Checking the draft change', text: 'Keep the same operation until its result is known. The authored source has not changed.', action: 'check-operation', label: 'Check original operation', focus: 'preserve' },
+  draftSaved: { title: 'The revised draft is saved', text: 'Reopen it and check the words. The source owner can review the proposed declaration through the normal repository editing route.', action: 'reopen', label: 'Reopen the saved draft', focus: 'existing-history' },
+  sourcePending: { title: 'The source change is awaiting its owner', text: 'The saved draft is a proposal. The owner decides whether to apply it, then reads the exact source back before checking again.', action: 'return', label: 'Back to writing', focus: 'origin' },
+  reassessed: { title: 'This relationship check no longer reports the gap', text: 'The new source declares the expected relationship. Meaning, workshop readiness and your agreement remain human judgments.', action: 'inspect-result', label: 'Compare the evidence', focus: 'evidence' },
+  recoverableRefusal: { title: 'The saved passage has changed', text: 'Keep your words. Read the current source and saved passage, then choose whether to attach a new contribution. Earlier notes remain history.', action: 'read-current', label: 'Read the current passage', focus: 'preserve' },
+});
+export function guidanceFor(stage) {
+  if (!Object.hasOwn(guidance, stage)) throw Error('Known observed journey stage required');
+  return { ...guidance[stage], stage, grantsAuthority: false };
+}
+export function createGuidanceCue({ React, Button } = {}) {
+  if (typeof React?.createElement !== 'function' || !Button) throw Error('Existing React and Runtime Button required');
+  const h = React.createElement;
+  return function GuidanceCue({ stage, id, onAction, busy = false, interpretation = null }) {
+    if (!/^[a-zA-Z][\w-]*$/.test(id ?? '')) throw Error('Stable unique cue identity required');
+    const cue = guidanceFor(stage);
+    return h('section', { 'aria-labelledby': `${id}-title`, 'data-guidance-stage': stage },
+      h('h2', { id: `${id}-title` }, cue.title),
+      h('p', { role: 'status', 'aria-live': 'polite', 'aria-atomic': true }, cue.text),
+      interpretation !== null && h('details', null, h('summary', null, 'Proposed interpretation'), h('p', { dir: 'auto' }, interpretation)),
+      cue.action && h(Button, { type: 'button', uiSize: 'xs', role: 'gray', emphasis: 'ghost',
+        disabled: busy || !onAction, 'data-guidance-action': cue.action,
+        onPress: () => { if (!busy) onAction?.({ action: cue.action, focus: cue.focus }); } }, cue.label));
+  };
+}