@sema-agent/settings-schema 15.0.0 → 15.1.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@
 
 ## Unreleased
 
+## 15.1.0 — 2026-10-28 — minor:车道坐标「空白按缺」的唯一判官 `isBlankCoordinate` 升为包根导出(加性:包根多一个名字,函数体与既有答案逐位不变)
+
+> 档位(按发版纪律):**minor** —— 加性:新导出一个(包根 `isBlankCoordinate`;导出面登记表 包根 761 → 762 名,合计 1460 → 1461 名)。没有新子路径、没有删改的导出;既有导出的答案逐位不变(写闸读的仍是同一个函数对象)。无 BREAKING,无迁移动作。
+> 15.0.0 节写的「判官 `isBlankCoordinate` 在包内私有、不进任何导出面」是 15.0.0 的事实;本版起它在包根,那一句不再成立(已发布的节不改,更正记在这里)。
+
+- **`isBlankCoordinate(value: string): boolean`(包根,具名导出;函数体就是写闸一直在读的那一只,`src/execution-lane-index.ts`)**。必需坐标「未设 / 空串 / 只含空白」一律算缺,15.0.0 起写闸对所有车道、所有必需坐标同判这一条;判官此前在包内私有,
+  想在自己一侧问同一个问题的消费方只能手抄一份同义函数,两份迟早在某个空白字符上各说各话。现在包根给同一只:`import { isBlankCoordinate } from "@sema-agent/settings-schema"`。
+  契约(与写闸逐位同):入参是**已经有的字符串值**,空串或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 / 全角空格 …)⇒ `true`,带任何非空白字符 ⇒ `false`;
+  它**不 trim 值、不管值的格式**(`" sandboxes "` 不是空白);「这一键根本没设」由调用方先判(写闸对没设的键另有一句 `requires coords.<键>`,两种缺法同样被拒);
+  它只答「这个值是不是空白」,不管键是必需还是可选 —— 据它**拒不拒**一个坐标由调用方按键的必需 / 可选决定:写闸只对必需坐标据它拒;个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata),可选坐标的空串照收。
+  索引模块 `execution-lane-index` 里其余的导出(车道表的派生索引、迁移键集、谓词)仍是包私有,主桶只具名取走这一个名字(不是 `export *`)。
+  三问 —— **谁需要**:在自己一侧判「必需坐标算不算缺」的消费方(例:服务端的必需 env 门、命令行):调同一只,不再各抄一份;
+  **谁受伤**:无 —— 新导出,没有既有读者;既有导出的答案逐位不变;**补偿**:无需。
+  钉:`test/blank-coordinate-export-15.1.0.test.ts`(引用:包根导出与包内写闸读的是同一个函数对象 · 真值表:`""` / `" "` / `"\t\n"` ⇒ 缺,`"a"` / `" a "` ⇒ 不缺,另含 trim 认的其余空白与真值 · 与写闸对 `K8S_NAMESPACE` 逐样本同答 ·
+  可选坐标的空串写闸照收 · 面:索引模块其余导出不在包根、登记表里该名只在包根一处且形为 value)、`test/api-surface.test.ts`(登记表 +1 行,与生成器输出逐字同)。
+
+**自 v15.0.0 起运行期代码有改动的公开导出(机器重算;上界 —— 可达 ≠ 一定变,不可达 ⇒ 一定不变;本版新增的导出不入表)**
+
+```text
+(无)
+```
+
 ## 15.0.0 — 2026-10-28 — major:k8s 车道的沙箱命名空间 `K8S_NAMESPACE` 由可选挪进必需(车道表的 k8s 行 · 本地文件契约 `RemoteExecSpec` 的 k8s 臂)· 写闸对必需坐标的值:空串或只含空白一律按缺(校验收紧三处:此前受理的声明从受理变成拒绝)
 
 > 档位(按发版纪律):**major** —— 校验收紧三处,每一处都让此前受理的输入被拒:**B1** 车道表把 `K8S_NAMESPACE` 挪进 k8s 行的必需栏(缺它的 k8s worker 被写闸拒;存下来的 workers 文档里有这样一行,

package/README.md

@@ -47,6 +47,11 @@ 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).
 
