@sema-agent/settings-schema 10.1.1 → 11.1.0

package/dist/cross-domain.js

@@ -1,3 +1,62 @@
+import { formatConfigPath } from "./config-fns.js";
+/** What a dangling reference failed to find —— the closed set (S-1075, 11.0.0): one word per referenced domain. */
+export const REF_ISSUE_KINDS = ["unknown_model", "unknown_roster", "unknown_worker", "unknown_skill", "unknown_mcp", "unknown_plugin"];
+/** The domain a {@link RefIssueKind}'s target lives in. */
+export const REF_ISSUE_TARGET_DOMAIN = {
+    unknown_model: "models",
+    unknown_roster: "rosters",
+    unknown_worker: "workers",
+    unknown_skill: "skills",
+    unknown_mcp: "mcp",
+    unknown_plugin: "plugins",
+};
+/** The domains whose documents carry cross-domain references (by name) —— the referrer side of the judge. */
+export const REF_REFERRER_DOMAINS = ["rosters", "workers", "models", "collab", "systems", "entitlement"];
+/** The noun a kind's sentence uses for its target. */
+function refTargetNoun(kind) {
+    switch (kind) {
+        case "unknown_model":
+            return "model";
+        case "unknown_roster":
+            return "roster";
+        case "unknown_worker":
+            return "worker";
+        case "unknown_skill":
+            return "skill";
+        case "unknown_mcp":
+            return "mcp server";
+        case "unknown_plugin":
+            return "plugin";
+    }
+}
+/** How a referrer is named in the sentence (its name through `show`). */
+function refReferrerLabel(r, show) {
+    const named = (noun) => (r.name === undefined ? noun : `${noun} "${show(r.name)}"`);
+    switch (r.domain) {
+        case "rosters":
+            return named("roster");
+        case "workers":
+            return named("worker");
+        case "models":
+            return named("models");
+        case "collab":
+            return named("collab template");
+        case "systems":
+            return named("system");
+        case "entitlement":
+            return named("tier");
+    }
+}
+/** The ONE rendering of a {@link RefIssue}'s sentence: `<referrer> → unknown <noun> "<target>" (at <path>)`. `show` maps each
+ *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted. */
+export function renderRefIssue(issue, show = (v) => v) {
+    return `${refReferrerLabel(issue.referrer, show)} → unknown ${refTargetNoun(issue.kind)} "${show(issue.target)}" (at ${formatConfigPath(issue.path)})`;
+}
+/** The one minting point of a {@link RefIssue}. */
+function danglingRef(path, kind, referrer, target) {
+    const operands = { path, code: "custom", kind, referrer, target };
+    return { ...operands, message: renderRefIssue(operands) };
+}
 /** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
  *  Widened from the fat ConfigStore to the narrow {@link ConfigReader} (it only calls `getDomain`) so a TOC
  *  file source can use it without the full store.
@@ -12,131 +71,143 @@ export function createSiblingResolver(store, pending) {
         return store.getDomain(domain);
     };
 }
-/** The domains whose writes carry cross-domain model/roster references we validate at save time — the closed
- *  set as a RUNTIME VALUE (4.0.0). A consumer that has to ask "is this domain ref-checked?" at runtime (a
- *  config-rollback path deciding whether to run the guard before writing) could only hand-copy the list
- *  before, and a hand copy drifts silently: two rollback routes in the admin console each carried a
- *  five-member copy that had lost `entitlement`, so an entitlement rollback skipped the guard entirely with
- *  nothing red anywhere. Ask this constant (or {@link isRefCheckedDomain}) instead of writing a list.
+/** The domains a write must be judged for —— the closed set as a RUNTIME VALUE (4.0.0): every domain that HOLDS cross-domain
+ *  references ({@link REF_REFERRER_DOMAINS}) and every domain those references POINT INTO (the targets of
+ *  {@link REF_ISSUE_TARGET_DOMAIN}) —— 11.0.0 (S-1066 ③) added the three target-only domains `skills` / `mcp` / `plugins`: deleting
+ *  a skill a tier still names is a dangling reference made by the skills write, so that write is judged too. A consumer that has
+ *  to ask "is this domain ref-checked?" at runtime (a config-rollback path deciding whether to run the guard before writing)
+ *  asks this constant (or {@link isRefCheckedDomain}) instead of writing a list — a hand copy drifts silently (two rollback routes
+ *  in the admin console each once carried a five-member copy that had lost `entitlement`).
  *
- *  `satisfies readonly (keyof DomainConfig)[]` keeps every member a real domain key; {@link RefCheckedDomain}
- *  is DERIVED from this value, so there is exactly one place the set is written down. */
-export const REF_CHECKED_DOMAINS = ["rosters", "workers", "models", "collab", "systems", "entitlement"];
+ *  `satisfies` keeps every member a real domain key; a pin checks it equals referrers ∪ targets. {@link RefCheckedDomain} is
+ *  DERIVED from this value. */
+export const REF_CHECKED_DOMAINS = ["rosters", "workers", "models", "collab", "systems", "entitlement", "skills", "mcp", "plugins"];
 /** Runtime narrowing to {@link RefCheckedDomain}, same idiom as `isDomainName`: use it instead of hard-coding
  *  the set when filtering an arbitrary domain key (a batch payload's keys, a rollback target). */
 export function isRefCheckedDomain(d) {
     return typeof d === "string" && REF_CHECKED_DOMAINS.includes(d);
 }
-/** Cross-domain ref integrity for one {@link RefCheckedDomain} value. Every issue `path` starts with the
- *  DOMAIN KEY (e.g. `["rosters", i, "models", j]`, `["collab", "templates", i, …]`) so a caller can prefix a
- *  batch index and get a coordinate that is unambiguous across arms. Empty = ok. Runtime resolution stays
- *  tolerant (falls back); this is purely a save-time guard — a precise 400 at save time is friendlier than a
- *  silently-wrong roster.
- *
- *  4.0.0 made that first sentence TRUE: the `collab` arm used to start its paths at `"templates"` and the
- *  `entitlement` arm at `"tiers"`, so a caller could not read `path[0]` as the domain. See the CHANGELOG entry
- *  for the migration (BREAKING, value shape). */
-export async function refIntegrityIssues(domain, value, resolve) {
-    const issues = [];
+/** Every by-name reference `domain`'s document makes —— the ONE place the reference graph is written down (which field of which
+ *  domain names what). Exhaustive over {@link RefReferrerDomain}: a new referrer domain is a compile error until it is listed. */
+function referencesFrom(domain, docs, push) {
     if (domain === "rosters") {
-        const catalog = new Set(((await resolve("models"))?.models ?? []).map((m) => m.name));
-        value.rosters.forEach((r, i) => {
-            r.models.forEach((name, j) => {
-                if (!catalog.has(name))
-                    issues.push({ path: ["rosters", i, "models", j], message: `roster "${r.name}" references unknown model "${name}" (not in the models catalog)`, code: "custom" });
-            });
+        (docs.rosters?.rosters ?? []).forEach((r, i) => {
+            const referrer = { domain, name: r.name };
+            r.models.forEach((name, j) => push({ path: ["rosters", i, "models", j], kind: "unknown_model", referrer, target: name }));
             for (const [role, target] of Object.entries(r.roles ?? {})) {
-                if (target && "model" in target && !catalog.has(target.model))
-                    issues.push({ path: ["rosters", i, "roles", role], message: `roster "${r.name}" role.${role} → unknown model "${target.model}"`, code: "custom" });
+                if (target && "model" in target)
+                    push({ path: ["rosters", i, "roles", role], kind: "unknown_model", referrer, target: target.model });
             }
-            // 0.6.3 markers (primaryModel/cheapModel) reference the catalog like a {model}-form role does — same
-            // save-time guard (a dangling marker would silently derive nothing at resolution).
-            if (r.primaryModel && !catalog.has(r.primaryModel))
-                issues.push({ path: ["rosters", i, "primaryModel"], message: `roster "${r.name}" primaryModel → unknown model "${r.primaryModel}" (not in the models catalog)`, code: "custom" });
-            if (r.cheapModel && !catalog.has(r.cheapModel))
-                issues.push({ path: ["rosters", i, "cheapModel"], message: `roster "${r.name}" cheapModel → unknown model "${r.cheapModel}" (not in the models catalog)`, code: "custom" });
-            (r.atModelAllowlist ?? []).forEach((name, j) => {
-                if (!catalog.has(name))
-                    issues.push({ path: ["rosters", i, "atModelAllowlist", j], message: `roster "${r.name}" atModelAllowlist "${name}" not in the models catalog`, code: "custom" });
-            });
+            // 0.6.3 markers (primaryModel/cheapModel) reference the catalog like a {model}-form role does.
+            if (r.primaryModel)
+                push({ path: ["rosters", i, "primaryModel"], kind: "unknown_model", referrer, target: r.primaryModel });
+            if (r.cheapModel)
+                push({ path: ["rosters", i, "cheapModel"], kind: "unknown_model", referrer, target: r.cheapModel });
+            if (r.atMention?.mode === "only")
+                r.atMention.models.forEach((name, j) => push({ path: ["rosters", i, "atMention", "models", j], kind: "unknown_model", referrer, target: name }));
         });
     }
     else if (domain === "workers") {
-        const rosterNames = new Set(((await resolve("rosters"))?.rosters ?? []).map((r) => r.name));
-        value.workers.forEach((w, i) => {
-            if (w.roster && !rosterNames.has(w.roster))
-                issues.push({ path: ["workers", i, "roster"], message: `worker "${w.name}" references unknown roster "${w.roster}"`, code: "custom" });
+        (docs.workers?.workers ?? []).forEach((w, i) => {
+            if (w.roster)
+                push({ path: ["workers", i, "roster"], kind: "unknown_roster", referrer: { domain, name: w.name }, target: w.roster });
         });
     }
     else if (domain === "models") {
-        // The roles map + @-allowlist reference models in THIS payload's OWN catalog (they ship together in the
-        // models domain), so validate against `value`, not the stored/sibling models.
-        const m = value;
-        const catalog = new Set(m.models.map((x) => x.name));
-        for (const [role, target] of Object.entries(m.roles ?? {})) {
-            if (target && "model" in target && !catalog.has(target.model))
-                issues.push({ path: ["models", "roles", role], message: `models.roles.${role} → unknown model "${target.model}" (not in the catalog)`, code: "custom" });
+        // The roles map + `atMention.models` reference the catalog of the SAME document (they ship together in the models domain).
+        const m = docs.models;
+        for (const [role, target] of Object.entries(m?.roles ?? {})) {
+            if (target && "model" in target)
+                push({ path: ["models", "roles", role], kind: "unknown_model", referrer: { domain }, target: target.model });
         }
-        (m.atModelAllowlist ?? []).forEach((name, j) => {
-            if (!catalog.has(name))
-                issues.push({ path: ["models", "atModelAllowlist", j], message: `atModelAllowlist "${name}" not in the models catalog`, code: "custom" });
-        });
+        if (m?.atMention?.mode === "only")
+            m.atMention.models.forEach((name, j) => push({ path: ["models", "atMention", "models", j], kind: "unknown_model", referrer: { domain }, target: name }));
     }
     else if (domain === "collab") {
-        // collab (0.7.0, replaces teams): a slot member's `modelRef` is a models-CATALOG name (T1 — never a
-        // roster, never a gateway id) and must resolve against the catalog (sibling — batch-aware). ABSENT
-        // modelRef is the legal "跟随用户当前模型" state, not a dangle. This is the SAVE-time guard; a model
-        // deleted/renamed LATER still dangles → the web renders the 悬空 destructive badge (§11-6), same as
-        // groupBindings.
-        const catalog = new Set(((await resolve("models"))?.models ?? []).map((x) => x.name));
-        value.templates.forEach((t, i) => {
+        // collab (0.7.0): a slot member's `modelRef` is a models-CATALOG name. ABSENT modelRef is the legal "跟随用户当前模型" state.
+        (docs.collab?.templates ?? []).forEach((t, i) => {
             t.slots.forEach((s, j) => {
                 s.members.forEach((mem, k) => {
-                    if (mem.modelRef && !catalog.has(mem.modelRef))
-                        issues.push({ path: ["collab", "templates", i, "slots", j, "members", k, "modelRef"], message: `collab template "${t.id}" slot "${s.id}" → unknown model "${mem.modelRef}" (not in the catalog)`, code: "custom" });
+                    if (mem.modelRef)
+                        push({ path: ["collab", "templates", i, "slots", j, "members", k, "modelRef"], kind: "unknown_model", referrer: { domain, name: t.id }, target: mem.modelRef });
                 });
             });
         });
     }
     else if (domain === "systems") {
-        // systems.callsWorkers → workers domain (a dangling name would mint a credential routed at nobody;
-        // resolution stays tolerant — this is the save-time guard, same as the other ref-checked domains).
-        const workers = new Set((await resolve("workers"))?.workers.map((w) => w.name) ?? []);
-        value.systems.forEach((sys, i) => {
-            sys.callsWorkers.forEach((name, j) => {
-                if (!workers.has(name))
-                    issues.push({ path: ["systems", i, "callsWorkers", j], message: `system "${sys.name}" references unknown worker "${name}"`, code: "custom" });
-            });
+        // systems.callsWorkers → workers (a dangling name would mint a credential routed at nobody).
+        (docs.systems?.systems ?? []).forEach((sys, i) => {
+            sys.callsWorkers.forEach((name, j) => push({ path: ["systems", i, "callsWorkers", j], kind: "unknown_worker", referrer: { domain, name: sys.name }, target: name }));
         });
     }
     else if (domain === "entitlement") {
-        // A tier references FIVE sibling domains by name (roster→rosters, models[]→models catalog, visibleSkills→
-        // skills, visibleMcp→mcp, visiblePlugins→plugins). A dangling ref otherwise resolves silently (e.g. a typo'd roster → resolve-
-        // entitlement yields an empty set → the principal is silently denied) — a precise 400 at save time is
-        // friendlier, matching the rosters/workers guards.
-        const rosterNames = new Set(((await resolve("rosters"))?.rosters ?? []).map((r) => r.name));
-        const modelCatalog = new Set(((await resolve("models"))?.models ?? []).map((m) => m.name));
-        const skillNames = new Set((await resolve("skills"))?.skills.map((s) => s.name) ?? []);
-        const mcpNames = new Set((await resolve("mcp"))?.servers.map((s) => s.name) ?? []);
-        const pluginNames = new Set((await resolve("plugins"))?.plugins.map((p) => p.name) ?? []);
-        value.tiers.forEach((t, i) => {
-            if (t.roster && !rosterNames.has(t.roster))
-                issues.push({ path: ["entitlement", "tiers", i, "roster"], message: `tier "${t.id}" references unknown roster "${t.roster}"`, code: "custom" });
-            (t.models ?? []).forEach((name, j) => { if (!modelCatalog.has(name))
-                issues.push({ path: ["entitlement", "tiers", i, "models", j], message: `tier "${t.id}" model "${name}" not in the models catalog`, code: "custom" }); });
-            (t.visibleSkills ?? []).forEach((name, j) => { if (!skillNames.has(name))
-                issues.push({ path: ["entitlement", "tiers", i, "visibleSkills", j], message: `tier "${t.id}" visibleSkill "${name}" not in skills`, code: "custom" }); });
-            (t.visibleMcp ?? []).forEach((name, j) => { if (!mcpNames.has(name))
-                issues.push({ path: ["entitlement", "tiers", i, "visibleMcp", j], message: `tier "${t.id}" visibleMcp "${name}" not in mcp`, code: "custom" }); });
-            (t.visiblePlugins ?? []).forEach((name, j) => { if (!pluginNames.has(name))
-                issues.push({ path: ["entitlement", "tiers", i, "visiblePlugins", j], message: `tier "${t.id}" visiblePlugin "${name}" not in plugins`, code: "custom" }); });
+        // A tier references FIVE domains by name; a dangling one otherwise resolves silently (a typo'd roster → an empty set → the
+        // principal is silently denied).
+        (docs.entitlement?.tiers ?? []).forEach((t, i) => {
+            const referrer = { domain, name: t.id };
+            if (t.roster)
+                push({ path: ["entitlement", "tiers", i, "roster"], kind: "unknown_roster", referrer, target: t.roster });
+            (t.models ?? []).forEach((name, j) => push({ path: ["entitlement", "tiers", i, "models", j], kind: "unknown_model", referrer, target: name }));
+            (t.visibleSkills ?? []).forEach((name, j) => push({ path: ["entitlement", "tiers", i, "visibleSkills", j], kind: "unknown_skill", referrer, target: name }));
+            (t.visibleMcp ?? []).forEach((name, j) => push({ path: ["entitlement", "tiers", i, "visibleMcp", j], kind: "unknown_mcp", referrer, target: name }));
+            (t.visiblePlugins ?? []).forEach((name, j) => push({ path: ["entitlement", "tiers", i, "visiblePlugins", j], kind: "unknown_plugin", referrer, target: name }));
         });
     }
     else {
-        // Exhaustiveness guard: a new RefCheckedDomain MUST add its own branch above, not silently inherit another
-        // domain's validation. `never` makes that a compile error; the throw is the runtime backstop.
+        // Exhaustiveness guard: a new referrer domain MUST add its own branch above. `never` makes that a compile error.
         const unhandled = domain;
-        throw new Error(`refIntegrityIssues: unhandled domain "${String(unhandled)}"`);
+        throw new Error(`referencesFrom: unhandled domain "${String(unhandled)}"`);
+    }
+}
+/** The names a target domain defines. */
+function namesIn(kind, docs) {
+    switch (kind) {
+        case "unknown_model":
+            return new Set((docs.models?.models ?? []).map((m) => m.name));
+        case "unknown_roster":
+            return new Set((docs.rosters?.rosters ?? []).map((r) => r.name));
+        case "unknown_worker":
+            return new Set((docs.workers?.workers ?? []).map((w) => w.name));
+        case "unknown_skill":
+            return new Set((docs.skills?.skills ?? []).map((sk) => sk.name));
+        case "unknown_mcp":
+            return new Set((docs.mcp?.servers ?? []).map((sv) => sv.name));
+        case "unknown_plugin":
+            return new Set((docs.plugins?.plugins ?? []).map((pl) => pl.name));
+    }
+}
+/**
+ * **THE reference judge** (11.0.0, S-1066 ③; pure, synchronous): every by-name cross-domain reference in a document set that does
+ * not resolve, as a {@link RefIssue} (`path` = where the reference sits, `path[0]` = the referrer's domain). Both seats read this
+ * one conclusion: the write seat ({@link refIntegrityIssues}, refusing) and the read side (`resolveEffectiveForWorker`'s
+ * `refIssues`, reporting what it drops). Before 11.0.0 the write seat judged forward only and the read side judged on its own,
+ * silently.
+ */
+export function danglingRefs(docs) {
+    const issues = [];
+    const names = new Map();
+    const known = (kind) => names.get(kind) ?? names.set(kind, namesIn(kind, docs)).get(kind);
+    for (const domain of REF_REFERRER_DOMAINS) {
+        referencesFrom(domain, docs, (ref) => {
+            if (!known(ref.kind).has(ref.target))
+                issues.push(danglingRef(ref.path, ref.kind, ref.referrer, ref.target));
+        });
     }
     return issues;
 }
+/** Cross-domain ref integrity for a write of one {@link RefCheckedDomain} value (the write seat): the judge's conclusion on the
+ *  document set AFTER the write ({@link danglingRefs} over `value` + every other ref-checked domain through `resolve`), narrowed
+ *  to the references this write is answerable for —— the ones its own document holds (forward: a roster naming a model that is not
+ *  in the catalog) and the ones pointing into it (reverse, 11.0.0: deleting a model a roster still names; the issue names the
+ *  roster, `path` points at the reference). Empty = ok.
+ *
+ *  BATCH-AWARE through `resolve` (a sibling being written in the same batch shadows the stored one, see
+ *  {@link createSiblingResolver}). A reference that already dangled before this write and still involves this domain is reported
+ *  too — the same as the forward half always did (a roster write re-judges every roster). */
+export async function refIntegrityIssues(domain, value, resolve) {
+    const docs = { [domain]: value };
+    for (const other of REF_CHECKED_DOMAINS)
+        if (other !== domain)
+            docs[other] = await resolve(other);
+    return danglingRefs(docs).filter((i) => i.referrer.domain === domain || REF_ISSUE_TARGET_DOMAIN[i.kind] === domain);
+}

package/dist/cross-session.d.ts

@@ -49,7 +49,13 @@ export type CrossSessionInboundValue = (typeof CROSS_SESSION_INBOUND_VALUES)[num
 /** 设置 UI 的「不设」拼写(见头注)——两键共用同一个字面量。 */
 export declare const CROSS_SESSION_INBOUND_UNSET: "default";
 /** 文件层受理面:四个显式值 + `"default"`(未设)。 */
-export declare const CrossSessionInboundSetting: z.ZodEnum<["wake", "next-turn", "hold", "refuse", "default"]>;
+export declare const CrossSessionInboundSetting: z.ZodEnum<{
+    default: "default";
+    wake: "wake";
+    "next-turn": "next-turn";
+    hold: "hold";
+    refuse: "refuse";
+}>;
 export type CrossSessionInboundSettingValue = z.infer<typeof CrossSessionInboundSetting>;
 /** 四值闭集(CC 逐字)。`"never"` = 不设期限。 */
 export declare const DIALOG_EXPIRY_VALUES: readonly ["60s", "5m", "10m", "never"];
@@ -57,7 +63,13 @@ export type DialogExpiryValue = (typeof DIALOG_EXPIRY_VALUES)[number];
 /** 未设时生效的值(CC 缺省)。 */
 export declare const DIALOG_EXPIRY_DEFAULT: DialogExpiryValue;
 /** 文件层受理面:四个值 + `"default"`(未设 ⇒ 落 {@link DIALOG_EXPIRY_DEFAULT})。 */
-export declare const DialogExpirySetting: z.ZodEnum<["60s", "5m", "10m", "never", "default"]>;
+export declare const DialogExpirySetting: z.ZodEnum<{
+    never: "never";
+    default: "default";
+    "60s": "60s";
+    "5m": "5m";
+    "10m": "10m";
+}>;
 export type DialogExpirySettingValue = z.infer<typeof DialogExpirySetting>;
 /**
  * 整份 `settings.json` 里**本片段负责的两键**。刻意 `passthrough`:本片段不是整份 settings 的闭集门
@@ -65,15 +77,21 @@ export type DialogExpirySettingValue = z.infer<typeof DialogExpirySetting>;
  * 值必合法**。
  */
 export declare const CrossSessionSettings: z.ZodObject<{
-    crossSessionInbound: z.ZodOptional<z.ZodEnum<["wake", "next-turn", "hold", "refuse", "default"]>>;
-    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    crossSessionInbound: z.ZodOptional<z.ZodEnum<["wake", "next-turn", "hold", "refuse", "default"]>>;
-    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    crossSessionInbound: z.ZodOptional<z.ZodEnum<["wake", "next-turn", "hold", "refuse", "default"]>>;
-    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
-}, z.ZodTypeAny, "passthrough">>;
+    crossSessionInbound: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wake: "wake";
+        "next-turn": "next-turn";
+        hold: "hold";
+        refuse: "refuse";
+    }>>;
+    dialogExpiry: z.ZodOptional<z.ZodEnum<{
+        never: "never";
+        default: "default";
+        "60s": "60s";
+        "5m": "5m";
+        "10m": "10m";
+    }>>;
+}, z.core.$loose>;
 export type CrossSessionSettings = z.infer<typeof CrossSessionSettings>;
 /** 一层读数:`ok:false` = 词表外(调用方响亮拒);`ok:true` 无 `value` = 未设;有 `value` = 显式值。 */
 export type SettingLayerRead<T> = {

package/dist/default-model.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 「目录的缺省模型是哪一条」—— **一只**纯函数(11.0.0,S-1070)。server 的 apply 与 dry-run、壳的本地池读口都调它,不再各写一份链;
+ * `roles.default` 是 `{select}` 形时它不答名(交回 `select`,由引擎解),所以本包与引擎对同一份配置不会各答一个。
+ *
+ * 缺省模型只有一个位:`models.roles.default`(core 角色链的根;N-7 起 `models.default` 结构键退役 —— 那时两位各答一个、主任务跑前者、
+ * `default` 角色解到后者)。本模块纯、零 I/O、浏览器安全。
+ */
+import type { ModelsConfig, RoleTarget } from "./types.js";
+/** core 对 `default` 角色的档语义:从它的缺省档 `pro` 起**只向低档**扫 —— pro → flash → lite,绝不向上抓 max / ultra
+ *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;钉对 devDependency 里精确钉住的那一版 core)。 */
+export declare const DEFAULT_ROLE_TIER_LADDER: readonly ["pro", "flash", "lite"];
+/** 命名链每一级的来源词(闭集)。 */
+export type CatalogDefaultSource = "roles.default" | `tierGroup.${(typeof DEFAULT_ROLE_TIER_LADDER)[number]}` | "fallback";
+/**
+ * 解析的结果 —— 纯数据,判别联合(`kind` 闭集,两词):
+ *  · `named`  —— 命名链选中的目录名 `name`、哪一级选的 `source`、哪几级点了名却不可用 `dangling`(调用方据此告警,解析口自己不出声);
+ *  · `select` —— `roles.default` 是 `{select}` 形:它不点名模型,按目录条目的**属性**(档 / 能力 / 偏好)挑。挑哪一条是引擎的选择语义
+ *    (core `resolveTaskModel` 对 `default` 角色的解法),本包不复刻、不猜、也不跳到命名链的下一级 —— `select` 原样交回,调用方交给引擎解。
+ *    引擎要在与 `has` **同一可用集**(启用 ∧ 本机可服务)上解:交给它一份更宽的目录,它就可能挑中一条 `has` 说不可用的条目。
+ *    它是第一级,前面没有可悬空的级,所以不带 `dangling`。
+ */
+export type CatalogDefaultModel = {
+    readonly kind: "named";
+    readonly name: string;
+    readonly source: CatalogDefaultSource;
+    readonly dangling: readonly {
+        readonly source: Exclude<CatalogDefaultSource, "fallback">;
+        readonly name: string;
+    }[];
+} | {
+    readonly kind: "select";
+    readonly select: Extract<RoleTarget, {
+        select: unknown;
+    }>["select"];
+};
+/**
+ * 缺省模型由 `roles.default` 的形分两路(一条规则:点名的走命名链,不点名的交回引擎):
+ *  · `{select}` ⇒ `{ kind: "select", select }`(见 {@link CatalogDefaultModel});
+ *  · `{model}` 或缺席 ⇒ 命名链 —— 第一个**可用**的候选:`roles.default` 的 `{model}` → 活动档位组的 pro / flash / lite 绑定
+ *    ({@link DEFAULT_ROLE_TIER_LADDER})→ `fallback`(调用方的兜底,通常是第一条可用条目)。`has(name)` = 调用方的「这条目录名此刻可用」
+ *    (启用 ∧ 本机可服务);点了名但不可用的一级记进 `dangling`、落下一级,绝不静默指错模型。
+ */
+export declare function resolveCatalogDefaultModel(models: Pick<ModelsConfig, "roles" | "tierGroups" | "activeTierGroup">, has: (name: string) => boolean, fallback: string): CatalogDefaultModel;

package/dist/default-model.js

@@ -0,0 +1,34 @@
+import { resolveActiveTiers } from "./config-fns.js";
+/** core 对 `default` 角色的档语义:从它的缺省档 `pro` 起**只向低档**扫 —— pro → flash → lite,绝不向上抓 max / ultra
+ *  (core `ROLE_TIER_DEFAULTS.default` + `DEFAULT_TIER_ORDER`;钉对 devDependency 里精确钉住的那一版 core)。 */
+export const DEFAULT_ROLE_TIER_LADDER = ["pro", "flash", "lite"];
+/**
+ * 缺省模型由 `roles.default` 的形分两路(一条规则:点名的走命名链,不点名的交回引擎):
+ *  · `{select}` ⇒ `{ kind: "select", select }`(见 {@link CatalogDefaultModel});
+ *  · `{model}` 或缺席 ⇒ 命名链 —— 第一个**可用**的候选:`roles.default` 的 `{model}` → 活动档位组的 pro / flash / lite 绑定
+ *    ({@link DEFAULT_ROLE_TIER_LADDER})→ `fallback`(调用方的兜底,通常是第一条可用条目)。`has(name)` = 调用方的「这条目录名此刻可用」
+ *    (启用 ∧ 本机可服务);点了名但不可用的一级记进 `dangling`、落下一级,绝不静默指错模型。
+ */
+export function resolveCatalogDefaultModel(models, has, fallback) {
+    const target = models.roles?.default;
+    const named = target !== undefined && "model" in target ? target.model : undefined;
+    const select = target !== undefined && "select" in target ? target.select : undefined;
+    // 判序与引擎同一只真值判(core `partsModel`:`model` 为真 ⇒ 按名;否则 `select` 为真 ⇒ 按属性挑):schema 读过的值只有一形,这一判序只对
+    // 绕过 schema 递进来的两形并在(含 `model: ""`)起作用 —— 那时也与引擎同答。
+    if (!named && select)
+        return { kind: "select", select };
+    const tiers = resolveActiveTiers(models) ?? {};
+    const candidates = [
+        { source: "roles.default", name: named },
+        ...DEFAULT_ROLE_TIER_LADDER.map((t) => ({ source: `tierGroup.${t}`, name: tiers[t] })),
+    ];
+    const dangling = [];
+    for (const c of candidates) {
+        if (c.name === undefined || c.name === "")
+            continue;
+        if (has(c.name))
+            return { kind: "named", name: c.name, source: c.source, dangling };
+        dangling.push({ source: c.source, name: c.name });
+    }
+    return { kind: "named", name: fallback, source: "fallback", dangling };
+}

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

@@ -1,14 +1,14 @@
 /**
- * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集与指路句,
- * 供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
+ * 供 `types.ts`(写闸)与 `one-time-migrations.ts`(一次性迁移 SS-M4)同读。
  * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
  * 索引只从表派生,不另存任何词:表改了,这里跟着变。
  *
- * ## 迁移指路(7.0.1)
+ * ## 迁移指路(7.0.1;11.0.0 起指路句住 `retired-form.ts`)
  * 拒因要不要带迁移指路只有一条规则:**这个键「旧形 ⇒ 迁移能搬」就带,搬不了的保留名(`PORT` / `MODEL_*` …)不带**。
  * 「迁移能搬」= 迁移自己识别的键集(车道键 {@link isLaneEnvKey} ∪ 店键 {@link STORE_ENV_KEYS}),写闸读的是**同一只谓词**
  * ({@link isMigratableEnvKey}),不是第二张手抄的表 —— 迁移多认一个键而写闸没跟,或反过来,不会静默分叉
- * (`test/migration-signpost-7.0.1.test.ts` 用真跑迁移的读数逐个保留名对拍)。
+ * (`test/migration-signpost-11.0.0.test.ts` 用真跑迁移的读数逐个保留名对拍)。
  */
 import { type ExecutionLane, type ExecutionLaneRow } from "./execution-lanes.js";
 /** 一条车道的表行。词表与表行由 `execution-lanes.ts` 的 `satisfies Record<ExecutionLane, …>` 一一对应 ——
@@ -32,7 +32,3 @@ export declare const STORE_ENV_KEYS: readonly ["DB_BACKEND", "MEMORY_ENGINE", "M
 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

@@ -1,14 +1,14 @@
 /**
- * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集与指路句,
- * 供 `types.ts`(写闸)与 `migrate-workers.ts`(一次性迁移)同读。
+ * 包内私有:车道表({@link EXECUTION_LANES})的两只**派生索引** + 「迁移能搬哪些键」的**一份**键集,
+ * 供 `types.ts`(写闸)与 `one-time-migrations.ts`(一次性迁移 SS-M4)同读。
  * 不进主桶、不进 `package.json` 的 `exports`(与 `secret-scan.ts` 同一姿势)—— 消费方只拿表本身,索引是本包的实现细节。
  * 索引只从表派生,不另存任何词:表改了,这里跟着变。
  *
- * ## 迁移指路(7.0.1)
+ * ## 迁移指路(7.0.1;11.0.0 起指路句住 `retired-form.ts`)
  * 拒因要不要带迁移指路只有一条规则:**这个键「旧形 ⇒ 迁移能搬」就带,搬不了的保留名(`PORT` / `MODEL_*` …)不带**。
  * 「迁移能搬」= 迁移自己识别的键集(车道键 {@link isLaneEnvKey} ∪ 店键 {@link STORE_ENV_KEYS}),写闸读的是**同一只谓词**
  * ({@link isMigratableEnvKey}),不是第二张手抄的表 —— 迁移多认一个键而写闸没跟,或反过来,不会静默分叉
- * (`test/migration-signpost-7.0.1.test.ts` 用真跑迁移的读数逐个保留名对拍)。
+ * (`test/migration-signpost-11.0.0.test.ts` 用真跑迁移的读数逐个保留名对拍)。
  */
 import { EXECUTION_LANES } from "./execution-lanes.js";
 /** 一条车道的表行。词表与表行由 `execution-lanes.ts` 的 `satisfies Record<ExecutionLane, …>` 一一对应 ——
@@ -40,7 +40,3 @@ export function isLaneEnvKey(name) {
 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

@@ -4,9 +4,9 @@
  *
  * ## 为什么在这里
  * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
- * 部署面的车道清单、中心表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
- *  · 中心写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
- *  · 中心渲染器按这张表把结构块渲成 env(唯一写者);
+ * 部署面的车道清单、web-admin 表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
+ *  · web-admin 写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
+ *  · web-admin 渲染器按这张表把结构块渲成 env(唯一写者);
  *  · 引擎提货时从这张表派生自己的车道词表 / 必需键表 / 租户分离位(引擎只留运行期事实,按导入联合类型穷举);
  *  · 部署面车道清单由这张表生成。
  * 写闸与起服读同一张表 ⇒ 不会分叉。
@@ -15,7 +15,8 @@
  *  · 车道词与次序:`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)。
+ *    :269 ssh / :288 adb / :308 local-docker / :327 device)。`tenantSeparationBasis`(11.0.0):分租户的那几臂凭什么分 ——
+ *    e2b / k8s / local-docker 每任务一只隔离目标(`isolation`),device 是发起者自己的设备(`principal-binding`)。
  *  · `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` 三元链里**该车道那一臂**
@@ -31,25 +32,47 @@
  *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
  *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
  *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
+ *    它在退役词墓碑 {@link RETIRED_LANE_WORDS} 里:读到即拒,拒句带出路。
  */
 /** 可声明的执行车道闭集(= 引擎 `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];
+/**
+ * 已退役的车道**值** —— 墓碑(与退役 env 名的墓碑表 `RETIRED_ENVS` 同一条线:永久、只增不减、一跳 —— 去向恒是现行车道词)。
+ * 一行 = `[旧词, 去向车道, 怎么配出旧词当年要的那件事]`。读到旧词的每一处(worker 规格的 `runtime.execution.lane`、车道文件
+ * `config.d/remote-exec.json` 的 `provider`、引擎的 `REMOTE_EXEC`)拒,拒句取 {@link retiredLaneWordRefusal} —— 出路在源头给,一句。
+ */
+export type RetiredLaneWord = readonly [old: string, to: ExecutionLane, how: string];
+export declare const RETIRED_LANE_WORDS: readonly RetiredLaneWord[];
+/** 一个车道值是不是退役词:是 ⇒ 带出路的整句;否(现行词、不认识的词、非串)⇒ `undefined`。纯函数。 */
+export declare function retiredLaneWordRefusal(word: unknown): string | undefined;
 /** 车道分不分租户(引擎能力表的 `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];
+/** 分租户车道**凭什么**分租户(两档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
+ *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离。只有 `tenantSeparation: "supported"` 的车道有依据。 */
+export declare const TENANT_SEPARATION_BASES: readonly ["isolation", "principal-binding"];
+export type TenantSeparationBasis = (typeof TENANT_SEPARATION_BASES)[number];
+/** 车道的租户分离位与它的依据 —— 判别联合:分租户 ⇔ 依据在场(类型保证,不靠一句注释)。消费方的规则读依据列,不点名车道。 */
+export type LaneTenancy = {
+    readonly tenantSeparation: "supported";
+    readonly tenantSeparationBasis: TenantSeparationBasis;
+} | {
+    readonly tenantSeparation: "single-user-only";
+    readonly tenantSeparationBasis?: never;
+};
 /** 一条车道的表行。四栏 env 名两两不交、跨车道也不交(`test/execution-lanes-7.0.0.test.ts` 钉)。
  *  - `requiredEnv` / `optionalEnv`:非密坐标 —— 写在 `runtime.execution.coords`(字面值);
- *  - `requiredSecretEnv` / `optionalSecretEnv`:密钥 —— 写在 `runtime.execution.secretRefs`(服务变量名 → 宿主 env-NAME,绝不写值)。 */
-export interface ExecutionLaneRow {
+ *  - `requiredSecretEnv` / `optionalSecretEnv`:密钥 —— 写在 `runtime.execution.secretRefs`(服务变量名 → 宿主 env-NAME,绝不写值);
+ *  - 租户分离位 + 依据:见 {@link LaneTenancy}。 */
+export type ExecutionLaneRow = {
     readonly lane: ExecutionLane;
-    readonly tenantSeparation: TenantSeparation;
     readonly requiredEnv: readonly string[];
     readonly requiredSecretEnv: readonly string[];
     readonly optionalEnv: readonly string[];
     readonly optionalSecretEnv: readonly string[];
-}
+} & LaneTenancy;
 /** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
 export declare const EXECUTION_LANES: readonly ExecutionLaneRow[];
 /** 存储后端(→ `DB_BACKEND`)。= server `src/config-types.ts` `DB_BACKEND_WORDS`(:67)逐字同序。 */