@sema-agent/settings-schema 6.1.0 → 6.3.0

package/dist/fleet.js

@@ -62,21 +62,130 @@ export const RestartSignal = z.object({
     since: z.number().int().nonnegative(),
 });
 /**
- * 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.
+ * 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).
  */
-export function readRestartSignal(health) {
+function readHealthSignal(health, key, schema) {
     try {
         if (health === null || typeof health !== "object" || Array.isArray(health))
             return undefined;
-        const parsed = RestartSignal.safeParse(health.restart);
+        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)` (an identifier in the closed allowlist
+ *    `DISCLOSABLE_IDENTITY_RE` — `A-Z a-z 0-9 . _ : / @ + -`, 1–256 chars — AND not secret-shaped, a URL userinfo included; the
+ *    rule the dropped-entry identity on read warnings already uses, 6.3.0). 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. */
@@ -93,6 +202,7 @@ export const InstanceHealth = z
     // 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). */
@@ -126,6 +236,17 @@ export const InstanceAnnouncement = z.object({
      *  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/secret-scan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 秘密扫描读的**归一化**,外加「URL 的 userinfo 就是凭据」那一只判定({@link carriesUserinfo})—— 包内私有模块(6.3.0):不进主 barrel、
+ * 不进 `package.json` 的 `exports`,消费方拿不到。
+ * 校验侧探测器 `containsSecretToken`(`./types`)只读 {@link percentLayers};展示侧脱敏器 `redactSecrets`(`./config-fns`)
+ * 读 {@link secretScanForms}。展示侧的读法(边界读法、`+` 读法、「没走完」那一位)刻意不做公开契约:它们以后要随新发现的
+ * 编码形调整,调整不该是契约变更(opus 独立腿 L7)。
+ *
+ * **单遍、零异常**(opus 独立腿 M1,对 6.2.0 的读路径 CPU 回归):6.2.0 起的宽容解码对每个 `%HH` 各 `try decodeURIComponent`,
+ * 非 ASCII 的转义每个都抛一次异常(≈ 20–30 µs / 字节,同步阻塞);6.3.0 首稿又让探测器顺带算它不用的展示形。这里两处解码都
+ * 不靠异常:单个转义的判据写成字符集(只有 ASCII 的 `%00`–`%7F` 单独解得开),转义串的判据写成 UTF-8 良构判定 ——
+ * 结果与原来的 try/catch 逐字相同(`test/disclosable-identity-6.3.0.test.ts` 的两只冻结 oracle 钉着)。
+ *
+ * 本模块零 import(`./types` 引它,它不回引,不成环)。
+ */
+/** How many percent-decoded layers a secret scan reads beyond the raw string (a multi-encoded `%2573%256B…` →
+ *  `%73%6B…` → `sk-…`). Bounded → deterministic. */
+export declare const SECRET_SCAN_DECODE_LAYERS = 3;
+/** The raw string first, then up to {@link SECRET_SCAN_DECODE_LAYERS} tolerant percent-decoded layers, stopping at the first
+ *  layer that decodes nothing — the forms the validation detector `containsSecretToken` reads, and nothing else. */
+export declare function percentLayers(text: string): readonly string[];
+/** What {@link secretScanForms} returns — plain data, no behavior. */
+export interface SecretScanForms {
+    /** {@link percentLayers} of the text. */
+    readonly percentLayers: readonly string[];
+    /** The forms the display-side redactor judges a whole string on: `percentLayers`, each layer's {@link boundaryReading}, and
+     *  each of those read the application/x-www-form-urlencoded way (`+` as a space); duplicates dropped, first seen first. */
+    readonly forms: readonly string[];
+    /** Normalization did not finish: the layer budget ran out while one more layer would still decode something. A caller that
+     *  shows text withholds it whole — what could not be normalized does not go out. (A lone undecodable escape is a fixed
+     *  point, not an unfinished one: `%E4%B8%AD` stays as it is and is not flagged.) */
+    readonly unresolved: boolean;
+}
+/** The display-side normalization — only `redactSecrets` (config-fns) calls it. */
+export declare function secretScanForms(text: string): SecretScanForms;
+/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0,opus 腿 L1):username / password 任一在场即是。校验侧 `NON_SECRET_URL` 与 https
+ *  插件源据此拒写(`./types`),身份面据此否决(`./config-fns` 的 `isDisclosableIdentity` —— `https://admin:hunter2@db…` /
+ *  `postgres://svc:pw@h` 的字符全在身份白名单里)。串解析不成 URL ⇒ false:这只判定只说「一个 URL 带没带 userinfo」,
+ *  不是 URL 的串不在它的射程里(无 scheme 的 `svc:pw@host` 解析成不透明路径,同样答 false —— 如实登记的边界)。 */
+export declare function carriesUserinfo(u: URL | string): boolean;

package/dist/secret-scan.js

@@ -0,0 +1,110 @@
+/**
+ * 秘密扫描读的**归一化**,外加「URL 的 userinfo 就是凭据」那一只判定({@link carriesUserinfo})—— 包内私有模块(6.3.0):不进主 barrel、
+ * 不进 `package.json` 的 `exports`,消费方拿不到。
+ * 校验侧探测器 `containsSecretToken`(`./types`)只读 {@link percentLayers};展示侧脱敏器 `redactSecrets`(`./config-fns`)
+ * 读 {@link secretScanForms}。展示侧的读法(边界读法、`+` 读法、「没走完」那一位)刻意不做公开契约:它们以后要随新发现的
+ * 编码形调整,调整不该是契约变更(opus 独立腿 L7)。
+ *
+ * **单遍、零异常**(opus 独立腿 M1,对 6.2.0 的读路径 CPU 回归):6.2.0 起的宽容解码对每个 `%HH` 各 `try decodeURIComponent`,
+ * 非 ASCII 的转义每个都抛一次异常(≈ 20–30 µs / 字节,同步阻塞);6.3.0 首稿又让探测器顺带算它不用的展示形。这里两处解码都
+ * 不靠异常:单个转义的判据写成字符集(只有 ASCII 的 `%00`–`%7F` 单独解得开),转义串的判据写成 UTF-8 良构判定 ——
+ * 结果与原来的 try/catch 逐字相同(`test/disclosable-identity-6.3.0.test.ts` 的两只冻结 oracle 钉着)。
+ *
+ * 本模块零 import(`./types` 引它,它不回引,不成环)。
+ */
+/** How many percent-decoded layers a secret scan reads beyond the raw string (a multi-encoded `%2573%256B…` →
+ *  `%73%6B…` → `sk-…`). Bounded → deterministic. */
+export const SECRET_SCAN_DECODE_LAYERS = 3;
+/** One TOLERANT percent-decode layer: an escape decodes on its own iff `decodeURIComponent` would accept it alone — exactly
+ *  the ASCII ones, `%00`–`%7F` — and every other escape (`%C2`, a lone `%E4`, `%ZZ` is not an escape at all) stays as it
+ *  is, so one bad escape elsewhere can't abort the whole decode (R13's all-or-nothing decodeURIComponent did). Same result
+ *  as the per-escape try/catch loop it replaces, with no exception per non-ASCII escape. */
+function percentDecodeLayer(s) {
+    return s.indexOf("%") === -1 ? s : s.replace(/%([0-7][0-9A-Fa-f])/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** The raw string first, then up to {@link SECRET_SCAN_DECODE_LAYERS} tolerant percent-decoded layers, stopping at the first
+ *  layer that decodes nothing — the forms the validation detector `containsSecretToken` reads, and nothing else. */
+export function percentLayers(text) {
+    const layers = [text];
+    let cur = text;
+    for (let i = 0; i < SECRET_SCAN_DECODE_LAYERS; i++) {
+        const next = percentDecodeLayer(cur);
+        if (next === cur)
+            break;
+        layers.push(next);
+        cur = next;
+    }
+    return layers;
+}
+/** Is this byte sequence well-formed UTF-8 (Unicode Table 3-7: no overlongs, no surrogates, nothing above U+10FFFF)? That is
+ *  exactly when `decodeURIComponent` accepts a run of escapes spelling these bytes — decided without throwing. */
+function isWellFormedUtf8(bytes) {
+    for (let i = 0; i < bytes.length;) {
+        const lead = bytes[i];
+        if (lead < 0x80) {
+            i += 1;
+            continue;
+        }
+        // [续字节个数, 第一个续字节的下界, 上界];其余续字节恒为 80..BF。
+        const shape = lead >= 0xc2 && lead <= 0xdf ? [1, 0x80, 0xbf]
+            : lead === 0xe0 ? [2, 0xa0, 0xbf]
+                : (lead >= 0xe1 && lead <= 0xec) || lead === 0xee || lead === 0xef ? [2, 0x80, 0xbf]
+                    : lead === 0xed ? [2, 0x80, 0x9f]
+                        : lead === 0xf0 ? [3, 0x90, 0xbf]
+                            : lead >= 0xf1 && lead <= 0xf3 ? [3, 0x80, 0xbf]
+                                : lead === 0xf4 ? [3, 0x80, 0x8f]
+                                    : undefined;
+        if (shape === undefined)
+            return false;
+        const [need, lo, hi] = shape;
+        for (let k = 1; k <= need; k++) {
+            const c = bytes[i + k];
+            if (c === undefined || c < (k === 1 ? lo : 0x80) || c > (k === 1 ? hi : 0xbf))
+                return false;
+        }
+        i += need + 1;
+    }
+    return true;
+}
+/** The display-side BOUNDARY reading of one layer (codex r2): every run of %HH escapes is decoded as UTF-8 in one go when it
+ *  is well-formed (an encoded NBSP / zero-width space becomes the delimiter it really is); otherwise its ASCII escapes decode
+ *  on their own and every other escape reads as a space — an escape never glues its hex digits onto the token after it
+ *  (`%C2%A0sk-live-…` read escape by escape is `%C2%A0sk-…`, whose tokens are `C2` / `A0sk-…`: the `sk-` boundary is gone,
+ *  though any standard decoder restores it). Display-only: the validation detector never reads it. */
+function boundaryReading(s) {
+    if (s.indexOf("%") === -1)
+        return s;
+    return s.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+        const bytes = [];
+        for (let i = 0; i < run.length; i += 3)
+            bytes.push(parseInt(run.slice(i + 1, i + 3), 16));
+        return isWellFormedUtf8(bytes) ? decodeURIComponent(run) : bytes.map((b) => (b < 0x80 ? String.fromCharCode(b) : " ")).join("");
+    });
+}
+/** The display-side normalization — only `redactSecrets` (config-fns) calls it. */
+export function secretScanForms(text) {
+    const layers = percentLayers(text);
+    const last = layers[layers.length - 1];
+    const unresolved = layers.length === SECRET_SCAN_DECODE_LAYERS + 1 && percentDecodeLayer(last) !== last;
+    const readings = [...layers, ...layers.map((layer) => boundaryReading(layer))];
+    const forms = [...new Set([...readings, ...readings.map((reading) => (reading.indexOf("+") === -1 ? reading : reading.replace(/\+/g, " ")))])];
+    return { percentLayers: layers, forms, unresolved };
+}
+/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0,opus 腿 L1):username / password 任一在场即是。校验侧 `NON_SECRET_URL` 与 https
+ *  插件源据此拒写(`./types`),身份面据此否决(`./config-fns` 的 `isDisclosableIdentity` —— `https://admin:hunter2@db…` /
+ *  `postgres://svc:pw@h` 的字符全在身份白名单里)。串解析不成 URL ⇒ false:这只判定只说「一个 URL 带没带 userinfo」,
+ *  不是 URL 的串不在它的射程里(无 scheme 的 `svc:pw@host` 解析成不透明路径,同样答 false —— 如实登记的边界)。 */
+export function carriesUserinfo(u) {
+    let url;
+    if (typeof u === "string") {
+        try {
+            url = new URL(u);
+        }
+        catch {
+            return false; // 不是 URL:不在这只判定的射程里(见头注),不是回退
+        }
+    }
+    else
+        url = u;
+    return url.username !== "" || url.password !== "";
+}