@genee/omp-opsx-addon 0.8.0 → 0.10.0

package/lib/model-selector.ts

@@ -2,15 +2,25 @@
  * Model selector — picks the best `Model<Api>` for a given role.
  *
  * Sorts by (in order):
- *   1. Effective gap = tierGap + surgePenalty (closest to expected wins).
- *      Surge penalty is applied during peak pricing windows and when
- *      monthly-plan providers have available quota (to avoid PAYG spend).
- *   2. Rank (higher tier wins).
- *   3. Plan priority: monthly-plan providers (0) before PAYG (1).
+ *   1. Coverage class — hard partition, primary key: monthly-plan covered (0)
+ *      before standard (1) before pay-as-you-go (2). PAYG candidates only
+ *      reach the top when no plan/standard candidate is available;
+ *      `paygLastResort: false` collapses this key. Classification is generic
+ *      (zero hardcoded provider names — see `classifyCoverage`).
+ *   2. Effective gap = tierGap + surgePenalty (closest to expected wins).
+ *      Surge penalty applies only during GLM-5 peak pricing windows — the
+ *      PAYG-vs-plan trade-off is the partition's job, not a penalty.
+ *   3. Rank (higher tier wins).
  *   4. Remaining fraction (healthier first).
- *   5. Cost (cheaper first).
- *   6. Reputation (higher first).
- *   7. Name (stable tie-break).
+ *   5. Cost band — quantized costInput: max(0, floor(log2)+1) power-of-two
+ *      bands; band 0 = free/missing price plus clamped <$1 positive prices.
+ *      Monotone in costInput, so cross-band order ≡ raw cost order (zero drift).
+ *   6. Speed inside the band (tokPerS desc; measured before unmeasured;
+ *      sentinels/unmeasured = -Infinity). `aggressive` mode moves speed ahead
+ *      of the band (crosses price within the same class + tier axis).
+ *   7. Cost raw value (cheaper first) — in-band order and speed-equal fallback.
+ *   8. Reputation (higher first).
+ *   9. Name (stable tie-break).
  */
 
 import type { Model, Api } from '@oh-my-pi/pi-catalog/types';
@@ -21,8 +31,10 @@ import {
     scoreModelWithProvider,
     tierNameToRank,
 } from './model-tiers.js';
-import type { ProviderHealth } from './usage-resolver.js';
+import { type ProviderHealth, canonicalizeProvider, quotaPolicyFor } from './usage-resolver.js';
+import { FREE_BAND, SENTINEL_BAND, type SpeedAwareRuntime, type SpeedIndex, speedIndexKey } from './model-speed.js';
 import { getPeakStatus, isGLM5Model, type PeakStatus } from './peak-detector.js';
