@sema-agent/client-core 0.14.0 → 0.16.0

package/dist/model/catalogLoader.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 { type EnvLike } from '../hostEnv.js';
+import { type ModelCatalogResult, type OnlineCatalogDoc } from './catalog.js';
+import type { ProviderPreset } from './providerPresets.js';
+/**
+ * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
+ * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
+ * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
+ */
+export declare const DEFAULT_CATALOG_SOURCES: readonly string[];
+/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
+export declare const CATALOG_DEFAULT_HOSTS: readonly string[];
+/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
+export declare const CATALOG_SOURCES_ENV = "SEMA_CATALOG_SOURCES";
+/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
+export declare const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export declare const CATALOG_CACHE_RELATIVE_PATH = "cache/model-catalog.json";
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export declare const CATALOG_CACHE_STALE_MS: number;
+/**
+ * 单源的**传输层**结局。
+ *
+ * 🔴 它**不是**第二套 origin 词表:UI 渲染「目录从哪来」恒读 `ModelCatalogResult.source` +
+ * `online.reason` + `cacheHit`。本词表只服务于 **doctor 的逐源分诊**(「两跳分别为什么没成」),
+ * 那是 `catalog.ts` 的单 URL 视角在结构上说不出来的量 —— 它只有一个 `online` 结局位。
+ */
+export type CatalogSourceOutcome = 'ok' | 'insecure-url' | 'host-not-allowed' | 'redirect-blocked' | 'redirect-opaque' | 'redirect-loop' | 'http-error' | 'network-error' | 'invalid-json' | 'sha-mismatch';
+/** 一次逐源尝试的留痕(doctor 用;🔴 绝不带载荷内容,只带判决与被截断的 message)。 */
+export interface CatalogSourceAttempt {
+    url: string;
+    outcome: CatalogSourceOutcome;
+    /** HTTP 状态码(只在真收到响应时在场)。 */
+    status?: number;
+    /** 旁签是否**真的比对过**(只在 `outcome:'ok'` 时在场;false = sha 拿不到,已记 warn 放行)。 */
+    shaChecked?: boolean;
+    /** 人话细节(判决相关短语 / 被截断的错误 message)。 */
+    detail?: string;
+}
+/** 缓存文件的信封(design/166 §3)。`fetchedAt` 缺席 = 写入时宿主没给时钟。 */
+export interface CatalogCacheEnvelope {
+    fetchedAt?: number;
+    sourceUrl: string;
+    catalog: OnlineCatalogDoc;
+}
+/**
+ * 缓存口 —— 宿主注入(本包零 `node:fs`,理由见文件头)。
+ *
+ * `writeAtomic` 的契约是**原子替换**(临时文件 + rename),不是 `writeFile` 的别名:
+ * 半截文件会让下一次冷启动读到一份坏缓存。Node 宿主的参考实现:
+ * ```js
+ * async writeAtomic(path, text) {
+ *   await mkdir(dirname(path), { recursive: true })
+ *   const tmp = `${path}.${process.pid}.tmp`
+ *   await writeFile(tmp, text, 'utf8')
+ *   await rename(tmp, path)     // 同目录 rename = 原子
+ * }
+ * ```
+ * 两个动词都允许同步或异步实现;抛异常由 loader 收成 warning(缓存是纵深,不是主路径)。
+ */
+export interface CatalogCachePort {
+    read(path: string): string | null | Promise<string | null>;
+    writeAtomic(path: string, text: string): void | Promise<void>;
+}
+/** `loadCatalogWithSources` 的入参。 */
+export interface LoadCatalogOptions {
+    /** 缓存落点的根(`configHome/cache/model-catalog.json`)。缺席 ⇒ 缓存腿不启用。 */
+    configHome?: string;
+    /** 覆盖候选链(缺省 `DEFAULT_CATALOG_SOURCES`;env 恒赢本项,见 `resolveCatalogSources`)。 */
+    sources?: readonly string[];
+    /** 宿主 env(缺省 `hostEnv()`)。 */
+    env?: EnvLike;
+    /** 每源传输预算(缺省 `DEFAULT_CATALOG_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+    /** 宿主时钟。缺席 ⇒ 不算 ageMs、不写 fetchedAt、不判 stale(绝不偷读时钟)。 */
+    nowMs?: number;
+    /** 传输注入口(缺省全局 `fetch`;本包既有姿势 = limitsWire/detachWire 的 `fetchImpl`)。 */
+    fetchImpl?: typeof fetch;
+    /** 缓存口。缺席 ⇒ 缓存腿整条不启用(`cacheHit` 键缺席)。 */
+    cache?: CatalogCachePort;
+    /** 用户本地覆盖层,原样透传给 `resolveModelCatalog`。 */
+    overrides?: readonly ProviderPreset[];
+}
+/**
+ * 结果 = `ModelCatalogResult`(来源标注/新鲜度/合并表全归 catalog.ts)+ 宿主面四位。
+ * 🔴 只**加**位不改位:端渲染仍读 `source` / `online.reason`。
+ */
+export interface LoadedModelCatalog extends ModelCatalogResult {
+    /** 真正被吃下的那一跳(线上成功或缓存自述的来源);全败 ⇒ 缺席。 */
+    sourceUrl?: string;
+    /** 这份线上载荷是不是从缓存顶上来的。**缓存口缺席 ⇒ 本键缺席**(没查过 ≠ 查过没用上)。 */
+    cacheHit?: boolean;
+    /** 缓存是否已过 30 天(照用但如实标)。只在 `cacheHit:true` 且宿主给了时钟时在场。 */
+    cacheStale?: boolean;
+    /** 逐源留痕(doctor 分诊用)。 */
+    attempts: CatalogSourceAttempt[];
+    /** 非致命的诚实记账(sha 拿不到 / 缓存读写失败 / 缓存半截)。 */
+    warnings: string[];
+}
+/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
+export declare function parseCatalogSources(raw: string | undefined | null): string[];
+/** `resolveCatalogSources` 的入参。 */
+export interface ResolveCatalogSourcesOptions {
+    env?: EnvLike;
+    sources?: readonly string[];
+}
+/**
+ * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
+ * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
+ */
+export declare function resolveCatalogSources(opts?: ResolveCatalogSourcesOptions): string[];
+/**
+ * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
+ * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
+ * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
+ */
+export declare function isAllowedCatalogUrl(url: string, allowedHosts: ReadonlySet<string>): boolean;
+/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
+export declare function catalogShaUrlFor(catalogUrl: string): string;
+/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
+export declare function catalogCachePath(configHome: string): string;
+/**
+ * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
+ * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
+ */
+export declare function loadCatalogWithSources(opts?: LoadCatalogOptions): Promise<LoadedModelCatalog>;

