@sema-agent/server 7.137.0 → 7.139.0

package/dist/memory-sync-client.js

@@ -1,99 +1,97 @@
 import { createHash, randomBytes } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rmdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { encodeScopeSegment, syncMemoryScope, } from "@sema-agent/core";
+import { carriesCredential, 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";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
+import { pathBaseUrlRefusal } from "./web-admin-client/center-request.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export function memorySyncPeerOf(url) {
+    const refusal = pathBaseUrlRefusal("memory sync: MEMORY_SYNC_URL", url);
+    if (refusal !== undefined)
+        throw new Error(refusal);
+    const u = new URL(url);
+    const identity = `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+    if (carriesCredential(identity)) {
+        throw new Error("memory sync: MEMORY_SYNC_URL holds a credential (a token-shaped part of its path) — the sync peer identity travels verbatim in every request body and " +
+            "cursor, so it is refused, never cleaned: put the token in MEMORY_SYNC_TOKEN and set MEMORY_SYNC_URL to the central base address itself");
+    }
+    if (identity.length > MEMORY_SYNC_PEER_COLUMN_CHARS) {
+        throw new Error(`memory sync: MEMORY_SYNC_URL normalizes to ${identity.length} characters — the peer identity is the central request's peer, which holds at most ${MEMORY_SYNC_PEER_COLUMN_CHARS}: use a shorter base URL`);
+    }
+    return identity;
+}
+export function buildMemorySyncEnabledFields(peer, scope, cursorPath) {
+    return { peer: buildDisplaySafeUrl(peer), scope, cursorPath };
+}
 export function createMemorySyncTransport(opts) {
-    const base = opts.url.replace(/\/+$/, "");
+    const peer = memorySyncPeerOf(opts.url);
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 60_000;
-    return async (path, body) => {
-        const res = await fetchImpl(`${base}${path}`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        const text = await res.text();
-        if (!res.ok)
-            throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
-        return JSON.parse(text);
-    };
+    return Object.freeze({
+        peer,
+        async post(path, body) {
+            const res = await fetchImpl(`${peer}${path}`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await res.text();
+            if (!res.ok)
+                throw new Error(`memory sync POST ${path}: HTTP ${res.status} ${text.slice(0, 200)}`);
+            return JSON.parse(text);
+        },
+    });
 }
-export function memorySyncCursorPath(memoryRoot, peer, scope) {
-    return join(memoryRoot, "sync-cursors", encodeScopeSegment(peer), `${createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32)}.json`);
+const SYNC_CURSOR_DIR = "sync-cursors";
+function scopeDigest(scope) {
+    return createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 32);
 }
-function legacyMemorySyncCursorPath(memoryRoot, peer) {
-    return join(memoryRoot, `sync-cursor-${encodeScopeSegment(peer)}.json`);
+export function memorySyncCursorPath(memoryRoot, scope) {
+    return join(memoryRoot, SYNC_CURSOR_DIR, `${scopeDigest(scope)}.json`);
 }
-async function loadCursor(path, scope, peer, log) {
+function unusableCursor(scope, path, why) {
+    return new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — the cursor file ${path} cannot be read as a sync cursor (${why}); the layer stays unsynced until the operator picks one of two ways out: ` +
+        "(1) restore the file from a backup; (2) delete it to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
+        "and entries deleted on one side since the last round come back from the other side");
+}
+function cursorOf(parsed) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return "not a JSON object";
+    const c = parsed;
+    const baseRevs = c["baseRevs"];
+    if (baseRevs === null || typeof baseRevs !== "object" || Array.isArray(baseRevs) || !Object.values(baseRevs).every((v) => typeof v === "string" && v.length > 0)) {
+        return "baseRevs is not a map of entry id to a non-empty rev";
+    }
+    const updatedAtMs = c["updatedAtMs"];
+    if (typeof updatedAtMs !== "number" || !Number.isFinite(updatedAtMs))
+        return "updatedAtMs is not a finite number";
+    return { scope: c["scope"], peer: c["peer"], store: c["store"], baseRevs: { ...baseRevs }, updatedAtMs };
+}
+async function loadLayerBaseline(path, scope) {
     let raw;
     try {
         raw = await readFile(path, "utf8");
     }
     catch (err) {
-        if (err.code !== "ENOENT")
-            log.warn("memory_sync_cursor_read_failed", { path, err: String(err), note: "treating as first round" });
-        return undefined;
+        if (err.code === "ENOENT")
+            return { kind: "none" };
+        throw new Error(`memory sync: layer ${JSON.stringify(scope)} not synced — cannot read the cursor file ${path} (${String(err)}); the next round reads it again once it is readable`);
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
-    catch (err) {
-        log.warn("memory_sync_cursor_corrupt", { path, err: String(err), note: "treating as first round" });
-        return undefined;
+    catch {
+        throw unusableCursor(scope, path, "not JSON");
     }
-    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"];
-        if (c["scope"] === scope &&
-            c["peer"] === peer &&
-            typeof c["updatedAtMs"] === "number" &&
-            Number.isFinite(c["updatedAtMs"]) &&
-            baseRevsRaw !== null &&
-            typeof baseRevsRaw === "object" &&
-            !Array.isArray(baseRevsRaw) &&
-            Object.values(baseRevsRaw).every((v) => typeof v === "string" && v.length > 0)) {
-            return { scope, peer, baseRevs: { ...baseRevsRaw }, updatedAtMs: c["updatedAtMs"] };
-        }
-    }
-    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 });
+    const cursor = cursorOf(parsed);
+    if (typeof cursor === "string")
+        throw unusableCursor(scope, path, cursor);
+    return { kind: "cursor", cursor };
 }
 async function saveCursor(path, cursor) {
     await mkdir(dirname(path), { recursive: true });
@@ -101,30 +99,129 @@ async function saveCursor(path, cursor) {
     await writeFile(tmp, JSON.stringify(cursor), "utf8");
     await rename(tmp, path);
 }
+const LEGACY_PEER_SEGMENT = "central";
+const LEGACY_ROOT_CURSOR_FILE = "sync-cursor-central.json";
+function m31Window() {
+    const row = ONE_TIME_MIGRATIONS.find((w) => w.id === "M31");
+    if (row === undefined)
+        throw new Error("memory-sync-client: the one-time migration registry has no M31 row — this migration outlived its registry row; delete it with that row");
+    return row;
+}
+function scopeOfLegacyCursor(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return undefined;
+    const scope = parsed["scope"];
+    return typeof scope === "string" && scope.length > 0 ? scope : undefined;
+}
+export async function relocateSyncCursorsM31(memoryRoot, log, opts) {
+    if (!migrationWindowOpen(opts.window ?? m31Window(), opts.today))
+        return { window: "closed", moved: 0, left: 0 };
+    let moved = 0;
+    let left = 0;
+    const codeOf = (err) => err?.code;
+    const exists = async (path) => {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return false;
+            throw err;
+        }
+    };
+    const move = async (from, to) => {
+        if (await exists(to)) {
+            left += 1;
+            log.warn("memory_sync_cursor_not_relocated", { path: from, to, note: "this layer already has a cursor at its path, so the file written by an earlier version stays where it is and no round reads it; delete it" });
+            return;
+        }
+        await mkdir(dirname(to), { recursive: true });
+        try {
+            await rename(from, to);
+        }
+        catch (err) {
+            if (codeOf(err) === "ENOENT")
+                return;
+            throw err;
+        }
+        moved += 1;
+        log.info("memory_sync_cursor_relocated", { from, to });
+    };
+    const legacyDir = join(memoryRoot, SYNC_CURSOR_DIR, LEGACY_PEER_SEGMENT);
+    let names = [];
+    try {
+        names = await readdir(legacyDir);
+    }
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    for (const name of [...names].sort()) {
+        if (/^[0-9a-f]{32}\.json$/.test(name))
+            await move(join(legacyDir, name), join(memoryRoot, SYNC_CURSOR_DIR, name));
+    }
+    if (names.length > 0) {
+        try {
+            await rmdir(legacyDir);
+        }
+        catch (err) {
+            if (codeOf(err) !== "ENOENT" && codeOf(err) !== "ENOTEMPTY" && codeOf(err) !== "EEXIST")
+                throw err;
+        }
+    }
+    const legacyFile = join(memoryRoot, LEGACY_ROOT_CURSOR_FILE);
+    let raw;
+    try {
+        raw = await readFile(legacyFile, "utf8");
+    }
+    catch (err) {
+        if (codeOf(err) !== "ENOENT")
+            throw err;
+    }
+    if (raw !== undefined) {
+        const scope = scopeOfLegacyCursor(raw);
+        if (scope === undefined) {
+            left += 1;
+            log.warn("memory_sync_cursor_not_relocated", { path: legacyFile, note: "a cursor file written by an earlier version that is not a JSON object naming its scope, so no layer can take it as its baseline; restore it from a backup and restart, or delete it" });
+        }
+        else {
+            await move(legacyFile, memorySyncCursorPath(memoryRoot, scope));
+        }
+    }
+    return { window: "open", moved, left };
+}
 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 now = opts.now ?? Date.now;
     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" });
+            opts.log.warn("memory_sync_layer_enumeration_unsupported", { scope: opts.scope, 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);
+        const cursorPath = memorySyncCursorPath(opts.memoryRoot, scope);
+        const baseline = await loadLayerBaseline(cursorPath, scope);
+        let cursor = baseline.kind === "cursor" ? baseline.cursor : undefined;
         let result;
         let subRound = 0;
         for (;;) {
@@ -133,18 +230,17 @@ export function createMemorySyncRunner(opts) {
                 backend: opts.backend,
                 scope,
                 transport: opts.transport,
-                peer,
                 ...(cursor !== undefined ? { cursor } : {}),
                 ...(opts.now !== undefined ? { now: opts.now } : {}),
                 ...(opts.maxPushEntries !== undefined ? { maxPushEntries: opts.maxPushEntries } : {}),
                 ...(opts.maxPullEntries !== undefined ? { maxPullEntries: opts.maxPullEntries } : {}),
             });
             for (const w of result.warnings ?? [])
-                opts.log.warn("memory_sync_warning", { scope, peer, subRound, warning: w });
+                opts.log.warn("memory_sync_warning", { scope, subRound, warning: w });
             if (!(result.pushTruncated === true || result.pullTruncated === true))
                 break;
             if (subRound >= MAX_SYNC_ROUNDS) {
-                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" });
+                opts.log.warn("memory_sync_rounds_exhausted", { scope, rounds: subRound, note: "truncation flag still set at the round cap — remaining items ride the next trigger" });
                 break;
             }
             if (result.cursorAdvanced && result.cursor !== undefined) {
@@ -156,12 +252,11 @@ export function createMemorySyncRunner(opts) {
                 }
             }
             cursor = result.cursor ?? cursor;
-            opts.log.info("memory_sync_continuation", { reason, scope, peer, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
+            opts.log.info("memory_sync_continuation", { reason, scope, subRound, pushTruncated: result.pushTruncated === true, pullTruncated: result.pullTruncated === true });
         }
         for (const c of result.conflicts) {
             opts.log.warn("memory_sync_conflict", {
                 scope,
-                peer,
                 side: c.side,
                 id: c.id,
                 reason: c.reason,
@@ -180,7 +275,6 @@ export function createMemorySyncRunner(opts) {
         opts.log.info("memory_sync_round", {
             reason,
             scope,
-            peer,
             ok: result.ok,
             cursorAdvanced: result.cursorAdvanced,
             pushedEntries: result.pushed.entries.length,
@@ -191,10 +285,11 @@ export function createMemorySyncRunner(opts) {
         });
         return result;
     };
+    let relocated = false;
     const round = async (reason) => {
-        if (!legacyCursorChecked) {
-            legacyCursorChecked = true;
-            await adoptLegacyCursor(opts.memoryRoot, opts.scope, peer, opts.log);
+        if (!relocated) {
+            await relocateSyncCursorsM31(opts.memoryRoot, opts.log, { today: new Date(now()).toISOString().slice(0, 10) });
+            relocated = true;
         }
         const layers = [];
         const failures = [];
@@ -204,7 +299,7 @@ export function createMemorySyncRunner(opts) {
             }
             catch (err) {
                 failures.push({ scope, err });
-                opts.log.warn("memory_sync_layer_failed", { reason, scope, peer, err: String(err) });
+                opts.log.warn("memory_sync_layer_failed", { reason, scope, cursorPath: memorySyncCursorPath(opts.memoryRoot, scope), err: String(err) });
             }
         }
         if (failures.length > 0) {
@@ -227,7 +322,7 @@ export function createMemorySyncRunner(opts) {
     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) });
+            opts.log.warn("memory_sync_failed", { reason, scope: opts.scope, err: String(err) });
         });
     };
     const trigger = (reason) => {
@@ -244,6 +339,6 @@ export function createMemorySyncRunner(opts) {
         tracked.add(scope);
         queueRound("track");
     };
-    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, peer, scope), pending: () => pending };
+    return { syncOnce, trigger, track, exclusive, cursorPathFor: (scope) => memorySyncCursorPath(opts.memoryRoot, scope), pending: () => pending };
 }
 //# sourceMappingURL=memory-sync-client.js.map

package/dist/memory-sync.d.ts

@@ -2,7 +2,7 @@ import { type MemoryBackend, type MemoryEntry, type PatchReport } from "@sema-ag
 import type { MemorySyncStore } from "./plugins/memory-sync-store-pg.js";
 /** 一轮同步请求(验型后的干净形状——`parseMemorySyncRequest` 是唯一铸造点)。 */
 export interface MemorySyncRequest {
-    /** 对端标识(MemorySyncCursor.peer,per-(scope,peer) 游标分区键)。 */
+    /** 对端标识(`CentralSyncCursor.peer`,per-(scope,peer) 游标分区键)= 客户端 transport 的身份(本仓的客户端腿:规范化的中心基址,`memory-sync-client.ts` `memorySyncPeerOf`)。 */
     peer: string;
     /** 客户端游标的共同基线:id → rev at last completed sync round(空 map = 首轮)。 */
     baseRevs: Record<string, string>;

package/dist/memory-sync.js

@@ -1,5 +1,6 @@
 import { computeEntryRev, MEMORY_ORIGIN_CAUSES, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
+import { MEMORY_SYNC_PEER_COLUMN_CHARS } from "./plugins/memory-key-guards.js";
 export const MEMORY_SYNC_MAX_ENTRIES = 500;
 export const MEMORY_SYNC_MAX_DELETES = 2000;
 export function parseMemorySyncRequest(body, scope) {
@@ -7,8 +8,8 @@ export function parseMemorySyncRequest(body, scope) {
         return { ok: false, error: "body must be a JSON object { peer, baseRevs, entries, deletes }" };
     const b = body;
     const peer = b["peer"];
-    if (typeof peer !== "string" || peer.length === 0 || peer.length > 190)
-        return { ok: false, error: "peer must be a non-empty string of at most 190 characters" };
+    if (typeof peer !== "string" || peer.length === 0 || peer.length > MEMORY_SYNC_PEER_COLUMN_CHARS)
+        return { ok: false, error: `peer must be a non-empty string of at most ${MEMORY_SYNC_PEER_COLUMN_CHARS} characters` };
     const rawBase = b["baseRevs"];
     if (rawBase === null || typeof rawBase !== "object" || Array.isArray(rawBase))
         return { ok: false, error: "baseRevs must be an object mapping entry id → rev (may be empty on the first round)" };

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

@@ -1,23 +1,3 @@
-/**
- * **env 模型路由读数的唯一读口**:`readModelRouteEnv(env)`、env 腿的条目表 `envLaneTable`,与车道值级端口 `laneAndEndpointFor`。
- *
- * ## 形(一只读口、一处调用)
- * 「env 里哪几把键是模型路由、空串 = 未设、provider 的显式 / 推断 / 缺省、env 腿铸哪几个条目槽」的读法只在这里:
- *  · {@link readModelRouteEnv}:`parseModelDomain`(`config.ts`,起服铸 `ServiceConfig` 的路由字段)吃它的读数(`process.env` 与测试快照是同一个入参位);
- *  · {@link envLaneTable}:env 腿的条目名与键序(`parseModelDomain` 铸真 `Model` 表经它);
- *  · {@link laneAndEndpointFor}:值级端口 —— 「这只模型在这张路由表上走哪条车道、这条车道的端点 / 凭据取哪一对 env 键」。车道只经 `brainLaneFor`
- *    (core `brainLaneOf` 对路由表的答案)取,键名取 {@link MODEL_ROUTE_ENV_KEYS};**只交键名不交值**。
- * 路由判据本身(「将要服务的那张表里每条 openai 兼容路由是否解析得到端点」)不在这里:唯一属主是 `model-route-endpoint.ts` 的 `judgeModelRouteEndpoint`,
- * 起服段与 `GET /v1/models.modelPlane` 经 `judgeServedModelRoute` 问它 —— 它们判的是**将要服务的那张表**(env 表或目录表),不是本文件读出的 env 视图。
- *
- * ## 对外
- * 本模块的精选再导出是子路径 `@sema-agent/server/model-route-env`(`src/model-route-env.ts`):引擎 core 是 BYOM(只吃调用方给的路由表,不读这些键),
- * 别仓要在引擎起之前回答「走哪条车道、端点 / 凭据取哪一对键」,读这一只,不各抄一份键名与车道判。
- *
- * ## 纯
- * 不读 `process.env`、不读文件、不枚举快照 —— 只按 {@link MODEL_ROUTE_ENV_KEYS} 点名取值(依赖闭包里没有 `node:*` / `process`,
- * `test/model-route-env-reading.test.ts` 钉)。同入同出;返回值是新对象。provider 词域外的值在这里按引擎派发的口径读作网关腿(`brainLaneFor`:域外词的路由表里没有那个键 ⇒ 引擎路由器落网关 fallback),不在此拒(域外拒启是 `model-provider-word` 那条不变量的事)。
- */
 import { type ModelBrainLane } from "./model-provider.js";
 /**
  * 路由读数读的九把 env 键(**闭表**;{@link readModelRouteEnv} 只碰这几把,测试用代理钉「读集 ⊆ 本表」)。
@@ -59,8 +39,9 @@ export interface ModelRouteEnvReading {
     /** `MODEL_GATEWAY_FALLBACK_URLS` 逐项 trim、丢空项。 */
     readonly gatewayFallbackUrls: string[];
     /**
-     * `MODEL_API_KEY`(网关腿的部署级凭据):**原样**读 —— 与其余各把不同,空串**不**折成未设。brain 装配以**真值**判这把凭据发不发(空串部署一个凭据字节都不发),
+     * `MODEL_API_KEY`(网关腿的部署级凭据):读数**原样**交出 —— 与其余各把不同,空串**不**折成未设:
      * 起服铸的 `ServiceConfig.gatewayApiKey` 逐字保留空串(compose 的 `${VAR:-}` 模板与空 Secret 挂载天天产它);读数改折叠会改变那一位。
+     * 「这把凭据设了没有」的问法不在读数里折,而是消费方问 {@link declaredCredential}(引擎的 `isBlankCredential`:空串与只含空白都 = 没有)。
      * 它只与网关端点配对(没有 {@link gatewayBaseUrl} 就不装载),配对由消费方判。
      */
     readonly gatewayApiKey: string | undefined;
@@ -85,6 +66,9 @@ export interface ModelRouteEnvReading {
     /** cheap 槽铸不铸(见 {@link EnvCheapSlot})。 */
     readonly cheapSlot: EnvCheapSlot;
 }
+/** 一把凭据键「设了没有」的唯一问法(两把 anthropic 键与网关键 `MODEL_API_KEY` 同读):引擎的 `isBlankCredential`(整串 trim 后为空 ⇒ 没有凭据)—— 与引擎对同一个值的读法同一只,
+ *  不自拼第二种「空」:只含空白的 key 旁边的 token 是 bearer(引擎让那只头作凭据照发),不是同设冲突;两把都空白 = 缺席、路由不挂;只含空白的网关 key = 没有部署凭据。 */
+export declare const declaredCredential: (v: string | undefined) => string | undefined;
 /** 逗号串读法的归一点:逐项 trim、丢空项(缺席 = 空串 = `[]`)。本文件的 CSV 路由键与 `config.ts` 的逗号串旋钮(按名薄壳 `csv(name)`)同读这一只;
  *  目录模块的回显分词与 `SERVICE_AUTH_TOKENS` 的 `k=v` 对分词是同形的另两处,尚未改调(清账版收,本函数届时挪到中性模块)。 */
 export declare const csvOf: (raw: string | undefined) => string[];
@@ -98,7 +82,7 @@ export declare function readModelRouteEnv(env: ModelRouteEnv): ModelRouteEnvRead
  *  · `ANTHROPIC_API_KEY`    ⇒ `x-api-key`(只发它);
  *  · `ANTHROPIC_AUTH_TOKEN` ⇒ `Authorization: Bearer`(只发它);
  *  · 两个都设 ⇒ `conflict`:两个名字说的是两种头,哪个赢都是替运维猜(7.135.0 及以前是「AUTH_TOKEN 优先」,x-api-key 被静默丢弃)⇒ 起服拒启,拒句 {@link anthropicCredentialRefusal}。
- * 空串 = 未设(与 {@link readModelRouteEnv} 同尺)。入参是两个名字各自的值 —— env 读数的两位或 `config.anthropic` 的 `apiKey` / `authToken` —— 不读 `process.env`。
+ * 「设了没有」按引擎的 `isBlankCredential` 读(空串与只含空白都 = 未设;与 {@link declaredCredential} 同一只)。入参是两个名字各自的值 —— env 读数的两位或 `config.anthropic` 的 `apiKey` / `authToken` —— 不读 `process.env`。
  * 读者:起服(`config.ts` 的拒启锚与跨键不变量表 `anthropic-credential-exclusive` 同一句)· brain 装配(交引擎哪种头)· hook 直连腿(哪种头、交引擎配对判官的那份值)·
  * 车道端口 {@link laneAndEndpointFor}(哪把键)· 起服的 Bearer 部署诊断(`boot/web-admin.ts`)。
  */

package/dist/model-route-gap.js

@@ -1,3 +1,4 @@
+import { isBlankCredential } from "@sema-agent/core";
 import { brainLaneFor, declaredRootUrl } from "./model-provider.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const MODEL_ROUTE_ENV_KEYS = {
@@ -22,14 +23,15 @@ export function mintedCheapId(slot) {
     }
 }
 const declaredValue = (v) => (v !== undefined && v !== "" ? v : undefined);
+export const declaredCredential = (v) => (v !== undefined && !isBlankCredential(v) ? v : undefined);
 export const csvOf = (raw) => (raw ?? "")
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean);
 export function readModelRouteEnv(env) {
     const K = MODEL_ROUTE_ENV_KEYS;
-    const anthropicApiKey = declaredValue(env[K.anthropicApiKey]);
-    const anthropicAuthToken = declaredValue(env[K.anthropicAuthToken]);
+    const anthropicApiKey = declaredCredential(env[K.anthropicApiKey]);
+    const anthropicAuthToken = declaredCredential(env[K.anthropicAuthToken]);
     const anthropicBaseUrl = declaredValue(env[K.anthropicBaseUrl]);
     const anthropicRouteMounted = anthropicApiKey !== undefined || anthropicAuthToken !== undefined;
     const explicitProvider = declaredValue(env[K.provider]);
@@ -58,8 +60,8 @@ export function readModelRouteEnv(env) {
 }
 export function judgeAnthropicCredential(names) {
     const K = MODEL_ROUTE_ENV_KEYS;
-    const apiKey = declaredValue(names.apiKey);
-    const authToken = declaredValue(names.authToken);
+    const apiKey = declaredCredential(names.apiKey);
+    const authToken = declaredCredential(names.authToken);
     if (apiKey !== undefined && authToken !== undefined)
         return { kind: "conflict" };
     if (apiKey !== undefined)
@@ -111,7 +113,7 @@ export function laneAndEndpointFor(env, model, routes) {
             };
         case "gateway": {
             const endpointDeclared = declaredRootUrl(reading.gatewayBaseUrl) !== undefined;
-            const credentialLoaded = endpointDeclared && reading.gatewayApiKey !== undefined && reading.gatewayApiKey !== "";
+            const credentialLoaded = endpointDeclared && declaredCredential(reading.gatewayApiKey) !== undefined;
             return { lane, endpointEnvName: K.gatewayBaseUrl, endpointDeclared, apiKeyEnvName: credentialLoaded ? K.gatewayApiKey : undefined };
         }
     }

package/dist/mods-declaration.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 部署声明的 mod 包 —— `MODS_ROOT` + `MODS_PACKAGES` 的**唯一读法**,以及部署座装配(`boot/deployment-mods.ts`)全部失败的**唯一词表与拒句**。
+ *
+ * ## 规则(一句)
+ * mod 包只从运维的部署声明装载;声明只说四件宿主的事实 —— 装哪个目录(`dir`)、叫什么(`name`,须与包自己的名逐字同)、站哪一档(`tier`)、
+ * 交给它什么(`options`);包里的三件文件只有引擎一只读者(`loadModPackage`),本仓**不读包内任何文件、不算摘要**。
+ *
+ * ## 声明的形
+ *  · `MODS_ROOT` —— 绝对路径;声明的每只包解析真实路径之后必须**严格**落在它(的真实路径)之下(按路径分量判,不是前缀;根本身不是包目录)。
+ *    单设它而不声明包 = 无事(形照判)。
+ *  · `MODS_PACKAGES` —— JSON 数组,每项闭集四键 `{ name, dir, tier, options? }`:`name` 非空串;`dir` 绝对路径;`tier` ∈ `prepend | user | append`
+ *    (宿主必填 —— 包不自报档;站不站得住由引擎的座 × 档表判,部署座三档都许);`options` 任意 JSON 值,原样交包的 `register`。
+ *    缺席 / 空串 = 不声明(部署座只有本仓自铸的注册,与没有这两根旋钮的版本逐字节同)。
+ *  · `MODS_PACKAGES` 是一份声明、不是凭据值:配置目录只回在场位与长度(不回显);`options` 不是凭据通道 —— 本服务不替包扣凭据(声明与包自己读的环境变量
+ *    都不在自有凭据声明里,宿主车道 `inheritEnv: "all"` 下模型的子进程照样继承)。
+ *
+ * ## 失败(两类,一张闭集词表,一种拒句)
+ *  · **声明 / 文件系统**(本仓判;任何一只包被装载之前,整张声明全部判完):
+ *    `config_invalid`(某一席的形不对 —— 整段 JSON、某一项、`MODS_ROOT`)· `root_missing`(声明了包而 `MODS_ROOT` 没设)·
+ *    `name_missing` · `duplicate_name` · `root_unreadable` · `dir_unreadable` · `outside_root` · `not_a_directory`;
+ *  · **读包者 / 准入**(引擎判,本仓只透传):`package_refused`(读包者拒了这只包)· `name_mismatch`(包自己的名与声明的不同)·
+ *    `admission_refused`(整列交引擎准入被拒)。
+ * 任一失败 = 拒启。拒句一行:`deployment mods refused: <词>(<主语>)[: <细节>]`,整行经出口座 `boot-refusal-line`(剥控制与双向字符、凭据形换记号、
+ * ≤ 512 码元含截断记号)—— 读包者 / 准入的机器码原样留在主语括号里;本仓写的句子不回显声明的值(路径、`options`),主语只点名是哪一席(`MODS_PACKAGES[2]`)
+ * 或哪只包;读包者 / 准入 / 包自己交回的话原样透传(过出口座),其中可能点名包目录 —— 那是运维要的诊断,包本身是受信代码。
+ */
+import type { ModRegistrationTier } from "@sema-agent/core";
+/** 声明的一只包(宿主的四件事实)。 */
+export interface DeclaredModPackage {
+    readonly name: string;
+    readonly dir: string;
+    readonly tier: ModRegistrationTier;
+    /** 缺席 = 声明里没写这一键(交给 `register` 的就是 `undefined`)。 */
+    readonly options?: unknown;
+}
+/**
+ * 部署声明(`loadConfig` 读一次;两只起服入口的装配都读这一份)。两种形,形即律:
+ *  · **没声明包** —— 没有 `packages` 这一席(变量缺席 / 空串 / 显式 `[]` 同一形);`root` 只在单设了 `MODS_ROOT` 时在(形照判、无事,配置目录照回);
+ *  · **声明了包** —— 至少一只,且**必有根**:「有包无根」「有根空表」都不是可表示的值(`root_missing` 只在本模块的读法里判,装配口没有这一臂)。
+ * 读者按 `d.packages === undefined` 分两形(`packages` 是判别位:没声明那一形上它只能缺席)。
+ */
+export type ModsDeclaration = {
+    readonly root?: string;
+    readonly packages?: never;
+} | {
+    readonly root: string;
+    readonly packages: readonly [DeclaredModPackage, ...DeclaredModPackage[]];
+};
+/** 声明里的一席:整根旋钮,或 `MODS_PACKAGES` 的第几项。 */
+export type DeclarationSeat = "MODS_ROOT" | "MODS_PACKAGES" | {
+    readonly entry: number;
+};
+/** 一次失败(词 + 主语 + 细节)。细节只有两种来源:本仓写死的句子,或读包者 / 准入交回的话(过出口座)。**失败词的唯一来源是本联合各成员的 `word`。** */
+export type DeploymentModsRefusal = {
+    readonly word: "config_invalid";
+    readonly seat: DeclarationSeat;
+    readonly why: string;
+} | {
+    readonly word: "root_missing";
+} | {
+    readonly word: "name_missing";
+    readonly entry: number;
+} | {
+    readonly word: "duplicate_name";
+    readonly entry: number;
+    readonly first: number;
+} | {
+    readonly word: "root_unreadable";
+    readonly cause: string;
+} | {
+    readonly word: "dir_unreadable";
+    readonly entry: number;
+    readonly cause: string;
+} | {
+    readonly word: "outside_root";
+    readonly entry: number;
+} | {
+    readonly word: "not_a_directory";
+    readonly entry: number;
+} | {
+    readonly word: "package_refused";
+    readonly name: string;
+    readonly code: string | undefined;
+    readonly reason: string;
+} | {
+    readonly word: "name_mismatch";
+    readonly name: string;
+    readonly packageName: string;
+} | {
+    readonly word: "admission_refused";
+    readonly code: string | undefined;
+    readonly reason: string;
+};
+/** 失败词(拒句的 `<词>`)= 联合成员的 `word`,不另写一份。渲染是穷尽 `switch`(加成员不加臂 = 编译红)。 */
+export type DeploymentModsRefusalWord = DeploymentModsRefusal["word"];
+/** 失败词闭集(运行期全集;「每词至少一格」的钉读它)。 */
+export declare const DEPLOYMENT_MODS_REFUSALS: readonly DeploymentModsRefusalWord[];
+/** 一次失败的拒句(一行;整行经出口座 `boot-refusal-line`:剥控制与双向字符、凭据形换记号、≤ 512 码元含截断记号)。 */
+export declare function buildDeploymentModsRefusalLine(r: DeploymentModsRefusal): string;
+/** 部署座装配的拒启(两只起服入口同一只类型;`refusal` 是机读的那一份,`message` 是它的拒句)。 */
+export declare class DeploymentModsRefusedError extends Error {
+    readonly refusal: DeploymentModsRefusal;
+    constructor(refusal: DeploymentModsRefusal);
+}
+/**
+ * 声明的形(纯函数,`loadConfig` 调;文件系统那一半在装配里):`MODS_ROOT` 的形 → `MODS_PACKAGES` 是不是 JSON 数组 → 逐项(序号升序;每项:是对象 →
+ * 键闭集 → `name` → `dir` → `tier` → 与前面的项重名)→ 声明了包而没设根。第一处不过即拒,拒句不回显声明的值。
+ */
+export declare function parseModsDeclaration(rootRaw: string | undefined, packagesRaw: string | undefined): ModsDeclaration;
+//# sourceMappingURL=mods-declaration.d.ts.map