+## 升级指引:15.0.x → 15.1.0(加性,零动作可升)
+
+包根多一个导出 `isBlankCoordinate(value: string): boolean` —— 车道坐标「空白按缺」的唯一判官:空串或只含空白 ⇒ `true`(写闸对必需坐标一直读的就是它),不 trim 值、不管值的格式;
+「这一键没设」由调用方先判;据它拒不拒由调用方按键的必需 / 可选决定(写闸只对必需坐标据它拒,可选坐标的空串照收)。在自己一侧判「必需坐标算不算缺」的消费方 import 它,退役手抄的同义函数。导出面只多这一个名字,既有导出的答案逐位不变。逐条见 CHANGELOG 15.1.0。
+
 ## 升级指引:14.8.x → 15.0.0(BREAKING:k8s 车道的 `K8S_NAMESPACE` 由可选变必需 —— 车道表与本地文件契约两处;必需坐标的纯空白值按缺)
 
 - **改了什么**:车道表 `EXECUTION_LANES` 的 k8s 行把 `K8S_NAMESPACE`(沙箱 pod 所在的命名空间)从 `optionalEnv` 挪进 `requiredEnv`(现为 `["K8S_SANDBOX_IMAGE", "K8S_NAMESPACE"]`)。

package/conformance/VERSION

@@ -1 +1 @@
-15.0.0
+15.1.0

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

@@ -1,7 +1,9 @@
 /**
- * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
+ * 车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
  * 供 `types.ts`(写闸)与 `one-time-migrations.ts`(一次性迁移 SS-M4)同读。
- * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
+ * 本模块是包内私有的:不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势),主桶也只具名取走一个名字 ——
+ * 必需坐标算不算「缺」的唯一判官 {@link isBlankCoordinate}(消费方要在自己一侧问同一个问题,调包根上这一只,不抄第二份);
+ * 其余导出(索引、键集、谓词)仍不进主桶 —— 消费方只拿表本身,它们是本包的实现细节。
  * 索引只从表派生,不另存任何词:表改了,这里跟着变。
  *
  * ## 迁移指路(7.0.1;11.0.0 起指路句住 `retired-form.ts`)
@@ -23,9 +25,10 @@ export interface LaneEnvOwner {
 /** 车道 env 名 → 归属。四栏两两不交、跨车道不交(`test/execution-lanes-7.0.0.test.ts` 钉),所以每个名恰好一个归属。 */
 export declare const LANE_ENV_OWNER: ReadonlyMap<string, LaneEnvOwner>;
 /**
- * 必需坐标的值算不算「缺」的**唯一判官**:空串,或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 …),都按缺席论。
- * 写闸对所有车道、所有必需坐标同判这一只;它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围)。可选坐标不走它 ——
- * 个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata)。
+ * 车道坐标的**唯一判官**:一个必需坐标「未设 / 空串 / 只含空白」一律算缺。本函数判其中的后两种,且只看**已经有的字符串值**:空串,或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 …)⇒ `true`;
+ * 「这一键根本没设」由调用方先判(写闸对没设的键另有一句 `requires coords.<键>`,两种缺法同样被拒)。
+ * 写闸对所有车道、所有必需坐标同判这一只;它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围:`" sandboxes "` 不是空白)。
+ * 它只答「这个值是不是空白」,不管这个键是必需还是可选:据它**拒不拒**一个坐标,由调用方按键的必需 / 可选决定 —— 写闸只对必需坐标据它拒;个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata),可选坐标的空串照收。
  */
 export declare function isBlankCoordinate(value: string): boolean;
 /** 一个车道 env 名在 WorkerSpec 里的**唯一写位**(保留键的拒因指路用它)。 */

package/dist/execution-lane-index.js

