model-compare-opencode-plugin 0.1.3 → 0.3.0

package/README.md

@@ -77,6 +77,7 @@ Commands:
 | Key | Action |
 |---|---|
 | `alt+m` | picks dialog — all three priorities with their current picks |
+| `alt+e` | toast the last response's served endpoint, alias responses only (`!` prefix flags a downgrade — not in the steering order) |
 | `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) |
@@ -84,7 +85,7 @@ Commands:
 
 Both dialogs open anywhere — including the opening screen, where no session exists yet. There, picking a row (a priority in the picks dialog, a model in the report) creates a new session already bound to that model and opens it; merely opening a dialog never creates a session. With a session open, a pick switches that session as before. 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.
+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), the `alt+e` served endpoint, and the cannot-steer notice — see [Steering and served endpoints](#steering-and-served-endpoints). Headless, command feedback is synthetic transcript messages at the next turn; the steering toasts have no headless surface.
 
 
 ## Configuration
@@ -99,7 +100,7 @@ Options live under `plugins[].options`:
 | `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 |
+| `catalogURL` | published catalog | Remote source URL. The catalog is published at `https://model-compare.dev/catalog.json` — the plugin's built-in default, fetched directly over https. (The old `https://canonical.github.io/model-compare/catalog.json` home redirects to a plaintext `http://` target; the plugin fails closed on any redirect that leaves https.) 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.
@@ -117,6 +118,35 @@ Per priority the plugin keeps one pin/last-known-good record in plugin storage,
 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.
 
 
