@sema-agent/server 7.100.0 → 7.101.1

package/dist/http/routes/side-query.js

@@ -1,6 +1,7 @@
 import { expandTiers, isThinkingLevel } from "@sema-agent/core";
 import { HttpError } from "../../security.js";
-import { isModelAllowlisted } from "../../model-select.js";
+import { isModelAllowlisted, matchCatalogModel, refusedCatalogEntry, selectableCatalog } from "../../model-select.js";
+import { modelUnavailableMessage } from "../../model-entry-refusal.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, httpErrorCode, msg } from "../send.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
@@ -68,9 +69,14 @@ export async function handleSideQuery(req, res, match, ctx) {
                     return;
                 }
                 if (typeof body.model === "string" && body.model.length > 0) {
-                    const bare = deps.config.models ?? {};
-                    const catalog = expandTiers(bare, deps.config.tiers ?? {}) ?? bare;
-                    if (!isModelAllowlisted(body.model, catalog, deps.config.atModelAllowlist)) {
+                    const catalog = selectableCatalog(deps.config.models ?? {}, deps.config.tiers, deps.config.modelRefusals);
+                    const unavailable = matchCatalogModel(body.model, catalog, deps.config.modelRefusals) === undefined ? refusedCatalogEntry(body.model, deps.config.modelRefusals) : undefined;
+                    if (unavailable !== undefined) {
+                        const message = modelUnavailableMessage("model", body.model.slice(0, 120), unavailable.name, unavailable.refusal);
+                        sendError(res, 400, "request.model_unavailable", message);
+                        return;
+                    }
+                    if (!isModelAllowlisted(body.model, catalog, deps.config.atModelAllowlist, deps.config.modelRefusals)) {
                         sendError(res, 400, "request.model_not_allowed", `model is not in this deployment's @-mention allowlist: "${body.model.slice(0, 120)}" — the allowlist is configured by the operator (config-center models.atModelAllowlist)`);
                         return;
                     }

package/dist/instruction-source-notice.d.ts

@@ -0,0 +1,97 @@
+/**
+ * S-690 —— 项目指令文件**换源**通告(`engine_notice` 码 `instructions.source_changed`)的唯一铸点与基线属主口。
+ *
+ * ## 这件事为什么归本仓
+ * 选哪一份指令文件是**部署的内容半场**(`project-memory.ts` 的 `INSTRUCTION_FILE_CHAIN`;core 的 `loadProjectMemory`
+ * 契约逐字「core … NEVER hardcodes a filename」),所以「这一 run 读的是哪一份、上一 run 读的是哪一份」也只有本仓
+ * 答得出。core 的 run 内变更车道(`steering_injected`,`source: "instructions_change"`)只跟**本 run 自己声明的**
+ * 来源比,进程重启(= 升级)后没有任何东西记得上一 run 注入的是哪一份 —— 于是两文件并存的仓升级后静默换源
+ * (车MN 收车档 §1.5,判据 G6)。
+ *
+ * ## 基线 = 会话的服务端元数据
+ * 基线是「同一 session 上一次 run 选中的链成员相对路径」(不是指纹:指纹密钥每进程随机,跨进程不可比)。它住在会话店的
+ * 服务端元数据面 —— SQL 两孪生是 `session_meta.instruction_source` 一列,local 文件店是一只 sidecar —— 所以重启 /
+ * 跨副本都读得到、随会话删除一起消失,且不进模型上下文、不进 wire 会话面。不接这张面的店(core 的内存 dev 店、
+ * `run-local` 的 core 文件店)⇒ 席缺席 ⇒ 一帧不发(诚实缺席:那两形的会话本来就活不过进程,或没有会话流可投)。
+ *
+ * ## 铸点(唯一)
+ * {@link announceInstructionSource} 是本码**唯一**的铸点(`@contract instructions.source_changed.single_mint`)。
+ * 调用点只有一处:`makeLoadProjectMemory` 在每次**走了指令链**的 prepare 载入完成之后(core 每个 run 恰调一次 `loadProjectMemory`)
+ * ⇒ 一 run 至多一帧。走链之前就判「这次没有项目可读」的 prepare(无手场景、cwd 不是本机绝对目录)是**不适用**,不是
+ * 「来源 = 无」—— 不进本铸点,基线保持上一次真读的那份(O6,7.101.0 合并复审:无手孪生 Runner 与主 Runner 共用同一只
+ * loader 与会话店,把不适用折成 `null` 会让「默认 → 无手 → 默认」同 session 两跳无端发两帧)。分工照 `task-mcp.ts` `mintInjectionDropNotices` 的先例:本模块铸通告,`emit` 由装配方给
+ * (部署的 `onNotice` 转发体 —— 先日志后分流,白名单 / 归属 / 消毒 / 隔离四件判据一个不绕)。
+ *
+ * ## 不做的事
+ * 不区分「升级换源」与「用户改了文件」(跨进程指纹不可比;载荷只说前后两个来源)。detail 没有 `runId`:铸点在 core 的
+ * `loadProjectMemory` 席内,该席的 ctx 不带 runId(core 7.30.1 键集 = cwd / handsEnabled / isSubagent / agentName /
+ * sessionId / phase)—— 与 `mcp.injection_dropped`「装配期铸、无 runId」同形,run 归属由投递腿承载(这条 run 的 SSE /
+ * 这条 run 的账本)。向 core 要 ctx 加 runId 已登记为未闭环项。
+ */
+import type { EngineNotice } from "@sema-agent/core";
+import type { ServerNoticeCode } from "./trace/engine-notice-wire.js";
+export declare const INSTRUCTION_SOURCE_CHANGED: ServerNoticeCode;
+/** 基线读数。`recorded: false` = 这个会话还没有任何 run 记过基线(首 run ⇒ 只写不发);`source: null` = 记过,且那一次
+ *  没有项目指令文件被选中。两态必须可判别:把「没记过」读成「记过没有」会让新会话首 run 发一帧 `null → CLAUDE.md`。 */
+export type InstructionSourceBaseline = {
+    readonly recorded: false;
+} | {
+    readonly recorded: true;
+    readonly source: string | null;
+};
+/** 基线属主口(会话店的服务端元数据面)。 */
+export interface InstructionSourceStore {
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * 覆写基线 —— **CAS**:只在店里此刻的基线仍等于 `expected`(调用方读到的那一份)时写,否则什么都不做(不抛)。
+     * 为什么是 CAS(codex che-NM r1 [high]):铸点对基线读写有期限,超期的写会**晚到**;不带期望值的覆写会让一个
+     * 基于过期读数的旧 run 盖掉更新的 run 写下的基线,下一 run 于是比错。会话行不存在 ⇒ 同样不写。
+     * 写**没有提交**必须抛(SQL 的写本来就如此;local sidecar 回滚内存再抛)—— 「内存已前进而盘没跟上」会让同来源的
+     * 后续 run 在相等比较上短路、再也不重写,重启后比的是一份过期的盘(codex che-NM r1 [medium])。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+}
+/** 一只装配好的席:基线店 + 通告出口。 */
+export interface InstructionSourceSeat {
+    readonly store: InstructionSourceStore;
+    readonly emit: (notice: EngineNotice) => void;
+}
+/**
+ * 基线的**存储编码**(SQL 列与 local sidecar 同一只):「没有项目指令文件」存成空串,链成员存它的相对路径;
+ * 「没记过」是 SQL `NULL` / sidecar 里缺键。空串不会与任何文件名撞(没有叫空名的文件),所以不需要保留词。
+ */
+export declare function encodeInstructionSource(source: string | null): string;
+/** 两份基线读数是否同一(CAS 的判等;三店与测试夹具同用这一只)。 */
+export declare function sameInstructionSourceBaseline(a: InstructionSourceBaseline, b: InstructionSourceBaseline): boolean;
+/** {@link encodeInstructionSource} 的逆。非串非空的值 = 这一格被本仓以外的东西写坏了 ⇒ 抛(调用方按基线读不出处置)。 */
+export declare function decodeInstructionSource(raw: unknown): InstructionSourceBaseline;
+/**
+ * 会话店是否提供基线面 —— **两个方法都在**才算(只有一半的店让读写不同源,比整张缺席更坏)。结构判而不是按类名判
+ * (包装店 `CachingSessionStore` 逐方法转发,判据看的是能力不是名字)。
+ */
+export declare function instructionSourceStoreOf(sessionStore: unknown): InstructionSourceStore | undefined;
+/** 装配点的唯一口(server boot 与 run-local 两处同走):店没有基线面或没有通告出口 ⇒ 席缺席(一帧不发)。 */
+export declare function createInstructionSourceSeat(sessionStore: unknown, emit: ((notice: EngineNotice) => void) | undefined): InstructionSourceSeat | undefined;
+/**
+ * 基线每一次读 / 写的期限(codex che-NM r1 [high])。铸点跑在 prepare 里、loader 等它交出答案才返回,而两支 SQL 孪生的
+ * 查询默认没有超时(MySQL 无、PG `statement_timeout` 缺省关)—— 一次卡住的行锁 / 连接就会把整个 prepare 挂住,而修前
+ * loader 根本不碰库。两层同一个数:① 这里放手(超期 ⇒ 按读 / 写失败处置,留痕放行);② 两支 SQL 孪生的基线查询带**每查询
+ * 超时**(codex che-NM r2 [high];S-9 `write-behind-counter.ts` 先例:mysql2 `{sql, timeout}` / pg `query_timeout`,pg-pool
+ * 超时即销毁那条连接)—— 只放手不截断,卡住的查询会一直占着池里的连接。超期后仍在飞的写由 CAS 挡住,不会盖掉更新的基线。
+ * 数值与 core 给 `probeInstructionSources` 的 2s 天花板同量级:一行 PK 读写在健康库上是毫秒级。
+ */
+export declare const BASELINE_IO_DEADLINE_MS = 2000;
+/**
+ * **唯一铸点**:本次 prepare 选中的来源 `current`(链成员相对路径;没有 = `null`)与基线比。
+ *  · 没有基线 ⇒ 只写不发(新会话首 run);
+ *  · 相同 ⇒ 什么都不做(不写);
+ *  · 不同 ⇒ 铸一帧、再以读到的基线为期望值 CAS 覆写。
+ * 基线读 / 写各有 {@link BASELINE_IO_DEADLINE_MS} 的期限。
+ *
+ * 失败方向(F 类,`server.instruction-source.announce-degraded`,detail 带 `op=read|write|emit`):通告是**披露**面
+ * 不是执法面,所以基线读 / 写 / 出口失败一律留痕后放行,**绝不**抛回调用方 —— 抛回去会让 core 把这次 prepare 的项目记忆整块丢掉(loader 抛 ⇒ 不注入),
+ * 为一条通告赔上模型要读的指令本身。读失败 ⇒ 本 run 不比也不写;写失败 ⇒ 本 run 的帧照发(它对本 run 为真),代价是
+ * 下一 run 可能再说一遍同一次换源;出口抛(转发体今天结构上不抛,守的是「本函数不抛」这条契约)⇒ 本 run 缺这一帧。
+ */
+export declare function announceInstructionSource(seat: InstructionSourceSeat, sessionId: string, current: string | null): Promise<void>;
+//# sourceMappingURL=instruction-source-notice.d.ts.map

package/dist/instruction-source-notice.js

@@ -0,0 +1,78 @@
+import { recordFailOpen } from "./observability/fail-open.js";
+export const INSTRUCTION_SOURCE_CHANGED = "instructions.source_changed";
+export function encodeInstructionSource(source) {
+    return source ?? "";
+}
+export function sameInstructionSourceBaseline(a, b) {
+    if (!a.recorded || !b.recorded)
+        return a.recorded === b.recorded;
+    return a.source === b.source;
+}
+export function decodeInstructionSource(raw) {
+    if (raw === null || raw === undefined)
+        return { recorded: false };
+    if (typeof raw !== "string")
+        throw new TypeError(`instruction_source holds a ${typeof raw}, not a string`);
+    return { recorded: true, source: raw === "" ? null : raw };
+}
+export function instructionSourceStoreOf(sessionStore) {
+    const s = sessionStore;
+    if (typeof s?.readInstructionSource !== "function" || typeof s.recordInstructionSource !== "function")
+        return undefined;
+    return { readInstructionSource: s.readInstructionSource.bind(s), recordInstructionSource: s.recordInstructionSource.bind(s) };
+}
+export function createInstructionSourceSeat(sessionStore, emit) {
+    const store = instructionSourceStoreOf(sessionStore);
+    return store && emit ? { store, emit } : undefined;
+}
+const describeSource = (source) => source ?? "no project instruction file";
+export const BASELINE_IO_DEADLINE_MS = 2_000;
+class BaselineDeadlineExceeded extends Error {
+}
+function withinDeadline(op) {
+    const running = Promise.resolve().then(op);
+    running.catch(() => undefined);
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new BaselineDeadlineExceeded(`no answer within ${BASELINE_IO_DEADLINE_MS}ms`)), BASELINE_IO_DEADLINE_MS);
+        timer.unref?.();
+    });
+    return Promise.race([running, deadline]).finally(() => clearTimeout(timer));
+}
+export async function announceInstructionSource(seat, sessionId, current) {
+    let baseline;
+    try {
+        baseline = await withinDeadline(() => seat.store.readInstructionSource(sessionId));
+    }
+    catch (e) {
+        degraded("read", sessionId, e);
+        return;
+    }
+    if (baseline.recorded && baseline.source === current)
+        return;
+    if (baseline.recorded) {
+        const previous = baseline.source;
+        try {
+            seat.emit({
+                code: INSTRUCTION_SOURCE_CHANGED,
+                message: `Project instructions for this run come from ${describeSource(current)}; the previous run of this session read ${describeSource(previous)}.`,
+                detail: { previous, current, sessionId },
+                sessionId,
+            });
+        }
+        catch (e) {
+            degraded("emit", sessionId, e);
+        }
+    }
+    try {
+        await withinDeadline(() => seat.store.recordInstructionSource(sessionId, baseline, current));
+    }
+    catch (e) {
+        degraded("write", sessionId, e);
+    }
+}
+function degraded(op, sessionId, e) {
+    const why = e instanceof BaselineDeadlineExceeded ? `timeout=${BASELINE_IO_DEADLINE_MS}ms` : `err=${e instanceof Error ? e.message : String(e)}`;
+    recordFailOpen("server.instruction-source.announce-degraded", `op=${op} session=${sessionId} ${why}`);
+}
+//# sourceMappingURL=instruction-source-notice.js.map

