@sema-agent/server 1.323.0 → 2.0.0

package/dist/config-provider.d.ts

@@ -1,6 +1,12 @@
 import { FileConfigStore } from "@sema-agent/registry-core/node";
 import { type EffectiveConfig as AgentConfigEffective } from "@sema-agent/registry-core";
 import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, type EffectiveConfig } from "./sema-registry.js";
+/** Result of a `fetchEffective` — EXACTLY sema-registry's return: the effective config + its etag, or
+ *  `null` for "unchanged" (remote 304; local: the version matched the caller's prior etag).
+ *  `domainErrors`([898] registry-core 0.10.12 tolerant seam,local lane only):catalog 域坏文件不再
+ *  连坐全包回落 env——坏域按该域 schema default 落+错误单列,好域照常生效;caller(main.ts)对每条打
+ *  per-domain warn 点名坏域。gate 域(governance/rosters/…)坏文件 tolerant 仍 throw(READ 容错不放宽
+ *  gate fail-loud,registry-core 半场精化)——那条路走既有的整包 catch。 */
 export type FetchEffectiveResult = {
     effective: EffectiveConfig;
     etag?: string;
@@ -9,23 +15,67 @@ export type FetchEffectiveResult = {
         error: string;
     }>;
 } | null;
+/** Sentinel returned by {@link raceBootFetch} when the boot pull outlived its budget — the caller
+ *  starts serving on the env fallback and the SAME promise settles in the background (never cancelled). */
 export declare const BOOT_FETCH_DEFERRED: unique symbol;
+/**
+ * Race the boot config pull against a wall-clock budget (clay 2026-07-17: a black-holed center made
+ * the SYNCHRONOUS boot pull hang ~5.7s on the TOC lane — the "local server takes 5s to start" report).
+ * Inside the budget → the fetch result verbatim (the healthy-center fast path is unchanged, typically
+ * <300ms). Past it → {@link BOOT_FETCH_DEFERRED}; the fetch is NOT aborted — the caller chains a
+ * background continuation that triggers a refresh tick when it finally settles. The timer is unref'd
+ * (never holds the loop) and cleared as soon as the fetch wins.
+ */
 export declare function raceBootFetch<T>(fetch: Promise<T>, budgetMs: number): Promise<T | typeof BOOT_FETCH_DEFERRED>;
+/**
+ * The two transport calls the service makes to obtain config, behind a backend-selectable seam. Both
+ * signatures and return shapes match `sema-registry.fetchEffective` / `sema-registry.fetchSkillContent`
+ * EXACTLY so that, ONCE WIRED, the caller (main.ts) could swap remote↔local without touching applyEffective
+ * et al. (main.ts does not swap on this seam yet — see the NOT-YET-WIRED note at the top of this module).
+ */
 export interface ConfigProvider {
+    /** "remote" = sema-registry HTTP; "local" = on-disk FileConfigStore. */
     readonly kind: "remote" | "local";
+    /**
+     * Pull the effective config. `etag` is the caller's last-seen version token (`if-none-match` on remote;
+     * the stable version string on local). Returns `null` when unchanged, else the config + a fresh etag.
+     * Throws on a transport/read error (caller keeps env fallback).
+     */
     fetchEffective(etag: string | undefined): Promise<FetchEffectiveResult>;
+    /**
+     * Fetch one skill body by content hash (`sha256:<hex>`). Remote: GET the content endpoint + verify the
+     * hash. Local: content-addressed lookup over the local skills domain. Returns `undefined` when the hash
+     * is unknown (remote 404 / local miss) so the caller keeps its baseline; throws only on a hard error
+     * (remote non-404 HTTP / hash mismatch).
+     */
     fetchSkillContent(contentHash: string): Promise<string | undefined>;
 }
