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

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# model-compare-opencode-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [OpenCode](https://opencode.ai) v2 plugin that picks the best value-for-money OpenRouter model from [canonical/model-compare](https://github.com/canonical/model-compare)'s ranking, for three priorities: `balanced`, `price`, `quality`. Ranking data comes from a vendored copy of upstream's `model_compare.py` (default) or the published `catalog.json`.
+
+Each priority is a live alias inside the existing OpenRouter provider — no new provider, no new credentials:
+
+| Alias | Resolves to |
+|---|---|
+| `openrouter/model-compare/balanced` | best all-round value pick |
+| `openrouter/model-compare/price` | best price pick |
+| `openrouter/model-compare/quality` | best quality pick |
+
+The alias re-points at the current pick while OpenCode runs (refresh every 30 minutes, data cache 6 hours). OpenCode's model picker shows it as `Model Compare: <priority> → <pick>`, with `(fallback)` or `(unavailable)` when the fallback is serving or the alias is disabled.
+
+
+## Install
+
+Add a `plugins` entry to `opencode.jsonc` (project or global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "model-compare-opencode-plugin",
+      "options": {
+        "source": "auto",
+        "defaultPriority": "balanced",
+        "fallback": "openrouter/z-ai/glm-5.3-flash"
+      }
+    }
+  ]
+}
+```
+
+All options are optional — see [Configuration](#configuration). The package is on npm; OpenCode resolves and loads it itself. To run a checkout of this repo instead, see [Development](#development).
+
+
+## Usage
+
+Point sessions at an alias — as the root default in `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openrouter/model-compare/balanced"
+}
+```
+
+Per agent (in the `.md` frontmatter):
+
+```md
+---
+description: Reviews changes for correctness
+mode: subagent
+model: openrouter/model-compare/quality
+---
+```
+
+Or via `--model`:
+
+```
+opencode run --model "msg"
+```
+
+
+**Where the alias binds.** An agent's `model` applies to subagent launches everywhere, and to primary agents only when you select the agent in the TUI. Headless runs (`opencode run --agent …`) and server-side agent switches do **not** apply it — the root default (or `--model`, or `/use-best`) governs.
+
+Commands:
+
+- `/use-best [priority]` — switch the session to `openrouter/model-compare/<p>` (defaults to `defaultPriority`). Refuses a disabled alias.
+- `/model-compare` — top 5 per priority with scores and data age; priorities whose `weights` override actually takes effect are labelled `(custom weights)` with recomputed scores, and each alias's current pick is marked `← current pick`. The output is a synthetic message (`resume: false`): it costs no model turn and, in a headless session, surfaces in the transcript at the next turn. In the TUI it opens the report dialog instead.
+
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `alt+m` | picks dialog — all three priorities with their current picks |
+| `alt+shift+m` | report dialog — the top-5 table; `return` switches the session to the highlighted model |
+| `up` / `down` | move the dialog cursor |
+| `return` | select the highlighted row (picks dialog: switch to that priority) |
+| `esc` | close the dialog |
+
+Both dialogs need an open session — with none, a toast explains and nothing else happens. The TUI has no `/use-best` keybinding: the slash command already covers switching.
+
+Status: the footer shows `MC: balanced → <pick>` (balanced only — `disabled`/`unavailable`/`(fallback)` as applicable; all three priorities live in the picks dialog). Toasts announce `/use-best` outcomes and pick changes — never for the first observation after load. Headless, all feedback is synthetic transcript messages at the next turn.
+
+
+## Configuration
+
+Options live under `plugins[].options`:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `source` | `auto` | `auto`, `local`, or `remote`. `auto` uses the vendored script when `python3` 3.10+ is available, otherwise the remote catalog |
+| `defaultPriority` | `balanced` | Priority used by `/use-best` with no argument |
+| `fallback` | unset | `openrouter/<id>` used when no pick is available. Only OpenRouter models work: the alias's `modelID` lives inside the `openrouter` provider. Runnability is checked at each resolution |
+| `weights` | upstream | Partial overrides per named priority (`quality`, `price`, `context`, `age`), merged with upstream's weights and renormalized to sum 1 |
+| `pinDays` | `14` | Age in days after which a pick is re-evaluated |
+| `minLead` | `0.03` | Score lead needed to replace a pinned pick |
+| `catalogURL` | published catalog | Remote source URL (`https://canonical.github.io/model-compare/catalog.json`). Only point it at a source you trust: it decides which models can be picked |
+| `scriptPath` | vendored copy | Development override for a local `model_compare.py` |
+
+A present-but-invalid value logs a warning and applies the default (`weights` drop invalid entries individually; the valid remainder applies). Absent options apply defaults silently. Setup never throws; the aliases stay functional.
+
+
+## Pinning and fallback
+
+Per priority the plugin keeps one pin/last-known-good record in plugin storage, keyed by the effective weights so different weight configurations don't collide. With a fresh catalog:
+
+- No pin: adopt the best candidate.
+- Pinned model gone or not runnable: switch to the best candidate now.
+- Pin older than `pinDays`: re-evaluate (which may re-adopt the same model; `since` resets on every adoption).
+- Otherwise: switch only when the best candidate leads the pinned pick by at least `minLead` (upstream's 0–1 score scale).
+
+Resolution order: pin (if runnable) → best runnable candidate → `fallback` (if runnable) → the alias is disabled. The fallback is never stored as a pin. Pins are advisory: concurrent OpenCode processes refresh independently, last writer wins.
+
+
+## Data sources
+
+- `auto` — vendored `vendor/model_compare.py` run with `python3` (no shell, 60 s timeout, minimal environment); degrades to remote when python3 is missing or the run fails.
+- `local` — the vendored script only; failures are reported and the pin/last-known-good pick is kept.
+- `remote` — HTTPS fetch of `catalogURL` with a 6-hour cache (upstream republishes every 6 hours).
+
+The last validated catalog is persisted, so ranking and `/model-compare` work offline after a restart. The cache is keyed by source (URL or script path), so changing the source never serves the previous source's data. Script exit code 2 means "no candidates" *or* an argparse usage error — never read it as "no candidates" alone.
+
+**Vendored pin:** `vendor/model_compare.py` is byte-identical to upstream `v0.3.1` (`vendor/UPSTREAM.json` records repo, tag, commit, sha256). Since upstream 0.3.0 the catalog is schema v2: `pricing` scalars hold effective-tier values — the tier in effect at 1M-token prompts — so models with OpenRouter price overrides are ranked at what a long session actually pays.
+
+**Upgrading the pin** — reviewed PRs only; nothing merges automatically:
+
+1. `node scripts/sync-vendor.mjs <tag>` — fetches the script at that commit, reports the sha256 change, re-pins `UPSTREAM.json`, prints the matching CHANGELOG section (`--check` verifies offline).
+2. Conformance tests check `--version`, schema v2, required fields, recomputed `overall` scores, and the standard-library-only import allowlist.
+3. The upgrade PR body lists script lines touching imports, URLs, environment variables, subprocess calls and file writes, for reviewer attention.
+4. Release with a changelog line naming the upstream tag; users run `opencode plugin update` (OpenCode checks but doesn't apply).
+
+A scheduled workflow opens a draft upgrade PR when upstream publishes a newer release (never a downgrade); a nightly canary exercises the script live; a weekly drift check compares the vendored sha256 against upstream's pinned commit and the published rankings against the published scores.
+
+
+## Troubleshooting
+
+- **`model-compare: no ranking data for openrouter/model-compare/<p>`** — an agent whose `model` is that alias made a primary request while the alias was disabled. The guard aborts the request — even when the root-governed effective model is healthy — to protect the configuration's intent. Set `options.fallback` or fix the data source. Primary requests only; title/compaction/generation are untouched.
+- **Primary run answered with a model I didn't configure** — the root default (and `/use-best`-switched sessions) fall back silently to OpenCode's choice when the alias is disabled. Agent `model` doesn't apply on headless primary runs anyway — see the binding note above.
+- **Where are the plugin's warnings?** Nowhere, currently: `opencode serve` prints nothing to stdio and plugin `console.warn` reaches no log. The visible diagnosis surface is `/model-compare` — its data-age and no-data lines.
+- **A pick change takes a minute or two to land, and runs started meanwhile wait.** When a pick changes (at most once per 30-minute refresh), the plugin replays OpenCode's provider/model/agent registries; the harness measured ~90–105 s, with runs started during the replay blocking. Nothing is wrong.
+- **`Model unavailable: openrouter/model-compare/<p>`** — a subagent configured with a disabled alias; OpenCode fails the launch before any request, so the guard is not involved.
+- **Data age in `/model-compare`** — the plugin's own acquisition time of the document, not upstream's `generated_at` (set at build time even when serving inputs from cache).
+- **No aliases at all** — the aliases live inside the `openrouter` provider; if it is not connected in the project, they cannot be created. The plugin warns at setup and on every refresh; primary runs fall back silently.
+
+
+## Development
+
+Run a checkout instead of the npm package:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "./src",
+      "options": {
+        "source": "auto"
+      }
+    }
+  ]
+}
+```
+
+OpenCode's local loader resolves a directory target strictly as `<dir>/index.*` — `exports` are ignored for local paths, and file targets are rejected. `src/` has the physical entry files (`src/index.ts`, `src/tui.tsx`); the plugin's imports resolve from the repo's `node_modules` (`npm ci` once at the repo root). The repo ships this setup as [`.test/`](.test/README.md). Two caveats: the watcher only watches package-style entries, so source edits need an OpenCode restart; and a bare package name is always npm-installed by OpenCode — it is not read from `node_modules` — so local testing must use the directory form.
+
+```sh
+npm test                                              # unit + vendored-conformance suites (hermetic)
+MC_INTEGRATION=1 npx vitest run tests/integration/    # live-server suite (opt-in)
+```
+
+- The integration files skip unless `MC_INTEGRATION=1`, so plain `npm test` stays hermetic. The suite drives a real `opencode serve` on 127.0.0.1:14721 and needs the `opencode` CLI and `python3` (skips cleanly when either is missing); one case needs network access and the `sqlite3` CLI.
+- `node scripts/pack-smoke.mjs` (also in CI) packs the plugin and checks the tarball against the packaging list (files, `exports`, relative imports). It does **not** load the package in OpenCode — install the tarball into a scratch project and confirm OpenCode loads it before publishing.
+- `fixtures/catalog-v0.3.0.json` is a recorded schema-v2 catalog; `fixtures/catalog-no-quality.json` is generated from it by `scripts/make-no-quality-fixture.py` (the vendored script's own quality-blind weights, so its scores are internally consistent). `node scripts/sync-vendor.mjs --check` verifies the pin's sha256 offline.
+- Repo layout: `src/core/` (pure ranking/pinning), `src/sources/` (local + remote acquisition), `src/opencode/` (aliases, guard, commands, storage, refresh), `vendor/` (pinned upstream script), `tests/{unit,conformance,integration}`.
+
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE). The vendored `vendor/model_compare.py` comes from [canonical/model-compare](https://github.com/canonical/model-compare) (GPL-3.0).

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "model-compare-opencode-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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": "./src/tui.tsx"
+  },
+  "files": [
+    "src",
+    "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"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "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")
+}