package/dist/memory-layer-legacy-lock.d.ts

@@ -0,0 +1,14 @@
+import type { EngineNotice } from "@sema-agent/core";
+import type { ServerNoticeCode } from "./trace/engine-notice-wire.js";
+export declare const MEMORY_LAYER_LOCKED_LEGACY: ServerNoticeCode;
+/** 探测读数:锁住的层名(排序)+ 看不全的目录条数。挂载面不存在(新数据根)⇒ 两者皆空。 */
+export interface LockedLegacyLayerProbe {
+    readonly layers: readonly string[];
+    readonly unreadable: number;
+}
+export declare function probeLockedLegacyMemoryLayers(memoryDir: string): LockedLegacyLayerProbe;
+/** 锁住的层 ⇒ 一条通告(纯数据);没有 ⇒ `undefined`。detail 两键:`layers`(层名)与 `remedy`(同一句 `chmod -R u+w <memoryDir>`)。 */
+export declare function buildMemoryLayerLockedLegacyNotice(memoryDir: string, layers: readonly string[]): EngineNotice | undefined;
+/** boot 期的唯一调用口:探测一次、有锁住的层就经 `emit` 发一条;看不全的子树走 F 类留痕。不抛(不拒启)。 */
+export declare function announceLockedLegacyMemoryLayers(memoryDir: string, emit: (notice: EngineNotice) => void): void;
+//# sourceMappingURL=memory-layer-legacy-lock.d.ts.map