+/** The config-provider knobs read off ServiceConfig (a structural subset — avoids importing the whole
+ *  ServiceConfig type and keeps this module testable with a plain object). */
 export interface ConfigProviderInput {
+    /** Set when SEMA_REGISTRY_URL (legacy CONFIG_CENTER_URL) is configured (config.ts `configCenter`). `dryRun` is carried through so a
+     *  remote↔local swap via this seam does NOT drop the dry-run posture main.ts branches on (config.ts
+     *  `configCenter.dryRun`); the provider itself does not consume it (the caller still branches on it). */
     configCenter?: {
         baseUrl: string;
         token: string;
         worker?: string;
         dryRun?: boolean;
     };
+    /** `CONFIG_PROVIDER` env — a CLOSED enum `local` | `remote` | undefined. `local` forces the local
+     *  backend; `remote` selects the center (falls through to local if no URL); any OTHER value is treated as
+     *  a misconfiguration and defaults to local (safe, non-network) with a warn. Normalize/trim the raw env
+     *  string at parse time in config.ts when this knob is actually wired. */
     provider?: string;
+    /** `CONFIG_LOCAL_DIR` env — root holding `config.d/<domain>.json` for the local backend. Defaults to
+     *  `./config.d`'s parent convention (the FileConfigStore takes the ROOT, and reads `<root>/config.d`). */
     localDir?: string;
 }
+/**
+ * RemoteConfigProvider — DELEGATES to the exported sema-registry HTTP functions. No HTTP is reimplemented;
+ * baseUrl/token/worker are bound once and passed through. The two delegate fns are injectable (defaulting
+ * to the real sema-registry exports) so a unit test can assert delegation without module-mocking.
+ */
 export declare class RemoteConfigProvider implements ConfigProvider {
     private readonly cc;
     private readonly deps;
@@ -41,14 +91,42 @@ export declare class RemoteConfigProvider implements ConfigProvider {
     fetchEffective(etag: string | undefined): Promise<FetchEffectiveResult>;
     fetchSkillContent(contentHash: string): Promise<string | undefined>;
 }
+/**
+ * LocalConfigProvider — reads the SAME config contract from disk via `FileConfigStore`. `getEffective()`
+ * returns the registry `EffectiveConfig` (all domains, defaults filled); `getVersion()` returns a
+ * stable change-detector. We map that down to the service-local `EffectiveConfig` shape and surface the
+ * version as the etag (so the caller's "skip re-apply if etag unchanged" works locally too).
+ */
 export declare class LocalConfigProvider implements ConfigProvider {
     readonly kind: "local";
     private readonly store;
+    /** [875]b 可观测性:config_loaded 日志要能回答「到底读的哪个目录」——复验实录:只设 LOCAL_DATA_ROOT 时
+     *  config.d 静默读不到且 0 模型无告警(CONFIG_LOCAL_DIR 才是本 lane 的选目录旋钮)。 */
     readonly root: string;
     constructor(root: string, store?: FileConfigStore);
     fetchEffective(etag: string | undefined): Promise<FetchEffectiveResult>;
     fetchSkillContent(contentHash: string): Promise<string | undefined>;
 }
+/**
+ * Map the registry `EffectiveConfig` (superset, all domains) → the service-local `EffectiveConfig`
+ * the consumers (`applyEffective`, `resolveMcpServers`, …) expect. The two are structurally compatible
+ * for every field the consumers read; this projection makes that explicit (and drops control-plane-only
+ * domains the service never consumes: rosters, systems, workers, hosts, integrations, access).
+ *
+ * Skills are mapped to the MANIFEST shape (name/description/scenarios/contentHash/enabled) — the same
+ * shape RemoteConfigProvider's `/effective` ships — so the lazy `fetchSkillContent`-by-hash path is
+ * identical in both modes. The local content hash is the `contentHash` the store already computed.
+ */
 export declare function mapToServiceEffective(eff: AgentConfigEffective, version: number): EffectiveConfig;
+/**
+ * Pick the backend off a CLOSED `provider` enum (`local` | `remote` | undefined): LOCAL when
+ * `CONFIG_PROVIDER=local`, OR when no sema-registry URL is configured (a lone box with config.d/ on disk
+ * and no control plane). REMOTE otherwise (a configured center URL, the default fleet posture). A
+ * `CONFIG_PROVIDER=remote` with no URL is a misconfiguration — we fall through to local rather than
+ * constructing a remote provider with no endpoint (the caller would have skipped the remote pull entirely
+ * under the old code path; local-with-empty-config.d degrades to env the same way). An UNRECOGNIZED value
+ * (typo / wrong case) is NOT treated as remote: it defaults to local (non-network) with a warn, so a
+ * fat-fingered knob can never silently source config from an unintended/stale network endpoint.
+ */
 export declare function createConfigProvider(input: ConfigProviderInput): ConfigProvider;
 //# sourceMappingURL=config-provider.d.ts.map

package/dist/config-provider.js

@@ -1,3 +1,40 @@
+/**
+ * ConfigProvider — the dual-mode seam over WHERE the effective config comes from (see
+ * sema-registry docs/DUAL-MODE-DESIGN.md §4).
+ *
+ * The service consumes sema-registry through EXACTLY two transport calls — `fetchEffective` (pull the
+ * effective config, ETag-conditional) and `fetchSkillContent` (lazy-pull one skill body by content hash).
+ * Everything downstream (applyEffective / applyRuntimeGates / resolveMcpServers / mcpForScenario / the
+ * skill overlay) is transport-agnostic: it operates on the returned `EffectiveConfig` / skill string.
+ *
+ * STATUS — FULLY provider-routed (提示词装配协议 §9.5-1/-3): boot AND the 60s refresh loop both pull
+ * through `configProvider.fetchEffective` (main.ts), so `CONFIG_PROVIDER=local` gets the same ongoing
+ * poll as the fleet path — a config.d edit lands within one poll (the local etag is the store's raws
+ * hash). The caller runs a whole-candidate gate over `domainErrors` (§9.5-5): on refresh an invalid
+ * domain rejects the candidate and the last-known-good keeps serving; boot stays tolerant per-domain
+ * (no LKG exists yet).
+ *
+ * This module factors those two calls behind a `ConfigProvider` interface with two backends:
+ *
+ *   - {@link RemoteConfigProvider} — the existing behaviour. DELEGATES verbatim to the exported
+ *     `sema-registry.fetchEffective` / `sema-registry.fetchSkillContent` (HTTP + Bearer + ETag + hash
+ *     verify). No HTTP is reimplemented here; this is a thin wrapper that binds baseUrl/token/worker.
+ *
+ *   - {@link LocalConfigProvider} — reads the SAME config contract from the local filesystem via
+ *     `@sema-agent/registry-core/node` `FileConfigStore` (`.env` + `config.d/<domain>.json` → an
+ *     `EffectiveConfig` through the SAME resolver the center uses). The registry `EffectiveConfig`
+ *     is a structural SUPERSET of the service-local `EffectiveConfig` the consumers expect, so we map
+ *     it down to EXACTLY that shape (see `mapToServiceEffective`). Skills are stored locally WITH their
+ *     bodies (the local store doesn't split content into a manifest), so `fetchSkillContent` is a
+ *     content-addressed lookup over the local skills domain (absent → undefined, mirroring a remote 404).
+ *
+ * SECRET BOUNDARY (unchanged in both modes): the config plane carries only env-NAME refs — `apiKeyEnv`,
+ * `envRefs`/`headerRefs`, `tokenEnv`. The real secret VALUE is never stored in config.d/<domain>.json and
+ * never read by this module; it is resolved from `process.env` downstream (sema-registry.ts
+ * `applyEffective`/`resolveMcpServers`). The local store is symmetric with the remote center on this: it
+ * ships NAMEs only. (Unit test asserts the local path resolves env-NAME→value via process.env and never
+ * persists a value.)
+ */
 import { createHmac, randomBytes } from "node:crypto";
 import { FileConfigStore } from "@sema-agent/registry-core/node";
 import { findSkillContent, skillContentHash, refIntegrityIssues, siblingResolver, } from "@sema-agent/registry-core";
@@ -5,14 +42,35 @@ import { redactSecrets } from "./trace/redact.js";
 import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, ConfigCenterHttpError, } from "./sema-registry.js";
 import { createLogger } from "./observability/logger.js";
 const logger = createLogger();
