@sema-agent/settings-schema 10.1.0 → 11.0.0

package/README.md

@@ -22,12 +22,12 @@
 > deprecate 标指向新名。
 
 Engine-agnostic, zero-dependency contract layer for the sema stack — **one source of truth** for the
-config domain across the center (the config-center product — today `sema-web-admin` — the fleet admin), the
+config domain across web-admin (the fleet admin product, today `sema-web-admin`), the
 server (the workers), and the client (desktop/CLI) seams. No two copies of the schema.
 
-> 命名说明:config-center 这个**产品**曾叫 `sema-registry`,又改成 `sema-web`,现在是 `sema-web-admin`
+> 命名说明:web-admin 这个**产品**曾叫 `sema-registry`,又改成 `sema-web`,现在是 `sema-web-admin`
 > (clay 令 2026-08-26 仓改名;后续仍可能再改)。本**包**名与产品名解耦,**不随产品改名而动**(1.0.0 这次
-> 改名是本包自身的正名,与产品名无关)—— 下文凡提「center / config-center 产品」即指该产品的当期实现。
+> 改名是本包自身的正名,与产品名无关)—— 下文凡提「web-admin」即指该产品的当期实现。
 
 - **Source of truth**: `github.com/sema-agent/sema-settings-schema`, branch `main` (private org repo; renamed from `sema-registry-core` on 2026-08-26, old URLs redirect).
   仓名本步不动(只改包名)。
@@ -35,18 +35,49 @@ server (the workers), and the client (desktop/CLI) seams. No two copies of the s
   (≤`0.19.0` 发在旧名 `@sema-agent/registry-core` 下,冻结)。
 
 The package is **pure**: zero `next`/`react`/server imports, zero DB drivers. Its only runtime dependency is
-`zod` (a `dependency` pinned `^3.24.0`, also declared as a `peerDependency` with the same range). `npm ls --prod`
+`zod` (a `dependency` pinned `^4.4.0`, also declared as a `peerDependency` with the same range). `npm ls --prod`
 therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 
-> **zod instances today: two, not one** (corrected in 6.2.0 — this section used to promise a single shared instance).
-> The range was chosen so every host would dedup to one zod, but the hosts have since moved apart: `sema-server` and the
-> CLI depend on zod 4 (`^4.x`), the config-center product (`sema-web-admin`) is still on zod 3. In a zod-4 host the
-> package manager installs this package's own zod 3 NESTED under it — the server tree today has zod 4 at the top level
-> and zod 3 at `node_modules/@sema-agent/settings-schema/node_modules/zod`. There, this package's schemas and the host's
-> are two zod instances: cross the seam with plain data (parse with the schemas / functions this package exports), and
-> never mix schema objects of the two instances (`instanceof ZodError`, composing a host schema with one of ours). Only
-> a zod-3 host (today the config-center product) still dedups to one instance. Moving this package to zod 4 is a major
-> of its own (S-777); 6.2.0 does not touch the dependency or peer range.
+> **One zod instance in a zod-4 host** (11.0.0). The range is `^4.4.0` for both the dependency and the peer, so a host on
+> zod 4 (`sema-server`, the CLI, the client core, the SDK) dedups this package's zod with its own: one instance, and schema objects
+> may cross the seam. A host still on zod 3 (until it upgrades — today the web-admin product, `sema-web-admin`) does not
+> satisfy the peer range, and its package manager installs this package's zod 4 NESTED under it: two instances there, so
+> cross the seam with plain data only (parse with the schemas / functions this package exports; never `instanceof ZodError`
+> across it, never compose a host schema with one of ours). Before 11.0.0 the picture was the mirror image (this package on
+> zod 3, nested inside every zod-4 host). The move to zod 4 did not change what any schema accepts or produces —
+> the conformance corpus reads byte-identically on both — only the wording of validation errors (see CHANGELOG 11.0.0).
+
+## 升级指引:10.x → 11.0.0 · 持久面:一次性迁移(`./one-time-migrations`)
+
+11.0.0 把读路径上为旧数据留的兼容臂全部收掉:旧形只有一种去处 —— **一次性迁移**把它改写成新形(你写回),读写两面遇旧形**响亮拒**,
+拒句点名迁移 id。没迁的存量会被拒,所以**先迁再读**。
+
+- **谁要跑**:持有存量配置的一方 —— 管理面起服时对每个 scope 的草稿、每个 principal 层(个人 models / mcp / skills / plugins)、每份冻结的
+  发布快照与回滚史各跑一次;引擎对自己的 last-known-good 文件跑 `migrateEffectiveSnapshot`;本地 `config.d` 目录跑命令行。
+- **怎么调**(纯函数,不读环境、不读墙钟、不改入参、不抬任何版本号 —— 版本号归你):
+
+  ```ts
+  import { migrateStoredDocuments, migrateEffectiveSnapshot, ONE_TIME_MIGRATIONS } from "@sema-agent/settings-schema/one-time-migrations";
+
+  // 一个 scope 的全部存储文档(域名 → 文档);缺席的域 = 从未设过。
+  const { docs, receipts } = migrateStoredDocuments(scopeDocs, { coverage: "scope" });
+  // principal 层 / 回滚史的单域行 / 任意子集:缺席的域 = 没给、不动。
+  migrateStoredDocuments({ models: personalModels, mcp: personalMcp }, { coverage: "partial" });
+  // 冻结的 effective(发布快照、引擎的 LKG):version / updatedAt 与其余信封键原样。
+  const { effective } = migrateEffectiveSnapshot(frozen);
+  ```
+
+  `docs` 里没改的文档是**同一引用**、被移除的(退役的 `runtime` 域)不在、迁出的新文档(`governance` / `limits`)在 —— 据此写回 / 删除。
+  `receipts` 逐条说「对哪个坐标做了什么」(`moved` / `rewritten` / `dropped-shadowed` / `dropped-inert` / `refused`;不带值)。
+  `refused` 的坐标原样留着,读侧照旧拒:要人改。再跑一次 = 零改动。
+- **目录形**:`npx @sema-agent/settings-schema migrate <config.d> [--check]`(同一只函数;目录当一个 scope;有 refused 一字不写、退出 1;
+  `--check` 有改动退出 3)。
+- **迁什么**(七条,`ONE_TIME_MIGRATIONS` 每行写着改写规则、删法、删后由谁接住):退役 `runtime` 域(治理三闸 → `governance`、五个限额键 → `limits`)·
+  hosts 超界 · 调度店 durable 键(读时改写,下一个写者落盘)· workers 6.x 行 · 模型钥匙双设 · `atModelAllowlist` → `atMention` · URL fragment。
+- **什么时候删**:每条的窗 = 11.0.0 发布日 + 30 天,窗关之后的那个 major 整族删(删法与删后的响亮臂见登记表那一行);本包的到期门到点即红。
+  删了之后还带旧形的存量,由墓碑照旧拒 —— 墓碑是拒,不会再被读成任何值。
+- **回滚史里单独一行 `runtime`**:迁不了(没有同一 scope 的 governance / limits 可判),回滚到它会被墓碑拒 —— 不可恢复。
+- **不要混跑**:迁移期间别让 10.x 与 11.x 的管理面副本同时在线(10.x 副本会照旧写出旧形,11.x 副本读它会拒)。
 
 ## 升级指引:9.0.0 → 10.0.0(BREAKING:写入校验认串中任意位置的私钥 PEM 头;读侧同套 schema ⇒ 存量私钥串的条目被丢 / 域 throw;导出面零变化)
 
