@sema-agent/settings-schema 6.0.0 → 6.2.0

package/dist/fleet.js

@@ -40,6 +40,151 @@ export function drainVerdict(s) {
     const grace = Math.max(DRAIN_GRACE_FLOOR_MS, s.graceMs);
     return s.nowMs - s.startedMs >= grace ? "exit_forced" : "wait";
 }
+/**
+ * "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:
+ * 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;
+ *    the contract only guarantees non-empty words, at least one).
+ *  - `version` — the config-center version that currently differs from boot (the LATEST seen — it moves forward with
+ *    later publishes, so a "one restart per version" dedupe bounds restarts per config version, not per reason set).
+ *    Judged exactly as `readEffectiveWire` judges a config version (a finite number) — one quantity, one rule.
+ *  - `since` — epoch ms when this restart first became required (stable across refreshes while `reasons` holds).
+ */
+export const RestartSignal = z.object({
+    reasons: z.array(z.string().min(1)).min(1),
+    version: z.number().finite(),
+    since: z.number().int().nonnegative(),
+});
+/**
+ * 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).
+ */
+function readHealthSignal(health, key, schema) {
+    try {
+        if (health === null || typeof health !== "object" || Array.isArray(health))
+            return undefined;
+        const parsed = schema.safeParse(health[key]);
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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);
+}
+/**
+ * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
+ * one edit in this file; who goes red at compile time: a reader that switches on the code exhaustively (a center), and
+ * a producer only where it holds a table KEYED BY the code (an exhaustive `switch` over the code, or a
+ * `Record<ModelEntryRefusalCode, …>`) — a producer table that merely `satisfies` these codes as values proves a subset,
+ * not equality, and stays green.
+ *
+ *  - {@link MODEL_ENTRY_REFUSAL_CODES} — why ONE catalog entry is not served on this host (the other entries keep serving):
+ *    `config.model_no_brain` — the entry's provider rides a brain this host has not mounted;
+ *    `config.model_entry_invalid` — the entry does not match the `ModelEntry` shape (dropped by the read, or re-judged at
+ *    the engine's own second boundary).
+ *  - {@link MODEL_PLANE_REFUSAL_CODES} — why the model plane of the catalog the engine was handed was refused AS A GROUP
+ *    (the engine keeps serving the model plane it had). This set mirrors the engine's group-refusal code TABLE as a
+ *    whole family — never picked by which invariant is reachable on the hot path today (reachability moves, the table
+ *    does not):
+ *    `config.default_model_missing` — the candidate has no default model;
+ *    `config.model_refused_name_minted` — a refused entry's name would be re-minted onto another entry by the
+ *    tier / alias expansion (or the dropped-entry carrier cannot prove it would not be);
+ *    `config.model_route_endpoint_missing` — an openai-compatible route of the candidate resolves to no endpoint;
+ *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary.
+ *    Source (engine): the first two in `src/model-entry-refusal.ts`, the last two in `src/model-route-endpoint.ts:40,42`
+ *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`).
+ */
+export const MODEL_ENTRY_REFUSAL_CODES = ["config.model_no_brain", "config.model_entry_invalid"];
+export const ModelEntryRefusalCode = z.enum(MODEL_ENTRY_REFUSAL_CODES);
+export const MODEL_PLANE_REFUSAL_CODES = [
+    "config.default_model_missing",
+    "config.model_refused_name_minted",
+    "config.model_route_endpoint_missing",
+    "config.gateway_fallback_without_primary",
+];
+export const ModelPlaneRefusalCode = z.enum(MODEL_PLANE_REFUSAL_CODES);
+/**
+ * "This instance does not serve part (or all) of the model catalog it was handed" — the engine's OWN per-host verdict
+ * (S-768), defined ONCE for both exits that carry it: the fleet heartbeat ({@link InstanceAnnouncement}`.modelRefusals`)
+ * and GET /health (`modelRefusals`; {@link InstanceHealth} keeps carrying it untyped, as it does `restart`). One mint point,
+ * two exits, ONE reader for both: {@link readModelRefusals}.
+ *
+ * Two faces, split on purpose — the failure direction must match the meaning (this is a DIAGNOSTIC key; an unknown word
+ * in it must never make a healthy instance unroutable):
+ *  - {@link ModelRefusalsWire} — what rides the wire and what a stored heartbeat row holds: the SHAPE law only, codes as
+ *    open non-empty strings. A code this package version does not know passes (it is "not said" to this reader, and the
+ *    stored row still carries it for a reader that is upgraded later).
+ *  - {@link ModelRefusalsSignal} — what {@link readModelRefusals} returns: the wire narrowed to the closed sets above (an
+ *    unknown entry code or plane code is dropped; narrowed to nothing ⇒ `undefined`, rendered like "not said"). The
+ *    closed-set types stay the compile-time red source for readers when a code is added.
+ *
+ * The wire shape:
+ *  - `entries` — catalog entry NAME → its code. The value is ONLY the code, on purpose: the engine's refusal fact also
+ *    holds the upstream `id`, the `provider` word, the bad field keys and an operator sentence, and none of them rides
+ *    here — an `entry_invalid` row is by definition one nothing validated, so its `id` / `provider` may be whatever the
+ *    broken row held, and the sentence is prose, not contract. "Which name, which reason" is the whole wire. A name that
+ *    cannot ride out is treated as NAMELESS — the engine leaves it out of this map entirely (not keyed, not counted). The
+ *    ONE predicate is `isReportableRefusalName(name)` (main barrel): this schema can carry the key (non-empty; `__proto__`
+ *    is silently dropped by the record, so it cannot) AND `isDisclosableIdentity(name)` (not secret-shaped — the rule the
+ *    dropped-entry identity on read warnings already uses). A producer calls it before keying; this schema deliberately
+ *    does not re-judge secrecy (see the 6.2.0 notes).
+ *  - `plane` — present ⇔ the model plane of the latest catalog the engine was handed was refused as a group (the engine
+ *    keeps serving the model plane it had); ONE code, never a list — one candidate has exactly one group verdict (the
+ *    engine judges the group invariants in a fixed order and stops at the first that fails; a refusal from the Runner
+ *    swap step carries no code and is outside this signal).
+ *  - `entries` and `plane` describe the same latest candidate catalog — the one the engine was handed last; with `plane`
+ *    present, that is the refused candidate (its per-entry verdicts are usually why it has no default). The engine does
+ *    not swap its own refusal table while the group stays refused (its selection channels still refuse by the previous
+ *    generation), so with `plane` present read `entries` as "why this catalog cannot land", not "what a pick is refused
+ *    right now".
+ *
+ * PRESENCE is the signal (same law as {@link RestartSignal}): present ⇔ at least one reportable refusal (an entry refusal
+ * under a name that rides out, or a group refusal). An empty signal (no entries and no `plane`) is refused by the shape
+ * law — "none" has exactly one spelling, the absent key. Inside, "no entry refusals" is spelled `entries: {}` (the key is
+ * required) — one spelling at each level.
+ */
+export const ModelRefusalsWire = z
+    .object({
+    entries: z.record(z.string().min(1), z.string().min(1)),
+    plane: z.string().min(1).optional(),
+})
+    .refine((s) => Object.keys(s.entries).length > 0 || s.plane !== undefined, {
+    message: "an empty model-refusals signal is not a signal — omit the key instead (absent ⇔ no reportable refusals)",
+});
+const isModelEntryRefusalCode = (c) => MODEL_ENTRY_REFUSAL_CODES.includes(c);
+const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
+/**
+ * The ONE reader of the model-refusals signal, for BOTH exits: pass a /health body or a parsed
+ * {@link InstanceAnnouncement} — it reads the `modelRefusals` key of whatever it is given. Shape mismatch, a missing key, a
+ * non-object body, even a throwing accessor ⇒ `undefined` — never throws. Then it narrows to the closed sets: an unknown
+ * entry code drops that entry, an unknown plane code drops `plane`; narrowed to nothing ⇒ `undefined`. So `undefined`
+ * means "nothing this reader can say"; whether that is "none" or "unknown" depends on whether the engine reports this key
+ * 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);
+    if (wire === undefined)
+        return undefined;
+    const entries = Object.fromEntries(Object.entries(wire.entries).filter((e) => isModelEntryRefusalCode(e[1])));
+    const plane = wire.plane !== undefined && isModelPlaneRefusalCode(wire.plane) ? wire.plane : undefined;
+    if (Object.keys(entries).length === 0 && plane === undefined)
+        return undefined;
+    return plane === undefined ? { entries } : { entries, plane };
+}
 /** The `/health` self-description every orchestrator reads (shipped shape, server 1.96.0). Liveness and
  *  readiness are deliberately SPLIT: `status` stays ok while draining (the process is alive); routability is
  *  `isReadyForTraffic`. Unknown fields pass through — health is a self-description, not a closed record. */
