@sema-agent/settings-schema 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -6,6 +6,90 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 8.1.0 — 2026-10-08 — 引擎自铸信号的共享型:`RestartSignal.withheld` · `EngineSignal` · 服务租约 API 型与中心能力位 · 排空请求 / 回执型 · fleet env 名常量(全部 additive)
+
+> **判档 = minor**(README「发版纪律」:新键 / 新导出 = minor)。本版只加**型与契约**,零行为:既有字段的语义、`InstanceHealth` / `InstanceAnnouncement`
+> 的形、`isReadyForTraffic` / `isRoutable` 的行为一字未动(**唯一一处校验方向的收紧**:`FLEET_GENERATION` 进保留 env 名表,见第五节——这个名字是本版才出现的,此前没有任何合法写手可被收紧,判档仍按 minor);`RestartSignal` 只多一个**可选**位(缺席 = 旧形,读出形不多铸键)。新增的是 `./fleet`
+> (与主入口)上的 27 个导出名,导出面登记表里只多名字行(合计数字随之变),无删、无改形。
+
+### 一、`RestartSignal.withheld?`(可选布尔,缺席 = false)
+
+引擎自己判定「这一拍不该被换代」(需要重启,但此刻换掉这只实例会丢它手里的状态)。它是 `restart` **里面**的限定词,不是独立信号:只在 `restart` 在场时才有。
+缺席与显式 `false` 同义;读器不替生产方铸这个键。`readRestartSignal` 原样读出,心跳 `InstanceAnnouncement.restart` 与 `/health` 两个出口仍是同一只 schema。
+金样加一格带 `withheld` 的 `/health` 体(`test/restart-signal-6.1.0.test.ts`)。
+
+### 二、`EngineSignal` + `readEngineSignal(health)`(+ `EngineDraining`)
+
+- `EngineSignal` = 引擎自铸的那一只对象:`{ ready, draining?: { actionId, since, deadlineAt }, restart?, generation?, instanceId?, leaseUntil?, configTargetVersion?, configAppliedVersion? }`。
+  心跳与 `/health` 携带**同名键、同值**,键**平铺**在体上(没有包装键)。`restart` 引的就是 `RestartSignal` 那一只 schema,`draining` 的三键同时是排空回执的三键(`EngineDraining`)。
+  `generation` 是配置渲染器所设 env 的回声(缺席 ⇔ 非 fleet 成员),**规范十进制串**(见下条);**`instanceId` 是引擎每进程自铸的身份**,不读 env(同一个 Deployment 的副本共用一份 env、容器重启复用 env,env 给不了进程身份),
+  单机引擎上也在场——只有 `generation` 标记 fleet 成员。
+- **与 `InstanceHealth` 的关系**:`InstanceHealth` 是 `/health` 的自描述(开放记录,`.passthrough()`,也装宿主自己加的 build / pid / port / 存储姿态);`EngineSignal` 是其中**引擎自铸**那一子集的**闭形**。
+  读时走默认 strip——整份 `/health` 体进去,只出这八个键。任一键形坏 ⇒ 整只信号 `undefined`(不拿剩下的充数)。
+- **读口只有一只**:`readEngineSignal` 与 `readRestartSignal` / `readModelRefusals` 同走一个私有的受保护读口(原先只服务 `/health` 单键的那只,本版把「取哪个键」参数化、改名 `readSignalBody`;
+  行为不变)。同一份敌意输入,三个读器同一个结局。
+- **方言**:`draining` 在 `InstanceHealth` / `InstanceAnnouncement` 上是**布尔**(8.0 方言,本版不动),在 `EngineSignal` 上是**对象**。布尔 `draining` 的体读不出 `EngineSignal`(`undefined`);
+  `undefined` 是「没有这只信号」,**永远不是「就绪」**——路由轴上的调用方应把它当不可路由,除非有意回落到布尔方言。
+  `isReadyForTraffic` / `isRoutable` 的输入留在布尔方言(`EngineSignal` 过不了它们的类型,这是故意的:`!== true` 会把对象形 `draining` 读成「就绪」);下一个 major 把布尔对(`draining` / `drainingSince`)退役、两个谓词改吃 `EngineSignal`。
+
+### 三、服务租约 API 型
+
+- `ServingLeaseRequest = { worker, scope?, generation, instanceId }`;
+  `ServingLeaseResponse` = 判别联合,**三词闭集** `granted { ttlMs }` / `denied { reason }` / `unknown`(`SERVING_LEASE_VERDICTS`);`denied` 的原因闭集恰两词 `superseded` | `retired`(`SERVING_LEASE_DENIED_REASONS`)。
+- **`unknown` 不是 `denied` 的一种**:它不带 reason(带了也被剥掉,读不成 denied),表示中心此刻没有这只实例的生命周期对象(库恢复中、scope 迁移中、尚未认领)——对「该不该继续服务」什么都没说。
+  只有 `denied` 臂约束引擎停服,且**只凭正面证据**:中心对 (scope, worker) 持久化一只代际下限(永不回收),低于下限 ⇒ `superseded`;`retired` 同样要有中心持有的记录;**对象缺席 ⇒ `unknown`,永不拒**。
+  **读器按 `verdict` 键判**(两张脸,失败方向随含义):严格线形 `ServingLeaseResponse` 说的是中心**能发什么**(原因闭集恰两词);`readServingLeaseResponse` 返回 `ServingLeaseReading`——
+  `verdict: "denied"` 时 `reason` 不在闭集 / 缺 / 非串 ⇒ **仍是 `denied`**,`reason` 读成占位词 `SERVING_LEASE_UNKNOWN_REASON`(`"unknown_reason"`),引擎照样自排空,
+  不会因中心学会第三个原因词就把 `denied` 读成 `undefined` 而继续服务。占位词只在读出形里,生产方发不出它。判别词本身不在三词闭集、或 `granted` 的 `ttlMs` 不合 ⇒ `undefined`(读方按中心不可达处理,既不当 `denied` 也不当 `granted`)。
+- **`generation` = 非负整数的规范十进制串**(`"0"`、`"7"`、`"10"`;不许 `"07"`、符号、小数、空白、非 ASCII 数字,也不许数字型),三处 wire 形(`EngineSignal.generation` / `ServingLeaseRequest.generation` / `DrainRequest.expectedGeneration`)同一条判据。
+  新导出 `isCanonicalGeneration(value)`(判别器,接 `unknown`)与 `compareGeneration(a, b)`(数值比,`"9"` 早于 `"10"`,位数不限;非规范入参响亮抛 `TypeError`)——中心持久化的代际下限靠它比较。
+- **`granted` 带的是时长 `ttlMs`(正整数 ms),不是绝对时刻**:引擎按「发出请求时的本地单调钟 + `ttlMs`」自己算到期,中心按库时间记自己的到期,两边不比钟(`EngineSignal.leaseUntil` 是引擎据此算出的到期)。
+- 常量:`SERVING_LEASE_TTL_DEFAULT_MS = 600_000`、`SERVING_LEASE_TTL_FLOOR_MS = 60_000`、`SERVING_LEASE_DRIFT_MARGIN_MS`(**派生自** `DEFAULT_HEARTBEAT_MS`,不是第二个数)。
+  配置的 TTL 过**一只**夹取函数 `clampServingLeaseTtlMs(n)`:读不出(缺 / `NaN` / 无穷 / 非数字)⇒ 缺省;低于地板(含 0 与负数)⇒ 地板;其余取整数 ms,无上限。它给**签发侧**的配置用;
+  应答里的 `ttlMs` 按授予值原样使用、**不**向上夹——引擎把短授予拉长到地板,等于持有租约超过中心记下的期限,那正是围栏要防的事。
+- 读器:`readServingLeaseRequest`(中心侧)/ `readServingLeaseResponse`(引擎侧),同一只受保护读口。
+- **中心能力位 `CenterCapabilities = { servingLease?: true }`** + `readCenterCapabilities(body)`:租约客户端**只在位在场时启用**;缺席(老中心 / 读不出)= 中心不支持租约 ⇒ 引擎不续租、也不被围栏,
+  所以执行器先于中心上线时,不会把还没有租约端点的中心逼成 `lease_expired`。位只有「`true` 或缺席」一种拼法(没有 `false`);未知位被剥,已知位的值不是 `true` ⇒ 整次读 `undefined`(读方等同缺席)。
+  这是兼容门、不是裁决——形里没有「中心拒绝租约」这句话。本仓原先没有中心能力位的表达,故自立这一只;承载它的中心端点不在本包定。
+
+### 四、排空请求 / 回执型
+
+- `DrainRequest = { actionId, scope?, worker, expectedGeneration?, instanceId?, deadlineAt, term? }`:身份(`scope?` / `worker` / `expectedGeneration?` / `instanceId?`)由排空口逐字段「缺席对缺席」比对——
+  非 fleet 成员没有 generation,故缺 `expectedGeneration` 是单机形而不是通配;`instanceId` 在场时是引擎自铸的进程身份。本形只说什么是合式请求,身份不符是排空口的拒因。
+  **两条车道,一个形**:Docker 车道与中心直调用这条 HTTP 排空请求;Kubernetes 车道不逐 pod 发 HTTP(寻址与 RBAC 不合),靠**租约拒 ⇒ 引擎自排空**。
+- `DrainReceipt = EngineDraining.extend({ state: "draining" | "already_draining" })`(`DRAIN_RECEIPT_STATES`),与 `EngineSignal.draining` 同一只形,不抄一份。
+- 读器:`readDrainRequest` / `readDrainReceipt`。
+
+### 五、fleet env 名常量
+
+`FLEET_GENERATION_ENV = "FLEET_GENERATION"`:配置渲染器设、引擎读回并回声成 `EngineSignal.generation`;**它进了保留 env 名表**(`RESERVED_WORKER_ENV`,`WorkerSpec.env` / `secretEnv` 设它即被拒,拒因指路「set by the config renderer … not configurable」),渲染器是唯一写手;两侧都 import 常量,不各自拼字符串
+(整个 `src/` 里这个字面量只出现一次,有源码文本钉)。env 缺席 ⇔ 非 fleet 成员。**刻意没有实例身份的 env 名**——实例身份由引擎每进程自铸(见第二节),`src/` 里 `FLEET_INSTANCE_ID` 一次都不许出现(负钉)。
+
+### 用户可见变化(谁受影响 / 怎么改 / 不改会怎样)
+
+1. **只用 schema / 读写 helper、不碰 fleet 的消费方**:零变化。
+2. **构造或解析 `RestartSignal` 的消费方**:可以多带一个可选布尔 `withheld`;不带照旧。**对 `RestartSignal` 的键做穷举**(`Record<keyof RestartSignal, …>`)的会编译红(多一个键)——按「提货成本」处理,补一行即可。
+3. **要读引擎信号的消费方**(中心 / 壳 / 编排器):用 `readEngineSignal(health)`,不要再各自对 `health.ready` / `health.draining` 手写判断;`undefined` 当「没有信号」,不当「就绪」。
+4. **仍读 `InstanceHealth.draining`(布尔)的**:不动。但注意:一旦某个引擎版本把 `/health` 的 `draining` 铸成对象(`EngineSignal` 方言),`InstanceHealth.safeParse` 对那份体会失败——那是该引擎版本与下一个 major 之间的接线问题,本版没有替它做兼容臂。
+5. **实现租约客户端 / 排空口的引擎(server)与中心(管理面)**:用 `ServingLeaseRequest` / `ServingLeaseResponse` / `DrainRequest` / `DrainReceipt` / `CenterCapabilities` 与 `FLEET_GENERATION_ENV` 对齐形;
+   租约客户端只在 `readCenterCapabilities(...)?.servingLease === true` 时启用;`instanceId` 自己每进程铸一个,不读 env;对 `verdict` 做 `switch` 时加 `default: never` 臂,以后加词编译会红;
+   `granted` 用 `ttlMs`(时长)按发请求时的本地单调钟算到期;应答一律走 `readServingLeaseResponse`(按 `verdict` 键判,`denied` 的原因词读不出也照样排空);`generation` 一律写规范十进制串(`"7"`),用 `compareGeneration` 比大小。
+6. **在 `WorkerSpec.env` / `secretEnv` 里设了 `FLEET_GENERATION` 的**:现在被拒(保留名,拒因指路「set by the config renderer … not configurable」)。这个名字是本版才出现的,正常部署没人设过;
+   设过的删掉那一行,由渲染器按该 worker 的代际写。**持有 `RESERVED_WORKER_ENV` 总数断言的测试**(本仓的历史钉就是一例)要 +1。
+
+### 红先 / 门
+
+- 先写 `test/engine-signal-8.1.0.test.ts`(含 `restart-signal-6.1.0` 的金样格)对着 8.0.0 的 `src/fleet.ts` 跑:新增 31 格里 25 格红(新导出缺席、`withheld` 被剥掉),
+  另 6 格是 additive 反向格(「不带 withheld 的旧形读出形不铸键」「`InstanceHealth` 四键 / passthrough 照旧」「就绪谓词行为照旧」等),在 8.0.0 上本来就绿;
+  逐步实现后同文件全绿(含 3 格源码文本钉:读口只有一只、漂移余量的定义、env 字面量单点与实例身份无 env 名)。
+  之后两轮增补(第一轮:删实例身份 env 名常量、加中心能力位、两处注;第二轮:`ttlMs`、规范 `generation`、读器按 `verdict` 键判、保留 env 名与夹取函数)里,
+  除中心能力位(源码先写、事后用变异自证补咬合)外,新格都先红再绿;`test/migration-signpost-7.0.1.test.ts` 里「保留名总数 = 90」的历史钉改成「90 + 登记的增词」(增词表里目前只有 `FLEET_GENERATION`)。
+- 变异自证(29 个变异,每个都至少使一格红,红的是预期的那一格):`withheld` 改 `.default(false)`、`EngineSignal` 改 `.passthrough()`、`unknown` 臂加 reason、`denied` 的 reason 改可选、漂移余量改字面量、`DrainReceipt` 改成抄一份、`EngineSignal.restart` 改成第二份形、`readEngineSignal` 自带一份 try/catch、`ready` 改可选、`draining` 兼收布尔、原因 / 判别词表多一词、env 名改字或在别处再拼一份、实例身份 env 名常量回来、能力位可写 `false`、能力位自带读口 / 严判未知位、`ttlMs` 变可选、`generation` 放宽成任意非空串 / 规范串正则放过前导零、`compareGeneration` 改字典序 / 不再抛、`denied` 读脸对 reason 严判、占位词混进闭集、`FLEET_GENERATION` 从保留表摘掉、`clampServingLeaseTtlMs` 去地板 / 把读不出夹到地板等。
+- 导出面登记表(`docs/API-SURFACE.md`)重生成:`.` 与 `./fleet` 相对 8.0.0 各 +27 名,无删无改形。
+
+### 未闭环(如实)
+
+
 ## 8.0.0 — 2026-10-04 — 一致性门第四条腿 `strictWrite`(严写受理)+ 每条腿都要表态(BREAKING,kit 类型面与 release 律)· `migrate-workers --check` 与真跑过同一只判定(BREAKING,CLI 退出码 / `refused[]`)· 导出面登记表机器门
 
 > **判档 = major**(README「发版纪律」):kit 的闭集 `LegName` 加一员、`ConformanceAdapter.legs` 从 `Partial<Record<…>>` 改成全量

