@sema-agent/settings-schema 1.10.0 → 2.0.0

package/dist/types.js

@@ -6,10 +6,10 @@
  *
  * Detail level is deliberate (the user asked for "详略设计"): `models` is the MVP — fully specified —
  * while `scenarios` / `runtime` carry a real-but-skeletal schema to be fleshed out in later phases
- * (see docs/ROADMAP.md; `integrations`/`access` were deleted in 0.6.0, EXPERT-REDESIGN §9). Adding a
+ * (see CHANGELOG.md; `integrations`/`access` were deleted in 0.6.0, EXPERT-REDESIGN §9). Adding a
  * field is: extend the zod schema here → the form + the effective-config API pick it up.
  *
- * ⚠️ SECURITY BOUNDARY (see docs/SERVICE-INTEGRATION.md): the config center stores **non-secret**
+ * ⚠️ SECURITY BOUNDARY (see the service-integration design note): the config center stores **non-secret**
  * config only. A model's API key / a backend token is NEVER stored here as a value — we store the NAME
  * of the env var that holds it (`apiKeyEnv`, `tokenEnv`), and the agent-service reads the real secret
  * from its own environment. So a leak of this DB never leaks a credential. This is **enforced** by the
@@ -220,8 +220,7 @@ export function extraBodyUnsafe(v) {
  *      serialization and persist another (the pre-R10 superRefine+transform stringified TWICE).
  *
  *  `field` only NAMES the field in the message — it never changes the judgment. What this does NOT do is validate
- *  SHAPE: a field's shape/vocabulary is the consumer's single point (1.7.2 / 1.9.0 rule), and this domain parses
- *  all-or-nothing, so a shape rejection here would blank the whole catalog. */
+ *  SHAPE: whose job that is, per key, is {@link PARSE_TRANSPARENT_KEYS}. */
 function vetFreeFormJson(v, field) {
     let rawUnsafe;
     try {
@@ -294,6 +293,56 @@ export const SealedApiKey = z.object({
      *  解密不依赖它,非 center 写面(本地 TOC 手写配置)缺省合法。 */
     setAt: z.string().min(1).optional(),
 });
+/**
+ * **解析透明键登记表** —— 本包收下但**不校验其形**的键,一处列全,连同「谁校验」。
+ *
+ * 成案:1.7.0 / 1.7.1 连着两次,在一个展示用的键上设形判据,让一条坏值抹掉了**整域**(彼时整域
+ * all-or-nothing);此后的缓解是逐键改成 `z.unknown()` 并在各自的 JSDoc 里**各复述一遍**同一段理由 ——
+ * 五行同义散文 ×3,没有任何一处能回答「一共有几个这样的键、分别归谁校验」。那正是「修法给每个新键加一条
+ * 特判」的形。这张表把那段理由收成一处:键在这里登记,JSDoc 只留一行指过来。
+ *
+ * 1.11.0 起整域 all-or-nothing 已按类改成逐条容错(坏条目逐条丢、同域其余条目存活),所以「设形判据
+ * 会抹掉整域」这条**理由本身已经弱化** —— 但登记表要回答的问题没变:这些键的形归谁校验。新键要不要
+ * 解析透明,按「本包是不是那张形表的属主」判,不再按「怕连坐」判。
+ *
+ * 「解析透明」按**行为**定义(不按 schema 的形名):喂一组有代表性的值全收 = 本包对它的形没有任何主张。
+ * 所以 `ModelEntry.extraBody` **不在**本表里 —— 它有自己的形门(必须是纯 JSON 对象,要摊进请求体);
+ * 它开放的只是对象里的键名词表(各家 provider 的请求参数表),那是另一回事,写在它自己的 JSDoc 里。
+ *
+ * 门:`test/parse-transparent-keys.test.ts` 从 `DOMAIN_SCHEMAS` **派生**出所有解析透明的叶子,与本表
+ * 双向对拍 —— 多登记一行(键已经不透明了)红,少登记一行(新键静默溜进来)也红;派生遇到不认识的
+ * schema 形 fail-loud,不「没认出来就当没有」。
+ */
+export const PARSE_TRANSPARENT_KEYS = [
+    {
+        domain: "models",
+        path: "models[].compat",
+        since: "1.10.0",
+        validatedBy: "engine-ingest",
+        why: "镜像引擎的 per-model wire-compat 声明(thinkingFormat 等五键);那张词表随引擎走,本包复述一份必漂。",
+    },
+    {
+        domain: "mcp",
+        path: "servers[].source",
+        since: "1.7.2",
+        validatedBy: "consumer",
+        why: "声明面的分组标签,开放集(部署方自己的词同样合法);标签规则(非空、≤80 字)只在消费方的投影处一处,它丢坏标签的键、保留服务器本身。",
+    },
+    {
+        domain: "mcp",
+        path: "servers[].toolFaces",
+        since: "1.9.0",
+        validatedBy: "engine-ingest",
+        why: "按远端工具名 key 的 face 覆盖层,形归引擎摄入侧(不合 schema 的工具不挂并通告一次);本包复述那张表必漂。",
+    },
+    {
+        domain: "entitlement",
+        path: "subjects[].overrides[].value",
+        since: "0.6.x",
+        validatedBy: "consumer",
+        why: "它的形由同一条 override 的 `key` 决定(一个 key 一种形),执法点在读那个 key 的消费方;在这里写死形等于把所有可覆盖键的形表搬进本包。",
+    },
+];
 export const ModelEntry = z.object({
     /** Catalog key + `@name` mention handle (stable, url/word-safe), e.g. "model-a". */
     name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
@@ -343,7 +392,9 @@ export const ModelEntry = z.object({
     // before our check). The getter-free descriptor walk (extraBodyUnsafe) validates the RAW value without
     // invoking any getter; a Proxy that fakes its descriptors is caught by re-scanning the JSON clone; and the
     // .transform persists that CLONE (concrete plain JSON) so a non-idempotent toJSON can't differ at persist.
-    // Round 2-5 hardening.
+    // Round 2-5 hardening. NOT in {@link PARSE_TRANSPARENT_KEYS}: this key DOES have a shape gate here (it must
+    // be a plain JSON object — it is spread into a request body). What is open is the KEY VOCABULARY inside that
+    // object: those are each provider's request params, and this package is not their owner.
     extraBody: z
         .unknown()
         .optional()
@@ -371,17 +422,13 @@ export const ModelEntry = z.object({
      *  gateway that thinks by DEFAULT can only be turned off with `chat_template_kwargs.enable_thinking=false`,
      *  which `extraBody` cannot carry (the engine reserves those request keys) — and without this key a catalog
      *  entry that declares it is stripped at parse, so the declaration never reaches the engine at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
      *
-     *  **Parse-transparent** (`z.unknown()`), same rule as `McpServerSpec.source` (1.7.2) and `.toolFaces` (1.9.0):
-     *  the SHAPE and the VOCABULARY (which `thinkingFormat` words exist) are the consuming side's single point —
-     *  this package deliberately does NOT restate that table. This domain parses all-or-nothing, so a shape/word
-     *  rejection HERE would blank the entire model catalog over one bad key (the 1.7.1 upgrade regression). ABSENT
-     *  = key not minted = today's behaviour, zero migration.
-     *
-     *  The ONE rejection that remains is the free-form SAFETY judgment shared with `extraBody`
-     *  ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too deep to hash
-     *  later. That is not shape validation — it is the boundary every free-form value must clear to enter the
-     *  persisted config and `stableHash` (R18). */
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].compat`). The ONE rejection that remains is the free-form SAFETY judgment shared with
+     *  `extraBody` ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too
+     *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
+     *  enter the persisted config and `stableHash` (R18). */
     compat: z
         .unknown()
         .optional()
@@ -510,11 +557,11 @@ export const ModelsConfig = z
         ctx.addIssue({ code: z.ZodIssueCode.custom, message: `activeTierGroup "${cfg.activeTierGroup}" is not a tier group name`, path: ["activeTierGroup"] });
     }
 });
-// ── Domain: rosters (per-worker model roster — docs/MULTI-ROSTER.md) ───────────
+// ── Domain: rosters (per-worker model roster — the multi-roster design note) ───────────
 // A named VIEW over the global `models` catalog: which models a worker exposes + its role map + @-allowlist.
 // A worker references one by name (WorkerSpec.roster); GET /effective?worker=<name> resolves it. Models stay
 // single-sourced in the `models` domain — a roster only references them by name (cross-domain ref checked at
-// resolution/PUT, see docs/MULTI-ROSTER.md §6). This is what lets one sema-registry serve heterogeneous
+// resolution/PUT, see the multi-roster design note §6). This is what lets one sema-registry serve heterogeneous
 // instances (OA vs review 各持异构模型) instead of a single global roster.
 export const RosterEntry = z.object({
     name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
@@ -545,7 +592,7 @@ export const RostersConfig = z
         seen.add(r.name);
         // intra-roster consistency: a role target / an @-allowlist entry pinned to a model NAME must be one
         // this roster exposes (when it's a subset). Cross-domain (the name exists in the catalog) is checked at
-        // PUT time — see MULTI-ROSTER.md. (Both layers matter: this catches subset-internal inconsistency even
+        // PUT time — see the multi-roster design note. (Both layers matter: this catches subset-internal inconsistency even
         // when models is the full catalog is left to the PUT check.)
         if (r.models.length) {
             const allowed = new Set(r.models);
@@ -587,6 +634,9 @@ export const ScenarioEntry = z.object({
     // registry field would become an ambiguous precedence channel」):配置域 prompt 单入口=center
     // prompts binding(scenario 维度);引擎 API 层 TaskSpec.systemPrompt 保留(不同层,勿混)。
     // 现网无用户直删;z.object 非 strict ⇒ 存量数据带 prompt 被 strip,parse 不炸。
+    // 落日(1.11.0):本条是**纯墓碑**(零代码,靠 strip 生效),没有要删的兼容码;它留在这里的唯一作用
+    // 是让下一个读到这段 schema 的人知道 `prompt` 这个名字曾经在这里、别再铸回来。0.19.0 起存量文档带
+    // 它会被 `unknown-keys-dropped` 点名,所以「还有人在写它」是可观察的,不靠记忆。
     enabled: z.boolean().default(true),
     notes: z.string().optional(),
 });
@@ -1026,6 +1076,8 @@ export const EntitlementOverride = z
     .object({
     principal: z.string().min(1),
     key: z.string().min(1),
+    /** The override's value — its SHAPE follows its `key`, so it is parse-transparent here and validated by
+     *  whoever enforces that key: {@link PARSE_TRANSPARENT_KEYS} (`entitlement.subjects[].overrides[].value`). */
     value: z.unknown(),
     effectiveFrom: z.string().optional(),
     effectiveUntil: z.string().optional(),
@@ -1282,10 +1334,11 @@ export const ExecutionPolicy = z.object({
 /** projectId 形状:lowercase 规范 UUID。**宽读严写**(core 口径):读面/claim 收 generic
  *  UUID(外部/历史铸造的 v4 也认——marker 是身份不是格式声明);铸造侧(core formatProjectMarker /
  *  center mint 端点)统一产 **uuidv7**。36 字符,天然满足 design/142 §1.2 段编码 64 上限。
- *  SINGLE-SOURCE 纪律:core 1.268.0 尚未公开导出其内部 UUID_RE——本常量为自持镜像,与 core 的对拍
- *  走 dev-only conformance(never a runtime import,EffectiveKey/coreTypes 先例)。
- *  TODO(0.10.x): @sema-agent/core 下一班车公开导出 PROJECT_ID_REGEX 后(core 已承诺),
- *  加 dev-only drift-lock 测试与其对拍(坐标:test/projects-0.10.test.ts「conformance」节)。 */
+ *  SINGLE-SOURCE 纪律:本常量是引擎那条正则的**自持镜像**(本仓不带引擎运行时依赖轴),对拍走 dev-only
+ *  conformance(never a runtime import,EffectiveKey/coreTypes 先例)。
+ *  1.11.0:drift-lock 已建(`test/upstream-drift.test.ts` ③)—— pattern 必须与引擎逐字相同,唯一成文的差是
+ *  flags:本常量刻意**不带** `i`,因为它是登记簿 Record 的**键**,大小写不同的同一个 UUID 会变成两条登记行
+ *  (同一 project 双注册);引擎侧是识别语义(读 marker / 找回身份),放宽合理。 */
 export const PROJECT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export const ProjectRegistration = z.object({
     /** 人读名(展示/管理面用;不是身份,改名自由——身份=Record 键 projectId)。 */
@@ -1424,7 +1477,7 @@ export const CollabConfig = z.object({ templates: z.array(CollabTemplate).defaul
         seen.add(t.id);
     });
 });
-// ── Domain: workers (声明式编排 — service design/22, docs/ORCHESTRATOR.md) ──────
+// ── Domain: workers (声明式编排 — service design/22, the orchestrator design note) ──────
 // 每个 worker = 一个 worker 服务实例的声明（一份 env profile）。sema-registry 存 DESIRED（逻辑参数
 // + secret 的 env-NAME 引用，**绝不存 secret 值**）；一个 per-host reconciler 拉取后在宿主机本地解析
 // secret → 渲染 docker compose → up/down 收敛。worker spec ↔ service env 的精确映射见 worker-env.ts。
@@ -1653,12 +1706,12 @@ export const WorkerSpec = z.object({
         auto: z.boolean().default(false),
         requires: z.array(z.string().min(1)).default([]),
         /** SOFT anti-affinity group: auto workers sharing this key are spread across hosts when possible
-         *  (preferred, never blocks placement — design SCHEDULING.md). 不填 = 无 spread 约束。 */
+         *  (preferred, never blocks placement — the scheduling design note). 不填 = 无 spread 约束。 */
         spread: z.string().min(1).optional(),
     })
         .optional(),
     /**
-     * per-worker roster 引用 (docs/MULTI-ROSTER.md)。指向 `rosters` 域里一个命名 roster；该 worker 的 service 拉
+     * per-worker roster 引用 (the multi-roster design note)。指向 `rosters` 域里一个命名 roster；该 worker 的 service 拉
      * `GET /api/config/effective?worker=<name>` 时,sema-registry 用这个 roster 解析它专属的 models/roles/@白名单。
      * 不填 → 该 worker 拿全局 models（向后兼容）。**不进 `workerSpecHash`**（改 roster 只让 service 重拉、不重建容器）。
      */
@@ -1801,13 +1854,13 @@ export const HostStatus = z.object({
     /** 探测时刻(ISO)——机器视图 hover 注明数据口径与此时间(§2-5:是分配额口径的底数,非实时负载)。 */
     ts: z.string().min(1),
 });
-// ── Domain: skills (中心化 skill 分发 — docs/MCP-SKILLS.md, Roadmap B1) ─────────
+// ── Domain: skills (中心化 skill 分发 — the mcp/skills design note, Roadmap B1) ─────────
 // A skill is a prompt-level capability: frontmatter (name/description/scenarios) + markdown `content`
 // the service feeds into the agent's model context when the skill is invoked (core progressive disclosure
 // — NOT the base system prompt). Still centrally-delivered agent instructions. The center stores the FULL skill
 // (incl. content, admin-edited); /effective ships a MANIFEST (content → contentHash) and the service
 // lazily pulls the body by hash (slice 2). Targeting is by `scenarios[]`, filtered service-side exactly
-// like the in-image `skillsForScenario` (MCP-SKILLS.md §3.1, §6 Q2). Applied at service boot/reconcile,
+// like the in-image `skillsForScenario` (the mcp/skills design note §3.1, §6 Q2). Applied at service boot/reconcile,
 // NOT hot (restart-to-apply, same as models/roles). ⚠️ content is centrally-delivered agent instructions
 // (injected into the model on invoke) → writing this domain is gated to `publisher` + the publish gate
 // (§3.3, DOMAIN_WRITE_ROLE in store.ts).
@@ -1818,7 +1871,7 @@ export const SkillSpec = z.object({
     description: z.string().default(""),
     /** Scenarios this skill applies to; empty = all scenarios (service-side filter, same as skillsForScenario). */
     scenarios: z.array(z.string().min(1)).default([]),
-    /** Per-roster targeting (v2, docs/MCP-SKILLS.md §6 Q2): roster NAMEs this skill is for. Empty = all rosters.
+    /** Per-roster targeting (v2, the mcp/skills design note §6 Q2): roster NAMEs this skill is for. Empty = all rosters.
      *  Filtered at GET /effective?worker=<name> by the worker's roster; the unscoped global pull ships all. */
     rosters: z.array(z.string().min(1)).default([]),
     /** The markdown body injected into the model context on invoke (progressive disclosure). Stored in full here; shipped as a hash in /effective. */
@@ -1845,7 +1898,7 @@ export const SkillsConfig = z
 export const SkillsManifestSchema = z.object({
     skills: z.array(SkillSpec.omit({ content: true }).extend({ contentHash: z.string().min(1) })).default([]),
 });
-// ── Domain: mcp (MCP server 注册表 — docs/MCP-SKILLS.md, Roadmap B1) ────────────
+// ── Domain: mcp (MCP server 注册表 — the mcp/skills design note, Roadmap B1) ────────────
 // sema-registry = an MCP-server REGISTRY: a scenario mounts a subset by `scenarios[]`. Maps onto core's
 // `McpServerSpec = { name, transport: {kind:"stdio",command,args?,env?} | {kind:"http",url,headers?}, allowTools?, contentOrigin?, source? }`.
 // SECRET BOUNDARY (§3.1, design/15): a transport's env/header VALUES may be secret → the center stores only
@@ -1942,23 +1995,19 @@ export const McpServerSpec = z.object({
      *  consumer can group servers by where they were declared). An OPEN set: CC's `plugin` / `user` /
      *  `project` / `local` are conventions, not a vocabulary — a deployment's own word is equally legal, so
      *  no closed table here (a closed table would reject the operator's grouping word at parse). ABSENT =
-     *  no label (`.optional()`, no default — a label has no default tier). 🔴 ZERO rules here (`z.unknown()`):
-     *  the label RULE (string, non-empty, ≤80 chars) lives in ONE place — the consumer's projection helper,
-     *  which drops a malformed label's KEY, keeps the server and records the drop. Nothing may live here:
-     *  this domain parses all-or-nothing, so ANY rejection at parse (1.7.0 `min/max`, 1.7.1 `z.string()`
-     *  against a `null`) lets one bad label default the ENTIRE mcp domain — every server gone, silently when
-     *  no onWarning is wired — a blast radius a display label must never have. 1.7.2 makes the key
-     *  parse-transparent: whatever JSON value the file carries reaches the consumer verbatim. Display-only:
-     *  no gate / policy / trust
-     *  effect (the trust axis is `contentOrigin` above, which stays a closed table). Before this key existed
-     *  both legs stripped it (default-strip object); this is the declaration half of the consumer-side fix
-     *  (ticket B-036 / S-143), the projection half lives in the consumer. */
+     *  no label (`.optional()`, no default — a label has no default tier). Display-only: no gate / policy /
+     *  trust effect (the trust axis is `contentOrigin` above, which stays a closed table). Before this key
+     *  existed both legs stripped it (default-strip object); this is the declaration half of the
+     *  consumer-side fix, the projection half lives in the consumer.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`mcp.servers[].source`). */
     source: z.unknown().optional(),
-    /** 1.9.0 —— core 7.8.0(design/388 片 1 F7)`toolFaces` 覆盖层:按远端工具名 key 的 face 声明
+    /** 1.9.0 —— 引擎的 `toolFaces` 覆盖层:按远端工具名 key 的 face 声明
      *  (`{ family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }`)。
-     *  与 `source` 同一条规矩:**解析透明**(`z.unknown()`),形的校验属 core 摄入侧(不合 schema 的工具**不挂**并
-     *  通告一次 `config.tool_face_invalid`);本仓不复述那张表 —— 这一域 all-or-nothing,任一字段解析拒都会
-     *  让整套 mcp 服务器静默消失。缺席 = 不铸键。 */
+     *  缺席 = 不铸键。
+     *
+     *  **解析透明** —— 形归谁校验、为什么不放这里:{@link PARSE_TRANSPARENT_KEYS}(`mcp.servers[].toolFaces`)。 */
     toolFaces: z.unknown().optional(),
     notes: z.string().optional(),
 });
@@ -2196,7 +2245,7 @@ export const DOMAIN_SCHEMAS = {
 };
 // ── Effective-config PROVENANCE (the unified shape TOC `sema config --effective` and TOB `/effective?principal=`
 //    step-5 trace both emit, so "why is this value what it is" renders identically across both seats). Settled
-//    via the center control-plane design gate③ (docs/design/CENTER-CONTROL-PLANE-DESIGN.md §R2-T/§10). A pure
+//    via the center control-plane design gate③ (see the center control-plane design note §R2-T/§10). A pure
 //    CONTRACT type — no runtime dep on the engine; the axis VALUES (enforcement/lockBehavior) mirror @sema-agent/
 //    core's safety vocabulary, validated by a dev-only conformance test (never a runtime import).
 /** One provenance source in a key's resolution trail. Two orthogonal axes: the TOC file LAYER, or the TOB
@@ -2226,7 +2275,7 @@ export const EffectiveKey = z.object({
  *  rollback-able). Lets user changes share the one audit stream the Audit page already renders. */
 export const RBAC_AUDIT = "rbac";
 /** Audit category for secret write-through (value injected into the orchestrator secret source) — name + action
- *  ONLY, never the value (config_change.value=null), same discipline as RBAC_AUDIT. docs/SELF-SERVICE-FLEET.md §3. */
+ *  ONLY, never the value (config_change.value=null), same discipline as RBAC_AUDIT. See the self-service-fleet design note §3. */
 export const SECRETS_AUDIT = "secrets";
 // Single source: derived from DOMAIN_SCHEMAS (insertion order = menu order) so the two can't drift —
 // adding a domain to DOMAIN_SCHEMAS is enough. Object.keys preserves declaration order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "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",
@@ -118,6 +118,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "e2e": "node examples/toc-e2e.mjs",
+    "drift:cc": "node scripts/extract-cc-hook-events.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}\""