@sema-agent/settings-schema 8.0.0 → 8.2.0

package/dist/fleet.d.ts

@@ -18,6 +18,42 @@
  *     the skeleton does not move).
  */
 import { z } from "zod";
+/**
+ * The center's `/api/fleet/*` endpoints that are addressed from outside the center, relative to its origin. ONE spelling: whoever
+ * calls one (the engine, the executor) and whoever serves or routes it (the center, the deployment's Service / Ingress) imports it
+ * here — nobody writes the string. Membership rule: an endpoint is here iff this package types its body, or it belongs to the
+ * liveness group ({@link FLEET_LIVE_PATHS}); a center-internal route is not.
+ *  - `instances` — `POST` = the heartbeat ({@link InstanceAnnouncement}; its 2xx reply carries the center's
+ *    {@link CenterCapabilities} under {@link HEARTBEAT_REPLY_CAPABILITIES_KEY}), `DELETE` = the goodbye ({@link InstanceDeregistration}).
+ *  - `usage` — `POST` a {@link UsageReport}.
+ *  - `quotaLeases` — the quota lease ({@link QuotaLease}).
+ *  - `servingLease` — `POST` a {@link ServingLeaseRequest}, answered with a {@link ServingLeaseResponse}.
+ *  - `hostPlanner` — `GET` one host's planner record, for the executor (its body is the center's and the executor's contract, not
+ *    this package's; it is here because the deployment routes it as a member of the liveness group).
+ * Notation: a value is a path TEMPLATE — a parameter is a whole segment written `{name}` (`hostPlanner` ends in `/{host}`, filled
+ * with the URL-encoded host id); the other values have none and are the path itself. A prefix router (an Ingress rule) takes the
+ * template up to its first `{`.
+ */
+export declare const FLEET_PATHS: {
+    readonly instances: "/api/fleet/instances";
+    readonly usage: "/api/fleet/usage";
+    readonly quotaLeases: "/api/fleet/leases";
+    readonly servingLease: "/api/fleet/live/serving-lease";
+    readonly hostPlanner: "/api/fleet/live/host-planner/{host}";
+};
+/**
+ * The LIVENESS group — the fleet endpoints a center answers without its readiness gate and without its config-governance gates
+ * (they read no config domain and take service credentials only), so that a center whose management face is refused never turns
+ * into a fleet that gets no answers. A deployment routes exactly these past the readiness gate (on Kubernetes: a second Service
+ * with `publishNotReadyAddresses`, and the Ingress rules for them point at it). Membership is THIS list, not a path prefix — the
+ * heartbeat predates the `/api/fleet/live/` prefix; every {@link FLEET_PATHS} entry under that prefix is a member. The
+ * quota-lease and usage endpoints are not.
+ *
+ * The same two constants ship as JSON for tooling that cannot import TypeScript (a Helm chart, a smoke script): the subpath
+ * `@sema-agent/settings-schema/fleet-paths.json` is `{ "FLEET_PATHS": …, "FLEET_LIVE_PATHS": … }`, written from these values at
+ * build time — never edited by hand.
+ */
+export declare const FLEET_LIVE_PATHS: readonly ["/api/fleet/instances", "/api/fleet/live/serving-lease", "/api/fleet/live/host-planner/{host}"];
 /** Lifecycle of a draining instance. `running`→`draining` on the stop signal; `drained` once in-flight hits
  *  zero (clean) or the grace deadline forces the issue. Exit always follows `drained`. */
 export declare const DRAIN_PHASES: readonly ["running", "draining", "drained"];
@@ -45,13 +81,37 @@ export type DrainVerdict = "wait" | "exit_clean" | "exit_forced";
 /** The drain state machine's single decision point: keep waiting, exit clean (drained), or force the exit
  *  (grace exhausted with legs still in flight — durable legs resume cross-instance via resumeFromRunId). */
 export declare function drainVerdict(s: DrainSnapshot): DrainVerdict;
