@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/model/catalogLoader.js

@@ -1,76 +1,18 @@
-/**
- * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
- *
- * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
- *
- * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
- * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
- * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
- * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
- *
- *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
- *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
- *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
- *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
- *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
- *
- * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
- * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
- * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
- * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
- *
- * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
- *
- * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
- * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
- * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
- * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
- * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
- * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
- * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
- * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
- * 是两件事,[honest-absence-not-fabricated-zero])。
- *
- * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
- *
- * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
- * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
- * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
- * 真要「手动刷新」,直接再调一次本函数就是最新语义。
- *
- * ## 时钟
- *
- * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
- * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
- */
 import { hostEnv } from '../hostEnv.js';
 import { resolveModelCatalog, } from './catalog.js';
-/**
- * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
- * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
- * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
- */
 export const DEFAULT_CATALOG_SOURCES = [
     'https://raw.githubusercontent.com/sema-agent/sema-model-catalog/main/dist/catalog.json',
     'https://cdn.jsdelivr.net/gh/sema-agent/sema-model-catalog@main/dist/catalog.json',
 ];
-/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
 export const CATALOG_DEFAULT_HOSTS = ['raw.githubusercontent.com', 'cdn.jsdelivr.net'];
-/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
 export const CATALOG_SOURCES_ENV = 'SEMA_CATALOG_SOURCES';
-/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
 const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
-/** 缓存相对 configHome 的落点(design/166 §3)。 */
 const CATALOG_CACHE_RELATIVE_PATH = 'cache/model-catalog.json';
-/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
 const CATALOG_CACHE_STALE_MS = 30 * 24 * 60 * 60 * 1000;
-/** 单源允许的重定向跳数上限(有界:302 环不许把 onboard 转死)。 */
 const MAX_REDIRECTS = 5;
-/** 异常 → 短 detail(只取 message 前段,绝不带栈、绝不带载荷;与 catalog.ts 同一口径)。 */
 function shortError(e) {
     return (e instanceof Error ? e.message : String(e)).slice(0, 160);
 }
