@sema-agent/settings-schema 12.3.0 → 13.0.0

package/dist/mcp-server-policy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * MCP 服务器名单判决(13.0.0,U6 / S-1626;cli [10720] 候包口)—— 托管 / 用户的 `allowedMcpServers` / `deniedMcpServers` 拦下一台 MCP
+ * 服务器时「为什么」的**唯一**判官。纯函数,浏览器安全。与 U3 `httpHookUrlVerdict` 同形:放行 ⇒ `undefined`;拦下 ⇒ {@link McpPolicyBlock}
+ * —— 判官出结构不出句,壳 / server / web-admin 只渲结构、不各自造句。
+ *
+ * 判法(锚 = cli main ceff8bc6 `mcpServerPolicyBlock`,它与 CC 2.1.296 名单判法逐支一致;URL 条目按本包 `url-pattern` 两只出口判):
+ *  - 拒绝名单**绝对优先**,各层都算(用户可以替自己拒):名字条目 → 命令条目(只对 stdio,整数组逐项相等)→ URL 条目(只对远端,拒绝出口)。
+ *  - 允许名单:各层写的拼成一张(CC「Arrays merge across settings sources」);托管层(源表 `SETTINGS_SOURCE_CONTRACT` 档 = `managed` 的源,
+ *    经 `settingsSourceContract` 查 —— 调用方不给档)写了 `allowManagedMcpServersOnly: true` ⇒ 只读托管层那一张(别层写的这个开关不生效)。没有一层写 ⇒ 不限;空 ⇒ 一台都不许;
+ *    stdio 且名单里有命令条目 ⇒ 必须命中其一;远端且名单里有 URL 条目 ⇒ 必须命中其一(放行出口);否则按名字。
+ *  - SDK 型等「不由宿主连接」的条目是否豁免,归调用方(cli 的过滤口豁免、盘上加载器不豁免 —— 那是接线,不是判法)。
+ *
+ * **目标零展开**(cli X-T1 同律):判官**判**的是宿主展开环境变量 / 用户配置之后的连接目标(`server.target` —— 真连的就是它,按写法判会让
+ * `${URL}` 绕过拒绝名单),**回显**的只有展开前的写法(`server.written`);stdio 只回显可执行名与参数个数(参数原文常常就是凭据)。
+ * 展开值不进 {@link McpPolicyBlock} 的任何字段。
+ */
+import { type SettingsSource } from "./settings-sources.js";
+/** 两张名单的键(闭集,声明序)。 */
+export declare const MCP_SERVER_LIST_KEYS: readonly ["allowedMcpServers", "deniedMcpServers"];
+export type McpServerListKey = (typeof MCP_SERVER_LIST_KEYS)[number];
+/** 名单里的一条:恰好一种 —— 按名字、按 stdio 命令数组(整数组逐项相等)、按 URL 模式(`url-pattern`)。 */
+export type McpServerListEntry = {
+    readonly serverName: string;
+} | {
+    readonly serverCommand: readonly string[];
+} | {
+    readonly serverUrl: string;
+};
+/** 一台服务器的连接目标:stdio = `[可执行, ...参数]`,远端 = URL。 */
+export type McpServerTarget = {
+    readonly kind: "command";
+    readonly command: readonly string[];
+} | {
+    readonly kind: "url";
+    readonly url: string;
+};
+/** 被判的那一台。`target` 缺席 = 判官只按名字判(类型不明 / 宿主不连接的条目)。`written` 缺席 = 宿主没有展开前的写法(那时只回显种类)。 */
+export interface McpPolicyServer {
+    readonly name: string;
+    /** 宿主真连的目标(展开之后)—— 只用来判,不回显。 */
+    readonly target?: McpServerTarget;
+    /** 同一目标展开之前的写法 —— 回显的唯一来源。种类与 `target` 不符 ⇒ 不回显。 */
+    readonly written?: McpServerTarget;
+}
+/** 一个设置层的两张名单读数。`source` = 这一层是哪个设置源(闭集 `SETTINGS_SOURCES`,原样回显进 `sources`;托管层由源表认,调用方不给档)。 */
+export interface McpPolicyLayer {
+    readonly source: SettingsSource;
+    readonly allowedMcpServers?: readonly McpServerListEntry[];
+    readonly deniedMcpServers?: readonly McpServerListEntry[];
+    readonly allowManagedMcpServersOnly?: boolean;
+}
+/** 没过的那一条的种类(闭集)。拒绝名单:命中的条目种类;允许名单:必须命中而没命中的条目种类,`empty` = 允许名单是空数组。 */
+export declare const MCP_POLICY_RULES: readonly ["name", "command", "url", "empty"];
+export type McpPolicyRule = (typeof MCP_POLICY_RULES)[number];
+/** 一台 MCP 服务器被名单拦下的原因(六字段,零句子)。 */
+export interface McpPolicyBlock {
+    /** 配置里的原名。 */
+    readonly name: string;
+    /** 判下它的那张名单(拒绝名单优先)。 */
+    readonly list: McpServerListKey;
+    readonly rule: McpPolicyRule;
+    /** 判官判的那种身份 —— 只有种类,不带值。 */
+    readonly target: McpServerTarget["kind"] | "none";
+    /** 展开前的写法:URL 原样;stdio 只给可执行名与参数个数。宿主没给写法(或种类不符)⇒ `undefined`(键恒在)。 */
+    readonly written: {
+        readonly url: string;
+    } | {
+        readonly command: string;
+        readonly argCount: number;
+    } | undefined;
+    /** 携带判下它的那张名单的设置层(入参序):拒绝 ⇒ 携带命中条目的层;允许 ⇒ 写了参与判决的允许名单的层。 */
+    readonly sources: readonly SettingsSource[];
+}
+/** 名单对这一台的判决:放行 ⇒ `undefined`;拦下 ⇒ 原因(判法见文件头)。 */
+export declare function mcpServerPolicyVerdict(server: McpPolicyServer, layers: readonly McpPolicyLayer[]): McpPolicyBlock | undefined;

