@sema-agent/settings-schema 8.3.1 → 9.0.0

package/CHANGELOG.md

@@ -6,6 +6,68 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 9.0.0 — 2026-10-09 — 能力读数三态读器 · 世代账两键由串改数(BREAKING)
+
+> **判档 = major**(README「发版纪律」:导出删除 / 改名、类型 retype ⇒ major)。**硬 breaking:删改直接做,零别名,消费方 tsc 红即通知。** 两件:
+> ① `readCenterCapabilities` 删,换 `readCapabilityReading` + `CapabilityReading`;② `EngineSignal.configTargetVersion` / `configAppliedVersion` 的类型由 `string` 改 `number`。
+> 导出面登记表:`.` 与 `./fleet` 各 **−1**(`readCenterCapabilities`)**+2**(`readCapabilityReading` 值、`CapabilityReading` 类型),无改形。已知的消费方只有引擎侧(server)。
+
+### 一、能力读数三态读器:`readCapabilityReading(reply): CapabilityReading`(替掉 `readCenterCapabilities`)
+
+**病**:`capabilities` 键在场但形坏(例:`{ servingLease: "true" }`、`null`),`readCenterCapabilities` 回 `undefined`;而 `undefined` 在引擎侧的读法是「中心没宣告」⇒ 引擎撤围栏。
+围栏这条轴上,「形坏」不许等于「缺席」—— 一份读不出的宣告可能是中心正在宣告租约,引擎却据此放掉了围栏。
+
+**改**:读器吃心跳 **2xx 的整只答复体**(键查找进读器 —— 一只载体一只读器;不再让调用方自己取 `reply.capabilities`),答闭集三态:
+
+- `{ kind: "declared"; capabilities: CenterCapabilities }` —— 键在场且过 `CenterCapabilities` schema(未知位被剥,缺席的位保持缺席;`{}` 也是 declared:宣告了、没有这一位);
+- `{ kind: "undeclared" }` —— 体是对象、键缺席 = 老中心,什么都没说(键的值是 `undefined` 这种 JSON 载不了的形,读成键缺席);
+- `{ kind: "unreadable"; why: "not-an-object" | "invalid-capabilities" }` —— 体不是对象(`null` / 数组 / 串 / 数 / 布尔 / `undefined`),或键在场但 schema 拒(含键上的 accessor 抛)。
+
+**引擎侧契约(写进读器头注)**:只有 `declared` / `undeclared` 是读数;**`unreadable` 不是读数** —— 引擎当作没有这一拍答复:保留上一次状态(没有过读数前 = 无租约),
+租约到期钟与不可达容忍钟照旧走,不因它启动、停止或延长任何东西。同步改真的注:`LEASE_STATES` 的 `none` 句(不再把「读不出」并进没宣告)、`CenterCapabilities` 头注(「读不出」不再算缺席)、
+`HEARTBEAT_REPLY_CAPABILITIES_KEY` 头注(「没有键 = 老中心」保留;补「键在场而形坏 ≠ 没宣告,是 unreadable」)。旧读器的头注随它删除。
+
+内部:`readSignalBody`(各 `read*` 共用的受保护读口)拆出同一个判决核心 `judgeSignalBody`,多答「为什么不是读数」(`not-an-object` / `invalid`);`readSignalBody` 是它的「读到或 `undefined`」面,
+其余读器一字不变。仍是**一只** `safeParse`、**一只** `catch`(8.1.0 的单点钉不动)。
+
+### 二、世代账两键由串改数:`EngineSignal.configTargetVersion` / `configAppliedVersion`
+
+`z.string().min(1)` ⇒ **有限数**(与 `RestartSignal.version` 是同一个量、同一条规则,在 `fleet.ts` 里定义一次,内部常量 `ConfigVersion`,不导出)。理由:引擎 `/health` 铸的就是 number 世代账;
+8.2.0 起头注就写着「引擎写成数、本形类型为串」并留给下一个 major —— 这里兑现,头注里的「types them as strings」「opaque strings」两句随之删掉,出口方言由三条减为两条
+(布尔 `draining`、就绪时 `/health` 不带 `ready`)。
+
+读数变化:带**数形**世代账的 `/health` 体,补上 `ready` 后 `readEngineSignal` 现在读得出(以前恒 `undefined`);带**串形**世代账的体现在读成 `undefined`(整只信号拒,不拿剩下的充数);
+`NaN` / `±Infinity` 拒(JSON 本来也载不了)。`InstanceAnnouncement` 一直不收这两键(strip),未动。
+
+### 用户可见变化(谁受影响 / 怎么改 / 不改会怎样)
+
+1. **引擎侧租约客户端(server)**:调 `readCenterCapabilities` 的 ⇒ tsc 红(没有这个导出了)。迁移一句:
+   `readCenterCapabilities(reply.capabilities)?.servingLease` ⇒ `const r = readCapabilityReading(reply); r.kind === "declared" && r.capabilities.servingLease`;
+   并对 `unreadable` 按契约不动状态与钟(旧代码里它与 `undeclared` 是同一个 `undefined`,所以以前会撤围栏)。对 `r.kind` 做 `switch` 时加 `default: never` 臂,以后加态编译会红。
+2. **读 `EngineSignal.configTargetVersion` / `configAppliedVersion` 的**:类型由 `string | undefined` 变 `number | undefined` ⇒ 把它当串用的 tsc 红;按数比较 / 展示即可(「equal ⇔ converged」不变)。
+   拿 `readEngineSignal` 读带串形世代账的体的,现在得 `undefined`。
+3. **其它消费方**(管理面 / sdk / 只用 schema 与读写 helper 的):零变化 —— 据发版方核对,它们没有这两处的读点。
+4. **持有导出面快照的测试 / 脚本**:`readCenterCapabilities` 行删,`readCapabilityReading`(值)与 `CapabilityReading`(类型)两行加。
+
+### 红先 / 门
+
+- 先写钉、对着改前的树跑红,再实现:`test/fleet-9.0.0.test.ts` 24 格(三态各一格 + 老中心 `{ ok: true }` ⇒ `undeclared`、`{ capabilities: { servingLease: "true" } }` ⇒ `unreadable` / `invalid-capabilities`、
+  `null` / `[]` / 串 ⇒ `unreadable` / `not-an-object`、`{ capabilities: { servingLease: true, extra: 1 } }` 按 `CenterCapabilities` 现行宽严(未知位被剥)⇒ `declared`;敌意 accessor / Proxy 不抛;
+  穷举 `switch` 编译钉;旧读器从两个入口都删;五处注释文本钉;世代账两键:数收、串 / 空串 / 非有限 / 空值拒,类型面,金样 `/health` 体,与 `RestartSignal.version` 同判,头注两句已删)⇒ 写钉时对改前的树 23 格里 21 红 2 绿
+  (2 绿是不依赖新读器的反向格),随后补一格(键的值是 `undefined` 读成键缺席);实装后 24 格全绿。
+- 既有钉随之改真:`test/engine-signal-8.1.0.test.ts`(世代账夹具与类型面改数;「形坏读成 `undefined`,读方等同缺席」那格翻成 `unreadable`,不再等同缺席;读器三格改用新读器)、
+  `test/fleet-8.2.0.test.ts`(能力位金样改读整只答复体;「补上 ready 也仍因数形的世代账读不出」那格翻成读得出)。
+- 变异自证(九个,每个都使预期那几格红):无效声明读成 `undeclared`(旧病)/ 非对象读成 `undeclared` / 载体不过 schema / `ConfigVersion` 丢 `.finite()` /
+  `configTargetVersion` 退回串 / 读器头注删「`unreadable` 不是读数」句 / 键缺席读成 `unreadable` / 旧读器别名回来 / `EngineSignal` 头注留着「types them as strings」。全量读数见发版链(本节不复述会过期的数)。
+- 导出面登记表(`docs/API-SURFACE.md`)重生成:`.` 与 `./fleet` 各 −1 +2。
+
+### 未闭环(如实)
+
+- **引擎对 `unreadable` 的处置是契约不是本包能判的**:「保留上一次状态与钟」写在读器头注里,本包没有取引擎源码的通道,没有机器门看引擎是否照做。
+- **`EngineSignal` 仍未被任何出口整只承载**:心跳的布尔 `draining`、`/health` 就绪时不带 `ready`,以及 `isReadyForTraffic` / `isRoutable` 仍吃布尔方言 —— 头注与 8.2.0 起都写「下一个 major」收;
+  本版只兑现了世代账两键,这几件仍待下一个 major。`InstanceHealth` 的 `restart` 仍未入形(同样留给下一个 major)。
+- **读器不判中心与引擎的凭证对应**:`declared` 里的位按调用方凭证答(共享令牌看不到 `servingLease`)是中心的事,本读器只读答复体里有什么。
+
 ## 8.3.1 — 2026-10-08 — FLEET_SCOPE_ENV 注改真(patch)
 
 > **判档 = patch**(README「发版纪律」:文案 / 注释 = patch)。只改 `src/fleet.ts` 里 `FLEET_SCOPE_ENV` 的头注(它随 `.d.ts` 发出);常量值不变,导出面登记表零 diff,零运行期行为,