-/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
 export function parseCatalogSources(raw) {
     if (typeof raw !== 'string')
         return [];
@@ -79,10 +21,6 @@ export function parseCatalogSources(raw) {
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
-/**
- * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
- * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
- */
 export function resolveCatalogSources(opts) {
     const env = opts?.env ?? hostEnv();
     const fromEnv = parseCatalogSources(env[CATALOG_SOURCES_ENV]);
@@ -93,29 +31,23 @@ export function resolveCatalogSources(opts) {
         return given;
     return [...DEFAULT_CATALOG_SOURCES];
 }
-/** 取 URL 的 host(含 port);解析不动 ⇒ undefined。 */
 function hostOf(url) {
     let parsed;
     try {
         parsed = new URL(url);
     }
     catch {
-        parsed = undefined; // 解析不动 = 不是合法 URL,调用方按「拒」处理(判决在 isAllowedCatalogUrl)
+        parsed = undefined;
     }
     return parsed?.host;
 }
-/**
- * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
- * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
- * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
- */
 export function isAllowedCatalogUrl(url, allowedHosts) {
     let parsed;
     try {
         parsed = new URL(url.trim());
     }
     catch {
-        parsed = undefined; // 非法 URL ⇒ 拒(下面那一行判它)
+        parsed = undefined;
     }
     if (parsed === undefined)
         return false;
@@ -123,15 +55,12 @@ export function isAllowedCatalogUrl(url, allowedHosts) {
         return false;
     return allowedHosts.has(parsed.host);
 }
-/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
 export function catalogShaUrlFor(catalogUrl) {
     return catalogUrl.endsWith('.json') ? `${catalogUrl.slice(0, -'.json'.length)}.sha256` : `${catalogUrl}.sha256`;
 }
-/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
 export function catalogCachePath(configHome) {
     return `${configHome.replace(/\/+$/, '')}/${CATALOG_CACHE_RELATIVE_PATH}`;
 }
-/** SHA-256 hex(WebCrypto;Node 18+ 与浏览器都有。拿不到实现 ⇒ null = 本次不比对)。 */
 async function sha256Hex(text) {
     const g = globalThis;
     const subtle = g.crypto?.subtle;
@@ -144,7 +73,6 @@ async function sha256Hex(text) {
         out += b.toString(16).padStart(2, '0');
     return out;
 }
-/** sha 文件内容 → hex(容忍 `<hex>  <filename>` 的 shasum 形与大小写)。认不出 ⇒ null。 */
 function parseShaFile(text) {
     const m = /\b([0-9a-fA-F]{64})\b/.exec(text);
     return m?.[1] === undefined ? null : m[1].toLowerCase();
@@ -166,8 +94,6 @@ async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
         let res;
         let dialError;
         try {
-            // 🔴 `redirect:'manual'` 是这道门的**执行体**:默认的 'follow' 会让 undici/浏览器替我们
-            //    跟到域外去(白名单被 302 绕过);手动跟 = 每一跳都回到上面那道 isAllowedCatalogUrl。
             res = await fetchImpl(current, { method: 'GET', redirect: 'manual', signal: controller.signal });
         }
         catch (e) {
@@ -178,8 +104,6 @@ async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
         }
         if (res === undefined)
             return { outcome: 'network-error', detail: dialError ?? 'dial failed' };
-        // 浏览器的 `redirect:'manual'` 给的是 opaqueredirect(status 0、无头)——看不见目标就
-        // **拒**(fail-closed):看不见的重定向恰恰是这道门要防的那种。
         if (res.status === 0)
             return { outcome: 'redirect-opaque', status: 0, detail: 'opaque redirect: target not inspectable' };
         if (res.status >= 300 && res.status < 400) {
@@ -214,16 +138,11 @@ async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
     }
     return { outcome: 'redirect-loop', detail: `more than ${MAX_REDIRECTS} redirects` };
 }
-/**
- * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
- * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
- */
 export async function loadCatalogWithSources(opts) {
     const sources = resolveCatalogSources({
         ...(opts?.env !== undefined ? { env: opts.env } : {}),
         ...(opts?.sources !== undefined ? { sources: opts.sources } : {}),
     });
-    // 白名单 = 默认两域 + **用户显式配置的源 host**(显式意愿=自担;doctor 如实标 user-configured)。
     const allowedHosts = new Set(CATALOG_DEFAULT_HOSTS);
     for (const s of sources) {
         const h = hostOf(s);
@@ -235,9 +154,6 @@ export async function loadCatalogWithSources(opts) {
     const attempts = [];
     const warnings = [];
     let lastDialed;
-    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
-    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
-    // 校验与合并是它的活,两边不重叠也不互相重写。
     const resolveWith = async (p) => {
         const onlineUrl = p?.url ?? lastDialed ?? sources[0];
         const resolveOpts = {
@@ -252,19 +168,6 @@ export async function loadCatalogWithSources(opts) {
         };
         return resolveModelCatalog(resolveOpts);
     };
-    // ══ 🔴 [4982] 候选② 的**同形存量**(0.42.0 异源复审 [high] 采纳)══════════════════════════
-    //
-    // 病根与「缓存腿从没被问过」是**同一条**:候选链的停止判据锚在**传输层**(`hit !== null`)而不是
-    // **内容判决**。后果比缓存那一格更重 —— 首源发得下来但内容不合格时,`break` 让**后续健康源
-    // 永远不会被请求**:一次坏发布、或一个 CDN 的半更新窗,就能把整条后备链压掉。
-    // ⇒ 停止判据换成 `accepted !== null`(内容判决),逐源「传输 → 旁签 → **内容校验**」,
-    //   只有真被接受的那一份才停链。
-    //
-    // 🔴 `rejected` 是**诚实兜底**不是备选源:全链都被拒时,拿**第一份被拒的**去出结果,
-    //    这样 `online.reason` 说的是真话(`schema-version-unsupported`),而不是退成
-    //    「一个源都没连上」(`fetch-failed`)—— 那会把「内容坏了」谎报成「网络坏了」。
-    //    它**绝不**参与「用哪份目录」的竞争:被拒就是被拒,`online.ok === false` 时合并结果本就
-    //    回落内置表。
     let accepted = null;
     let rejected = null;
     for (const src of sources) {
@@ -295,8 +198,6 @@ export async function loadCatalogWithSources(opts) {
             attempts.push({ url: src, outcome: 'invalid-json', ...(got.status !== undefined ? { status: got.status } : {}), detail: parseError });
             continue;
         }
-        // 旁签:同源同路径。拿不到 ⇒ 记 warn 放行(design/165 §4:它是防传输损坏的纵深,
-        // 不是防主动篡改 —— 把「拿不到」当「篡改」会让 CDN 的半更新窗把整条链打死)。
         const shaGot = await guardedGet(catalogShaUrlFor(finalUrl), allowedHosts, fetchImpl, timeoutMs);
         let shaChecked = false;
         if (shaGot.outcome === 'ok' && shaGot.text !== undefined) {
@@ -321,7 +222,6 @@ export async function loadCatalogWithSources(opts) {
         }
         attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
         const candidate = { url: finalUrl, doc, raw: got.text, shaChecked };
-        // 内容判决就在这里做 —— 传输成功**不等于**这份目录能用。
         const verdict = await resolveWith(candidate);
         if (verdict.online.ok) {
             accepted = { hit: candidate, base: verdict };
@@ -332,18 +232,11 @@ export async function loadCatalogWithSources(opts) {
         warnings.push(`catalog source ${finalUrl} was fetched but REJECTED by content validation ` +
             `(${verdict.online.reason ?? 'unknown'}) — trying the next source`);
     }
-    // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
     const cache = opts?.cache;
     const cachePath = opts?.configHome !== undefined ? catalogCachePath(opts.configHome) : undefined;
     let cacheHit = cache !== undefined ? false : undefined;
     let cacheStale;
     let cachedSourceUrl;
-    /**
-     * 读一次缓存信封 → `SourceHit`(+ 陈旧判)。**永不抛**;坏形/缺件记 warn 返 null。
-     * 🔴 [4982] 候选②(0.42.0)提出来的:此前这段是内联的,只有「传输全败」那一条路走得到它。
-     *    现在有**两个**调用点(传输全败 / 传输 ok 但内容被拒),提成一处才不会有两份读法。
-     *    `alreadyWarned` = 第二次调用时不重复堆同一批 warn(同一份坏缓存说两遍是噪音)。
-     */
     const readCachedHit = async (alreadyWarned) => {
         if (cache === undefined || cachePath === undefined)
             return null;
@@ -379,8 +272,6 @@ export async function loadCatalogWithSources(opts) {
                 warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
             return null;
         }
-        // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
-        // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
         const stale = opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number'
             ? opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS
             : undefined;
@@ -389,30 +280,6 @@ export async function loadCatalogWithSources(opts) {
             ...(stale !== undefined ? { stale } : {}),
         };
     };
-    // ══ 缓存腿:**内容判决**缺席时才问它(传输全败 与 内容被拒 两条路共用这一格)═══════════════
-    //
-    // 🔴 [4982] 候选②(P0-KPI,0.42.0):此前这条腿的门槛是 `hit === null`,而 `hit` 只记录**传输层**
-    //    结果(200 + 旁签过就算 hit)。于是「线上目录发得下来、但内容被 validateOnlineCatalog 拒」
-    //    这条缝里,loader 认为「有 hit」⇒ **永不查缓存**(即便缓存里躺着一份上次真正被接受过的
-    //    合法目录),用户只拿到内置精简表;而 `cacheHit:false` 这个**诚实位反过来说谎** —— 它读起来
-    //    是「没有缓存」,真相是「有缓存,但从头到尾没人问过它」。
-    //    判据锚在**真正决定结果的量**上:决定「用不用得上目录」的是**内容判决**(`accepted`),
-    //    不是传输判决(`hit !== null`)。异源复审 [high] 之后,候选链的停止判据也换成了同一个量
-    //    (见上方 `accepted` 头注)—— 两处同根同治,不留同形存量。
-    // 🔴 缓存那份**不开后门**:它照样过同一个 `resolveModelCatalog`。也被拒时**不拿它顶替**
-    //    (一份同样不合格的文档顶替不了什么),`cacheHit` 诚实留在 `false` —— 本位的语义是
-    //    「这次的目录**是从缓存来的**」,不是「问过缓存」;抬成 true 会让「缓存救场了」与
-    //    「缓存也坏了」在读数上不可分。「问过但没用上」那件事由 warning 说。
-    /**
-     * 线上腿的**归因汇总**(异源复审 [medium] 采纳,0.42.0)。
-     *
-     * 🔴 修的是一句会指错方向的话:此前只要**任一**源产生 `rejected`,回落 warning 就写
-     *    「every online catalog source was fetched but REJECTED」。而其余源完全可能是网络失败、
-     *    畸形 JSON、sha 不匹配、或被域白名单挡下 —— 把一次 CDN/网络事故说成「目录发布损坏」,
-     *    运维会照着错误方向查,恢复时间平白变长。
-     * ⇒ 按 `attempts` 的**真实计数**分两类措辞:全部进过内容校验且全被拒 ⇒ 说 "every … REJECTED";
-     *   混合故障 ⇒ 逐类报数,并保留内容拒绝的 reason。
-     */
     const onlineLegSummary = () => {
         const contentRejected = attempts.filter((a) => a.outcome === 'ok').length;
         const otherFailures = attempts.length - contentRejected;
@@ -446,8 +313,6 @@ export async function loadCatalogWithSources(opts) {
                 warnings.push(`${onlineLegSummary()} — fell back to the cached catalog (${cached.hit.url})`);
         }
         else {
-            // 缓存那份也不合格 ⇒ 诚实回落:`online` 报的仍是**线上腿自己**的判词(有被拒的那一份就用
-            // 它的,一个都没连上就是 fetch-failed),绝不拿缓存的判词冒充线上的。
             payload = rejected?.hit ?? null;
             base = rejected?.base ?? (await resolveWith(null));
             warnings.push(`${onlineLegSummary()}, and the cached catalog was rejected by content validation too — ` +
@@ -458,8 +323,6 @@ export async function loadCatalogWithSources(opts) {
         payload = rejected?.hit ?? null;
         base = rejected?.base ?? (await resolveWith(null));
     }
-    // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
-    // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
     if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {
         const envelope = {
             ...(opts?.nowMs !== undefined ? { fetchedAt: opts.nowMs } : {}),

package/dist/model/modelSupplyRules.d.ts

@@ -1,81 +1,42 @@
-/** vision 生效值的**出处**(UI 那一行「当前生效值与来源」的唯一数据源)。 */
-export type VisionSource = 
-/** 这条 entry 自己显式表态。 */
-'entry'
-/** entry 不表态,取 `inferFamily` 的家族缺省。 */
- | 'family'
-/** 两边都不表态 —— 生效值**未知**,绝不折算成 false。 */
- | 'unknown';
-/**
- * {@link resolveEntryVision} 的结果(具名:本仓 typeshape 门对导出面内联匿名形有棘轮)。
- *
- * 🔴 `value: undefined` 与 `value: false` 是**两件事**:前者「没人说过这个模型能不能看图」,
- * 后者「确认它不能看图」。把前者渲成后者会永久封死一个真能力。
- */
+export type VisionSource = 'entry' | 'family' | 'unknown';
 export interface EntryVisionResolution {
     value: boolean | undefined;
     source: VisionSource;
 }
-/**
- * 解析一条 entry 的 vision **生效值 + 来源**。纯函数(只吃 modelId/vision 两位,零 IO)。
- *
- * 🔴 [honest-absence]:家族与 entry 都不表态时给 `undefined`(未知),**不**给 `false`。
- * ⚠️ 「未知」只是**客户端这一层**诚实:引擎侧 registry-core `ModelEntry.vision` 是
- * `z.boolean().default(false)`,键缺席在那边就等于 false。**呈现层必须把这个后果一起说出来**,
- * 别让用户以为「未知」= 引擎会自己去问供应商。
- */
 export declare function resolveEntryVision(entry: {
     modelId: string;
     vision?: boolean;
 }): EntryVisionResolution;
-/** 一处挡住删除的引用。`where` 是坐标(用户照着去改),`fix` 是这一处该怎么解开。 */
 export type PoolDeleteBlocker = {
     kind: 'default' | 'roles' | 'roster' | 'unreadable';
     where: string;
     fix: string;
 };
-/** 一条「照删,但你该知道」的后果。删除**不**被阻断,确认屏必须把它渲出来。 */
 export type PoolDeleteWarning = {
     kind: 'allowlist-empties' | 'tier-binding';
-    /** 人话:删了会发生什么(不是坐标,是后果)。 */
     consequence: string;
 };
-/**
- * 档位组的**归一形**(settings `semaTierGroups`)。两处删除判定共用,单独具名以免两边各写一份内联形。
- */
 export interface TierGroupsView {
     active: string;
     groups: Record<string, {
         tiers: Record<string, string | undefined>;
     }>;
 }
-/** {@link computeDeleteWarnings} 的入参(具名:导出面禁内联匿名形,B4 棘轮)。 */
 export interface DeleteWarningsInput {
     id: string;
-    /**
-     * 已读到的 models.json 文档切片。🔴 两位是 `unknown` 而不是收窄形 —— 它们是**盘上 JSON 的原样**,
-     * 属主是引擎的 models 域 schema(开集、可演进)。在这里手抄一份结构就是手抄一份会漂的上游形;
-     * 本函数对它们的处理本来就是「只判是不是数组/对象,然后逐项过滤」,窄读没有消费者。
-     * `null` = 调用方没读到文档(两义分流在调用方,见 {@link computeDeleteBlockers} 头注)。
-     */
     doc: {
         atModelAllowlist?: unknown;
         tierGroups?: unknown;
     } | null;
-    /** settings `semaTierGroups` 归一形(缺席 ⇒ 回落 `doc.tierGroups`,与写路径的取值序同源)。 */
     tierGroups: TierGroupsView | null;
-    /** 删除**之后**仍在池里的 catalog name 全集(判「有效名单会不会变空」要的就是它)。 */
     survivingIds: readonly string[];
 }
-/** {@link computeDeleteBlockers} 的入参(具名:同上)。 */
 export interface DeleteBlockersInput {
     id: string;
-    /** 已读到的 models.json 文档切片;两位 `unknown` 的理由同 {@link DeleteWarningsInput.doc}。 */
     doc: {
         default?: unknown;
         roles?: unknown;
     } | null;
-    /** roster 归一形(激活组名 + 全部组的 slot 表;**分阶段组也在里面**,它们是真引用)。 */
     rosters: {
         active: string;
         rosters: Record<string, {
@@ -83,20 +44,5 @@ export interface DeleteBlockersInput {
         }>;
     } | null;
 }
-/**
- * 纯判定:删这条 entry 会带来哪些**语义变化**(不阻断)。
- *
- * 两格,都是「链不断但意思变了」:
- *   ① `atModelAllowlist` 的**有效名单**会被删空 ⇒ 按 registry-core 语义**全部启用模型都可 @**
- *      —— 一次静默的权限放宽,必须说;名单里还有别人 ⇒ 只是缩小名单,不用说。
- *   ② `semaTierGroups` 里有绑定指着它 ⇒ 删完那条绑定悬空 ⇒ 下次按档位解析会落到**另一个模型**上
- *      (而不是报错),用户会以为「我明明配了 pro 档」。
- */
 export declare function computeDeleteWarnings(input: DeleteWarningsInput): PoolDeleteWarning[];
-/**
- * 纯判定:这条 entry 现在被哪些**断链类**引用挡着。空数组 = 可以删。
- *
- * 🔴 `doc === null` 的两义**在调用方分流**:这里只认「已读到的文档」;读不出来时调用方自己产
- * `unreadable` 阻断 —— 那一刻我们并不知道谁指着它,fail-closed 拒删比「猜没人指着」安全。
- */
 export declare function computeDeleteBlockers(input: DeleteBlockersInput): PoolDeleteBlocker[];

package/dist/model/modelSupplyRules.js

@@ -1,44 +1,7 @@
-/**
- * modelSupplyRules.ts — **Model Hub 供给面的三端公共判定**(#318 件③ 上收,cli [4752] 预告的
- * 「resolveEntryVision / computeDeleteBlockers / computeDeleteWarnings 三纯函数」)。
- *
- * ── 为什么在这里 ────────────────────────────────────────────────────────────────────────────
- * 三端(TUI / web / desktop)的 Model Hub 要回答同样的三个问题:
- *   ① 这条模型档的 `vision` **生效值**是什么、**出处**是哪(自己表态 / 家族缺省 / 没人说过);
- *   ② 删这条档会不会**断链**(该拒删,并指路);
- *   ③ 删这条档会不会**悄悄改语义**(该照删,但确认屏必须逐条说出后果)。
- * 判定放在库里、装配与呈现留端 —— 三端各写一遍的话,三个 Hub 会对「同一条档能不能删」给出三个
- * 答案,而其中两个是在用户按下 y 之后才被发现的。
- *
- * ── 🔴 零 IO(本模块的立身之本)──────────────────────────────────────────────────────────────
- * 三个函数**只吃已读好的数据**,不碰文件系统、不认识 `models.json` 在哪、不持锁。读盘那半场留在
- * 各端(壳 = `modelChannels.poolDeleteBlockers` / `poolDeleteWarnings`,它们读完再调这里)。
- * 分层的判据在 cli 侧成文:`doc === null` 的两义**在调用方分流** —— 本模块只认「已读到的文档」,
- * 读不出来时由调用方自己产 `unreadable` 阻断(那一刻并不知道谁指着它,fail-closed 拒删比
- * 「猜没人指着」安全)。
- *
- * ── ⚠️ 上收差分(逐条,行为零改动)────────────────────────────────────────────────────────
- *  · `resolveEntryVision` 的返回型从**内联匿名对象**改为具名 {@link EntryVisionResolution}
- *    —— 本仓 typeshape 门对导出面的内联匿名形有棘轮(B4)。**结构逐字相同**,壳侧剪切时零适配。
- *  · `inferFamily` 的来源从壳内 re-export 改为同包 `./providerPresets.js` 直取(壳那份本来就是
- *    本包的 re-export)。⚠️ 与 #318 件③ 的**分层遮蔽修同批**:修前 `inferFamily(deepseek-*)?.vision`
- *    结构性恒 `undefined`,所以 `source:'family'` 这一档对 deepseek 族**从来没走到过**;修后才真的
- *    走得到。上收与修同批落地是刻意的 —— 只上收不修,等于把一条死分支原样搬进三端。
- *  · `isPlainObject` 在壳里是文件级私有,这里同形自持(不新增公面导出)。
- */
 import { inferFamily } from './providerPresets.js';
-/** 局部判据:普通对象(非 null、非数组)。与壳侧 `modelChannels.isPlainObject` 同形。 */
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
-/**
- * 解析一条 entry 的 vision **生效值 + 来源**。纯函数(只吃 modelId/vision 两位,零 IO)。
- *
- * 🔴 [honest-absence]:家族与 entry 都不表态时给 `undefined`(未知),**不**给 `false`。
- * ⚠️ 「未知」只是**客户端这一层**诚实:引擎侧 registry-core `ModelEntry.vision` 是
- * `z.boolean().default(false)`,键缺席在那边就等于 false。**呈现层必须把这个后果一起说出来**,
- * 别让用户以为「未知」= 引擎会自己去问供应商。
- */
 export function resolveEntryVision(entry) {
     if (typeof entry.vision === 'boolean')
         return { value: entry.vision, source: 'entry' };
@@ -47,24 +10,11 @@ export function resolveEntryVision(entry) {
         return { value: fam, source: 'family' };
     return { value: undefined, source: 'unknown' };
 }
-/**
- * 纯判定:删这条 entry 会带来哪些**语义变化**(不阻断)。
- *
- * 两格,都是「链不断但意思变了」:
- *   ① `atModelAllowlist` 的**有效名单**会被删空 ⇒ 按 registry-core 语义**全部启用模型都可 @**
- *      —— 一次静默的权限放宽,必须说;名单里还有别人 ⇒ 只是缩小名单,不用说。
- *   ② `semaTierGroups` 里有绑定指着它 ⇒ 删完那条绑定悬空 ⇒ 下次按档位解析会落到**另一个模型**上
- *      (而不是报错),用户会以为「我明明配了 pro 档」。
- */
 export function computeDeleteWarnings(input) {
     const { id, doc, tierGroups, survivingIds } = input;
     const out = [];
     const allow = doc?.atModelAllowlist;
     if (Array.isArray(allow)) {
-        // 🔴 判据锚在**有效名单**上,不锚「字面上是不是只有它一个」:落盘闸口会把**所有悬空名**一起
-        // 滤掉,所以 `['victim','already-dangling']` 这种名单删掉 victim 之后有效名单同样变空 = 同样
-        // 放宽到「全部启用模型都可 @」,而 `every(n => n === id)` 那条旧判据对它一声不吭 = 承诺给用户
-        // 的权限提示上的**假阴**。
         const declared = allow.filter((x) => typeof x === 'string');
         const effectiveBefore = declared.filter(n => n === id || survivingIds.includes(n));
         const effectiveAfter = declared.filter(n => n !== id && survivingIds.includes(n));
@@ -75,9 +25,6 @@ export function computeDeleteWarnings(input) {
             });
         }
     }
-    // 档位绑定的取值序与写路径同源:settings 现值优先,settings 没有档位组时回落 models.json 文件里
-    // 那份投影(只扫 settings 会漏掉「settings 无档位组、models.json 自带 tierGroups」那一格 ——
-    // 那份绑定同样会在写路径被 byId 静默滤掉)。
     const groups = tierGroups
         ? Object.entries(tierGroups.groups).map(([g, def]) => [g, def?.tiers ?? {}])
         : Array.isArray(doc?.tierGroups)
@@ -97,12 +44,6 @@ export function computeDeleteWarnings(input) {
     }
     return out;
 }
-/**
- * 纯判定:这条 entry 现在被哪些**断链类**引用挡着。空数组 = 可以删。
- *
- * 🔴 `doc === null` 的两义**在调用方分流**:这里只认「已读到的文档」;读不出来时调用方自己产
- * `unreadable` 阻断 —— 那一刻我们并不知道谁指着它,fail-closed 拒删比「猜没人指着」安全。
- */
 export function computeDeleteBlockers(input) {
     const { id, doc, rosters } = input;
     const out = [];
@@ -115,7 +56,6 @@ export function computeDeleteBlockers(input) {
     }
     if (doc && isPlainObject(doc.roles)) {
         for (const [role, target] of Object.entries(doc.roles)) {
-            // `{ select }` 形是**按 tier/needs 现选**,不是 catalog 引用 —— 删模型影响不到它,不拦。
             if (!isPlainObject(target) || typeof target.model !== 'string')
                 continue;
             if (target.model !== id)
@@ -134,8 +74,6 @@ export function computeDeleteBlockers(input) {
             for (const [slot, ref] of Object.entries(def.slots)) {
                 if (ref !== id)
                     continue;
-                // 分阶段(未激活)组同样是真引用:它一被 switchRoster 激活就要按 slot 解析池,指着已删的
-                // entry = 激活当场断链。只看 active.slots 的实现会把分阶段组整个漏掉。
                 const isActive = name === rosters.active;
                 out.push({
                     kind: 'roster',

package/dist/model/providerAuth.d.ts

@@ -1,47 +1,4 @@
-/**
- * providerAuth.ts — **模型供应商凭证轨**的双轨 seam(design/166 §5「B 档:设备码流」,2026-08-04)。
- *
- * ## 边界(先说清楚它**不是**什么)
- *
- * 🔴 [reuse-single-sso-no-parallel-auth]:registry SSO(cloudAuth,「登录 sema」那条)**绝不复用、
- * 绝不被改造**。本文件是**模型供应商**的凭证轨(拿一把 API key 去调某家模型),与 registry 登录轨
- * 物理分文件、零共享代码。两者唯一的相似点是「都会弹一个浏览器」,那不构成复用理由。
- *
- * 🔴 design/166 §6 已定谳:**授权码 + PKCE(C 档)不做、不留 seam、不留枚举位** —— Anthropic 侧
- * 条款明文禁止第三方代理其订阅凭证,而公开实现全都依赖冒用官方 client_id + 伪装 UA。本文件里
- * 因此**只有** api_key 与 device_code 两轨,没有第三个 kind 位。
- *
- * ## 能力真值 = 目录键 ∧ 包内实现(两者与)
- *
- * 目录(design/165 §2)里的 `deviceAuth` 键**只是能力开关**,client_id 与端点**绝不目录化下发**
- * (远端可改鉴权端点 = 钓鱼面)。所以 UI 是否显示「Sign in with device code」的判据是
- * `supportsDeviceCodeAuth(id, preset.deviceAuth)`:
- *   · 目录说有、包里没有 ⇒ **不显示**(防目录先行造出一个点了没反应的假 affordance);
- *   · 包里有、目录没说 ⇒ **不显示**(那家还没被目录确认支持)。
- *
- * ## 🔴 `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假 —— 这是有意的,不是没写完)
- *
- * 设计档写「首发 1 家:GitHub Copilot 形」。落码时的事实是:device flow 需要一个 **client_id**,
- * 而公开可查到的 Copilot client_id 全部是**别的编辑器插件自己的** app id(copilot.vim / VS Code
- * 扩展)。把它们编进我们的包 = 以别人的 app 身份向 GitHub 发起授权,与 §6 判 C 档出局时用的
- * **同一条判据**(「冒用官方 client_id」是主动欺骗,不是灰区)。我们自己名下的 OAuth app 尚未
- * 申请 ⇒ 这一格的诚实值是**空**,而不是先填一个能跑的别人的号。
- *
- * 空表不是把这条腿废了:轮询器、退避、上限、终态词表全部在位并被门覆盖(门用一份合成 descriptor
- * 跑真 HTTP)。**注册一家 = 往这张表加一行**,零代码改动。在那之前 `supportsDeviceCodeAuth`
- * 对每一家如实返回 false,UI 不显示该选项 —— 这正是「能力真值 = 两者与」自带的正确降级。
- *
- * ## key 到手之后
- *
- * 🔴 **落盘不在包内做**。`poll()` 把 key 原样返给宿主,宿主走**与手填完全相同的那条路径**
- * (壳 = `applyOnboard.ts` 写 settings `env.MODEL_API_KEY`)。两树都没有 auth.json 实体,
- * 本文件也不新建任何持久面(design/166 §5 复核 M4:零新持久面,禁造)。
- */
 import type { ProviderPreset, ProviderDeviceAuthHint } from './providerPresets.js';
-/**
- * 一个 provider 可用的凭证轨。
- * `api_key` 是现状唯一轨(手填,env 名来自 preset.authEnv);`device_code` 是 B 档新轨。
- */
 export type ProviderAuthMethod = {
     kind: 'api_key';
     env: string;
@@ -49,99 +6,39 @@ export type ProviderAuthMethod = {
     kind: 'device_code';
     providerId: string;
 };
-/**
- * 设备码端点三件套 —— **编译进包**(design/165 §2 红线:client_id / token 端点 / authorize 端点
- * 一律不进目录)。
- */
 export interface DeviceCodeEndpoints {
     clientId: string;
-    /** RFC 8628 device authorization endpoint。 */
     deviceCodeUrl: string;
-    /** token endpoint(轮询这一个)。 */
     tokenUrl: string;
-    /** 申请的 scope(留空 = 不发这个参数)。 */
     scope?: string;
 }
-/** 包内登记的一家设备码 provider。 */
 export interface DeviceAuthProvider {
-    /** 与目录/preset 的 `id` 同一个命名空间(用户 settings 里的持久引用)。 */
     providerId: string;
     label: string;
     endpoints: DeviceCodeEndpoints;
 }
-/**
- * 包内实现的设备码 provider 表。
- * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
- * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
- */
 export declare const DEVICE_AUTH_PROVIDERS: readonly DeviceAuthProvider[];
-/** 包内是否实现了这一家(能力真值的一半)。 */
 export declare function deviceAuthProviderFor(providerId: string): DeviceAuthProvider | undefined;
-/**
- * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
- * 任一缺席 ⇒ false(见文件头「能力真值」段)。
- */
 export declare function supportsDeviceCodeAuth(providerId: string, catalogHint: ProviderDeviceAuthHint | undefined): boolean;
-/**
- * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
- */
 export declare function providerAuthMethods(preset: ProviderPreset): ProviderAuthMethod[];
-/**
- * 一次 `poll()` 的结局。
- *
- * 🔴 比设计档草案多两个终态,理由是诚实:草案只有 `pending|ok|expired`,于是
- * 「用户点了拒绝」与「会话被本地取消」都只能冒充 `expired`(= 骗用户「过期了,再来一次」,
- * 而事实是再来一次还会被拒 / 是他自己取消的)。两者各占一位:
- *   · `denied`    —— 授权服务器说 access_denied;
- *   · `cancelled` —— 本地调过 `cancel()`。
- */
 export type DeviceCodeStatus = 'pending' | 'ok' | 'expired' | 'denied' | 'cancelled';
 export interface DeviceCodePollResult {
     status: DeviceCodeStatus;
-    /** 只在 `ok` 时在场。🔴 宿主拿去走与手填同一条落盘路径;包内零持久面。 */
     key?: string;
-    /** 人话细节(分诊用;绝不带 key、绝不带完整响应体)。 */
     detail?: string;
 }
-/**
- * 一次设备码会话。**宿主驱动**:UI 渲大字码 + URL,自己按 `intervalMs` 起节拍调 `poll()`
- * (等待型判据,不固定拍)。包内不起定时器 —— 定时器是宿主资产(与 `TimersPort` 同一条纪律)。
- */
 export interface DeviceCodeSession {
-    /** 用户要在浏览器里输入的大字码。 */
     userCode: string;
-    /** 用户要打开的验证页。 */
     verificationUrl: string;
-    /** 建议轮询间隔(毫秒)。429 / slow_down 之后会**变大**,宿主每拍都该重读这个值。 */
     intervalMs: number;
-    /** 本会话的墙钟终点(min(服务端 expires_in, 15min 上限))。 */
     expiresAtMs: number;
     poll(): Promise<DeviceCodePollResult>;
     cancel(): void;
 }
-/**
- * 设备码流的宿主注入面。
- * 🔴 `nowMs` **必填**:5s 间隔与 15min 上限都是墙钟判据,而本包绝不偷读时钟
- * (与 `catalog.ts` / `AdapterContext.now` 同一口径)。宿主传 `() => Date.now()`。
- */
 export interface DeviceCodeAuthOptions {
     nowMs: () => number;
-    /** 传输注入口(缺省全局 `fetch`)。 */
     fetchImpl?: typeof fetch;
-    /** 单次 HTTP 预算(缺省 `DEVICE_CODE_HTTP_TIMEOUT_MS`)。 */
     timeoutMs?: number;
 }
-/**
- * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
- * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
- * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
- *
- * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
- * 绝不返回一个永远 pending 的假会话。
- */
 export declare function openDeviceCodeSession(endpoints: DeviceCodeEndpoints, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;
-/**
- * 按 providerId 开设备码会话(UI 入口)。
- * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
- */
 export declare function beginDeviceCodeAuth(providerId: string, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;