+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;
+/**
+ * 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.
+ *  - `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
+ *    not granted one yet): the engine keeps serving until its own outage allowance runs out. Not a denial.
+ *  - `denied` — the center denied this instance on positive evidence (the `denied` verdict): sticky; the engine is draining and
+ *    stops at its deadline.
+ * Only a fleet member says it: an engine without a generation has no lease and carries no `leaseState` at all (there is no
+ * fifth word for "not a member" — absence is that).
+ */
+export declare const LEASE_STATES: readonly ["none", "granted", "expired", "denied"];
+export declare const LeaseState: z.ZodEnum<["none", "granted", "expired", "denied"]>;
+export type LeaseState = z.infer<typeof LeaseState>;
 /**
  * "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;
@@ -60,19 +120,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 +278,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). */
@@ -222,7 +293,10 @@ export declare const STALE_HEARTBEAT_MULTIPLIER = 2;
 /** Register/heartbeat upsert (worker → center, D2: worker-active). ONE shape for both — registration is the
  *  first heartbeat; every heartbeat re-announces the full row (idempotent upsert, no drift between a
  *  "register" and a "renew" schema). `draining:true` is the instance SELF-removing from the routable set the
- *  moment the stop signal lands — faster than any observer. */
+ *  moment the stop signal lands — faster than any observer.
+ *  Scope: the body carries NO `scope` — this shape has no such key, and one sent anyway is stripped. The row lands in the scope
+ *  the CREDENTIAL names: under a per-worker token, the scope the token binds (a `?scope=` query parameter, when given, must equal
+ *  it); under the shared token, the `?scope=` query parameter, absent ⇒ `"global"`. */
 export declare const InstanceAnnouncement: z.ZodObject<{
     instanceId: z.ZodString;
     /** worker (deployment) this instance belongs to — the dispatch key */
@@ -242,14 +316,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
@@ -277,6 +354,20 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         entries: Record<string, string>;
         plane?: string | undefined;
     }>>>;
+    /** Fleet membership and the lease reading, flat on the heartbeat body under the names and values {@link EngineSignal} gives
+     *  them (one mint point on the engine; this shape reuses that shape's schemas, not copies):
+     *  - `generation` — the canonical decimal generation ({@link isCanonicalGeneration}); present ⇔ the instance is a fleet member.
+     *  - `leaseState` — {@link LeaseState}; present ⇔ fleet member.
+     *  - `leaseUntil` — epoch ms until which the held lease runs; present ⇔ `leaseState` is `granted`.
+     *  The presence law between the three is the engine's; this shape does not judge it across keys. Every heartbeat re-announces
+     *  the full row, so a later heartbeat without a key means the engine no longer says it (the stored row is replaced, never merged).
+     *  Failure direction = meaning direction: these are evidence a center keeps, never routing input — a value that breaks its schema
+     *  drops that ONE key to ABSENT (`.catch`) and the heartbeat is still accepted, so a lease word a newer engine adds can never make
+     *  an older center refuse every heartbeat of that engine. A dropped key reads exactly like an unsaid one; the key may then be
+     *  present with the value `undefined`. */
+    generation: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
+    leaseState: z.ZodCatch<z.ZodOptional<z.ZodEnum<["none", "granted", "expired", "denied"]>>>;
+    leaseUntil: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     draining: boolean;
     version: string;
@@ -289,11 +380,15 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: {
         entries: Record<string, string>;
         plane?: string | undefined;
     } | undefined;
+    generation?: string | undefined;
+    leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
+    leaseUntil?: number | undefined;
 }, {
     version: string;
     instanceId: string;
@@ -305,9 +400,13 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
+    generation?: unknown;
+    leaseState?: unknown;
+    leaseUntil?: unknown;
 }>;
 export type InstanceAnnouncement = z.infer<typeof InstanceAnnouncement>;
 /** Explicit goodbye (stop signal handler) — removes the row immediately instead of waiting out staleness. */
@@ -346,14 +445,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
@@ -381,6 +483,20 @@ export declare const InstanceRegistration: z.ZodObject<{
         entries: Record<string, string>;
         plane?: string | undefined;
     }>>>;
+    /** Fleet membership and the lease reading, flat on the heartbeat body under the names and values {@link EngineSignal} gives
+     *  them (one mint point on the engine; this shape reuses that shape's schemas, not copies):
+     *  - `generation` — the canonical decimal generation ({@link isCanonicalGeneration}); present ⇔ the instance is a fleet member.
+     *  - `leaseState` — {@link LeaseState}; present ⇔ fleet member.
+     *  - `leaseUntil` — epoch ms until which the held lease runs; present ⇔ `leaseState` is `granted`.
+     *  The presence law between the three is the engine's; this shape does not judge it across keys. Every heartbeat re-announces
+     *  the full row, so a later heartbeat without a key means the engine no longer says it (the stored row is replaced, never merged).
+     *  Failure direction = meaning direction: these are evidence a center keeps, never routing input — a value that breaks its schema
+     *  drops that ONE key to ABSENT (`.catch`) and the heartbeat is still accepted, so a lease word a newer engine adds can never make
+     *  an older center refuse every heartbeat of that engine. A dropped key reads exactly like an unsaid one; the key may then be
+     *  present with the value `undefined`. */
+    generation: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
+    leaseState: z.ZodCatch<z.ZodOptional<z.ZodEnum<["none", "granted", "expired", "denied"]>>>;
+    leaseUntil: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
 } & {
     registeredMs: z.ZodNumber;
     lastSeenMs: z.ZodNumber;
@@ -399,11 +515,15 @@ export declare const InstanceRegistration: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: {
         entries: Record<string, string>;
         plane?: string | undefined;
     } | undefined;
+    generation?: string | undefined;
+    leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
+    leaseUntil?: number | undefined;
     observedReady?: boolean | undefined;
 }, {
     version: string;
@@ -418,18 +538,438 @@ export declare const InstanceRegistration: z.ZodObject<{
         reasons: string[];
         version: number;
         since: number;
+        withheld?: boolean | undefined;
     } | undefined;
     modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
+    generation?: unknown;
+    leaseState?: unknown;
+    leaseUntil?: unknown;
     observedReady?: boolean | undefined;
 }>;
 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>;
+/**
+ * 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 on the engine; {@link readEngineSignal} reads
+ * 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:
+ *  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`
+ * 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
+ * the target form, and `readEngineSignal` is the reader for a body that already speaks it.
+ *
+ *  - `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.
+ *  - `leaseState` — the serving lease as the engine holds it ({@link LeaseState}: `none` / `granted` / `expired` / `denied`);
+ *    present ⇔ fleet member (the engine says it on every beat once it has a generation).
+ *  - `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).
+ *
+ * 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>;
+    leaseState: z.ZodOptional<z.ZodEnum<["none", "granted", "expired", "denied"]>>;
+    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;
+    leaseState?: "none" | "granted" | "expired" | "denied" | 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;
+    leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
+    leaseUntil?: number | undefined;
+    configTargetVersion?: string | undefined;
+    configAppliedVersion?: string | undefined;
+}>;
+export type EngineSignal = z.infer<typeof EngineSignal>;
+/**
+ * The reader of {@link EngineSignal}: the shape's keys, flat on the given body, judged by 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") and for why today's heartbeat and `/health` bodies read as `undefined` here.
+ */
+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` — the tenant scope the lease is asked in. A renewal is taken on a PER-WORKER token only — the credential binds
+ * (scope, worker) — so the credential decides the scope and this field can only agree: absent = the scope the token binds; present
+ * ⇒ it must equal that scope (a mismatch is refused, never rewritten either way). The shared token may not renew a lease at all
+ * (the center answers 403). 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.
+ * 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
+ * that caller into the unreachable arm).
+ */
+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>;
+/**
+ * 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.
+ */
+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;
+/**
+ * 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 +1289,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 {};