admitperf 0.0.1__tar.gz

admitperf-0.0.1/.claude/skills/README.md

@@ -0,0 +1,51 @@
+# Project skills
+
+Eight skills that encode how this project is worked on. They load automatically for anyone
+using Claude Code in this repository — no setup, because they are versioned alongside the
+code they describe.
+
+| Skill | Use it when |
+|---|---|
+| [`admitperf-run`](admitperf-run/SKILL.md) | Running an experiment, or reading what one produced |
+| [`admitperf-policy`](admitperf-policy/SKILL.md) | Porting a published admission policy |
+| [`admitperf-review`](admitperf-review/SKILL.md) | Reviewing a change, adversarially |
+| [`admitperf-pr`](admitperf-pr/SKILL.md) | Opening a pull request |
+| [`admitperf-issue`](admitperf-issue/SKILL.md) | Filing a bug, a policy port, or a docs problem |
+| [`admitperf-debt`](admitperf-debt/SKILL.md) | Auditing claims against the bundles behind them |
+| [`admitperf-spec`](admitperf-spec/SKILL.md) | Planning docs, the board, and what is actually done |
+| [`admitperf-release`](admitperf-release/SKILL.md) | Cutting a release |
+
+## Why these exist
+
+They are not style guides. Each encodes a mistake this project actually made.
+
+- **`admitperf-run`** exists because of `experiments/half-capacity-headroom`:
+  `waiting_requests` identically zero across all three repeats, `running_requests` peaking
+  at 6-8 against a cap of 10. The engine was never saturated, so every signal was flat —
+  not just the one under test. That run was treated as banked evidence for weeks. It
+  isolates nothing.
+- **`admitperf-policy`** front-loads the Class A / Class B question, because a Class B
+  policy cannot sit behind this API at all and discovering that mid-port wastes the port.
+- **`admitperf-debt`** exists because a figure was published that its bundles did not
+  support, and because `docs/status.md` has disagreed with what the software can actually
+  demonstrate.
+- **`admitperf-pr`** says to check the gate's *exit codes*: piping `ruff` into `tail`
+  returns tail's status, and a formatting failure can be committed while the gate reports
+  clean. It also says to run the gate in a clean venv, because CI has already failed on an
+  extra the working venv had accumulated by hand.
+- **`admitperf-issue`** asks for the signal range before anything else, because "the policy
+  admitted everything" and "the policy never saw pressure" look identical from outside.
+- **`admitperf-spec`** exists because the plan and the board have disagreed: a direction was
+  recorded as banked while the run behind it isolated nothing.
+
+The thread running through all eight: **a number is not a result until you know the signal
+moved.** A policy that never saw its threshold did not perform badly — it never ran, and it
+reports the same numbers as no policy at all. Telling those apart is the entire point of
+this repository, so it is the first thing every skill checks.
+
+## Adding one
+
+A skill earns its place by encoding something that went wrong, or a rule a newcomer would
+otherwise learn by breaking. Keep it short, make it concrete, and cite the real incident —
+the specifics are what make a rule memorable and what let a reader judge whether it still
+applies.

admitperf-0.0.1/.claude/skills/admitperf-debt/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: admitperf-debt
+description: >-
+  Audit what AdmitPerf claims against what its bundles prove — numbers without a bundle,
+  policies never exercised, docs describing code that moved. Use when asked about technical
+  debt, what is unproven or over-claimed, or before a release or a paper submission.
+---
+
+# Auditing claims against proof
+
+## What this looks for
+
+**A claim the software cannot demonstrate in one command.** Reviewers read the repo; a gap
+between `docs/status.md` and what runs is the risk that matters here.
+
+## The audit
+
+1. **Every number in a doc names a bundle.** Walk the docs, list the figures, and for each
+   one find the run it came from. A number with no bundle is either unverified or lost, and
+   both are reported the same way: as unproven.
+2. **Every cited bundle names its commit.** Traceable only to a version string that never
+   changes is not traceable.
+3. **Every registered policy has a run where its signal crossed its threshold.** A policy
+   never exercised under pressure is a policy with no evidence behind it, however many
+   tests it passes.
+4. **Every claimed capability has a command that shows it.** If showing it needs three
+   steps and local knowledge, it is not demonstrable.
+5. **Docs against the tree.** This repo has moved its package layout more than once;
+   anything citing a path is suspect until checked.
+
+## Known debts, so they are not rediscovered
+
+- **A published figure its bundles did not support.** The reason this audit exists.
+- **`half-capacity-headroom` isolates nothing.** Engine never saturated, every signal flat.
+  Any claim resting on it is unsupported.
+- **KV pressure and queue depth have never been compared in the same deployment.**
+  `which-policy-when` is specified for it and has not run.
+- **`infra/` is vendored and unlinted.** Its lint debt is upstream's; ours is that we have
+  not decided what happens to the gateway inside it.
+
+## How to report
+
+Per item: the claim, where it is made, what would prove it, and whether that evidence
+exists. **An item that cannot be proven is reported as not-shown, never quietly dropped** —
+dropping it is how an over-claim survives an audit that was meant to catch it.