@@ -58,7 +89,7 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 ## 升级指引:8.3.1 → 9.0.0(BREAKING:两件,硬 breaking —— 删改直接做,零别名)
 
 **① 能力读数改三态读器**:`readCenterCapabilities(body)` 删,换 `readCapabilityReading(reply): CapabilityReading`(类型 `CapabilityReading` 同入)。输入改成心跳 **2xx 的整只答复体**(键查找进读器),
-答三态:`{ kind: "declared"; capabilities }`(`capabilities` 键在场且过 schema)· `{ kind: "undeclared" }`(体是对象、键缺席 = 老中心)·
+答三态:`{ kind: "declared"; capabilities }`(`capabilities` 键在场且过 schema)· `{ kind: "undeclared" }`(体是对象、键缺席 = 老 web-admin)·
 `{ kind: "unreadable"; why: "not-an-object" | "invalid-capabilities" }`(体不是对象 / 键在场但 schema 拒)。**只有 `declared` / `undeclared` 是读数;`unreadable` 不是读数 —— 引擎保留上一次状态与钟。**
 
 - **谁需要**:引擎侧的租约客户端(server)—— 围栏这条轴上「形坏」不许等于「缺席」:以前 `capabilities` 键在场但形坏读成 `undefined` = 「没宣告」,引擎据此撤围栏。
@@ -114,11 +145,11 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 - `EngineSignal`(+ `EngineDraining`)与 `readEngineSignal(health)` —— 引擎自铸信号的**闭形**(`ready` 必填,`draining?` / `restart?` / `generation?` / `instanceId?` /
   `leaseUntil?` / `configTargetVersion?` / `configAppliedVersion?` 可选);与既有读器走同一只受保护读口。⚠️ 8.2.0 订正:今天的心跳与 `/health` 都不整只
   承载它(心跳恒带布尔 `draining`、`/health` 就绪时不带 `ready`、世代账两键是数),`readEngineSignal` 对今天的心跳体恒 `undefined` —— 见 8.2.0 升级指引(9.0.0 起这两键在 `EngineSignal` 里就是数,不再是读不出的原因)。
-  `undefined` = 没有这只信号,**不是就绪**;布尔 `draining` 的旧方言体读不出它(两个就绪谓词的输入仍是布尔方言,下一个 major 收)。
+  `undefined` = 没有这只信号,**不是就绪**;布尔 `draining` 的旧方言体读不出它(两个就绪谓词当时的输入仍是布尔方言;11.0.0 起它们只收 `EngineSignal`,信号整只在 `engineSignal` 键下)。
 - 代际 —— `generation` 是非负整数的**规范十进制串**(`"7"`,不是 `"07"`、不是数字型),判别器 `isCanonicalGeneration`、数值比较 `compareGeneration`;三处 wire 形共用这一条判据。
 - 服务租约 API 型 —— `ServingLeaseRequest`、`ServingLeaseResponse`(`granted { ttlMs }` / `denied { reason: superseded | retired }` / `unknown` 三词闭集,
   **`unknown` 不是 `denied` 的一种**,`denied` 只凭正面证据;读器按 `verdict` 键判,`denied` 的原因词读不出时仍是 `denied`,原因读成 `unknown_reason`)、`SERVING_LEASE_TTL_DEFAULT_MS` / `SERVING_LEASE_TTL_FLOOR_MS` / `SERVING_LEASE_DRIFT_MARGIN_MS`、读器 `readServingLeaseRequest` / `readServingLeaseResponse`;
-  中心能力位 `CenterCapabilities { servingLease?: true }` + `readCenterCapabilities`(9.0.0 起删,由 `readCapabilityReading` 取代,见 9.0.0 升级指引)—— 租约客户端只在位在场时启用,缺席 = 中心不支持租约(不续租、不围栏)。
+  web-admin 能力位 `CenterCapabilities { servingLease?: true }` + `readCenterCapabilities`(9.0.0 起删,由 `readCapabilityReading` 取代,见 9.0.0 升级指引)—— 租约客户端只在位在场时启用,缺席 = web-admin 不支持租约(不续租、不围栏)。
 - 排空口型 —— `DrainRequest`、`DrainReceipt`(`state: draining | already_draining`)、读器 `readDrainRequest` / `readDrainReceipt`。
 - `FLEET_GENERATION_ENV` —— 配置渲染器与引擎共用的 generation env 名常量(实例身份 `instanceId` 由引擎每进程自铸,没有 env 名);它同时进了 `RESERVED_WORKER_ENV`,`worker.env` / `secretEnv` 设不了它。
 - `clampServingLeaseTtlMs(n)` —— 配置的租约 TTL 的唯一夹取点(读不出 ⇒ 缺省 600 000;低于地板 ⇒ 60 000;无上限)。
