dsh-best-ip 1.1.1 → 1.2.0

package/README.md

@@ -12,9 +12,28 @@ Benchmark the current DSH default model's API IPs. Testing recommends an address
 
 需要带有插件管理器、默认模型、Settings、凭据和 Web 服务的 DSH。当前兼容声明为 `>=0.2.1-rc.1`，包含 rc.1、rc.2、rc.3 及后续版本，不设版本上限；这只是安装版本范围，不代表所有后续版本都已实测兼容。Node.js 要求 `>=22`，无需单独安装运行时依赖。仅支持使用 API Key 的默认供应商，暂不支持 OAuth 或其他模型适配器。
 
+### 从 npm 安装（推荐）
+
+插件已发布到 npm，可直接按包名安装，无需克隆仓库：
+
+1. 在 DSH 侧栏打开 **插件 → 添加插件 / 安装第三方插件**。
+2. 在安装来源中填写包名：
+
+   ```text
+   dsh-best-ip
+   ```
+
+   需要固定版本时填写实际已发布的版本号，例如 `dsh-best-ip@1.2.0`。
+3. 确认信任该插件，点击 **安装**，随后选择 **立即启用**。
+4. 打开 **设置 → 模型节点优选**。
+
+包页面：https://www.npmjs.com/package/dsh-best-ip
+
+若你的 DSH 使用国内 npm 镜像且暂时提示找不到包，等待镜像同步，或手动触发 https://npmmirror.com/sync/dsh-best-ip 后再试。
+
 ### 从 GitHub 安装
 
-仓库推送完成且允许其他人读取后：
+适用于想跟随源码最新提交，或在插件尚未发布到 npm 时：
 
 1. 在 DSH 侧栏打开 **插件 → 添加插件 / 安装第三方插件**。
 2. 在安装来源中填写：
@@ -32,18 +51,19 @@ Benchmark the current DSH default model's API IPs. Testing recommends an address
 
 维护者运行 `npm pack` 生成 `.tgz` 后，可以将它作为 GitHub Release 附件分发。在同一个安装输入框中填写该包在 **DSH Host 上的绝对路径**；这不是浏览器文件上传。远程 Web 用户应使用服务器能读取的路径。
 
-发布到 npm 后，也可在安装输入框中填写 `dsh-best-ip@版本号`。GitHub/tgz 安装不要求先发布 npm；仅创建仓库或发布 npm 不会自动进入 DSH 的 Discover 列表，Discover 需要配置第三方插件索引。
+这三种方式都可以安装同一个插件，按名字或 tgz 安装不要求仓库可匿名读取。仅创建仓库或发布 npm 不会自动进入 DSH 的 Discover 列表，Discover 需要配置第三方插件索引。
 
 ## 使用
 
 - **自动测速**：发现有效 IP、测速并保存推荐，不改变当前 IP。
 - **自动测速并应用**：成功后应用本轮推荐；失败或停止时保留原 IP。
-- **最大测速 IP 数**：`10 / 任意（自定义） / 全部`，默认全部。按 ping 从低到高选取，失败的 IP 也占用名额，不用更慢地址补位。当前选择立即用于两个按钮，点击保存可长期保留。
+- **当前 IP 对照**：已保存应用的 IPv4 会在下次测试中重新纳入同一供应商/域名的候选，首轮优先实测；即使 DNS 或随机扫描没返回它，也不会漏测。只保存了推荐、尚未应用的地址不作对照；重复地址只测一份。
+- **最大测速 IP 数**：`10 / 任意（自定义） / 全部`，默认全部。正数上限内先给已选 IP 保留一个名额，其余按 ping 从低到高选取，例如 10 个是“当前地址 + 9 个新候选”，不会额外扩大付费预算；上限为 1 时仅测当前地址。失败也占名额，不用更慢地址补位。未限数量时，已选 IP 至多额外增加一个候选。显式 `only` 子集仍是权威范围，不会强行插入被排除的地址。当前选择立即用于两个按钮，点击保存可长期保留。
 - **测一下当前地址**：仅测试当前生效地址；未应用 IP 时使用系统 DNS 的 IPv4 地址，不改变选择。
 - **停止测试**：取消在途和排队请求，保留已完成样本，不应用部分结果。已发出的请求可能已经计费。
 - **应用此地址 / 清除并恢复系统 DNS**：显式应用或清除选择。
 
