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

package/src/knowledge-health/capabilities.mjs

@@ -0,0 +1,350 @@
+export const KNOWLEDGE_HEALTH_CAPABILITIES = Object.freeze({
+  "schema": "knowledge-health-capability-map@v0",
+  "projectionOnly": true,
+  "source": {
+    "commit": "fcfdbe5ded672d41c717f49e0cfdf68b6060834d",
+    "tree": "400e181cd0cb55976f3ef7ab1a1405531dacd521",
+    "referenceMode": "Static inventory of the native source at this commit and tree; each reference is pinned by blob. Not a release claim.",
+    "supersededQualification": {
+      "commit": "b1bdc9279a99f7c884ddfdfe0e2a24315d6f3666",
+      "tree": "2797f44baf89007d3808675d897e55a943fc0d65"
+    }
+  },
+  "publishedBaseline": {
+    "version": "0.2.0-alpha.12",
+    "registryIntegrityVerified": true,
+    "sourceVersionLabelIsNotReleaseProof": true
+  },
+  "capabilities": [
+    {
+      "id": "canonical-graph",
+      "spirals": [
+        "S1",
+        "S3"
+      ],
+      "sourceApi": "./graph#buildCanonicalGraph",
+      "sourceCommands": [
+        "atelier graph --project atelier.project.json",
+        "atelier graph --check --project atelier.project.json"
+      ],
+      "sourceReference": {
+        "path": "src/graph/graph.mjs",
+        "line": 147,
+        "blob": "6bce4e1213098457097e025f8ead53e6b4403336",
+        "sha256": "1f01fbeab7e6fcaed127c8fe84c9a48b08f1fec13d21f486c48726715a5bbb92"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": true,
+        "filePresent": true
+      },
+      "verification": "Native function used in the relocated receiving rehearsal. CLI syntax/source only; not executed by this supplier.",
+      "limits": "Canonical graph includes declared and ordinary-link origins/offsets. Legacy graph artifact/CLI includes declared edges only; --check verifies generated artifact freshness, not semantic truth.",
+      "smallestSourceOwnerCorrection": "Keep existing graph implementation. Receive the assessment join; do not replace legacy artifact or claim ordinary links satisfy required direction."
+    },
+    {
+      "id": "typed-plan-check",
+      "spirals": [
+        "S1"
+      ],
+      "sourceApi": "internal:inspectKnowledgePlan",
+      "sourceCommands": [
+        "atelier knowledge check --project atelier.project.json --plan knowledge-plan.json"
+      ],
+      "sourceReference": {
+        "path": "src/knowledge/plan.mjs",
+        "line": 34,
+        "blob": "b029609a678354f188980acb8954030daa817582",
+        "sha256": "7ee8d7d20fcc85264dd484b129eae9a1ab4424b47aae0cce764f9e769fe32336"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Actual rule exercised through the additive installed-export rehearsal.",
+      "limits": "Only typed plan/concept tag/native predicate direction. Native warnings can coexist with ok=true and exit 0; no arbitrary prose applicability.",
+      "smallestSourceOwnerCorrection": "Receive src/knowledge-health and additive ./knowledge-health export; preserve current rule and warnings. Decide user CI warning policy explicitly."
+    },
+    {
+      "id": "bounded-agent-context",
+      "spirals": [
+        "S1",
+        "S2"
+      ],
+      "sourceApi": "internal:createKnowledgeContext",
+      "sourceCommands": [
+        "atelier knowledge context --project atelier.project.json --plan knowledge-plan.json --question \"What supports pilot readiness?\" --mode graph"
+      ],
+      "sourceReference": {
+        "path": "src/knowledge/context.mjs",
+        "line": 57,
+        "blob": "7d2be260883267277050c6f7f1f0b0cd6888e5a4",
+        "sha256": "29a73bc8e1afa498f1ed11e158379317cf738a898a68930d95b90b1f1f395d0d"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Actual native context used in the receiving rehearsal.",
+      "limits": "Bounded metadata lexical seeds and declared one-hop neighbors; omissions, unreadable and unlisted counts retained. Text is data. No provider execution, global semantic search or recipient sharing authority.",
+      "smallestSourceOwnerCorrection": "Ship existing knowledge command with current source; expose source-bound joins via the additive adapter. No replacement retrieval or graph model."
+    },
+    {
+      "id": "question-evaluation",
+      "spirals": [
+        "S2"
+      ],
+      "sourceApi": "internal:evaluateKnowledgeQuestions",
+      "sourceCommands": [
+        "atelier knowledge evaluate --project atelier.project.json --plan knowledge-plan.json"
+      ],
+      "sourceReference": {
+        "path": "src/knowledge/context.mjs",
+        "line": 175,
+        "blob": "7d2be260883267277050c6f7f1f0b0cd6888e5a4",
+        "sha256": "29a73bc8e1afa498f1ed11e158379317cf738a898a68930d95b90b1f1f395d0d"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Native graph/lexical evaluation used before/after correction.",
+      "limits": "Author-specified expected source/relation pins are excluded from retrieval. Stale expectations remain stale. No answer correctness, held-out qualification or human usefulness inference.",
+      "smallestSourceOwnerCorrection": "Ship existing evaluator and explain graph versus lexical comparison, appropriate abstention and explicit expected-pin refresh; retain separate human trials."
+    },
+    {
+      "id": "ingestion-evaluation",
+      "spirals": [
+        "S2"
+      ],
+      "sourceApi": "./ingestion/evaluation#evaluateIngestionTrial",
+      "sourceCommands": [],
+      "sourceReference": {
+        "path": "src/ingestion/evaluation.mjs",
+        "line": 38,
+        "blob": "4871eea0e980e3eb518a4cb23dbe97687ffa71c7",
+        "sha256": "adcf2f5d61fe0313e82a525ec28cea771d9d9ac1e470acba1da5be571387ba58"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Actual exported function exercised on invented calibration evidence, including duplicate accounting.",
+      "limits": "Exact evidence multiset/threshold evaluation; calibration-only never passes held-out gate. Unknown cost/elapsed/human acceptance remain null/unassessed; semanticQualification not-assessed.",
+      "smallestSourceOwnerCorrection": "Include current source export/module in next release and the portable example. No new model or held-out answer bank; genuine semantic trial is separately owned."
+    },
+    {
+      "id": "local-ingestion",
+      "spirals": [
+        "S2"
+      ],
+      "sourceApi": "./ingestion#createIngestionStore",
+      "sourceCommands": [
+        "atelier ingest plan",
+        "atelier ingest run",
+        "atelier ingest status",
+        "atelier ingest query"
+      ],
+      "sourceReference": {
+        "path": "src/commands/ingest.mjs",
+        "line": 4,
+        "blob": "2c5fc628d612968f686990ef39e69fdb6fd701bd",
+        "sha256": "380152f2af7e1e0e8d429a8876bc2b413628c902450733a5163eb49781206da9"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Static API/command source inspection only.",
+      "limits": "Private local UTF-8 JSON envelope; explicit source/scope/budget, lexical evidence; local text/CSV/JSON processing. No semantic claim acceptance or raw file graph enrollment.",
+      "smallestSourceOwnerCorrection": "Reuse current ingestion/store and ./knowledge localKnowledgeContext/contribution paths. Route actual semantic operation and human decisions to existing owners."
+    },
+    {
+      "id": "semantic-operation",
+      "spirals": [
+        "S2"
+      ],
+      "sourceApi": "internal:createSemanticOperation",
+      "sourceCommands": [],
+      "sourceReference": {
+        "path": "src/knowledge/semantic-operation.mjs",
+        "line": 133,
+        "blob": "eb131c7511a45fd0904b4a74a958b04d6436123f",
+        "sha256": "fb6fafabb00dbd65890c5b409f6d4562dcf041c84606a1b0c4f8fb3930d09ef2"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Static source inspection only; not executed or provider-qualified.",
+      "limits": "Owner-bound recorded callback, source dependency witnesses and reconsideration; proposal-only, semantic acceptance pending. No public ./knowledge export at this source for this function.",
+      "smallestSourceOwnerCorrection": "If the Dev Day interpretation path needs it, add the smallest owner-controlled export/wiring and exercise recorded invented lifecycle. Do not substitute a deterministic score for semantic/human evaluation."
+    },
+    {
+      "id": "repository-observation",
+      "spirals": [
+        "S3"
+      ],
+      "sourceApi": "./runtime/observation#observeRepository",
+      "sourceCommands": [
+        "atelier sync status --repo .",
+        "atelier sync trace --repo ."
+      ],
+      "sourceReference": {
+        "path": "src/runtime/repository-observation.mjs",
+        "line": 419,
+        "blob": "89bc5a0fc5eae7830d95b8811faaf664b239d583",
+        "sha256": "e6a53f6ce639a53a0888e038b244d26180ec5ef554bc49686dd91d9b3befb069"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": true,
+        "filePresent": true
+      },
+      "verification": "Public baseline file/export verified; current source inspected read-only.",
+      "limits": "Local Git/head/status/filesystem evidence with blockers and bounded observation. A current Git observation does not prove application adoption, consumption, execution, remote freshness or causal lineage. Sync status/trace use already enrolled runtime state; reconcile/enroll/run are separate effects.",
+      "smallestSourceOwnerCorrection": "Join actual observation/status/operation trace with existing harness history/dependency snapshots in a receiving adapter; require explicit owner evidence for declared/adopted/consumed/executed. This context reports unobserved by default."
+    },
+    {
+      "id": "cross-repository-handoff",
+      "spirals": [
+        "S3"
+      ],
+      "sourceApi": "./harnesses#verifyHarnessHandoff",
+      "sourceCommands": [
+        "atelier harness inspect --profile knowledge --history HISTORY.json",
+        "atelier harness verify --handoff HANDOFF.json --history HISTORY.json"
+      ],
+      "sourceReference": {
+        "path": "src/commands/harness.mjs",
+        "line": 25,
+        "blob": "8fc40a7035e76a819c1752e1da2d413a89eb340f",
+        "sha256": "885070823aabe350eeabea1e629c6b91eb0462a1f5039e6b0759cdea81593ee6"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": false,
+        "filePresent": false
+      },
+      "verification": "Static source inspection only.",
+      "limits": "Complete ledgers and explicit repository/profile/records dependency snapshots. Proposal/reported acceptance is not execution authority; no actual adopter chain was observed.",
+      "smallestSourceOwnerCorrection": "Reuse existing harness handoff/verify/reconcile and exact repository identities; publish a recorded public invented multi-repository exercise through receiving owner. Keep actual adopter/withdrawal acceptance open."
+    },
+    {
+      "id": "readiness-and-generated-freshness",
+      "spirals": [
+        "S3",
+        "S5"
+      ],
+      "sourceApi": "./readiness#buildReadiness",
+      "sourceCommands": [
+        "atelier readiness --project atelier.project.json",
+        "atelier readiness --check --project atelier.project.json",
+        "atelier generated check --project atelier.project.json"
+      ],
+      "sourceReference": {
+        "path": "src/readiness/readiness.mjs",
+        "line": 174,
+        "blob": "05f39956a13a8f8435a4709d4512364aa56a5661",
+        "sha256": "e5244afa52d01e8342cf1730990c3be6dd93bd6e82aaa8fb0014b6215bace652"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": true,
+        "filePresent": true
+      },
+      "verification": "Public baseline file/export verified; static current source inspection only.",
+      "limits": "Existing artifact/schema/readiness checks, generated freshness and typed export boundaries. Native support limits and absent runtime evidence remain explicit; no human semantic health score.",
+      "smallestSourceOwnerCorrection": "Reuse current readiness/generated tools; wire the source-bound assessment outcome as an explicit input only where owner contract permits, without inferring human acceptance."
+    },
+    {
+      "id": "host-and-authoring",
+      "spirals": [
+        "S1",
+        "S4"
+      ],
+      "sourceApi": "./coauthor#createSession",
+      "sourceCommands": [
+        "atelier knowledge dashboard --project atelier.project.json --plan knowledge-plan.json",
+        "atelier knowledge session start",
+        "atelier dev --project atelier.project.json"
+      ],
+      "sourceReference": {
+        "path": "src/coauthor/session.mjs",
+        "line": 22,
+        "blob": "990ec8d01116ef289b514f9b590d53317b473b06",
+        "sha256": "8321f6c3164f55dbcec1c9e6e09f170ec5411e1ceb0685d32075516a4252b0b6"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "entryDeclared": true,
+        "filePresent": true
+      },
+      "verification": "Static current source inspection; this assessment supplier does not exercise UI/store/host save.",
+      "limits": "Existing native coauthor/store, presentation, Obsidian/sidecar and runtime ownership remain. Keyboard/IME/undo/zoom, actual source apply and participant understanding require the existing host proof owners.",
+      "smallestSourceOwnerCorrection": "Receive participatory supplier through existing Authoring writer. Source-bound assessment field binding is a handoff, not an apply operation; preserve one owning editor/save route."
+    },
+    {
+      "id": "normal-knowledge-workspace-init",
+      "spirals": [
+        "S1",
+        "S5"
+      ],
+      "sourceApi": null,
+      "sourceCommands": [
+        "atelier init ./workspace --template knowledge-workspace"
+      ],
+      "sourceReference": {
+        "path": "src/commands/init.mjs",
+        "line": 104,
+        "blob": "986712fb799daf3b8f1c484bf18b521fa6946ad7",
+        "sha256": "fb0c30241181ab6695a8690203bd83c561addd9e84392431395e907e5cb5a46d"
+      },
+      "publishedBaseline": {
+        "version": "0.2.0-alpha.12",
+        "dispatchAvailable": false,
+        "templateAvailable": false
+      },
+      "verification": "Source dispatch inspected read-only. Published baseline missing path/dispatch confirmed independently by package inspection and the receiving proof owner; not executed on a new registry release.",
+      "limits": "Explicit fixture helper does not qualify normal package init or installed hosted journey.",
+      "smallestSourceOwnerCorrection": "Ship actual current templates/knowledge-workspace and normal init knowledge-workspace dispatch; bind both to the frozen source and audit/execute normal init from exact official tarball and new published version."
+    }
+  ],
+  "retainedProgrammeToolingGaps": [
+    {
+      "spiral": "S2",
+      "need": "Semantic fidelity, qualifiers/contradiction/identity; optional bounded agent cost/value; private perspective and scoped learning",
+      "available": "Native question and ingestion evaluation, semantic operation lifecycle, contribution/learning primitives.",
+      "remaining": "Concrete package/UI lifecycle joins and human source-supported semantic trial. No model/held-out execution in this supplier.",
+      "owner": "Existing Foundation/Authoring semantic and evaluation owners via coordinator"
+    },
+    {
+      "spiral": "S3",
+      "need": "Declared/adopted/consumed/executed tracing; freshness, partial refresh, drift, withdrawal/recovery",
+      "available": "Git repository observation, sync status/trace, native source hashes/census omissions, harness ledgers/dependency snapshots.",
+      "remaining": "Actual receiving joins and recorded multi-repository use with exact owner evidence; withdrawal/recovery acceptance.",
+      "owner": "Existing Reliability/Adoption & proof via coordinator"
+    },
+    {
+      "spiral": "S4",
+      "need": "Additional hosts/media/domains, keyboard/IME/text scaling, accessible graph alternative, purposeful scale",
+      "available": "Existing source format/graph/presentation/runtime APIs and context byte/document/source budgets.",
+      "remaining": "Installed cross-host/media and accessibility/scale measurement. This proof is Node22.18 on macOS only.",
+      "owner": "Existing host/Authoring and Journey proof owners"
+    },
+    {
+      "spiral": "S5",
+      "need": "Ownership/documentation/rollback/maintenance and full programme closure",
+      "available": "Portable typed exercise, API/command map, native recovery/readiness and existing owner routes.",
+      "remaining": "Exact audited release, clean npm install, facilitator/participant feedback, ongoing owner receiving, all 22 promises disposition.",
+      "owner": "Coordinator, Foundation release and existing proof owners"
+    }
+  ],
+  "grantsAuthority": false
+})

package/src/knowledge-health/context.mjs

@@ -0,0 +1,62 @@
+import { assessmentDigest } from './assessment.mjs'
+
+const clone = value => structuredClone(value)
+const demand = (ok, message) => { if (!ok) throw new TypeError(message) }
+const canonical = value => Array.isArray(value) ? value.map(canonical)
+  : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value
+export const knowledgeHealthContextDigest = value => assessmentDigest(JSON.stringify(canonical(value)))
+
+/** A caller projection of existing outputs, never a canonical model or score. */
+export function knowledgeHealthContext({ assessment, graph, planBytes, agentSuggestions = [], repositoryEvidence = null }) {
+  demand(assessment?.projectionVersion === 'kh-required-direction-projection/r1'
+    && assessment.grantsAuthority === false && Array.isArray(assessment.findings), 'Source-qualified assessment required')
+  demand(Array.isArray(graph?.nodes) && Array.isArray(graph?.edges) && Array.isArray(graph?.diagnostics), 'Existing canonical graph required')
+  demand(assessment.evidence.graphSha256 === knowledgeHealthContextDigest(graph), 'Assessment graph identity mismatch')
+  demand(planBytes instanceof Uint8Array && assessmentDigest(planBytes) === assessment.evidence.planSha256, 'Assessment raw plan identity mismatch')
+  const plan = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(planBytes))
+  demand(Array.isArray(plan?.concepts) && Array.isArray(plan?.relations) && Array.isArray(plan?.questions), 'Typed plan required')
+  demand(Array.isArray(agentSuggestions) && agentSuggestions.length <= 20, 'At most 20 supplied suggestions')
+  const context = assessment.original.context
+  const selected = new Map((context?.sources ?? []).map(s => [s.id, s]))
+  const suggestions = agentSuggestions.map(suggestion => {
+    demand(suggestion && typeof suggestion.text === 'string' && suggestion.text.trim()
+      && Buffer.byteLength(suggestion.text) <= 4096 && Array.isArray(suggestion.citations)
+      && suggestion.citations.length > 0 && suggestion.citations.length <= 20, 'Bounded suggestion and citations required')
+    const p = suggestion.provenance
+    demand(p && ['actorId', 'method', 'version', 'recordId'].every(k => typeof p[k] === 'string' && p[k].trim())
+      && p.planSha256 === assessment.evidence.planSha256
+      && p.readSetSha256 === assessment.evidence.readSetSha256, 'Suggestion provenance must bind this assessment')
+    for (const c of suggestion.citations) {
+      const source = selected.get(c.id)
+      demand(source && c.sha256 === source.sha256, 'Suggestion citation is absent or stale')
+    }
+    return { text: suggestion.text, citations: clone(suggestion.citations), provenance: clone(p),
+      status: 'caller-supplied-unreviewed', semanticSupport: 'unknown', grantsAuthority: false }
+  })
+  const byCode = Object.fromEntries([...new Set(graph.diagnostics.map(d => d.code ?? 'unspecified'))].sort()
+    .map(code => [code, graph.diagnostics.filter(d => (d.code ?? 'unspecified') === code).length]))
+  return {
+    schema: 'atelier-knowledge-health-context@v0', projection: 'existing-output-view',
+    assessment: clone(assessment),
+    structure: { scope: 'This enrolled graph and typed plan; counts are observations, not health judgments.',
+      records: { observed: graph.nodes.length, unclassified: assessment.original.report.unclassifiedRecords ?? null },
+      edges: { observed: graph.edges.length, declared: graph.edges.filter(e => e.origin === 'declared').length,
+        ordinaryLinks: graph.edges.filter(e => e.origin === 'ordinary-link').length },
+      diagnostics: { observed: graph.diagnostics.length, byCode },
+      concepts: { planned: plan.concepts.length, checked: assessment.original.report.concepts?.length ?? null,
+        rows: clone(assessment.original.report.concepts ?? []) },
+      relations: { planned: plan.relations.length, checked: assessment.original.report.relations?.length ?? null,
+        rows: clone(assessment.original.report.relations ?? []) },
+      questions: { planned: plan.questions.length, selected: context?.question ?? null } },
+    coverage: context ? { state: assessment.coverage, ...clone(context.coverage), selected: context.sources.length,
+      omissions: clone(context.omissions), budget: clone(context.budget) } : { state: 'unknown', selected: null },
+    semantic: { qualification: 'not-assessed', support: 'unknown', providerCalls: 0,
+      measuredCost: null, humanAcceptance: 'unobserved' },
+    agentSuggestions: suggestions,
+    repository: { state: repositoryEvidence === null ? 'unobserved' : 'caller-supplied-unverified',
+      evidence: clone(repositoryEvidence), declared: 'unobserved', adopted: 'unobserved', consumed: 'unobserved', executed: 'unobserved' },
+    reproducibility: { ...clone(assessment.evidence),
+      graphDigestScope: 'Exact native graph output includes location-dependent options. Relocating changes that digest; source/read-set pins remain independently visible.' },
+    grantsAuthority: false,
+  }
+}

package/src/knowledge-health/example.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { resolveProjectConfig } from '../project/config.mjs'
+import { assessKnowledgeHealth } from './owner-join.mjs'
+import { assessmentDigest } from './assessment.mjs'
+import { evaluateIngestionTrial } from '../ingestion/evaluation.mjs'
+
+/** The caller explicitly creates a disposable example. No existing directory
+ * is overwritten, and the assessment operation itself never writes sources. */
+export function initializeExample(destination) {
+  const root = path.resolve(destination)
+  fs.mkdirSync(root, { recursive: false })
+  fs.cpSync(fileURLToPath(new URL('../../fixtures/knowledge-health/workspace/', import.meta.url)), root, { recursive: true, force: false })
+  const git = spawnSync('git', ['init', '--quiet'], { cwd: root, encoding: 'utf8', timeout: 15000,
+    env: { PATH: process.env.PATH, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null' } })
+  if (git.status !== 0) throw new Error('Example requires Git on PATH; remove the disposable example and retry after installing Git')
+  return root
+}
+
+export function assessExample(root) {
+  const project = resolveProjectConfig({ cwd: root, argv: ['--project', path.join(root, 'atelier.project.json')],
+    env: {}, writeLocalState: false })
+  const records = path.join(root, 'records'), sourceBytes = fs.readFileSync(path.join(records, 'checklist.md'))
+  const match = sourceBytes.toString('utf8').match(/^    supports: (\[[^\r\n]*\])$/m)
+  if (!match) throw new Error('Example declaration must remain an inline typed supports array')
+  const prefix = '    supports: ', needle = Buffer.from(match[0]), start = sourceBytes.indexOf(needle) + Buffer.byteLength(prefix)
+  const sourceRevisions = ['checklist.md', 'pilot.md'].map(sourcePath => ({ repo: 'records', path: sourcePath,
+    revision: `content-sha256:${assessmentDigest(fs.readFileSync(path.join(records, sourcePath)))}` }))
+  const revision = sourceRevisions.find(r => r.path === 'checklist.md').revision
+  const binding = { source: { id: 'demo:checklist', repo: 'records', path: 'checklist.md',
+    sha256: assessmentDigest(sourceBytes), revision },
+    field: { id: 'kg.relations.supports', pointer: '/kg/relations/supports', format: 'markdown-inline-array',
+      start, end: start + Buffer.byteLength(match[1]), quote: match[1] },
+    authoring: { storeId: 'invented-example-store', sourceId: 'demo:checklist', artifactId: 'invented-checklist',
+      fieldId: 'kg.relations.supports', actorBindingId: 'invented-example-owner' } }
+  return assessKnowledgeHealth({ project, relationId: 'checklist-pilot', questionId: 'readiness',
+    sourceRevisions, binding, currentSourceBytes: sourceBytes })
+}
+
+/** Recorded invented calibration only. Runs no processor, provider or held-out
+ * suite, and keeps the native evaluator's unknown semantic and cost states. */
+export function evaluateKnowledgeHealthCalibration() {
+  const read = name => JSON.parse(fs.readFileSync(new URL(`../../fixtures/knowledge-health/${name}.json`, import.meta.url), 'utf8'))
+  return evaluateIngestionTrial({ suite: read('calibration-suite'), trial: read('calibration-trial') })
+}

package/src/knowledge-health/index.mjs

@@ -0,0 +1,10 @@
+export { assessmentDigest, createAssessmentProjector, PROJECTION_VERSION } from './assessment.mjs'
+export { knowledgeHealthContext, knowledgeHealthContextDigest } from './context.mjs'
+export { assessKnowledgeHealth } from './owner-join.mjs'
+export { initializeExample as initializeKnowledgeHealthExample, assessExample as assessKnowledgeHealthExample, evaluateKnowledgeHealthCalibration } from './example.mjs'
+export { KNOWLEDGE_HEALTH_CAPABILITIES } from './capabilities.mjs'
+export { initializeKnowledgeHealthWorkshop, assessKnowledgeHealthWorkshop, prepareKnowledgeHealthWorkshopChoice } from './workshop.mjs'
+export { rehearseInstalledWorkshop } from '../knowledge/participatory/installed-workshop.mjs'
+export { inspectKnowledgePlan, validateKnowledgePlan } from '../knowledge/plan.mjs'
+
+export { createPublicWorkshopComposition, inspectPublicWorkshop, preparePublicWorkshopHandoff } from './workshop-composition.mjs'

package/src/knowledge-health/owner-join.mjs

@@ -0,0 +1,88 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { buildCanonicalGraph, createGraphFileCache } from '../graph/graph.mjs'
+import { splitFrontmatter, parseYamlSubset } from '../graph/knowledge-graph.mjs'
+import { inspectKnowledgePlan } from '../knowledge/plan.mjs'
+import { createKnowledgeContext, evaluateKnowledgeQuestions } from '../knowledge/context.mjs'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+import { assessmentDigest, createAssessmentProjector } from './assessment.mjs'
+import { knowledgeHealthContext, knowledgeHealthContextDigest } from './context.mjs'
+
+// Receiving proposal: place this directory beside the existing owner modules.
+// It joins their functions; it adds no graph rules, root CLI or source writer.
+import { ruleIdentity as identity } from './rule-identity.mjs'
+function verifyRules() {
+  for (const pin of identity.files) {
+    const bytes = fs.readFileSync(new URL(`../../${pin.path}`, import.meta.url))
+    if (assessmentDigest(bytes) !== pin.sha256) throw new Error(`Knowledge Health rule identity drift: ${pin.path}`)
+  }
+}
+const pinFor = file => identity.files.find(p => p.path === file)
+const check = { id: 'atelier.inspectKnowledgePlan.required-direction', version: identity.commit,
+  sourceTree: identity.tree, sourceBlob: pinFor('src/knowledge/plan.mjs').blob,
+  schemaBlob: pinFor('templates/knowledge-workspace/knowledge-plan.schema.json').blob,
+  graphBlob: pinFor('src/graph/graph.mjs').blob, sourceSha256: pinFor('src/knowledge/plan.mjs').sha256 }
+const projectAssessment = createAssessmentProjector({ inspectKnowledgePlan, splitFrontmatter, parseYamlSubset, check })
+
+function readBounded(file, ceiling) {
+  const fd = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(fd).size > ceiling) throw new Error('Assessment input exceeds byte ceiling')
+    const bytes = Buffer.alloc(ceiling + 1)
+    let count = 0, read
+    while (count < bytes.length && (read = fs.readSync(fd, bytes, count, bytes.length - count, null)) > 0) count += read
+    if (count > ceiling) throw new Error('Assessment input exceeds byte ceiling')
+    return bytes.subarray(0, count)
+  } finally { fs.closeSync(fd) }
+}
+
+/** Read-only assessment of an existing resolved project. Binding and revisions
+ * come from the source's owner. A content digest is not a durable store head. */
+export function assessKnowledgeHealth({ project, planPath = 'knowledge-plan.json', relationId, questionId,
+  sourceRevisions, binding, currentSourceBytes, maxContextBytes, agentSuggestions = [], repositoryEvidence = null }) {
+  verifyRules()
+  if (!project?.configPath || !project?.repoAccessPath || !Array.isArray(sourceRevisions)) {
+    throw new TypeError('Existing resolved project, explicit access file and source revisions required')
+  }
+  const file = path.resolve(project.configDir, planPath)
+  const planBytes = readBounded(file, 65536), planSha256 = assessmentDigest(planBytes)
+  const plan = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(planBytes))
+  const configBytes = readBounded(project.configPath, 1048576)
+  if (!isDeepStrictEqual(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(configBytes)), project.config)) {
+    throw new TypeError('Resolved project config is stale; resolve it again before assessment')
+  }
+  const scope = { projectSha256: assessmentDigest(configBytes),
+    repoAccessSha256: assessmentDigest(readBounded(project.repoAccessPath, 1048576)),
+    resolvedReposSha256: knowledgeHealthContextDigest(project.repos) }
+  const revisionKeys = sourceRevisions.map(r => JSON.stringify([r.repo, r.path]))
+  if (new Set(revisionKeys).size !== revisionKeys.length) throw new TypeError('Duplicate source revision')
+  const revisions = new Map(sourceRevisions.map(r => [JSON.stringify([r.repo, r.path]), r.revision]))
+  const cache = createGraphFileCache(), graph = buildCanonicalGraph(project, { fileCache: cache })
+  const readSet = { scope, entries: [...cache.files].map(([key, value]) => {
+    const [repo, sourcePath] = key.split('\u0000')
+    const revision = revisions.get(JSON.stringify([repo, sourcePath]))
+    if (typeof revision !== 'string' || !revision.trim()) throw new TypeError('Missing exact source revision')
+    return { repo, path: sourcePath, sha256: value.digest, revision }
+  }) }
+  const native = inspectKnowledgePlan(plan, graph)
+  const question = plan.questions?.find(q => q.id === questionId)
+  const context = native.ok && graph.ok && question
+    ? createKnowledgeContext({ project, plan, sha256: planSha256, graph, cache,
+      question: question.question, ...(maxContextBytes === undefined ? {} : { maxBytes: maxContextBytes }) }) : null
+  // Expected pins are an evaluation input, not a retrieval input. Never update
+  // them because a source was edited: stale evaluation remains visible.
+  const evaluation = native.ok && graph.ok ? evaluateKnowledgeQuestions({ project, plan, sha256: planSha256, graph, cache }) : null
+  if (scope.projectSha256 !== assessmentDigest(readBounded(project.configPath, 1048576))
+    || scope.repoAccessSha256 !== assessmentDigest(readBounded(project.repoAccessPath, 1048576))
+    || planSha256 !== assessmentDigest(readBounded(file, 65536))) throw new Error('Assessment scope changed during read; rerun from current inputs')
+  const assessment = projectAssessment({ planBytes, planSha256, graph, context, evaluation: null,
+    readSet, relationId, questionId, binding, currentSourceBytes })
+  // Retrieval evaluation can retain stale baseline expectations after an
+  // authorized edit while the current structural reassessment clears. These
+  // are separate facts. Caller can feed evaluation to the pure projector when
+  // its task specifically requires those frozen expected-evidence pins.
+  return { assessment, retrievalEvaluation: evaluation,
+    context: Array.isArray(plan.concepts) && Array.isArray(plan.relations) && Array.isArray(plan.questions)
+      ? knowledgeHealthContext({ assessment, graph, planBytes, agentSuggestions, repositoryEvidence }) : null }
+}

package/src/knowledge-health/proof/common.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import assert from 'node:assert/strict';
+export const hash=(value,algorithm='sha256',format='hex')=>createHash(algorithm).update(value).digest(format);
+export const readJson=p=>JSON.parse(fs.readFileSync(p,'utf8'));
+export function pin(p){const b=fs.readFileSync(p);return {path:path.resolve(p),sha256:hash(b),bytes:b.length};}
+export function cleanEnvironment(){
+  const allowed=['PATH','TMPDIR','TMP','TEMP','LANG','LC_ALL','SystemRoot','COMSPEC'];
+  const env=Object.fromEntries(allowed.filter(k=>process.env[k]!==undefined).map(k=>[k,process.env[k]]));
+  return {...env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0'};
+}
+export function run(command,args,{cwd,env=cleanEnvironment(),input,timeout=120000,accept=[0]}={}){
+  const out=spawnSync(command,args,{cwd,env,input,encoding:'utf8',timeout,maxBuffer:4*1024*1024});
+  const observation={command:path.basename(command),args,status:out.status,signal:out.signal,stdout:out.stdout??'',stderr:out.stderr??'',error:out.error?{code:out.error.code,message:out.error.message}:null};
+  if(!accept.includes(out.status)){const e=Error('Consumer command failed: '+path.basename(command)+' '+args.join(' '));e.observation=observation;throw e;}
+  return observation;
+}
+export function npm(args,root,extra={}){
+  assert.notEqual(process.platform,'win32','This harness has not been qualified on Windows');
+  return run('npm',[...args,'--registry=https://registry.npmjs.org','--userconfig='+path.join(root,'config/user.npmrc'),'--globalconfig='+path.join(root,'config/global.npmrc'),'--cache='+path.join(root,'cache'),'--fetch-retries=0','--fetch-timeout=20000'],{cwd:root,...extra});
+}
+export function files(root){const out=[];function walk(dir){for(const e of fs.readdirSync(dir,{withFileTypes:true})){if(e.isDirectory())walk(path.join(dir,e.name));else if(e.isFile())out.push(path.relative(root,path.join(dir,e.name)).replaceAll(path.sep,'/'));}}walk(root);return out.sort();}