package/README.md

@@ -48,6 +48,24 @@ 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.0.0 → 8.1.0(全部 additive,零动作可升)
+
+8.1.0 只在 `./fleet`(与主入口)上**加**型与契约,零行为:既有字段的语义、`InstanceHealth` / `InstanceAnnouncement` 的形、两个就绪谓词一字未动。新增清单:
+
+- `RestartSignal.withheld?` —— 可选布尔,引擎自判「这一拍不该被换代」;缺席 = `false`,读出形不铸键。
+- `EngineSignal`(+ `EngineDraining`)与 `readEngineSignal(health)` —— 引擎自铸信号的**闭形**(`ready` 必填,`draining?` / `restart?` / `generation?` / `instanceId?` /
+  `leaseUntil?` / `configTargetVersion?` / `configAppliedVersion?` 可选),键平铺在 `/health` 与心跳体上;与既有读器走同一只受保护读口。
+  `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` —— 租约客户端只在位在场时启用,缺席 = 中心不支持租约(不续租、不围栏)。
+- 排空口型 —— `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;无上限)。
+
+提货成本只有一处:对 `RestartSignal` 的键做穷举的消费方会因多一个键编译红。逐条(谁受影响 / 怎么改)见 CHANGELOG 8.1.0。
+
 ## 升级指引:7.x → 8.0.0
 
 8.0.0 的破坏面只在**一致性门 kit**(`./conformance`)的类型与 release 律、以及 CLI `migrate-workers --check` 的一种结局上;契约 schema、域默认值、
@@ -272,7 +290,20 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   sends it (UNKNOWN, not "none"). A name that cannot ride out is left out by the engine, judged by ONE predicate,
   `isReportableRefusalName` (the wire can carry the key — `__proto__` it cannot — and `isDisclosableIdentity`, the
   rule the dropped-entry identity on read warnings already uses: the `DISCLOSABLE_IDENTITY_RE` allowlist ∧ not
-  secret-shaped, 6.3.0).
+  secret-shaped, 6.3.0). **8.1.0** (additive) puts the engine's own state in one closed shape: `RestartSignal` gains the
+  optional `withheld` ("the engine says this beat must not be handed to a new generation"; absent ≡ false);
+  `EngineSignal` (`{ ready, draining?: EngineDraining, restart?, generation?, instanceId?, leaseUntil?,
+  configTargetVersion?, configAppliedVersion? }`) is the closed form of the engine-minted subset of the /health
+  self-description (keys flat on the /health and heartbeat bodies; `InstanceHealth` stays the open record) and
+  `readEngineSignal(health)` reads it through the same guarded reader as `readRestartSignal` / `readModelRefusals` —
+  `undefined` means "no such signal", never "ready", and a body carrying the boolean `draining` of the 8.0 dialect is not
+  one. The serving-lease wire (`ServingLeaseRequest` / `ServingLeaseResponse`: `granted { ttlMs }` | `denied { reason:
+  superseded | retired }` | `unknown` — a closed three-word set in which `unknown` is NOT a kind of `denied`; plus
+  `SERVING_LEASE_TTL_DEFAULT_MS` 600 000, `SERVING_LEASE_TTL_FLOOR_MS` 60 000 and `SERVING_LEASE_DRIFT_MARGIN_MS`, derived
+  from `DEFAULT_HEARTBEAT_MS`; `denied` rests on positive evidence only), the center capability bit `CenterCapabilities`
+  (`servingLease?: true` — absent means the center has no lease, so the engine neither renews nor is fenced), the drain
+  endpoint's `DrainRequest` / `DrainReceipt`, one reader per wire shape, and the env name `FLEET_GENERATION_ENV` are defined
+  here once for the renderer and the engine (an instance's id is minted by the engine per process — it has no env name).
 - **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.0.0
+8.1.0

package/dist/api/auth-bridge.d.ts

@@ -265,14 +265,14 @@ export declare const VerifiedIdentity: z.ZodObject<{
     scope: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     principal: string;
+    scope?: string | undefined;
     role?: string | undefined;
     grantId?: string | undefined;
-    scope?: string | undefined;
 }, {
     principal: string;
+    scope?: string | undefined;
     role?: string | undefined;
     grantId?: string | undefined;
-    scope?: string | undefined;
 }>;
 export type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
 /** The verifier's total result — exactly one of ok/error. */

package/dist/fleet.d.ts

@@ -51,7 +51,8 @@ export declare function drainVerdict(s: DrainSnapshot): DrainVerdict;
  * {@link readRestartSignal} — {@link InstanceHealth} keeps carrying it untyped, see there). One mint point, two exits —
  * never a second judgement.
  *
- * Shape = what the server already ships on /health (`restart: { reasons, version, since }`). PRESENCE is the signal:
+ * Shape = what the server already ships on /health (`restart: { reasons, version, since }`, plus the optional `withheld`
+ * qualifier below). PRESENCE is the signal:
  * present ⇔ a restart is required, absent ⇔ not; there is deliberately no `required` boolean inside (a boolean next
  * to presence is redundant, and two spellings of one fact drift).
  *  - `reasons` — which restart-to-apply slices differ from the value baked at boot (the vocabulary is the engine's;
@@ -60,19 +61,26 @@ export declare function drainVerdict(s: DrainSnapshot): DrainVerdict;
  *    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.
  *  - `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`
+ *    on the wire reads the same as the key being absent, and a reader never mints the key when the producer did not send
+ *    it. It is a qualifier INSIDE the restart signal, never a signal of its own: it exists only where `restart` does.
  */
 export declare const RestartSignal: z.ZodObject<{
     reasons: z.ZodArray<z.ZodString, "many">;
     version: z.ZodNumber;
     since: z.ZodNumber;
+    withheld: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     reasons: string[];
     version: number;
     since: number;
+    withheld?: boolean | undefined;
 }, {
     reasons: string[];
     version: number;
     since: number;
+    withheld?: boolean | undefined;
 }>;
 export type RestartSignal = z.infer<typeof RestartSignal>;
 /**
@@ -211,7 +219,11 @@ export declare const InstanceHealth: z.ZodObject<{
     drainingSince: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">>;
 export type InstanceHealth = z.infer<typeof InstanceHealth>;
-/** Readiness = the routability predicate (k8s readiness probe, gateway health filter, shell seam switch). */
+/** Readiness = the routability predicate (k8s readiness probe, gateway health filter, shell seam switch).
+ *  Its input is the boolean-`draining` dialect of {@link InstanceHealth}. An {@link EngineSignal} types `draining` as an
+ *  object, so it does not typecheck here (on purpose: `!== true` would read an object-valued `draining` as "ready").
+ *  The next major retires the boolean pair (`draining` / `drainingSince`) and gives both this predicate and
+ *  {@link isRoutable} `EngineSignal` as their input. */
 export declare function isReadyForTraffic(h: Pick<InstanceHealth, "draining">): boolean;
 /** Heartbeat cadence the announcement declares (center judges staleness against the DECLARED cadence, so a
  *  slow-heartbeat worker is not falsely reaped). */
@@ -242,14 +254,17 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         reasons: z.ZodArray<z.ZodString, "many">;
         version: z.ZodNumber;
         since: z.ZodNumber;
+        withheld: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     }, {
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     }>>;
     /** S-768: present ⇔ this instance has at least one reportable model refusal — the SAME {@link ModelRefusalsWire} /health
      *  carries, minted by the same getter; read it with {@link readModelRefusals}`(announcement)` (never off this field
@@ -289,6 +304,7 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: {
         entries: Record<string, string>;
@@ -305,6 +321,7 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
@@ -346,14 +363,17 @@ export declare const InstanceRegistration: z.ZodObject<{
         reasons: z.ZodArray<z.ZodString, "many">;
         version: z.ZodNumber;
         since: z.ZodNumber;
+        withheld: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     }, {
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     }>>;
     /** S-768: present ⇔ this instance has at least one reportable model refusal — the SAME {@link ModelRefusalsWire} /health
      *  carries, minted by the same getter; read it with {@link readModelRefusals}`(announcement)` (never off this field
@@ -399,6 +419,7 @@ export declare const InstanceRegistration: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: {
         entries: Record<string, string>;
@@ -418,6 +439,7 @@ export declare const InstanceRegistration: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
@@ -427,9 +449,400 @@ export type InstanceRegistration = z.infer<typeof InstanceRegistration>;
 /** Silent past the declared cadence × multiplier ⇒ stale (auto-removed from the routable set). */
 export declare function isInstanceStale(r: Pick<InstanceRegistration, "lastSeenMs" | "heartbeatMs">, nowMs: number): boolean;
 /** Health fusion: routable ⇔ self-declared ready ∧ not draining ∧ not stale ∧ observer does not veto.
- *  Two sources merge as an AND — EITHER source's "not ready" removes the instance (fail-closed). */
+ *  Two sources merge as an AND — EITHER source's "not ready" removes the instance (fail-closed).
+ *  Its input is the stored heartbeat row (boolean `draining`); it moves to {@link EngineSignal} in the same major as
+ *  {@link isReadyForTraffic}. */
 export declare function isRoutable(r: InstanceRegistration, nowMs: number): boolean;
 export declare function routableInstances(rs: InstanceRegistration[], nowMs: number): InstanceRegistration[];
+/**
+ * The engine's draining fact — ONE object wherever the engine says "I am draining": inside {@link EngineSignal}`.draining`
+ * and as the body of a {@link DrainReceipt}.
+ *  - `actionId` — the action that put the engine into draining (idempotency key of the drain request).
+ *  - `since` — epoch ms when draining began; it does not move when the same action repeats.
+ *  - `deadlineAt` — epoch ms by which the engine stops on its own.
+ */
+export declare const EngineDraining: z.ZodObject<{
+    actionId: z.ZodString;
+    since: z.ZodNumber;
+    deadlineAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    since: number;
+    actionId: string;
+    deadlineAt: number;
+}, {
+    since: number;
+    actionId: string;
+    deadlineAt: number;
+}>;
+export type EngineDraining = z.infer<typeof EngineDraining>;
+export declare function isCanonicalGeneration(value: unknown): value is string;
+/** Numeric order of two canonical generations: `-1` when `a` is older than `b`, `0` when equal, `1` when newer — `"9"` is
+ *  older than `"10"`; any number of digits. Throws a `TypeError` on an input that is not canonical (a comparison that quietly
+ *  returned some number would be a fence decision made on garbage); judge untrusted input with {@link isCanonicalGeneration}
+ *  first — the wire shapes of this file already do. */
+export declare function compareGeneration(a: string, b: string): -1 | 0 | 1;
+/**
+ * Everything the ENGINE itself mints about its own state, as one object — the closed form of the engine-owned subset of the
+ * /health self-description ({@link InstanceHealth} is that self-description: an open record, `.passthrough()`, which also
+ * carries what the host adds — build, pid, port, store posture). One mint point; the heartbeat and `/health` carry the same
+ * keys with the same values, flat (`ready`, `draining`, `restart`, … sit directly on the body, no wrapper key), and
+ * {@link readEngineSignal} is the one reader of either.
+ *
+ *  - `ready` — always said (never "absent while ready"): the engine can take new work right now.
+ *  - `draining` — present ⇔ draining ({@link EngineDraining}). NOTE the dialect: {@link InstanceHealth}`.draining` and
+ *    {@link InstanceAnnouncement}`.draining` are BOOLEANS (the 8.0 dialect, kept untouched); here it is an object. A body
+ *    whose `draining` is a boolean is therefore not an `EngineSignal` and reads as `undefined`.
+ *  - `restart` — the one {@link RestartSignal}, same schema object, no copy.
+ *  - `generation` — echo of the env the config renderer set on this instance ({@link FLEET_GENERATION_ENV}), a canonical
+ *    decimal string ({@link isCanonicalGeneration}). Absent ⇔ not a fleet member (a single-machine engine): it takes no lease
+ *    and is not fenced.
+ *  - `instanceId` — the engine's OWN process identity, minted by the engine every time the process starts (never read from
+ *    env: replicas of one Deployment share one env, and a restarted container reuses its env, so env cannot tell two
+ *    processes apart). It is present on a standalone engine too — only `generation` marks fleet membership.
+ *  - `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}); absent when it holds none.
+ *  - `configTargetVersion` / `configAppliedVersion` — the config-center version the engine was told to converge on, and the
+ *    one it has applied (opaque strings; 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
+ * signal this reader can say" — an engine that predates the keys, or a malformed body — and is NEVER "ready": a caller on
+ * the routing axis treats it as not routable unless it deliberately falls back to the boolean dialect of
+ * {@link InstanceHealth}.
+ */
+export declare const EngineSignal: z.ZodObject<{
+    ready: z.ZodBoolean;
+    draining: z.ZodOptional<z.ZodObject<{
+        actionId: z.ZodString;
+        since: z.ZodNumber;
+        deadlineAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        since: number;
+        actionId: string;
+        deadlineAt: number;
+    }, {
+        since: number;
+        actionId: string;
+        deadlineAt: number;
+    }>>;
+    restart: z.ZodOptional<z.ZodObject<{
+        reasons: z.ZodArray<z.ZodString, "many">;
+        version: z.ZodNumber;
+        since: z.ZodNumber;
+        withheld: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        reasons: string[];
+        version: number;
+        since: number;
+        withheld?: boolean | undefined;
+    }, {
+        reasons: string[];
+        version: number;
+        since: number;
+        withheld?: boolean | undefined;
+    }>>;
+    generation: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    leaseUntil: z.ZodOptional<z.ZodNumber>;
+    configTargetVersion: z.ZodOptional<z.ZodString>;
+    configAppliedVersion: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ready: boolean;
+    draining?: {
+        since: number;
+        actionId: string;
+        deadlineAt: number;
+    } | undefined;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+        withheld?: boolean | undefined;
+    } | undefined;
+    instanceId?: string | undefined;
+    generation?: string | undefined;
+    leaseUntil?: number | undefined;
+    configTargetVersion?: string | undefined;
+    configAppliedVersion?: string | undefined;
+}, {
+    ready: boolean;
+    draining?: {
+        since: number;
+        actionId: string;
+        deadlineAt: number;
+    } | undefined;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+        withheld?: boolean | undefined;
+    } | undefined;
+    instanceId?: string | undefined;
+    generation?: string | undefined;
+    leaseUntil?: number | undefined;
+    configTargetVersion?: string | undefined;
+    configAppliedVersion?: string | undefined;
+}>;
+export type EngineSignal = z.infer<typeof EngineSignal>;
+/**
+ * The reader of {@link EngineSignal}, for either exit (a /health body or a heartbeat body — the keys are flat on both): the
+ * same guarded body reader as {@link readRestartSignal} and {@link readModelRefusals}, so the same odd input gets the same
+ * answer from all three. Shape mismatch, a missing `ready`, a non-object body, even a throwing accessor ⇒ `undefined` —
+ * never throws. See {@link EngineSignal} for what `undefined` means (not "ready").
+ */
+export declare function readEngineSignal(health: unknown): EngineSignal | undefined;
+/**
+ * The env name a fleet member's generation travels under — the config renderer sets it, the engine reads it back and echoes
+ * it as {@link EngineSignal}`.generation`. Both sides import THIS constant; neither spells the name. The value is the
+ * generation this instance belongs to (opaque string); absent from the engine's env ⇔ not a fleet member (the standalone
+ * form). There is deliberately NO env name for the instance id: an instance's identity is minted by the engine per process
+ * ({@link EngineSignal}`.instanceId`), and env cannot carry it (see there).
+ */
+export declare const FLEET_GENERATION_ENV = "FLEET_GENERATION";
+/**
+ * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
+ * engine renews it with the center; the center answers per the lifecycle object it holds for that instance. Three constants
+ * fix the clock, all in ms:
+ *  - {@link SERVING_LEASE_TTL_DEFAULT_MS} — the lease length when the operator sets none (10 min).
+ *  - {@link SERVING_LEASE_TTL_FLOOR_MS} — the shortest lease there is: a configured TTL below it is treated as it (1 min),
+ *    the same way {@link DRAIN_GRACE_FLOOR_MS} protects a fat-fingered grace.
+ *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — the center's clock-skew allowance: it adds this to a lease's recorded expiry
+ *    before it counts that lease as over. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a
+ *    second constant that could drift from it.
+ */
+export declare const SERVING_LEASE_TTL_DEFAULT_MS = 600000;
+export declare const SERVING_LEASE_TTL_FLOOR_MS = 60000;
+export declare const SERVING_LEASE_DRIFT_MARGIN_MS = 30000;
+/**
+ * The ONE place a configured lease TTL becomes a usable one: not a number (absent, `NaN`, infinite, another type) ⇒
+ * {@link SERVING_LEASE_TTL_DEFAULT_MS}; a number below {@link SERVING_LEASE_TTL_FLOOR_MS} (zero and negatives included) ⇒ the
+ * floor; otherwise the number, truncated to whole ms, with no ceiling. It is for the ISSUING side's configuration. A reply's
+ * `ttlMs` is used exactly as granted and is never clamped upward — an engine that stretched a short grant to the floor would
+ * hold the lease past what the center recorded, which is the one thing the fence exists to prevent.
+ */
+export declare function clampServingLeaseTtlMs(configuredMs: number | undefined): number;
+/**
+ * Engine → center: "may this instance keep serving?" The identity triple names the instance exactly — a lease is never
+ * asked for by worker name alone. `generation` is the env echo ({@link FLEET_GENERATION_ENV}); `instanceId` is the engine's
+ * own per-process identity ({@link EngineSignal}`.instanceId`), so a restarted process is a NEW instance to the center.
+ * `scope` is the tenant scope the worker lives in (absent = the single-scope deployment). Only fleet members ask: an engine
+ * without a generation (the standalone form) has no lease and sends nothing.
+ */
+export declare const ServingLeaseRequest: z.ZodObject<{
+    worker: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    generation: z.ZodEffects<z.ZodString, string, string>;
+    instanceId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    instanceId: string;
+    worker: string;
+    generation: string;
+    scope?: string | undefined;
+}, {
+    instanceId: string;
+    worker: string;
+    generation: string;
+    scope?: string | undefined;
+}>;
+export type ServingLeaseRequest = z.infer<typeof ServingLeaseRequest>;
+/**
+ * Why a lease is refused — a CLOSED set of exactly two words, owned here:
+ *  - `superseded` — a newer generation of this worker has taken over; this instance is the old one.
+ *  - `retired` — the center has retired this instance (or the worker it belongs to).
+ * Only {@link ServingLeaseResponse}'s `denied` arm carries a reason; `unknown` has none, by shape.
+ */
+export declare const SERVING_LEASE_DENIED_REASONS: readonly ["superseded", "retired"];
+export declare const ServingLeaseDeniedReason: z.ZodEnum<["superseded", "retired"]>;
+export type ServingLeaseDeniedReason = z.infer<typeof ServingLeaseDeniedReason>;
+/**
+ * Center → engine: the verdict, a CLOSED set of three words ({@link SERVING_LEASE_VERDICTS}) — the arms of one
+ * discriminated union, so a reader that switches on `verdict` is told by the compiler when a word is added.
+ *  - `granted` — keep serving; `ttlMs` is how long the lease lasts, a DURATION, never a wall-clock instant: the engine counts
+ *    it from the instant it SENT the request, on its own monotonic clock (`expiresAt = sendAt + ttlMs`), and the center keeps
+ *    its own expiry from its store time — the two sides never compare clocks, so no clock agreement is needed.
+ *  - `denied` — this instance must stop: `reason` is {@link ServingLeaseDeniedReason}. The ONLY arm that obliges an engine to
+ *    stop serving, and it is issued on POSITIVE evidence only: the center keeps, per (scope, worker), a persisted generation
+ *    floor that is never garbage-collected, and a request whose generation lies below it is `superseded`; `retired` likewise
+ *    rests on a record the center holds. A center that merely holds no such record does not deny — it answers `unknown`.
+ *  - `unknown` — the center holds no lifecycle object for this instance right now (restoring its store, migrating scopes, not
+ *    yet claimed). It says NOTHING about whether the instance should serve, so it is not a kind of `denied` and absence of the
+ *    object NEVER turns into a denial: it carries no reason, and an engine never drains on it. To the engine it is the same
+ *    case as an unreachable center.
+ * This is the law for what a center SENDS. A reader does not apply it to `reason`: {@link readServingLeaseResponse} judges by
+ * the `verdict` key and keeps a `denied` a `denied` even when its reason is outside the set ({@link ServingLeaseReading}). A
+ * reply whose `verdict` itself is outside the three words (or a `granted` with no valid `ttlMs`) is not a verdict at all and
+ * reads as `undefined` — an unreachable center, never `denied`, never `granted`.
+ */
+export declare const ServingLeaseResponse: z.ZodDiscriminatedUnion<"verdict", [z.ZodObject<{
+    verdict: z.ZodLiteral<"granted">;
+    ttlMs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    verdict: "granted";
+    ttlMs: number;
+}, {
+    verdict: "granted";
+    ttlMs: number;
+}>, z.ZodObject<{
+    verdict: z.ZodLiteral<"denied">;
+    reason: z.ZodEnum<["superseded", "retired"]>;
+}, "strip", z.ZodTypeAny, {
+    reason: "superseded" | "retired";
+    verdict: "denied";
+}, {
+    reason: "superseded" | "retired";
+    verdict: "denied";
+}>, z.ZodObject<{
+    verdict: z.ZodLiteral<"unknown">;
+}, "strip", z.ZodTypeAny, {
+    verdict: "unknown";
+}, {
+    verdict: "unknown";
+}>]>;
+export type ServingLeaseResponse = z.infer<typeof ServingLeaseResponse>;
+/** The reason word a READER puts in place of a `denied` reason it cannot place (outside {@link SERVING_LEASE_DENIED_REASONS},
+ *  missing, not a string). Read-face only: a producer never sends it, and the strict {@link ServingLeaseResponse} refuses it. */
+export declare const SERVING_LEASE_UNKNOWN_REASON = "unknown_reason";
+/** The read face of {@link ServingLeaseResponse} — same three arms, with the `denied` arm tolerant about `reason`. */
+declare const ServingLeaseReadFace: z.ZodDiscriminatedUnion<"verdict", [z.ZodObject<{
+    verdict: z.ZodLiteral<"granted">;
+    ttlMs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    verdict: "granted";
+    ttlMs: number;
+}, {
+    verdict: "granted";
+    ttlMs: number;
+}>, z.ZodObject<{
+    verdict: z.ZodLiteral<"denied">;
+    reason: z.ZodEffects<z.ZodUnknown, "superseded" | "retired" | "unknown_reason", unknown>;
+}, "strip", z.ZodTypeAny, {
+    reason: "superseded" | "retired" | "unknown_reason";
+    verdict: "denied";
+}, {
+    verdict: "denied";
+    reason?: unknown;
+}>, z.ZodObject<{
+    verdict: z.ZodLiteral<"unknown">;
+}, "strip", z.ZodTypeAny, {
+    verdict: "unknown";
+}, {
+    verdict: "unknown";
+}>]>;
+/** The verdict words as a runtime list. `satisfies` bites a word the union does not have; the converse (a union arm missing
+ *  from this list) is pinned by a test that reads the union's discriminators. */
+export declare const SERVING_LEASE_VERDICTS: readonly ["granted", "denied", "unknown"];
+/** Center side: the request body of a serving-lease renewal. Shape mismatch / non-object / throwing accessor ⇒ `undefined`,
+ *  never throws (same guarded reader as every other read in this file). */
+export declare function readServingLeaseRequest(body: unknown): ServingLeaseRequest | undefined;
+/**
+ * What {@link readServingLeaseResponse} returns: {@link ServingLeaseResponse} plus the one thing a reader adds — a `denied`
+ * whose reason it could not place carries {@link SERVING_LEASE_UNKNOWN_REASON}. Two faces on purpose (the failure direction
+ * must match the meaning): the strict wire law says what a center may SEND (a closed two-word reason set); the reader judges
+ * by the `verdict` key alone, so a center that learns a third reason word cannot make an older engine read `denied` as
+ * `undefined` and keep serving. Branch on `verdict`; `reason` is for the log line.
+ */
+export type ServingLeaseReading = z.output<typeof ServingLeaseReadFace>;
+/** Engine side: the reply to a renewal, judged by its `verdict` key: `granted` needs a valid `ttlMs`, `denied` is `denied`
+ *  whatever its `reason` (see {@link ServingLeaseReading}), `unknown` is `unknown`. A non-object, a throwing accessor, a
+ *  `verdict` outside the three words or a `granted` without a valid `ttlMs` ⇒ `undefined`, never throws — and `undefined`
+ *  is read like an unreachable center, never like `denied` and never like `granted`. */
+export declare function readServingLeaseResponse(body: unknown): ServingLeaseReading | undefined;
+/**
+ * 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.
+ * This package fixes the shape and the reader, not which center endpoint carries the object.
+ */
+export declare const CenterCapabilities: z.ZodObject<{
+    servingLease: z.ZodOptional<z.ZodLiteral<true>>;
+}, "strip", z.ZodTypeAny, {
+    servingLease?: true | undefined;
+}, {
+    servingLease?: true | undefined;
+}>;
+export type CenterCapabilities = z.infer<typeof CenterCapabilities>;
+/** 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;
+/**
+ * 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
+ * call from the center) this HTTP request is how an instance is drained; on the Kubernetes lane no per-pod HTTP call is made
+ * (per-pod addressing and RBAC make it the wrong tool) — an instance is drained by its serving lease being denied
+ * ({@link ServingLeaseResponse}), after which the engine puts itself into draining.
+ *  - `actionId` — idempotency key: the same id again echoes the first answer ({@link DrainReceipt}`.state` =
+ *    `already_draining`) and changes nothing.
+ *  - the identity — `scope?` / `worker` / `expectedGeneration?` / `instanceId?` — names WHICH instance the action is for. The
+ *    engine compares it field by field against its own, absent against absent: an engine that is not a fleet member has no
+ *    generation, so a request with no `expectedGeneration` is the standalone form, not a wildcard; `instanceId`, when given,
+ *    is the engine's own per-process identity ({@link EngineSignal}`.instanceId`). A mismatch is the endpoint's refusal, not
+ *    this shape's: this schema only says what a well-formed request looks like.
+ *  - `deadlineAt` — epoch ms by which the engine stops on its own.
+ *  - `term` — the claim term the sending executor holds for this action (center-issued, opaque); absent where no executor
+ *    sits in between (a direct call, a hand-issued action).
+ */
+export declare const DrainRequest: z.ZodObject<{
+    actionId: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    worker: z.ZodString;
+    expectedGeneration: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    deadlineAt: z.ZodNumber;
+    term: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    worker: string;
+    actionId: string;
+    deadlineAt: number;
+    instanceId?: string | undefined;
+    scope?: string | undefined;
+    expectedGeneration?: string | undefined;
+    term?: string | undefined;
+}, {
+    worker: string;
+    actionId: string;
+    deadlineAt: number;
+    instanceId?: string | undefined;
+    scope?: string | undefined;
+    expectedGeneration?: string | undefined;
+    term?: string | undefined;
+}>;
+export type DrainRequest = z.infer<typeof DrainRequest>;
+/** What a drain request leaves the engine in: `draining` — this call put it into draining; `already_draining` — it already was
+ *  (the same action repeated), and the receipt reports the first call's facts. */
+export declare const DRAIN_RECEIPT_STATES: readonly ["draining", "already_draining"];
+export declare const DrainReceiptState: z.ZodEnum<["draining", "already_draining"]>;
+export type DrainReceiptState = z.infer<typeof DrainReceiptState>;
+/** The drain endpoint's answer: the engine's draining fact ({@link EngineDraining} — the same object {@link EngineSignal}
+ *  carries as `draining`, extended, not copied) plus how this call found the engine. */
+export declare const DrainReceipt: z.ZodObject<{
+    actionId: z.ZodString;
+    since: z.ZodNumber;
+    deadlineAt: z.ZodNumber;
+} & {
+    state: z.ZodEnum<["draining", "already_draining"]>;
+}, "strip", z.ZodTypeAny, {
+    since: number;
+    actionId: string;
+    deadlineAt: number;
+    state: "draining" | "already_draining";
+}, {
+    since: number;
+    actionId: string;
+    deadlineAt: number;
+    state: "draining" | "already_draining";
+}>;
+export type DrainReceipt = z.infer<typeof DrainReceipt>;
+/** Engine side: the request body of the drain endpoint. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
+export declare function readDrainRequest(body: unknown): DrainRequest | undefined;
+/** Caller side: the drain endpoint's answer. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
+export declare function readDrainReceipt(body: unknown): DrainReceipt | undefined;
 export declare const DISPATCH_STRATEGIES: readonly ["round-robin", "least-inflight", "consistent-hash"];
 export type DispatchStrategy = (typeof DISPATCH_STRATEGIES)[number];
 /** Per-worker dispatch policy (center-configured; the gateway is OPTIONAL — D3: TOC/self-maintained TOB go
@@ -749,3 +1162,4 @@ export interface AggregatedPrincipalUsage {
  *  view). Pure — storage/dedup of replayed batches is the caller's concern (key batches by
  *  worker+instanceId+windowStartMs). */
 export declare function aggregateUsage(reports: UsageReport[]): Record<string, AggregatedPrincipalUsage>;
