@sema-ai/registry-core 0.10.3

package/dist/types.js

@@ -0,0 +1,1727 @@
+/**
+ * Config schema — the single source of truth for what the config center manages.
+ *
+ * Organized into DOMAINS (one top-level menu each). The UI, the store, and the service-facing API all
+ * speak these types. Use zod both to validate UI input AND to derive the TS types (one definition).
+ *
+ * Detail level is deliberate (the user asked for "详略设计"): `models` is the MVP — fully specified —
+ * while `scenarios` / `runtime` carry a real-but-skeletal schema to be fleshed out in later phases
+ * (see docs/ROADMAP.md; `integrations`/`access` were deleted in 0.6.0, EXPERT-REDESIGN §9). Adding a
+ * field is: extend the zod schema here → the form + the effective-config API pick it up.
+ *
+ * ⚠️ SECURITY BOUNDARY (see docs/SERVICE-INTEGRATION.md): the config center stores **non-secret**
+ * config only. A model's API key / a backend token is NEVER stored here as a value — we store the NAME
+ * of the env var that holds it (`apiKeyEnv`, `tokenEnv`), and the agent-service reads the real secret
+ * from its own environment. So a leak of this DB never leaks a credential. This is **enforced** by the
+ * `ENV_NAME` schema (regex) on every `*Env` field — a pasted secret value is rejected, not just discouraged.
+ */
+import { z } from "zod";
+import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody depth cap with the hash cap (R18)
+import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
+// COARSE, best-effort literal-secret SHAPE detector (NOT exhaustive — the real boundary is the env-NAME schema
+// on structured fields). Rejected in free-form value fields (worker `env`, model `extraBody`), URL components,
+// AND as an env-NAME value (an AWS key id is a valid env-NAME charset yet is a secret VALUE, not a NAME). Case-
+// INSENSITIVE (HTTP auth schemes are). sk-/GitHub/Slack/JWT/AWS AKIA/Google AIza/PEM/Basic. Round 2-5 (codex).
+// `-----BEGIN[A-Z0-9 ]*PRIVATE KEY` matches ONLY private-key PEMs (BEGIN [RSA/EC/OPENSSH/ENCRYPTED ]PRIVATE KEY)
+// — a PUBLIC KEY / CERTIFICATE is NOT a secret and must NOT be flagged (PRINCIPAL_JWT_PUBKEYS lives in env).
+// 0.1.32: this is the root fix for the public-key false-positive — replaces the 0.1.31 name-based exemption,
+// which Codex flagged as a bypass (a private key misnamed `*_PUBKEY` skipped scanning entirely).
+export const SECRET_LITERAL_RE = /^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\s|basic\s|eyJ[A-Za-z0-9_-]{10,}\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN[A-Z0-9 ]*PRIVATE KEY)/i;
+// 所有 *Env / *tokenEnv 字段的值是宿主机 env 变量的 NAME（不是值）。合法 env 变量名 + 拒绝 secret 形状的值（AKIA…
+// 这类是合法 env-NAME 字符集却是密钥）—— "只存 env-NAME、绝不存 secret 值" 由 SCHEMA 保证。Round-5 (codex)。
+export const ENV_NAME = z
+    .string()
+    .regex(/^[A-Z_][A-Z0-9_]*$/, "must be an ENV var NAME (A-Z, 0-9, _; not a value)")
+    // Most SECRET_LITERAL_RE shapes (sk-/bearer/eyJ./AIza/-----BEGIN) can't be env-NAMEs anyway (dash/space/dot/
+    // lowercase — the charset above rejects them). The ONE secret shape that IS a valid all-caps env-NAME charset
+    // is an AWS access-key id (AKIA…) — block exactly that, WITHOUT false-rejecting legit names like
+    // GITHUB_PAT_TOKEN / GHU_TOKEN (which the full SECRET_LITERAL_RE would). Round-5 (codex).
+    .refine((s) => !/^AKIA[0-9A-Z]{12,}$/.test(s), "looks like an AWS access-key id, not an env-NAME — put the NAME of the env var here (the value lives in .env)");
+function scanForSecret(s) {
+    if (SECRET_LITERAL_RE.test(s))
+        return true;
+    // HTTP auth scheme + an opaque token, at a token boundary. SECRET_LITERAL_RE's `bearer\s`/`basic\s` only fire
+    // at the STRING start; the tokenizer below splits the scheme from its token (the space is a delimiter), so a
+    // mid-string `Authorization: Bearer <opaque-OAuth-token>` (no sk-/eyJ prefix) slipped through. Bounded
+    // {8,4096} → ReDoS-safe. The space is the last delimiter-spanning shape (sk-/gh_/AKIA keep their `-`/`_` in
+    // the token; the JWT dot is handled above). R12 (codex). */
+    if (/(?:^|[^A-Za-z0-9_-])(?:bearer|basic)[ \t]+\S{8,4096}/i.test(s))
+        return true;
+    // a JWT (3 dot-joined base64url segments, header starts `eyJ`) searched anywhere — so a mid-string one
+    // survives the tokenizer's dot-split. ReDoS-SAFE: a token-boundary prefix `(?:^|[^A-Za-z0-9_-])` (one start
+    // per word, so `"eyJ".repeat(n)` is a single anchored start = linear, not the quadratic an unanchored scan
+    // gave) + BOUNDED {n,2048} quantifiers. Requiring TWO dots (3 segments) avoids the false positive a 1-dot
+    // `eyJ…json` (base64 + a file extension) caused. Round-8/9 (codex: fixed the ReDoS + the false positive).
+    if (/(?:^|[^A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,2048}\.[A-Za-z0-9_-]{8,2048}\.[A-Za-z0-9_-]{4,2048}/i.test(s))
+        return true;
+    // Tokenize on ANY non-[alnum_-] char (incl `.` `"` `,` `;` `[](){}|` …) so a secret embedded in JSON/quoted/
+    // dotted/comma punctuation (`{"apiKey":"sk-…"}`, `host.sk-…`, `a,sk-…`) is isolated as its OWN token, then
+    // anchored-test each (keeping `-` in the token set so `sk-…` stays whole; a benign `task-key` stays one token
+    // that doesn't start with a secret prefix → no false positive). Round-8 (codex). prior set missed `."',;[](){}`.
+    return s.split(/[^A-Za-z0-9_-]+/).some((tok) => tok !== "" && SECRET_LITERAL_RE.test(tok));
+}
+/** A NUL byte in a string the consumer feeds to spawn()/fs is a FAIL-OPEN config: it validates+persists here
+ *  but Node throws at RUNTIME — `ERR_INVALID_ARG_VALUE` for argv, "must be a string without null bytes" for an
+ *  fs path — so the worker dies at exec/boot, not at config edit. A NUL is never legitimate in a command / path
+ *  / host / image, so reject it on every exec-bound string field (mcp stdio + the whole remoteExec contract). R20 (codex). */
+export const hasNul = (s) => s.includes("\0");
+/** Does `s` contain a secret-shaped token? Scans the raw string AND a percent-decoded form (a secret can hide
+ *  as `%73%6B-…`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage. Tokenized
+ *  + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11 (codex). */
+export function containsSecretToken(s) {
+    // scan the raw string AND up to 3 percent-decoded layers (handles a multi-encoded `%2573%256B…` → `%73%6B…`
+    // → `sk-…`). TOLERANT decode: each valid %HH is decoded, a malformed escape (`%ZZ`, `%` at end) is left as-is
+    // so one bad escape elsewhere can't abort the whole decode (R13's all-or-nothing decodeURIComponent did). We
+    // do NOT fail-closed on a bare `%` — that would false-reject legit values like `100%` / `%s`. A secret glued
+    // to a malformed escape (`%ZZsk-`) is an accepted coarse-heuristic gap (no consumer reconstructs it; the real
+    // guarantee is the env-NAME boundary on structured fields). Bounded → deterministic. R11/R13/R14 (codex). */
+    let cur = s;
+    for (let i = 0; i < 4; i++) {
+        if (scanForSecret(cur))
+            return true;
+        const next = cur.replace(/%[0-9A-Fa-f]{2}/g, (m) => {
+            try {
+                return decodeURIComponent(m);
+            }
+            catch {
+                return m;
+            }
+        });
+        if (next === cur)
+            break;
+        cur = next;
+    }
+    return false;
+}
+/** Scan a URL's PATH + query + fragment (KEYS and values, decoded, tokenized) for a secret-shaped literal.
+ *  Userinfo is handled separately (NON_SECRET_URL bans it; dockerHost scans the ssh user). Round-4/5 (codex). */
+export function urlQueryFragmentHasSecret(u) {
+    let pathname = u.pathname;
+    try {
+        pathname = decodeURIComponent(u.pathname);
+    }
+    catch {
+        /* malformed %-escape → use raw */
+    }
+    if (containsSecretToken(pathname))
+        return true; // a secret can sit in a path segment (`/sk-live-…/route`)
+    for (const [k, v] of u.searchParams.entries())
+        if (containsSecretToken(k) || containsSecretToken(v))
+            return true;
+    const frag = u.hash.startsWith("#") ? u.hash.slice(1) : u.hash;
+    if (frag) {
+        let decoded = frag;
+        try {
+            decoded = decodeURIComponent(frag.replace(/\+/g, " "));
+        }
+        catch {
+            /* malformed %-escape → test the raw form */
+        }
+        if (containsSecretToken(decoded))
+            return true;
+        for (const [k, v] of new URLSearchParams(frag).entries())
+            if (containsSecretToken(k) || containsSecretToken(v))
+                return true;
+    }
+    return false;
+}
+// A URL that must NOT embed credentials in userinfo (`https://user:pass@host`) or smuggle a secret-shaped value
+// into the query/fragment — those would store a secret VALUE in the config + ship it on /effective (defeating
+// the env-NAME boundary). Must be an http(s) URL with a host (the scheme check rejects file://host/… /
+// javascript://host/… that DO carry a host). Round 2-5 hardening.
+export const NON_SECRET_URL = z
+    .string()
+    .url()
+    .refine((s) => {
+    try {
+        const u = new URL(s);
+        if (!(u.protocol === "http:" || u.protocol === "https:") || !u.host || u.username || u.password)
+            return false;
+        return !urlQueryFragmentHasSecret(u);
+    }
+    catch {
+        return true; // already passed .url(); unreachable in practice
+    }
+}, "must be an http(s) URL with a host and NO credentials in the userinfo/query/fragment — secrets go in the *Env (env-NAME) fields");
+/** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded
+ *  walk that rejects — WITHOUT ever invoking a getter (a malicious getter could throw a secret-bearing message,
+ *  or return different values across the validate vs persist JSON.stringify calls) — anything that isn't plain
+ *  JSON-safe + secret-free: a literal-secret KEY or string value, a non-finite number, undefined/function/
+ *  symbol/bigint, a non-plain container (Map/Set/Date/class / a `toJSON`-bearing object — proto ≠ Object.prototype),
+ *  a sparse array, an ACCESSOR property, a cycle, or a pathologically deep/large value. Because a passing value
+ *  is proven plain JSON (no toJSON/getters), the stored original == what JSON.stringify persists — closing the
+ *  non-idempotent-toJSON / accessor-leak / non-plain-container bypasses. Round 2-5 hardening (codex). */
+export function extraBodyUnsafe(v) {
+    const stack = [[v, 0]];
+    const seen = new WeakSet();
+    let budget = 100_000;
+    while (stack.length) {
+        if (budget-- <= 0)
+            return true; // too large to vet → fail-closed
+        const [cur, depth] = stack.pop();
+        if (depth > MAX_EXTRA_BODY_DEPTH)
+            return true; // too deep to hash later — cap = hash cap MINUS the wrapper reserve, since extraBody is always hashed NESTED (R18: a value passing at the raw hash cap would still overflow once wrapped → write fail-open + read hard-DoS)
+        if (cur === null)
+            continue;
+        const t = typeof cur;
+        if (t === "string") {
+            if (containsSecretToken(cur))
+                return true; // tokenized (mid-string secret too) — sibling of URL/dockerHost/mcp. R8
+            continue;
+        }
+        if (t === "number") {
+            if (!Number.isFinite(cur))
+                return true; // Infinity/NaN → JSON null on persist
+            continue;
+        }
+        if (t === "boolean")
+            continue;
+        if (t !== "object")
+            return true; // undefined / function / symbol / bigint
+        if (seen.has(cur))
+            return true; // cycle → reject (would also break stableStringify)
+        seen.add(cur);
+        if (Array.isArray(cur)) {
+            if (cur.length !== Object.keys(cur).length)
+                return true; // sparse array (holes → null on persist)
+            // descriptor walk for arrays too (NOT `for…of`/index access — that would INVOKE an accessor index's
+            // getter, which could throw a secret-bearing message). Reject accessor elements. R11 (codex).
+            for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
+                if (k === "length")
+                    continue; // the array's own `length` data prop — not an element
+                if (!("value" in desc))
+                    return true; // accessor element — do NOT invoke
+                stack.push([desc.value, depth + 1]);
+            }
+            continue;
+        }
+        const proto = Object.getPrototypeOf(cur);
+        if (proto !== Object.prototype && proto !== null)
+            return true; // Map/Set/Date/class/toJSON-bearing → not plain
+        // descriptor walk: never read a value via [] (would invoke a getter); reject accessors outright.
+        for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
+            if (!("value" in desc))
+                return true; // accessor (get/set) — do NOT invoke
+            if (containsSecretToken(k))
+                return true; // secret-shaped KEY (tokenized). R8
+            stack.push([desc.value, depth + 1]);
+        }
+    }
+    return false;
+}
+/** A k8s resource quantity ("250m", "1", "0.5", "512Mi", "1Gi", "128M") — catches garbage at config-submit
+ *  rather than surfacing as a reconcile ApplyError at the apiserver (consistent with ENV_NAME/DURATION guards). */
+export const K8S_QUANTITY = z.string().regex(/^\d+(\.\d+)?(m|[kKMGTPE]i?)?$/, 'must be a k8s quantity like "250m", "512Mi", "1Gi"');
+/** A TCP port: 1–65535. ONE shared schema so every port field (workers.coords.tidbPort, ssh.port, …) bounds
+ *  the SAME way — a port of 65536/0/-1 is config corruption, reject it at validation, not at connect time. R16. */
+export const TCP_PORT = z.number().int().positive().max(65535);
+/** Per-1M-token price ($/Mtok). Maps to the service's MODEL_COST_INPUT/OUTPUT/CACHE_READ/CACHE_WRITE
+ *  (budget.ts buildPricing → per-principal cost gate). Lives on the models catalog (ModelEntry.cost) — the
+ *  single pricing source (worker.model, the old second consumer, was deleted in 0.7.0). A free model declares
+ *  0s (core 1.26: missing cost ≠ cheapest). */
+// `.finite()` on every $/Mtok field: `z.number().nonnegative()` accepts Infinity (Infinity >= 0), which then
+// JSON.stringify's to `null` on write → a later read fails "expected number, received null" (fail-closed at the
+// WRONG time). `.int()` fields are already Infinity-safe (Infinity isn't an integer). Round-4 (codex).
+export const ModelCost = z.object({
+    input: z.number().finite().nonnegative(),
+    output: z.number().finite().nonnegative(),
+    cacheRead: z.number().finite().nonnegative().default(0),
+    cacheWrite: z.number().finite().nonnegative().default(0),
+});
+// ── Domain: models (MVP, fully specified) ─────────────────────────────────────
+// Maps 1:1 onto sema-server's config.models / config.roles / @-model allowlist (core 1.24 role
+// map). `name` is the catalog key AND the `@name` handle; `id` is the gateway's model id.
+export const ModelEntry = z.object({
+    /** Catalog key + `@name` mention handle (stable, url/word-safe), e.g. "qwen-72b". */
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    /** The gateway's model id, e.g. "Qwen3.5-72B" (what actually goes on the wire). */
+    id: z.string().min(1),
+    /** Routes the brain in the service (createRoutingBrain by provider): "gateway"/"vllm" → OpenAI brain,
+     *  "anthropic" → Anthropic brain. */
+    provider: z.string().min(1).default("gateway"),
+    /** API family — must match the serving brain or cache accounting mis-counts (service design/18).
+     *  "openai-completions" for vLLM/OpenAI gateways, "anthropic-messages" for the Anthropic route. */
+    api: z.enum(["openai-completions", "anthropic-messages"]).default("openai-completions"),
+    /** Gateway base URL (non-secret). Empty → the service's default gateway for that provider. */
+    baseUrl: NON_SECRET_URL.optional().or(z.literal("")),
+    /** NAME of the env var (in the SERVICE's env) holding this model's API key — never the key itself. */
+    apiKeyEnv: ENV_NAME.optional(),
+    /** Price/capability tier — fuels core 1.25 `selectModel({ tier })` role resolution. */
+    tier: z.enum(["cheap", "standard", "premium"]).default("standard"),
+    reasoning: z.boolean().default(false),
+    vision: z.boolean().default(false),
+    contextWindow: z.number().int().positive().optional(),
+    maxTokens: z.number().int().positive().optional(),
+    /** $/Mtok. A genuinely-free model still declares 0s (core 1.26: missing cost ≠ cheapest). */
+    cost: ModelCost.optional(),
+    /** Extra OpenAI/Anthropic request-body params merged into every call to this model (core passes them
+     *  through), e.g. {frequency_penalty:0.5, presence_penalty:0.3}. Non-secret model metadata — same class
+     *  as cost/tier. Shipped on /effective.models.models[].extraBody; the service merges it into the request. */
+    // z.unknown() (NOT z.record — that iterates + reads top-level getters during parse, firing a malicious getter
+    // before our check). The getter-free descriptor walk (extraBodyUnsafe) validates the RAW value without
+    // invoking any getter; a Proxy that fakes its descriptors is caught by re-scanning the JSON clone; and the
+    // .transform persists that CLONE (concrete plain JSON) so a non-idempotent toJSON can't differ at persist.
+    // Round 2-5 hardening (codex).
+    extraBody: z
+        .unknown()
+        .optional()
+        // ONE transform that validates AND canonicalizes with a SINGLE JSON.stringify — the scanned clone IS the
+        // persisted value, so a non-idempotent getter/Proxy can't validate one serialization and persist another
+        // (the prior superRefine+transform stringified TWICE — codex R10). getter-free descriptor walk bounds size
+        // BEFORE the stringify; the clone is re-scanned so a Proxy that fakes its descriptors still can't ship a secret.
+        .transform((v, ctx) => {
+        if (v === undefined)
+            return undefined;
+        const proto = typeof v === "object" && v !== null ? Object.getPrototypeOf(v) : undefined;
+        if (typeof v !== "object" || v === null || Array.isArray(v) || (proto !== Object.prototype && proto !== null)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody must be a plain JSON object" });
+            return z.NEVER;
+        }
+        // wrap in try/catch: a hostile Proxy's getOwnPropertyDescriptor/ownKeys trap could THROW a secret-bearing
+        // message — never surface it; treat any reflective failure as invalid with a FIXED message. R11 (codex).
+        let rawUnsafe;
+        try {
+            rawUnsafe = extraBodyUnsafe(v);
+        }
+        catch {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody could not be validated (reflective access threw)" });
+            return z.NEVER;
+        }
+        if (rawUnsafe) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody: a key/value is a secret shape, non-JSON (Infinity/function/Map), an accessor, cyclic, or too deep" });
+            return z.NEVER;
+        }
+        let clone;
+        try {
+            clone = JSON.parse(JSON.stringify(v)); // the ONLY serialization — its result is what we scan AND persist
+        }
+        catch {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody is not JSON-serializable" });
+            return z.NEVER;
+        }
+        if (extraBodyUnsafe(clone)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody: its serialized form carries a secret" });
+            return z.NEVER;
+        }
+        return clone;
+    }),
+    /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
+     *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
+    quotaWeight: z.number().finite().nonnegative().default(1),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+}).superRefine((m, ctx) => {
+    // provider↔api pairing (service createRoutingBrain / design/18): the Anthropic brain needs `anthropic-messages`
+    // and that api needs the Anthropic provider — a mismatch mis-counts cache/cost at runtime. The console FORM
+    // suggested this; enforce it in the SCHEMA so a direct PUT / local TOC config can't ship a mis-paired model.
+    // (provider:"anthropic" must set api explicitly; gateway/vllm keep the openai-completions default.) Round-4 (codex).
+    if ((m.provider === "anthropic") !== (m.api === "anthropic-messages"))
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `provider "${m.provider}" + api "${m.api}" mismatch — provider:"anthropic" ⟺ api:"anthropic-messages"`, path: ["api"] });
+});
+// `verifier` (2026-06-11, SERVICE-RESPONSE-…-PHASE2): real consumer = core's verification gate
+// (runWithVerification/resumeWithVerification resolve the verifier sub-task model via this role). Fallback
+// semantics per core: a roster that doesn't set `verifier` uses `default`. core also has `advisor` (teacher
+// mode) — deliberately NOT added: Service AI evaluated teacher mode and won't consume it (no consumer, no key).
+export const ModelRole = z.enum(["default", "summarize", "subagent", "team", "synthesize", "verifier"]);
+/** A role resolves either to a model NAME, or by capability/price (core 1.25 `{ select }`). */
+export const RoleTarget = z.union([
+    z.object({ model: z.string().min(1) }),
+    z.object({ select: z.object({ tier: z.enum(["cheap", "standard", "premium"]).optional(), needs: z.array(z.enum(["vision", "reasoning"])).optional(), prefer: z.enum(["cheapest", "premium"]).optional() }) }),
+]);
+// ── sema 档位(tiers)与档位组(tier groups)──([599]③ center 半场, core 1.265 档位车) ──────
+// core 侧接缝 = `RunnerDeps.tiers`(档位词→模型绑定的**单表**, catalog 单点增广 expandTiers);center 侧
+// 把「多套命名预配置」存成 tierGroups,下发时只解析 ACTIVE 那一套成单表(组切换=center 换表下发,零新
+// 引擎机制)。与 `ModelEntry.tier`(cheap/standard/premium 价格分级, core 1.25 selectModel)是两回事——
+// 那是能力/价格元数据,这是用户面的模型预配置绑定;词表也不同(max/pro/flash/lite + ultra 预留)。
+/** 档位词→catalog 模型 `name` 的绑定。值=目录键(string 引用,不 enum——开放性照 execution
+ *  allowedLanes 先例);`ultra` 预留在 max 之上,绑定即生效零码改([598]②)。未绑档引擎侧沿链降档
+ *  fail-open;整表未配=引擎恒惰性(INERT)。 */
+export const TierBindings = z.object({
+    ultra: z.string().min(1).optional(),
+    max: z.string().min(1).optional(),
+    pro: z.string().min(1).optional(),
+    flash: z.string().min(1).optional(),
+    lite: z.string().min(1).optional(),
+});
+/** 「档位组」= 一套命名的档位绑定表预配置,如「日常组=v4-pro/v4-flash」vs「攻坚组=fable-5/v4-pro」。 */
+export const TierGroup = z.object({
+    /** Group key (same charset as catalog names), e.g. "daily" / "heavy". */
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    tiers: TierBindings.default({}),
+    notes: z.string().optional(),
+});
+export const ModelsConfig = z
+    .object({
+    models: z.array(ModelEntry).default([]),
+    /** role → target. Unset roles fall back to `default` (core fallback chain). */
+    roles: z.record(ModelRole, RoleTarget).default({}),
+    /** Which model names an end user may `@`-mention. Empty/undefined → all enabled models. */
+    atModelAllowlist: z.array(z.string()).optional(),
+    /** 命名档位组预配置([599]③)。只有 ACTIVE 组的绑定表会下发为引擎的 tiers 单表。 */
+    tierGroups: z.array(TierGroup).default([]),
+    /** 当前生效的档位组 name。未设(或无组)→ 不下发 tiers,引擎档位层恒惰性。 */
+    activeTierGroup: z.string().optional(),
+})
+    // `name` is the catalog key AND the @-handle AND the cross-domain ref target (rosters/collab/roles/allowlist
+    // all reference it by name). EVERY other name-keyed domain dedups (rosters/scenarios/systems/...); models —
+    // the most-referenced — was the lone gap. A duplicate name ships two conflicting defs (id/apiKeyEnv/cost/
+    // enabled) on the wire and makes every ref ambiguous (the `new Set(names)` existence checks collapse them).
+    // Round-3 fix (codex, reproduced).
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.models.forEach((m, i) => {
+        if (seen.has(m.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate model "${m.name}" — the catalog key (and @-handle) must be unique`, path: ["models", i, "name"] });
+        seen.add(m.name);
+    });
+    // Catalog self-references must resolve to a real model — a dangling global `roles.{role}.model` or an
+    // `atModelAllowlist` name not in `models` ships a broken wire (the global /effective path uses eff.models
+    // directly, with no roster filter). This lived ONLY in refIntegrityIssues (sema-registry) — but the schema
+    // is the only guard for a local TOC config / a direct PUT. Round-4 (codex, reproduced).
+    const names = new Set(cfg.models.map((m) => m.name));
+    for (const [role, t] of Object.entries(cfg.roles ?? {})) {
+        if (t && "model" in t && !names.has(t.model))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `role "${role}" → model "${t.model}" is not in the catalog`, path: ["roles", role, "model"] });
+    }
+    (cfg.atModelAllowlist ?? []).forEach((n, i) => {
+        if (!names.has(n))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `atModelAllowlist["${n}"] is not in the catalog`, path: ["atModelAllowlist", i] });
+    });
+    // 档位组 ref 完整性(照上面 roles/allowlist 悬空检测同款):组名去重 + 绑定必须命中 catalog +
+    // activeTierGroup 必须命中某组(悬空 active = 下发面从「换表」静默滑成「无表」,写入时 fail-loud)。
+    const groupSeen = new Set();
+    cfg.tierGroups.forEach((g, i) => {
+        if (groupSeen.has(g.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate tier group "${g.name}"`, path: ["tierGroups", i, "name"] });
+        groupSeen.add(g.name);
+        for (const [tier, model] of Object.entries(g.tiers)) {
+            if (typeof model === "string" && !names.has(model))
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `tier group "${g.name}" ${tier} → model "${model}" is not in the catalog`, path: ["tierGroups", i, "tiers", tier] });
+        }
+    });
+    if (cfg.activeTierGroup !== undefined && !groupSeen.has(cfg.activeTierGroup)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `activeTierGroup "${cfg.activeTierGroup}" is not a tier group name`, path: ["activeTierGroup"] });
+    }
+});
+// ── Domain: rosters (per-worker model roster — docs/MULTI-ROSTER.md) ───────────
+// A named VIEW over the global `models` catalog: which models a worker exposes + its role map + @-allowlist.
+// A worker references one by name (WorkerSpec.roster); GET /effective?worker=<name> resolves it. Models stay
+// single-sourced in the `models` domain — a roster only references them by name (cross-domain ref checked at
+// resolution/PUT, see docs/MULTI-ROSTER.md §6). This is what lets one sema-registry serve heterogeneous
+// instances (OA=Qwen vs review=DeepSeek) instead of a single global roster.
+export const RosterEntry = z.object({
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    /** Catalog model names this roster exposes (must exist in models.models[].name). Empty = the full catalog. */
+    models: z.array(z.string().min(1)).default([]),
+    /**
+     * 主模型角色标记(0.6.3, E3/[546]/[548]②)——catalog model NAME。worker.model 废除后 service 从 roster
+     * 解析 boot 主模型的归宿位:解析语义(resolve-roster)= primary 喂 `default`/`team`/`synthesize` 三角色、
+     * cheap 喂 `subagent`/`summarize`(service 现有 ModelRoles 口径;`verifier` 不派生——unset→default 兜底链)。
+     * 显式 `roles` **逐角色**优先于标记派生;标记优先于全局 models.roles。additive:不设=行为与 0.6.2 全等。
+     */
+    primaryModel: z.string().min(1).optional(),
+    /** cheap 模型角色标记(同上;worker.model.cheapId 的迁移归宿,§3②)。 */
+    cheapModel: z.string().min(1).optional(),
+    /** Role map override; unset roles fall back to marker-derived roles, then the global models.roles. */
+    roles: z.record(ModelRole, RoleTarget).optional(),
+    /** @-mention allowlist override; unset → inherits the global models.atModelAllowlist. */
+    atModelAllowlist: z.array(z.string()).optional(),
+    notes: z.string().optional(),
+});
+export const RostersConfig = z
+    .object({ rosters: z.array(RosterEntry).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.rosters.forEach((r, i) => {
+        if (seen.has(r.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate roster "${r.name}"`, path: ["rosters", i, "name"] });
+        seen.add(r.name);
+        // intra-roster consistency: a role target / an @-allowlist entry pinned to a model NAME must be one
+        // this roster exposes (when it's a subset). Cross-domain (the name exists in the catalog) is checked at
+        // PUT time — see MULTI-ROSTER.md. (Both layers matter: this catches subset-internal inconsistency even
+        // when models is the full catalog is left to the PUT check.)
+        if (r.models.length) {
+            const allowed = new Set(r.models);
+            // 0.6.3 markers: same subset-consistency line as roles/@-allowlist — a marker naming a model this
+            // roster doesn't expose would derive a dangling role (dropped at resolution, but reject loudly at PUT).
+            if (r.primaryModel && !allowed.has(r.primaryModel)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `roster "${r.name}" primaryModel → "${r.primaryModel}" not in roster.models`, path: ["rosters", i, "primaryModel"] });
+            }
+            if (r.cheapModel && !allowed.has(r.cheapModel)) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `roster "${r.name}" cheapModel → "${r.cheapModel}" not in roster.models`, path: ["rosters", i, "cheapModel"] });
+            }
+            for (const [role, target] of Object.entries(r.roles ?? {})) {
+                if (target && "model" in target && !allowed.has(target.model)) {
+                    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `roster "${r.name}" role.${role} → "${target.model}" not in roster.models`, path: ["rosters", i, "roles", role] });
+                }
+            }
+            (r.atModelAllowlist ?? []).forEach((name, j) => {
+                if (!allowed.has(name))
+                    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `roster "${r.name}" atModelAllowlist "${name}" not in roster.models`, path: ["rosters", i, "atModelAllowlist", j] });
+            });
+        }
+    });
+});
+// ── Domain: scenarios (场景组合配置化 — ASK-CENTER-2026-06-11-SCENARIOS, v1) ───────────────────────────
+// "组合即配置、能力钉死在部署": the center COMPOSES scenarios from the toolsets the deployment registers —
+// it can never mint a new capability (a new toolset = a service code change, deliberately expensive). The
+// service overlays these onto its built-in scenario table at boot; SAME NAME OVERRIDES the built-in (clay 拍
+// ①, the worker logs `sema_registry_scenarios.shadowsBuiltin` as the audit hook). Invalid entries are
+// skipped+warned worker-side, never fail boot. restart-to-apply like skills/mcp (clay 拍 ③).
+// The old skeletal roles/tools fields are gone (never stored anywhere, zero consumers, no migration).
+export const ScenarioEntry = z.object({
+    /** Scenario name — may equal a built-in name (then the center definition SHADOWS it). */
+    name: z.string().regex(/^[a-z][a-z0-9-]{1,31}$/, "lowercase slug, 2-32 chars (a-z, 0-9, -)"),
+    /** Toolset key from the SERVICE's registry (v1: "none" | "repo-readonly"). Deliberately a shaped string,
+     *  not an enum: the worker registry is the authority (unknown → skip+warn there), so the center never needs
+     *  a release just to NAME a toolset a newer service ships. */
+    toolset: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/, "toolset key (lowercase slug)"),
+    /** System-prompt-level content (clay 拍 ②: ≤4KB; the full text lands in the change/publish audit via the
+     *  domain snapshot). Optional — absent = a neutral scenario (no system framing). Wrapped by the service's
+     *  stablePrompt (prefix-cache discipline is code-side; the config plane can't bypass it). */
+    prompt: z.string().max(4096).optional(),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+});
+export const ScenarioConfig = z
+    .object({ scenarios: z.array(ScenarioEntry).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.scenarios.forEach((sc, i) => {
+        if (seen.has(sc.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate scenario "${sc.name}"`, path: ["scenarios", i, "name"] });
+        seen.add(sc.name);
+    });
+});
+// ── Domain: systems (系统接入/凭证生命周期 — SERVICE-PROPOSAL-SYSTEMS-DOMAIN, S1) ─────────────────────────
+// Declarative SYSTEM onboarding: which external systems (OA / CC-MCP facade / portal …) may call which
+// workers, with the credential LIFECYCLE (mint/deliver/rotate/revoke) owned by the orchestrator (S2/S3).
+// `name` doubles as the worker-derived run.source (the worker attributes a run to whichever credential
+// authenticated — never self-reported). This domain holds METADATA + nonces ONLY — credential VALUES live
+// exclusively in the secret store (I1: audit/UI/API see fingerprints, never values).
+/** Platform credential surfaces a system may NEVER deliver into (红线1 — would let a publish overwrite the
+ *  platform's own secrets). Runtime delivery (S3) re-checks; this is the save-time half. */
+export const DELIVER_DENYLIST = new Set([
+    "a2-platform-secrets",
+    "tidb-creds",
+    "gitea-notify",
+    "worker-secrets",
+    // the orchestrator's OWN minted-token store (S2) — a system must never deliver into its credential source.
+    "systems-credentials",
+]);
+export const SystemEntry = z.object({
+    /** System id = run.source value. Same shape the worker enforces for attribution. */
+    name: z.string().regex(/^[a-z][a-z0-9-]{1,31}$/, "lowercase slug, 2-32 chars (a-z, 0-9, -)"),
+    /** Workers this system may call — its token lands in each one's SERVICE_AUTH_TOKENS CSV (S2).
+     *  Cross-domain ref-checked against the workers domain. */
+    callsWorkers: z.array(z.string().min(1)).default([]),
+    /** Where the orchestrator delivers this system's credential (the CALLER's secret). v1: a BARE secret name
+     *  in the orchestrator's OWN namespace (no "ns/name" — cross-namespace = an RBAC expansion, deferred until
+     *  a real need). Optional: a system without deliverTo gets a minted token visible only via out-of-band ops. */
+    deliverTo: z
+        .object({
+        k8sSecret: z
+            .string()
+            .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'bare secret NAME in the orchestrator namespace (no "ns/" prefix — v1 is same-namespace only)')
+            .max(253)
+            // The `<worker>-env` suffix is the orchestrator's worker-credential projection pattern. A target
+            // worker that isn't provisioned yet has no Secret to label-check, so a name-level reservation is
+            // the only thing closing the "squat on a future worker's credential surface" timing hole (S3 设计
+            // §4.4, council DESIGN-6/13). Cost: callers can't use a secret that happens to end in -env.
+            .refine((n) => !n.endsWith("-env"), { message: 'secret names ending in "-env" are reserved for orchestrator worker-credential projections (红线1)' }),
+        key: z.string().regex(/^[-._a-zA-Z0-9]+$/, "k8s secret data key").max(253),
+    })
+        .optional(),
+    /** Bump to ROTATE this system's credential (S3 choreography: mint new → dual-token CSV → deliver → grace →
+     *  retire old). Same idiom as WorkerSpec.recreateNonce. */
+    rotateNonce: z.string().max(64).optional(),
+    /** Overlap window (seconds) during rotation before the OLD token is retired. Absent → orchestrator default
+     *  (service AI to confirm; S3). */
+    rotateGraceSec: z.number().int().positive().optional(),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+});
+export const SystemsConfig = z
+    .object({ systems: z.array(SystemEntry).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    const targets = new Map(); // "secret\0key" -> index of first ENABLED claimant
+    cfg.systems.forEach((sys, i) => {
+        if (seen.has(sys.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate system "${sys.name}"`, path: ["systems", i, "name"] });
+        seen.add(sys.name);
+        if (sys.deliverTo && DELIVER_DENYLIST.has(sys.deliverTo.k8sSecret)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `deliverTo.k8sSecret "${sys.deliverTo.k8sSecret}" is a PLATFORM credential surface — refused (红线1)`, path: ["systems", i, "deliverTo", "k8sSecret"] });
+        }
+        // Cross-system deliverTo collision (S3 设计 §4.5, council DESIGN-4): two enabled systems writing the
+        // same {secret,key} would silently overwrite each other (same SSA fieldManager). Save-time half; the
+        // orchestrator re-checks at delivery time.
+        if (sys.deliverTo && sys.enabled) {
+            const t = `${sys.deliverTo.k8sSecret}\0${sys.deliverTo.key}`;
+            const prior = targets.get(t);
+            if (prior !== undefined) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `deliverTo target "${sys.deliverTo.k8sSecret}/${sys.deliverTo.key}" already claimed by system "${cfg.systems[prior].name}" — one credential per delivery slot`, path: ["systems", i, "deliverTo"] });
+            }
+            else {
+                targets.set(t, i);
+            }
+        }
+    });
+});
+/** One system's credential-lifecycle OBSERVATION (S3 设计 §7) — written by the orchestrator each cycle via
+ *  `PUT /api/config/systems/status` (batch), read by the S4 UI. Carries FINGERPRINTS only, never values (I1). */
+export const SystemStatusEntry = z.object({
+    name: z.string().min(1),
+    /** lkg-hold = the systems domain went empty/absent and the orchestrator is holding the last-known-good
+     *  injection (S3 设计 §5); refused = a deliverTo runtime red-line check failed (see `reason`). */
+    phase: z.enum(["bootstrap", "steady", "rotating", "grace", "refused", "lkg-hold"]),
+    /** sha256/8 of the CURRENT token. */
+    fp: z.string().regex(/^[0-9a-f]{8}$/),
+    /** sha256/8 of the retiring token while a rotation grace window is open. */
+    prevFp: z.string().regex(/^[0-9a-f]{8}$/).optional(),
+    mintedAt: z.string().optional(),
+    /** When the retiring token will be dropped (set at delivery; absent while awaiting convergence). */
+    retireAt: z.string().optional(),
+    /** sha256/8 of the token last successfully written to deliverTo. */
+    deliveredFp: z.string().regex(/^[0-9a-f]{8}$/).optional(),
+    /** Which check refused delivery / why the orchestrator is holding (operator-facing, never a value). */
+    reason: z.string().max(500).optional(),
+    updatedAt: z.string(),
+});
+// ── Domain: runtime (限额残余 — API/CLI-only, EXPERT-REDESIGN §5) ─────────────────
+// 0.6.0 (runtime 域废除拆三刀): the governance trio (autonomy/commandPolicy/approvalRequire) moved OUT into
+// the new `governance` domain; the legacy-skeletal `approvalDeny`/`runStaleSec` (service never read them) are
+// DELETED outright. What remains = the fleet cost/rate LIMIT residue — kept API/CLI-only (the web renders NO
+// runtime surface; the "runtime" UI concept is abolished).
+// WIRE TRANSITION (双写, §5): the service still consumes the negotiated 6-gate contract off the runtime slot of
+// /effective — so `buildEffective` MIRRORS the governance keys into the runtime slot ({@link RuntimeWire})
+// until the service confirms the switch to the governance slot (blackboard ask⑤). governance is the TRUTH;
+// the runtime mirror is derived output only (never stored, never editable).
+export const RuntimeConfig = z.object({
+    // `.optional()` on every gate (settled discipline): ABSENT = "the center isn't managing this — keep your
+    // env value"; present — INCLUDING an explicit 0 — overrides (publishable "gate OFF"). A default here would
+    // silently override a deployment's env.
+    rateLimitPerMin: z.number().int().nonnegative().optional(),
+    // Fleet-level cost governance (SERVICE-RESPONSE-2026-06-11-PHASE2). All restart-to-apply, none secret.
+    // Per-worker WorkerSpec.runtime.maxPrincipalCostUsd (injected env) outranks this fleet default — precedence
+    // is the consumer's, documented in SERVICE-INTEGRATION.
+    maxTaskCostUsd: z.number().finite().nonnegative().optional(),
+    maxTaskTokens: z.number().int().nonnegative().optional(),
+    maxPrincipalCostUsd: z.number().finite().nonnegative().optional(),
+    costQuotaWindowSec: z.number().int().positive().optional(),
+});
+// ── Domain: governance (治理三件 — split out of runtime, EXPERT-REDESIGN §5) ──────
+// The governance trio an operator tunes via publish: autonomy ladder + command guardrails + approval-required
+// tools. NOT下沉 — gets its own admin tab (E5 form; E1 ships a transitional generic editor). Same `.optional()`
+// no-default discipline as the six gates: ABSENT = center 不管这项(keep env / 消费者默认),present 才生效。
+export const GovernanceConfig = z.object({
+    // autonomy:一个跨 knob 的安全总开关 / 放权梯度(普通用户敢用 + 专业用户放权)。
+    //   read-only(只读规划,不落改)| ask(每个放权动作问)| plan(plan-review 门)| auto(放开)。
+    // ⚠️ 消费侧(service)把它**展开**到 core 已有三原语(handsReadOnly / shellGate+onAsk / plan_review),
+    //   经 core 的收紧-only `tightenTaskSpec` 合并。core 裁决:不在 core 加并行 autonomy 枚举(双实现陷阱),
+    //   不静默覆盖调用者已设安全字段(auto 模式尤其不能静默清门控)。详见 sema-registry docs/CONFIG-RESEARCH §10。
+    autonomy: z.enum(["read-only", "ask", "plan", "auto"]).optional(),
+    // commandPolicy:命令级 allow/ask/deny 护栏(remoteExec 管"在哪跑",这管"能跑什么命令")。每条 = 一个
+    //   **精确 argv[0] 命令名** → 决策;**DENY-WINS**(冲突 deny 赢,与 core `combinePolicies` 一致,NOT last-match-wins)。
+    // ⚠️ EXACT,不是 glob(service [202] 裁决①,2026-06-22):core 1.114.0 shipped 的 `createCoarseCommandNamePolicy`
+    //   是 **精确 Set 匹配**(§10 把 `createCommandGlobPolicy` 降级时 glob 能力即移除——glob-on-argv[0] 正是 codex
+    //   要避的 bypass 面)。所以 `git*` 这类 glob 在此**被 fail-loud 拒绝**(不是静默永不匹配=放行的 fail-open 洞);
+    //   要扩面靠 allowlist/blocklist 模式(消费侧),不靠通配。
+    // ⚠️ COARSE / 非沙箱:只匹配 leading simple-command 名(经 core `parseLeadingCommandName` fail-closed 解析器);
+    //   `$(...)` / `sh -c` / `env` / `xargs` / `find -exec` / `python -c` / 子命令都绕得过——是 egress/irreversibility
+    //   安全轴之下的**纵深防御,绝非唯一隔离**(真隔离靠 executionEnv sandbox)。消费侧(service)必须经
+    //   `combinePolicies(部署默认, 本策略)` 编译进 `TaskSpec.toolPolicy`,绝不裸覆盖清掉部署级护栏;`shellGate:
+    //   "classify"` 下普通 ask 会被 irreversibility 提升为不可预算的 irreversible_ask。core 建
+    //   `createCoarseCommandNamePolicy` 消费它(config-research §10)。
+    commandPolicy: z
+        .array(z.object({
+        // 精确 argv[0] 命令名(如 "rm" / "git" / "docker-compose" / "python3.11")—— NOT a glob、NOT a path、NOT a
+        // shell 片段。拒 `*`/`?`(glob)、`/`(路径)、空格/shell 算符:运行时只拿 argv[0] 的名做精确匹配,任何这些
+        // 字符都永不匹配 = 规则静默失效(fail-open)→ 在此 fail-loud 拒收,逼操作员写成能真正生效的精确名。
+        command: z
+            .string()
+            .min(1)
+            .max(128)
+            .regex(/^[A-Za-z0-9._+-]+$/, "exact argv[0] command NAME — letters/digits/._+- only; NO glob (*,?), path (/), spaces or shell fragments — e.g. rm, git, docker-compose"),
+        decision: z.enum(["allow", "ask", "deny"]),
+    }))
+        .optional(),
+    /** Tool names needing operator approval (F4). Moved verbatim from runtime (same ABSENT/explicit-[] semantics). */
+    approvalRequire: z.array(z.string()).optional(),
+});
+/** The governance trio keys. 0.7.1:写出方向的 runtime 双写镜像已撤(service 1.150.0 已切新位,[549]
+ *  回执确认)——此常量今日唯一职责=READ 方向的 legacy lift(governance 域从未设时从旧 runtime 文档抬升,
+ *  config-fns legacyGovernanceFromRuntime),单一键源防逐键漂移。 */
+export const GOVERNANCE_MIRROR_KEYS = ["autonomy", "commandPolicy", "approvalRequire"];
+// ── integrations domain: DELETED in 0.6.0 (EXPERT-REDESIGN §9 — 零消费者实锤:service 明确排除,OA/Gitea
+// 实走 worker.env)。“按 scope connect GitHub” 是 backlog 的全新设计,不复用此形状。
+// ── access domain: DELETED in 0.6.0 (EXPERT-REDESIGN §9 — 彻底删除不留兼容;唯一消费者 agent-client portal
+// 已迁 env 名单,CHANNEL [339])。人员自助申请 access_request 与 git-identities 是不同前缀,保留,与此无关。
+// ── Domain: entitlement (per-PRINCIPAL governance — the "管人" axis, ⊥ console RBAC) ───────────────────────
+// L2 of the control plane (design CENTER-CONTROL-PLANE §3): who-can-USE-what (models / skills / mcp / budget /
+// runtime caps), keyed by the runtime PRINCIPAL — orthogonal to the api-token RBAC (who-can-EDIT-config); mixing
+// the two is a security incident. Stored in full here; the worker `/effective` EMPTIES it (privacy — never leak
+// every principal's tier/budget to a worker), and `/effective?principal=` resolves the per-principal view
+// (effective = worker-base ∩ tier⊕roles ∩ time-bounded overrides; intersection = either side's "deny" wins).
+// Minimal records — never raw usage numbers (those live in the data plane / telemetry).
+/** Token budget — LiteLLM-interop vocab + the center-specific DEGRADE mode + a per-RUN admission gate. */
+export const EntitlementBudget = z.object({
+    /** soft = alert only · hard = pre-call block · degrade = fall back to a cheaper model (center-specific). */
+    mode: z.enum(["soft", "hard", "degrade"]).optional(),
+    // .finite() on every $/USD float: z.number().nonnegative() accepts Infinity, which JSON.stringify's to null on
+    // persist → a later strict reparse throws (fail-open on write, fail-hard on read). Same discipline as ModelCost.
+    maxBudgetUsd: z.number().finite().nonnegative().optional(),
+    budgetDuration: z.string().optional(), // e.g. "30d"
+    tpmLimit: z.number().int().nonnegative().optional(),
+    rpmLimit: z.number().int().nonnegative().optional(),
+    maxParallelRequests: z.number().int().nonnegative().optional(),
+    perModel: z.record(z.string(), z.object({ maxBudgetUsd: z.number().finite().nonnegative().optional(), tpmLimit: z.number().int().nonnegative().optional(), rpmLimit: z.number().int().nonnegative().optional() })).optional(),
+    /** Per-RUN admission gate (agentic-runaway guard, §3.3 🔴) — period budgets can't stop ONE runaway run. */
+    maxRunCostUsd: z.number().finite().nonnegative().optional(),
+    maxIterations: z.number().int().positive().optional(),
+    /** WHERE this budget is enforced (scheduling framework D4, clay 拍 2026-07-04): `local` = worker-only
+     *  (per-instance or shared-DB — today's posture) · `lease` = AP pre-authorized QuotaLease from center +
+     *  after-the-fact reconciliation (default for sema-managed fleets) · `central` = CP pre-call check against
+     *  center (strict tenants; slow but exact). ABSENT = local. Orthogonal to `mode` (what happens on breach). */
+    enforcement: z.enum(["local", "lease", "central"]).optional(),
+});
+/** Token 双窗额度(配额轴, EXPERT-REDESIGN §4 — Claude 式 5h 滚动窗 + 自然周窗),单位=加权 tokens
+ *  (ModelEntry.quotaWeight 折算,weight-at-burn 记账时固化)。挂载点**只三处**:defaults(全局默认)/
+ *  subject(用户)/groupBinding(组) —— **绝不挂 tier**(B1 违宪修复,EntitlementTier fail-loud 拒收)。
+ *  取值极性(与 budget 的 min-wins 不同,明定):最具体一层生效(用户 > 组 > 全局默认),同层多组命中取
+ *  更严;tokenQuota 不参与 budget 的 min-of-budgets 归并。任一窗耗尽即拒(CC 式拒绝+恢复时间,E4)。 */
+export const TokenQuota = z.object({
+    /** 5h 滚动窗额度(加权 tokens)。ABSENT = 此窗不设限。 */
+    fiveHourTokens: z.number().int().nonnegative().optional(),
+    /** 自然周窗额度(加权 tokens)。ABSENT = 此窗不设限。 */
+    weeklyTokens: z.number().int().nonnegative().optional(),
+});
+/** 预算组(共享钱池,§4-1)——与个人 budget 双轨并行:一笔花费计入个人轨 + 所有所属池;多池并存取最先
+ *  耗尽;tokens 配额轴(TokenQuota)与它是两轨,先到顶者生效。成员条目带 `memberSince`:池只聚合入组时刻
+ *  之后的用量(入组不带入已烧量、退组不回落)——契约随 E1 冻结。 */
+export const BudgetGroupMember = z.object({
+    /** 池成员生效时刻(ISO)——用量聚合的下边界。 */
+    memberSince: z.string().min(1),
+});
+export const BudgetGroup = z.object({
+    id: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "budget group id: letters/digits/._- , no spaces"),
+    name: z.string().min(1),
+    maxBudgetUsd: z.number().finite().nonnegative(),
+    /** 池预算周期,e.g. "30d"(同 EntitlementBudget.budgetDuration 词汇)。ABSENT = 不按周期重置。 */
+    budgetDuration: z.string().optional(),
+    members: z
+        .object({
+        /** instance-level group ids(registry `groups` 表——store 对象,zod 看不见,存在性同 groupBindings
+         *  先例不做 schema 校验,dangling 由 UI 标红)。 */
+        groups: z.array(BudgetGroupMember.extend({ group: z.string().min(1) })).default([]),
+        principals: z.array(BudgetGroupMember.extend({ principal: z.string().min(1) })).default([]),
+    })
+        .default({ groups: [], principals: [] }),
+});
+/** 生效场景分配(§7,与配额同一挂载心智):全局默认 + 按组 + 按用户三层;解析优先级=用户 > 组 > 全局默认
+ *  > worker 级 runtime.scenario 兜底(引擎兜底行为待 ask② 确认)。`scenario` 是场景 NAME——可指 center
+ *  scenarios 域条目,也可指 service 内建场景名(内建不在域里,故**不做** cross-domain 存在性硬校验,
+ *  dangling 由 UI 标注)。 */
+export const ScenarioAssignments = z.object({
+    /** 全局默认场景名。ABSENT = 不设全局默认(落到 worker 级 runtime.scenario / 引擎内建)。 */
+    default: z.string().min(1).optional(),
+    groups: z.array(z.object({ group: z.string().min(1), scenario: z.string().min(1) })).default([]),
+    principals: z.array(z.object({ principal: z.string().min(1), scenario: z.string().min(1) })).default([]),
+});
+/** Org-forced-off runtime ceilings (gate②). ABSENT = no ceiling (local controls); `false` = org-disabled
+ *  fleet-wide. Only ever pushes the "off" ceiling — never force-enables (monotone tighten-only). */
+export const EntitlementRuntimeCaps = z.object({
+    allowBypassPermissions: z.boolean().optional(),
+    allowAutoMode: z.boolean().optional(),
+    /** Per-principal governance of the workflow/ultracode capability (K-2, clay 2026-06-28). center treats this as
+     *  the "准不准" axis; the engine separately advertises "能不能" (Capabilities.workflows). The shell enables
+     *  ultracode/workflows iff engine-capable ∧ principal-entitled. Like the others: ABSENT = no ceiling,
+     *  `false` = org-disabled fleet-wide (tighten-only false-wins; never force-enables). Full server-side
+     *  enforcement awaits core adding a per-principal authz axis that consumes this; until then it gates the shell UI. */
+    allowWorkflows: z.boolean().optional(),
+    /** Per-principal governance of the Fork (fork-session) tool — center's "准不准" axis, mirroring allowWorkflows.
+     *  The engine advertises "能不能" separately; a Fork is admitted iff engine-capable ∧ principal-entitled. Like the
+     *  others: ABSENT = no ceiling (Fork allowed), `false` = org-disabled fleet-wide (tighten-only false-wins; never
+     *  force-enables). core (RuntimeCaps.allowFork, prepare-task) consumes this per-principal: `allowFork === false`
+     *  → Fork DENIED, else allowed. */
+    allowFork: z.boolean().optional(),
+    /** Per-principal governance of observer agents (core 1.270.0/1.273.0 OBS-2, 板 [661]④/[668]①/[671]②) —
+     *  center's "准不准" axis for the AgentDefinition.observer pairing surface. ⚠️ core's consumption polarity is
+     *  INVERTED vs the other allow* caps: the engine is `=== true` explicit opt-in (default OFF — an undefined cap
+     *  ships dark), so this key is the ENABLE line, not just a ceiling. Three-state semantics (ABSENT ≠ false):
+     *  ABSENT = center says nothing → key NOT emitted on the wire (core stays the SOLE default source; service's
+     *  toCoreRuntimeCaps must not backfill a missing key into an explicit verdict — that would poison the
+     *  env-baseline compose order); `true` = explicitly enable observer agents for this principal; `false` =
+     *  explicit org deny — overrides the node-level env baseline EXPERIMENTAL_OBSERVER_AGENTS (center speaks →
+     *  center wins). On compose across bundles, `false` (deny) still wins — see RUNTIME_CAP_STRICT; core's
+     *  `=== true` opt-in check is orthogonal to that merge polarity. */
+    allowObservers: z.boolean().optional(),
+    allowUltracode: z.boolean().optional(),
+    /** Force this principal's run onto durable-approval (per-tool gate) — center's fleet-wide handle for CC-faithful
+     *  per-tool interception (K-3, core [318] confirmed it consumes this). Polarity is INVERTED vs the allow* caps:
+     *  here `true` is the STRICT/tightening value (forcing the gate ON), so it wins on compose — see RUNTIME_CAP_STRICT.
+     *  ABSENT = no fleet override (local/default resolution decides). Server-side enforcement = core's per-principal axis. */
+    forceDurableGate: z.boolean().optional(),
+});
+/** The STRICT (tightening) value per RuntimeCap — the value that WINS on compose (monotone tighten-only). The
+ *  `allow*` ceilings tighten toward `false` (disabled wins); `forceDurableGate` tightens toward `true` (forced
+ *  wins). Single source for the merge polarity so resolvers don't hardcode it. `Record<keyof …>` = a new cap
+ *  without an entry is a COMPILE error (no silent wrong-direction merge). */
+export const RUNTIME_CAP_STRICT = {
+    allowBypassPermissions: false,
+    allowAutoMode: false,
+    allowWorkflows: false,
+    allowFork: false,
+    allowObservers: false,
+    allowUltracode: false,
+    forceDurableGate: true,
+};
+/** A named entitlement bundle (a `tier`, or a composable `role`). Bind a `roster` to inherit its model/skill/mcp
+ *  visibility for free; explicit allowlists intersect on top. Edit a tier once → re-prices everyone on it. */
+export const EntitlementTier = z.object({
+    id: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "tier id: letters/digits/._- , no spaces"),
+    roster: z.string().optional(),
+    models: z.array(z.string()).optional(),
+    visibleSkills: z.array(z.string()).optional(),
+    visibleMcp: z.array(z.string()).optional(),
+    /** Plugin allowlist (plugins domain NAMEs) — plugins are an executable surface, so the same null/absent =
+     *  "no constraint on this axis" semantics as visibleMcp (deny-wins on intersection; C2, additive 0.5.0). */
+    visiblePlugins: z.array(z.string()).optional(),
+    budget: EntitlementBudget.optional(),
+    runtimeCaps: EntitlementRuntimeCaps.optional(),
+    /** 🔴 B1 违宪修复(EXPERT-REDESIGN §4-1):tokenQuota **不挂 tier** —— 只挂 defaults/subject/groupBinding。
+     *  fail-loud 而非 zod 默认的静默剥除(admin 挂上去以为生效才是最糟的)。 */
+    tokenQuota: z
+        .custom(() => false, { message: "tokenQuota does not mount on a tier — mount it on defaults / subjects[] / groupBindings[] (拍板:配额挂用户/组,非访问级别)" })
+        .optional(),
+});
+/** A time-bounded, audited per-principal override (escape hatch above the tier/role defaults). */
+export const EntitlementOverride = z
+    .object({
+    principal: z.string().min(1),
+    key: z.string().min(1),
+    value: z.unknown(),
+    effectiveFrom: z.string().optional(),
+    effectiveUntil: z.string().optional(),
+    approvedBy: z.string().min(1),
+    reason: z.string().optional(),
+})
+    .superRefine((o, ctx) => {
+    // value is persisted in the entitlement domain + frozen into PublishedSnapshot + audited — a pasted secret
+    // would ride along. Reject any secret-looking token (string or anywhere in a JSON value). Reference secrets
+    // by env-NAME, never inline. (Budget overrides are numbers/enums, so this never fires on the v1 use.)
+    const s = typeof o.value === "string" ? o.value : o.value == null ? "" : JSON.stringify(o.value);
+    if (s && containsSecretToken(s))
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "override.value appears to contain a secret token — overrides are persisted + audited; reference secrets by env-NAME, never inline a value", path: ["value"] });
+});
+export const EntitlementSubject = z.object({
+    principal: z.string().min(1),
+    displayName: z.string().optional(),
+    tierId: z.string().optional(),
+    /** Additional tier ids composed on top of `tierId` (union of allows, min of budgets) — the "role combo". */
+    roles: z.array(z.string()).default([]),
+    overrides: z.array(EntitlementOverride).default([]),
+    /** 用户层 token 双窗额度(最具体层,压过组与全局默认——极性见 {@link TokenQuota})。 */
+    tokenQuota: TokenQuota.optional(),
+});
+/** A GROUP → tier/roles binding (W4-Q01 已拍: 组绑定住在 entitlement 域内, per-scope 天然). `group` is the
+ *  INSTANCE-LEVEL group id (registry `groups` table — a store object, invisible to zod, so group EXISTENCE
+ *  cannot be schema-checked; a dangling group binding silently matches nobody and the UI red-flags it).
+ *  Merge semantics (W4-Q02 已拍, 并列合并): a member of the group gets the binding's tier ⊕ roles bundles
+ *  UNIONED with their personal subject bundles on the allow axes; budget/runtimeCaps stay tighten-only
+ *  (更严者胜) — a group binding can NARROW a personal budget, never widen it (top invariant). Overrides
+ *  remain personal-only (subject.overrides) — no group-wide escape hatch. */
+export const EntitlementGroupBinding = z.object({
+    group: z.string().min(1),
+    tierId: z.string().optional(),
+    /** Additional tier ids composed on top of `tierId` — same "role combo" shape as EntitlementSubject. */
+    roles: z.array(z.string()).default([]),
+    /** 组层 token 双窗额度(同层多组命中取更严;被用户层压过——极性见 {@link TokenQuota})。 */
+    tokenQuota: TokenQuota.optional(),
+});
+export const EntitlementConfig = z
+    .object({
+    /** FLEET-WIDE baseline applied to EVERY principal — including those with NO subject record. This is how an
+     *  org kill-switch (e.g. runtimeCaps.allowBypassPermissions:false) reaches unconfigured principals: a tier
+     *  can only TIGHTEN further (monotone), never re-loosen the default. Leave unset for per-tier-only control. */
+    defaults: z
+        .object({
+        runtimeCaps: EntitlementRuntimeCaps.optional(),
+        budget: EntitlementBudget.optional(),
+        /** 全局默认 token 双窗额度(最不具体层——被组/用户层压过)。 */
+        tokenQuota: TokenQuota.optional(),
+    })
+        .optional(),
+    tiers: z.array(EntitlementTier).default([]),
+    subjects: z.array(EntitlementSubject).default([]),
+    /** Group bindings (W4, additive 0.4.0) — bind an instance-level GROUP to a tier ⊕ roles combo. */
+    groupBindings: z.array(EntitlementGroupBinding).default([]),
+    /** 预算组(共享钱池,0.6.0 §4)——见 {@link BudgetGroup}。 */
+    budgetGroups: z.array(BudgetGroup).default([]),
+    /** 生效场景分配(0.6.0 §7)——见 {@link ScenarioAssignments}。 */
+    scenarioAssignments: ScenarioAssignments.optional(),
+})
+    .superRefine((cfg, ctx) => {
+    const tierIds = new Set();
+    cfg.tiers.forEach((t, i) => {
+        if (tierIds.has(t.id))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate tier id "${t.id}"`, path: ["tiers", i, "id"] });
+        tierIds.add(t.id);
+    });
+    const seenPools = new Set();
+    cfg.budgetGroups.forEach((b, i) => {
+        if (seenPools.has(b.id))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate budget group id "${b.id}"`, path: ["budgetGroups", i, "id"] });
+        seenPools.add(b.id);
+    });
+    const seenGroups = new Set();
+    cfg.groupBindings.forEach((g, i) => {
+        if (seenGroups.has(g.group))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate group binding "${g.group}"`, path: ["groupBindings", i, "group"] });
+        seenGroups.add(g.group);
+        if (g.tierId && !tierIds.has(g.tierId))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `group binding "${g.group}" → unknown tier "${g.tierId}"`, path: ["groupBindings", i, "tierId"] });
+        g.roles.forEach((r, j) => { if (!tierIds.has(r))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `group binding "${g.group}" → unknown role/tier "${r}"`, path: ["groupBindings", i, "roles", j] }); });
+    });
+    const seen = new Set();
+    cfg.subjects.forEach((s, i) => {
+        if (seen.has(s.principal))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate subject principal "${s.principal}"`, path: ["subjects", i, "principal"] });
+        seen.add(s.principal);
+        if (s.tierId && !tierIds.has(s.tierId))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `subject "${s.principal}" → unknown tier "${s.tierId}"`, path: ["subjects", i, "tierId"] });
+        s.roles.forEach((r, j) => { if (!tierIds.has(r))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `subject "${s.principal}" → unknown role/tier "${r}"`, path: ["subjects", i, "roles", j] }); });
+        s.overrides.forEach((o, j) => { if (o.principal !== s.principal)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `override.principal "${o.principal}" must equal subject "${s.principal}"`, path: ["subjects", i, "overrides", j, "principal"] }); });
+    });
+});
+// ── Domain: execution (S3 执行轴管控 — WHERE work may run, stage7 S3 / P5=A) ──────────────────
+// The execution-LANE policy an admin sets per scope(「团队任务必须在沙箱/受控执行环境中运行」).
+// Resolution MIRRORS the governance precedent: a plain SCOPE-level domain — no per-principal overlay,
+// no layer merge invented here (entitlement is the per-principal axis; this is not it). v1 = scope 级.
+// ⚠️ ENFORCEMENT HONESTY (P5=A, 2026-07): today the shell enforces this CLIENT-SIDE only (it locks its
+// sandbox settings by policy, CC managed-settings semantics) — env / a local config-source can bypass it.
+// The REAL boundary (engine gate refusing a disallowed lane) is the service's, tracked on blackboard
+// [580]; until that ships, never present this policy as a hard security boundary.
+/** sessionMirror TARGET url 的底线传输校验(0.10.1;0.10.2 加 trim 前置):**https,或 loopback http**
+ *  (本机第二引擎/dev)。与壳 `evaluateEngineRouting`(sema-shell engineTarget.ts,S1 路由闸)语义对齐:
+ *  镜像上行带会话内容+Bearer 凭证,非 loopback 明文 http = 凭证与会话数据裸奔——**写侧 schema 层就拒**
+ *  (fail-loud 比读侧执法更早;center 编辑面存不进去,壳读侧闸只兜手改存储的漏网)。基线复用
+ *  {@link NON_SECRET_URL}(禁 userinfo 凭证/禁 query/fragment 夹带 secret-shaped 值)。loopback 判定与壳
+ *  isLoopbackEngineUrl 逐字同表:127.0.0.1 / localhost / ::1 / [::1](URL.hostname 对 IPv6 带方括号,
+ *  两写法都收)。**trim 前置(0.10.2,附B 三单合评审 M-1)**:前导/尾随空白先归一再验且存储值即 trim
+ *  后值——否则 " https://…" 写侧收(new URL 容忍前导空白)而壳读侧逐字符比对拒 = 全员镜像静默 degraded。 */
+export const SESSION_MIRROR_ENGINE_URL = z.string().trim().pipe(NON_SECRET_URL).refine((s) => {
+    try {
+        const u = new URL(s);
+        if (u.protocol === "https:")
+            return true;
+        const h = u.hostname;
+        return h === "127.0.0.1" || h === "localhost" || h === "::1" || h === "[::1]";
+    }
+    catch {
+        return true; // already passed NON_SECRET_URL; unreachable in practice
+    }
+}, "non-loopback sessionMirror.engineUrl must be https — the mirror carries session content + a Bearer credential; plain http across the network is rejected at WRITE time (shell evaluateEngineRouting 同款传输闸)");
+/** Org 默认会话镜像目标(WEB-SETUP-RECON 附B,clay 拍两层,0.10.1)。**收编进 execution 域**(非独立
+ *  域)——142-S3 草案同款尺量:①同一治理轴(org 对「会话数据必须落到受控引擎」的 scope 级管控,与
+ *  「任务必须跑在受控 lane」同族;`required` 语义与 {@link ExecutionPolicy}.required 完全同构=壳锁定、
+ *  用户不可关、CC managed-settings 心智);②**无独立读损语义**(损坏退默认=required:true 审计强制静默
+ *  蒸发=放权,与 execution 的 throw 理由逐字同款——tierGroups 收编 models 的同款判据);③无独立写面
+ *  (纯声明字段,整文档 PUT 表达,无动作端点;RBAC 同 editor 档,信任面=org 背书与模型下发同级)。
+ *  独立域只换来第 16 域膨胀+#74 双表态+缺域 fixture 全套纯开销。
+ *  两层语义(附B r1 终稿):
+ *  - `required:false`(默认)= **便利默认值**:壳解析序第三腿(本地显式 --target > 本值 > connect
+ *    回落),开关仍由用户 `sync on`(隐私 opt-in 先例不破,STAGE7 P3);
+ *  - `required:true` = **org 治理强制**:会话镜像默认开且不可关,且**本地覆盖不生效——既不能改目标
+ *    也不能关闭(org 压一切;附B 三单合评审 MAJOR-1 勘误:治理态下本地 --target 完全被忽略)**
+ *    (审计场景;壳复用 CC managed-settings 锁定报错串——S3 execution 沙箱锁完全同构先例)。
+ *  整个 sessionMirror **optional,缺省 INERT**(无下发=老 center/老壳/0.8-0.10 存量 execution 文档
+ *  零行为差、零迁移)。⚠️ ENFORCEMENT HONESTY 同域头注:required 的锁今天也是 CLIENT-SIDE 执法。
+ *  开放演化:v2 可能加 audit 字段类(保留窗/脱敏面等)——本对象刻意**不 .strict()**(zod 默认 strip
+ *  未知键:v2 文档被 v1 消费者读到=未知键剥除,forward-compatible;加字段恒 additive patch)。 */
+export const SessionMirrorPolicy = z.object({
+    /** 镜像目标引擎 url(service 线 /v1 base)。校验见 {@link SESSION_MIRROR_ENGINE_URL}。 */
+    engineUrl: SESSION_MIRROR_ENGINE_URL,
+    /** true = org 治理强制(镜像默认开且不可关);false(默认)= 便利默认值(只补目标,不动开关)。 */
+    required: z.boolean().default(false),
+});
+export const ExecutionPolicy = z.object({
+    /** true = tasks under this scope MUST run in a sandbox / controlled execution lane (the consuming
+     *  shell locks sandbox-enabled by policy; user settings can't turn it off — CC 同款语义). */
+    required: z.boolean().default(false),
+    /** Which execution lanes are allowed. OPEN value domain — z.string(), NEVER an enum: adding a lane
+     *  must not be a BREAKING schema change (promised to the service on blackboard [580]④). Known lanes
+     *  today: `host` / `e2b` / `k8s` / `ssh` / `adb` / `local-docker`. Unknown strings are consumer-defined. */
+    allowedLanes: z.array(z.string().min(1)).default(["host"]),
+    /** Org 默认会话镜像目标(0.10.1,附B 两层)。ABSENT = INERT(center 未管镜像,壳解析序里本腿为空)。
+     *  读损档随域(DOMAIN_READ_FALLBACK.execution="throw" 已覆盖:损坏绝不静默退默认放权)。 */
+    sessionMirror: SessionMirrorPolicy.optional(),
+});
+// ── Domain: projects (142-S3 — project identity ledger + 无仓铸造权威, 0.10.0) ─────────────────
+// 登记簿语义(design/142 §1.3/F11):marker(`.sema/project`,checkout 现场)是身份真相源,本域是
+// 登记簿(索引/展示/审计)+ 无仓 project 的 projectId 铸造权威。铸造离线自由、使用时注册执法
+// (blackboard [633]①):执法位在 service worker(派生 `proj:*` 可读 scope 前查 `(tenant,projectId)`
+// 已注册),本域只是它查的那张表——登记簿**不读 marker 文件、不镜像 marker schema**([641]④ 确认)。
+// 复合键 `(tenant, projectId)` 的 tenant 半边由 center 的 SCOPE 轴承载(api/scopes.ts:每 scope 一份
+// 独立域文档),域内 Record 键=projectId only;fork 后同一 projectId 合法存在于两个 scope,互不相见。
+/** projectId 形状:lowercase 规范 UUID。**宽读严写**([641]②,core 口径):读面/claim 收 generic
+ *  UUID(外部/历史铸造的 v4 也认——marker 是身份不是格式声明);铸造侧(core formatProjectMarker /
+ *  center mint 端点)统一产 **uuidv7**。36 字符,天然满足 design/142 §1.2 段编码 64 上限。
+ *  SINGLE-SOURCE 纪律:core 1.268.0 尚未公开导出其内部 UUID_RE——本常量为自持镜像,与 core 的对拍
+ *  走 dev-only conformance(never a runtime import,EffectiveKey/coreTypes 先例)。
+ *  TODO(0.10.x): @sema-ai/core 下一班车公开导出 PROJECT_ID_REGEX 后([641]②-①承诺,黑板点名),
+ *  加 dev-only drift-lock 测试与其对拍(坐标:test/projects-0.10.test.ts「conformance」节)。 */
+export const PROJECT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const ProjectRegistration = z.object({
+    /** 人读名(展示/管理面用;不是身份,改名自由——身份=Record 键 projectId)。 */
+    displayName: z.string().min(1).max(120),
+    /** 归一化 git remotes(`host/path` 形态,design/142 §1.1 归一化规范)。归一化动作发生在 scaffold/
+     *  调用方,本契约只验底线形状:非空、无空白、不含 "://"(出现即证据未归一化,fail-loud)。
+     *  无仓 project = 空数组合法。`.max(16)` 防登记簿被单条撑爆。 */
+    gitRemotes: z
+        .array(z
+        .string()
+        .min(1)
+        .max(512)
+        .refine((s) => !/\s/.test(s) && !s.includes("://"), "must be a NORMALIZED remote (host/path — no scheme, no whitespace)"))
+        .max(16)
+        .default([]),
+    /** 该项目会话的默认记忆 scope 词表。OPEN value domain — z.string(),不 enum([580]④ 纪律:加词
+     *  不得 BREAKING)。方向([641]②-③,S4 细化):消费方=service memoryScope 派生(作 TaskSpec.
+     *  memory.scopes 种子),形态=v2 scope 键字符串(过 core parseScopeKey 校验;known 词根:`proj` /
+     *  `userproj`)。未知串=消费者自定义;空数组=不下发默认。本域只登记不解释,零耦合。 */
+    defaultScopes: z.array(z.string().min(1)).default([]),
+    /** 登记人 principal(审计锚;center 写面自动填 caller,不信客户端提交)。 */
+    registeredBy: z.string().min(1),
+    /** 登记时刻(ISO)。center 写面 server 端盖章。 */
+    registeredAt: z.string().min(1),
+    notes: z.string().optional(),
+});
+export const ProjectsConfig = z
+    .object({
+    /** 键=projectId({@link PROJECT_ID_REGEX},generic lowercase UUID——宽读);tenant 半边=center
+     *  scope 轴(不进域文档,见域头注)。 */
+    projects: z.record(z.string().regex(PROJECT_ID_REGEX, "projectId must be a lowercase canonical UUID"), ProjectRegistration).default({}),
+})
+    .superRefine((cfg, ctx) => {
+    // 同 scope 内一条 remote 只许属于一个 project——「remote → projectId」找回阶梯(design/142
+    // §1.5 ③)与 scaffold 防重铸查询要求该映射在租户内确定;撞了=写入 fail-loud(合法双登记诉求
+    // 出现时再放开,先紧后松 additive)。
+    const seen = new Map();
+    for (const [pid, reg] of Object.entries(cfg.projects)) {
+        for (const [i, r] of reg.gitRemotes.entries()) {
+            const prev = seen.get(r);
+            if (prev !== undefined && prev !== pid) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: `remote "${r}" already registered to project "${prev}"`, path: ["projects", pid, "gitRemotes", i] });
+            }
+            seen.set(r, pid);
+        }
+    }
+});
+// ── Domain: collab (协作模式 — multi-model collaboration templates, 0.7.0) ─────
+// Replaces the deleted `teams` domain (EXPERT-REDESIGN §8/§9, clay 五拍 T1-T5, blackboard [544]/[548]④).
+// Unified shape = slots × topology × rounds × finalizer. COMPLETELY separate from rosters (拍板): a slot
+// member's `modelRef` points at the models CATALOG (`ModelEntry.name`, the key — NOT the gateway modelId,
+// NOT a roster); roster churn never touches a template. Execution lives service-side ("collab spec →
+// workflow/team run" translation layer, [544]①); the center owns the template CONFIG only.
+export const CollabTopology = z.enum(["star", "ring", "layered", "pair", "blackboard"]);
+export const CollabFinalizerType = z.enum(["judge", "vote", "fuse", "verify", "summarize", "none"]);
+export const CollabEarlyStop = z.enum(["consensus", "stability", "judge_call", "verify_pass"]);
+/** Shared-context persistence. v1 durable lane = "store-blob" (service's existing durable face, [548]④);
+ *  "git" (auditable/replayable history) is a RESERVED enum position — accepted by the contract, execution
+ *  is a service follow-on (deliberately not bound to 0.7). */
+export const CollabPersistence = z.enum(["session", "store-blob", "git"]);
+const CollabMember = z.object({
+    /** Models-CATALOG name (the `@`-handle key). ABSENT = "跟随用户当前模型" — resolved at run time to the
+     *  caller's current model (T1; service resolves at team assembly, [544]③). Never a roster reference. */
+    modelRef: z.string().min(1).optional(),
+    /** Member-level lens/persona override (各带镜头 — a heterogeneous review panel puts N members with
+     *  different lenses in ONE cardinality-"N" slot). Falls back to the slot's `rolePrompt`. */
+    rolePrompt: z.string().max(2000).optional(),
+});
+const CollabSlot = z.object({
+    // The slot id is the canvas anchor AND the finalizer/transcript attribution key — same safe-identifier
+    // shape as a model name (it may be concatenated into prompts; no spaces/newlines → no prompt-structure injection).
+    id: z.string().min(1).regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, "letters/digits/._- only"),
+    /** Slot-default lens/立场 (template-provided; a member's own `rolePrompt` overrides it). */
+    rolePrompt: z.string().max(2000).optional(),
+    /** 1 = exactly one member; "N" = the slot accepts multiple members (异构评审团). */
+    cardinality: z.union([z.literal(1), z.literal("N")]).default(1),
+    members: z.array(CollabMember).default([]),
+    /** Tool names available to this slot's members (the old team `scenario` binding migrates here). */
+    tools: z.array(z.string().min(1)).optional(),
+});
+const CollabTemplate = z.object({
+    /** The template's reference key (shell `/team` selects by id; canvas routes by id). */
+    id: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    topology: CollabTopology,
+    slots: z.array(CollabSlot).min(1),
+    /** `max` is ALWAYS the safety cap (blackboard topology: event/round cap — required, 防跑飞);
+     *  `earlyStop: "verify_pass"` carries the architect pair's "verified → stop" loop. */
+    rounds: z.object({ max: z.number().int().positive(), earlyStop: CollabEarlyStop.optional() }),
+    finalizer: z.object({
+        type: CollabFinalizerType,
+        /** Slot id the finalizer anchors to (e.g. the judge slot). Meaningless for type "none". */
+        slot: z.string().optional(),
+    }),
+    sharedContext: z
+        .object({
+        kind: z.enum(["transcript", "blackboard"]).default("transcript"),
+        persistence: CollabPersistence.default("session"),
+    })
+        .default({}),
+    /** 多模型烧钱必须有闸 (拍板): the budget object is REQUIRED and at least one axis must be set. */
+    budget: z.object({
+        maxTokens: z.number().int().positive().optional(),
+        maxCost: z.number().finite().positive().optional(),
+    }),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+}).superRefine((t, ctx) => {
+    const slotIds = new Set();
+    t.slots.forEach((s, i) => {
+        if (slotIds.has(s.id))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate slot id "${s.id}"`, path: ["slots", i, "id"] });
+        slotIds.add(s.id);
+        if (s.cardinality === 1 && s.members.length > 1)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `slot "${s.id}" has cardinality 1 but ${s.members.length} members`, path: ["slots", i, "members"] });
+    });
+    if (t.finalizer.type === "none") {
+        if (t.finalizer.slot !== undefined)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `finalizer type "none" must not anchor a slot`, path: ["finalizer", "slot"] });
+    }
+    else if (t.finalizer.slot !== undefined && !slotIds.has(t.finalizer.slot)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `finalizer.slot "${t.finalizer.slot}" is not a slot id of this template`, path: ["finalizer", "slot"] });
+    }
+    if (t.budget.maxTokens === undefined && t.budget.maxCost === undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `template "${t.id}": budget needs at least one of maxTokens/maxCost (多模型烧钱必须有闸)`, path: ["budget"] });
+    }
+});
+export const CollabConfig = z.object({ templates: z.array(CollabTemplate).default([]) }).superRefine((cfg, ctx) => {
+    // `id` is the template's reference key — dedup like every other keyed domain (two same-id templates
+    // shipping → the resolver silently takes the first; same failure class the old teams dedup fixed).
+    const seen = new Set();
+    cfg.templates.forEach((t, i) => {
+        if (seen.has(t.id))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate collab template "${t.id}" — the template key must be unique`, path: ["templates", i, "id"] });
+        seen.add(t.id);
+    });
+});
+// ── Domain: workers (声明式编排 — service design/22, docs/ORCHESTRATOR.md) ──────
+// 每个 worker = 一个 sema-server 实例的声明（一份 env profile）。sema-registry 存 DESIRED（逻辑参数
+// + secret 的 env-NAME 引用，**绝不存 secret 值**）；一个 per-host reconciler 拉取后在宿主机本地解析
+// secret → 渲染 docker compose → up/down 收敛。worker spec ↔ service env 的精确映射见 worker-env.ts。
+//
+// 安全（service design/22 经 DeepSeek team 评审）：
+//  - 不提供任何挂载字段 → 杜绝 hostPath 攻击向量（合法镜像+合法 secretRef+恶意挂载偷宿主机文件）。
+//  - image 由 reconciler 按白名单强制（这里 default sema-server:latest）。
+//  - secretRefs 只是 env-NAME；真值在宿主机，reconciler 解析，永不进此库/网络/日志。
+// 时长串：整数 + 单位 s/m/h/d（如 "30m"/"2h"/"7d"）。lib/lifecycle/duration.ts 负责解析成 ms。
+const DURATION = z.string().regex(/^\d+(s|m|h|d)$/, 'duration like "30m", "2h", "7d" (units s/m/h/d)');
+// 生命周期 (design/25 §3 决策 3/4)。owner/purpose 用于配额 + 级联清理 + 审计；dependsOn 防级联雪崩。
+export const WorkerLifecycle = z.object({
+    kind: z.enum(["persistent", "ephemeral"]).default("persistent"),
+    /** ephemeral: 绝对存活时长，自 sema-registry 首次见到起算（防时钟漂移），到期硬移除。 */
+    ttl: DURATION.optional(),
+    /** 无活动多久 → 告警（MVP 只告警，不自动 disable）。数据源 = 反代 metrics。 */
+    idleTimeout: DURATION.optional(),
+    /** 归属（团队/项目）→ per-owner 配额 + owner 销毁时级联清理 + 审计。 */
+    owner: z.string().min(1).optional(),
+    purpose: z.string().optional(),
+    /** 依赖的其它 worker name —— sweeper 移除前查依赖，不孤儿化仍被依赖的 worker。 */
+    dependsOn: z.array(z.string().min(1)).optional(),
+});
+const WorkerSecretRefs = z.object({
+    /** NAME of the host env var holding the model API key → service MODEL_API_KEY (或 anthropic 时 ANTHROPIC_API_KEY). */
+    apiKeyEnv: ENV_NAME,
+    /** → SERVICE_AUTH_TOKEN (对外门禁). */
+    serviceAuthTokenEnv: ENV_NAME.optional(),
+    /** → GIT_API_TOKEN (只读，读被评审 repo). */
+    gitTokenEnv: ENV_NAME.optional(),
+    /** → TIDB_PASSWORD. */
+    tidbPasswordEnv: ENV_NAME.optional(),
+});
+/**
+ * Env keys the structured WorkerSpec fields already produce (worker-env.ts) — the general `env`/`secretEnv`
+ * passthrough may NOT set these (use the dedicated field). Blocks the council's two escape-hatch risks:
+ * redirecting model/traffic or disabling auth (PORT, MODEL_x, SESSION_BACKEND, REQUIRE_PRINCIPAL, gateway), and
+ * shadowing a projected secret with a literal (MODEL_API_KEY, SERVICE_AUTH_TOKEN, …). LOG_LEVEL is intentionally
+ * NOT reserved (benign, overridable for debugging). Keep in sync with workerToServiceEnv.
+ *
+ * ⚠️ SCOPE (0.1.30, after the R22→0.1.29 detour): this ONLY blocks keys that have a DEDICATED structured field
+ * or secretRef — so an operator is steered to that field instead of duplicating/shadowing it via env. It does
+ * NOT block the per-worker EXECUTION-SUBSTRATE config an operator legitimately sets via worker.env, which the
+ * live fleet relies on: `REMOTE_EXEC` (direct=k8s, canary=e2b set it HERE), `K8S_*` (SANDBOX_IMAGE/NAMESPACE/
+ * RUNTIME_CLASS/…), `E2B_*`, `MINIO_*`, `SSH_*`, `ADB_*`. worker.env is the OPERATOR's per-worker deployment env
+ * (publisher-gated, projected by the orchestrator to the worker pod) — NOT untrusted-task-controlled, so there
+ * is no "sandbox escape" to block here. R22 (codex) wrongly added those substrate keys treating worker.env as
+ * task-controlled; it would have REJECTED the live direct/canary workers on deploy. Reverted in 0.1.30. (Literal
+ * SECRET values pasted into env are still caught separately by containsSecretToken; substrate CREDS belong in
+ * secretEnv as env-NAME refs.)
+ */
+export const RESERVED_WORKER_ENV = new Set([
+    "PORT", "MODEL_PROVIDER", "MODEL_ID", "MODEL_REASONING", "MODEL_CHEAP_ID", "MODEL_MAX_TOKENS",
+    "MODEL_CONTEXT_WINDOW", "MODEL_COST_INPUT", "MODEL_COST_OUTPUT", "MODEL_COST_CACHE_READ",
+    "MODEL_COST_CACHE_WRITE", "MAX_PRINCIPAL_COST_USD", "SESSION_BACKEND", "MEMORY_BACKEND",
+    "REQUIRE_PRINCIPAL", "RATE_LIMIT_RPM", "DEFAULT_SCENARIO", "TIDB_DATABASE", "TIDB_HOST",
+    "TIDB_PORT", "TIDB_USER", "GIT_API_BASEURL", "MODEL_GATEWAY_BASEURL", "ANTHROPIC_BASEURL",
+    "MODEL_API_KEY", "ANTHROPIC_API_KEY", "SERVICE_AUTH_TOKEN", "GIT_API_TOKEN", "TIDB_PASSWORD",
+]);
+// Which structured WorkerSpec field owns each reserved env-NAME → so a rejection names the RIGHT field to use
+// (e.g. TIDB_DATABASE → runtime.db, MODEL_ID → model.modelId), not a vague "use the structured field".
+const RESERVED_ENV_FIELD = {
+    PORT: "(fixed at 8090 — not configurable)", MODEL_PROVIDER: "model.provider", MODEL_ID: "model.modelId",
+    MODEL_REASONING: "model.reasoning", MODEL_CHEAP_ID: "model.cheapId", MODEL_MAX_TOKENS: "model.maxTokens",
+    MODEL_CONTEXT_WINDOW: "model.contextWindow", MODEL_COST_INPUT: "model.cost.input", MODEL_COST_OUTPUT: "model.cost.output",
+    MODEL_COST_CACHE_READ: "model.cost.cacheRead", MODEL_COST_CACHE_WRITE: "model.cost.cacheWrite",
+    MAX_PRINCIPAL_COST_USD: "runtime.maxPrincipalCostUsd", SESSION_BACKEND: "runtime.sessionBackend",
+    MEMORY_BACKEND: "runtime.memoryBackend", REQUIRE_PRINCIPAL: "runtime.requirePrincipal", RATE_LIMIT_RPM: "runtime.rateLimitRpm",
+    DEFAULT_SCENARIO: "runtime.scenario", TIDB_DATABASE: "runtime.db", TIDB_HOST: "coords.tidbHost", TIDB_PORT: "coords.tidbPort",
+    TIDB_USER: "coords.tidbUser", GIT_API_BASEURL: "coords.gitApiBaseUrl", MODEL_GATEWAY_BASEURL: "model.gatewayBaseUrl",
+    ANTHROPIC_BASEURL: "model.gatewayBaseUrl", MODEL_API_KEY: "secretRefs.apiKeyEnv", ANTHROPIC_API_KEY: "secretRefs.apiKeyEnv",
+    SERVICE_AUTH_TOKEN: "secretRefs.serviceAuthTokenEnv", GIT_API_TOKEN: "secretRefs.gitTokenEnv",
+    TIDB_PASSWORD: "secretRefs.tidbPasswordEnv",
+};
+export const WorkerSpec = z.object({
+    /** 唯一 → 容器名 / compose project. */
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces"),
+    enabled: z.boolean().default(true),
+    /** 目标宿主机 id —— 哪个 per-host reconciler 认领它. 与 name 同样严格(精确匹配路由,松校验会静默不可达). */
+    host: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces").default("default"),
+    /** 容器镜像 (reconciler 按白名单强制). */
+    image: z.string().min(1).default("sema-server:latest"),
+    /**
+     * 对外路由前缀 (v2① 反代, design/25 决策7)。worker **不再 publish 宿主机端口**：反代 (Traefik) 按
+     * `routePrefix` 路由到容器内 8090。省略 → 用 `name` 作前缀。**唯一性由 WorkersConfig 提交时校验**。
+     * (废弃了原 `port` 字段 —— 宿主机端口是稀缺资源、规模化必撞车，且 hostPort 会被滥用绕过反代鉴权/限流/日志。)
+     */
+    routePrefix: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces").optional(),
+    /** Worker SCALE — number of pod replicas (k8s backend). Optional, absent → 1 (today's behaviour, no churn).
+     *  Hash-INCLUDED → a change re-applies the Deployment (k8s scales IN PLACE via SSA, no pod destruction). The
+     *  docker backend is single-container: it warns and runs 1 if this is >1. Capped at 100 (resource-exhaustion
+     *  guard — a typo'd 1e6 mustn't try to schedule a million pods; raise the cap if a real workload needs it). */
+    replicas: z.number().int().positive().max(100).optional(),
+    /** AUTOSCALING (k8s backend, HPA) — declare bounds and let the cluster's HorizontalPodAutoscaler own the
+     *  replica count (autoscaling/v2, CPU utilization; prove-before-scale 解禁 2026-06-13). Mutually exclusive
+     *  with `replicas` (WorkersConfig rejects both — two owners of the same knob WILL fight). The orchestrator
+     *  then OMITS spec.replicas from its SSA apply so it never wrestles the HPA controller; switching an
+     *  EXISTING fixed-replicas worker to autoscaling transiently resets it to 1 pod until the HPA raises it
+     *  to minReplicas (~15s) — enable during low traffic. CPU% needs resources.requests.cpu (backend default
+     *  50m applies if unset — set a realistic request or the percentage is meaningless). docker backend:
+     *  single-container, warns + ignores. Hash-INCLUDED; absent → no HPA, today's behaviour (zero churn). */
+    autoscaling: z
+        .object({
+        minReplicas: z.number().int().positive().max(100),
+        maxReplicas: z.number().int().positive().max(100),
+        /** Target average CPU utilization %, vs resources.requests.cpu. Absent → backend default 80. */
+        targetCpuPercent: z.number().int().min(10).max(95).optional(),
+    })
+        .refine((a) => a.maxReplicas >= a.minReplicas, { message: "maxReplicas must be >= minReplicas" })
+        .optional(),
+    /** Per-worker resource requests/limits (k8s backend). Optional → the backend's modest default
+     *  (requests cpu 50m/mem 128Mi, no limits). Hash-INCLUDED → a change rolls the pods (resources are
+     *  immutable on a running pod). CPU/memory are k8s quantity strings ("250m", "512Mi", "1", "2Gi"). */
+    resources: z
+        .object({
+        requests: z.object({ cpu: K8S_QUANTITY.optional(), memory: K8S_QUANTITY.optional() }).optional(),
+        limits: z.object({ cpu: K8S_QUANTITY.optional(), memory: K8S_QUANTITY.optional() }).optional(),
+    })
+        .optional(),
+    /** Scheduling-framework knobs (CONTROL-PLANE-SCHEDULING-DESIGN, clay 拍 D1/D3 2026-07-04). Optional and
+     *  hash-INCLUDED like every spec field — absent → contract defaults (zero churn on existing fleets). */
+    fleet: z
+        .object({
+        /** Per-worker dispatch policy consumed by center `/api/dispatch` (D3: the gateway hop is optional;
+         *  only affects traffic routed through it). Absent → contract defaults (round-robin, affinity on). */
+        dispatch: DispatchPolicy.optional(),
+        /** D1 per-worker drain-grace override → delivered to the container as env `DRAIN_GRACE_MS`
+         *  (worker-side default 600s, floor 10s). */
+        drainGraceMs: z.number().int().positive().optional(),
+    })
+        .optional(),
+    // `model` DELETED in 0.7.0 (EXPERT-REDESIGN §3 拍板 + E3 迁移闭环 — a2 存量 5 worker 已迁移目录+roster
+    // 标记,黑板 [551]/E3):模型/网关配置单一真源=models 目录,worker 经 `roster` 引用;主/cheap boot env
+    // 归宿=roster.primaryModel/cheapModel 标记(0.6.3,service [546]/[548]② 已承接)。pre-0.7 存量 JSON 里的
+    // `model` 键被 parse 静默剥除(zod strips unknown)→ workerSpecHash 变化=一次性重建;迁移工具输入=
+    // 冻结的 LegacyWorkerModel(migrate.ts),必须在升级 0.7 前跑完(a2 已闭环,E3 [551])。
+    /** 运行时 (非 secret). 映射到 service SESSION_BACKEND/REQUIRE_PRINCIPAL/RATE_LIMIT_RPM/… */
+    runtime: z.object({
+        // default "auto" (was "tidb" — Service AI's e2e-tag response traced the minimal-spec fatal here): the old
+        // default injected SESSION_BACKEND=tidb into EVERY spec that didn't set it, and the service fail-fasts on
+        // explicit tidb without TIDB_HOST (correct Tier-2 hardening — declared persistence must not silently
+        // degrade). "auto" = probe: with coords → tidb, without → memory, never fatal. A minimal `runtime:{}`
+        // worker now boots. No churn: previously-SAVED specs have "tidb" baked in (parseDomain persists defaults),
+        // so only NEW minimal specs see "auto"; explicit-"tidb" loud-fail semantics are untouched.
+        sessionBackend: z.enum(["tidb", "memory", "auto"]).default("auto"),
+        memoryBackend: z.enum(["off", "memory", "tidb"]).default("off"),
+        db: z.string().optional(), // TIDB_DATABASE (独立库)
+        scenario: z.string().optional(), // DEFAULT_SCENARIO
+        requirePrincipal: z.boolean().default(false),
+        rateLimitRpm: z.number().int().nonnegative().default(0),
+        /** Per-principal cumulative cost CAP (USD) → MAX_PRINCIPAL_COST_USD → the service's cost gate ENFORCEMENT
+         *  (over-cap → 429). Pairs with model.cost (which only ATTRIBUTES cost). ABSENT → no env → the service
+         *  defaults to 0 = off (today's behaviour); EXPLICIT 0 emits "0" = block-all and is HASH-DISTINCT from
+         *  absent (so the guard is `!= null`, not `> 0` — the two carry different caller intent). Optional + NO
+         *  default → absent never materialises → no spec-hash churn. Hash-included (read at boot → cap change recreates). */
+        maxPrincipalCostUsd: z.number().finite().nonnegative().optional(),
+    }),
+    /** 物理坐标 (非 secret). 映射到 GIT_API_BASEURL / TIDB_HOST 等. */
+    coords: z
+        .object({
+        gitApiBaseUrl: NON_SECRET_URL.optional().or(z.literal("")),
+        tidbHost: z.string().optional(),
+        tidbPort: TCP_PORT.optional(),
+        tidbUser: z.string().optional(),
+    })
+        .default({}),
+    secretRefs: WorkerSecretRefs,
+    /**
+     * 通用 env 透传（逃生口）——给**没有专属结构化字段**的 service env 用，让任意 worker 声明自己的 app 专属变量
+     * （如 OA 的 `OA_API_BASEURL`），不必为每个变量改契约。值是**字面非密值**（≤2048,且拒绝明显的密钥串——密钥走
+     * `secretEnv`）。**只能加结构化字段没产生的键**：`RESERVED_WORKER_ENV` 里的键(PORT、MODEL_x、gateway、auth、
+     * secret 名…)被拒,防 env 改路由/关鉴权/遮蔽密钥(council)。可覆盖非保留键(如 LOG_LEVEL)。hash-included(改它重建)。
+     */
+    env: z
+        .record(ENV_NAME, z.string().max(2048))
+        .superRefine((rec, ctx) => {
+        for (const [k, v] of Object.entries(rec)) {
+            if (RESERVED_WORKER_ENV.has(k))
+                ctx.addIssue({ code: "custom", message: `env cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k] ?? "the structured field"}` });
+            // 0.1.32: NO name exemption — a PUBLIC key is allowed because SECRET_LITERAL_RE now only flags PRIVATE keys
+            // (root fix), so a literal private key / token in env (ANY name, incl `*_PUBKEY`) is still rejected.
+            if (containsSecretToken(v))
+                ctx.addIssue({ code: "custom", message: `env["${k}"] looks like a literal secret — put secrets in secretEnv (an env-NAME), never a value in env` }); // tokenized (mid-string too). R8
+        }
+    })
+        .optional(),
+    /**
+     * 通用**密钥** env 透传：`{ service 的环境变量名 → 宿主机 env-NAME }`。编排器把宿主机 env-NAME 从它的 secret 源
+     * 解析成真值、经 secretKeyRef 注入——**sema-registry 只存名、绝不存值**（同 `secretRefs` 边界，值也是 `ENV_NAME`
+     * 故无法粘贴真值）。给 app 专属令牌用（如 `OA_SERVICE_TOKEN` → 某 env-名）。在 reconciler 里于 `env` 之后解析，
+     * 故密钥永不被 `env` 同名键遮蔽。`RESERVED_WORKER_ENV` 里的键被拒（那些结构化 secret 走 `secretRefs`）。
+     */
+    secretEnv: z
+        .record(ENV_NAME, ENV_NAME)
+        .superRefine((rec, ctx) => {
+        for (const k of Object.keys(rec))
+            if (RESERVED_WORKER_ENV.has(k))
+                ctx.addIssue({ code: "custom", message: `secretEnv cannot set reserved key "${k}" — set it via ${RESERVED_ENV_FIELD[k] ?? "secretRefs"}` });
+    })
+        .optional(),
+    /** Opaque recreate trigger (hash-INCLUDED): bump it to force the reconciler to recreate the worker — e.g. to
+     *  re-project a secret VALUE that changed (a secret write doesn't alter the spec, so without this the running
+     *  pod keeps the old value). Set by POST /api/config/workers/<name>/rotate. */
+    recreateNonce: z.string().max(64).optional(),
+    /**
+     * 生命周期 (v2②, design/25 §3)。可选——不填 = `persistent`（默认安全，绝不被 GC 误杀）。
+     * **reconciler 不读这个字段**（保持纯收敛）；TTL/idle 决策全在 sema-registry 侧 sweeper：到期就把 worker
+     * 从 desired 移除，reconciler 声明式自然 teardown。`ttl`/`idleTimeout` 用时长串（"30m"/"2h"/"7d"）。
+     */
+    lifecycle: WorkerLifecycle.optional(),
+    /**
+     * 多主机调度 (可选, 非 breaking — reconciler 不读)。`auto:true` → sema-registry 的 placement 按容量/标签约束
+     * 给它挑一台 host 并写回具体 `host`（reconciler 仍按具体 host 认领，契约不变）。`requires` = host 必须具备的
+     * 全部标签（hosts 域声明）。不填 = 手动指定 host（运维自己负责）。
+     */
+    placement: z
+        .object({
+        auto: z.boolean().default(false),
+        requires: z.array(z.string().min(1)).default([]),
+        /** SOFT anti-affinity group: auto workers sharing this key are spread across hosts when possible
+         *  (preferred, never blocks placement — design SCHEDULING.md). 不填 = 无 spread 约束。 */
+        spread: z.string().min(1).optional(),
+    })
+        .optional(),
+    /**
+     * per-worker roster 引用 (docs/MULTI-ROSTER.md)。指向 `rosters` 域里一个命名 roster；该 worker 的 service 拉
+     * `GET /api/config/effective?worker=<name>` 时,sema-registry 用这个 roster 解析它专属的 models/roles/@白名单。
+     * 不填 → 该 worker 拿全局 models（向后兼容）。**不进 `workerSpecHash`**（改 roster 只让 service 重拉、不重建容器）。
+     */
+    roster: z.string().min(1).optional(),
+    /** 预留 spec 签名钩子 (MVP 不验; reconciler 侧可加验签 — design/22 决策③). */
+    signature: z.string().optional(),
+    notes: z.string().optional(),
+});
+/** Effective route key for a worker = explicit routePrefix, else its name. */
+export function workerRouteKey(w) {
+    return w.routePrefix ?? w.name;
+}
+/** S/M/L 资源套餐常量(EXPERT-REDESIGN §3 四问③,E1 定档)——workers 向导的规格套餐与 E2 placement 的
+ *  默认折算**同源引用这一份**(worker 无 requests 时按 S 折算,§2-4)。值为 k8s quantity 串,直接落
+ *  `WorkerSpec.resources`;「自定义」= 不用套餐、直接写 resources。定档口径:S=轻量单副本(默认档,略高于
+ *  backend 兜底 50m/128Mi 的真实工作水位);M=常规编码 agent;L=重载(大 repo/多并发 turn)。 */
+export const WORKER_RESOURCE_PRESETS = {
+    S: { requests: { cpu: "250m", memory: "512Mi" }, limits: { cpu: "1", memory: "1Gi" } },
+    M: { requests: { cpu: "500m", memory: "1Gi" }, limits: { cpu: "2", memory: "2Gi" } },
+    L: { requests: { cpu: "1", memory: "2Gi" }, limits: { cpu: "4", memory: "4Gi" } },
+};
+export const WorkersConfig = z
+    .object({ workers: z.array(WorkerSpec).default([]) })
+    .superRefine((cfg, ctx) => {
+    // worker `name` and effective routePrefix must each be unique across the fleet (design/25 决策7:
+    // routePrefix 唯一性 sema-registry 提交时校验). Dup name → container-name clash; dup route → ambiguous
+    // reverse-proxy routing.
+    const names = new Set();
+    const routes = new Set();
+    cfg.workers.forEach((w, i) => {
+        if (names.has(w.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate worker name "${w.name}"`, path: ["workers", i, "name"] });
+        names.add(w.name);
+        const route = workerRouteKey(w);
+        // point the error at the field that actually set the route (explicit routePrefix, else the name fallback).
+        const routeField = w.routePrefix !== undefined ? "routePrefix" : "name";
+        if (routes.has(route))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate routePrefix "${route}" (collides with another worker's routePrefix/name)`, path: ["workers", i, routeField] });
+        routes.add(route);
+        // replicas + autoscaling = two owners of the same knob (the orchestrator's SSA vs the HPA controller
+        // would endlessly fight over spec.replicas) → reject at save, not at reconcile.
+        if (w.replicas !== undefined && w.autoscaling) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "replicas and autoscaling are mutually exclusive — the HPA owns the replica count when autoscaling is set", path: ["workers", i, "autoscaling"] });
+        }
+    });
+});
+// Worker STATUS — reconciler 回写的 ACTUAL state. NOT an admin domain: spec(admin 写) 与 status(reconciler
+// 写) 分离更新、各自乐观锁，避免 reconciler 覆盖刚改的 spec (design/22 决策⑤). 存在 worker_status 表/单独 API.
+export const WorkerCondition = z.object({
+    type: z.enum(["Reconciled", "Healthy", "Conflicted"]),
+    status: z.enum(["True", "False", "Unknown"]),
+    reason: z.string().optional(), // e.g. "HostUnreachable" | "InsufficientResources" | "ImagePullFailed"
+    message: z.string().optional(),
+    lastTransitionTime: z.string(),
+});
+export const WorkerStatus = z.object({
+    name: z.string().min(1),
+    host: z.string().min(1), // 哪个 reconciler 上报的
+    phase: z.enum(["Pending", "Running", "Failed", "Unknown"]),
+    conditions: z.array(WorkerCondition).default([]),
+    /** reconciler 处理时的 effective `version` — admin 改 spec 后 version 变,据此判断 status 是否陈旧. */
+    observedVersion: z.number().int().nonnegative(),
+    /** reconciler 算的逻辑 spec hash (漂移检测 + 防振荡, design/22 失败模式#1). */
+    observedSpecHash: z.string().optional(),
+    message: z.string().optional(),
+    updatedAt: z.string(),
+});
+// ── Hosts registry (机器 — 自注册+待批, EXPERT-REDESIGN §2) ───────────────────────
+// 声明 fleet 里有哪些 host + 标签/drain/批准状态。host `name` 对应 reconciler 的 ORCH_HOST_ID 与
+// WorkerSpec.host（同字符集）。0.6.0 改形（拍板:capacity 手填票数废除,机器自注册+默认待批）:
+//   - `capacity` DELETED —— 可放性改由探测值折算(HostStatus.probes − Σ已排 worker requests;计数制→资源制
+//     是探测数据齐备后的**独立开关**,E2 placement 承接,切换前沿用计数制兜底、不按票数)。
+//   - `approved` NEW —— 默认 false = 待批(不参与自动排布;enforcement 随 E2 placement 生效,E1 只落契约)。
+//     存量迁移 = grandfathering 批量回填 approved:true(migrate.ts),存量机器不出现排布空窗(§11-9)。
+/** DNS-label bound on a host NAME (0.8.0 tightening; single source — schema + the 0.8.1 read-path
+ *  grandfather clamp in config-fns both use it, so the two can never drift). */
+export const HOST_NAME_MAX = 63;
+/** Ceiling on the hosts ARRAY (0.8.0 tightening; same single-source rule as {@link HOST_NAME_MAX}). */
+export const HOSTS_ARRAY_MAX = 1024;
+export const HostEntry = z.object({
+    // .max(HOST_NAME_MAX=63) = DNS-label bound (E2 F3③ 挂账收账, 0.8.0): center-side probe clamp stays as双保险.
+    name: z.string().min(1).max(HOST_NAME_MAX).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces"),
+    /** 待批准入编状态机(§2-3):自注册/新登记默认 false = 待批,不参与自动排布;admin 批准(走 publish)→
+     *  true 参排(enforcement 随 E2)。既有 worker 不受影响(reconciler 仍按具体 host 认领)。 */
+    approved: z.boolean().default(false),
+    /** 调度标签（如 "gpu"/"region-us"），worker 的 `placement.requires` 据此匹配。 */
+    labels: z.array(z.string().min(1)).default([]),
+    /** 关闭 = 完全不可调度（既有 worker 仍由 reconciler 管，但 placement 视它不可用）。 */
+    enabled: z.boolean().default(true),
+    /** drain = 不再往这台**新**放 worker（既有的留着），用于下线前腾空。 */
+    drain: z.boolean().default(false),
+    notes: z.string().optional(),
+});
+export const HostsConfig = z
+    // .max(HOSTS_ARRAY_MAX=1024) hosts (E2 F3③ 挂账收账, 0.8.0) — a fleet registry, not a datacenter inventory;
+    // an absurdly long array is a poisoned publish, fail-loud at save time. READ path: 0.7-era stored data that
+    // exceeds these 0.8 bounds is GRANDFATHERED (clamped + warned, never thrown) inside buildEffective —
+    // see grandfatherHostsRead in config-fns (0.8.1, S3 M-1: 收紧不毁存量,E2 血训).
+    .object({ hosts: z.array(HostEntry).max(HOSTS_ARRAY_MAX).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.hosts.forEach((h, i) => {
+        if (seen.has(h.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate host "${h.name}"`, path: ["hosts", i, "name"] });
+        seen.add(h.name);
+    });
+});
+// Host STATUS — orchestrator 周期(60s)`PUT /api/config/hosts/status` 自报的探测值(与 workers/status 同款
+// token+CAS 姿势,同 WorkerStatus 先例:spec/admin 写 与 status/orchestrator 写 分离)。**探测值只进状态侧表
+// (fleet_host_status),不进配置域**(意图与实态分离);未知 host 名上报 → server 在 hosts 域登记待批条目
+// (仅身份字段 {name, approved:false},幂等一条,来源 token 记审计——EXPERT-REDESIGN §2-1/§11-4)。E2
+// placement 的资源制折算消费它(可分配 = probes − Σ已排 worker requests);从未上报的机器不参与自动排布。
+// Sanity ceilings (E2 F3③ 挂账收账, 0.8.0): a forged/absurd probe (cpuCores=1e12) would suck every auto
+// worker onto one host. Ceilings MIRROR center's probeCapacities clamp (PROBE_CPU_CORES_CEILING=4096 /
+// PROBE_MEM_BYTES_CEILING=2^50=1PiB) — schema now fail-louds at report time; center's clamp stays 双保险.
+export const PROBE_CPU_CORES_MAX = 4096;
+export const PROBE_MEM_BYTES_MAX = 2 ** 50; // 1 PiB
+export const HostProbes = z.object({
+    /** 探测到的 CPU 核数(docker info NCPU / k8s node allocatable cpu)。可为小数(k8s allocatable 如 3.9)。 */
+    cpuCores: z.number().finite().positive().max(PROBE_CPU_CORES_MAX),
+    /** 探测到的内存字节数(docker info MemTotal / k8s node allocatable memory)。 */
+    memBytes: z.number().int().positive().max(PROBE_MEM_BYTES_MAX),
+    /** 当前跑着的容器数(docker info ContainersRunning / k8s node 上本 fleet 的 pod 数)。 */
+    containersRunning: z.number().int().nonnegative(),
+    /** k8s backend 补充:node 名 + allocatable(与顶层同单位——cpuCores 核数 / memBytes 字节)。docker 无此段。 */
+    k8sNode: z
+        .object({
+        name: z.string().min(1),
+        allocatable: z.object({ cpuCores: z.number().finite().positive().max(PROBE_CPU_CORES_MAX).optional(), memBytes: z.number().int().positive().max(PROBE_MEM_BYTES_MAX).optional() }).optional(),
+    })
+        .optional(),
+});
+export const HostStatus = z.object({
+    /** host name(hosts 域 HostEntry.name / ORCH_HOST_ID 同字符集,同 .max(HOST_NAME_MAX=63) DNS-label bound)。
+     *  status 上报是 WRITE 路径 → fail-loud 保持(有意设计,S3 M-1 订正注记:center hosts/status PUT 无独立
+     *  probe 上限,schema 即闸;读路径 grandfather 只涉 config-hosts 域,不涉此处)。 */
+    host: z.string().min(1).max(HOST_NAME_MAX).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters/digits/-, no spaces"),
+    backend: z.enum(["docker", "k8s"]),
+    probes: HostProbes,
+    /** 探测时刻(ISO)——机器视图 hover 注明数据口径与此时间(§2-5:是分配额口径的底数,非实时负载)。 */
+    ts: z.string().min(1),
+});
+// ── Domain: skills (中心化 skill 分发 — docs/MCP-SKILLS.md, Roadmap B1) ─────────
+// A skill is a prompt-level capability: frontmatter (name/description/scenarios) + markdown `content`
+// the service feeds into the agent's model context when the skill is invoked (core progressive disclosure
+// — NOT the base system prompt). Still centrally-delivered agent instructions. The center stores the FULL skill
+// (incl. content, admin-edited); /effective ships a MANIFEST (content → contentHash) and the service
+// lazily pulls the body by hash (slice 2). Targeting is by `scenarios[]`, filtered service-side exactly
+// like the in-image `skillsForScenario` (MCP-SKILLS.md §3.1, §6 Q2). Applied at service boot/reconcile,
+// NOT hot (restart-to-apply, same as models/roles). ⚠️ content is centrally-delivered agent instructions
+// (injected into the model on invoke) → writing this domain is gated to `publisher` + the publish gate
+// (§3.3, DOMAIN_WRITE_ROLE in store.ts).
+export const SkillSpec = z.object({
+    /** Catalog key — must match the in-image SKILLS_DIR name to OVERRIDE it (§6 Q4 中心按名覆盖). */
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    /** One-line summary (frontmatter `description`) — surfaced to the model for skill selection. */
+    description: z.string().default(""),
+    /** Scenarios this skill applies to; empty = all scenarios (service-side filter, same as skillsForScenario). */
+    scenarios: z.array(z.string().min(1)).default([]),
+    /** Per-roster targeting (v2, docs/MCP-SKILLS.md §6 Q2): roster NAMEs this skill is for. Empty = all rosters.
+     *  Filtered at GET /effective?worker=<name> by the worker's roster; the unscoped global pull ships all. */
+    rosters: z.array(z.string().min(1)).default([]),
+    /** The markdown body injected into the model context on invoke (progressive disclosure). Stored in full here; shipped as a hash in /effective. */
+    content: z.string().default(""),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+});
+export const SkillsConfig = z
+    .object({ skills: z.array(SkillSpec).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.skills.forEach((s, i) => {
+        if (seen.has(s.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate skill "${s.name}"`, path: ["skills", i, "name"] });
+        seen.add(s.name);
+    });
+});
+// ── Domain: mcp (MCP server 注册表 — docs/MCP-SKILLS.md, Roadmap B1) ────────────
+// sema-registry = an MCP-server REGISTRY: a scenario mounts a subset by `scenarios[]`. Maps onto core's
+// `McpServerSpec = { name, transport: {kind:"stdio",command,args?,env?} | {kind:"http",url,headers?}, allowTools? }`.
+// SECRET BOUNDARY (§3.1, design/15): a transport's env/header VALUES may be secret → the center stores only
+// env-NAME references (`envRefs`/`headerRefs`: target-key → an ENV_NAME in the SERVICE's env). The service's
+// `resolveSpec` reads the real values from its own environment — this DB never holds a credential. Like
+// skills, MCP is applied at boot/reconcile (not hot) and writing is gated to `publisher` + the publish gate.
+const McpEnvRefs = z.record(ENV_NAME, ENV_NAME); // target ENV key → ENV_NAME holding its value (both env-name-shaped)
+// An HTTP header NAME: an RFC 7230 token that ALSO must not be a secret literal. A secret-SHAPED header name
+// (a headerRefs key `sk-live-…`, or principalHeader `ghp_…`) is stored + shipped verbatim on /effective — the
+// SAME invariant-① gap as worker.env / model.extraBody / mcp stdio command+args (credentials belong on the
+// VALUE side = an env-NAME ref, never the name). The token charset includes `%`, so an encoded secret could ride
+// the name — containsSecretToken percent-decodes, catching it too. ONE shared schema for both header-name fields. R19 (codex).
+const HTTP_HEADER_NAME = z
+    .string()
+    .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, "must be an HTTP header NAME")
+    .refine((s) => !containsSecretToken(s), "HTTP header name must not contain a secret literal — credentials go in the env-NAME value, never the header name");
+// Header NAME → ENV_NAME holding its value. Header names are tokens (RFC 7230) — not env-name-shaped.
+const McpHeaderRefs = z.record(HTTP_HEADER_NAME, ENV_NAME);
+export const McpTransport = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("stdio"),
+        // command + args are free-form values shipped verbatim on /effective. Like worker.env values + model
+        // extraBody (the sibling free-form fields), reject a secret-shaped literal — an admin pasting
+        // `args:["--api-key","sk-…"]` would otherwise store the VALUE + ship it (invariant ① gap). Credentials go in
+        // envRefs (env-NAME). FIELD-level refine (not a member superRefine) to preserve the discriminatedUnion. R6 (codex).
+        command: z
+            .string()
+            .min(1)
+            .refine((s) => !containsSecretToken(s), "mcp stdio command must not contain a secret literal — put credentials in envRefs (an env-NAME)")
+            .refine((s) => !hasNul(s), "mcp stdio command must not contain a NUL byte (Node cannot spawn it)"),
+        args: z
+            .array(z
+            .string()
+            .refine((s) => !containsSecretToken(s), "mcp stdio arg must not contain a secret literal — put credentials in envRefs (an env-NAME)")
+            .refine((s) => !hasNul(s), "mcp stdio arg must not contain a NUL byte (Node cannot spawn it)"))
+            .optional(),
+        /** target ENV key → ENV_NAME in the service env (never a secret value). */
+        envRefs: McpEnvRefs.optional(),
+    }),
+    z.object({
+        kind: z.literal("http"),
+        url: NON_SECRET_URL,
+        /** header NAME → ENV_NAME in the service env (e.g. Authorization → SEARCH_TOKEN_ENV). */
+        headerRefs: McpHeaderRefs.optional(),
+        /** Header NAME the SERVICE fills with the END-USER principal when proxying a tool call to this server, so the
+         *  server can do per-user RBAC (e.g. "x-agent-principal"). Distinct from headerRefs (static secret headers):
+         *  this is dynamic — the caller's principal, set per-request by the worker — so it's a header NAME, not an
+         *  env-NAME ref (no secret). Empty → the worker forwards no principal (server sees an anonymous call). */
+        principalHeader: HTTP_HEADER_NAME.optional(),
+    }),
+]);
+export const McpServerSpec = z.object({
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    transport: McpTransport,
+    /** Allowlist of tool names exposed from this server (core `allowTools`). Empty/undefined = all. */
+    allowTools: z.array(z.string().min(1)).optional(),
+    /** Scenarios this server is mounted in; empty = all (service-side filter, same as skills). */
+    scenarios: z.array(z.string().min(1)).default([]),
+    /** Per-roster targeting (v2): roster NAMEs this server is for. Empty = all rosters. Filtered at
+     *  GET /effective?worker=<name> by the worker's roster; the unscoped global pull ships all. */
+    rosters: z.array(z.string().min(1)).default([]),
+    enabled: z.boolean().default(true),
+    /** Per-server opt-in for INBOUND MCP elicitation (core `McpServerSpec.elicitation`, design/99 §E23). Default
+     *  OFF = fail-closed: only an opted-in server may prompt the user mid-tool-call. Service forwards this into the
+     *  core spec (was read untyped as `(s as {elicitation?})` before this field — service [253] ask). */
+    elicitation: z.boolean().default(false),
+    notes: z.string().optional(),
+});
+export const McpConfig = z
+    .object({ servers: z.array(McpServerSpec).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.servers.forEach((s, i) => {
+        if (seen.has(s.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate mcp server "${s.name}"`, path: ["servers", i, "name"] });
+        seen.add(s.name);
+    });
+});
+// ── Domain: plugins (plugin SOURCE REFERENCES — C2 plugins 上云, additive 0.5.0) ──────────────────────────
+// The cloud stores WHERE a plugin comes from, NEVER its content (clay 拍): {name, source, version/sha pin}.
+// The consuming shell materializes the plugin locally from the ref (git clone / marketplace install) — the
+// registry never hosts executable plugin bytes, so there is nothing here to content-scan or lazily serve.
+// Plugins are an EXECUTABLE surface (commands/hooks/MCP ride in) → write-gated to `publisher` like skills/
+// mcp (DOMAIN_WRITE_ROLE) and capped per-principal by entitlement `visiblePlugins` (deny-wins, same
+// mechanics as visibleMcp/visibleSkills — B1: a personal plugin ref is a net-new capability).
+/** A plugin/marketplace ORIGIN string: a git URL (http(s)/ssh/scp-style) or a forge `owner/repo` shorthand.
+ *  Deliberately permissive on FORM (git accepts many), strict on SECRETS: no secret-shaped literal, no NUL,
+ *  and an http(s) origin must not carry userinfo credentials or a secret-bearing query/fragment (same
+ *  invariant-① posture as NON_SECRET_URL — credentials never ride a stored origin; private remotes
+ *  authenticate via each machine's own git credential helper). */
+export const PLUGIN_ORIGIN = z
+    .string()
+    .min(1)
+    .refine((s) => !containsSecretToken(s), "plugin source must not contain a secret literal — private remotes authenticate via the consuming machine's git credentials, never an inline token")
+    .refine((s) => !hasNul(s), "plugin source must not contain a NUL byte")
+    .refine((s) => {
+    if (!/^https?:\/\//i.test(s))
+        return true; // ssh/scp-style/owner-repo shorthand: no URL userinfo to check
+    try {
+        const u = new URL(s);
+        return !u.username && !u.password && !urlQueryFragmentHasSecret(u);
+    }
+    catch {
+        return false; // claims to be http(s) but does not parse → reject
+    }
+}, "an http(s) plugin source must not embed credentials (userinfo) or a secret-bearing query/fragment");
+/** A full 40-hex git commit SHA — the ONLY pin form the supply-side treats as 钉死 (a branch/tag `version`
+ *  is a moving ref; only a commit pin makes the materialized bytes reproducible). */
+export const GIT_COMMIT_SHA = z.string().regex(/^[a-f0-9]{40}$/, "must be a full 40-character lowercase git commit SHA");
+/** WHERE a plugin comes from — two forms (clay 拍: git URL 与 marketplace ref 两形态):
+ *  - `git`: the plugin lives at a git URL directly (repo root = plugin root).
+ *  - `marketplace`: the plugin is `<name>@<marketplace>` in a plugin marketplace; `marketplace` is the
+ *    marketplace NAME and `url` its own origin (so a machine that never registered it can: add the
+ *    marketplace by url, then install by name). `url` absent = the consumer must already know the
+ *    marketplace (works inside a fleet with pre-seeded marketplaces; a dangling name installs nothing). */
+export const PluginSource = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("git"), url: PLUGIN_ORIGIN }),
+    z.object({
+        kind: z.literal("marketplace"),
+        marketplace: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+        url: PLUGIN_ORIGIN.optional(),
+    }),
+]);
+export const PluginSpec = z.object({
+    /** Plugin name (the `<name>` half of a `<name>@<marketplace>` id; the whole id for a direct git plugin). */
+    name: z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, "letters/digits/._- , no spaces"),
+    source: PluginSource,
+    /** Human version label (semver/tag). A moving ref — NOT a pin; pin with `sha`. */
+    version: z.string().optional(),
+    /** Git commit pin (independent of `version`, clay 拍): present ⇒ the ref is 钉死 — consumers materialize
+     *  exactly this commit; absent ⇒ the consumer tracks the source's default/`version` ref. */
+    sha: GIT_COMMIT_SHA.optional(),
+    enabled: z.boolean().default(true),
+    notes: z.string().optional(),
+});
+export const PluginsConfig = z
+    .object({ plugins: z.array(PluginSpec).default([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.plugins.forEach((p, i) => {
+        if (seen.has(p.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate plugin "${p.name}"`, path: ["plugins", i, "name"] });
+        seen.add(p.name);
+    });
+});
+// ── The domain registry ───────────────────────────────────────────────────────
+export const DOMAIN_SCHEMAS = {
+    models: ModelsConfig,
+    rosters: RostersConfig,
+    skills: SkillsConfig,
+    mcp: McpConfig,
+    plugins: PluginsConfig,
+    scenarios: ScenarioConfig,
+    systems: SystemsConfig,
+    collab: CollabConfig, // 0.7.0: replaces `teams` (EXPERT-REDESIGN §8/§9 同批换刀 — no editing gap)
+    workers: WorkersConfig,
+    hosts: HostsConfig,
+    runtime: RuntimeConfig,
+    governance: GovernanceConfig,
+    entitlement: EntitlementConfig,
+    execution: ExecutionPolicy, // 0.8.0: S3 execution-lane policy (scope 级; client-advisory until service gate [580])
+    projects: ProjectsConfig, // 0.10.0: 142-S3 project identity ledger + 无仓铸造权威 (scope=tenant 轴; NOT portable — 租户身份数据)
+    // integrations + access: DELETED in 0.6.0 (EXPERT-REDESIGN §9) — parseDomain/effective/路由随之 404。
+};
+// ── Effective-config PROVENANCE (the unified shape TOC `sema config --effective` and TOB `/effective?principal=`
+//    step-5 trace both emit, so "why is this value what it is" renders identically across both seats). Settled
+//    via the center control-plane design gate③ (docs/design/CENTER-CONTROL-PLANE-DESIGN.md §R2-T/§10). A pure
+//    CONTRACT type — no runtime dep on the engine; the axis VALUES (enforcement/lockBehavior) mirror @sema-ai/
+//    core's safety vocabulary, validated by a dev-only conformance test (never a runtime import).
+/** One provenance source in a key's resolution trail. Two orthogonal axes: the TOC file LAYER, or the TOB
+ *  PRINCIPAL dimension. `applied:false` + `reason` mark a source whose attempt was REJECTED by the monotone
+ *  tighten-only law (e.g. a layer trying to LOOSEN a principal floor → `reason:"trust-rejected"`). */
+export const SettingSource = z.discriminatedUnion("axis", [
+    z.object({ axis: z.literal("layer"), layer: z.enum(["MANAGED", "PROJECT", "LOCAL"]), applied: z.boolean().optional(), reason: z.string().optional() }),
+    z.object({ axis: z.literal("principal"), via: z.enum(["tier", "role", "override", "worker-base"]), id: z.string(), applied: z.boolean().optional(), reason: z.string().optional() }),
+]);
+/** The resolved provenance of ONE setting/config key. `winningSource` = the source that won; `sources[]` = the
+ *  full trail (a hybrid deploy carries both a principal floor and a layer tightening). `enforcement` (STRENGTH /
+ *  where enforced) drives fail-mode — fail-OPEN iff `client && !secret`; `gate`/`server`/secret → fail-CLOSED.
+ *  STRENGTH tiers: `gate`=data-plane engine (core tool-policy/exec-gate/sandbox/per-RUN budget); `server`=
+ *  control-plane/TOB boundary (service createAuthorizer / entitlement / per-period budget / SSO/SCIM/audit/org —
+ *  the verify-and-constrain point BEFORE the data plane, ⊥ gate); `resolver`=merger correctness; `client`=UI only.
+ *  `lockBehavior` (BEHAVIOR / what the managed layer does) is orthogonal, only meaningful under managed enforcement. */
+export const EffectiveKey = z.object({
+    key: z.string(),
+    value: z.unknown(),
+    winningSource: SettingSource,
+    locked: z.boolean(),
+    enforcement: z.enum(["gate", "server", "resolver", "client"]),
+    lockBehavior: z.enum(["locked", "advisory", "forced-off", "tighten-only"]).optional(),
+    sources: z.array(SettingSource).optional(),
+});
+/** Reserved audit "domain" for RBAC/user-management events (not a config domain → no snapshot, not
+ *  rollback-able). Lets user changes share the one audit stream the Audit page already renders. */
+export const RBAC_AUDIT = "rbac";
+/** Audit category for secret write-through (value injected into the orchestrator secret source) — name + action
+ *  ONLY, never the value (config_change.value=null), same discipline as RBAC_AUDIT. docs/SELF-SERVICE-FLEET.md §3. */
+export const SECRETS_AUDIT = "secrets";
+// Single source: derived from DOMAIN_SCHEMAS (insertion order = menu order) so the two can't drift —
+// adding a domain to DOMAIN_SCHEMAS is enough. Object.keys preserves declaration order.
+export const DOMAINS = Object.keys(DOMAIN_SCHEMAS);
+/** The canonical "is this a config domain?" predicate. Use it instead of hard-coding a domain list when
+ *  filtering arbitrary keys (e.g. a `config.d/` directory scan that also turns up the non-domain
+ *  `remote-exec.json`) — `remote-exec` is NOT a domain (it's the exec backend; see writeRemoteExec). */
+export function isDomainName(x) {
+    return typeof x === "string" && Object.prototype.hasOwnProperty.call(DOMAIN_SCHEMAS, x);
+}
+//# sourceMappingURL=types.js.map