@@ -52,6 +197,11 @@ export const InstanceHealth = z
     draining: z.boolean().optional(),
     /** epoch ms, present iff draining */
     drainingSince: z.number().optional(),
+    // S-741: the server's `restart` (and its redundant top-level `restartRequired` boolean) ride the passthrough
+    // UNTYPED on purpose — typing `restart` here would turn today's lenient read into a strict one (a /health body with
+    // an odd `restart` would stop parsing), which is a MAJOR by this package's release rules. Read it with
+    // {@link readRestartSignal}. Typing it on this schema is an item for the next major.
+    // 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). */
@@ -76,10 +226,26 @@ export const InstanceAnnouncement = z.object({
     /** reachable base URL for the deployment form: k8s pod IP:port / docker net alias / 127.0.0.1:<engine.port> */
     address: z.string().min(1),
     version: z.string().min(1),
-    /** self-declared: bootDone && !draining */
+    /** self-declared readiness: model roster landed AND not draining (server ≥7.102.0; older engines: !draining only) */
     ready: z.boolean(),
     draining: z.boolean().default(false),
     heartbeatMs: z.number().int().positive().default(DEFAULT_HEARTBEAT_MS),
+    /** S-741: present ⇔ this instance must restart to apply config — the SAME {@link RestartSignal} /health carries,
+     *  minted by the same getter (self-reported: a worker-scoped credential can only report for its own worker).
+     *  Every heartbeat re-announces the full row, so a later heartbeat WITHOUT it means "no longer required" — the
+     *  stored row ({@link InstanceRegistration}) is replaced, never merged. */
+    restart: RestartSignal.optional(),
+    /** 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
+     *  directly: the field is the open wire form, the reader narrows to the closed sets). Every heartbeat re-announces the
+     *  full row, so a later heartbeat WITHOUT it means "no reportable refusals any more" (the stored row is replaced, never
+     *  merged). Reading absence: from an engine that reports this key, absent = none reportable; an engine that predates
+     *  the key never sends it, so there absence is UNKNOWN, not "none" — tell the two apart by the announced `version`.
+     *  Failure direction = meaning direction (this is a diagnostic key): a code this package version does not know passes
+     *  (it is "not said" to the reader), and a value that breaks the {@link ModelRefusalsWire} shape law is dropped to
+     *  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),
 });
 /** Explicit goodbye (stop signal handler) — removes the row immediately instead of waiting out staleness. */
 export const InstanceDeregistration = z.object({

package/dist/index.d.ts

@@ -21,3 +21,4 @@ export * from "./migrate.js";
 export * from "./api/auth.js";
 export * from "./api/auth-bridge.js";
 export * from "./api/scopes.js";
+export * from "./center-credential.js";

package/dist/index.js

@@ -21,6 +21,7 @@ export * from "./migrate.js"; // 0.5→0.6 migration tools (hosts grandfathering
 export * from "./api/auth.js"; // /api/v1/auth/* wire contract (RFC 8628 device flow + rotating refresh + logout + approve) — REGISTRY-REBUILD-DESIGN §2, M1 shipped shapes frozen, pure/browser-safe
 export * from "./api/auth-bridge.js"; // 鉴权桥 contract: worker verifies registry user JWT (RS256-only, JWKS kid-miss refresh + throttle, offline grace fail-closed) → VerifiedIdentity — design §5, the service verifier's spec
 export * from "./api/scopes.js"; // multi-tenant scope contract: /api/v1/scopes* + /api/v1/auth/scope wire shapes + THE minting/switch decision functions (resolveTokenScope / canSwitchScope / effectiveScopeRole / tokenScopeOf) — registry imports these, never re-implements
+export * from "./center-credential.js"; // S-698 center-credential FILE contract: CenterCredentialEnvelope (user-session envelope, strict) + parseCenterCredentialFile (bare / envelope / unreadable — the one discrimination law) + S-742 CENTER_CREDENTIAL_ENV (the two declaration keys) + judgeCenterCredentialDeclaration (pick-exactly-one), pure/browser-safe
 // NOTE: the Node-fs-backed helpers (FileConfigStore + the file editor) are NOT in this barrel — they pull
 // `node:fs`/`node:path` and would break a browser/client bundle that only wants the contract (e.g.
 // sema-registry's client components import the zod types through here). Import them from the Node-only