package/dist/mcp-server-policy.js

@@ -0,0 +1,84 @@
+/**
+ * MCP 服务器名单判决(13.0.0,U6 / S-1626;cli [10720] 候包口)—— 托管 / 用户的 `allowedMcpServers` / `deniedMcpServers` 拦下一台 MCP
+ * 服务器时「为什么」的**唯一**判官。纯函数,浏览器安全。与 U3 `httpHookUrlVerdict` 同形:放行 ⇒ `undefined`;拦下 ⇒ {@link McpPolicyBlock}
+ * —— 判官出结构不出句,壳 / server / web-admin 只渲结构、不各自造句。
+ *
+ * 判法(锚 = cli main ceff8bc6 `mcpServerPolicyBlock`,它与 CC 2.1.296 名单判法逐支一致;URL 条目按本包 `url-pattern` 两只出口判):
+ *  - 拒绝名单**绝对优先**,各层都算(用户可以替自己拒):名字条目 → 命令条目(只对 stdio,整数组逐项相等)→ URL 条目(只对远端,拒绝出口)。
+ *  - 允许名单:各层写的拼成一张(CC「Arrays merge across settings sources」);托管层(源表 `SETTINGS_SOURCE_CONTRACT` 档 = `managed` 的源,
+ *    经 `settingsSourceContract` 查 —— 调用方不给档)写了 `allowManagedMcpServersOnly: true` ⇒ 只读托管层那一张(别层写的这个开关不生效)。没有一层写 ⇒ 不限;空 ⇒ 一台都不许;
+ *    stdio 且名单里有命令条目 ⇒ 必须命中其一;远端且名单里有 URL 条目 ⇒ 必须命中其一(放行出口);否则按名字。
+ *  - SDK 型等「不由宿主连接」的条目是否豁免,归调用方(cli 的过滤口豁免、盘上加载器不豁免 —— 那是接线,不是判法)。
+ *
+ * **目标零展开**(cli X-T1 同律):判官**判**的是宿主展开环境变量 / 用户配置之后的连接目标(`server.target` —— 真连的就是它,按写法判会让
+ * `${URL}` 绕过拒绝名单),**回显**的只有展开前的写法(`server.written`);stdio 只回显可执行名与参数个数(参数原文常常就是凭据)。
+ * 展开值不进 {@link McpPolicyBlock} 的任何字段。
+ */
+import { settingsSourceContract } from "./settings-sources.js";
+import { urlAllowPatternMatches, urlDenyPatternMatches } from "./url-pattern.js";
+/** 两张名单的键(闭集,声明序)。 */
+export const MCP_SERVER_LIST_KEYS = ["allowedMcpServers", "deniedMcpServers"];
+/** 没过的那一条的种类(闭集)。拒绝名单:命中的条目种类;允许名单:必须命中而没命中的条目种类,`empty` = 允许名单是空数组。 */
+export const MCP_POLICY_RULES = ["name", "command", "url", "empty"];
+const isName = (e) => "serverName" in e && e.serverName !== undefined;
+const isCommand = (e) => "serverCommand" in e && e.serverCommand !== undefined;
+const isUrl = (e) => "serverUrl" in e && e.serverUrl !== undefined;
+const sameCommand = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/** 拒绝名单里一条是否按 `rule` 这一种命中这一台。 */
+function denyHit(rule, entry, server) {
+    switch (rule) {
+        case "name":
+            return isName(entry) && entry.serverName === server.name;
+        case "command":
+            return server.target?.kind === "command" && isCommand(entry) && sameCommand(entry.serverCommand, server.target.command);
+        case "url":
+            return server.target?.kind === "url" && isUrl(entry) && urlDenyPatternMatches(server.target.url, entry.serverUrl);
+        default: {
+            const unknown = rule;
+            throw new RangeError(`mcpServerPolicyVerdict: unknown deny rule '${String(unknown)}'`);
+        }
+    }
+}
+/** 拼好的允许名单对这一台:放行 ⇒ `undefined`;否则必须命中而没命中的那一种。 */
+function allowMiss(entries, server) {
+    if (entries.length === 0)
+        return "empty";
+    const target = server.target;
+    if (target?.kind === "command" && entries.some(isCommand)) {
+        return entries.some((e) => isCommand(e) && sameCommand(e.serverCommand, target.command)) ? undefined : "command";
+    }
+    if (target?.kind === "url" && entries.some(isUrl)) {
+        return entries.some((e) => isUrl(e) && urlAllowPatternMatches(target.url, e.serverUrl)) ? undefined : "url";
+    }
+    return entries.some((e) => isName(e) && e.serverName === server.name) ? undefined : "name";
+}
+function writtenOf(server) {
+    const w = server.written;
+    if (w === undefined || w.kind !== server.target?.kind)
+        return undefined;
+    return w.kind === "url" ? { url: w.url } : { command: w.command[0] ?? "", argCount: Math.max(0, w.command.length - 1) };
+}
+/** 名单对这一台的判决:放行 ⇒ `undefined`;拦下 ⇒ 原因(判法见文件头)。 */
+export function mcpServerPolicyVerdict(server, layers) {
+    // 每一层先过源表(闭集外的源在这里响亮抛,哪怕那一层什么都没写);托管 ⇔ 源表档 = managed。
+    const managed = new Set(layers.filter((l) => settingsSourceContract(l.source).trust === "managed"));
+    const block = (list, rule, sources) => ({
+        name: server.name,
+        list,
+        rule,
+        target: server.target?.kind ?? "none",
+        written: writtenOf(server),
+        sources,
+    });
+    for (const rule of ["name", "command", "url"]) {
+        const sources = layers.filter((l) => (l.deniedMcpServers ?? []).some((e) => denyHit(rule, e, server))).map((l) => l.source);
+        if (sources.length > 0)
+            return block("deniedMcpServers", rule, sources);
+    }
+    const managedOnly = layers.some((l) => managed.has(l) && l.allowManagedMcpServersOnly === true);
+    const allowLayers = layers.filter((l) => l.allowedMcpServers !== undefined && (!managedOnly || managed.has(l)));
+    if (allowLayers.length === 0)
+        return undefined;
+    const miss = allowMiss(allowLayers.flatMap((l) => l.allowedMcpServers), server);
+    return miss === undefined ? undefined : block("allowedMcpServers", miss, allowLayers.map((l) => l.source));
+}