@@ -140,8 +171,9 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 
 ## What's in it
 
-- **The zod contract** (`types.ts`): `DOMAIN_SCHEMAS` (17 domains — 0.10.0 adds `projects`, the project
-  identity ledger; 0.10.18 adds `prompts`; 0.19.0 adds `limits`, the cost/rate-limit publication slot),
+- **The zod contract** (`types.ts`): `DOMAIN_SCHEMAS` (16 domains — 0.10.0 adds `projects`, the project
+  identity ledger; 0.10.18 adds `prompts`; 0.19.0 adds `limits`, the cost/rate-limit publication slot; 11.0.0 retires
+  `runtime` — its tombstone is `RETIRED_DOMAINS`, see "One-time migrations" below),
   `EffectiveConfig`, `EffectiveWire`,
   `ENV_NAME`/`K8S_QUANTITY` boundaries, every domain's entry/config type.
 - **Pure config fns** (`config-fns.ts`): `buildEffective` (deterministic — `updatedAt` is a required param),
@@ -150,24 +182,28 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   shapes (`User`, `PublishedSnapshot`, …).
 - **Roster resolution** (`resolve-roster.ts`): `resolveEffectiveForWorker` → the per-worker wire payload.
 - **Ref integrity** (`cross-domain.ts`): `refIntegrityIssues` + `createSiblingResolver` (the pure half — fleet
-  auto-placement stays in the config-center 产品). The ref-checked domains are a RUNTIME closed set —
+  auto-placement stays in the web-admin 产品). The ref-checked domains are a RUNTIME closed set —
   `REF_CHECKED_DOMAINS` + `isRefCheckedDomain` (`RefCheckedDomain` is derived from the value) — so a consumer
   asks the contract instead of hand-copying the list; every `RefIssue.path` starts with the domain key.
 - **Hashing** (`hash.ts`): `stableHash` (FNV-1a 64) for ETags / version detection.
 - **Skills manifest** (`skills-manifest.ts`): content-addressing for the lazy-pull skill bodies.
 - **Secret inventory** (`secret-refs.ts`): `collectEnvRefs` — every referenced env-NAME.
-- **The narrow reader** (`reader.ts`): `ConfigReader` (3 methods) — the config-center 产品's fat `ConfigStore`
+- **The narrow reader** (`reader.ts`): `ConfigReader` (3 methods) — the web-admin 产品's fat `ConfigStore`
   `extends` it; a local file source / test fixture implements it without stubbing ~32 methods.
 - **`remoteExec` contract** (`remote-exec.ts`): the per-machine `config.d/remote-exec.json` execution-substrate
   schema (`host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`), discriminated on `provider`; every secret an
   env-NAME ref. Every `provider` word is an execution-lane word (`EXECUTION_LANE_WORDS`, pinned at runtime and at
   compile time). **7.0.0** deleted the `remote-docker` variant: no engine read point ever ran it; a remote docker
-  daemon is the `local-docker` lane pointed at it (`DOCKER_HOST`).
+  daemon is the `local-docker` lane pointed at it (`DOCKER_HOST`). **11.0.0**: retired lane VALUES have a tombstone,
+  `RETIRED_LANE_WORDS` (`[old, to, how]`, permanent, one hop); a worker spec's `runtime.execution.lane` or this file's
+  `provider` naming one is refused with the way out (`retiredLaneWordRefusal(word)` is the one sentence; the issue code
+  stays `invalid_value` / `invalid_union`).
 - **WorkerSpec execution lane + store (7.0.0, M-R2)** (`execution-lanes.ts`, also subpath `./execution-lanes`, + `types.ts`): the lane / store
   vocabulary has ONE source — the exported data `EXECUTION_LANE_WORDS`, `EXECUTION_LANES` (per lane:
-  `tenantSeparation` + the env names it reads, in four columns `requiredEnv` / `requiredSecretEnv` / `optionalEnv` /
+  `tenantSeparation` — and, on a `supported` lane only, `tenantSeparationBasis`: `isolation` | `principal-binding`, a
+  discriminated union (11.0.0), so a rule reads WHY a lane separates tenants instead of naming lanes — + the env names it reads, in four columns `requiredEnv` / `requiredSecretEnv` / `optionalEnv` /
   `optionalSecretEnv`, copied from the engine with per-row coordinates), `STORE_BACKENDS`, `SESSION_BACKENDS`,
