@sema-agent/settings-schema 2.1.0 → 3.0.1

package/dist/conformance/run.js

@@ -0,0 +1,424 @@
+/**
+ * 驱动:一套语料 × 一个适配器的 N 条读腿 → 一份报告。
+ *
+ * 四律在这里落地(缺一不算「门」):
+ *  · **对抗律**——语料自带 `claim` / `firstRedOn`,由 `test/conformance-corpus.test.ts` 计数(本文件只保证
+ *    它们被读进来、坏形立刻抛)。
+ *  · **变异律**——本驱动是被变异的那一面:契约任一铸点被改坏,语料必红(`test/conformance-mutation.test.ts`)。
+ *  · **覆盖律**——报告逐 case × 腿出结局,覆盖矩阵按它计数(`test/conformance-coverage.test.ts`)。
+ *  · **来源律**——release 模式核 provenance 与每条腿的生产入口({@link releaseViolations})。
+ *
+ * 比对分三面,刻意不混:**effective**(剥掉元数据后结构化深相等)、**告警多重集**、**元数据**
+ * (`version`/`updatedAt` 由 harness 注入或由腿自己算,独立断言 —— 不让 canonical 把它盖过去)。
+ */
+import { mkdtemp, mkdir, readFile, realpath, rm, stat, writeFile, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+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 { 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 算的)。
+ *
+ * 返回 `root` 与 `cleanup`;所有文件的 mtime 统一设成 `mtime`,于是 `updatedAt` 对同一份快照恒定。
+ */
+export async function materializeLocalRoot(files, mtime) {
+    // 闸**先于**任何 fs 动作:一个坏名字不许留下半个临时根(「建了再清」比这多一条「清到一半又抛」的路)。
+    for (const name of Object.keys(files))
+        assertBareFileName(name);
+    const root = await mkdtemp(join(tmpdir(), "settings-conformance-"));
+    const dir = join(root, "config.d");
+    await mkdir(dir, { recursive: true });
+    const when = new Date(mtime);
+    try {
+        for (const [name, text] of Object.entries(files)) {
+            const p = join(dir, name);
+            // 上面那条单段律要保证的**就是**这条包含律。它是承重面上的断言,不是可跳过的装饰:真要有一天
+            // 单段律被改松,这里要 loud(清掉已建的临时根再抛),不许静默写出去。
+            if (!resolve(p).startsWith(resolve(dir) + sep)) {
+                throw new Error(`conformance: local-root file \`${name}\` resolves outside the case root — 语料不许写出自己的临时根`);
+            }
+            await writeFile(p, text, "utf8");
+            await utimes(p, when, when);
+        }
+    }
+    catch (e) {
+        await rm(root, { recursive: true, force: true });
+        throw e;
+    }
+    return { root, cleanup: () => rm(root, { recursive: true, force: true }) };
+}
+/**
+ * 语料落盘的**文件名闸**。语料是仓外贡献面(每条 case 的 `input.json` 里的 `localFiles` 键,以及
+ * {@link deriveLocalInput} 从 **domains 顶层键**派生的 `<域名>.json`),所以这里的名字不是自己写的常量:
+ * 一个 `"../../x.json"` 会顺着 `join(dir, name)` 写到临时根之外、覆盖宿主文件,而 `cleanup()` 只删临时根,
+ * 删不到跑出去的那一份。闸设在**落盘这个单铸点**上 —— 派生路、显式语料路、消费方自己调 kit 的路共一道闸,
+ * 零特判、零复述。错形沿用 kit 的 harness 错形(`conformance: …` 的 `Error`,经适配器腿记成 `harness-error`)。
+ */
+function assertBareFileName(name) {
+    const bad = name.length === 0 ? "is empty"
+        : name === "." || name === ".." ? "is a directory reference"
+            : name.includes("\0") ? "contains a NUL byte"
+                : name.includes("/") || name.includes("\\") ? "contains a path separator"
+                    : basename(name) !== name ? "is not a bare file name"
+                        : undefined;
+    if (bad !== undefined) {
+        throw new Error(`conformance: local-root file name ${JSON.stringify(name)} ${bad} — 语料给的文件名必须是**单段文件名**(single path segment),落盘处不做路径拼接`);
+    }
+}
+/** 一条腿的入参:语料给了显式的就用显式的,否则按变换表从 `domains` 派生。 */
+function legInput(c, leg) {
+    const { version, updatedAt } = c.input.meta;
+    switch (leg) {
+        case "domains":
+            return { leg, docs: c.input.domains, version, updatedAt };
+        case "wire":
+            return c.input.wirePayload === undefined ? deriveWireInput(c.input.domains, version, updatedAt) : { leg, payload: c.input.wirePayload };
+        case "localRoot":
+            return c.input.localFiles === undefined ? deriveLocalInput(c.input.domains, updatedAt) : { leg, files: c.input.localFiles, mtime: updatedAt };
+        default: {
+            const unhandled = leg;
+            throw new Error(`conformance: unknown leg ${String(unhandled)}`);
+        }
+    }
+}
+/** 磁盘形的腿期望 → 运行期形(`derive:true` 在这里真的派生)。`null` = 语料声明本腿不适用。
+ *
+ *  **导出**给覆盖律用:覆盖矩阵要数的是「这条腿最终被期望成什么」,那必须是**驱动真正用的那一份**期望
+ *  ——测试自己再算一遍派生,就是第二份真源,而两份真源的分歧正是本门要抓的病。 */
+export function resolveLegExpectation(c, leg, baseline) {
+    const spec = c.expected[leg];
+    if ("applicable" in spec)
+        return null;
+    if ("derive" in spec) {
+        const source = c.expected.domains;
+        if (!("outcome" in source) || source.outcome !== "effective") {
+            throw new Error(`conformance corpus: ${c.id}/expected.json#${leg} asks to derive from a domains expectation that is not \`effective\` — 拒绝态不派生,那条腿要写显式期望`);
+        }
+        const from = { outcome: "effective", effective: source.effective, warnings: source.warnings, metadata: source.metadata };
+        if (leg === "wire") {
+            // **派生不许替被测 helper 同时造输入与期望**(codex R1 [high] 复现):skills 是五条变换里唯一一条
+            // **算出一个新值**的(content → contentHash),而入参与期望都走同一只 `toManifestDoc` —— 把哈希算错
+            // 也会两侧同样算错,45 条 wire 语料照样全绿。于是这里 fail-loud:凡该变换**不是恒等**的 case,
+            // wire 腿必须写显式期望(金样入库即冻结,哈希一改就红)。其余四条变换只搬/只删,不铸新值,照常派生。
+            if (stableKey(toManifestDoc(source.effective.skills)) !== stableKey(source.effective.skills)) {
+                throw new Error(`conformance corpus: ${c.id}/expected.json#wire cannot be derived — 这条 case 的 skills 表示变换会**算出新值**(contentHash),` +
+                    `派生会让入参与期望同时错;请给 wire 腿写显式期望并写明 why(跑 \`npm run conformance:bless\` 填金样)`);
+            }
+            return deriveWireExpectation(from, c.input.domains);
+        }
+        if (leg === "localRoot")
+            return deriveLocalExpectation(from, c.input.domains, baseline, spec.localVersion);
+        throw new Error(`conformance corpus: ${c.id}/expected.json#${leg} cannot be derived`);
+    }
+    if (spec.outcome === "effective")
+        return { outcome: "effective", effective: spec.effective, warnings: spec.warnings, metadata: spec.metadata };
+    return { outcome: "rejected", stage: spec.stage, ...(spec.code === undefined ? {} : { code: spec.code }) };
+}
+/** effective 里的元数据两键(独立断言,不进结构比对)。 */
+const METADATA_KEYS = ["version", "updatedAt"];
+function splitMetadata(effective) {
+    if (effective === null || typeof effective !== "object" || Array.isArray(effective))
+        return { body: effective };
+    const src = effective;
+    // fromEntries(不是逐键赋值):`__proto__` 作自有键时逐键赋值会走原型 setter,把它从比对面上抹掉。
+    const body = Object.fromEntries(Object.entries(src).filter(([k]) => !METADATA_KEYS.includes(k)));
+    return { body, version: src.version, updatedAt: src.updatedAt };
+}
+/**
+ * 坐标 `patchPath` 是否落在登记的 `pathPrefix` **这棵子树**里 —— 判据是 **JSON Pointer 段前缀**,
+ * 不是裸串前缀:`/limits/infraCostRates` 盖 `/limits/infraCostRates` 与 `/limits/infraCostRates/**`,
+ * **不**盖 `/limits/infraCostRatesInjected`;`/models/1` 不盖 `/models/10`。裸 `startsWith` 会让一条登记
+ * 悄悄豁免没登记的相邻坐标,而账本是**逐坐标**白名单(棘轮),那就等于绕开它自己那条律。
+ * `prefix = ""` 表示根(release 模式另有大包大揽判据挡着,这里不特判)。
+ */
+const underPointerPrefix = (patchPath, prefix) => patchPath === prefix || patchPath.startsWith(`${prefix}/`);
+/**
+ * 一条 effective diff 的坐标落在账本哪一条上 —— 命中返回条目下标,没命中 `undefined`。
+ * 三道判据缺一不可:腿相同 ∧(`cases` 缺席或含该 case)∧ 坐标在 `pathPrefix` 那棵子树里。
+ */
+function ledgerIndexFor(ledger, caseId, leg, patchPath) {
+    for (let i = 0; i < ledger.length; i++) {
+        const e = ledger[i];
+        if (e.outcome !== undefined)
+            continue; // 结局形登记不管坐标(见 ledgerIndexForOutcome)
+        if (e.leg !== leg)
+            continue;
+        if (e.cases !== undefined && !e.cases.includes(caseId))
+            continue;
+        if (!underPointerPrefix(patchPath, e.pathPrefix))
+            continue;
+        return i;
+    }
+    return undefined;
+}
+/**
+ * 一条**结局形**分歧落在账本哪一条上。四道判据全等,一道都不放宽:腿 ∧ case 在点名名单里 ∧
+ * 金样期望的结局 ∧ 消费方实际的结局。没命中 `undefined`。
+ */
+function ledgerIndexForOutcome(ledger, caseId, leg, shape) {
+    for (let i = 0; i < ledger.length; i++) {
+        const o = ledger[i].outcome;
+        if (o === undefined)
+            continue;
+        // 形不合法的登记(`cases` 缺席/空 —— 违例已单记)绝不因此**扩大**覆盖:它谁都不命中,fail-closed。
+        if (o.leg !== leg || !Array.isArray(o.cases) || !o.cases.includes(caseId))
+            continue;
+        if (o.expected !== shape.expected || o.actual !== shape.actual)
+            continue;
+        return i;
+    }
+    return undefined;
+}
+/** 结局形不一致的一格:附上**结构化**的 `diff.outcome`,命中账本就记 `diff-ledgered`。 */
+function outcomeVerdict(base, detail, shape, ledger, hits) {
+    const diff = { effective: [], warnings: { missing: [], extra: [] }, metadata: [], outcome: shape };
+    const i = ledgerIndexForOutcome(ledger, base.caseId, base.leg, shape);
+    if (i === undefined)
+        return { ...base, status: "diff", detail, diff };
+    hits[i] += 1;
+    return { ...base, status: "diff-ledgered", detail: `${detail} — 落在适配器的已知分歧账本里(结局形,债)`, diff, ledgerRefs: [ledger[i].ref] };
+}
+/** 一格的比对。返回 status + detail(+ diff)。`hits` 是账本逐条的命中计数器 —— 由本函数就地累加
+ *  (比对与计数走同一遍遍历;再扫一遍就是第二份判定,两份判定的分歧正是本门要抓的那类病)。 */
+function judge(c, leg, expected, actual, normalizer, ledger, hits) {
+    const base = { caseId: c.id, leg };
+    if (expected.outcome === "rejected") {
+        if (actual.outcome !== "rejected") {
+            return outcomeVerdict(base, `expected a rejection at stage \`${expected.stage}\`, got an effective config`, { expected: "rejected", actual: "effective" }, ledger, hits);
+        }
+        if (actual.stage !== expected.stage) {
+            return outcomeVerdict(base, `expected rejection stage \`${expected.stage}\`, got \`${actual.stage}\` (${actual.diagnostics})`, { expected: "rejected", actual: "rejected", stage: actual.stage }, ledger, hits);
+        }
+        if (expected.code !== undefined && actual.code !== expected.code) {
+            return outcomeVerdict(base, `expected rejection code \`${expected.code}\`, got \`${String(actual.code)}\``, { expected: "rejected", actual: "rejected", stage: actual.stage }, ledger, hits);
+        }
+        return { ...base, status: "expected-rejected", detail: `rejected at \`${actual.stage}\` as expected` };
+    }
+    if (actual.outcome === "rejected") {
+        return outcomeVerdict(base, `expected an effective config, got a rejection at \`${actual.stage}\`: ${actual.diagnostics}`, { expected: "effective", actual: "rejected", stage: actual.stage }, ledger, hits);
+    }
+    // ① 秘密面先判:告警里带着语料埋的秘密,比读数对不对更严重。
+    const leaks = findSecretLeaks(actual.warnings, c.meta.secrets ?? []);
+    if (leaks.length > 0) {
+        return { ...base, status: "diff", detail: `warning surface leaked ${leaks.length} corpus secret(s) — 告警不许比它诊断的东西更危险`, diff: { effective: [], warnings: { missing: [], extra: leaks }, metadata: [] } };
+    }
+    // ② effective(剥元数据)
+    const split = splitMetadata(actual.effective);
+    const expectedBody = canonicalize(expected.effective);
+    const actualBody = canonicalize(split.body);
+    const effectivePatch = deepEqual(expectedBody, actualBody) ? [] : diffJson(expectedBody, actualBody);
+    // ③ 告警多重集
+    let actualProjections;
+    try {
+        actualProjections = actual.warnings.map((w) => projectWarning(w));
+    }
+    catch (e) {
+        return { ...base, status: "harness-error", detail: `a returned warning could not be projected: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const warningDiff = diffWarningMultiset(expected.warnings, actualProjections, normalizer);
+    // ④ 元数据独立断言
+    const actualVersion = actual.version ?? split.version;
+    const actualUpdatedAt = actual.updatedAt ?? split.updatedAt;
+    const metadataPatch = [];
+    if (expected.metadata.version !== undefined && actualVersion !== expected.metadata.version) {
+        metadataPatch.push({ op: "replace", path: "/version", expected: expected.metadata.version, actual: actualVersion });
+    }
+    else if (expected.metadata.version === undefined && !(typeof actualVersion === "number" && Number.isFinite(actualVersion))) {
+        metadataPatch.push({ op: "replace", path: "/version", expected: "a finite number", actual: actualVersion });
+    }
+    if (actualUpdatedAt !== expected.metadata.updatedAt)
+        metadataPatch.push({ op: "replace", path: "/updatedAt", expected: expected.metadata.updatedAt, actual: actualUpdatedAt });
+    if (effectivePatch.length === 0 && warningDiff.missing.length === 0 && warningDiff.extra.length === 0 && metadataPatch.length === 0) {
+        return { ...base, status: "pass", detail: "effective, warnings and metadata all match" };
+    }
+    const diff = { effective: effectivePatch, warnings: warningDiff, metadata: metadataPatch };
+    const detail = `${effectivePatch.length} effective diff(s), ${warningDiff.missing.length} missing / ${warningDiff.extra.length} extra warning(s), ${metadataPatch.length} metadata diff(s)`;
+    // ⑤ 账本(3.0.0 车 FT):**只收 effective 的差**,且**逐坐标**全覆盖才算入账。
+    // 告警与元数据这两面永不可入账 —— 它们是这道门的承重面(一条被「已知」掉的告警差,正是本门要抓的病);
+    // 一格里只要有一条坐标没登记,整格仍是 `diff`(账本是白名单,不是整格豁免)。
+    const ledgerable = effectivePatch.length > 0 && warningDiff.missing.length === 0 && warningDiff.extra.length === 0 && metadataPatch.length === 0;
+    if (ledgerable) {
+        const idx = effectivePatch.map((p) => ledgerIndexFor(ledger, c.id, leg, p.path));
+        if (idx.every((i) => i !== undefined)) {
+            for (const i of idx)
+                hits[i] += 1;
+            return { ...base, status: "diff-ledgered", detail: `${detail} — 全部落在适配器的已知分歧账本里`, diff, ledgerRefs: idx.map((i) => ledger[i].ref) };
+        }
+    }
+    return { ...base, status: "diff", detail, diff };
+}
+/** release 模式的**来源律 + 版本护栏**(historical 模式不跑这几条:它就是拿旧版包比行为的)。 */
+async function releaseViolations(adapter, opts, corpus, kit) {
+    const v = [];
+    if (opts.only !== undefined)
+        v.push("release mode forbids `only` — 一个能挑 case 的发版门不是门");
+    if (opts.normalizer !== undefined)
+        v.push("release mode forbids a normalizer — 归一器只用来看旧版,不用来放宽今天的门");
+    if (corpus.version !== kit.version)
+        v.push(`corpus VERSION ${corpus.version} !== kit package version ${kit.version}`);
+    if (adapter.provenance.version !== corpus.version)
+        v.push(`adapter provenance version ${adapter.provenance.version} !== corpus VERSION ${corpus.version}`);
+    if (adapter.provenance.integrity.trim().length === 0)
+        v.push("adapter provenance has an empty `integrity` — 三仓装的是不是同一份 tarball,靠的就是这一行");
+    // provenance 不是一句自报:它指的那份 package.json 必须**真在磁盘上**、真是这个包、版号真与自报值相同。
+    // 只核「是不是绝对路径」等于没核 —— 一个指向不存在目录的路径照样全绿(codex R1 [high] 复现)。
+    const pj = adapter.provenance.packageJsonPath;
+    if (!isAbsolute(pj)) {
+        v.push(`adapter provenance packageJsonPath must be absolute, got \`${pj}\``);
+    }
+    else {
+        try {
+            const declared = JSON.parse(await readFile(pj, "utf8"));
+            if (declared.name !== kit.name)
+                v.push(`adapter provenance packageJsonPath is not the contract package: ${pj} declares name \`${String(declared.name)}\`, expected \`${kit.name}\``);
+            else if (declared.version !== adapter.provenance.version)
+                v.push(`adapter provenance packageJsonPath version mismatch: the file says \`${String(declared.version)}\`, the adapter reports \`${adapter.provenance.version}\``);
+        }
+        catch {
+            v.push(`adapter provenance packageJsonPath cannot be read as JSON: ${pj}`);
+        }
+    }
+    // 账本条目的**形**:一条大包大揽的 `pathPrefix`(`/` 或空串)不是账本,是一个 `ok=true` 开关;
+    // 没有 `ref` / `flipWhen` 的一条登记没法被人查、也没法到期翻转(棘轮靠这两个字段才立得住)。
+    for (const e of adapter.knownDivergences ?? []) {
+        if (e.ref.trim().length === 0)
+            v.push("a known divergence has an empty `ref` — 查不到出处的一条登记等于没登记");
+        if (e.flipWhen.trim().length === 0)
+            v.push(`known divergence \`${e.ref}\` has an empty \`flipWhen\` — 说不出什么时候删,它就永远不会被删`);
+        if (e.outcome === undefined) {
+            if (!e.pathPrefix.startsWith("/") || e.pathPrefix.length < 2)
+                v.push(`known divergence \`${e.ref}\` has a blanket \`pathPrefix\` (\`${e.pathPrefix}\`) — 账本要逐坐标点名,整片豁免不是账本`);
+            continue;
+        }
+        // 结局形那一臂的两条硬约束。类型上已经挡住(`kind` 只有 `"debt"`、`cases` 必填),但适配器可能来自
+        // JSON / `as` —— 门不靠类型自证,运行期照判。`kind` 先读进一个宽类型的局部,否则 TS 把「不是 debt」
+        // 那一支收成 `never`,连报错文案都取不出字段。
+        const kind = e.kind;
+        const cases = e.outcome.cases;
+        if (kind !== "debt")
+            v.push(`known divergence \`${e.ref}\` is an outcome divergence with kind \`${kind}\` — 结局形只能是 \`debt\`:契约说拒、消费方说不拒,不是「成文语义」盖得住的分歧`);
+        if (!Array.isArray(cases) || cases.length === 0)
+            v.push(`known divergence \`${e.ref}\` is an outcome divergence that must name at least one case — 结局形不许按前缀大包一整条腿的拒绝面`);
+    }
+    const legs = Object.entries(adapter.legs).filter(([, l]) => l !== undefined);
+    if (legs.length === 0)
+        v.push("adapter registers no leg at all");
+    for (const [name, leg] of legs) {
+        const mod = leg.entry.module;
+        if (!isAbsolute(mod)) {
+            v.push(`leg \`${name}\` entry.module must be an absolute path, got \`${mod}\``);
+            continue;
+        }
+        if (!MODULE_EXTENSIONS.includes(extname(mod)))
+            v.push(`leg \`${name}\` entry.module is not a module file (${mod}) — 入口得是个模块,不是随便一个存在的文件`);
+        let real = mod;
+        try {
+            real = await realpath(mod); // 先解软链再判:一条指向 node_modules 里契约包的软链不算「在外面」
+            const s = await stat(real);
+            if (!s.isFile())
+                v.push(`leg \`${name}\` entry.module is not a file: ${mod}`);
+        }
+        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}) — 那条腿证明的是「包等于包」`);
+        if (leg.entry.export.trim().length === 0)
+            v.push(`leg \`${name}\` entry.export is empty`);
+    }
+    return v;
+}
+/**
+ * 跑一遍门。
+ *
+ * `release`:版本三方对齐(适配器加载到的包 == 语料 VERSION == kit 所在包)+ 每条登记的腿都指向一个
+ * **真存在、且不在契约包 node_modules 之下**的生产入口 + 禁 `only` + 至少登记一条腿 + **登记的腿必须跑**
+ * (未登记的腿只记 `skipped: no adapter`,不算违例)+ 账本条目的形 + 零陈腐账本条目。
+ * `historical`:对旧版包跑,只记行为 diff;归一器可在场且必须自陈有损。
+ */
+export async function runConformance(adapter, opts) {
+    const corpus = await loadCorpus(opts.corpusDir);
+    const kit = await kitIdentity();
+    const violations = opts.mode === "release" ? await releaseViolations(adapter, opts, corpus, kit) : [];
+    const only = opts.only === undefined ? undefined : new Set(opts.only);
+    const cases = only === undefined ? corpus.cases : corpus.cases.filter((c) => only.has(c.id));
+    if (only !== undefined) {
+        const missing = [...only].filter((id) => !corpus.cases.some((c) => c.id === id));
+        if (missing.length > 0)
+            throw new Error(`conformance: \`only\` names unknown case id(s): ${missing.join(", ")}`);
+    }
+    const ledger = adapter.knownDivergences ?? [];
+    const hits = ledger.map(() => 0);
+    const results = [];
+    for (const c of cases) {
+        for (const leg of LEG_NAMES) {
+            const expected = resolveLegExpectation(c, leg, corpus.baseline);
+            if (expected === null) {
+                const spec = c.expected[leg];
+                results.push({ caseId: c.id, leg, status: "skipped", detail: `case declares this leg not applicable: ${spec.why}` });
+                continue;
+            }
+            const impl = adapter.legs[leg];
+            if (impl === undefined) {
+                // 未登记 = 这个消费方结构上没有这条读法(docs/CONFORMANCE.md §1「没有的腿不要造」)。逐格记
+                // `skipped: no adapter`,覆盖矩阵看得见它没跑,**不算违例** —— 律指向的是**登记过的东西**
+                // (至少一条腿 + 登记的腿必须跑),而不是「三条腿必须都有」。
+                results.push({ caseId: c.id, leg, status: "skipped", detail: "no adapter: this consumer registered no such read leg" });
+                continue;
+            }
+            let actual;
+            try {
+                actual = await impl.run(legInput(c, leg));
+            }
+            catch (e) {
+                results.push({ caseId: c.id, leg, status: "harness-error", detail: `the adapter threw instead of returning an outcome: ${e instanceof Error ? e.message : String(e)}` });
+                continue;
+            }
+            results.push(judge(c, leg, expected, actual, opts.normalizer, ledger, hits));
+        }
+    }
+    const summary = { pass: 0, diff: 0, "diff-ledgered": 0, "expected-rejected": 0, "harness-error": 0, skipped: 0 };
+    for (const r of results)
+        summary[r.status] += 1;
+    const ledgerRows = ledger.map((e, i) => e.outcome === undefined
+        ? { ref: e.ref, kind: e.kind, leg: e.leg, pathPrefix: e.pathPrefix, ...(e.cases === undefined ? {} : { cases: e.cases }), flipWhen: e.flipWhen, hits: hits[i] }
+        : { ref: e.ref, kind: e.kind, leg: e.outcome.leg, outcome: { expected: e.outcome.expected, actual: e.outcome.actual }, cases: e.outcome.cases, flipWhen: e.flipWhen, hits: hits[i] });
+    if (opts.mode === "release") {
+        // **登记的腿必须跑**:登记了却在整套语料上一格真读数都没有,那条登记是空的。
+        for (const leg of LEG_NAMES) {
+            if (adapter.legs[leg] === undefined)
+                continue;
+            if (!results.some((r) => r.leg === leg && r.status !== "skipped")) {
+                violations.push(`leg \`${leg}\` is registered yet never ran — 整套语料上一格真读数都没有(登记的腿必须跑)`);
+            }
+        }
+        // **棘轮只降不升**:账本里一条从未命中的登记,自己就是违例 —— 债还了就得把账本删掉。
+        for (const row of ledgerRows) {
+            if (row.hits === 0)
+                violations.push(`stale ledger entry \`${row.ref}\` (leg \`${row.leg}\`, ${row.outcome === undefined ? `pathPrefix \`${row.pathPrefix}\`` : `outcome ${row.outcome.expected}→${row.outcome.actual}`}) never matched a diff — 差异没了就把这一条删掉(${row.flipWhen})`);
+        }
+    }
+    const uniqueViolations = [...new Set(violations)];
+    return {
+        mode: opts.mode,
+        adapter: { name: adapter.name, provenance: adapter.provenance, legs: LEG_NAMES.filter((l) => adapter.legs[l] !== undefined) },
+        corpusVersion: corpus.version,
+        kitVersion: kit.version,
+        ...(opts.normalizer === undefined ? {} : { normalizer: { id: opts.normalizer.id, lossy: opts.normalizer.lossy, why: opts.normalizer.why } }),
+        results,
+        summary,
+        ledger: ledgerRows,
+        violations: uniqueViolations,
+        ok: uniqueViolations.length === 0 && summary.diff === 0 && summary["harness-error"] === 0,
+    };
+}