@sema-agent/server 7.146.0 → 7.148.0

package/dist/config-lkg.d.ts

@@ -1,5 +1,6 @@
 import { type MigrationReceipt } from "@sema-agent/settings-schema/one-time-migrations";
-import type { PublishedPromptArtifact } from "@sema-agent/core";
+import { type PublishedPromptArtifact } from "@sema-agent/core";
+import { type ConfigDirTrustHost } from "./config-dir-trust.js";
 /** 落盘信封。`effective`/`etag` 逐字=当时的 fetchEffective 返回(JSON verbatim 面)。`formatVersion` 的语义见头注(5 = 载荷的 prompts 是中心层唯一的那种 wire 形)。 */
 export interface PersistedLkg {
     formatVersion: 5;
@@ -22,6 +23,21 @@ export declare function defaultSkillCacheDir(config: {
 export declare function defaultLkgPath(config: {
     readonly agentConfigDir?: string;
 }, worker: string | undefined, identity: string): string;
+/**
+ * formatVersion 1(7.98.0 及以前,信封不带凭证身份)的 LKG 不读回时的**拒因** —— 一个事实一句话:`loadLkg` 的 1 臂(`CONFIG_LKG_PATH` 指到旧文件)与
+ * 起服读腿点名默认路径旧文件名那一臂({@link preIdentityLkgPath})说同一句,运维按同一个 `reason` 认。
+ */
+export declare const PRE_IDENTITY_LKG_REASON = "pre-identity LKG (formatVersion 1) \u2014 not read back: it cannot prove whose credential fetched it (S-651); the next clean candidate rewrites it";
+/**
+ * 默认路径上 7.98.0 及以前的旧 LKG 还在吗 —— 在 ⇒ 交回它的路径,起服读腿据此打一行 `config_lkg_unusable`(拒因 {@link PRE_IDENTITY_LKG_REASON} + 出路「删掉」);
+ * 不在 ⇒ `undefined`。只看名字上有没有东西(`existsSync`),**不读内容**、不迁、不改名:那个名字只有身份箱之前的版本写过,一次性迁移窗已关。
+ * 配置根本身进不去时答「不在」—— 与 {@link loadLkg} 读箱同一个读法(那一形箱也读不到,箱缺席已是这次起服的结局)。
+ * 调用方只在读箱答「缺席」、且没有 `CONFIG_LKG_PATH` 覆写时问(覆写的那一条路径由 `loadLkg` 自己判);`loadLkg` 把读不了的箱也答成缺席,所以这里先看
+ * 箱名字上有没有东西 —— 有 ⇒ 箱在,旧文件与这次起服无关。
+ */
+export declare function preIdentityLkgLeftover(config: {
+    readonly agentConfigDir?: string;
+}, worker: string | undefined, binPath: string): string | undefined;
 /**
  * `CONFIG_LKG_PATH`(LKG 落盘路径覆写)的**唯一读法**:没设 ⇒ `undefined`(LKG 落在配置根下按箱派生,{@link defaultLkgPath});设了 ⇒ 绝对路径
  * (相对值按进程 cwd 解,与文件被打开时同一个解法);空串 ⇒ 拒(起服拒):空串解出来是进程工作目录本身 —— 一条落盘路径不该是一个目录,
@@ -55,14 +71,20 @@ export interface LkgReadMigration {
     readonly note?: string;
     readonly receipts: readonly MigrationReceipt[];
 }
+/** {@link loadLkg} 读之前判官要的两件:声明的属主(`CONFIG_LOCAL_OWNER_UID`,配置席 `configLocalOwnerUid`;与本地配置根同一张可信集)+ 宿主事实(测试注入;缺席 = 本进程)。 */
+export interface LkgReadTrust {
+    readonly declaredOwnerUid: number | undefined;
+    readonly host?: ConfigDirTrustHost;
+}
 /**
  * 读盘上 LKG。返回 undefined 的所有情形都「安静地回 env 兜底」(调用方 warn 点名 reason):
+ * 别人改得动这份文件(目录信任判官的发现)/
  * 文件缺席/JSON 坏/信封形不对/worker 或凭证身份不匹配(防同名文件跨 worker / 跨账号串包;`CONFIG_LKG_PATH`
  * 单一路径时这是唯一的一道)/载荷有迁不动的旧形({@link migrateLkgPayload})/prompts 面复判失败。
  * `migrated`:读回时做过一次性迁移(信封 2 → 3 / 4 → 5 或载荷的 settings-schema 迁移)—— 调用方响亮打一行,并把交回的 5 写回原位。
  * `prompts`:候选判官对这份载荷 prompts 面交出的中心层(引擎 verify 过的发布形 artifact;`undefined` = 载荷不带 prompts 键)—— 调用方采纳直接用它。
  */
-export declare function loadLkg(path: string, worker: string | undefined, identity: string): Promise<{
+export declare function loadLkg(path: string, worker: string | undefined, identity: string, trust: LkgReadTrust): Promise<{
     lkg: PersistedLkg;
     prompts: PublishedPromptArtifact | undefined;
     migrated?: LkgReadMigration;

package/dist/config-lkg.js

@@ -1,17 +1,29 @@
-import { promises as fs } from "node:fs";
+import { existsSync, promises as fs } from "node:fs";
 import { migrateEffectiveSnapshot } from "@sema-agent/settings-schema/one-time-migrations";
 import { formatConfigPath } from "@sema-agent/settings-schema";
 import { join, dirname, resolve } from "node:path";
-import { randomBytes } from "node:crypto";
+import { ensureDir } from "@sema-agent/core";
 import { judgeConfigCandidate } from "./web-admin-client/candidate-gate.js";
 import { centerStateBin } from "./center-credential.js";
 import { configRootOf } from "./sema-config-dir.js";
+import { atomicWriteFileAsync } from "./plugins/owner-only-file-mode.js";
+import { trustedFileRefusal } from "./config-dir-trust.js";
 export function defaultSkillCacheDir(config) {
     return join(configRootOf(config), "skill-cache");
 }
 export function defaultLkgPath(config, worker, identity) {
     return join(configRootOf(config), `config-lkg-${centerStateBin(worker, identity)}.json`);
 }
+export const PRE_IDENTITY_LKG_REASON = "pre-identity LKG (formatVersion 1) — not read back: it cannot prove whose credential fetched it (S-651); the next clean candidate rewrites it";
+function preIdentityLkgPath(config, worker) {
+    return join(configRootOf(config), `config-lkg-${(worker ?? "global").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64)}.json`);
+}
+export function preIdentityLkgLeftover(config, worker, binPath) {
+    if (existsSync(binPath))
+        return undefined;
+    const path = preIdentityLkgPath(config, worker);
+    return existsSync(path) ? path : undefined;
+}
 export function lkgPathOverrideOf(raw) {
     if (raw === undefined)
         return undefined;
@@ -28,12 +40,13 @@ export function lkgReadDenyRows(configLkgPath) {
 }
 export async function saveLkg(path, worker, identity, effective, etag) {
     const body = { formatVersion: 5, savedAt: new Date().toISOString(), worker: worker ?? "global", identity, ...(etag !== undefined ? { etag } : {}), effective };
-    const tmp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
-    await fs.mkdir(dirname(path), { recursive: true });
-    await fs.writeFile(tmp, JSON.stringify(body), { mode: 0o600 });
-    await fs.rename(tmp, path);
+    ensureDir(dirname(path));
+    await atomicWriteFileAsync(path, JSON.stringify(body), { durability: "best-effort" });
 }
-export async function loadLkg(path, worker, identity) {
+export async function loadLkg(path, worker, identity, trust) {
+    const untrusted = await trustedFileRefusal({ reader: "lkg", file: path, declaredOwnerUid: trust.declaredOwnerUid, ...(trust.host !== undefined ? { host: trust.host } : {}) });
+    if (untrusted !== undefined)
+        return { reason: untrusted };
     let text;
     try {
         text = await fs.readFile(path, "utf8");
@@ -53,7 +66,7 @@ export async function loadLkg(path, worker, identity) {
     const p = parsed;
     const formatVersion = p.formatVersion;
     if (formatVersion === 1)
-        return { reason: "pre-identity LKG (formatVersion 1) — not read back: it cannot prove whose credential fetched it (S-651); the next clean candidate rewrites it" };
+        return { reason: PRE_IDENTITY_LKG_REASON };
     if (formatVersion !== 2 && formatVersion !== 3 && formatVersion !== 4 && formatVersion !== 5)
         return { reason: `unknown formatVersion ${String(formatVersion)}` };
     if (typeof p.worker !== "string" || p.worker !== (worker ?? "global"))
@@ -153,7 +166,7 @@ function lkgPayloadShapeProblem(effective, etag) {
     const eff = effective;
     if (typeof eff.version !== "number")
         return "bad effective.version";
-    for (const [domain, arrayKey] of [["models", "models"], ["skills", "skills"], ["mcp", "servers"], ["scenarios", "scenarios"], ["limits", null]]) {
+    for (const [domain, arrayKey] of [["models", "models"], ["skills", "skills"], ["mcp", "servers"], ["a2a", "peers"], ["scenarios", "scenarios"], ["limits", null]]) {
         const v = eff[domain];
         if (v === undefined)
             continue;

package/dist/config-provider.d.ts

@@ -80,7 +80,7 @@ export declare const BOOT_FETCH_DEFERRED: unique symbol;
  * 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>;
+export declare function raceBootFetch<T>(pull: 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 `facade.fetchEffective` / `facade.fetchSkillContent`
@@ -186,16 +186,16 @@ export declare class LocalConfigProvider implements ConfigProvider {
     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).
+ * 本地腿交出的有效视图 —— **与中心 `/effective` 同一形**(两条腿只交一种形:契约的线上视图;远端腿交中心铸的那一份,`http-client.ts`)。
  *
- * 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.
+ * 铸法只有契约里那一只:`resolveEffectiveForWorker(eff, null)` —— 中心把存储形铸成 `/effective` 用的同一个函数(本地腿没有 worker 身份 ⇒ 全局拉取:
+ * 目录不按名册收窄、`rosters` 域清空、`entitlement` 清空、技能换成 manifest〔`content` → `contentHash`,正文经 {@link LocalConfigProvider.fetchSkillContent}
+ * 按哈希从同一次读取的存储形里找〕、其余域原样)。本地腿唯一自己的一步是**发布**:存储形的 `prompts` 换成发布形(`localPromptsWire`,契约包的唯一选择读法;
+ * 中心那一步是它的发布闸)。
+ *
+ * 不在这里挑键:每个消费方读自己要的字段(远端腿上它们读的一直是整份线上视图),所以契约给条目加一个键,两条腿同时带上 —— 不存在「本地腿静默丢键」那一类补丁。
  */
-export declare function mapToServiceEffective(eff: AgentConfigEffective, version: number): EffectiveConfig;
+export declare function publishLocalEffective(eff: AgentConfigEffective): EffectiveConfig;
 /**
  * 建判官 {@link configSourceKind} 答出来的那一种配置源:`local` ⇒ {@link LocalConfigProvider}(根 = 递进来的 `localDir`);`remote` ⇒
  * {@link RemoteConfigProvider}(中心 = `webAdmin`)。判官答「无配置源」(没写词、没配中心 = 纯 env 部署)⇒ 抛:调用方只在判官答 local / remote 时建

package/dist/config-provider.js

@@ -1,13 +1,13 @@
-import { readMcpSourceLabel } from "./mcp-source-label.js";
 import { createHmac, randomBytes } from "node:crypto";
 import { splitFoldedReadWarnings, withDroppedCatalogEntries } from "./web-admin-client/read-warnings.js";
 import { FileConfigStore, readEnvModelsDecision } from "@sema-agent/settings-schema/node";
 import { envModelsDecisionTag } from "@sema-agent/settings-schema";
 import { REMOTE_CATALOG_SOURCE } from "./env-model-table-gate.js";
 import { assertLocalConfigDirTrusted } from "./config-dir-trust.js";
-import { danglingRefs, emptyEffective, findSkillContent, promptArtifactFor, renderRefIssue, skillContentHash, } from "@sema-agent/settings-schema";
+import { candidateRefusedBy } from "./config-pull-failure.js";
+import { danglingRefs, emptyEffective, findSkillContent, promptArtifactFor, renderRefIssue, resolveEffectiveForWorker, } from "@sema-agent/settings-schema";
 import { redactSecrets } from "./trace/redact.js";
-import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, skillToolListsOf, WebAdminHttpError, } from "./web-admin-client/facade.js";
+import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, WebAdminHttpError, } from "./web-admin-client/facade.js";
 import { remoteConfigProviderUrlRefusal } from "./config-invariants.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -31,7 +31,7 @@ const redactContractSentence = (text) => redactSecrets(text);
 const redactDroppedEntry = (d) => ({ ...d, error: redactContractSentence(d.error) });
 const redactRefusedDocument = (d) => ({ ...d, error: redactContractSentence(d.error) });
 export const BOOT_FETCH_DEFERRED = Symbol("boot-fetch-deferred");
-export function raceBootFetch(fetch, budgetMs) {
+export function raceBootFetch(pull, budgetMs) {
     if (budgetMs <= 0)
         return Promise.resolve(BOOT_FETCH_DEFERRED);
     let timer;
@@ -39,7 +39,7 @@ export function raceBootFetch(fetch, budgetMs) {
         timer = setTimeout(() => res(BOOT_FETCH_DEFERRED), budgetMs);
         timer.unref?.();
     });
-    return Promise.race([fetch.finally(() => clearTimeout(timer)), budget]);
+    return Promise.race([pull.finally(() => clearTimeout(timer)), budget]);
 }
 export class RemoteConfigProvider {
     cc;
@@ -95,7 +95,15 @@ export class LocalConfigProvider {
     }
     async fetchEffective(etag) {
         await assertLocalConfigDirTrusted({ root: this.root, declaredOwnerUid: this.#declaredOwnerUid });
-        const read = await this.#store.read();
+        let read;
+        try {
+            read = await this.#store.read();
+        }
+        catch (readerError) {
+            if (isFileSystemError(readerError))
+                throw readerError;
+            throw candidateRefusedBy(readerError);
+        }
         const envModels = await readEnvModelsDecision(this.root);
         const catalogSource = { kind: "local", root: this.root, envModels };
         const tag = buildLocalConfigEtag(read.kind === "refused" ? read.version : read.effective.version, envModels);
@@ -128,7 +136,7 @@ export class LocalConfigProvider {
         this.#servedSkills = eff.skills;
         const unreadKeys = localUnreadPromptKeys(eff.prompts);
         return {
-            effective: withDroppedCatalogEntries(mapToServiceEffective(eff, eff.version), folded.droppedCatalogEntries),
+            effective: withDroppedCatalogEntries(publishLocalEffective(eff), folded.droppedCatalogEntries),
             ...(errors.length > 0 ? { domainErrors: errors } : {}),
             ...(droppedEntries.length > 0 ? { droppedEntries } : {}),
             ...(unreadKeys.length > 0 ? { unreadKeys } : {}),
@@ -138,9 +146,15 @@ export class LocalConfigProvider {
         return findSkillContent(this.#servedSkills, contentHash);
     }
 }
+function isFileSystemError(e) {
+    if (!(e instanceof Error))
+        return false;
+    const { syscall, code } = e;
+    return typeof syscall === "string" && typeof code === "string";
+}
 function refusedFaces(read) {
     return {
-        effective: mapToServiceEffective({ ...emptyEffective(), version: read.version }, read.version),
+        effective: publishLocalEffective({ ...emptyEffective(), version: read.version }),
         refusedDocuments: read.refusals.map(redactRefusedDocument),
     };
 }
@@ -152,106 +166,9 @@ function localPromptsWire(prompts, version) {
     const artifact = prompts === undefined ? undefined : promptArtifactFor(prompts, null);
     return artifact === undefined ? {} : { prompts: { schemaVersion: 2, artifact: { ...artifact, sourceRevision: `local:r${version}` } } };
 }
-export function mapToServiceEffective(eff, version) {
-    return {
-        version,
-        updatedAt: eff.updatedAt,
-        models: {
-            models: (eff.models.models ?? []).map((m) => ({
-                name: m.name,
-                id: m.id,
-                provider: m.provider,
-                api: m.api,
-                ...(m.baseUrl !== undefined ? { baseUrl: m.baseUrl } : {}),
-                ...(m.apiKeyEnv !== undefined ? { apiKeyEnv: m.apiKeyEnv } : {}),
-                ...(m.sealedApiKey !== undefined ? { sealedApiKey: m.sealedApiKey } : {}),
-                ...(m.quotaWeight !== undefined ? { quotaWeight: m.quotaWeight } : {}),
-                tier: m.tier,
-                ...(m.reasoning !== undefined ? { reasoning: m.reasoning } : {}),
-                ...(m.vision !== undefined ? { vision: m.vision } : {}),
-                ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
-                ...(m.maxTokens !== undefined ? { maxTokens: m.maxTokens } : {}),
-                ...(typeof m.autoCompactTokens === "number" ? { autoCompactTokens: m.autoCompactTokens } : {}),
-                ...(typeof m.charsPerToken === "number" ? { charsPerToken: m.charsPerToken } : {}),
-                ...(m.cost !== undefined ? { cost: m.cost } : {}),
-                ...(m.extraBody !== undefined ? { extraBody: m.extraBody } : {}),
-                ...(m.compat !== undefined ? { compat: m.compat } : {}),
-                ...(m.headers !== undefined ? { headers: m.headers } : {}),
-                ...(m.promptGuidance !== undefined ? { promptGuidance: m.promptGuidance } : {}),
-                enabled: m.enabled,
-            })),
-            roles: eff.models.roles ?? {},
-            atMention: eff.models.atMention,
-            ...(eff.models.tierGroups !== undefined ? { tierGroups: eff.models.tierGroups } : {}),
-            ...(eff.models.activeTierGroup !== undefined ? { activeTierGroup: eff.models.activeTierGroup } : {}),
-        },
-        ...(eff.collab?.templates?.length ? { collab: { templates: eff.collab.templates } } : {}),
-        ...(eff.plugins?.plugins?.length ? { plugins: { plugins: eff.plugins.plugins } } : {}),
-        skills: {
-            skills: (eff.skills.skills ?? []).map((s) => ({
-                name: s.name,
-                description: s.description,
-                scenarios: s.scenarios ?? [],
-                contentHash: skillContentHash(s.content),
-                enabled: s.enabled,
-                ...skillToolListsOf(s),
-            })),
-        },
-        mcp: {
-            servers: (eff.mcp.servers ?? []).map((s) => {
-                const base = {
-                    name: s.name,
-                    scenarios: s.scenarios ?? [],
-                    enabled: s.enabled,
-                    ...(s.allowTools !== undefined ? { allowTools: s.allowTools } : {}),
-                    ...(s.elicitation !== undefined ? { elicitation: s.elicitation } : {}),
-                    ...(s.contentOrigin !== undefined ? { contentOrigin: s.contentOrigin } : {}),
-                    ...readMcpSourceLabel(s.name, s.source),
-                    ...(s.toolFaces !== undefined ? { toolFaces: s.toolFaces } : {}),
-                    ...(s.toolAxes !== undefined ? { toolAxes: s.toolAxes } : {}),
-                    ...(s.sessionMetaKey !== undefined ? { sessionMetaKey: s.sessionMetaKey } : {}),
-                    ...(s.startupTimeoutMs !== undefined ? { startupTimeoutMs: s.startupTimeoutMs } : {}),
-                    ...(s.authForm !== undefined ? { authForm: s.authForm } : {}),
-                    ...(s.entryKind !== undefined ? { entryKind: s.entryKind } : {}),
-                };
-                if (s.transport.kind === "stdio") {
-                    return {
-                        ...base,
-                        transport: {
-                            kind: "stdio",
-                            command: s.transport.command,
-                            ...(s.transport.args !== undefined ? { args: s.transport.args } : {}),
-                            ...(s.transport.envRefs !== undefined ? { envRefs: s.transport.envRefs } : {}),
-                        },
-                    };
-                }
-                return {
-                    ...base,
-                    transport: {
-                        kind: "http",
-                        url: s.transport.url,
-                        ...(s.transport.headerRefs !== undefined ? { headerRefs: s.transport.headerRefs } : {}),
-                        ...(s.transport.principalHeader !== undefined ? { principalHeader: s.transport.principalHeader } : {}),
-                        ...(s.transport.assertionHeader !== undefined ? { assertionHeader: s.transport.assertionHeader } : {}),
-                    },
-                };
-            }),
-        },
-        ...localPromptsWire(eff.prompts, version),
-        scenarios: {
-            scenarios: (eff.scenarios.scenarios ?? []).map((sc) => ({
-                name: sc.name,
-                toolset: sc.toolset,
-                enabled: sc.enabled,
-            })),
-        },
-        ...(eff.limits !== undefined ? { limits: eff.limits } : {}),
-        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 } : {}),
-        },
-    };
+export function publishLocalEffective(eff) {
+    const { prompts: _storageForm, ...wire } = resolveEffectiveForWorker(eff, null).config;
+    return { ...wire, ...localPromptsWire(eff.prompts, eff.version) };
 }
 export function createConfigProvider(input) {
     const kind = configSourceKind({ configProvider: input.provider, webAdmin: input.webAdmin });

package/dist/config-pull-failure.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 一次配置拉取失败的**成因** —— 在拉取那一层定一次,失败行(起服 `config_source_unreachable_using_env` / 刷新拍 `web_admin_refresh_failed` /
+ * 迟到起服重拉 `config_boot_arrival_repull_failed` / run-local)读同一个值(错误上的 `pullCause`),不各写一份。
+ *
+ * 判据只有一条:**错误的型**。拉取层自己铸型 —— 契约读腿整包抛 ⇒ 读腿那一处包成 {@link ConfigCandidateRefusedError}({@link candidateRefusedBy};远程腿 `http-client.ts`、本地腿
+ * `config-provider.ts`;本地腿的目录信任拒 `ConfigDirUntrustedError` 是它的子类);应答属于一把已不在用的中心凭证 ⇒ {@link ConfigPullSupersededError}
+ * (起服服务的拉取口 `pullEffective`);其余一切出自拉取口的抛 ⇒ 拉取口包成 {@link ConfigSourceUnreachableError}。所以一只 catch 不用自记「走到哪一段了」:
+ * 是 {@link ConfigPullError} ⇒ 拉取失败(词 = 它的 `pullCause`);不是 ⇒ 拉取已成、后面的段抛的。
+ *
+ * 包装不改运维读到的那一句:包出来的错与原错 `name` / `message` 逐字同(`String(err)` 逐字同),原错挂在 `cause` 上。
+ *
+ * 纯叶(零 import)。
+ */
+/**
+ * 拉取失败的成因闭集(词序即文档序;加词 ⇒ {@link configPullFailureNote} 的穷尽 `switch` 编译红):
+ *  · `unreachable` —— 没拿到候选:传输错 / HTTP 非 2xx / 凭证取不到 / 重定向被拒 / 超时 / 读体途中断;本地腿上文件系统的错(读不到目录里的字节);
+ *  · `rejected` —— 配置源答了,本引擎拒收这份候选:契约读腿整包抛(门控域判形失败、载荷不是有效视图、体不是 JSON),或本地配置目录不被信任;
+ *  · `superseded` —— 应答在飞期间中心凭证换了人,这份应答属于上一把凭证 ⇒ 弃掉(下一拉按现凭证)。
+ */
+export declare const CONFIG_PULL_FAILURE_CAUSES: readonly ["unreachable", "rejected", "superseded"];
+export type ConfigPullFailureCause = (typeof CONFIG_PULL_FAILURE_CAUSES)[number];
+/** 刷新失败行的成因:拉取失败三词之外多一词 `apply_refused`(拉取已成、应用段抛 —— 起服把这一形记成另一个事件 `config_apply_refused`,刷新拍与迟到起服只有一行)。 */
+export type ConfigRefreshFailureCause = ConfigPullFailureCause | "apply_refused";
+/** 拉取层铸的错误型的共同基类(具体型只有下面三只与目录信任拒;成因读 `pullCause`)。 */
+export declare abstract class ConfigPullError extends Error {
+    abstract readonly pullCause: ConfigPullFailureCause;
+    protected constructor(message: string, name: string, options?: ErrorOptions);
+}
+/** `rejected`:配置源答了,本引擎拒收这份候选。读腿处用 {@link candidateRefusedBy} 包读者的原错;目录信任拒(`ConfigDirUntrustedError`)是子类,自铸句子。 */
+export declare class ConfigCandidateRefusedError extends ConfigPullError {
+    readonly pullCause: "rejected";
+    constructor(message: string, name: string, options?: ErrorOptions);
+}
+/** 读腿整包抛 ⇒ `rejected`(与原错 `name` / `message` 逐字同,原错挂 `cause`)。远程腿 `fetchEffective` 与本地腿 `LocalConfigProvider.fetchEffective` 的读腿处各调一次。 */
+export declare function candidateRefusedBy(readerError: unknown): ConfigCandidateRefusedError;
+/** `superseded`:应答属于一把已不在用的中心凭证。 */
+export declare class ConfigPullSupersededError extends ConfigPullError {
+    readonly pullCause: "superseded";
+    constructor(message: string);
+}
+/** `unreachable`:没拿到候选。拉取口用 {@link asConfigPullError} 包其余一切抛。 */
+export declare class ConfigSourceUnreachableError extends ConfigPullError {
+    readonly pullCause: "unreachable";
+    constructor(transportError: unknown);
+}
+/** 一次拉取的抛 ⇒ 拉取层铸的型(已是 ⇒ 原样;否则 ⇒ `unreachable`)。拉取口(起服服务的 `pullEffective`、run-local 的那一拉)的 catch 只调它。 */
+export declare function asConfigPullError(err: unknown): ConfigPullError;
+/** 失败行的 `note`(穷尽 switch:成因闭集加词不补句 ⇒ 编译红)。 */
+export declare function configPullFailureNote(cause: ConfigPullFailureCause): string;
+//# sourceMappingURL=config-pull-failure.d.ts.map

package/dist/config-pull-failure.js

@@ -0,0 +1,48 @@
+export const CONFIG_PULL_FAILURE_CAUSES = ["unreachable", "rejected", "superseded"];
+const nameOf = (e) => (e instanceof Error ? e.name : "Error");
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+export class ConfigPullError extends Error {
+    constructor(message, name, options) {
+        super(message, options);
+        this.name = name;
+    }
+}
+export class ConfigCandidateRefusedError extends ConfigPullError {
+    pullCause = "rejected";
+    constructor(message, name, options) {
+        super(message, name, options);
+    }
+}
+export function candidateRefusedBy(readerError) {
+    return new ConfigCandidateRefusedError(messageOf(readerError), nameOf(readerError), { cause: readerError });
+}
+export class ConfigPullSupersededError extends ConfigPullError {
+    pullCause = "superseded";
+    constructor(message) {
+        super(message, "Error");
+    }
+}
+export class ConfigSourceUnreachableError extends ConfigPullError {
+    pullCause = "unreachable";
+    constructor(transportError) {
+        super(messageOf(transportError), nameOf(transportError), { cause: transportError });
+    }
+}
+export function asConfigPullError(err) {
+    return err instanceof ConfigPullError ? err : new ConfigSourceUnreachableError(err);
+}
+export function configPullFailureNote(cause) {
+    switch (cause) {
+        case "unreachable":
+            return "no candidate was obtained from the config source (transport error, non-2xx answer, credential unavailable, redirect refused, timeout, or a filesystem error reading the local config directory) — the serving config stays as it is and the next pull retries";
+        case "rejected":
+            return "the config source answered but this engine refuses the candidate (a gate domain failed its schema, the payload is not an effective config, or the local config directory is not trusted) — `err` carries the reader's sentence with the field path; fix the named document";
+        case "superseded":
+            return "the answer belonged to a center credential that is no longer current — discarded; the next pull runs under the current credential";
+        default: {
+            const unhandled = cause;
+            throw new Error(`config pull failure: unknown cause ${String(unhandled)}`);
+        }
+    }
+}
+//# sourceMappingURL=config-pull-failure.js.map