@sema-agent/settings-schema 1.0.0

package/dist/config-fns.js

@@ -0,0 +1,472 @@
+import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, InfraCostRates, LimitsConfig, 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
+ *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
+ *  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. */
+export function redactSecrets(text) {
+    return 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));
+}
+/** 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
+ *  `{model}|{select}`) and redacts string path segments too. The ONE sanitizer every validation entry point
+ *  uses (parseDomain / validateDomain / validateRemoteExec / write*). R14. */
+export function sanitizeZodError(err) {
+    for (const iss of err.issues) {
+        const rec = iss;
+        for (const k of Object.keys(rec)) {
+            const v = rec[k];
+            if (typeof v === "string")
+                rec[k] = redactSecrets(v);
+            else if (Array.isArray(v)) {
+                rec[k] = v.map((el) => {
+                    if (typeof el === "string")
+                        return redactSecrets(el);
+                    if (el && typeof el === "object" && Array.isArray(el.issues))
+                        return sanitizeZodError(el); // nested unionErrors
+                    return el;
+                });
+            }
+        }
+    }
+    return err;
+}
+export const ROLE_RANK = { viewer: 0, editor: 1, publisher: 2, admin: 3 };
+export const USER_ROLES = ["viewer", "editor", "publisher", "admin"];
+/** True if `role` is at least `min` in the hierarchy (e.g. publisher satisfies editor). */
+export function roleAtLeast(role, min) {
+    return ROLE_RANK[role] >= ROLE_RANK[min];
+}
+export function isRole(v) {
+    return typeof v === "string" && USER_ROLES.includes(v);
+}
+/**
+ * Minimum role to WRITE a domain. Default = `editor`; `skills` and `mcp` are raised to `publisher`
+ * because their content goes straight into the agent's system prompt / tool surface — one edit retargets
+ * the prompt of every worker × scenario that loads it (docs/MCP-SKILLS.md §3.3, decision §6 Q3 从严).
+ * Looked up by the [domain] PUT route. Any domain absent here uses {@link DEFAULT_DOMAIN_WRITE_ROLE}.
+ */
+export const DEFAULT_DOMAIN_WRITE_ROLE = "editor";
+export const DOMAIN_WRITE_ROLE = {
+    skills: "publisher",
+    mcp: "publisher",
+    // plugins are an EXECUTABLE surface (commands/hooks/MCP ride in via the materialized plugin) — the same
+    // raised gate as skills/mcp (C2, 产品拍板: 可执行面同档).
+    plugins: "publisher",
+    // scenarios carry SYSTEM-PROMPT-level text + can SHADOW built-in scenario names (产品拍板 ①②) — a stronger
+    // injection surface than skills, so at least the same gate.
+    scenarios: "publisher",
+    // systems drive CREDENTIAL minting/delivery/rotation (S2/S3) — the credential lifecycle is ≥ the skills tier.
+    systems: "publisher",
+    // access: DELETED in 0.6.0 (域整删,EXPERT-REDESIGN §9)。
+    // governance (治理三件,0.6.0 从 runtime 拆出): editor(EXPERT-REDESIGN §5 domainWriteRole 同步——与
+    // runtime 残余同档,default 即 editor,故不列条目;此注释即该裁定的落点)。
+    // entitlement governs who-can-USE-what (models/skills/mcp/budget/runtime caps) per principal — a governance +
+    // security surface (budget ceilings, bypass kill-switch) on par with systems. Same raised gate.
+    entitlement: "publisher",
+    // prompts (0.10.19, board [1069]③/[1050]②d): declaration text goes STRAIGHT into the system prompt of
+    // every worker×scenario the binding covers — the same injection surface (and rationale) as skills/mcp,
+    // so the same raised gate. Center had pre-raised this locally per governance precedent; this row is the
+    // contract-side source of truth so every consumer of the shared write gate gets publisher, not editor.
+    prompts: "publisher",
+    // execution (0.8.0): editor — same档 as governance (治理旋钮同类;真安全边界在 service gate,
+    // client-advisory 面不值 publisher 档)。default 即 editor,故不列条目;此注释即该裁定的落点。
+    // projects (0.10.0, 142-S3): editor — 登记簿是身份索引不是注入面(无 prompt/凭据/可执行内容);
+    // mint/claim 动作端点与编辑面同档(草案 §3 "该 scope editor+")。default 即 editor,故不列条目。
+    // limits (0.19.0): editor —— 与 runtime(它的限额残余前身)同档,刻意不抬 publisher:本域是纯数值
+    // 旋钮,无 prompt 注入面、无凭据、无可执行内容;真正的执法点在消费方的限额闸,发布闸(PUBLISH_MODE /
+    // 审批流)才是"要不要多一道人"的属主。default 即 editor,故不列条目;此注释即该裁定的落点。
+};
+/** The minimum role required to write `domain` (the raised gate for skills/mcp, else editor). */
+export function domainWriteRole(domain) {
+    return DOMAIN_WRITE_ROLE[domain] ?? DEFAULT_DOMAIN_WRITE_ROLE;
+}
+/** The empty/defaults effective config at version 0 — what publish mode serves before the first publish.
+ *  Seeds the epoch (`new Date(0)`) so it's deterministic (the wall-clock default was the original store.ts
+ *  non-determinism — see the file header). */
+export function emptyEffective() {
+    return buildEffective(0, () => undefined, new Date(0).toISOString());
+}
+/** Validate + fill defaults for a domain payload (or the schema's empty default when absent/invalid). */
+export function parseDomain(domain, raw) {
+    // ONLY true absence (undefined) defaults; an explicit `null` (e.g. a `config.d/<d>.json` containing JSON
+    // `null`) is corrupt input → let zod reject it ("expected object, received null"), not silently default. R4.
+    let r;
+    try {
+        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw);
+    }
+    catch {
+        // a hostile getter/Proxy trap threw during traversal — its message may carry a secret; never surface it. R13.
+        throw new Error(`invalid "${domain}" config (a value could not be read during validation)`);
+    }
+    if (r.success)
+        return r.data;
+    throw sanitizeZodError(r.error); // recursive redaction (message/received/unionErrors) — no secret echo. R13/R14.
+}
+/**
+ * Shared GC predicate for worker-status rows (F10) — keeps memory/sqlite/tidb identical. Given the rows'
+ * `{name, updatedAt}` and the GC options, returns the names to prune (A: not in `keepNames`; B: older than
+ * `ttlMs`). Pass neither selector → prunes nothing (guards against a wipe-all). See `ConfigStore.gcWorkerStatuses`.
+ */
+export function statusRowsToPrune(rows, opts) {
+    if (opts.keepNames === undefined && opts.ttlMs === undefined)
+        return [];
+    const keep = opts.keepNames ? new Set(opts.keepNames) : undefined;
+    const cutoff = opts.ttlMs !== undefined ? (opts.now ?? new Date()).getTime() - opts.ttlMs : undefined;
+    return rows
+        .filter((r) => (keep !== undefined && !keep.has(r.name)) || (cutoff !== undefined && Date.parse(r.updatedAt) < cutoff))
+        .map((r) => r.name);
+}
+/**
+ * Merge every domain into the effective config a consumer pulls. Shared by all store impls.
+ * `updatedAt` is REQUIRED (the determinism refactor — the original store.ts defaulted it to the wall clock,
+ * which made `emptyEffective`/the memory store non-deterministic). Every caller now supplies it explicitly.
+ */
+/** Lift the governance trio out of a LEGACY runtime doc (pre-0.6 stored runtime carried autonomy/commandPolicy/
+ *  approvalRequire). Used as the governance domain's read fallback when governance was NEVER set — so a 0.5
+ *  store upgrades with zero data migration and zero gate loss. An explicitly-set governance domain WINS
+ *  (its absence-of-a-key then means "center not managing", never "fall back to legacy runtime"). */
+export function legacyGovernanceFromRuntime(rawRuntime) {
+    if (rawRuntime === null || typeof rawRuntime !== "object")
+        return undefined;
+    const r = rawRuntime;
+    const lifted = {};
+    for (const k of GOVERNANCE_MIRROR_KEYS)
+        if (r[k] !== undefined)
+            lifted[k] = r[k];
+    return Object.keys(lifted).length ? lifted : undefined;
+}
+/** 扫描深度上限(嵌套再深的配置文档不存在;有上限才不会被恶意深链拖住)。 */
+const DROP_SCAN_MAX_DEPTH = 8;
+/** 一条警告最多点名多少个键(告警载荷有界;截断即说明,见 {@link droppedKeys})。 */
+const DROP_SCAN_MAX_KEYS = 64;
+/** 纯 JSON 对象(不是数组、不是类实例/带原型的东西)——只对这种做键集对比,别的形状交给 parse 判。 */
+function isPlainJsonObject(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+function collectDropped(raw, parsed, prefix, depth, spared, out) {
+    if (depth > DROP_SCAN_MAX_DEPTH || out.length >= DROP_SCAN_MAX_KEYS)
+        return;
+    if (Array.isArray(raw) && Array.isArray(parsed)) {
+        // 长度不同 = 整条元素被丢/被裁(hosts 的 grandfather clamp 有自己的警告),不在本判据内,别造重复噪声。
+        if (raw.length !== parsed.length)
+            return;
+        for (let i = 0; i < raw.length; i++)
+            collectDropped(raw[i], parsed[i], `${prefix}${i}.`, depth + 1, [], out);
+        return;
+    }
+    if (!isPlainJsonObject(raw) || !isPlainJsonObject(parsed))
+        return;
+    for (const k of Object.keys(raw)) {
+        if (out.length >= DROP_SCAN_MAX_KEYS)
+            return;
+        if (depth === 0 && spared.includes(k))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(parsed, k)) {
+            out.push(prefix + k);
+            continue;
+        }
+        collectDropped(raw[k], parsed[k], `${prefix}${k}.`, depth + 1, spared, out);
+    }
+}
+/**
+ * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
+ *
+ * 成案(sema-server #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
+ * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
+ * (新 center 的新键不该炸老消费方),所以修法不是收紧成 `.strict()`,而是让它**响亮**:
+ * {@link buildEffective} 每域解析成功后调用本函数,非空即发 `"unknown-keys-dropped"` 警告。
+ *
+ * **嵌套也扫**(codex 复审 F2 真 finding):`{infraCostRates:{toolCalMicroUsd:10}}` 这种**拼错的嵌套
+ * 键**在顶层看不见(`infraCostRates` 键还在),只看顶层等于对计费面的错键完全失明。故按 raw↔parsed
+ * 的键集逐层对比(对象逐键、数组同长时逐下标),不依赖任何 zod 内省。
+ *
+ * `runtime` 域的治理三件({@link GOVERNANCE_MIRROR_KEYS})**不算被丢**:0.5 期 runtime 文档携带它们是
+ * 成文的抬升位(本文件的 governance 抬升函数会把它们抬进 governance 域),报出来是噪声。豁免只在顶层。
+ *
+ * 边界(如实登记):① 深度上限 {@link DROP_SCAN_MAX_DEPTH}、键数上限 {@link DROP_SCAN_MAX_KEYS}(告警
+ * 载荷有界,超出即少报);② 数组长度不同就整段跳过(元素级裁剪由各自的 clamp 告警负责);③ 只比对纯
+ * JSON 对象——raw 若是类实例/Proxy 这类形状不扫;④ 读 raw 的值可能触发访问器,整段包 try/catch 且**绝不**
+ * 让其错误外泄(错误文案可能带 secret,与 parseDomain 的 R13 同纪律),扫描失败即当作"没看见",不影响解析。
+ */
+export function droppedKeys(domain, raw, parsed) {
+    const out = [];
+    try {
+        collectDropped(raw, parsed, "", 0, domain === "runtime" ? GOVERNANCE_MIRROR_KEYS : [], out);
+    }
+    catch {
+        return []; // 反射/访问器抛错:告警是尽力而为的审计线,绝不能把解析拖下水,更不能回显其错误文案
+    }
+    return out;
+}
+/**
+ * open-world 域(`.passthrough()`)的**已知键表**:路径 → 该层已知键(`""` = 顶层)。键集从 schema 的
+ * `shape` **单源派生**(手抄一份必然漂),路径表本身是显式的——嵌套只在真有 open-world 子对象的地方登记。
+ *
+ * 为什么需要它(codex 复审 round2 F2):承运解决了「值到不了」,但没解决「键名拼错了没人说」——
+ * `toolResultsTtlSec`(多一个 s)会完好穿过本包,而消费方只遍历自己的键表,于是那条天花板悄悄没生效。
+ * 承运 + 点名两件一起做:值照送(消费方有权认新键),名照报(拼错的有人说)。
+ *
+ * 新开 open-world 域必须来这里登记 —— `test/silent-drop-gate-0.19.test.ts` 有一条门:任何
+ * `unknownKeys === "passthrough"` 的域 schema 都必须在本表里有行(缺行 = 该域的未知键无人点名)。
+ */
+const OPEN_WORLD_KNOWN_KEYS = {
+    limits: { "": Object.keys(LimitsConfig.shape), infraCostRates: Object.keys(InfraCostRates.shape) },
+};
+/**
+ * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(点号路径)。非 open-world 域恒空
+ * (它们的未知键走 {@link droppedKeys} 那条更重的「被丢了」告警)。
+ *
+ * 边界(如实):只看 {@link OPEN_WORLD_KNOWN_KEYS} 登记了的层级 —— 未登记层级(如某个未知键自己的
+ * 子树)不再下探,那本就是消费方自定义的内容,逐层猜没有意义。
+ */
+export function carriedUnknownKeys(domain, parsed) {
+    const table = OPEN_WORLD_KNOWN_KEYS[domain];
+    if (!table || !isPlainJsonObject(parsed))
+        return [];
+    const out = [];
+    for (const [path, known] of Object.entries(table)) {
+        const node = path === "" ? parsed : parsed[path];
+        if (!isPlainJsonObject(node))
+            continue;
+        const prefix = path === "" ? "" : `${path}.`;
+        for (const k of Object.keys(node)) {
+            if (out.length >= DROP_SCAN_MAX_KEYS)
+                return out;
+            if (!known.includes(k))
+                out.push(prefix + k);
+        }
+    }
+    return out;
+}
+/**
+ * 一域的 parse + **静默剥键/静默承运两条告警**(0.19.0)。`buildEffective` 与 `FileConfigStore.getDomain`
+ * 共用这一个判据 —— 此前只有 effective 那条路径有门,而 `getDomain` 是 `exportBundle` 的读法
+ * (codex 复审 round2 F3:导出一份被剥了键的域再导入 = 持久的配置丢失,而且全程无声)。
+ */
+export function parseDomainLoud(domain, raw, onWarning) {
+    const parsed = parseDomain(domain, raw);
+    if (onWarning) {
+        const dropped = droppedKeys(domain, raw, parsed);
+        if (dropped.length > 0)
+            onWarning({ domain, kind: "unknown-keys-dropped", keys: dropped });
+        const carried = carriedUnknownKeys(domain, parsed);
+        if (carried.length > 0)
+            onWarning({ domain, kind: "unknown-keys-carried", keys: carried });
+    }
+    return parsed;
+}
+/** Per-domain READ-corruption policy (0.8.1) — what buildEffective does when a stored domain no longer parses.
+ *  `"default"` = degrade to the schema default + warn (safe: the default only REMOVES capability, fail-closed).
+ *  `"throw"` = keep fail-loud (defaulting would LOOSEN gates or destructively apply — worse than an outage,
+ *  consumers fail-static on last-good). A `satisfies Record<DomainName,…>` forces every FUTURE domain to make
+ *  this call explicitly (compile error until it's classified). Per-domain rationale:
+ *    - models/skills/mcp/plugins/scenarios/systems/collab: additive capability catalogs — empty = the
+ *      capability disappears (fail-closed), no gate is lost.
+ *    - hosts: empty registry = no auto-placement targets (availability-only); self-registration re-lands
+ *      entries as approved:false = 待批 (fail-closed). Plus the precise grandfather clamp runs FIRST.
+ *    - rosters: THROW — a lost roster makes resolveEffectiveForWorker fall back to the FULL models catalog
+ *      ("global(fallback)"), silently WIDENING every restricted worker's model access. 放权,不许.
+ *    - workers: THROW — an empty fleet spec would make the reconciler RETIRE every managed worker
+ *      (destructive apply — far worse than a read outage).
+ *    - runtime: THROW — defaulting drops centrally-published rate/cost ceilings = unbounded spend (fail-open
+ *      on the budget axis).
+ *    - governance: THROW — defaulting drops autonomy/commandPolicy/approvalRequire = the consumer falls back
+ *      to env/defaults with the operator's guardrails silently gone. 放权,不许.
+ *    - entitlement: THROW — defaulting drops the org kill-switch/budget ceilings/tier restrictions for every
+ *      principal. 放权,不许.
+ *    - execution: THROW — defaulting flips required:true (sandbox mandate) back to false. 放权,不许.
+ *      (0.10.1: sessionMirror rides the SAME stance — defaulting would evaporate an org's required:true
+ *      mirror mandate = 审计面静默放权; the shared rationale is exactly WHY it was收编 here, not a new domain.)
+ *    - projects: THROW — defaulting evaporates the whole identity ledger: once the S4 worker gate ships,
+ *      every `proj:*` derivation fails-fast (全租户记忆面停摆 — consumers fail-static on last-good is
+ *      strictly better); WORSE, the claim write face is read-modify-write — reading a defaulted-empty
+ *      ledger and writing it back would CLOBBER existing registrations down to one entry (data loss,
+ *      one layer beyond the rosters "放权" rationale). */
+export const DOMAIN_READ_FALLBACK = {
+    models: "default",
+    rosters: "throw",
+    skills: "default",
+    mcp: "default",
+    plugins: "default",
+    scenarios: "default",
+    systems: "default",
+    collab: "default",
+    workers: "throw",
+    hosts: "default",
+    runtime: "throw",
+    governance: "throw",
+    entitlement: "throw",
+    execution: "throw",
+    projects: "throw",
+    // prompts:内容域(scenarios 同类)——坏形→空默认(=「无 prompts 管理」当年语义,web [1064]②
+    // backfill-empty-default 同口径);fail-closed 由 PUBLISH_MODE 发布闸承担,default 不扩权
+    // (空 bindings=不下发任何内容)。
+    prompts: "default",
+    // limits(0.19.0):THROW —— 与 runtime 逐字同判据(本域就是 runtime 限额残余的继任发布位)。坏形
+    // 降级成空域 = 中央发布的成本/限流天花板整片蒸发,消费方回自己的 env 底(可能宽得多)= 预算轴放权。
+    // 消费方 fail-static 在上一份好配置严格更好。
+    limits: "throw",
+};
+/** READ-path grandfather clamp for the 0.8.0 hosts tightening (0.8.1, S3 M-1). Clamps ONLY the two bounds
+ *  0.8.0 added (name > 63 → drop the entry; array > 1024 → slice) so 0.7-era legal stored data keeps reading;
+ *  everything else (regex, types, duplicates) is left for parseDomain — this is a targeted grandfather, not a
+ *  lenient parser. PURE + idempotent; returns the ORIGINAL reference when nothing exceeds the bounds. */
+export function grandfatherHostsRead(raw) {
+    if (raw === null || typeof raw !== "object" || !Array.isArray(raw.hosts)) {
+        return { raw, droppedNames: [] }; // not the expected shape — let parseDomain rule on it
+    }
+    const original = raw.hosts;
+    const droppedNames = [];
+    let hosts = original.filter((h) => {
+        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
+            return false;
+        }
+        return true;
+    });
+    let truncatedFrom;
+    if (hosts.length > HOSTS_ARRAY_MAX) {
+        truncatedFrom = hosts.length;
+        hosts = hosts.slice(0, HOSTS_ARRAY_MAX);
+    }
+    if (droppedNames.length === 0 && truncatedFrom === undefined)
+        return { raw, droppedNames }; // identity — byte-stable
+    return { raw: { ...raw, hosts }, droppedNames, truncatedFrom };
+}
+export function buildEffective(version, getRaw, updatedAt, onWarning) {
+    // 0.19.0 静默剥键/静默承运门:解析**成功**的域,把 schema 丢掉的键、以及 open-world 域里承运但本包
+    // 不认识的键(都含嵌套,点号路径)点名(行为不变,只是不再无声)。判据与 `getDomain` 同源
+    // ({@link parseDomainLoud})。只在成功路径上报——降级路径已经有 domain-defaulted 那条更重的警告。
+    const parseLoud = (domain, raw) => parseDomainLoud(domain, raw, onWarning);
+    // Generic READ guardrail (0.8.1): a domain that no longer parses degrades to its schema default + a warning
+    // — but ONLY where DOMAIN_READ_FALLBACK says the default is safe; gate-bearing domains keep throwing (决策
+    // 表与逐域理由见 DOMAIN_READ_FALLBACK). The success path is UNCHANGED (same parseDomain, same bytes).
+    const parseOr = (domain, raw) => {
+        try {
+            return parseLoud(domain, raw);
+        }
+        catch (e) {
+            if (DOMAIN_READ_FALLBACK[domain] === "throw")
+                throw e;
+            onWarning?.({ domain, kind: "domain-defaulted", error: e });
+            return parseDomain(domain, undefined); // schema default — always valid
+        }
+    };
+    // governance TRUTH: the domain itself; if it was never set, lift the trio from a legacy runtime doc
+    // (0.5→0.6 upgrade path — a2/local stores keep their gates without a data migration).
+    const governanceRaw = getRaw("governance");
+    const governance = parseLoud("governance", governanceRaw === undefined ? legacyGovernanceFromRuntime(getRaw("runtime")) : governanceRaw);
+    // runtime slot = limit residue ONLY. 0.7.1(BREAKING,service 回执收账):E1 的 governance→runtime
+    // 六闸双写镜像已撤——service 1.150.0 已切优先读 eff.governance 并回帖确认(撤双写以其确认为门槛,
+    // ask⑤ 顺序契约兑现)。READ 方向的 legacy lift(governance 域从未设时从旧 runtime 文档抬升三闸,
+    // 见 legacyGovernanceFromRuntime)保留——那是 0.5→0.6 升级路径,与写出镜像无关。
+    const runtime = parseLoud("runtime", getRaw("runtime"));
+    // 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 });
+    }
+    return {
+        version,
+        updatedAt,
+        models: parseOr("models", getRaw("models")),
+        rosters: parseLoud("rosters", getRaw("rosters")),
+        skills: parseOr("skills", getRaw("skills")),
+        mcp: parseOr("mcp", getRaw("mcp")),
+        plugins: parseOr("plugins", getRaw("plugins")),
+        scenarios: parseOr("scenarios", getRaw("scenarios")),
+        systems: parseOr("systems", getRaw("systems")),
+        collab: parseOr("collab", getRaw("collab")),
+        workers: parseLoud("workers", getRaw("workers")),
+        hosts: parseOr("hosts", hostsGf.raw),
+        runtime,
+        governance,
+        entitlement: parseLoud("entitlement", getRaw("entitlement")),
+        // execution (0.8.0, S3): plain scope-level parse — MIRRORS governance (no overlay/merge invented here).
+        execution: parseLoud("execution", getRaw("execution")),
+        // projects (0.10.0, 142-S3): THROW policy → parseLoud(≡ parseDomain + 剥键告警), never parseOr
+        // (defaulting would evaporate the identity ledger AND expose the claim read-modify-write face to
+        // clobbering stored registrations).
+        projects: parseLoud("projects", getRaw("projects")),
+        // prompts (0.10.18, [1064]②): content domain → parseOr(坏形回空默认=「无 prompts 管理」语义;
+        // fail-closed 由 PUBLISH_MODE 发布闸承担,空 bindings 不下发内容,default 不扩权)。
+        prompts: parseOr("prompts", getRaw("prompts")),
+        // limits (0.19.0, sema-server #322 批1): THROW 档 → parseLoud(坏形绝不静默降级成「没有天花板」)。
+        limits: parseLoud("limits", getRaw("limits")),
+    };
+}
+/** READ-side tolerant judgment for a GET /effective **wire payload**(the {@link EffectiveWire} contract)at
+ *  its CONSUMPTION boundary — a service pulling from a remote center passes the parsed JSON here instead of
+ *  type-asserting it(0.12.0,[2281] 裁B:「两个契约共用一个拼写不是一个被检查的契约」——拼写副本要在
+ *  消费端被真校验)。ONE judgment, two legs: every known domain goes through the SAME `parseDomain` +
+ *  {@link DOMAIN_READ_FALLBACK} policy as {@link buildEffective}(catalog 域坏形 → schema default + warning;
+ *  gate 域坏形 → throw,caller 的整包 catch 决定回落),including the governance legacy-lift and the hosts
+ *  read-grandfather — DELEGATED to buildEffective, not re-implemented(单判据双腿消费,§M4)。
+ *
+ *  `skills` is the ONE wire divergence: on the wire it is a MANIFEST(content → contentHash,
+ *  {@link SkillsManifest}),so the full skills-domain schema would reject every LEGAL manifest and silently
+ *  default the domain(蒸发整张 skill 清单)— it validates against {@link SkillsManifestSchema} instead,
+ *  same "default" fallback tier as the skills domain itself.
+ *
+ *  OPEN-WORLD on unknown top-level keys: they ride through VERBATIM(never validated, never dropped)— a
+ *  newer center's new domain reaches an older service untouched(§M2 能力面语义:读不到即走老路,不该炸),
+ *  and the legacy `teams` key(not a domain since 0.7, services still consume it for backward compat)keeps
+ *  flowing. Throws ONLY on garbage no caller can partially trust: a non-object payload, or a missing/
+ *  non-finite `version` — that is not "a bad domain", it is not an effective config at all. */
+export function readEffectiveWire(raw, onWarning) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("effective wire payload is not a JSON object");
+    const r = raw;
+    if (typeof r.version !== "number" || !Number.isFinite(r.version))
+        throw new Error("effective wire payload has no numeric version");
+    const updatedAt = typeof r.updatedAt === "string" ? r.updatedAt : "";
+    // skills redirected to undefined: buildEffective must never see the manifest(it would fail the full-domain
+    // schema and "default" it with a FALSE domain-defaulted warning);the manifest is judged separately below.
+    // prompts likewise redirected(#100):on the wire it is the center-assembled RESOLVED form(worker lane
+    // strips the bindings storage table — types.ts PromptsConfig 注 [1057]⑤),consumer-validated additive JSON;
+    // the storage-domain schema would swallow it to {bindings:[]} with ZERO warning(zod non-strict 剥键后
+    // "成功")— 3.24.0 起 server 侧 promptsGate 恒败的根因。verbatim,by presence(见 return)。
+    const built = buildEffective(r.version, (d) => (d === "skills" || d === "prompts" ? undefined : r[d]), updatedAt, onWarning);
+    let skills;
+    const manifest = SkillsManifestSchema.safeParse(r.skills ?? {});
+    if (manifest.success) {
+        skills = manifest.data;
+    }
+    else {
+        onWarning?.({ domain: "skills", kind: "domain-defaulted", error: sanitizeZodError(manifest.error) });
+        skills = { skills: [] };
+    }
+    // Open-world passthrough: keys that are neither validated domains nor the envelope fields ride verbatim.
+    const passthrough = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (!(k in built) && k !== "skills")
+            passthrough[k] = v;
+    }
+    // prompts:剥掉 buildEffective 恒物化的 {bindings:[]} 底座,按 wire 在场性 verbatim 挂回(#100:
+    // 缺席进缺席出——center worker-lane 闸关是常态形,物化会让消费端「缺席」分支永不可达)。
+    const { prompts: _promptsMaterialized, ...builtSansPrompts } = built;
+    return { ...passthrough, ...builtSansPrompts, skills, ...("prompts" in r ? { prompts: r.prompts } : {}) };
+}
+/** 档位组→引擎单表的唯一解析点(0.9.0)。返回 ACTIVE 档位组的绑定表(剔除未绑档),即 core
+ *  `RunnerDeps.tiers` 要吃的那张单表——组切换=center 换这张表下发,零新引擎机制。无 active 组/未命中/
+ *  组内一档未绑 → `undefined`(引擎档位层恒惰性,与「未配 tiers」逐字同义)。消费方(center /effective
+ *  投影、service applyEffective 接线)都走这一个函数,不要各自解析。 */
+export function resolveActiveTiers(models) {
+    if (!models.activeTierGroup)
+        return undefined;
+    const group = (models.tierGroups ?? []).find((g) => g.name === models.activeTierGroup);
+    if (!group)
+        return undefined; // schema 已 fail-loud 悬空 active;这里兜底旧数据,静默=INERT 与缺表同义
+    const bound = Object.entries(group.tiers).filter((e) => typeof e[1] === "string" && e[1].length > 0);
+    if (bound.length === 0)
+        return undefined;
+    return Object.fromEntries(bound);
+}

