@sema-agent/settings-schema 14.7.0 → 14.8.0

package/dist/env-model-table.d.ts

@@ -0,0 +1,163 @@
+import { type EnvModelsDecision } from "./config-root-documents.js";
+import { SUMMARIZE_MODEL_MISSING_CODE } from "./fleet.js";
+import type { ModelRole } from "./types.js";
+/** 一份 env 快照(`process.env` 也满足这个形)。 */
+export type EnvSnapshot = Readonly<Record<string, string | undefined>>;
+/** env 模型表的键名(闭集)。 */
+export declare const ENV_MODEL_TABLE_KEYS: {
+    readonly mainId: "MODEL_ID";
+    readonly cheapId: "MODEL_CHEAP_ID";
+    readonly verifier: "MODEL_VERIFIER";
+    readonly codeRoles: "MODEL_CODE_ROLES";
+};
+/** env 模型表的一把键名。 */
+export type EnvModelTableKey = (typeof ENV_MODEL_TABLE_KEYS)[keyof typeof ENV_MODEL_TABLE_KEYS];
+/** env 表里主模型的别名键(角色底的 `default` 绑它;引擎 env 表的条目键 = 这个别名 + 主 id + cheap id)。 */
+export declare const DEFAULT_MODEL_KEY: "default";
+/**
+ * env 表的 **cheap 槽**铸不铸(闭集四态,消费方穷举 `switch`;{@link mintedCheapId}):
+ *  · `absent` —— 没设(或空串);
+ *  · `without_main` —— 设了而主槽没设:cheap 槽是主模型「同网关换个 id」的形,没有主槽就没有它 ⇒ 不铸;
+ *  · `same_as_main` —— 与主 id 相同:说的就是主模型 ⇒ 不铸;
+ *  · `minted` —— 铸(`id` = `MODEL_CHEAP_ID`)。
+ */
+export type EnvCheapSlot = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "without_main" | "same_as_main" | "minted";
+    readonly id: string;
+};
+/** cheap 槽铸出来的 id(不铸 ⇒ `undefined`)。 */
+export declare function mintedCheapId(slot: EnvCheapSlot): string | undefined;
+/**
+ * 包内(不进包根):把 env 模型表的键(缺省四把;调用方只要两槽时只拍两把)**读一次**进一份快照(下标读,同「读到即算」)。计划助手与一次性迁移在**要用的那一刻**拍、
+ * 此后的每个读法都答自同一份 —— 一只 getter 两次读答两个值时,判「env 表已声明」与列 env 模型不会各读到一个(那样结局与回执自相矛盾);用不到的键不读。
+ */
+export declare function snapshotEnvModelTable(env: EnvSnapshot, keys?: readonly EnvModelTableKey[]): EnvSnapshot;
+/** env 两槽的**唯一读口**(见文件头)。`mainId` = `MODEL_ID`(空串 = 没有主槽)。 */
+export declare function readEnvModelSlots(env: EnvSnapshot): {
+    readonly mainId: string;
+    readonly cheapSlot: EnvCheapSlot;
+};
+/** **env 模型表已声明吗**(= `MODEL_ID` 在场且非空串;纯空白算在场)—— 引擎一侧的顶替闸(今天还不强制)与计划助手共用的那一只谓词。 */
+export declare function envModelTableDeclared(env: EnvSnapshot): boolean;
+/** env 表里的一条模型(槽序 main → cheap)。 */
+export interface EnvModelTableEntry {
+    readonly id: string;
+    readonly slot: "main" | "cheap";
+    readonly env: typeof ENV_MODEL_TABLE_KEYS.mainId | typeof ENV_MODEL_TABLE_KEYS.cheapId;
+}
+/** env 底的一个角色绑定:env 表键(别名 `default`、主 id 或 cheap id),或带开发模式提示词标记的同一个键(`MODEL_CODE_ROLES`)。 */
+export type EnvRoleBinding = string | {
+    readonly model: string;
+    readonly promptRole: "code";
+};
+/** env 模型表铸出来的全部事实(纯数据)。 */
+export interface EnvModelBaseline {
+    readonly entries: readonly EnvModelTableEntry[];
+    /** 角色 → env 表键(键序 verifier → default → subagent → summarize)。 */
+    readonly roles: Readonly<Partial<Record<ModelRole, EnvRoleBinding>>>;
+    /** `MODEL_VERIFIER` 的读数:未设 / 指 env 表里的一个键 / 指表外(⇒ verifier 落 `default`,由消费方告警)。 */
+    readonly verifier: {
+        readonly kind: "unset";
+    } | {
+        readonly kind: "bound";
+        readonly ref: string;
+    } | {
+        readonly kind: "rejected";
+        readonly raw: string;
+    };
+}
+/**
+ * env 模型表的**角色底**(纯数据):条目(主槽在 ⇒ 主;cheap 槽铸了 ⇒ cheap)、角色(verifier ⇒ `MODEL_VERIFIER` 指 env 表里的键时是它、否则 `default`;
+ * 主角色族(`ROSTER_PRIMARY_ROLES`)⇒ `default`;cheap 角色族(`ROSTER_CHEAP_ROLES`)⇒ cheap id,cheap 没铸 ⇒ `default`;`MODEL_CODE_ROLES` 点名的、角色底自己有的键
+ * 加开发模式提示词标记)。env 表键 = 别名 `default` + 主 id + cheap id(主槽不在 ⇒ 表空)。
+ */
+export declare function buildEnvModelBaseline(env: EnvSnapshot): EnvModelBaseline;
+/** 目标引擎读哪条配置腿:`local` = 读配置根的 `config.d`;`remote` = 读中心;`none` = 纯 env 部署,不读 `config.d`。 */
+export type EnvModelTableTarget = "local" | "remote" | "none";
+/** 一个落点:目录条目的名与它的上游 id。 */
+export interface EnvModelTableLanding {
+    readonly name: string;
+    readonly id: string;
+}
+/** 回执的一个角色行。`before.id = null` ⇒ env 表空,这个键在写前不解到任何 env 模型。 */
+export interface EnvModelTableRoleRow {
+    readonly role: string;
+    readonly before: {
+        readonly ref: string;
+        readonly id: string | null;
+    };
+    readonly promptRole?: "code";
+    /** `candidate_binds` = 候选自己的 `roles` 绑了这个角色({select} ⇒ `landing: null`);`catalog_default` = 落到目录缺省(env 底绑别名 `default`,或 `default` 角色本身
+     *  —— 它恒落在缺省解析器的答案上;候选把它绑到停用条目时解析器落到下一级;{select} 缺省 ⇒ `null`);
+     *  `candidate_entry` = env 底绑的名在候选目录里解得到(一条启用条目的名,或经活跃档位组展开的档位词 / 别名);`dangles` = 落不到任何启用条目。 */
+    readonly after: {
+        readonly kind: "candidate_binds" | "catalog_default" | "candidate_entry" | "dangles";
+        readonly landing: EnvModelTableLanding | null;
+    };
+}
+/** 回执(纯数据;确认键 = 它的定序 JSON)。 */
+export interface EnvModelTableReceipt {
+    /** 配置根的决定读数(`readEnvModelsDecision` 的 `kind`):读不懂的会在确认后被整份覆盖。 */
+    readonly decision: EnvModelsDecision["kind"];
+    /** 退场的 env 条目(槽序);`servedAs` = 候选里同 id 的启用条目名。 */
+    readonly envModels: readonly (EnvModelTableEntry & {
+        readonly servedAs: readonly string[];
+    })[];
+    readonly roles: readonly EnvModelTableRoleRow[];
+}
+/** 调用方带回的确认:上一次 `confirm` 给的键。 */
+export interface EnvModelTableWriteIntent {
+    readonly kind: "replace";
+    readonly confirmKey: string;
+}
+export interface EnvModelTableWriteInput {
+    /** 目标引擎起服看到的 env(只用于预测与回执;引擎用它自己的 env 复判)。 */
+    readonly env: EnvSnapshot;
+    readonly target: EnvModelTableTarget;
+    /** 配置根上的决定读数(`readEnvModelsDecision` 的答案)。 */
+    readonly decision: EnvModelsDecision;
+    /** 将要原子写入的完整 models 文档。 */
+    readonly candidate: unknown;
+    readonly intent?: EnvModelTableWriteIntent;
+}
+/** 计划(闭集;写者穷举 `switch`)。 */
+export type EnvModelTableWritePlan = {
+    readonly kind: "write";
+    readonly why: "not_read" | "not_managing" | "env_table_empty";
+} | {
+    readonly kind: "write";
+    readonly why: "acknowledged";
+    readonly receipt: EnvModelTableReceipt;
+}
+/** 先写 `config.env-models.json = replaced`(`writeEnvModelsDecision(root, "replaced", { write: "overwrite" })`),再写 models.json。 */
+ | {
+    readonly kind: "write_with_decision";
+    readonly receipt: EnvModelTableReceipt;
+}
+/** 把回执给用户看;用户确认 ⇒ 带 `{ kind: "replace", confirmKey }` 再调一次。`intent`:没带过键 `absent` / 带的键已过期 `stale`。 */
+ | {
+    readonly kind: "confirm";
+    readonly receipt: EnvModelTableReceipt;
+    readonly confirmKey: string;
+    readonly intent: "absent" | "stale";
+}
+/** 不可确认:先改文档(summarize 要落到一条启用条目)。 */
+ | {
+    readonly kind: "fix_first";
+    readonly code: typeof SUMMARIZE_MODEL_MISSING_CODE;
+    readonly receipt: EnvModelTableReceipt;
+};
+/**
+ * 写者在写 `config.d/models.json` 之前调的**计划**(判序见文件头)。纯函数:不读环境、不读盘、不改入参。
+ * 目标腿 / 决定读数不在闭集 ⇒ `TypeError`;候选读不出(撤销的 Proxy 等)或整份读不进 models 域(重名、悬空的角色名 …)⇒ `TypeError`(先修文档)。
+ */
+export declare function planEnvModelTableWrite(input: EnvModelTableWriteInput): EnvModelTableWritePlan;
+/**
+ * 计划停下来的那两种结局(`confirm` / `fix_first`)的**一句话**(三端同一句;只用回执里的 env 键名、目录名与模型 id —— 可披露的原样,秘密形的打成记号;凭据与别的 env 值从不进句子)。
+ * 写类结局不是拒 ⇒ `TypeError`。
+ */
+export declare function envModelTableWriteRefusal(plan: Extract<EnvModelTableWritePlan, {
+    readonly kind: "confirm" | "fix_first";
+}>): string;