admitperf-0.0.1/.claude/skills/admitperf-issue/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: admitperf-issue
+description: >-
+  File an AdmitPerf issue that is actionable on arrival — which template, the evidence to
+  gather before writing it, and the labels. Use when asked to file an issue, open a bug,
+  track something, or when a problem is found that will not be fixed in the current change.
+---
+
+# Filing an issue
+
+## Gather the evidence first
+
+For anything about a run, three things answer most of what would otherwise be asked, and
+each round trip of asking costs a day:
+
+1. **`manifest.json`** — what ran, against what, at which commit.
+2. **The signal range from `summary.json`.** Usually *the* answer. A policy whose signal
+   never approached its threshold did not misbehave; it never fired, and it reports the same
+   numbers as no policy at all.
+3. **The command**, and the config it ran against.
+
+If the signal range explains the behaviour, say so in the issue rather than filing it as a
+bug. "The policy admitted everything" and "the policy never saw pressure" look identical
+from outside and are completely different problems.
+
+## Which template
+
+| Template | For |
+|---|---|
+| **Bug report** | Something behaves differently from what it says it does |
+| **Policy port** | A published policy that should be available here |
+| **Documentation** | Wrong, missing, or misleading — misleading is the worst, the reader leaves confident |
+
+Blank issues are off on purpose. The templates ask for what we would otherwise have to
+chase.
+
+## Labels
+
+`policy` · `infra` · `measurement` · `blocked-on-gpu` · `bug` · `documentation` ·
+`enhancement`
+
+**`blocked-on-gpu` matters most.** It separates what can be done on a laptop today from what
+waits on a rented cluster. Without it the board looks full while everything on it is
+unstartable.
+
+## Writing it
+
+**One issue, one thing.** An issue that contains three problems gets closed when one is
+fixed.
+
+**Say what you expected, not just what happened.** *"It admitted everything"* is a
+description. *"It admitted everything, and I expected refusals once KV passed 0.9"* is a
+specification, and someone can tell whether it is fixed.
+
+**Attach it to the milestone** if it belongs in the current one. An issue with no milestone
+is invisible to anyone planning.
+
+## Before filing
+
+A problem found mid-change that you are about to fix does not need an issue. A problem found
+mid-change that you are **not** going to fix does — otherwise it survives as a comment in a
+diff nobody reads again.