package/dist/memory-layer-legacy-lock.js

@@ -0,0 +1,74 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { recordFailOpen } from "./observability/fail-open.js";
+export const MEMORY_LAYER_LOCKED_LEGACY = "memory.layer_locked_legacy";
+const OWNER_WRITE = 0o200;
+function shellQuoted(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+const isMissing = (err) => err?.code === "ENOENT";
+function treeHasLockedDir(dir, gaps) {
+    let st;
+    try {
+        st = lstatSync(dir);
+    }
+    catch (err) {
+        if (!isMissing(err))
+            gaps.n += 1;
+        return false;
+    }
+    if (!st.isDirectory())
+        return false;
+    if ((st.mode & OWNER_WRITE) === 0)
+        return true;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (!isMissing(err))
+            gaps.n += 1;
+        return false;
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && treeHasLockedDir(join(dir, e.name), gaps))
+            return true;
+    }
+    return false;
+}
+export function probeLockedLegacyMemoryLayers(memoryDir) {
+    const gaps = { n: 0 };
+    let top;
+    try {
+        top = readdirSync(memoryDir, { withFileTypes: true });
+    }
+    catch (err) {
+        return { layers: [], unreadable: isMissing(err) ? 0 : 1 };
+    }
+    const layers = top.filter((e) => e.isDirectory() && treeHasLockedDir(join(memoryDir, e.name), gaps)).map((e) => e.name);
+    return { layers: layers.sort(), unreadable: gaps.n };
+}
+export function buildMemoryLayerLockedLegacyNotice(memoryDir, layers) {
+    if (layers.length === 0)
+        return undefined;
+    const remedy = `chmod -R u+w ${shellQuoted(memoryDir)}`;
+    const one = layers.length === 1;
+    return {
+        code: MEMORY_LAYER_LOCKED_LEGACY,
+        message: `memory layer${one ? "" : "s"} ${layers.map((l) => JSON.stringify(l)).join(", ")} ${one ? "still carries" : "still carry"} the read-only permission bits ` +
+            "an engine from 7.30.x or earlier (a server replica at 7.100.0 or earlier) sets on every layer it mounts read-only — deleting an " +
+            "entry there (memory erase / origin clear) fails for a server that does not run as root: the request answers 500, its journal " +
+            `stays on disk and this replica's next start fails. Run \`${remedy}\` once no such engine still runs on this store (an older ` +
+            "replica sets the bits again whenever it mounts a layer read-only). Starting anyway.",
+        detail: { layers: [...layers], remedy },
+    };
+}
+export function announceLockedLegacyMemoryLayers(memoryDir, emit) {
+    const probe = probeLockedLegacyMemoryLayers(memoryDir);
+    if (probe.unreadable > 0)
+        recordFailOpen("server.memory.locked-layer-probe-partial", `unreadable=${probe.unreadable}`);
+    const notice = buildMemoryLayerLockedLegacyNotice(memoryDir, probe.layers);
+    if (notice !== undefined)
+        emit(notice);
+}
+//# sourceMappingURL=memory-layer-legacy-lock.js.map