-  `MEMORY_ENGINE_BACKENDS`. The center's write gate (this package's `WorkerSpec.safeParse`), the center's env
+  `MEMORY_ENGINE_BACKENDS`. Web-admin's write gate (this package's `WorkerSpec.safeParse`), web-admin's env
   renderer and the engine's boot checks all read that one table, so they cannot drift. A worker declares
   `runtime.execution = { lane, coords, secretRefs }` (non-secret coordinates as literals, secrets as host env-NAMEs,
   keys ⊆ that lane's columns, required ones present and non-empty) and `runtime.store = { backend, session, memory,
@@ -244,40 +280,68 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   and the pure client helpers `normalizeUserCode` / `nextPollInterval`. Shipped M1 shapes frozen.
   OpenAPI mirror: `docs/openapi-auth.yaml` (auth face only).
 - **Auth bridge** (`api/auth-bridge.ts`, subpath `./api/auth-bridge`): the 鉴权桥 contract —
-  how a worker verifies a registry-minted user JWT: RS256-only, JWKS from `/api/auth/sso/jwks` with
-  kid-miss forced refresh + ≥60s throttle, exp/nbf clock skew (60s), 24h offline grace then fail-closed;
+  how a worker verifies a web-admin-minted user JWT: RS256-only, JWKS from `/api/auth/sso/jwks` with
+  kid-miss forced refresh + ≥60s throttle, exp/nbf/iat clock skew (60s), 24h offline grace then fail-closed;
   `VerifierConfig` / `VerifiedIdentity` / `AuthBridgeErrorCode` + pure decision fns
   (`shouldForceJwksRefresh`, `jwksWithinOfflineGrace`, `classifyTimeClaims`, `toVerifiedIdentity`).
   The normative rules R1–R10 in its header are the service verifier's implementation spec.
-  `VerifiedIdentity` carries an optional `scope` (the token's active tenant scope — see `api/scopes`).
-- **Center credential file** (`center-credential.ts`, main barrel; S-698): the file behind
-  `SEMA_REGISTRY_TOKEN_FILE` is one of two KINDS — a bare line (one static token — the same kind of file as today:
+  `VerifiedIdentity` carries an optional `scope` (the token's active tenant scope — see `api/scopes`) and an optional `iat`
+  (issued-at, integer seconds, verbatim — absent claim ⇒ no key; not a non-negative integer ⇒ the token is refused).
+- **web-admin credential file + connection env names** (`web-admin-credential.ts`, main barrel; S-698): the file behind
+  `SEMA_WEB_ADMIN_TOKEN_FILE` is one of two KINDS — a bare line (one static token — the same kind of file as today:
   its first line, printable ASCII with no control / non-ASCII characters; user JWT vs worker pull token stays the reader's `looksLikeJwt` call) or a
-  `CenterCredentialEnvelope` (strict JSON: `kind: "user-session"` = `CENTER_CREDENTIAL_ENVELOPE_KIND`, a JWT
+  `WebAdminCredentialEnvelope` (strict JSON: `kind: "user-session"` = `WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND`, a JWT
   `accessToken` and a `refreshToken` under the same token law as the bare line, RFC 3339
-  `expiresAt` with seconds and a `Z` / `±hh:mm` offset in range, `issuer` = the issuing center's base URL judged
+  `expiresAt` with seconds and a `Z` / `±hh:mm` offset in range, `issuer` = the issuing web-admin's base URL judged
   by the same `NON_SECRET_URL` the `remoteExec` endpoints use — same-origin is the reader's comparison).
-  `parseCenterCredentialFile(text)` is the ONE discrimination law — trimmed text starting with `{` is read ONLY
+  `parseWebAdminCredentialFile(text)` is the ONE discrimination law — trimmed text starting with `{` is read ONLY
   as an envelope (a failure is `unreadable`, never a fallback to a bare line); anything else is a bare line,
   and a first line that is not a token is `unreadable` too (never sent as a bearer); empty is `unreadable`. The `reason` names envelope fields / zod issue codes / an unknown-key COUNT, never file
   content. Pure: reading, atomically writing and renewing the file are the consumers' job. S-742 lifts the
-  DECLARATION face here too: `CENTER_CREDENTIAL_ENV` (`{ token: "SEMA_REGISTRY_TOKEN", tokenFile:
-  "SEMA_REGISTRY_TOKEN_FILE" }` — one spelling for the center rendering worker env, the shell writing its local
-  engine's env, and the server reading it) and `judgeCenterCredentialDeclaration(env)` → `env` / `file` /
-  `absent`, the one pick-exactly-one rule: an empty string is unset, BOTH set (non-empty) throws (the refusal
+  DECLARATION face here too: `WEB_ADMIN_ENV` — every env name an engine reads to reach web-admin, one table
+  (`url` / `token` / `tokenFile` / `worker` / `liveUrl` / `webUrl` / `dryRun` / `adminToken` / `assertionToken` /
+  `assertionTokenFile`, values `SEMA_WEB_ADMIN_*`; one spelling for web-admin rendering worker env, the shell writing its
+  local engine's env, and the server reading it) and `judgeWebAdminCredentialDeclaration(env, credential)` — `credential` ∈
+  `WEB_ADMIN_CREDENTIALS` (`access` reads `token` / `tokenFile`, `assertion` reads `assertionToken` / `assertionTokenFile`;
+  no default) → `env` / `file` / `absent`, the one pick-exactly-one rule for every credential: an empty string is unset, BOTH set (non-empty) throws (the refusal
   names the two keys, never a value), the file path comes back verbatim (resolving a relative one against a cwd
   is the reader's job).
+- **Retired env names** (`retired-envs.ts`, main barrel): `RETIRED_ENVS` — the ONE tombstone table (literal tuples
+  `[old, to, "renamed"]` / `[old, to, "replaced", why]` / `[old, why, "removed"]`, a closed set of three families,
+  frozen). A tombstone is permanent: the old name present ⇒ refuse to start, whether or not the replacement is also
+  set (an empty string is unset); a chain is one hop (every row points at a current name). `retiredEnvRefusal(env)` is
+  the one refusal sentence (code `RETIRED_ENV_REFUSAL_CODE` = `config.env_key_retired`; names keys, never values;
+  pure — pass the env you are judging); `buildRetiredEnvWire()` is the catalog projection (`retired[]`). The engine's
+  boot, the shell starting a local engine and web-admin rendering worker env all judge this one table.
 - **Multi-tenant scopes** (`api/scopes.ts`, subpath `./api/scopes`): the scope contract — the `Scope`
   entity (`{id,name,createdAt}`, reserved default `"global"` always exists), per-scope `ScopeMember`
-  rows (`{scopeId,principal,role}` on the existing viewer<editor<publisher<admin ladder), the optional
-  JWT `scope` claim (absent = `"global"`, fully backward compatible; refresh tokens are never
-  scope-bound), and the wire shapes for `GET/POST /api/v1/scopes`, `POST /api/v1/auth/scope`
+  rows (`{scopeId,principal,role}` on the existing viewer<editor<publisher<admin ladder), the JWT
+  `scope` claim (every minted access token carries it; 11.0.0: a token without it is refused, not read as `"global"`;
+  refresh tokens are never scope-bound), and the wire shapes for `GET/POST /api/v1/scopes`, `POST /api/v1/auth/scope`
   (scope-switch mint, OAuth-style errors) and `PUT/DELETE /api/v1/scopes/{id}/members`. The DECISION
-  SEMANTICS live here as pure functions the registry imports (never re-implements):
+  SEMANTICS live here as pure functions web-admin imports (never re-implements):
   `resolveTokenScope` (mint-time scope binding: 1 membership → it; several incl. global → global;
   several without global → lexicographically first; none → `{scope:"global", role:instanceRole}`),
   `canSwitchScope` (member or instance admin), `effectiveScopeRole` (instance admin is `"admin"` in
-  every scope) and `tokenScopeOf` (missing claim = `"global"`). OpenAPI mirror: `docs/openapi-scopes.yaml`.
+  every scope) and `readTokenScope` (a set claim ⇒ `{ scope }`; a missing / empty / non-string claim ⇒ `{ refused:
+  "scope_claim_missing" }` — 11.0.0: no longer read as `"global"`). OpenAPI mirror: `docs/openapi-scopes.yaml`.
+- **Scope-bound tokens** (`api/pull-token.ts`, subpath `./api/pull-token`): the FORM and minting rule of the per-worker pull
+  token web-admin mints for every worker (`WEB_ADMIN_ENV.token`) — one rule, token families are data
+  (`ScopedTokenFamily = { v1Prefix, v2Prefix, macTag }`; `WORKER_PULL_TOKEN` = `wpt_` / `wpt2_` / `worker-pull`). Default scope ⇒
+  v1 `<v1Prefix><worker>_<mac>`, any other scope ⇒ v2 `<v2Prefix><scope>_<worker>_<mac>`, `mac` = HMAC-SHA256(shared key,
+  `<macTag>:v1:<worker>` / `<macTag>:v2:<scope>:<worker>`) in lowercase hex (pure-JS HMAC, byte-identical to `node:crypto`).
+  `mintScopedToken` throws instead of minting a token that could never verify (empty key, a scope that is not a scope id, a
+  worker name that is empty or carries the `_` frame separator); `readScopedTokenBinding` reads what a token CLAIMS;
+  `verifyScopedToken` = claim → re-mint → constant-time compare (a v2 token claiming the default scope never verifies).
+  The engine only carries the token as an opaque bearer.
+- **Principal length** (`api/auth-bridge.ts`): `PRINCIPAL_MAX_LENGTH` = 190 — the engine's principal gate refuses a longer
+  one; validate / mint principals against this value.
+- **/bug reports** (`api/feedback.ts`, subpath `./api/feedback`): `FeedbackSubmitRequest` (the POST body the shell sends to
+  `FEEDBACK_V1_PATH`; `description` trimmed, non-empty, ≤ `FEEDBACK_DESCRIPTION_MAX_CHARS`; `transcript` serialized ≤
+  `FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS`; `principal` is never a body field — it is the token subject), `FeedbackWire` (one
+  report row, server-stamped `createdAt`) and `FeedbackListResponse`.
+- **Content digest form** (`sha256.ts`): `Sha256Digest` / `SHA256_DIGEST_RE` — the one `sha256:<64 lowercase hex>` spelling every
+  digest-bearing seat in this package uses.
 - **Local file source** (`file-store.ts`, `file-edit.ts`): `FileConfigStore` reads `config.d/*.json` →
   `EffectiveConfig`; `validateDomain` / `writeDomainFile` / `listRequiredEnvNames` are the TOC's
   read/write/validate helpers. `getEffective({tolerant:true})` (0.10.12) isolates a malformed
@@ -288,7 +352,8 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   and any top-level key a domain schema strips are both NAMED through `onWarning`
   (`unread-config-file` / `unknown-keys-dropped`) instead of vanishing silently (**6.3.0**: every warning coordinate —
   unknown keys included — leaves through `redactSecrets`, so a secret-shaped key segment reads `[redacted-secret]`;
-  `droppedKeys` / `carriedUnknownKeys` return the same outgoing form). **2.0.0** adds per-ENTRY
+  the unknown-key scans behind those warnings are module-private since 11.0.0 — `parseDomainLoud` is the one public
+  primitive). **2.0.0** adds per-ENTRY
   tolerance on the same read path: one malformed catalog entry is dropped on its own (named through
   `onWarning` as `entry-dropped`) and its siblings survive, instead of the whole domain falling to
   its schema default. It is the SAME `DOMAIN_READ_FALLBACK` table that decides where this applies — gate
@@ -340,15 +405,15 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   (forward-compatible: unknown fields survive a round-trip, malformed records are dropped one by one).
 - **Fleet contract** (`fleet.ts`, subpath `./fleet`): drain protocol, instance discovery, dispatch policy,
   quota lease, usage report, quota-reset event. **S-741** adds the restart signal, defined ONCE:
-  `RestartSignal` (`{ reasons: string[] (≥1, non-empty words), version: number (the config-center version that
+  `RestartSignal` (`{ reasons: string[] (≥1, non-empty words), version: number (the web-admin config version that
   differs from boot — finite, judged exactly as `readEffectiveWire` judges a config version), since: number (epoch
   ms, non-negative integer) }` — exactly what the server already ships on /health). The heartbeat carries it as
-  `InstanceAnnouncement.restart?` (so `InstanceRegistration` carries it too); on /health, `InstanceHealth` is
-  UNCHANGED (passthrough — `restart` and the redundant top-level `restartRequired` ride untyped, so today's lenient
-  read stays lenient) and `readRestartSignal(health)` reads `health.restart` against the one shape (`undefined` on
-  any mismatch, never throws). Presence is the signal (present ⇔ restart required; no `required` boolean inside).
-  A heartbeat re-announces the full row, so one without `restart` means "no longer required". Typing
-  `InstanceHealth.restart` strictly is left for the next major. **S-768** adds the model-refusals signal the same
+  `InstanceAnnouncement.restart?` (so `InstanceRegistration` carries it too); on /health it rode untyped
+  (passthrough, next to the redundant top-level `restartRequired`). Presence is the signal (present ⇔ restart required;
+  no `required` boolean inside). A heartbeat re-announces the full row, so one without it means "no longer required".
+  Since 11.0.0 it is engine state and is read in ONE place on both exits — inside `EngineSignal` under `engineSignal`
+  (`readEngineSignal(body)?.restart`); the flat `restart` both bodies still carry is the pre-11 dialect, read by nothing,
+  and the flat reader `readRestartSignal` is gone. **S-768** adds the model-refusals signal the same
   way (one mint point, two exits, ONE reader): the wire face `ModelRefusalsWire` (`{ entries: { <catalog entry name>:
   <code> }, plane?: <code> }` with codes as open strings — name → code is the whole wire, no upstream id / provider /
   field keys / prose) rides the heartbeat as `InstanceAnnouncement.modelRefusals?` and /health (`InstanceHealth` again
@@ -364,30 +429,40 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   rule the dropped-entry identity on read warnings already uses: the `DISCLOSABLE_IDENTITY_RE` allowlist ∧ not
   secret-shaped, 6.3.0). **8.1.0** (additive) puts the engine's own state in one closed shape: `RestartSignal` gains the
   optional `withheld` ("the engine says this beat must not be handed to a new generation"; absent ≡ false);
-  `EngineSignal` (`{ ready, draining?: EngineDraining, restart?, generation?, instanceId?, leaseUntil?,
-  configTargetVersion?, configAppliedVersion? }`) is the closed form of the engine-minted subset of the /health
-  self-description (`InstanceHealth` stays the open record; neither exit carries it whole yet — see its doc comment) and
-  `readEngineSignal(health)` reads it through the same guarded reader as `readRestartSignal` / `readModelRefusals` —
-  `undefined` means "no such signal", never "ready", and a body carrying the boolean `draining` of the 8.0 dialect is not
-  one. The serving-lease wire (`ServingLeaseRequest` / `ServingLeaseResponse`: `granted { ttlMs }` | `denied { reason:
+  `EngineSignal` (`{ ready, draining?: EngineDraining, restart?, generation?, leaseState?, leaseUntil?,
+  configTargetVersion?, configAppliedVersion? }`; 11.0.0 took `instanceId` out — the instance's identity is the body's top
+  level) is the closed form of what the engine mints about itself. **11.0.0**: it rides
+  BOTH exits (`/health` and the heartbeat) WHOLE under the one key `ENGINE_SIGNAL_KEY` (`"engineSignal"`) — nested, because the
+  boolean `draining` dialect is still sent in its contraction window and one key cannot hold a boolean and an object;
+  `readEngineSignal(body)` reads that key only (same guarded reader as `readModelRefusals`; `undefined` =
+  "no such signal", never "ready"), both shapes type it (`InstanceAnnouncement.engineSignal` / `InstanceHealth.engineSignal`, a
+  malformed one is absent),
+  and the judges read nothing else: `judgeReadiness(signal)` / `judgeRoutability(row, nowMs)` → `{ routable: true }` |
+  `{ routable: false, code, why }` (closed set `NOT_ROUTABLE_CODES`: no-engine-signal / stale / observer-not-ready / draining /
+  not-ready), with `isReadyForTraffic` / `isRoutable` / `routableInstances` as their boolean forms. A row or body without the
+  signal — an engine that predates it — is `no-engine-signal`, never routable. One fact, one place: engine state only in the
+  signal, the row's identity (`instanceId`, `worker`, `address`, `version`, `heartbeatMs`) only at the top level; the flat state
+  keys both bodies still carry (`ready`, the boolean `draining` / `drainingSince`, `restart`, `generation`, `leaseState`,
+  `leaseUntil`) are the pre-11 dialect — shape unchanged, `@deprecated`, read by nothing here; their removal is registered in
+  `ONE_TIME_MIGRATIONS`. The serving-lease wire (`ServingLeaseRequest` / `ServingLeaseResponse`: `granted { ttlMs }` | `denied { reason:
   superseded | retired }` | `unknown` — a closed three-word set in which `unknown` is NOT a kind of `denied`; plus
   `SERVING_LEASE_TTL_DEFAULT_MS` 600 000, `SERVING_LEASE_TTL_FLOOR_MS` 60 000 and `SERVING_LEASE_DRIFT_MARGIN_MS`, derived
-  from `DEFAULT_HEARTBEAT_MS`; `denied` rests on positive evidence only), the center capability bit `CenterCapabilities`
-  (`servingLease?: true` — absent means the center has no lease, so the engine neither renews nor is fenced), the drain
+  from `DEFAULT_HEARTBEAT_MS`; `denied` rests on positive evidence only), the web-admin capability bit `WebAdminCapabilities`
+  (`servingLease?: true` — absent means web-admin has no lease, so the engine neither renews nor is fenced), the drain
   endpoint's `DrainRequest` / `DrainReceipt`, one reader per wire shape, and the env name `FLEET_GENERATION_ENV` are defined
   here once for the renderer and the engine (an instance's id is minted by the engine per process — it has no env name).
   **8.2.0** (additive) adds the engine's lease vocabulary `LEASE_STATES` (`none | granted | expired | denied`) as
   `EngineSignal.leaseState?`, keeps `generation` / `leaseState` / `leaseUntil` on the heartbeat (`InstanceAnnouncement` no longer
-  strips them; a malformed one drops to absent, the heartbeat still lands), spells the center's fleet endpoints once —
+  strips them; a malformed one drops to absent, the heartbeat still lands), spells web-admin's fleet endpoints once —
   `FLEET_PATHS` (heartbeat, usage, quota leases, serving lease `/api/fleet/live/serving-lease`, host planner
   `/api/fleet/live/host-planner/{host}`) and the liveness group `FLEET_LIVE_PATHS` (heartbeat, serving lease, host planner), also
   shipped as `@sema-agent/settings-schema/fleet-paths.json` for tooling that cannot import TypeScript — and names the one carrier of
-  the center's capability bits: `HEARTBEAT_REPLY_CAPABILITIES_KEY` (`"capabilities"`) on the heartbeat's 2xx reply.
+  web-admin's capability bits: `HEARTBEAT_REPLY_CAPABILITIES_KEY` (`"capabilities"`) on the heartbeat's 2xx reply.
   **8.3.0** (additive) adds the env name `FLEET_SCOPE_ENV` (`"FLEET_SCOPE"`) — the tenant scope a fleet member belongs to, set by the
   config renderer and read by the engine as its own identity's scope (absent ⇒ `GLOBAL_SCOPE`); a reserved worker env name.
   **9.0.0** (BREAKING) replaces `readCenterCapabilities` with the three-state reader `readCapabilityReading(reply)` (`declared` |
   `undeclared` | `unreadable` — a malformed declaration is not an absent one) and types `EngineSignal`'s two config-version keys as numbers.
-- **Declared-but-unvalidated keys** (`PARSE_TRANSPARENT_KEYS`, 2.0.0): the ONE registry of keys this package
+- **Declared-but-unvalidated keys** (`PARSE_TRANSPARENT_KEYS`, 2.0.0): the ONE web-admin of keys this package
   carries verbatim WITHOUT checking their shape, each row naming who does check it (the engine's ingest side or
   a consumer's enforcement point). Today: `models[].compat` (1.10.0), `models[].headers` (6.4.0; the header-name
   allowlist × lane is sema-server's, not restated here), `mcp.servers[].source` (1.7.2), `mcp.servers[].toolFaces`
@@ -402,9 +477,10 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 ## Cross-repo conformance gate (`./conformance`, 3.0.0)
 
 契约仓自带**金样语料 + 比对器**,随包发(`conformance/cases/**`)。每个消费方把**自己的生产入口**塞给
-kit 跑一遍 ⇒ 同一份 settings 语料在配置中心、worker、管理面、契约仓自身读出的 effective 逐字节一致、
+kit 跑一遍 ⇒ 同一份 settings 语料在 web-admin、worker、管理面、契约仓自身读出的 effective 逐字节一致、
 告警多重集一致;写入席对同一份文档收不收也一致。**四条腿**(8.0.0):`domains`(各域原始文档 → effective)、
-`strictWrite`(同一份文档 → 严写受理;契约仓 = `parseDomain`,任一份不受理 ⇒ `rejected{validate}`,读腿抢救处严写拒)、
+`strictWrite`(同一份文档 → 严写受理;契约仓 = `parseDomainLoud` + 跨域引用完整性,任一份不受理 ⇒ `rejected{validate}`,悬空引用 ⇒
+`rejected{validate, ref-integrity}` 带 `refIssues` 坐标,读腿抢救处严写拒;受理时的剥键 / 承运告警进告警面)、
 `wire`、`localRoot`。
 
 ```ts
@@ -465,15 +541,15 @@ defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
   codex 复审持「严格 semver 应升 major」异议,原样留档候裁)。
 - **文案 / 注释 / 测试 / bug 修复 = patch**:不改任何 wire 形、类型面、默认值与校验结果。行为面的
   「修 bug」若改变了合法输入的解析结果,按上两档判,不按 patch。
-- 契约破坏面动之前先盘 center / server / CLI 三方消费点;commit message 的 `feat!`/`BREAKING` 标记照旧,
+- 契约破坏面动之前先盘 web-admin / server / CLI 三方消费点;commit message 的 `feat!`/`BREAKING` 标记照旧,
   但标记不豁免版号义务。每版 CHANGELOG 一节,git tag `v<version>` 同名。
 - **持久数据面的破坏性变更(例:7.0.0)**:类型 / API 面直接删改、零别名(消费方 tsc 红即通知);**存下来的数据**不会自己红,
   所以同版配三件:读到旧形即**响亮拒**(拒因指路迁移命令,不是被 zod 静默剥掉)、一只**一次性迁移**(纯函数、幂等、
-  表达不了就 refused 点名,不替运维猜)、以及一个**写明的删除窗**(7.0.0 的 `migrateWorkersDomain` 在中心接上迁移后的下一版删除)——
+  表达不了就 refused 点名,不替运维猜)、以及一个**写明的删除窗**(7.0.0 的 `migrateWorkersDomain` 在 web-admin 接上迁移后的下一版删除)——
   绝不长成长命双读。
 - **历史注记(0.x 时代)**:0.x 下 `^0.7.0` 这类 range 只自动收 patch,故当年规矩是「破坏性必 bump
   minor,patch 只装 additive/修 bug/文档」。0.7.1(2026-07-10)曾携带两件预协调 BREAKING(撤 governance
-  effective 双写镜像、撤 QuotaLease 0.5 `tokens` 别名 shim),名义上违反该条;当时下游(center/service
+  effective 双写镜像、撤 QuotaLease 0.5 `tokens` 别名 shim),名义上违反该条;当时下游(web-admin/service
   1.150.0)均已显式迁移、实际破坏面为零,PM 拍板不重发 0.8.0(纯扰动)。该例外随 1.x 政策一并归档。
 - 发布(单腿 npmjs,内网腿已废止):`npm run publish:npm`;发后必须 curl 直打 npmjs 复验 shasum。
 
@@ -482,4 +558,4 @@ defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
 - 真源 = `sema-agent/sema-settings-schema` org 仓 `main`(2026-08-26 由 sema-registry-core 改名),所有变更直接落 org main(或 PR 进 main);
   不再向任何个人位/镜像位 push。
 - 提交门 = `npm run build` + `npx vitest run`;改域/契约后必跑 `npm run e2e`(examples/toc-e2e.mjs)。
-- 契约破坏面动之前先盘 center / server / CLI 三方消费点;破坏性变更必 bump major(见上节)。
+- 契约破坏面动之前先盘 web-admin / server / CLI 三方消费点;破坏性变更必 bump major(见上节)。

package/bin/settings-schema.mjs

@@ -1,20 +1,27 @@
 #!/usr/bin/env node
-// `settings-schema` — this package's command line (7.0.0: `migrate-workers <workers.json> [--check]`).
+// `settings-schema` — this package's command line (11.0.0: `migrate <config.d directory> [--check]`, the one-time migrations).
 // The ONLY place the package writes files with node:fs; the logic is `runSettingsSchemaCli` (dist/cli.js), which never
 // touches the filesystem itself — this entry injects real file I/O into it.
-import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { runSettingsSchemaCli } from "../dist/cli.js";
 
 const io = {
+  readDir: (path) => readdir(path),
   readFile: (path) => readFile(path, "utf8"),
-  // atomic: write a sibling temp file (same mode as the original), then rename over it — a half-written workers
-  // document is worse than the old one.
+  // atomic: write a sibling temp file (same mode as the original when there is one), then rename over it — a half-written
+  // domain document is worse than the old one.
   writeFileAtomic: async (path, text) => {
-    const { mode } = await stat(path);
+    let mode = 0o600;
+    try {
+      mode = (await stat(path)).mode & 0o777;
+    } catch (e) {
+      if (e?.code !== "ENOENT") throw e;
+    }
     const tmp = `${path}.migrate-${process.pid}.tmp`;
-    await writeFile(tmp, text, { encoding: "utf8", mode: mode & 0o777 });
+    await writeFile(tmp, text, { encoding: "utf8", mode });
     await rename(tmp, path);
   },
+  removeFile: (path) => unlink(path),
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text),
 };

package/conformance/VERSION

@@ -1 +1 @@
-10.0.0
+11.0.0

package/conformance/baseline.json

@@ -23,6 +23,9 @@
     "servers": []
   },
   "models": {
+    "atMention": {
+      "mode": "all"
+    },
     "models": [],
     "roles": {},
     "tierGroups": []
@@ -39,7 +42,6 @@
   "rosters": {
     "rosters": []
   },
-  "runtime": {},
   "scenarios": {
     "scenarios": []
   },

package/conformance/cases/c01-entry-salvage-then-typo/expected.json

@@ -26,6 +26,9 @@
         "servers": []
       },
       "models": {
+        "atMention": {
+          "mode": "all"
+        },
         "models": [
           {
             "api": "openai-completions",
@@ -55,7 +58,6 @@
       "rosters": {
         "rosters": []
       },
-      "runtime": {},
       "scenarios": {
         "scenarios": []
       },

package/conformance/cases/c02-hosts-clamp-stacked/expected.json

@@ -34,6 +34,9 @@
         "servers": []
       },
       "models": {
+        "atMention": {
+          "mode": "all"
+        },
         "models": [],
         "roles": {},
         "tierGroups": []
@@ -50,7 +53,6 @@
       "rosters": {
         "rosters": []
       },
-      "runtime": {},
       "scenarios": {
         "scenarios": []
       },
@@ -67,10 +69,15 @@
     "warnings": [
       {
         "domain": "hosts",
-        "droppedNames": [
-          "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx…"
+        "identity": {
+          "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+        },
+        "kind": "entry-dropped",
+        "path": [
+          "hosts",
+          0
         ],
-        "kind": "hosts-grandfathered"
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "hosts",
@@ -93,7 +100,7 @@
   "strictWrite": {
     "outcome": "rejected",
     "stage": "validate",
-    "why": "拒:读腿对 hosts 先做存量夹紧(超长名剔除,hosts-grandfathered)再逐条抢救(entry-dropped);两样都只活在读路径,严写按现行 schema 判:名长 > 63 与名字形不合法都拒。"
+    "why": "拒:严写按现行 schema 判 —— 名长 > 63 与名字形不合法都拒;读腿逐条抢救(entry-dropped)。读写同一只 schema(11.0.0 起读侧不再夹紧)。"
   },
   "wire": {
     "derive": true

package/conformance/cases/c02-hosts-clamp-stacked/meta.json

@@ -1,6 +1,6 @@
 {
   "contributor": "contract",
-  "claim": "读路径上有两个压缩点(hosts 的按名夹紧 + 逐条抢救)。两层叠加时,内层铸的 entry-dropped 坐标要过外层的位移表一次才是原文档坐标(S-323b)。少回写一层,告警就指向第三条别人的记录。",
+  "claim": "读路径上只剩一个压缩点(逐条抢救;11.0.0 起 hosts 的读侧夹紧臂退役,超长名那一条也由它剔)。超长名与形不合法的条目都作 entry-dropped 报原文档坐标;同文档里的拼错键回写到原下标。少回写一次,告警就指向别人的记录。",
   "firstRedOn": [
     "settings-schema@1.0.0",
     "settings-schema@1.10.0",

package/conformance/cases/c03-literal-dotted-top-key/expected.json

@@ -26,6 +26,9 @@
         "servers": []
       },
       "models": {
+        "atMention": {
+          "mode": "all"
+        },
         "models": [
           {
             "api": "openai-completions",
@@ -67,7 +70,6 @@
       "rosters": {
         "rosters": []
       },
-      "runtime": {},
       "scenarios": {
         "scenarios": []
       },
@@ -106,6 +108,9 @@
     "outcome": "effective",
     "effective": {
       "models": {
+        "atMention": {
+          "mode": "all"
+        },
         "models": [
           {
             "api": "openai-completions",
@@ -136,7 +141,22 @@
         "tierGroups": []
       }
     },
-    "warnings": [],
+    "warnings": [
+      {
+        "domain": "models",
+        "keys": [
+          [
+            "models",
+            1,
+            "k"
+          ],
+          [
+            "models.1.k"
+          ]
+        ],
+        "kind": "unknown-keys-dropped"
+      }
+    ],
     "metadata": {
       "version": 7,
       "updatedAt": "2026-09-16T00:00:00.000Z"

package/conformance/cases/c04-all-bad-collection-not-salvaged/expected.json

@@ -26,6 +26,9 @@
         "servers": []
       },
       "models": {
+        "atMention": {
+          "mode": "all"
+        },
         "models": [],
         "roles": {},
         "tierGroups": []
@@ -42,7 +45,6 @@
       "rosters": {
         "rosters": []
       },
-      "runtime": {},
       "scenarios": {
         "scenarios": []
       },