@sema-agent/settings-schema 6.3.0 → 7.0.0

package/dist/hooks.d.ts

@@ -1732,7 +1732,7 @@ export declare const PostModelSwitchHookInput: z.ZodObject<{
     pricing: z.ZodEnum<["configured", "catalog", "default"]>;
     hook_event_name: z.ZodLiteral<"PostModelSwitch">;
 }, "strip", z.ZodTypeAny, {
-    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    source: "auto" | "command" | "resume" | "picker" | "sdk";
     to_model: string;
     session_id: string;
     transcript_path: string;
@@ -1749,7 +1749,7 @@ export declare const PostModelSwitchHookInput: z.ZodObject<{
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
 }, {
-    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    source: "auto" | "command" | "resume" | "picker" | "sdk";
     to_model: string;
     session_id: string;
     transcript_path: string;
@@ -3173,7 +3173,7 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     pricing: z.ZodEnum<["configured", "catalog", "default"]>;
     hook_event_name: z.ZodLiteral<"PostModelSwitch">;
 }, "strip", z.ZodTypeAny, {
-    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    source: "auto" | "command" | "resume" | "picker" | "sdk";
     to_model: string;
     session_id: string;
     transcript_path: string;
@@ -3190,7 +3190,7 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
 }, {
-    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    source: "auto" | "command" | "resume" | "picker" | "sdk";
     to_model: string;
     session_id: string;
     transcript_path: string;
@@ -5545,20 +5545,20 @@ export declare const HttpHookEntry: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }>;
 /** One configured hook (CC settings shape + shell superset fields; discriminated on `type`). */
@@ -5655,20 +5655,20 @@ export declare const HookEntry: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }, {
     type: "http";
     url: string;
+    headers?: Record<string, string> | undefined;
     if?: string | undefined;
     timeout?: number | undefined;
     statusMessage?: string | undefined;
     once?: boolean | undefined;
-    headers?: Record<string, string> | undefined;
     allowedEnvVars?: string[] | undefined;
 }>]>;
 export type HookEntry = z.infer<typeof HookEntry>;
@@ -5773,20 +5773,20 @@ export declare const HookMatcherEntry: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     }, {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -5819,11 +5819,11 @@ export declare const HookMatcherEntry: z.ZodObject<{
     } | {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     })[];
     matcher?: string | undefined;
@@ -5857,11 +5857,11 @@ export declare const HookMatcherEntry: z.ZodObject<{
     } | {
         type: "http";
         url: string;
+        headers?: Record<string, string> | undefined;
         if?: string | undefined;
         timeout?: number | undefined;
         statusMessage?: string | undefined;
         once?: boolean | undefined;
-        headers?: Record<string, string> | undefined;
         allowedEnvVars?: string[] | undefined;
     })[];
     matcher?: string | undefined;

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  * the config center, the worker service, and the TOC desktop/CLI.
  */
 export * from "./types.js";
+export * from "./execution-lanes.js";
 export * from "./hash.js";
 export * from "./sha256.js";
 export * from "./skills-manifest.js";
@@ -17,6 +18,7 @@ export * from "./scheduler-store.js";
 export * from "./cross-session.js";
 export * from "./hooks.js";
 export * from "./fleet.js";
+export * from "./migrate-workers.js";
 export * from "./migrate.js";
 export * from "./api/auth.js";
 export * from "./api/auth-bridge.js";

package/dist/index.js

@@ -3,6 +3,7 @@
  * the config center, the worker service, and the TOC desktop/CLI.
  */
 export * from "./types.js";
+export * from "./execution-lanes.js"; // 7.0.0 M-R2: the ONE lane / store vocabulary (EXECUTION_LANE_WORDS / EXECUTION_LANES / STORE_BACKENDS / SESSION_BACKENDS / MEMORY_ENGINE_BACKENDS) — pure data, browser-safe
 export * from "./hash.js";
 export * from "./sha256.js";
 export * from "./skills-manifest.js";