+/**
+ * domainError strings must not echo raw config operands (self-review, information-surface lens):
+ * ref-integrity messages quote the referenced value verbatim, and tolerant-read parse failures carry
+ * zod/JSON.parse fragments of the file text — a controlled value pasted into the wrong slot (say, a
+ * credential in a model-ref position) would otherwise ride `config_candidate_rejected` /
+ * `config_domain_invalid` into the structured log stream. This runs at the producing boundary (the
+ * local provider is the only domainErrors producer): shared secret-shape redaction first, then every
+ * quoted operand becomes a short one-way fingerprint — keyed per process so the fingerprint is not a
+ * dictionary-comparable digest of the value, while equal operands still correlate within one log
+ * stream. The issue `path` stays clear; it is how the operator locates the entry.
+ */
 const OPERAND_FINGERPRINT_KEY = randomBytes(16);
 function redactConfigError(text) {
     return redactSecrets(text).replace(/"[^"]*"|'[^']*'/g, (m) => `"#${createHmac("sha256", OPERAND_FINGERPRINT_KEY).update(m.slice(1, -1)).digest("hex").slice(0, 8)}"`);
 }
+/** Sentinel returned by {@link raceBootFetch} when the boot pull outlived its budget — the caller
+ *  starts serving on the env fallback and the SAME promise settles in the background (never cancelled). */
 export const BOOT_FETCH_DEFERRED = Symbol("boot-fetch-deferred");
