@sema-agent/settings-schema 6.3.0 → 7.0.0

package/dist/types.js

@@ -19,6 +19,8 @@ import { z } from "zod";
 import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody depth cap with the hash cap (R18)
 import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
 import { carriesUserinfo, percentLayers } from "./secret-scan.js"; // package-private normalization + the userinfo judgement (not in the barrel)
+import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
+import { LANE_ENV_OWNER, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (not in the barrel)
 // COARSE, best-effort literal-secret SHAPE detector (NOT exhaustive — the real boundary is the env-NAME schema
 // on structured fields). Rejected in free-form value fields (worker `env`, model `extraBody`), URL components,
 // AND as an env-NAME value (an AWS key id is a valid env-NAME charset yet is a secret VALUE, not a NAME). Case-
@@ -201,9 +203,9 @@ export function extraBodyUnsafe(v) {
     }
     return false;
 }
-/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`
- *  and `ModelEntry.compat` share this ONE function (1.10.0; before that it was inline in `extraBody` and a second
- *  free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
+/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`,
+ *  `ModelEntry.compat` and `ModelEntry.headers` share this ONE function (1.10.0; before that it was inline in `extraBody`
+ *  and a second free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
  *
  *   1. getter-free descriptor walk ({@link extraBodyUnsafe}) over the RAW value — never invokes a getter, and any
  *      reflective throw (a hostile Proxy trap could throw a secret-bearing message) collapses into a FIXED message;
@@ -234,10 +236,26 @@ function vetFreeFormJson(v, field) {
         return { ok: false, message: `${field}: its serialized form carries a secret` };
     return { ok: true, value: clone };
 }
+/** The transform of every **parse-transparent free-form** key (`z.unknown().optional().transform(createFreeFormTransform(field))`:
+ *  `ModelEntry.compat` / `ModelEntry.headers`) — ONE closure, so those keys cannot drift apart: absent stays absent (key not
+ *  minted); anything else is the {@link vetFreeFormJson} safety judgment and nothing more (no SHAPE rule — whose job that is,
+ *  per key, is {@link PARSE_TRANSPARENT_KEYS}). `extraBody` is not one of these: it has its own shape gate first. */
+function createFreeFormTransform(field) {
+    return (v, ctx) => {
+        if (v === undefined)
+            return undefined;
+        const vetted = vetFreeFormJson(v, field);
+        if (!vetted.ok) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
+            return z.NEVER;
+        }
+        return vetted.value;
+    };
+}
 /** A k8s resource quantity ("250m", "1", "0.5", "512Mi", "1Gi", "128M") — catches garbage at config-submit
  *  rather than surfacing as a reconcile ApplyError at the apiserver (consistent with ENV_NAME/DURATION guards). */
 export const K8S_QUANTITY = z.string().regex(/^\d+(\.\d+)?(m|[kKMGTPE]i?)?$/, 'must be a k8s quantity like "250m", "512Mi", "1Gi"');
