@sema-agent/settings-schema 14.3.0 → 14.5.0

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1339 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1351 个(同名在多条子路径上各计一次)。
 
-## `.`(662)
+## `.`(671)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -36,6 +36,7 @@
 - `COMMAND_DECISIONS` — value
 - `CONFIG_CHANGE_SOURCES` — value
 - `CONTROL_AND_BIDI_CHARS` — value
+- `CREDENTIAL_PARAM_NAMES` — value
 - `CROSS_SESSION_INBOUND_UNSET` — value
 - `CROSS_SESSION_INBOUND_VALUES` — value
 - `CancelSource` — value+type
@@ -55,6 +56,7 @@
 - `ConfigChangeHookInput` — value
 - `ConfigPath` — type
 - `ConfigReader` — type
+- `CredentialParamName` — type
 - `CrossSessionInboundSetting` — value
 - `CrossSessionInboundSettingValue` — type
 - `CrossSessionInboundValue` — type
@@ -479,10 +481,13 @@
 - `TokenScopeRefusal` — type
 - `UI_LANGUAGE_SETTING` — value
 - `UI_LANGUAGE_VALUES` — value
+- `URL_CREDENTIAL_REASONS` — value
 - `USER_ROLES` — value
 - `UiLanguageSetting` — value
 - `UiLanguageSettings` — value+type
 - `UiLanguageValue` — type
+- `UrlCredential` — type
+- `UrlCredentialReason` — type
 - `UsageEntry` — value+type
 - `UsageReport` — value+type
 - `User` — type
@@ -548,6 +553,8 @@
 - `emptyEffective` — value
 - `extraBodyUnsafe` — value
 - `findSkillContent` — value
+- `findUrlCredential` — value
+- `findUrlUserinfo` — value
 - `fnv1a64` — value
 - `formatConfigPath` — value
 - `hasControlOrBidi` — value
@@ -563,6 +570,7 @@
 - `isAtLeast` — value
 - `isCanonicalGeneration` — value
 - `isContentOriginWord` — value
+- `isCredentialParamName` — value
 - `isDisclosableIdentity` — value
 - `isDomainName` — value
 - `isHierarchicalUrl` — value
@@ -663,6 +671,7 @@
 - `toVerifiedIdentity` — value
 - `trustRank` — value
 - `urlAllowPatternMatches` — value
+- `urlCredentialRule` — value
 - `urlDenyPatternMatches` — value
 - `urlQueryFragmentHasSecret` — value
 - `verifyScopedToken` — value
@@ -1060,17 +1069,19 @@
 - `resolveMemberAdmission` — value
 - `trustRank` — value
 
-## `./node`(36)
+## `./node`(39)
 
 - `ConfigBundle` — type
 - `ConfigDirectoryDocument` — type
 - `ConfigDirectoryIo` — type
 - `ConfigDirectoryMigration` — type
 - `ConfigDirectoryRefusal` — type
+- `ConfigDocumentsMigration` — type
 - `DomainReadError` — type
 - `FileConfigStore` — value+type
 - `LocalConfig` — type
 - `MigrateConfigDirectoryOptions` — type
+- `MigrateConfigDocumentsOptions` — type
 - `NON_DOMAIN_CONFIG_FILES` — value
 - `NON_PORTABLE_DOMAIN_REASONS` — value
 - `PORTABLE_DOMAINS` — value
@@ -1088,6 +1099,7 @@
 - `loadRemoteExec` — value
 - `loadSchedulerStore` — value
 - `migrateConfigDirectory` — value
+- `migrateConfigDocuments` — value
 - `mutateSchedulerStore` — value
 - `nodeConfigDirectoryIo` — value
 - `readBundle` — value

package/docs/CONSUMER-INTEGRATION.md

