@sema-agent/settings-schema 2.1.0 → 3.0.1

package/dist/conformance/corpus.d.ts

@@ -0,0 +1,73 @@
+import type { WarningProjection } from "./warnings.js";
+import type { LegName, RejectStage } from "./types.js";
+/** 本包的根目录 —— `src/conformance/*.ts` 与 `dist/conformance/*.js` 距根同深,两处求值同一个地方。 */
+export declare const PACKAGE_ROOT: string;
+/** 语料目录(默认 = 本包的 `conformance/`)。 */
+export declare const DEFAULT_CORPUS_DIR: string;
+/** 语料里一条腿的期望(磁盘形)。 */
+export type LegExpectationJson = {
+    derive: true;
+    localVersion?: number;
+} | {
+    applicable: false;
+    why: string;
+} | {
+    outcome: "effective";
+    effective: Record<string, unknown>;
+    warnings: WarningProjection[];
+    metadata: {
+        version?: number;
+        updatedAt: string;
+    };
+    why?: string;
+} | {
+    outcome: "rejected";
+    stage: RejectStage;
+    code?: string;
+    why?: string;
+};
+export interface CaseInput {
+    meta: {
+        version: number;
+        updatedAt: string;
+    };
+    domains: Record<string, unknown>;
+    /** 派生不出来的 wire 入参(坏信封:不是对象 / 缺 version / version 非有限数)。 */
+    wirePayload?: unknown;
+    /** 派生不出来的 `config.d/` 快照(空文件、非 JSON 文本、多余文件)。键 = 文件名。 */
+    localFiles?: Record<string, string>;
+}
+export interface CaseMeta {
+    /** **只写真交了的仓**:未交的仓留空位,不代写。 */
+    contributor: "server" | "web-admin" | "cli" | "client-core" | "test" | "core" | "contract";
+    /** 这条想打谁、为什么会读错。非空是对抗律的硬判据。 */
+    claim: string;
+    /** 语料里埋的秘密字面(告警面零命中门)。 */
+    secrets?: string[];
+    /** **historical 模式真跑**出来的「在哪些旧版上这条是红的」。空 = 护栏(也收,计数分开)。 */
+    firstRedOn: string[];
+    /** 人读补注(可空)。 */
+    note?: string;
+}
+export interface ConformanceCase {
+    id: string;
+    dir: string;
+    input: CaseInput;
+    meta: CaseMeta;
+    expected: Record<LegName, LegExpectationJson>;
+}
+export interface Corpus {
+    version: string;
+    /** 空文档集的 effective(冻结的 golden;非便携域的那一格由它供给,见 derive.ts T3)。 */
+    baseline: Record<string, unknown>;
+    cases: readonly ConformanceCase[];
+}
+/** 一个 case 目录 → 校验过的 case。 */
+export declare function loadCase(dir: string, id: string): Promise<ConformanceCase>;
+/** 整套语料。 */
+export declare function loadCorpus(corpusDir?: string): Promise<Corpus>;
+/** kit 自己所在那份包的身份(名 + 版号)—— 来源律拿它去认「适配器加载的是不是同一个包」。 */
+export declare function kitIdentity(): Promise<{
+    name: string;
+    version: string;
+}>;

package/dist/conformance/corpus.js

