@sema-agent/settings-schema 6.3.0 → 6.4.0

package/CHANGELOG.md

@@ -8,6 +8,54 @@
 
 ## Unreleased
 
+## 6.4.0 — 2026-10-01 — `models.models[].headers` 解析透明键(S-935;与 `compat` 同一只变换)
+
+> **判档 = minor**(新键 = additive,README「发版纪律」)。缺席 = 键不铸 = 6.3.0 行为,零迁移;不带 `headers` 的文档读出来逐字节不变
+> (conformance 全语料重加冕:既有 61 条 case、`baseline.json`、`VERSION` 零 diff)。
+
+### 病(6.3.0 及更早)
+
+sema-server 7.108.0(S-931)给模型目录条目加了 `headers`(部署 ↔ 供应商的 per-model 附加请求头,例 `{"anthropic-beta":"context-1m-2025-08-07"}`
+开 1M 上下文)。本包 `ModelEntry` 没有这个键 ⇒ 每一条按域 schema 解析的读口都把它剥掉并报 `unknown-keys-dropped`
+(实测:`[{"domain":"models","kind":"unknown-keys-dropped","keys":[["models",0,"headers"]]}]`)—— 远端 `readEffectiveWire`、`buildEffective`、
+文件腿 `FileConfigStore.getEffective()`(严格 / `{tolerant:true}` 两形,`loadLocalConfig` 走严格形)、`FileConfigStore.getDomain`
+(`exportBundle` 的读法);写腿 `writeDomainFile` / `validateDomain` 同样剥,且连告警都没有。经生产配置通道写下的 `headers`
+到不了 server 目录,只有绕过读腿的输入(盘上 LKG / 手写 effective)到得了。
+
+### 修
+
+- `ModelEntry.headers?`(`src/types.ts`):`z.unknown().optional().transform(createFreeFormTransform("headers"))` —— 与 `compat` **同一只**
+  变换(本版把 `compat` 那段内联闭包提成包内私有的 `createFreeFormTransform(field)`,两键共用,不再各写一份):缺席不铸键;其余只过
+  `vetFreeFormJson` 自由形安全判(密钥形键 / 值、访问器、环、非 JSON、深于 `MAX_EXTRA_BODY_DEPTH`),拒句与 `compat` 逐字同形、只换字段名。
+- **不做形校验**:字符串 / 数组 / 数字 / `null` / 非规范大小写的名(`Anthropic-Beta`)/ 白名单外的名 / 非字符串值 / 写在不读它的线路上,
+  本包一律逐字过。头名闭集白名单 × 读它的线路 × 值形的判据**唯一属主是 sema-server**(坏声明 ⇒ 该条目整条不可用),本包复述一份必漂。
+- 登记进 `PARSE_TRANSPARENT_KEYS`(`models[].headers`,`since: "6.4.0"`,`validatedBy: "consumer"`)。`ParseTransparentValidator` 的
+  `consumer` 词注去掉了「丢掉坏的那一个键、保留宿主条目」这句处置描述 —— 坏值怎么处置是执法点自己的契约(`headers` 的执法点整条
+  条目不可用,`mcp.servers[].source` 的只丢标签),写在各登记行的 `why` 里,本包不替它定(规则少一条,不加新词)。
+- 同深度上限:`src/hash.ts` `MAX_EXTRA_BODY_DEPTH` 注文补 `headers`(与 `extraBody` / `compat` 同一个包裹深度,同一个上限)。
+- 文档:README「Declared-but-unvalidated keys」、`llms.txt` 解析透明键登记表段(4 员 → 5 员)、`llms-full.txt` 补 `headers`。README 同句
+  顺手订正:它把 `models[].extraBody` 列成解析透明键、把「the key's own guard」列成第三种校验方 —— 两处都与实现不符(`extraBody`
+  有自己的形门,不在登记表里;校验方闭集只有 `engine-ingest` / `consumer` 两词),改成与 `src/types.ts` 一致。
+
+### 红先 / 门
+
+- `test/model-headers-6.4.0.test.ts` 16 格,修前 15 红 1 绿(绿的是 ③ 负控):① 五条读腿逐字交出、零告警 ①b 写腿逐字落盘
+  ② 密钥形值 / 键(`sk-ant-…` / 私钥 PEM / `Bearer …` / 密钥形键 / 数组里的嵌套值)拒,拒句 = `compat` 拒句换字段名 ②b 五条读腿上与
+  `compat` 同一个处置(经 `buildEffective` 的四条腿逐条丢 `entry-dropped`、兄弟幸存;`getDomain` 整域净化后抛)、零回显
+  ③ 负控:不带 `headers` 的文档 effective / wire 的 `stableHash` 与 6.3.0 实测金样逐位相同 ④ 不做形校验 ⑤ `stableHash` 键序无关、
+  声明 / 换值改变哈希、恰在 `MAX_EXTRA_BODY_DEPTH` 收且包进 effective 可哈希、超一层拒(与 `compat` 同层)⑥ 登记行。
+- 解析透明键登记表门(`test/parse-transparent-keys.test.ts`,从 `DOMAIN_SCHEMAS` 行为派生、双向对拍)随新键自动覆盖。
+- conformance 两条新语料(`npm run conformance:bless` 加冕):`c48-s935-model-headers-transported`(三腿逐字交出、零告警;openai 线路上的
+  数组形 `headers` 照样过;无 `headers` 的条目不铸键)、`c49-s935-model-headers-secret-entry-dropped`(密钥形值 ⇒ 条目逐条丢、零回显,
+  `secrets` 已登记)。对 6.3.0 源码实测三腿同红(c48:2 处 effective 差 + 1 条多出的 `unknown-keys-dropped`;c49:6 处 effective 差、
+  缺 1 条 `entry-dropped`、多 1 条 `unknown-keys-dropped`);`firstRedOn` 留空(historical 阶梯证据真跑于入库之前,不手填,c41 同口径)。
+
+### 消费方
+
+- **sema-server 7.109.0 提货**:`config-provider.ts` `mapToServiceEffective` 加一行过境 `headers`,并把 `test/catalog-entry-headers.test.ts`
+  末段 🚧 S-931-schema 两格(「两条读腿今天剥掉 `headers`」)翻成「读腿逐字交出 `headers`」的正向钉、删该段 🚧。
+- center / TOC:`ModelEntry` 的推断类型多一个 `headers?: unknown`;不读它的消费方零改动。
+
 ## 6.3.0 — 2026-09-27 — 安全修(codex gpt-6-astra 对 v6.1.0 复审 [high],回填 D-4):可披露身份改白名单闭形 `DISCLOSABLE_IDENTITY_RE` · `redactSecrets` 整串判套在一处归一化上 · 告警坐标出门一道
 
 > **判档 = minor**(发版方裁,2026-09-27;原排 6.2.1 当日补丁):按 README「发版纪律」,新导出 `DISCLOSABLE_IDENTITY_RE` = minor