@@ -17,6 +18,7 @@ export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (
 export * from "./cross-session.js"; // CC-parity `settings.json` cross-session keys (crossSessionInbound / dialogExpiry) — pure/browser-safe
 export * from "./hooks.js"; // CC-parity hooks contract (31-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
 export * from "./fleet.js"; // scheduling/fleet contract (drain protocol · instance discovery · dispatch policy · quota lease · usage report · quota reset event) — CONTROL-PLANE-SCHEDULING-DESIGN, pure/browser-safe
+export * from "./migrate-workers.js"; // 7.0.0 one-time workers-domain migration (env.REMOTE_EXEC / sessionBackend / tidb* → runtime.execution / runtime.store), pure — run it on the RAW document before parseDomain
 export * from "./migrate.js"; // 0.5→0.6 migration tools (hosts grandfathering + worker.model→catalog migration PLAN — report/draft only, E1; EXPERT-REDESIGN §2-2/§3), pure/browser-safe
 export * from "./api/auth.js"; // /api/v1/auth/* wire contract (RFC 8628 device flow + rotating refresh + logout + approve) — REGISTRY-REBUILD-DESIGN §2, M1 shipped shapes frozen, pure/browser-safe
 export * from "./api/auth-bridge.js"; // 鉴权桥 contract: worker verifies registry user JWT (RS256-only, JWKS kid-miss refresh + throttle, offline grace fail-closed) → VerifiedIdentity — design §5, the service verifier's spec

package/dist/migrate-workers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * workers 域的**一次性迁移**(7.0.0,M-R2 WorkerSpec 结构块)—— 持久面唯一允许的过渡,窗口关了就整文件删除
+ * (连同 `types.ts` 里「删除项读到即拒」那一只预处理)。纯函数、无 I/O、不改入参;文件形的入口是
+ * `settings-schema migrate-workers <file>`(`bin/settings-schema.mjs`,同一只函数)。
+ *
+ * ## 谁跑、在哪
+ * 读前抬升:在 `parseDomain("workers", raw)` / `DOMAIN_SCHEMAS.workers.safeParse` **之前**对**原始 JSON** 跑 —— workers 是
+ * 「读即抛」的 gate 域,6.x 存下来的行在 7.0.0 schema 上整域读不出来(删除项响亮拒、enabled 的 worker 缺两块)。中心在它唯一的
+ * workers 读口跑一次,结果写回;CLI 给文件后端 / 离线用。
+ *
+ * ## 规则(每个旧键恰好一种去处)
+ *  · **车道**:`env.REMOTE_EXEC` 是车道词 ⇒ `runtime.execution.lane`;同车道的 env 键 ⇒ `coords`,同车道的 `secretEnv` 密钥 ⇒
+ *    `secretRefs`(都按导出表 `EXECUTION_LANES` 的栏判)。别车道的键、`REQUIRE_EXECUTION_LANE` ⇒ **dropped**(引擎只读被点名车道
+ *    那一臂;声明了车道就恒渲 true)—— 今天就是惰性的。**enabled 且无 `REMOTE_EXEC` ⇒ refused**:那是「无手照回 completed」的
+ *    病例本身,迁移不替运维猜车道。停用且无 `REMOTE_EXEC` ⇒ 不写车道,残留车道键 dropped。
+ *  · **店**:`sessionBackend` ⇒ `store.session`(`tidb` ⇒ `mysql`,且 `store.backend` 由此为 `mysql`);`memoryBackend` ⇒ **dropped**
+ *    (它从未到达引擎);`coords.tidbHost` 在 ⇒ `store.backend = mysql`,`coords.tidb*` + `runtime.db` ⇒ `store.db`(缺端口 ⇒ 引擎
+ *    `MYSQL_PORT` 的缺省 3306),`secretRefs.tidbPasswordEnv` ⇒ `secretRefs.dbPasswordEnv`;没有 host ⇒ `store.backend = local`
+ *    (设计稿 §3.4:推一次、写死),零散坐标惰性 ⇒ dropped。`env` 逃生口里的 `DB_BACKEND` / `MEMORY_ENGINE` /
+ *    `MEMORY_ENGINE_BACKEND`(渲染器以前不渲,运维只能写在那里)⇒ 搬进 `store`,显式的 `DB_BACKEND` 优先。停用且旧形没点名任何店
+ *    (无 host、无 `DB_BACKEND`、无 `tidb` 词)⇒ 不写店,旧字段 dropped。
+ *  · **表达不了 ⇒ refused**:值写错了栏(密钥以字面值写在 env、坐标来自宿主密钥)、不认识的词、新旧两形并存、`DB_BACKEND=pg`
+ *    配 MySQL 族坐标 —— 迁移不搬值进密钥位、不读宿主密钥、不替运维挑赢家、不换库。
+ *  · **终判 = 7.0.0 schema**:迁出来的每只 worker 都过 `WorkerSpec.safeParse`;不过 ⇒ refused,拒因是 schema 自己的 issue
+ *    (例:多租户 + host 车道、点了车道却缺必需坐标)。迁移不复述任何一条写闸规则。
+ *
+ * refused 的 worker **不进**输出 `doc`(中心不加载它、在列表标红点名 `field`;CLI 有 refused 就一字不写),但随 `refused[].original`
+ * 逐字带回:`doc` ∪ `refused[].original` 覆盖输入的全部 worker,中心写回前按 `index` 放回(或另存),运维的 spec 不会随迁移消失。
+ * 拒因 / dropped 只点名字段,不回显值。
+ *
+ * ## 幂等
+ * 已迁形(没有任何旧键、该有的块都在)⇒ 原样(同一引用)返回、`changed = []`。所以再跑一次 ⇒ 零变化、`doc` 字节相等。
+ */
+import { type ConfigPath } from "./config-fns.js";
+/** 一个被丢掉的旧字段(引擎本就不读它 —— 通知一行,不是错误)。`field` 相对该 worker 条目;`index` = 它在输入 `workers` 里的下标。 */
+export interface WorkersMigrationDrop {
+    readonly name: string;
+    readonly index: number;
+    readonly field: ConfigPath;
+}
+/** 一只迁不了的 worker(不进输出 `doc`)。`field` 指到要人改的那一格(相对该 worker 条目;终判失败时是 7.0.0 形里的路径),
+ *  `reason` 只点名字段、不回显值。`original` = 输入里那一行**逐字**(同一个值,未拷贝未改写)——
+ *  🔴 **写回 `doc` 之前必须把每个 `refused[].original` 按 `index` 放回(或另存)**,否则这只 worker 的 spec 随写回从存储里消失,
+ *  运维看到的是「worker 不见了」而不是「worker 被标红」。它是调用方自己的数据,原样带回;要记日志,按调用方记那一行的规矩记。 */
+export interface WorkersMigrationRefusal {
+    readonly name: string;
+    readonly index: number;
+    readonly field: ConfigPath;
+    readonly reason: string;
+    readonly original: unknown;
+}
+/** `migrateWorkersDomain` 的结果。`changed` = 被改写的 worker 名(含只丢了旧字段的)。 */
+export interface WorkersDomainMigration {
+    readonly doc: unknown;
+    readonly changed: readonly string[];
+    readonly dropped: readonly WorkersMigrationDrop[];
+    readonly refused: readonly WorkersMigrationRefusal[];
+}
+/**
+ * 迁移一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回(判形是 `parseDomain` 的事,迁移不抛)。
+ * 规则、幂等与 refused 的处置见文件头。
+ */
+export declare function migrateWorkersDomain(doc: unknown): WorkersDomainMigration;

package/dist/migrate-workers.js

@@ -0,0 +1,331 @@
+/**
+ * workers 域的**一次性迁移**(7.0.0,M-R2 WorkerSpec 结构块)—— 持久面唯一允许的过渡,窗口关了就整文件删除
+ * (连同 `types.ts` 里「删除项读到即拒」那一只预处理)。纯函数、无 I/O、不改入参;文件形的入口是
+ * `settings-schema migrate-workers <file>`(`bin/settings-schema.mjs`,同一只函数)。
+ *
+ * ## 谁跑、在哪
+ * 读前抬升:在 `parseDomain("workers", raw)` / `DOMAIN_SCHEMAS.workers.safeParse` **之前**对**原始 JSON** 跑 —— workers 是
+ * 「读即抛」的 gate 域,6.x 存下来的行在 7.0.0 schema 上整域读不出来(删除项响亮拒、enabled 的 worker 缺两块)。中心在它唯一的
+ * workers 读口跑一次,结果写回;CLI 给文件后端 / 离线用。
+ *
+ * ## 规则(每个旧键恰好一种去处)
+ *  · **车道**:`env.REMOTE_EXEC` 是车道词 ⇒ `runtime.execution.lane`;同车道的 env 键 ⇒ `coords`,同车道的 `secretEnv` 密钥 ⇒
+ *    `secretRefs`(都按导出表 `EXECUTION_LANES` 的栏判)。别车道的键、`REQUIRE_EXECUTION_LANE` ⇒ **dropped**(引擎只读被点名车道
+ *    那一臂;声明了车道就恒渲 true)—— 今天就是惰性的。**enabled 且无 `REMOTE_EXEC` ⇒ refused**:那是「无手照回 completed」的
+ *    病例本身,迁移不替运维猜车道。停用且无 `REMOTE_EXEC` ⇒ 不写车道,残留车道键 dropped。
+ *  · **店**:`sessionBackend` ⇒ `store.session`(`tidb` ⇒ `mysql`,且 `store.backend` 由此为 `mysql`);`memoryBackend` ⇒ **dropped**
+ *    (它从未到达引擎);`coords.tidbHost` 在 ⇒ `store.backend = mysql`,`coords.tidb*` + `runtime.db` ⇒ `store.db`(缺端口 ⇒ 引擎
+ *    `MYSQL_PORT` 的缺省 3306),`secretRefs.tidbPasswordEnv` ⇒ `secretRefs.dbPasswordEnv`;没有 host ⇒ `store.backend = local`
+ *    (设计稿 §3.4:推一次、写死),零散坐标惰性 ⇒ dropped。`env` 逃生口里的 `DB_BACKEND` / `MEMORY_ENGINE` /
+ *    `MEMORY_ENGINE_BACKEND`(渲染器以前不渲,运维只能写在那里)⇒ 搬进 `store`,显式的 `DB_BACKEND` 优先。停用且旧形没点名任何店
+ *    (无 host、无 `DB_BACKEND`、无 `tidb` 词)⇒ 不写店,旧字段 dropped。
+ *  · **表达不了 ⇒ refused**:值写错了栏(密钥以字面值写在 env、坐标来自宿主密钥)、不认识的词、新旧两形并存、`DB_BACKEND=pg`
+ *    配 MySQL 族坐标 —— 迁移不搬值进密钥位、不读宿主密钥、不替运维挑赢家、不换库。
+ *  · **终判 = 7.0.0 schema**:迁出来的每只 worker 都过 `WorkerSpec.safeParse`;不过 ⇒ refused,拒因是 schema 自己的 issue
+ *    (例:多租户 + host 车道、点了车道却缺必需坐标)。迁移不复述任何一条写闸规则。
+ *
+ * refused 的 worker **不进**输出 `doc`(中心不加载它、在列表标红点名 `field`;CLI 有 refused 就一字不写),但随 `refused[].original`
+ * 逐字带回:`doc` ∪ `refused[].original` 覆盖输入的全部 worker,中心写回前按 `index` 放回(或另存),运维的 spec 不会随迁移消失。
+ * 拒因 / dropped 只点名字段,不回显值。
+ *
+ * ## 幂等
+ * 已迁形(没有任何旧键、该有的块都在)⇒ 原样(同一引用)返回、`changed = []`。所以再跑一次 ⇒ 零变化、`doc` 字节相等。
+ */
+import { formatConfigPath, redactSecrets } from "./config-fns.js";
+import { LANE_ENV_OWNER } from "./execution-lane-index.js";
+import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
+import { WorkerSpec } from "./types.js";
+function isRec(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** 车道块的两个特殊键(不在车道表里,但归车道块)。 */
+const LANE_WORD_KEYS = ["REMOTE_EXEC", "REQUIRE_EXECUTION_LANE"];
+/** 渲染器以前不渲、运维只能写在 env 逃生口里的店键(7.0.0 起归 `runtime.store`)。 */
+const STORE_ENV_KEYS = ["DB_BACKEND", "MEMORY_ENGINE", "MEMORY_ENGINE_BACKEND"];
+/** 6.x 删除项:`[容器, 键]`。 */
+const SIX_X_STORE_FIELDS = [
+    ["runtime", "sessionBackend"],
+    ["runtime", "memoryBackend"],
+    ["runtime", "db"],
+    ["coords", "tidbHost"],
+    ["coords", "tidbPort"],
+    ["coords", "tidbUser"],
+    ["secretRefs", "tidbPasswordEnv"],
+];
+/** 引擎 `MEMORY_ENGINE` 的两族词(server `src/config.ts` :3011–3012,比较前 trim + 小写)。 */
+const MEMORY_ENGINE_ON_WORDS = ["on", "true", "1", "yes", "enabled"];
+const MEMORY_ENGINE_OFF_WORDS = ["off", "false", "0", "no", "disabled"];
+/** 引擎 `MYSQL_PORT` 的缺省(server `src/config.ts` :1818)—— 旧形没写端口时引擎连的就是它。 */
+const MYSQL_DEFAULT_PORT = 3306;
+function isLaneWord(v) {
+    return typeof v === "string" && EXECUTION_LANE_WORDS.some((w) => w === v);
+}
+function isStoreWord(v) {
+    return typeof v === "string" && STORE_BACKENDS.some((w) => w === v);
+}
+function isMemoryBackendWord(v) {
+    return typeof v === "string" && MEMORY_ENGINE_BACKENDS.some((w) => w === v);
+}
+/** 拒因里只点名形如词的值(短、小写);其余一律不回显(值可能是粘错位置的凭据)。 */
+function describeWord(v) {
+    return typeof v === "string" && /^[a-z0-9][a-z0-9-]{0,31}$/.test(v) ? `"${v}"` : "(value not shown)";
+}
+const UNCHANGED = { kind: "unchanged" };
+function migrateEntry(raw, index) {
+    if (!isRec(raw) || typeof raw.name !== "string")
+        return UNCHANGED; // 不是一只可辨认的 worker:判形是 parseDomain 的事
+    const name = raw.name;
+    const refuse = (field, reason) => ({ kind: "refused", refusal: { name, index, field, reason: redactSecrets(reason), original: raw } });
+    const enabled = raw.enabled !== false;
+    const has = (container, key) => isRec(container) && Object.hasOwn(container, key);
+    const laneKeysOf = (rec) => isRec(rec) ? Object.keys(rec).filter((k) => LANE_WORD_KEYS.some((w) => w === k) || LANE_ENV_OWNER.has(k)) : [];
+    const storeKeysOf = (rec) => (isRec(rec) ? STORE_ENV_KEYS.filter((k) => Object.hasOwn(rec, k)) : []);
+    const envLaneKeys = laneKeysOf(raw.env);
+    const secretLaneKeys = laneKeysOf(raw.secretEnv);
+    const envStoreKeys = storeKeysOf(raw.env);
+    const secretStoreKeys = storeKeysOf(raw.secretEnv);
+    const oldStoreFields = SIX_X_STORE_FIELDS.filter(([c, k]) => has(raw[c], k));
+    const hasExecution = has(raw.runtime, "execution");
+    const hasStore = has(raw.runtime, "store");
+    const laneTouched = envLaneKeys.length + secretLaneKeys.length > 0;
+    const storeTouched = oldStoreFields.length + envStoreKeys.length + secretStoreKeys.length > 0;
+    if (hasExecution && laneTouched) {
+        return refuse(["runtime", "execution"], `declares runtime.execution AND execution-lane keys in env / secretEnv (${[...envLaneKeys, ...secretLaneKeys].join(", ")}) — keep one form; the migration does not pick a winner`);
+    }
+    // 新形的店字段有两处:`runtime.store` 与 `secretRefs.dbPasswordEnv`(gpt-6 腿 F1:只看前者时,手填过新口令引用、又留着旧
+    // `tidbPasswordEnv` 的行会被旧引用静默覆盖)。任一在场 ∧ 还有旧店字段 ⇒ 两形并存,不挑赢家。
+    const newStoreFields = [...(hasStore ? ["runtime.store"] : []), ...(has(raw.secretRefs, "dbPasswordEnv") ? ["secretRefs.dbPasswordEnv"] : [])];
+    if (newStoreFields.length > 0 && storeTouched) {
+        const old = [...oldStoreFields.map(([c, k]) => `${c}.${k}`), ...envStoreKeys.map((k) => `env.${k}`), ...secretStoreKeys.map((k) => `secretEnv.${k}`)];
+        return refuse(["runtime", "store"], `declares the 7.0.0 store fields (${newStoreFields.join(", ")}) AND 6.x store fields (${old.join(", ")}) — keep one form; the migration does not pick a winner`);
+    }
+    const secretStoreKey = secretStoreKeys[0];
+    if (secretStoreKey !== undefined)
+        return refuse(["secretEnv", secretStoreKey], `${secretStoreKey} is set from a host secret — the migration cannot read it; declare runtime.store by hand`);
+    if (has(raw.secretEnv, "REMOTE_EXEC"))
+        return refuse(["secretEnv", "REMOTE_EXEC"], "the execution lane is set from a host secret — the migration cannot read it; declare runtime.execution.lane by hand");
+    const needLane = !hasExecution && (enabled || laneTouched);
+    const needStore = !hasStore && (enabled || storeTouched);
+    if (!needLane && !needStore)
+        return UNCHANGED;
+    const w = structuredClone(raw);
+    const runtime = isRec(w.runtime) ? w.runtime : {};
+    w.runtime = runtime;
+    const env = isRec(w.env) ? w.env : {};
+    const secretEnv = isRec(w.secretEnv) ? w.secretEnv : {};
+    const coords = isRec(w.coords) ? w.coords : {};
+    const secretRefs = isRec(w.secretRefs) ? w.secretRefs : {};
+    const dropped = [];
+    const drop = (container, slot, key) => {
+        delete container[key];
+        dropped.push({ name, index, field: [slot, key] });
+    };
+    // ── 车道 ─────────────────────────────────────────────────────────────────────────────────────────
+    if (needLane) {
+        const rx = env.REMOTE_EXEC;
+        if (rx === undefined || rx === "") {
+            if (enabled) {
+                return refuse(["env", "REMOTE_EXEC"], `an enabled worker names no execution lane (env.REMOTE_EXEC is unset) — it boots with no hands and still reports tasks completed. ` +
+                    `The migration does not guess a lane: set runtime.execution.lane (${EXECUTION_LANE_WORDS.join(" | ")}) by hand, or disable the worker`);
+            }
+            for (const k of envLaneKeys)
+                drop(env, "env", k); // 停用且没点名车道 ⇒ 每个车道键都是惰性的
+            for (const k of secretLaneKeys)
+                drop(secretEnv, "secretEnv", k);
+        }
+        else {
+            if (!isLaneWord(rx)) {
+                return refuse(["env", "REMOTE_EXEC"], `env.REMOTE_EXEC ${describeWord(rx)} is not an execution lane (${EXECUTION_LANE_WORDS.join(" | ")}) — the engine refuses to start with it; set runtime.execution.lane by hand`);
+            }
+            const lane = rx;
+            const laneCoords = {};
+            const laneSecretRefs = {};
+            for (const k of envLaneKeys) {
+                if (k === "REMOTE_EXEC") {
+                    delete env[k];
+                    continue;
+                }
+                const owner = LANE_ENV_OWNER.get(k);
+                if (owner === undefined || owner.lane !== lane) {
+                    drop(env, "env", k); // REQUIRE_EXECUTION_LANE(声明了车道就恒渲 true)与别车道的键(引擎只读被点名那一臂)
+                    continue;
+                }
+                const v = env[k];
+                if (owner.secret) {
+                    return refuse(["env", k], `${k} is a secret of lane "${lane}" but env carries it as a literal value — the migration does not move a value into a secret slot: put it in the host secret source and reference it from runtime.execution.secretRefs.${k}`);
+                }
+                if (typeof v !== "string")
+                    return refuse(["env", k], `env.${k} is not a string`);
+                laneCoords[k] = v;
+                delete env[k];
+            }
+            for (const k of secretLaneKeys) {
+                const owner = LANE_ENV_OWNER.get(k);
+                if (owner === undefined || owner.lane !== lane) {
+                    drop(secretEnv, "secretEnv", k);
+                    continue;
+                }
+                const v = secretEnv[k];
+                if (!owner.secret) {
+                    return refuse(["secretEnv", k], `${k} is a non-secret coordinate of lane "${lane}" but is set from a host secret — the migration cannot read the value; write it in runtime.execution.coords.${k} by hand`);
+                }
+                if (typeof v !== "string")
+                    return refuse(["secretEnv", k], `secretEnv.${k} is not a string`);
+                laneSecretRefs[k] = v;
+                delete secretEnv[k];
+            }
+            runtime.execution = { lane, coords: laneCoords, secretRefs: laneSecretRefs };
+        }
+    }
+    // ── 店 ───────────────────────────────────────────────────────────────────────────────────────────
+    if (needStore) {
+        if (Object.hasOwn(runtime, "memoryBackend"))
+            drop(runtime, "runtime", "memoryBackend"); // 从未到达引擎
+        const sessionRaw = runtime.sessionBackend;
+        const host = coords.tidbHost;
+        const hostSet = typeof host === "string" && host !== "";
+        const dbBackendRaw = env.DB_BACKEND;
+        const dbBackendSet = dbBackendRaw !== undefined && dbBackendRaw !== "";
+        const named = hostSet || dbBackendSet || sessionRaw === "tidb";
+        const sqlCoordFields = [
+            [runtime, "runtime", "db"],
+            [coords, "coords", "tidbHost"],
+            [coords, "coords", "tidbPort"],
+            [coords, "coords", "tidbUser"],
+            [secretRefs, "secretRefs", "tidbPasswordEnv"],
+        ];
+        if (!enabled && !named) {
+            // 停用、旧形没点名任何店 ⇒ 不替它发明一个;旧字段全是惰性的
+            if (Object.hasOwn(runtime, "sessionBackend"))
+                drop(runtime, "runtime", "sessionBackend");
+            for (const [c, slot, k] of sqlCoordFields)
+                if (Object.hasOwn(c, k))
+                    drop(c, slot, k);
+            for (const k of STORE_ENV_KEYS)
+                if (Object.hasOwn(env, k))
+                    drop(env, "env", k);
+        }
+        else {
+            let session;
+            if (sessionRaw === undefined)
+                session = "auto"; // 6.x 的缺省
+            else if (sessionRaw === "tidb")
+                session = "mysql";
+            else if (sessionRaw === "memory" || sessionRaw === "auto")
+                session = sessionRaw;
+            else
+                return refuse(["runtime", "sessionBackend"], `runtime.sessionBackend ${describeWord(sessionRaw)} is not a 6.x session backend (tidb | memory | auto)`);
+            delete runtime.sessionBackend;
+            let backend;
+            if (dbBackendSet) {
+                if (!isStoreWord(dbBackendRaw))
+                    return refuse(["env", "DB_BACKEND"], `env.DB_BACKEND ${describeWord(dbBackendRaw)} is not a store backend (${STORE_BACKENDS.join(" | ")}) — the engine refuses to start with it`);
+                backend = dbBackendRaw;
+            }
+            else {
+                backend = hostSet || sessionRaw === "tidb" ? "mysql" : "local";
+            }
+            delete env.DB_BACKEND;
+            const sqlCoordsPresent = sqlCoordFields.filter(([c, , k]) => Object.hasOwn(c, k));
+            const store = { backend, session };
+            if (backend === "mysql") {
+                if (hostSet) {
+                    const port = coords.tidbPort;
+                    store.db = {
+                        host,
+                        port: port === undefined ? MYSQL_DEFAULT_PORT : port,
+                        ...(Object.hasOwn(coords, "tidbUser") ? { user: coords.tidbUser } : {}),
+                        ...(Object.hasOwn(runtime, "db") ? { database: runtime.db } : {}),
+                    };
+                }
+                if (Object.hasOwn(secretRefs, "tidbPasswordEnv"))
+                    secretRefs.dbPasswordEnv = secretRefs.tidbPasswordEnv;
+                for (const [c, , k] of sqlCoordsPresent)
+                    delete c[k];
+            }
+            else if (backend === "pg") {
+                if (sqlCoordsPresent.length > 0) {
+                    return refuse(["env", "DB_BACKEND"], `env.DB_BACKEND=pg but the SQL coordinates are the MySQL family (coords.tidb* / runtime.db / secretRefs.tidbPasswordEnv, rendered as MYSQL_*) — the migration does not move a MySQL server's coordinates onto pg; declare runtime.store by hand`);
+                }
+            }
+            else {
+                for (const [c, slot, k] of sqlCoordsPresent)
+                    drop(c, slot, k); // 非 SQL 店:SQL 坐标在引擎里是「声明不用」的惰性件
+            }
+            const memory = {};
+            const engineRaw = env.MEMORY_ENGINE;
+            if (engineRaw !== undefined) {
+                const word = typeof engineRaw === "string" ? engineRaw.trim().toLowerCase() : undefined;
+                if (word !== undefined && MEMORY_ENGINE_ON_WORDS.includes(word))
+                    memory.engine = "on";
+                else if (word !== undefined && MEMORY_ENGINE_OFF_WORDS.includes(word))
+                    memory.engine = "off";
+                else if (word !== "")
+                    return refuse(["env", "MEMORY_ENGINE"], "env.MEMORY_ENGINE is not an on/off word — the engine refuses to start with it");
+                delete env.MEMORY_ENGINE;
+            }
+            const memoryBackendRaw = env.MEMORY_ENGINE_BACKEND;
+            if (memoryBackendRaw !== undefined) {
+                if (!isMemoryBackendWord(memoryBackendRaw)) {
+                    return refuse(["env", "MEMORY_ENGINE_BACKEND"], `env.MEMORY_ENGINE_BACKEND ${describeWord(memoryBackendRaw)} is not a memory backend (${MEMORY_ENGINE_BACKENDS.join(" | ")}) — the engine refuses to start with it`);
+                }
+                memory.backend = memoryBackendRaw;
+                delete env.MEMORY_ENGINE_BACKEND;
+            }
+            if (Object.keys(memory).length > 0)
+                store.memory = memory;
+            runtime.store = store;
+        }
+    }
+    // 被搬空的 env / secretEnv 整键去掉(它们是可选字段;留一个 `{}` 只是噪声)
+    if (isRec(w.env) && Object.keys(env).length === 0 && isRec(raw.env) && Object.keys(raw.env).length > 0)
+        delete w.env;
+    if (isRec(w.secretEnv) && Object.keys(secretEnv).length === 0 && isRec(raw.secretEnv) && Object.keys(raw.secretEnv).length > 0)
+        delete w.secretEnv;
+    // 终判 = 7.0.0 schema 本身(迁移不复述写闸规则)
+    const verdict = WorkerSpec.safeParse(w);
+    if (!verdict.success) {
+        const issues = verdict.error.issues;
+        const shown = issues.slice(0, 3).map((i) => `${formatConfigPath(i.path)}: ${i.message}`);
+        const more = issues.length > shown.length ? ` (+${issues.length - shown.length} more)` : "";
+        const first = issues[0];
+        return refuse(first === undefined ? [] : first.path, `after migration the worker is not a valid 7.0.0 WorkerSpec — ${shown.join("; ")}${more}`);
+    }
+    return { kind: "migrated", entry: w, dropped };
+}
+/**
+ * 迁移一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回(判形是 `parseDomain` 的事,迁移不抛)。
+ * 规则、幂等与 refused 的处置见文件头。
+ */
+export function migrateWorkersDomain(doc) {
+    if (!isRec(doc) || !Array.isArray(doc.workers))
+        return { doc, changed: [], dropped: [], refused: [] };
+    const workers = doc.workers;
+    const kept = [];
+    const changed = [];
+    const dropped = [];
+    const refused = [];
+    workers.forEach((entry, index) => {
+        const out = migrateEntry(entry, index);
+        switch (out.kind) {
+            case "unchanged":
+                kept.push(entry);
+                break;
+            case "migrated":
+                kept.push(out.entry);
+                changed.push(String(out.entry.name));
+                dropped.push(...out.dropped);
+                break;
+            case "refused":
+                refused.push(out.refusal);
+                break;
+            default: {
+                const unhandled = out;
+                throw new Error(`migrateWorkersDomain: unhandled outcome ${JSON.stringify(unhandled)}`);
+            }
+        }
+    });
+    if (changed.length === 0 && refused.length === 0)
+        return { doc, changed: [], dropped: [], refused: [] };
+    return { doc: { ...doc, workers: kept }, changed, dropped, refused };
+}