package/dist/cross-domain.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-domain referential integrity — the PURE half, shared by the single-domain PUT and the batch write so
+ * BOTH enforce the same rules (docs/MULTI-ROSTER.md §6). The FLEET-coupled `applyAutoPlacement` (which imports
+ * `../fleet/placement`) STAYS in sema-registry — it's not pure and not portable. This package carries only
+ * `refIntegrityIssues` + `siblingResolver` + the ref-issue types.
+ *
+ * BATCH-AWARE: a sibling domain (the models a roster references, the rosters a worker references) may be
+ * changing in the SAME batch. So checks resolve siblings through a {@link SiblingResolver} that prefers a
+ * value being written NOW over the stored one — otherwise "add a model AND a roster that uses it" in one
+ * batch would wrongly fail. The single-domain PUT passes no pending writes, so its resolver is just the
+ * reader (behaviour unchanged).
+ */
+import type { ConfigReader } from "./reader.js";
+import type { DomainConfig } from "./types.js";
+export interface RefIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/** Resolve a sibling domain's effective value for integrity checks. */
+export type SiblingResolver = <K extends keyof DomainConfig>(domain: K) => Promise<DomainConfig[K] | undefined>;
+/** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
+ *  Widened from the fat ConfigStore to the narrow {@link ConfigReader} (it only calls `getDomain`) so a TOC
+ *  file source can use it without the full store. */
+export declare function siblingResolver(store: ConfigReader, pending?: Partial<{
+    [K in keyof DomainConfig]: DomainConfig[K];
+}>): SiblingResolver;
+/** The domains whose writes carry cross-domain model/roster references we validate at save time. */
+export type RefCheckedDomain = "rosters" | "workers" | "models" | "collab" | "systems" | "entitlement";
+/** Cross-domain ref integrity for a rosters/workers/models/collab/systems value. Paths start with the domain
+ *  key (e.g. `["rosters", i, "models", j]`) so a caller can prefix a batch index. Empty = ok. Runtime
+ *  resolution stays tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is
+ *  friendlier than a silently-wrong roster. */
+export declare function refIntegrityIssues(domain: RefCheckedDomain, value: unknown, resolve: SiblingResolver): Promise<RefIssue[]>;

