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

package/src/knowledge/workspace.mjs

@@ -0,0 +1,295 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { commandProject } from '../project/config.mjs'
+import { buildCanonicalGraph, createGraphFileCache } from '../graph/graph.mjs'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+import { digest, inspectKnowledgePlan, validateKnowledgePlan } from './plan.mjs'
+import {
+  createKnowledgeContext,
+  evaluateKnowledgeQuestions,
+} from './context.mjs'
+
+export function readKnowledgePlan(project, name = 'knowledge-plan.json') {
+  const file = path.resolve(project.configDir, name)
+  const fd = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(fd).size > 65536)
+      throw new Error('knowledge plan exceeds 65536 bytes')
+    const buffer = Buffer.alloc(65537)
+    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 > 65536) throw new Error('knowledge plan exceeds 65536 bytes')
+    const bytes = buffer.subarray(0, count)
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    const plan = JSON.parse(text)
+    const errors = validateKnowledgePlan(plan)
+    if (errors.length)
+      throw new Error(`invalid knowledge plan: ${errors.join('; ')}`)
+    // Raw bytes bind the workspace snapshot. Coauthor's text reader strips a
+    // UTF-8 BOM, so its source binding must use the same decoded text digest.
+    return { file, plan, sha256: digest(bytes), sourceDigest: digest(text) }
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+// One small, task-oriented curriculum. Domain definitions and evidence stay in
+// the consuming plan and sources. Prompts are retained in each private session.
+export const KNOWLEDGE_FLOWS = [
+  {
+    id: 'onboard',
+    title: 'Onboard',
+    description: 'Choose useful work and establish who can steward it.',
+    prompts: [
+      [
+        'work',
+        'What decision or deliverable should this workspace improve?',
+        'Name a real task, who needs it, and what a useful result would change.',
+      ],
+      [
+        'people',
+        'Who owns the sources, maintains the model, and reviews the result?',
+        'Name accountable roles and your own role. A typed name records a local assertion.',
+      ],
+      [
+        'sources',
+        'Which sources may be processed, and where must their use stop?',
+        'Record source permissions, audiences, excluded material, and correction or withdrawal arrangements.',
+      ],
+      [
+        'success',
+        'How will you recognize useful work at an acceptable cost?',
+        'Choose an unseen question, a direct-search comparison, and the time, correction, and measured usage you will record.',
+      ],
+    ],
+  },
+  {
+    id: 'model',
+    title: 'Model',
+    description: 'Give the smallest useful vocabulary a precise meaning.',
+    prompts: [
+      [
+        'concept',
+        'Which concept matters to this question, and what does it mean?',
+        'Give its definition, an example, and a counterexample. Reuse a concept before adding another.',
+      ],
+      [
+        'identity',
+        'How do you distinguish the same thing from two similar things?',
+        'State a stable identity rule, aliases, false-merge risks, and how corrections preserve history.',
+      ],
+      [
+        'relation',
+        'Which directed relationship makes the evidence useful?',
+        'Name both concepts, a native predicate, its direction, and its precise meaning. Distinguish an observation from an expectation.',
+      ],
+      [
+        'test',
+        'Which source-supported question would expose a bad model?',
+        'Name decisive passages and unresolved evidence. Propose plan and record changes for the source owner to review.',
+      ],
+    ],
+  },
+  {
+    id: 'deepen',
+    title: 'Deepen',
+    description:
+      'Resolve missing evidence, conflicting claims, and gaps in the model.',
+    prompts: [
+      [
+        'gap',
+        'What can this workspace still not answer reliably?',
+        'Choose a missing relationship, unsupported claim, stale source, contradiction, or unmodeled finding.',
+      ],
+      [
+        'evidence',
+        'What exactly does the source support?',
+        'Cite record IDs and passages. Preserve speaker, date, negation, uncertainty, and alternative explanations.',
+      ],
+      [
+        'proposal',
+        'What is the smallest justified correction or addition?',
+        'Propose a concept, relationship, or source correction. State why it helps this question and what could disprove it.',
+      ],
+      [
+        'review',
+        'Who should review it, and what remains unresolved?',
+        'Record the reviewer, next evidence needed, and a concrete owner handoff. This draft does not apply a source change.',
+      ],
+    ],
+  },
+  {
+    id: 'apply',
+    title: 'Apply',
+    description:
+      'Use bounded evidence to produce a useful answer or an explicit abstention.',
+    prompts: [
+      [
+        'answer',
+        'What answer does the selected evidence support?',
+        'Use source IDs and exact passages. Keep qualifications visible, and say when evidence is insufficient.',
+      ],
+      [
+        'limits',
+        'What remains uncertain or contradicted?',
+        'Separate recorded facts, inference, proposals, and missing evidence. Do not fill a gap from a forecast.',
+      ],
+      [
+        'action',
+        'What should happen next, and who owns that decision?',
+        'Name the proposed action or deliverable, prerequisites, recipient, and accountable owner. Saving does not execute it.',
+      ],
+      [
+        'validation',
+        'What must a reviewer verify before using this result?',
+        'Specify the source checks and the observable outcome that would demonstrate useful work.',
+      ],
+    ],
+  },
+  {
+    id: 'learn',
+    title: 'Learn',
+    description: 'Use observed outcomes to improve the next task.',
+    prompts: [
+      [
+        'outcome',
+        'What actually happened when this result was used?',
+        'Separate intended action, observed outcome, and user acceptance. Cite outcome evidence or say it is not yet observed.',
+      ],
+      [
+        'quality',
+        'What did the person or agent get right, miss, or need help with?',
+        'Record correctness, abstention, confusion, assistance, and correction effort on an unseen question.',
+      ],
+      [
+        'cost',
+        'What did the work cost compared with direct source search?',
+        'Record elapsed time, actual input/output/cache tokens, provider cost, and correction minutes. Use unknown for unmeasured values.',
+      ],
+      [
+        'change',
+        'What should change in the ontology or workflow?',
+        'Propose the smallest useful change, its owner, a regression question, and any lesson suitable for later reviewed reuse.',
+      ],
+    ],
+  },
+]
+
+export function loadKnowledgeWorkspace(
+  initial,
+  planName = 'knowledge-plan.json'
+) {
+  // Re-read enrollment and local overrides on every operation. Explicit CLI
+  // path overrides stay explicit; an edited project is not a cached authority.
+  const overrides = initial.repos
+    .filter((r) => r.pathSource === 'cli')
+    .flatMap((r) => ['--repo-path', `${r.name}=${r.path}`])
+  // Normalize the selected workspace directory, not internal plan/source links.
+  // /tmp, /var, and user-created workspace aliases resolve to the same binding.
+  const configDir = fs.realpathSync(initial.configDir)
+  const project = commandProject({
+    cwd: configDir,
+    argv: [
+      '--project',
+      path.join(configDir, path.basename(initial.configPath)),
+      ...overrides,
+    ],
+    writeLocalState: false,
+  })
+  const source = readKnowledgePlan(project, planName)
+  const cache = createGraphFileCache()
+  const graph = buildCanonicalGraph(project, { fileCache: cache })
+  const inventory = [...cache.files]
+    .map(([key, value]) => [key, value.digest])
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  const snapshot = digest(
+    JSON.stringify({
+      plan: source.sha256,
+      config: project.config,
+      repos: project.repos,
+      nodes: graph.nodes,
+      edges: graph.edges,
+      inventory,
+    })
+  )
+  return { project, ...source, cache, graph, snapshot }
+}
+
+export function knowledgeDashboard(workspace) {
+  const { project, plan, graph, snapshot } = workspace
+  const inspection = inspectKnowledgePlan(plan, graph)
+  const evaluation = graph.ok ? evaluateKnowledgeQuestions(workspace) : null
+  return {
+    schema: 'atelier-knowledge-dashboard/experimental-v1',
+    snapshot,
+    name: project.config.name,
+    purpose: plan.purpose,
+    steward: plan.steward,
+    reviewer: plan.reviewer,
+    governance: plan.governance,
+    budget: plan.budget,
+    inspection,
+    concepts: plan.concepts.map((c) => ({
+      ...c,
+      coverage: inspection.concepts?.find((x) => x.id === c.id) ?? null,
+    })),
+    relations: plan.relations.map((r) => ({
+      ...r,
+      coverage: inspection.relations?.find((x) => x.id === r.id) ?? null,
+    })),
+    questions: plan.questions,
+    evaluation,
+    flows: KNOWLEDGE_FLOWS,
+    next: !inspection.ok
+      ? {
+          stage: 'onboard',
+          reason: 'Repair the graph diagnostics before relying on context.',
+        }
+      : inspection.warnings.length
+      ? { stage: 'deepen', reason: inspection.warnings[0] }
+      : evaluation?.cases.some((c) => c.runs.graph.status === 'abstain-unverified')
+      ? {
+          stage: 'deepen',
+          reason:
+            'Matching evidence was omitted; the abstention cannot be verified. Inspect the listed omissions.',
+        }
+      : evaluation?.cases.some((c) => c.expect === 'abstain' && c.runs.graph.sourceIds.length)
+      ? {
+          stage: 'deepen',
+          reason:
+            'Matching evidence was retrieved for an expected abstention. Inspect the evidence and review the question.',
+        }
+      : evaluation?.cases.some(
+          (c) =>
+            !c.runs.graph.expectedEvidencePresent || c.runs.graph.stale.length
+        )
+      ? {
+          stage: 'deepen',
+          reason:
+            'Resolve missing or changed evidence before using the affected answer.',
+        }
+      : {
+          stage: 'apply',
+          reason:
+            'Try a useful question, inspect its evidence, and record the result for review.',
+        },
+    assurance:
+      'Coverage checks describe retrieval. Human judgment, useful outcomes, and measured savings remain to be observed.',
+    sourceEditsApplied: false,
+    providerCalls: 0,
+  }
+}
+
+export function knowledgeQuestionContext(workspace, id, mode = 'graph') {
+  const question = workspace.plan.questions.find((q) => q.id === id)
+  if (!question) throw new Error('unknown knowledge question')
+  return createKnowledgeContext({
+    ...workspace,
+    question: question.question,
+    mode,
+  })
+}