-页面默认显示 **全部最多约12w token**，旁边的 **!** 图标悬停可查看详细预算：160 个有效 IP × 3 次 × 最多 256 输出 token = 122,880 输出 token，另计输入 token。160 是额外扫描预算，DNS 返回地址可能额外增加；实际费用取决于有效 IP、输出长度及供应商计费。
+页面默认显示 **全部最多约12w token**，旁边的 **!** 图标悬停可查看详细预算：160 个有效 IP × 3 次 × 最多 256 输出 token = 122,880 输出 token，另计输入 token。160 是额外扫描预算，DNS 返回地址和上次已选 IP 可能额外增加；实际费用取决于有效 IP、输出长度及供应商计费。
 
 插件始终跟随目标用户的 DSH 默认供应商/模型，不携带预设供应商 ID、API 地址、凭据或已选 IP。切换默认模型不会自动测速。
 
@@ -55,15 +75,25 @@ Benchmark the current DSH default model's API IPs. Testing recommends an address
 | --- | --- | --- |
 | `maxBenchmarkIps` | `0` | 0 为全部，正整数为付费测速 IP 上限 |
 | `maxCandidates` | `160` | 额外 Cloudflare 地址探测上限，不含 DNS 返回地址 |
-| `benchmarkRuns` | `3` | 每个入选 IP 的相同复测次数，范围 1–5 |
+| `benchmarkRuns` | `3` | 每个入选 IP 的计划次数，范围 1–5；最后一轮允许跳过已证明无竞争力的失败尾部 |
+| `benchmarkTimeoutMs` | `60000` | 单次付费测速的总超时（连接至流结束），整数毫秒，范围 1000–300000；与 DNS、探测超时独立 |
+| `adaptiveBenchmarkTimeout` | `true` | 有足够健康节点时，缩短上一轮超时节点的下一次等待；设为 `false` 则始终使用基础超时 |
+| `adaptiveBenchmarkSampling` | `true` | 最后一轮优先确认领先者，并按乐观分数上界跳过失败尾部；设为 `false` 则测满计划次数（仍按新评分安排轮间顺序） |
 | `scanEdges` | `true` | 在 DNS 地址之外采样 Cloudflare 边缘网段 |
 | `dnsServers` | 公共 DNS 列表 | 只用于手动发现候选；空列表仅用系统解析器 |
 
 - 支持 HTTPS OpenAI Chat Completions、OpenAI Responses、Anthropic Messages；不猜测其他协议或特殊认证。
 - 仅扫描/测速 IPv4。探测验证目标域名的 TLS 证书；测速使用原域名的 Host/SNI，连接候选 IP。
