dsh-m 0.9.83 → 0.9.86

package/CHANGELOG.md

@@ -8,6 +8,24 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## 中文
 
+### 0.9.86 性能：packument 访问器——registry 元数据属主模块，登记网络腿出锁（钢人 C2 / ADR-0019）
+
+- **问题（钢人报告 C2 节）**：「registry 元数据」没有 owning module——登记（Register）只为读一个发布时戳，却在官方文件锁内发起 8MiB 级全量 packument 网络取（npmjs 首腿 5s 超时 + 生效源备腿至 12s），镜像机器装机的白等直接计入关键路径；B3 预热再经无缓存通道把同一全量取付第二次；三 adapter 各自取、各自缓存（或没有）。
+- **修复（ADR-0019）**：新属主模块 `src/core/packument.ts`——一次取回派生视图包 `{times, versions, distTags, readme, repo}`，按 (pkg, 生效源) 键缓存（TTL 5min / single-flight / cap=4 / 失败与 regex-invalid 负缓存同 TTL / onRouteSwitch 作废 + 生效源入键双保险）。登记 times **出锁**：发布时戳是不可变历史事实，锁外预取零 TOCTOU，锁体回归纯 fs（锁前存在性预读保「文件缺席零探测」钉子）；预检/登记共享 single-flight；B3 预热改 `warmPackumentFor`（bypass 缓存 + 生效源单腿真发暖 CDN + 回填）；readme 兜底腿同款单腿带缓存面（终末错误透传保全）。latest 小端点与 ADR-0006 制度不并入；四函数 + `extractGithubRepo` 迁入属主、versions.ts 原名 re-export（import 位零改动）。
+- **验证**：1462 项测试全绿（访问器 18 例新增：两腿超时收紧断言/single-flight 哨兵/负缓存/cap/路由作废/warm 单腿 bypass+回填/Active 面负缓存视 miss/readme 阶梯三态含 URL host 锚/锁内零网络时序断言）、typecheck 零错误；真机冒烟：访问器冷 143–269ms / 热 0ms / warm bypass 真发 29ms，登记真实 wire（临时 profile + 真实 young 版本）applied:true 111ms + 幂等 up-to-date 3ms；实施计划经独立评审三轮（13 条）+ 执行评审两轮（4 条建议全收口）。
+
+### 0.9.85 优化：版本号迁「关于」链接行尾 + 头部自升级入本地操作泵（两则真机反馈）
+
+- **① 版本号迁位（主人定稿）**：0.9.84 把插件版本号挂在「关于」标题行 sub（弱化灰字），真机对照后主人拍板迁至**链接行尾**（GitHub · 问题反馈 · npm · v0.9.85）——与外向元数据同组更协调，标题行回归纯净。缺失（ping 失败 → null）时整段不渲染，不留悬空分隔点；新增 `.dshm-links-ver` 弱化样式（label-secondary + tabular-nums）。不放升级入口的裁决不变。
+- **② 头部自升级漏记根治（主人真机反馈：⬆ 升级在操作日志无记录）**：根因是渠道两不沾——host-api `self-upgrade` 显式 `channel: 'panel'`（ADR-0018「面板通道零外部日志」不变量，防漏标落 external），而头部 chip 的 `doUpgrade` 直接 `api("self-upgrade")` 绕过本地操作泵，两头都不记。修复：chip 接线 `ops`（面板操作账本）并入泵 `ops.runOp("upgrade", "dsh-m", …)`，执行器回传 `opMeta {from,to}` 落账 → 已结束列表渲染「升级 dsh-m vX→vY」；SSR/探针无 `ops` 时回退直连 api。`stillApplies` 语义安全：dsh-m 恒已装 → 恒 applies，不触发 superseded。全家族盘点：安装/升级/卸载/开关/清单源/社区开关/「全部更新」（逐条 runOp 入队）均无漏记，自升级是唯一缺口。
+- **验证**：1443 项测试全绿（0.9.84 基线 1440 + 新增源锚：about-version 迁位改写与 render-smoke 自升级入泵）、typecheck 零错误；F1 族就绪门连续三跑全量稳定（曾现一次 657/42 异常未再复现，归因共享机瞬时载荷，已留日志）。
+
+### 0.9.84 优化：设置页「关于」标题行展示插件版本号
+
+- **问题（主人真机反馈）**：0.9.83 起窄容器下头部版本 chip 常态隐藏（共识 Q7——手机头部宽度让位给还原/关闭），插件自身版本号一度无处可查（设置页只有社区清单的「目录版本」）。
+- **方案（零视觉噪声）**：设置页「关于」卡标题行右侧既有 sub 槽（`.dshm-section-sub` 弱化灰字）挂裸版本号 `v{version}`——零新增行/块/CSS/i18n；`pluginVersion`（ping 单一事实源：挂载/回前台/重启确认后重取）以 prop 接入 SettingsTab，缺失（ping 失败 → null）时槽位自然为空（Section 兼容逻辑天然处理，与头部 chip「失败不留占位」同语义）；不放升级入口——头部 ⬆ + 市场卡片/CLI 所有权不变（尊重「dsh-m 自身卡已移除」裁决）。
+- **验证**：1442 项测试全绿（0.9.83 基线 1440 + 新增源锚 2 组于 client-about-version.test.mjs）、typecheck 零错误。
+
 ### 0.9.83 功能：手机窄屏自适应——面板头部两行重排 + 窄视口默认全屏
 
 - **问题（主人手机实拍）**：`.dshm-head` 是单行 no-wrap flex，最小内容宽 ~440-470px，手机面板内容宽仅 330-365px → 行尾溢出被 `.dshm-panel` overflow:hidden 裁掉：还原/关闭按钮组不可见不可点（关面板只剩遮罩点击）、版本 chip 拦腰截断、标题逐词换行、seg 键逐字竖排。移动端问题第三次以「用户手机截图反馈」方式暴露（0.9.66 触屏滑动方向、0.9.67 字号失控之后）。
@@ -591,6 +609,24 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## English
 