package/README.md

@@ -48,6 +48,21 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 > a zod-3 host (today the config-center product) still dedups to one instance. Moving this package to zod 4 is a major
 > of its own (S-777); 6.2.0 does not touch the dependency or peer range.
 
+## 升级指引:8.3.1 → 9.0.0(BREAKING:两件,硬 breaking —— 删改直接做,零别名)
+
+**① 能力读数改三态读器**:`readCenterCapabilities(body)` 删,换 `readCapabilityReading(reply): CapabilityReading`(类型 `CapabilityReading` 同入)。输入改成心跳 **2xx 的整只答复体**(键查找进读器),
+答三态:`{ kind: "declared"; capabilities }`(`capabilities` 键在场且过 schema)· `{ kind: "undeclared" }`(体是对象、键缺席 = 老中心)·
+`{ kind: "unreadable"; why: "not-an-object" | "invalid-capabilities" }`(体不是对象 / 键在场但 schema 拒)。**只有 `declared` / `undeclared` 是读数;`unreadable` 不是读数 —— 引擎保留上一次状态与钟。**
+
+- **谁需要**:引擎侧的租约客户端(server)—— 围栏这条轴上「形坏」不许等于「缺席」:以前 `capabilities` 键在场但形坏读成 `undefined` = 「没宣告」,引擎据此撤围栏。
+- **谁受伤**:调 `readCenterCapabilities` 的(tsc 红:没有这个导出了)。其它消费方(管理面 / sdk)据发版方核对没有读点。
+- **迁移一句**:`readCenterCapabilities(reply.capabilities)?.servingLease` ⇒ `const r = readCapabilityReading(reply); r.kind === "declared" && r.capabilities.servingLease`;
+  并对 `unreadable` 按契约不动状态与钟(旧代码里它和 `undeclared` 是同一个 `undefined`)。
+
+**② `EngineSignal.configTargetVersion` / `configAppliedVersion` 由串改数**(有限数,与 `RestartSignal.version` 同一条规则):引擎 `/health` 铸的就是 number 世代账。
+- **谁受伤**:把这两键当 `string` 用的(tsc 红);拿 `readEngineSignal` 读带串形世代账的体的(现在读成 `undefined`)。反过来,以前因数形世代账而读不出的 `/health` 体(补上 `ready` 后)现在读得出。
+- **补偿**:按数用即可,没有别的动作。逐条见 CHANGELOG 9.0.0。
+
 ## 升级指引:8.3.0 → 8.3.1(注释改真,零动作可升)
 
 `FLEET_SCOPE_ENV` 的头注改真:引擎读这只 env 只用来比对 `DrainRequest.scope`;续租体与心跳的 scope 由凭证定、不取这只 env。导出面与行为零变化,逐条见 CHANGELOG 8.3.1。