-- TCP 延迟（界面的 ping）只用于选择测试顺序，不决定最终推荐。
+- 已选 IP 只从相同供应商/域名的保存记录获取，不借用其他供应商或未应用的推荐；会尝试重新探测，但免费探测失败时仍保留它做真实 API 诊断，测速仍验证域名 TLS 证书，实际错误照常记录。其他探测失败的地址不会因此获得付费名额；无 DNS 且无已选地址时仍不盲扫。
+- TCP 延迟（界面的 ping）用于剩余名额及首轮对照之后的顺序；首轮完成后，每轮按最新统一评分从高到低安排下一轮。TPS 原值和每次实测结果始终保留；平分时依次考虑可信样本数、有效速度、慢尾、首字延迟、ping 和 IP。
+- 自适应超时只使用本次入选节点上一轮的数据：至少 3 个且占比达到 60% 的节点产出可信样本，才对上一轮 `timeout` / `ETIMEDOUT` 的节点缩短等待。预算为 `min(基础超时, max(基础超时的一半, 健康样本总时长 P90 × 2))`，使用 nearest-rank P90 并向上取整为毫秒；默认通常为 60 秒 → 30 秒。健康节点本身较慢时保留更长等待；整体变差、样本不足、节点恢复成功或出现其他错误时恢复基础超时，不会逐轮减成 15 秒、7.5 秒。第一轮及“测一下当前地址”始终使用基础超时，每个 IP 的计划次数不变。
+- 两项超时配置可在插件配置行设置；保存接口也接受这两个字段。新样本及进度中的 `timeoutMs` 保留实际预算，便于区分 30 秒和 60 秒超时；不改变正常模型请求的超时，也不重写旧测速记录。
 - 流式速度为输出 token 数 ÷ 首 token 到响应结束的时长。无有效 usage、截断、错误或过短样本不能获得可靠推荐。
-- 稳健得分使用 Q25、相对波动和可靠样本率：`Q25 / (1 + IQR / median) × 可靠样本率²`。至少需要 2 次可靠样本和计划次数的严格多数；原始 TPS 保留显示。
+- **评分 v2**：`100 × (0.8 × Hc + 0.2 × Q25c) / R × 成功率² × 测量可信度`。Hc 为封顶后的调和平均 TPS，Q25c 为封顶后的 nearest-rank Q25，R 为本次入选节点各自原始调和 TPS 的中位数。成功率仅统计真实已完成请求；测量可信度为 `可信样本数 / 成功请求数 × min(1, 可信样本数 / 2)`。失败与测量不充分分开，未测、跳过、取消不伪装成失败；IQR 仅作诊断，不再因纯粹提速而扣分。TTFT 仅参与平分决胜。
+- **群体速度上限**：至少 3 个节点且合计 6 个技术可信样本时，以各节点调和 TPS 的 nearest-rank Q90 × 1.5 作为经验上限（不低于 R）。超上限只封顶计分、标记 `high-capped`，不删除原值、不扣成功率。少量样本时不启用封顶/提前淘汰；无群体数据的单地址观测采用参考值 100，不能与另一轮的相对分数直接比较。
+- **最后一轮筛选**：参考量在轮间统一更新，最后一轮冻结同一参照和上限；先完成领先者复测，再对曾失败或没有可信样本的尾部，假设其剩余请求全部成功且达到上限，计算最高可能分。只有该上界仍低于已确认领先者得分的 95% 才跳过；成功但慢的节点、接近的竞争者仍继续测。全场两次都失败或参照不足时保留第三次机会。
+- **推荐与进度**：至少 2 次技术可信样本才有正式推荐资格，正常结束自动应用还须完整复测且无跳过/取消；只有 1 次成功的恢复结果仅显示暂列，不自动应用。进度分别显示已测、跳过、原始预算和轮次；“暂列领先 / 已确认 / 已淘汰 / 旧记录”清楚分开。每轮内分数实时更新、行顺序保持稳定，轮末统一重排。
+- **旧记录兼容**：不将 v1 分数重标成 v2。不同测试轮次用独立标识隔离；未在本轮入选的旧 v2 数据也只作历史展示，不混入当前榜单或冒充新推荐。单独重新发现候选只保留旧样本并统一标为历史，重启前后状态一致；已有手动/生效 IP 保持不变，重新测速后才获得新的可比分数。
 - 网络路径、代理、模型负载和限流都会影响结果。推荐只针对本次测试候选和工作负载，不保证全局最快。
 - 只有显式应用的地址才影响新建 DNS 连接；不修改操作系统 DNS，也不代表已存在的连接池会立即切换。同域名的不同供应商无法通过全局 DNS 钩子独立选择冲突 IP。
 - 设置接口仅接受本机回环客户端的同源 POST。远程 Web 管理目前不在支持范围内。

package/bench.js