@@ -234,6 +234,8 @@ server 直接拒启,不是静默降级。上一代 `SEMA_REGISTRY_*` 八名(`URL
 - **本地 `config.d` 的一次性迁移(引擎起服)**:调 `@sema-agent/settings-schema/node` 的 `migrateConfigDirectory(dir, { documents, io: nodeConfigDirectoryIo })`,`documents` 填你本地读腿会读的域名集
   (覆盖面外的文件不读不判不写不删;要迁 retired 的 `runtime` 域就得把 `governance` 与 `limits` 一并放进来 —— 迁出的旧值要写那两份,缺了 `runtime` 按 `partial` 拒迁、一字不写);按返回的 `kind` 穷举处置(`applied` / `noop` / `pending` / `refused` / `no-documents` / `unreadable`)。**别按同语义自写**读目录、迁、整域终判、原子写、删退役域文件那一串 ——
   命令行 `migrate` 与这只函数同一份实现;写盘用的就是本包那一只原子写器(契约文档新建 0o644、已有的沿用原模式、符号链接保留)。
+  手里已有存量文档原文、不经目录的消费方(例:命令行壳按层读 `settings` 里的 models 域,要的是「引擎起服那一次迁移之后这份文档整域读不读得进」)调同一个内核的同步口 `migrateConfigDocuments(docs, { documents })`(14.5.0,`./node`):
+  同一个闭集的无 io 形(`refused` ⇒ 引擎同样不写回、整域落缺省;**反向不成立** —— 引擎对整个目录一判,别的文档被拒也会让整目录不写,单层单域的 `noop` / `migrated` 不保证引擎那一次放行;`docs` 是壳的写手要的迁移后那一份)。一层一次调用;**别自己把 `migrateStoredDocuments` 与 `parseDomain` 按这个顺序再组装一遍**。
 - **会话网页链接**:要给用户一个 web-admin 里的会话链接,调 `webAdminSessionUrl(webBaseUrl, { worker, sessionId })`(`webBaseUrl` 取引擎 `/health` 自报的人用界面根 URL,
   `worker` 取引擎向 web-admin 登记用的 worker 名),得到 `<webBaseUrl>/chat?agent=<worker>&session=<sessionId>`;**别按地址形手拼** —— 路由属于 web-admin,模板与读回的
   `parseWebAdminSessionUrl(link)` 同在本包,路径与参数名只此一份。两位必填:只带 `session` 的链接会落到页面自己挑的 worker 上、可能找不到会话。

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-10-21 | 包版本: 14.3.0
+重写日期: 2026-10-23 | 包版本: 14.5.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -105,6 +105,7 @@ registry:公网 npmjs,无需私有 registry 配置。
 --- 6.4.0:`ModelEntry.headers?`(`z.unknown().optional()` 解析透明,无默认;与 `compat` 同一只变换 —— 缺席不铸键,其余只过与 `compat`/`extraBody` 共用的 `vetFreeFormJson` 安全判据,拒句同形只换字段名;登记在 `PARSE_TRANSPARENT_KEYS`,`validatedBy: "consumer"`)——部署 ↔ 供应商的 per-model 附加请求头,例 `{"anthropic-beta":"context-1m-2025-08-07"}`(开 1M 上下文);头名闭集白名单 × 读它的线路 × 值形的判据**唯一属主是 sema-server**(坏声明 ⇒ 该条目整条不可用,不是丢头照常),本包刻意不做形校验(字符串 / 数组 / 大小写不规范的名 / 白名单外的名一律逐字过,由 server 判)。修前(≤6.3.0)每条读腿都剥它并报 `unknown-keys-dropped` ---
   · rosters:`RosterEntry[]`(`primaryModel`/`cheapModel` 标记角色;`ROSTER_PRIMARY_ROLES`/`ROSTER_CHEAP_ROLES`)。
   · skills:`SkillSpec[]`(content 全文;wire 转 manifest 见 §4.5)。
+--- 14.4.0:`SkillSpec.allowedTools?` / `disallowedTools?`(`string[]`,元素非空串;与引擎本地 `.sema/skills` 清单同名同形)—— 逐条按作者所写承运:不去重 / 不排序 / 不判拼写(本包只判「非空字符串」);缺席 = 键不出现,在场 = 整只数组交给消费方的判官(`[]` 与缺席是两种承运形,读成什么由判官定;引擎本地目录把空名单读作未声明);manifest 由 `SkillSpec` 派生,两键自动随到 `/effective` 的 `skills[]`;读腿的逐条容错对它们与 `scenarios` / `rosters` / MCP `allowTools` 同一条律:坏元素逐元素丢并告警 `entry-dropped`(坐标到元素 `skills[i].<名单>[j]`),整只名单全坏 ⇒ 整条技能丢(告警 `skills[i]`;域里没有任何技能幸存 ⇒ 不发 `entry-dropped`、只发既有的 `domain-defaulted`);所以读腿上带坏元素的 `disallowedTools` 会被截短、技能照装(告警是响的),限度与消费方的处置见 CHANGELOG 该条。
   · 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 =
@@ -495,6 +496,18 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
   语义 = 命令行 `migrate` 的那一条(读目录 → 迁 → 整域终判 → 先写后删 → 原子写),命令行是它的渲染器;`documents` = 调用方读的域名集(覆盖面外不读不判不写不删;拼错的名字抛 `TypeError`;
   迁 retired 的 `runtime` 要把 `governance` 与 `limits` 一并放进覆盖面,否则 `runtime` 按 `partial` 拒迁、一字不写;迁移新建覆盖面外的文档 ⇒ 抛);
   `io: ConfigDirectoryIo`(`readDir` / `readFile` / `writeFileAtomic` / `removeFile`),真绑定 `nodeConfigDirectoryIo`(本包唯一的原子写器,`config-document` 模式规则;域文件是符号链接则写到真文件);写盘阶段的 I/O 错误原样抛出。
+- 同步单口(14.5.0,`./node`):`migrateConfigDocuments(docs, { documents })` → `ConfigDocumentsMigration`(闭集 `kind`:`unreadable`〔覆盖面内某份文档不是 JSON 对象 ⇒ 不抛;`document` + `reason`〕· `no-documents` ·
+  `refused`〔同目录形的 `refused[]` + `why`,另带 `docs` = 迁移后的那一份〕· `noop`〔`docs` 每份都是入参的同一引用;没改的文档不终判〕· `migrated`〔`docs` 迁移后的覆盖面内文档全集 + `applied` + `changed` + `removed`〕)。
+  与目录形同一个内核(读目录之后的「迁 → 整域终判」只此一处),`documents` 的律(覆盖面外不读不判不进结果、拼错的名字抛 `TypeError`、`runtime` 要把 `governance` / `limits` 放进覆盖面)逐字同;入参不被改,重跑 `docs` ⇒ `noop`;一层一次调用(层序 / 覆盖 / 托管锁的合并读法不在这里)。
+
+--- 4.11b URL 内嵌凭据判官(主 barrel,14.5.0;src/url-credential.ts) ---
+- `findUrlCredential(raw)`:URL 里的凭据 = 日志脱敏器已经在用的定义 —— userinfo(只有用户名也算;判由 `httpUrlFlaws(raw, ["userinfo"])`),或 query / fragment 里名字整名在 `CREDENTIAL_PARAM_NAMES`(23 词,小写 ASCII)上的参数
+  (名字按收方的读法读:`URLSearchParams` 解一次码,ASCII 大小写不敏感,不做 Unicode 折叠;复合名如 `db_password` 今天不是凭据名)。答首个命中(userinfo → query → fragment):`{ reason: "url_userinfo" }` 或
+  `{ reason: "url_credential_param", at: "query" | "fragment", name }`(`name` = 表里的词,小写);值从不进答案;不透明形 / 解析不了 / 非层级式 ⇒ `undefined`(这一形收不收是座位自己的律)。`findUrlUserinfo` = 判官的第一问;
+  `isCredentialParamName(decodedName)` = 名字判定;`urlCredentialRule(hit)` = 规则句(userinfo 与 `httpUrlRule("userinfo")` 同一句;参数句点名段与表词);`URL_CREDENTIAL_REASONS` = 拒因词闭集 `url_userinfo` / `url_credential_param`。
+- 与 `NON_SECRET_URL` 是两个问题、互补(不是一个包含另一个):本判官按参数**名**判,`NON_SECRET_URL` 按**值形**判密钥(`?key=abc` 它放行、本判官命中;`?x=sk-live-…` 反之);存量域文档位读后者。
+- 判官只判有没有,载体律留在座位:同一个键在新提交门拒、在续跑重放存量体的腿不拒、部署 env 只因 userinfo 拒 —— 所以它没有接进任何读已落盘 / 重放字节的 schema 或读器;拒体的形(HTTP 码、字段坐标、出路句)是座位自己的铸点。
+  凭据名表另有一份在服务端日志脱敏器里(带自由文本锚强度一列):消费方把它的表键钉在 `CREDENTIAL_PARAM_NAMES` 上(`Record<CredentialParamName, …>` 穷尽映射),加 / 删词不同步即编译红。
 
 --- 4.12 迁移工具(主 barrel) ---
 - 0.5 → 0.7 的迁移工具(`./migrate` 出口:hosts grandfathering、worker.model 归并计划 / 执行 / diff 门、teams → collab)

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-10-21 | 包版本: 14.3.0
+重写日期: 2026-10-23 | 包版本: 14.5.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、
@@ -150,6 +150,8 @@ llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
   (src/web-admin-credential.ts)
 - **目录形一次性迁移**(`./node`):`migrateConfigDirectory(dir, { documents, io, check? })` —— 命令行 `migrate` 背后的唯一实现(读目录 → 迁 → 整域终判 → 原子写 → 删退役域文件);`documents` = 调用方读的域名集(覆盖面外的文件不读不判不写不删),
   `io` 注入四个口,真绑定 `nodeConfigDirectoryIo`(node:fs + 唯一的原子写器);返回闭集 `unreadable` / `no-documents` / `refused` / `noop` / `pending` / `applied`。(src/config-dir-migration.ts · src/config-dir-io.ts)
+- **同步单口**(`./node`,14.5.0):`migrateConfigDocuments(docs, { documents })` —— 手里已有存量文档原文(文档名 → 文档)时,「迁 → 整域终判」一次调用、无 io,与目录形同一个内核同一个闭集的无 io 形:`unreadable`(覆盖面内某份不是 JSON 对象 ⇒ 不抛,点名 `document`)/ `no-documents` / `refused`(`docs` 仍交回迁移后的那一份)/ `noop`(同一引用)/ `migrated`(`docs` + `applied` + `changed` + `removed`)。一层一次调用,层的合并不在这里。(src/config-dir-migration.ts)
+- **URL 内嵌凭据判官**(包根,14.5.0):`findUrlCredential(raw)` —— userinfo,或 query / fragment 里名字整名在凭据名表 `CREDENTIAL_PARAM_NAMES`(23 词)上的参数 ⇒ `{ reason: "url_userinfo" }` / `{ reason: "url_credential_param", at, name }`,首个命中、值不进答案,不透明 / 解析不了 ⇒ `undefined`;`findUrlUserinfo`(第一问)· `isCredentialParamName` · `urlCredentialRule`(规则句)· `URL_CREDENTIAL_REASONS`(`url_userinfo` / `url_credential_param`)。判官只判有没有,载体律(新提交门拒 / 重放腿不拒 / 部署 env 只因 userinfo 拒)留在座位。(src/url-credential.ts)
 - **会话网页链接**:`webAdminSessionUrl(webBaseUrl, { worker, sessionId })` 铸 `<webBaseUrl>/chat?agent=<worker>&session=<sessionId>`(两位必填、逐位 `encodeURIComponent`、基址须是干净的绝对 http(s) URL 且尾斜杠折掉,
   坏输入抛、不铸半截链接)+ 配对解析 `parseWebAdminSessionUrl(link)`(绝对 / 相对串、`URL`、`URLSearchParams`;缺的那一位缺席)—— 路由与参数名只此一处,谁都别手拼。(src/web-admin-session-url.ts)
 - **按 scope 绑定的令牌**(`./api/pull-token`):形与铸法一条规则、令牌族是数据(`WORKER_PULL_TOKEN` = `wpt_` / `wpt2_` / `worker-pull`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "14.3.0",
+  "version": "14.5.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",
@@ -145,8 +145,7 @@
     "conformance:historical": "node scripts/conformance-historical.mjs",
     "api:surface": "node scripts/api-surface.mjs",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build && npm run test",
-    "publish:npm": "npm publish --access public --@sema-agent:registry=https://registry.npmjs.org/ --\"//registry.npmjs.org/:_authToken=${NPM_TOKEN}\""
+    "prepublishOnly": "npm run build && npm run test"
   },
   "devDependencies": {
     "@sema-agent/core": "7.53.0",