admitperf-0.0.1/.claude/skills/admitperf-policy/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: admitperf-policy
+description: >-
+  Port a published admission policy into AdmitPerf — the Class A/B test that comes first,
+  the frozen interface, declaring what signal it needs, and recording deviations from the
+  paper. Use when adding a policy, porting one from a paper, or reviewing a port.
+---
+
+# Porting a policy
+
+## Class A or Class B — decide before writing anything
+
+**Class A** is a pure function of `(request, observable fleet state) → decision`, running in
+front of an unmodified engine and reading its metrics. That is all this API accepts.
+
+**Class B** changes how batches are *formed inside* the engine. Porting one means
+maintaining a fork of thousands of lines of scheduler internals. FairBatching, FastServe
+and CONCUR are Class B and do not fit here — saying precisely why is itself the
+Portability axis the survey needs.
+
+Getting this wrong costs the whole port, and it is answerable from the paper's abstract.
+
+## The interface is frozen
+
+```python
+def decide(self, req: Request, state: SystemState) -> Decision
+```
+
+`ADMIT`, `DEFER` (with `retry_after_ms`), or `REJECT` (with a reason). Deterministic: the
+same inputs and internal state must give the same decision, or experiments stop being
+reproducible.
+
+Anything the policy needs that `SystemState` lacks arrives as an **optional** field. Never
+change `Decision` or `decide()`.
+
+## Declare what it reads
+
+A policy states its signal in the same vocabulary as the survey's axes — unit, setting,
+objective, signal, portability. Two things fall out for free:
+
+- The harness can **refuse to run** a policy against an engine that cannot supply its
+  signal, before any provisioning cost.
+- The report can show the **observed range** of that signal, which is what tells a reader
+  the policy was live.
+
+## Write the deviation list while porting, not after
+
+Anything that cannot be reproduced faithfully: a simulator-only assumption, a metric the
+engine does not expose, a constant the paper never states. Written during the port it is a
+record; written afterwards it is a reconstruction, and the details that mattered are gone.
+
+## Before calling it done
+
+- A test that the policy refuses *something* under pressure. A policy that admits
+  everything passes most tests.
+- A run where its signal actually crossed its threshold. Otherwise the port is unexercised
+  and you have no evidence it works.
+- Its entry in `docs/policies.md`, with the deviation list.

admitperf-0.0.1/.claude/skills/admitperf-pr/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: admitperf-pr
+description: >-
+  Open a pull request against AdmitPerf — the gate to run, what the body must explain, and
+  the branch rules. Use when asked to open or raise a PR, or when finishing a change that
+  is ready to land.
+---
+
+# Opening a PR
+
+## Run the gate, and check exit codes
+
+```bash
+ruff check . && ruff format --check . && pytest -q
+```
+
+**Check the exit code, not the output.** Piping either into `tail` returns tail's status,
+and a failure then looks clean. This is how a formatting failure gets committed.
+
+Run it in a **clean environment**, not your working venv. A narrower install than CI uses
+collects tests and then fails to import them — which has already shipped here once, when
+`.[dev]` passed locally only because the venv had accumulated `pandas` and `streamlit` by
+hand. Use `pip install -e '.[all]'` in a fresh venv, which is what CI does.
+
+## Branch and title
+
+Branch from `main`. Never commit to it directly.
+
+Conventional-commit title, because release notes are assembled from these:
+`feat(policies):` · `fix(bench):` · `refactor:` · `docs:` · `ci:`
+
+## The body
+
+**What changed, and why.** The *why* is the part worth writing — a change that explains its
+reasoning is understandable in six months. If you fixed something, describe the broken
+behaviour from outside: the symptom someone would have reported.
+
+**How it was verified.** Not "tests pass". What you actually drove — a run you watched, a
+bundle you read, the decision log you checked. This project has shipped a figure its
+bundles did not support and a run where every signal was flat. Both passed their tests.
+
+**Anything deliberately left undone.** Known gaps and follow-ups. A limitation stated here
+is a known limitation; the same limitation unstated is a bug waiting to be rediscovered.
+
+## Before marking ready
+
+- Any number in the diff names the bundle it came from.
+- A new policy is Class A and declares its signal.
+- Version untouched — releases are cut by tag, never by editing a version by hand.
+- Linked to its issue and milestone, so the board reflects reality.