+/**
+ * Race the boot config pull against a wall-clock budget (clay 2026-07-17: a black-holed center made
+ * the SYNCHRONOUS boot pull hang ~5.7s on the TOC lane — the "local server takes 5s to start" report).
+ * Inside the budget → the fetch result verbatim (the healthy-center fast path is unchanged, typically
+ * <300ms). Past it → {@link BOOT_FETCH_DEFERRED}; the fetch is NOT aborted — the caller chains a
+ * background continuation that triggers a refresh tick when it finally settles. The timer is unref'd
+ * (never holds the loop) and cleared as soon as the fetch wins.
+ */
 export function raceBootFetch(fetch, budgetMs) {
     if (budgetMs <= 0)
-        return Promise.resolve(BOOT_FETCH_DEFERRED);
+        return Promise.resolve(BOOT_FETCH_DEFERRED); // explicit "never block boot" posture
     let timer;
     const budget = new Promise((res) => {
         timer = setTimeout(() => res(BOOT_FETCH_DEFERRED), budgetMs);
@@ -20,6 +78,11 @@ export function raceBootFetch(fetch, budgetMs) {
     });
     return Promise.race([fetch.finally(() => clearTimeout(timer)), budget]);
 }
+/**
+ * RemoteConfigProvider — DELEGATES to the exported sema-registry HTTP functions. No HTTP is reimplemented;
+ * baseUrl/token/worker are bound once and passed through. The two delegate fns are injectable (defaulting
+ * to the real sema-registry exports) so a unit test can assert delegation without module-mocking.
+ */
 export class RemoteConfigProvider {
     cc;
     deps;
@@ -30,10 +93,16 @@ export class RemoteConfigProvider {
     }
     fetchEffective(etag) {
         const fn = this.deps.fetchEffective ?? remoteFetchEffective;
+        // 5th arg = worker scope; transport (fetchImpl) stays sema-registry's default.
         return fn(this.cc.baseUrl, this.cc.token, etag, undefined, this.cc.worker);
     }
     async fetchSkillContent(contentHash) {
         const fn = this.deps.fetchSkillContent ?? remoteFetchSkillContent;
+        // Honor the ConfigProvider contract symmetrically with the local backend: an UNKNOWN hash → undefined
+        // (caller keeps its baseline), and ONLY a hard error (non-404 HTTP / hash mismatch) throws. The remote
+        // transport throws a ConfigCenterHttpError(status=404) for an unknown hash; we translate that single
+        // case to undefined and re-throw everything else, so both backends return the same thing for the same
+        // "unknown hash" input (substitutability — the whole point of this seam).
         try {
             return await fn(this.cc.baseUrl, this.cc.token, contentHash);
         }
@@ -44,23 +113,48 @@ export class RemoteConfigProvider {
         }
     }
 }
+/**
+ * LocalConfigProvider — reads the SAME config contract from disk via `FileConfigStore`. `getEffective()`
+ * returns the registry `EffectiveConfig` (all domains, defaults filled); `getVersion()` returns a
+ * stable change-detector. We map that down to the service-local `EffectiveConfig` shape and surface the
+ * version as the etag (so the caller's "skip re-apply if etag unchanged" works locally too).
+ */
 export class LocalConfigProvider {
     kind = "local";
     store;
+    /** [875]b 可观测性:config_loaded 日志要能回答「到底读的哪个目录」——复验实录:只设 LOCAL_DATA_ROOT 时
+     *  config.d 静默读不到且 0 模型无告警(CONFIG_LOCAL_DIR 才是本 lane 的选目录旋钮)。 */
     root;
     constructor(root, store) {
         this.root = root;
         this.store = store ?? new FileConfigStore(root);
     }
     async fetchEffective(etag) {
+        // SINGLE store read: derive BOTH the etag AND the mapped payload from ONE atomic raws snapshot. Reading
+        // getVersion() and getEffective() separately would pair an etag from snapshot A with a payload from
+        // snapshot B if config.d is rewritten between the two awaits — a consumer could then cache etag=A bound
+        // to payload-B and, once files settle back to A, skip re-applying the now-correct config (304-skip
+        // staleness). `eff.version` IS the authoritative version of THIS payload (file-store getEffective()
+        // invariant), so it is the only correct source for the etag. Cost: we compute `eff` even on an
+        // unchanged poll, but that preserves snapshot consistency — see finding #3.
+        // [898] tolerant read(0.10.12):catalog 域坏文件 ⇒ 该域 default+domainErrors 单列(不再连坐整包回落
+        // env);gate 域坏文件仍 throw(走 caller 的整包 catch)。坏文件文本 hash 参与 version(坏≠absent、
+        // 坏→修好均 bump),304-skip 纪律不漏拍——所以坏域场景下 etag 对比照旧安全。
         const { effective: eff, domainErrors } = await this.store.getEffective({ tolerant: true });
         const tag = String(eff.version);
         if (etag !== undefined && etag === tag)
-            return null;
+            return null; // unchanged → mirror remote 304
+        // 提示词装配协议 §9.5-4 read-side cross-domain reference validation: dangling refs (a roster naming a
+        // model that isn't in the catalog, …) fold into domainErrors, so the caller's candidate gate rejects
+        // the tree whole on refresh (boot warns and proceeds — no LKG exists yet). Write-side zod is
+        // per-domain only and the center runs this check on its write path; the local lane never had it.
+        // The resolver gets THIS snapshot's domain values as `pending` (builder output is default-filled for
+        // every domain), so the check never re-reads config.d — the one-atomic-snapshot invariant above holds.
         const refErrors = [];
         const resolve = siblingResolver(this.store, eff);
         for (const d of ["rosters", "workers", "models", "collab", "systems", "entitlement"]) {
             const issues = await refIntegrityIssues(d, eff[d], resolve);
+            // path CLEAR (locates the entry) + message operand-fingerprinted (see redactConfigError).
             if (issues.length > 0)
                 refErrors.push({ domain: d, error: issues.map((i) => `${i.path.join(".")}: ${redactConfigError(i.message)}`).join("; ") });
         }
@@ -68,12 +162,24 @@ export class LocalConfigProvider {
         return { effective: mapToServiceEffective(eff, eff.version), etag: tag, ...(errors.length > 0 ? { domainErrors: errors } : {}) };
     }
     async fetchSkillContent(contentHash) {
+        // The local store keeps skill BODIES inline (no manifest split), so this is a content-addressed lookup
+        // over the skills domain. Absent hash → undefined (mirrors a remote 404 → caller keeps the baseline).
         const skills = await this.store.getDomain("skills");
         if (!skills)
             return undefined;
         return findSkillContent(skills, contentHash);
     }
 }
+/**
+ * Map the registry `EffectiveConfig` (superset, all domains) → the service-local `EffectiveConfig`
+ * the consumers (`applyEffective`, `resolveMcpServers`, …) expect. The two are structurally compatible
+ * for every field the consumers read; this projection makes that explicit (and drops control-plane-only
+ * domains the service never consumes: rosters, systems, workers, hosts, integrations, access).
+ *
+ * Skills are mapped to the MANIFEST shape (name/description/scenarios/contentHash/enabled) — the same
+ * shape RemoteConfigProvider's `/effective` ships — so the lazy `fetchSkillContent`-by-hash path is
+ * identical in both modes. The local content hash is the `contentHash` the store already computed.
+ */
 export function mapToServiceEffective(eff, version) {
     return {
         version,
@@ -91,27 +197,52 @@ export function mapToServiceEffective(eff, version) {
                 vision: m.vision,
                 ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
                 ...(m.maxTokens !== undefined ? { maxTokens: m.maxTokens } : {}),
+                // codex F5 ([818]① 1M dual-window): an EXPLICIT `autoCompactTokens` must survive this CLOSED
+                // projection — the remote lane ships the roster JSON verbatim and toModel reads the field
+                // structurally, but the local lane funnels through this mapper, which silently ATE the explicit
+                // value (it then fell back to the contextWindow derivation). Structural read (registry-core's
+                // ModelEntry doesn't declare it — same passthrough posture as tierGroups below). NOTE (honest
+                // gap): registry-core's zod ModelEntry is "strip"-mode, so a value in a config.d/models.json read
+                // through FileConfigStore is ALSO dropped upstream of this mapper — that half needs a registry-core
+                // schema addition; this fix removes OUR projection's drop for any caller of this seam.
                 ...(typeof m.autoCompactTokens === "number"
                     ? { autoCompactTokens: m.autoCompactTokens }
                     : {}),
                 ...(m.cost !== undefined ? { cost: m.cost } : {}),
                 ...(m.extraBody !== undefined ? { extraBody: m.extraBody } : {}),
+                // registry-core 0.10.13 promptGuidance ([998]⑤c): the CLOSED projection must pass it through or
+                // the local lane silently drops the configured sentences (autoCompactTokens 同类病).
                 ...(m.promptGuidance !== undefined ? { promptGuidance: m.promptGuidance } : {}),
                 enabled: m.enabled,
             })),
             roles: eff.models.roles ?? {},
+            // [874] registry-core 0.10.11:池结构级 `default?`(catalog name 目录键,与 roles.default 角色词两回事)。
+            // 本 mapper 是 CLOSED 投影——不直通则本地 lane 静默丢键(autoCompactTokens 同类病),applyEffective 的
+            // resolveDefaultModelName 第一优先级在本地 lane 永远点不亮。写面悬空 ref 由 registry-core superRefine
+            // fail-loud;存量/未经 schema 的路径仍由消费方 warn 降级(sema-registry.ts resolveDefaultModelName)。
             ...(eff.models.default !== undefined ? { default: eff.models.default } : {}),
             ...(eff.models.atModelAllowlist !== undefined ? { atModelAllowlist: eff.models.atModelAllowlist } : {}),
+            // registry-core 0.9.0 档位组: verbatim passthrough — applyEffective's resolveActiveTiers reads
+            // these structurally off eff.models (the remote lane ships them JSON-verbatim; the local lane must too).
             ...(eff.models.tierGroups !== undefined ? { tierGroups: eff.models.tierGroups } : {}),
             ...(eff.models.activeTierGroup !== undefined ? { activeTierGroup: eff.models.activeTierGroup } : {}),
         },
+        // registry-core 0.7 DELETED the teams domain (BREAKING, no compat key) — the local lane ships an EMPTY
+        // teams face: applyEffective's teams branch no-ops and the team scenario falls back to the builtin
+        // TEAM_PERSONAS base (a permanent base, not a stopgap). Its successor is `collab` below.
         teams: { teams: [] },
+        // collab domain: verbatim structural passthrough — FileConfigStore reads
+        // config.d/collab.json (PORTABLE_DOMAINS includes collab since 0.7) and applyEffective's
+        // projectCollabToTeams consumes the same shape on both lanes. Optional-chained against shape drift.
         ...(eff.collab?.templates?.length ? { collab: { templates: eff.collab.templates } } : {}),
         skills: {
             skills: (eff.skills.skills ?? []).map((s) => ({
                 name: s.name,
                 description: s.description,
                 scenarios: s.scenarios ?? [],
+                // The local store keeps the body inline; content-address it HERE so the manifest carries the same
+                // `sha256:<hex>` the remote /effective ships — and `fetchSkillContent` (findSkillContent) resolves
+                // the same hash back to the body. (skillContentHash is byte-identical to the center's hash.)
                 contentHash: skillContentHash(s.content),
                 enabled: s.enabled,
             })),
@@ -123,6 +254,8 @@ export function mapToServiceEffective(eff, version) {
                     scenarios: s.scenarios ?? [],
                     enabled: s.enabled,
                     ...(s.allowTools !== undefined ? { allowTools: s.allowTools } : {}),
+                    // E23: carry the per-server inbound-elicitation opt-in (default OFF). Typed end-to-end since
+                    // registry-core 0.1.34 added `McpServerSpec.elicitation?: boolean`.
                     ...(s.elicitation !== undefined ? { elicitation: s.elicitation } : {}),
                 };
                 if (s.transport.kind === "stdio") {
@@ -147,13 +280,22 @@ export function mapToServiceEffective(eff, version) {
                 };
             }),
         },
