@sema-agent/settings-schema 6.3.0 → 7.0.0

package/conformance/migrate-workers/m03-g5-refused-no-lane/input.json

@@ -0,0 +1,42 @@
+{
+  "workers": [
+    {
+      "name": "handless",
+      "enabled": true,
+      "host": "default",
+      "image": "sema-server:latest",
+      "secretRefs": {
+        "apiKeyEnv": "MODEL_KEY"
+      },
+      "runtime": {
+        "sessionBackend": "auto",
+        "memoryBackend": "off",
+        "requirePrincipal": false,
+        "rateLimitRpm": 0
+      },
+      "coords": {}
+    },
+    {
+      "name": "canary",
+      "enabled": true,
+      "host": "default",
+      "image": "sema-server:latest",
+      "secretRefs": {
+        "apiKeyEnv": "MODEL_KEY"
+      },
+      "runtime": {
+        "sessionBackend": "auto",
+        "memoryBackend": "off",
+        "requirePrincipal": false,
+        "rateLimitRpm": 0
+      },
+      "coords": {},
+      "env": {
+        "REMOTE_EXEC": "e2b"
+      },
+      "secretEnv": {
+        "E2B_API_KEY": "HOST_E2B_KEY"
+      }
+    }
+  ]
+}

package/conformance/migrate-workers/m03-g5-refused-no-lane/meta.json

@@ -0,0 +1,4 @@
+{
+  "contributor": "contract",
+  "claim": "G5 refused:enabled 且无 env.REMOTE_EXEC 的 worker(WA-49 病例本身)⇒ refused 点名 env.REMOTE_EXEC,不进输出 doc;同域的 canary(e2b,密钥在 secretEnv)照迁进 runtime.execution.secretRefs。"
+}

package/conformance/migrate-workers/m04-g7b-session-tidb-lifted/expected.json

@@ -0,0 +1,52 @@
+{
+  "doc": {
+    "workers": [
+      {
+        "name": "persist",
+        "enabled": true,
+        "host": "default",
+        "image": "sema-server:latest",
+        "secretRefs": {
+          "apiKeyEnv": "MODEL_KEY",
+          "dbPasswordEnv": "HOST_TIDB_PW"
+        },
+        "runtime": {
+          "requirePrincipal": false,
+          "rateLimitRpm": 0,
+          "execution": {
+            "lane": "host",
+            "coords": {},
+            "secretRefs": {}
+          },
+          "store": {
+            "backend": "mysql",
+            "session": "mysql",
+            "db": {
+              "host": "tidb.internal",
+              "port": 4000,
+              "user": "svc",
+              "database": "sema"
+            }
+          }
+        },
+        "coords": {
+          "gitApiBaseUrl": "https://git.internal"
+        }
+      }
+    ]
+  },
+  "changed": [
+    "persist"
+  ],
+  "dropped": [
+    {
+      "name": "persist",
+      "index": 0,
+      "field": [
+        "runtime",
+        "memoryBackend"
+      ]
+    }
+  ],
+  "refused": []
+}

package/conformance/migrate-workers/m04-g7b-session-tidb-lifted/input.json

@@ -0,0 +1,30 @@
+{
+  "workers": [
+    {
+      "name": "persist",
+      "enabled": true,
+      "host": "default",
+      "image": "sema-server:latest",
+      "secretRefs": {
+        "apiKeyEnv": "MODEL_KEY",
+        "tidbPasswordEnv": "HOST_TIDB_PW"
+      },
+      "runtime": {
+        "sessionBackend": "tidb",
+        "memoryBackend": "off",
+        "requirePrincipal": false,
+        "rateLimitRpm": 0,
+        "db": "sema"
+      },
+      "coords": {
+        "gitApiBaseUrl": "https://git.internal",
+        "tidbHost": "tidb.internal",
+        "tidbPort": 4000,
+        "tidbUser": "svc"
+      },
+      "env": {
+        "REMOTE_EXEC": "host"
+      }
+    }
+  ]
+}

package/conformance/migrate-workers/m04-g7b-session-tidb-lifted/meta.json

@@ -0,0 +1,4 @@
+{
+  "contributor": "contract",
+  "claim": "G7b:旧形 runtime.sessionBackend tidb(今天引擎见之拒启)+ tidb 坐标 ⇒ store {backend: mysql, session: mysql, db} + secretRefs.dbPasswordEnv —— 改成能起的形 + 通知行,不是拒。"
+}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的 workers 文档比旧文档更糟。 */
+export interface SettingsSchemaCliIo {
+    readFile(path: string): Promise<string>;
+    writeFileAtomic(path: string, text: string): Promise<void>;
+    stdout(text: string): void;
+    stderr(text: string): void;
+}
+export declare function runSettingsSchemaCli(argv: readonly string[], io: SettingsSchemaCliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,70 @@
+/**
+ * `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 错;3 = `--check` 且会有改动(不写)。stdout 恒打一行 JSON 报告(`event: "workers_domain_migrated"`,只点名字段、不带值)。
+ */
+import { formatConfigPath, sanitizeZodError } from "./config-fns.js";
+import { migrateWorkersDomain } from "./migrate-workers.js";
+import { DOMAIN_SCHEMAS } from "./types.js";
+const USAGE = [
+    "usage: settings-schema migrate-workers <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).",
+].join("\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);
+    io.stdout(`${JSON.stringify({
+        event: "workers_domain_migrated",
+        file,
+        changed: m.changed,
+        dropped: m.dropped.map((d) => ({ name: d.name, field: formatConfigPath(d.field) })),
+        refused: m.refused.map((r) => ({ name: r.name, field: formatConfigPath(r.field), reason: r.reason })),
+    })}\n`);
+    if (m.refused.length > 0) {
+        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)
+        return 0;
+    if (check)
+        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.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`);
+    return 0;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引**,供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.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;

package/dist/execution-lane-index.js

@@ -0,0 +1,23 @@
+/**
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引**,供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.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}`;
+}

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/hash.d.ts

@@ -23,9 +23,9 @@ export declare const MAX_HASH_WRAPPER_RESERVE = 32;
 /** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
  *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
  *  real free-form value (OpenAI-style request params nest <10 deep).
- *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
- *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
- *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody`, since 1.10.0
+ *  `ModelEntry.compat`, since 6.4.0 `ModelEntry.headers`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`),
+ *  so one cap serves them all. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
  *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export declare const MAX_EXTRA_BODY_DEPTH: number;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */

package/dist/hash.js

@@ -23,9 +23,9 @@ export const MAX_HASH_WRAPPER_RESERVE = 32;
 /** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
  *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
  *  real free-form value (OpenAI-style request params nest <10 deep).
- *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
- *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
- *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody`, since 1.10.0
+ *  `ModelEntry.compat`, since 6.4.0 `ModelEntry.headers`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`),
+ *  so one cap serves them all. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
  *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export const MAX_EXTRA_BODY_DEPTH = MAX_HASH_DEPTH - MAX_HASH_WRAPPER_RESERVE;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */