@sema-agent/settings-schema 14.7.0 → 15.0.0

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1396 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1460 个(同名在多条子路径上各计一次)。
 
-## `.`(708)
+## `.`(761)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -33,8 +33,12 @@
 - `BaseHookInput` — value+type
 - `BudgetGroup` — value+type
 - `BudgetGroupMember` — value
+- `CATALOG_REPLACES_ENV_MODELS_CODE` — value
+- `CENTER_REFS_VERDICTS` — value
+- `CENTER_REF_FAULTS` — value
 - `COMMAND_DECISIONS` — value
 - `CONFIG_CHANGE_SOURCES` — value
+- `CONFIG_ROOT_DOCUMENTS` — value
 - `CONTROL_AND_BIDI_CHARS` — value
 - `CREDENTIAL_PARAM_NAMES` — value
 - `CROSS_SESSION_INBOUND_UNSET` — value
@@ -44,6 +48,12 @@
 - `CasWriteResult` — type
 - `CatalogDefaultModel` — type
 - `CatalogDefaultSource` — type
+- `CenterRefFault` — type
+- `CenterRefLookup` — type
+- `CenterRefMember` — type
+- `CenterRefMemberVerdict` — type
+- `CenterRefsResolution` — type
+- `CenterRefsVerdict` — type
 - `CollabConfig` — value+type
 - `CollabEarlyStop` — value+type
 - `CollabFinalizerType` — value+type
@@ -56,6 +66,7 @@
 - `ConfigChangeHookInput` — value
 - `ConfigPath` — type
 - `ConfigReader` — type
+- `ConfigRootDocument` — type
 - `CredentialHandleAnswer` — value+type
 - `CredentialParamName` — type
 - `CredentialResolveRequest` — value+type
@@ -71,6 +82,7 @@
 - `DEFAULT_HEARTBEAT_MS` — value
 - `DEFAULT_HOOK_TIMEOUT_SECONDS` — value
 - `DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC` — value
+- `DEFAULT_MODEL_KEY` — value
 - `DEFAULT_OFFLINE_GRACE_SEC` — value
 - `DEFAULT_ROLE_TIER_LADDER` — value
 - `DELIVER_DENYLIST` — value
@@ -121,6 +133,9 @@
 - `DroppedEntryReasonCode` — type
 - `ENGINE_OWNED_HOOK_EVENTS` — value
 - `ENGINE_SIGNAL_KEY` — value
+- `ENV_MODELS_DECISIONS` — value
+- `ENV_MODELS_DOCUMENT` — value
+- `ENV_MODEL_TABLE_KEYS` — value
 - `ENV_NAME` — value
 - `EXECUTION_LANES` — value
 - `EXECUTION_LANE_WORDS` — value
@@ -143,8 +158,23 @@
 - `EntitlementTier` — value+type
 - `EntryKeptIndex` — type
 - `EntrySalvageResult` — type
+- `EnvCheapSlot` — type
+- `EnvModelBaseline` — type
+- `EnvModelTableEntry` — type
+- `EnvModelTableKey` — type
+- `EnvModelTableLanding` — type
+- `EnvModelTableReceipt` — type
+- `EnvModelTableRoleRow` — type
+- `EnvModelTableTarget` — type
+- `EnvModelTableWriteInput` — type
+- `EnvModelTableWriteIntent` — type
+- `EnvModelTableWritePlan` — type
+- `EnvModelsDecision` — type
+- `EnvModelsDecisionWord` — type
 - `EnvRef` — type
 - `EnvRefUse` — type
+- `EnvRoleBinding` — type
+- `EnvSnapshot` — type
 - `ExecutionLane` — type
 - `ExecutionLaneRow` — type
 - `ExecutionPolicy` — value+type
@@ -245,6 +275,7 @@
 - `MODEL_ENTRY_REFUSAL_CODES` — value
 - `MODEL_PLANE_REFUSAL_CODES` — value
 - `MODEL_SWITCH_SOURCES` — value
+- `MarkedMigrationId` — type
 - `McpConfig` — value+type
 - `McpContentOrigin` — type
 - `McpEntryKeyIssue` — type
@@ -264,6 +295,7 @@
 - `MergeCategorySpec` — value+type
 - `MergeShape` — value+type
 - `MessageDisplayHookInput` — value
+- `MigrationMarker` — type
 - `MinTrust` — value+type
 - `ModelCost` — value
 - `ModelEntry` — value+type
@@ -284,6 +316,8 @@
 - `OAuthErrorResponse` — value+type
 - `PARSE_TRANSPARENT_KEYS` — value
 - `PATH_BASE_URL_FORBIDDEN_PARTS` — value
+- `PLAIN_STRING_RECORD_FAULTS` — value
+- `PLAIN_STRING_RECORD_RESERVED_MEMBER` — value
 - `PLUGIN_ORIGIN` — value
 - `PRINCIPAL_INC_CLAIM` — value
 - `PRINCIPAL_MAX_LENGTH` — value
