@sema-agent/settings-schema 2.1.0 → 3.0.1

package/dist/api/auth.d.ts

@@ -26,7 +26,48 @@
  * Pure zod contract — zero IO, browser-safe, same rules as the rest of this package.
  */
 import { z } from "zod";
-export { AUTH_V1_PATHS, DEVICE_GRANT_TYPE, DEVICE_POLL_INTERVAL_SECONDS, DEVICE_CODE_TTL_SECONDS, ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS, OAUTH_ERROR_CODES, DEVICE_AUTH_STATUSES, normalizeUserCode, nextPollInterval, type OAuthErrorCode, type DeviceAuthStatus, } from "./wire.js";
+/** The five auth endpoints, relative to the registry origin. */
+export declare const AUTH_V1_PATHS: {
+    readonly deviceCode: "/api/v1/auth/device/code";
+    readonly deviceToken: "/api/v1/auth/device/token";
+    readonly deviceApprove: "/api/v1/auth/device/approve";
+    readonly tokenRefresh: "/api/v1/auth/token/refresh";
+    readonly logout: "/api/v1/auth/logout";
+};
+/** The RFC 8628 grant_type the device token endpoint requires. */
+export declare const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Minimum seconds between token-endpoint polls (RFC 8628 `interval`); polling faster → `slow_down`. */
+export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
+/** Device-code handshake lifetime (seconds) — the user has 15 minutes to open /activate and approve. */
+export declare const DEVICE_CODE_TTL_SECONDS: number;
+/** Access-token (RS256 JWT) lifetime in seconds — 1h, re-minted via refresh. */
+export declare const ACCESS_TOKEN_TTL_SECONDS: number;
+/** Refresh-grant lifetime (seconds) — 30d SLIDING: every rotation opens a fresh 30d window. */
+export declare const REFRESH_TOKEN_TTL_SECONDS: number;
+/** Every error code the /api/v1/auth/* endpoints answer (HTTP 400 unless noted). */
+export declare const OAUTH_ERROR_CODES: readonly ["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"];
+export type OAuthErrorCode = (typeof OAUTH_ERROR_CODES)[number];
+/** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
+ *  `denied` is contract-reserved for an explicit deny button (pairs with the `access_denied` poll error);
+ *  the shipped M1 store carries pending|approved only — adding deny later is implementation, not schema. */
+export declare const DEVICE_AUTH_STATUSES: readonly ["pending", "approved", "denied"];
+export type DeviceAuthStatus = (typeof DEVICE_AUTH_STATUSES)[number];
+/**
+ * Canonicalize a human-typed user code to the wire shape "XXXX-XXXX": uppercase, dashes/spaces optional.
+ * null = not a plausible code (wrong length/charset after stripping separators). Same normalization the
+ * server applies — run it client-side for instant feedback.
+ */
+export declare function normalizeUserCode(input: unknown): string | null;
+/**
+ * The RFC 8628 §3.5 poll-loop step: what interval to poll with next, and whether to keep going.
+ * - authorization_pending → keep polling at the current interval
+ * - slow_down             → keep polling, interval + 5s (the RFC-mandated increment)
+ * - anything else         → stop (expired_token/access_denied = terminal; invalid_* = client bug)
+ */
+export declare function nextPollInterval(currentIntervalSeconds: number, error: OAuthErrorCode): {
+    continue: boolean;
+    intervalSeconds: number;
+};
 /** The uniform error body. `error_description` is HUMAN diagnostic text — clients branch on `error` only. */
 export declare const OAuthErrorResponse: z.ZodObject<{
     error: z.ZodEnum<["authorization_pending", "slow_down", "expired_token", "access_denied", "invalid_request", "unsupported_grant_type", "invalid_grant", "server_error"]>;

package/dist/api/auth.js

@@ -26,11 +26,78 @@
  * Pure zod contract — zero IO, browser-safe, same rules as the rest of this package.
  */
 import { z } from "zod";
-import { OAUTH_ERROR_CODES, DEVICE_AUTH_STATUSES, DEVICE_GRANT_TYPE } from "./wire.js";
-// ── PURE wire subset moved to ./wire.ts(server AI 接手首车 2026-07-27):零依赖客户端可
-// `@sema-agent/settings-schema/api/wire` 运行时直取;这里 re-export 保持既有导入面字节兼容。
-export { AUTH_V1_PATHS, DEVICE_GRANT_TYPE, DEVICE_POLL_INTERVAL_SECONDS, DEVICE_CODE_TTL_SECONDS, ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS, OAUTH_ERROR_CODES, DEVICE_AUTH_STATUSES, normalizeUserCode, nextPollInterval, } from "./wire.js";
 // ── endpoint paths + protocol constants (shipped values) ─────────────────────────────────────────────────
+// 3.0.0(S-321):这些常量与纯函数 2026-07-27 曾被拆去 `./api/wire` 子路径(给「零依赖客户端运行时直取」
+// 留的门),四个消费仓自始至终零 import —— 死出口连同它的拆分一起删,常量回到它们的契约原处。
+/** The five auth endpoints, relative to the registry origin. */
+export const AUTH_V1_PATHS = {
+    deviceCode: "/api/v1/auth/device/code",
+    deviceToken: "/api/v1/auth/device/token",
+    deviceApprove: "/api/v1/auth/device/approve",
+    tokenRefresh: "/api/v1/auth/token/refresh",
+    logout: "/api/v1/auth/logout",
+};
+/** The RFC 8628 grant_type the device token endpoint requires. */
+export const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Minimum seconds between token-endpoint polls (RFC 8628 `interval`); polling faster → `slow_down`. */
+export const DEVICE_POLL_INTERVAL_SECONDS = 5;
+/** Device-code handshake lifetime (seconds) — the user has 15 minutes to open /activate and approve. */
+export const DEVICE_CODE_TTL_SECONDS = 15 * 60;
+/** Access-token (RS256 JWT) lifetime in seconds — 1h, re-minted via refresh. */
+export const ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
+/** Refresh-grant lifetime (seconds) — 30d SLIDING: every rotation opens a fresh 30d window. */
+export const REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** Every error code the /api/v1/auth/* endpoints answer (HTTP 400 unless noted). */
+export const OAUTH_ERROR_CODES = [
+    /** device/token: the user has not approved (or denied) the handshake yet — keep polling. */
+    "authorization_pending",
+    /** device/token: polling faster than `interval` — RFC 8628 §3.5: ADD 5 seconds to the interval. */
+    "slow_down",
+    /** device/token: handshake expired, unknown, or already exchanged — restart the flow.
+     *  (Deliberately covers "never existed": the server does not disclose handshake existence.) */
+    "expired_token",
+    /** device/token: the user explicitly denied the handshake — stop polling, do not restart silently. */
+    "access_denied",
+    /** any endpoint: malformed body / missing required field / wrong content type. */
+    "invalid_request",
+    /** device/token: grant_type is not DEVICE_GRANT_TYPE. */
+    "unsupported_grant_type",
+    /** token/refresh + device/approve: unknown / expired / revoked / replayed token or code — no detail. */
+    "invalid_grant",
+    /** SSO not configured on the registry (HTTP 503) — a deployment problem, not a client one. */
+    "server_error",
+];
+/** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
+ *  `denied` is contract-reserved for an explicit deny button (pairs with the `access_denied` poll error);
+ *  the shipped M1 store carries pending|approved only — adding deny later is implementation, not schema. */
+export const DEVICE_AUTH_STATUSES = ["pending", "approved", "denied"];
+// ── auth: pure client-side helpers(api/auth.ts 原件)────────────────────────────────────────────────────
+/**
+ * Canonicalize a human-typed user code to the wire shape "XXXX-XXXX": uppercase, dashes/spaces optional.
+ * null = not a plausible code (wrong length/charset after stripping separators). Same normalization the
+ * server applies — run it client-side for instant feedback.
+ */
+export function normalizeUserCode(input) {
+    if (typeof input !== "string")
+        return null;
+    const raw = input.toUpperCase().replace(/[\s-]/g, "");
+    if (!/^[A-Z0-9]{8}$/.test(raw))
+        return null;
+    return `${raw.slice(0, 4)}-${raw.slice(4)}`;
+}
+/**
+ * The RFC 8628 §3.5 poll-loop step: what interval to poll with next, and whether to keep going.
+ * - authorization_pending → keep polling at the current interval
+ * - slow_down             → keep polling, interval + 5s (the RFC-mandated increment)
+ * - anything else         → stop (expired_token/access_denied = terminal; invalid_* = client bug)
+ */
+export function nextPollInterval(currentIntervalSeconds, error) {
+    if (error === "authorization_pending")
+        return { continue: true, intervalSeconds: currentIntervalSeconds };
+    if (error === "slow_down")
+        return { continue: true, intervalSeconds: currentIntervalSeconds + 5 };
+    return { continue: false, intervalSeconds: currentIntervalSeconds };
+}
 // ── OAuth error envelope (RFC 6749 §5.2 / RFC 8628 §3.5) ─────────────────────────────────────────────────
 /** The uniform error body. `error_description` is HUMAN diagnostic text — clients branch on `error` only. */
 export const OAuthErrorResponse = z

package/dist/api/scopes.d.ts

@@ -51,7 +51,15 @@ export declare const GLOBAL_SCOPE = "global";
 export declare const RESERVED_SCOPE_IDS: readonly ["global"];
 /** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
 export declare const SCOPE_ID_REGEX: RegExp;
-export { SCOPES_V1_PATHS, SCOPE_CLAIM } from "./wire.js";
+/** The scope endpoints, relative to the registry origin. `members` needs the scope id — use scopeMembersPath. */
+export declare const SCOPES_V1_PATHS: {
+    /** GET (list) + POST (create). */
+    readonly scopes: "/api/v1/scopes";
+    /** POST — mint a new access token bound to another scope. */
+    readonly authScope: "/api/v1/auth/scope";
+};
+/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+export declare const SCOPE_CLAIM = "scope";
 /** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
 export declare function scopeMembersPath(scopeId: string): string;
 /** True for ids the API refuses to create/delete ("global"). */

package/dist/api/scopes.js

@@ -54,8 +54,14 @@ export const RESERVED_SCOPE_IDS = [GLOBAL_SCOPE];
 /** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
 export const SCOPE_ID_REGEX = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 /** The scope endpoints, relative to the registry origin. `members` needs the scope id — use scopeMembersPath. */
-import { SCOPES_V1_PATHS } from "./wire.js";
-export { SCOPES_V1_PATHS, SCOPE_CLAIM } from "./wire.js"; // moved to the zero-dep wire subset (re-export = 字节兼容)
+export const SCOPES_V1_PATHS = {
+    /** GET (list) + POST (create). */
+    scopes: "/api/v1/scopes",
+    /** POST — mint a new access token bound to another scope. */
+    authScope: "/api/v1/auth/scope",
+};
+/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+export const SCOPE_CLAIM = "scope";
 /** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
 export function scopeMembersPath(scopeId) {
     return `${SCOPES_V1_PATHS.scopes}/${encodeURIComponent(scopeId)}/members`;

package/dist/config-fns.d.ts

@@ -133,9 +133,28 @@ export interface PublishedSnapshot {
 export declare function emptyEffective(): EffectiveConfig;
 /** Validate + fill defaults for a domain payload (or the schema's empty default when absent/invalid). */
 export declare function parseDomain<K extends DomainName>(domain: K, raw: unknown): DomainConfig[K];
-/** 一条被丢掉的条目:`path` = 点号路径(`models.3` / `roles.summarize`),`error` 已脱敏。 */
+/** 一条告警的**坐标**:从域文档根出发的段序列。字符串段 = 对象键(逐字,含 `.` 也逐字);数字段 =
+ *  **数组下标**(非负整数;回写后 = 原文档下标)。今天没有任何告警指向域根,空数组不铸。
+ *
+ *  3.0.0 起取代点号串(S-323c)。串是**有损编码**:键名本来就允许含 `.`(见 {@link isReservedExtensionKey}
+ *  的分段匹配注),于是 `models.1.k` 既编码 `models[1].k`,也编码一个**字面叫 `models.1.k` 的顶层键**。
+ *  段形把「这一段是下标还是键名」这个位重新带上 —— 回写律因此从 2.1.0 的「两支文法各认各的」收成
+ *  **一条**({@link rebaseWarningPaths}),段数门与规范十进制门一并删除:规则数变少。
+ *
+ *  出门(日志 / UI)走 {@link formatConfigPath} 单铸;包内不做反向解析。 */
+export type ConfigPath = readonly (string | number)[];
+/** 一条 {@link ConfigPath} 的出门形(日志 / UI / 人读的告警文本)—— 本包**唯一**的 stringify 点,
+ *  消费方零复述。段间 `.`;数字段十进制;字符串段{@link PLAIN_PATH_SEGMENT 能逐字出门}就逐字,否则按
+ *  JSON 字符串字面量加引号(`models.1."a.b"` / `models."1".k`)—— 不加引号的话,含点的键段会与数组路径
+ *  出成同一个串、字面叫 `"1"` 的键会与下标 `1` 同形,那正是 S-323c 要消掉的二义。
+ *
+ *  **刻意不提供 parse 反函数**:2.1.0 起没有任何一处把坐标读回来(回写走 `keptIndex` 那本账),给它
+ *  一个反函数就是给下一个人一条「在串上做事」的路。 */
+export declare function formatConfigPath(p: ConfigPath): string;
+/** 一条被丢掉的条目:`path` = 段坐标({@link ConfigPath};`["models", 3]` / `["roles", "summarize"]`),
+ *  `error` 已脱敏。 */
 export interface DroppedEntry {
-    path: string;
+    path: ConfigPath;
     error: unknown;
 }
 /** 抢救造成的**下标位移表**:数组字段名 → 该字段压缩后每个位置的**原**下标(`kept[j]` = 压缩后第 j 条
@@ -208,7 +227,7 @@ export declare function statusRowsToPrune(rows: {
  *  store upgrades with zero data migration and zero gate loss. An explicitly-set governance domain WINS
  *  (its absence-of-a-key then means "center not managing", never "fall back to legacy runtime").
  *
- *  SUNSET (1.11.0): removal is a **persistent-data** break — a store still carrying the 0.5 shape would lose
+ *  SUNSET (2.0.0): removal is a **persistent-data** break — a store still carrying the 0.5 shape would lose
  *  its guardrails silently, so this arm cannot simply be deleted at a minor. It goes at the next MAJOR, with
  *  the standard persistent-data treatment (a loud refusal naming the domain + a one-time migration on the
  *  writer side), and the closing condition is observable rather than a promise: `buildEffective` now emits
@@ -232,7 +251,8 @@ export type EffectiveReadWarning = {
     error: unknown;
 }
 /** 域文档里那些**不属于该域 schema** 的键:行为照旧(zod 非 strict = 剥掉,前向兼容不动),但点名
- *  说出来。`keys` = 点号路径(`infraCostRates.toolCalMicroUsd` / `commandPolicy.0.typo`),见
+ *  说出来。`keys` = 段坐标({@link ConfigPath};`["infraCostRates","toolCalMicroUsd"]` /
+ *  `["commandPolicy",0,"typo"]`),见
  *  {@link droppedKeys} 的扫描边界。**1.5.0**:①{@link EXTENSION_NAMESPACES} 登记的扩展键(别的写者按契约
  *  放在文档里、本包刻意不认的键,如壳写在 models 条目上的 `sema*`)**不算未知键**——既不点名也不计数;
  *  ②`keys` 有界(`DROP_SCAN_MAX_KEYS`),超界时带 `truncatedFrom`(= 真实未知键总数,与 `hosts-grandfathered`
@@ -240,33 +260,33 @@ export type EffectiveReadWarning = {
  | {
     domain: DomainName;
     kind: "unknown-keys-dropped";
-    keys: string[];
+    keys: ConfigPath[];
     truncatedFrom?: number;
 }
 /** open-world 域(`.passthrough()`)里**已送达但本包不认识**的键:值原样到了消费方手里(承运),
- *  但拼错的键名同样该有人说 —— 认不认归持有键表的消费方,`keys` 是点号路径。 */
+ *  但拼错的键名同样该有人说 —— 认不认归持有键表的消费方,`keys` 是段坐标({@link ConfigPath})。 */
  | {
     domain: DomainName;
     kind: "unknown-keys-carried";
-    keys: string[];
+    keys: ConfigPath[];
     truncatedFrom?: number;
 }
 /** 0.5 期的 runtime 文档里还带着治理三闸,而 governance 域从未被设过 —— 读侧抬升腿真生效了。
  *  `keys` = 这次抬起来的那几个键。**照旧生效,只是不再无声**:兼容窗要能关掉,前提是有人知道它还开着。
- *  1.11.0 起。 */
+ *  2.0.0 起。 */
  | {
     domain: "governance";
     kind: "legacy-governance-lifted";
-    keys: string[];
+    keys: ConfigPath[];
 }
-/** 一条**条目**没通过它自己的 entry schema,被单独丢掉了(域内其余条目照常生效)。`path` = 点号路径
- *  (`models.3` / `roles.summarize`),与 `unknown-keys-dropped` 的路径形同一套。逐条一发 —— 载荷是
+/** 一条**条目**没通过它自己的 entry schema,被单独丢掉了(域内其余条目照常生效)。`path` = 段坐标
+ *  (`["models",3]` / `["roles","summarize"]`),与 `unknown-keys-dropped` 的坐标形同一套。逐条一发 —— 载荷是
  *  O(域里的条目数),与被读文档同阶,不放大,故不设条数上限(有上限的是**单条**告警里的键列表)。
- *  1.11.0 起;只可能来自 {@link DOMAIN_READ_FALLBACK} 判 `"default"` 的域,gate 域坏形仍然 throw。 */
+ *  2.0.0 起;只可能来自 {@link DOMAIN_READ_FALLBACK} 判 `"default"` 的域,gate 域坏形仍然 throw。 */
  | {
     domain: DomainName;
     kind: "entry-dropped";
-    path: string;
+    path: ConfigPath;
     error: unknown;
 }
 /** `config.d/` 里存在、但本地读取集**永远不会读**的文件(名字不是域,或是域但不便携)。 */
@@ -277,8 +297,8 @@ export type EffectiveReadWarning = {
     why: "not-a-domain" | "non-portable-domain";
 };
 /**
- * 一条告警里的**点号路径**从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,{@link EntryKeptIndex}
- * 是它唯一的坐标账。
+ * 一条告警里的**段坐标**({@link ConfigPath})从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,
+ * {@link EntryKeptIndex} 是它唯一的坐标账。
  *
  * 成案(S-323,消费方真案):整域 parse 失败后 {@link salvageEntries} 会把坏条目从数组里剔掉,之后的
  * 诊断({@link droppedKeys} / {@link carriedUnknownKeys})是拿**压缩后**的文档做键集对比出来的,它报的
@@ -309,25 +329,37 @@ export declare function rebaseWarningPaths(w: EffectiveReadWarning, keptIndex: E
  * 满额特判,四层各被下一轮复审打穿)。意图只能在**声明处**说清:写者在这里登记自己的命名空间,之后
  * 所有未被登记的未知键都是拼错,消费方一条规则:未知键 = 错误,零特例。
  *
- * 登记形(分段):`at` = 父路径正则(点号形含尾点,顶层 `""`,首尾锚定,test 有门)+ `key` = 键名前缀正则;`owner` = 写者;
+ * 登记形(分段):`at` = 父路径的**段模式**({@link ConfigPath} 的形加一个通配哨兵 {@link ANY_INDEX} =
+ * 任一数组下标,顶层 = `[]`;逐段全等,天然闭合——没有正则可以锚歪,test 有门)+ `key` = 键名前缀正则;
+ * `owner` = 写者;
  * `since` = 契约出处。新写者/新层级来这里加行,并在 CHANGELOG 点名——这是 additive(minor)。
  *
  *  · `models` 条目级 `sema[A-Z]…`:壳(cli)的自留字段族(`semaChannel`/`semaLabel`/`semaProbe`/`semaProbeAt`/
  *    `semaEffortDefault`/`semaVision`,壳侧 models.json 实键清单 design/cli-190c:「`sema` 前缀是壳侧自留字段的既定
  *    约定」,**全条目级、顶层零装饰键**)。顶层 `sema*` 不在此列 ⇒ 仍是未知键(拼错或越界)。
  */
-export declare const EXTENSION_NAMESPACES: Partial<Record<DomainName, ReadonlyArray<{
-    readonly at: RegExp;
+/** {@link EXTENSION_NAMESPACES} 段模式里的**通配段**:匹配任一数组下标。
+ *
+ *  刻意是 `unique symbol` 而不是一个约定字符串(如 `"#"`):文档键只可能是 `string | number`
+ *  ({@link ConfigPath} 的值域),所以哨兵**不可能**与任何文档键相等 —— 通配与字面「一个叫 `#` 的键」
+ *  这两件事零二义,而且字面 `"#"` 仍然是一个可登记的普通段。类型上也不塌:`readonly (string | "#")[]`
+ *  会被 TS 收成 `readonly string[]`(写错通配不编译红),`readonly (string | typeof ANY_INDEX)[]` 不会。 */
+export declare const ANY_INDEX: unique symbol;
+/** {@link EXTENSION_NAMESPACES} 的一条登记:父路径段模式 + 键名前缀 + 写者 + 契约出处。 */
+export interface ExtensionNamespaceRule {
+    readonly at: readonly (string | typeof ANY_INDEX)[];
     readonly key: RegExp;
     readonly owner: string;
     readonly since: string;
-}>>>;
-/** 该键是否落在 {@link EXTENSION_NAMESPACES} 登记的扩展命名空间里(⇒ 不是未知键)。**分段匹配**:`at` 对父路径(点号形,含尾点;
- *  顶层 = `""`),`key` 对键名本身——不在拼好的点号路径上猜(键名里可以含 `.`,`semaX.foo` 是一个键不是两层),前缀契约就是
- *  前缀契约(`semaGPT_5` / `semaX-v2` 都是成员,后缀不设未声明的文法)。 */
-export declare function isReservedExtensionKey(domain: DomainName, parentPath: string, key: string): boolean;
+}
+export declare const EXTENSION_NAMESPACES: Partial<Record<DomainName, ReadonlyArray<ExtensionNamespaceRule>>>;
+/** 该键是否落在 {@link EXTENSION_NAMESPACES} 登记的扩展命名空间里(⇒ 不是未知键)。**分段匹配**:`at` 对
+ *  父路径的段(长度相等 ∧ 逐段——{@link ANY_INDEX} 匹配任一**数字**段,字符串段逐字相等;顶层 = `[]`),`key` 对键名
+ *  本身——键名里可以含 `.`(`semaX.foo` 是一个键不是两层),段形让这件事不必再靠文法猜;前缀契约就是前缀
+ *  契约(`semaGPT_5` / `semaX-v2` 都是成员,后缀不设未声明的文法)。 */
+export declare function isReservedExtensionKey(domain: DomainName, parent: ConfigPath, key: string): boolean;
 /**
- * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
+ * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),段坐标形({@link ConfigPath})。
  *
  * 成案(消费方 #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
  * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
@@ -346,15 +378,15 @@ export declare function isReservedExtensionKey(domain: DomainName, parentPath: s
  * JSON 对象——raw 若是类实例/Proxy 这类形状不扫;④ 读 raw 的值可能触发访问器,整段包 try/catch 且**绝不**
  * 让其错误外泄(错误文案可能带 secret,与 parseDomain 的 R13 同纪律),扫描失败即当作"没看见",不影响解析。
  */
-export declare function droppedKeys(domain: DomainName, raw: unknown, parsed: unknown): string[];
+export declare function droppedKeys(domain: DomainName, raw: unknown, parsed: unknown): ConfigPath[];
 /**
- * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(点号路径)。非 open-world 域恒空
+ * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(段坐标)。非 open-world 域恒空
  * (它们的未知键走 {@link droppedKeys} 那条更重的「被丢了」告警)。
  *
  * 边界(如实):只看 {@link OPEN_WORLD_KNOWN_KEYS} 登记了的层级 —— 未登记层级(如某个未知键自己的
  * 子树)不再下探,那本就是消费方自定义的内容,逐层猜没有意义。
  */
-export declare function carriedUnknownKeys(domain: DomainName, parsed: unknown): string[];
+export declare function carriedUnknownKeys(domain: DomainName, parsed: unknown): ConfigPath[];
 /**
  * 一域的 parse + **静默剥键/静默承运两条告警**(0.19.0)。`buildEffective` 与 `FileConfigStore.getDomain`
  * 共用这一个判据 —— 此前只有 effective 那条路径有门,而 `getDomain` 是 `exportBundle` 的读法
@@ -427,7 +459,7 @@ export interface GrandfatherHostsReadResult {
  *  everything else (regex, types, duplicates) is left for parseDomain — this is a targeted grandfather, not a
  *  lenient parser. PURE + idempotent; returns the ORIGINAL reference when nothing exceeds the bounds.
  *
- *  SUNSET (1.11.0): same persistent-data class as the governance lift — it goes at the next MAJOR. This one was
+ *  SUNSET (2.0.0): same persistent-data class as the governance lift — it goes at the next MAJOR. This one was
  *  never silent (`hosts-grandfathered` fires whenever it clamps), so the closing condition is already
  *  observable: a deployment that has not seen that warning across a full read cycle no longer needs the arm. */
 export declare function grandfatherHostsRead(raw: unknown): GrandfatherHostsReadResult;