clearai-dsh 0.1.7 → 0.2.1

package/lib/fold.js

@@ -16,6 +16,7 @@
  * 与预设内核的契约:`meta = { kind: 'clearai', v: 1, mutation: { t, ... } }`。
  * 词汇表由本文件的 `applyMutation` 定义;预设侧只负责产出,不负责解释。
  */
+import { applyLexiconMutation, deriveConflicts, emptyLexicon, formatAssertion, graphProjection, lexiconHealth, normalizeLexicon, objectKey, VALUE_FORMS } from './domain-language.js'
 
 /** 世界线分支状态的秩。秩只增;一旦出现 adopted,整个分叉的分支状态冻结。 */
 const BRANCH_RANK = { exploring: 0, evaluated: 1, adopted: 2, pruned: 2 }
@@ -35,9 +36,12 @@ export const MUTATION_KIND = 'clearai'
  *   v6 → v7:那条账多一个 `label`:我们最后一次在平台对象上写下的那句身份文本。
  *           它的用途只有一个:**分清「身份变了」与「人改写过了」**——前者我们换窗口,
  *           后者以人为准、一个字都不动。没有它,这两种情形在外部长得一模一样。
+ *   v9 → v10:多了「领域词汇」(`lexicon`)与类型化事实:断言进 `fact.promoted`,
+ *           事实与假设按 id 关联(旧账本仍按主张文本)。旧日志折出来的 `lexicon` 是空表,
+ *           没有断言的事实照旧可读——形状变了才 +1,不是语义变了才 +1。
  * 投影缓存按版本判定,所以旧缓存会被丢弃、从日志重折一遍——用量是**从日志折出来的**,重折才完整。
  */
-export const STATE_VERSION = 9
+export const STATE_VERSION = 10
 
 /**
  * **只留台账、不折进视图**的变更类型(词汇表的另一半)。
@@ -108,6 +112,15 @@ export function emptyState() {
 		 * 抄一份就会漂移,而漂移的界面比没有界面更坏。它与目录同一条纪律:变了才发。
 		 */
 		ontology: null,