package/dist/safety-merge-spec.d.ts

@@ -90,9 +90,9 @@ export declare function isAtLeast(layer: MinTrust, minTrust: MinTrust): boolean;
  *  that would otherwise ask/deny — a privilege, so it needs trust; `tighten` = only ever narrows — restricting is
  *  safe from anyone, so any settings-file layer may add it. The word is what a consumer branches on for the
  *  NOT-admitted outlet: the ruling REQUIRES a consumer to turn a `loosen` member below its floor into a pending
- *  suggestion (consent flow) rather than drop it silently. This package returns that metadata only — it performs
- *  no admission and no degradation; whether a given consumer version implements the outlet is that consumer's
- *  contract. */
+ *  suggestion (consent flow) rather than drop it silently. This package returns that metadata, and `layerAdmission`
+ *  (`settings-sources.ts`) reads it per settings layer; it performs no degradation — whether a given consumer version
+ *  implements the outlet is that consumer's contract. */
 export declare const MemberDirection: z.ZodEnum<{
     loosen: "loosen";
     tighten: "tighten";
@@ -524,6 +524,16 @@ export declare const SAFETY_MERGE_SPEC: {
         readonly fail: "closed";
         readonly seam: "web-admin → governanceBaseline (SSO/SCIM/audit/budget, TOB-only)";
     };
+    readonly httpHookAllowlists: {
+        readonly mergeShape: "denyFirst";
+        readonly minTrust: "global";
+        readonly tighten: {
+            readonly rule: "setNarrower";
+        };
+        readonly enforcement: "resolver";
+        readonly fail: "closed";
+        readonly seam: "http hook URL / header-env allowlists (httpHookUrlVerdict / httpHookEnvVarsAllowed)";
+    };
 };
 export type SafetyMergeCategory = keyof typeof SAFETY_MERGE_SPEC;
 /** The members a category declares, as a CLOSED SET TYPE: `"allow" | "deny" | "ask"` for `permissions`, `never` for

package/dist/safety-merge-spec.js

@@ -90,9 +90,9 @@ export function isAtLeast(layer, minTrust) {
  *  that would otherwise ask/deny — a privilege, so it needs trust; `tighten` = only ever narrows — restricting is
  *  safe from anyone, so any settings-file layer may add it. The word is what a consumer branches on for the
  *  NOT-admitted outlet: the ruling REQUIRES a consumer to turn a `loosen` member below its floor into a pending
- *  suggestion (consent flow) rather than drop it silently. This package returns that metadata only — it performs
- *  no admission and no degradation; whether a given consumer version implements the outlet is that consumer's
- *  contract. */
+ *  suggestion (consent flow) rather than drop it silently. This package returns that metadata, and `layerAdmission`
+ *  (`settings-sources.ts`) reads it per settings layer; it performs no degradation — whether a given consumer version
+ *  implements the outlet is that consumer's contract. */
 export const MemberDirection = z.enum(["loosen", "tighten"]);
 /** One member's admission row. `minTrust` ABSENT ⇒ the category's `minTrust` applies: a row can refine the floor
  *  only by SAYING so; omission never lowers it (fail-closed by construction).
@@ -232,6 +232,13 @@ export const SAFETY_MERGE_SPEC = {
     autoCompaction: { mergeShape: "replace", minTrust: "session", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "compaction config" },
     ui: { mergeShape: "replace", minTrust: "local", tighten: { rule: "none" }, enforcement: "client", fail: "open", seam: "shell-only (theme/keybindings/statusLine) — never touches the engine" },
     org: { mergeShape: "replace", minTrust: "managed", tighten: { rule: "none" }, enforcement: "server", fail: "closed", seam: "web-admin → governanceBaseline (SSO/SCIM/audit/budget, TOB-only)" },
+    // 13.0.0 (U3 [10538]) — the http hook allowlists `allowedHttpHookUrls` / `httpHookAllowedEnvVars`. Every ADMITTED layer's list must
+    // pass (layers INTERSECT: a lower layer can only narrow, never add a URL the managed list lacks — CC concatenates, which lets it);
+    // admitted = `layerAdmission(source, workspace, "httpHookAllowlists") === "admitted"` — the source's tier (SETTINGS_SOURCE_CONTRACT) reaches
+    // this floor, global (user / flag / managed) — because a repo-controllable `[]` would silence the user's own http GUARD hooks — a
+    // tightening word with a loosening consequence, the same boundary as sandboxNetwork.failIfUnavailable. Read and judged by
+    // ./http-hook-allowlists (`httpHookUrlVerdict` / `httpHookEnvVarsAllowed`); not `sandboxNetwork` (that row is enforcement:"gate").
+    httpHookAllowlists: { mergeShape: "denyFirst", minTrust: "global", tighten: { rule: "setNarrower" }, enforcement: "resolver", fail: "closed", seam: "http hook URL / header-env allowlists (httpHookUrlVerdict / httpHookEnvVarsAllowed)" },
 };
 /** Own-property table lookup. The category union is compile-time only; a JavaScript or deserialized caller can
  *  hand in `"__proto__"` / `"constructor"` / `"toString"`, which a bare index resolves through Object.prototype

package/dist/settings-sources.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Settings SOURCES and the ONE layer-admission function.
+ *
+ * `SAFETY_MERGE_SPEC` answers "how trusted must a layer be to set this category / member, and which way does it move the unattended
+ * surface" (floor + direction); `trustRank` / `isAtLeast` are the ladder. What was missing is the LAYER side: which settings sources
+ * there are, which trust tier each one carries, which of them a repository controls, and what an untrusted workspace does to them —
+ * every host kept its own table for that. This file is that table, plus the one function a resolver asks per layer × key.
+ *
+ * THE RULE (one, no per-key special case): a repository-controllable source (`projectSettings` / `localSettings` — a clone brings or the
+ * repository's tooling writes them) in a workspace whose trust reading is not `accepted` admits only the members whose published
+ * direction is `"tighten"`; everything it may otherwise set is `trust_withheld`. In every case the source's tier must reach the floor
+ * (`isAtLeast(tier, floor)`), checked first — a write below its floor is `below_trust_floor` whether or not the workspace is trusted, which
+ * also keeps the loose pole of a value-directional (`boolPole`) member out of an untrusted layer. The `direction` data already says which
+ * keys an untrusted repository may still set (restricting needs no trust); there is no per-row workspace column (that would copy a
+ * layer fact into every category row).
+ *
+ * CC 2.1.296 (the reference): trust is one per-session boolean (a non-interactive session counts as trusted, `cli296.js:238351`); keys split
+ * into the operator tier `policy / flag / user` and the repository-controllable tier `project / local` ("projectSettings and
+ * localSettings are repo-controllable", `:237757`); merge order user < project < local < flag < policy (`:237339`).
+ * The local layer sits in the project tier here too: a `.local` settings file is gitignored, so a clone cannot bring one, and whoever can
+ * write it can write the project file next to it — "local below project" was never a written rule (it arrived with the first import of the
+ * table) and holds no threat model. The category rows (`hooks` / `env` / `mcpServers` / `rulesInstructions` at `minTrust: "project"`) and
+ * the ladder numbers are untouched: the change is on the source's tier, not on any row.
+ *
+ * NOT here (each has its own place): the hooks EXECUTION gate (`declined` ⇒ no hook from any layer runs) is contract text in `./hooks`'
+ * header and executes in the client core; the workspace trust RECORD (where "this folder was accepted" is stored) is host state.
+ */
+import { type MinTrust, type SafetyMergeCategory, type SafetyMergeMember } from "./safety-merge-spec.js";
+/** The settings sources, in MERGE order (a later source overrides an earlier one where a category's merge shape lets it):
+ *  user < project < local < flag < policy. `flagSettings` = settings handed in at launch (`--settings <file|json>`, an SDK embedder's inline
+ *  settings); `policySettings` = managed. */
+export declare const SETTINGS_SOURCES: readonly ["userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings"];
+export type SettingsSource = (typeof SETTINGS_SOURCES)[number];
+/** One source's admission facts: its trust tier (a {@link MinTrust} word, compared with `isAtLeast` against a floor) and whether a
+ *  repository controls it (⇒ subject to the workspace trust reading). */
+export interface SettingsSourceContract {
+    readonly trust: MinTrust;
+    readonly repoControllable: boolean;
+}
+/**
+ * The source table. `flagSettings` is in the operator tier (`global`, not repository-controllable) like CC's: settings handed in at launch are
+ * the launcher's own act — an SDK embedder or a wrapper script — not something a repository brings (a wrapper that turns repository content
+ * into `--settings` makes that choice itself).
+ */
+export declare const SETTINGS_SOURCE_CONTRACT: {
+    readonly userSettings: {
+        readonly trust: "global";
+        readonly repoControllable: false;
+    };
+    readonly projectSettings: {
+        readonly trust: "project";
+        readonly repoControllable: true;
+    };
+    readonly localSettings: {
+        readonly trust: "project";
+        readonly repoControllable: true;
+    };
+    readonly flagSettings: {
+        readonly trust: "global";
+        readonly repoControllable: false;
+    };
+    readonly policySettings: {
+        readonly trust: "managed";
+        readonly repoControllable: false;
+    };
+};
+/**
+ * The ONE lookup of {@link SETTINGS_SOURCE_CONTRACT}: a source's tier and whether a repository controls it. Every function in this package
+ * that needs a layer's tier reads it here ({@link layerAdmission}, the http hook allowlist judge, the MCP server list verdict) — none takes a
+ * tier from its caller. An unknown source (prototype names included) ⇒ RangeError, never a fallback tier.
+ */
+export declare function settingsSourceContract(source: SettingsSource): SettingsSourceContract;
+/**
+ * The host's reading of the workspace trust decision: `accepted` (the user accepted this folder), `declined` (the user did not, or the
+ * host must assume so), `no_trust_step` (the host has no trust step at all). A host whose reading throws or yields a word outside this set
+ * passes `declined`; this package's functions refuse an unknown word loudly rather than reading it as any tier.
+ */
+export declare const WORKSPACE_TRUST_STATES: readonly ["accepted", "declined", "no_trust_step"];
+export type WorkspaceTrustState = (typeof WORKSPACE_TRUST_STATES)[number];
+/** What {@link layerAdmission} answers (closed): `admitted`; `trust_withheld` = would be admitted once the workspace is `accepted`;
+ *  `below_trust_floor` = this source can never set it (its tier is below the floor). */
+export declare const LAYER_ADMISSION_VERDICTS: readonly ["admitted", "trust_withheld", "below_trust_floor"];
+export type LayerAdmissionVerdict = (typeof LAYER_ADMISSION_VERDICTS)[number];
+/**
+ * Does a value from `source` for `category` (or one of its declared `member`s; `value` = the candidate value, for a value-directional member)
+ * enter the effective settings, given the workspace trust reading? The rule is in the file header; the data is {@link SETTINGS_SOURCE_CONTRACT}
+ * and `SAFETY_MERGE_SPEC` (floors and directions through `memberAdmission`). Omitting `member` asks about the category as a whole key (a
+ * memberized category's undeclared sub-keys are asked this way: category floor, no direction).
+ * Unknown source / trust reading / category, a member named on a whole-key category, or an undeclared member ⇒ RangeError (never a fallback).
+ */
+export declare function layerAdmission<C extends SafetyMergeCategory>(source: SettingsSource, workspace: WorkspaceTrustState, category: C, member?: SafetyMergeMember<C>, value?: unknown): LayerAdmissionVerdict;

