@sema-agent/server 1.322.0 → 2.0.0

package/dist/config-center/apply-effective.js

@@ -1,3 +1,10 @@
+/**
+ * EffectiveConfig application — mutate the boot `ServiceConfig` OVER with a pulled `EffectiveConfig`
+ * (models/roles/tiers/projects `applyEffective`, the 6 runtime gates `applyRuntimeGates`, the per-request-hot
+ * governance baton `applyRuntimeHot`) plus their shared helpers (`toModel`, `mutateInPlace`,
+ * `resolveDefaultModelName`, `logEffectiveDiff`, `runtimeHasActiveGate`). Split out of `sema-registry.ts`
+ * (design/158 A13, internal-lossless — the facade re-exports every symbol below unchanged).
+ */
 import { isThinkingLevel } from "@sema-agent/core";
 import { resolveActiveTiers, SEALED_BOX_ALG } from "@sema-agent/registry-core";
 import { sealedKeyPoison } from "../sealed-key.js";
@@ -6,8 +13,11 @@ import { validateCommandRules } from "../runtime-governance.js";
 import { projectCollabToWorkflows, registerCollabWorkflows } from "../capabilities/collab-workflows.js";
 import { registerTeams } from "../capabilities/team.js";
 const asModelThinking = (v) => (v && isThinkingLevel(v) && v !== "off" ? v : undefined);
