@sema-agent/server 7.127.2 → 7.129.0

package/dist/trace/project.js

@@ -1,5 +1,5 @@
 import { admitProviderEcho, redactErrorMessage, redactModelText } from "../observability/run-terminal.js";
-import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, isPersistedRuleMandate, isSettlementParty, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, screenGateOutcome, TEAM_ROLES, ToolRoster, ToolRosterDelta, WRITE_PROTECTION_TARGET_VIEWS } from "@sema-agent/core";
+import { MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, screenGateOutcome, TEAM_ROLES, ToolRoster, ToolRosterDelta, WRITE_PROTECTION_TARGET_VIEWS } from "@sema-agent/core";
 import { Value } from "typebox/value";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets, redactDeep } from "./redact.js";
@@ -111,77 +111,16 @@ export function screenedGate(v) {
         return undefined;
     }
 }
-function modeLedgerDefect(d) {
-    const classesOk = (v) => Array.isArray(v) && v.every((c) => isAskClass(c));
-    if (d.kind === "denied") {
-        if (d.mode !== undefined && !isPermissionMode(d.mode))
-            return "disposition.mode is outside the closed set";
-        if (d.askClass !== undefined && !isAskClass(d.askClass))
-            return "disposition.askClass is outside the closed set";
-        if (d.classes !== undefined && !classesOk(d.classes))
-            return "disposition.classes is not a list of ask classes";
-        return false;
-    }
-    if (d.released === undefined)
-        return false;
-    const r = d.released;
-    if (r === null || typeof r !== "object")
-        return "disposition.released is not an object";
-    const o = r;
-    if (!isPermissionMode(o.mode) || !isAskClass(o.askClass) || !classesOk(o.classes))
-        return "disposition.released.mode / askClass / classes is outside its closed set";
-    if (o.origin !== undefined && !isAskOrigin(o.origin))
-        return "disposition.released.origin is outside the closed set";
-    if (o.mandate !== undefined && !isPersistedRuleMandate(o.mandate))
-        return "disposition.released.mandate is outside the closed set";
-    return false;
-}
-function withReleaseReasonTheEngineReads(g) {
-    const d = g.disposition;
-    if (d.kind !== "allowed" || d.released === undefined)
-        return g;
-    const r = d.released;
-    if (r === null || typeof r !== "object")
-        return g;
-    const reason = d.released.reason;
-    if (typeof reason !== "string" || isModeReleaseReason(reason))
-        return g;
-    const { reason: _unread, ...kept } = d.released;
-    return { ...g, disposition: { ...d, released: kept } };
-}
 function screenedGateOrThrow(v) {
-    if (v === null || typeof v !== "object") {
-        if (v !== undefined)
-            recordFailOpen("server.trace.gate-outcome-defective", "gate is not an object");
-        return undefined;
-    }
-    const stored = v;
-    if (stored.disposition === null || typeof stored.disposition !== "object" || (stored.disposition.kind !== "allowed" && stored.disposition.kind !== "denied")) {
-        recordFailOpen("server.trace.gate-outcome-defective", "disposition is not one of the two arms");
-        return undefined;
-    }
-    const g = withReleaseReasonTheEngineReads(stored);
-    const d = g.disposition;
-    const classifierFallbackRaw = d.classifier !== null && typeof d.classifier === "object" ? d.classifier.fallback : undefined;
-    const shapeDefect = (d.kind === "denied" && typeof d.deniedBy !== "string" && "disposition.deniedBy is not a string") ||
-        (d.kind === "denied" && d.cause !== undefined && typeof d.cause !== "string" && "disposition.cause is not a string") ||
-        (d.classifier !== undefined && (d.classifier === null || typeof d.classifier !== "object") && "disposition.classifier is not an object") ||
-        (classifierFallbackRaw !== undefined && (classifierFallbackRaw === null || typeof classifierFallbackRaw !== "object") && "disposition.classifier.fallback is not an object") ||
-        (classifierFallbackRaw !== undefined && classifierFallbackRaw !== null && typeof classifierFallbackRaw === "object" && typeof classifierFallbackRaw.cause !== "string" && "disposition.classifier.fallback.cause is not a string") ||
-        modeLedgerDefect(d) ||
-        (g.settlement !== undefined && (g.settlement === null || typeof g.settlement !== "object") && "settlement is not an object") ||
-        (g.settlement !== undefined && g.settlement !== null && typeof g.settlement.kind !== "string" && "settlement.kind is not a string") ||
-        (g.origin !== undefined && typeof g.origin !== "string" && "origin is not a string") ||
-        undefined;
-    if (shapeDefect !== undefined) {
-        recordFailOpen("server.trace.gate-outcome-defective", shapeDefect);
+    if (v === undefined)
         return undefined;
-    }
-    const defects = screenGateOutcome(g);
+    const defects = screenGateOutcome(v);
     if (defects.length > 0) {
         recordFailOpen("server.trace.gate-outcome-defective", defects.join("; "));
         return undefined;
     }
+    const g = v;
+    const d = g.disposition;
     const attribution = d.classifier;
     const classifier = attribution === undefined
         ? undefined
@@ -193,10 +132,6 @@ function screenedGateOrThrow(v) {
                 : { fallback: { from: attribution.fallback.from, to: attribution.fallback.to, cause: attribution.fallback.cause } }),
         };
     const settlement = g.settlement === undefined ? undefined : projectSettlement(g.settlement);