@@ -376,12 +376,12 @@ export function measureStream({
   })
 }
 
-// Fixed, versioned scoring policy: short streams amplify timing/buffering noise.
-// High spikes can be artifacts, but slow tails are genuine stability evidence.
-export const SCORING_VERSION = 1
+// Versioned technical thresholds: throughput alone never makes a sample suspect.
+export const SCORING_VERSION = 2
 export const MIN_RELIABLE_OUTPUT_TOKENS = 32
 export const MIN_RELIABLE_DECODE_MS = 200
 export const MIN_RELIABLE_RUNS = 2
+// Compatibility exports; only the low-tail diagnostic still uses these values.
 export const OUTLIER_MULTIPLIER = 4
 export const MIN_OUTLIER_RUNS = 3
 
@@ -399,14 +399,120 @@ const range = (values) => {
   const sorted = sortedNumbers(values)
   return { min: sorted[0] ?? null, max: sorted[sorted.length - 1] ?? null }
 }
-const measurable = (run) => run !== undefined && run !== null && run.error === undefined &&
-  run.cancelled !== true && run.usageReported === true && Number.isFinite(run.tps) && run.tps > 0 &&
-  Number.isSafeInteger(run.outputTokens) && run.outputTokens > 0 &&
+const successful = (run) => run != null && run.error == null && run.cancelled !== true
+const measurable = (run) => successful(run) && run.usageReported === true &&
+  Number.isFinite(run.tps) && run.tps > 0 && Number.isSafeInteger(run.outputTokens) && run.outputTokens > 0 &&
   Number.isFinite(run.ttftMs) && run.ttftMs >= 0