+/** design/123: accept only a positive finite roster charsPerToken (fail-safe to env default / core 4). */
 const charsPerTokenOf = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
 function toModel(m, envDefaults = {}) {
+    // design/111 L2②: a center model MAY declare defaultThinking/reasoningEffortLevels; absent → inherit the env-derived
+    // model's values (BL-8 — same class as reasoning/contextWindow/maxTokens, else a roster silently drops the env default).
     const thinkingDefault = asModelThinking(m.defaultThinking) ?? envDefaults.defaultThinking;
     const effortLevels = (m.reasoningEffortLevels ? m.reasoningEffortLevels.map(asModelThinking).filter((x) => x !== undefined) : undefined) ?? envDefaults.reasoningEffortLevels ?? [];
     const model = {
@@ -15,46 +25,93 @@ function toModel(m, envDefaults = {}) {
         name: m.name,
         provider: m.provider,
         api: m.api,
+        // 实机 /model 切 Kimi 404 定谳: a catalog model MAY carry its own gateway URL — the
+        // hardcoded "" made core's brain fall back to the boot-env endpoint, so cross-endpoint `body.model`
+        // selection hit the WRONG gateway (kimi id → Qwen vLLM → 404). Absent still = "" (brain env default;
+        // byte-compat for single-gateway rosters). core brain honors model.baseUrl; keys stay per-model via apiKeyEnv.
         baseUrl: m.baseUrl ?? "",
+        // BL-8 extended (systematic-audit): fall back to the ENV-derived model's reasoning, not Boolean(undefined)=false —
+        // else a center roster that omits `reasoning` SILENTLY disables it even though the env lane defaults it ON
+        // (config.ts MODEL_REASONING="true"). A center model MAY set false to override. Same class as contextWindow/maxTokens.
         reasoning: m.reasoning !== undefined ? Boolean(m.reasoning) : (envDefaults.reasoning ?? true),
         input: m.vision ? ["text", "image"] : ["text"],
+        // BL-8: fall back to the ENV-derived model's value (MODEL_CONTEXT_WINDOW / MODEL_MAX_TOKENS), not a
+        // hardcoded literal — else a center roster that replaces the env model SILENTLY clamps maxTokens to 4096
+        // (the prod review-gw runs deepseek at 32000), shrinking every response. A center model MAY still set its
+        // own value to override. (ROBUSTNESS-BACKLOG:28 / BL-8.)
         contextWindow: m.contextWindow ?? envDefaults.contextWindow ?? 262144,
         maxTokens: m.maxTokens ?? envDefaults.maxTokens ?? 4096,
+        // design/123 D2 (BL-8 class): center override ?? env default (MODEL_CHARS_PER_TOKEN) ?? omit = core 4.
+        // Positive-finite guard mirrors the env lane — a bad roster value must not zero structural estimates.
         ...(charsPerTokenOf(m.charsPerToken) !== undefined || envDefaults.charsPerToken !== undefined
             ? { charsPerToken: charsPerTokenOf(m.charsPerToken) ?? envDefaults.charsPerToken }
             : {}),
         cost: m.cost
             ? { input: m.cost.input, output: m.cost.output, cacheRead: m.cost.cacheRead ?? 0, cacheWrite: m.cost.cacheWrite ?? 0 }
             : { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        // Explicit cache family by provider (core 1.23) — same as the env path in config.ts. Anthropic brain
+        // reports input EXCLUDING cached; the openai gateway INCLUDES it (design/18).
         params: { ...(m.tier ? { tier: m.tier } : {}), promptCacheFamily: m.provider === "anthropic" ? "input-excludes-cached" : "input-includes-cached" },
+        // design/111 L2②: per-model default thinking + endpoint-accepted tiers (center override ?? env default, BL-8).
         ...(thinkingDefault ? { defaultThinking: thinkingDefault } : {}),
         ...(effortLevels.length > 0 && m.provider !== "anthropic" ? { compat: { reasoningEffortLevels: effortLevels } } : {}),
+        // Generation tuning (1.60) carried verbatim — without this a center roster that replaces the env model
+        // would silently drop the degenerate-looping prevention (freq/pres penalties). Absent → unchanged.
         ...(m.extraBody ? { extraBody: m.extraBody } : {}),
+        // Per-model behavior-slot sentences ([998]⑤c consumer half) — verbatim, same posture as extraBody.
         ...(Array.isArray(m.promptGuidance) && m.promptGuidance.length > 0 ? { promptGuidance: m.promptGuidance.map(String) } : {}),
     };
+    // [818]① 1M dual-window: an explicit roster `autoCompactTokens` (structural, like tier passthroughs) wins;
+    // else a >=1M contextWindow derives the CC-aligned 967000; else absent. Same helper as the env lane.
     const explicitAct = m.autoCompactTokens;
     applyAutoCompactWindow(model, typeof explicitAct === "number" ? explicitAct : undefined);
     return model;
 }
+/** Apply center config OVER the env-derived config (mutates `config`). Empty domains keep env defaults. */
+/** Replace a record's contents IN PLACE (clear keys, copy source) so holders of the SAME reference see the
+ *  change. This is what makes models/roles/pricing HOT-apply: core's Runner reads
+ *  `this.deps.models/roles/pricing` LIVE per-task and `/v1/models` reads `config.models` — both share the
+ *  reference captured at boot, so mutating it (vs reassigning) updates both with no split, no Runner rebuild. */
 export function mutateInPlace(target, source) {
     for (const k of Object.keys(target))
         delete target[k];
     Object.assign(target, source);
 }
 export function applyEffective(config, eff, logger, opts = {}) {
+    // version 0 / empty effective = the sema-registry has nothing for us yet — typically CONFIG_PUBLISH_MODE
+    // is ON but nothing has been published. We do NOT wipe: models/roles fall back to env (the enabled>0
+    // guard below), teams to BUILTIN_TEAMS (registerTeams resets to built-ins). Warn once at boot so the
+    // operator knows their config isn't live (publish a version, or disable the publish gate). See the
+    // sema-registry's ORCHESTRATOR-REVIEW §④ publish-gate contract.
     if (!opts.teamsOnly && !eff.version) {
         logger?.warn("sema_registry_unpublished", {
             version: eff.version,
             note: "empty/unpublished effective config — using env + built-in fallback; publish a config or unset CONFIG_PUBLISH_MODE",
         });
     }
+    // models/roles HOT-apply on BOTH boot and refresh (TOC "save = effective"). We MUTATE
+    // config.models/roles IN PLACE (mutateInPlace) — NOT reassign — so the live Runner (reads `this.deps.models/
+    // roles` per-task by reference) and `/v1/models` (reads config.models) share the one updated object with NO
+    // split, no Runner rebuild, no core change. Caller (main.ts refresh) additionally refreshes `pricing` (same
+    // ref) + rebuilds `keyResolver`. (Was startup-only when reassignment split the Runner's ref from config.)
     const enabled = (eff.models?.models ?? []).filter((m) => m.enabled !== false);
+    // codex R10: `deferModelPlane` skips the WHOLE model plane (models/roles/tiers + per-model keys) — main.ts
+    // sets it when the Runner is tier-frozen (private expanded copy) and the plane changed: hot-applying would
+    // split admission (/v1/models, catalog gates) from the Runner's frozen generation, letting a same-key retarget
+    // silently route/bill the stale Model object through the restart window. Deferred = live plane stays on the
+    // Runner's generation; the models-tiers restart slice signals the orchestrator; the restarted process applies
+    // the new plane at boot BEFORE Runner construction. Caller logs the deferral (never silent).
     if (enabled.length > 0 && opts.deferModelPlane !== true) {
         const models = {};
         const modelApiKeyEnv = {};
-        const modelApiKeys = {};
+        const modelApiKeys = {}; // sealed-box 解封明文(内存-only,绝不日志/落盘)或毒丸标记(解封失败,见下)
+        // Capture the env-derived model's generation bounds BEFORE the loop overwrites config.model (line below):
+        // a center model that omits maxTokens/contextWindow inherits the operator's env values, not a literal (BL-8).
         const envDefaults = { maxTokens: config.model.maxTokens, contextWindow: config.model.contextWindow, reasoning: config.model.reasoning, charsPerToken: config.model.charsPerToken, defaultThinking: config.model.defaultThinking, reasoningEffortLevels: config.model.compat?.reasoningEffortLevels };
         for (const m of enabled) {
+            // Guard (since 1.128.0): a registry baseUrl now DIRECTS model traffic (incl. that model's
+            // Authorization key) — a registry editor is a lower-trust writer than the env, so a non-http(s)/unparsable
+            // value is REJECTED back to "" (boot-env gateway) and every honored override is logged (observable routing).
             const rawBaseUrl = m.baseUrl;
             let safeUrl = rawBaseUrl;
             if (rawBaseUrl) {
@@ -74,6 +131,22 @@ export function applyEffective(config, eff, logger, opts = {}) {
                 }
             }
             models[m.name] = toModel(safeUrl === rawBaseUrl ? m : { ...m, baseUrl: safeUrl }, envDefaults);
+            // Sealed-box custody (registry-core 0.10.5): a model MAY carry `sealedApiKey` — the
+            // api key pasted in the web UI and sealed BROWSER-SIDE against this host's X25519 public key; the
+            // center stores only the ciphertext. We unseal with the private key registered under the EXACT
+            // `publicKeyId` (no try-every-key scanning — the contract selects precisely) and inject the
+            // plaintext into the in-memory per-model key pipeline (config.modelApiKeys → getApiKeyAndHeaders).
+            // Mutual exclusion (contract): sealed OUTRANKS apiKeyEnv when both are set — and STRICTLY so: a
+            // sealed key that fails to unseal (missing private key / bad base64 / MAC failure) does NOT fall
+            // back to the env-NAME reference. Falling back would turn "the key I pasted isn't live" into a
+            // silent misroute onto some stale env key; we fail LOUD (warn). And since a merely-ABSENT map
+            // entry is indistinguishable from "no per-model key configured" — which with a gateway
+            // MODEL_API_KEY deployed meant the model's tasks silently burned the shared account — a failed
+            // unseal plants a POISON PILL in the map instead of injecting nothing: the key resolver turns it
+            // into a task-level SealedKeyPoisonedError on every brain call (the gateway key is NEVER a silent
+            // fallback for a broken sealed key) until the operator fixes custody and a later apply delivers a
+            // decryptable ciphertext (the rebuild below makes recovery automatic). 🔴 Neither the plaintext
+            // NOR the ciphertext ever reaches a log line or the poison object (write-only discipline).
             if (m.sealedApiKey) {
                 const s = m.sealedApiKey;
                 if (s.alg !== SEALED_BOX_ALG) {
@@ -98,18 +171,30 @@ export function applyEffective(config, eff, logger, opts = {}) {
                     }
                 }
             }
+            // Per-model key: center declares the env var NAME (never the secret) holding this model's upstream
+            // key. Drives the spec's getApiKeyAndHeaders so each model authenticates with its own account; the
+            // value is resolved from process.env in THIS service (secrets stay in env, design/15). A model
+            // without apiKeyEnv (or whose env var is unset) falls back to the gateway key — purely additive.
+            // (`else if` on sealedApiKey ABSENCE: a sealed model never consults the env reference — see above.)
             else if (m.apiKeyEnv) {
                 if (process.env[m.apiKeyEnv])
                     modelApiKeyEnv[m.name] = m.apiKeyEnv;
                 else
                     logger?.warn("sema_registry_model_key_env_missing", { model: m.name, apiKeyEnv: m.apiKeyEnv, hint: "env var not set in this service — model falls back to the gateway key" });
             }
+            // A center model whose provider has no matching brain in THIS service's env will mis-route:
+            // createRoutingBrain falls back to the gateway brain. The anthropic route needs ANTHROPIC_API_KEY.
             if (m.provider === "anthropic" && !config.anthropic) {
                 logger?.warn("sema_registry_model_no_brain", { model: m.name, provider: m.provider, hint: "set ANTHROPIC_API_KEY in this service's env, else it mis-routes to the gateway brain" });
             }
         }
-        config.modelApiKeyEnv = modelApiKeyEnv;
-        config.modelApiKeys = modelApiKeys;
+        config.modelApiKeyEnv = modelApiKeyEnv; // reassign ok — keyResolver is rebuilt from it on refresh (main.ts)
+        // same rebuild contract; plaintext values — memory-only, never logged. Poison markers ride the same
+        // map (they ARE per-model key state: "configured but broken"); the cast bridges config.ts's
+        // plaintext-only field type until it is widened to Record<string, string | SealedKeyPoison>.
+        config.modelApiKeys = modelApiKeys; // 类型已放真(string | SealedKeyPoison),桥接 cast 退役
+        // weight-at-burn 源:quotaWeight 按 name+id 双键索引(tracer 的 brain.call e.model=模型 id,
+        // 目录键=name——双键免猜);非法值(≤0/NaN)按缺省 1 丢弃。IN PLACE 与 models 同批 hot-apply。
         const quotaWeights = {};
         for (const m of enabled) {
             const qw = typeof m.quotaWeight === "number" && Number.isFinite(m.quotaWeight) && m.quotaWeight > 0 ? m.quotaWeight : undefined;
@@ -127,27 +212,53 @@ export function applyEffective(config, eff, logger, opts = {}) {
             else if ("select" in tgt)
                 roles[role] = { select: tgt.select };
         }
+        // registry-core 0.9.0: tier groups → the engine's single active tier table. `resolveActiveTiers`
+        // is registry-core's ONE resolution point (active group → its bound tiers; no active / dangling / all-unbound
+        // → undefined = INERT). Values are catalog NAME strings (open, not enum'd); dangling bindings were already
+        // culled center-side. mutateInPlace keeps the reference RunnerDeps.tiers holds — the expansion itself happens
+        // at Runner CONSTRUCTION (core 1.265 expandTiers), so a refresh-time change is restart-to-apply like models.
+        // NOTE: the wire face (this module's EffectiveConfig) carries the JSON body verbatim, so tierGroups ride
+        // eff.models even though CenterModel doesn't type them — resolveActiveTiers reads them structurally.
         const activeTiers = resolveActiveTiers(eff.models) ?? {};
+        // [865]①(clay 生产实锤:onboard 选 kimi 实跑 Qwen)显式默认解析——enabled[0] 会被任何改变 pool 顺序的写
+        // 静默翻转,default 必须消费 wire 里已有的显式意图。解析单源 = resolveDefaultModelName(dry-run 的
+        // wouldDefaultModel 共用同一只,报数与真 apply 永不撕裂——codex M2)。
         const picked = resolveDefaultModelName(eff, (n) => models[n] !== undefined, enabled[0].name, (source, name) => logger?.warn("sema_registry_default_dangling", { source, name, hint: "explicit default names a model that is not in the enabled catalog — falling to the next source" }));
         const defaultName = picked.name;
         const defaultSource = picked.source;
         models.default = models[defaultName];
-        mutateInPlace(config.models, models);
+        mutateInPlace(config.models, models); // IN PLACE: keep the ref the Runner + /v1/models share (hot-apply)
         config.model = config.models.default;
         if (Object.keys(roles).length > 0)
-            mutateInPlace(config.roles, roles);
+            mutateInPlace(config.roles, roles); // IN PLACE: Runner reads this.deps.roles live
         mutateInPlace(config.tiers, activeTiers);
         logger?.info("sema_registry_models", { count: enabled.length, default: config.model.id, defaultSource, roles: Object.keys(roles), tiers: Object.keys(config.tiers), sealedKeys: Object.values(modelApiKeys).filter((v) => typeof v === "string").length, sealedPoisoned: Object.values(modelApiKeys).filter((v) => typeof v !== "string").length });
     }
+    // Runtime governance/limit gates (phase-2): STARTUP only (restart-to-apply) — the live RateLimiter / CostQuota
+    // / approval gate are built from `config` AFTER this in main.ts, so mutating it here before they're constructed
+    // is what takes effect; a refresh (teamsOnly) must NOT touch them (the running gates hold their boot values).
+    // governance 切新位:治理三件优先读 governance 域(真值),runtime 旧位(双写镜像)fallback——
+    // 双写期两处逐键相等语义不变;center 撤双写后 governance 即唯一来源。限额残余(rateLimit/cost 五件)仍在 runtime。
     const gatesView = eff.governance ? { ...eff.runtime, ...eff.governance } : eff.runtime;
     if (!opts.teamsOnly)
         applyRuntimeGates(config, gatesView, logger);
+    // Runtime governance "second baton" (center §10): autonomy + commandPolicy are per-request HOT (read live in
+    // resolveSpec), NOT baked into boot middleware → apply on BOTH boot and refresh (outside the teamsOnly guard) so
+    // they hot-reload. No restart-to-apply signal (they take effect on the next task without a restart).
     applyRuntimeHot(config, gatesView, logger);
+    // Teams → registry (hot-reloadable; center overrides/extends the built-ins).
+    // codex R11: teams + collab workflows carry MODEL REFERENCES (member.model / workflow model args) — when the
+    // model plane is deferred (tier-frozen Runner, see the deferModelPlane guard above) these faces must defer
+    // WITH it, or a candidate that atomically adds/retargets a model AND updates a team/workflow to reference it
+    // publishes a mixed generation: the new template goes live while config.models/the Runner stay old (a new ref
+    // fails as unknown; a same-name retarget silently executes stale). One catalog generation = one visibility.
     if (opts.deferModelPlane !== true) {
         const teams = {};
         for (const t of (eff.teams?.teams ?? []).filter((t) => t.enabled !== false)) {
             teams[t.name] = {
                 name: t.name,
+                // F8: honor member.model (core TeamMember.model supports it) — was silently dropped, leaving the
+                // member to fall back to the "team" role instead of the operator's chosen model.
                 members: t.members.map((mm) => ({ role: mm.role, ...(mm.model ? { model: mm.model } : {}), modelRole: mm.modelRole, systemPrompt: mm.systemPrompt })),
                 rounds: t.rounds,
                 synthesizer: t.synthesizer ? { role: t.synthesizer.role, modelRole: t.synthesizer.modelRole, systemPrompt: t.synthesizer.systemPrompt } : undefined,
@@ -156,6 +267,11 @@ export function applyEffective(config, eff, logger, opts = {}) {
         registerTeams(teams);
         if (Object.keys(teams).length > 0)
             logger?.info("sema_registry_teams", { teams: Object.keys(teams) });
+        // collab → named-workflow projection(切片 1.5,design/140 统一解;切片① 的
+        // TeamTemplate 投影已整体替换——纪律「别留双路径降级」)。可投影子集翻译成命名 workflow 注册条目
+        // (执行体=core 内置 team-discussion 脚本,center 模板=defaultArgs 合并链第二级;键=collab id,shell
+        // `/team`/LLM 经 Workflow({name}) 调用);子集外整条跳过+结构化上报,绝不静默降级。HOT:boot+refresh
+        // 双腿整表替换(非粘——center 停发即空表,内置 workflow 不受影响)。
         const projected = projectCollabToWorkflows(eff.collab?.templates);
         registerCollabWorkflows(projected.workflows);
         if (Object.keys(projected.workflows).length > 0)
@@ -165,6 +281,11 @@ export function applyEffective(config, eff, logger, opts = {}) {
         if (projected.notes.length > 0)
             logger?.info("sema_registry_collab_notes", { notes: projected.notes });
     }
+    // 142-S4 projects 域(registry-core 0.10.0):center 项目登记簿 → config.projects(键=
+    // projectId)。消费是 per-request 查表(memoryScope 派生 + defaultScopes 种子,security.ts/main.ts),
+    // 所以 boot+refresh 双腿都 mutateInPlace 热应用(整表替换,非粘——center 停发即清空);env lane 恒空。
+    // 宽读:域包裹 `{projects:{...}}`(registry-core ProjectsConfig 真形状)与裸 Record 都认(projectId=UUID,
+    // 永不撞 "projects" 字面键);防御:非 object 条目跳过,字段逐个验型(wire verbatim,不信任形状)。
     const projDomain = eff.projects;
     const rawProjects = (projDomain && typeof projDomain === "object" && !Array.isArray(projDomain)
         ? "projects" in projDomain && typeof projDomain.projects === "object"
@@ -174,7 +295,7 @@ export function applyEffective(config, eff, logger, opts = {}) {
     const projects = {};
     for (const [pid, reg] of Object.entries(rawProjects)) {
         if (!reg || typeof reg !== "object" || Array.isArray(reg))
-            continue;
+            continue; // defensive: non-object entry → skip
         const r = reg;
         projects[pid] = {
             ...(typeof r.displayName === "string" ? { displayName: r.displayName } : {}),
@@ -182,11 +303,36 @@ export function applyEffective(config, eff, logger, opts = {}) {
             ...(Array.isArray(r.defaultScopes) ? { defaultScopes: r.defaultScopes.filter((x) => typeof x === "string") } : {}),
         };
     }
-    mutateInPlace(config.projects, projects);
+    mutateInPlace(config.projects, projects); // IN PLACE: keep the ref per-request consumers captured at boot
     if (Object.keys(projects).length > 0)
         logger?.info("sema_registry_projects", { projects: Object.keys(projects) });
 }
+/**
+ * Apply the center `runtime` governance/limit gates OVER the env-derived config (mutates `config`).
+ *
+ * UNIFORM presence semantics across all 6 gates (center `f95438a` adopted this from our sentinel flag —
+ * SERVICE-INTEGRATION「Runtime 治理/限额闸」): all six fields are center `.optional()`, so
+ *   `undefined` = center isn't managing it → KEEP env;
+ *   present (any value, INCLUDING an explicit 0 / [] = "publish the gate OFF") → OVERRIDE env.
+ * (Earlier center had `rateLimitPerMin`/`approvalRequire` as `.default(0/[])`, which would have let a default
+ *  silently disable an env-set gate — we flagged it, center made all six optional, so a plain presence rule is
+ *  now both correct and uniform. No sentinel special-casing.)
+ *
+ * Only guard: `costQuotaWindowSec` must be `> 0` (a 0 window is nonsensical — core divides by it). Center's
+ * schema is `.positive()` so it can't send 0; this is belt-and-suspenders.
+ *
+ * Per-worker overrides ride the per-worker `/effective?worker=` response (center merges WorkerSpec.runtime over
+ * the fleet default server-side), so this single "effective beats env" rule already honors per-worker > fleet.
+ */
+/** The 6 runtime governance/limit gates, in ONE place (council DRY): the consume loop, the restart-to-apply
+ *  signal, and the dry-run diff all derive from this list, so adding a 7th gate is a single edit and can't
+ *  silently miss `runtimeHasActiveGate` (which would break the restart-to-apply warning). All six share keys
+ *  across `EffectiveConfig["runtime"]` and `ServiceConfig`. Exported (not in the original single-file form) so
+ *  the sibling restart-signal module can share the identical key list + presence rule. */
 export const RUNTIME_GATE_KEYS = ["rateLimitPerMin", "approvalRequire", "maxTaskCostUsd", "maxTaskTokens", "maxPrincipalCostUsd", "costQuotaWindowSec"];
+/** Uniform presence rule (center f95438a): a gate is "managed" when the field is present — any number (incl. 0),
+ *  or an array for approvalRequire. Sole guard: costQuotaWindowSec must be > 0 (a 0 window is nonsensical — core
+ *  divides by it; center's `.positive()` already enforces, belt-and-suspenders here). */
 export function runtimeGatePresent(rt, key) {
     const v = rt[key];
     if (key === "approvalRequire")
@@ -201,21 +347,42 @@ export function applyRuntimeGates(config, rt, logger) {
     const applied = {};
     for (const key of RUNTIME_GATE_KEYS) {
         if (!runtimeGatePresent(rt, key))
-            continue;
-        config[key] = rt[key];
+            continue; // undefined / sentinel → keep env
+        config[key] = rt[key]; // present (incl. explicit 0/[]) → override
         applied[key] = rt[key];
     }
     if (Object.keys(applied).length > 0)
         logger?.info("sema_registry_runtime", applied);
 }
+/**
+ * Apply the runtime governance "second baton" (center §10): `autonomy` + `commandPolicy`. UNLIKE the 6 gates in
+ * {@link applyRuntimeGates}, these are per-request HOT (read live in main.ts `resolveSpec` via
+ * `applyRuntimeGovernance`), so they apply on BOTH boot and refresh (NOT via RUNTIME_GATE_KEYS / restart-to-apply).
+ *
+ * 🔴 NON-STICKY (differs from the restart-to-apply gates on purpose — adversarial-review HIGH): a hot field that
+ * center STOPS publishing must REVERT to the env baseline, not keep the last center value. The restart-to-apply
+ * gates can be sticky because a refresh never touches them (the running middleware holds boot values until a
+ * restart re-reads env+center); a HOT field has no such reset, so "absent ⇒ keep" would silently freeze a stale
+ * center override (e.g. center published `auto`, then un-published it — the gate would stay OFF forever). So we
+ * recompute every call as `present ? center : envBaseline`. The env baseline = `AUTONOMY` (re-derived, env is
+ * immutable at runtime) for autonomy; `undefined` (no env scalar source) for commandPolicy.
+ *
+ * 🔴 commandPolicy is VALIDATED here (adversarial-review HIGH): an invalid command (glob/path/operator — which
+ * core's EXACT-name matcher would silently never match → a hole) is rejected FAIL-LOUD and the prior good policy
+ * is KEPT (a broken publish never half-applies a silently-weakened gate).
+ */
 export function applyRuntimeHot(config, rt, logger) {
     const applied = {};
+    // autonomy: present ⇒ center value; absent ⇒ revert to the env baseline (never a stale center override).
     const envAutonomy = parseAutonomy(process.env.AUTONOMY);
     const nextAutonomy = rt?.autonomy !== undefined ? rt.autonomy : envAutonomy;
     if (config.autonomy !== nextAutonomy) {
         config.autonomy = nextAutonomy;
         applied.autonomy = nextAutonomy ?? "(env-baseline)";
     }
+    // commandPolicy: present+valid ⇒ apply; present+invalid ⇒ fail-loud + keep prior; absent ⇒ revert to baseline
+    // (undefined — no env scalar source for structured command rules). Only re-set + log on an ACTUAL change
+    // (deep-equal compare) — refresh runs every ~60s and the policy is usually unchanged; logging every tick = noise.
     if (rt?.commandPolicy !== undefined) {
         const errors = validateCommandRules(rt.commandPolicy);
         if (errors.length > 0) {
@@ -223,17 +390,32 @@ export function applyRuntimeHot(config, rt, logger) {
         }
         else if (JSON.stringify(config.commandPolicy) !== JSON.stringify(rt.commandPolicy)) {
             config.commandPolicy = rt.commandPolicy;
-            applied.commandPolicy = rt.commandPolicy.length;
+            applied.commandPolicy = rt.commandPolicy.length; // log the COUNT, not the rules (avoid leaking on every refresh)
         }
     }
     else if (config.commandPolicy !== undefined) {
-        config.commandPolicy = undefined;
+        config.commandPolicy = undefined; // center stopped managing → revert to baseline (no env source)
         applied.commandPolicy = "(env-baseline)";
     }
     if (Object.keys(applied).length > 0)
         logger?.info("sema_registry_runtime_hot", applied);
 }
+/** [865]①/H3:activeTierGroup 档绑定当默认时的档梯,与 core 单一语义源逐字对齐(core roles.js:
+ *  `ROLE_TIER_DEFAULTS.default = "pro"` + `resolveTier` 从本档位置**只向低档**扫 DEFAULT_TIER_ORDER
+ *  [ultra,max,pro,flash,lite] ⇒ pro→flash→lite,绝不向上抓 max/ultra——引擎运行时对 "default" 角色就是
+ *  这么解析的,applyEffective 的 default 若用别的梯子会与真路由再度撕裂,codex H3)。 */
 const DEFAULT_ROLE_TIER_LADDER = ["pro", "flash", "lite"];
+/**
+ * [865]① 显式默认解析——applyEffective 与 dry-run(logEffectiveDiff.wouldDefaultModel)共用的单源。优先级
+ * (显式源指向不在目录/未启用的名 ⇒ onDangling 回调后落下一级,绝不静默指错模型):
+ *   1) eff.models.default 结构键 —— ✅ 既得路径([874] registry-core 0.10.11 落 `default?: string` schema
+ *      键+per-worker /effective 直通;本地 lane 由 config-provider mapToServiceEffective 直通)。写面悬空 ref
+ *      由 registry-core superRefine fail-loud;存量/未经 schema 路径仍走本函数的 warn 降级(双层姿势与
+ *      activeTierGroup 同构)。(1.200-1.202 期间此级恒空=当时如实的前行 seam,codex H2 注记已兑现。)
+ *   2) roles.default 的显式 {model} 绑定(现有 wire 真源)。
+ *   3) activeTierGroup 档绑定,按 {@link DEFAULT_ROLE_TIER_LADDER}(= core 对 "default" 角色的档语义)。
+ *   4) fallback(enabled[0]——原兜底,唯一不触发 onDangling 的落点)。
+ */
 export function resolveDefaultModelName(eff, has, fallback, onDangling) {
     const activeTiers = resolveActiveTiers(eff.models) ?? {};
     const structural = eff.models?.default;
@@ -252,6 +434,11 @@ export function resolveDefaultModelName(eff, has, fallback, onDangling) {
     }
     return { name: fallback, source: "enabled[0]" };
 }
+/**
+ * Read-only comparison (SEMA_REGISTRY_DRY_RUN): log what the center config WOULD change vs the current
+ * (env-derived) config, WITHOUT applying it. The safe-rollout step the sema-registry recommends — verify
+ * the center's models/roles/teams match (or intentionally differ from) the env baseline before going live.
+ */
 export function logEffectiveDiff(config, eff, logger) {
     const enabled = (eff.models?.models ?? []).filter((m) => m.enabled !== false);
     const centerModels = enabled.map((m) => ({ name: m.name, id: m.id, provider: m.provider, apiKeyEnv: m.apiKeyEnv ?? null, tier: m.tier ?? null }));
@@ -261,7 +448,9 @@ export function logEffectiveDiff(config, eff, logger) {
     logger?.warn("sema_registry_dry_run", {
         note: "DRY RUN — registry config NOT applied; unset SEMA_REGISTRY_DRY_RUN to go live",
         version: eff.version,
-        wouldOverrideModels: enabled.length > 0,
+        wouldOverrideModels: enabled.length > 0, // empty/unpublished center → env baseline kept (no override)
+        // [865]①/codex M2:与 applyEffective 同一只解析器——dry-run 的上线前核验必须报真 apply 会选的默认,
+        // 报 enabled[0] 会让核验对显式默认(roles.default/tier 档)配置给出错误结论。
         wouldDefaultModel: enabled.length > 0 ? resolveDefaultModelName(eff, (n) => enabled.some((m) => m.name === n), enabled[0].name).name : null,
         currentDefaultModel: config.model.id,
         models: { center: centerModels, envDerived: envModels },
@@ -270,11 +459,14 @@ export function logEffectiveDiff(config, eff, logger) {
         skills: { centerWouldLoad: (eff.skills?.skills ?? []).filter((s) => s.enabled !== false).map((s) => s.name) },
         mcp: { centerWouldRegister: (eff.mcp?.servers ?? []).filter((s) => s.enabled !== false).map((s) => s.name) },
         runtime: {
+            // What the gates would become if applied (present center value overrides; absent → kept env shown as current).
             center: eff.runtime ?? null,
             current: Object.fromEntries(RUNTIME_GATE_KEYS.map((k) => [k, config[k]])),
         },
     });
 }
+/** True if the center `runtime` carries any managed gate (a PRESENT field) — i.e. a refresh that changed it
+ *  needs a restart to take effect (restart-to-apply). Same key list + presence rule as applyRuntimeGates. */
 export function runtimeHasActiveGate(rt) {
     if (!rt)
         return false;

package/dist/config-center/http-client.d.ts

@@ -1,10 +1,30 @@
 import type { EntitlementRuntimeCaps } from "@sema-agent/registry-core";
 import type { ScenarioRuling } from "../capabilities/scenarios.js";
 import type { EffectiveConfig, ExecutionRuling } from "./types.js";
+/** GET the effective config (Bearer + ETag). null = 304 (unchanged). Throws on transport/HTTP error. */
 export declare function fetchEffective(baseUrl: string, token: string, etag: string | undefined, fetchImpl?: typeof fetch, worker?: string): Promise<{
     effective: EffectiveConfig;
     etag?: string;
 } | null>;
+/**
+ * design/99 §K (core 1.157 `RunnerDeps.runtimeCapsResolver`) — GET the PER-PRINCIPAL runtime
+ * ENTITLEMENTS the engine enforces server-side, from center's `GET /api/config/effective?principal=&worker=`.
+ * Center pre-resolves the tighten-only intersection (fleet defaults ∩ tier ⊕ roles + overrides) and returns a
+ * `runtimeCaps` block — the service passes it through verbatim (no further tightening, per center's ruling).
+ *
+ * 🔐 TOKEN/WORKER (center ruling, sema-registry `aeb4979`): two valid postures —
+ *   • FULL `SERVICE_PULL_TOKEN` + `?principal=` → full per-user body (caps + per-user config).
+ *   • worker-scoped `wpt_<self>` + `?principal=&worker=<self>` → **caps-only** body (`{principal, configured,
+ *     runtimeCaps, budget}`; never other tenants' config) — a worker MAY resolve its OWN worker's principals.
+ *   A `wpt_` with NO `?worker=` (or a mismatched worker) still 403s. So we ALWAYS pass `?worker=` when the
+ *   deployment has one (`SEMA_REGISTRY_WORKER`): it authorizes the wpt_ path AND is harmless on the full token
+ *   (the caps value is worker-independent — `resolveEntitlement` resolves from the principal alone; worker only
+ *   scopes the config view we ignore). This re-adds the `worker` arg dropped in 1.14.0 (L2-3) — center's ruling
+ *   makes it load-bearing for AUTHORIZATION, not for the caps value.
+ * `null` = 304 (caller keeps its cached value). THROWS on transport / non-304 HTTP error → the resolver
+ * fail-closes (core then DENIES the optional `allowWorkflows` cap — an outage must never silently GRANT). ETag is
+ * content-hashed (`p-<hash>`); an `if-none-match` poll is cheap. Mirrors `fetchEffective` (Bearer + 8s + scheme guard).
+ */
 export declare function fetchPrincipalCaps(baseUrl: string, token: string, principal: string, etag: string | undefined, fetchImpl?: typeof fetch, worker?: string): Promise<{
     runtimeCaps: EntitlementRuntimeCaps | null;
     configured: boolean;
@@ -13,11 +33,25 @@ export declare function fetchPrincipalCaps(baseUrl: string, token: string, princ
     executionDrift?: string;
     etag?: string;
 } | null>;
+/** An HTTP error from a sema-registry fetch that carries the response status so callers can branch on it
+ *  (e.g. translate a 404 to "unknown hash → undefined") WITHOUT parsing the message string. */
 export declare class ConfigCenterHttpError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
+/**
+ * Fetch one skill's body by content hash (`GET /api/config/skills/content/<hash>`, Bearer) and VERIFY its
+ * sha256 matches the manifest hash (integrity + tamper check). The content is immutable per hash, so the
+ * caller caches by hash and never re-fetches an unchanged skill. Throws a {@link ConfigCenterHttpError}
+ * (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".
+ */
 export declare function fetchSkillContent(baseUrl: string, token: string, contentHash: string, fetchImpl?: typeof fetch): Promise<string>;
+/** [985]b / [1285]① — §9.4 by-digest 补拉二函(fetchSkillContent 同姿势:HTTP+Bearer+8s 超时+
+ *  消费侧自证)。artifact=envelope JSON(验真=调用方过 core verifyPromptArtifact,canonical 重算——
+ *  本函数只做传输与形读,不越权解释);blob=段文本 raw-byte(sha256 逐位自证,fetchSkillContent 同款)。
+ *  digest 参数收带前缀/裸 hex 两形([1285] 参数口径)。 */
 export declare function fetchPromptArtifact(baseUrl: string, token: string, artifactDigest: string, fetchImpl?: typeof fetch): Promise<unknown>;
 export declare function fetchPromptBlob(baseUrl: string, token: string, contentDigest: string, fetchImpl?: typeof fetch): Promise<string>;
 //# sourceMappingURL=http-client.d.ts.map

package/dist/config-center/http-client.js

@@ -1,8 +1,19 @@
+/**
+ * sema-registry HTTP client — the transport calls the service makes against the config-center
+ * (`fetchEffective`/`fetchPrincipalCaps`/`fetchSkillContent`/`fetchPromptArtifact`/`fetchPromptBlob`) plus
+ * the shared HTTP-error type. Split out of `sema-registry.ts` (design/158 A13, internal-lossless — the
+ * facade re-exports every symbol below unchanged).
+ */
 import { createHash } from "node:crypto";
+/** GET the effective config (Bearer + ETag). null = 304 (unchanged). Throws on transport/HTTP error. */
 export async function fetchEffective(baseUrl, token, etag, fetchImpl = fetch, worker) {
+    // Defensive scheme guard: Node's fetch supports file:// — a mis-set
+    // SEMA_REGISTRY_URL must not turn into a local-file read. Reject anything but http(s).
     const scheme = new URL(baseUrl).protocol;
     if (scheme !== "http:" && scheme !== "https:")
         throw new Error(`SEMA_REGISTRY_URL must be http(s), got "${scheme}"`);
+    // worker-scoped pull: `?worker=<name>` returns that worker's roster; omitted → the global roster
+    // (backward compatible — the center returns today's global config when no worker is given).
     const url = `${baseUrl.replace(/\/+$/, "")}/api/config/effective${worker ? `?worker=${encodeURIComponent(worker)}` : ""}`;
     const res = await fetchImpl(url, {
         headers: { authorization: `Bearer ${token}`, ...(etag ? { "if-none-match": etag } : {}) },
@@ -14,10 +25,30 @@ export async function fetchEffective(baseUrl, token, etag, fetchImpl = fetch, wo
         throw new Error(`sema-registry HTTP ${res.status}`);
     return { effective: (await res.json()), etag: res.headers.get("etag") ?? undefined };
 }
+/**
+ * design/99 §K (core 1.157 `RunnerDeps.runtimeCapsResolver`) — GET the PER-PRINCIPAL runtime
+ * ENTITLEMENTS the engine enforces server-side, from center's `GET /api/config/effective?principal=&worker=`.
+ * Center pre-resolves the tighten-only intersection (fleet defaults ∩ tier ⊕ roles + overrides) and returns a
+ * `runtimeCaps` block — the service passes it through verbatim (no further tightening, per center's ruling).
+ *
+ * 🔐 TOKEN/WORKER (center ruling, sema-registry `aeb4979`): two valid postures —
+ *   • FULL `SERVICE_PULL_TOKEN` + `?principal=` → full per-user body (caps + per-user config).
+ *   • worker-scoped `wpt_<self>` + `?principal=&worker=<self>` → **caps-only** body (`{principal, configured,
+ *     runtimeCaps, budget}`; never other tenants' config) — a worker MAY resolve its OWN worker's principals.
+ *   A `wpt_` with NO `?worker=` (or a mismatched worker) still 403s. So we ALWAYS pass `?worker=` when the
+ *   deployment has one (`SEMA_REGISTRY_WORKER`): it authorizes the wpt_ path AND is harmless on the full token
+ *   (the caps value is worker-independent — `resolveEntitlement` resolves from the principal alone; worker only
+ *   scopes the config view we ignore). This re-adds the `worker` arg dropped in 1.14.0 (L2-3) — center's ruling
+ *   makes it load-bearing for AUTHORIZATION, not for the caps value.
+ * `null` = 304 (caller keeps its cached value). THROWS on transport / non-304 HTTP error → the resolver
+ * fail-closes (core then DENIES the optional `allowWorkflows` cap — an outage must never silently GRANT). ETag is
+ * content-hashed (`p-<hash>`); an `if-none-match` poll is cheap. Mirrors `fetchEffective` (Bearer + 8s + scheme guard).
+ */
 export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchImpl = fetch, worker) {
     const scheme = new URL(baseUrl).protocol;
     if (scheme !== "http:" && scheme !== "https:")
         throw new Error(`SEMA_REGISTRY_URL must be http(s), got "${scheme}"`);
+    // `?principal=<id>[&worker=<self>]` — worker authorizes the wpt_<self> caps-only path; harmless on a full token.
     const params = new URLSearchParams({ principal });
     if (worker)
         params.set("worker", worker);
@@ -27,6 +58,9 @@ export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchI
         signal: AbortSignal.timeout(8000),
     });
     if (res.status === 304) {
+        // A 304 is only valid as a reply to OUR conditional. If we sent no etag and still got 304, center is
+        // misbehaving — DON'T treat it as "unchanged" (that surfaces undefined caps = no restriction = fail OPEN).
+        // Throw so the resolver fail-closes (review B). With an etag, 304 = genuine "unchanged" → null.
         if (!etag)
             throw new Error("sema-registry returned 304 to a non-conditional principal-caps request");
         return null;
@@ -37,6 +71,10 @@ export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchI
     return {
         runtimeCaps: body.runtimeCaps ?? null,
         configured: Boolean(body.configured),
+        // The caps view carries the RESOLVED per-principal scenario ruling (two keys, shape pinned
+        // by center tests). An older center has NO such keys → undefined (no governance, legacy passthrough) —
+        // distinct from the "assigned nothing" ruling {scenario:null, allowlist:[]} a newer center returns.
+        // Defensive on shape (scenario face is fail-open — see gateScenarioRequest): non-string entries dropped.
         ...("scenario" in body || "allowlist" in body
             ? {
                 scenario: {
@@ -45,6 +83,15 @@ export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchI
                 },
             }
             : {}),
+        // (stage7 P5, registry-core 0.8 execution 域): the caps view's per-principal execution
+        // ruling `{required, allowedLanes}` — same car, same no-cache semantics as the scenario ruling. An
+        // older center has no key → undefined (no enforcement). allowedLanes is an OPEN value domain
+        // (adding a lane is never BREAKING) — tolerate unknown names, drop non-string ELEMENTS defensively.
+        // shape DRIFT (required non-boolean / allowedLanes non-array) must NOT be
+        // coerced — the old coercion turned "allowedLanes came as a comma string" + required=true into
+        // allowedLanes=[] = fleet-wide deny-all (fail-CLOSED on a wire glitch, opposite of the fail-open posture)
+        // and a drifted `required` into silent non-enforcement. Now: drift ⇒ DROP the whole ruling (fail-open,
+        // gate passes) + `executionDrift` so the caller's audit line fires (the resolver routes it to onError).
         ...((() => {
             const ex = body.execution;
             if (ex === undefined || ex === null)
@@ -54,6 +101,10 @@ export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchI
             if (!Array.isArray(ex.allowedLanes))
                 return { executionDrift: `execution.allowedLanes is ${typeof ex.allowedLanes}, expected string[] — ruling dropped (fail-open)` };
             const execution = { required: ex.required, allowedLanes: ex.allowedLanes.filter((s) => typeof s === "string") };
+            // registry-core 0.10.1-0.10.2:execution.sessionMirror 宽读。observation-only 子面
+            // (server 非执法端,见 ExecutionRuling.sessionMirror 注),所以形状漂移只丢**本子面**并走 executionDrift
+            // 审计线(resolver 路由到 onError),**绝不**连带丢 lane ruling(那是真执法面,不能被观测子面拖垮)。
+            // required 缺省 false = registry-core zod 默认(便利态);engineUrl 必须非空 string。
             if (ex.sessionMirror !== undefined && ex.sessionMirror !== null) {
                 const sm = ex.sessionMirror;
                 const smOk = typeof sm === "object" && typeof sm.engineUrl === "string" && sm.engineUrl.length > 0 && (sm.required === undefined || typeof sm.required === "boolean");
@@ -67,6 +118,8 @@ export async function fetchPrincipalCaps(baseUrl, token, principal, etag, fetchI
         etag: res.headers.get("etag") ?? undefined,
     };
 }
+/** An HTTP error from a sema-registry fetch that carries the response status so callers can branch on it
+ *  (e.g. translate a 404 to "unknown hash → undefined") WITHOUT parsing the message string. */
 export class ConfigCenterHttpError extends Error {
     status;
     constructor(message, status) {
@@ -75,6 +128,14 @@ export class ConfigCenterHttpError extends Error {
         this.name = "ConfigCenterHttpError";
     }
 }
+/**
+ * Fetch one skill's body by content hash (`GET /api/config/skills/content/<hash>`, Bearer) and VERIFY its
+ * sha256 matches the manifest hash (integrity + tamper check). The content is immutable per hash, so the
+ * caller caches by hash and never re-fetches an unchanged skill. Throws a {@link ConfigCenterHttpError}
+ * (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".
+ */
 export async function fetchSkillContent(baseUrl, token, contentHash, fetchImpl = fetch) {
     const url = `${baseUrl.replace(/\/+$/, "")}/api/config/skills/content/${encodeURIComponent(contentHash)}`;
     const res = await fetchImpl(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(8000) });
@@ -87,6 +148,10 @@ export async function fetchSkillContent(baseUrl, token, contentHash, fetchImpl =
         throw new Error(`skill content hash mismatch for ${contentHash}: computed sha256:${got}`);
     return content;
 }
+/** [985]b / [1285]① — §9.4 by-digest 补拉二函(fetchSkillContent 同姿势:HTTP+Bearer+8s 超时+
+ *  消费侧自证)。artifact=envelope JSON(验真=调用方过 core verifyPromptArtifact,canonical 重算——
+ *  本函数只做传输与形读,不越权解释);blob=段文本 raw-byte(sha256 逐位自证,fetchSkillContent 同款)。
+ *  digest 参数收带前缀/裸 hex 两形([1285] 参数口径)。 */
 export async function fetchPromptArtifact(baseUrl, token, artifactDigest, fetchImpl = fetch) {
     const url = `${baseUrl.replace(/\/+$/, "")}/api/config/prompts/epoch-artifacts/${encodeURIComponent(artifactDigest)}`;
     const res = await fetchImpl(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(8000) });
@@ -99,6 +164,9 @@ export async function fetchPromptBlob(baseUrl, token, contentDigest, fetchImpl =
     const res = await fetchImpl(url, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(8000) });
     if (!res.ok)
         throw new ConfigCenterHttpError(`prompt blob HTTP ${res.status} for ${contentDigest}`, res.status);
+    // codex F2(补拉批):哈希必须打在**响应原始字节**上(res.text() 的 UTF-8 宽容解码会剥 BOM/替换坏序列
+    // ——验的就不再是送来的字节,content-addressed 完整性破功);验过再严格解码(fatal:true,坏 UTF-8
+    // 掷错而非静默替换)。
     const bytes = new Uint8Array(await res.arrayBuffer());
     const want = contentDigest.replace(/^sha256:/, "").toLowerCase();
     const got = createHash("sha256").update(bytes).digest("hex");