model-compare-opencode-plugin 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "model-compare-opencode-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "OpenCode plugin that switches OpenRouter model aliases to the best value-for-money pick from canonical/model-compare's ranking (balanced, price, quality).",
+  "keywords": [
+    "opencode",
+    "openrouter",
+    "model-compare",
+    "plugin",
+    "llm"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./dist/tui.js"
+  },
+  "files": [
+    "src",
+    "dist/tui.js",
+    "vendor/model_compare.py",
+    "vendor/UPSTREAM.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canonical/model-compare-opencode-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/canonical/model-compare-opencode-plugin/issues"
+  },
+  "homepage": "https://github.com/canonical/model-compare-opencode-plugin#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "seroval": "^1.6.9"
+  },
+  "scripts": {
+    "build": "node scripts/build-tui.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test && node scripts/pack-smoke.mjs"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.16"
+  },
+  "peerDependencies": {
+    "@opentui/core": "^0.5.8",
+    "@opentui/solid": "^0.5.8",
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
+    "@types/node": "^22.18.13",
+    "solid-js": "1.9.12",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}

package/src/config.ts

@@ -0,0 +1,197 @@
+// src/config.ts
+// Plugin option parsing (design §3): warn-and-default validation over the
+// raw `options` object OpenCode hands the plugin. Any violation logs a
+// warning naming the option and applies the default (or drops the offending
+// piece); absent options apply their default silently. Never throws —
+// whatever shape arrives collapses to a usable Config.
+//
+// Absent-vs-invalid: an option OpenCode didn't set (`undefined`) simply takes
+// its default without a warning — nothing was misconfigured, and a bare
+// `plugins` entry without `options` must stay quiet. A value that IS present
+// but invalid warns. `fallback` and `scriptPath` additionally accept explicit
+// `null` as a valid "unset" (their §3 rows list `null` as legal).
+
+import type { Priority, Weights } from "./core/types"
+
+export type Config = {
+  source: "auto" | "local" | "remote"
+  defaultPriority: Priority
+  // "openrouter/<id>" (§3) or null.
+  fallback: string | null
+  weights: Partial<Record<Priority, Partial<Weights>>>
+  pinDays: number // default 14
+  minLead: number // default 0.03
+  catalogURL: string // default "https://canonical.github.io/model-compare/catalog.json"
+  scriptPath: string | null // null → vendored copy
+}
+
+const SOURCES = ["auto", "local", "remote"] as const
+const PRIORITIES = ["balanced", "price", "quality"] as const
+const WEIGHT_KEYS = ["quality", "price", "context", "age"] as const
+
+const DEFAULT_CATALOG_URL = "https://canonical.github.io/model-compare/catalog.json"
+const FALLBACK_PREFIX = "openrouter/"
+
+// True for plain config objects. Arrays are excluded: their index keys are
+// never meaningful option names, so they warn like any other garbage.
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+// A safe rendering of an offending value for warning messages. Deliberately
+// avoids JSON.stringify, which throws on circular structures.
+function shown(v: unknown): string {
+  if (typeof v === "string") return `"${v}"`
+  if (typeof v === "object" && v !== null) return Array.isArray(v) ? "an array" : "an object"
+  if (typeof v === "function") return "a function"
+  return String(v)
+}
+
+function isEnumValue(v: unknown, names: readonly string[]): v is string {
+  return typeof v === "string" && (names as readonly string[]).includes(v)
+}
+
+export function parseConfig(raw: unknown): { config: Config; warnings: string[] } {
+  const warnings: string[] = []
+  const o: Record<string, unknown> = isPlainObject(raw) ? raw : {}
+
+  // source — one of the three names (§3).
+  let source: Config["source"] = "auto"
+  if (o.source !== undefined) {
+    if (isEnumValue(o.source, SOURCES)) {
+      source = o.source as Config["source"]
+    } else {
+      warnings.push(
+        `invalid source: ${shown(o.source)} is not one of "auto", "local", "remote"; using "auto"`,
+      )
+    }
+  }
+
+  // defaultPriority — one of the three Priority names.
+  let defaultPriority: Priority = "balanced"
+  if (o.defaultPriority !== undefined) {
+    if (isEnumValue(o.defaultPriority, PRIORITIES)) {
+      defaultPriority = o.defaultPriority as Priority
+    } else {
+      warnings.push(
+        `invalid defaultPriority: ${shown(o.defaultPriority)} is not one of` +
+          ` "balanced", "price", "quality"; using "balanced"`,
+      )
+    }
+  }
+
+  // fallback — "openrouter/<id>" with a non-empty, "#"-free remainder (§3),
+  // or unset. Explicit null counts as unset.
+  let fallback: string | null = null
+  const rawFallback = o.fallback
+  if (rawFallback !== undefined && rawFallback !== null) {
+    if (
+      typeof rawFallback === "string" &&
+      rawFallback.startsWith(FALLBACK_PREFIX) &&
+      rawFallback.length > FALLBACK_PREFIX.length &&
+      !rawFallback.includes("#")
+    ) {
+      fallback = rawFallback
+    } else {
+      warnings.push(
+        `invalid fallback: ${shown(rawFallback)} is not "openrouter/<model-id>"; treating it as unset`,
+      )
+    }
+  }
+
+  // weights — partial overrides per named priority. Unknown priority names,
+  // unknown weight keys, and values that aren't finite numbers ≥ 0 are
+  // dropped individually; the valid remainder is kept. An override whose
+  // keys all drop leaves no entry behind: an empty override would change
+  // downstream ranking semantics (§6) despite overriding nothing.
+  const weights: Config["weights"] = {}
+  const rawWeights = o.weights
+  if (rawWeights !== undefined) {
+    if (!isPlainObject(rawWeights)) {
+      warnings.push(
+        `invalid weights: ${shown(rawWeights)} is not an object; ignoring all weight overrides`,
+      )
+    } else {
+      for (const [priority, override] of Object.entries(rawWeights)) {
+        if (!isEnumValue(priority, PRIORITIES)) {
+          warnings.push(`invalid weights: unknown priority "${priority}"; dropping its override`)
+          continue
+        }
+        if (!isPlainObject(override)) {
+          warnings.push(
+            `invalid weights.${priority}: ${shown(override)} is not an object; dropping the override`,
+          )
+          continue
+        }
+        const kept: Partial<Weights> = {}
+        for (const [key, value] of Object.entries(override)) {
+          if (!isEnumValue(key, WEIGHT_KEYS)) {
+            warnings.push(`invalid weights.${priority}: unknown weight key "${key}"; dropping it`)
+            continue
+          }
+          if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            warnings.push(
+              `invalid weights.${priority}.${key}: ${shown(value)} is not a number ≥ 0; dropping it`,
+            )
+            continue
+          }
+          kept[key as keyof Weights] = value
+        }
+        if (Object.keys(kept).length > 0) weights[priority as Priority] = kept
+      }
+    }
+  }
+
+  // pinDays — a finite number > 0; fractional days are fine.
+  let pinDays = 14
+  if (o.pinDays !== undefined) {
+    const v = o.pinDays
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) {
+      pinDays = v
+    } else {
+      warnings.push(`invalid pinDays: ${shown(v)} is not a positive number; using 14`)
+    }
+  }
+
+  // minLead — a finite number in [0, 1].
+  let minLead = 0.03
+  if (o.minLead !== undefined) {
+    const v = o.minLead
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1) {
+      minLead = v
+    } else {
+      warnings.push(`invalid minLead: ${shown(v)} is not a number between 0 and 1; using 0.03`)
+    }
+  }
+
+  // catalogURL — an "https://" URL; anything else gets the published catalog.
+  let catalogURL = DEFAULT_CATALOG_URL
+  if (o.catalogURL !== undefined) {
+    const v = o.catalogURL
+    if (typeof v === "string" && v.startsWith("https://")) {
+      catalogURL = v
+    } else {
+      warnings.push(
+        `invalid catalogURL: ${shown(v)} is not an "https://" URL; using the published catalog`,
+      )
+    }
+  }
+
+  // scriptPath — a non-empty string, or unset/null for the vendored copy.
+  let scriptPath: string | null = null
+  const rawScriptPath = o.scriptPath
+  if (rawScriptPath !== undefined && rawScriptPath !== null) {
+    if (typeof rawScriptPath === "string" && rawScriptPath.length > 0) {
+      scriptPath = rawScriptPath
+    } else {
+      warnings.push(
+        `invalid scriptPath: ${shown(rawScriptPath)} is not a non-empty string; using the vendored copy`,
+      )
+    }
+  }
+
+  return {
+    config: { source, defaultPriority, fallback, weights, pinDays, minLead, catalogURL, scriptPath },
+    warnings,
+  }
+}