+        // prompts 域投影(a 实现班车,[985]a §3/[1234]① 位):**catalog 轴打通 local lane**——catalog 是
+        // center 铸好的 immutable envelope(免 covering 解析,server 零解析义务红线 [1042]②b 不破),
+        // config.d/prompts.json 携带 `catalog` 即以 wire 双轴形(registry-core `EffectivePromptsWire`)下发,
+        // 与 remote lane 的 additive prompts key 同门(adoptCenterPrompts→validatePromptsDomain,core verify
+        // 全管线)。bindings(declaration 轴原料)仍不投影:covering 解析半场恒在 center,local lane 的
+        // declaration 轴维持不透传(那不是遗漏,是分工)。
         ...(eff.prompts?.catalog !== undefined
             ? { prompts: { schemaVersion: 1, catalog: eff.prompts.catalog } }
             : {}),
         scenarios: {
+            // ([1057] 注记保留:declaration 轴 remote lane only——covering 解析半场在 center(web),
+            // local FileConfigStore 只有 bindings 原文而 server 零解析义务([1042]②b 红线)。)
             scenarios: (eff.scenarios.scenarios ?? []).map((sc) => ({
                 name: sc.name,
                 toolset: sc.toolset,
+                // ([1053] 0.10.15:ScenarioEntry.prompt 字段已删——scenario 级提示词走 center prompts binding)
                 enabled: sc.enabled,
             })),
         },
