@sema-agent/settings-schema 6.4.0 → 7.0.1

package/dist/cli.js

@@ -0,0 +1,110 @@
+/**
+ * `settings-schema` 命令行的核心(7.0.0)—— 子命令只有一个:`migrate-workers <workers.json> [--check]`,即
+ * {@link migrateWorkersDomain} 的文件形(文件后端 / 离线用;中心在它的 workers 读口直接调同一只函数)。
+ *
+ * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(那是本包唯一用 fs 写文件的地方),所以测试可以直接驱动它。
+ * 不进主桶 —— 它是 bin 的实现,不是契约面。
+ *
+ * 退出码:0 = 已写回 / 无事可做;1 = 有 worker 迁不了(refused)或迁出的文档整域读不进 7.0.0,**一字不写**;2 = 用法 / 读文件 /
+ * JSON 错(此时 stdout 为空);3 = `--check` 且会有改动(不写)。
+ *
+ * ## 报告形(7.0.1:让「没写」在机读上不可能被读成「写了」)
+ * 退出码 0 / 1 / 3 时 stdout 恰两行:
+ *  · 第 1 行 = **唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`;
+ *  · 第 2 行 = JSON 报告(`event: "workers_domain_migrated"`,只点名字段、不带值),同带 `outcome` / `written`。
+ * `written` 不是独立字段:由 `outcome` 派生({@link writtenOf};只有 `applied` 写盘)。**键名带时态**:`written=true` 才有 `changed` /
+ * `dropped`;`written=false`(refused / noop / pending)时是 `wouldChange` / `wouldDrop` —— 读旧字段 `changed` 的脚本在没写的时候
+ * 读不到值,而不是读到一份「已迁」名单。结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。
+ */
+import { formatConfigPath, sanitizeZodError } from "./config-fns.js";
+import { MIGRATE_WORKERS_COMMAND } from "./execution-lane-index.js";
+import { migrateWorkersDomain } from "./migrate-workers.js";
+import { DOMAIN_SCHEMAS } from "./types.js";
+const USAGE = [
+    `usage: ${MIGRATE_WORKERS_COMMAND} <workers.json> [--check]`,
+    "  One-time 7.0.0 migration of a workers domain document ({ \"workers\": [...] }): env.REMOTE_EXEC + lane keys →",
+    "  runtime.execution, sessionBackend / coords.tidb* / runtime.db / tidbPasswordEnv → runtime.store. Writes the file in",
+    "  place only when every worker migrates; --check only reports (exit 3 if the file would change).",
+    "  stdout (exit 0 / 1 / 3): line 1 = outcome=<refused|applied|noop|pending> written=<true|false>, line 2 = the JSON report",
+    "  (changed / dropped only when written=true; otherwise wouldChange / wouldDrop).",
+].join("\n");
+/** 这个结论写没写盘 —— 只有 `applied` 写。`written` 从这里派生,不是报告里一个可以和 `outcome` 各说各话的独立字段。 */
+function writtenOf(outcome) {
+    switch (outcome) {
+        case "applied":
+            return true;
+        case "refused":
+        case "noop":
+        case "pending":
+            return false;
+        default: {
+            const unhandled = outcome;
+            throw new Error(`settings-schema: unhandled outcome ${String(unhandled)}`);
+        }
+    }
+}
+/** 一次发出报告:结论行 + JSON 行(一次 `stdout` 调用)。键名带时态:写了 ⇒ `changed` / `dropped`,没写 ⇒ `wouldChange` / `wouldDrop`。 */
+function reportOf(outcome, file, m) {
+    const written = writtenOf(outcome);
+    const dropped = m.dropped.map((d) => ({ name: d.name, field: formatConfigPath(d.field) }));
+    const json = JSON.stringify({
+        event: "workers_domain_migrated",
+        outcome,
+        written,
+        file,
+        ...(written ? { changed: m.changed, dropped } : { wouldChange: m.changed, wouldDrop: dropped }),
+        refused: m.refused.map((r) => ({ name: r.name, field: formatConfigPath(r.field), reason: r.reason })),
+    });
+    return `outcome=${outcome} written=${written}\n${json}\n`;
+}
+export async function runSettingsSchemaCli(argv, io) {
+    const [command, ...rest] = argv;
+    const check = rest.includes("--check");
+    const files = rest.filter((a) => a !== "--check");
+    const file = files[0];
+    if (command !== "migrate-workers" || files.length !== 1 || file === undefined || file.startsWith("-")) {
+        io.stderr(`${USAGE}\n`);
+        return 2;
+    }
+    let text;
+    try {
+        text = await io.readFile(file);
+    }
+    catch (err) {
+        io.stderr(`settings-schema: cannot read ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        io.stderr(`settings-schema: ${file} is not valid JSON\n`);
+        return 2;
+    }
+    const m = migrateWorkersDomain(doc);
+    if (m.refused.length > 0) {
+        io.stdout(reportOf("refused", file, m));
+        io.stderr(`settings-schema: ${m.refused.length} worker(s) cannot be migrated (see "refused") — fix them by hand and re-run; nothing was written\n`);
+        return 1;
+    }
+    if (m.changed.length === 0) {
+        io.stdout(reportOf("noop", file, m));
+        return 0;
+    }
+    if (check) {
+        io.stdout(reportOf("pending", file, m));
+        return 3;
+    }
+    // 整域再判一次(域层规则:名字 / 路由唯一 …)—— 读不进 7.0.0 的文档不落盘。
+    const whole = DOMAIN_SCHEMAS.workers.safeParse(m.doc);
+    if (!whole.success) {
+        const issues = sanitizeZodError(whole.error).issues.map((i) => `${formatConfigPath(i.path)}: ${i.message}`);
+        io.stdout(reportOf("refused", file, m));
+        io.stderr(`settings-schema: the migrated document does not read as a 7.0.0 workers domain — ${issues.join("; ")}; nothing was written\n`);
+        return 1;
+    }
+    await io.writeFileAtomic(file, `${JSON.stringify(m.doc, null, 2)}\n`);
+    io.stdout(reportOf("applied", file, m)); // 写盘成功之后才报 applied
+    return 0;
+}

package/dist/execution-lane-index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集与指路句,
+ * 供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
+ * 索引只从表派生,不另存任何词:表改了,这里跟着变。
+ *
+ * ## 迁移指路(7.0.1)
+ * 拒因要不要带迁移指路只有一条规则:**这个键「旧形 ⇒ 迁移能搬」就带,搬不了的保留名(`PORT` / `MODEL_*` …)不带**。
+ * 「迁移能搬」= 迁移自己识别的键集(车道键 {@link isLaneEnvKey} ∪ 店键 {@link STORE_ENV_KEYS}),写闸读的是**同一只谓词**
+ * ({@link isMigratableEnvKey}),不是第二张手抄的表 —— 迁移多认一个键而写闸没跟,或反过来,不会静默分叉
+ * (`test/migration-signpost-7.0.1.test.ts` 用真跑迁移的读数逐个保留名对拍)。
+ */
+import { type ExecutionLane, type ExecutionLaneRow } from "./execution-lanes.js";
+/** 一条车道的表行。词表与表行由 `execution-lanes.ts` 的 `satisfies Record<ExecutionLane, …>` 一一对应 ——
+ *  找不到 = 本包自身的不变量坏了(不是输入错),所以抛。 */
+export declare function laneRowOf(lane: ExecutionLane): ExecutionLaneRow;
+/** 一个车道 env 名归谁:哪条车道、密钥栏还是坐标栏、必需还是可选。 */
+export interface LaneEnvOwner {
+    readonly lane: ExecutionLane;
+    readonly secret: boolean;
+    readonly required: boolean;
+}
+/** 车道 env 名 → 归属。四栏两两不交、跨车道不交(`test/execution-lanes-7.0.0.test.ts` 钉),所以每个名恰好一个归属。 */
+export declare const LANE_ENV_OWNER: ReadonlyMap<string, LaneEnvOwner>;
+/** 一个车道 env 名在 WorkerSpec 里的**唯一写位**(保留键的拒因指路用它)。 */
+export declare function laneEnvSeat(name: string, owner: LaneEnvOwner): string;
+/** 车道块的两个特殊键(不在车道表里,但归车道块:迁移把 `REMOTE_EXEC` 搬成 `runtime.execution.lane`、`REQUIRE_EXECUTION_LANE` 丢弃)。 */
+export declare const LANE_WORD_KEYS: readonly ["REMOTE_EXEC", "REQUIRE_EXECUTION_LANE"];
+/** 渲染器以前不渲、运维只能写在 env 逃生口里的店键(7.0.0 起归 `runtime.store`;迁移搬进 `store`)。 */
+export declare const STORE_ENV_KEYS: readonly ["DB_BACKEND", "MEMORY_ENGINE", "MEMORY_ENGINE_BACKEND"];
+/** 一个名字是不是车道块的键:车道词两键,或车道表里的任一车道 env 名。 */
+export declare function isLaneEnvKey(name: string): boolean;
+/** 一个名字是不是迁移会处理的 6.x env 键(搬进结构块 / 丢弃 / 点名它拒):车道块的键 ∪ 店键。写闸拒因带不带迁移指路只看它。 */
+export declare function isMigratableEnvKey(name: string): boolean;
+/** 迁移命令的唯一拼写(design/327 §3.4 原句):`npx` 全名形 —— 没装本包的运维粘贴即可跑;裸 bin 名 `settings-schema …` 在没装本包的机器上是 `command not found`。 */
+export declare const MIGRATE_WORKERS_COMMAND: "npx @sema-agent/settings-schema migrate-workers";
+/** 拒因里的迁移指路 —— **一句话、一个常量**:保留名闸(`env` / `secretEnv` 里的 {@link isMigratableEnvKey} 键)与删除项预处理(七个被删旧键)引用同一个。 */
+export declare const MIGRATION_SIGNPOST: string;

package/dist/execution-lane-index.js

@@ -0,0 +1,46 @@
+/**
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集与指路句,
+ * 供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
+ * 索引只从表派生,不另存任何词:表改了,这里跟着变。
+ *
+ * ## 迁移指路(7.0.1)
+ * 拒因要不要带迁移指路只有一条规则:**这个键「旧形 ⇒ 迁移能搬」就带,搬不了的保留名(`PORT` / `MODEL_*` …)不带**。
+ * 「迁移能搬」= 迁移自己识别的键集(车道键 {@link isLaneEnvKey} ∪ 店键 {@link STORE_ENV_KEYS}),写闸读的是**同一只谓词**
+ * ({@link isMigratableEnvKey}),不是第二张手抄的表 —— 迁移多认一个键而写闸没跟,或反过来,不会静默分叉
+ * (`test/migration-signpost-7.0.1.test.ts` 用真跑迁移的读数逐个保留名对拍)。
+ */
+import { EXECUTION_LANES } from "./execution-lanes.js";
+/** 一条车道的表行。词表与表行由 `execution-lanes.ts` 的 `satisfies Record<ExecutionLane, …>` 一一对应 ——
+ *  找不到 = 本包自身的不变量坏了(不是输入错),所以抛。 */
+export function laneRowOf(lane) {
+    const row = EXECUTION_LANES.find((r) => r.lane === lane);
+    if (row === undefined)
+        throw new Error(`execution lane table has no row for "${lane}" (package invariant broken)`);
+    return row;
+}
+/** 车道 env 名 → 归属。四栏两两不交、跨车道不交(`test/execution-lanes-7.0.0.test.ts` 钉),所以每个名恰好一个归属。 */
+export const LANE_ENV_OWNER = new Map(EXECUTION_LANES.flatMap((r) => {
+    const own = (names, secret, required) => names.map((k) => [k, { lane: r.lane, secret, required }]);
+    return [...own(r.requiredEnv, false, true), ...own(r.optionalEnv, false, false), ...own(r.requiredSecretEnv, true, true), ...own(r.optionalSecretEnv, true, false)];
+}));
+/** 一个车道 env 名在 WorkerSpec 里的**唯一写位**(保留键的拒因指路用它)。 */
+export function laneEnvSeat(name, owner) {
+    return `runtime.execution.${owner.secret ? "secretRefs" : "coords"}.${name}`;
+}
+/** 车道块的两个特殊键(不在车道表里,但归车道块:迁移把 `REMOTE_EXEC` 搬成 `runtime.execution.lane`、`REQUIRE_EXECUTION_LANE` 丢弃)。 */
+export const LANE_WORD_KEYS = ["REMOTE_EXEC", "REQUIRE_EXECUTION_LANE"];
+/** 渲染器以前不渲、运维只能写在 env 逃生口里的店键(7.0.0 起归 `runtime.store`;迁移搬进 `store`)。 */
+export const STORE_ENV_KEYS = ["DB_BACKEND", "MEMORY_ENGINE", "MEMORY_ENGINE_BACKEND"];
+/** 一个名字是不是车道块的键:车道词两键,或车道表里的任一车道 env 名。 */
+export function isLaneEnvKey(name) {
+    return LANE_WORD_KEYS.some((k) => k === name) || LANE_ENV_OWNER.has(name);
+}
+/** 一个名字是不是迁移会处理的 6.x env 键(搬进结构块 / 丢弃 / 点名它拒):车道块的键 ∪ 店键。写闸拒因带不带迁移指路只看它。 */
+export function isMigratableEnvKey(name) {
+    return isLaneEnvKey(name) || STORE_ENV_KEYS.some((k) => k === name);
+}
+/** 迁移命令的唯一拼写(design/327 §3.4 原句):`npx` 全名形 —— 没装本包的运维粘贴即可跑;裸 bin 名 `settings-schema …` 在没装本包的机器上是 `command not found`。 */
+export const MIGRATE_WORKERS_COMMAND = "npx @sema-agent/settings-schema migrate-workers";
+/** 拒因里的迁移指路 —— **一句话、一个常量**:保留名闸(`env` / `secretEnv` 里的 {@link isMigratableEnvKey} 键)与删除项预处理(七个被删旧键)引用同一个。 */
+export const MIGRATION_SIGNPOST = `lift a stored 6.x spec once with migrateWorkersDomain(doc) (on the raw document, ahead of parseDomain) or \`${MIGRATE_WORKERS_COMMAND} <file>\``;

package/dist/execution-lanes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,零函数、零依赖(叶模块:
+ * 本文件不 import 任何东西,`types.ts` 反过来引它)。
+ *
+ * ## 为什么在这里
+ * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
+ * 部署面的车道清单、中心表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
+ *  · 中心写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
+ *  · 中心渲染器按这张表把结构块渲成 env(唯一写者);
+ *  · 引擎提货时从这张表派生自己的车道词表 / 必需键表 / 租户分离位(引擎只留运行期事实,按导入联合类型穷举);
+ *  · 部署面车道清单由这张表生成。
+ * 写闸与起服读同一张表 ⇒ 不会分叉。
+ *
+ * ## 行内容的出处(逐行抄自引擎真码,坐标 = server 7.112.0 树)
+ *  · 车道词与次序:`src/execution-lane-caps.ts` `EXECUTION_LANE_WORDS`(:335)去掉 `in-process` =
+ *    `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
+ *    :269 ssh / :288 adb / :308 local-docker / :327 device)。
+ *  · `requiredEnv ∪ requiredSecretEnv`:`src/config.ts` `REQUIRED_ENVS_BY_LANE`(:1054)逐字;按 `src/config-catalog.ts`
+ *    该键那一行的值类型分栏 —— 类型 `secret` / `opaque`(目录自己「绝不回显值」的两类)进 `*SecretEnv`,其余进 `*Env`。
+ *  · `optionalEnv ∪ optionalSecretEnv`:`src/config.ts` `parseOrchestrationDomain` 的 `REMOTE_EXEC` 三元链里**该车道那一臂**
+ *    读的 env 名(:3925 e2b / :3957 k8s / :3991 ssh / :4006 adb / :4014 host / :4026 local-docker / :4055 device;
+ *    臂内调用的解析器 `parseSshHostKeyEnv` :1521、`parseDevicePreAuthPerRemoteEnv` :871、`parseDeviceEnrollTokenTtlEnv` :857
+ *    读的名也算),去掉必需键,同样按目录值类型分栏。**不收**别的域也读的名:k8s 臂里的 `MINIO_ENDPOINT` /
+ *    `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` / `MINIO_REGION` 同时是存储域对象存储的键(`src/config.ts` :1848 / :1872),
+ *    收进车道栏会把它们保留成「k8s 专属」,别的车道就再也设不了快照对象存储。也**不收**臂外的适配器调参键
+ *    (`HOST_BG_*` / `E2B_BG_*` / `K8S_BG_*` / `HOST_SHELL_PATH` …):它们不是车道坐标,照旧走 `env` 逃生口。
+ *
+ * ## 不在表里的词
+ *  · `in-process`:引擎内部「没有 remoteExec」这个状态的名字,不是可声明的车道 —— 显式「无手」的 worker 在模型要用工具时
+ *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
+ *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
+ *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
+ */
+/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序)。 */
+export declare const EXECUTION_LANE_WORDS: readonly ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device"];
+export type ExecutionLane = (typeof EXECUTION_LANE_WORDS)[number];
+/** 车道分不分租户(引擎能力表的 `tenantSeparation` 位,两档,没有「不表态」)。
+ *  `supported` = 每个租户的命令落在各自的目标上;`single-user-only` = 所有任务落同一个共享目标 ⇒ 只许单用户 worker。 */
+export declare const TENANT_SEPARATION_WORDS: readonly ["supported", "single-user-only"];
+export type TenantSeparation = (typeof TENANT_SEPARATION_WORDS)[number];
+/** 一条车道的表行。四栏 env 名两两不交、跨车道也不交(`test/execution-lanes-7.0.0.test.ts` 钉)。
+ *  - `requiredEnv` / `optionalEnv`:非密坐标 —— 写在 `runtime.execution.coords`(字面值);
+ *  - `requiredSecretEnv` / `optionalSecretEnv`:密钥 —— 写在 `runtime.execution.secretRefs`(服务变量名 → 宿主 env-NAME,绝不写值)。 */
+export interface ExecutionLaneRow {
+    readonly lane: ExecutionLane;
+    readonly tenantSeparation: TenantSeparation;
+    readonly requiredEnv: readonly string[];
+    readonly requiredSecretEnv: readonly string[];
+    readonly optionalEnv: readonly string[];
+    readonly optionalSecretEnv: readonly string[];
+}
+/** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
+export declare const EXECUTION_LANES: readonly ExecutionLaneRow[];
+/** 存储后端(→ `DB_BACKEND`)。= server `src/config-types.ts` `DB_BACKEND_WORDS`(:67)逐字同序。 */
+export declare const STORE_BACKENDS: readonly ["mysql", "pg", "local", "memory"];
+export type StoreBackend = (typeof STORE_BACKENDS)[number];
+/** session 店(→ `SESSION_BACKEND`)。= server `src/config.ts` :1760 `enumEnv("SESSION_BACKEND", …)` 的词表逐字同序
+ *  (`tidb` 不在集内:引擎见之拒启)。 */
+export declare const SESSION_BACKENDS: readonly ["memory", "mysql", "auto"];
+export type SessionBackend = (typeof SESSION_BACKENDS)[number];
+/** 记忆持久面方言(→ `MEMORY_ENGINE_BACKEND`)。= server `src/config.ts` :3436 闭集 / 目录 :468 `enumValues` 逐字同序。 */
+export declare const MEMORY_ENGINE_BACKENDS: readonly ["file", "pg", "tidb"];
+export type MemoryEngineBackend = (typeof MEMORY_ENGINE_BACKENDS)[number];

package/dist/execution-lanes.js

@@ -0,0 +1,152 @@
+/**
+ * 执行车道 + 存储后端的**词表正本**(7.0.0,M-R2 WorkerSpec 结构块)。纯数据常量,零函数、零依赖(叶模块:
+ * 本文件不 import 任何东西,`types.ts` 反过来引它)。
+ *
+ * ## 为什么在这里
+ * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
+ * 部署面的车道清单、中心表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
+ *  · 中心写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
+ *  · 中心渲染器按这张表把结构块渲成 env(唯一写者);
+ *  · 引擎提货时从这张表派生自己的车道词表 / 必需键表 / 租户分离位(引擎只留运行期事实,按导入联合类型穷举);
+ *  · 部署面车道清单由这张表生成。
+ * 写闸与起服读同一张表 ⇒ 不会分叉。
+ *
+ * ## 行内容的出处(逐行抄自引擎真码,坐标 = server 7.112.0 树)
+ *  · 车道词与次序:`src/execution-lane-caps.ts` `EXECUTION_LANE_WORDS`(:335)去掉 `in-process` =
+ *    `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
+ *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
+ *    :269 ssh / :288 adb / :308 local-docker / :327 device)。
+ *  · `requiredEnv ∪ requiredSecretEnv`:`src/config.ts` `REQUIRED_ENVS_BY_LANE`(:1054)逐字;按 `src/config-catalog.ts`
+ *    该键那一行的值类型分栏 —— 类型 `secret` / `opaque`(目录自己「绝不回显值」的两类)进 `*SecretEnv`,其余进 `*Env`。
+ *  · `optionalEnv ∪ optionalSecretEnv`:`src/config.ts` `parseOrchestrationDomain` 的 `REMOTE_EXEC` 三元链里**该车道那一臂**
+ *    读的 env 名(:3925 e2b / :3957 k8s / :3991 ssh / :4006 adb / :4014 host / :4026 local-docker / :4055 device;
+ *    臂内调用的解析器 `parseSshHostKeyEnv` :1521、`parseDevicePreAuthPerRemoteEnv` :871、`parseDeviceEnrollTokenTtlEnv` :857
+ *    读的名也算),去掉必需键,同样按目录值类型分栏。**不收**别的域也读的名:k8s 臂里的 `MINIO_ENDPOINT` /
+ *    `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` / `MINIO_REGION` 同时是存储域对象存储的键(`src/config.ts` :1848 / :1872),
+ *    收进车道栏会把它们保留成「k8s 专属」,别的车道就再也设不了快照对象存储。也**不收**臂外的适配器调参键
+ *    (`HOST_BG_*` / `E2B_BG_*` / `K8S_BG_*` / `HOST_SHELL_PATH` …):它们不是车道坐标,照旧走 `env` 逃生口。
+ *
+ * ## 不在表里的词
+ *  · `in-process`:引擎内部「没有 remoteExec」这个状态的名字,不是可声明的车道 —— 显式「无手」的 worker 在模型要用工具时
+ *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
+ *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
+ *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
+ */
+/** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序)。 */
+export const EXECUTION_LANE_WORDS = ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device"];
+/** 车道分不分租户(引擎能力表的 `tenantSeparation` 位,两档,没有「不表态」)。
+ *  `supported` = 每个租户的命令落在各自的目标上;`single-user-only` = 所有任务落同一个共享目标 ⇒ 只许单用户 worker。 */
+export const TENANT_SEPARATION_WORDS = ["supported", "single-user-only"];
+/** 逐车道一行。`satisfies Record<ExecutionLane, …>` = 词表加词而这里不加行 ⇒ 编译红。 */
+const LANE_ROWS = {
+    /** server `config.ts` :4014 臂(无必需键);`execution-lane-caps.ts` :209 `single-user-only`(所有任务落 worker 宿主)。 */
+    host: {
+        tenantSeparation: "single-user-only",
+        requiredEnv: [],
+        requiredSecretEnv: [],
+        optionalEnv: ["HOST_WORKSPACE_BASE", "HOST_COMMAND_TIMEOUT_MS"],
+        optionalSecretEnv: [],
+    },
+    /** server `config.ts` :3925 臂;`E2B_API_KEY` 目录 :351 类型 `secret`、`E2B_SANDBOX_ENV` :359 类型 `secret`;
+     *  `execution-lane-caps.ts` :230 `supported`(每任务一只 microVM)。 */
+    e2b: {
+        tenantSeparation: "supported",
+        requiredEnv: [],
+        requiredSecretEnv: ["E2B_API_KEY"],
+        optionalEnv: ["E2B_TEMPLATE", "E2B_TIMEOUT_MS", "E2B_LIVENESS_MS", "E2B_ALLOW_NET", "E2B_MOUNT_PATH", "E2B_ORPHAN_RECLAIM"],
+        optionalSecretEnv: ["E2B_SANDBOX_ENV"],
+    },
+    /** server `config.ts` :3957 臂;`K8S_TOKEN` 目录 :412 类型 `secret`、`K8S_CA_CERT_B64` :403 类型 `opaque`;
+     *  `execution-lane-caps.ts` :249 `supported`(每任务一只 pod)。`MINIO_*` 刻意不收(见文件头)。 */
+    k8s: {
+        tenantSeparation: "supported",
+        requiredEnv: ["K8S_SANDBOX_IMAGE"],
+        requiredSecretEnv: [],
+        optionalEnv: [
+            "K8S_API_URL",
+            "K8S_INSECURE_TLS",
+            "K8S_NAMESPACE",
+            "K8S_RUNTIME_CLASS",
+            "K8S_MOUNT_PATH",
+            "K8S_TIMEOUT_MS",
+            "K8S_MEMORY",
+            "K8S_CPU",
+            "WORKSPACE_SNAPSHOT_BUCKET",
+            "WORKSPACE_SNAPSHOT_PREFIX",
+            "WORKSPACE_SNAPSHOT_TTL_SEC",
+        ],
+        optionalSecretEnv: ["K8S_TOKEN", "K8S_CA_CERT_B64"],
+    },
+    /** server `config.ts` :3991 臂 + `parseSshHostKeyEnv` :1521;`SSH_PRIVATE_KEY` 目录 :687 类型 `secret`;
+     *  `execution-lane-caps.ts` :269 `single-user-only`(一台跨任务共享的常驻真机)。 */
+    ssh: {
+        tenantSeparation: "single-user-only",
+        requiredEnv: ["SSH_HOST", "SSH_USER"],
+        requiredSecretEnv: ["SSH_PRIVATE_KEY"],
+        optionalEnv: ["SSH_PORT", "SSH_MOUNT_PATH", "SSH_HOST_FINGERPRINT", "SSH_KNOWN_HOSTS"],
+        optionalSecretEnv: [],
+    },
+    /** server `config.ts` :4006 臂;`execution-lane-caps.ts` :288 `single-user-only`(一台跨任务共享的设备)。 */
+    adb: {
+        tenantSeparation: "single-user-only",
+        requiredEnv: ["ADB_SERIAL"],
+        requiredSecretEnv: [],
+        optionalEnv: ["ADB_PATH", "ADB_MOUNT_PATH"],
+        optionalSecretEnv: [],
+    },
+    /** server `config.ts` :4026 臂;`DOCKER_SANDBOX_ENV` 目录 :345 类型 `secret`;`execution-lane-caps.ts` :308 `supported`
+     *  (每任务一只容器)。`DOCKER_HOST` 在本行:远端 docker 守护进程 = 本车道 + `coords.DOCKER_HOST`。 */
+    "local-docker": {
+        tenantSeparation: "supported",
+        requiredEnv: ["DOCKER_IMAGE"],
+        requiredSecretEnv: [],
+        optionalEnv: [
+            "DOCKER_MOUNT_PATH",
+            "DOCKER_PATH",
+            "DOCKER_HOST",
+            "DOCKER_MEMORY",
+            "DOCKER_CPUS",
+            "DOCKER_PIDS_LIMIT",
+            "DOCKER_DROP_CAPS",
+            "DOCKER_NETWORK",
+            "DOCKER_COMMAND_TIMEOUT_MS",
+        ],
+        optionalSecretEnv: ["DOCKER_SANDBOX_ENV"],
+    },
+    /** server `config.ts` :4055 臂 + `parseDevicePreAuthPerRemoteEnv` :871 / `parseDeviceEnrollTokenTtlEnv` :857(无必需键:设备是运行期
+     *  连进来的);`execution-lane-caps.ts` :327 `supported`(发起者自己的设备)。 */
+    device: {
+        tenantSeparation: "supported",
+        requiredEnv: [],
+        requiredSecretEnv: [],
+        optionalEnv: [
+            "DEVICE_DELIVERY_TIMEOUT_MS",
+            "DEVICE_RECONNECT_GRACE_MS",
+            "DEVICE_EXEC_TIMEOUT_MS",
+            "DEVICE_MAX_INFLIGHT_PER_DEVICE",
+            "DEVICE_MAX_PREAUTH_PER_REMOTE",
+            "DEVICE_ENROLL_TOKEN_TTL_SEC",
+            "DEVICE_SUPERSEDE",
+        ],
+        optionalSecretEnv: [],
+    },
+};
+/** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
+export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) => {
+    const row = LANE_ROWS[lane];
+    return Object.freeze({
+        lane,
+        tenantSeparation: row.tenantSeparation,
+        requiredEnv: Object.freeze([...row.requiredEnv]),
+        requiredSecretEnv: Object.freeze([...row.requiredSecretEnv]),
+        optionalEnv: Object.freeze([...row.optionalEnv]),
+        optionalSecretEnv: Object.freeze([...row.optionalSecretEnv]),
+    });
+}));
+/** 存储后端(→ `DB_BACKEND`)。= server `src/config-types.ts` `DB_BACKEND_WORDS`(:67)逐字同序。 */
+export const STORE_BACKENDS = ["mysql", "pg", "local", "memory"];
+/** session 店(→ `SESSION_BACKEND`)。= server `src/config.ts` :1760 `enumEnv("SESSION_BACKEND", …)` 的词表逐字同序
+ *  (`tidb` 不在集内:引擎见之拒启)。 */
+export const SESSION_BACKENDS = ["memory", "mysql", "auto"];
+/** 记忆持久面方言(→ `MEMORY_ENGINE_BACKEND`)。= server `src/config.ts` :3436 闭集 / 目录 :468 `enumValues` 逐字同序。 */
+export const MEMORY_ENGINE_BACKENDS = ["file", "pg", "tidb"];

package/dist/file-edit.js

@@ -95,29 +95,34 @@ export function listRequiredEnvNames(eff, remoteExec, resolvedEnv) {
             add(r.envName, use.domain, use.detail);
     if (remoteExec) {
         const re = remoteExec;
-        if (re.provider === "e2b") {
-            add(re.apiKeyEnv, "remoteExec", "e2b.apiKeyEnv");
-            for (const e of re.sandboxEnv ?? [])
-                add(e, "remoteExec", "e2b.sandboxEnv[]");
-        }
-        else if (re.provider === "k8s") {
-            add(re.tokenEnv, "remoteExec", "k8s.tokenEnv");
-            add(re.caCertEnv, "remoteExec", "k8s.caCertEnv");
-            if (re.s3Snapshot) {
-                add(re.s3Snapshot.accessKeyEnv, "remoteExec", "k8s.s3Snapshot.accessKeyEnv");
-                add(re.s3Snapshot.secretKeyEnv, "remoteExec", "k8s.s3Snapshot.secretKeyEnv");
+        // Exhaustive over the provider words (7.0.0: ⊆ EXECUTION_LANE_WORDS) — a new provider that carries an env-NAME
+        // ref must say so here, or this switch is a compile error (no silent "carries nothing" default).
+        switch (re.provider) {
+            case "e2b":
+                add(re.apiKeyEnv, "remoteExec", "e2b.apiKeyEnv");
+                for (const e of re.sandboxEnv ?? [])
+                    add(e, "remoteExec", "e2b.sandboxEnv[]");
+                break;
+            case "k8s":
+                add(re.tokenEnv, "remoteExec", "k8s.tokenEnv");
+                add(re.caCertEnv, "remoteExec", "k8s.caCertEnv");
+                if (re.s3Snapshot) {
+                    add(re.s3Snapshot.accessKeyEnv, "remoteExec", "k8s.s3Snapshot.accessKeyEnv");
+                    add(re.s3Snapshot.secretKeyEnv, "remoteExec", "k8s.s3Snapshot.secretKeyEnv");
+                }
+                break;
+            case "ssh":
+                add(re.privateKeyEnv, "remoteExec", "ssh.privateKeyEnv");
+                break;
+            case "adb":
+            case "host":
+            case "local-docker":
+                break; // these carry no secret env-NAME refs
+            default: {
+                const unhandled = re;
+                throw new Error(`listRequiredEnvNames: unhandled remoteExec provider ${JSON.stringify(unhandled)}`);
             }
         }
-        else if (re.provider === "ssh") {
-            add(re.privateKeyEnv, "remoteExec", "ssh.privateKeyEnv");
-        }
-        else if (re.provider === "remote-docker") {
-            add(re.tlsCertEnv, "remoteExec", "remote-docker.tlsCertEnv");
-            add(re.tlsKeyEnv, "remoteExec", "remote-docker.tlsKeyEnv");
-            add(re.tlsCaEnv, "remoteExec", "remote-docker.tlsCaEnv");
-            add(re.sshKeyEnv, "remoteExec", "remote-docker.sshKeyEnv");
-        }
-        // adb / host / local-docker carry no secret env-NAME refs.
     }
     return [...map.entries()]
         .map(([envName, refs]) => ({ envName, refs, present: resolvedEnv[envName] !== undefined }))

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;

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、不改入参;文件形的入口是
+ * `npx @sema-agent/settings-schema migrate-workers <file>`(`bin/settings-schema.mjs`,同一只函数;命令拼写的唯一正本 = `MIGRATE_WORKERS_COMMAND`)。
+ *
+ * ## 谁跑、在哪
+ * 读前抬升:在 `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;