@wenathlan/getry 2.0.162 → 2.0.164

package/cli.ts

@@ -44,7 +44,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
 import { stdin, stdout } from "node:process";
 import { createInterface, type Interface } from "node:readline/promises";
-import { main } from "./server.js";
 
 // ---------------------------------------------------------------------------
 // arg parsing — zero dependency
@@ -795,6 +794,13 @@ async function cmdserve(portarg: string | undefined): Promise<void> {
   const port = Number(portarg) || Number(process.env.PORT) || 3001;
   process.env.PORT = String(port);
   console.log(`${colors.cyan}starting gateway on port ${port}${colors.reset}`);
+  /* the transport main loads lazily (the published-envelope law): the
+   * console family — init through export, chat, help — runs on node
+   * builtins alone inside the published envelope, and the serve seat
+   * imports the engine transport only when the caller actually serves,
+   * so a documentation envelope never crashes on a module it does not
+   * ship before a command ever dispatches. */
+  const { main } = await import("./server.js");
   await main();
 }
 
@@ -820,6 +826,93 @@ async function cmdexport(dirarg: string | undefined): Promise<void> {
   console.log(`\nexported to ${target} — deploy this folder to vercel or netlify`);
 }
 
+// ---------------------------------------------------------------------------
+// chat — the windows 11 console seat of the clibin family (pr13: same
+// design as the web / desktop surface, the difference is only the
+// responsiveness / dpi — native detection, 1x / 1.5x / 2x / 3x, never xdpi)
+// ---------------------------------------------------------------------------
+
+/** the chat accent of the prompt and the titlebar name (ansi 117 — the family accent #a3d7e6). */
+const CHATACCENT = "\x1b[38;5;117m" as const;
+/** the focus ink of the active top rule (ansi 75 — the family focus #4cc2ff). */
+const CHATFOCUS = "\x1b[38;5;75m" as const;
+/** the hover red of the unknown-command rows (ansi 203 — rgb(232, 17, 35)). */
+const CHATHOVER = "\x1b[38;5;203m" as const;
+/** the dim ink of the description rows (the minimal text law). */
+const CHATINK = "\x1b[2m" as const;
+/** the reset token that closes every colored run. */
+const CHATRESET = "\x1b[0m" as const;
+/** the single glyph of the rules and the rails. */
+const CHATBAR = "─" as const;
+/** the engine ownership one-liner of the seat, quoted from the help banner. */
+const CHATENGINE = "the universal ai gateway library — any llm any baseurl any api key (the help banner)" as const;
+/** the scale ladder the native detection resolves (the automatic scaling law). */
+const CHATSCALESTEPS = [1, 1.5, 2, 3] as const;
+
+/** the dpi frame the chat chrome renders inside: the resolved scale seat, the terminal columns and the rail length the titlebar draws. */
+interface chatframe {
+  /** the scale seat of the ladder (1, 1.5, 2 or 3). */
+  scale: number;
+  /** the columns the terminal answers (windows terminal, conpty, xterm, tmux — every pty reports them). */
+  columns: number;
+  /** the titlebar rail length in cells (the pixel rail folded to the grid and clamped so the line never wraps). */
+  rail: number;
+}
+
+/** resolves the dpi frame natively, zero dependencies: the columns come from stdout (every windows and linux terminal answers them), the scale seat from the column ladder — the explicit GETRY_DPI environment override wins first (the native scaling knob). */
+function chatdetectframe(): chatframe {
+  const columns = Number.isFinite(stdout.columns) && Number(stdout.columns) > 0 ? Number(stdout.columns) : 80;
+  const override = Number(process.env.GETRY_DPI ?? "");
+  const scale =
+    Number.isFinite(override) && override > 0 && CHATSCALESTEPS.includes(override as (typeof CHATSCALESTEPS)[number])
+      ? override
+      : columns >= 200
+        ? 3
+        : columns >= 160
+          ? 2
+          : columns >= 120
+            ? 1.5
+            : 1;
+  const rail = Math.max(4, Math.min(Math.round(24 * scale), columns - "getry".length - 16));
+  return { scale, columns, rail };
+}
+
+/** runs the chat console: the titlebar, the top rule, the ❯ prompt and the dispatch (help, version, dpi, engine, exit) — the same chat look the web / desktop surfaces carry, an eof on stdin closing the console the same way exit does. */
+async function cmdchat(): Promise<void> {
+  const frame = chatdetectframe();
+  const seatversion = version();
+  const rl = createInterface({ input: stdin, output: stdout });
+  let eof = false;
+  rl.on("close", () => { eof = true; });
+  const rule = CHATBAR.repeat(Math.max(3, Math.round(3 * frame.scale)));
+  console.log(`${CHATACCENT}┌ getry ─ cli${CHATRESET}  ${CHATINK}${CHATBAR.repeat(frame.rail)} ─ ❐ ✕${CHATRESET}`);
+  console.log(`${CHATFOCUS}${rule} getry ${rule}${CHATRESET}`);
+  console.log(`${CHATACCENT}getry${CHATRESET} ${CHATINK}v${seatversion}${CHATRESET}`);
+  console.log(`${CHATINK}the getry console — same design as web / desktop, only the DPI differs. type help.${CHATRESET}`);
+  rl.setPrompt(`${CHATACCENT}❯${CHATRESET} `);
+  rl.prompt();
+  for await (const raw of rl) {
+    const line = raw.trim();
+    const command = line.length > 0 ? line.split(/\s+/)[0]!.toLowerCase() : "";
+    if (command === "exit") rl.close();
+    else if (command === "help") {
+      console.log(`${CHATINK}commands${CHATRESET}`);
+      console.log(`  help      ${CHATINK}this list${CHATRESET}`);
+      console.log(`  version   ${CHATINK}the package version, read from package.json at runtime${CHATRESET}`);
+      console.log(`  dpi       ${CHATINK}the resolved dpi seat of this terminal (scale, columns, rail)${CHATRESET}`);
+      console.log(`  engine    ${CHATINK}the engine ownership one-liner of the app${CHATRESET}`);
+      console.log(`  exit      ${CHATINK}close the console${CHATRESET}`);
+    } else if (command === "version") console.log(`${CHATACCENT}getry${CHATRESET} ${seatversion}`);
+    else if (command === "dpi") console.log(`${CHATACCENT}getry${CHATRESET} ${CHATINK}dpi seat ${frame.scale}x on ${frame.columns} columns — rail ${frame.rail} cells, ladder 1x / 1.5x / 2x / 3x${CHATRESET}`);
+    else if (command === "engine") console.log(`${CHATINK}${CHATENGINE}${CHATRESET}`);
+    else if (command.length > 0) console.log(`${CHATHOVER}✕${CHATRESET} ${CHATINK}unknown command: ${command} — type help${CHATRESET}`);
+    if (command === "exit") break;
+    /* the prompt is cosmetic chrome: a piped stdin that already reached eof skips it, the buffered lines still answer. */
+    if (!eof) rl.prompt();
+  }
+  console.log(`${CHATINK}getry console closed.${CHATRESET}`);
+}
+
 // ---------------------------------------------------------------------------
 // help
 // ---------------------------------------------------------------------------
