ci: lint gates (clippy, ruff, thaw-lint) + contributor rails

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+<!-- Keep the diff scoped to one concern. See CONTRIBUTING.md. -->
+
+## What & why
+
+<!-- One or two sentences: what changes, and the problem it solves. -->
+
+## How it was verified
+
+<!-- Commands you ran, or the pod/receipt for a GPU/perf change. -->
+
+## Checklist
+
+- [ ] `python tools/thaw_lint.py` is clean
+- [ ] `ruff check --select F,E9` passes on the Python I touched
+- [ ] `cargo clippy --workspace --exclude thaw-py --all-targets -- -D warnings` is clean (if Rust changed)
+- [ ] Tests pass (`pytest tests/ -q` and/or `cargo test`), and new behavior has a test
+- [ ] Diff is scoped — no unrelated files
+- [ ] **Perf claims ship their receipt** (`site/receipts/*.json` from the run), state what was actually measured, and use a re-validated number — no retracted multipliers, no local paths in receipts

.github/workflows/test.yml

@@ -10,6 +10,69 @@ permissions:
   contents: read
 
 jobs:
+  lint:
+    name: lint (clippy, ruff, thaw-lint)
+    runs-on: ubuntu-22.04
+    timeout-minutes: 15
+    steps:
+      # fetch-depth: 0 so the changed-files ruff step can diff against the
+      # PR base (or the previous commit on a push).
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install ruff
+        run: pip install ruff
+
+      # ruff runs on CHANGED Python only. The legacy tree has known debt
+      # (tracked in the ratchet plan in CONTRIBUTING.md); gating the whole
+      # tree on it would block every PR. Scoping to the diff means new and
+      # touched code must be clean without forcing a one-shot tree cleanup
+      # that would collide with in-flight PRs. --select F,E9 = real bugs
+      # (undefined names, unused imports, syntax), not style.
+      - name: ruff (real-bug rules) on changed Python
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha }}"
+          if [ -z "$BASE" ]; then BASE="${{ github.event.before }}"; fi
+          if ! git rev-parse --verify "$BASE" >/dev/null 2>&1; then
+            BASE="$(git rev-parse HEAD^ 2>/dev/null || true)"
+          fi
+          if [ -n "$BASE" ]; then
+            FILES="$(git diff --name-only --diff-filter=ACMR "$BASE" HEAD -- '*.py' || true)"
+          else
+            FILES="$(git ls-files '*.py')"
+          fi
+          if [ -z "$FILES" ]; then
+            echo "No changed Python files — skipping ruff."
+            exit 0
+          fi
+          echo "Linting changed Python files:"
+          echo "$FILES"
+          echo "$FILES" | xargs ruff check --select F,E9
+
+      # thaw-lint runs on the WHOLE tree: every rule is a regression guard on
+      # something currently clean (or a non-blocking WARN), so it stays green.
+      - name: thaw-lint (project footguns)
+        run: python tools/thaw_lint.py
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      - uses: Swatinem/rust-cache@v2
+
+      # clippy runs tree-wide with -D warnings: the workspace is clean today,
+      # so this is a regression guard. thaw-py is excluded (it needs the
+      # PyO3/CUDA surface that only builds in the wheel workflow).
+      - name: cargo clippy (deny warnings)
+        run: cargo clippy --workspace --exclude thaw-py --all-targets -- -D warnings
+
   rust:
     name: cargo test (${{ matrix.os }})
     runs-on: ${{ matrix.os }}

CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to thaw
+
+thaw is a small team moving fast. These are the rails that keep PRs flowing
+without regressions or hours lost to footguns we've already paid for once.
+
+## The loop
+
+1. Branch off `main` (`git checkout -b area/short-description`).
+2. Make the change. Keep the diff scoped — one concern per PR.
+3. Run the checks below locally.
+4. Open a PR. CI runs `lint`, `cargo test`, and `pytest`. Fill in the template.
+5. Get a review. Address blocking + high items; land it.
+
+Never push to `main` directly, and never tag a release without a GPU
+validation pass — see [Release](#release).
+
+## Checks before you push
+
+```bash
+# Project footgun linter (whole tree, fast, no deps)
+python tools/thaw_lint.py
+
+# Real-bug lint on the Python you touched
+ruff check --select F,E9 <your changed .py files>
+
+# Rust: format + lint + tests
+cargo fmt --all
+cargo clippy --workspace --exclude thaw-py --all-targets -- -D warnings
+cargo test --workspace --exclude thaw-py
+
+# Python tests (torch/vllm/sglang are mocked — no GPU needed)
+pytest tests/ -q
+```
+
+### What CI gates
+
+| Gate | Scope | Why scoped this way |
+|------|-------|---------------------|
+| `cargo clippy -D warnings` | whole workspace (minus `thaw-py`) | clean today — a regression guard |
+| `python tools/thaw_lint.py` | whole tree | every ERROR rule is currently green |
+| `ruff check --select F,E9` | **changed Python only** | the legacy tree has known debt; see the ratchet below |
+
+**The ruff ratchet.** We do not gate the whole tree on ruff yet — there are
+~36 pre-existing real-bug findings (mostly unused imports) that a one-shot
+cleanup would land right on top of in-flight PRs. So ruff runs only on the
+files your PR changes: new and touched code must be clean, legacy debt does
+not block you. Once the open PRs land, a dedicated `ruff --fix` sweep will
+clear the backlog and the gate widens to the whole tree. If you're already in
+a legacy file, fixing its findings while you're there is welcome.
+
+`cargo fmt --check` is **not** gated yet (a full `cargo fmt` touches ~16 files
+and would conflict with open Rust PRs). Run `cargo fmt --all` before pushing
+anyway; we'll turn the gate on once the tree is normalized.
+
+## thaw-lint — the project-specific rules
+
+`tools/thaw_lint.py` encodes the mistakes that have actually cost us time.
+`ERROR` fails CI; `WARN` just surfaces. Run `python tools/thaw_lint.py --list`
+to see them all. Current ERROR rules:
+
+- **`import thaw_native`** → the `thaw-native` wheel installs the module
+  `thaw`. Write `import thaw`. (This one cost real fresh-pod debugging hours.)
+- **Personal `@icloud.com` email** in tracked files → the public contact is
+  `nils@thaw.sh`.
+- **`matteso1/thaw` URLs** → the repo lives at `thaw-ai/thaw`; the old one is
+  archived and 404s clone scripts.
+- **Leftover `breakpoint()` / `pdb.set_trace()`** in shipped Python.
+- **Retracted speedup multipliers** (`17.2x`, `12.6x`, `9.7x`, `5.9x`) in the
+  README or `site/` — see [receipt hygiene](#receipt--benchmark-hygiene).
+- **Hard-setting `VLLM_ALLOW_INSECURE_SERIALIZATION`** → use
+  `os.environ.setdefault` so a user can override a security-sensitive flag.
+
+Sure a line is a false positive? Add `# thaw-lint: allow` to it. New footgun
+worth guarding? Add a `Rule` to `tools/thaw_lint.py` with a test — keep ERROR
+rules ones the tree is currently clean on, so they're regression guards, not a
+backlog.
+
+## Receipt & benchmark hygiene
+
+Performance is the pitch, so the bar on numbers is high.
+
+- **Only claim re-validated numbers.** Default to the most conservative
+  defensible figure, not the most flattering one.
+- **A perf claim ships with its receipt** — a JSON under `site/receipts/` from
+  the run that produced it, in the same PR. Prose-only numbers rot.
+- **Say what the benchmark actually measured.** If it injects synthetic
+  latency, it measured latency-hiding, not bandwidth — don't let the README
+  round that up to a throughput claim.
+- **Scrub local paths** (`C:\Users\...`, `/home/you/...`) out of committed
+  receipts.
+- Retired numbers live in `docs/ARCHITECTURE.md` so they don't resurface.
+
+## GPU vs. no-GPU
+
+A lot of thaw runs without a GPU — the whole inspect/diff/log/rewind surface,
+the format readers, the Rust core against `MockCuda`. Those are unit-tested in
+CI. The GPU paths (real freeze/restore/fork, TP, KV cache) are validated on a
+pod per release; `tests/gpu/` and `benchmarks/` hold those. Don't put a
+GPU-requiring test in the default `pytest` path — mock the engine
+(`tests/conftest.py` shows how) or gate it under `tests/gpu/`.
+
+## Ownership boundary (format vs. transport)
+
+To keep two people out of each other's way, work splits at the file format
+line:
+
+- **Above the line — format, semantics, the verb surface.** The `.thaw` /
+  `.thawkv` schema, `handle.json`, cross-engine restore, `verify`, lineage,
+  the fork API contract. Changes here define *what the bytes mean*.
+- **Below the line — byte transport & throughput.** Restore DMA, freeze
+  pipelining, multi-NVMe/TP write paths, parallel cloud fetch. Changes here
+  move *the same bytes faster*.
+
+`python/thaw_common/cloud.py` is the one file both sides touch — partition it:
+manifest parse/resolve above the line, the transfer executor below it, with a
+typed boundary between. When a change spans the line (e.g. shard-at-freeze),
+freeze the on-disk schema + golden fixtures **first**, then build transport
+against bytes-on-disk rather than against in-flight code.
+
+## Release
+
+The `thaw-native` version string lives in **two** independent places that must
+match: `Cargo.toml` `[workspace.package]` and **`crates/thaw-py/pyproject.toml`**
+(the authoritative file maturin reads — the other crate `Cargo.toml`s inherit
+via `version.workspace = true`). Desyncing them has failed a release before.
+Bump both, validate on a GPU pod, then tag.

Cargo.toml

@@ -36,7 +36,7 @@ version = "0.3.2"
 edition = "2021"
 rust-version = "1.75"
 license = "Apache-2.0"
-repository = "https://github.com/matteso1/thaw"
+repository = "https://github.com/thaw-ai/thaw"
 authors = ["Nils Matteson <nils@thaw.sh>"]
 
 # Release profile tuning. `opt-level = 3` is the Rust default for release,

demos/bench_cold_cache.sh

@@ -8,7 +8,7 @@
 # Usage (fresh pod, one line):
 #   export GH_PAT=ghp_xxx HF_TOKEN=hf_xxx
 #   curl -sSL -H "Authorization: token $GH_PAT" \
-#     https://raw.githubusercontent.com/matteso1/thaw/main/demos/bench_cold_cache.sh \
+#     https://raw.githubusercontent.com/thaw-ai/thaw/main/demos/bench_cold_cache.sh \
 #     | GH_PAT=$GH_PAT HF_TOKEN=$HF_TOKEN bash
 #
 # Or after the repo is cloned:
@@ -76,11 +76,11 @@ if [ "$SKIP_SETUP" != "1" ]; then
         log "  thaw/ already exists — pulling latest"
         cd thaw && git pull
     else
-        git clone "https://${GH_PAT}@github.com/matteso1/thaw.git"
+        git clone "https://${GH_PAT}@github.com/thaw-ai/thaw.git"
         cd thaw
     fi
     # Scrub PAT from remote so it doesn't linger in git config on the pod
-    git remote set-url origin "https://github.com/matteso1/thaw.git"
+    git remote set-url origin "https://github.com/thaw-ai/thaw.git"
 
     log "=== Installing vLLM + maturin ==="
     pip install -q vllm "maturin[patchelf]" huggingface_hub 2>&1 | tail -3 | tee -a "$MAIN_LOG"

demos/run_quick_test.sh

@@ -10,7 +10,7 @@
 # Usage on a fresh RunPod/Lambda pod:
 #   export HF_TOKEN=hf_xxxxx
 #   export GITHUB_PAT=ghp_xxxxx
-#   curl -sSL https://raw.githubusercontent.com/matteso1/thaw/main/demos/run_quick_test.sh | bash -s -- --setup
+#   curl -sSL https://raw.githubusercontent.com/thaw-ai/thaw/main/demos/run_quick_test.sh | bash -s -- --setup
 
 set -euo pipefail
 
@@ -37,7 +37,7 @@ if $SETUP; then
     # Clone repo
     if [ ! -d /workspace/thaw ]; then
         if [ -n "${GITHUB_PAT:-}" ]; then
-            git clone "https://${GITHUB_PAT}@github.com/matteso1/thaw.git" /workspace/thaw
+            git clone "https://${GITHUB_PAT}@github.com/thaw-ai/thaw.git" /workspace/thaw
         else
             git clone https://github.com/thaw-ai/thaw.git /workspace/thaw
         fi

demos/run_stress_test.sh

@@ -61,7 +61,7 @@ if [ -d thaw ]; then
     cd thaw && git pull
 else
     if [ -n "${GITHUB_PAT:-}" ]; then
-        git clone "https://${GITHUB_PAT}@github.com/matteso1/thaw.git"
+        git clone "https://${GITHUB_PAT}@github.com/thaw-ai/thaw.git"
     else
         git clone https://github.com/thaw-ai/thaw.git
     fi

demos/setup_runpod.sh

@@ -20,7 +20,7 @@ pip install vllm
 
 echo "[2/5] Cloning thaw..."
 cd /root
-[ -d thaw ] && cd thaw && git pull || (git clone https://github.com/matteso1/thaw.git && cd thaw)
+[ -d thaw ] && cd thaw && git pull || (git clone https://github.com/thaw-ai/thaw.git && cd thaw)
 cd /root/thaw
 pip install -e .
 

docs/BENCHMARKS.md

@@ -231,7 +231,7 @@ For why whole-flow speedup numbers depend heavily on whether HF download is in t
 
 ```bash
 # On any CUDA 12+ machine with enough VRAM for the model:
-git clone https://github.com/matteso1/thaw.git && cd thaw
+git clone https://github.com/thaw-ai/thaw.git && cd thaw
 pip install "maturin[patchelf]" vllm
 cd crates/thaw-py && maturin develop --release --features cuda && cd ../..
 

docs/SETUP.md

@@ -91,7 +91,7 @@ Colab doesn't persist state across sessions, so you re-run setup each time. Budg
 
 ```python
 # Cell 1: clone the repo
-!git clone https://github.com/matteso1/thaw.git
+!git clone https://github.com/thaw-ai/thaw.git
 %cd thaw
 
 # Cell 2: install Rust (cached across sessions if you use a persistent disk,

notebooks/gpu_benchmark.ipynb

@@ -31,7 +31,7 @@
     "# [3] Clone repo\n",
     "from google.colab import userdata\n",
     "pat = userdata.get('GITHUB_PAT')\n",
-    "!git clone https://{pat}@github.com/matteso1/thaw.git /content/thaw 2>/dev/null || (cd /content/thaw && git pull)\n",
+    "!git clone https://{pat}@github.com/thaw-ai/thaw.git /content/thaw 2>/dev/null || (cd /content/thaw && git pull)\n",
     "!cd /content/thaw && git log --oneline -3"
    ]
   },

notebooks/quickstart.ipynb

@@ -22,7 +22,7 @@
    "outputs": [],
    "source": [
     "# Install thaw-vllm + fix Colab compatibility\n",
-    "!pip install git+https://github.com/matteso1/thaw.git -q\n",
+    "!pip install git+https://github.com/thaw-ai/thaw.git -q\n",
     "!pip install vllm fastapi uvicorn -q\n",
     "!pip install \"sympy==1.13.3\" -q"
    ]

scripts/pod-bench-freeze.sh

@@ -12,7 +12,7 @@
 # pattern, and measures wall-clock time for each path.
 #
 # Required env:
-#   GH_PAT      GitHub PAT with repo access to matteso1/thaw
+#   GH_PAT      GitHub PAT with repo access to thaw-ai/thaw
 #
 # Optional env:
 #   SIZE_MB     default 16384  (16 GiB — approx Llama-3-8B weights)
@@ -22,7 +22,7 @@
 #
 # Usage on vllm/vllm-openai:latest pod:
 #   export GH_PAT=...
-#   git clone https://$GH_PAT@github.com/matteso1/thaw.git /workspace/thaw
+#   git clone https://$GH_PAT@github.com/thaw-ai/thaw.git /workspace/thaw
 #   bash /workspace/thaw/scripts/pod-bench-freeze.sh
 #
 # If the checkout already exists, the script will `git fetch + reset --hard`
@@ -63,7 +63,7 @@ fi
 banner "[1/3] Clone + update thaw"
 mkdir -p "$(dirname "$THAW_DIR")"
 if [ ! -d "$THAW_DIR/.git" ]; then
-  git clone "https://$GH_PAT@github.com/matteso1/thaw.git" "$THAW_DIR"
+  git clone "https://$GH_PAT@github.com/thaw-ai/thaw.git" "$THAW_DIR"
 else
   cd "$THAW_DIR"
   git fetch --quiet origin main

scripts/pod-validate-kv.sh

@@ -17,7 +17,7 @@
 # overlay the git checkout for the Python code.
 #
 # Required env:
-#   GH_PAT               GitHub PAT with repo scope (matteso1/thaw)
+#   GH_PAT               GitHub PAT with repo scope (thaw-ai/thaw)
 #
 # Optional env:
 #   HF_TOKEN             HF token for gated Llama weights
@@ -29,7 +29,7 @@
 # Usage (pod: vllm/vllm-openai:latest):
 #   export GH_PAT=...
 #   export HF_TOKEN=...                # for gated Llama
-#   git clone https://$GH_PAT@github.com/matteso1/thaw.git /workspace/thaw
+#   git clone https://$GH_PAT@github.com/thaw-ai/thaw.git /workspace/thaw
 #   bash /workspace/thaw/scripts/pod-validate-kv.sh
 #
 # Re-run to pull latest code: same command. Script fetch+resets origin/main.
@@ -93,7 +93,7 @@ fi
 banner "[2/4] Clone + install thaw (Python, --no-deps)"
 mkdir -p "$(dirname "$THAW_DIR")"
 if [ ! -d "$THAW_DIR/.git" ]; then
-  git clone "https://$GH_PAT@github.com/matteso1/thaw.git" "$THAW_DIR"
+  git clone "https://$GH_PAT@github.com/thaw-ai/thaw.git" "$THAW_DIR"
 else
   cd "$THAW_DIR"
   git fetch --quiet origin main

scripts/pod-validate-s3.sh

@@ -20,7 +20,7 @@
 # Usage (pod template: vllm-latest → vllm/vllm-openai:latest):
 #   export GH_PAT=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
 #   export AWS_DEFAULT_REGION=us-east-2 THAW_BUCKET=thaw-test-nils-2026
-#   git clone https://$GH_PAT@github.com/matteso1/thaw.git /workspace/thaw
+#   git clone https://$GH_PAT@github.com/thaw-ai/thaw.git /workspace/thaw
 #   bash /workspace/thaw/scripts/pod-validate-s3.sh
 #
 # The script fetches + hard-resets origin/main itself, so to re-run with
@@ -69,7 +69,7 @@ fi
 banner "[2/3] Clone + install thaw (Python, --no-deps)"
 mkdir -p "$(dirname "$THAW_DIR")"
 if [ ! -d "$THAW_DIR/.git" ]; then
-  git clone "https://$GH_PAT@github.com/matteso1/thaw.git" "$THAW_DIR"
+  git clone "https://$GH_PAT@github.com/thaw-ai/thaw.git" "$THAW_DIR"
 else
   cd "$THAW_DIR"
   git fetch --quiet origin main