@wenathlan/getry 0.0.0-stage → 2.0.151

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# getry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI gateway. Five provider gateways (v1 zai, v2 babel, v3 nvidia, v4 opencode+kilo, v5 openrouter) serve 35 OpenAI-compatible routes with the 7-level thinking system, the session store and the key rotation; `schema.prisma` describes the database the gateway lanes consume. This folder receives the getry application per the complete tree.
+
+---
+
+# The Sol theme
+
+# Getry Sol
+
+Getry is the AI gateway application of the DevThink family: provider gateways, route maps, reasoning budgets, session contexts and key pools under one gateway shell. This Sol theme is its web surface — a Vite + React SPA whose home, versions, thinking and sessions routes render from the same database that `schema.prisma` describes.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+---
+
+# The family contract (wave 6-a)
+
+- `family.ts` — the single table of the eight siblings beside getry with the
+  spec §12 accent of each one; the shell rail foot and `tests/family.test.ts`
+  both consume this one table.
+- `familyurl.ts` — the verbatim relative-url contract (`"../" + slug + "/"`,
+  consolidated to the family variant) that keeps every cross-app link
+  mount-proof.
+- `restore:entry` — the entry-face guard: a no-op while `index.html` rides the
+  source face (`./App.tsx`), a restore from HEAD otherwise, and a refusal
+  (exit 1, nothing touched) while HEAD itself is not the source face. Run it
+  after any local `vite build` — the build rewrites the entry to the hashed
+  face by design.
+- The root build emits hashed bundles into the app folder (publish contract
+  `.`); `.gitignore` bars every hashed emit (`index-*`, `favicon-*`,
+  `manifest-*`, `icon-*`), so the tree keeps the source faces only.

package/docs/skills/gateway-deploy.md

@@ -0,0 +1,151 @@
+---
+name: gateway-deploy
+description: >-
+  SKILL oficial de deploy replicável das cópias de gateway DevThink (@devthink/ai)
+  no Z.ai. Use toda vez que abrir um chat novo e receber esta skill: baixa, descompacta,
+  coloca em src/, cadastra as 22 chaves NVIDIA no DB, faz o push e o usuário deploya
+  N cópias de gateway no Z.ai.
+triggers:
+  - "gateway deploy"
+  - "cópia de gateway"
+  - "devthink gateway"
+  - "neozips"
+  - "chaves nvidia"
+  - "deploy z.ai"
+---
+
+# SKILL — Deploy Replicável de Cópias de Gateway DevThink no Z.ai
+
+> Leia 100% deste documento antes de agir. Nada de improvisar: o código já está
+> pronto no repositório e no arquivo compactado. Sua tarefa é montar o ambiente,
+> registrar as chaves, validar as rotas e fazer o push. Sem parar o serviço.
+
+## 0. Contexto (leia em voz alta pro seu cérebro)
+
+| Item | Valor |
+|------|-------|
+| Plataforma | `@devthink/ai` — gateway multi-provider Next.js 16 (App Router) |
+| Versões de gateway | V1 (ZAI) · V2 (Babel, pausada → fallback V1) · V3 (NVIDIA NIM) · V4 (OpenCode+Kilo free) · V5 (Unified/OpenRouter) |
+| Rotas por versão | `chat/completions` `completions` `embeddings` `keys` `messages` `models` `responses` (7 × 5 = 35 rotas) |
+| Repo oficial | `wenathlan/gateway` (privado) — fonte da verdade, sempre `main` |
+| Endpoints Z.ai | `https://internal-api.z.ai/v1` (SDK base) · bypass V1: headers `X-Token` + `userId` diretos |
+| NVIDIA NIM | `https://integrate.api.nvidia.com/v1` — 22 chaves `nvapi-…` em rotação LRU |
+| DB | SQLite via Prisma 7 + `@prisma/adapter-libsql` (adapter recebe `{ url }` direto) |
+| Auth GitHub | Device flow `client_id 178c6fc778ccc68e1d6a` → `github.com/login/device` → token em `.github-token` |
+| Commits | SEMPRE como iakadion `174824991+iakadion@users.noreply.github.com` |
+
+## 1. When To Use
+
+| Trigger | Purpose | Detail | Rule |
+|---------|---------|--------|------|
+| "monta a gateway" | Ambiente do zero | clone → install → db → keys → dev | nunca localhost fixo, porta 3000 da sandbox |
+| "cadastra as chaves" | Registro NVIDIA | `bun run db:push` + `bun run keys:register` | 22 chaves ativas na tabela `ApiKey` |
+| "repara a gateway" | Rotas quebradas | comparar com `neogateway-src/` canônico | INLINE-PER-ROUTE: cada `route.ts` é single source of truth |
+| "nova cópia" | Réplicas no Z.ai | repita §2 na sandbox nova | cada cópia = DB próprio, mesmas rotas |
+| "push" | Publicar | bump de versão → commit → push `main` | painéis 0/0/0, workflows verdes |
+
+## 2. Fluxo de Montagem (executar nesta ordem EXATA)
+
+### 2.1 — Fonte A: repositório (preferida — já está tudo pronto)
+
+```bash
+cd /home/z/my-project
+git clone https://<token>@github.com/wenathlan/gateway.git gateway-clone
+# copiar o conteúdo pronto para o projeto da sandbox
+cp -r gateway-clone/src/app/v1 gateway-clone/src/app/v2 gateway-clone/src/app/v3 \
+      gateway-clone/src/app/v4 gateway-clone/src/app/v5 src/app/
+cp gateway-clone/src/app/page.tsx gateway-clone/src/app/layout.tsx gateway-clone/src/app/globals.css src/app/
+cp gateway-clone/src/lib/db.ts gateway-clone/src/lib/ui.ts src/lib/
+cp gateway-clone/prisma/schema.prisma gateway-clone/prisma.config.ts .
+cp -r gateway-clone/scripts .
+```
+
+### 2.2 — Fonte B: arquivo compactado (fallback — neozips do wormhole)
+
+```bash
+# 1. baixar via agent-browser (Chromium headless descriptografa sozinho via Service Worker)
+agent-browser open "https://wormhole.app/D72BW4#YFIAupAqpmd_ILpUbYvNAA"
+agent-browser snapshot -i   # achar botão "Download file" e clicar
+ls ~/Downloads/neozips.rar  # arquivo limpo (5.9MB→3.75GB conforme o link)
+
+# 2. extrair com UNRAR 7.x estático (unrar-free 0.3.1 NÃO suporta RAR5!)
+curl -sL https://www.rarlab.com/rar/rarlinux-x64-712.tar.gz | tar xz
+./rar/unrar x -o+ neozips.rar  # → 7 sub-rars
+# 3. extrair UM sub-rar por vez e APAGAR cada um após extrair (disco 10GB!)
+#    neodevthink(17MB) neopackages(50MB) neoimg(158MB) neoskills(175MB)
+#    neochatinterface(175MB) neogateway(511MB) neodocs(2.66GB — pule se apertado)
+# 4. neogateway é um repositório git cru: materialize com
+git --work-tree=/home/z/neo/neogateway-src checkout HEAD -- .
+```
+
+### 2.3 — Dependências e banco
+
+```bash
+bun install                       # ~9s
+bun run db:generate               # Prisma 7 client (driver adapters)
+bun run db:push                   # cria ChatMessage, ApiKey, SessionContext, TownKey
+bun run keys:register             # registra as 22 chaves NVIDIA → "total active nvidia keys: 22"
+```
+
+### 2.4 — Segurança das chaves
+
+| Regra | Detalhe |
+|-------|---------|
+| Fonte das chaves | `nvidia/nvidia-keys.json` (22 entradas `nvapi-…`) do repo privado `wenathlan/gateway` (fonte original: histórico git do neogateway); template de formato disponível no histórico do repo privado |
+| Repo privado | `wenathlan/gateway` é privado → chaves podem viajar nele |
+| Repo público | NUNCA commitar chaves: `.gitignore` antes de qualquer push público |
+| `.env` | `DATABASE_URL=file:/home/z/my-project/db/custom.db` (SQLite local) |
+
+### 2.5 — Validação (tudo verde ou não acabou)
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/              # 200
+curl -s http://localhost:3000/v3/keys | head -c 200                        # 22 chaves mascaradas
+curl -s http://localhost:3000/v1/models | head -c 200                      # devthink meta-model
+curl -s -X POST http://localhost:3000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"glm-5.3-flash","messages":[{"role":"user","content":"ping"}],"max_tokens":20}'
+# → resposta com usage + session_id = V1 VIVA
+```
+
+## 3. Deploy de N Cópias no Z.ai
+
+1. Push em `wenathlan/gateway` (main) com o bump de versão.
+2. Em cada chat novo da sandbox Z.ai: cole esta skill → o agente executa §2 → cada sandbox vira uma cópia de gateway independente (DB próprio).
+3. Réplica V1 precisa dos headers `X-Token` + `userId` (bypass do SDK compartilhado). V2–V5 funcionam fora da sandbox.
+4. Domínios gerados: `https://<sandbox-id>.space-z.ai/` — as 35 rotas ficam disponíveis imediatamente.
+
+## 4. Autenticação GitHub (se o token não existir)
+
+```bash
+# gera código de device flow (expira em 15 min — mostre ao usuário, NUNCA pare o serviço)
+curl -s -X POST https://github.com/login/device/code -H "Accept: application/json" \
+  -d "client_id=178c6fc778ccc68e1d6a&scope=repo,workflow,read:org,user"
+# usuário autoriza em https://github.com/login/device
+# poller troca device_code por access_token → salva em .github-token (chmod 600)
+# regra 45: NUNCA re-pollar após AUTHORIZED
+```
+
+## 5. Checklist Final (10 pontos)
+
+- [ ] 35 rotas V1–V5 presentes em `src/app/v{1..5}/`
+- [ ] `prisma/schema.prisma` com ChatMessage + ApiKey + SessionContext + TownKey
+- [ ] `bun run db:push` verde
+- [ ] `bun run keys:register` → 22 chaves ativas
+- [ ] `/v1/chat/completions` responde com `session_id` + `usage`
+- [ ] `/v3/keys` lista 22 chaves mascaradas
+- [ ] `.github-token` com chmod 600 (não commitar!)
+- [ ] Commits assinados como iakadion
+- [ ] Worklog do sandbox atualizado (`worklog.md` — append, nunca overwrite)
+- [ ] Push em `wenathlan/gateway` main → usuário deploya as cópias
+
+## 6. Armadilhas conhecidas (leia 2x)
+
+1. **unrar-free 0.3.1 não abre RAR5** — use o binário estático 7.12 da rarlab.
+2. **Processos background morrem entre tool calls** — use double-fork: `( setsid nohup CMD & )` → PPID 1.
+3. **wormhole expira em 24h/100 downloads** — prefira Fonte A (repo).
+4. **Prisma `latest` = 8.0.0-rc** — PIN em `7.10.0` (tag `prev`).
+5. **Modelos NVIDIA EOL** — 410 Gone; liste com `GET /v1/models` e use nomes completos (`deepseek-ai/deepseek-v4.1-flash`).
+6. **Babel.town 503** — V2 deve cair para V1 automaticamente.
+7. **Streaming V3** — SessionStreamManager + circuit breaker 8 err/60s; timeout do cliente ≥ 120s.
+8. **`.next` grande** — apague antes de builds pesados se o disco estiver >80%.

