@sema-agent/settings-schema 1.0.0

package/dist/migrate.js

@@ -0,0 +1,542 @@
+import { RESERVED_WORKER_ENV } from "./types.js";
+/** 存量 hosts grandfathering(§2-2):对既有条目批量回填 `approved:true` 并剥掉 `capacity`。幂等——
+ *  已带 approved 的条目保持原值(重跑不覆盖 admin 手动置回待批的机器)。 */
+export function grandfatherHosts(rawHosts) {
+    if (rawHosts === null || typeof rawHosts !== "object" || !Array.isArray(rawHosts.hosts)) {
+        return { hosts: undefined, approvedBackfilled: [], capacityStripped: [] };
+    }
+    const approvedBackfilled = [];
+    const capacityStripped = [];
+    const hosts = (rawHosts.hosts).map((h) => {
+        if (h === null || typeof h !== "object")
+            return h;
+        const entry = { ...h };
+        const name = typeof entry.name === "string" ? entry.name : "(unnamed)";
+        if (entry.approved === undefined) {
+            entry.approved = true; // grandfathering:存量机器已在编,不因契约升级退回待批
+            approvedBackfilled.push(name);
+        }
+        if ("capacity" in entry) {
+            delete entry.capacity; // 0.6.0 契约已删;留着也会被 zod strip,主动剥干净便于 diff 审计
+            capacityStripped.push(name);
+        }
+        return entry;
+    });
+    return { hosts: { ...rawHosts, hosts }, approvedBackfilled, capacityStripped };
+}
+const catalogName = (modelId) => {
+    const n = modelId.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "");
+    return /^[a-z0-9]/.test(n) ? n : `m-${n || "model"}`;
+};
+/** 规范容器内 env 名:MODEL_KEY_<NAME>(§3 apiKeyEnv 命名空间转换)。 */
+export const canonicalModelKeyEnv = (name) => `MODEL_KEY_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "MODEL"}`;
+const signatureOf = (m, hostKeyEnv) => JSON.stringify({ provider: m.provider ?? "gateway", baseUrl: m.gatewayBaseUrl ?? "", key: hostKeyEnv, cost: m.cost ?? null });
+/** 扫描存量 workers 的 model 七字段,产出 models 目录条目草稿 + 冲突报告 + cheapId→roster 计划。
+ *  `existingModelNames` = 现 models 目录已占用的 name(避让后缀)。PURE——不写任何东西。
+ *  0.6.3:`opts.existingModels` 给出现目录条目时做内容级去重——worker.model 与既有条目 (id, provider,
+ *  baseUrl) 相同 → 复用(进 `reuses`,不出新草稿;缺 apiKeyEnv 的条目给回填建议)。 */
+export function planWorkerModelMigration(workers, existingModelNames = [], opts = {}) {
+    const drafts = [];
+    const conflicts = [];
+    const reuses = [];
+    const rosterActions = [];
+    const report = [];
+    const existing = opts.existingModels ?? [];
+    const usedNames = new Set([...existingModelNames, ...existing.map((e) => e.name)]);
+    // modelId → (signature → draft)
+    const byId = new Map();
+    // 复用聚合:entryName → reuse(同条目多 worker 归并;宿主名不一致=真冲突,进 conflicts)
+    const reuseByEntry = new Map();
+    const claimName = (base) => {
+        let name = base;
+        for (let i = 2; usedNames.has(name); i++)
+            name = `${base}-${i}`;
+        usedNames.add(name);
+        return name;
+    };
+    const upsert = (worker, m, hostKeyEnv, modelId, opts = {}) => {
+        // 0.6.4(W3/MINOR-1):cheap 条目身份与**主模型价格无关**(cheap 草稿 cost 恒 undefined,E1 裁定不照搬
+        // 主模型价)——cheap 签名剔除 cost,两 worker 同 cheapId 仅主模型价不同不再拆条目误报冲突(误报会连带
+        // 阻断整条 rosterAction,爆炸半径大于表面)。主模型签名仍含 cost(§3:cost 不同=拆条目,契约不变)。
+        const sig = signatureOf(opts.cheapOf ? { provider: m.provider, gatewayBaseUrl: m.gatewayBaseUrl } : m, hostKeyEnv);
+        const sigs = byId.get(modelId) ?? new Map();
+        byId.set(modelId, sigs);
+        let d = sigs.get(sig);
+        // cheap 挂靠:忽略 cost 维度找同 (provider, baseUrl, 宿主 key) 的既有草稿(如该 modelId 已被别的
+        // worker 作主模型合成过)——挂靠主形草稿定价真实,优于另造无价 cheap 条目。
+        if (!d && opts.cheapOf) {
+            d = [...sigs.values()].find((x) => x.entry.provider === (m.provider ?? "gateway") && (x.entry.baseUrl ?? "") === (m.gatewayBaseUrl ?? "") && x.hostApiKeyEnv === hostKeyEnv);
+            if (d) {
+                if (!d.sourceWorkers.includes(worker))
+                    d.sourceWorkers.push(worker);
+                return d;
+            }
+        }
+        if (!d) {
+            const name = claimName(catalogName(modelId));
+            const provider = m.provider ?? "gateway";
+            d = {
+                entry: {
+                    name,
+                    id: modelId,
+                    provider,
+                    api: provider === "anthropic" ? "anthropic-messages" : "openai-completions",
+                    baseUrl: m.gatewayBaseUrl || undefined,
+                    apiKeyEnv: canonicalModelKeyEnv(name),
+                    reasoning: opts.cheapOf ? undefined : m.reasoning || undefined,
+                    maxTokens: opts.cheapOf ? undefined : m.maxTokens,
+                    contextWindow: opts.cheapOf ? undefined : m.contextWindow,
+                    // cheap 草稿不照搬主模型 cost:worker.model 只有主模型单一价,copy 给 cheap 条目=错误定价喂给
+                    // prefer:cheapest/quota-weight 消费方;留空更安全(types.ts 口径 missing cost ≠ cheapest),
+                    // E3 人工确认时补价(E1 评审 MINOR)。
+                    cost: opts.cheapOf ? undefined : m.cost,
+                    notes: opts.cheapOf ? `migrated from worker.model.cheapId (worker "${opts.cheapOf}")` : `migrated from worker.model (worker "${worker}")`,
+                },
+                sourceWorkers: [],
+                hostApiKeyEnv: hostKeyEnv,
+            };
+            sigs.set(sig, d);
+            drafts.push(d);
+            if (sigs.size > 1) {
+                const names = [...sigs.values()].map((x) => x.entry.name);
+                conflicts.push({ modelId, entryNames: names, reason: `same modelId "${modelId}" with differing gatewayBaseUrl/apiKeyEnv/cost/provider — split into ${names.length} entries (人工确认后再执行)` });
+                report.push(`⚠️ conflict: modelId "${modelId}" → entries [${names.join(", ")}] (signatures differ)`);
+            }
+        }
+        if (!d.sourceWorkers.includes(worker))
+            d.sourceWorkers.push(worker);
+        return d;
+    };
+    /** 0.6.3 内容级去重:worker.model 与既有条目 (id, provider, baseUrl) 相同 → 复用。返回 undefined=无匹配走草稿。
+     *  0.6.4(W1/C1,PM 裁定):`compareFields`(仅主模型路径——cheapId 路径的 m 是主模型对象,四字段不属于
+     *  cheap)时对 cost/maxTokens/contextWindow/reasoning 逐字段比对:worker.model 侧有值且与条目不一致 →
+     *  **降级为冲突**(仍记 reuse 占位防重复草稿,但 apply 按 conflictedEntryNames 整条跳过进人工确认段;
+     *  不静默采用条目侧)。worker.model 侧缺值=退化存量,不算冲突(目录为前进方向真值)。 */
+    const tryReuse = (worker, m, hostKeyEnv, modelId, compareFields = false) => {
+        const e = existing.find((x) => x.id === modelId && (x.provider ?? "gateway") === (m.provider ?? "gateway") && (x.baseUrl ?? "") === (m.gatewayBaseUrl ?? ""));
+        if (!e)
+            return undefined;
+        if (compareFields) {
+            const diffs = [];
+            const fmt = (v) => (v === undefined ? "(unset)" : JSON.stringify(v));
+            if (m.cost !== undefined && JSON.stringify(m.cost) !== JSON.stringify(e.cost))
+                diffs.push(`cost ${fmt(m.cost)} ≠ ${fmt(e.cost)}`);
+            if (m.maxTokens !== undefined && m.maxTokens !== e.maxTokens)
+                diffs.push(`maxTokens ${fmt(m.maxTokens)} ≠ ${fmt(e.maxTokens)}`);
+            if (m.contextWindow !== undefined && m.contextWindow !== e.contextWindow)
+                diffs.push(`contextWindow ${fmt(m.contextWindow)} ≠ ${fmt(e.contextWindow)}`);
+            if (m.reasoning !== undefined && !!m.reasoning !== !!e.reasoning)
+                diffs.push(`reasoning ${fmt(!!m.reasoning)} ≠ ${fmt(!!e.reasoning)}`);
+            if (diffs.length) {
+                conflicts.push({ modelId, entryNames: [e.name], reason: `worker "${worker}" model 与既有条目 "${e.name}" 字段不一致(${diffs.join("; ")})— REUSE 降级为冲突,不静默采用,人工确认后再执行` });
+                report.push(`⚠️ conflict: worker "${worker}" model "${modelId}" vs catalog "${e.name}" — ${diffs.join("; ")}(REUSE 降级为冲突,人工确认)`);
+            }
+        }
+        let r = reuseByEntry.get(e.name);
+        if (!r) {
+            const backfill = e.apiKeyEnv ? undefined : canonicalModelKeyEnv(e.name);
+            r = { entryName: e.name, modelId, sourceWorkers: [], hostApiKeyEnv: hostKeyEnv, apiKeyEnvBackfill: backfill, containerApiKeyEnv: e.apiKeyEnv ?? backfill };
+            reuseByEntry.set(e.name, r);
+            reuses.push(r);
+        }
+        else if (r.hostApiKeyEnv !== hostKeyEnv) {
+            // 同一条目、不同宿主 key——接线单二义,人工裁决(不静默择一)。
+            conflicts.push({ modelId, entryNames: [e.name], reason: `existing entry "${e.name}" reused by workers with differing host apiKeyEnv ("${r.hostApiKeyEnv}" vs "${hostKeyEnv}") — wiring ambiguous, 人工确认后再执行` });
+            report.push(`⚠️ conflict: entry "${e.name}" host apiKeyEnv differs across workers ("${r.hostApiKeyEnv}" vs "${hostKeyEnv}" @ ${worker})`);
+        }
+        if (!r.sourceWorkers.includes(worker))
+            r.sourceWorkers.push(worker);
+        return r;
+    };
+    for (const w of workers) {
+        const m = w.model;
+        if (!m || !m.modelId)
+            continue;
+        const hostKeyEnv = w.secretRefs?.apiKeyEnv ?? "";
+        const mainReuse = tryReuse(w.name, m, hostKeyEnv, m.modelId, true);
+        const main = mainReuse ?? upsert(w.name, m, hostKeyEnv, m.modelId);
+        const mainName = mainReuse ? mainReuse.entryName : main.entry.name;
+        const mainKey = mainReuse ? mainReuse.containerApiKeyEnv : main.entry.apiKeyEnv;
+        report.push(mainReuse
+            ? `worker "${w.name}": model "${m.modelId}" → REUSE existing catalog "${mainName}" (apiKeyEnv ${hostKeyEnv || "(unset)"} → ${mainKey}${mainReuse.apiKeyEnvBackfill ? ", 回填条目 apiKeyEnv" : ""})`
+            : `worker "${w.name}": model "${m.modelId}" → catalog "${mainName}" (apiKeyEnv ${hostKeyEnv || "(unset)"} → ${mainKey})`);
+        let cheapName;
+        if (m.cheapId) {
+            const cheapReuse = tryReuse(w.name, m, hostKeyEnv, m.cheapId);
+            if (cheapReuse) {
+                cheapName = cheapReuse.entryName;
+                report.push(`worker "${w.name}": cheapId "${m.cheapId}" → REUSE existing catalog "${cheapName}" + roster cheapModel 标记(0.6.3)`);
+            }
+            else {
+                const cheap = upsert(w.name, m, hostKeyEnv, m.cheapId, { cheapOf: w.name });
+                cheapName = cheap.entry.name;
+                // 挂靠到主形草稿(定价真实)时不再误报"未定价";只有真·无价 cheap 草稿才提示人工补价。
+                report.push(cheap.entry.cost !== undefined
+                    ? `worker "${w.name}": cheapId "${m.cheapId}" → catalog "${cheapName}"(挂靠既有草稿)+ roster cheapModel 标记(0.6.3)`
+                    : `worker "${w.name}": cheapId "${m.cheapId}" → catalog "${cheapName}" + roster cheapModel 标记(0.6.3)⚠️ cheap 条目未定价(源数据无 cheap 独立价,不沿用主模型 cost),E3 落库前请人工核对补价`);
+            }
+        }
+        rosterActions.push({ worker: w.name, mainModel: mainName, cheapModel: cheapName });
+    }
+    // 0.6.4(C2a):容器内 env 名全局碰撞检测——canonicalModelKeyEnv 把非字母数字折叠成 "_"(foo-bar/foo_bar/
+    // foo.bar 同名),不同条目分到同一容器 env 名且**宿主 key 不同**时接线互踩(后写者被静默跳过)→ 冲突进
+    // 人工段。宿主 key 相同的碰撞无歧义(同值幂等,两模型共享一把 key 属合法形态),放行。
+    {
+        const byEnv = new Map();
+        const claim = (env, u) => {
+            const arr = byEnv.get(env);
+            if (arr)
+                arr.push(u);
+            else
+                byEnv.set(env, [u]);
+        };
+        for (const d of drafts)
+            claim(d.entry.apiKeyEnv, { entryName: d.entry.name, modelId: d.entry.id, hostKey: d.hostApiKeyEnv });
+        for (const r of reuses)
+            claim(r.containerApiKeyEnv, { entryName: r.entryName, modelId: r.modelId, hostKey: r.hostApiKeyEnv });
+        for (const [env, users] of byEnv) {
+            const names = [...new Set(users.map((u) => u.entryName))];
+            const hostKeys = [...new Set(users.map((u) => u.hostKey))];
+            if (names.length > 1 && hostKeys.length > 1) {
+                conflicts.push({ modelId: [...new Set(users.map((u) => u.modelId))].join(" / "), entryNames: names, reason: `container apiKeyEnv "${env}" 被多个条目占用 [${names.join(", ")}] 且宿主 key 不一致 [${hostKeys.join(", ")}] — 接线互踩,人工改条目名/apiKeyEnv 后再执行` });
+                report.push(`⚠️ conflict: container env "${env}" collision across entries [${names.join(", ")}] with differing host keys [${hostKeys.join(", ")}]`);
+            }
+        }
+    }
+    report.push(`plan: ${drafts.length} catalog draft(s), ${reuses.length} reuse(s), ${conflicts.length} conflict(s), ${rosterActions.length} worker roster action(s) — REPORT ONLY, nothing written (E3 executes after 人工确认).`);
+    return { drafts, conflicts, reuses, rosterActions, report };
+}
+/** roster 的"生效主模型"(标记优先,退回显式 roles.default 的 {model} 形)——find-or-assign 的匹配键。 */
+const rosterEffPrimary = (r) => r.primaryModel ?? (r.roles?.default?.model);
+const rosterEffCheap = (r) => r.cheapModel ?? (r.roles?.subagent?.model);
+/**
+ * 执行迁移计划(§3②③;**不删 worker.model**——真删=0.7):
+ *  1. models:追加非冲突草稿(同名已存在=幂等跳过);复用条目缺 apiKeyEnv 时回填规范名。
+ *  2. rosters:有 roster 的 worker → 该 roster 落 primaryModel/cheapModel 标记(已设且不同=skip 报冲突;
+ *     标记模型不在 roster.models 子集时补进子集);无 roster 的 worker → 指认「生效主/cheap 相同」的既有
+ *     roster,否则按主模型名新建。
+ *  3. workers:secretEnv 接线 {容器内 apiKeyEnv ← 宿主 secretRefs.apiKeyEnv}(已接/宿主名缺失=跳过)+
+ *     无 roster 的 worker 写入指认结果。
+ * 幂等:对自身输出重跑 changes=[]。冲突 modelId 关联的 rosterAction/接线整条跳过(人工确认段)。
+ */
+export function applyModelMigrationPlan(plan, docs) {
+    const changes = [];
+    const skipped = [];
+    const models = { ...docs.models, models: docs.models.models.map((m) => ({ ...m })) };
+    const rosters = { ...docs.rosters, rosters: docs.rosters.rosters.map((r) => ({ ...r, models: r.models ? [...r.models] : r.models })) };
+    const workers = { ...docs.workers, workers: docs.workers.workers.map((w) => ({ ...w, secretEnv: w.secretEnv ? { ...w.secretEnv } : w.secretEnv })) };
+    const conflictedEntryNames = new Set(plan.conflicts.flatMap((c) => c.entryNames));
+    // 1a. 追加非冲突草稿
+    for (const d of plan.drafts) {
+        if (conflictedEntryNames.has(d.entry.name)) {
+            skipped.push(`draft "${d.entry.name}" (modelId "${d.entry.id}") — conflicted, 人工确认后再执行`);
+            continue;
+        }
+        if (models.models.some((m) => m.name === d.entry.name))
+            continue; // 幂等
+        models.models.push({ ...d.entry });
+        changes.push(`models: +"${d.entry.name}" (id ${d.entry.id}, apiKeyEnv ${d.entry.apiKeyEnv})`);
+    }
+    // 1b. 复用条目 apiKeyEnv 回填
+    for (const r of plan.reuses) {
+        if (conflictedEntryNames.has(r.entryName)) {
+            skipped.push(`reuse "${r.entryName}" — conflicted(字段不一致 / host apiKeyEnv 二义 / env 碰撞), 人工确认后再执行`);
+            continue;
+        }
+        const e = models.models.find((m) => m.name === r.entryName);
+        if (!e) {
+            skipped.push(`reuse "${r.entryName}" — entry no longer in catalog`);
+            continue;
+        }
+        if (r.apiKeyEnvBackfill && !e.apiKeyEnv) {
+            e.apiKeyEnv = r.apiKeyEnvBackfill;
+            changes.push(`models: "${r.entryName}" apiKeyEnv 回填 → ${r.apiKeyEnvBackfill}`);
+        }
+    }
+    const entryKey = (name) => {
+        const reuse = plan.reuses.find((x) => x.entryName === name);
+        if (reuse)
+            return reuse.containerApiKeyEnv;
+        const d = plan.drafts.find((x) => x.entry.name === name);
+        if (d)
+            return d.entry.apiKeyEnv;
+        return models.models.find((m) => m.name === name)?.apiKeyEnv;
+    };
+    const entryHostKey = (name) => plan.reuses.find((x) => x.entryName === name)?.hostApiKeyEnv ?? plan.drafts.find((x) => x.entry.name === name)?.hostApiKeyEnv;
+    const usedRosterNames = new Set(rosters.rosters.map((r) => r.name));
+    const claimRosterName = (base) => {
+        const b = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "") || "roster";
+        let name = /^[a-z0-9]/.test(b) ? b : `r-${b}`;
+        for (let i = 2; usedRosterNames.has(name); i++)
+            name = `${b}-${i}`;
+        usedRosterNames.add(name);
+        return name;
+    };
+    /** 标记落到 roster;若 roster.models 是非空子集且缺该模型名,补进子集(否则 PUT 校验拒)。 */
+    const setMarker = (r, field, model) => {
+        if (r[field] === model)
+            return;
+        if (r[field] && r[field] !== model) {
+            skipped.push(`roster "${r.name}" ${field} already "${r[field]}" ≠ "${model}" — 不覆盖,人工裁决`);
+            return;
+        }
+        r[field] = model;
+        if (r.models && r.models.length && !r.models.includes(model)) {
+            r.models.push(model);
+            changes.push(`rosters: "${r.name}" models += "${model}"(标记子集一致性)`);
+        }
+        changes.push(`rosters: "${r.name}" ${field} = "${model}"`);
+    };
+    // 2. roster 标记与指认:先处理已有 roster 的 worker(落标记),再给无 roster 的 worker 指认/新建
+    const actionable = plan.rosterActions.filter((a) => {
+        const bad = [a.mainModel, a.cheapModel].filter((n) => !!n).filter((n) => conflictedEntryNames.has(n));
+        if (bad.length) {
+            skipped.push(`worker "${a.worker}" roster action — 冲突条目 [${bad.join(", ")}], 人工确认后再执行`);
+            return false;
+        }
+        return true;
+    });
+    for (const a of actionable) {
+        const w = workers.workers.find((x) => x.name === a.worker);
+        if (!w?.roster)
+            continue;
+        const r = rosters.rosters.find((x) => x.name === w.roster);
+        if (!r) {
+            skipped.push(`worker "${a.worker}" → roster "${w.roster}" not found(dangling ref)`);
+            continue;
+        }
+        setMarker(r, "primaryModel", a.mainModel);
+        if (a.cheapModel)
+            setMarker(r, "cheapModel", a.cheapModel);
+    }
+    for (const a of actionable) {
+        const w = workers.workers.find((x) => x.name === a.worker);
+        if (!w || w.roster)
+            continue;
+        let target = rosters.rosters.find((r) => rosterEffPrimary(r) === a.mainModel && (a.cheapModel ? rosterEffCheap(r) === a.cheapModel : rosterEffCheap(r) === undefined));
+        // 次选:主模型相同、cheap 不冲突(目标无 cheap 而 roster 有)也可指认——worker 原本无 cheapId,roster 的 cheap 只多不少
+        target ??= a.cheapModel ? undefined : rosters.rosters.find((r) => rosterEffPrimary(r) === a.mainModel);
+        if (!target) {
+            const name = claimRosterName(a.mainModel);
+            target = { name, models: a.cheapModel ? [a.mainModel, a.cheapModel] : [a.mainModel], primaryModel: a.mainModel, ...(a.cheapModel ? { cheapModel: a.cheapModel } : {}) };
+            rosters.rosters.push(target);
+            changes.push(`rosters: +"${name}" (primaryModel "${a.mainModel}"${a.cheapModel ? `, cheapModel "${a.cheapModel}"` : ""})`);
+        }
+        else {
+            setMarker(target, "primaryModel", a.mainModel);
+            if (a.cheapModel)
+                setMarker(target, "cheapModel", a.cheapModel);
+        }
+        w.roster = target.name;
+        changes.push(`workers: "${w.name}" roster = "${target.name}"`);
+    }
+    // 3. secretEnv 接线:容器内 apiKeyEnv ← 宿主名(不动 worker.model;specHash 变化=滚动重建的触发点)
+    for (const a of actionable) {
+        const w = workers.workers.find((x) => x.name === a.worker);
+        if (!w)
+            continue;
+        for (const entryName of [a.mainModel, a.cheapModel].filter((n) => !!n)) {
+            const container = entryKey(entryName);
+            const host = entryHostKey(entryName);
+            if (!container) {
+                skipped.push(`worker "${a.worker}" wiring "${entryName}" — 条目无 apiKeyEnv,跳过`);
+                continue;
+            }
+            if (!host) {
+                skipped.push(`worker "${a.worker}" wiring "${entryName}" — 宿主 apiKeyEnv 缺失(secretRefs.apiKeyEnv 未设),跳过`);
+                continue;
+            }
+            if (RESERVED_WORKER_ENV.has(container)) {
+                skipped.push(`worker "${a.worker}" wiring "${entryName}" — 容器名 "${container}" 是保留键(schema 拒 secretEnv 设置),人工改条目 apiKeyEnv`);
+                continue;
+            }
+            const cur = w.secretEnv?.[container];
+            if (cur === host)
+                continue; // 已接同值(幂等)
+            // 0.6.4(C2b):现值≠期望宿主名 → 不再静默接受过时/错误映射,进人工确认段(也不覆盖——覆盖可能打断在用接线)。
+            if (cur !== undefined) {
+                skipped.push(`worker "${a.worker}" wiring "${entryName}" — secretEnv["${container}"] 现值 "${cur}" ≠ 期望宿主名 "${host}",不覆盖,人工确认`);
+                continue;
+            }
+            w.secretEnv = { ...(w.secretEnv ?? {}), [container]: host };
+            changes.push(`workers: "${w.name}" secretEnv["${container}"] = "${host}"(宿主名)`);
+        }
+    }
+    return { models, rosters, workers, changes, skipped };
+}
+// ── 4. 迁移 diff 白名单门(0.6.4, E3 双评审 C3)—— PURE:apply 前后三域对比,只放行迁移的预期改动 ──────
+const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/**
+ * 迁移执行的**行为等价门**(C3,与 refIntegrityIssues 双门同点位):对 {@link applyModelMigrationPlan}
+ * 的前后三域做白名单式结构 diff——只允许迁移语义内的预期变更,任何意外漂移返回违规行(调用方 fail-closed
+ * 400,不落库)。白名单:
+ *  - models:只许**新增**条目、既有条目只许 apiKeyEnv 从缺 → 有(回填);不许删、不许改其它字段。
+ *  - rosters:只许新增 roster(且只带 name/models/primaryModel/cheapModel 四键);既有 roster 只许
+ *    primaryModel/cheapModel 从缺 → 有、models 子集**追加**(且追加项必须是该 roster 的主/cheap 标记)。
+ *  - workers:不许增删;每个 worker 只许 roster 从缺 → 有(指认)、secretEnv **添键且值严格匹配计划内
+ *    (容器名 → 宿主名) 接线映射**(既有键不许动);其余键(含 model——真删=0.7)逐键必须不变。
+ * 空数组 = 通过。PURE,无 I/O。
+ */
+export function migrationDiffViolations(plan, before, after) {
+    const v = [];
+    // 计划内接线映射:容器 env 名 → 允许的宿主名集合(drafts + reuses)。新增 secretEnv 键必须命中。
+    const expectedWiring = new Map();
+    const allow = (container, host) => {
+        const s = expectedWiring.get(container);
+        if (s)
+            s.add(host);
+        else
+            expectedWiring.set(container, new Set([host]));
+    };
+    for (const d of plan.drafts)
+        allow(d.entry.apiKeyEnv, d.hostApiKeyEnv);
+    for (const r of plan.reuses)
+        allow(r.containerApiKeyEnv, r.hostApiKeyEnv);
+    // models
+    {
+        const afterBy = new Map(after.models.models.map((m) => [m.name, m]));
+        for (const b of before.models.models) {
+            const a = afterBy.get(b.name);
+            if (!a) {
+                v.push(`models: 条目 "${b.name}" 被删除(迁移不许删)`);
+                continue;
+            }
+            for (const k of new Set([...Object.keys(b), ...Object.keys(a)])) {
+                if (k === "apiKeyEnv" && b.apiKeyEnv === undefined && typeof a.apiKeyEnv === "string")
+                    continue; // 回填
+                if (!sameJson(b[k], a[k]))
+                    v.push(`models: "${b.name}".${k} 意外变更(${JSON.stringify(b[k])} → ${JSON.stringify(a[k])})`);
+            }
+        }
+    }
+    // rosters
+    {
+        const beforeBy = new Map(before.rosters.rosters.map((r) => [r.name, r]));
+        const afterNames = new Set(after.rosters.rosters.map((r) => r.name));
+        for (const b of before.rosters.rosters)
+            if (!afterNames.has(b.name))
+                v.push(`rosters: "${b.name}" 被删除(迁移不许删)`);
+        for (const a of after.rosters.rosters) {
+            const b = beforeBy.get(a.name);
+            if (!b) {
+                const extra = Object.keys(a).filter((k) => !["name", "models", "primaryModel", "cheapModel"].includes(k));
+                if (extra.length)
+                    v.push(`rosters: 新建 "${a.name}" 带白名单外键 [${extra.join(", ")}]`);
+                continue;
+            }
+            for (const k of new Set([...Object.keys(b), ...Object.keys(a)])) {
+                if ((k === "primaryModel" || k === "cheapModel") && b[k] === undefined && typeof a[k] === "string")
+                    continue; // 落标记
+                if (k === "models" && Array.isArray(b.models) && Array.isArray(a.models)) {
+                    const added = a.models.filter((m) => !b.models.includes(m));
+                    const removed = b.models.filter((m) => !a.models.includes(m));
+                    if (removed.length)
+                        v.push(`rosters: "${a.name}".models 移除了 [${removed.join(", ")}](迁移只许追加)`);
+                    for (const m of added)
+                        if (m !== a.primaryModel && m !== a.cheapModel)
+                            v.push(`rosters: "${a.name}".models 追加了非主/cheap 标记项 "${m}"`);
+                    continue;
+                }
+                if (!sameJson(b[k], a[k]))
+                    v.push(`rosters: "${a.name}".${k} 意外变更(${JSON.stringify(b[k])} → ${JSON.stringify(a[k])})`);
+            }
+        }
+    }
+    // workers
+    {
+        const afterBy = new Map(after.workers.workers.map((w) => [w.name, w]));
+        for (const a of after.workers.workers)
+            if (!before.workers.workers.some((b) => b.name === a.name))
+                v.push(`workers: 出现新增 worker "${a.name}"(迁移不建 worker)`);
+        for (const b of before.workers.workers) {
+            const a = afterBy.get(b.name);
+            if (!a) {
+                v.push(`workers: "${b.name}" 被删除(迁移不许删)`);
+                continue;
+            }
+            for (const k of new Set([...Object.keys(b), ...Object.keys(a)])) {
+                if (k === "roster" && b.roster === undefined && typeof a.roster === "string") {
+                    if (!after.rosters.rosters.some((r) => r.name === a.roster))
+                        v.push(`workers: "${b.name}".roster 指认了不存在的 roster "${a.roster}"`);
+                    continue;
+                }
+                if (k === "secretEnv") {
+                    const bs = b.secretEnv ?? {};
+                    const as = a.secretEnv ?? {};
+                    for (const key of Object.keys(bs))
+                        if (as[key] !== bs[key])
+                            v.push(`workers: "${b.name}".secretEnv["${key}"] 被改/删(${JSON.stringify(bs[key])} → ${JSON.stringify(as[key])};迁移只许添键)`);
+                    for (const key of Object.keys(as)) {
+                        if (key in bs)
+                            continue;
+                        if (!expectedWiring.get(key)?.has(as[key]))
+                            v.push(`workers: "${b.name}".secretEnv["${key}"] = ${JSON.stringify(as[key])} 不在计划内接线映射(计划外漂移)`);
+                    }
+                    continue;
+                }
+                if (!sameJson(b[k], a[k]))
+                    v.push(`workers: "${b.name}".${k} 意外变更(${JSON.stringify(b[k])} → ${JSON.stringify(a[k])})`);
+            }
+        }
+    }
+    return v;
+}
+/** 迁移合成模板的默认安全闸(拍板:多模型烧钱必须有闸——老 TeamDef 没有 budget 概念,迁移必须给一个;
+ *  调用方/admin 可再调)。 */
+export const DEFAULT_COLLAB_BUDGET_TOKENS = 1_000_000;
+/**
+ * teams → collab 存量迁移(EXPERT-REDESIGN §8-5):每个 TeamDef → star 模板。
+ *  - members → "reviewer" 槽(cardinality "N")members[]:member.model(目录 name)→ modelRef;
+ *    member.systemPrompt(+role 前缀)→ 成员级 rolePrompt。
+ *  - `modelRole` 机制不入新形状(T1:只存目录引用或空)——带 modelRole 无 model 的成员迁为 modelRef 空
+ *    (=跟随用户当前模型),丢弃记录进 report。
+ *  - synthesizer → 独立 "synthesizer" 槽 + finalizer {type:"summarize", slot};无 synthesizer →
+ *    finalizer {type:"summarize"}(runTeamDiscussion 的缺省综合行为)。
+ *  - rounds 保留为 rounds.max;scenario → 迁移报告(工具展开需 scenario 定义,人工在槽位 tools 落地);
+ *    maxTranscriptTokens/无 budget → budget.maxTokens 兜底 {@link DEFAULT_COLLAB_BUDGET_TOKENS}。
+ * 幂等:纯函数,同输入同输出;name 冲突由调用方 parseDomain 的 id 去重校验兜底(team name 本就唯一)。
+ */
+export function migrateTeamsToCollab(rawTeams) {
+    const report = [];
+    const teams = (rawTeams !== null && typeof rawTeams === "object" && Array.isArray(rawTeams.teams))
+        ? (rawTeams.teams)
+        : [];
+    const templates = teams.map((t) => {
+        const members = (t.members ?? []).map((m) => {
+            if (!m.model && m.modelRole)
+                report.push(`team "${t.name}" member "${m.role}": modelRole "${m.modelRole}" 不入新形状(T1)→ modelRef 空=跟随用户当前模型`);
+            return {
+                ...(m.model ? { modelRef: m.model } : {}),
+                ...(m.systemPrompt ? { rolePrompt: `[${m.role}] ${m.systemPrompt}`.slice(0, 2000) } : { rolePrompt: `[${m.role}]` }),
+            };
+        });
+        const slots = [{ id: "reviewer", cardinality: "N", members }];
+        let finalizer = { type: "summarize" };
+        if (t.synthesizer) {
+            const s = t.synthesizer;
+            if (!s.model && s.modelRole)
+                report.push(`team "${t.name}" synthesizer: modelRole "${s.modelRole}" 不入新形状(T1)→ modelRef 空`);
+            slots.push({ id: "synthesizer", cardinality: 1, members: [{ ...(s.model ? { modelRef: s.model } : {}), ...(s.systemPrompt ? { rolePrompt: s.systemPrompt.slice(0, 2000) } : {}) }] });
+            finalizer = { type: "summarize", slot: "synthesizer" };
+        }
+        if (t.scenario)
+            report.push(`team "${t.name}": scenario "${t.scenario}" → 槽位 tools 需人工展开(工具集定义在 scenarios 域,迁移不解析)`);
+        report.push(`team "${t.name}" → collab star 模板 "${t.name}"(${members.length} member(s), rounds.max=${t.rounds ?? 2}, budget.maxTokens=${t.maxTranscriptTokens ?? DEFAULT_COLLAB_BUDGET_TOKENS})`);
+        return {
+            id: t.name,
+            name: t.name,
+            description: t.notes,
+            topology: "star",
+            slots,
+            rounds: { max: t.rounds ?? 2 },
+            finalizer,
+            sharedContext: { kind: "transcript", persistence: "session" },
+            budget: { maxTokens: t.maxTranscriptTokens ?? DEFAULT_COLLAB_BUDGET_TOKENS },
+            enabled: t.enabled ?? true,
+            ...(t.notes ? { notes: t.notes } : {}),
+        };
+    });
+    if (!teams.length)
+        report.push("no legacy teams — nothing to migrate.");
+    return { collab: { templates }, report };
+}

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @sema-agent/settings-schema/node — the Node-only entry. These helpers read/write `config.d/<domain>.json`
+ * over the real filesystem (`node:fs`/`node:path`), so they are split out of the main barrel: a browser or
+ * client bundle that only needs the pure contract (zod types, hash, roster resolution, ref-integrity) must
+ * not transitively pull `node:fs`. The TOC desktop/CLI + any server-side file source imports them here.
+ */
+export * from "./file-store.js";
+export * from "./file-edit.js";
+export * from "./bundle.js";
+export * from "./local-load.js";
+export * from "./scheduler-store-node.js";