@@ -164,15 +306,36 @@ export function mapToServiceEffective(eff, version) {
             ...(eff.runtime.maxPrincipalCostUsd !== undefined ? { maxPrincipalCostUsd: eff.runtime.maxPrincipalCostUsd } : {}),
             ...(eff.runtime.costQuotaWindowSec !== undefined ? { costQuotaWindowSec: eff.runtime.costQuotaWindowSec } : {}),
         },
+        // Governance trio (autonomy/commandPolicy/approvalRequire): moved OUT of runtime into the dedicated
+        // governance domain (registry-core 0.6, runtime double-write mirror removed in 0.7.1 — buildEffective
+        // still READ-lifts legacy raw runtime values into governance, so old on-disk config keeps working).
+        // Mapped to the service-local `governance` slot; applyEffective's gatesView consumes it with priority.
+        // The registry shapes are IDENTICAL to the service's Autonomy/CommandRule declarations (straight passthrough).
         governance: {
             ...(eff.governance.autonomy !== undefined ? { autonomy: eff.governance.autonomy } : {}),
             ...(eff.governance.commandPolicy !== undefined ? { commandPolicy: eff.governance.commandPolicy } : {}),
             ...(eff.governance.approvalRequire !== undefined ? { approvalRequire: eff.governance.approvalRequire } : {}),
         },