package/src/core/catalog.ts

@@ -0,0 +1,189 @@
+// src/core/catalog.ts
+// Catalog document validation (design §5). Accepts schema v2 documents (only) from
+// either source (vendored script or remote catalog) and projects them onto
+// the plugin's Catalog type. Validation only — ranking lives elsewhere.
+
+import type { Catalog, ModelEntry, Priority, Weights } from "./types"
+
+const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+const SCORE_KEYS = ["quality", "price", "context", "age"] as const
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function validateCatalog(
+  raw: unknown,
+): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
+  if (!isObject(raw)) return { ok: false, reason: "catalog must be a JSON object" }
+
+  // Supported schema: v2 only — upstream's current contract (0.3.0: pricing
+  // scalars are effective-tier values; pricing.base/tiers/schedule and a
+  // top-level schedules index were added — ignored here, see the roadmap
+  // for consumer ideas). The plugin has never been released, so no stored
+  // v1 documents exist anywhere; the published catalog has served v2 since
+  // 2026-10-10.
+  if (raw.schema_version !== 2) {
+    return { ok: false, reason: `schema_version must be 2, got ${JSON.stringify(raw.schema_version)}` }
+  }
+  if (typeof raw.generated_at !== "string") {
+    return { ok: false, reason: "generated_at must be a string" }
+  }
+
+  // parameters.weights: optional; kept as published (possibly partial, keys
+  // absent upstream stay absent), except that every value must survive a
+  // sanity check: only the four WEIGHT_KEYS with a finite, non-negative
+  // number are kept (a string, NaN/±Infinity or negative weight is dropped
+  // like an unknown key — a hostile catalogURL serves arbitrary JSON here).
+  // An all-dropped map behaves as absent: with every priority map dropped,
+  // weights stays {} and consumers fall back to DEFAULT_WEIGHTS (design §5);
+  // when at least one map survives, a dropped priority reads as a missing
+  // one — weight 0 per the documented no-data semantics.
+  const weights: Partial<Record<Priority, Partial<Weights>>> = {}
+  const weightsRaw = isObject(raw.parameters) ? raw.parameters.weights : undefined
+  if (weightsRaw !== undefined) {
+    if (!isObject(weightsRaw)) return { ok: false, reason: "parameters.weights must be an object" }
+    for (const priority of PRIORITIES) {
+      const entry = weightsRaw[priority]
+      if (entry === undefined) continue
+      if (!isObject(entry)) {
+        return { ok: false, reason: `parameters.weights.${priority} must be an object` }
+      }
+      // The weight keys are the same four names as the score components.
+      const filtered: Partial<Weights> = {}
+      for (const key of SCORE_KEYS) {
+        const value = entry[key]
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) filtered[key] = value
+      }
+      if (Object.keys(filtered).length === 0) continue
+      weights[priority] = filtered
+    }
+  }
+
+  // models: required. Each entry needs an id and full scores (components and
+  // overall), plus the fields the ModelEntry type promises: a string name, an
+  // object pricing with a numeric blended_per_1m (the price tie-break reads
+  // it), and a numeric context — matching upstream, where models without
+  // parseable pricing land in filtered, never in models (design §5). Every
+  // numeric must be a FINITE number: JSON.parse("1e999") and hand-edited
+  // storage records can carry Infinity/NaN, and either poisons the ranking
+  // comparators (Infinity - Infinity is NaN) — a non-finite value rejects the
+  // document in the same reason style as a non-number. The optional pricing
+  // split (input_per_1m/output_per_1m) survives only as finite numbers — the
+  // values fmtPrice reads — while every other listed field is optional and
+  // passes through as published.
+  if (!Array.isArray(raw.models)) return { ok: false, reason: "models must be an array" }
+  const models: ModelEntry[] = []
+  for (let i = 0; i < raw.models.length; i++) {
+    const entry = raw.models[i]
+    if (!isObject(entry)) return { ok: false, reason: `models[${i}] must be an object` }
+    if (typeof entry.id !== "string") return { ok: false, reason: `models[${i}].id must be a string` }
+    if (!isObject(entry.scores)) return { ok: false, reason: `models[${i}].scores must be an object` }
+
+    const components = {} as Record<(typeof SCORE_KEYS)[number], number>
+    for (const key of SCORE_KEYS) {
+      const value = entry.scores[key]
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return { ok: false, reason: `models[${i}].scores.${key} must be a number` }
+      }
+      components[key] = value
+    }
+    if (!isObject(entry.scores.overall)) {
+      return { ok: false, reason: `models[${i}].scores.overall must be an object` }
+    }
+    const overall = {} as Record<Priority, number>
+    for (const priority of PRIORITIES) {
+      const value = entry.scores.overall[priority]
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return { ok: false, reason: `models[${i}].scores.overall.${priority} must be a number` }
+      }
+      overall[priority] = value
+    }
+
+    if (typeof entry.name !== "string") {
+      return { ok: false, reason: `models[${i}].name must be a string` }
+    }
+    const pricing = entry.pricing
+    if (!isObject(pricing)) {
+      return { ok: false, reason: `models[${i}].pricing must be an object` }
+    }
+    const blended = pricing.blended_per_1m
+    if (typeof blended !== "number" || !Number.isFinite(blended)) {
+      return { ok: false, reason: `models[${i}].pricing.blended_per_1m must be a number` }
+    }
+    if (typeof entry.context !== "number" || !Number.isFinite(entry.context)) {
+      return { ok: false, reason: `models[${i}].context must be a number` }
+    }
+
+    // quality is optional (number | null): a non-number is coerced to null as
+    // before, but a NUMBER must be finite — NaN/Infinity would poison the
+    // quality tie-break in byRankingKey.
+    if (typeof entry.quality === "number" && !Number.isFinite(entry.quality)) {
+      return { ok: false, reason: `models[${i}].quality must be a finite number` }
+    }
+    const quality = typeof entry.quality === "number" ? entry.quality : null
+    // The optional pricing split: kept only when finite numbers. A hostile
+    // catalogURL can serve any JSON here and fmtPrice reads these as numbers
+    // — a non-numeric or non-finite value is dropped to undefined (absent
+    // stays absent, present-but-invalid behaves as absent).
+    const input = pricing.input_per_1m
+    const output = pricing.output_per_1m
+    models.push({
+      ...entry,
+      id: entry.id,
+      name: entry.name,
+      pricing: {
+        ...pricing,
+        blended_per_1m: blended,
+        input_per_1m: typeof input === "number" && Number.isFinite(input) ? input : undefined,
+        output_per_1m: typeof output === "number" && Number.isFinite(output) ? output : undefined,
+      },
+      context: entry.context,
+      scores: { ...components, overall },
+      quality,
+    })
+  }
+
+  // rankings: optional; when present, each known priority must map to an
+  // ordered list of model ids. Unknown priority keys are ignored.
+  const rankings: Partial<Record<Priority, string[]>> = {}
+  if (raw.rankings !== undefined) {
+    if (!isObject(raw.rankings)) return { ok: false, reason: "rankings must be an object" }
+    for (const priority of PRIORITIES) {
+      const list = raw.rankings[priority]
+      if (list === undefined) continue
+      if (!Array.isArray(list) || !list.every((id) => typeof id === "string")) {
+        return { ok: false, reason: `rankings.${priority} must be an array of strings` }
+      }
+      rankings[priority] = [...(list as string[])]
+    }
+  }
+
+  return {
+    ok: true,
+    catalog: {
+      generatedAt: raw.generated_at,
+      weights,
+      rankings,
+      models,
+    },
+  }
+}
+
+// Re-validates a catalog read back from plugin storage (the projected
+// `Catalog`, not the raw upstream document) by rebuilding the raw shape and
+// running it through validateCatalog: a corrupt or hand-edited record is
+// rejected instead of reaching ranking code. The round trip is lossless for a
+// catalog validateCatalog produced.
+export function validateStoredCatalog(
+  stored: unknown,
+): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
+  if (!isObject(stored)) return { ok: false, reason: "stored catalog must be an object" }
+  return validateCatalog({
+    schema_version: 2,
+    generated_at: stored.generatedAt,
+    parameters: { weights: stored.weights },
+    models: stored.models,
+    rankings: stored.rankings,
+  })
+}

