@sema-agent/settings-schema 8.3.0 → 8.3.1

package/CHANGELOG.md

@@ -6,6 +6,53 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 8.3.1 — 2026-10-08 — FLEET_SCOPE_ENV 注改真(patch)
+
+> **判档 = patch**(README「发版纪律」:文案 / 注释 = patch)。只改 `src/fleet.ts` 里 `FLEET_SCOPE_ENV` 的头注(它随 `.d.ts` 发出);常量值不变,导出面登记表零 diff,零运行期行为,
+> 零 wire 形。**8.3.0 已发的那一节一字未动**(按包规则,对已发节的更正写进当前节)—— 它里面作废的说法在下面逐句点名。
+
+### 一、病:8.3.0 的头注把续租体与心跳说成引擎用这只 env 填的东西
+
+8.3.0 的头注(与同节第一节)写「引擎读它作自身身份的 scope:比对 `DrainRequest.scope`、作 `ServingLeaseRequest.scope` 发出、在心跳上点名(`?scope=`)」。
+后两处与引擎的实现相反:引擎读这只 env **只**用来比对 `DrainRequest.scope`(请求不带 scope ⇒ 读成默认 scope,与引擎自己缺席时读的是同一只缺省);
+**续租体与心跳都不另送 scope** —— 那两处的 scope 由凭证绑定决定。这条规则本包一直写在 `ServingLeaseRequest` 注(续租只收 per-worker 令牌,缺席 = 令牌的 scope,在场必须相等)与
+`InstanceAnnouncement` 注(心跳体没有 `scope` 键,行落在凭证点名的 scope)上,8.3.0 的 `FLEET_SCOPE_ENV` 头注与它们自相矛盾。
+
+### 二、8.3.0 一节里作废的三句(同一个说法)
+
+1. 第一节「引擎读它作**自身身份的 scope**:排空口里拿 `DrainRequest.scope` 比对的那一格、续租体 `ServingLeaseRequest.scope`、心跳的 `?scope=`」—— 后两项作废,只剩第一项。
+2. 用户可见变化第 2 条的括注「(续租体「在场必须相等」的规则下会被拒)」—— 作废;没渲 `FLEET_SCOPE` 的后果见下面第四节。
+3. 未闭环第二条「不一致时按各口既有的规则表现为拒(续租体 scope 在场必须与令牌绑定的相等)/ 比对不上」里的「续租体 … 拒」—— 作废,只剩「比对不上」。
+
+### 三、现读法(一个事实一个源)
+
+- **续租 / 心跳的 scope = 凭证**:续租只收 per-worker 令牌,`ServingLeaseRequest.scope` 缺席 = 令牌绑定的 scope、在场必须相等(令牌与体字段之间的规则,不涉 `FLEET_SCOPE`,未变);
+  心跳体没有 `scope` 键,行落在凭证点名的 scope。引擎不用 `FLEET_SCOPE` 填这两处。
+- **引擎自身身份的 scope = 渲染器给的 `FLEET_SCOPE`**(缺席 = `GLOBAL_SCOPE`;不从令牌格式反推),唯一用途 = 比对 `DrainRequest.scope`(请求不带 scope ⇒ 读成默认 scope)。
+- **两者同值是渲染器的义务**:本包不判、也判不了(令牌不在本包)。
+
+头注改成这一读法;文本钉见第五节。README 的 8.3.0 条目与 llms 事实版没有复述作废的那句;`llms-full.txt` 的 `FLEET_SCOPE_ENV` 事实句补写了「只用来比对 `DrainRequest.scope`、续租 / 心跳的 scope 由凭证定」。
+
+### 四、用户可见变化(谁受影响 / 怎么改 / 不改会怎样)
+
+1. **只用 schema / 读写 helper、不碰 fleet 的消费方**:零变化(注释改动,导出面零 diff)。
+2. **配置渲染器(管理面)**:渲 `FLEET_SCOPE` 的义务不变,值 = 该成员 per-worker 令牌绑定的 scope。现读法下它**只**影响引擎对排空请求 scope 的比对:
+   不渲 ⇒ 引擎身份按 `GLOBAL_SCOPE`,非 `global` 租户的排空请求(带该租户 scope)与它比对不上;**续租与心跳不受影响**(它们的 scope 来自凭证,不来自这只 env)。
+3. **引擎(server)**:不要把 `FLEET_SCOPE` 填进续租体或心跳;引擎现有的读法(只比对 `DrainRequest.scope`)不变,本版只是把本包的注改成与它一致。
+
+### 五、红先 / 门
+
+- 先写钉、对着改前的注跑红,再改注:`test/fleet-scope-env-8.3.1.test.ts` 五格(常量不动 / 头注不再说「sends as」「names on its heartbeat」「?scope=」,且凡提到续租 / 心跳的句子同句带「credential」/
+  头注把用途钉在比对 `DrainRequest.scope` 并写明请求不带 scope 读成默认 scope / 头注一句话说清「续租 / 心跳的 scope = 凭证;引擎自身身份的 scope = 渲染器给的 `FLEET_SCOPE`;同值是渲染器的义务」/
+  8.3.0 既有三件仍在)⇒ 3 红 2 绿(2 绿是反向格:常量值不动、既有三件不丢);改注后全绿;`test/fleet-scope-env-8.3.0.test.ts` 不动、仍绿。
+- 变异自证(每个都使预期那一格红):头注改回「sends as … ServingLeaseRequest.scope」/ 头注删「the credential's」句 / 头注删「renderer's obligation」句 / 头注删「carries no scope reads as the default scope」/ 头注写回 `?scope=`。
+- 全量读数见发版链(本节不复述一份会过期的数)。
+
+### 未闭环(如实)
+
+- **现读法里引擎侧的事实**(只比对 `DrainRequest.scope`、请求不带 scope 读缺省、续租体与心跳不另送 scope)出自引擎实现;本包没有取引擎源码的通道,没有机器门看「引擎改了读法而本注没跟」。
+- **8.3.0 已发节里作废的三句仍留在那一节**(已发节字节不动):读者以本节为准。
+
 ## 8.3.0 — 2026-10-08 — fleet 成员所属租户 scope 的 env 名常量 `FLEET_SCOPE_ENV`(additive)
 
 > **判档 = minor**(README「发版纪律」:新键 / 新导出 = minor)。新导出 1 名(`FLEET_SCOPE_ENV`,`.` 与 `./fleet` 各 +1)与一个新保留 env 名;

