@sema-agent/settings-schema 3.0.1 → 4.0.0

package/dist/config-fns.js

@@ -207,7 +207,7 @@ function judgeEntry(schema, value) {
  * 一条粘错位置的凭据,所以路径里的键段过 {@link redactSecrets} 才出门(不变量①:secret 值永不随错误外流,
  * 与 parseDomain 的 R13/R14 同一条);② 整段遍历包 try/catch —— 读字段、枚举 Record 都会触发访问器,
  * 抛出来的文案可能带 secret。抢救是**尽力而为**的:抢不动就当没抢救(返回原引用),让既有的整域档位去裁,
- * 绝不把解析拖下水、更不回显它的错误(与同文件 `scanDropped` 逐字同纪律)。
+ * 绝不把解析拖下水、更不回显它的错误(与同文件 {@link droppedKeys} 逐字同纪律)。
  *
  * 边界(如实登记):① 只看**顶层**字段(条目集合就在顶层,嵌套的坏形属于条目自身的问题);② raw 不是
  * 纯 JSON 对象、字段值与 schema 形状对不上(schema 说数组、文档给对象)⇒ 原样返回,交给整域档位裁;
@@ -321,6 +321,58 @@ export function legacyGovernanceFromRuntime(rawRuntime) {
             lifted[k] = r[k];
     return Object.keys(lifted).length ? lifted : undefined;
 }
+/** {@link EffectiveReadWarning} 的 `kind` **闭集**(运行期值)。一致性 kit 的覆盖律按它计数,消费方要遍历
+ *  「所有告警种类」也用它 —— 属主在告警联合自己的模块里,`./conformance` 只再导出(4.0.0 前它住在 kit 里,
+ *  那边是联合的下游,却握着联合的闭集)。
+ *
+ *  **这张表由谁咬住**(实测,2026-09-22,别照 `satisfies` 的样子推):`satisfies` 只咬「多一个联合里**没有**
+ *  的词」;**少登记一个** kind 它咬不住(少一员的数组照样可赋值)。真正咬「新 kind 必须被处置」的是三处
+ *  `never` 穷举臂 —— {@link projectWarning}、{@link rebaseWarningPaths}、kit 的 `normalizeProjection`
+ *  (给联合加一条新臂,实测这三处各红一条,`satisfies` 那行零诊断);而「新 kind 三处都处置了、却忘了登记
+ *  进本表」这半条缝,由 `test/warning-projection-derived-4.0.0.test.ts` 的闭集格看着(本表 == 从 AST 解出的
+ *  臂集,逐字同集同序)。 */
+export const WARNING_KINDS = [
+    "hosts-grandfathered",
+    "domain-defaulted",
+    "unknown-keys-dropped",
+    "unknown-keys-carried",
+    "legacy-governance-lifted",
+    "entry-dropped",
+    "unread-config-file",
+];
+/**
+ * 一条告警 → 它的投影。**闭集穷举**:新 kind 不在这里表态就编译红(#157 的闭集纪律);而字段级的对齐由
+ * {@link WarningProjection} 的派生保证 —— 少铸一个字段,这里就是编译红。
+ *
+ * `truncatedFrom` 缺席时**不铸这个键**(不是铸 `undefined`)—— 规范化会把 `undefined` 值剔掉,两种写法
+ * 最终同形,但不铸更诚实:「没有截断」与「截断了 0 条」不该在中间形上分成两件事。
+ */
+export function projectWarning(w) {
+    switch (w.kind) {
+        case "hosts-grandfathered":
+            return { kind: w.kind, domain: w.domain, droppedNames: w.droppedNames, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
+        case "domain-defaulted":
+            return { kind: w.kind, domain: w.domain };
+        // 两臂字段相同但**不合并**:合并后 `kind` 塌成两员的联合,TS 就再也认不出它属于投影联合的哪一员
+        // (真编译红过一次)。逐 kind 一臂,是这张表本来的样子。
+        case "unknown-keys-dropped":
+            return { kind: w.kind, domain: w.domain, keys: w.keys, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
+        case "unknown-keys-carried":
+            return { kind: w.kind, domain: w.domain, keys: w.keys, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
+        case "legacy-governance-lifted":
+            return { kind: w.kind, domain: w.domain, keys: w.keys };
+        case "entry-dropped":
+            return { kind: w.kind, domain: w.domain, path: w.path };
+        case "unread-config-file":
+            return { kind: w.kind, file: w.file, ...(w.domain === undefined ? {} : { domain: w.domain }), why: w.why };
+        default: {
+            const unhandled = w;
+            // 运行期到不了(本联合由本模块铸造);到了就让它红 —— 一条不认识的告警被静默投影成空,
+            // 正是「门看起来全绿」的那种假绿。
+            throw new Error(`settings-schema: unknown EffectiveReadWarning kind — ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
 /**
  * 一条告警里的**段坐标**({@link ConfigPath})从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,
  * {@link EntryKeptIndex} 是它唯一的坐标账。
@@ -330,7 +382,7 @@ export function legacyGovernanceFromRuntime(rawRuntime) {
  * `models.1` 指的是压缩后的第 1 条。运维照着这条告警去改原文档的第 1 条 —— 改的是别人的行,而且改完
  * 告警还在(他以为改对了)。**告警必须说运维看得见的那份文档里的坐标**。
  *
- * 为什么回写在这里、而不是让扫描函数认识原文档:给 `scanDropped` / `scanCarried` 加一个「原始 raw」
+ * 为什么回写在这里、而不是让扫描函数认识原文档:给 {@link droppedKeys} / {@link carriedUnknownKeys} 加一个「原始 raw」
  * 第二入参,等于让扫描同时持有两套坐标,每条新告警都要自己决定用哪套。回写是**告警出门前**的一次
  * 坐标换算,与诊断本身正交 —— 一个铸点,所有臂一次表态。
  *
@@ -481,16 +533,6 @@ function collectDropped(domain, raw, parsed, prefix, depth, spared, acc) {
         collectDropped(domain, raw[k], parsed[k], [...prefix, k], depth + 1, spared, acc);
     }
 }
-function scanDropped(domain, raw, parsed) {
-    const acc = { keys: [], total: 0 };
-    try {
-        collectDropped(domain, raw, parsed, [], 0, domain === "runtime" ? GOVERNANCE_MIRROR_KEYS : [], acc);
-    }
-    catch {
-        return { keys: [], total: 0 }; // 反射/访问器抛错:告警是尽力而为的审计线,绝不能把解析拖下水,更不能回显其错误文案
-    }
-    return acc;
-}
 /**
  * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),段坐标形({@link ConfigPath})。
  *
@@ -506,13 +548,25 @@ function scanDropped(domain, raw, parsed) {
  * `runtime` 域的治理三件({@link GOVERNANCE_MIRROR_KEYS})**不算被丢**:0.5 期 runtime 文档携带它们是
  * 成文的抬升位(本文件的 governance 抬升函数会把它们抬进 governance 域),报出来是噪声。豁免只在顶层。
  *
+ * 返回 {@link UnknownKeyScan}:`keys` 是**有界**的点名列表,`total` 是截断前的真实总数(4.0.0 BREAKING,
+ * 此前只回 `keys` —— 见 {@link UnknownKeyScan} 的成案)。本包自己的告警(`unknown-keys-dropped`)也是拿这两个
+ * 数拼出来的,**一个铸点**:消费方自铸的 `truncatedFrom` 与告警里那个恒等。
+ *
  * 边界(如实登记):① 深度上限 {@link DROP_SCAN_MAX_DEPTH}、键数上限 {@link DROP_SCAN_MAX_KEYS}(告警
- * 载荷有界,超出即少报);② 数组长度不同就整段跳过(元素级裁剪由各自的 clamp 告警负责);③ 只比对纯
- * JSON 对象——raw 若是类实例/Proxy 这类形状不扫;④ 读 raw 的值可能触发访问器,整段包 try/catch 且**绝不**
- * 让其错误外泄(错误文案可能带 secret,与 parseDomain 的 R13 同纪律),扫描失败即当作"没看见",不影响解析。
+ * 载荷有界,超出即少报**点名**——`total` 不少报);② 数组长度不同就整段跳过(元素级裁剪由各自的 clamp 告警
+ * 负责);③ 只比对纯 JSON 对象——raw 若是类实例/Proxy 这类形状不扫;④ 读 raw 的值可能触发访问器,整段包
+ * try/catch 且**绝不**让其错误外泄(错误文案可能带 secret,与 parseDomain 的 R13 同纪律),扫描失败即当作
+ * "没看见"(`{ keys: [], total: 0 }`),不影响解析。
  */
 export function droppedKeys(domain, raw, parsed) {
-    return scanDropped(domain, raw, parsed).keys;
+    const acc = { keys: [], total: 0 };
+    try {
+        collectDropped(domain, raw, parsed, [], 0, domain === "runtime" ? GOVERNANCE_MIRROR_KEYS : [], acc);
+    }
+    catch {
+        return { keys: [], total: 0 }; // 反射/访问器抛错:告警是尽力而为的审计线,绝不能把解析拖下水,更不能回显其错误文案
+    }
+    return acc;
 }
 /**
  * open-world 域(`.passthrough()`)的**已知键表**:段坐标 → 该层已知键(`[]` = 顶层)。键集从 schema 的
@@ -535,13 +589,14 @@ const OPEN_WORLD_KNOWN_KEYS = {
  * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(段坐标)。非 open-world 域恒空
  * (它们的未知键走 {@link droppedKeys} 那条更重的「被丢了」告警)。
  *
+ * 返回 {@link UnknownKeyScan}(4.0.0 BREAKING,与 {@link droppedKeys} 同形同律:`keys` 有界、`total` 是
+ * 截断前的真实总数)。非 open-world 域返回的也是这个形(`{ keys: [], total: 0 }`),不是别的东西 ——
+ * 「这个域没有承运未知键」与「这个域不参与承运」在消费方那里是同一个处置。
+ *
  * 边界(如实):只看 {@link OPEN_WORLD_KNOWN_KEYS} 登记了的层级 —— 未登记层级(如某个未知键自己的
  * 子树)不再下探,那本就是消费方自定义的内容,逐层猜没有意义。
  */
 export function carriedUnknownKeys(domain, parsed) {
-    return scanCarried(domain, parsed).keys;
-}
-function scanCarried(domain, parsed) {
     const table = OPEN_WORLD_KNOWN_KEYS[domain];
     const acc = { keys: [], total: 0 };
     if (table === undefined)
@@ -571,10 +626,10 @@ function scanCarried(domain, parsed) {
 export function parseDomainLoud(domain, raw, onWarning) {
     const parsed = parseDomain(domain, raw);
     if (onWarning) {
-        const dropped = scanDropped(domain, raw, parsed);
+        const dropped = droppedKeys(domain, raw, parsed);
         if (dropped.keys.length > 0)
             onWarning({ domain, kind: "unknown-keys-dropped", keys: dropped.keys, ...(dropped.total > dropped.keys.length ? { truncatedFrom: dropped.total } : {}) });
-        const carried = scanCarried(domain, parsed);
+        const carried = carriedUnknownKeys(domain, parsed);
         if (carried.keys.length > 0)
             onWarning({ domain, kind: "unknown-keys-carried", keys: carried.keys, ...(carried.total > carried.keys.length ? { truncatedFrom: carried.total } : {}) });
     }

package/dist/conformance/contract-adapter.js

@@ -6,11 +6,18 @@
  * `buildEffective` / `readEffectiveWire` / `loadLocalConfig` **就是**它的生产入口);②historical 模式要对
  * 一份旧版 dist 跑同样的三腿。
  *
+ * 4.0.0 起这句自陈**有牙**:入口落在契约包自己身上 ⇒ 造适配器那一刻就**拒**(抛,不是告警 —— 一条告警
+ * 在 CI 日志里活不过第二天,而这道门一旦被同义反复接进去,它报的全绿是**假绿**)。判别式单铸在
+ * `./entry-origin.js`,`runConformance` 的 release 门用的是同一只(手写的适配器字面量走不到工厂,
+ * 那条路只有门看得见)。两条腿的拒绝句也同源:说清你落在哪儿、合法的是哪儿。
+ *
  * 拒绝分层的判据(一条,不是一串特例):**ZodError 形的错 = `validate`**(某个域没通过它的 schema);
  * 其余按腿各自的默认层 —— wire 腿是 `envelope`(它在解析任何域之前先判信封),local-root 腿是 `parse`
  * (文件层先判:空文件 / 非 JSON / 非对象),domains 腿本来就只有校验这一层。
  */
 import { materializeLocalRoot } from "./run.js";
+import { contractOwnedEntry, contractOwnedEntryWhy } from "./entry-origin.js";
+import { LEG_NAMES } from "./types.js";
 /** ZodError 形(鸭子判,不用 `instanceof` —— historical 模式下旧版 dist 可能挂在另一份 zod 上)。 */
 const isZodLike = (e) => e !== null && typeof e === "object" && Array.isArray(e.issues);
 /** 内容哈希那一层拒绝的自述 —— `stableStringify` 的深度闸是**本包自己**抛的、也只有它会抛这一句;
@@ -21,7 +28,37 @@ const reject = (e, fallback) => {
     const stage = isZodLike(e) ? "validate" : diagnostics.startsWith(HASH_STAGE_MARK) ? "hash" : fallback;
     return { outcome: "rejected", stage, diagnostics };
 };
+/**
+ * 入口的**运行期拒**(fail-closed):三条腿的入口一条都不许落在**这份正在跑的**契约包自己的构建产物里,
+ * 缺席也不行。判别式与拒绝句来自 `./entry-origin.js`,这里只负责「拒」这个动作 —— 以及**按形分派**:
+ * 工厂看不见 `mode`,所以它只拒在任何模式下都错的那一形(`own-build-output` = 拿自己比自己);
+ * `another-installed-copy` 在 `historical` 模式下是正当的(那个模式就是拿旧版包比行为,而旧版包常常正好
+ * 装在 `node_modules/<包名>/` 布局下)⇒ 留给看得见 mode 的 release 门点名,工厂不越权。
+ * 形是闭集,`default` 那支是**编译期**守卫:新加一形而不在这里表态 ⇒ `never` 赋值红。
+ */
+function refuseContractOwnedEntries(entries) {
+    for (const leg of LEG_NAMES) {
+        const entry = entries[leg];
+        if (entry === undefined || typeof entry.module !== "string" || entry.module.length === 0) {
+            throw new Error(`conformance: leg \`${leg}\` 缺 entry.module —— 三条腿各自的**生产入口**坐标是必填的(来源律 §2d-2)`);
+        }
+        const owned = contractOwnedEntry(entry.module);
+        if (owned === undefined)
+            continue;
+        switch (owned.form) {
+            case "own-build-output":
+                throw new Error(`conformance: ${contractOwnedEntryWhy(leg, entry.module, owned)}`);
+            case "another-installed-copy":
+                continue; // 见上:historical 模式的正当形,归看得见 mode 的 release 门判
+            default: {
+                const unhandled = owned.form;
+                throw new Error(`conformance: 来源律判别式回了一个没人处置的形 ${JSON.stringify(unhandled)}`);
+            }
+        }
+    }
+}
 export function createContractAdapter(opts) {
+    refuseContractOwnedEntries(opts.entries);
     const { mod } = opts;
     const run = async (input) => {
         const warnings = [];

package/dist/conformance/entry-origin.d.ts

@@ -0,0 +1,24 @@
+/** 契约包在盘上的两种样子(闭集):**我自己**,与**另一份**。 */
+export declare const CONTRACT_OWNED_FORMS: readonly ["own-build-output", "another-installed-copy"];
+export type ContractOwnedForm = (typeof CONTRACT_OWNED_FORMS)[number];
+/** 判别式命中:哪一形、命中的是哪一段路径(拒绝句要说得出「你落在哪儿」)。 */
+export interface ContractOwnedEntry {
+    form: ContractOwnedForm;
+    /** 命中的那段路径前缀(逐字,给人看的坐标)。 */
+    anchor: string;
+}
+/**
+ * 这个入口坐标落在契约包自己身上吗?命中回形与坐标,没命中回 `undefined`。
+ *
+ * ⚠️ **两形的判定顺序是承重的**:消费方装好的那份 kit **自己就住在 `node_modules/<包名>/` 里**,它的
+ * `dist/` 同时命中两形。「是不是**我自己**」必须先判 —— 否则最该拒的那一形(消费方拿自己比自己)会被
+ * 判成「另一份」而被工厂放行。先 `dist` 后 `node_modules`,两形于是不相交:`another-installed-copy`
+ * 字面意思就是**另一份**装好的契约包(historical 模式的正当目标)。
+ *
+ * ⚠️ **判之前先归一**(两侧都归):`<包根>/./dist/x.js` 与 `<包根>//dist/x.js` 与一条指向 `<包根>/dist`
+ * 的软链,指的都是同一个文件。release 门会先 `realpath` 再判,但 `historical` 模式根本不跑那道门 ——
+ * 工厂这一侧是那条路上唯一的闸,所以归一得在**判别式里**做,两处执法才咬同一个判据。
+ */
+export declare function contractOwnedEntry(modulePath: string): ContractOwnedEntry | undefined;
+/** 拒绝句/违例句共用的那一段:你落在哪儿、合法的是哪儿。两处文案同源,消费方读到的是同一句话。 */
+export declare function contractOwnedEntryWhy(leg: string, modulePath: string, owned: ContractOwnedEntry): string;

package/dist/conformance/entry-origin.js

@@ -0,0 +1,86 @@
+/**
+ * 来源律的**判别式**(§2d-2 同义反复护栏)——「这条腿的入口,其实就是契约包自己吗?」
+ *
+ * 成案:消费方登记的腿必须是**自己生产代码**的入口。把契约包的函数注册成腿,门证明的只是「包等于包」:
+ * 一次纯粹的同义反复,而且看起来全绿。判据落在**入口坐标**上,不在「你调了谁」上 —— 后者机器证不了
+ * (`docs/CONFORMANCE.md` 逐字写明了这条诚实边界)。
+ *
+ * **一只判别式,两处执法**(单铸,不许两处各写一遍「哪儿算契约包自己」)。两形是个**闭集**
+ * ({@link CONTRACT_OWNED_FORMS}),而**哪一形归哪一处**由一句话定:**工厂只拒在任何模式下都错的那一形**,
+ * 另一形归**看得见 `mode`** 的那道门。
+ *   · `own-build-output` —— 入口落在**正在跑这段码的这份**契约包自己的构建产物 `<包根>/dist/` 下。
+ *     这是「拿自己比自己」,`release` 与 `historical` 两个模式下都是同义反复 ⇒ {@link createContractAdapter}
+ *     造适配器时**当场拒**(运行期拒,不是告警)。
+ *   · `another-installed-copy` —— 入口落在**另一份**装好的契约包(`node_modules/<包名>/`)里。它在 `release`
+ *     下是同义反复,在 `historical` 下却**正当**(那个模式就是拿旧版包比行为,而旧版包常常正好装在
+ *     `node_modules/<包名>/` 这个布局下)⇒ 工厂**不拒**(工厂看不见 `mode`,不越权),由 `runConformance`
+ *     的 release 门记成违例。
+ * 手写的适配器字面量(接入文档的默认配方)根本走不到工厂 ⇒ 那道门**两形都判**。
+ *
+ * 为什么 `own-build-output` 咬 `dist/` 而不是整个包根:契约仓**自证**时,腿的入口是本仓的 `src/*.ts`
+ * (那对契约仓来说就是它的生产入口,是这只工厂存在的两个理由之一),而 `src/` 不随包发 —— 消费方手上
+ * 只有 `dist/`。于是同一条判据既拦住了消费方的同义反复,又放行了契约仓自证;historical 模式拿
+ * **另一份**旧版包当入口,那份不是「自己」,照样放行。
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { PACKAGE_ROOT } from "./corpus.js";
+/** 契约包在盘上的两种样子(闭集):**我自己**,与**另一份**。 */
+export const CONTRACT_OWNED_FORMS = ["own-build-output", "another-installed-copy"];
+let cachedName;
+/** 本包的名字 —— 从**自己**的 package.json 读(不手抄;`kitIdentity()` 读的是同一个文件)。读不出来就抛:
+ *  一只判不了「哪儿是契约包自己」的判别式,静默放行等于把来源律整条关掉。 */
+function contractPackageName() {
+    if (cachedName === undefined) {
+        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+        if (typeof pkg.name !== "string" || pkg.name.length === 0) {
+            throw new Error("conformance: 契约包自己的 package.json 没有 `name` —— 来源律判别式判不了「哪儿是契约包自己」");
+        }
+        cachedName = pkg.name;
+    }
+    return cachedName;
+}
+/** 一条路径的**归一形**(判据咬的是**文件**,不是字符串):点段 / 双斜杠先由 `resolve` 抹平,再尽力解一次
+ *  软链(`npm link` 出来的树就是软链)。文件不在盘上 ⇒ 解不了,那就只用字面归一形 —— 这不是放行:
+ *  「入口不存在」本来就由 release 门单独点名,这里少一个候选形不会让任何一形逃掉。 */
+function canonicalForms(p) {
+    const lexical = resolve(p);
+    try {
+        const real = realpathSync(lexical);
+        return real === lexical ? [lexical] : [lexical, real];
+    }
+    catch {
+        return [lexical];
+    }
+}
+/**
+ * 这个入口坐标落在契约包自己身上吗?命中回形与坐标,没命中回 `undefined`。
+ *
+ * ⚠️ **两形的判定顺序是承重的**:消费方装好的那份 kit **自己就住在 `node_modules/<包名>/` 里**,它的
+ * `dist/` 同时命中两形。「是不是**我自己**」必须先判 —— 否则最该拒的那一形(消费方拿自己比自己)会被
+ * 判成「另一份」而被工厂放行。先 `dist` 后 `node_modules`,两形于是不相交:`another-installed-copy`
+ * 字面意思就是**另一份**装好的契约包(historical 模式的正当目标)。
+ *
+ * ⚠️ **判之前先归一**(两侧都归):`<包根>/./dist/x.js` 与 `<包根>//dist/x.js` 与一条指向 `<包根>/dist`
+ * 的软链,指的都是同一个文件。release 门会先 `realpath` 再判,但 `historical` 模式根本不跑那道门 ——
+ * 工厂这一侧是那条路上唯一的闸,所以归一得在**判别式里**做,两处执法才咬同一个判据。
+ */
+export function contractOwnedEntry(modulePath) {
+    const candidates = canonicalForms(modulePath);
+    const ownDists = canonicalForms(join(PACKAGE_ROOT, "dist")).map((d) => d + sep);
+    for (const anchor of ownDists) {
+        if (candidates.some((c) => c.startsWith(anchor)))
+            return { form: "own-build-output", anchor };
+    }
+    const installed = `${sep}node_modules${sep}${contractPackageName().split("/").join(sep)}${sep}`;
+    if (candidates.some((c) => c.includes(installed)))
+        return { form: "another-installed-copy", anchor: installed };
+    return undefined;
+}
+/** 拒绝句/违例句共用的那一段:你落在哪儿、合法的是哪儿。两处文案同源,消费方读到的是同一句话。 */
+export function contractOwnedEntryWhy(leg, modulePath, owned) {
+    return (`leg \`${leg}\` entry.module sits inside the contract package (${modulePath}) —— 命中 ${owned.form} @ ${owned.anchor};` +
+        `那条腿证明的是「包等于包」。合法的入口 = **你自己生产代码**里那个真入口文件的绝对路径` +
+        `(消费方:对着你自己的装配层求 \`fileURLToPath(import.meta.url)\`;契约仓自证:本仓 \`src/*.ts\`;` +
+        `historical 模式:另一份旧版包的 dist)。见 docs/CONFORMANCE.md 的来源律一节。`);
+}

package/dist/conformance/run.js

@@ -18,12 +18,10 @@ import { canonicalize, deepEqual, diffJson, stableKey } from "./canonical.js";
 import { diffWarningMultiset, findSecretLeaks, projectWarning } from "./warnings.js";
 import { deriveLocalExpectation, deriveLocalInput, deriveWireExpectation, deriveWireInput, toManifestDoc } from "./derive.js";
 import { kitIdentity, loadCorpus } from "./corpus.js";
+import { contractOwnedEntry, contractOwnedEntryWhy } from "./entry-origin.js";
 import { LEG_NAMES, } from "./types.js";
 /** 一个**模块**文件的样子 —— 来源律用它挡住「随便找个存在的文件当入口」(`package.json` 也是文件)。 */
 const MODULE_EXTENSIONS = [".ts", ".mts", ".cts", ".tsx", ".js", ".mjs", ".cjs", ".jsx"];
-/** 契约包装在 `node_modules` 里的样子 —— 来源律用它判「这条腿其实就是契约包自己」。按**包名**拼,
- *  不手抄(包名从 kit 自己的 package.json 来)。 */
-const contractInNodeModules = (packageName) => `${sep}node_modules${sep}${packageName.split("/").join(sep)}${sep}`;
 /**
  * 把一份 `config.d/` 快照落成真目录 —— **kit 单铸**,消费方零复述(每个消费方各写一遍落盘逻辑,
  * mtime 怎么设、目录怎么建就会各不相同,而 `updatedAt` 正是按 mtime 算的)。
@@ -330,9 +328,11 @@ async function releaseViolations(adapter, opts, corpus, kit) {
         catch {
             v.push(`leg \`${name}\` entry.module does not exist: ${mod}`);
         }
-        const insideContract = contractInNodeModules(kit.name);
-        if (mod.includes(insideContract) || real.includes(insideContract))
-            v.push(`leg \`${name}\` entry.module sits inside the contract package (${mod}) — 那条腿证明的是「包等于包」`);
+        // 来源律判别式 = `./entry-origin.js` 那一只(工厂当场拒的同一只)。点段 / 双斜杠 / 软链的归一在
+        // 判别式**里面**做(两处执法咬同一个判据),所以这里不再自己解一遍。
+        const owned = contractOwnedEntry(mod);
+        if (owned !== undefined)
+            v.push(contractOwnedEntryWhy(name, mod, owned));
         if (leg.entry.export.trim().length === 0)
             v.push(`leg \`${name}\` entry.export is empty`);
     }

package/dist/conformance/types.d.ts

@@ -81,7 +81,11 @@ export interface ConformanceProvenance {
  * 同义反复,而且看起来全绿。`module` 必须是消费方**生产代码**里那个真入口文件的绝对路径,`export`
  * 是它导出的那个名字。
  *
- * **门的诚实边界**:kit 能核的是「这个文件真的存在」「它不在契约包的 node_modules 目录之下」。它**不能**
+ * 4.0.0 起这条律**有牙且两处执法**:判别式单铸在 `./entry-origin.js`(两形闭集 —— **我自己**的构建产物 /
+ * **另一份**装好的包)。`createContractAdapter` 看不见 `mode`,只拒在任何模式下都错的那一形(拿自己比自己),
+ * **当场拒**;另一形在 `historical` 下正当,连同手写的适配器字面量(走不到工厂)一起由 `release` 门记成违例。
+ *
+ * **门的诚实边界**:kit 能核的是「这个文件真的存在」「它不落在契约包自己身上」。它**不能**
  * 证明这个文件内部没有直接转调契约函数 —— 那由消费方半场的**变异自证**负责(消费方对自己的折叠/投影层
  * 注入一处变异 ⇒ kit 必红)。本字段是护栏,不是证明,docs/CONFORMANCE.md 逐字写明这一点。
  */

package/dist/conformance/warnings.d.ts

@@ -1,9 +1,10 @@
 /**
- * 告警的**穷举 typed 投影**与**多重集**比对 —— kit 的第二个单铸点。
+ * 告警投影的**多重集比对** —— kit 的第二个单铸点。
  *
- * 为什么是穷举投影而不是「把告警对象整个比一遍」:`error` 字段带的是 zod 的错误对象/文案,它可经脱敏、
- * 可随 zod 小版本改字 —— 比文案就是比实现。所以投影**逐臂列全**每个 kind 的非 `error` 字段,`error`
- * 一律不进比对;但它也不是就这么放过去了:{@link findSecretLeaks} 先断言它不含语料自带的秘密清单。
+ * **投影本身不在这里**(4.0.0):`WarningProjection` / `projectWarning` / `WARNING_KINDS` 的属主是告警联合
+ * 自己的模块 `../config-fns`,本文件只再导出(kit 的进口逐字不变)。投影 = 每臂减掉 `error`,**从联合派生**;
+ * 为什么要剥 `error`:它带的是 zod 的错误对象/文案,可经脱敏、可随 zod 小版本改字 —— 比文案就是比实现。
+ * `error` 因此不进比对,但也不是就这么放过去了:{@link findSecretLeaks} 先断言它不含语料自带的秘密清单。
  *
  * 为什么是**多重集**而不是集合:同一个 kind 在同一个域上发两次(两条坏条目、两处未知键路径)是有信息的
  * —— 去重会让「报了一条」与「报了两条」同形,而那恰是消费方最容易漏折的一类。
@@ -11,51 +12,9 @@
  * 坐标({@link ConfigPath})按**结构**比:段数组进 JSON 编码,`["a.b"]` 与 `["a","b"]`、`["1"]` 与 `[1]`
  * 在编码里都还分得开。kit 内**零** `formatConfigPath` 调用 —— 出门形是给人看的,不是比对用的。
  */
-import type { ConfigPath, EffectiveReadWarning } from "../config-fns.js";
+import { type ConfigPath, type EffectiveReadWarning, type WarningProjection } from "../config-fns.js";
 import type { ConformanceNormalizer } from "./types.js";
-/** {@link EffectiveReadWarning} 的 `kind` 闭集(覆盖律按它计数;新 kind 不登记 ⇒ 下面的 switch 编译红)。 */
-export declare const WARNING_KINDS: readonly ["hosts-grandfathered", "domain-defaulted", "unknown-keys-dropped", "unknown-keys-carried", "legacy-governance-lifted", "entry-dropped", "unread-config-file"];
-export type WarningKind = (typeof WARNING_KINDS)[number];
-/** 一条告警的投影 —— 每臂列全该 kind 的**非 `error`** 字段。 */
-export type WarningProjection = {
-    kind: "hosts-grandfathered";
-    domain: "hosts";
-    droppedNames: readonly string[];
-    truncatedFrom?: number;
-} | {
-    kind: "domain-defaulted";
-    domain: string;
-} | {
-    kind: "unknown-keys-dropped";
-    domain: string;
-    keys: readonly ConfigPath[];
-    truncatedFrom?: number;
-} | {
-    kind: "unknown-keys-carried";
-    domain: string;
-    keys: readonly ConfigPath[];
-    truncatedFrom?: number;
-} | {
-    kind: "legacy-governance-lifted";
-    domain: "governance";
-    keys: readonly ConfigPath[];
-} | {
-    kind: "entry-dropped";
-    domain: string;
-    path: ConfigPath;
-} | {
-    kind: "unread-config-file";
-    file: string;
-    domain?: string;
-    why: string;
-};
-/**
- * 一条告警 → 它的投影。**闭集穷举**:新 kind 不在这里表态就编译红(#157 的闭集纪律)。
- *
- * `truncatedFrom` 缺席时**不铸这个键**(不是铸 `undefined`)—— 规范化会把 `undefined` 值剔掉,两种写法
- * 最终同形,但不铸更诚实:「没有截断」与「截断了 0 条」不该在中间形上分成两件事。
- */
-export declare function projectWarning(w: EffectiveReadWarning): WarningProjection;
+export { WARNING_KINDS, projectWarning, type WarningKind, type WarningProjection } from "../config-fns.js";
 /**
  * 一条投影的**比对归一形**:①坐标过一遍映射(historical 模式把段拼成旧版的点号串;无归一器时是恒等);
  * ②`keys` / `droppedNames` 这两个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,

package/dist/conformance/warnings.js

@@ -1,46 +1,23 @@
-import { canonicalize, stableKey } from "./canonical.js";
-/** {@link EffectiveReadWarning} 的 `kind` 闭集(覆盖律按它计数;新 kind 不登记 ⇒ 下面的 switch 编译红)。 */
-export const WARNING_KINDS = [
-    "hosts-grandfathered",
-    "domain-defaulted",
-    "unknown-keys-dropped",
-    "unknown-keys-carried",
-    "legacy-governance-lifted",
-    "entry-dropped",
-    "unread-config-file",
-];
 /**
- * 一条告警 → 它的投影。**闭集穷举**:新 kind 不在这里表态就编译红(#157 的闭集纪律)。
+ * 告警投影的**多重集比对** —— kit 的第二个单铸点。
+ *
+ * **投影本身不在这里**(4.0.0):`WarningProjection` / `projectWarning` / `WARNING_KINDS` 的属主是告警联合
+ * 自己的模块 `../config-fns`,本文件只再导出(kit 的进口逐字不变)。投影 = 每臂减掉 `error`,**从联合派生**;
+ * 为什么要剥 `error`:它带的是 zod 的错误对象/文案,可经脱敏、可随 zod 小版本改字 —— 比文案就是比实现。
+ * `error` 因此不进比对,但也不是就这么放过去了:{@link findSecretLeaks} 先断言它不含语料自带的秘密清单。
  *
- * `truncatedFrom` 缺席时**不铸这个键**(不是铸 `undefined`)—— 规范化会把 `undefined` 值剔掉,两种写法
- * 最终同形,但不铸更诚实:「没有截断」与「截断了 0 条」不该在中间形上分成两件事。
+ * 为什么是**多重集**而不是集合:同一个 kind 在同一个域上发两次(两条坏条目、两处未知键路径)是有信息的
+ * —— 去重会让「报了一条」与「报了两条」同形,而那恰是消费方最容易漏折的一类。
+ *
+ * 坐标({@link ConfigPath})按**结构**比:段数组进 JSON 编码,`["a.b"]` 与 `["a","b"]`、`["1"]` 与 `[1]`
+ * 在编码里都还分得开。kit 内**零** `formatConfigPath` 调用 —— 出门形是给人看的,不是比对用的。
  */
-export function projectWarning(w) {
-    switch (w.kind) {
-        case "hosts-grandfathered":
-            return { kind: w.kind, domain: w.domain, droppedNames: w.droppedNames, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
-        case "domain-defaulted":
-            return { kind: w.kind, domain: w.domain };
-        // 两臂字段相同但**不合并**:合并后 `kind` 塌成两员的联合,TS 就再也认不出它属于投影联合的哪一员
-        // (真编译红过一次)。逐 kind 一臂,是这张表本来的样子。
-        case "unknown-keys-dropped":
-            return { kind: w.kind, domain: w.domain, keys: w.keys, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
-        case "unknown-keys-carried":
-            return { kind: w.kind, domain: w.domain, keys: w.keys, ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
-        case "legacy-governance-lifted":
-            return { kind: w.kind, domain: w.domain, keys: w.keys };
-        case "entry-dropped":
-            return { kind: w.kind, domain: w.domain, path: w.path };
-        case "unread-config-file":
-            return { kind: w.kind, file: w.file, ...(w.domain === undefined ? {} : { domain: w.domain }), why: w.why };
-        default: {
-            const unhandled = w;
-            // 运行期到不了(本联合由契约包铸造);到了就让它红 —— 一条不认识的告警被静默投影成空,
-            // 正是「门看起来全绿」的那种假绿。
-            throw new Error(`conformance: unknown EffectiveReadWarning kind — ${JSON.stringify(unhandled)}`);
-        }
-    }
-}
+import { projectWarning } from "../config-fns.js";
+import { canonicalize, stableKey } from "./canonical.js";
+// 投影的**属主在 `../config-fns`**(告警联合自己的模块;4.0.0 起)—— kit 只再导出,进口不断。
+// 4.0.0 之前这三件住在本文件里,于是「一条告警有哪些字段」在舰队里有两个属主:契约那边加一个字段,
+// 这边的手写投影不动,而**没有一格会红**。现在投影从联合逐臂派生(`Omit<臂, "error">`),那条缝没了。
+export { WARNING_KINDS, projectWarning } from "../config-fns.js";
 /** 一只**袋**:元素按各自的稳定编码排序,重数保留。比对前归一用,不改变「报了几条」这件事。 */
 const bag = (items) => [...items].sort((a, b) => (stableKey(a) < stableKey(b) ? -1 : stableKey(a) > stableKey(b) ? 1 : 0));
 /**

package/dist/cross-domain.d.ts

@@ -29,10 +29,30 @@ export type SiblingResolver = <K extends keyof DomainConfig>(domain: K) => Promi
 export declare function createSiblingResolver(store: ConfigReader, pending?: Partial<{
     [K in keyof DomainConfig]: DomainConfig[K];
 }>): SiblingResolver;
-/** The domains whose writes carry cross-domain model/roster references we validate at save time. */
-export type RefCheckedDomain = "rosters" | "workers" | "models" | "collab" | "systems" | "entitlement";
-/** Cross-domain ref integrity for a rosters/workers/models/collab/systems value. Paths start with the domain
- *  key (e.g. `["rosters", i, "models", j]`) so a caller can prefix a batch index. Empty = ok. Runtime
- *  resolution stays tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is
- *  friendlier than a silently-wrong roster. */
+/** The domains whose writes carry cross-domain model/roster references we validate at save time — the closed
+ *  set as a RUNTIME VALUE (4.0.0). A consumer that has to ask "is this domain ref-checked?" at runtime (a
+ *  config-rollback path deciding whether to run the guard before writing) could only hand-copy the list
+ *  before, and a hand copy drifts silently: two rollback routes in the admin console each carried a
+ *  five-member copy that had lost `entitlement`, so an entitlement rollback skipped the guard entirely with
+ *  nothing red anywhere. Ask this constant (or {@link isRefCheckedDomain}) instead of writing a list.
+ *
+ *  `satisfies readonly (keyof DomainConfig)[]` keeps every member a real domain key; {@link RefCheckedDomain}
+ *  is DERIVED from this value, so there is exactly one place the set is written down. */
+export declare const REF_CHECKED_DOMAINS: readonly ["rosters", "workers", "models", "collab", "systems", "entitlement"];
+/** The domains whose writes carry cross-domain model/roster references we validate at save time.
+ *  DERIVED from {@link REF_CHECKED_DOMAINS} (4.0.0) — a hand-written union next to the value would be a
+ *  second copy of the same set, free to disagree with it. */
+export type RefCheckedDomain = (typeof REF_CHECKED_DOMAINS)[number];
+/** Runtime narrowing to {@link RefCheckedDomain}, same idiom as `isDomainName`: use it instead of hard-coding
+ *  the set when filtering an arbitrary domain key (a batch payload's keys, a rollback target). */
+export declare function isRefCheckedDomain(d: unknown): d is RefCheckedDomain;
+/** Cross-domain ref integrity for one {@link RefCheckedDomain} value. Every issue `path` starts with the
+ *  DOMAIN KEY (e.g. `["rosters", i, "models", j]`, `["collab", "templates", i, …]`) so a caller can prefix a
+ *  batch index and get a coordinate that is unambiguous across arms. Empty = ok. Runtime resolution stays
+ *  tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is friendlier than a
+ *  silently-wrong roster.
+ *
+ *  4.0.0 made that first sentence TRUE: the `collab` arm used to start its paths at `"templates"` and the
+ *  `entitlement` arm at `"tiers"`, so a caller could not read `path[0]` as the domain. See the CHANGELOG entry
+ *  for the migration (BREAKING, value shape). */
 export declare function refIntegrityIssues(domain: RefCheckedDomain, value: unknown, resolve: SiblingResolver): Promise<RefIssue[]>;

package/dist/cross-domain.js

@@ -12,10 +12,30 @@ export function createSiblingResolver(store, pending) {
         return store.getDomain(domain);
     };
 }
-/** Cross-domain ref integrity for a rosters/workers/models/collab/systems value. Paths start with the domain
- *  key (e.g. `["rosters", i, "models", j]`) so a caller can prefix a batch index. Empty = ok. Runtime
- *  resolution stays tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is
- *  friendlier than a silently-wrong roster. */
+/** The domains whose writes carry cross-domain model/roster references we validate at save time — the closed
+ *  set as a RUNTIME VALUE (4.0.0). A consumer that has to ask "is this domain ref-checked?" at runtime (a
+ *  config-rollback path deciding whether to run the guard before writing) could only hand-copy the list
+ *  before, and a hand copy drifts silently: two rollback routes in the admin console each carried a
+ *  five-member copy that had lost `entitlement`, so an entitlement rollback skipped the guard entirely with
+ *  nothing red anywhere. Ask this constant (or {@link isRefCheckedDomain}) instead of writing a list.
+ *
+ *  `satisfies readonly (keyof DomainConfig)[]` keeps every member a real domain key; {@link RefCheckedDomain}
+ *  is DERIVED from this value, so there is exactly one place the set is written down. */
+export const REF_CHECKED_DOMAINS = ["rosters", "workers", "models", "collab", "systems", "entitlement"];
+/** Runtime narrowing to {@link RefCheckedDomain}, same idiom as `isDomainName`: use it instead of hard-coding
+ *  the set when filtering an arbitrary domain key (a batch payload's keys, a rollback target). */
+export function isRefCheckedDomain(d) {
+    return typeof d === "string" && REF_CHECKED_DOMAINS.includes(d);
+}
+/** Cross-domain ref integrity for one {@link RefCheckedDomain} value. Every issue `path` starts with the
+ *  DOMAIN KEY (e.g. `["rosters", i, "models", j]`, `["collab", "templates", i, …]`) so a caller can prefix a
+ *  batch index and get a coordinate that is unambiguous across arms. Empty = ok. Runtime resolution stays
+ *  tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is friendlier than a
+ *  silently-wrong roster.
+ *
+ *  4.0.0 made that first sentence TRUE: the `collab` arm used to start its paths at `"templates"` and the
+ *  `entitlement` arm at `"tiers"`, so a caller could not read `path[0]` as the domain. See the CHANGELOG entry
+ *  for the migration (BREAKING, value shape). */
 export async function refIntegrityIssues(domain, value, resolve) {
     const issues = [];
     if (domain === "rosters") {
@@ -73,7 +93,7 @@ export async function refIntegrityIssues(domain, value, resolve) {
             t.slots.forEach((s, j) => {
                 s.members.forEach((mem, k) => {
                     if (mem.modelRef && !catalog.has(mem.modelRef))
-                        issues.push({ path: ["templates", i, "slots", j, "members", k, "modelRef"], message: `collab template "${t.id}" slot "${s.id}" → unknown model "${mem.modelRef}" (not in the catalog)`, code: "custom" });
+                        issues.push({ path: ["collab", "templates", i, "slots", j, "members", k, "modelRef"], message: `collab template "${t.id}" slot "${s.id}" → unknown model "${mem.modelRef}" (not in the catalog)`, code: "custom" });
                 });
             });
         });
@@ -101,15 +121,15 @@ export async function refIntegrityIssues(domain, value, resolve) {
         const pluginNames = new Set((await resolve("plugins"))?.plugins.map((p) => p.name) ?? []);
         value.tiers.forEach((t, i) => {
             if (t.roster && !rosterNames.has(t.roster))
-                issues.push({ path: ["tiers", i, "roster"], message: `tier "${t.id}" references unknown roster "${t.roster}"`, code: "custom" });
+                issues.push({ path: ["entitlement", "tiers", i, "roster"], message: `tier "${t.id}" references unknown roster "${t.roster}"`, code: "custom" });
             (t.models ?? []).forEach((name, j) => { if (!modelCatalog.has(name))
-                issues.push({ path: ["tiers", i, "models", j], message: `tier "${t.id}" model "${name}" not in the models catalog`, code: "custom" }); });
+                issues.push({ path: ["entitlement", "tiers", i, "models", j], message: `tier "${t.id}" model "${name}" not in the models catalog`, code: "custom" }); });
             (t.visibleSkills ?? []).forEach((name, j) => { if (!skillNames.has(name))
-                issues.push({ path: ["tiers", i, "visibleSkills", j], message: `tier "${t.id}" visibleSkill "${name}" not in skills`, code: "custom" }); });
+                issues.push({ path: ["entitlement", "tiers", i, "visibleSkills", j], message: `tier "${t.id}" visibleSkill "${name}" not in skills`, code: "custom" }); });
             (t.visibleMcp ?? []).forEach((name, j) => { if (!mcpNames.has(name))
-                issues.push({ path: ["tiers", i, "visibleMcp", j], message: `tier "${t.id}" visibleMcp "${name}" not in mcp`, code: "custom" }); });
+                issues.push({ path: ["entitlement", "tiers", i, "visibleMcp", j], message: `tier "${t.id}" visibleMcp "${name}" not in mcp`, code: "custom" }); });
             (t.visiblePlugins ?? []).forEach((name, j) => { if (!pluginNames.has(name))
-                issues.push({ path: ["tiers", i, "visiblePlugins", j], message: `tier "${t.id}" visiblePlugin "${name}" not in plugins`, code: "custom" }); });
+                issues.push({ path: ["entitlement", "tiers", i, "visiblePlugins", j], message: `tier "${t.id}" visiblePlugin "${name}" not in plugins`, code: "custom" }); });
         });
     }
     else {

package/dist/node.d.ts

@@ -9,3 +9,4 @@ export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
+export * from "./prompts-digest.js";

package/dist/node.js

@@ -9,3 +9,4 @@ export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract
+export * from "./prompts-digest.js"; // prompts 下发包的内容摘要(4.0.0 从 scheduler-store-node 搬来 —— 与调度存储无关;出口路径不变)