package/README.md

@@ -209,9 +209,12 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   rule the dropped-entry identity on read warnings already uses: the `DISCLOSABLE_IDENTITY_RE` allowlist ∧ not
   secret-shaped, 6.3.0).
 - **Declared-but-unvalidated keys** (`PARSE_TRANSPARENT_KEYS`, 2.0.0): the ONE registry of keys this package
-  carries verbatim WITHOUT checking their shape, each row naming who does check it (the engine's ingest side,
-  a consumer's projection, or the key's own guard). Today: `models[].extraBody`, `models[].compat` (1.10.0),
-  `mcp.servers[].source` (1.7.2), `mcp.servers[].toolFaces` (1.9.0), and an entitlement override's `value`.
+  carries verbatim WITHOUT checking their shape, each row naming who does check it (the engine's ingest side or
+  a consumer's enforcement point). Today: `models[].compat` (1.10.0), `models[].headers` (6.4.0; the header-name
+  allowlist × lane is sema-server's, not restated here), `mcp.servers[].source` (1.7.2), `mcp.servers[].toolFaces`
+  (1.9.0), and an entitlement override's `value`. `models[].extraBody` is NOT one of them — it has its own shape
+  gate (a plain JSON object); what it leaves open is the key vocabulary inside. `compat` / `headers` / `extraBody`
+  still clear the one free-form safety judgment (secret-shaped key/value, accessor, cycle, non-JSON, too deep ⇒ rejected).
 - **Extension namespaces** (`EXTENSION_NAMESPACES`, 1.5.0): keys another writer puts in a domain document by
   contract and this package deliberately does not model (today: the shell's entry-level `sema*` fields on
   `models`). They are still stripped, but they are NOT reported as unknown keys — intent is declared at the

package/conformance/VERSION

@@ -1 +1 @@
-6.3.0
+6.4.0

package/conformance/cases/c48-s935-model-headers-transported/expected.json

@@ -0,0 +1,115 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "models": [
+          {
+            "api": "anthropic-messages",
+            "apiKeyEnv": "ANTHROPIC_API_KEY",
+            "enabled": true,
+            "headers": {
+              "anthropic-beta": "context-1m-2025-08-07"
+            },
+            "id": "claude-x",
+            "name": "claude-1m",
+            "provider": "anthropic",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          },
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "headers": [
+              "Anthropic-Beta: not-a-header-bag"
+            ],
+            "id": "gw-id",
+            "name": "gw",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          },
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "plain-id",
+            "name": "plain",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          }
+        ],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "runtime": {},
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-01T00:00:00.000Z"
+    }
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 1883250445565322
+  }
+}