+### Performance in 0.9.86 — packument accessor: registry metadata gets an owning module, register's network leg leaves the lock (steelman C2 / ADR-0019)
+
+- **Problem (steelman report, card C2)**: "registry metadata" had no owning module - Register fetched an 8MiB-scale full packument INSIDE the official file lock just to read one publish timestamp (npmjs first leg 5s timeout + effective-source leg up to 12s), putting mirror machines' white-wait directly on the install critical path; the B3 prewarm paid the same full fetch a second time through an uncached channel; three adapters each fetched, interpreted and cached (or not) independently.
+- **Fix (ADR-0019)**: new owning module `src/core/packument.ts` - one fetch derives a view bundle `{times, versions, distTags, readme, repo}`, cached under (pkg, effective registry) keys (TTL 5min / single-flight / cap=4 / failures and regex-invalids negative-cached for the same TTL / onRouteSwitch invalidation + registry-in-key double insurance). Register's timestamp fetch **leaves the lock**: publish timestamps are immutable historical facts (zero TOCTOU), the lock body is pure fs again (a cheap pre-lock existence read preserves the "local check first" pin). Precheck and register share single-flight; B3 prewarm uses `warmPackumentFor` (cache-bypassing + effective-source single-leg real request to warm the CDN + backfill); the readme fallback leg shares the same single-leg cached face (final-leg error passthrough preserved). The latest small endpoint and ADR-0006 stay out of scope; four functions + `extractGithubRepo` moved into the owner, versions.ts re-exports under the original names (zero import-site changes).
+- **Verification**: 1462 tests green (18 accessor cases added: two-leg timeout-tightening assertions / single-flight sentinel / negative cache / cap / route invalidation / warm single-leg bypass+backfill / Active-face negative-cache-as-miss / readme ladder three states with URL host anchors / in-lock zero-network timing assertion), typecheck clean; live smoke: accessor cold 143-269ms / warm 0ms / warm bypass real request 29ms, register real-wire (temp profile + genuinely young version) applied:true in 111ms + idempotent up-to-date in 3ms; the plan closed over three independent review rounds (13 findings) + two execution review rounds (4 suggestions).
+
+### 0.9.85 Enhancement — version moves to the About links row + head self-upgrade enters the local ops pump (two real-device reports)
+
+- **① Version relocation (owner's call)**: 0.9.84 hung the plugin version on the "About" title-row sub (muted small text); after on-device comparison the owner decided to move it to the **links row tail** (GitHub · Issues · npm · v0.9.85) — grouped with the outward metadata, the title row stays clean. Missing version (ping failure → null) renders nothing, no dangling separator; new `.dshm-links-ver` muted style (label-secondary + tabular-nums). The no-upgrade-entry ruling stands.
+- **② Head self-upgrade log gap cured (owner's real-device report: ⬆ upgrades were absent from the operations log)**: the root cause fell between two ledgers — host-api `self-upgrade` explicitly passes `channel: 'panel'` (ADR-0018 invariant "panel channel writes zero external records", guarding against mislabelled external rows), while the head chip's `doUpgrade` called `api("self-upgrade")` directly, bypassing the local ops pump — so neither recorded it. Fix: the chip receives `ops` (the panel's ledger) and goes through `ops.runOp("upgrade", "dsh-m", …)`; the executor returns `opMeta {from,to}` so the ended list renders "升级 dsh-m vX→vY"; SSR/probes without `ops` fall back to the direct api call. `stillApplies` is semantically safe: dsh-m is always installed → always applies, no superseded. Family audit: install/upgrade/uninstall/toggle/registry-source/community-toggle and "Update all" (per-item runOp enqueue) all record correctly — self-upgrade was the only gap.
+- **Verification**: 1443 tests green (0.9.84 baseline 1440 + new source anchors: about-version relocation rewrite and render-smoke self-upgrade pump), typecheck clean; the F1-family readiness gate held stable across three consecutive full runs (one anomalous 657/42 run never reproduced — attributed to transient load on this shared box, logs archived).
+
+### 0.9.84 Enhancement — plugin version shown on the Settings "About" title row
+
+- **Problem (owner's real-device feedback)**: since 0.9.83 the head version chip stays hidden in its idle state on narrow containers (consensus Q7 — phone head width goes to the restore/close buttons), leaving the plugin's own version nowhere to check (the settings page only had the community catalog's 目录版本).
+- **Fix (zero visual noise)**: the "About" card's title row reuses its existing `sub` slot (`.dshm-section-sub`, muted small text on the right) to show the bare `v{version}` — zero new rows/blocks/CSS/i18n; `pluginVersion` (ping single source of truth: mount / foreground-return / post-restart re-check) reaches SettingsTab as a prop, and a missing version (ping failure → null) leaves the slot naturally empty (Section's compat logic handles it — same "no placeholder on failure" semantics as the head chip); no upgrade entry here — the head ⬆ plus marketplace card/CLI keep that ownership (respecting the removed dsh-m self card ruling).
+- **Verification**: 1442 tests green (0.9.83 baseline 1440 + 2 new source-anchor groups in client-about-version.test.mjs), typecheck clean.
+
 ### 0.9.83 Feature — mobile adaptive layout: two-row panel head + fullscreen-by-default on narrow viewports
 
 - **Problem (user phone screenshot)**: `.dshm-head` is a single-line no-wrap flex whose minimum content width is ~440-470px, while a phone panel offers only 330-365px — the row-end overflow gets clipped by `.dshm-panel`'s `overflow:hidden`: the restore/close button group becomes invisible and untappable (closing the panel is left to backdrop taps only), the version chip is cut mid-glyph, the title wraps word-by-word into a tower, and the seg tabs stack their CJK labels one character per line. This is the third mobile issue surfaced via "user phone screenshot" (after 0.9.66 touch-swipe direction and 0.9.67 font blow-up).

package/lib/client.js

@@ -2913,6 +2913,7 @@ button.dshm-badge:hover{filter:brightness(.95)}
 .dshm-links{display:flex;align-items:center;gap:6px;flex-wrap:wrap;margin-top:7px;padding-top:6px;border-top:1px solid var(--dsw-alias-border-l2,#e5e7eb);font-size:11px;color:var(--dsw-alias-label-caption,#6b7280)}
 .dshm-links-k,.dshm-links-sep{color:var(--dsw-alias-label-caption,#9ca3af)}
 .dshm-links a{color:var(--dsw-alias-state-business-primary,#4d6bfe);text-decoration:none;font-weight:500}
+.dshm-links-ver{font-weight:500;color:var(--dsw-alias-label-secondary,#4b5563);font-variant-numeric:tabular-nums}
 .dshm-links a:hover{text-decoration:underline}
 .dshm-prog{display:flex;align-items:center;gap:8px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l2,#e5e7eb);border-radius:8px;font-size:12px;color:var(--dsw-alias-label-secondary,#4b5563)}
 .dshm-prog .bar{flex:1;height:6px;border-radius:3px;background:var(--dsw-alias-bg-layer-2,rgba(38,49,72,.08));overflow:hidden;min-width:80px}
@@ -4594,7 +4595,7 @@ function regSourceLabel(data) {
 function configStatusLabel(status) {
   return lookup(`settings.status.${status || "loading"}` || "settings.status.loading");
 }
-function SettingsTab({ notify, onRegistryChanged, onForceMarket, opsRecords, onOpsClearFinished, onOpsRemove }) {
+function SettingsTab({ notify, onRegistryChanged, onForceMarket, opsRecords, onOpsClearFinished, onOpsRemove, version }) {
   const reg = useAsync((force) => api("registry", force ? { force: true } : {}), []);
   const cfgState = useAsync(() => api("registry-config"), []);
   const [busy, setBusy] = useState(false);
@@ -4798,7 +4799,10 @@ function SettingsTab({ notify, onRegistryChanged, onForceMarket, opsRecords, onO
       snap.warnings && snap.warnings.length ? h("div", { className: "dshm-note warn" }, `${lookup("settings.warnings")}\uFF1A${snap.warnings.join("\uFF1B")}`) : null,
       state && state.errors && state.errors.length ? h("div", { className: "dshm-err" }, `${lookup("settings.remotehint")}\uFF1A${state.errors.slice(0, 5).join("\uFF1B")}`) : null
     ),
-    // ③ 关于：当前定位 + 仓库/反馈链接（dsh-m 自身卡已按主人要求移除——升级走市场卡片/CLI，self-check/self-upgrade API 保留）
+    // ③ 关于：当前定位 + 仓库/反馈链接（dsh-m 自身卡已按主人要求移除——升级走市场卡片/CLI，self-check/self-upgrade API 保留）。
+    //    版本号挂链接行尾（0.9.85 主人定稿：0.9.84 曾挂标题 sub，真机对照后迁此——与 GitHub/npm 等
+    //    外向元数据同组更协调）；缺失（ping 失败 → null）时整段不渲染，不留悬空分隔点；
+    //    不放升级入口——头部 ⬆ + 市场卡片/CLI 所有权不变。
     Section(
       lookup("settings.about"),
       h("div", { className: "dshm-hint" }, lookup("settings.about.text")),
@@ -4809,7 +4813,11 @@ function SettingsTab({ notify, onRegistryChanged, onForceMarket, opsRecords, onO
         h("span", { className: "dshm-links-sep" }, "\xB7"),
         h(ExtLink, { href: "https://github.com/iasiv5/dsh-m/issues" }, lookup("settings.about.issues")),
         h("span", { className: "dshm-links-sep" }, "\xB7"),
-        h(ExtLink, { href: "https://www.npmjs.com/package/dsh-m" }, lookup("settings.about.npm"))
+        h(ExtLink, { href: "https://www.npmjs.com/package/dsh-m" }, lookup("settings.about.npm")),
+        version ? [
+          h("span", { className: "dshm-links-sep" }, "\xB7"),
+          h("span", { className: "dshm-links-ver" }, `v${version}`)
+        ] : null
       )
     ),
     // ④ 操作记录：恒通宽卡（第二批搬迁），进行中常驻 + 已结束滚动区，空态 hint 导览
@@ -5077,7 +5085,7 @@ var TABS = [
   ["installed", "tab.installed", "installed"],
   ["settings", "tab.settings", null]
 ];
-function DshmVersionChip({ version, notify, initialCheck }) {
+function DshmVersionChip({ version, notify, initialCheck, ops }) {
   const [check, setCheck] = useState(
     () => initialCheck !== void 0 ? initialCheck : typeof window !== "undefined" && window.localStorage ? readSelfCheckCache2(window.localStorage, { version }) : null
   );
@@ -5101,7 +5109,10 @@ function DshmVersionChip({ version, notify, initialCheck }) {
     if (busy) return;
     setBusy(true);
     try {
-      const res = await api("self-upgrade");
+      const res = await (ops ? ops.runOp("upgrade", "dsh-m", async () => {
+        const r = await api("self-upgrade");
+        return { ...r, opMeta: { from: version, to: r.version || "latest" } };
+      }, { npm: "dsh-m" }) : api("self-upgrade"));
       clearSelfCheckCache2(typeof window !== "undefined" && window.localStorage ? window.localStorage : null);
       setCheck({ current: version, latest: null, outdated: false, ahead: false });
       notify({
@@ -5584,7 +5595,7 @@ function MarketPanel({ onClose }) {
           )
         ),
         h("span", { className: "dshm-spacer" }),
-        pluginVersion ? h(DshmVersionChip, { version: pluginVersion, notify }) : null,
+        pluginVersion ? h(DshmVersionChip, { version: pluginVersion, notify, ops }) : null,
         profile && profile.kind !== "web" ? h("span", { className: "dshm-dshchip", title: lookup("profile.chipTitle", { name: profile.name }) }, profile.name) : null,
         // 窗口控制组（0.7.7）：最大化/还原 + 关闭，连体设计（系统化窗口按钮）
         h(
@@ -5612,6 +5623,7 @@ function MarketPanel({ onClose }) {
         tab === "installed" ? h(InstalledTab, { notify, installed, updates, onMutation: refreshViews, ops }) : null,
         tab === "settings" ? h(SettingsTab, {
           notify,
+          version: pluginVersion,
           onRegistryChanged,
           onForceMarket: () => marketReloadAll(true),
           opsRecords: opRecords,

package/lib/core/exclude-governance.js

@@ -231,16 +231,26 @@ export async function registerExclusion(profileDir, target, deps = {}) {
         });
     const file = join(profileDir, WS_FILE);
     try {
+        // 锁前廉价存在性预读（ADR-0019，评审 G1-1）：文件缺席零探测直返 no-file——
+        // 「本地检查先行」契约（钉子测试 + 缺省绑定下测试离线可跑）双保。
+        try {
+            await doRead(file);
+        }
+        catch {
+            return { applied: false, reason: 'no-file' };
+        }
+        // times 出锁（ADR-0019）：发布时戳是不可变历史事实，锁外预取零 TOCTOU——镜像机器
+        // 装机不再在官方文件锁内白等网络腿（最多 5s 首腿 + 12s 备腿）；取数失败 → not-young
+        // （fail-open 口径不变，ADR-0009 判定分支逐字未动）。
+        const times = await (deps.packumentTimes ?? cachedPackumentTimes)(target.pkg, 12_000);
         return await withFileLock(join(profileDir, 'package.json'), async () => {
-            // 本地检查先行：文件缺席直接 no-file（不发 registry 探测——缺省绑定下测试离线可跑）
             let yaml;
             try {
-                yaml = await doRead(file);
+                yaml = await doRead(file); // 锁内重读续走：锁保护的是写，读的 TOCTOU 无害
             }
             catch {
                 return { applied: false, reason: 'no-file' };
             }
-            const times = await (deps.packumentTimes ?? cachedPackumentTimes)(target.pkg, 12_000);
             const now = deps.nowMs ?? Date.now();
             const publishedAt = times ? Date.parse(times[target.version] ?? '') : NaN;
             if (!Number.isFinite(publishedAt))

package/lib/core/packument.js

@@ -0,0 +1,362 @@
+/**
+ * packument 访问器（ADR-0019）：npm 全量 packument 取数的唯一属主模块（GLOSSARY 在案）。
+ * 一次取回按需派生视图（times/versions/distTags/readme/repo），按（pkg, 生效 registry）
+ * 记忆化共享给登记、预检与 B3 预热；latest 小端点探测与其缓存制度（ADR-0006）不在辖区。
+ *
+ * 取数双面：fetchDocThrowing（strict——两腿阶梯，npmjs 首腿 `min(timeoutMs,5s)` 收紧 →
+ * 生效源备腿，终末失败抛原始错误，供 readme 阶梯错误透传）；fetchPackumentDoc（lenient——
+ * 同阶梯 catch → null，times 的 fail-open 口径）。发布时戳是不可变历史事实，TTL 5min 只防
+ * 内存滞留过期内容，不作废旧时戳判定；失败与 regex-invalid 的确定性 null 同按 TTL 负缓存
+ * （故障窗口内预检/登记不二次打网）。
+ *
+ * 腿策略（ADR-0012 消费端）：times 走两腿（完整性敏感读，npmjs 权威优先）；warm 与 readme
+ * 兜底腿走「生效源单腿」（warm 暖的正是 B3 重试要打的 CDN，两腿会让镜像机先付 npmjs 5s
+ * 且暖错对象——评审 G1-3/G2-2 裁决）。onRouteSwitch 作废 + 缓存键含生效源双保险；本模块是
+ * 唯一注册点（release-age 旧注册已随其本地缓存退役）。
+ */
+import { fetchJsonLimited } from './httpx.js';
+import { DEFAULT_NPM_REGISTRY, NPM_MIRROR, activeNpmRegistry, onRouteSwitch, syncNpmmirrorPackage } from './npm-route.js';
+/** npm 包名形状（与既有四函数同一字符集，scoped 允许）。 */
+const PKG_RE = /^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/;
+/** registry base 归一（去尾斜杠；空/缺省 → 官方 npmjs）。 */
+function registryBase(registry) {
+    const base = typeof registry === 'string' && registry.trim() !== '' ? registry.trim() : DEFAULT_NPM_REGISTRY;
+    return base.replace(/\/+$/, '');
+}
+/** 精确 semver：接受 prerelease/build metadata，拒绝 v 前缀、range、tag 与脏尾缀。 */
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export function isExactVersion(version) {
+    return EXACT_VERSION_RE.test(version);
+}
+// ---------- 取数层（strict / lenient 双面） ----------
+/**
+ * strict 面：两腿阶梯取全量 packument，终末失败抛原始错误。
+ * L3 权威链（ADR-0012）：npmjs 首腿超时收紧 `Math.min(timeoutMs, 5_000)`；生效源即 npmjs
+ * 时失败直接抛（权威源无备腿可降）；两腿皆败抛终末腿错误（readme 阶梯的错误透传依赖此约定）。
+ */
+export async function fetchDocThrowing(pkg, timeoutMs = 20_000, signal, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const firstLegMs = Math.min(timeoutMs, 5_000);
+    try {
+        return (await fetcher(`${registryBase(DEFAULT_NPM_REGISTRY)}/${encodeURIComponent(pkg)}`, {
+            timeoutMs: firstLegMs,
+            signal,
+            maxBytes: 8 * 1024 * 1024,
+        }));
+    }
+    catch (firstErr) {
+        const alt = await activeNpmRegistry();
+        if (alt === DEFAULT_NPM_REGISTRY)
+            throw firstErr;
+        return (await fetcher(`${registryBase(alt)}/${encodeURIComponent(pkg)}`, {
+            timeoutMs,
+            signal,
+            maxBytes: 8 * 1024 * 1024,
+        }));
+    }
+}
+/** lenient 面：同阶梯 catch → null（times 的 fail-open 口径；regex-invalid 亦 null）。 */
+export async function fetchPackumentDoc(pkg, timeoutMs = 20_000, signal, deps) {
+    try {
+        return await fetchDocThrowing(pkg, timeoutMs, signal, deps);
+    }
+    catch {
+        return null;
+    }
+}
+/** 生效源单腿 strict 取数（warm 与 readme 兜底腿的取数原语；失败抛原始错误）。返回 doc 与取数所用 base——调用方回填键必须用同一 base（评审 R1-1：一次生效源判定贯穿取数与回填，杜绝路由切换窗口的键错配）。 */
+async function fetchDocViaActiveThrowing(pkg, timeoutMs, signal, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const base = await activeNpmRegistry();
+    const doc = (await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}`, {
+        timeoutMs,
+        signal,
+        maxBytes: 8 * 1024 * 1024,
+    }));
+    return { doc, base };
+}
+// ---------- 视图层 ----------
+/** packument repository → "owner/repo"（仅 github.com；git+https / git@ / .git / #frag 归一；非 GitHub 返回空串）。 */
+export function extractGithubRepo(v) {
+    const url = v && typeof v === 'object' && !Array.isArray(v) && typeof v.url === 'string'
+        ? v.url
+        : typeof v === 'string'
+            ? v
+            : '';
+    if (!url)
+        return '';
+    const m = /github\.com[/:]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?(?:[/?#]|$)/i.exec(url);
+    return m ? `${m[1]}/${m[2]}` : '';
+}
+/** 全量 packument → 派生视图包（纯函数；畸形字段一律回落默认值，不抛）。 */
+export function packumentViews(doc) {
+    const d = doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {};
+    const times = {};
+    const t = d.time;
+    if (t && typeof t === 'object' && !Array.isArray(t)) {
+        for (const [k, v] of Object.entries(t)) {
+            if (typeof v === 'string' && v !== '')
+                times[k] = v;
+        }
+    }
+    const versions = d.versions && typeof d.versions === 'object' && !Array.isArray(d.versions) ? Object.keys(d.versions) : [];
+    const distTags = d['dist-tags'] && typeof d['dist-tags'] === 'object' && !Array.isArray(d['dist-tags'])
+        ? d['dist-tags']
+        : {};
+    const readme = typeof d.readme === 'string' && d.readme.trim() !== '' ? d.readme : '';
+    return { times, versions, distTags, readme, repo: extractGithubRepo(d.repository) };
+}
+const packumentCache = new Map();
+const packumentInflight = new Map();
+const PACKUMENT_TTL_MS = 5 * 60_000;
+const PACKUMENT_CAP = 4;
+function packumentKey(pkg, registry) {
+    return `${pkg}\n${registry}`;
+}
+function backfill(key, views) {
+    if (packumentCache.has(key))
+        packumentCache.delete(key); // 重写移尾：淘汰语义 = 最旧写入
+    packumentCache.set(key, { at: Date.now(), views });
+    if (packumentCache.size > PACKUMENT_CAP) {
+        const oldest = packumentCache.keys().next().value;
+        if (oldest !== undefined)
+            packumentCache.delete(oldest);
+    }
+}
+/** 路由作废（ADR-0012 L1：生效源切换 → 缓存整体作废）；亦是测试隔离钩子。 */
+export function clearPackumentAccessorCache() {
+    packumentCache.clear();
+    packumentInflight.clear();
+}
+onRouteSwitch(() => clearPackumentAccessorCache());
+/** lenient 带缓存取数（times/全视图共用；single-flight；失败/非法 → null 负缓存）。 */
+async function entryLenient(pkg, timeoutMs, signal, deps) {
+    const key = packumentKey(pkg, await activeNpmRegistry());
+    const hit = packumentCache.get(key);
+    if (hit && Date.now() - hit.at < PACKUMENT_TTL_MS)
+        return hit.views;
+    const existing = packumentInflight.get(key);
+    if (existing)
+        return existing;
+    const p = (async () => {
+        let views = null;
+        try {
+            views = packumentViews(await fetchDocThrowing(pkg, timeoutMs, signal, deps));
+        }
+        catch {
+            views = null;
+        }
+        backfill(key, views);
+        return views;
+    })().finally(() => {
+        packumentInflight.delete(key);
+    });
+    packumentInflight.set(key, p);
+    return p;
+}
+/** 带缓存发布时戳表（预检/登记消费；语义 = 旧 cachedPackumentTimes：失败 null 不抛）。 */
+export async function packumentTimes(pkg, timeoutMs = 12_000, signal, deps) {
+    const views = await entryLenient(pkg, timeoutMs, signal, deps);
+    return views ? views.times : null;
+}
+/** 带缓存全视图（npmPackument 隐式 registry 路径消费）。 */
+export async function packumentDocViews(pkg, timeoutMs = 20_000, signal, deps) {
+    return entryLenient(pkg, timeoutMs, signal, deps);
+}
+/**
+ * 生效源单腿带缓存全视图（readme 隐式 registry 兜底腿专用，G2-2 方案 a）：命中（且非
+ * 负缓存）直回；miss/负缓存 → 单腿 strict 重取（失败抛原始错误）+ 回填。负缓存条目仅
+ * lenient 面消费——strict 面视 null 为 miss，保终末错误透传（≈现状无缓存每次尝试）。
+ */
+export async function packumentDocViewsActive(pkg, timeoutMs = 20_000, signal, deps) {
+    const key = packumentKey(pkg, await activeNpmRegistry());
+    const hit = packumentCache.get(key);
+    if (hit && Date.now() - hit.at < PACKUMENT_TTL_MS && hit.views !== null)
+        return hit.views;
+    const { doc, base } = await fetchDocViaActiveThrowing(pkg, timeoutMs, signal, deps);
+    const views = packumentViews(doc);
+    backfill(packumentKey(pkg, base), views);
+    return views;
+}
+/**
+ * B3 预热（G1-3 裁决）：bypass 缓存读 + 生效源单腿直取 + 成功回填——预热的目的就是真发
+ * 请求暖 CDN（B3 重试要打的正是生效源），缓存命中≠预热；失败/abort 异常向上传播（调用方
+ * makeNpmWarmPackument 按 R4c 消化：abort rethrow、其余吞错）。
+ */
+export async function warmPackumentFor(pkg, timeoutMs = 20_000, signal, deps) {
+    const { doc, base } = await fetchDocViaActiveThrowing(pkg, timeoutMs, signal, deps);
+    backfill(packumentKey(pkg, base), packumentViews(doc));
+}
+function sleepAbortable(ms, signal) {
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(t);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const t = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/**
+ * 精确版本元数据（兼容预检/integrity 锚定）。L2① 履约阶梯（ADR-0012）：
+ * 显式 registry 参数 > 生效源 → 失败且生效源为镜像 → sync → 有界等待 10s → 同源重试一次
+ * → 仍败 → npmjs 兜底（sync+重试为尽力而为，npmjs 兜底是主安全网）；
+ * 主源即 npmjs 时失败直接抛（权威源无镜像滞后可言）。
+ */
+export async function npmVersion(pkg, version, timeoutMs = 20_000, signal, registry, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    if (!isExactVersion(version))
+        throw new Error(`不是精确版本（拒绝 range/tag/前缀）: ${version}`);
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const sync = deps?.syncNpmmirror ?? syncNpmmirrorPackage;
+    const wait = deps?.wait ?? sleepAbortable;
+    const leg = async (base) => {
+        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
+        const resolved = typeof data.version === 'string' ? data.version : '';
+        if (!resolved)
+            throw new Error(`npm 未返回版本: ${pkg}@${version}`);
+        const peers = {};
+        if (data.peerDependencies !== null && typeof data.peerDependencies === 'object') {
+            for (const [name, range] of Object.entries(data.peerDependencies)) {
+                if (typeof range === 'string')
+                    peers[name] = range;
+            }
+        }
+        return {
+            version: resolved,
+            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
+            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+            peers,
+        };
+    };
+    const primary = registry?.trim() ? registry.trim() : await activeNpmRegistry();
+    try {
+        return await leg(primary);
+    }
+    catch (firstErr) {
+        // L2①（ADR-0012）：仅 sync 真正受理才重试镜像（kill switch / 同步失败不付 10s 等待）。
+        if (primary === NPM_MIRROR && (await sync(pkg))) {
+            await wait(10_000, signal);
+            try {
+                return await leg(primary);
+            }
+            catch {
+                // 同源重试仍败 → npmjs 兜底
+            }
+        }
+        if (primary !== DEFAULT_NPM_REGISTRY)
+            return leg(DEFAULT_NPM_REGISTRY);
+        throw firstErr;
+    }
+}
+/**
+ * 升级探测（检测读）。L3 权威链（ADR-0012）：新鲜度敏感——npmjs 权威源优先
+ * （首腿超时收紧 `Math.min(timeoutMs, 5_000)`），失败降级生效源（≠npmjs 时）；
+ * 不设 sync 腿。显式 registry 参数优先。
+ */
+export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const leg = async (base, ms) => {
+        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs: ms, signal });
+        const version = typeof data.version === 'string' ? data.version : '';
+        if (!version)
+            throw new Error(`npm 未返回版本: ${pkg}`);
+        return {
+            version,
+            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
+            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+        };
+    };
+    const explicit = registry?.trim();
+    if (explicit)
+        return leg(explicit, timeoutMs);
+    const firstLegMs = Math.min(timeoutMs, 5_000);
+    try {
+        return await leg(DEFAULT_NPM_REGISTRY, firstLegMs);
+    }
+    catch (firstErr) {
+        const alt = await activeNpmRegistry();
+        if (alt === DEFAULT_NPM_REGISTRY)
+            throw firstErr;
+        return leg(alt, timeoutMs);
+    }
+}
+/**
+ * 拉取完整 packument（NO_MATCHING_VERSION 退避重试前的预热/校验原语）。
+ * 返回该包已知的全部版本号；解析不出 versions 时返回空列表（不抛）。
+ * 隐式 registry → 访问器缓存（lenient 两腿面；该路径在 B3 改用 warmPackumentFor 后已无
+ * 生产消费方，仅测试触达——G3-2 备案）；显式 registry 直取不走缓存。
+ */
+export async function npmPackument(pkg, timeoutMs = 20_000, signal, registry, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    const explicit = registry?.trim();
+    if (!explicit) {
+        const views = await packumentDocViews(pkg, timeoutMs, signal, deps?.fetchJsonLimited ? { fetchJsonLimited: deps.fetchJsonLimited } : undefined);
+        if (!views)
+            throw new Error(`packument 不可用: ${pkg}`);
+        return { versions: views.versions };
+    }
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const data = await fetcher(`${registryBase(explicit)}/${encodeURIComponent(pkg)}`, {
+        timeoutMs,
+        signal,
+        maxBytes: 8 * 1024 * 1024,
+    });
+    const versions = data?.versions !== null && typeof data?.versions === 'object' ? Object.keys(data.versions) : [];
+    return { versions };
+}
+/**
+ * npm packument readme 兜底（0.9.45 U10b / 0.9.50 两腿阶梯）：腿1 `/latest` 小端点优先
+ * （KB 级载荷，超时收紧 `min(timeoutMs,5s)`），readme 命中即短路；空或腿失败落腿2
+ * packument。任一腿成功即成功——readme 空渲染「没有 README」（含 latest 空白 readme +
+ * packument 失败的降级，不抛）；两腿全败抛终末腿（packument）错误。两腿均在生效源。
+ * 0.9.86：腿2 隐式 registry 改走访问器「生效源单腿带缓存」面（G2-2 方案 a——腿策略与
+ * 现状单腿一致，不换两腿；共享缓存）；显式 registry 直取不走缓存。
+ */
+export async function npmPackumentReadme(pkg, timeoutMs = 20_000, signal, registry, deps) {
+    if (!PKG_RE.test(pkg))
+        throw new Error(`无效 npm 包名: ${pkg}`);
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const explicit = registry?.trim();
+    const base = explicit ? registryBase(explicit) : registryBase(await activeNpmRegistry());
+    const extractReadme = (data) => typeof data?.readme === 'string' && data.readme.trim() !== '' ? data.readme : '';
+    // 腿1：/latest 版本文档（小载荷；超时收紧同 npmLatest 首腿先例）
+    let latestOk = false;
+    let latestRepo = '';
+    try {
+        const latestDoc = await fetcher(`${base}/${encodeURIComponent(pkg)}/latest`, { timeoutMs: Math.min(timeoutMs, 5_000), signal, maxBytes: 8 * 1024 * 1024 });
+        latestOk = true;
+        latestRepo = extractGithubRepo(latestDoc?.repository);
+        const latestReadme = extractReadme(latestDoc);
+        if (latestReadme)
+            return { readme: latestReadme, repo: latestRepo };
+    }
+    catch {
+        // latest 腿失败 → 落 packument 腿（终末腿语义见下）
+    }
+    // 腿2：packument（终末腿）——隐式 registry 走访问器 Active 面（单腿带缓存 + 错误透传）
+    try {
+        if (explicit) {
+            const data = await fetcher(`${base}/${encodeURIComponent(pkg)}`, { timeoutMs, signal, maxBytes: 8 * 1024 * 1024 });
+            return { readme: extractReadme(data), repo: extractGithubRepo(data?.repository) };
+        }
+        const views = await packumentDocViewsActive(pkg, timeoutMs, signal, deps?.fetchJsonLimited ? { fetchJsonLimited: deps.fetchJsonLimited } : undefined);
+        return { readme: views.readme, repo: views.repo };
+    }
+    catch (packumentErr) {
+        if (latestOk) {
+            // latest 到达但 readme 空 + packument 失败 → 降级空 readme（0.9.50 语义，不抛）
+            return { readme: '', repo: latestRepo };
+        }
+        throw packumentErr;
+    }
+}

package/lib/core/profile-transaction.js

@@ -37,7 +37,7 @@ import { join } from 'node:path';
 import { webProfileDir } from './env.js';
 import { isSafePkgName, resolvePluginDir } from './installed.js';
 import { setLivePluginDisabled } from './live-plugin.js';
-import { npmPackument } from './versions.js';
+import { warmPackumentFor } from './packument.js';
 import { syncNpmmirrorPackage } from './npm-route.js';
 import { clearAllLatestCache } from './latest-cache.js';
 import { assertNpmIntegrity, atomicWriteFile, readPnpmLockIntegrity, readPnpmLockOverrides, restoreSnapshots, snapshotFiles, verifySnapshots, } from './npm-integrity.js';
@@ -65,7 +65,11 @@ export const TX_FAILURE_CODES = [
  * fetcher 参数仅测试注入；失败吞错。deps 未提供且调用方未绑定时，
  * 事务内 B3 跳过预热仅重试——绝不调用 undefined。
  */
-export function makeNpmWarmPackument(timeoutMs, fetcher = npmPackument) {
+export function makeNpmWarmPackument(timeoutMs, 
+// 0.9.86（ADR-0019）：缺省 fetcher 改 warmPackumentFor——bypass 缓存 + 生效源单腿真发请求
+// （预热的目的就是暖 CDN）+ 成功回填访问器缓存；abort 由本包装按 R4c 消化（rethrow）、
+// 其余失败吞错（预热尽力而为）不变。
+fetcher = warmPackumentFor) {
     return async (pkg, signal) => {
         try {
             await fetcher(pkg, timeoutMs, signal);

package/lib/core/release-age.js

@@ -26,8 +26,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
-import { fetchJsonLimited } from './httpx.js';
-import { DEFAULT_NPM_REGISTRY, activeNpmRegistry, onRouteSwitch } from './npm-route.js';
+import { clearPackumentAccessorCache, fetchPackumentDoc, packumentTimes, packumentViews } from './packument.js';
 /** pnpm 11.7 实机测得的策略窗口：24h（operation-l5fXEd 的 cutoff = 检查时刻 − 1440min）。 */
 export const DEFAULT_MINIMUM_RELEASE_AGE_MIN = 1440;
 function scalarNumber(value) {
@@ -148,46 +147,13 @@ export function describeReleaseAgeFailure(input) {
     lines.push(`预计 ${fmtLocal(maxDeadline)} 后可重试；等待期内也可由操作员把 pnpm-workspace.yaml 中对应的独立精确排除条目改为包名级或复合条目以解除拦截`);
     return { message: lines.join('\n'), violations, targetViolating: targetViol !== undefined };
 }
-async function fetchPackumentTimes(base, pkg, timeoutMs, signal, fetcher) {
-    const data = await fetcher(`${base}/${encodeURIComponent(pkg)}`, {
-        timeoutMs,
-        signal,
-        maxBytes: 8 * 1024 * 1024,
-    });
-    if (!data || typeof data !== 'object' || data.time === null || typeof data.time !== 'object')
-        return null;
-    const out = {};
-    for (const [k, v] of Object.entries(data.time)) {
-        if (typeof v === 'string')
-            out[k] = v;
-    }
-    return out;
-}
 /**
- * registry packument 的 time 映射（与 npmPackument 同源；失败返回 null，不抛）。
- * L3 权威链（ADR-0012）：发布时刻是完整性敏感读——npmjs 权威源优先（首腿超时收紧
- * `Math.min(timeoutMs, 5_000)`），失败降级生效源；两腿皆败 → null（fail-open 口径不变）。
+ * registry packument 的 time 映射（0.9.86 起薄委托 packument 访问器，ADR-0019：两腿阶梯
+ * 单份活代码于 fetchDocThrowing）。失败返回 null，不抛；L3 权威链（ADR-0012）语义不变。
  */
 export async function npmPackumentTimes(pkg, timeoutMs = 20_000, signal, deps) {
-    if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
-        return null;
-    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
-    const firstLegMs = Math.min(timeoutMs, 5_000);
-    try {
-        return await fetchPackumentTimes(DEFAULT_NPM_REGISTRY, pkg, firstLegMs, signal, fetcher);
-    }
-    catch {
-        // 权威源不可达 → 生效源降级
-    }
-    const alt = await activeNpmRegistry();
-    if (alt === DEFAULT_NPM_REGISTRY)
-        return null;
-    try {
-        return await fetchPackumentTimes(alt, pkg, timeoutMs, signal, fetcher);
-    }
-    catch {
-        return null;
-    }
+    const doc = await fetchPackumentDoc(pkg, timeoutMs, signal, deps);
+    return doc ? packumentViews(doc).times : null;
 }
 /** 读 profile 的 pnpm-workspace.yaml 策略；缺席/不可读 → null（调用方 fail-open）。 */
 export async function readWorkspacePolicy(profileDir) {
@@ -200,28 +166,20 @@ export async function readWorkspacePolicy(profileDir) {
         return null;
     }
 }
-const packumentCache = new Map();
-const PACKUMENT_CACHE_TTL_MS = 5 * 60_000;
-/** L1（ADR-0012）：npm 生效源切换 → 作废 packument 缓存（镜像的答案不是官方源的答案）。 */
-export function clearPackumentCache() {
-    packumentCache.clear();
-}
-onRouteSwitch(() => clearPackumentCache());
 /**
- * 带进程内缓存的 packument time 探测（TTL 5min）：预检与登记（exclude-governance）
- * 共用——同一操作里预检刚拉过的 packument 不二次拉取（8MiB 级全量）。
+ * 0.9.86 薄委托（ADR-0019）：本地 Map/TTL/路由注册整体退役——缓存与作废语义由 packument
+ * 访问器属主承担（single-flight/TTL 5min/负缓存/cap=4/onRouteSwitch 唯一注册均在彼处）。
  */
+export function clearPackumentCache() {
+    clearPackumentAccessorCache();
+}
+/** 带缓存 packument time 探测（预检与登记共用）：薄委托访问器 times 视图，签名与语义不变。 */
 export async function cachedPackumentTimes(pkg, timeoutMs = 12_000, signal, deps) {
-    const hit = packumentCache.get(pkg);
-    if (hit && Date.now() - hit.at < PACKUMENT_CACHE_TTL_MS)
-        return hit.times;
-    const times = await npmPackumentTimes(pkg, timeoutMs, signal, deps);
-    packumentCache.set(pkg, { at: Date.now(), times });
-    return times;
+    return packumentTimes(pkg, timeoutMs, signal, deps);
 }
-/** 测试钩子：清空 packument 进程内缓存。 */
+/** 测试钩子：清空 packument 进程内缓存（现属访问器）。 */
 export function _resetReleaseAgeCachesForTests() {
-    packumentCache.clear();
+    clearPackumentAccessorCache();
 }
 /**
  * 委派前预检（ADR-0009 收敛语义）：仅当策略显式设置 age 或开启 strict 时，对窗口内

package/lib/core/versions.js

@@ -3,10 +3,15 @@
  * npm：registry /latest（pnpm 安装本身会按 lock integrity 校验 tarball）。
  * GitHub：优先最新 release/tag（更新提示只跟稳定版走，不跟 main HEAD——中间提交可能不稳定）；
  * 未认证限额 60 次/小时，自用足够。
+ *
+ * 0.9.86（ADR-0019）：npm registry 元数据族（npmVersion/npmPackument/npmPackumentReadme/
+ * npmLatest/extractGithubRepo/isExactVersion 及其类型）实现已迁入 packument 访问器属主模块；
+ * 本文件原名 re-export 保全部 import 位零改动，自身只留 GitHub 族。
  */
 import { gt } from 'semver';
 import { fetchJsonLimited, HttpError } from './httpx.js';
-import { DEFAULT_NPM_REGISTRY, NPM_MIRROR, activeNpmRegistry, syncNpmmirrorPackage } from './npm-route.js';
+import { isExactVersion } from './packument.js';
+export { npmVersion, npmPackument, npmPackumentReadme, npmLatest, extractGithubRepo, isExactVersion, } from './packument.js';
 /** GitHub 匿名限额（60 次/小时/IP）用尽时返回可读提示（含重置等待分钟数），否则 null。 */
 function githubRateLimitMessage(err) {
     if (err instanceof HttpError && err.status === 403 && err.headers?.get('x-ratelimit-remaining') === '0') {
@@ -20,195 +25,6 @@ function githubRateLimitMessage(err) {
     }
     return null;
 }
-/** registry base 归一（去尾斜杠；空/缺省 → 官方 npmjs）。 */
-function registryBase(registry) {
-    const base = typeof registry === 'string' && registry.trim() !== '' ? registry.trim() : 'https://registry.npmjs.org';
-    return base.replace(/\/+$/, '');
-}
-/** 精确 semver：接受 prerelease/build metadata，拒绝 v 前缀、range、tag 与脏尾缀。 */
-const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-export function isExactVersion(version) {
-    return EXACT_VERSION_RE.test(version);
-}
-function sleepAbortable(ms, signal) {
-    return new Promise((resolve) => {
-        const done = () => {
-            clearTimeout(t);
-            signal?.removeEventListener('abort', done);
-            resolve();
-        };
-        const t = setTimeout(done, ms);
-        signal?.addEventListener('abort', done, { once: true });
-    });
-}
-/**
- * 精确版本元数据（兼容预检/integrity 锚定）。L2① 履约阶梯（ADR-0012）：
- * 显式 registry 参数 > 生效源 → 失败且生效源为镜像 → sync → 有界等待 10s → 同源重试一次
- * → 仍败 → npmjs 兜底（sync+重试为尽力而为，npmjs 兜底是主安全网）；
- * 主源即 npmjs 时失败直接抛（权威源无镜像滞后可言）。
- */
-export async function npmVersion(pkg, version, timeoutMs = 20_000, signal, registry, deps) {
-    if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
-        throw new Error(`无效 npm 包名: ${pkg}`);
-    if (!isExactVersion(version))
-        throw new Error(`不是精确版本（拒绝 range/tag/前缀）: ${version}`);
-    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
-    const sync = deps?.syncNpmmirror ?? syncNpmmirrorPackage;
-    const wait = deps?.wait ?? sleepAbortable;
-    const leg = async (base) => {
-        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
-        const resolved = typeof data.version === 'string' ? data.version : '';
-        if (!resolved)
-            throw new Error(`npm 未返回版本: ${pkg}@${version}`);
-        const peers = {};
-        if (data.peerDependencies !== null && typeof data.peerDependencies === 'object') {
-            for (const [name, range] of Object.entries(data.peerDependencies)) {
-                if (typeof range === 'string')
-                    peers[name] = range;
-            }
-        }
-        return {
-            version: resolved,
-            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
-            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
-            peers,
-        };
-    };
-    const primary = registry?.trim() ? registry.trim() : await activeNpmRegistry();
-    try {
-        return await leg(primary);
-    }
-    catch (firstErr) {
-        // L2①（ADR-0012）：仅 sync 真正受理（评审 R1-2：kill switch / 同步失败返回 false 时
-        // 不付 10s 等待成本、不发必 404 的同源重试——「风险与回退」承诺的行为回到现状）才重试镜像。
-        if (primary === NPM_MIRROR && (await sync(pkg))) {
-            await wait(10_000, signal);
-            try {
-                return await leg(primary);
-            }
-            catch {
-                // 同源重试仍败 → npmjs 兜底
-            }
-        }
-        if (primary !== DEFAULT_NPM_REGISTRY)
-            return leg(DEFAULT_NPM_REGISTRY);
-        throw firstErr;
-    }
-}
-/**
- * 拉取完整 packument（NO_MATCHING_VERSION 退避重试前的预热/校验原语）。
- * 返回该包已知的全部版本号；解析不出 versions 时返回空列表（不抛）。
- * L1（ADR-0012/R1-6）：registry 参数曾被忽略——现「显式参数 > 生效源」。
- */
-export async function npmPackument(pkg, timeoutMs = 20_000, signal, registry, deps) {
-    if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
-        throw new Error(`无效 npm 包名: ${pkg}`);
-    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
-    const base = registry?.trim() ? registry.trim() : await activeNpmRegistry();
-    const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}`, {
-        timeoutMs,
-        signal,
-        maxBytes: 8 * 1024 * 1024,
-    });
-    const versions = data?.versions !== null && typeof data?.versions === 'object' ? Object.keys(data.versions) : [];
-    return { versions };
-}
-/**
- * packument repository → "owner/repo"（仅 github.com；git+https / git@ / .git / #frag 归一；
- * 非 GitHub 返回空串——README 相对路径锚定只对 GitHub raw/blob 有意义）。0.9.48。
- */
-export function extractGithubRepo(v) {
-    const url = typeof v === 'string'
-        ? v
-        : v && typeof v === 'object' && typeof v.url === 'string'
-            ? v.url
-            : '';
-    if (!url)
-        return '';
-    const m = /github\.com[/:]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?(?:[/?#]|$)/i.exec(url);
-    return m ? `${m[1]}/${m[2]}` : '';
-}
-/**
- * npm packument readme 兜底（0.9.45 U10b 修复）：市场/收藏详情 Modal 的 README 折叠页对
- * 「未安装」条目无法走本地 profile 读取——回源 npm 兜底。安全基线同 npmPackument：HTTPS、
- * 8MB 上限；无 readme 字段返回空串（不抛，客户端显示「没有 README」）；L1（ADR-0012）：
- * 显式 registry 参数 > 生效源。
- * 0.9.48：随附 repo（repository 归一为 owner/repo，仅 GitHub），供 README 相对链接/图片
- * 锚定仓库基址；无 repository 或非 GitHub 时为空串。
- * 0.9.50：两腿阶梯——腿1 `/latest` 版本文档优先（KB 级小载荷，超大 packument 超帽免疫；
- * 超时收紧 `Math.min(timeoutMs, 5_000)`，同 npmLatest 首腿先例），readme 命中即短路；空或
- * 腿失败落腿2 packument（20s 满额，行为同 0.9.45）。任一腿成功即成功——readme 空渲染
- * 「没有 README」（含 latest 空白 readme + packument 失败的降级，不抛）；两腿全败抛终末腿
- * （packument）错误。两腿均在生效源，不跨源；两腿 readme 判空同一 trim 规则。repo 随到达
- * 的腿取 repository（packument 到达时以 packument 为准）。
- */
-export async function npmPackumentReadme(pkg, timeoutMs = 20_000, signal, registry, deps) {
-    if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
-        throw new Error(`无效 npm 包名: ${pkg}`);
-    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
-    const base = registry?.trim() ? registry.trim() : await activeNpmRegistry();
-    const extractReadme = (data) => typeof data?.readme === 'string' && data.readme.trim() !== '' ? data.readme : '';
-    // 腿1：/latest 版本文档（小载荷；超时收紧同 npmLatest 首腿先例）
-    let latestOk = false;
-    let latestRepo = '';
-    try {
-        const latestDoc = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs: Math.min(timeoutMs, 5_000), signal, maxBytes: 8 * 1024 * 1024 });
-        latestOk = true;
-        latestRepo = extractGithubRepo(latestDoc?.repository);
-        const latestReadme = extractReadme(latestDoc);
-        if (latestReadme)
-            return { readme: latestReadme, repo: latestRepo };
-    }
-    catch {
-        // latest 腿失败 → 落 packument 腿（终末腿语义见下）
-    }
-    // 腿2：packument（0.9.45 U10b 原兜底腿，行为不变）
-    try {
-        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}`, { timeoutMs, signal, maxBytes: 8 * 1024 * 1024 });
-        return { readme: extractReadme(data), repo: extractGithubRepo(data?.repository) };
-    }
-    catch (packumentErr) {
-        // latest 腿已成功证明包在而无有效 readme → 降级成功（空 readme），不冒充失败
-        if (latestOk)
-            return { readme: '', repo: latestRepo };
-        throw packumentErr;
-    }
-}
-/**
- * 升级探测（检测读）。L3 权威链（ADR-0012）：新鲜度敏感——npmjs 权威源优先
- * （首腿超时收紧 `Math.min(timeoutMs, 5_000)`），失败降级生效源（≠npmjs 时）；
- * 不设 sync 腿（两腿全败属网络型失败，sync 只救镜像滞后）。显式 registry 参数优先。
- */
-export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry, deps) {
-    // 允许 scoped 包名：@scope/name（isSafePkgName 同款字符集）
-    if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
-        throw new Error(`无效 npm 包名: ${pkg}`);
-    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
-    const leg = async (base, ms) => {
-        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs: ms, signal });
-        const version = typeof data.version === 'string' ? data.version : '';
-        if (!version)
-            throw new Error(`npm 未返回版本: ${pkg}`);
-        return {
-            version,
-            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
-            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
-        };
-    };
-    const explicit = registry?.trim();
-    if (explicit)
-        return leg(explicit, timeoutMs);
-    const firstLegMs = Math.min(timeoutMs, 5_000);
-    try {
-        return await leg(DEFAULT_NPM_REGISTRY, firstLegMs);
-    }
-    catch (firstErr) {
-        const alt = await activeNpmRegistry();
-        if (alt === DEFAULT_NPM_REGISTRY)
-            throw firstErr;
-        return leg(alt, timeoutMs);
-    }
-}
 export async function githubTagSha(repo, tag, timeoutMs = 20_000, signal, budget, apiBase = 'https://api.github.com') {
     // commits/{ref} 会自动解引用 annotated tag，返回的才是可用于 #sha 锁定的 commit
     const data = await fetchJsonLimited(`${apiBase}/repos/${repo}/commits/${encodeURIComponent(tag)}`, {
@@ -386,7 +202,7 @@ export async function githubLatestTag(repo, timeoutMs = 20_000, signal, budget,
  */
 export function isNewerVersion(candidate, current) {
     // 只接受精确 semver（与收录语义一致：v 前缀/range/tag 不参与比较）；非法输入不抛、一律 false
-    if (!EXACT_VERSION_RE.test(String(candidate ?? '')) || !EXACT_VERSION_RE.test(String(current ?? '')))
+    if (!isExactVersion(String(candidate ?? '')) || !isExactVersion(String(current ?? '')))
         return false;
     try {
         return gt(String(candidate), String(current));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-m",
-  "version": "0.9.83",
+  "version": "0.9.86",
   "description": "可自定义收录清单的 DSH 插件市场：收录、安装、卸载、升级一站完成，附 agent 工具与 dshm CLI。",
   "license": "MIT",
   "type": "module",