@sema-agent/settings-schema 6.4.0 → 7.0.0

package/conformance/cases/c68-s784-device-local-store/expected.json

@@ -0,0 +1,83 @@
+{
+  "domains": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "7.0.0 写闸(WorkerSpec)拒 —— workers 是 gate 域,一只坏 worker 整域拒,不逐条容错"
+  },
+  "wire": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "wire 腿把同一份文档交给同一个 buildEffective,拒绝层相同"
+  },
+  "localRoot": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "runtime": {},
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "workers",
+        "file": "workers.json",
+        "kind": "unread-config-file",
+        "why": "non-portable-domain"
+      }
+    ],
+    "metadata": {
+      "version": 2617555914511015,
+      "updatedAt": "1970-01-01T00:00:00.000Z"
+    },
+    "why": "workers 是非便携域:本机腿不读 config.d/workers.json(只报 unread-config-file),写闸判据只在 domains / wire 两腿上可观察"
+  }
+}

package/conformance/cases/c68-s784-device-local-store/input.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-03T00:00:00.000Z"
+  },
+  "domains": {
+    "workers": {
+      "workers": [
+        {
+          "name": "w",
+          "secretRefs": {
+            "apiKeyEnv": "MODEL_KEY"
+          },
+          "runtime": {
+            "execution": {
+              "lane": "device"
+            },
+            "store": {
+              "backend": "local"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c68-s784-device-local-store/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "device 车道 ∧ 非 SQL 店(local)⇒ 拒:设备注册簿 / session↔设备绑定 / 审计都在 SQL 里,引擎 `device-durable-store` 起服即拒 —— 写闸前置同判,不让「声明得了、起不来」的 device worker 过闸(gpt-6 腿 F2)。",
+  "firstRedOn": []
+}

package/conformance/cases/cli04-env-value-with-newline/expected.json

@@ -65,10 +65,21 @@
             "image": "sema-server:latest",
             "name": "w1",
             "runtime": {
-              "memoryBackend": "off",
+              "execution": {
+                "coords": {},
+                "lane": "host",
+                "secretRefs": {}
+              },
               "rateLimitRpm": 0,
               "requirePrincipal": false,
-              "sessionBackend": "auto"
+              "store": {
+                "backend": "local",
+                "memory": {
+                  "backend": "file",
+                  "engine": "on"
+                },
+                "session": "auto"
+              }
             },
             "secretRefs": {
               "apiKeyEnv": "OPENAI_API_KEY"

package/conformance/cases/cli04-env-value-with-newline/input.json

@@ -8,7 +8,14 @@
       "workers": [
         {
           "name": "w1",
-          "runtime": {},
+          "runtime": {
+            "execution": {
+              "lane": "host"
+            },
+            "store": {
+              "backend": "local"
+            }
+          },
           "secretRefs": {
             "apiKeyEnv": "OPENAI_API_KEY"
           },

package/conformance/cases/cli04-env-value-with-newline/meta.json

@@ -1,5 +1,5 @@
 {
   "contributor": "cli",
-  "claim": "壳视角④:worker 的 env 值里有换行 / 回车 ⇒ 读侧**原样承运**(不折叠、不截断、不静默改写)。壳的 `/config show` 单行渲染会断行,那是显示面的事;读侧一改,配置就与运维写下的不是同一份。注意这一域是非便携域:local-root 腿看不到它,只报 unread-config-file —— 三腿三样,壳要知道自己问的是哪一腿。",
+  "claim": "壳视角④:worker 的 env 值里有换行 / 回车 ⇒ 读侧**原样承运**(不折叠、不截断、不静默改写)。壳的 `/config show` 单行渲染会断行,那是显示面的事;读侧一改,配置就与运维写下的不是同一份。注意这一域是非便携域:local-root 腿看不到它,只报 unread-config-file —— 三腿三样,壳要知道自己问的是哪一腿。 (7.0.0:输入的 worker 改成 7.0.0 形 —— 显式声明 `runtime.execution {lane: host}` + `runtime.store {backend: local}`。6.x 原输入是 enabled 且无车道的 `runtime: {}`,正是 WA-49 病例,一次性迁移对它是 refused,迁不出可读形;本条要打的是 env 值的承运,与车道无关,所以按新形写明车道,不是放宽读侧。)",
   "firstRedOn": []
 }

package/conformance/migrate-workers/m01-g5-k8s-env-lifted/expected.json

@@ -0,0 +1,49 @@
+{
+  "doc": {
+    "workers": [
+      {
+        "name": "direct",
+        "enabled": true,
+        "host": "default",
+        "image": "sema-server:latest",
+        "secretRefs": {
+          "apiKeyEnv": "MODEL_KEY"
+        },
+        "runtime": {
+          "requirePrincipal": false,
+          "rateLimitRpm": 0,
+          "execution": {
+            "lane": "k8s",
+            "coords": {
+              "K8S_SANDBOX_IMAGE": "registry.internal/sandbox@sha256:abc",
+              "K8S_NAMESPACE": "sandboxes"
+            },
+            "secretRefs": {}
+          },
+          "store": {
+            "backend": "local",
+            "session": "auto"
+          }
+        },
+        "coords": {},
+        "env": {
+          "LOG_LEVEL": "debug"
+        }
+      }
+    ]
+  },
+  "changed": [
+    "direct"
+  ],
+  "dropped": [
+    {
+      "name": "direct",
+      "index": 0,
+      "field": [
+        "runtime",
+        "memoryBackend"
+      ]
+    }
+  ],
+  "refused": []
+}

package/conformance/migrate-workers/m01-g5-k8s-env-lifted/input.json

@@ -0,0 +1,26 @@
+{
+  "workers": [
+    {
+      "name": "direct",
+      "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": "k8s",
+        "K8S_SANDBOX_IMAGE": "registry.internal/sandbox@sha256:abc",
+        "K8S_NAMESPACE": "sandboxes",
+        "LOG_LEVEL": "debug"
+      }
+    }
+  ]
+}

package/conformance/migrate-workers/m01-g5-k8s-env-lifted/meta.json

@@ -0,0 +1,4 @@
+{
+  "contributor": "contract",
+  "claim": "G5 正臂:6.x 活舰队形(env.REMOTE_EXEC=k8s + 同车道 K8S_*)⇒ runtime.execution {lane: k8s, coords 搬入},env 里两键消失、非车道键留下;memoryBackend 进 dropped(从未生效);无 SQL 坐标 ⇒ store.backend local。"
+}

package/conformance/migrate-workers/m02-g5-idempotent/expected.json

@@ -0,0 +1,38 @@
+{
+  "doc": {
+    "workers": [
+      {
+        "name": "direct",
+        "enabled": true,
+        "host": "default",
+        "image": "sema-server:latest",
+        "secretRefs": {
+          "apiKeyEnv": "MODEL_KEY"
+        },
+        "runtime": {
+          "requirePrincipal": false,
+          "rateLimitRpm": 0,
+          "execution": {
+            "lane": "k8s",
+            "coords": {
+              "K8S_SANDBOX_IMAGE": "registry.internal/sandbox@sha256:abc",
+              "K8S_NAMESPACE": "sandboxes"
+            },
+            "secretRefs": {}
+          },
+          "store": {
+            "backend": "local",
+            "session": "auto"
+          }
+        },
+        "coords": {},
+        "env": {
+          "LOG_LEVEL": "debug"
+        }
+      }
+    ]
+  },
+  "changed": [],
+  "dropped": [],
+  "refused": []
+}

package/conformance/migrate-workers/m02-g5-idempotent/input.json

@@ -0,0 +1,33 @@
+{
+  "workers": [
+    {
+      "name": "direct",
+      "enabled": true,
+      "host": "default",
+      "image": "sema-server:latest",
+      "secretRefs": {
+        "apiKeyEnv": "MODEL_KEY"
+      },
+      "runtime": {
+        "requirePrincipal": false,
+        "rateLimitRpm": 0,
+        "execution": {
+          "lane": "k8s",
+          "coords": {
+            "K8S_SANDBOX_IMAGE": "registry.internal/sandbox@sha256:abc",
+            "K8S_NAMESPACE": "sandboxes"
+          },
+          "secretRefs": {}
+        },
+        "store": {
+          "backend": "local",
+          "session": "auto"
+        }
+      },
+      "coords": {},
+      "env": {
+        "LOG_LEVEL": "debug"
+      }
+    }
+  ]
+}

package/conformance/migrate-workers/m02-g5-idempotent/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "G5 幂等:输入 = m01 的迁移输出(已迁形)⇒ changed / dropped / refused 全空,doc 字节相等。input.json 由加冕脚本从 m01 的 expected 生成,不手写。",
+  "inputFrom": "m01-g5-k8s-env-lifted"
+}

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

@@ -0,0 +1,71 @@
+{
+  "doc": {
+    "workers": [
+      {
+        "name": "canary",
+        "enabled": true,
+        "host": "default",
+        "image": "sema-server:latest",
+        "secretRefs": {
+          "apiKeyEnv": "MODEL_KEY"
+        },
+        "runtime": {
+          "requirePrincipal": false,
+          "rateLimitRpm": 0,
+          "execution": {
+            "lane": "e2b",
+            "coords": {},
+            "secretRefs": {
+              "E2B_API_KEY": "HOST_E2B_KEY"
+            }
+          },
+          "store": {
+            "backend": "local",
+            "session": "auto"
+          }
+        },
+        "coords": {}
+      }
+    ]
+  },
+  "changed": [
+    "canary"
+  ],
+  "dropped": [
+    {
+      "name": "canary",
+      "index": 1,
+      "field": [
+        "runtime",
+        "memoryBackend"
+      ]
+    }
+  ],
+  "refused": [
+    {
+      "name": "handless",
+      "index": 0,
+      "field": [
+        "env",
+        "REMOTE_EXEC"
+      ],
+      "reason": "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 (host | e2b | k8s | ssh | adb | local-docker | device) by hand, or disable the worker",
+      "original": {
+        "name": "handless",
+        "enabled": true,
+        "host": "default",
+        "image": "sema-server:latest",
+        "secretRefs": {
+          "apiKeyEnv": "MODEL_KEY"
+        },
+        "runtime": {
+          "sessionBackend": "auto",
+          "memoryBackend": "off",
+          "requirePrincipal": false,
+          "rateLimitRpm": 0
+        },
+        "coords": {}
+      }
+    }
+  ]
+}

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}`;
+}