@wenathlan/getry 2.0.165 → 2.0.167

package/{tests → test}/cli.test.ts

@@ -289,7 +289,7 @@ describe("cli init with db keys", () => {
     );
     expect(keyscode).toBe(0);
     expect(stdout).toContain("register keys");
-    const seed = join(dbworkdir, "tests", "seedkeys.mjs");
+    const seed = join(dbworkdir, "test", "seedkeys.mjs");
     expect(existsSync(seed)).toBe(true);
     const content = readFileSync(seed, "utf8");
     expect(content).toContain("key-aaaaaaaaaa");

package/{tests → test}/gateway.test.ts

@@ -889,9 +889,9 @@ describe("hardcoded provider url scan of the source tree", () => {
     const outsidescan = new Set([...gatewaysources, "providers.ts", "gateway.ts", "types.ts"]);
     for (const entry of await readdir(root))
       if (entry.endsWith(".ts") && !outsidescan.has(entry)) files.push(join(root, entry));
-    for (const entry of await readdir(join(root, "tests")))
+    for (const entry of await readdir(join(root, "test")))
       if (entry.endsWith(".ts") && !entry.endsWith(".test.ts") && entry !== "reviewedorigins.ts")
-        files.push(join(root, "tests", entry));
+        files.push(join(root, "test", entry));
     expect(files.length).toBeGreaterThan(40);
     const providerhosts = [
       /api\.openai\.com/,

package/{tests → test}/gatewayversions.test.ts

@@ -6,7 +6,7 @@
  * through the thinking seat. the suite pins its own DATABASE_URL before the
  * db import so the mirror opens its own seat (one writer per wal file — the
  * SQLITE_BUSY lesson). runnable with vitest:
- *   pnpm vitest run tests/gatewayversions.test.ts
+ *   pnpm vitest run test/gatewayversions.test.ts
  */
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";

package/{tests → test}/intelligence.test.ts

@@ -5,7 +5,7 @@
 // provenance and metrics domain rides its new owner — the battery
 // answers the same contracts the engine suite once pinned: the rag
 // chunking, the retrieval provenance and the token budget trio).
-// runnable with vitest: pnpm vitest run tests/intelligence.test.ts
+// runnable with vitest: pnpm vitest run test/intelligence.test.ts
 import assert from "node:assert/strict";
 import { describe, it } from "vitest";
 import {

package/{tests → test}/keyrotation.test.ts

@@ -3,7 +3,7 @@
  * the health-aware round-robin of nextkeyrow (the pr19 key rotation law —
  * never expose keys, rotation periods, per-provider health) beside the
  * masking discipline the render paths owe. runnable with vitest:
- *   pnpm vitest run tests/keyrotation.test.ts
+ *   pnpm vitest run test/keyrotation.test.ts
  */
 import assert from "node:assert/strict";
 import { describe, it } from "vitest";

package/{tests → test}/onboardingstate.test.ts

@@ -1,7 +1,7 @@
 // # onboardingstate.test — the pure contract of the seen flags: the host
 //   validation of the platform base (https only, public hosts only, mapped
 //   ipv6 normalized) and the seen-wins stage merge the accessor and the
-//   pages share. runnable with vitest: pnpm vitest run tests/onboardingstate.test.ts
+//   pages share. runnable with vitest: pnpm vitest run test/onboardingstate.test.ts
 import assert from "node:assert/strict";
 import { describe, it } from "vitest";
 import { hostallowed, mergeStage } from "../onboardingstate.ts";

package/{tests → test}/providerfixtures.ts

@@ -1,6 +1,6 @@
 /** The recorded provider wire fixtures of the gateway family as one dense typescript module: the streams, the completions, the model lists and the tags answer of the four provider shapes (anthropic, gemini, ollama and the openai compatible surface), each export holding the exact original file text of its tests root source. The localhost gateway fixture server serves them over plain http so the adapter suite and the container smoke run the full request cycle offline — no external network, no provider endpoint, no key — and the gateway tests parse the same bodies the stub transports answer. */
 
-/** the anthropic message stream (sse events of the content block delta family) — the exact text of the former tests/anthropic-stream.txt. */
+/** the anthropic message stream (sse events of the content block delta family) — the exact text of the former test/anthropic-stream.txt. */
 export const anthropicstream = `event: message_start
 data: {"type":"message_start","message":{"id":"msg-fixture-1","role":"assistant"}}
 
@@ -24,7 +24,7 @@ data: {"type":"message_stop"}
 
 `;
 
-/** the anthropic completion answer (the stop reason and the usage record) — the exact text of the former tests/anthropic-completion.json. */
+/** the anthropic completion answer (the stop reason and the usage record) — the exact text of the former test/anthropic-completion.json. */
 export const anthropiccompletion = `{
   "id": "msg-fixture-1",
   "type": "message",
@@ -41,7 +41,7 @@ export const anthropiccompletion = `{
 }
 `;
 
-/** the anthropic model list (the fixture claude shapes with their context windows) — the exact text of the former tests/anthropic-models.json. */
+/** the anthropic model list (the fixture claude shapes with their context windows) — the exact text of the former test/anthropic-models.json. */
 export const anthropicmodels = `{
   "data": [
     {
@@ -61,7 +61,7 @@ export const anthropicmodels = `{
 }
 `;
 
-/** the gemini generatecontent stream (the sse quoted-json chunks of the streamed answer) — the exact text of the former tests/gemini-stream.txt. */
+/** the gemini generatecontent stream (the sse quoted-json chunks of the streamed answer) — the exact text of the former test/gemini-stream.txt. */
 export const geministream = `data: {"candidates":[{"content":{"parts":[{"text":"gemini "}],"role":"model"},"index":0}]}
 
 data: {"candidates":[{"content":{"parts":[{"text":"candidate parts "}],"role":"model"},"index":0}]}
@@ -70,7 +70,7 @@ data: {"candidates":[{"content":{"parts":[{"text":"stream"}],"role":"model"},"in
 
 `;
 
-/** the gemini completion answer (the candidates with the finish reason) — the exact text of the former tests/gemini-completion.json. */
+/** the gemini completion answer (the candidates with the finish reason) — the exact text of the former test/gemini-completion.json. */
 export const geminicompletion = `{
   "candidates": [
     {
@@ -86,7 +86,7 @@ export const geminicompletion = `{
 }
 `;
 
-/** the gemini model list (the fixture gemini shapes) — the exact text of the former tests/gemini-models.json. */
+/** the gemini model list (the fixture gemini shapes) — the exact text of the former test/gemini-models.json. */
 export const geminimodels = `{
   "models": [
     {
@@ -106,13 +106,13 @@ export const geminimodels = `{
 }
 `;
 
-/** the ollama chat stream (the ndjson lines of the streamed answer) — the exact text of the former tests/ollama-stream.txt. */
+/** the ollama chat stream (the ndjson lines of the streamed answer) — the exact text of the former test/ollama-stream.txt. */
 export const ollamastream = `{"model":"fixture-local:7b","created_at":"2026-01-01T00:00:00Z","message":{"role":"assistant","content":"the local "},"done":false}
 {"model":"fixture-local:7b","created_at":"2026-01-01T00:00:00Z","message":{"role":"assistant","content":"runtime streams "},"done":false}
 {"model":"fixture-local:7b","created_at":"2026-01-01T00:00:00Z","message":{"role":"assistant","content":"line by line"},"done":true}
 `;
 
-/** the ollama chat completion answer (the message and the done record) — the exact text of the former tests/ollama-completion.json. */
+/** the ollama chat completion answer (the message and the done record) — the exact text of the former test/ollama-completion.json. */
 export const ollamacompletion = `{
   "model": "fixture-local:7b",
   "created_at": "2026-01-01T00:00:00Z",
@@ -126,7 +126,7 @@ export const ollamacompletion = `{
 }
 `;
 
-/** the ollama tags answer (the local model list with sizes and digests) — the exact text of the former tests/ollama-tags.json. */
+/** the ollama tags answer (the local model list with sizes and digests) — the exact text of the former test/ollama-tags.json. */
 export const ollamatags = `{
   "models": [
     {
@@ -161,7 +161,7 @@ export const ollamatags = `{
 }
 `;
 
-/** the openai compatible chat stream (the sse chunks of the streamed answer) — the exact text of the former tests/openaicompat-stream.txt. */
+/** the openai compatible chat stream (the sse chunks of the streamed answer) — the exact text of the former test/openaicompat-stream.txt. */
 export const openaicompatstream = `data: {"id":"chatcmpl-fixture-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"{\\"goal\\":"}}]}
 
 data: {"id":"chatcmpl-fixture-1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"\\"streamed answer\\","}}]}
@@ -172,7 +172,7 @@ data: [DONE]
 
 `;
 
-/** the openai compatible chat completion answer (the choices with the message and the usage) — the exact text of the former tests/openaicompat-completion.json. */
+/** the openai compatible chat completion answer (the choices with the message and the usage) — the exact text of the former test/openaicompat-completion.json. */
 export const openaicompatcompletion = `{
   "id": "chatcmpl-fixture-1",
   "object": "chat.completion",
@@ -191,7 +191,7 @@ export const openaicompatcompletion = `{
 }
 `;
 
-/** the openai compatible model list (the fixture model shapes) — the exact text of the former tests/openaicompat-models.json. */
+/** the openai compatible model list (the fixture model shapes) — the exact text of the former test/openaicompat-models.json. */
 export const openaicompatmodels = `{
   "object": "list",
   "data": [

package/{tests → test}/researchfixtures.ts

@@ -1,4 +1,4 @@
-/** The public research catalog sources as one dense typescript module: the twelve public github search exports beside the two markdown documents the catalog build derives from them, each export holding the exact original file text of its tests/code source. The exports record source metadata only — the catalog build never downloads or executes repository code — and the markdown documents carry the licensed sample, the method notes and the comparative feature and flow matrix the research review reads. */
+/** The public research catalog sources as one dense typescript module: the twelve public github search exports beside the two markdown documents the catalog build derives from them, each export holding the exact original file text of its test/code source. The exports record source metadata only — the catalog build never downloads or executes repository code — and the markdown documents carry the licensed sample, the method notes and the comparative feature and flow matrix the research review reads. */
 
 /** The public repository metadata of the browser agent search export (one recorded repository), harvested from the public github search index on 2026-08-27 — the exact text of the former reposagent.json. */
 export const reposagent = `[

package/{tests → test}/sandboxmodality.test.ts

@@ -9,7 +9,7 @@
 // modality id pins the seat for the platform's join to validate at
 // dispatch — this module never judges engine vocabulary). runnable with
 // vitest:
-//   pnpm vitest run tests/sandboxmodality.test.ts
+//   pnpm vitest run test/sandboxmodality.test.ts
 import assert from "node:assert/strict";
 import { describe, it } from "vitest";
 import { lanesof } from "@wenathlan/saddle/workloadlaw";

package/thinking.ts

@@ -0,0 +1,416 @@
+/**
+ * thinking.ts — the thinking seat of getry (root layer): the registerable
+ * reasoning ladder plus the routing the rungs drive.
+ *
+ * the reasoning ladder the gateway accepts on every chat route: named
+ * levels, each bound to the thinking budget the provider receives. the
+ * ladder is registered, never fixed: the seven rungs below are the family
+ * seed only — a registration (the GETRY_THINKING_LEVELS surface at boot,
+ * or registerthinkinglevels from the host) replaces the whole ladder with
+ * whatever the person registered: any count, any names, any budgets. no
+ * ceiling lives in this engine — a plan that wants fewer rungs blocks in
+ * the devthink system layer, never here.
+ *
+ * beside the ladder the seat owns the routing the level selects: the model
+ * tier the rung targets (tier routing), the token budget clamped to the
+ * model output ceiling, the two-calls pattern verdict, the ordered
+ * fallback chain over the provider catalog, and the session/stream lanes a
+ * thinking request rides. every routing function below is pure,
+ * dependency-free math over structural rows — the gateway modules (engine,
+ * gateway) and the family consumers (devthink and siblings) wire the real
+ * catalog rows in, never a second copy of the math.
+ *
+ * the logicfold3 fold retired the thinkingtypes.ts mirror this seat once
+ * carried (the declaration surface that repeated every export below as an
+ * `export declare` tombstone — zero import sites repo-wide) — every
+ * declaration it mirrored answers from this implementation alone.
+ */
+
+/** the name of one thinking level — the seven seed rungs stay literate for
+ * completion, and any registered name rides beside them: the vocabulary is
+ * what the person registers, never a closed union. */
+export type ThinkingLevelName = (string & {}) | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/** one rung of the reasoning ladder. */
+export type ThinkingLevel = {
+  level: ThinkingLevelName;
+  budget: number;
+  desc: string;
+};
+
+/** the family seed ladder — the seven rungs the self-hosted build answers
+ * until a registration replaces them. the seed is a default, never a
+ * ceiling: registerthinkinglevels accepts any count of rungs. */
+export const THINKINGLEVELS: ThinkingLevel[] = [
+  { level: "none", budget: 0, desc: "no thinking" },
+  { level: "minimal", budget: 1400, desc: "quick reasoning" },
+  { level: "low", budget: 5500, desc: "light reasoning" },
+  { level: "medium", budget: 17000, desc: "balanced" },
+  { level: "high", budget: 68000, desc: "deep reasoning default" },
+  { level: "xhigh", budget: 68000, desc: "extra deep" },
+  { level: "max", budget: 68000, desc: "maximum" },
+];
+
+/** the seed rung the gateway resolves when the request names none — the
+ * registered default (GETRY_THINKING_DEFAULT or registerthinkinglevels)
+ * overrides it at runtime through defaultthinkinglevel(). */
+export const DEFAULTTHINKINGLEVEL: ThinkingLevelName = "high";
+
+/** the registration surface: GETRY_THINKING_LEVELS — a JSON array of rung
+ * objects ({"level","budget","desc"}) the person registers at boot; any
+ * count rides. invalid json answers the family seed untouched. */
+const LEVELS_ENV = "GETRY_THINKING_LEVELS";
+
+/** the registration surface for the default rung: GETRY_THINKING_DEFAULT —
+ * a level name that must name a rung of the registered ladder. */
+const DEFAULT_ENV = "GETRY_THINKING_DEFAULT";
+
+/** parses one registration payload into a ladder — the honest rungs only:
+ * named, finite-budgeted, deduped (last wins). no count cap applies. */
+function parseRegisteredLevels(raw: string): ThinkingLevel[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) return null;
+  const rungs = new Map<string, ThinkingLevel>();
+  for (const entry of parsed) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { level, budget, desc } = entry as Record<string, unknown>;
+    if (typeof level !== "string" || level.trim() === "") continue;
+    const name = level.toLowerCase().trim();
+    const tokens = typeof budget === "number" && Number.isFinite(budget) && budget >= 0 ? Math.floor(budget) : 0;
+    rungs.set(name, {
+      level: name,
+      budget: tokens,
+      desc: typeof desc === "string" && desc !== "" ? desc : `registered level ${name}`,
+    });
+  }
+  return rungs.size === 0 ? null : [...rungs.values()];
+}
+
+/** the live ladder: the registered rungs, or the family seed when no
+ * registration ever landed. resolved once at import from the environment
+ * so the load-time budget maps capture the registered ladder too. */
+let ladder: ThinkingLevel[] = parseRegisteredLevels(process.env[LEVELS_ENV] ?? "") ?? THINKINGLEVELS;
+
+/** the live default rung: a registered default that names a real rung, or
+ * the family seed default. */
+let ladderDefault: ThinkingLevelName | null = (() => {
+  const raw = process.env[DEFAULT_ENV];
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  const name = raw.toLowerCase().trim();
+  return ladder.some((rung) => rung.level === name) ? name : null;
+})();
+
+/**
+ * registers the thinking ladder — the owner's word is the law: any count of
+ * rungs, any names, any budgets (no ceiling in this engine). the
+ * registration replaces the whole ladder; pass the seed back to restore the
+ * family default. invalid entries are skipped, duplicates keep the last
+ * write, and an empty registration answers the seed untouched.
+ *
+ * @law levels depend on what the person registers — never a fixed 7
+ * @param levels the rungs to register.
+ * @param options the default rung of the registration (must name a rung).
+ * @returns the live ladder after the registration.
+ */
+export function registerthinkinglevels(
+  levels: readonly ThinkingLevel[],
+  options?: { default?: ThinkingLevelName },
+): ThinkingLevel[] {
+  const rungs = parseRegisteredLevels(JSON.stringify(levels));
+  if (rungs === null) return ladder;
+  ladder = rungs;
+  const wanted = options?.default;
+  if (typeof wanted === "string" && wanted.trim() !== "" && islevel(wanted)) {
+    ladderDefault = wanted.toLowerCase().trim();
+  } else if (wanted === undefined) {
+    ladderDefault = ladder.some((rung) => rung.level === DEFAULTTHINKINGLEVEL) ? DEFAULTTHINKINGLEVEL : null;
+  }
+  return ladder;
+}
+
+/**
+ * lists the live ladder in serve order (the registration order, none first
+ * when the seed rides).
+ *
+ * @returns the thinking levels the engine accepts right now.
+ */
+export function listlevels(): ThinkingLevel[] {
+  return ladder;
+}
+
+/** the live default rung — the registered default or the family seed. */
+export function defaultthinkinglevel(): ThinkingLevelName {
+  return ladderDefault ?? DEFAULTTHINKINGLEVEL;
+}
+
+/**
+ * resolves the budget of one named level against the live ladder.
+ *
+ * @param level the level name to resolve.
+ * @returns the thinking budget in tokens — 0 when the rung never registered.
+ */
+export function budgetof(level: ThinkingLevelName): number {
+  return ladder.find((rung) => rung.level === (typeof level === "string" ? level.toLowerCase().trim() : level))
+    ?.budget ?? 0;
+}
+
+/**
+ * checks whether a request value names a real rung of the live ladder.
+ *
+ * @param candidate the raw value from the request.
+ * @returns true when the value is a registered level.
+ */
+export function islevel(candidate: string): candidate is ThinkingLevelName {
+  const name = candidate.toLowerCase().trim();
+  return ladder.some((rung) => rung.level === name);
+}
+
+/**
+ * formats a budget the way the theme renders it (grouped thousands).
+ *
+ * @param budget the budget in tokens.
+ * @returns the formatted label.
+ */
+export function formatbudget(budget: number): string {
+  return budget.toLocaleString("en-US");
+}
+
+/* ===== block: tier routing ===== */
+
+/** the model tier vocabulary the provider catalog rows carry (the
+ * intelligencerank tier of the gateway types): 1 the flagship tier, 2 the
+ * strong tier, 3 the mid tier, 4 the economy tier. */
+export type thinkingmodeltier = 1 | 2 | 3 | 4;
+
+/**
+ * resolves the model tier one thinking level targets — the rung POSITION
+ * on the live ladder selects the tier, never the name: the fraction of the
+ * ladder the rung sits at walks the tiers bottom-up (at or below a quarter
+ * the economy tier 4, at or below a half the mid tier 3, at or below three
+ * quarters the strong tier 2, above it the flagship tier 1), so the family
+ * seed routes none/minimal to 4, low/medium to 3, high to 2 and xhigh/max
+ * to the flagship 1 — and a registered ladder of any length routes the same
+ * way. a single-rung registration answers the ceiling the rung carries (a
+ * zero-budget rung targets the economy tier, every other single rung the
+ * flagship). a level that names no rung of the live ladder routes the
+ * default rung's tier, the same honest fallback budgetof answers.
+ *
+ * @law the level selects the model tier — the tier ladder never hardcodes
+ *      the seven seed names
+ * @param level the level name to route.
+ * @returns the model tier the level targets.
+ */
+export function targettier(level: ThinkingLevelName): thinkingmodeltier {
+  const rungs = ladder;
+  const named = typeof level === "string" ? level.toLowerCase().trim() : level;
+  let index = rungs.findIndex((rung) => rung.level === named);
+  if (index < 0) index = rungs.findIndex((rung) => rung.level === defaultthinkinglevel());
+  if (index < 0) return 2;
+  if (rungs.length <= 1) return rungs[index].budget === 0 ? 4 : 1;
+  const fraction = index / (rungs.length - 1);
+  if (fraction <= 0.25) return 4;
+  if (fraction <= 0.5) return 3;
+  if (fraction <= 0.75) return 2;
+  return 1;
+}
+
+/* ===== block: token budgets ===== */
+
+/** the two-calls threshold the family seed pins (98304 tokens — the glm
+ * max output window the v1 lane rides); a config threshold always wins. */
+export const TWOCALLSTHRESHOLD = 98304;
+
+/**
+ * clamps the budget of one level to a model's output ceiling — the gateway
+ * never promises the provider more thinking tokens than the model can
+ * answer with (the clamp discipline the bodybuild config names).
+ *
+ * @param level the level whose budget rides.
+ * @param ceiling the model max output tokens (no clamp when absent).
+ * @returns the budget in tokens, clamped down to the ceiling.
+ */
+export function clampbudget(level: ThinkingLevelName, ceiling?: number): number {
+  const budget = budgetof(level);
+  if (ceiling === undefined || !Number.isFinite(ceiling) || ceiling <= 0) return budget;
+  return Math.min(budget, Math.floor(ceiling));
+}
+
+/**
+ * decides whether a request rides the two-calls pattern (call 1 thinking
+ * enabled, call 2 a fresh response when the guarantee rides): the pattern
+ * fires when the thinking budget plus the response ceiling crosses the
+ * threshold, or whenever the level thinks at all — the exact math the
+ * engine's zai sdk lane always carried, lifted here so every consumer
+ * answers the same verdict.
+ *
+ * @param level the thinking level of the request.
+ * @param responsemax the response ceiling in tokens (max_tokens or the
+ *        metamodel output window).
+ * @param threshold the two-calls trigger threshold (the family default
+ *        98304 when absent).
+ * @param budget the effective thinking budget when a config map overrides
+ *        the ladder (the live ladder answers when absent).
+ * @returns true when the request rides the two-calls pattern.
+ */
+export function twocallspattern(input: {
+  level: ThinkingLevelName;
+  responsemax: number;
+  threshold?: number;
+  budget?: number;
+}): boolean {
+  const budget = input.budget ?? budgetof(input.level);
+  const threshold = input.threshold ?? TWOCALLSTHRESHOLD;
+  return budget + input.responsemax > threshold || input.level !== "none";
+}
+
+/* ===== block: fallback chains ===== */
+
+/** one model row of the provider catalog the seat routes over — the
+ * structural slice of the modeldef kind the gateway types own (id,
+ * reasoning flag, output ceiling, leaderboard rank): the seat never
+ * imports the gateway graph, so the rows ride as plain shapes. */
+export type thinkingmodelrow = {
+  id: string;
+  reasoning?: boolean;
+  maxoutput?: number;
+  rank?: { score?: number; tier?: thinkingmodeltier };
+};
+
+/**
+ * checks whether one catalog model can serve a thinking level: a model
+ * that carries no reasoning flag counts as capable (the family convention
+ * — an unknown capability answers true the way the engine's
+ * supports_thinking projection does), a model that declares reasoning
+ * false never carries a thinking budget.
+ *
+ * @param model the catalog row to check.
+ * @param level the level the request rides.
+ * @returns true when the model may serve the level.
+ */
+export function modelcapable(model: thinkingmodelrow, level: ThinkingLevelName): boolean {
+  if (model.reasoning === false) return level === "none";
+  return true;
+}
+
+/**
+ * builds the ordered fallback chain of one provider's catalog for a level:
+ * the capable models ordered by tier distance from the level's target
+ * tier (exact tier first, adjacent tiers outward), then by whether the
+ * output ceiling holds the full budget unclamped, then by leaderboard
+ * score, then by id — a stable, honest order the caller walks top to
+ * bottom on failure. unranked models ride after every ranked tier.
+ *
+ * @param models the provider catalog rows.
+ * @param level the level the request rides.
+ * @returns the ordered capable rows.
+ */
+export function fallbackchain(models: readonly thinkingmodelrow[], level: ThinkingLevelName): thinkingmodelrow[] {
+  const target = targettier(level);
+  const budget = budgetof(level);
+  const capable = models.filter((model) => modelcapable(model, level));
+  const distance = (model: thinkingmodelrow): number => {
+    const tier = model.rank?.tier;
+    if (tier === undefined) return Number.MAX_SAFE_INTEGER;
+    return Math.abs(tier - target);
+  };
+  const fullfit = (model: thinkingmodelrow): boolean =>
+    model.maxoutput === undefined || model.maxoutput >= budget;
+  return capable.sort((left, right) => {
+    const bydistance = distance(left) - distance(right);
+    if (bydistance !== 0) return bydistance;
+    const byfit = Number(fullfit(right)) - Number(fullfit(left));
+    if (byfit !== 0) return byfit;
+    const byscore = (right.rank?.score ?? -Infinity) - (left.rank?.score ?? -Infinity);
+    if (byscore !== 0) return byscore;
+    return left.id.localeCompare(right.id);
+  });
+}
+
+/* ===== block: session and stream lanes ===== */
+
+/** the lane a thinking request rides: "session" pins the per-session
+ * rotation context (the rotation cursor and the thinking budget bind to
+ * the (sessionid, provider) row the sessions store owns), "stream" rides
+ * the sse emission contract (reasoning deltas before content, the parser
+ * pattern the streaming routes follow). a request may ride both lanes at
+ * once — a session-scoped stream. */
+export type thinkinglane = "session" | "stream";
+
+/**
+ * resolves the lanes one thinking request rides, in bind order: the
+ * session lane first (the rotation context binds before any byte leaves
+ * the gateway), the stream lane second (the emission order of the
+ * answer). a request that names neither lane rides no named lane — a
+ * plain one-shot completion.
+ *
+ * @param input the request shape: stream true asks the sse contract,
+ *        sessionid binds the session rotation context.
+ * @returns the lanes in bind order (empty when the request is a plain
+ *          one-shot completion).
+ */
+export function lanesof(input: { stream?: boolean; sessionid?: string | null }): thinkinglane[] {
+  const lanes: thinkinglane[] = [];
+  if (typeof input.sessionid === "string" && input.sessionid.trim() !== "") lanes.push("session");
+  if (input.stream === true) lanes.push("stream");
+  return lanes;
+}
+
+/* ===== block: provider catalog ===== */
+
+/** one provider row of the catalog the seat routes over — the structural
+ * slice of the gateway version rows (provider name, lifecycle badge, the
+ * model catalog). */
+export type thinkingproviderrow = {
+  provider: string;
+  badge?: "live" | "paused";
+  models: readonly thinkingmodelrow[];
+};
+
+/**
+ * lists the providers whose catalog serves a level (at least one capable
+ * model), live providers first — a paused provider still serves the list
+ * as a fallback seat the way the paused v2 lane falls back to v1, it just
+ * never leads the chain.
+ *
+ * @param catalog the provider rows.
+ * @param level the level the request rides.
+ * @returns the serving providers, live first, input order stable within
+ *          each badge group.
+ */
+export function providersserving(catalog: readonly thinkingproviderrow[], level: ThinkingLevelName): thinkingproviderrow[] {
+  return catalog
+    .filter((provider) => provider.models.some((model) => modelcapable(model, level)))
+    .sort((left, right) => Number(left.badge !== "live") - Number(right.badge !== "live"));
+}
+
+/** one provider/model candidate of the cross-provider chain. */
+export type thinkingcandidate = { provider: string; model: thinkingmodelrow };
+
+/**
+ * builds the cross-provider fallback chain for a level: every serving
+ * provider in live-first order, each contributing its own ordered
+ * fallbackchain — the single honest walk order a consumer retries through
+ * on failure (the tier-exact candidate of the live providers first, the
+ * paused providers' candidates last).
+ *
+ * @param catalog the provider rows.
+ * @param level the level the request rides.
+ * @returns the ordered provider/model candidates.
+ */
+export function providerchain(
+  catalog: readonly thinkingproviderrow[],
+  level: ThinkingLevelName,
+): thinkingcandidate[] {
+  const chain: thinkingcandidate[] = [];
+  for (const provider of providersserving(catalog, level)) {
+    for (const model of fallbackchain(provider.models, level)) {
+      chain.push({ provider: provider.provider, model });
+    }
+  }
+  return chain;
+}