@@ -308,6 +342,8 @@
 - `PermissionRuleValue` — value+type
 - `PermissionUpdate` — value+type
 - `PermissionUpdateDestination` — value+type
+- `PlainStringRecordFault` — type
+- `PlainStringRecordRead` — type
 - `PluginSource` — value+type
 - `PluginSpec` — value+type
 - `PluginsConfig` — value+type
@@ -349,6 +385,7 @@
 - `REF_ISSUE_TARGET_DOMAIN` — value
 - `REF_REFERRER_DOMAINS` — value
 - `REMOTE_EXEC_DOCUMENT` — value
+- `REMOTE_MCP_SERVER_NAME_PREFIX` — value
 - `RESERVED_SCOPE_IDS` — value
 - `RESERVED_WORKER_ENV` — value
 - `RETIRED_DOMAINS` — value
@@ -356,6 +393,7 @@
 - `RETIRED_ENV_REFUSAL_CODE` — value
 - `RETIRED_LANE_WORDS` — value
 - `ROLE_RANK` — value
+- `ROOT_DOCUMENT_UNREADABLE_REASONS` — value
 - `ROSTER_CHEAP_ROLES` — value
 - `ROSTER_PRIMARY_ROLES` — value
 - `RUNTIME_CAP_STRICT` — value
@@ -379,6 +417,7 @@
 - `RetiredEnvWire` — type
 - `RetiredLaneWord` — type
 - `RoleTarget` — value+type
+- `RootDocumentUnreadableReason` — type
 - `RosterEntry` — value+type
 - `RostersConfig` — value+type
 - `RoutingVerdict` — type
@@ -414,6 +453,7 @@
 - `STALE_SESSION_RECORD_MS` — value
 - `STORE_BACKENDS` — value
 - `SUBMIT_IDEMPOTENCY_KEY` — value
+- `SUMMARIZE_MODEL_MISSING_CODE` — value
 - `SafetyMergeCategory` — type
 - `SafetyMergeMember` — type
 - `SandboxGitConfig` — value+type
@@ -561,9 +601,11 @@
 - `aggregateUsage` — value
 - `applyProjectPatch` — value
 - `buildEffective` — value
+- `buildEnvModelBaseline` — value
 - `buildLayerPartsUnreadNotice` — value
 - `buildRetiredEnvWire` — value
 - `canSwitchScope` — value
+- `catalogManagesModelPlane` — value
 - `clampServingLeaseTtlMs` — value
 - `classifyHooksConfig` — value
 - `classifyTimeClaims` — value
@@ -573,6 +615,7 @@
 - `createSiblingResolver` — value
 - `danglingRefs` — value
 - `describeBadContentOrigin` — value
+- `describeBadMcpServerName` — value
 - `describeBadWireName` — value
 - `describeNotStringArray` — value
 - `describeNotStringRecord` — value
@@ -581,6 +624,10 @@
 - `drainVerdict` — value
 - `effectiveScopeRole` — value
 - `emptyEffective` — value
+- `enabledEntryCount` — value
+- `envModelTableDeclared` — value
+- `envModelTableWriteRefusal` — value
+- `envModelsDecisionTag` — value
 - `extraBodyUnsafe` — value
 - `findSkillContent` — value
 - `findUrlCredential` — value
@@ -619,6 +666,7 @@
 - `isSchedulerRecord` — value
 - `isStringArray` — value
 - `isStringRecord` — value
+- `isUsableMcpServerName` — value
 - `isUsableWireName` — value
 - `judgeReadiness` — value
 - `judgeRoutability` — value
@@ -635,6 +683,7 @@
 - `memberTighten` — value
 - `membersOf` — value
 - `mintScopedToken` — value
+- `mintedCheapId` — value
 - `narrowAtMention` — value
 - `nextPollInterval` — value
 - `normalizeContentHash` — value
@@ -648,6 +697,7 @@
 - `parseWebAdminSessionUrl` — value
 - `pathBaseUrlFlaws` — value
 - `pickInstance` — value
+- `planEnvModelTableWrite` — value
 - `projectWarning` — value
 - `promptArtifactFor` — value
 - `readCapabilityReading` — value
@@ -657,9 +707,11 @@
 - `readDrainRequest` — value
 - `readEffectiveWire` — value
 - `readEngineSignal` — value
+- `readEnvModelSlots` — value
 - `readHttpHookAllowlistLayer` — value
 - `readMcpIdentityHeaders` — value
 - `readModelRefusals` — value
+- `readPlainStringRecord` — value
 - `readRequestMcpTransport` — value
 - `readScopedTokenBinding` — value
 - `readServingLeaseRequest` — value
@@ -677,6 +729,7 @@
 - `renderRefIssue` — value
 - `resolveActiveTiers` — value
 - `resolveCatalogDefaultModel` — value
+- `resolveCenterRefs` — value
 - `resolveEffectiveForWorker` — value
 - `resolveMemberAdmission` — value
 - `resolveMemberTighten` — value
