clearai-dsh 0.1.7 → 0.2.1

package/presets/clearai/plugins/clearai-kernel.js

@@ -401,7 +401,22 @@ export const HUMAN_GATE_MARK = '[clearai·人门]'
  * 两侧白名单一旦各自维护,摘动词时只改一侧 ⇒ 内核仍认、宿主不认 ⇒ **等价性用例立刻红** ✓。
  * 这正是那条用例存在的意义:两份实现漂移不许静默。
  */
-export const HUMAN_GATE_ACTIONS = ['adopt_branch', 'abandon_fork', 'promote_skill', 'retract_fact', 'keep_fact', 'confirm_provisional']
+/**
+ * **逐字镜像 `ui/lib/fold.js` 的同名清单**(预设面不能 import 宿主半,于是只能两份;
+ * 两份相等由 `test/authority-boundary.test.mjs` 钉死——它红的时候,是清单漂了,不是测试坏了)。
+ */
+export const HUMAN_GATE_ACTIONS = [
+	'adopt_branch',
+	'abandon_fork',
+	'promote_skill',
+	'retract_fact',
+	'keep_fact',
+	'confirm_provisional',
+	'register_term',
+	'register_predicate',
+	'revise_term',
+	'deprecate_entry',
+]
 export function parseHumanGateMessage(message) {
 	if (message === null || typeof message !== 'object') return null
 	// 署名必须是人:插件与模型来源的同名标记不算人门动作(与宿主半同一条纪律)。
@@ -446,6 +461,7 @@ export const CONFIG_KEYS = [
 	'templateDir',
 	'l4RejectSelfWritten',
 	'minHypotheses',
+	'requireTypedPromotion',
 	'bashDenyRules',
 	'auditProvider',
 	'auditTimeoutMs',
@@ -478,6 +494,8 @@ export const MECHANISM_TOOLS = {
 	brain: ['SaveSkill', 'WriteMemory'],
 	/** 账本两件:它长在 git 上(A 层用工作区自己的仓库,B 层用数据区的旁路账本,与世界线共用一本)。 */
 	ledger: ['FileHistory', 'RestoreFile'],
+	/** 领域语言:七个动词 = 词汇的全部写入口(注册/修订/废止) + 一个读入口(按概念取已知)。 */
+	ontology: ['RegisterTerm', 'RegisterPredicate', 'ReviseTerm', 'RevisePredicate', 'DeprecateTerm', 'DeprecatePredicate', 'QueryKnowledge'],
 }
 const TOOL_CATALOG = new Set(Object.values(MECHANISM_TOOLS).flat())
 
@@ -625,6 +643,14 @@ export function apply(ctx, config = {}) {
 		l4RejectSelfWritten: config.l4RejectSelfWritten !== false,
 		/** ClearAI 代码里「≥2 条假设」只是文案;默认不强制。 */
 		minHypotheses: config.minHypotheses ?? 0,
+		/**
+		 * **知识门**:将要升格的命题必须已有断言的形态,否则结案被拒。
+		 *
+		 * 与 `minHypotheses` 是**两条不同的立场**,所以是两个键,不是一个:
+		 * 前者说「开工要有候选对比」,这条说「结论要有形态」。一个部署完全可以只要前者。
+		 * 机制侧缺省关(= 断言始终是加法),preset 里写 true——与 `blockedThreshold` 同一个模式。
+		 */
+		requireTypedPromotion: config.requireTypedPromotion === true,
 		bashDenyRules: config.bashDenyRules !== false,
 		auditProvider: config.auditProvider ?? 'spawn',
 		auditTimeoutMs: config.auditTimeoutMs ?? 240000,
@@ -703,6 +729,24 @@ export function apply(ctx, config = {}) {
 		return process.cwd()
 	}
 
+	/**
+	 * 这个会话是不是**派出去的子会话**(评估者 / 侦察 / 执行者 / 横评仲裁)。
+	 *
+	 * 判据读宿主的会话头:`dsh-subagent` 生成子会话时写死 `parentSession`——与它写死
+	 * `cwd: parentHeader.cwd` 是同一处,所以「共享工作区」与「身份是子会话」总是一起出现。
+	 * 会话服务问不出来时按「不是子会话」处理:与 `sessionCwd` 的退路同一个方向,
+	 * 拿不到证据时维持既有行为,不新增一条静默分支。
+	 */
+	function isSpawnedChild(sessionId) {
+		try {
+			const header = ctx.get('sessions')?.get?.(sessionId)?.header
+			if (header === null || typeof header !== 'object') return false
+			return header.origin === 'subagent' || header.parentSession !== undefined
+		} catch {
+			return false
+		}
+	}
+
 	/**
 	 * 认一条假设:`id` 最稳,**原文**与**唯一前缀**(≥8 字)也认。
 	 *
@@ -2557,7 +2601,7 @@ export function apply(ctx, config = {}) {
 		const facts = Array.isArray(state?.facts) ? state.facts : []
 		if (facts.length === 0) return null
 		const lines = [
-			'# 事实库(已升格、可作为「已知」引用)',
+			'# 本体内容(已确立条目,可作为「已知」引用;未结构化的旧条目照旧在架)',
 			'',
 			'> 每条都带**边界**(推翻条件)与**支持等级**:引用它之前先看边界还在不在。',
 			'> 这一份由系统维护(做的人不能写 `clear/knowledge/facts`);新的在前。',
@@ -2587,6 +2631,11 @@ export function apply(ctx, config = {}) {
 
 	/** 写货架;内容没变就返回 null(调用方据此决定要不要在卡里提一句)。 */
 	function ensureFactsShelf(sessionId, state) {
+		/**
+		 * 与词汇货架**同一条所有权规则,同一个位置**(写入口):子会话的投影里
+		 * 没有主线的事实,让它铺只会按它自己那份重写 `INDEX.md`。
+		 */
+		if (isSpawnedChild(sessionId)) return null
 		/**
 		 * 货架要显示「被推翻」那个读数,而它是**派生的**(fold 的 derive),不在原始状态里。
 		 * 所以这里问一次读面,而不是在货架里重算一遍(重算 = 第二份判据,必然漂)。
@@ -2605,6 +2654,74 @@ export function apply(ctx, config = {}) {
 		}
 	}
 
+	/**
+	 * **领域词汇货架**:把折出来的词汇落成 `clear/ontology/domain.md`。
+	 *
+	 * 与过程本体货架同一条纪律(读面 + 幂等),但**触发时机不同**:过程本体随发布版本,
+	 * 一个会话铺一次就够;词汇每一步都可能变,所以每个本体动词落账之后都要重铺一遍——
+	 * 内容没变就不重写(文件时间戳是给人的读数,不是噪声)。
+	 *
+	 * 带 `mutations` 时按**这一步之后**的样子渲染:工具返回前货架就已更新,读的人不必等下一回合。
+	 */
+	/**
+	 * 铺领域词汇货架(幂等)。
+	 *
+	 * **写入口自带所有权判据:派出去的子会话结构上写不进这份文件。**
+	 *
+	 * 规则一句话:工作区级读面属于拥有账本的会话。子会话(评估者 / 侦察 / 执行者)与主线
+	 * 共享同一个工作区,却持有**另一份(空的)投影**——让它照自己的投影重铺,
+	 * `renderShelf(子会话)` 渲染出的就是「还没有词条」的占位版。真跑里评估者两次读到
+	 * 7 行占位版、主线连读三次都是 96 行 21 词条,两边各自稳定:文件在「谁最后铺了一拍」
+	 * 之间摆动,而两边谁都没说谎。子会话**读**这份货架(评估者核对判据正要读它),但不写。
+	 *
+	 * 判据放在**写函数里**而不是调用点,与 `tools/pre-execute` 拒模型写 `clear/` 是同一条
+	 * 纪律:边界住在咽喉点,新增多少调用点都绕不过(不可表达优于不可违反)。
+	 */
+	function ensureDomainShelf(hostService, sessionId, mutations = []) {
+		if (hostService?.domain?.renderShelf === undefined) return ''
+		if (isSpawnedChild(sessionId)) return ''
+		try {
+			const body = hostService.domain.renderShelf(sessionId, Array.isArray(mutations) ? mutations : [])
+			const file = join(sessionCwd(sessionId), 'clear', 'ontology', 'domain.md')
+			if (existsSync(file) && readFileSync(file, 'utf8') === body) return ''
+			writeTextFile(file, body)
+			return `\n词汇货架已更新:${join('clear', 'ontology', 'domain.md')}(概念 / 谓词 / 图 / 引用)。**它是读面,不是权威**——要改词汇就调注册 / 修订 / 废止动词。`
+		} catch (error) {
+			ctx.logger?.warn?.(`clearai domain shelf: 写入失败 ${String(error?.message ?? error).slice(0, 160)}`)
+			return ''
+		}
+	}
+
+	/**
+	 * 领域判据的宿主入口。**拿不到就明确拒,不抛**:预设与宿主半同包同版本,
+	 * 但一个缺了这道门的宿主(旧包、裁剪过的部署、测试桩)不该让工具在 `undefined` 上崩——
+	 * 崩掉会让模型以为是自己的参数错了,而真实原因是这一层没接上。
+	 */
+	function domainJudge(hostService) {
+		return hostService?.domain ?? null
+	}
+
+	/** 在折出来的词汇里找一个条目(概念或谓词)。判据与折法同源:读的就是 `state.lexicon`。 */
+	function findLexiconEntry(state, id) {
+		const lexicon = state?.lexicon ?? {}
+		const wanted = String(id ?? '').trim()
+		if (wanted === '') return null
+		const term = (Array.isArray(lexicon.terms) ? lexicon.terms : []).find((item) => item.id === wanted)
+		if (term !== undefined) return { kind: 'term', entry: term }
+		const predicate = (Array.isArray(lexicon.predicates) ? lexicon.predicates : []).find((item) => item.id === wanted)
+		if (predicate !== undefined) return { kind: 'predicate', entry: predicate }
+		return null
+	}
+
+	/** 查询条件的一行人话:让「查不到」也说得清查的是什么。 */
+	function describeFilter(filter) {
+		const parts = []
+		if (filter.term !== '') parts.push(`概念「${filter.term}」`)
+		if (filter.predicate !== '') parts.push(`谓词「${filter.predicate}」`)
+		if (filter.subject !== '') parts.push(`主体「${filter.subject}」`)
+		return `查询:${parts.join(' · ')}`
+	}
+
 	/**
 	 * **本体货架**:把已装的那份本体落成 `clear/ontology/<id>.md`。
 	 *
@@ -2685,10 +2802,34 @@ export function apply(ctx, config = {}) {
 				promote_at_level: { type: 'string', enum: LEVELS, description: '升格门槛(默认 L3)' },
 				hypotheses: {
 					type: 'array',
-					description: '候选假设:每条一句话主张 + 一句推翻条件',
+					description:
+						'候选假设:每条一句话主张 + 一句推翻条件;可带**类型化断言**(可选,提供即严校:谓词与概念必须已登记、宾语形态要合值域、同一事实里不许自相矛盾)。不写断言照旧成立——断言是加法,不是门槛。',
 					items: {
 						type: 'object',
-						properties: { claim: { type: 'string' }, refute_when: { type: 'string' } },
+						properties: {
+							claim: { type: 'string' },
+							refute_when: { type: 'string' },
+							assertions: {
+								type: 'array',
+								description: '断言:主词–谓词–宾语(引用领域词汇里的 id)',
+								items: {
+									type: 'object',
+									properties: {
+										predicate: { type: 'string' },
+										subject: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string' } }, required: ['id'], additionalProperties: false },
+										object: {
+											type: 'object',
+											properties: { kind: { type: 'string', enum: ['statement', 'quantity', 'formula', 'code', 'reference', 'instance'] }, value: {}, unit: { type: 'string' }, type: { type: 'string' } },
+											required: ['kind'],
+											additionalProperties: false,
+										},
+										qualifiers: { type: 'object' },
+									},
+									required: ['predicate', 'subject', 'object'],
+									additionalProperties: false,
+								},
+							},
+						},
 						required: ['claim', 'refute_when'],
 						additionalProperties: false,
 					},
@@ -2714,6 +2855,19 @@ export function apply(ctx, config = {}) {
 			for (const hypothesis of hypotheses) {
 				if (typeof hypothesis?.claim !== 'string' || hypothesis.claim.trim() === '') return fail('hypothesis_claim_required', '每条假设要有一句话主张。')
 				if (typeof hypothesis?.refute_when !== 'string' || hypothesis.refute_when.trim() === '') return fail('hypothesis_refute_required', '每条假设必须写清「什么结果会推翻它」——没有推翻条件的假设无法被检验。')
+				/**
+				 * **宽松+校验**:不写断言放行(断言是加法),写了就在**落账之前**严校——
+				 * 引用不存在的谓词 / 概念、宾语形态不合值域、同一事实自相矛盾,一律当场拒。
+				 * 判据来自宿主半(`hostService.domain`),与折法和读面同源。
+				 */
+				if (hypothesis.assertions !== undefined && hypothesis.assertions !== null) {
+					const judge = domainJudge(hostService)
+					if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验断言。请检查宿主半与预设是否同版本。')
+					const problems = judge.validateAssertions(sessionId, hypothesis.assertions)
+					if (problems.length > 0) {
+						return fail('assertions_rejected', `这条假设的断言不能成立(先注册词汇,或改断言):\n${problems.map((item) => `- ${item}`).join('\n')}`)
+					}
+				}
 			}
 			// 假设数量下限:首次立目标就得带够候选——0 条一样拦(候选对比是检验的前提,
 			// 只有一个猜想时「验证」容易退化成找证据支持自己)。修订不受此限。
@@ -2727,6 +2881,35 @@ export function apply(ctx, config = {}) {
 			const goalId = isRevision ? state.goal.id : uniqueId('g')
 			const revision = isRevision ? state.goal.revision + 1 : 1
 			const promoteAtLevel = LEVELS.includes(args.promote_at_level) ? args.promote_at_level : 'L3'
+			/**
+			 * **修订不许给同一句话发新身份。**
+			 *
+			 * 真跑踩出来的:一轮长跑里目标改过一次版,卡上就出现 4 条主张的 6~8 行读数——
+			 * 同一句话挂着两个 id、各报一个状态(一个「已支持」、另一个「未触及」),
+			 * 模型得自己去调和两份自相矛盾的读数。而 id 是身份:主张原文没变就该用回原来的 id,
+			 * 这样「这条猜想被验到哪一级」跨版本仍然接着算。
+			 *
+			 * 反过来,**这一版没再列出来的**要如实落成 `hypothesis/superseded`:
+			 * 折法早就认识这条变更,只是从来没有人发过它(与 `retracted` 当年那个「声明了没有生产者」
+			 * 是同一种病)。不发它,被放弃的猜想会永远挂在 `proposed` 上,结案时又变成一条假的「没看过」。
+			 */
+			const existing = state.hypotheses.filter((item) => item.goal === goalId)
+			const claimKey = (text) => String(text ?? '').trim().replace(/\s+/g, ' ')
+			const idByClaim = new Map(existing.map((item) => [claimKey(item.claim), item.id]))
+			const reused = new Set()
+			const nextHypotheses = hypotheses.map((hypothesis, index) => {
+				const claim = hypothesis.claim.trim()
+				const carried = idByClaim.get(claimKey(claim))
+				if (carried !== undefined) reused.add(carried)
+				return {
+					id: carried ?? `h-${Math.random().toString(36).slice(2, 8)}`,
+					claim,
+					refute_when: hypothesis.refute_when.trim(),
+					/** 断言随假设落账;没写就是 null(加法,不是门槛)。 */
+					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
+					version: index + 1,
+				}
+			})
 			mutations.push({
 				t: 'goal/set',
 				id: goalId,
@@ -2735,13 +2918,14 @@ export function apply(ctx, config = {}) {
 				promote_at_level: promoteAtLevel,
 				revision,
 				reason: isRevision ? String(args.reason).trim() : null,
-				hypotheses: hypotheses.map((hypothesis, index) => ({
-					id: `h-${Math.random().toString(36).slice(2, 8)}`,
-					claim: hypothesis.claim.trim(),
-					refute_when: hypothesis.refute_when.trim(),
-					version: index + 1,
-				})),
+				hypotheses: nextHypotheses,
 			})
+			for (const dropped of existing) {
+				if (reused.has(dropped.id)) continue
+				const promoted = (state.facts ?? []).some((fact) => fact.hypothesis === dropped.id)
+				if (promoted) continue
+				mutations.push({ t: 'hypothesis/superseded', goal: goalId, id: dropped.id, claim: dropped.claim, by: `rev${revision}` })
+			}
 			let scoutNote = ''
 			if (!isRevision && CFG.precommitRecon) {
 				// 立约前侦察:harness 发起(不是模型请求),一生一次,且只在真的有人给过材料时做
@@ -2836,6 +3020,43 @@ export function apply(ctx, config = {}) {
 				)
 			}
 			const derived = hostService.derive(sessionId)
+			/**
+			 * **知识门:核心结论不许以纯散文升格。**
+			 *
+			 * 位置有讲究——它坐在「计划已收尾」之后、**派评估者之前**。判据与准入同一条顺序纪律:
+			 * 先把能做的前提查完,再花钱请人裁决;等评估卡回来才发现没形态,那一次子 run 就白花了。
+			 *
+			 * 为什么需要它:断言一直是「加法,不是门槛」,于是真跑里模型的最优策略就是
+			 * 「检索 → 总结 → 写报告」——本体、实体、认识论三张图都长不出来,因为完成函数里没有它们。
+			 * 让缺口进卡(见 `renderCard`)只解决「看得见」;这一道解决「绕不过」。
+			 *
+			 * **判据是结构谓词,不是词面**:将要升格的命题里,只要有一条没有断言就拦。
+			 * 出口有两条,都是诚实的:补上断言的形态再结,或者如实 `abandoned`。
+			 * 缺口不许被伪装成 support(那是「造证」,比不结案坏得多)。
+			 *
+			 * 开关是 `requireTypedPromotion`(机制缺省关,preset 里开):它与 `minHypotheses`
+			 * 是两条不同的立场,所以不共用一个键。另外它**只在知识模式下生效**——
+			 * 没有登记的命题就没有「形态」可谈,那时拦下来的只是一句空话。
+			 */
+			if (CFG.requireTypedPromotion && derived.knowledge.mode === 'knowledge') {
+				const threshold = levelIndexOf(goal.promote_at_level)
+				/** 与下面那段升格循环**逐字同一套谓词**:将要升格的就是这几条,一条不多一条不少。 */
+				const promotable = derived.hypotheses.filter(
+					(hypothesis) =>
+						(hypothesis.status === 'alive' || hypothesis.status === 'proposed') &&
+						(hypothesis.refutations ?? 0) === 0 &&
+						levelIndexOf(hypothesis.supportedLevel) >= threshold,
+				)
+				const untyped = promotable.filter((hypothesis) => !Array.isArray(hypothesis.assertions) || hypothesis.assertions.length === 0)
+				if (untyped.length > 0) {
+					return fail(
+						'claims_untyped',
+						`有 ${untyped.length} 条命题已经验到门槛、却**没有断言的形态**,再往下就是散文升格:\n${untyped
+							.map((hypothesis) => `- ${hypothesis.id}(${hypothesis.supportedLevel}):${hypothesis.claim}`)
+							.join('\n')}\n把结论写成「主词 · 谓词 = 宾语」才进得了实体图,下一轮也才按概念取用得到。两条路:\n① **补形态再结**:词汇里没有对应的概念 / 谓词就先 \`RegisterTerm\` / \`RegisterPredicate\`,再用 \`SetGoal\` 修订目标、把这些命题连断言一起重列一遍(主张原文一字不动就会用回原 id,验到哪一级接着算),然后重新结案;\n② **如实放弃**:这些结论不值得留下形态,就用 \`CloseGoal(outcome="abandoned")\` 说清阻塞收兵。\n别为了让门放行而编一个词——词汇是约定,它将长期约束这个项目怎么写结论。`,
+					)
+				}
+			}
 			const unfinished = plan === null ? [] : plan.steps.filter((step) => step.status === 'open')
 			const syntheticStep = { id: `goal:${goal.id}`, ordinal: 0, do: `核验目标 ${goal.id} 的判据与转写忠实度`, done_criteria: goal.done_criteria, artifacts: [], tests: null }
 			const gate = {
@@ -2909,10 +3130,17 @@ export function apply(ctx, config = {}) {
 					t: 'fact/promoted',
 					id: factId,
 					goal: goal.id,
+					/**
+					 * **身份与内容一起定型**:`hypothesis` 是产出它的那条假设(按 id 关联,
+					 * 措辞改了也认得出),`assertions` 是这条事实的类型化内容(没写就是 null)。
+					 * 断言只在**升格这一刻**落地——旧事实不会被回溯改写。
+					 */
+					hypothesis: hypothesis.id,
 					text: hypothesis.claim,
 					scope: hypothesis.refute_when ?? null,
 					level: hypothesis.supportedLevel ?? null,
 					evidence: state.evidence.filter((item) => item.verdict === 'support').map((item) => item.id),
+					assertions: Array.isArray(hypothesis.assertions) ? hypothesis.assertions : null,
 					path,
 				})
 				promoted.push(hypothesis.claim)
@@ -3007,6 +3235,301 @@ export function apply(ctx, config = {}) {
 		additionalProperties: false,
 	}
 
+
+	// ── 领域语言(本体动词)─────────────────────────────────────────────────
+	/**
+	 * 七个动词 = 领域词汇的**全部写入口**(注册 / 修订 / 废止,概念与谓词各一套)+ 一个读入口。
+	 *
+	 * 它们只做一件事:把「这个领域有哪些概念、哪些谓词、关系取什么值形态」写进账本事件,
+	 * 由折法折成 `state.lexicon`;再由同一份折法长出本体图、冲突读数与货架。
+	 *
+	 * 四条贯穿所有动词的纪律:
+	 *   · **判据只有一份**——校验经 `hostService.domain.*`(与折法、读面同源),预设侧不复制规则;
+	 *   · **依据必填**——约定可以自愿,不能无来由;
+	 *   · **没有删除**——修订留版本,废止留缘由且是黏性终态;
+	 *   · **语义变化必须换 id**——改展示信息走修订,改含义/主词域/值域走「废止 + 新注册」。
+	 */
+	defineTool({
+		name: 'RegisterTerm',
+		description:
+			'登记一个领域概念(本体图上的节点)。id 用小写 slug;`gloss` 一句话说清它指什么;`basis` 必填——哪份材料、哪条事实或人说的哪句话让这个词成立。`parent` 可选(is_a,只能连概念)。登记是**约定**不是主张:它不需要证据等级,但从此可以出现在断言里。要改展示信息用 ReviseTerm,要作废用 DeprecateTerm(记录不会删)。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string', description: '小写字母开头的 slug(字母/数字/下划线,≤40)' },
+				label: { type: 'string', description: '给人看的名字' },
+				gloss: { type: 'string', description: '一句话释义' },
+				aliases: { type: 'array', items: { type: 'string' }, description: '别名(可选)' },
+				parent: { type: 'string', description: '父概念 id(可选,is_a)' },
+				basis: { type: 'string', description: '依据:哪份材料 / 哪条事实 / 谁说的' },
+			},
+			required: ['id', 'label', 'gloss', 'basis'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const judge = domainJudge(hostService)
+			if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验词汇。请检查宿主半与预设是否同版本。')
+			const problems = judge.validateTerm(sessionId, args)
+			if (problems.length > 0) return fail('term_rejected', `这个词不能登记:\n${problems.map((item) => `- ${item}`).join('\n')}`)
+			mutations.push({
+				t: 'ontology/term_added',
+				id: String(args.id).trim(),
+				label: String(args.label).trim(),
+				gloss: String(args.gloss).trim(),
+				aliases: Array.isArray(args.aliases) ? args.aliases.map((alias) => String(alias)) : [],
+				parent: args.parent === undefined ? null : String(args.parent).trim(),
+				basis: String(args.basis).trim(),
+			})
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'term_registered',
+				message: `概念 ${String(args.id).trim()} 已登记。它现在是本体图上的一个节点:新断言可以引用它。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'RegisterPredicate',
+		description:
+			'登记一个领域谓词(本体图上的边)。值域二选一:`range={form:"quantity"|"statement"|"formula"|"code"|"reference",unit?}` 说宾语是一个**字面值**,或 `range={term:"<概念 id>"}` 说宾语是**另一个概念的实例**。`domain` 可选(主词域,声明了它,断言的主体就必须写明类型)。`functional=true` 表示单值:同一主体出现两个不同取值时,投影会给出一对**冲突**(只暴露,不裁决)。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string', description: '小写字母开头的 slug' },
+				label: { type: 'string', description: '给人看的名字' },
+				gloss: { type: 'string', description: '一句话释义(可选)' },
+				domain: { type: 'string', description: '主词域:概念 id(可选)' },
+				range: {
+					type: 'object',
+					description: '值域:{form,unit?} 或 {term}',
+					properties: {
+						form: { type: 'string', enum: ['statement', 'quantity', 'formula', 'code', 'reference'] },
+						unit: { type: 'string' },
+						term: { type: 'string' },
+					},
+					additionalProperties: false,
+				},
+				functional: { type: 'boolean', description: '是否单值(默认否)' },
+				basis: { type: 'string', description: '依据(必填)' },
+			},
+			required: ['id', 'label', 'range', 'basis'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const judge = domainJudge(hostService)
+			if (judge === null) return fail('domain_unavailable', '这一层的宿主没有提供领域判据(domain facade):无法校验词汇。请检查宿主半与预设是否同版本。')
+			const problems = judge.validatePredicate(sessionId, args)
+			if (problems.length > 0) return fail('predicate_rejected', `这个谓词不能登记:\n${problems.map((item) => `- ${item}`).join('\n')}`)
+			mutations.push({
+				t: 'ontology/predicate_added',
+				id: String(args.id).trim(),
+				label: String(args.label).trim(),
+				gloss: args.gloss === undefined ? '' : String(args.gloss).trim(),
+				domain: args.domain === undefined ? null : String(args.domain).trim(),
+				range: args.range,
+				functional: args.functional === true,
+				basis: String(args.basis).trim(),
+			})
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'predicate_registered',
+				message: `谓词 ${String(args.id).trim()} 已登记(${args.range?.term ? `宾语是概念 ${args.range.term} 的实例` : `宾语取 ${args.range?.form} 形态`}${args.functional === true ? ' · 单值' : ''})。下一步:在 SetGoal 的假设里带上断言,引用它。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'ReviseTerm',
+		description:
+			'修订一个概念的**展示信息**(名字 / 释义 / 别名):版本 +1,旧值留在账上,id 不变。**语义变化不许走这条路**——含义、父概念变了就废止旧条目、注册新条目;稳定 id 的含义在历史上悄悄改变,等于拿今天的释义重写所有旧事实。',
+		parameters: {
+			type: 'object',
+			properties: {
+				id: { type: 'string' },
+				label: { type: 'string', description: '新名字(可选)' },
+				gloss: { type: 'string', description: '新释义(可选)' },
+				aliases: { type: 'array', items: { type: 'string' } },
+				reason: { type: 'string', description: '为什么改(必填)' },
+			},
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'term') return fail('unknown_term', `词汇里没有这个概念:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('term_deprecated', `概念 ${String(args.id)} 已废止,不能修订(要恢复语义就注册新条目)。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '修订要写一句原因:改了什么、为什么改。')
+			if (args.label === undefined && args.gloss === undefined && args.aliases === undefined) return fail('nothing_to_revise', '没有要改的字段:label / gloss / aliases 至少给一个。')
+			mutations.push({ t: 'ontology/term_revised', id: String(args.id), label: args.label === undefined ? undefined : String(args.label).trim(), gloss: args.gloss === undefined ? undefined : String(args.gloss).trim(), aliases: Array.isArray(args.aliases) ? args.aliases.map((alias) => String(alias)) : undefined, reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'term_revised', message: `概念 ${String(args.id)} 已修订(旧值留在账上)。${note}` })
+		},
+	})
+
+	defineTool({
+		name: 'RevisePredicate',
+		description: '修订一个谓词的**展示信息**(名字 / 释义)。值域、主词域与单值性是语义——那三样变了要废止旧谓词、注册新的。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string' }, label: { type: 'string' }, gloss: { type: 'string' }, reason: { type: 'string' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'predicate') return fail('unknown_predicate', `词汇里没有这个谓词:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('predicate_deprecated', `谓词 ${String(args.id)} 已废止,不能修订。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '修订要写一句原因。')
+			mutations.push({ t: 'ontology/predicate_revised', id: String(args.id), label: args.label === undefined ? undefined : String(args.label).trim(), gloss: args.gloss === undefined ? undefined : String(args.gloss).trim(), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'predicate_revised', message: `谓词 ${String(args.id)} 已修订(版本 +1,旧值留着)。${note}` })
+		},
+	})
+
+	/**
+	 * **废止是黏性终态**:没有复活这条路。存量事实照旧可读(历史留着),
+	 * 引用它的**新**断言会被拒,并在货架上标明「所用术语已废止」。
+	 */
+	defineTool({
+		name: 'DeprecateTerm',
+		description:
+			'废止一个概念(或谓词):缘由必填。**没有删除**——条目、旧版本与引用过它的事实全部留着;新断言不许再引用它,存量事实在货架上标明「所用术语已废止」。要恢复语义就注册一个新条目(那是覆盖,不是复活)。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string', description: '概念或谓词的 id' }, reason: { type: 'string', description: '为什么废止(必填)' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null) return fail('unknown_entry', `词汇里没有这个条目:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('already_deprecated', `${String(args.id)} 已经是废止状态(这一步不会重复记账)。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '废止要写缘由:为什么这个词不再用。')
+			mutations.push({ t: entry.kind === 'term' ? 'ontology/term_deprecated' : 'ontology/predicate_deprecated', id: String(args.id), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({
+				ok: true,
+				code: 'entry_deprecated',
+				message: `${entry.kind === 'term' ? '概念' : '谓词'} ${String(args.id)} 已废止(记录保留,新断言不许再引用;引用过它的事实照旧可读)。${note}`,
+			})
+		},
+	})
+
+	defineTool({
+		name: 'DeprecatePredicate',
+		description: '废止一个谓词:缘由必填,记录保留,新断言不许再引用它(与 DeprecateTerm 同一条纪律,单列出来是为了让参数与语义各自说清)。',
+		parameters: {
+			type: 'object',
+			properties: { id: { type: 'string' }, reason: { type: 'string' } },
+			required: ['id', 'reason'],
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const entry = findLexiconEntry(state, args.id)
+			if (entry === null || entry.kind !== 'predicate') return fail('unknown_predicate', `词汇里没有这个谓词:${String(args.id)}`)
+			if (entry.entry.status === 'deprecated') return fail('already_deprecated', `${String(args.id)} 已经是废止状态。`)
+			if (typeof args.reason !== 'string' || args.reason.trim() === '') return fail('reason_required', '废止要写缘由。')
+			mutations.push({ t: 'ontology/predicate_deprecated', id: String(args.id), reason: String(args.reason).trim() })
+			const note = ensureDomainShelf(hostService, sessionId, mutations)
+			return done({ ok: true, code: 'entry_deprecated', message: `谓词 ${String(args.id)} 已废止(记录保留,新断言不许再引用)。${note}` })
+		},
+	})
+
+	/**
+	 * **螺旋上半圈的入口**:按概念 / 谓词 / 主体取「已知」。
+	 * 读数全部来自投影(事实与流转中的假设),不新建任何存储;它也不改任何东西。
+	 */
+	defineTool({
+		name: 'QueryKnowledge',
+		description:
+			'按概念 / 谓词 / 主体查「已知」:返回带类型化断言的**已升格事实**与**还在流转的命题**。要复用前面的结论就用它,而不是把事实库重读一遍。只读:它不改任何东西。',
+		parameters: {
+			type: 'object',
+			properties: {
+				term: { type: 'string', description: '概念 id:匹配断言的主体类型 / 宾语概念 / 词条本身' },
+				predicate: { type: 'string', description: '谓词 id' },
+				subject: { type: 'string', description: '主体名称(实例)' },
+			},
+			additionalProperties: false,
+		},
+		output: CARD_OUTPUT,
+		async execute(args, exec) {
+			const call = open(exec)
+			if (call.ok !== true) return call.response
+			const { hostService, sessionId, state, mutations } = call
+			const done = finish(hostService, sessionId, mutations)
+			const derived = hostService.derive(sessionId)
+			const filter = { term: args.term === undefined ? '' : String(args.term).trim(), predicate: args.predicate === undefined ? '' : String(args.predicate).trim(), subject: args.subject === undefined ? '' : String(args.subject).trim() }
+			if (filter.term === '' && filter.predicate === '' && filter.subject === '') return fail('query_empty', '至少给一个条件:term / predicate / subject。')
+			const match = (assertion) => {
+				const subject = assertion?.subject ?? {}
+				const object = assertion?.object ?? {}
+				if (filter.predicate !== '' && String(assertion?.predicate ?? '') !== filter.predicate) return false
+				if (filter.subject !== '' && String(subject.id ?? '') !== filter.subject) return false
+				if (filter.term !== '') {
+					const hits = [String(subject.type ?? ''), String(subject.id ?? ''), String(object.kind) === 'instance' ? String(object.type ?? '') : '', String(object.kind) === 'instance' ? String(object.value ?? '') : '', String(assertion?.predicate ?? '')]
+					if (!hits.includes(filter.term)) return false
+				}
+				return true
+			}
+			const facts = derived.factRows.filter((fact) => (Array.isArray(fact.assertions) ? fact.assertions : []).some(match))
+			const inFlight = derived.hypotheses.filter((hypothesis) => (Array.isArray(hypothesis.assertions) ? hypothesis.assertions : []).some(match))
+			if (facts.length === 0 && inFlight.length === 0) {
+				return done({ ok: true, code: 'knowledge_empty', message: `这个词汇条件下还没有任何东西:${describeFilter(filter)}。要么先登记/验证,要么换个条件——**不要**把「查不到」写成「不存在」。` })
+			}
+			const lines = []
+			if (facts.length > 0) {
+				lines.push(`已知(已升格,可作为已知引用):${facts.length} 条`)
+				for (const fact of facts.slice(0, 12)) {
+					lines.push(`- ${fact.id} · ${clip(String(fact.text ?? ''), 120)}(支持到 ${fact.level ?? '—'}${fact.review?.decision === 'retracted' ? ' · **已撤回**' : fact.refuted === true ? ' · 有推翻证据等人决定' : ''})`)
+					lines.push(`  边界:${clip(String(fact.scope ?? '(未写)'), 120)}`)
+					for (const assertion of fact.assertions ?? []) if (match(assertion)) lines.push(`  断言:${hostService.domain.format(sessionId, assertion)}`)
+				}
+				if (facts.length > 12) lines.push(`  (还有 ${facts.length - 12} 条,见 clear/knowledge/facts/INDEX.md)`)
+			}
+			if (inFlight.length > 0) {
+				lines.push(`还在流转的命题(未升格):${inFlight.length} 条`)
+				for (const hypothesis of inFlight.slice(0, 8)) {
+					lines.push(`- ${hypothesis.id} [${hypothesis.status}] ${clip(String(hypothesis.claim ?? ''), 100)}${hypothesis.supportedLevel === null ? '' : `(支持到 ${hypothesis.supportedLevel})`}`)
+					for (const assertion of hypothesis.assertions ?? []) if (match(assertion)) lines.push(`  断言:${hostService.domain.format(sessionId, assertion)}`)
+				}
+			}
+			return done({ ok: true, code: 'knowledge_found', message: `${describeFilter(filter)}\n${lines.join('\n')}` })
+		},
+	})
+
 	defineTool({
 		name: 'CreatePlan',
 		description:
@@ -5707,7 +6230,12 @@ export function apply(ctx, config = {}) {
 
 	function protectedRoots(sessionId) {
 		const cwd = sessionCwd(sessionId)
-		return [join(cwd, 'clear', 'evidence'), join(cwd, 'clear', 'knowledge', 'facts'), join(cwd, 'clear', 'goals')]
+		/**
+		 * 系统所有的四格:`evidence` / `facts` / `goals`,加上 `ontology`(词汇货架)。
+		 * 为什么词汇也在此列:货架是**渲染**,词条的权威在账本事件里——
+		 * 谁直接改那份 markdown,谁就制造了一份谁也不认的词汇表(面板读的是折法)。
+		 */
+		return [join(cwd, 'clear', 'evidence'), join(cwd, 'clear', 'knowledge', 'facts'), join(cwd, 'clear', 'goals'), join(cwd, 'clear', 'ontology')]
 	}
 
 	function touchesProtected(sessionId, value) {
@@ -5844,7 +6372,7 @@ export function apply(ctx, config = {}) {
 				// 「评估卡与事实只能由系统写」:做的人写不进证据面(执行者同样适用)
 				const suspect = touchesProtected(sessionId, args.file_path) ?? touchesProtected(sessionId, args.path) ?? (exec.name === 'bash' ? touchesProtected(sessionId, args.command) : null)
 				if (suspect !== null) {
-					return { kind: 'deny', reason: `clear/evidence、clear/knowledge/facts、clear/goals 由系统所有,做的人不能写:${suspect}。事实与评估卡只能由系统落盘。` }
+					return { kind: 'deny', reason: `clear/evidence、clear/knowledge/facts、clear/goals、clear/ontology 由系统所有,做的人不能写:${suspect}。事实、评估卡与词汇货架只能由系统落盘(词汇要改就调注册/修订/废止动词)。` }
 				}
 				// L4 人放行:ClearAI 的设计目标未实现,这里用宿主的审批瀑布实现。
 				// 门挂在**等级**上:主线看步骤等级,世界线看分支等级——两条路同一道门。
@@ -6017,6 +6545,15 @@ export function apply(ctx, config = {}) {
 			ontologyShelved.add(sessionId)
 			if (shelf !== null) ontologyNote = `\n- 本体已就位(${CONTRIB.ontology.objects.length} 个对象 · ${CONTRIB.ontology.levels.length} 级):${join('clear', 'ontology', `${CONTRIB.ontology.id}.md`)}——交付前对照它(哪些状态合法、每一级谁来判)。`
 		}
+		/**
+		 * **领域词汇货架**每一拍都重铺一次(幂等:内容没变就不重写)。
+		 *
+		 * 为什么不像过程本体那样只铺一次:那一份随**发布版本**,这一份随**会话**——
+		 * 一个项目今天没用词汇、明天开始用,货架必须自己长出来,而不是等人记得去建。
+		 * 它也不进卡:货架的位置在提示词里说一次就够,每拍重复就是往上下文里灌水。
+		 * 所有权判据(子会话不写)在写入口——见 `ensureDomainShelf`。
+		 */
+		ensureDomainShelf(host(), sessionId)
 		let brainNote = ''
 		/** 事实货架那句话说一次就够(事实很少变)。 */
 		let factsNote = ''
@@ -6139,6 +6676,7 @@ export function apply(ctx, config = {}) {
 			/**
 			 * **事实货架**:事实变了才重写、才在卡里提一句——**变了才发**,与目录同一条纪律。
 			 * 事实很少变(升格一次),所以这句话在大多数回合里都不出现。
+			 * 所有权判据(子会话不写)在写入口——见 `ensureFactsShelf`。
 			 */
 			const shelf = ensureFactsShelf(sessionId, state)
 			if (shelf !== null) factsNote = `\n- 事实库多了一条(或边界改了):${shelf}——引用前先看它的边界(推翻条件)。`