+## Steering and served endpoints
+
+Requests made through one of the three aliases carry the resolved pick's routing: the catalog's per-model `steering` block is injected into the request body under OpenRouter's `provider` key, so the call is routed onto the endpoints whose pricing the ranking actually ranked — not onto whatever OpenRouter's default routing picks, which can be a sub-default-quantization endpoint at a price the ranking never saw.
+
+The block comes from the catalog, whichever source produced it: the vendored script derives it from the same per-model endpoint data its pricing uses, and the published catalog carries it ready-made. Only the block's `provider` sub-object is injected — its top-level `model` field never reaches the body — and the routing object is built field by field:
+
+- `order` — the endpoints the ranking priced, cheapest blended price first; eligible endpoints whose price can't be computed are appended last rather than dropped.
+- `ignore` — the live endpoints the ranking excluded, so OpenRouter cannot route onto pricing it never ranked (sub-default quantizations, schedule-gate failures, variants).
+- `quantizations` — the precision floor: the model's default precision and anything more precise among its live endpoints. The key is omitted entirely when the model has no default precision — never sent as an empty list, which would exclude every endpoint.
+- `allow_fallbacks` — always `true`: when nothing in `order` can serve, OpenRouter may still route outside the list.
+
+The rules, and the exceptions:
+
+- **Aliases only.** Steering fires only when the session's model is one of the three aliases and the request's model is that alias's current pick. What decides is the request's model reference: alias references steer, concrete references never do — a model you picked directly is untouched even when it is the exact model an alias currently resolves to. Primary turns and compaction alike are steered; auxiliary calls that run a different model (title generation) are not.
+- **A pre-existing `provider` key wins.** If the request body already carries a `provider` key — routing you or a provider integration configured — the plugin does not inject; it never clobbers routing it did not choose.
+- **No steering data, no injection.** When the plugin has no catalog source, or the current pick's catalog entry carries no `steering` block, the request proceeds untouched: OpenRouter's default routing applies and the run completes normally — unsteered, not failed. With no catalog source at all, the TUI says so once per session, on the first alias request that has a pick to steer: `cannot steer this session; OpenRouter default routing applies` (skipped when that request already carries its own `provider` — then default routing is not what applies). Headless runs render no toasts; the routing behavior is identical. A disabled alias steers nothing and toasts nothing; what serves then is the binding's own fallback behavior (see [Troubleshooting](#troubleshooting)).
+- **Always-on.** No option turns steering off. It is what makes the plugin's value promise — the ranked price is what you pay — true.
+
+`order` is a preference list, not a pinned destination: OpenRouter works down the list and serves from whichever ranked endpoint can take the call — which one serves is OpenRouter's decision, and with fallbacks allowed it can even land outside the list.
+
+**Which endpoint served a call.** Three ways to check:
+
+- The `alt+e` toast (see [Keyboard shortcuts](#keyboard-shortcuts)) — the current session's last primary alias response's served endpoint: `last response served by <endpoint>`, or `! served by <endpoint> — not in steering order` when the served provider matched no entry of the steering order actually applied. The report dialog's footer carries the same capture as `last response: <model> @ <endpoint>`, under the note `routing steered to <quant> endpoints (aliases only)`.
+- The response body — every OpenRouter response names its serving endpoint in the `provider` field.
+- OpenRouter's dashboard — per-request endpoint records.
+
+The alt+e capture is best-effort by design, and alias-scoped: only a session whose model is one of the three aliases has responses peeked and recorded — a direct pick's or another agent's response is never read, let alone modified. The plugin peeks at only the first 4 KB of the response body — a pass-through read; the body itself flows byte-for-byte. Streaming responses carry `provider` in the first chunk, so the peek normally catches them; a non-streaming response whose `provider` field sits beyond the peek window is forwarded uncaptured, and `alt+e` then toasts nothing. The response body's `provider` field and OpenRouter's dashboard remain the authoritative verification paths.
+
+
 ## 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.
@@ -125,16 +155,18 @@ Resolution order: pin (if runnable) → best runnable candidate → `fallback` (
 
 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.
+**Vendored pin:** `vendor/model_compare.py` is byte-identical to upstream `v0.4.0` (`vendor/UPSTREAM.json` records repo, tag, commit, sha256). Since upstream 0.4.0 the catalog is schema v3: `pricing` carries tier and schedule structure alongside the flat scalars, and `parameters` carries the published ranking weights. The plugin accepts schema v3 ONLY — `validateCatalog` rejects anything else — and releases are gated on the live remote serving v3 (the release-gate check pipes `https://model-compare.dev/catalog.json` through `scripts/canary-check.mjs`, which fails closed when the served document is not the expected schema). Effective-tier pricing semantics still apply: `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.
+
+**Vendored 0.4.0 cold-cache network profile:** since 0.4.0 the vendored script performs per-model endpoint-pricing fetches when building a fresh catalog (71 in the recorded run). Each fetch fails closed per model — after the script's internal retries, a failed endpoint fetch drops that model and the catalog shrinks silently (429-class responses raise without retry) — so a degraded network costs pool coverage, not pricing correctness. A cold cache under a slow network can exceed the plugin's 60-second local budget, in which case the plugin warns and falls back (`auto` → remote, `local` → its cached document).
 
 **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.
+2. Conformance tests check `--version`, schema v3, 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.
+A scheduled workflow opens a draft upgrade PR when upstream publishes a newer release (never a downgrade); a nightly canary exercises the vendored script against live upstream data and asserts the generated catalog is schema v3 (`scripts/canary-check.mjs` pins `EXPECTED_SCHEMA_VERSION = 3` and exits nonzero on any other version); releases additionally gate on the live remote itself (see the publishing gates below); a weekly drift check compares the vendored sha256 against upstream's pinned commit and the published rankings against the published scores.
 
 
 ## Troubleshooting
@@ -177,8 +209,8 @@ MC_INTEGRATION=1 npx vitest run tests/integration/    # live-server suite (opt-i
 - Local development loads `src/` directly and needs no build; the *published* package does — OpenCode's Solid JSX transform skips `node_modules` paths, so the npm-installed raw TSX cannot load (see [Install](#install) and the troubleshooting entry). `npm run build` precompiles `src/tui.tsx` through the same Babel pipeline as the host's loader (taken from the pinned `@opentui/solid`) into `dist/tui.js`, rebasing relative imports from `src/`-relative to `dist/`-relative; `prepublishOnly` runs it, and CI builds before the packaging check. `dist/` is regenerated, never committed.
 - 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, after `node scripts/build-tui.mjs`) packs the plugin and checks the tarball against the packaging list (files, `exports`, relative imports, and that the TUI artifact is precompiled — no react import). It does **not** load the package in OpenCode — install the tarball into a scratch project and confirm OpenCode loads it before publishing.
-- Publishing: cut a GitHub release tagged `vX.Y.Z` and `.github/workflows/release.yaml` stages the package on npm through trusted publishing (tokenless OIDC — no token secret; the npmjs.com trusted-publisher entry must name `release.yaml`, the `canonical/model-compare-opencode-plugin` repository and the `release` environment, with "Allow npm publish" and "Allow npm dist-tag" unchecked — stage-only, npm's recommended posture). Nothing goes live until a maintainer approves it with 2FA on npmjs.com (package page → Staged Packages) or via `npm stage approve`. The workflow fails closed when the tag does not match `package.json`'s version, and the gates (build, typecheck, tests, pack-smoke) run before staging.
-- `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.
+- Publishing: cut a GitHub release tagged `vX.Y.Z` and `.github/workflows/release.yaml` stages the package on npm through trusted publishing (tokenless OIDC — no token secret; the npmjs.com trusted-publisher entry must name `release.yaml`, the `canonical/model-compare-opencode-plugin` repository and the `release` environment, with "Allow npm publish" and "Allow npm dist-tag" unchecked — stage-only, npm's recommended posture). Nothing goes live until a maintainer approves it with 2FA on npmjs.com (package page → Staged Packages) or via `npm stage approve`. The workflow fails closed when the tag does not match `package.json`'s version, and the gates (build, typecheck, tests, pack-smoke, live-remote canary) run before staging.
+- `fixtures/catalog-v0.4.0.json` is the sole contract fixture — a recorded schema-v3 catalog; `fixtures/catalog-no-quality.json` is derived from it by `scripts/make-no-quality-fixture.py` (the vendored script's own quality-blind weights, so its scores are internally consistent). No v2 fixture exists; the v3-only gate rejects one. `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), `dist/` (generated `tui.js` artifact, gitignored), `vendor/` (pinned upstream script), `tests/{unit,conformance,integration}`.
 
 

package/dist/tui.js

@@ -57,7 +57,7 @@ import { TextAttributes, RGBA } from "@opentui/core";
 
 import { createEffect, createMemo, createRoot, createSignal } from "solid-js";
 import { ALIAS_PROVIDER, PRIORITIES, alignedPriority, aliasId, pickOf, pickFromName, readAliasViews, statusLine, useBestDecision, useBestNotice, useBestRefusal } from "../src/opencode/usebest";
-import { sanitizeCatalogText } from "../src/opencode/commands";
+import { lastResponseLine, sanitizeCatalogText } from "../src/opencode/commands";
 import { ModelCompare } from "../src/rpc";
 const TOAST_MS = 6_000;
 const RESYNC_MS = 30_000;
@@ -69,6 +69,11 @@ const PACKAGE_FRAGMENT = "model-compare-opencode-plugin";
 // The RPC event the /model-compare command emits (see src/rpc.ts; the wire
 // name is prefixed with the RPC's id).
 const REPORT_EVENT = "rpc.model-compare.report";
+// The event the runtime hook emits once per session when it would have
+// steered a request but has no steering data (no catalog source) — the Q2
+// fallback's runtime notification. The toast copy below is the whole message.
+const CANNOT_STEER_EVENT = "rpc.model-compare.cannotSteer";
+const CANNOT_STEER_COPY = "cannot steer this session; OpenRouter default routing applies";
 
 // The list dialogs' lifecycle token (see showListDialog): a module-scope
 // generation counter, bumped every time a dialog is armed, plus the armed
@@ -158,6 +163,30 @@ function toReportEntries(raw) {
     }];
   });
 }
+
+// The report payload's footer capture (the last-response line and the alt+e
+// toast's data), defensively normalized at the trust boundary like the
+// entries: anything but a well-shaped object — or one without an endpoint —
+// degrades to null (no capture), never a placeholder line.
+function toCapture(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const capture = raw;
+  if (typeof capture.endpoint !== "string" || capture.endpoint === "") return null;
+  return {
+    endpoint: capture.endpoint,
+    // The Task-5 handoff: a capture may carry an empty model (a response
+    // whose provider had no model id) — carried as-is, and the footer omits
+    // the model part rather than rendering an empty slot.
+    model: typeof capture.model === "string" ? capture.model : "",
+    downgrade: capture.downgrade === true
+  };
+}
+
+// The footer's steering note, defensively normalized: anything but a
+// non-empty string means the note does not render (no steering data).
+function toSteeringNote(raw) {
+  return typeof raw === "string" && raw !== "" ? raw : null;
+}
 export default Plugin.define({
   id: "model-compare-tui",
   async setup(context) {
@@ -347,7 +376,11 @@ export default Plugin.define({
     // dialog is open, cleared on close; the app slot's in-tree effect maps
     // it to a modal layer.
     const [listKeys, setListKeys] = createSignal(null);
-    function showListDialog(title, rows, onPick) {
+    function showListDialog(title, rows, onPick,
+    // The footer's extra lines (the report dialog's steering note and
+    // last-response line), rendered muted ABOVE the Details line. Absent
+    // for the other dialogs (the picks dialog carries no footer lines).
+    footerLines = []) {
       const selectable = rows.filter(row => row.value !== undefined);
       if (selectable.length === 0) {
         notify("nothing to select", "error");
@@ -594,9 +627,18 @@ export default Plugin.define({
             })();
           });
         });
+        _$insert(_el$2, () => footerLines.map(line => (() => {
+          var _el$18 = _$createElement("box"),
+            _el$19 = _$createElement("text");
+          _$insertNode(_el$18, _el$19);
+          _$setProp(_el$18, "paddingLeft", 4);
+          _$setProp(_el$19, "fg", muted);
+          _$insert(_el$19, line);
+          return _el$18;
+        })()), _el$8);
         _$insertNode(_el$8, _el$9);
         _$setProp(_el$8, "paddingLeft", 4);
-        _$insertNode(_el$9, _$createTextNode(`Details: https://canonical.github.io/model-compare`));
+        _$insertNode(_el$9, _$createTextNode(`Details: https://model-compare.dev`));
         _$setProp(_el$9, "fg", muted);
         _$effect(_p$ => {
           var _v$ = TextAttributes.BOLD,
@@ -701,9 +743,17 @@ export default Plugin.define({
           });
         }
       }
+      // The report dialog's footer (design §Decisions, option C): the
+      // steering note ABOVE the last-response line, both omitted when their
+      // data is absent — never a placeholder line.
+      const footerLines = [];
+      if (data.steeringNote !== null) footerLines.push(data.steeringNote);
+      const lastResponse = lastResponseLine(data.capture);
+      if (lastResponse !== null) footerLines.push(lastResponse);
       showListDialog(`Model Compare — top 5 (data age: ${data.age ?? "unknown"})`, rows, id => {
-        if (data.sessionID !== null) {
-          void switchToModel(data.sessionID, id);
+        const sessionID = data.sessionID;
+        if (sessionID !== null) {
+          void switchToModel(sessionID, id);
           return;
         }
         // The opening screen: the pick becomes a NEW session's model —
@@ -712,7 +762,7 @@ export default Plugin.define({
           providerID: ALIAS_PROVIDER,
           id
         }, `switched to openrouter/${sanitizeCatalogText(id)}`);
-      });
+      }, footerLines);
     }
 
     // The report dialog rides the /model-compare command's RPC event: ONE
@@ -732,13 +782,38 @@ export default Plugin.define({
       const entries = toReportEntries(data.entries);
       const eventSessionID = data.sessionID;
       // Ownerless callback: park the report on the signal — the app slot's
-      // in-tree effect opens the dialog (see pendingReport above).
+      // in-tree effect opens the dialog (see pendingReport above). The
+      // footer's fields ride the payload like the entries (defensively
+      // normalized at this trust boundary).
       setPendingReport({
         sessionID: eventSessionID,
         age: typeof data.age === "string" ? data.age : null,
-        entries
+        entries,
+        capture: toCapture(data.capture),
+        steeringNote: toSteeringNote(data.steeringNote)
       });
     });
+
+    // The cannot-steer fallback (Task 6): the runtime hook emits this event
+    // once per session when a steerable alias request finds no steering data
+    // (no catalog source). The TUI surfaces it as a toast with the exact
+    // fallback copy; headless shows nothing — like every TUI-coupled surface.
+    // Scoped exactly like the report listener: a foreign directory's session
+    // is never viewable here, and only the CURRENTLY viewed session toasts.
+    // Trade-off: a cannotSteer notice for a same-project background session
+    // (or a session the user isn't currently viewing) is dropped forever —
+    // the emit is once-per-session — but noise from unopened sessions is the
+    // worse failure; the notice is about the session the user interacts with.
+    const offCannotSteerEvent = context.data.listen(({
+      details
+    }) => {
+      const event = details;
+      if (event.type !== CANNOT_STEER_EVENT) return;
+      if (typeof event.location?.directory === "string" && here !== undefined && event.location.directory !== here) return;
+      const data = event.data;
+      if (typeof data?.sessionID !== "string" || data.sessionID !== currentSessionID()) return;
+      notify(CANNOT_STEER_COPY);
+    });
     createRoot(dispose => {
       disposeRoot = dispose;
 
@@ -867,7 +942,9 @@ export default Plugin.define({
           showReportDialog({
             sessionID: null,
             age: typeof data?.age === "string" ? data.age : null,
-            entries: toReportEntries(data?.entries)
+            entries: toReportEntries(data?.entries),
+            capture: toCapture(data?.capture),
+            steeringNote: toSteeringNote(data?.steeringNote)
           });
         } catch (error) {
           notify(`report failed: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -875,6 +952,41 @@ export default Plugin.define({
       }
     };
 
+    // The served-endpoint toast (design §Steering visibility): alt+e toasts
+    // the CURRENT session's last response's served endpoint, looked up
+    // through the report RPC's footer fields (the capture record rides the
+    // established report payload path). The copy is exact — normal:
+    // "last response served by <endpoint>"; downgrade (the served provider
+    // matched none of the applied steering order): "! served by <endpoint> —
+    // not in steering order"; nothing toasts when nothing was captured for
+    // the session (and with no session open there is nothing to look up).
+    const endpointCommand = {
+      id: "model-compare.endpoint",
+      title: "Last served endpoint",
+      group: "Model Compare",
+      bind: "alt+e",
+      palette: true,
+      run: async () => {
+        const sessionID = currentSessionID();
+        if (sessionID === null) return;
+        try {
+          const report = await context.client.rpc(ModelCompare).report({
+            sessionID
+          }, here === undefined ? undefined : {
+            location: {
+              directory: here
+            }
+          });
+          const capture = toCapture(report?.capture);
+          if (capture === null) return;
+          // F-20: the endpoint is response data — flattened for the toast.
+          notify(capture.downgrade ? `! served by ${sanitizeCatalogText(capture.endpoint)} — not in steering order` : `last response served by ${sanitizeCatalogText(capture.endpoint)}`);
+        } catch (error) {
+          notify(`endpoint lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+        }
+      }
+    };
+
     // The palette-only use-best: the immediate-toast variant. The SLASH
     // surface is left to the server command (one entry everywhere); the
     // palette is TUI-layer territory, where this variant's instant feedback
@@ -950,7 +1062,7 @@ export default Plugin.define({
         try {
           context.keymap.layer(() => ({
             mode: "global",
-            commands: [useBestCommand, picksCommand, reportCommand]
+            commands: [useBestCommand, picksCommand, reportCommand, endpointCommand]
           }));
         } catch (error) {
           layerFailure("the model-compare keymap layer", error);
@@ -967,6 +1079,7 @@ export default Plugin.define({
       if (resyncTimer !== undefined) clearInterval(resyncTimer);
       context.renderer.off("resize", onRendererResize);
       offReportEvent();
+      offCannotSteerEvent();
       disposeRoot();
       disposeAppSlot();
       disposeHomeFooter();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-compare-opencode-plugin",
-  "version": "0.1.3",
+  "version": "0.3.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",

package/src/config.ts

@@ -21,7 +21,7 @@ export type Config = {
   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"
+  catalogURL: string // default "https://model-compare.dev/catalog.json"
   scriptPath: string | null // null → vendored copy
 }
 
@@ -29,7 +29,10 @@ 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"
+// The published catalog's direct https URL — no redirect involved (the old
+// canonical.github.io home redirected to a plaintext http target, which
+// fetchRemote now refuses; see Ruling 9).
+const DEFAULT_CATALOG_URL = "https://model-compare.dev/catalog.json"
 const FALLBACK_PREFIX = "openrouter/"
 
 // True for plain config objects. Arrays are excluded: their index keys are

package/src/core/catalog.ts

@@ -1,5 +1,5 @@
 // src/core/catalog.ts
-// Catalog document validation (design §5). Accepts schema v2 documents (only) from
+// Catalog document validation (design §5). Accepts schema v3 documents (only) from
 // either source (vendored script or remote catalog) and projects them onto
 // the plugin's Catalog type. Validation only — ranking lives elsewhere.
 
@@ -12,19 +12,48 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
 
+function isNonEmptyStringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length > 0 && value.every((id) => typeof id === "string")
+}
+
+// The steering block (F-11/F-12): the raw upstream entry carries
+// { model, provider: { order, ignore, quantizations?, allow_fallbacks } }.
+// The projection unwraps `provider` as ModelEntry.steering and never projects
+// the top-level `model`. Per-field absence (the pricing-split posture), no
+// throw, no partial field: order/ignore must be non-empty string arrays (an
+// empty list would filter out every endpoint) and allow_fallbacks a boolean —
+// any miss drops the whole block; quantizations is optional and kept only as
+// a non-empty string array, otherwise that field alone is dropped and the
+// block survives.
+function steer(raw: unknown): ModelEntry["steering"] {
+  if (!isObject(raw)) return undefined
+  const provider = raw.provider
+  if (!isObject(provider)) return undefined
+  const order = provider.order
+  const ignore = provider.ignore
+  const fallbacks = provider.allow_fallbacks
+  if (!isNonEmptyStringList(order) || !isNonEmptyStringList(ignore) || typeof fallbacks !== "boolean") {
+    return undefined
+  }
+  const steering: NonNullable<ModelEntry["steering"]> = {
+    order: [...order],
+    ignore: [...ignore],
+    allow_fallbacks: fallbacks,
+  }
+  if (isNonEmptyStringList(provider.quantizations)) steering.quantizations = [...provider.quantizations]
+  return steering
+}
+
 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)}` }
+  // Supported schema: v3 only — upstream's current contract (0.4.0's
+  // schema_version 3). Every other version is rejected with the reason string
+  // the canary and the stored-document path rely on.
+  if (raw.schema_version !== 3) {
+    return { ok: false, reason: `schema_version must be 3, got ${JSON.stringify(raw.schema_version)}` }
   }
   if (typeof raw.generated_at !== "string") {
     return { ok: false, reason: "generated_at must be a string" }
@@ -128,6 +157,11 @@ export function validateCatalog(
     // stays absent, present-but-invalid behaves as absent).
     const input = pricing.input_per_1m
     const output = pricing.output_per_1m
+    // The steering block projects (or reads as absent) per the steer() rules.
+    // The assignment sits AFTER the spread so it explicitly overrides the raw
+    // block that `...entry` would otherwise carry through verbatim — a
+    // hostile steering block must never survive onto the projected entry.
+    const steering = steer(entry.steering)
     models.push({
       ...entry,
       id: entry.id,
@@ -141,6 +175,7 @@ export function validateCatalog(
       context: entry.context,
       scores: { ...components, overall },
       quality,
+      steering,
     })
   }
 
@@ -174,16 +209,26 @@ export function validateCatalog(
 // `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.
+// catalog validateCatalog produced. A model carrying a projected steering
+// block is re-wrapped into the raw { model, provider } shape first — the
+// top-level `model` is never projected, so entry.id stands in for it (the
+// projection ignores it either way). A hand-edited steering block re-projects
+// or reads as absent, exactly like a raw one would.
 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" }
+  const models = Array.isArray(stored.models)
+    ? stored.models.map((entry) => {
+        if (!isObject(entry) || entry.steering === undefined) return entry
+        return { ...entry, steering: { model: entry.id, provider: entry.steering } }
+      })
+    : stored.models
   return validateCatalog({
-    schema_version: 2,
+    schema_version: 3,
     generated_at: stored.generatedAt,
     parameters: { weights: stored.weights },
-    models: stored.models,
+    models,
     rankings: stored.rankings,
   })
 }

package/src/core/steering.ts

@@ -0,0 +1,145 @@
+// src/core/steering.ts
+// The steering decision core (design §Steering injection + served-endpoint
+// visibility): whether a request may carry the catalog's steering block, the
+// injection shape, and the served-endpoint membership verdict. Pure functions
+// over the data the wiring hooks supply — no I/O, no OpenCode imports.
+//
+// Layering note: the guard module (src/opencode/guard.ts) owns the canonical
+// alias-ref parse, but core modules never import from src/opencode (this
+// repo's rule: only opencode → core). The identification below mirrors the
+// guard's parseAliasRef exactly — variant-blind, exact-priority remainder —
+// and both copies are pinned to the same vectors (tests/unit/guard.test.ts
+// and the steeringFor cases here); a semantic change to one must be mirrored
+// in the other.
+
+import type { ModelEntry, Priority } from "./types"
+
+// A model reference as the hook event carries it (`event.model`), mirroring
+// the guard's ModelRef (src/opencode/guard.ts) structurally — the wiring
+// passes the event's ref straight through, and any `variant` key the event
+// adds is ignored (spike fact 1: the alias ref's variant is not stable across
+// binding styles — absent for root-default/frontmatter, "default" for
+// `--model` — so identification must stay variant-blind).
+export type ModelRef = { providerID: string; id: string }
+
+// The resolved pick for one priority, mirroring the alias registry's
+// AliasTarget (src/opencode/aliases.ts) structurally for the same layering
+// reason: the wiring passes its plan's picks directly.
+export type AliasTarget = { id: string | null; fromFallback: boolean }
+
+// The steering block exactly as ModelEntry.steering projects it (Task 2):
+// OpenRouter's provider routing sub-object. The raw upstream block's
+// top-level `model` field is never part of it.
+export type Steering = NonNullable<ModelEntry["steering"]>
+
+const ALIAS_PREFIX = "model-compare/"
+
+const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+
+// Alias identification over the event's model ref — the guard's parseAliasRef
+// rule mirrored (see the layering note above): ONLY openrouter plus
+// `model-compare/<p>` whose remainder is exactly a priority name; ids may
+// carry more slashes in OpenRouter's vendor/model style, so anything after
+// the priority disqualifies. Accepts undefined for runtime robustness (the
+// caller's ref is runtime data).
+function aliasPriority(ref: ModelRef | undefined): Priority | null {
+  if (ref === undefined || ref.providerID !== "openrouter") return null
+  if (!ref.id.startsWith(ALIAS_PREFIX)) return null
+  const remainder = ref.id.slice(ALIAS_PREFIX.length)
+  return PRIORITIES.includes(remainder as Priority) ? (remainder as Priority) : null
+}
+
+// The steering block to inject for a request, or null when the request must
+// not be steered: a non-alias ref (including a DIRECTLY-PICKED model — even
+// when its id equals the current pick's; matching on that equality would
+// INVERT the rule, since an alias-bound ref is never equal to a concrete pick
+// id while a directly-picked one is — and steer requests outside the aliases,
+// the anti-goal), a pick that resolved to nothing, a body model that is not
+// the pick's id, or a pick whose catalog entry carries no steering block.
+//
+// `bodyModel` is the request body's `model` field when the wiring has read it
+// (the live body carries the pick id verbatim — spike fact 1); undefined
+// skips that gate and lets the alias signal decide. The `models` map is keyed
+// by bare catalog id — the pick ids' form.
+export function steeringFor(
+  eventModel: ModelRef,
+  bodyModel: string | undefined,
+  picks: Partial<Record<Priority, AliasTarget>>,
+  models: Map<string, ModelEntry>,
+): Steering | null {
+  const p = aliasPriority(eventModel)
+  if (p === null) return null
+  const pick = picks[p]
+  if (pick === undefined || pick.id === null) return null
+  if (bodyModel !== undefined && bodyModel !== pick.id) return null
+  return models.get(pick.id)?.steering ?? null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// The body with the steering block's provider sub-object injected under the
+// `provider` key — or the input returned untouched when it already carries a
+// `provider` key (the plugin never clobbers routing the user or a provider
+// configured) or is not a JSON object. The injected routing object is built
+// field-by-field, never spread from the steering block, so the raw block's
+// top-level `model` field (or any unknown key) cannot reach the body; an
+// absent `quantizations` stays absent (OpenRouter reads the key's presence).
+//
+// Contract the wiring relies on: the SAME reference comes back when nothing
+// was injected, a NEW object when it was — reference inequality is the
+// "re-create the Request" signal.
+export function injectSteering(body: unknown, steering: Steering): unknown {
+  if (!isPlainObject(body) || Object.hasOwn(body, "provider")) return body
+  return {
+    ...body,
+    provider: {
+      order: steering.order,
+      ignore: steering.ignore,
+      ...(steering.quantizations === undefined ? {} : { quantizations: steering.quantizations }),
+      allow_fallbacks: steering.allow_fallbacks,
+    },
+  }
+}
+
+// normalize_provider (vendor/model_compare.py): casefold the name and strip
+// ALL non-alphanumeric characters — "Z.AI", "z-ai" and "z ai" all normalize
+// to "zai". JS toLowerCase stands in for Python's casefold (provider display
+// names are ASCII in practice; a non-ASCII residue the casefold would keep is
+// stripped by the character class either way).
+function normalizeProvider(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "")
+}
+
+// The provider part of a routing reference: the text before the first `/`
+// (`novita/fp8`, `deepinfra/fp8/flex` → `novita`/`deepinfra`), or the whole
+// string when it carries none — a served display name (`Novita`) is therefore
+// its own provider part. Applied to BOTH sides symmetrically (spike fact 3:
+// the served string is a display name, never the script's tagged-slug form).
+function providerPart(ref: string): string {
+  const slash = ref.indexOf("/")
+  return slash === -1 ? ref : ref.slice(0, slash)
+}
+
+// The served-endpoint verdict for one response: compare the response's
+// `provider` string against the steering `order` that was actually applied to
+// the request. `endpoint` is the served string verbatim (the alt+e toast's
+// text) — null only when there is nothing to record (no provider at all, or a
+// name with no provider part). `downgrade` is true ONLY when a parseable
+// provider matches no entry of a NON-EMPTY order; an absent or empty order
+// (no steering data — offline, or a model without a steering block) records
+// the endpoint with no verdict, because `!` may only assert a fallback
+// "despite the steering" when a non-empty order was actually applied.
+export function captureEndpoint(
+  provider: string | null,
+  order: string[] | null,
+): { endpoint: string | null; downgrade: boolean } {
+  if (provider === null) return { endpoint: null, downgrade: false }
+  const served = normalizeProvider(providerPart(provider))
+  if (served === "") return { endpoint: null, downgrade: false }
+  const entries = order ?? []
+  if (entries.length === 0) return { endpoint: provider, downgrade: false }
+  const matched = entries.some((entry) => normalizeProvider(providerPart(entry)) === served)
+  return { endpoint: provider, downgrade: !matched }
+}