package/dist/env-model-table.js

@@ -0,0 +1,257 @@
+/**
+ * env 模型表 —— `MODEL_ID` / `MODEL_CHEAP_ID` 两槽与它们铸出的角色底 —— 的**一份读法**,与写者在写 `config.d/models.json` 之前调的**计划助手**
+ * (纯、零 I/O、浏览器安全;读配置根上的决定文档的函数在 `./node`)。
+ *
+ * ## 律
+ *  · **env 两槽只在这里读一次**({@link readEnvModelSlots}):`MODEL_ID` 缺席或空串 = 没有主槽(纯空白算在场 —— 与引擎的 env 路由读口同尺);
+ *    cheap 槽四态({@link EnvCheapSlot})。「env 模型表已声明」({@link envModelTableDeclared})与角色底({@link buildEnvModelBaseline})都由它派生 ——
+ *    这道闸的执行方(引擎一侧;今天引擎还不强制)与写者的计划助手调同一份(一次性迁移 SS-M11 只用两槽点名被顶替的 env 模型,铸不铸不看它),不各写一份。env 快照按「读到即算」(下标读;原型分层的快照里继承来的键算在场)。
+ *    引擎另有「名册占位 ⇒ env 表算空」一格,那是引擎自己的部署事实,不在本包。
+ *  · **计划助手判序**({@link planEnvModelTableWrite}):目标腿不读 `config.d`(remote / none)⇒ 照写 → 候选不管模型面 ⇒ 照写 → summarize 会悬空 ⇒
+ *    `fix_first`(不可确认:每个任务都要解 summarize,采纳后任务全拒)→ env 表未声明 ⇒ 照写、**不写确认** → 配置根的决定是 `replaced` ⇒ 照写 →
+ *    调用方带回的确认键等于这一次的 ⇒ `write_with_decision`(先经 `writeEnvModelsDecision` 写 `replaced`,再写目录;两次写在写者对 models.json 的同一把锁里)→
+ *    否则 `confirm`(把回执给用户看)。执法在引擎一侧(本地腿的顶替闸;今天引擎不拒这个组),本助手只是让写者在写之前知道这道闸强制起来会不会拒、会顶掉什么。
+ *  · **回执按 id**:每个退场的 env 条目带 `servedAs`(候选里同 id 的启用条目名 —— 上游模型仍被服务,形可能不同);每个 env 底角色带写前绑谁
+ *    (env 表键 + 它解到的 id)与采纳后落到哪个条目(`{name, id}`)。缺省落点经 `resolveCatalogDefaultModel`(与引擎的 stage 同一只解析器);
+ *    绑到停用条目或目录外的名 = `dangles`。确认键 = 回执的定序 JSON —— 后果(落点名 / id、env 槽、决定读数)一变,旧键就过期。
+ *  · 可用性(引擎的 brain 腿、端点、读腿逐条丢)计划判不了;决定性的 summarize 那一格由引擎的不变量兜。
+ */
+import { z } from "zod";
+import { entryEnabledFlag, catalogManagesModelPlane } from "./catalog-manages.js";
+import { parseDomainSalvaged, isDisclosableIdentity, resolveActiveTiers, withheldNameToken } from "./config-fns.js";
+import { ENV_MODELS_DOCUMENT } from "./config-root-documents.js";
+import { resolveCatalogDefaultModel } from "./default-model.js";
+import { SUMMARIZE_MODEL_MISSING_CODE } from "./fleet.js";
+import { landCatalogWord } from "./tier-words.js";
+import { stableStringify } from "./hash.js";
+import { captureJson, dataDescriptor, isolatedObject } from "./own-key-read.js";
+import { ROSTER_CHEAP_ROLES, ROSTER_PRIMARY_ROLES } from "./resolve-roster.js";
+/** env 模型表的键名(闭集)。 */
+export const ENV_MODEL_TABLE_KEYS = { mainId: "MODEL_ID", cheapId: "MODEL_CHEAP_ID", verifier: "MODEL_VERIFIER", codeRoles: "MODEL_CODE_ROLES" };
+/** env 表里主模型的别名键(角色底的 `default` 绑它;引擎 env 表的条目键 = 这个别名 + 主 id + cheap id)。 */
+export const DEFAULT_MODEL_KEY = "default";
+/** cheap 槽铸出来的 id(不铸 ⇒ `undefined`)。 */
+export function mintedCheapId(slot) {
+    switch (slot.kind) {
+        case "minted":
+            return slot.id;
+        case "absent":
+        case "without_main":
+        case "same_as_main":
+            return undefined;
+        default: {
+            const unhandled = slot;
+            throw new Error(`mintedCheapId: unhandled slot ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * 包内(不进包根):把 env 模型表的键(缺省四把;调用方只要两槽时只拍两把)**读一次**进一份快照(下标读,同「读到即算」)。计划助手与一次性迁移在**要用的那一刻**拍、
+ * 此后的每个读法都答自同一份 —— 一只 getter 两次读答两个值时,判「env 表已声明」与列 env 模型不会各读到一个(那样结局与回执自相矛盾);用不到的键不读。
+ */
+export function snapshotEnvModelTable(env, keys = Object.values(ENV_MODEL_TABLE_KEYS)) {
+    const snapshot = isolatedObject(); // the package's copy container (no inherited members to read)
+    for (const key of keys)
+        Object.defineProperty(snapshot, key, dataDescriptor(env[key]));
+    return snapshot;
+}
+/** env 两槽的**唯一读口**(见文件头)。`mainId` = `MODEL_ID`(空串 = 没有主槽)。 */
+export function readEnvModelSlots(env) {
+    const mainId = env[ENV_MODEL_TABLE_KEYS.mainId] ?? "";
+    const rawCheapId = env[ENV_MODEL_TABLE_KEYS.cheapId];
+    const cheapSlot = !rawCheapId
+        ? { kind: "absent" }
+        : mainId === ""
+            ? { kind: "without_main", id: rawCheapId }
+            : rawCheapId === mainId
+                ? { kind: "same_as_main", id: rawCheapId }
+                : { kind: "minted", id: rawCheapId };
+    return { mainId, cheapSlot };
+}
+/** **env 模型表已声明吗**(= `MODEL_ID` 在场且非空串;纯空白算在场)—— 引擎一侧的顶替闸(今天还不强制)与计划助手共用的那一只谓词。 */
+export function envModelTableDeclared(env) {
+    return readEnvModelSlots(env).mainId !== "";
+}
+/** 逗号串:逐项 trim、丢空项。 */
+const csv = (raw) => (raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+/**
+ * env 模型表的**角色底**(纯数据):条目(主槽在 ⇒ 主;cheap 槽铸了 ⇒ cheap)、角色(verifier ⇒ `MODEL_VERIFIER` 指 env 表里的键时是它、否则 `default`;
+ * 主角色族(`ROSTER_PRIMARY_ROLES`)⇒ `default`;cheap 角色族(`ROSTER_CHEAP_ROLES`)⇒ cheap id,cheap 没铸 ⇒ `default`;`MODEL_CODE_ROLES` 点名的、角色底自己有的键
+ * 加开发模式提示词标记)。env 表键 = 别名 `default` + 主 id + cheap id(主槽不在 ⇒ 表空)。
+ */
+export function buildEnvModelBaseline(env) {
+    const { mainId, cheapSlot } = readEnvModelSlots(env);
+    const cheapId = mintedCheapId(cheapSlot);
+    const entries = mainId === "" ? [] : [{ id: mainId, slot: "main", env: ENV_MODEL_TABLE_KEYS.mainId }, ...(cheapId === undefined ? [] : [{ id: cheapId, slot: "cheap", env: ENV_MODEL_TABLE_KEYS.cheapId }])];
+    const tableKeys = new Set(mainId === "" ? [] : [DEFAULT_MODEL_KEY, mainId, ...(cheapId === undefined ? [] : [cheapId])]);
+    const rawVerifier = env[ENV_MODEL_TABLE_KEYS.verifier];
+    const verifier = !rawVerifier ? { kind: "unset" } : tableKeys.has(rawVerifier) ? { kind: "bound", ref: rawVerifier } : { kind: "rejected", raw: rawVerifier };
+    const roles = new Map([["verifier", verifier.kind === "bound" ? verifier.ref : DEFAULT_MODEL_KEY]]);
+    for (const r of ROSTER_PRIMARY_ROLES)
+        roles.set(r, DEFAULT_MODEL_KEY);
+    for (const r of ROSTER_CHEAP_ROLES)
+        roles.set(r, cheapId ?? DEFAULT_MODEL_KEY);
+    for (const name of csv(env[ENV_MODEL_TABLE_KEYS.codeRoles])) {
+        const role = name;
+        const cur = roles.get(role);
+        if (cur === undefined)
+            continue; // 只装饰角色底自己有的键(Map 没有原型上的名字)
+        roles.set(role, { model: typeof cur === "string" ? cur : cur.model, promptRole: "code" });
+    }
+    return { entries, roles: Object.fromEntries(roles), verifier };
+}
+const ENV_MODEL_TABLE_TARGETS = ["local", "remote", "none"];
+const decisionKindOf = (decision) => {
+    const kind = decision?.kind;
+    switch (kind) {
+        case "absent":
+        case "replaced":
+        case "kept":
+        case "unreadable":
+            return kind;
+        default:
+            throw new TypeError(`planEnvModelTableWrite: decision must be a readEnvModelsDecision answer (got kind ${JSON.stringify(kind)})`);
+    }
+};
+/** 候选按引擎本地读腿的视图读(逐条抢救;整份读不进 ⇒ 抛 TypeError —— 引擎读不进的文档,本助手不替它算回执,先修文档)。 */
+function candidateView(candidate) {
+    try {
+        return parseDomainSalvaged("models", candidate);
+    }
+    catch (e) {
+        const first = e instanceof z.ZodError ? e.issues[0] : undefined;
+        const why = first === undefined ? (e instanceof Error ? e.message : String(e)) : `${first.path.join(".") || "(document)"}: ${first.message}`;
+        throw new TypeError(`planEnvModelTableWrite: the candidate does not read as a models document — fix it first (${why})`);
+    }
+}
+function buildReceipt(baseline, view, decision) {
+    const enabled = view.models.filter((m) => entryEnabledFlag(m) !== false).map((m) => ({ name: m.name, id: m.id }));
+    const byName = new Map(enabled.map((e) => [e.name, e]));
+    const tiers = resolveActiveTiers(view);
+    /** 一个名采纳后落到哪条:经与引擎同一张档位展开(目录键先赢;env 底继承来的 `flash` 一类档位词按活跃组解)。 */
+    const land = (word) => {
+        const name = landCatalogWord(word, (n) => byName.has(n), tiers);
+        const e = name === undefined ? undefined : byName.get(name);
+        return e === undefined ? undefined : { name: e.name, id: e.id };
+    };
+    const main = baseline.entries.find((e) => e.slot === "main");
+    const idOf = (ref) => (ref === DEFAULT_MODEL_KEY ? (main?.id ?? null) : (baseline.entries.find((e) => e.id === ref)?.id ?? null));
+    /** 目录缺省的落点 —— 恒是 `resolveCatalogDefaultModel` 的答案(与引擎的 stage 同一只解析器;它的第一级就是候选自己的 `roles.default`,点名停用条目时它落到下一级)。
+     *  `bound` = 候选自己绑了 `default`:解析器用的正是那一级 ⇒ `candidate_binds`,否则 `catalog_default`。 */
+    const viaCatalogDefault = (bound) => {
+        const fallback = enabled[0];
+        if (fallback === undefined)
+            return { kind: "dangles", landing: null };
+        const d = resolveCatalogDefaultModel(view, (n) => byName.has(n), fallback.name);
+        if (d.kind === "select")
+            return { kind: bound ? "candidate_binds" : "catalog_default", landing: null };
+        const l = land(d.name);
+        if (l === undefined)
+            return { kind: "dangles", landing: null };
+        return { kind: bound && d.source === "roles.default" ? "candidate_binds" : "catalog_default", landing: l };
+    };
+    const afterOf = (role, ref) => {
+        const bound = Object.hasOwn(view.roles, role) ? view.roles[role] : undefined;
+        if (role === DEFAULT_MODEL_KEY)
+            return viaCatalogDefault(bound !== undefined); // the default role lands where the catalog default resolves, bound or not
+        if (bound !== undefined) {
+            if (!("model" in bound))
+                return { kind: "candidate_binds", landing: null };
+            const l = land(bound.model);
+            return l === undefined ? { kind: "dangles", landing: null } : { kind: "candidate_binds", landing: l };
+        }
+        if (ref === DEFAULT_MODEL_KEY)
+            return viaCatalogDefault(false);
+        const l = land(ref);
+        return l === undefined ? { kind: "dangles", landing: null } : { kind: "candidate_entry", landing: l };
+    };
+    return {
+        decision,
+        envModels: baseline.entries.map((e) => ({ id: e.id, slot: e.slot, env: e.env, servedAs: enabled.filter((c) => c.id === e.id).map((c) => c.name) })),
+        roles: Object.entries(baseline.roles).map(([role, spec]) => {
+            const ref = typeof spec === "string" ? spec : spec.model;
+            const promptRole = typeof spec === "string" ? undefined : spec.promptRole;
+            return { role, before: { ref, id: idOf(ref) }, ...(promptRole === undefined ? {} : { promptRole }), after: afterOf(role, ref) };
+        }),
+    };
+}
+/**
+ * 写者在写 `config.d/models.json` 之前调的**计划**(判序见文件头)。纯函数:不读环境、不读盘、不改入参。
+ * 目标腿 / 决定读数不在闭集 ⇒ `TypeError`;候选读不出(撤销的 Proxy 等)或整份读不进 models 域(重名、悬空的角色名 …)⇒ `TypeError`(先修文档)。
+ */
+export function planEnvModelTableWrite(input) {
+    const decision = decisionKindOf(input.decision);
+    const target = input.target;
+    if (!ENV_MODEL_TABLE_TARGETS.includes(target))
+        throw new TypeError(`planEnvModelTableWrite: target must be one of ${ENV_MODEL_TABLE_TARGETS.join(" / ")} (got ${JSON.stringify(target)})`);
+    switch (target) {
+        case "remote":
+        case "none":
+            return { kind: "write", why: "not_read" };
+        case "local":
+            break;
+        default: {
+            const unhandled = target;
+            throw new TypeError(`planEnvModelTableWrite: unhandled target ${JSON.stringify(unhandled)}`);
+        }
+    }
+    const copy = captureJson(input.candidate);
+    if (!copy.ok)
+        throw new TypeError(`planEnvModelTableWrite: the candidate could not be read — ${copy.sentence}`);
+    if (!catalogManagesModelPlane(copy.value))
+        return { kind: "write", why: "not_managing" };
+    const env = snapshotEnvModelTable(input.env); // read once: the receipt and the env-table rule answer from the same reading
+    const receipt = buildReceipt(buildEnvModelBaseline(env), candidateView(copy.value), decision);
+    if (receipt.roles.find((r) => r.role === "summarize")?.after.kind === "dangles")
+        return { kind: "fix_first", code: SUMMARIZE_MODEL_MISSING_CODE, receipt };
+    if (!envModelTableDeclared(env))
+        return { kind: "write", why: "env_table_empty" };
+    if (decision === "replaced")
+        return { kind: "write", why: "acknowledged", receipt };
+    const confirmKey = stableStringify(receipt);
+    const intent = input.intent;
+    if (intent !== undefined && intent.kind === "replace" && intent.confirmKey === confirmKey)
+        return { kind: "write_with_decision", receipt };
+    return { kind: "confirm", receipt, confirmKey, intent: intent === undefined ? "absent" : "stale" };
+}
+// ── 拒句投影 ─────────────────────────────────────────────────────────────────────────────────────────────
+/** 句子里的一个名 / id:可披露 ⇒ 原样(加引号);否则 ⇒ 不可逆记号(秘密形不出门)。 */
+const shown = (v) => (isDisclosableIdentity(v) ? JSON.stringify(v) : withheldNameToken(v));
+const landingText = (after) => {
+    if (after.landing !== null)
+        return `${shown(after.landing.name)} (id ${shown(after.landing.id)})`;
+    return after.kind === "dangles" ? "nothing (no enabled catalog entry)" : "an entry the engine selects ({select})";
+};
+/**
+ * 计划停下来的那两种结局(`confirm` / `fix_first`)的**一句话**(三端同一句;只用回执里的 env 键名、目录名与模型 id —— 可披露的原样,秘密形的打成记号;凭据与别的 env 值从不进句子)。
+ * 写类结局不是拒 ⇒ `TypeError`。
+ */
+export function envModelTableWriteRefusal(plan) {
+    const file = `${ENV_MODELS_DOCUMENT}.json`;
+    const kind = plan.kind;
+    switch (kind) {
+        case "confirm": {
+            const r = plan.receipt;
+            const models = r.envModels.map((e) => `${e.env} ${shown(e.id)} (${e.slot} slot) ${e.servedAs.length > 0 ? `stays served as ${e.servedAs.map(shown).join(", ")}` : "stops being served"}`).join("; ");
+            const roles = r.roles.map((row) => `${row.role} → ${landingText(row.after)}`).join(", ");
+            const decision = r.decision === "unreadable"
+                ? ` The config root's ${file} is unreadable; confirming overwrites it as a whole.`
+                : r.decision === "kept"
+                    ? ` The config root's ${file} says "kept"; confirming overwrites it.`
+                    : "";
+            return (`writing this models document replaces the env model table on the local config leg: ${models}; after adoption ${roles}.${decision} ` +
+                `To let the catalog replace them, confirm — the writer records ${file} = {"envModels":"replaced"} in the config root first, then writes the models document; to keep the env models, do not write it.`);
+        }
+        case "fix_first": {
+            const row = plan.receipt.roles.find((x) => x.role === "summarize");
+            const ref = row === undefined ? "" : ` (env binding ${shown(row.before.ref)})`;
+            return (`this models document leaves the summarize role unresolved${ref}: it lands on no enabled catalog entry, so every task would be refused after adoption (${SUMMARIZE_MODEL_MISSING_CODE}). ` +
+                "Bind roles.summarize to an enabled entry of the document, or add an enabled entry under the name it points at, then plan the write again.");
+        }
+        default:
+            throw new TypeError(`envModelTableWriteRefusal: only a "confirm" or "fix_first" plan is a refusal (got ${JSON.stringify(kind)})`);
+    }
+}

package/dist/fleet.d.ts

@@ -163,9 +163,15 @@ export type RestartSignal = z.infer<typeof RestartSignal>;
  *    `config.model_refused_name_minted` — a refused entry's name would be re-minted onto another entry by the
  *    tier / alias expansion (or the dropped-entry carrier cannot prove it would not be);
  *    `config.model_route_endpoint_missing` — an openai-compatible route of the candidate resolves to no endpoint;
- *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary.
- *    Source (engine): the first two in `src/model-entry-refusal.ts`, the last two in `src/model-route-endpoint.ts:40,42`
- *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`).
+ *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary;
+ *    `config.catalog_replaces_env_models` ({@link CATALOG_REPLACES_ENV_MODELS_CODE}) — on the LOCAL config leg, a candidate that
+ *    manages the model plane would replace a declared env model table (`MODEL_ID` …) while the config root's decision document
+ *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving;
+ *    `config.summarize_model_missing` ({@link SUMMARIZE_MODEL_MISSING_CODE}) — the summarize role, which every task resolves,
+ *    would land on no servable entry (every task would be refused after adoption).
+ *    Source (engine): the first two in `src/model-entry-refusal.ts`, the next two in `src/model-route-endpoint.ts:40,42`
+ *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`); the
+ *    last two are named HERE first (the code is a contract word: this package names it and exports the two constants for the engine to read; the engine does not mint them today).
  */
 export declare const MODEL_ENTRY_REFUSAL_CODES: readonly ["config.model_no_brain", "config.model_entry_invalid"];
 export declare const ModelEntryRefusalCode: z.ZodEnum<{
@@ -173,8 +179,14 @@ export declare const ModelEntryRefusalCode: z.ZodEnum<{
     "config.model_entry_invalid": "config.model_entry_invalid";
 }>;
 export type ModelEntryRefusalCode = z.infer<typeof ModelEntryRefusalCode>;
-export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary"];
+/** The env-model-table confirmation gate's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}). */
+export declare const CATALOG_REPLACES_ENV_MODELS_CODE: "config.catalog_replaces_env_models";
+/** The summarize invariant's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}); a writer's plan answers `fix_first` with it. */
+export declare const SUMMARIZE_MODEL_MISSING_CODE: "config.summarize_model_missing";
+export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary", "config.catalog_replaces_env_models", "config.summarize_model_missing"];
 export declare const ModelPlaneRefusalCode: z.ZodEnum<{
+    "config.catalog_replaces_env_models": "config.catalog_replaces_env_models";
+    "config.summarize_model_missing": "config.summarize_model_missing";
     "config.default_model_missing": "config.default_model_missing";
     "config.model_refused_name_minted": "config.model_refused_name_minted";
     "config.model_route_endpoint_missing": "config.model_route_endpoint_missing";
@@ -566,9 +578,15 @@ export declare const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
  *  - {@link SERVING_LEASE_TTL_DEFAULT_MS} — the lease length when the operator sets none (10 min).
  *  - {@link SERVING_LEASE_TTL_FLOOR_MS} — the shortest lease there is: a configured TTL below it is treated as it (1 min),
  *    the same way {@link DRAIN_GRACE_FLOOR_MS} protects a fat-fingered grace.
- *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — web-admin's clock-skew allowance: it adds this to a lease's recorded expiry
- *    before it counts that lease as over. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a
- *    second constant that could drift from it.
+ *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — the clock-skew allowance for reading a lease deadline an engine REPORTS. The engine
+ *    says `EngineSignal.leaseUntil` (epoch ms: its own computation from the granted `ttlMs`, on its own clock); a reader that asks
+ *    "does this member's lease still hold?" compares that instant with ITS OWN now — two clocks that need not agree — so it counts
+ *    the lease as held only while `leaseUntil >= now + SERVING_LEASE_DRIFT_MARGIN_MS`. That is the conservative direction: a skew
+ *    up to the margin can make a lease that still holds read as short, never one that is over read as held. It is an allowance for
+ *    reading a reported deadline, not part of the lease clock: the engine enforces the lease on its own monotonic clock and
+ *    web-admin keeps its own expiry from its store time (see {@link ServingLeaseResponse}) — the two sides never compare clocks
+ *    to enforce. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a second constant that could
+ *    drift from it.
  */
 export declare const SERVING_LEASE_TTL_DEFAULT_MS = 600000;
 export declare const SERVING_LEASE_TTL_FLOOR_MS = 60000;

package/dist/fleet.js

@@ -231,17 +231,29 @@ function readSignalBody(body, pick, schema) {
  *    `config.model_refused_name_minted` — a refused entry's name would be re-minted onto another entry by the
  *    tier / alias expansion (or the dropped-entry carrier cannot prove it would not be);
  *    `config.model_route_endpoint_missing` — an openai-compatible route of the candidate resolves to no endpoint;
- *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary.
- *    Source (engine): the first two in `src/model-entry-refusal.ts`, the last two in `src/model-route-endpoint.ts:40,42`
- *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`).
+ *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary;
+ *    `config.catalog_replaces_env_models` ({@link CATALOG_REPLACES_ENV_MODELS_CODE}) — on the LOCAL config leg, a candidate that
+ *    manages the model plane would replace a declared env model table (`MODEL_ID` …) while the config root's decision document
+ *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving;
+ *    `config.summarize_model_missing` ({@link SUMMARIZE_MODEL_MISSING_CODE}) — the summarize role, which every task resolves,
+ *    would land on no servable entry (every task would be refused after adoption).
+ *    Source (engine): the first two in `src/model-entry-refusal.ts`, the next two in `src/model-route-endpoint.ts:40,42`
+ *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`); the
+ *    last two are named HERE first (the code is a contract word: this package names it and exports the two constants for the engine to read; the engine does not mint them today).
  */
 export const MODEL_ENTRY_REFUSAL_CODES = ["config.model_no_brain", "config.model_entry_invalid"];
 export const ModelEntryRefusalCode = z.enum(MODEL_ENTRY_REFUSAL_CODES);
+/** The env-model-table confirmation gate's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}). */
+export const CATALOG_REPLACES_ENV_MODELS_CODE = "config.catalog_replaces_env_models";
+/** The summarize invariant's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}); a writer's plan answers `fix_first` with it. */
+export const SUMMARIZE_MODEL_MISSING_CODE = "config.summarize_model_missing";
 export const MODEL_PLANE_REFUSAL_CODES = [
     "config.default_model_missing",
     "config.model_refused_name_minted",
     "config.model_route_endpoint_missing",
     "config.gateway_fallback_without_primary",
+    CATALOG_REPLACES_ENV_MODELS_CODE,
+    SUMMARIZE_MODEL_MISSING_CODE,
 ];
 export const ModelPlaneRefusalCode = z.enum(MODEL_PLANE_REFUSAL_CODES);
 /**
@@ -594,9 +606,15 @@ export const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
  *  - {@link SERVING_LEASE_TTL_DEFAULT_MS} — the lease length when the operator sets none (10 min).
  *  - {@link SERVING_LEASE_TTL_FLOOR_MS} — the shortest lease there is: a configured TTL below it is treated as it (1 min),
  *    the same way {@link DRAIN_GRACE_FLOOR_MS} protects a fat-fingered grace.
- *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — web-admin's clock-skew allowance: it adds this to a lease's recorded expiry
- *    before it counts that lease as over. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a
- *    second constant that could drift from it.
+ *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — the clock-skew allowance for reading a lease deadline an engine REPORTS. The engine
+ *    says `EngineSignal.leaseUntil` (epoch ms: its own computation from the granted `ttlMs`, on its own clock); a reader that asks
+ *    "does this member's lease still hold?" compares that instant with ITS OWN now — two clocks that need not agree — so it counts
+ *    the lease as held only while `leaseUntil >= now + SERVING_LEASE_DRIFT_MARGIN_MS`. That is the conservative direction: a skew
+ *    up to the margin can make a lease that still holds read as short, never one that is over read as held. It is an allowance for
+ *    reading a reported deadline, not part of the lease clock: the engine enforces the lease on its own monotonic clock and
+ *    web-admin keeps its own expiry from its store time (see {@link ServingLeaseResponse}) — the two sides never compare clocks
+ *    to enforce. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a second constant that could
+ *    drift from it.
  */
 export const SERVING_LEASE_TTL_DEFAULT_MS = 600_000;
 export const SERVING_LEASE_TTL_FLOOR_MS = 60_000;

package/dist/index.d.ts

@@ -7,6 +7,9 @@ export * from "./execution-lanes.js";
 export * from "./url-shape.js";
 export * from "./url-credential.js";
 export * from "./default-model.js";
+export { catalogManagesModelPlane, enabledEntryCount } from "./catalog-manages.js";
+export { DEFAULT_MODEL_KEY, ENV_MODEL_TABLE_KEYS, buildEnvModelBaseline, envModelTableDeclared, envModelTableWriteRefusal, mintedCheapId, planEnvModelTableWrite, readEnvModelSlots, type EnvCheapSlot, type EnvModelBaseline, type EnvModelTableEntry, type EnvModelTableKey, type EnvModelTableLanding, type EnvModelTableReceipt, type EnvModelTableRoleRow, type EnvModelTableTarget, type EnvModelTableWriteInput, type EnvModelTableWriteIntent, type EnvModelTableWritePlan, type EnvRoleBinding, type EnvSnapshot, } from "./env-model-table.js";
+export { CONFIG_ROOT_DOCUMENTS, ENV_MODELS_DECISIONS, ENV_MODELS_DOCUMENT, ROOT_DOCUMENT_UNREADABLE_REASONS, envModelsDecisionTag, type ConfigRootDocument, type EnvModelsDecision, type EnvModelsDecisionWord, type MarkedMigrationId, type MigrationMarker, type RootDocumentUnreadableReason } from "./config-root-documents.js";
 export * from "./loopback.js";
 export * from "./hash.js";
 export * from "./sha256.js";
@@ -42,3 +45,5 @@ export * from "./mcp-server-policy.js";
 export * from "./ui-language.js";
 export * from "./control-and-bidi.js";
 export * from "./mcp-request-entry.js";
+export { REMOTE_MCP_SERVER_NAME_PREFIX } from "./mcp-server-name.js";
+export * from "./center-refs.js";

package/dist/index.js

@@ -7,6 +7,9 @@ export * from "./execution-lanes.js"; // 7.0.0 M-R2: the ONE lane / store vocabu
 export * from "./url-shape.js"; // 11.0.0: THE URL shape judge (httpUrlFlaws / httpUrlRule / isHierarchicalUrl), pure/browser-safe
 export * from "./url-credential.js"; // 14.5.0: THE "does this URL carry a credential" judge (findUrlCredential / findUrlUserinfo / URL_CREDENTIAL_REASONS / CREDENTIAL_PARAM_NAMES …), pure/browser-safe
 export * from "./default-model.js"; // 11.0.0: THE catalog-default resolver (roles.default → active tier ladder → fallback), pure/browser-safe
+export { catalogManagesModelPlane, enabledEntryCount } from "./catalog-manages.js"; // THE "does this models document manage the model plane" judge (raw half: at least one entry not explicitly disabled) + the log count it is derived from, pure/browser-safe
+export { DEFAULT_MODEL_KEY, ENV_MODEL_TABLE_KEYS, buildEnvModelBaseline, envModelTableDeclared, envModelTableWriteRefusal, mintedCheapId, planEnvModelTableWrite, readEnvModelSlots, } from "./env-model-table.js"; // the env model table (MODEL_ID / MODEL_CHEAP_ID) read once: readEnvModelSlots / envModelTableDeclared / buildEnvModelBaseline + the writer's plan planEnvModelTableWrite (receipt by id, confirmKey) + envModelTableWriteRefusal, pure/browser-safe (named: the env snapshot helper stays package-private)
+export { CONFIG_ROOT_DOCUMENTS, ENV_MODELS_DECISIONS, ENV_MODELS_DOCUMENT, ROOT_DOCUMENT_UNREADABLE_REASONS, envModelsDecisionTag } from "./config-root-documents.js"; // the config-root documents (config.env-models.json + the per-id migration marker config.migration.<id>.json): names + closed answer tables + the one tagged identity of a decision reading (envModelsDecisionTag); the readers / writer are in ./node
 export * from "./loopback.js"; // 11.0.0: the two「本机」predicates (auth relaxation — narrow / connection routing — wide), pure/browser-safe
 export * from "./hash.js";
 export * from "./sha256.js";
@@ -42,6 +45,8 @@ export * from "./mcp-server-policy.js"; // 13.0.0 (U6): mcpServerPolicyVerdict
 export * from "./ui-language.js"; // 13.0.0 (S-1592): the UI-language settings fragment (semaUiLanguage, en | zh, category ui, user settings) + readUiLanguage, pure/browser-safe
 export * from "./control-and-bidi.js"; // the one-line echo strip set (C0 + DEL + the 12 Bidi_Control code points) — CONTROL_AND_BIDI_CHARS (the class, as regex source text) + stripControlAndBidi / hasControlOrBidi, pure/browser-safe
 export * from "./mcp-request-entry.js"; // 14.0.0: the request-plane MCP entry judges (isUsableWireName / isContentOriginWord / readMcpIdentityHeaders / readRequestMcpTransport + the value-shape describers) — one reading for the service legs and the shell pre-check, pure/browser-safe
+export { REMOTE_MCP_SERVER_NAME_PREFIX } from "./mcp-server-name.js"; // the MCP server-name prefix reserved for the remote MCP servers a device executor offers (mount name = prefix + the executor's server name); the predicate and its sentence stay package-private — the request plane's MCP name judges (isUsableMcpServerName / describeBadMcpServerName) read them; the config plane's McpServerSpec.name accepts the prefix (refusing it would be a validation tightening — a major), pure/browser-safe
+export * from "./center-refs.js"; // resolveCenterRefs(refs, lookup) — THE center-roster reference resolver: one verdict word per member (missing_name / not_a_string / read_threw, CENTER_REF_FAULTS), one whole verdict (resolved / unresolved / refs_unreadable, CENTER_REFS_VERDICTS); the refs record is read by the public readPlainStringRecord, the lookup is the caller's, it reads no process.env; pure/browser-safe
 // NOTE: the Node-fs-backed helpers (FileConfigStore + the file editor) are NOT in this barrel — they pull
 // `node:fs`/`node:path` and would break a browser/client bundle that only wants the contract (e.g.
 // web-admin's client components import the zod types through here). Import them from the Node-only