package/dist/model/catalogLoader.js

@@ -0,0 +1,382 @@
+/**
+ * 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 不能被网络拖住)。 */
+export const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export const CATALOG_CACHE_RELATIVE_PATH = 'cache/model-catalog.json';
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export 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 [];
+    return raw
+        .split(',')
+        .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]);
+    if (fromEnv.length > 0)
+        return fromEnv;
+    const given = (opts?.sources ?? []).map((s) => s.trim()).filter((s) => s.length > 0);
+    if (given.length > 0)
+        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)
+    }
+    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 ⇒ 拒(下面那一行判它)
+    }
+    if (parsed === undefined)
+        return false;
+    if (parsed.protocol !== 'https:')
+        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;
+    const Enc = g.TextEncoder;
+    if (subtle === undefined || Enc === undefined)
+        return null;
+    const digest = await subtle.digest('SHA-256', new Enc().encode(text));
+    let out = '';
+    for (const b of new Uint8Array(digest))
+        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();
+}
+async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (!isAllowedCatalogUrl(current, allowedHosts)) {
+            const insecure = !/^https:/i.test(current.trim());
+            return {
+                outcome: hop === 0 ? (insecure ? 'insecure-url' : 'host-not-allowed') : 'redirect-blocked',
+                detail: hop === 0
+                    ? `source rejected before dialing: ${insecure ? 'not https' : `host not allowlisted (${hostOf(current) ?? 'unparsable'})`}`
+                    : `redirect target rejected: ${hostOf(current) ?? 'unparsable'}`,
+            };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 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) {
+            dialError = shortError(e);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        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) {
+            const loc = res.headers.get('location');
+            if (loc === null || loc.length === 0) {
+                return { outcome: 'http-error', status: res.status, detail: 'redirect without Location' };
+            }
+            let next;
+            try {
+                next = new URL(loc, current).toString();
+            }
+            catch (e) {
+                return { outcome: 'redirect-blocked', status: res.status, detail: `unparsable Location: ${shortError(e)}` };
+            }
+            current = next;
+            continue;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            return { outcome: 'http-error', status: res.status, detail: `HTTP ${res.status}` };
+        }
+        let text;
+        let readError;
+        try {
+            text = await res.text();
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (text === undefined)
+            return { outcome: 'network-error', status: res.status, detail: readError ?? 'body read failed' };
+        return { outcome: 'ok', status: res.status, finalUrl: current, text };
+    }
+    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);
+        if (h !== undefined)
+            allowedHosts.add(h);
+    }
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
+    const attempts = [];
+    const warnings = [];
+    let hit = null;
+    let lastDialed;
+    for (const src of sources) {
+        if (hit !== null)
+            break;
+        const got = await guardedGet(src, allowedHosts, fetchImpl, timeoutMs);
+        if (got.outcome !== 'insecure-url' && got.outcome !== 'host-not-allowed')
+            lastDialed = src;
+        if (got.outcome !== 'ok' || got.text === undefined) {
+            attempts.push({
+                url: src,
+                outcome: got.outcome,
+                ...(got.status !== undefined ? { status: got.status } : {}),
+                ...(got.detail !== undefined ? { detail: got.detail } : {}),
+            });
+            continue;
+        }
+        const finalUrl = got.finalUrl ?? src;
+        let doc;
+        let parseError;
+        try {
+            doc = JSON.parse(got.text);
+        }
+        catch (e) {
+            parseError = shortError(e);
+        }
+        if (parseError !== undefined) {
+            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) {
+            const expected = parseShaFile(shaGot.text);
+            const actual = await sha256Hex(got.text);
+            if (expected === null) {
+                warnings.push(`catalog sha256 sidecar for ${finalUrl} is not a hex digest — payload accepted without the checksum`);
+            }
+            else if (actual === null) {
+                warnings.push('no WebCrypto SHA-256 in this host — catalog payload accepted without the checksum');
+            }
+            else if (expected !== actual) {
+                attempts.push({ url: src, outcome: 'sha-mismatch', detail: 'catalog.sha256 does not match the payload digest' });
+                continue;
+            }
+            else {
+                shaChecked = true;
+            }
+        }
+        else {
+            warnings.push(`catalog sha256 sidecar unavailable for ${finalUrl} (${shaGot.outcome}) — payload accepted without the checksum`);
+        }
+        attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
+        hit = { url: finalUrl, doc, raw: got.text, shaChecked };
+    }
+    // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
+    const cache = opts?.cache;
+    const cachePath = opts?.configHome !== undefined ? catalogCachePath(opts.configHome) : undefined;
+    let cacheHit = cache !== undefined ? false : undefined;
+    let cacheStale;
+    let cachedSourceUrl;
+    if (hit === null && cache !== undefined && cachePath !== undefined) {
+        let text = null;
+        let readError;
+        try {
+            text = await cache.read(cachePath);
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (readError !== undefined)
+            warnings.push(`catalog cache read failed: ${readError}`);
+        if (typeof text === 'string' && text.length > 0) {
+            let env;
+            let envError;
+            try {
+                env = JSON.parse(text);
+            }
+            catch (e) {
+                envError = shortError(e);
+            }
+            if (envError !== undefined)
+                warnings.push(`catalog cache is not parsable JSON (ignored): ${envError}`);
+            const doc = env?.catalog;
+            const url = env?.sourceUrl;
+            if (doc !== undefined && typeof url === 'string' && url.length > 0) {
+                // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
+                // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
+                hit = { url, doc, raw: text, shaChecked: false };
+                cacheHit = true;
+                cachedSourceUrl = url;
+                if (opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number') {
+                    cacheStale = opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS;
+                }
+            }
+            else if (envError === undefined) {
+                warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
+            }
+        }
+    }
+    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
+    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
+    // 校验与合并是它的活,两边不重叠也不互相重写。
+    const payload = hit;
+    const onlineUrl = payload?.url ?? lastDialed ?? sources[0];
+    const resolveOpts = {
+        ...(onlineUrl !== undefined ? { onlineUrl } : {}),
+        fetchJson: async () => {
+            if (payload === null)
+                throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
+            return payload.doc;
+        },
+        ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
+        ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+    };
+    const base = await resolveModelCatalog(resolveOpts);
+    // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
+    // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
+    if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {
+        const envelope = {
+            ...(opts?.nowMs !== undefined ? { fetchedAt: opts.nowMs } : {}),
+            sourceUrl: payload.url,
+            catalog: payload.doc,
+        };
+        let writeError;
+        try {
+            await cache.writeAtomic(cachePath, JSON.stringify(envelope));
+        }
+        catch (e) {
+            writeError = shortError(e);
+        }
+        if (writeError !== undefined)
+            warnings.push(`catalog cache write failed: ${writeError}`);
+    }
+    const sourceUrl = base.online.ok ? (cachedSourceUrl ?? payload?.url) : undefined;
+    return {
+        ...base,
+        ...(sourceUrl !== undefined ? { sourceUrl } : {}),
+        ...(cacheHit !== undefined ? { cacheHit } : {}),
+        ...(cacheStale !== undefined ? { cacheStale } : {}),
+        attempts,
+        warnings,
+    };
+}