@sema-agent/settings-schema 10.1.0 → 11.0.0

package/CHANGELOG.md

@@ -6,6 +6,425 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 11.0.0 — 2026-10-10 — 依赖换 zod 4、三处死出口收回、持久面一次性迁移族、同一个问题一只判官、名与契约(major)
+
+> 本节四件:以下先是平台一件(zod 4 + 三处出口收窄 + 上游锚抬钉),再是持久面一件(「持久面」一节起),再是判官一件(「判官」一节起),再是名与契约一件(「名与契约」一节起)。每条硬破坏写三句:谁受影响 / 怎么改 / 不改会怎样。
+
+### 硬破坏:运行期依赖由 zod 3 换成 zod 4
+
+`dependencies` 与 `peerDependencies` 的 `zod` 由 `^3.24.0` 改为 `^4.4.0`。**没有哪只 schema 改了受理什么、产出什么**:符合性语料 84 条 × 四条腿、
+workers 迁移金样、空文档集与样例目录、外加 21 枚针对 zod 3 / 4 语义差的探针,在 zod 3.25.76 上录下的读数(effective、告警投影多重集、结局与拒绝层、迁移输出)
+在 zod 4 上逐字节相同(平台一件落地时由 `test/zod-major-equivalence.test.ts` 钉住;该钉随后按寿命条款删除,见「持久面」一节的「其余」);当时在 zod 4 树上
+重新加冕语料,84 条 `expected.json`、迁移金样与 `baseline.json` 原样不变(之后持久面一件有意改了语料读数,同见那一条);
+另对 113 份语料域文档做 30000 次确定性变异、对全部导出 schema 做 12360 组生成输入,两版本的受理与产出逐条相同。变的只有**错误的文本**(下一节)。
+
+- **谁受影响**:宿主树里还在 zod 3 的消费方(今天是管理面 sema-web-admin)—— peer 不满足,npm 把本包的 zod 4 嵌套装进它的树,两份 zod 并存;
+  其余宿主(server / CLI / client-core / SDK,都在 zod 4)反而从「本包嵌套一份 zod 3」变成同段一份。另:钉了 zod 3 错误原句或 issue code 的测试与文案。
+- **怎么改**:宿主升 zod 4(`^4.4.0` 同段即单实例);重跑钉了校验错误原句 / issue code 的格,按下一节改读法。
+- **不改会怎样**:zod 3 宿主照样能装能用(跨缝只传纯数据、经本包导出的函数用本包 schema,与 11.0.0 之前 zod 4 宿主的处境对称);
+  但跨实例的 `instanceof ZodError`、把宿主 schema 与本包 schema 组合,在两实例下都不成立。
+
+### 行为变(型面以外):校验错误的文本随 zod 4 改变
+
+- issue code 改名:`invalid_string` → `invalid_format`;`invalid_enum_value` → `invalid_value`(问题里带 `values`,不再有 `options` / `received`);
+  `invalid_union_discriminator` → `invalid_union`(带 `options`);`invalid_type` 不再带 `received` 字段;句子全换成 zod 4 的英文模板。
+  **按 issue code 分流的消费方要改读新码**(发版前普查:管理面的表单错误映射与 env 名拒因两处按 `invalid_string` / `invalid_enum_value` 分流;
+  不改 ⇒ 这两类错误落到它们的缺省臂,界面上的说明退成泛化句,受理与否不受影响)。
+- 枚举不中的句子**不再回显输入值**(zod 3 的句尾 `received '<值>'`;zod 4 只列允许值)。本包为改写那句而设的内部渲染件随之删除,workers 一行的拒因句
+  (一次性迁移 SS-M4 的 `refused` 收据、`readWorkersRows` 的 `held[].reason`)改用 zod 的 issue 句原样(仍不回显值)。
+- 闭集为键的 Record(`models.roles`、`rosters[].roles`、`HooksConfig`)出现闭集外的键:zod 3 在 `[…, 键]` 上报一条枚举不中;zod 4 在 Record 本身上报
+  `unrecognized_keys`(`keys` 点名那个键)。逐条容错读(`entry-dropped`)不受影响:键仍按键 schema 单独判。
+- 按模式约束键的 Record(如 `orgMemory` 的 `org:` 键)出现坏键:zod 4 报 `invalid_key`(句子 `Invalid key in record`),键 schema 自己的句子嵌在它的 `issues` 里。
+  `sanitizeZodError` 递归脱敏这些嵌套 issue(以及 `invalid_union` 的 `errors`),并按脱敏后的 issue 重铸 `message`。
+- 预处理(workers 的「删除项读到即拒」)报了错时,zod 4 不再接着报同一行的其余 issue(zod 3 两组都报):受理与否不变,一处报几条变了。
+- `validateDomain` / `validateRemoteExec` 返回的 `issues` 是 zod 4 的 `ZodIssue` 型(`path` 型为 `PropertyKey[]`;本包的输入是 JSON,经脱敏后的路径段恒为串或数)。
+- 只对 JS 调用方可见(JSON 表达不出):未带 `.finite()` 的数字字段收到 `Infinity` 时 zod 4 拒(zod 3 收);对象键是 Symbol 的 Record 输入 zod 4 拒(zod 3 忽略)。
+- 发布物里 `d.ts` 的 schema 对象形成员不再带 JSDoc(zod 4 的 `z.object()` 签名经一层映射类型,声明输出里成员注释丢失;顶层导出的注释一个不少,构建开关不变)。
+
+为保住「受理什么、产出什么」不变,源码按 zod 4 语义改了五类形(都只在本包内部):对象 / 数组字面缺省由 `.default` 改 `.prefault`(内层缺省照样物化);
+闭集键 Record 改 `z.partialRecord`;整数判据单立为 `Number.isInteger`(zod 4 的 `.int()` 另拒 ±(2^53−1) 之外的整数,存量文档里的大整数照收);
+URL 判据不再借 zod 的 `.url()`(它会 trim 并删 tab / 换行、交回改写后的值),值原样保留;收 `undefined` 的对象键补 `.optional()`(zod 4 要求非可选键在场)。
+
+### 硬破坏:删 `./migrate` 出口(22 名)
+
+`./migrate` 子路径、根入口对它的再导出、`src/migrate.ts` 整件删除:`grandfatherHosts` / `GrandfatherHostsResult`、`planWorkerModelMigration` / `applyModelMigrationPlan` /
+`migrationDiffViolations` / `canonicalModelKeyEnv` 与它们的型(`LegacyWorkerModel` / `ModelDraftEntry` / `ModelMigrationDraft` / `ModelMigrationConflict` /
+`ModelMigrationReuse` / `RosterAction` / `ModelMigrationPlan` / `ExistingModelEntry` / `PlanMigrationOpts` / `ApplyMigrationDocs` / `ApplyModelMigrationResult`)、
+`migrateTeamsToCollab` / `DEFAULT_COLLAB_BUDGET_TOKENS` / `LegacyTeamDef` / `TeamsToCollabResult` / `MigratedCollabConfig`。0.5 → 0.7 的一次性迁移窗口早已过去。
+
+- **谁受影响**:import 这些名字或 `@sema-agent/settings-schema/migrate` 的代码。发版前逐名普查:管理面已把三处读点退役,server / CLI / client-core / SDK / core 零读点。
+- **怎么改**:删掉 import;还没跑过 0.5 → 0.7 迁移的存量库,先在 10.x 上跑完再升。
+- **不改会怎样**:tsc 红;运行期 `ERR_PACKAGE_PATH_NOT_EXPORTED` / 导入名 `undefined`。
+
+### 硬破坏:未知键扫描不再导出(`droppedKeys` / `carriedUnknownKeys` / `UnknownKeyScan`)
+
+两只扫描改为模块私有,它们的返回型 `UnknownKeyScan` 一并收回;完整原语 `parseDomainLoud` 不变 —— 它的告警(`unknown-keys-dropped` / `unknown-keys-carried`)
+带有界的 `keys` 与截断前总数 `truncatedFrom`,两个数仍由同一只扫描拼出。
+
+- **谁受影响**:直接调用这两只函数的代码(发版前普查:各仓同名命中都是各自的字段名,零 import)。
+- **怎么改**:调 `parseDomainLoud(domain, raw, onWarning)`,读告警的 `keys` / `truncatedFrom`。
+- **不改会怎样**:tsc 红;运行期导入名 `undefined`。
+
+### 硬破坏:hook 事件闭集只导出一个名(`CC_198_HOOK_EVENTS` / `POST_198_HOOK_EVENTS` 收回)
+
+两半(来自 CC 2.1.198 那张表的 27 个、之后加的 6 个)改为模块私有,导出的闭集只有 `HOOK_EVENTS`(33 个,次序不变)。
+
+- **谁受影响**:import 这两个半张表的代码(发版前普查:生产零读点,只有 CLI 一格负控测试拿它当干扰形)。
+- **怎么改**:读 `HOOK_EVENTS`;要「哪些是 2.1.198 的」就取 `HOOK_EVENTS.slice(0, 27)`。
+- **不改会怎样**:tsc 红;运行期导入名 `undefined`。
+
+### 硬破坏:`SAFETY_MERGE_SPEC.shellGate` 的收紧序收成引擎的一个词
+
+`shellGate.tighten.order` 由 `["off", "classify", "always"]` 改为 `["always"]`;`TightenRule` 的 `enumRank.order` 下限由 2 个词改为 1 个(一个词的序 = 词表只有它,合并只有恒等)。
+引擎(core 7.34.0 起)的 shell 地板只剩 `always`,`off` / `classify` 在引擎入口响亮拒;本包的上游漂移门对 core 7.47.0 读到这处差而红,按引擎的事实改真。
+
+- **谁受影响**:按本表给 `shellGate` 排序合并的设置解析器(发版前普查:server 已不读这条序;CLI 的解析器没有 `shellGate` 这一格);用 1.x 冻结形 schema 校验整张表的代码(这一类目不再过 `min(2)`)。
+- **怎么改**:`shellGate` 只认 `always`;`off` / `classify` 在设置层就按词表外处理(与引擎入口同判)。
+- **不改会怎样**:词表外的 `off` / `classify` 在设置合并时落到「词表外」那一臂(拒),而不是被排序后送到引擎再被拒。
+
+### 持久面:读路径零抬升臂,旧形由登记过窗的一次性迁移改写一次(`./one-time-migrations`)
+
+律(一条):**旧形只有一种去处 —— 一次性迁移把它改写成新形(调用方写回、幂等、只认形);读写两面遇旧形一律响亮拒,拒句点名迁移 id。**
+10.x 的读路径上有五只常驻兼容臂,每次读都把同样的旧数据抬一遍、从不写回:治理三闸从 `runtime` 文档抬进 `governance`、未知键扫描为 `runtime`
+上的三闸开豁免、hosts 超界夹紧、调度店 durable 键重铸、workers 6.x 行读时抬升。11.0.0 起常驻臂为 0;唯一的读时改写是调度店那一条(登记在迁移表里、
+随迁移族删)。窗只登记在 `ONE_TIME_MIGRATIONS` 一处(到期门与回填门:`test/one-time-migration-window-gate.test.ts`);src / 文档里不许再出现
+「下一个 major 删」类散文窗(散文窗门:`test/self-declared-window-gate-11.0.0.test.ts`)。
+
+**新子路径 `./one-time-migrations`**(不进主入口):`migrateStoredDocuments(docs, { coverage })` / `migrateEffectiveSnapshot(effective)` /
+`migrateSchedulerRecords(records)`、登记表 `ONE_TIME_MIGRATIONS` 与行型 `OneTimeMigrationWindow`、收据 `MigrationReceipt`(闭集 `MIGRATION_APPLIED_AS`:
+`moved` / `rewritten` / `dropped-shadowed` / `dropped-inert` / `refused`)、数据迁移 id 闭集 `ONE_TIME_MIGRATION_IDS`(SS-M1…SS-M7 + SS-M9;SS-M9 见「判官」小节;收据只许这些 id)、wire 退役位 id 闭集
+`WIRE_RETIREMENT_IDS` + `WireRetirementId`(SS-W1,同表登记、没有收据,见「名与契约」)、`urlSeatPatterns()`。
+纯函数:不读环境、不读墙钟、不改入参、**不抬任何版本号**(草稿版本、快照的版本 / 全局修订号由调用方决定动不动);没改的文档原样(同一引用)返回。
+命令行:`npx @sema-agent/settings-schema migrate <config.d> [--check]`(取代 `migrate-workers`,同一只函数)。写回前对要写的每个域文档(改过的、新建的)
+跑一次整域终判(读侧那一只 `parseDomain`:名字 / 路由前缀唯一这类跨行规则只有整域判得出),读不进 ⇒ `outcome=refused written=false`、rc 1、一字不写,
+`refused[]` 逐条带整域拒因(与迁移步的拒同一套形,`migration: null`);`--check` 过同一只判定(不会报 pending 而真跑报 refused)。
+
+管理面起服迁移的四个前提,本版逐条成立:
+1. **principal 层也迁**:个人 models / mcp / skills / plugins 是同形的域文档,`migrateStoredDocuments(…, { coverage: "partial" })` 照迁(钥匙双设、
+   `atModelAllowlist`、URL fragment 三条落在这几个域上)。
+2. **接受单域子集**:`coverage: "partial"` 下缺的域 = 不动、不新建;`runtime` 只能连同它那个 scope 的 `governance` 与 `limits` 一起迁 ——
+   回滚史里单独一行 `runtime` 迁不了(收据 `refused`,原样留),回滚到它由墓碑响亮拒(不可恢复)。
+3. **不抬草稿版本**:函数纯,结果里没有版本;冻结快照的 `version` / `updatedAt` 与其余信封键原样。
+4. **迁移期不混跑 10.x 与 11.x 的管理面副本**(运维约束):**谁受伤** —— 10.x 副本会照旧写出旧形(`runtime` 文档、`atModelAllowlist`、双设钥匙),
+   11.x 副本与 11.x 引擎读它会拒(`runtime` 整份拒;`atModelAllowlist` 让 models 域降级 / rosters 整份拒);**什么补偿** —— 先把所有副本升到 11.x
+   再起服迁移;迁移幂等,任何一个 11.x 副本起服再跑一次都只会补上漏的,不会重改已迁的。
+
+#### 硬破坏:`runtime` 域退役(16 域)
+
+`DOMAINS` / `DOMAIN_SCHEMAS` / `EffectiveConfig` / `DOMAIN_READ_FALLBACK` 去掉 `runtime`;删 `RuntimeConfig`、`GOVERNANCE_MIRROR_KEYS`、`legacyGovernanceFromRuntime`、
+告警员 `legacy-governance-lifted`;`PORTABLE_DOMAINS` 去掉 `runtime`。新增墓碑表 `RETIRED_DOMAINS`(+ `RetiredDomainName` / `isRetiredDomainName` /
+`retiredDomainSentence`)与 `RetiredDomainError`(`code: "retired_domain"`、`domain`、`migration`):`parseDomain` 写 `runtime` 拒;`buildEffective` 会向店要
+`"runtime"`(`getRaw` 的参数型因此是 `DomainName | RetiredDomainName`,即 `StoredDocumentReader`),带事实(在场且不是 `{}`)⇒ 整份抛;`readEffectiveWire`
+遇 wire 上带事实的 `runtime` 整包抛、`{}` 不再当未知键承运;读 `config.d/` 的每个入口(`FileConfigStore` 的 `getDomain` / `getEffective`
+—— 于是经 `getDomain` 读的 `exportBundle` —— 与 `readBundle`)都先判 `config.d/runtime.json` 的墓碑,不论要的是哪几个域:带事实 ⇒ 同一句 `RetiredDomainError`,
+不交回一份静默丢了限额的 bundle。改写:一次性迁移 SS-M1。
+
+- **谁受影响**:读 `eff.runtime` / `RuntimeConfig` / `GOVERNANCE_MIRROR_KEYS` / `legacyGovernanceFromRuntime` 的代码;穷举告警种类的 switch;自己实现 `getRaw` 的店
+  (要能答 `"runtime"`);还存着 runtime 文档的中心与本地目录(含 10.x 导出、`config.d/` 里带 `runtime.json` 的 bundle);写 runtime 域的编辑面与路由。
+- **怎么改**:五个限额键读 `limits`,治理三闸读 `governance`;switch 删 `legacy-governance-lifted` 一臂;`getRaw` 对退役域名照实返回店里的文档;
+  起服对存量跑 SS-M1(scope 全集,`coverage: "scope"`)。写 runtime 的路由删掉。
+- **不改会怎样**:tsc 红;没迁的 scope 整份读不出(`RetiredDomainError`,句子点名 SS-M1);一个仍发 `runtime` 限额的更老中心,11.x 引擎读它的 wire 会整包拒、
+  回落上一份好配置。
+
+#### 硬破坏:hosts 读侧夹紧臂退役
+
+删 `grandfatherHostsRead` / `GrandfatherHostsReadResult` 与告警员 `hosts-grandfathered`;读写同一只 schema。名长 > 63 的条目在读侧逐条丢(`entry-dropped`),
+数组 > 1024 让 hosts 整域降级(`domain-defaulted`),两处拒句都点名 SS-M2。改写:一次性迁移 SS-M2(= 夹紧臂当年的生效读法)。
+
+- **谁受影响**:调 `grandfatherHostsRead` 的代码;穷举告警种类的 switch;还存着 0.8.0 之前超界 hosts 的中心。
+- **怎么改**:switch 删一臂;起服跑 SS-M2。
+- **不改会怎样**:tsc 红;没迁的超界条目从目录里消失(带告警)、超界数组让整张主机表降级成空。
+
+#### 硬破坏:workers 迁移族拆开 —— 逐行终判单立 `readWorkersRows`,6.x 改写进 SS-M4
+
+删 `migrateWorkersDomain` / `WorkersDomainMigration` / `WorkersMigrationDrop` / `WorkersMigrationRefusal`、命令 `migrate-workers`、随包的 workers 迁移金样目录。
+新 `readWorkersRows(raw) → { doc, held }`(主入口;`HeldWorkerRow` / `WorkersRowsRead`):每一只认得出名字的 worker 单独过读侧判据,读不进的那一行扣下、
+原文随 `held[].original` 交回 —— 这是 workers 域的永久读语义(一只坏 worker 不再拖黑整个舰队)。6.x 行的改写搬进 SS-M4(写回;改写后仍读不进的行不写半成品,
+原样留、收据 `refused`)。`WorkerSpec` 的 6.x 删除项由 schema 里原位的墓碑字段拒(句子点名 SS-M4),不再是 schema 外的预处理 —— `WorkerSpec` 重新是对象 schema。
+
+- **谁受影响**:管理面 workers 读口(import 改名);运维文档里的离线自检命令;读 `WorkerSpec` 管道形的代码。
+- **怎么改**:读口调 `readWorkersRows`,扣下的行标红;起服对 workers 文档跑 SS-M4(`migrateStoredDocuments`);离线自检改用 `migrate <dir> --check`。
+- **不改会怎样**:tsc 红;6.x 行被墓碑拒、被 `readWorkersRows` 扣下而不是被改写。
+
+#### 硬破坏:模型钥匙二选一
+
+`ModelEntry` 同设 `sealedApiKey` 与 `apiKeyEnv` ⇒ 拒(读侧逐条丢 `entry-dropped`,写侧拒;句子点名 SS-M5)。改写:SS-M5 删 `apiKeyEnv`(= 当年的生效读法 sealed 赢)。
+
+- **谁受影响**:切换钥匙写法时不清另一字段的编辑面;按「sealed 优先」写优先级臂的消费方;存着双设条目的中心。
+- **怎么改**:切换写法时清掉另一字段;删优先级臂;起服跑 SS-M5。
+- **不改会怎样**:双设的模型条目从目录里消失(带告警)。
+
+#### 硬破坏:`atModelAllowlist` 退役,换 `atMention` 三态(换表示,不翻义)
+
+`models.atMention`:`{mode:"all"}`(缺省,物化)/ `{mode:"none"}` / `{mode:"only", models}`(至少一个名);`rosters[].atMention` 缺席 = 继承全局。
+「一个都不许」第一次可表达;roster 收窄后一个都不剩 ⇒ `{mode:"none"}`(新导出 `narrowAtMention` —— 一只收窄读法,按 principal 收窄也调它)。
+`atModelAllowlist` 是两处原位的墓碑字段:在场即拒(句子点名 SS-M6)。新导出 `AtMention` / `AT_MENTION_MODES` / `AtMentionMode`。改写:SS-M6(`[]` → all、
+非空 → only、缺席不写;两形并存 ⇒ refused)。
+
+- **谁受影响**:读 `models.atModelAllowlist` / roster 的 `atModelAllowlist` 的代码(@-提及门、编辑面、引用索引);各自写「剔空就保留原单」绕行的消费方;存着旧键的中心。
+- **怎么改**:读 `atMention.mode`;收窄调 `narrowAtMention`;删绕行;起服跑 SS-M6。
+- **不改会怎样**:tsc 红;带旧键的 models 文档整域降级、rosters 整份读不出。
+
+#### 硬破坏:调度店读写口没有静默模式
+
+`parseSchedulerStore(text, { nowMs })` / `loadSchedulerStore(path, { nowMs })` 恒返回 `{ records, warnings }`(`SchedulerStoreRead`);`SchedulerStore.load()` 同形;
+`createFileSchedulerStore(path, { now })`;`mutateSchedulerStore(path, fn, { nowMs, retries? })` 的结果都带 `warnings`,并多一个结局 `unreadable_file`。
+告警闭集:`unreadable-file`(整份文件不是 JSON 数组 —— 不再读成空店;`mutate` 遇它不调 `fn`、不写)/ `malformed-record` / `stale-session-record`
+(会话链上的记录 —— 显式 `lifetime: "session"` ∧ `sessionId` 在场 —— `nextRunMs` 过去 ≥ 7 天,`STALE_SESSION_RECORD_MS`:读时丢,下一个写者落盘;
+`lifetime` 缺席读作 durable,与 SS-M3 同一只读法,durable 记录哪怕带着来源 sessionId 也不丢)/ `one-time-migration`(SS-M3 的收据)。删告警员 `durable-scope-rekeyed`。
+所有写者走 `mutateSchedulerStore` 这一只原语(裸 load → save 是丢更新的竞争)。
+
+- **谁受影响**:引擎的调度后端与壳的常驻 daemon(两个读写点)。
+- **怎么改**:传调用方的时钟;把 `warnings` 接进日志;写者改走 `mutateSchedulerStore`,处置 `unreadable_file`。
+- **不改会怎样**:tsc 红;一份读不懂的调度文件仍会被裸 save 整份覆盖。
+
+#### 硬破坏:`statusRowsToPrune` 的 `now` 必填
+
+本包不读墙钟(确定性律);TTL 臂此前缺 `now` 时悄悄读墙钟。现在缺 `now`(或不是有效 `Date`)⇒ 抛。
+
+- **谁受影响 / 怎么改 / 不改会怎样**:管理面 worker 状态 GC 的调用点(两处)传 `now`;不传 ⇒ tsc 红、运行期抛。
+
+#### 行为变:URL fragment 的存量改写(SS-M7)
+
+URL 座位(由域 schema 派生:`models.models[].baseUrl`、`mcp.servers[].transport.url`、`execution.sessionMirror.engineUrl`、
+`workers.workers[].coords.gitApiBaseUrl`)上的 `#` 及其后由 SS-M7 剥掉(fragment 从不上线)。`NON_SECRET_URL` 拒 fragment 的那一半在同版的「一只 URL 形判官」件里。
+注:`remote-exec.json` 与凭证信封不是域文档,SS-M7 不覆盖它们(手改)。
+
+#### 其余
+
+- 新导出 `outgoingPath(path)`(主入口):带用户键段的坐标出门前的那一道(与读告警同一只脱敏);一次性迁移的收据坐标与 `readWorkersRows` 的
+  `held[].field` 都经它 —— 未知键名、Record 键可能就是粘错位置的凭据,收据与报告从不带原文。
+- 未知键扫描的 runtime 顶层豁免随抬升臂删除(零豁免);读路径上只剩一个坐标压缩点(逐条抢救),坐标回写律不变。
+- zod 大版本的等价钉(`test/zod-major-equivalence.test.ts` 与它的 zod 3 金样)按它自己的寿命条款删除:本节有意改了语料读数(域退役、迁移),
+  不在新树上重录(重录 = 用新版本自证新版本)。符合性语料按新读数加冕:84 条 `expected.json` 与 `baseline.json` 变(`runtime` 格消失、`models.atMention`
+  物化、退役域四腿同拒、hosts 超界走逐条丢 / 整域降级),c06 / c20 两格 🚧 金样翻成四腿 `rejected`。
+
+### 判官:同一个问题只有一只判官(URL 形、秘密扫描、userinfo、出门上界、引用完整性、缺省模型、「本机」、hooks matcher)
+
+律(一条):**同一个问题在本包只有一只判官,写侧、读侧、展示侧都问它;判官的结论是数据(词 / 结构化操作数),句子由同一只渲染函数从数据铸。**
+
+#### 硬破坏:`NON_SECRET_URL` 由 URL 形判官定义,fragment 一律拒(含空 `#`)
+
+新模块(主入口)`HTTP_URL_PARTS` / `HttpUrlPart` / `HttpUrlFlaw` / `HTTP_URL_SHAPE_RULE` / `httpUrlFlaws(raw, forbid)` / `httpUrlRule(flaw)` /
+`isHierarchicalUrl(raw)`:这个值是不是层级式 http(s) URL、座位禁的部件(userinfo / query / fragment)在不在,答案是规则词;`NON_SECRET_URL` =
+禁 userinfo 与 fragment ∧ path / query 无秘密形,一条 flaw 一条 issue(`params.flaw` 带词,句子不回显值),值不改写。插件源的 https 形判改走同一只判官。
+- **谁受影响**:存量 URL 座位(模型目录 `baseUrl`、mcp http `url`、remoteExec 端点、会话镜像引擎地址、git API 基址)带 `#` 的条目;钉了旧拒句
+  `must be an http(s) URL with a host …` 的消费方。
+- **怎么改**:先跑一次性迁移(SS-M7 剥 `#` 及其后);拒句按 `params.flaw` 或 `httpUrlRule(flaw)` 读。
+- **不改会怎样**:带 `#` 的模型条目在读侧被逐条丢(`entry-dropped`)、gate 域整域拒;写侧 400。
+
+#### 硬破坏(行为):一只秘密扫描器 —— 写入校验读展示侧同一组归一化形
+
+`containsSecretToken` 与 `redactSecrets` 读同一组形(百分号层、边界读法、`+` 读作空格;归一化没走完 ⇒ 按秘密处置)与同一张形表;
+形表加一形:`bearer` / `basic` 后接**编码过的空格**(`+` / `%20`)再接任意令牌(`note:Basic+dTpw`、`x-Bearer%20abc123`)。
+- **谁受影响**:存量自由文本值(worker env、mcp 参数、`extraBody` 等)里只在深层编码 / `+` 读法 / 边界读法下才显形的秘密串,以及上面那种短凭据形。
+- **怎么改**:把凭据挪进 env-NAME 位(这些值本来就不许存);真实目录名普查(`o3-mini+high` 等 18 形)三处读数不变。
+- **不改会怎样**:读侧该条被丢(可降级域)或整域拒(gate 域),写侧 400 —— 与 10.0.0「私钥头任意位置」同形。
+
+#### 行为变:自由文本出门面不带 URL 的 userinfo
+
+告警坐标、错误句、身份面上,含 `@` 的 URL 候选段带凭据(`https://u:pw@h`、`jdbc:postgresql://u:pw@h`、`//u:pw@h`、`u:pw@db:5432/app`、只带用户名的
+`ssh://git@h`)⇒ 整段 `[redacted-secret]`;只在百分号编码形上可见的 ⇒ 整串扣。身份谓词问的就是这只脱敏器放不放行(不再单列一条否决)。
+校验判定不变:自由文本写口照旧不因 userinfo 拒。谁受影响:读这些文本的界面会看到记号而不是原 URL。
+
+#### 行为变:出门标识串一条长度上界
+
+`sanitizeZodError` 交出的 issue 里,用户写的标识串(坐标字符串段、未知键 `keys`、句中操作数)与告警坐标段同一道:长过 256 ⇒ 整段 `[redacted-secret]`,
+句子由同一组出门形重铸。整句不受上界约束(迁移指路、墓碑句、上界句逐字出门)。谁受影响:按原串比对超长坏键错误文本的测试。
+
+#### 硬破坏:错误句的操作数结构化
+
+- `RefIssue` 带 `kind`(闭集 `REF_ISSUE_KINDS`:`unknown_model` / `unknown_roster` / `unknown_worker` / `unknown_skill` / `unknown_mcp` / `unknown_plugin`;
+  目标域 `REF_ISSUE_TARGET_DOMAIN`)、`referrer`(`{domain, name?}`,引用者域闭集 `REF_REFERRER_DOMAINS`)、`target`;`code` 收窄为 `"custom"`;`message` 由
+  `renderRefIssue(issue, show?)` 铸,句式统一为 `<引用者> → unknown <noun> "<target>" (at <坐标>)`。
+- 本包 schema 句子里插了值的自定义问题带 `params: QuotedIssueParams`(`template` + `operands`,`message` = `renderQuotedSentence(params)`);
+  定句(迁移指路、词表出路、字段名)在 template 里,operands 只有配置里的值。
+- **谁受影响**:按引用完整性句子文本匹配的消费方(句子改了);日志边界从句子里猜值的那一路。
+- **怎么改**:按 `kind` / `referrer` / `target` 或 `params.operands` 读;要换掉值就把自己的 `show` 传给两只渲染函数。
+- **不改会怎样**:按旧句文本匹配的格不再命中;逐值打指纹的边界仍得猜。
+
+#### 硬破坏:一只引用判官,双向
+
+`danglingRefs(docs)`(新,纯、同步):整套文档里每一条按名的跨域引用,解析不到的逐条成 `RefIssue`。写入席 `refIntegrityIssues(domain, value, resolve)`
+= 它在写后整套文档上的结论里、本域持有的(前向)与指向本域的(反向)那些 —— **删一个仍被引用的名 ⇒ 点名引用者**(坐标指到引用处)。
+`REF_CHECKED_DOMAINS` 多 `skills` / `mcp` / `plugins` 三员(被 tier 引用的目标域)。`resolveEffectiveForWorker` 的结果多 `refIssues`(同一只判官对这台
+worker 与其 roster 的结论;剔法不变,不再静默)。
+- **谁受影响**:管理面写入席与回滚路径(对三个新成员也要跑闸;对目标域的写会因仍被引用而 400);对 `REF_CHECKED_DOMAINS` 穷举分支的消费方(编译红)。
+- **怎么改**:回滚 / 写入照旧问 `isRefCheckedDomain`;拒句点名的引用者先改;读侧把 `refIssues` 记进日志或展示。
+- **不改会怎样**:删一个被 roster / tier 引用的名照旧受理,引用者在读侧静默丢那一条。
+
+#### 新增:被丢条目的身份区分「扣名」与「非串名」
+
+`DroppedEntryIdentity` 加可选 `nameWithheld: true` / `idWithheld: true`:名 / id 是字符串但不能原样出门时带标记(不说为什么),不是字符串时什么都不带。
+符合性语料 c40 / c41 / c43 / c45 / c46 / cli01 / cli02 的 `identity` 只多这两个标记。谁受影响:对 `identity` 做深相等的消费方。
+
+#### 硬破坏:缺省模型只有 `roles.default` 一位;解析口一只
+
+- 新导出 `resolveCatalogDefaultModel(models, has, fallback)` → 判别联合 `CatalogDefaultModel`(`kind` 闭集两词):`roles.default` 是 `{model}` 或缺席 ⇒
+  `{ kind: "named", name, source, dangling }`(`roles.default` 的 `{model}` → 活动档位组 pro / flash / lite → 兜底;点了名却不可用的一级记进 `dangling`);
+  `roles.default` 是 `{select}` 形 ⇒ `{ kind: "select", select }` —— 它不点名模型,挑哪一条是引擎的选择语义,本包不猜、也不跳到档位梯或兜底,`select` 原样交回。
+  另导出 `DEFAULT_ROLE_TIER_LADDER`(钉对引擎对 `default` 角色的档语义)。
+- `models.default` 结构键退役:`ModelsConfig` 上是墓碑字段(写读两面拒,拒句点名 SS-M9);一次性迁移 SS-M9 把它并进 `roles.default` —— 两位都在且不同时
+  并过去的是 `models.default`(迁移前缺省解析的第一级,主任务真跑的那一个),原 `roles.default` 收据记 `dropped-shadowed`。
+- **谁受影响**:存量里写了 `models.default` 的部署;读 `models.default` 的消费方(缺省解析、重启信号);本地模型池写 `default` 键的壳。
+- **怎么改**:先跑一次性迁移;缺省解析改调 `resolveCatalogDefaultModel`,对两词穷举分支:`named` ⇒ `models["default"]` 填 `name`;`select` ⇒ 把 `select`
+  交给引擎按 `default` 角色解(core `resolveTaskModel` 的语义:`selectModel` 挑不中再走引擎自己的档位与回落;给引擎的目录与 `has` 是同一可用集),
+  不在本地落到档位梯或兜底 —— server 的缺省解析与壳的本地池读口都按此到货。
+- **不改会怎样**:没迁移的 `models.default` 让 models 域整域降级为缺省(读侧)、写侧 400。
+
+#### 新增:「本机」两个问题两只谓词;hooks matcher 一只读法
+
+- `isLoopbackAuthHost(host)`(鉴权放宽,窄:字面 `127.0.0.1` / `localhost` / `::1` / `[::1]` 与 socket 形 `::ffff:127.0.0.1`)与 `isLoopbackRouteHost(host)`
+  (连接路由,宽:`localhost` 含尾点、127/8、`0.0.0.0`、`::1` 各写法、`::`、IPv4 映射回环段);纯函数、浏览器安全。会话镜像地址的明文 http 放行改问窄的那一只。
+- `hookMatcherSelects(matcher, name)` → `true` / `false` / `"invalid"`:缺席 / 空 / `*` 选一切;名字字符与 `|` `,` 空格 ⇒ 名字表;其余整体当 JS 正则、**不锚定**。
+  读法与事件无关(事件不是入参;参照实现对 `StopFailure` / `FileChanged` 只认 `|`,那两个事件下带 `,` / 空格的 matcher 在这里读作名字表)。
+  谁受影响:此前把正则形整体锚定的读者改调它后,正则 matcher 会多选中工具(要只选一个名写 `^Name$`)。
+
+#### 未在本版
+
+- 秘密检测表与引擎侧检测表的并集:权威表住在上游的原语包里,该包未发布;本版的一只扫描器不等它,表的并集随原语包到货另一版收。
+
+### 名与契约:一个叫法、一张表、一种读法
+
+#### 硬破坏:叫法归一 web-admin(导出名改名、env 名换值,零别名)
+
+`CenterCredentialEnvelope` / `CenterCredentialFile` / `CenterCredentialDeclaration` / `CENTER_CREDENTIAL_ENVELOPE_KIND` / `parseCenterCredentialFile` /
+`judgeCenterCredentialDeclaration` / `CenterCapabilities` / `REGISTRY_JWKS_PATH` / `RegistryJwk` / `RegistryJwks` 改名为对应的 `WebAdmin*` / `WEB_ADMIN_*`
+(路径值不变);`CENTER_CREDENTIAL_ENV` 并入一张八键表 `WEB_ADMIN_ENV`(`url` / `token` / `tokenFile` / `worker` / `liveUrl` / `webUrl` / `dryRun` /
+`adminToken`),值由 `SEMA_REGISTRY_*` 换成 `SEMA_WEB_ADMIN_*`;源文件 `src/center-credential.ts` → `src/web-admin-credential.ts`;`SAFETY_MERGE_SPEC.org.seam`
+等随包展示串同改。
+- **谁受伤**:import 旧名的(tsc 红);部署里还设着 `SEMA_REGISTRY_*` 的 —— 本版这八个旧名**不进**墓碑表(在跑的引擎还把它们当活旋钮读;引擎换读现名之后
+  的那一版再进表),所以本版不拒启;其中渲染器对老引擎仍写的 `SEMA_REGISTRY_URL` / `_WORKER` / `_TOKEN` 三名是保留名(worker 规格里自写拒,见「保留 env 名」),
+  其余五名照收;给 worker 渲染 env 的一方要按目标引擎版本写名(混版本车队按目标版本渲)。
+
+#### 硬破坏:断言令牌(`wat_`)的两个声明键,与主凭证同一只二选一判官
+
+`WEB_ADMIN_ENV` 加 `assertionToken` / `assertionTokenFile`(值 `SEMA_WEB_ADMIN_ASSERTION_TOKEN` / `SEMA_WEB_ADMIN_ASSERTION_TOKEN_FILE`);凭证闭集
+`WEB_ADMIN_CREDENTIALS` = `access` | `assertion`,每份凭证由表里一对键(值 | 文件)声明;判官改为 `judgeWebAdminCredentialDeclaration(env, credential)`
+(第二参必填、没有缺省),两个都设 ⇒ 拒,拒句与主凭证同一句式只换键名;两对互不读。
+- **谁需要**:web-admin 给 worker 渲染断言令牌的两键;引擎按同一只判官读。**谁受伤**:调判官只传一参的(tsc 红,补 `"access"`;JS 调用方漏传 ⇒ 响亮拒)。
+
+#### 新增:`VerifiedIdentity.iat?`(签发时刻,原样带出)
+
+验签通过的令牌,其 JWT 标准 `iat`(秒)原样进 `VerifiedIdentity.iat`;缺席不铸键;在场而不是非负整数 ⇒ 该令牌 `malformed`;签发时刻晚于「现在 +
+`DEFAULT_CLOCK_SKEW_SEC`」⇒ `expired`(`classifyTimeClaims` 收 `iat`,与 `exp` / `nbf` 同一个容忍常量)。
+- **谁需要**:引擎消费「主体被删」事件后按 `iat` 截断删之前签发的令牌。**谁受伤**:签发方铸了小数 / 串形 `iat` 的令牌(此前不看,现在拒)。
+
+#### 新增:退役 env 名墓碑表搬进本包(`RETIRED_ENVS` / `retiredEnvRefusal(env)` / `buildRetiredEnvWire()`)
+
+三族闭集(renamed / replaced / removed),永久、一跳(`CONFIG_CENTER_*` / `REGISTRY_ADMIN_TOKEN` 直指现名);拒启句只此一处铸(纯函数,读传入的 env)。
+进表的判据:没有任何受支持的引擎还读这个名(故上一代 `SEMA_REGISTRY_*` 本版不在表里)。
+- **谁受伤**:各仓手抄的那几份表与从别人构建产物里正则抽的夹具(改 import);`LEADER_CONFLICT_ROUNDS` 那一行的「为什么没了」改成全英文句(拒启句文本变)。
+
+#### 行为变:保留 env 名 = 渲染器写的名(墓碑名不在其中)
+
+`RESERVED_WORKER_ENV` 里 `ANTHROPIC_BASEURL`(引擎墓碑名)换成现名 `ANTHROPIC_BASE_URL`;渲染器写的 web-admin 连接三键(`WEB_ADMIN_ENV` 的
+`url` / `worker` / `token`)入表(渲染器写、不可配)。规则一条:渲染器写的名字是保留名 —— 改名窗里渲染器对老引擎仍写上一代 `SEMA_REGISTRY_URL` /
+`SEMA_REGISTRY_WORKER` / `SEMA_REGISTRY_TOKEN`,这三名与现名三键同一组、同一句拒;引擎换读现名的那一版它们随之搬去墓碑表(同一提交)。`WorkerSpec` 的 `env` / `secretEnv` 写闸同时问墓碑表 `RETIRED_ENVS`:旧名在场(空串 = 未设)⇒ 拒,
+拒句就是墓碑句 `retiredEnvRefusal`(`ANTHROPIC_BASEURL` 照旧被拒,只是拒句从保留名指路换成墓碑句;`TIDB_*`、`CONFIG_CENTER_*`、`OA_*` 等表里的旧名此前过写闸、
+引擎拒启,现在写侧就拒)。
+- **谁受伤**:worker 规格的 `env` / `secretEnv` 里自己写了这四个现名、上一代渲染三名或任一墓碑旧名的(写侧拒,读侧 `readWorkersRows` 逐行扣下,SS-M4 改写后仍带旧名的行
+  `refused`);此前在本地补保留现名的那份补丁、管理面自己的墓碑名写闸可删(本包写闸已答同一句)。
+
+#### 新增:四只此前在消费方手抄的契约件
+
+`./api/pull-token`(按 scope 绑定令牌的形与铸法:一条规则,令牌族是数据 —— `WORKER_PULL_TOKEN`、`mintScopedToken` / `readScopedTokenBinding` /
+`verifyScopedToken`,纯 JS HMAC-SHA256,与 `node:crypto` 逐字节同)· `PRINCIPAL_MAX_LENGTH`(190,`./api/auth-bridge`)· `./api/feedback`(/bug 报告的
+`FeedbackSubmitRequest` / `FeedbackWire` / `FeedbackListResponse` + 两个上限)· `Sha256Digest` / `SHA256_DIGEST_RE`(本包五处同一条摘要正则收成一只)。
+- **谁受伤**:无(纯增);手抄方到货删手抄。
+
+#### 行为变:已退役的车道值给出路(`RETIRED_LANE_WORDS` / `retiredLaneWordRefusal(word)`)
+
+worker 规格的 `runtime.execution.lane` 与 `config.d/remote-exec.json` 的 `provider` 读到 `remote-docker` ⇒ 拒句带出路(`local-docker` + `DOCKER_HOST`);
+issue 码不变,只有这一句的文本变。
+- **谁受伤**:钉了原 zod 句的文案锚(红一次);在本仓外补出路句的一方可删补丁。
+
+#### 新增(型形变):车道表的「凭什么分租户」一列
+
+`ExecutionLaneRow` 改成判别联合:`tenantSeparation: "supported"` 的行必带 `tenantSeparationBasis`(`isolation` | `principal-binding`),
+`single-user-only` 的行没有这一列(`TENANT_SEPARATION_BASES` / `TenantSeparationBasis` / `LaneTenancy` 新导出)。
+- **谁受伤**:手造车道行的代码(型变);点名车道的一致性规则改读这一列。
+
+#### 硬破坏:fleet 方言收一(展开 / 收缩)—— 引擎信号整只承载在一个键下,判官只读它
+
+`EngineSignal` 在 `/health` 与心跳体上整只承载在 `ENGINE_SIGNAL_KEY`(`"engineSignal"`)下(嵌套:收缩窗内布尔 `draining` 照发,一个键装不下两种形);
+`readEngineSignal(body)` 只读这个键(平铺的同名键不再读);心跳形与 `/health` 形都类型化 `engineSignal`(形坏 ⇒ 缺席,体照收);新判官 `judgeReadiness(signal)` /
+`judgeRoutability(row, nowMs)` → `{ routable }` 或 `{ routable: false, code ∈ NOT_ROUTABLE_CODES, why }`(没有信号的拒句点名「the engine predates engineSignal」),
+`isReadyForTraffic`(入参改成 `EngineSignal | undefined`)/ `isRoutable` / `routableInstances` 是它们的布尔形。一个事实一处:引擎状态只在信号里读,
+行的身份(`instanceId` 等)只在体的顶层 —— 平铺读口 `readRestartSignal` 删(重启 = `readEngineSignal(body)?.restart`),`EngineSignal.instanceId` 删;
+两只形上与信号同名的平铺键(`ready`、布尔 `draining` / `drainingSince`、`restart`、`generation`、`leaseState`、`leaseUntil`)是收缩窗里的方言:形不动、
+标 `@deprecated`、本包零读点,删码登记在 `ONE_TIME_MIGRATIONS` 的 `SS-W1`(窗后的下一个 major)。
+- **谁受伤**:路由读者 —— 没有引擎信号的行 / 体(不发 `engineSignal` 的旧引擎)判 `no-engine-signal`、不可路由:**先把引擎升到发 `engineSignal` 的版本,
+  再换路由读者**(编排器按镜像版本判,不满足就拒切换并响亮报);拿 `isReadyForTraffic` 喂布尔方言体的(tsc 红);读平铺 `EngineSignal` 的(读成 `undefined`);
+  调 `readRestartSignal` 的(tsc 红 —— 改 `readEngineSignal(body)?.restart`;旧引擎的体里没有信号,读出 `undefined`,与它不可路由同向);引擎铸信号时写
+  `instanceId` 的(对象字面量 tsc 红;wire 上照发无害,读侧剥掉 —— 身份读体顶层的 `instanceId`)。
+
+#### 硬破坏:一致性门账本只收债
+
+`KnownDivergence` 删 `kind: "declared"`;每行必带票号形 `ref`(`LEDGER_REF_RULE`)与 `window`(`YYYY-MM-DD`,UTC 日历日);release 模式挂着账本要传钟
+`ConformanceOptions.nowMs`(库码不读环境时钟),过窗即违例。
+- **谁受伤**:账本行写成散文 ref、没有窗、或用 `declared` 的消费方适配器(tsc 红 / release 违例);release 调用点补 `nowMs`。
+
+#### 行为变:一致性门先判秘密泄漏、再判结局
+
+一条腿交回的告警或拒绝诊断句带语料秘密 ⇒ `diff`(不论结局形是否一致、账本是否盖得住)。
+- **谁受伤**:诊断句里原样回显了语料秘密的适配器(此前在结局分歧格里漏判)。
+
+#### 硬破坏:严写腿 = 写入席的两道
+
+`ContractModule` 的 `parseDomain` 换成 `parseDomainLoud` + `danglingRefs`(那一只引用判官,整份文档集判一次);严写腿的告警面不再恒空(剥掉 / 承运的未知键点名),
+悬空跨域引用 ⇒ `rejected{validate, code: "ref-integrity"}` 带坐标 `refIssues`(`REF_INTEGRITY_REJECT_CODE` / `RefIssueCoordinate`),金样同存同比。
+语料:13 条严写金样加告警,新增一条悬空引用 case。
+- **谁受伤**:自己实现严写腿的适配器要交告警与引用问题(否则在那 13 + 1 条上分歧);historical 模式的脚本换接线。
+
+#### 新增:prompts 包身份的形一处定义(`PromptPackId` / `PROMPT_PACK_ID_PREFIX`)
+
+`EffectivePrompts.packId` 与内容摘要的铸点引同一只;前缀的值不变。
+- **谁受伤**:无;另写了一份 packId 正则的读方改用本包 schema。
+
+#### 硬破坏:一份 bundle 只装可搬的域
+
+`exportBundle` / `readBundle` 的 `domains` 收窄成 `PortableDomain[]`,`ConfigBundle` 的键同收,`writeBundle` 运行期也拒非便携键。
+- **谁受伤**:给 bundle 函数传 workers / hosts / systems / projects / entitlement 的(tsc 红 / 运行期拒);不传 `domains` 的调用方零改动。
+
+#### 行为变:`readBundle`、`FileConfigStore` 与命令行 `migrate` 读 `config.d/` 文件是同一只读法
+
+只有文件不存在 = 缺席;在场的文件是空 / 纯空白(半写、截断)、坏 JSON、或解析出来不是 JSON 对象(`null` / 数组 / 数 / 串 / 布尔)⇒ `readBundle` 抛、
+`migrate` 退出 2,句子与 `FileConfigStore` 逐字同(此前 `readBundle` 把空文件读成缺席、把 `null` / 数组原样放进 bundle;`migrate` 对空文件报另一句、
+对数组形的域文件报 noop rc 0;同一个目录三个读者三个答案)。非域名拼路径的拒句也只剩一句(`readBundle` 与 `FileConfigStore.domainPath` 同句)。
+- **谁需要**:从本地 bundle 导入的一方 —— 一个被截断的 `governance.json` 不再被读成「没设」而静默丢掉护栏。
+- **谁受伤**:`config.d/` 里留着空文件或非对象文件的 bundle,导入从「省略那一域」变成响亮拒。**补偿**:删掉那个文件(= 缺席),或写成合法对象。
+
+#### 硬破坏:访问令牌缺 scope 声明 ⇒ 拒(`tokenScopeOf` → `readTokenScope`)
+
+`readTokenScope(claims)` → `{ scope }` | `{ refused: "scope_claim_missing" }`(`TOKEN_SCOPE_REFUSALS` 闭集):缺 / 空 / 非串的 `scope` 声明不再读成
+`"global"`。旧名零别名。
+- **谁受伤**:调 `tokenScopeOf` 的(tsc 红;拒映射 401);仍持有 scope 上线前所铸访问令牌的会话 —— 访问令牌最长活 3600 s,刷新即重铸带声明的那一枚,
+  前提是所有在跑的 web-admin 都已是签发点全带 `scope` 的版本、并过了一个令牌寿命。
+
+#### 注释改真(零行为)
+
+`EffectivePromptsWire`(引擎只认双轴形,平铺体响亮拒)· `./api/auth` 头注(这一面保留、没有删的窗,写明三方消费方)· `readEffectiveWire`(引擎早已不读
+`teams`)· `WorkerSpec.placement`(`placement.auto` 判 `host` 是钉还是提示)· 本包注释与文档里指那个产品的 center / registry / 中心 一律写 web-admin。
+
+### 新增(additive)
+
+- `ModelTier`(`cheap` / `standard` / `premium`,schema + 型):`ModelEntry.tier` 与 `RoleTarget.select.tier` 引用同一只(此前两处各写一遍)。
+- `PromptSlot`(`identity` / `scenario` / `behavior`,schema + 型):`PromptTextDeclaration.slot` 与 `PromptArtifactSection.slot` 引用同一只。
+
+### 开发期(不进发布物)
+
+- devDependency `@sema-agent/core` 由 7.33.1 抬到 7.47.0(与 server 钉的同一只);上游漂移门 ② ③ ④ 与 safety-merge-spec 对拍对新版本跑过,红的那一处见上一节。
+- hook 事件锚定快照(`test/fixtures/cc-hook-events.json`)按 CC 2.1.291 的解码语料机器重抽:事件集与次序与 2.1.259 相同,只有版本标记变。
+- 上游漂移门加两组:⑤ `PROMPT_ARTIFACT_LIMITS` 逐键 === 引擎 `ARTIFACT_LIMITS`;⑥ `MCP_CONTENT_ORIGINS` 与引擎 `ToolContentOrigin` 编译期双向同 ——
+  两张镜像表的对拍从消费方搬回镜像的属主。
+- **排空动作号是标识符,不是自由文本**(`DRAIN_ACTION_ID`,一只常量两席:排空请求体 `actionId` 与 `EngineDraining.actionId`):引擎把它原样发到无鉴权的 `/health`(`engineSignal.draining.actionId`),所以 1–128 字符、首字母数字、其余字母数字 / `.` / `_` / `:` / `-`;带空格 / 任意文本的动作号写入即拒。**谁受伤**:用自由文本当排空动作号的编排脚本(升级即 400);**补偿**:改成 id 形(时间戳 / 序号都合法)。
+
+## 10.1.1 — 2026-10-10 — 发布修正:随包的 `conformance/VERSION` 与 llms 版本行抬到本版(patch;零代码变化)
+
+> 10.1.0 的发布提交只抬了 `package.json` / 锁 / CHANGELOG,漏抬随包出的 `conformance/VERSION`(仍 10.0.0)与 `llms.txt` / `llms-full.txt` 的「包版本」行;
+> tag 树的三只版本钉红(4 文件 11 格)。本版只补这三处(`conformance:bless` 写 VERSION),源码零变化,导出面零变化。消费方按 10.1.0 节读。
+
 ## 10.1.0 — 2026-10-10 — 被丢条目带机读原因 `reasonCode`(minor,additive:新导出 + 可选新键,零删零改名)
 
 > 本节一件,additive(新导出 + 新字段),零删零改名。判档口径见下方「发版纪律」:新键 / 新导出 = minor。