@sema-agent/settings-schema 6.0.0 → 6.1.0

package/dist/fleet.d.ts

@@ -45,6 +45,42 @@ 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 `/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 +129,52 @@ 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;
+    }>>;
 }, "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;
 }, {
-    instanceId: string;
     version: string;
+    instanceId: string;
     worker: string;
     address: string;
     ready: boolean;
     draining?: boolean | undefined;
+    restart?: {
+        reasons: string[];
+        version: number;
+        since: number;
+    } | undefined;
     heartbeatMs?: number | undefined;
 }>;
 export type InstanceAnnouncement = z.infer<typeof InstanceAnnouncement>;
@@ -139,34 +202,61 @@ 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;
+    }>>;
 } & {
     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;
     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;
     heartbeatMs?: number | undefined;
     observedReady?: boolean | undefined;
 }>;
@@ -410,7 +500,6 @@ export declare const UsageReport: z.ZodObject<{
         quotaWeightAtUse?: number | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    instanceId: string;
     entries: {
         principal: string;
         model: string;
@@ -421,11 +510,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 +525,7 @@ export declare const UsageReport: z.ZodObject<{
         runs?: number | undefined;
         quotaWeightAtUse?: number | undefined;
     }[];
+    instanceId: string;
     worker: string;
     windowStartMs: number;
     windowEndMs: number;

package/dist/fleet.js

@@ -40,6 +40,43 @@ 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 /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) {
+    try {
+        if (health === null || typeof health !== "object" || Array.isArray(health))
+            return undefined;
+        const parsed = RestartSignal.safeParse(health.restart);
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return 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. */
@@ -52,6 +89,10 @@ 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.
 })
     .passthrough();
 /** Readiness = the routability predicate (k8s readiness probe, gateway health filter, shell seam switch). */
@@ -76,10 +117,15 @@ 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(),
 });
 /** 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

package/dist/types.d.ts

@@ -16,6 +16,12 @@
  * `ENV_NAME` schema (regex) on every `*Env` field — a pasted secret value is rejected, not just discouraged.
  */
 import { z } from "zod";
+/** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
+ *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
+ *  `redactSecrets` (config-fns) tests it ANYWHERE in a string. It carries spaces, so the token-splitting detector
+ *  {@link containsSecretToken} only sees it at the very start of a string; a PEM behind a newline or a `key: ` prefix
+ *  slipped past (S-712 codex review [high]). Public keys / certificates never match (see above). */
+export declare const PRIVATE_KEY_PEM_HEADER: RegExp;
 export declare const SECRET_LITERAL_RE: RegExp;
 export declare const ENV_NAME: z.ZodEffects<z.ZodString, string, string>;
 /** A NUL byte in a string the consumer feeds to spawn()/fs is a FAIL-OPEN config: it validates+persists here

package/dist/types.js

@@ -26,7 +26,13 @@ import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (sched
 // — a PUBLIC KEY / CERTIFICATE is NOT a secret and must NOT be flagged (PRINCIPAL_JWT_PUBKEYS lives in env).
 // 0.1.32: this is the root fix for the public-key false-positive — replaces the 0.1.31 name-based exemption,
 // which review flagged as a bypass (a private key misnamed `*_PUBKEY` skipped scanning entirely).
-export const SECRET_LITERAL_RE = /^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\s|basic\s|eyJ[A-Za-z0-9_-]{10,}\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN[A-Z0-9 ]*PRIVATE KEY)/i;
+/** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
+ *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
+ *  `redactSecrets` (config-fns) tests it ANYWHERE in a string. It carries spaces, so the token-splitting detector
+ *  {@link containsSecretToken} only sees it at the very start of a string; a PEM behind a newline or a `key: ` prefix
+ *  slipped past (S-712 codex review [high]). Public keys / certificates never match (see above). */
+export const PRIVATE_KEY_PEM_HEADER = /-----BEGIN[A-Z0-9 ]*PRIVATE KEY/i;
+export const SECRET_LITERAL_RE = new RegExp(`^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\\s|basic\\s|eyJ[A-Za-z0-9_-]{10,}\\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|${PRIVATE_KEY_PEM_HEADER.source})`, "i");
 // 所有 *Env / *tokenEnv 字段的值是宿主机 env 变量的 NAME（不是值）。合法 env 变量名 + 拒绝 secret 形状的值（AKIA…
 // 这类是合法 env-NAME 字符集却是密钥）—— "只存 env-NAME、绝不存 secret 值" 由 SCHEMA 保证。Round-5。
 export const ENV_NAME = z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",