+import type { QualityPreference } from './complexity-router.js';
 
 export interface ScoredCandidate {
     model: Model<Api>;
@@ -34,12 +46,14 @@ export interface ScoredCandidate {
     remainingFraction?: number;
     tierGap: number;
     costInput: number;
-    /** 0 = provider has a monthly plan, 1 = PAYG / unknown. Lower preferred. */
-    planPriority: number;
+    /** Coverage partition: 0 = monthly-plan covered, 1 = standard, 2 = pay-as-you-go. Primary sort key; lower preferred. */
+    coverageClass: 0 | 1 | 2;
     /** Coding reputation 0-100 from model family (SWE-bench ranking). Higher preferred. */
     reputation: number;
     /** Surge pricing penalty (0 = normal, 1+ = penalized). Added to tierGap for sorting. */
     surgePenalty: number;
+    /** provider_auto sentinel: heuristic scoring bypassed for the declared tier; dedup-exempt; costInput = +∞ (cost-neutral). */
+    isProviderAuto: boolean;
 }
 export interface SelectorResult {
     role: string;
@@ -62,6 +76,26 @@ export interface SelectorInput {
     planProviders?: Set<string>;
     /** Pre-computed peak status (for testing). If omitted, computed from current time. */
     peakStatus?: PeakStatus;
+    /** Keep pay-as-you-go candidates as last resort (coverage partition active). Default true. */
+    paygLastResort?: boolean;
+    /** provider → 服务端路由哨兵模型 id（键已 canonicalizeProvider 规范化，值与 catalog id 大小写不敏感匹配）。 */
+    providerAuto?: Record<string, string>;
+    /** provider → 哨兵声明档位（解析层已过 TIER_NAMES 校验）；未声明的哨兵按 mid。 */
+    providerAutoTiers?: Record<string, TierName>;
+    /** 速度感知 runtime（mode + 已载入索引）；缺省/禁用时排序与 W1 定型序逐字节一致。 */
+    speedAware?: SpeedAwareRuntime;
+    /**
+     * 质量带旋钮（W4，design D6）：balanced/缺省 → 既有分支逐字节（零漂移的
+     * 结构保证是「不进入」新分支，而非行为等价的新路径）；cost → tier 轴槽位
+     * 内部容差带量化；quality → 质量分前缀分层。槽位不移动、既有键相对次序
+     * 不改动（model-selection-ordering requirement 为跨引用权威约束）。
+     */
+    qualityPreference?: QualityPreference;
+    /**
+     * 数据层标注段（W4 路由，调用方组装，如 `band=complex, stall+1`）：纯追加
+     * 到 pickedReason 与 decision 的 picked 行；缺省零追加（W3 speed 段同款）。
+     */
+    note?: string;
 }
 
 function globToRegex(pattern: string): RegExp {
@@ -114,10 +148,54 @@ export const DEFAULT_PLAN_PROVIDERS = new Set([
     'kimi',
     'openai-codex',
     'cursor',
+    'ark-coding-plan',
 ]);
 
-export function mergePlanProviders(extra?: readonly string[]): Set<string> {
-    return new Set([...DEFAULT_PLAN_PROVIDERS, ...(extra ?? [])]);
+/** Coverage partition classes: 0 = monthly-plan covered, 1 = standard, 2 = pay-as-you-go. */
+export type CoverageClass = 0 | 1 | 2;
+
+/**
+ * Coverage class of a provider: plan-set member → 0 (plan);
+ * `quotaPolicyFor() === 'balance'` (pay-as-you-go) → 2; everything else → 1.
+ * Generic by design — no provider names here. Both sides are canonicalized so
+ * `ArkCodingPlan` / `arkcodingplan` spellings hit `ark-coding-plan`. An
+ * undefined plan set is treated as empty.
+ */
+export function classifyCoverage(
+    provider: string,
+    planProviders?: ReadonlySet<string>,
+): CoverageClass {
+    const canonical = canonicalizeProvider(provider);
+    if (planProviders) {
+        for (const entry of planProviders) {
+            if (canonicalizeProvider(entry) === canonical) return 0;
+        }
+    }
+    return quotaPolicyFor(canonical) === 'balance' ? 2 : 1;
+}
+
+/** Human-readable coverage class (`class=plan|standard|payg`) for decision logs and /pick-model choices rendering. */
+export const COVERAGE_LABEL: Record<CoverageClass, 'plan' | 'standard' | 'payg'> = {
+    0: 'plan',
+    1: 'standard',
+    2: 'payg',
+};
+
+export function mergePlanProviders(
+    extra?: readonly string[],
+    remove?: readonly string[],
+): Set<string> {
+    const out = new Set<string>();
+    for (const entry of [...DEFAULT_PLAN_PROVIDERS, ...(extra ?? [])]) {
+        out.add(canonicalizeProvider(entry));
+    }
+    if (remove?.length) {
+        const removed = new Set(remove.map(canonicalizeProvider));
+        for (const entry of out) {
+            if (removed.has(entry)) out.delete(entry);
+        }
+    }
+    return out;
 }
 
 function isAllowlisted(selector: string, allowlist: string[] | undefined): boolean {
@@ -166,7 +244,16 @@ function isNewer(a: [number, number], b: [number, number]): boolean {
  *  Prefers latest generation first, then reputation as tiebreaker. */
 function dedupByProviderTier(candidates: ScoredCandidate[]): ScoredCandidate[] {
     const best = new Map<string, ScoredCandidate>();
+    const autos: ScoredCandidate[] = [];
     for (const c of candidates) {
+        // Sentinels skip the (provider, tier) contest entirely: version-less ids
+        // (`default` / `ark-code-latest`) extract [0,0] and would always be
+        // evicted by any concrete model. At most one sentinel per provider
+        // (provider_auto maps provider → single id), so no flooding risk.
+        if (c.isProviderAuto) {
+            autos.push(c);
+            continue;
+        }
         const key = `${c.model.provider}:${c.tier}`;
         const existing = best.get(key);
         if (!existing) {
@@ -185,20 +272,84 @@ function dedupByProviderTier(candidates: ScoredCandidate[]): ScoredCandidate[] {
             }
         }
     }
-    return [...best.values()];
+    return [...best.values(), ...autos];
+}
+
+/**
+ * Cost band quantization (frozen slot — change: speed-aware-selection):
+ * `max(0, floor(log2(c)) + 1)` for c > 0. The clamp keeps every band ≥ 0 and
+ * monotone in costInput, so any cross-band pair orders exactly like the raw
+ * costInput comparison — the unquantized W1 order never regresses. c ≤ 0
+ * (free / missing price) and clamp-collected 0 < c < 1 positive prices share
+ * band 0 (raw costInput still orders inside: free, then $0.4, then $0.99);
+ * +∞ (provider-auto sentinel) lands in the last band, behind everything.
+ */
+export function costBand(costInput: number): number {
+    if (costInput <= 0) return FREE_BAND;
+    if (!Number.isFinite(costInput)) return SENTINEL_BAND;
+    return Math.max(0, Math.floor(Math.log2(costInput)) + 1);
+}
+
+/**
+ * Quality-knob cost-mode tolerance (W4, design D6; module constant — W3 band
+ * 先例, not configurable): candidates within T of the per-class minimal
+ * effective tier-axis value share band 0 and compare de-axised (Azure「带内
+ * 等质，选最便宜」的容差带类比，披露于 README); beyond T is band 1, sorted by
+ * the full frozen chain. Band 0 always precedes band 1 (cross-band quality
+ * order preserved).
+ */
+export const QUALITY_COST_TOLERANCE = 1;
+
+/**
+ * Per-candidate speed sort key: measured tokPerS, else -Infinity (identity
+ * lower bound — measured beats unmeasured inside a band; unmeasured
+ * candidates keep their relative W1 order via band/costInput). The sentinel
+ * guard lives on the candidate side, not the data side: a black-box
+ * provider-auto route must not score even if model_perf happens to hold a
+ * row for its id.
+ */
+function speedKeyOf(c: ScoredCandidate, index: SpeedIndex): number {
+    if (c.isProviderAuto) return Number.NEGATIVE_INFINITY;
+    return index.get(speedIndexKey(`${c.model.provider}/${c.model.id}`))?.tokPerS ?? Number.NEGATIVE_INFINITY;
 }
 
 export function selectModel(input: SelectorInput): SelectorResult {
-    const { role, models, tierOverrides, health, allowlist, planProviders, peakStatus } = input;
+    const { role, models, tierOverrides, health, allowlist, planProviders, peakStatus, paygLastResort, providerAuto, providerAutoTiers, speedAware, qualityPreference, note } = input;
     const roleTiers = input.roleTiers ?? DEFAULT_ROLE_TIER;
     const expectedTier: TierName = roleTiers[role] ?? DEFAULT_ROLE_TIER[role] ?? 'mid';
     const expectedRank = tierNameToRank(expectedTier);
 
     const allCandidates: ScoredCandidate[] = models.map((model) => {
         const selector = `${model.provider}/${model.id}`;
-        const score = scoreModelWithProvider(model.provider, model.id, model.name, tierOverrides);
         const h = health?.get(model.provider);
         const quota = candidateQuota(model, h);
+        const autoKey = providerAuto ? canonicalizeProvider(model.provider) : undefined;
+        const autoId = providerAuto && autoKey ? providerAuto[autoKey] : undefined;
+        if (autoId !== undefined && model.id.toLowerCase() === autoId.toLowerCase()) {
+            // provider_auto sentinel: skip the local heuristic entirely — the
+            // declared tier carries rank/tierGap (its only legitimate edge),
+            // reputation stays 0 ("no local standing"), and +∞ costInput
+            // yields to every real-cost candidate within the same coverage
+            // class + tier: the catalog's all-zero cost must not fake a win.
+            const tier = (autoKey ? providerAutoTiers?.[autoKey] : undefined) ?? 'mid';
+            const rank = tierNameToRank(tier);
+            return {
+                model,
+                selector,
+                rank,
+                tier,
+                reason: `provider-auto (tier=${tier})`,
+                exhausted: quota.exhausted,
+                remainingFraction: quota.remainingFraction,
+                tierGap: Math.abs(rank - expectedRank),
+                costInput: Number.POSITIVE_INFINITY,
+                coverageClass: classifyCoverage(model.provider, planProviders),
+                reputation: 0,
+                surgePenalty: 0,
+                isProviderAuto: true,
+            };
+        }
+        const score = scoreModelWithProvider(model.provider, model.id, model.name, tierOverrides);
         return {
             model,
             selector,
@@ -209,9 +360,10 @@ export function selectModel(input: SelectorInput): SelectorResult {
             remainingFraction: quota.remainingFraction,
             tierGap: Math.abs(score.rank - expectedRank),
             costInput: model.cost?.input ?? 0,
-            planPriority: planProviders?.has(model.provider) ? 0 : 1,
+            coverageClass: classifyCoverage(model.provider, planProviders),
             reputation: score.reputation,
             surgePenalty: 0,
+            isProviderAuto: false,
         };
     });
 
@@ -221,46 +373,148 @@ export function selectModel(input: SelectorInput): SelectorResult {
     // from flooding the candidate pool against the latest (M3).
     const deduped = dedupByProviderTier(filtered);
     // ── surge pricing penalty ──────────────────────────────────────
-    // Peak-time pricing adjustments + monthly-plan preference.
+    // GLM-5 peak-time pricing adjustment only: the PAYG-vs-plan trade-off is
+    // handled by the coverage-class partition, not by surge penalties.
     const peak = peakStatus ?? getPeakStatus();
-    const hasMonthlyAvailable = deduped.some(
-        (c) => planProviders?.has(c.model.provider) && !c.exhausted,
-    );
     for (const c of deduped) {
-        const isDS = c.model.provider === 'deepseek';
         const isGLM5 = c.model.provider === 'zhipu-coding-plan' && isGLM5Model(c.model.id);
-        let penalty = 0;
-        if (isDS && peak.deepseekPeak) penalty = Math.max(penalty, 2);
-        if (isGLM5 && peak.glm5Peak) penalty = Math.max(penalty, 2);
-        // When any monthly-plan provider has available quota, heavily
-        // penalize DeepSeek (PAYG) to preserve plan budget.
-        if (isDS && hasMonthlyAvailable) penalty = Math.max(penalty, 3);
-        c.surgePenalty = penalty;
+        c.surgePenalty = isGLM5 && peak.glm5Peak ? 2 : 0;
     }
 
 
 
+    // ── W4 quality_preference knob (design D6) ─────────────────────
+    // balanced/absent → knobActive stays false and every structure below is
+    // inert: the frozen chain in the sort lambda runs byte-identically (the
+    // zero-drift guarantee is "not entering" the knob path).
+    const knobActive = qualityPreference === 'cost' || qualityPreference === 'quality';
+    // Cost mode anchor: per coverage class (fixed 0|1|2 slots), the minimal
+    // effective tier-axis value in the deduped pool (W3 costBand 量化的同构
+    // 先例 — slot-internal quantization, one pre-scan).
+    const tierAnchors: (number | undefined)[] = [undefined, undefined, undefined];
+    if (qualityPreference === 'cost') {
+        for (const c of deduped) {
+            const eff = c.tierGap + c.surgePenalty;
+            const anchor = tierAnchors[c.coverageClass];
+            if (anchor === undefined || eff < anchor) tierAnchors[c.coverageClass] = eff;
+        }
+    }
+    // Tier-axis band: ≤ T above the class anchor → band 0 (de-axised), else band 1.
+    const tierBandOf = (c: ScoredCandidate): number => {
+        const anchor = tierAnchors[c.coverageClass] ?? 0;
+        return c.tierGap + c.surgePenalty - anchor <= QUALITY_COST_TOLERANCE ? 0 : 1;
+    };
+    // Frozen-chain tail shared by both knob branches: the keys AFTER the tier
+    // axis in the W1-W3 order (remainingFraction → [cost band → speed] →
+    // costInput raw asc → reputation → selector). includeReputation=false for
+    // the quality prefix (reputation already consumed by the prefix keys).
+    // Allocated only when the knob is active — the legacy path allocates nothing.
+    const knobTail = knobActive
+        ? (x: ScoredCandidate, y: ScoredCandidate, includeReputation: boolean): number => {
+            const xr = x.remainingFraction ?? 1;
+            const yr = y.remainingFraction ?? 1;
+            if (xr !== yr) return yr - xr;
+            if (speedAware) {
+                const bandX = costBand(x.costInput);
+                const bandY = costBand(y.costInput);
+                const speedX = speedKeyOf(x, speedAware.index);
+                const speedY = speedKeyOf(y, speedAware.index);
+                if (speedAware.mode === 'aggressive') {
+                    if (speedX !== speedY) return speedY - speedX;
+                    if (bandX !== bandY) return bandX - bandY;
+                } else {
+                    if (bandX !== bandY) return bandX - bandY;
+                    if (speedX !== speedY) return speedY - speedX;
+                }
+            }
+            if (x.costInput !== y.costInput) return x.costInput - y.costInput;
+            if (includeReputation && x.reputation !== y.reputation) return y.reputation - x.reputation;
+            return x.selector.localeCompare(y.selector);
+        }
+        : null;
+
     let picked: ScoredCandidate | null = null;
     if (deduped.length > 0) {
         const sorted = [...deduped].sort((a, b) => {
+            // Coverage class is the primary key: a hard partition — PAYG only
+            // wins when no plan/standard candidate is available. When
+            // paygLastResort is false the partition is collapsed (every
+            // candidate compares equal on this key).
+            if ((paygLastResort ?? true) && a.coverageClass !== b.coverageClass) {
+                return a.coverageClass - b.coverageClass;
+            }
+            if (knobTail && qualityPreference === 'quality') {
+                // 质量分前缀分层（design D6）：(effGap, rank, reputation desc)
+                // 提入前缀（coverageClass 已在上方消费）——成本/速度无法越过一个
+                // 轴位或声誉差距（Azure Quality「无视成本」）。rank/reputation 已
+                // 由前缀消费，分区内不再重复；分区内剩余键保持原链子序列。
+                const effA = a.tierGap + a.surgePenalty;
+                const effB = b.tierGap + b.surgePenalty;
+                if (effA !== effB) return effA - effB;
+                if (a.rank !== b.rank) return b.rank - a.rank;
+                if (a.reputation !== b.reputation) return b.reputation - a.reputation;
+                return knobTail(a, b, false);
+            }
+            if (knobTail && qualityPreference === 'cost') {
+                const bandDelta = tierBandOf(a) - tierBandOf(b);
+                if (bandDelta !== 0) return bandDelta; // 带 0 恒先于带 1（跨带质量序保持）
+                if (tierBandOf(a) === 0) {
+                    // 带 0 内去轴化（Azure「带内等质，选最便宜」字面落地，README
+                    // 披露）：tierGap/surge/rank 不参与——带内质量等价，成本/速度
+                    // 决胜。哨兵按声明档正常参与量化（effGap 用声明档，无特判）。
+                    return knobTail(a, b, true);
+                }
+                // 带 1 内：全冻结链自洽（落到下方既有链）。
+            }
             const effA = a.tierGap + a.surgePenalty;
             const effB = b.tierGap + b.surgePenalty;
             if (effA !== effB) return effA - effB;
             if (a.rank !== b.rank) return b.rank - a.rank;
-            // Same effective tier: prefer monthly plan, then cheapest model
-            if (a.planPriority !== b.planPriority) return a.planPriority - b.planPriority;
             const ar = a.remainingFraction ?? 1;
             const br = b.remainingFraction ?? 1;
             if (ar !== br) return br - ar;
-            if (a.costInput !== b.costInput) return a.costInput - b.costInput;
+            if (speedAware) {
+                // Speed-aware selection fills the frozen cost-band + speed
+                // slots (slots never move). Keys are plain per-candidate
+                // scalars — this lexicographic chain is a strict weak
+                // ordering; "both measured" pairwise gating is NOT (three
+                // same-band candidates cycle under it, design D4).
+                const bandA = costBand(a.costInput);
+                const bandB = costBand(b.costInput);
+                const speedA = speedKeyOf(a, speedAware.index);
+                const speedB = speedKeyOf(b, speedAware.index);
+                if (speedAware.mode === 'aggressive') {
+                    // Speed crosses price bands within the same class + tier axis.
+                    if (speedA !== speedB) return speedB - speedA;
+                    if (bandA !== bandB) return bandA - bandB;
+                } else {
+                    if (bandA !== bandB) return bandA - bandB;
+                    if (speedA !== speedB) return speedB - speedA;
+                }
+                // Same band + same speed (incl. both unmeasured): raw cost wins.
+                if (a.costInput !== b.costInput) return a.costInput - b.costInput;
+            } else if (a.costInput !== b.costInput) {
+                // No speed runtime: byte-identical to the frozen W1 order.
+                return a.costInput - b.costInput;
+            }
             if (a.reputation !== b.reputation) return b.reputation - a.reputation;
             return a.selector.localeCompare(b.selector);
         });
         picked = sorted[0] ?? null;
     }
-    const decision = buildDecisionLog(role, expectedTier, allCandidates, deduped, picked);
+    // Data-layer observability only (rendering never carries pickedReason):
+    // annotate when the picked candidate is measured — never for sentinels,
+    // never when speed awareness is off.
+    const pickedSpeed = picked && speedAware && !picked.isProviderAuto
+        ? speedAware.index.get(speedIndexKey(`${picked.model.provider}/${picked.model.id}`))
+        : undefined;
+    const speedNote = pickedSpeed ? ` speed=${pickedSpeed.tokPerS.toFixed(1)}tok/s` : '';
+    // W4 data-layer annotation (caller-composed, e.g. `band=complex, stall+1`):
+    // pure append — absent note keeps the W3 format byte-identical.
+    const routeNote = note?.trim() ? ` ${note.trim()}` : '';
+    const decision = buildDecisionLog(role, expectedTier, allCandidates, deduped, picked, speedNote, routeNote);
     const pickedReason = picked
-        ? `${picked.selector} (tier=${picked.tier}, gap=${picked.tierGap}${picked.surgePenalty > 0 ? `+${picked.surgePenalty}` : ''})`
+        ? `${picked.selector} (tier=${picked.tier}, gap=${picked.tierGap}${picked.surgePenalty > 0 ? `+${picked.surgePenalty}` : ''}, class=${COVERAGE_LABEL[picked.coverageClass]}${picked.isProviderAuto ? ', auto' : ''}${pickedSpeed ? `, speed=${pickedSpeed.tokPerS.toFixed(1)}tok/s` : ''}${routeNote ? `,${routeNote}` : ''})`
         : null;
 
     return { role, expectedTier, picked: picked?.model ?? null, candidates: deduped, allCandidates, decision, pickedReason };
@@ -269,6 +523,7 @@ export function selectModel(input: SelectorInput): SelectorResult {
 function buildDecisionLog(
     role: string, expectedTier: TierName,
     all: ScoredCandidate[], filtered: ScoredCandidate[], picked: ScoredCandidate | null,
+    speedNote: string, routeNote: string = '',
 ): string {
     const total = all.length;
     const exhausted = all.filter((c) => c.exhausted).length;
@@ -277,7 +532,7 @@ function buildDecisionLog(
     return [
         `role=${role}: expected tier=${expectedTier}`,
         `${total} available, ${exhausted} exhausted, ${filtered.length} candidates`,
-        `picked=${picked.selector} tier=${picked.tier} gap=${picked.tierGap}`,
+        `picked=${picked.selector} tier=${picked.tier} class=${COVERAGE_LABEL[picked.coverageClass]} gap=${picked.tierGap}${picked.isProviderAuto ? ' auto' : ''}${speedNote}${routeNote}`,
         `reason=${picked.reason}`,
     ].join(' | ');
 }
@@ -290,10 +545,19 @@ export function selectAllRoles(
     allowlist: string[] | undefined,
     planProviders?: Set<string>,
     peakStatus?: PeakStatus,
+    paygLastResort?: boolean,
+    providerAuto?: Record<string, string>,
+    providerAutoTiers?: Record<string, TierName>,
+    /** Single trailing object (no more loose scalars); absent = W1 byte-stable order. */
+    speedAware?: SpeedAwareRuntime,
+    /** W4 质量带旋钮（透传 selectModel；缺省 = 既有分支逐字节）。 */
+    qualityPreference?: QualityPreference,
+    /** W4 数据层标注段（透传 selectModel；缺省零追加）。 */
+    note?: string,
 ): Record<string, SelectorResult> {
     const out: Record<string, SelectorResult> = {};
     for (const role of roles) {
-        out[role] = selectModel({ role, models, roleTiers, tierOverrides, health, allowlist, planProviders, peakStatus });
+        out[role] = selectModel({ role, models, roleTiers, tierOverrides, health, allowlist, planProviders, peakStatus, paygLastResort, providerAuto, providerAutoTiers, speedAware, qualityPreference, note });
     }
     return out;
 }

package/lib/model-speed.ts

@@ -0,0 +1,189 @@
+/**
+ * Speed-aware selection — read-only consumer of the host `agent.db`
+ * `model_perf` table (change: speed-aware-selection).
+ *
+ * Data plane: `model_perf(model_key TEXT PRIMARY KEY, samples REAL,
+ * output_tokens REAL, gen_ms REAL, ttft_samples REAL, ttft_ms REAL,
+ * updated_at INTEGER)`. Cumulative counters per model; tok/s =
+ * `output_tokens / gen_ms × 1000`, ttft = `ttft_ms / ttft_samples` (0 when no
+ * TTFT data). The provider segment of `model_key` keeps its catalog alias
+ * verbatim (`ArkCodingPlan/...`), so index keys are normalized through
+ * `canonicalizeProvider` + lowercase id — the same convention the selector
+ * uses on the candidate side.
+ *
+ * Read path is event-driven only (no timer, no background task): the first
+ * enabled selection opens the DB once, and a module-level TTL cache (300s)
+ * serves every selection in between. Read failures (missing db / missing
+ * table / corrupt file) degrade to an empty index with the same negative
+ * TTL — silently, by design: an optional data source must never pollute the
+ * selection path's log. Zero writers: the DB opens `readonly` and every
+ * statement is a SELECT. This module deliberately does NOT import
+ * concurrency-control (independent read-only consumer, no file coupling).
+ */
+
+import { Database } from 'bun:sqlite';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { canonicalizeProvider } from './usage-resolver.js';
+
+/** Aggregated speed entry for one model (tokPerS rounded by the consumer). */
+export interface SpeedEntry {
+    /** Output tokens per second: sum(output_tokens)/sum(gen_ms)×1000. */
+    tokPerS: number;
+    /** Mean time-to-first-token in ms; 0 when the row carries no TTFT data. */
+    ttftMs: number;
+    /** Sample count (post min_samples filter — always ≥ the threshold). */
+    samples: number;
+}
+
+/** Normalized model key → measured speed. */
+export type SpeedIndex = ReadonlyMap<string, SpeedEntry>;
+
+/** Comparison modes for the speed slot (see model-selector). */
+export const SPEED_MODES = ['tie-break', 'aggressive'] as const;
+export type SpeedMode = (typeof SPEED_MODES)[number];
+
+export interface SpeedAwareConfig {
+    enabled: boolean;
+    mode: SpeedMode;
+    minSamples: number;
+}
+
+/** Everything the selector needs: the mode plus the loaded index. */
+export interface SpeedAwareRuntime {
+    mode: SpeedMode;
+    index: SpeedIndex;
+}
+
+/** Rows below this sample count stay unmeasured (load-time filter). */
+export const DEFAULT_MIN_SAMPLES = 20;
+/** Module-level cache lifetime; expired → reload on the next selection. */
+export const SPEED_CACHE_TTL_MS = 300_000;
+
+/** Cost-band quantization constants (selector imports these — frozen slots). */
+export const FREE_BAND = 0;
+export const SENTINEL_BAND = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Normalize a model key to the index/candidate lookup convention:
+ * `canonicalizeProvider(providerSegment)/idSegment.toLowerCase()`.
+ * `model_key` rows keep the provider alias verbatim (`ArkCodingPlan/...`),
+ * candidates carry the catalog spelling — both fold onto the same key.
+ */
+export function speedIndexKey(modelKey: string): string {
+    const slash = modelKey.indexOf('/');
+    if (slash < 0) return modelKey.toLowerCase();
+    return `${canonicalizeProvider(modelKey.slice(0, slash))}/${modelKey.slice(slash + 1).toLowerCase()}`;
+}
+
+export interface LoadSpeedIndexOptions {
+    /** Rows with samples below this are skipped (defaults to DEFAULT_MIN_SAMPLES). */
+    minSamples?: number;
+}
+
+/** Defensive numeric column read: number → finite as-is, bigint → number, else 0. */
+function toNumber(value: unknown): number {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'bigint') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : 0;
+    }
+    return 0;
+}
+
+/**
+ * Load the whole `model_perf` table into a normalized speed index.
+ * Opens the DB `readonly` and closes it in a `finally` — throws on missing
+ * db/table/corrupt file (the caller decides whether to degrade silently).
+ */
+export function loadSpeedIndex(dbPath: string, opts?: LoadSpeedIndexOptions): SpeedIndex {
+    const minSamples = opts?.minSamples ?? DEFAULT_MIN_SAMPLES;
+    const db = new Database(dbPath, { readonly: true });
+    loadCountForTest++;
+    try {
+        // SELECT * + name-based reads: hosts with an older schema (no ttft
+        // columns) degrade naturally — undefined → 0, no fallback query.
+        const rows = db.query('SELECT * FROM model_perf').all() as Array<Record<string, unknown>>;
+        const out = new Map<string, SpeedEntry>();
+        for (const row of rows) {
+            const modelKey = row.model_key;
+            if (typeof modelKey !== 'string' || modelKey === '') continue;
+            const genMs = toNumber(row.gen_ms);
+            if (genMs <= 0) continue;
+            const samples = toNumber(row.samples);
+            if (samples < minSamples) continue;
+            const ttftSamples = toNumber(row.ttft_samples);
+            const ttftMs = toNumber(row.ttft_ms);
+            out.set(speedIndexKey(modelKey), {
+                tokPerS: (toNumber(row.output_tokens) / genMs) * 1000,
+                ttftMs: ttftSamples > 0 ? ttftMs / ttftSamples : 0,
+                samples,
+            });
+        }
+        return out;
+    } finally {
+        db.close();
+    }
+}
+
+// ── module-level TTL singleton (event-driven; no timers) ────────────────────
+
+let cache: { index: SpeedIndex; loadedAt: number } | null = null;
+let dbPathForTest: string | null = null;
+let loadCountForTest = 0;
+
+function refreshCache(minSamples: number, now: number): SpeedIndex {
+    let index: SpeedIndex;
+    try {
+        index = loadSpeedIndex(dbPathForTest ?? join(homedir(), '.omp', 'agent', 'agent.db'), { minSamples });
+    } catch {
+        // Missing db / missing table / corrupt file → empty index, same TTL
+        // as a successful load (negative cache: no reopen storm), silent.
+        index = new Map();
+    }
+    cache = { index, loadedAt: now };
+    return index;
+}
+
+function currentCachedIndex(minSamples: number): SpeedIndex {
+    const now = Date.now();
+    if (cache && now - cache.loadedAt < SPEED_CACHE_TTL_MS) return cache.index;
+    return refreshCache(minSamples, now);
+}
+
+/**
+ * Assembly-layer hook: `undefined` config or `enabled: false` returns
+ * `undefined` with ZERO IO (the disabled path never touches the DB);
+ * otherwise returns the mode plus the TTL-cached speed index.
+ */
+export function resolveSpeedAware(cfg?: SpeedAwareConfig): SpeedAwareRuntime | undefined {
+    if (!cfg?.enabled) return undefined;
+    return { mode: cfg.mode, index: currentCachedIndex(cfg.minSamples) };
+}
+
+/**
+ * Frozen programmatic signature (programme smart-model-selection W3):
+ * measured entry for a model key (`provider/id`), or null when unmeasured.
+ * Walks the same default TTL singleton the selection path uses.
+ */
+export function speedScore(modelKey: string): SpeedEntry | null {
+    return currentCachedIndex(DEFAULT_MIN_SAMPLES).get(speedIndexKey(modelKey)) ?? null;
+}
+
+// ── test seams (precedent: index.ts `_setOpsxGlobalHomeForTest`) ────────────
+
+/** Point the singleton at a fixture db; `null` restores the derived default. */
+export function setSpeedDbPathForTest(path: string | null): void {
+    dbPathForTest = path;
+}
+
+/** Drop the TTL cache and zero the load counter (fresh baseline for zero-read assertions). */
+export function resetSpeedCacheForTest(): void {
+    cache = null;
+    loadCountForTest = 0;
+}
+
+/** Successful db opens since module load; zero-read assertions for disabled paths. */
+export function speedLoadCountForTest(): number {
+    return loadCountForTest;
+}