package/conformance/cases/c48-s935-model-headers-transported/input.json

@@ -0,0 +1,37 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-01T00:00:00.000Z"
+  },
+  "domains": {
+    "models": {
+      "models": [
+        {
+          "name": "claude-1m",
+          "provider": "anthropic",
+          "api": "anthropic-messages",
+          "id": "claude-x",
+          "apiKeyEnv": "ANTHROPIC_API_KEY",
+          "headers": {
+            "anthropic-beta": "context-1m-2025-08-07"
+          }
+        },
+        {
+          "name": "gw",
+          "provider": "openai",
+          "id": "gw-id",
+          "apiKeyEnv": "OPENAI_API_KEY",
+          "headers": [
+            "Anthropic-Beta: not-a-header-bag"
+          ]
+        },
+        {
+          "name": "plain",
+          "provider": "openai",
+          "id": "plain-id",
+          "apiKeyEnv": "OPENAI_API_KEY"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c48-s935-model-headers-transported/meta.json

@@ -0,0 +1,6 @@
+{
+  "contributor": "contract",
+  "claim": "S-935(6.4.0):`models[].headers` 是解析透明键(与 `compat` 同一只变换)⇒ 三读腿**逐字交出、零告警**,不剥、不报 `unknown-keys-dropped`;并且本包**不做形校验** —— 写在 openai 线路上的数组形 `headers`(非规范大小写的名、根本不是头袋)照样逐字过,形与线路归 sema-server 的目录条目判据。任一腿把它剥掉,经生产配置通道写下的附加请求头(开 1M 上下文的 `anthropic-beta`)就到不了 server 目录且零告警;任一腿对它做形校验,就是本包复述了 server 的白名单(两个写者)。第三条不带 `headers` 的条目是负控:不铸键。",
+  "firstRedOn": [],
+  "note": "车SL(2026-10-01)红先:6.3.0 读腿在本条上三腿同红 —— 两条带 `headers` 的条目都被剥掉该键,`unknown-keys-dropped` 点名 `[\"models\",0,\"headers\"]` / `[\"models\",1,\"headers\"]`(实测读数见车SL 收车档)。firstRedOn 为空:`conformance/historical/` 的阶梯证据(2.1.0 及更早)真跑于本条入库之前,没有本条的读数,那一栏只收 historical 真跑,不手填(c41 同口径)。"
+}

package/conformance/cases/c49-s935-model-headers-secret-entry-dropped/expected.json

@@ -0,0 +1,98 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "models": [
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "gw-id",
+            "name": "gw",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          }
+        ],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "runtime": {},
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "models",
+        "identity": {
+          "id": "claude-x",
+          "name": "claude-1m"
+        },
+        "kind": "entry-dropped",
+        "path": [
+          "models",
+          0
+        ]
+      }
+    ],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-01T00:00:00.000Z"
+    }
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 496785931148953
+  }
+}

package/conformance/cases/c49-s935-model-headers-secret-entry-dropped/input.json

