@sema-agent/settings-schema 17.0.0 → 17.1.0

package/CHANGELOG.md

@@ -8,6 +8,61 @@
 
 ## Unreleased
 
+## 17.1.0 — 2026-11-02 — minor:车道表 device 行的可选栏登记 `DEVICE_TRUSTED_PROXY_CIDRS`(引擎读它作设备 WS 未鉴权握手 per-remote 帽键的可信代理名单)
+
+> 档位(按发版纪律):**minor** —— 车道表一行加一个 env 名(加性):写闸自此受理 `runtime.execution.coords.DEVICE_TRUSTED_PROXY_CIDRS`(此前判「不是任何车道的坐标」)。导出面零变化(没有导出增删,签名不变)。
+> 随表成为保留名的那一面:`env` / `secretEnv` 逃生口不再收这个名字(指路 coords)—— 本版之前没有任何已发引擎读过它(读它的引擎版本提货本版),逃生口里写着它的规格从没生效过,没有可搬的旧形,所以不进晚登记键表、不配迁移;
+> 若你的存量 worker 规格在 `env` 里写过它,把它搬到 `runtime.execution.coords`(只对声明 device 车道的 worker 有意义)。
+
+- **`EXECUTION_LANES` device 行 `optionalEnv` 加 `DEVICE_TRUSTED_PROXY_CIDRS`(在 `DEVICE_SUPERSEDE` 之前,与引擎 device 臂的读序同)**。律不变:引擎的 device 臂读哪些 env,车道表 device 行就登记哪些 —— 不登记就是「引擎读、表漏登记」(16.0.0 的 `DEVICE_RELAY_URL` 是同一病形)。
+  它是非密可选坐标:声明 device 的 worker 写 `coords.DEVICE_TRUSTED_PROXY_CIDRS` 受理;没声明 device 的 worker 写它 ⇒ 「属于 device 车道」那一句;写进 `secretRefs` ⇒ 「非密坐标,写 coords」那一句;`env` / `secretEnv` 写它 ⇒ 保留名那一句(指路唯一写位)。
+  值(CIDR 逗号分隔;缺省空 = 引擎不读任何代理头)的文法由引擎起服判(坏项拒启),写闸对可选坐标只判归属 —— 与本行其余可选坐标同。晚登记键表 `LATE_LANE_ENV_KEYS` 的头注改写成它真实的登记条件(登记之前引擎已在读的键),内容不变。
+  三问 —— **谁需要**:由车道表派生转发清单 / 旋钮表的消费方(部署的 compose 透传、控制台的 device 旋钮表、服务端的车道表对账):随表带上这根键,不再手补;
+  **谁受伤**:在 `env` / `secretEnv` 逃生口里写过这个名字的 worker 规格(本版之前没有引擎读它,写着也从没生效)读出来被拒;**补偿**:拒句点名唯一写位 `runtime.execution.coords.DEVICE_TRUSTED_PROXY_CIDRS`,搬过去即可。
+  钉:`test/device-trusted-proxy-17.1.0.test.ts`(行内容与位置 · 归属索引 · 写闸四形:device 受理 / 别的车道拒 / secretRefs 拒 / 逃生口拒且不在晚登记键表)、`test/device-relay-16.0.0.test.ts` 与 `test/execution-lanes-7.0.0.test.ts` 的整表钉随表改、`test/migration-signpost-11.0.0.test.ts` 的保留名增词账加这一名。
+
+**自 v17.0.0 起运行期代码有改动的公开导出(机器重算;上界 —— 可达 ≠ 一定变,不可达 ⇒ 一定不变;本版新增的导出不入表)**
+
+```text
+DOMAINS [., ./types]
+DOMAIN_SCHEMAS [., ./types]
+EXECUTION_LANES [., ./execution-lanes]
+FileConfigStore [./node]
+NON_PORTABLE_DOMAINS [./conformance]
+RESERVED_WORKER_ENV [., ./types]
+WorkerSpec [., ./types]
+WorkersConfig [., ./types]
+buildEffective [., ./config-fns]
+deriveLocalExpectation [./conformance]
+deriveWireExpectation [./conformance]
+domainFilePath [./node]
+emptyEffective [., ./config-fns]
+foreignKeysOf [./conformance]
+isDomainName [., ./types]
+loadLocalConfig [./node]
+loadRemoteExec [./node]
+migrateConfigDirectory [./node]
+migrateConfigDocuments [./node]
+migrateEffectiveSnapshot [./one-time-migrations]
+migrateEnvModelsDecision [./node]
+migrateStoredDocuments [./one-time-migrations]
+parseDomain [., ./config-fns]
+parseDomainLoud [., ./config-fns]
+parseDomainSalvaged [., ./config-fns]
+planEnvModelTableWrite [.]
+readBundle [./node]
+readEffectiveWire [., ./config-fns]
+readWorkersRows [.]
+remoteExecPath [./node]
+resolveLegExpectation [./conformance]
+runConformance [./conformance]
+urlSeatPatterns [./one-time-migrations]
+validateDomain [./node]
+writeBundle [./node]
+writeDomainFile [./node]
+writeRemoteExec [./node]
+```
+
 ## 17.0.0 — 2026-11-01 — major:`config.d` 文档与 `.env` 的缺席律只有一种 —— 悬空的符号链接是「在场却读不出」,读它拒,不再读成缺席
 
 > 档位(按发版纪律):**major** —— 一处行为硬破坏(B1,三问在下):此前被静默受理的输入(悬空的符号链接)改拒,能让按上一版运行的部署在**运行期**变红;先例 16.0.0 的纯空白字段改拒(「校验收紧」)。

