@suluk/models 0.1.0

package/REFRESH.md

@@ -0,0 +1,42 @@
+# @suluk/models — the weekly refresh spec
+
+The catalog is a **generated, content-addressed artifact**, not a live call. This package ships the schema + selector + a small SEED catalog; the ~200-row catalog is produced by the fetcher below. Council `wf_729cde52-cc7`.
+
+## The honest split — two derivability classes (the verifier's correction)
+
+The naive "everything weekly from public data" is false. Derivability splits in two:
+
+**(A) WEEKLY-DERIVABLE from a live API — the automatable spine (build first).** Pure facts from the OpenRouter `/models` + `/endpoints` API: per-token `input`/`output`/`cached` price, `context_length`, `max_completion_tokens`, `supported_parameters` (→ `tool_calling` / `forced_tool_choice` / `parallel_tool_calls` / `structured_output` / `json_schema_strict` — **declared, not verified**), `architecture.input/output_modalities`, provider fan-out, usage rankings, region/data-policy. These refresh cleanly every week. Our **own** signal: a week-over-week snapshot diff → `priceVolatile` and the `status` deprecation delta.
+
+**(B) PERIODIC, lower-cadence, human-reviewable — the benchmark TIERS (second pass).** BFCL / τ-bench (agentic-tool-use), IFEval + LMArena (instruction-following), GPQA/AIME (reasoning), SWE-bench-Verified (coding), RULER (long-context), MMLU-Pro (knowledge), LMArena Elo (human-preference). These are **periodic publications, not APIs** — they cannot be claimed "weekly." They are mapped to coarse tiers by a committed **bucketing rules file** (which leaderboard snapshot → which tier boundary) so the tiers are auditable and reproducible. Coverage is **sparse** — most rows are `unknown` on the agentic + long-context axes; we **surface the gap, never impute**.
+
+## Honesty rules (council-unanimous)
+
+1. **Coarse tiers over scores** — `frontier|strong|mid|basic|unknown`; the raw cited number lives in `source`, never as the sortable value.
+2. **Cite per metric** — every `Cell` carries `{source, asOf}`; an unsourced cell is MISSING (fail-closed in hard filters, soft-penalty in ranks), never a confident value. A tier is an **adopted public prior at a low ceiling**, never our measured fact — we do **not** self-test.
+3. **Name contamination/saturation** — MMLU + HumanEval are demoted (MMLU-Pro gate; HumanEval secondary to SWE-bench-Verified); cross-witness a benchmark tier against LMArena (≥2 sources to agree on `frontier`).
+4. **Staleness visible** — per-cell `asOf`; a not-seen-this-week row is STALE; the catalog is pinned by `snapshotHash` so a selection is reproducible (a re-pick with no author edit is otherwise un-auditable).
+5. **Disclosed blindspots we cannot close without self-testing** — `supported_parameters` is decidable-as-DECLARED not as-true (a model can advertise tools and emit malformed calls → the CAP filter and the agentic-RELIABILITY tier are SEPARATE fields); AA latency/throughput are single-vendor + route/load-dependent (tag the provider, never a guarantee); provider quantization can drop quality with no version bump — disclosed, not solved; popularity is selection-bias (tiebreak only).
+
+## Open sub-question (deferred to a micro-panel)
+
+Key a row by **model** or by **(model, provider-endpoint)**? Governance/price/region attach to the *endpoint actually served* (structurally sounder), but that 3–5×'s the row count and the author UX. To resolve with a receipt + ceiling before hardening. The seed catalog currently keys by model with a single `provider`.
+
+## Pipeline
+
+```
+weekly:   OpenRouter /models  ──▶  normalizeOpenRouter (A) facts cells  ─┐   [BUILT: normalize.ts + fetch.ts]
+periodic: leaderboard snapshots + BUCKETING_RULES ─▶ applyBucketing (B) tier cells ─┤  [BUILT: bucketing.ts; the live overlay is TODO]
+                                                                                   ▼
+                                              catalogFrom ▶ ModelRecord rows ▶ snapshotHash ▶ ModelCatalog (committed, versioned)
+```
+
+**BUILT (no-network spine, unit-tested):** `bucketing.ts` (`BUCKETING_RULES` + `applyBucketing` — the committed,
+cited tier-boundary rules per axis, the red-line), `normalize.ts` (`normalizeOpenRouterModel`/`normalizeOpenRouter` —
+the OpenRouter `/models` → fact-cells transform; `snapshotHash`/`catalogFrom` — content-addressed catalog), and
+`fetch.ts` (`fetchOpenRouterCatalog` — the thin live wrapper). The selector (`selectModel`) and the agent seam
+(`deriveRequirements`/`resolveSkillModels`, having replaced `SulukSkillRef.model[]` + the analyzer's `DEFAULT_WINDOWS`)
+are wired against these.
+
+**TODO:** run `fetchOpenRouterCatalog` weekly (CI) to commit the ~200-row fact catalog; build the Class-B overlay that
+maps leaderboard snapshots through `applyBucketing` onto `intel.*` (human-reviewed, lower cadence); then retire the seed.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@suluk/models",
+  "version": "0.1.0",
+  "description": "A weekly, PUBLIC-DATA-ONLY catalog of OpenRouter models + a selector: a suluk skill declares NEEDS (hard filters) + a small PREFERENCE (a named profile), and selectModel picks the best CURRENT model — never a hard-coded id. Decidable OpenRouter facts as numbers; noisy benchmarks as COARSE TIERS with {source, asOf}; no cross-axis composite (blending is the selector's job). CANDIDATE tooling — NOT official OAS.",
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+"type": "git",
+"url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+"directory": "tooling/ts/packages/models"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
+},
+"devDependencies": {
+"@types/bun": "latest"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/bucketing.ts

@@ -0,0 +1,39 @@
+/**
+ * The TIER BUCKETING RULES (metrics-council red-line `wf_729cde52-cc7`) — a DOCUMENTED, COMMITTED mapping from a
+ * published leaderboard metric to a coarse tier, per INTEL axis. Without this the tiers are un-auditable and not
+ * weekly-maintainable (the minimalist red-line). The VALUE is that the mapping is EXPLICIT + CITED + reproducible —
+ * not that a boundary is exact (tune at review). `applyBucketing` is a pure function the Class-B tier pass calls.
+ *
+ * Scores are the published metric normalized to [0,1] (accuracy/pass-rate), EXCEPT human-preference which is raw
+ * LMArena Elo. A null/absent score ⇒ `unknown` (NEVER imputed to worst — that would kill new models).
+ */
+import type { Tier } from "./types";
+
+export interface AxisRule {
+  /** the public leaderboard(s) this axis is bucketed from (cited in every cell's `source`). */
+  source: string;
+  /** what the score means (so a reviewer can reproduce the bucketing). */
+  metric: string;
+  /** score >= frontier ⇒ frontier; >= strong ⇒ strong; >= mid ⇒ mid; else basic. */
+  boundaries: { frontier: number; strong: number; mid: number };
+}
+
+export const BUCKETING_RULES: Record<string, AxisRule> = {
+  agenticToolUse: { source: "bfcl-v3 + tau-bench", metric: "BFCL overall accuracy (tau-bench corroborates)", boundaries: { frontier: 0.85, strong: 0.70, mid: 0.50 } },
+  instructionFollowing: { source: "ifeval", metric: "IFEval strict prompt+instruction accuracy", boundaries: { frontier: 0.88, strong: 0.78, mid: 0.65 } },
+  reasoning: { source: "gpqa-diamond + aime", metric: "GPQA-Diamond accuracy (AIME corroborates)", boundaries: { frontier: 0.70, strong: 0.55, mid: 0.40 } },
+  coding: { source: "swe-bench-verified", metric: "SWE-bench-Verified resolved % (HumanEval secondary)", boundaries: { frontier: 0.60, strong: 0.45, mid: 0.30 } },
+  longCtxComprehension: { source: "ruler-128k", metric: "RULER avg accuracy @128k (needle corroborates)", boundaries: { frontier: 0.90, strong: 0.80, mid: 0.65 } },
+  knowledge: { source: "mmlu-pro", metric: "MMLU-Pro accuracy (saturation-flagged)", boundaries: { frontier: 0.80, strong: 0.70, mid: 0.55 } },
+  humanPreference: { source: "lmarena", metric: "LMArena overall Elo (style-confounded — cross-witness only)", boundaries: { frontier: 1350, strong: 1250, mid: 1150 } },
+};
+
+/** Bucket a raw leaderboard score into a coarse tier per the committed rule. Null/absent/unknown-axis ⇒ `unknown`. */
+export function applyBucketing(axis: string, score: number | null | undefined): Tier {
+  const rule = BUCKETING_RULES[axis];
+  if (!rule || score === null || score === undefined || Number.isNaN(score)) return "unknown";
+  if (score >= rule.boundaries.frontier) return "frontier";
+  if (score >= rule.boundaries.strong) return "strong";
+  if (score >= rule.boundaries.mid) return "mid";
+  return "basic";
+}

package/src/catalog.ts

@@ -0,0 +1,89 @@
+/**
+ * SEED catalog — a small, hand-curated set of headline models so the selector + the agent seam can be built and
+ * tested BEFORE the weekly fetcher exists (see REFRESH.md). These cells are illustrative public-knowledge values
+ * stamped `asOf`; the real catalog is a generated, content-addressed artifact from OpenRouter (facts) + periodic
+ * benchmark tiers (see REFRESH.md). Tiers are coarse and source-cited; UNKNOWN is honest, never imputed.
+ */
+import type { Cell, ModelCatalog, ModelRecord, Tier, DataRetention } from "./types";
+
+const ASOF = "2026-06-13";
+const OR = "openrouter.api";          // decidable facts (price, context, caps, modalities, ops)
+const AA = "artificialanalysis.ai";   // single-vendor speed + composite (provider/load-dependent)
+const num = (value: number | null, source = OR): Cell<number> => ({ value, source: value === null ? "" : source, asOf: ASOF });
+const flag = (value: boolean | null, source = OR): Cell<boolean> => ({ value, source: value === null ? "" : source, asOf: ASOF });
+const tier = (value: Tier | null, source: string): Cell<Tier> => ({ value, source: value === null ? "" : source, asOf: ASOF });
+const mods = (value: string[] | null): Cell<string[]> => ({ value, source: value === null ? "" : OR, asOf: ASOF });
+const str = <T extends string>(value: T | null, source: string): Cell<T> => ({ value, source: value === null ? "" : source, asOf: ASOF });
+const U = null; // UNKNOWN shorthand
+
+interface Spec {
+  id: string; provider: string; family: string; status?: ModelRecord["status"];
+  inP: number; outP: number; cachedP?: number | null;
+  win: number; out?: number | null; fidelity?: Tier | null;
+  ttft?: Tier | null; tput?: Tier | null;
+  tool?: boolean; forced?: boolean; parallel?: boolean; structured?: boolean; strict?: boolean;
+  inMod?: string[]; outMod?: string[];
+  agentic?: Tier | null; instruct?: Tier | null; reasoning?: Tier | null; coding?: Tier | null; longctx?: Tier | null; knowledge?: Tier | null; humanpref?: Tier | null;
+  retention?: DataRetention; region?: string | null; license?: string | null;
+  fanout?: number; popularity?: number | null; released?: string | null; volatile?: boolean;
+}
+const mk = (s: Spec): ModelRecord => ({
+  id: s.id, provider: s.provider, family: s.family, status: s.status ?? "active",
+  cost: { inputPerMtok: num(s.inP), outputPerMtok: num(s.outP), cachedInputPerMtok: num(s.cachedP ?? U), perRequest: flag(false) },
+  context: { maxWindow: num(s.win), maxOutput: num(s.out ?? U), longCtxFidelity: tier(s.fidelity ?? U, "ruler.public") },
+  speed: { ttft: tier(s.ttft ?? U, AA), throughput: tier(s.tput ?? U, AA) },
+  caps: {
+    toolCalling: flag(s.tool ?? false), forcedToolChoice: flag(s.forced ?? false), parallelToolCalls: flag(s.parallel ?? false),
+    structuredOutput: flag(s.structured ?? false), jsonSchemaStrict: flag(s.strict ?? false),
+    inputModalities: mods(s.inMod ?? ["text"]), outputModalities: mods(s.outMod ?? ["text"]),
+  },
+  intel: {
+    agenticToolUse: tier(s.agentic ?? U, "bfcl+tau-bench"), instructionFollowing: tier(s.instruct ?? U, "ifeval+lmarena-if"),
+    reasoning: tier(s.reasoning ?? U, "gpqa+aime"), coding: tier(s.coding ?? U, "swe-bench-verified"),
+    longCtxComprehension: tier(s.longctx ?? U, "ruler.public"), knowledge: tier(s.knowledge ?? U, "mmlu-pro"),
+    humanPreference: tier(s.humanpref ?? U, "lmarena"),
+  },
+  gov: { dataRetention: str(s.retention ?? "unknown", s.retention ? "provider.tos" : ""), region: str(s.region ?? U, "openrouter.provider"), license: str(s.license ?? U, "openrouter.license") },
+  ops: { providerFanOut: num(s.fanout ?? 1), popularityRank: num(s.popularity ?? U, "openrouter.rankings"), releaseDate: str(s.released ?? U, "provider"), priceVolatile: flag(s.volatile ?? false, "suluk.snapshot-diff") },
+});
+
+/** Illustrative seed — NOT the live catalog. Tiers reflect coarse public standing as of asOf; UNKNOWN is honest. */
+export const SEED_CATALOG: ModelCatalog = {
+  schemaVersion: "0.1.0",
+  generatedAt: ASOF,
+  snapshotHash: "sha256-seed-0001",
+  rows: [
+    mk({ id: "anthropic/claude-opus-4", provider: "anthropic", family: "claude", inP: 15, outP: 75, cachedP: 1.5, win: 200000, out: 64000, fidelity: "strong",
+      ttft: "mid", tput: "mid", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image"],
+      agentic: "frontier", instruct: "frontier", reasoning: "frontier", coding: "frontier", longctx: "strong", knowledge: "frontier", humanpref: "frontier",
+      retention: "ephemeral", region: "us", license: "proprietary", fanout: 2, popularity: 3, released: "2026-05" }),
+    mk({ id: "anthropic/claude-sonnet-4-6", provider: "anthropic", family: "claude", inP: 3, outP: 15, cachedP: 0.3, win: 200000, out: 64000, fidelity: "strong",
+      ttft: "strong", tput: "strong", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image"],
+      agentic: "frontier", instruct: "frontier", reasoning: "strong", coding: "frontier", longctx: "strong", knowledge: "strong", humanpref: "strong",
+      retention: "ephemeral", region: "us", license: "proprietary", fanout: 2, popularity: 1, released: "2026-04" }),
+    mk({ id: "google/gemini-2.5-flash", provider: "google", family: "gemini", inP: 0.3, outP: 2.5, cachedP: 0.075, win: 1000000, out: 65000, fidelity: "mid",
+      ttft: "frontier", tput: "frontier", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image", "audio"],
+      agentic: "strong", instruct: "strong", reasoning: "mid", coding: "strong", longctx: "mid", knowledge: "strong", humanpref: "strong",
+      retention: "logged", region: "us", license: "proprietary", fanout: 1, popularity: 2, released: "2026-03" }),
+    mk({ id: "google/gemini-2.5-pro", provider: "google", family: "gemini", inP: 1.25, outP: 10, cachedP: 0.31, win: 1000000, out: 65000, fidelity: "strong",
+      ttft: "strong", tput: "strong", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image", "audio", "pdf"],
+      agentic: "strong", instruct: "frontier", reasoning: "frontier", coding: "strong", longctx: "frontier", knowledge: "frontier", humanpref: "frontier",
+      retention: "logged", region: "us", license: "proprietary", fanout: 1, popularity: 4, released: "2026-03" }),
+    mk({ id: "openai/gpt-5", provider: "openai", family: "gpt", inP: 10, outP: 30, cachedP: 1.25, win: 400000, out: 128000, fidelity: "strong",
+      ttft: "mid", tput: "mid", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image"],
+      agentic: "frontier", instruct: "frontier", reasoning: "frontier", coding: "frontier", longctx: "strong", knowledge: "frontier", humanpref: "frontier",
+      retention: "logged", region: "us", license: "proprietary", fanout: 2, popularity: 5, released: "2026-02" }),
+    mk({ id: "openai/gpt-4o-mini", provider: "openai", family: "gpt", inP: 0.15, outP: 0.6, cachedP: 0.075, win: 128000, out: 16000,
+      ttft: "frontier", tput: "frontier", tool: true, forced: true, parallel: true, structured: true, strict: true, inMod: ["text", "image"],
+      agentic: "mid", instruct: "strong", reasoning: "mid", coding: "mid", knowledge: "mid", humanpref: "mid",
+      retention: "logged", region: "us", license: "proprietary", fanout: 2, popularity: 6, released: "2025-07" }),
+    mk({ id: "deepseek/deepseek-v3", provider: "deepseek", family: "deepseek", inP: 0.27, outP: 1.1, cachedP: 0.07, win: 128000, out: 8000,
+      ttft: "mid", tput: "strong", tool: true, structured: true, inMod: ["text"],
+      agentic: "mid", instruct: "strong", reasoning: "strong", coding: "strong", knowledge: "strong", humanpref: "strong",
+      retention: "trains", region: "cn", license: "mit", fanout: 3, popularity: 7, released: "2025-12", volatile: true }),
+    mk({ id: "meta-llama/llama-4-maverick", provider: "meta", family: "llama", inP: 0.2, outP: 0.6, win: 1000000, out: 16000, fidelity: U,
+      ttft: "strong", tput: "strong", tool: true, structured: true, inMod: ["text", "image"],
+      agentic: U /* thin public agentic data */, instruct: "mid", reasoning: "mid", coding: "mid", knowledge: "strong", humanpref: "mid",
+      retention: "zero", region: "us", license: "llama-4-community", fanout: 5, popularity: 8, released: "2025-04" }),
+  ],
+};

package/src/fetch.ts

@@ -0,0 +1,20 @@
+/**
+ * The LIVE weekly fetcher (Class A) — a THIN wrapper over the pure `normalizeOpenRouter` transform. This is the only
+ * part that needs network; it is deliberately tiny so the transform stays unit-tested. The Class-B benchmark TIER
+ * pass (BFCL/IFEval/SWE-bench/RULER/MMLU-Pro/LMArena → `applyBucketing`) is a separate, lower-cadence, human-reviewed
+ * step that overlays `intel.*` tiers onto these rows — see REFRESH.md. `asOf` must be passed in (scripts stamp time;
+ * the package never calls `new Date()` implicitly so a run is reproducible).
+ */
+import type { ModelCatalog } from "./types";
+import { type ORModel, normalizeOpenRouter, catalogFrom } from "./normalize";
+
+/** Fetch OpenRouter `/models` and normalize to the fact-cell catalog. NETWORK — run from a weekly script/CI, not tests. */
+export async function fetchOpenRouterCatalog(asOf: string, opts: { baseUrl?: string; fetchImpl?: typeof fetch } = {}): Promise<ModelCatalog> {
+  const base = opts.baseUrl ?? "https://openrouter.ai/api/v1";
+  const f = opts.fetchImpl ?? fetch;
+  const res = await f(`${base}/models`);
+  if (!res.ok) throw new Error(`@suluk/models: OpenRouter /models returned ${res.status}`);
+  const body = (await res.json()) as { data?: ORModel[] };
+  if (!Array.isArray(body.data)) throw new Error("@suluk/models: unexpected OpenRouter /models payload (no data[])");
+  return catalogFrom(normalizeOpenRouter(body.data, asOf), asOf);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @suluk/models — a weekly, PUBLIC-DATA-ONLY OpenRouter model catalog + a selector. A suluk skill declares NEEDS
+ * (hard filters) + a small PREFERENCE (a named profile), and selectModel picks the best CURRENT model — never a
+ * hard-coded id. Decidable OpenRouter facts are numbers; noisy benchmarks are coarse TIERS with {source, asOf};
+ * UNKNOWN is honest (never imputed to worst); no cross-axis composite is stored (blending is the selector's job).
+ * Council wf_729cde52-cc7. CANDIDATE tooling — NOT official OAS. The live weekly fetcher is specified in REFRESH.md
+ * (this package ships the schema + selector + a SEED catalog; the 200-row generated catalog is the data-eng spine).
+ */
+export type {
+  Tier, Cell, DataRetention, ModelRecord, ModelCatalog, HardFilters, Profile, Preferences, RankedModel, SelectResult,
+} from "./types";
+export { SEED_CATALOG } from "./catalog";
+export { PROFILES, type ResolvedProfile } from "./profiles";
+export { selectModel, deriveRequirements } from "./select";
+// the weekly fetcher spine: documented tier bucketing rules (red-line) + the pure OpenRouter facts transform + a thin live fetch.
+export { BUCKETING_RULES, applyBucketing, type AxisRule } from "./bucketing";
+export { normalizeOpenRouter, normalizeOpenRouterModel, catalogFrom, snapshotHash, type ORModel } from "./normalize";
+export { fetchOpenRouterCatalog } from "./fetch";

package/src/normalize.ts

@@ -0,0 +1,79 @@
+/**
+ * normalizeOpenRouter — the WEEKLY-DERIVABLE spine (Class A in REFRESH.md): the OpenRouter `/models` API → the
+ * DECIDABLE fact cells of a ModelRecord (cost, context, capabilities-as-DECLARED, modalities, recency). PURE +
+ * unit-tested; the live `fetch` is a thin wrapper (fetch.ts). The noisy benchmark TIER cells (intel.*) are left
+ * `unknown` here — they come from the periodic Class-B pass via `applyBucketing`, not this API. We do NOT impute.
+ */
+import { createHash } from "node:crypto";
+import type { Cell, DataRetention, ModelCatalog, ModelRecord } from "./types";
+
+/** The subset of an OpenRouter `/models` row we rely on (all public facts). */
+export interface ORModel {
+  id: string;
+  name?: string;
+  created?: number; // unix seconds
+  context_length?: number;
+  pricing?: { prompt?: string; completion?: string; request?: string; input_cache_read?: string };
+  top_provider?: { max_completion_tokens?: number | null };
+  architecture?: { input_modalities?: string[]; output_modalities?: string[] };
+  supported_parameters?: string[];
+}
+
+const c = <T,>(value: T | null, source: string, asOf: string): Cell<T> => ({ value, source: value === null ? "" : source, asOf });
+const perMtok = (s?: string): number | null => (s === undefined ? null : Math.round(parseFloat(s) * 1_000_000 * 1000) / 1000);
+const has = (params: string[] | undefined, k: string) => !!params?.includes(k);
+const OR = "openrouter.api";
+
+/** One OpenRouter model → its decidable fact cells (intel/gov tiers stay UNKNOWN; filled by the Class-B pass). */
+export function normalizeOpenRouterModel(m: ORModel, asOf: string): ModelRecord {
+  const provider = m.id.split("/")[0] ?? "unknown";
+  const family = (m.id.split("/")[1] ?? "").replace(/[:@-].*$/, "") || provider;
+  const sp = m.supported_parameters;
+  const U = <T,>(): Cell<T> => ({ value: null, source: "", asOf });
+  return {
+    id: m.id, provider, family, status: "active",
+    cost: {
+      inputPerMtok: c(perMtok(m.pricing?.prompt), OR, asOf),
+      outputPerMtok: c(perMtok(m.pricing?.completion), OR, asOf),
+      cachedInputPerMtok: c(perMtok(m.pricing?.input_cache_read), OR, asOf),
+      perRequest: c(m.pricing?.request !== undefined ? parseFloat(m.pricing.request) > 0 : null, OR, asOf),
+    },
+    context: {
+      maxWindow: c(m.context_length ?? null, OR, asOf),
+      maxOutput: c(m.top_provider?.max_completion_tokens ?? null, OR, asOf),
+      longCtxFidelity: U(), // RULER — not in this API; Class-B pass
+    },
+    speed: { ttft: U(), throughput: U() }, // Artificial Analysis — not in this API
+    caps: {
+      toolCalling: c(sp ? has(sp, "tools") : null, OR, asOf),
+      forcedToolChoice: c(sp ? has(sp, "tool_choice") : null, OR, asOf),
+      parallelToolCalls: c(sp ? has(sp, "parallel_tool_calls") : null, OR, asOf),
+      structuredOutput: c(sp ? has(sp, "structured_outputs") || has(sp, "response_format") : null, OR, asOf),
+      jsonSchemaStrict: c(sp ? has(sp, "structured_outputs") : null, OR, asOf),
+      inputModalities: c(m.architecture?.input_modalities ?? null, OR, asOf),
+      outputModalities: c(m.architecture?.output_modalities ?? null, OR, asOf),
+    },
+    intel: { agenticToolUse: U(), instructionFollowing: U(), reasoning: U(), coding: U(), longCtxComprehension: U(), knowledge: U(), humanPreference: U() },
+    gov: { dataRetention: U<DataRetention>(), region: U(), license: U() },
+    ops: {
+      providerFanOut: c(1, OR, asOf),
+      popularityRank: U(),
+      releaseDate: c(m.created ? new Date(m.created * 1000).toISOString().slice(0, 10) : null, "openrouter.created", asOf),
+      priceVolatile: c(false, "suluk.snapshot-diff", asOf),
+    },
+  };
+}
+
+export function normalizeOpenRouter(models: ORModel[], asOf: string): ModelRecord[] {
+  return models.map((m) => normalizeOpenRouterModel(m, asOf)).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** A content-addressed hash over the rows' load-bearing FACT cells (reproducible pin; ties C027 contentHash). */
+export function snapshotHash(rows: ModelRecord[]): string {
+  const facts = rows.map((r) => [r.id, r.cost.inputPerMtok.value, r.cost.outputPerMtok.value, r.context.maxWindow.value, r.caps.toolCalling.value]);
+  return "sha256-" + createHash("sha256").update(JSON.stringify(facts), "utf8").digest("hex").slice(0, 16);
+}
+
+export function catalogFrom(rows: ModelRecord[], asOf: string): ModelCatalog {
+  return { schemaVersion: "0.1.0", generatedAt: asOf, snapshotHash: snapshotHash(rows), rows };
+}

package/src/profiles.ts

@@ -0,0 +1,23 @@
+/**
+ * The 6 named PROFILES — the 90%-case author UX (a profile = preset preference weights + AUTO-WIRED implied hard
+ * filters so the author can't foot-gun). Same SHAPE as today's skill.model[] (a preference, not an id), so the
+ * migration is mechanical. The escape hatch (≤4 small int weights + taskShape) is for power users; the catalog
+ * tracks ~30 fields but the author touches ~4.
+ */
+import type { HardFilters, Preferences, Profile } from "./types";
+
+export interface ResolvedProfile {
+  prefer: { intelligence: 0 | 1 | 2 | 3; cost: 0 | 1 | 2 | 3; speed: 0 | 1 | 2 | 3; context: 0 | 1 | 2 | 3 };
+  taskShape?: Preferences["taskShape"];
+  /** filters the profile auto-wires (an author choosing "tool-reliable" implicitly requires tool-calling). */
+  impliedFilters: Partial<HardFilters>;
+}
+
+export const PROFILES: Record<Profile, ResolvedProfile> = {
+  "tool-reliable": { prefer: { intelligence: 3, cost: 1, speed: 1, context: 1 }, taskShape: "agentic", impliedFilters: { needsTools: true } },
+  "cheap-fast": { prefer: { intelligence: 1, cost: 3, speed: 3, context: 0 }, impliedFilters: {} },
+  "balanced": { prefer: { intelligence: 2, cost: 2, speed: 2, context: 1 }, impliedFilters: {} },
+  "max-reasoning": { prefer: { intelligence: 3, cost: 0, speed: 0, context: 1 }, taskShape: "reasoning", impliedFilters: {} },
+  "long-context": { prefer: { intelligence: 2, cost: 1, speed: 0, context: 3 }, impliedFilters: { fidelityFloor: "mid" } },
+  "vision": { prefer: { intelligence: 2, cost: 1, speed: 1, context: 1 }, impliedFilters: { inputModalities: ["image"] } },
+};

package/src/select.ts

@@ -0,0 +1,136 @@
+/**
+ * selectModel — requirements FILTER first (capabilities + context + governance + the C028 allowlist MEET; can empty
+ * the set ⇒ FAIL LOUD naming the unsatisfiable filter), then preferences RANK the survivors over coarse tiers.
+ * A preference can NEVER widen a hard filter (the operator/C028 set is terminal). UNKNOWN is a soft penalty, never
+ * worst. Output carries a "why this model" explainer — adoption dies if selection is a black box.
+ */
+import type { Cell, HardFilters, ModelCatalog, ModelRecord, Preferences, RankedModel, SelectResult, Tier } from "./types";
+import { PROFILES } from "./profiles";
+
+const TIER_SCORE: Record<Tier, number> = { frontier: 4, strong: 3, mid: 2, basic: 1, unknown: 1.5 };
+const TIER_RANK: Record<Exclude<Tier, "unknown">, number> = { frontier: 4, strong: 3, mid: 2, basic: 1 };
+const scoreTier = (c: Cell<Tier>): number => TIER_SCORE[c.value ?? "unknown"];
+const isTrue = (c: Cell<boolean>): boolean => c.value === true; // fail-closed: unknown/false does not satisfy
+const supersetOf = (have: Cell<string[]>, need: string[]): boolean => !!have.value && need.every((m) => have.value!.includes(m));
+
+/** Resolve a profile + escape-hatch into concrete weights + implied filters + taskShape. */
+function resolvePrefs(prefs: Preferences): { w: { intelligence: number; cost: number; speed: number; context: number }; taskShape?: Preferences["taskShape"]; implied: Partial<HardFilters> } {
+  const base = prefs.profile ? PROFILES[prefs.profile] : { prefer: { intelligence: 2, cost: 2, speed: 1, context: 1 }, impliedFilters: {}, taskShape: undefined as Preferences["taskShape"] };
+  const w = { ...base.prefer, ...(prefs.prefer ?? {}) };
+  return { w, taskShape: prefs.taskShape ?? base.taskShape, implied: base.impliedFilters };
+}
+
+/** Merge author requirements with a profile's implied filters (author can ADD but the operator policy is terminal). */
+function mergeFilters(reqs: HardFilters, implied: Partial<HardFilters>): HardFilters {
+  return { ...implied, ...reqs, policy: reqs.policy ?? implied.policy };
+}
+
+interface FilterTrace { passed: string[]; failed: string | null }
+function checkFilters(m: ModelRecord, f: HardFilters): FilterTrace {
+  const passed: string[] = [];
+  const need = (ok: boolean, label: string): string | null => { if (ok) { passed.push(label); return null; } return label; };
+  // capabilities (declared-not-verified; fail-closed on unknown)
+  const checks: Array<[boolean | undefined, () => boolean, string]> = [
+    [f.needsTools, () => isTrue(m.caps.toolCalling), "tool-calling"],
+    [f.needsForcedToolChoice, () => isTrue(m.caps.forcedToolChoice), "forced-tool-choice"],
+    [f.needsStructured, () => isTrue(m.caps.structuredOutput), "structured-output"],
+    [f.strictSchema, () => isTrue(m.caps.jsonSchemaStrict), "strict-schema"],
+  ];
+  for (const [req, test, label] of checks) if (req) { const fail = need(test(), label); if (fail) return { passed, failed: fail }; }
+  if (f.inputModalities?.length) { const fail = need(supersetOf(m.caps.inputModalities, f.inputModalities), `input-modalities[${f.inputModalities.join(",")}]`); if (fail) return { passed, failed: fail }; }
+  if (f.outputModalities?.length) { const fail = need(supersetOf(m.caps.outputModalities, f.outputModalities), `output-modalities[${f.outputModalities.join(",")}]`); if (fail) return { passed, failed: fail }; }
+  // context — minWindow fail-closed on unknown (don't claim a fit we can't prove)
+  if (f.minWindowRequired !== undefined) { const fail = need(m.context.maxWindow.value !== null && m.context.maxWindow.value >= f.minWindowRequired, `min-window>=${f.minWindowRequired}`); if (fail) return { passed, failed: fail }; }
+  if (f.minOutputTokens !== undefined && m.context.maxOutput.value !== null) { const fail = need(m.context.maxOutput.value >= f.minOutputTokens, `min-output>=${f.minOutputTokens}`); if (fail) return { passed, failed: fail }; }
+  if (f.fidelityFloor && m.context.longCtxFidelity.value && m.context.longCtxFidelity.value !== "unknown") { const fail = need(TIER_RANK[m.context.longCtxFidelity.value] >= TIER_RANK[f.fidelityFloor as Exclude<Tier, "unknown">], `fidelity>=${f.fidelityFloor}`); if (fail) return { passed, failed: fail }; }
+  // price caps (price is always known from OpenRouter)
+  if (f.maxInputPrice !== undefined) { const fail = need(m.cost.inputPerMtok.value !== null && m.cost.inputPerMtok.value <= f.maxInputPrice, `input-price<=${f.maxInputPrice}`); if (fail) return { passed, failed: fail }; }
+  if (f.maxOutputPrice !== undefined) { const fail = need(m.cost.outputPerMtok.value !== null && m.cost.outputPerMtok.value <= f.maxOutputPrice, `output-price<=${f.maxOutputPrice}`); if (fail) return { passed, failed: fail }; }
+  // governance — FAIL-CLOSED (unknown excluded), C028
+  const p = f.policy;
+  if (p?.allowedRegions?.length) { const fail = need(!!m.gov.region.value && p.allowedRegions.includes(m.gov.region.value), "region"); if (fail) return { passed, failed: fail }; }
+  if (p?.allowedLicenses?.length) { const fail = need(!!m.gov.license.value && p.allowedLicenses.includes(m.gov.license.value), "license"); if (fail) return { passed, failed: fail }; }
+  if (p?.allowedRetention?.length) { const fail = need(m.gov.dataRetention.value !== null && p.allowedRetention.includes(m.gov.dataRetention.value), "data-retention"); if (fail) return { passed, failed: fail }; }
+  // the TERMINAL allowlist MEET (a model outside a non-empty allowlist is excluded on ANY grounds)
+  if (p?.modelAllowlist?.length) { const fail = need(p.modelAllowlist.includes(m.id), "policy-allowlist"); if (fail) return { passed, failed: fail }; }
+  // liveness
+  { const fail = need(m.status === "active", "status-active"); if (fail) return { passed, failed: fail }; }
+  return { passed, failed: null };
+}
+
+/** The intelligence sub-tier the preference points at (taskShape routes the single knob; default = agentic for agents). */
+function intelCell(m: ModelRecord, taskShape?: Preferences["taskShape"]): Cell<Tier> {
+  if (taskShape === "coding") return m.intel.coding;
+  if (taskShape === "reasoning") return m.intel.reasoning;
+  if (taskShape === "agentic") return m.intel.agenticToolUse;
+  // default: prefer the agentic tier, fall back to instruction-following then reasoning
+  return m.intel.agenticToolUse.value !== null ? m.intel.agenticToolUse : m.intel.instructionFollowing.value !== null ? m.intel.instructionFollowing : m.intel.reasoning;
+}
+
+const blendedPrice = (m: ModelRecord): number => (m.cost.inputPerMtok.value ?? 0) * 0.75 + (m.cost.outputPerMtok.value ?? 0) * 0.25;
+/** Normalize a raw numeric across the candidate pool into [1,4]; `higherBetter=false` inverts (cheaper→higher). */
+function norm(values: number[], v: number, higherBetter: boolean): number {
+  const min = Math.min(...values), max = Math.max(...values);
+  if (max === min) return 2.5;
+  const t = (v - min) / (max - min);
+  return 1 + 3 * (higherBetter ? t : 1 - t);
+}
+
+export function selectModel(reqs: HardFilters, prefs: Preferences, catalog: ModelCatalog): SelectResult {
+  const { w, taskShape, implied } = resolvePrefs(prefs);
+  const filters = mergeFilters(reqs, implied);
+
+  const survivors: { m: ModelRecord; passed: string[] }[] = [];
+  const excludedBy = new Map<string, number>();
+  for (const m of catalog.rows) {
+    const t = checkFilters(m, filters);
+    if (t.failed) excludedBy.set(t.failed, (excludedBy.get(t.failed) ?? 0) + 1);
+    else survivors.push({ m, passed: t.passed });
+  }
+
+  if (survivors.length === 0) {
+    const unsatisfiable = [...excludedBy.entries()].sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} (excluded ${n})`);
+    return { ranked: [], candidateCount: 0, unsatisfiable, coverageGaps: [] };
+  }
+
+  const prices = survivors.map((s) => blendedPrice(s.m));
+  const headrooms = survivors.map((s) => (s.m.context.maxWindow.value ?? 0) - (filters.minWindowRequired ?? 0));
+
+  const ranked: RankedModel[] = survivors.map((s, i) => {
+    const intel = intelCell(s.m, taskShape);
+    const g = {
+      intelligence: scoreTier(intel),
+      cost: norm(prices, prices[i], false),
+      speed: scoreTier(s.m.speed.ttft),
+      context: norm(headrooms, headrooms[i], true),
+    };
+    const score = w.intelligence * g.intelligence + w.cost * g.cost + w.speed * g.speed + w.context * g.context;
+    const tierByAxis: RankedModel["why"]["tierByAxis"] = {
+      intelligence: { tier: intel.value ?? "unknown", source: intel.source, asOf: intel.asOf },
+      latency: { tier: s.m.speed.ttft.value ?? "unknown", source: s.m.speed.ttft.source, asOf: s.m.speed.ttft.asOf },
+      cost: { tier: `${blendedPrice(s.m).toFixed(2)} $/Mtok blended`, source: s.m.cost.inputPerMtok.source, asOf: s.m.cost.inputPerMtok.asOf },
+    };
+    const decidingPreference = (["intelligence", "cost", "speed", "context"] as Array<keyof typeof w>).sort((a, b) => w[b] - w[a])[0];
+    return { id: s.m.id, provider: s.m.provider, score, why: { passedFilters: s.passed, decidingPreference: `${decidingPreference} (weight ${w[decidingPreference]})`, tierByAxis } };
+  }).sort((a, b) => b.score - a.score);
+
+  // coverage gaps on the winner — soft axes with no data (honesty surface)
+  const winner = survivors.find((s) => s.m.id === ranked[0].id)!.m;
+  const coverageGaps: string[] = [];
+  if (intelCell(winner, taskShape).value === null) coverageGaps.push("intelligence (no public tier for this taskShape)");
+  if (winner.speed.ttft.value === null) coverageGaps.push("latency");
+  if (winner.context.longCtxFidelity.value === null && (filters.minWindowRequired ?? 0) > 200000) coverageGaps.push("long-context-fidelity (large window, unverified)");
+
+  return { ranked, candidateCount: survivors.length, coverageGaps };
+}
+
+/** Derive HardFilters from an agent/skill's declared needs + the analyzer's load (the C027 seam). */
+export function deriveRequirements(input: { minWindowRequired?: number; hasRoutes?: boolean; needsStructured?: boolean; inputModalities?: string[]; policy?: HardFilters["policy"] }): HardFilters {
+  return {
+    ...(input.hasRoutes ? { needsTools: true } : {}),
+    ...(input.minWindowRequired !== undefined ? { minWindowRequired: input.minWindowRequired } : {}),
+    ...(input.needsStructured ? { needsStructured: true } : {}),
+    ...(input.inputModalities?.length ? { inputModalities: input.inputModalities } : {}),
+    ...(input.policy ? { policy: input.policy } : {}),
+  };
+}

package/src/types.ts

@@ -0,0 +1,117 @@
+/**
+ * @suluk/models — the catalog schema (council wf_729cde52-cc7). A row is one model+provider endpoint. Decidable
+ * OpenRouter facts are NUMBERS/BOOLS; noisy third-party benchmarks are COARSE TIERS (frontier/strong/mid/basic/
+ * unknown) — never a 2-decimal score (that launders noisy/contaminated public data as precision). Every cell carries
+ * {source, asOf}; an unsourced cell is MISSING, never a confident value, and a missing tier is NEVER imputed to
+ * worst (that would kill new models). The catalog stores NO cross-axis composite — blending is the selector's job
+ * at query time under explicit operator weights (storing a blend launders preference as fact).
+ */
+
+export type Tier = "frontier" | "strong" | "mid" | "basic" | "unknown";
+
+/** One catalog value with provenance. `value: null` ⇒ UNKNOWN (and `source` is ""); never imputed. */
+export interface Cell<T> { value: T | null; source: string; asOf: string }
+
+export type DataRetention = "zero" | "ephemeral" | "logged" | "trains" | "unknown";
+
+export interface ModelRecord {
+  /** the OpenRouter id the selector compiles against (stable wire id). */
+  id: string;
+  provider: string;
+  family: string;
+  status: "active" | "deprecated" | "sunset" | "preview";
+  cost: {
+    inputPerMtok: Cell<number>;
+    outputPerMtok: Cell<number>;
+    cachedInputPerMtok: Cell<number>;
+    perRequest: Cell<boolean>;
+  };
+  context: {
+    maxWindow: Cell<number>;
+    maxOutput: Cell<number>;
+    /** RULER/needle — does the big window actually hold quality? sparse public data ⇒ mostly unknown; NEVER inferred from size. */
+    longCtxFidelity: Cell<Tier>;
+  };
+  /** Artificial-Analysis single-vendor, provider/route/load-dependent — their measurement, not a guarantee. */
+  speed: { ttft: Cell<Tier>; throughput: Cell<Tier> };
+  /** capabilities are DECLARED-not-verified (provider self-report; we do not self-test). */
+  caps: {
+    toolCalling: Cell<boolean>;
+    forcedToolChoice: Cell<boolean>;
+    parallelToolCalls: Cell<boolean>;
+    structuredOutput: Cell<boolean>;
+    jsonSchemaStrict: Cell<boolean>;
+    inputModalities: Cell<string[]>;
+    outputModalities: Cell<string[]>;
+  };
+  /** "intelligence" split into 6 orthogonal-ish, source-separated dimensions (ranked by relevance to tool-using agents). */
+  intel: {
+    agenticToolUse: Cell<Tier>;       // BFCL + tau-bench — rank 1 for suluk agents; thinnest coverage
+    instructionFollowing: Cell<Tier>; // IFEval
+    reasoning: Cell<Tier>;            // GPQA-Diamond + AIME
+    coding: Cell<Tier>;               // SWE-bench-Verified (HumanEval secondary)
+    longCtxComprehension: Cell<Tier>; // RULER (same datum as context.longCtxFidelity)
+    knowledge: Cell<Tier>;            // MMLU-Pro (saturation-flagged)
+    humanPreference: Cell<Tier>;      // LMArena — a SEPARATE cross-witness axis, never summed into a capability tier
+  };
+  gov: { dataRetention: Cell<DataRetention>; region: Cell<string>; license: Cell<string> };
+  ops: { providerFanOut: Cell<number>; popularityRank: Cell<number>; releaseDate: Cell<string>; priceVolatile: Cell<boolean> };
+}
+
+export interface ModelCatalog {
+  schemaVersion: string;
+  generatedAt: string;
+  /** content-addressed so a selection is reproducible week-over-week (ties C027 contentHash). */
+  snapshotHash: string;
+  rows: ModelRecord[];
+}
+
+/** Hard requirements — these FILTER (can empty the set ⇒ fail-loud), never rank. */
+export interface HardFilters {
+  needsTools?: boolean;
+  needsForcedToolChoice?: boolean;
+  needsStructured?: boolean;
+  strictSchema?: boolean;
+  inputModalities?: string[];
+  outputModalities?: string[];
+  /** the analyzer's per-agent minWindowRequired (context.ts) becomes the hard min-context gate. */
+  minWindowRequired?: number;
+  minOutputTokens?: number;
+  fidelityFloor?: Tier;
+  maxInputPrice?: number;
+  maxOutputPrice?: number;
+  /** C028 governance/allowlist — the TERMINAL, non-overridable MEET (a preference can NEVER widen these). */
+  policy?: { modelAllowlist?: string[]; allowedRegions?: string[]; allowedLicenses?: string[]; allowedRetention?: DataRetention[] };
+}
+
+export type Profile = "tool-reliable" | "cheap-fast" | "balanced" | "max-reasoning" | "long-context" | "vision";
+
+/** Preference — RANKS the survivors. A named profile is the 90% case; the escape hatch is ≤4 small int weights. */
+export interface Preferences {
+  profile?: Profile;
+  prefer?: { intelligence?: 0 | 1 | 2 | 3; cost?: 0 | 1 | 2 | 3; speed?: 0 | 1 | 2 | 3; context?: 0 | 1 | 2 | 3 };
+  /** routes the single "intelligence" knob to the ONE relevant INTEL sub-tier. */
+  taskShape?: "agentic" | "coding" | "reasoning";
+}
+
+export interface RankedModel {
+  id: string;
+  provider: string;
+  score: number;
+  why: {
+    passedFilters: string[];
+    decidingPreference: string;
+    tierByAxis: Record<string, { tier: Tier | string; source: string; asOf: string }>;
+  };
+}
+
+export interface SelectResult {
+  /** ranked best-first; empty when no model satisfies the hard filters. */
+  ranked: RankedModel[];
+  /** the count after hard filtering. */
+  candidateCount: number;
+  /** present when the requirements emptied the set — names the unsatisfiable filter(s). */
+  unsatisfiable?: string[];
+  /** UNKNOWN-coverage warning: soft axes with no data on the winner (honesty surface). */
+  coverageGaps: string[];
+}

package/test/normalize.test.ts

@@ -0,0 +1,51 @@
+import { test, expect, describe } from "bun:test";
+import { applyBucketing, normalizeOpenRouterModel, normalizeOpenRouter, catalogFrom, snapshotHash, type ORModel } from "../src/index";
+
+describe("@suluk/models — tier bucketing rules (the red-line)", () => {
+  test("scores bucket per the committed boundaries; null / unknown-axis ⇒ unknown", () => {
+    expect(applyBucketing("agenticToolUse", 0.9)).toBe("frontier");
+    expect(applyBucketing("agenticToolUse", 0.72)).toBe("strong");
+    expect(applyBucketing("agenticToolUse", 0.55)).toBe("mid");
+    expect(applyBucketing("agenticToolUse", 0.2)).toBe("basic");
+    expect(applyBucketing("agenticToolUse", null)).toBe("unknown");
+    expect(applyBucketing("not-an-axis", 0.9)).toBe("unknown");
+    expect(applyBucketing("humanPreference", 1400)).toBe("frontier"); // Elo scale, not [0,1]
+  });
+});
+
+describe("@suluk/models — normalizeOpenRouter (the weekly facts spine)", () => {
+  const m: ORModel = {
+    id: "anthropic/claude-opus-4", created: 1746057600, context_length: 200000,
+    pricing: { prompt: "0.000015", completion: "0.000075", input_cache_read: "0.0000015" },
+    top_provider: { max_completion_tokens: 64000 },
+    architecture: { input_modalities: ["text", "image"], output_modalities: ["text"] },
+    supported_parameters: ["tools", "tool_choice", "structured_outputs", "response_format"],
+  };
+  const rec = normalizeOpenRouterModel(m, "2026-06-13");
+
+  test("prices convert per-token → per-Mtok; context + modalities + caps from supported_parameters", () => {
+    expect(rec.cost.inputPerMtok.value).toBe(15);
+    expect(rec.cost.outputPerMtok.value).toBe(75);
+    expect(rec.cost.cachedInputPerMtok.value).toBe(1.5);
+    expect(rec.context.maxWindow.value).toBe(200000);
+    expect(rec.context.maxOutput.value).toBe(64000);
+    expect(rec.caps.toolCalling.value).toBe(true);
+    expect(rec.caps.structuredOutput.value).toBe(true);
+    expect(rec.caps.inputModalities.value).toEqual(["text", "image"]);
+    expect(rec.provider).toBe("anthropic");
+    expect(rec.cost.inputPerMtok.source).toBe("openrouter.api");
+  });
+
+  test("benchmark TIER cells are UNKNOWN here (filled by the Class-B pass), never imputed", () => {
+    expect(rec.intel.agenticToolUse.value).toBeNull();
+    expect(rec.intel.reasoning.value).toBeNull();
+    expect(rec.context.longCtxFidelity.value).toBeNull();
+    expect(rec.speed.ttft.value).toBeNull();
+  });
+
+  test("catalogFrom is content-addressed + deterministic", () => {
+    const rows = normalizeOpenRouter([m], "2026-06-13");
+    expect(catalogFrom(rows, "2026-06-13").snapshotHash).toBe(catalogFrom(rows, "2026-06-13").snapshotHash);
+    expect(snapshotHash(rows)).toStartWith("sha256-");
+  });
+});

package/test/select.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe } from "bun:test";
+import { selectModel, deriveRequirements, SEED_CATALOG } from "../src/index";
+
+describe("@suluk/models selectModel — filter then rank", () => {
+  test("tool-reliable profile requires tool-calling and ranks agentic-tool-use highest", () => {
+    const r = selectModel({}, { profile: "tool-reliable" }, SEED_CATALOG);
+    expect(r.ranked.length).toBeGreaterThan(0);
+    const top = r.ranked[0];
+    expect(top.why.passedFilters).toContain("tool-calling");
+    expect(["frontier", "strong"]).toContain(top.why.tierByAxis.intelligence.tier);
+    expect(top.why.decidingPreference).toContain("intelligence");
+  });
+
+  test("cheap-fast picks a cheap, fast model (never the premium ones)", () => {
+    const r = selectModel({}, { profile: "cheap-fast" }, SEED_CATALOG);
+    expect(["openai/gpt-4o-mini", "google/gemini-2.5-flash", "deepseek/deepseek-v3", "meta-llama/llama-4-maverick"]).toContain(r.ranked[0].id);
+    expect(["anthropic/claude-opus-4", "openai/gpt-5"]).not.toContain(r.ranked[0].id);
+  });
+
+  test("the analyzer's minWindowRequired is a HARD min-context gate (fail-closed)", () => {
+    const r = selectModel({ minWindowRequired: 500000 }, { profile: "balanced" }, SEED_CATALOG);
+    const ids = r.ranked.map((x) => x.id).sort();
+    expect(ids).toEqual(["google/gemini-2.5-flash", "google/gemini-2.5-pro", "meta-llama/llama-4-maverick"]);
+  });
+
+  test("C028 modelAllowlist is the TERMINAL MEET — a model outside it is excluded on any grounds", () => {
+    const r = selectModel({ policy: { modelAllowlist: ["google/gemini-2.5-flash"] } }, { profile: "max-reasoning" }, SEED_CATALOG);
+    expect(r.candidateCount).toBe(1);
+    expect(r.ranked[0].id).toBe("google/gemini-2.5-flash"); // even though max-reasoning would prefer a frontier reasoner
+  });
+
+  test("governance filters FAIL-CLOSED (unknown/disallowed retention excluded)", () => {
+    const r = selectModel({ policy: { allowedRetention: ["zero", "ephemeral"] } }, { profile: "balanced" }, SEED_CATALOG);
+    const ids = r.ranked.map((x) => x.id).sort();
+    expect(ids).toEqual(["anthropic/claude-opus-4", "anthropic/claude-sonnet-4-6", "meta-llama/llama-4-maverick"]);
+  });
+
+  test("vision profile requires image input (text-only models excluded)", () => {
+    const r = selectModel({}, { profile: "vision" }, SEED_CATALOG);
+    expect(r.ranked.map((x) => x.id)).not.toContain("deepseek/deepseek-v3");
+  });
+
+  test("FAIL LOUD when requirements empty the set — names the unsatisfiable filter", () => {
+    const r = selectModel({ minWindowRequired: 2_000_000 }, { profile: "balanced" }, SEED_CATALOG);
+    expect(r.ranked).toEqual([]);
+    expect(r.unsatisfiable?.some((u) => u.includes("min-window"))).toBe(true);
+  });
+
+  test("UNKNOWN is surfaced as a coverage gap, never imputed to worst", () => {
+    // isolate llama (agentic tool-use = unknown) via the allowlist
+    const r = selectModel({ policy: { modelAllowlist: ["meta-llama/llama-4-maverick"] } }, { profile: "tool-reliable" }, SEED_CATALOG);
+    expect(r.ranked[0].id).toBe("meta-llama/llama-4-maverick"); // not excluded for unknown agentic
+    expect(r.coverageGaps.some((g) => g.startsWith("intelligence"))).toBe(true);
+  });
+
+  test("every ranked result carries a 'why this model' explainer", () => {
+    const r = selectModel({}, { profile: "balanced" }, SEED_CATALOG);
+    const why = r.ranked[0].why;
+    expect(Array.isArray(why.passedFilters)).toBe(true);
+    expect(why.decidingPreference).toBeTruthy();
+    expect(why.tierByAxis.cost.source).toBe("openrouter.api");
+  });
+
+  test("deriveRequirements maps an agent's structure to hard filters (the C027 seam)", () => {
+    expect(deriveRequirements({ hasRoutes: true, minWindowRequired: 120000 })).toEqual({ needsTools: true, minWindowRequired: 120000 });
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }