@sema-agent/settings-schema 8.1.0 → 8.3.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,6 +81,29 @@ 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
@@ -234,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 */
@@ -292,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;
@@ -310,6 +386,9 @@ export declare const InstanceAnnouncement: z.ZodObject<{
         entries: Record<string, string>;
         plane?: string | undefined;
     } | undefined;
+    generation?: string | undefined;
+    leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
+    leaseUntil?: number | undefined;
 }, {
     version: string;
     instanceId: string;
@@ -325,6 +404,9 @@ export declare const InstanceAnnouncement: z.ZodObject<{
     } | 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. */
@@ -401,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;
@@ -425,6 +521,9 @@ export declare const InstanceRegistration: z.ZodObject<{
         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;
@@ -443,6 +542,9 @@ export declare const InstanceRegistration: z.ZodObject<{
     } | undefined;
     modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
+    generation?: unknown;
+    leaseState?: unknown;
+    leaseUntil?: unknown;
     observedReady?: boolean | undefined;
 }>;
 export type InstanceRegistration = z.infer<typeof InstanceRegistration>;
@@ -475,18 +577,24 @@ export declare const EngineDraining: z.ZodObject<{
     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.
+ * 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
@@ -499,8 +607,10 @@ export declare function compareGeneration(a: string, b: string): -1 | 0 | 1;
  *  - `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}); absent when it holds none.
+ *    `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).
  *
@@ -543,6 +653,7 @@ export declare const EngineSignal: z.ZodObject<{
     }>>;
     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>;
@@ -561,6 +672,7 @@ export declare const EngineSignal: z.ZodObject<{
     } | undefined;
     instanceId?: string | undefined;
     generation?: string | undefined;
+    leaseState?: "none" | "granted" | "expired" | "denied" | undefined;
     leaseUntil?: number | undefined;
     configTargetVersion?: string | undefined;
     configAppliedVersion?: string | undefined;
@@ -579,16 +691,17 @@ export declare const EngineSignal: z.ZodObject<{
     } | 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}, 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").
+ * 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;
 /**
@@ -599,6 +712,18 @@ export declare function readEngineSignal(health: unknown): EngineSignal | undefi
  * ({@link EngineSignal}`.instanceId`), and env cannot carry it (see there).
  */
 export declare const FLEET_GENERATION_ENV = "FLEET_GENERATION";
+/**
+ * The env name a fleet member's tenant scope travels under — the config renderer sets it to the scope this member's per-worker
+ * token binds (the same value, taken from the same place the token is issued for), and the engine reads it as the scope of its
+ * OWN identity: the scope it compares a {@link DrainRequest}'s `scope` against, sends as {@link ServingLeaseRequest}`.scope`, and
+ * names on its heartbeat ({@link InstanceAnnouncement}'s `?scope=`). Both sides import THIS constant; neither spells the name.
+ * One fact, one source: the scope is GIVEN by the renderer — the engine never derives it from the token's format (a token is
+ * opaque to it, and a format guess would be a second source that can disagree with the scope the center binds). Absent from
+ * the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) — the same default the center reads where nothing
+ * names a scope; this note does not restate the value. Like {@link FLEET_GENERATION_ENV} it is a reserved worker env name
+ * (`WorkerSpec.env` / `secretEnv` cannot set it).
+ */
+export declare const FLEET_SCOPE_ENV = "FLEET_SCOPE";
 /**
  * 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
@@ -625,8 +750,11 @@ export declare function clampServingLeaseTtlMs(configuredMs: number | undefined)
  * 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.
+ * `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;
@@ -758,7 +886,10 @@ export declare function readServingLeaseResponse(body: unknown): ServingLeaseRea
  * 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.
+ * 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>>;
@@ -768,6 +899,14 @@ export declare const CenterCapabilities: z.ZodObject<{
     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;

package/dist/fleet.js

@@ -19,6 +19,43 @@
  */
 import { z } from "zod";
 import { fnv1a64 } from "./hash.js";
+// ── The center's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
+/**
+ * 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 const FLEET_PATHS = {
+    instances: "/api/fleet/instances",
+    usage: "/api/fleet/usage",
+    quotaLeases: "/api/fleet/leases",
+    servingLease: "/api/fleet/live/serving-lease",
+    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 const FLEET_LIVE_PATHS = [FLEET_PATHS.instances, FLEET_PATHS.servingLease, FLEET_PATHS.hostPlanner];
 // ── Domain 1: drain protocol (graceful rolling update — the ground every form stands on) ──────────────────
 /** 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`. */