package/README.md

@@ -47,6 +47,12 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 > 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).
 
+## 升级指引:17.0.x → 17.1.0(加性,零动作可升)
+
+车道表 `EXECUTION_LANES` 的 device 行在可选栏多一个非密坐标 `DEVICE_TRUSTED_PROXY_CIDRS`(在 `DEVICE_SUPERSEDE` 之前):引擎读它作设备 WS 未鉴权握手 per-remote 帽键的可信代理名单(CIDR 逗号分隔,缺省空 = 不读任何代理头)。
+写 device worker 的 `runtime.execution.coords.DEVICE_TRUSTED_PROXY_CIDRS` 自此受理(此前判「不是任何车道的坐标」);值文法(CIDR 项、主机位、前缀 0)由引擎起服判,写闸只判归属。它也随车道表成为保留名:`env` / `secretEnv` 逃生口不收它(指路 coords)。
+由车道表派生转发清单 / 旋钮表的消费方(部署的 compose 透传、控制台的 device 旋钮表)随表带上它。导出面零变化。逐条见 CHANGELOG 17.1.0。
+
 ## 升级指引:16.0.x → 17.0.0(BREAKING:`config.d` 文档与 `.env` 的悬空符号链接读不出 ⇒ 拒,不再读成缺席)
 
 - **改了什么**(三问见 CHANGELOG 17.0.0 B1):缺席 = 路径上没有任何条目。`config.d/<名>.json`(含 `remote-exec.json`)、`config.d` 目录本身或 `.env` 是**悬空的符号链接**(链接在、目标不在)时,

package/conformance/VERSION

@@ -1 +1 @@
-17.0.0
+17.1.0

package/dist/execution-lane-index.d.ts

@@ -39,8 +39,8 @@ export interface EnvKeyMigration {
     readonly migration: OneTimeMigrationId;
     readonly before: string;
 }
-/** 7.0.0 之后才登记进车道表的车道 env 名 → 改写它的迁移(只增不减;每加一个,在这里写一行)。16.0.0:`DEVICE_RELAY_URL`(device 行的必需坐标;
- *  此前 device 臂就读它而表漏登记,7.0.0–15.x 的写闸把它当普通 env 收下)→ SS-M12。 */
+/** 7.0.0 之后才登记进车道表、而登记之前引擎就已在读的车道 env 名 → 改写它的迁移(只增不减;每有一个,在这里写一行)。16.0.0:`DEVICE_RELAY_URL`(device 行的必需坐标;
+ *  此前 device 臂就读它而表漏登记,7.0.0–15.x 的写闸把它当普通 env 收下)→ SS-M12。登记之前没有任何已发引擎读过的新键(17.1.0 `DEVICE_TRUSTED_PROXY_CIDRS`)没有存量旧形可搬,不进本表。 */
 export declare const LATE_LANE_ENV_KEYS: ReadonlyMap<string, EnvKeyMigration>;
 /** 一个 env 名在逃生口里 ⇒ 哪一条迁移搬它(见文件头「迁移指路」):晚登记的车道键 ⇒ 登记它那一版的迁移;别的车道块键与店键 ⇒ SS-M4;其余 ⇒ `undefined`(没有迁移搬它)。
  *  写闸拒因带不带指路、指哪一条只看它。 */

package/dist/execution-lane-index.js

