@sema-agent/settings-schema 1.0.0

package/dist/api/wire.js

@@ -0,0 +1,89 @@
+/**
+ * `api/wire` — the ZERO-DEPENDENCY wire subset of the auth/scopes contracts (server AI 接手首车,
+ * 2026-07-27,跨仓 candidate 落地):endpoint paths, protocol constants and PURE helper functions,
+ * with **no zod import** — so a zero-runtime-dependency client (e.g. `@sema-agent/sdk/registry`) can
+ * import these at RUNTIME instead of value-copying them behind a same-source anchor test.
+ *
+ * ⚠️ 拆分纪律:这里只放**纯**件(常量/纯函数/字面量类型)。zod schema 留在 `api/auth.ts` /
+ * `api/scopes.ts`(它们 re-export 本文件 ⇒ 既有导入面字节兼容,谁都不用改)。给本文件加东西前
+ * 自问:它 import 了任何东西吗?——答案必须是 no(test/wire-purity 打包门盯着)。
+ */
+// ── auth: endpoint paths + protocol constants(api/auth.ts 原件,shipped values 冻结)─────────────────
+/** The five auth endpoints, relative to the registry origin. */
+export const AUTH_V1_PATHS = {
+    deviceCode: "/api/v1/auth/device/code",
+    deviceToken: "/api/v1/auth/device/token",
+    deviceApprove: "/api/v1/auth/device/approve",
+    tokenRefresh: "/api/v1/auth/token/refresh",
+    logout: "/api/v1/auth/logout",
+};
+/** The RFC 8628 grant_type the device token endpoint requires. */
+export const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Minimum seconds between token-endpoint polls (RFC 8628 `interval`); polling faster → `slow_down`. */
+export const DEVICE_POLL_INTERVAL_SECONDS = 5;
+/** Device-code handshake lifetime (seconds) — the user has 15 minutes to open /activate and approve. */
+export const DEVICE_CODE_TTL_SECONDS = 15 * 60;
+/** Access-token (RS256 JWT) lifetime in seconds — 1h, re-minted via refresh. */
+export const ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
+/** Refresh-grant lifetime (seconds) — 30d SLIDING: every rotation opens a fresh 30d window. */
+export const REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** Every error code the /api/v1/auth/* endpoints answer (HTTP 400 unless noted). */
+export const OAUTH_ERROR_CODES = [
+    /** device/token: the user has not approved (or denied) the handshake yet — keep polling. */
+    "authorization_pending",
+    /** device/token: polling faster than `interval` — RFC 8628 §3.5: ADD 5 seconds to the interval. */
+    "slow_down",
+    /** device/token: handshake expired, unknown, or already exchanged — restart the flow.
+     *  (Deliberately covers "never existed": the server does not disclose handshake existence.) */
+    "expired_token",
+    /** device/token: the user explicitly denied the handshake — stop polling, do not restart silently. */
+    "access_denied",
+    /** any endpoint: malformed body / missing required field / wrong content type. */
+    "invalid_request",
+    /** device/token: grant_type is not DEVICE_GRANT_TYPE. */
+    "unsupported_grant_type",
+    /** token/refresh + device/approve: unknown / expired / revoked / replayed token or code — no detail. */
+    "invalid_grant",
+    /** SSO not configured on the registry (HTTP 503) — a deployment problem, not a client one. */
+    "server_error",
+];
+/** Handshake states a consent-screen lookup can see. (`approved` rows vanish once exchanged/consumed.)
+ *  `denied` is contract-reserved for an explicit deny button (pairs with the `access_denied` poll error);
+ *  the shipped M1 store carries pending|approved only — adding deny later is implementation, not schema. */
+export const DEVICE_AUTH_STATUSES = ["pending", "approved", "denied"];
+// ── auth: pure client-side helpers(api/auth.ts 原件)────────────────────────────────────────────────────
+/**
+ * Canonicalize a human-typed user code to the wire shape "XXXX-XXXX": uppercase, dashes/spaces optional.
+ * null = not a plausible code (wrong length/charset after stripping separators). Same normalization the
+ * server applies — run it client-side for instant feedback.
+ */
+export function normalizeUserCode(input) {
+    if (typeof input !== "string")
+        return null;
+    const raw = input.toUpperCase().replace(/[\s-]/g, "");
+    if (!/^[A-Z0-9]{8}$/.test(raw))
+        return null;
+    return `${raw.slice(0, 4)}-${raw.slice(4)}`;
+}
+/**
+ * The RFC 8628 §3.5 poll-loop step: what interval to poll with next, and whether to keep going.
+ * - authorization_pending → keep polling at the current interval
+ * - slow_down             → keep polling, interval + 5s (the RFC-mandated increment)
+ * - anything else         → stop (expired_token/access_denied = terminal; invalid_* = client bug)
+ */
+export function nextPollInterval(currentIntervalSeconds, error) {
+    if (error === "authorization_pending")
+        return { continue: true, intervalSeconds: currentIntervalSeconds };
+    if (error === "slow_down")
+        return { continue: true, intervalSeconds: currentIntervalSeconds + 5 };
+    return { continue: false, intervalSeconds: currentIntervalSeconds };
+}
+// ── scopes: endpoint paths + claim(api/scopes.ts 原件)─────────────────────────────────────────────────
+export const SCOPES_V1_PATHS = {
+    /** GET (list) + POST (create). */
+    scopes: "/api/v1/scopes",
+    /** POST — mint a new access token bound to another scope. */
+    authScope: "/api/v1/auth/scope",
+};
+/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+export const SCOPE_CLAIM = "scope";