+		/**
+		 * **领域词汇**(概念与谓词)与它的读面。
+		 *
+		 * 为什么它与上面的 `ontology` 是两个字段:`ontology` 是**过程本体**的形状
+		 * (插件自己的后台流转结构,随版本走、不可编辑);`lexicon` 是**领域本体**的内容
+		 * (项目自己的语言:概念、谓词、值形态),由账本里的本体事件折出来、可增删改。
+		 * 名字分开,是因为权威不同——一个随发布变,一个随项目长。
+		 */
+		lexicon: emptyLexicon(),
 		/**
 		 * **续跑窗口的账**:我们向平台说过的那句话——「这个窗口归我布防 / 我按了暂停 /
 		 * 我收兵了 / 它不在了而那不是我们干的」。形状见 `applyMutation` 的 `continuation/set`。
@@ -196,6 +209,18 @@ function clone(value) {
 	return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * 假设 ↔ 事实的关联:优先按 `hypothesis` id(新账本),旧账本按主张文本——
+ * 那时的事实还没有那个字段。顺序不能反:id 是身份,文本只是当时的措辞,
+ * 改一次措辞就断链的关联迟早会把「这条假设已被升格」读成「还没升格」。
+ */
+function factFromHypothesis(facts, goalId, hypothesisId, claim) {
+	return (Array.isArray(facts) ? facts : []).some((fact) => {
+		if (typeof fact?.hypothesis === 'string' && fact.hypothesis !== '') return fact.hypothesis === hypothesisId
+		return fact?.goal === goalId && String(fact.text ?? '') === String(claim ?? '')
+	})
+}
+
 function appendSteps(plan, rawSteps) {
 	for (const raw of rawSteps) {
 		plan.steps.push({
@@ -260,13 +285,38 @@ export function applyMutation(state, mutation) {
 				}
 			}
 			for (const hypothesis of mutation.hypotheses ?? []) {
+				/**
+				 * **一个 id 只对应一条主张,永远**(与领域词汇那条「语义变化必须换 id」同一条纪律)。
+				 *
+				 * 真跑里这条缺失的代价很大:修订目标时内核给**同一句话**发了新 id,而这里照单全收,
+				 * 于是一张运行态卡上出现 4 条主张的 6~8 行读数——同一句话挂着两个 id、各报一个状态
+				 * (一个「已支持」、另一个「未触及」),模型得自己去调和两份打架的读数。
+				 *
+				 * 所以这里按 id **upsert**,但**只更新不改变身份的那些字段**(断言、推翻条件、版本):
+				 * 修订时给一条老命题补上断言是正当的更新;而换掉它的 `claim` 就是拿旧 id 说新话——
+				 * 那一律拒(内核已在源头保证换主张必换 id),终态(`superseded` / `refuted`)同样黏住。
+				 */
+				const claim = String(hypothesis.claim ?? '')
+				const known = next.hypotheses.find((item) => item.id === hypothesis.id)
+				if (known !== undefined) {
+					if (String(known.claim ?? '') !== claim) continue
+					known.refute_when = hypothesis.refute_when
+					known.version = hypothesis.version ?? known.version
+					if (Array.isArray(hypothesis.assertions)) known.assertions = clone(hypothesis.assertions)
+					continue
+				}
 				next.hypotheses.push({
 					id: hypothesis.id,
 					goal: mutation.id,
-					claim: hypothesis.claim,
+					claim,
 					refute_when: hypothesis.refute_when,
 					status: 'proposed',
 					version: hypothesis.version ?? 1,
+					/**
+					 * **类型化断言随假设走**:登记时校验、升格时定型。
+					 * 不写断言照旧成立(宽松+校验);写了就是「这条主张用这门语言怎么说」。
+					 */
+					assertions: Array.isArray(hypothesis.assertions) ? clone(hypothesis.assertions) : null,
 					at,
 				})
 			}
@@ -290,7 +340,7 @@ export function applyMutation(state, mutation) {
 			 * 前者说这条猜想错了,后者说这条猜想不再被提。后者不该改写前者。
 			 * 已经升格成事实的(`claim` 出现在 facts 里)同理:事实在,假设就不能被悄悄换掉。
 			 */
-			const promoted = next.facts.some((fact) => fact.goal === mutation.goal && fact.text === mutation.claim)
+			const promoted = factFromHypothesis(next.facts, mutation.goal, mutation.id, mutation.claim)
 			const row = next.hypotheses.find((item) => item.id === mutation.id && item.status !== 'superseded' && item.status !== 'refuted' && !promoted)
 			if (row !== undefined) {
 				row.status = 'superseded'
@@ -475,15 +525,19 @@ export function applyMutation(state, mutation) {
 			/**
 			 * 事实的字段:`scope` 是它的**边界**(推翻条件)——没有边界的事实下一轮没人敢用;
 			 * `level` 是它被支持到哪一级(判者可查)。两者都来自升格那一刻的假设,不事后补。
+			 * `hypothesis` 是产出它的那条假设(新账本才有),`assertions` 是类型化断言——
+			 * 没提供就是 null:**不提供放行,提供即严校**(校验发生在落账之前)。
 			 */
 			next.facts.push({
 				id: mutation.id,
 				goal: mutation.goal,
+				hypothesis: mutation.hypothesis ?? null,
 				text: mutation.text,
 				scope: mutation.scope ?? null,
 				level: mutation.level ?? null,
 				evidence: mutation.evidence ?? [],
 				path: mutation.path ?? null,
+				assertions: Array.isArray(mutation.assertions) ? clone(mutation.assertions) : null,
 				at,
 			})
 			break
@@ -748,6 +802,22 @@ export function applyMutation(state, mutation) {
 			}
 			break
 		}
+		/**
+		 * **领域词汇的六个事件**:接纳 / 版本化修订 / 黏性废止(概念与谓词各三条)。
+		 *
+		 * 折法在这里只做解释:把事件折成 `lexicon`。校验(引用是否存在、形状对不对、
+		 * 语义变化有没有偷偷走修订)全部发生在**落账之前**——预设侧的工具与宿主路由
+		 * 用的是 `domain-language.js` 的同一份判据;折法不重复判一遍,否则两份判据必然漂。
+		 */
+		case 'ontology/term_added':
+		case 'ontology/predicate_added':
+		case 'ontology/term_revised':
+		case 'ontology/predicate_revised':
+		case 'ontology/term_deprecated':
+		case 'ontology/predicate_deprecated': {
+			next.lexicon = applyLexiconMutation(next.lexicon ?? emptyLexicon(), mutation, at)
+			break
+		}
 		default: {
 			return state // 不认识:不感兴趣,原样返回
 		}
@@ -763,6 +833,22 @@ export function applyMutations(state, mutations) {
 	return next
 }
 
+/**
+ * **给一批变更盖上事件时间**。
+ *
+ * 产出方(内核)只写「发生了什么」,不读时钟;时间属于**日志里的那一刻**(`event.time`)。
+ * 变更自己带了 `at` 就以它为准(有些路径确实知道更准的时刻),否则用事件时间。
+ * 事件也没时间(旧日志/合成事件)时**不动它**——那里本来就是 0,不假装知道。
+ */
+function stampAt(mutations, time) {
+	if (time === null || !Array.isArray(mutations) || mutations.length === 0) return mutations
+	return mutations.map((mutation) => {
+		if (mutation === null || typeof mutation !== 'object') return mutation
+		if (typeof mutation.at === 'number') return mutation
+		return { ...mutation, at: time }
+	})
+}
+
 /**
  * 会话日志事件 → 状态。这是投影的入口:除了工具结果里的变更记录,
  * 还吃三条**关于过程本身的事实**——
@@ -843,7 +929,7 @@ export function applyEvent(state, event) {
 					try {
 						const payload = JSON.parse(facts.text)
 						if (Array.isArray(payload?.mutations) && payload.mutations.length > 0) {
-							next = applyMutations(next, payload.mutations)
+							next = applyMutations(next, stampAt(payload.mutations, typeof event.time === 'number' ? event.time : null))
 							touched = true
 						}
 					} catch {
@@ -911,6 +997,29 @@ export function applyEvent(state, event) {
 			fact.review = { decision: gate.action === 'retract_fact' ? 'retracted' : 'kept', reason: gate.note ?? null, at, by: 'user' }
 			return next
 		}
+		/**
+		 * **本体四动词(人的通道)**:路由侧已按同一份判据校验过(表外的值进不了日志),
+		 * 折法只做两件事——落成带 `by:'user'` 的词汇事件,以及**幂等**(人可能点两下、
+		 * 消息也可能重放:同 id 再登记不重复落,修订/废止的幂等由 applyLexiconMutation 自己保证)。
+		 */
+		if (gate.action === 'register_term' || gate.action === 'register_predicate') {
+			const entry = gate.entry ?? {}
+			const taken = (next.lexicon.terms ?? []).some((item) => item.id === entry.id) || (next.lexicon.predicates ?? []).some((item) => item.id === entry.id)
+			if (taken === true) return next
+			next.lexicon = applyLexiconMutation(next.lexicon, { t: gate.action === 'register_term' ? 'ontology/term_added' : 'ontology/predicate_added', ...entry, by: 'user' }, at)
+			return next
+		}
+		if (gate.action === 'revise_term') {
+			const entry = gate.entry ?? {}
+			next.lexicon = applyLexiconMutation(next.lexicon, { t: 'ontology/term_revised', ...entry, by: 'user' }, at)
+			return next
+		}
+		if (gate.action === 'deprecate_entry') {
+			const entry = gate.entry ?? {}
+			const kind = (next.lexicon.terms ?? []).some((item) => item.id === entry.id) ? 'ontology/term_deprecated' : 'ontology/predicate_deprecated'
+			next.lexicon = applyLexiconMutation(next.lexicon, { t: kind, ...entry, by: 'user' }, at)
+			return next
+		}
 		const fork = next.forks.find((item) => item.id === (gate.fork ?? null))
 		if (fork === undefined) return next
 		fork.humanDecision = {
@@ -961,7 +1070,17 @@ export function applyEvent(state, event) {
 		const meta = event.data === undefined || event.data === null ? undefined : event.data.meta
 		let next = state
 		if (meta !== null && meta !== undefined && typeof meta === 'object' && meta.kind === MUTATION_KIND) {
-			next = applyMutations(next, Array.isArray(meta.mutations) ? meta.mutations : meta.mutation === undefined ? [] : [meta.mutation])
+			/**
+			 * **时间由折法盖上去,不由产出方写**:内核只写「发生了什么」,不知道也不该关心
+			 * 这条记录落在日志的哪一刻;而事件本身带着 `time`,那才是权威。
+			 *
+			 * 不盖的后果是全局性的:每条变更的 `at` 都取 `mutation.at ?? 0`,于是凡是显示时间的
+			 * 地方——Inspector 的历史、计划开合、证据时刻——一律是 **1970-01-01**。
+			 * 盖在这里(而不是让内核每条都写一遍时间)同时满足两件事:内核不必读时钟,
+			 * 折法仍然只有一个入口。
+			 */
+			const stamped = stampAt(Array.isArray(meta.mutations) ? meta.mutations : meta.mutation === undefined ? [] : [meta.mutation], typeof event.time === 'number' ? event.time : null)
+			next = applyMutations(next, stamped)
 		}
 		if (next.inFlight !== null) {
 			const cleared = next === state ? clone(state) : next
@@ -975,6 +1094,614 @@ export function applyEvent(state, event) {
 
 // ── 派生:阶段 / 完成度 / 假设状态 / 世界线阶段,全部现算,状态里不存 ──────────
 
+/** 假设的终态:到了这里就不再是「还要继续做的活」。 */
+const TERMINAL_HYPOTHESIS = new Set(['refuted', 'superseded', 'retracted'])
+
+/**
+ * **知识模式(分诊)与缺口读数。**
+ *
+ * 判据是**结构的,不是词法的**:这里不猜「这句话像不像研究任务」。立约(`SetGoal`)并用
+ * 相互竞争的假设登记它,是模型自己已经做出的那次承诺——它意味着这件事要跨多轮、要有依据、
+ * 要有可复核的结论。日常问答从不立约,于是从不进这一档。用词面启发式去猜任务类型,
+ * 正是真跑里评估者抓到的那类「硬编码比例」的老路:猜错了没人能复核,而结构判据可以。
+ *
+ * 缺口(`gaps`)是**读数,不是拦截**,也不新增账本:每一条都从已有事实算出来,并且指得出
+ * 一个今天就能补的动作。它们要进运行态卡——模型每一步唯一读到的那个窗口。让缺口每回合可见,
+ * 比让提示词多叮嘱一句可靠:提示词会被读成建议,而卡里的读数不会。
+ */
+export function deriveKnowledge(state, hypotheses, factRows, lexicon) {
+	const goal = state?.goal ?? null
+	const open = goal !== null && goal.status !== 'achieved' && goal.status !== 'abandoned'
+	const registered = hypotheses.filter((item) => !TERMINAL_HYPOTHESIS.has(item.status))
+	/**
+	 * 模式的**唯一**判据:目标还开着,而且它带着登记过的假设。
+	 *
+	 * 为什么不是「目标存在」就够:`minHypotheses` 是部署自己的产品立场(内核缺省是 0 = 机制中立)。
+	 * 一个把下限设成 0 的部署明确说了「我不要这条纪律」,那时它也不该收到知识模式的读数。
+	 */
+	const mode = open && registered.length > 0 ? 'knowledge' : 'ordinary'
+	const terms = Array.isArray(lexicon?.terms) ? lexicon.terms : []
+	const predicates = Array.isArray(lexicon?.predicates) ? lexicon.predicates : []
+	const gaps = []
+	if (mode === 'knowledge') {
+		/**
+		 * ① 语言还没立起来:跨轮复用与「按概念取用已知」都要求先有词汇。
+		 *    判据是**两个都空**——只有概念没有谓词时,关系还说不出来,但语言已经开张了,
+		 *    那是进展不是缺口(否则每注册一个概念就多一条永远擦不掉的抱怨)。
+		 */
+		if (terms.length === 0 && predicates.length === 0) {
+			gaps.push({
+				code: 'no_language',
+				count: registered.length,
+				detail: `${registered.length} 条在验命题,但还没有任何概念与谓词:换一轮只能靠重读散文取用它们`,
+			})
+		}
+		/**
+		 * ② 只有散文主张的命题:断言是可选的(「加法,不是门槛」),所以这里**不是违规**,
+		 *    而是「这条主张还不能被机器比对」。只算非终态的:被推翻/被替代的不再欠这一笔。
+		 */
+		const proseOnly = registered.filter((item) => !Array.isArray(item.assertions) || item.assertions.length === 0)
+		if (proseOnly.length > 0) {
+			gaps.push({
+				code: 'prose_only_claims',
+				count: proseOnly.length,
+				detail: `${proseOnly.length} 条在验命题只有散文主张:两条结论是不是在说同一件事,只能靠重读判断`,
+			})
+		}
+		/**
+		 * ③ **升格时没带断言**。只算 0.2.0 那条路走出来的事实(`hypothesis` 已关联)——
+		 *    更早的事实补不上断言(见已知缺口),把它们算成欠账就是一条永远还不掉的抱怨。
+		 */
+		const unstructured = factRows.filter((fact) => typeof fact.hypothesis === 'string' && fact.hypothesis !== '' && (!Array.isArray(fact.assertions) || fact.assertions.length === 0))
+		if (unstructured.length > 0) {
+			gaps.push({
+				code: 'unstructured_facts',
+				count: unstructured.length,
+				detail: `${unstructured.length} 条已升格事实没有断言:它们进不了实体图,也不能按概念取用`,
+			})
+		}
+		/**
+		 * ④ **从没被证据碰过的命题**。只在这次会话已经真的跑出过证据之后才报——计划刚立、
+		 *    一步都还没走时,所有假设都是「没碰过」,那是正常的起点而不是缺口。
+		 *    它和结案时那条 `unjudged` 是同一条先例:**不逼裁决,但不许把「没看过」写成「没问题」**。
+		 */
+		if (Array.isArray(state?.evidence) && state.evidence.length > 0) {
+			const untouched = registered.filter((item) => item.refutations + item.inconclusive === 0 && item.supportedLevel === null)
+			if (untouched.length > 0) {
+				gaps.push({
+					code: 'untouched_claims',
+					count: untouched.length,
+					detail: `${untouched.length} 条在验命题还没有任何证据碰过(支持 / 推翻 / 无法判定都算碰过)`,
+				})
+			}
+		}
+	}
+	return {
+		mode,
+		/** 一句人话:为什么进了这一档(或为什么没进)。它进卡,所以不许写成术语。 */
+		why:
+			mode === 'knowledge'
+				? `目标还开着,带着 ${registered.length} 条登记过的命题——这是跨轮、要依据、要可复核结论的活`
+				: open
+					? '目标还开着,但没有登记命题:按普通任务推进'
+					: '没有开着的目标:按普通任务推进',
+		gaps,
+	}
+}
+
+/**
+ * **知识预检(preflight)**:进入知识模式那一刻,把「已知」主动送到模型面前。
+ *
+ * 解决的问题:真跑里模型不查就开工——不是因为不知道有 \`QueryKnowledge\`,
+ * 而是因为**没人提醒它此刻该查**。提示词会被读成建议;卡里的读数不会。
+ * 于是这里把相关性判断做成投影:从当前目标与命题的文本出发,圈出**有界**的一组
+ * 已有词汇、事实与冲突,随运行态卡注入。模型只在这份摘要不够用时才需要精确查询。
+ *
+ * 三条纪律(与缺口读数同一套):
+ *   · **只读**:不产生变更,不新增状态——它就是 \`derive\` 的另一个读面;
+ *   · **有界**:terms / predicates / facts 各有上限,超出如实说「还有 N 个未列出」;
+ *   · **不猜语义**:相关性是**词面命中**(label / id / alias 出现在主张文本里),
+ *     不是「系统认为相关」——命中的依据逐条可复核。
+ *
+ * 判据的形状:主张文本(去空白)包含词条的 label / id / alias(去空白),
+ * 或者命题已有的断言引用了该谓词。前者是「这个词已经在对话里出现了」,后者是「已经在用了」。
+ */
+export function knowledgePreflight(state, derived) {
+	const knowledge = derived?.knowledge ?? deriveKnowledge(state, derived?.hypotheses ?? [], derived?.factRows ?? [], derived?.lexicon)
+	if (knowledge.mode !== 'knowledge') return null
+	const terms = Array.isArray(derived?.lexicon?.terms) ? derived.lexicon.terms : []
+	const predicates = Array.isArray(derived?.lexicon?.predicates) ? derived.lexicon.predicates : []
+	const hypotheses = Array.isArray(derived?.hypotheses) ? derived.hypotheses : []
+	const factRows = Array.isArray(derived?.factRows) ? derived.factRows : []
+	const conflicts = Array.isArray(derived?.conflicts) ? derived.conflicts : []
+	/** 命题的文本面:目标主张 + 每条命题的主张(去空白后做包含判断)。 */
+	const claimText = [state?.goal?.claim, ...hypotheses.map((item) => item.claim)].filter((text) => typeof text === 'string' && text !== '').map((text) => String(text).replace(/\s+/g, ''))
+	/** 命题已经引用的谓词(断言在假设上时就该算「在用」)。 */
+	const usedPredicates = new Set(hypotheses.flatMap((item) => (Array.isArray(item.assertions) ? item.assertions : [])).map((assertion) => String(assertion?.predicate ?? '')))
+	const hits = (entry) => {
+		const candidates = [entry.id, entry.label, ...(Array.isArray(entry.aliases) ? entry.aliases : [])].filter((text) => typeof text === 'string' && text !== '').map((text) => String(text).replace(/\s+/g, ''))
+		return candidates.some((candidate) => claimText.some((text) => text.includes(candidate)))
+	}
+	const LIMIT = 20
+	const matchedTerms = terms.filter((term) => hits(term) && term.status !== 'deprecated')
+	const matchedPredicates = predicates.filter((predicate) => usedPredicates.has(predicate.id) || hits(predicate))
+	const matchedTermIds = new Set(matchedTerms.map((term) => term.id))
+	const matchedPredicateIds = new Set(matchedPredicates.map((predicate) => predicate.id))
+	/** 事实:断言引用了命中的谓词,或主词类型是命中的概念。 */
+	const matchedFacts = factRows.filter((fact) =>
+		(Array.isArray(fact.assertions) ? fact.assertions : []).some((assertion) => matchedPredicateIds.has(String(assertion?.predicate ?? '')) || matchedTermIds.has(String(assertion?.subject?.type ?? ''))),
+	)
+	return {
+		mode: 'knowledge',
+		/** 词面命中的词汇:模型接下来要写的结论大概率会用到它们。 */
+		terms: matchedTerms.slice(0, LIMIT).map((term) => ({ id: term.id, label: term.label, gloss: term.gloss, parent: term.parent ?? null, status: term.status, uses: term.uses ?? 0, basis: term.basis ?? null })),
+		termsTruncated: Math.max(0, matchedTerms.length - LIMIT),
+		predicates: matchedPredicates.slice(0, LIMIT).map((predicate) => ({ id: predicate.id, label: predicate.label, domain: predicate.domain, range: predicate.range, functional: predicate.functional === true, status: predicate.status, uses: predicate.uses ?? 0, basis: predicate.basis ?? null })),
+		predicatesTruncated: Math.max(0, matchedPredicates.length - LIMIT),
+		/** 命中的既有事实(可复用的「已知」)。 */
+		facts: matchedFacts.slice(0, LIMIT).map((fact) => ({ id: fact.id, text: fact.text, level: fact.level ?? null, scope: fact.scope ?? null, hypothesis: fact.hypothesis ?? null, review: fact.review?.decision ?? null })),
+		factsTruncated: Math.max(0, matchedFacts.length - LIMIT),
+		/** 冲突:有就带上(它们约束「哪些结论还不能随便写)。 */
+		conflicts: conflicts.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject })),
+		/** 缺口读数(与卡里同一份:`deriveKnowledge` 的 gaps)。 */
+		gaps: knowledge.gaps,
+	}
+}
+
+// ── 知识 Inspector:一个选择 → 它的定义 / 关系 / 断言 / 证据链 / 历史 ──────────
+
+/**
+ * **图上的一个选择(节点或边),它的全部知识读数。**
+ *
+ * 为什么要有它:图能画出来不等于图是知识入口。点击一个节点却只得到「按此过滤」,
+ * 读的人仍然不知道这个词是什么意思、凭什么信、谁改过它。这一份投影把那条链补齐:
+ *
+ * ```text
+ * 概念   → 定义 / 父概念 / 子概念 / 用它的谓词 / 相关实例 / 相关事实 / 历史
+ * 谓词   → 主词域 / 值域 / 单值性 / 用它的事实 / 由它产生的冲突 / 历史
+ * 实例   → 类型 / 入边 / 出边 / 每条断言的完整链 / 冲突
+ * 字面值 → 值形态 / 取值 / 产生它的事实 / 出处
+ * 断言边 → 事实 → 命题 → 证据 → 出处 → 产生步骤 → 复核态
+ * ```
+ *
+ * 三条纪律与其余读面同一套:
+ *   · **只读**:纯函数,不产生变更、不新增状态;判据只有这一处(客户端不许自己拼链);
+ *   · **有界**:每一类列表都有上限,超出如实报 truncated;
+ *   · **不编**:关联不到就如实给空,不猜「大概相关」——旧账本没有 `hypothesis` 关联时
+ *     给 `null`,不拿文本相等去冒充身份(那条退路只属于折法,不属于读面)。
+ *
+ * 选择可以是 `{ kind, id }`,也可以直接给图上的 id 串(前缀即类型,见 `normalizeSelection`)。
+ */
+export function inspectGraphSelection(state, selection, derived) {
+	const picked = normalizeSelection(selection)
+	if (picked === null) return null
+	const rows = derived ?? derive(state)
+	const context = inspectorContext(state, rows)
+	switch (picked.kind) {
+		case 'concept':
+			return inspectConcept(context, picked.id)
+		case 'value_type':
+			return inspectValueType(context, picked.id)
+		case 'predicate':
+			return inspectPredicate(context, picked.id)
+		case 'instance':
+			return inspectInstance(context, picked.id)
+		case 'literal':
+			return inspectLiteral(context, picked.id)
+		case 'edge':
+			return inspectEdge(context, picked.id)
+		default:
+			return null
+	}
+}
+
+/** 列表上限:读面有界,超出如实报 truncated(与知识预检同一套纪律)。 */
+const INSPECT_LIMIT = 30
+const cut = (list, limit = INSPECT_LIMIT) => ({ rows: list.slice(0, limit), truncated: Math.max(0, list.length - limit) })
+
+/**
+ * 把选择归一到 `{ kind, id }`。
+ *
+ * 图上的 id 串自带类型前缀(`graphProjection` 定的形状),所以两种调用方式都认:
+ * 客户端手上有节点对象时给 `{ kind, id }` 最稳;只拿到 id 串时按前缀解析。
+ * 解析不出来**返回 null**,不猜一个类型——猜错会让 Inspector 端出一份别的东西的定义。
+ */
+function normalizeSelection(selection) {
+	const raw = typeof selection === 'string' ? { id: selection } : selection
+	if (raw === null || typeof raw !== 'object') return null
+	const id = String(raw.id ?? '')
+	if (id === '') return null
+	/** 调用方声明的类型优先认;声明了就必须对得上,不许「说 A 给 B」。 */
+	const declared = typeof raw.kind === 'string' ? raw.kind : ''
+	const ok = (kind) => declared === '' || declared === kind
+	if (id.startsWith('term:')) return ok('concept') ? { kind: 'concept', id: id.slice('term:'.length) } : null
+	if (id.startsWith('is_a:')) return ok('concept') ? { kind: 'concept', id: id.slice('is_a:'.length) } : null
+	if (id.startsWith('form:')) return ok('value_type') ? { kind: 'value_type', id: id.slice('form:'.length) } : null
+	if (id.startsWith('predicate:')) return ok('predicate') ? { kind: 'predicate', id: id.slice('predicate:'.length) } : null
+	if (id.startsWith('assertion:')) return ok('edge') ? { kind: 'edge', id } : null
+	if (declared === 'concept' || declared === 'predicate' || declared === 'value_type' || declared === 'edge') return { kind: declared, id }
+	/** 剩下的两种由图上的 id 形状定:实例是 `类型|名称`,字面值是 `谓词:值形态:取值`。 */
+	if (id.includes('|')) return ok('instance') ? { kind: 'instance', id } : null
+	if (id.includes(':')) return ok('literal') ? { kind: 'literal', id } : null
+	return null
+}
+
+/**
+ * Inspector 的**一次性的索引**:把状态里的几组东西按 id 归好,省得每个分支各建一遍。
+ * 它不缓存、不外传——每次询问建一次,免得读面带上一份会过期的索引。
+ */
+function inspectorContext(state, derived) {
+	const facts = Array.isArray(derived?.factRows) ? derived.factRows : Array.isArray(state?.facts) ? state.facts : []
+	const lexicon = normalizeLexicon(state?.lexicon)
+	const hypothesisById = new Map((state?.hypotheses ?? []).map((item) => [String(item.id ?? ''), item]))
+	/**
+	 * 命题**优先读派生的那一份**:`supportedLevel` / `refutations` / `inconclusive` 都是现算的,
+	 * 只读原始状态的话,Inspector 会写「支持到 —」而卡片上明明有等级——同一件事两处说法不同。
+	 */
+	const derivedHypothesisById = new Map((Array.isArray(derived?.hypotheses) ? derived.hypotheses : []).map((item) => [String(item.id ?? ''), item]))
+	const evidenceById = new Map((state?.evidence ?? []).map((item) => [String(item.id ?? ''), item]))
+	const materialById = new Map((state?.materials ?? []).map((item) => [String(item.id ?? ''), item]))
+	const stepOf = (planId, stepId) =>
+		(state?.plans ?? []).find((plan) => plan.id === planId)?.steps.find((step) => step.id === stepId) ?? null
+	return { state, derived, facts, lexicon, hypothesisById, derivedHypothesisById, evidenceById, materialById, stepOf, conflicts: Array.isArray(derived?.conflicts) ? derived.conflicts : [] }
+}
+
+/** 一条断言的一行人话(与货架 / 卡片同源:`domain-language` 的 `formatAssertion`)。 */
+const say = (lexicon, assertion) => formatAssertion(lexicon, assertion)
+
+/**
+ * **一条事实的完整链**:事实 → 命题 → 证据 → 出处 → 产生步骤 → 复核态。
+ *
+ * 这是阶段 5 的核心:图上一条边背后到底站着什么。每一段都来自账本已有的东西,
+ * 没有一段是这里推断出来的。
+ */
+function factChain(context, fact) {
+	const { lexicon, hypothesisById, derivedHypothesisById, evidenceById, stepOf, conflicts } = context
+	const evidenceIds = Array.isArray(fact?.evidence) ? fact.evidence : []
+	const evidence = evidenceIds
+		.map((id) => evidenceById.get(String(id)))
+		.filter((item) => item !== undefined)
+		.map((item) => {
+			const step = stepOf(item.plan, item.step) ?? null
+			return {
+				id: item.id,
+				verdict: item.verdict,
+				level: item.level,
+				evaluator: item.evaluator,
+				basis: item.basis ?? null,
+				anchor: item.anchor ?? null,
+				at: item.at ?? null,
+				/** 四类出处由账本记账时解析好,这里只搬运。 */
+				origins: Array.isArray(item.origins) ? item.origins : [],
+				refs: Array.isArray(item.refs) ? item.refs : [],
+				/** 材料(id 或路径)也带上摘要,读的人不必再开一次文件。 */
+				materials: (Array.isArray(item.refs) ? item.refs : [])
+					.map((ref) => context.materialById.get(String(ref)))
+					.filter((item2) => item2 !== undefined)
+					.map((item2) => ({ id: item2.id, source: item2.source ?? null, path: item2.path ?? null, note: (item2.note ?? '').slice(0, 200) })),
+				step: step === null ? null : { plan: item.plan, id: item.step, do: step.do ?? null, doneCriteria: step.done_criteria ?? null, status: step.status ?? null },
+			}
+		})
+	const hypothesisId = typeof fact?.hypothesis === 'string' && fact.hypothesis !== '' ? fact.hypothesis : null
+	const hypothesis = hypothesisId === null ? null : derivedHypothesisById.get(hypothesisId) ?? hypothesisById.get(hypothesisId) ?? null
+	const assertions = Array.isArray(fact?.assertions) ? fact.assertions : []
+	return {
+		id: fact?.id ?? null,
+		text: fact?.text ?? null,
+		level: fact?.level ?? null,
+		scope: fact?.scope ?? null,
+		path: fact?.path ?? null,
+		at: fact?.at ?? null,
+		/** `live` / `refuted`(有推翻证据待人裁决)/ `retracted`(人已撤回)。 */
+		status: fact?.review?.decision === 'retracted' ? 'retracted' : fact?.refuted === true ? 'refuted' : 'live',
+		review: fact?.review === undefined || fact?.review === null ? null : { decision: fact.review.decision ?? null, reason: fact.review.reason ?? null, at: fact.review.at ?? null },
+		assertions: assertions.map((assertion) => ({ ...assertion, chip: say(lexicon, assertion) })),
+		hypothesis:
+			hypothesis === null
+				? null
+				: { id: hypothesis.id, claim: hypothesis.claim ?? null, refuteWhen: hypothesis.refute_when ?? null, status: hypothesis.status ?? null, supportedLevel: hypothesis.supportedLevel ?? null, refutations: hypothesis.refutations ?? 0, inconclusive: hypothesis.inconclusive ?? 0 },
+		evidence,
+		/** 由这条事实参与构成的冲突(只暴露,不裁决——与投影同一句话)。 */
+		conflicts: conflicts
+			.filter((conflict) => (Array.isArray(conflict.sides) ? conflict.sides : []).some((side) => side.fact === fact?.id))
+			.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject, sides: conflict.sides.map((side) => ({ fact: side.fact ?? null, value: side.value ?? null })) })),
+		history: factHistory(fact, evidence),
+	}
+}
+
+/**
+ * 事实的**留痕**:升格 / 评审决定 / 每条证据什么时候到的。
+ * 它是「状态里真的留着的那几条记录」,不是完整事件流——完整事件流在会话日志里,
+ * 读面不假装自己有它(见 known-gaps)。
+ */
+function factHistory(fact, evidence) {
+	const events = []
+	if (fact?.at !== undefined && fact?.at !== null) events.push({ kind: 'fact/promoted', at: fact.at, summary: `升格为事实(支持到 ${fact.level ?? '—'})` })
+	if (fact?.review !== undefined && fact?.review !== null) {
+		events.push({
+			kind: 'fact/reviewed',
+			at: fact.review.at ?? null,
+			summary: fact.review.decision === 'retracted' ? '人审查后**撤回**(记录保留)' : '人审查后**维持**(判证据不可靠)',
+			reason: fact.review.reason ?? null,
+		})
+	}
+	for (const item of evidence) events.push({ kind: 'evidence/recorded', at: item.at ?? null, summary: `${item.verdict}(${item.evaluator} · ${item.level})`, reason: item.basis ?? null })
+	return events.filter((event) => event.at !== null).sort((left, right) => left.at - right.at)
+}
+
+/** 词汇条目的留痕:登记 / 历次修订 / 废止。登记与修订本来就存在词条里(折法保留的)。 */
+function entryHistory(entry, label) {
+	const events = []
+	if (entry?.at !== undefined && entry?.at !== null) events.push({ kind: `${label}_added`, at: entry.at, summary: `登记(依据:${entry.basis ?? '—'})`, by: entry.by ?? null })
+	for (const revision of Array.isArray(entry?.revisions) ? entry.revisions : []) {
+		events.push({ kind: `${label}_revised`, at: revision.at ?? null, summary: `修订到 v${revision.version ?? '?'}`, reason: revision.reason ?? null, by: revision.by ?? null })
+	}
+	if (entry?.deprecated !== undefined && entry?.deprecated !== null) {
+		events.push({ kind: `${label}_deprecated`, at: entry.deprecated.at ?? null, summary: '废止(黏性终态,没有复活)', reason: entry.deprecated.reason ?? null, by: entry.deprecated.by ?? null })
+	}
+	return events.filter((event) => event.at !== null || event.kind.endsWith('_deprecated')).sort((left, right) => (left.at ?? 0) - (right.at ?? 0))
+}
+
+/** 事实的断言是否碰到这个概念(主词类型 = 概念 id)。 */
+const assertsOn = (fact, termId) => (Array.isArray(fact?.assertions) ? fact.assertions : []).some((assertion) => String(assertion?.subject?.type ?? '') === termId)
+const usesPredicate = (fact, predicateId) => (Array.isArray(fact?.assertions) ? fact.assertions : []).some((assertion) => String(assertion?.predicate ?? '') === predicateId)
+
+/** 概念节点:语言里这个词是什么、它连着谁、哪些事实在用它。 */
+function inspectConcept(context, termId) {
+	const { lexicon, facts, conflicts, state } = context
+	const term = lexicon.terms.find((item) => item.id === termId)
+	if (term === undefined) return null
+	const children = lexicon.terms.filter((item) => String(item.parent ?? '') === termId)
+	const predicates = lexicon.predicates.filter((item) => String(item.domain ?? '') === termId || String(item.range?.term ?? '') === termId)
+	const relatedFacts = facts.filter((fact) => assertsOn(fact, termId))
+	/** 实例:这一概念下主词出现过的具体对象(从断言投影,与实体图同一份判据)。 */
+	const instances = new Map()
+	for (const fact of relatedFacts) {
+		for (const assertion of Array.isArray(fact.assertions) ? fact.assertions : []) {
+			if (String(assertion?.subject?.type ?? '') !== termId) continue
+			const key = String(assertion.subject.id ?? '')
+			if (key === '') continue
+			if (!instances.has(key)) instances.set(key, { id: `${termId}|${key}`, ref: key, label: key, facts: [] })
+			instances.get(key).facts.push(fact.id ?? null)
+		}
+	}
+	const chain = cut(relatedFacts)
+	return {
+		selection: { kind: 'concept', id: term.id, label: term.label ?? term.id },
+		definition: {
+			id: term.id,
+			label: term.label ?? term.id,
+			gloss: term.gloss ?? null,
+			aliases: Array.isArray(term.aliases) ? term.aliases : [],
+			parent: term.parent === null || term.parent === undefined ? null : String(term.parent),
+			status: term.status ?? 'admitted',
+			version: term.version ?? 1,
+			basis: term.basis ?? null,
+			by: term.by ?? null,
+			at: term.at ?? null,
+			uses: term.uses ?? 0,
+		},
+		relations: {
+			parent: term.parent === null || term.parent === undefined ? null : { id: String(term.parent), label: lexicon.terms.find((item) => item.id === String(term.parent))?.label ?? String(term.parent) },
+			children: children.map((item) => ({ id: item.id, label: item.label ?? item.id, status: item.status ?? 'admitted' })),
+			predicates: predicates.map((item) => ({ id: item.id, label: item.label ?? item.id, domain: item.domain ?? null, range: item.range ?? null, functional: item.functional === true, status: item.status ?? 'admitted' })),
+			instances: [...instances.values()].sort((left, right) => (left.id < right.id ? -1 : 1)).map((item) => ({ id: item.id, ref: item.ref, label: item.label, factCount: item.facts.length })),
+		},
+		facts: chain.rows.map((fact) => factChain(context, fact)),
+		factsTruncated: chain.truncated,
+		conflicts: conflicts
+			.filter((conflict) => String(conflict.subject ?? '').startsWith(`${termId}|`) || predicates.some((predicate) => predicate.id === conflict.predicate))
+			.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject, sides: conflict.sides.map((side) => ({ fact: side.fact ?? null, value: side.value ?? null })) })),
+		history: entryHistory(term, 'term'),
+		actions: { canFilter: true, canExpand: true, canEdit: true },
+		/** 词汇是**约定**,不需要证据等级——把它说清楚,免得读的人以为它「没验」。 */
+		note: '概念是约定,不是主张:它不带证据等级。用这个词写下的句子才需要。',
+	}
+}
+
+/** 值形态节点:系统固定的五种之一(不独立治理,所以它没有历史)。 */
+function inspectValueType(context, form) {
+	const { lexicon, facts } = context
+	const known = lexicon.predicates.filter((item) => String(item.range?.form ?? '') === form)
+	if (known.length === 0 && !VALUE_FORMS.includes(form)) return null
+	const used = facts.filter((fact) => (Array.isArray(fact.assertions) ? fact.assertions : []).some((assertion) => String(assertion?.object?.kind ?? '') === form))
+	const chain = cut(used)
+	return {
+		selection: { kind: 'value_type', id: form, label: form },
+		definition: { id: form, label: form, kind: 'value_type', status: 'builtin', gloss: VALUE_FORM_GLOSS[form] ?? null },
+		relations: { predicates: known.map((item) => ({ id: item.id, label: item.label ?? item.id, domain: item.domain ?? null, range: item.range ?? null })) },
+		facts: chain.rows.map((fact) => factChain(context, fact)),
+		factsTruncated: chain.truncated,
+		conflicts: [],
+		/** 值形态由系统固定,不进领域本体、也没有版本史——如实说空,不编一段。 */
+		history: [],
+		actions: { canFilter: true, canExpand: false, canEdit: false },
+		note: '值形态由系统固定(statement / quantity / formula / code / reference),不独立治理,所以没有版本史。',
+	}
+}
+
+/** 谓词节点:它允许什么关系、谁在用、用出了哪些冲突。 */
+function inspectPredicate(context, predicateId) {
+	const { lexicon, facts, conflicts } = context
+	const predicate = lexicon.predicates.find((item) => item.id === predicateId)
+	if (predicate === undefined) return null
+	const used = facts.filter((fact) => usesPredicate(fact, predicateId))
+	const chain = cut(used)
+	const range = predicate.range ?? null
+	return {
+		selection: { kind: 'predicate', id: predicate.id, label: predicate.label ?? predicate.id },
+		definition: {
+			id: predicate.id,
+			label: predicate.label ?? predicate.id,
+			gloss: predicate.gloss ?? null,
+			domain: predicate.domain ?? null,
+			/** 主词域的**名字**也带上:只给 id,读的人还要自己回词汇表里找。 */
+			domainLabel: predicate.domain === null || predicate.domain === undefined ? null : lexicon.terms.find((item) => item.id === String(predicate.domain))?.label ?? String(predicate.domain),
+			range,
+			functional: predicate.functional === true,
+			status: predicate.status ?? 'admitted',
+			version: predicate.version ?? 1,
+			basis: predicate.basis ?? null,
+			by: predicate.by ?? null,
+			at: predicate.at ?? null,
+			uses: predicate.uses ?? 0,
+		},
+		relations: {
+			valueForm: range?.form ?? null,
+			rangeTerm: range?.term ?? null,
+			/** 用这个谓词写下的**断言**(不是事实:一条事实可以带多条断言)。 */
+			assertions: used.length,
+			subjects: [...new Set(used.flatMap((fact) => (Array.isArray(fact.assertions) ? fact.assertions : []).filter((assertion) => String(assertion?.predicate ?? '') === predicateId).map((assertion) => `${String(assertion?.subject?.type ?? '')}|${String(assertion?.subject?.id ?? '')}`)))].map((key) => ({ key, ref: key.split('|')[1] ?? key, type: key.split('|')[0] ?? '' })),
+		},
+		facts: chain.rows.map((fact) => factChain(context, fact)),
+		factsTruncated: chain.truncated,
+		conflicts: conflicts
+			.filter((conflict) => conflict.predicate === predicateId)
+			.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject, sides: conflict.sides.map((side) => ({ fact: side.fact ?? null, value: side.value ?? null })) })),
+		history: entryHistory(predicate, 'predicate'),
+		actions: { canFilter: true, canExpand: true, canEdit: true },
+		note: predicate.functional === true ? '单值谓词:同一主词上两条未撤回的确认事实取值不同时,系统给出一对冲突读数(只暴露,不裁决)。' : null,
+	}
+}
+
+/** 实例节点:某个具体对象身上挂着的全部断言与它们的链。 */
+function inspectInstance(context, key) {
+	const { lexicon, facts, conflicts } = context
+	const separator = key.indexOf('|')
+	if (separator < 0) return null
+	const type = key.slice(0, separator)
+	const ref = key.slice(separator + 1)
+	if (ref === '') return null
+	const outgoing = []
+	const incoming = []
+	for (const fact of facts) {
+		for (const assertion of Array.isArray(fact.assertions) ? fact.assertions : []) {
+			const subjectMatches = String(assertion?.subject?.type ?? '') === type && String(assertion?.subject?.id ?? '') === ref
+			const objectMatches = String(assertion?.object?.kind ?? '') === 'instance' && String(assertion?.object?.value ?? '') === ref && (String(assertion?.object?.type ?? '') === type || String(assertion?.object?.type ?? '') === '')
+			if (subjectMatches) outgoing.push({ fact, assertion, direction: 'out' })
+			if (objectMatches) incoming.push({ fact, assertion, direction: 'in' })
+		}
+	}
+	if (outgoing.length === 0 && incoming.length === 0 && !lexicon.terms.some((item) => item.id === type)) return null
+	const touchedFacts = [...new Set([...outgoing, ...incoming].map((item) => item.fact))]
+	const chain = cut(touchedFacts)
+	const edges = [...outgoing, ...incoming].map((item) => ({
+		direction: item.direction,
+		predicate: String(item.assertion?.predicate ?? ''),
+		predicateLabel: lexicon.predicates.find((entry) => entry.id === String(item.assertion?.predicate ?? ''))?.label ?? null,
+		chip: say(lexicon, item.assertion),
+		fact: item.fact.id ?? null,
+		level: item.fact.level ?? null,
+		status: item.fact.review?.decision === 'retracted' ? 'retracted' : item.fact.refuted === true ? 'refuted' : 'live',
+	}))
+	return {
+		selection: { kind: 'instance', id: key, label: ref },
+		definition: {
+			id: key,
+			ref,
+			type: type === '' ? null : type,
+			typeLabel: type === '' ? null : lexicon.terms.find((item) => item.id === type)?.label ?? type,
+			/** 实例**不注册**(从断言投影出来),所以它没有独立生命周期与版本史。 */
+			status: 'projected',
+		},
+		relations: { edges, out: outgoing.length, in: incoming.length },
+		facts: chain.rows.map((fact) => factChain(context, fact)),
+		factsTruncated: chain.truncated,
+		conflicts: conflicts
+			.filter((conflict) => String(conflict.subject ?? '') === key)
+			.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject, sides: conflict.sides.map((side) => ({ fact: side.fact ?? null, value: side.value ?? null })) })),
+		history: [],
+		actions: { canFilter: true, canExpand: true, canEdit: false },
+		note: '实例由断言投影出来,不单独注册、也不做实体消解(同名即同节点);它没有自己的版本史。',
+	}
+}
+
+/** 字面值节点:一个取值,以及是谁写下它的。 */
+function inspectLiteral(context, key) {
+	const { lexicon, facts } = context
+	const separator = key.indexOf(':')
+	if (separator < 0) return null
+	const predicateId = key.slice(0, separator)
+	const objectPart = key.slice(separator + 1)
+	const holders = []
+	for (const fact of facts) {
+		for (const assertion of Array.isArray(fact.assertions) ? fact.assertions : []) {
+			if (String(assertion?.predicate ?? '') !== predicateId) continue
+			if (objectKey(assertion.object) !== objectPart) continue
+			holders.push({ fact, assertion })
+		}
+	}
+	if (holders.length === 0) return null
+	const predicate = lexicon.predicates.find((item) => item.id === predicateId) ?? null
+	const touchedFacts = [...new Set(holders.map((item) => item.fact))]
+	const chain = cut(touchedFacts)
+	return {
+		selection: { kind: 'literal', id: key, label: say(lexicon, holders[0].assertion) },
+		definition: {
+			id: key,
+			predicate: predicateId,
+			predicateLabel: predicate?.label ?? predicateId,
+			form: holders[0].assertion?.object?.kind ?? null,
+			value: holders[0].assertion?.object?.value ?? null,
+			unit: holders[0].assertion?.object?.unit ?? null,
+			/** 值形态决定「这个取值是什么东西」:数值 / 公式 / 代码路径 / 引用。 */
+			status: 'projected',
+		},
+		relations: { holders: holders.length, predicateRange: predicate?.range ?? null },
+		facts: chain.rows.map((fact) => factChain(context, fact)),
+		factsTruncated: chain.truncated,
+		conflicts: [],
+		history: [],
+		actions: { canFilter: true, canExpand: true, canEdit: false },
+		note: '字面值是断言里的客体,由事实投影出来;它没有独立生命周期。',
+	}
+}
+
+/** 断言边:一条事实边的完整链(图上点击一条边时看的就是它)。 */
+function inspectEdge(context, edgeId) {
+	const { lexicon, facts, conflicts } = context
+	const parts = edgeId.split(':')
+	if (parts[0] !== 'assertion' || parts.length < 4) return null
+	const factId = parts[1]
+	const predicateId = parts[2]
+	/** 主语键里有 `|`,而它自己可能带 `:`——所以从第 4 段起重新拼回去(不按段数硬切)。 */
+	const subjectKey = parts.slice(3).join(':')
+	const fact = facts.find((item) => String(item.id ?? '') === factId)
+	if (fact === undefined) return null
+	const predicate = lexicon.predicates.find((item) => item.id === predicateId) ?? null
+	const chain = factChain(context, fact)
+	const separator = subjectKey.indexOf('|')
+	return {
+		selection: { kind: 'edge', id: edgeId, label: `${predicate?.label ?? predicateId} · ${fact.text ?? ''}`.slice(0, 120) },
+		definition: {
+			kind: 'assertion',
+			predicate: predicateId,
+			predicateLabel: predicate?.label ?? predicateId,
+			predicateGloss: predicate?.gloss ?? null,
+			domain: predicate?.domain ?? null,
+			range: predicate?.range ?? null,
+			functional: predicate?.functional === true,
+			subject: separator < 0 ? { type: null, id: subjectKey } : { type: subjectKey.slice(0, separator), id: subjectKey.slice(separator + 1) },
+		},
+		/** 一条边就是一条事实:**链在 `facts[0]` 里**,读面不把它拆成两处说。 */
+		facts: [chain],
+		factsTruncated: 0,
+		conflicts: chain.conflicts,
+		history: chain.history,
+		actions: { canFilter: true, canExpand: true, canEdit: false },
+		note: predicate?.functional === true ? '这条边落在单值谓词上:同一主词出现第二个不同取值时会产生冲突(只暴露,不裁决)。' : null,
+	}
+}
+
+/** 五种值形态的名字与一句话解释(名字取自 `domain-language` 的枚举,这里只加给人读的说明)。 */
+const VALUE_FORM_GLOSS = {
+	statement: '短陈述字符串',
+	quantity: '数值 + 单位',
+	formula: '公式源码(LaTeX;本版不做语义解析)',
+	code: '指向工作区里真有的文件路径',
+	reference: '外部引用(文献 / URL / 编号)',
+}
+
 export function derive(state) {
 	const activePlan = state.plans.find((plan) => plan.status === 'active') ?? null
 	const closedPlans = state.plans.filter((plan) => plan.status === 'closed')
@@ -987,6 +1714,13 @@ export function derive(state) {
 	 * 读的是事实上的 `review`——人的动作落在事实那一侧,facts 是唯一事实源。
 	 */
 	const retractedClaims = new Set((state.facts ?? []).filter((item) => item.review?.decision === 'retracted').map((item) => String(item.text ?? '')))
+	/** 同一件事,新的关联方式:事实带 `hypothesis` 时按 id 撤(文本只是旧账本的退路)。 */
+	const retractedHypotheses = new Set(
+		(state.facts ?? [])
+			.filter((item) => item.review?.decision === 'retracted')
+			.map((item) => item.hypothesis)
+			.filter((id) => typeof id === 'string' && id !== ''),
+	)
 	const hypotheses = state.hypotheses.map((hypothesis) => {
 		const rows = []
 		for (const item of state.evidence) {
@@ -1000,7 +1734,7 @@ export function derive(state) {
 			.reduce((best, item) => Math.max(best, levelIndex(item.level)), -1)
 		let status = hypothesis.status
 		// 撤回优先于一切:那是人对已升格事实的裁决,后来的支持证据不复活它。
-		if (retractedClaims.has(String(hypothesis.claim ?? ''))) status = 'retracted'
+		if (retractedHypotheses.has(hypothesis.id) || retractedClaims.has(String(hypothesis.claim ?? ''))) status = 'retracted'
 		else if (status === 'proposed' && rows.length > 0) status = 'alive'
 		// 被推翻是黏性终态:「已被替代」不该改写「已被推翻」——两件事。
 		if (status !== 'superseded' && status !== 'refuted' && status !== 'retracted' && refutations > 0) status = 'refuted'
@@ -1053,6 +1787,11 @@ export function derive(state) {
 		 *   · **升格算数**:回落口径里,被升格成事实的假设也算「已确认」——升格本来就是它最硬的确认。
 		 */
 		const promotedClaims = new Set((state.facts ?? []).map((item) => String(item.text ?? '')))
+		const promotedHypotheses = new Set(
+			(state.facts ?? [])
+				.map((item) => item.hypothesis)
+				.filter((id) => typeof id === 'string' && id !== ''),
+		)
 		const live = activePlan?.steps.filter((step) => step.status !== 'void') ?? []
 		if (state.goal?.status === 'achieved') progress = 1
 		else if (state.goal?.status === 'abandoned') progress = 0
@@ -1060,7 +1799,7 @@ export function derive(state) {
 		else {
 			const effective = hypotheses.filter((item) => item.status !== 'superseded' && item.status !== 'retracted')
 			if (effective.length > 0) {
-				const done = effective.filter((item) => item.status === 'confirmed' || promotedClaims.has(String(item.claim ?? ''))).length
+				const done = effective.filter((item) => item.status === 'confirmed' || promotedHypotheses.has(item.id) || promotedClaims.has(String(item.claim ?? ''))).length
 				progress = done / effective.length
 			}
 		}
@@ -1196,9 +1935,23 @@ export function derive(state) {
 	 *   · `review` ——人已经审查过(撤回 / 维持),决定连缘由一起留着。
 	 */
 	const factRows = (state.facts ?? []).map((fact) => {
-		const owner = hypotheses.find((item) => String(item.claim ?? '') === String(fact.text ?? ''))
+		const linked = typeof fact.hypothesis === 'string' && fact.hypothesis !== ''
+		const owner = hypotheses.find((item) => (linked ? item.id === fact.hypothesis : String(item.claim ?? '') === String(fact.text ?? '')))
 		return { ...fact, refuted: (owner?.refutations ?? 0) > 0, review: fact.review ?? null }
 	})
+
+	/**
+	 * **领域词汇的派生读数**(两条,都不新存东西):
+	 *   · `conflicts`——同一个单值谓词、同一主体、两个不同客体的**成对**事实。它是读数,
+	 *     不是裁决:这里不撤回任何一侧,也不判断哪条为真(那是证据与人的事)。
+	 *   · `lexiconHealth`——悬空引用、父链成环、没人用的条目、被废止条目仍在使用。
+	 *     全是提示,不拦任何操作。
+	 * 两者都吃 `factRows` 而不是 `state.facts`:事实的复核态与推翻标记是派生的,
+	 * 在这里重算一遍就等于第二份判据。
+	 */
+	const lexicon = normalizeLexicon(state.lexicon)
+	const conflicts = deriveConflicts(factRows, lexicon)
+	const lexiconIssues = lexiconHealth(lexicon, factRows)
 	for (const fact of factRows) {
 		/**
 		 * **推翻证据只标记事实,撤不撤由人定**(数据本身也可能是错的)。
@@ -1232,7 +1985,28 @@ export function derive(state) {
 		}
 	})
 
-	return { phase, progress, hypotheses, activePlan, closedPlans, pendingAudit, forks, factRows, settlement, stepOf, inbox, hasOpenGate, planConfirmationPending, planIsAuthorized }
+	return {
+		phase,
+		progress,
+		hypotheses,
+		activePlan,
+		closedPlans,
+		pendingAudit,
+		forks,
+		factRows,
+		settlement,
+		stepOf,
+		inbox,
+		hasOpenGate,
+		planConfirmationPending,
+		planIsAuthorized,
+		/** 领域词汇与它的两条派生读数(见上面那段:冲突与健康度都只是读数)。 */
+		lexicon,
+		conflicts,
+		lexiconIssues,
+		/** 知识模式(分诊)与缺口读数:结构判据,不猜词面(见 `deriveKnowledge`)。 */
+		knowledge: deriveKnowledge(state, hypotheses, factRows, lexicon),
+	}
 }
 
 /**
@@ -1266,7 +2040,24 @@ export function derive(state) {
  */
 export const HUMAN_GATE_MARK = '[clearai·人门]'
 /** 面板上允许出现的动词。表外的动词一律拒(与贡献表同一套「表外的名字不许出现」)。 */
-export const HUMAN_GATE_ACTIONS = ['adopt_branch', 'abandon_fork', 'promote_skill', 'retract_fact', 'keep_fact', 'confirm_provisional']
+export const HUMAN_GATE_ACTIONS = [
+	'adopt_branch',
+	'abandon_fork',
+	'promote_skill',
+	'retract_fact',
+	'keep_fact',
+	'confirm_provisional',
+	/**
+	 * **本体四动词(人的通道)**:面板抽屉发的就是它们;模型有同名语义的工具
+	 * (`RegisterTerm` 等),但这两个面落的是**同一套判据与同一本账**——判据在宿主半的
+	 * `domain` 门里,词汇事件只有一种折法。这个数组在内核那一侧有一份**逐字镜像**
+	 * (预设面不能 import 这一层),两边相等由 authority-boundary 套件钉死。
+	 */
+	'register_term',
+	'register_predicate',
+	'revise_term',
+	'deprecate_entry',
+]
 /** 运行档的两个取值。**只用于读取旧日志**里的 `set_autonomy` 记录;当前没有写入口。 */
 export const AUTONOMY_VALUES = ['attended', 'unattended']
 
@@ -1370,6 +2161,29 @@ export function view(state, sessionId) {
 		brain: state.brain ?? null,
 		/** 本体形状(面板页眉据此生成,不手抄)。 */
 		ontology: state.ontology ?? null,
+		/**
+		 * **领域词汇的读面**:概念、谓词、冲突、健康读数与图投影。
+		 *
+		 * 客户端不重算——它连折法都读不到(浏览器那半是独立模块),所以图在这里算好推下去。
+		 * 于是「同一份账本 ⇒ 同一张图」是投影的性质,不是两处渲染约定出来的巧合。
+		 */
+		lexicon: {
+			terms: derived.lexicon.terms,
+			predicates: derived.lexicon.predicates,
+			conflicts: derived.conflicts,
+			health: derived.lexiconIssues,
+			graph: graphProjection(state),
+		},
+		/**
+		 * **知识模式(分诊)**:面板据此把「这一格是知识主场还是普通进展」说清楚,
+		 * 与卡片读的是同一份派生(判据只有一处:`deriveKnowledge`)。
+		 */
+		knowledge: derived.knowledge,
+		/**
+		 * **知识预检**:进入知识模式那一刻的相关已知(词汇 / 事实 / 冲突,有界)。
+		 * 面板可以画它,内核的 pre-step 把它送进卡——判据与缺口读数一样,只有这一处。
+		 */
+		preflight: knowledgePreflight(state, derived),
 		/**
 		 * 续跑窗口的账:面板读它,于是「续跑停着——等裁决」这种**平台说不出来的话**
 		 * 有地方说。轮数与相位仍然只在原生 dock 上出现(一个事实只在**一块**面上说),
@@ -1413,6 +2227,10 @@ export function view(state, sessionId) {
 							/** 从没被走过的等级(派生):面板据此说清「这一级是跳上来的」。 */
 							untouchedLevels: hypothesis.untouchedLevels,
 							version: hypothesis.version,
+							/** 断言随假设走(未升格):面板同画芯片(chip 同样在投影侧算好),标注「未升格」。 */
+							assertions: Array.isArray(hypothesis.assertions)
+								? hypothesis.assertions.map((assertion) => ({ ...assertion, chip: formatAssertion(state.lexicon, assertion) }))
+								: null,
 						})),
 					},
 		/**
@@ -1542,6 +2360,11 @@ export function view(state, sessionId) {
 			evidenceIds: item.evidence,
 			path: item.path,
 			at: item.at,
+			/**
+			 * **类型化断言**(可 null):事实的内容形态。面板用它画断言芯片——
+			 * 点开就地展开词条卡,这是「事实 ↔ 本体」那座桥的界面侧。
+			 */
+			assertions: Array.isArray(item.assertions) ? item.assertions : null,
 			/** 派生:收到过推翻证据(要复核)与人的审查决定(撤回 / 维持)。 */
 			refuted: item.refuted === true,
 			review: item.review ?? null,
@@ -1681,10 +2504,48 @@ export function renderCard(state) {
 			lines.push(`  · ${hypothesis.id} [${hypothesis.status}] ${hypothesis.claim} — 推翻条件:${hypothesis.refute_when}${readings}`)
 		}
 	}
+	/**
+	 * **知识模式与缺口**:这一行是「分诊」在模型侧的全部可见面。
+	 *
+	 * 普通任务**一个字都不加**(提示词与卡片同一条零成本纪律:不立约的会话不长出新字节)。
+	 * 进了这一档才报,而且报的是**缺口 + 指得出动作的读数**,不是纪律条文——
+	 * 真跑里模型跳过本体步骤不是因为不知道有这件工具,而是因为完成函数里没有它;
+	 * 缺口逐回合摆在卡上,那件事才进得了它的视野。
+	 */
+	if (derived.knowledge.mode === 'knowledge') {
+		lines.push(`- 知识模式:${derived.knowledge.why}`)
+		/**
+		 * **知识预检**:与缺口同一拍出现的相关已知。
+		 *
+		 * 它解决的是「模型不查就开工」——相关性判断在这里做完(词面命中,逐条可复核),
+		 * 模型拿到的是**可以直接引用的 id 清单**,而不是一句「去查 QueryKnowledge」。
+		 * 没有命中时如实说「没找到相关的」,不把空读数写成「世上没有」。
+		 */
+		const preflight = knowledgePreflight(state, derived)
+		if (preflight !== null) {
+			if (preflight.terms.length > 0 || preflight.predicates.length > 0) {
+				const more = (count) => (count > 0 ? `(还有 ${count} 个未列出)` : '')
+				lines.push(
+					`  · 相关已知(词面命中,可直接引用):概念 ${preflight.terms.map((term) => `${term.id}${term.label === term.id ? '' : `(${term.label})`}`).join('、') || '无'}${more(preflight.termsTruncated)};谓词 ${preflight.predicates.map((predicate) => `${predicate.id}${predicate.label === predicate.id ? '' : `(${predicate.label})`}`).join('、') || '无'}${more(preflight.predicatesTruncated)}`,
+				)
+				if (preflight.facts.length > 0) {
+					lines.push(`  · 可复用事实 ${preflight.facts.length} 条:${preflight.facts.map((fact) => `${fact.id}(${fact.level ?? '?'})`).join('、')}${preflight.factsTruncated > 0 ? `(还有 ${preflight.factsTruncated} 条未列出)` : ''}`)
+				}
+			} else {
+				lines.push('  · 相关已知:当前主张文本没有命中任何已有概念 / 谓词——要写断言就先立词(带依据),别把查不到当成不存在')
+			}
+		}
+		if (derived.knowledge.gaps.length === 0) {
+			lines.push('  · 结构完整:语言、断言的命题、带断言的已升格事实、证据覆盖这四项今天都不欠')
+		} else {
+			const total = derived.knowledge.gaps.reduce((sum, gap) => sum + gap.count, 0)
+			lines.push(`  · 缺口 ${total} 条(${derived.knowledge.gaps.map((gap) => `${gap.code} ${gap.count}`).join(' · ')}):`)
+			for (const gap of derived.knowledge.gaps) lines.push(`    - ${gap.detail}`)
+		}
+	}
 	if (plan === null) {
 		lines.push('- 当前计划:无活动计划')
-	} else {
-		if (derived.planConfirmationPending) {
+	} else {		if (derived.planConfirmationPending) {
 			/**
 			 * 授权记号的语义:它是**归属**,不是闸门。
 			 *
@@ -1761,6 +2622,27 @@ export function renderCard(state) {
 		lines.push(`- 最近一条证据:${last.id} ${last.verdict}(${last.evaluator} · ${last.level})`)
 	}
 	if (state.facts.length > 0) lines.push(`- 已升格事实:${state.facts.length} 条`)
+	/**
+	 * **领域词汇与类型化事实**的一句话读数。
+	 *
+	 * 为什么要进卡片:模型要靠它决定「这条结论能不能写成断言、要不要先登记词」。而**冲突**
+	 * 必须说出来、但不许自动处置——卡片只报数并指向那两条事实,撤不撤由人(或由证据)定。
+	 * 事实没有断言时也报一句:那是「这门语言还没用起来」的读数,不是错误。
+	 */
+	{
+		const lexicon = derived.lexicon
+		const typed = state.facts.filter((fact) => Array.isArray(fact.assertions) && fact.assertions.length > 0).length
+		if (lexicon.terms.length > 0 || lexicon.predicates.length > 0) {
+			lines.push(`- 领域词汇:${lexicon.terms.length} 个概念 · ${lexicon.predicates.length} 个谓词;已升格事实里 ${typed}/${state.facts.length} 条带类型化断言`)
+			if (derived.lexiconIssues.some((issue) => issue.severity === 'warning')) lines.push(`  · 词汇健康度有 ${derived.lexiconIssues.filter((issue) => issue.severity === 'warning').length} 条待看(悬空引用 / 成环;在面板「本体」里)`)
+		}
+		if (derived.conflicts.length > 0) {
+			for (const conflict of derived.conflicts) {
+				const sides = conflict.sides.map((side) => `${side.fact ?? '?'}(${side.value})`).join(' 对 ')
+				lines.push(`- **冲突(${conflict.predicate} · ${conflict.subject})**:${sides}——两条都还没被撤回。它是读数不是裁决:要么用证据推翻一侧,要么由人撤回一侧;系统不替你选。`)
+			}
+		}
+	}
 	// 结案时留的痕:未判的假设不是「没问题」,是「没看过」——结案之后也要看得见。
 	if (Array.isArray(goal?.unjudged) && goal.unjudged.length > 0) lines.push(`- 结案留痕:有 ${goal.unjudged.length} 条假设没有被任何证据触及(${goal.unjudged.join(', ')})`)
 	/**