@@ -1111,7 +1164,7 @@
 - `tightenVerdict` — value
 - `trustRank` — value
 
-## `./node`(39)
+## `./node`(48)
 
 - `ConfigBundle` — type
 - `ConfigDirectoryDocument` — type
@@ -1119,7 +1172,11 @@
 - `ConfigDirectoryMigration` — type
 - `ConfigDirectoryRefusal` — type
 - `ConfigDocumentsMigration` — type
+- `ConfigRootIo` — type
 - `DomainReadError` — type
+- `EnvModelsDecisionWrite` — type
+- `EnvModelsMigration` — type
+- `EnvModelsMint` — type
 - `FileConfigStore` — value+type
 - `LocalConfig` — type
 - `MigrateConfigDirectoryOptions` — type
@@ -1142,15 +1199,20 @@
 - `loadSchedulerStore` — value
 - `migrateConfigDirectory` — value
 - `migrateConfigDocuments` — value
+- `migrateEnvModelsDecision` — value
 - `mutateSchedulerStore` — value
 - `nodeConfigDirectoryIo` — value
+- `nodeConfigRootIo` — value
 - `readBundle` — value
+- `readEnvModelsDecision` — value
+- `readMigrationMarker` — value
 - `remoteExecPath` — value
 - `saveSchedulerStore` — value
 - `validateDomain` — value
 - `validateRemoteExec` — value
 - `writeBundle` — value
 - `writeDomainFile` — value
+- `writeEnvModelsDecision` — value
 - `writeRemoteExec` — value
 
 ## `./one-time-migrations`(18)
@@ -1284,9 +1346,10 @@
 - `interpolateHookEnvVars` — value
 - `stopAttributionText` — value
 
-## `./fleet`(84)
+## `./fleet`(86)
 
 - `AggregatedPrincipalUsage` — type
+- `CATALOG_REPLACES_ENV_MODELS_CODE` — value
 - `CapabilityReading` — type
 - `DEFAULT_DRAIN_GRACE_MS` — value
 - `DEFAULT_HEARTBEAT_MS` — value
@@ -1340,6 +1403,7 @@
 - `SERVING_LEASE_VERDICTS` — value
 - `STALE_HEARTBEAT_MULTIPLIER` — value
 - `SUBMIT_IDEMPOTENCY_KEY` — value
+- `SUMMARIZE_MODEL_MISSING_CODE` — value
 - `ServingLeaseDeniedReason` — value+type
 - `ServingLeaseReading` — type
 - `ServingLeaseRequest` — value+type

package/docs/CONSUMER-INTEGRATION.md

@@ -9,6 +9,7 @@
 > **11.0.0** 的持久面(`runtime` 域退役、读侧兼容臂退役、一次性迁移族 `./one-time-migrations`)在 §0.4。
 > **14.7.0** 的沙箱 git 凭据平面(取值口 wire 型、有效配置块 `sandboxGit`、`VerifiedIdentity.principalInc`)在 §12。
 > **14.7.0** 的路径基址判官(`PATH_BASE_URL_FORBIDDEN_PARTS` / `pathBaseUrlFlaws`)与公告地址 env 名(`FLEET_ADVERTISE_ADDRESS_ENV`)在 §13。
+> 中心引用解析口 `resolveCenterRefs` 与记录读器 `readPlainStringRecord`(原因词表 `PLAIN_STRING_RECORD_FAULTS`)在 §14。
 
 ---
 
@@ -118,7 +119,7 @@
 - **读侧的新形**:`ModelEntry` 钥匙二选一(`sealedApiKey` 与 `apiKeyEnv` 同设 ⇒ 拒);`atMention`(`{mode:"all"}` 缺省 /
   `{mode:"none"}` / `{mode:"only",models}`,roster 位缺席 = 继承,收窄读法一只 `narrowAtMention` —— 收窄到一个都不剩就是 `none`);
   workers 6.x 字段与 `atModelAllowlist` 是 schema 里原位的**墓碑字段**(在场即拒,句子点名迁移);`readWorkersRows(raw) → { doc, held }`
-  (workers 域的逐行终判,取代 `migrateWorkersDomain` 的终判半)。
+  (workers 域的逐行终判,取代 `migrateWorkersDomain` 的终判半;被扣下的行若还带着旧字段,`held[].field` 指到那个旧字段,`reason` 的文字**不点名它**,说现行位与出路:跑迁移,迁移已拒过这一行的就手写现行形、删旧字段)。
 - **调度店**:`parseSchedulerStore(text, { nowMs })` / `loadSchedulerStore(path, { nowMs })` 恒返回 `{ records, warnings }`(没有静默模式);
   整份文件不是 JSON 数组 ⇒ `unreadable-file`,`mutateSchedulerStore(path, fn, { nowMs })` 遇它不调 `fn`、不写(`reason: "unreadable_file"`);
   会话链上的记录(显式 `lifetime: "session"`)过期 ≥ 7 天 ⇒ 读时丢 + `stale-session-record`(`lifetime` 缺席读作 durable,不丢);所有写者走 `mutateSchedulerStore` 这一只原语(裸 load→save 是丢更新的竞争)。
