@sema-agent/settings-schema 10.1.0 → 11.0.0

package/dist/conformance/contract-adapter.d.ts

@@ -2,8 +2,15 @@ import type { ConformanceAdapter, ConformanceProvenance, LegEntry, LegName } fro
 /** 一份契约模块(新旧版同形 —— 四条腿的签名自 0.19.0 起没动过)。 */
 export interface ContractModule {
     buildEffective(version: number, getRaw: (d: string) => unknown, updatedAt: string, onWarning?: (w: unknown) => void): unknown;
-    /** 严写受理的生产入口:一个域名 + 一份原始文档 → 受理后的域文档,不受理就抛。 */
-    parseDomain(domain: string, raw: unknown): unknown;
+    /** 严写受理第一道:一个域名 + 一份原始文档 → 受理后的域文档,不受理就抛;受理时的告警(剥掉 / 承运的未知键)交给 `onWarning`。 */
+    parseDomainLoud(domain: string, raw: unknown, onWarning?: (w: unknown) => void): unknown;
+    /** 严写受理第二道 = **那一只引用判官**:整份(受理后的)文档集 → 每一条解析不到的跨域引用(`path` 以引用者的域键起手)。
+     *  一份文档集只判一次(不逐域各问一遍 —— 那样同一条悬空引用会被正反两向各报一次)。 */
+    danglingRefs(docs: Record<string, unknown>): ReadonlyArray<{
+        path: ReadonlyArray<string | number>;
+    }> | Promise<ReadonlyArray<{
+        path: ReadonlyArray<string | number>;
+    }>>;
     readEffectiveWire(raw: unknown, onWarning?: (w: unknown) => void): unknown;
     loadLocalConfig(root: string, opts?: {
         onWarning?: (w: unknown) => void;

package/dist/conformance/contract-adapter.js

@@ -6,9 +6,11 @@
  * `buildEffective` / `parseDomain` / `readEffectiveWire` / `loadLocalConfig` **就是**它的生产入口);②historical 模式要对
  * 一份旧版 dist 跑同样的四腿。
  *
- * `strictWrite`(严写受理)= 文档集里**每一个**键各自过 `parseDomain`(写入席收下的那份);任何一份不受理 ⇒ 整次
- * `rejected{stage:"validate"}`(写是一个动作,不是逐份抢救);全部受理 ⇒ `effective` = 键 → 受理后的域文档(只含入参里的
- * 键,不补缺席域)。`parseDomain` 不铸告警,所以这条腿的告警面恒空。
+ * `strictWrite`(严写受理)= 写入席的两道:① 文档集里**每一个**键各自过 `parseDomainLoud`(受理的那份 + 受理时的告警:剥掉 /
+ * 承运的未知键);任何一份不受理 ⇒ 整次 `rejected{stage:"validate"}`(写是一个动作,不是逐份抢救)。② 对文档集里每个引用受检域
+ * 整份受理后的文档集过一次**那一只引用判官** `danglingRefs`(文档集里没有的域 = 空;正反两向一次判完);
+ * 有悬空引用 ⇒ `rejected{stage:"validate", code: REF_INTEGRITY_REJECT_CODE, refIssues}`。都过 ⇒ `effective` = 键 → 受理后的域文档
+ * (只含入参里的键,不补缺席域)+ ① 的告警。
  *
  * 4.0.0 起这句自陈**有牙**:入口落在契约包自己身上 ⇒ 造适配器那一刻就**拒**(抛,不是告警 —— 一条告警
  * 在 CI 日志里活不过第二天,而这道门一旦被同义反复接进去,它报的全绿是**假绿**)。判别式单铸在
@@ -21,7 +23,7 @@
  */
 import { materializeLocalRoot } from "./run.js";
 import { contractOwnedEntry, contractOwnedEntryWhy } from "./entry-origin.js";
-import { LEG_NAMES } from "./types.js";
+import { LEG_NAMES, REF_INTEGRITY_REJECT_CODE } from "./types.js";
 /** ZodError 形(鸭子判,不用 `instanceof` —— historical 模式下旧版 dist 可能挂在另一份 zod 上)。 */
 const isZodLike = (e) => e !== null && typeof e === "object" && Array.isArray(e.issues);
 /** 内容哈希那一层拒绝的自述 —— `stableStringify` 的深度闸是**本包自己**抛的、也只有它会抛这一句;
@@ -76,15 +78,21 @@ export function createContractAdapter(opts) {
                 catch (e) {
                     return reject(e, "validate");
                 }
-            case "strictWrite":
+            case "strictWrite": {
+                let accepted;
                 try {
                     // fromEntries(不是逐键赋值):文档集的键是用户写的,`__proto__` 作键时逐键赋值会走原型 setter。
-                    const accepted = Object.fromEntries(Object.entries(input.docs).map(([d, raw]) => [d, mod.parseDomain(d, raw)]));
-                    return { outcome: "effective", effective: accepted, warnings: [], version: input.version, updatedAt: input.updatedAt };
+                    accepted = Object.fromEntries(Object.entries(input.docs).map(([d, raw]) => [d, mod.parseDomainLoud(d, raw, onWarning)]));
                 }
                 catch (e) {
                     return reject(e, "validate");
                 }
+                const refIssues = (await mod.danglingRefs(accepted)).map((issue) => ({ path: [...issue.path] }));
+                if (refIssues.length > 0) {
+                    return { outcome: "rejected", stage: "validate", code: REF_INTEGRITY_REJECT_CODE, diagnostics: `${refIssues.length} dangling cross-domain reference(s)`, refIssues };
+                }
+                return { outcome: "effective", effective: accepted, warnings: warnings, version: input.version, updatedAt: input.updatedAt };
+            }
             case "wire":
                 try {
                     const effective = mod.readEffectiveWire(input.payload, onWarning);

package/dist/conformance/corpus.d.ts

@@ -24,6 +24,9 @@ export type LegExpectationJson = {
     outcome: "rejected";
     stage: RejectStage;
     code?: string;
+    refIssues?: Array<{
+        path: Array<string | number>;
+    }>;
     why?: string;
 };
 export interface CaseInput {

package/dist/conformance/corpus.js

@@ -55,6 +55,11 @@ function checkLegExpectation(v, where) {
     if (r.outcome === "rejected") {
         if (!REJECT_STAGES.includes(r.stage))
             throw new Error(`conformance corpus: ${where}.stage must be one of ${REJECT_STAGES.join("|")}`);
+        if (r.refIssues !== undefined) {
+            const ok = Array.isArray(r.refIssues) && r.refIssues.every((x) => isRecord(x) && Array.isArray(x.path) && x.path.every((seg) => typeof seg === "string" || typeof seg === "number"));
+            if (!ok)
+                throw new Error(`conformance corpus: ${where}.refIssues must be an array of { path: (string|number)[] }`);
+        }
         return r;
     }
     throw new Error(`conformance corpus: ${where} is none of {derive:true} | {applicable:false,why} | {outcome:"effective"} | {outcome:"rejected"}`);

package/dist/conformance/derive.d.ts

@@ -60,6 +60,9 @@ export type LegExpectation = {
     outcome: "rejected";
     stage: RejectStage;
     code?: string;
+    refIssues?: ReadonlyArray<{
+        path: ReadonlyArray<string | number>;
+    }>;
 };
 /** T1 + T2 + T4:`domains` 期望 → `wire` 期望。 */
 export declare function deriveWireExpectation(source: Extract<LegExpectation, {

package/dist/conformance/index.d.ts

@@ -2,7 +2,7 @@
  * `@sema-agent/settings-schema/conformance` —— 跨仓一致性门的 kit。
  *
  * 一句话:契约仓自带**金样语料 + 比对器**;每个消费方把**自己的生产读腿**塞给 kit 跑一遍 ⇒ 同一份
- * settings 语料在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
+ * settings 语料在 web-admin / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
  *
  * 三步接线(消费方侧):
  *   1. 造一个 {@link ConformanceAdapter}:`provenance` = 你**实际加载到**的那份契约包(package.json 路径、
@@ -20,4 +20,4 @@ export { loadCorpus, loadCase, kitIdentity, DEFAULT_CORPUS_DIR, PACKAGE_ROOT, ty
 export { DERIVATION_TRANSFORMS, LEG_EXPECTATION, 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_DECLINE_REASONS, LEG_NAMES, REJECT_STAGES, type ConformanceAdapter, type ConformanceLeg, type DomainDocsInput, type LegDeclineReason, type LegDeclined, type LegStance, 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";
+export { LEDGER_REF_RULE, LEG_DECLINE_REASONS, REF_INTEGRITY_REJECT_CODE, type RefIssueCoordinate, LEG_NAMES, REJECT_STAGES, type ConformanceAdapter, type ConformanceLeg, type DomainDocsInput, type LegDeclineReason, type LegDeclined, type LegStance, 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

@@ -2,7 +2,7 @@
  * `@sema-agent/settings-schema/conformance` —— 跨仓一致性门的 kit。
  *
  * 一句话:契约仓自带**金样语料 + 比对器**;每个消费方把**自己的生产读腿**塞给 kit 跑一遍 ⇒ 同一份
- * settings 语料在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
+ * settings 语料在 web-admin / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、告警多重集一致。
  *
  * 三步接线(消费方侧):
  *   1. 造一个 {@link ConformanceAdapter}:`provenance` = 你**实际加载到**的那份契约包(package.json 路径、
@@ -20,4 +20,4 @@ export { loadCorpus, loadCase, kitIdentity, DEFAULT_CORPUS_DIR, PACKAGE_ROOT } f
 export { DERIVATION_TRANSFORMS, LEG_EXPECTATION, 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_DECLINE_REASONS, LEG_NAMES, REJECT_STAGES, } from "./types.js";
+export { LEDGER_REF_RULE, LEG_DECLINE_REASONS, REF_INTEGRITY_REJECT_CODE, LEG_NAMES, REJECT_STAGES, } from "./types.js";

package/dist/conformance/run.js

@@ -19,7 +19,7 @@ import { diffWarningMultiset, findSecretLeaks, projectWarning } from "./warnings
 import { deriveLocalExpectation, deriveLocalInput, deriveWireExpectation, deriveWireInput, toManifestDoc } from "./derive.js";
 import { kitIdentity, loadCorpus } from "./corpus.js";
 import { contractOwnedEntry, contractOwnedEntryWhy } from "./entry-origin.js";
-import { LEG_DECLINE_REASONS, LEG_NAMES, } from "./types.js";
+import { LEDGER_REF_RULE, LEG_DECLINE_REASONS, LEG_NAMES, } from "./types.js";
 /** 一个**模块**文件的样子 —— 来源律用它挡住「随便找个存在的文件当入口」(`package.json` 也是文件)。 */
 const MODULE_EXTENSIONS = [".ts", ".mts", ".cts", ".tsx", ".js", ".mjs", ".cjs", ".jsx"];
 /**
@@ -120,7 +120,15 @@ export function resolveLegExpectation(c, leg, baseline) {
     }
     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 }) };
+    return { outcome: "rejected", stage: spec.stage, ...(spec.code === undefined ? {} : { code: spec.code }), ...(spec.refIssues === undefined ? {} : { refIssues: spec.refIssues }) };
+}
+/** 两袋悬空引用坐标相等吗(多重集;坐标按结构比 —— 与告警坐标同一只稳定键)。 */
+function sameRefIssueBag(expected, actual) {
+    if (actual === undefined || actual.length !== expected.length)
+        return false;
+    const key = (x) => stableKey(x.path);
+    const a = actual.map(key).sort();
+    return expected.map(key).sort().every((k, i) => k === a[i]);
 }
 /** effective 里的元数据两键(独立断言,不进结构比对)。 */
 const METADATA_KEYS = ["version", "updatedAt"];
@@ -186,10 +194,29 @@ function outcomeVerdict(base, detail, shape, ledger, hits) {
     hits[i] += 1;
     return { ...base, status: "diff-ledgered", detail: `${detail} — 落在适配器的已知分歧账本里(结局形,债)`, diff, ledgerRefs: [ledger[i].ref] };
 }
+/** 一条腿交回的**每一处文本**里的语料秘密:读出 ⇒ 告警面(`findSecretLeaks`,同一只判据);拒绝 ⇒ 诊断句。 */
+function legLeaks(actual, secrets) {
+    switch (actual.outcome) {
+        case "effective":
+            return findSecretLeaks(actual.warnings, secrets);
+        case "rejected":
+            return secrets.filter((s) => s.length > 0 && actual.diagnostics.includes(s));
+        default: {
+            const unhandled = actual;
+            throw new Error(`conformance: unknown outcome ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
 /** 一格的比对。返回 status + detail(+ diff)。`hits` 是账本逐条的命中计数器 —— 由本函数就地累加
  *  (比对与计数走同一遍遍历;再扫一遍就是第二份判定,两份判定的分歧正是本门要抓的那类病)。 */
 function judge(c, leg, expected, actual, normalizer, ledger, hits) {
     const base = { caseId: c.id, leg };
+    // ① 秘密面**先于一切**判:一条腿交回的文本(读出时的告警、拒绝时的诊断句)里带着语料埋的秘密,比读数对不对、结局形对不对都严重
+    // —— 不论结局形是否一致、账本是否盖得住,这一格都是 `diff`,且不可入账。
+    const leaks = legLeaks(actual, c.meta.secrets ?? []);
+    if (leaks.length > 0) {
+        return { ...base, status: "diff", detail: `the leg's output leaked ${leaks.length} corpus secret(s) — 告警 / 诊断不许比它诊断的东西更危险`, diff: { effective: [], warnings: { missing: [], extra: leaks }, metadata: [] } };
+    }
     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);
@@ -200,16 +227,14 @@ function judge(c, leg, expected, actual, normalizer, 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);
         }
+        if (expected.refIssues !== undefined && !sameRefIssueBag(expected.refIssues, actual.refIssues)) {
+            return outcomeVerdict(base, `expected dangling references at ${JSON.stringify(expected.refIssues.map((x) => x.path))}, got ${JSON.stringify(actual.refIssues?.map((x) => x.path) ?? "none")}`, { 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);
@@ -255,6 +280,13 @@ function judge(c, leg, expected, actual, normalizer, ledger, hits) {
     }
     return { ...base, status: "diff", detail, diff };
 }
+/** `YYYY-MM-DD` 且是真实的日历日(UTC;`2026-02-30` 不是)。 */
+function isCalendarDate(v) {
+    if (typeof v !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(v))
+        return false;
+    const d = new Date(`${v}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v;
+}
 function stanceOf(adapter, leg) {
     const legs = adapter.legs;
     const s = legs !== null && typeof legs === "object" ? legs[leg] : undefined;
@@ -312,26 +344,39 @@ async function releaseViolations(adapter, opts, corpus, kit) {
         }
     }
     // 账本条目的**形**:一条大包大揽的 `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` — 查不到出处的一条登记等于没登记");
+    // 没有票号形 `ref` / `window` / `flipWhen` 的一条登记没法被人查、也没法到期(棘轮靠这三个字段才立得住)。
+    // 类型上已经挡住(`kind` 只有 `"debt"`、`window` 必填),但适配器可能来自 JSON / `as` —— 门不靠类型自证,运行期照判;
+    // 字段先读进宽类型的局部,否则 TS 把「不是 debt」那一支收成 `never`,连报错文案都取不出字段。
+    const ledger = adapter.knownDivergences ?? [];
+    const nowMs = opts.nowMs;
+    const today = typeof nowMs === "number" && Number.isFinite(nowMs) ? new Date(nowMs).toISOString().slice(0, 10) : undefined;
+    if (ledger.length > 0 && today === undefined)
+        v.push("release mode needs `nowMs` to judge the ledger windows — 库码不读环境时钟,钟由调用方传(账本为空时不需要)");
+    for (const e of ledger) {
+        const ref = e.ref;
+        const kind = e.kind;
+        const window = e.window;
+        const name = typeof ref === "string" ? ref : String(ref);
+        if (typeof ref !== "string" || !LEDGER_REF_RULE.test(ref))
+            v.push(`known divergence \`ref\` ${JSON.stringify(ref)} is not a ticket id (\`ABC-12\` / \`ABC-12②\` / \`XY-7.3\` form) — 查不到出处的一条登记等于没登记`);
+        if (kind !== "debt")
+            v.push(`known divergence \`${name}\` has kind \`${String(kind)}\` — the ledger takes only debts (a ticket and a window), no standing exemptions`);
+        if (window === undefined)
+            v.push(`known divergence \`${name}\` has no \`window\` — 说不出最晚活到哪天的债永远不会被还`);
+        else if (!isCalendarDate(window))
+            v.push(`known divergence \`${name}\`: \`window\` ${JSON.stringify(window)} is not a calendar date (YYYY-MM-DD, UTC)`);
+        else if (today !== undefined && today > window)
+            v.push(`known divergence \`${name}\` is past its window ${window} (today ${today}) — pay the debt, or move the window in the ticket with a reason`);
         if (e.flipWhen.trim().length === 0)
-            v.push(`known divergence \`${e.ref}\` has an empty \`flipWhen\` — 说不出什么时候删,它就永远不会被删`);
+            v.push(`known divergence \`${name}\` 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}\`) — 账本要逐坐标点名,整片豁免不是账本`);
+                v.push(`known divergence \`${name}\` 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 — 结局形不许按前缀大包一整条腿的拒绝面`);
+            v.push(`known divergence \`${name}\` is an outcome divergence that must name at least one case — 结局形不许按前缀大包一整条腿的拒绝面`);
     }
     // **每条腿都要表态**:实现,或显式声明不承担(闭集理由词 + why)。缺表态 / 形不对 ⇒ 违例 —— 不许静默跳过,也不许默认当通过。
     const legs = [];
@@ -453,8 +498,8 @@ export async function runConformance(adapter, opts) {
     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] });
+        ? { ref: e.ref, kind: e.kind, window: e.window, leg: e.leg, pathPrefix: e.pathPrefix, ...(e.cases === undefined ? {} : { cases: e.cases }), flipWhen: e.flipWhen, hits: hits[i] }
+        : { ref: e.ref, kind: e.kind, window: e.window, 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) {

package/dist/conformance/types.d.ts

@@ -3,7 +3,7 @@
  *
  * 成案:2.0.0 / 2.1.0 两版的正确性靠「表态 + 黑盒测试 + 提货车各自红先」,三样都是**单仓视角** ——
  * 真跨仓分歧是被提货车**碰巧**撞出来的。碰巧不是门。本 kit 让每个消费方把**自己的生产读腿**塞进来跑
- * 同一份语料:同一份 settings 在 center / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、
+ * 同一份语料:同一份 settings 在 web-admin / worker / 管理面 / 契约仓自身读出的 effective 逐字节一致、
  * 告警多重集一致,否则红。
  *
  * 规范化(canonical JSON、告警投影、坐标深相等)全部在 kit 内**单铸** —— 消费方零复述,因为一份被各自
@@ -13,11 +13,12 @@ import type { EffectiveReadWarning, WarningProjection } from "../config-fns.js";
 /** 四条腿的名字。**闭集** —— 新开一条腿要同时在 `derive.ts` 的 {@link LEG_EXPECTATION}(`Record<LegName, …>`,
  *  不表态即编译红)里说清它的期望从哪来,且每个消费方的 {@link ConformanceAdapter.legs} 都要对它表态(实现或声明不承担)。
  *
- *  · `domains`:各域**原始文档**(center 侧存储形)→ effective。契约仓的 `buildEffective`(读:逐条抢救 + 降级 + 告警)。
- *  · `strictWrite`:同一份各域原始文档 → **严写受理**(写入席收下这份文档集与否)。契约仓的 `parseDomain`;管理面的
- *    域写受理。结局复用 {@link LegOutcome} 的两类:全部受理 ⇒ `effective` = 严格解析出的域文档集(只含入参里的键,
- *    不补缺席域);任何一份不受理 ⇒ `rejected{stage:"validate"}`。读腿抢救的(坏条目丢弃、整域降级、主机名夹紧)
- *    在这条腿上是拒 —— 写入席不替运维删他的条目。
+ *  · `domains`:各域**原始文档**(web-admin 侧存储形)→ effective。契约仓的 `buildEffective`(读:逐条抢救 + 降级 + 告警)。
+ *  · `strictWrite`:同一份各域原始文档 → **严写受理**(写入席收下这份文档集与否)。契约仓 = 逐域 `parseDomainLoud` + 整份文档集过一次
+ *    引用判官 `danglingRefs`;管理面 = 它的域写受理。结局复用 {@link LegOutcome} 的两类:全部受理 ⇒ `effective`
+ *    = 严格解析出的域文档集(只含入参里的键,不补缺席域)+ 受理时的告警(剥掉 / 承运的未知键);任何一份不受理 ⇒
+ *    `rejected{stage:"validate"}`;都解析得了但有悬空引用 ⇒ `rejected{stage:"validate", code:`{@link REF_INTEGRITY_REJECT_CODE}`}`,
+ *    拒体带悬空引用的坐标(`refIssues`)。读腿抢救的(坏条目丢弃、整域降级、主机名夹紧)在这条腿上是拒 —— 写入席不替运维删他的条目。
  *  · `wire`:`GET /effective` 载荷 → effective。契约仓的 `readEffectiveWire`。
  *  · `localRoot`:`config.d/` 目录快照(文件名 → 文件内容)→ effective。契约仓的 `loadLocalConfig`。 */
 export type LegName = "domains" | "strictWrite" | "wire" | "localRoot";
@@ -63,7 +64,15 @@ export type LegOutcome = {
     stage: RejectStage;
     code?: string;
     diagnostics: string;
+    refIssues?: readonly RefIssueCoordinate[];
 };
+/** 严写腿因**悬空引用**拒收时的拒绝码(机读;金样与比对都按它)。 */
+export declare const REF_INTEGRITY_REJECT_CODE = "ref-integrity";
+/** 一条悬空引用的坐标(段数组,以域键起手 —— `refIntegrityIssues` 的 `path`)。严写腿以 {@link REF_INTEGRITY_REJECT_CODE} 拒收时,
+ *  拒体带它们的**多重集**;金样同存,比对按坐标(句子不比:句子可随实现改字)。 */
+export interface RefIssueCoordinate {
+    path: readonly (string | number)[];
+}
 /** 拒绝发生的层。闭集 —— 新层要来这里登记(语料的 `stage` 字段按本表校验)。 */
 export type RejectStage = "envelope" | "parse" | "validate" | "hash" | "store";
 /** {@link RejectStage} 的运行期表(语料校验用;与类型同源)。 */
@@ -136,7 +145,8 @@ export interface LegDeclined {
  *  release 门在运行期按同一条律判(适配器可能来自 JS / `as`):带 `declined` 又带 `entry` 或 `run` = 形不对。 */
 export type LegStance = ConformanceLeg | LegDeclined;
 /**
- * 消费方对金样的一条**已知合法差异**的登记位 —— 临时欠账,或成文语义。
+ * 消费方对金样的一条**已知差异**的登记位 —— 一笔**债**(11.0.0 起只有这一种:删了「成文语义」`declared`,它没有到期,一行登记活过了
+ * 它指向的票)。每行带**票号形**的 `ref`(查得到出处)与 `window`(最晚活到哪天),release 模式过窗即违例。
  *
  * 成案:消费方对金样的合法差异今天只能写在测试注里,而散文不是判据 —— 谁也说不清「这条差异还在不在」。
  * 登记之后它变成机器可核的一行:命中即 `diff-ledgered`(不阻塞),**从未命中即违例**(`stale ledger entry`)。
@@ -158,11 +168,13 @@ export interface PathDivergence {
      *  登记 `/models/1` 不豁免 `/models/10`)。必须以 `/` 开头并**点名至少一个顶层键** —— `/` 或空串是
      *  一个 `ok=true` 开关,不是账本。 */
     pathPrefix: string;
-    /** `"debt"` = 临时欠账(`ref` 是台账号);`"declared"` = 消费方成文语义(`ref` 是契约 / 文档锚)。 */
-    kind: "debt" | "declared";
-    /** 台账号或文档锚 —— 报告按它分组,人照它去查这笔差异的出处。 */
+    /** 账本只有债。 */
+    kind: "debt";
+    /** 台账票号({@link LEDGER_REF_RULE}:`ABC-12` / `ABC-12②` / `XY-7.3` 这一形,不是一段散文)—— 报告按它分组,人照它去查出处。 */
     ref: string;
-    /** 什么时候该把这一条删掉(债还了 / 语义改了)。人读,非空。 */
+    /** 这笔债最晚活到哪天:`YYYY-MM-DD`(UTC 日历日,当天仍在窗内)。release 模式的钟({@link ConformanceOptions.nowMs})晚于它 ⇒ 违例。 */
+    window: string;
+    /** 什么时候该把这一条删掉(债还了)。人读,非空。 */
     flipWhen: string;
     outcome?: never;
 }
@@ -172,10 +184,7 @@ export interface PathDivergence {
  * 成案(接线实跑):这类差根本没有 effective patch —— 比对停在「结局形就不一样」那一步,坐标形账本
  * 按 `pathPrefix` 够不着它,于是消费方 `ok` 恒 false,而它恰恰是门最该点名、也最该逼着修的一类。
  *
- * 两条硬约束,都是为了不让它变成一张万能豁免:
- *  · **`cases` 必填且非空** —— 结局形分歧不许按前缀大包一整条腿的拒绝面;
- *  · **只能是 `kind:"debt"`** —— 契约说拒、消费方说不拒,这不是「成文语义」盖得住的分歧,只能是债,
- *    带台账号、带翻转条件,由 stale 律逼着到期删掉。
+ * 硬约束:**`cases` 必填且非空** —— 结局形分歧不许按前缀大包一整条腿的拒绝面。与坐标形同律:是债,带票号、带窗、带翻转条件。
  */
 export interface OutcomeDivergence {
     kind: "debt";
@@ -189,10 +198,14 @@ export interface OutcomeDivergence {
         actual: "rejected" | "effective";
     };
     ref: string;
+    window: string;
     flipWhen: string;
     leg?: never;
     pathPrefix?: never;
 }
+/** 账本 `ref` 的形 —— 一个台账票号:大写字母起头、`-` 分段、带数字,可带一个小数段与至多两个字符的尾缀(`ABC-12`、`ABC-12②`、
+ *  `AB-C3`、`XY-7.3`),没有空白。一段散文(「一个设计稿的章节号 — …」)不是票号:查不到、也到不了期。 */
+export declare const LEDGER_REF_RULE: RegExp;
 /** 一个消费方交给 kit 的东西:它是谁、它加载的契约包是哪一份、它有哪几条生产读腿。 */
 export interface ConformanceAdapter {
     /** 消费方名(语料 `contributor` 同词表:`server` / `web-admin` / `cli` / `client-core` / `test` / `contract`)。 */
@@ -282,6 +295,7 @@ export interface ConformanceResult {
 export interface LedgerRow {
     ref: string;
     kind: KnownDivergence["kind"];
+    window: string;
     leg: LegName;
     /** 坐标形登记的段前缀(见 {@link PathDivergence.pathPrefix});**结局形**登记没有这一项。 */
     pathPrefix?: string;
@@ -334,4 +348,6 @@ export interface ConformanceOptions {
     corpusDir?: string;
     /** historical 模式的归一器。release 模式传了即违例(归一器只用来看旧版,不用来放宽今天的门)。 */
     normalizer?: ConformanceNormalizer;
+    /** 判账本窗的钟(epoch ms)。库码不读环境时钟:release 模式下适配器挂着账本 ⇒ 必须传,否则违例;账本为空不需要。 */
+    nowMs?: number;
 }

package/dist/conformance/types.js

@@ -1,6 +1,11 @@
 /** 四条腿的名字表(运行期枚举用;与 {@link LegName} 同源 —— 多一员少一员编译红)。 */
 export const LEG_NAMES = ["domains", "strictWrite", "wire", "localRoot"];
+/** 严写腿因**悬空引用**拒收时的拒绝码(机读;金样与比对都按它)。 */
+export const REF_INTEGRITY_REJECT_CODE = "ref-integrity";
 /** {@link RejectStage} 的运行期表(语料校验用;与类型同源)。 */
 export const REJECT_STAGES = ["envelope", "parse", "validate", "hash", "store"];
 /** {@link LegDeclineReason} 的运行期表(release 门校验用;与类型同源)。 */
 export const LEG_DECLINE_REASONS = ["no-production-path"];
+/** 账本 `ref` 的形 —— 一个台账票号:大写字母起头、`-` 分段、带数字,可带一个小数段与至多两个字符的尾缀(`ABC-12`、`ABC-12②`、
+ *  `AB-C3`、`XY-7.3`),没有空白。一段散文(「一个设计稿的章节号 — …」)不是票号:查不到、也到不了期。 */
+export const LEDGER_REF_RULE = /^(?=[^\s]*\d)[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+(?:\.[0-9]+)?[^\s]{0,2}$/;

package/dist/conformance/warnings.d.ts

@@ -17,7 +17,7 @@ import type { ConformanceNormalizer } from "./types.js";
 export { WARNING_KINDS, projectWarning, type WarningKind, type WarningProjection } from "../config-fns.js";
 /**
  * 一条投影的**比对归一形**:①坐标过一遍映射(historical 模式把段拼成旧版的点号串;无归一器时是恒等);
- * ②`keys` / `droppedNames` 这两个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
+ * ②`keys` 这个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
  * 写在这里一次。
  *
  * 为什么集合字段要按袋比(codex R1 [medium] 复现):一条告警里的 `keys` 是「这些键被剥了」的**一只袋**,

package/dist/conformance/warnings.js

@@ -22,7 +22,7 @@ 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));
 /**
  * 一条投影的**比对归一形**:①坐标过一遍映射(historical 模式把段拼成旧版的点号串;无归一器时是恒等);
- * ②`keys` / `droppedNames` 这两个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
+ * ②`keys` 这个**集合字段**按袋归一。第二处闭集穷举:哪些 kind 带坐标、带在哪个字段上,
  * 写在这里一次。
  *
  * 为什么集合字段要按袋比(codex R1 [medium] 复现):一条告警里的 `keys` 是「这些键被剥了」的**一只袋**,
@@ -34,12 +34,9 @@ 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;

package/dist/cross-domain.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-domain referential integrity — the PURE half, shared by the single-domain PUT and the batch write so
  * BOTH enforce the same rules (the multi-roster design note §6). The FLEET-coupled `applyAutoPlacement` (which imports
- * `../fleet/placement`) STAYS in sema-registry — it's not pure and not portable. This package carries only
+ * `../fleet/placement`) STAYS in web-admin — it's not pure and not portable. This package carries only
  * `refIntegrityIssues` + `createSiblingResolver` + the ref-issue types.
  *
  * BATCH-AWARE: a sibling domain (the models a roster references, the rosters a worker references) may be
@@ -12,11 +12,43 @@
  */
 import type { ConfigReader } from "./reader.js";
 import type { DomainConfig } from "./types.js";
+/** What a dangling reference failed to find —— the closed set (S-1075, 11.0.0): one word per referenced domain. */
+export declare const REF_ISSUE_KINDS: readonly ["unknown_model", "unknown_roster", "unknown_worker", "unknown_skill", "unknown_mcp", "unknown_plugin"];
+export type RefIssueKind = (typeof REF_ISSUE_KINDS)[number];
+/** The domain a {@link RefIssueKind}'s target lives in. */
+export declare const REF_ISSUE_TARGET_DOMAIN: {
+    readonly unknown_model: "models";
+    readonly unknown_roster: "rosters";
+    readonly unknown_worker: "workers";
+    readonly unknown_skill: "skills";
+    readonly unknown_mcp: "mcp";
+    readonly unknown_plugin: "plugins";
+};
+/** The domains whose documents carry cross-domain references (by name) —— the referrer side of the judge. */
+export declare const REF_REFERRER_DOMAINS: readonly ["rosters", "workers", "models", "collab", "systems", "entitlement"];
+export type RefReferrerDomain = (typeof REF_REFERRER_DOMAINS)[number];
+/** Who holds the reference: the referring entry's own name / id, or — for a domain-level field (`models.roles`,
+ *  `models.atMention`) — the domain alone (`name` absent). */
+export interface RefReferrer {
+    domain: RefReferrerDomain;
+    name?: string;
+}
+/** One reference that does not resolve —— structured operands (S-1075, 11.0.0): `kind` (what was not found), `referrer` (who
+ *  holds the reference), `target` (the name that was not found), `path` (where the reference sits; `path[0]` = the referrer's
+ *  domain key). `message` is {@link renderRefIssue} of them — a reader that must treat the user-written values differently from
+ *  the sentence's fixed words (a log boundary fingerprinting each value) re-renders with its own `show` instead of parsing the
+ *  sentence. Before 11.0.0 the values were only inside `message`. */
 export interface RefIssue {
     path: (string | number)[];
+    code: "custom";
+    kind: RefIssueKind;
+    referrer: RefReferrer;
+    target: string;
     message: string;
-    code: string;
 }
+/** The ONE rendering of a {@link RefIssue}'s sentence: `<referrer> → unknown <noun> "<target>" (at <path>)`. `show` maps each
+ *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted. */
+export declare function renderRefIssue(issue: Omit<RefIssue, "message">, show?: (value: string) => string): string;
 /** Resolve a sibling domain's effective value for integrity checks. */
 export type SiblingResolver = <K extends keyof DomainConfig>(domain: K) => Promise<DomainConfig[K] | undefined>;
 /** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
@@ -29,30 +61,42 @@ 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 — 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.
+/** The domains a write must be judged for —— the closed set as a RUNTIME VALUE (4.0.0): every domain that HOLDS cross-domain
+ *  references ({@link REF_REFERRER_DOMAINS}) and every domain those references POINT INTO (the targets of
+ *  {@link REF_ISSUE_TARGET_DOMAIN}) —— 11.0.0 (S-1066 ③) added the three target-only domains `skills` / `mcp` / `plugins`: deleting
+ *  a skill a tier still names is a dangling reference made by the skills write, so that write is judged too. 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)
+ *  asks this constant (or {@link isRefCheckedDomain}) instead of writing a list — a hand copy drifts silently (two rollback routes
+ *  in the admin console each once carried a five-member copy that had lost `entitlement`).
  *
- *  `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. */
+ *  `satisfies` keeps every member a real domain key; a pin checks it equals referrers ∪ targets. {@link RefCheckedDomain} is
+ *  DERIVED from this value. */
+export declare const REF_CHECKED_DOMAINS: readonly ["rosters", "workers", "models", "collab", "systems", "entitlement", "skills", "mcp", "plugins"];
+/** A domain a write must be judged for. DERIVED from {@link REF_CHECKED_DOMAINS} (4.0.0). */
 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.
+/** The documents the judge reads: any subset of the {@link RefCheckedDomain} domains. A domain that is absent defines no names
+ *  and holds no references (an absent `models` = an empty catalog: every model reference dangles). */
+export type RefDocs = Partial<{
+    [K in RefCheckedDomain]: DomainConfig[K];
+}>;
+/**
+ * **THE reference judge** (11.0.0, S-1066 ③; pure, synchronous): every by-name cross-domain reference in a document set that does
+ * not resolve, as a {@link RefIssue} (`path` = where the reference sits, `path[0]` = the referrer's domain). Both seats read this
+ * one conclusion: the write seat ({@link refIntegrityIssues}, refusing) and the read side (`resolveEffectiveForWorker`'s
+ * `refIssues`, reporting what it drops). Before 11.0.0 the write seat judged forward only and the read side judged on its own,
+ * silently.
+ */
+export declare function danglingRefs(docs: RefDocs): RefIssue[];
+/** Cross-domain ref integrity for a write of one {@link RefCheckedDomain} value (the write seat): the judge's conclusion on the
+ *  document set AFTER the write ({@link danglingRefs} over `value` + every other ref-checked domain through `resolve`), narrowed
+ *  to the references this write is answerable for —— the ones its own document holds (forward: a roster naming a model that is not
+ *  in the catalog) and the ones pointing into it (reverse, 11.0.0: deleting a model a roster still names; the issue names the
+ *  roster, `path` points at the reference). Empty = ok.
  *
- *  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). */
+ *  BATCH-AWARE through `resolve` (a sibling being written in the same batch shadows the stored one, see
+ *  {@link createSiblingResolver}). A reference that already dangled before this write and still involves this domain is reported
+ *  too — the same as the forward half always did (a roster write re-judges every roster). */
 export declare function refIntegrityIssues(domain: RefCheckedDomain, value: unknown, resolve: SiblingResolver): Promise<RefIssue[]>;