@sema-agent/settings-schema 6.1.0 → 6.3.0

package/dist/config-fns.js

@@ -16,6 +16,8 @@
 // zod is a VALUE import here (not just a type): {@link salvageEntries} introspects a domain schema to find
 // its entry collections. zod is this package's one runtime dependency, so this costs nothing new.
 import { z } from "zod";
+import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
+import { carriesUserinfo, secretScanForms } from "./secret-scan.js"; // package-private display-side normalization + the userinfo judgement (not in the barrel)
 import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, SkillsManifestSchema, containsSecretToken } from "./types.js";
 /** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
  *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
@@ -23,20 +25,32 @@ import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX,
  *  any secret-shaped run (`%` kept in the run so a percent-encoded secret stays whole for the percent-aware
  *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14.
  *
- *  **Output invariant** (S-712 verification pass N1 + codex review [high] ×2): a string holding a private-key PEM
- *  header ANYWHERE ({@link PRIVATE_KEY_PEM_HEADER}) is withheld WHOLE, and no result trips `containsSecretToken`.
- *  The PEM header is judged on the ORIGINAL text, before any replacement: the token pass can rewrite the header
- *  itself away (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes
- *  `[redacted-secret]` and the key body after it would ride out untouched — codex verification round). A PEM header
- *  carries spaces, so the targeted passes can never isolate it, and the detector only sees it at the very start of
- *  a string. Every warning face that goes through here (coordinates, error text, entry identity) inherits the same
- *  guarantee. The validation-side detector `containsSecretToken` is deliberately NOT widened here: making it reject
- *  a mid-string PEM would tighten every field it validates (a major). */
+ *  **Output invariant** (S-712 verification pass N1 + codex review [high] ×2; 6.3.0): a string holding a private-key
+ *  PEM header ANYWHERE ({@link PRIVATE_KEY_PEM_HEADER}) in ANY of its {@link secretScanForms} `forms` is withheld WHOLE, a
+ *  string whose normalization did not finish (`unresolved`) is withheld WHOLE, and no result trips `containsSecretToken` on
+ *  any of its forms.
+ *  The whole-string judgement is ONE rule — both detectors run over the normalized forms: the PEM header on every form of
+ *  the ORIGINAL text, `containsSecretToken` on every form of the targeted result; what could not be normalized does not go
+ *  out (6.3.0, codex r1 F1: `-----BEGIN+PRIVATE+KEY` form-encoded headers and four-layer encodings both rode out).
+ *  6.3.0 (codex review of v6.1.0 [high]): `key=` + a percent-encoded PEM showed its header only on a decoded form
+ *  (`-----BEGIN%20PRIVATE%20KEY` — `%20` is not in `[A-Z0-9 ]`), and the detector's anchored decode missed it behind
+ *  the `key=` prefix, so the whole key rode out through coordinates, zod `received` / `message` and entry identity.
+ *  The PEM header is judged BEFORE any replacement: the token pass can rewrite the header itself away
+ *  (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes `[redacted-secret]` and the
+ *  key body after it would ride out untouched — codex verification round). A PEM header carries spaces, so the
+ *  targeted passes can never isolate it, and the detector only sees it at the very start of a string. Every
+ *  free-text warning face that goes through here (coordinates, error text) inherits the same guarantee; the entry
+ *  identity face additionally has to be an identifier ({@link isDisclosableIdentity}). The validation-side detector
+ *  `containsSecretToken` is deliberately NOT widened here: making it reject a mid-string PEM would tighten every field
+ *  it validates (a major). */
 export function redactSecrets(text) {
     const targeted = text
         .replace(/\b(bearer|basic)(\s+)\S+/gi, "$1$2[redacted-secret]")
         .replace(/[A-Za-z0-9_./:+=%-]{6,}/g, (tok) => (containsSecretToken(tok) ? "[redacted-secret]" : tok));
-    return PRIVATE_KEY_PEM_HEADER.test(text) || containsSecretToken(targeted) ? "[redacted-secret]" : targeted;
+    const scan = secretScanForms(text);
+    const targetedForms = targeted === text ? scan.forms : secretScanForms(targeted).forms; // 没替换过(最常见)⇒ 同一组形,不再归一化一遍
+    const whole = scan.unresolved || scan.forms.some((form) => PRIVATE_KEY_PEM_HEADER.test(form)) || targetedForms.some((form) => containsSecretToken(form));
+    return whole ? "[redacted-secret]" : targeted;
 }
 /** Sanitize a ZodError IN PLACE so no surfaced error (message / `received` / nested `unionErrors`) echoes a
  *  pasted secret. RECURSES into `unionErrors` (a `z.union` failure nests a ZodError per member — e.g. RoleTarget
@@ -184,10 +198,62 @@ const PLAIN_PATH_SEGMENT = /^(?!(?:0|[1-9]\d*)$)[^."\u0000-\u001f]+$/;
 export function formatConfigPath(p) {
     return p.map((seg) => (typeof seg === "number" ? String(seg) : PLAIN_PATH_SEGMENT.test(seg) ? seg : JSON.stringify(seg))).join(".");
 }
-/** 身份串:字符串,且 {@link redactSecrets} 原样放行 —— 与坐标段脱敏、`error` 文案脱敏({@link sanitizeZodError})
- *  **同一只**判据:告警面上任何一处用户写的串,要么过这一只脱敏器出门,要么(可缺的身份)不出门。两只判据
- *  会在同一条告警里给出两种答案(对抗轮 #2 真复现:`Bearer` 后接 NBSP 或短令牌时,旧判据放行、坐标却打码)。 */
-const isIdentityString = (v) => typeof v === "string" && redactSecrets(v) === v;
+/** 本文件铸的、带用户写的键段的告警坐标出门前的**唯一**一道(6.3.0,codex r1 F2):字符串段过 {@link outgoingSegment} —— 与 `error` 文案
+ *  ({@link sanitizeZodError})、身份否决({@link isDisclosableIdentity})**同一只**脱敏器,不另设判据;数字段(下标)原样。
+ *  键段是用户写的,完全可能就是一条粘错位置的凭据:被丢 Record 条目的键、未知键告警(`unknown-keys-dropped` /
+ *  `-carried`)的键名都一样(后者 0.19.0 起从不过脱敏器,`sk-…` 形的未知键名原样进告警与投影)。schema 已知的字段名
+ *  脱敏器原样放行,所以坐标里「它是哪个字段」照旧可读。经它的坐标就是出门形 —— {@link droppedKeys} /
+ *  {@link carriedUnknownKeys} 这两只导出函数给消费方的 `keys` 同样是它的产物。`legacy-governance-lifted.keys` 不经它:那些键只来自
+ *  闭集 {@link GOVERNANCE_MIRROR_KEYS},按构造没有用户写的串(opus 腿 I1)。 */
+function outgoingPath(p) {
+    return p.map((seg) => (typeof seg === "string" ? outgoingSegment(seg) : seg));
+}
+/** 一段用户写的串(坐标键段、`hosts-grandfathered` 被夹紧的主机名)出门前的那一道:长过 {@link DISCLOSABLE_IDENTITY_MAX}(与身份白名单同一只上界)
+ *  ⇒ 不扫描、整段 `[redacted-secret]`(标识符不会那么长;fail-closed 且 O(1) —— opus 独立腿 M1:6.3.0 首稿让每个未知键名
+ *  不论多长都过脱敏器,64 个 16 KB 的键名把一次读拖到 20 s 以上);否则过 {@link redactSecrets}。 */
+function outgoingSegment(seg) {
+    return seg.length > DISCLOSABLE_IDENTITY_MAX ? "[redacted-secret]" : redactSecrets(seg);
+}
+/** 可披露身份与出门坐标段的**长度上界**(一只常量,两处用:{@link DISCLOSABLE_IDENTITY_RE} 的上限、{@link outgoingSegment}
+ *  的「超长不扫描」界)。与 web-admin 读侧名长上限 256 对齐。 */
+const DISCLOSABLE_IDENTITY_MAX = 256;
+/** 可披露身份的**闭形**(6.3.0):字符集 `A-Z a-z 0-9 . _ : / @ + -`、长度 1–256(上限与 web-admin 读侧名长上限 256 对齐;`ModelEntry.name`
+ *  本身不设上限,超 256 字的合法名按无名处置)。身份是**标识符**不是自由文本 ——
+ *  允许集才是它的语义:上游模型 id 的真实形(`accounts/fireworks/models/…`、`Qwen/Qwen2.5-72B-Instruct`、
+ *  `claude-3-5-sonnet@20240620`、`deepseek-v4-flash:free`、`o3-mini+high`)都在集内;`%` / `=` / 空白 / 引号 / 反斜杠 /
+ *  控制与零宽字符 / 非 ASCII 一律在集外 —— 编码过的、带前缀的、多行的、会在日志里伪造行的串,不可能是一个标识符。
+ *  无旗标(无 `g` ⇒ `.test` 无状态,可放心共享这一只)。判据只有 {@link isDisclosableIdentity} 一只,消费方要
+ *  「这个名能不能写出去」问它,不要拿本常量自拼(集内仍有密钥形,见那一只的否决项)。 */
+export const DISCLOSABLE_IDENTITY_RE = new RegExp(`^[A-Za-z0-9._:/@+-]{1,${DISCLOSABLE_IDENTITY_MAX}}$`);
+/** 身份串 —— 「一个用户写的身份串(条目的 `name` / `id`)能不能**原样**出门」的**唯一**判据(6.3.0 起两项合取):
+ *   ① **形**:落在 {@link DISCLOSABLE_IDENTITY_RE} 白名单闭形里(不再是「不像密钥就可披露」—— 6.1.0 / 6.2.0 的黑名单
+ *      判据放行过 `key=` + 百分号编码的整把 PEM 私钥,codex 对 v6.1.0 复审 [high]);
+ *   ② **否决**(「无密钥形」):坐标脱敏器 {@link redactSecrets} 原样放行 —— 集内照样有密钥形(`sk-…` / `ghp_…` /
+ *      `AKIA…` / 三段 JWT 的字符全在集内),而且判它的必须是坐标段、`error` 文案({@link sanitizeZodError})用的**同一只**
+ *      脱敏器:两只判据会在同一条告警里给出两种答案(对抗轮 #2 真复现;集内的残例 = `@` 之后的单点 `eyJ…` 串,裸探测器
+ *      判阴、脱敏器会改,语料 c41 钉着);∧ 不是带 userinfo 的 URL —— 校验侧 `NON_SECRET_URL` 拒写的同一只判定
+ *      (`carriesUserinfo`,包内私有;opus 腿 L1:`postgres://svc:pw@h` 的字符全在集内)。
+ *  入参是 `string`、返回 `boolean`,**刻意不是**类型谓词(`v is string`):它对一些字符串答 false,谓词形会让调用方的
+ *  否定分支把一个 `string` 收窄成 `never`;「是不是字符串」由调用点自己判(运行期收到非字符串照答 false、不抛)。
+ *  不可披露的串按**无名**处置(不带,而不是打码:打过码的串不再是身份)。
+ *  执法面(同一条律):被丢条目的身份({@link DroppedEntryIdentity},本文件铸);`ModelRefusalsWire` 的 `entries` 键
+ *  (经 {@link isReportableRefusalName},S-768);引擎自己的日志 / 拒因句里要不要写出一个名字,同样问这一只。 */
+export function isDisclosableIdentity(v) {
+    // 非字符串(JS / any 调用方)⇒ false,不抛(秘密轴 fail-closed)
+    return typeof v === "string" && DISCLOSABLE_IDENTITY_RE.test(v) && redactSecrets(v) === v && !carriesUserinfo(v);
+}
+/** S-768 —— 「一个目录条目名能不能当 {@link ModelRefusalsWire} `entries` 的键」的**唯一**判据;引擎铸键前只调这一只,
+ *  不过 ⇒ 按无名处置(不进键、不计数)。两条律的合取,不手抄任何一条:
+ *   ① 这只 schema **自己载得住**这个键 —— 就地拿 schema 判(空串不过键规则;`__proto__` 这类名被 zod 的 record 静默丢掉,
+ *      载不住),不写名单;
+ *   ② {@link isDisclosableIdentity}(不是白名单闭形里的标识符,或是秘密形 ⇒ 不出门)。
+ *  非字符串 ⇒ false。住在本文件而不是 `./fleet`:`fleet.ts` 被 `types.ts` 引,它再引本文件会成环。 */
+export function isReportableRefusalName(name) {
+    if (!isDisclosableIdentity(name))
+        return false;
+    const probe = ModelRefusalsWire.safeParse({ entries: { [name]: MODEL_ENTRY_REFUSAL_CODES[0] } });
+    return probe.success && Object.hasOwn(probe.data.entries, name);
+}
 /** 一条被丢条目原文的身份({@link DroppedEntryIdentity} 的**唯一**读法)。只看纯 JSON 对象的**自有数据
  *  属性**;任何反射/陷阱抛错 ⇒ 当作读不出(身份是诊断面的附件,绝不许把抢救拖下水)。 */
 function readEntryIdentity(entry) {
@@ -202,8 +268,8 @@ function readEntryIdentity(entry) {
         const id = own("id");
         const enabled = own("enabled");
         const identity = {
-            ...(isIdentityString(name) ? { name } : {}),
-            ...(isIdentityString(id) ? { id } : {}),
+            ...(typeof name === "string" && isDisclosableIdentity(name) ? { name } : {}),
+            ...(typeof id === "string" && isDisclosableIdentity(id) ? { id } : {}),
             ...(typeof enabled === "boolean" ? { enabled } : {}),
         };
         return Object.keys(identity).length > 0 ? identity : undefined;
@@ -253,7 +319,7 @@ function judgeEntry(schema, value) {
  * 造出一个空集合**。
  *
  * 🔴 **告警不许比它诊断的东西更危险**(复审 R1 两条,红先复现):① Record 的键是用户写的,完全可能就是
- * 一条粘错位置的凭据,所以路径里的键段过 {@link redactSecrets} 才出门(不变量①:secret 值永不随错误外流,
+ * 一条粘错位置的凭据,所以路径里的键段过 {@link redactSecrets} 才出门(6.3.0 起经 `outgoingPath` 这一道;不变量①:secret 值永不随错误外流,
  * 与 parseDomain 的 R13/R14 同一条);② 整段遍历包 try/catch —— 读字段、枚举 Record 都会触发访问器,
  * 抛出来的文案可能带 secret。抢救是**尽力而为**的:抢不动就当没抢救(返回原引用),让既有的整域档位去裁,
  * 绝不把解析拖下水、更不回显它的错误(与同文件 {@link droppedKeys} 逐字同纪律)。
@@ -299,7 +365,7 @@ function salvageEntriesUnsafe(schema, raw) {
                     keptFrom.push(i); // 压缩后第 keptFrom.length-1 条 = 原文档第 i 条
                     return true;
                 }
-                bad.push(droppedEntry([field, i], error, entry));
+                bad.push(droppedEntry(outgoingPath([field, i]), error, entry));
                 return false;
             });
             // 零幸存者 ⇒ 没有要抢救的东西(见头注:绝不凭空造出一个空集合)。
@@ -319,7 +385,7 @@ function salvageEntriesUnsafe(schema, raw) {
                 if (error === undefined)
                     kept[key] = entry;
                 else
-                    bad.push(droppedEntry([field, redactSecrets(key)], error, entry)); // 键是用户写的,可能就是一条粘错位置的凭据
+                    bad.push(droppedEntry(outgoingPath([field, key]), error, entry)); // 键是用户写的,可能就是一条粘错位置的凭据
             }
             if (bad.length > 0 && Object.keys(kept).length > 0) {
                 dropped.push(...bad);
@@ -399,7 +465,7 @@ export const WARNING_KINDS = [
 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 }) };
+            return { kind: w.kind, domain: w.domain, droppedNames: w.droppedNames, ...(w.droppedTotal === undefined ? {} : { droppedTotal: w.droppedTotal }), ...(w.truncatedFrom === undefined ? {} : { truncatedFrom: w.truncatedFrom }) };
         case "domain-defaulted":
             return { kind: w.kind, domain: w.domain };
         // 两臂字段相同但**不合并**:合并后 `kind` 塌成两员的联合,TS 就再也认不出它属于投影联合的哪一员
@@ -576,7 +642,7 @@ function collectDropped(domain, raw, parsed, prefix, depth, spared, acc) {
                 continue; // 扩展命名空间:按契约放的键,不是未知键
             acc.total += 1;
             if (acc.keys.length < DROP_SCAN_MAX_KEYS)
-                acc.keys.push([...prefix, k]);
+                acc.keys.push(outgoingPath([...prefix, k]));
             continue;
         }
         collectDropped(domain, raw[k], parsed[k], [...prefix, k], depth + 1, spared, acc);
@@ -662,7 +728,7 @@ export function carriedUnknownKeys(domain, parsed) {
                 continue;
             acc.total += 1;
             if (acc.keys.length < DROP_SCAN_MAX_KEYS)
-                acc.keys.push([...at, k]);
+                acc.keys.push(outgoingPath([...at, k]));
         }
     }
     return acc;
