@sema-agent/settings-schema 14.6.0 → 14.8.0

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/file-edit.js

@@ -8,6 +8,7 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
+import { emptyDocument, guardedSafeParse } from "./own-key-read.js";
 import { collectEnvRefs } from "./secret-refs.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { configDDocumentText } from "./config-d-file.js";
@@ -33,28 +34,23 @@ const DOMAINS_LIST = Object.keys(DOMAIN_SCHEMAS).join(", ");
  *  (clear message) if `domain` is not a real domain name (a misuse, not invalid user data). */
 export function validateDomain(domain, raw) {
     assertDomainName(domain);
-    let r;
-    try {
-        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw); // explicit null is corrupt, not defaults (R4)
-    }
-    catch {
+    // explicit null is corrupt, not defaults (R4); the first read of `error` sits in the same guard as `safeParse` (zod 4.6 builds the sentences on that read)
+    const schema = DOMAIN_SCHEMAS[domain];
+    const judged = guardedSafeParse(() => schema.safeParse(raw === undefined ? emptyDocument() : raw), sanitizeZodError);
+    if (!judged.ok) {
         // a hostile getter/Proxy trap threw during traversal — never surface its (secret-bearing) message. R13.
         return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid "${fixed(domain)}" config (a value could not be read during validation)`, path: [] }] };
     }
-    if (r.success)
-        return { ok: true, value: r.data };
-    return { ok: false, issues: sanitizeZodError(r.error).issues }; // recursive redaction (R13/R14) — no secret echo
+    if (judged.value.success)
+        return { ok: true, value: judged.value.data };
+    return { ok: false, issues: judged.value.error.issues }; // redacted inside the guard (R13/R14) — no secret echo
 }
 /** Same, for the remote-exec contract (a standalone contract, not a DOMAIN_SCHEMAS member). */
 export function validateRemoteExec(raw) {
-    let r;
-    try {
-        r = RemoteExecSpec.safeParse(raw);
-    }
-    catch {
+    const judged = guardedSafeParse(() => RemoteExecSpec.safeParse(raw), sanitizeZodError);
+    if (!judged.ok)
         return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid remoteExec (a value could not be read during validation)`, path: [] }] };
-    }
-    return r.success ? { ok: true, value: r.data } : { ok: false, issues: sanitizeZodError(r.error).issues }; // no secret echo (R14)
+    return judged.value.success ? { ok: true, value: judged.value.data } : { ok: false, issues: judged.value.error.issues }; // redacted inside the guard (R14)
 }
 /** Absolute path to a domain's JSON file under a config root (mirrors FileConfigStore.domainPath). Guards the
  *  name (no `../../secret` traversal even if a caller bypasses the DomainName type). */

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";
@@ -548,6 +560,17 @@ export declare const FLEET_GENERATION_ENV = "FLEET_GENERATION";
  * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export declare const FLEET_SCOPE_ENV = "FLEET_SCOPE";