package/dist/memory-operator-faces.js

@@ -1,6 +1,5 @@
 import { MemoryEngine, } from "@sema-agent/core";
 import { memoryMountRootOf } from "./memory-scope.js";
-import { memoryLayerWriteRefusal } from "./memory-layer-preflight.js";
 export function backendOwnsControlPlane(backend) {
     const b = backend;
     return typeof b?.controlPlaneRoot === "string" && b.controlPlaneRoot !== "";
@@ -41,7 +40,6 @@ function erasureEnvelopeRefusal(input, allowedScopes) {
 export function createMemoryComplianceFaces(store, opts) {
     if (!backendOwnsControlPlane(store.backend))
         return undefined;
-    const mountRoot = memoryMountRootOf(store.backend, store.root);
     const engine = new MemoryEngine({
         backend: store.backend,
         memoryDir: memoryMountRootOf(store.backend, store.root),
@@ -59,14 +57,6 @@ export function createMemoryComplianceFaces(store, opts) {
             const refusal = erasureEnvelopeRefusal(input, opts?.allowedScopes);
             if (refusal !== undefined)
                 return Promise.reject(refusal);
-            try {
-                const locked = memoryLayerWriteRefusal(mountRoot);
-                if (locked !== undefined)
-                    return Promise.reject(locked);
-            }
-            catch (err) {
-                return Promise.reject(err);
-            }
             return engine.eraseMemoryEntries(input);
         },
     };
@@ -74,7 +64,6 @@ export function createMemoryComplianceFaces(store, opts) {
 export function createMemoryOriginFaces(store, opts) {
     if (!backendOwnsControlPlane(store.backend))
         return undefined;
-    const mountRoot = memoryMountRootOf(store.backend, store.root);
     const engine = new MemoryEngine({
         backend: store.backend,
         memoryDir: memoryMountRootOf(store.backend, store.root),
@@ -84,12 +73,7 @@ export function createMemoryOriginFaces(store, opts) {
     return {
         listExternal: (scopes) => engine.listExternalOriginEntries(scopes),
         listClearances: () => engine.listOriginClearances(),
-        clear: async (entryId, input) => {
-            const locked = memoryLayerWriteRefusal(mountRoot);
-            if (locked !== undefined)
-                throw locked;
-            return engine.clearEntryOrigin(entryId, input);
-        },
+        clear: (entryId, input) => engine.clearEntryOrigin(entryId, input),
     };
 }
 export function createSessionMemoryStatusFace(store, opts) {

package/dist/memory-store-refusal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * core 7.31.1 #1094 —— **`memory.target_outside_store`** 在本仓的唯一读法属主(纯叶:零 http / 零 boot 依赖)。
+ *
+ * ## 这个码说的是什么(core `docs/wire-consumption/7.31.1.md` 逐 face 表,tag v7.31.1 亲读)
+ * 记忆 store 里的一个目录经软链通到了 store **外**(或 store 根在 backend 打开 / 引擎首次挂载之后被改指)⇒ 引擎对落点在外的
+ * 删 / 写 / 重放 / 自身写一律**不做**,抛普通 `Error` + `.code`(文案以码领头,点名动作、路径、解析到哪)。core 的读法原话:
+ * operator 要处置的拒(去掉那只目录链),**不是**可重试的 IO 故障,也**不是**对调用方的裁决;链去掉之前重发恒拒。
+ *
+ * ## 两条到达车道,两个读者(本模块各给一只,别处不许再写第二份判据)
+ *  ① **抛出面**(抹除 / 出处 / 外源列表 / 清标 / bundle 导出导入 —— 凡触 store 树的 backend 面):`.code` 就是码
+ *     ⇒ {@link targetOutsideStoreOf}。HTTP 映射在 `http/memory-store-refusal-reply.ts`(409,一处字面量)。
+ *  ② **报告面**(harvest `incident`):core 契约写明 report 车道上码**只在文本里** —— `sidecar_corrupt` 的 detail 恰两种形
+ *     `memory commit refused: memory.target_outside_store: …` / `memory control plane refused: memory.target_outside_store: …`
+ *     (core `docs/wire-consumption/7.31.1.md` 的 harvest 行逐字)⇒ {@link targetOutsideStoreInIncident} 只认**这两个 lead 紧跟码**
+ *     的位置:lead 与码都是 core 铸的字面,路径与引用数据全在码之后。🔴 不做全文子串找(codex 一审 C2:一条真控制面损坏若在
+ *     它引用的坏数据里恰好带着这串字,子串找会把它标成目录链 —— 两者运维动作相反)。不读散文、不猜语义;结构化码位
+ *     (`HarvestReport.incident` / `.warnings` 带码)是向 core 索取的欠账。
+ *     ⚠️ 同一拒的**还原类**(缺失文件还原 / 只读层还原 / `MEMORY.md` 写)只进 `HarvestReport.warnings`(可以 `ok:true`、无 incident),
+ *     那几行的前缀是**条目路径**(模型可写)—— 本仓今天不读 warnings 车道(既有面,不是本批回归),也不在模型可写的文本上
+ *     找码;这一半候 core 的结构化码位(登记在案,codex 一审 C3)。
+ *
+ * ## 不是这个码的三形(core 同表「different surface」,本仓**不**自拼码,如实走各自既有臂)
+ *  · journal 重放目标目录成链 ⇒ `ControlPlaneCorruptError`(无 `.code`,KL-1094-b)⇒ 路由 typed 500 `internal.memory_control_plane_corrupt`;
+ *  · 引擎原地写撞硬链(nlink>1)⇒ 文本 `has N names (a hard link)`、无码(KL-1094-g / #1105)⇒ 走该写点既有的失败车道(harvest
+ *    warnings / 挂载失败),抛出面够不着;
+ *  · 解析故障(`EACCES` / `ELOOP` / `ENOTDIR`)⇒ 以 errno 本身抛 ⇒ 路由未分类 500 + 运维 warn(`String(err)` 带 core 补救句)。
+ */
+/** core 的码(`src/core/memory-engine/layout.ts` `TARGET_OUTSIDE_STORE`;core 不在包根导出它,本常量是它在本仓的唯一写点)。 */
+export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+/** 抛出面:`err` 是这一拒 ⇒ 原样交回(已窄化成 `Error`,调用方要它的 `message`);否则 `undefined`。形 = core 的 `Error` + `.code`。 */
+export declare function targetOutsideStoreOf(err: unknown): Error | undefined;
+/** 报告面:harvest `incident` 是这一拒 ⇒ 码;否则 `undefined`(真控制面损坏的 `sidecar_corrupt` 走这一臂 —— 不被说成链)。 */
+export declare function targetOutsideStoreInIncident(incident: {
+    readonly kind: string;
+    readonly detail: string;
+}): typeof TARGET_OUTSIDE_STORE | undefined;
+//# sourceMappingURL=memory-store-refusal.d.ts.map

package/dist/memory-store-refusal.js

@@ -0,0 +1,14 @@
+export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+export function targetOutsideStoreOf(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const { code } = err;
+    return code === TARGET_OUTSIDE_STORE ? err : undefined;
+}
+const INCIDENT_PREFIXES = [`memory commit refused: ${TARGET_OUTSIDE_STORE}: `, `memory control plane refused: ${TARGET_OUTSIDE_STORE}: `];
+export function targetOutsideStoreInIncident(incident) {
+    if (incident.kind !== "sidecar_corrupt")
+        return undefined;
+    return INCIDENT_PREFIXES.some((p) => incident.detail.startsWith(p)) ? TARGET_OUTSIDE_STORE : undefined;
+}
+//# sourceMappingURL=memory-store-refusal.js.map

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

@@ -0,0 +1,130 @@
+/** 不可用的成因 —— **闭集**(加一个成因 ⇒ {@link MODEL_ENTRY_REFUSAL_CODES} 与 {@link refusalEventOf} 编译红)。 */
+export type ModelEntryRefusalReason = "no_brain" | "entry_invalid";
+/** 机读码(拼法随 `config.*` 家族,按**规则**命名):出现在拒因句的方括号里、warn 字段里、`modelRefusals` 里。 */
+export declare const MODEL_ENTRY_REFUSAL_CODES: {
+    readonly no_brain: "config.model_no_brain";
+    readonly entry_invalid: "config.model_entry_invalid";
+};
+export type ModelEntryRefusalCode = (typeof MODEL_ENTRY_REFUSAL_CODES)[ModelEntryRefusalReason];
+/** 「这张表没有缺省模型」的机读码(S-705;boot 拒启与热路径模型面组拒同一个码)。 */
+export declare const DEFAULT_MODEL_MISSING_CODE = "config.default_model_missing";
+/** 🔴 S-712「被拒的名字被档位 / 别名增广铸到了别的条目上(或读不出被丢条目的名字,无从证明没有)」的机读码
+ *  (不变量 `refused-names-not-minted`;热路径 / boot 首次 apply / dry-run 同一个码)。 */
+export declare const REFUSED_NAME_MINTED_CODE = "config.model_refused_name_minted";
+/**
+ * 一条不可用条目的**事实**(纯数据;`config.modelRefusals[<name>]` 的值)。
+ * 🔴 不含任何值:不含 baseUrl、不含钥匙、不含坏字段的原值 —— 只有成因、码、上游 id(显式选择按 id 形也要命中)、
+ * 坏字段的**键名**,与一句给运维的出路。
+ */
+export interface ModelEntryRefusal {
+    readonly reason: ModelEntryRefusalReason;
+    readonly code: ModelEntryRefusalCode;
+    /** 条目的上游 `id`(壳常按 id 形回读 mainLoopModel —— 按 id 选中同样要拿到拒因,不许落「未知模型」)。 */
+    readonly id: string;
+    /** 条目写的 provider 词(`no_brain` 的主语;`entry_invalid` 时照录,词可能本身就是坏的那一处)。 */
+    readonly provider: string;
+    /** `entry_invalid`:不合形的字段键路径(`contextWindow` / `cost.input` / `api` …);`no_brain` 恒空。 */
+    readonly fields: readonly string[];
+    /** 一句话:为什么不可用 + 出路(不含值)。 */
+    readonly detail: string;
+}
+/** 判据要知道的**部署事实**(不在条目里)。 */
+export interface CatalogEntryVerdictCtx {
+    /** anthropic 路由装上了没有(= `config.anthropic` 在场,`createBrain` 同判)。 */
+    readonly anthropicRouteMounted: boolean;
+}
+/** 条目最小读面(`CenterModel` 与本地投影都结构满足;形判走 settings-schema,不信这张型)。 */
+export interface CatalogEntryLike {
+    readonly name: string;
+    readonly id: string;
+    readonly provider: string;
+}
+/**
+ * **逐条判据**:`undefined` = 本部署能完整服务它。判序即语义:先形(不合形的条目谈不上走哪条腿),再腿。
+ *
+ * 形判的属主是 settings-schema 的 `ModelEntry`(两条读腿用的就是它)—— 本仓不手抄任何一条字段规则;这里只是
+ * 在第二道边界(绕过读腿的输入)上**再问一次同一个属主**,并把答案变成一条带码的拒因。只取 `success` 与 issue
+ * 坐标,不取它的输出(输出会补缺省、剥扩展键,那是读腿的事)。
+ */
+export declare function judgeCatalogEntry(m: CatalogEntryLike, ctx: CatalogEntryVerdictCtx): ModelEntryRefusal | undefined;
+/** 一批已启用条目的判决:可用的(保序)、不可用的(按 catalog name)、以及身份证明不了的被丢条目(坐标)。 */
+export interface CatalogEntriesVerdict<M extends CatalogEntryLike> {
+    readonly usable: readonly M[];
+    readonly refused: Readonly<Record<string, ModelEntryRefusal>>;
+    /** S-712:读腿逐条丢掉、而身份证明不了的条目坐标(`models.3`;载体上不带 `name` 的那些 —— 读腿只在原文档对不上本次解析时
+     *  这样交出,见 `read-warnings.ts` `DroppedModelIdentity`)。非空 ⇒ 不变量 `refused-names-not-minted` 无从成立 ⇒ 模型面组拒。 */
+    readonly unreadable: readonly string[];
+}
+/**
+ * 批量形(模型面 stage 与 dry-run 共用这一只 —— 报数与真 apply 永不撕裂)。
+ * S-712:`dropped` = 读腿交出的被丢条目身份(`EffectiveConfig.models.droppedIdentities`)—— 它们与逐条判据判出的 `entry_invalid`
+ * 是**同一件事**(条目不合 `ModelEntry` 形),只是在第一道边界就被丢了;带名字的铸墓碑,不带名字的(读腿证明不了身份)进
+ * `unreadable`。没有字符串名的坏行读腿已按停用处置、根本不进载体(7.101.0 验修轮 V-2:没有名字就没有可保留的名字)。
+ * 入参按 `unknown` 判形:载体可能来自盘上 LKG(本仓写的,但文件可被改),形不对的一律按证明不了处置(fail-closed)。
+ * 与一条可用 / 已判不可用条目同名时不覆盖(可用条目仍可用;同名撞车由不变量 `refused-names-not-minted` 响亮拒)。
+ */
+export declare function judgeCatalogEntries<M extends CatalogEntryLike>(enabled: readonly M[], ctx: CatalogEntryVerdictCtx, dropped?: unknown): CatalogEntriesVerdict<M>;
+/** 成因 → 它那一条 warn 的事件名(**穷举**)。两个名字是票面点名的既有/新事件,运维的告警规则按名挂。 */
+export declare function refusalEventOf(reason: ModelEntryRefusalReason): "sema_registry_model_no_brain" | "sema_registry_model_entry_invalid";
+/** warn 字段(不含值):`field` = 第一处坏字段(告警规则最常按它分组),`fields` = 全部。 */
+export declare function refusalWarnFields(name: string, r: ModelEntryRefusal): Record<string, unknown>;
+/**
+ * 一次**显式选择**命中了不可用条目时的拒因句(HTTP `request.model_unavailable` 的 `error`、run-local 的 stderr、
+ * hook 选模型的失败文案 —— 各处同一句)。`field` = 调用方的通道名(`model` / `compactionModel` / `agents[0].model` /
+ * `@-mention`),`requested` = 调用方发来的原形(name 或 id),已由调用方截断。
+ */
+export declare function modelUnavailableMessage(field: string, requested: string, name: string, r: ModelEntryRefusal): string;
+/** 缺省模型不变量读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
+export interface DefaultModelView {
+    readonly models: Readonly<Record<string, unknown>>;
+    readonly modelRefusals: Readonly<Record<string, ModelEntryRefusal>>;
+}
+/**
+ * 这张表是从哪条腿来的(闭集 —— 拒因句的出路按腿分:加腿不补 {@link defaultModelRefusal} 的臂 = 编译红)。
+ *  · `env` —— 进程此刻服务的表**没有目录在管**(没配目录 / 目录迟到且无 LKG / 目录的模型面这一组被拒):`MODEL_ID` 是出路之一;
+ *  · `catalog` —— 判的是一份**目录候选**(模型面 stage):目录一旦生效就整张换掉 env 表,`MODEL_ID` 救不了这份候选 ——
+ *    出路只在目录里(修条目 / 换绑)。opus 腿 ④(7.101.0 合并复审):此前两腿同一句,目录腿教「设 MODEL_ID 即可」是假话。
+ */
+export type ModelTableLeg = "env" | "catalog";
+/**
+ * 🔴 S-705 —— **这张模型表有没有一只缺省模型**(`models.default`)。`undefined` = 有。
+ *
+ * 规则只有一句:**进程服务的那张表必须有 `default`**。env 腿(`MODEL_ID`)与目录腿(缺省解析)是它的两个来源,
+ * 任一在场即过;目录一旦生效就整张换掉 env 表,所以判的永远是「生效之后的那张表」—— 这正是它必须在目录应用
+ * **之后**判的理由(此前 `parseModelDomain` 在目录应用之前就对 `MODEL_ID` 空串拒启,把只配了目录的用户无谓拒掉)。
+ *
+ * 拒因一句:码 + 这条腿上**真实**的出路 + 若目录在场但每条都不可用,点名它们与各自的码。env 腿句首保留 `MODEL_ID is required`
+ * 这个既有的可 grep 片段(壳与运维脚本认它);目录腿不提 `MODEL_ID`(见 {@link ModelTableLeg})。
+ */
+export declare function defaultModelRefusal(view: DefaultModelView, leg: ModelTableLeg): string | undefined;
+/** 一个被铸出的被拒名字:`name` = 被拒条目的名字,`target` = 增广把它指向的那条条目,`via` = 它是以什么身份被铸出的。 */
+export interface MintedRefusedName {
+    readonly name: string;
+    readonly target: string;
+    /** `tier-word`(档位词)/ `cc-alias`(CC 别名 → 它的档位)/ `best`(头档别名)/ `catalog-entry`(一条可用条目与它同名)。 */
+    readonly via: string;
+    /** 被拒条目自己的拒因码。 */
+    readonly code: ModelEntryRefusalCode;
+}
+/** 不变量 `refused-names-not-minted` 读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
+export interface RefusedNameView {
+    readonly models: Readonly<Record<string, unknown>>;
+    readonly tiers: Readonly<Record<string, string>>;
+    readonly modelRefusals: Readonly<Record<string, ModelEntryRefusal>>;
+}
+/**
+ * 🔴 S-712 —— 不变量 `refused-names-not-minted` 的判据:**这张表回应的每一个名字(目录键 ∪ core `expandTiers` 增广出来的档位词 /
+ * CC 别名 / `best`)都不是一个被拒条目的名字**。返回撞上的那些(空 = 成立)。
+ *
+ * 为什么是「增广之后」:引擎在构造 / 换装时自己 `expandTiers(models, tiers)`,显式 `model:"sonnet"` 与角色绑定 `advisor→sonnet` 都在
+ * 增广目录上解析。一条条目被拒(不可用 / 被 schema 丢掉)之后它的名字空出来,同名的档位词 / CC 别名就不再被它 shadow,增广把
+ * 那个词铸到另一条条目上 —— 点它的请求被静默换了目的地、端点与账号(gpt-6 腿 F2 / F3,真复现)。判「增广之后」让引擎拿到的目录
+ * **永远没有**被拒名:显式点它落 `request.model_unavailable`(选择面让出名字 + 查拒因表),角色绑定落引擎对未知名的响亮拒。
+ * 可用条目与被拒条目同名(同一个名字发布了两条、其中一条坏的)同样算撞:哪一条才是运维的意思无从判,拒比猜安全。
+ */
+export declare function mintedRefusedNames(view: RefusedNameView): MintedRefusedName[];
+/** 不变量 `refused-names-not-minted` 的拒因句(`undefined` = 成立)。warn 与世代账 / 拒因同一句;逐对明细另走 {@link mintedRefusedNames}。 */
+export declare function refusedNameMintedRefusal(view: RefusedNameView): string | undefined;
+/** 身份证明不了的被丢条目的拒因句(同一不变量同一个码:证明不了的名字无从证明它不被增广铸出)。 */
+export declare function unreadableDroppedRefusal(entries: readonly string[]): string;
+//# sourceMappingURL=model-entry-refusal.d.ts.map