@@ -746,15 +812,23 @@ export const DOMAIN_READ_FALLBACK = {
  *  observable: a deployment that has not seen that warning across a full read cycle no longer needs the arm. */
 export function grandfatherHostsRead(raw) {
     if (raw === null || typeof raw !== "object" || !Array.isArray(raw.hosts)) {
-        return { raw, droppedNames: [], keptIndex: NO_ENTRIES_DROPPED }; // not the expected shape — let parseDomain rule on it
+        return { raw, droppedNames: [], droppedTotal: 0, keptIndex: NO_ENTRIES_DROPPED }; // not the expected shape — let parseDomain rule on it
     }
     const original = raw.hosts;
     const droppedNames = [];
+    let droppedTotal = 0;
     const keptFrom = [];
     let hosts = original.filter((h, i) => {
         const name = h !== null && typeof h === "object" ? h.name : undefined;
         if (typeof name === "string" && name.length > HOST_NAME_MAX) {
-            droppedNames.push(name.slice(0, HOST_NAME_MAX) + "…"); // audit label — clipped so the warning itself stays bounded
+            droppedTotal += 1;
+            // 先钳后扫(S-813):只给前 DROP_SCAN_MAX_KEYS 个铸标签,其余只计数 —— 出门那一道每个名都要归一化一遍,不能随文档条数放大。
+            if (droppedNames.length >= DROP_SCAN_MAX_KEYS)
+                return false;
+            // 出门前先过同一道(6.3.0,opus 腿 M2):用户写的主机名完全可能就是一条粘错位置的凭据,夹紧只管载荷上界、不管秘密 ——
+            // 此前 `sk-live-…` 形 / 编码 PEM 形以 63 字原文前缀出门。判在夹紧**之前**(截断会把秘密形截成探测器认不出的半截)。
+            const out = outgoingSegment(name);
+            droppedNames.push(out.length > HOST_NAME_MAX ? out.slice(0, HOST_NAME_MAX) + "…" : out); // audit label — clipped so the warning itself stays bounded
             return false;
         }
         keptFrom.push(i); // 夹紧后第 keptFrom.length-1 条 = 原文档第 i 条
@@ -765,11 +839,11 @@ export function grandfatherHostsRead(raw) {
         truncatedFrom = hosts.length;
         hosts = hosts.slice(0, HOSTS_ARRAY_MAX);
     }
-    if (droppedNames.length === 0 && truncatedFrom === undefined)
-        return { raw, droppedNames, keptIndex: NO_ENTRIES_DROPPED }; // identity — byte-stable
+    if (droppedTotal === 0 && truncatedFrom === undefined)
+        return { raw, droppedNames, droppedTotal, keptIndex: NO_ENTRIES_DROPPED }; // identity — byte-stable
     // 位移**只**来自按名剔条目;纯截断留下的是原数组前缀,幸存者下标不动 ⇒ 不登记(见 EntryKeptIndex)。
-    const keptIndex = droppedNames.length > 0 ? { hosts: keptFrom.slice(0, hosts.length) } : NO_ENTRIES_DROPPED;
-    return { raw: { ...raw, hosts }, droppedNames, truncatedFrom, keptIndex };
+    const keptIndex = droppedTotal > 0 ? { hosts: keptFrom.slice(0, hosts.length) } : NO_ENTRIES_DROPPED;
+    return { raw: { ...raw, hosts }, droppedNames, droppedTotal, truncatedFrom, keptIndex };
 }
 export function buildEffective(version, getRaw, updatedAt, onWarning) {
     // 0.19.0 静默剥键/静默承运门:解析**成功**的域,把 schema 丢掉的键、以及 open-world 域里承运但本包
@@ -846,8 +920,9 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
     // hosts: the PRECISE grandfather for the 0.8.0 tightening runs BEFORE parse (0.7-era legal data over the
     // new bounds reads on, clamped + warned); any residual corruption falls to the generic guardrail above.
     const hostsGf = grandfatherHostsRead(getRaw("hosts"));
-    if (hostsGf.droppedNames.length > 0 || hostsGf.truncatedFrom !== undefined) {
-        onWarning?.({ domain: "hosts", kind: "hosts-grandfathered", droppedNames: hostsGf.droppedNames, truncatedFrom: hostsGf.truncatedFrom });
+    if (hostsGf.droppedTotal > 0 || hostsGf.truncatedFrom !== undefined) {
+        const clipped = hostsGf.droppedTotal > hostsGf.droppedNames.length ? { droppedTotal: hostsGf.droppedTotal } : {};
+        onWarning?.({ domain: "hosts", kind: "hosts-grandfathered", droppedNames: hostsGf.droppedNames, ...clipped, truncatedFrom: hostsGf.truncatedFrom });
     }
     return {
         version,

package/dist/cross-session.d.ts

@@ -15,11 +15,11 @@
  *   HELD cross-session message awaits approval」。**注意它有两个消费面**:远端停靠的审批对话框,与
  *   停审的跨会话消息;本模块只声明键形,哪个宿主消费哪一面由宿主自陈。
  *
- * ## `"default"` 这第四个拼写
+ * ## `"default"` 这第五个拼写
  *
- * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第四种策略**:读取器
+ * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第五种策略**:读取器
  * (`readCrossSessionInbound` / `readDialogExpiry`)把它与 `null`/缺席一同折成 `undefined`。所以
- * `CrossSessionInboundSetting` 的受理面是四拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有三个。
+ * `CrossSessionInboundSetting` 的受理面是五拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有四个。
  *
  * ## 坏值方向 = 响亮,不静默
  *
@@ -29,8 +29,11 @@
  *
  * ## 与引擎词表的锁步
  *
- * 引擎另有一份同词表(判定纯函数的输入域)。两份**必须逐字相等**;等值由消费方(同时装了本包与引擎
- * 的那一侧)用一格锁步钉住 —— 任一侧加词/改序,那一格先红。本包不 import 引擎(纯度不变量)。
+ * 两张词表与 dialogExpiry 缺省的语义属主是引擎(判定纯函数的输入域;缺省也铸在引擎),本模块的三只常量是
+ * 它们的**登记镜像** —— 保留镜像是因为本包不能运行期依赖引擎,删掉它们两键的 schema 就只剩 `z.string()`。
+ * 两份**必须逐字同序相等**;等值由**本仓自证**:`test/upstream-drift.test.ts` ④ 在 dev 期读引擎的运行期导出,
+ * 登记表恒空(零豁免)、顺序另钉 —— 任一侧加词/改序/改缺省,那一格先红。消费方不再替本仓守这面镜像,只钉
+ * 「自己读的是引擎那份」。本包不 import 引擎(纯度不变量;引擎只在 devDependency)。
  */
 import { z } from "zod";
 /**

package/dist/cross-session.js

@@ -15,11 +15,11 @@
  *   HELD cross-session message awaits approval」。**注意它有两个消费面**:远端停靠的审批对话框,与
  *   停审的跨会话消息;本模块只声明键形,哪个宿主消费哪一面由宿主自陈。
  *
- * ## `"default"` 这第四个拼写
+ * ## `"default"` 这第五个拼写
  *
- * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第四种策略**:读取器
+ * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第五种策略**:读取器
  * (`readCrossSessionInbound` / `readDialogExpiry`)把它与 `null`/缺席一同折成 `undefined`。所以
- * `CrossSessionInboundSetting` 的受理面是四拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有三个。
+ * `CrossSessionInboundSetting` 的受理面是五拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有四个。
  *
  * ## 坏值方向 = 响亮,不静默
  *
@@ -29,8 +29,11 @@
  *
  * ## 与引擎词表的锁步
  *
- * 引擎另有一份同词表(判定纯函数的输入域)。两份**必须逐字相等**;等值由消费方(同时装了本包与引擎
- * 的那一侧)用一格锁步钉住 —— 任一侧加词/改序,那一格先红。本包不 import 引擎(纯度不变量)。
+ * 两张词表与 dialogExpiry 缺省的语义属主是引擎(判定纯函数的输入域;缺省也铸在引擎),本模块的三只常量是
+ * 它们的**登记镜像** —— 保留镜像是因为本包不能运行期依赖引擎,删掉它们两键的 schema 就只剩 `z.string()`。
+ * 两份**必须逐字同序相等**;等值由**本仓自证**:`test/upstream-drift.test.ts` ④ 在 dev 期读引擎的运行期导出,
+ * 登记表恒空(零豁免)、顺序另钉 —— 任一侧加词/改序/改缺省,那一格先红。消费方不再替本仓守这面镜像,只钉
+ * 「自己读的是引擎那份」。本包不 import 引擎(纯度不变量;引擎只在 devDependency)。
  */
 import { z } from "zod";
 // ── crossSessionInbound ────────────────────────────────────────────────────────────────────────────

package/dist/fleet.d.ts

@@ -81,6 +81,107 @@ export type RestartSignal = z.infer<typeof RestartSignal>;
  * Presence law: only `restart` counts; the top-level `restartRequired` boolean the server also ships is not read.
  */
 export declare function readRestartSignal(health: unknown): RestartSignal | undefined;
+/**
+ * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
+ * one edit in this file; who goes red at compile time: a reader that switches on the code exhaustively (a center), and
+ * a producer only where it holds a table KEYED BY the code (an exhaustive `switch` over the code, or a
+ * `Record<ModelEntryRefusalCode, …>`) — a producer table that merely `satisfies` these codes as values proves a subset,
+ * not equality, and stays green.
+ *
+ *  - {@link MODEL_ENTRY_REFUSAL_CODES} — why ONE catalog entry is not served on this host (the other entries keep serving):
+ *    `config.model_no_brain` — the entry's provider rides a brain this host has not mounted;
+ *    `config.model_entry_invalid` — the entry does not match the `ModelEntry` shape (dropped by the read, or re-judged at
+ *    the engine's own second boundary).
+ *  - {@link MODEL_PLANE_REFUSAL_CODES} — why the model plane of the catalog the engine was handed was refused AS A GROUP
+ *    (the engine keeps serving the model plane it had). This set mirrors the engine's group-refusal code TABLE as a
+ *    whole family — never picked by which invariant is reachable on the hot path today (reachability moves, the table
+ *    does not):
+ *    `config.default_model_missing` — the candidate has no default model;
+ *    `config.model_refused_name_minted` — a refused entry's name would be re-minted onto another entry by the
+ *    tier / alias expansion (or the dropped-entry carrier cannot prove it would not be);
+ *    `config.model_route_endpoint_missing` — an openai-compatible route of the candidate resolves to no endpoint;
+ *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary.
+ *    Source (engine): the first two in `src/model-entry-refusal.ts`, the last two in `src/model-route-endpoint.ts:40,42`
+ *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`).
+ */
+export declare const MODEL_ENTRY_REFUSAL_CODES: readonly ["config.model_no_brain", "config.model_entry_invalid"];
+export declare const ModelEntryRefusalCode: z.ZodEnum<["config.model_no_brain", "config.model_entry_invalid"]>;
+export type ModelEntryRefusalCode = z.infer<typeof ModelEntryRefusalCode>;
+export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary"];
+export declare const ModelPlaneRefusalCode: z.ZodEnum<["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary"]>;
+export type ModelPlaneRefusalCode = z.infer<typeof ModelPlaneRefusalCode>;
+/**
+ * "This instance does not serve part (or all) of the model catalog it was handed" — the engine's OWN per-host verdict
+ * (S-768), defined ONCE for both exits that carry it: the fleet heartbeat ({@link InstanceAnnouncement}`.modelRefusals`)
+ * and GET /health (`modelRefusals`; {@link InstanceHealth} keeps carrying it untyped, as it does `restart`). One mint point,
+ * two exits, ONE reader for both: {@link readModelRefusals}.
+ *
+ * Two faces, split on purpose — the failure direction must match the meaning (this is a DIAGNOSTIC key; an unknown word
+ * in it must never make a healthy instance unroutable):
+ *  - {@link ModelRefusalsWire} — what rides the wire and what a stored heartbeat row holds: the SHAPE law only, codes as
+ *    open non-empty strings. A code this package version does not know passes (it is "not said" to this reader, and the
+ *    stored row still carries it for a reader that is upgraded later).
+ *  - {@link ModelRefusalsSignal} — what {@link readModelRefusals} returns: the wire narrowed to the closed sets above (an
+ *    unknown entry code or plane code is dropped; narrowed to nothing ⇒ `undefined`, rendered like "not said"). The
+ *    closed-set types stay the compile-time red source for readers when a code is added.
+ *
+ * The wire shape:
+ *  - `entries` — catalog entry NAME → its code. The value is ONLY the code, on purpose: the engine's refusal fact also
+ *    holds the upstream `id`, the `provider` word, the bad field keys and an operator sentence, and none of them rides
+ *    here — an `entry_invalid` row is by definition one nothing validated, so its `id` / `provider` may be whatever the
+ *    broken row held, and the sentence is prose, not contract. "Which name, which reason" is the whole wire. A name that
+ *    cannot ride out is treated as NAMELESS — the engine leaves it out of this map entirely (not keyed, not counted). The
+ *    ONE predicate is `isReportableRefusalName(name)` (main barrel): this schema can carry the key (non-empty; `__proto__`
+ *    is silently dropped by the record, so it cannot) AND `isDisclosableIdentity(name)` (an identifier in the closed allowlist
+ *    `DISCLOSABLE_IDENTITY_RE` — `A-Z a-z 0-9 . _ : / @ + -`, 1–256 chars — AND not secret-shaped, a URL userinfo included; the
+ *    rule the dropped-entry identity on read warnings already uses, 6.3.0). A producer calls it before keying; this schema deliberately
+ *    does not re-judge secrecy (see the 6.2.0 notes).
+ *  - `plane` — present ⇔ the model plane of the latest catalog the engine was handed was refused as a group (the engine
+ *    keeps serving the model plane it had); ONE code, never a list — one candidate has exactly one group verdict (the
+ *    engine judges the group invariants in a fixed order and stops at the first that fails; a refusal from the Runner
+ *    swap step carries no code and is outside this signal).
+ *  - `entries` and `plane` describe the same latest candidate catalog — the one the engine was handed last; with `plane`
+ *    present, that is the refused candidate (its per-entry verdicts are usually why it has no default). The engine does
+ *    not swap its own refusal table while the group stays refused (its selection channels still refuse by the previous
+ *    generation), so with `plane` present read `entries` as "why this catalog cannot land", not "what a pick is refused
+ *    right now".
+ *
+ * PRESENCE is the signal (same law as {@link RestartSignal}): present ⇔ at least one reportable refusal (an entry refusal
+ * under a name that rides out, or a group refusal). An empty signal (no entries and no `plane`) is refused by the shape
+ * law — "none" has exactly one spelling, the absent key. Inside, "no entry refusals" is spelled `entries: {}` (the key is
+ * required) — one spelling at each level.
+ */
+export declare const ModelRefusalsWire: z.ZodEffects<z.ZodObject<{
+    entries: z.ZodRecord<z.ZodString, z.ZodString>;
+    plane: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}>, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}>;
+export type ModelRefusalsWire = z.infer<typeof ModelRefusalsWire>;
+/** {@link ModelRefusalsWire} narrowed to the closed code sets — the return type of {@link readModelRefusals}. */
+export type ModelRefusalsSignal = {
+    entries: Record<string, ModelEntryRefusalCode>;
+    plane?: ModelPlaneRefusalCode;
+};
+/**
+ * The ONE reader of the model-refusals signal, for BOTH exits: pass a /health body or a parsed
+ * {@link InstanceAnnouncement} — it reads the `modelRefusals` key of whatever it is given. Shape mismatch, a missing key, a
+ * non-object body, even a throwing accessor ⇒ `undefined` — never throws. Then it narrows to the closed sets: an unknown
+ * entry code drops that entry, an unknown plane code drops `plane`; narrowed to nothing ⇒ `undefined`. So `undefined`
+ * means "nothing this reader can say"; whether that is "none" or "unknown" depends on whether the engine reports this key
+ * at all — it answers the key only and never judges the engine's version (see {@link InstanceAnnouncement}`.modelRefusals`).
+ */
+export declare function readModelRefusals(body: unknown): ModelRefusalsSignal | undefined;
 /** The `/health` self-description every orchestrator reads (shipped shape, server 1.96.0). Liveness and
  *  readiness are deliberately SPLIT: `status` stays ok while draining (the process is alive); routability is
  *  `isReadyForTraffic`. Unknown fields pass through — health is a self-description, not a closed record. */
@@ -150,6 +251,32 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         version: number;
         since: number;
     }>>;
+    /** S-768: present ⇔ this instance has at least one reportable model refusal — the SAME {@link ModelRefusalsWire} /health
+     *  carries, minted by the same getter; read it with {@link readModelRefusals}`(announcement)` (never off this field
+     *  directly: the field is the open wire form, the reader narrows to the closed sets). Every heartbeat re-announces the
+     *  full row, so a later heartbeat WITHOUT it means "no reportable refusals any more" (the stored row is replaced, never
+     *  merged). Reading absence: from an engine that reports this key, absent = none reportable; an engine that predates
+     *  the key never sends it, so there absence is UNKNOWN, not "none" — tell the two apart by the announced `version`.
+     *  Failure direction = meaning direction (this is a diagnostic key): a code this package version does not know passes
+     *  (it is "not said" to the reader), and a value that breaks the {@link ModelRefusalsWire} shape law is dropped to
+     *  ABSENT (`.catch`) — it never fails the announcement, so it can never make a healthy instance unroutable (unlike
+     *  `restart`, whose shape still gates the row). The key may then be present with the value `undefined`. */
+    modelRefusals: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        entries: z.ZodRecord<z.ZodString, z.ZodString>;
+        plane: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     draining: boolean;
     version: string;
@@ -163,6 +290,10 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         version: number;
         since: number;
     } | undefined;
+    modelRefusals?: {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    } | undefined;
 }, {
     version: string;
     instanceId: string;
@@ -175,6 +306,7 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         version: number;
         since: number;
     } | undefined;
+    modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
 }>;
 export type InstanceAnnouncement = z.infer<typeof InstanceAnnouncement>;
@@ -223,6 +355,32 @@ export declare const InstanceRegistration: z.ZodObject<{
         version: number;
         since: number;
     }>>;
+    /** S-768: present ⇔ this instance has at least one reportable model refusal — the SAME {@link ModelRefusalsWire} /health
+     *  carries, minted by the same getter; read it with {@link readModelRefusals}`(announcement)` (never off this field
+     *  directly: the field is the open wire form, the reader narrows to the closed sets). Every heartbeat re-announces the
+     *  full row, so a later heartbeat WITHOUT it means "no reportable refusals any more" (the stored row is replaced, never
+     *  merged). Reading absence: from an engine that reports this key, absent = none reportable; an engine that predates
+     *  the key never sends it, so there absence is UNKNOWN, not "none" — tell the two apart by the announced `version`.
+     *  Failure direction = meaning direction (this is a diagnostic key): a code this package version does not know passes
+     *  (it is "not said" to the reader), and a value that breaks the {@link ModelRefusalsWire} shape law is dropped to
+     *  ABSENT (`.catch`) — it never fails the announcement, so it can never make a healthy instance unroutable (unlike
+     *  `restart`, whose shape still gates the row). The key may then be present with the value `undefined`. */
+    modelRefusals: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        entries: z.ZodRecord<z.ZodString, z.ZodString>;
+        plane: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>>>;
 } & {
     registeredMs: z.ZodNumber;
     lastSeenMs: z.ZodNumber;
@@ -242,6 +400,10 @@ export declare const InstanceRegistration: z.ZodObject<{
         version: number;
         since: number;
     } | undefined;
+    modelRefusals?: {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    } | undefined;
     observedReady?: boolean | undefined;
 }, {
     version: string;
@@ -257,6 +419,7 @@ export declare const InstanceRegistration: z.ZodObject<{
         version: number;
         since: number;
     } | undefined;
+    modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
     observedReady?: boolean | undefined;
 }>;