@@ -1,7 +1,9 @@
 /**
- * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
+ * 车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
  * 供 `types.ts`(写闸)与 `one-time-migrations.ts`(一次性迁移 SS-M4)同读。
- * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
+ * 本模块是包内私有的:不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势),主桶也只具名取走一个名字 ——
+ * 必需坐标算不算「缺」的唯一判官 {@link isBlankCoordinate}(消费方要在自己一侧问同一个问题,调包根上这一只,不抄第二份);
+ * 其余导出(索引、键集、谓词)仍不进主桶 —— 消费方只拿表本身,它们是本包的实现细节。
  * 索引只从表派生,不另存任何词:表改了,这里跟着变。
  *
  * ## 迁移指路(7.0.1;11.0.0 起指路句住 `retired-form.ts`)
@@ -25,9 +27,10 @@ export const LANE_ENV_OWNER = new Map(EXECUTION_LANES.flatMap((r) => {
     return [...own(r.requiredEnv, false, true), ...own(r.optionalEnv, false, false), ...own(r.requiredSecretEnv, true, true), ...own(r.optionalSecretEnv, true, false)];
 }));
 /**
- * 必需坐标的值算不算「缺」的**唯一判官**:空串,或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 …),都按缺席论。
- * 写闸对所有车道、所有必需坐标同判这一只;它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围)。可选坐标不走它 ——
- * 个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata)。
+ * 车道坐标的**唯一判官**:一个必需坐标「未设 / 空串 / 只含空白」一律算缺。本函数判其中的后两种,且只看**已经有的字符串值**:空串,或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 …)⇒ `true`;
+ * 「这一键根本没设」由调用方先判(写闸对没设的键另有一句 `requires coords.<键>`,两种缺法同样被拒)。
+ * 写闸对所有车道、所有必需坐标同判这一只;它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围:`" sandboxes "` 不是空白)。
+ * 它只答「这个值是不是空白」,不管这个键是必需还是可选:据它**拒不拒**一个坐标,由调用方按键的必需 / 可选决定 —— 写闸只对必需坐标据它拒;个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata),可选坐标的空串照收。
  */
 export function isBlankCoordinate(value) {
     return value.trim() === "";

package/dist/index.d.ts

@@ -47,3 +47,4 @@ export * from "./control-and-bidi.js";
 export * from "./mcp-request-entry.js";
 export { REMOTE_MCP_SERVER_NAME_PREFIX } from "./mcp-server-name.js";
 export * from "./center-refs.js";
+export { isBlankCoordinate } from "./execution-lane-index.js";

package/dist/index.js

@@ -47,6 +47,7 @@ export * from "./control-and-bidi.js"; // the one-line echo strip set (C0 + DEL
 export * from "./mcp-request-entry.js"; // 14.0.0: the request-plane MCP entry judges (isUsableWireName / isContentOriginWord / readMcpIdentityHeaders / readRequestMcpTransport + the value-shape describers) — one reading for the service legs and the shell pre-check, pure/browser-safe
 export { REMOTE_MCP_SERVER_NAME_PREFIX } from "./mcp-server-name.js"; // the MCP server-name prefix reserved for the remote MCP servers a device executor offers (mount name = prefix + the executor's server name); the predicate and its sentence stay package-private — the request plane's MCP name judges (isUsableMcpServerName / describeBadMcpServerName) read them; the config plane's McpServerSpec.name accepts the prefix (refusing it would be a validation tightening — a major), pure/browser-safe
 export * from "./center-refs.js"; // resolveCenterRefs(refs, lookup) — THE center-roster reference resolver: one verdict word per member (missing_name / not_a_string / read_threw, CENTER_REF_FAULTS), one whole verdict (resolved / unresolved / refs_unreadable, CENTER_REFS_VERDICTS); the refs record is read by the public readPlainStringRecord, the lookup is the caller's, it reads no process.env; pure/browser-safe
+export { isBlankCoordinate } from "./execution-lane-index.js"; // THE lane-coordinate blank judge (empty or whitespace-only = absent; the write gate and every consumer ask this one function; whether a key is set, and whether an optional key may be empty, stays the caller's call); named: the lane tables' derived indexes stay package-private, 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.
 // web-admin's client components import the zod types through here). Import them from the Node-only

package/dist/types.js

@@ -30,7 +30,7 @@ import { PREVIOUS_WEB_ADMIN_ENV } from "./previous-web-admin-env.js"; // the pre
 import { retiredEnvRefusal } from "./retired-envs.js"; // the worker env write gate asks the retired-env tombstone table too (one table, one refusal sentence)
 import { Sha256Digest } from "./sha256.js"; // the one `sha256:<hex>` digest form
 import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
-import { LANE_ENV_OWNER, isBlankCoordinate, isMigratableEnvKey, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (not in the barrel)
+import { LANE_ENV_OWNER, isBlankCoordinate, isMigratableEnvKey, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (isBlankCoordinate is also named in the barrel; the rest are not)
 import { migrationSignpost, retiredFormSentence, retiredKey } from "./retired-form.js"; // 11.0.0: the ONE retired-form sentence + key tombstone (package-private)
 import { retiredRoleWordsRefusal } from "./retired-role-words.js"; // 12.0.0: the retired role-word tombstone (package-private; SS-M8)
 import { buildQuotedIssue, fixed } from "./quoted-issue.js"; // THE minting point of custom issues (package-private)

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1460 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1461 个(同名在多条子路径上各计一次)。
 
-## `.`(761)
+## `.`(762)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -645,6 +645,7 @@
 - `interpolateHookEnvVars` — value
 - `isAbsoluteHostPath` — value
 - `isAtLeast` — value
+- `isBlankCoordinate` — value
 - `isCanonicalGeneration` — value
 - `isContentOriginWord` — value
 - `isCredentialParamName` — value

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-10-28 | 包版本: 15.0.0
+重写日期: 2026-10-28 | 包版本: 15.1.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -268,6 +268,9 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   坐标在每行 JSDoc)。`TENANT_SEPARATION_WORDS`。
   k8s 行的非密必需栏 = `K8S_SANDBOX_IMAGE` + `K8S_NAMESPACE`(沙箱 pod 所在的命名空间,部署自己声明;服务端的必需 env 门按本行 `requiredEnv ∪ requiredSecretEnv` 拒启)——
   写 worker 的 k8s 行时 `runtime.execution.coords` 两键都要给,缺一键 ⇒ 写闸 issue、存下来的 workers 文档整域读不出。
+- `isBlankCoordinate(value: string): boolean`(包根,15.1.0):必需坐标的值算不算「缺」的**唯一判官** —— 空串或只含空白(`String.prototype.trim` 认的空白)⇒ `true`,带任何非空白字符 ⇒ `false`;
+  不 trim 值、不管值的格式(`" sandboxes "` 不是空白)。写闸对所有车道、所有必需坐标读的就是这一只,消费方在自己一侧问同一个问题调它、不抄第二份。
+  它只看已经有的字符串值:「这一键根本没设」由调用方先判(写闸对没设的键另有一句 `requires coords.<键>`),据它拒不拒由调用方按键是必需还是可选决定:写闸只对必需坐标据它拒,可选坐标的空串照收(`K8S_RUNTIME_CLASS` 的空串 = 不用 Kata)。(src/execution-lane-index.ts)
 - `STORE_BACKENDS`(mysql/pg/local/memory)、`SESSION_BACKENDS`(memory/mysql/auto)、`MEMORY_ENGINE_BACKENDS`(file/pg/tidb)。
 - 判据(都在 `WorkerSpec` schema 里,zod issue 的 `path` 指字段、message 带出路):enabled ⇒ 两块必填;coords / secretRefs 键 ⊆
   表[lane] 对应栏、必需键在场且非空白(空串或只含空白按缺);别车道键点名车道;`requirePrincipal` ∧ single-user-only 车道拒(出路按表现算);host ∧ 副本 > 1

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-10-28 | 包版本: 15.0.0
+重写日期: 2026-10-28 | 包版本: 15.1.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、
@@ -87,6 +87,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   每个 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 判别联合〕+ 它读的 env 名四栏)、退役车道值墓碑 `RETIRED_LANE_WORDS` + 拒句 `retiredLaneWordRefusal(word)`(11.0.0)、`STORE_BACKENDS` / `SESSION_BACKENDS` / `MEMORY_ENGINE_BACKENDS`。
+  必需坐标的值算不算「缺」的唯一判官 `isBlankCoordinate(value)`(包根,15.1.0:空串或只含空白 ⇒ true;写闸读的同一只,消费方在自己一侧问同一个问题调它;「键没设」由调用方先判,据它拒不拒由调用方按键的必需 / 可选决定〔写闸只对必需坐标据它拒〕;src/execution-lane-index.ts)。
   WorkerSpec 的 `runtime.execution` / `runtime.store` 两块按这张表判(写闸 = `WorkerSpec.safeParse`,拒因在 zod issue 里);
   6.x 存量 workers 文档在 `parseDomain` 之前跑一次 `migrateWorkersDomain`(或 bin `npx @sema-agent/settings-schema migrate-workers`;7.0.1 起 stdout = 结论行 `outcome=… written=…` + JSON,没写时 `wouldChange` 取代 `changed`)。
   (src/execution-lanes.ts;src/types.ts: `WorkerSpec`;src/migrate-workers.ts)

package/package.json

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