package/dist/cross-domain.js

@@ -0,0 +1,118 @@
+/** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
+ *  Widened from the fat ConfigStore to the narrow {@link ConfigReader} (it only calls `getDomain`) so a TOC
+ *  file source can use it without the full store. */
+export function siblingResolver(store, pending) {
+    return async (domain) => {
+        if (pending && Object.prototype.hasOwnProperty.call(pending, domain))
+            return pending[domain];
+        return store.getDomain(domain);
+    };
+}
+/** Cross-domain ref integrity for a rosters/workers/models/collab/systems value. Paths start with the domain
+ *  key (e.g. `["rosters", i, "models", j]`) so a caller can prefix a batch index. Empty = ok. Runtime
+ *  resolution stays tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is
+ *  friendlier than a silently-wrong roster. */
+export async function refIntegrityIssues(domain, value, resolve) {
+    const issues = [];
+    if (domain === "rosters") {
+        const catalog = new Set(((await resolve("models"))?.models ?? []).map((m) => m.name));
+        value.rosters.forEach((r, i) => {
+            r.models.forEach((name, j) => {
+                if (!catalog.has(name))
+                    issues.push({ path: ["rosters", i, "models", j], message: `roster "${r.name}" references unknown model "${name}" (not in the models catalog)`, code: "custom" });
+            });
+            for (const [role, target] of Object.entries(r.roles ?? {})) {
+                if (target && "model" in target && !catalog.has(target.model))
+                    issues.push({ path: ["rosters", i, "roles", role], message: `roster "${r.name}" role.${role} → unknown model "${target.model}"`, code: "custom" });
+            }
+            // 0.6.3 markers (primaryModel/cheapModel) reference the catalog like a {model}-form role does — same
+            // save-time guard (a dangling marker would silently derive nothing at resolution).
+            if (r.primaryModel && !catalog.has(r.primaryModel))
+                issues.push({ path: ["rosters", i, "primaryModel"], message: `roster "${r.name}" primaryModel → unknown model "${r.primaryModel}" (not in the models catalog)`, code: "custom" });
+            if (r.cheapModel && !catalog.has(r.cheapModel))
+                issues.push({ path: ["rosters", i, "cheapModel"], message: `roster "${r.name}" cheapModel → unknown model "${r.cheapModel}" (not in the models catalog)`, code: "custom" });
+            (r.atModelAllowlist ?? []).forEach((name, j) => {
+                if (!catalog.has(name))
+                    issues.push({ path: ["rosters", i, "atModelAllowlist", j], message: `roster "${r.name}" atModelAllowlist "${name}" not in the models catalog`, code: "custom" });
+            });
+        });
+    }
+    else if (domain === "workers") {
+        const rosterNames = new Set(((await resolve("rosters"))?.rosters ?? []).map((r) => r.name));
+        value.workers.forEach((w, i) => {
+            if (w.roster && !rosterNames.has(w.roster))
+                issues.push({ path: ["workers", i, "roster"], message: `worker "${w.name}" references unknown roster "${w.roster}"`, code: "custom" });
+        });
+    }
+    else if (domain === "models") {
+        // The roles map + @-allowlist reference models in THIS payload's OWN catalog (they ship together in the
+        // models domain), so validate against `value`, not the stored/sibling models.
+        const m = value;
+        const catalog = new Set(m.models.map((x) => x.name));
+        for (const [role, target] of Object.entries(m.roles ?? {})) {
+            if (target && "model" in target && !catalog.has(target.model))
+                issues.push({ path: ["models", "roles", role], message: `models.roles.${role} → unknown model "${target.model}" (not in the catalog)`, code: "custom" });
+        }
+        (m.atModelAllowlist ?? []).forEach((name, j) => {
+            if (!catalog.has(name))
+                issues.push({ path: ["models", "atModelAllowlist", j], message: `atModelAllowlist "${name}" not in the models catalog`, code: "custom" });
+        });
+    }
+    else if (domain === "collab") {
+        // collab (0.7.0, replaces teams): a slot member's `modelRef` is a models-CATALOG name (T1 — never a
+        // roster, never a gateway id) and must resolve against the catalog (sibling — batch-aware). ABSENT
+        // modelRef is the legal "跟随用户当前模型" state, not a dangle. This is the SAVE-time guard; a model
+        // deleted/renamed LATER still dangles → the web renders the 悬空 destructive badge (§11-6), same as
+        // groupBindings.
+        const catalog = new Set(((await resolve("models"))?.models ?? []).map((x) => x.name));
+        value.templates.forEach((t, i) => {
+            t.slots.forEach((s, j) => {
+                s.members.forEach((mem, k) => {
+                    if (mem.modelRef && !catalog.has(mem.modelRef))
+                        issues.push({ path: ["templates", i, "slots", j, "members", k, "modelRef"], message: `collab template "${t.id}" slot "${s.id}" → unknown model "${mem.modelRef}" (not in the catalog)`, code: "custom" });
+                });
+            });
+        });
+    }
+    else if (domain === "systems") {
+        // systems.callsWorkers → workers domain (a dangling name would mint a credential routed at nobody;
+        // resolution stays tolerant — this is the save-time guard, same as the other ref-checked domains).
+        const workers = new Set((await resolve("workers"))?.workers.map((w) => w.name) ?? []);
+        value.systems.forEach((sys, i) => {
+            sys.callsWorkers.forEach((name, j) => {
+                if (!workers.has(name))
+                    issues.push({ path: ["systems", i, "callsWorkers", j], message: `system "${sys.name}" references unknown worker "${name}"`, code: "custom" });
+            });
+        });
+    }
+    else if (domain === "entitlement") {
+        // A tier references FIVE sibling domains by name (roster→rosters, models[]→models catalog, visibleSkills→
+        // skills, visibleMcp→mcp, visiblePlugins→plugins). A dangling ref otherwise resolves silently (e.g. a typo'd roster → resolve-
+        // entitlement yields an empty set → the principal is silently denied) — a precise 400 at save time is
+        // friendlier, matching the rosters/workers guards.
+        const rosterNames = new Set(((await resolve("rosters"))?.rosters ?? []).map((r) => r.name));
+        const modelCatalog = new Set(((await resolve("models"))?.models ?? []).map((m) => m.name));
+        const skillNames = new Set((await resolve("skills"))?.skills.map((s) => s.name) ?? []);
+        const mcpNames = new Set((await resolve("mcp"))?.servers.map((s) => s.name) ?? []);
+        const pluginNames = new Set((await resolve("plugins"))?.plugins.map((p) => p.name) ?? []);
+        value.tiers.forEach((t, i) => {
+            if (t.roster && !rosterNames.has(t.roster))
+                issues.push({ path: ["tiers", i, "roster"], message: `tier "${t.id}" references unknown roster "${t.roster}"`, code: "custom" });
+            (t.models ?? []).forEach((name, j) => { if (!modelCatalog.has(name))
+                issues.push({ path: ["tiers", i, "models", j], message: `tier "${t.id}" model "${name}" not in the models catalog`, code: "custom" }); });
+            (t.visibleSkills ?? []).forEach((name, j) => { if (!skillNames.has(name))
+                issues.push({ path: ["tiers", i, "visibleSkills", j], message: `tier "${t.id}" visibleSkill "${name}" not in skills`, code: "custom" }); });
+            (t.visibleMcp ?? []).forEach((name, j) => { if (!mcpNames.has(name))
+                issues.push({ path: ["tiers", i, "visibleMcp", j], message: `tier "${t.id}" visibleMcp "${name}" not in mcp`, code: "custom" }); });
+            (t.visiblePlugins ?? []).forEach((name, j) => { if (!pluginNames.has(name))
+                issues.push({ path: ["tiers", i, "visiblePlugins", j], message: `tier "${t.id}" visiblePlugin "${name}" not in plugins`, code: "custom" }); });
+        });
+    }
+    else {
+        // Exhaustiveness guard: a new RefCheckedDomain MUST add its own branch above, not silently inherit another
+        // domain's validation. `never` makes that a compile error; the throw is the runtime backstop.
+        const unhandled = domain;
+        throw new Error(`refIntegrityIssues: unhandled domain "${String(unhandled)}"`);
+    }
+    return issues;
+}