@sema-agent/settings-schema 14.6.0 → 14.8.0

package/dist/declared-capture.js

@@ -0,0 +1,344 @@
+/**
+ * 包内私有(不进主桶):**按声明键投影的快照,与校验合在一起** —— 校验器(zod)读一个对象时只读它声明的键、剥掉其余;要保护它别读到 `Object.prototype` 上被污染的继承值、别碰会抛的 getter,
+ * 就得给它一份**自有键副本**。整份深拷({@link captureJson})会把「校验器根本不读」的键(没声明的键里放着 `Date` / `Map` / 函数 / 环 / 一个会抛的 getter)也读进来 ——
+ * 一个本来读得通的 body 变成整体读不出。所以:**只捕获校验器会读的键**,而「会读哪些键」随联合选哪一臂而定,所以投影与校验一起走({@link parseDeclared})。
+ *
+ *  · 对象形(`z.object`,没有 catchall —— 即「剥掉没声明的键」那一种):只读它声明的键(`shape` 的键),每个声明键的值按**对应子 schema** 递归;没声明的键一个都不读不拷;
+ *  · **判别联合**:先按判别键(与声明键同一只描述符读)选臂,**只投影选中那一臂**的声明键;判别键**只读一次** —— 选臂的那个词就是快照里交给校验器的那个词;
+ *    判别键缺席 / 不是任何一臂的词 ⇒ 只交过去判别键(校验器只看它就拒);
+ *  · **普通联合**(顶层):按序逐臂 —— 一臂一份只含该臂声明键的快照、**只拿该臂的 schema 校验**,该臂通过才接受、**第一臂通过即止**,没通过才轮到下一臂(与 zod 按序试臂一致;不取并集;
+ *    拿整个联合去校验的话,后臂会用默认值接受前一臂的残缺投影);**互斥联合**(`z.xor`)所有臂都走一遍、恰一臂通过才接受(两臂都通过 zod 拒,这里同样拒)。
+ *    嵌在对象里的普通联合、以及套着包装层的联合当不透明:整个值深拷、对整只 schema 校验;
+ *  · `unknown` / `any`(投影走到的位置上):校验器自己不看它的内容 ⇒ 调用方的原值原样交过去(后面接的 transform 是包自己写的);
+ *  · 其余(标量、`record`、数组、`strict` 的对象 —— 校验器要读全部键):整个值深拷(不透明)。
+ * 声明键的律与内核同:自有但不可枚举 ⇒ 读不成纯数据、整份拒({@link NOT_PLAIN_DATA}),**不当缺席**;自有 getter 抛 / 陷阱抛 ⇒ {@link UNINSPECTABLE};只靠继承 ⇒ 缺席。
+ * 任何一份快照拿不到(读不出 / 拒)⇒ 整个读不出(不再试后面的臂:v14.6.0 里校验器在那里读到的会抛)。守护在 {@link parseDeclared} 入口一处:门的 schema 内省、快照递归与校验同在里面。
+ *
+ * **门 = 闭集白名单**(`admit`,每只 schema 第一次进来时走一遍整棵 schema 树,通过的记下;递归 schema 按「节点 × 位置」只判一次):只放行**与 zod 同答**(判决与数据,对 JSON 输入)的节点种类
+ * —— 每一种都按 zod 4.4 / 4.6 的读法推过、有对 zod 逐例比判决与数据的钉;反例搜索不是穷举,找到不同答的形就从放行单拿掉 ——
+ * 叶子(不跑用户函数、没有子 schema)· 不跑看得见输入的函数的包装层(`optional` / `nullable` / `default` / `prefault`)· 后处理 `.transform(f)`(`f` 看到的是里面那只 schema 的输出,两边同一份)·
+ * 对象(声明键不是符号、也不叫寻常对象从 `Object.prototype` 继承来的名字 —— zod 在原值上读到继承的成员,投影读成缺席)· 判别联合(不带 `unionFallback`)· 普通 / 互斥联合 · `record` · 数组 ·
+ * 投影走到的位置上的 `unknown` / `any`。对象 / 数组 / record 上挂的检查(refine / superRefine / 长度 …)看到的是 zod 自己铸的新输出,两边同一份。
+ * 其余一律**响亮拒**(抛 `parseDeclared: unsupported schema shape — …`;这是包自己的 schema 选错了读法,不是调用方的值读不出):`.catch`(兜底函数看到整个原值 —— zod ≥ 4.6 交 `ctx.input`)·
+ * 输入侧变换(`z.preprocess`、字段位上单独的 `z.transform`、两侧都是 schema 的管道)· `z.custom`(谓词看到的是副本)· 深拷节点之下的 `unknown` / `any`(副本会进输出;passthrough 对象同因)·
+ * 声明键叫继承名 / 是符号(有限键集 record 的键同此)· loose record · 顶层普通联合自己挂的检查 · 带 `unionFallback` 的判别联合 · `tuple` / `intersection` / `map` / `set` / `lazy` / `readonly` …(没推过)。
+ * 不逐形补黑名单:新形默认拒。校验只问判决、不要句子(`evaluate` 给 zod 逐次 `error` 参数):副本的原型不是 `Object.prototype`,zod 拼拒句时会读副本上用户写的自有 `constructor`。
+ */
+import { z } from "zod";
+import { NOT_PLAIN_DATA, NO_PRIOR_READS, UNINSPECTABLE, captureJson, dataDescriptor, inspect, isolatedObject, readDeclaredKey } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
+import { unwrapOnce } from "./zod-unwrap.js";
+const failed = (sentence) => ({ ok: false, sentence });
+/** 判语的句子(只在这里拼一次)。 */
+const unsupportedShape = (what) => `parseDeclared: unsupported schema shape — ${what}`;
+/** 包装层的层数界(schema 作者写出来的常数,8 层远超实际)。 */
+const WRAPPER_BOUND = 8;
+/** 剥掉投影会穿过的包装层拿内里的 schema:`optional` / `nullable` / `default` / `prefault` 与后处理 `.transform(f)`。`.catch` 与输入侧的变换不穿 —— 停在它们身上(白名单门拒它们)。 */
+function innerOf(schema) {
+    let cur = schema;
+    for (let i = 0; i < WRAPPER_BOUND; i++) {
+        const step = unwrapOnce(cur);
+        if (step === undefined || step.via === "preprocess" || cur instanceof z.ZodCatch)
+            return cur;
+        cur = step.next;
+    }
+    return cur;
+}
+/**
+ * 对象 schema 的声明键表:读 `def.shape` —— zod 自己校验时读的就是这一份(它在第一次被读时才物化,物化失败下次再试);**不读** classic 面的 `object.shape`:
+ * 那是 zod 4.4 的另一只惰性属性,物化时抛(例:`Object.prototype` 被污染)就永远答 `undefined`,而 zod 自己校验从不读它 —— 读它会让门在污染撤掉之后仍读不出,v14.6.0 不会。
+ */
+const shapeOf = (object) => object._zod.def.shape;
+/** 普通联合(含互斥联合 `z.xor`),不是判别联合 —— `evaluate` 逐臂走它;白名单门按同一个判据认它。 */
+const isPlainUnion = (schema) => schema instanceof z.ZodUnion && !(schema instanceof z.ZodDiscriminatedUnion);
+/** 寻常对象从 `Object.prototype` 继承来的成员名(ES 规定的闭集)。声明键叫这些名字时,zod 在调用方的值上 `[[Get]]` 读到继承来的成员,投影把它读成缺席 —— 两边不同答。 */
+const ORDINARY_OBJECT_MEMBERS = new Set(["constructor", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable", "toLocaleString", "toString", "valueOf", "__proto__", "__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__"]);
+/** 走过白名单门的 schema(按根;fleet 每次请求都是那七只,不重走)。 */
+const ADMITTED = new WeakSet();
+/** 白名单门(见文件头):整棵 schema 树只含放行的形 ⇒ 记下、交回 `undefined`;否则交回不支持的那一句(见 {@link Refusal})。与 `evaluate` / `snapshotOf` 同一套判据(`isPlainUnion` / `innerOf`)。 */
+function admit(schema) {
+    if (ADMITTED.has(schema))
+        return undefined;
+    const refusal = admitEvaluated(schema, new Map());
+    if (refusal === undefined)
+        ADMITTED.add(schema);
+    return refusal;
+}
+/** 一串子节点逐个过门,第一句不支持就停(交回它)。 */
+function admitEach(children, at, seen) {
+    for (const child of children) {
+        const refusal = admitAt(child, at, seen);
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+/** `evaluate` 走的那一层:普通联合逐臂;其余是一份投影。 */
+function admitEvaluated(schema, seen) {
+    if (isPlainUnion(schema)) {
+        // `evaluate` 逐臂拿**臂的** schema 校验:挂在联合本身上的检查(`.refine` / `.superRefine`)一次都不跑 —— zod 会跑,两边不同答
+        if ((schema._zod.def.checks ?? []).length > 0)
+            return "a union with checks of its own at the top (`.refine` on the union: the per-arm evaluation validates with each arm's schema, so the union's own checks would never run)";
+        for (const option of schema._zod.def.options) {
+            const refusal = admitEvaluated(option, seen);
+            if (refusal !== undefined)
+                return refusal;
+        }
+        return undefined;
+    }
+    return admitAt(schema, "projected", seen);
+}
+function admitAt(schema, at, seen) {
+    const inner = innerOf(schema);
+    const positions = seen.get(inner) ?? new Set();
+    if (positions.has(at))
+        return undefined;
+    seen.set(inner, positions.add(at));
+    const kind = inner._zod.def.type;
+    switch (kind) {
+        // 叶子:不跑用户函数、没有子 schema —— 校验器只看这个值本身(原始值两边是同一个;对象两边都按形拒)
+        case "string":
+        case "number":
+        case "int":
+        case "boolean":
+        case "bigint":
+        case "symbol":
+        case "null":
+        case "undefined":
+        case "void":
+        case "never":
+        case "nan":
+        case "date":
+        case "literal":
+        case "enum":
+        case "template_literal":
+        case "file":
+            return undefined;
+        case "unknown":
+        case "any":
+            return at === "copied" ? "`unknown` / `any` under a copied node (record / array / a union inside a field / a catchall — passthrough included): the copy, not the caller's value, would reach the output" : undefined;
+        case "object": {
+            const object = inner;
+            const shape = shapeOf(object);
+            if (Object.getOwnPropertySymbols(shape).length > 0)
+                return "a symbol key (the projection reads string keys only)";
+            const catchall = object._zod.def.catchall;
+            for (const key of Object.keys(shape)) {
+                if (ORDINARY_OBJECT_MEMBERS.has(key))
+                    return `a declared key named \`${key}\` (zod reads the member an ordinary object inherits; the projection reads it as absent)`;
+                const refusal = admitAt(shape[key], catchall === undefined ? at : "copied", seen);
+                if (refusal !== undefined)
+                    return refusal;
+            }
+            return catchall !== undefined ? admitAt(catchall, "copied", seen) : undefined;
+        }
+        case "union": {
+            const options = inner._zod.def.options;
+            if (inner instanceof z.ZodDiscriminatedUnion) {
+                if (inner._zod.def.unionFallback === true)
+                    return "a discriminated union with `unionFallback` (zod falls back to trying every arm on the full value; the projection of one arm's declared keys cannot say what it would do)";
+                return admitEach(options, at, seen);
+            }
+            return admitEach(options, "copied", seen); // 走到这里的普通联合是不透明的(嵌在字段里 / 套着包装层):整个值深拷
+        }
+        case "record": {
+            const record = inner;
+            if (record._zod.def.mode === "loose")
+                return "a loose record (keys the key schema does not match ride through by reference — the copy, not the caller's value, would reach the output)";
+            // 有限键集(枚举 / 字面量键):zod 逐个按键名在值上 `[[Get]]` —— 键名是继承名时读到继承的成员,副本上读成缺席(与对象声明键同一条)
+            for (const key of record._zod.def.keyType._zod.values ?? []) {
+                if (typeof key === "string" && ORDINARY_OBJECT_MEMBERS.has(key))
+                    return `a record key named \`${key}\` in a finite key set (zod reads the member an ordinary object inherits; the copy reads it as absent)`;
+            }
+            return admitEach([record._zod.def.keyType, record._zod.def.valueType], "copied", seen);
+        }
+        case "array":
+            return admitAt(inner.element, "copied", seen);
+        case "catch":
+            return "`.catch` (its fallback sees the caller's whole value — zod ≥ 4.6 hands it `ctx.input`; a projection changes what it sees)";
+        case "pipe":
+            return `a pipe the projection does not pass through — an input-side \`z.preprocess(f, …)\` or \`a.pipe(b)\` (the function / the second schema would see a projection or a copy, not what zod sees), or wrappers nested deeper than ${WRAPPER_BOUND} layers`;
+        case "transform":
+            return "a bare `z.transform(f)` (an input-side function: it would see the projection, not the caller's value)";
+        case "custom":
+            return "`z.custom` / `z.instanceof` (the predicate would see the projection, not the caller's value)";
+        case "optional":
+        case "nullable":
+        case "default":
+        case "prefault":
+            return `wrappers nested deeper than ${WRAPPER_BOUND} layers`;
+        case "tuple":
+        case "intersection":
+        case "map":
+        case "set":
+        case "lazy":
+        case "promise":
+        case "function":
+        case "readonly":
+        case "nonoptional":
+        case "success":
+            return `\`${kind}\` (not on the allow-list: the projection has not been proven to answer as zod does)`;
+        default: {
+            const unhandled = kind;
+            return `an unknown schema kind \`${String(unhandled)}\``;
+        }
+    }
+}
+/** 一个值要不要进对象投影:是朴素对象 ⇒ `undefined`(继续投影);不是对象(`null` / 原始值)⇒ 原样交过去(校验器自己拒);数组 / 类实例 / 读不出 ⇒ 深拷(同一套坏形与句子)。 */
+function nonObjectSnapshot(value) {
+    const kind = jsonShapeOf(value);
+    switch (kind) {
+        case "plain":
+            return undefined;
+        case "null":
+        case "primitive":
+            return { ok: true, value };
+        case "array":
+        case "non_plain_object":
+        case "uninspectable":
+            return captureJson(value);
+        default: {
+            const unhandled = kind;
+            throw new Error(`declared-capture: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** 对象形投影:声明键逐个读(自有可枚举数据属性 ⇒ 取值按子 schema 递归;继承 / 缺席 ⇒ 跳过;隐藏 / 访问器 / 读不出 ⇒ 整份拒)。`prior` 里已有的键用那一次的读数,不再读。 */
+function objectSnapshot(shape, value, prior) {
+    const skip = nonObjectSnapshot(value);
+    if (skip !== undefined)
+        return skip;
+    const copy = isolatedObject();
+    for (const key of Object.keys(shape)) {
+        const read = prior.get(key) ?? readDeclaredKey(value, key);
+        switch (read.presence) {
+            case "own": {
+                const child = snapshotOf(shape[key], read.value, NO_PRIOR_READS);
+                if (!child.ok)
+                    return child;
+                Object.defineProperty(copy, key, dataDescriptor(child.value));
+                break;
+            }
+            case "inherited":
+            case "absent":
+                break;
+            case "hidden":
+                return failed(NOT_PLAIN_DATA);
+            case "unreadable":
+                return failed(UNINSPECTABLE);
+            default: {
+                const unhandled = read;
+                throw new Error(`declared-capture: unhandled presence ${String(unhandled.presence)}`);
+            }
+        }
+    }
+    return { ok: true, value: copy };
+}
+/**
+ * 判别联合:按判别键选臂,只投影那一臂;判别键缺席 / 不是任何一臂的词 ⇒ 只交过去判别键。**判别键只读一次**:这一次的读数交给选中那一臂的投影复用(`prior`),
+ * 所以快照里的判别词就是选臂的那个词 —— 校验器拿快照按判别键派发,落到的就是选中的这一臂(没有第二次读,也就没有「第二次读到另一个词、落到另一臂」)。
+ */
+function discriminatedSnapshot(union, value, prior) {
+    const skip = nonObjectSnapshot(value);
+    if (skip !== undefined)
+        return skip;
+    const discriminator = union._zod.def.discriminator;
+    const read = prior.get(discriminator) ?? readDeclaredKey(value, discriminator);
+    if (read.presence === "hidden")
+        return failed(NOT_PLAIN_DATA);
+    if (read.presence === "unreadable")
+        return failed(UNINSPECTABLE);
+    const word = read.presence === "own" ? read.value : undefined;
+    const arms = union._zod.def.options;
+    const chosen = arms.find((arm) => innerOf(arm)._zod.propValues?.[discriminator]?.has(word) === true);
+    if (chosen !== undefined)
+        return snapshotOf(chosen, value, new Map(prior).set(discriminator, read));
+    // 没有一臂认这个词(或键缺席):校验器只看判别键就拒,别的键一个都不碰
+    const only = isolatedObject();
+    if (read.presence === "own") {
+        const kept = captureJson(word);
+        if (!kept.ok)
+            return kept;
+        Object.defineProperty(only, discriminator, dataDescriptor(kept.value));
+    }
+    return { ok: true, value: only };
+}
+/**
+ * `schema` 在 `value` 上会读的键的快照(恰一份;普通联合不在这里 —— 它逐臂各走一遍,见 `evaluate`;嵌在对象里的普通联合当不透明,整个值深拷)。
+ * `prior`:同一个值上已经读过的声明键(判别联合读过的判别键;投影走进字段值时是一张新的空表)—— **快照里这些键的在场与值恒是那一次的读数,不读第二次**:投影直接复用;
+ * 整份深拷的臂(`strict` / 带 catchall 的对象)把它交给 `captureJson`,列成员时这些键取那一次的读数、不再问描述符(所以判别联合选臂的词就是交给校验器的词,不论臂怎么拍快照)。
+ */
+function snapshotOf(schema, value, prior) {
+    const inner = innerOf(schema);
+    if (inner instanceof z.ZodUnknown || inner instanceof z.ZodAny)
+        return { ok: true, value };
+    if (inner instanceof z.ZodDiscriminatedUnion)
+        return discriminatedSnapshot(inner, value, prior);
+    if (inner instanceof z.ZodObject && inner._zod.def.catchall === undefined)
+        return objectSnapshot(shapeOf(inner), value, prior);
+    return captureJson(value, "isolated", prior);
+}
+/**
+ * 按 zod 的联合语义逐臂各走一遍:一臂 = 只含该臂声明键的快照 + **只拿该臂的 schema 校验**(拿整个联合去校验的话,后臂会用默认值接受前一臂的残缺投影)。
+ *  · 普通联合:按序,第一臂通过即止(不取并集);
+ *  · 互斥联合(`z.xor`:`def.inclusive === false`):**所有**臂都走一遍,恰一臂通过才接受 —— 两臂都通过 zod 拒(这里同样拒,不是取第一臂丢掉另一臂的键);
+ *  · 其余(含判别联合:它按判别键选臂,见 `discriminatedSnapshot`):恰一份快照、拿整只 schema 校验。
+ * 联合外面套着包装层(`optional` / `default` / `catch` …)⇒ 当不透明(整个值深拷、对整只 schema 校验),包装层的语义由 zod 自己走。
+ */
+function evaluate(schema, value) {
+    if (isPlainUnion(schema)) {
+        const exclusive = schema._zod.def.inclusive === false;
+        let accepted;
+        for (const option of schema._zod.def.options) {
+            const verdict = evaluate(option, value);
+            if (verdict.kind === "unreadable")
+                return verdict;
+            if (verdict.kind !== "ok")
+                continue;
+            if (!exclusive)
+                return verdict;
+            if (accepted !== undefined)
+                return { kind: "rejected" }; // xor:两臂都通过 ⇒ 拒
+            accepted = verdict;
+        }
+        return accepted ?? { kind: "rejected" };
+    }
+    const snapshot = snapshotOf(schema, value, NO_PRIOR_READS);
+    if (!snapshot.ok)
+        return { kind: "unreadable" };
+    // 只问判决、不要句子(parseDeclared 从不交出拒因):逐次 `error` 参数让 zod 不进 locale 拼句 —— 拼句会对副本做 `parsedType`(副本的原型不是 Object.prototype,
+    // 用户写的自有 `constructor` 键会被读成类型名、转串时抛),联合 / 互斥联合会因此把一臂判成「读不出」、不再试后面的臂,与 zod 在原值上的判决不同。只读 `success` / `data`,
+    // 不构造错误对象(所以不用 `guardedSafeParse`);校验过程抛 ⇒ 入口那一只守护(`inspect`)接住
+    const parsed = schema.safeParse(snapshot.value, { error: () => "rejected" });
+    return parsed.success ? { kind: "ok", data: parsed.data } : { kind: "rejected" };
+}
+/**
+ * 对 `value` 校验的守护读法(`schema` 的 safeParse):校验器读的是投影后的自有键快照,不是调用方的对象。读不出 / 不是纯数据 / 校验不过 ⇒ `{ ok: false }`(不抛);
+ * 联合按 {@link evaluate} 的语义逐臂。`schema` 不在白名单里(见文件头)⇒ 抛 `parseDeclared: unsupported schema shape — …`(不论输入)。
+ * **守护边界就在这里一处**(内核的 `inspect`):白名单门对 schema 的内省(zod 的惰性属性 —— 声明键表、判别联合的 `propValues` —— 第一次被读时才物化,物化时 zod 用字面量描述符调
+ * `defineProperty`、往 `{}` 上按键名累加:`Object.prototype` 被污染成 `get` / `set` / `value` / 判别键名时,物化在这一步抛)、投影快照的递归(递归 schema × 很深的数据会爆栈)与校验,
+ * 全在同一只守护里 —— 抛了 ⇒ `{ ok: false }`(与 v14.6.0 那一层守护同向:读口答「读不出」,不把引擎的错 / 嵌入方的抛出值带出去)。
+ * 「不支持」是门**交回**的判语、在守护外抛:它是包自己的 schema 选错了读法,与输入无关。
+ */
+export function parseDeclared(schema, value) {
+    const run = inspect(() => {
+        const refusal = admit(schema);
+        return refusal !== undefined ? { kind: "unsupported", what: refusal } : evaluate(schema, value);
+    });
+    if (!run.ok)
+        return { ok: false };
+    const verdict = run.value;
+    switch (verdict.kind) {
+        case "unsupported":
+            throw new Error(unsupportedShape(verdict.what));
+        case "ok":
+            return { ok: true, data: verdict.data };
+        case "rejected":
+        case "unreadable":
+            return { ok: false };
+        default: {
+            const unhandled = verdict;
+            throw new Error(`parseDeclared: unhandled verdict ${String(unhandled.kind)}`);
+        }
+    }
+}

package/dist/default-model.d.ts

@@ -7,7 +7,7 @@
  */
 import type { ModelsConfig, RoleTarget } from "./types.js";
 /** core 对 `default` 角色的档语义:从它的缺省档 `pro` 起**只向低档**扫 —— pro → flash → lite,绝不向上抓 max / ultra
- *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;钉对 devDependency 里精确钉住的那一版 core)。 */
+ *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;档序只在 `./tier-words` 一处,这里按起点派生;对拍钉对 devDependency 里精确钉住的那一版 core)。 */
 export declare const DEFAULT_ROLE_TIER_LADDER: readonly ["pro", "flash", "lite"];
 /** 命名链每一级的来源词(闭集)。 */
 export type CatalogDefaultSource = "roles.default" | `tierGroup.${(typeof DEFAULT_ROLE_TIER_LADDER)[number]}` | "fallback";

package/dist/default-model.js

@@ -1,7 +1,8 @@
 import { resolveActiveTiers } from "./config-fns.js";
+import { tierLadderFrom } from "./tier-words.js";
 /** core 对 `default` 角色的档语义:从它的缺省档 `pro` 起**只向低档**扫 —— pro → flash → lite,绝不向上抓 max / ultra
- *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;钉对 devDependency 里精确钉住的那一版 core)。 */
-export const DEFAULT_ROLE_TIER_LADDER = ["pro", "flash", "lite"];
+ *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;档序只在 `./tier-words` 一处,这里按起点派生;对拍钉对 devDependency 里精确钉住的那一版 core)。 */
+export const DEFAULT_ROLE_TIER_LADDER = tierLadderFrom("pro");
 /**
  * 缺省模型由 `roles.default` 的形分两路(一条规则:点名的走命名链,不点名的交回引擎):
  *  · `{select}` ⇒ `{ kind: "select", select }`(见 {@link CatalogDefaultModel});
@@ -13,8 +14,8 @@ export function resolveCatalogDefaultModel(models, has, fallback) {
     const target = models.roles?.default;
     const named = target !== undefined && "model" in target ? target.model : undefined;
     const select = target !== undefined && "select" in target ? target.select : undefined;
-    // 判序与引擎同一只真值判(core `partsModel`:`model` 为真 ⇒ 按名;否则 `select` 为真 ⇒ 按属性挑):schema 读过的值只有一形,这一判序只对
-    // 绕过 schema 递进来的两形并在(含 `model: ""`)起作用 —— 那时也与引擎同答。
+    // 判序按真值判:`model` 为非空串 ⇒ 按名;否则 `select` 为真 ⇒ 按属性挑。schema 读过的值只有一形(`model` 是非空串),这一判序只对绕过 schema
+    // 递进来的空串 `model` 起作用 —— 本包把它读作没写;引擎(devDependency 钉的那一版)按在场判、空串按名拒(`unknown_model_ref`),这一形两边不同答。
     if (!named && select)
         return { kind: "select", select };
     const tiers = resolveActiveTiers(models) ?? {};

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;