package/dist/node.js

@@ -0,0 +1,11 @@
+/**
+ * @sema-agent/settings-schema/node — the Node-only entry. These helpers read/write `config.d/<domain>.json`
+ * over the real filesystem (`node:fs`/`node:path`), so they are split out of the main barrel: a browser or
+ * client bundle that only needs the pure contract (zod types, hash, roster resolution, ref-integrity) must
+ * not transitively pull `node:fs`. The TOC desktop/CLI + any server-side file source imports them here.
+ */
+export * from "./file-store.js";
+export * from "./file-edit.js";
+export * from "./bundle.js";
+export * from "./local-load.js";
+export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract

package/dist/reader.d.ts

@@ -0,0 +1,18 @@
+import type { DomainConfig, DomainName, EffectiveConfig } from "./types.js";
+/**
+ * The MINIMAL read surface a consumer needs to resolve config — a local file source (FileConfigStore), the
+ * TOC desktop, or a test fixture implements this WITHOUT stubbing the ~32 publish/RBAC/worker-status/lifecycle
+ * methods of sema-registry's full ConfigStore.
+ *
+ * sema-registry's fat `ConfigStore` should `extends ConfigReader` (every store impl already has all three
+ * methods, so the extension is satisfied automatically). The signatures here MUST match store.ts exactly
+ * (incl. the `<K extends DomainName>` generic and the `| undefined` on getDomain) or that `extends` fails.
+ */
+export interface ConfigReader {
+    /** The stored payload for a domain, validated; `undefined` if never set. */
+    getDomain<K extends DomainName>(domain: K): Promise<DomainConfig[K] | undefined>;
+    /** All domains merged (defaults for unset) + a monotonic version — what a consumer pulls. */
+    getEffective(): Promise<EffectiveConfig>;
+    /** The current monotonic version ALONE — a cheap read so a conditional poll can short-circuit. */
+    getVersion(): Promise<number>;
+}

package/dist/reader.js

@@ -0,0 +1 @@
+export {};