+export {};

package/dist/fleet.js

@@ -40,13 +40,16 @@ export function drainVerdict(s) {
     const grace = Math.max(DRAIN_GRACE_FLOOR_MS, s.graceMs);
     return s.nowMs - s.startedMs >= grace ? "exit_forced" : "wait";
 }
+/** 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();
 /**
  * "This instance must restart to apply config" — the engine's OWN observation (S-741), defined ONCE for both exits that
  * carry it: the fleet heartbeat ({@link InstanceAnnouncement}`.restart`, typed) and GET /health (`restart`, read through
  * {@link readRestartSignal} — {@link InstanceHealth} keeps carrying it untyped, see there). One mint point, two exits —
  * never a second judgement.
  *
- * Shape = what the server already ships on /health (`restart: { reasons, version, since }`). PRESENCE is the signal:
+ * Shape = what the server already ships on /health (`restart: { reasons, version, since }`, plus the optional `withheld`
+ * qualifier below). PRESENCE is the signal:
  * present ⇔ a restart is required, absent ⇔ not; there is deliberately no `required` boolean inside (a boolean next
  * to presence is redundant, and two spellings of one fact drift).
  *  - `reasons` — which restart-to-apply slices differ from the value baked at boot (the vocabulary is the engine's;
@@ -55,35 +58,45 @@ export function drainVerdict(s) {
  *    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.
  *  - `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`
+ *    on the wire reads the same as the key being absent, and a reader never mints the key when the producer did not send
+ *    it. It is a qualifier INSIDE the restart signal, never a signal of its own: it exists only where `restart` does.
  */
 export const RestartSignal = z.object({
     reasons: z.array(z.string().min(1)).min(1),
     version: z.number().finite(),
-    since: z.number().int().nonnegative(),
+    since: EpochMs,
+    withheld: z.boolean().optional(),
 });
 /**
- * The ONE /health reader behind every engine-owned signal ({@link readRestartSignal}, {@link readModelRefusals}): `health[key]`
- * judged against that signal's one shape. Shape mismatch, a missing key, a non-object body, even a throwing accessor ⇒
- * `undefined` — never throws (a probe must not die on one odd body).
+ * 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.
  */
-function readHealthSignal(health, key, schema) {
+function readSignalBody(body, pick, schema) {
     try {
-        if (health === null || typeof health !== "object" || Array.isArray(health))
+        if (body === null || typeof body !== "object" || Array.isArray(body))
             return undefined;
-        const parsed = schema.safeParse(health[key]);
+        const parsed = schema.safeParse(pick(body));
         return parsed.success ? parsed.data : undefined;
     }
     catch {
         return 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;
 /**
  * The /health exit of {@link RestartSignal}: `health.restart` judged against the one shape. Shape mismatch, a missing
  * key, a non-object body, even a throwing accessor ⇒ `undefined` — never throws (a probe must not die on one odd body).
  * Presence law: only `restart` counts; the top-level `restartRequired` boolean the server also ships is not read.
  */
 export function readRestartSignal(health) {
-    return readHealthSignal(health, "restart", RestartSignal);
+    return readSignalBody(health, (h) => h.restart, RestartSignal);
 }
 /**
  * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
@@ -177,7 +190,7 @@ const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
  * at all — it answers the key only and never judges the engine's version (see {@link InstanceAnnouncement}`.modelRefusals`).
  */
 export function readModelRefusals(body) {
-    const wire = readHealthSignal(body, "modelRefusals", ModelRefusalsWire);
+    const wire = readSignalBody(body, (b) => b.modelRefusals, ModelRefusalsWire);
     if (wire === undefined)
         return undefined;
     const entries = Object.fromEntries(Object.entries(wire.entries).filter((e) => isModelEntryRefusalCode(e[1])));
@@ -205,7 +218,11 @@ export const InstanceHealth = z
     // S-768: `modelRefusals` rides the passthrough untyped for the same reason — read it with {@link readModelRefusals}.
 })
     .passthrough();
-/** Readiness = the routability predicate (k8s readiness probe, gateway health filter, shell seam switch). */
+/** Readiness = the routability predicate (k8s readiness probe, gateway health filter, shell seam switch).
+ *  Its input is the boolean-`draining` dialect of {@link InstanceHealth}. An {@link EngineSignal} types `draining` as an
+ *  object, so it does not typecheck here (on purpose: `!== true` would read an object-valued `draining` as "ready").
+ *  The next major retires the boolean pair (`draining` / `drainingSince`) and gives both this predicate and
+ *  {@link isRoutable} `EngineSignal` as their input. */
 export function isReadyForTraffic(h) {
     return h.draining !== true;
 }
@@ -266,13 +283,271 @@ export function isInstanceStale(r, nowMs) {
     return nowMs - r.lastSeenMs > STALE_HEARTBEAT_MULTIPLIER * r.heartbeatMs;
 }
 /** Health fusion: routable ⇔ self-declared ready ∧ not draining ∧ not stale ∧ observer does not veto.
- *  Two sources merge as an AND — EITHER source's "not ready" removes the instance (fail-closed). */
+ *  Two sources merge as an AND — EITHER source's "not ready" removes the instance (fail-closed).
+ *  Its input is the stored heartbeat row (boolean `draining`); it moves to {@link EngineSignal} in the same major as
+ *  {@link isReadyForTraffic}. */
 export function isRoutable(r, nowMs) {
     return r.ready && !r.draining && r.observedReady !== false && !isInstanceStale(r, nowMs);
 }
 export function routableInstances(rs, nowMs) {
     return rs.filter((r) => isRoutable(r, nowMs));
 }
+// ── Domain 2b: the engine's own signal, the serving lease, the drain endpoint ─────────────────────────────
+/**
+ * The engine's draining fact — ONE object wherever the engine says "I am draining": inside {@link EngineSignal}`.draining`
+ * and as the body of a {@link DrainReceipt}.
+ *  - `actionId` — the action that put the engine into draining (idempotency key of the drain request).
+ *  - `since` — epoch ms when draining began; it does not move when the same action repeats.
+ *  - `deadlineAt` — epoch ms by which the engine stops on its own.
+ */
+export const EngineDraining = z.object({
+    actionId: z.string().min(1),
+    since: EpochMs,
+    deadlineAt: EpochMs,
+});
+/**
+ * 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.
+ * One spelling per value, so equality is string equality and the order is numeric ({@link compareGeneration}) — the center's
+ * persisted generation floor and every "is this generation below the floor" judgement rest on that order. The renderer writes
+ * the value into {@link FLEET_GENERATION_ENV}; an env value that is present but not canonical is a misconfiguration to refuse
+ * loudly, not an absent generation (absence is what marks a non-member). Wherever a wire shape here carries a generation
+ * ({@link EngineSignal}`.generation`, {@link ServingLeaseRequest}, {@link DrainRequest}`.expectedGeneration`) it is judged by
+ * this one predicate.
+ */
+const CANONICAL_GENERATION = /^(?:0|[1-9][0-9]*)$/;
+export function isCanonicalGeneration(value) {
+    return typeof value === "string" && CANONICAL_GENERATION.test(value);
+}
+/** Numeric order of two canonical generations: `-1` when `a` is older than `b`, `0` when equal, `1` when newer — `"9"` is
+ *  older than `"10"`; any number of digits. Throws a `TypeError` on an input that is not canonical (a comparison that quietly
+ *  returned some number would be a fence decision made on garbage); judge untrusted input with {@link isCanonicalGeneration}
+ *  first — the wire shapes of this file already do. */
+export function compareGeneration(a, b) {
+    if (!isCanonicalGeneration(a) || !isCanonicalGeneration(b)) {
+        throw new TypeError(`compareGeneration: a generation is a canonical non-negative decimal string (got ${JSON.stringify(isCanonicalGeneration(a) ? b : a)})`);
+    }
+    if (a.length !== b.length)
+        return a.length < b.length ? -1 : 1; // canonical ⇒ no leading zeros ⇒ more digits is larger
+    return a === b ? 0 : a < b ? -1 : 1;
+}
+/** The generation field of every wire shape that carries one — a string judged by {@link isCanonicalGeneration}. */
+const Generation = z.string().refine(isCanonicalGeneration, { message: "a generation is a canonical non-negative decimal string (no sign, no leading zero)" });
+/**
+ * Everything the ENGINE itself mints about its own state, as one object — the closed form of the engine-owned subset of the
+ * /health self-description ({@link InstanceHealth} is that self-description: an open record, `.passthrough()`, which also
+ * carries what the host adds — build, pid, port, store posture). One mint point; the heartbeat and `/health` carry the same
+ * keys with the same values, flat (`ready`, `draining`, `restart`, … sit directly on the body, no wrapper key), and
+ * {@link readEngineSignal} is the one reader of either.
+ *
+ *  - `ready` — always said (never "absent while ready"): the engine can take new work right now.
+ *  - `draining` — present ⇔ draining ({@link EngineDraining}). NOTE the dialect: {@link InstanceHealth}`.draining` and
+ *    {@link InstanceAnnouncement}`.draining` are BOOLEANS (the 8.0 dialect, kept untouched); here it is an object. A body
+ *    whose `draining` is a boolean is therefore not an `EngineSignal` and reads as `undefined`.
+ *  - `restart` — the one {@link RestartSignal}, same schema object, no copy.
+ *  - `generation` — echo of the env the config renderer set on this instance ({@link FLEET_GENERATION_ENV}), a canonical
+ *    decimal string ({@link isCanonicalGeneration}). Absent ⇔ not a fleet member (a single-machine engine): it takes no lease
+ *    and is not fenced.
+ *  - `instanceId` — the engine's OWN process identity, minted by the engine every time the process starts (never read from
+ *    env: replicas of one Deployment share one env, and a restarted container reuses its env, so env cannot tell two
+ *    processes apart). It is present on a standalone engine too — only `generation` marks fleet membership.
+ *  - `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}); absent when it holds none.
+ *  - `configTargetVersion` / `configAppliedVersion` — the config-center version the engine was told to converge on, and the
+ *    one it has applied (opaque strings; 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
+ * signal this reader can say" — an engine that predates the keys, or a malformed body — and is NEVER "ready": a caller on
+ * the routing axis treats it as not routable unless it deliberately falls back to the boolean dialect of
+ * {@link InstanceHealth}.
+ */
+export const EngineSignal = z.object({
+    ready: z.boolean(),
+    draining: EngineDraining.optional(),
+    restart: RestartSignal.optional(),
+    generation: Generation.optional(),
+    instanceId: z.string().min(1).optional(),
+    leaseUntil: EpochMs.optional(),
+    configTargetVersion: z.string().min(1).optional(),
+    configAppliedVersion: z.string().min(1).optional(),
+});
+/**
+ * The reader of {@link EngineSignal}, for either exit (a /health body or a heartbeat body — the keys are flat on both): the
+ * same guarded body reader as {@link readRestartSignal} and {@link readModelRefusals}, so the same odd input gets the same
+ * answer from all three. Shape mismatch, a missing `ready`, a non-object body, even a throwing accessor ⇒ `undefined` —
+ * never throws. See {@link EngineSignal} for what `undefined` means (not "ready").
+ */
+export function readEngineSignal(health) {
+    return readSignalBody(health, wholeBody, EngineSignal);
+}
+/**
+ * The env name a fleet member's generation travels under — the config renderer sets it, the engine reads it back and echoes
+ * it as {@link EngineSignal}`.generation`. Both sides import THIS constant; neither spells the name. The value is the
+ * generation this instance belongs to (opaque string); absent from the engine's env ⇔ not a fleet member (the standalone
+ * form). There is deliberately NO env name for the instance id: an instance's identity is minted by the engine per process
+ * ({@link EngineSignal}`.instanceId`), and env cannot carry it (see there).
+ */
+export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
+/**
+ * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
+ * engine renews it with the center; the center answers per the lifecycle object it holds for that instance. Three constants
+ * fix the clock, all in ms:
+ *  - {@link SERVING_LEASE_TTL_DEFAULT_MS} — the lease length when the operator sets none (10 min).
+ *  - {@link SERVING_LEASE_TTL_FLOOR_MS} — the shortest lease there is: a configured TTL below it is treated as it (1 min),
+ *    the same way {@link DRAIN_GRACE_FLOOR_MS} protects a fat-fingered grace.
+ *  - {@link SERVING_LEASE_DRIFT_MARGIN_MS} — the center's clock-skew allowance: it adds this to a lease's recorded expiry
+ *    before it counts that lease as over. It is DERIVED from {@link DEFAULT_HEARTBEAT_MS} (one cadence, one number), never a
+ *    second constant that could drift from it.
+ */
+export const SERVING_LEASE_TTL_DEFAULT_MS = 600_000;
+export const SERVING_LEASE_TTL_FLOOR_MS = 60_000;
+export const SERVING_LEASE_DRIFT_MARGIN_MS = DEFAULT_HEARTBEAT_MS;
+/**
+ * The ONE place a configured lease TTL becomes a usable one: not a number (absent, `NaN`, infinite, another type) ⇒
+ * {@link SERVING_LEASE_TTL_DEFAULT_MS}; a number below {@link SERVING_LEASE_TTL_FLOOR_MS} (zero and negatives included) ⇒ the
+ * floor; otherwise the number, truncated to whole ms, with no ceiling. It is for the ISSUING side's configuration. A reply's
+ * `ttlMs` is used exactly as granted and is never clamped upward — an engine that stretched a short grant to the floor would
+ * hold the lease past what the center recorded, which is the one thing the fence exists to prevent.
+ */
+export function clampServingLeaseTtlMs(configuredMs) {
+    if (typeof configuredMs !== "number" || !Number.isFinite(configuredMs))
+        return SERVING_LEASE_TTL_DEFAULT_MS;
+    return Math.max(SERVING_LEASE_TTL_FLOOR_MS, Math.floor(configuredMs));
+}
+/**
+ * Engine → center: "may this instance keep serving?" The identity triple names the instance exactly — a lease is never
+ * asked for by worker name alone. `generation` is the env echo ({@link FLEET_GENERATION_ENV}); `instanceId` is the engine's
+ * own per-process identity ({@link EngineSignal}`.instanceId`), so a restarted process is a NEW instance to the center.
+ * `scope` is the tenant scope the worker lives in (absent = the single-scope deployment). Only fleet members ask: an engine
+ * without a generation (the standalone form) has no lease and sends nothing.
+ */
+export const ServingLeaseRequest = z.object({
+    worker: z.string().min(1),
+    scope: z.string().min(1).optional(),
+    generation: Generation,
+    instanceId: z.string().min(1),
+});
+/**
+ * Why a lease is refused — a CLOSED set of exactly two words, owned here:
+ *  - `superseded` — a newer generation of this worker has taken over; this instance is the old one.
+ *  - `retired` — the center has retired this instance (or the worker it belongs to).
+ * Only {@link ServingLeaseResponse}'s `denied` arm carries a reason; `unknown` has none, by shape.
+ */
+export const SERVING_LEASE_DENIED_REASONS = ["superseded", "retired"];
+export const ServingLeaseDeniedReason = z.enum(SERVING_LEASE_DENIED_REASONS);
+const ServingLeaseGranted = z.object({ verdict: z.literal("granted"), ttlMs: z.number().int().positive() });
+const ServingLeaseDenied = z.object({ verdict: z.literal("denied"), reason: ServingLeaseDeniedReason });
+const ServingLeaseUnknown = z.object({ verdict: z.literal("unknown") });
+/**
+ * Center → engine: the verdict, a CLOSED set of three words ({@link SERVING_LEASE_VERDICTS}) — the arms of one
+ * discriminated union, so a reader that switches on `verdict` is told by the compiler when a word is added.
+ *  - `granted` — keep serving; `ttlMs` is how long the lease lasts, a DURATION, never a wall-clock instant: the engine counts
+ *    it from the instant it SENT the request, on its own monotonic clock (`expiresAt = sendAt + ttlMs`), and the center keeps
+ *    its own expiry from its store time — the two sides never compare clocks, so no clock agreement is needed.
+ *  - `denied` — this instance must stop: `reason` is {@link ServingLeaseDeniedReason}. The ONLY arm that obliges an engine to
+ *    stop serving, and it is issued on POSITIVE evidence only: the center keeps, per (scope, worker), a persisted generation
+ *    floor that is never garbage-collected, and a request whose generation lies below it is `superseded`; `retired` likewise
+ *    rests on a record the center holds. A center that merely holds no such record does not deny — it answers `unknown`.
+ *  - `unknown` — the center holds no lifecycle object for this instance right now (restoring its store, migrating scopes, not
+ *    yet claimed). It says NOTHING about whether the instance should serve, so it is not a kind of `denied` and absence of the
+ *    object NEVER turns into a denial: it carries no reason, and an engine never drains on it. To the engine it is the same
+ *    case as an unreachable center.
+ * This is the law for what a center SENDS. A reader does not apply it to `reason`: {@link readServingLeaseResponse} judges by
+ * the `verdict` key and keeps a `denied` a `denied` even when its reason is outside the set ({@link ServingLeaseReading}). A
+ * reply whose `verdict` itself is outside the three words (or a `granted` with no valid `ttlMs`) is not a verdict at all and
+ * reads as `undefined` — an unreachable center, never `denied`, never `granted`.
+ */
+export const ServingLeaseResponse = z.discriminatedUnion("verdict", [ServingLeaseGranted, ServingLeaseDenied, ServingLeaseUnknown]);
+/** The reason word a READER puts in place of a `denied` reason it cannot place (outside {@link SERVING_LEASE_DENIED_REASONS},
+ *  missing, not a string). Read-face only: a producer never sends it, and the strict {@link ServingLeaseResponse} refuses it. */
+export const SERVING_LEASE_UNKNOWN_REASON = "unknown_reason";
+const isServingLeaseDeniedReason = (w) => SERVING_LEASE_DENIED_REASONS.includes(w);
+/** What a reader makes of the `denied` arm: it is judged by the `verdict` key ALONE, and `reason` is diagnostic — a reason it
+ *  can place is kept, anything else becomes {@link SERVING_LEASE_UNKNOWN_REASON}. The arm is still `denied`. */
+const ServingLeaseDeniedRead = z.object({
+    verdict: z.literal("denied"),
+    reason: z.unknown().transform((r) => (isServingLeaseDeniedReason(r) ? r : SERVING_LEASE_UNKNOWN_REASON)),
+});
+/** The read face of {@link ServingLeaseResponse} — same three arms, with the `denied` arm tolerant about `reason`. */
+const ServingLeaseReadFace = z.discriminatedUnion("verdict", [ServingLeaseGranted, ServingLeaseDeniedRead, ServingLeaseUnknown]);
+/** The verdict words as a runtime list. `satisfies` bites a word the union does not have; the converse (a union arm missing
+ *  from this list) is pinned by a test that reads the union's discriminators. */
+export const SERVING_LEASE_VERDICTS = ["granted", "denied", "unknown"];
+/** Center side: the request body of a serving-lease renewal. Shape mismatch / non-object / throwing accessor ⇒ `undefined`,
+ *  never throws (same guarded reader as every other read in this file). */
+export function readServingLeaseRequest(body) {
+    return readSignalBody(body, wholeBody, ServingLeaseRequest);
+}
+/** Engine side: the reply to a renewal, judged by its `verdict` key: `granted` needs a valid `ttlMs`, `denied` is `denied`
+ *  whatever its `reason` (see {@link ServingLeaseReading}), `unknown` is `unknown`. A non-object, a throwing accessor, a
+ *  `verdict` outside the three words or a `granted` without a valid `ttlMs` ⇒ `undefined`, never throws — and `undefined`
+ *  is read like an unreachable center, never like `denied` and never like `granted`. */
+export function readServingLeaseResponse(body) {
+    return readSignalBody(body, wholeBody, ServingLeaseReadFace);
+}
+/**
+ * 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.
+ * This package fixes the shape and the reader, not which center endpoint carries the object.
+ */
+export const CenterCapabilities = z.object({
+    servingLease: z.literal(true).optional(),
+});
+/** 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 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
+ * call from the center) this HTTP request is how an instance is drained; on the Kubernetes lane no per-pod HTTP call is made
+ * (per-pod addressing and RBAC make it the wrong tool) — an instance is drained by its serving lease being denied
+ * ({@link ServingLeaseResponse}), after which the engine puts itself into draining.
+ *  - `actionId` — idempotency key: the same id again echoes the first answer ({@link DrainReceipt}`.state` =
+ *    `already_draining`) and changes nothing.
+ *  - the identity — `scope?` / `worker` / `expectedGeneration?` / `instanceId?` — names WHICH instance the action is for. The
+ *    engine compares it field by field against its own, absent against absent: an engine that is not a fleet member has no
+ *    generation, so a request with no `expectedGeneration` is the standalone form, not a wildcard; `instanceId`, when given,
+ *    is the engine's own per-process identity ({@link EngineSignal}`.instanceId`). A mismatch is the endpoint's refusal, not
+ *    this shape's: this schema only says what a well-formed request looks like.
+ *  - `deadlineAt` — epoch ms by which the engine stops on its own.
+ *  - `term` — the claim term the sending executor holds for this action (center-issued, opaque); absent where no executor
+ *    sits in between (a direct call, a hand-issued action).
+ */
+export const DrainRequest = z.object({
+    actionId: z.string().min(1),
+    scope: z.string().min(1).optional(),
+    worker: z.string().min(1),
+    expectedGeneration: Generation.optional(),
+    instanceId: z.string().min(1).optional(),
+    deadlineAt: EpochMs,
+    term: z.string().min(1).optional(),
+});
+/** What a drain request leaves the engine in: `draining` — this call put it into draining; `already_draining` — it already was
+ *  (the same action repeated), and the receipt reports the first call's facts. */
+export const DRAIN_RECEIPT_STATES = ["draining", "already_draining"];
+export const DrainReceiptState = z.enum(DRAIN_RECEIPT_STATES);
+/** The drain endpoint's answer: the engine's draining fact ({@link EngineDraining} — the same object {@link EngineSignal}
+ *  carries as `draining`, extended, not copied) plus how this call found the engine. */
+export const DrainReceipt = EngineDraining.extend({ state: DrainReceiptState });
+/** Engine side: the request body of the drain endpoint. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
+export function readDrainRequest(body) {
+    return readSignalBody(body, wholeBody, DrainRequest);
+}
+/** Caller side: the drain endpoint's answer. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
+export function readDrainReceipt(body) {
+    return readSignalBody(body, wholeBody, DrainReceipt);
+}
 // ── Domain 3: dispatch policy (traffic + failover + LB — three domains, one gateway) ──────────────────────
 export const DISPATCH_STRATEGIES = ["round-robin", "least-inflight", "consistent-hash"];
 /** Per-worker dispatch policy (center-configured; the gateway is OPTIONAL — D3: TOC/self-maintained TOB go

package/dist/types.js

@@ -17,7 +17,7 @@
  */
 import { z } from "zod";
 import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody depth cap with the hash cap (R18)
-import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
+import { DispatchPolicy, FLEET_GENERATION_ENV } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
 import { carriesUserinfo, percentLayers } from "./secret-scan.js"; // package-private normalization + the userinfo judgement (not in the barrel)
 import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
 import { LANE_ENV_OWNER, MIGRATION_SIGNPOST, isMigratableEnvKey, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (not in the barrel)
@@ -1569,6 +1569,8 @@ const RESERVED_ENV_FIELD = Object.freeze({
     PG_DATABASE: "runtime.store.db.database", PG_PASSWORD: "secretRefs.dbPasswordEnv",
     // ── runtime.execution(7.0.0):车道词两键 + 车道表里每个名(派生,不手抄)
     REMOTE_EXEC: "runtime.execution.lane",
+    // ── fleet 成员身份:渲染器按该 worker 的代际写它,引擎读回并回声成 EngineSignal.generation —— 没有 WorkerSpec 字段能写它
+    [FLEET_GENERATION_ENV]: "(set by the config renderer from the worker's generation — not configurable)",
     REQUIRE_EXECUTION_LANE: "runtime.execution.lane (the renderer emits REQUIRE_EXECUTION_LANE=true for every declared lane)",
     ...Object.fromEntries([...LANE_ENV_OWNER].map(([name, owner]) => [name, laneEnvSeat(name, owner)])),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "8.0.0",
+  "version": "8.1.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",