@sema-agent/settings-schema 6.0.0 → 6.2.0

package/dist/config-fns.js

@@ -16,16 +16,28 @@
 // zod is a VALUE import here (not just a type): {@link salvageEntries} introspects a domain schema to find
 // its entry collections. zod is this package's one runtime dependency, so this costs nothing new.
 import { z } from "zod";
-import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, InfraCostRates, LimitsConfig, SkillsManifestSchema, containsSecretToken } from "./types.js";
+import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
+import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, SkillsManifestSchema, containsSecretToken } from "./types.js";
 /** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
  *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
  *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
  *  any secret-shaped run (`%` kept in the run so a percent-encoded secret stays whole for the percent-aware
- *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14. */
+ *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14.
+ *
+ *  **Output invariant** (S-712 verification pass N1 + codex review [high] ×2): a string holding a private-key PEM
+ *  header ANYWHERE ({@link PRIVATE_KEY_PEM_HEADER}) is withheld WHOLE, and no result trips `containsSecretToken`.
+ *  The PEM header is judged on the ORIGINAL text, before any replacement: the token pass can rewrite the header
+ *  itself away (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes
+ *  `[redacted-secret]` and the key body after it would ride out untouched — codex verification round). A PEM header
+ *  carries spaces, so the targeted passes can never isolate it, and the detector only sees it at the very start of
+ *  a string. Every warning face that goes through here (coordinates, error text, entry identity) inherits the same
+ *  guarantee. The validation-side detector `containsSecretToken` is deliberately NOT widened here: making it reject
+ *  a mid-string PEM would tighten every field it validates (a major). */
 export function redactSecrets(text) {
-    return text
+    const targeted = text
         .replace(/\b(bearer|basic)(\s+)\S+/gi, "$1$2[redacted-secret]")
         .replace(/[A-Za-z0-9_./:+=%-]{6,}/g, (tok) => (containsSecretToken(tok) ? "[redacted-secret]" : tok));
+    return PRIVATE_KEY_PEM_HEADER.test(text) || containsSecretToken(targeted) ? "[redacted-secret]" : targeted;
 }
 /** Sanitize a ZodError IN PLACE so no surfaced error (message / `received` / nested `unionErrors`) echoes a
  *  pasted secret. RECURSES into `unionErrors` (a `z.union` failure nests a ZodError per member — e.g. RoleTarget
@@ -173,6 +185,64 @@ const PLAIN_PATH_SEGMENT = /^(?!(?:0|[1-9]\d*)$)[^."\u0000-\u001f]+$/;
 export function formatConfigPath(p) {
     return p.map((seg) => (typeof seg === "number" ? String(seg) : PLAIN_PATH_SEGMENT.test(seg) ? seg : JSON.stringify(seg))).join(".");
 }
+/** 身份串 —— 「一个用户写的身份串(条目的 `name` / `id`)能不能**原样**出门」的**唯一**判据:
+ *  {@link redactSecrets} 原样放行。入参是 `string`、返回 `boolean`,**刻意不是**类型谓词(`v is string`):它对一些
+ *  字符串答 false,谓词形会让调用方的否定分支把一个 `string` 收窄成 `never`;「是不是字符串」由调用点自己判
+ *  (运行期收到非字符串照答 false、不抛)。秘密形的串按**无名**处置(不带,而不是打码:打过码的串不再是身份)。
+ *  与坐标段脱敏、`error` 文案脱敏({@link sanitizeZodError})**同一只**判据:告警面上任何一处用户写的串,要么过这一只
+ *  脱敏器出门,要么(可缺的身份)不出门。两只判据会在同一条告警里给出两种答案(对抗轮 #2 真复现:`Bearer` 后接 NBSP
+ *  或短令牌时,旧判据放行、坐标却打码)。
+ *  执法面(同一条律):被丢条目的身份({@link DroppedEntryIdentity},本文件铸);`ModelRefusalsWire` 的 `entries` 键
+ *  (经 {@link isReportableRefusalName},S-768);引擎自己的日志 / 拒因句里要不要写出一个名字,同样问这一只。 */
+export function isDisclosableIdentity(v) {
+    return typeof v === "string" && redactSecrets(v) === v; // 非字符串(JS / any 调用方)⇒ false,不抛(秘密轴 fail-closed)
+}
+/** S-768 —— 「一个目录条目名能不能当 {@link ModelRefusalsWire} `entries` 的键」的**唯一**判据;引擎铸键前只调这一只,
+ *  不过 ⇒ 按无名处置(不进键、不计数)。两条律的合取,不手抄任何一条:
+ *   ① 这只 schema **自己载得住**这个键 —— 就地拿 schema 判(空串不过键规则;`__proto__` 这类名被 zod 的 record 静默丢掉,
+ *      载不住),不写名单;
+ *   ② {@link isDisclosableIdentity}(秘密形 ⇒ 不出门)。
+ *  非字符串 ⇒ false。住在本文件而不是 `./fleet`:`fleet.ts` 被 `types.ts` 引,它再引本文件会成环。 */
+export function isReportableRefusalName(name) {
+    if (!isDisclosableIdentity(name))
+        return false;
+    const probe = ModelRefusalsWire.safeParse({ entries: { [name]: MODEL_ENTRY_REFUSAL_CODES[0] } });
+    return probe.success && Object.hasOwn(probe.data.entries, name);
+}
+/** 一条被丢条目原文的身份({@link DroppedEntryIdentity} 的**唯一**读法)。只看纯 JSON 对象的**自有数据
+ *  属性**;任何反射/陷阱抛错 ⇒ 当作读不出(身份是诊断面的附件,绝不许把抢救拖下水)。 */
+function readEntryIdentity(entry) {
+    try {
+        if (!isPlainJsonObject(entry))
+            return undefined;
+        const own = (k) => {
+            const d = Object.getOwnPropertyDescriptor(entry, k);
+            return d !== undefined && "value" in d ? d.value : undefined;
+        };
+        const name = own("name");
+        const id = own("id");
+        const enabled = own("enabled");
+        const identity = {
+            ...(typeof name === "string" && isDisclosableIdentity(name) ? { name } : {}),
+            ...(typeof id === "string" && isDisclosableIdentity(id) ? { id } : {}),
+            ...(typeof enabled === "boolean" ? { enabled } : {}),
+        };
+        return Object.keys(identity).length > 0 ? identity : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 一条记账行 → 它的 `entry-dropped` 告警。域面({@link buildEffective})与 wire 面(skills manifest)共用
+ *  这**一只** —— 告警形只在这里拼,新字段不会在一条腿上漏铸。 */
+function entryDroppedWarning(domain, d) {
+    return d.identity === undefined ? { domain, kind: "entry-dropped", path: d.path, error: d.error } : { domain, kind: "entry-dropped", path: d.path, error: d.error, identity: d.identity };
+}
+/** 一条被丢条目的记账行 —— `salvageEntries` 两种集合形(数组 / Record)共用的**唯一**铸点。 */
+function droppedEntry(path, error, entry) {
+    const identity = readEntryIdentity(entry);
+    return identity === undefined ? { path, error } : { path, error, identity };
+}
 /** 一次「什么都没丢」的抢救的位移表(冻结的共享空表 —— {@link rebaseWarningPaths} 对它恒等)。 */
 const NO_ENTRIES_DROPPED = Object.freeze({});
 /** 一条条目的 parse —— 坏就返回它的(脱敏)错误。恶意 getter/Proxy 在遍历中抛错时**绝不**外泄其文案
@@ -250,7 +320,7 @@ function salvageEntriesUnsafe(schema, raw) {
                     keptFrom.push(i); // 压缩后第 keptFrom.length-1 条 = 原文档第 i 条
                     return true;
                 }
-                bad.push({ path: [field, i], error });
+                bad.push(droppedEntry([field, i], error, entry));
                 return false;
             });
             // 零幸存者 ⇒ 没有要抢救的东西(见头注:绝不凭空造出一个空集合)。
@@ -270,7 +340,7 @@ function salvageEntriesUnsafe(schema, raw) {
                 if (error === undefined)
                     kept[key] = entry;
                 else
-                    bad.push({ path: [field, redactSecrets(key)], error }); // 键是用户写的,可能就是一条粘错位置的凭据
+                    bad.push(droppedEntry([field, redactSecrets(key)], error, entry)); // 键是用户写的,可能就是一条粘错位置的凭据
             }
             if (bad.length > 0 && Object.keys(kept).length > 0) {
                 dropped.push(...bad);
@@ -362,7 +432,7 @@ export function projectWarning(w) {
         case "legacy-governance-lifted":
             return { kind: w.kind, domain: w.domain, keys: w.keys };
         case "entry-dropped":
-            return { kind: w.kind, domain: w.domain, path: w.path };
+            return { kind: w.kind, domain: w.domain, path: w.path, ...(w.identity === undefined ? {} : { identity: w.identity }) };
         case "unread-config-file":
             return { kind: w.kind, file: w.file, ...(w.domain === undefined ? {} : { domain: w.domain }), why: w.why };
         default: {
@@ -764,7 +834,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
                     // 不过本层自己的表,直接交给出口(出口会补上更外层的换算);`buffered` 里的是对**本层压缩后**
                     // 文档的诊断,是从下方上来的 ⇒ 先过本层的表,再交给出口。scan 函数一字不动。
                     for (const d of salvage.dropped)
-                        emit?.({ domain, kind: "entry-dropped", path: d.path, error: d.error });
+                        emit?.(entryDroppedWarning(domain, d));
                     for (const w of buffered)
                         emit?.(rebaseWarningPaths(w, salvage.keptIndex));
                     return parsed;
@@ -875,7 +945,7 @@ export function readEffectiveWire(raw, onWarning) {
         const retry = salvage.dropped.length > 0 ? SkillsManifestSchema.safeParse(salvage.raw) : undefined;
         if (retry?.success) {
             for (const d of salvage.dropped)
-                onWarning?.({ domain: "skills", kind: "entry-dropped", path: d.path, error: d.error });
+                onWarning?.(entryDroppedWarning("skills", d));
             skills = retry.data;
         }
         else {

package/dist/conformance/types.d.ts

@@ -9,7 +9,7 @@
  * 规范化(canonical JSON、告警投影、坐标深相等)全部在 kit 内**单铸** —— 消费方零复述,因为一份被各自
  * 复述的规范化就是第二份真源,而两份真源的分歧正是本门要抓的那类病。
  */
-import type { EffectiveReadWarning } from "../config-fns.js";
+import type { EffectiveReadWarning, WarningProjection } from "../config-fns.js";
 /** 三条读腿的名字。**闭集** —— 新开一条腿要同时在语料派生表(`derive.ts` 的 `DERIVATION_TRANSFORMS`)里表态。
  *
  *  · `domains`:各域**原始文档**(center 侧存储形)→ effective。契约仓的 `buildEffective`。
@@ -192,6 +192,11 @@ export interface ConformanceNormalizer {
     why: string;
     /** 把一条坐标归一到共同空间。有损归一器在这里把段拼成串。 */
     path(p: readonly (string | number)[]): unknown;
+    /** 把一条**告警投影**归一到共同空间(可选;先于 {@link ConformanceNormalizer.path} 作用,期望与实际两侧同过)。
+     *  用途:剥掉旧版**铸不出**的 additive 字段(S-712 的 `entry-dropped.identity`)—— 旧版没有这个字段不是读法
+     *  分歧,不许被记成「旧版行为红」。剥掉的字段同样是有损的一部分,`why` 里写明。release 模式禁归一器,故
+     *  这只钩子只作用于 historical 读数。 */
+    warning?(p: WarningProjection): WarningProjection;
 }
 /**
  * 一格结局。`pass` / `expected-rejected` / `diff-ledgered` 不阻塞,`diff` / `harness-error` 红,

package/dist/conformance/warnings.js

@@ -51,13 +51,20 @@ export function normalizeProjection(p, f) {
 }
 /** 恒等坐标映射(无归一器时的那一只)。 */
 const identityPath = (path) => path;
+/** 归一器对一条投影的**整体**作用:先过投影级钩子({@link ConformanceNormalizer.warning},可缺),再做坐标映射 +
+ *  集合字段按袋。比对键与报告值共用这一只,两处不会各归一各的。 */
+function normalizedProjection(p, normalizer) {
+    if (normalizer === undefined)
+        return normalizeProjection(p, identityPath);
+    return normalizeProjection(normalizer.warning === undefined ? p : normalizer.warning(p), normalizer.path);
+}
 /** 一条投影的比对键。 */
 export function projectionKey(p, normalizer) {
-    return stableKey(normalizeProjection(p, normalizer === undefined ? identityPath : normalizer.path));
+    return stableKey(normalizedProjection(p, normalizer));
 }
 /** 一条投影的规范形(进报告的 `missing`/`extra` 用,人读)。 */
 export function projectionValue(p, normalizer) {
-    return canonicalize(normalizeProjection(p, normalizer === undefined ? identityPath : normalizer.path));
+    return canonicalize(normalizedProjection(p, normalizer));
 }
 /**
  * 两个投影**多重集**的差。重数保留:期望两条、实际一条 ⇒ `missing` 里留一条。

package/dist/fleet.d.ts

@@ -45,6 +45,142 @@ 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;
+/**
+ * "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 declare const RestartSignal: z.ZodObject<{
+    reasons: z.ZodArray<z.ZodString, "many">;
+    version: z.ZodNumber;
+    since: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    reasons: string[];
+    version: number;
+    since: number;
+}, {
+    reasons: string[];
+    version: number;
+    since: number;
+}>;
+export type RestartSignal = z.infer<typeof RestartSignal>;
+/**
+ * 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 declare function readRestartSignal(health: unknown): RestartSignal | undefined;
+/**
+ * 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 declare const MODEL_ENTRY_REFUSAL_CODES: readonly ["config.model_no_brain", "config.model_entry_invalid"];
+export declare const ModelEntryRefusalCode: z.ZodEnum<["config.model_no_brain", "config.model_entry_invalid"]>;
+export type ModelEntryRefusalCode = z.infer<typeof ModelEntryRefusalCode>;
+export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary"];
+export declare const ModelPlaneRefusalCode: z.ZodEnum<["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary"]>;
+export type ModelPlaneRefusalCode = z.infer<typeof ModelPlaneRefusalCode>;
+/**
+ * "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 declare const ModelRefusalsWire: z.ZodEffects<z.ZodObject<{
+    entries: z.ZodRecord<z.ZodString, z.ZodString>;
+    plane: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}>, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}, {
+    entries: Record<string, string>;
+    plane?: string | undefined;
+}>;
+export type ModelRefusalsWire = z.infer<typeof ModelRefusalsWire>;
+/** {@link ModelRefusalsWire} narrowed to the closed code sets — the return type of {@link readModelRefusals}. */
+export type ModelRefusalsSignal = {
+    entries: Record<string, ModelEntryRefusalCode>;
+    plane?: ModelPlaneRefusalCode;
+};
+/**
+ * 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 declare function readModelRefusals(body: unknown): ModelRefusalsSignal | undefined;
 /** 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. */
@@ -93,25 +229,83 @@ export declare const InstanceAnnouncement: z.ZodObject<{
     /** reachable base URL for the deployment form: k8s pod IP:port / docker net alias / 127.0.0.1:<engine.port> */
     address: z.ZodString;
     version: z.ZodString;
-    /** self-declared: bootDone && !draining */
+    /** self-declared readiness: model roster landed AND not draining (server ≥7.102.0; older engines: !draining only) */
     ready: z.ZodBoolean;
     draining: z.ZodDefault<z.ZodBoolean>;
     heartbeatMs: z.ZodDefault<z.ZodNumber>;
+    /** 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: z.ZodOptional<z.ZodObject<{
+        reasons: z.ZodArray<z.ZodString, "many">;
+        version: z.ZodNumber;
+        since: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        reasons: string[];
+        version: number;
+        since: number;
+    }, {
+        reasons: string[];
+        version: number;
+        since: number;
+    }>>;
+    /** 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: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        entries: z.ZodRecord<z.ZodString, z.ZodString>;
+        plane: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     draining: boolean;
-    instanceId: string;
     version: string;
+    instanceId: string;
     worker: string;
     address: string;
     ready: boolean;
     heartbeatMs: number;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+    } | undefined;
+    modelRefusals?: {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    } | undefined;
 }, {
-    instanceId: string;
     version: string;
+    instanceId: string;
     worker: string;
     address: string;
     ready: boolean;
     draining?: boolean | undefined;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+    } | undefined;
+    modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
 }>;
 export type InstanceAnnouncement = z.infer<typeof InstanceAnnouncement>;
@@ -139,34 +333,92 @@ export declare const InstanceRegistration: z.ZodObject<{
     /** reachable base URL for the deployment form: k8s pod IP:port / docker net alias / 127.0.0.1:<engine.port> */
     address: z.ZodString;
     version: z.ZodString;
-    /** self-declared: bootDone && !draining */
+    /** self-declared readiness: model roster landed AND not draining (server ≥7.102.0; older engines: !draining only) */
     ready: z.ZodBoolean;
     draining: z.ZodDefault<z.ZodBoolean>;
     heartbeatMs: z.ZodDefault<z.ZodNumber>;
+    /** 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: z.ZodOptional<z.ZodObject<{
+        reasons: z.ZodArray<z.ZodString, "many">;
+        version: z.ZodNumber;
+        since: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        reasons: string[];
+        version: number;
+        since: number;
+    }, {
+        reasons: string[];
+        version: number;
+        since: number;
+    }>>;
+    /** 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: z.ZodCatch<z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        entries: z.ZodRecord<z.ZodString, z.ZodString>;
+        plane: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }, {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    }>>>;
 } & {
     registeredMs: z.ZodNumber;
     lastSeenMs: z.ZodNumber;
     observedReady: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     draining: boolean;
-    instanceId: string;
     version: string;
+    instanceId: string;
     worker: string;
     address: string;
     ready: boolean;
     heartbeatMs: number;
     registeredMs: number;
     lastSeenMs: number;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+    } | undefined;
+    modelRefusals?: {
+        entries: Record<string, string>;
+        plane?: string | undefined;
+    } | undefined;
     observedReady?: boolean | undefined;
 }, {
-    instanceId: string;
     version: string;
+    instanceId: string;
     worker: string;
     address: string;
     ready: boolean;
     registeredMs: number;
     lastSeenMs: number;
     draining?: boolean | undefined;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+    } | undefined;
+    modelRefusals?: unknown;
     heartbeatMs?: number | undefined;
     observedReady?: boolean | undefined;
 }>;
@@ -410,7 +662,6 @@ export declare const UsageReport: z.ZodObject<{
         quotaWeightAtUse?: number | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    instanceId: string;
     entries: {
         principal: string;
         model: string;
@@ -421,11 +672,11 @@ export declare const UsageReport: z.ZodObject<{
         runs?: number | undefined;
         quotaWeightAtUse?: number | undefined;
     }[];
+    instanceId: string;
     worker: string;
     windowStartMs: number;
     windowEndMs: number;
 }, {
-    instanceId: string;
     entries: {
         principal: string;
         model: string;
@@ -436,6 +687,7 @@ export declare const UsageReport: z.ZodObject<{
         runs?: number | undefined;
         quotaWeightAtUse?: number | undefined;
     }[];
+    instanceId: string;
     worker: string;
     windowStartMs: number;
     windowEndMs: number;