clearai-dsh 0.3.0 → 0.4.0

package/lib/domain-language.js

@@ -20,6 +20,8 @@
  * 断言里 `predicate` 与 `subject.type` 都是这个空间里的名字,分开两个空间只会让引用含混。
  */
 
+import { bilingual, tr } from './lang.js'
+
 /** 字面值的五种形态。断言客体如果是**值**,必是其中之一。 */
 export const VALUE_FORMS = ['statement', 'quantity', 'formula', 'code', 'reference']
 
@@ -202,42 +204,50 @@ export function subjectKey(assertion) {
 	return `${text(subject.type)}|${text(subject.id)}`
 }
 
+/**
+ * 一个类型算不算某个概念:就是它,或它的父链上有它(`jepa` is_a … `method` ⇒ 算 `method`)。
+ * 主词域与值域都按这一条判——只认字面相等,模型就得为每个子类另立一条谓词。
+ */
+function isKindOf(lexicon, type, ancestor) {
+	return type === ancestor || termChain(lexicon, type).chain.includes(ancestor)
+}
+
 /** 客体形态与谓词值域是否相容。 */
-function objectProblems(predicate, object) {
+function objectProblems(lexicon, predicate, object) {
 	const problems = []
-	if (!isPlainObject(object)) return [problem('object_required', '断言要有宾语')]
+	if (!isPlainObject(object)) return [problem('object_required', tr('断言要有宾语', 'An assertion needs an object'))]
 	const kind = text(object.kind)
-	if (!OBJECT_KINDS.includes(kind)) return [problem('object_kind_unknown', `宾语形态「${kind}」不认识(可用:${OBJECT_KINDS.join(' / ')})`)]
+	if (!OBJECT_KINDS.includes(kind)) return [problem('object_kind_unknown', tr(`宾语形态「${kind}」不认识(可用:${OBJECT_KINDS.join(' / ')})`, `Unknown object kind "${kind}" (allowed: ${OBJECT_KINDS.join(' / ')})`))]
 	const range = isPlainObject(predicate.range) ? predicate.range : {}
 	const rangeTerm = text(range.term)
 	const rangeForm = text(range.form)
 	if (rangeTerm !== '') {
-		if (kind !== 'instance') return [problem('object_form_mismatch', `谓词「${predicate.id}」的宾语是概念「${rangeTerm}」的实例,宾语形态应为 instance`)]
+		if (kind !== 'instance') return [problem('object_form_mismatch', tr(`谓词「${predicate.id}」的宾语是概念「${rangeTerm}」的实例,宾语形态应为 instance`, `The object of predicate "${predicate.id}" is an instance of concept "${rangeTerm}"; the object kind should be instance`))]
 		const type = text(object.type)
-		if (type !== '' && type !== rangeTerm) return [problem('object_type_mismatch', `宾语实例的类型「${type}」与谓词值域「${rangeTerm}」不一致`)]
-		if (text(object.value) === '') return [problem('object_value_required', '宾语实例要有名称')]
+		if (type !== '' && !isKindOf(lexicon, type, rangeTerm)) return [problem('object_type_mismatch', tr(`宾语实例的类型「${type}」既不是谓词值域「${rangeTerm}」,也不是它的下位概念`, `The object instance type "${type}" is neither the predicate range "${rangeTerm}" nor one of its subconcepts`))]
+		if (text(object.value) === '') return [problem('object_value_required', tr('宾语实例要有名称', 'The object instance needs a name'))]
 		return []
 	}
-	if (rangeForm !== '' && kind !== rangeForm) return [problem('object_form_mismatch', `谓词「${predicate.id}」的值形态是 ${rangeForm},宾语却是 ${kind}`)]
+	if (rangeForm !== '' && kind !== rangeForm) return [problem('object_form_mismatch', tr(`谓词「${predicate.id}」的值形态是 ${rangeForm},宾语却是 ${kind}`, `Predicate "${predicate.id}" takes ${rangeForm} values, but the object is ${kind}`))]
 	switch (kind) {
 		case 'statement':
-			if (text(object.value) === '') problems.push(problem('object_value_required', '陈述不能为空'))
-			else if (String(object.value).length > 2000) problems.push(problem('object_value_too_long', '陈述超过 2000 字:把它拆成断言,或把长文放证据里'))
+			if (text(object.value) === '') problems.push(problem('object_value_required', tr('陈述不能为空', 'The statement cannot be empty')))
+			else if (String(object.value).length > 2000) problems.push(problem('object_value_too_long', tr('陈述超过 2000 字:把它拆成断言,或把长文放证据里', 'The statement is over 2000 characters: split it into assertions, or put the long text in evidence')))
 			break
 		case 'quantity':
-			if (typeof object.value !== 'number' || !Number.isFinite(object.value)) problems.push(problem('object_quantity_shape', '量形态的 value 必须是有限数值'))
-			if (text(object.unit) === '') problems.push(problem('object_unit_required', '量形态要带单位:没有单位的数不是量'))
+			if (typeof object.value !== 'number' || !Number.isFinite(object.value)) problems.push(problem('object_quantity_shape', tr('量形态的 value 必须是有限数值', 'A quantity value must be a finite number')))
+			if (text(object.unit) === '') problems.push(problem('object_unit_required', tr('量形态要带单位:没有单位的数不是量', 'A quantity needs a unit: a number without a unit is not a quantity')))
 			break
 		case 'formula':
-			if (text(object.value) === '') problems.push(problem('object_value_required', '公式不能为空'))
+			if (text(object.value) === '') problems.push(problem('object_value_required', tr('公式不能为空', 'The formula cannot be empty')))
 			break
 		case 'code':
-			if (text(object.value) === '') problems.push(problem('object_value_required', 'code 形态要指向工作区里的一个文件,不能为空'))
-			else if (/^([/\\]|[A-Za-z]:[\\/])/.test(text(object.value))) problems.push(problem('object_code_absolute', 'code 形态要写工作区内的相对路径:绝对路径换个工作区就没了'))
-			else if (text(object.value).split(/[/\\]/).includes('..')) problems.push(problem('object_code_escape', 'code 形态不许越出工作区(路径里出现了 ..)'))
+			if (text(object.value) === '') problems.push(problem('object_value_required', tr('code 形态要指向工作区里的一个文件,不能为空', 'A code value must point to a file in the workspace and cannot be empty')))
+			else if (/^([/\\]|[A-Za-z]:[\\/])/.test(text(object.value))) problems.push(problem('object_code_absolute', tr('code 形态要写工作区内的相对路径:绝对路径换个工作区就没了', 'A code value must be a path relative to the workspace: an absolute path breaks in another workspace')))
+			else if (text(object.value).split(/[/\\]/).includes('..')) problems.push(problem('object_code_escape', tr('code 形态不许越出工作区(路径里出现了 ..)', 'A code value cannot leave the workspace (the path contains ..)')))
 			break
 		case 'reference':
-			if (text(object.value) === '') problems.push(problem('object_value_required', '引用不能为空'))
+			if (text(object.value) === '') problems.push(problem('object_value_required', tr('引用不能为空', 'The reference cannot be empty')))
 			break
 		default:
 			break
@@ -251,32 +261,32 @@ function objectProblems(predicate, object) {
  */
 export function validateAssertion(lexicon, assertion) {
 	const problems = []
-	if (!isPlainObject(assertion)) return [problem('assertion_shape', '断言必须是一个对象')]
+	if (!isPlainObject(assertion)) return [problem('assertion_shape', tr('断言必须是一个对象', 'An assertion must be an object'))]
 	const predicateId = text(assertion.predicate)
-	if (predicateId === '') return [problem('predicate_required', '断言要写谓词')]
+	if (predicateId === '') return [problem('predicate_required', tr('断言要写谓词', 'An assertion needs a predicate'))]
 	const found = findEntry(lexicon, predicateId)
-	if (found === null) return [problem('predicate_unknown', `谓词「${predicateId}」还没登记`)]
-	if (found.kind !== 'predicate') return [problem('predicate_not_predicate', `「${predicateId}」是个概念,不能当谓词用`)]
+	if (found === null) return [problem('predicate_unknown', tr(`谓词「${predicateId}」还没登记`, `Predicate "${predicateId}" does not exist yet`))]
+	if (found.kind !== 'predicate') return [problem('predicate_not_predicate', tr(`「${predicateId}」是个概念,不能当谓词用`, `"${predicateId}" is a concept and cannot be used as a predicate`))]
 	const predicate = found.entry
-	if (!isUsable(predicate)) problems.push(problem('predicate_deprecated', `谓词「${predicateId}」已废止:新断言不能再用它`))
+	if (!isUsable(predicate)) problems.push(problem('predicate_deprecated', tr(`谓词「${predicateId}」已废止:新断言不能再用它`, `Predicate "${predicateId}" is deprecated: new assertions cannot use it`)))
 	const subject = assertion.subject
-	if (!isPlainObject(subject) || text(subject.id) === '') problems.push(problem('subject_required', '断言要有主体(至少一个名称)'))
+	if (!isPlainObject(subject) || text(subject.id) === '') problems.push(problem('subject_required', tr('断言要有主体(至少一个名称)', 'An assertion needs a subject (at least a name)')))
 	else {
 		const domain = text(predicate.domain)
 		const type = text(subject.type)
 		if (domain !== '') {
-			if (type === '') problems.push(problem('subject_type_required', `谓词「${predicateId}」声明了主词域「${domain}」,主体要写明 type`))
-			else if (type !== domain) problems.push(problem('subject_type_mismatch', `主体类型「${type}」与主词域「${domain}」不一致`))
+			if (type === '') problems.push(problem('subject_type_required', tr(`谓词「${predicateId}」声明了主词域「${domain}」,主体要写明 type`, `Predicate "${predicateId}" declares the domain "${domain}", so the subject needs a type`)))
+			else if (!isKindOf(lexicon, type, domain)) problems.push(problem('subject_type_mismatch', tr(`主体类型「${type}」既不是主词域「${domain}」,也不是它的下位概念`, `Subject type "${type}" is neither the domain "${domain}" nor one of its subconcepts`)))
 		}
 		if (type !== '') {
 			const typeEntry = findEntry(lexicon, type)
-			if (typeEntry === null) problems.push(problem('subject_type_unknown', `主体类型「${type}」还没登记`))
-			else if (typeEntry.kind !== 'term') problems.push(problem('subject_type_not_term', `主体类型「${type}」是个谓词`))
-			else if (!isUsable(typeEntry.entry)) problems.push(problem('subject_type_deprecated', `主体类型「${type}」已废止`))
+			if (typeEntry === null) problems.push(problem('subject_type_unknown', tr(`主体类型「${type}」还没登记`, `Subject type "${type}" does not exist yet`)))
+			else if (typeEntry.kind !== 'term') problems.push(problem('subject_type_not_term', tr(`主体类型「${type}」是个谓词`, `Subject type "${type}" is a predicate`)))
+			else if (!isUsable(typeEntry.entry)) problems.push(problem('subject_type_deprecated', tr(`主体类型「${type}」已废止`, `Subject type "${type}" is deprecated`)))
 		}
 	}
-	problems.push(...objectProblems(predicate, assertion.object))
-	if (assertion.qualifiers !== undefined && assertion.qualifiers !== null && !isPlainObject(assertion.qualifiers)) problems.push(problem('qualifiers_shape', 'qualifiers 只能是对象(限定条件:时间、工况、适用范围)'))
+	problems.push(...objectProblems(lexicon, predicate, assertion.object))
+	if (assertion.qualifiers !== undefined && assertion.qualifiers !== null && !isPlainObject(assertion.qualifiers)) problems.push(problem('qualifiers_shape', tr('qualifiers 只能是对象(限定条件:时间、工况、适用范围)', 'qualifiers must be an object (conditions: time, setting, scope)')))
 	return problems
 }
 
@@ -296,7 +306,7 @@ export function validateAssertion(lexicon, assertion) {
  */
 export function validateAssertions(state, assertions, options = {}) {
 	if (assertions === undefined || assertions === null) return []
-	if (!Array.isArray(assertions)) return [problem('assertions_shape', 'assertions 只能是数组')]
+	if (!Array.isArray(assertions)) return [problem('assertions_shape', tr('assertions 只能是数组', 'assertions must be an array'))]
 	if (assertions.length === 0) return []
 	const stateForm = isPlainObject(state) && isPlainObject(state.lexicon)
 	const lexicon = stateForm ? state.lexicon : state
@@ -313,11 +323,11 @@ export function validateAssertions(state, assertions, options = {}) {
 	const problems = []
 	const seen = new Map()
 	for (const [index, assertion] of assertions.entries()) {
-		for (const item of validateAssertion(lexicon, assertion)) problems.push(`断言 ${index + 1} · ${item}`)
+		for (const item of validateAssertion(lexicon, assertion)) problems.push(tr(`断言 ${index + 1} · ${item}`, `Assertion ${index + 1} · ${item}`))
 		const key = `${text(assertion?.predicate)}\u0000${subjectKey(assertion)}`
 		const value = objectKey(assertion?.object)
 		if (seen.has(key) && seen.get(key) !== value) {
-			problems.push(problem('assertion_self_conflict', `同一事实里「${text(assertion?.predicate)}」在主体「${text(assertion?.subject?.id)}」上给了两个值:${seen.get(key)} 与 ${value}`))
+			problems.push(problem('assertion_self_conflict', tr(`同一事实里「${text(assertion?.predicate)}」在主体「${text(assertion?.subject?.id)}」上给了两个值:${seen.get(key)} 与 ${value}`, `Within one fact, "${text(assertion?.predicate)}" gives two values for subject "${text(assertion?.subject?.id)}": ${seen.get(key)} and ${value}`)))
 		}
 		seen.set(key, value)
 		if (entities === null || legacy) continue
@@ -341,7 +351,7 @@ export function validateAssertions(state, assertions, options = {}) {
  * 换成一个裸对象会让内核当场渲染出 `[object Object]`——那比不报更坏。
  */
 function subjectUnknown(subject) {
-	const message = new String(problem('assert_subject_unknown', `主体「${subject}」还不在实体图上:先登记这个实例(带类型与出处),或在这一批断言里让某个宾语以 instance 形态引出它`))
+	const message = new String(problem('assert_subject_unknown', tr(`主体「${subject}」还不在实体图上:先登记这个实例(带类型与出处),或在这一批断言里让某个宾语以 instance 形态引出它`, `Subject "${subject}" is not on the entity graph yet: write its entity file (with type and source) first, or introduce it as an instance object in this batch of assertions`)))
 	message.code = 'assert_subject_unknown'
 	message.subject = subject
 	return message
@@ -405,20 +415,20 @@ export function lexiconHealth(lexicon, facts) {
 	for (const term of normalized.terms) {
 		if (text(term.parent) !== '') usedTerms.add(text(term.parent))
 		const walk = termChain(normalized, term.id)
-		if (walk.cycle !== null) issues.push({ kind: 'cycle', severity: 'warning', id: term.id, detail: `is_a 父链成环(回到「${walk.cycle}」)` })
-		else if (walk.missing !== null) issues.push({ kind: 'dangling_parent', severity: 'warning', id: term.id, detail: `父概念「${walk.missing}」不在词汇里` })
+		if (walk.cycle !== null) issues.push({ kind: 'cycle', severity: 'warning', id: term.id, detail: tr(`is_a 父链成环(回到「${walk.cycle}」)`, `The is_a chain loops (back to "${walk.cycle}")`) })
+		else if (walk.missing !== null) issues.push({ kind: 'dangling_parent', severity: 'warning', id: term.id, detail: tr(`父概念「${walk.missing}」不在词汇里`, `Parent concept "${walk.missing}" is not in the vocabulary`) })
 	}
 	for (const predicate of normalized.predicates) {
 		const domain = text(predicate.domain)
 		const range = isPlainObject(predicate.range) ? predicate.range : {}
 		if (domain !== '') {
 			usedTerms.add(domain)
-			if (findEntry(normalized, domain) === null) issues.push({ kind: 'dangling_domain', severity: 'warning', id: predicate.id, detail: `主词域「${domain}」不在词汇里` })
+			if (findEntry(normalized, domain) === null) issues.push({ kind: 'dangling_domain', severity: 'warning', id: predicate.id, detail: tr(`主词域「${domain}」不在词汇里`, `Domain "${domain}" is not in the vocabulary`) })
 		}
 		const rangeTerm = text(range.term)
 		if (rangeTerm !== '') {
 			usedTerms.add(rangeTerm)
-			if (findEntry(normalized, rangeTerm) === null) issues.push({ kind: 'dangling_range', severity: 'warning', id: predicate.id, detail: `宾语域「${rangeTerm}」不在词汇里` })
+			if (findEntry(normalized, rangeTerm) === null) issues.push({ kind: 'dangling_range', severity: 'warning', id: predicate.id, detail: tr(`宾语域「${rangeTerm}」不在词汇里`, `Range "${rangeTerm}" is not in the vocabulary`) })
 		}
 	}
 	for (const fact of Array.isArray(facts) ? facts : []) {
@@ -431,21 +441,21 @@ export function lexiconHealth(lexicon, facts) {
 			if (type !== '') usedTerms.add(type)
 			const predicate = findEntry(normalized, predicateId)
 			if (predicate === null) {
-				if (!retracted) issues.push({ kind: 'unknown_predicate_in_fact', severity: 'warning', id: String(fact.id ?? ''), detail: `事实里用了没登记的谓词「${predicateId}」` })
+				if (!retracted) issues.push({ kind: 'unknown_predicate_in_fact', severity: 'warning', id: String(fact.id ?? ''), detail: tr(`事实里用了没登记的谓词「${predicateId}」`, `A fact uses the unknown predicate "${predicateId}"`) })
 				continue
 			}
-			if (predicate.entry.status === 'deprecated' && !retracted) issues.push({ kind: 'deprecated_in_use', severity: 'info', id: predicateId, detail: `已废止的「${predicateId}」仍被事实「${String(fact.id ?? '')}」引用(记录保留,不再新增)` })
+			if (predicate.entry.status === 'deprecated' && !retracted) issues.push({ kind: 'deprecated_in_use', severity: 'info', id: predicateId, detail: tr(`已废止的「${predicateId}」仍被事实「${String(fact.id ?? '')}」引用(记录保留,不再新增)`, `The deprecated "${predicateId}" is still used by fact "${String(fact.id ?? '')}" (the record stays; no new uses)`) })
 		}
 	}
 	for (const term of normalized.terms) {
 		if (term.status === 'deprecated') continue
 		if (!usedTerms.has(term.id) && !normalized.predicates.some((item) => text(item.domain) === term.id || text(item.range?.term) === term.id)) {
-			issues.push({ kind: 'unused', severity: 'info', id: term.id, detail: '还没有任何谓词或事实引用它' })
+			issues.push({ kind: 'unused', severity: 'info', id: term.id, detail: tr('还没有任何谓词或事实引用它', 'No predicate or fact uses it yet') })
 		}
 	}
 	for (const predicate of normalized.predicates) {
 		if (predicate.status === 'deprecated') continue
-		if (!usedPredicates.has(predicate.id)) issues.push({ kind: 'unused', severity: 'info', id: predicate.id, detail: '还没有任何事实用它' })
+		if (!usedPredicates.has(predicate.id)) issues.push({ kind: 'unused', severity: 'info', id: predicate.id, detail: tr('还没有任何事实用它', 'No fact uses it yet') })
 	}
 	return issues.sort((a, b) => (a.kind === b.kind ? (a.id < b.id ? -1 : 1) : a.kind < b.kind ? -1 : 1))
 }
@@ -453,9 +463,9 @@ export function lexiconHealth(lexicon, facts) {
 /**
  * **每个概念被引用了多少次**:断言主体的类型、谓词声明的主词域 / 值域、以及实体断言的类型。
  *
- * 为什么要单独一份判据:「零引用」这件事有两处读者——货架上那一节,与 `deriveKnowledge`
- * 的 `orphan_terms` 缺口。两处各算一遍,迟早会出现「货架说没人用、缺口说用了」这种
- * 同一件事两种读数;所以引用面只在这里定义一次,两边都读它。
+ * 为什么要单独一份判据:「零引用」这件事有两处读者——货架上「零引用的概念」那一节,
+ * 与同一份货架里概念那一列的引用数。两处各算一遍,迟早会出现「引用 0 却没进零引用一节」这种
+ * 同一件事两种读数;所以引用面只在这里定义一次,两边都读它。(第四阶段起它不再是缺口,只是货架读数。)
  */
 export function termUsage(lexicon, facts, entityAssertions = []) {
 	const normalized = normalizeLexicon(lexicon)
@@ -579,6 +589,19 @@ export function graphProjection(state) {
 				facts: [],
 			})
 		}
+		/**
+		 * **组成 / 属于**:实体文件放在另一个实体的目录里(`line_a/kiln_3.json`)就是它的一部分。
+		 * 节点带上 `container`(界面据此画可折叠的子图),同时出一条 `part_of` 边。
+		 */
+		const byRef = new Map([...instances.values()].map((node) => [node.ref, node]))
+		for (const entity of Array.isArray(state?.entities) ? state.entities : []) {
+			const parent = text(entity?.parent)
+			if (parent === '' || !byRef.has(parent)) continue
+			const node = instances.get(`${text(entity.type)}|${text(entity.id)}`)
+			if (node === undefined) continue
+			node.container = byRef.get(parent).id
+			edges.push({ id: `part_of:${node.id}`, kind: 'part_of', layer: 'entity', source: 'registered', predicate: null, label: tr('属于', 'part of'), from: node.id, to: node.container, status: 'asserted', level: null, fact: null, scope: null, claim: null })
+		}
 	}
 	for (const fact of facts) {
 		const status = fact?.review?.decision === 'retracted' ? 'retracted' : fact?.refuted === true ? 'refuted' : 'live'
@@ -828,7 +851,7 @@ export function applyLexiconMutation(lexicon, mutation, at) {
  * 读的人分不出哪些是可复用的语言、哪些是一次具体的记录。每节开头一句「这一节是什么」。
  *
  * **零引用的概念单独一节**:注册了却没有任何结论引用它,那它还是约定、不是已知。
- * 这一节是这句话的可见面(与 `orphan_terms` 缺口读的是同一件事)。
+ * 这一节是这句话的可见面(只是货架读数,不是缺口)。
  *
  * 第一个参数收两种形状:整份**状态**(推荐,个体那一节要有实体面)或旧的**词汇**;
  * `options.view` 传 `knowledge-view.js` 的 `knowledgeView()` 输出时,「使用」一节读的就是
@@ -850,7 +873,7 @@ export function describeDomainShelf(lexiconOrState, facts, hypotheses = [], opti
 	const entityNodes = state === null ? [] : graphProjection(state).nodes.filter((node) => node.layer === 'entity' && node.kind === 'instance')
 	/**
 	 * **引用面读同一份判据**:概念那一列用 `termUsage`(断言主体 + 主词域 / 值域),
-	 * 与 `orphan_terms` 缺口 / 零引用那一节完全同源——否则会出现「引用 0 却没进零引用一节」
+	 * 与零引用那一节完全同源——否则会出现「引用 0 却没进零引用一节」
 	 * 这种同一张表里两种读数打架的形状。谓词那一列数的是断言条数。
 	 */
 	const termRefs = termUsage(normalized, rows, entityAssertions)
@@ -866,7 +889,7 @@ export function describeDomainShelf(lexiconOrState, facts, hypotheses = [], opti
 		if (predicate !== '') predicateRefs.set(predicate, (predicateRefs.get(predicate) ?? 0) + 1)
 	}
 	const conflicts = deriveConflicts(rows, normalized)
-	/** 零引用的概念:与 `deriveKnowledge` 的 `orphan_terms` 缺口读**同一份**引用面。 */
+	/** 零引用的概念:与概念那一列读**同一份**引用面。 */
 	const orphans = terms.filter((term) => term.status !== 'deprecated' && (termRefs.get(term.id) ?? 0) === 0)
 	const lines = [
 		'# 领域本体(项目词汇)',
@@ -891,7 +914,7 @@ export function describeDomainShelf(lexiconOrState, facts, hypotheses = [], opti
 	}
 	lines.push(`## 个体(实例)(${entityNodes.length})`, '', '> 这一节是**具体物**:某个实例在某出处下成立——它带类型与出处,不是约定,也不能再当概念用。', '')
 	if (entityNodes.length === 0) {
-		lines.push('(没有实例。`RegisterInstance` 登记一个,`Assert` 让它在图上长出边——只登记节点不产边,图仍然是空的。)', '')
+		lines.push('(没有实例。在 `clear/ontology/entities/` 下写一个实体文件,它的 `relations` 让它在图上长出边——只有节点没有边,图仍然是空的。)', '')
 	} else {
 		lines.push('| id | 名称 | 类型 | 来源 | 依据 / 出处 |', '|---|---|---|---|---|')
 		for (const node of entityNodes) {
@@ -998,3 +1021,484 @@ export function describeDomainGraph(lexicon) {
 	lines.push('```', '')
 	return lines.join('\n')
 }
+
+// ═══ 工作区文件:事实与本体住在项目里 ═══════════════════════════════════════
+//
+// 会话账本只活在一次会话里,而研究要跨会话攒下来。所以「攒下来的东西」住在工作区的文件里:
+//   · `clear/knowledge/facts/<id>.json`:升格的事实,一条一个文件,只有系统写;
+//   · `clear/ontology/{concepts,relations,entities}/**.json`:本体,模型用原生文件工具直接写。
+// 内核每一拍把这两处的变化折成一条 `workspace/synced` 变更,投影从文件内容派生词汇、实体与
+// 事实——折法仍然只吃账本,文件是账本之外唯一的输入,而且进账本时就是一条可重放的事实。
+
+/** 事实文件所在的目录(相对工作区)。 */
+export const FACTS_DIR = 'clear/knowledge/facts'
+/** 本体文件树的根(相对工作区)。 */
+export const ONTOLOGY_DIR = 'clear/ontology'
+/** 本体文件树的三支:目录名 → 文件种类。 */
+export const ONTOLOGY_BRANCHES = { concepts: 'concept', relations: 'relation', entities: 'entity' }
+/** 读面有界:文件数与单个文件的字节数都有上限,超出的如实报成问题,不静默截断。 */
+export const WORKSPACE_LIMITS = { files: 2000, bytes: 65536 }
+
+/** FNV-1a(32 位):浏览器与宿主两侧都能算的同步散列,只用来比「变没变」。 */
+function hashText(value) {
+	let h = 0x811c9dc5
+	const source = String(value)
+	for (let index = 0; index < source.length; index += 1) {
+		h ^= source.charCodeAt(index)
+		h = Math.imul(h, 0x01000193) >>> 0
+	}
+	return h.toString(16).padStart(8, '0')
+}
+
+/**
+ * 一个词条**含义**的指纹:概念看释义与父概念,谓词看主词域、值域与单值性。
+ * 名字、别名、依据不进指纹——改名不改义,事实不必因此复核。
+ */
+export function definitionFingerprint(entry) {
+	if (!isPlainObject(entry)) return null
+	const meaning = 'range' in entry || 'domain' in entry ? { domain: text(entry.domain), range: isPlainObject(entry.range) ? { term: text(entry.range.term), form: text(entry.range.form), unit: text(entry.range.unit) } : null, functional: entry.functional === true } : { gloss: text(entry.gloss), parent: text(entry.parent) }
+	return `fnv:${hashText(JSON.stringify(meaning))}`
+}
+
+/** 一组断言用到的词条(谓词、主体类型、宾语类型),各自此刻的含义指纹。 */
+export function fingerprintDefinitions(lexicon, assertions, options = {}) {
+	const normalized = normalizeLexicon(lexicon)
+	const out = {}
+	const take = (id) => {
+		const key = text(id)
+		if (key === '' || key in out) return
+		const found = findEntry(normalized, key)
+		if (found !== null) out[key] = definitionFingerprint(found.entry)
+	}
+	for (const assertion of Array.isArray(assertions) ? assertions : []) {
+		take(assertion?.predicate)
+		take(assertion?.subject?.type)
+		take(assertion?.object?.type)
+	}
+	/**
+	 * **按词面挂上**(`options.text`):真跑里模型几乎不给判断写结构化断言,
+	 * 只靠断言的话事实与本体是两张互不引用的表,「定义已变」永远触发不了。
+	 * 所以升格时也按主张原文里出现的词(id / 名字 / 别名,去空白、不分大小写、至少两个字)
+	 * 把概念与关系挂上——与知识预检同一条词面规则,有界、可复核。
+	 */
+	const said = text(options?.text).replace(/\s+/g, '').toLowerCase()
+	if (said !== '') {
+		for (const entry of [...(normalized.terms ?? []), ...(normalized.predicates ?? [])]) {
+			if (entry?.status === 'deprecated') continue
+			const names = [entry?.id, entry?.label, ...(Array.isArray(entry?.aliases) ? entry.aliases : [])].map((name) => text(name).replace(/\s+/g, '').toLowerCase()).filter((name) => name.length >= 2)
+			if (names.some((name) => said.includes(name))) take(entry.id)
+		}
+	}
+	return out
+}
+
+/** 事实升格以后,它用到的词条里**含义改过或已不在**的那些 id。 */
+export function changedDefinitions(lexicon, definitions) {
+	if (!isPlainObject(definitions)) return []
+	const normalized = normalizeLexicon(lexicon)
+	const changed = []
+	for (const [id, fingerprint] of Object.entries(definitions)) {
+		const found = findEntry(normalized, id)
+		if (found === null || definitionFingerprint(found.entry) !== fingerprint) changed.push(id)
+	}
+	return changed
+}
+
+/**
+ * 工作区路径 → 它是哪种文件。认不出的返回 null(不是本体也不是事实,不归投影管)。
+ * `dirs` 是本体文件在它那一支里的上级目录(由近及远的反序:最后一个就是直接上级)。
+ */
+export function classifyWorkspacePath(path) {
+	const parts = String(path ?? '').replace(/\\/g, '/').split('/').filter((part) => part !== '' && part !== '.')
+	if (parts.length === 0 || !parts.at(-1).endsWith('.json')) return null
+	const id = parts.at(-1).slice(0, -'.json'.length)
+	const facts = FACTS_DIR.split('/')
+	if (parts.length === facts.length + 1 && facts.every((part, index) => parts[index] === part)) return { kind: 'fact', id, dirs: [] }
+	const root = ONTOLOGY_DIR.split('/')
+	if (parts.length >= root.length + 2 && root.every((part, index) => parts[index] === part)) {
+		const kind = ONTOLOGY_BRANCHES[parts[root.length]]
+		if (kind === undefined) return null
+		return { kind, id, dirs: parts.slice(root.length + 1, -1) }
+	}
+	return null
+}
+
+/**
+ * 事实文件 → 事实行(与 `fact/promoted` 折出来的同形)。复核写在文件的 `status` / `review` 上。
+ */
+export function factFromFile(data, path) {
+	if (!isPlainObject(data) || text(data.id) === '' || text(data.text) === '') return null
+	const review = isPlainObject(data.review) ? { decision: data.review.decision === 'retracted' ? 'retracted' : 'kept', reason: data.review.reason ?? null, at: data.review.at ?? null, by: data.review.by ?? 'user' } : null
+	return {
+		id: text(data.id),
+		goal: data.goal ?? null,
+		hypothesis: data.hypothesis ?? null,
+		text: String(data.text),
+		scope: data.scope ?? null,
+		level: data.level ?? null,
+		evidence: Array.isArray(data.evidence) ? data.evidence : [],
+		assertions: Array.isArray(data.assertions) ? clone(data.assertions) : null,
+		definitions: isPlainObject(data.definitions) ? clone(data.definitions) : null,
+		path: path ?? null,
+		at: typeof data.at === 'number' ? data.at : null,
+		review,
+	}
+}
+
+// ═══ 本体文件树:字段、单文件校验、从文件折出词汇与实体 ═════════════════════════
+//
+// 本体由模型用原生文件工具直接写,住在 `clear/ontology/{concepts,relations,entities}/` 下:
+//   · 命名规则只有一条:`X.json` 描述节点 X,它的子节点放在同级的 `X/` 目录里;
+//   · 概念目录嵌套 = is_a,实体目录嵌套 = 组成 / 属于,关系目录只是分组;
+//   · 身份是 id(= 文件名),位置是目录。引用只用 id,所以整支目录挪走就是重新分层,引用不断。
+// 校验分三道:写入时查**单个文件**(这里的 `checkOntologyFile`,不过就拒写);读取时查**跨文件**
+// (`materializeOntology` 的 problems,只提示、有问题的节点或边不进图);升格时把断言涉及的
+// 节点全查一遍(就是 `validateAssertions`,不过就不升格)。
+
+/** 实体 id 比概念宽:具体物的名字常带大写与短横(`V-JEPA_2`),但仍是一个文件名能装下的键。 */
+const ENTITY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$/
+const PROVENANCE_KINDS = ['url', 'named', 'backref']
+const ONTOLOGY_STATUS = ['active', 'deprecated']
+
+/**
+ * 三种本体文件的字段定义。内核把它铺成 `clear/ontology/SCHEMA.json`(只读),
+ * 写入时的校验与这份定义是同一份:字段在这里改,两边一起变。
+ */
+export const ONTOLOGY_SCHEMA = bilingual({
+	about: [
+		'本体文件的字段定义(系统铺设,只读)。命名规则:X.json 描述节点 X,它的子节点放在同级的 X/ 目录里;id 必须等于文件名。概念目录嵌套 = is_a;实体目录嵌套 = 组成 / 属于;关系可以平铺,也可以分目录(只是分组)。引用一律只写 id,挪目录不断引用。写入时只查单个文件;引用断了、类型对不上等跨文件问题在卡片上提示,升格时才拦。',
+		'Field definitions for ontology files (laid down by the system, read-only). Naming: X.json describes node X, and its children live in the sibling X/ directory; id must equal the file name. Nested concept directories mean is_a; nested entity directories mean part-of; relations can be flat or grouped in directories (grouping only). References use ids only, so moving directories never breaks them. Writes check a single file; cross-file problems such as broken references or type mismatches are flagged on the card and only block at promotion.',
+	],
+	concept: {
+		where: 'clear/ontology/concepts/**/<id>.json',
+		required: {
+			id: ['slug:小写字母开头,字母/数字/下划线,≤40,等于文件名', 'slug: starts with a lowercase letter; letters, digits, underscores; ≤40; equals the file name'],
+			label: ['给人看的名字', 'the human-readable name'],
+			gloss: ['一句话释义:它指什么', 'one-sentence gloss: what it refers to'],
+		},
+		optional: {
+			aliases: ['别名数组', 'array of aliases'],
+			basis: ['依据:哪份材料让这个词成立', 'basis: which material establishes this term'],
+			status: 'active | deprecated',
+			replaced_by: ['废止后由哪个 id 接替', 'the id that replaces it once deprecated'],
+			note: ['备注', 'note'],
+		},
+		example: {
+			id: 'jepa',
+			label: ['联合嵌入预测架构', 'Joint-embedding predictive architecture'],
+			aliases: ['JEPA'],
+			gloss: ['在表示空间里从上下文预测目标的表示,不还原像素', 'predicts the representation of a target from context in representation space, without reconstructing pixels'],
+			basis: 'LeCun 2022',
+		},
+	},
+	relation: {
+		where: 'clear/ontology/relations/**/<id>.json',
+		required: {
+			id: ['slug,同概念(概念与关系共用一个 id 空间)', 'slug, as for concepts (concepts and relations share one id space)'],
+			label: ['给人看的名字', 'the human-readable name'],
+			range: [
+				`宾语是哪种东西:一个概念 id(宾语是该概念的实体),或 {"form": ${VALUE_FORMS.map((form) => `"${form}"`).join(' | ')}, "unit"?: "..."}(宾语是字面值)`,
+				`what the object is: a concept id (the object is an entity of that concept), or {"form": ${VALUE_FORMS.map((form) => `"${form}"`).join(' | ')}, "unit"?: "..."} (the object is a literal value)`,
+			],
+		},
+		optional: {
+			gloss: ['一句话释义', 'one-sentence gloss'],
+			domain: ['主语必须是哪个概念(下位概念也算)', 'which concept the subject must be (subconcepts count)'],
+			functional: ['true = 单值:同一主语只能有一个取值,两个不同取值会被报成冲突', 'true = single-valued: one value per subject; two different values are reported as a conflict'],
+			basis: ['依据', 'basis'],
+			status: 'active | deprecated',
+			replaced_by: ['接替的 id', 'the replacing id'],
+			note: ['备注', 'note'],
+		},
+		example: { id: 'derived_from', label: ['衍生自', 'derived from'], domain: 'method', range: 'method', functional: false },
+	},
+	entity: {
+		where: 'clear/ontology/entities/**/<id>.json',
+		required: {
+			id: ['字母或数字开头,字母/数字/下划线/短横,≤60,等于文件名', 'starts with a letter or digit; letters, digits, underscores, hyphens; ≤60; equals the file name'],
+			label: ['给人看的名字', 'the human-readable name'],
+			type: ['它是哪个概念的实体(概念 id)', 'which concept it is an entity of (concept id)'],
+			basis: ['依据:哪份材料让它可以被指认', 'basis: which material lets it be identified'],
+			provenance: [
+				`出处 {"kind": ${PROVENANCE_KINDS.map((kind) => `"${kind}"`).join(' | ')}, "ref": "链接 / 文献名 / 工作区里的文件"}`,
+				`source {"kind": ${PROVENANCE_KINDS.map((kind) => `"${kind}"`).join(' | ')}, "ref": "link / paper name / file in the workspace"}`,
+			],
+		},
+		optional: {
+			aliases: ['别名数组', 'array of aliases'],
+			relations: [
+				'它对外的关系,每条一个出处:{"predicate": 关系 id, "object": 另一个实体的 id} 或 {"predicate": 关系 id, "value": 字面值, "unit"?: 单位};两种都要带 "evidence": {"kind", "ref"}',
+				'its outgoing relations, each with a source: {"predicate": relation id, "object": another entity id} or {"predicate": relation id, "value": literal, "unit"?: unit}; both need "evidence": {"kind", "ref"}',
+			],
+			note: ['备注', 'note'],
+		},
+		example: {
+			id: 'v_jepa_2_ac',
+			label: 'V-JEPA 2-AC',
+			type: 'world_model',
+			basis: ['动作条件的 V-JEPA 2', 'action-conditioned V-JEPA 2'],
+			provenance: { kind: 'named', ref: 'sources/vjepa2.md' },
+			relations: [
+				{ predicate: 'derived_from', object: 'v_jepa_2', evidence: { kind: 'named', ref: ['V-JEPA 2 论文', 'V-JEPA 2 paper'] } },
+				{ predicate: 'released_year', value: 2025, evidence: { kind: 'named', ref: ['V-JEPA 2 论文', 'V-JEPA 2 paper'] } },
+			],
+		},
+	},
+})
+
+const FIELDS = {
+	concept: ['id', 'label', 'gloss', 'aliases', 'basis', 'status', 'replaced_by', 'note'],
+	relation: ['id', 'label', 'gloss', 'domain', 'range', 'functional', 'basis', 'status', 'replaced_by', 'note'],
+	entity: ['id', 'label', 'type', 'basis', 'provenance', 'aliases', 'relations', 'note'],
+}
+const RELATION_FIELDS = ['predicate', 'object', 'value', 'unit', 'evidence', 'note']
+
+/** 一个出处对象的形状问题(没有就返回 null)。 */
+function evidenceShape(value, at) {
+	if (!isPlainObject(value)) return tr(`${at}要是 {"kind", "ref"} 对象`, `${at} must be a {"kind", "ref"} object`)
+	if (!PROVENANCE_KINDS.includes(text(value.kind))) return tr(`${at}.kind 只能是 ${PROVENANCE_KINDS.join(' / ')}`, `${at}.kind must be ${PROVENANCE_KINDS.join(' / ')}`)
+	if (text(value.ref) === '') return tr(`${at}.ref 不能为空`, `${at}.ref cannot be empty`)
+	return null
+}
+
+/**
+ * **第一道校验:单个文件**。给路径与解析好的内容(或原文),返回问题清单(空 = 通过)。
+ * 只查这一个文件自己:JSON 能解析、字段齐且类型对、id 等于文件名、枚举取值合法。
+ * 引用指向的东西在不在**不查**——模型改一组文件时中间状态必然暂时不一致,
+ * 这时就查跨文件引用,等于逼它按固定顺序写。
+ */
+export function checkOntologyFile(path, content) {
+	const place = classifyWorkspacePath(path)
+	if (place === null || place.kind === 'fact') return [tr(`不是本体文件的位置:本体文件要放在 ${ONTOLOGY_DIR}/{concepts,relations,entities}/ 下,扩展名 .json`, `Not an ontology file location: ontology files go under ${ONTOLOGY_DIR}/{concepts,relations,entities}/ with a .json extension`)]
+	let data = content
+	if (typeof content === 'string') {
+		try {
+			data = JSON.parse(content)
+		} catch (error) {
+			return [tr(`不是合法 JSON:${String(error?.message ?? error).slice(0, 160)}`, `Not valid JSON: ${String(error?.message ?? error).slice(0, 160)}`)]
+		}
+	}
+	if (!isPlainObject(data)) return [tr('文件内容要是一个 JSON 对象', 'The file content must be a JSON object')]
+	const kind = place.kind
+	const problems = []
+	const pattern = kind === 'entity' ? ENTITY_ID_PATTERN : ID_PATTERN
+	if (!pattern.test(place.id)) problems.push(
+			kind === 'entity'
+				? tr(`文件名「${place.id}」不能当实体 id:字母或数字开头,只用字母/数字/下划线/短横,≤60`, `File name "${place.id}" cannot be an entity id: start with a letter or digit; letters, digits, underscores, hyphens only; ≤60`)
+				: tr(`文件名「${place.id}」不能当 id:小写字母开头,只用小写字母/数字/下划线,≤40`, `File name "${place.id}" cannot be an id: start with a lowercase letter; lowercase letters, digits, underscores only; ≤40`),
+		)
+	if (data.id !== undefined && text(data.id) !== place.id) problems.push(tr(`id「${text(data.id)}」要等于文件名「${place.id}」(身份就是文件名;改 id 就是改文件名)`, `id "${text(data.id)}" must equal the file name "${place.id}" (identity is the file name; changing the id means renaming the file)`))
+	const extra = Object.keys(data).filter((key) => !FIELDS[kind].includes(key))
+	if (extra.length > 0) {
+		const kindWord = kind === 'concept' ? tr('概念', 'concepts') : kind === 'relation' ? tr('关系', 'relations') : tr('实体', 'entities')
+		problems.push(tr(`不认识的字段:${extra.join('、')}(${kindWord}可用:${FIELDS[kind].join('、')};详见 ${ONTOLOGY_DIR}/SCHEMA.json)`, `Unknown fields: ${extra.join(', ')} (${kindWord} allow: ${FIELDS[kind].join(', ')}; see ${ONTOLOGY_DIR}/SCHEMA.json)`))
+	}
+	if (text(data.label) === '') problems.push(tr('label 必填:给人看的名字', 'label is required: the human-readable name'))
+	if (data.aliases !== undefined && (!Array.isArray(data.aliases) || data.aliases.some((alias) => typeof alias !== 'string'))) problems.push(tr('aliases 只能是字符串数组', 'aliases must be an array of strings'))
+	for (const key of ['basis', 'gloss', 'note', 'replaced_by']) if (data[key] !== undefined && data[key] !== null && typeof data[key] !== 'string') problems.push(tr(`${key} 只能是字符串`, `${key} must be a string`))
+	if (data.status !== undefined && !ONTOLOGY_STATUS.includes(text(data.status))) problems.push(tr(`status 只能是 ${ONTOLOGY_STATUS.join(' / ')}`, `status must be ${ONTOLOGY_STATUS.join(' / ')}`))
+	if (kind === 'concept' && text(data.gloss) === '') problems.push(tr('gloss 必填:一句话说清它指什么,不然引用它的人各读各的', 'gloss is required: one sentence on what it refers to, or everyone who cites it reads it differently'))
+	if (kind === 'relation') {
+		if (data.domain !== undefined && data.domain !== null && !ID_PATTERN.test(text(data.domain))) problems.push(tr('domain 要是一个概念 id', 'domain must be a concept id'))
+		if (data.functional !== undefined && typeof data.functional !== 'boolean') problems.push(tr('functional 只能是 true / false', 'functional must be true / false'))
+		const range = data.range
+		if (typeof range === 'string') {
+			if (!ID_PATTERN.test(text(range))) problems.push(tr('range 写成字符串时要是一个概念 id', 'range given as a string must be a concept id'))
+		} else if (isPlainObject(range)) {
+			const form = text(range.form)
+			const term = text(range.term)
+			if (form !== '' && term !== '') problems.push(tr('range 只能二选一:一个概念 id,或 {"form"}', 'range is one or the other: a concept id, or {"form"}'))
+			else if (term !== '') {
+				if (!ID_PATTERN.test(term)) problems.push(tr('range.term 要是一个概念 id', 'range.term must be a concept id'))
+			} else if (!VALUE_FORMS.includes(form)) problems.push(tr(`range.form 只能是 ${VALUE_FORMS.join(' / ')}`, `range.form must be ${VALUE_FORMS.join(' / ')}`))
+			if (range.unit !== undefined && typeof range.unit !== 'string') problems.push(tr('range.unit 只能是字符串', 'range.unit must be a string'))
+		} else problems.push(tr(`range 必填:一个概念 id(宾语是实体),或 {"form": ${VALUE_FORMS.join(' | ')}}(宾语是字面值)`, `range is required: a concept id (the object is an entity), or {"form": ${VALUE_FORMS.join(' | ')}} (the object is a literal value)`))
+	}
+	if (kind === 'entity') {
+		if (!ID_PATTERN.test(text(data.type))) problems.push(tr('type 必填:它是哪个概念的实体(概念 id)', 'type is required: which concept it is an entity of (concept id)'))
+		if (text(data.basis) === '') problems.push(tr('basis 必填:实体是观测,要说清哪份材料让它可以被指认', 'basis is required: an entity is an observation, so say which material identifies it'))
+		const shape = evidenceShape(data.provenance, 'provenance')
+		if (shape !== null) problems.push(tr(`${shape}(实体没有出处就进不了图)`, `${shape} (an entity without a source cannot enter the graph)`))
+		if (data.relations !== undefined) {
+			if (!Array.isArray(data.relations)) problems.push(tr('relations 只能是数组', 'relations must be an array'))
+			else
+				data.relations.forEach((relation, index) => {
+					const at = `relations[${index}]`
+					if (!isPlainObject(relation)) return problems.push(tr(`${at} 要是对象`, `${at} must be an object`))
+					const unknown = Object.keys(relation).filter((key) => !RELATION_FIELDS.includes(key))
+					if (unknown.length > 0) problems.push(tr(`${at} 不认识的字段:${unknown.join('、')}(可用:${RELATION_FIELDS.join('、')})`, `${at} has unknown fields: ${unknown.join(', ')} (allowed: ${RELATION_FIELDS.join(', ')})`))
+					if (!ID_PATTERN.test(text(relation.predicate))) problems.push(tr(`${at}.predicate 要是一个关系 id`, `${at}.predicate must be a relation id`))
+					const hasObject = relation.object !== undefined
+					const hasValue = relation.value !== undefined
+					if (hasObject === hasValue) problems.push(tr(`${at} 要么给 object(另一个实体的 id),要么给 value(字面值),二选一`, `${at} needs exactly one of object (another entity id) or value (a literal)`))
+					else if (hasObject && !ENTITY_ID_PATTERN.test(text(relation.object))) problems.push(tr(`${at}.object 要是一个实体 id`, `${at}.object must be an entity id`))
+					if (relation.unit !== undefined && typeof relation.unit !== 'string') problems.push(tr(`${at}.unit 只能是字符串`, `${at}.unit must be a string`))
+					const evidence = evidenceShape(relation.evidence, `${at}.evidence`)
+					if (evidence !== null) problems.push(tr(`${evidence}(一条关系一个出处;没有出处的话是意见,不是观测)`, `${evidence} (one source per relation; without a source it is an opinion, not an observation)`))
+				})
+		}
+	}
+	return problems
+}
+
+/** 关系文件的值域 → 词汇里的值域形状(`{term}` 或 `{form, unit?}`)。 */
+function rangeOf(range) {
+	if (typeof range === 'string') return { term: text(range) }
+	if (!isPlainObject(range)) return null
+	if (text(range.term) !== '') return { term: text(range.term) }
+	return text(range.unit) === '' ? { form: text(range.form) } : { form: text(range.form), unit: text(range.unit) }
+}
+
+/**
+ * **从工作区文件折出本体**(第二道校验在这里):词汇(概念 + 关系)、实体、实体断言、问题清单。
+ *
+ * 读的是 `state.workspace.files`(路径 → `{digest, data|error}`),所以它是纯函数:
+ * 同一批文件永远折出同一张图。跨文件的问题只**提示**,有问题的节点或边不进图——
+ * 图上画出来的每一样东西都是这门语言认得的。
+ */
+export function materializeOntology(files) {
+	const problems = []
+	const flag = (path, id, code, detail, severity = 'warning') => problems.push({ path, id, code, detail, severity })
+	const entries = Object.entries(isPlainObject(files) ? files : {})
+		.map(([path, file]) => ({ path, file, place: classifyWorkspacePath(path) }))
+		.filter((item) => item.place !== null && item.place.kind !== 'fact')
+		.sort((a, b) => (a.path < b.path ? -1 : 1))
+	const terms = []
+	const predicates = []
+	const entityRows = []
+	const ids = new Map()
+	for (const { path, file, place } of entries) {
+		if (file?.error !== undefined && file?.error !== null) {
+			flag(path, place.id, 'file_unreadable', String(file.error), 'error')
+			continue
+		}
+		const shape = checkOntologyFile(path, file?.data)
+		if (shape.length > 0) {
+			flag(path, place.id, 'file_invalid', shape.join(';'), 'error')
+			continue
+		}
+		const data = file.data
+		/** 概念与关系共用一个 id 空间(断言里谓词与类型都是这里的名字);实体自成一个空间。 */
+		const space = place.kind === 'entity' ? 'entity' : 'lexicon'
+		const key = `${space}:${place.id}`
+		if (ids.has(key)) {
+			flag(path, place.id, 'duplicate_id', tr(`id「${place.id}」重复了:${ids.get(key)} 已经用了它(这一份不进图)`, `Duplicate id "${place.id}": ${ids.get(key)} already uses it (this one stays off the graph)`), 'error')
+			continue
+		}
+		ids.set(key, path)
+		const status = text(data.status) === 'deprecated' ? 'deprecated' : 'admitted'
+		const parent = place.dirs.length === 0 ? null : place.dirs.at(-1)
+		if (place.kind === 'concept') {
+			terms.push({ id: place.id, label: text(data.label), gloss: text(data.gloss), aliases: Array.isArray(data.aliases) ? data.aliases.map(String) : [], parent, status, basis: text(data.basis) || null, replacedBy: text(data.replaced_by) || null, path })
+		} else if (place.kind === 'relation') {
+			predicates.push({ id: place.id, label: text(data.label), gloss: text(data.gloss), domain: text(data.domain) || null, range: rangeOf(data.range), functional: data.functional === true, status, basis: text(data.basis) || null, replacedBy: text(data.replaced_by) || null, path })
+		} else {
+			entityRows.push({ place, path, data, parent })
+		}
+	}
+	const lexicon = { terms, predicates }
+	for (const term of terms) {
+		if (term.parent === null) continue
+		const found = findEntry(lexicon, term.parent)
+		if (found === null || found.kind !== 'term') flag(term.path, term.id, 'dangling_parent', tr(`它放在目录「${term.parent}/」里,但没有概念文件 ${term.parent}.json:上一层不成立`, `It sits in directory "${term.parent}/" but there is no concept file ${term.parent}.json: the level above does not hold`), 'info')
+	}
+	for (const predicate of predicates) {
+		if (predicate.domain !== null && findEntry(lexicon, predicate.domain)?.kind !== 'term') flag(predicate.path, predicate.id, 'dangling_domain', tr(`主语概念「${predicate.domain}」不存在`, `Subject concept "${predicate.domain}" does not exist`))
+		const term = text(predicate.range?.term)
+		if (term !== '' && findEntry(lexicon, term)?.kind !== 'term') flag(predicate.path, predicate.id, 'dangling_range', tr(`宾语概念「${term}」不存在`, `Object concept "${term}" does not exist`))
+	}
+	const entities = []
+	const entityById = new Map()
+	for (const { place, path, data, parent } of entityRows) {
+		const type = text(data.type)
+		const typeEntry = findEntry(lexicon, type)
+		if (typeEntry === null || typeEntry.kind !== 'term') {
+			flag(path, place.id, 'entity_type_unknown', tr(`类型「${type}」不是已有的概念:先写概念文件,这个实体才进图`, `Type "${type}" is not an existing concept: write the concept file first, then this entity enters the graph`))
+			continue
+		}
+		const entity = { id: place.id, type, label: text(data.label), basis: text(data.basis), provenance: { kind: text(data.provenance.kind), ref: text(data.provenance.ref) }, aliases: Array.isArray(data.aliases) ? data.aliases.map(String) : [], parent, path, relations: Array.isArray(data.relations) ? data.relations : [] }
+		entities.push(entity)
+		entityById.set(entity.id, entity)
+	}
+	const entityAssertions = []
+	const functionalSeen = new Map()
+	for (const entity of entities) {
+		if (entity.parent !== null && !entityById.has(entity.parent)) flag(entity.path, entity.id, 'dangling_container', tr(`它放在目录「${entity.parent}/」里,但没有实体文件 ${entity.parent}.json:「属于」这一层不成立`, `It sits in directory "${entity.parent}/" but there is no entity file ${entity.parent}.json: the part-of level does not hold`), 'info')
+		entity.relations.forEach((relation, index) => {
+			const predicateId = text(relation.predicate)
+			const found = findEntry(lexicon, predicateId)
+			const where = tr(`${entity.id} 的第 ${index + 1} 条关系`, `relation ${index + 1} of ${entity.id}`)
+			if (found === null || found.kind !== 'predicate') {
+				flag(entity.path, entity.id, 'relation_unknown', tr(`${where}:关系「${predicateId}」没有关系文件`, `${where}: relation "${predicateId}" has no relation file`))
+				return
+			}
+			let object
+			if (relation.object !== undefined) {
+				const target = entityById.get(text(relation.object))
+				if (target === undefined) {
+					flag(entity.path, entity.id, 'dangling_object', tr(`${where}:宾语实体「${text(relation.object)}」不存在(或它自己没进图)`, `${where}: object entity "${text(relation.object)}" does not exist (or is itself off the graph)`))
+					return
+				}
+				object = { kind: 'instance', value: target.id, type: target.type }
+			} else {
+				const form = text(found.entry.range?.form) || (typeof relation.value === 'number' ? 'quantity' : 'statement')
+				object = { kind: form, value: relation.value }
+				const unit = text(relation.unit) || text(found.entry.range?.unit)
+				if (unit !== '') object.unit = unit
+			}
+			const assertion = { id: `${entity.id}#${index + 1}`, subject: { id: entity.id, type: entity.type }, predicate: predicateId, object, evidence: { kind: text(relation.evidence.kind), ref: text(relation.evidence.ref) } }
+			const invalid = validateAssertion(lexicon, assertion)
+			if (invalid.length > 0) {
+				flag(entity.path, entity.id, 'relation_invalid', `${where}:${invalid.join(';')}`)
+				return
+			}
+			if (found.entry.functional === true) {
+				const key = `${predicateId}\u0000${entity.id}`
+				const value = objectKey(object)
+				if (functionalSeen.has(key) && functionalSeen.get(key) !== value) flag(entity.path, entity.id, 'functional_conflict', tr(`${where}:「${predicateId}」是单值关系,${entity.id} 却有两个取值(${functionalSeen.get(key)} 与 ${value})`, `${where}: "${predicateId}" is single-valued, but ${entity.id} has two values (${functionalSeen.get(key)} and ${value})`))
+				functionalSeen.set(key, value)
+			}
+			entityAssertions.push(assertion)
+		})
+	}
+	return {
+		lexicon,
+		entities: entities.map(({ relations, ...entity }) => entity),
+		entityAssertions,
+		problems,
+	}
+}
+
+/**
+ * **本体大纲**(卡片上那一段):概念树与实体树的前两层,每一支标上它底下有多少个节点;
+ * 关系只报总数。模型一眼看得出哪里深、哪里平、哪些节点还散在顶层——
+ * 「让模型感受到结构」的全部做法就是这一段,有上限,细节它自己去读文件。
+ */
+export function ontologyOutline(state, limit = 12) {
+	const lexicon = normalizeLexicon(state?.lexicon)
+	const entities = Array.isArray(state?.entities) ? state.entities : []
+	const tree = (nodes, parentOf) => {
+		const children = new Map()
+		for (const node of nodes) {
+			const parent = parentOf(node)
+			const key = parent !== null && nodes.some((item) => item.id === parent) ? parent : null
+			children.set(key, [...(children.get(key) ?? []), node.id])
+		}
+		const count = (id) => (children.get(id) ?? []).reduce((sum, child) => sum + 1 + count(child), 0)
+		const roots = (children.get(null) ?? []).sort()
+		const shown = roots.slice(0, limit).map((id) => {
+			const kids = (children.get(id) ?? []).sort()
+			const below = count(id)
+			const sub = kids.slice(0, 6).map((kid) => (count(kid) > 0 ? `${kid}(${count(kid)})` : kid))
+			return below === 0 ? id : tr(`${id}(${below}):${sub.join('、')}${kids.length > 6 ? ` 等 ${kids.length} 支` : ''}`, `${id} (${below}): ${sub.join(', ')}${kids.length > 6 ? ` and more, ${kids.length} branches` : ''}`)
+		})
+		return { total: nodes.length, roots: roots.length, lines: shown, more: Math.max(0, roots.length - limit) }
+	}
+	return {
+		concepts: tree(lexicon.terms, (term) => text(term.parent) || null),
+		relations: lexicon.predicates.length,
+		entities: tree(entities, (entity) => text(entity.parent) || null),
+		assertions: Array.isArray(state?.entityAssertions) ? state.entityAssertions.length : 0,
+		problems: Array.isArray(state?.ontologyProblems) ? state.ontologyProblems.length : 0,
+	}
+}