package/dist/settings-sources.js

@@ -0,0 +1,107 @@
+/**
+ * Settings SOURCES and the ONE layer-admission function.
+ *
+ * `SAFETY_MERGE_SPEC` answers "how trusted must a layer be to set this category / member, and which way does it move the unattended
+ * surface" (floor + direction); `trustRank` / `isAtLeast` are the ladder. What was missing is the LAYER side: which settings sources
+ * there are, which trust tier each one carries, which of them a repository controls, and what an untrusted workspace does to them —
+ * every host kept its own table for that. This file is that table, plus the one function a resolver asks per layer × key.
+ *
+ * THE RULE (one, no per-key special case): a repository-controllable source (`projectSettings` / `localSettings` — a clone brings or the
+ * repository's tooling writes them) in a workspace whose trust reading is not `accepted` admits only the members whose published
+ * direction is `"tighten"`; everything it may otherwise set is `trust_withheld`. In every case the source's tier must reach the floor
+ * (`isAtLeast(tier, floor)`), checked first — a write below its floor is `below_trust_floor` whether or not the workspace is trusted, which
+ * also keeps the loose pole of a value-directional (`boolPole`) member out of an untrusted layer. The `direction` data already says which
+ * keys an untrusted repository may still set (restricting needs no trust); there is no per-row workspace column (that would copy a
+ * layer fact into every category row).
+ *
+ * CC 2.1.296 (the reference): trust is one per-session boolean (a non-interactive session counts as trusted, `cli296.js:238351`); keys split
+ * into the operator tier `policy / flag / user` and the repository-controllable tier `project / local` ("projectSettings and
+ * localSettings are repo-controllable", `:237757`); merge order user < project < local < flag < policy (`:237339`).
+ * The local layer sits in the project tier here too: a `.local` settings file is gitignored, so a clone cannot bring one, and whoever can
+ * write it can write the project file next to it — "local below project" was never a written rule (it arrived with the first import of the
+ * table) and holds no threat model. The category rows (`hooks` / `env` / `mcpServers` / `rulesInstructions` at `minTrust: "project"`) and
+ * the ladder numbers are untouched: the change is on the source's tier, not on any row.
+ *
+ * NOT here (each has its own place): the hooks EXECUTION gate (`declined` ⇒ no hook from any layer runs) is contract text in `./hooks`'
+ * header and executes in the client core; the workspace trust RECORD (where "this folder was accepted" is stored) is host state.
+ */
+import { SAFETY_MERGE_SPEC, isAtLeast, memberAdmission } from "./safety-merge-spec.js";
+/** The settings sources, in MERGE order (a later source overrides an earlier one where a category's merge shape lets it):
+ *  user < project < local < flag < policy. `flagSettings` = settings handed in at launch (`--settings <file|json>`, an SDK embedder's inline
+ *  settings); `policySettings` = managed. */
+export const SETTINGS_SOURCES = ["userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings"];
+/**
+ * The source table. `flagSettings` is in the operator tier (`global`, not repository-controllable) like CC's: settings handed in at launch are
+ * the launcher's own act — an SDK embedder or a wrapper script — not something a repository brings (a wrapper that turns repository content
+ * into `--settings` makes that choice itself).
+ */
+export const SETTINGS_SOURCE_CONTRACT = {
+    userSettings: { trust: "global", repoControllable: false },
+    projectSettings: { trust: "project", repoControllable: true },
+    localSettings: { trust: "project", repoControllable: true },
+    flagSettings: { trust: "global", repoControllable: false },
+    policySettings: { trust: "managed", repoControllable: false },
+};
+/**
+ * The ONE lookup of {@link SETTINGS_SOURCE_CONTRACT}: a source's tier and whether a repository controls it. Every function in this package
+ * that needs a layer's tier reads it here ({@link layerAdmission}, the http hook allowlist judge, the MCP server list verdict) — none takes a
+ * tier from its caller. An unknown source (prototype names included) ⇒ RangeError, never a fallback tier.
+ */
+export function settingsSourceContract(source) {
+    if (!Object.hasOwn(SETTINGS_SOURCE_CONTRACT, source)) {
+        throw new RangeError(`SETTINGS_SOURCE_CONTRACT: unknown settings source '${String(source)}' (sources: ${SETTINGS_SOURCES.join(", ")})`);
+    }
+    return SETTINGS_SOURCE_CONTRACT[source];
+}
+/**
+ * The host's reading of the workspace trust decision: `accepted` (the user accepted this folder), `declined` (the user did not, or the
+ * host must assume so), `no_trust_step` (the host has no trust step at all). A host whose reading throws or yields a word outside this set
+ * passes `declined`; this package's functions refuse an unknown word loudly rather than reading it as any tier.
+ */
+export const WORKSPACE_TRUST_STATES = ["accepted", "declined", "no_trust_step"];
+/** What {@link layerAdmission} answers (closed): `admitted`; `trust_withheld` = would be admitted once the workspace is `accepted`;
+ *  `below_trust_floor` = this source can never set it (its tier is below the floor). */
+export const LAYER_ADMISSION_VERDICTS = ["admitted", "trust_withheld", "below_trust_floor"];
+/**
+ * Does a value from `source` for `category` (or one of its declared `member`s; `value` = the candidate value, for a value-directional member)
+ * enter the effective settings, given the workspace trust reading? The rule is in the file header; the data is {@link SETTINGS_SOURCE_CONTRACT}
+ * and `SAFETY_MERGE_SPEC` (floors and directions through `memberAdmission`). Omitting `member` asks about the category as a whole key (a
+ * memberized category's undeclared sub-keys are asked this way: category floor, no direction).
+ * Unknown source / trust reading / category, a member named on a whole-key category, or an undeclared member ⇒ RangeError (never a fallback).
+ */
+export function layerAdmission(source, workspace, category, member, value) {
+    const layer = settingsSourceContract(source);
+    const trusted = workspaceAccepted(workspace);
+    let floor;
+    let direction;
+    if (member === undefined) {
+        if (!Object.hasOwn(SAFETY_MERGE_SPEC, category)) {
+            throw new RangeError(`SAFETY_MERGE_SPEC: unknown category '${String(category)}' (categories: ${Object.keys(SAFETY_MERGE_SPEC).join(", ")})`);
+        }
+        floor = SAFETY_MERGE_SPEC[category].minTrust;
+    }
+    else {
+        const resolved = memberAdmission(category, member, value);
+        floor = resolved.minTrust;
+        direction = resolved.direction;
+    }
+    if (!isAtLeast(layer.trust, floor))
+        return "below_trust_floor";
+    if (layer.repoControllable && !trusted && direction !== "tighten")
+        return "trust_withheld";
+    return "admitted";
+}
+/** `accepted` ⇒ true; `declined` / `no_trust_step` ⇒ false (they differ only at the hooks execution gate, not here); anything else ⇒ RangeError. */
+function workspaceAccepted(workspace) {
+    switch (workspace) {
+        case "accepted":
+            return true;
+        case "declined":
+        case "no_trust_step":
+            return false;
+        default: {
+            const unknown = workspace;
+            throw new RangeError(`WORKSPACE_TRUST_STATES: unknown workspace trust reading '${String(unknown)}' (readings: ${WORKSPACE_TRUST_STATES.join(", ")})`);
+        }
+    }
+}