@@ -0,0 +1,28 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-01T00:00:00.000Z"
+  },
+  "domains": {
+    "models": {
+      "models": [
+        {
+          "name": "claude-1m",
+          "provider": "anthropic",
+          "api": "anthropic-messages",
+          "id": "claude-x",
+          "apiKeyEnv": "ANTHROPIC_API_KEY",
+          "headers": {
+            "x-api-key": "sk-ant-api03-FAKES935CORPUS000000000000000000"
+          }
+        },
+        {
+          "name": "gw",
+          "provider": "openai",
+          "id": "gw-id",
+          "apiKeyEnv": "OPENAI_API_KEY"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c49-s935-model-headers-secret-entry-dropped/meta.json

@@ -0,0 +1,9 @@
+{
+  "contributor": "contract",
+  "claim": "S-935(6.4.0):`models[].headers` 里粘了一把密钥形值(`x-api-key: sk-ant-…`)⇒ 与 `compat` 同一只自由形安全判据拒 ⇒ 该条目**逐条丢**(`entry-dropped`,坐标 `[\"models\",0]`)、兄弟条目幸存、告警面零回显那把钥匙。打的是两种读错:① 腿把 `headers` 当未知键剥掉(6.3.0 形)⇒ 条目带着「看起来干净」的形幸存,明文凭据却已经进了持久层且没人拒;② 腿对 `headers` 另起一套判据(或把拒句拼上值)⇒ 告警面带出密钥。",
+  "firstRedOn": [],
+  "secrets": [
+    "sk-ant-api03-FAKES935CORPUS000000000000000000"
+  ],
+  "note": "车SL(2026-10-01)红先:6.3.0 读腿在本条上三腿同红 —— 条目幸存(`headers` 被剥)+ `unknown-keys-dropped` 点名 `[\"models\",0,\"headers\"]`,没有 `entry-dropped`(实测读数见车SL 收车档)。firstRedOn 为空:同 c48 / c41 口径(historical 阶梯证据真跑于本条入库之前,不手填)。"
+}

package/dist/hash.d.ts

@@ -23,9 +23,9 @@ export declare const MAX_HASH_WRAPPER_RESERVE = 32;
 /** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
  *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
  *  real free-form value (OpenAI-style request params nest <10 deep).
- *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
- *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
- *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody`, since 1.10.0
+ *  `ModelEntry.compat`, since 6.4.0 `ModelEntry.headers`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`),
+ *  so one cap serves them all. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
  *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export declare const MAX_EXTRA_BODY_DEPTH: number;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */

package/dist/hash.js

@@ -23,9 +23,9 @@ export const MAX_HASH_WRAPPER_RESERVE = 32;
 /** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
  *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
  *  real free-form value (OpenAI-style request params nest <10 deep).
- *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
- *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
- *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody`, since 1.10.0
+ *  `ModelEntry.compat`, since 6.4.0 `ModelEntry.headers`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`),
+ *  so one cap serves them all. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
  *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export const MAX_EXTRA_BODY_DEPTH = MAX_HASH_DEPTH - MAX_HASH_WRAPPER_RESERVE;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */

package/dist/hooks.d.ts

@@ -5545,20 +5545,20 @@ export declare const HttpHookEntry: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }>;
 /** One configured hook (CC settings shape + shell superset fields; discriminated on `type`). */
@@ -5655,20 +5655,20 @@ export declare const HookEntry: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }>]>;
 export type HookEntry = z.infer<typeof HookEntry>;
@@ -5773,20 +5773,20 @@ export declare const HookMatcherEntry: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     }, {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -5819,11 +5819,11 @@ export declare const HookMatcherEntry: z.ZodObject<{
     } | {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     })[];
     matcher?: string | undefined;
@@ -5857,11 +5857,11 @@ export declare const HookMatcherEntry: z.ZodObject<{
     } | {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     })[];
     matcher?: string | undefined;

package/dist/types.d.ts

