@sema-agent/settings-schema 2.1.0 → 3.0.0

package/dist/conformance/types.d.ts

@@ -0,0 +1,288 @@
+/**
+ * 跨仓一致性门(conformance kit)的**形**:一套语料、一个比对器、N 条读腿。
+ *
+ * 成案:2.0.0 / 2.1.0 两版的正确性靠「表态 + 黑盒测试 + 提货车各自红先」,三样都是**单仓视角** ——
+ * 真跨仓分歧是被提货车**碰巧**撞出来的。碰巧不是门。本 kit 让每个消费方把**自己的生产读腿**塞进来跑
+ * 同一份语料:同一份 settings 在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、
+ * 告警多重集一致,否则红。
+ *
+ * 规范化(canonical JSON、告警投影、坐标深相等)全部在 kit 内**单铸** —— 消费方零复述,因为一份被各自
+ * 复述的规范化就是第二份真源,而两份真源的分歧正是本门要抓的那类病。
+ */
+import type { EffectiveReadWarning } from "../config-fns.js";
+/** 三条读腿的名字。**闭集** —— 新开一条腿要同时在语料派生表(`derive.ts` 的 `DERIVATION_TRANSFORMS`)里表态。
+ *
+ *  · `domains`:各域**原始文档**(center 侧存储形)→ effective。契约仓的 `buildEffective`。
+ *  · `wire`:`GET /effective` 载荷 → effective。契约仓的 `readEffectiveWire`。
+ *  · `localRoot`:`config.d/` 目录快照(文件名 → 文件内容)→ effective。契约仓的 `loadLocalConfig`。 */
+export type LegName = "domains" | "wire" | "localRoot";
+/** 三条腿的名字表(运行期枚举用;与 {@link LegName} 同源 —— 多一员少一员编译红)。 */
+export declare const LEG_NAMES: readonly ["domains", "wire", "localRoot"];
+/** 一条读腿的入参。腿名决定形,`domains` 是真源,另两形由 harness 派生(见 derive.ts 的变换表)。 */
+export type LegInput = {
+    leg: "domains";
+    docs: Readonly<Record<string, unknown>>;
+    version: number;
+    updatedAt: string;
+} | {
+    leg: "wire";
+    payload: unknown;
+} | {
+    leg: "localRoot";
+    files: Readonly<Record<string, string>>;
+    mtime: string;
+};
+/**
+ * 一条腿跑完的**结局**。两类,分开报:读出了 effective,或者**拒绝**了。
+ *
+ * `rejected` 不是失败 —— 一份 gate 域坏掉的文档**就该**被拒,那是期望结局。真正的失败是
+ * 「harness 自己炸了」({@link ConformanceStatus} 的 `harness-error`):适配器抛了未受控异常,
+ * 我们连它的表态都没拿到。两件事混在一起报,就再也分不出「契约按设计拒收」与「消费方接线坏了」。
+ *
+ * `stage` 是**闭集**:拒绝发生在哪一层 —— 信封(不是一份 effective)/ 解析 / 校验 / 哈希 / 存储。
+ * `diagnostics` 是人读的一句话,**不参与比对**(它可经脱敏,比文案 = 比实现);比的是 `stage` 与 `code`。
+ */
+export type LegOutcome = {
+    outcome: "effective";
+    effective: unknown;
+    warnings: readonly EffectiveReadWarning[];
+    version?: number;
+    updatedAt?: string;
+} | {
+    outcome: "rejected";
+    stage: RejectStage;
+    code?: string;
+    diagnostics: string;
+};
+/** 拒绝发生的层。闭集 —— 新层要来这里登记(语料的 `stage` 字段按本表校验)。 */
+export type RejectStage = "envelope" | "parse" | "validate" | "hash" | "store";
+/** {@link RejectStage} 的运行期表(语料校验用;与类型同源)。 */
+export declare const REJECT_STAGES: readonly ["envelope", "parse", "validate", "hash", "store"];
+/**
+ * 适配器**实际加载到的那个契约模块**的出处 —— kit 核的是它,不是核自己那份 import。
+ *
+ * 成案:kit 与消费方装的可能根本不是同一份包(monorepo 软链、预发 tarball、忘了重装)。让 kit 核
+ * 「我自己这份包的版本」等于核了个寂寞;适配器必须报**它加载的那份**的 package.json 路径、版号与
+ * 完整性串,release 模式三者与语料版本对齐才算数。
+ */
+export interface ConformanceProvenance {
+    /** 适配器加载到的契约包的 `package.json` **绝对路径**。 */
+    packageJsonPath: string;
+    /** 那份 package.json 里的 `version`。 */
+    version: string;
+    /** 它的完整性串 —— 预发 tarball 的 `sha256:<hex>`,或 npm 装包时记下的 `integrity`。语料不校验其值,
+     *  只要求**在场且非空**:它是人工核对「三仓装的是同一份 tarball」的那一行。 */
+    integrity: string;
+}
+/**
+ * 一条腿的**生产入口**坐标(同义反复护栏,§2d-2)。
+ *
+ * 成案:如果消费方在测试里把契约包的函数本身注册成读腿,这道门证明的是「包等于包」—— 一次纯粹的
+ * 同义反复,而且看起来全绿。`module` 必须是消费方**生产代码**里那个真入口文件的绝对路径,`export`
+ * 是它导出的那个名字。
+ *
+ * **门的诚实边界**:kit 能核的是「这个文件真的存在」「它不在契约包的 node_modules 目录之下」。它**不能**
+ * 证明这个文件内部没有直接转调契约函数 —— 那由消费方半场的**变异自证**负责(消费方对自己的折叠/投影层
+ * 注入一处变异 ⇒ kit 必红)。本字段是护栏,不是证明,docs/CONFORMANCE.md 逐字写明这一点。
+ */
+export interface LegEntry {
+    /** 生产入口文件的**绝对路径**(消费方自己 `fileURLToPath(import.meta.url)` 出来的那个,不是手抄串)。 */
+    module: string;
+    /** 该文件里被当作读腿入口的导出名。 */
+    export: string;
+}
+/** 一条登记进 kit 的读腿:它的生产入口 + 真正跑它的那只函数。 */
+export interface ConformanceLeg {
+    entry: LegEntry;
+    run(input: LegInput): Promise<LegOutcome> | LegOutcome;
+}
+/**
+ * 消费方对金样的一条**已知合法差异**的登记位 —— 临时欠账,或成文语义。
+ *
+ * 成案:消费方对金样的合法差异今天只能写在测试注里,而散文不是判据 —— 谁也说不清「这条差异还在不在」。
+ * 登记之后它变成机器可核的一行:命中即 `diff-ledgered`(不阻塞),**从未命中即违例**(`stale ledger entry`)。
+ * 这条反向律是本形的重点:与本仓 silent-degradation 棘轮同律,只降不升 —— 债还了就得把账本删掉,
+ * 否则它自己会把门顶红。
+ *
+ * **只收 effective 的差**:告警与元数据差永不可入账(见 {@link ConformanceStatus} 的 `diff-ledgered`)。
+ * **逐坐标**白名单而不是整格豁免:同一格里多一条没登记的坐标,整格仍然是 `diff`。
+ */
+export type KnownDivergence = PathDivergence | OutcomeDivergence;
+/** 一条**坐标形**登记:effective 的某一片值与金样不同。判别位 = 有 `pathPrefix`、没有 `outcome`。 */
+export interface PathDivergence {
+    /** 这条登记管哪条腿。 */
+    leg: LegName;
+    /** 只管这几个 case;缺席 = 这条腿上的所有 case。 */
+    cases?: readonly string[];
+    /** effective diff 的 **JSON Pointer 段前缀**:盖住 `pathPrefix` 本身与 `pathPrefix + "/"` 之下的整棵子树,
+     *  **不**盖名字更长的相邻坐标(登记 `/limits/infraCostRates` 不豁免 `/limits/infraCostRatesInjected`,
+     *  登记 `/models/1` 不豁免 `/models/10`)。必须以 `/` 开头并**点名至少一个顶层键** —— `/` 或空串是
+     *  一个 `ok=true` 开关,不是账本。 */
+    pathPrefix: string;
+    /** `"debt"` = 临时欠账(`ref` 是台账号);`"declared"` = 消费方成文语义(`ref` 是契约 / 文档锚)。 */
+    kind: "debt" | "declared";
+    /** 台账号或文档锚 —— 报告按它分组,人照它去查这笔差异的出处。 */
+    ref: string;
+    /** 什么时候该把这一条删掉(债还了 / 语义改了)。人读,非空。 */
+    flipWhen: string;
+    outcome?: never;
+}
+/**
+ * 一条**结局形**登记:契约期望这条腿**拒绝**,而消费方读出了 effective(降级 + 诊断),或反过来。
+ *
+ * 成案(接线实跑):这类差根本没有 effective patch —— 比对停在「结局形就不一样」那一步,坐标形账本
+ * 按 `pathPrefix` 够不着它,于是消费方 `ok` 恒 false,而它恰恰是门最该点名、也最该逼着修的一类。
+ *
+ * 两条硬约束,都是为了不让它变成一张万能豁免:
+ *  · **`cases` 必填且非空** —— 结局形分歧不许按前缀大包一整条腿的拒绝面;
+ *  · **只能是 `kind:"debt"`** —— 契约说拒、消费方说不拒,这不是「成文语义」盖得住的分歧,只能是债,
+ *    带台账号、带翻转条件,由 stale 律逼着到期删掉。
+ */
+export interface OutcomeDivergence {
+    kind: "debt";
+    outcome: {
+        leg: LegName;
+        /** **必填且非空**:结局形登记只管点名的这几个 case。 */
+        cases: readonly string[];
+        /** 金样说这条腿该是什么结局。 */
+        expected: "rejected" | "effective";
+        /** 消费方实际给出的结局。 */
+        actual: "rejected" | "effective";
+    };
+    ref: string;
+    flipWhen: string;
+    leg?: never;
+    pathPrefix?: never;
+}
+/** 一个消费方交给 kit 的东西:它是谁、它加载的契约包是哪一份、它有哪几条生产读腿。 */
+export interface ConformanceAdapter {
+    /** 消费方名(语料 `contributor` 同词表:`server` / `web-admin` / `cli` / `client-core` / `test` / `contract`)。 */
+    name: string;
+    provenance: ConformanceProvenance;
+    /**
+     * **只登记你真有的腿**。未登记 = 这个消费方结构上没有这条读法(例:worker 服务的生产代码里没有
+     * `buildEffective` 调用点,它只有 wire 腿与 local-root 腿)—— 报告逐格记 `skipped: no adapter`
+     * (覆盖矩阵看得见它没跑),**不算违例**。
+     *
+     * release 模式的两条律都指向**登记过的东西**:①至少登记一条腿;②**登记的腿必须跑** —— 登记了却在
+     * 整套语料上一格真读数都没有,那条登记是空的,违例。
+     */
+    legs: Partial<Record<LegName, ConformanceLeg>>;
+    /** 已知的**合法**差异账本(见 {@link KnownDivergence})。缺席 = 零容忍,任何 diff 都阻塞。 */
+    knownDivergences?: readonly KnownDivergence[];
+}
+/**
+ * historical 模式的**有损归一器**:把旧版包的读数与今天的语料放进同一个空间比。
+ *
+ * 它必须**自陈有损**(`lossy`):2.1.0 的告警坐标是点号串,3.0.0 是段数组 —— 归一就是把段数组按
+ * `.` 拼成串,而那正是 3.0.0 要消掉的那个有损编码(`["a.b"]` 与 `["a","b"]` 归一后同串)。自陈的
+ * 意义在于:`firstRedOn` 的读数要能说出「这条没红是因为归一器把它抹平了」这种可能,而不是假装
+ * 旧版与新版一致。
+ */
+export interface ConformanceNormalizer {
+    /** 归一器身份(写进报告:`settings-schema@2.1.0`)。 */
+    id: string;
+    /** 自陈有损与否 —— 有损的归一器,其「零 diff」读数**不是**「行为相同」的证明。 */
+    lossy: boolean;
+    /** 有损在哪一处(人读,进报告)。 */
+    why: string;
+    /** 把一条坐标归一到共同空间。有损归一器在这里把段拼成串。 */
+    path(p: readonly (string | number)[]): unknown;
+}
+/**
+ * 一格结局。`pass` / `expected-rejected` / `diff-ledgered` 不阻塞,`diff` / `harness-error` 红,
+ * `skipped` 既不绿也不红(没跑)。
+ *
+ * `diff-ledgered`(3.0.0 车 FT):这一格的 effective 差**逐坐标**落在适配器的
+ * {@link KnownDivergence} 账本里 —— 一笔登记在案的合法差异,不阻塞,但单独计数、按 `ref` 列出来。
+ * **告警差与元数据差永不进这一格**:它们是这道门的承重面,一条被「已知」掉的告警差正是本门要抓的病。
+ */
+export type ConformanceStatus = "pass" | "diff" | "diff-ledgered" | "expected-rejected" | "harness-error" | "skipped";
+/** effective 的一处差:JSON Pointer 坐标 + 两侧的值(`undefined` = 该侧没有这个位置)。 */
+export interface EffectivePatch {
+    op: "add" | "remove" | "replace";
+    /** RFC 6901 JSON Pointer —— 这是**诊断输出**,不是比对输入(比对走结构化深相等)。 */
+    path: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/** 告警多重集的差:期望里有而实际没有的、实际里有而期望没有的(各自带重数)。 */
+export interface WarningMultisetDiff {
+    missing: readonly unknown[];
+    extra: readonly unknown[];
+}
+/** 一个 case × 一条腿的读数。 */
+export interface ConformanceResult {
+    caseId: string;
+    leg: LegName;
+    status: ConformanceStatus;
+    /** 一句话:为什么是这个 status(skipped 说哪条腿没登记;harness-error 说抛了什么)。 */
+    detail: string;
+    /** `status === "diff"` / `"diff-ledgered"` 时才在场。`outcome` 只在**结局形**不一致时在场 ——
+     *  那种差没有 effective patch(比对停在「结局形就不一样」那一步),靠 `detail` 文案分辨等于没有判据。 */
+    diff?: {
+        effective: readonly EffectivePatch[];
+        warnings: WarningMultisetDiff;
+        metadata: readonly EffectivePatch[];
+        outcome?: {
+            expected: "rejected" | "effective";
+            actual: "rejected" | "effective";
+            stage?: RejectStage;
+        };
+    };
+    /** `status === "diff-ledgered"` 时在场:盖住这一格的账本条目 `ref`(逐坐标,按 diff 顺序)。 */
+    ledgerRefs?: readonly string[];
+}
+/** 报告里的一行账本:登记内容 + 它这一跑**命中了几条 diff**。`hits === 0` ⇒ 陈腐(release 模式违例)。 */
+export interface LedgerRow {
+    ref: string;
+    kind: KnownDivergence["kind"];
+    leg: LegName;
+    /** 坐标形登记的段前缀(见 {@link PathDivergence.pathPrefix});**结局形**登记没有这一项。 */
+    pathPrefix?: string;
+    /** 结局形登记盯的那对结局;**坐标形**登记没有这一项。 */
+    outcome?: {
+        expected: "rejected" | "effective";
+        actual: "rejected" | "effective";
+    };
+    cases?: readonly string[];
+    flipWhen: string;
+    hits: number;
+}
+/** 一次跑的报告。 */
+export interface ConformanceReport {
+    mode: ConformanceMode;
+    adapter: {
+        name: string;
+        provenance: ConformanceProvenance;
+        legs: readonly LegName[];
+    };
+    /** 语料版本(`conformance/VERSION`)。 */
+    corpusVersion: string;
+    /** kit 自己所在包的版本(= 语料应当对齐的那个)。 */
+    kitVersion: string;
+    normalizer?: {
+        id: string;
+        lossy: boolean;
+        why: string;
+    };
+    results: readonly ConformanceResult[];
+    summary: Readonly<Record<ConformanceStatus, number>>;
+    /** 适配器账本逐条的命中数(按 `ref` 读)。空数组 = 这个适配器没挂账本。 */
+    ledger: readonly LedgerRow[];
+    /** 四律里**不按 case 计**的违例(来源律 / 版本护栏 / release 禁 only 与禁 skipped)。非空 ⇒ `ok:false`。 */
+    violations: readonly string[];
+    /** 全绿 = 零**未入账** diff / 零 harness-error / 零 violations(未登记的腿的 `skipped` 不算红)。 */
+    ok: boolean;
+}
+/** 两种模式。 */
+export type ConformanceMode = "release" | "historical";
+export interface ConformanceOptions {
+    mode: ConformanceMode;
+    /** 只跑这几个 case(调试用)。**release 模式禁用** —— 一个能挑 case 的发版门不是门。 */
+    only?: readonly string[];
+    /** 语料目录;默认 = 本包的 `conformance/`。 */
+    corpusDir?: string;
+    /** historical 模式的归一器。release 模式传了即违例(归一器只用来看旧版,不用来放宽今天的门)。 */
+    normalizer?: ConformanceNormalizer;
+}

package/dist/conformance/types.js

@@ -0,0 +1,4 @@
+/** 三条腿的名字表(运行期枚举用;与 {@link LegName} 同源 —— 多一员少一员编译红)。 */
+export const LEG_NAMES = ["domains", "wire", "localRoot"];
+/** {@link RejectStage} 的运行期表(语料校验用;与类型同源)。 */
+export const REJECT_STAGES = ["envelope", "parse", "validate", "hash", "store"];

package/dist/conformance/warnings.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 告警的**穷举 typed 投影**与**多重集**比对 —— kit 的第二个单铸点。
+ *
+ * 为什么是穷举投影而不是「把告警对象整个比一遍」:`error` 字段带的是 zod 的错误对象/文案,它可经脱敏、
+ * 可随 zod 小版本改字 —— 比文案就是比实现。所以投影**逐臂列全**每个 kind 的非 `error` 字段,`error`
+ * 一律不进比对;但它也不是就这么放过去了:{@link findSecretLeaks} 先断言它不含语料自带的秘密清单。
+ *
+ * 为什么是**多重集**而不是集合:同一个 kind 在同一个域上发两次(两条坏条目、两处未知键路径)是有信息的
+ * —— 去重会让「报了一条」与「报了两条」同形,而那恰是消费方最容易漏折的一类。
+ *
+ * 坐标({@link ConfigPath})按**结构**比:段数组进 JSON 编码,`["a.b"]` 与 `["a","b"]`、`["1"]` 与 `[1]`
+ * 在编码里都还分得开。kit 内**零** `formatConfigPath` 调用 —— 出门形是给人看的,不是比对用的。
+ */
+import type { ConfigPath, EffectiveReadWarning } 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;
+/**
+ * 一条投影的**比对归一形**:①坐标过一遍映射(historical 模式把段拼成旧版的点号串;无归一器时是恒等);
+ * ②`keys` / `droppedNames` 这两个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
+ * 写在这里一次。
+ *
+ * 为什么集合字段要按袋比(codex R1 [medium] 复现):一条告警里的 `keys` 是「这些键被剥了」的**一只袋**,
+ * 它的顺序来自文档的枚举次序,契约从没承诺过。照序列比,消费方只要换个扫描次序,就会在 effective、坐标
+ * 与重数全都相同的情况下把发版门顶红 —— 那是纯粹的假红。**重数仍然保留**(同一条坐标报两次 ≠ 报一次),
+ * 而一条 {@link ConfigPath} **内部**的段序当然仍是序列(`["a","b"]` 与 `["b","a"]` 是两条不同的坐标)。
+ */
+export declare function normalizeProjection(p: WarningProjection, f: (path: ConfigPath) => unknown): unknown;
+/** 一条投影的比对键。 */
+export declare function projectionKey(p: WarningProjection, normalizer?: ConformanceNormalizer): string;
+/** 一条投影的规范形(进报告的 `missing`/`extra` 用,人读)。 */
+export declare function projectionValue(p: WarningProjection, normalizer?: ConformanceNormalizer): unknown;
+/**
+ * 两个投影**多重集**的差。重数保留:期望两条、实际一条 ⇒ `missing` 里留一条。
+ */
+export declare function diffWarningMultiset(expected: readonly WarningProjection[], actual: readonly WarningProjection[], normalizer?: ConformanceNormalizer): {
+    missing: unknown[];
+    extra: unknown[];
+};
+/**
+ * 告警面(投影 + `error` 文案)里有没有语料自带的秘密。
+ *
+ * 口径(诚实登记,docs/CONFORMANCE.md 同步写明):扫的是**告警**,不是 effective。effective 里逐字承运
+ * 运维自己写下的那份文档是契约(配置就是他写的那份),而告警是**本包自己铸的新文本** —— 一条把秘密
+ * 抄进坐标或错误文案的告警,会把秘密带进日志、审计流、管理面,那才是「告警比它诊断的东西更危险」。
+ */
+export declare function findSecretLeaks(warnings: readonly EffectiveReadWarning[], secrets: readonly string[]): string[];

package/dist/conformance/warnings.js

@@ -0,0 +1,144 @@
+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 的闭集纪律)。
+ *
+ * `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(`conformance: unknown EffectiveReadWarning kind — ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/** 一只**袋**:元素按各自的稳定编码排序,重数保留。比对前归一用,不改变「报了几条」这件事。 */
+const bag = (items) => [...items].sort((a, b) => (stableKey(a) < stableKey(b) ? -1 : stableKey(a) > stableKey(b) ? 1 : 0));
+/**
+ * 一条投影的**比对归一形**:①坐标过一遍映射(historical 模式把段拼成旧版的点号串;无归一器时是恒等);
+ * ②`keys` / `droppedNames` 这两个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
+ * 写在这里一次。
+ *
+ * 为什么集合字段要按袋比(codex R1 [medium] 复现):一条告警里的 `keys` 是「这些键被剥了」的**一只袋**,
+ * 它的顺序来自文档的枚举次序,契约从没承诺过。照序列比,消费方只要换个扫描次序,就会在 effective、坐标
+ * 与重数全都相同的情况下把发版门顶红 —— 那是纯粹的假红。**重数仍然保留**(同一条坐标报两次 ≠ 报一次),
+ * 而一条 {@link ConfigPath} **内部**的段序当然仍是序列(`["a","b"]` 与 `["b","a"]` 是两条不同的坐标)。
+ */
+export function normalizeProjection(p, f) {
+    switch (p.kind) {
+        case "unknown-keys-dropped":
+        case "unknown-keys-carried":
+        case "legacy-governance-lifted":
+            return { ...p, keys: bag(p.keys.map(f)) };
+        case "entry-dropped":
+            return { ...p, path: f(p.path) };
+        case "hosts-grandfathered":
+            return { ...p, droppedNames: bag(p.droppedNames) };
+        case "domain-defaulted":
+        case "unread-config-file":
+            return p;
+        default: {
+            const unhandled = p;
+            throw new Error(`conformance: unknown warning projection kind — ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/** 恒等坐标映射(无归一器时的那一只)。 */
+const identityPath = (path) => path;
+/** 一条投影的比对键。 */
+export function projectionKey(p, normalizer) {
+    return stableKey(normalizeProjection(p, normalizer === undefined ? identityPath : normalizer.path));
+}
+/** 一条投影的规范形(进报告的 `missing`/`extra` 用,人读)。 */
+export function projectionValue(p, normalizer) {
+    return canonicalize(normalizeProjection(p, normalizer === undefined ? identityPath : normalizer.path));
+}
+/**
+ * 两个投影**多重集**的差。重数保留:期望两条、实际一条 ⇒ `missing` 里留一条。
+ */
+export function diffWarningMultiset(expected, actual, normalizer) {
+    const count = new Map();
+    const sample = new Map();
+    for (const p of expected) {
+        const k = projectionKey(p, normalizer);
+        count.set(k, (count.get(k) ?? 0) + 1);
+        if (!sample.has(k))
+            sample.set(k, projectionValue(p, normalizer));
+    }
+    for (const p of actual) {
+        const k = projectionKey(p, normalizer);
+        count.set(k, (count.get(k) ?? 0) - 1);
+        if (!sample.has(k))
+            sample.set(k, projectionValue(p, normalizer));
+    }
+    const missing = [];
+    const extra = [];
+    for (const [k, n] of [...count.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+        for (let i = 0; i < n; i++)
+            missing.push(sample.get(k));
+        for (let i = 0; i < -n; i++)
+            extra.push(sample.get(k));
+    }
+    return { missing, extra };
+}
+/** 秘密扫描的拼接分隔串 —— 刻意是一段不会出现在任何配置里的字面,且**不是控制字节**(测试/源码里
+ *  放真控制字节会被别的门扫到);它的作用只是不让两条告警的尾首拼出一个假阳性。 */
+const JOINER = "\n<<conformance-scan-boundary>>\n";
+/** 一条告警的 `error` 的人读文案(只给秘密扫描用,永不进比对)。 */
+function errorText(w) {
+    if (!("error" in w))
+        return "";
+    const e = w.error;
+    if (e === undefined || e === null)
+        return "";
+    if (e instanceof Error)
+        return `${e.name}: ${e.message}${JOINER}${e.stack ?? ""}`;
+    try {
+        return typeof e === "string" ? e : JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+/**
+ * 告警面(投影 + `error` 文案)里有没有语料自带的秘密。
+ *
+ * 口径(诚实登记,docs/CONFORMANCE.md 同步写明):扫的是**告警**,不是 effective。effective 里逐字承运
+ * 运维自己写下的那份文档是契约(配置就是他写的那份),而告警是**本包自己铸的新文本** —— 一条把秘密
+ * 抄进坐标或错误文案的告警,会把秘密带进日志、审计流、管理面,那才是「告警比它诊断的东西更危险」。
+ */
+export function findSecretLeaks(warnings, secrets) {
+    if (secrets.length === 0)
+        return [];
+    const hay = warnings.map((w) => `${stableKey(projectWarning(w))}${JOINER}${errorText(w)}`).join(JOINER);
+    return secrets.filter((s) => s.length > 0 && hay.includes(s));
+}

package/dist/file-store.d.ts

@@ -17,6 +17,13 @@ import { type DomainConfig, type DomainName, type EffectiveConfig } from "./type
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
 export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution", "prompts", "limits"];
 export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
+/** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
+ *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
+ *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
+ *
+ *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
+ *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
+export declare const NON_DOMAIN_CONFIG_FILES: ReadonlySet<string>;
 /**
  * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
  *

package/dist/file-store.js

@@ -42,8 +42,12 @@ import { isDomainName } from "./types.js";
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
 export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution", "prompts", "limits"];
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
- *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读。 */
-const NON_DOMAIN_CONFIG_FILES = new Set(["remote-exec.json"]);
+ *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
+ *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
+ *
+ *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
+ *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
+export const NON_DOMAIN_CONFIG_FILES = new Set(["remote-exec.json"]);
 /**
  * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",
@@ -51,6 +51,11 @@
       "types": "./dist/config-fns.d.ts",
       "default": "./dist/config-fns.js"
     },
+    "./package.json": "./package.json",
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "default": "./dist/conformance/index.js"
+    },
     "./reader": {
       "types": "./dist/reader.d.ts",
       "default": "./dist/reader.js"
@@ -98,14 +103,11 @@
     "./api/scopes": {
       "types": "./dist/api/scopes.d.ts",
       "default": "./dist/api/scopes.js"
-    },
-    "./api/wire": {
-      "types": "./dist/api/wire.d.ts",
-      "default": "./dist/api/wire.js"
     }
   },
   "files": [
     "dist",
+    "conformance",
     "README.md",
     "CHANGELOG.md"
   ],

package/dist/api/wire.d.ts

@@ -1,60 +0,0 @@
-/**
- * `api/wire` — the ZERO-DEPENDENCY wire subset of the auth/scopes contracts (server AI 接手首车,
- * 2026-07-27,跨仓 candidate 落地):endpoint paths, protocol constants and PURE helper functions,
- * with **no zod import** — so a zero-runtime-dependency client (e.g. `@sema-agent/sdk/registry`) can
- * import these at RUNTIME instead of value-copying them behind a same-source anchor test.
- *
- * ⚠️ 拆分纪律:这里只放**纯**件(常量/纯函数/字面量类型)。zod schema 留在 `api/auth.ts` /
- * `api/scopes.ts`(它们 re-export 本文件 ⇒ 既有导入面字节兼容,谁都不用改)。给本文件加东西前
- * 自问:它 import 了任何东西吗?——答案必须是 no(test/wire-purity 打包门盯着)。
- */
-/** The five auth endpoints, relative to the registry origin. */
-export declare const AUTH_V1_PATHS: {
-    readonly deviceCode: "/api/v1/auth/device/code";
-    readonly deviceToken: "/api/v1/auth/device/token";
-    readonly deviceApprove: "/api/v1/auth/device/approve";
-    readonly tokenRefresh: "/api/v1/auth/token/refresh";
-    readonly logout: "/api/v1/auth/logout";
-};
-/** The RFC 8628 grant_type the device token endpoint requires. */
-export declare const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
-/** Minimum seconds between token-endpoint polls (RFC 8628 `interval`); polling faster → `slow_down`. */
-export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
-/** Device-code handshake lifetime (seconds) — the user has 15 minutes to open /activate and approve. */
-export declare const DEVICE_CODE_TTL_SECONDS: number;
-/** Access-token (RS256 JWT) lifetime in seconds — 1h, re-minted via refresh. */
-export declare const ACCESS_TOKEN_TTL_SECONDS: number;
-/** Refresh-grant lifetime (seconds) — 30d SLIDING: every rotation opens a fresh 30d window. */
-export declare const REFRESH_TOKEN_TTL_SECONDS: number;
-/** Every error code the /api/v1/auth/* endpoints answer (HTTP 400 unless noted). */
-export declare const OAUTH_ERROR_CODES: readonly ["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"];
-export type OAuthErrorCode = (typeof OAUTH_ERROR_CODES)[number];
-/** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
- *  `denied` is contract-reserved for an explicit deny button (pairs with the `access_denied` poll error);
- *  the shipped M1 store carries pending|approved only — adding deny later is implementation, not schema. */
-export declare const DEVICE_AUTH_STATUSES: readonly ["pending", "approved", "denied"];
-export type DeviceAuthStatus = (typeof DEVICE_AUTH_STATUSES)[number];
-/**
- * Canonicalize a human-typed user code to the wire shape "XXXX-XXXX": uppercase, dashes/spaces optional.
- * null = not a plausible code (wrong length/charset after stripping separators). Same normalization the
- * server applies — run it client-side for instant feedback.
- */
-export declare function normalizeUserCode(input: unknown): string | null;
-/**
- * The RFC 8628 §3.5 poll-loop step: what interval to poll with next, and whether to keep going.
- * - authorization_pending → keep polling at the current interval
- * - slow_down             → keep polling, interval + 5s (the RFC-mandated increment)
- * - anything else         → stop (expired_token/access_denied = terminal; invalid_* = client bug)
- */
-export declare function nextPollInterval(currentIntervalSeconds: number, error: OAuthErrorCode): {
-    continue: boolean;
-    intervalSeconds: number;
-};
-export declare const SCOPES_V1_PATHS: {
-    /** GET (list) + POST (create). */
-    readonly scopes: "/api/v1/scopes";
-    /** POST — mint a new access token bound to another scope. */
-    readonly authScope: "/api/v1/auth/scope";
-};
-/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
-export declare const SCOPE_CLAIM = "scope";