package/dist/types.d.ts

@@ -179,8 +179,8 @@ export declare const ModelEntry: z.ZodObject<{
         standard: "standard";
         premium: "premium";
     }>>;
-    reasoning: z.ZodDefault<z.ZodBoolean>;
-    vision: z.ZodDefault<z.ZodBoolean>;
+    reasoning: z.ZodOptional<z.ZodBoolean>;
+    vision: z.ZodOptional<z.ZodBoolean>;
     contextWindow: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
     autoCompactTokens: z.ZodOptional<z.ZodNumber>;
@@ -292,8 +292,8 @@ export declare const ModelsConfig: z.ZodObject<{
             standard: "standard";
             premium: "premium";
         }>>;
-        reasoning: z.ZodDefault<z.ZodBoolean>;
-        vision: z.ZodDefault<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodBoolean>;
+        vision: z.ZodOptional<z.ZodBoolean>;
         contextWindow: z.ZodOptional<z.ZodNumber>;
         maxTokens: z.ZodOptional<z.ZodNumber>;
         autoCompactTokens: z.ZodOptional<z.ZodNumber>;
@@ -2311,8 +2311,8 @@ export declare const DOMAIN_SCHEMAS: {
                 standard: "standard";
                 premium: "premium";
             }>>;
-            reasoning: z.ZodDefault<z.ZodBoolean>;
-            vision: z.ZodDefault<z.ZodBoolean>;
+            reasoning: z.ZodOptional<z.ZodBoolean>;
+            vision: z.ZodOptional<z.ZodBoolean>;
             contextWindow: z.ZodOptional<z.ZodNumber>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
             autoCompactTokens: z.ZodOptional<z.ZodNumber>;

