clearai-dsh 0.2.0 → 0.2.2

package/lib/fold.js

@@ -16,7 +16,7 @@
  * 与预设内核的契约:`meta = { kind: 'clearai', v: 1, mutation: { t, ... } }`。
  * 词汇表由本文件的 `applyMutation` 定义;预设侧只负责产出,不负责解释。
  */
-import { applyLexiconMutation, deriveConflicts, emptyLexicon, formatAssertion, graphProjection, lexiconHealth, normalizeLexicon } from './domain-language.js'
+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 }
@@ -285,10 +285,30 @@ 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,
@@ -813,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 }
+	})
+}
+
 /**
  * 会话日志事件 → 状态。这是投影的入口:除了工具结果里的变更记录,
  * 还吃三条**关于过程本身的事实**——
@@ -893,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 {
@@ -1034,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
@@ -1048,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')
@@ -1350,6 +2004,8 @@ export function derive(state) {
 		lexicon,
 		conflicts,
 		lexiconIssues,
+		/** 知识模式(分诊)与缺口读数:结构判据,不猜词面(见 `deriveKnowledge`)。 */
+		knowledge: deriveKnowledge(state, hypotheses, factRows, lexicon),
 	}
 }
 
@@ -1518,6 +2174,16 @@ export function view(state, sessionId) {
 			health: derived.lexiconIssues,
 			graph: graphProjection(state),
 		},
+		/**
+		 * **知识模式(分诊)**:面板据此把「这一格是知识主场还是普通进展」说清楚,
+		 * 与卡片读的是同一份派生(判据只有一处:`deriveKnowledge`)。
+		 */
+		knowledge: derived.knowledge,
+		/**
+		 * **知识预检**:进入知识模式那一刻的相关已知(词汇 / 事实 / 冲突,有界)。
+		 * 面板可以画它,内核的 pre-step 把它送进卡——判据与缺口读数一样,只有这一处。
+		 */
+		preflight: knowledgePreflight(state, derived),
 		/**
 		 * 续跑窗口的账:面板读它,于是「续跑停着——等裁决」这种**平台说不出来的话**
 		 * 有地方说。轮数与相位仍然只在原生 dock 上出现(一个事实只在**一块**面上说),
@@ -1838,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) {
 			/**
 			 * 授权记号的语义:它是**归属**,不是闸门。
 			 *