package/dist/bundle.d.ts

@@ -0,0 +1,13 @@
+import type { ConfigReader } from "./reader.js";
+import { type DomainName } from "./types.js";
+export type ConfigBundle = Partial<Record<DomainName, unknown>>;
+/** Read the (portable, by default) domains out of any ConfigReader → a bundle object. Absent domains are
+ *  omitted (not defaulted) so a re-import doesn't fabricate domains the source never set. */
+export declare function exportBundle(reader: ConfigReader, domains?: readonly DomainName[]): Promise<ConfigBundle>;
+/** Write a bundle to `<root>/config.d/<domain>.json` — each file atomic + VALIDATED (writeDomainFile parses
+ *  against the domain zod, so a malformed source domain fails loudly rather than writing garbage). Returns the
+ *  domains written. (The TOC owns `<root>`; secrets stay in `<root>/.env`, never in these files.) */
+export declare function writeBundle(root: string, bundle: ConfigBundle): Promise<DomainName[]>;
+/** Read a `<root>/config.d/*.json` bundle → raw domain configs (missing/empty file → omitted). The reverse of
+ *  writeBundle: feed into sema-registry's per-domain PUT to import, or into the resolver to run locally. */
+export declare function readBundle(root: string, domains?: readonly DomainName[]): Promise<ConfigBundle>;

package/dist/bundle.js

@@ -0,0 +1,67 @@
+/**
+ * Round-trip between a config SOURCE (any {@link ConfigReader} — sema-registry's store OR a FileConfigStore)
+ * and a local `config.d/<domain>.json` BUNDLE. This is how a FLEET config seeds a TOC desktop (export → copy
+ * the bundle + set .env → run locally) and how a local bundle seeds sema-registry (readBundle → PUT each domain
+ * via the existing domain API). The bundle = the RAW authorable domain configs; `skills` carry their full
+ * bodies (SkillSpec.content is stored in full — NOT the /effective manifest), so there is no separate
+ * body-bundling step and the round-trip is symmetric.
+ *
+ * Node-only (writeBundle/readBundle touch the filesystem) → imported via `@sema-agent/settings-schema/node`.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeDomainFile } from "./file-edit.js";
+import { PORTABLE_DOMAINS } from "./file-store.js";
+import { isDomainName } from "./types.js";
+/** Read the (portable, by default) domains out of any ConfigReader → a bundle object. Absent domains are
+ *  omitted (not defaulted) so a re-import doesn't fabricate domains the source never set. */
+export async function exportBundle(reader, domains = PORTABLE_DOMAINS) {
+    const out = {};
+    for (const d of domains) {
+        const v = await reader.getDomain(d);
+        if (v !== undefined)
+            out[d] = v;
+    }
+    return out;
+}
+/** Write a bundle to `<root>/config.d/<domain>.json` — each file atomic + VALIDATED (writeDomainFile parses
+ *  against the domain zod, so a malformed source domain fails loudly rather than writing garbage). Returns the
+ *  domains written. (The TOC owns `<root>`; secrets stay in `<root>/.env`, never in these files.) */
+export async function writeBundle(root, bundle) {
+    const written = [];
+    for (const [d, v] of Object.entries(bundle)) {
+        if (v === undefined)
+            continue;
+        await writeDomainFile(root, d, v);
+        written.push(d);
+    }
+    return written;
+}
+/** Read a `<root>/config.d/*.json` bundle → raw domain configs (missing/empty file → omitted). The reverse of
+ *  writeBundle: feed into sema-registry's per-domain PUT to import, or into the resolver to run locally. */
+export async function readBundle(root, domains = PORTABLE_DOMAINS) {
+    const out = {};
+    await Promise.all(domains.map(async (d) => {
+        if (!isDomainName(d))
+            throw new Error(`"${d}" is not a config domain — refusing to build a config.d path from it (no traversal)`);
+        let text;
+        try {
+            text = await readFile(path.join(root, "config.d", `${d}.json`), "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return; // absent file → omit (not fabricated)
+            throw e;
+        }
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        try {
+            out[d] = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`invalid JSON in config.d/${d}.json`); // sanitized: never echo the raw file text
+        }
+    }));
+    return out;
+}