package/dist/types.js

@@ -422,8 +422,8 @@ export const PARSE_TRANSPARENT_KEYS = [
         domain: "mcp",
         path: "servers[].toolAxes",
         since: "12.2.0",
-        validatedBy: "consumer",
-        why: "连接器条目声明的按工具轴覆盖层;轴的词表与形归投影它的消费方(server 两腿进 core spec)与写它的连接器,本包只承载,复述那张表必漂。",
+        validatedBy: "engine-ingest",
+        why: "连接器条目声明的按工具轴覆盖层;轴的词表与形只有一只判官 = 引擎根导出 `readMcpToolAxes`(整声明一坏全拒、不默认),投影它的消费方(server 两腿)与写它的连接器都调它,本包只承载 —— 这里再写一份 zod 就是第二只判官,必漂。",
     },
     {
         domain: "mcp",
@@ -474,8 +474,11 @@ export const ModelEntry = z.object({
     sealedApiKey: SealedApiKey.optional(),
     /** Price/capability tier — fuels core 1.25 `selectModel({ tier })` role resolution. */
     tier: ModelTier.default("standard"),
-    reasoning: z.boolean().default(false),
-    vision: z.boolean().default(false),
+    /** Capability bits are THREE-STATE (S-1625 / C-R484): `true` = declared capable, `false` = declared not capable, ABSENT =
+     *  not declared — the reader applies its own default (the engine reads it through one predicate). This package never fills an
+     *  absent bit in: reading "not written" as "not capable" is a default only a reader may choose. */
+    reasoning: z.boolean().optional(),
+    vision: z.boolean().optional(),
     contextWindow: INTEGER.positive().optional(),
     maxTokens: INTEGER.positive().optional(),
     /** Auto-compaction trigger threshold (tokens) for this model — web-admin 显式下发时本地 FileConfigStore
@@ -2253,7 +2256,8 @@ export const HostEntry = z.object({
     // .max(HOST_NAME_MAX=63) = DNS-label bound (E2 F3③ 挂账收账, 0.8.0): web-admin-side probe clamp stays as双保险.
     name: z.string().min(1).max(HOST_NAME_MAX, `host name longer than ${HOST_NAME_MAX} characters (a DNS label) — ${HOSTS_BOUND_SIGNPOST}`).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces"),
     /** 待批准入编状态机(§2-3):自注册/新登记默认 false = 待批,不参与自动排布;admin 批准(走 publish)→
-     *  true 参排(enforcement 随 E2)。既有 worker 不受影响(reconciler 仍按具体 host 认领)。 */
+     *  true 参排(enforcement 随 E2)。只管**自动排布**:`placement.auto:false` 的 worker 的 `host` 是钉,钉在哪台由运维写定、与这里无关;
+     *  `auto:true` 的 worker 只会被排到已批准的 host 上(钉 / 提示按 {@link WorkerSpec} 的 `placement.auto` 判)。 */
     approved: z.boolean().default(false),
     /** 调度标签（如 "gpu"/"region-us"），worker 的 `placement.requires` 据此匹配。 */
     labels: z.array(z.string().min(1)).prefault([]),

package/dist/ui-language.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 界面语言设置片段(13.0.0,S-1592;client-core [10575] §三′ 请托)—— 壳 / 桌面 / web 自己界面(chrome)的语言,**不是**模型回答用的语言
+ * (CC 的 `language` 键是后者;两个事实不共用一个键)。形照 `cross-session.ts` 的片段契约:导出值闭集 + 一层的读器。纯、浏览器安全。
+ *
+ * - 键 `semaUiLanguage`(沿用终端已写的键,cli `src/sema/i18n/languageStore.ts`,已存值零迁移);作用源 = 用户设置;合并类 = `ui`
+ *   (`SAFETY_MERGE_SPEC.ui`,`enforcement: "client"`,壳侧、不进引擎)。
+ * - 合法值闭集 {@link UI_LANGUAGE_VALUES} = `en` / `zh`。
+ * - 缺席或不合法 ⇒ 跟宿主 locale。读器**不猜**:不把 `zh-CN` 折成 `zh`、不按大小写折 —— locale 标签到这两个词的映射是宿主读 locale 时的事,
+ *   不是读设置时的事。
+ */
+import { z } from "zod";
+import type { SettingLayerRead } from "./cross-session.js";
+/** 合法值闭集(声明序)。 */
+export declare const UI_LANGUAGE_VALUES: readonly ["en", "zh"];
+export type UiLanguageValue = (typeof UI_LANGUAGE_VALUES)[number];
+/** 这把键的声明:键名 / 值域 / 合并类 / 作用源 —— 三端读写键与值域都取这里。 */
+export declare const UI_LANGUAGE_SETTING: {
+    readonly key: "semaUiLanguage";
+    readonly values: readonly ["en", "zh"];
+    readonly category: "ui";
+    readonly source: "userSettings";
+};
+/** 值的形门(写侧用:写进设置文件的只能是这两个词之一)。 */
+export declare const UiLanguageSetting: z.ZodEnum<{
+    en: "en";
+    zh: "zh";
+}>;
+/** 整份 `settings.json` 里本片段负责的那一键;刻意 `passthrough`(本片段不是整份设置的闭集门)。 */
+export declare const UiLanguageSettings: z.ZodObject<{
+    semaUiLanguage: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$loose>;
+export type UiLanguageSettings = z.infer<typeof UiLanguageSettings>;
+/**
+ * 读一层的 `semaUiLanguage` 原始值:合法 ⇒ `{ ok: true, value }`;缺席 / `null` ⇒ `{ ok: true }`(未设);其余一切 ⇒ `{ ok: false }`(存的值
+ * 不是两种之一,设置面可据此说一句)。两种「无值」消费方都落到宿主 locale;读器从不猜一个值。
+ */
+export declare function readUiLanguage(raw: unknown): SettingLayerRead<UiLanguageValue>;

package/dist/ui-language.js

@@ -0,0 +1,37 @@
+/**
+ * 界面语言设置片段(13.0.0,S-1592;client-core [10575] §三′ 请托)—— 壳 / 桌面 / web 自己界面(chrome)的语言,**不是**模型回答用的语言
+ * (CC 的 `language` 键是后者;两个事实不共用一个键)。形照 `cross-session.ts` 的片段契约:导出值闭集 + 一层的读器。纯、浏览器安全。
+ *
+ * - 键 `semaUiLanguage`(沿用终端已写的键,cli `src/sema/i18n/languageStore.ts`,已存值零迁移);作用源 = 用户设置;合并类 = `ui`
+ *   (`SAFETY_MERGE_SPEC.ui`,`enforcement: "client"`,壳侧、不进引擎)。
+ * - 合法值闭集 {@link UI_LANGUAGE_VALUES} = `en` / `zh`。
+ * - 缺席或不合法 ⇒ 跟宿主 locale。读器**不猜**:不把 `zh-CN` 折成 `zh`、不按大小写折 —— locale 标签到这两个词的映射是宿主读 locale 时的事,
+ *   不是读设置时的事。
+ */
+import { z } from "zod";
+/** 合法值闭集(声明序)。 */
+export const UI_LANGUAGE_VALUES = ["en", "zh"];
+/** 这把键的声明:键名 / 值域 / 合并类 / 作用源 —— 三端读写键与值域都取这里。 */
+export const UI_LANGUAGE_SETTING = {
+    key: "semaUiLanguage",
+    values: UI_LANGUAGE_VALUES,
+    category: "ui",
+    source: "userSettings",
+};
+/** 值的形门(写侧用:写进设置文件的只能是这两个词之一)。 */
+export const UiLanguageSetting = z.enum(UI_LANGUAGE_VALUES);
+/** 整份 `settings.json` 里本片段负责的那一键;刻意 `passthrough`(本片段不是整份设置的闭集门)。 */
+export const UiLanguageSettings = z
+    .object({
+    [UI_LANGUAGE_SETTING.key]: UiLanguageSetting.optional(),
+})
+    .passthrough();
+/**
+ * 读一层的 `semaUiLanguage` 原始值:合法 ⇒ `{ ok: true, value }`;缺席 / `null` ⇒ `{ ok: true }`(未设);其余一切 ⇒ `{ ok: false }`(存的值
+ * 不是两种之一,设置面可据此说一句)。两种「无值」消费方都落到宿主 locale;读器从不猜一个值。
+ */
+export function readUiLanguage(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true };
+    return typeof raw === "string" && UI_LANGUAGE_VALUES.includes(raw) ? { ok: true, value: raw } : { ok: false };
+}

package/dist/url-pattern.d.ts

@@ -0,0 +1,33 @@
+/**
+ * URL 名单里一条模式对一个 URL 的**唯一判法**(13.0.0,U3 [10538] / S-1597)。管理员写的 URL 名单 —— http hook `allowedHttpHookUrls`
+ * ({@link ./http-hook-allowlists})、MCP `allowedMcpServers` / `deniedMcpServers` 的 `serverUrl` 条目({@link ./mcp-server-policy})——
+ * 都读这一只。纯函数,全局只用 `URL`,浏览器安全。
+ *
+ * 一条律,两只出口:**名单读不准的地方一律判向「拦」**。放行出口在含糊处不命中(命中面 ⊆ 上游),拒绝出口在含糊处命中(命中面 ⊇ 上游)。
+ *
+ * 组件判法(上游同形:CC 2.1.296 `g9`,cli296.js:249195;上游两张名单都调它):
+ *  - 模式恰为 `*` ⇒ 一切命中;URL 自身解析不了 ⇒ 不命中。
+ *  - 模式里的 `*` 换成占位记号后按 URL 解析;解析不了且端口位是 `*` ⇒ 端口位换 0 再解析,并记「端口不判」。
+ *  - 协议:相等,或模式协议整段是 `*`。主机名:两边去尾点、小写后按 glob 比。
+ *  - 端口:模式没写端口且主机名带 `*` ⇒ 不判;否则逐字相等(协议缺省端口两边都读成空)。
+ *  - 路径:模式路径是 `/` 或空、没有查询串、且模式原文不以 `/` 结尾 ⇒ 任意路径命中;否则「路径 + 查询串」按 glob 比。片段、用户信息不比。
+ *  - 模式解析不出 URL(或特殊协议的主机名里出现带通配的 punycode 标签)⇒ 回落成按 `/` 分段的 glob(段数相等、逐段比,`*` 跨不过 `/`)。
+ *  glob 只认 `*`(任意长度任意字符,含空),其余逐字、区分大小写。
+ *
+ * 放行出口比上游严(上游四洞;登本包 docs/CC-DIVERGENCE.md,与 cli 偏离登记 D-025 / D-026 / D-028 / D-029 同形):
+ *  - D-025 模式写了端口(哪怕是协议缺省端口,解析后读成空)⇒ 主机名带 `*` 也照判端口(上游把写明的 `:443` 当没写、放行任意端口)。
+ *    「写没写」由解析器自己答:同一串换成缺省端口不同的同族协议再解析,端口不再读成空 ⇒ 写了。
+ *  - D-026 目标协议不在「主机即连接目标」的四种(http / https / ws / wss)⇒ 模式必须写出那个协议,`*` 协议不通配它;`ws+unix:` 的连接目标
+ *    是路径里第一个 `:` 之前的套接字路径 ⇒ 套接字段只认逐字相等(带 `*` 即不放行任何套接字 —— 套接字路径到连接层还会被点段 / 反斜杠 /
+ *    长度截断改写,glob 判不住真实目标);`:` 之后的请求路径照 glob;没写路径的模式、套接字段为空或含 `..` 段的目标一律不放行。
+ *  - D-028 模式解析不出 URL 形(走分段回落)⇒ 不放行:回落把主机与端口拼成一段比,`*` 能跨过两者的边界。
+ *  - D-029 解析后主机名里出现不是占位来的 `*`(`%2a` / 全角 `＊` 被解析器解码、归一成的字面 `*`)⇒ 不放行:那是字面字符,不是通配。
+ * 拒绝出口比上游宽一处(D-027):另按整串 glob 再判一次,既有的无协议 / 跨组件写法不因按组件判而失效。
+ *
+ * 占位记号(与上游 / cli 不同的一处实现):上游用每进程随机串;本包要纯、要确定 ⇒ 按输入选一个记号 —— 它在模式与目标的任何解析读法里
+ * (原文 / 百分号解码 / IDNA 近似映射)都不出现,放进模式后也只在放进去的那几处出现(不与相邻字面拼出第二份)。
+ */
+/** 放行名单:`url` 是否被模式 `pattern` 放行(判法见文件头;命中面 ⊆ 上游)。 */
+export declare function urlAllowPatternMatches(url: string, pattern: string): boolean;
+/** 拒绝名单:`url` 是否被模式 `pattern` 拦下(上游组件判法,或整串 glob;命中面 ⊇ 上游)。 */
+export declare function urlDenyPatternMatches(url: string, pattern: string): boolean;