admitperf-0.0.1/.claude/skills/admitperf-release/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: admitperf-release
+description: >-
+  Cut an AdmitPerf release — the tag-driven flow, the TestPyPI round trip, the trusted
+  publisher step only a human can do, and what cannot be undone. Use when asked to cut a
+  release, tag a version, or prepare one.
+---
+
+# Cutting a release
+
+## What cannot be undone
+
+**A published version number can never be reused.** Not on PyPI, not on TestPyPI. If `0.1.0`
+publishes broken, the fix is `0.1.1` and `0.1.0` stays broken forever. Everything below
+exists because of that.
+
+## Before anything
+
+**Trusted Publishing must be configured first, by a human, in a browser.** The workflow
+stores no token; it mints one per run over OIDC. Register at
+`pypi.org/manage/account/publishing/` with owner `harshuljain13`, repo `AdmitPerf`,
+workflow `release.yml`, environment `pypi` — and the same on TestPyPI.
+
+A first-time package that is not registered on **both** indexes half-publishes: TestPyPI
+succeeds, PyPI fails, and that version is now burned.
+
+## The flow
+
+```bash
+# bump the version in pyproject.toml and admitperf/__init__.py — they must match
+git commit -am "release: 0.1.0"
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+A tag publishes. A branch never does.
+
+The workflow then goes **TestPyPI → install back out of TestPyPI → smoke-test → PyPI**. That
+round trip is the only thing that catches a missing dependency or a bad pin, because it is a
+real index resolve. A local path install cannot fail that way, which is why local success
+proves nothing here.
+
+## Rehearse first
+
+`workflow_dispatch` with `target: testpypi` runs the whole thing without cutting a tag. Do
+this for any release that changes packaging, adds a dependency, or moves a module.
+
+## Before tagging
+
+- CI green on `main`, including the wheel job that installs into a clean venv and imports
+  the public API. That job is what catches a module missing from the package manifest; the
+  editable install cannot, because it sees the working tree.
+- `docs/status.md` matches what ships.
+- No number in the docs lacks a bundle. A release is a bad time to discover one.

admitperf-0.0.1/.claude/skills/admitperf-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: admitperf-review
+description: >-
+  Adversarial review for AdmitPerf changes, tuned to the defects this repository actually
+  produces — results from runs where the signal never moved, and claims the bundles do not
+  support. Use when reviewing a PR or a diff, or before marking anything done.
+---
+
+# Reviewing a change
+
+## The defect this repo produces
+
+Not broken code. **A number that looks like a result and is not one.**
+
+The shape: a run completes, a table is produced, the table is cited — and the signal the
+policy reads never left its floor, so the policy never acted and the table says nothing
+about it. This has happened: `half-capacity-headroom`, `waiting_requests` identically zero
+across three repeats, treated as banked evidence.
+
+So on any change that produces or cites a number, ask first: **could this number have come
+from a run where nothing was saturated?** If yes, that is the review finding.
+
+## Checks, in order of what they catch
+
+1. **Does a cited number name its bundle, and does that bundle name its commit?** A number
+   traceable only to a version string that never changes is not traceable.
+2. **Is the comparison within one deployment?** Pooling across hardware reports the
+   machine, not the policy.
+3. **Repeats and spread?** A single run has no error bar. A gap inside noise is not a gap.
+4. **Does a new policy actually refuse anything** in its tests? One that admits everything
+   passes most of them.
+5. **Class A?** A policy that needs engine changes does not fit behind this API, and a
+   review is the last cheap place to notice.
+6. **Does `docs/status.md` still match what the code can demonstrate in one command?** The
+   gap between claim and proof is the risk that matters for this project.
+
+## On vendored code
+
+`infra/` is the vendored serving cluster, excluded from ruff. Do not reformat it — that
+makes every future diff against upstream unreadable. Changes there should be minimal and
+should say why they could not be made upstream.
+
+## What a good review comment looks like
+
+Name the failing input, not the style. *"If `max_num_seqs` is below what KV allows, this
+measures the scheduler rather than the cache"* is reviewable. *"Consider refactoring"* is
+not.

admitperf-0.0.1/.claude/skills/admitperf-run/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: admitperf-run
+description: >-
+  Run an AdmitPerf experiment and read what it produced — the saturation check that comes
+  before any comparison, what a bundle contains, and the one question that decides whether
+  a result means anything. Use when running a benchmark, reading results, comparing
+  policies, or interpreting a report.
+---
+
+# Running an experiment, and reading one
+
+## Ask this first, every time
+
+**Did the signal move?**
+
+A policy that never reached its threshold did not perform badly. It never ran, and it
+reports the same numbers as having no policy at all. Until you know the signal's observed
+range, a results table tells you nothing.
+
+This is not hypothetical. `experiments/half-capacity-headroom` recorded `waiting_requests`
+identically **zero** across all three repeats, with `running_requests` peaking at 6-8
+against a cap of 10. The engine was never saturated, so *every* signal was flat — not just
+the one under test. The run was treated as banked evidence for weeks. It isolates nothing.
+
+## Before comparing anything
+
+1. **Establish capacity.** `bench capacity` finds what the deployment can actually serve.
+   Comparing policies below that ceiling compares nothing.
+2. **Check the load is capacity-relative.** "15 rps" is meaningless alone; "15 rps at 46%
+   of ceiling" is a number someone else can reproduce.
+3. **Confirm the engine queues internally.** Load must back up *inside* vLLM, not in front
+   of it. If `max_concurrent_inputs` is below the engine's `max_num_seqs`, requests wait at
+   the platform and the admission signal stays flat while latency climbs.
+
+## What a bundle contains
+
+```
+results/<timestamp>-<experiment>/<policy>-r<n>/
+├── manifest.json     what ran, against what, with which settings and commit
+├── summary.json      the numbers, each tagged with where it came from
+├── decisions.jsonl   every admit/defer/reject, with the state it was decided on
+└── outcomes.jsonl    per-request TTFT, inter-token gaps, deadline verdict
+```
+
+`decisions.jsonl` is the one that matters. A verdict alone cannot be interpreted after the
+fact; the state beside it can.
+
+## Reading a result
+
+- **Identical numbers across policies** is a finding, not a failure — but only once you can
+  say whether it is because the policies agreed or because none of them fired.
+- **Never pool runs across deployments.** A table mixing an A10G row with an A100 row
+  reports the machine, not the policy. `same-policies-across-gpus` exists to enforce this.
+- **Repeats and spread, or no claim.** A single run has no error bar, and a difference
+  inside run-to-run noise is not a difference.
+- **Reject and defer are outcomes**, not losses. Goodput-under-admission counts them; raw
+  throughput hides them.
+
+## Do not
+
+- Quote latency from a freshly started worker. The engine reports ready minutes before it
+  serves, while it downloads weights and compiles graphs.
+- Report a win without naming the regime it holds in. The question this project exists to
+  answer is *which signal wins under which workload*, and an unqualified winner answers a
+  question nobody asked.

admitperf-0.0.1/.claude/skills/admitperf-spec/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: admitperf-spec
+description: >-
+  Work with AdmitPerf's planning docs and the issue board — which one is authoritative,
+  reconciling a claim against the tree before calling anything done, and recording
+  deviations. Use when asked what is done, about phases or tasks, or when closing work.
+---
+
+# Planning, and what is actually done
+
+## Two places track work. Only one is authoritative.
+
+- **GitHub issues and the milestone** — the source of truth for status. What is open, what
+  is blocked, what shipped.
+- **`.spec-dev/`** — local planning, deliberately not in git. Requirements, design
+  decisions, task breakdowns. It explains *why*; it does not record *whether*.
+
+When they disagree, the board wins and the plan gets updated. A plan that claims work is
+done is how this project once recorded a direction as "banked" while the run behind it
+isolated nothing.
+
+## `.spec-dev/` contents
+
+```
+requirements.md         the thesis, the goals, what would make it wrong
+spec.md                 the active design decisions
+spec-paperB-stale.md    superseded, kept because its findings are still true
+tasks.md                phases, each one sitting
+```
+
+**A stale plan is marked stale, not deleted.** `spec-paperB-stale.md` carries the
+half-capacity finding, which is still the most important thing in that file.
+
+## Before calling anything done
+
+**Reconcile against the tree, not against the plan.** The question is never "did I write
+this down as finished" but "can I show it in one command".
+
+- For a policy: a run where its signal crossed its threshold. Tests passing is not that.
+- For a measurement: the bundle, and the commit that produced it.
+- For a claim in a doc: the command that demonstrates it.
+
+Anything that cannot be shown is reported as **not-shown**, never quietly dropped. Dropping
+it is how an over-claim survives.
+
+## Recording a deviation
+
+When the work diverges from the plan — and it will — write the deviation where the plan is,
+with the reason, at the time. Afterwards it is a reconstruction and the detail that mattered
+is already gone.
+
+The deviations worth recording are the ones where something turned out to be impossible or
+unnecessary, not the ones where an estimate was wrong.
+
+## Closing
+
+An issue closes when its stated "done when" is true, not when the code was written. Several
+issues on this board have a "done when" that requires a live cluster; those cannot close
+from a laptop, and marking them done because the code exists is the failure mode the
+`blocked-on-gpu` label was created to prevent.

admitperf-0.0.1/.env.example

@@ -0,0 +1,167 @@
+# Optional. Nothing here is needed to run AdmitPerf against a local engine, or
+# to deploy an ungated model to Modal after `modal setup`.
+#
+#   cp .env.example .env
+#
+# `.env` is read by every `admitperf` command, including the ones the dashboard
+# runs for you. Anything already exported wins, so a one-off
+# `HF_TOKEN=... admitperf infra up` still overrides the file.
+#
+# This is a superset of the lab's own env file plus AdmitPerf's. Every name
+# below is read somewhere in this repository — the list was taken from the code
+# rather than copied, and the file that reads each one is named. A variable the
+# code does not read is worse than a missing one: it looks configured.
+#
+# The cluster reads its settings from the ENVIRONMENT, not from
+# infra/config/cluster.yaml. The YAML records intent and generates manifests;
+# these are what a running gateway actually sees. Where the two disagree, the
+# environment wins and nothing warns you. See #15.
+
+
+# ===========================================================================
+# GPU box access                          infra/render.py, infra/setup/*.sh
+# ===========================================================================
+# Addresses and keys live HERE, not in infra/config/cluster.yaml, which is
+# committed. An IP is a fact about today; the topology is not. Re-renting a box is
+# an edit to this file rather than a commit, and a private key path is never
+# committed at all.
+#
+# Resolved per host by name: host `gpu-a` reads LAMBDA_HOST_GPU_A, falling back to
+# LAMBDA only when it is the ONLY host. With two boxes LAMBDA is ambiguous and is
+# refused — applying one address to both would point every URL at one machine
+# while the plan claimed two, which is a one-worker run reported as two.
+#
+# `render.py --plan` works with these unset. `--env` and bring-up refuse, naming
+# the variable they want.
+# LAMBDA=ubuntu@YOUR_LAMBDA_IP                 # shorthand, single host only
+# LAMBDA_HOST_GPU_A=ubuntu@YOUR_LAMBDA_IP
+# LAMBDA_HOST_GPU_B=ubuntu@YOUR_SECOND_IP
+# LAMBDA_SSH_KEY=$HOME/.ssh/YOUR_LAMBDA_KEY    # one key for every host
+# LAMBDA_SSH_KEY_GPU_B=$HOME/.ssh/OTHER_KEY    # per-host override
+
+
+# ===========================================================================
+# Models and topology                     infra/gateway/serve.py, router/
+# ===========================================================================
+# READ THIS BEFORE CHANGING THE MODELS. Two traps live here, and both of them
+# produce a run that looks fine and proves nothing.
+#
+# 1. TEXT_MODEL and VISION_MODEL being DIFFERENT, with LAB_SPLIT=capability,
+#    makes the two workers non-interchangeable. Placement then becomes a
+#    capability lookup — a vision request has exactly one destination — and the
+#    admission question disappears, because there is no choice left to make.
+#    The project's design (infra/config/cluster.yaml) calls for ONE model on
+#    both workers so placement stays a load decision. The defaults below are
+#    the lab's and do not match that. Pick one deliberately.
+#
+# 2. A 3B model will not fill KV. These defaults are 3B because the lab ran on
+#    one small GPU. Admission never bites, every signal stays flat, and the run
+#    reproduces experiments/half-capacity-headroom by construction. If you keep
+#    them, you must also cap max_num_seqs by hand and declare the cap artificial.
+#
+# export TEXT_MODEL=Qwen/Qwen2.5-3B-Instruct
+# export VISION_MODEL=Qwen/Qwen2.5-VL-3B-Instruct
+# export LOCAL_MODEL=Qwen/Qwen2.5-3B-Instruct
+
+# phase = prefill/decode disaggregation. capability = text worker + vision
+# worker, which is trap 1 above.
+# export LAB_TOPOLOGY=disaggregated
+# export LAB_SPLIT=capability
+
+
+# ===========================================================================
+# Endpoints                               infra/gateway/, infra/router/
+# ===========================================================================
+# PREFILL_URLS, DECODE_URLS, LAB_TOPOLOGY, LAB_SPLIT, KV_BACKEND and LOCAL_MODEL
+# are RENDERED by `infra.render --env` from the topology. Setting them by hand
+# overrides the config silently, which is how a two-pool plan ends up serving
+# from one. Prefer re-rendering.
+# ===========================================================================
+# export LOCAL_BASE_URL=http://127.0.0.1:8000/v1
+# export PREFILL_URLS=http://127.0.0.1:8000
+# export DECODE_URLS=http://127.0.0.1:8001          # infra/setup/lambda_sliced.sh
+# export ORCH_URL=http://127.0.0.1:8080/v1
+
+# Where the gateway itself binds.         infra/gateway/serve.py
+# export SERVE_HOST=0.0.0.0
+# export SERVE_PORT=8080
+
+
+# ===========================================================================
+# KV transport                            infra/router/kvbus.py
+# ===========================================================================
+# mooncake is the only backend that does anything. nccl and nixl are
+# deliberate no-op stubs — four lines that return. Setting either makes hops
+# vanish from Mooncake's /hops while requests still succeed, so ZERO HOPS IN
+# THE DASHBOARD DOES NOT PROVE THE HOP DID NOT HAPPEN. Check this first.
+# export KV_BACKEND=mooncake
+# export MOONCAKE_URL=http://127.0.0.1:50051
+
+
+# ===========================================================================
+# Load generation                         NOT VENDORED YET — see #27
+# ===========================================================================
+# The lab's load generators (locustfile.py, crew_flood.py) live in its app/
+# directory and were not copied into this repository. LOCUST_HOST is listed for
+# completeness; nothing here reads it today.
+# export LOCUST_HOST=http://127.0.0.1:8080
+
+
+# ===========================================================================
+# Overflow — paid capacity for when our own cluster refuses
+#                                         infra/router/overflow.py
+# ===========================================================================
+# OVERFLOW_MAX_REQS is a LIFETIME counter on the gateway process, not a rate
+# limit. After this many overflows the path turns itself off and requests fall
+# back to the local refusal. That is a deliberate spend guard, and it is also a
+# measurement hazard: a run can report "overflow did not help" when what
+# actually happened is that overflow stopped being available. See #26.
+#
+# A 4B model answering in place of a 72B is a relief valve, not an equivalent
+# service. Overflowed responses are not comparable to local ones and must not
+# be pooled with them when reporting quality.
+#
+# Unrecognised names here are ignored silently and the gateway reports
+# "overflow off" — a typo looks like a configuration choice.
+# RENDERED FROM THE CONFIG, except the key. `python -m infra.render --env` emits
+# OVERFLOW_BACKEND, OVERFLOW_BASE_URL, OVERFLOW_MODEL, OVERFLOW_MAX_REQS and
+# OVERFLOW_MAX_TOKENS from infra/config/cluster.yaml, so they are not typed in two
+# places where they would drift. Set them below only to override a rendered run.
+#
+# The key is the one secret in that block, and it belongs here:
+# export OVERFLOW_API_KEY=                 # unset = overflow off
+#
+# export OVERFLOW_BACKEND=superlinked
+# export OVERFLOW_BASE_URL=https://api.superlinked.com/v1
+# export OVERFLOW_MODEL=Qwen/Qwen3.5-4B
+# export OVERFLOW_MAX_REQS=20
+# export OVERFLOW_MAX_TOKENS=64
+# export OVERFLOW_MAX_REQS=20
+
+
+# ===========================================================================
+# Trace — one row per request             infra/gateway/serve.py
+# ===========================================================================
+# The report is generated from this file. It is also where the signal value
+# behind each admission decision will be recorded (#11).
+# export TRACE_PATH=traces/requests.jsonl
+
+
+# ===========================================================================
+# AdmitPerf's own settings
+# ===========================================================================
+# Override the config a command loads.    src/admitperf/core/config.py
+# ADMITPERF_CONFIG=src/admitperf/experiments/my-run/config.yaml
+
+# Gated weights only (Llama, Gemma). Forwarded to the container at deploy time
+# as a Modal secret; never written into an image layer.
+# HF_TOKEN=hf_xxx
+
+# Alternative to the above, if you would rather keep the token in Modal:
+#   modal secret create huggingface HF_TOKEN=hf_xxx
+# ADMITPERF_HF_SECRET=huggingface
+
+# Modal auth, if you cannot run `modal setup` interactively (CI). The Modal
+# provider is not on the cluster path — see decision D1.
+# MODAL_TOKEN_ID=ak-...
+# MODAL_TOKEN_SECRET=as-...