+        // NOTE: entitlement is NOT mapped — the ruling is that the local lane never carries it (by design;
+        // TOB governance concept) and the fleet scenario ruling rides center's caps view, not /effective.
     };
 }
+/**
+ * Pick the backend off a CLOSED `provider` enum (`local` | `remote` | undefined): LOCAL when
+ * `CONFIG_PROVIDER=local`, OR when no sema-registry URL is configured (a lone box with config.d/ on disk
+ * and no control plane). REMOTE otherwise (a configured center URL, the default fleet posture). A
+ * `CONFIG_PROVIDER=remote` with no URL is a misconfiguration — we fall through to local rather than
+ * constructing a remote provider with no endpoint (the caller would have skipped the remote pull entirely
+ * under the old code path; local-with-empty-config.d degrades to env the same way). An UNRECOGNIZED value
+ * (typo / wrong case) is NOT treated as remote: it defaults to local (non-network) with a warn, so a
+ * fat-fingered knob can never silently source config from an unintended/stale network endpoint.
+ */
 export function createConfigProvider(input) {
     const p = input.provider;
+    // Closed enum: only `local` | `remote` | undefined are valid. An unrecognized/typo'd value (`Local`,
+    // `LOCAL`, ` local`, garbage) must NOT silently fall through to the network source — pick the non-network
+    // safe default (local) and warn, so a misconfigured knob never sources config (incl. env-NAME refs that
+    // gate secret wiring) from a possibly-stale remote URL the operator didn't intend. See finding #4.
     if (p !== undefined && p !== "local" && p !== "remote") {
         logger.warn("config_provider_unrecognized", {
             provider: p,