package/src/knowledge-health/assessment.mjs

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+
+// Consumer projection only. The injected Atelier checker owns every graph rule.
+// No I/O, accepted knowledge, authoring write, model, or health score lives here.
+export const PROJECTION_VERSION = 'kh-required-direction-projection/r1'
+export const assessmentDigest = bytes => createHash('sha256').update(bytes).digest('hex')
+const clone = value => structuredClone(value)
+const sha = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
+const text = value => typeof value === 'string' && value.trim().length > 0
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (plain(value)) return Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])]))
+  return value
+}
+const digestObject = value => assessmentDigest(JSON.stringify(canonical(value)))
+const requireInput = (condition, message) => { if (!condition) throw new TypeError(message) }
+const safePath = value => text(value) && !value.startsWith('/') && !value.includes('\\')
+  && value.split('/').every(part => part && part !== '.' && part !== '..')
+const decode = bytes => new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+function readSetPins(readSet) {
+  requireInput(plain(readSet) && plain(readSet.scope) && sha(readSet.scope.projectSha256)
+    && sha(readSet.scope.repoAccessSha256) && Array.isArray(readSet.entries), 'Exact project/access/read-set pins required')
+  const keys = new Set()
+  const entries = readSet.entries.map(entry => {
+    requireInput(plain(entry) && text(entry.repo) && safePath(entry.path) && sha(entry.sha256)
+      && text(entry.revision), 'Exact source read-set entry required')
+    const key = JSON.stringify([entry.repo, entry.path])
+    requireInput(!keys.has(key), 'Duplicate read-set source'); keys.add(key)
+    return { repo: entry.repo, path: entry.path, sha256: entry.sha256, revision: entry.revision }
+  }).sort((a, b) => {
+    const left = JSON.stringify([a.repo, a.path]), right = JSON.stringify([b.repo, b.path])
+    return left < right ? -1 : left > right ? 1 : 0
+  })
+  return { scope: clone(readSet.scope), entries }
+}
+
+/** Inject the current owner-qualified implementations and their source identity. */
+export function createAssessmentProjector({ inspectKnowledgePlan, splitFrontmatter, parseYamlSubset, check }) {
+  requireInput([inspectKnowledgePlan, splitFrontmatter, parseYamlSubset].every(f => typeof f === 'function')
+    && plain(check) && text(check.id) && sha(check.sourceSha256)
+    && ['version', 'sourceTree', 'sourceBlob', 'schemaBlob', 'graphBlob'].every(k => /^[a-f0-9]{40}$/.test(check[k] ?? '')),
+  'Qualified checker/parser commit/tree/blob identity required')
+  const checker = clone(check)
+  const metadata = bytes => {
+    const split = splitFrontmatter(decode(bytes))
+    requireInput(split !== null, 'A typed Markdown frontmatter declaration is required')
+    return parseYamlSubset(split.yaml)
+  }
+
+  return function assessRequiredDirection({ planBytes, planSha256, graph, context = null,
+    evaluation = null, readSet, relationId, questionId, binding = null, currentSourceBytes = null }) {
+    requireInput(planBytes instanceof Uint8Array && sha(planSha256)
+      && assessmentDigest(planBytes) === planSha256, 'Current raw plan bytes/hash required')
+    const plan = JSON.parse(decode(planBytes))
+    requireInput(plain(graph) && typeof graph.ok === 'boolean' && Array.isArray(graph.nodes)
+      && Array.isArray(graph.edges) && Array.isArray(graph.errors), 'Canonical graph output required')
+    const pins = readSetPins(readSet)
+    // Original checker output is never rewritten or reconstructed from warnings.
+    const report = inspectKnowledgePlan(plan, graph)
+    const original = clone({ report, diagnostics: graph.diagnostics ?? [], graphErrors: graph.errors, context, evaluation })
+    requireInput(plain(report) && typeof report.ok === 'boolean' && Array.isArray(report.warnings)
+      && Array.isArray(report.errors), 'Unsupported checker output')
+    const evidence = { check: clone(checker), planSha256, readSet: pins, readSetSha256: digestObject(pins),
+      graphSha256: digestObject(graph), reportSha256: digestObject(report) }
+    const result = { projectionVersion: PROJECTION_VERSION, status: 'uncertain',
+      structure: report.status ?? 'invalid', coverage: 'unknown', currency: 'unverified',
+      semanticQualification: 'not-assessed', semanticSupport: 'unknown', grantsAuthority: false,
+      evidence, original, findings: [], refusal: null }
+    const refuse = (code, reason) => {
+      result.status = 'uncertain'; result.refusal = { code, reason }; return result
+    }
+    if (!graph.ok || !report.ok) { result.status = 'invalid'; return result }
+    requireInput(Array.isArray(report.relations), 'Unsupported relation-check output')
+    const relation = plan.relations.find(r => r.id === relationId)
+    const question = plan.questions.find(q => q.id === questionId)
+    requireInput(relation && question && question.relations.includes(relationId), 'A task-required declared relation must be selected')
+    const checked = report.relations.find(r => r.id === relationId)
+    requireInput(checked && Number.isSafeInteger(checked.matchingEdges), 'Selected relation has no checker result')
+    const warning = `relation ${relationId} has no declared edge in the required direction`
+    requireInput(report.warnings.includes(warning) === (checked.matchingEdges === 0), 'Checker relation/warning mismatch')
+    evidence.relationId = relationId; evidence.questionId = questionId
+
+    if (context !== null) {
+      requireInput(context.schema === 'atelier-knowledge-context@v1' && plain(context.coverage)
+        && Array.isArray(context.omissions) && Array.isArray(context.sources), 'Existing context output required')
+      if (context.planSha256 !== planSha256) return refuse('context-plan-stale', 'Context belongs to a different plan')
+      if (context.question !== question.question) return refuse('context-question-mismatch', 'Context belongs to a different task question')
+      for (const source of context.sources) {
+        const pin = pins.entries.find(e => e.repo === source.repo && e.path === source.path)
+        if (!pin || pin.sha256 !== source.sha256) return refuse('context-read-set-mismatch', 'Selected context source does not match the read-set')
+      }
+      result.coverage = context.coverage.omitted > 0 || context.coverage.omissionsUnlisted > 0 ? 'partial' : 'complete'
+      if (context.omissions.some(o => o.reason === 'changed-since-census')) {
+        result.currency = 'changed'
+        return refuse('source-changed-since-census', 'Current context omitted changed source bytes')
+      }
+      evidence.contextCensusSha256 = context.censusSha256
+      evidence.contextSha256 = digestObject(context)
+    }
+    if (evaluation !== null) {
+      requireInput(evaluation.schema === 'atelier-knowledge-evaluation@v1' && Array.isArray(evaluation.cases), 'Existing evaluation output required')
+      if (evaluation.planSha256 !== planSha256) return refuse('evaluation-plan-stale', 'Evaluation belongs to a different plan')
+      const evaluated = evaluation.cases.find(c => c.id === questionId)?.runs?.graph
+      requireInput(evaluated && Array.isArray(evaluated.stale), 'Selected question has no graph evaluation result')
+      if (evaluated.stale.length) {
+        result.currency = 'changed'
+        return refuse('expected-evidence-stale', 'Evaluation retains stale expected source pins')
+      }
+      evidence.evaluationSha256 = digestObject(evaluation)
+    }
+
+    // Bind even a cleared finding so a stale or missing target never masquerades
+    // as verified source correction. Refusals expose no actionable edit target.
+    if (!binding || !(currentSourceBytes instanceof Uint8Array)) return refuse('binding-missing', 'Exact source/field binding and current bytes are required')
+    const source = binding.source, field = binding.field, authoring = binding.authoring
+    if (!plain(source) || !plain(field) || !plain(authoring)) return refuse('binding-missing', 'Source, declaration and existing authoring identity are required')
+    const pin = pins.entries.find(e => e.repo === source.repo && e.path === source.path)
+    if (!pin || !sha(source.sha256) || !text(source.revision) || source.sha256 !== pin.sha256
+      || source.revision !== pin.revision || assessmentDigest(currentSourceBytes) !== source.sha256) {
+      result.currency = 'changed'; return refuse('binding-stale', 'Source bytes/revision differ from the bound read-set')
+    }
+    const node = graph.nodes.find(n => n.id === source.id && n.repo === source.repo && n.path === source.path)
+    const from = plan.concepts.find(c => c.id === relation.from)
+    if (!node || !node.tags.includes(from.tag)) return refuse('binding-source-mismatch', 'Target is not a source in the selected relation role')
+    if (field.format !== 'markdown-inline-array' || field.id !== `kg.relations.${relation.predicate}`
+      || field.pointer !== `/kg/relations/${relation.predicate}` || !Number.isSafeInteger(field.start)
+      || !Number.isSafeInteger(field.end) || field.start < 0 || field.end <= field.start
+      || field.end > currentSourceBytes.length || !text(field.quote) || !/^\[[^\r\n]*\]$/.test(field.quote)) {
+      return refuse('unsupported-declaration-profile', 'Only exact inline typed relation-array values are supported')
+    }
+    if (!['storeId', 'sourceId', 'artifactId', 'fieldId', 'actorBindingId'].every(k => text(authoring[k]))
+      || authoring.sourceId !== source.id || authoring.fieldId !== field.id) return refuse('authoring-binding-mismatch', 'Existing opaque authoring binding must match this source and field')
+    try {
+      const bytes = Buffer.from(currentSourceBytes)
+      // Fatal decoding of each segment refuses a split UTF-8 character.
+      decode(bytes.subarray(0, field.start)); decode(bytes.subarray(field.end))
+      if (decode(bytes.subarray(field.start, field.end)) !== field.quote) return refuse('binding-quote-mismatch', 'Declaration quote differs from exact source bytes')
+      const parsed = metadata(bytes), declared = parsed.kg?.relations?.[relation.predicate]
+      if (parsed.kg?.id !== node.id || !Array.isArray(declared) || !isDeepStrictEqual(declared, node.relations?.[relation.predicate])) {
+        return refuse('binding-declaration-mismatch', 'Typed declaration differs from canonical graph metadata')
+      }
+      // Prove the byte range is THIS typed value, using the existing parser.
+      // A matching quote in prose, another field or an overshadowed key fails.
+      const sentinel = `kh-locator-probe-${assessmentDigest(bytes).slice(0, 16)}`
+      const probe = Buffer.concat([bytes.subarray(0, field.start), Buffer.from(JSON.stringify([sentinel])), bytes.subarray(field.end)])
+      const expected = clone(parsed); expected.kg.relations[relation.predicate] = [sentinel]
+      if (!isDeepStrictEqual(metadata(probe), expected)) return refuse('binding-not-declaration', 'Byte range does not uniquely address the selected typed declaration')
+    } catch { return refuse('binding-decode-or-profile', 'Source or declaration does not fit the supported exact-byte profile') }
+
+    result.currency = 'current'
+    evidence.bindingSha256 = digestObject(binding)
+    evidence.comparisonSha256 = digestObject({ ...evidence, binding })
+    result.status = result.coverage === 'partial' ? 'partial'
+      : result.coverage === 'unknown' ? 'uncertain' : report.status
+    if (checked.matchingEdges === 0) result.findings.push({ referenceKey: `required-direction:${relationId}`,
+      originalMessage: warning, check: clone(checker), relation: clone(relation), questionId,
+      source: clone(source), declaration: clone(field), authoringBinding: clone(authoring),
+      actionable: result.coverage === 'complete', uncertainty: ['semantic-support-unassessed',
+        ...(result.coverage !== 'complete' ? ['coverage-incomplete'] : [])],
+      action: { kind: 'review-source-declaration', sourceMutation: false, canonicalAcceptance: false } })
+    return result
+  }
+}