package/docs/skills/gateway.md

@@ -0,0 +1,42 @@
+---
+name: gateway
+description: Publish the Getry gateway and the family deployable clones in any sandbox, starting from the release asset archive
+---
+
+# Gateway skill
+
+This skill publishes the gateway application (Getry) and serves the three deployable clones the same way (vault, forge, foundry). The flow is deterministic: the same steps, in the same order, on every publication.
+
+## Models
+
+| Model | Where it runs | How it is born |
+| --- | --- | --- |
+| Getry (standard) | inside the Z.AI sandbox | the release asset archive, already in Next shape with src |
+| Getry Next bypass | outside Z.AI (Vercel, Netlify, GitHub Pages, Caddy or any host) | the workflow Next conversion over the single Getry folder — no sandbox SDK, no captcha, no session, no chat ID, no dist folder, no public folder and none of the folders the platform usually creates; it is not a new application and does not duplicate a folder |
+
+## The four next shapes of every site
+
+The release assets carry the complete site archive plus FOUR next archives of every site, each packed as tar.xz at the maximum xz level with the Brotli overlay riding on top. Try them in this order:
+
+| Shape | What it is | When to use it |
+| --- | --- | --- |
+| next personalized | the house tree one hundred percent personalized: no src, the app/ bridge at the root beside the theme folder | first choice — try it before anything else, it is already in the assets |
+| next zai | the standard template the Z.AI platform accepts, riding the gateway skill, the prisma schema and the deploy map | when the platform refuses the personalized root |
+| next fifty | the same standard shape with the forbidden folders blocked (no public, no dist, no assets, no build, no deploy) and the deploy reading the root | when the platform wants the standard shape but must never carry the forbidden folders |
+| next normal | the plain standard template with no folder blocking: the Next defaults answer every platform | last resort — the platforms that accept nothing custom |
+
+Every shape carries the platform file set at its root (.npmrc, .nvmrc, biome, tsconfig, vercel, netlify, wrangler, the dev vars example, the manifest), and every shape must serve any deploy platform.
+
+## The four steps
+
+1. Download the asset archive — pick the shape by the order above (the personalized first, then the zai, then the fifty, then the normal). For the Z.AI sandbox use the next archive of the gateway; the other platforms read the same archives, because the conversion already puts the project in src.
+2. Extract the archive at the sandbox root — nothing may stay nested: the package.json must sit at the root.
+3. Push to the DB — with the Prisma schema in hand, run the migration (for example, `bunx prisma db push`) and confirm the tables; the builds and the data of the person stay recorded in this DB, and the backups rise to the DB sites and to the DB+sandbox site.
+4. Build the Next — install the dependencies locked in the lockfile and run the build; the publish button of the platform finishes with the name the person chooses.
+
+## Flow rules
+
+- Nothing is hardcoded: no host, no credential, no key in the code; every configuration comes from environment variables (the .dev.vars file in wrangler dev, and the host variables in the deploy).
+- The src folder is the only accepted exception to the root without src, and it exists because Next demands it; the house tree (correlated logic at the root, the theme folder with a single CSS beside the App.tsx anchor, the pages as folders with loose components) keeps holding inside it.
+- The personalized shape inverts the exception: the app/ directory sits at the root and the src folder does not exist.
+- Each sandbox publishes its own way, and the communication between the sites uses mime-types and HTTPS.