package/src/core/hash.ts

@@ -0,0 +1,12 @@
+// src/core/hash.ts
+// 32-bit FNV-1a as lowercase hex. Used to derive storage keys (pin records by
+// effective weights §7.2, the document cache by source identity) — not a
+// security primitive.
+export function fnv1aHex(input: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0")
+}

package/src/core/pins.ts

@@ -0,0 +1,158 @@
+// src/core/pins.ts
+// Pin/last-known-good state and pick resolution (design §7, §9). Pure
+// decision logic over a validated Catalog — no I/O, no OpenCode imports; the
+// caller supplies runnability, the stored pin, and the clock.
+
+import type { Catalog, Priority, Weights } from "./types"
+import { fnv1aHex } from "./hash"
+import { effectiveWeights, overallScore, rankModels } from "./rank"
+
+// One record per priority and effective-weights hash: both the pin and the
+// last-known-good pick (§7.2).
+export type Pin = { v: 1; id: string; since: number }
+
+export type ResolveInput = {
+  catalog: Catalog | null
+  p: Priority
+  override?: Partial<Weights>
+  // True when OpenCode lists `openrouter/<id>` as an enabled model (§7.1).
+  // Receives bare catalog ids.
+  runnable: (id: string) => boolean
+  // Config value like "openrouter/<id>", or null (§3).
+  fallback: string | null
+  stored: Pin | null
+  now: number
+  pinDays: number
+  minLead: number
+}
+
+export type ResolveResult = {
+  targetId: string | null
+  source: "pick" | "pin" | "fallback" | "none"
+  // The pin state after this resolution: a freshly adopted/kept record, or
+  // null only when nothing was adopted and nothing is stored (§7.8 keeps the
+  // fallback out of the pin; §9 skips, never deletes, an unrunnable record).
+  pin: Pin | null
+  notices: string[]
+}
+
+const PROVIDER_PREFIX = "openrouter/"
+const DAY_MS = 86_400_000
+
+// Config values look like "openrouter/<id>"; catalog ids are bare. Strip
+// exactly one leading prefix — a bare id may itself contain slashes
+// (provider/model), so nothing beyond the prefix is touched.
+function bareModelId(configValue: string): string {
+  return configValue.startsWith(PROVIDER_PREFIX)
+    ? configValue.slice(PROVIDER_PREFIX.length)
+    : configValue
+}
+
+export { fnv1aHex }
+
+export function pinKey(p: Priority, w: Weights): string {
+  return `pin/${p}/${fnv1aHex(JSON.stringify(w))}`
+}
+
+// §9's chain when there is no runnable pick from ranking: configured fallback
+// (checked by bare id) → none. `stored` rides along as the pin state: the
+// fallback itself is never stored as a pin (§7.8).
+function fallbackOrNone(
+  fallback: string | null,
+  runnable: (id: string) => boolean,
+  stored: Pin | null,
+  notices: string[],
+): ResolveResult {
+  if (fallback !== null) {
+    const bare = bareModelId(fallback)
+    if (runnable(bare)) {
+      notices.push(`fallback used: ${bare}`)
+      return { targetId: bare, source: "fallback", pin: stored, notices }
+    }
+  }
+  return { targetId: null, source: "none", pin: stored, notices }
+}
+
+export function resolve(input: ResolveInput): ResolveResult {
+  const { catalog, p, override, runnable, fallback, stored, now, pinDays, minLead } = input
+  const notices: string[] = []
+
+  // Without a fresh catalog (§9): stored pin (if runnable) → fallback (if
+  // runnable) → none. No rank-related notices — there is no ranking here.
+  if (catalog === null) {
+    if (stored && runnable(stored.id)) {
+      return { targetId: stored.id, source: "pin", pin: stored, notices }
+    }
+    if (stored) notices.push(`pin skipped: ${stored.id} is not runnable`)
+    return fallbackOrNone(fallback, runnable, stored, notices)
+  }
+
+  // Fresh catalog (§7.4): rank under the current weights, then walk the order
+  // for the first runnable candidate.
+  const eff = effectiveWeights(catalog, p, override)
+  // "Override ignored" notices: whatever the weight merge chose to ignore.
+  notices.push(...eff.warnings)
+  const ranked = rankModels(catalog, p, override).ids
+  const byId = new Map(catalog.models.map((m) => [m.id, m]))
+  const best = ranked.find((id) => runnable(id)) ?? null
+
+  // §9 when the fresh rules yield no runnable candidate: same chain as the
+  // no-catalog path.
+  if (best === null) {
+    if (stored && runnable(stored.id)) {
+      return { targetId: stored.id, source: "pin", pin: stored, notices }
+    }
+    if (stored) notices.push(`pin skipped: ${stored.id} is not runnable`)
+    return fallbackOrNone(fallback, runnable, stored, notices)
+  }
+
+  // (Re)adopt the best candidate; the target staying the stored pin id (only
+  // possible on the expiry re-adoption below) still counts as "pin".
+  const adopt = (id: string): ResolveResult => ({
+    targetId: id,
+    source: stored !== null && id === stored.id ? "pin" : "pick",
+    pin: { v: 1, id, since: now },
+    notices,
+  })
+
+  if (stored === null) return adopt(best)
+
+  const pinEntry = byId.get(stored.id) ?? null
+
+  // (a) The pinned model is not runnable, or has left the pool — §7.4 says
+  // switch to the best candidate now. (A ranking entry outside the pool could
+  // still name the pin id; that degenerates into a same-id re-adoption.)
+  if (!runnable(stored.id) || pinEntry === null) {
+    if (best !== stored.id) notices.push(`pin switched: ${stored.id} → ${best}`)
+    return adopt(best)
+  }
+
+  // (b) The pin is older than pinDays: re-adopt the best candidate — which
+  // may be the pinned model itself — and reset `since` (§7.4 "which may be
+  // the same model"; §7.6 "since resets every time a pin is adopted or
+  // re-adopted").
+  if (now - stored.since > pinDays * DAY_MS) {
+    if (best !== stored.id) notices.push(`pin switched: ${stored.id} → ${best}`)
+    return adopt(best)
+  }
+
+  // Nothing changed: keep the pin exactly as stored, clock untouched.
+  if (best === stored.id) {
+    return { targetId: stored.id, source: "pin", pin: stored, notices }
+  }
+
+  // (c) Switch only when the challenger leads by ≥ minLead; both scores come
+  // from the current catalog under the current effective weights (§7.4). A
+  // challenger missing from the pool can't be scored, so it can't lead.
+  const bestEntry = byId.get(best) ?? null
+  const lead =
+    bestEntry === null
+      ? Number.NEGATIVE_INFINITY
+      : overallScore(bestEntry, eff.weights) - overallScore(pinEntry, eff.weights)
+  if (lead >= minLead) {
+    notices.push(`pin switched: ${stored.id} → ${best}`)
+    return adopt(best)
+  }
+
+  return { targetId: stored.id, source: "pin", pin: stored, notices }
+}