@sema-agent/server 7.132.0 → 7.133.0

package/dist/memory-sync-client.d.ts

@@ -20,29 +20,43 @@ export declare function createMemorySyncTransport(opts: {
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
 }): MemorySyncTransport;
-/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录
- *  旁)下的 per-peer sidecar。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同)。 */
-export declare function memorySyncCursorPath(memoryRoot: string, peer: string): string;
+/** cursor 文件路径:`memoryRoot`(= RunnerDeps.memoryEngineDir 的 resolved config root,memory/ 目录旁)下的
+ *  per-(peer, scope) sidecar(`sync-cursors/<peer>/<scope 摘要>.json`)。peer 段走 core encodeScopeSegment(文件名安全字符纪律与 scope 目录同);scope 段取 sha256 前 32 hex
+ *  (scope 键带 `:` `/` 且可长过段编码的 64 字符帽 —— 名字只需区分,内容里仍记原 scope,读时比对)。 */
+export declare function memorySyncCursorPath(memoryRoot: string, peer: string, scope: string): string;
+/** 一轮里一层的结果。 */
+export interface MemorySyncLayerResult {
+    readonly scope: string;
+    readonly result: MemorySyncClientResult;
+}
+/** 一轮(按层)的结果:成功的各层,按同步序(同步层在前,项目层按键序)。 */
+export interface MemorySyncRound {
+    readonly layers: readonly MemorySyncLayerResult[];
+}
 export interface MemorySyncRunner {
-    /** 一轮同步(串行:排在上一轮之后)。返回 core 结构化结果供调用方记 metrics/日志;transport/
-     *  协议错误向上 throw(本地零副作用,core 契约)。cursor 读写、conflicts warn 都在轮内完成。 */
-    syncOnce(reason: string): Promise<MemorySyncClientResult>;
+    /** 一轮同步(串行:排在上一轮之后),逐层一轮。任一层 transport/协议错误 ⇒ 其余层照跑,轮末汇总 reject(失败层本地零副作用,
+     *  core 契约);cursor 读写、conflicts warn 都在层内完成。 */
+    syncOnce(reason: string): Promise<MemorySyncRound>;
     /** fire-and-forget 一轮:上一轮在飞(排队/执行中)则跳过(inflight 节流);失败 warn 不上抛。 */
     trigger(reason: string): void;
-    /** cursor sidecar 的落盘路径(boot 日志/测试可见性)。 */
-    readonly cursorPath: string;
+    /** 跟踪一只本层属主的项目层(本地还没有条目也每轮拉它);首次跟踪即排一轮。不是本同步腿覆盖的项目层 ⇒ 抛(调用方的错)。 */
+    track(scope: string): void;
+    /** 把一段动本地记忆面的工作排进同步的串行链(等在飞的轮落定、执行时没有轮在飞)—— 项目层折叠用(`memory-project-layer.ts`)。 */
+    exclusive<T>(work: () => Promise<T>): Promise<T>;
+    /** 某一层的 cursor sidecar 路径(boot 日志/测试可见性)。 */
+    cursorPathFor(scope: string): string;
     /** 排队+在飞的轮数(测试的确定性等待面;0 = 完全空闲)。 */
     pending(): number;
 }
-/**
- * 组装一个 per-(scope,peer) 的同步执行器:cursor 持久化 + core `syncMemoryScope` + conflicts 上报 +
- * 串行化/节流。`backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` =
- * resolved config root(cursor sidecar 落在 memory/ 目录旁)。
- */
 /** S2.5 分批 loop 的轮数上限(fail-loud 警戒,防协议异常时死循环;正常收敛远低于此)。 */
 export declare const MAX_SYNC_ROUNDS = 32;