@@ -91,12 +106,12 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 - `RestartSignal.withheld?` —— 可选布尔,引擎自判「这一拍不该被换代」;缺席 = `false`,读出形不铸键。
 - `EngineSignal`(+ `EngineDraining`)与 `readEngineSignal(health)` —— 引擎自铸信号的**闭形**(`ready` 必填,`draining?` / `restart?` / `generation?` / `instanceId?` /
   `leaseUntil?` / `configTargetVersion?` / `configAppliedVersion?` 可选);与既有读器走同一只受保护读口。⚠️ 8.2.0 订正:今天的心跳与 `/health` 都不整只
-  承载它(心跳恒带布尔 `draining`、`/health` 就绪时不带 `ready`、世代账两键是数),`readEngineSignal` 对今天的心跳体恒 `undefined` —— 见 8.2.0 升级指引。
+  承载它(心跳恒带布尔 `draining`、`/health` 就绪时不带 `ready`、世代账两键是数),`readEngineSignal` 对今天的心跳体恒 `undefined` —— 见 8.2.0 升级指引(9.0.0 起这两键在 `EngineSignal` 里就是数,不再是读不出的原因)。
   `undefined` = 没有这只信号,**不是就绪**;布尔 `draining` 的旧方言体读不出它(两个就绪谓词的输入仍是布尔方言,下一个 major 收)。
 - 代际 —— `generation` 是非负整数的**规范十进制串**(`"7"`,不是 `"07"`、不是数字型),判别器 `isCanonicalGeneration`、数值比较 `compareGeneration`;三处 wire 形共用这一条判据。
 - 服务租约 API 型 —— `ServingLeaseRequest`、`ServingLeaseResponse`(`granted { ttlMs }` / `denied { reason: superseded | retired }` / `unknown` 三词闭集,
   **`unknown` 不是 `denied` 的一种**,`denied` 只凭正面证据;读器按 `verdict` 键判,`denied` 的原因词读不出时仍是 `denied`,原因读成 `unknown_reason`)、`SERVING_LEASE_TTL_DEFAULT_MS` / `SERVING_LEASE_TTL_FLOOR_MS` / `SERVING_LEASE_DRIFT_MARGIN_MS`、读器 `readServingLeaseRequest` / `readServingLeaseResponse`;
-  中心能力位 `CenterCapabilities { servingLease?: true }` + `readCenterCapabilities` —— 租约客户端只在位在场时启用,缺席 = 中心不支持租约(不续租、不围栏)。
+  中心能力位 `CenterCapabilities { servingLease?: true }` + `readCenterCapabilities`(9.0.0 起删,由 `readCapabilityReading` 取代,见 9.0.0 升级指引)—— 租约客户端只在位在场时启用,缺席 = 中心不支持租约(不续租、不围栏)。
 - 排空口型 —— `DrainRequest`、`DrainReceipt`(`state: draining | already_draining`)、读器 `readDrainRequest` / `readDrainReceipt`。
 - `FLEET_GENERATION_ENV` —— 配置渲染器与引擎共用的 generation env 名常量(实例身份 `instanceId` 由引擎每进程自铸,没有 env 名);它同时进了 `RESERVED_WORKER_ENV`,`worker.env` / `secretEnv` 设不了它。
 - `clampServingLeaseTtlMs(n)` —— 配置的租约 TTL 的唯一夹取点(读不出 ⇒ 缺省 600 000;低于地板 ⇒ 60 000;无上限)。
@@ -354,6 +369,8 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   the center's capability bits: `HEARTBEAT_REPLY_CAPABILITIES_KEY` (`"capabilities"`) on the heartbeat's 2xx reply.
   **8.3.0** (additive) adds the env name `FLEET_SCOPE_ENV` (`"FLEET_SCOPE"`) — the tenant scope a fleet member belongs to, set by the
   config renderer and read by the engine as its own identity's scope (absent ⇒ `GLOBAL_SCOPE`); a reserved worker env name.