-/** A TCP port: 1–65535. ONE shared schema so every port field (workers.coords.tidbPort, ssh.port, …) bounds
+/** A TCP port: 1–65535. ONE shared schema so every port field (workers.runtime.store.db.port, ssh.port, …) bounds
  *  the SAME way — a port of 65536/0/-1 is config corruption, reject it at validation, not at connect time. R16. */
 export const TCP_PORT = z.number().int().positive().max(65535);
 /** Per-1M-token price ($/Mtok). Maps to the service's MODEL_COST_INPUT/OUTPUT/CACHE_READ/CACHE_WRITE
@@ -313,6 +331,13 @@ export const PARSE_TRANSPARENT_KEYS = [
         validatedBy: "engine-ingest",
         why: "镜像引擎的 per-model wire-compat 声明(thinkingFormat 等五键);那张词表随引擎走,本包复述一份必漂。",
     },
+    {
+        domain: "models",
+        path: "models[].headers",
+        since: "6.4.0",
+        validatedBy: "consumer",
+        why: "部署 ↔ 供应商的 per-model 附加请求头;判据(头名闭集白名单 × 读它的线路 × 值形)的唯一属主是 server 的目录条目判据(坏声明 ⇒ 该条目整条不可用,不是丢头照常),本包复述一份那张表必漂、两处各一份就是两个写者。",
+    },
     {
         domain: "mcp",
         path: "servers[].source",
@@ -424,16 +449,20 @@ export const ModelEntry = z.object({
     compat: z
         .unknown()
         .optional()
-        .transform((v, ctx) => {
-        if (v === undefined)
-            return undefined;
-        const vetted = vetFreeFormJson(v, "compat");
-        if (!vetted.ok) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
-            return z.NEVER;
-        }
-        return vetted.value;
-    }),
+        .transform(createFreeFormTransform("compat")),
+    /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+     *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+     *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+     *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+     *  `extraBody` ({@link vetFreeFormJson}). */
+    headers: z
+        .unknown()
+        .optional()
+        .transform(createFreeFormTransform("headers")),
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.number().finite().nonnegative().default(1),
@@ -1297,8 +1326,9 @@ export const ExecutionPolicy = z.object({
      *  shell locks sandbox-enabled by policy; user settings can't turn it off — CC 同款语义). */
     required: z.boolean().default(false),
     /** Which execution lanes are allowed. OPEN value domain — z.string(), NEVER an enum: adding a lane
-     *  must not be a BREAKING schema change (promised to the service). Known lanes
-     *  today: `host` / `e2b` / `k8s` / `ssh` / `adb` / `local-docker`. Unknown strings are consumer-defined. */
+     *  must not be a BREAKING schema change (promised to the service). The closed set of lanes a worker can
+     *  declare is `EXECUTION_LANE_WORDS` (`execution-lanes.ts`, 7.0.0) — read it there, not from a copy in this
+     *  comment. Unknown strings are consumer-defined. */
     allowedLanes: z.array(z.string().min(1)).default(["host"]),
     /** Org 默认会话镜像目标(0.10.1,附B 两层)。ABSENT = INERT(center 未管镜像,壳解析序里本腿为空)。
      *  读损档随域(DOMAIN_READ_FALLBACK.execution="throw" 已覆盖:损坏绝不静默退默认放权)。 */
@@ -1500,61 +1530,181 @@ const WorkerSecretRefs = z.object({
     serviceAuthTokenEnv: ENV_NAME.optional(),
     /** → GIT_API_TOKEN (只读，读被评审 repo). */
     gitTokenEnv: ENV_NAME.optional(),
-    /** → TIDB_PASSWORD. */
-    tidbPasswordEnv: ENV_NAME.optional(),
+    /** 7.0.0:SQL 店的口令 → `MYSQL_PASSWORD` / `PG_PASSWORD`(渲染器按 `runtime.store.backend` 选名族)。
+     *  在场 ⇔ `runtime.store.backend` ∈ {mysql, pg}(WorkerSpec 层判,与 `runtime.store.db` 同一条规则)。取代 6.x 的 `tidbPasswordEnv`。 */
+    dbPasswordEnv: ENV_NAME.optional(),
 });
 /**
- * Env keys the structured WorkerSpec fields already produce (worker-env.ts) — the general `env`/`secretEnv`
- * passthrough may NOT set these (use the dedicated field). Blocks the council's two escape-hatch risks:
- * redirecting model/traffic or disabling auth (PORT, MODEL_x, SESSION_BACKEND, REQUIRE_PRINCIPAL, gateway), and
- * shadowing a projected secret with a literal (MODEL_API_KEY, SERVICE_AUTH_TOKEN, …). LOG_LEVEL is intentionally
- * NOT reserved (benign, overridable for debugging). Keep in sync with workerToServiceEnv.
+ * 每个**保留** env 名 → WorkerSpec 里产出它的那个结构字段(唯一写位)。`env` / `secretEnv` 逃生口拒这些名,拒因指路到这里写的字段
+ * (例:`K8S_SANDBOX_IMAGE` → `runtime.execution.coords.K8S_SANDBOX_IMAGE`)。{@link RESERVED_WORKER_ENV} 由本表的键**派生**,
+ * 不再是第二张要「保持同步」的手写表。
+ *
+ * 封堵逃生口的两类风险(council):改路由 / 关鉴权(PORT、MODEL_x、REQUIRE_PRINCIPAL、gateway)与用字面量遮蔽已投射的密钥
+ * (MODEL_API_KEY、SERVICE_AUTH_TOKEN …)。LOG_LEVEL 刻意不保留(无害,调试可覆盖)。
  *
- * ⚠️ SCOPE (0.1.30, after the R22→0.1.29 detour): this ONLY blocks keys that have a DEDICATED structured field
- * or secretRef — so an operator is steered to that field instead of duplicating/shadowing it via env. It does
- * NOT block the per-worker EXECUTION-SUBSTRATE config an operator legitimately sets via worker.env, which the
- * live fleet relies on: `REMOTE_EXEC` (direct=k8s, canary=e2b set it HERE), `K8S_*` (SANDBOX_IMAGE/NAMESPACE/
- * RUNTIME_CLASS/…), `E2B_*`, `MINIO_*`, `SSH_*`, `ADB_*`. worker.env is the OPERATOR's per-worker deployment env
- * (publisher-gated, projected by the orchestrator to the worker pod) — NOT untrusted-task-controlled, so there
- * is no "sandbox escape" to block here. R22 wrongly added those substrate keys treating worker.env as
- * task-controlled; it would have REJECTED the live direct/canary workers on deploy. Reverted in 0.1.30. (Literal
- * SECRET values pasted into env are still caught separately by containsSecretToken; substrate CREDS belong in
- * secretEnv as env-NAME refs.)
+ * 7.0.0 增删(M-R2 结构块):
+ *  · **加** `REMOTE_EXEC` / `REQUIRE_EXECUTION_LANE` + 车道表({@link EXECUTION_LANES})里**全部**车道 env 名 —— 车道有了结构位
+ *    `runtime.execution`,逃生口再能设车道就是两把尺。这是对 0.1.30「执行基座键不保留」的**反转**:当年不保留是因为没有结构位
+ *    (活舰队 direct = k8s、canary = e2b 只能在 `worker.env` 里设);存量行由一次性迁移 `migrateWorkersDomain` 搬进结构块。
+ *    别的域也读的名(`MINIO_*`、`LOG_LEVEL`、`REMOTE_EXEC_HOME_DIR`)不在车道表里,照旧不保留。
+ *  · **加** `DB_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND` —— `runtime.store` 产出它们。
+ *  · **删** `MEMORY_BACKEND`(引擎从不读的死名,渲染器不再产出)与 `TIDB_*` 族(引擎的墓碑名,见之拒启;结构字段不再产出它们 ——
+ *    墓碑名由引擎导出的墓碑表把关,不是本表的职责)。MYSQL_* / PG_* 两族归 `runtime.store.db` + `secretRefs.dbPasswordEnv`。
  */
-export const RESERVED_WORKER_ENV = new Set([
-    "PORT", "MODEL_PROVIDER", "MODEL_ID", "MODEL_REASONING", "MODEL_CHEAP_ID", "MODEL_MAX_TOKENS",
-    "MODEL_CONTEXT_WINDOW", "MODEL_COST_INPUT", "MODEL_COST_OUTPUT", "MODEL_COST_CACHE_READ",
-    "MODEL_COST_CACHE_WRITE", "MAX_PRINCIPAL_COST_USD", "SESSION_BACKEND", "MEMORY_BACKEND",
-    "REQUIRE_PRINCIPAL", "RATE_LIMIT_RPM", "DEFAULT_SCENARIO", "TIDB_DATABASE", "TIDB_HOST",
-    "TIDB_PORT", "TIDB_USER", "GIT_API_BASEURL", "MODEL_GATEWAY_BASEURL", "ANTHROPIC_BASEURL",
-    "MODEL_API_KEY", "ANTHROPIC_API_KEY", "SERVICE_AUTH_TOKEN", "GIT_API_TOKEN", "TIDB_PASSWORD",
-    // server ≥2.0 的中立后端面(kind mysql|pg|local):MYSQL_* 是首选族(TIDB_* 为其兼容别名)、PG_* 是
-    // 第三族——三族同为 coords 结构化字段的遮蔽面,缺任何一族=该族键可从 worker.env 静默压过结构化配置
-    // (2026-07-31 交叉终扫 G1 补齐;此前只列 TIDB_* 一族)。
-    "MYSQL_DATABASE", "MYSQL_HOST", "MYSQL_PORT", "MYSQL_USER", "MYSQL_PASSWORD",
-    "PG_DATABASE", "PG_HOST", "PG_PORT", "PG_USER", "PG_PASSWORD",
-]);
-// Which structured WorkerSpec field owns each reserved env-NAME → so a rejection names the RIGHT field to use
-// (e.g. TIDB_DATABASE → runtime.db, MODEL_ID → model.modelId), not a vague "use the structured field".
-const RESERVED_ENV_FIELD = {
+const RESERVED_ENV_FIELD = Object.freeze({
     PORT: "(fixed at 8090 — not configurable)", MODEL_PROVIDER: "model.provider", MODEL_ID: "model.modelId",
     MODEL_REASONING: "model.reasoning", MODEL_CHEAP_ID: "model.cheapId", MODEL_MAX_TOKENS: "model.maxTokens",
     MODEL_CONTEXT_WINDOW: "model.contextWindow", MODEL_COST_INPUT: "model.cost.input", MODEL_COST_OUTPUT: "model.cost.output",
     MODEL_COST_CACHE_READ: "model.cost.cacheRead", MODEL_COST_CACHE_WRITE: "model.cost.cacheWrite",
-    MAX_PRINCIPAL_COST_USD: "runtime.maxPrincipalCostUsd", SESSION_BACKEND: "runtime.sessionBackend",
-    MEMORY_BACKEND: "runtime.memoryBackend", REQUIRE_PRINCIPAL: "runtime.requirePrincipal", RATE_LIMIT_RPM: "runtime.rateLimitRpm",
-    DEFAULT_SCENARIO: "runtime.scenario", TIDB_DATABASE: "runtime.db", TIDB_HOST: "coords.tidbHost", TIDB_PORT: "coords.tidbPort",
-    TIDB_USER: "coords.tidbUser", GIT_API_BASEURL: "coords.gitApiBaseUrl", MODEL_GATEWAY_BASEURL: "model.gatewayBaseUrl",
-    // G1 补齐的两族与 TIDB_* 同归属(coords.tidb* 字段名是历史命名,承 mysql-协议三家;PG 同面)
-    MYSQL_DATABASE: "runtime.db", MYSQL_HOST: "coords.tidbHost", MYSQL_PORT: "coords.tidbPort", MYSQL_USER: "coords.tidbUser", MYSQL_PASSWORD: "secretRefs.tidbPasswordEnv",
-    PG_DATABASE: "runtime.db", PG_HOST: "coords.tidbHost", PG_PORT: "coords.tidbPort", PG_USER: "coords.tidbUser", PG_PASSWORD: "secretRefs.tidbPasswordEnv",
+    MAX_PRINCIPAL_COST_USD: "runtime.maxPrincipalCostUsd", REQUIRE_PRINCIPAL: "runtime.requirePrincipal", RATE_LIMIT_RPM: "runtime.rateLimitRpm",
+    DEFAULT_SCENARIO: "runtime.scenario", GIT_API_BASEURL: "coords.gitApiBaseUrl", MODEL_GATEWAY_BASEURL: "model.gatewayBaseUrl",
     ANTHROPIC_BASEURL: "model.gatewayBaseUrl", MODEL_API_KEY: "secretRefs.apiKeyEnv", ANTHROPIC_API_KEY: "secretRefs.apiKeyEnv",
     SERVICE_AUTH_TOKEN: "secretRefs.serviceAuthTokenEnv", GIT_API_TOKEN: "secretRefs.gitTokenEnv",
-    TIDB_PASSWORD: "secretRefs.tidbPasswordEnv",
-};
-export const WorkerSpec = z.object({
+    // ── runtime.store(7.0.0)
+    DB_BACKEND: "runtime.store.backend", SESSION_BACKEND: "runtime.store.session",
+    MEMORY_ENGINE: "runtime.store.memory.engine", MEMORY_ENGINE_BACKEND: "runtime.store.memory.backend",
+    MYSQL_HOST: "runtime.store.db.host", MYSQL_PORT: "runtime.store.db.port", MYSQL_USER: "runtime.store.db.user",
+    MYSQL_DATABASE: "runtime.store.db.database", MYSQL_PASSWORD: "secretRefs.dbPasswordEnv",
+    PG_HOST: "runtime.store.db.host", PG_PORT: "runtime.store.db.port", PG_USER: "runtime.store.db.user",
+    PG_DATABASE: "runtime.store.db.database", PG_PASSWORD: "secretRefs.dbPasswordEnv",
+    // ── runtime.execution(7.0.0):车道词两键 + 车道表里每个名(派生,不手抄)
+    REMOTE_EXEC: "runtime.execution.lane",
+    REQUIRE_EXECUTION_LANE: "runtime.execution.lane (the renderer emits REQUIRE_EXECUTION_LANE=true for every declared lane)",
+    ...Object.fromEntries([...LANE_ENV_OWNER].map(([name, owner]) => [name, laneEnvSeat(name, owner)])),
+});
+/** 结构化 WorkerSpec 字段已经产出的 env 名 —— 通用 `env` / `secretEnv` 逃生口**不许**设它们(用专属字段)。由
+ *  `RESERVED_ENV_FIELD`(名 → 唯一写位)的键派生;增删理由见那张表的头注。 */
+export const RESERVED_WORKER_ENV = new Set(Object.keys(RESERVED_ENV_FIELD));
+// ── 7.0.0 M-R2:`runtime.execution` / `runtime.store` 两个结构块 ─────────────────────────────────────────────
+// 词表只有一个正本(`execution-lanes.ts` 的导出表):本包写闸(`WorkerSpec.safeParse`)、中心渲染器、引擎起服三处读同一张表。
+// 拒因都在 zod issue 里(`path` 指到要改的字段、`message` 带出路)—— schema 本身是唯一判据,不另导出拒因函数。
+/** 一个非密字面值(车道坐标 / SQL 坐标):≤2048,不像密钥(与 `env` 逃生口同一条判据 —— 密钥走 env-NAME 引用)。 */
+const nonSecretLiteral = (minLength) => z
+    .string()
+    .min(minLength)
+    .max(2048)
+    .refine((s) => !containsSecretToken(s), "looks like a literal secret — a credential goes in a secretRefs field as an env-NAME, never a value here");
+/**
+ * `runtime.execution` —— 这台 worker 的执行车道(渲染:`REMOTE_EXEC=<lane>` + `REQUIRE_EXECUTION_LANE=true` + coords / secretRefs 逐键)。
+ *  - `lane`:{@link EXECUTION_LANE_WORDS} 之一。没有「无手」词。
+ *  - `coords`:该车道的**非密坐标**(服务变量名 → 字面值),键 ⊆ 表[lane] 的 `requiredEnv ∪ optionalEnv`;必需键在场且非空串
+ *    (引擎把空串读作未设)。可选键的空串照收(例:`K8S_RUNTIME_CLASS=""` 在引擎里是「不用 Kata」)。
+ *  - `secretRefs`:该车道的**密钥**(服务变量名 → 宿主 env-NAME),键 ⊆ 表[lane] 的 `requiredSecretEnv ∪ optionalSecretEnv`,必需键在场。
+ *  别车道的键 ⇒ 拒并点名它属于哪条车道;本车道的密钥写进 coords / 坐标写进 secretRefs ⇒ 拒并指路另一栏。
+ */
+const ExecutionBlock = z
+    .object({
+    lane: z.enum(EXECUTION_LANE_WORDS),
+    coords: z.record(ENV_NAME, nonSecretLiteral(0)).default({}),
+    secretRefs: z.record(ENV_NAME, ENV_NAME).default({}),
+})
+    .superRefine((x, ctx) => {
+    const row = laneRowOf(x.lane);
+    const issue = (slot, key, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [slot, key], message });
+    const owned = (secret) => (secret ? [...row.requiredSecretEnv, ...row.optionalSecretEnv] : [...row.requiredEnv, ...row.optionalEnv]);
+    const judgeKey = (slot, key) => {
+        const wantSecret = slot === "secretRefs";
+        const owner = LANE_ENV_OWNER.get(key);
+        if (owner === undefined) {
+            const allowed = owned(wantSecret);
+            issue(slot, key, `${key} is not ${wantSecret ? "a secret" : "a coordinate"} of any execution lane — lane "${x.lane}" takes ${slot} ${allowed.length > 0 ? allowed.join(", ") : "(none)"}`);
+            return false;
+        }
+        if (owner.lane !== x.lane) {
+            issue(slot, key, `${key} belongs to lane "${owner.lane}", not "${x.lane}" — remove it, or set runtime.execution.lane to "${owner.lane}"`);
+            return false;
+        }
+        if (owner.secret !== wantSecret) {
+            issue(slot, key, owner.secret
+                ? `${key} is a secret of lane "${x.lane}" — put it in runtime.execution.secretRefs as an env-NAME (never a value in coords)`
+                : `${key} is a non-secret coordinate of lane "${x.lane}" — write its value in runtime.execution.coords`);
+            return false;
+        }
+        return true;
+    };
+    for (const [key, value] of Object.entries(x.coords)) {
+        if (judgeKey("coords", key) && value === "" && LANE_ENV_OWNER.get(key)?.required === true) {
+            issue("coords", key, `required coordinate ${key} of lane "${x.lane}" is empty — the engine reads an empty value as unset and refuses to start`);
+        }
+    }
+    for (const key of Object.keys(x.secretRefs))
+        judgeKey("secretRefs", key);
+    for (const key of row.requiredEnv)
+        if (!Object.hasOwn(x.coords, key))
+            issue("coords", key, `lane "${x.lane}" requires coords.${key} (the engine refuses to start without it)`);
+    for (const key of row.requiredSecretEnv)
+        if (!Object.hasOwn(x.secretRefs, key))
+            issue("secretRefs", key, `lane "${x.lane}" requires secretRefs.${key} — the host env-NAME holding it`);
+});
+/** `MEMORY_ENGINE` 的两个词(引擎目录行的 `enumValues`;引擎还认 true/false/1/0… 两族同义词,结构位只收规范词)。 */
+const MEMORY_ENGINE_SWITCH = ["on", "off"];
+/** 店词 → 是不是 SQL 店。SQL 坐标(`runtime.store.db` + `secretRefs.dbPasswordEnv`)在场 ⇔ 是。穷举表:店词加词 ⇒ 编译红。 */
+const STORE_IS_SQL = { mysql: true, pg: true, local: false, memory: false };
+/** 记忆持久面方言 → 它要求的店(`file` 不要求)。穷举表:方言加词 ⇒ 编译红。 */
+const MEMORY_BACKEND_NEEDS_STORE = { file: undefined, pg: "pg", tidb: "mysql" };
+/**
+ * `runtime.store` —— 这台 worker 的持久化(取代 6.x 散落的 `sessionBackend` / `memoryBackend` / `db` / `coords.tidb*` /
+ * `secretRefs.tidbPasswordEnv`)。渲染(唯一写者):`DB_BACKEND` / `SESSION_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND` 恒渲;
+ * `backend` 为 mysql ⇒ `MYSQL_HOST/PORT/USER/DATABASE` + `MYSQL_PASSWORD`(← `secretRefs.dbPasswordEnv`),pg ⇒ `PG_*` 同形。
+ * 跨字段四条在 WorkerSpec 层判(要看 `secretRefs` 与 `requirePrincipal`)。
+ */
+const StoreBlock = z.object({
+    backend: z.enum(STORE_BACKENDS),
+    session: z.enum(SESSION_BACKENDS).default("auto"),
+    memory: z
+        .object({
+        engine: z.enum(MEMORY_ENGINE_SWITCH).default("on"),
+        backend: z.enum(MEMORY_ENGINE_BACKENDS).default("file"),
+    })
+        .default({}),
+    /** SQL 服务器坐标(中立,一份;名族由 `backend` 决定)。 */
+    db: z
+        .object({
+        host: nonSecretLiteral(1),
+        port: TCP_PORT,
+        user: nonSecretLiteral(1),
+        database: nonSecretLiteral(1),
+    })
+        .optional(),
+});
+/** 7.0.0 删除的字段 → 它的新位。**迁移窗口代码**:与 `migrateWorkersDomain` 同窗删除(只为未迁移的旧形读到即响亮拒,而不是被
+ *  zod 静默剥掉 —— 剥掉的话,一行旧数据会以「什么都没声明」的样子过闸)。 */
+const RETIRED_WORKER_FIELDS = [
+    { parent: "runtime", key: "sessionBackend", now: "runtime.store.session" },
+    { parent: "runtime", key: "memoryBackend", now: "runtime.store.memory — the old field never reached the engine" },
+    { parent: "runtime", key: "db", now: "runtime.store.db.database" },
+    { parent: "coords", key: "tidbHost", now: "runtime.store.db.host" },
+    { parent: "coords", key: "tidbPort", now: "runtime.store.db.port" },
+    { parent: "coords", key: "tidbUser", now: "runtime.store.db.user" },
+    { parent: "secretRefs", key: "tidbPasswordEnv", now: "secretRefs.dbPasswordEnv" },
+];
+/** 一个对象的**自有数据属性**值(不触发访问器;不是普通对象 ⇒ undefined)。 */
+function ownDataValue(obj, key) {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj))
+        return undefined;
+    const d = Object.getOwnPropertyDescriptor(obj, key);
+    return d !== undefined && "value" in d ? d.value : undefined;
+}
+function retiredWorkerFieldIssues(raw, ctx) {
+    for (const { parent, key, now } of RETIRED_WORKER_FIELDS) {
+        const container = ownDataValue(raw, parent);
+        if (container !== null && typeof container === "object" && !Array.isArray(container) && Object.hasOwn(container, key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [parent, key],
+                message: `${parent}.${key} was removed in 7.0.0 (now ${now}) — run the one-time migration before reading this document: migrateWorkersDomain(doc) ahead of parseDomain, or \`settings-schema migrate-workers <file>\``,
+            });
+        }
+    }
+    return raw;
+}
+/** 一台 worker 的名字(唯一 → 容器名 / compose project / 缺省路由键)—— **唯一**的名字判据。中心在租约 / 用量 /
+ *  discovery `?worker=` 等面上校验外部传来的 worker 名时读它(不抄窄正则)。7.0.0 起单独导出:`WorkerSpec` 不再是普通
+ *  对象 schema(预处理 + 跨字段判据),`WorkerSpec.shape.name` 不复存在。 */
+export const WORKER_NAME = z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces");
+const WorkerSpecObject = z.object({
     /** 唯一 → 容器名 / compose project. */
-    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces"),
+    name: WORKER_NAME,
     enabled: z.boolean().default(true),
     /** 目标宿主机 id —— 哪个 per-host reconciler 认领它. 与 name 同样严格(精确匹配路由,松校验会静默不可达). */
     host: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces").default("default"),
@@ -1614,17 +1764,12 @@ export const WorkerSpec = z.object({
     // 归宿=roster.primaryModel/cheapModel 标记(0.6.3,service 已承接)。pre-0.7 存量 JSON 里的
     // `model` 键被 parse 静默剥除(zod strips unknown)→ workerSpecHash 变化=一次性重建;迁移工具输入=
     // 冻结的 LegacyWorkerModel(migrate.ts),必须在升级 0.7 前跑完(a2 已闭环,E3)。
-    /** 运行时 (非 secret). 映射到 service SESSION_BACKEND/REQUIRE_PRINCIPAL/RATE_LIMIT_RPM/… */
+    /** 运行时 (非 secret). 映射到 service REQUIRE_PRINCIPAL / RATE_LIMIT_RPM / … 与两个结构块(7.0.0)。 */
     runtime: z.object({
-        // default "auto" (was "tidb" — Service AI's e2e-tag response traced the minimal-spec fatal here): the old
-        // default injected SESSION_BACKEND=tidb into EVERY spec that didn't set it, and the service fail-fasts on
-        // explicit tidb without TIDB_HOST (correct Tier-2 hardening — declared persistence must not silently
-        // degrade). "auto" = probe: with coords → tidb, without → memory, never fatal. A minimal `runtime:{}`
-        // worker now boots. No churn: previously-SAVED specs have "tidb" baked in (parseDomain persists defaults),
-        // so only NEW minimal specs see "auto"; explicit-"tidb" loud-fail semantics are untouched.
-        sessionBackend: z.enum(["tidb", "memory", "auto"]).default("auto"),
-        memoryBackend: z.enum(["off", "memory", "tidb"]).default("off"),
-        db: z.string().optional(), // TIDB_DATABASE (独立库)
+        /** 7.0.0 执行车道块(见 `ExecutionBlock`)。enabled 的 worker 必填(WorkerSpec 层判);停用的可缺。 */
+        execution: ExecutionBlock.optional(),
+        /** 7.0.0 存储块(见 `StoreBlock`)。enabled 的 worker 必填(WorkerSpec 层判);停用的可缺。 */
+        store: StoreBlock.optional(),
         scenario: z.string().optional(), // DEFAULT_SCENARIO
         requirePrincipal: z.boolean().default(false),
         rateLimitRpm: z.number().int().nonnegative().default(0),
@@ -1635,13 +1780,10 @@ export const WorkerSpec = z.object({
          *  default → absent never materialises → no spec-hash churn. Hash-included (read at boot → cap change recreates). */
         maxPrincipalCostUsd: z.number().finite().nonnegative().optional(),
     }),
-    /** 物理坐标 (非 secret). 映射到 GIT_API_BASEURL / TIDB_HOST 等. */
+    /** 物理坐标 (非 secret). 映射到 GIT_API_BASEURL。7.0.0 起 SQL 坐标在 `runtime.store.db`(`tidb*` 三键删除)。 */
     coords: z
         .object({
         gitApiBaseUrl: NON_SECRET_URL.optional().or(z.literal("")),
-        tidbHost: z.string().optional(),
-        tidbPort: TCP_PORT.optional(),
-        tidbUser: z.string().optional(),
     })
         .default({}),
     secretRefs: WorkerSecretRefs,
@@ -1656,7 +1798,7 @@ export const WorkerSpec = z.object({
         .superRefine((rec, ctx) => {
         for (const [k, v] of Object.entries(rec)) {
             if (RESERVED_WORKER_ENV.has(k))
-                ctx.addIssue({ code: "custom", message: `env cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k] ?? "the structured field"}` });
+                ctx.addIssue({ code: "custom", message: `env cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k]}` });
             // 0.1.32: NO name exemption — a PUBLIC key is allowed because SECRET_LITERAL_RE now only flags PRIVATE keys
             // (root fix), so a literal private key / token in env (ANY name, incl `*_PUBKEY`) is still rejected.
             if (containsSecretToken(v))
@@ -1675,7 +1817,7 @@ export const WorkerSpec = z.object({
         .superRefine((rec, ctx) => {
         for (const k of Object.keys(rec))
             if (RESERVED_WORKER_ENV.has(k))
-                ctx.addIssue({ code: "custom", message: `secretEnv cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k] ?? "secretRefs"}` });
+                ctx.addIssue({ code: "custom", message: `secretEnv cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k]}` });
     })
         .optional(),
     /** Opaque recreate trigger (hash-INCLUDED): bump it to force the reconciler to recreate the worker — e.g. to
@@ -1712,6 +1854,86 @@ export const WorkerSpec = z.object({
     signature: z.string().optional(),
     notes: z.string().optional(),
 });
+/** 跨字段判据(G1 / G2 / host∧多副本 / store 四条)。每条一个 issue,`path` 指到要改的字段。 */
+function workerSpecIssues(w, ctx) {
+    const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path, message });
+    const { execution, store, requirePrincipal } = w.runtime;
+    // G1:enabled 的 worker 必须声明车道与店(停用的不渲染,可缺)。
+    if (w.enabled && execution === undefined) {
+        issue(["runtime", "execution", "lane"], `an enabled worker must declare its execution lane — runtime.execution.lane: ${EXECUTION_LANE_WORDS.join(" | ")}. ` +
+            `Without one it would boot with no hands and still report tasks completed; there is no "no hands" lane — disable the worker instead`);
+    }
+    if (w.enabled && store === undefined) {
+        issue(["runtime", "store", "backend"], `an enabled worker must declare its store — runtime.store.backend: ${STORE_BACKENDS.join(" | ")}`);
+    }
+    if (execution !== undefined) {
+        // G2:多租户姿态不许跑不分租户的车道;出路按表现算(不手写第五份词表)。
+        if (requirePrincipal && laneRowOf(execution.lane).tenantSeparation === "single-user-only") {
+            const outlets = EXECUTION_LANES.filter((r) => r.tenantSeparation === "supported").map((r) => r.lane);
+            issue(["runtime", "execution", "lane"], `runtime.requirePrincipal=true (multi-tenant posture) with the "${execution.lane}" execution lane runs every tenant's Bash on one shared target — ` +
+                `this lane does not separate tenants; set runtime.execution.lane to ${outlets.join(" / ")}, or set runtime.requirePrincipal=false for a single-user worker`);
+        }
+        // host ∧ 多副本:副本数有两个旋钮(replicas / autoscaling.maxReplicas,二者互斥),一条规则看「最多几个副本」。
+        if (execution.lane === "host") {
+            const [path, replicas] = w.autoscaling !== undefined ? [["autoscaling", "maxReplicas"], w.autoscaling.maxReplicas] : [["replicas"], w.replicas ?? 1];
+            if (replicas > 1) {
+                issue(path, `the "host" execution lane runs tools on each replica's own filesystem — ${replicas} replicas would hold ${replicas} different workspaces behind one route, ` +
+                    `so a session's next turn can land where its files are not. Keep a single replica, or choose a lane other than "host"`);
+            }
+        }
+    }
+    // store 四条:① SQL 店 ⇒ db + dbPasswordEnv 在场;② 非 SQL 店 ⇒ 两者都不在场(①② 是一条规则:SQL 坐标 ⇔ SQL 店);
+    // ③ memory.backend 与店相配;④ 多租户 ⇒ SQL 店。
+    const sql = store !== undefined && STORE_IS_SQL[store.backend];
+    // 「店真开出来了没有」(引擎 server 79de35f8 读数):SQL 池只在 SQL 店 ∧ session ≠ memory 时打开(`boot/stores.ts:85` wantDb;
+    // `config.ts:1781` needsTidb —— 本包 SQL 店恒带 `db`,所以 auto 必开);任何店只在 backend ≠ memory 时存在(`plugins/store-backend.ts:927`)。
+    // 读开出来的店的起服不变量,写闸前置同判(同表同词):
+    const sqlPoolOpens = sql && store !== undefined && store.session !== "memory";
+    // device 车道 ⇒ SQL 池必须开(引擎 `config-invariants.ts:318` `device-durable-store`:设备注册簿 / session↔设备绑定 / 审计都在 SQL 里)。
+    // 与 G2 同族(gpt-6 腿 F2)。同族的 `device-durable-approval` 读的是 `DURABLE_APPROVAL`(逃生口里的 env + 姿态缺省),不在结构字段上,
+    // 写闸判不了 —— 那一条只在起服拒。
+    if (execution?.lane === "device" && store !== undefined && !sqlPoolOpens) {
+        if (!sql) {
+            issue(["runtime", "store", "backend"], `the "device" execution lane keeps its device registry, session↔device binding and audit trail in SQL — store.backend "${store.backend}" has none ` +
+                `(the engine refuses to start: device-durable-store); set store.backend to mysql | pg`);
+        }
+        else {
+            issue(["runtime", "store", "session"], `the "device" execution lane needs the SQL store actually built — store.session "memory" builds no SQL coordinates ` +
+                `(the engine refuses to start: device-durable-store); set store.session to auto | mysql`);
+        }
+    }
+    if (store !== undefined) {
+        // ⑧ session mysql 要一个 durable 会话店,memory 后端一只都不建(`plugins/session-store.ts:17`「a DB session backend requires a store backend」)。
+        if (store.session === "mysql" && store.backend === "memory") {
+            issue(["runtime", "store", "session"], `store.session "mysql" asks for a durable session store, but store.backend "memory" builds none (the engine refuses to start: a DB session backend requires a store backend); ` +
+                `set store.session to auto | memory, or store.backend to mysql | pg | local`);
+        }
+        // ⑨ 记忆引擎开 ∧ 方言 pg / tidb ⇒ 引擎绑 SQL 池(`boot/stores.ts:209` / `:232` / `:300`);session memory 时池不开 ⇒ 起服拒。
+        if (store.memory.engine === "on" && MEMORY_BACKEND_NEEDS_STORE[store.memory.backend] !== undefined && sql && !sqlPoolOpens) {
+            issue(["runtime", "store", "session"], `store.memory.backend "${store.memory.backend}" binds the SQL pool, but store.session "memory" never opens it (the engine refuses to start half-configured); ` +
+                `set store.session to auto | mysql, or store.memory.backend to file, or store.memory.engine to off`);
+        }
+    }
+    if (store !== undefined) {
+        if (sql && store.db === undefined)
+            issue(["runtime", "store", "db"], `store.backend "${store.backend}" needs runtime.store.db {host, port, user, database}`);
+        if (!sql && store.db !== undefined)
+            issue(["runtime", "store", "db"], `store.backend "${store.backend}" uses no SQL server — remove runtime.store.db, or set store.backend to mysql | pg`);
+        const needs = MEMORY_BACKEND_NEEDS_STORE[store.memory.backend];
+        if (needs !== undefined && store.backend !== needs) {
+            issue(["runtime", "store", "memory", "backend"], `store.memory.backend "${store.memory.backend}" keeps memory in the ${needs} store — it needs store.backend "${needs}" (got "${store.backend}")`);
+        }
+        if (requirePrincipal && !sql) {
+            issue(["runtime", "store", "backend"], `runtime.requirePrincipal=true (multi-tenant posture) needs a SQL store — store.backend "${store.backend}" has no tenant isolation; set store.backend to mysql | pg`);
+        }
+    }
+    if (sql && w.secretRefs.dbPasswordEnv === undefined)
+        issue(["secretRefs", "dbPasswordEnv"], `a SQL store (runtime.store.backend mysql | pg) needs secretRefs.dbPasswordEnv — the host env-NAME holding the database password`);
+    if (!sql && w.secretRefs.dbPasswordEnv !== undefined)
+        issue(["secretRefs", "dbPasswordEnv"], `secretRefs.dbPasswordEnv is set but there is no SQL store (runtime.store.backend mysql | pg) — remove it`);
+}
+/** 一台 worker 的声明。写闸 = `WorkerSpec.safeParse`(7.0.0 删除项读到即拒 + 两个结构块 + 跨字段判据)。 */
+export const WorkerSpec = z.preprocess(retiredWorkerFieldIssues, WorkerSpecObject.superRefine(workerSpecIssues));
 /** Effective route key for a worker = explicit routePrefix, else its name. */
 export function workerRouteKey(w) {
     return w.routePrefix ?? w.name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "6.3.0",
+  "version": "7.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",
@@ -18,6 +18,9 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "settings-schema": "./bin/settings-schema.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -43,6 +46,10 @@
       "types": "./dist/secret-refs.d.ts",
       "default": "./dist/secret-refs.js"
     },
+    "./execution-lanes": {
+      "types": "./dist/execution-lanes.d.ts",
+      "default": "./dist/execution-lanes.js"
+    },
     "./resolve-roster": {
       "types": "./dist/resolve-roster.d.ts",
       "default": "./dist/resolve-roster.js"
@@ -107,6 +114,7 @@
   },
   "files": [
     "dist",
+    "bin",
     "conformance",
     "README.md",
     "CHANGELOG.md"