package/README.md

@@ -48,6 +48,10 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 > 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.
 
+## 升级指引:8.3.0 → 8.3.1(注释改真,零动作可升)
+
+`FLEET_SCOPE_ENV` 的头注改真:引擎读这只 env 只用来比对 `DrainRequest.scope`;续租体与心跳的 scope 由凭证定、不取这只 env。导出面与行为零变化,逐条见 CHANGELOG 8.3.1。
+
 ## 升级指引:8.2.0 → 8.3.0(additive,零动作可升)
 
 `./fleet`(与主入口)多一个 env 名常量 `FLEET_SCOPE_ENV = "FLEET_SCOPE"`:成员所属租户 scope,渲染器写、引擎读(缺席 = `GLOBAL_SCOPE`),同时进 `RESERVED_WORKER_ENV`(`worker.env` / `secretEnv` 设它被拒)。逐条见 CHANGELOG 8.3.0。

package/conformance/VERSION

@@ -1 +1 @@
-8.3.0
+8.3.1

package/dist/fleet.d.ts

@@ -715,13 +715,15 @@ export declare const FLEET_GENERATION_ENV = "FLEET_GENERATION";
 /**
  * The env name a fleet member's tenant scope travels under — the config renderer sets it to the scope this member's per-worker
  * token binds (the same value, taken from the same place the token is issued for), and the engine reads it as the scope of its
- * OWN identity: the scope it compares a {@link DrainRequest}'s `scope` against, sends as {@link ServingLeaseRequest}`.scope`, and
- * names on its heartbeat ({@link InstanceAnnouncement}'s `?scope=`). Both sides import THIS constant; neither spells the name.
- * One fact, one source: the scope is GIVEN by the renderer — the engine never derives it from the token's format (a token is
- * opaque to it, and a format guess would be a second source that can disagree with the scope the center binds). Absent from
- * the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) — the same default the center reads where nothing
- * names a scope; this note does not restate the value. Like {@link FLEET_GENERATION_ENV} it is a reserved worker env name
- * (`WorkerSpec.env` / `secretEnv` cannot set it).
+ * OWN identity, for one use: the scope it compares a {@link DrainRequest}'s `scope` against (a request that carries no scope
+ * reads as the default scope — the same default the engine's own absence reads as). Both sides import THIS constant; neither
+ * spells the name. One fact, one source: a lease's and the heartbeat's scope is the credential's (the credential decides it, see
+ * {@link ServingLeaseRequest} and {@link InstanceAnnouncement}; nothing in the engine's env does); the engine's own identity
+ * scope is the one the renderer gave in this env; that the two are the same value is the renderer's obligation.
+ * The engine never derives it from the token's format (a token is opaque to it, and a format guess would be a second source
+ * that can disagree with the scope the center binds). Absent from the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) —
+ * the same default the center reads where nothing names a scope; this note does not restate the value. Like
+ * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export declare const FLEET_SCOPE_ENV = "FLEET_SCOPE";
 /**

package/dist/fleet.js

@@ -477,13 +477,15 @@ export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
 /**
  * The env name a fleet member's tenant scope travels under — the config renderer sets it to the scope this member's per-worker
  * token binds (the same value, taken from the same place the token is issued for), and the engine reads it as the scope of its
- * OWN identity: the scope it compares a {@link DrainRequest}'s `scope` against, sends as {@link ServingLeaseRequest}`.scope`, and
- * names on its heartbeat ({@link InstanceAnnouncement}'s `?scope=`). Both sides import THIS constant; neither spells the name.
- * One fact, one source: the scope is GIVEN by the renderer — the engine never derives it from the token's format (a token is
- * opaque to it, and a format guess would be a second source that can disagree with the scope the center binds). Absent from
- * the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) — the same default the center reads where nothing
- * names a scope; this note does not restate the value. Like {@link FLEET_GENERATION_ENV} it is a reserved worker env name
- * (`WorkerSpec.env` / `secretEnv` cannot set it).
+ * OWN identity, for one use: the scope it compares a {@link DrainRequest}'s `scope` against (a request that carries no scope
+ * reads as the default scope — the same default the engine's own absence reads as). Both sides import THIS constant; neither
+ * spells the name. One fact, one source: a lease's and the heartbeat's scope is the credential's (the credential decides it, see
+ * {@link ServingLeaseRequest} and {@link InstanceAnnouncement}; nothing in the engine's env does); the engine's own identity
+ * scope is the one the renderer gave in this env; that the two are the same value is the renderer's obligation.
+ * The engine never derives it from the token's format (a token is opaque to it, and a format guess would be a second source
+ * that can disagree with the scope the center binds). Absent from the engine's env ⇒ the default scope, {@link GLOBAL_SCOPE} (`api/scopes`) —
+ * the same default the center reads where nothing names a scope; this note does not restate the value. Like
+ * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "8.3.0",
+  "version": "8.3.1",
   "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",