+  **9.0.0** (BREAKING) replaces `readCenterCapabilities` with the three-state reader `readCapabilityReading(reply)` (`declared` |
+  `undeclared` | `unreadable` — a malformed declaration is not an absent one) and types `EngineSignal`'s two config-version keys as numbers.
 - **Declared-but-unvalidated keys** (`PARSE_TRANSPARENT_KEYS`, 2.0.0): the ONE registry of keys this package
   carries verbatim WITHOUT checking their shape, each row naming who does check it (the engine's ingest side or
   a consumer's enforcement point). Today: `models[].compat` (1.10.0), `models[].headers` (6.4.0; the header-name

package/conformance/VERSION

@@ -1 +1 @@
-8.3.1
+9.0.0

package/dist/fleet.d.ts

@@ -90,8 +90,10 @@ export declare function compareGeneration(a: string, b: string): -1 | 0 | 1;
 /**
  * The serving lease as the ENGINE holds it — a CLOSED set of four words, owned here (the engine's vocabulary, word for word;
  * a reader that switches on it exhaustively is told by the compiler when a word is added):
- *  - `none` — the lease is not in effect: the center has not announced {@link CenterCapabilities}`.servingLease` (an older or
- *    degraded center). The engine behaves exactly as an engine without a lease — no renewals, no fence.
+ *  - `none` — the lease is not in effect: the center has declared no {@link CenterCapabilities}`.servingLease` ({@link readCapabilityReading}
+ *    says `undeclared` — an older center — or `declared` without the bit). The engine behaves exactly as an engine without a lease —
+ *    no renewals, no fence. A reply that cannot be read (`unreadable`) is not a reading: it does not move the engine into or out of
+ *    `none` — it keeps the state it had.
  *  - `granted` — the engine holds a lease; `leaseUntil` says until when (epoch ms, the engine's own computation from the
  *    granted `ttlMs`, see {@link ServingLeaseResponse}).
  *  - `expired` — the lease is in effect but no grant is valid right now (the center is unreachable, answered `unknown`, or has
@@ -118,7 +120,8 @@ export type LeaseState = z.infer<typeof LeaseState>;
  *    the contract only guarantees non-empty words, at least one).
  *  - `version` — the config-center version that currently differs from boot (the LATEST seen — it moves forward with
  *    later publishes, so a "one restart per version" dedupe bounds restarts per config version, not per reason set).
- *    Judged exactly as `readEffectiveWire` judges a config version (a finite number) — one quantity, one rule.
+ *    Judged exactly as `readEffectiveWire` judges a config version (a finite number, `ConfigVersion`) — one quantity, one rule;
+ *    {@link EngineSignal}'s two version-ledger keys use the same one.
  *  - `since` — epoch ms when this restart first became required (stable across refreshes while `reasons` holds).
  *  - `withheld` — optional: the ENGINE's own verdict that this beat must not be handed to a new generation ("a restart is
  *    required, but replacing this instance right now would lose state it holds"). Absent ≡ `false` — an explicit `false`
@@ -584,13 +587,12 @@ export type EngineDraining = z.infer<typeof EngineDraining>;
  * this shape off a body whose keys sit flat on it (no wrapper key).
  *
  * Where it rides today: on NEITHER exit whole. The heartbeat ({@link InstanceAnnouncement}) and `/health` ({@link InstanceHealth})
- * still speak the 8.0 dialect for the keys they share with this shape, in three ways:
+ * still speak the 8.0 dialect for the keys they share with this shape, in two ways:
  *  1. `draining` is a BOOLEAN there, not the {@link EngineDraining} object. The heartbeat always carries it (`false` included);
  *     `/health` carries `draining: true` only while draining.
  *  2. `/health` carries `ready` only while NOT ready (`ready: false`); a ready engine's `/health` body has no `ready` key.
- *  3. The engine writes `configTargetVersion` / `configAppliedVersion` as numbers; this shape types them as strings.
  * So `readEngineSignal` over a heartbeat body is always `undefined` (point 1), and over a `/health` body it is `undefined` whenever
- * any of the three applies. What does ride both exits flat, under these names and with these values: `restart`, `instanceId`
+ * either applies. What does ride both exits flat, under these names and with these values: `restart`, `instanceId`
  * and the fleet-membership keys `generation` / `leaseState` / `leaseUntil` — on the heartbeat, read them off the parsed
  * {@link InstanceAnnouncement} (which types all five). The next major retires the boolean pair (`draining` / `drainingSince`),
  * has both exits carry this shape whole and moves {@link isReadyForTraffic} / {@link isRoutable} onto it; until then this is
@@ -612,7 +614,7 @@ export type EngineDraining = z.infer<typeof EngineDraining>;
  *  - `leaseUntil` — epoch ms until which the engine holds its serving lease, as the engine computed it from the last
  *    `ttlMs` it was granted ({@link ServingLeaseResponse}); present ⇔ `leaseState` is `granted`.
  *  - `configTargetVersion` / `configAppliedVersion` — the config-center version the engine was told to converge on, and the
- *    one it has applied (opaque strings; equal ⇔ converged).
+ *    one it has applied: numbers, as the engine mints them (finite, the same rule as {@link RestartSignal}`.version`; equal ⇔ converged).
  *
  * Reading: `EngineSignal` is parsed with the default strip — a whole /health body goes in, only these keys come out. A
  * shape violation in ANY key makes the whole signal `undefined` (it is never "the rest of it"). `undefined` means "no
@@ -655,8 +657,8 @@ export declare const EngineSignal: z.ZodObject<{
     instanceId: z.ZodOptional<z.ZodString>;
     leaseState: z.ZodOptional<z.ZodEnum<["none", "granted", "expired", "denied"]>>;
     leaseUntil: z.ZodOptional<z.ZodNumber>;
-    configTargetVersion: z.ZodOptional<z.ZodString>;
-    configAppliedVersion: z.ZodOptional<z.ZodString>;
+    configTargetVersion: z.ZodOptional<z.ZodNumber>;
+    configAppliedVersion: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     ready: boolean;
     draining?: {
@@ -674,8 +676,8 @@ export declare const EngineSignal: z.ZodObject<{
     generation?: string | undefined;
     leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
     leaseUntil?: number | undefined;
-    configTargetVersion?: string | undefined;
-    configAppliedVersion?: string | undefined;
+    configTargetVersion?: number | undefined;
+    configAppliedVersion?: number | undefined;
 }, {
     ready: boolean;
     draining?: {
@@ -693,8 +695,8 @@ export declare const EngineSignal: z.ZodObject<{
     generation?: string | undefined;
     leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
     leaseUntil?: number | undefined;
-    configTargetVersion?: string | undefined;
-    configAppliedVersion?: string | undefined;
+    configTargetVersion?: number | undefined;
+    configAppliedVersion?: number | undefined;
 }>;
 export type EngineSignal = z.infer<typeof EngineSignal>;
 /**
@@ -881,13 +883,15 @@ export declare function readServingLeaseResponse(body: unknown): ServingLeaseRea
  * What the CENTER says it can do: capability bits an engine reads before it starts using a center-side endpoint.
  *  - `servingLease` — the center answers serving-lease renewals ({@link ServingLeaseRequest} / {@link ServingLeaseResponse}).
  *
- * A bit is `true` or absent — one spelling for "not supported" (there is no `false`). Absent (an older center, a body without
- * the key, a body that cannot be read) means the center does not support the lease, and the engine then neither renews a
- * lease nor is fenced by one: this is the compatibility gate that lets an executor ship ahead of the center without pushing
- * running engines into lease expiry. It is a gate, not a verdict — nothing in this shape says "the center refuses leases".
- * A reader asks `readCenterCapabilities(body)?.servingLease === true` and starts the lease client only on that.
- * Unknown bits are stripped (a newer center's extra bits never break an older reader); a known bit whose value is not `true`
- * makes the whole read `undefined`, which reads exactly as absent.
+ * A bit is `true` or absent — one spelling for "not supported" (there is no `false`). An absent bit — in a declared object, or
+ * because the center declares nothing at all (an older center) — means the center does not support the lease, and the engine then
+ * neither renews a lease nor is fenced by one: this is the compatibility gate that lets an executor ship ahead of the center
+ * without pushing running engines into lease expiry. It is a gate, not a verdict — nothing in this shape says "the center refuses
+ * leases". Read a heartbeat reply with {@link readCapabilityReading} and start the lease client only on a `declared` reading whose
+ * `capabilities.servingLease === true`.
+ * Unknown bits are stripped (a newer center's extra bits never break an older reader); a known bit whose value is not `true` breaks
+ * the declaration — and a broken declaration is NOT an absent one: the reply reads as `unreadable`, which is not a reading (the engine
+ * keeps the state it had; see {@link readCapabilityReading}).
  * It rides in ONE place: the heartbeat's 2xx reply ({@link FLEET_PATHS}`.instances`), under {@link HEARTBEAT_REPLY_CAPABILITIES_KEY}.
  * The center answers the bits per CALLER CREDENTIAL: under a per-worker token, by what the center supports; under the shared token
  * `servingLease` is always absent (the serving-lease endpoint takes per-worker tokens only, so announcing it there would only push
@@ -903,15 +907,39 @@ export declare const CenterCapabilities: z.ZodObject<{
 export type CenterCapabilities = z.infer<typeof CenterCapabilities>;
 /**
  * The key of the heartbeat's 2xx reply body under which the center puts its {@link CenterCapabilities} — the object's only carrier.
- * The center writes `{ …, [HEARTBEAT_REPLY_CAPABILITIES_KEY]: caps }`; the engine reads
- * `readCenterCapabilities(reply[HEARTBEAT_REPLY_CAPABILITIES_KEY])`, and only on a 2xx (a failed heartbeat says nothing about the
- * bits). Nested, not flat: the reply's own keys and the capability bits never share a namespace. A reply without the key is an
- * older center — no capability said.
+ * The center writes `{ …, [HEARTBEAT_REPLY_CAPABILITIES_KEY]: caps }`; the engine reads the whole reply with
+ * `readCapabilityReading(reply)` — the key lookup lives in the reader, one carrier one reader — and only on a 2xx (a failed heartbeat
+ * says nothing about the bits). Nested, not flat: the reply's own keys and the capability bits never share a namespace.
+ * A reply without the key is an older center — no capability said (`undeclared`). A reply with the key present with a value that
+ * breaks the shape is NOT "without the key" — it is `unreadable`, and an unreadable reply says nothing: neither declared nor undeclared.
  */
 export declare const HEARTBEAT_REPLY_CAPABILITIES_KEY = "capabilities";
-/** Engine side: the center's capability object. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws
- *  (and `undefined` means "no capability said" — the same as every bit absent). */
-export declare function readCenterCapabilities(body: unknown): CenterCapabilities | undefined;
+/** What one heartbeat reply says about the center's capabilities — three readings of the reply, see {@link readCapabilityReading}. */
+export type CapabilityReading = {
+    kind: "declared";
+    capabilities: CenterCapabilities;
+} | {
+    kind: "undeclared";
+} | {
+    kind: "unreadable";
+    why: "not-an-object" | "invalid-capabilities";
+};
+/**
+ * Engine side: what one heartbeat reply says about the center's capabilities. The input is the heartbeat's whole 2xx reply body
+ * (the key lookup lives here — one carrier, one reader), the output one of three readings:
+ *  - `declared` — the key ({@link HEARTBEAT_REPLY_CAPABILITIES_KEY}) is present and its value passes {@link CenterCapabilities};
+ *    `capabilities` is the parsed object (unknown bits stripped, an absent bit stays absent).
+ *  - `undeclared` — the reply is an object and the key is absent: an older center, which has said nothing about capabilities.
+ *    (`undefined` as the key's value is what JSON cannot carry; it reads as the key being absent.)
+ *  - `unreadable` — the reply is not an object (`why: "not-an-object"`), or the key is present but its value is not a
+ *    {@link CenterCapabilities} (`why: "invalid-capabilities"`; an accessor that throws reads the same way).
+ * Only `declared` and `undeclared` are readings. `unreadable` is not a reading: on the fence axis a malformed declaration must not
+ * read as "the center declared nothing", so the engine acts on it as on no reply at all — it keeps the state it last had (before
+ * any reading: no lease) and leaves its clocks, the lease expiry and the outage allowance, as they were. Start the lease client only
+ * on `declared` with `capabilities.servingLease === true`. Never throws; judged by the same one guarded body judgement as every
+ * other reader here.
+ */
+export declare function readCapabilityReading(reply: unknown): CapabilityReading;
 /**
  * The drain endpoint's request: "put this instance into draining, by this deadline". One persisted action, one validation,
  * whether the center calls directly or an executor retries it. Two lanes, one shape: on the Docker lane (and for a direct

package/dist/fleet.js

@@ -79,6 +79,9 @@ export function drainVerdict(s) {
 }
 /** A wall-clock instant as epoch milliseconds — one quantity, one rule, wherever the fleet contract carries a point in time. */
 const EpochMs = z.number().int().nonnegative();
+/** A config-center version — a finite number, judged the way `readEffectiveWire` judges one. One quantity, one rule, wherever the
+ *  fleet contract carries it: {@link RestartSignal}`.version` and {@link EngineSignal}'s version-ledger keys. */
+const ConfigVersion = z.number().finite();
 /**
  * A generation is a non-negative integer written as its CANONICAL decimal string: `"0"`, `"7"`, `"10"` — no sign, no
  * leading zero (`"07"` is not a generation), no fraction, no whitespace, ASCII digits only, and a string, never a number.
@@ -110,8 +113,10 @@ const Generation = z.string().refine(isCanonicalGeneration, { message: "a genera
 /**
  * The serving lease as the ENGINE holds it — a CLOSED set of four words, owned here (the engine's vocabulary, word for word;
  * a reader that switches on it exhaustively is told by the compiler when a word is added):
- *  - `none` — the lease is not in effect: the center has not announced {@link CenterCapabilities}`.servingLease` (an older or
- *    degraded center). The engine behaves exactly as an engine without a lease — no renewals, no fence.
+ *  - `none` — the lease is not in effect: the center has declared no {@link CenterCapabilities}`.servingLease` ({@link readCapabilityReading}
+ *    says `undeclared` — an older center — or `declared` without the bit). The engine behaves exactly as an engine without a lease —
+ *    no renewals, no fence. A reply that cannot be read (`unreadable`) is not a reading: it does not move the engine into or out of
+ *    `none` — it keeps the state it had.
  *  - `granted` — the engine holds a lease; `leaseUntil` says until when (epoch ms, the engine's own computation from the
  *    granted `ttlMs`, see {@link ServingLeaseResponse}).
  *  - `expired` — the lease is in effect but no grant is valid right now (the center is unreachable, answered `unknown`, or has
@@ -137,7 +142,8 @@ export const LeaseState = z.enum(LEASE_STATES);
  *    the contract only guarantees non-empty words, at least one).
  *  - `version` — the config-center version that currently differs from boot (the LATEST seen — it moves forward with
  *    later publishes, so a "one restart per version" dedupe bounds restarts per config version, not per reason set).
- *    Judged exactly as `readEffectiveWire` judges a config version (a finite number) — one quantity, one rule.
+ *    Judged exactly as `readEffectiveWire` judges a config version (a finite number, `ConfigVersion`) — one quantity, one rule;
+ *    {@link EngineSignal}'s two version-ledger keys use the same one.
  *  - `since` — epoch ms when this restart first became required (stable across refreshes while `reasons` holds).
  *  - `withheld` — optional: the ENGINE's own verdict that this beat must not be handed to a new generation ("a restart is
  *    required, but replacing this instance right now would lose state it holds"). Absent ≡ `false` — an explicit `false`
@@ -146,29 +152,39 @@ export const LeaseState = z.enum(LEASE_STATES);
  */
 export const RestartSignal = z.object({
     reasons: z.array(z.string().min(1)).min(1),
-    version: z.number().finite(),
+    version: ConfigVersion,
     since: EpochMs,
     withheld: z.boolean().optional(),
 });
 /**
- * The ONE guarded body reader behind every wire-shape read in this file: the engine-owned signals on /health
- * ({@link readRestartSignal}, {@link readModelRefusals}, {@link readEngineSignal}) and the request / reply bodies of the
- * fleet endpoints ({@link readServingLeaseRequest}, {@link readServingLeaseResponse}, {@link readDrainRequest},
- * {@link readDrainReceipt}). `pick(body)` — one key of the body, or the body itself — is judged against that shape's one
- * schema. Shape mismatch, a non-object body, even a throwing accessor ⇒ `undefined` — never throws (a probe must not die
- * on one odd body). A second hand-written guard anywhere else in this package is the defect, not a convenience.
+ * The ONE guarded body judgement behind every wire-shape read in this file: `pick(body)` — one key of the body, or the body itself —
+ * is judged against that shape's one schema, and the verdict says WHY when it is not a read: `not-an-object` (the body is null, an
+ * array or a scalar) or `invalid` (the shape rejected it, or an accessor threw). It never throws (a probe must not die on one odd
+ * body). Almost every reader wants only "a read or nothing" and goes through {@link readSignalBody}; the one reader whose
+ * failure direction matters ({@link readCapabilityReading}) takes the reason. A second hand-written guard anywhere else in this
+ * package is the defect, not a convenience.
  */
-function readSignalBody(body, pick, schema) {
+function judgeSignalBody(body, pick, schema) {
     try {
         if (body === null || typeof body !== "object" || Array.isArray(body))
-            return undefined;
+            return { kind: "not-an-object" };
         const parsed = schema.safeParse(pick(body));
-        return parsed.success ? parsed.data : undefined;
+        return parsed.success ? { kind: "read", value: parsed.data } : { kind: "invalid" };
     }
     catch {
-        return undefined;
+        return { kind: "invalid" };
     }
 }
+/**
+ * The reader behind every wire-shape read in this file that has no use for a reason: the engine-owned signals on /health
+ * ({@link readRestartSignal}, {@link readModelRefusals}, {@link readEngineSignal}) and the request / reply bodies of the
+ * fleet endpoints ({@link readServingLeaseRequest}, {@link readServingLeaseResponse}, {@link readDrainRequest},
+ * {@link readDrainReceipt}). Shape mismatch, a non-object body, even a throwing accessor ⇒ `undefined` — never throws.
+ */
+function readSignalBody(body, pick, schema) {
+    const judged = judgeSignalBody(body, pick, schema);
+    return judged.kind === "read" ? judged.value : undefined;
+}
 /** `pick` for a shape whose keys sit flat on the body itself (as opposed to under one key of it). */
 const wholeBody = (body) => body;
 /**
@@ -410,13 +426,12 @@ export const EngineDraining = z.object({
  * this shape off a body whose keys sit flat on it (no wrapper key).
  *
  * Where it rides today: on NEITHER exit whole. The heartbeat ({@link InstanceAnnouncement}) and `/health` ({@link InstanceHealth})
- * still speak the 8.0 dialect for the keys they share with this shape, in three ways:
+ * still speak the 8.0 dialect for the keys they share with this shape, in two ways:
  *  1. `draining` is a BOOLEAN there, not the {@link EngineDraining} object. The heartbeat always carries it (`false` included);
  *     `/health` carries `draining: true` only while draining.
  *  2. `/health` carries `ready` only while NOT ready (`ready: false`); a ready engine's `/health` body has no `ready` key.
- *  3. The engine writes `configTargetVersion` / `configAppliedVersion` as numbers; this shape types them as strings.
  * So `readEngineSignal` over a heartbeat body is always `undefined` (point 1), and over a `/health` body it is `undefined` whenever
- * any of the three applies. What does ride both exits flat, under these names and with these values: `restart`, `instanceId`
+ * either applies. What does ride both exits flat, under these names and with these values: `restart`, `instanceId`
  * and the fleet-membership keys `generation` / `leaseState` / `leaseUntil` — on the heartbeat, read them off the parsed
  * {@link InstanceAnnouncement} (which types all five). The next major retires the boolean pair (`draining` / `drainingSince`),
  * has both exits carry this shape whole and moves {@link isReadyForTraffic} / {@link isRoutable} onto it; until then this is
@@ -438,7 +453,7 @@ export const EngineDraining = z.object({
  *  - `leaseUntil` — epoch ms until which the engine holds its serving lease, as the engine computed it from the last
  *    `ttlMs` it was granted ({@link ServingLeaseResponse}); present ⇔ `leaseState` is `granted`.
  *  - `configTargetVersion` / `configAppliedVersion` — the config-center version the engine was told to converge on, and the
- *    one it has applied (opaque strings; equal ⇔ converged).
+ *    one it has applied: numbers, as the engine mints them (finite, the same rule as {@link RestartSignal}`.version`; equal ⇔ converged).
  *
  * Reading: `EngineSignal` is parsed with the default strip — a whole /health body goes in, only these keys come out. A
  * shape violation in ANY key makes the whole signal `undefined` (it is never "the rest of it"). `undefined` means "no
@@ -454,8 +469,8 @@ export const EngineSignal = z.object({
     instanceId: z.string().min(1).optional(),
     leaseState: LeaseState.optional(),
     leaseUntil: EpochMs.optional(),
-    configTargetVersion: z.string().min(1).optional(),
-    configAppliedVersion: z.string().min(1).optional(),
+    configTargetVersion: ConfigVersion.optional(),
+    configAppliedVersion: ConfigVersion.optional(),
 });
 /**
  * The reader of {@link EngineSignal}: the shape's keys, flat on the given body, judged by the same guarded body reader as
@@ -592,13 +607,15 @@ export function readServingLeaseResponse(body) {
  * What the CENTER says it can do: capability bits an engine reads before it starts using a center-side endpoint.
  *  - `servingLease` — the center answers serving-lease renewals ({@link ServingLeaseRequest} / {@link ServingLeaseResponse}).
  *
- * A bit is `true` or absent — one spelling for "not supported" (there is no `false`). Absent (an older center, a body without
- * the key, a body that cannot be read) means the center does not support the lease, and the engine then neither renews a
- * lease nor is fenced by one: this is the compatibility gate that lets an executor ship ahead of the center without pushing
- * running engines into lease expiry. It is a gate, not a verdict — nothing in this shape says "the center refuses leases".
- * A reader asks `readCenterCapabilities(body)?.servingLease === true` and starts the lease client only on that.
- * Unknown bits are stripped (a newer center's extra bits never break an older reader); a known bit whose value is not `true`
- * makes the whole read `undefined`, which reads exactly as absent.
+ * A bit is `true` or absent — one spelling for "not supported" (there is no `false`). An absent bit — in a declared object, or
+ * because the center declares nothing at all (an older center) — means the center does not support the lease, and the engine then
+ * neither renews a lease nor is fenced by one: this is the compatibility gate that lets an executor ship ahead of the center
+ * without pushing running engines into lease expiry. It is a gate, not a verdict — nothing in this shape says "the center refuses
+ * leases". Read a heartbeat reply with {@link readCapabilityReading} and start the lease client only on a `declared` reading whose
+ * `capabilities.servingLease === true`.
+ * Unknown bits are stripped (a newer center's extra bits never break an older reader); a known bit whose value is not `true` breaks
+ * the declaration — and a broken declaration is NOT an absent one: the reply reads as `unreadable`, which is not a reading (the engine
+ * keeps the state it had; see {@link readCapabilityReading}).
  * It rides in ONE place: the heartbeat's 2xx reply ({@link FLEET_PATHS}`.instances`), under {@link HEARTBEAT_REPLY_CAPABILITIES_KEY}.
  * The center answers the bits per CALLER CREDENTIAL: under a per-worker token, by what the center supports; under the shared token
  * `servingLease` is always absent (the serving-lease endpoint takes per-worker tokens only, so announcing it there would only push
@@ -609,16 +626,46 @@ export const CenterCapabilities = z.object({
 });
 /**
  * The key of the heartbeat's 2xx reply body under which the center puts its {@link CenterCapabilities} — the object's only carrier.
- * The center writes `{ …, [HEARTBEAT_REPLY_CAPABILITIES_KEY]: caps }`; the engine reads
- * `readCenterCapabilities(reply[HEARTBEAT_REPLY_CAPABILITIES_KEY])`, and only on a 2xx (a failed heartbeat says nothing about the
- * bits). Nested, not flat: the reply's own keys and the capability bits never share a namespace. A reply without the key is an
- * older center — no capability said.
+ * The center writes `{ …, [HEARTBEAT_REPLY_CAPABILITIES_KEY]: caps }`; the engine reads the whole reply with
+ * `readCapabilityReading(reply)` — the key lookup lives in the reader, one carrier one reader — and only on a 2xx (a failed heartbeat
+ * says nothing about the bits). Nested, not flat: the reply's own keys and the capability bits never share a namespace.
+ * A reply without the key is an older center — no capability said (`undeclared`). A reply with the key present with a value that
+ * breaks the shape is NOT "without the key" — it is `unreadable`, and an unreadable reply says nothing: neither declared nor undeclared.
  */
 export const HEARTBEAT_REPLY_CAPABILITIES_KEY = "capabilities";
-/** Engine side: the center's capability object. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws
- *  (and `undefined` means "no capability said" — the same as every bit absent). */
-export function readCenterCapabilities(body) {
-    return readSignalBody(body, wholeBody, CenterCapabilities);
+/** The reply body as far as the capability carrier is concerned: the one key, optional, nothing else (the reply's other keys are stripped). */
+const CapabilitiesCarrier = z.object({ [HEARTBEAT_REPLY_CAPABILITIES_KEY]: CenterCapabilities.optional() });
+/**
+ * Engine side: what one heartbeat reply says about the center's capabilities. The input is the heartbeat's whole 2xx reply body
+ * (the key lookup lives here — one carrier, one reader), the output one of three readings:
+ *  - `declared` — the key ({@link HEARTBEAT_REPLY_CAPABILITIES_KEY}) is present and its value passes {@link CenterCapabilities};
+ *    `capabilities` is the parsed object (unknown bits stripped, an absent bit stays absent).
+ *  - `undeclared` — the reply is an object and the key is absent: an older center, which has said nothing about capabilities.
+ *    (`undefined` as the key's value is what JSON cannot carry; it reads as the key being absent.)
+ *  - `unreadable` — the reply is not an object (`why: "not-an-object"`), or the key is present but its value is not a
+ *    {@link CenterCapabilities} (`why: "invalid-capabilities"`; an accessor that throws reads the same way).
+ * Only `declared` and `undeclared` are readings. `unreadable` is not a reading: on the fence axis a malformed declaration must not
+ * read as "the center declared nothing", so the engine acts on it as on no reply at all — it keeps the state it last had (before
+ * any reading: no lease) and leaves its clocks, the lease expiry and the outage allowance, as they were. Start the lease client only
+ * on `declared` with `capabilities.servingLease === true`. Never throws; judged by the same one guarded body judgement as every
+ * other reader here.
+ */
+export function readCapabilityReading(reply) {
+    const judged = judgeSignalBody(reply, wholeBody, CapabilitiesCarrier);
+    switch (judged.kind) {
+        case "not-an-object":
+            return { kind: "unreadable", why: "not-an-object" };
+        case "invalid":
+            return { kind: "unreadable", why: "invalid-capabilities" };
+        case "read": {
+            const capabilities = judged.value[HEARTBEAT_REPLY_CAPABILITIES_KEY];
+            return capabilities === undefined ? { kind: "undeclared" } : { kind: "declared", capabilities };
+        }
+        default: {
+            const unhandled = judged;
+            return unhandled;
+        }
+    }
 }
 /**
  * The drain endpoint's request: "put this instance into draining, by this deadline". One persisted action, one validation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "8.3.1",
+  "version": "9.0.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",