clearai-dsh 0.4.0 → 0.5.0

package/lib/domain-language.js

@@ -1026,12 +1026,17 @@ export function describeDomainGraph(lexicon) {
 //
 // 会话账本只活在一次会话里,而研究要跨会话攒下来。所以「攒下来的东西」住在工作区的文件里:
 //   · `clear/knowledge/facts/<id>.json`:升格的事实,一条一个文件,只有系统写;
+//   · `clear/knowledge/lessons/<id>.json`:结案时经独立评估核过的经验,一条一个文件,只有系统写;
 //   · `clear/ontology/{concepts,relations,entities}/**.json`:本体,模型用原生文件工具直接写。
 // 内核每一拍把这两处的变化折成一条 `workspace/synced` 变更,投影从文件内容派生词汇、实体与
 // 事实——折法仍然只吃账本,文件是账本之外唯一的输入,而且进账本时就是一条可重放的事实。
 
 /** 事实文件所在的目录(相对工作区)。 */
 export const FACTS_DIR = 'clear/knowledge/facts'
+/** 经验文件所在的目录(相对工作区)。 */
+export const LESSONS_DIR = 'clear/knowledge/lessons'
+/** 经验的四类:坑、要核的读数、会骗人的捷径、先验。 */
+export const LESSON_KINDS = ['trap', 'check', 'shortcut', 'prior']
 /** 本体文件树的根(相对工作区)。 */
 export const ONTOLOGY_DIR = 'clear/ontology'
 /** 本体文件树的三支:目录名 → 文件种类。 */
@@ -1056,7 +1061,11 @@ function hashText(value) {
  */
 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) }
+	/** 单位与形状只在写了时进指纹:没写这两格的旧词条,指纹与从前逐字相同。 */
+	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, ...(text(entry.shape) === '' ? {} : { shape: text(entry.shape) }) }
+			: { gloss: text(entry.gloss), parent: text(entry.parent), ...(text(entry.unit) === '' ? {} : { unit: text(entry.unit) }) }
 	return `fnv:${hashText(JSON.stringify(meaning))}`
 }
 
@@ -1114,6 +1123,8 @@ export function classifyWorkspacePath(path) {
 	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 lessons = LESSONS_DIR.split('/')
+	if (parts.length === lessons.length + 1 && lessons.every((part, index) => parts[index] === part)) return { kind: 'lesson', 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]]
@@ -1145,6 +1156,26 @@ export function factFromFile(data, path) {
 	}
 }
 
+/**
+ * 经验文件 → 经验行(与 `lesson/recorded` 折出来的同形)。`status: "retracted"` 的不再推送。
+ * 经验改变的是注意力与做法(「这台装置的温度要拿参考读数核」),事实改变的是信念。
+ */
+export function lessonFromFile(data, path) {
+	if (!isPlainObject(data) || text(data.id) === '' || text(data.text) === '') return null
+	return {
+		id: text(data.id),
+		goal: data.goal ?? null,
+		text: String(data.text),
+		kind: LESSON_KINDS.includes(data.kind) ? data.kind : 'trap',
+		about: Array.isArray(data.about) ? data.about.map(String).filter((item) => item.trim() !== '').slice(0, 6) : [],
+		evidence: typeof data.evidence === 'string' ? data.evidence : null,
+		boundary: typeof data.boundary === 'string' ? data.boundary : null,
+		status: data.status === 'retracted' ? 'retracted' : 'active',
+		path: path ?? null,
+		at: typeof data.at === 'number' ? data.at : null,
+	}
+}
+
 // ═══ 本体文件树:字段、单文件校验、从文件折出词汇与实体 ═════════════════════════
 //
 // 本体由模型用原生文件工具直接写,住在 `clear/ontology/{concepts,relations,entities}/` 下:
@@ -1164,6 +1195,14 @@ const ONTOLOGY_STATUS = ['active', 'deprecated']
  * 三种本体文件的字段定义。内核把它铺成 `clear/ontology/SCHEMA.json`(只读),
  * 写入时的校验与这份定义是同一份:字段在这里改,两边一起变。
  */
