@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/decisions/contracts.mjs

@@ -0,0 +1,321 @@
+import { createHash } from 'node:crypto'
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const RESERVED = new Set(['__proto__', 'constructor', 'prototype'])
+const VERSION = /^1\.[0-9]+\.[0-9]+$/
+const REASONS = new Set(['insufficient-evidence', 'ambiguous', 'no-match', 'budget-exhausted', 'provider-unavailable', 'timeout', 'invalid-response', 'unauthorized'])
+const TOLERANCE = 1e-6
+
+// Inspect descriptors before reading values. Invalid in-process inputs such as
+// accessors, symbols, sparse arrays, cycles and custom prototypes are refused
+// without calling their conversion methods or returning their content.
+function jsonSnapshot(input) {
+  const ancestors = new Set()
+  let nodes = 0
+  let bytes = 0
+  function count(value) {
+    bytes += value
+    if (bytes > 16777216) throw new TypeError()
+  }
+  function copy(value, depth) {
+    if (++nodes > 100000 || depth > 32) throw new TypeError()
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) {
+      if (typeof value === 'string' && Buffer.byteLength(value) > 16777216) throw new TypeError()
+      count(Buffer.byteLength(JSON.stringify(value)))
+      return value
+    }
+    if (!value || typeof value !== 'object' || ancestors.has(value)) throw new TypeError()
+    const array = Array.isArray(value)
+    const prototype = Object.getPrototypeOf(value)
+    if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw new TypeError()
+    const descriptors = Object.getOwnPropertyDescriptors(value)
+    const keys = Reflect.ownKeys(descriptors)
+    if (keys.some((key) => typeof key !== 'string' || RESERVED.has(key))) throw new TypeError()
+    count(2)
+    ancestors.add(value)
+    let result
+    if (array) {
+      const length = descriptors.length?.value
+      if (!Number.isSafeInteger(length) || length < 0 || length > 100000 || keys.length !== length + 1) throw new TypeError()
+      result = []
+      for (let index = 0; index < length; index++) {
+        const descriptor = descriptors[String(index)]
+        if (!descriptor || !Object.hasOwn(descriptor, 'value') || !descriptor.enumerable) throw new TypeError()
+        if (index) count(1)
+        result.push(copy(descriptor.value, depth + 1))
+      }
+    } else {
+      result = Object.create(null)
+      for (const [index, key] of keys.entries()) {
+        const descriptor = descriptors[key]
+        if (!Object.hasOwn(descriptor, 'value') || !descriptor.enumerable) throw new TypeError()
+        if (Buffer.byteLength(key) > 16777216) throw new TypeError()
+        count(Buffer.byteLength(JSON.stringify(key)) + 1 + (index ? 1 : 0))
+        result[key] = copy(descriptor.value, depth + 1)
+      }
+    }
+    ancestors.delete(value)
+    return result
+  }
+  return copy(input, 0)
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function text(value, maximum, allowEmpty = false) {
+  if (typeof value !== 'string' || (!allowEmpty && !value.trim())) return false
+  let length = 0
+  for (const character of value) {
+    void character
+    if (++length > maximum) return false
+  }
+  return true
+}
+
+function identifier(value) {
+  return typeof value === 'string' && ID.test(value) && !RESERVED.has(value)
+}
+
+function report() {
+  const errors = []
+  return {
+    errors,
+    check(condition, label) {
+      if (!condition && errors.length < 64) errors.push(label)
+      return condition
+    },
+  }
+}
+
+function closed(value, required, optional, label, checks) {
+  if (!checks.check(object(value), `${label}: expected object`)) return false
+  const allowed = new Set([...required, ...optional, 'ext'])
+  checks.check(required.every((key) => Object.hasOwn(value, key)), `${label}: required field missing`)
+  checks.check(Object.keys(value).every((key) => allowed.has(key)), `${label}: unknown field`)
+  if (Object.hasOwn(value, 'ext')) checks.check(object(value.ext), `${label}.ext: expected object`)
+  return true
+}
+
+function record(value, minimum, maximum, label, checks) {
+  if (!checks.check(object(value), `${label}: expected record`)) return false
+  const keys = Object.keys(value)
+  checks.check(keys.length >= minimum && keys.length <= maximum, `${label}: entry count outside limits`)
+  checks.check(keys.every(identifier), `${label}: invalid identifier`)
+  return keys.length <= maximum
+}
+
+function scope(value, label, checks) {
+  if (closed(value, ['workspaceId', 'authorizationRef'], [], label, checks)) {
+    checks.check(identifier(value.workspaceId), `${label}.workspaceId: invalid identifier`)
+    checks.check(identifier(value.authorizationRef), `${label}.authorizationRef: invalid identifier`)
+  }
+}
+
+function version(value, label, checks) {
+  if (Object.hasOwn(value, 'contractVersion')) {
+    checks.check(typeof value.contractVersion === 'string' && VERSION.test(value.contractVersion), `${label}.contractVersion: invalid version`)
+  }
+}
+
+function inspectRequest(request, checks) {
+  if (!closed(request, ['schema', 'id', 'task', 'rubricVersion', 'scope', 'state', 'evidence', 'questions'], ['contractVersion'], 'request', checks)) return
+  checks.check(request.schema === 'atelier-decision-request@v1', 'request.schema: unsupported schema')
+  version(request, 'request', checks)
+  for (const key of ['id', 'task', 'rubricVersion']) checks.check(identifier(request[key]), `request.${key}: invalid identifier`)
+  scope(request.scope, 'request.scope', checks)
+  checks.check(text(request.state, 32000, true), 'request.state: expected string within limit')
+  const evidenceIds = new Set()
+  if (checks.check(Array.isArray(request.evidence) && request.evidence.length >= 1 && request.evidence.length <= 256, 'request.evidence: expected 1..256 entries')) {
+    for (const evidence of request.evidence) {
+      if (!closed(evidence, ['id', 'sourceRef'], [], 'request.evidence[]', checks)) continue
+      checks.check(identifier(evidence.id), 'request.evidence[].id: invalid identifier')
+      checks.check(!evidenceIds.has(evidence.id), 'request.evidence: duplicate identifier')
+      evidenceIds.add(evidence.id)
+      checks.check(text(evidence.sourceRef, 2048), 'request.evidence[].sourceRef: expected nonempty reference within limit')
+    }
+  }
+  inspectQuestions(request.questions, checks, 'request.questions', evidenceIds)
+}
+
+function inspectQuestions(questions, checks, label, evidenceIds = null) {
+  if (!record(questions, 1, 64, label, checks)) return
+  for (const question of Object.values(questions)) {
+    if (!closed(question, ['type', 'instructions', 'evidenceIds', 'criteria'], [], `${label}[]`, checks)) continue
+    checks.check(text(question.instructions, 4000), `${label}[].instructions: expected nonempty string within limit`)
+    if (checks.check(Array.isArray(question.evidenceIds) && question.evidenceIds.length >= 1 && question.evidenceIds.length <= 256, `${label}[].evidenceIds: expected 1..256 references`)) {
+      checks.check(new Set(question.evidenceIds).size === question.evidenceIds.length, `${label}[].evidenceIds: duplicate reference`)
+      checks.check(question.evidenceIds.every(identifier), `${label}[].evidenceIds: invalid reference`)
+      if (evidenceIds !== null) checks.check(question.evidenceIds.every((id) => evidenceIds.has(id)), `${label}[].evidenceIds: unknown reference`)
+    }
+    if (question.type === 'choice') {
+      if (record(question.criteria, 2, 64, `${label}[].criteria`, checks)) {
+        checks.check(Object.values(question.criteria).every((value) => text(value, 2000)), `${label}[].criteria: expected nonempty descriptions within limit`)
+      }
+    } else if (question.type === 'score') {
+      checks.check(Array.isArray(question.criteria) && question.criteria.length >= 2 && question.criteria.length <= 10 && question.criteria.every((value) => text(value, 2000)), `${label}[].criteria: expected 2..10 nonempty ordered descriptions within limit`)
+    } else if (question.type === 'boolean') {
+      if (closed(question.criteria, ['true', 'false'], [], `${label}[].criteria`, checks)) {
+        checks.check(text(question.criteria.true, 2000) && text(question.criteria.false, 2000), `${label}[].criteria: expected nonempty descriptions within limit`)
+      }
+    } else {
+      checks.check(false, `${label}[].type: unsupported type`)
+    }
+  }
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (object(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`
+  return JSON.stringify(value)
+}
+
+function digest(request) {
+  return createHash('sha256').update(canonical(request), 'utf8').digest('hex')
+}
+
+function inspected(input) {
+  const checks = report()
+  let request
+  try {
+    request = jsonSnapshot(input)
+    inspectRequest(request, checks)
+  } catch {
+    checks.check(false, 'request: expected bounded plain JSON')
+  }
+  return { request, checks }
+}
+
+/** Validate structure and evidence references; this does not authorize egress. */
+export function validateDecisionRequest(input) {
+  const { checks } = inspected(input)
+  return { ok: checks.errors.length === 0, errors: checks.errors }
+}
+
+/** Hash a valid request, including its scope, evidence, rubric and extensions. */
+export function decisionRequestDigest(input) {
+  const { request, checks } = inspected(input)
+  if (checks.errors.length) throw new TypeError('Invalid decision request')
+  return digest(request)
+}
+
+function probability(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+}
+
+function distribution(values, label, checks) {
+  if (!checks.check(values.every(probability), `${label}: values must be probabilities`)) return false
+  return checks.check(Math.abs(values.reduce((sum, value) => sum + value, 0) - 1) <= TOLERANCE, `${label}: probabilities must sum to one`)
+}
+
+function sameKeys(left, right) {
+  const leftKeys = Object.keys(left).sort()
+  const rightKeys = Object.keys(right).sort()
+  return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index])
+}
+
+function answer(question, value, checks, label) {
+  if (question.type === 'choice') {
+    if (!closed(value, ['type', 'choice', 'probabilities', 'confidence'], [], label, checks)) return
+    checks.check(value.type === 'choice', `${label}.type: question type mismatch`)
+    checks.check(probability(value.confidence), `${label}.confidence: expected probability`)
+    checks.check(identifier(value.choice) && Object.hasOwn(question.criteria, value.choice), `${label}.choice: unknown choice`)
+    if (record(value.probabilities, 2, 64, `${label}.probabilities`, checks)) {
+      checks.check(sameKeys(value.probabilities, question.criteria), `${label}.probabilities: criteria keys mismatch`)
+      const values = Object.values(value.probabilities)
+      if (distribution(values, `${label}.probabilities`, checks) && Object.hasOwn(value.probabilities, value.choice)) {
+        checks.check(value.probabilities[value.choice] === Math.max(...values), `${label}.choice: choice must have maximum probability`)
+      }
+    }
+  } else if (question.type === 'score') {
+    if (!closed(value, ['type', 'score', 'probabilities', 'confidence'], [], label, checks)) return
+    checks.check(value.type === 'score', `${label}.type: question type mismatch`)
+    checks.check(probability(value.confidence), `${label}.confidence: expected probability`)
+    checks.check(typeof value.score === 'number' && Number.isFinite(value.score) && value.score >= 0 && value.score <= question.criteria.length - 1, `${label}.score: outside score range`)
+    if (checks.check(Array.isArray(value.probabilities) && value.probabilities.length === question.criteria.length, `${label}.probabilities: criteria count mismatch`)) {
+      if (distribution(value.probabilities, `${label}.probabilities`, checks)) {
+        const expectation = value.probabilities.reduce((sum, value, index) => sum + value * index, 0)
+        checks.check(Math.abs(value.score - expectation) <= TOLERANCE, `${label}.score: weighted expectation mismatch`)
+      }
+    }
+  } else {
+    if (!closed(value, ['type', 'probability'], [], label, checks)) return
+    checks.check(value.type === 'boolean', `${label}.type: question type mismatch`)
+    checks.check(probability(value.probability), `${label}.probability: expected probability`)
+  }
+}
+
+function inspectAnswers(questions, answers, checks, label) {
+  if (!record(answers, 0, 64, label, checks)) return
+  checks.check(sameKeys(answers, questions), `${label}: question keys mismatch`)
+  for (const [id, question] of Object.entries(questions)) {
+    if (Object.hasOwn(answers, id)) answer(question, answers[id], checks, `${label}[]`)
+  }
+}
+
+/**
+ * Validate question/answer shape and distributions without state or hashing.
+ * Evidence reference syntax is checked; membership and authority belong to
+ * the host that holds the source snapshot and transient request binding.
+ */
+export function validateDecisionAnswers(inputQuestions, inputAnswers) {
+  const checks = report()
+  let questions
+  try {
+    questions = jsonSnapshot(inputQuestions)
+    inspectQuestions(questions, checks, 'questions')
+  } catch {
+    checks.check(false, 'questions: expected bounded plain JSON')
+  }
+  if (checks.errors.length) return { ok: false, errors: checks.errors }
+  try {
+    inspectAnswers(questions, jsonSnapshot(inputAnswers), checks, 'answers')
+  } catch {
+    checks.check(false, 'answers: expected bounded plain JSON')
+  }
+  return { ok: checks.errors.length === 0, errors: checks.errors }
+}
+
+function inspectResult(request, result, checks) {
+  if (!closed(result, ['schema', 'requestId', 'requestDigest', 'task', 'rubricVersion', 'scope', 'provider', 'authority', 'mode', 'status', 'answers', 'usage', 'elapsedMs'], ['reason', 'contractVersion'], 'result', checks)) return
+  checks.check(result.schema === 'atelier-decision-result@v1', 'result.schema: unsupported schema')
+  version(result, 'result', checks)
+  checks.check(result.requestId === request.id, 'result.requestId: request binding mismatch')
+  checks.check(result.requestDigest === digest(request), 'result.requestDigest: request binding mismatch')
+  checks.check(result.task === request.task && result.rubricVersion === request.rubricVersion, 'result: task or rubric binding mismatch')
+  scope(result.scope, 'result.scope', checks)
+  checks.check(canonical(result.scope) === canonical(request.scope), 'result.scope: request binding mismatch')
+  if (closed(result.provider, ['id', 'model'], [], 'result.provider', checks)) {
+    checks.check(identifier(result.provider.id), 'result.provider.id: invalid identifier')
+    checks.check(text(result.provider.model, 128), 'result.provider.model: expected nonempty model within limit')
+  }
+  checks.check(result.authority === 'proposal-only', 'result.authority: proposal-only required')
+  checks.check(result.mode === 'shadow' || result.mode === 'advisory', 'result.mode: unsupported mode')
+  checks.check(typeof result.elapsedMs === 'number' && Number.isFinite(result.elapsedMs) && result.elapsedMs >= 0, 'result.elapsedMs: expected finite nonnegative number')
+  if (result.usage !== null && closed(result.usage, ['inputTokens', 'outputTokens'], [], 'result.usage', checks)) {
+    checks.check([result.usage.inputTokens, result.usage.outputTokens].every((value) => Number.isSafeInteger(value) && value >= 0), 'result.usage: expected nonnegative safe integers')
+  }
+  if (!record(result.answers, 0, 64, 'result.answers', checks)) return
+  if (result.status === 'assessed') {
+    checks.check(!Object.hasOwn(result, 'reason'), 'result.reason: not allowed for assessed result')
+    inspectAnswers(request.questions, result.answers, checks, 'result.answers')
+  } else if (result.status === 'abstained') {
+    checks.check(Object.keys(result.answers).length === 0, 'result.answers: abstention must have no answers')
+    checks.check(REASONS.has(result.reason), 'result.reason: unsupported abstention reason')
+  } else {
+    checks.check(false, 'result.status: unsupported status')
+  }
+}
+
+/** Validate integrity and distributions; validity never establishes correctness. */
+export function validateDecisionResult(input, output) {
+  const { request, checks } = inspected(input)
+  if (checks.errors.length) return { ok: false, errors: ['request: invalid decision request'] }
+  try {
+    inspectResult(request, jsonSnapshot(output), checks)
+  } catch {
+    checks.check(false, 'result: expected bounded plain JSON')
+  }
+  return { ok: checks.errors.length === 0, errors: checks.errors }
+}

package/src/disclosure/content-scan.mjs

@@ -35,6 +35,19 @@ export function compileDisclosurePatterns(patternDocs = []) {
   })
 }
 
+export function scanDisclosureText(text, { denylistPatterns = [] } = {}) {
+  if (typeof text !== 'string' || Buffer.byteLength(text) > 4 * 1024 * 1024) throw new Error('disclosure text unavailable or exceeds bounds')
+  const findings = []
+  const patterns = [...STRUCTURAL_DISCLOSURE_PATTERNS, ...denylistPatterns]
+  for (const [index,line] of text.split('\n').entries()) {
+    for (const {pattern,label} of patterns) {
+      pattern.lastIndex = 0
+      if (pattern.test(line)) findings.push({label,line:index+1})
+    }
+  }
+  return {ok:findings.length===0,findings}
+}
+
 export function scanDisclosureContent({
   root = process.cwd(),
   staged = false,

package/src/export/atelier-export-contract.mjs

@@ -191,8 +191,23 @@ function formatAjvError(error) {
   return `${location} ${error.message ?? 'failed schema validation'}`
 }
 
+// One compiled validator per schema object, for as long as the schema lives:
+// compilation is a pure function of the schema, and a registered contract is
+// validated many times per run (a large manifest, every journal entry).
+const compiledValidators = new WeakMap()
+
+function validatorFor(schema) {
+  if (schema === null || typeof schema !== 'object') return ajvForSchema().compile(schema)
+  let validate = compiledValidators.get(schema)
+  if (!validate) {
+    validate = ajvForSchema().compile(schema)
+    compiledValidators.set(schema, validate)
+  }
+  return validate
+}
+
 export function validateJsonSchema(schema, doc) {
-  const validate = ajvForSchema().compile(schema)
+  const validate = validatorFor(schema)
   if (validate(doc)) return []
   return asArray(validate.errors).map(formatAjvError)
 }

package/src/extension-packs/lifecycle.mjs

@@ -0,0 +1,154 @@
+import fs from 'node:fs'
+import { BASE_MIGRATIONS } from '../upgrade/upgrade.mjs'
+import { validReviewArtifact } from '../collaboration/review-contracts.mjs'
+import { fileURLToPath } from 'node:url'
+import { readBoundedSource } from '../readiness-protocols/source-read.mjs'
+
+const rootVersion = JSON.parse(
+  fs.readFileSync(
+    fileURLToPath(new URL('../../package.json', import.meta.url)),
+    'utf8',
+  ),
+).version
+
+export function inspectPackLifecycle(project, packs) {
+  const declared =
+    project.config.ext?.['mnstry.atelier']?.extensionPackLifecycle
+  if (!declared)
+    return {
+      ok: packs.length === 0,
+      schema: 'atelier-pack-lifecycle-report@v1',
+      rootVersion,
+      entries: packs.map((pack) => ({
+        id: pack.id,
+        status: 'legacy-unqualified',
+        admitted: false,
+      })),
+      errors: packs.length
+        ? [
+            'extension-pack lifecycle declaration required for evidence-bound review',
+          ]
+        : [],
+    }
+  let policy
+  try {
+    policy = JSON.parse(readBoundedSource(project.configDir, declared).text)
+  } catch {
+    return {
+      ok: false,
+      errors: ['lifecycle declaration unavailable or unsafe'],
+    }
+  }
+  if (
+    !validReviewArtifact('lifecycle', policy) ||
+    policy.schema !== 'atelier-pack-lifecycle@v1' ||
+    !Array.isArray(policy.packs) ||
+    policy.packs.length > 100 ||
+    Object.keys(policy).some(
+      (key) => !['schema', 'packs', 'ext', 'contractVersion'].includes(key),
+    )
+  )
+    return { ok: false, errors: ['invalid lifecycle declaration'] }
+  const ids = new Set(),
+    errors = []
+  for (const entry of policy.packs) {
+    if (
+      !entry ||
+      typeof entry.id !== 'string' ||
+      ids.has(entry.id) ||
+      !Array.isArray(entry.compatibleRootVersions) ||
+      !entry.compatibleRootVersions.length ||
+      entry.compatibleRootVersions.some(
+        (version) => typeof version !== 'string',
+      ) ||
+      !['active', 'deprecated', 'retired'].includes(entry.status) ||
+      typeof entry.version !== 'string' ||
+      !/^sha256:[a-f0-9]{64}$/.test(entry.digest ?? '') ||
+      Object.keys(entry).some(
+        (key) =>
+          ![
+            'id',
+            'version',
+            'digest',
+            'compatibleRootVersions',
+            'status',
+            'replacement',
+            'migrationId',
+            'ext',
+          ].includes(key),
+      )
+    )
+      errors.push('invalid or duplicate lifecycle pack entry')
+    if (
+      entry?.migrationId &&
+      !BASE_MIGRATIONS.some(
+        (migration) =>
+          migration.id === entry.migrationId &&
+          migration.class === 'extension_pack' &&
+          migration.active !== false,
+      )
+    )
+      errors.push('unknown pack migration; owner migration unavailable')
+    ids.add(entry?.id)
+  }
+  const entries = packs.map((pack) => {
+    const entry = policy.packs.find((item) => item?.id === pack.id)
+    const admitted = Boolean(
+      entry &&
+        entry.version === pack.version &&
+        entry.digest === pack.digest &&
+        entry.compatibleRootVersions?.includes(rootVersion) &&
+        entry.status !== 'retired',
+    )
+    if (!admitted)
+      errors.push(`pack ${pack.id} is not qualified for new execution`)
+    return {
+      id: pack.id,
+      status: entry?.status ?? 'legacy-unqualified',
+      admitted,
+      replacement: entry?.replacement ?? null,
+      migrationId: entry?.migrationId ?? null,
+    }
+  })
+  return {
+    ok: errors.length === 0,
+    schema: 'atelier-pack-lifecycle-report@v1',
+    rootVersion,
+    entries,
+    errors,
+    policy,
+  }
+}
+
+// This report names the existing data-only upgrade operation. It neither
+// changes declarations nor admits a replacement; the source owner applies it.
+export function planPackLifecycleMigration(project, packs) {
+  const report = inspectPackLifecycle(project, packs)
+  const migration = BASE_MIGRATIONS.find(
+    (entry) => entry.class === 'extension_pack' && entry.active !== false,
+  )
+  return {
+    ok: report.ok,
+    schema: 'atelier-pack-migration-plan@v1',
+    dryRun: true,
+    writes: false,
+    current: report,
+    migration: migration
+      ? {
+          id: migration.id,
+          files: migration.files,
+          requiredPostChecks: migration.requiredPostChecks,
+          authority: migration.authority,
+        }
+      : null,
+    steps: [
+      'Retain the prior package, pack declarations, lock and historical records.',
+      'Review replacement term and protocol meanings in the source owner workflow.',
+      'Update the declared version, digest and exact compatible root versions together.',
+      'Use the existing upgrade migration to verify and refresh the lock after owner review.',
+      'Create a new evidence-bound run; old runs retain their original meaning.',
+    ],
+    rollback:
+      'Restore the prior declarations, package and lock together. Retain contribution and evidence history.',
+  }
+}

package/src/graph/graph.mjs

@@ -6,9 +6,12 @@ import {
   REPO_ACCESS_SCHEMA,
   VALID_RELATION_TYPES,
   buildKnowledgeGraph,
+  createGraphFileCache,
   parseYamlSubset,
 } from './knowledge-graph.mjs'
 
+export { createGraphFileCache }
+
 // Compatibility exports. Parsing, census, validation, and diagnostics all live
 // in knowledge-graph.mjs; this module only projects its canonical result into
 // the long-standing `atelier graph` artifact shape.
@@ -100,12 +103,71 @@ function externalRepos(project) {
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
-function canonicalBuild(project) {
+function canonicalBuild(project, overrides = {}) {
   const input = canonicalInput(project)
-  const result = buildKnowledgeGraph(input.options)
+  const result = buildKnowledgeGraph({ ...input.options, ...overrides })
   return { input, result }
 }
 
+// The supported project-to-options seam: the exact buildKnowledgeGraph options
+// every graph consumer derives from a loaded project, plus the configured
+// repositories that could not be read.
+export function canonicalGraphOptions(project) {
+  return canonicalInput(project)
+}
+
+const canonicalEdgeId = (edge) => JSON.stringify([edge.source, edge.type, edge.target])
+
+// The canonical graph for a loaded project, for consumers that need derived
+// edges and the source offsets behind them. Nothing is resolved here: nodes,
+// edges, link occurrences and link findings all come from
+// buildKnowledgeGraph. Each edge gains a stable id and an origin; a derived
+// edge carries every source occurrence that produced it. Embedded assets are
+// reported beside the graph, like link occurrences: `embeds` holds one record
+// per embed occurrence and `assets` each embedded file once. Neither adds a
+// node or an edge.
+// `fileCache` (createGraphFileCache) lets repeated builds of one workspace
+// reuse the per-file census and link scan of every Markdown source whose
+// bytes did not change; the result is the same as without it. `observedDigest`
+// (see createGraphFileCache) lets a caller that observes sources by digest
+// spare the read of a source it knows unchanged.
+export function buildCanonicalGraph(project, { isLinkTargetEligible, isAssetEligible, fileCache = null, observedDigest = null } = {}) {
+  const { input, result } = canonicalBuild(project, {
+    ...(isLinkTargetEligible ? { isLinkTargetEligible } : {}),
+    ...(isAssetEligible ? { isAssetEligible } : {}),
+    ...(fileCache ? { fileCache } : {}),
+    ...(observedDigest ? { observedDigest } : {}),
+  })
+  const canonical = result.workspaceGraph ?? { nodes: [], edges: [], diagnostics: [] }
+  const occurrences = new Map()
+  for (const link of result.resolvedLinks ?? []) {
+    const id = canonicalEdgeId(link)
+    if (!occurrences.has(id)) occurrences.set(id, [])
+    occurrences.get(id).push(link)
+  }
+  const edges = canonical.edges.map((edge) => {
+    const id = canonicalEdgeId(edge)
+    return edge.declared === true
+      ? { id, ...edge, origin: 'declared' }
+      : { id, ...edge, origin: 'ordinary-link', occurrences: occurrences.get(id) ?? [] }
+  })
+  const embeds = result.resolvedEmbeds ?? []
+  const assets = [...new Map(embeds.map((embed) => [embed.asset.id, embed.asset])).values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return {
+    ok: result.ok && input.missing.length === 0,
+    errors: [...input.missing, ...result.errors],
+    options: input.options,
+    nodes: canonical.nodes,
+    edges,
+    diagnostics: canonical.diagnostics,
+    links: result.resolvedLinks ?? [],
+    embeds,
+    assets,
+    linkDiagnostics: result.linkDiagnostics ?? [],
+    ...(result.fileCensus ? { fileCensus: result.fileCensus } : {}),
+  }
+}
+
 export function buildGraph(project) {
   const { input, result } = canonicalBuild(project)
   const canonical = result.workspaceGraph ?? { nodes: [], edges: [], diagnostics: [] }