-    if (g.settlement !== undefined && settlement === undefined) {
-        recordFailOpen("server.trace.gate-outcome-defective", "settlement.who is not an object with a party in the closed set");
-        return undefined;
-    }
     const rel = d.kind === "allowed" ? d.released : undefined;
     const released = rel === undefined
         ? undefined
@@ -242,11 +177,7 @@ export function screenedStoredEventData(type, data) {
     return { ...d, gate };
 }
 function projectSettlement(st) {
-    const whoV = st.who;
-    const partyV = whoV === null || typeof whoV !== "object" ? undefined : whoV.party;
-    if (!isSettlementParty(partyV))
-        return undefined;
-    const who = whoV;
+    const who = st.who;
     return {
         kind: st.kind,
         when: st.when,
@@ -289,7 +220,7 @@ export function toolEndEventData(ev) {
         ...(ev.output !== undefined ? { output: projectToolOutput(ev.output) } : {}),
         ...(ev.truncated ? { truncated: true } : {}),
         ...(Number.isFinite(ev.totalChars) ? { totalChars: ev.totalChars } : {}),
-        ...(ev.structured !== undefined ? { structured: projectToolStructured(ev.structured) } : {}),
+        ...(ev.structured !== undefined ? { structured: projectToolStructured(ev.structured, redactDeep) } : {}),
         ...(typeof ev.errorCode === "string" && ev.errorCode.length <= 128 ? { errorCode: ev.errorCode } : {}),
         ...(typeof ev.delivered === "string" && MCP_DELIVERY_VERDICTS.includes(ev.delivered) ? { delivered: ev.delivered } : {}),
         ...(gate !== undefined ? { gate } : {}),

package/dist/trace/tool-output-media.d.ts

@@ -4,15 +4,21 @@
  */
 export declare function projectToolOutput(output: unknown): unknown;
 /**
- * 两面共用的 `structured` 投影(与 {@link projectToolOutput} 同律):媒体卡逐成员过 `redactDeep`,`file` 里 `base64` 逐字、其余成员照脱;
- * 其它一切整只过 `redactDeep`。保键序(逐键映射),不改入参。
+ * 媒体卡座位的**唯一一只遍历**(与 {@link projectToolOutput} 同律):媒体卡逐成员过 `redact`,`file` 里 `base64` 逐字、其余成员照脱;
+ * 其它一切整只过 `redact`。保键序(逐键映射),不改入参。
+ *
+ * 形判与遍历只此一只,**脱敏器由调用面给**(「什么算该脱」是各面自己的事,「字节座位不过它」是这里的事):
+ *  · `tool_end` 活面 / 持久面(`toolEndEventData` 经 `trace/project.ts`):凭据脱敏 `redactDeep`;
+ *  · 会话存档读面(`audit.ts` 的 `toolResult.details` 叶):模型文本段脱敏的深扫(`redactDeepWith(v, redactModelText)`)。
+ * `redact` 必须是整值→整值的纯函数(环 / 深度守卫在它里面,遍历不重做);非媒体卡原样交给它,所以非媒体卡的读数就是调用面自己的深扫。
  */
-export declare function projectToolStructured(structured: unknown): unknown;
+export declare function projectToolStructured(structured: unknown, redact: (value: unknown) => unknown): unknown;
 /**
  * `tool_end` 载荷的媒体降级(持久面恒用;活面只在连接积压时用),**一次调用降两个座位**:
  *  · `output`:带 `data` 的媒体块换成描述符,有任何一块被换 ⇒ 帧级 `truncated: true` 且帧级 `totalChars` 在场 —— core 不变量
  *    「Present iff truncated」:被界之前那个值的真实大小。帧上已有 `totalChars`(core 已截断:文本被切而媒体留着)⇒ **原样保留**
- *    (它说的是更早的原值,本仓手里的已是切过的值,重算只会低报);没有 ⇒ 按 {@link trueSizeOf} 逐块求和(core 没截,`output` 就是原值 ——
+ *    (它说的是更早的原值,本仓手里的已是切过的值,重算只会低报);没有 ⇒ 按引擎的逐块计数器 `toolOutputBlockChars` 求和(core 7.51.1 导出,`tool_end.totalChars` 加总的就是它;本仓 7.128.x 及以前的拷贝
+ *    `trueSizeOf` 随之删除)(core 没截,`output` 就是原值 ——
  *    文本块是本服务脱敏后的字节,即本服务交付的内容)。已是描述符的块(无 `data`)原样 ⇒ 幂等。
  *  · `structured`:媒体卡去掉 `file.base64`(core 卡形自己的「不带字节」形),其余成员逐字。帧级 `truncated` / `totalChars` 只说 `output`,
  *    单独剥卡**不动**它们(`output` 已是 core 描述符而卡仍带 ≤48K 字节的帧,和卡超 48K 时 core 自己略去 `base64` 的帧,在这两个键上读数一致)。

package/dist/trace/tool-output-media.js

@@ -1,12 +1,6 @@
+import { isMediaBlock, mediaBlockDescriptor, toolOutputBlockChars } from "@sema-agent/core";
 import { redactDeep } from "./redact.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-function isMediaBlock(b) {
-    if (b === null || typeof b !== "object" || Array.isArray(b))
-        return false;
-    const block = b;
-    return (block.type === "image" || block.type === "document") && typeof block.data === "string";
-}
-const MIME_ECHO_MAX = 255;
 export function projectToolOutput(output) {
     if (!Array.isArray(output))
         return redactDeep(output);
@@ -21,20 +15,11 @@ function isMediaCard(s) {
     const file = card.file;
     return file !== null && typeof file === "object" && !Array.isArray(file) && typeof file.base64 === "string";
 }
-export function projectToolStructured(structured) {
+export function projectToolStructured(structured, redact) {
     if (!isMediaCard(structured))
-        return redactDeep(structured);
-    const file = Object.fromEntries(Object.entries(structured.file).map(([k, v]) => [k, k === "base64" ? v : redactDeep(v)]));
-    return Object.fromEntries(Object.entries(structured).map(([k, v]) => [k, k === "file" ? file : redactDeep(v)]));
-}
-function trueSizeOf(b) {
-    if (isMediaBlock(b))
-        return b.data.length;
-    if (b !== null && typeof b === "object" && !Array.isArray(b) && b.type === "text" && typeof b.text === "string") {
-        const { type: _type, text, ...rest } = b;
-        return text.length + Math.max(0, (JSON.stringify(rest)?.length ?? 2) - 2);
-    }
-    return JSON.stringify(b)?.length ?? 0;
+        return redact(structured);
+    const file = Object.fromEntries(Object.entries(structured.file).map(([k, v]) => [k, k === "base64" ? v : redact(v)]));
+    return Object.fromEntries(Object.entries(structured).map(([k, v]) => [k, k === "file" ? file : redact(v)]));
 }
 export function toolEndMediaAsDescriptors(data) {
     const output = data.output;
@@ -45,15 +30,8 @@ export function toolEndMediaAsDescriptors(data) {
     const next = { ...data };
     if (outputHasMedia) {
         const blocks = output;
-        const totalChars = typeof data.totalChars === "number" && Number.isFinite(data.totalChars) ? data.totalChars : blocks.reduce((n, b) => n + trueSizeOf(b), 0);
-        next.output = blocks.map((b) => isMediaBlock(b)
-            ? {
-                type: b.type,
-                ...(typeof b.mimeType === "string" && b.mimeType.length <= MIME_ECHO_MAX ? { mimeType: b.mimeType } : {}),
-                bytes: Math.floor((b.data.length * 3) / 4),
-                truncated: true,
-            }
-            : b);
+        const totalChars = typeof data.totalChars === "number" && Number.isFinite(data.totalChars) ? data.totalChars : blocks.reduce((n, b) => n + toolOutputBlockChars(b), 0);
+        next.output = blocks.map((b) => (isMediaBlock(b) ? mediaBlockDescriptor(b) : b));
         next.truncated = true;
         next.totalChars = totalChars;
     }

package/dist/web-admin-client/apply-effective.js

@@ -15,6 +15,7 @@ import { judgeModelRouteEndpoint } from "../model-route-endpoint.js";
 import { gateIntentUnserviceableReason } from "../approval.js";
 import { refusedGroups } from "./apply-ledger.js";
 import { judgeConfigCandidate } from "./candidate-gate.js";
+import { declareServerWithheldEnv, withdrawServerWithheldEnv } from "../server-secret-env.js";
 const charsPerTokenOf = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
 function envDerivedModel(config) {
     const m = config.envModel;
@@ -97,17 +98,21 @@ export function applyEffective(config, eff, logger, opts) {
         return false;
     }
     const mp = staged.modelPlaneGroup.stages.models;
-    if (mp !== undefined && opts.swapPlane !== undefined) {
-        try {
-            opts.swapPlane({ models: mp.models, tiers: mp.activeTiers });
-        }
-        catch (err) {
-            logger?.warn("web_admin_model_plane_swap_refused", {
-                version: staged.version,
-                error: err instanceof Error ? err.message : String(err),
-                note: "the Runner refused the candidate model plane (swapDeps screens the whole candidate atomically — the current generation stays in force untouched); candidate refused whole, re-judged next poll (/health shows target≠applied while it persists)",
-            });
-            return false;
+    if (mp !== undefined) {
+        declareCandidateWithheldEnv(mp.modelApiKeyEnv, staged.version);
+        if (opts.swapPlane !== undefined) {
+            try {
+                opts.swapPlane({ models: mp.models, tiers: mp.activeTiers });
+            }
+            catch (err) {
+                withdrawServerWithheldEnv();
+                logger?.warn("web_admin_model_plane_swap_refused", {
+                    version: staged.version,
+                    error: err instanceof Error ? err.message : String(err),
+                    note: "the Runner refused the candidate model plane (swapDeps screens the whole candidate atomically — the current generation stays in force untouched); candidate refused whole, re-judged next poll (/health shows target≠applied while it persists)",
+                });
+                return false;
+            }
         }
     }
     commitStaged(config, staged);
@@ -141,6 +146,18 @@ export function applyEffective(config, eff, logger, opts) {
         logger?.info("web_admin_projects", { projects: Object.keys(staged.projects) });
     return true;
 }
+function declareCandidateWithheldEnv(modelApiKeyEnv, version) {
+    try {
+        declareServerWithheldEnv(modelApiKeyEnv);
+    }
+    catch (err) {
+        const entries = Object.entries(modelApiKeyEnv)
+            .map(([model, envName]) => `${model}→${envName}`)
+            .join(", ");
+        throw new Error(`model catalog (effective v${version}): a model entry's apiKeyEnv names a variable the engine cannot withhold from model-driven shells — ` +
+            `the candidate is refused whole and the current generation keeps serving; fix that entry's apiKeyEnv (entries: ${entries}). Engine: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 function commitStaged(config, staged) {
     const mp = staged.modelPlaneGroup.stages.models;
     if (mp) {

package/dist/web-admin-client/facade.d.ts

@@ -50,7 +50,7 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type EngineRestartSignal, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
-export { applyCenterReadFace, CENTER_READ_FACE_LIVE_KEYS, type CenterReadFaceApply, type CenterReadFaceReport, type ReadFaceBaseline } from "./read-face.js";
+export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
+export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS, type CenterReadFaceApply, type CenterReadFaceReport, type ReadFaceBaseline, type ReadFaceSeat } from "./read-face.js";
 export type { CenterSkillManifest, CenterMcpServer, CenterA2aPeer, CenterModel, CenterReadFace, EffectiveConfig, ExecutionRuling, SessionMirrorRuling, } from "./types.js";
 //# sourceMappingURL=facade.d.ts.map

package/dist/web-admin-client/facade.js

@@ -1,6 +1,6 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
-export { applyCenterReadFace, CENTER_READ_FACE_LIVE_KEYS } from "./read-face.js";
+export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
+export { applyCenterReadFace, buildReadFaceBaseline, buildReadFaceSwapCandidate, restoreReadFaceBaseline, CENTER_READ_FACE_LIVE_KEYS } from "./read-face.js";
 //# sourceMappingURL=facade.js.map

package/dist/web-admin-client/http-client.d.ts

@@ -88,8 +88,8 @@ export declare class WebAdminHttpError extends Error {
  * sha256 matches the manifest hash (integrity + rewrite check). The content is immutable per hash, so the
  * caller caches by hash and never re-fetches an unchanged skill. Throws a {@link WebAdminHttpError}
  * (carrying `.status`) on an HTTP error — INCLUDING 404 — or a plain Error on hash mismatch. Callers that
- * want "unknown hash → undefined" parity with the local backend inspect `.status === 404` and swallow it;
- * the legacy `applyCenterSkills` path keeps treating every throw as "skip this skill, keep baseline".
+ * want "unknown hash → undefined" parity with the local backend inspect `.status === 404` and swallow it —
+ * `RemoteConfigProvider.fetchSkillContent` does exactly that, and it is the only caller on the skills read port.
  */
 export declare function fetchSkillContent(center: CenterEndpoint, contentHash: string, fetchImpl?: typeof fetch): Promise<string>;
 /** [ref]b / [ref]① — §9.4 by-digest 补拉二函(fetchSkillContent 同姿势:HTTP+Bearer+8s 超时+

package/dist/web-admin-client/read-face.d.ts

@@ -1,22 +1,66 @@
+/**
+ * #A4([ref] 窗三件批 件1;[ref]/[ref] 承诺件)—— READ 容纳面四键的 **web-admin 消费腿**。
+ *
+ * 部署 env 的四键(`READ_FACE` / `READ_DENY_PATTERNS` / `READ_DENY_BUILTIN_TIERS` / `READ_DENY_BUILTIN_EXCLUDE`,见 config.ts)
+ * 此前是这条轴上的唯一入口:一个用 web-admin 管理整片 worker 的组织,想统一收紧 READ 面只能逐机改 env。本模块把
+ * `EffectiveConfig.readFace`(见 types.ts {@link CenterReadFace})投影到同样的四个 `ServiceConfig` 键上。
+ *
+ * ── 生效时机:**逐席由引擎答**(S-174 起 face;S-1560 / core 7.51.0 起四席全热)──────────────────────────
+ * 哪些席能热换,不是本仓的意见:`KEY_MAP` 每行的 `cfgKey` 就是 core 的席名,能不能热换由 core 的 `isSwappableDepSeat` 亲答
+ * ({@link CENTER_READ_FACE_LIVE_KEYS})。本模块按这**一个**判据分相({@link CenterReadFaceApply}):
+ *  · `boot` 相 —— 四键全落(Runner 还没建,每一席都还会 bake);
+ *  · `live` 相(refresh 拍)—— **只落引擎有活体席的键**,回执 {@link CenterReadFaceReport.changedSeats} 报这一拍换了值的席,
+ *    调用方据它向全部 boot Runner `swapDeps` 一次。引擎**没有**活体席的键 live 相**刻意不落**:写进 `config` 会让
+ *    `/health` / wiring 读面宣称一个引擎并没有在执行的 READ 姿态(而 `read-face` restart 片仍在为它要一次重启)—— 那正是这条
+ *    轴上最危险的谎(读面说收紧了、执行面没有)。
+ * 落配、`applied` 日志、换席候选、重启片的指纹读的是**同一个**判据 —— core 把某席移进 / 移出闭集,四处自动一起走
+ * (core 7.51.0 把读拒三席移了进去,而 live 相的落配当时是一句手写的「deny 三键只在 boot 相落」,与另三处的派生读法分家:
+ * 重启片说「热了」、落配说「不落」,组织收紧读拒规则 ⇒ 既不生效也不要求重启。S-1560 收成一个判据)。
+ *
+ * ── 三条规则,每条都有失败方向的论证 ──────────────────────────────────────────────────────────
+ *
+ * ① **env 显式恒赢,逐键判**(operator-knob 律)。env 是**这台机器**的部署主权表达,center 是组织下发;
+ *    冲突时保留 env 并留一条点名 warn。为什么不照 6 闸的「center 覆盖 env」:那六闸是**限额/治理**面
+ *    (组织比单机更知道该收多紧),而 READ 容纳面描述的是**这台机器的磁盘上有什么** —— 运维在这台机器上
+ *    写下 `READ_FACE=roots` 时知道的事情,组织的下发面不知道。静默盖掉它是本仓「部署级旋钮」纪律的反面。
+ *    逐键而非整域:env 只写了 face 时,center 的三个 deny 键照常落(否则一个 env 键会把整片组织策略挡掉)。
+ *    判据 = **键在场**(`!== undefined`):`readDenyBuiltinTiers: []` 是 env `none` 的显式空姿态,
+ *    不是「没设过」—— 用真值判会把「一档内建都不要」这个显式表态判成缺席。
+ *    🔴 判在**基线**上(本机 env / posture,center 之前的值),不是判「键现在在不在场」:center 自己上一拍写下的值
+ *    也让键在场,拿它当 env 就会把组织自己的第二次发布挡在门外。
+ *
+ * ② **坏值整域拒 + 响亮**([ref] 安全轴)。任何一个成员过不了引擎自己的校验器 ⇒ 整个 readFace 域不落,
+ *    保留 env 前值 + warn 点名。两个方向都要:半应用一份 READ 姿态(收紧了一半)会让运维以为策略生效;
+ *    而 throw 会让一次坏发布把常驻进程炸掉(env 腿 throw 是对的 —— 那是启动期、由本机运维自己写的值)。
+ *    与 `stageApprovalRequire` 的域级拒绝先例同形。
+ *
+ * ③ **校验一律交给引擎**(`compileReadDeny` / `resolveReadDenyBuiltins`)。宿主不自造第二份判定语义,
+ *    与 env 腿逐字同款;且校验跑在**合成后的最终姿态**上(env 键 + center 键混合形),否则
+ *    「env 选了档位、center 删了一个不在该档里的行名」这类跨腿坏组合会漏过。
+ */
+import { type SwappableDeps } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { ReadFaceSource } from "../read-face-posture.js";
 import type { Logger } from "../observability/logger.js";
 import type { CenterReadFace, EffectiveConfig } from "./types.js";
-/**
- * S-174 —— 哪些 center 键是**热换席**。判据**不是本仓的意见**:`KEY_MAP` 的 `cfgKey` 落在 core 的闭集
- * `SWAPPABLE_DEP_SEATS` 里(经 `isSwappableDepSeat` 亲问)⇒ 这个键 refresh 期可换;否则它是 boot-baked
- * 座,只有重启能换。core 加/删可换席 ⇒ 本集合与 `read-face` restart 片的指纹**同时**跟着走,不留第二份
- * 手抄表(restart-signal.ts 读的就是这一只)。
- */
-export declare const CENTER_READ_FACE_LIVE_KEYS: ReadonlySet<keyof CenterReadFace>;
-/** 本进程的**前 center** READ face 姿态(env / posture / 引擎默认)。`live` 相必带 —— 一次发布**撤回**
- *  `face` 键时,活席要还原到它,而不是把上一份发布的档位无限期latch 住(那是这条轴上的 fail-OPEN 方向:
- *  组织把 `open` 撤回之后,worker 还在 open)。boot 相不需要:那一刻 `config` 上的值就是基线。 */
-export interface ReadFaceBaseline {
-    readonly readFace?: "open" | "roots";
+/** 四个 center 成员落到的 `ServiceConfig` 键 —— 同时就是 core 的席名(`SWAPPABLE_DEP_SEATS` 的成员名)。 */
+export type ReadFaceSeat = "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude";
+type ReadFaceSeatValues = {
+    readonly [K in ReadFaceSeat]?: ServiceConfig[K];
+};
+/** 本进程的**前 center** READ 姿态(env / posture / 引擎默认)—— 四键的值 + `readFace` 的来源。三处读它:
+ *  ① env-wins 判据(基线上谁被 env 占住);② `live` 相的撤回臂(一次发布**撤回**某键时,活席要还原到它,而不是把上一份发布的
+ *  值无限期 latch 住 —— 那是这条轴上的 fail-OPEN 方向:组织把 `open` / 一条 deny 规则撤回之后,worker 还在旧姿态上);
+ *  ③ 换席抛时的整体回滚(由 {@link buildReadFaceBaseline} 在调用前现取一份)。boot 相不需要传:那一刻 `config` 上的值就是基线。 */
+export type ReadFaceBaseline = ReadFaceSeatValues & {
     readonly readFaceSource: ReadFaceSource;
-}
-/** 本次调用落在哪一相(见文件头注「一席热、三席重启」)。判别联合而不是可选字段:`baseline` 只在
+};
+/** 取 `config` 此刻的 READ 姿态快照(纯数据;数组按引用 —— 本模块只整值替换、从不原地改)。 */
+export declare function buildReadFaceBaseline(config: ServiceConfig): ReadFaceBaseline;
+/** 把 `config` 的 READ 姿态整体写回一份快照(换席抛时的回滚;快照里缺席的键写回 `undefined`)。 */
+export declare function restoreReadFaceBaseline(config: ServiceConfig, snap: ReadFaceBaseline): void;
+export declare const CENTER_READ_FACE_LIVE_KEYS: ReadonlySet<keyof CenterReadFace>;
+/** 本次调用落在哪一相(见文件头注「逐席由引擎答」)。判别联合而不是可选字段:`baseline` 只在
  *  `live` 相有意义,写成可选就等于允许一次「没有基线的 live 调用」——那正是撤回臂会静默失效的形。 */
 export type CenterReadFaceApply = {
     readonly phase: "boot";
@@ -24,20 +68,29 @@ export type CenterReadFaceApply = {
     readonly phase: "live";
     readonly baseline: ReadFaceBaseline;
 };
-/** 调用回执。`envHeld` 同旧返回值(喂 `RestartSliceCtx.readFaceEnvHeld`);`faceChanged` 是 live 相的
- *  换席信号 —— 真 ⇒ 调用方必须 `swapDeps({ readFace: config.readFace })` 一次,否则 config 与 Runner 分家。 */
+/** 调用回执。`envHeld` 同旧返回值(喂 `RestartSliceCtx.readFaceEnvHeld`);`changedSeats` 是 live 相的换席信号 ——
+ *  这一拍**值真的变了**的活体席(按 {@link ReadFaceSeat} 席名)。非空 ⇒ 调用方必须把这些席的值 `swapDeps` 给全部 boot
+ *  Runner 一次,否则 config 与 Runner 分家。boot 相无人消费(Runner 还没建)。 */
 export interface CenterReadFaceReport {
     readonly envHeld: readonly (keyof CenterReadFace)[];
-    readonly faceChanged: boolean;
+    readonly changedSeats: readonly ReadFaceSeat[];
 }
 /**
- * 应用 center 的 readFace 域(**boot-only**:调用点在 boot 拉取之后、`createRunnerDeps` 之前)。
- * 缺席 ⇒ 零触碰。规则见文件头注 ①②③。
+ * 换席候选:`changed`(回执的 {@link CenterReadFaceReport.changedSeats})里每一席取 `seats` 里的值。
+ * `seats` 由调用方从部署姿态座席族的唯一属主取(`boot/runner-deps.ts` `buildDeploymentPostureSeats`)—— 席的**值**是座席族
+ * 铸的(例如 `readDenyPatterns` 并入 LKG 派生行),本模块只决定**换哪几席**。键在场即指令:值为 `undefined` 的席也进候选
+ * (core 据此把那一席清回引擎缺省 —— 撤回臂靠它兑现)。
+ */
+export declare function buildReadFaceSwapCandidate(seats: Pick<SwappableDeps, ReadFaceSeat>, changed: readonly ReadFaceSeat[]): SwappableDeps;
+/**
+ * 应用 center 的 readFace 域(boot 相:调用点在 boot 拉取之后、`createRunnerDeps` 之前;live 相:refresh 拍两条 commit 腿)。
+ * 缺席 ⇒ 零触碰(live 相:撤回臂把活体席还原到基线)。规则见文件头注 ①②③。
  *
- * 返回值 = **本机 env 显式占住的 center 键名**(与本次发布内容无关的部署事实)。调用方把它喂给
+ * 返回值 `envHeld` = **本机 env 显式占住的 center 键名**(与本次发布内容无关的部署事实)。调用方把它喂给
  * `RestartSliceCtx.readFaceEnvHeld`,`read-face` restart 片于是只指纹「真会 boot-bake 的那部分」——
  * 否则 center 改一个本机永远用不上的键,整片 fleet 会为一次对自己毫无影响的发布滚动重启一遍
  * (codex 交叉复审 finding 2,验真后采纳的那一半)。
  */
 export declare function applyCenterReadFace(config: ServiceConfig, eff: EffectiveConfig, logger?: Logger, apply?: CenterReadFaceApply): CenterReadFaceReport;
+export {};
 //# sourceMappingURL=read-face.d.ts.map

package/dist/web-admin-client/read-face.js

@@ -1,11 +1,43 @@
 import { compileReadDeny, isSwappableDepSeat, resolveReadDenyBuiltins } from "@sema-agent/core";
+export function buildReadFaceBaseline(config) {
+    return {
+        ...(config.readFace !== undefined ? { readFace: config.readFace } : {}),
+        readFaceSource: config.readFaceSource,
+        ...(config.readDenyPatterns !== undefined ? { readDenyPatterns: config.readDenyPatterns } : {}),
+        ...(config.readDenyBuiltinTiers !== undefined ? { readDenyBuiltinTiers: config.readDenyBuiltinTiers } : {}),
+        ...(config.readDenyBuiltinExclude !== undefined ? { readDenyBuiltinExclude: config.readDenyBuiltinExclude } : {}),
+    };
+}
+export function restoreReadFaceBaseline(config, snap) {
+    config.readFace = snap.readFace;
+    config.readFaceSource = snap.readFaceSource;
+    config.readDenyPatterns = snap.readDenyPatterns;
+    config.readDenyBuiltinTiers = snap.readDenyBuiltinTiers;
+    config.readDenyBuiltinExclude = snap.readDenyBuiltinExclude;
+}
 const KEY_MAP = [
-    { centerKey: "face", cfgKey: "readFace", envHolds: (c) => c.readFaceSource === "env" },
-    { centerKey: "denyPatterns", cfgKey: "readDenyPatterns", envHolds: (c) => c.readDenyPatterns !== undefined },
-    { centerKey: "denyBuiltinTiers", cfgKey: "readDenyBuiltinTiers", envHolds: (c) => c.readDenyBuiltinTiers !== undefined },
-    { centerKey: "denyBuiltinExclude", cfgKey: "readDenyBuiltinExclude", envHolds: (c) => c.readDenyBuiltinExclude !== undefined },
+    { centerKey: "face", cfgKey: "readFace", envHolds: (b) => b.readFaceSource === "env" },
+    { centerKey: "denyPatterns", cfgKey: "readDenyPatterns", envHolds: (b) => b.readDenyPatterns !== undefined },
+    { centerKey: "denyBuiltinTiers", cfgKey: "readDenyBuiltinTiers", envHolds: (b) => b.readDenyBuiltinTiers !== undefined },
+    { centerKey: "denyBuiltinExclude", cfgKey: "readDenyBuiltinExclude", envHolds: (b) => b.readDenyBuiltinExclude !== undefined },
 ];
-export const CENTER_READ_FACE_LIVE_KEYS = new Set(KEY_MAP.filter((r) => isSwappableDepSeat(r.cfgKey)).map((r) => r.centerKey));
+const LIVE_SEATS = new Set(KEY_MAP.filter((r) => isSwappableDepSeat(r.cfgKey)).map((r) => r.cfgKey));
+export const CENTER_READ_FACE_LIVE_KEYS = new Set(KEY_MAP.filter((r) => LIVE_SEATS.has(r.cfgKey)).map((r) => r.centerKey));
+function putCandidateSeat(candidate, key, value) {
+    candidate[key] = value;
+}
+export function buildReadFaceSwapCandidate(seats, changed) {
+    const candidate = {};
+    for (const seat of changed)
+        putCandidateSeat(candidate, seat, seats[seat]);
+    return candidate;
+}
+function putSeat(config, key, value) {
+    config[key] = value;
+}
+function sameSeatValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
 class ReadFaceDomainError extends Error {
 }
 function normalizeDenyPatterns(raw) {
@@ -44,18 +76,25 @@ function normalizeNameList(field, raw) {
     });
 }
 export function applyCenterReadFace(config, eff, logger, apply = { phase: "boot" }) {
-    const envHeldKeys = KEY_MAP.filter((r) => r.envHolds(config)).map((r) => r.centerKey);
-    const faceBefore = config.readFace;
-    const report = () => ({ envHeld: envHeldKeys, faceChanged: config.readFace !== faceBefore });
-    const revertFaceToBaseline = () => {
-        if (apply.phase !== "live")
+    const base = apply.phase === "live" ? apply.baseline : buildReadFaceBaseline(config);
+    const envHeldKeys = KEY_MAP.filter((r) => r.envHolds(base)).map((r) => r.centerKey);
+    const lands = (seat) => apply.phase === "boot" || LIVE_SEATS.has(seat);
+    const before = buildReadFaceBaseline(config);
+    const report = () => ({
+        envHeld: envHeldKeys,
+        changedSeats: KEY_MAP.filter((r) => LIVE_SEATS.has(r.cfgKey) && !sameSeatValue(before[r.cfgKey], config[r.cfgKey])).map((r) => r.cfgKey),
+    });
+    const revertToBaseline = (r) => {
+        if (apply.phase !== "live" || !lands(r.cfgKey))
             return;
-        config.readFace = apply.baseline.readFace;
-        config.readFaceSource = apply.baseline.readFaceSource;
+        putSeat(config, r.cfgKey, base[r.cfgKey]);
+        if (r.cfgKey === "readFace")
+            config.readFaceSource = base.readFaceSource;
     };
     const domain = eff.readFace;
     if (domain === undefined || domain === null) {
-        revertFaceToBaseline();
+        for (const r of KEY_MAP)
+            revertToBaseline(r);
         return report();
     }
     if (typeof domain !== "object" || Array.isArray(domain)) {
@@ -66,7 +105,7 @@ export function applyCenterReadFace(config, eff, logger, apply = { phase: "boot"
         return report();
     }
     const d = domain;
-    const envHeld = KEY_MAP.filter((r) => d[r.centerKey] !== undefined && r.envHolds(config)).map((r) => `${r.cfgKey} (readFace.${r.centerKey})`);
+    const envHeld = KEY_MAP.filter((r) => d[r.centerKey] !== undefined && r.envHolds(base)).map((r) => `${r.cfgKey} (readFace.${r.centerKey})`);
     let staged;
     try {
         const normalized = {
@@ -80,10 +119,12 @@ export function applyCenterReadFace(config, eff, logger, apply = { phase: "boot"
         if (normalized.readDenyBuiltinTiers !== undefined || normalized.readDenyBuiltinExclude !== undefined) {
             resolveReadDenyBuiltins(builtinsArg(normalized.readDenyBuiltinTiers, normalized.readDenyBuiltinExclude));
         }
-        staged = Object.fromEntries(KEY_MAP.filter((r) => !r.envHolds(config)).map((r) => [r.cfgKey, normalized[r.cfgKey]]).filter(([, v]) => v !== undefined));
-        const finalPatterns = staged.readDenyPatterns ?? config.readDenyPatterns;
-        const finalTiers = staged.readDenyBuiltinTiers ?? config.readDenyBuiltinTiers;
-        const finalExclude = staged.readDenyBuiltinExclude ?? config.readDenyBuiltinExclude;
+        staged = Object.fromEntries(KEY_MAP.filter((r) => !r.envHolds(base)).map((r) => [r.cfgKey, normalized[r.cfgKey]]).filter(([, v]) => v !== undefined));
+        const baseSeats = base;
+        const finalOf = (k) => staged[k] ?? (lands(k) ? baseSeats[k] : config[k]);
+        const finalPatterns = finalOf("readDenyPatterns");
+        const finalTiers = finalOf("readDenyBuiltinTiers");
+        const finalExclude = finalOf("readDenyBuiltinExclude");
         if (finalPatterns !== undefined)
             compileReadDeny(finalPatterns);
         if (finalTiers !== undefined || finalExclude !== undefined)
@@ -96,20 +137,19 @@ export function applyCenterReadFace(config, eff, logger, apply = { phase: "boot"
         });
         return report();
     }
-    if (staged.readFace !== undefined) {
-        config.readFace = staged.readFace;
-        config.readFaceSource = "center";
-    }
-    else {
-        revertFaceToBaseline();
-    }
-    if (apply.phase === "boot") {
-        if (staged.readDenyPatterns !== undefined)
-            config.readDenyPatterns = staged.readDenyPatterns;
-        if (staged.readDenyBuiltinTiers !== undefined)
-            config.readDenyBuiltinTiers = staged.readDenyBuiltinTiers;
-        if (staged.readDenyBuiltinExclude !== undefined)
-            config.readDenyBuiltinExclude = staged.readDenyBuiltinExclude;
+    const landed = [];
+    for (const r of KEY_MAP) {
+        if (!lands(r.cfgKey))
+            continue;
+        const v = staged[r.cfgKey];
+        if (v === undefined) {
+            revertToBaseline(r);
+            continue;
+        }
+        putSeat(config, r.cfgKey, v);
+        if (r.cfgKey === "readFace")
+            config.readFaceSource = "center";
+        landed.push(r.cfgKey);
     }
     if (envHeld.length > 0) {
         logger?.warn("web_admin_read_face_env_wins", {
@@ -117,13 +157,13 @@ export function applyCenterReadFace(config, eff, logger, apply = { phase: "boot"
             note: "this machine's explicit env READ-face keys WIN over the published readFace domain (deployment sovereignty) — the published values for these keys were NOT applied; unset the env key if the org publication should own it",
         });
     }
-    if (Object.keys(staged).length > 0) {
+    if (landed.length > 0) {
         logger?.info("web_admin_read_face", {
-            applied: Object.keys(staged).filter((k) => apply.phase === "boot" || KEY_MAP.some((r) => r.cfgKey === k && CENTER_READ_FACE_LIVE_KEYS.has(r.centerKey))),
-            ...(staged.readFace !== undefined ? { face: staged.readFace } : {}),
+            applied: landed,
+            ...(staged.readFace !== undefined && landed.includes("readFace") ? { face: staged.readFace } : {}),
             note: apply.phase === "boot"
                 ? "boot phase — every seat still bakes into the runner deps that are about to be assembled"
-                : "live phase — the read FACE is hot-swapped into every boot Runner (core swapDeps seat); the deny seats stay boot-baked and keep asking for the `read-face` restart slice",
+                : "live phase — the landed seats are hot-swapped into every boot Runner (core swapDeps seats); a seat the engine cannot hot-swap is not written here and keeps asking for the `read-face` restart slice",
         });
     }
     return report();