@@ -42,6 +79,50 @@ export function drainVerdict(s) {
 }
 /** A wall-clock instant as epoch milliseconds — one quantity, one rule, wherever the fleet contract carries a point in time. */
 const EpochMs = z.number().int().nonnegative();
+/**
+ * A 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)" });
+/**
+ * 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 const LEASE_STATES = ["none", "granted", "expired", "denied"];
+export const LeaseState = z.enum(LEASE_STATES);
 /**
  * "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
@@ -236,7 +317,10 @@ export 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 const InstanceAnnouncement = z.object({
     instanceId: z.string().min(1),
     /** worker (deployment) this instance belongs to — the dispatch key */
@@ -264,6 +348,20 @@ export const InstanceAnnouncement = z.object({
      *  ABSENT (`.catch`) — it never fails the announcement, so it can never make a healthy instance unroutable (unlike
      *  `restart`, whose shape still gates the row). The key may then be present with the value `undefined`. */
     modelRefusals: ModelRefusalsWire.optional().catch(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: Generation.optional().catch(undefined),
+    leaseState: LeaseState.optional().catch(undefined),
+    leaseUntil: EpochMs.optional().catch(undefined),
 });
 /** Explicit goodbye (stop signal handler) — removes the row immediately instead of waiting out staleness. */
 export const InstanceDeregistration = z.object({
@@ -305,40 +403,24 @@ export const EngineDraining = z.object({
     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.
+ * 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
@@ -351,8 +433,10 @@ const Generation = z.string().refine(isCanonicalGeneration, { message: "a genera
  *  - `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}); absent when it holds none.
+ *    `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).
  *
@@ -368,15 +452,16 @@ export const EngineSignal = z.object({
     restart: RestartSignal.optional(),
     generation: Generation.optional(),
     instanceId: z.string().min(1).optional(),
+    leaseState: LeaseState.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").
+ * 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 function readEngineSignal(health) {
     return readSignalBody(health, wholeBody, EngineSignal);
@@ -389,6 +474,18 @@ export function readEngineSignal(health) {
  * ({@link EngineSignal}`.instanceId`), and env cannot carry it (see there).
  */
 export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
+/**
+ * The env name a fleet member's tenant scope travels under — the config renderer sets it to the scope this member's per-worker
+ * token binds (the same value, taken from the same place the token is issued for), and the engine reads it as the scope of its
+ * OWN identity: the scope it compares a {@link DrainRequest}'s `scope` against, sends as {@link ServingLeaseRequest}`.scope`, and
+ * names on its heartbeat ({@link InstanceAnnouncement}'s `?scope=`). Both sides import THIS constant; neither spells the name.
+ * One fact, one source: the scope is GIVEN by the renderer — the engine never derives it from the token's format (a token is
+ * opaque to it, and a format guess would be a second source that can disagree with the scope the center binds). Absent from
+ * the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) — the same default the center reads where nothing
+ * names a scope; this note does not restate the value. Like {@link FLEET_GENERATION_ENV} it is a reserved worker env name
+ * (`WorkerSpec.env` / `secretEnv` cannot set it).
+ */
+export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
 /**
  * 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
@@ -419,8 +516,11 @@ export function clampServingLeaseTtlMs(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.
+ * `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 const ServingLeaseRequest = z.object({
     worker: z.string().min(1),
@@ -497,11 +597,22 @@ export function readServingLeaseResponse(body) {
  * 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.
+ * 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 const CenterCapabilities = z.object({
     servingLease: z.literal(true).optional(),
 });
+/**
+ * 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 const HEARTBEAT_REPLY_CAPABILITIES_KEY = "capabilities";
 /** Engine side: the center's capability object. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws
  *  (and `undefined` means "no capability said" — the same as every bit absent). */
 export function readCenterCapabilities(body) {

package/dist/issue-text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The ONE rendering of a zod issue into a sentence that may leave in a report which promises to name fields, never values (the
+ * workers migration's `refused[].reason`, the `migrate-workers` CLI report). Internal — not on any package subpath.
+ *
+ * zod's own messages name the expected shape, not the input, with one exception: the default `invalid_enum_value` message ends in
+ * `, received '<the value>'`. That issue is re-worded from its options alone (the closed set it expected); every other issue keeps
+ * its message as is. The result still goes through the usual secret redaction where the caller applies it.
+ */
+import type { z } from "zod";
+export declare function issueText(issue: z.ZodIssue): string;

package/dist/issue-text.js

@@ -0,0 +1,8 @@
+export function issueText(issue) {
+    switch (issue.code) {
+        case "invalid_enum_value":
+            return `Invalid enum value. Expected ${issue.options.map((o) => `'${String(o)}'`).join(" | ")}`;
+        default:
+            return issue.message;
+    }
+}