+/**
+ * 组装同步执行器:同步层 `scope` + 同属主的项目层,逐层一轮(cursor 持久化 + core `syncMemoryScope` + conflicts 上报),串行化/节流。
+ * `backend` = 本地 File authority plane(memoryEngineBackendFor 的产物);`memoryRoot` = resolved config root(cursor sidecar 落在 memory/ 目录旁)。
+ */
 export declare function createMemorySyncRunner(opts: {
     backend: MemoryBackend;
+    /** 同步层(`config.memorySync.scope`);它同属主的项目层随它一起同步。 */
     scope: string;
     memoryRoot: string;
     transport: MemorySyncTransport;

package/dist/memory-sync-client.js

@@ -1,7 +1,9 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
+import { replicationCovers } from "./memory-scope.js";
+import { parseProjectLayerKey } from "./project-layer-key.js";
 export const DEFAULT_MEMORY_SYNC_PEER = "central";
 export function createMemorySyncTransport(opts) {
     const base = opts.url.replace(/\/+$/, "");
@@ -20,7 +22,10 @@ export function createMemorySyncTransport(opts) {
         return JSON.parse(text);
     };
 }
-export function memorySyncCursorPath(memoryRoot, peer) {
+export function memorySyncCursorPath(memoryRoot, peer, scope) {
+    return join(memoryRoot, "sync-cursors", encodeScopeSegment(peer), `${createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32)}.json`);
+}
+function legacyMemorySyncCursorPath(memoryRoot, peer) {
     return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
 }
 async function loadCursor(path, scope, peer, log) {
@@ -41,6 +46,13 @@ async function loadCursor(path, scope, peer, log) {
         log.warn("memory_sync_cursor_corrupt", { path, err: String(err), note: "treating as first round" });
         return undefined;
     }
+    const cursor = cursorOf(parsed, scope, peer);
+    if (cursor !== undefined)
+        return cursor;
+    log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
+    return undefined;
+}
+function cursorOf(parsed, scope, peer) {
     if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
         const c = parsed;
         const baseRevsRaw = c["baseRevs"];
@@ -55,9 +67,34 @@ async function loadCursor(path, scope, peer, log) {
             return { scope, peer, baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
         }
     }
-    log.warn("memory_sync_cursor_invalid", { path, scope, peer, note: "shape/identity mismatch — treating as first round" });
     return undefined;
 }
+async function adoptLegacyCursor(memoryRoot, scope, peer, log) {
+    const target = memorySyncCursorPath(memoryRoot, peer, scope);
+    const legacy = legacyMemorySyncCursorPath(memoryRoot, peer);
+    const facts = await Promise.all([readFile(target, "utf8").then(() => "present", (err) => (err.code === "ENOENT" ? "absent" : "present")), readFile(legacy, "utf8").then((text) => ({ text }), (err) => ({ err }))]);
+    const [targetFact, legacyRead] = facts;
+    if (targetFact === "present")
+        return;
+    if ("err" in legacyRead) {
+        if (legacyRead.err.code !== "ENOENT")
+            log.warn("memory_sync_cursor_read_failed", { path: legacy, err: String(legacyRead.err), note: "legacy cursor not adopted — this layer starts from its own cursor" });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(legacyRead.text);
+    }
+    catch (err) {
+        log.warn("memory_sync_cursor_corrupt", { path: legacy, err: String(err), note: "legacy cursor not adopted" });
+        return;
+    }
+    if (cursorOf(parsed, scope, peer) === undefined)
+        return;
+    await mkdir(dirname(target), { recursive: true });
+    await rename(legacy, target);
+    log.info("memory_sync_cursor_adopted", { from: legacy, to: target, scope, peer });
+}
 async function saveCursor(path, cursor) {
     await mkdir(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
@@ -65,18 +102,36 @@ async function saveCursor(path, cursor) {
     await rename(tmp, path);
 }
 export const MAX_SYNC_ROUNDS = 32;
+function enumerateScopes(backend) {
+    const face = backend.listScopes;
+    return typeof face === "function" ? face.call(backend) : { supported: false, reason: "the memory backend has no listScopes face" };
+}
 export function createMemorySyncRunner(opts) {
     const peer = opts.peer ?? DEFAULT_MEMORY_SYNC_PEER;
-    const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer);
-    const round = async (reason) => {
-        let cursor = await loadCursor(cursorPath, opts.scope, peer, opts.log);
+    const coverage = { kind: "layers", layers: [opts.scope] };
+    const tracked = new Set();
+    let legacyCursorChecked = false;
+    let enumerationWarned = false;
+    const isCoveredProjectLayer = (scope) => scope !== opts.scope && parseProjectLayerKey(scope) !== undefined && replicationCovers(coverage, scope);
+    const layersOfRound = () => {
+        const local = enumerateScopes(opts.backend);
+        if (!local.supported && !enumerationWarned) {
+            enumerationWarned = true;
+            opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, peer, reason: local.reason, note: "only the sync layer and tracked project layers are synced" });
+        }
+        const projectLayers = new Set([...(local.supported ? local.scopes : []), ...tracked].filter(isCoveredProjectLayer));
+        return [opts.scope, ...[...projectLayers].sort()];
+    };
+    const syncLayer = async (scope, reason) => {
+        const cursorPath = memorySyncCursorPath(opts.memoryRoot, peer, scope);
+        let cursor = await loadCursor(cursorPath, scope, peer, opts.log);
         let result;
         let subRound = 0;
         for (;;) {
             subRound += 1;
             result = await syncMemoryScope({
                 backend: opts.backend,
-                scope: opts.scope,
+                scope,
                 transport: opts.transport,
                 peer,
                 ...(cursor !== undefined ? { cursor } : {}),
@@ -85,11 +140,11 @@ export function createMemorySyncRunner(opts) {
                 ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
             });
             for (const w of result.warnings ?? [])
-                opts.log.warn("memory_sync_warning", { scope: opts.scope, peer, subRound, warning: w });
+                opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
                 break;
             if (subRound >= MAX_SYNC_ROUNDS) {
-                opts.log.warn("memory_sync_rounds_exhausted", { scope: opts.scope, peer, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
+                opts.log.warn("memory_sync_rounds_exhausted", { scope, peer, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
                 break;
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
@@ -101,11 +156,11 @@ export function createMemorySyncRunner(opts) {
                 }
             }
             cursor = result.cursor ?? cursor;
-            opts.log.info("memory_sync_continuation", { reason, scope: opts.scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
+            opts.log.info("memory_sync_continuation", { reason, scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
-                scope: opts.scope,
+                scope,
                 peer,
                 side: c.side,
                 id: c.id,
@@ -124,7 +179,7 @@ export function createMemorySyncRunner(opts) {
         }
         opts.log.info("memory_sync_round", {
             reason,
-            scope: opts.scope,
+            scope,
             peer,
             ok: result.ok,
             cursorAdvanced: result.cursorAdvanced,
@@ -136,11 +191,32 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
+    const round = async (reason) => {
+        if (!legacyCursorChecked) {
+            legacyCursorChecked = true;
+            await adoptLegacyCursor(opts.memoryRoot, opts.scope, peer, opts.log);
+        }
+        const layers = [];
+        const failures = [];
+        for (const scope of layersOfRound()) {
+            try {
+                layers.push({ scope, result: await syncLayer(scope, reason) });
+            }
+            catch (err) {
+                failures.push({ scope, err });
+                opts.log.warn("memory_sync_layer_failed", { reason, scope, peer, err: String(err) });
+            }
+        }
+        if (failures.length > 0) {
+            throw new Error(`memory sync round failed for ${failures.length} layer(s): ${failures.map((f) => `${f.scope}: ${f.err instanceof Error ? f.err.message : String(f.err)}`).join("; ")}`);
+        }
+        return { layers };
+    };
     let chain = Promise.resolve();
     let pending = 0;
-    const syncOnce = (reason) => {
+    const exclusive = (work) => {
         pending += 1;
-        const run = chain.then(() => round(reason));
+        const run = chain.then(work);
         chain = run.then(() => {
             pending -= 1;
         }, () => {
@@ -148,13 +224,26 @@ export function createMemorySyncRunner(opts) {
         });
         return run;
     };
-    const trigger = (reason) => {
-        if (pending > 0)
-            return;
+    const syncOnce = (reason) => exclusive(() => round(reason));
+    const queueRound = (reason) => {
         void syncOnce(reason).catch((err) => {
             opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, peer, err: String(err) });
         });
     };
-    return { syncOnce, trigger, cursorPath, pending: () => pending };
+    const trigger = (reason) => {
+        if (pending > 0)
+            return;
+        queueRound(reason);
+    };
+    const track = (scope) => {
+        if (!isCoveredProjectLayer(scope)) {
+            throw new Error(`memory sync track(): ${JSON.stringify(scope)} is not a project layer of this sync leg (layer ${JSON.stringify(opts.scope)} replicates its own project layers only)`);
+        }
+        if (tracked.has(scope))
+            return;
+        tracked.add(scope);
+        queueRound("track");
+    };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, peer, scope), pending: () => pending };
 }
 //# sourceMappingURL=memory-sync-client.js.map

package/dist/model-entry-refusal.d.ts

@@ -116,10 +116,18 @@ export declare function refusedNamesLogFields(key: string, names: readonly strin
 export declare function refusalEventOf(reason: ModelEntryRefusalReason): "web_admin_model_no_brain" | "web_admin_model_entry_invalid";
 /** warn 字段(不含值):`field` = 第一处坏字段(告警规则最常按它分组),`fields` = 全部。S-805:`model` 只在名可披露时写。 */
 export declare function refusalWarnFields(name: string, r: ModelEntryRefusal): Record<string, unknown>;
+/** 调用方写的模型 ref(`model` / `compactionModel` / `agents[i].model` / `@name`)回到人面前 —— 拒句与留声日志 —— 的字符上限。 */
+export declare const MODEL_REF_ECHO_CHARS = 120;
+/**
+ * 调用方写的模型 ref 的回显形:过回显的一只口径 {@link echoCallerText}(剥控制与双向字符,截到 {@link MODEL_REF_ECHO_CHARS} 字,超出加 `…`)。
+ * 目录门、`resolveSpec`、side-query 的拒句,以及它们写进运维日志的 `requested` 字段,**都**调这一只 —— 不在站点手写 `slice`。
+ */
+export declare function echoModelRef(ref: string): string;
 /**
  * 一次**显式选择**命中了不可用条目时的拒因句(HTTP `request.model_unavailable` 的 `error`、run-local 的 stderr、
  * hook 选模型的失败文案 —— 各处同一句)。`field` = 调用方的通道名(`model` / `compactionModel` / `agents[0].model` /
- * `@-mention`),`requested` = 调用方发来的原形(name 或 id),已由调用方截断。
+ * `@-mention`),`requested` = 调用方发来的**原形**(name 或 id;本函数回显它时过 {@link echoModelRef},调用方不预先截)。
+ * 别名段(`(catalog entry …)`)的判断读原形:ref 与条目名逐字相同 ⇒ 不带,不因回显截短而误判成「另有条目」。
  */
 export declare function modelUnavailableMessage(field: string, requested: string, name: string, r: ModelEntryRefusal): string;
 /** 缺省模型不变量读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */

package/dist/model-entry-refusal.js

@@ -3,6 +3,7 @@ import { ModelEntry, formatConfigPath, isReportableRefusalName } from "@sema-age
 import { catalogBrainLane } from "./model-provider.js";
 import { readCatalogEntryHeaders } from "./model-entry-headers.js";
 import { DroppedCatalogEntryRow, describeSchemaIssueFields, describeSchemaIssues } from "./web-admin-client/read-warnings.js";
+import { echoCallerText } from "./caller-text-echo.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const ENTRY_REFUSAL_REASON_OF = {
     "config.model_no_brain": "no_brain",
@@ -132,9 +133,13 @@ export function refusalWarnFields(name, r) {
         hint: r.detail,
     };
 }
+export const MODEL_REF_ECHO_CHARS = 120;
+export function echoModelRef(ref) {
+    return echoCallerText(ref, { maxChars: MODEL_REF_ECHO_CHARS });
+}
 export function modelUnavailableMessage(field, requested, name, r) {
     const alias = requested === name ? "" : ` (catalog entry "${name}")`;
-    return `${field} "${requested}"${alias} is published in the catalog but unavailable on this deployment [${r.code}] — ${r.detail}`;
+    return `${field} "${echoModelRef(requested)}"${alias} is published in the catalog but unavailable on this deployment [${r.code}] — ${r.detail}`;
 }
 export function defaultModelRefusal(view, leg) {
     if (Object.hasOwn(view.models, DEFAULT_MODEL_REF) && view.models[DEFAULT_MODEL_REF] !== undefined)

package/dist/model-plane-face.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `GET /v1/models` 顶层 `modelPlane` 的**唯一铸点** —— 壳问「这台引擎服务的是哪张模型表 / 目录采纳了没有 / 起服路由判官怎么说」读这一格,不自己预测。
+ *
+ * ## 为什么在 server 里答
+ * 判官的输入是服务进程的事实:采纳之后 `config.model` 是不是还是那只 env 模型(对象同一性)、anthropic 路由装没装(凭据在场性)、名册布防(env 表是占位)。
+ * 壳拼不出这些,只能镜像两道判(目录条目逐条合形、车道 / 端点可解析)—— 镜像会随时间与真判官漂开(同一问两份读法)。所以结论只有 server 说,壳读它。
+ *
+ * ## 四个字段,两根轴
+ *  · `servedTable` —— **谁在服**:{@link servedModelTableLeg}(此刻服务 env 表还是目录表;同一只读法,不另记旗子)。
+ *  · `catalog` —— **最近一份目录候选的结局**({@link CATALOG_STANCES}):
+ *      `refused` —— 候选被整拒:候选判官整拒(`candidateRejectionState` 座),或模型面组拒(`modelRefusalsState().plane` 在场;各码见
+ *                   settings-schema `MODEL_PLANE_REFUSAL_CODES`)。没有 LKG 时服务的是 env 表,有 LKG(或上一代已采纳)时仍服目录表 —— 谁在服归 `servedTable` 答,
+ *                   不在这一格里合并(合并 = 一个字段两个意思);逐条被拒(条目不可用,`entries`)不是整拒,那些条目之外的目录照服;
+ *      `adopted` —— 没有整拒、且服务的是目录表;
+ *      `absent`  —— 没有整拒、且服务的是 env 表:没配目录源 / 配了但没有启用条目(候选不管模型面,不是拒)/ 纯 env 部署。
+ *    两个座(候选判官的结论座与模型面组拒的信号座)是候选在两道判官各自留下的事实,本格只读它们,不另算第二份。
+ *    **不在内**:候选过了两道判官、却在装配期被引擎整份拒收(`applyEffective` 里引擎拒收 `apiKeyEnv` 声明 / Runner 拒收换装;活配置零触碰,只有日志与 `/health` 世代账的 target≠applied)——
+ *    这一形今天没有座,`catalog` 仍按上一代读;`adopted` 说的是「没有被判官整拒」,不是「最新候选已落地」(那一问归世代账)。要覆盖它得先给装配期拒收立一个座(另案设计)。
+ *  · `refusalCode` / `gap` —— **起服路由判官对当前 config 的判决**:`judgeServedModelRoute` 同一只函数(装配第 2 段与 `run-local` 调的就是它),通过 ⇒ 两键缺席。
+ *    进程既然起来了,正常是缺席;测试夹具 / 自建装配 / 不拒启的入口可能在场 —— 如实投,不替它们编造通过。**不带句子**(拒因句只走日志与起服错误)。
+ *
+ * ## 只在起服后可答
+ * 读面挂在运行中的进程上;判官必须在目录应用之后调(`judgeServedModelRoute` 头注),起服前没有「将要服务的表」,所以没有起服前的预判口。
+ */
+import type { ModelRefusalsSignal } from "@sema-agent/settings-schema";
+import { type ModelRouteEndpointVerdict, type ModelRouteGap, type ServedModelRouteView } from "./model-route-endpoint.js";
+import { type ModelTableLeg } from "./model-select.js";
+import type { CandidateRejection } from "./web-admin-client/candidate-gate.js";
+/** `modelPlane.catalog` 的闭集(消费方用穷举 switch —— 加一词不补臂 ⇒ 编译红)。 */
+export declare const CATALOG_STANCES: readonly ["absent", "adopted", "refused"];
+export type CatalogStance = (typeof CATALOG_STANCES)[number];
+/** `GET /v1/models.modelPlane` 的 wire 形(纯数据;条件键缺席,不铸 `null` / 空串)。 */
+export interface ModelPlaneFace {
+    readonly servedTable: ModelTableLeg;
+    readonly catalog: CatalogStance;
+    /** 起服路由判官判决的机读码(`ModelPlaneRefusalCode` 的子集:路由端点族两码)。 */
+    readonly refusalCode?: ModelRouteEndpointVerdict["code"];
+    /** 同一次判决的出路轴(缺口两词)。 */
+    readonly gap?: ModelRouteGap;
+}
+/** {@link buildModelPlaneFace} 读的进程事实(都由调用方从各自的座取,本函数不碰任何全局)。 */
+export interface ModelPlaneFacts {
+    /** 严格名册布防(`isRosterGateArmed`):env 表是占位、不被判(装配第 2 段传的是同一只谓词)。 */
+    readonly envTableIsPlaceholder: boolean;
+    /** 候选判官最近一次整拒的结论座(`WebAdminRuntime.candidateRejectionState()`);座空 / 没有配置管道 ⇒ `undefined`。 */
+    readonly candidateRejection: CandidateRejection | undefined;
+    /** 模型拒因信号(`WebAdminRuntime.modelRefusalsState()`);`plane` 在场 ⇒ 最近一份候选的模型面被整组拒。 */
+    readonly modelRefusals: Pick<ModelRefusalsSignal, "plane"> | undefined;
+}
+export declare function buildModelPlaneFace(config: ServedModelRouteView, facts: ModelPlaneFacts): ModelPlaneFace;
+//# sourceMappingURL=model-plane-face.d.ts.map

package/dist/model-plane-face.js

@@ -0,0 +1,24 @@
+import { judgeServedModelRoute } from "./model-route-endpoint.js";
+import { servedModelTableLeg } from "./model-select.js";
+export const CATALOG_STANCES = ["absent", "adopted", "refused"];
+function catalogStanceOf(served, wholeRefused) {
+    if (wholeRefused)
+        return "refused";
+    switch (served) {
+        case "catalog":
+            return "adopted";
+        case "env":
+            return "absent";
+    }
+}
+export function buildModelPlaneFace(config, facts) {
+    const servedTable = servedModelTableLeg(config);
+    const wholeRefused = facts.candidateRejection !== undefined || facts.modelRefusals?.plane !== undefined;
+    const verdict = judgeServedModelRoute(config, { envTableIsPlaceholder: facts.envTableIsPlaceholder });
+    return {
+        servedTable,
+        catalog: catalogStanceOf(servedTable, wholeRefused),
+        ...(verdict !== undefined ? { refusalCode: verdict.code, gap: verdict.gap } : {}),
+    };
+}
+//# sourceMappingURL=model-plane-face.js.map

package/dist/model-provider.d.ts

@@ -99,6 +99,11 @@ export declare function mountRoutes<R extends object, T>(view: {
 export declare function anthropicRouteRoot(route: {
     readonly baseUrl?: string | undefined;
 }): string;
+/**
+ * **请求根「算不算声明了」的唯一尺**:缺席、空串、纯空白都是没声明(core 原话 "nothing, an empty string and whitespace read as undeclared"),声明了就原样带回。
+ * anthropic 路由的请求根({@link anthropicRouteRoot})、openai 兼容路由的有效端点(`model-route-endpoint.ts` 的 `openaiRouteBaseUrl`)与 env 值级端口的 `endpointDeclared` 读同一只。
+ */
+export declare function declaredRootUrl(url: string | undefined): string | undefined;
 /** 判词侧的路由表:值 = 路由自己的配置({@link mountRoutes} 的恒等铸法 —— 判官不读值,只问键)。 */
 export declare function routeTableOf<R extends object>(view: {
     readonly anthropic?: R | undefined;

package/dist/model-provider.js

@@ -29,8 +29,10 @@ export function mountRoutes(view, mount) {
     return route !== undefined ? { anthropic: mount(route) } : {};
 }
 export function anthropicRouteRoot(route) {
-    const declared = route.baseUrl;
-    return declared !== undefined && declared.trim() !== "" ? declared : ANTHROPIC_DEFAULT_BASE_URL;
+    return declaredRootUrl(route.baseUrl) ?? ANTHROPIC_DEFAULT_BASE_URL;
+}
+export function declaredRootUrl(url) {
+    return url !== undefined && url.trim() !== "" ? url : undefined;
 }
 export function routeTableOf(view) {
     return mountRoutes(view, (route) => route);

package/dist/model-route-endpoint.d.ts

@@ -20,8 +20,8 @@
  *    经 {@link judgeServedModelRoute}:目录被采纳 ⇒ 判目录表(目录视图),目录缺席 / 被整拒 / 没有启用条目 ⇒ 判 env 表(env 视图);
  *    严格名册布防(`isRosterGateArmed`)时 env 表是占位、从不被派发 ⇒ 不判它(备用网关那一条与表无关,照判)。
  *    不在 `loadConfig()`:那是目录应用**之前**,env 表还不知道会不会服务(目录一旦采纳就整张换掉它);
- *  · 包根导出的 `judgeModelRouteGap(env)`(`model-route-gap.ts`)问的是**env 腿**:「这份 env 交给引擎、没有目录时起不起得来」—— 同一只判据的 env 视图,
- *    目录在场时起服以目录为准;
+ *  · 壳 / 包问「这台引擎服务哪张表、起服判官怎么说」读 `GET /v1/models` 的 `modelPlane`(`model-plane-face.ts`,同一只 {@link judgeServedModelRoute});
+ *    起服前没有「将要服务的表」可判,所以没有起服前的预判口;
  *  · 热路径:`web-admin-client/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务(目录视图);
  *  · run-local:配置源解析完之后按真要派发的表判(`run-local.ts`)—— 本入口没有名册门,不豁免占位;
  *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);
@@ -43,22 +43,19 @@ export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_end
 /** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
 export declare const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
 /**
- * **路由缺口的出路轴**(闭集;{@link judgeModelRouteGap} 的 `gap` 词,包根导出 —— 壳 / 包在引擎起来之前问同一句)。
+ * **路由缺口的出路轴**(闭集;`GET /v1/models.modelPlane.gap` 的词,包根导出其型)。**只有缺口两词** —— 通过 = 判决为 `undefined`(没有第三个词可说「无缺口」)。
  *
  * 与上面的**码**是两根轴:码是组拒的机读词(`ModelPlaneRefusalCode`,settings-schema 属主),这里是**出路**:
  *  · `endpoint_missing` —— 缺的是网关端点:openai 兼容腿上的条目解析不到 base URL(或备用网关设了、主网关没设);
  *    出路 = 设 `MODEL_GATEWAY_BASEURL`,或(目录视图)给条目自己的 `baseUrl` / (env 视图)挂 anthropic 路由、或不设 `MODEL_ID` 让目录缺省服务;
  *  · `lane_credential_missing` —— 缺的是**车道凭据**:条目的 provider 词是 `anthropic`(用户选的是 anthropic 车道),
  *    却因 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 都没有而没装上 anthropic 路由、落进了 openai 腿,那条腿又没有端点;
- *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给);
- *  · `none` —— 这份配置能派发到的每一条 openai 兼容路由都解析得到端点。
+ *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给)。
  *
- * **声明序 = 语义序**(缺口两词在前,`none` 最后);加一词 ⇒ 所有穷举 switch 当场编译红。
+ * **声明序 = 语义序**;加一词 ⇒ 所有穷举 switch 当场编译红。
  */
-export declare const MODEL_ROUTE_GAP_WORDS: readonly ["endpoint_missing", "lane_credential_missing", "none"];
+export declare const MODEL_ROUTE_GAP_WORDS: readonly ["endpoint_missing", "lane_credential_missing"];
 export type ModelRouteGap = (typeof MODEL_ROUTE_GAP_WORDS)[number];
-/** 有缺口的那两词(判决的结构化形只在有缺口时存在,`none` = 判决为 `undefined`)。 */
-export type ModelRouteGapBreach = Exclude<ModelRouteGap, "none">;
 /**
  * 拒因给出的**本机网关显式写法**。`src/` 里本机 8000 那个字面的**唯一**住处 —— 源码门钉在
  * `test/config-gateway-endpoint-required.test.ts` ⑧(出现在别处 = 有人又在铸缺省)。
@@ -107,8 +104,8 @@ export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView,
 /** S-768:部署级判决的结构化形 —— 码与拒因句由**同一次**判决给出(一个不变量 id 两个码,组拒码在判决那刻当数据带出,不从句子里抠)。 */
 export interface ModelRouteEndpointVerdict {
     readonly code: typeof GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE | typeof MODEL_ROUTE_ENDPOINT_MISSING_CODE;
-    /** 出路轴({@link MODEL_ROUTE_GAP_WORDS} 的缺口两词):同一次判决给出,不从句子或码里反推(`lane_credential_missing` 与 `endpoint_missing` 共用一个码)。 */
-    readonly gap: ModelRouteGapBreach;
+    /** 出路轴({@link MODEL_ROUTE_GAP_WORDS}):同一次判决给出,不从句子或码里反推(`lane_credential_missing` 与 `endpoint_missing` 共用一个码)。 */
+    readonly gap: ModelRouteGap;
     readonly reason: string;
 }
 /**

package/dist/model-route-endpoint.js

@@ -1,14 +1,11 @@
-import { brainLaneFor, catalogBrainLane, routeTableOf } from "./model-provider.js";
+import { brainLaneFor, catalogBrainLane, declaredRootUrl, routeTableOf } from "./model-provider.js";
 import { DEFAULT_MODEL_REF, servedModelTableLeg } from "./model-select.js";
 export const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 export const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
-export const MODEL_ROUTE_GAP_WORDS = ["endpoint_missing", "lane_credential_missing", "none"];
+export const MODEL_ROUTE_GAP_WORDS = ["endpoint_missing", "lane_credential_missing"];
 export const LOCAL_GATEWAY_HINT = "MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1";
-function declared(url) {
-    return url !== undefined && url.trim() !== "" ? url : undefined;
-}
 export function openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl) {
-    return declared(routeBaseUrl) ?? declared(gatewayBaseUrl);
+    return declaredRootUrl(routeBaseUrl) ?? declaredRootUrl(gatewayBaseUrl);
 }
 function unresolvedRouteLabel(name, provider) {
     return catalogBrainLane(provider) === "anthropic"
@@ -23,7 +20,7 @@ export function modelRouteEndpointRefusal(view, leg) {
     return judgeModelRouteEndpoint(view, leg)?.reason;
 }
 export function judgeModelRouteEndpoint(view, leg) {
-    const gateway = declared(view.gatewayBaseUrl);
+    const gateway = declaredRootUrl(view.gatewayBaseUrl);
     if (gateway === undefined && view.gatewayFallbackUrls.length > 0) {
         const reason = (`env MODEL_GATEWAY_FALLBACK_URLS is set but MODEL_GATEWAY_BASEURL is not [${GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE}] — ` +
             "the fallback URLs are mirrors of the primary gateway (same provider, same account, same key scope), tried only " +

package/dist/model-route-env.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@sema-agent/server/model-route-env` —— 模型路由 env 读法的**精选入口**(纯数据 + 纯函数;import 不写文件、不起句柄、不装监听器、不出声 —— 依赖的包在装载时读自己的环境变量不在此列)。
+ *
+ * 为什么有这只文件:引擎(core)是 BYOM —— 它只吃调用方交的路由表与 `baseUrl` / `apiKey`,从不读 `MODEL_*` / `ANTHROPIC_*` 这些 env 键。
+ * 「env 里哪几把键是模型路由、空串算不算设了、provider 怎么推断、这只模型走哪条车道、这条车道的端点 / 凭据取哪一对键」的读法属本服务,
+ * 在引擎起之前就要答这句话的调用方(壳首启、客户端运行时、sdk 转口)读这一只,不各抄一份键名与车道判。
+ *
+ * 为什么是子路径而不是包根:包根的依赖闭包是整台服务(存储、HTTP、沙箱……),这里只需要一张键表和几只纯函数;
+ * 值依赖仅 `@sema-agent/core`(车道判词)与 `@sema-agent/settings-schema`,仓内只有四只纯叶(`test/model-route-env-port.test.ts` 钉死)。
+ *
+ * 为什么是精选而不是把 `model-route-gap.ts` 整只暴露:那个模块里还有起服自己的读法助手(逗号串分词、cheap 槽铸 id)。把它们变成公开面,等于替实现细节背上 semver。
+ * 要加名字 = 改这只文件 + 同批改 `test/model-route-env-port.test.ts` 的闭集(新增公开面必须是一次有意的动作)。
+ *
+ *  · `MODEL_ROUTE_ENV_KEYS` —— 九把路由 env 键的闭表(字段名 → 键名);
+ *  · `readModelRouteEnv(env)` —— 读口:`env` 交整张 `Record<string, string | undefined>`(`process.env` 或等价快照),只按表点名取值;
+ *  · `envLaneTable(mainId, main, cheap)` —— env 腿的条目表(别名 `default` + 主槽 id + cheap 槽 id);
+ *  · `laneAndEndpointFor(env, model, routes)` —— 值级端口:车道 + 端点 / 凭据的键名(不含任何 env 值)。
+ */
+export { MODEL_ROUTE_ENV_KEYS, readModelRouteEnv, envLaneTable, laneAndEndpointFor } from "./model-route-gap.js";
+export type { EnvCheapSlot, LaneAndEndpoint, ModelRouteEnv, ModelRouteEnvName, ModelRouteEnvReading, ModelRouteSubject } from "./model-route-gap.js";
+export type { ModelBrainLane } from "./model-provider.js";
+//# sourceMappingURL=model-route-env.d.ts.map

package/dist/model-route-env.js

@@ -0,0 +1,2 @@
+export { MODEL_ROUTE_ENV_KEYS, readModelRouteEnv, envLaneTable, laneAndEndpointFor } from "./model-route-gap.js";
+//# sourceMappingURL=model-route-env.js.map