Prices from what the cluster costs: ctl prices suggest

auth.gpu_hour_cost (and core_hour_cost) is what an hour of a GPU (a core)
costs the operator. The leader keeps, by the hour, the GPU- and core-hours
each model's replicas hold (held_1h); llmgw ctl prices suggest spreads a
model's over the tokens it served, an output token counted as four input
ones and a cached prompt token as a tenth of one, and --apply writes the
prices into auth.pricing. Idle hours are in the cost, so a model held and
little used comes out dear; one held and billed nothing is shown with what
it held.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -34,7 +34,37 @@ jobs:
         run: go vet ./...
 
       - name: Test with the race detector
-        run: go test -race ./...
+        # Under the job's limit, so a package that hangs panics with the
+        # test it was in and where every goroutine waited, rather than the
+        # job ending at its deadline with nothing said: from 2026-10-15 every
+        # run did, printing nothing after internal/release.
+        run: go test -race -timeout 12m ./...
 
       - name: Build
         run: go build ./...
+
+      # llmgw-kb runs on people's own machines, Windows included, which no
+      # test here runs on: building it for each catches a Unix-only call.
+      - name: Build llmgw-kb for every system
+        run: |
+          for target in windows/amd64 windows/arm64 darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do
+            CGO_ENABLED=0 GOOS="${target%/*}" GOARCH="${target#*/}" go build -o /dev/null ./cmd/llmgw-kb
+          done
+
+      # The Terraform provider is a module of its own, which ./... above does
+      # not reach. Its tests check its client against docs/admin-api.openapi.json,
+      # so a change to the admin API that breaks the provider fails here. The
+      # acceptance tests (TF_ACC=1) are left out: they need Terraform itself.
+      - name: Test the Terraform provider
+        working-directory: terraform-provider-llmgw
+        run: |
+          go vet ./...
+          go test ./...
+
+      # The NVML backend needs cgo and cannot run without a driver, but it must
+      # at least keep compiling: it is the only source of NVLink topology and a
+      # break would otherwise surface on a GPU node, far from here.
+      - name: Build the NVML backend
+        env:
+          CGO_ENABLED: "1"
+        run: go build -tags nvml ./...

.gitea/workflows/engine-releases.yml

@@ -0,0 +1,20 @@
+# Fails when an engine llmgw follows release by release (FreeToken) has
+# published a version newer than the one DefaultEngines installs: the failed
+# run is the notice to check the new version and move to it. See
+# scripts/engine_releases.py.
+name: Engine releases
+
+on:
+  schedule:
+    # Mondays 06:00 UTC.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Compare with PyPI
+        run: python3 scripts/engine_releases.py

.gitea/workflows/release.yml

@@ -0,0 +1,228 @@
+# Attaches binaries to a release when a version tag is pushed.
+#
+# Without this a release is a git tag, and installing llmgw on a node means
+# having a Go toolchain and the source. The onboarding script copies a binary
+# from wherever it is run, which works and quietly makes whoever runs it the
+# build server.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # The built-in token every job is given carries whatever the instance's
+    # default mode allows, and under the restricted default that is read-only
+    # on releases — so the build would succeed and the publish would be
+    # refused. `contents` covers code and releases together, which is what
+    # creating a release needs: `releases: write` alone was refused, because
+    # creating one can create its tag.
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Tags are what the version string is built from, and a shallow clone
+          # has none of them.
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Build
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME:-$(git describe --tags --always)}"
+          mkdir -p dist
+
+          # CGO_ENABLED=0 is the whole point: the binary has to run on a node
+          # whose libc is older than the builder's, and llmgw has no C
+          # dependency — modernc.org/sqlite is pure Go precisely so this stays
+          # true.
+          for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do
+            os="${target%/*}"; arch="${target#*/}"
+            name="llmgw-${version}-${os}-${arch}"
+            echo "building $name"
+            CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" go build \
+              -trimpath \
+              -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${version}" \
+              -o "dist/${name}" ./cmd/llmgw
+            (cd dist && sha256sum "${name}" >> checksums.txt)
+          done
+
+          # llmgw-kb, which people run on their own machines to put their
+          # documents into a knowledge base: Windows too, which llmgw itself
+          # does not build for.
+          for target in windows/amd64 windows/arm64 darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do
+            os="${target%/*}"; arch="${target#*/}"
+            ext=""; [ "$os" = windows ] && ext=".exe"
+            name="llmgw-kb-${version}-${os}-${arch}${ext}"
+            echo "building $name"
+            CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" go build \
+              -trimpath \
+              -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${version}" \
+              -o "dist/${name}" ./cmd/llmgw-kb
+            (cd dist && sha256sum "${name}" >> checksums.txt)
+          done
+
+          # The reverse proxy configurations, so a release page carries
+          # everything install.md asks for and the repository is not needed.
+          for f in deploy/proxy/Caddyfile deploy/proxy/nginx.conf; do
+            cp "$f" dist/
+            (cd dist && sha256sum "$(basename "$f")" >> checksums.txt)
+          done
+
+          # An NVML build for nodes with NVLink, which the portable binary
+          # cannot serve.
+          #
+          # NVML is the only source of NVLink topology, its bindings need cgo,
+          # and cgo is exactly what CGO_ENABLED=0 above exists to avoid. So the
+          # portable binary silently falls back to taking the lowest free GPU
+          # indices — right on an SXM box with NVSwitch, and wrong on a PCIe
+          # box where NVLink bridges pair specific cards: a tensor group
+          # straddling two bridges runs several times slower and nothing says
+          # so. Shipping only the portable build meant nobody could have that
+          # topology without building it themselves.
+          #
+          # Dynamically linked against the host's libc by necessity, so it is
+          # published beside the portable one rather than instead of it.
+          if command -v gcc >/dev/null; then
+            nvml_name="llmgw-${version}-linux-amd64-nvml"
+            CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build \
+              -tags nvml -trimpath \
+              -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${version}" \
+              -o "dist/${nvml_name}" ./cmd/llmgw
+            (cd dist && sha256sum "${nvml_name}" >> checksums.txt)
+          else
+            echo "no C toolchain; skipping the nvml build" >&2
+          fi
+
+          # Proof the artifact runs at all before it is published. It cannot
+          # test the cross-compiled ones, which is why the native build is
+          # checked rather than assumed.
+          ./dist/llmgw-${version}-linux-amd64 --version
+          ./dist/llmgw-kb-${version}-linux-amd64 --version
+          cat dist/checksums.txt
+
+      # Signed, so a machine that trusts the key built into it installs
+      # nothing the server alone could have put there. `release sign` checks
+      # the signature against that key before writing it, so a secret that
+      # does not match trusted.pub stops the release too.
+      - name: Sign the checksums
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME:-$(git describe --tags --always)}"
+          if [ -z "${RELEASE_SIGNING_KEY:-}" ]; then
+            # Builds that carry a trusted key install only signed releases:
+            # publishing an unsigned one would be a release no upgraded
+            # machine accepts, so it stops here instead.
+            if [ -s internal/release/trusted.pub ]; then
+              echo "internal/release/trusted.pub holds a key, and the RELEASE_SIGNING_KEY secret is not set:"
+              echo "add it under Settings -> Secrets, or this release could not be installed anywhere."
+              exit 1
+            fi
+            echo "no RELEASE_SIGNING_KEY secret and no trusted key; releases are not signed"
+            exit 0
+          fi
+          ./dist/llmgw-${version}-linux-amd64 release sign dist/checksums.txt
+          echo "signed: dist/checksums.txt.sig"
+
+      - name: Attach to the release
+        env:
+          TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          set -euo pipefail
+          # Gitea gives every job a GITEA_TOKEN, so this is not the usual
+          # "you forgot to add a secret" — an empty one means the job was denied
+          # a token, which is an instance setting rather than a repository one.
+          if [ -z "${TOKEN:-}" ]; then
+            echo "The job was given no GITEA_TOKEN, so nothing can be uploaded."
+            echo "Check Settings -> Actions -> General; the binaries are in dist/."
+            exit 1
+          fi
+          # workflow_dispatch can be fired from a branch, where GITHUB_REF_NAME
+          # is the branch name. Uploading then would create a release called
+          # "main". The binaries are still built and kept as a check that the
+          # release build works; only the publishing is a tag's business.
+          if [ "${GITHUB_REF_TYPE:-}" != "tag" ]; then
+            echo "not a tag (ref=${GITHUB_REF_NAME}); built, not published"
+            exit 0
+          fi
+          tag="${GITHUB_REF_NAME}"
+          api="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
+
+          # Gitea materialises a release row for every pushed tag, so this
+          # nearly always finds one and the create below is for a tag pushed
+          # some other way.
+          #
+          # The id is read with grep rather than sed because sed's .* is greedy:
+          # "id" appears again inside the nested author object, so the old
+          # pattern took the author's id when it matched at all — and it did not
+          # match "id": 13 with a space, which is what actually happened. The
+          # first "id" in a release object is the release's own.
+          release_id() {
+            curl -sS -H "Authorization: token $TOKEN" "$api/releases/tags/$tag" \
+              | grep -o '"id"[[:space:]]*:[[:space:]]*[0-9]*' \
+              | head -1 | grep -o '[0-9]*$'
+          }
+
+          id=$(release_id || true)
+          if [ -z "$id" ]; then
+            echo "no release for $tag yet; creating one"
+            out=$(curl -sS -w '\n%{http_code}' -X POST \
+                  -H "Authorization: token $TOKEN" \
+                  -H "Content-Type: application/json" \
+                  -d "{\"tag_name\":\"$tag\",\"name\":\"$tag\"}" \
+                  "$api/releases")
+            echo "create returned $(printf '%s' "$out" | tail -1)"
+            # Re-read rather than parsing the create response: a 409 means it
+            # was there all along, which is a success for our purposes.
+            id=$(release_id || true)
+            [ -n "$id" ] || printf '%s\n' "$out" | head -5 >&2
+          fi
+          [ -n "$id" ] || { echo "could not find or create the release" >&2; exit 1; }
+          echo "release id $id"
+
+          for f in dist/*; do
+            echo "uploading $(basename "$f")"
+            curl -sS -f -X POST -H "Authorization: token $TOKEN" \
+              -F "attachment=@$f" \
+              "$api/releases/$id/assets?name=$(basename "$f")" >/dev/null \
+              || { echo "upload of $(basename "$f") was refused" >&2; exit 1; }
+          done
+          echo "attached $(ls dist | wc -l) files to $tag"
+
+  # The release page says what changed, copied from CHANGELOG.md. Gitea makes
+  # an empty release for every tag and the job above only attaches files, so
+  # every release until this existed was a list of binaries and nothing else.
+  #
+  # After the build, because that is what guarantees the release exists. Run by
+  # hand from a branch it syncs every version in the changelog, which is how
+  # the releases made before this got their notes.
+  notes:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Copy the changelog onto the release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_INSTANCE: ${{ github.server_url }}
+          GITEA_REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          if [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then
+            python3 scripts/gitea/release_notes.py --tag "${GITHUB_REF_NAME}"
+          else
+            python3 scripts/gitea/release_notes.py
+          fi

.gitignore

@@ -5,3 +5,9 @@
 *.db-shm
 .DS_Store
 coverage.out
+# The provider built in place, and what Terraform leaves beside an example.
+/terraform-provider-llmgw/terraform-provider-llmgw
+/terraform-provider-llmgw/examples/.terraform*
+/terraform-provider-llmgw/examples/terraform.tfstate*
+# What a development server run from the checkout writes beside it.
+/secrets/

LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Ilker Manap
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

Makefile

@@ -2,10 +2,11 @@ MODULE  := gitea.mynodes.xyz/ilker/llmgw
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 LDFLAGS := -X '$(MODULE)/internal/version.Version=$(VERSION)'
 
-.PHONY: build test race lint fmt clean rename
+.PHONY: build test race lint fmt vuln check clean rename proto proto-tools
 
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/llmgw ./cmd/llmgw
+	go build -ldflags "$(LDFLAGS)" -o bin/llmgw-kb ./cmd/llmgw-kb
 
 test:
 	go test ./...
@@ -20,6 +21,28 @@ fmt:
 	go fmt ./...
 	go vet ./...
 
+# Known vulnerabilities reachable from this code, in the standard library and
+# in dependencies. A toolchain left behind is the commonest cause: the go
+# directive in go.mod is what fixes it.
+vuln:
+	go run golang.org/x/vuln/cmd/govulncheck@latest ./...
+
+# What has to pass before a change is merged.
+check: test
+	go vet ./...
+	$(MAKE) vuln
+
+# Regenerate the agent protocol. Generated code is committed, so this only
+# needs running when api/proto changes.
+proto: proto-tools
+	buf lint
+	buf generate
+
+proto-tools:
+	go install github.com/bufbuild/buf/cmd/buf@latest
+	go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+	go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
+
 clean:
 	rm -rf bin dist
 

README.md

@@ -1,10 +1,25 @@
 # llmgw
 
-A single-binary LLM gateway for clusters with multiple InfiniBand fabrics and
-heterogeneous GPUs.
+A single-binary LLM gateway for clusters with multiple InfiniBand fabrics,
+NVLink domains and heterogeneous GPUs.
 
-It serves LLMs running on your own GPU servers (vLLM / SGLang) behind one
-OpenAI-compatible endpoint. Design document: [llmgw-plan.md](llmgw-plan.md).
+It serves LLMs running on your own GPU and CPU servers (vLLM, SGLang,
+llama.cpp, TensorRT-LLM) behind one OpenAI- and Anthropic-compatible
+endpoint, and answers from your own documents. Design document: [llmgw-plan.md](llmgw-plan.md).
+
+## Getting started
+
+On the machine that will be the control plane, with the release binary
+installed:
+
+```sh
+sudo llmgw
+```
+
+The setup screens install one machine or three (high availability), check
+them first, and leave a model answering. After that the same command opens
+the console. [docs/quick-install.md](docs/quick-install.md) has the six steps
+from empty servers to a first request; everything else is below.
 
 ## Status
 
@@ -13,24 +28,298 @@ Releases track the roadmap phases; see [CHANGELOG.md](CHANGELOG.md).
 | Version | Phase | Scope | State |
 |---|---|---|---|
 | v0.1.0 | 0 | Skeleton and sim-engine | released |
-| v0.2.0 | 1 | Static router (filter/score/pick, streaming proxy) | in progress |
-| v0.3.0 | 1.5 | Admission control (priority bands) | planned |
-| v0.4.0 | 2 | Agent: GPU/IB discovery, single-node engines | planned |
-| v0.5.0 | 3 | Control plane: catalog, scheduler, reconciler | planned |
-| v0.6.0 | 4 | Multi-node placement and fabric awareness | planned |
-| v1.0.0 | 5 | Tenancy, prefix affinity, benchmarking | planned |
+| v0.2.0 | 1 | Static router (filter/score/pick, streaming proxy) | released |
+| v0.3.0 | 1.5 | Admission control (priority bands) | released |
+| v0.4.0 | 2 | Agent: GPU/IB discovery, engine supervision | released as part of v0.5.0 |
+| v0.5.0 | 3 | Control plane: catalog, placement, reconciler, ctl | released |
+| v0.6.0 | 4 | Multi-node placement and fabric awareness | released |
+| v0.7.0 | — | Conversations, agent memory, disk management | released |
+| v0.8.0 | — | PostgreSQL, leader election, agent failover | released |
+| v0.9.0 | — | Managing people and the tenancy tree | released |
+| v0.10.0 | — | InfiniBand fabrics and NVLink, doctor, node add, engines installed by the nodes | released |
+| v0.11.0 | — | High availability from setup, the setup and console screens, usage sums and per-tenant alerts | released |
+| v0.12.0 | — | The cluster's settings in the store, in force when changed; the firewall switch; wipe | released |
+| v0.13.0 | — | The whole system stopped and started from one command; Qwen3Guard judges, on a GPU and CPUs together | released |
+| v0.14.0 | — | Knowledge bases: documents from people's own machines, kept apart per tenant, answered from | released (v0.14.1: adapters, the tree over the API, the firewall on every machine; v0.14.2: pictures from ComfyUI; v0.14.3: 3D models as jobs; v0.14.4: any ComfyUI workflow as a job, presets, licences; v0.14.5: picture and 3D models that add themselves; v0.14.6: setup that explains every part and lets it be chosen, the gateway on all three HA machines; v0.14.7: the judge sized for its machine; v0.14.8: sign-in with Active Directory, several keys for one outside provider; v0.14.9: sign-in set up from the console, a node's console that shows the machine) |
+| v0.15.0 | — | The company's MCP tools and VS Code through the gateway; guardrails that ask outside services and put redacted values back; answers to similar questions | released (v0.15.1: Strata, a 125B model of experts on one card; a second mirror kept in step; pickled weights refused; a served model's context changed; v0.15.2: a served model moved to more cards; v0.15.3: a model stopped and kept, or removed with its files) |
+| v0.16.0 | — | Weights pinned to a commit and checked against what Hugging Face published; documents embedded by the gateway; Strata offered where models are chosen; cluster upgrades that say how far they are | released (v0.16.1: the mirror's Strata tab, Strata's ready-made packs; v0.16.2: standbys that answer clients, FreeToken, a model fetched once per node; v0.16.3: replicas per profile, a served model's settings on the mirror page, the CPU's speed before serving) |
+| v1.0.0 | 5 | What phase 5 has left: precise KV routing proven on vLLM, the block cost picker, defragmentation across NVLink domains, prefill/decode disaggregation | planned |
 
-**v0.1.0 does not serve traffic**: `llmgw server` is still a stub. What works
-today is `sim-engine` plus the routing libraries it exists to test.
+As of v0.6.0 a cluster runs unattended: agents report their hardware, the
+control plane places replicas — including ones larger than a single machine —
+models load when someone asks for them and stop when nobody does, and keys,
+budgets and rate limits decide who may use any of it.
+
+Since v0.11.0 (each release's detail is in [CHANGELOG.md](CHANGELOG.md)):
+
+- **Setup that explains, and high availability that is whole** (v0.14.6).
+  `sudo llmgw` lists the parts of an install, each with what it is for and
+  what is missing without it, and every one can be turned off or set: the
+  starter model and its context, the mirror's directory, the judge's
+  categories and what it does when it does not answer, limits, the
+  portal's language, pictures and 3D. With three machines each runs the
+  control plane, with a floating address on the leader, and any one can
+  be lost: on three VMs, cutting the store primary's power lost no
+  request. One ComfyUI serves an environment's models, pictures, 3D and
+  workflows are MCP tools, and `/v1/messages` gives a model's reasoning as
+  thinking blocks.
+- **Picture and 3D models that add themselves** (v0.14.5). Where a node's
+  card fits flux-schnell or triposr and the catalog makes nothing of that
+  kind, the leader adds it on demand, so a new cluster's portal has its
+  Images and 3D pages; the cluster page and the console show each preset
+  and add it by hand, and `presets.auto` turns it off. Stable Fast 3D's
+  colours can be brought to the picture's (`albedo_match`), and every mesh
+  carries its whole licence.
+- **Any ComfyUI workflow, and models by name** (v0.14.4). `POST
+  /v1/workflows/runs` runs a ComfyUI model's workflow as a job, its inputs
+  (text, numbers, choices, images, masks, audio, video, files) declared in
+  the catalog and listed in `/v1/models`. `llmgw ctl model add triposr` or
+  `flux-schnell` adds a tested model with no YAML; a profile may name the
+  card it needs instead of a class, and ComfyUI now installs on V100s. A
+  licence carries what a machine can match, and a person can leave
+  licences out on the profile page so no key of theirs reaches such a
+  model. A 3D job waiting for the one card says what holds it and for
+  about how long.
+- **3D models as jobs** (v0.14.3). `POST /v1/3d/generations` answers with a
+  job, asked after until its mesh is ready to download. ComfyUI makes it on
+  the cluster's own cards, TripoSR being the tested model. The job says how
+  far along it is, the model's licence is written into the GLB, and
+  `per_mesh` prices it. People make them at `/3d` on the portal; `llmgw ctl
+  3d` shows every owner's jobs. A model profile may also load weights of
+  its own, and an admission band may wait longer than the rest, for bulk
+  work.
+- **Pictures from ComfyUI** (v0.14.2). `POST /v1/images/generations` is made
+  by ComfyUI, behind a gate that demands the replica's key, as an engine the
+  agents install from its source checked against a digest. `per_image`
+  prices it, and people make pictures at `/images` on the portal.
+- **Adapters, and the tenancy tree over the API** (v0.14.1). `llmgw ctl
+  kb dataset` and `llmgw ctl train` make a LoRA adapter from a collection
+  on a node's spare GPU memory, kept on the mirror and seen only by its
+  owner. Organizations, teams, projects, keys and memberships are in the
+  admin API and the Terraform provider. The agents' settings are edited
+  with the cluster's, on the portal too, and the firewall setting reaches
+  every machine.
+- **Knowledge bases** (v0.14.0). People put a company's documents in from
+  their own machines with `llmgw-kb`, a separate download for Windows,
+  macOS and Linux that reads PDF, Office, OpenDocument, mail and many more
+  formats and sends text and vectors, never the files. Collections are kept
+  apart per tenant, down to row-level security in PostgreSQL. A chat
+  request, or a part of the tree by default, is answered from them with
+  its sources: [docs/knowledge.md](docs/knowledge.md).
+- **One command for the whole system** (v0.13.0): `llmgw stop`, `start` and
+  `restart`. Qwen3Guard is the guardrails' judge, on a GPU and on CPUs
+  together.
+- **Settings that apply when changed** (v0.12.0). The cluster's
+  configuration lives in the store, the same on every control plane and in
+  force within seconds (`llmgw ctl config`, the console's Settings). The
+  firewall can be switched on and off for the whole cluster.
+- **Security hardening** (v0.11.2): signed releases only, a token on the
+  admin API, engines not run as root, TLS for the agent port, etcd and
+  Patroni, a firewall for llmgw's internal ports, encrypted backups,
+  bounded connections, sign-in throttling, a Content-Security-Policy.
+- **Guardrails** (v0.11.2). Policies check requests and answers for PII,
+  secrets, prompt injection, deny patterns, and with a judge model; they
+  observe or enforce, and attach to any part of the tenancy tree:
+  [docs/guardrails.md](docs/guardrails.md).
+- **Administration** (v0.11.2):
+  - an audit log of every change (`ctl audit`);
+  - staff roles (viewer, operator, billing, admin);
+  - single sign-on through OpenID Connect and provisioning through SCIM
+    2.0;
+  - key lifetime limits, and rotation with overlap (`keys ttl`, `keys
+    rotate`);
+  - usage export as CSV (`ctl usage export`).
+- **Notifications** (v0.11.2): webhooks, signed or Slack-shaped, for a
+  model parked, a node lost, a budget spent and new weights published, and
+  Alertmanager receiver templates.
+- **Traffic and models** (v0.11.2):
+  - request tags, canaries of new weights with automatic rollback, and
+    quality suites gating updates;
+  - a response cache, kept and replayed requests, and batches;
+  - Anthropic's Messages API, and more of OpenAI's (structured output,
+    images, rerank, audio, moderations);
+  - scaling by the clock, and SLO-aware admission;
+  - TensorRT-LLM, MIG, and models imported from Ollama;
+  - routing by what each vLLM replica's cache holds, and LoRA adapters
+    loaded on demand;
+  - other llmgw clusters as providers, and placement that knows racks,
+    PDUs and power caps.
+- **Operations** (v0.11.2):
+  - `server restore`, off-machine backup copies, and secrets in Vault;
+  - forgetting a person, and keeping a project's requests in the cluster;
+  - offline installs from a bundle, and a Helm chart;
+  - tracing from the control plane to the engines;
+  - the admin API in OpenAPI, with a Terraform provider;
+  - the portal in English and Turkish, with its docs at /docs.
+
+Every one of these is in the console as well as on the command line:
+[docs/console.md](docs/console.md).
+
+What is still ahead is in [BACKLOG.md](BACKLOG.md). Two things that look like
+gaps are not: a model falls through to its fallbacks when there is no
+capacity as well as when a budget is spent, and routing profiles are chosen
+by the key rather than by a request header on purpose — a header would let
+any client promote itself into the top priority band.
+
+One thing is worth saying plainly:
+multi-node replicas are proven on a simulated cluster and on real hardware
+without a fabric. The InfiniBand, NVLink and NCCL paths — telling fabrics apart
+by their subnet managers, mapping them, finding NVLink domains, launching across
+nodes — are written against the formats and failure modes those tools actually
+have and tested against them, but they have not yet run on a machine that has
+them. On such a machine, run `llmgw doctor --json` first and keep the report;
+[docs/fabrics.md](docs/fabrics.md) says what to look at after that.
+
+## Documentation
+
+Every page is also in the binary: `llmgw docs`, or **Manual** in the console.
+
+**Installing**
+
+- [docs/quick-install.md](docs/quick-install.md) — from empty servers to a
+  first request, in six steps: start here
+- [docs/install.md](docs/install.md) — the same with every option explained,
+  and running the cluster after: monitoring, notifications, single sign-on,
+  the firewall, upgrades, backups
+- [docs/node-onboarding.md](docs/node-onboarding.md) — adding nodes to a
+  cluster that exists
+- [docs/kubernetes.md](docs/kubernetes.md) — the control plane on
+  Kubernetes with the Helm chart, and why GPU nodes stay outside it
+- [docs/kong.md](docs/kong.md) — llmgw behind Kong Gateway, or Kong behind
+  llmgw: the configuration, what Kong counts, and which to choose
+- [docs/fabrics.md](docs/fabrics.md) — InfiniBand fabrics and NVLink: what
+  llmgw needs of them, checking a node with `llmgw doctor`, and what to look at
+  when a replica spanning nodes will not run
+
+**Running it**
+
+- [docs/console.md](docs/console.md) — the console that bare `llmgw` opens:
+  every view, and the command each of its actions runs
+- [docs/onboarding.md](docs/onboarding.md) — accounts, keys, limits, staff
+  roles and single sign-on
+- [docs/clients.md](docs/clients.md) — using the gateway from code with the
+  official OpenAI and Anthropic SDKs, and llmgw's extensions
+- [docs/guardrails.md](docs/guardrails.md) — checking requests and answers:
+  policies, detectors, a judge model, and where each applies
+- [docs/knowledge.md](docs/knowledge.md) — knowledge bases: collections,
+  who may read them, `llmgw-kb` on people's machines, and answers from
+  documents
+- [docs/choosing-models.md](docs/choosing-models.md) — which models to run,
+  how many of each, and where the weights should live
+
+**Reference**
+
+- [docs/reference.md](docs/reference.md) — every configuration key, generated
+  from the structs and checked by a test, so it cannot describe a setting that
+  does not exist or miss one that does
+- [docs/data.md](docs/data.md) — what llmgw stores, what it does not, and
+  what leaves the machine; written for a security review
+- [docs/admin-api.md](docs/admin-api.md) and its OpenAPI document — the
+  admin API, for scripts; [terraform-provider-llmgw/](terraform-provider-llmgw/)
+  manages models, quotas and guardrails with Terraform or OpenTofu
+- [deploy/](deploy/) — [a mirror](deploy/mirror/) on its own machine,
+  [Caddy and nginx](deploy/proxy/) in front of the client port, [two control
+  planes](deploy/ha/) behind a balancer, and [Prometheus, Alertmanager and
+  Grafana](deploy/monitoring/)
+
+**Working on llmgw**
+
+- [docs/development.md](docs/development.md) — built from source on one
+  workstation, no systemd and no `sudo`
+- [llmgw-plan.md](llmgw-plan.md) — the design; [BACKLOG.md](BACKLOG.md) —
+  what is next
 
 ## Building
 
 ```sh
-make build      # bin/llmgw
+make build      # bin/llmgw and bin/llmgw-kb
 make test       # unit tests
 make race       # with the race detector
 ```
 
+## Operating a cluster
+
+```sh
+llmgw ctl nodes                      # capacity, health, what is running where
+llmgw ctl models                     # catalog and replica counts
+llmgw ctl replicas --model llama     # replicas and their shards
+llmgw ctl explain-placement llama    # why a model has not been placed
+llmgw ctl drain gpu-a-01             # move work off a node, one replica at a time
+llmgw ctl cordon gpu-a-01            # stop new placement, leave what runs
+sudo llmgw doctor                    # on a node: what its GPUs, NVLink and fabric need
+llmgw ctl audit --since 24h          # who changed what
+llmgw ctl usage export --from 2026-09-01 --to 2026-10-01 --by project,model
+llmgw ctl kb list                    # knowledge-base collections, grants, defaults
+```
+
+Bare `llmgw` opens the console, which does all of this from one screen.
+
+`ctl` talks to the admin port (`:9090` by default), not the client-facing one.
+Add `--json` to any command for machine-readable output.
+
+`explain-placement` is the one worth knowing about: "unschedulable" on its own
+says nothing about which of six constraints bit, so it prints every candidate
+considered and the reason it was rejected.
+
+## What llmgw adds to a request
+
+Measured with `llmgw ctl bench overhead`. It starts an engine that answers
+at once and a gateway in front of it, in one process on loopback. It sends
+the same load straight to the engine and through the gateway, and reports
+what the gateway added. Run on an Apple M5 (10 CPUs, load about 2) on
+2026-10-16, 10 s a step, 72,000 requests with none failed:
+
+| Through the gateway | added at p50 | added at p99 |
+|---|---|---|
+| bare | 0.06–0.24 ms | 0.10–0.33 ms |
+| with authentication and usage accounting | 0.05–0.32 ms | 0.09–0.37 ms |
+| with the guardrails' pattern checks as well | 0.10–0.42 ms | 0.15–0.49 ms |
+
+The range is across 100 to 2,000 requests a second. The overhead was
+*lowest* at 2,000, most likely because a busier processor keeps its cores
+awake. The guardrails' judge model is not in these figures: a judgment
+takes seconds on CPUs (see [install.md](docs/install.md)) and is a model's
+time, not the gateway's.
+
+The command also prints the gateway's CPU per thousand requests. Gateway,
+engine and load share one process there, so that figure is rough (0.04 to
+0.65 s per thousand in the run above); the latency is the one to quote.
+Figures from a VM on a busy host move with the host: run it where you will
+deploy, and keep the load it prints beside the result. CI runs a one-second
+version on every change (`TestTheGatewaysOverheadIsMeasured`).
+
+## Running the router
+
+```sh
+# Two fake engines and a router in front of them.
+./bin/llmgw sim-engine --listen :8001 --model llama &
+./bin/llmgw sim-engine --listen :8002 --model llama &
+./bin/llmgw server \
+  --endpoint e1=http://127.0.0.1:8001=llama \
+  --endpoint e2=http://127.0.0.1:8002=llama
+
+curl -N localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'x-session-id: demo' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"hello"}],"stream":true}'
+```
+
+For anything real use a config file; [deploy/examples/server.yaml](deploy/examples/server.yaml)
+is commented throughout. Metrics, health and pprof are on the admin port (`:9090`
+by default), deliberately separate from the client-facing one.
+
+Requests carry a priority band (`x-llmgw-band`). Under load, low bands wait at
+the gateway while high bands keep flowing, so the cluster degrades from the
+bottom up instead of everywhere at once. Measured effect: interactive p99 stays
+within 1.24x of idle while 500 concurrent batch requests run, against 58x with
+admission off.
+
+Routing profiles select how endpoints are scored: `chat` favours session
+affinity and the replica that has been answering soonest (its time to first
+token, smoothed), `batch` favours the shortest queue, `long-context` favours
+free KV cache. Pick one per model in the config, or per request with the
+`x-llmgw-profile` header.
+
 ## sim-engine
 
 Simulates the inference-engine behaviours **the router cares about**, so the
@@ -83,3 +372,10 @@ make rename NEW=git.example.com/team/llmgw
 ## Language
 
 Code, comments, tests, commit messages and documentation are in English.
+
+## Licence
+
+Functional Source License 1.1 with an Apache 2.0 future licence
+(FSL-1.1-ALv2); see [LICENSE](LICENSE). Each release may be used, read and
+changed for anything except offering it as a competing product or service,
+and becomes Apache 2.0 two years after it is published.

api/gen/llmgw/v1/llmgwv1connect/agent.connect.go

@@ -0,0 +1,119 @@
+// Code generated by protoc-gen-connect-go. DO NOT EDIT.
+//
+// Source: llmgw/v1/agent.proto
+
+// Package llmgw.v1 is the protocol between a node agent and the control plane
+// (plan §5.6).
+//
+// The agent dials out and holds a bidirectional stream open. That direction is
+// deliberate: GPU nodes sit behind firewalls and NAT far more often than a
+// control plane does, and an outbound connection needs no inbound rule on every
+// node in the fleet.
+package llmgwv1connect
+
+import (
+	connect "connectrpc.com/connect"
+	context "context"
+	errors "errors"
+	v1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	http "net/http"
+	strings "strings"
+)
+
+// This is a compile-time assertion to ensure that this generated file and the connect package are
+// compatible. If you get a compiler error that this constant is not defined, this code was
+// generated with a version of connect newer than the one compiled into your binary. You can fix the
+// problem by either regenerating this code with an older version of connect or updating the connect
+// version compiled into your binary.
+const _ = connect.IsAtLeastVersion1_13_0
+
+const (
+	// AgentServiceName is the fully-qualified name of the AgentService service.
+	AgentServiceName = "llmgw.v1.AgentService"
+)
+
+// These constants are the fully-qualified names of the RPCs defined in this package. They're
+// exposed at runtime as Spec.Procedure and as the final two segments of the HTTP route.
+//
+// Note that these are different from the fully-qualified method names used by
+// google.golang.org/protobuf/reflect/protoreflect. To convert from these constants to
+// reflection-formatted method names, remove the leading slash and convert the remaining slash to a
+// period.
+const (
+	// AgentServiceConnectProcedure is the fully-qualified name of the AgentService's Connect RPC.
+	AgentServiceConnectProcedure = "/llmgw.v1.AgentService/Connect"
+)
+
+// AgentServiceClient is a client for the llmgw.v1.AgentService service.
+type AgentServiceClient interface {
+	// Connect opens the agent's stream. It stays open for the agent's lifetime;
+	// losing it is how each side learns the other is gone.
+	Connect(context.Context) *connect.BidiStreamForClient[v1.AgentMessage, v1.ControlMessage]
+}
+
+// NewAgentServiceClient constructs a client for the llmgw.v1.AgentService service. By default, it
+// uses the Connect protocol with the binary Protobuf Codec, asks for gzipped responses, and sends
+// uncompressed requests. To use the gRPC or gRPC-Web protocols, supply the connect.WithGRPC() or
+// connect.WithGRPCWeb() options.
+//
+// The URL supplied here should be the base URL for the Connect or gRPC server (for example,
+// http://api.acme.com or https://acme.com/grpc).
+func NewAgentServiceClient(httpClient connect.HTTPClient, baseURL string, opts ...connect.ClientOption) AgentServiceClient {
+	baseURL = strings.TrimRight(baseURL, "/")
+	agentServiceMethods := v1.File_llmgw_v1_agent_proto.Services().ByName("AgentService").Methods()
+	return &agentServiceClient{
+		connect: connect.NewClient[v1.AgentMessage, v1.ControlMessage](
+			httpClient,
+			baseURL+AgentServiceConnectProcedure,
+			connect.WithSchema(agentServiceMethods.ByName("Connect")),
+			connect.WithClientOptions(opts...),
+		),
+	}
+}
+
+// agentServiceClient implements AgentServiceClient.
+type agentServiceClient struct {
+	connect *connect.Client[v1.AgentMessage, v1.ControlMessage]
+}
+
+// Connect calls llmgw.v1.AgentService.Connect.
+func (c *agentServiceClient) Connect(ctx context.Context) *connect.BidiStreamForClient[v1.AgentMessage, v1.ControlMessage] {
+	return c.connect.CallBidiStream(ctx)
+}
+
+// AgentServiceHandler is an implementation of the llmgw.v1.AgentService service.
+type AgentServiceHandler interface {
+	// Connect opens the agent's stream. It stays open for the agent's lifetime;
+	// losing it is how each side learns the other is gone.
+	Connect(context.Context, *connect.BidiStream[v1.AgentMessage, v1.ControlMessage]) error
+}
+
+// NewAgentServiceHandler builds an HTTP handler from the service implementation. It returns the
+// path on which to mount the handler and the handler itself.
+//
+// By default, handlers support the Connect, gRPC, and gRPC-Web protocols with the binary Protobuf
+// and JSON codecs. They also support gzip compression.
+func NewAgentServiceHandler(svc AgentServiceHandler, opts ...connect.HandlerOption) (string, http.Handler) {
+	agentServiceMethods := v1.File_llmgw_v1_agent_proto.Services().ByName("AgentService").Methods()
+	agentServiceConnectHandler := connect.NewBidiStreamHandler(
+		AgentServiceConnectProcedure,
+		svc.Connect,
+		connect.WithSchema(agentServiceMethods.ByName("Connect")),
+		connect.WithHandlerOptions(opts...),
+	)
+	return "/llmgw.v1.AgentService/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case AgentServiceConnectProcedure:
+			agentServiceConnectHandler.ServeHTTP(w, r)
+		default:
+			http.NotFound(w, r)
+		}
+	})
+}
+
+// UnimplementedAgentServiceHandler returns CodeUnimplemented from all methods.
+type UnimplementedAgentServiceHandler struct{}
+
+func (UnimplementedAgentServiceHandler) Connect(context.Context, *connect.BidiStream[v1.AgentMessage, v1.ControlMessage]) error {
+	return connect.NewError(connect.CodeUnimplemented, errors.New("llmgw.v1.AgentService.Connect is not implemented"))
+}

buf.gen.yaml

@@ -0,0 +1,12 @@
+version: v2
+managed:
+  enabled: true
+plugins:
+  - local: protoc-gen-go
+    out: api/gen
+    opt: paths=source_relative
+  - local: protoc-gen-connect-go
+    out: api/gen
+    opt: paths=source_relative
+inputs:
+  - directory: api/proto

buf.yaml

@@ -0,0 +1,16 @@
+version: v2
+modules:
+  - path: api/proto
+lint:
+  use:
+    - STANDARD
+  except:
+    # The standard names assume request/response pairs. This is one long-lived
+    # bidirectional stream carrying several kinds of message in each direction,
+    # so "AgentMessage" and "ControlMessage" say what they are and
+    # "ConnectRequest"/"ConnectResponse" would not.
+    - RPC_REQUEST_STANDARD_NAME
+    - RPC_RESPONSE_STANDARD_NAME
+breaking:
+  use:
+    - FILE

cmd/llmgw-kb/main.go

@@ -0,0 +1,469 @@
+// Command llmgw-kb puts a person's documents into an llmgw knowledge base
+// from their own machine (BACKLOG F2): it reads the files there, cuts them
+// into chunks, has the gateway embed them with the person's key, and sends
+// the text and vectors — only for what changed since the last run, which a
+// ledger on the machine remembers.
+//
+// Its own binary, for Windows, macOS and Linux: it carries none of the
+// server, agent or setup code that llmgw does.
+package main
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kb/extract"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kb/kbsync"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/version"
+)
+
+func main() {
+	if err := root().Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		os.Exit(1)
+	}
+}
+
+// config is what `login` keeps: the gateway, the key, and for a personal key
+// the project it acts in.
+type config struct {
+	Gateway string `json:"gateway"`
+	Key     string `json:"key"`
+	Project string `json:"project,omitempty"`
+	CA      string `json:"ca,omitempty"`
+}
+
+func configPath() (string, error) {
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "llmgw-kb", "config.json"), nil
+}
+
+// loadConfig reads the saved configuration, with the environment over it:
+// LLMGW_URL, LLMGW_API_KEY, LLMGW_PROJECT.
+func loadConfig() (config, error) {
+	var c config
+	if p, err := configPath(); err == nil {
+		if b, err := os.ReadFile(p); err == nil {
+			if err := json.Unmarshal(b, &c); err != nil {
+				return c, fmt.Errorf("%s: %w", p, err)
+			}
+		}
+	}
+	for env, dst := range map[string]*string{"LLMGW_URL": &c.Gateway, "LLMGW_API_KEY": &c.Key, "LLMGW_PROJECT": &c.Project} {
+		if v := strings.TrimSpace(os.Getenv(env)); v != "" {
+			*dst = v
+		}
+	}
+	return c, nil
+}
+
+func client(flags *globalFlags) (*kbsync.Client, error) {
+	c, err := loadConfig()
+	if err != nil {
+		return nil, err
+	}
+	if flags.gateway != "" {
+		c.Gateway = flags.gateway
+	}
+	if flags.project != "" {
+		c.Project = flags.project
+	}
+	if flags.ca != "" {
+		c.CA = flags.ca
+	}
+	if c.Gateway == "" || c.Key == "" {
+		return nil, errors.New("no gateway or key: run `llmgw-kb login`, or set LLMGW_URL and LLMGW_API_KEY")
+	}
+	h, err := kbsync.NewHTTP(c.CA)
+	if err != nil {
+		return nil, err
+	}
+	return &kbsync.Client{Base: c.Gateway, Key: c.Key, Project: c.Project, HTTP: h}, nil
+}
+
+type globalFlags struct {
+	gateway, project, ca, ledger string
+}
+
+func (g *globalFlags) openLedger(ctx context.Context) (*kbsync.Ledger, error) {
+	p := g.ledger
+	if p == "" {
+		var err error
+		if p, err = kbsync.DefaultLedgerPath(); err != nil {
+			return nil, err
+		}
+	}
+	return kbsync.OpenLedger(ctx, p)
+}
+
+func root() *cobra.Command {
+	g := &globalFlags{}
+	cmd := &cobra.Command{
+		Use:   "llmgw-kb",
+		Short: "Put your documents into an llmgw knowledge base, from this machine",
+		Long: `llmgw-kb reads documents on this machine, cuts them into chunks, has the
+gateway embed them with your key, and sends the text and vectors to a
+knowledge base. Files are never uploaded. Run it as often as you like: a
+ledger on this machine remembers what was sent, and only what changed is
+read and sent again.`,
+		Version:       version.Version,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+	cmd.PersistentFlags().StringVar(&g.gateway, "gateway", "", "the gateway's address (default: from login, or LLMGW_URL)")
+	cmd.PersistentFlags().StringVar(&g.project, "project", "", "the project a personal key acts in (default: from login, or LLMGW_PROJECT)")
+	cmd.PersistentFlags().StringVar(&g.ca, "ca", "", "a PEM file of certificates to trust besides the system's")
+	cmd.PersistentFlags().StringVar(&g.ledger, "ledger", "", "the ledger file (default: in your configuration directory)")
+	cmd.AddCommand(loginCmd(g), collectionsCmd(g), syncCmd(g), statusCmd(g), historyCmd(g), formatsCmd())
+	return cmd
+}
+
+func loginCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "login",
+		Short: "Save the gateway's address and your key",
+		Long: `Asks for the gateway's address and your API key, checks them, and saves them
+in your configuration directory, readable by you only. The key is typed
+without being shown, so it does not end up in your shell's history.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			c, _ := loadConfig()
+			in := bufio.NewReader(os.Stdin)
+			ask := func(q, def string) string {
+				if def != "" {
+					fmt.Fprintf(cmd.OutOrStdout(), "%s [%s]: ", q, def)
+				} else {
+					fmt.Fprintf(cmd.OutOrStdout(), "%s: ", q)
+				}
+				s, _ := in.ReadString('\n')
+				if s = strings.TrimSpace(s); s == "" {
+					return def
+				}
+				return s
+			}
+			c.Gateway = strings.TrimRight(ask("Gateway address (https://…)", or(g.gateway, c.Gateway)), "/")
+			fmt.Fprint(cmd.OutOrStdout(), "API key: ")
+			var key string
+			if term.IsTerminal(int(os.Stdin.Fd())) {
+				b, err := term.ReadPassword(int(os.Stdin.Fd()))
+				fmt.Fprintln(cmd.OutOrStdout())
+				if err != nil {
+					return err
+				}
+				key = strings.TrimSpace(string(b))
+			} else {
+				key, _ = in.ReadString('\n')
+				key = strings.TrimSpace(key)
+			}
+			if key != "" {
+				c.Key = key
+			}
+			c.Project = ask("Project, for a personal key (empty for a project's key)", or(g.project, c.Project))
+			if g.ca != "" {
+				c.CA = g.ca
+			}
+			h, err := kbsync.NewHTTP(c.CA)
+			if err != nil {
+				return err
+			}
+			cl := &kbsync.Client{Base: c.Gateway, Key: c.Key, Project: c.Project, HTTP: h, Wait: time.Second}
+			ctx, cancel := context.WithTimeout(cmd.Context(), 30*time.Second)
+			defer cancel()
+			cs, err := cl.Collections(ctx)
+			if err != nil {
+				return fmt.Errorf("the gateway refused: %w", err)
+			}
+			p, err := configPath()
+			if err != nil {
+				return err
+			}
+			if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+				return err
+			}
+			b, _ := json.MarshalIndent(c, "", "  ")
+			if err := os.WriteFile(p, b, 0o600); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Saved in %s. This key reaches %d collection(s); `llmgw-kb collections` lists them.\n", p, len(cs))
+			return nil
+		},
+	}
+}
+
+func or(a, b string) string {
+	if a != "" {
+		return a
+	}
+	return b
+}
+
+func collectionsCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "collections",
+		Short: "List the collections your key may read, and which it may add to",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			cs, err := c.Collections(cmd.Context())
+			if err != nil {
+				return err
+			}
+			if len(cs) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "No collections. An administrator creates them and grants access (llmgw ctl kb).")
+				return nil
+			}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "NAME\tACCESS\tOWNER\tEMBEDDED BY")
+			for _, x := range cs {
+				access := "read"
+				if x.Writable {
+					access = "read, write"
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%s\t%s (%d)\n", x.Name, access, or(x.OwnerName, x.Owner), x.EmbedModel, x.Dims)
+			}
+			return tw.Flush()
+		},
+	}
+}
+
+func syncCmd(g *globalFlags) *cobra.Command {
+	var o kbsync.Options
+	var verbose bool
+	var ocr string
+	var maxMiB int64
+	cmd := &cobra.Command{
+		Use:   "sync COLLECTION PATH...",
+		Short: "Send a collection what changed in these folders and files",
+		Long: `Reads the files under each PATH that the collection does not already have as
+they are, and sends their text and vectors. Run it again whenever you like;
+unchanged files are not even read.
+
+Documents are named by their path under PATH, with forward slashes; with
+several PATHs, each folder's own name comes first.
+
+  --dry-run   reads and cuts everything, sends nothing, and says what would
+              leave this machine
+  --delete    removes documents this machine sent whose files are gone
+              (only under these PATHs; nothing anybody else sent)
+  --retry     reads again files skipped before (after installing LibreOffice
+              or Tesseract, say)
+
+Without --include, every file of a known format is read (llmgw-kb formats);
+hidden files, version control folders and Office lock files are not.`,
+		Args: cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt)
+			defer stop()
+			l, err := g.openLedger(ctx)
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			o.Collection, o.Roots = args[0], args[1:]
+			o.Extract = extract.Options{Helpers: extract.FindHelpers(), OCRLanguages: ocr, MaxBytes: maxMiB << 20}
+			out := cmd.OutOrStdout()
+			c.Waiting = func(why string, d time.Duration) {
+				fmt.Fprintf(out, "  ..       waiting %s: %s\n", d, why)
+			}
+			start := time.Now()
+			rep, err := kbsync.Sync(ctx, c, l, o, func(e kbsync.Event) {
+				switch e.Kind {
+				case "unchanged":
+					if !verbose {
+						return
+					}
+					fmt.Fprintf(out, "  =        %s\n", e.Name)
+				case "sent", "would-send":
+					fmt.Fprintf(out, "  %-8s %s (%d chunks, %s)\n", label(e.Kind), e.Name, e.Chunks, size(e.Bytes))
+				default:
+					line := fmt.Sprintf("  %-8s %s", label(e.Kind), e.Name)
+					if e.Detail != "" {
+						line += ": " + e.Detail
+					}
+					fmt.Fprintln(out, line)
+				}
+			})
+			if rep.Collection.Name != "" {
+				verb := "sent"
+				if o.DryRun {
+					verb = "would send"
+				}
+				fmt.Fprintf(out, "\n%s: %d files; %s %d (%d chunks, %s), %d unchanged, %d skipped, %d failed, %d deleted, in %s\n",
+					rep.Collection.Name, rep.Files, verb, rep.Sent, rep.Chunks, size(rep.Bytes), rep.Unchanged,
+					rep.Skipped, rep.Failed, rep.Deleted, time.Since(start).Round(time.Second))
+			}
+			if err != nil {
+				return err
+			}
+			if rep.Failed > 0 {
+				return fmt.Errorf("%d document(s) failed; run again to retry them", rep.Failed)
+			}
+			return nil
+		},
+	}
+	f := cmd.Flags()
+	f.StringSliceVar(&o.Include, "include", nil, "read only files matching these globs (\"*.pdf,docs/**/*.md\")")
+	f.StringSliceVar(&o.Exclude, "exclude", nil, "never read files matching these globs")
+	f.BoolVar(&o.Hidden, "hidden", false, "read hidden files and folders too")
+	f.BoolVar(&o.DryRun, "dry-run", false, "send nothing; say what would be sent")
+	f.BoolVar(&o.Delete, "delete", false, "remove documents this machine sent whose files are gone")
+	f.BoolVar(&o.Retry, "retry", false, "read again files skipped before")
+	f.IntVar(&o.Workers, "workers", 4, "files read and sent at once")
+	f.BoolVar(&o.EmbedHere, "embed-here", false,
+		"embed on this machine and send the vectors, even to a gateway that embeds text it is sent")
+	f.StringVar(&ocr, "ocr-languages", "tur+eng", "Tesseract's languages for images and scanned pages")
+	f.Int64Var(&maxMiB, "max-size", 256, "skip files larger than this many MiB")
+	f.BoolVarP(&verbose, "verbose", "v", false, "list unchanged files too")
+	return cmd
+}
+
+func label(kind string) string {
+	switch kind {
+	case "would-send":
+		return "send"
+	case "would-delete":
+		return "delete"
+	}
+	return kind
+}
+
+func size(b int64) string {
+	switch {
+	case b >= 1<<20:
+		return fmt.Sprintf("%.1f MiB", float64(b)/(1<<20))
+	case b >= 1<<10:
+		return fmt.Sprintf("%.0f KiB", float64(b)/(1<<10))
+	}
+	return fmt.Sprintf("%d B", b)
+}
+
+func statusCmd(g *globalFlags) *cobra.Command {
+	var all bool
+	return &cobra.Command{
+		Use:   "status COLLECTION",
+		Short: "Show what this machine has sent to a collection, and what it skipped",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			m, err := c.Manifest(cmd.Context(), args[0])
+			if err != nil {
+				return err
+			}
+			l, err := g.openLedger(cmd.Context())
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			es, err := l.Entries(cmd.Context(), strings.TrimRight(c.Base, "/"), m.Collection.ID)
+			if err != nil {
+				return err
+			}
+			counts := map[kbsync.State]int{}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "STATE\tDOCUMENT\tCHUNKS\tWHEN\tWHY")
+			for _, e := range es {
+				counts[e.State]++
+				if e.State == kbsync.Sent && !all {
+					continue
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%d\t%s\t%s\n", e.State, e.Name, e.Chunks, e.At.Format("2006-01-02 15:04"), e.Reason)
+			}
+			_ = tw.Flush()
+			fmt.Fprintf(cmd.OutOrStdout(), "\n%s holds %d documents; from this machine %d sent, %d skipped, %d failed.",
+				m.Collection.Name, len(m.Documents), counts[kbsync.Sent], counts[kbsync.Skipped], counts[kbsync.Failed])
+			if !all {
+				fmt.Fprint(cmd.OutOrStdout(), " (--all lists the sent ones too)")
+			}
+			fmt.Fprintln(cmd.OutOrStdout())
+			return nil
+		},
+	}
+}
+
+func historyCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "history",
+		Short: "List the latest syncs from this machine",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			l, err := g.openLedger(cmd.Context())
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			runs, err := l.Runs(cmd.Context(), 20)
+			if err != nil {
+				return err
+			}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "STARTED\tTOOK\tCOLLECTION\tSENT\tUNCHANGED\tSKIPPED\tFAILED\tDELETED")
+			for _, r := range runs {
+				took := "unfinished"
+				if !r.Finished.IsZero() {
+					took = r.Finished.Sub(r.Started).Round(time.Second).String()
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%s\t%d\t%d\t%d\t%d\t%d\n", r.Started.Format("2006-01-02 15:04"), took,
+					r.Collection, r.Sent, r.Unchanged, r.Skipped, r.Failed, r.Delete)
+			}
+			return tw.Flush()
+		},
+	}
+}
+
+func formatsCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "formats",
+		Short: "List the formats read, and the helpers found on this machine",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			builtIn, helper := extract.Supported()
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "Read here:\n%s\n\n", wrap(builtIn))
+			fmt.Fprintf(out, "Read with a helper program:\n%s\n\n", wrap(helper))
+			fmt.Fprintln(out, "Helpers:")
+			for _, l := range extract.FindHelpers().Describe() {
+				fmt.Fprintln(out, "  "+l)
+			}
+			return nil
+		},
+	}
+}
+
+func wrap(words []string) string {
+	var b strings.Builder
+	line := "  "
+	for _, w := range words {
+		if len(line)+len(w) > 78 {
+			b.WriteString(strings.TrimRight(line, " ") + "\n")
+			line = "  "
+		}
+		line += w + " "
+	}
+	b.WriteString(strings.TrimRight(line, " "))
+	return b.String()
+}

cmd/llmgw-kb/main_test.go

@@ -0,0 +1,24 @@
+package main
+
+import (
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// The client goes onto employees' laptops: none of the server, agent, store
+// or setup code may come with it, and it must build where llmgw does not.
+func TestTheClientCarriesNoServerCode(t *testing.T) {
+	out, err := exec.Command("go", "list", "-deps", ".").Output()
+	if err != nil {
+		t.Skipf("go list: %v", err)
+	}
+	for _, dep := range strings.Fields(string(out)) {
+		for _, banned := range []string{"/internal/store", "/internal/router", "/internal/agent", "/internal/control",
+			"/internal/cli", "/internal/guard", "github.com/jackc/pgx"} {
+			if strings.Contains(dep, banned) {
+				t.Errorf("llmgw-kb depends on %s", dep)
+			}
+		}
+	}
+}

cmd/llmgw/main.go

@@ -5,6 +5,8 @@ package main
 import (
 	"fmt"
 	"os"
+	// Time zones for scaling schedules, on a machine without the tz database.
+	_ "time/tzdata"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/cli"
 )

deploy/bootstrap/add-node.sh

@@ -0,0 +1,112 @@
+#!/bin/sh
+# add-node.sh — build a node and put it in the fleet, in one command.
+#
+# provision-node.sh and onboard-node.sh stay separate because the two halves
+# need different access: one the hypervisor, one the certificate authority.
+# That is a real boundary and this script does not erase it — it drives both
+# where one person holds both, which is the common case and was the case here.
+#
+# The reason to have it is not keystrokes. The VM name, the hostname, the node
+# id and the certificate's common name must all be the same string, and the
+# address appears in three places; split across two invocations run minutes
+# apart, that agreement is maintained by whoever is typing. Here it is stated
+# once.
+set -eu
+
+usage() {
+  cat >&2 <<'USAGE'
+usage: add-node.sh --name NODE --ip ADDR/CIDR --server URL [options]
+
+  --name NODE       node id, hostname and VM name; also the certificate's CN
+  --ip ADDR/CIDR    e.g. 10.0.0.145/24
+  --server URL      control plane, e.g. https://10.0.0.140:7443
+
+  --vmid N          Proxmox VMID (default: the last octet of --ip)
+  --cores N         (default 4)
+  --cpu TYPE        QEMU CPU model (default host; see provision-node.sh)
+  --memory MB       (default 8192)
+  --disk GB         (default 20)
+  --fabric NAME     InfiniBand fabric; repeatable as NAME:hca1,hca2.
+                    Omit for a node with no fabric.
+  --llamacpp-bin P  path to llama-server on the node
+  --vllm-bin P      path to vllm
+  --sglang-python P path to the python that has sglang
+  --binary PATH     llmgw binary to install (default: the one on PATH)
+  --pki DIR         certificate authority (default /etc/llmgw/pki)
+  --ssh-user U      (default ilker)
+  --provision-only  build the VM and stop
+  --onboard-only    skip provisioning; the machine already exists
+USAGE
+  exit 2
+}
+
+NAME= IP= SERVER= VMID= CORES=4 MEMORY=8192 DISK=20 CPU=
+BINARY= PKI=/etc/llmgw/pki SSH_USER=ilker
+PROVISION=1 ONBOARD=1
+set -- "$@"
+PASS_THROUGH=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name) NAME="$2"; shift 2;;
+    --ip) IP="$2"; shift 2;;
+    --server) SERVER="$2"; shift 2;;
+    --vmid) VMID="$2"; shift 2;;
+    --cores) CORES="$2"; shift 2;;
+    --cpu) CPU="$2"; shift 2;;
+    --memory) MEMORY="$2"; shift 2;;
+    --disk) DISK="$2"; shift 2;;
+    --binary) BINARY="$2"; shift 2;;
+    --pki) PKI="$2"; shift 2;;
+    --ssh-user) SSH_USER="$2"; shift 2;;
+    --provision-only) ONBOARD=0; shift;;
+    --onboard-only) PROVISION=0; shift;;
+    # Everything the onboarding step understands and this one does not need to.
+    --fabric|--llamacpp-bin|--vllm-bin|--sglang-python|--ib-root|--nvidia-smi|--mgmt-addr|--mgmt-if)
+      PASS_THROUGH="$PASS_THROUGH $1 $2"; shift 2;;
+    -h|--help) usage;;
+    *) echo "unknown option: $1" >&2; usage;;
+  esac
+done
+[ -n "$NAME" ] && [ -n "$IP" ] && [ -n "$SERVER" ] || usage
+
+# The address without its prefix, which is what onboarding and ssh want.
+ADDR="${IP%%/*}"
+# The last octet as the VMID by default: it keeps `qm list` and `ctl nodes` in
+# the same order, and one fewer number to choose is one fewer to get wrong.
+[ -n "$VMID" ] || VMID="${ADDR##*.}"
+
+here() { dirname "$0"; }
+PROVISION_SH="$(here)/provision-node.sh"
+ONBOARD_SH="$(here)/onboard-node.sh"
+[ -x "$PROVISION_SH" ] || PROVISION_SH="$(command -v llmgw-provision-node || true)"
+[ -x "$ONBOARD_SH" ] || ONBOARD_SH="$(command -v llmgw-onboard-node || true)"
+
+if [ "$PROVISION" = 1 ]; then
+  [ -x "$PROVISION_SH" ] || { echo "cannot find provision-node.sh" >&2; exit 1; }
+  echo "== 1/2  building $NAME as VM $VMID"
+  # shellcheck disable=SC2086
+  "$PROVISION_SH" --vmid "$VMID" --name "$NAME" --ip "$IP" \
+    --cores "$CORES" --memory "$MEMORY" --disk "$DISK" ${CPU:+--cpu "$CPU"}
+fi
+
+if [ "$ONBOARD" = 0 ]; then
+  echo "$NAME built. Onboard it from the CA host when you are ready."
+  exit 0
+fi
+
+[ -x "$ONBOARD_SH" ] || { echo "cannot find onboard-node.sh" >&2; exit 1; }
+echo
+echo "== 2/2  onboarding $NAME"
+# Onboarding waits for ssh itself, which is what makes running the two halves
+# back to back safe: cloud-init is still regenerating host keys and restarting
+# sshd for the first minute of a new machine's life.
+# shellcheck disable=SC2086
+"$ONBOARD_SH" --node "$NAME" --addr "$ADDR" --server "$SERVER" \
+  --pki "$PKI" --ssh-user "$SSH_USER" \
+  ${BINARY:+--binary "$BINARY"} $PASS_THROUGH
+
+echo
+echo "Check it with: llmgw ctl nodes"
+echo
+echo "The agent installs its engines itself; the node takes no model until they"
+echo "are installed and seen to run. 'llmgw ctl nodes' shows where that stands."

deploy/bootstrap/onboard-node.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+#
+# Give a machine an identity in an llmgw cluster.
+#
+# Run on the host that holds the certificate authority, because that is the one
+# thing that cannot be delegated: this script issues the credential by which the
+# control plane will believe the node is who it says it is.
+#
+# What it does, in the order it matters:
+#   1. issue a client certificate whose common name is the node id
+#   2. copy the CA root, the certificate and its key to the machine
+#   3. trust the root system-wide, so other tooling there stops complaining
+#   4. install the binary, the configuration and the unit
+#   5. start the agent
+#
+# The node id, the VM name, the hostname and the certificate common name are all
+# the same string. They do not have to be, and every time they are not, someone
+# spends an afternoon working out which of the four a message is talking about.
+set -euo pipefail
+
+usage() {
+  cat >&2 <<USAGE
+usage: $0 --node ID --addr HOST --server URL [options]
+
+  --node ID         node id, hostname and certificate common name
+  --addr HOST       how to reach the machine over ssh
+  --server URL      the control plane's agent endpoint, e.g. https://10.0.0.140:7443;
+                    several, comma separated, for a node that fails over
+  --fabric NAME     InfiniBand fabric this node is attached to; repeatable as
+                    --fabric NAME:hca1,hca2 . Omit for a node with no fabric,
+                    which can host single-node replicas and will never be given
+                    a multi-node one.
+  --mgmt-addr ADDR  address engines are reachable on (default: the node's
+                    address on the route to --server, found by the agent)
+  --mgmt-if NAME    interface NCCL bootstraps over (default: the one holding
+                    that address)
+  --llamacpp-bin P  use this llama-server instead of the one the agent installs
+  --vllm-bin P      use this vllm instead of the one the agent installs on a
+                    GPU node (also set engines.vllm: "" in server.yaml)
+  --sglang-python P python interpreter of an SGLang virtualenv you installed
+  --nvidia-smi PATH where nvidia-smi lives, when it is not on PATH. Containerized
+                    driver installs routinely put it somewhere else.
+  --ib-root DIR     the sysfs InfiniBand directory (default /sys/class/infiniband)
+  --pki DIR         where the authority lives (default /etc/llmgw/pki)
+  --binary PATH     llmgw binary to install (default: the one running this).
+                    Releases carry static linux/amd64 and linux/arm64 builds;
+                    downloading one is better than copying whatever happens to
+                    be on the machine you are running this from.
+  --releases URL    where release binaries are downloaded from (default the
+                    project's Gitea releases)
+  --ssh-user NAME   (default ilker)
+USAGE
+  exit 2
+}
+
+NODE= ADDR= SERVER= MGMT_OVERRIDE= MGMT_IF_OVERRIDE=
+NVIDIA_SMI= IB_ROOT=/sys/class/infiniband
+LLAMACPP_BIN= VLLM_BIN= SGLANG_PYTHON=
+SSH_WAIT=180
+PKI=/etc/llmgw/pki BINARY= SSH_USER=ilker
+RELEASES=https://gitea.mynodes.xyz/ilker/llmgw/releases/download
+FABRIC_NAME= FABRIC_HCAS="mlx5_0,mlx5_1"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --node) NODE="$2"; shift 2;;
+    --addr) ADDR="$2"; shift 2;;
+    --server) SERVER="$2"; shift 2;;
+    --fabric) FABRIC_NAME="${2%%:*}"; [ "${2#*:}" != "$2" ] && FABRIC_HCAS="${2#*:}"; shift 2;;
+    --mgmt-addr) MGMT_OVERRIDE="$2"; shift 2;;
+    --mgmt-if) MGMT_IF_OVERRIDE="$2"; shift 2;;
+    --llamacpp-bin) LLAMACPP_BIN="$2"; shift 2;;
+    --vllm-bin) VLLM_BIN="$2"; shift 2;;
+    --sglang-python) SGLANG_PYTHON="$2"; shift 2;;
+    --nvidia-smi) NVIDIA_SMI="$2"; shift 2;;
+    --ib-root) IB_ROOT="$2"; shift 2;;
+    --pki) PKI="$2"; shift 2;;
+    --binary) BINARY="$2"; shift 2;;
+    --releases) RELEASES="$2"; shift 2;;
+    --ssh-user) SSH_USER="$2"; shift 2;;
+    *) usage;;
+  esac
+done
+[ -n "$NODE" ] && [ -n "$ADDR" ] && [ -n "$SERVER" ] || usage
+BINARY="${BINARY:-$(command -v llmgw)}"
+[ -x "$BINARY" ] || { echo "no llmgw binary; pass --binary" >&2; exit 1; }
+[ -f "$PKI/ca-key.pem" ] || { echo "no authority in $PKI; run 'llmgw ctl cert init-ca' first" >&2; exit 1; }
+
+# accept-new, not "no": a machine provisioned a minute ago has a host key
+# nobody has seen, and refusing it stopped onboarding dead with "Host key
+# verification failed" — an error about ssh, in the middle of a script whose
+# whole job is to talk to a new machine. accept-new learns an unknown key and
+# still refuses a changed one, which is the distinction that matters: the risk
+# being guarded against is a substituted machine, not a new one.
+SSHOPTS="-o BatchMode=yes -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new"
+SSH="ssh $SSHOPTS $SSH_USER@$ADDR"
+say() { printf '  %s\n' "$*"; }
+
+echo "onboarding $NODE at $ADDR"
+
+# Waiting rather than failing: cloud-init restarts sshd after it regenerates
+# the host keys, so a machine that answered a moment ago refuses connections
+# for a few seconds. Observed while onboarding node05 — the agent was already
+# registered and healthy while ssh was refusing.
+wait_for_ssh() {
+  deadline=$(( $(date +%s) + SSH_WAIT ))
+  until $SSH true 2>/dev/null; do
+    [ "$(date +%s)" -lt "$deadline" ] || {
+      echo "cannot reach $SSH_USER@$ADDR over ssh after ${SSH_WAIT}s" >&2
+      exit 1
+    }
+    sleep 5
+  done
+}
+wait_for_ssh
+
+# 1. The certificate. Issued fresh every time: re-onboarding a machine should
+#    not depend on finding an old key, and the old one keeps working until it
+#    is revoked, which is a separate decision.
+say "issuing a certificate"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+"$BINARY" ctl cert issue-client "$NODE" --dir "$PKI" --out "$TMP" >/dev/null
+
+# 2 and 3. Identity. The root is trusted by the agent's configuration only,
+#    never system-wide: it signs whatever the control plane asks, and every
+#    TLS client on the machine would take it for any site.
+say "installing the certificate"
+scp -q $SSHOPTS "$PKI/ca.pem" "$TMP/$NODE.pem" "$TMP/$NODE-key.pem" "$SSH_USER@$ADDR:/tmp/"
+$SSH "set -e
+  sudo install -d -m 0755 /etc/llmgw
+  sudo install -m 0644 /tmp/ca.pem /etc/llmgw/ca.pem
+  sudo install -m 0644 /tmp/$NODE.pem /etc/llmgw/agent.pem
+  sudo install -m 0600 /tmp/$NODE-key.pem /etc/llmgw/agent-key.pem
+  sudo chown root:root /etc/llmgw/*
+  if [ -f /usr/local/share/ca-certificates/llmgw-ca.crt ]; then
+    sudo rm -f /usr/local/share/ca-certificates/llmgw-ca.crt
+    sudo update-ca-certificates --fresh >/dev/null 2>&1 || true
+  fi
+  rm -f /tmp/ca.pem /tmp/$NODE.pem /tmp/$NODE-key.pem"
+
+# 4. The binary, the configuration and the unit.
+# The node fetches the release CI built for this version, for its own
+# architecture, and checks it against the release's checksums — rather than
+# being handed whatever binary is on the machine running this script. A build
+# that is not a release (a developer's, with commits past the tag) has no such
+# file, and is copied as before.
+TAG="$("$BINARY" --version 2>/dev/null | awk '{print $NF}')"
+if printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$'; then
+  say "installing llmgw $TAG from the release"
+  $SSH "set -e
+    arch=\$(dpkg --print-architecture)
+    name=llmgw-$TAG-linux-\$arch
+    cd /tmp && rm -f \$name checksums.txt
+    curl -fsSL -o \$name '$RELEASES/$TAG/'\$name
+    curl -fsSL -o checksums.txt '$RELEASES/$TAG/checksums.txt'
+    grep \" \$name\\\$\" checksums.txt | sha256sum -c - >/dev/null
+    sudo install -m 0755 \$name /usr/local/bin/llmgw
+    rm -f \$name checksums.txt"
+else
+  say "installing the binary (${TAG:-unversioned}, not a release)"
+  scp -q $SSHOPTS "$BINARY" "$SSH_USER@$ADDR:/tmp/llmgw"
+  $SSH 'sudo install -m 0755 /tmp/llmgw /usr/local/bin/llmgw && rm -f /tmp/llmgw'
+fi
+
+say "writing the configuration"
+NODE_IS_HOSTNAME=no
+[ "$($SSH hostname 2>/dev/null)" = "$NODE" ] && NODE_IS_HOSTNAME=yes
+# Only what the node cannot find out for itself. Its name is its hostname, its
+# address is the one on the route to the control plane, llama-server is looked
+# for on PATH and where release archives are unpacked, GPUs are there when
+# nvidia-smi is, and memory, disk and engines are re-read while it runs. Every
+# setting written here is one that has to be kept true by hand — so an option
+# below is written only when it was given, as an override.
+{
+  echo "# $NODE, written by onboard-node.sh."
+  # Several addresses, comma separated, are every control plane the node may
+  # fail over to; a standby refuses it and it moves on to the next.
+  if [ "${SERVER#*,}" != "$SERVER" ]; then
+    echo "servers:"
+    printf '%s\n' "$SERVER" | tr ',' '\n' | sed 's/^ *//; s/^/  - "/; s/$/"/'
+  else
+    echo "server: \"$SERVER\""
+  fi
+  echo
+  echo "tls:"
+  echo "  ca: /etc/llmgw/ca.pem"
+  echo "  cert: /etc/llmgw/agent.pem"
+  echo "  key: /etc/llmgw/agent-key.pem"
+  # The certificate's common name is --node, and the control plane refuses a
+  # stream whose node id differs from it. Said explicitly only when the
+  # hostname would say something else.
+  [ "$NODE_IS_HOSTNAME" = yes ] || echo "node_id: $NODE"
+  [ -n "$MGMT_OVERRIDE" ] && echo "mgmt_addr: \"$MGMT_OVERRIDE\""
+  [ -n "$MGMT_IF_OVERRIDE" ] && echo "mgmt_interface: $MGMT_IF_OVERRIDE"
+  if [ -n "$FABRIC_NAME" ]; then
+    # Fabric membership is the one thing that cannot be found: OpenSM's default
+    # subnet prefix is the same on every fabric, so a matching prefix proves
+    # nothing and a wrong guess hangs the first all-reduce.
+    echo "fabrics:"
+    echo "  - name: $FABRIC_NAME"
+    echo "    hcas: [$(echo "$FABRIC_HCAS" | sed 's/,/, /g')]"
+  fi
+  if [ -n "$NVIDIA_SMI" ] || [ "$IB_ROOT" != /sys/class/infiniband ]; then
+    echo "discovery:"
+    [ -n "$NVIDIA_SMI" ] && echo "  nvidia_smi: \"$NVIDIA_SMI\""
+    [ "$IB_ROOT" != /sys/class/infiniband ] && echo "  ib_root: $IB_ROOT"
+  fi
+  if [ -n "$LLAMACPP_BIN$VLLM_BIN$SGLANG_PYTHON" ]; then
+    echo "engines:"
+    [ -n "$LLAMACPP_BIN" ] && printf '  llamacpp:\n    bin: "%s"\n' "$LLAMACPP_BIN"
+    [ -n "$VLLM_BIN" ] && printf '  vllm:\n    bin: "%s"\n' "$VLLM_BIN"
+    [ -n "$SGLANG_PYTHON" ] && printf '  sglang:\n    python: "%s"\n' "$SGLANG_PYTHON"
+  fi
+  true
+} > "$TMP/agent.yaml"
+scp -q "$TMP/agent.yaml" "$SSH_USER@$ADDR:/tmp/agent.yaml"
+
+cat > "$TMP/llmgw-agent.service" <<'UNIT'
+[Unit]
+Description=llmgw node agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/llmgw agent --config /etc/llmgw/agent.yaml
+# Root, because the agent launches engines and needs device access. Engines
+# outlive a restart of this unit and are adopted again on the next start, so
+# KillMode must not take the whole process group with it.
+KillMode=process
+Restart=on-failure
+RestartSec=2s
+# RDMA pins the buffers it registers, and NCCL registers a great deal: with
+# systemd's default 8 MB lock limit, an engine that drops the capability that
+# lets root ignore it fails its first collective over InfiniBand.
+LimitMEMLOCK=infinity
+StateDirectory=llmgw-agent
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+scp -q "$TMP/llmgw-agent.service" "$SSH_USER@$ADDR:/tmp/"
+
+# An engine path that is wrong, or right but unrunnable, is the failure this
+# node type is most likely to have, and it is invisible: the agent registers
+# healthy and every shard placed on it dies with "executable file not found"
+# or a missing shared library. Checked here because it is cheap here and
+# expensive later — llama-server on node05 was present, executable, and could
+# not start for want of libgomp1, and the node reported ready throughout.
+check_engine() {
+  [ -n "$2" ] || return 0
+  if $SSH "test -x '$2'" 2>/dev/null; then
+    if $SSH "'$2' --version >/dev/null 2>&1 || '$2' --help >/dev/null 2>&1"; then
+      say "$1: $2 runs"
+      return 0
+    fi
+    ENGINE_PROBLEMS="$ENGINE_PROBLEMS
+  $1 at $2 exists but will not run. Usually a missing shared library:
+    ssh $SSH_USER@$ADDR ldd $2 | grep 'not found'"
+    return 0
+  fi
+  ENGINE_PROBLEMS="$ENGINE_PROBLEMS
+  $1 is configured at $2, which is not an executable on $NODE."
+}
+ENGINE_PROBLEMS=
+if [ -n "$LLAMACPP_BIN$VLLM_BIN$SGLANG_PYTHON" ]; then
+  say "checking the engines"
+  check_engine llamacpp "$LLAMACPP_BIN"
+  check_engine vllm "$VLLM_BIN"
+  check_engine sglang "$SGLANG_PYTHON"
+fi
+
+say "starting the agent"
+$SSH 'set -e
+  sudo install -m 0644 -o root -g root /tmp/agent.yaml /etc/llmgw/agent.yaml
+  sudo install -m 0644 /tmp/llmgw-agent.service /etc/systemd/system/llmgw-agent.service
+  rm -f /tmp/agent.yaml /tmp/llmgw-agent.service
+  sudo systemctl daemon-reload
+  sudo systemctl enable --now llmgw-agent >/dev/null
+  sudo systemctl restart llmgw-agent'
+
+echo
+if [ -z "$LLAMACPP_BIN$VLLM_BIN$SGLANG_PYTHON" ]; then
+  say "the agent now installs the engines the control plane asks for: the"
+  say "build for this machine, checked against its publisher's checksum and run"
+  say "before the node is offered any model. 'llmgw ctl nodes' shows progress."
+fi
+if [ -n "$ENGINE_PROBLEMS" ]; then
+  echo "$NODE is onboarded but an engine will not run:$ENGINE_PROBLEMS"
+  echo
+  echo "The node will register as ready regardless. Fix this before a replica"
+  echo "is placed on it, or the shard fails and the reason is three logs away."
+  echo
+fi
+echo "$NODE onboarded. It should appear in 'llmgw ctl nodes' within a few seconds."
+echo "If it does not, the control plane's log says why — a certificate whose"
+echo "common name does not match the claimed node id is refused by design."

deploy/bootstrap/provision-node.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# Create a VM on Proxmox for a new llmgw node.
+#
+# Run on the Proxmox host. It does the half of onboarding that is about
+# hardware; onboard-node.sh does the half that is about identity, and the two
+# are separate because they are done by different people with different access.
+#
+# Idempotent only in the sense that it refuses to touch an existing VMID. A node
+# that already exists is not something a provisioning script should have an
+# opinion about.
+set -euo pipefail
+
+usage() {
+  cat >&2 <<USAGE
+usage: $0 --vmid N --name NAME --ip ADDR [options]
+
+  --vmid N          Proxmox VM id; must be free
+  --name NAME       VM name; use the node id, so the machine, the hostname and
+                    the certificate common name are the same string
+  --ip ADDR         address with prefix, e.g. 10.0.0.144/24
+  --gw ADDR         gateway (default 10.0.0.1)
+  --cores N         (default 4)
+  --cpu TYPE        QEMU CPU model (default host)
+  --memory MB       (default 8192)
+  --disk GB         (default 20)
+  --bridge NAME     (default vmbr0)
+  --storage NAME    (default local-lvm)
+  --image PATH      cloud image (default Ubuntu 24.04 in the ISO store)
+  --user NAME       cloud-init user (default ilker)
+  --sshkeys PATH    authorized_keys to install (default /root/.ssh/authorized_keys)
+USAGE
+  exit 2
+}
+
+VMID= NAME= IP= GW=10.0.0.1 CORES=4 MEMORY=8192 DISK=20
+# host, not Proxmox's kvm64 default. kvm64 hides AVX, AVX2, FMA and even
+# SSE4.2 from the guest, and an inference node without vector instructions is
+# not slightly slower, it is unusable: llama.cpp falls back to its scalar
+# backend and a 1.5B model dropped from 39 tokens a second to 5.8, with prompt
+# processing 19x worse. It cost an afternoon to find because nothing is broken
+# — every number is simply small.
+#
+# The trade is live migration: a VM pinned to the host CPU cannot move to a
+# machine with a different one. For a node whose job is arithmetic, that is
+# the right way round.
+CPU=host
+BRIDGE=vmbr0 STORAGE=local-lvm USER=ilker
+IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
+SSHKEYS=/root/.ssh/authorized_keys
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --vmid) VMID="$2"; shift 2;;
+    --name) NAME="$2"; shift 2;;
+    --ip) IP="$2"; shift 2;;
+    --gw) GW="$2"; shift 2;;
+    --cores) CORES="$2"; shift 2;;
+    --cpu) CPU="$2"; shift 2;;
+    --memory) MEMORY="$2"; shift 2;;
+    --disk) DISK="$2"; shift 2;;
+    --bridge) BRIDGE="$2"; shift 2;;
+    --storage) STORAGE="$2"; shift 2;;
+    --image) IMAGE="$2"; shift 2;;
+    --user) USER="$2"; shift 2;;
+    --sshkeys) SSHKEYS="$2"; shift 2;;
+    *) usage;;
+  esac
+done
+[ -n "$VMID" ] && [ -n "$NAME" ] && [ -n "$IP" ] || usage
+
+if qm status "$VMID" >/dev/null 2>&1; then
+  echo "VM $VMID already exists. Pick a free id; this script will not adopt one." >&2
+  exit 1
+fi
+[ -f "$IMAGE" ] || { echo "no cloud image at $IMAGE" >&2; exit 1; }
+
+echo "creating $NAME as VM $VMID at $IP"
+qm create "$VMID" \
+  --name "$NAME" --cores "$CORES" --memory "$MEMORY" --cpu "$CPU" \
+  --net0 "virtio,bridge=$BRIDGE" --ostype l26 --agent enabled=1
+
+# Imported rather than installed: a cloud image plus cloud-init is the whole
+# reason a node takes a minute to build instead of an afternoon.
+qm importdisk "$VMID" "$IMAGE" "$STORAGE" >/dev/null
+qm set "$VMID" --scsihw virtio-scsi-pci --scsi0 "$STORAGE:vm-$VMID-disk-0,discard=on,ssd=1" >/dev/null
+qm disk resize "$VMID" scsi0 "${DISK}G" >/dev/null
+qm set "$VMID" --ide2 "$STORAGE:cloudinit" --boot order=scsi0 >/dev/null
+qm set "$VMID" \
+  --ipconfig0 "ip=$IP,gw=$GW" \
+  --nameserver "$GW 8.8.8.8" \
+  --ciuser "$USER" \
+  --sshkeys "$SSHKEYS" >/dev/null
+
+qm start "$VMID"
+echo "started. cloud-init takes a minute; then run onboard-node.sh from the CA host."

deploy/container/Dockerfile

@@ -0,0 +1,40 @@
+# The llmgw control plane as a container image, for deploy/helm/llmgw.
+#
+# The project publishes binaries, not an image, so this is built where the
+# image is to live:
+#
+#   docker build -f deploy/container/Dockerfile --build-arg VERSION=v0.11.1 \
+#     -t registry.internal/llmgw:v0.11.1 .
+#   docker push registry.internal/llmgw:v0.11.1
+#
+# The binary is static (CGO_ENABLED=0, as every release is), so the image is
+# that one file on a base with nothing else in it: no shell, no package
+# manager. `kubectl exec ... -- llmgw ctl status` still works, because it
+# runs the binary rather than a shell.
+#
+# Only the control plane runs from it. An agent installs engines on its
+# machine, manages its GPUs and supervises processes there as root, which is
+# what a container is built to prevent: docs/kubernetes.md.
+
+FROM golang:1.26 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+ARG VERSION=dev
+RUN CGO_ENABLED=0 go build -trimpath \
+      -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${VERSION}" \
+      -o /out/llmgw ./cmd/llmgw && \
+    mkdir -p /out/state
+
+FROM gcr.io/distroless/static-debian12:nonroot
+COPY --from=build /out/llmgw /usr/local/bin/llmgw
+# The chart mounts server.yaml, the certificates and the token under
+# /etc/llmgw, and the SQLite store, when it is one, under /var/lib/llmgw —
+# owned by the user the server runs as, so a volume Docker fills from the
+# image is writable without Kubernetes' fsGroup.
+COPY --from=build --chown=65532:65532 /out/state /var/lib/llmgw
+USER 65532:65532
+EXPOSE 8080 7443 9091
+ENTRYPOINT ["/usr/local/bin/llmgw"]
+CMD ["server", "--config", "/etc/llmgw/server.yaml"]

deploy/eval/arithmetic.yaml

@@ -0,0 +1,58 @@
+# Arithmetic a small instruction model gets right: sums, products and a
+# little reading, each answer scored by the last number in it. A quantisation
+# that has gone wrong, or a chat template that no longer matches the
+# weights, shows up here as a falling score long before anyone notices it in
+# conversation.
+#
+#   llmgw ctl eval MODEL --suite arithmetic
+#   llmgw ctl model update MODEL --eval arithmetic --min-score 0.8
+#
+# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite
+# there of the same name replaces this one.
+name: arithmetic
+description: Sums, products and word problems, each scored by the number in its answer.
+threshold: 0.7
+system: You are a careful calculator. Answer with the number only, without words or units.
+max_tokens: 64
+cases:
+  - id: add-small
+    prompt: What is 17 + 25?
+    number: 42
+  - id: add-carry
+    prompt: What is 389 + 476?
+    number: 865
+  - id: subtract
+    prompt: What is 1000 - 357?
+    number: 643
+  - id: subtract-negative
+    prompt: What is 12 - 30?
+    number: -18
+  - id: multiply
+    prompt: What is 12 * 12?
+    number: 144
+  - id: multiply-larger
+    prompt: What is 23 * 17?
+    number: 391
+    weight: 2
+  - id: divide
+    prompt: What is 144 / 6?
+    number: 24
+  - id: decimal
+    prompt: What is 2.5 * 4?
+    number: 10
+  - id: percent
+    prompt: What is 15% of 200?
+    number: 30
+  - id: words-apples
+    prompt: Ana has 7 apples and buys 5 more, then gives 3 away. How many apples does she have?
+    number: 9
+    weight: 2
+  - id: words-time
+    prompt: A train leaves at 14:00 and the trip takes 150 minutes. How many hours does the trip take?
+    number: 2.5
+    tolerance: 0.01
+    weight: 2
+  - id: order-of-operations
+    prompt: What is 2 + 3 * 4?
+    number: 14
+    weight: 2

deploy/eval/json-format.yaml

@@ -0,0 +1,94 @@
+# Following a format: asked for JSON of a given shape, does the model give
+# it — the thing an application parsing its answers depends on, and the
+# first to go when a chat template drifts. Each answer is read as JSON (a
+# code fence or a sentence around it is forgiven) and held to a schema.
+#
+#   llmgw ctl eval MODEL --suite json-format
+#
+# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite
+# there of the same name replaces this one.
+name: json-format
+description: Answers asked for as JSON of a given shape, held to a schema.
+threshold: 0.7
+system: You answer with a single JSON value and nothing else.
+max_tokens: 200
+cases:
+  - id: person
+    prompt: >-
+      Give a JSON object for a person named Ada Lovelace, born in 1815, with the
+      keys "name" (a string) and "born" (a number).
+    json_schema:
+      type: object
+      required: [name, born]
+      properties:
+        name: {type: string, pattern: "Ada"}
+        born: {type: integer, minimum: 1815, maximum: 1815}
+
+  - id: list-of-colours
+    prompt: Give a JSON array of exactly three colour names, as strings.
+    json_schema:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items: {type: string, minLength: 1}
+
+  - id: boolean-answer
+    prompt: >-
+      Is water wet? Answer as a JSON object with one key, "answer", whose
+      value is true or false.
+    json_schema:
+      type: object
+      required: [answer]
+      properties:
+        answer: {type: boolean}
+
+  - id: nested
+    prompt: >-
+      Give a JSON object describing a book: "title" (a string), "author" (an
+      object with "first" and "last", both strings) and "pages" (a whole number
+      above zero). Use any book.
+    json_schema:
+      type: object
+      required: [title, author, pages]
+      properties:
+        title: {type: string, minLength: 1}
+        author:
+          type: object
+          required: [first, last]
+          properties:
+            first: {type: string}
+            last: {type: string}
+        pages: {type: integer, exclusiveMinimum: 0}
+    weight: 2
+
+  - id: enum-choice
+    prompt: >-
+      Classify the sentence "I love this product!" as positive, negative or
+      neutral. Answer as a JSON object {"sentiment": "..."} using one of those
+      three words in lower case.
+    json_schema:
+      type: object
+      required: [sentiment]
+      properties:
+        sentiment: {enum: [positive]}
+    weight: 2
+
+  - id: numbers
+    prompt: 'Give a JSON object {"sum": N} where N is the sum of 4, 5 and 6.'
+    json_schema:
+      type: object
+      required: [sum]
+      properties:
+        sum: {const: 15}
+
+  - id: no-extra-keys
+    prompt: >-
+      Give a JSON object with exactly two keys, "city" and "country", for
+      Paris. No other keys.
+    json_schema:
+      type: object
+      required: [city, country]
+      additionalProperties: false
+      properties:
+        city: {type: string}
+        country: {type: string}

deploy/examples/agent.yaml

@@ -0,0 +1,113 @@
+# llmgw agent configuration, one per GPU node.
+#
+# The agent dials out to the control plane and keeps one stream open. Engines
+# keep serving if the agent restarts: the router talks to them directly, and
+# orphan adoption picks them up again on the next start.
+
+# Everything a node can find out about itself, it does: its id is its hostname,
+# its address is the one on the route to the control plane, llama-server is
+# looked for on PATH and in /opt/llama.cpp, GPUs are there when nvidia-smi is,
+# weights are fetched into /var/lib/llmgw-weights and looked for there, and
+# memory, disk and installed engines are re-read while the agent runs. So a
+# plain CPU node needs only the two blocks below, and the same file on every
+# node. What follows them are overrides, for when the defaults are wrong.
+
+server: "http://llmgw-server.internal:7443"
+
+# The agent's half of mutual TLS. The certificate's common name must be this
+# node's id — its hostname, unless node_id says otherwise — because the control
+# plane compares the two and refuses the stream when they disagree:
+#
+#   llmgw ctl cert issue-client gpu-a-01 --dir /etc/llmgw/pki
+#
+# With this set, `server` above must be an https:// address — an agent holding
+# certificates and dialling http:// is refused at startup rather than connecting
+# in the clear without noticing.
+#
+# tls:
+#   ca: /etc/llmgw/ca.pem
+#   cert: /etc/llmgw/agent.pem
+#   key: /etc/llmgw/agent-key.pem
+
+# ---- overrides ---------------------------------------------------------------
+
+# node_id: gpu-a-01          # when it is not the hostname
+
+# The address engines are reachable on, and the address NCCL bootstraps over.
+# Never a fabric address: NCCL rendezvouses over TCP before moving to RDMA.
+# mgmt_addr: "10.0.0.11"
+# mgmt_interface: eth0
+
+# Free-form, for a profile's node_selector. Nothing needs them; do not restate
+# what is measured (memory, GPUs, engines), because a label goes stale.
+# labels:
+#   rack: r12
+
+heartbeat_interval: 5s
+reconnect_base: 1s
+reconnect_max: 30s
+
+# Each fabric this node's adapters are on, by name. The name is checked against
+# what the adapters report — the subnet managers every port on one fabric sees —
+# so two independent fabrics given one name are placed as two and the cluster
+# page says so; give each its own. The rate is measured, not read from here.
+#
+# A node with no fabrics is its own single-node island: it can host single-node
+# replicas and will never be given a multi-node one. docs/fabrics.md has more.
+fabrics:
+  - name: ib-a
+    hcas: [mlx5_0, mlx5_1, mlx5_2, mlx5_3]
+
+discovery:
+  # Worth setting where the driver lives outside the default paths, which
+  # containerized driver installs often do.
+  nvidia_smi: ""
+  ib_root: /sys/class/infiniband
+  # NVLink topology comes from `nvidia-smi topo -m` on every build; a binary
+  # built with `-tags nvml` reads it from NVML instead, when this is set.
+  prefer_nvml: true
+
+# Where this node keeps model weights besides /var/lib/llmgw-weights, which is
+# where fetched weights land and is always looked in. Storage differs at
+# every installation and llmgw deliberately does not own it: a Lustre mount, an
+# image exported over the fabric with SRP or NVMe-oF, local NVMe, or a copy
+# made by hand all look identical from here.
+#
+# What it buys is placement preferring a node that already holds the model over
+# one that must first move tens of gigabytes. That matters most where fabrics
+# are isolated from one another, because weights in one fabric are not weights
+# in another and the only path between them is the management network.
+#
+# model_dirs:
+#   - /var/lib/llmgw-models
+#   - /mnt/lustre/models
+
+# The agent installs the engines the control plane names (see `engines:` in
+# server.yaml) under /opt/llmgw/engines: the build for this machine — CUDA when
+# an NVIDIA driver is loaded — checked against its publisher's checksum, with
+# the OS packages it needs, and run before the node takes any model. llama.cpp
+# is installed this way today. Naming a binary below opts that engine out and
+# uses yours instead; vLLM and SGLang still have to be named until the agent
+# installs them too.
+# engines_dir: /opt/llmgw/engines
+
+engines:
+  vllm:
+    bin: /opt/venvs/vllm/bin/vllm
+    # How a replica spanning nodes is launched. mp, the default, is what vLLM
+    # documents today and needs nothing but vLLM; ray is for a vLLM too old
+    # for mp's multi-node flags, and needs Ray on every node.
+    launch_mode: mp       # "mp" or "ray"
+    # ray_bin: /opt/venvs/vllm/bin/ray
+  sglang:
+    # SGLang is launched as a module, which is its documented entry point.
+    python: /opt/venvs/sglang/bin/python
+
+supervisor:
+  work_dir: /var/lib/llmgw-agent
+  # Engine output is the only diagnosis when a model fails to load, so keep a
+  # useful tail of it.
+  log_lines: 512
+  # Engines need time to free GPU memory cleanly before being killed.
+  stop_timeout: 60s
+  health_interval: 2s

deploy/examples/server.yaml

@@ -0,0 +1,287 @@
+# llmgw router configuration (phase 1).
+#
+# The endpoint list is static here. From phase 3 it comes from the control
+# plane instead and this section disappears; everything else stays.
+#
+# Any field can be overridden from the environment with an LLMGW_ prefix and
+# __ for nesting:  LLMGW_ROUTER__RETRIES=3
+
+listen: ":8080"        # client-facing OpenAI API
+admin_listen: "127.0.0.1:9090"  # dashboard, management API, pprof — keep it local
+# Metrics only, on their own port, so Prometheus can reach them without pprof
+# being reachable too. Empty means off; metrics stay on admin_listen either way.
+# metrics_listen: "0.0.0.0:9091"
+# Where node agents connect. Separate from the client port so the fleet-facing
+# surface can be firewalled independently.
+agent_listen: ":7443"
+
+# Mutual TLS on the agent port (plan §5.6). With it, a node's identity is taken
+# from its certificate's common name and an agent claiming a different node id
+# is refused. Without it the port would be plaintext HTTP/2 and anyone who can
+# reach it could claim to be any node, so the control plane refuses to start
+# unless `agent_insecure: true` is set — and then listens on loopback unless
+# agent_listen names an address. That is for one machine or a test.
+#
+# These certificates come from llmgw's own authority, not a public one: public
+# authorities stopped issuing the clientAuth usage, so no Let's Encrypt
+# certificate can authenticate an agent.
+#
+#   llmgw ctl cert init-ca --dir /etc/llmgw/pki
+#   llmgw ctl cert issue-server llmgw-ctl --host 10.0.0.140 --dir /etc/llmgw/pki
+#
+# Every address an agent might dial has to appear in --host, bare IP addresses
+# included: hostname verification reads subject alternative names and ignores
+# the common name entirely.
+#
+# This covers the fleet-facing port only. The client-facing API above is public
+# and belongs behind a publicly trusted certificate.
+#
+# agent_tls:
+#   ca: /etc/llmgw/ca.pem
+#   cert: /etc/llmgw/server.pem
+#   key: /etc/llmgw/server-key.pem
+
+# The public page at "/". Someone who reaches this address without a key needs a
+# route to getting one, and the gateway cannot guess who to send them to.
+#
+# landing:
+#   contact: "platform@example.com"   # or an https:// URL, or "#platform on Slack"
+#   notice: "Internal use only."
+
+# API keys on the client-facing port (plan §7.9). Off by default, because a
+# gateway on a trusted network with no keys issued still has to serve — but
+# nothing else protects that port, so turning it on is what makes it safe to
+# expose.
+#
+#   llmgw keys init --store /var/lib/llmgw/llmgw.db
+#   llmgw keys create --store /var/lib/llmgw/llmgw.db --project default "laptop"
+#
+# The key is printed once. Only its hash is stored, so there is nothing to
+# recover it from.
+#
+# auth:
+#   enabled: true
+#   store: /var/lib/llmgw/llmgw.db
+#   # How long a resolved key is trusted before being read again. This is the
+#   # price of keeping the database off the request path: it bounds how long a
+#   # revoked key keeps working.
+#   cache_ttl: 30s
+#   # How long a rejected key is remembered as rejected, so a client looping
+#   # with a bad key cannot become a database read per request.
+#   negative_ttl: 5s
+#
+#   # Serve the signup form. What it creates is a pending account that can do
+#   # nothing until `llmgw users approve` places it in a project, so this is not
+#   # a way in — it only moves key creation from you to the person who needs one.
+#   # Off, there is no form and you issue keys with `llmgw keys create --claim`.
+#   signup_open: true
+#
+#   # What each model costs, in micro-units per thousand tokens. A unit is
+#   # whatever you decide: self-hosted models have no per-token price, so it can
+#   # be GPU-seconds, a notional rate, or 1000 everywhere — which turns budgets
+#   # into plain token quotas.
+#   #
+#   # A model priced at zero is exempt from budget checks, which is what lets a
+#   # key with nothing left still be served a cheap fallback.
+#   default_price: { prompt_per_1k: 0, completion_per_1k: 0 }
+#   pricing:
+#     llama-3.3-70b: { prompt_per_1k: 1000, completion_per_1k: 3000 }
+#     qwen2.5-32b:   { prompt_per_1k: 400,  completion_per_1k: 1200 }
+#
+#   # Usage rows are written in batches off the request path. Beyond buffer_size
+#   # they are dropped rather than blocking a request: losing some accounting is
+#   # bad, turning a stalled database into an outage is worse.
+#   flush_interval: 200ms
+#   batch_size: 500
+#   buffer_size: 8192
+#
+#   # How long the record of each request is kept (what `ctl request` reads).
+#   # Charts, totals and budgets come from five-minute sums that are kept, so
+#   # this only bounds the table that grows by a row a request. 0 keeps all.
+#   usage_retention: 2160h   # 90 days
+
+router:
+  scrape_interval: 2s
+  scrape_timeout: 1s
+  # How long an endpoint may go unscraped before it is scored down. It is never
+  # dropped for staleness alone: if the whole pool went stale there would be
+  # nowhere left to send anything.
+  stale_after: 10s
+
+  # Additional endpoints to try after a failure, and only while nothing has
+  # reached the client yet.
+  retries: 2
+  # How long a failing endpoint leaves the candidate pool. A long fallback list
+  # with no cooldown turns one endpoint's rate limit into a cluster-wide retry
+  # storm.
+  cooldown: 15s
+  # Consecutive failures that open the breaker. Set to 1 for pure cooldown
+  # behaviour.
+  failure_threshold: 3
+
+  default_profile: chat        # chat | batch | long-context | debug
+
+  # Approximate prefix routing (plan §7.5 tier 1): send a request to the replica
+  # that has probably already prefilled its prefix.
+  #
+  # It earns its keep when the working set does not fit in one replica's cache.
+  # With a handful of prompts and a large cache, scattering is free — every
+  # replica ends up holding everything — and this only adds constraint. Measured
+  # with sim-engines whose caches were too small for the working set: cache hits
+  # went from 22.5% to 81.7%.
+  #
+  # Watch llmgw_prefix_decisions_total to tune it. A high
+  # load_balance_override count means the guard is doing its job and affinity is
+  # not getting a chance; a high cache_miss_min_load means match_ratio or
+  # min_match is too strict for your traffic.
+  prefix:
+    enabled: false
+    # The shortest match worth acting on, in bytes. Below this the overlap is
+    # coincidence — two English prompts share "The".
+    min_match: 64
+    # The share of the prompt that must match. A short shared header on a very
+    # long prompt saves almost no prefill.
+    match_ratio: 0.3
+    # The imbalance guard, and both must trip before affinity is abandoned.
+    # Absolute alone fires on an idle cluster where one replica has two requests
+    # and another none; relative alone fires on a busy one where 200 against 180
+    # is a rounding error. Without the guard the cache hit rate rises while p99
+    # collapses.
+    balance_abs: 8
+    balance_rel: 1.5
+    # An engine evicts on its own schedule, so an old record may describe a
+    # cache that is gone.
+    ttl: 10m
+    max_nodes: 100000
+  session_header: x-session-id # affinity key; falls back to the `user` field
+  # Ask engines for usage even when the client did not, so token accounting
+  # works regardless of client behaviour. The extra chunk is dropped on the way
+  # back to a client that did not ask for it.
+  inject_usage: true
+  max_body_bytes: 33554432
+  # Memory for the answers of projects that reuse them (llmgw keys cache),
+  # all together; the least recently used go first. Nothing is reused until a
+  # project turns it on.
+  # cache:
+  #   max_bytes: 134217728     # 128 MB
+  #   max_entry_bytes: 1048576 # 1 MB
+
+  timeouts:
+    dial: 5s
+    response_header: 60s
+    first_token: 120s
+    idle: 60s      # between streamed tokens; catches a wedged engine
+    total: 30m
+
+  # Flow control: decides *when* a request may proceed, before scheduling
+  # decides where it goes. Without it a batch workload starves interactive
+  # traffic, because an engine queue is FIFO and knows nothing about tenants.
+  admission:
+    enabled: true
+    # With auth on, the key decides the band and this header is ignored. With
+    # auth off the header is trusted, so any client can promote itself into the
+    # top band — do not expose the port in that configuration.
+    band_header: x-llmgw-band
+    default_band: gold
+    # A band waits once pool saturation passes its ceiling, so the cluster
+    # degrades from the bottom up. A ceiling of 1.0 means "flow up to the
+    # healthy limit"; use a value above 1 for a band that must never wait.
+    bands:
+      - { name: platinum, priority: 400, saturation_ceiling: 1.00 }
+      - { name: gold,     priority: 300, saturation_ceiling: 0.85 }
+      - { name: silver,   priority: 200, saturation_ceiling: 0.60 }
+      - { name: bronze,   priority: 100, saturation_ceiling: 0.30 }
+    # Drop a request that has waited this long: the client has usually given up,
+    # and sending the GPU work nobody is waiting for helps no one.
+    queue_ttl: 30s
+    # Reject immediately once a band's queue is this deep, rather than letting
+    # it accumulate silently.
+    queue_capacity_per_band: 2000
+    interval: 10ms
+
+  # What the scorers normalize against. Measure these with `ctl bench` rather
+  # than guessing: target_waiting in particular governs how the whole system
+  # behaves under load. Too low starves the GPU, too high brings back queueing
+  # delay.
+  scoring:
+    target_waiting: 4
+    target_inflight: 8
+    kv_ceiling: 0.9
+    session_load_factor: 1.25
+
+# How aggressively the control plane reconciles.
+# The engines every node installs, and at which version. Unset keeps the
+# versions this release was checked against (llama.cpp b10991). Each agent
+# picks the build for its own hardware and installs it itself; changing a
+# version here reaches every node on its next connect.
+# engines:
+#   llamacpp: b10991
+
+control:
+  interval: 5s
+  base_backoff: 10s
+  max_backoff: 10m
+  # Node expiry is staged deliberately: a network blip must not tear down
+  # replicas that are still serving, and rebuilding a multi-node replica costs
+  # tens of minutes of model loading.
+  unreachable_after: 15s
+  lost_after: 60s
+  port_range: [20000, 20999]
+  mgmt_interface: eth0
+
+# Each model needs a source — a weights path or a HuggingFace id — and at least
+# one profile if the control plane is to place it. Without profiles the model is
+# catalogued but never started, which is the router-only mode below.
+models:
+  - name: llama-3.3-70b
+    source: meta-llama/Llama-3.3-70B-Instruct
+    aliases: [llama]
+    fallbacks: [qwen2.5-32b]
+    routing_profile: chat
+    scaling: { min: 1, max: 4 }
+    profiles:
+      # Two nodes of four H100s each. A multi-node profile requires a fabric,
+      # and a replica never spans two of them.
+      - name: tp8
+        engine: vllm
+        gpu_class: h100-80g
+        tp: 8
+        nodes: 2
+        gpus_per_node: 4
+        priority: 100
+        weight: 8
+        startup_timeout: 30m
+      # Where a whole node is free, one node is cheaper to schedule and faster
+      # to start than two.
+      - name: tp4-a100
+        engine: vllm
+        gpu_class: a100-40g
+        tp: 4
+        priority: 50
+        weight: 3
+        startup_timeout: 20m
+
+  - name: qwen2.5-32b
+    source: Qwen/Qwen2.5-32B-Instruct
+    aliases: [qwen]
+    routing_profile: batch
+    scaling: { min: 1, max: 2 }
+    profiles:
+      - name: tp2
+        engine: sglang
+        gpu_class: h100-80g
+        tp: 2
+        priority: 100
+        weight: 2
+        startup_timeout: 15m
+
+# A static replica list, used only when no model declares a profile. That is the
+# router-only mode for testing against sim-engines; with the control plane
+# running, agents provide the replicas instead.
+#
+# endpoints:
+#   - id: sim-1
+#     url: http://127.0.0.1:8001
+#     models: [llama-3.3-70b]
+#     pool: local
+#     weight: 1

deploy/ha/README.md

@@ -0,0 +1,172 @@
+# More than one control plane
+
+llmgw handles the hard half of this itself: only one control plane places work,
+and agents find whichever one is leading. What it does not do is move client
+traffic, because that happens in front of both and llmgw is not in front of
+anything.
+
+This directory is the missing half. It is a pattern rather than a product:
+substitute your own load balancer if you have one.
+
+## What llmgw does on its own
+
+**One leader.** Leadership is a lease in the shared store. A second control
+plane starts, sees the lease, and stands by — it places nothing, evicts
+nothing and drains nothing. Start one by accident and your cluster is
+unharmed.
+
+**Agents follow.** A standby refuses agent streams, so agents move to the
+leader by themselves. Give each agent both addresses:
+
+```yaml
+servers:
+  - "https://ctl-1.internal:7443"
+  - "https://ctl-2.internal:7443"
+```
+
+Measured on a cluster: leadership moved three seconds after the leader was
+stopped, every agent had arrived six seconds later, and every replica was
+adopted rather than restarted — the engines never stopped serving.
+
+## What it does not do
+
+Client traffic. During that same failover the standby served inference
+correctly on its own port while the public address returned 502, because
+nothing in front of the two had moved.
+
+So something has to. The options, in the order most people should consider
+them:
+
+**A load balancer you already run.** Health-check `/leader` on each control
+plane and send traffic to whichever answers. This is the right answer if you
+have one, and it needs nothing else from this directory.
+
+**A floating address.** `keepalived.conf.example` here moves one IP between
+the two machines. Fewer moving parts than a load balancer and no extra hop,
+at the cost of one machine carrying all the traffic.
+
+**DNS.** Works, eventually. A record with a short TTL is a failover measured
+in whatever your resolvers actually honour rather than what you set, which on
+a bad day is minutes. Fine for a cluster people use interactively, wrong for
+one an agent is driving.
+
+## Check `/leader`, not `/health`
+
+This is the one thing to get right, and the obvious choice is the wrong one.
+
+`/health` says the process is up. It says nothing about whether it leads,
+and a standby is exactly that case: alive, answering, and holding no endpoints
+at all — its reconciler placed nothing and it has no agent streams to adopt
+from. A standby passes client requests on to the leader, so traffic sent to
+one still works — until the leader is the machine that was lost, and there
+is nobody to pass them to.
+
+`/leader` is 200 on the control plane that leads and 503 on a standby. It is
+what keepalived follows for the floating address, and what a load balancer
+should send traffic by: to the one machine that answers 200.
+
+`/ready` is narrower: 200 only when this process has somewhere to send a
+request, so 503 on a standby and also on a leader with no model running yet.
+Checking it takes the portal and the admin pages away with the models — on a
+new cluster with no node yet, nobody can sign in to add one. Use it to stop
+sending inference only, if your load balancer can tell the paths apart.
+
+Both are open, because a load balancer has no key.
+
+During a failover nothing passes for about the length of the lease handover:
+three seconds when the leader is stopped cleanly, up to the lease TTL when it
+is not. A proxy that waits that long for a healthy machine rather than
+failing at once (Caddy's `lb_try_duration`) hides it from clients.
+
+**Caddy**, in front of three control planes — the end of
+[deploy/proxy/Caddyfile](../proxy/Caddyfile) has it with the rest of the
+settings:
+
+```
+reverse_proxy 10.0.0.157:8080 10.0.0.158:8080 10.0.0.159:8080 {
+	lb_policy first
+	health_uri /leader
+	health_interval 2s
+	lb_try_duration 15s
+	flush_interval -1
+}
+```
+
+With a floating address the address already follows the leader: give Caddy
+that one address instead.
+
+Not the admin port, for a different reason: it serves pprof, and pprof can
+dump the process heap, where API keys sit in plaintext.
+
+## Both control planes need the same store
+
+Leadership lives in it, and so do keys, budgets and conversations. Two control
+planes on two SQLite files are two clusters that happen to share a name.
+
+```yaml
+auth:
+  store: "@/etc/llmgw/secrets/store-dsn"
+```
+
+See [docs/install.md](../../docs/install.md) for moving an existing
+installation onto PostgreSQL without reissuing every key.
+
+## The store itself: PostgreSQL under Patroni
+
+Two control planes on one PostgreSQL have moved the single point of failure,
+not removed it. Patroni keeps PostgreSQL on two machines, one streaming to the
+other, and promotes the standby when the primary is lost. It keeps its leader
+lock in etcd, and etcd decides only with a majority — so three members, not
+two: two machines that lose sight of each other must not both decide they are
+the primary. The third member can be any machine that is up; it holds a vote,
+not data.
+
+On the reference cluster:
+
+| machine | etcd | PostgreSQL |
+|---|---|---|
+| llmgw-ctl (control plane) | member | — |
+| llmgw-pg01 | member | Patroni |
+| llmgw-ctl02 (second control plane) | member | Patroni |
+
+`llmgw server init --patroni user@host --patroni user@host` sets all of it up
+over ssh and moves the store in — see [install.md](../../docs/install.md).
+It looks before it acts at every step, so it is also how an existing cluster
+is checked: run against one that is up, it changes nothing. What it writes
+is in `etcd.default.example` (one member's `/etc/default/etcd`) and
+`patroni.yml.example` (one node's `/etc/patroni/config.yml`), for anyone
+doing it by hand; passwords are generated into `/root/llmgw-pg` on each
+database machine.
+
+**Give llmgw every member, and ask for the writable one:**
+
+```
+postgres://llmgw:…@10.0.0.149:5432,10.0.0.150:5432/llmgw?sslmode=disable&target_session_attrs=read-write
+```
+
+The driver connects to whichever member accepts writes, and reconnects to the
+new one after a failover. No floating address or HAProxy is needed for that.
+`llmgw server backup` reads the same address and dumps from a standby when
+there is one.
+
+Measured on the reference cluster, with the gateway serving throughout:
+
+- **Planned switchover** (`patronictl switchover`): the control plane logged
+  one failed lease renewal, reconnected to the new primary, and kept its
+  leadership; nothing else noticed.
+- **The primary's machine switched off**: the standby was promoted 24 seconds
+  later — the 30-second TTL in `patroni.yml` — and the control plane rode it
+  out without losing leadership or a replica. Started again, the old primary
+  rejoined as a standby by itself.
+
+**Watching it.** For a store of several hosts the control plane reads the
+cluster from each member's Patroni (port 8008) and publishes
+`llmgw_store_member{member,host,role,state}`, `llmgw_store_replica_lag_bytes`
+and `llmgw_store_patroni_up`; a host of the address that the cluster no longer
+lists is a member in state `missing`. `llmgw ctl status` prints it as one
+line, and `deploy/monitoring/llmgw-rules.yml` alerts on no leader, a member
+not streaming or missing, and a standby too far behind to be promoted.
+
+Not done here, and worth doing in production: a watchdog (`softdog`) so a
+primary that has lost the lock but not died cannot keep accepting writes, TLS
+on etcd and between PostgreSQL members, and more than one standby.

deploy/ha/etcd.default.example

@@ -0,0 +1,10 @@
+# llmgw: one member of the three that hold Patroni's leader lock (140, 149, 150).
+ETCD_NAME=llmgw-pg01
+ETCD_DATA_DIR=/var/lib/etcd/default
+ETCD_LISTEN_PEER_URLS=http://10.0.0.149:2380
+ETCD_LISTEN_CLIENT_URLS=http://10.0.0.149:2379,http://127.0.0.1:2379
+ETCD_INITIAL_ADVERTISE_PEER_URLS=http://10.0.0.149:2380
+ETCD_ADVERTISE_CLIENT_URLS=http://10.0.0.149:2379
+ETCD_INITIAL_CLUSTER=llmgw-ctl=http://10.0.0.140:2380,llmgw-pg01=http://10.0.0.149:2380,llmgw-ctl02=http://10.0.0.150:2380
+ETCD_INITIAL_CLUSTER_STATE=new
+ETCD_INITIAL_CLUSTER_TOKEN=llmgw-patroni

deploy/ha/keepalived.conf.example

@@ -0,0 +1,67 @@
+# A floating address for two control planes.
+#
+# One IP that lives on whichever machine is up. Clients and the reverse proxy
+# in front of llmgw point at the address, not at either host, so a failover is
+# invisible to them.
+#
+# This is not a load balancer: all traffic goes to the holder. That is usually
+# the right trade for a control plane, which serves far less than the nodes
+# it schedules.
+#
+# Copy to /etc/keepalived/keepalived.conf on both machines, changing state,
+# priority and interface.
+
+global_defs {
+    enable_script_security
+    script_user nobody
+}
+
+# The address moves only while llmgw can actually serve, not merely while the
+# machine is powered on.
+#
+# /ready, not /health. /health is 200 on a standby, which is up, answering and
+# holding no endpoints at all — so the address would sit on a host that refuses
+# every request. /ready is 200 only when there is somewhere to send one.
+#
+# Not the admin port either: it serves pprof, which can dump the heap that
+# holds every API key.
+vrrp_script check_llmgw {
+    script "/usr/bin/curl -fsS --max-time 2 -o /dev/null http://127.0.0.1:8080/ready"
+    interval 2
+    timeout 3
+    # Two failures before giving up the address, so one slow moment does not
+    # move it. Two successes before taking it back, so a flapping gateway does
+    # not drag the address with it.
+    fall 2
+    rise 2
+    weight -40
+}
+
+vrrp_instance llmgw {
+    # MASTER on the machine you would rather serve; BACKUP on the other.
+    state MASTER
+    interface eth0
+    # Any number both machines agree on and nothing else on the segment uses:
+    # another cluster's keepalived with the same one reads as an invalid
+    # password. `llmgw server add --vip` derives one from the address.
+    virtual_router_id 51
+    # The higher one wins while both are healthy. The weight above is enough
+    # to invert this when the preferred machine's gateway is not answering.
+    priority 100
+    advert_int 1
+
+    authentication {
+        auth_type PASS
+        # Change this. It stops another host on the segment claiming the
+        # address, which is otherwise a single unicast packet away.
+        auth_pass CHANGEME
+    }
+
+    virtual_ipaddress {
+        10.0.0.150/24
+    }
+
+    track_script {
+        check_llmgw
+    }
+}

deploy/ha/patroni.yml.example

@@ -0,0 +1,68 @@
+# llmgw: the control planes' store, kept by Patroni on llmgw-pg01 and
+# llmgw-ctl02, with the leader lock in etcd on 140, 149 and 150.
+scope: llmgw
+namespace: /service/
+name: llmgw-pg01
+
+restapi:
+  listen: 10.0.0.149:8008
+  connect_address: 10.0.0.149:8008
+
+etcd3:
+  hosts: 10.0.0.140:2379,10.0.0.149:2379,10.0.0.150:2379
+
+bootstrap:
+  dcs:
+    ttl: 30
+    loop_wait: 10
+    retry_timeout: 10
+    maximum_lag_on_failover: 1048576
+    postgresql:
+      use_pg_rewind: true
+      use_slots: true
+      parameters:
+        wal_level: replica
+        hot_standby: "on"
+        max_wal_senders: 10
+        max_replication_slots: 10
+        wal_keep_size: 1GB
+        wal_log_hints: "on"
+        password_encryption: scram-sha-256
+  initdb:
+    - encoding: UTF8
+    - data-checksums
+
+postgresql:
+  listen: 127.0.0.1,10.0.0.149:5432
+  connect_address: 10.0.0.149:5432
+  data_dir: /var/lib/postgresql/16/llmgw
+  bin_dir: /usr/lib/postgresql/16/bin
+  pgpass: /var/lib/postgresql/.pgpass_patroni
+  authentication:
+    superuser:
+      username: postgres
+      password: "<from /root/llmgw-pg>"
+    replication:
+      username: replicator
+      password: "<from /root/llmgw-pg>"
+    rewind:
+      username: postgres
+      password: "<from /root/llmgw-pg>"
+  parameters:
+    unix_socket_directories: /var/run/postgresql
+  pg_hba:
+    - local all all peer
+    - host all all 127.0.0.1/32 scram-sha-256
+    - host replication replicator 10.0.0.149/32 scram-sha-256
+    - host replication replicator 10.0.0.150/32 scram-sha-256
+    - host all postgres 10.0.0.149/32 scram-sha-256
+    - host all postgres 10.0.0.150/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.140/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.149/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.150/32 scram-sha-256
+
+tags:
+  nofailover: false
+  noloadbalance: false
+  clonefrom: false
+  nosync: false

deploy/helm/llmgw/Chart.yaml

@@ -0,0 +1,17 @@
+apiVersion: v2
+name: llmgw
+description: >-
+  The llmgw control plane — the OpenAI-compatible gateway, the router and the
+  scheduler that places models on GPU and CPU nodes. The nodes themselves run
+  outside Kubernetes; see docs/kubernetes.md.
+type: application
+# The chart's own version; appVersion is the llmgw release the image holds.
+version: 0.1.0
+appVersion: "v0.11.1"
+home: https://gitea.mynodes.xyz/ilker/llmgw
+sources:
+  - https://gitea.mynodes.xyz/ilker/llmgw
+keywords:
+  - llm
+  - gateway
+  - inference

deploy/helm/llmgw/templates/NOTES.txt

@@ -0,0 +1,27 @@
+The llmgw control plane is starting as {{ include "llmgw.fullname" . }}.
+
+The admin API listens on the pod's loopback only. To reach it from here:
+
+  kubectl -n {{ .Release.Namespace }} port-forward statefulset/{{ include "llmgw.fullname" . }} 9090:9090 &
+  export LLMGW_ADMIN_TOKEN=$(kubectl -n {{ .Release.Namespace }} get secret {{ include "llmgw.adminSecret" . }} \
+    -o jsonpath='{.data.{{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}}' | base64 -d)
+  llmgw ctl status
+
+The first administrator:
+
+  kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \
+    llmgw users create you@example.com --password '<a password>'
+  kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \
+    llmgw users role you@example.com admin
+
+Agents connect to the {{ include "llmgw.fullname" . }}-agents Service on port {{ .Values.agentService.port }}:
+
+  kubectl -n {{ .Release.Namespace }} get service {{ include "llmgw.fullname" . }}-agents
+
+Its address must be in the certificate in {{ .Values.agentTLS.existingSecret }}. Nodes join from
+the machine holding llmgw's authority:
+
+  sudo llmgw node add ubuntu@gpu01 --server https://<that address>:{{ .Values.agentService.port }} \
+    --pki ./pki --admin 127.0.0.1:9090
+
+docs/kubernetes.md has the rest, and why the nodes stay outside Kubernetes.

deploy/helm/llmgw/templates/_helpers.tpl

@@ -0,0 +1,74 @@
+{{/* The release's name for everything the chart makes. */}}
+{{- define "llmgw.fullname" -}}
+{{- if contains .Chart.Name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "llmgw.selectorLabels" -}}
+app.kubernetes.io/name: {{ .Chart.Name }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{- define "llmgw.labels" -}}
+{{ include "llmgw.selectorLabels" . }}
+app.kubernetes.io/version: {{ .Values.image.tag | default .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}
+{{- end -}}
+
+{{- define "llmgw.image" -}}
+{{- if not .Values.image.repository -}}
+{{- fail "image.repository: the image built from deploy/container/Dockerfile, pushed where the cluster can pull it (the project publishes binaries, not an image)" -}}
+{{- end -}}
+{{- printf "%s:%s" .Values.image.repository (.Values.image.tag | default .Chart.AppVersion) -}}
+{{- end -}}
+
+{{- define "llmgw.adminSecret" -}}
+{{- .Values.adminToken.existingSecret | default (printf "%s-admin" (include "llmgw.fullname" .)) -}}
+{{- end -}}
+
+{{/*
+server.yaml: what the chart decides — listeners, where the certificates,
+the token and the store are mounted — laid over .Values.config. The chart's
+keys win, because each names a port or a path the pod is built around.
+*/}}
+{{- define "llmgw.serverConfig" -}}
+{{- $store := "/var/lib/llmgw/llmgw.db" -}}
+{{- if eq .Values.store.type "postgres" -}}
+{{- $store = "@/etc/llmgw/store/dsn" -}}
+{{- end -}}
+{{- $base := dict
+  "listen" ":8080"
+  "admin_listen" "127.0.0.1:9090"
+  "metrics_listen" ":9091"
+  "agent_listen" ":7443"
+  "admin_token_file" "/etc/llmgw/admin/admin-token"
+  "agent_tls" (dict "ca" "/etc/llmgw/tls/ca.pem" "cert" "/etc/llmgw/tls/server.pem" "key" "/etc/llmgw/tls/server-key.pem")
+  "auth" (dict "store" $store)
+-}}
+{{- if .Values.offlineChecksums.configMap -}}
+{{- $_ := set $base "offline" (dict "checksums" "/etc/llmgw/offline/offline.sha256") -}}
+{{- end -}}
+{{- $cfg := mustMergeOverwrite (deepCopy (.Values.config | default dict)) $base -}}
+# Made by the llmgw Helm chart from its values. Every key: docs/reference.md
+{{ toYaml $cfg }}
+{{- end -}}
+
+{{/* Refuses values that would make a pod that cannot work. */}}
+{{- define "llmgw.validate" -}}
+{{- if not (has .Values.store.type (list "sqlite" "postgres")) -}}
+{{- fail (printf "store.type %q: sqlite or postgres" .Values.store.type) -}}
+{{- end -}}
+{{- if ne (int .Values.replicas) 1 -}}
+{{- fail "replicas: this chart runs one control plane; values.yaml says why" -}}
+{{- end -}}
+{{- if and (eq .Values.store.type "postgres") (not .Values.store.postgres.existingSecret) -}}
+{{- fail "store.postgres.existingSecret: a Secret holding the PostgreSQL address" -}}
+{{- end -}}
+{{- if not .Values.agentTLS.existingSecret -}}
+{{- fail "agentTLS.existingSecret: a Secret with ca.pem, server.pem and server-key.pem from llmgw's authority (see values.yaml)" -}}
+{{- end -}}
+{{- end -}}

deploy/helm/llmgw/templates/configmap.yaml

@@ -0,0 +1,10 @@
+{{- include "llmgw.validate" . -}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+data:
+  server.yaml: |
+    {{- include "llmgw.serverConfig" . | nindent 4 }}

deploy/helm/llmgw/templates/ingress.yaml

@@ -0,0 +1,37 @@
+{{- if .Values.ingress.enabled }}
+# The OpenAI-compatible API, the portal and the chat page on port 8080. Never
+# the agent port: its mutual TLS cannot pass through an HTTP proxy.
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- with .Values.ingress.className }}
+  ingressClassName: {{ . }}
+  {{- end }}
+  {{- with .Values.ingress.tls }}
+  tls:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            pathType: {{ .pathType }}
+            backend:
+              service:
+                name: {{ include "llmgw.fullname" $ }}
+                port:
+                  name: api
+          {{- end }}
+    {{- end }}
+{{- end }}

deploy/helm/llmgw/templates/secret-admin.yaml

@@ -0,0 +1,19 @@
+{{- if not .Values.adminToken.existingSecret }}
+{{- $name := include "llmgw.adminSecret" . }}
+{{- $token := randAlphaNum 64 }}
+{{- /* Kept across upgrades: a new token on every upgrade would lock out every console holding the old one. */}}
+{{- with lookup "v1" "Secret" .Release.Namespace $name }}
+{{- $token = index .data "admin-token" | b64dec }}
+{{- end }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ $name }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  annotations:
+    helm.sh/resource-policy: keep
+type: Opaque
+data:
+  admin-token: {{ $token | b64enc | quote }}
+{{- end }}

deploy/helm/llmgw/templates/servicemonitor.yaml

@@ -0,0 +1,21 @@
+{{- if .Values.serviceMonitor.enabled }}
+# For the Prometheus Operator: the metrics port, which serves metrics and
+# nothing else. deploy/monitoring holds the rules and dashboards that read them.
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+    {{- with .Values.serviceMonitor.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "llmgw.selectorLabels" . | nindent 6 }}
+  endpoints:
+    - port: metrics
+      path: /metrics
+      interval: {{ .Values.serviceMonitor.interval }}
+{{- end }}

deploy/helm/llmgw/templates/services.yaml

@@ -0,0 +1,70 @@
+# The API and the metrics, for the cluster and an Ingress.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: api
+      port: {{ .Values.service.port }}
+      targetPort: api
+    - name: metrics
+      port: {{ .Values.service.metricsPort }}
+      targetPort: metrics
+---
+# Where agents on the nodes connect. Mutual TLS ends in the pod: whatever is
+# in between must pass TCP through untouched.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}-agents
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.agentService.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.agentService.type }}
+  {{- if and (eq .Values.agentService.type "LoadBalancer") .Values.agentService.loadBalancerIP }}
+  loadBalancerIP: {{ .Values.agentService.loadBalancerIP }}
+  {{- end }}
+  {{- with .Values.agentService.loadBalancerSourceRanges }}
+  loadBalancerSourceRanges:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  {{- if has .Values.agentService.type (list "LoadBalancer" "NodePort") }}
+  externalTrafficPolicy: {{ .Values.agentService.externalTrafficPolicy }}
+  {{- end }}
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: agents
+      port: {{ .Values.agentService.port }}
+      targetPort: agents
+---
+# The StatefulSet's own, giving each pod a stable name.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}-headless
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+spec:
+  clusterIP: None
+  publishNotReadyAddresses: true
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: api
+      port: 8080
+      targetPort: api

deploy/helm/llmgw/templates/statefulset.yaml

@@ -0,0 +1,181 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+spec:
+  # One control plane: Kubernetes replaces it within seconds when it goes,
+  # and the agents reconnect on their own. See replicas in values.yaml.
+  replicas: 1
+  serviceName: {{ include "llmgw.fullname" . }}-headless
+  selector:
+    matchLabels:
+      {{- include "llmgw.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "llmgw.selectorLabels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      annotations:
+        # server.yaml is read at start: a changed one restarts the pod.
+        checksum/config: {{ include "llmgw.serverConfig" . | sha256sum }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      # Agents reconnect within seconds of a control plane going; a long
+      # grace period only delays the one that replaces it.
+      terminationGracePeriodSeconds: 30
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 65532
+        runAsGroup: 65532
+        fsGroup: 65532
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: llmgw
+          image: {{ include "llmgw.image" . }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args: ["server", "--config", "/etc/llmgw/server.yaml"]
+          env:
+            # For `kubectl exec ... -- llmgw ctl`, which reads the token
+            # from here; the server reads admin_token_file.
+            - name: LLMGW_ADMIN_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "llmgw.adminSecret" . }}
+                  key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}
+          ports:
+            - name: api
+              containerPort: 8080
+            - name: agents
+              containerPort: 7443
+            - name: metrics
+              containerPort: 9091
+          # Up is /health. Ready is /leader: a control plane holds the
+          # agents' connections and places models only once it leads — on
+          # PostgreSQL, once the lease of the one it replaced has run out. A
+          # cluster with no node yet is still ready: /ready would wait for a
+          # replica, and nodes could then never connect.
+          startupProbe:
+            httpGet: {path: /health, port: api}
+            periodSeconds: 5
+            failureThreshold: 60
+          livenessProbe:
+            httpGet: {path: /health, port: api}
+            periodSeconds: 10
+            failureThreshold: 6
+          readinessProbe:
+            httpGet: {path: /leader, port: api}
+            periodSeconds: 5
+            failureThreshold: 2
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: config
+              mountPath: /etc/llmgw/server.yaml
+              subPath: server.yaml
+              readOnly: true
+            - name: agent-tls
+              mountPath: /etc/llmgw/tls
+              readOnly: true
+            - name: admin-token
+              mountPath: /etc/llmgw/admin
+              readOnly: true
+            {{- if eq .Values.store.type "postgres" }}
+            - name: store
+              mountPath: /etc/llmgw/store
+              readOnly: true
+            {{- end }}
+            {{- if .Values.offlineChecksums.configMap }}
+            - name: offline
+              mountPath: /etc/llmgw/offline
+              readOnly: true
+            {{- end }}
+            - name: data
+              mountPath: /var/lib/llmgw
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: config
+          configMap:
+            name: {{ include "llmgw.fullname" . }}
+        - name: agent-tls
+          secret:
+            secretName: {{ .Values.agentTLS.existingSecret }}
+            defaultMode: 0440
+            items:
+              - {key: ca.pem, path: ca.pem}
+              - {key: server.pem, path: server.pem}
+              - {key: server-key.pem, path: server-key.pem}
+        - name: admin-token
+          secret:
+            secretName: {{ include "llmgw.adminSecret" . }}
+            defaultMode: 0440
+            items:
+              - key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}
+                path: admin-token
+        {{- if eq .Values.store.type "postgres" }}
+        - name: store
+          secret:
+            secretName: {{ .Values.store.postgres.existingSecret }}
+            defaultMode: 0440
+            items:
+              - key: {{ .Values.store.postgres.secretKey }}
+                path: dsn
+        {{- end }}
+        {{- if .Values.offlineChecksums.configMap }}
+        - name: offline
+          configMap:
+            name: {{ .Values.offlineChecksums.configMap }}
+            items:
+              - key: {{ .Values.offlineChecksums.key }}
+                path: offline.sha256
+        {{- end }}
+        - name: tmp
+          emptyDir: {}
+        {{- if eq .Values.store.type "postgres" }}
+        # The store is PostgreSQL; nothing here outlives the pod.
+        - name: data
+          emptyDir: {}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+  {{- if eq .Values.store.type "sqlite" }}
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+        labels:
+          {{- include "llmgw.selectorLabels" . | nindent 10 }}
+      spec:
+        accessModes: ["ReadWriteOnce"]
+        {{- with .Values.store.sqlite.storageClass }}
+        storageClassName: {{ . }}
+        {{- end }}
+        resources:
+          requests:
+            storage: {{ .Values.store.sqlite.size }}
+  {{- end }}

deploy/helm/llmgw/values.yaml

@@ -0,0 +1,132 @@
+# The llmgw control plane in Kubernetes. docs/kubernetes.md says what this
+# runs, what it does not, and how nodes outside the cluster join it.
+
+image:
+  # Where you pushed the image built from deploy/container/Dockerfile. The
+  # project publishes binaries, not an image, so this has no default.
+  repository: ""
+  # Empty takes the chart's appVersion.
+  tag: ""
+  pullPolicy: IfNotPresent
+imagePullSecrets: []
+
+# One control plane, always. Two against PostgreSQL would elect a leader and
+# keep a standby, but a standby serves nothing and is never ready, so a
+# rollout would wait on it for ever. Until the chart handles that, it runs
+# one: Kubernetes replaces it within seconds when it goes, and the agents
+# reconnect on their own.
+replicas: 1
+
+store:
+  # sqlite: a file on a PersistentVolumeClaim, for one replica.
+  # postgres: a PostgreSQL you run, its address in a Secret.
+  type: sqlite
+  sqlite:
+    size: 10Gi
+    storageClass: ""
+  postgres:
+    # A Secret holding the address, postgres://user:password@host:5432/llmgw?sslmode=verify-full
+    existingSecret: ""
+    secretKey: dsn
+
+# The agent port's certificate. It comes from llmgw's own authority, not a
+# public one — agents present certificates from the same authority — so it
+# is made outside the cluster, where the authority's key stays:
+#
+#   llmgw ctl cert init-ca --dir ./pki
+#   llmgw ctl cert issue-server llmgw-ctl --host <agent address> --dir ./pki --out ./pki
+#   kubectl create secret generic llmgw-agent-tls \
+#     --from-file=ca.pem=pki/ca.pem \
+#     --from-file=server.pem=pki/server.pem \
+#     --from-file=server-key.pem=pki/server-key.pem
+#
+# --host is every address agents dial: agentService's load balancer address
+# or DNS name.
+agentTLS:
+  existingSecret: ""
+
+# The admin API's token (llmgw ctl, the console). Empty makes one, kept in a
+# Secret across upgrades.
+adminToken:
+  existingSecret: ""
+  secretKey: admin-token
+
+# server.yaml beyond what the chart sets (listeners, TLS, store, admin
+# token): any key of docs/reference.md, laid over the chart's. An offline
+# cluster sets offline.mirror here, and offlineChecksums below.
+config:
+  control:
+    enabled: true
+  auth:
+    enabled: true
+    signup_open: false
+    default_rpm: 60
+    default_tpm: 200000
+    default_price:
+      prompt_per_1k: 1000
+      completion_per_1k: 1000
+    max_key_ttl: 2160h
+  # mirror:
+  #   api: https://models.internal:8082
+  # offline:
+  #   mirror: http://models.internal:8081
+  # firewall_networks: ["10.42.0.0/16"]   # the pods' network, so nodes' engines answer the router
+
+# On an offline cluster, a ConfigMap or Secret holding the engine checksums
+# 'llmgw bundle trust' writes (offline.sha256), mounted where offline.checksums
+# points. Empty mounts none.
+offlineChecksums:
+  configMap: ""
+  key: offline.sha256
+
+# The OpenAI-compatible API and the metrics, inside the cluster.
+service:
+  type: ClusterIP
+  port: 8080
+  metricsPort: 9091
+  annotations: {}
+
+# Where agents connect, with mutual TLS. Nodes run outside the cluster, so
+# this is a load balancer by default; the TLS ends in the pod, never at a
+# proxy in between.
+agentService:
+  type: LoadBalancer
+  port: 7443
+  annotations: {}
+  loadBalancerIP: ""
+  loadBalancerSourceRanges: []
+  # Keeps the agents' addresses as they are, which the node's identity does
+  # not need but the logs and the audit read better with.
+  externalTrafficPolicy: Local
+
+ingress:
+  enabled: false
+  className: ""
+  annotations: {}
+  hosts:
+    - host: llm.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+  #  - secretName: llm-example-com
+  #    hosts: [llm.example.com]
+
+# A ServiceMonitor for the Prometheus Operator, scraping the metrics port.
+serviceMonitor:
+  enabled: false
+  interval: 30s
+  labels: {}
+
+resources:
+  requests:
+    cpu: 500m
+    memory: 512Mi
+  limits:
+    memory: 2Gi
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
+podAnnotations: {}
+podLabels: {}

deploy/mirror/README.md

@@ -0,0 +1,273 @@
+# A model mirror
+
+One machine that holds the model files, so nodes fetch over your own network
+instead of over the internet.
+
+This is the highest-value piece of infrastructure around llmgw and the cheapest.
+Eight nodes each pulling forty gigabytes from Hugging Face is a day's work, and
+on plenty of corporate networks it is not possible at all. From a mirror on the
+same switch it is minutes.
+
+llmgw needs nothing special for this: a model's `source` is a URL, and the URL
+can be yours.
+
+## What it is
+
+An HTTP server serving a directory. That is the whole design.
+
+```
+/srv/models/
+  qwen2.5-14b-instruct/
+    2026-03/
+      q4_k_m.gguf
+  bge-m3/
+    2026-01/
+      model.safetensors
+```
+
+At an offline site the mirror also holds what the nodes would otherwise fetch
+from the internet — llmgw's releases and the llama.cpp builds — under
+`_llmgw/releases/` and `_llmgw/engines/`, put there by `llmgw bundle import`
+(docs/install.md, "Offline sites"). They are not models: `mirror list` and
+`mirror unused` pass over them, and a node checks each against what the
+control plane says it must be, not against anything the mirror says.
+
+The date in the path is the point of the layout, not decoration. A model
+repository that changes upstream changes what you are running, and the first
+sign is a prompt that worked last week answering differently this week with
+nobody able to say why. Pin it here and that cannot happen.
+
+## Running it
+
+`llmgw` is the mirror. Same binary as the control plane and the agents, one
+subcommand:
+
+```
+sudo mkdir -p /srv/models && sudo chown llmgw:llmgw /srv/models
+llmgw mirror serve --dir /srv/models --base http://models.internal:8081
+```
+
+There is a unit in `deploy/systemd/llmgw-mirror.service`. Set `--base` to the
+address nodes reach this machine on — not `localhost`, and not a name only this
+host knows itself by. It is the string that ends up in catalog entries, and a
+wrong one makes `mirror unused` report files as unreferenced when they are in
+use. The next step after that list is deletion.
+
+### Two listeners
+
+`--listen :8081` serves the weights. Read-only, unauthenticated, Range requests
+supported so an interrupted fetch on a node resumes rather than restarts. This
+is the path eight nodes pull forty gigabytes from.
+
+`--api-listen :8082` is the management API. Separate on purpose: putting a
+client certificate in front of the byte path would mean re-certifying every
+agent's fetcher in order to change how models are administered.
+
+The API is unauthenticated unless you give it the fleet's CA, and it says so at
+startup rather than leaving you to find out. Anyone who can reach that port can
+start downloads and delete models, so either keep it on a trusted network or
+hand it certificates:
+
+```
+llmgw mirror serve --dir /srv/models --base http://models.internal:8081 \
+  --tls-ca /etc/llmgw/ca.pem \
+  --tls-cert /etc/llmgw/mirror.pem \
+  --tls-key /etc/llmgw/mirror-key.pem \
+  --api-client control-plane
+```
+
+`--api-client` is required with `--tls-ca`: it names the one certificate the
+API answers, because the CA signs every node's certificate as well.
+
+That is the same CA the agents already use, so the certificates come from the
+authority you have:
+
+```
+llmgw ctl cert issue-server mirror --host models.internal --host 10.0.0.146
+llmgw ctl cert issue-client control-plane
+```
+
+`--host` has to cover every address the API is called on, because that is what
+a client verifies against. Both sides are checked — the mirror will not accept a
+caller without a certificate from this CA, the same rule the agent stream
+follows.
+
+### nginx instead
+
+If you already run nginx, it serves a directory perfectly well and you do not
+need `mirror serve` for the bytes:
+
+```nginx
+server {
+    listen 80;
+    server_name models.internal;
+
+    root /srv/models;
+
+    # Read-only. This is deliberate: a mirror that can be written to over HTTP
+    # is a way to replace a model with another one, and the nodes would fetch
+    # it without complaint.
+    location / {
+        autoindex on;
+        # Large files, and the client is a machine with a resumable fetcher.
+        # Sendfile and no buffering keep memory flat regardless of size.
+        sendfile on;
+        tcp_nopush on;
+    }
+}
+```
+
+`autoindex` is there so a person can browse what is available; llmgw does not
+need it.
+
+## Filling it
+
+From the mirror itself:
+
+```
+llmgw mirror add \
+  --model qwen2.5-14b-instruct --version 2026-03 \
+  "https://huggingface.co/<repo>/resolve/<revision>/q4_k_m.gguf"
+```
+
+Use a revision rather than `main` in the source URL. `main` is what moves.
+
+It downloads to a temporary name and renames when complete, so an interrupted
+download never leaves something a catalog could be pointed at, and it prints the
+sha256 when it lands. Compare that against what upstream publishes — Hugging
+Face gives it as `lfs.oid` from
+`https://huggingface.co/api/models/<repo>/tree/<revision>`. A mirror is the one
+place in this system where a corrupt file is copied to every node instead of
+being caught once.
+
+It refuses to overwrite a version that is already there. Add a new one beside
+it: that refusal is what makes the old weights still available when the new ones
+turn out to be worse.
+
+## Driving it from elsewhere
+
+The same fetch over the API, so the control plane — or anything else — can ask
+for a model without anyone logging in:
+
+```
+curl -X POST http://models.internal:8082/v1/models -d '{
+  "source": "https://huggingface.co/<repo>/resolve/<revision>/q4_k_m.gguf",
+  "model": "qwen2.5-14b-instruct",
+  "version": "2026-03"
+}'
+```
+
+The mirror does the downloading. A control plane that pulled the bytes itself
+and pushed them here would carry every model twice over the network, through the
+one machine least able to spare the bandwidth.
+
+It answers `202` with the URL a catalog entry should use, and the bytes are not
+here yet. Poll for them:
+
+| | |
+|---|---|
+| `GET /v1/models` | everything held or arriving, and the base to build URLs from |
+| `POST /v1/models` | fetch this source into model/version |
+| `GET /v1/models/{model}/{version}` | `fetching` with a byte count, `present`, or `failed` with the reason |
+| `DELETE /v1/models/{model}/{version}` | remove a version; refuses while it is downloading |
+| `GET /v1/health` | up *and* able to read its own directory |
+
+A failed fetch stays `failed` with what went wrong, rather than disappearing:
+otherwise the thing waiting on that model waits forever with nothing to say why.
+Asking twice for the same download joins the one already running instead of
+starting a rival writer on the same file.
+
+`DELETE` takes the whole version, never one file of it. A model split across
+several files is useless with one missing, and half a version on disk looks
+present and will not load.
+
+## Retiring a model
+
+```
+llmgw mirror unused     # what no catalog entry refers to
+llmgw mirror remove --model <m> --version <v> --file <f>
+```
+
+`unused` compares against every `source` in the running catalog, so the answer
+is what can go rather than what looks old. It refuses to answer when it cannot
+reach the control plane: an empty catalog and an unreachable one produce the
+same list — everything — and the obvious next step after that list is deletion.
+
+Retire the catalog entry first, let the fleet settle, then remove. A node that
+has to refetch a file you deleted cannot, and the failure arrives later, on the
+node, looking like something else.
+
+## From the control plane's admin page
+
+Configure the mirror on the control plane and the same operations appear at
+`/admin/mirror`, behind the admin session the other admin pages use:
+
+```yaml
+mirror:
+  api: https://models.internal:8082
+  tls:
+    ca: /etc/llmgw/ca.crt
+    cert: /etc/llmgw/control-plane.crt
+    key: /etc/llmgw/control-plane.key
+```
+
+Leave the block out and the page is not mounted at all, which is the right page
+for a deployment with no mirror — not an empty one pointing at nothing.
+
+The page lists what is held, what is arriving with its byte count, and what
+failed with the reason; it starts a fetch, retries a failed one, and removes a
+version. It reloads itself only while something is downloading, because a reload
+at any other moment takes with it whatever is half-typed in the form.
+
+Two things it deliberately will not do. It cannot point the control plane at a
+different mirror — that is configuration, and changing it needs access to the
+host rather than a session. And it does not write the catalog for you: it shows
+the URL an entry should use, and putting it there is still a deliberate act,
+because that is the moment a model starts being served.
+
+The address is a mistake worth naming: `api` is the **management** port, not the
+one nodes fetch bytes from. They are two listeners so this one can be locked
+down without re-certifying every agent's fetcher.
+
+## Pointing llmgw at it
+
+```yaml
+- name: qwen2.5-14b-instruct
+  source: http://models.internal/qwen2.5-14b-instruct/2026-03/q4_k_m.gguf
+  scaling: { min: 2, max: 2 }
+  profiles:
+    - name: gpu
+      engine: vllm
+      gpu_class: h100-80g
+      tp: 1
+```
+
+Each node fetches once, in the background, before its engine starts — and
+`llmgw ctl replicas` shows how far along it is while it does. A killed download
+resumes rather than restarting, and a partial file is never visible under the
+model's name, so an interrupted fetch cannot be handed to an engine.
+
+## What this is not
+
+It is not a cache. Nothing populates it on its own: a model is there because
+somebody asked for it, by hand or over the API, and one nobody asked for is not
+there. That is on purpose. A mirror that fetched on demand would reach the
+internet at the least convenient moment, and in a network where that is blocked
+it would fail in a way that looks like llmgw being broken.
+
+It is also not a replacement for a shared filesystem. If you already run one
+that every node mounts, put the models on it and use a path as the `source` —
+nothing is fetched at all, and llmgw notices the filesystem is shared and will
+not count the same free space once per node.
+
+## When this stops being enough
+
+Somewhere above ten or twenty nodes, one mirror serving a forty gigabyte file
+to all of them at once becomes the bottleneck instead of the fix. At that point
+the options are a filer, a second mirror per rack, or distribution between the
+nodes themselves.
+
+llmgw knows which nodes already hold which weights — it is in `ctl status` as
+"N models on X/Y nodes" — so distributing between them is a feature it is
+positioned to add. It has not been built, because a mirror is enough for
+everyone who has needed it so far.

deploy/monitoring/README.md

@@ -0,0 +1,186 @@
+# Watching a cluster
+
+Prometheus, Alertmanager and Grafana, configured for what llmgw actually
+publishes. Every alert here is written against a series this system emits;
+nothing is aimed at a metric that might exist.
+
+## What it is
+
+One scrape target for the whole fleet.
+
+Agents publish no metrics of their own. The control plane gathers what they
+report — node state, memory, disk, engine queue depth, KV occupancy — and
+republishes all of it, so a single endpoint describes every machine. That is
+worth knowing before going looking for an exporter on each node.
+
+## The port it scrapes
+
+`metrics_listen`, not `admin_listen`.
+
+The admin listener is bound to loopback for one reason: it also serves pprof,
+and pprof can dump the process heap, where API keys sit in plaintext. Metrics
+are the one thing on that listener something else genuinely needs to reach, so
+they get a port of their own instead of becoming an argument for opening the
+other one.
+
+```yaml
+# /etc/llmgw/server.yaml
+metrics_listen: ":9091"
+```
+
+Confirm it carries nothing else:
+
+```
+curl -s -o /dev/null -w '%{http_code}\n' http://<control-plane>:9091/debug/pprof/   # 404
+curl -s -o /dev/null -w '%{http_code}\n' http://<control-plane>:9091/api/v1/nodes   # 404
+```
+
+## Installing
+
+On Ubuntu 24.04 the first two come from the archive; Grafana needs its own
+repository.
+
+```
+apt-get install prometheus prometheus-alertmanager
+
+install -m 0644 prometheus.yml            /etc/prometheus/prometheus.yml
+install -m 0644 llmgw-rules.yml           /etc/prometheus/rules/llmgw.yml
+install -m 0644 alertmanager.yml          /etc/prometheus/alertmanager.yml
+# Alertmanager answers on loopback only. Its API takes silences from anyone who
+# can reach it, with no login, and silencing BackupTooOld or ModelParked is how
+# something that should be noticed is not. Prometheus beside it is its only
+# client; one Alertmanager needs no cluster port.
+echo 'ARGS="--web.listen-address=127.0.0.1:9093 --cluster.listen-address="' \
+    > /etc/default/prometheus-alertmanager
+# Prometheus itself is read-only as installed: its admin and lifecycle APIs
+# stay off (no --web.enable-admin-api, no --web.enable-lifecycle). It still
+# answers any query from anyone who reaches :9090, which says which models and
+# nodes there are and how busy each is. Its readers are the control plane
+# (monitoring.prometheus) and Grafana beside it; to keep it to those, allow
+# the control plane and drop the rest, e.g. with nftables:
+#   nft add rule inet filter input tcp dport 9090 ip saddr != { 127.0.0.1, CONTROL_PLANE_IP } drop
+promtool check config /etc/prometheus/prometheus.yml
+systemctl restart prometheus prometheus-alertmanager
+
+install -m 0644 grafana/datasource.yaml   /etc/grafana/provisioning/datasources/llmgw.yaml
+install -m 0644 grafana/dashboards.yaml   /etc/grafana/provisioning/dashboards/llmgw.yaml
+install -m 0644 -o grafana -g grafana grafana/llmgw-overview.json \
+    /var/lib/grafana/dashboards/llmgw.json
+install -m 0644 -o grafana -g grafana grafana/llmgw-tenants.json \
+    /var/lib/grafana/dashboards/llmgw-tenants.json
+systemctl restart grafana-server
+```
+
+The dashboard is provisioned from a file rather than clicked together, so it
+survives a reinstall and can be reviewed in a diff.
+
+## Where to run it
+
+Not on the control plane. Monitoring that dies with the thing it monitors tells
+you nothing at the moment you need it, and the control plane is also the busiest
+machine in a small cluster.
+
+Anywhere else on the management network will do. The mirror is a reasonable
+host: it has the disk, and serving weights is bursty rather than constant.
+
+## Nothing is sent anywhere
+
+Alertmanager groups and holds alerts and has no receiver.
+
+Where an alert should go — an address, a Slack workspace, a webhook — is a
+decision with credentials attached, and a monitoring system that quietly starts
+mailing people is worse than one that is visibly not wired up. Alerts are
+visible in Prometheus, and at `:9093` on the monitoring host itself (`ssh -L
+9093:127.0.0.1:9093 <host>` to open its page); add a receiver to `alertmanager.yml` to
+make them travel. `critical` already routes separately so it can be pointed
+somewhere else without touching the rest.
+
+## Check that it fires
+
+An alerting system nobody has seen fire is an assumption.
+
+```
+llmgw ctl cordon <node>     # work already there keeps running
+# ~2 minutes later
+ssh <host> curl -s http://127.0.0.1:9093/api/v2/alerts | jq '.[].labels'
+llmgw ctl uncordon <node>   # the alert resolves on its own
+```
+
+Cordoning is the cheapest real test: it changes a metric the rules read, stops
+nothing, and reverses in one command.
+
+## What the alerts assume
+
+**A stopped model publishes no series.** `llmgw_model_replicas_ready` exists
+only for models with a replica placed, so `== 0` cannot fire for one that is
+deliberately off. That is what makes an on-demand catalogue quiet here.
+
+**Saturation of 1 is the healthy limit, not failure.** It is the worse of queue
+depth and KV occupancy, measured by `ctl bench` rather than guessed. The alert
+allows five minutes above it before saying anything.
+
+**Latencies are in seconds.** These thresholds are written for CPU inference. A
+p99 first token of thirty seconds is the alerting point here and would be
+absurd on a GPU; change it when the hardware changes.
+
+**Disk is only reported by nodes that hold weights.** A node with no model
+directory reports nothing rather than zero, and the rule divides free by total
+so a node that reports neither never fires.
+
+## Where the metrics live
+
+On the machine that scrapes them, in Prometheus's own store, and that is the
+right answer at this size. Measured on this cluster: 2,359 series at 41 samples
+a second, which compresses to roughly 7 MB a day — about 3 GB for a year.
+
+```
+# /etc/default/prometheus
+ARGS="--storage.tsdb.retention.time=365d --storage.tsdb.retention.size=20GB"
+```
+
+A year because the questions worth asking of this data are seasonal: what did
+capacity look like last quarter, was it always this slow, how much did the
+fleet grow. Fifteen days answers none of them.
+
+Both limits, not one. The time limit is the intent; the size cap is what stops
+Prometheus becoming the thing that fills the disk if the series count grows
+tenfold after somebody adds a fleet.
+
+No remote write, no object store, no second tier. At two thousand series that
+is infrastructure for a problem this cluster does not have, and every one of
+those has its own failure modes to learn.
+
+### The part that is not about capacity
+
+The disk is not the constraint — 900 GB free against 3 GB a year. What matters
+is what shares it.
+
+On this cluster the model mirror and the metrics database are on the same
+filesystem. A mirror that fills it stops Prometheus writing, so monitoring goes
+quiet at exactly the moment the disk is the problem, and the alert that would
+have said so is the one that died.
+
+Two ways out, in order of how much they cost:
+
+- Watch it, which is now done. `prometheus-node-exporter` arrives with the
+  Prometheus package and was running, unscraped, on this machine — so the disk
+  holding both was watched by nothing. It is a scrape target now, and
+  `MonitoringDiskFilling` fires at fifteen percent rather than five, because
+  the thing being protected is the ability to be told.
+- Separate them: a volume of its own for `/var/lib/prometheus`, or monitoring
+  on its own machine. Worth doing before the mirror holds a few hundred
+  gigabytes; not worth doing today at seven percent used.
+
+## What is not here
+
+No exporter on the llmgw nodes, so no host CPU, load average or network for
+them. The control plane publishes memory, disk and liveness for every node,
+which is what placement decides on; the rest is a `node_exporter` away if
+somebody wants it. The monitoring host itself is scraped, for the reason above.
+
+No probe of the mirror. Its `/v1/health` is JSON rather than Prometheus text,
+and checking it properly means `blackbox_exporter`.
+
+No recording rules. At this size every query in the dashboard runs fast enough
+raw, and a recording rule is a second definition of a number to keep in step
+with the first.

deploy/monitoring/alertmanager.yml

@@ -0,0 +1,89 @@
+# Alertmanager for the llmgw cluster.
+#
+# Nothing is sent anywhere until a receiver is chosen, on purpose. Where an alert should go — an
+# address, a Slack workspace, a webhook — is a decision with credentials
+# attached, and a monitoring system that quietly starts mailing people is worse
+# than one that is visibly not wired up. Alerts group and fire here and are
+# visible at :9093 and in Prometheus; uncomment a receiver template below and
+# name it on the route to make them travel.
+global:
+  resolve_timeout: 5m
+
+route:
+  # By alert and by what it is about, so five nodes going quiet in the same
+  # network blip arrive as one notification rather than five.
+  group_by: ['alertname', 'node', 'model']
+  group_wait: 30s
+  group_interval: 5m
+  # Long, because a repeat is a reminder and not news. A cluster with one thing
+  # wrong should not produce a message an hour.
+  repeat_interval: 12h
+  receiver: none
+
+  routes:
+    # Critical gets its own branch so it can be pointed somewhere else later
+    # without touching the rest: the difference between "a node is draining"
+    # and "nothing is serving" is who should be woken.
+    - matchers: [severity="critical"]
+      receiver: none
+      group_wait: 10s
+      repeat_interval: 4h
+
+receivers:
+  - name: none
+
+  # Receiver templates. Uncomment one, fill in where it goes, and name it in
+  # `receiver:` above — on the route, the critical branch, or both. Secrets go
+  # in files Alertmanager reads (the *_file settings), mode 0640 owned by
+  # root:prometheus, not in this file. `amtool check-config` before a restart.
+  #
+  # Slack (an incoming webhook):
+  # - name: slack
+  #   slack_configs:
+  #     - api_url_file: /etc/prometheus/slack-webhook-url
+  #       channel: '#llmgw'
+  #       send_resolved: true
+  #       title: '{{ .Status | toUpper }}: {{ .CommonLabels.alertname }}'
+  #       text: >-
+  #         {{ range .Alerts }}{{ .Annotations.summary }}
+  #         {{ .Annotations.description }}
+  #         {{ end }}
+  #
+  # E-mail (through a relay that takes authenticated submission):
+  # - name: email
+  #   email_configs:
+  #     - to: ops@example.com
+  #       from: llmgw-alerts@example.com
+  #       smarthost: smtp.example.com:587
+  #       auth_username: llmgw-alerts@example.com
+  #       auth_password_file: /etc/prometheus/smtp-password
+  #       send_resolved: true
+  #
+  # PagerDuty (Events API v2), for the critical branch — what should wake
+  # someone:
+  # - name: pagerduty
+  #   pagerduty_configs:
+  #     - routing_key_file: /etc/prometheus/pagerduty-routing-key
+  #       severity: '{{ .CommonLabels.severity }}'
+  #       description: '{{ .CommonAnnotations.summary }}'
+  #
+  # A webhook of your own (Alertmanager's JSON, version 4):
+  # - name: webhook
+  #   webhook_configs:
+  #     - url_file: /etc/prometheus/alert-webhook-url
+  #       send_resolved: true
+  #       max_alerts: 20
+  #
+  # The gateway itself also sends a few events straight to webhooks, with no
+  # Prometheus in between — a model parked, a node lost, a budget spent, new
+  # weights published: `notify.webhooks` in server.yaml (docs/install.md,
+  # "Being told").
+
+inhibit_rules:
+  # A node that is down explains every replica on it. Reporting both says the
+  # same thing twice and buries whichever is the actual cause.
+  - source_matchers: [alertname="NodeNotReady"]
+    target_matchers: [alertname="EndpointMetricsStale"]
+    equal: ['node']
+  - source_matchers: [alertname="ControlPlaneUnreachable"]
+    target_matchers: [severity="warning"]

deploy/monitoring/grafana/dashboards.yaml

@@ -0,0 +1,11 @@
+apiVersion: 1
+providers:
+  - name: llmgw
+    orgId: 1
+    folder: llmgw
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 30
+    allowUiUpdates: true
+    options:
+      path: /var/lib/grafana/dashboards

deploy/monitoring/grafana/datasource.yaml

@@ -0,0 +1,11 @@
+# Provisioned rather than clicked in, so the dashboard below can reference it by
+# a fixed uid and the whole setup survives a reinstall of the machine.
+apiVersion: 1
+datasources:
+  - name: Prometheus
+    uid: llmgw-prom
+    type: prometheus
+    access: proxy
+    url: http://localhost:9090
+    isDefault: true
+    editable: false

deploy/monitoring/grafana/llmgw-overview.json

@@ -0,0 +1,958 @@
+{
+  "uid": "llmgw-overview",
+  "title": "llmgw \u2014 cluster",
+  "tags": [
+    "llmgw"
+  ],
+  "timezone": "browser",
+  "schemaVersion": 39,
+  "version": 1,
+  "refresh": "30s",
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "panels": [
+    {
+      "id": 1,
+      "title": "Nodes ready",
+      "type": "stat",
+      "description": "Nodes taking work. A node that is known but draining or cordoned is not counted.",
+      "gridPos": {
+        "x": 0,
+        "y": 0,
+        "w": 4,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "count(llmgw_node_up == 1)",
+          "legendFormat": "ready",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 2,
+      "title": "Replicas serving",
+      "type": "stat",
+      "description": "Across every model. A model deliberately stopped contributes nothing and is not a fault.",
+      "gridPos": {
+        "x": 4,
+        "y": 0,
+        "w": 4,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(llmgw_model_replicas_ready)",
+          "legendFormat": "ready",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 3,
+      "title": "Models with something serving",
+      "type": "stat",
+      "description": "",
+      "gridPos": {
+        "x": 8,
+        "y": 0,
+        "w": 4,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "count(llmgw_model_replicas_ready > 0)",
+          "legendFormat": "models",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 4,
+      "title": "Requests per second",
+      "type": "timeseries",
+      "description": "Failing is counted separately rather than as a percentage, so a quiet cluster reads as quiet instead of as 0% of nothing.",
+      "gridPos": {
+        "x": 12,
+        "y": 0,
+        "w": 12,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_requests_total[5m]))",
+          "legendFormat": "all",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        },
+        {
+          "refId": "B",
+          "expr": "sum(rate(llmgw_requests_total{status=~\"5..\"}[5m]))",
+          "legendFormat": "failing",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 5,
+      "title": "Replicas ready, by model",
+      "type": "timeseries",
+      "description": "Only models with a replica placed appear. One that is stopped on purpose publishes no series.",
+      "gridPos": {
+        "x": 0,
+        "y": 4,
+        "w": 12,
+        "h": 7
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_model_replicas_ready",
+          "legendFormat": "{{model}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      }
+    },
+    {
+      "id": 6,
+      "title": "Pool saturation",
+      "type": "timeseries",
+      "description": "The worse of queue depth and KV occupancy. 1 is the limit measured as healthy, not the point of failure.",
+      "gridPos": {
+        "x": 12,
+        "y": 4,
+        "w": 12,
+        "h": 7
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_pool_saturation",
+          "legendFormat": "{{model}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "max": 2,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 7,
+      "title": "Time to first token",
+      "type": "timeseries",
+      "description": "As the router sees it. On CPU these are seconds, not milliseconds; compare against what ctl bench measured.",
+      "gridPos": {
+        "x": 0,
+        "y": 11,
+        "w": 12,
+        "h": 7
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.5, sum by (model, le) (rate(llmgw_ttft_seconds_bucket[5m])))",
+          "legendFormat": "{{model}} p50",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        },
+        {
+          "refId": "B",
+          "expr": "histogram_quantile(0.99, sum by (model, le) (rate(llmgw_ttft_seconds_bucket[5m])))",
+          "legendFormat": "{{model}} p99",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 8,
+      "title": "Tokens per second",
+      "type": "timeseries",
+      "description": "",
+      "gridPos": {
+        "x": 12,
+        "y": 11,
+        "w": 12,
+        "h": 7
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (direction) (rate(llmgw_tokens_total[5m]))",
+          "legendFormat": "{{direction}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 9,
+      "title": "Engine queue depth",
+      "type": "timeseries",
+      "description": "Requests the engine has accepted and not started. Rising here is the first sign of saturation.",
+      "gridPos": {
+        "x": 0,
+        "y": 18,
+        "w": 8,
+        "h": 6
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_endpoint_waiting",
+          "legendFormat": "{{replica}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      }
+    },
+    {
+      "id": 10,
+      "title": "KV cache occupancy",
+      "type": "timeseries",
+      "description": "",
+      "gridPos": {
+        "x": 8,
+        "y": 18,
+        "w": 8,
+        "h": 6
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_endpoint_kv_cache_usage",
+          "legendFormat": "{{replica}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 11,
+      "title": "Model disk free",
+      "type": "timeseries",
+      "description": "The filesystems holding weights. A node that cannot hold the next model is skipped by placement rather than failing.",
+      "gridPos": {
+        "x": 16,
+        "y": 18,
+        "w": 8,
+        "h": 6
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_node_disk_free_bytes",
+          "legendFormat": "{{node}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 12,
+      "title": "Seconds since each node last reported",
+      "type": "timeseries",
+      "description": "Heartbeats are every 5s. A line that climbs is an agent going quiet; the control plane stops placing there at 15s.",
+      "gridPos": {
+        "x": 0,
+        "y": 24,
+        "w": 12,
+        "h": 6
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "llmgw_node_last_seen_seconds",
+          "legendFormat": "{{node}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "id": 13,
+      "title": "Replicas by state",
+      "type": "timeseries",
+      "description": "",
+      "gridPos": {
+        "x": 12,
+        "y": 24,
+        "w": 12,
+        "h": 6
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (state) (llmgw_replicas)",
+          "legendFormat": "{{state}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      }
+    },
+    {
+      "type": "row",
+      "title": "GPUs",
+      "id": 14,
+      "gridPos": {
+        "x": 0,
+        "y": 30,
+        "w": 24,
+        "h": 1
+      },
+      "collapsed": false,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU busy, by card",
+      "description": "Share of each sample period in which any kernel ran (nvidia-smi's utilization.gpu), sampled every heartbeat. Not how much of the chip: one SM busy reads 100%. The SMs panel and power against its limit say how much.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 31,
+        "w": 12,
+        "h": 7
+      },
+      "id": 15,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_utilization_percent",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU memory in use, by card",
+      "description": "Framebuffer in use. Engines reserve most of it at start.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 31,
+        "w": 12,
+        "h": 7
+      },
+      "id": 16,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_memory_used_bytes / llmgw_gpu_memory_total_bytes",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU memory bandwidth busy, by card",
+      "description": "Decode is bound by memory: high here with compute low is a card waiting on memory.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 38,
+        "w": 12,
+        "h": 7
+      },
+      "id": 17,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_memory_utilization_percent",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU temperature",
+      "description": "Throttling usually starts in the high 80s.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 38,
+        "w": 12,
+        "h": 7
+      },
+      "id": 18,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_temperature_celsius",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "celsius"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU power against its limit",
+      "description": "1 is the enforced limit; a card held there is power-capped.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 45,
+        "w": 12,
+        "h": 7
+      },
+      "id": 19,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_power_watts / llmgw_gpu_power_limit_watts",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1.1
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU clock",
+      "description": "A clock held low under load is the card throttled; see the next panel for why.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 45,
+        "w": 12,
+        "h": 7
+      },
+      "id": 20,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_sm_clock_mhz",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "rotmhz"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "What holds GPUs back",
+      "description": "Cards throttled now, by reason, and uncorrected ECC errors since the driver loaded.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 52,
+        "w": 24,
+        "h": 7
+      },
+      "id": 21,
+      "targets": [
+        {
+          "expr": "sum by (reason) (llmgw_gpu_throttled)",
+          "legendFormat": "throttled: {{reason}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum by (node, gpu) (llmgw_gpu_ecc_errors)",
+          "legendFormat": "ECC errors {{node}} gpu {{gpu}}",
+          "refId": "B"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Output tokens/s per GPU, by model",
+      "description": "What each model gets out of each card it holds.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 59,
+        "w": 12,
+        "h": 7
+      },
+      "id": 22,
+      "targets": [
+        {
+          "expr": "sum by (model) (rate(llmgw_tokens_total{direction=\"completion\"}[5m])) / count by (model) (llmgw_gpu_assigned)",
+          "legendFormat": "{{model}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Output tokens per watt-hour, by model",
+      "description": "Tokens for the energy the model's cards draw.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 59,
+        "w": 12,
+        "h": 7
+      },
+      "id": 23,
+      "targets": [
+        {
+          "expr": "sum by (model) (rate(llmgw_tokens_total{direction=\"completion\"}[5m])) * 3600 / sum by (model) (llmgw_gpu_power_watts * on (node, gpu) group_left (model) llmgw_gpu_assigned)",
+          "legendFormat": "{{model}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU wear",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "id": 24,
+      "description": "What wears cards out: XID errors in the last 15 minutes, memory rows remapped, PCIe retries an hour. Anything above zero here is worth a look on that card's node page.",
+      "gridPos": {
+        "x": 0,
+        "y": 66,
+        "w": 24,
+        "h": 7
+      },
+      "targets": [
+        {
+          "expr": "increase(llmgw_gpu_xid_errors[15m]) > 0",
+          "legendFormat": "XID {{node}} gpu {{gpu}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum by (node, gpu) (llmgw_gpu_remapped_rows) > 0",
+          "legendFormat": "rows remapped {{node}} gpu {{gpu}}",
+          "refId": "B"
+        },
+        {
+          "expr": "increase(llmgw_gpu_pcie_replays[1h]) > 0",
+          "legendFormat": "PCIe retries/h {{node}} gpu {{gpu}}",
+          "refId": "C"
+        },
+        {
+          "expr": "increase(llmgw_gpu_nvlink_errors[1h]) > 0",
+          "legendFormat": "NVLink {{kind}}/h {{node}} gpu {{gpu}}",
+          "refId": "D"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU SMs and tensor cores active, by card",
+      "description": "From the cards' profiling counters: NVML's GPM on Hopper and later, or a dcgm-exporter on the node. SMs active is the share of time the SMs had work, averaged over all of them; the gap to busy is chip a running kernel leaves idle. Tensor cores stay low in decode at batch one; prefill and batches are where they rise. Empty for cards nothing can profile.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 73,
+        "w": 24,
+        "h": 7
+      },
+      "id": 25,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_sm_active_percent",
+          "legendFormat": "{{node}} gpu {{gpu}} SMs",
+          "refId": "A"
+        },
+        {
+          "expr": "llmgw_gpu_tensor_active_percent",
+          "legendFormat": "{{node}} gpu {{gpu}} tensor",
+          "refId": "B"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    }
+  ]
+}

deploy/monitoring/grafana/llmgw-tenants.json

@@ -0,0 +1,650 @@
+{
+  "uid": "llmgw-tenants",
+  "title": "llmgw \u2014 tenants",
+  "schemaVersion": 39,
+  "version": 1,
+  "editable": true,
+  "time": {
+    "from": "now-24h",
+    "to": "now"
+  },
+  "refresh": "1m",
+  "tags": [
+    "llmgw"
+  ],
+  "description": "Requests, tokens, failures, refusals and first-token time per tenant \u2014 the level router.tenant_label names \u2014 and every budget's share spent.",
+  "templating": {
+    "list": [
+      {
+        "name": "tenant",
+        "label": "Tenant",
+        "type": "query",
+        "datasource": {
+          "type": "prometheus",
+          "uid": "llmgw-prom"
+        },
+        "query": {
+          "query": "label_values(llmgw_tenant_requests_total, tenant)",
+          "refId": "tenant"
+        },
+        "definition": "label_values(llmgw_tenant_requests_total, tenant)",
+        "multi": true,
+        "includeAll": true,
+        "allValue": ".*",
+        "current": {
+          "text": "All",
+          "value": "$__all"
+        },
+        "refresh": 2,
+        "sort": 1
+      }
+    ]
+  },
+  "panels": [
+    {
+      "id": 1,
+      "title": "Requests a second",
+      "type": "stat",
+      "description": "Across the tenants chosen above.",
+      "gridPos": {
+        "x": 0,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 2,
+      "title": "Failing",
+      "type": "stat",
+      "description": "Requests that failed, not counting refusals by a limit.",
+      "gridPos": {
+        "x": 6,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"error\"}[5m])) / sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.02
+              },
+              {
+                "color": "red",
+                "value": 0.05
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 3,
+      "title": "Refused by a limit",
+      "type": "stat",
+      "description": "Rate, token and budget limits; 429 to the caller.",
+      "gridPos": {
+        "x": 12,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[5m])) / sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.02
+              },
+              {
+                "color": "red",
+                "value": 0.1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 4,
+      "title": "First token, p95",
+      "type": "stat",
+      "description": "What people wait for before anything appears.",
+      "gridPos": {
+        "x": 18,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.95, sum by (le) (rate(llmgw_tenant_ttft_seconds_bucket{tenant=~\"$tenant\"}[5m])))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 3
+              },
+              {
+                "color": "red",
+                "value": 10
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 5,
+      "title": "Requests by tenant",
+      "type": "timeseries",
+      "description": "Stacked, so the top edge is the whole of it.",
+      "gridPos": {
+        "x": 0,
+        "y": 4,
+        "w": 12,
+        "h": 9
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps",
+          "custom": {
+            "stacking": {
+              "mode": "normal"
+            },
+            "fillOpacity": 30
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 6,
+      "title": "Tokens by tenant",
+      "type": "timeseries",
+      "description": "Prompt and completion together: what was consumed.",
+      "gridPos": {
+        "x": 12,
+        "y": 4,
+        "w": 12,
+        "h": 9
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_tokens_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "stacking": {
+              "mode": "normal"
+            },
+            "fillOpacity": 30
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 7,
+      "title": "Refused by a limit, by tenant",
+      "type": "timeseries",
+      "description": "The share of each tenant's requests a limit turned away.",
+      "gridPos": {
+        "x": 0,
+        "y": 13,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[5m])) / sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 8,
+      "title": "Failing, by tenant",
+      "type": "timeseries",
+      "description": "One tenant alone failing is usually what it sends; all of them together is a model.",
+      "gridPos": {
+        "x": 12,
+        "y": 13,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"error\"}[5m])) / sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 9,
+      "title": "First token p95, by tenant",
+      "type": "timeseries",
+      "description": "",
+      "gridPos": {
+        "x": 0,
+        "y": 21,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.95, sum by (tenant, le) (rate(llmgw_tenant_ttft_seconds_bucket{tenant=~\"$tenant\"}[10m])))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 10,
+      "title": "Budgets spent this period",
+      "type": "bargauge",
+      "description": "Every organization, team, project and person with a budget. Requests are refused at 100%.",
+      "gridPos": {
+        "x": 12,
+        "y": 21,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sort_desc(llmgw_budget_spent_ratio)",
+          "legendFormat": "{{scope}} {{name}} ({{period}})",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.8
+              },
+              {
+                "color": "red",
+                "value": 1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "displayMode": "gradient",
+        "orientation": "horizontal",
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "showUnfilled": true
+      }
+    },
+    {
+      "id": 11,
+      "title": "Who used most, last 24 hours",
+      "type": "table",
+      "description": "Spend in money is on the people page's usage tab, which reads it from the store.",
+      "gridPos": {
+        "x": 0,
+        "y": 29,
+        "w": 24,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sort_desc(sum by (tenant) (increase(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[24h])))",
+          "legendFormat": "requests",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        },
+        {
+          "refId": "B",
+          "expr": "sum by (tenant) (increase(llmgw_tenant_tokens_total{tenant=~\"$tenant\"}[24h]))",
+          "legendFormat": "tokens",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        },
+        {
+          "refId": "C",
+          "expr": "sum by (tenant) (increase(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[24h]))",
+          "legendFormat": "limited",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "options": {
+        "showHeader": true
+      },
+      "transformations": [
+        {
+          "id": "merge",
+          "options": {}
+        },
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": {
+              "Time": true
+            },
+            "renameByName": {
+              "Value #A": "Requests",
+              "Value #B": "Tokens",
+              "Value #C": "Refused by a limit"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

deploy/monitoring/llmgw-rules.yml

@@ -0,0 +1,586 @@
+# Alerts for llmgw. Every expression here is against a series this cluster
+# actually publishes; nothing is written against a metric that might exist.
+groups:
+  - name: llmgw-fleet
+    rules:
+      - alert: ControlPlaneUnreachable
+        expr: up{job="llmgw"} == 0
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "The control plane is not answering"
+          description: >-
+            Nothing has scraped 10.0.0.140:9091 for a minute. Engines already
+            running keep serving — the router is in the same process, so if
+            this is down, so is the gateway.
+
+      - alert: NodeNotReady
+        expr: llmgw_node_up == 0
+        for: 2m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} is {{ $labels.state }}"
+          description: >-
+            The node is known but not taking work. Two minutes, because a node
+            restarting its agent is briefly not ready and is not a problem.
+
+      - alert: AgentGoneQuiet
+        expr: llmgw_node_last_seen_seconds > 60
+        for: 1m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} has not reported for {{ $value | humanizeDuration }}"
+          description: >-
+            Heartbeats are every 5s. A minute of silence is the network or the
+            agent, and the control plane stages expiry at 15s unreachable and
+            60s lost — so this fires around the point it stops placing there.
+
+      - alert: ModelHasNothingServing
+        expr: llmgw_model_replicas_ready == 0
+        for: 10m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.model }} has no replica ready"
+          description: >-
+            The model should be running and nothing is serving it. Ten minutes,
+            because a large model on CPU legitimately takes minutes to load. The
+            series is published at 0 for every model that should be running —
+            before v0.10.4 it was published only while a replica was ready, so
+            this could not fire at all. A model deliberately stopped, or an
+            on-demand one nobody is asking for, publishes nothing.
+
+      - alert: ModelParked
+        expr: llmgw_model_parked == 1
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.model }} failed every time it started and is no longer retried"
+          description: >-
+            Five replicas in a row failed at start. Before this existed a model
+            whose weights its engine could not load was started 155 times over
+            eight hours. `llmgw ctl status` has the last error; once it is dealt
+            with, `llmgw ctl retry <model>`. Changing the model's definition
+            also retries it.
+
+      - alert: ModelFailingToStart
+        expr: llmgw_model_start_failures >= 2
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} has failed to start {{ $value }} times in a row"
+          description: >-
+            On its way to being parked. The engine's own words are in
+            `llmgw ctl logs <node> --source <shard>` for the next attempt, or in
+            the control plane's log for the last one.
+
+      - alert: ModelCannotBePlaced
+        expr: llmgw_model_unplaceable == 1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} is wanted and fits on no node"
+          description: >-
+            Short of replicas, and the last attempt found nowhere with the
+            memory, cards or engine it needs. `llmgw ctl explain-placement
+            <model>` says what each node lacks. For an on-demand model, requests
+            for it are told this rather than asked to retry.
+
+      - alert: ModelPreempted
+        expr: increase(llmgw_model_preempted_total[15m]) > 0
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.model }} ({{ $labels.class }}) gave up replicas to a higher class"
+          description: >-
+            Capacity ran short and a model of a higher class took this one's
+            room. Expected now and then; if it keeps firing for the same model,
+            the cluster is too small for what is asked of it at these classes.
+            `llmgw ctl models` shows who it gave way to.
+
+      - alert: CapacityAtLimit
+        expr: llmgw_capacity_holds >= on(scope, resource) llmgw_capacity_limit
+        for: 15m
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.scope }} holds all the {{ $labels.resource }} it may"
+          description: >-
+            Its models get no further replicas, under load or not, until
+            something of theirs stops or the limit is raised: `llmgw ctl quota
+            list`, `llmgw ctl quota set`.
+
+      - alert: EngineInstallFailed
+        expr: llmgw_node_engine_install{state="failed"} == 1
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.engine }} {{ $labels.version }} will not install on {{ $labels.node }}"
+          description: >-
+            The node takes no model needing it until it does. The agent retries
+            on its own; `llmgw ctl nodes` and the node's logs on the cluster
+            page say why it failed.
+
+      - alert: ControlPlaneLeadership
+        expr: sum(llmgw_control_plane_leader) != 1
+        for: 2m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $value }} control planes believe they are placing work"
+          description: >-
+            None means nothing is placed or replaced; two means both are, each
+            into GPUs the other believes free. The lease is in the store: check
+            it is reachable from every control plane.
+
+      - alert: CertificateExpiresSoon
+        expr: (llmgw_certificate_expiry_timestamp_seconds - time()) < 30 * 86400
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.cert }} ({{ $labels.subject }}) expires in {{ $value | humanizeDuration }}"
+          description: >-
+            Certificates last a year and nothing renews them. When the agent
+            server's runs out every agent refuses to connect at once. Reissue
+            with `llmgw ctl cert` and restart the control plane.
+
+      - alert: CertificateExpiresVerySoon
+        expr: (llmgw_certificate_expiry_timestamp_seconds - time()) < 7 * 86400
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.cert }} ({{ $labels.subject }}) expires in {{ $value | humanizeDuration }}"
+          description: See CertificateExpiresSoon; a week is not long.
+
+      - alert: BackupTooOld
+        expr: time() - llmgw_backup_last_success_timestamp_seconds > 26 * 3600
+        labels: { severity: warning }
+        annotations:
+          summary: "The newest llmgw backup is {{ $value | humanizeDuration }} old"
+          description: >-
+            llmgw-backup.timer runs nightly. Also fires when there has never
+            been a backup (the series is 0 then). `journalctl -u
+            llmgw-backup.service` on the control plane says why the last one
+            failed; docs/install.md, "Backing up", says how to set it up.
+
+      - alert: ModelUpdateAvailable
+        expr: llmgw_model_update_available == 1
+        for: 1h
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.repo }} has new weights for {{ $labels.model }}"
+          description: >-
+            The registry repository the model was served from has published
+            different files under the same names. `llmgw ctl model updates`
+            lists what changed; `llmgw ctl model update {{ $labels.model }}`
+            moves it to them, and `llmgw ctl model rollback` goes back.
+
+      - alert: PoolSaturated
+        expr: llmgw_pool_saturation > 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} is over its healthy limit"
+          description: >-
+            Saturation is the worse of queue depth and KV occupancy; 1 is the
+            limit measured as healthy, not the point of failure. Sustained above
+            it means requests are queueing — add a replica or lower the load.
+
+      - alert: EndpointBreakerOpen
+        expr: llmgw_endpoint_breaker_open == 1
+        for: 2m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.replica }} has been taken out of rotation"
+          description: >-
+            The router stopped sending to this replica after repeated failures.
+            Traffic is going elsewhere; if it is the only replica, the model is
+            down.
+
+      - alert: EndpointMetricsStale
+        expr: llmgw_endpoint_metrics_stale == 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.replica }} is being routed to blind"
+          description: >-
+            Its queue depth and KV usage are old, so the scheduler is choosing
+            with stale numbers. The replica may be serving perfectly well; the
+            decisions about it are the problem.
+
+      - alert: NodeDiskFilling
+        expr: llmgw_node_disk_free_bytes / llmgw_node_disk_total_bytes < 0.10
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} has {{ $value | humanizePercentage }} of its model disk free"
+          description: >-
+            Weights are tens of gigabytes. A node that cannot hold the next one
+            is skipped by placement rather than failing, so this is quiet until
+            somebody wonders why a model will not land there.
+
+  - name: llmgw-gpus
+    rules:
+      - alert: GPUThermalThrottling
+        expr: llmgw_gpu_throttled{reason=~"sw_thermal|hw_thermal|hw_slowdown"} == 1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} is slowed by heat ({{ $labels.reason }})"
+          description: >-
+            Ten minutes held back by temperature: every replica on the card is
+            slower than its measurements say. Usually airflow, a fan, or the
+            room — the node page shows the card's temperature over time.
+
+      - alert: GPUUncorrectedECCErrors
+        expr: llmgw_gpu_ecc_errors > 0
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has {{ $value }} uncorrected ECC errors"
+          description: >-
+            Uncorrected memory errors since the driver loaded: what runs on the
+            card may be computing on corrupted memory. Drain the node
+            (llmgw ctl drain) and have the card looked at.
+
+      - alert: GPUXidError
+        expr: increase(llmgw_gpu_xid_errors[15m]) > 0
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} logged an XID error"
+          description: >-
+            The driver reported an error on the card (its code is
+            llmgw_gpu_last_xid, and the node page says it in words). 79 is a
+            card fallen off the bus, 48 and 63/64 memory errors, 74 NVLink,
+            94/95 contained and uncontained ECC errors: those need the card
+            looked at. Others are often an engine's own fault, and pass.
+
+      - alert: GPUOutOfSpareRows
+        expr: llmgw_gpu_remap_failure == 1
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has no spare memory rows left"
+          description: >-
+            The card cannot remap another failing row. Drain the node and
+            have the card replaced.
+
+      - alert: GPUNeedsReset
+        expr: llmgw_gpu_remap_pending == 1 or llmgw_gpu_retirement_pending == 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has memory repairs waiting for a reset"
+          description: >-
+            Rows remapped or pages retired take effect only after the card is
+            reset. Drain the node (llmgw ctl drain), reset or reboot, and bring
+            it back.
+
+      - alert: GPUPCIeRetriesClimbing
+        expr: increase(llmgw_gpu_pcie_replays[1h]) > 100
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }}: {{ $value }} PCIe retries in an hour"
+          description: >-
+            The card's link to the host is retrying. A riser, the slot or a
+            cable is the usual cause, and transfers to the card slow down.
+
+      - alert: GPUNVLinkErrorsClimbing
+        expr: increase(llmgw_gpu_nvlink_errors{kind="crc"}[1h]) > 10
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }}: NVLink CRC errors climbing"
+          description: >-
+            Errors on the card's NVLink links: tensor-parallel replicas on it
+            slow down, and a link that keeps failing takes a replica with it.
+
+      - alert: GPUHot
+        expr: llmgw_gpu_temperature_celsius > 87
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} at {{ $value }} °C"
+          description: >-
+            Ten minutes above 87 °C, where most data-centre cards begin to
+            throttle.
+
+  - name: monitoring-host
+    rules:
+      - alert: MonitoringDiskFilling
+        expr: >-
+          node_filesystem_avail_bytes{job="monitoring-host",fstype!~"tmpfs|overlay|squashfs"}
+          / node_filesystem_size_bytes{job="monitoring-host",fstype!~"tmpfs|overlay|squashfs"} < 0.15
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.mountpoint }} on the monitoring host is {{ $value | humanizePercentage }} free"
+          description: >-
+            This filesystem holds the model mirror and the metrics database at
+            once. Filling it stops new weights arriving and stops Prometheus
+            writing — so monitoring goes quiet at the moment it is most needed,
+            which is why this fires at fifteen percent rather than five.
+
+      - alert: MonitoringDiskAlmostFull
+        expr: >-
+          node_filesystem_avail_bytes{job="monitoring-host",fstype!~"tmpfs|overlay|squashfs"}
+          / node_filesystem_size_bytes{job="monitoring-host",fstype!~"tmpfs|overlay|squashfs"} < 0.05
+        for: 5m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.mountpoint }} on the monitoring host has {{ $value | humanizePercentage }} left"
+
+  - name: llmgw-traffic
+    rules:
+      # These need traffic through the gateway to have any series at all. A
+      # counter with no observations publishes nothing, so a quiet cluster
+      # simply has no data here rather than a rule that is always false.
+      - alert: HighErrorRate
+        expr: >-
+          sum by (model) (rate(llmgw_requests_total{status=~"5.."}[5m]))
+          / sum by (model) (rate(llmgw_requests_total[5m])) > 0.05
+        for: 5m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.model }} is failing {{ $value | humanizePercentage }} of requests"
+
+      - alert: SlowFirstToken
+        expr: >-
+          histogram_quantile(0.99,
+            sum by (model, le) (rate(llmgw_ttft_seconds_bucket[10m]))) > 30
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} takes {{ $value | humanizeDuration }} to first token at p99"
+          description: >-
+            On CPU this is expected under load and is why the threshold is
+            thirty seconds rather than one. Compare with what ctl bench measured
+            before treating it as a fault.
+
+      - alert: RequestsBeingRejected
+        expr: sum by (band) (rate(llmgw_admission_rejected_total[5m])) > 0
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "Admission is turning away {{ $labels.band }} traffic"
+          description: >-
+            Working as designed when the cluster is full: the lowest band is
+            held first. Worth knowing about because the callers being refused
+            do not know why.
+
+  # Per tenant: the level router.tenant_label names (a team by default), and
+  # every organization, team, project and person given a budget.
+  - name: llmgw-tenants
+    rules:
+      - alert: BudgetMostlySpent
+        expr: llmgw_budget_spent_ratio >= 0.8 and llmgw_budget_spent_ratio < 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.scope }} {{ $labels.name }} has spent {{ $value | humanizePercentage }} of its {{ $labels.period }}ly budget"
+          description: >-
+            Its requests are refused once it reaches all of it, until the
+            period turns. Raise it on the people page, or tell them now
+            rather than when they are refused.
+
+      - alert: BudgetSpent
+        expr: llmgw_budget_spent_ratio >= 1
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.scope }} {{ $labels.name }} has spent its {{ $labels.period }}ly budget"
+          description: >-
+            Every request under it is refused with 429 until the period
+            turns, unless a cheaper model is named as its fallback.
+
+      - alert: TenantHittingLimits
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total{outcome="limited"}[10m]))
+          / sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of {{ $labels.tenant }}'s requests are refused by a limit"
+          description: >-
+            A rate, token or budget limit is turning their traffic away. Either
+            the limit is too low for what they now do, or something of theirs
+            is looping.
+
+      - alert: TenantErrors
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total{outcome="error"}[10m]))
+          / sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.05
+          and sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.05
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of {{ $labels.tenant }}'s requests fail"
+          description: >-
+            Not counting refusals by a limit. If every tenant fails alike it
+            is a model (ModelFailing); one alone is usually what they send —
+            prompts past the context, a model they may not use.
+
+      - alert: TenantTrafficSpike
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total[30m]))
+          > 3 * sum by (tenant) (rate(llmgw_tenant_requests_total[7d]))
+          and sum by (tenant) (rate(llmgw_tenant_requests_total[30m])) > 0.2
+        for: 15m
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.tenant }} is sending three times its weekly average"
+          description: >-
+            A new workload, a batch job, or a client retrying in a loop. Only
+            for a tenant sending more than one request every five seconds, so
+            a quiet team starting work in the morning does not page anybody.
+
+      - alert: TenantSlowFirstToken
+        expr: >-
+          histogram_quantile(0.95,
+            sum by (tenant, le) (rate(llmgw_tenant_ttft_seconds_bucket[15m]))) > 10
+          and sum by (tenant) (rate(llmgw_tenant_ttft_seconds_count[15m])) > 0.02
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.tenant }} waits {{ $value | humanizeDuration }} for a first token at p95"
+          description: >-
+            What their people feel. Compare with SlowFirstToken per model: if
+            only this tenant is slow, it is the models it uses or its queue
+            band, not the cluster.
+  # The store, when it is a replicated cluster under Patroni (llmgw server
+  # init --patroni). Published only for a store of several hosts.
+  - name: llmgw-store
+    rules:
+      - alert: StoreHasNoLeader
+        expr: llmgw_store_patroni_up == 1 and on() count(llmgw_store_member{role="leader"}) == 0
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "The store's cluster has no primary"
+          description: >-
+            Every write fails — keys, usage, budgets, leadership. Patroni
+            promotes a standby within its 30-second TTL; a minute without one
+            means it cannot: etcd has lost its majority, or no standby is fit.
+            `patronictl -c /etc/patroni/config.yml list` on a member says which.
+
+      - alert: StorePatroniUnreachable
+        expr: llmgw_store_patroni_up == 0
+        for: 2m
+        labels: { severity: warning }
+        annotations:
+          summary: "No member of the store's cluster answers on its Patroni port"
+          description: >-
+            The control plane reads the cluster's state from port 8008 on each
+            member. The database may still be serving; nothing here can tell.
+
+      - alert: StoreReplicaNotStreaming
+        expr: llmgw_store_member{role!="leader", state!="streaming"} == 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.member }} is {{ $labels.state }}, not streaming from the primary"
+          description: >-
+            A standby that is not streaming is not a standby: if the primary
+            is lost now, there is nothing to promote. "missing" is a host of
+            the store address the cluster no longer lists — usually a machine
+            that is down.
+
+      - alert: StoreReplicaBehind
+        expr: llmgw_store_replica_lag_bytes > 64 * 1024 * 1024 or llmgw_store_replica_lag_bytes == -1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.member }} is {{ $value | humanize1024 }}B behind the primary"
+          description: >-
+            Patroni will not promote a standby more than 1 MB behind, so a
+            failover now would find none fit. -1 is a lag Patroni cannot read.
+
+  - name: llmgw-guard
+    rules:
+      - alert: GuardFailingOpen
+        expr: >-
+          sum(rate(llmgw_guard_fail_open_total[5m]))
+            / clamp_min(sum(rate(llmgw_guard_checks_total[5m])), 1e-9) > 0.01
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of judged traffic is served unjudged"
+          description: >-
+            A guard policy's judge model is not answering within its latency
+            budget, and the policy fails open: requests go through flagged
+            "judge unavailable" instead of being judged.
+            llmgw_guard_judge_errors_total says whether it is timing out or
+            not there; `llmgw ctl replicas` whether the judge has replicas.
+
+      - alert: GuardJudgeSlow
+        expr: >-
+          histogram_quantile(0.95, sum by (le, judge_model) (rate(llmgw_guard_judge_latency_seconds_bucket[5m]))) > 0.25
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "Judge {{ $labels.judge_model }} answers in {{ $value | humanizeDuration }} at p95"
+          description: >-
+            Over the default latency budget: every judged request waits this
+            long, and those over their policy's budget are served unjudged or
+            refused. Give the judge more replicas, or faster ones.
+
+      - alert: GuardJudgeUnavailable
+        expr: sum by (reason) (rate(llmgw_guard_judge_errors_total{reason!="timeout"}[5m])) > 0
+        for: 5m
+        labels: { severity: critical }
+        annotations:
+          summary: "The guardrails cannot ask their judge ({{ $labels.reason }})"
+          description: >-
+            no_judge: a policy names a model that is not in the catalog with
+            role: guard. unavailable: it has no replica answering. format: it
+            answers in a form its guard.format does not read.
+
+      - alert: GuardBlocksSpiking
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_guard_blocks_total[1h]))
+            > 3 * sum by (tenant) (rate(llmgw_tenant_guard_blocks_total[7d]))
+          and sum by (tenant) (increase(llmgw_tenant_guard_blocks_total[1h])) > 10
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.tenant }} is being blocked three times as often as usual"
+          description: >-
+            A tenant's requests or answers are blocked by the guardrails
+            more than three times their weekly rate. Someone probing, a
+            client sending data it should not, or a policy that changed.
+            The /admin/guard page lists the recent ones by request.
+
+      - alert: GuardSecretInAnswer
+        expr: sum(increase(llmgw_guard_checks_total{stage="output",category="secret",action!="allowed"}[5m])) > 0
+        labels: { severity: critical }
+        annotations:
+          summary: "A model put a credential in an answer"
+          description: >-
+            An answer contained something shaped like a key or a private key.
+            It was stopped or rewritten if the policy enforces; either way a
+            model has seen it, in its prompt or its training. The usage rows
+            with guard_category secret say which request.
+
+  - name: llmgw-slo
+    rules:
+      - alert: ModelTTFTOverSLO
+        expr: >-
+          histogram_quantile(0.99, sum by (le, model) (rate(llmgw_ttft_seconds_bucket[10m])))
+            > on (model) group_left llmgw_model_slo_seconds{kind="ttft_p99"}
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} answers its first token past its SLO at p99"
+          description: >-
+            The p99 time to the first token over ten minutes is past the
+            model's slo.ttft_p99. Admission already holds the lower bands back
+            while it is; this says it has lasted. More replicas, or less
+            traffic in the bands above.
+
+      - alert: ModelTPOTOverSLO
+        expr: >-
+          histogram_quantile(0.99, sum by (le, model) (rate(llmgw_tpot_seconds_bucket[10m])))
+            > on (model) group_left llmgw_model_slo_seconds{kind="tpot_p99"}
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} produces tokens slower than its SLO at p99"
+          description: >-
+            The p99 time per output token is past slo.tpot_p99: replicas are
+            batching more than they can decode quickly, or a slower card is
+            serving. llmgw_output_tokens_per_second by pool says which.

deploy/monitoring/prometheus.yml

@@ -0,0 +1,65 @@
+# Prometheus for the llmgw cluster.
+#
+# One scrape target for the whole fleet. Agents publish nothing of their own —
+# the control plane gathers what they report and republishes it, so node health,
+# disk and endpoint state all arrive here from 10.0.0.140.
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+  external_labels:
+    cluster: mynodes
+
+alerting:
+  alertmanagers:
+    - static_configs:
+        - targets: ['localhost:9093']
+
+rule_files:
+  - /etc/prometheus/rules/llmgw.yml
+
+scrape_configs:
+  # The control plane's dedicated metrics port. Not its admin listener: that one
+  # is loopback because it also serves pprof, and pprof can dump the heap where
+  # API keys sit in plaintext.
+  #
+  # Every control plane, one line each: the leader moves on restarts and the
+  # router's metrics are the leading one's, so scraping one alone leaves gaps
+  # — and alerts on them — whenever another leads.
+  - job_name: llmgw
+    static_configs:
+      - targets: ['10.0.0.140:9091']
+        labels:
+          instance: control-plane-140
+      # - targets: ['10.0.0.150:9091']
+      #   labels:
+      #     instance: control-plane-150
+
+  # Every machine of the cluster, for its node exporter: network and disk
+  # traffic, filesystems, CPU time. The control plane lists them — nodes,
+  # itself, the store's members — so a node added is a node scraped with
+  # nothing edited here, and each carries its llmgw id as the node label.
+  # `llmgw node add` installs the exporter; on a machine added before that,
+  # apt-get install prometheus-node-exporter.
+  # Asked of every control plane too: a standby lists only the control
+  # planes and the store, and they label every machine alike, so the same
+  # target from two of them is scraped once.
+  - job_name: nodes
+    http_sd_configs:
+      - url: http://10.0.0.140:9091/prometheus/targets
+        refresh_interval: 1m
+      # - url: http://10.0.0.150:9091/prometheus/targets
+      #   refresh_interval: 1m
+
+  - job_name: prometheus
+    static_configs:
+      - targets: ['localhost:9090']
+
+  # The machine this runs on. It came with the Prometheus package and was not
+  # being scraped, which left the disk holding both the model mirror and the
+  # metrics themselves watched by nothing — so a mirror that filled it would
+  # take monitoring down and the alert that would have warned did not exist.
+  - job_name: monitoring-host
+    static_configs:
+      - targets: ['localhost:9100']
+        labels:
+          instance: monitoring

deploy/proxy/Caddyfile

@@ -0,0 +1,75 @@
+# llmgw behind Caddy: the client-facing port (8080) on a public name, with a
+# certificate Caddy obtains and renews by itself.
+#
+# Replace llm.example.com, point its DNS at this machine, open 80 and 443, and
+# run: caddy run --config /etc/caddy/Caddyfile
+#
+# Only 8080 goes through here. 7443 (agents) is mutual TLS with the cluster's
+# own authority and must reach llmgw directly; 9090 and 9091 stay private.
+
+llm.example.com {
+	# The router reads at most 32 MiB of body (router.max_body_bytes). Refusing
+	# more here gives the client a 413 before the upload, not after it.
+	request_body {
+		max_size 32MB
+	}
+
+	# One control plane. With more than one, see the end of this file.
+	reverse_proxy 127.0.0.1:8080 {
+		# Tokens are written the moment they are generated. Without this a
+		# streamed reply can arrive in bursts, and a client measuring time to
+		# first token measures the proxy instead.
+		flush_interval -1
+
+		# Caddy sets X-Forwarded-Proto and X-Forwarded-Host itself and, with
+		# no trusted_proxies, discards whatever the client sent. llmgw relies
+		# on that: the proto decides whether session cookies are Secure, and
+		# the host is the base URL the landing page tells people to use.
+		# Behind a load balancer of your own, name it in trusted_proxies.
+
+		transport http {
+			# A long generation can be silent for a while before the first
+			# token. llmgw has its own limits (timeouts.*); this must not be
+			# the shorter one.
+			response_header_timeout 15m
+		}
+	}
+
+	# No `encode` on purpose: compressing a stream buffers it.
+
+	# Access log to stderr, which under systemd is the journal.
+	log
+}
+
+# More than one control plane (server init --standbys, server add): one of
+# them leads, the others stand by. Name them all and send to the one that
+# leads — /leader is 200 there and 503 on a standby. Not /ready: that is 503
+# on a leader with no model running yet, and would take the portal away with
+# it. A standby would pass a request on to the leader anyway, but not while
+# there is none, and the hop is for nothing.
+#
+# With a floating address (--vip) the address already follows the leader:
+# give reverse_proxy that one address instead, and keep the rest as above.
+#
+# llm.example.com {
+# 	request_body {
+# 		max_size 32MB
+# 	}
+# 	reverse_proxy 10.0.0.157:8080 10.0.0.158:8080 10.0.0.159:8080 {
+# 		# The first that is healthy: the leader, whichever it is.
+# 		lb_policy first
+# 		health_uri /leader
+# 		health_interval 2s
+# 		health_timeout 2s
+# 		# While leadership moves — a few seconds when a leader is lost —
+# 		# none is healthy; a request waits that long for one rather than
+# 		# failing at once.
+# 		lb_try_duration 15s
+# 		lb_try_interval 250ms
+# 		flush_interval -1
+# 		transport http {
+# 			response_header_timeout 15m
+# 		}
+# 	}
+# 	log
+# }

deploy/proxy/README.md

@@ -0,0 +1,39 @@
+# A reverse proxy in front of llmgw
+
+The client-facing port (8080) is plain HTTP. On anything but a trusted network,
+put it behind a proxy that holds a publicly trusted certificate.
+
+| File | For |
+| --- | --- |
+| [Caddyfile](Caddyfile) | Caddy — obtains and renews its own certificate; the least work |
+| [nginx.conf](nginx.conf) | nginx, with a certificate from certbot |
+
+Both are also attached to every release.
+
+The `/about` page shows both, from copies in `internal/web/proxy`; a test fails
+when those differ from these, so change them here and copy them over.
+
+Four things both files get right, and any other proxy has to as well:
+
+- **Streaming is not buffered.** Replies are server-sent events; a buffering
+  proxy delivers them in one burst at the end.
+- **The read timeout is longer than a model's silence.** nginx's default of 60
+  seconds turns a slow first token into a 504.
+- **`X-Forwarded-Proto` and `X-Forwarded-Host` are set by the proxy**, replacing
+  whatever the client sent. llmgw uses the first to mark session cookies
+  `Secure` and the second for the base URL on its landing page.
+- **The body limit matches llmgw's** (32 MiB, `router.max_body_bytes`), so an
+  oversized request is refused before it is uploaded.
+
+Only port 8080 is proxied. Agents reach 7443 directly — it is mutual TLS with
+the cluster's own authority, and a proxy terminating it would take away the
+node identity it carries. 9090 (admin, pprof) stays on loopback; 9091
+(metrics) goes to your monitoring host only.
+
+With a proxy on the same machine, bind llmgw to loopback so nothing reaches it
+around the proxy:
+
+```yaml
+# /etc/llmgw/server.yaml
+listen: "127.0.0.1:8080"
+```

deploy/proxy/nginx.conf

@@ -0,0 +1,63 @@
+# llmgw behind nginx: the client-facing port (8080) on a public name.
+#
+# Put this in /etc/nginx/sites-available/llmgw (or conf.d/llmgw.conf), replace
+# llm.example.com, and get a certificate — certbot --nginx -d llm.example.com
+# fills in the ssl_ lines below. Then: nginx -t && systemctl reload nginx
+#
+# Only 8080 goes through here. 7443 (agents) is mutual TLS with the cluster's
+# own authority and must reach llmgw directly; 9090 and 9091 stay private.
+
+upstream llmgw {
+    server 127.0.0.1:8080;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llm.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    # `listen ... http2` rather than `http2 on;`: the latter needs nginx
+    # 1.25.1, and Ubuntu 22.04 and Debian 12 ship older ones. Newer nginx
+    # accepts this form with a deprecation warning.
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name llm.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/llm.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/llm.example.com/privkey.pem;
+
+    # The router reads at most 32 MiB of body (router.max_body_bytes).
+    client_max_body_size 32m;
+
+    location / {
+        proxy_pass http://llmgw;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+
+        # Set, never appended: llmgw decides from X-Forwarded-Proto whether
+        # session cookies are Secure, and builds the base URL the landing page
+        # shows from X-Forwarded-Host. A value passed through from the client
+        # would be the client's choice.
+        proxy_set_header Host              $host;
+        proxy_set_header X-Forwarded-Host  $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+
+        # Streamed replies: tokens go out as they are generated. Buffering
+        # turns a stream into one late burst, and gzip buffers too.
+        proxy_buffering off;
+        proxy_cache off;
+        gzip off;
+
+        # nginx's default is 60 seconds between two reads from upstream. A
+        # large model can think longer than that before its first token, and
+        # the client then sees a 504 for a request that was about to succeed.
+        # llmgw has its own limits (timeouts.*); this must not be the shorter.
+        proxy_read_timeout 15m;
+        proxy_send_timeout 15m;
+    }
+}

deploy/systemd/README.md

@@ -0,0 +1,34 @@
+# systemd units
+
+Two roles, two units. Copy the one you need to `/etc/systemd/system/`, put the
+matching configuration in `/etc/llmgw/`, and `systemctl enable --now` it.
+
+## The control plane — `llmgw-server.service`
+
+Runs unprivileged. It needs to read its own TLS key, so that file must belong to
+the `llmgw` user and nothing else:
+
+```
+useradd --system --home-dir /var/lib/llmgw --shell /usr/sbin/nologin llmgw
+chown llmgw:llmgw /etc/llmgw/server-key.pem
+chmod 0400 /etc/llmgw/server-key.pem
+```
+
+`StateDirectory=llmgw` creates `/var/lib/llmgw` with the right owner, which is
+where the store belongs. `ProtectSystem=strict` makes the rest of the filesystem
+read-only, so anything else it writes to has to be named explicitly.
+
+## The agent — `llmgw-agent.service`
+
+Runs as root, because it launches engines and needs device access.
+
+`KillMode=process` is the line that matters and the reason this file exists
+rather than being generated. Without it, systemd kills the whole control group
+on stop — including the engines, which hold a loaded model and are serving
+traffic. Engines are meant to outlive an agent restart: the router talks to them
+directly, and the agent adopts them again when it comes back. Taking them down
+with the agent turns a thirty-second upgrade into a full model reload on every
+node.
+
+systemd will log `Found left-over process ... in control group while starting
+unit. Ignoring.` on the next start. That is the mechanism working, not a fault.

deploy/systemd/llmgw-agent.service

@@ -0,0 +1,24 @@
+[Unit]
+Description=llmgw node agent
+After=network-online.target
+Wants=network-online.target
+# Never given up on: a new release that fails its first starts, or an upgrade
+# that restarts it twice in a minute, would otherwise leave the node off.
+StartLimitIntervalSec=0
+
+[Service]
+ExecStart=/usr/local/bin/llmgw agent --config /etc/llmgw/agent.yaml
+# Root, because the agent launches engines and needs device access. Engines
+# outlive a restart of this unit and are adopted again on the next start, so
+# KillMode must not take the whole process group with it.
+KillMode=process
+Restart=on-failure
+RestartSec=2s
+# RDMA pins the buffers it registers, and NCCL registers a great deal: with
+# systemd's default 8 MB lock limit, an engine that drops the capability that
+# lets root ignore it fails its first collective over InfiniBand.
+LimitMEMLOCK=infinity
+StateDirectory=llmgw-agent
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/llmgw-backup.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=llmgw backup: the store and /etc/llmgw, to /var/backups/llmgw-server
+After=llmgw-server.service postgresql.service
+
+[Service]
+Type=oneshot
+# Nothing it writes is for anyone else: the archive holds the CA's key and a
+# copy of the store.
+UMask=0077
+# Root, because the archive includes /etc/llmgw/secrets and the certificate
+# authority's key, which the llmgw user deliberately cannot read all of.
+ExecStart=/usr/local/bin/llmgw server backup --config /etc/llmgw/server.yaml --keep 14
+Nice=10
+IOSchedulingClass=idle

deploy/systemd/llmgw-backup.timer

@@ -0,0 +1,12 @@
+[Unit]
+Description=Back up llmgw every night
+
+[Timer]
+OnCalendar=*-*-* 03:15:00
+# A machine that was off at 03:15 backs up when it next starts, rather than
+# waiting another day with a gap nobody notices until the alert.
+Persistent=true
+RandomizedDelaySec=10m
+
+[Install]
+WantedBy=timers.target

deploy/systemd/llmgw-mirror.service

@@ -0,0 +1,29 @@
+[Unit]
+Description=llmgw model mirror
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# --base is what a catalog entry will say, so it has to be the address nodes
+# reach this machine on — not localhost, and not the name only this host knows
+# itself by. Getting it wrong makes `mirror unused` report files as unreferenced
+# when they are in use, and the next step after that list is deletion.
+ExecStart=/usr/local/bin/llmgw mirror serve \
+    --dir /srv/models \
+    --listen :8081 \
+    --api-listen :8082 \
+    --base http://models.internal:8081
+User=llmgw
+Group=llmgw
+Restart=on-failure
+RestartSec=2s
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+# The one writable path. The mirror serves reads to the whole fleet and writes
+# only what its own API was asked to fetch, so nothing else needs to be.
+ReadWritePaths=/srv/models
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/llmgw-server.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=llmgw control plane
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/llmgw server --config /etc/llmgw/server.yaml
+User=llmgw
+Group=llmgw
+Restart=on-failure
+RestartSec=2s
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+StateDirectory=llmgw
+
+[Install]
+WantedBy=multi-user.target

docs.go

@@ -0,0 +1,109 @@
+// Package llmgw holds what the binary carries besides code: its manual, the
+// description of its admin API, and the example quality suites.
+package llmgw
+
+import (
+	"embed"
+	"io/fs"
+	"sort"
+	"strings"
+)
+
+// Docs is the documentation, read on any machine by `llmgw docs` and the
+// console's manual without a checkout or the internet.
+//
+//go:embed README.md CHANGELOG.md docs/*.md
+var Docs embed.FS
+
+// Doc is one page of the manual.
+type Doc struct {
+	// Key is what `llmgw docs KEY` takes, and the page's address under /docs/
+	// on the gateway.
+	Key string
+	// Path is the file in Docs.
+	Path string
+	// Title is the document's first heading.
+	Title string
+}
+
+// Source is the document's markdown.
+func (d Doc) Source() string {
+	b, err := fs.ReadFile(Docs, d.Path)
+	if err != nil {
+		return "# " + d.Path + "\n\nNot in this build."
+	}
+	return string(b)
+}
+
+// docOrder is the documents in the order someone new reads them. Here rather
+// than with either reader, because the console's manual and the gateway's
+// docs portal both list them, and two lists drift.
+var docOrder = []string{"console", "quick-install", "install", "node-onboarding", "onboarding",
+	"clients", "guardrails", "knowledge", "choosing-models", "fabrics", "facility-aware-placement", "data",
+	"reference", "development"}
+
+// Manual is every document, in reading order: those docOrder names, then any
+// other under docs/ alphabetically, so a new one is never missing, then the
+// README and the changes.
+func Manual() []Doc {
+	var out []Doc
+	seen := map[string]bool{}
+	add := func(key, path string) {
+		if seen[key] {
+			return
+		}
+		b, err := fs.ReadFile(Docs, path)
+		if err != nil {
+			return
+		}
+		seen[key] = true
+		out = append(out, Doc{Key: key, Path: path, Title: titleOf(string(b), path)})
+	}
+	for _, k := range docOrder {
+		add(k, "docs/"+k+".md")
+	}
+	entries, _ := fs.ReadDir(Docs, "docs")
+	var rest []string
+	for _, e := range entries {
+		if strings.HasSuffix(e.Name(), ".md") {
+			rest = append(rest, strings.TrimSuffix(e.Name(), ".md"))
+		}
+	}
+	sort.Strings(rest)
+	for _, k := range rest {
+		add(k, "docs/"+k+".md")
+	}
+	add("readme", "README.md")
+	add("changes", "CHANGELOG.md")
+	return out
+}
+
+// titleOf is a document's first top-level heading, or its path when it has
+// none.
+func titleOf(src, path string) string {
+	for _, l := range strings.Split(src, "\n") {
+		if strings.HasPrefix(l, "# ") {
+			return strings.TrimSpace(strings.TrimPrefix(l, "# "))
+		}
+	}
+	return path
+}
+
+// AdminOpenAPI is the admin API described in OpenAPI 3.1, generated from its
+// route table by `go generate` in internal/docgen and served at
+// /api/v1/openapi.json, so a client can be pointed at the server it talks to.
+//
+//go:embed docs/admin-api.openapi.json
+var AdminOpenAPI []byte
+
+// ClientOpenAPI is the client API described in OpenAPI 3.1, generated from
+// internal/clientapi's route table and served at /v1/openapi.json.
+//
+//go:embed docs/client-api.openapi.json
+var ClientOpenAPI []byte
+
+// EvalSuites are the example quality suites under deploy/eval, which the
+// control plane runs by name when its eval directory has none of the name.
+//
+//go:embed deploy/eval/*.yaml
+var EvalSuites embed.FS

docs/admin-api.md

@@ -0,0 +1,169 @@
+# The admin API
+
+Written for whoever automates a cluster rather than typing at it: how to reach
+the control plane's management API, what it asks of a request, and where its
+description is.
+
+`llmgw ctl` and the console are clients of this API and nothing more, so
+anything they do can be done with `curl`, a generated client or the
+[Terraform provider](../terraform-provider-llmgw/README.md). It adds and
+removes models, scales them, cordons and upgrades nodes, sets capacity
+quotas, attaches guardrail policies, adds organizations, teams and projects,
+issues and revokes API keys, puts people in the tree, and reads the fleet,
+usage and the audit log.
+
+## Reaching it
+
+The API is under `/api/v1` on the admin listener, `admin_listen` in
+`/etc/llmgw/server.yaml`: `127.0.0.1:9090` unless changed. It is on loopback
+on purpose. The same listener serves pprof when it is turned on, and the
+server refuses to start with it on any other address unless
+`admin_remote: true` — the token would cross the network in clear.
+
+From another machine, tunnel to it rather than moving it:
+
+```sh
+ssh -N -L 9090:127.0.0.1:9090 admin@control-plane &
+curl -s -H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" http://127.0.0.1:9090/api/v1/summary
+```
+
+With `admin_remote: true` and `admin_listen: 10.0.0.5:9090`, call that address
+directly — on a network you trust, or behind a TLS proxy that keeps the
+`Host` header an address.
+
+## The token
+
+Every path under `/api` needs the admin token as a bearer token:
+
+```
+Authorization: Bearer 6f1c…
+```
+
+The server writes it the first time it starts, 0600, to
+`/var/lib/llmgw/admin-token` under its systemd unit (`admin_token_file`
+moves it; a server run by hand keeps it in `secrets/admin-token` beside its
+configuration). `llmgw ctl` reads it from there, which is why it runs with
+sudo, or from `LLMGW_ADMIN_TOKEN`. To give it to automation:
+
+```sh
+sudo cat /var/lib/llmgw/admin-token
+```
+
+The token is the whole of the API's authorisation: whoever holds it can do
+everything the API does. Keep it where you keep other root credentials.
+
+## What a request must look like
+
+Besides the token, the listener refuses three things before a handler sees
+them, as defences against a browser being turned against it:
+
+- **A name in `Host`.** The listener answers to an address or `localhost`,
+  not a DNS name, so a page on some other site cannot reach it by rebinding
+  a name to 127.0.0.1. Call it as `http://127.0.0.1:9090`, not
+  `http://cp.example.com:9090`; behind a proxy, have the proxy send an
+  address.
+- **A cross-site request.** One whose `Origin` is another host, or whose
+  `Sec-Fetch-Site` says another site sent it.
+- **A change that is not JSON.** Every method but `GET` and `HEAD` must carry
+  `Content-Type: application/json`, even a `DELETE` or a `POST` with no body.
+  A form post from a page cannot set that header.
+
+A change is recorded in the audit log with who made it, as the request says
+in `X-Llmgw-Actor` (letters, digits and `._-@`, at most 64; `unknown` when
+absent). `llmgw ctl` sends the name of whoever ran it; automation should send
+its own, `terraform` or `ci@deploy`, so `llmgw ctl audit` can tell them apart.
+
+A refusal is a 4xx or 5xx with `{"error": "…"}` saying why. 501 means this
+control plane lacks what the endpoint needs — a store, a mirror, guard
+policies — and says which.
+
+## Some calls
+
+```sh
+H=(-H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" -H "Content-Type: application/json" -H "X-Llmgw-Actor: $USER")
+API=http://127.0.0.1:9090/api/v1
+
+# The fleet in one answer, and every model.
+curl -s "${H[@]}" $API/summary
+curl -s "${H[@]}" $API/models
+
+# Add a model, read back its definition with the defaults filled in, scale it.
+curl -s "${H[@]}" -X POST $API/models -d '{
+  "name": "qwen-small",
+  "source": "/srv/models/qwen2.5-1.5b-instruct-q4_k_m.gguf",
+  "profiles": [{"name": "cpu", "engine": "llamacpp", "min_memory_gb": 4, "cpu_cores": 4}],
+  "scaling": {"min": 1, "max": 2}
+}'
+curl -s "${H[@]}" $API/models/qwen-small
+curl -s "${H[@]}" -X POST $API/models/qwen-small/scale -d '{"min": 0, "max": 2, "idle_timeout": 1800000000000}'
+
+# A team's capacity quota.
+curl -s "${H[@]}" -X PUT $API/quotas -d '{"scope": "team:Acme/ml", "limit": {"gpus": 8}}'
+
+# An organization, a team in it and a project in that; then a key for the
+# project. The answer holds the key once: only its hash is kept.
+curl -s "${H[@]}" -X POST $API/orgs -d '{"name": "Acme"}'
+curl -s "${H[@]}" -X POST $API/teams -d '{"name": "ml", "in": "Acme"}'
+curl -s "${H[@]}" -X POST $API/projects -d '{"name": "search", "in": "Acme/ml"}'
+curl -s "${H[@]}" -X POST $API/keys -d '{"name": "ci", "project": "Acme/ml/search", "expires_in": "720h"}'
+curl -s "${H[@]}" -X POST $API/users/ayse@example.com/memberships -d '{"target": "team:Acme/ml"}'
+
+# Remove the model; a DELETE carries the content type too.
+curl -s "${H[@]}" -X DELETE $API/models/qwen-small
+```
+
+Durations in bodies are integer nanoseconds, as Go encodes them: half an hour
+is `1800000000000`.
+
+## The description
+
+The API is described in OpenAPI 3.1:
+
+- served by every control plane at `GET /api/v1/openapi.json` (with the
+  token, like the rest), as built into that binary, so it describes the
+  server you are talking to;
+- committed as [admin-api.openapi.json](admin-api.openapi.json) for reading
+  without a cluster.
+
+```sh
+curl -s "${H[@]}" $API/openapi.json > llmgw-admin.json
+```
+
+It lists every endpoint, its path and query parameters, and the schema of
+each request and answer, with the meaning of each field. Load it into any
+OpenAPI tool — Swagger UI, Redoc, an editor — or generate a client from it:
+
+```sh
+docker run --rm -v "$PWD:/w" openapitools/openapi-generator-cli generate \
+  -i /w/llmgw-admin.json -g python -o /w/llmgw-admin-client
+```
+
+### How it is kept true
+
+The document is generated, not written. `internal/control/adminapi/routes.go`
+holds a table of every endpoint: its method and path, a summary, its query
+parameters, and Go values of the types it reads and answers with. The
+generator in `internal/docgen/openapi` reads those types by reflection, the
+way `encoding/json` encodes them, and takes each field's description from its
+comment in the source.
+
+Two tests keep it from drifting. One registers the API on a recording mux and
+fails when an endpoint is served and not in the table, or in the table and not
+served. The other regenerates the document and fails when it differs from the
+committed one. After changing an endpoint or a type it carries:
+
+```sh
+go generate ./internal/docgen
+```
+
+## What it does not cover
+
+- **Making people's accounts.** People sign up, are invited, or come from
+  the identity provider (OIDC, SCIM); the API lists them and puts them in
+  the tree, and `llmgw users` approves, disables and deletes them. Key
+  lifetime limits and spending limits are `llmgw keys ttl` and `llmgw keys
+  limits`.
+- **The client-facing API** (`/v1/chat/completions` and the rest), which is
+  OpenAI's and Anthropic's, on `listen`, with API keys.
+- **The rest of the admin listener**: `/metrics`, `/health`, the dashboard
+  pages and `/debug/pprof`, which are not under `/api`.

docs/choosing-models.md

@@ -0,0 +1,149 @@
+# Choosing what to run
+
+llmgw serves whatever you give it and has no opinion about which models those
+are. This page has an opinion, because "we have GPUs, now what" is the question
+that stalls most of these projects — and the usual first answer, one large
+model, is the wrong shape.
+
+Model releases move faster than documentation. Treat the families named here as
+a starting point and check what is current before committing; the reasoning is
+what should outlive the names.
+
+## Three jobs, not one model
+
+The requests a company actually makes fall into three groups with different
+needs, and no single model serves all three well.
+
+**Interactive** — chat, autocomplete, short questions. Most of your traffic.
+Here latency beats quality: a person waits two seconds and does not wait
+twenty. A 7–14B class model, always resident.
+
+**Heavy** — long document analysis, code generation, anything that needs
+reasoning. Quality beats latency, and a queue is acceptable. A 30–70B class
+model, loaded on demand:
+
+```yaml
+scaling: { min: 0, max: 1, idle_timeout: 30m }
+```
+
+llmgw starts it when somebody asks and stops it when nobody has, so it costs
+nothing while it is not in use. The first request waits for the load, and the
+client is told that rather than refused.
+
+**Embeddings** — and this is the one that gets forgotten. Most "let us chat
+with our documents" projects are retrieval projects, and retrieval runs on an
+embedding model. It is small, it is cheap, and it carries the highest request
+volume of the three: every document chunk once, every query forever. llmgw
+routes `/v1/embeddings` like any other endpoint.
+
+A deployment with the first two and not the third can answer questions from
+what the model already knew. It cannot answer questions about your company.
+
+## Swedish and English
+
+The first thing to know is that this combination is harder than either alone.
+
+Open models are strongest in English by a wide margin. Swedish is served —
+better than most languages its size, because the Nordic languages appear in
+multilingual training sets — but the gap is real, and it widens as models get
+smaller. **A 7B model that feels fine in English can feel noticeably worse in
+Swedish**, which means the interactive tier may need to be larger than an
+English-only deployment would choose. Test before deciding; do not assume the
+English benchmark transfers.
+
+Two things matter more than the model's headline multilingual score:
+
+**Cross-lingual retrieval.** A Swedish company writes internal documents in
+Swedish and reads technical documentation in English. Somebody will ask a
+question in Swedish whose answer is in an English document. An embedding model
+that handles both languages separately may still fail to connect them, and it
+fails silently — the model gives a confident answer from the wrong source, and
+nobody notices because the answer reads well. Test this explicitly: ask in one
+language, check that documents in the other are retrieved.
+
+**Swedish compounds.** *Kundtjänstmedarbetare* is one token-hostile word where
+English would use three. This hurts keyword search more than dense retrieval,
+so if you run hybrid search, expect the lexical half to underperform on Swedish
+and weight accordingly.
+
+## How to actually decide
+
+Benchmarks will not settle this. Take twenty real documents and twenty real
+questions from the company — in both languages, including at least a few where
+the question and the answer are in different languages — and compare candidates
+on those. An afternoon of this is worth more than a week of reading leaderboards,
+and it is the only way to find the failure modes that matter to you.
+
+Do the same for the embedding model, separately. A good generation model on top
+of bad retrieval produces fluent, confident, wrong answers, which is the worst
+failure this stack has: it does not look like a failure.
+
+## How many replicas
+
+Not "how many employees". **Concurrency**, which is far lower than headcount
+because people spend most of their time reading rather than waiting on a model.
+Two hundred people generate perhaps five to fifteen concurrent requests at
+peak, for interactive use.
+
+vLLM batches continuously, so one replica on a capable card serves many
+concurrent requests. Which means the replica count is usually decided by
+**redundancy rather than throughput**:
+
+| Tier | Replicas | Why |
+|---|---|---|
+| Embeddings | 2 | Not for capacity. If retrieval stops, every document feature stops. |
+| Interactive | 2 | So a node can be rebooted during working hours. |
+| Heavy | 0–1, on demand | Loaded when asked for, stopped when idle. |
+
+Then measure rather than guess:
+
+```
+llmgw ctl bench <model>
+```
+
+It climbs concurrency until the SLO breaks and reports the last level that met
+it. Peak throughput arrives long after latency has become unusable, so
+throughput alone overstates what the hardware can serve.
+
+## Where the weights live
+
+The single highest-value piece of infrastructure here is **a local mirror**: one
+internal HTTP server holding the model files. [deploy/mirror/](../deploy/mirror/)
+has the nginx config and the directory layout. Hugging Face is slow, rate
+limited, and blocked outright on plenty of corporate networks. Eight nodes each
+pulling forty gigabytes from the internet is a day; from a mirror on the same
+switch it is minutes. Point a model's `source` at it and llmgw fetches from
+there.
+
+**Pin the version.** Put it in the path — `/models/qwen2.5-14b/2026-03/q4_k_m.gguf`
+— so a repository that changes upstream cannot change what you are running.
+Without this, a prompt that worked last week gives a different answer this week
+and nobody can explain why.
+
+**Quantisation.** For llama.cpp, `q4_k_m` is the practical default: the quality
+difference from `q8_0` is smaller than most people expect and the memory
+difference is a factor of two. For vLLM on modern cards, FP8 or AWQ. Run
+`llmgw ctl plan <model>` to see whether a given precision fits before
+downloading anything.
+
+**Disk.** Budget three to five times what you first estimate. Several
+quantisations, several versions, and partial downloads all accumulate.
+`llmgw ctl nodes` shows free space per node once `model_dirs` is configured,
+and `llmgw ctl weights` reclaims files llmgw downloaded and no model needs —
+never files you placed yourself.
+
+Under ten nodes, let each keep its own copy; it is simpler and the disk is
+cheap. Above that, consider a shared filesystem — llmgw notices one and will
+not count the same free terabyte once per node.
+
+## Before anyone starts using it
+
+Set budgets and limits on day one, not later:
+
+```
+llmgw keys limits --scope project --id <project> --rpm 60 --budget 50
+```
+
+The reason is not technical. A resource that appears free and unlimited becomes,
+three months later, a cost nobody can account for — and introducing limits at
+that point is a much harder conversation than having had them from the start.

docs/clients.md

@@ -0,0 +1,633 @@
+# Using llmgw from code
+
+Written for a developer whose program talks to a model through llmgw. There
+is no llmgw SDK, and there will not be one: the gateway speaks OpenAI's API
+and Anthropic's Messages API, so the official SDKs for both work as they are.
+Only two things change — the base URL and the key. Everything llmgw adds on
+top is an HTTP header, which every one of those SDKs lets you set.
+
+The examples use `https://llm.example.com` for the gateway; use the address
+your operator gave you, or the one on the gateway's own front page. Every
+example reads the key from `LLMGW_API_KEY`. `<model-name>` is a model this
+gateway serves: `GET /v1/models` lists the ones your key may use, and sending
+the placeholder unchanged is answered with that list rather than with an
+error.
+
+## Getting a key
+
+Keys are made on the gateway's **Account** page after signing in, or issued
+by an operator. A key is shown once and never again — only its hash is kept —
+so put it in a password manager straight away. `GET /me` with the key says
+what it may do and what it has spent.
+
+## The base URL and the key
+
+| SDK | Base URL | Key |
+|---|---|---|
+| OpenAI (any language) | `https://llm.example.com/v1` | `Authorization: Bearer …`, as the SDK sends it |
+| Anthropic (any language) | `https://llm.example.com` — the SDK adds `/v1/messages` | `x-api-key: …`, as the SDK sends it |
+
+Both SDKs also read their usual environment variables, so a program that
+already uses them needs no change at all:
+
+```
+export OPENAI_BASE_URL=https://llm.example.com/v1
+export OPENAI_API_KEY=$LLMGW_API_KEY
+
+export ANTHROPIC_BASE_URL=https://llm.example.com
+export ANTHROPIC_API_KEY=$LLMGW_API_KEY
+```
+
+### The API described
+
+Every endpoint is described in OpenAPI 3.1 at `/v1/openapi.json`. It needs
+no key, so a client generator can be pointed at it. `/docs/api` shows it in
+Swagger UI, where *Authorize* takes a key and *Try it out* sends a request to
+the gateway. People with a part in running the gateway also find the admin
+API's document there.
+
+## A first request
+
+### curl
+
+```
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>",
+       "messages": [{"role": "user", "content": "Say hello in Turkish."}]}'
+```
+
+### Python
+
+```
+pip install openai
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(base_url="https://llm.example.com/v1",
+                api_key=os.environ["LLMGW_API_KEY"])
+
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Say hello in Turkish."}],
+)
+print(reply.choices[0].message.content)
+```
+
+### TypeScript
+
+```
+npm install openai
+```
+
+```typescript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "https://llm.example.com/v1",
+  apiKey: process.env.LLMGW_API_KEY,
+});
+
+const reply = await client.chat.completions.create({
+  model: "<model-name>",
+  messages: [{ role: "user", content: "Say hello in Turkish." }],
+});
+console.log(reply.choices[0].message.content);
+```
+
+### Go
+
+```
+go get github.com/openai/openai-go/v3
+```
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/openai/openai-go/v3"
+	"github.com/openai/openai-go/v3/option"
+)
+
+func main() {
+	client := openai.NewClient(
+		option.WithBaseURL("https://llm.example.com/v1/"),
+		option.WithAPIKey(os.Getenv("LLMGW_API_KEY")),
+	)
+	reply, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
+		Model:    "<model-name>",
+		Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Say hello in Turkish.")},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(reply.Choices[0].Message.Content)
+}
+```
+
+The import path carries the SDK's major version; use the one your module
+already has.
+
+## Streaming
+
+Set `stream` and read the chunks. llmgw may send a last chunk that carries
+only the token counts and no choices, so check for a choice before reading
+one — the OpenAI API does the same when usage is asked for.
+
+```python
+stream = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Count to ten."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices and chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+print()
+```
+
+```typescript
+const stream = await client.chat.completions.create({
+  model: "<model-name>",
+  messages: [{ role: "user", content: "Count to ten." }],
+  stream: true,
+});
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+```
+
+```go
+stream := client.Chat.Completions.NewStreaming(ctx, openai.ChatCompletionNewParams{
+	Model:    "<model-name>",
+	Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Count to ten.")},
+})
+for stream.Next() {
+	chunk := stream.Current()
+	if len(chunk.Choices) > 0 {
+		fmt.Print(chunk.Choices[0].Delta.Content)
+	}
+}
+if err := stream.Err(); err != nil {
+	log.Fatal(err)
+}
+```
+
+With curl, add `"stream": true` to the body and `-N` so curl prints the
+events as they come.
+
+## Tools
+
+Function calling is OpenAI's: describe the tools, run the ones the model
+asks for, send the results back. Whether a model calls tools well is the
+model's business, not the gateway's; ask your operator which of the served
+models are set up for it.
+
+**Editors' agents need such a model.** Continue's Agent mode, Cline and
+Codex act only through tool calls: with a model whose calls come back as
+text — `<tool_call>{...}` or a JSON block in the answer, `tool_calls` empty —
+they chat but never read a file or run a command. Qwen2.5-Coder is one;
+Qwen3-Coder is not. The configuration the portal writes for Continue says
+`tool_use` only for a model whose catalog entry says tools, and gives
+Continue the model's context and longest answer, so it never sends a request
+the gateway refuses.
+
+```python
+import json
+
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "The current weather in a city.",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+}]
+
+messages = [{"role": "user", "content": "Is it raining in Ankara?"}]
+reply = client.chat.completions.create(model="<model-name>", messages=messages, tools=tools)
+msg = reply.choices[0].message
+
+if msg.tool_calls:
+    messages.append(msg)
+    for call in msg.tool_calls:
+        args = json.loads(call.function.arguments)
+        result = {"city": args["city"], "raining": False}  # your code here
+        messages.append({"role": "tool", "tool_call_id": call.id,
+                         "content": json.dumps(result)})
+    reply = client.chat.completions.create(model="<model-name>", messages=messages, tools=tools)
+
+print(reply.choices[0].message.content)
+```
+
+## Embeddings
+
+```python
+result = client.embeddings.create(
+    model="<embedding-model>",
+    input=["llmgw routes requests", "to GPUs it can reach"],
+)
+vectors = [d.embedding for d in result.data]
+```
+
+```typescript
+const result = await client.embeddings.create({
+  model: "<embedding-model>",
+  input: ["llmgw routes requests", "to GPUs it can reach"],
+});
+const vectors = result.data.map((d) => d.embedding);
+```
+
+An embedding model is a model of its own; a chat model does not answer
+`/v1/embeddings`.
+
+## The Responses API
+
+`/v1/responses` is served too, for clients that speak nothing else (Codex
+among them). llmgw translates it to chat completions, so it works with every
+model the gateway serves; what has no equivalent there — OpenAI's hosted
+tools, reasoning summaries — is ignored rather than refused.
+
+```python
+response = client.responses.create(
+    model="<model-name>",
+    instructions="Answer in one sentence.",
+    input="Why is the sky blue?",
+)
+print(response.output_text)
+```
+
+Streamed, the events are the Responses API's own:
+
+```python
+stream = client.responses.create(model="<model-name>", input="Count to ten.", stream=True)
+for event in stream:
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="", flush=True)
+```
+
+## Batches
+
+For work that need not finish now: OpenAI's Files and Batch APIs. A batch runs
+at the lowest priority, so it uses what interactive traffic leaves free, and
+each line is counted against the key that submitted it.
+
+```python
+import json
+
+with open("requests.jsonl", "w") as f:
+    for i, text in enumerate(["first document", "second document"]):
+        f.write(json.dumps({
+            "custom_id": f"doc-{i}",
+            "method": "POST",
+            "url": "/v1/chat/completions",
+            "body": {"model": "<model-name>",
+                     "messages": [{"role": "user", "content": "Summarise: " + text}]},
+        }) + "\n")
+
+batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
+batch = client.batches.create(
+    input_file_id=batch_file.id,
+    endpoint="/v1/chat/completions",
+    completion_window="24h",
+)
+
+# Later:
+batch = client.batches.retrieve(batch.id)
+if batch.status == "completed":
+    for line in client.files.content(batch.output_file_id).text.splitlines():
+        result = json.loads(line)
+        print(result["custom_id"], result["response"]["body"]["choices"][0]["message"]["content"])
+```
+
+## The Anthropic SDK
+
+`/v1/messages` is Anthropic's Messages API, translated to chat completions and
+back, streamed or not, with tools and images. It serves the gateway's own
+models — `model` is a model this gateway serves, not a Claude model.
+
+```
+pip install anthropic
+```
+
+```python
+import os
+import anthropic
+
+client = anthropic.Anthropic(base_url="https://llm.example.com",
+                             api_key=os.environ["LLMGW_API_KEY"])
+
+message = client.messages.create(
+    model="<model-name>",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Say hello in Turkish."}],
+)
+print(message.content[0].text)
+
+with client.messages.stream(
+    model="<model-name>",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Count to ten."}],
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic({
+  baseURL: "https://llm.example.com",
+  apiKey: process.env.LLMGW_API_KEY,
+});
+
+const message = await client.messages.create({
+  model: "<model-name>",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Say hello in Turkish." }],
+});
+for (const block of message.content) {
+  if (block.type === "text") console.log(block.text);
+}
+```
+
+```go
+client := anthropic.NewClient(
+	option.WithBaseURL("https://llm.example.com/"),
+	option.WithAPIKey(os.Getenv("LLMGW_API_KEY")),
+)
+message, err := client.Messages.New(ctx, anthropic.MessageNewParams{
+	Model:     "<model-name>",
+	MaxTokens: 1024,
+	Messages: []anthropic.MessageParam{
+		anthropic.NewUserMessage(anthropic.NewTextBlock("Say hello in Turkish.")),
+	},
+})
+if err != nil {
+	log.Fatal(err)
+}
+for _, block := range message.Content {
+	if text, ok := block.AsAny().(anthropic.TextBlock); ok {
+		fmt.Println(text.Text)
+	}
+}
+```
+
+(`github.com/anthropics/anthropic-sdk-go` and its `option` package.)
+
+With curl:
+
+```
+curl https://llm.example.com/v1/messages \
+  -H "x-api-key: $LLMGW_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "max_tokens": 1024,
+       "messages": [{"role": "user", "content": "Say hello in Turkish."}]}'
+```
+
+## What llmgw adds
+
+Each is a header, so a request stays exactly what the SDK would send anywhere
+else. Set one for every request on the client, or for one request:
+
+| | Every request | One request |
+|---|---|---|
+| Python (both SDKs) | `OpenAI(..., default_headers={...})` | `create(..., extra_headers={...})` |
+| TypeScript (both SDKs) | `new OpenAI({ ..., defaultHeaders: {...} })` | `create({...}, { headers: {...} })` |
+| Go (both SDKs) | `openai.NewClient(..., option.WithHeader(k, v))` | `New(ctx, params, option.WithHeader(k, v))` |
+| curl | | `-H "k: v"` |
+
+### Stored conversations: `x-llmgw-thread`
+
+Send the same thread id with each request and only the new turn; llmgw puts
+the stored conversation in front of it. The conversation continues on
+whichever model serves the next turn, even a different one. It must be
+turned on for your project by an operator (`llmgw keys threads`); a request
+that names a thread on a gateway that keeps none is refused rather than
+answered without its history.
+
+```python
+import uuid
+
+thread = str(uuid.uuid4())  # anyone in your project who knows it reads it
+for turn in ["My name is Deniz.", "What is my name?"]:
+    reply = client.chat.completions.create(
+        model="<model-name>",
+        messages=[{"role": "user", "content": turn}],
+        extra_headers={"x-llmgw-thread": thread},
+    )
+    print(reply.choices[0].message.content)
+```
+
+A thread belongs to the project, not to the key, so use an id nobody can
+guess: at most 128 letters, digits and `- _ . :`. When the conversation no
+longer fits the model, the oldest turns are left out and the reply carries
+`x-llmgw-thread-trimmed` with how many. `DELETE /v1/threads/{id}` forgets one:
+
+```
+curl -X DELETE https://llm.example.com/v1/threads/$THREAD \
+  -H "Authorization: Bearer $LLMGW_API_KEY"
+```
+
+### Sessions: `x-session-id`
+
+Requests with the same session id go to the same replica while it is
+healthy, so a conversation that resends its history finds it already in that
+replica's cache and answers sooner. Without the header, the body's `user`
+field is used. Nothing is stored; it is only a routing hint.
+
+```python
+client = OpenAI(base_url="https://llm.example.com/v1", api_key=os.environ["LLMGW_API_KEY"],
+                default_headers={"x-session-id": "chat-7f3a"})
+```
+
+### Tags and metadata
+
+Requests can be labelled so the usage they record can be told apart — by
+feature, by customer, by job. Send OpenAI's own `metadata`, string keys to
+string values, or the same as the `x-llmgw-tags` header for a client that
+cannot set `metadata`; the `user` field is recorded too. Which tags also
+become metric labels is the operator's choice (`router.tag_labels`).
+
+```python
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Classify this ticket."}],
+    metadata={"feature": "triage", "customer": "acme"},
+    user="user-1234",
+)
+```
+
+```
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "x-llmgw-tags: feature=triage,customer=acme" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "messages": [{"role": "user", "content": "Classify this ticket."}]}'
+```
+
+### Canaries: `x-llmgw-variant`
+
+While an operator tries a model's newer weights on a share of its traffic, a
+session stays on one side. `x-llmgw-variant: canary` sends a request to the
+canary deliberately — to try it before it is promoted, or to compare the two.
+
+```python
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "hello"}],
+    extra_headers={"x-llmgw-variant": "canary"},
+)
+```
+
+### Memory notes: `/v1/memory`
+
+Notes an agent keeps for itself across conversations: a key, some text, and
+optional tags, private to your project and to the agent named in
+`x-llmgw-agent` (`default` when it is not sent). An operator turns them on for
+a project (`llmgw keys memory`). They are plain REST, so any HTTP client
+will do:
+
+```
+H="Authorization: Bearer $LLMGW_API_KEY"
+
+curl -X PUT https://llm.example.com/v1/memory/favourite-colour -H "$H" \
+  -H "x-llmgw-agent: helper" -H "Content-Type: application/json" \
+  -d '{"text": "The user likes dark green.", "tags": ["preference"]}'
+
+curl "https://llm.example.com/v1/memory?q=green" -H "$H" -H "x-llmgw-agent: helper"
+curl "https://llm.example.com/v1/memory?tag=preference" -H "$H" -H "x-llmgw-agent: helper"
+curl https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper"
+curl -X DELETE https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper"
+```
+
+A key is up to 200 bytes, a note up to 16 KiB, with at most 16 tags of
+lowercase letters, digits, `-` and `_`, and 1000 notes per agent.
+
+### MCP: `/mcp`
+
+The same notes as tools an agent can be given — `remember`, `recall` and
+`forget` — from an MCP server at `https://llm.example.com/mcp` (the HTTP
+transport, answered as plain JSON). Add it to your agent's MCP servers with
+the key as a bearer token and, if you want notes kept apart, `x-llmgw-agent`.
+llmgw does not put these tools into requests by itself: an agent that is not
+given the server never sees its notes.
+
+```
+curl https://llm.example.com/mcp \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
+```
+
+**Pictures, 3D models, vision and workflows.** Where the gateway has the
+models for them, the same server offers more tools — only those it has a
+model for:
+
+| Tool | Does |
+|---|---|
+| `generate_image` | A picture from a prompt. `style` adds what a picture for a mesh wants: `concept` (one object, three-quarter view, grey background), `side` (an exact side view), `texture` (a seamless tile) or `none`. Answers the PNG's `file_id`, `url` and `seed`, with a 512 px preview to look at. |
+| `generate_mesh` | A GLB from a picture — `image` is a `file-…` id (a `generate_image` result, say), a data URL or base64 — or from a `prompt`, for which a concept picture is made first. `seed`, `resolution`, `texture_resolution`, and any other input the model's workflow declares in `inputs`. Answers the GLB's `file_id`, `url` and licence. |
+| `review_images` | Asks a vision model about one to four pictures (each shrunk to 1280 px on its long side); `json_schema` makes it answer that JSON. |
+| `run_workflow` | Runs a ComfyUI workflow from the inputs its catalog entry declares, and answers its result file. |
+| `job_status` | Where a mesh or a workflow run stands, and its file when done; `wait_seconds` waits for it. |
+| `gateway_status` | The picture, 3D, vision and workflow models, whether each is loaded on a GPU now, a workflow's inputs, and your last jobs. |
+
+Each tool makes its request of the gateway under your key, so your
+allowlist, limits, left-out licences and budget apply, and it is charged
+and listed like any other request. What it makes is kept as your file for
+as long as job results are: fetch it from `url` with the same key (`curl -H
+"Authorization: Bearer $LLMGW_API_KEY" -o rock.glb <url>`). A tool server
+over HTTP cannot write to your disk, so an agent that needs the file
+locally — to import it in Blender — fetches it, or goes through a small
+local bridge that does.
+
+A picture can be uploaded once and named by its id after: `POST /v1/files`
+with `purpose=vision` (or `user_data`) keeps it, for as long as job results
+are kept, as a file of yours that `generate_mesh`, `review_images` and a
+workflow's file inputs take as `file-…`. A call is at most 64 MB.
+
+A model that is not loaded is waited for: a picture or a look at one whose
+model is starting, or waiting for another to give up the GPU, waits as a
+mesh does, saying so, rather than failing with "model loading".
+
+A mesh takes from half a minute to a few minutes. A client that takes the
+answer as a stream (`Accept: text/event-stream`, as Claude Code does) is
+answered that way: `notifications/progress` for the call's
+`progressToken` while it runs — queued, waiting for the GPU, the node and
+its percent — then the result, and the call waits up to ten minutes. One
+answered in one piece waits 50 seconds; a job not done by then is answered
+with its `job_id`, to ask after with `job_status`. `wait_seconds` (up to
+900) sets either.
+
+```
+claude mcp add --transport http llmgw https://llm.example.com/mcp \
+  --header "Authorization: Bearer $LLMGW_API_KEY"
+```
+
+**Your company's tools.** Where an administrator has registered the
+company's own MCP servers (Jira, a file server, a database) and your key is
+granted their tools, the same `/mcp` lists them too, each as `server.tool`
+(`jira.search`). Give your agent only llmgw's `/mcp` and your key: the
+servers' own credentials stay with llmgw. A tool your key is not granted is
+not listed, and calling it by name is refused. Each call is in the audit
+log under your key: which tool, the size of what was sent, how it ended and
+how long it took, never what it said.
+
+### Licences you leave out
+
+A model's licence is in `/v1/models` (`license`: its `id`, `name`, whether
+it allows commercial use and the regions it grants nothing in). On your
+profile page, under **Licences**, you can leave licences out: one by one,
+every licence that forbids commercial use, or every licence that grants
+nothing in a region you name (`EU` for the union). The rules cover models
+added later too. From then on those models are not listed to your keys and
+a request for one is refused with 403 and the code `licence_excluded`,
+naming the choice that left it out — on every key you own and on the
+portal's pages, whatever a key's own allowlist says. A change reaches keys
+already in use within a minute.
+
+### Headers llmgw sends back
+
+| Header | Says |
+|---|---|
+| `x-request-id` | The request's id in the gateway's logs and usage records — quote it when asking an operator about a request. |
+| `x-llmgw-served-model` | The model that answered, when it was not the one asked for: a spent budget can move a request to a cheaper model. |
+| `x-llmgw-queue-ms` | How long the request waited for room before it was sent. |
+| `x-llmgw-thread-trimmed` | How many stored turns were left out to fit the model. |
+
+## When something is refused
+
+Errors come back in the shape of the API that was called — OpenAI's
+`{"error": {"message": …, "type": …}}` or Anthropic's — so each SDK raises
+its usual exception with the gateway's message in it. The ones worth knowing:
+
+| Status | Usually means |
+|---|---|
+| 400 | Besides a malformed request: a prompt too long for the model, or a guardrail policy refused it (the code `content_policy_violation`). |
+| 401 | No key, a mistyped one, or one that was revoked or has expired. |
+| 403 | The key may not use that model; with the code `licence_excluded`, its licence is one you left out on your profile page. |
+| 429 | A rate limit or budget of the key, its project or its team was reached. `Retry-After` says when to try again, and is absent when waiting will not help — a spent monthly budget. |
+| 503 | No model of that name is served (the message lists the ones that are), the model is still loading, or every replica is busy and the queue is full. The SDKs retry by themselves; a name that is not served will not start to be. |
+| 504 | Every replica was busy for as long as the key's band may wait. `Retry-After` says when to send it again. |
+
+## Priority
+
+With keys on, the key decides the request's priority band and routing
+profile, set by an operator; the `x-llmgw-band` and `x-llmgw-profile` headers
+are ignored, so a client cannot promote itself. On a gateway without keys
+they are read from the request.

docs/console.md

@@ -0,0 +1,406 @@
+# The console
+
+`sudo llmgw`, with nothing after it, on a machine llmgw runs on. On a machine
+with nothing installed it opens the setup screens; on a control plane, the
+console described here; on a node, the node's own console, which shows
+what runs on that machine and edits `agent.yaml`. Everything on these screens can also be done by command — each
+screen says which — so a script never needs them and a person never needs
+to remember the commands.
+
+The keyboard drives it; there is no mouse. **?** opens this page from
+anywhere, and the **Manual** entry holds every other page, as `llmgw docs`
+does without the console.
+
+## The layout
+
+A bar across the top names the machine. Down the left, the entries, in four
+groups: **Watch**, **People**, **Help**, **Settings** and **Do**. The panel on
+the right shows the entry chosen. The bottom line always says which keys do
+what at that moment, and a question or a result opens as a dialog over the
+panel.
+
+| Key | Does |
+|---|---|
+| ↑ ↓ | Choose an entry, or a row in the panel |
+| → or Enter | Go into the panel |
+| Enter on a row | What can be done to it: its details first, then the rest |
+| ← or Esc | Back out: from a page to its list, from the panel to the entries |
+| A | Add one, on a view that holds things: a quota, an account, a key |
+| PgUp PgDn | Scroll a long panel |
+| ? | This page |
+| Q | Leave; the cluster keeps running |
+| Ctrl-C | Leave at once |
+
+What is watched is read again every three seconds.
+
+## Forms and questions
+
+A change that needs values opens a form, filled in with what is set now. Tab
+or ↓ moves to the next field, ← → changes a choice, and Enter on **Apply**
+sends it; a form of one field is sent by Enter on it. A mistake the form can
+see — a maximum below the minimum, a word where a number goes — is said in the
+form and nothing is sent. One the control plane refuses comes back as a dialog
+with its reason, word for word.
+
+Anything that cannot be undone — removing, draining, deleting, revoking —
+asks first, and only **Y** goes ahead.
+
+Serving a model and moving one to new weights are jobs on the control plane:
+started from here, they run there in the background whatever this screen
+does, and the console is free at once. **Jobs** follows them. Upgrading the
+cluster, a backup and adding a node change this machine or another over ssh;
+those close the screen and run in the terminal, so their output is there to
+read, and Enter brings the console back.
+
+## Setting up
+
+On a machine with nothing installed, the control plane is set up from one
+form (`sudo llmgw server init`): the administrator's email, other names nodes
+reach the machine by, and ticks for PostgreSQL, the model mirror, this machine
+as a node, the starter model and the guardrails' judge. **Offline bundle**
+and **Its sha256** are for a site with no internet: the path of a bundle made
+by `llmgw bundle create`, and the sha256 it printed. Given, the bundle goes
+into the mirror, every file checked, and the cluster is set up to fetch
+nothing from outside (install.md, "Offline sites"). A bundle with no sha256,
+or with the mirror unticked, is said in the form and nothing starts.
+
+## Watch
+
+**Overview** is `llmgw ctl status`: nodes, GPUs by class, fabrics, replicas,
+models, the store's members, and anything parked, unplaced or idle. With no
+webhook in the cluster's settings it says the alerts go nowhere.
+
+**Monitor** draws the cluster the way btop draws a machine: CPU, memory,
+GPU busy and GPU memory, requests and tokens a second, time to first token,
+requests in flight and queued, network and disk — Braille charts, filled
+and coloured green to red by height — over 5 minutes, an hour, a day or a
+week (**1**–**4**, or **R** for the next). Below them each node's CPU,
+memory and network now and as a sparkline, each card's busy, memory, heat
+and power, and each model's requests a second. The history comes from the
+Prometheus named by `monitoring.prometheus` in server.yaml; without one the
+charts draw what this console has seen since it opened, and say so. Network
+and disk come from each machine's node exporter, which `llmgw node add`
+installs. **N** sends a test notification to each webhook in server.yaml's
+`notify` section and says how each answered (`llmgw ctl notify test`). A node's and a model's own pages have their charts too, over the
+same range.
+
+**Nodes** lists every node with its state, where it is (its rack, or row,
+room or site, and PDUs), load, GPUs, replicas, disk and agent version. A node
+in a held rack reads *ready, held*. On a row:
+
+- **Details** — its address, location and any hold, system, load, engines and
+  GPUs, and any warning.
+- **Cordon** places nothing new on it; **Uncordon** undoes it.
+- **Location…** sets its site, room, row, rack and PDUs (the `llmgw.io/`
+  labels), which placement spreads replicas across.
+- **Hold rack …** places nothing new in the node's rack, and can drain it;
+  **Release …** on a node in a held domain undoes it. See
+  [facility-aware-placement.md](facility-aware-placement.md).
+- **Drain** moves its replicas off one at a time, each replacement up before
+  the original stops.
+- **vllm build / sglang build** (nodes with GPUs) — which build of the engine
+  the node installs: `auto` follows its hardware, `none` installs none.
+- **Upgrade its agent** to a release; its engines keep serving.
+- **Delete model files nothing uses** frees the node's disk.
+- **Remove from the cluster** — the control plane forgets it; the machine is
+  not touched.
+
+**GPUs** is every card: how busy, its memory, temperature, power, and the
+model holding it.
+
+**Models** lists the catalog: ready against wanted, status, class, profiles,
+and **UPDATE** when the registry has new weights for it. On a row:
+
+- **Details** — description, replicas, class, owner, profiles, source, where
+  its weights came from, what it reserves against what it uses, and its
+  replicas.
+- **Replicas (scale)** — the minimum kept running, the most it scales to,
+  and for a model loaded on demand how long it may sit unused. A maximum of
+  0 stops it.
+- **Class** — critical, standard or opportunistic: whose capacity gives way
+  when there is not enough for everyone.
+- **Owner** — the organization, team or project whose capacity quota it
+  counts against.
+- **Resources** — the memory and cores one replica reserves on its node.
+- **LoRA adapters** — `name=source[@scale]`, separated by commas.
+- **Restart its replicas**, one by one or in place.
+- **Update to …** — when the repository it came from has published different
+  weights for its files: they are fetched into the mirror beside the ones in
+  use, checked, swapped in, and the replicas replaced one at a time.
+  **Go back to …** returns to the weights the update replaced.
+  **Ask the registry for new weights now** checks without waiting for the
+  next scheduled look (`mirror.update_check`, six hours by default).
+- **Try the new weights as a canary…** — instead of swapping them in, runs
+  them beside the model as `MODEL-canary`, one replica, given the share of
+  its requests you choose. With a canary running the menu has **Canary's
+  share…**, **Promote the canary…** (the model moves to its weights, the
+  canary is removed) and **Take the canary out…**. A canary that errs or
+  answers more slowly than the model is taken out by itself. The MODEL
+  column shows `(10% to canary)` and `(canary of …)`.
+- **Ask it a quality suite…** — one of the suites the control plane has (in
+  `control.eval_dir`, or built in: `arithmetic`, `json-format`), asked
+  through the router; the dialog counts the answers as they come in, then
+  shows the score, each case and the model's last runs. Esc stops watching;
+  the run carries on and is kept. **Its quality runs** lists them, as
+  `llmgw ctl eval --history` does.
+- **Hold its updates to a quality suite…** — the suite and score its new
+  weights must reach before an update or a promotion moves it to them
+  (`llmgw ctl model gate`); **none** takes it away. With one set, **Update
+  to …** and **Promote the canary…** say so.
+- **Why is it placed where it is** — `llmgw ctl explain-placement`.
+- **Try again**, for a model parked after failing every start.
+- **Remove** — its replicas stop and it leaves the catalog. A model from
+  `server.yaml` is changed there instead; the console says so.
+
+**A** on Models adds one from a definition file on this machine: the YAML a
+model takes in `server.yaml`.
+
+**Replicas** lists every replica; on one, **Restart it**, replaced or in
+place.
+
+**Usage** is the last 24 hours by team, project or organization (→ changes
+which): requests, tokens, errors and spend.
+
+**Quotas** are capacity quotas: the GPUs, cores and memory each organization,
+team or project is guaranteed and may at most hold, and what it holds now.
+**A** adds one; on a row, change or remove it.
+
+**Knowledge** lists the knowledge-base collections: each one's owner, the
+model that embeds it, how many documents and chunks it holds and who else it
+is granted to. **A** makes one. On a row: its **Documents**, **Grant…** a
+project, team, organization, person or key read or write access, **Revoke**
+a grant, **Answer from it by default…** for a part of the tree, **Try a
+search…** as an administrator, or **Delete…** it. People
+fill collections from their own machines with `llmgw-kb`
+([knowledge.md](knowledge.md)). Off on a SQLite store, and says why.
+
+**MCP servers** lists the company's own MCP servers that agents reach through
+the gateway's `/mcp`, their tools named `server.tool`: whether each is on,
+who has been granted its tools, its rate per caller, the names of the
+credentials it is sent (never their values) and its address. **A** adds one:
+its name, which is its tools' prefix, its address, and a bearer token or
+another header, kept sealed in the store. On a row: **Test, and list its
+tools**, with its credential, as a call would; **Grant its tools to…** a
+team, project, organization, person or key — all of them, `jira.*`, or some
+by name — beside whatever else that level is granted, and saying when a
+level above keeps them out of reach; **Revoke** a grant;
+**Change…** its address, timeout or rate; **Replace its credential…**;
+**Turn off** (its tools are listed nowhere and every call refused) or on;
+**Remove…**. A server's tools are seen nowhere until granted. The screen
+also says how a person points an agent at the gateway, with a key of their
+own from `/profile/keys`. `llmgw ctl mcp` does the same from a shell, and
+the web page **MCP servers** (`/admin/mcp`, administrators only) in a browser.
+
+**Mirror** is what the model mirror holds, one row for each version of each
+model — a file, or the set of files a model of several is: shards, a vision
+projector, a config and tokenizer — with how far its download has got and
+which models use it. **A** downloads a URL into it; **I** imports a model
+from an Ollama on this machine into a mirror directory on this machine — the
+mirror beside the control plane — and shows the model definition to add for
+it (a mirror elsewhere: `llmgw mirror import-ollama` there); on a row, its files with
+their checksums and where each was fetched from, the source a model
+definition names for it, or remove it — with a warning when a model still
+uses it.
+
+**Jobs** lists the models being served or updated since the control plane
+started: what each is doing now — the download's progress, a replica
+starting — and whether it ended done, failed, or waiting for room on busy
+cards. The entry shows how many are running. Enter on one shows its steps.
+`llmgw ctl jobs` is the same, and `llmgw ctl jobs ID` follows one.
+
+**Slurm** is the Slurm cluster run beside llmgw, when there is one: its
+controller and whether slurmctld runs, and each node that runs slurmd —
+whose it is now (llmgw's, Slurm's, or on its way between them), its state in
+Slurm, the jobs running there. On a row, **Lend to Slurm…** moves the node's
+replicas off and then lets Slurm run jobs there; **Take back from Slurm…**
+starts no new job there and gives it back to llmgw when its jobs have ended.
+Both change `slurm.lent` in the cluster's settings, as `llmgw ctl slurm lend`
+and `reclaim` do. Turning Slurm on and choosing its nodes is `llmgw ctl slurm
+setup`, or the Slurm part of the first install. Above the nodes it says where
+the shared files come from and how many users llmgw made; the SHARED column
+is each node's (mounted, exported, missing). `llmgw ctl slurm shared` and
+`llmgw ctl slurm users` change them.
+
+**Logs** shows a node's agent log, newest at the bottom, errors and warnings
+coloured.
+
+## People
+
+The accounts, keys and organizations live in the store; these views read it
+and change it with the same commands as `llmgw users`, `llmgw keys` and
+`llmgw org`, so their checks and messages are the ones shown.
+
+**Accounts** — who has signed up, their state, whether they see the cluster
+dashboard, and what they belong to. **A** creates an account, already
+approved. On a row: approve one waiting, suspend or reinstate, give or take
+the cluster dashboard, add to or take out of an organization, team or
+project (on an organization as a member, its manager, who sees its page, or
+its admin, who also changes it), their limits, a new password (their sessions close), delete, and
+**Forget them…** for a request to be forgotten (`llmgw users forget`).
+
+**API keys** — every key, its project, owner, state and last use. **A**
+issues one; the key is shown once, in the result, and never again. On a row:
+its limits, **Rotate…** — a new key with the same project, owner and limits,
+the old one working on for the overlap you give (`llmgw keys rotate`) — or
+revoke it.
+
+**Accounts** rows also have **Staff role…**:
+- `viewer` looks at every page under /admin and changes nothing;
+- `operator` also runs the cluster from them (models through the mirror, a
+  node's engines);
+- `billing` sees usage and quotas;
+- `admin` may do anything.
+
+The STAFF column shows each person's role.
+
+On **Usage**, **E** exports usage as CSV to a file on the control plane:
+by hour, day or month and any of organization, team, project, user, key and
+model.
+
+**Audit** lists every change of the last week — through `ctl`, this console
+or the /admin pages, and people's own keys and passwords — with who made
+it, through what, and how it ended. Enter shows the fields it was given,
+with anything secret taken out. `llmgw ctl audit` is the same, with filters.
+
+**Organizations** — the tenancy tree: organizations, their teams, the teams'
+projects, with members, keys and limits. **A** adds an organization. On a
+row: add a team or project inside it, rename, move, limits for the level and
+for each of its members, its capacity quota, and for a project how long
+conversations and agent notes are kept, and whether its requests are
+(**Keep requests…**: for how long, and what share), and whether they stay in
+the cluster (**Requests stay in the cluster…**: never an outside provider),
+and whether the same request is answered again from memory (**Cache
+answers…**: for how long, and whether only reproducible answers or any). **Longest key lifetime…** caps how
+long a key made there may live, and is the expiry of one made without any
+(`llmgw keys ttl`; `auth.max_key_ttl` in server.yaml caps every key).
+**Remove** takes away only something empty.
+
+Limits are requests and tokens a minute, a budget per day or month, and the
+models allowed. Each level only narrows what is above it.
+
+**Sign-in** — how people get in besides a password kept here: single
+sign-on, Active Directory and provisioning, each on or off, with the
+directory's last sync (how many people, accounts kept in step, suspended,
+reinstated).
+- **E** sets up Entra ID. Give the tenant ID, the client ID and secret,
+  and the groups for administrators and operators. A provider other than
+  Entra takes its issuer URL in place of the tenant. The form shows the
+  redirect address to register.
+- **D** sets up Active Directory: the servers, where people are, the
+  service account and its password, the domain's CA certificate as a PEM
+  file on this machine, the group whose members may sign in, and groups
+  for roles and teams.
+- Before it is kept, the directory is tried from the control plane: each
+  server reached and bound, how many people may sign in, how many are in
+  each group. If any step fails, nothing is kept and the steps are shown.
+  **T** tries the settings in force.
+- On the provisioning row, Enter makes a SCIM token, shown once.
+- The password, the client secret and the token are kept in the store,
+  sealed by the master key when one is set. The settings name them as
+  `store:auth/…`, so each control plane has them with no file put on it.
+  The CA is written into the settings themselves.
+
+**Guardrails…** on a row lists the guardrail policies server.yaml defines.
+Each policy is marked in one of three ways:
+
+- attached here (✓): Enter detaches it;
+- applying from above (·): from everywhere, or from the organization or
+  team named;
+- neither: Enter attaches it.
+
+The **GUARDRAILS** column names those attached to the row itself. Policies
+narrow like limits; see [guardrails.md](guardrails.md).
+
+## Help
+
+**Manual** lists every page there is: these, the installation and operation
+guides, the configuration reference, a page for every command, the README
+and the changes in each release. On a page:
+
+| Key | Does |
+|---|---|
+| ↑ ↓, PgUp PgDn, Space | Scroll |
+| g, G | The top, the end |
+| T | Contents: the page's headings, Enter goes to one |
+| / | Find; the lines holding it are marked |
+| n, N | The next match, the one before |
+| [ ] | The topic before, the one after |
+| ← | Back to the list |
+
+`llmgw docs` opens the same manual outside the console, on any machine,
+installed or not; `llmgw docs install` opens one page; piped, it prints the
+page's text.
+
+## Settings
+
+**server.yaml** (on a node, **agent.yaml**) is every key, as a tree of menus
+built from the configuration reference: the value set, or the one that
+applies when nothing is, its type, and what it is for. Enter changes a value
+or opens a block; on a list or map of blocks, Enter opens an entry and **D**
+removes one. **U** puts a key back to its default. **S** saves.
+
+On a control plane, the cluster's keys are read from and saved to the
+cluster's settings in the store — the same on every control plane, in force
+on all of them within seconds (`llmgw ctl config` does the same from a
+shell) — and this machine's own keys (listeners, certificates, the store's
+address) to its server.yaml, which the server notices and applies by itself.
+Either is checked before anything is kept, and the file's comments survive.
+On a node, agent.yaml is read when the agent starts, so the console offers
+to restart it.
+
+## Do
+
+- **Add a node** — installs llmgw on a machine over ssh, checks it, gives it a
+  certificate and starts its agent (`sudo llmgw node add`).
+- **Replicate the store** — moves the store onto two more machines under
+  Patroni (offered only while it is not replicated).
+- **Serve a model** — Hugging Face's models: trending, most downloaded,
+  most liked or newest (**S** changes which), or **/** to search. **F**
+  switches between GGUF files, which llama.cpp runs on the CPU or a GPU, and
+  original safetensors weights, which vLLM runs on GPUs. Enter on a
+  repository plans it against the cluster as it is, before anything is
+  fetched: the model's shape is read from one file's header, or its
+  config.json, and every file is listed with the best way it runs here — on
+  one card, on several of a node's cards, across several nodes' cards over a
+  fabric (original weights only), or on a CPU node — what each card or node
+  would hold, and whether that hardware is free now. The file that suits the
+  cluster best is first, marked ★; one that fits nowhere says so. Busy is not
+  unfit: which file is best follows the hardware the cluster has, not what it
+  is running, so a file for a card that is in use is still offered for it —
+  served, it waits for the card, or with a fallback runs elsewhere until then. Choosing a
+  file offers every way it fits, best first, and what to do when that one is
+  busy: the next best way, written as a lower-priority profile so placement
+  falls back to it, or wait. A vision model offers its projector too, fetched
+  beside it and loaded with it so the model reads images. What is chosen is
+  fetched into the mirror, checked, added to the catalog and started, and a
+  replica is asked to say hello (`llmgw ctl model serve`; the plan alone is
+  `llmgw ctl model plan`).
+  `mirror.registry` points it at another registry, for a site without the
+  internet.
+- **Upgrade the cluster** to a release: this machine, then every node in turn
+  (`sudo llmgw ctl upgrade`).
+- **Restart all replicas**, one at a time.
+- **Back up now** — the store and `/etc/llmgw` into one archive
+  (`sudo llmgw server backup`).
+- **Wipe this machine** — removes llmgw's services, configuration, state and
+  users from this machine, after listing them and asking for its name
+  (`sudo llmgw wipe`; on a node too).
+- **Leave**.
+
+## The node's console
+
+On a node, `sudo llmgw` opens on **Overview**: what this machine is doing, read
+on the machine itself, so it works without an admin token and while the control
+plane is out of reach. Refreshed every three seconds, it shows
+
+- llmgw-agent's state and since when, and the version of llmgw;
+- each control plane the agent dials, from `agent.yaml` and the list the
+  leader last sent, and whether it can be reached;
+- each GPU: how busy, its memory, its heat, and the models on it;
+- the engines running here, from the agent's own records: replica, model,
+  engine, GPUs, port, whether the process is still there, and for how long;
+- the free space where weights and engines are kept;
+- the agent's warnings and errors of the last hour.
+
+Below it, `agent.yaml` in the same settings view, and the manual. The cluster
+is watched and changed from a control plane.

docs/data.md

@@ -0,0 +1,241 @@
+# What llmgw stores, and what leaves the machine
+
+Written for the review that happens before a gateway is allowed near anyone's
+documents. It describes what the software does. Mapping that onto an
+obligation — GDPR, a sector rule, an internal policy — is work for whoever
+holds the obligation; this page exists so that work starts from facts rather
+than from a vendor's summary.
+
+Everything below is checkable in the source, and the places to look are named.
+
+## The short version
+
+By default llmgw stores **no prompt or completion text anywhere**. It stores
+who made a request, when, how many tokens, and what it cost.
+
+Two features change that, and both are off until somebody turns them on for a
+named project, and neither can be turned on without also saying for how long.
+
+Nothing on the serving path leaves the cluster — **unless the catalog has a
+model served outside it** (`external:` in a model definition): a request for
+that model, or one that falls back to it, sends its prompt to that provider.
+A guardrail policy with `no_store` refuses both for the scopes it covers.
+
+**Guardrails** read every prompt and answer they are configured for, in the
+gateway's own memory, to judge them. What they record — in the usage row and
+the log — is the action, the policy, the category and how long it took: never
+the text, the value that matched, or the placeholder map of a redaction. See
+[guardrails.md](guardrails.md).
+
+## What is stored, exactly
+
+**Usage records**, one per request: the key, the project, the model asked for,
+the model that answered, prompt and completion token counts, cost, HTTP status
+and latency. No message content. The row is in `internal/store/store.go` as
+`Usage` and there is no field for text in it. What the client chose to say
+about the request is kept with it: OpenAI's `user` field and its `metadata`
+or `x-llmgw-tags` — short strings, set by the client, for attributing spend.
+A client that puts a person's name or address there puts it in the usage
+records; the field is the client's, and so is that choice. Tags are not sent
+on to the engine.
+
+**API keys**, as SHA-256 hashes. The key itself is shown once, at creation, and
+never stored — so a leaked database hands over no working credential, and
+neither llmgw nor an administrator can recover a key somebody lost. A prefix is
+kept so a key can be identified in a listing without revealing it.
+
+**The store's own secrets**, like the one engine keys are derived from, plain
+unless `secrets.master_key` seals them — with Vault's transit engine, so that
+neither the store nor its backups hold them.
+
+**People and tenancy**: accounts, the organisation/team/project tree, and the
+limits attached to it. Passwords are hashed.
+
+**Sessions** for the browser pages, as tokens.
+
+**Conversations and agent notes** — only for a project that asked. See below.
+
+**Kept requests** — only for a project that asked (`llmgw keys requests`):
+what each request sent the model, after the guardrails' redaction and with
+any stored conversation in it, and the answer the client got, for the hours
+it said, all of them or a share. Never under a `no_store` policy.
+
+**Batch files** — when a client uses the Batch API: the file of requests it
+uploaded (prompts) and the files the batch wrote (answers), in the store,
+until deleted (`DELETE /v1/files/{id}`) or, for what a batch wrote, until
+`router.batch.retain_days` (30) pass. Only keys of the project that made
+them can read them, and a project under a `no_store` policy cannot make
+them.
+
+**Reused answers** — only for a project that asked (`llmgw keys cache`):
+each answer that may be reused, as the client got it, and a hash of the
+request it answers, in the gateway process's memory — never in the store,
+never on disk — for the project's TTL or until pushed out by newer ones
+(`router.cache.max_bytes`), and gone with a restart. Never under a `no_store`
+policy. A project that reuses answers to similar questions (`--similar`)
+also has each question's last user message embedded, and the vector kept
+beside its answer, in the same memory and for as long. Forgetting a person does not reach into it; the answers age out by
+the TTL. The store keeps only the setting, and a usage record's mark that it
+was answered from the cache.
+
+## What is not stored
+
+Prompts. Completions. Anything the model was shown or produced, unless the
+project turned on conversations, notes or kept requests, or sent a batch.
+(Reused answers are held in memory only, as above.)
+
+The chat page in llmgw's own web interface keeps the conversation in a
+JavaScript variable in the browser. Refresh it and the conversation is gone,
+because it was never anywhere else.
+
+## Conversations and notes, when they are turned on
+
+Two features keep text, and both work the same way:
+
+- **Conversations** (`x-llmgw-thread`) let a client send only its new turn while
+  llmgw replays the history — including to a different model than the one the
+  conversation started on.
+- **Agent notes** (`/v1/memory`, and MCP tools) let an agent keep something for
+  itself across conversations.
+
+Both are **off for every project** until an operator runs `llmgw keys threads`
+or `llmgw keys memory` for that project by name. A request carrying a thread id
+against a project that has not is refused with an explanation, not quietly
+served without its history.
+
+Both **require a retention window**. There is no way to turn either on without
+saying how many hours, because a store with no expiry is a transcript of
+everything a team ever typed, kept forever because nobody chose a number. The
+window is measured from the last turn, so an active conversation does not
+expire underneath it, and a background sweep removes what has passed it.
+
+Both are **scoped to a project**, and the scope is part of every lookup rather
+than a check afterwards. Reading a conversation that belongs to another project
+returns the same answer as reading one that does not exist, so a leaked id
+cannot be used to discover what exists elsewhere.
+
+`DELETE /v1/threads/{id}` removes a conversation and its messages immediately.
+It is a client endpoint, not an administrative one: the person who said the
+thing can unsay it without asking somebody else to read it first.
+
+Turning retention off stops new storage, and existing conversations go at the
+next hourly sweep.
+
+## What leaves the machine
+
+**Nothing on the serving path.** A request arrives, is routed to an engine on
+your own hardware, and the answer comes back. The router talks to engines, the
+engines talk to nothing, the agents talk to the control plane. All of it is
+inside the cluster.
+
+Around the serving path, a cluster set up the ordinary way does reach out.
+None of it carries a prompt, an answer, a key or a user — it is software and
+public model files coming in — but a review should know each one:
+
+**Installing engines.** Each node's agent downloads the llama.cpp build for its
+hardware from GitHub, checked against the checksum GitHub publishes, and vLLM
+(SGLang when asked) from PyPI, with `uv` from GitHub. On every node, when it
+joins and when the engine version changes.
+
+**Releases.** `llmgw node add`, `llmgw ctl upgrade` and `llmgw upgrade` fetch
+llmgw's own release binaries from the project's release server, checked against
+its signed checksums.
+
+**Fetching weights.** When a model's `source` is a URL, the agent downloads it;
+the mirror fetches what it is asked to, from Hugging Face or another URL, and
+`server init` has it fetch the starter model and the guardrails' judge. Point
+sources at the mirror and the nodes fetch only from it — which is also the
+faster arrangement, because eight nodes pulling forty gigabytes from the
+internet is a day's work and from a local mirror it is minutes. A `source` that
+is a path on disk is never fetched.
+
+**The registry.** With a mirror configured, the control plane asks Hugging Face
+every six hours whether the models served from it have newer files
+(`mirror.update_check`), and `/admin/mirror` searches it. `llmgw ctl plan`
+reads a model's architecture from huggingface.co to work out whether it fits
+your hardware.
+
+There is no telemetry, no licence check, and no call home.
+
+### A cluster with no way out
+
+A site with no route to the internet installs from an **offline bundle**
+instead, and then nothing at all leaves the cluster (docs/install.md, "Offline
+sites"). The bundle is made on a machine that has internet — llmgw's release
+binaries with their signed checksums, the llama.cpp builds with the checksums
+GitHub publishes, the model files with the checksums Hugging Face publishes,
+each checked as it is downloaded — carried in, and imported into the mirror.
+With `offline.mirror` set in `server.yaml`, nodes install engines from the
+mirror and never from GitHub, releases come from the mirror, and the registry
+is not asked about newer weights.
+
+Verification is not weakened by any of this. A release is held to the project's
+signing key wherever it is fetched from. An engine file is held to the checksum
+recorded when the bundle was made, which the control plane keeps and hands each
+node over the agent's authenticated connection: the mirror serves plain HTTP,
+and nothing a node runs is taken on the mirror's word. The bundle itself is
+checked against the sha256 its maker printed, carried to the site apart from
+the bundle.
+
+What does not come in a bundle: vLLM and SGLang, which are Python environments
+from PyPI — an offline node serves with llama.cpp unless one is installed on it
+by hand — and the operating system's own packages (the OpenMP runtime the
+engine needs, PostgreSQL when chosen), which come from the machines' package
+sources: at an offline site, the distribution mirror it already has. Searching
+the registry from `/admin/mirror` and `llmgw ctl plan` need the internet and
+do not work offline; `mirror.registry` can point the first at an internal copy.
+
+## What the software cannot do for you
+
+**The admin port serves pprof**, and pprof can dump the process heap — where
+API keys sit in plaintext while they are being checked. Bind it to loopback and
+reach it over SSH. The default does this; a deployment that changes it should
+know why.
+
+**The store holds everything.** With conversations turned on it holds text as
+well as accounting, so where it lives, who can read it and how it is backed up
+are decisions with the same weight as the ones above. The PostgreSQL DSN
+belongs in a file readable only by the user llmgw runs as, which is why the
+configuration takes `@/path/to/file` rather than the address itself.
+
+**Model weights are yours.** llmgw reclaims only files it downloaded, and it
+identifies those by a name it generated. Anything you put on a node it will not
+touch, whatever the catalog says.
+
+## Where to look
+
+| Claim | Where |
+|---|---|
+| Usage rows carry no text | `internal/store/store.go`, type `Usage` |
+| Keys are stored hashed | `internal/store/keys.go` |
+| Conversations are off by default | `internal/store/threads.go`, `ThreadRetention` |
+| Retention is required | `llmgw keys threads --help` |
+| Scope is part of the lookup | `internal/store/threads.go`, `Thread` |
+| Deletion is a client endpoint | `internal/router/threads.go`, `handleDeleteThread` |
+| Weight fetching is the only serving-path egress | `internal/agent/weights/fetch.go` |
+
+## Forgetting a person
+
+`llmgw users forget <email> --yes` (or **Forget them…** in the console) is for
+a request to be forgotten:
+
+- their usage — every request record and every sum — is kept, so totals and
+  budgets stay true, but under a random pseudonym that links to nothing;
+- their kept requests (`keys requests`), personal files and batches, and
+  their own limits are deleted;
+- their email and id are taken out of the audit log, which keeps what was
+  done;
+- then the account goes, as `users delete` removes it: sessions ended, keys
+  revoked and left without an owner.
+
+Conversations and agent notes belong to projects, not to the people in them,
+and are not touched: a project forgets them by its retention, and a thread by
+`DELETE /v1/threads/{id}`. Backups taken before still hold everything until
+they age out; that is what their retention is for.
+
+## Keeping a project's requests in the cluster
+
+`llmgw keys residency --project <path> --in-cluster` refuses the project's
+keys any model served by an outside provider, and never uses one for them as
+a fallback or a canary: their prompts do not leave the machines the cluster
+runs on. `--anywhere` lifts it.

docs/development.md

@@ -0,0 +1,376 @@
+# Development: llmgw from source on one machine
+
+Written for a developer who wants to see llmgw answer a request on a single
+workstation, built from source, with no systemd and no `sudo` — for working on
+llmgw itself. **To install llmgw on servers, read
+[quick-install.md](quick-install.md) instead.**
+
+What you end up with: an OpenAI-compatible endpoint on `localhost:8080` in front
+of a real model served by llama.cpp.
+
+## Two ways to run
+
+Steps 1 to 4 use the simple one, **router-only**: you start the engines yourself
+and tell the router where they are with `--endpoint`. No certificates, no node
+agent.
+
+Step 5 uses the **control plane and node agent**, the same architecture as a real
+cluster on one machine: the agent starts and supervises the engine, and the
+control plane places the model.
+
+## 1. Build
+
+```
+git clone https://gitea.mynodes.xyz/ilker/llmgw && cd llmgw
+make build
+make test
+./bin/llmgw --version
+```
+
+`make build` writes `./bin/llmgw`. Go 1.26.6 or later is the only requirement (an older Go fetches it itself).
+
+## 2. Check the path with a fake engine
+
+Before involving a GPU, prove the router works. `sim-engine` is an
+OpenAI-compatible fake that streams placeholder words.
+
+```
+./bin/llmgw sim-engine --listen :8001 --model llama &
+./bin/llmgw server --endpoint e1=http://127.0.0.1:8001=llama &
+
+curl -N localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'x-session-id: demo' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"hello"}],"stream":true}'
+```
+
+Chunks of `alpha beta gamma ...` ending in `data: [DONE]` mean the router is
+fine. Stop both before continuing (see [Stopping](#stopping)).
+
+## 3. Serve a real model
+
+Two processes, two ports. Clients only ever talk to the router; the router
+knows where the engine is because you tell it with `--endpoint`:
+
+```
+curl :8080  ->  llmgw router :8080  ->  llama serve :8082  ->  model
+ (client)        (the gateway)           (the engine)
+```
+
+Requests go to 8080. Port 8082 is the engine's own, and you only touch it to
+check that the engine is up.
+
+llmgw does not install engines or weights. You need:
+
+- a `llama-server` build from llama.cpp (CUDA build if you want the GPU), and
+- a `.gguf` file.
+
+Check the card first with `nvidia-smi`. An 8 GB card holds a 1B model at bf16
+(2.4 GB) or a 9B model at `q4_k_m` (5.4 GB).
+
+Start the engine on its own port. The model name given to `--alias` is the name
+clients will use:
+
+```
+llama serve \
+  -m /path/to/Llama-3.2-1B-Instruct-BF16.gguf \
+  --host 0.0.0.0 --port 8082 -ngl 99 --alias llama
+```
+
+`-ngl 99` offloads every layer to the GPU. Confirm it is up and knows the model:
+
+```
+curl -s localhost:8082/v1/models
+```
+
+Then point the router at it. The format is `id=URL=model`:
+
+```
+./bin/llmgw server --endpoint e1=http://127.0.0.1:8082=llama
+```
+
+## 4. Ask it something
+
+Streaming:
+
+```
+curl -N localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'x-session-id: demo' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"hello"}],"stream":true}'
+```
+
+One reply at once:
+
+```
+curl -s localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"hello"}],"max_tokens":100}'
+```
+
+Also useful: `curl -s localhost:8080/v1/models` and
+`curl -s localhost:8080/health`. `llmgw ctl` does not work in this mode: it
+talks to the control plane's admin API, which router-only mode does not have,
+so `ctl status` answers `404`.
+
+On the machine this was written on, a 1B bf16 model on an RTX 4070 laptop GPU
+answered at roughly 85 tokens per second.
+
+## Several replicas of one model
+
+Give the router more than one `--endpoint` with the same model name and it
+spreads requests across them. `x-session-id` keeps a conversation on the same
+replica so its cache is reused:
+
+```
+./bin/llmgw server \
+  --endpoint e1=http://127.0.0.1:8082=llama \
+  --endpoint e2=http://127.0.0.1:8083=llama
+```
+
+## Stopping
+
+```
+pkill -f "llmgw server"
+pkill -f "llmgw sim-engine"
+```
+
+Stop the engine the way you started it (Ctrl-C in its terminal).
+
+## What goes wrong
+
+**`listening on :8080: bind: address already in use`.** An earlier router is
+still running. `ss -ltnp | grep 8080` names the process; stop it first. This is
+the usual result of moving from step 2 to step 3 without stopping the fake
+engine's router.
+
+**`/v1/models` on the engine returns an empty list.** The engine was started
+without `-m`, so it is a router with nothing to load. Restart it with a model.
+
+**`error: nothing to serve`.** `llmgw server` with no `--endpoint` and no model
+carrying `profiles` has nothing to do. In router-only mode, always pass at least
+one `--endpoint`.
+
+**Requests fail with a model-not-found error.** The name in the request must
+match the name after the last `=` in `--endpoint`, and it must be a name the
+engine actually serves (its `--alias`).
+
+**Answers are poor.** A 1B model is a plumbing test, not a chat assistant. Swap
+in a larger `.gguf`; nothing else changes.
+
+## 5. Let llmgw run the engine (control plane and node agent)
+
+Steps 2 and 3 start the engine by hand. Here a **node agent** starts and
+supervises llama.cpp for you, and a control plane decides where the model runs.
+Still one machine, still no `sudo`. Stop everything from steps 2 and 3 first:
+the GPU has to be free and port 8080 unused.
+
+```
+curl :8080  ->  llmgw server (control plane + router)  <-  llmgw agent (this node)
+                                                              |
+                                                       starts llama-server :20000
+```
+
+The agent dials the control plane over mutual TLS, so this needs a small private
+certificate authority. Everything goes in a scratch directory, `devcluster/`,
+which is in `.gitignore`.
+
+### Certificates
+
+```
+mkdir -p devcluster/pki
+./bin/llmgw ctl cert init-ca --dir devcluster/pki
+./bin/llmgw ctl cert issue-server llmgw-ctl --host 127.0.0.1 --host localhost \
+  --dir devcluster/pki --out devcluster
+./bin/llmgw ctl cert issue-client llmgw-node01 --dir devcluster/pki --out devcluster
+```
+
+The name given to `issue-client` becomes the certificate's common name and must
+equal `node_id` in the agent config. The control plane refuses an agent whose
+claimed id differs from its certificate.
+
+### The engine wrapper
+
+The agent starts the engine as `<bin> --model ... --port ...`. A `llama` binary
+that wants `llama serve ...` refuses every flag, so put a wrapper in front of it:
+
+```
+cat > devcluster/llama-server <<'EOF'
+#!/bin/sh
+exec /path/to/llama serve "$@"
+EOF
+chmod +x devcluster/llama-server
+
+./bin/llmgw ctl engine-check llamacpp --bin devcluster/llama-server
+```
+
+`engine-check` should end with `every flag llmgw builds is accepted`. If your
+build already ships a `llama-server` binary, point `bin` at that and skip the
+wrapper.
+
+### Control plane config: `devcluster/server.yaml`
+
+```yaml
+listen: "127.0.0.1:8080"
+admin_listen: "127.0.0.1:9090"
+agent_listen: "127.0.0.1:7443"
+
+agent_tls:
+  ca: devcluster/pki/ca.pem
+  cert: devcluster/server.pem
+  key: devcluster/server-key.pem
+
+models:
+  - name: llama
+    source: /path/to/Llama-3.2-1B-Instruct-BF16.gguf
+    routing_profile: chat
+    context_length: 8192
+    scaling: { min: 1, max: 1 }
+    profiles:
+      - name: gpu
+        engine: llamacpp
+        gpu_class: 4070-8g
+        weight: 1
+        priority: 100
+        startup_timeout: 5m
+```
+
+Three things in there are easy to get wrong:
+
+- **The model must have at least one profile.** That is what switches the control
+  plane on. With `models: []` the server starts as a plain router and exits with
+  `nothing to serve`.
+- **`gpu_class` decides CPU or GPU.** Without it the replica is placed in the CPU
+  pool and runs on the CPU. Get the class name from `./bin/llmgw agent inventory`
+  (the `CLASS` column).
+- **There is no `auth:` block.** Leave it out for a local trial; with auth on,
+  requests need an API key.
+
+### Agent config: `devcluster/agent.yaml`
+
+```yaml
+node_id: llmgw-node01
+server: "https://127.0.0.1:7443"
+mgmt_addr: "127.0.0.1"
+
+tls:
+  ca: devcluster/pki/ca.pem
+  cert: devcluster/llmgw-node01.pem
+  key: devcluster/llmgw-node01-key.pem
+
+engines:
+  llamacpp:
+    bin: /absolute/path/to/devcluster/llama-server
+
+supervisor:
+  work_dir: devcluster/agent-work
+```
+
+### Run it
+
+Two terminals:
+
+```
+./bin/llmgw server --config devcluster/server.yaml
+./bin/llmgw agent  --config devcluster/agent.yaml
+```
+
+The model is not placed at once. The control plane waits about 35 seconds for the
+fleet to settle after it starts, then places the replica, and the agent then
+loads the weights. Watch it with:
+
+```
+./bin/llmgw ctl nodes
+./bin/llmgw ctl models
+./bin/llmgw ctl replicas
+./bin/llmgw ctl explain-placement llama
+```
+
+`STATUS ready` in `ctl models` means it is serving. `nvidia-smi` should now show
+the model in GPU memory. The same curl from step 4 works against port 8080.
+
+`ctl` works here, unlike in router-only mode, because there is a control plane
+for it to talk to.
+
+Stop it with Ctrl-C in each terminal. The agent leaves the engine running when
+the agent itself stops, so if you restart the agent and the GPU stays full,
+`pgrep -af "llama serve"` will show the engine still up.
+
+## 6. Memory: conversations and notes
+
+Off unless you ask. llmgw otherwise stores nothing anyone typed. On a single
+machine with no API keys, one block in the server config turns on two things:
+
+```yaml
+threads:
+  store: devcluster/data/threads.db
+  retain_hours: 24
+```
+
+Restart the server after adding it. `retain_hours` is required: everything kept
+expires that long after it was last written.
+
+Everything kept this way sits in one shared pool with no owner, and anyone who
+can reach the port and knows an id can read it. That is fine on one machine and
+wrong on a shared network. With auth on, threads and notes are per project
+instead and the block is ignored; see [install.md](install.md).
+
+### Conversations (threads)
+
+Send the same `x-llmgw-thread` id and only the new turn. llmgw puts the stored
+history in front of it:
+
+```
+curl -s localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' -H 'x-llmgw-thread: demo' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"My name is Deniz."}]}'
+
+curl -s localhost:8080/v1/chat/completions \
+  -H 'content-type: application/json' -H 'x-llmgw-thread: demo' \
+  -d '{"model":"llama","messages":[{"role":"user","content":"What is my name?"}]}'
+
+curl -X DELETE localhost:8080/v1/threads/demo     # forget it
+```
+
+Without the block, a request carrying `x-llmgw-thread` is refused with
+`this gateway keeps no conversations` rather than answered without its history.
+
+### Notes an agent keeps for itself
+
+Notes outlive any one conversation. Each is a key, some text and optional tags,
+kept per agent; name the agent with `x-llmgw-agent` (default `default`), so two
+agents using the same key do not read each other's notes.
+
+```
+curl -X PUT localhost:8080/v1/memory/favorite-color \
+  -H 'content-type: application/json' \
+  -d '{"text":"The user likes dark green.","tags":["preference"]}'
+
+curl 'localhost:8080/v1/memory?q=green'          # search by words
+curl 'localhost:8080/v1/memory?tag=preference'   # or by tag
+curl localhost:8080/v1/memory/favorite-color
+curl -X DELETE localhost:8080/v1/memory/favorite-color
+```
+
+The same notes are offered to an agent as tools over MCP at
+`http://localhost:8080/mcp`: `remember`, `recall` and `forget`. Add that URL to
+your agent's MCP server list (HTTP transport; how you set request headers such
+as `x-llmgw-agent` depends on the client). llmgw does not put these tools into
+chat requests on its own, so an agent that is not given the server never sees
+memory.
+
+Limits: a key is up to 200 bytes, a note's text up to 16 KiB, at most 16 tags,
+1000 notes per agent. Tags are lowercase letters, digits, `-` and `_`.
+
+## Where this stops
+
+Router-only mode (steps 2 to 4) has no authentication, no placement and no model
+management: you start and restart engines yourself. Step 5 adds placement, model
+management and a node agent, and can add authentication as `install.md`
+describes. For a real cluster, with several nodes, systemd and a persistent
+certificate authority, follow [install.md](install.md).
+
+One caveat found while writing this page: `install.md` recommends starting with
+an empty `models: []` and adding models later with `ctl model add`. The control
+plane only turns on when the config declares a model with `profiles`, so that
+first start does not produce a control plane.

docs/fabrics.md

@@ -0,0 +1,210 @@
+# InfiniBand fabrics and NVLink
+
+For a site whose GPU nodes are joined by InfiniBand or RoCE, by NVLink, or both
+— several independent fabrics, NVL72 racks, eight-GPU HGX boards. It says what
+llmgw does with them, what it needs from you before it can, how to check a node
+in one command, and where to look when a replica spanning nodes will not run.
+
+Read [install.md](install.md) first; this is the part of it that only matters
+once there is a fabric.
+
+> **Where this stands.** Every piece here was written against the real formats
+> of `sminfo`, `saquery`, `ibnetdiscover`, `nvidia-smi topo -m` and
+> `nvidia-smi -q`, and tested against them — but none of it has yet run on a
+> site with the hardware. Run `llmgw doctor --json` on two or three nodes first
+> and keep the reports: if a parser meets a format it does not know, that report
+> is what fixes it, and the fix is a control plane upgrade, not one per node.
+
+## What llmgw does with them
+
+**Two kinds of interconnect.** InfiniBand or RoCE joins nodes (scale-out).
+NVLink joins GPUs — inside one machine on an HGX board, or across the nodes of a
+rack on an NVL72 or an NVLink Switch system (scale-up). A replica spanning nodes
+is placed, in order of preference:
+
+1. inside one **multi-node NVLink domain**, if any has enough usable nodes:
+   tensor parallelism between its nodes then runs over NVLink;
+2. on one **physical InfiniBand or RoCE fabric**, preferring nodes under one
+   leaf switch and putting nodes with a degraded cable last.
+
+It is never split across two fabrics or two NVLink domains. Within a node, the
+GPUs a shard gets are the set with the most NVLink pairs, then the nearest to
+the fabric's adapters, then on one NUMA node.
+
+**A fabric has a name and an identity.** The name is what `agent.yaml` says; the
+identity is what the adapters report — on InfiniBand the subnet managers every
+port on one fabric sees, on RoCE the IP network of its RoCE v2 address. The name
+is how you address a fabric; the identity is how llmgw catches the name being
+wrong: two independent fabrics given one name are placed as two, and the
+cluster page says so.
+
+## Before a node joins
+
+On every GPU node:
+
+| What | Why | Check |
+|---|---|---|
+| NVIDIA driver | everything | `nvidia-smi` |
+| `nvidia-fabricmanager`, on an NVSwitch machine | without it CUDA does not start on those GPUs | `systemctl is-active nvidia-fabricmanager` |
+| `rdma-core`, `ib_uverbs` loaded | user-space RDMA at all | `ls /sys/class/infiniband`, `lsmod \| grep ib_uverbs` |
+| `nvidia_peermem` loaded | GPUDirect RDMA; without it NCCL copies every transfer through host memory | `lsmod \| grep nvidia_peermem` |
+| `infiniband-diags` | tells llmgw which fabric a port is on; the agent installs it if missing | `which sminfo` |
+
+On an NVL72 or NVLink Switch system, also:
+
+| What | Why | Check |
+|---|---|---|
+| `nvidia-imex` running, every node of the domain in `/etc/nvidia-imex/nodes_config.cfg` | GPUs in different nodes share memory through it | `systemctl is-active nvidia-imex` |
+| an IMEX channel (`options nvidia NVreg_CreateImexChannel0=1`) | an engine opens one | `ls /dev/nvidia-caps-imex-channels` |
+| every GPU joined to its domain | the fabric manager does this | `nvidia-smi -q \| grep -A6 Fabric` shows `State: Completed` |
+
+On each InfiniBand fabric:
+
+- **A subnet manager, and a standby.** Without one, ports come up to `INIT` and
+  stay there; without a standby, the fabric keeps its routes if the master
+  stops but cannot recover from any change after. llmgw watches this but does
+  not run one.
+- **Its own name** in `agent.yaml` on every node attached to it. Optionally, a
+  distinct `subnet_prefix` in each subnet manager's configuration, which makes
+  GIDs unique across fabrics; llmgw does not need it.
+
+## Declaring the fabrics
+
+In `/etc/llmgw/agent.yaml`, the adapters on each fabric, by name:
+
+```yaml
+fabrics:
+  - name: ib-compute
+    hcas: [mlx5_0, mlx5_1, mlx5_2, mlx5_3, mlx5_6, mlx5_7, mlx5_8, mlx5_9]
+  - name: ib-storage
+    hcas: [mlx5_4]
+```
+
+or `--fabric ib-compute:mlx5_0,mlx5_1,…` when onboarding ([node-onboarding.md](node-onboarding.md)).
+An adapter belongs to one fabric; a node may be on several. A replica on
+`ib-compute` is given only `ib-compute`'s adapters (`NCCL_IB_HCA`).
+
+The rate is measured, not taken from the file: a fabric's rate on a node is the
+slowest of its active adapters, because a collective runs at the speed of its
+slowest link.
+
+The agent checks the declaration against the adapters on every heartbeat. An
+adapter that is missing, or whose port is down, takes that fabric off the node
+within seconds — the node stops being offered multi-node work on it — and
+returns it when the port comes back.
+
+## Checking a node: `llmgw doctor`
+
+```
+sudo llmgw doctor                 # uses /etc/llmgw/agent.yaml when present
+sudo llmgw doctor --json > $(hostname)-doctor.json
+```
+
+It reads the node and says what is wrong and how to fix it, most serious first,
+and exits non-zero when anything fails:
+
+```
+FAIL  nvlink  this machine has NVSwitch but nvidia-fabricmanager is inactive: CUDA will not initialise on its GPUs
+              → systemctl enable --now nvidia-fabricmanager (its version must match the driver's)
+WARN  fabric  nvidia_peermem is not loaded: GPUDirect RDMA is off, and NCCL copies every transfer through host memory
+              → modprobe nvidia_peermem
+OK    gpu     8 GPUs: 8× NVIDIA H100 80GB HBM3
+OK    nvlink  NVLink groups: [0 1 2 3 4 5 6 7]
+OK    fabric  mlx5_0/1 ACTIVE at 400 Gb/s (InfiniBand), subnet manager 0x248a07030030f0c0 (LID 1, SMINFO_MASTER)
+OK    fabric  subnet managers of 0x248a07030030f0c0's fabric: 0x248a07030030f0c0 (master, priority 15), 0x248a07030030f1d4 (standby, priority 14)
+OK    agent   fabric ib-compute: mlx5_0,mlx5_1,… usable at 400 Gb/s
+OK    agent   NCCL bootstraps over ens3 (10.1.0.21)
+```
+
+followed by each GPU's NVLink peers and nearest adapter, each port's state,
+rate and errors, and the NCCL environment a shard on each fabric would be given.
+`--json` writes every fact it read as well as what it concluded — send that
+file when the report is not enough.
+
+## Checking two nodes: `llmgw ctl fabric-test`
+
+Every check on one node can pass while two nodes still cannot reach each other
+— a cable into the wrong switch, a partition key, a RoCE network with no route
+— and a replica spanning them then hangs on its first all-reduce. Before
+placing one, on the control plane:
+
+```
+llmgw ctl fabric-test gpu01 gpu02
+```
+
+```
+gpu01 → gpu02 on ib-compute, 41s
+
+RAIL              LINK      MEASURED    VERDICT  DETAIL
+mlx5_0 → mlx5_0   400 Gb/s  388.2 Gb/s  ok       97% of 400 Gb/s
+mlx5_1 → mlx5_1   400 Gb/s  241.0 Gb/s  slow     60% of 400 Gb/s: check the cable, and the card's PCIe width and NUMA node
+mlx5_2 → mlx5_2   400 Gb/s  0.0 Gb/s    fail     gpu01: ib_write_bw: Couldn't connect to 10.1.0.22:18517
+```
+
+It runs `ib_write_bw` (perftest, installed on a node the first time) from each
+of the first node's adapters on the fabric to the same adapter on the second —
+mlx5_0 to mlx5_0, the way NCCL pairs them — one rail at a time, through the
+agents, so no SSH between nodes is needed. Each rail is graded against its
+link's rate: **ok** at 80% or more, **slow** at 50%, **fail** below that or when
+nothing got through. `--fabric` picks one when the nodes share several,
+`--seconds` the length of each rail's run. The traffic is real: run it when the
+fabric is quiet.
+
+It measures RDMA between adapters, not GPUDirect or NCCL itself: a pass says
+the fabric carries traffic between these two nodes at its rate, which is what
+a first all-reduce needs and what nothing on one node can show.
+
+## Watching them
+
+- **Cluster page, Fabrics.** Each declared fabric and what it physically is;
+  a table of subnet managers per fabric — master, priority, standbys, the last
+  change of master — and every disagreement: one name on two fabrics, two names
+  on one, an adapter up but undeclared, ports up with no subnet manager, a
+  fabric with no standby, a recent failover.
+- **`/admin/fabrics`.** Each fabric's map, from `ibnetdiscover` run by one of
+  its nodes every five minutes: switches in their tiers, adapters under their
+  leaves, cables coloured by rate, degraded ones in red, rail alignment, and
+  the cluster's own adapters live with their traffic. Click anything for its
+  detail.
+- **`/admin/nvlink`.** Each multi-node NVLink domain as a rack of trays: which
+  GPUs are joined, which node's IMEX is down, which link runs degraded.
+- **A node's page.** Its ports with state, rate, errors and what they are
+  physically on; its GPU-by-GPU NVLink matrix; its load.
+- **Metrics**, for alerts:
+
+| Metric | Alert when |
+|---|---|
+| `llmgw_ib_port_active` | a declared port is 0 |
+| `llmgw_ib_port_counter_total{counter="symbol_error"}` and `link_downed` | rising |
+| `llmgw_ib_port_rate_gbps` | below its usual rate |
+| `llmgw_fabric_subnet_managers{state="standby"}` | absent or 0 |
+| `llmgw_fabric_master_sm` | its `sm_guid` changes (a failover) |
+| `llmgw_fabric_problems{level="fail"}` | above 0 |
+| `llmgw_gpu_nvlink_joined` | 0 |
+| `llmgw_imex_up` | 0 |
+
+## What an engine is given
+
+For a shard on an InfiniBand or RoCE fabric:
+
+| Variable | Value |
+|---|---|
+| `NCCL_IB_HCA` | that fabric's adapters on this node, and no others |
+| `NCCL_IB_DISABLE` | `0` (`1` for a single-node shard) |
+| `NCCL_SOCKET_IFNAME`, `GLOO_SOCKET_IFNAME` | the node's management interface: `mgmt_interface`, or the one holding its management address |
+| `NCCL_IB_GID_INDEX` | on RoCE only: the RoCE v2 entry with an IPv4 address |
+| `NCCL_MNNVL_ENABLE`, `NCCL_CUMEM_ENABLE` | `1`, for a replica inside a multi-node NVLink domain |
+
+A profile's `env` overrides any of them. vLLM launches a multi-node replica
+with its own multiprocessing (`engines.vllm.launch_mode: mp`, the default):
+every node runs `vllm serve` with its rank and the leader's address, the
+workers headless. `launch_mode: ray` is there for a vLLM too old for that.
+
+## When a replica spanning nodes will not run
+
+| It | Look at |
+|---|---|
+| is not placed | `llmgw ctl explain-placement <model>`: a fabric split by identity, a node whose IMEX is down, a node refused because its adapters are cabled to two fabrics |
+| starts and hangs on its first collective | `llmgw ctl fabric-test` between two of its nodes; the cluster page's fabric problems; `doctor` on each node — a port down, the wrong interface, RoCE without a v2 GID |
+| runs, slowly | `nvidia_peermem`; the map for a degraded cable; the node page's NVLink matrix for a group that crossed PCIe |
+| worked yesterday | the subnet manager table for a failover; `link_downed` on the node's ports |

docs/facility-aware-placement.md

@@ -0,0 +1,400 @@
+# Facility-aware placement: rack power, temperature and cooling
+
+**Status: steps 0, 1 and 2 are built, with the manual hold of step 4;
+temperature conditions (steps 3 and 4) and shedding (step 5) are not**,
+until the thermal data of a real site is at hand — without it thresholds would
+be designed against guesses. This is the design for step 5 of resource
+allocation, after reserved CPU cores and memory (1), capacity classes and
+preemption (2), tenant capacity quotas (3) and sizing by measured throughput
+(4). [What is built](#what-is-built) says what works today and where it
+departs from the design below; the rest of the document is the design.
+
+## What is built
+
+**Where a node is.** Five labels: `llmgw.io/site`, `room`, `row`, `rack` and
+`pdu` (a comma separated list, for a dual-fed rack). They come from the node's
+`agent.yaml` under `labels:`, or from the control plane:
+
+```
+llmgw ctl label gpu01 llmgw.io/rack=r12-07 llmgw.io/pdu=r12-07-a,r12-07-b
+llmgw ctl label gpu01 llmgw.io/rack-        # back to agent.yaml's value, if any
+```
+
+Labels set with `ctl label` are kept in the store, win over the agent's, and
+may be set before the node joins. A misspelt `llmgw.io/` key is refused. A
+domain is named `level:name` — `rack:r12-07`, `pdu:r12-07-a` — and names are
+taken as given, so two rooms that both have a rack `r1` must label them apart.
+A node without location labels is in no domain and places as it always did.
+
+**Spreading.** A model's next replica goes first to a node sharing no rack and
+no PDU with the nodes the model already runs on; nodes sharing fewer come
+before nodes sharing more. It is an ordering, never a filter: a rack holding
+the only free cards still takes the replica. It ranks above preferring a node
+that already holds the weights — a second replica one breaker away from the
+first is worth less than the copy saved — and above bin packing.
+
+**Keeping a replica together.** A profile's `keep_within: rack` (or `row`,
+`room`, `site`) keeps a multi-node replica's nodes in one such domain, inside
+the fabric or NVLink domain placement already requires; nodes without the
+label are passed over for it, with the reason.
+
+**Holds.** `llmgw ctl facility hold rack:r12-07 --reason "PDU swap"` places
+nothing new in the domain, as a cordon of each of its nodes would, including
+nodes labelled into it later. `--drain` also drains its nodes, one replica at
+a time with the replacement up first; `llmgw ctl facility release` undoes
+both. Holds are kept in the store across restarts (the drain itself is node
+state, which is not: after a restart the hold still keeps work out, and
+replicas not yet moved stay where they are). Any domain can be held: a PDU
+holds every rack on it.
+
+**Power budgets.** In `server.yaml`:
+
+```yaml
+facility:
+  margin: 0.1            # share of every cap kept free
+  gpu_watts: 700         # a card that reports no power limit
+  cpu_core_watts: 10     # a core reserved by a CPU replica (cpu_cores)
+  node_watts: 350        # each node's own draw beyond its cards
+  budgets:
+    - domain: rack:r12-07
+      cap_watts: 16000   # what one feed carries alone, derated
+      other_watts: 800   # switches, storage
+    - domain: pdu:r12-07-a
+      cap_watts: 7400
+```
+
+A replica's draw is the profile's `power_watts` (split over its nodes) when
+declared; otherwise each card at the power limit it reports through the agent's
+sensors (or `gpu_watts`), and each reserved core at `cpu_core_watts`. A
+domain's use is, node by node, `node_watts` plus the larger of what is placed
+there and what the node's sensors read in the last two minutes
+(`measured_fresh`), plus the domain's `other_watts`. A shard that would take
+any of its node's domains past `cap × (1 − margin)` is refused; a multi-node
+replica's shards are counted together, so two that each fit a rack alone do not
+both go into it. A draw nobody knows — no declared figure, no card limit, no
+`gpu_watts` — counts as nothing: missing data never blocks.
+
+**What people see.** `llmgw ctl explain-placement` names the domain: *rack
+r12-07 is held: PDU swap*, *rack r12-07: 14.2 kW of a 14.4 kW limit (16.0 kW
+cap less 10%) in use, the shard needs ~2.8 kW*. The rejections of a placed
+replica are kept too, so a replica in an unexpected rack says why. `llmgw ctl
+nodes` has a LOCATION column, shows *ready, held*, and filters with `--domain
+rack:r12-07`. `llmgw ctl facility` lists every domain with its nodes, use,
+limit, reserved and measured draw, and holds. The console's Nodes view has a
+WHERE column; a node's page shows its location and hold, and its menu sets
+the location (**Location…**) and holds or releases its rack. The admin API:
+`GET /api/v1/facility`, `POST /api/v1/facility/holds`, `DELETE
+/api/v1/facility/holds/{domain}`, `POST /api/v1/nodes/{id}/labels`.
+
+**Where it departs from the design below, and why.**
+
+- Domains come from labels alone; there is no facility file declaring them.
+  Budgets are in `server.yaml`, the one file the control plane already reads.
+  A DCIM export would generate that block.
+- Feeds are not modelled. The cap given is what one feed carries alone,
+  derated — the figure the design says matters — so the operator gives the
+  one number instead of llmgw deriving it from two.
+- The manual hold of step 4 is built now, without conditions: it needs no
+  sensor data and answers the commonest facility event, planned maintenance.
+  Its command is `ctl facility hold`, with a `--drain` the design did not have.
+- `keep_within` is new: the request that a multi-node replica stay in one rack
+  where the cabling requires it.
+- Spreading is an ordering of candidates, not the scoring of the design; power
+  headroom does not yet order racks ("level load across racks"), and
+  multi-node replicas are not spread across racks.
+- No `llmgw_domain_*` metrics or alerts yet; `ctl facility` and the API carry
+  the same figures.
+
+## Why
+
+In a large installation the scarce thing is often not a GPU but the room it
+sits in. Three failures are invisible to placement today:
+
+- **A rack goes over its power budget.** Every node in it reports healthy;
+  placement sees free cards and fills them; the breaker, or the facility's
+  power cap, decides the rest. A rack with A and B feeds is worse: it runs
+  fine until one feed fails and the other cannot carry the load.
+- **Hot hardware is slow hardware.** GPUs throttle long before they fail. A
+  replica placed in a rack whose inlet air is too warm serves fewer tokens per
+  second than its measured capacity says, and nothing connects the two.
+- **Correlated failure.** Two replicas of a model on two nodes in the same rack
+  or on the same PDU are one failure away from zero. Placement spreads replicas
+  across nodes, not across racks.
+
+The goal is for placement to treat facility limits the way it already treats
+memory and cores: reserve against a budget, refuse what does not fit, say why,
+and never let missing data stop the cluster.
+
+## What it builds on
+
+| Already in place | Used for |
+|---|---|
+| Node labels, reported by agents, matched by `node_selector` | Where a node is: its rack, row, PDU |
+| `inventory.Allocation` carries GPUs, memory and cores per shard | Adding watts, summed per rack and PDU |
+| Placement rejections (`explain-placement`, headroom's "why not") | Naming the rack that is full or hot |
+| Headroom: the scheduler dry-run on a copy of the inventory | Room that respects power budgets, for free |
+| Preemption with classes, minimums and a dry run (step 2) | Shedding load from a hot rack in the right order |
+| Measured throughput per profile (step 4) | Tokens per watt as a placement preference |
+| Node sensors, read by every agent (step 0, built) | Heat and power with no facility integration: see below |
+| `internal/promq`, a Prometheus client | Reading facility metrics that DCIM exporters publish |
+
+## Concepts
+
+**Location.** Each node has a place in a tree: site, room, row, rack. Power has
+its own tree beside it: a rack draws from one or more PDUs, and each PDU from a
+feed. Both are read from node labels with well-known keys:
+
+```yaml
+# agent.yaml
+labels:
+  llmgw.io/site: sto1
+  llmgw.io/room: hall-b
+  llmgw.io/row: "12"
+  llmgw.io/rack: r12-07
+  llmgw.io/pdu: r12-07-a,r12-07-b   # both feeds, for a dual-fed rack
+```
+
+A node without these labels is its own rack of one: placement behaves as it
+does today.
+
+**Domain.** A rack, a row, a PDU, a room: anything with a budget or a
+condition. Domains are declared in a facility file (below) or discovered from
+node labels; a label naming a domain the file does not declare creates it with
+no budget and no condition.
+
+**Budget.** A domain may have a power cap in watts. Placement reserves each
+replica's estimated draw against every domain its node belongs to and refuses a
+placement that would take any of them past its cap less a safety margin. For a
+dual-fed rack the cap that matters is what one feed can carry alone, since that
+is what the rack must survive.
+
+**Condition.** A domain has a thermal and cooling condition: `ok`, `warm`, `hot`
+or `unknown`, derived from readings against thresholds with hysteresis.
+Conditions change what placement prefers and allows; they are not amounts to
+fill.
+
+**Reading.** A measured value with a time: inlet temperature, power draw, a
+cooling unit's alarm state. Readings older than their staleness limit are
+treated as absent.
+
+## Estimating a replica's draw
+
+What placement reserves has to be known before the replica runs, so it is an
+estimate first and a measurement later:
+
+1. **Declared.** A profile may say `power_watts`. The operator's figure wins.
+2. **Derived.** Otherwise GPU profiles take each card's power limit from NVML
+   (the agent already reads the cards; the power limit is one more field) plus
+   a per-node share for CPU, memory and fans; CPU profiles take their reserved
+   cores times a per-core figure for the node's CPU model.
+3. **Measured.** Once replicas run, the agent reports their cards' actual draw
+   (NVML) and, where the BMC allows, the node's (Redfish or IPMI DCMI). A
+   domain's headroom is computed from the larger of what is reserved and what
+   is measured, so an estimate that was too low is corrected by the room it
+   stops offering, not by an outage.
+
+## Decisions
+
+### Power
+
+- **Hard limit.** A placement that would take any domain past `cap × (1 −
+  margin)` is rejected, with the domain and the figures: *rack r12-07: 14.2 of
+  16.0 kW reserved, replica needs ~2.8, margin 10%*.
+- **Feeds.** For a domain with two feeds the cap is the smaller feed's rating
+  times its derating (typically 80%), not the sum.
+- **Already over.** A domain found over its cap, because the estimate was low
+  or the cap was lowered, gets no new placements, and an alert. It is not
+  emptied automatically; shedding power is the facility's decision, and
+  stopping inference to do it is ours only if asked (see shedding below).
+
+### Temperature and cooling
+
+Thresholds are per domain with defaults, and each condition needs to hold for a
+while before it changes, in both directions, so a single reading neither
+starts nor ends anything:
+
+| Condition | Enters when | Placement |
+|---|---|---|
+| `ok` | below the warm threshold for 5 min | normal |
+| `warm` | inlet above the warm threshold for 2 min, GPU temperatures near throttling, or any GPU thermally throttled | allowed, scored down: other domains first |
+| `hot` | inlet above the hot threshold for 2 min, a cooling unit in alarm, or a sustained share of the domain's GPUs thermally throttled | no new placements, as a cordon would, but automatic and reversible |
+| `unknown` | no fresh reading | as `ok`, and reported as unknown |
+
+**Shedding** (optional, off by default): a domain `hot` for longer than its
+shed delay has load moved off it using step 2's machinery. The lowest class goes
+first, and replicas above their model's minimum go before any at it. A critical
+minimum is never touched, and moves are rate limited to one replica per domain
+per interval. The replica is placed elsewhere first where there is room, so
+shedding moves work rather than dropping it. GPU power capping (`nvidia-smi
+-pl`) is a gentler alternative worth measuring against shedding: less
+throughput, no restart.
+
+### Spreading
+
+Replicas of one model are spread across racks, and across PDUs, the way they
+are spread across nodes today. This is a preference, dropped when it is the only
+thing standing in the way, as node spreading already is.
+
+### Scoring
+
+Placement today filters, then takes the first candidate in a fixed order
+(fewest free GPUs for GPU profiles, fewest replicas for CPU ones, nodes holding
+the weights first). Facility signals are better as a score than as more
+filters. Candidates that pass the hard limits are ordered by:
+
+1. condition: `ok` before `warm`;
+2. power headroom left in the rack after this replica, more first, so load
+   levels across racks;
+3. the existing order.
+
+Once measurements include power, step 4's profile preference can use tokens per
+watt instead of tokens per GPU where both are known.
+
+## Where the data comes from
+
+A `FacilitySource` interface, implemented several ways, chosen in
+`server.yaml`:
+
+```go
+type FacilitySource interface {
+    // Domains is what the source knows: budgets, thresholds, members.
+    Domains(ctx) ([]Domain, error)
+    // Readings is the latest value of each signal, per domain.
+    Readings(ctx) ([]Reading, error)
+}
+```
+
+- **Static file.** Domains, caps and thresholds, written by hand or generated
+  from a DCIM export. Enough for power budgets with no live data at all.
+- **Prometheus.** DCIM, PDU (SNMP exporter) and BMC (Redfish exporter)
+  readings usually end up in Prometheus. The source runs configured instant
+  queries and maps their labels onto domains:
+
+  ```yaml
+  facility:
+    source: prometheus
+    prometheus: http://monitoring:9090
+    signals:
+      inlet_temp_c:
+        query: max by (rack) (dcim_rack_inlet_temperature_celsius)
+        domain_label: rack
+        stale_after: 2m
+      power_watts:
+        query: sum by (pdu) (pdu_outlet_power_watts)
+        domain_label: pdu
+      cooling_alarm:
+        query: max by (row) (crac_alarm)
+        domain_label: row
+  ```
+- **Agents (built, step 0).** What each node reads about itself, every ten
+  seconds at most, sent with its heartbeat:
+  - **GPUs, from nvidia-smi:** temperature, memory (HBM) temperature where the
+    driver reports it, power draw, the enforced power limit, and what is
+    holding the clocks down now — `sw_power_cap`, `hw_slowdown`, `sw_thermal`,
+    `hw_thermal`, `power_brake`.
+  - **CPUs, from hwmon** (what lm_sensors reads, without it installed): the
+    package temperature, or the hottest core; and the board's inlet or ambient
+    sensor where it has one (`SYSTIN`, `Inlet`, `Ambient`).
+  - **CPU power, from RAPL:** the packages' energy counters over time,
+    subdomains not counted twice, counter wrap handled.
+
+  A machine without a sensor reports nothing for it, never a zero; a VM has
+  none of them. Published as `llmgw_gpu_temperature_celsius`,
+  `llmgw_gpu_memory_temperature_celsius`, `llmgw_gpu_power_watts`,
+  `llmgw_gpu_power_limit_watts`, `llmgw_gpu_throttled{reason}`,
+  `llmgw_node_cpu_temperature_celsius`, `llmgw_node_cpu_power_watts` and
+  `llmgw_node_inlet_temperature_celsius`, and on each node's page.
+
+  What they can and cannot say:
+  - **Throttling is the strongest signal there is.** A temperature is a proxy;
+    a card holding its clocks down is the fact that invalidates its measured
+    capacity, and it needs no threshold to be chosen.
+  - **Measured power** is GPU draw plus CPU packages; memory, disks, fans and
+    power-supply losses are not in it, so a node's draw is that plus an
+    estimated remainder. A rack's is its llmgw nodes' plus a declared figure
+    for everything else in it: switches and storage report nothing here.
+  - **CPU and GPU temperatures follow the load, not the room.** A hot rack is
+    inferred from many nodes running hot at comparable load, or from
+    throttling, not from one node's CPU. Only a board inlet sensor reads the
+    air, and most boards have none.
+  - **No budget comes from a sensor.** A reading is a draw; the cap it is
+    measured against still comes from the facility.
+- **Simulated.** Readings from a script, for tests and for rehearsing a
+  thermal event on a cluster without facility data.
+
+## Safety
+
+- **Missing data never blocks.** A source that is down, a reading that is stale,
+  a node without location labels: placement behaves as it does today, and says
+  the data is missing (a metric, a line on the cluster page). Facility
+  awareness can make placement more careful, never impossible.
+- **Hysteresis and hold times** on every condition, so a noisy sensor does not
+  flap a rack between allowed and forbidden.
+- **Observe-only first.** A mode where every decision is computed, logged and
+  shown ("would have refused: rack r12-07 hot") but nothing is enforced, run
+  for long enough to trust the thresholds before turning enforcement on.
+- **Manual override.** `llmgw ctl facility hold RACK` and `release RACK`, for the
+  facility team to mark a domain unavailable, or to clear a condition they know
+  to be a sensor fault.
+- **Shedding is opt-in**, per domain or cluster-wide, and rate limited.
+
+## What people see
+
+- `explain-placement` and headroom name the domain: *rack r12-07 is hot (inlet
+  31°C for 6 min)*, *pdu r12-07-a: 7.1 of 7.4 kW*.
+- `llmgw ctl facility` lists domains with budget, reserved, measured and
+  condition. The cluster page gets a rack summary beside the nodes table.
+- Metrics: `llmgw_domain_power_budget_watts`, `_reserved_watts`,
+  `_measured_watts`, `llmgw_domain_condition{condition}`,
+  `llmgw_domain_reading_age_seconds`; alerts for a domain near its cap, a
+  domain hot, a domain over its cap, and facility data gone stale.
+
+## Rollout
+
+Each step ships on its own and is useful without the next:
+
+0. **Node sensors, observe-only (built).** GPU heat, power and throttling,
+   CPU heat and power, inlet air where the board has a sensor; published and
+   shown, no decision changed.
+1. **Location and spreading (built).** Well-known labels, domains from labels, replicas
+   spread across racks and PDUs, locations on the node views. No facility data
+   needed.
+2. **Power budgets from a static file (built, without headroom
+   scoring).** Caps and margins, estimated draw per
+   replica (declared or derived), hard limit in placement and headroom.
+3. **Readings, observe-only.** The Prometheus source beside the agents',
+   conditions with hysteresis (throttling first among them), measured power
+   folded into headroom; decisions shown, not enforced.
+4. **Thermal enforcement.** `warm` scored down, `hot` refused; the manual hold
+   and release are built.
+5. **Shedding and tokens per watt.** Opt-in shedding through step 2's
+   preemption; measured power in profile preference.
+
+## Testing
+
+- The simulated source drives unit tests of every condition transition, the
+  hysteresis, staleness, and the placement outcomes, with mutation checks as
+  for steps 1–4.
+- Property tests: whatever the readings, placement never exceeds a declared
+  cap with fresh data, and never refuses everything because data is missing.
+- On the PoC cluster, with no facility data: step 1 with labelled VMs, step 2
+  with a static file of made-up caps, steps 3–4 with the simulated source
+  replaying a thermal event.
+- Before enforcement anywhere real: a period in observe-only mode against the
+  site's actual data.
+
+## Open questions
+
+- **What the sites have.** Which DCIM, which PDUs, which BMCs, and whether any
+  of it already reaches a Prometheus. The source design assumes Prometheus is
+  the common ground; a site without it needs another source.
+- **Who owns the numbers.** Caps, deratings and thresholds belong to the
+  facility team. Whether they edit llmgw's file, or llmgw reads theirs.
+- **Phase balance.** Three-phase PDUs have per-phase limits; whether placement
+  should see phases or only the PDU total.
+- **Cooling granularity.** Cooling is often per row or per aisle, not per rack;
+  the domain tree allows either, but the defaults should match what sites
+  actually measure.
+- **Power capping instead of shedding.** Whether to lower GPU power limits in a
+  warm rack rather than move replicas, and how that interacts with measured
+  capacity from step 4, which would no longer hold at the lower limit.

docs/guardrails.md

@@ -0,0 +1,390 @@
+# Guardrails
+
+Written for the operator deciding what the gateway lets through: what a
+policy can check, what it can do, and how one is attached to a team.
+
+`llmgw server init` writes a `baseline` policy that applies to every
+request, with Qwen3Guard-Gen 0.6B as its judge on CPUs; see
+[install.md](install.md#2-the-control-plane) for what it checks. The
+policies are part of the cluster's settings, kept in the store: `llmgw ctl
+config edit` (or the console's Settings) changes them, and the change is in
+force on every control plane within seconds, without a restart. A cluster
+whose settings were brought in from a server.yaml without a `guard:` section
+gets the `baseline` policy, without a judge. With no policies, nothing is
+checked and nothing costs anything. With one, every request is judged once it is authorised and
+within its limits, with its stored conversation spliced in, and before it is
+sent to a model; and the answer is judged before the client sees it.
+
+## Turning them off and on
+
+```
+llmgw ctl guard off --note "why"   # no request is checked, whatever the policies say
+llmgw ctl guard on                 # every policy checks again, as it was
+```
+
+That is `guard.enabled` in the cluster's settings, in force on every control
+plane within seconds without a restart. The policies and where they are
+attached are kept. While off, `llmgw ctl status`, `llmgw ctl guard list` and
+the guardrails page say so. To stop one policy rather than all, give it
+`mode: off`, or `mode: shadow` to have it record what it would do.
+
+## A policy
+
+```yaml
+guard:
+  # Applied to every request.
+  default: [baseline]
+  policies:
+    baseline:
+      input:
+        pii: {secret: block, card: redact}
+        injection: flag
+      output:
+        pii: {secret: block}
+    finance:
+      mode: enforce          # enforce (default), shadow, off
+      fail: closed           # open (default) or closed, for checks that can fail
+      no_store: true         # no conversations, notes, prefix routing or external models
+      max_output_tokens: 2048
+      system_prompt: "You answer questions about Acme's products only."
+      drop_client_system: true
+      stream: sentence       # sentence (default) or buffer_all
+      require_capabilities: true   # no tools/images to models whose catalog entry lacks them
+      validate_structured: true    # answers must fit response_format's json_schema
+      input:
+        pii: {email: redact, phone: redact, iban: block, tckn: redact}
+        injection: block
+        max_chars: 40000
+        deny:
+          - {name: codename, regex: "(?i)project falcon", action: block}
+      output:
+        pii: {iban: redact, tckn: redact, secret: block}
+      tools:
+        allow: [search, fetch]
+        deny: [shell]
+        on_denied: strip     # strip (default) or block
+        max_calls_per_turn: 4
+        validate_arguments: true
+```
+
+**What is found.**
+
+- **Personal data:** email, phone, iban, card, tckn, ip. Each is checked
+  before it counts: IBANs by their mod-97 check, cards by Luhn and issuer
+  prefix, TCKNs by their two check digits, phone numbers only when written
+  to be dialled (`+90…`, `00…`, `0532…`).
+- **Secrets** (`secret`): OpenAI- and Anthropic-style keys, AWS access key
+  ids, GitHub, Slack and Google tokens, JWTs, PEM private keys and llmgw's
+  own keys.
+- **Prompt injection:** instructions to drop instructions (English and
+  Turkish), chat-template control tokens in user text, invisible Unicode,
+  long encoded blobs. These are found through disguises: fullwidth letters,
+  Cyrillic look-alikes, zero-width characters, and base64, hex and URL
+  encoding two levels deep.
+- **`deny` patterns:** matched against the text as written, and as a model
+  reads it once those disguises are removed.
+
+**What is done.**
+
+- **`flag`** lets the request through and records it.
+- **`redact`** rewrites the value as a placeholder (`[EMAIL_1]`; the same
+  value is the same placeholder throughout a request).
+- **`block`** stops it.
+
+**Putting them back.** With `restore: true` in a policy's `input`, the
+values a request had redacted are put back in its answer: the model reads
+"write to [PERSON_1] at [EMAIL_1]", the client reads the name and address
+it sent. Streamed answers too — a placeholder split across two events is
+held until it is whole. Only that request's own values, only into its
+answer; the map is kept in memory for the request and nowhere else. The
+output rules then read the answer as the client will, so a policy that
+redacts personal data in answers still does.
+
+```yaml
+input:
+  pii: {email: redact, phone: redact}
+  restore: true
+```
+
+**Shapes.**
+
+- `system_prompt` is put first.
+- `drop_client_system` removes the caller's own system and developer
+  messages.
+- `max_output_tokens` is set where a request asks for none, and lowers one
+  that asks for more.
+- A tool `deny`/`allow` list strips the tool from the request, or refuses
+  it.
+- In the answer, a call to a tool that is not allowed, more calls than
+  `max_calls_per_turn`, or arguments that do not fit the parameters the
+  request declared (`validate_arguments`) stop it.
+- `require_capabilities` refuses tools offered to a model whose catalog
+  entry does not say `capabilities.tools`, and images to one without
+  `capabilities.vision`. It is opt-in because an entry that says nothing is
+  read as "cannot".
+- `validate_structured` checks an answer against the `json_schema` the
+  request asked for in `response_format`. Buffered, or streamed with
+  `buffer_all`, an answer that does not fit is stopped; streamed a sentence
+  at a time it has gone out already, and is flagged.
+
+## A judge model
+
+Patterns find what has a shape. For what does not — violence, crime,
+sexual content, self-harm, jailbreaks, whatever a moderation model was
+trained on — a policy can have a **judge model on the cluster** read the
+text.
+
+The judge must be in the catalog under the name the policy gives, as a
+judge (`role: guard`), with a replica ready. When it is not, what the
+policy judges is refused with `guard_unavailable` (`fail: closed`) or served
+unjudged (`fail: open`), and `llmgw ctl status` and the console's Overview
+say which judge and why.
+
+### Which judge
+
+| judge | runs on | size | |
+|---|---|---|---|
+| `qwen3guard-0.6b` | CPUs | 0.8 GB | the default: about 2 s a check on two threads |
+| `qwen3guard-4b` | a GPU | 2.5 GB | for a cluster with a card to spare |
+| `qwen3guard-8b` | a GPU | 4.7 GB | |
+| `llama-guard-3-1b` | CPUs | 0.9 GB | the earlier default: refuses ordinary coding requests |
+| `llama-guard-3-8b` | a GPU | 4.6 GB | |
+
+Measured on the reference cluster, as the judge's probability of "unsafe"
+for ordinary coding requests against harmful ones, Llama Guard 3 1B could
+not tell them apart: "continue" 0.51, "continue the code above" 0.89, "how
+do I kill all child processes in bash" 0.92, against 0.97 to 1.00 for
+harmful requests, at any quantisation. Qwen3Guard-Gen 0.6B gave the
+ordinary ones 0.15 at the most and the harmful ones 1.00. Its verdicts are
+safe, unsafe and **controversial**; controversial counts as safe unless the
+policy says `controversial: unsafe`.
+
+A policy that names one of these is enough: the leader fetches its weights
+into the mirror and serves it as a judge, and serves it again if it is
+removed from the catalog. Another judge is served by hand with `--repo`.
+
+```
+llmgw ctl guard judge status              # each judge the policies ask, and what is wrong with it
+llmgw ctl guard judge enable              # Qwen3Guard-Gen 0.6B on CPUs, or the judge the policies ask that is missing
+llmgw ctl guard judge enable --gpu        # Qwen3Guard-Gen 4B on a GPU
+llmgw ctl guard judge use qwen3guard-4b qwen3guard-0.6b   # the order every policy asks them in
+llmgw ctl guard judge enable --replace    # when a model of that name is there, but not as a judge
+```
+
+or **Do → Serve the guardrails' judge** in the console.
+
+### A GPU and CPUs together
+
+`judge.models` is a list asked in turn: the first judge that answers gives
+the verdict. The next is asked when one has no replica serving, fails, or
+does not answer within `latency_budget`; a judge with no replica at all is
+passed over at once. A judge on a GPU first and one on CPUs after it is
+the GPU's speed while it has its card, and the CPUs' when it does not.
+
+```yaml
+judge:
+  models: [qwen3guard-4b, qwen3guard-0.6b]
+  input: block
+  output: block
+  latency_budget: 5s           # each judge's wait
+```
+
+A judge on a GPU is served as a `standard` model, on one card: it takes a
+card only from what may give one up, and waits while every card is busy,
+the judge on CPUs standing in. A judge on CPUs is `critical`, with two
+replicas, because every judged request waits on one. `llmgw ctl guard judge
+status` says, for each judge, which is asked when it gives no verdict.
+
+### When it refuses ordinary requests
+
+A refusal by a judge names the hazard it saw — the client is told `refused
+by the gateway's policy (judge: Violent)` — and the same is kept with the
+request: `llmgw ctl request <id>`, the server's log (`guard_rule`) and the
+guardrails page show it. To see what the judge says of any text, without
+anything being kept:
+
+```
+llmgw ctl guard judge ask 'How do I sort a list in Python?'
+# qwen3guard-0.6b: safe, 1900 ms
+# it answered: "Safety: Safe\nCategories: None"
+```
+
+A judge that says `unsafe` to ordinary text is usually Llama Guard 3 1B
+(`llmgw ctl guard judge use qwen3guard-0.6b`), the wrong weights (another
+repository's, without the judge's template: `judge enable --replace` serves
+the right ones), or a policy counting every category: give its judge
+`categories`. The baseline counts Violent, Non-violent Illegal Acts, Sexual
+Content or Sexual Acts, Suicide & Self-Harm and Jailbreak; PII is the
+patterns', and copyright, unethical acts and politically sensitive topics
+refuse too much ordinary work. While finding out, `judge.input: flag`
+records instead of refusing.
+
+A judge's file served from the mirror page — Llama Guard, Qwen3Guard,
+ShieldGemma — is served as a judge too, under the name the policies ask.
+By hand, the catalog entry is:
+
+```yaml
+# a catalog model (server.yaml models:, or ctl model add)
+- name: qwen3guard-0.6b
+  source: http://mirror:8081/qwen3guard-0.6b/…/Qwen3Guard-Gen-0.6B.Q8_0.gguf
+  role: guard
+  guard:
+    format: qwen3guard         # qwen3guard, llamaguard3, shieldgemma or json
+  scaling: {min: 2, max: 2}
+  profiles: [{name: cpu, engine: llamacpp}]
+
+# in a guard policy
+judge:
+  models: [qwen3guard-0.6b]    # or model: one judge
+  input: block                 # flag or block; empty does not ask about input
+  output: flag
+  categories: [Violent, Jailbreak]   # only these count; empty: any unsafe verdict
+  controversial: safe          # or unsafe
+  latency_budget: 250ms        # each judge's wait; after the last, fail: open serves (flagged), closed refuses
+```
+
+A model with `role: guard` is the guardrails' alone:
+
+- it is not in `/v1/models` or the chat page, and is refused (404) to
+  every key, as a name and as a fallback;
+- it must always run — on demand is refused. One on CPUs is `critical`
+  and should have two replicas on different nodes, because every judged
+  request waits on it.
+
+The gateway's calls to it go past admission, accounting and the guardrails
+themselves.
+
+- **Formats:**
+  - `qwen3guard` asks in Qwen3Guard's own words and reads "Safety: Safe |
+    Unsafe | Controversial" and its "Categories:".
+  - `llamaguard3` reads Meta's "safe" / "unsafe\nS1,S10"; give the catalog
+    entry `categories` to have S1 recorded as its name.
+  - `shieldgemma` asks Google's model whether the text breaks the listed
+    principles (`categories`, each a sentence) and reads Yes or No.
+  - `json` expects `{"safe": false, "categories": [...]}`.
+- **What is read:**
+  - **Input:** the request's last user turn, after the patterns.
+  - **Output:** the answer, together with that user turn. A streamed answer
+    is read every 600 characters and at the end, so text between two
+    readings has gone out already; `stream: buffer_all` holds it until it
+    is read.
+  - **A long text** is read by its start and its end (about 6000
+    characters), so a message with a file pasted into it fits the judge's
+    context rather than overflowing it and going unjudged.
+- **Cache:** the same text is not asked about twice within five minutes.
+
+## An outside service
+
+A site required to use a particular guardrail — Azure Content Safety,
+Lakera Guard, NeMo Guardrails, a classifier of its own — names it in a
+policy's `services`. It is asked over HTTP beside the patterns and before
+the judge; its "unsafe" blocks or flags like theirs, and a service that does
+not answer is what the policy's `fail` says.
+
+```yaml
+policies:
+  strict:
+    fail: closed
+    services:
+      - name: lakera
+        url: https://api.lakera.ai/v2/guard
+        header_files: {Authorization: /etc/llmgw/secrets/lakera}   # "Bearer …", read each call
+        body: '{"messages": [{"role": "user", "content": {{json .Text}}}]}'
+        blocked: flagged                 # where the answer says unsafe
+        reason: breakdown.0.detector_type
+        on: both                         # input, output or both
+        action: block                    # or flag
+        timeout: 2s
+```
+
+`body` is a template given `.Text` (`{{json .Text}}` writes it as a JSON
+string; empty sends `{"input": …}`). `blocked` and `reason` are dotted paths
+into the JSON answer, numbers for list items; true, a number above zero, a
+non-empty list or a string other than "false" is unsafe. On input the
+service reads the latest user turn as the model will, with what `redact`
+took out still out; on output the whole answer, once, at its end, as the
+client reads it — with `restore`, the values put back. Being at the end, a
+service can stop a streamed answer only where it is held back
+(`stream: buffer_all`): released a sentence at a time, the client has read
+it by then, and what the service finds ends the stream with
+`content_filter`, flags it and is recorded. The rule recorded is
+`service:<name>:<reason>`. The service is told the text only, never who
+sent it. Under `fail: open`, the default, a service that cannot be asked
+lets the text through — and a caller can make it fail, sending what it
+refuses to read; give `fail: closed` where the service must decide. Of an
+answer asked for with `n` above 1, the service reads the first.
+
+## Where a policy applies
+
+`guard.default` applies everywhere. Others are attached to a part of the
+tenancy tree, and apply to everything below it:
+
+```
+llmgw ctl guard attach project:Acme/finance/payroll finance
+llmgw ctl guard attach key:key-7f3a baseline
+llmgw ctl guard list
+llmgw ctl guard detach project:Acme/finance/payroll finance
+```
+
+Policies narrow, as limits do. A policy attached lower can tighten what
+applies above it, never loosen it. Combined, they take:
+
+- the strictest mode and failure;
+- for each kind, the strictest action;
+- every deny pattern and denied tool;
+- only the tools every allow list allows;
+- the smallest limits;
+- `no_store` if any of them asks;
+- every pinned prompt, widest first.
+
+An attachment applies at once.
+
+## What a client sees
+
+**A refused request** is answered with 400:
+
+```json
+{"error": {"type": "invalid_request_error", "code": "content_policy_violation",
+           "message": "this request was refused by the gateway's policy (secret)"}}
+```
+
+It names the category, never the text, and costs nothing.
+
+**A stopped answer** ends with `finish_reason: "content_filter"`. A stream
+ends with that chunk and `[DONE]`, and the engine is cancelled. The
+Responses API reports it as `incomplete` with
+`incomplete_details.reason: "content_filter"`.
+
+**Headers:** `x-llmgw-guard` (`flagged`, `redacted`, `blocked`) and
+`x-llmgw-guard-policy` say what was done.
+
+**Streams.** A streamed answer is judged a sentence at a time. Text is held
+until a sentence, a line or 200 characters ends, released up to its last
+whitespace — so a value still arriving is never sent in two halves — and
+rewritten if needed. **What was released cannot be taken back**: a policy
+that must never let a word through uses `stream: buffer_all`, which holds
+the whole answer until it is judged.
+
+## Shadow mode
+
+`mode: shadow` judges and records — the usage row says `shadow-blocked`,
+`shadow-redacted` — and changes nothing. Run a new policy in shadow first,
+and read what it would have done before enforcing it.
+
+## What is recorded
+
+Each request's usage row has the action, policy, category and the time the
+checks took. The access log has the action, stage and policy. Neither has
+the text, a matched value, or the placeholder map: the map exists only in
+the gateway's memory while the request is served.
+
+## In the console
+
+`sudo llmgw` has a **Guardrails** view: each policy with its mode, what it
+does when it cannot judge, and what it checks; whether each judge model it
+leans on has replicas ready — a policy that fails closed refuses everything
+while its judge has none; where policies are attached, with A to attach one
+and Enter on a row to detach it; and what they did in the last day (W for an
+hour or a week), totals first and the newest requests after, each with the
+request id `llmgw ctl request` reads. The same is at `GET /api/v1/guard` and
+`GET /api/v1/guard/events?since=24h`, and on the portal's Guardrails page.

docs/knowledge.md

@@ -0,0 +1,428 @@
+# Knowledge bases
+
+A knowledge base is a collection of a company's documents that the cluster
+can answer from. People put their documents into it from their own machines
+with `llmgw-kb`. The tool reads the files on that machine, cuts them into
+passages ("chunks") and sends their text; the gateway embeds each passage
+with the person's own key and keeps the text and the vectors. The files
+themselves never leave the machine.
+
+## Why retrieval, and not training
+
+Retrieval is the tool for *knowledge*: policies, procedures, contracts. The
+answer can name its source, a changed document is sent again in minutes, and
+a passage only ever reaches people allowed to read its collection.
+
+Training a model on the documents (LoRA) changes how it *writes*, not what it
+reliably *knows*. It has no access control: whatever goes into the weights
+is available to everyone who may use them.
+
+## What it needs
+
+- **The PostgreSQL store with pgvector.** On a SQLite store knowledge bases
+  are off, and `llmgw ctl kb list` and the console say why.
+  - `llmgw server init` and the high-availability database setup install
+    pgvector and enable it.
+  - A cluster set up before this build needs it by hand, once:
+    1. Install the package on every database machine:
+       `sudo apt-get install postgresql-16-pgvector` (use the server's
+       version number).
+    2. On the leader, enable it in llmgw's database:
+       `sudo -u postgres psql -d llmgw -c 'CREATE EXTENSION vector'`.
+    3. Restart the control planes: `llmgw restart`.
+- **An embedding model in the catalog**, with `capabilities.embeddings`.
+  Two good choices handle Turkish and run on CPUs: `BAAI/bge-m3` (1024
+  dimensions) and `Qwen/Qwen3-Embedding-0.6B`.
+
+  Add it as any model is added (**Serve a model** in the console, or the
+  catalog), with its entry saying that it embeds:
+
+  ```yaml
+  capabilities:
+    embeddings: true
+  ```
+
+  A collection stays with the model it was made with: vectors from two
+  models cannot be compared.
+
+  Some embedding models are trained with an instruction before the
+  question and none before the documents. Give it as the entry's
+  `query_prefix`; llmgw puts it before questions only. For
+  Qwen3-Embedding:
+
+  ```yaml
+  query_prefix: "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
+  ```
+
+  With pgvector 0.7 or later a collection's index is kept at half
+  precision (`halfvec`), which halves its memory and takes models of up to
+  4000 dimensions; with an older pgvector the limit is 2000. A collection
+  keeps the kind it was made with.
+
+## For administrators
+
+### Make a collection
+
+A collection belongs to one part of the tenancy tree: an organization, a
+team, a project or a person. Whoever is in the owner, at any level below it,
+may read it and add to it.
+
+```sh
+llmgw ctl kb create team:Acme/hr policies bge-m3
+llmgw ctl kb create user:USER-ID notes bge-m3 --org Acme
+```
+
+The model's dimension is asked of the model itself, so the model has to be
+able to serve when the collection is made. `--dims 1024` gives it instead.
+
+In the console: **Knowledge**, then **A**.
+
+### Who may read and add
+
+The owner, and everything below it, may read and add. A **grant** gives the
+same to another part of the same organization, to a person, or to one key:
+
+```sh
+llmgw ctl kb grant Acme/policies project:Acme/sales/crm           # read
+llmgw ctl kb grant Acme/policies team:Acme/legal --write          # read and add
+llmgw ctl kb revoke Acme/policies project:Acme/sales/crm
+```
+
+How access works:
+
+- **Grants add up down the tree.** A grant to a team reaches its projects
+  and their keys.
+- **Nothing crosses organizations.** A grant to another organization's
+  team, project, key or person is refused.
+- **A person's own key** (a key with no project) reads nothing by itself.
+  The person names the project they act in (`llmgw-kb login` asks for it,
+  or `--project`) and must be a member of it. Joining a second team
+  therefore does not quietly widen what every key of theirs can read.
+- **No access looks like no collection.** A collection a key may not read
+  is answered exactly as one that does not exist, so even its name does not
+  leak.
+
+### Answer from collections by default
+
+Clients that cannot add a header still get answers from the documents when
+their part of the tree has a default:
+
+```sh
+llmgw ctl kb default team:Acme/hr Acme/policies Acme/forms
+llmgw ctl kb default key:KEY-ID Acme/policies
+llmgw ctl kb default team:Acme/hr --clear
+```
+
+- **Which default applies.** The narrowest one: a key's over its project's,
+  a project's over its team's, a team's over its organization's.
+- **A request can override it.** A request that names collections uses
+  those instead, and `X-Llmgw-Knowledge: none` turns the default off for
+  that request.
+- **A default never refuses a request.** A collection the caller may not
+  read is left out for them. If the search fails (the embedding model is
+  down, say), the request is answered without passages and the failure is
+  logged.
+- **Changes take effect within 30 seconds.**
+
+In the console: **Knowledge**, Enter on a collection, then **Answer from it
+by default…**.
+
+### Look after it
+
+```sh
+llmgw ctl kb list                          # collections, owners, documents, grants
+llmgw ctl kb docs Acme/policies            # its documents, who added each and when
+llmgw ctl kb rm Acme/policies old/form.pdf # one document out
+llmgw ctl kb search Acme/policies how many days of annual leave
+llmgw ctl kb delete Acme/policies          # the collection, its documents and grants
+```
+
+Rules that apply:
+
+- A project, team or organization that owns a collection is not deleted
+  until its collections are. This is the same rule as for one with members.
+- A person's own collections go with their account (`users delete`,
+  `users forget`).
+- Every document added or removed is in the audit log (`llmgw ctl audit`),
+  by name. The text is never recorded.
+
+### A large import
+
+A few thousand documents ask the embedding model for far more than it can
+answer at once. Give the key that sends them a band of its own, below the
+people's, that may wait for room for minutes rather than the 30 seconds the
+others wait:
+
+```sh
+llmgw ctl config set router.admission.bands '[{name: gold, priority: 300, saturation_ceiling: 0.85},
+  {name: bronze, priority: 100, saturation_ceiling: 0.3}, {name: bulk, priority: 50, saturation_ceiling: 0.3, queue_ttl: 5m}]'
+llmgw keys create import --project Acme/docs --band bulk
+```
+
+The people's questions then go first, and the import waits behind them. The
+gateway embeds a document's passages 32 at a time, four batches at once,
+enough to fill an embedding replica's slots; a batch told to wait (`Retry-After`)
+waits up to five minutes before the document is answered the same, and
+`llmgw-kb` sends it again rather than counting it as failed. It gives up
+after 15 minutes.
+
+## For everyone: `llmgw-kb`
+
+### Get it
+
+Download `llmgw-kb` for your system from the release page, next to `llmgw`:
+
+| System | File |
+|---|---|
+| Windows (Intel/AMD) | `llmgw-kb-VERSION-windows-amd64.exe` |
+| Windows (ARM) | `llmgw-kb-VERSION-windows-arm64.exe` |
+| macOS (Apple silicon) | `llmgw-kb-VERSION-darwin-arm64` |
+| macOS (Intel) | `llmgw-kb-VERSION-darwin-amd64` |
+| Linux | `llmgw-kb-VERSION-linux-amd64` / `-arm64` |
+
+Rename it to `llmgw-kb` (`llmgw-kb.exe` on Windows) and put it somewhere on
+your PATH. You do not need to install anything else.
+
+On macOS, a downloaded program that is not signed is stopped the first time.
+Either right-click it and choose Open, or run
+`xattr -d com.apple.quarantine llmgw-kb`.
+
+### Log in once
+
+```sh
+llmgw-kb login
+```
+
+It asks for three things, checks them, and saves them where only you can
+read them:
+
+- **The gateway's address.**
+- **Your API key.** It is typed without being shown.
+- **A project.** Needed only for a personal key.
+
+Instead of logging in you can set `LLMGW_URL`, `LLMGW_API_KEY` and
+`LLMGW_PROJECT`.
+
+```sh
+llmgw-kb collections        # what your key may read, and which you may add to
+```
+
+### Send your documents
+
+```sh
+llmgw-kb sync policies ~/Documents/HR
+llmgw-kb sync policies "C:\Users\ayse\Documents\İK" --include "*.pdf,*.docx"
+llmgw-kb sync policies ./handbook ./forms --exclude "drafts/**"
+```
+
+Run it as often as you like. The first run sends everything. Later runs
+send only what changed, and do not even read files whose size and time have
+not changed.
+
+| Option | What it does |
+|---|---|
+| `--dry-run` | Reads and cuts everything, sends nothing, and lists what would leave the machine and how much. |
+| `--delete` | Also removes documents whose files are gone. Only those this machine sent, from these folders; never anything someone else sent. |
+| `--retry` | Reads again files skipped before, for example after installing LibreOffice. |
+| `--include`, `--exclude` | Glob patterns. `*.pdf` matches a file name; `reports/**/*.xlsx` matches a path. |
+| `--hidden` | Reads hidden files and folders too (left out by default). |
+| `-v` | Lists unchanged files too. |
+| `--embed-here` | Embeds the passages from this machine and sends the vectors. With a gateway that does not embed them itself it does so anyway. |
+
+Documents are named by their path under the folder, with forward slashes,
+on every system. With several folders, each folder's own name comes first.
+
+```sh
+llmgw-kb status policies    # what this machine sent and skipped, and why
+llmgw-kb history            # the latest runs
+llmgw-kb formats            # what can be read here
+```
+
+### What it reads
+
+| Read here | Formats |
+|---|---|
+| Documents | PDF (text), Word (`.docx`), Excel (`.xlsx`), PowerPoint (`.pptx`, with speaker notes), OpenDocument (`.odt`, `.ods`, `.odp`), RTF, EPUB |
+| Web and mail | HTML, MHTML, e-mail (`.eml`, with its attachments) |
+| Text | Markdown, plain text, CSV, JSON, YAML, XML, subtitles, notebooks (`.ipynb`), source code |
+| Archives | ZIP, with every file inside it read in turn |
+
+| Read with a helper on your machine | Helper |
+|---|---|
+| Word, Excel and PowerPoint 97–2003 (`.doc`, `.xls`, `.ppt`), Pages, Numbers, Keynote and others | [LibreOffice](https://www.libreoffice.org) |
+| Images and scanned PDFs | [Tesseract](https://tesseract-ocr.github.io) (with the Turkish language data), plus Poppler's `pdftoppm` for PDFs |
+| PDFs the built-in reader cannot parse | Poppler's `pdftotext` |
+
+`llmgw-kb formats` says which helpers it found. Text in UTF-8, UTF-16, or
+the Windows Turkish and Western code pages is read correctly.
+
+A file that cannot be read is skipped with the reason, and the run goes on.
+Reasons include a locked Office file, a format with no helper, and a
+scanned page with no OCR.
+
+### What leaves your machine
+
+For each new or changed document, one request leaves the machine, over the
+gateway's TLS connection: its name, its file's SHA-256 digest and size, and
+its passages' text. The gateway embeds the passages through `/v1/embeddings`
+as you, so your key's limits, budget and guardrails apply as if you had
+asked. That is about a kilobyte a passage; embedding here (`--embed-here`)
+brings each vector down and sends it up again, some thirty times more.
+
+The file itself is never sent. `--dry-run` shows exactly what would be.
+
+### The ledger
+
+`llmgw-kb` keeps a small SQLite database of what it did with every
+document: the file it came from, its size, time and digest, and whether it
+was sent, skipped or failed, with the reason.
+
+| System | Where it is |
+|---|---|
+| Windows | `%AppData%\llmgw-kb\ledger.db` |
+| macOS | `~/Library/Application Support/llmgw-kb/ledger.db` |
+| Linux | `~/.config/llmgw-kb/ledger.db` |
+
+Deleting the ledger is safe: the next run hashes every file once, finds what
+the collection already has, and sends nothing that is unchanged. `--ledger`
+uses another file.
+
+## Asking questions of a collection
+
+A chat request names the collections to answer from in a header. Any client
+that can add a header can do it: the OpenAI and Anthropic SDKs, Continue, or
+curl.
+
+```sh
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "X-Llmgw-Knowledge: politikalar" \
+  -d '{"model": "qwen2.5-coder-14b-instruct",
+       "messages": [{"role": "user", "content": "Kaç gün yıllık iznim var?"}]}'
+```
+
+```python
+client.chat.completions.create(
+    model="qwen2.5-coder-14b-instruct",
+    messages=[{"role": "user", "content": "Kaç gün yıllık iznim var?"}],
+    extra_headers={"X-Llmgw-Knowledge": "politikalar"},
+)
+```
+
+What the gateway does with such a request:
+
+1. **It finds the collections.** It looks up the ones named, by name or ID,
+   among those the key may read. A collection it may not read is answered
+   404, the same as one that does not exist.
+2. **It embeds the question.** The last user message is embedded by the
+   collection's model, on the caller's own account: their limits, budget and
+   guardrails apply.
+3. **It searches.** The collections are searched by meaning and by words
+   (below).
+4. **It adds the passages.** The best passages are numbered and added to the
+   system message, with an instruction to answer from them, cite them as
+   [1], [2], and say so when they do not hold the answer. The system message
+   is created if the request has none. Passages that would not fit the
+   model's context are left out, the weakest first.
+5. **It judges and sends the request.** The request, passages included, then
+   goes through the guardrails and to the model as usual. A document
+   carrying instructions aimed at its reader is judged like anything else
+   the model reads.
+
+On the portal's chat page, **Documents** picks a collection the person may
+read in the chosen project, the default, or none. Under each answer, the
+sources it was given are listed by number.
+
+How it is shaped:
+
+| | |
+|---|---|
+| `X-Llmgw-Knowledge` | Collections, comma separated; `none` for no passages, whatever the default. |
+| `X-Llmgw-Knowledge-K` | How many passages, 1 to 20; 5 by default. |
+| `X-Llmgw-Project` | For a personal key: the project it acts in. |
+| `x-llmgw-sources` (answer) | The passages given, as `document#chunk`, in their numbered order; empty when nothing matched. |
+
+Behaviour to know about:
+
+- **No passages matched.** The model is told that nothing in the documents
+  answers the question, and asked to say so rather than answer from general
+  knowledge.
+- **Other APIs.** Requests through `/v1/responses` and `/v1/messages`
+  (Codex, Claude Code) work the same way, since they are answered as chat
+  completions.
+- **Separate prefix caches.** On vLLM replicas, a request given passages
+  carries a `cache_salt` derived from the collections they came from.
+  Requests that could be given the same passages still share cached blocks,
+  and no one else's do: not another organization's, nor another team's of
+  the same one. How fast an answer starts therefore says nothing about what
+  someone else asked.
+- **No answer cache.** Answers from knowledge bases are never served from
+  the answer cache, because two keys of one project can read different
+  collections.
+
+### How a passage is chosen
+
+Each passage scores the following, and the highest scores win:
+
+- its similarity in meaning to the question (cosine, 0 to 1), plus
+- up to 0.3 for the share of the question's words it contains.
+
+Words almost every passage has ("ne", "için", "the", "of") are not counted.
+The meaning does most of the work: "how much leave do fathers get" finds the
+paternity page, not the annual-leave page that shares more of its words.
+The word match helps with what meaning cannot carry, such as a form number,
+a product code or a name.
+
+Metrics: `llmgw_kb_retrievals_total{result}` (found, nothing, refused) and
+`llmgw_kb_retrieval_seconds`.
+
+## Training an adapter on a collection
+
+An adapter (LoRA) changes how a model *writes*: the organisation's words,
+format and tone. It does not reliably teach facts. On the PoC, a small
+model trained on nine policy documents answered 4 of 9 rephrased questions
+right and mixed facts up on the rest, while the same questions through the
+knowledge base got 9 of 9. Use both: the knowledge base for what answers
+say, an adapter for how they sound.
+
+```sh
+# 1. Questions and answers from the collection, written by a model of the
+#    cluster. Read the file through and correct it.
+llmgw ctl kb dataset Acme/policies --model qwen2.5-coder-14b-instruct --out policies.jsonl
+
+# 2. Train on a node. --gpu-memory is what the job needs of a card; it
+#    runs beside an engine when the engine leaves that much free.
+llmgw ctl train start policies-tone --model qwen2.5-0.5b-instruct \
+  --base-repo Qwen/Qwen2.5-0.5B-Instruct --node cuda01 --gpu-memory 2300 --data policies.jsonl
+llmgw ctl train show JOB --follow
+
+# 3. Make it the model's adapter, kept on the mirror.
+llmgw ctl train publish JOB --restart
+```
+
+The node trains with its installed vLLM's torch and a small overlay (peft
+and accelerate), as the engines' user. For a model llama.cpp serves, it also
+converts the adapter to GGUF with the installed llama.cpp's own code. What
+it makes is kept by the control plane (`llmgw ctl train download`).
+
+An adapter is private like its collection:
+
+- **It has an owner.** An adapter trained on a collection carries some of
+  what the collection says in its weights, so it belongs to a part of the
+  tree.
+  - By default the owner is the collection's owner.
+  - `--owner` names another, which must be able to read every collection
+    the pairs came from.
+  - Only callers in the owner's part of the tree see the adapter. To anyone
+    else it is a model that does not exist, absent from `/v1/models` too.
+- **It is public only by choice.** `--public` makes an adapter every
+  caller's. It is refused for pairs from a knowledge base, so it is only for
+  pairs written by hand.
+
+## How it is kept apart
+
+Passages live in PostgreSQL, partitioned by organization, with an index per
+collection. Every search and every write names the organization and the
+collections the caller may use. On top of that, row-level security on the
+table checks the same thing again, so a query that forgot its filter
+returns nothing rather than another tenant's passages.

docs/kong.md

@@ -0,0 +1,95 @@
+# llmgw and Kong
+
+For a site that already runs Kong. The two meet over plain HTTP: Kong in
+front of llmgw, as one more API it governs, or Kong behind llmgw, as an
+OpenAI-compatible provider. Nothing of either is built into the other.
+
+Tried with Kong Gateway 3.9 (`kong:3.9`, the last open-source release; 3.10
+and later need a Kong licence) in DB-less mode, in front of llmgw.
+
+## Kong in front of llmgw
+
+Two ways, both tried.
+
+**A plain route.** Kong forwards the request as it came. Tried with chat
+completions, streamed and not; llmgw's other APIs — Anthropic's
+`/v1/messages`, `/v1/responses`, embeddings, pictures — go the same way,
+since Kong does not read them. Kong adds its own authentication, rate limits
+and logging; llmgw still checks the key, the budget and the guardrails.
+
+```yaml
+_format_version: "3.0"
+services:
+- name: llmgw
+  url: https://llm.example.com          # llmgw's client port
+  routes:
+  - name: llmgw
+    paths: [/llmgw]                      # /llmgw/v1/chat/completions → /v1/chat/completions
+```
+
+**Kong's `ai-proxy` plugin**, for Kong's own token statistics on a chat
+route. llmgw is an OpenAI provider whose `upstream_url` is llmgw:
+
+```yaml
+services:
+- name: llmgw-chat
+  url: https://llm.example.com
+  routes:
+  - name: chat
+    paths: [/chat]
+  plugins:
+  - name: ai-proxy
+    config:
+      route_type: llm/v1/chat
+      logging: {log_statistics: true, log_payloads: false}
+      model:
+        provider: openai
+        name: qwen-coder                 # a model llmgw serves
+        options:
+          upstream_url: https://llm.example.com/v1/chat/completions
+```
+
+**Keys.** Without an `auth` block, `ai-proxy` passes the client's
+`Authorization` header on: each team keeps its own llmgw key, and llmgw's
+budgets, limits, guardrails and usage stay per team. With
+`auth: {header_name: Authorization, header_value: "Bearer sk-llmgw-…"}` Kong
+sends one key of its own instead, and llmgw sees every caller as that key —
+then budgets per team are Kong's to keep.
+
+**What Kong counts.** For a whole answer Kong reads llmgw's `usage` and
+records prompt and completion tokens as llmgw did. For a streamed answer
+Kong 3.9 records an estimate of the prompt tokens and no completion tokens,
+even with `stream_options.include_usage` set — the usage chunk reaches it
+and is not read. llmgw's own accounting counts both; use its usage export
+(`llmgw ctl usage export`) or `/admin/usage` for figures to bill by.
+
+**Timeouts.** A long answer from a model still loading outlasts Kong's
+60-second defaults: set the service's `read_timeout` to the time a model may
+take to start, as for nginx in [install.md](install.md).
+
+## Kong behind llmgw
+
+Not tried here. Kong's AI routes speak OpenAI's API, so llmgw reaches models Kong fronts as
+it reaches any provider: a model whose source is `external`.
+
+```yaml
+- name: kong-gpt
+  source: external
+  external:
+    url: https://kong.example.com/openai     # Kong's route, without /v1
+    model: gpt-4o-mini
+    api_key_file: /etc/llmgw/secrets/kong-consumer.key
+```
+
+The key is the one Kong's own authentication asks of a consumer. As a
+fallback (`fallbacks: [kong-gpt]`) it is used only when the cluster has no
+room.
+
+## Which to choose
+
+Kong in front when the site's API policy says every API goes through Kong:
+llmgw is then one more upstream, and its per-team accounting still holds
+when each team keeps its own key. Kong behind when the site already reaches
+outside providers through Kong and llmgw should too. llmgw does not need
+Kong for anything it does itself — keys, budgets, guardrails, routing to
+its own replicas.

docs/kubernetes.md

@@ -0,0 +1,228 @@
+# llmgw and Kubernetes
+
+The control plane runs in Kubernetes, from the Helm chart in
+`deploy/helm/llmgw`. The GPU nodes do not: they stay ordinary machines,
+joined with `llmgw node add` as on any other cluster. This page says why,
+and how the two meet.
+
+## What goes where
+
+| Part | Where | Why |
+|---|---|---|
+| Control plane: the API on 8080, the agents' port 7443, the scheduler | A StatefulSet, from the chart | A Go binary with a store and three ports: what Kubernetes runs well |
+| Store | A file on a PersistentVolumeClaim (SQLite), or your PostgreSQL | Either, as on a host |
+| GPU and CPU nodes | Outside, as hosts | See below |
+| Model mirror | Outside, on a machine with a large disk | Every node pulls tens of gigabytes from it over plain HTTP; a pod with a volume that size is a host in all but name |
+
+### Why the nodes stay outside
+
+The agent on a node is not a service that happens to use a GPU. It installs
+the engines on the machine — the llama.cpp build for its driver, vLLM in a
+Python environment — checks them against their publisher's checksums and
+runs them; it chooses which GPUs each replica gets, by index and by NVLink
+topology; it starts engines as processes that outlive its own restarts, so a
+node upgrades while it serves; it writes the machine's firewall; and it
+replaces its own binary when the cluster upgrades. All of that is root on
+the host, which is exactly what a container is built to prevent.
+
+Run as a DaemonSet it would need to be privileged, with the host's network,
+process namespace and filesystem, and the NVIDIA device plugin would have to
+be kept off its GPUs — or the two would hand the same card to two owners.
+What is left is the host agent with a container's indirection around it, and
+none of the scheduling, isolation or restart guarantees that make a pod
+worth having. So the chart does not ship one, and this is the
+recommendation:
+
+- **Keep GPU machines out of Kubernetes**, and add them with `node add`.
+- **If they are already Kubernetes workers**, dedicate them: taint them so
+  no other pod lands there, keep the NVIDIA device plugin off them (most
+  installs select nodes by label — leave the label off), and run the llmgw
+  agent on the host, where `node add` puts it. llmgw then owns the GPUs, and
+  Kubernetes schedules nothing that would want them.
+
+## The image
+
+The project publishes binaries, not an image. Build one from the repository
+and push it where the cluster pulls from — at an offline site, the internal
+registry:
+
+```
+docker build -f deploy/container/Dockerfile --build-arg VERSION=v0.11.1 \
+  -t registry.internal/llmgw:v0.11.1 .
+docker push registry.internal/llmgw:v0.11.1
+```
+
+It is the static binary on a distroless base: no shell, running as user
+65532, with a read-only root filesystem in the pod.
+
+## The agent port's certificate
+
+Agents and the control plane authenticate each other with certificates from
+llmgw's own authority, and the TLS ends in the pod — so the authority's key
+stays outside the cluster, on the machine you will add nodes from, and the
+pod is given only its own certificate.
+
+Decide first the address agents will dial: the `-agents` Service is a
+LoadBalancer, so give it a fixed `agentService.loadBalancerIP` or a DNS name
+that points at it. That address has to be in the certificate:
+
+```
+llmgw ctl cert init-ca --dir ./pki
+llmgw ctl cert issue-server llmgw-ctl --host 10.0.0.200 --host llmgw-agents.example.com \
+  --dir ./pki --out ./pki
+kubectl -n llmgw create secret generic llmgw-agent-tls \
+  --from-file=ca.pem=pki/ca.pem \
+  --from-file=server.pem=pki/server.pem \
+  --from-file=server-key.pem=pki/server-key.pem
+```
+
+Keep `pki/ca-key.pem` as you would on a host: whoever holds it can make any
+node's identity.
+
+## Installing
+
+```yaml
+# values.yaml
+image:
+  repository: registry.internal/llmgw
+  tag: v0.11.1
+agentTLS:
+  existingSecret: llmgw-agent-tls
+agentService:
+  loadBalancerIP: 10.0.0.200
+ingress:
+  enabled: true
+  className: nginx
+  hosts: [{host: llm.example.com, paths: [{path: /, pathType: Prefix}]}]
+  tls: [{secretName: llm-example-com, hosts: [llm.example.com]}]
+config:
+  mirror:
+    api: http://models.internal:8082
+  # The address the router reaches nodes' engines from is a Kubernetes
+  # node's, once the pod's traffic leaves the cluster: the nodes' firewalls
+  # must let it in.
+  firewall_networks: ["10.0.1.0/24"]
+```
+
+```
+helm install llmgw deploy/helm/llmgw -n llmgw -f values.yaml
+```
+
+`config` is `server.yaml`: any key of [reference.md](reference.md), laid
+under what the chart sets itself — the listeners, where the certificates,
+the admin token and the store are mounted. A changed `config` restarts the
+pod.
+
+**The store.** By default SQLite, on a 10 GiB claim. For PostgreSQL, put its
+address in a Secret and point the chart at it:
+
+```
+kubectl -n llmgw create secret generic llmgw-store \
+  --from-literal=dsn='postgres://llmgw:…@pg.internal:5432/llmgw?sslmode=verify-full'
+```
+
+```yaml
+store:
+  type: postgres
+  postgres:
+    existingSecret: llmgw-store
+```
+
+**One control plane.** The chart runs one replica. Two against PostgreSQL
+would elect a leader and keep a standby, but a standby serves nothing and is
+never ready, so a StatefulSet rollout would wait on it for ever. Kubernetes
+replaces the one pod within seconds when it goes, and agents reconnect on
+their own; the replicas on the nodes keep serving meanwhile.
+
+**Probes.** Alive is `/health`. Ready is `/leader`, which on PostgreSQL waits
+for the lease of the pod it replaced to run out — not `/ready`, which waits
+for a model replica, and would keep a cluster with no node yet from ever
+accepting one.
+
+**Monitoring.** The metrics port, 9091, serves metrics and nothing else;
+`serviceMonitor.enabled: true` makes a ServiceMonitor for the Prometheus
+Operator, and `deploy/monitoring` holds the rules and dashboards.
+
+## Using it
+
+The admin API listens on the pod's loopback, as on a host — it can dump keys
+from the heap when profiling is on. Reach it through the pod:
+
+```
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw users create you@example.com --password '…'
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw users role you@example.com admin
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw ctl status
+```
+
+or from your machine, through a port-forward:
+
+```
+kubectl -n llmgw port-forward statefulset/llmgw 9090:9090 &
+export LLMGW_ADMIN_TOKEN=$(kubectl -n llmgw get secret llmgw-admin -o jsonpath='{.data.admin-token}' | base64 -d)
+llmgw ctl status
+```
+
+The token is made by the chart and kept across upgrades
+(`adminToken.existingSecret` brings your own).
+
+## Adding nodes
+
+From the machine holding `pki/`, with the port-forward above running and
+`LLMGW_ADMIN_TOKEN` set:
+
+```
+sudo -E llmgw node add ubuntu@gpu01 \
+  --server https://10.0.0.200:7443 --pki ./pki --admin 127.0.0.1:9090
+```
+
+`--server` is the address in the certificate. The node is installed, checked
+and started over ssh exactly as on any cluster ([node-onboarding.md](node-onboarding.md)),
+and dials the control plane in the pod. Its firewall comes from
+`firewall_networks` in the server configuration `node add` reads (`--config`,
+`/etc/llmgw/server.yaml` by default): copy the chart's out of the cluster
+first, or give `--no-firewall` and keep the engines' ports open to the
+Kubernetes nodes by hand.
+
+```
+kubectl -n llmgw get configmap llmgw -o jsonpath='{.data.server\.yaml}' > server.yaml
+sudo -E llmgw node add ubuntu@gpu01 --config ./server.yaml --server https://10.0.0.200:7443 \
+  --pki ./pki --admin 127.0.0.1:9090
+```
+
+## Offline
+
+An offline site ([install.md](install.md), "Offline sites") works the same
+way with the control plane in a pod. Import the bundle on the mirror's
+machine with `llmgw bundle import`, record its engines' checksums in a
+file, and give that file to the chart as a ConfigMap:
+
+```
+llmgw bundle trust llmgw-bundle.tar --sha256 3f2a… --file ./offline.sha256
+kubectl -n llmgw create configmap llmgw-offline --from-file=offline.sha256
+```
+
+```yaml
+offlineChecksums:
+  configMap: llmgw-offline
+config:
+  offline:
+    mirror: http://models.internal:8081
+```
+
+A later bundle: `bundle trust` into the same file, and replace the ConfigMap
+(`kubectl create configmap … --dry-run=client -o yaml | kubectl apply -f -`).
+The control plane reads the file again when it changes; there is no restart.
+
+## What has and has not been tried
+
+The chart is checked with `helm lint` and `helm template` for SQLite,
+PostgreSQL, an Ingress, a ServiceMonitor and an offline cluster, and refuses
+what would not work — no image, no certificate, a PostgreSQL store without
+its address, more than one replica. The image has been run the way the
+chart runs it — read-only root, user 65532, the same files mounted at the
+same paths, SQLite on a volume — and answered `/health`, `/leader` and
+`/metrics`, with `llmgw ctl` and `llmgw users` working through `exec`.
+
+It has **not** been installed on a Kubernetes cluster, and no node has yet
+joined a control plane running in one. Until it has, a control plane on a
+host is the well-trodden path.

docs/large-models.md

@@ -0,0 +1,145 @@
+# Large models: several cards, several nodes
+
+A model too big for one card runs on several. llmgw chooses how from the
+model's own figures and the cluster as it is; this page is the rules it
+follows, the commands, and what to look at when a first one is brought up
+on new hardware.
+
+## How a model is split
+
+In order, the first that fits:
+
+1. **One card.** Nothing to split.
+2. **Several cards of one node, tensor parallel.** Every layer is cut
+   across the cards, so they talk for every token: they must be on one
+   NVLink domain. The agent reads `nvidia-smi topo -m` and gives a replica
+   the cards with the most NVLink between them
+   ([install.md](install.md#nvlink-if-your-gpus-have-it)).
+3. **Several nodes, pipeline parallel between them.** Each node holds a
+   run of layers on all its cards (tensor parallel inside it), and only a
+   layer's output crosses to the next node. The nodes must share one
+   InfiniBand or RoCE fabric: a replica never spans two, and never a node
+   with none. Any number of nodes, not only two or four.
+
+The plan takes the fewest cards, then the fewest nodes, then the better
+precision up to eight bits.
+
+**Tensor width and the KV heads.** The cards split the model's KV heads
+among them, or past their number each card holds a copy of one. So the
+width divides the KV heads or is a multiple of them: a model with 8 KV
+heads runs 2, 4, 8 or 16 wide, not 12. Qwen3-235B has 4 and runs on 8.
+
+**Mixture of experts.** A model of experts (Qwen3-235B-A22B, DeepSeek-V3,
+Llama 4, Mixtral) on more than one card is served with vLLM's
+`--enable-expert-parallel`: each card holds whole experts rather than a
+slice of every one, which is less traffic per token. It is read from
+`config.json` (`num_experts`, `n_routed_experts`, `num_local_experts`).
+
+**When it does not fit.** A smaller precision first: an FP8 or AWQ
+repository of the same model, or a GGUF quantisation on llama.cpp if one
+node's cards hold it. Then more nodes. `llmgw ctl model plan REPO
+--precision bf16,fp8` shows each precision's fit from the model's config.
+
+## What a way needs
+
+Each way the plan offers says what a replica needs of each card, part by
+part, and of all its cards together:
+
+```
+$ llmgw ctl model plan meta-llama/Llama-3.3-70B-Instruct --format safetensors --context 32768
+FILE      SIZE    BEST WAY        A CARD   OF     ALL CARDS  NOW
+original  131 GB  4 × h100-80g    37.4 GB  72 GB  150 GB     free
+
+Best: original on 4 × h100-80g: 37.4 GB a card (weights 32.9 + context 2.5 + engine 2.0) of 72 usable; 150 GB on 4 cards.
+The context costs 0.31 GB per 1000 tokens, the whole model (--context to plan another).
+```
+
+- **weights:** the files, divided over the cards.
+- **context:** the KV cache for the context planned, divided likewise.
+- **engine:** the engine's own: 2 GB and a fiftieth of the weights for vLLM.
+- **usable:** 90% of a card; the rest is the driver's and fragmentation's.
+
+The console's **Serve a model** shows the same for every way a file runs.
+A context longer than planned is checked against it before anything is
+fetched.
+
+## Serving one
+
+Without flags the plan's best way is taken:
+
+```
+llmgw ctl model serve Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 --format safetensors --context-length 32768
+```
+
+Or a way given by hand, for instance two nodes of eight:
+
+```
+llmgw ctl model serve meta-llama/Llama-3.3-70B-Instruct --format safetensors \
+    --gpu-class h100-80g --gpus 8 --nodes 2 --env NCCL_DEBUG=INFO
+```
+
+`--gpus` is the cards on each node and `--nodes` the nodes. The pipeline
+is the nodes and the tensor width the cards of each.
+
+`--env KEY=VALUE` goes into the engine's environment on every node:
+`NCCL_DEBUG=INFO` while bringing a cluster up, `NCCL_IB_*` to steer it.
+Only the variables engines are tuned with are taken. llmgw already sets
+these:
+- `NCCL_IB_HCA` to the fabric's adapters;
+- `NCCL_IB_GID_INDEX` on RoCE;
+- `NCCL_SOCKET_IFNAME` to the management network;
+- for an NVLink domain spanning nodes, `NCCL_MNNVL_ENABLE`.
+
+The job's first step says what it needs of each card. The weights then
+come to the mirror once and from it to each node. The startup timeout (20
+minutes unless the profile's `startup_timeout` says otherwise) runs from
+when a node's download last moved. So a model of hundreds of gigabytes is
+not failed while it is still arriving, and one whose download stops is
+failed that long after.
+
+## Watching it come up
+
+| What | Where |
+|---|---|
+| The replica and its shards, one per node, each with its download | `llmgw ctl replicas` |
+| Why it is not placed | `llmgw ctl explain-placement MODEL` |
+| A node's engine output (NCCL's lines with `NCCL_DEBUG=INFO`) | `llmgw ctl logs NODE --source SHARD` |
+| The bandwidth between two nodes, rail by rail | `llmgw ctl fabric-test NODE NODE` |
+| Each node's GPUs, NVLink and adapters | `llmgw doctor` on the node; its page under /admin |
+| Every step of a start, across nodes | the `replica start` trace ([install.md](install.md)) |
+
+With `NCCL_DEBUG=INFO`, NCCL says which transport it took between nodes:
+`NET/IB` is the fabric. `NET/Socket` means it fell back to TCP, and the
+model will run, slowly.
+
+## Bringing it up on new hardware
+
+A first run on a fabric, in order. Each step is worth its output if
+something goes wrong.
+
+1. **The nodes.** Add each with its fabric:
+   `llmgw node add host --fabric ib-a:mlx5_0,mlx5_1`. Then
+   `llmgw ctl nodes` shows every node ready, on `ib-a`.
+2. **The fabric.** `llmgw ctl fabric-test node1 node2`: each rail at its
+   rated speed (a 400 Gb/s rail near 45 GB/s).
+3. **One node, several cards.** A dense 70B at bf16 on four or eight
+   cards of one node, by the plan:
+   `llmgw ctl model serve meta-llama/Llama-3.3-70B-Instruct --format safetensors`.
+   Ready, then a question answered.
+4. **Two nodes.** The same model forced over two:
+   `--gpu-class CLASS --gpus 8 --nodes 2 --env NCCL_DEBUG=INFO`, under
+   another `--name`. Ready, answering, and `NET/IB` in both shards' logs.
+5. **Experts.** A mixture-of-experts model on one node's eight cards,
+   for instance `Qwen/Qwen3-235B-A22B-Instruct-2507-FP8`: its profile
+   carries `--enable-expert-parallel` (`llmgw ctl models`, or its
+   definition from the admin API).
+6. **A node lost.** With the two-node replica serving, stop one node's
+   agent (`systemctl stop llmgw-agent`): the replica fails and is placed
+   again once the node is back or another has room. Nothing is left
+   holding cards.
+
+For each, worth keeping:
+- the time from serve to ready;
+- tokens a second from `llmgw ctl bench`;
+- the plan's per-card figure against what `nvidia-smi` shows once loaded;
+- anything it said that was wrong.

docs/node-onboarding.md

@@ -0,0 +1,209 @@
+# Adding a node
+
+Written for whoever runs the cluster.
+
+## The short version
+
+On the control plane:
+
+```
+sudo llmgw node add ubuntu@10.0.0.145
+```
+
+That is all a machine that already exists needs — bare metal, or a VM you
+built. [install.md](install.md#5-adding-the-node) says what it does. On
+Proxmox, the machine itself can be built first by the script below, on the
+hypervisor.
+
+## The two halves
+
+Two scripts, because the two halves of onboarding are done by different people
+with different access: one needs the hypervisor, the other needs the
+certificate authority.
+
+## 1. The machine
+
+On the Proxmox host:
+
+```
+llmgw-provision-node --vmid 144 --name llmgw-node04 --ip 10.0.0.144/24
+```
+
+Name it after the node id. **The VM name, the hostname, the node id and the
+certificate's common name are all the same string.** They do not have to be, and
+every time they are not, somebody spends an afternoon working out which of the
+four a message is talking about.
+
+It imports a cloud image and lets cloud-init do the rest, which is why a node
+takes a minute rather than an afternoon. It refuses to touch an existing VMID:
+adopting a machine is not a decision a provisioning script should make.
+
+Releases carry static `linux/amd64` and `linux/arm64` binaries. Download one and
+pass it with `--binary` rather than copying whatever happens to be on the
+machine you are running onboarding from — otherwise whoever runs the script
+quietly becomes the build server, and the fleet ends up running whatever was in
+their working tree.
+
+## 2. The identity
+
+On the control plane, which holds the certificate authority — this is the
+part that cannot be delegated, because it issues the credential by which the
+control plane believes the node is who it says it is:
+
+```
+sudo llmgw node add ilker@10.0.0.144 --fabric ib-b:mlx5_0,mlx5_1
+```
+
+It checks the machine with `llmgw doctor`, issues a client certificate whose
+common name is the node id (the hostname), installs it along with the CA root,
+trusts that root system-wide, installs the binary and the unit, starts the
+agent, and waits for the node to join.
+
+If it does not join, the agent's log on the node says why. A certificate whose
+common name does not match the claimed node id is refused by design — that
+check is what makes a node's identity something it proves rather than
+something it picks.
+
+**It needs SSH from the control plane to the node.** Provisioning copies the
+hypervisor's `authorized_keys` into the new machine; with `ssh -A` to the
+control plane and `sudo --preserve-env=SSH_AUTH_SOCK`, the same key that
+reaches the hypervisor reaches the node.
+
+`deploy/bootstrap/onboard-node.sh` is the script this replaced, for a machine
+holding an authority but not a current llmgw.
+
+## The CPU model matters, and its default is wrong
+
+Nodes are provisioned with `--cpu host`. Proxmox's default, `kvm64`, hides
+AVX, AVX2, FMA and even SSE4.2 from the guest, and llama.cpp then loads its
+scalar backend instead of the one built for the host's instruction set.
+Measured on node05, an 8-core VM on a Xeon E5-2680 v4, same weights, same
+threads, the only change being the CPU model:
+
+| Qwen2.5-Coder  | kvm64 tok/s | host tok/s |
+| -------------- | ----------: | ---------: |
+| 1.5B q4_K_M    |        5.80 |      39.09 |
+| 3B q4_K_M      |        2.90 |      20.51 |
+| 7B q4_K_M      |        1.33 |       9.88 |
+
+Prompt processing is worse still: 7.6 tokens a second against 143.8, a factor
+of nineteen.
+
+It is worth calling out because nothing looks broken. The node registers, the
+engine starts, replies are correct — every number is simply small, and the
+obvious conclusion is that CPU inference is hopeless rather than that the VM
+cannot multiply efficiently.
+
+The trade is live migration: a VM pinned to the host CPU cannot move to a
+machine with a different one. For a node whose job is arithmetic that is the
+right way round, and `--cpu` overrides it where it is not.
+
+## Engines
+
+The script installs none, and does not need to: once the agent is connected,
+the control plane tells it which engines to have and it installs them itself
+— llama.cpp on every node, vLLM on every node with an NVIDIA GPU it can run
+on, SGLang where the control plane names a version. Each is checked to run
+before the node offers it, so a node never advertises an engine that cannot
+start. [install.md](install.md#engines) says what vLLM needs of the node.
+
+`--llamacpp-bin`, `--vllm-bin` and `--sglang-python` are for an engine you
+installed yourself. For the agent to use yours rather than install its own,
+also set that engine's version to `""` under `engines` in `server.yaml`.
+
+Weights are the other thing a node needs. llmgw fetches them for a model whose
+`source` is a URL, one copy per node, which covers the simple case; anything
+larger — a shared filesystem, a cache — stays the operator's arrangement, and
+llmgw is content to find the files already there.
+
+The `sim` engine needs neither, which is what makes it useful for exercising
+everything else.
+
+## Checking an engine after an upgrade
+
+Engines rename and remove flags between versions, and when that happens the
+failure arrives minutes into a model load, in the engine's own error message, on
+a node nobody was watching.
+
+```
+llmgw ctl engine-check vllm
+llmgw ctl engine-check llamacpp --help-output "$(llama-server --help 2>&1)"
+```
+
+It builds the widest command llmgw would ever produce — a multi-node one, since
+a flag that only appears there is exactly the one nobody notices has gone — and
+checks every flag against the engine's own `--help`. No GPU required: a CLI
+prints its help on any machine.
+
+Some programs do not give up their whole help for `--help`. vLLM prints a
+summary of section names and expects `--help=all`; checking against the summary
+reports every flag as missing, confidently and wrongly. `engine-check` knows
+that one. If you add an engine, check that what you get back is the full list.
+
+vLLM also refuses to do anything at all on a machine with no accelerator,
+including print its help, unless `VLLM_TARGET_DEVICE` says what to assume.
+`engine-check` sets it.
+
+Give it the **whole** help. Truncating llama.cpp's 725 lines to 400 reports five
+flags as missing that the running cluster uses; the command warns when the text
+it was given does not document `--help` itself, which is the cheapest sign it
+was cut short.
+
+## Fabrics
+
+`--fabric` is how a node says which InfiniBand fabric it is attached to. The
+name is checked against what the adapters report — every port on one fabric
+sees the same subnet managers — so two independent fabrics given one name are
+placed as two, and the cluster page says so; give each fabric its own name.
+The agent installs `infiniband-diags`, which that check needs, if it is missing.
+
+Before a node with a fabric joins, run `sudo llmgw doctor` on it: it checks the
+subnet manager, GPUDirect RDMA, the fabric manager and IMEX on NVLink machines,
+and the declared fabrics against the adapters. [fabrics.md](fabrics.md) has the
+rest.
+
+Omit it for a node with no fabric. Such a node is its own island: it can host
+single-node replicas and will never be given a multi-node one.
+
+Two adapters per fabric is the default; `--fabric ib-b:mlx5_2,mlx5_3` names them
+explicitly. An adapter must never appear under two fabrics — the agent refuses
+that configuration: a replica given adapters on two fabrics starts, passes its
+health checks, and hangs on its first all-reduce.
+
+## Where the driver is
+
+```
+--nvidia-smi /opt/nvidia/bin/nvidia-smi
+--ib-root /sys/class/infiniband
+```
+
+Both default to the usual places. Containerized driver installs routinely put
+`nvidia-smi` somewhere else, and an agent that cannot find it registers with no
+GPUs — which looks exactly like a node that has none.
+
+## Removing a node
+
+```
+llmgw ctl drain llmgw-node04     # move its replicas off, one at a time
+llmgw ctl nodes                  # wait until it holds none
+```
+
+Then stop the agent. Draining brings each replacement up before stopping the
+original, which is the difference between a rolling move and an outage.
+
+The node's certificate stays valid until it expires. There is no revocation list
+— if a machine is decommissioned rather than retired, reissue the authority or
+accept that a certificate naming a node that no longer exists can still connect
+and claim to be it.
+
+## Testing without hardware
+
+Every part of this works on machines with no GPUs and no InfiniBand. Point
+`--nvidia-smi` at a script that prints the CSV discovery asks for, point
+`--ib-root` at a sysfs-shaped directory, and use `engine: sim` in the catalog.
+
+The simulated engine rendezvouses for real: rank 0 binds the dist-init port and
+does not serve until every worker has joined, and workers serve nothing. That
+exercises the multi-node launch sequence, the fabric constraint, and failure and
+rebuild — which is most of what goes wrong — without exercising NCCL, which is
+the rest.

docs/onboarding.md

@@ -0,0 +1,545 @@
+# Onboarding a user
+
+Written for whoever operates an llmgw deployment: the person with a shell on the
+control plane machine.
+
+There are two ways a person gets a key. Pick one and put it in the config.
+
+| | Self-service | Operator-issued |
+|---|---|---|
+| Config | `auth.signup_open: true` | `auth.signup_open: false` |
+| They do | sign up, wait, then make their own keys | wait for a link |
+| You do | approve once | issue every key |
+| Good for | more than a handful of people | a few, or machines |
+
+Self-service does not mean open. A signup produces an account that can do
+nothing at all; **approval is what makes it work**, and approval needs a shell
+here rather than a session cookie, because it is the step that decides who gets
+to spend the cluster.
+
+Everything below runs as the user the server runs as, so the files it creates
+stay readable by it:
+
+```
+sudo -u llmgw llmgw <command> --store /var/lib/llmgw/llmgw.db
+```
+
+## Self-service
+
+Turn on the form:
+
+```yaml
+auth:
+  enabled: true
+  store: /var/lib/llmgw/llmgw.db
+  signup_open: true
+```
+
+The landing page then links to it, and the rest is:
+
+```
+llmgw users list --pending --store …
+ID          EMAIL              STATE    ADMIN  MEMBER OF     SIGNED UP
+usr-k4mq…   ayse@example.com   pending  -      on their own  4m12s ago
+
+llmgw users approve ayse@example.com --by ilker --store …
+llmgw users approve ayse@example.com --project Acme/ml/training --store …   # or straight into a project
+```
+
+That is the whole operator loop. From then on they sign in at `/login`, and
+their account page (`/profile`) is where they create keys, see when each was
+last used, revoke the ones they are done with, and see their own use over the
+last thirty days against every budget that applies to them. A key is shown once
+on the page that creates it and never again.
+
+### Connecting an editor
+
+The account page's **Connect your editor** makes a key for VS Code, Continue,
+Codex or Cline and shows what the tool needs with that key, this gateway's
+address and a model already in it:
+
+- **VS Code** — llmgw's own extension, downloaded from the gateway at
+  `/setup/vscode/llmgw.vsix` with this gateway's address already in it. It
+  offers every chat model the key may use to VS Code itself: the chat's model
+  picker, agent mode, and any extension that asks VS Code for a language model
+  (Cline's "VS Code LM API" provider among them), with no setup of their own.
+  **llmgw: Sign In** in VS Code opens this page with VS Code chosen; the page's
+  **Open in VS Code** link hands the key back, and the extension keeps it in
+  VS Code's secret storage. A link the extension did not ask for is confirmed
+  first, with the gateway's address shown, since it decides where code is sent.
+  **llmgw: Enter API Key** takes a pasted one instead.
+- **Continue** — an assistant file of its own, `~/.continue/assistants/llmgw.yaml`,
+  so their `config.yaml` is not touched.
+- **Codex** — a provider and a profile in `~/.codex/config.toml`, run with
+  `codex --profile llmgw`; their default model stays as it was. Codex speaks the
+  Responses API, which the gateway translates at `/v1/responses`.
+- **Cline** — four settings to paste into its own screen, since it keeps them
+  in VS Code's secret storage where no file reaches.
+- **Claude Code** — not on the page yet; it speaks Anthropic's Messages API,
+  which the gateway translates at `/v1/messages`:
+  `ANTHROPIC_BASE_URL=https://<gateway> ANTHROPIC_AUTH_TOKEN=<key>
+  ANTHROPIC_MODEL=<model> ANTHROPIC_SMALL_FAST_MODEL=<model> claude`. It
+  needs a model that calls tools well.
+
+For Continue and Codex there is a one-line command,
+`curl -fsSL <gateway>/setup/<tool>?model=… | sh`. Its script is served without
+signing in and holds no secret — the key comes from the environment — and it
+keeps a copy of anything it replaces. Revoking the key disconnects the tool.
+
+How well an editor's agent mode works depends on the model: it needs one that
+calls tools well, which the coder models do and small general ones often do not.
+
+**This gateway sends no email.** There is no "your account was approved" message
+and no password reset, so tell people what to expect: they sign up, they tell
+you, you approve, they sign in. If that loop is too manual for your size, it is
+the thing to automate — not the approval step.
+
+To close an account:
+
+```
+llmgw users suspend usr-k4mq… --store …
+```
+
+which closes their sessions immediately. Their **API keys keep working** — those
+are separate credentials, and revoking them is a separate step:
+
+```
+llmgw keys list --project default --store …
+llmgw keys revoke key-… --store …
+```
+
+That separation is deliberate: a suspended person's running jobs should not all
+fail at once without someone deciding they should.
+
+## Operator-issued
+
+With `signup_open: false` there is no form, and you issue keys yourself. This is
+also the path for things that are not people — CI, a notebook server, a script.
+
+### Decide where the key belongs
+
+Keys hang off a project, projects off a team, teams off an organization. Limits
+can be set at any of those levels and compose downward by taking the **most
+restrictive** value — a key cannot raise what its team set, and a team cannot
+raise what its organization set. That is the only rule under which a budget
+means anything.
+
+If you have no structure yet, one of each is fine:
+
+```
+llmgw org add org mynodes
+llmgw org add team default --in mynodes
+llmgw org add project default --in mynodes/default
+llmgw org tree --people
+```
+
+Everything that takes an organization, team or project — here, in `users` and
+in `keys` — accepts its id, its path (`mynodes/default/default`) or its name
+when the name is unique, so an id never has to be copied off a page. When there
+is only one project, `--project` can be left out.
+
+The tree is not fixed once made:
+
+```
+llmgw org rename project Acme/platform/gateway api-gateway
+llmgw org move project Acme/platform/gateway --to Scania/ml
+llmgw org remove team Acme/old                 # only when nothing is in it
+llmgw users delete ayse@example.com --yes      # signs out, revokes their keys
+llmgw keys list --all                          # every key, where it spends, and whose
+```
+
+A project that ever had a key cannot be removed, because usage history refers
+to it — rename it instead.
+
+### Where people belong
+
+A person can be a member of any number of organizations, teams and projects, or
+of none:
+
+```
+llmgw users join ayse@example.com --team Acme/ml          # every project in ml
+llmgw users join ayse@example.com --project Scania/research/vision
+llmgw users leave ayse@example.com --project Acme/ml/training
+```
+
+A member of a team or organization may use every project in it. Leaving revokes
+the keys the person made in projects they can no longer reach; a project they
+still reach through another membership keeps them.
+
+Someone who is a member of nothing still uses the gateway, on their own:
+personal keys, and the chat page, within their personal limits. When they make
+a key on `/profile` they choose what it spends against — one of their projects,
+or "Personal". An operator can do the same:
+
+```
+llmgw keys create laptop --for ayse@example.com                      # personal
+llmgw keys create ci --for ayse@example.com --project Acme/ml/training
+```
+
+Personal use can be limited by default, or turned off so people use the gateway
+only through their projects:
+
+```yaml
+auth:
+  personal:
+    rpm: 20
+    tpm: 50000
+    budget: 10        # whole units
+    period: month
+    # disabled: true
+```
+
+A personal key has no project, so it keeps no conversations or agent notes;
+those are kept per project.
+
+### Organization managers and admins
+
+A member of an organization can be made its manager, who sees it, or its
+admin, who also changes it:
+
+```
+llmgw users join boss@acme.com --org Acme --role manager
+llmgw users join lead@acme.com --org Acme --role admin
+```
+
+or with the role chosen on their organization membership on `/admin/users`.
+Both get an **Organization** link and a page at `/org`: usage over time by team,
+project or person, the teams and projects with their limits and spend, and every
+member. Only what was spent in that organization's projects is on it; what its
+people do elsewhere is not.
+
+A manager's page is read-only. An organization's admin also changes the
+organization from it:
+
+- adds and renames its teams and projects, and removes an empty one;
+- adds a person by their sign-in address to the organization, a team or a
+  project, and takes them out (their keys there are revoked with it);
+- makes a member of the organization a manager or an admin, or neither;
+- revokes a key spent in its projects.
+
+What reaches past the organization stays with the cluster's administrators:
+its limits and budgets, approving or suspending an account (someone not yet
+approved cannot be added), the organization's own name, and anything else on
+the cluster. An admin cannot take away their own role. A group from single
+sign-on or Active Directory that puts someone in the organization does not, by
+saying so again at the next sign-in, take a manager's or admin's role away.
+
+An administrator of the cluster following `/org` lands on the same
+organization's panel on the people page instead, where all of that can be
+changed.
+
+`llmgw keys init` still works for provisioning scripts and is idempotent, but it
+will no longer move a team or project that already exists under another parent;
+it says so and stops.
+
+Split it when you want separate limits or separate reporting, not before.
+
+### Issue the key as a one-time link
+
+```
+llmgw keys create --store … \
+  --project default \
+  --band gold \
+  --base-url https://llmgw.example \
+  --claim \
+  "ayse-laptop"
+
+https://llmgw.example/claim/3mKq…
+```
+
+Send the link, not the key.
+
+A key pasted into a chat window stays in that chat window forever, searchable by
+everyone who joins the channel later. A link works once and then expires, so the
+worst case is someone opening it before the intended person — which you find out
+about, because they will tell you the link is dead.
+
+The name is for you, not the user: it appears in `keys list` and is how you will
+know which key to revoke.
+
+**Why the link is safe to store.** The key is sealed with the link's own token,
+and the token is never written down — only its hash is. A database leak yields
+two useless hashes and a blob nothing in the database can open.
+
+Without `--claim` the key is printed to stdout instead, for when you are
+provisioning something that is not a person:
+
+```
+llmgw keys create --store … --project ci "github-runner" > /run/secrets/llmgw-key
+```
+
+## Limits
+
+Limits are optional. A key with none is unlimited, which is the right default on
+a private cluster and the wrong one the moment the gateway faces anything else.
+
+```
+# Everyone in this project
+llmgw keys limits --store … --scope project --id default \
+  --rpm 60 --tpm 200000
+
+# One key, tighter
+llmgw keys limits --store … --scope key --id key-mpmip77twpt7qaxc \
+  --rpm 10
+
+# Restrict which models
+llmgw keys limits --store … --scope project --id default \
+  --models qwen-0.5b,llama-3.3-70b
+```
+
+An **absent** model list permits everything. An **empty** one permits nothing —
+`--models ""` is a way to suspend a project without revoking its keys.
+
+Allowlists compose by intersection: a key cannot add a model its team withheld.
+A model's canonical name and any of its aliases name the same thing, so either
+form works.
+
+Budgets are given in whole units, as the Limits tab shows them, and what a unit
+means is yours to decide. Self-hosted models have no per-token price, so it can
+be GPU-seconds, a notional rate, or one unit per thousand tokens everywhere —
+a price of 1 000 000 in `auth.pricing`, which is in micro-units — and a budget
+becomes a plain quota of thousands of tokens.
+Models are priced in the server's `auth.pricing` section; a model priced at zero
+is exempt from budget checks, which is what lets a key with nothing left still be
+served a cheap fallback.
+
+```
+llmgw keys limits --store … --scope project --id Acme/platform/gateway \
+  --budget 50 --period month              # 50 units a month
+```
+
+Two more kinds of limit follow people rather than the tree:
+
+```
+# A person, everywhere: every key they hold, every project, the chat page
+llmgw keys limits --scope user --id ayse@example.com --budget 25
+
+# Each member of a project separately — a fair share, not one shared pool
+llmgw keys limits --scope project --id Acme/ml/training --per-member --rpm 20
+```
+
+A request is held to all of them at once: the key's own, its project's, team's
+and organization's, each per-member limit on those for its owner, and the
+owner's own. The strictest wins, and each is counted in its own pool.
+
+## The landing page
+
+Someone who reaches the gateway without a key sees the landing page. Tell it who
+to send them to, or it can only shrug:
+
+```yaml
+landing:
+  contact: "platform@example.com"   # or an https:// URL, or "#platform on Slack"
+  notice: "Internal use only."
+```
+
+An address becomes a mailto link, an `http(s)` URL stays a link, anything else is
+shown as text. Other schemes are never linked — configuration is not always
+written by whoever runs the gateway, and a `javascript:` href on a page served to
+every visitor is a short path to a stored XSS.
+
+## The docs portal
+
+The gateway also serves its manual at `/docs`: these pages, rendered, with
+[clients.md](clients.md) — how to use the gateway from the official OpenAI
+and Anthropic SDKs — first on its index. The landing page and the account
+page link to it, so a user's questions about streaming, tools or the Anthropic
+SDK have an answer that is not you.
+
+It is public, like the landing page. The client guide is for the person who
+has no account yet, and the operator documents describe llmgw in general —
+no address, model, node or key of this installation — which is what the
+project's repository publishes anyway. A site that would rather not say even
+that turns sign-in on:
+
+```yaml
+landing:
+  docs_sign_in: true
+```
+
+A visitor is then sent to sign in first. On a gateway with API keys and no
+accounts, the portal asks for a key instead, like the API.
+
+## What the user sees
+
+They open the link, press the button, and get the key once. The page shows them
+the base URL and a working `curl`, and points at two endpoints:
+
+- `GET /v1/models` — what this key may use
+- `GET /me` — its limits and what it has spent
+
+`/me` is there so nobody has to ask you "why was I rate limited" or "how much
+have I used". It is outside `/v1` because it is not part of the OpenAI API.
+
+## Rotation and revocation
+
+```
+llmgw keys list --store … --project default
+```
+
+`LAST USED` is written in batches rather than per request, so it lags by up to a
+minute. It is the column that tells you whether a key is still in use, which is
+what makes rotation safe:
+
+**To rotate**, `llmgw keys rotate <key-id> --overlap 48h` issues a new key with
+the same project, owner and limits and lets the old one work for the overlap,
+then stop. Watch `LAST USED` on the old one stop moving before it runs out.
+
+**To cap how long keys live**, `llmgw keys ttl project:Acme/ml/train 720h` (or
+`team:`, `org:`; `off` removes it), and `auth.max_key_ttl` in server.yaml for
+every key. A key is made within the shortest limit that applies, and one asked
+for without an expiry gets that limit. `keys list --all` shows each key's kind
+— service (a project's), member, personal — and when it expires.
+
+```
+llmgw keys revoke --store … key-mpmip77twpt7qaxc
+```
+
+Revocation is a soft delete: the key stops working, the row stays, and its usage
+history keeps its subject. A running server keeps accepting a revoked key until
+its cache expires — `auth.cache_ttl`, 30 seconds by default. That is the price of
+keeping the database off the request path, and it is the number to lower if you
+need revocation to bite faster.
+
+## Passwords
+
+People change their own from `/profile`. It asks for the current one — a session
+is what someone gets from a borrowed laptop, and the password is what they do not
+have — and it signs every other browser out, which is the point if they are
+changing it because something went wrong.
+
+Someone who has forgotten theirs follows **Forgotten your password?** on the
+sign-in page. With mail set up in the cluster's settings, a link to set a new one
+is mailed to their address — the page says the same whether or not the address
+has an account, so nobody can find out who does from it:
+
+```
+llmgw ctl config set mail '{smtp: smtp.example.com:587, from: llmgw@example.com,
+  username: llmgw, password_file: /etc/llmgw/secrets/smtp, base_url: https://llm.example.com}'
+```
+
+`base_url` is where the link points, and it is never taken from the request:
+otherwise a stranger could ask for someone's link from a page of their own. A
+link works once, for an hour, and a newer one replaces it.
+
+Without mail, the page says to ask an operator, who makes the link and hands it
+over however suits:
+
+```
+llmgw users reset-link ayse@example.com --store …    # --base-url without mail.base_url
+```
+
+Or sets a temporary password to give them, and has them change it from their
+profile:
+
+```
+llmgw users reset-password usr-k4mq… --password "a temporary passphrase" --store …
+```
+
+Either way their sessions are closed — if they lost the password, the reason
+might be that someone else has it. Their API keys keep working; those are
+separate credentials. People who sign in through single sign-on have no password
+here, and get no link.
+
+## Trying a model in the browser
+
+`/chat` is a playground for anyone signed in. It exists so somebody can see
+whether a model works without setting up a client, and — more often — so they
+can tell whether a problem is the gateway or their code.
+
+**The browser never holds a key.** The page carries a session; the server turns
+that into the same identity an API key would produce, resolved from the person's
+project, and the request goes down the ordinary path: admission, model
+allowlist, rate limits, budget, accounting. Anything else would make the page a
+hole in every limit the rest of the gateway enforces.
+
+Usage from the page is attributed to `session:<user-id>` rather than a key, so
+it is billed to the right project and visibly did not come from a credential
+somebody holds. One turn is capped at 512 tokens: a playground should not be the
+thing that ties up a replica for ten minutes, and anyone who wants a longer
+answer has an API key for that.
+
+Nothing is stored. The conversation lives in the page and is gone when it is
+closed.
+
+## Seeing the cluster
+
+The dashboard — nodes, replicas, models, why something did not get placed, usage
+per key — is served twice, and the difference matters.
+
+On the **admin listener** (`127.0.0.1:9090` by default) it needs no
+authentication: having a shell on the machine is the credential.
+
+```
+ssh -L 9090:127.0.0.1:9090 <control-plane>   # then http://127.0.0.1:9090/
+```
+
+That listener also serves pprof, which can dump the process heap — where API
+keys sit in plaintext. **Never expose that port.** It is bound to loopback for
+that reason.
+
+On the **client-facing port** the same page is at `/admin`, behind a session and
+an admin flag, so it can be reached from a browser without the port carrying
+pprof along with it:
+
+```
+llmgw users promote usr-k4mq… --store …
+```
+
+Someone without the flag gets a 404 rather than a 403, because 403 confirms the
+page exists.
+
+## Managing accounts from the browser
+
+`/admin/users` is the tree: organizations, teams and projects, each project
+opening onto its members and its keys. From there an admin approves people
+(into a project or on their own), adds them to and takes them out of
+organizations, teams and projects, suspends and removes them, revokes keys, and
+adds, renames, moves and removes organizations, teams and projects. A
+searchable list of every account is at the bottom. Choosing any organization,
+team, project or person opens a panel beside the tree with its limits, its
+capacity quota and its use over the last week, and its limits can be changed
+there.
+
+The same page has two more tabs, each at the address it had as a page of its
+own: **Limits** (`/admin/quotas`) is every limit in the tree at once — per
+branch, per member of any part of it, and per person — with the capacity quotas;
+**Usage** (`/admin/usage`) is the cluster's use over time by organization, team,
+project or person, and the GPU time each owner held. The page works as plain
+forms; with scripts on, a change updates it in place and the projects you had
+open stay open.
+
+Three things are deliberately not there:
+
+| | Why |
+|---|---|
+| `llmgw users promote` | An admin who can make admins turns a stolen session into permanent access |
+| `llmgw users reset-password` | Setting someone's password is taking over their account |
+| `llmgw keys create` | Issuing a credential on another person's behalf |
+
+Each of those turns a stolen admin cookie into more than it was, and each is
+rare enough that a shell is no hardship. Cordon and drain are CLI-only for the
+same reason; what the pages do change on the cluster — serving models through
+the mirror, a node's engines — needs the `operator` or `admin` staff role.
+
+Every administrative change is recorded in the audit log — who, when, through
+what, the fields given with secrets taken out, and how it ended, refusals
+included: `llmgw ctl audit`, or **Audit** in the console.
+
+## What this does not do
+
+- **No email.** No approval notice, no self-service password reset, no address
+  verification. The loop is manual on purpose at this size; if it stops being
+  the right size, that is the thing to automate.
+- **Single sign-on is optional.** With `auth.oidc` people sign in through
+  your identity provider, and SCIM 2.0 (`auth.scim`) creates, updates and
+  suspends accounts from it; see [install.md](install.md#single-sign-on).
+  Without them accounts are local, with local passwords.
+- **Staff roles are coarse.** `viewer`, `operator`, `billing` and `admin`
+  (`llmgw users role`) decide what someone may see and do under /admin, and a
+  page draws only the forms that person may send: a viewer sees no forms. An
+  organization's manager can view it; its admin also changes its teams,
+  projects, people and keys. Every change is in the audit log (`llmgw ctl
+  audit`).
+- **Rate limits are per gateway instance.** With two instances each counts its own,
+  so the effective limit doubles. v1 is single-instance by design.

docs/quick-install.md

@@ -0,0 +1,248 @@
+# Quick install
+
+From empty servers to a model answering requests, in six steps. This page
+has only the commands and what to check after each; [install.md](install.md)
+explains every choice.
+
+## What you need
+
+| | |
+|---|---|
+| **A control plane** | One machine, or three for high availability (the store replicated, either one able to take over). Linux, x86-64 or ARM64: Debian 12, Ubuntu 22.04+ or RHEL 10. No GPU needed; 2 GB RAM, 20 GB disk each — 12 GB RAM when it is also a node running the starter model and the two judges, which setup checks before it installs anything; four cores or more, or the judges on machines of their own, keep a judgment within its wait. |
+| **GPU nodes** (optional to start) | The same Linux, with the NVIDIA driver installed. vLLM needs driver 525 or newer and a Turing GPU or newer; a V100 gets an older vLLM. |
+| **root** | on the control plane. On the other two of a three-machine setup, `sudo` (its password is asked for if it needs one); on nodes, `sudo` without a password. |
+| **SSH** | from the control plane to the other machines. The setup screens take a key, the ssh agent or a password; `node add` uses ssh keys. A machine nothing may log into joins with a code instead (`llmgw join`). |
+| **Network** | nodes reach the control plane on 7443 and 8081; users reach it on 8080. The machines need internet access to download engines and models. |
+
+You do not install llama.cpp, vLLM, Python or CUDA. The nodes do that
+themselves once they join.
+
+## 1. Put llmgw on the control plane
+
+```
+VERSION=$(curl -fsSL https://gitea.mynodes.xyz/api/v1/repos/ilker/llmgw/releases/latest \
+  | grep -o '"tag_name":"[^"]*"' | cut -d'"' -f4)
+U=https://gitea.mynodes.xyz/ilker/llmgw/releases/download/$VERSION
+curl -fsSLO $U/llmgw-$VERSION-linux-amd64          # -linux-arm64 on ARM
+curl -fsSL $U/checksums.txt | sha256sum -c --ignore-missing
+sudo install -m0755 llmgw-$VERSION-linux-amd64 /usr/local/bin/llmgw
+llmgw --version
+```
+
+`sha256sum` must print `OK`. If it does not, the download is damaged; do not
+install it.
+
+## 2. Set up the control plane
+
+```
+sudo llmgw
+```
+
+With nothing installed, `llmgw` opens the setup screens. They ask whether
+this is **one machine or three** (high availability), and for three, the
+other two: address, user, and an ssh key, the ssh agent or a password. They
+check every machine before installing anything — system, disk, clock, ports,
+internet, whether the machines reach one another — show the plan, and
+install:
+
+- the service, its certificates and its configuration, and a firewall for
+  its internal ports;
+- with three machines, the store replicated across them (PostgreSQL under
+  Patroni);
+- your administrator account. **The password is shown once. Copy it now.**
+- a model mirror, which downloads model files once for the whole cluster;
+- this machine as a first node, and a small model (Qwen2.5 0.5B) on it;
+- guardrails on every request, with a judge model (Qwen3Guard-Gen 0.6B, two
+  replicas) on CPUs — a request it cannot check is refused, not let through — and API keys that expire within 90 days. What is hardened, and how
+  to loosen it: [install.md](install.md#2-the-control-plane).
+
+Run again later, `sudo llmgw` is the console: the cluster's state and
+everything you can do to it ([console.md](console.md)). Every step below is
+also there, under **Do**.
+
+**In a script**, the same for one machine:
+
+```
+sudo llmgw server init --admin you@example.com
+```
+
+If nodes will reach this machine by a name or address it does not know itself
+(a DNS name, a NAT address), add `--host` for each:
+`--host llm.example.com`. It is safe to run again: it keeps what exists and
+finishes what is missing.
+
+**The mirror on its own machine**, when it wants a larger disk than the
+control plane has: first on that machine, with llmgw installed as in step 1,
+
+```
+sudo llmgw mirror init --control-plane <control plane address>
+```
+
+then on the control plane `sudo llmgw server init --mirror http://<mirror
+address>:8082`. The mirror serves model files to every node, and takes
+orders only from the control plane. Untick "This machine as a node" in the
+form (or add `--no-node`) to keep models off the control plane; the starter
+model then starts on the first node you add.
+
+**Check:** open `http://<control-plane>:8080/chat`, sign in with the printed
+password, and ask something. The small model answers. Change the password on
+the account page.
+
+## 3. Add the GPU nodes
+
+In the console, **Do → Add a node**. Or on the control plane:
+
+```
+sudo llmgw node add ubuntu@10.0.0.21
+```
+
+Several at once: `sudo llmgw node add ubuntu@10.0.0.21 ubuntu@10.0.0.22 ubuntu@10.0.0.23`.
+
+Replace `ubuntu` with the user you log in to the node as, and `10.0.0.21` with
+its address. That user needs `sudo` without a password on the node.
+
+It logs in over SSH and, while you watch:
+
+1. installs llmgw on the node, the release for its processor, checksum checked;
+2. runs `llmgw doctor` there, and stops if the node has a problem. Each problem
+   comes with the command that fixes it. Fix it and run the same command again;
+3. gives the node its certificate and configuration, and starts its agent;
+4. waits for the node to join and install llama.cpp.
+
+The node's name in the cluster is its hostname. vLLM installs by itself after
+that, in a few more minutes on a GPU node (about 8 GB). The cluster page
+(`/admin`) shows its progress, or why the node cannot run it.
+
+**InfiniBand.** When the node's adapters are up, `node add` shows them grouped
+by the fabric they are on and asks for each fabric's name. Give every node on
+the same fabric the same name. In a script, give it instead:
+
+```
+sudo llmgw node add ubuntu@10.0.0.21 --fabric ib-a:mlx5_0,mlx5_1,mlx5_2,mlx5_3
+```
+
+Once two nodes on a fabric are in, check they reach each other at the link's
+rate before placing anything across them:
+
+```
+llmgw ctl fabric-test gpu01 gpu02
+```
+
+**If it cannot log in.** `sudo` runs SSH as root, with root's keys. To use your
+own keys instead, log in to the control plane with `ssh -A` and keep your
+agent through sudo:
+
+```
+sudo --preserve-env=SSH_AUTH_SOCK llmgw node add ubuntu@10.0.0.21
+```
+
+**Check:** `llmgw ctl nodes` lists the node. Running `node add` again on the
+same node is safe: it renews its certificate and configuration, and keeps what
+runs there.
+
+A machine retired for good is removed with `llmgw node remove <name>` once its
+agent is stopped.
+
+## 4. Add a model
+
+Open `/admin/mirror` and choose **Explore models**. It lists what is popular on
+Hugging Face, showing only what your nodes can run: judged by the cluster as it
+is now — the largest card and its compute capability, the most memory on one
+node — so a model too big for them, in a form those cards lack (FP8 needs 8.9),
+or in neither GGUF nor safetensors is left out, and the page says how many.
+Without GPUs it lists GGUF only. Untick **only what these nodes can run** to
+see everything. On a model's page a file too big for the cluster is shown
+without a **Fetch** button, with what it would need.
+
+The **CPU tok/s** column is about how fast one reply would come on the CPU of
+the fastest node whose memory holds the model at Q4_K_M; a model's page gives
+it for each GGUF file by its own size. Every node's agent measures how fast its
+memory reads when it starts (it is in the agent's log as `memory_gbs`), and a
+token on a CPU reads every weight once: the estimate is that speed over the
+model's size — for a model of experts named like `30B-A3B`, its active part.
+On the test cluster it came within 15% of what llama.cpp measured. Several
+replies at once share the reads and each is slower.
+
+**GPU tok/s** is the same on the cards, for the layout this cluster would
+give the model — the fewest cards that hold it, of each class, the fastest of
+those; its tooltip says which ("2× h100-80g, NVLink, vLLM", "2 nodes × 1×
+a100-80g over ib0 (InfiniBand 200 Gb/s), vLLM"). A card's memory bandwidth is
+known from its model name (an H100 SXM and an H100 PCIe differ by half); a card
+not in the table gets no figure. Tensor parallel across a node's cards divides
+what each reads, and adds two all-reduces a layer, short over NVLink and
+longer over PCIe; llama.cpp across cards splits by layer, so the cards take
+turns and a reply is no faster than on one; a pipeline across nodes takes turns
+too, and adds a hop over the fabric for each node. One card's figures were
+measured on the test cluster's RTX 6000; tensor parallel and the fabric are
+from what NCCL is known to take, not measured here.
+
+1. Click a model to read its card.
+2. Pick one of its files, usually a `q4_k_m` for a first try, and click
+   **Fetch**. It is downloaded into the mirror once, for every node.
+3. When the download finishes, click **serve** on its row in the table above.
+4. In the form, choose how it runs: **always on**, or **on demand**, which
+   loads it on the first request and stops it after 15 minutes unused. Click
+   **Add to the catalog**.
+
+The model is placed on a node that fits it, and its status on `/admin` turns
+`ready`.
+
+**Check:** the model appears in the list on `/chat`. Ask it something.
+
+## 5. Give people access
+
+**A key for a program:** each person makes their own on the account page
+(`/profile`). The key is shown once.
+
+```
+curl http://<control-plane>:8080/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "messages": [{"role": "user", "content": "hello"}]}'
+```
+
+Any OpenAI client works. Only the base URL changes:
+`http://<control-plane>:8080/v1`.
+
+**An editor:** the account page connects Continue, Codex or Cline. Pick the
+tool and a model, and it gives a one-line command that writes the
+configuration.
+
+**Other people's accounts:** they sign up at `/signup`, and you approve them on
+the people page (`/admin/users`).
+
+## 6. Put it behind HTTPS
+
+Port 8080 is plain HTTP. Before users outside a trusted network use it, put a
+reverse proxy in front with a real certificate. With Caddy, which gets the
+certificate by itself:
+
+```
+sudo apt-get install -y caddy          # Debian and Ubuntu
+curl -fsSL $U/Caddyfile | sed 's/llm.example.com/YOUR.DOMAIN/' | sudo tee /etc/caddy/Caddyfile
+sudo systemctl reload caddy
+```
+
+Keep 7443 (nodes) and 8081 (mirror) on the internal network. They never go
+through the proxy. There is an nginx configuration too:
+[deploy/proxy/](../deploy/proxy/).
+
+## When something does not work
+
+| What you see | What to do |
+|---|---|
+| `node add` stops at `join` | `sudo journalctl -u llmgw-agent -n 50` on the node. Usually it cannot reach port 7443 on the control plane. |
+| `node add` says the address is not in the certificate | Run `sudo llmgw server init --host <that address>`, then `node add` again. |
+| A node says it cannot run vLLM | The reason is on `/admin`: the driver is older than 580, the GPU is older than Turing, or there is less than 25 GB free. |
+| A model shows `not placed` | `llmgw ctl explain-placement <model>` names each node and why it was not used. |
+| A reply stops after 60 seconds behind nginx | Use the nginx configuration from the release. Its timeouts are set for slow models. |
+| Anything else about a node | `sudo llmgw doctor` on it. `--json` writes everything it read, to send to whoever helps you. |
+
+## Next
+
+- [install.md](install.md): the same steps with every option explained, and
+  running the cluster after: monitoring, notifications, single sign-on,
+  backups, upgrades.
+- [console.md](console.md): everything the console does.
+- [fabrics.md](fabrics.md): InfiniBand and NVLink.
+- [onboarding.md](onboarding.md): accounts, projects, budgets and keys.

go.mod

@@ -1,17 +1,101 @@
 module gitea.mynodes.xyz/ilker/llmgw
 
-go 1.26.3
+go 1.26.6
 
 require (
+	connectrpc.com/connect v1.21.0
+	filippo.io/age v1.3.2
+	github.com/NVIDIA/go-nvml v0.13.4-0
+	github.com/cespare/xxhash/v2 v2.3.0
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/charmbracelet/x/ansi v0.11.6
+	github.com/coreos/go-oidc/v3 v3.21.0
+	github.com/go-jose/go-jose/v4 v4.1.4
+	github.com/go-ldap/ldap/v3 v3.4.15
+	github.com/go-zeromq/zmq4 v0.17.0
+	github.com/jackc/pgx/v5 v5.11.0
+	github.com/knadh/koanf/parsers/yaml v1.1.1
+	github.com/knadh/koanf/providers/env/v2 v2.0.1
+	github.com/knadh/koanf/providers/file v1.2.1
+	github.com/knadh/koanf/v2 v2.3.6
+	github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0
+	github.com/mattn/go-isatty v0.0.24
+	github.com/prometheus/client_golang v1.24.1
+	github.com/prometheus/client_model v0.6.3
 	github.com/prometheus/common v0.71.0
 	github.com/spf13/cobra v1.10.2
+	github.com/vmihailenco/msgpack/v5 v5.4.1
+	github.com/yuin/goldmark v1.8.6
+	go.opentelemetry.io/otel v1.46.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0
+	go.opentelemetry.io/otel/sdk v1.46.0
+	go.opentelemetry.io/otel/trace v1.46.0
+	go.yaml.in/yaml/v3 v3.0.5
+	golang.org/x/crypto v0.57.0
+	golang.org/x/net v0.59.0
+	golang.org/x/oauth2 v0.37.0
+	golang.org/x/sync v0.23.0
+	golang.org/x/sys v0.48.0
+	golang.org/x/term v0.46.0
+	golang.org/x/text v0.42.0
+	google.golang.org/protobuf v1.36.12
+	modernc.org/sqlite v1.59.0
 )
 
 require (
-	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	filippo.io/edwards25519 v1.2.0 // indirect
+	filippo.io/hpke v0.4.0 // indirect
+	github.com/Azure/go-ntlmssp v0.1.1 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
+	github.com/charmbracelet/colorprofile v0.4.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.9.0 // indirect
+	github.com/clipperhouse/stringish v0.1.1 // indirect
+	github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-asn1-ber/asn1-ber v1.5.8 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/go-zeromq/goczmq/v4 v4.2.2 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/knadh/koanf/maps v0.1.2 // indirect
+	github.com/kylelemons/godebug v1.1.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.19 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
-	github.com/prometheus/client_model v0.6.3 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
-	google.golang.org/protobuf v1.36.12 // indirect
+	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0 // indirect
+	go.opentelemetry.io/otel/metric v1.46.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.11.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688 // indirect
+	google.golang.org/grpc v1.83.1 // indirect
+	modernc.org/libc v1.75.7 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.12.1 // indirect
 )

go.sum

@@ -1,30 +1,260 @@
+c2sp.org/CCTV/age v0.0.0-20260829155415-4448f2097b2d h1:Blprhc2SbChNZtWcU+BLTM4YdoqYAS9V7cJgOwJKyAs=
+c2sp.org/CCTV/age v0.0.0-20260829155415-4448f2097b2d/go.mod h1:SrHC2C7r5GkDk8R+NFVzYy/sdj0Ypg9htaPXQq5Cqeo=
+connectrpc.com/connect v1.21.0 h1:LhqSJt7jHf5NJBo9Jq/t/9FjcYAideif0mg+qe2jCUs=
+connectrpc.com/connect v1.21.0/go.mod h1:A2ygJrukXwWy32vkCAAHNVguZrqZ+jeZ9rGRnGR4dN4=
+filippo.io/age v1.3.2 h1:r6RSZLFSMm6rzKepZ7ZAYkKCu14f3/Me8c7uKYh7C8c=
+filippo.io/age v1.3.2/go.mod h1:TH/Yr2sSRhCKbaH4XPxpUV0Us8Gv6txYUpiZQWz8Evk=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
+filippo.io/hpke v0.4.0 h1:p575VVQ6ted4pL+it6M00V/f2qTZITO0zgmdKCkd5+A=
+filippo.io/hpke v0.4.0/go.mod h1:EmAN849/P3qdeK+PCMkDpDm83vRHM5cDipBJ8xbQLVY=
+github.com/Azure/go-ntlmssp v0.1.1 h1:l+FM/EEMb0U9QZE7mKNEDw5Mu3mFiaa2GKOoTSsNDPw=
+github.com/Azure/go-ntlmssp v0.1.1/go.mod h1:NYqdhxd/8aAct/s4qSYZEerdPuH1liG2/X9DiVTbhpk=
+github.com/NVIDIA/go-nvml v0.13.4-0 h1:o3jp9u2x1R9ShFE3v+Aesp55XOSIQFMJz/VGNUcJaNE=
+github.com/NVIDIA/go-nvml v0.13.4-0/go.mod h1:id63qwpoDWpFXwnwM6psDCSqW4BmNu6mWpr4YeQtPGo=
+github.com/alexbrainman/sspi v0.0.0-20250919150558-7d374ff0d59e h1:4dAU9FXIyQktpoUAgOJK3OTFc/xug0PCXYCqU0FgDKI=
+github.com/alexbrainman/sspi v0.0.0-20250919150558-7d374ff0d59e/go.mod h1:cEWa1LVoE5KvSD9ONXsZrj0z6KqySlCCNKHlLzbqAt4=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
+github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
+github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
+github.com/charmbracelet/colorprofile v0.4.1 h1:a1lO03qTrSIRaK8c3JRxJDZOvhvIeSco3ej+ngLk1kk=
+github.com/charmbracelet/colorprofile v0.4.1/go.mod h1:U1d9Dljmdf9DLegaJ0nGZNJvoXAhayhmidOdcBwAvKk=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
+github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
+github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
+github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/clipperhouse/displaywidth v0.9.0 h1:Qb4KOhYwRiN3viMv1v/3cTBlz3AcAZX3+y9OLhMtAtA=
+github.com/clipperhouse/displaywidth v0.9.0/go.mod h1:aCAAqTlh4GIVkhQnJpbL0T/WfcrJXHcj8C0yjYcjOZA=
+github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
+github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
+github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
+github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
+github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
+github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/go-asn1-ber/asn1-ber v1.5.8 h1:H9AZkK22UOmfX8J84ubyaZxKJZ3FMHVwn8swoMML7iQ=
+github.com/go-asn1-ber/asn1-ber v1.5.8/go.mod h1:hEBeB/ic+5LoWskz+yKT7vGhhPYkProFKoKdwZRWMe0=
+github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
+github.com/go-ldap/ldap/v3 v3.4.15 h1:eRB4f4Ecn1POL1mO86+uUDlecmyWsdiJwh60bAUS4UY=
+github.com/go-ldap/ldap/v3 v3.4.15/go.mod h1:jeD0c98EdZQCKKKKe4kTWs5aCf6y+j8KuYsYLznZSQk=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
+github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/go-zeromq/goczmq/v4 v4.2.2 h1:HAJN+i+3NW55ijMJJhk7oWxHKXgAuSBkoFfvr8bYj4U=
+github.com/go-zeromq/goczmq/v4 v4.2.2/go.mod h1:Sm/lxrfxP/Oxqs0tnHD6WAhwkWrx+S+1MRrKzcxoaYE=
+github.com/go-zeromq/zmq4 v0.17.0 h1:r12/XdqPeRbuaF4C3QZJeWCt7a5vpJbslDH1rTXF+Kc=
+github.com/go-zeromq/zmq4 v0.17.0/go.mod h1:EQxjJD92qKnrsVMzAnx62giD6uJIPi1dMGZ781iCDtY=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY=
+github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
+github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
+github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jcmturner/aescts/v2 v2.0.0 h1:9YKLH6ey7H4eDBXW8khjYslgyqG2xZikXP0EQFKrle8=
+github.com/jcmturner/aescts/v2 v2.0.0/go.mod h1:AiaICIRyfYg35RUkr8yESTqvSy7csK90qZ5xfvvsoNs=
+github.com/jcmturner/dnsutils/v2 v2.0.0 h1:lltnkeZGL0wILNvrNiVCR6Ro5PGU/SeBvVO/8c/iPbo=
+github.com/jcmturner/dnsutils/v2 v2.0.0/go.mod h1:b0TnjGOvI/n42bZa+hmXL+kFJZsFT7G4t3HTlQ184QM=
+github.com/jcmturner/gofork v1.7.6 h1:QH0l3hzAU1tfT3rZCnW5zXl+orbkNMMRGJfdJjHVETg=
+github.com/jcmturner/gofork v1.7.6/go.mod h1:1622LH6i/EZqLloHfE7IeZ0uEJwMSUyQ/nDd82IeqRo=
+github.com/jcmturner/goidentity/v6 v6.0.1 h1:VKnZd2oEIMorCTsFBnJWbExfNN7yZr3EhJAxwOkZg6o=
+github.com/jcmturner/goidentity/v6 v6.0.1/go.mod h1:X1YW3bgtvwAXju7V3LCIMpY0Gbxyjn/mY9zx4tFonSg=
+github.com/jcmturner/gokrb5/v8 v8.4.4 h1:x1Sv4HaTpepFkXbt2IkL29DXRf8sOfZXo8eRKh687T8=
+github.com/jcmturner/gokrb5/v8 v8.4.4/go.mod h1:1btQEpgT6k+unzCwX1KdWMEwPPkkgBtP+F6aCACiMrs=
+github.com/jcmturner/rpc/v2 v2.0.3 h1:7FXXj8Ti1IaVFpSAziCZWNzbNuZmnvw/i6CqLNdWfZY=
+github.com/jcmturner/rpc/v2 v2.0.3/go.mod h1:VUJYCIDm3PVOEHw8sgt091/20OJjskO/YJki3ELg/Hc=
+github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
+github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/knadh/koanf/maps v0.1.2 h1:RBfmAW5CnZT+PJ1CVc1QSJKf4Xu9kxfQgYVQSu8hpbo=
+github.com/knadh/koanf/maps v0.1.2/go.mod h1:npD/QZY3V6ghQDdcQzl1W4ICNVTkohC8E73eI2xW4yI=
+github.com/knadh/koanf/parsers/yaml v1.1.1 h1:u70vV5IyaM0HvONh8HoqBC97oTgO33KcpZbTLiKVinU=
+github.com/knadh/koanf/parsers/yaml v1.1.1/go.mod h1:HHmcHXUrp9cOPcuC+2wrr44GTUB0EC+PyfN3HZD9tFg=
+github.com/knadh/koanf/providers/env/v2 v2.0.1 h1:a3KagndPqhcWHQv6Pz4OZmwkI/yMeTjkiZye6ZCkyW0=
+github.com/knadh/koanf/providers/env/v2 v2.0.1/go.mod h1:1g01PE+Ve1gBfWNNw2wmULRP0tc8RJrjn5p2N/jNCIc=
+github.com/knadh/koanf/providers/file v1.2.1 h1:bEWbtQwYrA+W2DtdBrQWyXqJaJSG3KrP3AESOJYp9wM=
+github.com/knadh/koanf/providers/file v1.2.1/go.mod h1:bp1PM5f83Q+TOUu10J/0ApLBd9uIzg+n9UgthfY+nRA=
+github.com/knadh/koanf/v2 v2.3.6 h1:JoQPSJmvS4aP0xNc8xMDr5tcrkSEInL23/Il7pITAKo=
+github.com/knadh/koanf/v2 v2.3.6/go.mod h1:gRb40VRAbd4iJMYYD5IxZ6hfuopFcXBpc9bbQpZwo28=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0 h1:7Q+xNAZFmnfYOMweHN3c/PDFUKKfY1pVJ26K++QvVfU=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0/go.mod h1:1fEHWurg7pvf5SG6XNE5Q8UZmOwex51Mkx3SLhrW5B4=
+github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
+github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mitchellh/copystructure v1.2.0 h1:vpKXTN4ewci03Vljg/q9QvCGUDttBOGBIa15WveJJGw=
+github.com/mitchellh/copystructure v1.2.0/go.mod h1:qLl+cE2AmVv+CoeAwDPye/v+N2HKCj9FbZEVFJRxO9s=
+github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ=
+github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
-github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
-github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
+github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
 github.com/prometheus/client_model v0.6.3 h1:O0jaTVAYNxTHYInEPFJt5I3+sN8zqBtVMPTB1qyxiEo=
 github.com/prometheus/client_model v0.6.3/go.mod h1:gpN5P9S7Rr6Yr92PiQ+Ixvhf6JZEkF1dnxsYL2aPBEM=
 github.com/prometheus/common v0.71.0 h1:9KDAKb7Mj3HEVKyFCK6Dc/HIwlBzZIN2l7/lrHl3KK8=
 github.com/prometheus/common v0.71.0/go.mod h1:CLJ5H8TEsGX8bl31BdMkfhIZ+QmZ9tBPPotUxUbfcmk=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IUPn0Bjt8=
+github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
+github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
+github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.8.6 h1:d0VcaP1sx9GkFVkoW+KtggpGi2KZ965i14b0+bDQST4=
+github.com/yuin/goldmark v1.8.6/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.46.0 h1:FHt5/CDyVxi/8IM1CH7VE/rRgq3kLHa2mSTVMO8AWyc=
+go.opentelemetry.io/otel v1.46.0/go.mod h1:Gj3SEScelsNC45tp4nSxRYlS+f5iez7W8XPMCt905kE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0 h1:OFnwLJr+pF3iHrlGSzbxyuo6/6HyBlnlN1CWEJmBVcw=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0/go.mod h1:716wFneO0ov19A2beH5hjfh9AK5z/VWNAtDijp1Y0/g=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0 h1:KrC1YrQeSt46ITMWAbgQx1M1eV1/1TKzttrBzymPmss=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0/go.mod h1:zDSEzoEqsOrgBeGvH66KRgxh90VonFyJqBHA0Pk3+rM=
+go.opentelemetry.io/otel/metric v1.46.0 h1:yBnkXvgV7AXFILZc5K6IZe/CBFF3OS7BJ8ov6/lj0K8=
+go.opentelemetry.io/otel/metric v1.46.0/go.mod h1:iPmdWqifKUdzziPkvvzIJXITl56fQx2mGM/DHLB3/2o=
+go.opentelemetry.io/otel/sdk v1.46.0 h1:h5CNQQjEbuQXY/JfZtgt3i7HVFV3aHPO2OAwO2eTYPI=
+go.opentelemetry.io/otel/sdk v1.46.0/go.mod h1:GAERFXFt5SYCEB+YiKUbMBeza6UaDH7GmGOZEfh2gSM=
+go.opentelemetry.io/otel/sdk/metric v1.46.0 h1:0piZ26EG4RBfebb2jhDH6ERCYHoVWduc3kLgPCwSnSE=
+go.opentelemetry.io/otel/sdk/metric v1.46.0/go.mod h1:I1PbKrdVc8Qu8HYVDNtqVIwLwjNrhsV/uFuxfwg8mO4=
+go.opentelemetry.io/otel/trace v1.46.0 h1:OULy7ccdJnZtJ0UDYFOIGaCmiWzJ8Vi2G/Rsu60qs1c=
+go.opentelemetry.io/otel/trace v1.46.0/go.mod h1:J7GAXweO77XSFkB/rmAqk9D6ihszhFjLU+d9WuUxDLI=
+go.opentelemetry.io/proto/otlp v1.11.0 h1:5rrYs0Ykyj50sdU/JU0x8etU+LubXWb+gED6TbEdMIk=
+go.opentelemetry.io/proto/otlp v1.11.0/go.mod h1:SmVizdCOAm3XBtG1g1NnOdhW6jtddT72hLMhv8VwA8E=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
 go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
 go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
+golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
+golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues=
+golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
+golang.org/x/oauth2 v0.37.0 h1:JUlcxA8oAtauLfiH8FX2/FkAWHAdi0QtGCGc+hofE98=
+golang.org/x/oauth2 v0.37.0/go.mod h1:IxwZNxUULJmpBFf9K/9NTMSIfZZuvuTy1gGxhigP/58=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
+golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
+golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
+golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688 h1:ax2KzoSRIZU/M0cIxri3pKxy99vniH1PVxWC6si/eZI=
+google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688/go.mod h1:1RJ9BQGyNdZwkGc1eTqkErfRZ6RJyYPHZo73BZ1vQqI=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688 h1:cYNAzI2sUwhmCcoj9TxvihSrqsxt6uIkj3rDRhSDmW4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688/go.mod h1:DjtHYE8FKJLivXcBEjGwndXfIC23G0VpXiXKqG179uA=
+google.golang.org/grpc v1.83.1 h1:HIO0+BEtBP6soyqvqC8sNUjZ7bTs+0hFQuFF+RAy++Y=
+google.golang.org/grpc v1.83.1/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ=
 google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
 google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
+modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
+modernc.org/ccgo/v4 v4.35.0/go.mod h1:qrVGs9S3Sr2Ztcg9ve+kTAYMp5a3YvWjo+SoN06kJ5I=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.75.7 h1:o3DTP9/0p9pKmY2WCKQaySW6wIiZhNM7wc2lUoyhfew=
+modernc.org/libc v1.75.7/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.59.0 h1:X1es1GpqBlS/5T+vbM4HLUdaa8OtQx468DF2vrx+38A=
+modernc.org/sqlite v1.59.0/go.mod h1:+paeT2A3iPRHkQDwG7oA6Tk0zQd5woMEI8q7orfry8k=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

internal/account/account_test.go

@@ -0,0 +1,487 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+func newStore(t *testing.T) *store.DB {
+	t.Helper()
+	s, err := store.OpenSQLite(context.Background(), filepath.Join(t.TempDir(), "a.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+
+	ctx := context.Background()
+	for _, err := range []error{
+		s.PutOrg(ctx, store.Org{ID: "org", Name: "Org"}),
+		s.PutTeam(ctx, store.Team{ID: "team", OrgID: "org", Name: "Team"}),
+		s.PutProject(ctx, store.Project{ID: "proj", TeamID: "team", Name: "Proj"}),
+	} {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	return s
+}
+
+func newService(t *testing.T) (*Service, *store.DB) {
+	t.Helper()
+	s := newStore(t)
+	return New(s, DefaultConfig(), slog.New(slog.DiscardHandler)), s
+}
+
+const goodPassword = "correct horse battery staple"
+
+func TestSignupLeavesAnAccountWaiting(t *testing.T) {
+	// A public signup form that produced a working account would be a way in.
+	svc, st := newService(t)
+	ctx := context.Background()
+
+	if err := svc.SignUp(ctx, "Ayse@Example.COM", "Ayşe", goodPassword); err != nil {
+		t.Fatal(err)
+	}
+	u, err := st.UserByEmail(ctx, "ayse@example.com")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if u.State != store.UserPending {
+		t.Errorf("a new account is %q", u.State)
+	}
+	if u.Email != "ayse@example.com" {
+		t.Errorf("the address was not normalized: %q", u.Email)
+	}
+
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); !errors.Is(err, ErrNotApproved) {
+		t.Errorf("a pending account signed in: %v", err)
+	}
+}
+
+func TestSignupDoesNotRevealExistingAccounts(t *testing.T) {
+	// A form that says "this address already has an account" is an account
+	// enumerator anyone can run, and the person signing up learns nothing they
+	// need: either way they wait for approval.
+	svc, _ := newService(t)
+	ctx := context.Background()
+
+	if err := svc.SignUp(ctx, "ayse@example.com", "A", goodPassword); err != nil {
+		t.Fatal(err)
+	}
+	if err := svc.SignUp(ctx, "ayse@example.com", "Someone Else", goodPassword); err != nil {
+		t.Errorf("the second signup reported %v, which confirms the address is taken", err)
+	}
+}
+
+func TestApprovalIsWhatMakesAnAccountWork(t *testing.T) {
+	svc, st := newService(t)
+	ctx := context.Background()
+	must(t, svc.SignUp(ctx, "ayse@example.com", "A", goodPassword))
+
+	u, _ := st.UserByEmail(ctx, "ayse@example.com")
+	must(t, st.ApproveUser(ctx, u.ID, "proj", "ilker", time.Now()))
+
+	token, csrf, err := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if token == "" || csrf == "" {
+		t.Fatal("sign-in produced no session")
+	}
+	_, got, err := svc.Resolve(ctx, token)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ok, err := st.CanUseProject(ctx, got.ID, "proj"); err != nil || !ok {
+		t.Errorf("the approved account is not a member of the project it was approved into: %v", err)
+	}
+}
+
+func TestApprovalNeedNotNameAProject(t *testing.T) {
+	// A person need not belong to anything to use the gateway: approved into
+	// nothing, they work on their own within their personal limits.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	if err := st.ApproveUser(ctx, "usr-1", "", "ilker", time.Now()); err != nil {
+		t.Fatalf("approving with no project: %v", err)
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); err != nil {
+		t.Errorf("an account approved into nothing cannot sign in: %v", err)
+	}
+}
+
+func newStoreAndUser(t *testing.T) (*Service, *store.DB) {
+	t.Helper()
+	svc, st := newService(t)
+	hash, _ := HashPassword(goodPassword)
+	must(t, st.CreateUser(context.Background(), store.User{
+		ID: "usr-1", Email: "ayse@example.com", Name: "A",
+		PasswordHash: hash, State: store.UserPending, CreatedAt: time.Now(),
+	}))
+	return svc, st
+}
+
+func TestSuspensionTakesEffectOnOpenSessions(t *testing.T) {
+	// Leaving existing sessions open would make suspension advisory.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	token, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := svc.Resolve(ctx, token); err != nil {
+		t.Fatal(err)
+	}
+
+	must(t, st.SetUserState(ctx, "usr-1", store.UserSuspended))
+	if _, _, err := svc.Resolve(ctx, token); !errors.Is(err, store.ErrNoSession) {
+		t.Errorf("a suspended account kept its session: %v", err)
+	}
+}
+
+func TestSignOutEndsTheSession(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	token, _, _ := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	must(t, svc.SignOut(ctx, token))
+	if _, _, err := svc.Resolve(ctx, token); !errors.Is(err, store.ErrNoSession) {
+		t.Errorf("the session survived sign-out: %v", err)
+	}
+}
+
+func TestAWrongPasswordAndAMissingAccountAreIndistinguishable(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	_, _, wrong := svc.SignIn(ctx, "ayse@example.com", "wrong password here")
+	_, _, missing := svc.SignIn(ctx, "nobody@example.com", "wrong password here")
+	if !errors.Is(wrong, ErrBadCredentials) || !errors.Is(missing, ErrBadCredentials) {
+		t.Fatalf("wrong=%v missing=%v", wrong, missing)
+	}
+}
+
+func TestGuessingIsBounded(t *testing.T) {
+	// Without this a public login form is an open brute-force target.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	cfg := DefaultConfig()
+	cfg.MaxAttempts = 3
+	svc = New(st, cfg, slog.New(slog.DiscardHandler))
+
+	for i := range 3 {
+		if _, _, err := svc.SignIn(ctx, "ayse@example.com", "nope"); !errors.Is(err, ErrBadCredentials) {
+			t.Fatalf("attempt %d: %v", i, err)
+		}
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", "nope"); !errors.Is(err, ErrTooManyTries) {
+		t.Errorf("guessing was not bounded: %v", err)
+	}
+	// And a correct password is refused too while the window is open, or the
+	// limit would be trivially bypassed by interleaving.
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); !errors.Is(err, ErrTooManyTries) {
+		t.Errorf("the window did not apply to a correct password: %v", err)
+	}
+}
+
+func TestASuccessfulSignInClearsTheWindow(t *testing.T) {
+	// Otherwise a person who mistypes their password a few times is locked out
+	// for the rest of the window even after getting it right.
+	st := newStore(t)
+	hash, _ := HashPassword(goodPassword)
+	ctx := context.Background()
+	must(t, st.CreateUser(ctx, store.User{
+		ID: "usr-1", Email: "a@example.com", Name: "A",
+		PasswordHash: hash, State: store.UserPending, CreatedAt: time.Now(),
+	}))
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	cfg := DefaultConfig()
+	cfg.MaxAttempts = 3
+	svc := New(st, cfg, slog.New(slog.DiscardHandler))
+
+	for range 2 {
+		_, _, _ = svc.SignIn(ctx, "a@example.com", "nope")
+	}
+	if _, _, err := svc.SignIn(ctx, "a@example.com", goodPassword); err != nil {
+		t.Fatal(err)
+	}
+	for range 3 {
+		if _, _, err := svc.SignIn(ctx, "a@example.com", "nope"); errors.Is(err, ErrTooManyTries) {
+			t.Fatal("the window was not cleared by a successful sign-in")
+		}
+	}
+}
+
+func TestCSRFTokensAreCheckedAgainstTheSession(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	token, csrf, _ := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	sess, _, _ := svc.Resolve(ctx, token)
+
+	if !svc.CheckCSRF(sess, csrf) {
+		t.Error("the session's own token was rejected")
+	}
+	for _, bad := range []string{"", "wrong", csrf + "x", csrf[:len(csrf)-1]} {
+		if svc.CheckCSRF(sess, bad) {
+			t.Errorf("%q was accepted as a csrf token", bad)
+		}
+	}
+	// A token from another session must not work in this one.
+	other, otherCSRF, _ := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	_ = other
+	if svc.CheckCSRF(sess, otherCSRF) {
+		t.Error("another session's token was accepted")
+	}
+}
+
+func TestPasswordsAreHashedNotStored(t *testing.T) {
+	svc, st := newService(t)
+	ctx := context.Background()
+	must(t, svc.SignUp(ctx, "ayse@example.com", "A", goodPassword))
+
+	u, _ := st.UserByEmail(ctx, "ayse@example.com")
+	if strings.Contains(u.PasswordHash, goodPassword) {
+		t.Fatal("the password is in the database")
+	}
+	if !strings.HasPrefix(u.PasswordHash, "$argon2id$") {
+		t.Errorf("hash format: %q", u.PasswordHash)
+	}
+	ok, err := VerifyPassword(goodPassword, u.PasswordHash)
+	if err != nil || !ok {
+		t.Errorf("the hash does not verify: %v %v", ok, err)
+	}
+	if ok, _ := VerifyPassword("something else entirely", u.PasswordHash); ok {
+		t.Error("a wrong password verified")
+	}
+}
+
+func TestTwoHashesOfOnePasswordDiffer(t *testing.T) {
+	// A salt that did not vary would make the table a rainbow-table lookup.
+	a, _ := HashPassword(goodPassword)
+	b, _ := HashPassword(goodPassword)
+	if a == b {
+		t.Fatal("hashing is not salted")
+	}
+}
+
+func TestShortPasswordsAreRefused(t *testing.T) {
+	if _, err := HashPassword("short"); !errors.Is(err, ErrWeakPassword) {
+		t.Errorf("a five-character password was accepted: %v", err)
+	}
+	svc, _ := newService(t)
+	if err := svc.SignUp(context.Background(), "a@example.com", "A", "short"); !errors.Is(err, ErrWeakPassword) {
+		t.Errorf("signup accepted it: %v", err)
+	}
+}
+
+func TestMalformedHashesAreRejectedRatherThanMatched(t *testing.T) {
+	for _, bad := range []string{"", "plaintext", "$argon2id$", "$bcrypt$v=19$m=1,t=1,p=1$aa$bb"} {
+		if ok, err := VerifyPassword(goodPassword, bad); ok || err == nil {
+			t.Errorf("VerifyPassword(%q) = %v, %v", bad, ok, err)
+		}
+	}
+}
+
+func TestObviousNonAddressesAreRefused(t *testing.T) {
+	svc, _ := newService(t)
+	ctx := context.Background()
+	for _, bad := range []string{"", "ayse", "ayse@", "@example.com", "a b@example.com", "a@b", "a@@b.com"} {
+		if err := svc.SignUp(ctx, bad, "A", goodPassword); !errors.Is(err, ErrInvalidEmail) {
+			t.Errorf("SignUp(%q) = %v", bad, err)
+		}
+	}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestChangingAPasswordNeedsTheOldOne(t *testing.T) {
+	// A session is what an attacker gets from a borrowed laptop or a stolen
+	// cookie. The password is what they do not have, and without this check the
+	// first thing they would do is take the account.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+	u, _ := st.UserByID(ctx, "usr-1")
+
+	if err := svc.ChangePassword(ctx, st, u, "not the password", "a brand new passphrase"); !errors.Is(err, ErrBadCredentials) {
+		t.Errorf("a wrong current password was accepted: %v", err)
+	}
+	// And the old one still works.
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); err != nil {
+		t.Errorf("the password changed anyway: %v", err)
+	}
+}
+
+func TestChangingAPasswordSignsOutEverywhere(t *testing.T) {
+	// Leaving other sessions open would mean a password change does nothing
+	// about the reason someone is changing it.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	laptop, _, _ := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	phone, _, _ := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+
+	u, _ := st.UserByID(ctx, "usr-1")
+	must(t, svc.ChangePassword(ctx, st, u, goodPassword, "a brand new passphrase"))
+
+	for name, token := range map[string]string{"laptop": laptop, "phone": phone} {
+		if _, _, err := svc.Resolve(ctx, token); !errors.Is(err, store.ErrNoSession) {
+			t.Errorf("the %s session survived the change: %v", name, err)
+		}
+	}
+	// The new password works and the old one does not.
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", "a brand new passphrase"); err != nil {
+		t.Errorf("the new password does not work: %v", err)
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); !errors.Is(err, ErrBadCredentials) {
+		t.Errorf("the old password still works: %v", err)
+	}
+}
+
+func TestANewPasswordMustActuallyBeNew(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+	u, _ := st.UserByID(ctx, "usr-1")
+
+	if err := svc.ChangePassword(ctx, st, u, goodPassword, goodPassword); !errors.Is(err, ErrSamePassword) {
+		t.Errorf("changing a password to itself: %v", err)
+	}
+	if err := svc.ChangePassword(ctx, st, u, goodPassword, "short"); !errors.Is(err, ErrWeakPassword) {
+		t.Errorf("a short new password was accepted: %v", err)
+	}
+}
+
+func TestGuessingTheCurrentPasswordIsBounded(t *testing.T) {
+	// Someone with a stolen session should not get unlimited attempts at the
+	// password that would let them keep it.
+	st := newStore(t)
+	ctx := context.Background()
+	hash, _ := HashPassword(goodPassword)
+	must(t, st.CreateUser(ctx, store.User{
+		ID: "usr-1", Email: "a@example.com", Name: "A",
+		PasswordHash: hash, State: store.UserPending, CreatedAt: time.Now(),
+	}))
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+
+	cfg := DefaultConfig()
+	cfg.MaxAttempts = 3
+	svc := New(st, cfg, slog.New(slog.DiscardHandler))
+	u, _ := st.UserByID(ctx, "usr-1")
+
+	for range 3 {
+		_ = svc.ChangePassword(ctx, st, u, "wrong", "a brand new passphrase")
+	}
+	if err := svc.ChangePassword(ctx, st, u, "wrong", "a brand new passphrase"); !errors.Is(err, ErrTooManyTries) {
+		t.Errorf("guessing was unbounded: %v", err)
+	}
+}
+
+func TestSomebodyGuessingElsewhereCannotLockTheOwnerOut(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+	cfg := DefaultConfig()
+	cfg.MaxAttempts = 3
+	svc = New(st, cfg, slog.New(slog.DiscardHandler))
+
+	attacker, owner := WithClient(ctx, "203.0.113.9"), WithClient(ctx, "198.51.100.7")
+	for range 5 {
+		_, _, _ = svc.SignIn(attacker, "ayse@example.com", "nope")
+	}
+	if _, _, err := svc.SignIn(attacker, "ayse@example.com", "nope"); !errors.Is(err, ErrTooManyTries) {
+		t.Errorf("the guessing client was not held back: %v", err)
+	}
+	if _, _, err := svc.SignIn(owner, "ayse@example.com", goodPassword); err != nil {
+		t.Errorf("the owner, elsewhere, was locked out: %v", err)
+	}
+	// Spread over many clients, guessing is still bounded per address.
+	held := false
+	for i := range 40 {
+		c := WithClient(ctx, "192.0.2."+strings.Repeat("1", 1+i%3)+string(rune('0'+i%10)))
+		if _, _, err := svc.SignIn(c, "ayse@example.com", "nope"); errors.Is(err, ErrTooManyTries) {
+			held = true
+		}
+	}
+	if !held {
+		t.Error("guesses from many clients were not bounded")
+	}
+}
+
+func TestAHashThatCannotGetATurnSaysTheServerIsBusy(t *testing.T) {
+	was := argonWait
+	argonWait = 10 * time.Millisecond
+	t.Cleanup(func() { argonWait = was })
+	// Every turn taken.
+	n := cap(argonSlots)
+	for range n {
+		argonSlots <- struct{}{}
+	}
+	t.Cleanup(func() {
+		for range n {
+			<-argonSlots
+		}
+	})
+	if _, err := HashPassword(goodPassword); !errors.Is(err, ErrBusy) {
+		t.Errorf("a hash with no turn: %v", err)
+	}
+}
+
+func TestAForgottenPasswordIsResetOnceThroughALink(t *testing.T) {
+	svc, st := newService(t)
+	ctx := context.Background()
+	must(t, svc.SignUp(ctx, "ayse@example.com", "A", goodPassword))
+	u, _ := st.UserByEmail(ctx, "ayse@example.com")
+
+	// Waiting for approval: no link, said the same as for nobody.
+	if _, _, err := svc.RequestReset(ctx, st, "ayse@example.com"); !errors.Is(err, ErrNoReset) {
+		t.Fatalf("a pending account got a link: %v", err)
+	}
+	if _, _, err := svc.RequestReset(ctx, st, "nobody@example.com"); !errors.Is(err, ErrNoReset) {
+		t.Fatalf("an unknown address: %v", err)
+	}
+	must(t, st.ApproveUser(ctx, u.ID, "proj", "ilker", time.Now()))
+	session, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	must(t, err)
+
+	token, got, err := svc.RequestReset(ctx, st, "AYSE@example.com")
+	if err != nil || token == "" || got.ID != u.ID {
+		t.Fatalf("an active account: %q %+v %v", token, got, err)
+	}
+	if err := svc.ResetPassword(ctx, st, st, token, "short"); !errors.Is(err, ErrWeakPassword) {
+		t.Fatalf("a weak password: %v", err)
+	}
+	next := goodPassword + "-new"
+	must(t, svc.ResetPassword(ctx, st, st, token, next))
+	if _, _, err := svc.Resolve(ctx, session); err == nil {
+		t.Error("a session from before the reset still works")
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", next); err != nil {
+		t.Errorf("the new password does not sign in: %v", err)
+	}
+	if err := svc.ResetPassword(ctx, st, st, token, next+"2"); !errors.Is(err, ErrNoReset) {
+		t.Errorf("a link used twice: %v", err)
+	}
+}

internal/account/directory_test.go

@@ -0,0 +1,63 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+type fakeDirectory struct {
+	asked []string
+	u     store.User
+	err   error
+}
+
+func (f *fakeDirectory) SignIn(_ context.Context, login, _ string) (store.User, error) {
+	f.asked = append(f.asked, login)
+	return f.u, f.err
+}
+
+// With a directory, a name the store has no password for is the
+// directory's to check; an account with a password here — the
+// administrator init made — is still checked here, so a directory that is
+// down locks nobody out.
+func TestPasswordsKeptElsewhereAreTheDirectorysToCheck(t *testing.T) {
+	svc, st := newService(t)
+	ctx := t.Context()
+	hash, _ := HashPassword("local-secret")
+	admin := store.User{ID: "usr-admin", Email: "admin@example.com", Name: "a", PasswordHash: hash,
+		State: store.UserActive, CreatedAt: time.Now()}
+	ada := store.User{ID: "usr-ada", Email: "ada@corp.example", Name: "Ada", PasswordHash: "!ldap",
+		State: store.UserActive, CreatedAt: time.Now()}
+	for _, u := range []store.User{admin, ada} {
+		if err := st.CreateUser(ctx, u); err != nil {
+			t.Fatal(err)
+		}
+	}
+	dir := &fakeDirectory{u: ada}
+	svc.SetDirectory(dir)
+
+	if _, _, err := svc.SignIn(ctx, "admin@example.com", "local-secret"); err != nil || len(dir.asked) != 0 {
+		t.Fatalf("the local administrator: %v, directory asked %v", err, dir.asked)
+	}
+	// A name, not an address, and an account kept by the directory.
+	for _, login := range []string{`CORP\ada`, "ada@corp.example"} {
+		if tok, _, err := svc.SignIn(ctx, login, "ad-secret"); err != nil || tok == "" {
+			t.Errorf("%s: %v", login, err)
+		}
+	}
+	if len(dir.asked) != 2 || dir.asked[0] != `CORP\ada` {
+		t.Errorf("the directory was asked %v", dir.asked)
+	}
+	dir.err = ErrBadCredentials
+	if _, _, err := svc.SignIn(ctx, "ada", "wrong"); !errors.Is(err, ErrBadCredentials) {
+		t.Errorf("a password the directory refused: %v", err)
+	}
+	// A reset link would give a directory's account a password here.
+	if _, _, err := svc.RequestReset(ctx, st, "ada@corp.example"); !errors.Is(err, ErrNoReset) {
+		t.Errorf("a directory's account was sent a reset link: %v", err)
+	}
+}

internal/account/password.go

@@ -0,0 +1,144 @@
+// Package account is the human half of authentication: people sign up, an
+// operator approves them, and they issue their own API keys from a profile page
+// (plan §7.9).
+//
+// This is deliberately a different mechanism from the one in internal/auth.
+// That one authenticates machines holding 256-bit random keys; this one
+// authenticates people holding passwords they chose. The two have opposite
+// requirements — a fast hash is correct there and wrong here — and keeping them
+// apart is what stops one set of assumptions leaking into the other.
+package account
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"runtime"
+	"strings"
+	"time"
+
+	"golang.org/x/crypto/argon2"
+)
+
+// Argon2 parameters. OWASP's current floor for argon2id, which costs roughly
+// 50ms per attempt on ordinary hardware — slow enough to make an offline
+// dictionary attack expensive, fast enough that a login does not feel broken.
+//
+// They are stored with each hash, so raising them later leaves existing
+// passwords working until their owners next sign in.
+const (
+	argonTime    = 3
+	argonMemory  = 64 * 1024 // KiB
+	argonThreads = 4
+	argonKeyLen  = 32
+	saltLen      = 16
+)
+
+// MinPasswordLen is the only password rule.
+//
+// Length is the one requirement that reliably buys entropy. Composition rules —
+// a digit, a symbol, a capital — push people towards Password1! and produce
+// less entropy than they cost, so there are none.
+const MinPasswordLen = 12
+
+// ErrWeakPassword says a password is too short to accept.
+var ErrWeakPassword = fmt.Errorf("a password must be at least %d characters", MinPasswordLen)
+
+// ErrBadHash says a stored hash could not be parsed.
+var ErrBadHash = errors.New("unreadable password hash")
+
+// HashPassword derives a storable hash.
+func HashPassword(password string) (string, error) {
+	if len([]rune(password)) < MinPasswordLen {
+		return "", ErrWeakPassword
+	}
+	salt := make([]byte, saltLen)
+	if _, err := rand.Read(salt); err != nil {
+		return "", err
+	}
+	sum, err := idKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
+	if err != nil {
+		return "", err
+	}
+
+	b64 := base64.RawStdEncoding.EncodeToString
+	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
+		argon2.Version, argonMemory, argonTime, argonThreads, b64(salt), b64(sum)), nil
+}
+
+// VerifyPassword reports whether a password matches a stored hash.
+//
+// The comparison is constant time. The parameters come from the hash rather
+// than from the constants above, so a hash written under older settings still
+// verifies.
+func VerifyPassword(password, encoded string) (bool, error) {
+	parts := strings.Split(encoded, "$")
+	if len(parts) != 6 || parts[1] != "argon2id" {
+		return false, ErrBadHash
+	}
+
+	var version int
+	if _, err := fmt.Sscanf(parts[2], "v=%d", &version); err != nil || version != argon2.Version {
+		return false, ErrBadHash
+	}
+	var memory, time uint32
+	var threads uint8
+	if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &time, &threads); err != nil {
+		return false, ErrBadHash
+	}
+
+	salt, err := base64.RawStdEncoding.DecodeString(parts[4])
+	if err != nil {
+		return false, ErrBadHash
+	}
+	want, err := base64.RawStdEncoding.DecodeString(parts[5])
+	if err != nil {
+		return false, ErrBadHash
+	}
+
+	got, err := idKey([]byte(password), salt, time, memory, threads, uint32(len(want)))
+	if err != nil {
+		return false, err
+	}
+	return subtle.ConstantTimeCompare(got, want) == 1, nil
+}
+
+// dummyHash is verified against when no account matches, so a login attempt for
+// an address that does not exist costs the same time as one that does.
+//
+// Without it, a stopwatch enumerates every account on the system.
+var dummyHash string
+
+func init() {
+	h, err := HashPassword(strings.Repeat("x", MinPasswordLen))
+	if err != nil {
+		panic("account: cannot build the dummy hash: " + err.Error())
+	}
+	dummyHash = h
+}
+
+// argonSlots bounds how many hashes run at once. Each takes 64 MiB, and the
+// login and signup forms are on the client-facing port: without a bound, a
+// few hundred parallel attempts at random addresses asked for gigabytes at
+// once, and the per-address throttle does not see them — each address is new.
+// Beyond the bound, attempts wait their turn instead.
+var argonSlots = make(chan struct{}, max(2, runtime.NumCPU()/2))
+
+// ErrBusy is a hash that waited its turn too long: the server is answering
+// more sign-ins than it can hash, and says so rather than hold the request.
+var ErrBusy = errors.New("too many sign-ins at once; try again in a moment")
+
+// argonWait bounds the wait for a turn; a variable so a test can shorten it.
+var argonWait = 10 * time.Second
+
+func idKey(password, salt []byte, t, memory uint32, threads uint8, keyLen uint32) ([]byte, error) {
+	select {
+	case argonSlots <- struct{}{}:
+	case <-time.After(argonWait):
+		return nil, ErrBusy
+	}
+	defer func() { <-argonSlots }()
+	return argon2.IDKey(password, salt, t, memory, threads, keyLen), nil
+}

internal/account/service.go

@@ -0,0 +1,470 @@
+package account
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base32"
+	"errors"
+	"log/slog"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// What a sign-in or sign-up can fail with.
+var (
+	ErrBadCredentials = errors.New("that email and password do not match an account")
+	ErrNotApproved    = errors.New("this account is waiting for approval")
+	ErrSuspended      = errors.New("this account has been suspended")
+	ErrTooManyTries   = errors.New("too many attempts; try again shortly")
+	ErrInvalidEmail   = errors.New("that does not look like an email address")
+)
+
+// Store is what the service needs from persistence.
+type Store interface {
+	CreateUser(ctx context.Context, u store.User) error
+	UserByEmail(ctx context.Context, email string) (store.User, error)
+	UserByID(ctx context.Context, id string) (store.User, error)
+	TouchLogin(ctx context.Context, id string, at time.Time) error
+
+	CreateSession(ctx context.Context, userID, token, csrf string, ttl time.Duration) error
+	SessionByToken(ctx context.Context, token string) (store.Session, store.User, error)
+	DeleteSession(ctx context.Context, token string) error
+	TouchSession(ctx context.Context, token string, at time.Time) error
+}
+
+// Config tunes the service.
+type Config struct {
+	// SignupOpen decides whether anyone may create an account. Off, the form is
+	// not served at all; accounts are made with `llmgw users create`.
+	SignupOpen bool
+	// SessionTTL is how long a sign-in lasts.
+	SessionTTL time.Duration
+	// MaxAttempts and AttemptWindow bound password guessing per address.
+	MaxAttempts   int
+	AttemptWindow time.Duration
+}
+
+// DefaultConfig returns sensible values.
+func DefaultConfig() Config {
+	return Config{
+		SignupOpen:    true,
+		SessionTTL:    store.SessionTTL,
+		MaxAttempts:   10,
+		AttemptWindow: 15 * time.Minute,
+	}
+}
+
+func (c *Config) normalize() {
+	d := DefaultConfig()
+	if c.SessionTTL <= 0 {
+		c.SessionTTL = d.SessionTTL
+	}
+	if c.MaxAttempts <= 0 {
+		c.MaxAttempts = d.MaxAttempts
+	}
+	if c.AttemptWindow <= 0 {
+		c.AttemptWindow = d.AttemptWindow
+	}
+}
+
+// Service is signup, sign-in and sessions.
+type Service struct {
+	store Store
+	cfg   Config
+	log   *slog.Logger
+	now   func() time.Time
+
+	mu       sync.Mutex
+	attempts map[string]*attemptWindow
+
+	// dir checks the passwords of accounts this store keeps none for.
+	dir Directory
+}
+
+// Directory checks a password against an outside directory — Active
+// Directory over LDAP — and answers the account to sign in: made or kept in
+// step with the directory. Its errors are this package's ErrBadCredentials
+// and ErrSuspended for the person's own, and anything else for the
+// directory's.
+type Directory interface {
+	SignIn(ctx context.Context, login, password string) (store.User, error)
+}
+
+// SetDirectory has passwords for accounts with none here, and names that are
+// not addresses, checked by the directory. An account with a password here
+// — the administrator init made — is still checked here, so a directory that
+// is down locks nobody out.
+func (s *Service) SetDirectory(d Directory) { s.dir = d }
+
+type attemptWindow struct {
+	count int
+	since time.Time
+}
+
+// New builds the service.
+func New(s Store, cfg Config, log *slog.Logger) *Service {
+	cfg.normalize()
+	if log == nil {
+		log = slog.Default()
+	}
+	return &Service{store: s, cfg: cfg, log: log, now: time.Now, attempts: map[string]*attemptWindow{}}
+}
+
+// SignupOpen reports whether the form should be served.
+func (s *Service) SignupOpen() bool { return s.cfg.SignupOpen }
+
+// SignUp creates a pending account.
+//
+// It returns nil whether or not the address was already taken. A signup form
+// that says "this address already has an account" is an account enumerator that
+// anyone can run, and the person signing up learns nothing they need: either
+// way, what happens next is that they wait for approval.
+func (s *Service) SignUp(ctx context.Context, email, name, password string) error {
+	email = store.NormalizeEmail(email)
+	if !validEmail(email) {
+		return ErrInvalidEmail
+	}
+	hash, err := HashPassword(password)
+	if err != nil {
+		return err
+	}
+	if name = strings.TrimSpace(name); name == "" {
+		name = email
+	}
+
+	err = s.store.CreateUser(ctx, store.User{
+		ID: randomID("usr"), Email: email, Name: name,
+		PasswordHash: hash, State: store.UserPending, CreatedAt: s.now(),
+	})
+	if errors.Is(err, store.ErrEmailTaken) {
+		// Logged so an operator can see it; not told to the caller.
+		s.log.Info("signup for an address that already has an account")
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	s.log.Info("a new account is waiting for approval", "email", email)
+	return nil
+}
+
+// SignIn checks a password and opens a session, returning the session token and
+// the CSRF token that must accompany the forms in it.
+func (s *Service) SignIn(ctx context.Context, email, password string) (token, csrf string, err error) {
+	login := strings.TrimSpace(email)
+	email = store.NormalizeEmail(email)
+	// Counted per address and the client trying it, so somebody guessing
+	// from elsewhere cannot lock the owner out of their own account; and per
+	// address alone, more loosely, so guesses spread over many clients are
+	// still bounded.
+	byClient := email
+	if c := clientFrom(ctx); c != "" {
+		byClient = email + "|" + c
+	}
+	if !s.allowAttempt(byClient, s.cfg.MaxAttempts) || !s.allowAttempt("all|"+email, 10*s.cfg.MaxAttempts) {
+		return "", "", ErrTooManyTries
+	}
+
+	u, err := s.store.UserByEmail(ctx, email)
+	// No password kept here — the directory's, or nobody's — and a
+	// directory to ask: it decides.
+	if s.dir != nil && (errors.Is(err, store.ErrNotFound) || (err == nil && strings.HasPrefix(u.PasswordHash, "!"))) {
+		if u, err = s.dir.SignIn(ctx, login, password); err != nil {
+			return "", "", err
+		}
+		s.clearAttempts(byClient)
+		return s.open(ctx, u)
+	}
+	if errors.Is(err, store.ErrNotFound) {
+		// Verify anyway, against a hash that cannot match. Returning early here
+		// would let a stopwatch enumerate every account on the system.
+		_, _ = VerifyPassword(password, dummyHash)
+		return "", "", ErrBadCredentials
+	}
+	if err != nil {
+		return "", "", err
+	}
+
+	ok, err := VerifyPassword(password, u.PasswordHash)
+	if errors.Is(err, ErrBusy) {
+		// Not an answer about the password: said as what it is.
+		return "", "", err
+	}
+	if err != nil || !ok {
+		return "", "", ErrBadCredentials
+	}
+	// The password was right, so this was not an attack.
+	s.clearAttempts(byClient)
+
+	// State is checked after the password, on purpose. Checking first would
+	// tell anyone who guesses an address whether it has a pending account.
+	switch u.State {
+	case store.UserPending:
+		return "", "", ErrNotApproved
+	case store.UserSuspended:
+		return "", "", ErrSuspended
+	}
+	return s.open(ctx, u)
+}
+
+// open makes a session for a person whose password was right.
+func (s *Service) open(ctx context.Context, u store.User) (token, csrf string, err error) {
+	if token, err = store.NewSessionToken(); err != nil {
+		return "", "", err
+	}
+	if csrf, err = store.NewSessionToken(); err != nil {
+		return "", "", err
+	}
+	if err := s.store.CreateSession(ctx, u.ID, token, csrf, s.cfg.SessionTTL); err != nil {
+		return "", "", err
+	}
+	if err := s.store.TouchLogin(ctx, u.ID, s.now()); err != nil {
+		s.log.Warn("could not record a sign-in", "err", err)
+	}
+	return token, csrf, nil
+}
+
+// Resolve turns a session cookie into the person holding it.
+func (s *Service) Resolve(ctx context.Context, token string) (store.Session, store.User, error) {
+	if token == "" {
+		return store.Session{}, store.User{}, store.ErrNoSession
+	}
+	sess, u, err := s.store.SessionByToken(ctx, token)
+	if err != nil {
+		return store.Session{}, store.User{}, err
+	}
+	if err := s.store.TouchSession(ctx, token, s.now()); err != nil {
+		s.log.Debug("could not touch a session", "err", err)
+	}
+	return sess, u, nil
+}
+
+// SignOut closes one session.
+func (s *Service) SignOut(ctx context.Context, token string) error {
+	if token == "" {
+		return nil
+	}
+	return s.store.DeleteSession(ctx, token)
+}
+
+// CheckCSRF compares a submitted token against the session's.
+//
+// A cookie authenticates the browser, not the page that asked. Without this, any
+// site the person visits can post a form to ours and have the browser attach the
+// session automatically.
+func (s *Service) CheckCSRF(sess store.Session, submitted string) bool {
+	if submitted == "" || len(sess.CSRFHash) == 0 {
+		return false
+	}
+	return subtle.ConstantTimeCompare(store.HashKey(submitted), sess.CSRFHash) == 1
+}
+
+// allowAttempt bounds password guessing per address.
+//
+// Per address rather than per IP: an attacker has many addresses to come from
+// and only one to guess against, and limiting by IP would lock out everyone
+// behind one office NAT the moment somebody fat-fingers their password.
+func (s *Service) allowAttempt(email string, limit int) bool {
+	now := s.now()
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	w, ok := s.attempts[email]
+	if !ok && len(s.attempts) >= maxTrackedAddresses {
+		// Full of addresses nobody has signed in as for a while: forget the
+		// ones whose window has passed. Only expiring, never evicting early —
+		// dropping a live window is how an attacker spraying random addresses
+		// would buy unlimited guesses at the one they care about.
+		for k, v := range s.attempts {
+			if now.Sub(v.since) > s.cfg.AttemptWindow {
+				delete(s.attempts, k)
+			}
+		}
+		if len(s.attempts) >= maxTrackedAddresses {
+			// Still full, so somebody is spraying addresses faster than they
+			// expire. New ones wait; those already tracked are unaffected.
+			return false
+		}
+	}
+	if !ok || now.Sub(w.since) > s.cfg.AttemptWindow {
+		s.attempts[email] = &attemptWindow{count: 1, since: now}
+		return true
+	}
+	w.count++
+	return w.count <= limit
+}
+
+type clientKey struct{}
+
+// WithClient says which client a request comes from — its address — for the
+// sign-in throttle.
+func WithClient(ctx context.Context, client string) context.Context {
+	return context.WithValue(ctx, clientKey{}, client)
+}
+
+func clientFrom(ctx context.Context) string {
+	c, _ := ctx.Value(clientKey{}).(string)
+	return c
+}
+
+// maxTrackedAddresses bounds the throttle's memory. Unbounded, it grew by one
+// entry per address tried and shrank only on a successful sign-in.
+const maxTrackedAddresses = 50000
+
+func (s *Service) clearAttempts(email string) {
+	s.mu.Lock()
+	delete(s.attempts, email)
+	s.mu.Unlock()
+}
+
+// validEmail is deliberately crude. A real check is delivery, which this does
+// not do; this only rejects what is obviously not an address so the database
+// does not fill with them.
+func validEmail(s string) bool {
+	at := strings.IndexByte(s, '@')
+	if at <= 0 || at != strings.LastIndexByte(s, '@') || at == len(s)-1 {
+		return false
+	}
+	if strings.ContainsAny(s, " \t\r\n<>\"") {
+		return false
+	}
+	return strings.Contains(s[at+1:], ".")
+}
+
+func randomID(prefix string) string {
+	var buf [10]byte
+	_, _ = rand.Read(buf[:])
+	return prefix + "-" + strings.ToLower(
+		base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(buf[:]))
+}
+
+// ErrSamePassword says the new password is the old one.
+var ErrSamePassword = errors.New("that is the password you already have")
+
+// PasswordChanger is the extra storage a password change needs.
+type PasswordChanger interface {
+	SetPassword(ctx context.Context, userID, hash string) error
+	DeleteUserSessions(ctx context.Context, userID string) error
+}
+
+// ChangePassword replaces a person's password and signs them out everywhere.
+//
+// The current password is required even though the caller already holds a
+// session. A session is what an attacker gets from a borrowed laptop or a stolen
+// cookie; the password is what they do not have, and without this check the
+// first thing they would do is take the account.
+//
+// Every session is closed, this browser's included. Leaving the others open
+// would mean a password change does nothing about the reason someone is
+// changing it. The caller re-issues a session for the browser in front of them.
+func (s *Service) ChangePassword(ctx context.Context, pw PasswordChanger,
+	u store.User, current, next string,
+) error {
+	if !s.allowAttempt("pw:"+u.ID, s.cfg.MaxAttempts) {
+		return ErrTooManyTries
+	}
+	ok, err := VerifyPassword(current, u.PasswordHash)
+	if err != nil || !ok {
+		return ErrBadCredentials
+	}
+	s.clearAttempts("pw:" + u.ID)
+
+	if same, _ := VerifyPassword(next, u.PasswordHash); same {
+		return ErrSamePassword
+	}
+	hash, err := HashPassword(next)
+	if err != nil {
+		return err
+	}
+	if err := pw.SetPassword(ctx, u.ID, hash); err != nil {
+		return err
+	}
+	if err := pw.DeleteUserSessions(ctx, u.ID); err != nil {
+		return err
+	}
+	s.log.Info("a password was changed", "user", u.ID)
+	return nil
+}
+
+// OpenSession starts a session for a person who has just proved who they are by
+// some other means — immediately after changing their password, which closed
+// the one they were using.
+func (s *Service) OpenSession(ctx context.Context, userID string) (token, csrf string, err error) {
+	if token, err = store.NewSessionToken(); err != nil {
+		return "", "", err
+	}
+	if csrf, err = store.NewSessionToken(); err != nil {
+		return "", "", err
+	}
+	if err := s.store.CreateSession(ctx, userID, token, csrf, s.cfg.SessionTTL); err != nil {
+		return "", "", err
+	}
+	return token, csrf, nil
+}
+
+// ResetLinkTTL is how long a password reset link works.
+const ResetLinkTTL = time.Hour
+
+// ResetStore keeps password reset links.
+type ResetStore interface {
+	UserByEmail(ctx context.Context, email string) (store.User, error)
+	CreatePasswordReset(ctx context.Context, userID string, ttl time.Duration) (string, error)
+	PasswordResetUser(ctx context.Context, token string) (string, error)
+	UsePasswordReset(ctx context.Context, token string) (string, error)
+}
+
+// ErrNoReset is an address that gets no reset link: none has an account, the
+// account signs in through single sign-on, or it is not active. Never told to
+// whoever asked, who learns the same either way.
+var ErrNoReset = errors.New("no reset link for that address")
+
+// RequestReset mints a reset link token for the person an address belongs
+// to, when they sign in with a password and are active. A few a quarter of
+// an hour per address: each sends a mail.
+func (s *Service) RequestReset(ctx context.Context, rs ResetStore, email string) (string, store.User, error) {
+	email = store.NormalizeEmail(email)
+	if !validEmail(email) {
+		return "", store.User{}, ErrNoReset
+	}
+	if !s.allowAttempt("reset:"+email, 3) {
+		return "", store.User{}, ErrTooManyTries
+	}
+	u, err := rs.UserByEmail(ctx, email)
+	// An account whose password is kept elsewhere — "!oidc", "!scim",
+	// "!ldap" — gets no link: setting one here would give it a second way
+	// in that its directory knows nothing of, and outlives its leaving.
+	if err != nil || u.PasswordHash == "" || strings.HasPrefix(u.PasswordHash, "!") || u.State != store.UserActive {
+		return "", store.User{}, ErrNoReset
+	}
+	token, err := rs.CreatePasswordReset(ctx, u.ID, ResetLinkTTL)
+	if err != nil {
+		return "", store.User{}, err
+	}
+	s.log.Info("a password reset link was made", "user", u.ID)
+	return token, u, nil
+}
+
+// ResetPassword sets a password from a reset link, which is spent, and signs
+// the person out everywhere: if they lost it, someone else may have it.
+func (s *Service) ResetPassword(ctx context.Context, rs ResetStore, pw PasswordChanger, token, next string) error {
+	hash, err := HashPassword(next)
+	if err != nil {
+		return err
+	}
+	userID, err := rs.UsePasswordReset(ctx, token)
+	if err != nil {
+		return ErrNoReset
+	}
+	if err := pw.SetPassword(ctx, userID, hash); err != nil {
+		return err
+	}
+	if err := pw.DeleteUserSessions(ctx, userID); err != nil {
+		return err
+	}
+	s.log.Info("a password was set from a reset link", "user", userID)
+	return nil
+}

internal/account/throttle_bound_test.go

@@ -0,0 +1,33 @@
+package account
+
+import (
+	"fmt"
+	"testing"
+	"time"
+)
+
+func TestSprayingAddressesCannotGrowTheThrottleOrEscapeIt(t *testing.T) {
+	now := time.Unix(0, 0)
+	s := &Service{cfg: DefaultConfig(), attempts: map[string]*attemptWindow{}, now: func() time.Time { return now }}
+
+	// The target is being guessed at.
+	for i := 0; i < s.cfg.MaxAttempts; i++ {
+		s.allowAttempt("victim@example.com", s.cfg.MaxAttempts)
+	}
+	// Then the table is flooded with made-up addresses.
+	for i := 0; i < maxTrackedAddresses+100; i++ {
+		s.allowAttempt(fmt.Sprintf("x%d@example.com", i), s.cfg.MaxAttempts)
+	}
+	if n := len(s.attempts); n > maxTrackedAddresses {
+		t.Errorf("the table grew to %d", n)
+	}
+	if s.allowAttempt("victim@example.com", s.cfg.MaxAttempts) {
+		t.Error("flooding the table reset the target's throttle")
+	}
+
+	// Once the window passes, everything expires and sign-ins work again.
+	now = now.Add(s.cfg.AttemptWindow + time.Second)
+	if !s.allowAttempt("new@example.com", s.cfg.MaxAttempts) {
+		t.Error("a new address was refused after the flood expired")
+	}
+}

internal/accounting/accounting.go

@@ -0,0 +1,477 @@
+package accounting
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// Refusals a key can hit. They are distinguished so the client is told which
+// limit it hit, and so retrying is only suggested where retrying helps.
+var (
+	ErrRateLimited  = errors.New("request rate limit exceeded")
+	ErrTokenLimited = errors.New("token rate limit exceeded")
+	ErrBudgetSpent  = errors.New("budget exhausted")
+)
+
+// LimitError carries which limit was hit and, where it makes sense, when to
+// come back.
+type LimitError struct {
+	Err error
+	// RetryAfter is zero when waiting does not help, which is the case for a
+	// spent budget: it will not refill until the period rolls over, and telling
+	// a client to retry in a second would be a lie.
+	RetryAfter time.Duration
+}
+
+func (e *LimitError) Error() string { return e.Err.Error() }
+func (e *LimitError) Unwrap() error { return e.Err }
+
+// Accountant enforces limits and records what was used.
+//
+// One object because the three halves are not independent: a budget check needs
+// the price, the price needs the model, and the record closes the loop by
+// feeding the counters that the next check reads.
+type Accountant struct {
+	pricing  *Pricing
+	budgets  *Budgets
+	requests *Limiter
+	tokens   *Limiter
+	recorder *Recorder
+	log      *slog.Logger
+	// notify is told when a budget runs out; nil tells no one.
+	notify atomic.Pointer[notify.Notifier]
+}
+
+// SetNotifier gives the accountant somewhere to say a budget is spent.
+func (a *Accountant) SetNotifier(n *notify.Notifier) { a.notify.Store(n) }
+
+// New builds an accountant.
+func New(pricing *Pricing, recorder *Recorder, log *slog.Logger) *Accountant {
+	if log == nil {
+		log = slog.Default()
+	}
+	return &Accountant{
+		pricing:  pricing,
+		budgets:  NewBudgets(),
+		requests: NewLimiter(),
+		tokens:   NewLimiter(),
+		recorder: recorder,
+		log:      log,
+	}
+}
+
+// RestoreBudgets seeds the in-memory counters from the store.
+//
+// Called at startup. A restart must not reset a budget, which it would if the
+// counters only ever lived in memory.
+func (a *Accountant) RestoreBudgets(ctx context.Context, s store.Store, period store.Period) error {
+	start := PeriodStart(period, time.Now())
+	if start.IsZero() {
+		return nil
+	}
+	spend, keys, err := storedSpend(ctx, s, start)
+	if err != nil {
+		return fmt.Errorf("restoring budgets: %w", err)
+	}
+	a.budgets.Restore(period, spend)
+	a.log.Info("restored budgets from the store",
+		"keys", keys, "counters", len(spend), "since", start)
+	return nil
+}
+
+// CatchUpBudgets raises each counter to what the store has recorded, where
+// that is more. Run every so often by a router that is one of several taking
+// requests: the others' spend reaches it only through the store. Never
+// lowers a counter, which leads the store by whatever this process has not
+// written yet.
+func (a *Accountant) CatchUpBudgets(ctx context.Context, s store.Store, period store.Period) error {
+	start := PeriodStart(period, time.Now())
+	if start.IsZero() {
+		return nil
+	}
+	spend, _, err := storedSpend(ctx, s, start)
+	if err != nil {
+		return fmt.Errorf("reading budgets: %w", err)
+	}
+	a.budgets.Raise(period, spend)
+	return nil
+}
+
+// storedSpend is the spend since start the store has recorded, by counter,
+// and how many keys it came from.
+func storedSpend(ctx context.Context, s store.Store, start time.Time) (map[string]int64, int, error) {
+	rows, err := s.SpendSinceByScope(ctx, start)
+	if err != nil {
+		return nil, 0, err
+	}
+	// Every scope a key sits under, not just the key. A budget owned by a team
+	// is one counter fed by every key beneath it, and restoring only per-key
+	// totals would bring the control plane back up believing the team had spent
+	// nothing — which is a budget that resets on every restart, for exactly the
+	// scopes where it matters most.
+	// And every pool a person is in: their own, and each per-member limit of
+	// the project, team and organization they spent it in.
+	spend := make(map[string]int64, len(rows)*8)
+	for _, r := range rows {
+		owners := []store.LimitOwner{
+			{Scope: store.ScopeKey, ID: r.KeyID},
+			{Scope: store.ScopeProject, ID: r.ProjectID},
+			{Scope: store.ScopeTeam, ID: r.TeamID},
+			{Scope: store.ScopeOrg, ID: r.OrgID},
+			{Scope: store.ScopeUser, ID: r.UserID},
+		}
+		if r.UserID != "" && r.ProjectID != "" {
+			owners = append(owners,
+				store.MemberOwner(store.ScopeProjectMember, r.ProjectID, r.UserID),
+				store.MemberOwner(store.ScopeTeamMember, r.TeamID, r.UserID),
+				store.MemberOwner(store.ScopeOrgMember, r.OrgID, r.UserID))
+		}
+		for _, o := range owners {
+			if o.ID == "" || strings.HasPrefix(o.ID, "/") {
+				continue
+			}
+			if k := o.CounterKey(); k != "" {
+				spend[k] += r.Micros
+			}
+		}
+	}
+	return spend, len(rows), nil
+}
+
+// Reservation is what Check returns: the estimate it charged, so Record can
+// settle the difference against the real figure.
+// pool is one level's counter and the period its budget runs over.
+type pool struct {
+	Counter string
+	Period  store.Period
+}
+
+type Reservation struct {
+	KeyID string
+	// Budgets and Tokens are every counter the check went through, carried so
+	// the settlement lands on the same ones. Every, not the tightest: an
+	// organization's pool only fills up if each team's spend is added to it
+	// as well as to the team's own.
+	//
+	// Derived again at settlement would mean re-resolving the limits, and a
+	// budget checked against the team and settled against the key is a budget
+	// that never fills up.
+	Budgets         []pool
+	Tokens          []string
+	EstimatedTokens int64
+	Price           Price
+	// Period is the key's budget period, carried from the check so the record
+	// counts against the same window the check read. Deriving it later would
+	// mean guessing, and a monthly budget credited to a daily counter is a
+	// budget that never binds.
+	Period store.Period
+}
+
+// Check decides whether a request may proceed.
+//
+// It runs before scheduling and touches no database: every counter it reads is
+// in memory. The token limit is checked against an estimate, because the real
+// figure only exists once the request has run; Record settles the difference.
+func (a *Accountant) Check(p auth.Principal, model string, estimatedTokens int64) (Reservation, error) {
+	price := a.pricing.For(model)
+	lim := p.Limits
+	// Every level that set a limit, each against its own pool. A quota written
+	// on a team is one pool the team shares, and the organization above it is a
+	// second pool that the team's spending also fills — both have to hold, or
+	// an organization given 1000 with four teams given 500 spends 2000.
+	chain := levels(lim, p.KeyID)
+
+	res := Reservation{
+		KeyID: p.KeyID, EstimatedTokens: estimatedTokens,
+		Price: price, Period: lim.BudgetPeriod,
+	}
+	for _, l := range chain {
+		if l.Budget != nil {
+			res.Budgets = append(res.Budgets, pool{l.Counter, l.Period})
+		}
+		if l.TPM != nil {
+			res.Tokens = append(res.Tokens, l.Counter)
+		}
+	}
+	if p.KeyID == "" {
+		return res, nil
+	}
+
+	// Budget first. It is the limit whose refusal cannot be retried away, so
+	// telling the client about it first is more useful than reporting a rate
+	// limit it would hit again in a second.
+	//
+	// A model that costs nothing is exempt, which is what lets a key with no
+	// budget left still be served a cheap fallback (plan §7.7).
+	// Budgets first, and all of them. Exhausted only reads, so the order costs
+	// nothing and a refusal here charges no counter.
+	if !price.Zero() {
+		for _, l := range chain {
+			if l.Budget != nil && a.budgets.Exhausted(l.Counter, l.Period, *l.Budget) {
+				a.notify.Load().Notify(notify.BudgetSpent, l.Counter,
+					fmt.Sprintf("the %s budget of %s is spent: requests to priced models are refused until it renews",
+						or(string(l.Period), "total"), l.Counter),
+					map[string]any{"counter": l.Counter, "period": string(l.Period), "budget": *l.Budget})
+				return res, &LimitError{Err: ErrBudgetSpent}
+			}
+		}
+	}
+
+	// Rate limits charge as they check — deliberately, so two concurrent
+	// requests cannot both see room. With several levels that means a refusal
+	// at one has already taken from the levels before it, so those are handed
+	// back. Without the refund a team at its ceiling would quietly eat its
+	// organization's rate limit with requests that were never served.
+	if err := a.allowAll(chain, func(l level) (string, int, int64, bool) {
+		return l.Counter, valInt(l.RPM), 1, l.RPM != nil
+	}, a.requests); err != nil {
+		return res, &LimitError{Err: ErrRateLimited, RetryAfter: time.Second}
+	}
+	if err := a.allowAll(chain, func(l level) (string, int, int64, bool) {
+		return l.Counter, valInt(l.TPM), estimatedTokens, l.TPM != nil
+	}, a.tokens); err != nil {
+		// The request was not charged against the request-rate limit in vain:
+		// it was, and that is correct — it did arrive.
+		return res, &LimitError{Err: ErrTokenLimited, RetryAfter: time.Second}
+	}
+	return res, nil
+}
+
+// level is one scope's limits with the counter they are enforced against.
+type level struct {
+	Counter string
+	Period  store.Period
+	RPM     *int
+	TPM     *int
+	Budget  *int64
+}
+
+// levels turns a resolved chain into the pools a request must pass.
+//
+// Falls back to the collapsed values when the chain is empty, which is what a
+// principal assembled by hand looks like — in tests, and anywhere that builds
+// limits without walking the tree.
+func levels(e store.Effective, keyID string) []level {
+	if len(e.Chain) == 0 {
+		var out []level
+		if e.RPM != nil || e.TPM != nil || e.Budget != nil {
+			out = append(out, level{
+				Counter: counterFor(e.BudgetOwner, keyID),
+				Period:  e.BudgetPeriod, Budget: e.Budget,
+			})
+			out[0].RPM, out[0].TPM = e.RPM, e.TPM
+			// One entry, so a hand-built principal with different owners per
+			// limit still counts each where it said to.
+			if r, b := counterFor(e.RPMOwner, keyID), out[0].Counter; r != b && e.RPM != nil {
+				out[0].RPM = nil
+				out = append(out, level{Counter: r, RPM: e.RPM})
+			}
+			if tp, b := counterFor(e.TPMOwner, keyID), out[0].Counter; tp != b && e.TPM != nil {
+				out[0].TPM = nil
+				out = append(out, level{Counter: tp, TPM: e.TPM})
+			}
+		}
+		return out
+	}
+	out := make([]level, 0, len(e.Chain))
+	for _, l := range e.Chain {
+		out = append(out, level{
+			Counter: store.LimitOwner{Scope: l.Scope, ID: l.ScopeID}.CounterKey(),
+			Period:  l.BudgetPeriod, RPM: l.RPM, TPM: l.TPM, Budget: l.Budget,
+		})
+	}
+	return out
+}
+
+// allowAll charges every level that has this limit, refunding on a refusal.
+func (a *Accountant) allowAll(chain []level,
+	pick func(level) (key string, limit int, n int64, has bool), lim *Limiter,
+) error {
+	var charged []struct {
+		key string
+		n   int64
+	}
+	for _, l := range chain {
+		key, limit, n, has := pick(l)
+		if !has {
+			continue
+		}
+		if !lim.Allow(key, limit, n) {
+			for _, c := range charged {
+				lim.Charge(c.key, -c.n)
+			}
+			return errRefused
+		}
+		charged = append(charged, struct {
+			key string
+			n   int64
+		}{key, n})
+	}
+	return nil
+}
+
+var errRefused = errors.New("refused")
+
+func valInt(v *int) int {
+	if v == nil {
+		return 0
+	}
+	return *v
+}
+
+// Record settles a finished request: it reconciles the token estimate, adds to
+// the budget, and queues the usage row.
+func (a *Accountant) Record(res Reservation, u store.Usage) {
+	if res.KeyID == "" {
+		return
+	}
+	actual := u.PromptTokens + u.CompletionTokens
+
+	// The estimate was charged up front; charge the difference now. A caller
+	// whose requests are consistently larger than estimated is still bounded,
+	// one window later than with a perfect estimate.
+	// Every level the check went through, so an organization's pool fills up
+	// from its teams' spending rather than only from requests that named it.
+	for _, c := range res.Tokens {
+		a.tokens.Charge(c, actual-res.EstimatedTokens)
+	}
+
+	// Priced by the model that answered: a fallback served by another model
+	// costs what that one costs, not what the one asked for would have.
+	price := res.Price
+	if u.ServedModel != "" && u.ServedModel != u.Model && a.pricing != nil {
+		price = a.pricing.For(u.ServedModel)
+	}
+	u.CostMicros = price.Cost(u.PromptTokens, u.CachedTokens, u.CompletionTokens, u.Images, u.Meshes)
+	for _, b := range res.Budgets {
+		a.budgets.Add(b.Counter, b.Period, u.CostMicros)
+	}
+
+	if a.recorder != nil {
+		a.recorder.Record(u)
+	}
+}
+
+// RecordRefused queues the row of a request a limit refused: nothing is
+// charged — it used nothing — but it is counted, so a team running into its
+// limits shows as one rather than as a team that went quiet.
+func (a *Accountant) RecordRefused(u store.Usage) {
+	if u.KeyID == "" || a.recorder == nil {
+		return
+	}
+	u.PromptTokens, u.CompletionTokens, u.CostMicros = 0, 0, 0
+	a.recorder.Record(u)
+}
+
+// Status returns what a key has used, for headers and `ctl`.
+func (a *Accountant) Status(p auth.Principal) (spent int64, rpm, tpm float64) {
+	if p.KeyID == "" {
+		return 0, 0, 0
+	}
+	// The pool that will refuse them, which is not always the one with the
+	// smallest number on it. A team given 2000 inside an organization given the
+	// same is bounded by whichever is nearer its ceiling, and that is the
+	// organization as soon as a second team spends anything. A header that
+	// reported the team's would disagree with the refusal that follows it.
+	for _, l := range levels(p.Limits, p.KeyID) {
+		if l.Budget != nil {
+			if v := a.budgets.Spent(l.Counter, l.Period); v > spent {
+				spent = v
+			}
+		}
+		if l.RPM != nil {
+			if v := a.requests.Rate(l.Counter); v > rpm {
+				rpm = v
+			}
+		}
+		if l.TPM != nil {
+			if v := a.tokens.Rate(l.Counter); v > tpm {
+				tpm = v
+			}
+		}
+	}
+	return spent, rpm, tpm
+}
+
+// counterFor is the counter a limit owned by this scope should use.
+//
+// Falls back to the key's own counter when no scope owns the limit, which
+// happens when nothing in the chain set one.
+//
+// Namespaced even then. A bare key id here and a "key:"-prefixed one in the
+// restore path would be two different counters for the same key, so a budget
+// would check against an empty one and survive every restart — which is how
+// this was wrong when it was first written.
+func counterFor(o store.LimitOwner, keyID string) string {
+	if k := o.CounterKey(); k != "" {
+		return k
+	}
+	return keyCounter(keyID)
+}
+
+// keyCounter is a key's own counter, in the same namespace as every other.
+func or(v, fallback string) string {
+	if v == "" {
+		return fallback
+	}
+	return v
+}
+
+func keyCounter(keyID string) string {
+	if keyID == "" {
+		return ""
+	}
+	return store.LimitOwner{Scope: store.ScopeKey, ID: keyID}.CounterKey()
+}
+
+// AnythingPriced reports whether a budget can ever be spent against.
+//
+// On the accountant rather than making callers reach for the price table: what
+// they are asking is whether the budgets they are about to display mean
+// anything, and the accountant is what would enforce them.
+func (a *Accountant) AnythingPriced() bool { return a.pricing.AnythingPriced() }
+
+// Headroom is the tightest of a principal's request and token limits: how
+// much is left of each, and when the minute it is counted over rolls on.
+type Headroom struct {
+	RequestLimit, RequestsLeft int
+	TokenLimit, TokensLeft     int
+	Reset                      time.Duration
+}
+
+// Headroom reports what a principal has left, after whatever Check just
+// charged. Of several levels the one with least left is the one that will
+// refuse first, so that is the one reported. A limit of 0 means none is set.
+func (a *Accountant) Headroom(p auth.Principal) Headroom {
+	var h Headroom
+	firstReq, firstTok := true, true
+	for _, l := range levels(p.Limits, p.KeyID) {
+		if l.RPM != nil && *l.RPM > 0 {
+			left := max(0, *l.RPM-int(a.requests.Rate(l.Counter)))
+			if firstReq || left < h.RequestsLeft {
+				h.RequestLimit, h.RequestsLeft, firstReq = *l.RPM, left, false
+			}
+		}
+		if l.TPM != nil && *l.TPM > 0 {
+			left := max(0, *l.TPM-int(a.tokens.Rate(l.Counter)))
+			if firstTok || left < h.TokensLeft {
+				h.TokenLimit, h.TokensLeft, firstTok = *l.TPM, left, false
+			}
+		}
+	}
+	// The windows slide, so room comes back continuously; the next minute
+	// boundary is when a whole window's worth has moved on, and is the figure
+	// a client pacing itself can act on.
+	now := time.Now()
+	h.Reset = now.Truncate(windowLen).Add(windowLen).Sub(now)
+	return h
+}

internal/accounting/accounting_test.go

@@ -0,0 +1,749 @@
+package accounting
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify/notifytest"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+func intp(v int) *int     { return &v }
+func i64p(v int64) *int64 { return &v }
+
+func principal(id string, tune func(*store.Effective)) auth.Principal {
+	e := store.Effective{KeyID: id, ProjectID: "proj"}
+	if tune != nil {
+		tune(&e)
+	}
+	return auth.Principal{KeyID: id, ProjectID: "proj", Limits: e}
+}
+
+func pricing(t *testing.T) *Pricing {
+	t.Helper()
+	return NewPricing(map[string]Price{
+		"paid": {PromptPer1k: 1000, CompletionPer1k: 3000},
+		"free": {},
+	}, Price{})
+}
+
+func TestCostRoundsUpSoSmallRequestsAreNotFree(t *testing.T) {
+	// Rounding down would make a stream of tiny requests cost nothing, which is
+	// exactly the traffic shape a quota exists to bound.
+	p := Price{PromptPer1k: 1000, CompletionPer1k: 3000}
+	if got := p.Cost(1, 0, 0, 0, 0); got != 1 {
+		t.Errorf("one prompt token cost %d", got)
+	}
+	if got := p.Cost(1000, 0, 1000, 0, 0); got != 4000 {
+		t.Errorf("a thousand of each cost %d, want 4000", got)
+	}
+	if got := p.Cost(0, 0, 0, 0, 0); got != 0 {
+		t.Errorf("an empty request cost %d", got)
+	}
+}
+
+func TestACachedPromptCostsTheCachedRate(t *testing.T) {
+	p := Price{PromptPer1k: 1000, CachedPer1k: 100, CompletionPer1k: 3000}
+	// 10,000 prompt tokens of which 9,000 were read from the cache: 1,000 at
+	// the prompt rate and 9,000 at the cached one.
+	if got, want := p.Cost(10000, 9000, 0, 0, 0), int64(1000+900); got != want {
+		t.Errorf("a 90%% cached prompt cost %d, want %d", got, want)
+	}
+	// More cached than prompt is an engine's miscount, not a refund.
+	if got := p.Cost(100, 500, 0, 0, 0); got != 10 {
+		t.Errorf("cached beyond the prompt cost %d, want 10", got)
+	}
+	// No cached rate: cached tokens cost what any prompt token does.
+	if got := (Price{PromptPer1k: 1000}).Cost(10000, 9000, 0, 0, 0); got != 10000 {
+		t.Errorf("without a cached rate a cached prompt cost %d, want 10000", got)
+	}
+}
+
+func TestAPictureCostsItsPriceOnTopOfItsPrompt(t *testing.T) {
+	p := Price{PromptPer1k: 1000, PerImage: 50000}
+	if got := p.Cost(20, 0, 0, 3, 0); got != 20+150000 {
+		t.Errorf("three pictures from a 20-token prompt cost %d", got)
+	}
+	if (Price{PerImage: 1}).Zero() {
+		t.Error("a model priced per picture reads as free, and would pass a spent budget")
+	}
+}
+
+func TestZeroPricedModelsStayAvailableWhenTheBudgetIsSpent(t *testing.T) {
+	// This is what makes budget fallback work: a key with nothing left can
+	// still be served something that costs nothing.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) {
+		e.Budget = i64p(100)
+		e.BudgetPeriod = store.PeriodMonth
+	})
+
+	res, err := a.Check(p, "paid", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000, CompletionTokens: 0})
+
+	if _, err := a.Check(p, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("a spent budget still served a paid model: %v", err)
+	}
+	if _, err := a.Check(p, "free", 10); err != nil {
+		t.Errorf("a spent budget refused a free model: %v", err)
+	}
+}
+
+func TestBudgetRefusalDoesNotSuggestRetrying(t *testing.T) {
+	// A budget does not refill until the period rolls over, so a Retry-After of
+	// a second would be a lie that turns one client into a retry loop.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) {
+		e.Budget = i64p(1)
+		e.BudgetPeriod = store.PeriodDay
+	})
+	res, _ := a.Check(p, "paid", 10)
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 5000})
+
+	_, err := a.Check(p, "paid", 10)
+	var le *LimitError
+	if !errors.As(err, &le) {
+		t.Fatalf("expected a limit error, got %v", err)
+	}
+	if le.RetryAfter != 0 {
+		t.Errorf("a spent budget suggested retrying in %v", le.RetryAfter)
+	}
+}
+
+func TestRateLimitsBind(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) { e.RPM = intp(3) })
+
+	for i := range 3 {
+		if _, err := a.Check(p, "free", 1); err != nil {
+			t.Fatalf("request %d was refused: %v", i, err)
+		}
+	}
+	if _, err := a.Check(p, "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Errorf("the fourth request was allowed: %v", err)
+	}
+}
+
+func TestTokenLimitsUseTheEstimateAndThenSettle(t *testing.T) {
+	// The real token count only exists once the request has run, so the check
+	// has to work on an estimate. A caller that consistently underestimates
+	// must still end up bounded.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) { e.TPM = intp(1000) })
+
+	// Claims 10 tokens, actually uses 900.
+	res, err := a.Check(p, "free", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 400, CompletionTokens: 500})
+
+	// The settled figure is what the next check sees, so a second request of
+	// the same shape cannot fit.
+	if _, err := a.Check(p, "free", 200); !errors.Is(err, ErrTokenLimited) {
+		t.Errorf("the underestimate was never settled: %v", err)
+	}
+}
+
+func TestNoLimitIsNotALimitOfZero(t *testing.T) {
+	// The distinction the store keeps with a nil pointer. Getting it wrong here
+	// would silently forbid every request for every key with no limits set.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", nil)
+
+	for range 50 {
+		if _, err := a.Check(p, "paid", 10_000); err != nil {
+			t.Fatalf("a key with no limits was refused: %v", err)
+		}
+	}
+}
+
+func TestAnUnauthenticatedRequestIsNotAccounted(t *testing.T) {
+	// With auth off there is no key to charge, and Check must not refuse.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	res, err := a.Check(auth.Principal{}, "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{PromptTokens: 1000})
+	if spent, _, _ := a.Status(auth.Principal{}); spent != 0 {
+		t.Errorf("an anonymous request was charged %d", spent)
+	}
+}
+
+func TestBudgetSurvivesARestart(t *testing.T) {
+	// The counters live in memory; the store is what makes them survive.
+	ctx := context.Background()
+	path := filepath.Join(t.TempDir(), "acct.db")
+	s, err := store.OpenSQLite(ctx, path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+
+	must(t, s.PutOrg(ctx, store.Org{ID: "o", Name: "o"}))
+	must(t, s.PutTeam(ctx, store.Team{ID: "t", OrgID: "o", Name: "t"}))
+	must(t, s.PutProject(ctx, store.Project{ID: "proj", TeamID: "t", Name: "p"}))
+	_, k, _ := store.NewKey("k1", "n", "proj")
+	k.CreatedAt = time.Now()
+	must(t, s.CreateKey(ctx, k))
+
+	must(t, s.WriteUsage(ctx, []store.Usage{
+		{At: time.Now(), KeyID: "k1", ProjectID: "proj", Model: "paid",
+			ServedModel: "paid", CostMicros: 5000, Status: 200},
+	}))
+
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	must(t, a.RestoreBudgets(ctx, s, store.PeriodMonth))
+
+	p := principal("k1", func(e *store.Effective) {
+		e.Budget = i64p(5000)
+		e.BudgetPeriod = store.PeriodMonth
+	})
+	if _, err := a.Check(p, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("the budget was reset by the restart: %v", err)
+	}
+}
+
+func TestCatchingUpRaisesButNeverLowers(t *testing.T) {
+	// Another router's spend arrives through the store; this one's own, not
+	// written yet, must not be wiped by a store that is behind.
+	b := NewBudgets()
+	b.Add("mine", store.PeriodMonth, 900)
+	b.Add("shared", store.PeriodMonth, 100)
+
+	b.Raise(store.PeriodMonth, map[string]int64{"mine": 400, "shared": 700, "theirs": 50})
+
+	for key, want := range map[string]int64{"mine": 900, "shared": 700, "theirs": 50} {
+		if got := b.Spent(key, store.PeriodMonth); got != want {
+			t.Errorf("%s: spent %d, want %d", key, got, want)
+		}
+	}
+}
+
+func TestBudgetsResetAtThePeriodBoundary(t *testing.T) {
+	b := NewBudgets()
+	now := time.Date(2026, 1, 31, 23, 59, 0, 0, time.UTC)
+	b.now = func() time.Time { return now }
+
+	b.Add("k1", store.PeriodMonth, 900)
+	if got := b.Spent("k1", store.PeriodMonth); got != 900 {
+		t.Fatalf("spent %d", got)
+	}
+
+	now = now.Add(2 * time.Minute) // into February
+	if got := b.Spent("k1", store.PeriodMonth); got != 0 {
+		t.Errorf("the counter carried %d across the month boundary", got)
+	}
+}
+
+func TestDailyAndMonthlyBoundariesDiffer(t *testing.T) {
+	b := NewBudgets()
+	now := time.Date(2026, 3, 15, 12, 0, 0, 0, time.UTC)
+	b.now = func() time.Time { return now }
+
+	b.Add("daily", store.PeriodDay, 100)
+	b.Add("monthly", store.PeriodMonth, 100)
+
+	now = now.Add(24 * time.Hour)
+	if got := b.Spent("daily", store.PeriodDay); got != 0 {
+		t.Errorf("the daily counter carried %d across a day", got)
+	}
+	if got := b.Spent("monthly", store.PeriodMonth); got != 100 {
+		t.Errorf("the monthly counter lost %d within a month", 100-got)
+	}
+}
+
+func TestTheWindowDoesNotAllowTwiceTheLimit(t *testing.T) {
+	// The reason for a sliding window. With a fixed one, a caller sends its
+	// whole allowance at the end of a window and again at the start of the
+	// next, so the observed rate is double the limit exactly when the system is
+	// least able to take it.
+	l := NewLimiter()
+	base := time.Date(2026, 1, 1, 12, 0, 0, 0, time.UTC)
+	now := base.Add(59 * time.Second)
+	l.now = func() time.Time { return now }
+
+	const limit = 60
+	sent := 0
+	for range limit {
+		if l.Allow("k", limit, 1) {
+			sent++
+		}
+	}
+	if sent != limit {
+		t.Fatalf("the first burst only managed %d", sent)
+	}
+
+	// One second later, in the next fixed window.
+	now = base.Add(61 * time.Second)
+	second := 0
+	for range limit {
+		if l.Allow("k", limit, 1) {
+			second++
+		}
+	}
+	// Some allowance returns as the old window slides out of view, but nowhere
+	// near the whole of it.
+	if second > limit/2 {
+		t.Errorf("a second burst of %d passed immediately after %d; the window is not sliding",
+			second, sent)
+	}
+}
+
+func TestLimiterIsSafeUnderConcurrency(t *testing.T) {
+	// Checking and charging have to be one operation, or two concurrent
+	// requests both see room and both take it.
+	l := NewLimiter()
+	const limit = 100
+
+	var wg sync.WaitGroup
+	var mu sync.Mutex
+	allowed := 0
+	for range 500 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if l.Allow("k", limit, 1) {
+				mu.Lock()
+				allowed++
+				mu.Unlock()
+			}
+		}()
+	}
+	wg.Wait()
+	if allowed != limit {
+		t.Errorf("%d requests passed a limit of %d", allowed, limit)
+	}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+// teamMember is a key whose budget and rate limit were set on its team, which
+// is the arrangement an enterprise actually asks for: a group gets a quota and
+// the people in it share it.
+func teamMember(keyID, teamID string, tune func(*store.Effective)) auth.Principal {
+	e := store.Effective{KeyID: keyID, ProjectID: "proj", TeamID: teamID}
+	owner := store.LimitOwner{Scope: store.ScopeTeam, ID: teamID}
+	e.BudgetOwner, e.RPMOwner, e.TPMOwner = owner, owner, owner
+	if tune != nil {
+		tune(&e)
+	}
+	return auth.Principal{KeyID: keyID, ProjectID: "proj", Limits: e}
+}
+
+func TestATeamBudgetIsOnePoolRatherThanOnePerMember(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	budget := func(e *store.Effective) {
+		e.Budget = i64p(3000)
+		e.BudgetPeriod = store.PeriodMonth
+	}
+	first := teamMember("k1", "t1", budget)
+	second := teamMember("k2", "t1", budget)
+
+	// One member spends the lot.
+	res, err := a.Check(first, "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000, CompletionTokens: 1000})
+
+	// The second must now be refused. Counted per key it would have its own
+	// untouched 3000 — a team budget of 3000 with ten keys would permit thirty
+	// thousand, which is the bug this change exists for.
+	if _, err := a.Check(second, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("the team's budget should be shared; the second member got %v", err)
+	}
+}
+
+func TestATeamRateLimitIsSharedToo(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	rpm := func(e *store.Effective) { e.RPM = intp(1) }
+
+	if _, err := a.Check(teamMember("k1", "t1", rpm), "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Check(teamMember("k2", "t1", rpm), "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Error("a rate limit set on the team should be shared by its keys")
+	}
+}
+
+func TestTwoTeamsDoNotShareACounter(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	rpm := func(e *store.Effective) { e.RPM = intp(1) }
+
+	if _, err := a.Check(teamMember("k1", "t1", rpm), "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	// Pooling is the point; pooling the wrong things is the danger. One team
+	// exhausting another's quota would be worse than the bug being fixed.
+	if _, err := a.Check(teamMember("k2", "t2", rpm), "free", 1); err != nil {
+		t.Errorf("a second team should have its own counter, got %v", err)
+	}
+}
+
+func TestAKeyLimitStaysPerKey(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	perKey := func(id string) auth.Principal {
+		return principal(id, func(e *store.Effective) {
+			e.RPM = intp(1)
+			e.RPMOwner = store.LimitOwner{Scope: store.ScopeKey, ID: id}
+		})
+	}
+
+	if _, err := a.Check(perKey("k1"), "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	// The tree still has to be able to say "each of you may do this much".
+	// Sharing a group pool must not become the only thing expressible.
+	if _, err := a.Check(perKey("k2"), "free", 1); err != nil {
+		t.Errorf("a limit owned by the key should not be shared, got %v", err)
+	}
+}
+
+func TestTheDifferentLimitsCanBeOwnedByDifferentScopes(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	// A team budget with a per-key rate limit is the ordinary arrangement: the
+	// group's money, the individual's throughput.
+	mk := func(id string) auth.Principal {
+		e := store.Effective{KeyID: id, TeamID: "t1"}
+		e.Budget, e.BudgetPeriod = i64p(3000), store.PeriodMonth
+		e.BudgetOwner = store.LimitOwner{Scope: store.ScopeTeam, ID: "t1"}
+		e.RPM = intp(1)
+		e.RPMOwner = store.LimitOwner{Scope: store.ScopeKey, ID: id}
+		return auth.Principal{KeyID: id, Limits: e}
+	}
+
+	res, err := a.Check(mk("k1"), "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000, CompletionTokens: 1000})
+
+	// k2's rate limit is its own and untouched; the budget is the team's and
+	// gone. The budget is checked first, so that is what comes back.
+	if _, err := a.Check(mk("k2"), "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("expected the shared budget to bite, got %v", err)
+	}
+}
+
+func TestStatusReportsTheCounterThatWillRefuseYou(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	budget := func(e *store.Effective) {
+		e.Budget = i64p(9000)
+		e.BudgetPeriod = store.PeriodMonth
+	}
+	res, err := a.Check(teamMember("k1", "t1", budget), "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000, CompletionTokens: 1000})
+
+	// A member who has spent nothing themselves still sees the team's spend,
+	// because that is the number that will stop them. A header disagreeing with
+	// the refusal it precedes is worse than no header.
+	spent, _, _ := a.Status(teamMember("k2", "t1", budget))
+	if spent == 0 {
+		t.Error("a member should see the pool's spend, not their own")
+	}
+}
+
+func TestATeamBudgetSurvivesARestart(t *testing.T) {
+	// The per-key restore could not do this: it rebuilt a counter named after
+	// the key, while the check reads one named after the team. The control
+	// plane came back believing the team had spent nothing — a budget that
+	// resets on every restart, for exactly the scope where it matters most.
+	ctx := context.Background()
+	s, err := store.OpenSQLite(ctx, filepath.Join(t.TempDir(), "team.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+
+	must(t, s.PutOrg(ctx, store.Org{ID: "o", Name: "o"}))
+	must(t, s.PutTeam(ctx, store.Team{ID: "t1", OrgID: "o", Name: "t"}))
+	must(t, s.PutProject(ctx, store.Project{ID: "proj", TeamID: "t1", Name: "p"}))
+	for _, id := range []string{"k1", "k2"} {
+		_, k, _ := store.NewKey(id, "n", "proj")
+		k.CreatedAt = time.Now()
+		must(t, s.CreateKey(ctx, k))
+	}
+
+	// Two members of one team, 2500 each: neither alone exceeds a 4000 budget,
+	// together they do.
+	must(t, s.WriteUsage(ctx, []store.Usage{
+		{At: time.Now(), KeyID: "k1", ProjectID: "proj", Model: "paid",
+			ServedModel: "paid", CostMicros: 2500, Status: 200},
+		{At: time.Now(), KeyID: "k2", ProjectID: "proj", Model: "paid",
+			ServedModel: "paid", CostMicros: 2500, Status: 200},
+	}))
+
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	must(t, a.RestoreBudgets(ctx, s, store.PeriodMonth))
+
+	p := teamMember("k1", "t1", func(e *store.Effective) {
+		e.Budget = i64p(4000)
+		e.BudgetPeriod = store.PeriodMonth
+	})
+	if _, err := a.Check(p, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("the team's spend should have been restored and pooled: %v", err)
+	}
+}
+
+// inTree is a key under org/team/project, with whatever each level sets.
+func inTree(keyID string, chain ...store.Limits) auth.Principal {
+	e := store.Effective{KeyID: keyID, Chain: chain}
+	// The collapsed values still exist for headers and the profile page; they
+	// are not what enforcement reads any more.
+	for _, l := range chain {
+		if l.Budget != nil && (e.Budget == nil || *l.Budget < *e.Budget) {
+			e.Budget, e.BudgetPeriod = l.Budget, l.BudgetPeriod
+			e.BudgetOwner = store.LimitOwner{Scope: l.Scope, ID: l.ScopeID}
+		}
+	}
+	return auth.Principal{KeyID: keyID, Limits: e}
+}
+
+func orgBudget(id string, v int64) store.Limits {
+	return store.Limits{Scope: store.ScopeOrg, ScopeID: id,
+		Budget: i64p(v), BudgetPeriod: store.PeriodMonth}
+}
+
+func teamBudget(id string, v int64) store.Limits {
+	return store.Limits{Scope: store.ScopeTeam, ScopeID: id,
+		Budget: i64p(v), BudgetPeriod: store.PeriodMonth}
+}
+
+func TestTheSumOfTeamsCannotExceedTheOrganization(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+
+	// Each request costs 800. The organization allows 2000 and each of its four
+	// teams allows 2000, so no team comes close to its own ceiling — but the
+	// organization's fills after three. Taking only the most restrictive value,
+	// the organization's number was never looked at and all four went through.
+	//
+	// A budget stops spending once it is reached rather than refusing the
+	// request that would cross it, so the third is served and the fourth is not.
+	spend := func(team string) error {
+		p := inTree(team+"-k", orgBudget("o", 2000), teamBudget(team, 2000))
+		res, err := a.Check(p, "paid", 1000)
+		if err != nil {
+			return err
+		}
+		a.Record(res, store.Usage{KeyID: team + "-k", PromptTokens: 200, CompletionTokens: 200})
+		return nil
+	}
+
+	total := 0
+	for _, team := range []string{"t1", "t2", "t3", "t4"} {
+		if err := spend(team); err == nil {
+			total++
+		}
+	}
+	if total != 3 {
+		t.Errorf("expected the organization to stop the fourth team, %d got through", total)
+	}
+}
+
+func TestATeamStillStopsBeforeItsOrganizationDoes(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := func() auth.Principal {
+		return inTree("k1", orgBudget("o", 100_000), teamBudget("t1", 800))
+	}
+
+	res, err := a.Check(p(), "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 200, CompletionTokens: 200})
+
+	// The narrower pool binds first, which is what it is for. Enforcing every
+	// level must not stop the tighter one working.
+	if _, err := a.Check(p(), "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("the team's own budget should still bite, got %v", err)
+	}
+}
+
+func TestSpendingFillsEveryPoolAboveIt(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := inTree("k1", orgBudget("o", 5000), teamBudget("t1", 5000))
+
+	res, err := a.Check(p, "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 200, CompletionTokens: 200})
+
+	// Settled onto both, or the organization's pool would only ever fill from
+	// requests that named it directly — which is none of them.
+	if got := a.budgets.Spent("org:o", store.PeriodMonth); got == 0 {
+		t.Error("the organization's pool did not fill")
+	}
+	if got := a.budgets.Spent("team:t1", store.PeriodMonth); got == 0 {
+		t.Error("the team's pool did not fill")
+	}
+}
+
+func TestARefusalHandsBackWhatTheNarrowerLevelsTook(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	// The team allows plenty; the organization allows one request a minute.
+	chain := []store.Limits{
+		{Scope: store.ScopeOrg, ScopeID: "o", RPM: intp(1)},
+		{Scope: store.ScopeTeam, ScopeID: "t1", RPM: intp(100)},
+	}
+	if _, err := a.Check(inTree("k1", chain...), "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	before := a.requests.Rate("team:t1")
+
+	if _, err := a.Check(inTree("k2", chain...), "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Fatalf("the organization should have refused the second, got %v", err)
+	}
+
+	// A rate limiter charges as it checks, so a refusal further along has
+	// already taken from the levels before it. Left there, a team at its
+	// organization's ceiling would quietly eat its own rate limit with requests
+	// that were never served.
+	if after := a.requests.Rate("team:t1"); after != before {
+		t.Errorf("the refused request stayed charged to the team: %v -> %v", before, after)
+	}
+}
+
+func TestAChainWithNoLimitsAnywhereAllowsEverything(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	for i := 0; i < 5; i++ {
+		if _, err := a.Check(inTree("k1"), "paid", 1000); err != nil {
+			t.Fatalf("nothing is limited, but request %d was refused: %v", i, err)
+		}
+	}
+}
+
+func TestStatusReportsTheFullestPoolNotTheSmallestNumber(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	chain := func(team string) auth.Principal {
+		return inTree(team+"-k", orgBudget("o", 9000), teamBudget(team, 9000))
+	}
+
+	// Another team spends; this one has spent nothing of its own.
+	res, err := a.Check(chain("t1"), "paid", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "t1-k", PromptTokens: 200, CompletionTokens: 200})
+
+	spent, _, _ := a.Status(chain("t2"))
+	// The organization's pool is the one nearer its ceiling, so it is the one
+	// that will refuse them. Reporting the team's nil would disagree with the
+	// refusal that eventually follows it.
+	if spent == 0 {
+		t.Error("a member should see the fullest pool that bounds them")
+	}
+}
+
+func TestAnEmptyPriceTableMeansNoBudgetCanEverBind(t *testing.T) {
+	// The ordinary case for self-hosted models, and the reason a budget on a
+	// team can read as a limit while binding on nothing.
+	if NewPricing(nil, Price{}).AnythingPriced() {
+		t.Error("nothing priced should say so")
+	}
+	if NewPricing(map[string]Price{"m": {}}, Price{}).AnythingPriced() {
+		t.Error("a model priced at zero is not priced")
+	}
+	if !NewPricing(map[string]Price{"m": {PromptPer1k: 1}}, Price{}).AnythingPriced() {
+		t.Error("one priced model is enough for a budget to move")
+	}
+	if !NewPricing(nil, Price{CompletionPer1k: 1}).AnythingPriced() {
+		t.Error("a fallback price prices everything")
+	}
+	var nilPricing *Pricing
+	if nilPricing.AnythingPriced() {
+		t.Error("no price table at all is not priced")
+	}
+}
+
+func TestHeadroomIsTheTightestLimitAfterThisRequest(t *testing.T) {
+	// A project allowing 100 a minute under a team allowing 3: the team is
+	// what will refuse, so the team is what a client is told about.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) {
+		e.Chain = []store.Limits{
+			{Scope: store.ScopeProject, ScopeID: "proj", RPM: intp(100), TPM: intp(50000)},
+			{Scope: store.ScopeTeam, ScopeID: "team", RPM: intp(3)},
+		}
+	})
+	if _, err := a.Check(p, "m", 10); err != nil {
+		t.Fatal(err)
+	}
+	h := a.Headroom(p)
+	if h.RequestLimit != 3 || h.RequestsLeft != 2 {
+		t.Errorf("requests %d left of %d; expected 2 of the team's 3", h.RequestsLeft, h.RequestLimit)
+	}
+	if h.TokenLimit != 50000 || h.TokensLeft != 50000-10 {
+		t.Errorf("tokens %d left of %d", h.TokensLeft, h.TokenLimit)
+	}
+	if h.Reset <= 0 || h.Reset > time.Minute {
+		t.Errorf("reset %v", h.Reset)
+	}
+	if none := a.Headroom(principal("k2", nil)); none.RequestLimit != 0 || none.TokenLimit != 0 {
+		t.Errorf("a key with no limits advertised some: %+v", none)
+	}
+}
+
+func TestAFallbackIsChargedWhatTheModelThatAnsweredCosts(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := inTree("fb-k", teamBudget("fb", 1_000_000))
+	res, err := a.Check(p, "paid", 400)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Asked for "paid", answered by "free": nothing is owed.
+	a.Record(res, store.Usage{KeyID: "fb-k", Model: "paid", ServedModel: "free", PromptTokens: 200, CompletionTokens: 200})
+	if spent, _, _ := a.Status(p); spent != 0 {
+		t.Errorf("charged %d for a request the free model answered", spent)
+	}
+	res, _ = a.Check(p, "paid", 400)
+	a.Record(res, store.Usage{KeyID: "fb-k", Model: "paid", ServedModel: "paid", PromptTokens: 200, CompletionTokens: 200})
+	if spent, _, _ := a.Status(p); spent == 0 {
+		t.Error("the paid model answering cost nothing")
+	}
+}
+
+func TestASpentBudgetTellsSomeoneOnce(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	n, sent := notifytest.Catch(t)
+	a.SetNotifier(n)
+	p := principal("k1", func(e *store.Effective) {
+		e.Budget = i64p(100)
+		e.BudgetPeriod = store.PeriodMonth
+	})
+	res, err := a.Check(p, "paid", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000})
+	for range 3 {
+		if _, err := a.Check(p, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+			t.Fatalf("not refused: %v", err)
+		}
+	}
+	got := sent()
+	if len(got) != 1 || got[0].Kind != notify.BudgetSpent || !strings.Contains(got[0].Message, "month") {
+		t.Fatalf("sent %+v, want one budget_spent", got)
+	}
+}

internal/accounting/budget.go

@@ -0,0 +1,114 @@
+package accounting
+
+import (
+	"sync"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// PeriodStart is when the current budget period began.
+//
+// Periods are anchored to UTC rather than to a per-key start date, so every
+// key's day and month boundary is the same instant. A key whose period started
+// when it was created would make "spend this month" mean something different
+// for every key, and make the restore query unanswerable in one pass.
+func PeriodStart(p store.Period, now time.Time) time.Time {
+	u := now.UTC()
+	switch p {
+	case store.PeriodDay:
+		return time.Date(u.Year(), u.Month(), u.Day(), 0, 0, 0, 0, time.UTC)
+	case store.PeriodMonth:
+		return time.Date(u.Year(), u.Month(), 1, 0, 0, 0, 0, time.UTC)
+	default:
+		return time.Time{}
+	}
+}
+
+// Budgets tracks spend per key in memory, so a budget check costs no query.
+//
+// The database catches up through the batch writer. That means the in-memory
+// figure leads the stored one, which is the right direction: a budget that only
+// counted what had already been written would let a burst overspend by however
+// much the writer was behind.
+type Budgets struct {
+	now func() time.Time
+
+	mu    sync.Mutex
+	spend map[string]counter
+}
+
+type counter struct {
+	micros int64
+	since  time.Time
+}
+
+// NewBudgets builds an empty tracker.
+func NewBudgets() *Budgets {
+	return &Budgets{now: time.Now, spend: map[string]counter{}}
+}
+
+// Restore seeds the counters from what the store already recorded.
+//
+// A restart must not reset a budget, which it would if the counter lived only
+// in memory. The caller passes the spend since each period's start.
+func (b *Budgets) Restore(period store.Period, spend map[string]int64) {
+	start := PeriodStart(period, b.now())
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for key, micros := range spend {
+		b.spend[key] = counter{micros: micros, since: start}
+	}
+}
+
+// Raise lifts counters to the spend given, where it is more.
+func (b *Budgets) Raise(period store.Period, spend map[string]int64) {
+	start := PeriodStart(period, b.now())
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for key, micros := range spend {
+		if c := b.currentLocked(key, start); micros > c.micros {
+			c.micros = micros
+			b.spend[key] = c
+		}
+	}
+}
+
+// Spent returns a key's spend in the current period, resetting it if the period
+// has rolled over.
+func (b *Budgets) Spent(keyID string, period store.Period) int64 {
+	start := PeriodStart(period, b.now())
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.currentLocked(keyID, start).micros
+}
+
+// Add records spend.
+func (b *Budgets) Add(keyID string, period store.Period, micros int64) {
+	if micros == 0 {
+		return
+	}
+	start := PeriodStart(period, b.now())
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	c := b.currentLocked(keyID, start)
+	c.micros += micros
+	b.spend[keyID] = c
+}
+
+// Exhausted reports whether a key has spent its budget.
+func (b *Budgets) Exhausted(keyID string, period store.Period, budget int64) bool {
+	return b.Spent(keyID, period) >= budget
+}
+
+// currentLocked returns the counter, rolled over if the period changed.
+func (b *Budgets) currentLocked(keyID string, start time.Time) counter {
+	c, ok := b.spend[keyID]
+	if !ok || c.since.Before(start) {
+		// Either never seen, or the period rolled over while the process was
+		// running. Both start from zero.
+		c = counter{since: start}
+		b.spend[keyID] = c
+	}
+	return c
+}

internal/accounting/cost.go

@@ -0,0 +1,121 @@
+// Package accounting turns finished requests into spend, enforces what a key
+// is allowed, and gets both into the store without touching the request path
+// (plan §7.9.3, §7.9.4).
+package accounting
+
+import (
+	"strings"
+	"sync"
+)
+
+// Price is what one model costs, in micro-units per thousand tokens.
+//
+// Micro-units rather than a float because spend is accumulated by repeated
+// addition, and repeated addition of floats drifts. What a unit means is the
+// operator's: self-hosted models have no per-token price, so it may be
+// GPU-seconds, a notional rate, or 1000 everywhere — which turns a budget into
+// a token quota.
+type Price struct {
+	PromptPer1k     int64 `koanf:"prompt_per_1k"`
+	CompletionPer1k int64 `koanf:"completion_per_1k"`
+	// CachedPer1k is what a prompt token costs that the engine or provider
+	// read from its cache instead of computing: the part of prompt_tokens
+	// the answer counts as cached_tokens. Zero charges those at
+	// PromptPer1k, as before there was a rate for them.
+	CachedPer1k int64 `koanf:"cached_per_1k"`
+	// PerImage is what one picture costs, for a model that makes them: a
+	// picture's cost is the card's time, which its prompt's few tokens do
+	// not measure.
+	PerImage int64 `koanf:"per_image"`
+	// PerMesh is what one 3D model costs: minutes of a card, which no
+	// token count measures.
+	PerMesh int64 `koanf:"per_mesh"`
+}
+
+// Zero reports whether this model spends nothing.
+//
+// It matters beyond arithmetic: a zero-cost model stays available to a key
+// whose budget is spent, which is what makes the plan's budget fallback work
+// (§7.7).
+func (p Price) Zero() bool {
+	return p.PromptPer1k == 0 && p.CompletionPer1k == 0 && p.CachedPer1k == 0 && p.PerImage == 0 && p.PerMesh == 0
+}
+
+// Cost computes what a request spent, rounding up.
+//
+// Up rather than to nearest: rounding down would make a stream of tiny requests
+// free, which is exactly the shape of traffic a quota exists to bound.
+//
+// cachedTokens are counted within promptTokens, as OpenAI's usage counts
+// them, and are charged at the cached rate instead of the prompt rate.
+func (p Price) Cost(promptTokens, cachedTokens, completionTokens, images, meshes int64) int64 {
+	cachedTokens = min(max(cachedTokens, 0), max(promptTokens, 0))
+	cachedRate := p.CachedPer1k
+	if cachedRate == 0 {
+		cachedRate = p.PromptPer1k
+	}
+	return divUp((promptTokens-cachedTokens)*p.PromptPer1k+cachedTokens*cachedRate, 1000) +
+		divUp(completionTokens*p.CompletionPer1k, 1000) +
+		max(images, 0)*p.PerImage + max(meshes, 0)*p.PerMesh
+}
+
+func divUp(n, d int64) int64 {
+	if n <= 0 {
+		return 0
+	}
+	return (n + d - 1) / d
+}
+
+// Pricing resolves a model name to its price.
+type Pricing struct {
+	mu       sync.RWMutex
+	byModel  map[string]Price
+	fallback Price
+}
+
+// NewPricing builds a price table. Names are matched case-insensitively,
+// because a model name reaches us from whatever the client typed.
+func NewPricing(byModel map[string]Price, fallback Price) *Pricing {
+	table := make(map[string]Price, len(byModel))
+	for name, p := range byModel {
+		table[strings.ToLower(name)] = p
+	}
+	return &Pricing{byModel: table, fallback: fallback}
+}
+
+// For returns a model's price, or the fallback.
+func (p *Pricing) For(model string) Price {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	if v, ok := p.byModel[strings.ToLower(model)]; ok {
+		return v
+	}
+	return p.fallback
+}
+
+// AnythingPriced reports whether any model costs anything.
+//
+// A budget is spend per period, and spend is computed from a price table. With
+// no prices every request costs nothing, so a budget written on a team is a
+// number that can never move — displayed as a limit, reported as zero percent
+// used, and binding on nothing.
+//
+// Self-hosted models have no per-token price, so an empty table is the ordinary
+// case rather than a misconfiguration. What is not ordinary is showing somebody
+// a budget without saying so.
+func (p *Pricing) AnythingPriced() bool {
+	if p == nil {
+		return false
+	}
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	if !p.fallback.Zero() {
+		return true
+	}
+	for _, price := range p.byModel {
+		if !price.Zero() {
+			return true
+		}
+	}
+	return false
+}

internal/accounting/limiter.go

@@ -0,0 +1,137 @@
+package accounting
+
+import (
+	"sync"
+	"time"
+)
+
+// Limiter enforces per-key rate limits.
+//
+// A sliding window rather than a fixed one. A fixed window lets a caller send
+// its whole minute's allowance in the last second of one window and again in
+// the first second of the next, so the observed rate is twice the configured
+// limit exactly when the system is least able to take it.
+//
+// The window is approximated from two buckets, which is the usual compromise:
+// exact enough that the doubling cannot happen, and bounded memory per key
+// rather than a timestamp per request.
+type Limiter struct {
+	now func() time.Time
+
+	mu   sync.Mutex
+	keys map[string]*window
+}
+
+type window struct {
+	// current and previous are counts in this minute and the one before.
+	current, previous int64
+	// othersCurrent and othersPrevious are the same counts on the other
+	// control planes taking requests, as last heard: what makes a limit the
+	// cluster's rather than each process's.
+	othersCurrent, othersPrevious int64
+	start                         time.Time
+}
+
+// NewLimiter builds an empty limiter.
+func NewLimiter() *Limiter {
+	return &Limiter{now: time.Now, keys: map[string]*window{}}
+}
+
+const windowLen = time.Minute
+
+// Allow charges n against a key's limit and reports whether it fits.
+//
+// Charging and checking are one operation on purpose: doing them separately
+// lets two concurrent requests both see room and both take it.
+func (l *Limiter) Allow(key string, limit int, n int64) bool {
+	if limit <= 0 {
+		// No limit configured. Zero would be a limit of zero, which is why
+		// callers pass a nil pointer rather than 0 for "unset".
+		return true
+	}
+	now := l.now()
+
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	w := l.windowLocked(key, now)
+	if w.rate(now)+float64(n) > float64(limit) {
+		return false
+	}
+	w.current += n
+	return true
+}
+
+// Charge records usage that was already allowed, for reconciliation.
+//
+// Token limits are checked against an estimate before the request runs, because
+// the real figure only exists once it has. The difference is charged here, so a
+// caller whose requests are consistently larger than estimated is still bounded
+// — one window later than it would be with a perfect estimate.
+func (l *Limiter) Charge(key string, n int64) {
+	if n == 0 {
+		return
+	}
+	now := l.now()
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	w := l.windowLocked(key, now)
+	w.current += n
+	if w.current < 0 {
+		w.current = 0
+	}
+}
+
+// Rate returns a key's current observed rate.
+func (l *Limiter) Rate(key string) float64 {
+	now := l.now()
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.windowLocked(key, now).rate(now)
+}
+
+func (l *Limiter) windowLocked(key string, now time.Time) *window {
+	w, ok := l.keys[key]
+	if !ok {
+		w = &window{start: now.Truncate(windowLen)}
+		l.keys[key] = w
+	}
+	w.roll(now)
+	return w
+}
+
+// roll advances the window to now.
+func (w *window) roll(now time.Time) {
+	start := now.Truncate(windowLen)
+	switch {
+	case start.Equal(w.start):
+		return
+	case start.Sub(w.start) == windowLen:
+		w.previous, w.current = w.current, 0
+		w.othersPrevious, w.othersCurrent = w.othersCurrent, 0
+	default:
+		// More than one window has passed with no traffic.
+		w.previous, w.current = 0, 0
+		w.othersPrevious, w.othersCurrent = 0, 0
+	}
+	w.start = start
+}
+
+// rate weights the previous window by how much of it is still in view.
+func (w *window) rate(now time.Time) float64 {
+	cur, prev := w.current+w.othersCurrent, w.previous+w.othersPrevious
+	elapsed := now.Sub(w.start)
+	if elapsed >= windowLen {
+		return float64(cur)
+	}
+	remaining := 1 - float64(elapsed)/float64(windowLen)
+	return float64(prev)*remaining + float64(cur)
+}
+
+// Forget drops a key's window. Used when a key is revoked; keeping it would
+// leak memory for every key that ever called.
+func (l *Limiter) Forget(key string) {
+	l.mu.Lock()
+	delete(l.keys, key)
+	l.mu.Unlock()
+}

internal/accounting/people_test.go

@@ -0,0 +1,126 @@
+package accounting
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// peopleStore has Acme/ml/training with two members, ayse and deniz.
+func peopleStore(t *testing.T) (*store.DB, string) {
+	t.Helper()
+	ctx := context.Background()
+	s, err := store.OpenSQLite(ctx, filepath.Join(t.TempDir(), "p.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	org, _ := s.CreateOrg(ctx, "Acme")
+	team, _ := s.CreateTeam(ctx, org, "ml")
+	proj, _ := s.CreateProject(ctx, team, "training")
+	for _, id := range []string{"ayse", "deniz"} {
+		if err := s.CreateUser(ctx, store.User{ID: id, Email: id + "@x", Name: id,
+			PasswordHash: "h", State: store.UserPending, CreatedAt: time.Now()}); err != nil {
+			t.Fatal(err)
+		}
+		if err := s.ApproveUser(ctx, id, proj, "test", time.Now()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return s, proj
+}
+
+// keyFor makes a key for a person and resolves it the way authentication does.
+func keyFor(t *testing.T, s *store.DB, id, user, project string) auth.Principal {
+	t.Helper()
+	ctx := context.Background()
+	_, k, _ := store.NewKey(id, id, project)
+	if err := s.CreateUserKey(ctx, user, k); err != nil {
+		t.Fatal(err)
+	}
+	e, err := s.Resolve(ctx, id)
+	if err != nil {
+		t.Fatalf("resolving %s: %v", id, err)
+	}
+	return auth.Principal{KeyID: id, UserID: e.UserID, ProjectID: e.ProjectID, Limits: e}
+}
+
+func TestAPersonsLimitIsOnePoolAcrossTheirKeys(t *testing.T) {
+	s, proj := peopleStore(t)
+	if err := s.PutLimits(context.Background(),
+		store.Limits{Scope: store.ScopeUser, ScopeID: "ayse", RPM: intp(2)}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	personal := keyFor(t, s, "k-personal", "ayse", "")
+	inProject := keyFor(t, s, "k-project", "ayse", proj)
+
+	// Two requests, one on each key, use up the person's two a minute.
+	for _, p := range []auth.Principal{personal, inProject} {
+		if _, err := a.Check(p, "free", 1); err != nil {
+			t.Fatalf("%s: %v", p.KeyID, err)
+		}
+	}
+	if _, err := a.Check(personal, "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Errorf("a third request across her keys was allowed: %v", err)
+	}
+	// Deniz is somebody else.
+	if _, err := a.Check(keyFor(t, s, "k-deniz", "deniz", proj), "free", 1); err != nil {
+		t.Errorf("another person was limited by hers: %v", err)
+	}
+}
+
+func TestAPerMemberLimitCountsEachMemberApart(t *testing.T) {
+	s, proj := peopleStore(t)
+	if err := s.PutLimits(context.Background(),
+		store.Limits{Scope: store.ScopeProjectMember, ScopeID: proj, RPM: intp(1)}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	ayse := keyFor(t, s, "k-a", "ayse", proj)
+	deniz := keyFor(t, s, "k-d", "deniz", proj)
+
+	if _, err := a.Check(ayse, "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Check(ayse, "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Errorf("her second request passed a one-a-minute per-member limit: %v", err)
+	}
+	// Her share is hers: Deniz still has his.
+	if _, err := a.Check(deniz, "free", 1); err != nil {
+		t.Errorf("one member's use counted against another: %v", err)
+	}
+	// And outside the project it does not apply at all.
+	if _, err := a.Check(keyFor(t, s, "k-a-own", "ayse", ""), "free", 1); err != nil {
+		t.Errorf("a project's per-member limit held her personal key: %v", err)
+	}
+}
+
+func TestAPersonsBudgetSurvivesARestart(t *testing.T) {
+	s, _ := peopleStore(t)
+	ctx := context.Background()
+	if err := s.PutLimits(ctx, store.Limits{Scope: store.ScopeUser, ScopeID: "ayse",
+		Budget: i64p(1000), BudgetPeriod: store.PeriodMonth}); err != nil {
+		t.Fatal(err)
+	}
+	// Spent before the restart, personally and on the chat page.
+	if err := s.WriteUsage(ctx, []store.Usage{
+		{At: time.Now(), KeyID: "k-old", UserID: "ayse", CostMicros: 600, Model: "paid", ServedModel: "paid"},
+		{At: time.Now(), KeyID: "session:ayse", UserID: "ayse", CostMicros: 500, Model: "paid", ServedModel: "paid"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	if err := a.RestoreBudgets(ctx, s, store.PeriodMonth); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Check(keyFor(t, s, "k-new", "ayse", ""), "paid", 1); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("a restart forgot what she had spent: %v", err)
+	}
+}

internal/accounting/recorder.go

@@ -0,0 +1,189 @@
+package accounting
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// RecorderConfig tunes the batch writer.
+type RecorderConfig struct {
+	// FlushInterval and BatchSize decide when a batch is written. Whichever
+	// comes first.
+	FlushInterval time.Duration
+	BatchSize     int
+	// Capacity bounds the buffer. Beyond it, records are dropped rather than
+	// blocking a request — see Record.
+	Capacity int
+}
+
+// DefaultRecorderConfig returns sensible values.
+func DefaultRecorderConfig() RecorderConfig {
+	return RecorderConfig{FlushInterval: 200 * time.Millisecond, BatchSize: 500, Capacity: 8192}
+}
+
+func (c *RecorderConfig) normalize() {
+	d := DefaultRecorderConfig()
+	if c.FlushInterval <= 0 {
+		c.FlushInterval = d.FlushInterval
+	}
+	if c.BatchSize <= 0 {
+		c.BatchSize = d.BatchSize
+	}
+	if c.Capacity <= 0 {
+		c.Capacity = d.Capacity
+	}
+}
+
+// Toucher is the part of the authenticator the recorder flushes alongside
+// usage, so last-used timestamps ride the same transaction schedule.
+type Toucher interface {
+	FlushTouches(ctx context.Context) error
+}
+
+// Recorder batches usage records into the store.
+//
+// The buffered channel is the whole design. A request must never wait on a
+// database write, so Record is a non-blocking send and the writer drains it on
+// its own schedule.
+type Recorder struct {
+	cfg   RecorderConfig
+	store store.Store
+	touch Toucher
+	log   *slog.Logger
+
+	ch   chan store.Usage
+	done chan struct{}
+	wg   sync.WaitGroup
+
+	mu      sync.Mutex
+	dropped int64
+	written int64
+}
+
+// NewRecorder builds a recorder. Start begins writing.
+func NewRecorder(s store.Store, touch Toucher, cfg RecorderConfig, log *slog.Logger) *Recorder {
+	cfg.normalize()
+	if log == nil {
+		log = slog.Default()
+	}
+	return &Recorder{
+		cfg: cfg, store: s, touch: touch, log: log,
+		ch:   make(chan store.Usage, cfg.Capacity),
+		done: make(chan struct{}),
+	}
+}
+
+// Record queues one request's accounting.
+//
+// Never blocks. If the buffer is full — a database stalled long enough to fill
+// eight thousand records — the record is dropped and counted. Losing some
+// accounting is bad; making every request wait on a stalled database is worse,
+// because it converts a reporting problem into an outage.
+func (r *Recorder) Record(u store.Usage) {
+	select {
+	case r.ch <- u:
+	default:
+		r.mu.Lock()
+		r.dropped++
+		n := r.dropped
+		r.mu.Unlock()
+		if n == 1 || n%1000 == 0 {
+			r.log.Warn("dropping usage records: the store is not keeping up",
+				"dropped_total", n)
+		}
+	}
+}
+
+// Start runs the writer until ctx ends.
+func (r *Recorder) Start(ctx context.Context) {
+	r.wg.Add(1)
+	go func() {
+		defer r.wg.Done()
+		defer close(r.done)
+		r.run(ctx)
+	}()
+}
+
+// Stop waits for the writer to drain and finish.
+func (r *Recorder) Stop() { r.wg.Wait() }
+
+func (r *Recorder) run(ctx context.Context) {
+	t := time.NewTicker(r.cfg.FlushInterval)
+	defer t.Stop()
+
+	batch := make([]store.Usage, 0, r.cfg.BatchSize)
+	for {
+		select {
+		case <-ctx.Done():
+			// Drain what is already queued before leaving. These are completed
+			// requests that have already been served; throwing them away would
+			// mean a clean shutdown silently loses the last moments of billing.
+			r.drain(&batch)
+			r.flush(context.WithoutCancel(ctx), batch)
+			return
+
+		case u := <-r.ch:
+			batch = append(batch, u)
+			if len(batch) >= r.cfg.BatchSize {
+				r.flush(ctx, batch)
+				batch = batch[:0]
+			}
+
+		case <-t.C:
+			r.drain(&batch)
+			if len(batch) > 0 {
+				r.flush(ctx, batch)
+				batch = batch[:0]
+			}
+			if err := r.touchFlush(ctx); err != nil {
+				r.log.Warn("failed to write last-used timestamps", "err", err)
+			}
+		}
+	}
+}
+
+// drain moves everything queued into the batch without blocking.
+func (r *Recorder) drain(batch *[]store.Usage) {
+	for len(*batch) < r.cfg.BatchSize {
+		select {
+		case u := <-r.ch:
+			*batch = append(*batch, u)
+		default:
+			return
+		}
+	}
+}
+
+func (r *Recorder) flush(ctx context.Context, batch []store.Usage) {
+	if len(batch) == 0 {
+		return
+	}
+	if err := r.store.WriteUsage(ctx, batch); err != nil {
+		// The records are gone either way; what matters is that this is loud.
+		// Silently losing billing data is the kind of thing discovered at the
+		// end of a month.
+		r.log.Error("failed to write usage records", "count", len(batch), "err", err)
+		return
+	}
+	r.mu.Lock()
+	r.written += int64(len(batch))
+	r.mu.Unlock()
+}
+
+func (r *Recorder) touchFlush(ctx context.Context) error {
+	if r.touch == nil {
+		return nil
+	}
+	return r.touch.FlushTouches(ctx)
+}
+
+// Stats reports what the recorder has done, for metrics and tests.
+func (r *Recorder) Stats() (written, dropped int64) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.written, r.dropped
+}

internal/accounting/recorder_test.go

@@ -0,0 +1,210 @@
+package accounting
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// fakeStore records what was written and can be made slow or broken.
+type fakeStore struct {
+	store.Store
+
+	mu      sync.Mutex
+	batches [][]store.Usage
+
+	block   chan struct{}
+	fail    atomic.Bool
+	touched atomic.Int64
+}
+
+func (f *fakeStore) WriteUsage(_ context.Context, rows []store.Usage) error {
+	if f.block != nil {
+		<-f.block
+	}
+	if f.fail.Load() {
+		return errors.New("store is down")
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.batches = append(f.batches, append([]store.Usage(nil), rows...))
+	return nil
+}
+
+func (f *fakeStore) rows() []store.Usage {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []store.Usage
+	for _, b := range f.batches {
+		out = append(out, b...)
+	}
+	return out
+}
+
+func (f *fakeStore) batchCount() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.batches)
+}
+
+type fakeToucher struct{ n *atomic.Int64 }
+
+func (f fakeToucher) FlushTouches(context.Context) error {
+	f.n.Add(1)
+	return nil
+}
+
+func TestRecordsAreBatchedNotWrittenOneByOne(t *testing.T) {
+	// The whole point of the buffer: a hundred requests must not be a hundred
+	// transactions.
+	f := &fakeStore{}
+	r := NewRecorder(f, nil, RecorderConfig{FlushInterval: 20 * time.Millisecond, BatchSize: 500},
+		slog.New(slog.DiscardHandler))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	r.Start(ctx)
+
+	for i := range 100 {
+		r.Record(store.Usage{KeyID: "k", PromptTokens: int64(i)})
+	}
+	waitFor(t, time.Second, func() bool { return len(f.rows()) == 100 })
+
+	if n := f.batchCount(); n > 5 {
+		t.Errorf("100 records took %d transactions", n)
+	}
+	cancel()
+	r.Stop()
+}
+
+func TestRecordNeverBlocksARequest(t *testing.T) {
+	// A stalled database must not become an outage. Losing accounting is bad;
+	// making every request wait on the store is worse.
+	f := &fakeStore{block: make(chan struct{})}
+	r := NewRecorder(f, nil, RecorderConfig{
+		FlushInterval: time.Millisecond, BatchSize: 1, Capacity: 8,
+	}, slog.New(slog.DiscardHandler))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	r.Start(ctx)
+	defer func() { close(f.block); cancel(); r.Stop() }()
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for range 1000 {
+			r.Record(store.Usage{KeyID: "k"})
+		}
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("Record blocked while the store was stalled")
+	}
+
+	_, dropped := r.Stats()
+	if dropped == 0 {
+		t.Error("the overflow was not counted, so nobody would ever know")
+	}
+}
+
+func TestAShutdownDoesNotLoseWhatIsAlreadyQueued(t *testing.T) {
+	// Those are completed requests that were already served. Throwing them away
+	// means a clean shutdown silently loses the last moments of billing.
+	f := &fakeStore{}
+	r := NewRecorder(f, nil, RecorderConfig{FlushInterval: time.Hour, BatchSize: 10_000},
+		slog.New(slog.DiscardHandler))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	r.Start(ctx)
+
+	for range 50 {
+		r.Record(store.Usage{KeyID: "k"})
+	}
+	cancel()
+	r.Stop()
+
+	if got := len(f.rows()); got != 50 {
+		t.Errorf("a clean shutdown wrote %d of 50 queued records", got)
+	}
+}
+
+func TestAFailedWriteIsLoudRatherThanSilent(t *testing.T) {
+	// Silently losing billing data is the kind of thing discovered at the end
+	// of a month.
+	f := &fakeStore{}
+	f.fail.Store(true)
+	logged := &countingHandler{}
+	r := NewRecorder(f, nil, RecorderConfig{FlushInterval: 10 * time.Millisecond, BatchSize: 1},
+		slog.New(logged))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	r.Start(ctx)
+	r.Record(store.Usage{KeyID: "k"})
+
+	waitFor(t, time.Second, func() bool { return logged.count(slog.LevelError) > 0 })
+	cancel()
+	r.Stop()
+
+	if written, _ := r.Stats(); written != 0 {
+		t.Errorf("a failed write was counted as %d written", written)
+	}
+}
+
+func TestLastUsedRidesTheSameSchedule(t *testing.T) {
+	var n atomic.Int64
+	f := &fakeStore{}
+	r := NewRecorder(f, fakeToucher{n: &n}, RecorderConfig{FlushInterval: 10 * time.Millisecond},
+		slog.New(slog.DiscardHandler))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	r.Start(ctx)
+	waitFor(t, time.Second, func() bool { return n.Load() > 0 })
+	cancel()
+	r.Stop()
+}
+
+type countingHandler struct {
+	mu     sync.Mutex
+	levels []slog.Level
+}
+
+func (c *countingHandler) Enabled(context.Context, slog.Level) bool { return true }
+func (c *countingHandler) WithAttrs([]slog.Attr) slog.Handler       { return c }
+func (c *countingHandler) WithGroup(string) slog.Handler            { return c }
+func (c *countingHandler) Handle(_ context.Context, r slog.Record) error {
+	c.mu.Lock()
+	c.levels = append(c.levels, r.Level)
+	c.mu.Unlock()
+	return nil
+}
+
+func (c *countingHandler) count(l slog.Level) int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	n := 0
+	for _, got := range c.levels {
+		if got == l {
+			n++
+		}
+	}
+	return n
+}
+
+func waitFor(t *testing.T, limit time.Duration, pred func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(limit)
+	for time.Now().Before(deadline) {
+		if pred() {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatal("condition never became true")
+}

internal/accounting/shared.go

@@ -0,0 +1,110 @@
+package accounting
+
+import "time"
+
+// Counts are one limiter's counts by counter: this minute's and the one
+// before, as absolute figures, so reporting them twice changes nothing.
+type Counts struct {
+	Minute   time.Time        `json:"minute"`
+	Current  map[string]int64 `json:"current,omitempty"`
+	Previous map[string]int64 `json:"previous,omitempty"`
+}
+
+// Add sums other into c, aligned to c's minute: counts of a minute that is
+// c's previous one land there, older ones are dropped. Clocks a second apart
+// at a minute's turn are why.
+func (c *Counts) Add(other Counts) {
+	switch {
+	case other.Minute.Equal(c.Minute):
+		c.Current = addInto(c.Current, other.Current)
+		c.Previous = addInto(c.Previous, other.Previous)
+	case other.Minute.Add(windowLen).Equal(c.Minute):
+		c.Previous = addInto(c.Previous, other.Current)
+	}
+}
+
+func addInto(dst, src map[string]int64) map[string]int64 {
+	if len(src) == 0 {
+		return dst
+	}
+	if dst == nil {
+		dst = make(map[string]int64, len(src))
+	}
+	for k, v := range src {
+		dst[k] += v
+	}
+	return dst
+}
+
+// Counts reads this limiter's own counts, without the others'.
+func (l *Limiter) Counts() Counts {
+	now := l.now()
+	out := Counts{Minute: now.Truncate(windowLen), Current: map[string]int64{}, Previous: map[string]int64{}}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	for k, w := range l.keys {
+		w.roll(now)
+		if w.current > 0 {
+			out.Current[k] = w.current
+		}
+		if w.previous > 0 {
+			out.Previous[k] = w.previous
+		}
+	}
+	return out
+}
+
+// SetOthers replaces what the other control planes have counted. A counter
+// they did not mention has nothing from them.
+func (l *Limiter) SetOthers(c Counts) {
+	now := l.now()
+	aligned := Counts{Minute: now.Truncate(windowLen)}
+	aligned.Add(c)
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	for k, w := range l.keys {
+		w.roll(now)
+		w.othersCurrent, w.othersPrevious = aligned.Current[k], aligned.Previous[k]
+		delete(aligned.Current, k)
+		delete(aligned.Previous, k)
+	}
+	// Counters only others have used yet: a key spread over the cluster is
+	// limited here from its first request.
+	for k := range aligned.Current {
+		w := l.windowLocked(k, now)
+		w.othersCurrent, w.othersPrevious = aligned.Current[k], aligned.Previous[k]
+		delete(aligned.Previous, k)
+	}
+	for k, v := range aligned.Previous {
+		l.windowLocked(k, now).othersPrevious = v
+	}
+}
+
+// Rates are an accountant's two limiters' counts.
+type Rates struct {
+	Requests Counts `json:"requests"`
+	Tokens   Counts `json:"tokens"`
+}
+
+// Add sums other into r.
+func (r *Rates) Add(other Rates) {
+	r.Requests.Add(other.Requests)
+	r.Tokens.Add(other.Tokens)
+}
+
+// NewRates is an empty sum for the minute now is in.
+func NewRates(now time.Time) Rates {
+	m := now.Truncate(windowLen)
+	return Rates{Requests: Counts{Minute: m}, Tokens: Counts{Minute: m}}
+}
+
+// Rates reads this process's own request and token counts.
+func (a *Accountant) Rates() Rates {
+	return Rates{Requests: a.requests.Counts(), Tokens: a.tokens.Counts()}
+}
+
+// SetOtherRates puts the other control planes' counts in force here.
+func (a *Accountant) SetOtherRates(r Rates) {
+	a.requests.SetOthers(r.Requests)
+	a.tokens.SetOthers(r.Tokens)
+}

internal/accounting/shared_test.go

@@ -0,0 +1,71 @@
+package accounting
+
+import (
+	"testing"
+	"time"
+)
+
+// Two control planes each allowing a key six of its ten a minute: once each
+// has heard the other's count, neither allows another.
+func TestALimitIsTheClustersOnceTheCountsAreShared(t *testing.T) {
+	now := time.Date(2026, 11, 1, 12, 0, 10, 0, time.UTC)
+	a, b := NewLimiter(), NewLimiter()
+	a.now, b.now = func() time.Time { return now }, func() time.Time { return now }
+	for range 6 {
+		if !a.Allow("k", 10, 1) || !b.Allow("k", 10, 1) {
+			t.Fatal("refused within the limit")
+		}
+	}
+	a.SetOthers(b.Counts())
+	b.SetOthers(a.Counts())
+	if a.Allow("k", 10, 1) || b.Allow("k", 10, 1) {
+		t.Error("twelve of ten allowed once both knew")
+	}
+	// Reporting the same counts again changes nothing: they are absolute.
+	a.SetOthers(b.Counts())
+	if got := a.Rate("k"); got != 12 {
+		t.Errorf("rate %v after the same counts twice", got)
+	}
+	// What the others counted is never charged back to them.
+	if c := a.Counts(); c.Current["k"] != 6 {
+		t.Errorf("own count %d", c.Current["k"])
+	}
+}
+
+// A key only the others have used is limited here from its first request,
+// and their counts move into the previous minute with the clock.
+func TestOthersCountsFollowTheMinute(t *testing.T) {
+	now := time.Date(2026, 11, 1, 12, 0, 50, 0, time.UTC)
+	a, b := NewLimiter(), NewLimiter()
+	a.now, b.now = func() time.Time { return now }, func() time.Time { return now }
+	for range 10 {
+		b.Allow("k", 10, 1)
+	}
+	a.SetOthers(b.Counts())
+	if a.Allow("k", 10, 1) {
+		t.Error("a key the cluster has used up was allowed where it had not been seen")
+	}
+	now = now.Add(20 * time.Second) // 12:01:10, a sixth into the next minute
+	if got := a.Rate("k"); got < 8 || got > 8.5 {
+		t.Errorf("rate %v: the others' last minute should weigh five sixths", got)
+	}
+	// Counts of a minute ago, sent late, land in the previous minute.
+	old := b.Counts()
+	old.Minute = now.Truncate(time.Minute).Add(-time.Minute)
+	old.Current, old.Previous = map[string]int64{"k": 3}, nil
+	a.SetOthers(old)
+	if got := a.Rate("k"); got < 2 || got > 3 {
+		t.Errorf("rate %v from late counts", got)
+	}
+}
+
+func TestRatesAddAlignsMinutes(t *testing.T) {
+	m := time.Date(2026, 11, 1, 12, 1, 0, 0, time.UTC)
+	sum := NewRates(m)
+	sum.Add(Rates{Requests: Counts{Minute: m, Current: map[string]int64{"k": 2}, Previous: map[string]int64{"k": 1}}})
+	sum.Add(Rates{Requests: Counts{Minute: m.Add(-time.Minute), Current: map[string]int64{"k": 5}}})
+	sum.Add(Rates{Requests: Counts{Minute: m.Add(-2 * time.Minute), Current: map[string]int64{"k": 100}}})
+	if sum.Requests.Current["k"] != 2 || sum.Requests.Previous["k"] != 6 {
+		t.Errorf("sum %+v", sum.Requests)
+	}
+}

internal/accounting/suggest.go

@@ -0,0 +1,91 @@
+package accounting
+
+import (
+	"math"
+	"slices"
+)
+
+// Prices from what the cluster costs: what each model held of it (its
+// replicas' GPU- and core-hours) at what an hour of a GPU or a core costs
+// the operator, spread over the tokens it served. Idle time is in it: a
+// model held all month and used an hour costs what it held, not the hour.
+//
+// An output token is priced OutputPerInput input tokens, as producing one
+// is that much dearer (one step a token, against a prompt read in one
+// pass); a cached prompt token a tenth of an input one.
+const (
+	OutputPerInput = 4
+	CachedPerInput = 0.1
+)
+
+// Basis is what an hour costs, in the units budgets are in.
+type Basis struct {
+	GPUHour  float64
+	CoreHour float64
+}
+
+// Held is what a model held, and Served what it answered with.
+type Held struct {
+	GPUSeconds, CoreSeconds int64
+}
+
+// Served is a model's tokens.
+type Served struct {
+	Prompt, Completion int64
+}
+
+// Suggestion is one model's price from its cost.
+type Suggestion struct {
+	Model     string  `json:"model"`
+	GPUHours  float64 `json:"gpu_hours"`
+	CoreHours float64 `json:"core_hours"`
+	// Cost is what it held cost, in budget units.
+	Cost       float64 `json:"cost"`
+	Prompt     int64   `json:"prompt_tokens"`
+	Completion int64   `json:"completion_tokens"`
+	// Price is the suggestion; zero with a Note saying why there is none.
+	Price Price  `json:"price"`
+	Note  string `json:"note,omitempty"`
+}
+
+// Suggest prices every model that held something or served something.
+func Suggest(held map[string]Held, served map[string]Served, b Basis) []Suggestion {
+	var names []string
+	for m := range held {
+		names = append(names, m)
+	}
+	for m := range served {
+		if _, ok := held[m]; !ok {
+			names = append(names, m)
+		}
+	}
+	slices.Sort(names)
+	out := make([]Suggestion, 0, len(names))
+	for _, m := range names {
+		h, s := held[m], served[m]
+		g := Suggestion{Model: m, GPUHours: float64(h.GPUSeconds) / 3600, CoreHours: float64(h.CoreSeconds) / 3600,
+			Prompt: s.Prompt, Completion: s.Completion}
+		g.Cost = g.GPUHours*b.GPUHour + g.CoreHours*b.CoreHour
+		// Tokens counted as output ones: an input token is a fraction of one.
+		units := float64(s.Completion) + float64(s.Prompt)/OutputPerInput
+		switch {
+		case g.Cost == 0 && units > 0:
+			g.Note = "held nothing recorded here: an outside provider's, or served before the hours were kept"
+		case g.Cost > 0 && units == 0:
+			g.Note = "held the cluster and was billed no tokens (a guard's judge, or a model priced by the picture or 3D model): no one pays what it held"
+		case g.Cost > 0:
+			// Micro-units per thousand output tokens, rounded up so a
+			// cheap model is never free.
+			out1k := int64(math.Ceil(g.Cost / units * 1000 * 1e6))
+			g.Price = Price{
+				CompletionPer1k: out1k,
+				PromptPer1k:     ceilDiv(out1k, OutputPerInput),
+				CachedPer1k:     max(int64(math.Ceil(float64(ceilDiv(out1k, OutputPerInput))*CachedPerInput)), 1),
+			}
+		}
+		out = append(out, g)
+	}
+	return out
+}
+
+func ceilDiv(a, b int64) int64 { return (a + b - 1) / b }

internal/accounting/suggest_test.go

@@ -0,0 +1,45 @@
+package accounting
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSuggestSpreadsWhatAModelHeldOverItsTokens(t *testing.T) {
+	// The worked example: two cards for 1000 hours at 1.35 an hour is 2700;
+	// 3.0 billion output tokens and 4.0 billion input ones, counted as 1.0
+	// billion output ones, are 4.0 billion: 0.675 a million output tokens.
+	held := map[string]Held{
+		"llama-70b": {GPUSeconds: 2 * 1000 * 3600},
+		"idle":      {GPUSeconds: 3600},
+		"small-cpu": {CoreSeconds: 8 * 100 * 3600},
+	}
+	served := map[string]Served{
+		"llama-70b": {Prompt: 4_000_000_000, Completion: 3_000_000_000},
+		"small-cpu": {Prompt: 1_000_000, Completion: 1_000_000},
+		"outside":   {Prompt: 10, Completion: 10},
+	}
+	got := Suggest(held, served, Basis{GPUHour: 1.35, CoreHour: 0.01})
+	by := map[string]Suggestion{}
+	for _, s := range got {
+		by[s.Model] = s
+	}
+	l := by["llama-70b"]
+	if l.Cost != 2700 || l.Price.CompletionPer1k != 675 || l.Price.PromptPer1k != 169 || l.Price.CachedPer1k != 17 {
+		t.Errorf("llama: %+v", l)
+	}
+	// What it costs back at that price is what it held, within the rounding.
+	back := float64(l.Price.Cost(l.Prompt, 0, l.Completion, 0, 0)) / 1e6
+	if back < l.Cost || back > l.Cost*1.01 {
+		t.Errorf("charged %.2f for a cost of %.2f", back, l.Cost)
+	}
+	if s := by["small-cpu"]; s.Cost != 8 || s.Price.CompletionPer1k == 0 {
+		t.Errorf("cpu: %+v", s)
+	}
+	if s := by["idle"]; !s.Price.Zero() || !strings.Contains(s.Note, "billed no tokens") {
+		t.Errorf("idle: %+v", s)
+	}
+	if s := by["outside"]; !s.Price.Zero() || !strings.Contains(s.Note, "held nothing") {
+		t.Errorf("outside: %+v", s)
+	}
+}

internal/agent/agent_test.go

@@ -0,0 +1,947 @@
+package agent
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"testing"
+	"time"
+
+	"golang.org/x/net/http2"
+	"golang.org/x/net/http2/h2c"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/inventory"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/reconciler"
+)
+
+// statusRecorder captures what the control plane hears about shards, and what
+// it is asked to adopt.
+type statusRecorder struct {
+	ch chan status
+
+	mu       sync.Mutex
+	calls    []adoptCall
+	adopted  []reconciler.AdoptedShard
+	unclaim  []string // shard ids to report back as unclaimed
+	fetches  []fetchReport
+	computes []reconciler.Compute
+}
+
+type status struct {
+	replicaID, shardID string
+	state              supervisor.State
+	err                string
+}
+
+func newRecorder() *statusRecorder { return &statusRecorder{ch: make(chan status, 128)} }
+
+func (r *statusRecorder) OnShardStatus(replicaID, shardID string, st supervisor.State, errMsg string) {
+	select {
+	case r.ch <- status{replicaID, shardID, st, errMsg}:
+	default:
+	}
+}
+
+// fetches records download progress, so a test can assert that a fetch is
+// visible from the control plane rather than only in the node's log.
+func (r *statusRecorder) OnShardCompute(replicaID, shardID string, c reconciler.Compute) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.computes = append(r.computes, c)
+}
+
+func (r *statusRecorder) OnFetchProgress(replicaID, shardID, source, phase string, done, total int64) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.fetches = append(r.fetches, fetchReport{replicaID, shardID, source, done, total})
+}
+
+func (r *statusRecorder) fetchReports() []fetchReport {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return append([]fetchReport(nil), r.fetches...)
+}
+
+type fetchReport struct {
+	replicaID, shardID, source string
+	done, total                int64
+}
+
+func (r *statusRecorder) Adopt(nodeID string, shards []reconciler.AdoptedShard) []reconciler.AdoptedShard {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.calls = append(r.calls, adoptCall{nodeID: nodeID, shards: shards})
+	r.adopted = append(r.adopted, shards...)
+
+	var unclaimed []reconciler.AdoptedShard
+	for _, s := range shards {
+		if slices.Contains(r.unclaim, s.ShardID) {
+			unclaimed = append(unclaimed, s)
+		}
+	}
+	return unclaimed
+}
+
+// adoptCall records that the service reached the reconciler at all, which an
+// empty shard list used to prevent.
+type adoptCall struct {
+	nodeID string
+	shards []reconciler.AdoptedShard
+}
+
+func (r *statusRecorder) adoptCalls() []adoptCall {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return slices.Clone(r.calls)
+}
+
+func (r *statusRecorder) adoptedShards() []reconciler.AdoptedShard {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return slices.Clone(r.adopted)
+}
+
+func (r *statusRecorder) markUnclaimed(ids ...string) {
+	r.mu.Lock()
+	r.unclaim = append(r.unclaim, ids...)
+	r.mu.Unlock()
+}
+
+func (r *statusRecorder) await(t *testing.T, limit time.Duration, pred func(status) bool) status {
+	t.Helper()
+	deadline := time.After(limit)
+	var seen []status
+	for {
+		select {
+		case s := <-r.ch:
+			seen = append(seen, s)
+			if pred(s) {
+				return s
+			}
+		case <-deadline:
+			t.Fatalf("no matching status within %v; saw %+v", limit, seen)
+			return status{}
+		}
+	}
+}
+
+// fakeEngineScript writes a script that stands in for vLLM.
+//
+// It parses the real --port flag the vLLM adapter generates rather than being
+// told out of band, so the adapter's argument construction is exercised too.
+func fakeEngineScript(t *testing.T, body string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "fake-vllm")
+	script := `#!/bin/sh
+port=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port) port="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+` + body + "\n"
+	if err := os.WriteFile(path, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// servingEngine answers /health and /v1/models, which is what readiness needs.
+func servingEngine(t *testing.T) string {
+	t.Helper()
+	py, err := exec.LookPath("python3")
+	if err != nil {
+		t.Skip("python3 is required for the fake engine")
+	}
+	return fakeEngineScript(t, `exec `+py+` -c '
+import http.server, json, sys
+port = int(sys.argv[1])
+class H(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        if self.path == "/health":
+            self.send_response(200); self.end_headers(); return
+        if self.path == "/v1/models":
+            b = json.dumps({"object":"list","data":[{"id":"test-model"}]}).encode()
+            self.send_response(200)
+            self.send_header("content-type","application/json")
+            self.send_header("content-length", str(len(b)))
+            self.end_headers(); self.wfile.write(b); return
+        self.send_response(404); self.end_headers()
+    def log_message(self, *a): pass
+http.server.HTTPServer(("127.0.0.1", port), H).serve_forever()
+' "$port"`)
+}
+
+type harness struct {
+	svc *agentsvc.Service
+	inv *inventory.Store
+	rec *statusRecorder
+	srv *httptest.Server
+	ag  *Agent
+	ln  *dropListener
+	// streams counts how many times an agent has opened the Connect stream,
+	// which is the only honest way to tell a reconnect from a stale entry.
+	streams *atomic.Int64
+}
+
+// dropListener tracks accepted connections so a test can sever them.
+//
+// httptest's CloseClientConnections does not work here: h2c with prior
+// knowledge hijacks the connection, and httptest stops tracking hijacked
+// connections. A test relying on it would pass without ever reconnecting.
+type dropListener struct {
+	net.Listener
+	mu    sync.Mutex
+	conns []net.Conn
+}
+
+func (l *dropListener) Accept() (net.Conn, error) {
+	c, err := l.Listener.Accept()
+	if err != nil {
+		return nil, err
+	}
+	l.mu.Lock()
+	l.conns = append(l.conns, c)
+	l.mu.Unlock()
+	return c, nil
+}
+
+// drop severs every connection, as a control plane restart would.
+func (l *dropListener) drop() {
+	l.mu.Lock()
+	conns := l.conns
+	l.conns = nil
+	l.mu.Unlock()
+	for _, c := range conns {
+		_ = c.Close()
+	}
+}
+
+// start wires a real agent to a real service over h2c, so this exercises the
+// protocol rather than two structs calling each other.
+func start(t *testing.T, cfgFns ...func(*Config)) *harness {
+	t.Helper()
+	return startWith(t, slog.New(slog.DiscardHandler), cfgFns...)
+}
+
+// startLogged is start with logging on, for diagnosing protocol behaviour.
+func startLogged(t *testing.T, cfgFns ...func(*Config)) *harness {
+	t.Helper()
+	return startWith(t, slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug})), cfgFns...)
+}
+
+func startWith(t *testing.T, log *slog.Logger, cfgFns ...func(*Config)) *harness {
+	t.Helper()
+
+	inv := inventory.NewStore()
+	rec := newRecorder()
+	svc := agentsvc.New(inv, rec, false, log)
+
+	path, handler := svc.Handler()
+	mux := http.NewServeMux()
+	mux.Handle(path, handler)
+
+	var streams atomic.Int64
+	counting := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		streams.Add(1)
+		mux.ServeHTTP(w, r)
+	})
+
+	raw, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ln := &dropListener{Listener: raw}
+	// connect's bidirectional streams need HTTP/2; h2c provides it without TLS.
+	srv := httptest.NewUnstartedServer(h2c.NewHandler(counting, &http2.Server{}))
+	srv.Listener = ln
+	srv.Start()
+
+	cfg := DefaultConfig()
+	cfg.NodeID = "n1"
+	cfg.Server = srv.URL
+	cfg.MgmtAddr = "127.0.0.1"
+	cfg.HeartbeatInterval = 50 * time.Millisecond
+	cfg.ReconnectBase = 20 * time.Millisecond
+	cfg.ReconnectMax = 100 * time.Millisecond
+	cfg.Discovery.SkipGPUs = true
+	cfg.Discovery.IBRoot = filepath.Join(t.TempDir(), "absent")
+	cfg.Superv = supervisor.Config{
+		WorkDir: t.TempDir(), LogLines: 64,
+		StopTimeout: 2 * time.Second, HealthInterval: 20 * time.Millisecond,
+	}
+	for _, f := range cfgFns {
+		f(&cfg)
+	}
+
+	client := &http.Client{Transport: &http2.Transport{
+		AllowHTTP: true,
+		DialTLSContext: func(ctx context.Context, network, addr string, _ *tls.Config) (net.Conn, error) {
+			return (&net.Dialer{}).DialContext(ctx, network, addr)
+		},
+	}}
+
+	ag, err := New(cfg, client, log)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() { _ = ag.Run(ctx) }()
+
+	h := &harness{svc: svc, inv: inv, rec: rec, srv: srv, ag: ag, ln: ln, streams: &streams}
+	t.Cleanup(func() {
+		cancel()
+		ag.Supervisor().StopAll(context.Background())
+		srv.Close()
+	})
+	h.waitRegistered(t)
+	return h
+}
+
+func (h *harness) waitRegistered(t *testing.T) {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, ok := h.inv.Get("n1"); ok && len(h.svc.ConnectedNodes()) == 1 {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("the agent never registered")
+}
+
+// shardCommand builds a single-node vLLM shard on a free port.
+//
+// The model path is a real file. It used to be "/models/x", which stopped
+// working once the agent began checking that weights exist before launching an
+// engine — the check doing exactly what it is for, on a test that was relying
+// on nobody looking.
+func shardCommand(t *testing.T, shardID string) reconciler.ShardCommand {
+	t.Helper()
+	modelPath := filepath.Join(t.TempDir(), "model.gguf")
+	if err := os.WriteFile(modelPath, []byte("weights"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return reconciler.ShardCommand{
+		ReplicaID: "rep-1", ShardID: shardID, NodeID: "n1",
+		Spec: engines.ShardSpec{
+			ReplicaID: "rep-1", ShardID: shardID, Rank: 0, NNodes: 1,
+			GPUIndices: []int{0}, HTTPPort: freePort(t),
+			Profile: engines.Profile{
+				Name: "p", Engine: "vllm", TP: 1,
+				ModelPath: modelPath, ServedModelName: "test-model",
+			},
+		},
+		StartupTimeout: 15 * time.Second,
+	}
+}
+
+func freePort(t *testing.T) int {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ln.Close()
+	return ln.Addr().(*net.TCPAddr).Port
+}
+
+func TestRegistrationCarriesInventory(t *testing.T) {
+	// The node must actually have the adapters it declares. It used to declare
+	// mlx5_0 and mlx5_1 on a node whose sysfs held neither, which passed
+	// because nothing compared the two — and that is the gap a real cluster
+	// would have found as a replica hanging on its first all-reduce.
+	ibRoot := ibTreeWithActivePorts(t, "mlx5_0", "mlx5_1")
+	h := start(t, func(c *Config) {
+		c.Hostname = "gpu-a-01"
+		c.Labels = map[string]string{"rack": "r12"}
+		c.Discovery.IBRoot = ibRoot
+		c.Fabrics = []inventory.FabricAttachment{
+			{Fabric: "ib-a", HCAs: []string{"mlx5_0", "mlx5_1"}, RateGbps: 200},
+		}
+	})
+
+	n, ok := h.inv.Get("n1")
+	if !ok {
+		t.Fatal("node missing from inventory")
+	}
+	if n.Hostname != "gpu-a-01" || n.MgmtAddr != "127.0.0.1" {
+		t.Errorf("identity wrong: %+v", n)
+	}
+	if n.Labels["rack"] != "r12" {
+		t.Errorf("labels lost: %v", n.Labels)
+	}
+	// The fabric label cannot be inferred from the wire, so losing it in
+	// transit would silently disable multi-node placement.
+	if !n.HasFabric("ib-a") {
+		t.Fatalf("fabric attachment lost: %+v", n.Fabrics)
+	}
+	if got := n.HCAsFor("ib-a"); !slices.Equal(got, []string{"mlx5_0", "mlx5_1"}) {
+		t.Errorf("HCAs=%v", got)
+	}
+}
+
+func TestHeartbeatKeepsNodeAlive(t *testing.T) {
+	h := start(t)
+
+	n, _ := h.inv.Get("n1")
+	first := n.LastSeen
+
+	// Waited for rather than slept through: four heartbeat intervals was not
+	// always enough on a loaded runner for one to have landed.
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if n, _ = h.inv.Get("n1"); n.LastSeen.After(first) {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Error("heartbeats are not refreshing LastSeen; the node would be declared lost")
+}
+
+func TestStartAndStopShardEndToEnd(t *testing.T) {
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = servingEngine(t)
+	})
+
+	cmd := shardCommand(t, "shard-a")
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+
+	got := h.rec.await(t, 30*time.Second, func(s status) bool {
+		return s.shardID == "shard-a" && s.state == supervisor.Ready
+	})
+	if got.replicaID != "rep-1" {
+		t.Errorf("replica id lost in transit: %q", got.replicaID)
+	}
+
+	if err := h.svc.StopShard(t.Context(), "n1", "shard-a"); err != nil {
+		t.Fatal(err)
+	}
+	h.rec.await(t, 15*time.Second, func(s status) bool {
+		return s.shardID == "shard-a" && s.state == supervisor.Stopped
+	})
+}
+
+func TestFailedShardCarriesDiagnosis(t *testing.T) {
+	// When a model fails to load the engine's output is the only diagnosis, so
+	// it has to survive the trip to the control plane.
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = fakeEngineScript(t, `echo 'CUDA out of memory' >&2; exit 1`)
+	})
+
+	if err := h.svc.StartShard(t.Context(), shardCommand(t, "shard-bad")); err != nil {
+		t.Fatal(err)
+	}
+	got := h.rec.await(t, 30*time.Second, func(s status) bool {
+		return s.shardID == "shard-bad" && s.state == supervisor.Failed
+	})
+	if got.err == "" {
+		t.Error("the failure carried no error message")
+	}
+}
+
+func TestEngineThatNeverBecomesReady(t *testing.T) {
+	// A process that runs but never serves must time out rather than hang the
+	// replica forever.
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = fakeEngineScript(t, `sleep 60`)
+	})
+
+	cmd := shardCommand(t, "shard-stuck")
+	cmd.StartupTimeout = 500 * time.Millisecond
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	h.rec.await(t, 20*time.Second, func(s status) bool {
+		return s.shardID == "shard-stuck" && s.state == supervisor.Failed
+	})
+}
+
+func TestValidationRejectsBeforeLaunch(t *testing.T) {
+	// An engine that refuses a profile does so after minutes of loading;
+	// catching it at dispatch costs nothing.
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = servingEngine(t)
+	})
+
+	cmd := shardCommand(t, "shard-invalid")
+	cmd.Spec.Profile.ModelPath = "" // validation requires one
+
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	got := h.rec.await(t, 15*time.Second, func(s status) bool {
+		return s.shardID == "shard-invalid" && s.state == supervisor.Failed
+	})
+	if got.err == "" {
+		t.Error("validation failure carried no reason")
+	}
+}
+
+func TestDispatchToUnconnectedNode(t *testing.T) {
+	h := start(t)
+
+	err := h.svc.StartShard(t.Context(), reconciler.ShardCommand{NodeID: "nowhere", ShardID: "x"})
+	if err == nil {
+		t.Fatal("dispatching to an unconnected node succeeded")
+	}
+	if !errors.Is(err, agentsvc.ErrNotConnected) {
+		t.Errorf("err=%v, expected ErrNotConnected", err)
+	}
+}
+
+func TestAgentReconnects(t *testing.T) {
+	// A control plane restart must not require touching every GPU node.
+	h := start(t)
+
+	before := h.streams.Load()
+	h.ln.drop()
+
+	// Counting streams, not connected nodes: a stale entry in the connection
+	// map would make a node look connected without any reconnect having
+	// happened, and an assertion on it would pass vacuously.
+	deadline := time.Now().Add(15 * time.Second)
+	for time.Now().Before(deadline) {
+		if h.streams.Load() > before && len(h.svc.ConnectedNodes()) == 1 {
+			if err := h.svc.DrainShard(t.Context(), "n1", "nothing"); err != nil {
+				t.Fatalf("the reconnected stream does not accept commands: %v", err)
+			}
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatalf("the agent never reconnected (streams %d -> %d)", before, h.streams.Load())
+}
+
+func TestIdempotentStart(t *testing.T) {
+	// The control plane retries commands; a repeat must not start a second
+	// process (plan §5.6).
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = fakeEngineScript(t, `sleep 30`)
+	})
+
+	cmd := shardCommand(t, "shard-idem")
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	h.rec.await(t, 15*time.Second, func(s status) bool {
+		return s.shardID == "shard-idem" && s.state == supervisor.Starting
+	})
+
+	sup := h.ag.Supervisor()
+	sh, err := sup.Get("shard-idem")
+	if err != nil {
+		t.Fatal(err)
+	}
+	pid := sh.Status().PID
+
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	time.Sleep(400 * time.Millisecond)
+
+	sh2, err := sup.Get("shard-idem")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sh2.Status().PID != pid {
+		t.Errorf("a second process was started: pid %d then %d", pid, sh2.Status().PID)
+	}
+}
+
+// TestRunningShardsReportedOnReconnect covers the control plane restart hole
+// (plan §6.5): a reconnecting agent has to describe what it is already running,
+// or the control plane concludes the cluster is empty and places duplicates
+// while the originals keep holding GPUs.
+func TestRunningShardsReportedOnReconnect(t *testing.T) {
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = fakeEngineScript(t, `sleep 60`)
+	})
+
+	cmd := shardCommand(t, "shard-live")
+	cmd.Pool = "ib-a/h100-80g"
+	cmd.Fabric = "ib-a"
+	cmd.Spec.HCAs = []string{"mlx5_0"}
+
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	h.rec.await(t, 15*time.Second, func(s status) bool {
+		return s.shardID == "shard-live" && s.state == supervisor.Starting
+	})
+
+	// Drop the stream, as a control plane restart would.
+	h.ln.drop()
+
+	deadline := time.Now().Add(15 * time.Second)
+	for time.Now().Before(deadline) {
+		if got := h.rec.adoptedShards(); len(got) > 0 {
+			a := got[0]
+			if a.ShardID != "shard-live" || a.ReplicaID != "rep-1" {
+				t.Fatalf("wrong shard reported: %+v", a)
+			}
+			// Everything the control plane needs to rebuild the replica.
+			if a.Model != "test-model" || a.Profile != "p" {
+				t.Errorf("catalog identity lost: model=%q profile=%q", a.Model, a.Profile)
+			}
+			if a.Pool != "ib-a/h100-80g" || a.Fabric != "ib-a" {
+				t.Errorf("pool/fabric lost: %q %q", a.Pool, a.Fabric)
+			}
+			if !slices.Equal(a.HCAs, []string{"mlx5_0"}) {
+				t.Errorf("HCAs lost: %v", a.HCAs)
+			}
+			if a.Endpoint == "" {
+				t.Error("rank 0 reported no endpoint; the router would have nowhere to send")
+			}
+			if len(a.GPUIndices) == 0 {
+				t.Error("GPU indices lost; the inventory could not reclaim them")
+			}
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	t.Fatal("the reconnecting agent never reported its running shard")
+}
+
+// TestUnclaimedShardIsStopped covers the other half: a shard whose model left
+// the catalog is holding GPUs nothing will ever route to.
+func TestUnclaimedShardIsStopped(t *testing.T) {
+	h := start(t, func(c *Config) {
+		c.Engines.VLLM.Bin = fakeEngineScript(t, `sleep 60`)
+	})
+
+	cmd := shardCommand(t, "shard-orphaned")
+	if err := h.svc.StartShard(t.Context(), cmd); err != nil {
+		t.Fatal(err)
+	}
+	h.rec.await(t, 15*time.Second, func(s status) bool {
+		return s.shardID == "shard-orphaned" && s.state == supervisor.Starting
+	})
+
+	sh, err := h.ag.Supervisor().Get("shard-orphaned")
+	if err != nil {
+		t.Fatal(err)
+	}
+	pid := sh.Status().PID
+
+	// The control plane will refuse to claim it on reconnect.
+	h.rec.markUnclaimed("shard-orphaned")
+	h.ln.drop()
+
+	deadline := time.Now().Add(20 * time.Second)
+	for time.Now().Before(deadline) {
+		if !processAliveForTest(pid) {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Error("an unclaimed shard kept running and holding its GPUs")
+}
+
+// processAliveForTest mirrors the supervisor's liveness check.
+func processAliveForTest(pid int) bool {
+	return syscall.Kill(pid, 0) == nil
+}
+
+func TestAShardWithMissingWeightsFailsBeforeLaunching(t *testing.T) {
+	// The commonest setup mistake on a fresh node. Left to the engine it
+	// surfaces minutes into a load, in the engine's own words, on a machine
+	// nobody is watching — so it is caught here, where the message can say
+	// what is actually wrong.
+	a := &Agent{cfg: Config{WeightsCache: t.TempDir()}, log: slog.New(slog.DiscardHandler)}
+	_, err := a.weights().Ensure(t.Context(), filepath.Join(t.TempDir(), "not-there.gguf"), false)
+	if err == nil {
+		t.Fatal("a missing weights file was accepted")
+	}
+	if !strings.Contains(err.Error(), "not-there.gguf") {
+		t.Errorf("the error does not name the file: %v", err)
+	}
+}
+
+func TestTheCacheDefaultsToTheFirstModelDirectory(t *testing.T) {
+	// A node that has said where its models live has already answered this;
+	// asking twice is a second thing to get out of step.
+	dir := t.TempDir()
+	a := &Agent{cfg: Config{ModelDirs: []string{dir, "/elsewhere"}}, log: slog.New(slog.DiscardHandler)}
+	if got := a.weights().CacheDir; got != dir {
+		t.Errorf("cache = %q, want the first model directory %q", got, dir)
+	}
+}
+
+// ibTreeWithActivePorts builds a sysfs InfiniBand tree with the named adapters,
+// each with one active port, shaped like the real thing.
+func ibTreeWithActivePorts(t *testing.T, names ...string) string {
+	t.Helper()
+	root := t.TempDir()
+	for _, name := range names {
+		dir := filepath.Join(root, name, "ports", "1")
+		if err := os.MkdirAll(filepath.Join(dir, "gids"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		for file, content := range map[string]string{
+			"state":      "4: ACTIVE",
+			"phys_state": "5: LinkUp",
+			"rate":       "200 Gb/sec (4X HDR)",
+			"link_layer": "InfiniBand",
+			"lid":        "0x1a",
+			"gids/0":     "fec0:0000:0000:000a:0002:c903:00a0:1234",
+		} {
+			if err := os.WriteFile(filepath.Join(dir, file), []byte(content+"\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	return root
+}
+
+func TestAFabricWhoseAdaptersAreAbsentIsNotAdvertised(t *testing.T) {
+	// The failure this prevents: a typo, or a card that enumerated differently
+	// after a reboot, produced NCCL_IB_HCA naming an adapter that is not there.
+	// The replica starts, passes its health checks, and hangs on its first
+	// all-reduce — the exact case the fabric invariant exists to prevent,
+	// arriving through a door nobody was watching.
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = ibTreeWithActivePorts(t, "mlx5_0")
+		c.Fabrics = []inventory.FabricAttachment{
+			{Fabric: "ib-typo", HCAs: []string{"mlx5_9"}, RateGbps: 200},
+		}
+	})
+
+	n, ok := h.inv.Get("n1")
+	if !ok {
+		t.Fatal("node missing from inventory")
+	}
+	if n.HasFabric("ib-typo") {
+		t.Errorf("a fabric with no usable adapter was advertised: %+v", n.Fabrics)
+	}
+}
+
+func TestAFabricRateIsTheSlowestActiveLink(t *testing.T) {
+	// A collective runs at the speed of its slowest link, so reporting the
+	// fastest would have the scheduler believe a fabric is quicker than it is.
+	root := t.TempDir()
+	for name, rate := range map[string]string{"mlx5_0": "200", "mlx5_1": "100"} {
+		dir := filepath.Join(root, name, "ports", "1")
+		if err := os.MkdirAll(filepath.Join(dir, "gids"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		for file, content := range map[string]string{
+			"state": "4: ACTIVE", "phys_state": "5: LinkUp",
+			"rate": rate + " Gb/sec (4X HDR)", "link_layer": "InfiniBand",
+			"lid": "0x1a", "gids/0": "fec0::1",
+		} {
+			if err := os.WriteFile(filepath.Join(dir, file), []byte(content+"\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = root
+		c.Fabrics = []inventory.FabricAttachment{
+			{Fabric: "ib-a", HCAs: []string{"mlx5_0", "mlx5_1"}},
+		}
+	})
+
+	n, _ := h.inv.Get("n1")
+	for _, f := range n.Fabrics {
+		if f.Fabric == "ib-a" && f.RateGbps != 100 {
+			t.Errorf("fabric rate = %d, want the slower link's 100", f.RateGbps)
+		}
+	}
+}
+
+func TestAPortGoingDownIsToldToTheControlPlaneOnce(t *testing.T) {
+	// Checked only at registration, a port going down went unnoticed until
+	// the agent restarted, and the node went on being offered multi-node
+	// work that would hang on its first collective.
+	root := ibTreeWithActivePorts(t, "mlx5_0")
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = root
+		c.Fabrics = []inventory.FabricAttachment{{Fabric: "ib-a", HCAs: []string{"mlx5_0"}}}
+	})
+	if n, _ := h.inv.Get("n1"); !n.HasFabric("ib-a") {
+		t.Fatalf("the fabric should be advertised at registration: %+v", n.Fabrics)
+	}
+
+	hb := h.ag.heartbeat().GetHeartbeat()
+	if hb.GetFabricsChanged() || len(hb.GetIbPorts()) != 1 || hb.GetIbPorts()[0].GetState() != "ACTIVE" {
+		t.Fatalf("a quiet heartbeat should carry the port and no change: %+v", hb)
+	}
+
+	if err := os.WriteFile(filepath.Join(root, "mlx5_0", "ports", "1", "state"), []byte("1: DOWN\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	hb = h.ag.heartbeat().GetHeartbeat()
+	if !hb.GetFabricsChanged() || len(hb.GetFabrics()) != 0 {
+		t.Errorf("the port going down should withdraw the fabric: changed=%v fabrics=%v",
+			hb.GetFabricsChanged(), hb.GetFabrics())
+	}
+	if hb = h.ag.heartbeat().GetHeartbeat(); hb.GetFabricsChanged() {
+		t.Error("the change should be sent once, not on every heartbeat")
+	}
+}
+
+func TestAShardUsesThisNodesInterfaceAndRoCEIndex(t *testing.T) {
+	// The control plane sends one interface name for every node; a node whose
+	// management network is on another had NCCL bind nothing. And which RoCE
+	// GID entry routes is a property of this node's adapters.
+	a := &Agent{cfg: Config{MgmtInterface: "ens3"}}
+	a.inv.HCAs = []discovery.HCA{{Name: "mlx5_0", Ports: []discovery.Port{
+		{Num: 1, State: "ACTIVE", LinkLayer: discovery.LinkEthernet, RoCEv2GID: 3}}}}
+	spec := engines.ShardSpec{MgmtInterface: "eth0", HCAs: []string{"mlx5_0"}}
+	a.localizeSpec(&spec)
+	if spec.MgmtInterface != "ens3" {
+		t.Errorf("interface = %q", spec.MgmtInterface)
+	}
+	if spec.GIDIndex == nil || *spec.GIDIndex != 3 {
+		t.Errorf("GID index = %v", spec.GIDIndex)
+	}
+
+	ib := engines.ShardSpec{HCAs: []string{"mlx5_1"}}
+	a.inv.HCAs = append(a.inv.HCAs, discovery.HCA{Name: "mlx5_1", Ports: []discovery.Port{
+		{Num: 1, State: "ACTIVE", LinkLayer: discovery.LinkInfiniBand, RoCEv2GID: -1}}})
+	a.localizeSpec(&ib)
+	if ib.GIDIndex != nil {
+		t.Error("an InfiniBand shard was given a GID index")
+	}
+}
+
+func TestTheManagementInterfaceIsFoundNotAssumed(t *testing.T) {
+	// It was defaulted to eth0 before it could be looked for, so it never
+	// was: a node on ens3 or bond0 had NCCL bootstrap over nothing.
+	cfg := DefaultConfig()
+	cfg.Server = "http://127.0.0.1:7443"
+	cfg.NodeID = "n1"
+	cfg.MgmtAddr = "127.0.0.1"
+	if err := cfg.normalize(); err != nil {
+		t.Fatal(err)
+	}
+	if cfg.MgmtInterface == "" || cfg.MgmtInterface == "eth0" {
+		t.Errorf("interface = %q, want the loopback interface holding 127.0.0.1", cfg.MgmtInterface)
+	}
+}
+
+func TestEachFabricsSubnetManagersAreAskedOnce(t *testing.T) {
+	// Two adapters on one fabric see one master. Its managers are listed
+	// through one of them — the same list twice is a query too many — and
+	// every port says which master it sees.
+	oldSM, oldSMs := querySM, querySMs
+	t.Cleanup(func() { querySM, querySMs = oldSM, oldSMs })
+	querySM = func(string, int) (*discovery.SMInfo, error) {
+		return &discovery.SMInfo{GUID: "0x01", LID: 1, State: "SMINFO_MASTER"}, nil
+	}
+	lists := 0
+	querySMs = func(string, int) ([]discovery.SMRecord, error) {
+		lists++
+		return []discovery.SMRecord{{GUID: "0x01", State: "master"}, {GUID: "0x02", State: "standby"}}, nil
+	}
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = ibTreeWithActivePorts(t, "mlx5_0", "mlx5_1")
+		c.Fabrics = []inventory.FabricAttachment{{Fabric: "ib-a", HCAs: []string{"mlx5_0", "mlx5_1"}}}
+	})
+	hb := h.ag.heartbeat().GetHeartbeat()
+	withList := 0
+	for _, p := range hb.GetIbPorts() {
+		if p.GetSmGuid() != "0x01" {
+			t.Errorf("%s sees master %q", p.GetHca(), p.GetSmGuid())
+		}
+		if len(p.GetSubnetManagers()) > 0 {
+			withList++
+		}
+	}
+	if lists != 1 || withList != 1 {
+		t.Errorf("listed %d times, carried on %d ports; want once, on one", lists, withList)
+	}
+}
+
+func TestAFabricScanIsAskedForAndAnswered(t *testing.T) {
+	// One node per fabric maps it; the control plane asks and parses.
+	old := scanFabric
+	t.Cleanup(func() { scanFabric = old })
+	var asked string
+	scanFabric = func(_ context.Context, hca string, port int) (string, error) {
+		asked = fmt.Sprintf("%s/%d", hca, port)
+		return "Switch\t36 \"S-00000000000000a1\"\t\t# \"MF0;leaf-a:QM8700/U1\" enhanced port 0 lid 1 lmc 0\n", nil
+	}
+	h := start(t)
+	r, err := h.svc.ScanFabric(t.Context(), "n1", "mlx5_0", 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if asked != "mlx5_0/1" || !strings.Contains(r.GetOutput(), "leaf-a") || r.GetError() != "" {
+		t.Errorf("asked %q, got %+v", asked, r)
+	}
+}
+
+func TestABandwidthTestIsRunOnTheAdapterAskedFor(t *testing.T) {
+	oldRun, oldHave := runWriteBW, haveWriteBW
+	t.Cleanup(func() { runWriteBW, haveWriteBW = oldRun, oldHave })
+	haveWriteBW = func() bool { return true }
+	var got discovery.WriteBW
+	runWriteBW = func(_ context.Context, w discovery.WriteBW) (float64, string, error) {
+		got = w
+		return 388.2, " #bytes  #iterations  BW peak[Gb/sec]  BW average[Gb/sec]\n", nil
+	}
+	h := start(t, func(c *Config) { c.Discovery.IBRoot = ibTreeWithActivePorts(t, "mlx5_0") })
+
+	r, err := h.svc.FabricTest(t.Context(), "n1", &llmgwv1.FabricTestRequest{
+		Role: "client", Hca: "mlx5_0", Port: 1, Peer: "10.0.0.2", TcpPort: 18515, Seconds: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.GetGbps() != 388.2 || r.GetError() != "" {
+		t.Errorf("reply %+v", r)
+	}
+	if got.HCA != "mlx5_0" || got.Peer != "10.0.0.2" || got.TCPPort != 18515 || got.GIDIndex != -1 {
+		t.Errorf("ran %+v", got)
+	}
+
+	// An adapter the node does not have is said so, without running anything.
+	got = discovery.WriteBW{}
+	r, _ = h.svc.FabricTest(t.Context(), "n1", &llmgwv1.FabricTestRequest{Role: "server", Hca: "mlx5_9", Port: 1, Seconds: 1})
+	if !strings.Contains(r.GetError(), "no port mlx5_9/1") || got.HCA != "" {
+		t.Errorf("reply %+v, ran %+v", r, got)
+	}
+}
+
+func TestANewStreamIsToldTheFilesAgain(t *testing.T) {
+	// Registration carries what the startup scan found; a file deleted since
+	// came back on a control plane that restarted, because the next
+	// heartbeat saw the list unchanged since it was last sent.
+	dir := t.TempDir()
+	h := start(t, func(c *Config) { c.ModelDirs = []string{dir} })
+	if err := os.WriteFile(filepath.Join(dir, "0123456789abcdef-m.gguf"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	h.ag.heartbeat()
+	if hb := h.ag.heartbeat().GetHeartbeat(); hb.GetWeightsChanged() {
+		t.Fatal("an unchanged list should not be sent again on the same stream")
+	}
+	h.ag.forgetSent()
+	hb := h.ag.heartbeat().GetHeartbeat()
+	if !hb.GetWeightsChanged() || len(hb.GetWeights()) != 1 {
+		t.Errorf("a new stream should be told the files: changed=%v %v", hb.GetWeightsChanged(), hb.GetWeights())
+	}
+}