@@ -40,8 +40,8 @@ export function isLaneEnvKey(name) {
     return LANE_WORD_KEYS.some((k) => k === name) || LANE_ENV_OWNER.has(name);
 }
 const SIX_X_ENV = Object.freeze({ migration: "SS-M4", before: "7.0.0" });
-/** 7.0.0 之后才登记进车道表的车道 env 名 → 改写它的迁移(只增不减;每加一个,在这里写一行)。16.0.0:`DEVICE_RELAY_URL`(device 行的必需坐标;
- *  此前 device 臂就读它而表漏登记,7.0.0–15.x 的写闸把它当普通 env 收下)→ SS-M12。 */
+/** 7.0.0 之后才登记进车道表、而登记之前引擎就已在读的车道 env 名 → 改写它的迁移(只增不减;每有一个,在这里写一行)。16.0.0:`DEVICE_RELAY_URL`(device 行的必需坐标;
+ *  此前 device 臂就读它而表漏登记,7.0.0–15.x 的写闸把它当普通 env 收下)→ SS-M12。登记之前没有任何已发引擎读过的新键(17.1.0 `DEVICE_TRUSTED_PROXY_CIDRS`)没有存量旧形可搬,不进本表。 */
 export const LATE_LANE_ENV_KEYS = lateLaneEnvKeys([["DEVICE_RELAY_URL", Object.freeze({ migration: "SS-M12", before: "16.0.0" })]]);
 /** 建 {@link LATE_LANE_ENV_KEYS}:每一行的名字必须在车道表里(载入时验,名字拼错 ⇒ 包载入即抛,不静默成一条永不命中的行)。 */
 function lateLaneEnvKeys(rows) {

package/dist/execution-lanes.js

@@ -141,7 +141,8 @@ const LANE_ROWS = {
     },
     /** server `config.ts` :4055 臂 + `parseDevicePreAuthPerRemoteEnv` :871 / `parseDeviceEnrollTokenTtlEnv` :857;`execution-lane-caps.ts` :327
      *  `supported`(发起者自己的设备)。16.0.0:`DEVICE_RELAY_URL`(设备拨哪里)是**必需**坐标 —— 引擎的 device 臂缺它即拒启
-     *  (`parseDeviceRelayUrlEnv`;此前它是 device 臂读而本表漏登记的键),值只有两种:ws(s) 绝对 URL 或字面 `none`(值的文法见 `./device-relay`)。 */
+     *  (`parseDeviceRelayUrlEnv`;此前它是 device 臂读而本表漏登记的键),值只有两种:ws(s) 绝对 URL 或字面 `none`(值的文法见 `./device-relay`)。
+     *  17.1.0:`DEVICE_TRUSTED_PROXY_CIDRS`(可选)= 设备 WS 未鉴权握手 per-remote 帽键的可信代理名单(CIDR 闭集,缺省空 = 不读任何代理头);值文法由引擎起服判。 */
     device: {
         tenantSeparation: "supported",
         tenantSeparationBasis: "principal-binding",
@@ -155,6 +156,7 @@ const LANE_ROWS = {
             "DEVICE_MAX_INFLIGHT_PER_DEVICE",
             "DEVICE_MAX_PREAUTH_PER_REMOTE",
             "DEVICE_ENROLL_TOKEN_TTL_SEC",
+            "DEVICE_TRUSTED_PROXY_CIDRS",
             "DEVICE_SUPERSEDE",
         ],
         optionalSecretEnv: [],

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-11-01 | 包版本: 17.0.0
+重写日期: 2026-11-02 | 包版本: 17.1.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -266,7 +266,7 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
 - `EXECUTION_LANES: readonly ExecutionLaneRow[]`:每行 `{ lane, tenantSeparation: "supported"|"single-user-only", singleReplica, requiredEnv,
   requiredSecretEnv, optionalEnv, optionalSecretEnv }`(深冻结;四栏 env 名两两不交、跨车道不交;行内容逐格抄自引擎,
   坐标在每行 JSDoc)。`TENANT_SEPARATION_WORDS`。`singleReplica`(16.0.0):执行目标挂在一个副本上(host:副本自己的文件系统;device:设备连上的那一个副本)——
-  声明了这种车道的 worker 只能一个副本。device 行的非密必需栏 = `DEVICE_RELAY_URL`(16.0.0;设备拨哪里:ws(s) 绝对 URL 或字面 `none`,值判官 `deviceRelayFlaws`,包根)。
+  声明了这种车道的 worker 只能一个副本。device 行的非密必需栏 = `DEVICE_RELAY_URL`(16.0.0;设备拨哪里:ws(s) 绝对 URL 或字面 `none`,值判官 `deviceRelayFlaws`,包根);非密可选栏含 `DEVICE_TRUSTED_PROXY_CIDRS`(17.1.0;设备 WS 未鉴权握手 per-remote 帽键的可信代理名单,CIDR 逗号分隔,缺省空 = 引擎不读任何代理头;值文法由引擎起服判,写闸只判归属)。
   k8s 行的非密必需栏 = `K8S_SANDBOX_IMAGE` + `K8S_NAMESPACE`(沙箱 pod 所在的命名空间,部署自己声明;服务端的必需 env 门按本行 `requiredEnv ∪ requiredSecretEnv` 拒启)——
   写 worker 的 k8s 行时 `runtime.execution.coords` 两键都要给,缺一键 ⇒ 写闸 issue、存下来的 workers 文档整域读不出。
 - `isBlankCoordinate(value: string): boolean`(包根 15.1.0;`./execution-lanes` 子路径 15.2.0,与包根是同一个函数对象 —— 函数体住在零依赖的叶模块,全包一处定义):必需坐标的值算不算「缺」的**唯一判官** —— 空串或只含空白(`String.prototype.trim` 认的空白)⇒ `true`,带任何非空白字符 ⇒ `false`;

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-11-01 | 包版本: 17.0.0
+重写日期: 2026-11-02 | 包版本: 17.1.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、
@@ -87,7 +87,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
 - `remoteExec` 执行层契约:6 个 provider(host / local-docker / e2b / k8s / ssh / adb),判别字段 `provider`;
   每个 provider 词 ⊆ 车道词表(7.0.0 删 `remote-docker`:引擎零读点)。(src/remote-exec.ts: `RemoteExecSpec`)
 - **执行车道 + 存储的词表正本**(7.0.0,纯数据):`EXECUTION_LANE_WORDS`(host / e2b / k8s / ssh / adb / local-docker / device)、
-  `EXECUTION_LANES`(每车道 `tenantSeparation`〔supported 行另带依据 `tenantSeparationBasis`:isolation / principal-binding,11.0.0 判别联合〕+ `singleReplica`〔16.0.0〕+ 它读的 env 名四栏;device 行必需 `DEVICE_RELAY_URL`〔16.0.0,值判官 `deviceRelayFlaws`〕)、退役车道值墓碑 `RETIRED_LANE_WORDS` + 拒句 `retiredLaneWordRefusal(word)`(11.0.0)、`STORE_BACKENDS` / `SESSION_BACKENDS` / `MEMORY_ENGINE_BACKENDS`(file / pg / mysql)。
+  `EXECUTION_LANES`(每车道 `tenantSeparation`〔supported 行另带依据 `tenantSeparationBasis`:isolation / principal-binding,11.0.0 判别联合〕+ `singleReplica`〔16.0.0〕+ 它读的 env 名四栏;device 行必需 `DEVICE_RELAY_URL`〔16.0.0,值判官 `deviceRelayFlaws`〕、可选栏含 `DEVICE_TRUSTED_PROXY_CIDRS`〔17.1.0,设备握手帽键的可信代理名单,值文法由引擎判〕)、退役车道值墓碑 `RETIRED_LANE_WORDS` + 拒句 `retiredLaneWordRefusal(word)`(11.0.0)、`STORE_BACKENDS` / `SESSION_BACKENDS` / `MEMORY_ENGINE_BACKENDS`(file / pg / mysql)。
   worker 声明有序车道集 `runtime.execution.lanes`(16.0.0,首项缺省;旧单值 `lane` 是墓碑)。
   必需坐标的值算不算「缺」的唯一判官 `isBlankCoordinate(value)`(包根与 `./execution-lanes` 子路径同一个函数对象〔包根 15.1.0、子路径 15.2.0〕:空串或只含空白 ⇒ true;写闸读的同一只,消费方在自己一侧问同一个问题调它;「键没设」由调用方先判,据它拒不拒由调用方按键的必需 / 可选决定〔写闸只对必需坐标据它拒〕;src/execution-lanes.ts)。
   WorkerSpec 的 `runtime.execution` / `runtime.store` 两块按这张表判(写闸 = `WorkerSpec.safeParse`,拒因在 zod issue 里);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "17.0.0",
+  "version": "17.1.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, 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",