+/**
+ * **本体只留能产出预期的东西**:概念分三类,度量必须写单位(释义就是口径);关系分四类,
+ * 「影响」带大致形状——预期就从这里来(「温度升,杂质单调升」);「测量」写清怎么核读数。
+ */
+export const CONCEPT_KINDS = ['category', 'measure', 'phenomenon']
+export const RELATION_KINDS = ['affects', 'defines', 'measures', 'manifests_as']
+export const RELATION_SHAPES = ['increasing', 'decreasing', 'peak', 'threshold', 'coupled']
+
 export const ONTOLOGY_SCHEMA = bilingual({
 	about: [
 		'本体文件的字段定义(系统铺设,只读)。命名规则:X.json 描述节点 X,它的子节点放在同级的 X/ 目录里;id 必须等于文件名。概念目录嵌套 = is_a;实体目录嵌套 = 组成 / 属于;关系可以平铺,也可以分目录(只是分组)。引用一律只写 id,挪目录不断引用。写入时只查单个文件;引用断了、类型对不上等跨文件问题在卡片上提示,升格时才拦。',
@@ -1174,9 +1213,11 @@ export const ONTOLOGY_SCHEMA = bilingual({
 		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'],
+			gloss: ['一句话释义:它指什么;度量(良率、收率……)写明口径,也就是怎么算', 'one-sentence gloss: what it refers to; for a measure (yield, conversion …) state its definition, that is, how it is computed'],
 		},
 		optional: {
+			kind: ['category = 类别(反应器、催化剂);measure = 度量(收率、杂质,要写 unit);phenomenon = 现象(漂移、失活)', 'category (reactor, catalyst); measure (yield, impurity; needs unit); phenomenon (drift, deactivation)'],
+			unit: ['单位(度量必填,无量纲写 "1")', 'unit (required for a measure; "1" if dimensionless)'],
 			aliases: ['别名数组', 'array of aliases'],
 			basis: ['依据:哪份材料让这个词成立', 'basis: which material establishes this term'],
 			status: 'active | deprecated',
@@ -1203,6 +1244,9 @@ export const ONTOLOGY_SCHEMA = bilingual({
 		},
 		optional: {
 			gloss: ['一句话释义', 'one-sentence gloss'],
+			kind: ['affects = 影响(一个量怎样随另一个量变);defines = 定义(一个度量怎么算);measures = 测量(哪个仪器测哪个量);manifests_as = 表现为(一个现象在读数上什么样)', 'affects (how one quantity moves with another); defines (how a measure is computed); measures (which instrument reads which quantity); manifests_as (what a phenomenon looks like in the readings)'],
+			shape: [`影响的大致形状:${RELATION_SHAPES.join(' | ')};预期从这里来`, `rough shape of an effect: ${RELATION_SHAPES.join(' | ')}; expectations come from it`],
+			check: ['测量关系:读数怎么核(参考探头、标样、重复点)', 'for a measurement: how to check the reading (reference probe, standard, repeat point)'],
 			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'],
@@ -1226,6 +1270,7 @@ export const ONTOLOGY_SCHEMA = bilingual({
 		},
 		optional: {
 			aliases: ['别名数组', 'array of aliases'],
+			history: ['带日期的经历:[{"at": "YYYY-MM-DD", "what": "校准 / 更换 / 发现漂移", "evidence"?: {"kind", "ref"}}]', 'dated history: [{"at": "YYYY-MM-DD", "what": "calibrated / replaced / drift found", "evidence"?: {"kind", "ref"}}]'],
 			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"}',
@@ -1247,10 +1292,11 @@ export const ONTOLOGY_SCHEMA = bilingual({
 })
 
 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'],
+	concept: ['id', 'label', 'gloss', 'kind', 'unit', 'aliases', 'basis', 'status', 'replaced_by', 'note'],
+	relation: ['id', 'label', 'gloss', 'kind', 'shape', 'check', 'domain', 'range', 'functional', 'basis', 'status', 'replaced_by', 'note'],
+	entity: ['id', 'label', 'type', 'basis', 'provenance', 'aliases', 'relations', 'history', 'note'],
 }
+
 const RELATION_FIELDS = ['predicate', 'object', 'value', 'unit', 'evidence', 'note']
 
 /** 一个出处对象的形状问题(没有就返回 null)。 */
@@ -1269,7 +1315,7 @@ function evidenceShape(value, at) {
  */
 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`)]
+	if (place === null || place.kind === 'fact' || place.kind === 'lesson') 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 {
@@ -1298,9 +1344,18 @@ export function checkOntologyFile(path, content) {
 	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 === 'concept') {
+		if (data.kind !== undefined && !CONCEPT_KINDS.includes(text(data.kind))) problems.push(tr(`kind 只能是 ${CONCEPT_KINDS.join(' / ')}(类别 / 度量 / 现象)`, `kind must be ${CONCEPT_KINDS.join(' / ')}`))
+		if (data.unit !== undefined && typeof data.unit !== 'string') problems.push(tr('unit 只能是字符串', 'unit must be a string'))
+		if (text(data.kind) === 'measure' && text(data.unit) === '') problems.push(tr('度量要写 unit(无量纲写 "1"):口径和单位不写下来,「定义已变」就无从发现', 'a measure needs a unit (write "1" if dimensionless): without the definition and unit written down, a changed definition cannot be noticed'))
+	}
 	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'))
+		if (data.kind !== undefined && !RELATION_KINDS.includes(text(data.kind))) problems.push(tr(`kind 只能是 ${RELATION_KINDS.join(' / ')}(影响 / 定义 / 测量 / 表现为)`, `kind must be ${RELATION_KINDS.join(' / ')}`))
+		if (data.shape !== undefined && !RELATION_SHAPES.includes(text(data.shape))) problems.push(tr(`shape 只能是 ${RELATION_SHAPES.join(' / ')}(单调升 / 单调降 / 有峰 / 阈值 / 与别的量耦合)`, `shape must be ${RELATION_SHAPES.join(' / ')}`))
+		if (data.shape !== undefined && data.kind !== undefined && text(data.kind) !== 'affects') problems.push(tr('shape 只给「影响」(kind=affects)的关系', 'shape only applies to an affects relation (kind=affects)'))
+		if (data.check !== undefined && typeof data.check !== 'string') problems.push(tr('check 只能是字符串', 'check must be a string'))
 		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'))
@@ -1319,6 +1374,13 @@ export function checkOntologyFile(path, content) {
 		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.history !== undefined) {
+			if (!Array.isArray(data.history)) problems.push(tr('history 只能是数组', 'history must be an array'))
+			else
+				data.history.forEach((item, index) => {
+					if (!isPlainObject(item) || !/^\d{4}-\d{2}-\d{2}/.test(text(item.at)) || text(item.what) === '') problems.push(tr(`history[${index}] 要是 {"at": "YYYY-MM-DD", "what": "发生了什么"}`, `history[${index}] must be {"at": "YYYY-MM-DD", "what": "what happened"}`))
+				})
+		}
 		if (data.relations !== undefined) {
 			if (!Array.isArray(data.relations)) problems.push(tr('relations 只能是数组', 'relations must be an array'))
 			else
@@ -1361,7 +1423,7 @@ export function materializeOntology(files) {
 	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')
+		.filter((item) => item.place !== null && item.place.kind !== 'fact' && item.place.kind !== 'lesson')
 		.sort((a, b) => (a.path < b.path ? -1 : 1))
 	const terms = []
 	const predicates = []
@@ -1389,9 +1451,9 @@ export function materializeOntology(files) {
 		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 })
+			terms.push({ id: place.id, label: text(data.label), gloss: text(data.gloss), ...(CONCEPT_KINDS.includes(text(data.kind)) ? { kind: text(data.kind) } : {}), ...(text(data.unit) === '' ? {} : { unit: text(data.unit) }), 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 })
+			predicates.push({ id: place.id, label: text(data.label), gloss: text(data.gloss), ...(RELATION_KINDS.includes(text(data.kind)) ? { kind: text(data.kind) } : {}), ...(RELATION_SHAPES.includes(text(data.shape)) ? { shape: text(data.shape) } : {}), ...(text(data.check) === '' ? {} : { check: text(data.check) }), 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 })
 		}

package/lib/fold.js

@@ -16,7 +16,7 @@
  * 与预设内核的契约:`meta = { kind: 'clearai', v: 1, mutation: { t, ... } }`。
  * 词汇表由本文件的 `applyMutation` 定义;预设侧只负责产出,不负责解释。
  */
-import { applyLexiconMutation, changedDefinitions, materializeOntology, classifyWorkspacePath, deriveConflicts, emptyLexicon, factFromFile, formatAssertion, graphProjection, lexiconHealth, normalizeLexicon, objectKey, termUsage, VALUE_FORMS } from './domain-language.js'
+import { applyLexiconMutation, changedDefinitions, materializeOntology, classifyWorkspacePath, deriveConflicts, emptyLexicon, factFromFile, formatAssertion, lessonFromFile, graphProjection, lexiconHealth, normalizeLexicon, objectKey, termUsage, VALUE_FORMS } from './domain-language.js'
 import { handleOf, knowledgeView, trustOf } from './knowledge-view.js'
 import { bilingual, detectLanguage, messageText, tr, withLanguage } from './lang.js'
 
@@ -60,9 +60,15 @@ export const MUTATION_KIND = 'clearai'
  *           `definitionsChanged`。本体(词汇、实体、实体关系)改为从本体文件折出来,跨文件问题记在
  *           `ontologyProblems`。旧日志里没有这些,折出来就是空的。
  *   v15 → v16:多了 `language`(人说话用的语言,从人的消息折出来):系统写给人的话、面板里的读数都跟着它。
+ *   v16 → v17:**预期与未解释**:步骤带 `expect`(`step/expected` 也能补写);多了 `anomalies`(未解释项,
+ *           `anomaly/opened` / `anomaly/resolved` 折进来,评估者报的随 `audit/settled` 一起来);目标带
+ *           `irreversible`(不可逆动作的命令特征);放行带 `action`。对手判断(`rival` / `split_by`)删了,
+ *           旧账里的这两格不再读。
+ *   v17 → v18:多了 `lessons`(经验:结案时经独立评估核过的「下次要留意什么」,`lesson/recorded` 折进来;
+ *           别的会话留下的从 `clear/knowledge/lessons/<id>.json` 经 `workspace/synced` 进来)。
  * 投影缓存按版本判定,所以旧缓存会被丢弃、从日志重折一遍。
  */
-export const STATE_VERSION = 16
+export const STATE_VERSION = 18
 
 /**
  * **只留台账、不折进视图**的变更类型(词汇表的另一半)。
@@ -89,6 +95,13 @@ export function emptyState() {
 		facts: [],
 		blocks: {},
 		releases: [],
+		/**
+		 * **未解释项**(认识论里的「反常」):和预期或本体对不上的观测。只有三个去处:
+		 * 被解释(`explained`)、写明理由排除(`ruled_out`)、交给人(`escalated`);没去处的就是开着(`open`)。
+		 */
+		anomalies: [],
+		/** **经验**:本会话结案写下的(别的会话的在工作区文件里,派生时合进来)。 */
+		lessons: [],
 		/**
 		 * **本体形状**:内核随投影下发的那份声明(对象/状态/边/等级)。
 		 * 为什么进投影而不是在界面里手抄:面板那一格的页眉要从**声明**生成——
@@ -205,6 +218,8 @@ function appendSteps(plan, rawSteps) {
 			artifacts: raw.artifacts ?? [],
 			done_criteria: raw.done_criteria,
 			tests: normalizeTests(raw.tests),
+			/** 动手前写下的预期(可选);落空的地方记成未解释项。 */
+			expect: typeof raw.expect === 'string' && raw.expect !== '' ? raw.expect : null,
 			status: 'open',
 			evidence: null,
 			advancedAt: null,
@@ -226,6 +241,7 @@ export function applyMutation(state, mutation) {
 	if (mutation === null || typeof mutation !== 'object' || typeof mutation.t !== 'string') return state
 	const at = typeof mutation.at === 'number' ? mutation.at : 0
 	const next = clone(state)
+	if (!Array.isArray(next.anomalies)) next.anomalies = []
 	const RANK = { open: 0, blocked: 0, advanced: 1, void: 1 }
 	const settle = (step, status) => {
 		if (step === undefined || step === null) return
@@ -243,6 +259,7 @@ export function applyMutation(state, mutation) {
 				previous.claim = mutation.claim
 				previous.done_criteria = mutation.done_criteria
 				previous.promote_at_level = mutation.promote_at_level
+				if (Array.isArray(mutation.irreversible)) previous.irreversible = clone(mutation.irreversible)
 				/** 修订可以带上新的速览与判据清单(没带就保持旧值——「不提供」不等于「清空」)。 */
 				if (typeof mutation.headline === 'string' && mutation.headline !== '') previous.headline = mutation.headline
 				if (Array.isArray(mutation.criteria)) previous.criteria = clone(mutation.criteria)
@@ -255,6 +272,8 @@ export function applyMutation(state, mutation) {
 					claim: mutation.claim,
 					done_criteria: mutation.done_criteria,
 					promote_at_level: mutation.promote_at_level,
+					/** 不可逆动作:`{action, command}`,命令里出现 `command` 那段原文就要人放行。 */
+					irreversible: Array.isArray(mutation.irreversible) ? clone(mutation.irreversible) : [],
 					status: 'open',
 					revision: mutation.revision ?? 1,
 					reasons: [mutation.reason ?? null],
@@ -297,6 +316,7 @@ export function applyMutation(state, mutation) {
 					known.refute_when = hypothesis.refute_when
 					known.version = hypothesis.version ?? known.version
 					if (typeof hypothesis.name === 'string' && hypothesis.name !== '') known.name = hypothesis.name
+					if (typeof hypothesis.retests === 'string' && hypothesis.retests !== '') known.retests = hypothesis.retests
 					if (Array.isArray(hypothesis.assertions)) known.assertions = clone(hypothesis.assertions)
 					continue
 				}
@@ -307,6 +327,8 @@ export function applyMutation(state, mutation) {
 					...(typeof hypothesis.name === 'string' && hypothesis.name !== '' ? { name: hypothesis.name } : {}),
 					claim,
 					refute_when: hypothesis.refute_when,
+					/** 复检的是哪条已有事实(事实 id;可以是别的会话留下的)。 */
+					...(typeof hypothesis.retests === 'string' && hypothesis.retests !== '' ? { retests: hypothesis.retests } : {}),
 					status: 'proposed',
 					version: hypothesis.version ?? 1,
 					/**
@@ -378,6 +400,44 @@ export function applyMutation(state, mutation) {
 			step.criteria_versions.push(mutation.new_criteria) // 旧版本留着,什么都不删
 			break
 		}
+		case 'step/expected': {
+			const step = stepOf(mutation.plan, mutation.step)
+			if (step === undefined || step.status !== 'open') break
+			step.expect = String(mutation.expect ?? '') || null
+			break
+		}
+		case 'anomaly/opened': {
+			if (next.anomalies.some((item) => item.id === mutation.id)) break
+			next.anomalies.push({ id: mutation.id, what: String(mutation.what ?? ''), anchor: mutation.anchor ?? null, step: mutation.step ?? null, by: mutation.by ?? 'model', status: 'open', reason: null, explainedBy: null, at, resolvedAt: null })
+			break
+		}
+		case 'lesson/recorded': {
+			if (!Array.isArray(next.lessons)) next.lessons = []
+			if (next.lessons.some((item) => item.id === mutation.id)) break
+			next.lessons.push({
+				id: mutation.id,
+				goal: mutation.goal ?? null,
+				text: String(mutation.text ?? ''),
+				kind: mutation.kind ?? 'trap',
+				about: Array.isArray(mutation.about) ? mutation.about.map(String) : [],
+				evidence: mutation.evidence ?? null,
+				boundary: mutation.boundary ?? null,
+				status: 'active',
+				path: mutation.path ?? null,
+				at,
+			})
+			break
+		}
+		case 'anomaly/resolved': {
+			const item = next.anomalies.find((entry) => entry.id === mutation.id)
+			if (item === undefined || item.status !== 'open') break
+			if (!['explained', 'ruled_out', 'escalated'].includes(mutation.outcome)) break
+			item.status = mutation.outcome
+			item.reason = mutation.reason ?? null
+			item.explainedBy = mutation.by ?? null
+			item.resolvedAt = at
+			break
+		}
 		case 'plan/voided': {
 			const step = stepOf(mutation.plan, mutation.step)
 			if (step === undefined) break
@@ -484,6 +544,13 @@ export function applyMutation(state, mutation) {
 				audit.card_path = mutation.card_path ?? null
 				if (mutation.digest !== undefined) audit.digest = mutation.digest ?? null
 			}
+			/** 评估者报的、做的人没登记的异常:记成未解释项(id 由裁决 id 派生,重放幂等)。 */
+			const found = Array.isArray(mutation.anomalies) ? mutation.anomalies : []
+			for (const [index, item] of found.entries()) {
+				const id = `${mutation.id}#u${index + 1}`
+				if (next.anomalies.some((entry) => entry.id === id)) continue
+				next.anomalies.push({ id, what: String(item?.what ?? ''), anchor: null, step: mutation.step ?? null, by: 'evaluator', matters: item?.matters ?? null, status: 'open', reason: null, explainedBy: null, at, resolvedAt: null })
+			}
 			break
 		}
 		case 'evidence/recorded': {
@@ -534,6 +601,8 @@ export function applyMutation(state, mutation) {
 				via: mutation.via ?? null,
 				at,
 				call: mutation.call ?? null,
+				/** 放行的是哪件不可逆动作(拦在命令上的那道门);步级放行没有这一格。 */
+				...(typeof mutation.action === 'string' && mutation.action !== '' ? { action: mutation.action } : {}),
 			})
 			break
 		}
@@ -584,9 +653,9 @@ export function applyMutation(state, mutation) {
 			 */
 			const touchedOntology = (mutation.changes ?? []).some((change) => {
 				const kind = classifyWorkspacePath(change?.path)?.kind
-				return kind !== undefined && kind !== 'fact'
+				return kind !== undefined && kind !== 'fact' && kind !== 'lesson'
 			})
-			if (touchedOntology || Object.keys(files).some((path) => classifyWorkspacePath(path)?.kind !== 'fact')) {
+			if (touchedOntology || Object.keys(files).some((path) => !['fact', 'lesson'].includes(classifyWorkspacePath(path)?.kind))) {
 				const ontology = materializeOntology(files)
 				next.lexicon = ontology.lexicon
 				next.entities = ontology.entities
@@ -1077,7 +1146,9 @@ export function knowledgePreflight(state, derived) {
 	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 nextStep = (derived?.activePlan?.steps ?? []).find((step) => step?.status === 'open') ?? null
+	const claimText = [state?.goal?.claim, ...hypotheses.map((item) => item.claim), nextStep?.do, nextStep?.expect].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) => {
@@ -1089,19 +1160,27 @@ export function knowledgePreflight(state, derived) {
 	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 ?? ''))),
+	/**
+	 * 事实:断言引用了命中的谓词或概念;**或**升格时按词面挂上的定义里有命中的词(真跑里事实几乎都没有断言,
+	 * 只认断言等于从不命中);**或**有判断用 `retests` 指着它。撤回的不给。
+	 */
+	const retested = new Set(hypotheses.map((item) => item.retests).filter((id) => typeof id === 'string'))
+	const matchedFacts = factRows.filter(
+		(fact) =>
+			fact.review?.decision !== 'retracted' &&
+			(retested.has(fact.id) ||
+				Object.keys(fact.definitions ?? {}).some((id) => matchedTermIds.has(id) || matchedPredicateIds.has(id)) ||
+				(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 })),
+		terms: matchedTerms.slice(0, LIMIT).map((term) => ({ id: term.id, label: term.label, gloss: term.gloss, kind: term.kind ?? null, unit: term.unit ?? null, 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 })),
+		predicates: matchedPredicates.slice(0, LIMIT).map((predicate) => ({ id: predicate.id, label: predicate.label, gloss: predicate.gloss ?? '', kind: predicate.kind ?? null, shape: predicate.shape ?? null, check: predicate.check ?? null, 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 })),
+		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, foreign: fact.foreign === true })),
 		factsTruncated: Math.max(0, matchedFacts.length - LIMIT),
 		/** 冲突:有就带上(它们约束「哪些结论还不能随便写)。 */
 		conflicts: conflicts.map((conflict) => ({ predicate: conflict.predicate, subject: conflict.subject })),
@@ -1685,15 +1764,18 @@ export function derive(state) {
 	 *   · `review` ——人已经审查过(撤回 / 维持),决定连缘由一起留着。
 	 */
 	const lexicon = normalizeLexicon(state.lexicon)
+	/** 声明了 `retests` 的判断被推翻 ⇒ 它复检的那条事实也算被推翻(跨会话只认事实 id)。 */
+	const retestRefuted = new Set(hypotheses.filter((item) => typeof item.retests === 'string' && (item.refutations ?? 0) > 0).map((item) => item.retests))
 	const ownFacts = (state.facts ?? []).map((fact) => {
 		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, foreign: false }
+		return { ...fact, refuted: (owner?.refutations ?? 0) > 0 || retestRefuted.has(fact.id), review: fact.review ?? null, foreign: false }
 	})
 	/**
 	 * **别的会话留下的事实**(住在 `clear/knowledge/facts/<id>.json`,经 `workspace/synced` 进账)。
 	 * 同一个 id 本会话账上也有就以账上那条为准(它带着推翻读数);文件上的复核结论照样认。
-	 * 它们的假设不在本会话,所以 `refuted` 只能是 false——推翻要在这里重新检验一次才算。
+	 * 它们的假设不在本会话,所以推翻要在这里重新检验一次才算:本会话的判断用 `retests` 指向它,
+	 * 那条判断被推翻,这条事实就标「被推翻」。
 	 */
 	const ownIds = new Set(ownFacts.map((fact) => fact.id))
 	const foreignFacts = []
@@ -1706,7 +1788,7 @@ export function derive(state) {
 			if (own.review === null && row.review !== null) own.review = row.review
 			continue
 		}
-		foreignFacts.push({ ...row, refuted: false, foreign: true })
+		foreignFacts.push({ ...row, refuted: retestRefuted.has(row.id), foreign: true })
 	}
 	foreignFacts.sort((a, b) => (a.at ?? 0) - (b.at ?? 0))
 	/**
@@ -1724,6 +1806,18 @@ export function derive(state) {
 	 * 两者都吃 `factRows` 而不是 `state.facts`:事实的复核态与推翻标记是派生的,
 	 * 在这里重算一遍就等于第二份判据。
 	 */
+	/**
+	 * **经验行**:本会话写下的,加上别的会话留在 `clear/knowledge/lessons/` 的。同 id 以文件为准
+	 * (人可以在文件上标 `status: "retracted"` 撤回);撤回的不再推送。新的在前。
+	 */
+	const lessonById = new Map()
+	for (const item of state.lessons ?? []) lessonById.set(item.id, { ...item })
+	for (const [path, file] of Object.entries(state.workspace?.files ?? {})) {
+		if (classifyWorkspacePath(path)?.kind !== 'lesson' || file?.data === undefined) continue
+		const row = lessonFromFile(file.data, path)
+		if (row !== null) lessonById.set(row.id, { ...lessonById.get(row.id), ...row, at: row.at ?? lessonById.get(row.id)?.at ?? null })
+	}
+	const lessonRows = [...lessonById.values()].filter((item) => item.status !== 'retracted').sort((a, b) => (b.at ?? 0) - (a.at ?? 0))
 	const conflicts = deriveConflicts(factRows, lexicon)
 	const lexiconIssues = lexiconHealth(lexicon, factRows)
 	/**
@@ -1771,6 +1865,7 @@ export function derive(state) {
 		closedPlans,
 		pendingAudit,
 		factRows,
+		lessonRows,
 		settlement,
 		stepOf,
 		needYou,