@@ -843,6 +936,7 @@ function printhelp(): void {
       "  models <version>           list models for a version",
       "  serve [--port <n>]         start the gateway server",
       "  export [--dir <path>]      export the web folder scaffold",
+      "  chat                       the windows 11 chat console seat (same design as web / desktop)",
       "  help                       show this help",
       "",
       "Library usage:",
@@ -910,6 +1004,9 @@ async function consolemain(): Promise<void> {
       case "export":
         await cmdexport(stringflag(parsed, "dir"));
         break;
+      case "chat":
+        await cmdchat();
+        break;
       case "help":
       case "--help":
       case "-h":

package/docs/acceptableusepolicy.md

@@ -0,0 +1,9 @@
+# Getry acceptable use policy
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Getry source code is licensed under the GNU General Public License version 3.0 only. This policy governs hosted services, credentials, runners and integrations operated with Getry; it does not reduce rights granted by the GPL.
+
+Operators must use Getry lawfully, respect the terms of each connected provider, protect credentials, and obtain authorization before accessing systems or data. Operators must not use Getry to distribute malware, evade access controls, attack third-party systems, violate privacy, infringe intellectual property, or exceed provider quotas.
+
+The project may suspend a hosted integration or reject an unsafe request when necessary to protect users, providers or the public. These operational controls do not restrict lawful use, modification or redistribution of the GPL-licensed software itself.

package/docs/authors.md

@@ -0,0 +1,16 @@
+# Getry authors
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The project authors and historical copyright holders are:
+
+| Contributor | Role |
+|---|---|
+| devthink | Historical author and project contributor |
+| nathlan | Project owner and maintainer |
+| iakadion | Historical author and project contributor |
+| nathu filho | Historical author and project contributor |
+| allan neris | Historical author and project contributor |
+| andraneris | Historical author and project contributor |
+
+Getry is maintained at https://github.com/wenathlan/devthink/tree/main/getry (the DevThink monorepo) and distributed under GPL-3.0-only. Contributors retain copyright in their original contributions unless a separate written agreement states otherwise.

package/docs/bugreport.md

@@ -0,0 +1,16 @@
+---
+name: Bug Report
+about: Report a reproducible issue in Getry
+title: "[BUG]"
+labels: bug
+---
+
+# Getry is licensed under GPL-3.0-only. Please do not include secrets or private data.
+
+**Describe the issue:**
+
+**File / Line:**
+
+**Expected behavior:**
+
+**Additional context:**

package/docs/cla.md

@@ -0,0 +1,9 @@
+# Getry contributor terms
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry does not require an exclusive proprietary assignment of contributions. A contributor submitting a change represents that the contributor has the right to submit it and grants the project the permissions necessary to review, merge, reproduce, distribute and maintain the contribution under GPL-3.0-only.
+
+The contributor keeps copyright in the contribution. The project may include the contribution in source and binary releases under GPL-3.0-only and may preserve attribution and required notices.
+
+If a separate contributor agreement is required for a particular institutional or commercial arrangement, it must be reviewed and accepted in writing before the contribution is merged. This file is not a replacement for legal advice or a bespoke agreement.

package/docs/codeofconduct.md

@@ -0,0 +1,9 @@
+# Getry code of conduct
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Getry community follows a respectful, inclusive and technically constructive standard. Participants communicate in good faith, explain technical concerns with evidence, respect different backgrounds and experience levels, and protect private information.
+
+Unacceptable conduct includes harassment, discrimination, threats, deliberate disclosure of private information, malicious interference, impersonation, spam, and behavior that violates applicable law or the project policies.
+
+Project maintainers may moderate discussions, remove harmful content, or restrict participation when necessary. Reports should be sent through the repository security or support channels, with private disclosure used for security-sensitive matters.

package/docs/contributing.md

@@ -0,0 +1,9 @@
+# Contributing to Getry
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry welcomes contributions that improve the gateway, its provider routes, the documentation, the tests and the security posture. Contributions are licensed under GPL-3.0-only unless a different compatible arrangement is agreed in writing before acceptance.
+
+A pull request should explain the change, include focused verification, preserve the root-first architecture and avoid credentials, private data or generated artifacts. Security vulnerabilities must use the private process in `SECURITY.md` rather than a public issue.
+
+Maintainers may review, request changes, decline or merge a contribution. No contributor is required to transfer exclusive ownership of their work merely to submit a pull request.

package/docs/copyright.md

@@ -0,0 +1,7 @@
+# Getry copyright notice
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Getry source code and original documentation are distributed under the GNU General Public License version 3.0 only. The complete license text is kept in the repository `LICENSE` file (the saddle seat carries the family copy) and must be distributed with covered copies.
+
+Copyright ownership remains with the respective authors and contributors. Copyright ownership does not remove the rights granted by GPL-3.0-only. The Getry name, logos and other marks are covered separately by `trademarkpolicy.md`.

package/docs/disclaimer.md

@@ -0,0 +1,7 @@
+# Getry disclaimer
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry is provided under GPL-3.0-only and without warranty to the maximum extent permitted by law. The project does not guarantee availability, correctness, security, compatibility, performance or fitness for a particular purpose.
+
+Operators remain responsible for reviewing source code, configuring integrations, protecting credentials, validating outputs and complying with the terms of connected services. Nothing in this disclaimer removes rights or obligations established by GPL-3.0-only.

package/docs/distributionlanes.md

@@ -0,0 +1,19 @@
+# Distribution lanes
+
+The eleven distribution lanes of the PR14 law and the honest status each lane answers for getry at the 2.0.163 family rung. A lane never ships metadata its real surface cannot back: a lane without a real carrier stays a documented stub until the surface lands, and no version ever bumps to fake a lane.
+
+| Lane | Carrier | Status | Note |
+| --- | --- | --- | --- |
+| npmjs | package.json — @wenathlan/getry | live | the family-npmjs lane publishes the envelope every release rung |
+| GitHub Packages npm | package.json — @wenathlan/getry | live | the family-githubnpm lane publishes the same envelope idempotently |
+| Maven | pom.xml — io.github.wenathlan:getry | live | the family-maven lane deploys the jar |
+| NuGet | getry.csproj | live | the family-nuget lane packs the envelope |
+| Gradle | build.gradle.kts — com.wenathlan:getry | live | the family-gradle lane publishes the module |
+| Ruby Gems | getry.gemspec | live | the family-rubygems lane pushes the gem |
+| Docker Container | Dockerfile | live | the family-ghcr lane pushes ghcr.io/wenathlan/getry (the vault, saddle, devthink and debonair siblings its Dockerfile COPYs ride the staged context) and the family-container lane attaches the release archive |
+| Go Get | go.mod | stub | no Go source surface ships yet — the lane lands when a real Go adapter exists, never as an empty module |
+| Cargo Crates | Cargo.toml | stub | no Rust source surface ships yet — the lane lands with a real crate, never as an empty manifest |
+| PyPi | pyproject.toml | stub | no Python package surface ships yet — the lane lands with a real wheel, never as an empty project table |
+| Homebrew | Formula | stub | no tap repository ships yet — the formula lands pointing at the real release binaries with real checksums, never at a placeholder |
+
+The engines block of package.json keeps Go, Rust and Python as declared toolchain floors — a catalog row is not a distribution lane. The dual npm law answers through the npmjs and GitHub Packages rows; the release binaries (the desktop bundles, the mobile artifacts, the container archive) ride the family-desktop, family-mobile and family-container lanes every release rung.

package/docs/eula.md

@@ -0,0 +1,7 @@
+# Getry end user license notice
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry source code, scripts and covered binaries are licensed under the GNU General Public License version 3.0 only. The repository `LICENSE` file (the saddle seat carries the family copy) controls the copyright license and grants the permissions described there.
+
+This notice does not add a proprietary restriction to GPL-licensed code. Separate terms may apply to a hosted service, a third-party provider, a trademark, or data supplied by an operator. Those terms cannot remove rights granted by the GPL for the covered source code.

package/docs/exportcontrol.md

@@ -0,0 +1,17 @@
+             GETRY - EXPORT CONTROL NOTICE
+               Version 1.0, August 2026
+
+ Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors. Licensed under GPL-3.0-only.
+ Project: getry
+
+  Project Getry is open-source software under GPL-3.0-only. Export,
+  re-export and sanctions laws may still apply to a particular operator,
+  destination, service or use case.
+
+  You agree not to export, re-export, or transfer Project getry to any
+  prohibited destination, entity, or person, or for any prohibited end-use.
+
+  Operators are responsible for checking applicable rules before
+  transferring source, binaries, credentials or data across borders.
+
+             END OF EXPORT CONTROL NOTICE

package/docs/gateway.md

@@ -9,7 +9,7 @@
 
 ## module inventory
 
-- `gateway.ts` — the gateway versions domain: `GATEWAYROUTES` (the 7 route kinds), `GATEWAYVERSIONS` (the v1–v5 catalog), `PARSERSTEPS` (the streaming parser pattern), `listversions`, `findversion`, `totalroutes`, `liveversions`.
+- `gateway.ts` — the gateway versions domain: `GATEWAYROUTES` (the 7 route kinds), `GATEWAYVERSIONS` (the v1–v5 catalog), `PARSERSTEPS` (the streaming parser pattern), `listversions`, `findversion`, `totalroutes`, `liveversions`, and `thinkingchain` (the level-routed cross-provider chain the thinking seat computes over this catalog).
 - `gatewayconfig.ts` — the embedded single-version gateway definition (v1 zai sdk, keyless).
 - `gatewayviewconfig.ts` — the shipped multi-version catalog (v1–v5) the console page renders; the config loader probes `sol/config.mjs|ts|js` for user overrides.
 - `engine.ts` — the universal gateway engine: `createversion(cfg)` produces all route handlers from one `gatewayconfig`.
@@ -20,13 +20,14 @@
 - `llm.ts` — the model call core: request building, provider calls, stream delta parsing, command guard, plan drafting, replan on fail, step reflection, usage accounting.
 - `streaming.ts` — the SSE parser and stream normalizer: split-tolerant parsing, payload normalization, thinking signature cache, OpenAI/Anthropic transformers, auto-recovery.
 - `streamfallback.ts` — the upstream error catalog and the fallback runner that walks the route chain when one model dies.
-- `routerotation.ts` — weighted pool rotation with cooldown ledger (litellm-style knobs).
+- `routerotation.ts` — the model pool rotation math: weighted draws, health-aware round-robin under a persisted cursor (`pickroundrobin`, `rotatepool`) and the cooldown ledger (litellm-style knobs).
 - `sessions.ts` — the per-(sessionId, provider) session context store and rotation index.
+- `thinking.ts` — the thinking seat (`@wenathlan/getry/thinking`): the registerable 7-level reasoning ladder plus the routing the rungs drive — tier routing (`targettier`), the budget clamp (`clampbudget`), the two-calls verdict (`twocallspattern`, `TWOCALLSTHRESHOLD`), the fallback chain (`fallbackchain`, `modelcapable`), the session/stream lanes (`lanesof`) and the provider catalog chain (`providersserving`, `providerchain`) — pure dependency-free math over structural rows.
 - `quota.ts` — dual-source (Antigravity + Gemini CLI) quota manager with adaptive TTL cache.
 - `models.ts` — the merged model catalog (frozen 25/08/2026): model definitions, classifiers, thinking tables, endpoint routing.
 - `intelligence.ts` — provenance, token estimation, markdown chunking, rag manifest, llms.txt, metric store.
 - `oauth.ts` / `accounts.ts` / `recovery.ts` / `project.ts` — the provider oauth family, multi-account manager, recovery and project id discovery.
-- `db.ts` — the database contract: typed rows, in-memory seeds, HTTPS accessors, better-sqlite3 mirror.
+- `db.ts` — the database contract: typed rows, in-memory seeds, HTTPS accessors, the health-aware round-robin key picker (`nextkeyrow`) and the better-sqlite3 mirror (onboarding states, labels and the `gateway_versions` route table).
 - `prismaconfig.ts` / `prismashim.ts` / `nodeshim.ts` — prisma schema path resolution and runtime shims.
 - `gatewayprobe.ts` — manual chat round trip against a deployed gateway (`GET /v1/models`, `POST /v1/chat/completions`).
 - `gatewaysmoke.ts` — offline container smoke: one full request cycle against the recorded openaicompat fixture.
@@ -69,8 +70,14 @@ the 7-level thinking ladder (`thinking.ts`), each level bound to a token budget:
 - `xhigh` — budget 68000, extra deep.
 - `max` — budget 68000, maximum.
 
-- helpers: `listlevels`, `budgetof`, `islevel`, `formatbudget`.
-- the engine maps the budget onto the provider param (`chattemplatekwargs` for v3, `thinking` for v1) and runs the two-calls pattern when the thinking budget plus the response cap crosses the threshold (default 98304).
+- helpers: `listlevels`, `budgetof`, `islevel`, `formatbudget`; the registration surface (`registerthinkinglevels`, `GETRY_THINKING_LEVELS`) replaces the whole ladder with any count of rungs.
+- the engine maps the budget onto the provider param (`chattemplatekwargs` for v3, `thinking` for v1) and takes the two-calls verdict from the seat (`twocallspattern`): the pattern fires when the thinking budget plus the response cap crosses the threshold (`TWOCALLSTHRESHOLD`, default 98304) or whenever the level thinks at all.
+- the routing the level drives (all pure math in `thinking.ts`):
+  - tier routing — `targettier` maps the rung POSITION (never the name) to the model tier: none/minimal → 4 (economy), low/medium → 3 (mid), high → 2 (strong), xhigh/max → 1 (flagship); registered ladders route by the same fraction.
+  - token budgets — `clampbudget` clamps the level budget to the model's output ceiling.
+  - fallback chains — `fallbackchain` orders a catalog by tier distance from the target tier, then full-budget fit, then leaderboard score, then id; `modelcapable` never serves a reasoning-false model a thinking level.
+  - lanes — `lanesof` resolves the bind order: the session lane (per-session rotation cursor and budget) before the stream lane (reasoning deltas before content).
+  - provider catalog — `providersserving`/`providerchain` build the cross-provider walk (live providers first, paused providers last); `gateway.ts` wires the real v1–v5 rows through `thinkingchain`.
 
 ## auth and key rotation
 
@@ -78,7 +85,8 @@ the 7-level thinking ladder (`thinking.ts`), each level bound to a token budget:
 - key sources resolved in configured order, first hit wins: `db` (prisma model lookup), `env` (single or separator-joined), `inline` (config provided), `ephemeralurl` (babel town pattern).
 - key rotation modes when multiple keys exist: `single`, `roundrobin`, `lru`.
 - v3 carries the key pool: 22 nvidia keys registered into the `nvidiaKey` table, round-robin per request.
-- pool-level rotation (`routerotation.ts`): weight-based picks with a cooldown ledger — 3 allowed fails, 5s cooldown, 5s escalation step, 60s ceiling (litellm router defaults lifted as pure math).
+- pool-level rotation (`routerotation.ts`): weight-based picks, health-aware round-robin under a persisted cursor and the cooldown ledger — 3 allowed fails, 5s cooldown, 5s escalation step, 60s ceiling (litellm router defaults lifted as pure math).
+- key-row rotation (`db.ts` `nextkeyrow`): health-aware round-robin over the `ApiKeyRow` pool — active, unexpired keys only; never rate-limited, never erroring seats lead; an erroring key rides only when nothing healthy remains; selection answers the row, rendering masks (`maskkey`).
 - session-level rotation (`sessions.ts`): the devthink meta model rotates every `ROTATIONEVERY = 6` turns within a session.
 - errors from upstream land on the key counters (`applyerrortokey` on `ApiKeyRow`) and feed the fallback chain.
 
@@ -93,14 +101,15 @@ the 7-level thinking ladder (`thinking.ts`), each level bound to a token budget:
 
 - `schema.prisma` — sqlite datasource (prisma client with driver adapters; libsql http/https or file url for serverless deploy via `DATABASE_URL`).
 - six models: `ChatMessage` (every interaction log across v1–v5), `NvidiaKey`, `TownKey`, `ApiKey` (the key pools), `SessionContext` (per-session rotation and thinking state), `OnboardingState` (first-run flags).
-- `db.ts` — typed rows plus in-memory seeds (`KEYSEED`, `MESSAGESEED`, `SESSIONSEED`) the static build falls back to; the self-hosted deploy answers the same rows over HTTPS; a better-sqlite3 mirror at the foot of the file runs the local gateway runtime (prepared statements only, idempotent schema, dynamic import the browser never bundles).
+- `db.ts` — typed rows plus in-memory seeds (`KEYSEED`, `MESSAGESEED`, `SESSIONSEED`, the `GATEWAYVERSIONS` family seed) the static build falls back to; the self-hosted deploy answers the same rows over HTTPS; a better-sqlite3 mirror at the foot of the file runs the local gateway runtime (prepared statements only, idempotent schema, dynamic import the browser never bundles).
+- the route table is data-driven: the `gateway_versions` mirror table holds the instance rows (seed-on-first-run from the `GATEWAYVERSIONS` family seed, registration-safe upsert through `savegatewayversion`), the internal api (`readgatewayversionrows`, `listversionrows`) serves them, and the versions/home wingets read the rows — never a hardcoded TSX table.
 - family sync contract: identity pointers are text, counts are 32-bit ints, time is datetime or iso text.
 
 ## sol surface
 
 - `sol/Sol.tsx` mounts the route table: `/intro`, `/onboarding`, `/`, `/versions`, `/thinking`, `/sessions`, `/404`.
 - subapps: `home`, `intro`, `notfound`, `onboarding`, `sessions`, `shell`, `thinking`, `toast`, `versions`, `wingets` (HomeEntrygate, ShellBrandmark, ShellEmptystate).
-- `versions` — the gateway registry: five replica rows (version tag, provider chip, live dot, the 7 route chips), the parser pattern rail, quick-start calls. every row reads `gateway.ts`.
+- `versions` — the gateway registry: five replica rows (version tag, provider chip, live dot, the 7 route chips), the parser pattern rail, quick-start calls. every row reads the db route table lane (`listversionrows`: the sqlite mirror of the gateway runtime, the family seed of `gateway.ts` under the static build).
 - `thinking` — the reasoning ladder: 7 rungs with hairline budget bars against the 68k ceiling, the default rung marked. every number reads `thinking.ts`.
 - `sessions` — the session registry: session contexts as the ledger table, rotation summary and masked provider keys as the meta rail, the recent chat log below. rows arrive over HTTPS from the self-hosted database with seed fallback.
 
@@ -113,4 +122,4 @@ the 7-level thinking ladder (`thinking.ts`), each level bound to a token budget:
 
 ## tests
 
-- 27 test files under `tests/` cover the gateway surface: gateway, server (auth, engine, property, utils), llm, modelroute, promptlibrary, routerotation, streamfallback, intelligence, jsonpolicy, family, design, cli, providercli, onboardingstate, sandboxmodality, debonairlane, torture.llm, plus the provider lineage (constants, fingerprint, models, oauth) and the shared fixtures (`gatewayserver.ts`, `providerfixtures.ts`, `researchfixtures.ts`).
+- 29 test files under `tests/` cover the gateway surface: gateway, gatewayversions (the 5/35 route table law, the sqlite mirror rows, the thinking chain), server (auth, engine, property, utils), llm, modelroute, promptlibrary, keyrotation (the health-aware key round-robin and the masking discipline), routerotation, thinkingladder (the registerable ladder and the tier/budget/chain/lane routing), streamfallback, intelligence, jsonpolicy, family, design, cli, providercli, onboardingstate, sandboxmodality, debonairlane, torture.llm, plus the provider lineage (constants, fingerprint, models, oauth) and the shared fixtures (`gatewayserver.ts`, `providerfixtures.ts`, `researchfixtures.ts`).

package/docs/governance.md

@@ -0,0 +1,9 @@
+# Getry governance
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry is maintained as a library-first open-source project under GPL-3.0-only. The repository owner coordinates releases, security response, release approvals and provider integrations. Contributors retain copyright in their contributions unless a separate written agreement states otherwise.
+
+Changes should include focused reasoning, tests where practical, documentation for public behavior, and review of security-sensitive workflows. Release artifacts must be traceable to repository source and generated by the documented automation.
+
+Technical governance is recorded in the repository plans and workflow files. This document describes project responsibility and does not override the GPL or a contributor's applicable rights.

package/docs/notice.md

@@ -0,0 +1,7 @@
+# Getry notice
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry is open-source software licensed under the GNU General Public License version 3.0 only. The source code, generated artifacts and documentation may include work from third-party projects; each third-party component remains subject to its own license.
+
+The project name and logos are trademarks of their respective owner. The trademark policy does not restrict rights granted by GPL-3.0-only to the source code.

package/docs/privacypolicy.md

@@ -0,0 +1,9 @@
+# Getry privacy policy
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The Getry gateway library does not intentionally collect telemetry or transmit data without an operator-requested integration. Gateway, provider and session features can access data only when the operator configures and invokes them. Operators must review the configuration and the privacy policy of every connected provider.
+
+The repository itself is hosted by third-party services such as GitHub. Those services process requests, account data, logs and cookies under their own policies. A deployment that adds analytics, account data, logs or external storage must document that behavior and provide the controls required by applicable law.
+
+Privacy questions and reports should use the repository support channel. Security-sensitive reports must follow `SECURITY.md`.

package/docs/pullrequesttemplate.md

@@ -0,0 +1,13 @@
+<!-- Getry pull request template -->
+
+# Description
+
+## Type of change
+
+## Verification
+
+- [ ] The change preserves GPL-3.0-only metadata and required notices.
+- [ ] Tests or a reason for not adding tests are included.
+- [ ] Security-sensitive behavior and workflow changes were reviewed.
+- [ ] No credentials, private data or generated build output was added.
+- [ ] Public documentation was updated when behavior changed.

package/docs/support.md

@@ -0,0 +1,7 @@
+# Getry support
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry is open-source software under GPL-3.0-only. Questions about installation, configuration, usage and reproducible failures should include the version, target, relevant logs and a minimal reproduction without credentials or private data.
+
+Security reports must use the private process in `SECURITY.md`. Requests involving a third-party provider should also include the provider and the operator-controlled configuration. Community support is provided on a best-effort basis and does not create a warranty, service-level agreement or maintenance obligation.

package/docs/termsandconditions.md

@@ -0,0 +1,9 @@
+# Getry terms and conditions
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+These terms describe access to the Getry repository, documentation, releases and project services. The source code license is the GNU General Public License version 3.0 only; the repository `LICENSE` file (the saddle seat carries the family copy) controls permissions to copy, modify, run and redistribute covered works.
+
+Users must comply with applicable law, third-party provider terms, the acceptable use policy, and the security policy. Users must not use a configured integration to access data or systems without authorization, expose credentials, distribute malware, or evade safety controls.
+
+The repository and project services are provided without warranty to the maximum extent permitted by law. Separate provider terms apply to infrastructure, accounts, data and hosted services. These terms do not add restrictions to GPL-licensed source code.

package/docs/termsofuse.md

@@ -0,0 +1,9 @@
+# Getry terms of use
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry may be used, modified and redistributed under GPL-3.0-only. Use of a connected provider account or api key remains subject to the operator's authorization and that provider's terms.
+
+Users must protect secrets, respect privacy, avoid unauthorized access, and validate outputs before relying on them. Feedback may be used by the project under the applicable copyright permissions; submitting feedback does not transfer unrelated rights in the contributor's code.
+
+The project is provided as-is without a warranty or service-level commitment. The GPL and applicable law control where this document conflicts with a covered source license.

package/docs/thirdpartynotices.md

@@ -0,0 +1,7 @@
+# Getry third-party notices
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+Getry includes or builds with third-party components. Their individual licenses remain in force and are not replaced by GPL-3.0-only. Package manifests, lockfiles and generated license inventories are the source of truth for the exact dependency set of each release.
+
+When a component requires a notice, attribution or source offer, the release process must include it. A future dependency should be recorded with its name, version, license identifier, copyright notice and source URL.

package/docs/trademarkpolicy.md

@@ -0,0 +1,7 @@
+# Getry trademark policy
+
+Copyright (C) 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris, and contributors.
+
+The name “Getry”, together with associated logos and marks, identifies the project and its official releases. GPL-3.0-only grants rights to the source code; it does not grant permission to use project marks in a way that suggests endorsement, affiliation or official distribution.
+
+Forks and modified distributions should use distinct names and branding where necessary to avoid confusion. Descriptive references to compatibility, origin or modification are permitted when they are accurate and do not imply sponsorship.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/getry",
-  "version": "2.0.162",
+  "version": "2.0.164",
   "description": "getry is the AI gateway of the wenathlan family: five provider gateways (v1 zai, v2 babel, v3 nvidia, v4 opencode+kilo, v5 openrouter) serving 35 OpenAI-compatible routes with the 7-level thinking system, the session store and the key rotation, described by schema.prisma and served as one static Sol surface. The envelope distributes the documentation set and the tests directory as one package.",
   "keywords": [
     "getry",
@@ -194,9 +194,11 @@
   "files": [
     "README.md",
     "docs",
-    "tests"
+    "tests",
+    "cli.ts"
   ],
   "engines": {
+    "babel": "^7.28.0",
     "bare": "^1.18.0",
     "bun": "^1.4.4",
     "cargo": ">=1.85.0",
@@ -219,6 +221,7 @@
     "typescript": "^5.8.0",
     "v": "^0.5.2",
     "vscode": "^1.118.0",
+    "yaml": "^2.9.1",
     "yarn": "^4.17.1"
   },
   "peerDependencies": {
@@ -246,12 +249,12 @@
     "@libsql/client": "^0.18.0",
     "@prisma/adapter-libsql": "^7.10.1",
     "@prisma/client": "^7.10.1",
+    "@wenathlan/argan": "~2.0.155",
     "@wenathlan/cadria": "~2.0.155",
     "@wenathlan/debonair": "~2.0.155",
     "@wenathlan/devthink": "~2.0.154",
     "@wenathlan/getry": "~2.0.155",
     "@wenathlan/saddle": "~2.0.155",
-    "@wenathlan/argan": "~2.0.155",
     "@wenathlan/vault": "~2.0.155",
     "better-sqlite3": "^13.0.3",
     "drizzle-orm": "^0.45.4",
@@ -364,22 +367,26 @@
     "zod": "^4.6.7"
   },
   "overrides": {
-    "esbuild": "^0.28.2",
+    "uuid": "^11.1.1",
     "deepmerge-ts": "^8.0.0",
+    "esbuild": "^0.28.2",
+    "follow-redirects": "^1.16.2",
+    "minimatch": "^11.0.3",
+    "glob": "^14.0.3",
     "mysql2": "^3.24.6",
-    "uuid": "^11.1.1",
     "postcss-selector-parser": "^7.1.6",
     "source-map-js": "1.2.2",
-    "katex": "^0.18.2",
     "proxy-addr": "2.0.8",
     "body-parser": "^2.4.0",
     "fast-uri": "^3.1.9",
-    "follow-redirects": "^1.16.2",
-    "minimatch": "^11.0.3",
-    "glob": "^14.0.3",
     "zod": "^4.6.7",
     "undici": "^7.30.1",
-    "shell-quote": "^1.11.0"
+    "katex": "^0.18.2",
+    "shell-quote": "^1.11.0",
+    "xcode": {
+      "uuid": "11.1.1"
+    },
+    "@grpc/grpc-js": "1.14.5"
   },
   "publishConfig": {
     "access": "public",

package/tests/gatewayversions.test.ts

@@ -0,0 +1,145 @@
+/**
+ * gatewayversions.test.ts — the data-driven route table of the gateway: the
+ * family seed counts (5 providers, 7 route kinds, 35 routes), the sqlite
+ * mirror rows the node runtime serves (seed-on-first-run, registration-safe
+ * upsert) and the thinking chain the gateway wires over the catalog rows
+ * 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
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, it } from "vitest";
+
+/* the db seat isolation law: DATABASE_URL is read at the db module eval, so
+ * the seat lands before the dynamic import below opens the mirror. */
+process.env.DATABASE_URL = `file:${join(mkdtempSync(join(tmpdir(), "gateway-versions-")), "route-table.test.db")}`;
+
+const db = await import("../db.ts");
+const { GATEWAYROUTES, GATEWAYVERSIONS, thinkingchain, totalroutes } = await import("../gateway.ts");
+
+afterAll(() => {
+  rmSync(join(process.env.DATABASE_URL!.slice("file:".length), ".."), { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// the family seed counts — the pr19 by-example law: 5 providers, 35 routes
+// ---------------------------------------------------------------------------
+
+describe("the family seed route table (5 providers, 35 routes)", () => {
+  it("carries the five provider gateways", () => {
+    assert.equal(GATEWAYVERSIONS.length, 5);
+    assert.deepEqual(
+      GATEWAYVERSIONS.map((version) => version.provider),
+      ["zai", "babel town", "nvidia nim", "opencode zen plus kilo", "openrouter"],
+    );
+  });
+
+  it("serves the seven OpenAI-compatible route kinds per gateway", () => {
+    assert.equal(GATEWAYROUTES.length, 7);
+    for (const version of GATEWAYVERSIONS) {
+      assert.deepEqual(version.routes, [...GATEWAYROUTES], `${version.v} carries the seven route kinds`);
+    }
+  });
+
+  it("totals the thirty-five routes the gateway serves", () => {
+    assert.equal(totalroutes(), 35);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// the sqlite mirror rows — instance rows live in the database
+// ---------------------------------------------------------------------------
+
+describe("the gateway_versions mirror (the data-driven route table)", () => {
+  it("seeds the five family rows on first use and answers them in version order", async () => {
+    const rows = await db.readgatewayversionrows();
+    assert.equal(rows.length, 5);
+    assert.deepEqual(
+      rows.map((row) => row.v),
+      ["v1", "v2", "v3", "v4", "v5"],
+    );
+    assert.equal(rows.reduce((sum, row) => sum + row.routes.length, 0), 35);
+    // the routes ride the json cell and parse back to the route kinds
+    assert.deepEqual(rows[0].routes, [...GATEWAYROUTES]);
+  });
+
+  it("keeps the seeding idempotent — a second pass lands nothing", async () => {
+    const seeded = await db.seedGatewayVersionRows();
+    assert.equal(seeded, 0);
+    assert.equal((await db.readgatewayversionrows()).length, 5);
+  });
+
+  it("writes and answers a registered row a later seed never overwrites", async () => {
+    const written = await db.savegatewayversion({
+      v: "v6",
+      provider: "a person registered gateway",
+      pattern: "registered through the internal api",
+      badge: "live",
+      models: "registered-model",
+      note: "the route table answers the registration, never a hardcoded row",
+      routes: ["chat/completions", "models"],
+    });
+    assert.equal(written?.provider, "a person registered gateway");
+    const rows = await db.readgatewayversionrows();
+    assert.equal(rows.length, 6);
+    const registered = rows.find((row) => row.v === "v6");
+    assert.deepEqual(registered?.routes, ["chat/completions", "models"]);
+    // the seed re-run respects the registration: v6 stays, nothing resets
+    assert.equal(await db.seedGatewayVersionRows(), 0);
+    assert.equal((await db.readgatewayversionrows()).find((row) => row.v === "v6")?.provider, "a person registered gateway");
+  });
+
+  it("falls back to the canonical route kinds when a routes cell arrives broken", async () => {
+    await db.savegatewayversion({
+      v: "v7",
+      provider: "broken cell gateway",
+      pattern: "a bad write never loses the routes",
+      badge: "paused",
+      models: "any",
+      note: "the projection keeps the family route kinds",
+      routes: [],
+    });
+    const rows = await db.readgatewayversionrows();
+    const broken = rows.find((row) => row.v === "v7");
+    assert.deepEqual(broken?.routes, [...GATEWAYROUTES]);
+    assert.equal(broken?.badge, "paused");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// the thinking chain over the catalog — the level routes the provider rows
+// ---------------------------------------------------------------------------
+
+describe("thinkingchain — the level-routed cross-provider chain over the catalog", () => {
+  it("orders the live providers first and the paused provider last", () => {
+    const chain = thinkingchain("max");
+    const order: string[] = [];
+    for (const candidate of chain) {
+      if (order[order.length - 1] !== candidate.provider) order.push(candidate.provider);
+    }
+    assert.deepEqual(order, ["zai", "nvidia nim", "opencode zen plus kilo", "openrouter", "babel town"]);
+  });
+
+  it("leads with the flagship tier for the maximum level and never serves a reasoning-false model", () => {
+    const chain = thinkingchain("max");
+    assert.equal(chain[0].provider, "zai");
+    assert.equal(chain[0].model.id, "glm-5.3");
+    for (const candidate of chain) {
+      assert.notEqual(candidate.model.reasoning, false, `${candidate.provider}/${candidate.model.id} never carries a thinking level`);
+    }
+    // the first nvidia candidate is the tier-1 rotation backend the v3 lane rides
+    const firstnvidia = chain.find((candidate) => candidate.provider === "nvidia nim");
+    assert.equal(firstnvidia?.model.id, "moonshotai/kimi-k3");
+  });
+
+  it("walks the strong tier first for the default high level", () => {
+    const chain = thinkingchain("high");
+    assert.equal(chain[0].model.id, "glm-5.1");
+    const ids = chain.slice(0, 4).map((candidate) => candidate.model.id);
+    assert.deepEqual(ids, ["glm-5.1", "glm-5v", "glm-5.3", "glm-5.3-flash"]);
+  });
+});

package/tests/keyrotation.test.ts

@@ -0,0 +1,129 @@
+/**
+ * keyrotation.test.ts — the provider key rotation over the ApiKeyRow pool:
+ * 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
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { type ApiKeyRow, maskkey, nextkeyrow, rotationsummary } from "../db.ts";
+
+/** the reference clock of the fixtures (a fixed epoch, no wall time). */
+const NOW = 1_800_000_000_000;
+
+/** Builds one key row fixture with every value the rotation reads. */
+function key(over: Partial<ApiKeyRow> & { id: string }): ApiKeyRow {
+  return {
+    provider: "nvidia",
+    key: `nvapi-fixed-${over.id.padStart(4, "0")}-credential-shape`,
+    label: `nim rotation ${over.id}`,
+    active: true,
+    status: "active",
+    useCount: 0,
+    rotationCount: 0,
+    errorCount: 0,
+    rateLimitHit: false,
+    createdAt: "2026-09-12T10:00:00.000Z",
+    expiresAt: null,
+    ...over,
+  };
+}
+
+describe("nextkeyrow — the health-aware round-robin of the key pool", () => {
+  it("walks the pool in stable order and wraps the cursor", () => {
+    const pool = [key({ id: "k1" }), key({ id: "k2" }), key({ id: "k3" })];
+    const walk: string[] = [];
+    let cursor = 0;
+    for (let step = 0; step < 5; step++) {
+      const pick = nextkeyrow(pool, cursor, NOW);
+      assert.ok(pick, "an eligible pool always answers");
+      walk.push(pick.row.id);
+      cursor = pick.cursor;
+    }
+    assert.deepEqual(walk, ["k1", "k2", "k3", "k1", "k2"]);
+  });
+
+  it("never answers a revoked, inactive or expired key", () => {
+    const pool = [
+      key({ id: "revoked", status: "revoked" }),
+      key({ id: "inactive", active: false }),
+      key({ id: "expired", expiresAt: "2026-01-01T00:00:00.000Z" }),
+      key({ id: "live" }),
+    ];
+    for (let cursor = 0; cursor < 4; cursor++) {
+      const pick = nextkeyrow(pool, cursor, NOW);
+      assert.ok(pick);
+      assert.equal(pick.row.id, "live");
+    }
+    assert.equal(nextkeyrow(pool.slice(0, 3), 0, NOW), null);
+  });
+
+  it("keeps an unparseable expiry honest — only a real parse retires a key", () => {
+    const pool = [key({ id: "odd", expiresAt: "not-a-date" }), key({ id: "live" })];
+    const walk: string[] = [];
+    let cursor = 0;
+    for (let step = 0; step < 4; step++) {
+      const pick = nextkeyrow(pool, cursor, NOW);
+      assert.ok(pick);
+      walk.push(pick.row.id);
+      cursor = pick.cursor;
+    }
+    assert.deepEqual(walk, ["odd", "live", "odd", "live"]);
+  });
+
+  it("leads with the healthy seats — an erroring or rate-limited key rides only when nothing healthy remains", () => {
+    const pool = [
+      key({ id: "healthy-a" }),
+      key({ id: "erroring", errorCount: 3 }),
+      key({ id: "ratelimited", rateLimitHit: true }),
+      key({ id: "healthy-b" }),
+    ];
+    const walk: string[] = [];
+    let cursor = 0;
+    for (let step = 0; step < 4; step++) {
+      const pick = nextkeyrow(pool, cursor, NOW);
+      assert.ok(pick);
+      walk.push(pick.row.id);
+      cursor = pick.cursor;
+    }
+    assert.deepEqual(walk, ["healthy-a", "healthy-b", "healthy-a", "healthy-b"]);
+    // every healthy seat out of the pool: the erroring seats take the walk
+    const degraded = [key({ id: "erroring", errorCount: 3 }), key({ id: "ratelimited", rateLimitHit: true })];
+    const fallback = nextkeyrow(degraded, 0, NOW);
+    assert.ok(fallback);
+    assert.equal(fallback.row.id, "erroring");
+    assert.equal(fallback.cursor, 1);
+  });
+
+  it("normalizes any cursor the caller persisted", () => {
+    const pool = [key({ id: "k1" }), key({ id: "k2" }), key({ id: "k3" })];
+    assert.equal(nextkeyrow(pool, -1, NOW)?.row.id, "k3");
+    assert.equal(nextkeyrow(pool, 7, NOW)?.row.id, "k2");
+  });
+
+  it("answers an empty pool with null, never a thrown rotation", () => {
+    assert.equal(nextkeyrow([], 0, NOW), null);
+  });
+});
+
+describe("the key render discipline — selection answers rows, rendering masks", () => {
+  it("masks every key shape the routes answer", () => {
+    const short = "nvapi-short";
+    assert.equal(maskkey(short), "nvap****");
+    const long = "nvapi-1234567890abcdef-ijklmnop";
+    assert.equal(maskkey(long), "nvapi-12****mnop");
+    const masked = maskkey(key({ id: "k9" }).key);
+    assert.ok(!masked.includes("credential-shape"), "the mask never carries the key body");
+  });
+
+  it("summarizes the per-provider rotation health the rail renders", () => {
+    const pool = [
+      key({ id: "k1" }),
+      key({ id: "k2", rotationCount: 18 }),
+      key({ id: "k3", errorCount: 2 }),
+      key({ id: "k4", status: "revoked" }),
+    ];
+    assert.deepEqual(rotationsummary(pool), { active: 3, rotating: 1, erroring: 1 });
+  });
+});

package/tests/routerotation.test.ts

@@ -12,8 +12,10 @@ import {
   notefailure,
   notesuccess,
   pickroute,
+  pickroundrobin,
   ROTATIONDEFAULTS,
   remainingcooldown,
+  rotatepool,
 } from "../routerotation.ts";
 
 /** the three-route pool the tests rotate over. */
@@ -95,3 +97,101 @@ describe("routerotation cooldown ledger", () => {
     assert.equal(healthyroutes(POOL, ledger, 1000).length, 3);
   });
 });
+
+// ---------------------------------------------------------------------------
+// round robin + the unified rotation entry (pr19: round-robin + weighted +
+// health-aware in one rotation math)
+// ---------------------------------------------------------------------------
+
+describe("routerotation round robin", () => {
+  it("walks the healthy pool in stable order and wraps the cursor", () => {
+    const ledger = newledger();
+    const walk: string[] = [];
+    let cursor = 0;
+    for (let step = 0; step < 7; step++) {
+      const pick = pickroundrobin(POOL, ledger, cursor, 1000);
+      assert.ok(pick, "a healthy pool always answers");
+      walk.push(pick.route.id);
+      cursor = pick.cursor;
+    }
+    assert.deepEqual(walk, ["r1", "r2", "r3", "r1", "r2", "r3", "r1"]);
+  });
+
+  it("gives every healthy route an equal share over a full cycle", () => {
+    const ledger = newledger();
+    const shares = new Map<string, number>([["r1", 0], ["r2", 0], ["r3", 0]]);
+    let cursor = 0;
+    for (let step = 0; step < 300; step++) {
+      const pick = pickroundrobin(POOL, ledger, cursor, 1000);
+      assert.ok(pick);
+      shares.set(pick.route.id, (shares.get(pick.route.id) ?? 0) + 1);
+      cursor = pick.cursor;
+    }
+    assert.equal(shares.get("r1"), 100);
+    assert.equal(shares.get("r2"), 100);
+    assert.equal(shares.get("r3"), 100);
+  });
+
+  it("stays health-aware: cooling and zero-weight routes leave the walk", () => {
+    const ledger = newledger();
+    notefailure(ledger, "r2", { allowedFails: 0 }, 1000);
+    const routes = [...POOL, { id: "r0", provider: "babeltown", model: "paused", weight: 0 }];
+    const walk: string[] = [];
+    let cursor = 0;
+    for (let step = 0; step < 4; step++) {
+      const pick = pickroundrobin(routes, ledger, cursor, 1000);
+      assert.ok(pick);
+      walk.push(pick.route.id);
+      cursor = pick.cursor;
+    }
+    assert.deepEqual(walk, ["r1", "r3", "r1", "r3"]);
+    // the cooldown expiry walks r2 back in: the cursor resumes over the
+    // restored three-route pool (0 → r1) and the very next pick reaches r2
+    const back = pickroundrobin(routes, ledger, cursor, 1000 + ROTATIONDEFAULTS.cooldownMs + 1);
+    assert.ok(back);
+    assert.equal(back.route.id, "r1");
+    const then = pickroundrobin(routes, ledger, back.cursor, 1000 + ROTATIONDEFAULTS.cooldownMs + 1);
+    assert.equal(then?.route.id, "r2");
+  });
+
+  it("answers null when every route cools down, whatever the cursor", () => {
+    const ledger = newledger();
+    for (const route of POOL) notefailure(ledger, route.id, { allowedFails: 0 }, 1000);
+    assert.equal(pickroundrobin(POOL, ledger, 0, 1000), null);
+    assert.equal(pickroundrobin(POOL, ledger, 41, 1000), null);
+  });
+
+  it("normalizes any cursor the caller persisted onto the healthy pool", () => {
+    const ledger = newledger();
+    assert.equal(pickroundrobin(POOL, ledger, -1, 1000)?.route.id, "r3");
+    assert.equal(pickroundrobin(POOL, ledger, 7, 1000)?.route.id, "r2");
+    assert.equal(pickroundrobin(POOL, ledger, 8, 1000)?.route.id, "r3");
+  });
+});
+
+describe("rotatepool — the unified rotation entry", () => {
+  it("defaults to the round-robin walk", () => {
+    const ledger = newledger();
+    const first = rotatepool({ routes: POOL, ledger, cursor: 0, now: 1000 });
+    const second = rotatepool({ routes: POOL, ledger, cursor: first?.cursor, now: 1000 });
+    assert.equal(first?.route.id, "r1");
+    assert.equal(second?.route.id, "r2");
+  });
+
+  it("answers the weighted draw under the weighted strategy (cursor untouched)", () => {
+    const ledger = newledger();
+    const pick = rotatepool({ routes: POOL, ledger, strategy: "weighted", cursor: 9, rand: () => 0, now: 1000 });
+    assert.equal(pick?.route.id, "r1");
+    assert.equal(pick?.cursor, 9);
+    // rand just below 1 lands on the last healthy route
+    const tail = rotatepool({ routes: POOL, ledger, strategy: "weighted", rand: () => 0.9999, now: 1000 });
+    assert.equal(tail?.route.id, "r3");
+  });
+
+  it("answers null under both strategies when nothing is healthy", () => {
+    const ledger = newledger();
+    for (const route of POOL) notefailure(ledger, route.id, { allowedFails: 0 }, 1000);
+    assert.equal(rotatepool({ routes: POOL, ledger, strategy: "round-robin", now: 1000 }), null);
+    assert.equal(rotatepool({ routes: POOL, ledger, strategy: "weighted", rand: () => 0, now: 1000 }), null);
+  });
+});

package/tests/thinkingladder.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULTTHINKINGLEVEL,
+  THINKINGLEVELS,
+  TWOCALLSTHRESHOLD,
+  type ThinkingLevelName,
+  budgetof,
+  clampbudget,
+  defaultthinkinglevel,
+  fallbackchain,
+  islevel,
+  lanesof,
+  listlevels,
+  providerchain,
+  type thinkingproviderrow,
+  providersserving,
+  registerthinkinglevels,
+  targettier,
+  twocallspattern,
+} from "../thinking.ts";
+import { autothinking } from "../utils.ts";
+
+// ---------------------------------------------------------------------------
+// the registerable ladder — the engine freedom law: levels depend on what
+// the person registers, never a fixed 7 (pr5)
+// ---------------------------------------------------------------------------
+
+describe("the thinking ladder registration (the engine freedom law)", () => {
+  it("answers the seven rung family seed when nothing is registered", () => {
+    expect(listlevels()).toEqual(THINKINGLEVELS);
+    expect(defaultthinkinglevel()).toBe(DEFAULTTHINKINGLEVEL);
+    expect(defaultthinkinglevel()).toBe("high");
+  });
+
+  it("accepts any count of registered rungs — more than seven rides", () => {
+    const twelve = Array.from({ length: 12 }, (_, i) => ({
+      level: `run${i}` as const,
+      budget: 1000 * (i + 1),
+      desc: `registered rung ${i}`,
+    }));
+    const live = registerthinkinglevels(twelve, { default: "run11" });
+    expect(live).toHaveLength(12);
+    expect(listlevels()).toHaveLength(12);
+    expect(islevel("run0")).toBe(true);
+    expect(islevel("run11")).toBe(true);
+    expect(islevel("high")).toBe(false);
+    expect(budgetof("run3")).toBe(4000);
+    expect(autothinking("RUN3")).toBe("run3");
+    expect(defaultthinkinglevel()).toBe("run11");
+    expect(autothinking("bogus")).toBe("run11");
+  });
+
+  it("accepts fewer rungs than seven — one rung rides", () => {
+    registerthinkinglevels([{ level: "deep", budget: 999999, desc: "the only rung" }], { default: "deep" });
+    expect(listlevels()).toHaveLength(1);
+    expect(budgetof("deep")).toBe(999999);
+    expect(autothinking("anything")).toBe("deep");
+  });
+
+  it("skips invalid entries and keeps the last duplicate", () => {
+    const live = registerthinkinglevels(
+      [
+        { level: "", budget: 5, desc: "nameless" },
+        { level: "solo", budget: 7, desc: "first" },
+        { level: "solo", budget: 9, desc: "last wins" },
+        { level: "negative", budget: -1, desc: "floors to zero" },
+      ],
+      { default: "solo" },
+    );
+    expect(live.map((rung) => rung.level)).toEqual(["solo", "negative"]);
+    expect(budgetof("solo")).toBe(9);
+    expect(budgetof("negative")).toBe(0);
+  });
+
+  it("an empty registration answers the ladder untouched", () => {
+    const before = listlevels();
+    expect(registerthinkinglevels([])).toEqual(before);
+  });
+
+  it("restores the family seed when the seed rides back", () => {
+    registerthinkinglevels(THINKINGLEVELS);
+    expect(listlevels()).toEqual(THINKINGLEVELS);
+    expect(islevel("high")).toBe(true);
+    expect(autothinking("maximum")).toBe("max");
+    expect(defaultthinkinglevel()).toBe("high");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// the thinking seat routing — the tier ladder, the budget clamp, the
+// two-calls verdict, the fallback chain, the lanes and the provider catalog
+// (the pr19 thinking seat: the level selects the model tier, the token
+// budget and the fallback chain — pure math, no gateway import)
+// ---------------------------------------------------------------------------
+
+describe("the thinking seat routing (the family seed ladder)", () => {
+  it("routes each seed rung to its model tier by ladder position", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    expect(targettier("none")).toBe(4);
+    expect(targettier("minimal")).toBe(4);
+    expect(targettier("low")).toBe(3);
+    expect(targettier("medium")).toBe(3);
+    expect(targettier("high")).toBe(2);
+    expect(targettier("xhigh")).toBe(1);
+    expect(targettier("max")).toBe(1);
+  });
+
+  it("routes an unknown level to the default rung's tier", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    expect(targettier("bogus" as ThinkingLevelName)).toBe(2);
+  });
+
+  it("clamps the level budget to the model output ceiling", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    expect(clampbudget("high")).toBe(68000);
+    expect(clampbudget("high", 16384)).toBe(16384);
+    expect(clampbudget("none", 16384)).toBe(0);
+    // a missing or invalid ceiling never clamps
+    expect(clampbudget("high", undefined)).toBe(68000);
+    expect(clampbudget("high", Number.NaN)).toBe(68000);
+    expect(clampbudget("high", -1)).toBe(68000);
+  });
+
+  it("answers the two-calls verdict the engine's zai lane always carried", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    // a thinking level always rides the pattern
+    expect(twocallspattern({ level: "minimal", responsemax: 0 })).toBe(true);
+    expect(twocallspattern({ level: "high", responsemax: 1 })).toBe(true);
+    // none rides the pattern only when the windows cross the threshold
+    expect(twocallspattern({ level: "none", responsemax: 1000 })).toBe(false);
+    expect(twocallspattern({ level: "none", responsemax: TWOCALLSTHRESHOLD + 1 })).toBe(true);
+    // a config threshold and a config budget override win
+    expect(twocallspattern({ level: "none", responsemax: 100, threshold: 50 })).toBe(true);
+    expect(twocallspattern({ level: "none", responsemax: 100, budget: TWOCALLSTHRESHOLD })).toBe(true);
+  });
+
+  it("orders the fallback chain by tier distance, budget fit, score and id", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    const chain = fallbackchain(
+      [
+        { id: "tier1-small", reasoning: true, maxoutput: 4096, rank: { score: 60, tier: 1 } },
+        { id: "tier2-a", reasoning: true, maxoutput: 131072, rank: { score: 40, tier: 2 } },
+        { id: "tier2-b", reasoning: true, maxoutput: 131072, rank: { score: 44, tier: 2 } },
+        { id: "tier1-big", reasoning: true, maxoutput: 131072, rank: { score: 55, tier: 1 } },
+        { id: "tier3", reasoning: true, maxoutput: 131072, rank: { score: 30, tier: 3 } },
+        { id: "unranked", reasoning: true, maxoutput: 131072 },
+        { id: "nonthinking", reasoning: false, maxoutput: 131072, rank: { score: 90, tier: 1 } },
+      ],
+      "high",
+    );
+    // level high targets tier 2: tier-2 rows first (score desc), then the
+    // tier-1 row that holds the full budget, then every remaining tier-1
+    // and tier-3 row by distance (fullfit before score — the small tier-1
+    // rides below the full-fit tier-3), the unranked row last; the
+    // reasoning-false row never serves
+    expect(chain.map((row) => row.id)).toEqual([
+      "tier2-b",
+      "tier2-a",
+      "tier1-big",
+      "tier3",
+      "tier1-small",
+      "unranked",
+    ]);
+    // the none level serves every row (no thinking budget to carry)
+    expect(fallbackchain([{ id: "nonthinking", reasoning: false }], "none")).toHaveLength(1);
+  });
+
+  it("resolves the session and stream lanes in bind order", () => {
+    expect(lanesof({})).toEqual([]);
+    expect(lanesof({ stream: false, sessionid: null })).toEqual([]);
+    expect(lanesof({ stream: true })).toEqual(["stream"]);
+    expect(lanesof({ sessionid: "chat-9f21" })).toEqual(["session"]);
+    expect(lanesof({ stream: true, sessionid: "chat-9f21" })).toEqual(["session", "stream"]);
+    expect(lanesof({ sessionid: "   " })).toEqual([]);
+  });
+
+  it("orders the provider chain live first and serves only capable catalogs", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    const catalog: thinkingproviderrow[] = [
+      { provider: "pausedone", badge: "paused", models: [{ id: "p1", reasoning: true, rank: { score: 50, tier: 2 } }] },
+      { provider: "liveone", badge: "live", models: [{ id: "l1", reasoning: true, rank: { score: 40, tier: 2 } }] },
+      { provider: "blind", badge: "live", models: [{ id: "b1", reasoning: false }] },
+    ];
+    expect(providersserving(catalog, "high").map((row) => row.provider)).toEqual(["liveone", "pausedone"]);
+    const chain = providerchain(catalog, "high");
+    expect(chain.map((candidate) => `${candidate.provider}/${candidate.model.id}`)).toEqual([
+      "liveone/l1",
+      "pausedone/p1",
+    ]);
+  });
+});
+
+describe("the thinking seat routing (a registered ladder)", () => {
+  it("routes the tier by position over any registered ladder length", () => {
+    registerthinkinglevels(
+      [
+        { level: "quick", budget: 100, desc: "registered floor" },
+        { level: "mid", budget: 900, desc: "registered middle" },
+        { level: "deep", budget: 90000, desc: "registered ceiling" },
+      ],
+      { default: "mid" },
+    );
+    expect(targettier("quick")).toBe(4);
+    expect(targettier("mid")).toBe(3);
+    expect(targettier("deep")).toBe(1);
+    expect(clampbudget("deep", 16384)).toBe(16384);
+  });
+
+  it("answers the ceiling a single-rung registration carries", () => {
+    registerthinkinglevels([{ level: "only", budget: 500, desc: "the only rung" }], { default: "only" });
+    expect(targettier("only")).toBe(1);
+    registerthinkinglevels([{ level: "off", budget: 0, desc: "no thinking at all" }], { default: "off" });
+    expect(targettier("off")).toBe(4);
+  });
+
+  it("restores the family seed for the suites that follow", () => {
+    registerthinkinglevels(THINKINGLEVELS, { default: "high" });
+    expect(listlevels()).toEqual(THINKINGLEVELS);
+    expect(targettier("high")).toBe(2);
+  });
+});