package/dist/config-fns.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Pure config functions + data shapes — LIFTED verbatim out of sema-registry's `store.ts` (the half that
+ * depends only on `./types`, zero app/DB/next coupling). sema-registry re-exports these so its existing
+ * `@/lib/config` importers keep working unchanged (ONE copy of the code, here).
+ *
+ * Two DETERMINISM refactors vs. the original store.ts (so the package is wall-clock-free and a local file
+ * source can produce byte-identical effective config for identical inputs):
+ *   1. `buildEffective(version, getRaw, updatedAt)` — `updatedAt` is now a REQUIRED param (was a
+ *      `new Date().toISOString()` default). Every caller supplies it explicitly.
+ *   2. `emptyEffective()` seeds the epoch (`new Date(0).toISOString()`) instead of the wall clock, matching
+ *      the stores' existing "epoch sentinel" reduce seed.
+ *
+ * The fat `ConfigStore` interface itself STAYS in sema-registry (app-only, ~32 publish/RBAC/worker-status
+ * methods); only the narrow {@link ConfigReader} (reader.ts) is carried here.
+ */
+import type { z } from "zod";
+import { type DomainConfig, type DomainName, type EffectiveConfig, type EffectiveWire } from "./types.js";
+/** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
+ *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
+ *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
+ *  any secret-shaped run (`%` kept in the run so a percent-encoded secret stays whole for the percent-aware
+ *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14. */
+export declare function redactSecrets(text: string): string;
+/** Sanitize a ZodError IN PLACE so no surfaced error (message / `received` / nested `unionErrors`) echoes a
+ *  pasted secret. RECURSES into `unionErrors` (a `z.union` failure nests a ZodError per member — e.g. RoleTarget
+ *  `{model}|{select}`) and redacts string path segments too. The ONE sanitizer every validation entry point
+ *  uses (parseDomain / validateDomain / validateRemoteExec / write*). R14. */
+export declare function sanitizeZodError(err: z.ZodError): z.ZodError;
+/** Result of a CAS write (sema-registry's `ConfigStore.setDomainsIfUnchanged`): applied (new `version`) or
+ *  rejected because the version moved (`currentVersion` = what it is now, so the caller can re-read + retry). */
+export type CasWriteResult = {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    currentVersion: number;
+};
+/** sema-registry's lifecycle bookkeeping for one worker (its OWN clock — design/25 决策3). */
+export interface WorkerLifecycleRecord {
+    name: string;
+    /** when sema-registry FIRST saw this worker — TTL is measured from here. */
+    firstSeenAt: string;
+    /** last time the reverse-proxy saw traffic to it (idle detection). */
+    lastActiveAt?: string;
+}
+/** RBAC roles, hierarchical: viewer < editor < publisher < admin. */
+export type UserRole = "viewer" | "editor" | "publisher" | "admin";
+export declare const ROLE_RANK: Record<UserRole, number>;
+export declare const USER_ROLES: readonly UserRole[];
+/** True if `role` is at least `min` in the hierarchy (e.g. publisher satisfies editor). */
+export declare function roleAtLeast(role: UserRole, min: UserRole): boolean;
+export declare function isRole(v: unknown): v is UserRole;
+/**
+ * Minimum role to WRITE a domain. Default = `editor`; `skills` and `mcp` are raised to `publisher`
+ * because their content goes straight into the agent's system prompt / tool surface — one edit retargets
+ * the prompt of every worker × scenario that loads it (docs/MCP-SKILLS.md §3.3, decision §6 Q3 从严).
+ * Looked up by the [domain] PUT route. Any domain absent here uses {@link DEFAULT_DOMAIN_WRITE_ROLE}.
+ */
+export declare const DEFAULT_DOMAIN_WRITE_ROLE: UserRole;
+export declare const DOMAIN_WRITE_ROLE: Partial<Record<DomainName, UserRole>>;
+/** The minimum role required to write `domain` (the raised gate for skills/mcp, else editor). */
+export declare function domainWriteRole(domain: DomainName): UserRole;
+/** A console user (no secret). */
+export interface User {
+    username: string;
+    role: UserRole;
+    /** True = an SSO user (empty password hash) auto-provisioned from Gitea OAuth — signs in via Gitea only,
+     *  no password. Derived on list (we expose the boolean, never the hash) so /users can distinguish them. */
+    sso?: boolean;
+}
+/** A user with its password hash (login only — never sent to the client). */
+export interface UserAuth extends User {
+    passwordHash: string;
+    /** scrypt hash of the user's API token (NOT the plaintext), or undefined/"" if none. A `Bearer cc_<user>_<rand>`
+     *  is authenticated by scrypt-verifying `<rand>` against this. Set/revoked via `ConfigStore.setUserApiToken`. */
+    apiTokenHash?: string;
+}
+/** Outcome of an atomic `ConfigStore.approvePublish`. */
+export type ApprovePublishResult = {
+    status: "no-pending";
+} | {
+    status: "is-requester";
+} | {
+    status: "approved";
+    approvals: number;
+    required: number;
+} | {
+    status: "published";
+    approvals: number;
+    version: number;
+}
+/** The draft changed since the request was opened — publishing it would release content the approvers
+ *  never reviewed. The pending is cleared; re-request against the current draft. */
+ | {
+    status: "draft-moved";
+    expectedVersion: number;
+    currentVersion: number;
+};
+/** A pending publish awaiting approvals (publish approval workflow). Singleton — the current draft. */
+export interface PendingPublish {
+    requestedBy: string;
+    requestedAt: string;
+    summary?: string;
+    /** The config version this request asks to release — approvals sign off on EXACTLY this draft; the final
+     *  approval refuses (draft-moved) if the version has advanced since. Optional only for legacy rows
+     *  persisted before the field existed (treated as moved — never published). */
+    draftVersion?: number;
+    /** approvers who've signed off (deduped; the requester may not approve their own). */
+    approvals: {
+        user: string;
+        at: string;
+    }[];
+}
+/** A frozen, deliberately-published config release (draft→publish gate, E). */
+export interface PublishedSnapshot {
+    /** the frozen merged config consumers receive in publish mode (carries the version at publish time). */
+    config: EffectiveConfig;
+    /** when it was promoted to published. */
+    publishedAt: string;
+    /** who published it. */
+    publishedBy: string;
+    /** optional release note. */
+    summary?: string;
+    /** MONOTONIC publish counter — increments on EVERY publish INCLUDING a rollback-republish, so it never goes
+     *  backward (unlike `config.version`, which a rollback re-freezes to an OLDER value). The sole ordering/
+     *  freshness authority consumers compare across published snapshots (design CENTER-CONTROL-PLANE R2-S #9 /
+     *  R2-D4). `config.version` stays the CAS/contentHash anchor WITHIN a revision; revision orders ACROSS them. */
+    globalRevision: number;
+}
+/** The empty/defaults effective config at version 0 — what publish mode serves before the first publish.
+ *  Seeds the epoch (`new Date(0)`) so it's deterministic (the wall-clock default was the original store.ts
+ *  non-determinism — see the file header). */
+export declare function emptyEffective(): EffectiveConfig;
+/** Validate + fill defaults for a domain payload (or the schema's empty default when absent/invalid). */
+export declare function parseDomain<K extends DomainName>(domain: K, raw: unknown): DomainConfig[K];
+/**
+ * Shared GC predicate for worker-status rows (F10) — keeps memory/sqlite/tidb identical. Given the rows'
+ * `{name, updatedAt}` and the GC options, returns the names to prune (A: not in `keepNames`; B: older than
+ * `ttlMs`). Pass neither selector → prunes nothing (guards against a wipe-all). See `ConfigStore.gcWorkerStatuses`.
+ */
+export declare function statusRowsToPrune(rows: {
+    name: string;
+    updatedAt: string;
+}[], opts: {
+    keepNames?: string[];
+    ttlMs?: number;
+    now?: Date;
+}): string[];
+/**
+ * Merge every domain into the effective config a consumer pulls. Shared by all store impls.
+ * `updatedAt` is REQUIRED (the determinism refactor — the original store.ts defaulted it to the wall clock,
+ * which made `emptyEffective`/the memory store non-deterministic). Every caller now supplies it explicitly.
+ */
+/** Lift the governance trio out of a LEGACY runtime doc (pre-0.6 stored runtime carried autonomy/commandPolicy/
+ *  approvalRequire). Used as the governance domain's read fallback when governance was NEVER set — so a 0.5
+ *  store upgrades with zero data migration and zero gate loss. An explicitly-set governance domain WINS
+ *  (its absence-of-a-key then means "center not managing", never "fall back to legacy runtime"). */
+export declare function legacyGovernanceFromRuntime(rawRuntime: unknown): unknown;
+/** A warning emitted by {@link buildEffective} when it clamps/degrades instead of throwing (0.8.1), or by
+ *  {@link FileConfigStore} when a file it will never read sits in `config.d/` (0.19.0). Callers route it to
+ *  their audit stream; omitting the callback keeps the resilience but drops the telemetry.
+ *
+ *  0.19.0 加了两个 kind(additive union member —— 用 `switch` 穷举本类型的消费方需补臂):
+ *  `"unknown-keys-dropped"` / `"unread-config-file"`,成案见 {@link droppedKeys}(sema-server
+ *  #322:配置写了、进程跑着、值没到,而没有任何一个字说出来)。 */
+export type EffectiveReadWarning = {
+    domain: "hosts";
+    kind: "hosts-grandfathered";
+    droppedNames: string[];
+    truncatedFrom?: number;
+} | {
+    domain: DomainName;
+    kind: "domain-defaulted";
+    error: unknown;
+}
+/** 域文档里那些**不属于该域 schema** 的键:行为照旧(zod 非 strict = 剥掉,前向兼容不动),但点名
+ *  说出来。`keys` = 点号路径(`infraCostRates.toolCalMicroUsd` / `commandPolicy.0.typo`),见
+ *  {@link droppedKeys} 的扫描边界。 */
+ | {
+    domain: DomainName;
+    kind: "unknown-keys-dropped";
+    keys: string[];
+}
+/** open-world 域(`.passthrough()`)里**已送达但本包不认识**的键:值原样到了消费方手里(承运),
+ *  但拼错的键名同样该有人说 —— 认不认归持有键表的消费方,`keys` 是点号路径。 */
+ | {
+    domain: DomainName;
+    kind: "unknown-keys-carried";
+    keys: string[];
+}
+/** `config.d/` 里存在、但本地读取集**永远不会读**的文件(名字不是域,或是域但不便携)。 */
+ | {
+    kind: "unread-config-file";
+    file: string;
+    domain?: DomainName;
+    why: "not-a-domain" | "non-portable-domain";
+};
+/**
+ * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
+ *
+ * 成案(sema-server #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
+ * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
+ * (新 center 的新键不该炸老消费方),所以修法不是收紧成 `.strict()`,而是让它**响亮**:
+ * {@link buildEffective} 每域解析成功后调用本函数,非空即发 `"unknown-keys-dropped"` 警告。
+ *
+ * **嵌套也扫**(codex 复审 F2 真 finding):`{infraCostRates:{toolCalMicroUsd:10}}` 这种**拼错的嵌套
+ * 键**在顶层看不见(`infraCostRates` 键还在),只看顶层等于对计费面的错键完全失明。故按 raw↔parsed
+ * 的键集逐层对比(对象逐键、数组同长时逐下标),不依赖任何 zod 内省。
+ *
+ * `runtime` 域的治理三件({@link GOVERNANCE_MIRROR_KEYS})**不算被丢**:0.5 期 runtime 文档携带它们是
+ * 成文的抬升位(本文件的 governance 抬升函数会把它们抬进 governance 域),报出来是噪声。豁免只在顶层。
+ *
+ * 边界(如实登记):① 深度上限 {@link DROP_SCAN_MAX_DEPTH}、键数上限 {@link DROP_SCAN_MAX_KEYS}(告警
+ * 载荷有界,超出即少报);② 数组长度不同就整段跳过(元素级裁剪由各自的 clamp 告警负责);③ 只比对纯
+ * JSON 对象——raw 若是类实例/Proxy 这类形状不扫;④ 读 raw 的值可能触发访问器,整段包 try/catch 且**绝不**
+ * 让其错误外泄(错误文案可能带 secret,与 parseDomain 的 R13 同纪律),扫描失败即当作"没看见",不影响解析。
+ */
+export declare function droppedKeys(domain: DomainName, raw: unknown, parsed: unknown): string[];
+/**
+ * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(点号路径)。非 open-world 域恒空
+ * (它们的未知键走 {@link droppedKeys} 那条更重的「被丢了」告警)。
+ *
+ * 边界(如实):只看 {@link OPEN_WORLD_KNOWN_KEYS} 登记了的层级 —— 未登记层级(如某个未知键自己的
+ * 子树)不再下探,那本就是消费方自定义的内容,逐层猜没有意义。
+ */
+export declare function carriedUnknownKeys(domain: DomainName, parsed: unknown): string[];
+/**
+ * 一域的 parse + **静默剥键/静默承运两条告警**(0.19.0)。`buildEffective` 与 `FileConfigStore.getDomain`
+ * 共用这一个判据 —— 此前只有 effective 那条路径有门,而 `getDomain` 是 `exportBundle` 的读法
+ * (codex 复审 round2 F3:导出一份被剥了键的域再导入 = 持久的配置丢失,而且全程无声)。
+ */
+export declare function parseDomainLoud<K extends DomainName>(domain: K, raw: unknown, onWarning?: (w: EffectiveReadWarning) => void): DomainConfig[K];
+/** Per-domain READ-corruption policy (0.8.1) — what buildEffective does when a stored domain no longer parses.
+ *  `"default"` = degrade to the schema default + warn (safe: the default only REMOVES capability, fail-closed).
+ *  `"throw"` = keep fail-loud (defaulting would LOOSEN gates or destructively apply — worse than an outage,
+ *  consumers fail-static on last-good). A `satisfies Record<DomainName,…>` forces every FUTURE domain to make
+ *  this call explicitly (compile error until it's classified). Per-domain rationale:
+ *    - models/skills/mcp/plugins/scenarios/systems/collab: additive capability catalogs — empty = the
+ *      capability disappears (fail-closed), no gate is lost.
+ *    - hosts: empty registry = no auto-placement targets (availability-only); self-registration re-lands
+ *      entries as approved:false = 待批 (fail-closed). Plus the precise grandfather clamp runs FIRST.
+ *    - rosters: THROW — a lost roster makes resolveEffectiveForWorker fall back to the FULL models catalog
+ *      ("global(fallback)"), silently WIDENING every restricted worker's model access. 放权,不许.
+ *    - workers: THROW — an empty fleet spec would make the reconciler RETIRE every managed worker
+ *      (destructive apply — far worse than a read outage).
+ *    - runtime: THROW — defaulting drops centrally-published rate/cost ceilings = unbounded spend (fail-open
+ *      on the budget axis).
+ *    - governance: THROW — defaulting drops autonomy/commandPolicy/approvalRequire = the consumer falls back
+ *      to env/defaults with the operator's guardrails silently gone. 放权,不许.
+ *    - entitlement: THROW — defaulting drops the org kill-switch/budget ceilings/tier restrictions for every
+ *      principal. 放权,不许.
+ *    - execution: THROW — defaulting flips required:true (sandbox mandate) back to false. 放权,不许.
+ *      (0.10.1: sessionMirror rides the SAME stance — defaulting would evaporate an org's required:true
+ *      mirror mandate = 审计面静默放权; the shared rationale is exactly WHY it was收编 here, not a new domain.)
+ *    - projects: THROW — defaulting evaporates the whole identity ledger: once the S4 worker gate ships,
+ *      every `proj:*` derivation fails-fast (全租户记忆面停摆 — consumers fail-static on last-good is
+ *      strictly better); WORSE, the claim write face is read-modify-write — reading a defaulted-empty
+ *      ledger and writing it back would CLOBBER existing registrations down to one entry (data loss,
+ *      one layer beyond the rosters "放权" rationale). */
+export declare const DOMAIN_READ_FALLBACK: {
+    readonly models: "default";
+    readonly rosters: "throw";
+    readonly skills: "default";
+    readonly mcp: "default";
+    readonly plugins: "default";
+    readonly scenarios: "default";
+    readonly systems: "default";
+    readonly collab: "default";
+    readonly workers: "throw";
+    readonly hosts: "default";
+    readonly runtime: "throw";
+    readonly governance: "throw";
+    readonly entitlement: "throw";
+    readonly execution: "throw";
+    readonly projects: "throw";
+    readonly prompts: "default";
+    readonly limits: "throw";
+};
+/** Result of {@link grandfatherHostsRead}. `raw` is the (possibly clamped) document to parse; when NOTHING
+ *  was clamped it is the ORIGINAL reference — well-formed data stays byte-identical through the read path. */
+export interface GrandfatherHostsReadResult {
+    raw: unknown;
+    /** Host names DROPPED because they exceed HOST_NAME_MAX (63) — truncating would forge a NEW identity that
+     *  matches no ORCH_HOST_ID (and could collide into the duplicate-name refine), so the entry is skipped whole. */
+    droppedNames: string[];
+    /** Set when the hosts array (after drops) exceeded HOSTS_ARRAY_MAX (1024) and was sliced — the pre-slice length. */
+    truncatedFrom?: number;
+}
+/** READ-path grandfather clamp for the 0.8.0 hosts tightening (0.8.1, S3 M-1). Clamps ONLY the two bounds
+ *  0.8.0 added (name > 63 → drop the entry; array > 1024 → slice) so 0.7-era legal stored data keeps reading;
+ *  everything else (regex, types, duplicates) is left for parseDomain — this is a targeted grandfather, not a
+ *  lenient parser. PURE + idempotent; returns the ORIGINAL reference when nothing exceeds the bounds. */
+export declare function grandfatherHostsRead(raw: unknown): GrandfatherHostsReadResult;
+export declare function buildEffective(version: number, getRaw: (d: DomainName) => unknown, updatedAt: string, onWarning?: (w: EffectiveReadWarning) => void): EffectiveConfig;
+/** READ-side tolerant judgment for a GET /effective **wire payload**(the {@link EffectiveWire} contract)at
+ *  its CONSUMPTION boundary — a service pulling from a remote center passes the parsed JSON here instead of
+ *  type-asserting it(0.12.0,[2281] 裁B:「两个契约共用一个拼写不是一个被检查的契约」——拼写副本要在
+ *  消费端被真校验)。ONE judgment, two legs: every known domain goes through the SAME `parseDomain` +
+ *  {@link DOMAIN_READ_FALLBACK} policy as {@link buildEffective}(catalog 域坏形 → schema default + warning;
+ *  gate 域坏形 → throw,caller 的整包 catch 决定回落),including the governance legacy-lift and the hosts
+ *  read-grandfather — DELEGATED to buildEffective, not re-implemented(单判据双腿消费,§M4)。
+ *
+ *  `skills` is the ONE wire divergence: on the wire it is a MANIFEST(content → contentHash,
+ *  {@link SkillsManifest}),so the full skills-domain schema would reject every LEGAL manifest and silently
+ *  default the domain(蒸发整张 skill 清单)— it validates against {@link SkillsManifestSchema} instead,
+ *  same "default" fallback tier as the skills domain itself.
+ *
+ *  OPEN-WORLD on unknown top-level keys: they ride through VERBATIM(never validated, never dropped)— a
+ *  newer center's new domain reaches an older service untouched(§M2 能力面语义:读不到即走老路,不该炸),
+ *  and the legacy `teams` key(not a domain since 0.7, services still consume it for backward compat)keeps
+ *  flowing. Throws ONLY on garbage no caller can partially trust: a non-object payload, or a missing/
+ *  non-finite `version` — that is not "a bad domain", it is not an effective config at all. */
+export declare function readEffectiveWire(raw: unknown, onWarning?: (w: EffectiveReadWarning) => void): EffectiveWire;
+/** 档位组→引擎单表的唯一解析点(0.9.0)。返回 ACTIVE 档位组的绑定表(剔除未绑档),即 core
+ *  `RunnerDeps.tiers` 要吃的那张单表——组切换=center 换这张表下发,零新引擎机制。无 active 组/未命中/
+ *  组内一档未绑 → `undefined`(引擎档位层恒惰性,与「未配 tiers」逐字同义)。消费方(center /effective
+ *  投影、service applyEffective 接线)都走这一个函数,不要各自解析。 */
+export declare function resolveActiveTiers(models: Pick<DomainConfig["models"], "tierGroups" | "activeTierGroup">): Record<string, string> | undefined;