@@ -216,7 +217,7 @@ server 直接拒启,不是静默降级。上一代 `SEMA_REGISTRY_*` 八名(`URL
 |---|---|---|
 | models / roles | `RunnerDeps.models`/`roles` | role 解析不变 |
 | skills | 本地=全文内联;远程=manifest + `fetchSkillContent(hash)` | 本地无 wire 跳,无需按 hash 回取 |
-| mcp | `TaskSpec.mcp`(allowTools + principalHeader) | env/header NAME→值解析 |
+| mcp | `TaskSpec.mcp`(allowTools + principalHeader + sessionMetaKey) | env/header NAME→值解析;`sessionMetaKey` 本包原样承运,交给引擎之前可调引擎的 `judgeSessionMetaKey` 早判 |
 | limits(0.19.0,cost/限流族 14 键;11.0.0 起五个限额键的唯一位) | 消费方的限额面(server:`stage-limits`) | `.optional()` 无默认;本包只判结构,业务域值(下限/0 哨兵/跨键不变量)由消费方响亮拒 |
 | governance.autonomy / commandPolicy | 见 §6(小心区) | 经 tightenTaskSpec / combinePolicies |
 | rosters | control-plane only | `/effective` wire 经 `resolveEffectiveForWorker` 清空/剥离 |
@@ -461,3 +462,72 @@ fleet 成员对中心公告的可达地址(`FLEET_ADVERTISE_ADDRESS`,中心往
 - **缺席 / 空串的处置**:见 §13.3 —— 读的一方自己答。
 - **座位名册**:一个值算不算「后面要拼路径的基址」是读它的一方的事;本包给的是判这种座位的那一只判官,不维护座位清单(§13 开头列的是今天已知的读者)。
 - **不进保留 env 名表**:`FLEET_ADVERTISE_ADDRESS` 与 generation / scope 两只不同 —— 那两只只有渲染器能写,所以进 `RESERVED_WORKER_ENV`;公告地址是运维可以声明的值(渲染器也可以写),`worker.env` 设它照旧不被拒。
+
+## 14. 中心引用解析口 `resolveCenterRefs` 与记录读器 `readPlainStringRecord` —— 服务端中心腿与客户端核心两方的读法
+
+中心名册里 MCP server 的传输带两张**引用表**:stdio 的 `envRefs`(目标 env 键 → 变量名)、http 的 `headerRefs`(目标头名 → 变量名)。名册只存变量名、从不存值;值要在消费方自己的宿主环境里读。
+「变量没设」「设了但读到的不是串」「读它的时候抛了」「引用表本身不成样子」四种情形,本包此前只发引用表的形、不发读法,留给每个宿主自己写。本节说**本包发什么、两方各自怎么读**:本包只有**读引用表的那一个读法**(纯、浏览器安全、零 IO、不读环境);
+读哪一层环境、要不要缓存、解不开时挂不挂(§14.4),都是两方自己的事。
+
+### 14.1 本包发什么
+
+| 件 | 是什么 |
+|---|---|
+| `resolveCenterRefs(refs, lookup)` | 解析口。`refs` = 名册里 `envRefs` / `headerRefs` 的值(`undefined` = 没声明);`lookup(name) => string \| undefined` = **调用方给的**查找函数(必给)。返回 `CenterRefsResolution`,按 `verdict` 分三臂;包根 |
+| `CENTER_REF_FAULTS` / `CenterRefFault` | 一个成员没解到的原因词,闭集:`missing_name` · `not_a_string` · `read_threw`;包根 |
+| `CENTER_REFS_VERDICTS` / `CenterRefsVerdict` | 整台结论的词,闭集:`resolved` · `unresolved` · `refs_unreadable`;包根 |
+| `CenterRefMember` / `CenterRefMemberVerdict` / `CenterRefLookup` / `CenterRefsResolution` | 型:成员行 `{ key, ref, verdict }`(`verdict` = `resolved` 或上面三词之一)· 判定词 · 查找函数型 · 读数;包根 |
+| `readPlainStringRecord(v)` | 「名 → 串」记录的读器(传输读器读 `env` / `headers` 用的就是它,同一个函数);包根 |
+| `PLAIN_STRING_RECORD_FAULTS` / `PlainStringRecordFault` / `PlainStringRecordRead` / `PLAIN_STRING_RECORD_RESERVED_MEMBER` | 读器的原因词表(三词)· 词的型 · 读数型 · 保留成员名 `"__proto__"`;包根 |
+
+### 14.2 解析口的读法(一条律:每成员一句判定,整台一个结论)
+
+1. 引用表经 `readPlainStringRecord` 读。读不出(整张不是纯数据、有成员的变量名不是串、读成员就抛、叫 `__proto__` 的成员)⇒ **整台 `refs_unreadable`**,`fault` 是读器的词、坏在某个成员时 `member` 点名它的回显形;**一个变量都没问**。
+   读器会把叫 `__proto__` 的串值成员剔出副本;解析口不许这样悄悄丢一条引用再挂,所以同样答 `refs_unreadable` / `member_name_reserved`。
+2. 每个成员恰问一次 `lookup(变量名)`(按引用表副本的自有键序:整数形的键在前、其余按记录列出的次序;实参只有变量名),判成**一个词**。一个成员坏了不早停 —— 每个成员都有自己的判定,调用方一次点名所有缺的变量:
+
+   | `lookup` 的答案 | 成员词 |
+   |---|---|
+   | 一个串(空串也是串) | `resolved` |
+   | `undefined`(变量没设) | `missing_name` |
+   | 别的种类(数、`null`、对象、函数……) | `not_a_string` |
+   | 抛了(任何抛出值,含撤销的 Proxy) | `read_threw`(不传出) |
+
+3. 整台结论:每个成员都 `resolved`(零成员也是)⇒ `resolved`,带 `values`(目标键 → 串,新铸的朴素对象);有成员不是 ⇒ `unresolved`,带 `members`(**行里没有变量的值**,失败读数可以进日志);引用表读不出 ⇒ `refs_unreadable`。
+4. `refs` 是 `undefined` ⇒ `resolved`、零成员、零次查找,与空表同答;别的非记录值(`null`、数组、串)是 `refs_unreadable`,不当缺席。
+5. `lookup` 没给 / 不是函数 ⇒ **`TypeError`**(调用方的编程错;不折成 `read_threw`,更不回落任何环境 —— 本包不读 `process.env`)。
+
+`lookup` 的写法是调用方的事,有一条提醒:对普通对象做 `obj[name]` 会读到继承位(`toString` / `constructor`),解析口把它判成 `not_a_string`(响亮,不当作已设);想让这类名字落成「没设」就按自有键读
+(`Object.hasOwn(table, name) ? table[name] : undefined`)。同一个变量被两个目标键引用会被问两次 —— 缓存(每名读一次、跨轮不缓存)是查找函数的事。
+
+### 14.3 读器的原因词(`PLAIN_STRING_RECORD_FAULTS`,三词)
+
+| 词 | 说的是 | 记录交不交 |
+|---|---|---|
+| `not_plain_record` | 整张不是纯数据(`null` / 数组 / 原始值 / `Map` / 类实例 / 函数,或读形状就抛的对象) | 不交 |
+| `member_not_string` | 某个成员的值不是串(读成了别的种类),或它读不出(它的访问器抛了,或读它的描述符时代理陷阱抛了)—— 两种情形 `detail` 句子分说 | 不交,`member` 点名它 |
+| `member_name_reserved` | 某个成员叫 `__proto__`(引擎的声明收据拒这个名);名坏优先 —— 值也坏或读不出时句子并列说全,词仍是这一个 | 值是串:交其余、`reservedMember: true`;否则不交 |
+
+按词分派;读器从不抛。传输读器的 `lost[].fault` 就是这张表(读成员就抛的那一形,词是 `member_not_string`,句子 `could not be read (its getter threw)`)。
+
+### 14.4 两方做什么
+
+- **客户端核心 / 服务端中心腿**:
+  ```ts
+  const r = resolveCenterRefs(transport.envRefs, (name) => hostEnv.read(name)); // hostEnv = 你的宿主环境座位;headerRefs 同
+  switch (r.verdict) {
+    case "resolved": return mount(r.values);
+    case "unresolved": for (const m of r.members) if (m.verdict !== "resolved") warn(m.verdict, m.key, m.ref); return skipWholeServer();
+    case "refs_unreadable": warn(r.fault, r.member); return skipWholeServer();
+    default: { const unhandled: never = r; throw new Error(`unhandled ${String(unhandled)}`); }
+  }
+  ```
+  解析不了时挂不挂是你这条腿的规则(「整台不挂 + 点名」是一台少了鉴权头或凭据 env 的 server 不拨号的那条);本口只判。
+- **不手抄**:不要在自己这边再写一遍「变量没设 / 读到的不是串 / 读抛」的判法或这三个词的字面量;词表与读数型从本包 import,穷尽 `switch` 加 `never` 兜底(加词时编译红)。
+
+### 14.5 本包不做的(如实)
+
+- **读哪一层环境**:`lookup` 读什么(进程环境、合并后的环境、远端环境)是调用方的事;本包不读 `process.env`,也不缓存。
+- **挂不挂**:读数是判决,不是处置。
+- **变量名的形**:名册的 schema 已把变量名限在 env 名的字符集内;本口把变量名当不透明串交给 `lookup`,不再判一遍形。
+- **值的好坏**:解到串就是 `resolved`,空串、很长的串都不另判;值是不是凭据、扣不扣留,是读数之后的另一道判官的事。

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-10-25 | 包版本: 14.7.0
+重写日期: 2026-10-28 | 包版本: 15.0.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -109,6 +109,9 @@ registry:公网 npmjs,无需私有 registry 配置。
   · mcp:`McpServerSpec[]` —— `transport` 判别 stdio(command/args/envRefs)| http(url/headerRefs/
     principalHeader/assertionHeader;后两者互斥);`allowTools?`、`scenarios`/`rosters` 过滤、`elicitation`(默认 false,inbound elicitation
     的 per-server opt-in)、`contentOrigin?`(信任出处声明,闭词表 `MCP_CONTENT_ORIGINS =
+--- 14.8.0:`McpServerSpec.sessionMetaKey?`(`z.unknown().optional()` 解析透明,登记在 `PARSE_TRANSPARENT_KEYS`,`validatedBy: "engine-ingest"` —— 唯一判官 = 引擎根导出 `judgeSessionMetaKey`(类型 / 非空 / 上界 / MCP `_meta` 键名文法 / 保留前缀 / `progressToken` / `sema/` 命名空间一并判);引擎往这台服务器的 `tools/call` / `resources/read` 的 `params._meta[key]` 里放发送腿会话 id;缺席不铸键)---
+--- 14.8.0:`McpServerSpec.startupTimeoutMs?`(`z.unknown().optional()` 解析透明,登记在 `PARSE_TRANSPARENT_KEYS`,`validatedBy: "engine-ingest"` —— 格式与界由引擎判:唯一判官 = 引擎根导出 `mcpStartupTimeoutMs`(是不是数 / 整数性 / 范围一并判,在拨号时判:不合 ⇒ 拒这一台服务器的拨号,其余服务器照挂);这一台服务器自己的启动界,握手与首次工具列举各带它,缺席读进程级缺省界;本包不判、任何 JSON 值原样过,缺席不铸键)---
+--- 14.8.0:`remote-` 前缀保留给设备执行端提供的远程 MCP 服务器(`REMOTE_MCP_SERVER_NAME_PREFIX`,挂载名 `remote-<名>`;字面比较、区分大小写):请求面在 `isUsableMcpServerName` / `describeBadMcpServerName`(线上名判官 `isUsableWireName` 不变,A2A 对端名用它);配置面 `McpServerSpec.name` 不拒它(拒是校验收紧,归 major)---
 --- 12.2.0:`McpServerSpec.toolAxes?` / `authForm?` / `entryKind?`(三键均 `z.unknown().optional()` 解析透明,登记在 `PARSE_TRANSPARENT_KEYS`(`authForm` / `entryKind` `validatedBy: "consumer"`;`toolAxes` 自 13.0.0 起 `"engine-ingest"` —— 形判官只有引擎根导出 `readMcpToolAxes` 一只,消费方两腿都调它);连接器条目的声明键,词表与语义归读它的消费方,本包只承载、原样过任意 JSON 形;缺席不铸键)---
 --- 12.2.0:`McpTransport`(http 形)`assertionHeader?`(HTTP 头名,过 `principalHeader` / `headerRefs` 键同一只头名判官;承载连接器断言;与 `principalHeader` **互斥** —— 同设 ⇒ 解析期拒,条目层 `superRefine` 判一处,拒句点名条目名与两键;stdio 形上与 `principalHeader` 同判:键被剥并报 `unknown-keys-dropped`;缺席不铸键;断言怎么铸 / 验归消费方)---
 --- 1.9.0:`McpServerSpec.toolFaces?`(`z.unknown().optional()` 解析透明,登记在 `PARSE_TRANSPARENT_KEYS`;引擎的工具名册 face 覆盖层,按远端工具名 key `{family?, pathTarget?, renderHints?, ruleFace?}`;形校验归引擎摄入侧,不合 schema 的工具不挂并通告一次 `config.tool_face_invalid`;缺席不铸键)
@@ -248,7 +251,7 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   - `host`:{ workdir?, allowedPaths?, shell?, commandTimeoutMs? } —— 无 secret。
   - `local-docker`:{ image!, memory?, cpus?, network?("none"|"bridge"|"host"), workdir?, mountPath? }。
   - `e2b`:{ apiKeyEnv!, template?, timeoutMs?, livenessMs?, allowInternetAccess?, sandboxEnv? }。
-  - `k8s`:{ image!, apiUrl?, tokenEnv?, caCertEnv?, insecureTls?, namespace?, runtimeClass?, mountPath?,
+  - `k8s`:{ image!, apiUrl?, tokenEnv?, caCertEnv?, insecureTls?, namespace!, runtimeClass?, mountPath?,
     timeoutMs?, memory?, cpu?, s3Snapshot?{ endpoint, bucket?, accessKeyEnv, secretKeyEnv, … } }。
   - `ssh`:{ host!, port?, username!, privateKeyEnv!, mountPath? }。
   - `adb`:{ serial!, adbPath?, mountPath? }。
@@ -263,9 +266,11 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
 - `EXECUTION_LANES: readonly ExecutionLaneRow[]`:每行 `{ lane, tenantSeparation: "supported"|"single-user-only", requiredEnv,
   requiredSecretEnv, optionalEnv, optionalSecretEnv }`(深冻结;四栏 env 名两两不交、跨车道不交;行内容逐格抄自引擎,
   坐标在每行 JSDoc)。`TENANT_SEPARATION_WORDS`。
+  k8s 行的非密必需栏 = `K8S_SANDBOX_IMAGE` + `K8S_NAMESPACE`(沙箱 pod 所在的命名空间,部署自己声明;服务端的必需 env 门按本行 `requiredEnv ∪ requiredSecretEnv` 拒启)——
+  写 worker 的 k8s 行时 `runtime.execution.coords` 两键都要给,缺一键 ⇒ 写闸 issue、存下来的 workers 文档整域读不出。
 - `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
+  表[lane] 对应栏、必需键在场且非空白(空串或只含空白按缺);别车道键点名车道;`requirePrincipal` ∧ single-user-only 车道拒(出路按表现算);host ∧ 副本 > 1
   拒;device ⇒ SQL 店且 session ≠ memory;memory 店 ∧ session mysql 拒;记忆引擎 pg/tidb ∧ session memory 拒;SQL 坐标 ⇔ SQL 店;
   记忆后端配店;多租户 ⇒ SQL 店;6.x 删除项(`sessionBackend` / `memoryBackend` / `runtime.db` /
   `coords.tidb*` / `tidbPasswordEnv`)读到即拒并指路迁移。`WorkerSpec` 是 ZodEffects(无 `.shape`):名字判据单独导出 `WORKER_NAME`(src/types.ts)。

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-10-25 | 包版本: 14.7.0
+重写日期: 2026-10-28 | 包版本: 15.0.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、
@@ -52,7 +52,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   (src/config-fns.ts: `rebaseWarningPaths` / `EntrySalvageResult.keptIndex` / `GrandfatherHostsReadResult.keptIndex`)
 - **解析透明键登记表** `PARSE_TRANSPARENT_KEYS`(2.0.0):本包收下但**不校验其形**的键一处列全,每行写清
   谁校验(引擎摄入侧 / 消费方)。「解析透明」按**行为**定义(喂一组代表性值全收),所以 `extraBody` 不在表里
-  ——它有自己的形门(必须是纯 JSON 对象),开放的只是对象里的键名词表。今日 8 员:
+  ——它有自己的形门(必须是纯 JSON 对象),开放的只是对象里的键名词表。今日 10 员:
   `models.models[].compat`(1.10.0,镜像引擎 `OpenAICompletionsCompat` 五键 `thinkingFormat`/
   `reasoningEffortLevels`/`maxTokensField`/`requiresReasoningContentOnAssistantMessages`/
   `supportsReasoningEffort`;真需求 = vLLM/Qwen 类缺省开思考的网关要 `chat_template_kwargs.enable_thinking=false`,
@@ -60,7 +60,7 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   例 `{"anthropic-beta":"context-1m-2025-08-07"}`;头名闭集白名单 × 读它的线路 × 值形的判据唯一属主是 server,
   坏声明 ⇒ 该条目整条不可用;本包不复述那张表)、`mcp.servers[].source`(1.7.0,声明方自述的分组标签,开集,只做显示
   分组不进信任轴)、`mcp.servers[].toolFaces`(1.9.0,按远端工具名 key 的 face 覆盖层,形归引擎摄入侧)、
-  `mcp.servers[].toolAxes` / `authForm` / `entryKind`(12.2.0,连接器条目的三只声明键,本包只承载;`toolAxes` 的形判官 = 引擎 `readMcpToolAxes` 一只,另两键的语义归读它的消费方)、
+  `mcp.servers[].toolAxes` / `authForm` / `entryKind`(12.2.0,连接器条目的三只声明键,本包只承载;`toolAxes` 的形判官 = 引擎 `readMcpToolAxes` 一只,另两键的语义归读它的消费方)、`mcp.servers[].sessionMetaKey`(14.8.0,引擎往这台服务器请求 `_meta` 里放会话 id 的那把键;唯一判官 = 引擎根导出 `judgeSessionMetaKey`,本包只承载)、`mcp.servers[].startupTimeoutMs`(14.8.0,这一台服务器自己的启动界;唯一判官 = 引擎根导出 `mcpStartupTimeoutMs`,本包只承载)、
   `entitlement.subjects[].overrides[].value`。`compat`/`headers`/`extraBody` 仍走同一只自由形安全判据(secret 形/
   访问器/循环/非 JSON/过深 ⇒ 拒 —— 那是安全边界,不是形校验)。(src/types.ts: `PARSE_TRANSPARENT_KEYS`)
 - **`mcp.servers[].transport.assertionHeader`**(12.2.0 新增,http 形可选):承载连接器断言的 HTTP 头名,头名过 `principalHeader` /
@@ -69,6 +69,8 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
 - **`mcp.servers[].contentOrigin`**(1.4.0 新增):MCP 工具产出的信任出处声明,闭词表
   `MCP_CONTENT_ORIGINS = ["local","execution","external"]`(表外值 parse 拒,不做大小写折叠);缺席 = 引擎
   预声明行为。与 `source` 分轴:信任走它,显示分组走 `source`。(src/types.ts: `MCP_CONTENT_ORIGINS`)
+- **`mcp.servers[].startupTimeoutMs`**(14.8.0 新增,可选):这一台服务器自己的启动界(整数毫秒,握手与首次工具列举各带它;缺席读进程级缺省界)。解析透明、原样承运:
+  格式与界由引擎判 —— 唯一判官 = 引擎根导出 `mcpStartupTimeoutMs`,在拨号时判,不合 ⇒ 拒这一台服务器的拨号,本包不判。(src/types.ts: `McpServerSpec` / `PARSE_TRANSPARENT_KEYS`)
 - 把零散域**合并成一个 `EffectiveConfig`**(`buildEffective`,确定性:`updatedAt` 必传;`onWarning` 收
   降级/剥键/承运/未读文件五类告警),或在**消费端边界容错读 wire 载荷**(`readEffectiveWire`)。
   (src/config-fns.ts: `buildEffective` / `readEffectiveWire` / `EffectiveReadWarning`)
@@ -116,9 +118,13 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
 - **MCP 名单判决**(13.0.0):`mcpServerPolicyVerdict(server, layers)` → `McpPolicyBlock{name, list, rule, target, written, sources}` 或 `undefined`;
   判按展开后目标、回显只按展开前写法(stdio 只给可执行名 + 参数个数);托管层 = 源表档 `managed` 的源(层只带源名);只收紧的源只贡献拒绝名单(允许名单是拼接 = 放宽,不读)。(src/mcp-server-policy.ts)
 - **请求面 MCP 条目判官**(14.0.0,`src/mcp-request-entry.ts`):`isUsableWireName` / `describeBadWireName`(引擎线上名长界 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像;首尾空白 = 坏名,不 trim 不规范化,内部空白合法)·
+  `isUsableMcpServerName` / `describeBadMcpServerName`(MCP 服务器名 = 线上名判官再加一臂:`remote-` 前缀 `REMOTE_MCP_SERVER_NAME_PREFIX` 保留给设备执行端提供的远程 MCP 服务器,配置面 `McpServerSpec.name` 不拒(拒是校验收紧,归 major);A2A 对端名仍用 `isUsableWireName`)·
   `isContentOriginWord` / `describeBadContentOrigin`(回显剥控制与双向字符、截 64 字、引号形)· `readMcpIdentityHeaders` · `readRequestMcpTransport`(硬坏形 `ok:false` 点名键路径;软坏形读器丢键并记进 `lost`;
   `env` / `headers` 只收纯数据的「名 → 串」记录,`Map` / 类实例 / 自有 `__proto__` 成员不收、交副本,`lost` 条目带 `member` / `fault` 机读位)
   + 值种类描述件 —— 服务端请求腿与壳的发送前预检同读一份(判据与原因句逐字同)。`toolFaces` 声明在本包解析透明,形归引擎摄入侧判,本包不镜像工具面词表。
+- **中心引用解析口**(`src/center-refs.ts`):`resolveCenterRefs(refs, lookup)` —— `refs` = 名册里 `envRefs` / `headerRefs`(目标键 → 变量名;`undefined` = 没声明),`lookup(name) => string | undefined` 由调用方给(必给;没给 ⇒ `TypeError`,本包不读 `process.env`)。
+  每成员一句判定 `resolved` / `missing_name` / `not_a_string` / `read_threw`(`CENTER_REF_FAULTS`),整台 `resolved` / `unresolved` / `refs_unreadable`(`CENTER_REFS_VERDICTS`);值只在 `resolved` 臂的 `values`,`unresolved` 臂的行只有词;只判不决定挂不挂。
+  引用表经公开记录读器 `readPlainStringRecord`(`PLAIN_STRING_RECORD_FAULTS` 三词:`not_plain_record` / `member_not_string` / `member_name_reserved`)读,读不出整张不交、一个变量都不问。读法见 `docs/CONSUMER-INTEGRATION.md` §14。
 - **一行回显的剥除集**(`src/control-and-bidi.ts`,主 barrel):`CONTROL_AND_BIDI_CHARS`(C0 + DEL + 12 个 `Bidi_Control` 码点,正则字符类体的源码文本)·
   `stripControlAndBidi(text)` · `hasControlOrBidi(text)`;外来串落成一行(拒句 / 告警 / 日志 / 屏上)前剥的唯一一份,C1 与 U+2028 / U+2029 不在集里;
   是本包的回显策略(不是引擎双向码点表的镜像),请求面描述器与消费方都读它,禁自存字符类。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "14.7.0",
+  "version": "15.0.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",
@@ -148,7 +148,7 @@
     "prepublishOnly": "npm run build && npm run test"
   },
   "devDependencies": {
-    "@sema-agent/core": "7.53.0",
+    "@sema-agent/core": "7.58.0",
     "@types/node": "^22.10.0",
     "esbuild": "^0.21.5",
     "typescript": "^5.7.0",