+/**
+ * The env name a fleet member's advertise address travels under — the base URL this instance tells the control plane it can be
+ * reached at; the control plane appends request paths to it. The operator or the config renderer sets it (on Kubernetes the renderer
+ * writes a `$(POD_IP)` placeholder in the value and the kubelet expands it), and the engine reads it back. Both sides import THIS
+ * constant; neither spells the name. The address is a base that request paths are appended to, so a reader judges a present, non-empty
+ * value with `pathBaseUrlFlaws` (main barrel) — the one judge of every such seat, which forbids a credential, a
+ * query and a fragment there and allows a path prefix; judge the value AFTER the deployment has expanded its placeholders. Absent or
+ * the empty string means "no address declared" (the `${NAME:-}` idiom of a compose file), and that reading is the caller's, not the
+ * judge's.
+ */
+export declare const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
 /**
  * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
  * engine renews it with web-admin; web-admin answers per the lifecycle object it holds for that instance. Three constants
@@ -555,9 +578,15 @@ export declare const FLEET_SCOPE_ENV = "FLEET_SCOPE";
  *  - {@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

@@ -20,6 +20,8 @@
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
 import { fnv1a64 } from "./hash.js";
+import { parseDeclared } from "./declared-capture.js";
+import { readDeclaredKey, ownValueOf } from "./own-key-read.js";
 import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 // ── Web-admin's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
@@ -164,24 +166,41 @@ export const RestartSignal = z.object({
     since: EpochMs,
     withheld: z.boolean().optional(),
 });
-/**
- * The ONE guarded body judgement behind every wire-shape read in this file: `pick(body)` — one key of the body, or the body itself —
- * is judged against that shape's one schema, and the verdict says WHY when it is not a read: `not-an-object` (the body is null, an
- * array or a scalar) or `invalid` (the shape rejected it, or an accessor threw). It never throws (a probe must not die on one odd
- * body). Almost every reader wants only "a read or nothing" and goes through {@link readSignalBody}; the one reader whose
- * failure direction matters ({@link readCapabilityReading}) takes the reason. A second hand-written guard anywhere else in this
- * package is the defect, not a convenience.
- */
+const WHOLE_BODY = Symbol("whole body");
 function judgeSignalBody(body, pick, schema) {
-    try {
-        if (!isPlainJsonObject(body))
-            return { kind: "not-an-object" };
-        const parsed = schema.safeParse(pick(body));
-        return parsed.success ? { kind: "read", value: parsed.data } : { kind: "invalid" };
+    if (!isPlainJsonObject(body))
+        return { kind: "not-an-object" };
+    // the carrier key is read from the body's OWN keys (a polluted `Object.prototype.engineSignal` is not a signal the body carries) with the SAME descriptor check as a declared key:
+    // an own key that cannot be read as plain data (hidden — non-enumerable —, or an accessor that throws) is no readable signal, never "absent"
+    let target = body;
+    if (pick !== WHOLE_BODY) {
+        const carried = readDeclaredKey(body, pick);
+        switch (carried.presence) {
+            case "own":
+                target = carried.value;
+                break;
+            case "inherited":
+            case "absent":
+                target = undefined;
+                break;
+            case "hidden":
+            case "unreadable":
+                return { kind: "invalid" };
+            default: {
+                const unhandled = carried;
+                throw new Error(`judgeSignalBody: unhandled presence ${String(unhandled.presence)}`);
+            }
+        }
     }
-    catch {
+    // the validator reads members with `[[Get]]`, required keys included: a key the body does not carry would be filled from a polluted `Object.prototype` (a granted lease from an empty reply, a
+    // ready signal from `{}`, a "declared" capability from nothing) — so it never sees the caller's object: it reads an own-key snapshot of exactly the keys it declares (for a union: of
+    // the arm it will try), on the kernel's isolated prototype `COPY_PROTOTYPE` (no inherited members; it still answers `toString` / `valueOf`), and a value that cannot be captured
+    // (an accessor — throwing or not —, a hidden own key, a trap that throws, a cycle, not plain data) is `invalid`. `parseDeclared` admits only a closed allow-list of schema shapes, each
+    // reasoned and pinned against zod's own verdict and data; any other shape is a loud throw — the package chose the wrong reader, not a caller value that cannot be read
+    const parsed = parseDeclared(schema, target);
+    if (!parsed.ok)
         return { kind: "invalid" };
-    }
+    return { kind: "read", value: parsed.data };
 }
 /**
  * The reader behind every wire-shape read in this file that has no use for a reason: the engine-owned signals on /health
@@ -193,8 +212,6 @@ function readSignalBody(body, pick, schema) {
     const judged = judgeSignalBody(body, pick, schema);
     return judged.kind === "read" ? judged.value : undefined;
 }
-/** `pick` for a shape whose keys sit flat on the body itself (as opposed to under one key of it). */
-const wholeBody = (body) => body;
 /**
  * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
  * one edit in this file; who goes red at compile time: a reader that switches on the code exhaustively (a web-admin), and
@@ -214,17 +231,29 @@ const wholeBody = (body) => body;
  *    `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);
 /**
@@ -285,11 +314,14 @@ const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
  * at all — it answers the key only and never judges the engine's version (see {@link InstanceAnnouncement}`.modelRefusals`).
  */
 export function readModelRefusals(body) {
-    const wire = readSignalBody(body, (b) => b.modelRefusals, ModelRefusalsWire);
+    const wire = readSignalBody(body, "modelRefusals", ModelRefusalsWire);
     if (wire === undefined)
         return undefined;
     const entries = Object.fromEntries(Object.entries(wire.entries).filter((e) => isModelEntryRefusalCode(e[1])));
-    const plane = wire.plane !== undefined && isModelPlaneRefusalCode(wire.plane) ? wire.plane : undefined;
+    // the validated output is an ordinary object: an absent optional `plane` stays absent (own key only), never read off a polluted `Object.prototype`
+    const planeRead = ownValueOf(wire, "plane");
+    const planeWord = planeRead.ok ? planeRead.value : undefined;
+    const plane = typeof planeWord === "string" && isModelPlaneRefusalCode(planeWord) ? planeWord : undefined;
     if (Object.keys(entries).length === 0 && plane === undefined)
         return undefined;
     return plane === undefined ? { entries } : { entries, plane };
@@ -363,7 +395,7 @@ export const ENGINE_SIGNAL_KEY = "engineSignal";
  * dialect; the carrier is the one key).
  */
 export function readEngineSignal(body) {
-    return readSignalBody(body, (b) => b[ENGINE_SIGNAL_KEY], EngineSignal);
+    return readSignalBody(body, ENGINE_SIGNAL_KEY, EngineSignal);
 }
 /** The `/health` self-description every orchestrator reads. Liveness and readiness are deliberately SPLIT: `status` stays ok while
  *  draining (the process is alive); readiness is {@link judgeReadiness} over the engine signal the body carries under
@@ -556,6 +588,17 @@ export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
  * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
+/**
+ * The env name a fleet member's advertise address travels under — the base URL this instance tells the control plane it can be
+ * reached at; the control plane appends request paths to it. The operator or the config renderer sets it (on Kubernetes the renderer
+ * writes a `$(POD_IP)` placeholder in the value and the kubelet expands it), and the engine reads it back. Both sides import THIS
+ * constant; neither spells the name. The address is a base that request paths are appended to, so a reader judges a present, non-empty
+ * value with `pathBaseUrlFlaws` (main barrel) — the one judge of every such seat, which forbids a credential, a
+ * query and a fragment there and allows a path prefix; judge the value AFTER the deployment has expanded its placeholders. Absent or
+ * the empty string means "no address declared" (the `${NAME:-}` idiom of a compose file), and that reading is the caller's, not the
+ * judge's.
+ */
+export const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
 /**
  * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
  * engine renews it with web-admin; web-admin answers per the lifecycle object it holds for that instance. Three constants
@@ -563,9 +606,15 @@ export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
  *  - {@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;
@@ -647,14 +696,14 @@ export const SERVING_LEASE_VERDICTS = ["granted", "denied", "unknown"];
 /** Web-admin side: the request body of a serving-lease renewal. Shape mismatch / non-object / throwing accessor ⇒ `undefined`,
  *  never throws (same guarded reader as every other read in this file). */
 export function readServingLeaseRequest(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseRequest);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseRequest);
 }
 /** Engine side: the reply to a renewal, judged by its `verdict` key: `granted` needs a valid `ttlMs`, `denied` is `denied`
  *  whatever its `reason` (see {@link ServingLeaseReading}), `unknown` is `unknown`. A non-object, a throwing accessor, a
  *  `verdict` outside the three words or a `granted` without a valid `ttlMs` ⇒ `undefined`, never throws — and `undefined`
  *  is read like an unreachable web-admin, never like `denied` and never like `granted`. */
 export function readServingLeaseResponse(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseReadFace);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseReadFace);
 }
 /**
  * What web-admin says it can do: capability bits an engine reads before it starts using a web-admin-side endpoint.
@@ -704,14 +753,16 @@ const CapabilitiesCarrier = z.object({ [HEARTBEAT_REPLY_CAPABILITIES_KEY]: WebAd
  * other reader here.
  */
 export function readCapabilityReading(reply) {
-    const judged = judgeSignalBody(reply, wholeBody, CapabilitiesCarrier);
+    const judged = judgeSignalBody(reply, WHOLE_BODY, CapabilitiesCarrier);
     switch (judged.kind) {
         case "not-an-object":
             return { kind: "unreadable", why: "not-an-object" };
         case "invalid":
             return { kind: "unreadable", why: "invalid-capabilities" };
         case "read": {
-            const capabilities = judged.value[HEARTBEAT_REPLY_CAPABILITIES_KEY];
+            // the validated output is an ordinary object: an absent optional key must stay absent, not be read off a polluted `Object.prototype` — own key only (it was parsed from a snapshot, so it cannot be unreadable)
+            const carried = ownValueOf(judged.value, HEARTBEAT_REPLY_CAPABILITIES_KEY);
+            const capabilities = carried.ok ? carried.value : undefined;
             return capabilities === undefined ? { kind: "undeclared" } : { kind: "declared", capabilities };
         }
         default: {
@@ -755,11 +806,11 @@ export const DrainReceiptState = z.enum(DRAIN_RECEIPT_STATES);
 export const DrainReceipt = EngineDraining.extend({ state: DrainReceiptState });
 /** Engine side: the request body of the drain endpoint. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainRequest(body) {
-    return readSignalBody(body, wholeBody, DrainRequest);
+    return readSignalBody(body, WHOLE_BODY, DrainRequest);
 }
 /** Caller side: the drain endpoint's answer. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainReceipt(body) {
-    return readSignalBody(body, wholeBody, DrainReceipt);
+    return readSignalBody(body, WHOLE_BODY, DrainReceipt);
 }
 // ── Domain 3: dispatch policy (traffic + failover + LB — three domains, one gateway) ──────────────────────
 export const DISPATCH_STRATEGIES = ["round-robin", "least-inflight", "consistent-hash"];

package/dist/hash.d.ts

@@ -1,12 +1,3 @@
-/**
- * Tiny stable content hash — shared by `workerSpecHash` (reconciler drift detection) and the per-worker
- * `/effective` ETag (so an unrelated roster change doesn't churn a worker's cache). Zero-dep, deterministic.
- *
- * FNV-1a **64-bit** (BigInt) → 16 hex. NOT cryptographic; it's a change-detector. 64-bit pushes the
- * birthday-collision boundary to ~5B distinct inputs — a collision would silently SUPPRESS a needed
- * container restart (drift) or serve a stale 304 (ETag), so we don't want the 32-bit ~77k boundary here
- * (council finding). Output length isn't a contract (values are only compared for equality before/after).
- */
 /** Max nesting stableStringify will hash. A real EffectiveConfig nests ~10-15 deep; this generous cap turns a
  *  pathologically deep OR cyclic value (e.g. a poisoned `model.extraBody` = z.unknown()) into a DETERMINISTIC
  *  throw instead of a `RangeError: Maximum call stack` that would crash every scoped-worker `/effective` poll