@@ -0,0 +1,99 @@
+/**
+ * 语料的**磁盘形**与加载器。语料随 npm 发(`package.json` 的 `files` 里登记 `conformance`),所以
+ * 消费方装上包就有整套金样,零复制。
+ *
+ * 一条 case = 一个目录 `conformance/cases/<id>/`:
+ *   · `input.json`    —— **真源是 `domains`**(各域原始文档);`wire` / `local-root` 两腿的入参由
+ *                        `derive.ts` 的变换表派生。个别腿的入参派生不出来(坏 wire 信封、空文件)时,
+ *                        用 `wirePayload` / `localFiles` 显式给。
+ *   · `expected.json` —— `domains` 腿的期望是**显式 golden**;另两腿默认写 `{"derive":true}`,由变换表
+ *                        派生;派生解释不了的腿写显式期望并带 `why`(那是明示声明,不是暗门)。
+ *   · `meta.json`     —— `contributor`(**只写真交了的仓**)、`claim`(这条想打谁、为什么会读错)、
+ *                        `secrets`(语料里埋的秘密字面,告警面零命中门用)、`firstRedOn`(**由 historical
+ *                        模式对旧版真跑填**,不许手写)。
+ *
+ * 加载器对语料本身 fail-loud:形不对就抛。一份被悄悄读错的语料,比没有语料更坏。
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { REJECT_STAGES } from "./types.js";
+/** 本包的根目录 —— `src/conformance/*.ts` 与 `dist/conformance/*.js` 距根同深,两处求值同一个地方。 */
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** 语料目录(默认 = 本包的 `conformance/`)。 */
+export const DEFAULT_CORPUS_DIR = join(PACKAGE_ROOT, "conformance");
+const readJson = async (p) => JSON.parse(await readFile(p, "utf8"));
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+function requireRecord(v, where) {
+    if (!isRecord(v))
+        throw new Error(`conformance corpus: ${where} must be a JSON object`);
+    return v;
+}
+function checkLegExpectation(v, where) {
+    const r = requireRecord(v, where);
+    if (r.derive === true) {
+        if (r.localVersion !== undefined && typeof r.localVersion !== "number")
+            throw new Error(`conformance corpus: ${where}.localVersion must be a number`);
+        return r;
+    }
+    if (r.applicable === false) {
+        if (typeof r.why !== "string" || r.why.length === 0)
+            throw new Error(`conformance corpus: ${where} declares applicable:false without a \`why\` — a leg that does not apply must say why`);
+        return r;
+    }
+    if (r.outcome === "effective") {
+        requireRecord(r.effective, `${where}.effective`);
+        if (!Array.isArray(r.warnings))
+            throw new Error(`conformance corpus: ${where}.warnings must be an array`);
+        const meta = requireRecord(r.metadata, `${where}.metadata`);
+        if (typeof meta.updatedAt !== "string")
+            throw new Error(`conformance corpus: ${where}.metadata.updatedAt must be a string`);
+        return r;
+    }
+    if (r.outcome === "rejected") {
+        if (!REJECT_STAGES.includes(r.stage))
+            throw new Error(`conformance corpus: ${where}.stage must be one of ${REJECT_STAGES.join("|")}`);
+        return r;
+    }
+    throw new Error(`conformance corpus: ${where} is none of {derive:true} | {applicable:false,why} | {outcome:"effective"} | {outcome:"rejected"}`);
+}
+/** 一个 case 目录 → 校验过的 case。 */
+export async function loadCase(dir, id) {
+    const [inputRaw, metaRaw, expectedRaw] = await Promise.all([readJson(join(dir, "input.json")), readJson(join(dir, "meta.json")), readJson(join(dir, "expected.json"))]);
+    const input = requireRecord(inputRaw, `${id}/input.json`);
+    const meta = requireRecord(metaRaw, `${id}/meta.json`);
+    const expected = requireRecord(expectedRaw, `${id}/expected.json`);
+    const inputMeta = requireRecord(input.meta, `${id}/input.json#meta`);
+    if (typeof inputMeta.version !== "number" || typeof inputMeta.updatedAt !== "string")
+        throw new Error(`conformance corpus: ${id}/input.json#meta needs {version:number, updatedAt:string}`);
+    requireRecord(input.domains, `${id}/input.json#domains`);
+    if (typeof meta.claim !== "string" || meta.claim.trim().length === 0)
+        throw new Error(`conformance corpus: ${id}/meta.json#claim is empty — 每条语料必须写它想打谁`);
+    if (!Array.isArray(meta.firstRedOn))
+        throw new Error(`conformance corpus: ${id}/meta.json#firstRedOn must be an array`);
+    const legs = {};
+    for (const leg of ["domains", "wire", "localRoot"]) {
+        if (expected[leg] === undefined)
+            throw new Error(`conformance corpus: ${id}/expected.json has no \`${leg}\` — 每腿都要表态(派生 / 显式 / 不适用)`);
+        legs[leg] = checkLegExpectation(expected[leg], `${id}/expected.json#${leg}`);
+    }
+    if ("derive" in legs.domains)
+        throw new Error(`conformance corpus: ${id}/expected.json#domains cannot be derived — domains 腿是真源`);
+    return { id, dir, input: input, meta: meta, expected: legs };
+}
+/** 整套语料。 */
+export async function loadCorpus(corpusDir = DEFAULT_CORPUS_DIR) {
+    const version = (await readFile(join(corpusDir, "VERSION"), "utf8")).trim();
+    const baseline = requireRecord(await readJson(join(corpusDir, "baseline.json")), "conformance/baseline.json");
+    const casesDir = join(corpusDir, "cases");
+    const ids = (await readdir(casesDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    const cases = await Promise.all(ids.map((id) => loadCase(join(casesDir, id), id)));
+    return { version, baseline, cases };
+}
+/** kit 自己所在那份包的身份(名 + 版号)—— 来源律拿它去认「适配器加载的是不是同一个包」。 */
+export async function kitIdentity() {
+    const pkg = requireRecord(await readJson(join(PACKAGE_ROOT, "package.json")), "package.json");
+    if (typeof pkg.name !== "string" || typeof pkg.version !== "string")
+        throw new Error("conformance: package.json has no name/version");
+    return { name: pkg.name, version: pkg.version };
+}

package/dist/conformance/derive.d.ts

@@ -0,0 +1,48 @@
+import { type DomainName } from "../types.js";
+import type { WarningProjection } from "./warnings.js";
+import type { LegName, LegInput, RejectStage } from "./types.js";
+/** 一条登记在案的表示差异。 */
+export interface DerivationTransform {
+    id: string;
+    legs: readonly LegName[];
+    what: string;
+}
+/** 变换表(本文件头注的机器形;`docs/CONFORMANCE.md` 与 `test/conformance-coverage.test.ts` 都读它)。 */
+export declare const DERIVATION_TRANSFORMS: readonly DerivationTransform[];
+/** 非便携域 —— 由 {@link PORTABLE_DOMAINS} 派生,零手抄。 */
+export declare const NON_PORTABLE_DOMAINS: readonly DomainName[];
+/** 一份 `domains` 文档集里,**不是域名**的那些顶层键(T4 的触发面)。 */
+export declare const foreignKeysOf: (docs: Readonly<Record<string, unknown>>) => string[];
+/** T2 的**入参**半场:域形的 skills 文档 → wire 形的 manifest 文档。结构变换,不解析 —— 坏形原样传下去,
+ *  让 wire 腿自己的判据去裁(否则语料就没法喂一份坏 manifest 了)。 */
+export declare function toManifestDoc(doc: unknown): unknown;
+/** `domains` 真源 → `wire` 腿入参(T1 缺席进缺席出 + T2 表示换 + T4 未知键照原样带上)。 */
+export declare function deriveWireInput(docs: Readonly<Record<string, unknown>>, version: number, updatedAt: string): LegInput;
+/** `domains` 真源 → `local-root` 腿入参(每个顶层键一个 `config.d/<键>.json`,含非域名的那些 —— T3/T4
+ *  的告警正是靠它们在目录里在场才会响)。 */
+export declare function deriveLocalInput(docs: Readonly<Record<string, unknown>>, mtime: string): LegInput;
+/** 一条腿的期望(派生结果与语料显式期望共用同一形)。 */
+export type LegExpectation = {
+    outcome: "effective";
+    effective: Record<string, unknown>;
+    warnings: readonly WarningProjection[];
+    metadata: {
+        version?: number;
+        updatedAt: string;
+    };
+} | {
+    outcome: "rejected";
+    stage: RejectStage;
+    code?: string;
+};
+/** T1 + T2 + T4:`domains` 期望 → `wire` 期望。 */
+export declare function deriveWireExpectation(source: Extract<LegExpectation, {
+    outcome: "effective";
+}>, docs: Readonly<Record<string, unknown>>): LegExpectation;
+/** 纪元时刻 —— 一个 `config.d/` 里没有任何**便携**域文件时 `updatedAt` 的取值(`#maxMtimeIso` 只 stat 便携域)。 */
+export declare const EPOCH_ISO: string;
+/** T3 + T4 + T5:`domains` 期望 → `local-root` 期望。`baseline` = 空文档集的 effective(语料里冻结的
+ *  `conformance/baseline.json`),非便携域取它的那一格 —— 不现算,免得 schema 默认一改 golden 就跟着动。 */
+export declare function deriveLocalExpectation(source: Extract<LegExpectation, {
+    outcome: "effective";
+}>, docs: Readonly<Record<string, unknown>>, baseline: Readonly<Record<string, unknown>>, localVersion: number | undefined): LegExpectation;

package/dist/conformance/derive.js

@@ -0,0 +1,136 @@
+/**
+ * **三腿等价先定义再比**:语料以 `domains`(各域原始文档)为真源,`wire` 与 `local-root` 两腿的**入参**
+ * 与**期望**都由本文件派生 —— 派生规则就是三条腿之间那几处**表示差异**的完整登记表。
+ *
+ * 为什么派生期望而不是每腿各写一份 golden:三份手写 golden 之间的关系是**隐含**的,谁也说不清某一处
+ * 不同是「设计如此」还是「某一腿读错了」。派生把那层关系变成代码:凡不能由登记的变换解释的差异,一定
+ * 显示成 diff。于是「有没有第四条变换没登记」这件事不再靠人回忆 —— 没登记的那条会自己红出来。
+ *
+ * 变换表(每条写明:动了什么、影响哪几条腿、出处):
+ *  · **T1 prompts 物化**(wire):`buildEffective` 恒物化 `prompts: {bindings:[]}`;wire 腿按**在场性**
+ *    verbatim 挂回(`readEffectiveWire` 的 `"prompts" in r` 判据)—— 缺席进缺席出,且在场时是**未解析的
+ *    原文档**。
+ *  · **T2 skills 表示**(wire):域形带 `content`,wire 形带 `contentHash`(manifest)。判据 schema 随表示走。
+ *  · **T3 非便携域**(local-root):`config.d/` 只读 {@link PORTABLE_DOMAINS};其余域的文件在场则报
+ *    `unread-config-file{why:"non-portable-domain"}`,域本身取 schema 默认。**由 `PORTABLE_DOMAINS` 派生,
+ *    不手抄域名** —— 设计稿只点了 `hosts` 一个实例,类是「非便携域」。
+ *  · **T4 未知顶层键**(wire + local-root):wire 是 open-world,不认识的顶层键**逐字承运**;`domains` 腿
+ *    只按域名取文档,多出来的键根本不会被问到(无声);local-root 报
+ *    `unread-config-file{why:"not-a-domain"}`。三腿三样 —— 这条是本车对着真读数补登记的第四条。
+ *  · **T5 文件层先判**(local-root):`config.d/<域>.json` 的内容必须是 JSON **对象**(空文件 / `null` /
+ *    数组 / 标量一律 throw,fail-closed),这一层在域解析**之前**,`domains` 腿没有它。
+ *  · **T6 文件名分类**(local-root):`config.d/` 里的文件分三类 —— 域文件(读)、
+ *    {@link NON_DOMAIN_CONFIG_FILES}(`remote-exec.json`:**有自己的读取与校验路径**,既不报未知文件、
+ *    坏形时也由它自己那条腿拒)、隐藏文件 / 非 `.json`(扫描忽略,不报)。只有剩下的才是
+ *    `unread-config-file{not-a-domain}`。这条是本车在对抗复审后补登记的第六条 —— 把 `remote-exec.json`
+ *    当普通未知文件报,门会对着一份完全合法的部署喊错。
+ *
+ * 语料可以对某一腿写**显式期望**(带 `why`)来覆盖派生 —— 那是「这条 case 的这条腿不由变换解释」的
+ * 明示声明,不是一条暗门。
+ */
+import { NON_DOMAIN_CONFIG_FILES, PORTABLE_DOMAINS } from "../file-store.js";
+import { skillContentHash } from "../skills-manifest.js";
+import { DOMAINS, isDomainName } from "../types.js";
+/** 变换表(本文件头注的机器形;`docs/CONFORMANCE.md` 与 `test/conformance-coverage.test.ts` 都读它)。 */
+export const DERIVATION_TRANSFORMS = [
+    { id: "T1-prompts-materialisation", legs: ["wire"], what: "buildEffective 恒物化 prompts:{bindings:[]};wire 按在场性 verbatim 挂回(缺席进缺席出)" },
+    { id: "T2-skills-representation", legs: ["wire"], what: "域形 content ↔ wire 形 contentHash(manifest),判据 schema 随表示走" },
+    { id: "T3-non-portable-domains", legs: ["localRoot"], what: "config.d/ 只读 PORTABLE_DOMAINS;其余域取默认 + unread-config-file{non-portable-domain}" },
+    { id: "T4-unknown-top-level-key", legs: ["wire", "localRoot"], what: "wire open-world 逐字承运;domains 腿按域名取文档故无声;local 报 unread-config-file{not-a-domain}" },
+    { id: "T5-file-layer-first", legs: ["localRoot"], what: "config.d/<域>.json 必须是 JSON 对象(空/null/数组/标量 throw),这一层在域解析之前" },
+    { id: "T6-file-name-classification", legs: ["localRoot"], what: "config.d/ 的文件分三类:域文件 / NON_DOMAIN_CONFIG_FILES(remote-exec.json 自带读取与校验路径)/ 隐藏文件与非 .json(忽略);只有剩下的才报 not-a-domain" },
+];
+/** 非便携域 —— 由 {@link PORTABLE_DOMAINS} 派生,零手抄。 */
+export const NON_PORTABLE_DOMAINS = DOMAINS.filter((d) => !PORTABLE_DOMAINS.includes(d));
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** 一份 `domains` 文档集里,**不是域名**的那些顶层键(T4 的触发面)。 */
+export const foreignKeysOf = (docs) => Object.keys(docs).filter((k) => !isDomainName(k));
+/** T2 的**入参**半场:域形的 skills 文档 → wire 形的 manifest 文档。结构变换,不解析 —— 坏形原样传下去,
+ *  让 wire 腿自己的判据去裁(否则语料就没法喂一份坏 manifest 了)。 */
+export function toManifestDoc(doc) {
+    if (!isPlainObject(doc) || !Array.isArray(doc.skills))
+        return doc;
+    return {
+        ...doc,
+        skills: doc.skills.map((entry) => {
+            if (!isPlainObject(entry) || typeof entry.content !== "string")
+                return entry;
+            const { content, ...rest } = entry;
+            return { ...rest, contentHash: skillContentHash(content) };
+        }),
+    };
+}
+/** `domains` 真源 → `wire` 腿入参(T1 缺席进缺席出 + T2 表示换 + T4 未知键照原样带上)。 */
+export function deriveWireInput(docs, version, updatedAt) {
+    // fromEntries(不是逐键赋值):语料里的顶层键可以叫 `__proto__`(S-332 的那一类),逐键赋值会把它
+    // 变成一次原型改写,载荷里就再也没有这个键 —— 整条 case 于是测了个寂寞。
+    const payload = Object.fromEntries([
+        ["version", version],
+        ["updatedAt", updatedAt],
+        ...Object.entries(docs).map(([k, v]) => [k, k === "skills" ? toManifestDoc(v) : v]),
+    ]);
+    return { leg: "wire", payload };
+}
+/** `domains` 真源 → `local-root` 腿入参(每个顶层键一个 `config.d/<键>.json`,含非域名的那些 —— T3/T4
+ *  的告警正是靠它们在目录里在场才会响)。 */
+export function deriveLocalInput(docs, mtime) {
+    const files = {};
+    for (const [k, v] of Object.entries(docs))
+        files[`${k}.json`] = JSON.stringify(v, null, 2) + "\n";
+    return { leg: "localRoot", files, mtime };
+}
+const clone = (v) => structuredClone(v);
+/** T1 + T2 + T4:`domains` 期望 → `wire` 期望。 */
+export function deriveWireExpectation(source, docs) {
+    const base = clone(source.effective);
+    // T1:缺席进缺席出;在场则是**未解析的原文档**(wire 腿从不 parse prompts)。
+    // T2:域形条目的 content → contentHash(manifest 的条目 schema = 域条目 omit content + contentHash)。
+    // T4:open-world 顶层键逐字承运 —— 用 fromEntries 而不是逐键赋值,否则一个叫 `__proto__` 的顶层键
+    // 会变成一次原型改写(期望侧与实际侧被同样吃掉 = 比对器对这一类全盲,S-332 同族)。
+    const effective = Object.fromEntries([
+        ...Object.entries(base).filter(([k]) => k !== "prompts" && k !== "skills"),
+        ["skills", toManifestDoc(base.skills)],
+        ...(Object.prototype.hasOwnProperty.call(docs, "prompts") ? [["prompts", clone(docs.prompts)]] : []),
+        ...foreignKeysOf(docs).map((k) => [k, clone(docs[k])]),
+    ]);
+    const warnings = source.warnings.filter((w) => {
+        if ("domain" in w && w.domain === "prompts")
+            return false; // T1:wire 腿不解析 prompts ⇒ 没有它的告警
+        if ("domain" in w && w.domain === "skills" && (w.kind === "unknown-keys-dropped" || w.kind === "unknown-keys-carried"))
+            return false; // T2:manifest 不走剥键扫描
+        return true;
+    });
+    return { outcome: "effective", effective, warnings, metadata: { ...source.metadata } };
+}
+/** 纪元时刻 —— 一个 `config.d/` 里没有任何**便携**域文件时 `updatedAt` 的取值(`#maxMtimeIso` 只 stat 便携域)。 */
+export const EPOCH_ISO = new Date(0).toISOString();
+/** T3 + T4 + T5:`domains` 期望 → `local-root` 期望。`baseline` = 空文档集的 effective(语料里冻结的
+ *  `conformance/baseline.json`),非便携域取它的那一格 —— 不现算,免得 schema 默认一改 golden 就跟着动。 */
+export function deriveLocalExpectation(source, docs, baseline, localVersion) {
+    // T5:文件层先判 —— 任何一个**便携**域的文档不是 JSON 对象 ⇒ 整条腿在解析层被拒。
+    const badFile = PORTABLE_DOMAINS.find((d) => Object.prototype.hasOwnProperty.call(docs, d) && !isPlainObject(docs[d]));
+    if (badFile !== undefined)
+        return { outcome: "rejected", stage: "parse" };
+    const effective = clone(source.effective);
+    for (const d of NON_PORTABLE_DOMAINS)
+        effective[d] = clone(baseline[d]);
+    const warnings = source.warnings.filter((w) => !("domain" in w && w.domain !== undefined && NON_PORTABLE_DOMAINS.includes(w.domain)));
+    for (const d of NON_PORTABLE_DOMAINS) {
+        if (Object.prototype.hasOwnProperty.call(docs, d))
+            warnings.push({ kind: "unread-config-file", file: `${d}.json`, domain: d, why: "non-portable-domain" });
+    }
+    // T6:只有**既不是专用文件、也不是隐藏文件**的那些才报 not-a-domain(分类表从 file-store 派生,零手抄)。
+    for (const k of foreignKeysOf(docs)) {
+        const file = `${k}.json`;
+        if (NON_DOMAIN_CONFIG_FILES.has(file) || file.startsWith("."))
+            continue;
+        warnings.push({ kind: "unread-config-file", file, why: "not-a-domain" });
+    }
+    const anyPortable = PORTABLE_DOMAINS.some((d) => Object.prototype.hasOwnProperty.call(docs, d));
+    return {
+        outcome: "effective",
+        effective,
+        warnings,
+        metadata: { updatedAt: anyPortable ? source.metadata.updatedAt : EPOCH_ISO, ...(localVersion === undefined ? {} : { version: localVersion }) },
+    };
+}

package/dist/conformance/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@sema-agent/settings-schema/conformance` —— 跨仓一致性门的 kit。
+ *
+ * 一句话:契约仓自带**金样语料 + 比对器**;每个消费方把**自己的生产读腿**塞给 kit 跑一遍 ⇒ 同一份
+ * settings 语料在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
+ *
+ * 三步接线(消费方侧):
+ *   1. 造一个 {@link ConformanceAdapter}:`provenance` = 你**实际加载到**的那份契约包(package.json 路径、
+ *      版号、完整性串);`legs` = 你自己的生产读腿,每条带 `entry{module,export}`(生产入口的绝对路径)。
+ *   2. `const report = await runConformance(adapter, { mode: "release" })`。
+ *   3. 断言 `report.ok`;不绿就读 `report.violations` 与每格的 `diff`(effective 的 JSON patch、告警多重集差、
+ *      元数据差三面分开)。
+ *
+ * 语料贡献形、四律、报告形见 `docs/CONFORMANCE.md`。Node-only(语料在磁盘上,local-root 腿要落盘)。
+ */
+export { runConformance, materializeLocalRoot, resolveLegExpectation } from "./run.js";
+export { createContractAdapter, type ContractAdapterOptions, type ContractModule } from "./contract-adapter.js";
+export { loadCorpus, loadCase, kitIdentity, DEFAULT_CORPUS_DIR, PACKAGE_ROOT, type Corpus, type ConformanceCase, type CaseInput, type CaseMeta, type LegExpectationJson } from "./corpus.js";
+export { DERIVATION_TRANSFORMS, NON_PORTABLE_DOMAINS, EPOCH_ISO, deriveWireInput, deriveLocalInput, deriveWireExpectation, deriveLocalExpectation, foreignKeysOf, toManifestDoc, type DerivationTransform, type LegExpectation, } from "./derive.js";
+export { canonicalize, deepEqual, diffJson, stableKey, type JsonPatchOp } from "./canonical.js";
+export { WARNING_KINDS, projectWarning, normalizeProjection, projectionKey, projectionValue, diffWarningMultiset, findSecretLeaks, type WarningKind, type WarningProjection, } from "./warnings.js";
+export { LEG_NAMES, REJECT_STAGES, type ConformanceAdapter, type ConformanceLeg, type ConformanceMode, type ConformanceNormalizer, type ConformanceOptions, type ConformanceProvenance, type ConformanceReport, type ConformanceResult, type ConformanceStatus, type KnownDivergence, type OutcomeDivergence, type PathDivergence, type LedgerRow, type LegEntry, type LegInput, type LegName, type LegOutcome, type RejectStage, } from "./types.js";

package/dist/conformance/index.js

@@ -0,0 +1,22 @@
+/**
+ * `@sema-agent/settings-schema/conformance` —— 跨仓一致性门的 kit。
+ *
+ * 一句话:契约仓自带**金样语料 + 比对器**;每个消费方把**自己的生产读腿**塞给 kit 跑一遍 ⇒ 同一份
+ * settings 语料在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
+ *
+ * 三步接线(消费方侧):
+ *   1. 造一个 {@link ConformanceAdapter}:`provenance` = 你**实际加载到**的那份契约包(package.json 路径、
+ *      版号、完整性串);`legs` = 你自己的生产读腿,每条带 `entry{module,export}`(生产入口的绝对路径)。
+ *   2. `const report = await runConformance(adapter, { mode: "release" })`。
+ *   3. 断言 `report.ok`;不绿就读 `report.violations` 与每格的 `diff`(effective 的 JSON patch、告警多重集差、
+ *      元数据差三面分开)。
+ *
+ * 语料贡献形、四律、报告形见 `docs/CONFORMANCE.md`。Node-only(语料在磁盘上,local-root 腿要落盘)。
+ */
+export { runConformance, materializeLocalRoot, resolveLegExpectation } from "./run.js";
+export { createContractAdapter } from "./contract-adapter.js";
+export { loadCorpus, loadCase, kitIdentity, DEFAULT_CORPUS_DIR, PACKAGE_ROOT } from "./corpus.js";
+export { DERIVATION_TRANSFORMS, NON_PORTABLE_DOMAINS, EPOCH_ISO, deriveWireInput, deriveLocalInput, deriveWireExpectation, deriveLocalExpectation, foreignKeysOf, toManifestDoc, } from "./derive.js";
+export { canonicalize, deepEqual, diffJson, stableKey } from "./canonical.js";
+export { WARNING_KINDS, projectWarning, normalizeProjection, projectionKey, projectionValue, diffWarningMultiset, findSecretLeaks, } from "./warnings.js";
+export { LEG_NAMES, REJECT_STAGES, } from "./types.js";

package/dist/conformance/run.d.ts

@@ -0,0 +1,27 @@
+import { type LegExpectation } from "./derive.js";
+import { type ConformanceCase } from "./corpus.js";
+import { type ConformanceAdapter, type ConformanceOptions, type ConformanceReport, type LegName } from "./types.js";
+/**
+ * 把一份 `config.d/` 快照落成真目录 —— **kit 单铸**,消费方零复述(每个消费方各写一遍落盘逻辑,
+ * mtime 怎么设、目录怎么建就会各不相同,而 `updatedAt` 正是按 mtime 算的)。
+ *
+ * 返回 `root` 与 `cleanup`;所有文件的 mtime 统一设成 `mtime`,于是 `updatedAt` 对同一份快照恒定。
+ */
+export declare function materializeLocalRoot(files: Readonly<Record<string, string>>, mtime: string): Promise<{
+    root: string;
+    cleanup: () => Promise<void>;
+}>;
+/** 磁盘形的腿期望 → 运行期形(`derive:true` 在这里真的派生)。`null` = 语料声明本腿不适用。
+ *
+ *  **导出**给覆盖律用:覆盖矩阵要数的是「这条腿最终被期望成什么」,那必须是**驱动真正用的那一份**期望
+ *  ——测试自己再算一遍派生,就是第二份真源,而两份真源的分歧正是本门要抓的病。 */
+export declare function resolveLegExpectation(c: ConformanceCase, leg: LegName, baseline: Readonly<Record<string, unknown>>): LegExpectation | null;
+/**
+ * 跑一遍门。
+ *
+ * `release`:版本三方对齐(适配器加载到的包 == 语料 VERSION == kit 所在包)+ 每条登记的腿都指向一个
+ * **真存在、且不在契约包 node_modules 之下**的生产入口 + 禁 `only` + 至少登记一条腿 + **登记的腿必须跑**
+ * (未登记的腿只记 `skipped: no adapter`,不算违例)+ 账本条目的形 + 零陈腐账本条目。
+ * `historical`:对旧版包跑,只记行为 diff;归一器可在场且必须自陈有损。
+ */
+export declare function runConformance(adapter: ConformanceAdapter, opts: ConformanceOptions): Promise<ConformanceReport>;