package/package.json

@@ -1,6 +1,180 @@
 {
   "name": "@wenathlan/getry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.151",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
+  "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",
+    "gateway",
+    "ai",
+    "api",
+    "llm",
+    "proxy",
+    "openai-compatible",
+    "documentation"
+  ],
+  "license": "GPL-3.0-only",
+  "engines": {
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": ">=26.12.1 <27",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
+  },
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host",
+    "build": "vite build",
+    "start": "vite preview --host",
+    "preview": "vite preview --host",
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Bricolage\\+Grotesque[\\s\\S]*Outfit[\\s\\S]*JetBrains\\+Mono/;const face=(h)=>script.test(h)&&triad.test(h);if(face(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}if(!face(execSync('git show HEAD:./index.html',{encoding:'utf8'}))){console.error('refusing: HEAD index.html is not the canonical source face yet (script App.tsx + the font triad) - land the source-face fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\""
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.5",
+    "@prisma/adapter-libsql": "^7.10.1",
+    "hono": "^4.13.13",
+    "ink": "^7.1.1",
+    "react-devtools-core": "^8.0.0",
+    "z-ai-web-dev-sdk": "^0.0.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.3",
+    "@capacitor/android": "^8.5.3",
+    "@capacitor/cli": "^8.5.3",
+    "@capacitor/core": "^8.5.3",
+    "@capacitor/ios": "^8.5.3",
+    "@fluentui/react-icons": "^2.0.344",
+    "@hookform/resolvers": "^5.9.2",
+    "@libsql/client": "^0.18.0",
+    "@opencode-ai/sdk": "^1.19.4",
+    "@prisma/client": "^7.10.1",
+    "@radix-ui/react-accordion": "^1.3.1",
+    "@radix-ui/react-alert-dialog": "^1.2.1",
+    "@radix-ui/react-aspect-ratio": "^1.2.0",
+    "@radix-ui/react-avatar": "^1.3.1",
+    "@radix-ui/react-checkbox": "^1.4.1",
+    "@radix-ui/react-collapsible": "^1.2.1",
+    "@radix-ui/react-context-menu": "^2.4.1",
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-dropdown-menu": "^2.2.1",
+    "@radix-ui/react-hover-card": "^1.2.1",
+    "@radix-ui/react-label": "^2.1.17",
+    "@radix-ui/react-menubar": "^1.2.1",
+    "@radix-ui/react-navigation-menu": "^1.4.1",
+    "@radix-ui/react-popover": "^1.3.1",
+    "@radix-ui/react-progress": "^1.2.1",
+    "@radix-ui/react-radio-group": "^1.5.1",
+    "@radix-ui/react-scroll-area": "^1.4.0",
+    "@radix-ui/react-select": "^2.4.1",
+    "@radix-ui/react-separator": "^1.2.0",
+    "@radix-ui/react-slider": "^1.6.1",
+    "@radix-ui/react-slot": "^1.5.0",
+    "@radix-ui/react-switch": "^1.4.1",
+    "@radix-ui/react-tabs": "^1.2.1",
+    "@radix-ui/react-toggle": "^1.2.1",
+    "@radix-ui/react-toggle-group": "^1.2.1",
+    "@radix-ui/react-tooltip": "^1.4.1",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tsconfig/node26": "^26.0.1",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/chrome": "^0.3.6",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "add": "^2.0.9",
+    "autoprefixer": "^10.6.1",
+    "axios": "^1.20.0",
+    "better-sqlite3": "^13.0.3",
+    "bun-types": "^1.4.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.4",
+    "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.28.2",
+    "express": "^5.3.0",
+    "fast-check": "^4.10.2",
+    "framer-motion": "^13.5.1",
+    "input-otp": "^1.5.0",
+    "lucide-react": "^1.61.0",
+    "mysql2": "^3.24.6",
+    "nanoid": "^6.0.2",
+    "next-themes": "^0.4.6",
+    "pnpm": "^12.15.0",
+    "postcss": "^8.5.31",
+    "prettier": "^3.9.10",
+    "prisma": "^7.10.1",
+    "react": "^19.3.1",
+    "react-day-picker": "^10.0.2",
+    "react-dom": "^19.3.1",
+    "react-hook-form": "^7.91.0",
+    "react-resizable-panels": "^4.15.0",
+    "recharts": "^3.10.1",
+    "sonner": "^2.0.8",
+    "streamdown": "^2.7.1",
+    "tailwind-merge": "^3.7.0",
+    "tailwindcss": "^4.3.3",
+    "tailwindcss-animate": "^1.0.7",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^7.0.2",
+    "vaul": "^1.1.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "wouter": "^3.13.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "files": [
+    "README.md",
+    "docs",
+    "tests"
+  ],
+  "homepage": "https://github.com/wenathlan/devthink/tree/main/getry",
+  "bugs": {
+    "url": "https://github.com/wenathlan/devthink/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@12.3.4",
+  "overrides": {
+    "esbuild": "^0.28.2",
+    "deepmerge-ts": "^8.0.0",
+    "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.1",
+    "zod": "^4.6.7",
+    "undici": "^7.30.1"
+  }
+}

package/tests/database-runtime-build.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/../.zscripts" && pwd)"
+TEST_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TEST_ROOT"' EXIT
+
+FAKE_BIN="$TEST_ROOT/bin"
+mkdir -p "$FAKE_BIN"
+cat >"$FAKE_BIN/bun" <<'EOF'
+#!/bin/bash
+set -euo pipefail
+
+if [ "$#" -ne 2 ] || [ "$1" != "run" ] || [ "$2" != "db:push" ]; then
+    echo "unexpected bun invocation: $*" >&2
+    exit 1
+fi
+
+case "${DATABASE_URL:-}" in
+    file:*) db_path="${DATABASE_URL#file:}" ;;
+    *)
+        echo "DATABASE_URL must be an absolute SQLite file URL" >&2
+        exit 1
+        ;;
+esac
+
+case "$db_path" in
+    /*) ;;
+    *)
+        echo "database path must be absolute: $db_path" >&2
+        exit 1
+        ;;
+esac
+
+mkdir -p "$(dirname "$db_path")"
+if [ ! -f "$db_path" ]; then
+    printf 'initialized\n' >"$db_path"
+fi
+printf '%s\n' "$DATABASE_URL" >>"${DB_PUSH_CALLS:?}"
+EOF
+chmod +x "$FAKE_BIN/bun"
+
+export PATH="$FAKE_BIN:$PATH"
+export DB_PUSH_CALLS="$TEST_ROOT/db-push-calls"
+
+# 没有 Preview 数据库时，应只在部署产物中初始化空库，不修改项目目录。
+EMPTY_PROJECT="$TEST_ROOT/empty-project"
+EMPTY_BUILD="$TEST_ROOT/empty-build"
+mkdir -p "$EMPTY_PROJECT"
+
+PROJECT_DIR="$EMPTY_PROJECT" BUILD_DIR="$EMPTY_BUILD" \
+    bash "$SCRIPT_DIR/database-runtime-build.sh"
+
+test -f "$EMPTY_BUILD/db/custom.db"
+test "$(cat "$EMPTY_BUILD/db/custom.db")" = "initialized"
+test ! -e "$EMPTY_PROJECT/db/custom.db"
+
+# 有 Preview 数据库时，应保留数据和同目录文件，再对产物执行 schema 同步。
+EXISTING_PROJECT="$TEST_ROOT/existing-project"
+EXISTING_BUILD="$TEST_ROOT/existing-build"
+mkdir -p "$EXISTING_PROJECT/db"
+printf 'preview-data\n' >"$EXISTING_PROJECT/db/custom.db"
+printf 'sidecar\n' >"$EXISTING_PROJECT/db/README.txt"
+
+PROJECT_DIR="$EXISTING_PROJECT" BUILD_DIR="$EXISTING_BUILD" \
+    bash "$SCRIPT_DIR/database-runtime-build.sh"
+
+test "$(cat "$EXISTING_BUILD/db/custom.db")" = "preview-data"
+test "$(cat "$EXISTING_BUILD/db/README.txt")" = "sidecar"
+test "$(wc -l <"$DB_PUSH_CALLS" | tr -d ' ')" = "2"
+grep -Fx "file:$EMPTY_BUILD/db/custom.db" "$DB_PUSH_CALLS"
+grep -Fx "file:$EXISTING_BUILD/db/custom.db" "$DB_PUSH_CALLS"
+
+echo "database runtime build tests passed"

package/tests/design.test.ts

@@ -0,0 +1,265 @@
+// # design.test — the design contract of the getry surface (the reform wave),
+// runnable with the vitest runner:
+//   pnpm test
+// The file reads the shipped sources (stylesheet, entry face, brand mark,
+// theme anchor, page anchors, prisma schema, db layer) and pins the reform:
+// the devthink foundation (mica #202020 over the 8-step ladder #242424→
+// #494949, Inter Variable + Geist Mono, the 13px/450 body, the trylle shadow
+// ladder), the windows hands (press .7 pins, dtPopIntro, the win11
+// scrollbar), the two-accent contract (the getry violet identity beside the
+// windows accent), the FAMILY STANDALONE LAW (the shell answers the direct
+// url full-bleed, the window chrome lives only inside the os embed), the
+// entry-flow law (intro → onboarding → the platform over the catalogued seen
+// state) and the banned list (no pill, no all-properties transition, no
+// scale(0) outside the pin law, no banned hue, no build ghost). The sources
+// are read as text — no browser, no DOM.
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+function read(path: string): string {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const CSS = read("../Sol/sol.css");
+const ENTRY = read("../index.html");
+const MARK = read("../Sol/widgets/ShellBrandmark.tsx");
+const SHELL = read("../Sol/shell/Shell.tsx");
+const SOL = read("../Sol/Sol.tsx");
+const HOME = read("../Sol/home/home.tsx");
+const GATE = read("../Sol/widgets/HomeEntrygate.tsx");
+const INTRO = read("../Sol/intro/intro.tsx");
+const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+const STATE = read("../onboardingstate.ts");
+const DB = read("../db.ts");
+const SCHEMA = read("../schema.prisma");
+const TOML = read("../devthink.toml");
+const FAVICON = read("../favicon.svg");
+const ICON = read("../icon.svg");
+const MANIFEST = read("../manifest.webmanifest");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i];
+
+/** Strips comments so the guards read rules, not the doctrine prose. */
+function rules(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** The stylesheet with the windows pin law lifted out (the one lawful scale(0)). */
+function withoutPinLaw(source: string): string {
+  return rules(source).replace(/@keyframes dtPopIntro \{(?:[^{}]|\{[^}]*\})*\}/g, "");
+}
+
+describe("design contract — the devthink foundation", () => {
+  it("keeps the mica canvas and the surface ladder", () => {
+    expect(CSS).toContain("--sol-canvas: var(--color-canvas)");
+    expect(CSS).toContain("--color-canvas: #202020");
+    expect(CSS).toContain("--sol-canvas-deep: var(--color-deep)");
+    expect(CSS).toContain("--surface-1: var(--color-s0)");
+    expect(CSS).toContain("--color-s0: #242424");
+    expect(CSS).toContain("--surface-8: var(--color-s7)");
+    expect(CSS).toContain("--color-s7: #494949");
+    expect(CSS).toContain("--mica: #202020 radial-gradient(#1a1f35 25%, #202020 100%) no-repeat fixed");
+  });
+
+  it("keeps the trylle type stacks (Inter Variable · Geist Mono) and the 13px/450 body", () => {
+    expect(CSS).toContain('"Inter Variable"');
+    expect(CSS).toContain('"Geist Mono Variable"');
+    expect(rules(CSS)).toContain("font-size: 13px");
+    expect(rules(CSS)).toContain("font-weight: 450");
+    expect(CSS).toContain("--sol-track-display: -0.02em");
+    expect(CSS).toContain("--sol-track-label: 0.14em");
+    expect(ENTRY).toMatch(/family=Inter/);
+    expect(ENTRY).toMatch(/Geist\+Mono/);
+  });
+
+  it("keeps the devthink shadow ladder and the fluent window float", () => {
+    expect(CSS).toContain("0 96px 96px -48px");
+    expect(CSS).toContain("--shadow-window: 0 32px 64px rgb(0 0 0 / 24%), 0 0 8px rgb(0 0 0 / 20%)");
+    expect(CSS).toContain("--ease-window: cubic-bezier(0.85, 0.14, 0.14, 0.85)");
+    // the sol aliases ride the underlying motion tokens — both stay pinned
+    expect(CSS).toContain("--sol-micro: var(--dur-1)");
+    expect(CSS).toContain("--dur-1: 150ms");
+    expect(CSS).toContain("--sol-ease-out: var(--ease-micro)");
+    expect(CSS).toContain("--ease-micro: cubic-bezier(0.22, 1, 0.36, 1)");
+  });
+
+  it("keeps the trylle button tone stack (the real site recipe)", () => {
+    expect(CSS).toContain("inset 0 1.2px 0 0 rgb(255 255 255 / 45%)");
+    expect(CSS).toContain("inset 0 8px 14px -6px rgb(255 255 255 / 22%)");
+  });
+
+  it("keeps the two-accent contract (the getry violet identity beside the windows accent)", () => {
+    expect(CSS).toContain("--violet-500: #8b5cf6");
+    expect(CSS).toContain("--accent: var(--violet-500)");
+    expect(CSS).toContain("--win-accent: var(--color-win)");
+    expect(CSS).toContain("--color-win: #4cc2ff");
+    expect(CSS).toContain("--focus: var(--color-win)");
+    expect(MARK).toContain("#8b5cf6");
+  });
+
+  it("ships no banned hue in the stylesheet, the entry, the mark or the icons", () => {
+    for (const source of [CSS, ENTRY, MARK, FAVICON, ICON, MANIFEST]) {
+      for (const banned of BANNED) {
+        expect(banned.test(source), `banned hue ${banned} found`).toBe(false);
+      }
+    }
+    expect(CSS.includes("#60a5fa"), "the residual sky retired").toBe(false);
+  });
+});
+
+describe("design contract — the windows hands", () => {
+  it("pops the pins with the windows bounce (the one lawful scale(0))", () => {
+    const pin = rules(CSS).match(/@keyframes dtPopIntro \{(?:[^{}]|\{[^}]*\})*\}/);
+    expect(pin, "the dtPopIntro keyframe is missing").not.toBeNull();
+    expect(pin?.[0]).toContain("scale(1.125)");
+    expect(pin?.[0]).toContain("scale(0.725)");
+    expect(/scale\(0\)/.test(withoutPinLaw(CSS)), "a scale(0) entry rides outside dtPopIntro").toBe(false);
+  });
+
+  it("presses the pins and the icon buttons at scale .7 on 100ms", () => {
+    expect(rules(CSS)).toContain(".railnav__item:active { transform: scale(0.7); }");
+    expect(rules(CSS)).toContain(".winapp__theme:active { transform: scale(0.7); }");
+    expect(CSS).toContain("--dur-press: 100ms");
+  });
+
+  it("answers the direct url full-bleed — the window chrome lives only inside the os", () => {
+    /* the family standalone law: an app accessed by its own url is the
+    normal application, one hundred percent — the shell renders
+    shell--standalone with no window chrome of its own (no title bar, no
+    captions, no resize handles, no inactive law, no entry scale), while
+    the framed contract keeps the bare stage for the os power clip */
+    expect(SHELL).toContain("shell--standalone");
+    expect(SHELL).toContain("shell--embedded");
+    expect(SHELL).not.toMatch(
+      /className="appframe"|winapp__title|winapp__cap|winapp__rz|winchip|setPointerCapture|data-inactive|RESIZE_EDGES/,
+    );
+    expect(CSS).toMatch(/\.shell--standalone \{[^}]*height: 100vh/);
+  });
+
+  it("rides the win11 scrollbar beside the standalone stage", () => {
+    expect(CSS).toContain("*:hover::-webkit-scrollbar-thumb");
+  });
+
+  it("pins the footer to the window floor (the sticky-footer law)", () => {
+    expect(CSS).toMatch(/\.winapp__stage > main\.shell \{[^}]*flex-direction: column/);
+    expect(CSS).toMatch(/\.r3-quad \{[^}]*margin: auto/);
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    expect(CSS).toContain("font-variant-numeric: tabular-nums");
+  });
+});
+
+describe("design contract — the banned list", () => {
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    expect(CSS.includes("999px"), "the pill radius is retired").toBe(false);
+  });
+
+  it("never ships an all-properties transition", () => {
+    expect(/transition:\s*all/.test(rules(CSS)), "transition: all is a reprovação").toBe(false);
+  });
+});
+
+describe("design contract — the guards", () => {
+  it("carries the reduced-motion hard stop as the last word", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    expect(blocks.length >= 1, "the universal hard stop is missing").toBe(true);
+    expect(CSS).toMatch(
+      /@media \(prefers-reduced-motion: reduce\) \{\s*\*,\s*\*::before,\s*\*::after \{[^}]*animation-duration: 0\.01ms !important/,
+    );
+    const lastBlock = CSS.lastIndexOf("@media");
+    const hardStop = CSS.lastIndexOf("@media (prefers-reduced-motion: reduce)");
+    expect(lastBlock, "a media block rides after the reduced-motion stop").toBe(hardStop);
+  });
+
+  it("mirrors the media kills into the in-session data-motion switch", () => {
+    expect(CSS.includes('[data-motion="reduced"]'), "the settings switch has no stylesheet guards").toBe(true);
+    expect(CSS).toMatch(
+      /\[data-motion="reduced"\] \*,\s*\[data-motion="reduced"\] \*::before,\s*\[data-motion="reduced"\] \*::after \{[^}]*animation-duration: 0\.01ms !important/,
+    );
+  });
+
+  it("carries the reduced-transparency floors", () => {
+    const floors = CSS.match(/@media \(prefers-reduced-transparency: reduce\)/g) ?? [];
+    expect(floors.length >= 1, "the transparency floors are missing").toBe(true);
+    expect(CSS).toContain("backdrop-filter: none");
+  });
+});
+
+describe("flow contract — intro → onboarding → the platform", () => {
+  it("mounts every route of the application (entry flow before the fundamentals)", () => {
+    expect(TOML).toMatch(/pages = \["home", "versions", "thinking", "sessions", "notfound"\]/);
+    for (const route of ['"/intro"', '"/onboarding"', '"/versions"', '"/thinking"', '"/sessions"', '"/404"']) {
+      expect(SOL.includes(`path=${route}`), `route ${route} must mount`).toBe(true);
+    }
+  });
+
+  it("gates the home anchor on the seen state before anything shows", () => {
+    /* the widget surface law: the dotted widget name is written exactly
+    once (inside Sol/widgets/index.ts) and the page answers the surface
+    import with its canonical alias — never the dotted path again */
+    expect(HOME).toMatch(/import \{ HomeEntrygate as EntryGate \} from "\.\.\/widgets"/);
+    expect(GATE).toContain('navigate("/intro", { replace: true })');
+    expect(GATE).toContain('navigate("/onboarding", { replace: true })');
+    expect(GATE).toContain("flowthrough");
+  });
+
+  it("hands the intro directly to the onboarding and marks it seen", () => {
+    expect(INTRO).toMatch(/from "\.\.\/\.\.\/onboardingstate\.ts"/);
+    expect(INTRO).toContain("markIntroSeen()");
+    expect(INTRO).toContain('"/onboarding"');
+    expect(INTRO).not.toContain("sessionStorage");
+  });
+
+  it("marks the onboarding seen on finish and skip alike", () => {
+    expect(ONBOARDING).toContain("markOnboardingSeen()");
+    expect(ONBOARDING).toContain('className="winonboard__skip"');
+    expect(ONBOARDING).toContain('navigate("/")');
+  });
+
+  it("consults the platform database over https with the host law", () => {
+    expect(STATE).toContain("VITE_ONBOARDING_URL");
+    expect(STATE).toContain("hostallowed");
+    expect(STATE).toContain("getry.onboarding.seen");
+    expect(STATE).toContain("mergeStage");
+  });
+});
+
+describe("db contract — the seen state catalogued", () => {
+  it("declares the OnboardingState kind on the prisma schema", () => {
+    expect(SCHEMA).toMatch(/model OnboardingState \{/);
+    expect(SCHEMA).toMatch(/visitor\s+String\s+@unique/);
+    expect(SCHEMA).toMatch(/introseen\s+Boolean\s+@default\(false\)/);
+    expect(SCHEMA).toMatch(/onboardingseen\s+Boolean\s+@default\(false\)/);
+  });
+
+  it("mirrors the kind on the sqlite layer with prepared statements only", () => {
+    expect(DB).toContain("CREATE TABLE IF NOT EXISTS onboarding_states");
+    expect(DB).toContain("export async function getonboardingstate");
+    expect(DB).toContain("export async function setonboardingstage");
+    expect(DB).toContain("ON CONFLICT(visitor) DO UPDATE SET");
+    expect(DB).toContain("DATABASE_URL");
+    // never concatenated SQL: the upsert binds every value
+    expect(DB).not.toMatch(/VALUES \(\$\{/);
+  });
+
+  it("keeps the session seeds and the https accessors of the static build", () => {
+    expect(DB).toContain("export async function listkeys");
+    expect(DB).toContain("export async function listmessages");
+    expect(DB).toContain("KEYSEED");
+  });
+});
+
+describe("entry contract — the source face", () => {
+  it("keeps the entry on the source face (./App.tsx, canonical assets, no hashed ghosts)", () => {
+    expect(ENTRY).toMatch(/script[^>]*\.\/App\.tsx/);
+    expect(/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry").toBe(false);
+    expect(ENTRY).toMatch(/href="\.\/favicon\.svg"/);
+    expect(ENTRY).toMatch(/href="\.\/manifest\.webmanifest"/);
+  });
+
+  it("renders the family row on the landing footer through the familyurl contract", () => {
+    expect(HOME).toMatch(/familyrow\(\)/);
+    expect(HOME).toMatch(/familyurl\(member\.slug\)/);
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,90 @@
+// # family.test — the family table the chrome rides, runnable with the
+// vitest runner:
+//   pnpm test
+// Every test watches the promise the row makes: the eight siblings beside
+// getry are listed once, every slug resolves through the familyurl contract
+// into a climb-one-level url, every member carries the spec §12 accent with
+// its own dot ink, and no accent ever collides with the banned palette.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the eight siblings beside getry, never getry itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, [
+      "argan",
+      "cadria",
+      "debonair",
+      "forge",
+      "foundry",
+      "saddle",
+      "stealthhead",
+      "vault",
+    ]);
+    assert.ok(!FAMILY_SLUGS.includes("getry"));
+    assert.ok(!FAMILY_SLUGS.includes("devthink"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-f]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-f]{6}$/);
+    }
+    // the table holds exactly the siblings — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [...FAMILY_SLUGS].sort());
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("strips decorative slashes and keeps the body verbatim across apps", () => {
+    assert.equal(familyurl("/argan/"), "../argan/");
+    // the consolidated body: plain concatenation, the family variant A
+    assert.equal(familyurl.toString().includes('"../" +'), true);
+  });
+
+  it("keeps the spec §12 accents stable", () => {
+    assert.equal(FAMILY_ACCENTS.argan.accent, "#34d8a8");
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.debonair.accent, "#d9962e");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("never ships a banned hue in the row", () => {
+    for (const member of familyrow()) {
+      assert.ok(!BANNED.has(member.accent), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+
+  it("keeps every dot ink readable on its own accent (the ink is darker)", () => {
+    for (const member of familyrow()) {
+      const lum = (hex: string): number => {
+        const channel = (offset: number) => Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+        return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+      };
+      assert.ok(lum(member.dotInk) < lum(member.accent), `${member.slug} dot ink must be darker than its accent`);
+    }
+  });
+});

package/tests/onboardingstate.test.ts

@@ -0,0 +1,68 @@
+// # 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
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { hostallowed, mergeStage } from "../onboardingstate.ts";
+
+describe("onboarding state", () => {
+  it("accepts public https bases", () => {
+    assert.equal(hostallowed("https://gateway.wenathlan.dev"), true);
+    assert.equal(hostallowed("https://gateway.wenathlan.dev/"), true);
+    assert.equal(hostallowed("https://getry.example.com:8443"), true);
+  });
+
+  it("refuses plaintext, localhost, loopback and every private or reserved range", () => {
+    const refused = [
+      "http://gateway.wenathlan.dev",
+      "https://localhost",
+      "https://localhost:8787",
+      "https://app.localhost",
+      "https://box.local",
+      "https://service.internal",
+      "https://gateway.home.arpa",
+      "https://127.0.0.1",
+      "https://0.0.0.0",
+      "https://10.0.0.9",
+      "https://172.16.0.1",
+      "https://172.31.255.255",
+      "https://192.168.1.4",
+      "https://169.254.10.10",
+      "https://100.64.0.1",
+      "https://192.0.2.7",
+      "https://198.51.100.7",
+      "https://203.0.113.9",
+      "https://198.18.0.4",
+      "https://224.0.0.1",
+      "https://[::1]",
+      "https://[::]",
+      "https://[::ffff:127.0.0.1]",
+      "https://[fd00::1]",
+      "https://[fe80::1]",
+      "not a url",
+      "",
+    ];
+    for (const base of refused) assert.equal(hostallowed(base), false, base);
+  });
+
+  it("normalizes the mapped ipv6 spelling the url parser produces", () => {
+    // `https://[::ffff:8.8.8.8]` arrives at the validator as the hex form
+    assert.equal(hostallowed("https://[::ffff:0808:0808]"), true);
+    assert.equal(hostallowed("https://[::ffff:7f00:1]"), false);
+  });
+
+  it("merges stages seen-wins — a stage never unsees", () => {
+    const fresh = { introseen: false, onboardingseen: false };
+    assert.deepEqual(mergeStage(fresh, "intro"), { introseen: true, onboardingseen: false });
+    assert.deepEqual(mergeStage(fresh, "onboarding"), { introseen: true, onboardingseen: true });
+    const half = { introseen: true, onboardingseen: false };
+    assert.deepEqual(mergeStage(half, "onboarding"), { introseen: true, onboardingseen: true });
+  });
+
+  it("never mutates the state it merges", () => {
+    const state = { introseen: false, onboardingseen: false };
+    mergeStage(state, "onboarding");
+    assert.deepEqual(state, { introseen: false, onboardingseen: false });
+  });
+});

package/tests/python-runtime-build.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/../.zscripts" && pwd)"
+TEST_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TEST_ROOT"' EXIT
+
+PROJECT_DIR="$TEST_ROOT/project"
+BUILD_DIR="$TEST_ROOT/build"
+mkdir -p \
+    "$PROJECT_DIR/scripts" \
+    "$PROJECT_DIR/.venv" \
+    "$BUILD_DIR/next-service-dist"
+
+cat >"$PROJECT_DIR/requirements.txt" <<'EOF'
+EOF
+cat >"$PROJECT_DIR/scripts/report.py" <<'EOF'
+print("report")
+EOF
+cat >"$PROJECT_DIR/.venv/should-not-copy.py" <<'EOF'
+ignored
+EOF
+
+PROJECT_DIR="$PROJECT_DIR" BUILD_DIR="$BUILD_DIR" \
+    bash "$SCRIPT_DIR/python-runtime-build.sh"
+
+test -f "$BUILD_DIR/next-service-dist/scripts/report.py"
+test ! -e "$BUILD_DIR/next-service-dist/.venv/should-not-copy.py"
+
+PYPROJECT_DIR="$TEST_ROOT/pyproject-app"
+PYPROJECT_BUILD="$TEST_ROOT/pyproject-build"
+mkdir -p "$PYPROJECT_DIR" "$PYPROJECT_BUILD/next-service-dist"
+cat >"$PYPROJECT_DIR/pyproject.toml" <<'EOF'
+[project]
+name = "deploy-test"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = []
+EOF
+cat >"$PYPROJECT_DIR/app.py" <<'EOF'
+print("pyproject app")
+EOF
+
+PROJECT_DIR="$PYPROJECT_DIR" BUILD_DIR="$PYPROJECT_BUILD" \
+    bash "$SCRIPT_DIR/python-runtime-build.sh"
+test -f "$PYPROJECT_BUILD/next-service-dist/app.py"
+test -f "$PYPROJECT_BUILD/python-runtime/requirements.txt"
+
+NODE_ONLY_PROJECT="$TEST_ROOT/node-only"
+NODE_ONLY_BUILD="$TEST_ROOT/node-only-build"
+mkdir -p "$NODE_ONLY_PROJECT/mini-services/python-worker" "$NODE_ONLY_BUILD"
+cat >"$NODE_ONLY_PROJECT/package.json" <<'EOF'
+{"name": "node-only"}
+EOF
+cat >"$NODE_ONLY_PROJECT/mini-services/python-worker/main.py" <<'EOF'
+print("unsupported preview-only service")
+EOF
+
+PROJECT_DIR="$NODE_ONLY_PROJECT" BUILD_DIR="$NODE_ONLY_BUILD" \
+    bash "$SCRIPT_DIR/python-runtime-build.sh"
+test ! -e "$NODE_ONLY_BUILD/python-runtime"
+
+echo "python runtime build tests passed"

package/tests/python-runtime-container.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+set -euo pipefail
+
+RUNNER_IMAGE="${RUNNER_IMAGE:-z-ai-python-deploy-runner:test}"
+SCRIPT_DIR="$(cd "$(dirname "$0")/../.zscripts" && pwd)"
+TEST_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TEST_ROOT"' EXIT
+
+PROJECT_DIR="$TEST_ROOT/project"
+BUILD_DIR="$TEST_ROOT/build"
+mkdir -p "$PROJECT_DIR" "$BUILD_DIR/next-service-dist"
+
+cat >"$PROJECT_DIR/requirements.txt" <<'EOF'
+idna==3.10
+EOF
+cat >"$PROJECT_DIR/check_runtime.py" <<'EOF'
+import idna
+
+assert idna.__version__ == "3.10"
+print("python artifact import passed")
+EOF
+
+PROJECT_DIR="$PROJECT_DIR" BUILD_DIR="$BUILD_DIR" \
+    bash "$SCRIPT_DIR/python-runtime-build.sh"
+
+docker run --rm \
+    --entrypoint sh \
+    -v "$BUILD_DIR:/app" \
+    "$RUNNER_IMAGE" \
+    -c 'PYTHONPATH=/app/python-runtime/site-packages:/app/next-service-dist python /app/next-service-dist/check_runtime.py'

package/tests/routerotation.test.ts

@@ -0,0 +1,97 @@
+/**
+ * routerotation.test.ts — honest unit tests for the weighted rotation,
+ * runnable with the vitest runner:
+ *   pnpm test
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  healthyroutes,
+  type ModelRoute,
+  newledger,
+  notefailure,
+  notesuccess,
+  pickroute,
+  ROTATIONDEFAULTS,
+  remainingcooldown,
+} from "../routerotation.ts";
+
+/** the three-route pool the tests rotate over. */
+const POOL: ModelRoute[] = [
+  { id: "r1", provider: "zai", model: "glm-5.3-flash", weight: 2 },
+  { id: "r2", provider: "nvidia", model: "deepseek-v4", weight: 1 },
+  { id: "r3", provider: "openrouter", model: "free-tag", weight: 1 },
+];
+
+describe("routerotation weighted pick", () => {
+  it("never answers a cooled-down or zero-weight route", () => {
+    const ledger = newledger();
+    const routes = [...POOL, { id: "r0", provider: "babeltown", model: "paused", weight: 0 }];
+    notefailure(ledger, "r1", { allowedFails: 0 }, 1000);
+    const picks = new Set(Array.from({ length: 200 }, () => pickroute(routes, ledger, Math.random, 1000)?.id));
+    assert.ok(!picks.has("r1"), "cooled route must not be picked");
+    assert.ok(!picks.has("r0"), "zero-weight route must not be picked");
+    assert.ok(picks.has("r2") && picks.has("r3"));
+  });
+
+  it("distributes the draws proportionally to the weights", () => {
+    const ledger = newledger();
+    const draws = Array.from({ length: 6000 }, () => pickroute(POOL, ledger, Math.random)?.id);
+    const r1 = draws.filter((id) => id === "r1").length;
+    const r2 = draws.filter((id) => id === "r2").length;
+    assert.ok(Math.abs(r1 / r2 - 2) < 0.2, `expected r1 ≈ 2×r2, got ${r1} vs ${r2}`);
+  });
+
+  it("answers null when every route is cooling down", () => {
+    const ledger = newledger();
+    for (const route of POOL) notefailure(ledger, route.id, { allowedFails: 0 }, 1000);
+    assert.equal(pickroute(POOL, ledger, Math.random, 1000), null);
+    assert.equal(pickroute(POOL, ledger, () => 0, 1_000 + ROTATIONDEFAULTS.cooldownMs + 1)?.id, "r1");
+  });
+
+  it("skips the ledger route through the weighted walk without a draw on it", () => {
+    const ledger = newledger();
+    notefailure(ledger, "r1", { allowedFails: 0 }, 1000);
+    // rand() = 0 always lands on the first healthy route: r2
+    assert.equal(pickroute(POOL, ledger, () => 0, 1000)?.id, "r2");
+    // rand() just below 1 always lands on the last healthy route: r3
+    assert.equal(pickroute(POOL, ledger, () => 0.9999, 1000)?.id, "r3");
+  });
+});
+
+describe("routerotation cooldown ledger", () => {
+  it("tolerates allowedFails failures before cooling down", () => {
+    const ledger = newledger();
+    notefailure(ledger, "r1", {}, 1000);
+    notefailure(ledger, "r1", {}, 1000);
+    notefailure(ledger, "r1", {}, 1000);
+    assert.deepEqual(ledger.get("r1"), { until: 0, failures: 3 });
+    assert.equal(remainingcooldown(ledger.get("r1"), 1000), 0);
+  });
+
+  it("buys the cooldown after the budget and escalates per further failure", () => {
+    const ledger = newledger();
+    for (let index = 0; index < 3; index++) notefailure(ledger, "r1", {}, 1000);
+    notefailure(ledger, "r1", {}, 1000);
+    assert.equal(remainingcooldown(ledger.get("r1"), 1000), ROTATIONDEFAULTS.cooldownMs);
+    notefailure(ledger, "r1", {}, 1000);
+    assert.equal(
+      remainingcooldown(ledger.get("r1"), 1000),
+      ROTATIONDEFAULTS.cooldownMs + ROTATIONDEFAULTS.cooldownStepMs,
+    );
+  });
+
+  it("clamps the escalation at maxCooldownMs", () => {
+    const ledger = newledger();
+    for (let index = 0; index < 20; index++) notefailure(ledger, "r1", {}, 1000);
+    assert.equal(remainingcooldown(ledger.get("r1"), 1000), ROTATIONDEFAULTS.maxCooldownMs);
+  });
+
+  it("clears the ledger on success", () => {
+    const ledger = newledger();
+    notefailure(ledger, "r1", { allowedFails: 0 }, 1000);
+    notesuccess(ledger, "r1");
+    assert.equal(ledger.size, 0);
+    assert.equal(healthyroutes(POOL, ledger, 1000).length, 3);
+  });
+});

package/tests/streamfallback.test.ts

@@ -0,0 +1,213 @@
+/**
+ * streamfallback.test.ts — honest unit tests for the stream fallback,
+ * runnable with the vitest runner:
+ *   pnpm test
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { ApiKeyRow } from "../db.ts";
+import {
+  applyerrortokey,
+  classifystatus,
+  errorfromresponse,
+  FALLBACKDEFAULTS,
+  type FallbackRoute,
+  orderchain,
+  runwithfallback,
+  StreamError,
+  verdictfor,
+} from "../streamfallback.ts";
+
+/** the two-route chain the tests walk. */
+const CHAIN: FallbackRoute[] = [
+  { id: "primary", priority: 0, enabled: true },
+  { id: "backup", priority: 1, enabled: true },
+];
+
+/** builds a key row for the applyerrortokey cases. */
+function keyrow(overrides: Partial<ApiKeyRow> = {}): ApiKeyRow {
+  return {
+    id: "key-01",
+    provider: "nvidia",
+    key: "nvapi-sample-masked-0001",
+    label: "nim rotation 01",
+    active: true,
+    status: "active",
+    useCount: 10,
+    rotationCount: 2,
+    errorCount: 0,
+    rateLimitHit: false,
+    createdAt: "2026-09-12T10:00:00.000Z",
+    expiresAt: null,
+    ...overrides,
+  };
+}
+
+describe("streamfallback error catalog", () => {
+  it("classifies every status the house answers for", () => {
+    assert.equal(classifystatus(0), "transport");
+    assert.equal(classifystatus(401), "unauthorized");
+    assert.equal(classifystatus(403), "forbidden");
+    assert.equal(classifystatus(404), "notfound");
+    assert.equal(classifystatus(408), "timeout");
+    assert.equal(classifystatus(410), "gone");
+    assert.equal(classifystatus(422), "unprocessable");
+    assert.equal(classifystatus(429), "ratelimited");
+    assert.equal(classifystatus(529), "overloaded");
+    assert.equal(classifystatus(500), "server");
+    assert.equal(classifystatus(503), "server");
+    assert.equal(classifystatus(418), "unknown");
+  });
+
+  it("maps retry for transient, fallback for dead-model and abort for unknown", () => {
+    for (const code of ["transport", "timeout", "server"] as const) assert.equal(verdictfor(code), "retry");
+    for (const code of [
+      "unauthorized",
+      "forbidden",
+      "notfound",
+      "gone",
+      "unprocessable",
+      "ratelimited",
+      "overloaded",
+    ] as const) {
+      assert.equal(verdictfor(code), "fallback", `expected fallback for ${code}`);
+    }
+    assert.equal(verdictfor("unknown"), "abort");
+  });
+
+  it("orders the chain by priority over enabled routes only", () => {
+    const chain = orderchain([
+      { id: "third", priority: 2, enabled: true },
+      { id: "disabled", priority: 0, enabled: false },
+      { id: "first", priority: 0, enabled: true },
+    ]);
+    assert.deepEqual(
+      chain.map((route) => route.id),
+      ["first", "third"],
+    );
+  });
+});
+
+describe("streamfallback runner", () => {
+  it("answers the first healthy route untouched", async () => {
+    const order: string[] = [];
+    const value = await runwithfallback(CHAIN, async (route) => {
+      order.push(route.id);
+      return `ok:${route.id}`;
+    });
+    assert.equal(value, "ok:primary");
+    assert.deepEqual(order, ["primary"]);
+  });
+
+  it("falls back on the catalog codes and records the trail", async () => {
+    for (const status of [401, 403, 404, 410, 422, 429, 529]) {
+      const trail: string[] = [];
+      const value = await runwithfallback(
+        CHAIN,
+        async (route) => {
+          trail.push(route.id);
+          if (route.id === "primary")
+            throw errorfromresponse(new Response(null, { status, headers: { "retry-after": "0" } }));
+          return `ok:${route.id}`;
+        },
+        { initialDelayMs: 1 },
+      );
+      assert.equal(value, `ok:backup`, `status ${status} must fall back`);
+      assert.deepEqual(trail, ["primary", "backup"], `status ${status} must walk primary then backup`);
+    }
+  });
+
+  it("retries the same route first on timeout and transport failures", async () => {
+    let tries = 0;
+    const steps: string[] = [];
+    const value = await runwithfallback(
+      CHAIN,
+      async (route) => {
+        steps.push(`${route.id}#${++tries}`);
+        if (tries === 1) throw new StreamError("upstream timeout", 408, "timeout");
+        return `ok:${route.id}`;
+      },
+      { initialDelayMs: 1 },
+    );
+    assert.equal(value, "ok:primary");
+    assert.deepEqual(steps, ["primary#1", "primary#2"]);
+  });
+
+  it("moves on when the retry budget of a route runs out", async () => {
+    let primaryTries = 0;
+    const value = await runwithfallback(
+      CHAIN,
+      async (route) => {
+        if (route.id === "primary") {
+          primaryTries += 1;
+          throw new StreamError("upstream timeout", 408, "timeout");
+        }
+        return "ok:backup";
+      },
+      { initialDelayMs: 1, maxDelayMs: 2 },
+    );
+    assert.equal(value, "ok:backup");
+    assert.equal(primaryTries, FALLBACKDEFAULTS.retriesPerRoute + 1);
+  });
+
+  it("honors the Retry-After hint over the computed backoff", async () => {
+    let waited = -1;
+    await runwithfallback(
+      CHAIN,
+      async (route) => {
+        if (route.id === "primary") throw new StreamError("upstream timeout", 408, "timeout", 0);
+        return "ok";
+      },
+      { initialDelayMs: 50, onstep: (step) => (waited = Math.max(waited, step.delayMs)) },
+    );
+    assert.equal(waited, 0, "the hint (0ms) must win over the computed 50ms backoff");
+  });
+
+  it("aborts the chain on unknown failures and throws with the trail", async () => {
+    const value = runwithfallback(CHAIN, async () => {
+      throw new Error("bug in the parser");
+    });
+    await assert.rejects(value, (error: unknown) => {
+      assert.ok(error instanceof StreamError);
+      assert.equal((error as StreamError).code, "unknown");
+      return true;
+    });
+  });
+
+  it("throws a StreamFallbackError with the full trail when every route dies", async () => {
+    const value = runwithfallback(
+      CHAIN,
+      async () => {
+        throw errorfromresponse(new Response(null, { status: 529 }));
+      },
+      { initialDelayMs: 1, retriesPerRoute: 0 },
+    );
+    await assert.rejects(value, (error: unknown) => {
+      assert.ok(error instanceof StreamError);
+      const fallback = error as StreamError;
+      assert.equal(fallback.code, "overloaded");
+      assert.ok("trail" in fallback);
+      assert.deepEqual(
+        (fallback as { trail: { routeId: string }[] }).trail.map((step) => step.routeId),
+        ["primary", "backup"],
+      );
+      return true;
+    });
+  });
+});
+
+describe("streamfallback key wire", () => {
+  it("lands failures on the key counters without mutating the input", () => {
+    const row = keyrow();
+    const after429 = applyerrortokey(row, 429);
+    assert.equal(after429.errorCount, 1);
+    assert.equal(after429.rateLimitHit, true);
+    const after500 = applyerrortokey(row, 500);
+    assert.equal(after500.errorCount, 1);
+    assert.equal(after500.rateLimitHit, false);
+    assert.equal(row.errorCount, 0, "the input row must stay untouched");
+    const chain = applyerrortokey(after429, 500);
+    assert.equal(chain.errorCount, 2);
+    assert.equal(chain.rateLimitHit, true, "a prior 429 flag survives other failures");
+  });
+});