@@ -117,7 +117,8 @@ export declare const SealedApiKey: z.ZodObject<{
 export type SealedApiKey = z.infer<typeof SealedApiKey>;
 /** 谁来校验一个**解析透明键**的形。闭集:新增一员要在这里加词,穷举消费方即编译红。
  *  · `engine-ingest` —— 引擎摄入侧单点校验(不合形的那一条不挂并通告一次);
- *  · `consumer`      —— 消费方的投影/执法点(丢掉坏的那一个键、保留其宿主条目、记账)。 */
+ *  · `consumer`      —— 消费方的投影/执法点。坏值怎么处置(只丢那一个键 / 整条宿主条目不可用)是那个执法点自己的
+ *                      契约,写在登记行的 `why` 里 —— 本包不替它定。 */
 export type ParseTransparentValidator = "engine-ingest" | "consumer";
 /** {@link PARSE_TRANSPARENT_KEYS} 的一行。 */
 export interface ParseTransparentKey {
@@ -247,6 +248,16 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
      *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
      *  enter the persisted config and `stableHash` (R18). */
     compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+    /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+     *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+     *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+     *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+     *  `extraBody` ({@link vetFreeFormJson}). */
+    headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -283,6 +294,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
     compat?: unknown;
+    headers?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -313,6 +325,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: unknown;
     compat?: unknown;
+    headers?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -347,6 +360,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
     compat?: unknown;
+    headers?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -377,6 +391,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: unknown;
     compat?: unknown;
+    headers?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -585,6 +600,16 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
          *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
          *  enter the persisted config and `stableHash` (R18). */
         compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+        /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+         *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+         *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+         *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+         *  ABSENT = key not minted = today's behaviour, zero migration.
+         *
+         *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+         *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+         *  `extraBody` ({@link vetFreeFormJson}). */
+        headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
         /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
          *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
         quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -621,6 +646,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -651,6 +677,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -685,6 +712,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -715,6 +743,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -839,6 +868,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -894,6 +924,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -953,6 +984,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -1008,6 +1040,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -9501,6 +9534,16 @@ export declare const DOMAIN_SCHEMAS: {
              *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
              *  enter the persisted config and `stableHash` (R18). */
             compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+            /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+             *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+             *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+             *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+             *  ABSENT = key not minted = today's behaviour, zero migration.
+             *
+             *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+             *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+             *  `extraBody` ({@link vetFreeFormJson}). */
+            headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
             /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
              *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
             quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -9537,6 +9580,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9567,6 +9611,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9601,6 +9646,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9631,6 +9677,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9755,6 +9802,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9810,6 +9858,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9869,6 +9918,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9924,6 +9974,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;

package/dist/types.js

@@ -201,9 +201,9 @@ export function extraBodyUnsafe(v) {
     }
     return false;
 }
-/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`
- *  and `ModelEntry.compat` share this ONE function (1.10.0; before that it was inline in `extraBody` and a second
- *  free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
+/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`,
+ *  `ModelEntry.compat` and `ModelEntry.headers` share this ONE function (1.10.0; before that it was inline in `extraBody`
+ *  and a second free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
  *
  *   1. getter-free descriptor walk ({@link extraBodyUnsafe}) over the RAW value — never invokes a getter, and any
  *      reflective throw (a hostile Proxy trap could throw a secret-bearing message) collapses into a FIXED message;
@@ -234,6 +234,22 @@ function vetFreeFormJson(v, field) {
         return { ok: false, message: `${field}: its serialized form carries a secret` };
     return { ok: true, value: clone };
 }
+/** The transform of every **parse-transparent free-form** key (`z.unknown().optional().transform(createFreeFormTransform(field))`:
+ *  `ModelEntry.compat` / `ModelEntry.headers`) — ONE closure, so those keys cannot drift apart: absent stays absent (key not
+ *  minted); anything else is the {@link vetFreeFormJson} safety judgment and nothing more (no SHAPE rule — whose job that is,
+ *  per key, is {@link PARSE_TRANSPARENT_KEYS}). `extraBody` is not one of these: it has its own shape gate first. */
+function createFreeFormTransform(field) {
+    return (v, ctx) => {
+        if (v === undefined)
+            return undefined;
+        const vetted = vetFreeFormJson(v, field);
+        if (!vetted.ok) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
+            return z.NEVER;
+        }
+        return vetted.value;
+    };
+}
 /** A k8s resource quantity ("250m", "1", "0.5", "512Mi", "1Gi", "128M") — catches garbage at config-submit
  *  rather than surfacing as a reconcile ApplyError at the apiserver (consistent with ENV_NAME/DURATION guards). */
 export const K8S_QUANTITY = z.string().regex(/^\d+(\.\d+)?(m|[kKMGTPE]i?)?$/, 'must be a k8s quantity like "250m", "512Mi", "1Gi"');
@@ -313,6 +329,13 @@ export const PARSE_TRANSPARENT_KEYS = [
         validatedBy: "engine-ingest",
         why: "镜像引擎的 per-model wire-compat 声明(thinkingFormat 等五键);那张词表随引擎走,本包复述一份必漂。",
     },
+    {
+        domain: "models",
+        path: "models[].headers",
+        since: "6.4.0",
+        validatedBy: "consumer",
+        why: "部署 ↔ 供应商的 per-model 附加请求头;判据(头名闭集白名单 × 读它的线路 × 值形)的唯一属主是 server 的目录条目判据(坏声明 ⇒ 该条目整条不可用,不是丢头照常),本包复述一份那张表必漂、两处各一份就是两个写者。",
+    },
     {
         domain: "mcp",
         path: "servers[].source",
@@ -424,16 +447,20 @@ export const ModelEntry = z.object({
     compat: z
         .unknown()
         .optional()
-        .transform((v, ctx) => {
-        if (v === undefined)
-            return undefined;
-        const vetted = vetFreeFormJson(v, "compat");
-        if (!vetted.ok) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
-            return z.NEVER;
-        }
-        return vetted.value;
-    }),
+        .transform(createFreeFormTransform("compat")),
+    /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+     *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+     *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+     *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+     *  `extraBody` ({@link vetFreeFormJson}). */
+    headers: z
+        .unknown()
+        .optional()
+        .transform(createFreeFormTransform("headers")),
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.number().finite().nonnegative().default(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",