+const reliable = (run) => measurable(run) && run.outputTokens >= MIN_RELIABLE_OUTPUT_TOKENS &&
+  Number.isFinite(run.decodeMs) && run.decodeMs >= MIN_RELIABLE_DECODE_MS
+const nonnegativeCount = (value) => Number.isSafeInteger(value) && value >= 0
+const quantile = (sorted, fraction) => sorted.length === 0 ? null : sorted[Math.ceil(sorted.length * fraction) - 1]
+
+// Scaling by the minimum avoids overflowing 1 / tinyTPS or summing huge TPS.
+// Optional cap copies let optimisticScore handle even safe-integer plans in O(runs).
+function harmonicMean(values, cap = null, copies = 0) {
+  const count = values.length + copies
+  if (count === 0) return null
+  let min = copies > 0 ? cap : Number.MAX_VALUE
+  let max = copies > 0 ? cap : 0
+  for (const value of values) {
+    min = Math.min(min, value)
+    max = Math.max(max, value)
+  }
+  let scaledSum = 0
+  for (const value of values) scaledSum += min / value
+  const average = scaledSum / count + (copies > 0 ? (min / cap) * (copies / count) : 0)
+  return Math.min(max, min / average)
+}
+
+const DEFAULT_SCORING_CONTEXT = Object.freeze({
+  scoringVersion: SCORING_VERSION, calibrated: false, peerCount: 0, sampleCount: 0,
+  speedReference: 100, speedCap: null,
+})
+
+/** Build a fresh, node-balanced context from this cohort's raw samples only. */
+export function buildScoringContext(groups) {
+  if (!Array.isArray(groups) || groups.some((group) => !Array.isArray(group))) {
+    throw new TypeError('Scoring groups must be arrays of raw runs')
+  }
+  const means = []
+  let sampleCount = 0
+  for (const group of new Set(groups)) {
+    const values = group.filter(reliable).map((run) => run.tps)
+    if (values.length === 0) continue
+    means.push(harmonicMean(values))
+    sampleCount += values.length
+    if (!Number.isSafeInteger(sampleCount)) throw new TypeError('Too many scoring samples')
+  }
+  means.sort((a, b) => a - b)
+  const peerCount = means.length
+  const speedReference = median(means) ?? 100
+  const calibrated = peerCount >= 3 && sampleCount >= 6
+  const upper = calibrated ? quantile(means, 0.9) : null
+  const speedCap = calibrated
+    ? Math.max(speedReference, upper > Number.MAX_VALUE / 1.5 ? Number.MAX_VALUE : upper * 1.5) : null
+  return Object.freeze({ scoringVersion: SCORING_VERSION, calibrated, peerCount, sampleCount, speedReference, speedCap })
+}
+
+// Fail closed rather than silently comparing scores in different units. Copy only
+// the public contract so callers cannot persist credentials through context extras.
+function scoringContextOrDefault(context) {
+  if (context === undefined) return { ...DEFAULT_SCORING_CONTEXT }
+  if (context === null || typeof context !== 'object' || Array.isArray(context)) throw new TypeError('Invalid scoring context')
+  const { scoringVersion, calibrated, peerCount, sampleCount, speedReference, speedCap } = context
+  const countsValid = nonnegativeCount(peerCount) && nonnegativeCount(sampleCount) && sampleCount >= peerCount &&
+    (peerCount > 0 || sampleCount === 0)
+  const enoughPeers = countsValid && peerCount >= 3 && sampleCount >= 6
+  if (scoringVersion !== SCORING_VERSION || typeof calibrated !== 'boolean' || !countsValid ||
+      calibrated !== enoughPeers || !Number.isFinite(speedReference) || speedReference <= 0 ||
+      (peerCount === 0 && speedReference !== 100) ||
+      (calibrated ? !Number.isFinite(speedCap) || speedCap <= 0 || speedCap < speedReference : speedCap !== null)) {
+    throw new TypeError('Invalid scoring context')
+  }
+  return { scoringVersion, calibrated, peerCount, sampleCount, speedReference, speedCap }
+}
+
+function normalizedCounts(runs, plannedRuns, skippedRuns = 0) {
+  const skipped = nonnegativeCount(skippedRuns) ? Math.min(skippedRuns, Number.MAX_SAFE_INTEGER - runs.length) : 0
+  const actual = runs.length + skipped
+  return { planned: nonnegativeCount(plannedRuns) ? Math.max(plannedRuns, actual) : actual, skipped }
+}
+
+function scoreMetrics(values, successfulRuns, completedRuns, context, copies = 0) {
+  const scored = sortedNumbers(values.map((value) => context.speedCap === null ? value : Math.min(value, context.speedCap)))
+  const count = scored.length + copies
+  const successRate = completedRuns > 0 ? successfulRuns / completedRuns : 0
+  const measurementConfidence = successfulRuns > 0
+    ? (count / successfulRuns) * Math.min(1, count / MIN_RELIABLE_RUNS) : 0
+  if (count === 0) return { successRate, measurementConfidence, effectiveTps: null, provisionalScore: null }
+  const effectiveTps = harmonicMean(scored, context.speedCap, copies)
+  const qIndex = Math.ceil(count * 0.25) - 1
+  const lower = qIndex < scored.length ? scored[qIndex] : context.speedCap
+  // Score with an unrounded dimensionless H/Q25 ratio. The displayed H may be
+  // subnormal: rounding it first can make a faster sample lower the score and
+  // even invalidate the optimistic pruning bound.
+  const scale = lower
+  const minimum = Math.min(scored[0] ?? context.speedCap, copies > 0 ? context.speedCap : Number.MAX_VALUE)
+  const meanReciprocal = scored.reduce((sum, value) => sum + minimum / value, 0) / count +
+    (copies > 0 ? (minimum / context.speedCap) * (copies / count) : 0)
+  const harmonicRatio = (minimum / scale) / meanReciprocal
+  const blend = 0.8 * harmonicRatio + 0.2
+  const penalty = 100 * successRate ** 2 * measurementConfidence
+  const ratio = scale / context.speedReference
+  let provisionalScore = ratio * (blend * penalty)
+  const minNormal = 2 ** -1022
+  if (!Number.isFinite(provisionalScore) || ratio < minNormal || provisionalScore < minNormal) {
+    // Take only the final rounding when an intermediate ratio is subnormal or
+    // overflows. The normal fast path retains exact constant-speed scores.
+    const logScore = Math.log(scale) - Math.log(context.speedReference) + Math.log(blend) + Math.log(penalty)
+    provisionalScore = logScore >= Math.log(Number.MAX_VALUE) ? Number.MAX_VALUE : Math.exp(logScore)
+  }
+  return { successRate, measurementConfidence, effectiveTps, provisionalScore }
+}
 
 export function sampleError(run) {
   if (run?.cancelled === true) return 'test stopped'
-  if (run?.error === undefined) return run == null ? 'missing run' : null
+  if (run?.error == null) return run == null ? 'missing run' : null
   // Provider bodies and exception messages can echo prompts, URLs or secrets.
   // Persist a bounded error category, never their arbitrary trailing text.
   if (typeof run.error !== 'string') return 'request failed'
@@ -428,89 +534,103 @@ export function sampleError(run) {
 }
 
 /**
- * Preserve transport/median display fields independently of ranking. Samples are
- * a fixed-size allowlist per attempted run: finite raw numbers are unchanged,
- * non-finite/missing values become null, and text/credentials are never copied.
- * plannedRuns includes unstarted work, so stopping early cannot inflate a score.
- * conservativeTps is nearest-rank Q25(v); relativeSpread is (Q75-Q25)/median(v).
- * stabilityScore = Q25/(1+relativeSpread) * (reliableRuns/plannedRuns)^2.
- * rankEligible is authoritative; rejected scores are null, not transport errors.
+ * Preserve raw transport/median display fields independently of ranking. Only
+ * technical rules select scoring samples; caps never lower reliability. The
+ * score is 100 * (0.8 * capped H + 0.2 * capped nearest-rank Q25) / reference
+ * times successRate squared and measurementConfidence. Spread is diagnostic.
+ * Pending, cancelled and deliberately skipped work are distinct from failures.
  */
-export function summarize(runs, { plannedRuns = runs.length } = {}) {
-  plannedRuns = Number.isSafeInteger(plannedRuns) && plannedRuns >= 0
-    ? Math.max(plannedRuns, runs.length) : runs.length
-  const ok = runs.filter((run) => run !== undefined && run !== null && run.error === undefined && run.cancelled !== true)
+export function summarize(runs, {
+  plannedRuns = runs.length, scoringContext, skippedRuns = 0, skippedReason,
+} = {}) {
+  const context = scoringContextOrDefault(scoringContext)
+  const counts = normalizedCounts(runs, plannedRuns, skippedRuns)
+  plannedRuns = counts.planned
+  skippedRuns = counts.skipped
+  const ok = runs.filter(successful)
   const valid = ok.filter(measurable)
   const samples = Array.from(runs, (run) => {
     const flags = []
     if (run?.cancelled === true) flags.push('cancelled')
-    if (run?.error !== undefined && run?.cancelled !== true) flags.push('transport-error')
-    const valid = measurable(run)
-    if (!valid) flags.push('unmeasurable')
+    if (run?.error != null && run?.cancelled !== true) flags.push('transport-error')
+    if (!measurable(run)) flags.push('unmeasurable')
     if (Number.isSafeInteger(run?.outputTokens) && run.outputTokens > 0 && run.outputTokens < MIN_RELIABLE_OUTPUT_TOKENS) {
       flags.push('insufficient-tokens')
     }
     if (run?.decodeMs == null) flags.push('missing-decode-window')
     else if (!Number.isFinite(run.decodeMs) || run.decodeMs < 0) flags.push('invalid-decode-window')
     else if (run.decodeMs < MIN_RELIABLE_DECODE_MS) flags.push('insufficient-decode-window')
+    const trusted = reliable(run)
+    const capped = trusted && context.speedCap !== null && run.tps > context.speedCap
+    if (capped) flags.push('high-capped')
     return {
       status: finite(run?.status), tps: finite(run?.tps), ttftMs: finite(run?.ttftMs),
       totalMs: finite(run?.totalMs), decodeMs: finite(run?.decodeMs), outputTokens: finite(run?.outputTokens),
+      ...(Number.isSafeInteger(run?.timeoutMs) && run.timeoutMs > 0 ? { timeoutMs: run.timeoutMs } : {}),
       usageReported: run?.usageReported === true, error: sampleError(run), cancelled: run?.cancelled === true,
-      flags, reliable: valid && run.outputTokens >= MIN_RELIABLE_OUTPUT_TOKENS &&
-        Number.isFinite(run.decodeMs) && run.decodeMs >= MIN_RELIABLE_DECODE_MS,
+      flags, reliable: trusted, scoredTps: trusted ? (capped ? context.speedCap : run.tps) : null,
     }
   })
   const technical = samples.filter((sample) => sample.reliable)
   if (technical.length >= MIN_OUTLIER_RUNS) {
     const center = median(technical.map((sample) => sample.tps))
     for (const sample of technical) {
-      if (sample.tps / center > OUTLIER_MULTIPLIER) {
-        sample.flags.push('high-outlier')
-        sample.reliable = false
-      } else if (sample.tps < center / OUTLIER_MULTIPLIER) {
-        // Keep the low tail in v: discarding it would reward unstable routes.
-        sample.flags.push('low-tail')
-      }
+      if (sample.tps < center / OUTLIER_MULTIPLIER) sample.flags.push('low-tail')
     }
   }
-  const values = sortedNumbers(samples.filter((sample) => sample.reliable).map((sample) => sample.tps))
+  const values = sortedNumbers(technical.map((sample) => sample.tps))
   const reliableRuns = values.length
-  const rankEligible = reliableRuns >= MIN_RELIABLE_RUNS && reliableRuns > plannedRuns / 2
-  const q25 = values.length > 0 ? values[Math.ceil(values.length * 0.25) - 1] : null
-  const q75 = values.length > 0 ? values[Math.ceil(values.length * 0.75) - 1] : null
+  const rankEligible = reliableRuns >= MIN_RELIABLE_RUNS
+  const q25 = quantile(values, 0.25)
+  const q75 = quantile(values, 0.75)
   const center = median(values)
   const relativeSpread = center === null ? null : Math.min(Number.MAX_VALUE, (q75 - q25) / center)
-  const stabilityScore = rankEligible
-    ? q25 / (1 + relativeSpread) * (reliableRuns / plannedRuns) ** 2 : null
-  const scoreReason = rankEligible
-    ? `ranked using ${reliableRuns}/${plannedRuns} reliable runs; lower-quartile TPS, spread and completion penalties`
-    : reliableRuns < MIN_RELIABLE_RUNS
-      ? `only ${reliableRuns}/${plannedRuns} reliable runs; at least ${MIN_RELIABLE_RUNS} are required (>=${MIN_RELIABLE_OUTPUT_TOKENS} output tokens and >=${MIN_RELIABLE_DECODE_MS}ms decode window)`
-      : `only ${reliableRuns}/${plannedRuns} reliable runs; a strict majority of planned runs is required`
   const cancelled = samples.filter((sample) => sample.cancelled).length
-  const firstFailure = runs.find((run) => run?.error !== undefined)
+  const completedRuns = runs.length - cancelled
+  const successfulRuns = ok.length
+  const metrics = scoreMetrics(values, successfulRuns, completedRuns, context)
+  const pendingRuns = Math.max(0, plannedRuns - runs.length - skippedRuns)
+  const confirmed = rankEligible && pendingRuns === 0 && skippedRuns === 0 && cancelled === 0 && runs.length >= plannedRuns
+  const scoreReason = reliableRuns === 0 ? 'No technically reliable samples'
+    : !rankEligible ? 'Provisional; at least 2 reliable runs required'
+      : confirmed ? 'Confirmed; harmonic speed, success and confidence'
+        : 'Provisional; pending, cancelled or skipped runs remain'
+  const firstFailure = samples.find((sample) => sample.error !== null)
   const eligible = valid.length > runs.length / 2
   const tps = range(valid.map((run) => run.tps))
   const ttft = range(valid.map((run) => run.ttftMs))
   return {
-    runs: runs.length,
-    failed: runs.length - ok.length,
-    measurable: valid.length,
-    unmeasurable: ok.length - valid.length,
-    eligible,
+    runs: runs.length, failed: completedRuns - successfulRuns,
+    measurable: valid.length, unmeasurable: ok.length - valid.length, eligible,
     ...(!eligible ? { error: valid.length === 0
-      ? (firstFailure === undefined ? 'no run produced measurable TPS' : sampleError(firstFailure))
+      ? (firstFailure === undefined ? 'no run produced measurable TPS' : firstFailure.error)
       : `only ${valid.length}/${runs.length} runs produced measurable TPS; a strict majority is required` } : {}),
-    ttftMs: median(valid.map((run) => run.ttftMs)),
-    tps: median(valid.map((run) => run.tps)),
-    tpsMin: tps.min, tpsMax: tps.max,
-    ttftMinMs: ttft.min, ttftMaxMs: ttft.max,
-    totalMs: median(valid.map((run) => run.totalMs)),
-    outputTokens: median(valid.map((run) => run.outputTokens)),
+    ttftMs: median(valid.map((run) => run.ttftMs)), tps: median(valid.map((run) => run.tps)),
+    tpsMin: tps.min, tpsMax: tps.max, ttftMinMs: ttft.min, ttftMaxMs: ttft.max,
+    totalMs: median(valid.map((run) => run.totalMs)), outputTokens: median(valid.map((run) => run.outputTokens)),
     usageReported: ok.length > 0 && ok.every((run) => run.usageReported === true),
-    samples, plannedRuns, completedRuns: runs.length - cancelled, cancelled,
-    reliableRuns, suspectRuns: samples.length - reliableRuns, rankEligible,
-    conservativeTps: q25, relativeSpread, stabilityScore, scoringVersion: SCORING_VERSION, scoreReason,
+    samples, plannedRuns, completedRuns, successfulRuns, cancelled, skippedRuns, pendingRuns,
+    ...(skippedRuns > 0 ? { skippedReason: skippedReason === 'optimistic-bound' ? 'optimistic-bound' : 'not scheduled' } : {}),
+    reliableRuns, suspectRuns: samples.length - reliableRuns, rankEligible, confirmed, eliminated: skippedRuns > 0,
+    harmonicTps: harmonicMean(values), conservativeTps: q25, relativeSpread,
+    ...metrics, stabilityScore: metrics.provisionalScore,
+    scoringVersion: SCORING_VERSION, scoreContext: context, scoreReason,
   }
 }
+
+/**
+ * Best possible final score under a frozen calibrated cap. Real failures and
+ * cancellations stay untouched. Unmeasured attempts are successful, technically
+ * reliable cap-TPS samples with zero TTFT. Use summarize's exact score primitive
+ * without allocating a potentially enormous synthetic-sample array.
+ */
+export function optimisticScore(runs, { plannedRuns = runs.length, scoringContext } = {}) {
+  const context = scoringContextOrDefault(scoringContext)
+  if (!context.calibrated || !Number.isFinite(context.speedCap) || context.speedCap <= 0) return null
+  const { planned } = normalizedCounts(runs, plannedRuns)
+  const remaining = planned - runs.length
+  const values = runs.filter(reliable).map((run) => run.tps)
+  const successfulRuns = runs.filter(successful).length + remaining
+  const completedRuns = runs.filter((run) => run?.cancelled !== true).length + remaining
+  return scoreMetrics(values, successfulRuns, completedRuns, context, remaining).provisionalScore
+}